opencastle 0.27.0 → 0.27.1

package/src/cli/convoy/types.ts

@@ -1,4 +1,4 @@
-export type ConvoyStatus = 'pending' | 'running' | 'done' | 'failed' | 'gate-failed'
+export type ConvoyStatus = 'pending' | 'running' | 'done' | 'failed' | 'gate-failed' | 'hook-failed'
 
 export type ConvoyTaskStatus =
   | 'pending'
@@ -6,8 +6,13 @@ export type ConvoyTaskStatus =
   | 'running'
   | 'done'
   | 'failed'
+  | 'gate-failed'
+  | 'review-blocked'
   | 'timed-out'
   | 'skipped'
+  | 'hook-failed'
+  | 'disputed'
+  | 'wait-for-input'
 
 export type WorkerStatus = 'spawned' | 'running' | 'done' | 'failed' | 'killed'
 
@@ -26,6 +31,9 @@ export interface ConvoyRecord {
   total_tokens: number | null
   total_cost_usd: string | null
   pipeline_id: string | null
+  circuit_state: string | null
+  review_tokens_total: number | null
+  review_budget: number | null
 }
 
 export interface TaskRecord {
@@ -52,6 +60,24 @@ export interface TaskRecord {
   completion_tokens: number | null
   total_tokens: number | null
   cost_usd: string | null
+  gates: string | null
+  on_exhausted: 'dlq' | 'skip' | 'stop'
+  injected: number
+  provenance: string | null
+  idempotency_key: string | null
+  current_step: number | null
+  total_steps: number | null
+  review_level: string | null
+  review_verdict: string | null
+  review_tokens: number | null
+  review_model: string | null
+  panel_attempts: number
+  dispute_id: string | null
+  drift_score: number | null
+  drift_retried: number
+  outputs?: string | null          // JSON array of TaskOutput
+  inputs?: string | null           // JSON array of TaskInput
+  discovered_issues?: string | null // JSON array
 }
 
 export interface WorkerRecord {
@@ -90,3 +116,146 @@ export interface PipelineRecord {
   total_tokens: number | null
   total_cost_usd: string | null
 }
+
+export interface BuiltInGatesConfig {
+  secret_scan?: boolean
+  blast_radius?: boolean
+  dependency_audit?: 'auto' | boolean
+  regression_test?: 'auto' | boolean
+  browser_test?: 'auto' | boolean
+  gate_timeout?: number
+}
+
+
+export interface BrowserTestConfig {
+  urls: string[]
+  check_console_errors?: boolean
+  visual_diff_threshold?: number
+  a11y?: boolean
+  severity_threshold?: 'critical' | 'serious' | 'moderate' | 'minor'
+  baselines_dir?: string
+}
+export interface GuardConfig {
+  enabled?: boolean      // default: true
+  agent?: string         // optional agent name (e.g. 'session-guard')
+  checks?: string[]      // e.g. ['observability', 'cleanup', 'cost-report']
+}
+
+export interface DlqRecord {
+  id: string
+  convoy_id: string
+  task_id: string
+  agent: string
+  failure_type: string
+  error_output: string | null
+  attempts: number
+  tokens_spent: number | null
+  escalation_task_id: string | null
+  resolved: number
+  resolution: string | null
+  created_at: string
+  resolved_at: string | null
+}
+
+export interface CircuitBreakerConfig {
+  threshold?: number      // failures before Open (default: 3)
+  cooldown_ms?: number    // ms in Open before Half-Open (default: 300000 = 5min)
+  fallback_agent?: string // reassign pending tasks when circuit opens
+}
+
+export interface TaskOutput {
+  name: string
+  type: 'file' | 'summary' | 'json'
+  description?: string
+}
+
+export interface TaskInput {
+  from: string
+  name: string
+  as?: string
+}
+
+export interface ArtifactRecord {
+  id: string
+  convoy_id: string
+  task_id: string
+  name: string
+  type: 'file' | 'summary' | 'json'
+  content: string
+  created_at: string
+}
+
+export interface AgentIdentityRecord {
+  id: string
+  agent: string
+  convoy_id: string
+  task_id: string
+  summary: string
+  created_at: string
+  retention_days: number
+}
+
+export interface StepCondition {
+  step: string         // reference previous step by id
+  exitCode?: { eq?: number; ne?: number; gt?: number; lt?: number }
+  fileExists?: { path: string }
+}
+
+export interface TaskStep {
+  id?: string
+  prompt: string
+  gates?: string[]
+  max_retries?: number // inherits from task if omitted
+  if?: StepCondition
+}
+
+export interface Hook {
+  type: 'review' | 'guard' | 'agent' | 'command' | 'validate'
+  name?: string
+  prompt?: string  // for agent hooks
+  command?: string // for command hooks
+  on?: 'pre_task' | 'post_task' | 'post_convoy'
+}
+
+export interface TaskStepRecord {
+  id: number
+  task_id: string
+  step_index: number
+  prompt: string
+  gates: string | null
+  status: string
+  exit_code: number | null
+  output: string | null
+  started_at: string | null
+  finished_at: string | null
+}
+
+export interface WatchTrigger {
+  type: 'file-change' | 'cron' | 'git-push'
+  glob?: string        // for file-change: glob pattern to watch
+  schedule?: string    // for cron: 5-field cron expression
+  branch?: string      // for git-push: branch name pattern
+  debounce_ms?: number // file-change debounce (default: 500ms)
+}
+
+export interface WatchConfig {
+  triggers: WatchTrigger[]
+  clear_scratchpad?: boolean // clear scratchpad on watch start
+  scratchpad_retention_days?: number // auto-clear scratchpad entries older than N days
+}
+
+export interface ScratchpadRecord {
+  key: string
+  value: string
+  updated_at: string
+}
+
+export interface MCPServerConfig {
+  name: string
+  type: string
+  local?: boolean
+  command?: string
+  args?: string[]
+  url?: string
+  config?: Record<string, unknown>
+}

package/src/cli/run/adapters/claude.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, existsSync, readFileSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { EventEmitter } from 'node:events'
+import type { Task } from '../../types.js'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeTask(): Task {
+  return {
+    id: 'test-task',
+    agent: 'developer',
+    prompt: 'Do something',
+    files: [],
+    timeout: '5m',
+    depends_on: [],
+    description: 'test task',
+    max_retries: 0,
+  } as unknown as Task
+}
+
+function makeMockProc(exitCode = 0, stdoutData = '{"result":"ok"}') {
+  const proc = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter
+    stderr: EventEmitter
+    killed: boolean
+    kill: ReturnType<typeof vi.fn>
+  }
+  proc.stdout = new EventEmitter()
+  proc.stderr = new EventEmitter()
+  proc.killed = false
+  proc.kill = vi.fn()
+  process.nextTick(() => {
+    if (stdoutData) proc.stdout.emit('data', Buffer.from(stdoutData))
+    proc.emit('close', exitCode)
+  })
+  return proc
+}
+
+// ── SDK mode ──────────────────────────────────────────────────────────────────
+
+describe('claude adapter — SDK mode', () => {
+  let mockCreateSession: ReturnType<typeof vi.fn>
+  let mockSession: {
+    sendAndWait: ReturnType<typeof vi.fn>
+    on: ReturnType<typeof vi.fn>
+    destroy: ReturnType<typeof vi.fn>
+    abort: ReturnType<typeof vi.fn>
+  }
+
+  beforeEach(() => {
+    vi.resetModules()
+    mockSession = {
+      sendAndWait: vi.fn().mockResolvedValue({ data: { content: 'I did the task' } }),
+      on: vi.fn(),
+      destroy: vi.fn().mockResolvedValue(undefined),
+      abort: vi.fn().mockResolvedValue(undefined),
+    }
+    mockCreateSession = vi.fn().mockResolvedValue(mockSession)
+    vi.doMock('@anthropic-ai/agent-sdk', () => {
+      // Must use a regular function (not arrow) so `new AgentClient()` works
+      function MockAgentClient(this: Record<string, unknown>) {
+        this.start = vi.fn().mockResolvedValue(undefined)
+        this.createSession = mockCreateSession
+      }
+      return {
+        AgentClient: MockAgentClient,
+        approveAll: vi.fn(),
+      }
+    })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('passes mcpServers to createSession when provided', async () => {
+    const { execute } = await import('./claude.js')
+    const mcpServers = [{ name: 'my-mcp', type: 'local', command: 'node', args: ['server.js'] }]
+    await execute(makeTask(), { mcpServers })
+    expect(mockCreateSession).toHaveBeenCalledWith(
+      expect.objectContaining({ mcpServers }),
+    )
+  })
+
+  it('does NOT include mcpServers in createSession when not provided', async () => {
+    const { execute } = await import('./claude.js')
+    await execute(makeTask(), {})
+    const callArg = mockCreateSession.mock.calls[0]?.[0] as Record<string, unknown>
+    expect(callArg).not.toHaveProperty('mcpServers')
+  })
+
+  it('does NOT include mcpServers when mcpServers is empty array', async () => {
+    const { execute } = await import('./claude.js')
+    await execute(makeTask(), { mcpServers: [] })
+    const callArg = mockCreateSession.mock.calls[0]?.[0] as Record<string, unknown>
+    expect(callArg).not.toHaveProperty('mcpServers')
+  })
+})
+
+// ── CLI mode ──────────────────────────────────────────────────────────────────
+
+describe('claude adapter — CLI mode', () => {
+  let tmpDir: string
+  let mockSpawn: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.resetModules()
+    tmpDir = realpathSync(mkdtempSync(join(tmpdir(), 'claude-test-')))
+
+    mockSpawn = vi.fn().mockImplementation((cmd: string) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      return makeMockProc(0, '{"result":"ok"}')
+    })
+    vi.doMock('node:child_process', () => ({ spawn: mockSpawn }))
+  })
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true })
+    vi.restoreAllMocks()
+  })
+
+  it('writes mcp.json to cwd with correct format when mcpServers provided', async () => {
+    let capturedContent: string | null = null
+    mockSpawn.mockImplementation((cmd: string) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      const mcpPath = join(tmpDir, 'mcp.json')
+      if (existsSync(mcpPath)) {
+        capturedContent = readFileSync(mcpPath, 'utf8')
+      }
+      return makeMockProc(0, '{}')
+    })
+
+    const { executeViaCli } = await import('./claude.js')
+    const mcpServers = [{ name: 'my-mcp', type: 'local', command: 'node', args: ['server.js'] }]
+    await executeViaCli(makeTask(), { mcpServers, cwd: tmpDir })
+
+    expect(capturedContent).not.toBeNull()
+    expect(JSON.parse(capturedContent!)).toEqual({
+      mcpServers: { 'my-mcp': { command: 'node', args: ['server.js'] } },
+    })
+  })
+
+  it('passes --mcp-config flag pointing to mcp.json path', async () => {
+    const capturedArgs: string[] = []
+    mockSpawn.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      capturedArgs.push(...args)
+      return makeMockProc(0, '{}')
+    })
+    const { executeViaCli } = await import('./claude.js')
+    const mcpServers = [{ name: 'my-mcp', type: 'local', command: 'node', args: ['server.js'] }]
+    await executeViaCli(makeTask(), { mcpServers, cwd: tmpDir })
+
+    const idx = capturedArgs.indexOf('--mcp-config')
+    expect(idx).toBeGreaterThanOrEqual(0)
+    expect(capturedArgs[idx + 1]).toBe(join(tmpDir, 'mcp.json'))
+  })
+
+  it('cleans up mcp.json after successful execution', async () => {
+    const { executeViaCli } = await import('./claude.js')
+    const mcpServers = [{ name: 'my-mcp', type: 'local', command: 'node', args: ['server.js'] }]
+    await executeViaCli(makeTask(), { mcpServers, cwd: tmpDir })
+    expect(existsSync(join(tmpDir, 'mcp.json'))).toBe(false)
+  })
+
+  it('cleans up mcp.json after failed execution (non-zero exit)', async () => {
+    mockSpawn.mockImplementation((cmd: string) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      return makeMockProc(1, '')
+    })
+    const { executeViaCli } = await import('./claude.js')
+    const mcpServers = [{ name: 'err-mcp', type: 'local', command: 'node', args: [] }]
+    await executeViaCli(makeTask(), { mcpServers, cwd: tmpDir })
+    expect(existsSync(join(tmpDir, 'mcp.json'))).toBe(false)
+  })
+
+  it('includes --approve-mcps flag when mcp_approve_all is true', async () => {
+    const capturedArgs: string[] = []
+    mockSpawn.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      capturedArgs.push(...args)
+      return makeMockProc(0, '{}')
+    })
+    const { executeViaCli } = await import('./claude.js')
+    await executeViaCli(makeTask(), { mcp_approve_all: true, cwd: tmpDir })
+    expect(capturedArgs).toContain('--approve-mcps')
+  })
+
+  it('does NOT write mcp.json when mcpServers not configured', async () => {
+    const { executeViaCli } = await import('./claude.js')
+    await executeViaCli(makeTask(), { cwd: tmpDir })
+    expect(existsSync(join(tmpDir, 'mcp.json'))).toBe(false)
+  })
+
+  it('does NOT add --approve-mcps when mcp_approve_all is not set', async () => {
+    const capturedArgs: string[] = []
+    mockSpawn.mockImplementation((cmd: string, args: string[]) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      capturedArgs.push(...args)
+      return makeMockProc(0, '{}')
+    })
+    const { executeViaCli } = await import('./claude.js')
+    await executeViaCli(makeTask(), { cwd: tmpDir })
+    expect(capturedArgs).not.toContain('--approve-mcps')
+  })
+
+  it('maps mcpServers with url and config into mcp.json', async () => {
+    let capturedContent: string | null = null
+    mockSpawn.mockImplementation((cmd: string) => {
+      if (cmd === 'which') return makeMockProc(0, '')
+      const mcpPath = join(tmpDir, 'mcp.json')
+      if (existsSync(mcpPath)) capturedContent = readFileSync(mcpPath, 'utf8')
+      return makeMockProc(0, '{}')
+    })
+    const { executeViaCli } = await import('./claude.js')
+    const mcpServers = [
+      {
+        name: 'remote-mcp',
+        type: 'remote',
+        url: 'http://localhost:9000',
+        config: { token: 'abc' },
+      },
+    ]
+    await executeViaCli(makeTask(), { mcpServers, cwd: tmpDir })
+    expect(capturedContent).not.toBeNull()
+    const parsed = JSON.parse(capturedContent!) as { mcpServers: Record<string, Record<string, unknown>> }
+    expect(parsed.mcpServers['remote-mcp']).toMatchObject({
+      url: 'http://localhost:9000',
+      token: 'abc',
+    })
+  })
+})

package/src/cli/run/adapters/claude.ts

@@ -1,10 +1,13 @@
 import { spawn } from 'node:child_process'
+import { writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
 import { parseTimeout } from '../schema.js'
 import type { Task, ExecuteOptions, ExecuteResult, TokenUsage } from '../../types.js'
 
 // Adapter name
 export const name = 'claude'
 
+export function supportsSessionContinuity(): boolean { return false }
 // Module-level state for mode selection
 let mode: 'sdk' | 'cli' | null = null
 
@@ -100,6 +103,8 @@ async function executeViaSdk(task: Task, options: ExecuteOptions = {}): Promise<
     },
     infiniteSessions: { enabled: false },
     ...(options.verbose ? { streaming: true } : {}),
+    // mcpServers is forward-compatible: field will be recognised by future SDK versions
+    ...(options.mcpServers?.length ? { mcpServers: options.mcpServers } : {}),
   })
   activeSessions.set(task.id, session)
   if (options.verbose) {
@@ -108,12 +113,21 @@ async function executeViaSdk(task: Task, options: ExecuteOptions = {}): Promise<
       process.stdout.write(event.data.deltaContent)
     })
   }
+  interface SdkResponse {
+    data?: {
+      content?: string
+      usage?: Record<string, number>
+    }
+    usage?: Record<string, number>
+  }
+
   try {
     const timeoutMs = parseTimeout(task.timeout)
     const response = await session.sendAndWait({ prompt }, timeoutMs)
-    const data = (response as any)?.data as Record<string, unknown> | undefined
+    const typed = response as SdkResponse
+    const data = typed?.data
     const output = (data?.content as string | undefined) ?? ''
-    const rawUsage = data?.usage ?? (response as any)?.usage
+    const rawUsage = data?.usage ?? typed?.usage
     const u = rawUsage as Record<string, number> | undefined
     const usageResult = u
       ? {
@@ -150,7 +164,7 @@ function killSdk(task: Task): void {
 }
 
 // --- CLI implementation (from claude-code.ts) ---
-async function executeViaCli(task: Task, options: ExecuteOptions = {}): Promise<ExecuteResult> {
+export async function executeViaCli(task: Task, options: ExecuteOptions = {}): Promise<ExecuteResult> {
   let prompt = `You are a ${task.agent}. ${task.prompt}`
   if (task.files && task.files.length > 0) {
     prompt += `\n\nOnly modify files under: ${task.files.join(', ')}`
@@ -163,11 +177,32 @@ async function executeViaCli(task: Task, options: ExecuteOptions = {}): Promise<
     '--max-turns',
     '50',
   ]
-  return new Promise((resolve) => {
+  const cwd = options?.cwd ?? process.cwd()
+  const mcpJsonPath = join(cwd, 'mcp.json')
+  let wroteJson = false
+  if (options.mcpServers?.length) {
+    const mcpJson: Record<string, Record<string, unknown>> = {}
+    for (const server of options.mcpServers) {
+      const entry: Record<string, unknown> = {}
+      if (server.command) entry.command = server.command
+      if (server.args) entry.args = server.args
+      if (server.url) entry.url = server.url
+      if (server.config) Object.assign(entry, server.config)
+      mcpJson[server.name] = entry
+    }
+    writeFileSync(mcpJsonPath, JSON.stringify({ mcpServers: mcpJson }, null, 2), 'utf8')
+    args.push('--mcp-config', mcpJsonPath)
+    wroteJson = true
+  }
+  if (options.mcp_approve_all) {
+    args.push('--approve-mcps')
+  }
+  try {
+  return await new Promise<ExecuteResult>((resolve) => {
     const proc = spawn('claude', args, {
       stdio: ['ignore', 'pipe', 'pipe'],
       env: { ...process.env },
-      cwd: options?.cwd ?? process.cwd(),
+      cwd,
     })
     let stdout = ''
     let stderr = ''
@@ -212,6 +247,11 @@ async function executeViaCli(task: Task, options: ExecuteOptions = {}): Promise<
     })
     task._process = proc
   })
+  } finally {
+    if (wroteJson) {
+      try { unlinkSync(mcpJsonPath) } catch { /* ignore */ }
+    }
+  }
 }
 
 function killCli(task: Task): void {