Agent Execution

agent.agent_executions (NEW)
├─ id (uuid, PK)
├─ org_id, workspace_id (org-scoped, RLS)
├─ agent_id, agent_version_id (FK)
├─ origin_type (enum: chat|event_trigger|scheduled_job|mcp_request|workflow_run)
├─ origin_id (uuid, polymorphic FK)
├─ status (planning|running|completed|failed|cancelled)
├─ input_payload, output_payload (jsonb)
├─ failure_reason (nullable)
├─ started_at, completed_at (timestamps)
├─ latency_ms (bigint)
├─ input_tokens, output_tokens (int, nullable)
├─ estimated_cost_usd (numeric(10,6), nullable)
├─ synced_to_graph_at (timestamp, nullable) ← sync flag
├─ created_at, updated_at, created_by_user_id (auditMixin)

agent.agent_execution_steps (NEW)
├─ id, execution_id (FK)
├─ step_number (int)
├─ step_type (tool_call|decision|retry|wait)
├─ status, input_payload, output_payload
├─ latency_ms, input_tokens, output_tokens
├─ failure_reason (nullable)

agent.agent_tool_calls (NEW)
├─ id, execution_step_id (FK)
├─ tool_name, tool_type (mcp|capability|builtin)
├─ request_payload, response_payload (jsonb)
├─ status, latency_ms, input_tokens, output_tokens
├─ created_at

-- "What was the cost of this execution?"
SELECT estimated_cost_usd, input_tokens, output_tokens 
FROM agent_executions 
WHERE id = $1 AND org_id = $2;

-- "Aggregate cost by origin type this week"
SELECT origin_type, SUM(estimated_cost_usd), COUNT(*)
FROM agent_executions
WHERE org_id = $1 AND created_at > now() - interval '7 days'
GROUP BY origin_type;

-- "Find all failed executions"
SELECT * FROM agent_executions
WHERE org_id = $1 AND status = 'failed'
ORDER BY created_at DESC LIMIT 100;

// Primary execution node (mirrored from Postgres)
(:Execution {
  id: "aex-123",
  status: "completed",
  cost: 0.0052,
  inputTokens: 1240,
  outputTokens: 340,
  startedAt: ISO8601,
  completedAt: ISO8601,
  latencyMs: 12000
})

// Outbound edges from execution
[:INVOKED_AGENT] → (:Agent {id, name, slug})
[:ORIGINATED_FROM] → (:Message {id}) // if origin=chat
[:ORIGINATED_FROM] → (:EventTrigger {id}) // if origin=event_trigger
[:ORIGINATED_FROM] → (:ScheduleRun {id}) // if origin=scheduled_job
[:ORIGINATED_FROM] → (:MCPRequest {id}) // if origin=mcp_request
[:ORIGINATED_FROM] → (:WorkflowRun {id}) // if origin=workflow_run

// Ontology linkage (inferred or declared)
[:TOUCHED_ENTITY] → (:Entity {type: "Customer|Project|Feature|..."})

// Step-level structure
[:STEP] → (:ExecutionStep {number, status, latency})
  ├─ [:CALLED_TOOL] → (:Tool {name, type})
  └─ [:INVOKED_AGENT] → (:Agent) // sub-agent spawns

// Sub-execution lineage
[:SPAWNED_EXECUTION] → (:Execution) // parent → child

// Conversation lineage
[:IN_CONVERSATION] → (:Conversation {id})

// "Which ontology entities were involved in this execution?"
MATCH (exec:Execution {id: "aex-123"})
       -[:TOUCHED_ENTITY]-> (entity)
RETURN entity.type, entity.id, entity.name;

// "Show execution lineage: what spawned this?"
MATCH path = (exec:Execution {id: "aex-123"})
       <-[:SPAWNED_EXECUTION*]-(root)
RETURN path;

// "All executions touching Customer X"
MATCH (cust:Customer {id: "cust-001"})
       <-[:TOUCHED_ENTITY]-(exec:Execution)
RETURN exec ORDER BY exec.startedAt DESC;

// "Dependency chain: message → execution → sub-agents → entities"
MATCH (msg:Message {id: "msg-abc"})
       <-[:ORIGINATED_FROM]-(exec:Execution)
       -[:SPAWNED_EXECUTION*]-> (child:Execution)
       -[:TOUCHED_ENTITY]-> (entity)
RETURN msg, exec, child, entity;

execution_id (String)
org_id, workspace_id (UUID)
agent_id (UUID)
origin_type (enum)
origin_id (UUID)
status (enum)
started_at, completed_at (DateTime)
latency_ms (UInt32)
input_tokens, output_tokens (UInt32)
cost_usd (Decimal(10, 6))
step_count (UInt16)
tool_call_count (UInt16)
error_present (UInt8) // boolean
created_at (DateTime) → partitioned, TTL 2 years

PRIMARY KEY (org_id, created_at, execution_id)
ORDER BY (org_id, created_at)
PARTITION BY toYYYYMM(created_at)

-- "Token usage trend by origin (30 days)"
SELECT 
  date_trunc('day', created_at) as day,
  origin_type,
  SUM(output_tokens) as tokens,
  AVG(cost_usd) as avg_cost
FROM execution_events
WHERE org_id = 'org-123' AND created_at > now() - interval '30 days'
GROUP BY day, origin_type
ORDER BY day DESC;

-- "Execution count + error rate by agent"
SELECT 
  agent_id,
  COUNT(*) as executions,
  SUM(error_present) / COUNT(*) * 100 as error_rate_pct
FROM execution_events
WHERE org_id = 'org-123' AND created_at > now() - interval '7 days'
GROUP BY agent_id;

┌──────────────────────────────────────────────────────────────┐
│ Dispatch Origin (Chat UI, Event Trigger, Schedule, MCP)      │
└────────────────────┬─────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ invoke() [AI SDK Boundary]                                    │
│ - Stream response to client (SSE for chat)                    │
│ - Collect: tokens, latency, tool calls, outputs              │
│ - Infer: touched entities (from context, tools, outputs)     │
└────────────────────┬─────────────────────────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────────────────────────┐
│ Execution Complete (in-memory telemetry sealed)              │
│ - Calculate cost (via AI SDK model pricing)                  │
│ - Capture failure reason (if applicable)                     │
└────────────────────┬─────────────────────────────────────────┘
                     │
         ┌───────────┼───────────┬───────────┐
         │           │           │           │
         ▼           ▼           ▼           ▼
    ┌────────┐  ┌────────┐  ┌────────┐  ┌──────────┐
    │Postgres│  │ Neo4j  │  │ClickHouse │  │  Cache  │
    │(SYNC)  │  │(ASYNC) │  │ (ASYNC)   │  │(Memcache)
    └────────┘  └────────┘  └────────┘  └──────────┘
    
    WRITE:       ASYNC EMIT:  ASYNC EMIT:    SET TTL:
    - Record     - Exec node  - Event row    - Session
    - ACID lock  - Edges to   - Partitioned  - Lock
    - Metering     entities   - TTL=2yr      - Context
    boundary
    
    ┌─ Sync flag: synced_to_graph_at
    │  (retry if Neo4j failed)
    │
    └─ Retry logic:
       Cron job: "SELECT * FROM agent_executions 
                  WHERE synced_to_graph_at IS NULL 
                  AND created_at > now() - interval '24h'"

agent.workflow_runs (container)
├─ id: "wfr-123"
├─ title: "Research competitor features"
├─ plan_json: [task1, task2, task3]
├─ status: "running"
├─ totalTasks: 3
├─ completedTasks: 1
└─ created_at, updated_at

    ↓ (linked via origin_id)

agent.agent_executions (individual invocations)
├─ id: "aex-a"
├─ origin_type: "workflow_run"
├─ origin_id: "wfr-123" ← links back
├─ status: "completed"
├─ estimated_cost_usd: 0.0042
├─ output_tokens: 240

├─ id: "aex-b"
├─ origin_type: "workflow_run"
├─ origin_id: "wfr-123"
├─ status: "running"
└─ ...

├─ id: "aex-c"
├─ origin_type: "workflow_run"
├─ origin_id: "wfr-123"
├─ status: "pending"
└─ ...

-- "Show all executions from this workflow run"
SELECT * FROM agent_executions
WHERE origin_type = 'workflow_run' AND origin_id = 'wfr-123'
ORDER BY created_at;

-- "Total cost of a workflow run"
SELECT SUM(estimated_cost_usd) FROM agent_executions
WHERE origin_type = 'workflow_run' AND origin_id = 'wfr-123';

-- "Which workflow runs are still pending?"
SELECT wr.*, COUNT(ae.id) as pending_executions
FROM agent.workflow_runs wr
LEFT JOIN agent.agent_executions ae 
  ON wr.id = ae.origin_id 
  AND ae.origin_type = 'workflow_run'
  AND ae.status = 'pending'
WHERE wr.status IN ('planning', 'running')
GROUP BY wr.id
HAVING pending_executions > 0;

-- Drop schemas in dependency order
DROP SCHEMA IF EXISTS execution CASCADE;
-- execution.executions, execution.execution_steps, execution.tool_calls gone

-- Drop orphaned tables (not schema-scoped)
DROP TABLE IF EXISTS workflow.playbooks CASCADE;
DROP TABLE IF EXISTS workflow.playbook_versions CASCADE;
DROP TABLE IF EXISTS workflow.playbook_steps CASCADE;

DROP TABLE IF EXISTS event.triggers CASCADE;
DROP TABLE IF EXISTS integration.connections CASCADE;
DROP TABLE IF EXISTS content.documents CASCADE;
DROP TABLE IF EXISTS agent.tools CASCADE;

-- Clean up Drizzle relations
-- (relations.ts will have these entries removed)

-- Add to chat.messages (optional, for convenience)
ALTER TABLE chat.messages 
ADD COLUMN agent_execution_id uuid REFERENCES agent.agent_executions(id);

-- Index for fast lookup
CREATE INDEX messages_execution_idx ON chat.messages(agent_execution_id);

-- Create agent schema (if not exists)
CREATE SCHEMA IF NOT EXISTS agent;

-- agent_executions table
CREATE TABLE agent.agent_executions (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id uuid NOT NULL,
  workspace_id uuid NOT NULL,
  agent_id uuid NOT NULL,
  agent_version_id uuid NOT NULL,
  
  -- Polymorphic origin: exactly one non-null (CHECK enforced)
  origin_type text NOT NULL CHECK (origin_type IN ('chat', 'event_trigger', 'scheduled_job', 'mcp_request', 'workflow_run')),
  origin_id uuid NOT NULL,
  
  -- Execution state
  status citext NOT NULL DEFAULT 'planning' CHECK (status IN ('planning', 'running', 'completed', 'failed', 'cancelled')),
  input_payload jsonb NOT NULL,
  output_payload jsonb,
  failure_reason text,
  
  -- Telemetry (canonical for metering)
  started_at timestamp with time zone,
  completed_at timestamp with time zone,
  latency_ms bigint,
  input_tokens integer,
  output_tokens integer,
  estimated_cost_usd numeric(10, 6),
  
  -- Sync flag (for Neo4j mirror)
  synced_to_graph_at timestamp with time zone,
  
  -- Audit
  created_at timestamp with time zone NOT NULL DEFAULT now(),
  updated_at timestamp with time zone NOT NULL DEFAULT now(),
  created_by_user_id uuid,
  updated_by_user_id uuid,
  
  FOREIGN KEY (org_id) REFERENCES org.organizations(id) ON DELETE CASCADE,
  FOREIGN KEY (workspace_id) REFERENCES workspace.workspaces(id) ON DELETE CASCADE,
  FOREIGN KEY (agent_id) REFERENCES agent.agents(id),
  FOREIGN KEY (agent_version_id) REFERENCES agent.agent_versions(id)
);

-- Indexes
CREATE INDEX agent_executions_org_idx ON agent.agent_executions(org_id, workspace_id);
CREATE INDEX agent_executions_origin_idx ON agent.agent_executions(origin_type, origin_id);
CREATE INDEX agent_executions_status_idx ON agent.agent_executions(status);
CREATE INDEX agent_executions_agent_idx ON agent.agent_executions(agent_id);
CREATE INDEX agent_executions_created_at_idx ON agent.agent_executions(created_at DESC);

-- RLS
ALTER TABLE agent.agent_executions ENABLE ROW LEVEL SECURITY;
CREATE POLICY agent_executions_tenant_policy 
  ON agent.agent_executions 
  USING (EXISTS (
    SELECT 1 FROM iam.org_members om 
    WHERE om.org_id = agent_executions.org_id 
    AND om.user_id = current_user_id()
  ));

-- agent_execution_steps table
CREATE TABLE agent.agent_execution_steps (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  execution_id uuid NOT NULL REFERENCES agent.agent_executions(id) ON DELETE CASCADE,
  org_id uuid NOT NULL,
  workspace_id uuid NOT NULL,
  
  step_number integer NOT NULL,
  step_type text NOT NULL CHECK (step_type IN ('tool_call', 'decision', 'retry', 'wait')),
  status citext NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed', 'cancelled')),
  
  input_payload jsonb NOT NULL,
  output_payload jsonb,
  failure_reason text,
  
  latency_ms bigint,
  input_tokens integer,
  output_tokens integer,
  
  created_at timestamp with time zone NOT NULL DEFAULT now(),
  updated_at timestamp with time zone NOT NULL DEFAULT now(),
  created_by_user_id uuid,
  updated_by_user_id uuid,
  
  FOREIGN KEY (org_id) REFERENCES org.organizations(id) ON DELETE CASCADE,
  FOREIGN KEY (workspace_id) REFERENCES workspace.workspaces(id) ON DELETE CASCADE,
  UNIQUE (execution_id, step_number)
);

CREATE INDEX agent_execution_steps_execution_idx ON agent.agent_execution_steps(execution_id);
CREATE INDEX agent_execution_steps_org_idx ON agent.agent_execution_steps(org_id, workspace_id);

ALTER TABLE agent.agent_execution_steps ENABLE ROW LEVEL SECURITY;
CREATE POLICY agent_execution_steps_tenant_policy 
  ON agent.agent_execution_steps 
  USING (EXISTS (
    SELECT 1 FROM iam.org_members om 
    WHERE om.org_id = agent_execution_steps.org_id 
    AND om.user_id = current_user_id()
  ));

-- agent_tool_calls table
CREATE TABLE agent.agent_tool_calls (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  execution_step_id uuid NOT NULL REFERENCES agent.agent_execution_steps(id) ON DELETE CASCADE,
  org_id uuid NOT NULL,
  workspace_id uuid NOT NULL,
  
  tool_name text NOT NULL,
  tool_type text NOT NULL CHECK (tool_type IN ('mcp', 'capability', 'builtin')),
  
  request_payload jsonb NOT NULL,
  response_payload jsonb,
  status text NOT NULL CHECK (status IN ('pending', 'running', 'completed', 'failed')),
  
  latency_ms bigint,
  input_tokens integer,
  output_tokens integer,
  
  created_at timestamp with time zone NOT NULL DEFAULT now(),
  
  FOREIGN KEY (org_id) REFERENCES org.organizations(id) ON DELETE CASCADE,
  FOREIGN KEY (workspace_id) REFERENCES workspace.workspaces(id) ON DELETE CASCADE
);

CREATE INDEX agent_tool_calls_step_idx ON agent.agent_tool_calls(execution_step_id);
CREATE INDEX agent_tool_calls_tool_idx ON agent.agent_tool_calls(tool_name);
CREATE INDEX agent_tool_calls_org_idx ON agent.agent_tool_calls(org_id, workspace_id);

ALTER TABLE agent.agent_tool_calls ENABLE ROW LEVEL SECURITY;
CREATE POLICY agent_tool_calls_tenant_policy 
  ON agent.agent_tool_calls 
  USING (EXISTS (
    SELECT 1 FROM iam.org_members om 
    WHERE om.org_id = agent_tool_calls.org_id 
    AND om.user_id = current_user_id()
  ));

-- Drop execution schema entirely
DROP SCHEMA IF EXISTS execution CASCADE;

-- Drop orphaned tables
DROP TABLE IF EXISTS workflow.playbooks CASCADE;
DROP TABLE IF EXISTS workflow.playbook_versions CASCADE;
DROP TABLE IF EXISTS workflow.playbook_steps CASCADE;

DROP TABLE IF EXISTS event.triggers CASCADE;
DROP TABLE IF EXISTS integration.connections CASCADE;
DROP TABLE IF EXISTS content.documents CASCADE;
DROP TABLE IF EXISTS agent.tools CASCADE;

-- (Dangling indexes will be auto-dropped by CASCADE)

// packages/database/src/schema/agent-executions.ts
import { bigint, index, integer, jsonb, text, timestamp, uuid } from "drizzle-orm/pg-core";
import { sql } from "drizzle-orm";
import { agentSchema } from "./_schemas";
import { auditMixin, citext, idMixin, orgScopeMixin } from "./_mixins";

export const agentExecutions = agentSchema.table("agent_executions", {
  ...idMixin("aex"),
  ...auditMixin(),
  ...orgScopeMixin(),
  agentId: uuid("agent_id").notNull(),
  agentVersionId: uuid("agent_version_id").notNull(),
  originType: citext("origin_type").notNull(),
  originId: uuid("origin_id").notNull(),
  status: citext("status").notNull().default("planning"),
  inputPayload: jsonb("input_payload").notNull(),
  outputPayload: jsonb("output_payload"),
  failureReason: text("failure_reason"),
  startedAt: timestamp("started_at", { withTimezone: true, mode: "date" }),
  completedAt: timestamp("completed_at", { withTimezone: true, mode: "date" }),
  latencyMs: bigint("latency_ms", { mode: "bigint" }),
  inputTokens: integer("input_tokens"),
  outputTokens: integer("output_tokens"),
  estimatedCostUsd: text("estimated_cost_usd"), // numeric serialized as string for JSON compat
  syncedToGraphAt: timestamp("synced_to_graph_at", { withTimezone: true, mode: "date" }),
}, (t) => ({
  orgIdx: index("agent_executions_org_idx").on(t.orgId, t.workspaceId),
  originIdx: index("agent_executions_origin_idx").on(t.originType, t.originId),
  statusIdx: index("agent_executions_status_idx").on(t.status),
  agentIdx: index("agent_executions_agent_idx").on(t.agentId),
  createdAtIdx: index("agent_executions_created_at_idx").on(t.createdAt),
}));

export const agentExecutionSteps = agentSchema.table("agent_execution_steps", {
  ...idMixin("aes"),
  ...auditMixin(),
  ...orgScopeMixin(),
  executionId: uuid("execution_id").notNull(),
  stepNumber: integer("step_number").notNull(),
  stepType: citext("step_type").notNull(),
  status: citext("status").notNull(),
  inputPayload: jsonb("input_payload").notNull(),
  outputPayload: jsonb("output_payload"),
  failureReason: text("failure_reason"),
  latencyMs: bigint("latency_ms", { mode: "bigint" }),
  inputTokens: integer("input_tokens"),
  outputTokens: integer("output_tokens"),
}, (t) => ({
  executionIdx: index("agent_execution_steps_execution_idx").on(t.executionId),
  orgIdx: index("agent_execution_steps_org_idx").on(t.orgId, t.workspaceId),
  uniqueStepIdx: sql`UNIQUE (${t.executionId}, ${t.stepNumber})`,
}));

export const agentToolCalls = agentSchema.table("agent_tool_calls", {
  ...idMixin("atc"),
  ...orgScopeMixin(),
  executionStepId: uuid("execution_step_id").notNull(),
  toolName: text("tool_name").notNull(),
  toolType: citext("tool_type").notNull(),
  requestPayload: jsonb("request_payload").notNull(),
  responsePayload: jsonb("response_payload"),
  status: text("status").notNull(),
  latencyMs: bigint("latency_ms", { mode: "bigint" }),
  inputTokens: integer("input_tokens"),
  outputTokens: integer("output_tokens"),
  createdAt: timestamp("created_at", { withTimezone: true, mode: "date" })
    .notNull()
    .default(sql`now()`),
}, (t) => ({
  stepIdx: index("agent_tool_calls_step_idx").on(t.executionStepId),
  toolIdx: index("agent_tool_calls_tool_idx").on(t.toolName),
  orgIdx: index("agent_tool_calls_org_idx").on(t.orgId, t.workspaceId),
}));

/**
 * Record a completed agent execution to the canonical log.
 * ACID-guaranteed; failure means execution is NOT recorded for billing.
 * 
 * @param context - Execution context (org, workspace, user)
 * @param execution - Execution metadata (agent, origin, status, tokens, outputs)
 * @returns recorded execution ID + synced_to_graph_at flag
 */
async function recordExecution(
  context: ExecutionContext,
  execution: ExecutionTelemetry
): Promise<{ executionId: string; syncedToGraphAt: Date | null }>;

0014 [DB Migration]
├─ OXA-XXXX.1 (CREATE tables)
├─ OXA-XXXX.3 (TypeScript)
├─ OXA-XXXX.4 (Handler)
│  ├─ OXA-XXXX.5 (Chat)
│  ├─ OXA-XXXX.6 (Event Trigger) *BLOCKED
│  ├─ OXA-XXXX.7 (Scheduled)
│  ├─ OXA-XXXX.8 (MCP)
│  ├─ OXA-XXXX.9 (Neo4j Sync)
│  │  └─ OXA-XXXX.10 (Retry Cron)
│  ├─ OXA-XXXX.11 (ClickHouse)
│  ├─ OXA-XXXX.12 (API Routes)
│  └─ OXA-XXXX.13 (MCP Tools)

0015 [DB Migration]
└─ OXA-XXXX.2 (DROP dead tables)
   └─ All OXA-XXXX.4+ (no dependency; can run in parallel after 0014)

┌─────────────────────────────────────────────────────────────┐
│ Chat UI: User submits message                               │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ Agent processes request                                      │
│ - If "/plan" → agent generates a multi-step plan            │
│ - Creates: agent.workflow_runs row (plan container)         │
│ - For each task in plan:                                    │
│     └─ Invoke sub-agent → record agent_executions           │
└────────────────────┬────────────────────────────────────────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
         ▼           ▼           ▼
    ┌────────┐  ┌────────┐  ┌────────┐
    │ Task 1 │  │ Task 2 │  │ Task 3 │
    │ (exec) │  │ (exec) │  │ (exec) │
    └────────┘  └────────┘  └────────┘
     
    Each task:
    - Spawns agent_executions with:
      origin_type = 'workflow_run'
      origin_id = <workflow_run_id>
      status, tokens, cost, etc.

type WorkflowRun = {
  id: string; // "wfr-123"
  
  // Ownership
  orgId: string;
  workspaceId: string;
  
  // Plan definition
  title: string; // "Research competitor features"
  goal: string; // User's intent
  planJson: Array<Task>; // [
                         //   {stepNumber: 1, task: "...", type: "..."},
                         //   {stepNumber: 2, task: "...", dependencies: [1]},
                         // ]
  
  // Progress tracking
  status: 'planning' | 'running' | 'completed' | 'failed' | 'cancelled';
  totalTasks: number;
  completedTasks: number;
  failedTasks: number;
  
  // Execution config
  maxParallelism: number; // default 50
  outputFormat: 'json' | 'csv';
  resultUrl?: string; // If result written to storage
  
  // Timing
  startedAt?: Date;
  completedAt?: Date;
  
  // Audit
  createdAt: Date;
  updatedAt: Date;
  createdByUserId?: string;
};

SELECT id, title, status, completed_tasks, total_tasks 
FROM agent.workflow_runs 
WHERE org_id = $1 AND created_at > now() - interval '24h'
ORDER BY created_at DESC;

type AgentExecution = {
  id: string; // "aex-123"
  
  // Ownership
  orgId: string;
  workspaceId: string;
  
  // Agent identity
  agentId: string;
  agentVersionId: string;
  
  // Polymorphic origin
  originType: 'chat' | 'event_trigger' | 'scheduled_job' | 'mcp_request' | 'workflow_run';
  originId: string; // conversationId, triggerId, scheduleRunId, mcpRequestId, OR workflow_run_id
  
  // Execution state
  status: 'planning' | 'running' | 'completed' | 'failed' | 'cancelled';
  inputPayload: Record<string, unknown>;
  outputPayload?: Record<string, unknown>;
  failureReason?: string;
  
  // Telemetry (canonical for metering)
  startedAt?: Date;
  completedAt?: Date;
  latencyMs?: number;
  inputTokens?: number;
  outputTokens?: number;
  estimatedCostUsd?: Decimal; // Pulled from AI SDK response
  
  // Sync flag (for Neo4j mirror)
  syncedToGraphAt?: Date;
  
  // Audit
  createdAt: Date;
  updatedAt: Date;
  createdByUserId?: string;
};

SELECT id, agent_id, status, estimated_cost_usd, input_tokens, output_tokens
FROM agent.agent_executions
WHERE origin_type = 'workflow_run' AND origin_id = $1
ORDER BY created_at ASC;

-- Total cost of orchestration
SELECT SUM(estimated_cost_usd) as total_cost
FROM agent.agent_executions
WHERE origin_type = 'workflow_run' AND origin_id = $1;

workflow_runs = "The plan" (container)
agent_executions = "Execution ledger" (log)

workflow_runs is the "what should happen"
agent_executions is the "what actually happened + its cost"

Message: "Plan a pricing page" → Agent (planning phase)

Agent (Claude, planning) thinks:
"To build a pricing page, I should:
  1. Analyze competitor pricing pages
  2. Research user preferences from support tickets
  3. Generate a pricing strategy
  4. Draft the page copy"

Output:
{
  "type": "plan",
  "tasks": [
    {stepNumber: 1, task: "Analyze competitor pricing", type: "research", ...},
    {stepNumber: 2, task: "Research user preferences", type: "research", ...},
    {stepNumber: 3, task: "Generate strategy", type: "synthesis", ...},
    {stepNumber: 4, task: "Draft page", type: "generation", ...}
  ]
}

agent_executions (planning phase):
- id: aex-plan-001
- origin_type: 'chat'
- origin_id: <conversation_id>
- status: 'completed'
- agent: Claude (planner)
- input_tokens: 1240
- output_tokens: 340
- estimated_cost_usd: 0.0052

workflow_runs (creation):
- id: wfr-456
- title: "Plan: Build a pricing page"
- goal: "Build a pricing page"
- plan_json: [task1, task2, task3, task4]
- status: 'running'
- totalTasks: 4
- completedTasks: 0

Agent spawned (Task 1: Analyze competitor pricing)
└─ Invokes: "Analyze Stripe, GitHub, Vercel pricing pages"

agent_executions (task 1 execution):
- id: aex-task1-001
- origin_type: 'workflow_run'  ← This is the link back to wfr-456
- origin_id: 'wfr-456'         ← Connect to the orchestration container
- status: 'completed'
- agent: Claude (researcher)
- input_tokens: 2100
- output_tokens: 1800
- estimated_cost_usd: 0.0156

agent_executions:
- id: aex-task2-001
- origin_type: 'workflow_run'
- origin_id: 'wfr-456'
- status: 'completed'
- estimated_cost_usd: 0.0098

agent_executions:
- id: aex-task3-001
- origin_type: 'workflow_run'
- origin_id: 'wfr-456'
- status: 'completed'
- estimated_cost_usd: 0.0142

Agent spawned (Task 4: Draft page)
└─ Invokes: "Generate pricing page copy and markdown"

agent_executions:
- id: aex-task4-001
- origin_type: 'workflow_run'
- origin_id: 'wfr-456'
- status: 'completed'
- estimated_cost_usd: 0.0234

workflow_runs (completion):
- id: wfr-456
- status: 'completed'
- completedTasks: 4
- resultUrl: 'https://...' ← Generated artifacts

Metrics (from agent_executions):
SELECT SUM(estimated_cost_usd) FROM agent.agent_executions
WHERE origin_type = 'workflow_run' AND origin_id = 'wfr-456'
-- Total: 0.0052 + 0.0156 + 0.0098 + 0.0142 + 0.0234 = 0.0682

SELECT SUM(ae.estimated_cost_usd) as total_cost
FROM agent.agent_executions ae
WHERE ae.origin_type = 'workflow_run' AND ae.origin_id = ?;

SELECT 
  ae.id, 
  ae.status, 
  ae.estimated_cost_usd, 
  ae.input_tokens, 
  ae.output_tokens,
  ae.latency_ms
FROM agent.agent_executions ae
WHERE ae.origin_type = 'workflow_run' AND ae.origin_id = ?
ORDER BY ae.created_at ASC;

SELECT 
  wr.id,
  wr.title,
  SUM(ae.estimated_cost_usd) as total_cost,
  COUNT(ae.id) as task_count
FROM agent.workflow_runs wr
LEFT JOIN agent.agent_executions ae 
  ON wr.id = ae.origin_id 
  AND ae.origin_type = 'workflow_run'
WHERE wr.org_id = ?
GROUP BY wr.id, wr.title
HAVING SUM(ae.estimated_cost_usd) > 0.05
ORDER BY total_cost DESC;

MATCH (exec:Execution {id: "aex-task2-001"})
       -[:TOUCHED_ENTITY]-> (entity)
RETURN entity;