Agent Execution Engine

interface AgentAdapter {
  dispatch(request: DispatchRequest): Promise<DispatchResult>;
}
 
interface DispatchRequest {
  prompt:        string;
  systemPrompt?: string;
  skillsDir?:    string;        // path to temp dir (Claude: --add-dir; Ollama: read + prepend)
  sessionId?:    string;        // resume prior session (Claude only)
  activityRunId: string;        // for phone-home callback validation
  model:         string;
  timeoutMs:     number;        // derived from ClaudeAdapterConfig.timeoutSec * 1000
  graceMs?:      number;        // derived from ClaudeAdapterConfig.graceSec * 1000 (Claude only)
  maxTurns?:     number;        // derived from ClaudeAdapterConfig.maxTurnsPerRun (Claude only)
  maxTokens?:    number;
 
  // Run context — passed to WebhookAdapter as POST body fields so external agents
  // know why they were woken and can authenticate their callback
  wakeReason:    'new_task' | 'rejection' | 'scheduled' | 'unblocked'
               | 'subtask_completed' | 'review_approved' | 'review_feedback';
  tenantId:      string;
  agentRole:     AgentRole;
  runId:         string;        // same as activityRunId — exposed for external adapters
}
 
interface DispatchResult {
  // For sync adapters (Claude CLI, Ollama): result is available immediately
  text?:       string;
  sessionId?:  string | null;
  usage?:      { inputTokens: number; outputTokens: number };
  cost?:       number;
  durationMs?: number;
 
  // For async adapters (Webhook): result arrives via phone-home callback
  callbackUrl?: string;
  taskToken?:   string;   // short-lived JWT scoped to this activityRunId
}
 
type AgentEvent =
  | { type: 'text_delta';  delta: string }
  | { type: 'tool_call';   name: string; input: unknown }
  | { type: 'tool_result'; name: string; output: unknown }
  | { type: 'completed';   result: DispatchResult }
  | { type: 'error';       error: AgentError };

// POST to agentConfig.webhookUrl
{
  prompt:       "...",
  wakeReason:   "rejection",
  agentRole:    "copywriter",
  tenantId:     "ten_abc123",
  runId:        "run_xyz789",
  callbackUrl:  "https://api.leadmetrics.io/api/agent-callback/run_xyz789",
  taskToken:    "<JWT signed with run-scoped secret, expires in 1h>"
}

function resolveAdapter(config: AgentConfig): AgentAdapter {
  switch (config.adapterType) {
    case 'claude':   return new ClaudeAdapter(config);
    case 'openai':   return new OpenAIAdapter(config);
    case 'ollama':   return new OllamaAdapter(config);
    case 'webhook':  return new WebhookAdapter(config);
  }
}

async function withGracefulTimeout(
  child: ChildProcess,
  timeoutMs: number,
  graceMs: number
): Promise<void> {
  const sigterm = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
  const sigkill = setTimeout(() => child.kill('SIGKILL'), timeoutMs + graceMs);
  try {
    await onProcessExit(child);
  } finally {
    clearTimeout(sigterm);
    clearTimeout(sigkill);
  }
}

interface AdapterTestResult {
  ok:      boolean;
  message: string;          // human-readable status
  checks:  AdapterCheck[];  // individual check results
}
 
interface AdapterCheck {
  name:    string;
  ok:      boolean;
  detail?: string;
}

          ┌────────────┐
          │   active   │◄──────────────────────────┐
          └──────┬─────┘                           │
                 │ job picked up                   │ error cleared (manual)
                 ▼                                  │ or budget reset (auto)
          ┌────────────┐       all retries         │
          │  running   │──── exhausted ────────►┌──┴──────┐
          └──────┬─────┘                        │  error  │
                 │ job completes                 └─────────┘
                 ▼
          ┌────────────┐
          │    idle    │  (active but no queued tasks — display alias for active)
          └──────┬─────┘
                 │ budget exceeded / manual pause
                 ▼
          ┌────────────┐
          │   paused   │
          └──────┬─────┘
                 │ permanently disabled
                 ▼
          ┌─────────────┐
          │ terminated  │
          └─────────────┘

// Worker sets running on job start
await db.update(agentConfigs)
  .set({ status: 'running', runningCount: sql`running_count + 1` })
  .where(and(eq(agentConfigs.tenantId, tenantId), eq(agentConfigs.role, agentRole)));
 
// Worker restores active when running count reaches zero
await db.update(agentConfigs)
  .set({
    status:       sql`CASE WHEN running_count - 1 <= 0 THEN 'active' ELSE 'running' END`,
    runningCount: sql`GREATEST(running_count - 1, 0)`,
  })
  .where(and(eq(agentConfigs.tenantId, tenantId), eq(agentConfigs.role, agentRole)));
 
// Dead-letter handler sets error
await db.update(agentConfigs)
  .set({ status: 'error', lastErrorAt: new Date(), lastErrorMessage: errorMessage })
  .where(and(eq(agentConfigs.tenantId, tenantId), eq(agentConfigs.role, agentRole)));

const MODEL_PRICING: Record<string, { inputPer1M: number; outputPer1M: number }> = {
  'claude-sonnet-4-6': { inputPer1M: 3.00,  outputPer1M: 15.00 },
  'claude-haiku-4-5':  { inputPer1M: 0.25,  outputPer1M: 1.25  },
  'gemma3:4b':         { inputPer1M: 0,      outputPer1M: 0     }, // local = free
};
 
function calculateCost(model: string, inputTokens: number, outputTokens: number): number {
  const pricing = MODEL_PRICING[model] ?? { inputPer1M: 0, outputPer1M: 0 };
  return (inputTokens / 1_000_000) * pricing.inputPer1M
       + (outputTokens / 1_000_000) * pricing.outputPer1M;
}

await db.insert(llmCalls).values({
  activityRunId,
  tenantId,
  sessionId,
  model,
  promptHash:    sha256(prompt),
  responseHash:  sha256(resultText),
  inputTokens,
  outputTokens,
  costUsd:       calculateCost(model, inputTokens, outputTokens),
  durationMs,
  createdAt:     new Date(),
});

Claude/Ollama Adapter (AsyncIterable<AgentEvent>)
        │ text_delta events
        ▼
Next.js API Route (SSE, text/event-stream)
        │
        ▼
usePlatformEvents() hook (React, SSE client)
        │
        ▼
Activity Detail screen — live output pane (W5)

agent-engine/
├── src/
│   ├── adapters/
│   │   ├── claude.ts       # ClaudeAdapter — CLI child process, NDJSON, graceful shutdown
│   │   ├── ollama.ts       # OllamaAdapter — local REST, streaming
│   │   ├── openai.ts       # OpenAIAdapter — REST API, streaming SSE
│   │   └── webhook.ts      # WebhookAdapter — POST + phone-home callback
│   ├── config/
│   │   ├── claude.ts       # ClaudeAdapterConfig schema + renderPromptTemplate()
│   │   ├── ollama.ts       # OllamaAdapterConfig schema
│   │   ├── openai.ts       # OpenAIAdapterConfig schema
│   │   └── webhook.ts      # WebhookAdapterConfig schema
│   ├── health/
│   │   ├── claude.ts       # ClaudeAdapter health checks (CLI, auth, cwd, probe)
│   │   ├── ollama.ts       # OllamaAdapter health checks (server, model)
│   │   └── types.ts        # AdapterTestResult, AdapterCheck
│   ├── factory.ts          # resolveAdapter()
│   ├── callback.ts         # Phone-home callback handler (validates JWT, stores result)
│   ├── status.ts           # Agent status transitions — setRunning(), setIdle(), setError()
│   ├── pricing.ts          # MODEL_PRICING + calculateCost()
│   ├── types.ts            # AgentAdapter, DispatchRequest, AgentEvent, DispatchResult
│   └── index.ts
└── package.json