opencastle 0.10.7 → 0.11.0

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,13 +126,31 @@ export const IDE_LABELS: Record<IdeChoice, string> = {
 
 // ── Run command types ──────────────────────────────────────────
 
+/** 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;
 }
 
@@ -231,6 +249,8 @@ export interface RunOptions {
   reportDir: string | null;
   verbose: boolean;
   help: boolean;
+  maxIterations: number | null;
+  mode: string | null;
 }
 
 /** Validation result. */
@@ -250,3 +270,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) {

package/src/dashboard/dist/index.html

@@ -1059,29 +1059,28 @@ Export
   // ── Export ─────────────────────────────────────────────────
 
   function exportData() {
-    const data = {
-      exported_at: new Date().toISOString(),
-      sessions: rawSessions,
-      delegations: rawDelegations,
-      panels: rawPanels,
-      reviews: rawReviews,
-    };
-    const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
+    const events = [
+      ...rawSessions,
+      ...rawDelegations,
+      ...rawPanels,
+      ...rawReviews,
+    ].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    const blob = new Blob([events.map((e) => JSON.stringify(e)).join('\n') + '\n'], { type: 'application/x-ndjson' });
     const url = URL.createObjectURL(blob);
     const a = document.createElement('a');
     a.href = url;
-    a.download = 'opencastle-dashboard-' + new Date().toISOString().slice(0, 10) + '.json';
+    a.download = 'opencastle-events-' + new Date().toISOString().slice(0, 10) + '.ndjson';
     a.click();
     URL.revokeObjectURL(url);
   }
 
   async function main() {
-    const [sessions, delegations, panels, reviews] = await Promise.all([
-      loadNdjson(base + 'data/sessions.ndjson'),
-      loadNdjson(base + 'data/delegations.ndjson'),
-      loadNdjson(base + 'data/panels.ndjson'),
-      loadNdjson(base + 'data/reviews.ndjson'),
-    ]);
+    const events = await loadNdjson(base + 'data/events.ndjson');
+
+    const sessions = events.filter((e) => e.type === 'session');
+    const delegations = events.filter((e) => e.type === 'delegation');
+    const panels = events.filter((e) => e.type === 'panel');
+    const reviews = events.filter((e) => e.type === 'review');
 
     rawSessions = sessions;
     rawDelegations = delegations;

package/src/dashboard/node_modules/.vite/deps/_metadata.json

@@ -1,25 +1,25 @@
 {
-  "hash": "314c051f",
+  "hash": "87401706",
   "configHash": "30f8ea04",
-  "lockfileHash": "153a5e79",
-  "browserHash": "9424a639",
+  "lockfileHash": "56be8082",
+  "browserHash": "8ccc6e37",
   "optimized": {
     "astro > cssesc": {
       "src": "../../../../../node_modules/cssesc/cssesc.js",
       "file": "astro___cssesc.js",
-      "fileHash": "de6d329b",
+      "fileHash": "7e157996",
       "needsInterop": true
     },
     "astro > aria-query": {
       "src": "../../../../../node_modules/aria-query/lib/index.js",
       "file": "astro___aria-query.js",
-      "fileHash": "280e2b7f",
+      "fileHash": "021f979d",
       "needsInterop": true
     },
     "astro > axobject-query": {
       "src": "../../../../../node_modules/axobject-query/lib/index.js",
       "file": "astro___axobject-query.js",
-      "fileHash": "3aee3dc0",
+      "fileHash": "f1a04609",
       "needsInterop": true
     }
   },

package/src/dashboard/scripts/generate-seed-data.ts

@@ -2,15 +2,13 @@
 /**
  * Generate realistic seed data for the Agent Dashboard.
  *
- * Writes NDJSON files to docs/ai-agents/logs/:
- *   - sessions.ndjson   (50 records)
- *   - delegations.ndjson (35 records)
- *   - panels.ndjson      (12 records + preserves existing)
+ * Writes a single NDJSON file to the configured logs directory:
+ *   - events.ndjson  (50 session + 35 delegation + 12 panel records, sorted by timestamp)
  *
  * Usage: npx tsx opencastle/src/dashboard/scripts/generate-seed-data.ts
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 
 const REPO_ROOT = join(__dirname, '..', '..', '..', '..');
@@ -156,6 +154,7 @@ const END_DATE = new Date('2026-02-25T18:00:00Z');
 // --- Generate Sessions ---
 
 interface SessionRecord {
+  type: 'session';
   timestamp: string;
   agent: string;
   model: string;
@@ -180,6 +179,7 @@ function generateSessions(count: number): SessionRecord[] {
     const discoveries = rng.next() > 0.7 ? [rng.pick(TASK_DESCRIPTIONS)] : [];
 
     records.push({
+      type: 'session',
       timestamp: generateTimestamp(i, count, START_DATE, END_DATE),
       agent: rng.pick(AGENTS),
       model: rng.pick(MODELS),
@@ -199,6 +199,7 @@ function generateSessions(count: number): SessionRecord[] {
 // --- Generate Delegations ---
 
 interface DelegationRecord {
+  type: 'delegation';
   timestamp: string;
   session_id: string;
   agent: string;
@@ -220,9 +221,9 @@ function generateDelegations(count: number): DelegationRecord[] {
     const outcome = outcomeRoll < 0.75 ? 'success' : outcomeRoll < 0.9 ? 'partial' : 'failed';
 
     records.push({
+      type: 'delegation',
       timestamp: generateTimestamp(i, count, START_DATE, END_DATE),
-      session_id: `feat/${issue.toLowerCase()}`,
-      agent: rng.pick(AGENTS),
+      session_id: `feat/${issue.toLowerCase()}`,      agent: rng.pick(AGENTS),
       model: rng.pick(MODELS),
       tier: rng.weighted(TIERS),
       mechanism: rng.next() < 0.6 ? 'sub-agent' : 'background',
@@ -239,6 +240,7 @@ function generateDelegations(count: number): DelegationRecord[] {
 // --- Generate Panels ---
 
 interface PanelRecord {
+  type: 'panel';
   timestamp: string;
   panel_key: string;
   verdict: string;
@@ -264,6 +266,7 @@ function generatePanels(count: number): PanelRecord[] {
     const issue = rng.pick(TRACKER_ISSUES);
 
     records.push({
+      type: 'panel',
       timestamp: generateTimestamp(i, count, START_DATE, END_DATE),
       panel_key: panelKey,
       verdict: isPass ? 'pass' : 'block',
@@ -287,50 +290,27 @@ function generatePanels(count: number): PanelRecord[] {
 function main() {
   mkdirSync(LOGS_DIR, { recursive: true });
 
-  // Read existing panel records to preserve them
-  const panelsPath = join(LOGS_DIR, 'panels.ndjson');
-  let existingPanels: string[] = [];
-  try {
-    const content = readFileSync(panelsPath, 'utf-8').trim();
-    if (content) {
-      existingPanels = content.split('\n').filter(Boolean);
-    }
-  } catch {
-    // File doesn't exist yet
-  }
-
   // Generate data
   const sessions = generateSessions(50);
   const delegations = generateDelegations(35);
   const panels = generatePanels(12);
 
-  // Write sessions
-  const sessionsPath = join(LOGS_DIR, 'sessions.ndjson');
-  writeFileSync(sessionsPath, sessions.map((r) => JSON.stringify(r)).join('\n') + '\n');
-  console.log(`Wrote ${sessions.length} session records to ${sessionsPath}`);
-
-  // Write delegations
-  const delegationsPath = join(LOGS_DIR, 'delegations.ndjson');
-  writeFileSync(delegationsPath, delegations.map((r) => JSON.stringify(r)).join('\n') + '\n');
-  console.log(`Wrote ${delegations.length} delegation records to ${delegationsPath}`);
-
-  // Write panels (preserve existing + add new, sorted by timestamp)
-  const allPanelLines = [
-    ...existingPanels,
-    ...panels.map((r) => JSON.stringify(r)),
-  ];
-  // Parse and sort all panel records by timestamp
-  const allPanelRecords = allPanelLines
-    .map((line) => JSON.parse(line))
-    .sort((a: { timestamp: string }, b: { timestamp: string }) => a.timestamp.localeCompare(b.timestamp));
-  writeFileSync(panelsPath, allPanelRecords.map((r: unknown) => JSON.stringify(r)).join('\n') + '\n');
-  console.log(`Wrote ${allPanelRecords.length} panel records to ${panelsPath} (${existingPanels.length} existing + ${panels.length} new)`);
+  // Merge and sort all events by timestamp
+  type AnyRecord = SessionRecord | DelegationRecord | PanelRecord;
+  const allEvents: AnyRecord[] = [...sessions, ...delegations, ...panels]
+    .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+  // Write single events.ndjson
+  const eventsPath = join(LOGS_DIR, 'events.ndjson');
+  writeFileSync(eventsPath, allEvents.map((r) => JSON.stringify(r)).join('\n') + '\n');
+  console.log(`Wrote ${allEvents.length} event records to ${eventsPath}`);
 
   // Summary
   console.log('\n--- Seed Data Summary ---');
   console.log(`Sessions:    ${sessions.length}`);
   console.log(`Delegations: ${delegations.length}`);
-  console.log(`Panels:      ${allPanelRecords.length} (${existingPanels.length} existing + ${panels.length} generated)`);
+  console.log(`Panels:      ${panels.length}`);
+  console.log(`Total:       ${allEvents.length}`);
 
   // Outcome distribution
   const sessionOutcomes = sessions.reduce<Record<string, number>>((acc, s) => {
@@ -345,10 +325,10 @@ function main() {
   }, {});
   console.log(`Delegation tiers: ${JSON.stringify(tierDist)}`);
 
-  const panelVerdicts = allPanelRecords.reduce((acc: Record<string, number>, p: { verdict: string }) => {
+  const panelVerdicts = panels.reduce<Record<string, number>>((acc, p) => {
     acc[p.verdict] = (acc[p.verdict] || 0) + 1;
     return acc;
-  }, {} as Record<string, number>);
+  }, {});
   console.log(`Panel verdicts: ${JSON.stringify(panelVerdicts)}`);
 }