┌─────────────────────────────────────────────────────────┐
│  Agent Definitions (compile-time)                       │
│  Static declarations: tools, budgets, permissions       │
├─────────────────────────────────────────────────────────┤
│  Agent Execution Service (runtime)                      │
│  Step loop, tool dispatch, credit tracking              │
├─────────────────────────────────────────────────────────┤
│  Agent Tool Registry                                    │
│  Tool lookup, permission enforcement, I/O schemas       │
├─────────────────────────────────────────────────────────┤
│  Agent Quota Service                                    │
│  Credit reservation, balance checks, usage tracking     │
└─────────────────────────────────────────────────────────┘

interface AgentDefinition {
  id: string;                         // Unique identifier (e.g. 'compliance_checker')
  name: string;                       // Human-readable name
  description: string;                // Purpose description
  requiredFeature: Feature;           // Tier entitlement gate
  requiredPermissions: Permission[];  // RBAC permissions the user must hold
  allowedTools: string[];             // Tool allowlist (sandbox boundary)
  maxSteps: number;                   // Step budget per run
  defaultCreditBudget: number;        // Credit cost ceiling
  icon: string;                       // Lucide icon name
  category: string;                   // Domain grouping
}

// Core tools registered at startup
agentToolRegistry.register(createAgentTool({
  name: 'analyze_compliance',
  description: 'Analyze entries for compliance issues',
  inputSchema: z.object({ entryIds: z.array(z.string()) }),
  handler: async (input, context) => { /* ... */ },
  requiredPermissions: [Permission.VIEW_JOURNALS],
  creditCost: 2,
}));

User triggers agent run
    │
    ├── Check credit balance ≥ defaultCreditBudget
    │       └── Insufficient → reject with INSUFFICIENT_CREDITS
    │
    ├── Reserve credits (hold)
    │
    ├── Execute steps (each tool call deducts from reservation)
    │
    └── Settle reservation
            ├── Success → deduct actual usage, refund remainder
            └── Failure → full refund of reserved credits

interface AgentRun {
  id: string;
  organizationId: string;
  agentType: string;
  agentDefinitionId: string;
  status: AgentRunStatus;
  triggeredBy: string;              // User ID for audit trail
  triggeredByName: string;
  permissions: Permission[];        // Captured RBAC at run start
  input: Record<string, unknown>;
  output?: Record<string, unknown>;
  steps: AgentStep[];               // Embedded array of execution steps
  creditReservationId: string;
  creditsReserved: number;
  creditsConsumed: number;
  totalInputTokens: number;         // Token tracking for analytics
  totalOutputTokens: number;
  startedAt: string;
  completedAt?: string;
  durationMs?: number;
  error?: AgentRunError;
  escalation?: AgentEscalation;     // Human-in-the-loop state
}

interface AgentStep {
  id: string;
  runId: string;
  stepIndex: number;
  toolName: string;
  status: 'pending' | 'running' | 'completed' | 'failed';
  input: Record<string, unknown>;
  output?: Record<string, unknown>;
  creditsUsed: number;
  inputTokens: number;
  outputTokens: number;
  durationMs: number;
  startedAt: string;
  completedAt?: string;
  error?: string;
}