AgentDefinition (static config)
  ├─ id, name, description
  ├─ requiredFeature: Feature
  ├─ requiredPermissions: Permission[]
  ├─ allowedTools: string[]
  ├─ maxSteps, defaultCreditBudget
  └─ category: AgentCategory

AgentRun (runtime instance)
  ├─ id, organizationId
  ├─ agentType, agentDefinitionId
  ├─ status: AgentRunStatus
  ├─ triggeredBy, triggeredByName
  ├─ permissions: Permission[] (snapshot)
  ├─ input / output
  ├─ steps: AgentStep[] (embedded)
  ├─ creditReservationId, creditsReserved, creditsConsumed
  ├─ totalInputTokens, totalOutputTokens
  ├─ startedAt, completedAt, durationMs
  ├─ error?: AgentRunError
  ├─ escalation?: AgentEscalation
  └─ createdAt, updatedAt

AgentStep (embedded in AgentRun)
  ├─ id, runId, stepIndex
  ├─ toolName
  ├─ status: AgentStepStatus
  ├─ input / output
  ├─ creditsUsed, inputTokens, outputTokens, durationMs
  ├─ startedAt, completedAt
  └─ error?: string

AgentEscalation (embedded in AgentRun)
  ├─ runId, stepId
  ├─ reason
  ├─ options: EscalationOption[]
  ├─ requiredPermission?: Permission
  ├─ resolvedBy, resolvedByName, resolution, resolvedAt
  └─ escalatedAt

type AgentRunStatus =
  | 'queued'          // Run created, waiting to start
  | 'running'         // Actively executing steps
  | 'paused'          // Temporarily paused (manual)
  | 'awaiting_human'  // Paused for human-in-the-loop decision
  | 'completed'       // All steps finished successfully
  | 'failed'          // Step failed with unrecoverable error
  | 'cancelled';      // Manually cancelled by user

type AgentStepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';

type AgentCategory = 'compliance' | 'reporting' | 'grants' | 'finance' | 'journals' | 'general';

interface AgentTool {
  name: string;
  description: string;
  requiredPermissions: Permission[];
  execute(input: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult>;
}

interface AgentToolResult {
  success: boolean;
  output: Record<string, unknown>;
  tokensUsed?: { input: number; output: number };
  creditsUsed: number;
  error?: string;
}

interface AgentToolContext {
  organizationId: string;
  userId: string;              // Triggering user
  userPermissions: Permission[]; // Snapshot of user's RBAC at run start
  agentRunId: string;
  stepId: string;
}

interface AgentEscalation {
  runId: string;
  stepId: string;
  reason: string;               // Why the agent is asking
  options: EscalationOption[];  // Choices presented to the user
  requiredPermission?: Permission; // Who can respond
  resolvedBy?: string;
  resolvedByName?: string;
  resolution?: string;          // The chosen option
  resolvedAt?: string;
  escalatedAt: string;
}

interface EscalationOption {
  id: string;
  label: string;
  description?: string;
  action: 'approve' | 'reject' | 'modify' | 'skip';
}

interface AgentRunError {
  message: string;
  code?: string;
  stepIndex?: number;  // Which step failed
  stepId?: string;
  stack?: string;
}

interface AgentRunFilters {
  organizationId: string;
  agentType?: string;
  status?: AgentRunStatus[];
  triggeredBy?: string;
  dateRange?: { start: string; end: string };
}