oxe-cc 1.0.0 → 1.2.1

package/lib/runtime/scheduler/agent-registry.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistry = void 0;
+class AgentRegistry {
+    constructor(heartbeatTimeoutMs = 30000) {
+        this.agents = new Map();
+        this.heartbeatTimeoutMs = heartbeatTimeoutMs;
+    }
+    register(id, executor, workspaceManager, assignedTaskIds = [], role) {
+        if (this.agents.has(id))
+            throw new Error(`Agent "${id}" is already registered`);
+        const agent = {
+            id,
+            executor,
+            workspaceManager,
+            assignedTaskIds,
+            heartbeat: {
+                agent_id: id,
+                last_seen: new Date().toISOString(),
+                current_task: null,
+                status: 'idle',
+            },
+            role,
+            actionLog: [],
+        };
+        this.agents.set(id, agent);
+        return agent;
+    }
+    unregister(id) {
+        this.agents.delete(id);
+    }
+    beat(id, currentTask = null) {
+        const agent = this.agents.get(id);
+        if (!agent)
+            return;
+        agent.heartbeat.last_seen = new Date().toISOString();
+        agent.heartbeat.current_task = currentTask;
+        agent.heartbeat.status = currentTask ? 'running' : 'idle';
+    }
+    setStatus(id, status) {
+        const agent = this.agents.get(id);
+        if (agent)
+            agent.heartbeat.status = status;
+    }
+    isAlive(id) {
+        const agent = this.agents.get(id);
+        if (!agent)
+            return false;
+        const elapsed = Date.now() - new Date(agent.heartbeat.last_seen).getTime();
+        return elapsed < this.heartbeatTimeoutMs;
+    }
+    /** Returns agents that haven't sent a heartbeat within the timeout window */
+    timedOut() {
+        return [...this.agents.values()].filter((a) => !this.isAlive(a.id));
+    }
+    liveAgents() {
+        return [...this.agents.values()].filter((a) => this.isAlive(a.id));
+    }
+    get(id) {
+        return this.agents.get(id) ?? null;
+    }
+    list() {
+        return [...this.agents.values()];
+    }
+    /**
+     * Reassign orphaned tasks from timed-out agents to a fallback agent.
+     * Returns the list of task IDs that were reassigned.
+     */
+    failover(fallbackAgentId) {
+        const fallback = this.agents.get(fallbackAgentId);
+        if (!fallback)
+            throw new Error(`Fallback agent "${fallbackAgentId}" not found`);
+        const orphaned = [];
+        for (const agent of this.timedOut()) {
+            orphaned.push(...agent.assignedTaskIds);
+            agent.assignedTaskIds = [];
+            agent.heartbeat.status = 'failed';
+        }
+        fallback.assignedTaskIds = [...fallback.assignedTaskIds, ...orphaned];
+        return orphaned;
+    }
+    /** Return all agents assigned to a given role */
+    getByRole(role) {
+        return [...this.agents.values()].filter((a) => a.role === role);
+    }
+    /** Append an action log entry for a registered agent (no-op if unknown) */
+    logAction(agentId, log) {
+        const agent = this.agents.get(agentId);
+        if (agent)
+            agent.actionLog.push(log);
+    }
+    clear() {
+        this.agents.clear();
+    }
+}
+exports.AgentRegistry = AgentRegistry;

package/lib/runtime/scheduler/agent-roles.d.ts

@@ -0,0 +1,54 @@
+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 declare function createBudget(opts?: Partial<Omit<AgentBudget, 'consumed_tokens' | 'consumed_time_ms' | 'consumed_retries'>>): AgentBudget;
+export declare function consumeBudget(budget: AgentBudget, delta: {
+    tokens?: number;
+    time_ms?: number;
+    retries?: number;
+}): AgentBudget;
+export declare function isBudgetExhausted(budget: AgentBudget): boolean;
+export declare 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;
+export declare 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;
+}

package/lib/runtime/scheduler/agent-roles.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArbitrationEngine = void 0;
+exports.createBudget = createBudget;
+exports.consumeBudget = consumeBudget;
+exports.isBudgetExhausted = isBudgetExhausted;
+exports.buildHandoff = buildHandoff;
+function createBudget(opts = {}) {
+    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,
+    };
+}
+function consumeBudget(budget, delta) {
+    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),
+    };
+}
+function isBudgetExhausted(budget) {
+    return (budget.consumed_tokens >= budget.max_tokens ||
+        budget.consumed_time_ms >= budget.max_time_ms ||
+        budget.consumed_retries >= budget.max_retries);
+}
+function buildHandoff(opts) {
+    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 ────────────────────────────────────────────────────────
+class ArbitrationEngine {
+    /**
+     * Choose the best result from multiple competing agents.
+     * Prefers success; among successes prefers more evidence; falls back to first.
+     */
+    arbitrate(results) {
+        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;
+    }
+}
+exports.ArbitrationEngine = ArbitrationEngine;

package/lib/runtime/scheduler/index.d.ts

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

package/lib/runtime/scheduler/index.js

@@ -15,3 +15,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./scheduler"), exports);
+__exportStar(require("./run-journal"), exports);
+__exportStar(require("./agent-registry"), exports);
+__exportStar(require("./agent-roles"), exports);

package/lib/runtime/scheduler/multi-agent-coordinator.d.ts

@@ -1,6 +1,7 @@
 import type { ExecutionGraph } from '../compiler/graph-compiler';
 import type { WorkspaceManager } from '../workspace/workspace-manager';
 import type { TaskExecutor, SchedulerContext } from './scheduler';
+import type { CooperativeHandoff } from './agent-roles';
 export type CoordinationMode = 'parallel' | 'competitive' | 'cooperative';
 export interface AgentSpec {
     id: string;
@@ -28,6 +29,7 @@ export interface CoordinationResult {
         completed: string[];
         failed: string[];
     }>;
+    handoffs?: CooperativeHandoff[];
 }
 export declare class MultiAgentCoordinator {
     run(graph: ExecutionGraph, opts: CoordinationOptions): Promise<CoordinationResult>;

package/lib/runtime/scheduler/multi-agent-coordinator.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MultiAgentCoordinator = void 0;
 const bus_1 = require("../events/bus");
 const scheduler_1 = require("./scheduler");
+const agent_roles_1 = require("./agent-roles");
 // ─── Parallel mode ───────────────────────────────────────────────────────────
 // Tasks are partitioned across agents. Each agent runs its own Scheduler
 // on a sub-graph. Results are merged.
@@ -132,16 +133,102 @@ async function competeTwoAgents(nodeId, node, agentA, agentB, opts) {
     }
     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, opts) {
+    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 = [];
+    (0, bus_1.appendEvent)(projectRoot, sessionId, {
+        type: 'RunStarted',
+        run_id: runId,
+        payload: { mode: 'cooperative', planner: planner.id, executor: executor.id },
+    });
+    const completed = [];
+    const failed = [];
+    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 = (0, agent_roles_1.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);
+            (0, bus_1.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;
+            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);
+                (0, bus_1.appendEvent)(projectRoot, sessionId, { type: 'WorkItemCompleted', run_id: runId, work_item_id: nodeId, payload: { mode: 'cooperative' } });
+            }
+            else {
+                failed.push(nodeId);
+                (0, bus_1.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;
+    }
+    (0, bus_1.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 ──────────────────────────────────────────────────────────────
 class MultiAgentCoordinator {
     async run(graph, opts) {
         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/lib/runtime/scheduler/run-journal.d.ts

@@ -0,0 +1,18 @@
+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;
+}
+export declare function saveJournal(projectRoot: string, runId: string, journal: RunJournal): void;
+export declare function loadJournal(projectRoot: string, runId: string): RunJournal | null;
+export declare function deleteJournal(projectRoot: string, runId: string): void;
+export declare function createJournal(runId: string): RunJournal;

package/lib/runtime/scheduler/run-journal.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveJournal = saveJournal;
+exports.loadJournal = loadJournal;
+exports.deleteJournal = deleteJournal;
+exports.createJournal = createJournal;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+function journalPath(projectRoot, runId) {
+    return path_1.default.join(projectRoot, '.oxe', 'runs', runId, 'journal.json');
+}
+function saveJournal(projectRoot, runId, journal) {
+    const p = journalPath(projectRoot, runId);
+    fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+    fs_1.default.writeFileSync(p, JSON.stringify(journal, null, 2), 'utf8');
+}
+function loadJournal(projectRoot, runId) {
+    const p = journalPath(projectRoot, runId);
+    if (!fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function deleteJournal(projectRoot, runId) {
+    const p = journalPath(projectRoot, runId);
+    try {
+        fs_1.default.unlinkSync(p);
+    }
+    catch {
+        // ignore if not found
+    }
+}
+function createJournal(runId) {
+    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/lib/runtime/scheduler/scheduler.d.ts

@@ -2,6 +2,7 @@ import type { OxeEvent } from '../events/envelope';
 import type { ExecutionGraph, GraphNode } from '../compiler/graph-compiler';
 import type { WorkspaceManager } from '../workspace/workspace-manager';
 import type { WorkspaceLease } from '../models/workspace';
+import type { RunJournal } from './run-journal';
 export interface TaskResult {
     success: boolean;
     failure_class: 'env' | 'policy' | 'test' | 'timeout' | null;
@@ -21,7 +22,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[];
@@ -29,11 +30,20 @@ export interface RunResult {
 export declare class Scheduler {
     private cancelled;
     private paused;
+    private journal;
+    private ctx;
     run(graph: ExecutionGraph, ctx: SchedulerContext): Promise<RunResult>;
+    /**
+     * Recover a previously paused run by loading its journal and re-running
+     * only the work items that haven't completed yet.
+     */
+    recover(runId: string, ctx: SchedulerContext, graph: ExecutionGraph): Promise<RunResult | null>;
     private runWave;
     private runNode;
     pause(): void;
     resume(): void;
     cancel(): void;
+    getJournal(): RunJournal | null;
+    static loadJournal(projectRoot: string, runId: string): RunJournal | null;
     private emit;
 }