opencastle 0.10.7 → 0.12.0

package/src/cli/run/schema.ts

@@ -39,6 +39,12 @@ interface RawSpec {
   on_failure?: unknown
   adapter?: unknown
   tasks?: unknown
+  mode?: unknown
+  loop?: unknown
+  version?: unknown
+  defaults?: unknown
+  gates?: unknown
+  branch?: unknown
 }
 
 interface RawTask {
@@ -49,6 +55,8 @@ interface RawTask {
   depends_on?: unknown
   files?: unknown
   description?: unknown
+  model?: unknown
+  max_retries?: unknown
 }
 
 /**
@@ -90,72 +98,180 @@ export function validateSpec(spec: unknown): ValidationResult {
     errors.push('`adapter` must be a string')
   }
 
-  // Tasks
-  if (!s.tasks || !Array.isArray(s.tasks) || s.tasks.length === 0) {
-    errors.push('`tasks` is required and must be a non-empty array')
-    return { valid: false, errors }
+  // version
+  if (s.version !== undefined) {
+    if (typeof s.version !== 'number' || !Number.isInteger(s.version) || s.version !== 1) {
+      errors.push('`version` must be 1')
+    }
   }
 
-  const taskIds = new Set<string>()
-  const tasks = s.tasks as RawTask[]
-
-  for (let i = 0; i < tasks.length; i++) {
-    const task = tasks[i]
-    const prefix = `tasks[${i}]`
+  // defaults
+  if (s.defaults !== undefined) {
+    if (!s.defaults || typeof s.defaults !== 'object' || Array.isArray(s.defaults)) {
+      errors.push('`defaults` must be an object')
+    } else {
+      const d = s.defaults as Record<string, unknown>
+      if (d.timeout !== undefined && isNaN(parseTimeout(d.timeout as string))) {
+        errors.push(
+          '`defaults.timeout` must be in format: <number><s|m|h> (e.g. "10m")'
+        )
+      }
+      if (d.model !== undefined && typeof d.model !== 'string') {
+        errors.push('`defaults.model` must be a string')
+      }
+      if (d.max_retries !== undefined) {
+        const mr = Number(d.max_retries)
+        if (!Number.isInteger(mr) || mr < 0) {
+          errors.push('`defaults.max_retries` must be a non-negative integer')
+        }
+      }
+      if (d.agent !== undefined && typeof d.agent !== 'string') {
+        errors.push('`defaults.agent` must be a string')
+      }
+    }
+  }
 
-    if (!task || typeof task !== 'object') {
-      errors.push(`${prefix}: must be an object`)
-      continue
+  // gates
+  if (s.gates !== undefined) {
+    if (
+      !Array.isArray(s.gates) ||
+      !(s.gates as unknown[]).every((g) => typeof g === 'string')
+    ) {
+      errors.push('`gates` must be an array of strings')
     }
+  }
+
+  // branch
+  if (s.branch !== undefined && typeof s.branch !== 'string') {
+    errors.push('`branch` must be a string')
+  }
+
+  // mode
+  const mode = s.mode !== undefined ? s.mode : 'tasks'
+  if (mode !== 'tasks' && mode !== 'loop') {
+    errors.push('`mode` must be one of: tasks, loop')
+  }
 
-    // id
-    if (!task.id || typeof task.id !== 'string') {
-      errors.push(`${prefix}: \`id\` is required and must be a string`)
-    } else if (taskIds.has(task.id)) {
-      errors.push(`${prefix}: duplicate task id "${task.id}"`)
+  if (mode === 'loop') {
+    // Loop validation — tasks array is NOT required
+    const loop = s.loop as Record<string, unknown> | undefined
+    if (!loop || typeof loop !== 'object') {
+      errors.push('`loop` is required when mode is "loop"')
     } else {
-      taskIds.add(task.id)
+      if (!loop.prompt || typeof loop.prompt !== 'string') {
+        errors.push('`loop.prompt` is required and must be a string')
+      }
+      if (loop.max_iterations !== undefined) {
+        const mi = Number(loop.max_iterations)
+        if (!Number.isInteger(mi) || mi < 1) {
+          errors.push('`loop.max_iterations` must be an integer >= 1')
+        }
+      }
+      if (loop.timeout !== undefined) {
+        if (isNaN(parseTimeout(loop.timeout as string))) {
+          errors.push(
+            '`loop.timeout` must be in format: <number><s|m|h> (e.g. "10m")'
+          )
+        }
+      }
+      if (loop.backpressure !== undefined) {
+        if (
+          !Array.isArray(loop.backpressure) ||
+          !(loop.backpressure as unknown[]).every((b) => typeof b === 'string')
+        ) {
+          errors.push('`loop.backpressure` must be an array of strings')
+        }
+      }
+      if (loop.plan_file !== undefined && typeof loop.plan_file !== 'string') {
+        errors.push('`loop.plan_file` must be a string')
+      }
+      if (loop.model !== undefined && typeof loop.model !== 'string') {
+        errors.push('`loop.model` must be a string')
+      }
     }
-
-    // prompt
-    if (!task.prompt || typeof task.prompt !== 'string') {
-      errors.push(`${prefix}: \`prompt\` is required and must be a string`)
+  } else {
+    // Tasks mode — tasks array is required
+    if (!s.tasks || !Array.isArray(s.tasks) || s.tasks.length === 0) {
+      errors.push('`tasks` is required and must be a non-empty array')
+      return { valid: false, errors }
     }
 
-    // timeout
-    if (task.timeout !== undefined) {
-      if (isNaN(parseTimeout(task.timeout as string))) {
-        errors.push(
-          `${prefix}: \`timeout\` must be in format: <number><s|m|h> (e.g. "10m")`
-        )
+    const taskIds = new Set<string>()
+    const tasks = s.tasks as RawTask[]
+
+    for (let i = 0; i < tasks.length; i++) {
+      const task = tasks[i]
+      const prefix = `tasks[${i}]`
+
+      if (!task || typeof task !== 'object') {
+        errors.push(`${prefix}: must be an object`)
+        continue
       }
-    }
 
-    // depends_on
-    if (task.depends_on !== undefined) {
-      if (!Array.isArray(task.depends_on)) {
-        errors.push(`${prefix}: \`depends_on\` must be an array`)
+      // id
+      if (!task.id || typeof task.id !== 'string') {
+        errors.push(`${prefix}: \`id\` is required and must be a string`)
+      } else if (taskIds.has(task.id)) {
+        errors.push(`${prefix}: duplicate task id "${task.id}"`)
       } else {
-        for (const dep of task.depends_on as string[]) {
-          if (!taskIds.has(dep) && !tasks.some((t) => t && t.id === dep)) {
-            errors.push(
-              `${prefix}: \`depends_on\` references unknown task "${dep}"`
-            )
+        taskIds.add(task.id)
+      }
+
+      // prompt
+      if (!task.prompt || typeof task.prompt !== 'string') {
+        errors.push(`${prefix}: \`prompt\` is required and must be a string`)
+      }
+
+      // timeout
+      if (task.timeout !== undefined) {
+        if (isNaN(parseTimeout(task.timeout as string))) {
+          errors.push(
+            `${prefix}: \`timeout\` must be in format: <number><s|m|h> (e.g. "10m")`
+          )
+        }
+      }
+
+      // depends_on
+      if (task.depends_on !== undefined) {
+        if (!Array.isArray(task.depends_on)) {
+          errors.push(`${prefix}: \`depends_on\` must be an array`)
+        } else {
+          for (const dep of task.depends_on as string[]) {
+            if (!taskIds.has(dep) && !tasks.some((t) => t && t.id === dep)) {
+              errors.push(
+                `${prefix}: \`depends_on\` references unknown task "${dep}"`
+              )
+            }
           }
         }
       }
-    }
 
-    // files
-    if (task.files !== undefined && !Array.isArray(task.files)) {
-      errors.push(`${prefix}: \`files\` must be an array`)
+      // files
+      if (task.files !== undefined && !Array.isArray(task.files)) {
+        errors.push(`${prefix}: \`files\` must be an array`)
+      }
+
+      // model
+      if (task.model !== undefined && typeof task.model !== 'string') {
+        errors.push(`${prefix}: \`model\` must be a string`)
+      }
+
+      // max_retries
+      if (task.max_retries !== undefined) {
+        const mr = Number(task.max_retries)
+        if (!Number.isInteger(mr) || mr < 0) {
+          errors.push(
+            `${prefix}: \`max_retries\` must be a non-negative integer`
+          )
+        }
+      }
     }
-  }
 
-  // DAG cycle detection
-  if (errors.length === 0) {
-    const cycleErr = detectCycles(tasks as Array<{ id: string; depends_on?: string[] }>)
-    if (cycleErr) errors.push(cycleErr)
+    // DAG cycle detection
+    if (errors.length === 0) {
+      const cycleErr = detectCycles(tasks as Array<{ id: string; depends_on?: string[] }>)
+      if (cycleErr) errors.push(cycleErr)
+    }
   }
 
   return { valid: errors.length === 0, errors }
@@ -214,19 +330,53 @@ export function applyDefaults(spec: Record<string, unknown>): TaskSpec {
   s.on_failure = (s.on_failure as string) || 'continue'
   // Leave adapter empty so run.ts can auto-detect the best available CLI
   s.adapter = (s.adapter as string) || ''
-
-  const tasks = s.tasks as Array<Record<string, unknown>>
-  for (const task of tasks) {
-    task.agent = (task.agent as string) || 'developer'
-    task.timeout = (task.timeout as string) || '30m'
-    task.depends_on = (task.depends_on as string[]) || []
-    task.files = (task.files as string[]) || []
-    task.description = (task.description as string) || (task.id as string)
+  s.mode = (s.mode as string) || 'tasks'
+
+  if (s.mode === 'loop') {
+    const loop = ((s.loop ?? {}) as Record<string, unknown>)
+    loop.max_iterations = loop.max_iterations !== undefined ? Number(loop.max_iterations) : 20
+    loop.plan_file = (loop.plan_file as string) || 'IMPLEMENTATION_PLAN.md'
+    loop.timeout = (loop.timeout as string) || '10m'
+    s.loop = loop
+  } else {
+    const tasks = s.tasks as Array<Record<string, unknown>>
+    const d =
+      s.version === 1 && s.defaults
+        ? (s.defaults as Record<string, unknown>)
+        : {}
+    for (const task of tasks) {
+      task.agent =
+        (task.agent as string) || (d.agent as string | undefined) || 'developer'
+      task.timeout =
+        (task.timeout as string) ||
+        (d.timeout as string | undefined) ||
+        '30m'
+      task.depends_on = (task.depends_on as string[]) || []
+      task.files = (task.files as string[]) || []
+      task.description = (task.description as string) || (task.id as string)
+      // model: task-level overrides defaults (no hardcoded fallback)
+      if (task.model === undefined && d.model !== undefined) {
+        task.model = d.model
+      }
+      // max_retries: task-level overrides defaults, fallback to 1
+      if (task.max_retries === undefined) {
+        task.max_retries =
+          d.max_retries !== undefined ? Number(d.max_retries) : 1
+      }
+    }
   }
 
   return s as unknown as TaskSpec
 }
 
+/**
+ * Returns true if the spec uses the Convoy Engine enhanced format (version: 1).
+ */
+export function isConvoySpec(spec: unknown): boolean {
+  if (!spec || typeof spec !== 'object') return false
+  return (spec as Record<string, unknown>).version === 1
+}
+
 /**
  * Read, parse, validate, and return a typed task spec from a YAML file.
  * @throws If file cannot be read, parsed, or spec is invalid

package/src/cli/run.ts

@@ -1,3 +1,4 @@
+import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { parseTaskSpec } from './run/schema.js'
 import { createExecutor, buildPhases } from './run/executor.js'
@@ -9,14 +10,17 @@ const HELP = `
   opencastle run [options]
 
   Process a task queue from a spec file, delegating to AI agents autonomously.
+  Supports two modes: tasks (default phase-based execution) and loop (iterative Ralph Loop).
 
   Options:
     --file, -f <path>        Task spec file (default: opencastle.tasks.yml)
     --dry-run                Show execution plan without running
-    --concurrency, -c <n>    Override max parallel tasks
+    --concurrency, -c <n>    Override max parallel tasks (tasks mode)
     --adapter, -a <name>     Override agent runtime adapter
     --report-dir <path>      Where to write run reports (default: .opencastle/runs)
     --verbose                Show full agent output
+    --mode <name>            Execution mode: tasks | loop
+    --max-iterations <n>     Override max loop iterations (loop mode)
     --help, -h               Show this help
 `
 
@@ -32,6 +36,8 @@ function parseArgs(args: string[]): RunOptions {
     reportDir: null,
     verbose: false,
     help: false,
+    maxIterations: null,
+    mode: null,
   }
 
   for (let i = 0; i < args.length; i++) {
@@ -73,6 +79,26 @@ function parseArgs(args: string[]): RunOptions {
       case '--verbose':
         opts.verbose = true
         break
+      case '--max-iterations': {
+        if (i + 1 >= args.length) { console.error('  \u2717 --max-iterations requires a number'); process.exit(1) }
+        const val = parseInt(args[++i], 10)
+        if (!Number.isFinite(val) || val < 1) {
+          console.error(`  \u2717 --max-iterations must be an integer >= 1`)
+          process.exit(1)
+        }
+        opts.maxIterations = val
+        break
+      }
+      case '--mode': {
+        if (i + 1 >= args.length) { console.error('  \u2717 --mode requires a name'); process.exit(1) }
+        const modeVal = args[++i]
+        if (modeVal !== 'tasks' && modeVal !== 'loop') {
+          console.error(`  \u2717 --mode must be one of: tasks, loop`)
+          process.exit(1)
+        }
+        opts.mode = modeVal
+        break
+      }
       default:
         console.error(`  ✗ Unknown option: ${arg}`)
         console.log(HELP)
@@ -102,6 +128,7 @@ export default async function run({ args }: CliContext): Promise<void> {
   if (opts.concurrency !== null) spec.concurrency = opts.concurrency
   if (opts.adapter !== null) spec.adapter = opts.adapter
   if (opts.verbose) spec._verbose = true
+  if (opts.mode !== null) spec.mode = opts.mode as 'tasks' | 'loop'
 
   // ── Auto-detect adapter if not specified ─────────────────────
   let detectionFailed = false
@@ -117,9 +144,25 @@ export default async function run({ args }: CliContext): Promise<void> {
   }
 
   // ── Dry run ──────────────────────────────────────────────────
-  const phases = buildPhases(spec.tasks)
-
   if (opts.dryRun) {
+    if (spec.mode === 'loop') {
+      const loop = spec.loop!
+      console.log(`\n  \uD83C\uDFF0 Loop Plan: ${spec.name}`)
+      console.log(`  Mode: loop`)
+      console.log(`  Prompt: ${loop.prompt}`)
+      console.log(`  Max iterations: ${loop.max_iterations}`)
+      console.log(`  Timeout: ${loop.timeout}`)
+      if (loop.plan_file) console.log(`  Plan file: ${loop.plan_file}`)
+      if (loop.model) console.log(`  Model: ${loop.model}`)
+      if (loop.backpressure?.length) {
+        console.log(`  Backpressure:`)
+        for (const cmd of loop.backpressure) {
+          console.log(`    - ${cmd}`)
+        }
+      }
+      return
+    }
+    const phases = buildPhases(spec.tasks!)
     printExecutionPlan(spec, phases)
     return
   }
@@ -164,8 +207,42 @@ export default async function run({ args }: CliContext): Promise<void> {
   }
 
   // ── Execute ──────────────────────────────────────────────────
-  console.log(`\n  🏰 OpenCastle Run: ${spec.name}`)
-  console.log(`  Adapter: ${adapter.name} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks.length}`)
+  if (spec.mode === 'loop') {
+    const { createLoopExecutor } = await import('./run/loop-executor.js')
+    const { createLoopReporter } = await import('./run/loop-reporter.js')
+
+    if (opts.maxIterations !== null && spec.loop) {
+      spec.loop.max_iterations = opts.maxIterations
+    }
+
+    const promptPath = resolve(process.cwd(), spec.loop!.prompt)
+    try {
+      await readFile(promptPath)
+    } catch {
+      console.error(`  \u2717 Prompt file not found: ${spec.loop!.prompt}`)
+      process.exit(1)
+    }
+
+    console.log(`\n  \uD83C\uDFF0 OpenCastle Loop: ${spec.name}`)
+    console.log(`  Adapter: ${adapter.name} | Max iterations: ${spec.loop!.max_iterations} | Timeout: ${spec.loop!.timeout}`)
+    if (spec.loop!.backpressure?.length) {
+      console.log(`  Backpressure: ${spec.loop!.backpressure.join(', ')}`)
+    }
+
+    const loopReporter = createLoopReporter(spec.name, {
+      reportDir: opts.reportDir ? resolve(process.cwd(), opts.reportDir) : undefined,
+      verbose: opts.verbose,
+    })
+
+    const loopExecutor = createLoopExecutor(spec, adapter, loopReporter)
+    const loopReport = await loopExecutor.run()
+
+    const failed = loopReport.stoppedReason === 'error' || loopReport.stoppedReason === 'backpressure-fail'
+    process.exit(failed ? 1 : 0)
+  }
+
+  console.log(`\n  \uD83C\uDFF0 OpenCastle Run: ${spec.name}`)
+  console.log(`  Adapter: ${adapter.name} | Concurrency: ${spec.concurrency} | Tasks: ${spec.tasks!.length}`)
 
   const reporter = createReporter(spec, {
     reportDir: opts.reportDir

package/src/cli/types.ts

@@ -126,14 +126,48 @@ export const IDE_LABELS: Record<IdeChoice, string> = {
 
 // ── Run command types ──────────────────────────────────────────
 
+/** Default values merged into each task for Convoy Engine (version: 1) specs. */
+export interface TaskDefaults {
+  timeout?: string;
+  model?: string;
+  max_retries?: number;
+  agent?: string;
+}
+
+/** Loop execution configuration. */
+export interface LoopConfig {
+  /** Maximum number of agent iterations (default 20). */
+  max_iterations: number;
+  /** Path to the prompt file read each iteration. */
+  prompt: string;
+  /** Path to the plan file (default 'IMPLEMENTATION_PLAN.md'). */
+  plan_file?: string;
+  /** Per-iteration timeout (default '10m'). */
+  timeout: string;
+  /** Model override for loop sessions. */
+  model?: string;
+  /** Shell commands that must exit 0 after each iteration. */
+  backpressure?: string[];
+}
+
 /** Validated task spec from YAML. */
 export interface TaskSpec {
   name: string;
   concurrency: number;
   on_failure: 'continue' | 'stop';
   adapter: string;
-  tasks: Task[];
+  tasks?: Task[];
+  mode?: 'tasks' | 'loop';
+  loop?: LoopConfig;
   _verbose?: boolean;
+  /** Spec schema version (1 for Convoy Engine format). */
+  version?: number;
+  /** Worker defaults merged into each task (Convoy Engine). */
+  defaults?: TaskDefaults;
+  /** Shell commands run after all tasks complete; each must exit 0. */
+  gates?: string[];
+  /** Git feature branch name. */
+  branch?: string;
 }
 
 /** A single task in the spec. */
@@ -146,6 +180,10 @@ export interface Task {
   files: string[];
   description: string;
   _process?: ChildProcess;
+  /** Model override for this task. */
+  model?: string;
+  /** Max retry attempts (default: 1). */
+  max_retries: number;
 }
 
 /** Task execution status. */
@@ -231,6 +269,8 @@ export interface RunOptions {
   reportDir: string | null;
   verbose: boolean;
   help: boolean;
+  maxIterations: number | null;
+  mode: string | null;
 }
 
 /** Validation result. */
@@ -250,3 +290,49 @@ export interface Executor {
   run(): Promise<RunReport>;
   getPhases(): Task[][];
 }
+
+// ── Loop executor types ────────────────────────────────────────
+
+/** Result of a single backpressure command run. */
+export interface BackpressureResult {
+  command: string;
+  exitCode: number;
+  output: string;
+  passed: boolean;
+}
+
+/** Result of a single loop iteration. */
+export interface LoopIterationResult {
+  iteration: number;
+  status: 'done' | 'failed' | 'backpressure-fail';
+  duration: number;
+  output: string;
+  backpressureResults?: BackpressureResult[];
+}
+
+/** Final report produced by the loop executor. */
+export interface LoopRunReport {
+  name: string;
+  mode: 'loop';
+  startedAt: string;
+  completedAt: string;
+  duration: string;
+  totalIterations: number;
+  completedIterations: number;
+  stoppedReason: 'max-iterations' | 'plan-empty' | 'backpressure-fail' | 'user-abort' | 'error';
+  iterations: LoopIterationResult[];
+}
+
+/** Reporter interface for loop execution progress. */
+export interface LoopReporter {
+  onIterationStart(iteration: number, maxIterations: number): void;
+  onIterationDone(iteration: number, result: LoopIterationResult): void;
+  onBackpressureStart(command: string): void;
+  onBackpressureResult(result: BackpressureResult): void;
+  onComplete(report: LoopRunReport): Promise<void>;
+}
+
+/** Executor for loop-mode run specs. */
+export interface LoopExecutor {
+  run(): Promise<LoopRunReport>;
+}

package/src/cli/update.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
-import { readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { readFile, appendFile, rename } from 'node:fs/promises'
 import { readManifest, writeManifest } from './manifest.js'
 import { multiselect, confirm, closePrompts, c } from './prompt.js'
 import { isLegacyStack, migrateStackConfig, IDE_LABELS } from './types.js'
@@ -247,6 +248,9 @@ export default async function update({
     }
   }
 
+  // ── Migrate legacy log files ────────────────────────────────────
+  await migrateLegacyLogs(projectRoot)
+
   // ── Update manifest ─────────────────────────────────────────────
   if (hasVersionUpdate) manifest.version = pkg.version
   manifest.ides = ides
@@ -322,6 +326,63 @@ export default async function update({
   closePrompts()
 }
 
+async function migrateLegacyLogs(projectRoot: string): Promise<void> {
+  const logsDir = resolve(projectRoot, '.github', 'customizations', 'logs')
+  if (!existsSync(logsDir)) return
+
+  const typeMap: Record<string, string> = {
+    'sessions.ndjson': 'session',
+    'delegations.ndjson': 'delegation',
+    'reviews.ndjson': 'review',
+    'panels.ndjson': 'panel',
+    'disputes.ndjson': 'dispute',
+  }
+
+  const eventsFile = resolve(logsDir, 'events.ndjson')
+  let totalMigrated = 0
+
+  for (const [filename, type] of Object.entries(typeMap)) {
+    const filePath = resolve(logsDir, filename)
+    if (!existsSync(filePath)) continue
+
+    let content: string
+    try {
+      content = await readFile(filePath, 'utf8')
+    } catch {
+      continue
+    }
+
+    const lines = content.split('\n').filter((line) => line.trim() !== '')
+    if (lines.length === 0) continue
+
+    const migratedLines: string[] = []
+    for (const line of lines) {
+      try {
+        const record = JSON.parse(line) as Record<string, unknown>
+        if (!record['type']) {
+          record['type'] = type
+        }
+        migratedLines.push(JSON.stringify(record))
+      } catch {
+        console.warn(`  ${c.yellow('⚠')}  Skipping malformed JSON line in ${filename}`)
+      }
+    }
+
+    if (migratedLines.length > 0) {
+      await appendFile(eventsFile, migratedLines.join('\n') + '\n', 'utf8')
+      totalMigrated += migratedLines.length
+    }
+
+    await rename(filePath, filePath + '.migrated')
+  }
+
+  if (totalMigrated > 0) {
+    console.log(
+      `  ${c.green('✓')} Migrated ${c.bold(String(totalMigrated))} records from legacy log files to events.ndjson`
+    )
+  }
+}
+
 function sameSet(a: Set<string>, b: Set<string>): boolean {
   if (a.size !== b.size) return false
   for (const item of a) {