opencastle 0.27.0 → 0.27.2

package/src/cli/agents.ts

@@ -0,0 +1,177 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { CliContext } from './types.js'
+import { c } from './prompt.js'
+
+const HELP = `
+  opencastle agents [subcommand] [options]
+
+  Manage persistent agent identities.
+
+  Subcommands:
+    list                     List all agent identities (agent, task count, latest date)
+    inspect <agent>          Show summaries for a specific agent
+    purge <agent>            Delete all identities for an agent
+    compact --older-than <d> Delete identities older than N days
+
+  Options:
+    --older-than <days>      Days threshold for compact subcommand
+    --yes, -y                Skip confirmation prompt
+    --help, -h               Show this help
+`
+
+interface AgentsOptions {
+  subcommand: string | null
+  agentName: string | null
+  olderThan: number | null
+  yes: boolean
+  help: boolean
+}
+
+function parseAgentsArgs(args: string[]): AgentsOptions {
+  const opts: AgentsOptions = {
+    subcommand: null,
+    agentName: null,
+    olderThan: null,
+    yes: false,
+    help: false,
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    switch (arg) {
+      case '--help':
+      case '-h':
+        opts.help = true
+        break
+      case '--older-than':
+        if (i + 1 >= args.length) { console.error('  \u2717 --older-than requires a number'); process.exit(1) }
+        opts.olderThan = parseInt(args[++i], 10)
+        if (!Number.isFinite(opts.olderThan) || opts.olderThan < 1) {
+          console.error('  \u2717 --older-than must be a positive integer')
+          process.exit(1)
+        }
+        break
+      case '--yes':
+      case '-y':
+        opts.yes = true
+        break
+      default:
+        if (arg.startsWith('--')) {
+          console.error(`  \u2717 Unknown option: ${arg}`)
+          console.log(HELP)
+          process.exit(1)
+        }
+        if (!opts.subcommand) {
+          opts.subcommand = arg
+        } else if (!opts.agentName) {
+          opts.agentName = arg
+        }
+    }
+  }
+
+  return opts
+}
+
+export default async function agents({ args }: CliContext): Promise<void> {
+  const opts = parseAgentsArgs(args)
+
+  if (opts.help || !opts.subcommand) {
+    console.log(HELP)
+    return
+  }
+
+  const dbPath = resolve(process.cwd(), '.opencastle', 'convoy.db')
+  if (!existsSync(dbPath)) {
+    console.log('  No convoy database found at .opencastle/convoy.db')
+    return
+  }
+
+  const { createConvoyStore } = await import('./convoy/store.js')
+  const store = createConvoyStore(dbPath)
+
+  try {
+    switch (opts.subcommand) {
+      case 'list': {
+        const summaries = store.listAgentIdentitySummary()
+        if (summaries.length === 0) {
+          console.log('  No agent identities found.')
+          return
+        }
+        console.log(`\n  Agent Identities (${summaries.length} agents):\n`)
+        console.log(`  ${'Agent'.padEnd(25)} ${'Tasks'.padEnd(8)} Latest`)
+        console.log(`  ${'\u2500'.repeat(25)} ${'\u2500'.repeat(8)} ${'\u2500'.repeat(20)}`)
+        for (const s of summaries) {
+          console.log(`  ${s.agent.padEnd(25)} ${String(s.task_count).padEnd(8)} ${s.latest_date}`)
+        }
+        console.log()
+        break
+      }
+
+      case 'inspect': {
+        if (!opts.agentName) {
+          console.error('  \u2717 inspect requires an agent name: opencastle agents inspect <agent>')
+          process.exit(1)
+        }
+        const identities = store.getAgentIdentities(opts.agentName, 100)
+        if (identities.length === 0) {
+          console.log(`  No identities found for agent "${opts.agentName}".`)
+          return
+        }
+        console.log(`\n  Agent: ${opts.agentName} (${identities.length} identities)\n`)
+        for (const id of identities) {
+          console.log(`  ${c.dim('\u2500'.repeat(60))}`)
+          console.log(`  Task: ${id.task_id} | Convoy: ${id.convoy_id}`)
+          console.log(`  Date: ${id.created_at} | Retention: ${id.retention_days}d`)
+          console.log(`  Summary:`)
+          const lines = id.summary.split('\n')
+          for (const line of lines.slice(0, 10)) {
+            console.log(`    ${line}`)
+          }
+          if (lines.length > 10) {
+            console.log(`    ${c.dim(`... ${lines.length - 10} more lines`)}`)
+          }
+          console.log()
+        }
+        break
+      }
+
+      case 'purge': {
+        if (!opts.agentName) {
+          console.error('  \u2717 purge requires an agent name: opencastle agents purge <agent>')
+          process.exit(1)
+        }
+        if (!opts.yes) {
+          const existing = store.getAgentIdentities(opts.agentName, 1000)
+          if (existing.length === 0) {
+            console.log(`  No identities found for agent "${opts.agentName}".`)
+            return
+          }
+          console.log(`\n  This will delete ${existing.length} identities for agent "${opts.agentName}".`)
+          console.log(`  Use --yes or -y to confirm.`)
+          return
+        }
+        const deleted = store.purgeAgentIdentities(opts.agentName)
+        console.log(`  \u2713 Purged ${deleted} identities for agent "${opts.agentName}".`)
+        break
+      }
+
+      case 'compact': {
+        if (!opts.olderThan) {
+          console.error('  \u2717 compact requires --older-than <days>')
+          process.exit(1)
+        }
+        const deleted = store.deleteAgentIdentitiesOlderThan(opts.olderThan)
+        console.log(`  \u2713 Deleted ${deleted} identities older than ${opts.olderThan} days.`)
+        break
+      }
+
+      default:
+        console.error(`  \u2717 Unknown subcommand: ${opts.subcommand}`)
+        console.log(HELP)
+        process.exit(1)
+    }
+  } finally {
+    store.close()
+  }
+}

package/src/cli/baselines.ts

@@ -0,0 +1,143 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
+import { join, basename } from 'node:path'
+import type { CliContext } from './types.js'
+import { scanForSecrets } from './convoy/gates.js'
+
+const HELP = `
+  opencastle baselines <subcommand> [options]
+
+  Manage visual regression baselines.
+
+  Subcommands:
+    update --slug <name> --from <file>   Update a baseline from a PNG file
+    list                                  List all baselines
+
+  Options:
+    --slug <name>    Baseline name (used as filename)
+    --from <file>    Source PNG file path
+    --dir <path>     Baselines directory (default: .opencastle/baselines)
+    --help, -h       Show this help
+`
+
+interface BaselinesOptions {
+  subcommand: string | null
+  slug: string | null
+  from: string | null
+  dir: string
+  help: boolean
+}
+
+function parseBaselinesArgs(args: string[]): BaselinesOptions {
+  const opts: BaselinesOptions = {
+    subcommand: null,
+    slug: null,
+    from: null,
+    dir: '.opencastle/baselines',
+    help: false,
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    switch (arg) {
+      case '--help':
+      case '-h':
+        opts.help = true
+        break
+      case '--slug':
+        if (i + 1 >= args.length) {
+          console.error('  \u2717 --slug requires a name')
+          process.exit(1)
+        }
+        opts.slug = args[++i]
+        break
+      case '--from':
+        if (i + 1 >= args.length) {
+          console.error('  \u2717 --from requires a file path')
+          process.exit(1)
+        }
+        opts.from = args[++i]
+        break
+      case '--dir':
+        if (i + 1 >= args.length) {
+          console.error('  \u2717 --dir requires a path')
+          process.exit(1)
+        }
+        opts.dir = args[++i]
+        break
+      default:
+        if (arg.startsWith('--')) {
+          console.error(`  \u2717 Unknown option: ${arg}`)
+          console.log(HELP)
+          process.exit(1)
+        }
+        if (!opts.subcommand) {
+          opts.subcommand = arg
+        }
+    }
+  }
+  return opts
+}
+
+export default async function baselines({ args }: CliContext): Promise<void> {
+  const opts = parseBaselinesArgs(args)
+
+  if (opts.help || !opts.subcommand) {
+    console.log(HELP)
+    return
+  }
+
+  switch (opts.subcommand) {
+    case 'update': {
+      if (!opts.slug) {
+        console.error('  \u2717 update requires --slug <name>')
+        process.exit(1)
+      }
+      if (!/^[a-zA-Z0-9_-]+$/.test(opts.slug)) {
+        console.error('  \u2717 Slug must contain only alphanumeric characters, hyphens, and underscores')
+        process.exit(1)
+      }
+      if (!opts.from) {
+        console.error('  \u2717 update requires --from <file>')
+        process.exit(1)
+      }
+      if (!existsSync(opts.from)) {
+        console.error(`  \u2717 Source file not found: ${opts.from}`)
+        process.exit(1)
+      }
+      const data = readFileSync(opts.from)
+      const scan = scanForSecrets(data.toString('base64'), opts.from)
+      if (!scan.clean) {
+        console.error('  \u2717 Source file contains potential secrets \u2014 baseline not updated')
+        process.exit(1)
+      }
+      mkdirSync(opts.dir, { recursive: true })
+      const dest = join(opts.dir, `${opts.slug}.png`)
+      writeFileSync(dest, data)
+      console.log(`  \u2713 Baseline updated: ${dest}`)
+      break
+    }
+
+    case 'list': {
+      if (!existsSync(opts.dir)) {
+        console.log(`  No baselines directory found at ${opts.dir}`)
+        return
+      }
+      const files = readdirSync(opts.dir).filter((f) => f.endsWith('.png'))
+      if (files.length === 0) {
+        console.log('  No baselines found.')
+        return
+      }
+      console.log(`\n  Baselines in ${opts.dir}:\n`)
+      for (const file of files) {
+        const stats = statSync(join(opts.dir, file))
+        console.log(`  ${basename(file, '.png').padEnd(30)} ${(stats.size / 1024).toFixed(1)} KB`)
+      }
+      console.log()
+      break
+    }
+
+    default:
+      console.error(`  \u2717 Unknown subcommand: ${opts.subcommand}`)
+      console.log(HELP)
+      process.exit(1)
+  }
+}

package/src/cli/convoy/TELEMETRY.md

@@ -0,0 +1,203 @@
+# Convoy Telemetry Model
+
+How Convoy concepts map to [OpenTelemetry](https://opentelemetry.io/) semantics.
+
+## Conceptual Mapping
+
+| Convoy Concept | OTel Concept | ID Field | Description |
+|---------------|-------------|----------|-------------|
+| **Convoy** | Trace | `convoy_id` → `trace_id` | A single execution run of a `.convoy.yml` spec |
+| **Task** | Span | `task_id` → `span_id` | One unit of work within a convoy |
+| **TaskStep** | Sub-span | `step_index` | Sequential steps within a multi-step task |
+| **Event** | Log / SpanEvent | `type` | Structured occurrence during execution |
+| **Metrics** | Derived aggregates | — | Computed from events (tokens, cost, duration) |
+
+### ID Correlation
+
+```
+trace_id  = convoy_id   (globally unique, set at convoy creation)
+span_id   = task_id      (unique within convoy, from spec)
+worker_id = worker trace (ephemeral, tied to adapter process)
+```
+
+Every event carries `convoy_id`, `task_id`, and `worker_id` (all nullable) to enable correlation across the trace hierarchy.
+
+## Storage
+
+- **Primary**: SQLite (`convoy.db`) — durable, queryable, crash-safe
+- **Supplementary**: NDJSON (`convoy-events.ndjson`) — append-only log for streaming/grep
+
+SQLite is the source of truth. NDJSON is replayed from SQLite on crash recovery via `recoverNdjson()`.
+
+### Write Strategy (v1)
+
+NDJSON writes use synchronous `appendFileSync` + `fsyncSync` per event. This ensures crash-safety — every event is durable before the engine proceeds. Trade-offs:
+
+- **Latency**: ~1-2ms per event (sync I/O). For convoys with <10,000 events this is negligible.
+- **Throughput**: Not suitable for >10,000 events/second workloads.
+- **Crash-safety**: Every event is fsynced before the engine continues, so a crash never loses the last event.
+
+An async buffered writer is deferred as an optimization for Phase 5 if profiling shows sync writes become a bottleneck.
+
+## Event Type Reference
+
+All 39 canonical event types emitted by the convoy engine.
+
+### Convoy Lifecycle
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `convoy_started` | engine.ts | `name?: string` |
+| `convoy_finished` | engine.ts | `status: string` |
+| `convoy_failed` | engine.ts | `status: string; reason?: string` |
+| `convoy_guard` | engine.ts | `checks?: string[]` |
+
+### Task Lifecycle
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `task_started` | engine.ts | `worker_id?: string` |
+| `task_done` | engine.ts | `status?: string; retries?: number; worker_id?: string` |
+| `task_failed` | engine.ts | `reason: string; worker_id?: string; gate?: string; hook?: string` |
+| `task_skipped` | engine.ts | `reason: string` |
+| `task_retried` | engine.ts | `previous_status: string` |
+| `task_waiting_input` | engine.ts | `task_id?: string; reason?: string` |
+
+### Review & Disputes
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `review_started` | engine.ts | `level: string; task_id?: string; model?: string` |
+| `review_verdict` | engine.ts | `level: string; verdict: string; tokens: number; model?: string; feedback_length?: number; budget_exceeded?: boolean; budget_downgrade?: boolean; budget_skip?: boolean; passes?: number; blocks?: number` |
+| `dispute_opened` | engine.ts | `dispute_id: string; task_id: string; agent?: string; reason?: string` |
+| `dlq_entry_created` | engine.ts | `dlq_id: string; task_id: string; agent?: string; attempts?: number` |
+
+### Drift Detection
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `drift_check_result` | engine.ts | `score?: number; threshold?: number; passed?: boolean` |
+| `drift_detected` | engine.ts | `score?: number; files?: string[]` |
+
+### Circuit Breaker
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `circuit_breaker_tripped` | engine.ts | `agent?: string; failure_count?: number; threshold?: number` |
+| `circuit_breaker_fallback` | engine.ts | `original_agent?: string; fallback_agent?: string; task_id?: string` |
+| `circuit_breaker_blocked` | engine.ts | `agent?: string; task_id?: string` |
+
+### Merge & Worktree
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `merge_conflict_detected` | engine.ts | `task_id?: string; files?: string[]` |
+| `merge_conflict_failed` | engine.ts | `task_id?: string; error?: string` |
+
+### Artifacts & Injection
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `file_injection_received` | engine.ts | `task_id?: string; from_task?: string; name?: string` |
+| `artifact_limit_reached` | engine.ts | `task_id?: string; limit?: number; current?: number` |
+
+### Agent Intelligence
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `agent_identity_captured` | engine.ts | `agent?: string; task_id?: string` |
+| `agent_identity_rejected` | engine.ts | `agent?: string; task_id?: string; reason?: string` |
+| `weak_area_skipped` | engine.ts | `agent?: string; weak_areas?: string[]; task_files?: string[]` |
+| `swarm_concurrency_update` | engine.ts | `new_concurrency?: number; reason?: string` |
+
+### Hooks
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `post_convoy_hook_failed` | engine.ts | `hook?: string; error?: string` |
+
+### Observability / Session
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `session` | engine.ts | `agent?: string; model?: string; task?: string; outcome?: string; duration_min?: number` |
+| `delegation` | engine.ts | `agent?: string; model?: string; tier?: string; mechanism?: string; outcome?: string` |
+
+### Security & Reliability
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `secret_leak_prevented` | engine.ts, events.ts | `original_type?: string; patterns?: string[]; task_id?: string; findings_count?: number; context?: string` |
+| `ndjson_write_failed` | events.ts | `original_type?: string` |
+
+### Built-in Gates
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `built_in_gate_result` | engine.ts | `gate: string; passed: boolean; output?: string; level?: string` |
+
+### Watch Mode
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `watch_started` | watch.ts | `trigger_type?: string; pid?: number` |
+| `watch_cycle_start` | watch.ts | `cycle_number?: number; triggered_by?: string` |
+| `watch_cycle_end` | watch.ts | `cycle_number?: number; status?: string` |
+| `watch_stopped` | watch.ts | `reason?: string` |
+
+### Worker Health
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `worker_killed` | health.ts | `reason?: string; worker_id?: string; task_id?: string` |
+
+### Discovered Issues
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `discovered_issue` | issues.ts | `task_id?: string; title?: string; file?: string; description?: string; severity?: string` |
+
+## Derived Metrics
+
+These are computed from raw events, not emitted directly.
+
+| Metric | Derivation |
+|--------|-----------|
+| Task duration | `task_done.timestamp - task_started.timestamp` |
+| Convoy duration | `convoy_finished.timestamp - convoy_started.timestamp` |
+| Retry rate | `COUNT(task_retried) / COUNT(task_started)` |
+| Gate failure rate | `COUNT(built_in_gate_result WHERE !passed) / COUNT(built_in_gate_result)` |
+| Review pass rate | `COUNT(review_verdict WHERE verdict='pass') / COUNT(review_verdict)` |
+| Token usage | `SUM(review_verdict.tokens)` per convoy |
+| Circuit breaker trips | `COUNT(circuit_breaker_tripped)` per agent |
+
+## Runtime Validation
+
+- `validateEventType(type)` — checks membership in `KNOWN_EVENT_TYPES` (a `Set<string>` exported from [`types.ts`](types.ts)). Unknown types trigger a `console.warn` but do not throw, preserving extensibility for custom event types.
+- `validateEventData(type, data)` — validates the `data` payload shape for known event types. Defined in [`event-schemas.ts`](event-schemas.ts). Returns `{ valid: boolean; issues?: string[] }`. Invalid payloads trigger a `console.warn` but do not block emission.
+
+Both validators are called at emit time in [`events.ts`](events.ts).
+
+## Dashboard Build Pipeline
+
+To build the dashboard with real convoy data:
+
+```sh
+# 1. Run ETL to extract data from SQLite → JSON
+npm run dashboard:etl
+
+# 2. Build the Astro dashboard (reads from public/data/*.json)
+npx astro build --root src/dashboard
+
+# 3. Serve locally (optional)
+npx astro preview --root src/dashboard
+```
+
+In CI, add these steps after tests pass:
+
+```yaml
+- run: npm run dashboard:etl
+- run: npx astro build --root src/dashboard
+```
+
+The ETL script gracefully handles missing databases — it produces empty JSON files so the dashboard renders an empty state instead of crashing.

package/src/cli/convoy/dashboard-types.ts

@@ -0,0 +1,141 @@
+export interface DashboardOverallStats {
+  total_convoys: number
+  running_convoys: number
+  successful_convoys: number
+  failed_convoys: number
+  avg_convoy_duration_sec: number | null
+  p95_convoy_duration_sec: number | null
+  total_tokens: number
+  total_cost_usd: number
+  top_agents: Array<{ agent: string; task_count: number; total_tokens: number }>
+  top_models: Array<{ model: string; task_count: number; total_tokens: number }>
+  retry_queue_count: number
+  disputed_tasks: number
+}
+
+export interface DashboardConvoySummary {
+  id: string
+  name: string
+  status: string
+  branch: string | null
+  created_at: string
+  started_at: string | null
+  finished_at: string | null
+  duration_sec: number | null
+  total_tokens: number | null
+  total_cost_usd: number | null
+  tasks_total: number
+  tasks_done: number
+  tasks_running: number
+  tasks_waiting: number
+  tasks_failed: number
+  tasks_retrying: number
+}
+
+export interface DashboardTaskSummary {
+  id: string
+  phase: number
+  agent: string
+  model: string | null
+  status: string
+  duration_sec: number | null
+  retries: number
+  files: string[]
+  total_tokens: number | null
+  cost_usd: number | null
+  review_level: string | null
+  review_verdict: string | null
+  drift_score: number | null
+}
+
+export interface DashboardConvoyDetail {
+  convoy: {
+    id: string
+    name: string
+    status: string
+    created_at: string
+    finished_at: string | null
+    branch: string | null
+    total_tokens: number | null
+    total_cost_usd: number | null
+  }
+  taskSummary: {
+    total: number
+    done: number
+    running: number
+    failed: number
+    review_blocked: number
+    disputed: number
+    reviewed: number
+    panel_reviewed: number
+    tasks_with_drift: number
+    max_drift_score: number | null
+    drift_retried: number
+  }
+  quality: {
+    reviewed_tasks: number
+    review_blocked_tasks: number
+    disputed_tasks: number
+    panel_reviews: number
+  }
+  drift: {
+    tasks_with_drift: number
+    max_drift_score: number | null
+    drift_retried_tasks: number
+  }
+  dlq_count: number
+  dlq_entries: Array<{
+    id: string
+    task_id: string
+    agent: string
+    failure_type: string
+    attempts: number
+    resolved: number
+  }>
+  artifact_count: number
+  artifacts: Array<{
+    id: string
+    name: string
+    type: string
+    task_id: string
+    created_at: string
+  }>
+  has_more_events: boolean
+  events: Array<{
+    type: string
+    task_id: string | null
+    data: unknown
+    created_at: string
+  }>
+  tasks: Array<{
+    id: string
+    phase: number
+    agent: string
+    model: string | null
+    status: string
+    retries: number
+    started_at: string | null
+    finished_at: string | null
+    total_tokens: number | null
+    cost_usd: number | null
+    review_level: string | null
+    review_verdict: string | null
+    review_tokens: number | null
+    review_model: string | null
+    panel_attempts: number | null
+    dispute_id: string | null
+    drift_score: number | null
+    drift_retried: number | null
+    files: string[] | null
+  }>
+}
+
+export interface DashboardTimelineEvent {
+  id: number
+  timestamp: string
+  type: string
+  convoy_id: string | null
+  task_id: string | null
+  worker_id: string | null
+  summary: string
+}