Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Agent Execution Architecture

​

Overview

User triggers agent run
        │
        ▼
┌──────────────────────┐
│ AgentExecutionService │  Orchestrates the entire lifecycle
│  ├─ startRun()       │  Validates → reserves credits → creates run doc
│  ├─ executeStep()    │  Invokes tools → consumes credits
│  ├─ pauseRun()       │  Creates escalation (human-in-the-loop)
│  ├─ resumeRun()      │  Resolves escalation → continues
│  ├─ completeRun()    │  Releases unused credits
│  └─ failRun()        │  Releases all reserved credits
└──────────────────────┘
        │
        ├──▶ AgentToolRegistry      (tool lookup & permission check)
        ├──▶ CreditService          (reserve / consume / release)
        ├──▶ AgentQuotaService       (tier-based limits)
        └──▶ EventBus               (lifecycle events)

​

Key Components

​

AgentExecutionService

​

AgentToolRegistry

// Register a tool
agentToolRegistry.register(createAgentTool({
  name: 'generate_journal',
  description: '...',
  requiredPermissions: [Permission.USE_AI_WIZARD, Permission.EDIT_OWN_ENTRIES],
  execute: async (input, context) => { /* calls geminiService */ },
}));

// Lookup at execution time
const tool = agentToolRegistry.getTool('generate_journal');
const result = await tool.execute(input, context);

​

AgentQuotaService

• Monthly run limit: maxAgentRunsPerMonth from TierLimits
• Concurrent agent limit: maxConcurrentAgents — counts runs with status running or awaiting_human
• Hourly rate limit: agentRunsPerHour
• Per-run step budget: maxAgentStepsPerRun
• Per-run token budget: maxAgentTokenBudgetPerRun

​

Agent Definitions

​

Run Lifecycle Flow

                  startRun()
                      │
        ┌─────────────▼─────────────┐
        │         queued            │
        └─────────────┬─────────────┘
                      │ (validation passes)
        ┌─────────────▼─────────────┐
   ┌───▶│         running           │◀──────────┐
   │    └──┬──────────┬──────────┬──┘            │
   │       │          │          │               │
   │  executeStep() pauseRun() failRun()    resumeRun()
   │       │          │          │               │
   │       ▼          ▼          ▼               │
   │   (next step) awaiting   failed             │
   │       │       _human        │               │
   │       │          │          │               │
   └───────┘          └──────────────────────────┘
        │
   completeRun()
        │
        ▼
    completed

​

Credit Integration

1. Reserve: creditService.reserveCredits(orgId, budget, runId) — atomically checks available balance and creates a reservation
2. Consume: After each executeStep(), creditService.consumeCredits(orgId, reservationId, actualCredits) deducts from the reservation
3. Release: On completeRun(), cancelRun(), or failRun(), creditService.releaseCredits() returns uncommitted credits to the pool

​

Event Emissions

​

Security Model

• Agents inherit the triggering user’s RBAC permissions — captured at run start in AgentRun.permissions
• Each tool checks permissions before execution via createAgentTool() wrapper
• The AgentDefinition.requiredPermissions array is validated at startRun() time
• Feature entitlement gates (AGENT_BASIC, AGENT_MULTI_STEP, AGENT_AUTONOMOUS) are checked via the entitlement system

​

Firestore Data Model

organizations/{orgId}/
  agent_runs/{runId}         ← AgentRun document
    steps: AgentStep[]       ← Embedded array (not subcollection)
    escalation?: AgentEscalation  ← Embedded object
  creditReservations/{id}    ← Managed by CreditService

​

Adding a New Agent

1. Define the agent in agentDefinitions.ts:
   const MY_AGENT: AgentDefinition = {
     id: 'my_agent',
     name: 'My Agent',
     description: '...',
     requiredFeature: Feature.AGENT_MULTI_STEP,
     requiredPermissions: [Permission.VIEW_PROJECTS],
     allowedTools: ['query_documents', 'generate_report'],
     maxSteps: 10,
     defaultCreditBudget: 25,
     icon: 'Sparkles',
     category: 'general',
   };
   
2. Add to AGENT_DEFINITIONS array
3. Register any new tools in AgentToolRegistry.registerBuiltInTools()

​

Adding a New Tool

1. Add to registerBuiltInTools() in AgentToolRegistry.ts:
   registry.register(createAgentTool({
     name: 'my_tool',
     description: '...',
     requiredPermissions: [Permission.SOME_PERM],
     execute: async (input, context) => {
       const { myService } = await import('@/features/my/services/myService');
       const result = await myService.doSomething(input.data as string);
       return { success: true, output: { result }, creditsUsed: 5 };
     },
   }));
   
2. Add the tool name to the allowedTools array of relevant agent definitions

​

Maintenance

• Adding new agent definitions or tools
• Changing the credit reservation/consumption flow
• Modifying the run state machine
• Adding new event emissions