oxe-cc 1.0.0 → 1.2.1

package/packages/runtime/src/scheduler/agent-roles.ts

@@ -0,0 +1,109 @@
+import type { TaskResult } from './scheduler';
+
+export type AgentRole = 'planner' | 'executor' | 'reviewer' | 'verifier';
+
+export interface AgentBudget {
+  max_tokens: number;
+  max_time_ms: number;
+  max_retries: number;
+  consumed_tokens: number;
+  consumed_time_ms: number;
+  consumed_retries: number;
+}
+
+export interface CooperativeHandoff {
+  handoff_id: string;
+  from_agent_id: string;
+  to_agent_id: string;
+  from_role: AgentRole;
+  to_role: AgentRole;
+  work_item_id: string;
+  context_pack_ref: string | null;
+  transferred_at: string;
+}
+
+export interface AgentActionLog {
+  agent_id: string;
+  role: AgentRole;
+  work_item_id: string;
+  action: 'execute' | 'verify' | 'review' | 'plan';
+  result: 'success' | 'failure';
+  duration_ms: number;
+  timestamp: string;
+}
+
+export function createBudget(
+  opts: Partial<Omit<AgentBudget, 'consumed_tokens' | 'consumed_time_ms' | 'consumed_retries'>> = {}
+): AgentBudget {
+  return {
+    max_tokens: opts.max_tokens ?? Infinity,
+    max_time_ms: opts.max_time_ms ?? Infinity,
+    max_retries: opts.max_retries ?? Infinity,
+    consumed_tokens: 0,
+    consumed_time_ms: 0,
+    consumed_retries: 0,
+  };
+}
+
+export function consumeBudget(
+  budget: AgentBudget,
+  delta: { tokens?: number; time_ms?: number; retries?: number }
+): AgentBudget {
+  return {
+    ...budget,
+    consumed_tokens: budget.consumed_tokens + (delta.tokens ?? 0),
+    consumed_time_ms: budget.consumed_time_ms + (delta.time_ms ?? 0),
+    consumed_retries: budget.consumed_retries + (delta.retries ?? 0),
+  };
+}
+
+export function isBudgetExhausted(budget: AgentBudget): boolean {
+  return (
+    budget.consumed_tokens >= budget.max_tokens ||
+    budget.consumed_time_ms >= budget.max_time_ms ||
+    budget.consumed_retries >= budget.max_retries
+  );
+}
+
+export function buildHandoff(opts: {
+  from_agent_id: string;
+  to_agent_id: string;
+  from_role: AgentRole;
+  to_role: AgentRole;
+  work_item_id: string;
+  context_pack_ref?: string | null;
+}): CooperativeHandoff {
+  return {
+    handoff_id: `hoff-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+    from_agent_id: opts.from_agent_id,
+    to_agent_id: opts.to_agent_id,
+    from_role: opts.from_role,
+    to_role: opts.to_role,
+    work_item_id: opts.work_item_id,
+    context_pack_ref: opts.context_pack_ref ?? null,
+    transferred_at: new Date().toISOString(),
+  };
+}
+
+// ─── ArbitrationEngine ────────────────────────────────────────────────────────
+
+export class ArbitrationEngine {
+  /**
+   * Choose the best result from multiple competing agents.
+   * Prefers success; among successes prefers more evidence; falls back to first.
+   */
+  arbitrate(results: Array<{ agent_id: string; result: TaskResult }>): TaskResult {
+    if (results.length === 0) {
+      return { success: false, failure_class: null, evidence: [], output: 'no results to arbitrate' };
+    }
+
+    const successes = results.filter((r) => r.result.success);
+    if (successes.length === 0) {
+      return results[0].result;
+    }
+
+    // Among successes, prefer the one with most evidence
+    successes.sort((a, b) => b.result.evidence.length - a.result.evidence.length);
+    return successes[0].result;
+  }
+}

package/packages/runtime/src/scheduler/index.ts

@@ -1 +1,4 @@
 export * from './scheduler';
+export * from './run-journal';
+export * from './agent-registry';
+export * from './agent-roles';

package/packages/runtime/src/scheduler/multi-agent-coordinator.ts

@@ -4,6 +4,8 @@ import type { WorkspaceManager } from '../workspace/workspace-manager';
 import type { TaskExecutor, TaskResult, SchedulerContext } from './scheduler';
 import { Scheduler } from './scheduler';
 import type { WorkspaceLease } from '../models/workspace';
+import { buildHandoff } from './agent-roles';
+import type { CooperativeHandoff } from './agent-roles';
 
 export type CoordinationMode = 'parallel' | 'competitive' | 'cooperative';
 
@@ -31,6 +33,7 @@ export interface CoordinationResult {
   failed: string[];
   blocked: string[];
   agent_results: Array<{ agent_id: string; completed: string[]; failed: string[] }>;
+  handoffs?: CooperativeHandoff[];
 }
 
 // ─── Parallel mode ───────────────────────────────────────────────────────────
@@ -194,6 +197,108 @@ async function competeTwoAgents(
   return winner;
 }
 
+// ─── Cooperative mode ────────────────────────────────────────────────────────
+// planner (agent[0]) does a dry-run to collect context, then hands off to
+// executor (agent[1]) which performs the real run. Handoffs are recorded.
+
+async function runCooperative(
+  graph: ExecutionGraph,
+  opts: CoordinationOptions
+): Promise<CoordinationResult> {
+  if (opts.agents.length < 2) {
+    throw new Error('Cooperative mode requires at least 2 agents');
+  }
+  const [planner, executor] = opts.agents;
+  const { projectRoot, sessionId, runId } = opts;
+  const handoffs: CooperativeHandoff[] = [];
+
+  appendEvent(projectRoot, sessionId, {
+    type: 'RunStarted',
+    run_id: runId,
+    payload: { mode: 'cooperative', planner: planner.id, executor: executor.id },
+  });
+
+  const completed: string[] = [];
+  const failed: string[] = [];
+
+  for (const wave of graph.waves) {
+    for (const nodeId of wave.node_ids) {
+      const node = graph.nodes.get(nodeId)!;
+
+      // Phase 1: planner allocates workspace + signals readiness (no output used)
+      const planAlloc = await planner.workspaceManager.allocate({
+        work_item_id: nodeId,
+        attempt_number: 1,
+        strategy: node.workspace_strategy,
+        mutation_scope: node.mutation_scope,
+      });
+      await planner.workspaceManager.dispose(planAlloc.workspace_id).catch(() => {});
+
+      const handoff = buildHandoff({
+        from_agent_id: planner.id,
+        to_agent_id: executor.id,
+        from_role: 'planner',
+        to_role: 'executor',
+        work_item_id: nodeId,
+        context_pack_ref: null,
+      });
+      handoffs.push(handoff);
+
+      appendEvent(projectRoot, sessionId, {
+        type: 'AttemptStarted',
+        run_id: runId,
+        work_item_id: nodeId,
+        payload: { mode: 'cooperative', handoff_id: handoff.handoff_id },
+      });
+
+      // Phase 2: executor performs the real task
+      const execAlloc = await executor.workspaceManager.allocate({
+        work_item_id: nodeId,
+        attempt_number: 1,
+        strategy: node.workspace_strategy,
+        mutation_scope: node.mutation_scope,
+      });
+
+      let result: TaskResult;
+      try {
+        result = await executor.executor.execute(node, execAlloc, runId, 1);
+      } catch (e) {
+        result = { success: false, failure_class: 'env', evidence: [], output: String(e) };
+      }
+      await executor.workspaceManager.dispose(execAlloc.workspace_id).catch(() => {});
+
+      if (result.success) {
+        completed.push(nodeId);
+        appendEvent(projectRoot, sessionId, { type: 'WorkItemCompleted', run_id: runId, work_item_id: nodeId, payload: { mode: 'cooperative' } });
+      } else {
+        failed.push(nodeId);
+        appendEvent(projectRoot, sessionId, { type: 'WorkItemBlocked', run_id: runId, work_item_id: nodeId, payload: { mode: 'cooperative', failure_class: result.failure_class } });
+        break;
+      }
+    }
+    if (failed.length > 0) break;
+  }
+
+  appendEvent(projectRoot, sessionId, {
+    type: 'RunCompleted',
+    run_id: runId,
+    payload: { mode: 'cooperative', completed: completed.length, failed: failed.length },
+  });
+
+  return {
+    mode: 'cooperative',
+    run_id: runId,
+    completed,
+    failed,
+    blocked: [],
+    agent_results: [
+      { agent_id: planner.id, completed: [], failed: [] },
+      { agent_id: executor.id, completed, failed },
+    ],
+    handoffs,
+  };
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 export class MultiAgentCoordinator {
@@ -201,10 +306,7 @@ export class MultiAgentCoordinator {
     switch (opts.mode) {
       case 'parallel': return runParallel(graph, opts);
       case 'competitive': return runCompetitive(graph, opts);
-      case 'cooperative':
-        // Cooperative mode: planner (agent[0]) prepares context,
-        // executor (agent[1]) implements. For R3, delegate to sequential parallel.
-        return runParallel(graph, { ...opts, mode: 'parallel' });
+      case 'cooperative': return runCooperative(graph, opts);
       default:
         throw new Error(`Unknown coordination mode: ${opts.mode}`);
     }

package/packages/runtime/src/scheduler/run-journal.ts

@@ -0,0 +1,62 @@
+import path from 'path';
+import fs from 'fs';
+import type { RunResult } from './scheduler';
+
+export interface RunJournal {
+  run_id: string;
+  paused_at: string | null;
+  cancelled: boolean;
+  eligible_work_items: string[];
+  completed_work_items: string[];
+  failed_work_items: string[];
+  blocked_work_items: string[];
+  pending_gates: string[];
+  replay_cursor: string | null;
+  scheduler_state: 'running' | 'paused' | 'cancelled' | 'completed';
+  partial_result: Omit<RunResult, 'status'> | null;
+}
+
+function journalPath(projectRoot: string, runId: string): string {
+  return path.join(projectRoot, '.oxe', 'runs', runId, 'journal.json');
+}
+
+export function saveJournal(projectRoot: string, runId: string, journal: RunJournal): void {
+  const p = journalPath(projectRoot, runId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(journal, null, 2), 'utf8');
+}
+
+export function loadJournal(projectRoot: string, runId: string): RunJournal | null {
+  const p = journalPath(projectRoot, runId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as RunJournal;
+  } catch {
+    return null;
+  }
+}
+
+export function deleteJournal(projectRoot: string, runId: string): void {
+  const p = journalPath(projectRoot, runId);
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    // ignore if not found
+  }
+}
+
+export function createJournal(runId: string): RunJournal {
+  return {
+    run_id: runId,
+    paused_at: null,
+    cancelled: false,
+    eligible_work_items: [],
+    completed_work_items: [],
+    failed_work_items: [],
+    blocked_work_items: [],
+    pending_gates: [],
+    replay_cursor: null,
+    scheduler_state: 'running',
+    partial_result: null,
+  };
+}

package/packages/runtime/src/scheduler/scheduler.ts

@@ -4,6 +4,13 @@ import type { EventInput } from '../events/bus';
 import type { ExecutionGraph, GraphNode } from '../compiler/graph-compiler';
 import type { WorkspaceManager, WorkspaceRequest } from '../workspace/workspace-manager';
 import type { WorkspaceLease } from '../models/workspace';
+import {
+  saveJournal,
+  loadJournal,
+  deleteJournal,
+  createJournal,
+} from './run-journal';
+import type { RunJournal } from './run-journal';
 
 export interface TaskResult {
   success: boolean;
@@ -32,7 +39,7 @@ export interface SchedulerContext {
 
 export interface RunResult {
   run_id: string;
-  status: 'completed' | 'failed' | 'cancelled';
+  status: 'completed' | 'failed' | 'cancelled' | 'paused';
   completed: string[];
   failed: string[];
   blocked: string[];
@@ -43,10 +50,13 @@ type NodeStatus = 'pending' | 'ready' | 'running' | 'completed' | 'failed' | 'bl
 export class Scheduler {
   private cancelled = false;
   private paused = false;
+  private journal: RunJournal | null = null;
+  private ctx: SchedulerContext | null = null;
 
   async run(graph: ExecutionGraph, ctx: SchedulerContext): Promise<RunResult> {
     this.cancelled = false;
     this.paused = false;
+    this.ctx = ctx;
 
     const status = new Map<string, NodeStatus>();
     for (const id of graph.nodes.keys()) status.set(id, 'pending');
@@ -55,10 +65,26 @@ export class Scheduler {
     const failed: string[] = [];
     const blocked: string[] = [];
 
+    this.journal = createJournal(ctx.runId);
+    saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+
     this.emit(ctx, { type: 'RunStarted', payload: { run_id: ctx.runId } });
 
     for (const wave of graph.waves) {
       if (this.cancelled) break;
+
+      // Respect pause: persist journal and return paused result
+      if (this.paused) {
+        this.journal.scheduler_state = 'paused';
+        this.journal.paused_at = new Date().toISOString();
+        this.journal.completed_work_items = completed.slice();
+        this.journal.failed_work_items = failed.slice();
+        this.journal.blocked_work_items = blocked.slice();
+        this.journal.partial_result = { run_id: ctx.runId, completed, failed, blocked };
+        saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+        return { run_id: ctx.runId, status: 'paused', completed, failed, blocked };
+      }
+
       const waveFailed = await this.runWave(
         wave.node_ids,
         graph,
@@ -68,6 +94,13 @@ export class Scheduler {
         failed,
         blocked
       );
+
+      // Sync journal after each wave
+      this.journal.completed_work_items = completed.slice();
+      this.journal.failed_work_items = failed.slice();
+      this.journal.blocked_work_items = blocked.slice();
+      saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+
       if (waveFailed) break;
     }
 
@@ -95,6 +128,116 @@ export class Scheduler {
       payload: { run_id: ctx.runId, status: finalStatus },
     });
 
+    this.journal.scheduler_state = this.cancelled ? 'cancelled' : 'completed';
+    this.journal.completed_work_items = completed.slice();
+    this.journal.failed_work_items = failed.slice();
+    this.journal.blocked_work_items = blocked.slice();
+    saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+
+    return { run_id: ctx.runId, status: finalStatus, completed, failed, blocked };
+  }
+
+  /**
+   * Recover a previously paused run by loading its journal and re-running
+   * only the work items that haven't completed yet.
+   */
+  async recover(runId: string, ctx: SchedulerContext, graph: ExecutionGraph): Promise<RunResult | null> {
+    const journal = loadJournal(ctx.projectRoot, runId);
+    if (!journal || journal.scheduler_state !== 'paused') return null;
+
+    // Restore state from journal
+    this.cancelled = false;
+    this.paused = false;
+    this.ctx = ctx;
+    this.journal = { ...journal, scheduler_state: 'running', paused_at: null };
+
+    const restoredCompleted = new Set(journal.completed_work_items);
+    const restoredFailed = new Set(journal.failed_work_items);
+    const restoredBlocked = new Set(journal.blocked_work_items);
+
+    const status = new Map<string, NodeStatus>();
+    for (const id of graph.nodes.keys()) {
+      if (restoredCompleted.has(id)) status.set(id, 'completed');
+      else if (restoredFailed.has(id)) status.set(id, 'failed');
+      else if (restoredBlocked.has(id)) status.set(id, 'blocked');
+      else status.set(id, 'pending');
+    }
+
+    const completed = [...restoredCompleted];
+    const failed = [...restoredFailed];
+    const blocked = [...restoredBlocked];
+
+    saveJournal(ctx.projectRoot, runId, this.journal);
+
+    this.emit(ctx, { type: 'RunStarted', payload: { run_id: ctx.runId, recovered: true } });
+
+    for (const wave of graph.waves) {
+      if (this.cancelled) break;
+      if (this.paused) {
+        this.journal.scheduler_state = 'paused';
+        this.journal.paused_at = new Date().toISOString();
+        this.journal.completed_work_items = completed.slice();
+        this.journal.failed_work_items = failed.slice();
+        this.journal.blocked_work_items = blocked.slice();
+        this.journal.partial_result = { run_id: ctx.runId, completed, failed, blocked };
+        saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+        return { run_id: ctx.runId, status: 'paused', completed, failed, blocked };
+      }
+
+      // Skip waves fully completed
+      const allDone = wave.node_ids.every(
+        (id) => restoredCompleted.has(id) || restoredFailed.has(id) || restoredBlocked.has(id)
+      );
+      if (allDone) continue;
+
+      const waveFailed = await this.runWave(
+        wave.node_ids,
+        graph,
+        ctx,
+        status,
+        completed,
+        failed,
+        blocked
+      );
+
+      this.journal.completed_work_items = completed.slice();
+      this.journal.failed_work_items = failed.slice();
+      this.journal.blocked_work_items = blocked.slice();
+      saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+
+      if (waveFailed) break;
+    }
+
+    for (const [id, s] of status) {
+      if (s === 'pending') {
+        status.set(id, 'blocked');
+        blocked.push(id);
+        this.emit(ctx, {
+          type: 'WorkItemBlocked',
+          work_item_id: id,
+          payload: { reason: 'upstream_wave_failed' },
+        });
+      }
+    }
+
+    const finalStatus: RunResult['status'] = this.cancelled
+      ? 'cancelled'
+      : failed.length > 0
+      ? 'failed'
+      : 'completed';
+
+    this.emit(ctx, {
+      type: 'RunCompleted',
+      payload: { run_id: ctx.runId, status: finalStatus, recovered: true },
+    });
+
+    this.journal.scheduler_state = this.cancelled ? 'cancelled' : 'completed';
+    this.journal.completed_work_items = completed.slice();
+    this.journal.failed_work_items = failed.slice();
+    this.journal.blocked_work_items = blocked.slice();
+    saveJournal(ctx.projectRoot, ctx.runId, this.journal);
+    deleteJournal(ctx.projectRoot, ctx.runId);
+
     return { run_id: ctx.runId, status: finalStatus, completed, failed, blocked };
   }
 
@@ -107,11 +250,11 @@ export class Scheduler {
     failed: string[],
     blocked: string[]
   ): Promise<boolean> {
-    // Partition: eligible vs blocked-by-dep
     const eligible: string[] = [];
     const depsNotMet: string[] = [];
 
     for (const id of nodeIds) {
+      if (status.get(id) === 'completed') continue; // already done in recovery
       const node = graph.nodes.get(id)!;
       const depsMet = node.depends_on.every((dep) => status.get(dep) === 'completed');
       if (depsMet) {
@@ -121,7 +264,6 @@ export class Scheduler {
       }
     }
 
-    // Nodes whose deps weren't met in this wave → blocked
     for (const id of depsNotMet) {
       status.set(id, 'blocked');
       blocked.push(id);
@@ -132,21 +274,18 @@ export class Scheduler {
       });
     }
 
-    // Separate read-only (no mutation_scope) from mutation nodes
     const readOnly = eligible.filter((id) => {
       const node = graph.nodes.get(id)!;
       return node.mutation_scope.length === 0;
     });
     const mutations = eligible.filter((id) => !readOnly.includes(id));
 
-    // Run read-only nodes in parallel
     if (readOnly.length > 0) {
       await Promise.all(
         readOnly.map((id) => this.runNode(id, graph, ctx, status, completed, failed))
       );
     }
 
-    // Run mutation nodes sequentially to avoid scope conflicts
     for (const id of mutations) {
       if (this.cancelled) break;
       await this.runNode(id, graph, ctx, status, completed, failed);
@@ -214,7 +353,6 @@ export class Scheduler {
           return;
         }
 
-        // Policy failures never retry
         if (lastResult.failure_class === 'policy') break;
 
         if (attempt < maxAttempts) {
@@ -246,7 +384,6 @@ export class Scheduler {
       }
     }
 
-    // All attempts exhausted
     this.emit(ctx, {
       type: 'WorkItemBlocked',
       work_item_id: nodeId,
@@ -258,14 +395,37 @@ export class Scheduler {
 
   pause(): void {
     this.paused = true;
+    if (this.journal && this.ctx) {
+      this.journal.scheduler_state = 'paused';
+      this.journal.paused_at = new Date().toISOString();
+      saveJournal(this.ctx.projectRoot, this.ctx.runId, this.journal);
+    }
   }
 
   resume(): void {
     this.paused = false;
+    if (this.journal && this.ctx) {
+      this.journal.scheduler_state = 'running';
+      this.journal.paused_at = null;
+      saveJournal(this.ctx.projectRoot, this.ctx.runId, this.journal);
+    }
   }
 
   cancel(): void {
     this.cancelled = true;
+    if (this.journal && this.ctx) {
+      this.journal.cancelled = true;
+      this.journal.scheduler_state = 'cancelled';
+      saveJournal(this.ctx.projectRoot, this.ctx.runId, this.journal);
+    }
+  }
+
+  getJournal(): RunJournal | null {
+    return this.journal;
+  }
+
+  static loadJournal(projectRoot: string, runId: string): RunJournal | null {
+    return loadJournal(projectRoot, runId);
   }
 
   private emit(

package/packages/runtime/src/verification/index.ts

@@ -1 +1,2 @@
 export * from './verification-compiler';
+export * from './verification-manifest';