oxe-cc 0.9.3 → 1.2.1

package/packages/runtime/src/reducers/run-state-reducer.ts

@@ -0,0 +1,269 @@
+import type { OxeEvent } from '../events/envelope';
+import type { Run } from '../models/run';
+import type { WorkItem } from '../models/work-item';
+import type { Attempt } from '../models/attempt';
+import type { Workspace } from '../models/workspace';
+
+export interface PolicyDecisionRecord {
+  allowed: boolean;
+  gate_required: boolean;
+  reason: string;
+  rule_id: string | null;
+}
+
+export interface ToolFailureRecord {
+  tool: string;
+  error: string;
+  timestamp: string;
+}
+
+export interface RunState {
+  run: Run | null;
+  workItems: Map<string, WorkItem>;
+  attempts: Map<string, Attempt[]>;
+  workspaces: Map<string, Workspace>;
+  completedWorkItems: Set<string>;
+  failedWorkItems: Set<string>;
+  blockedWorkItems: Set<string>;
+  // Phase 1 extensions
+  retryCounts: Map<string, number>;
+  policyDecisions: Map<string, PolicyDecisionRecord>;
+  pendingGates: Set<string>;
+  resolvedGates: Map<string, { decision: string; actor?: string }>;
+  verificationStatus: Map<string, 'started' | 'completed' | 'failed'>;
+  evidenceRefs: Map<string, string[]>;
+  toolFailures: Map<string, ToolFailureRecord[]>;
+}
+
+export function createEmptyRunState(): RunState {
+  return {
+    run: null,
+    workItems: new Map(),
+    attempts: new Map(),
+    workspaces: new Map(),
+    completedWorkItems: new Set(),
+    failedWorkItems: new Set(),
+    blockedWorkItems: new Set(),
+    retryCounts: new Map(),
+    policyDecisions: new Map(),
+    pendingGates: new Set(),
+    resolvedGates: new Map(),
+    verificationStatus: new Map(),
+    evidenceRefs: new Map(),
+    toolFailures: new Map(),
+  };
+}
+
+export function reduce(events: OxeEvent[]): RunState {
+  return events.reduce(applyEvent, createEmptyRunState());
+}
+
+// Exported alias so debug-reducer can import applyEvent without circular issues
+export { applyEvent as applyEventExported };
+
+function applyEvent(state: RunState, event: OxeEvent): RunState {
+  switch (event.type) {
+    case 'RunStarted': {
+      const run = event.payload as unknown as Run;
+      return { ...state, run };
+    }
+
+    case 'RunCompleted': {
+      if (!state.run) return state;
+      const status = (event.payload as { status?: Run['status'] }).status ?? 'completed';
+      return {
+        ...state,
+        run: { ...state.run, status, ended_at: event.timestamp },
+      };
+    }
+
+    case 'WorkItemReady': {
+      if (!event.work_item_id) return state;
+      const workItems = new Map(state.workItems);
+      const existing = workItems.get(event.work_item_id);
+      if (existing) {
+        workItems.set(event.work_item_id, { ...existing, status: 'ready' });
+      } else {
+        const item = event.payload as unknown as WorkItem;
+        workItems.set(event.work_item_id, { ...item, work_item_id: event.work_item_id, status: 'ready' });
+      }
+      return { ...state, workItems };
+    }
+
+    case 'AttemptStarted': {
+      if (!event.work_item_id || !event.attempt_id) return state;
+      const attempts = new Map(state.attempts);
+      const attempt: Attempt = {
+        attempt_id: event.attempt_id,
+        work_item_id: event.work_item_id,
+        attempt_number: (event.payload as { attempt_number?: number }).attempt_number ?? 1,
+        workspace_id: null,
+        agent_profile: null,
+        model: null,
+        started_at: event.timestamp,
+        ended_at: null,
+        outcome: null,
+      };
+      const existing = attempts.get(event.work_item_id) ?? [];
+      attempts.set(event.work_item_id, [...existing, attempt]);
+      return { ...state, attempts };
+    }
+
+    case 'WorkspaceAllocated': {
+      const ws = event.payload as unknown as Workspace;
+      if (!ws.workspace_id) return state;
+      const workspaces = new Map(state.workspaces);
+      workspaces.set(ws.workspace_id, { ...ws, status: 'ready' });
+      return { ...state, workspaces };
+    }
+
+    case 'WorkItemCompleted': {
+      if (!event.work_item_id) return state;
+      const workItems = new Map(state.workItems);
+      const item = workItems.get(event.work_item_id);
+      if (item) workItems.set(event.work_item_id, { ...item, status: 'completed' });
+      const completedWorkItems = new Set(state.completedWorkItems);
+      completedWorkItems.add(event.work_item_id);
+      // Collect evidence refs from payload
+      const evidence = (event.payload as { evidence?: string[] }).evidence ?? [];
+      if (evidence.length > 0) {
+        const evidenceRefs = new Map(state.evidenceRefs);
+        const existing = evidenceRefs.get(event.work_item_id) ?? [];
+        evidenceRefs.set(event.work_item_id, [...existing, ...evidence]);
+        return { ...state, workItems, completedWorkItems, evidenceRefs };
+      }
+      return { ...state, workItems, completedWorkItems };
+    }
+
+    case 'WorkItemBlocked': {
+      if (!event.work_item_id) return state;
+      const workItems = new Map(state.workItems);
+      const item = workItems.get(event.work_item_id);
+      if (item) workItems.set(event.work_item_id, { ...item, status: 'blocked' });
+      const blockedWorkItems = new Set(state.blockedWorkItems);
+      blockedWorkItems.add(event.work_item_id);
+      return { ...state, workItems, blockedWorkItems };
+    }
+
+    case 'RetryScheduled': {
+      if (!event.work_item_id) return state;
+      const retryCounts = new Map(state.retryCounts);
+      const current = retryCounts.get(event.work_item_id) ?? 0;
+      retryCounts.set(event.work_item_id, current + 1);
+      return { ...state, retryCounts };
+    }
+
+    case 'PolicyEvaluated': {
+      const p = event.payload as {
+        work_item_id?: string;
+        allowed?: boolean;
+        gate_required?: boolean;
+        reason?: string;
+        rule_id?: string | null;
+      };
+      const key = p.work_item_id ?? event.work_item_id;
+      if (!key) return state;
+      const policyDecisions = new Map(state.policyDecisions);
+      policyDecisions.set(key, {
+        allowed: p.allowed ?? true,
+        gate_required: p.gate_required ?? false,
+        reason: p.reason ?? '',
+        rule_id: p.rule_id ?? null,
+      });
+      return { ...state, policyDecisions };
+    }
+
+    case 'GateRequested': {
+      const gateId = (event.payload as { gate_id?: string }).gate_id;
+      if (!gateId) return state;
+      const pendingGates = new Set(state.pendingGates);
+      pendingGates.add(gateId);
+      return { ...state, pendingGates };
+    }
+
+    case 'GateResolved': {
+      const p = event.payload as { gate_id?: string; decision?: string; actor?: string };
+      if (!p.gate_id) return state;
+      const pendingGates = new Set(state.pendingGates);
+      pendingGates.delete(p.gate_id);
+      const resolvedGates = new Map(state.resolvedGates);
+      resolvedGates.set(p.gate_id, { decision: p.decision ?? 'approved', actor: p.actor });
+      return { ...state, pendingGates, resolvedGates };
+    }
+
+    case 'VerificationStarted': {
+      const key = event.work_item_id ?? (event.payload as { work_item_id?: string }).work_item_id;
+      if (!key) return state;
+      const verificationStatus = new Map(state.verificationStatus);
+      verificationStatus.set(key, 'started');
+      return { ...state, verificationStatus };
+    }
+
+    case 'VerificationCompleted': {
+      const p = event.payload as { work_item_id?: string; status?: 'completed' | 'failed' };
+      const key = event.work_item_id ?? p.work_item_id;
+      if (!key) return state;
+      const verificationStatus = new Map(state.verificationStatus);
+      verificationStatus.set(key, p.status ?? 'completed');
+      return { ...state, verificationStatus };
+    }
+
+    case 'ToolFailed': {
+      if (!event.work_item_id) return state;
+      const p = event.payload as { tool?: string; error?: string };
+      const toolFailures = new Map(state.toolFailures);
+      const existing = toolFailures.get(event.work_item_id) ?? [];
+      toolFailures.set(event.work_item_id, [
+        ...existing,
+        { tool: p.tool ?? 'unknown', error: p.error ?? '', timestamp: event.timestamp },
+      ]);
+      return { ...state, toolFailures };
+    }
+
+    case 'EvidenceCollected': {
+      const p = event.payload as { work_item_id?: string; refs?: string[]; ref?: string };
+      const key = event.work_item_id ?? p.work_item_id;
+      if (!key) return state;
+      const refs = p.refs ?? (p.ref ? [p.ref] : []);
+      if (refs.length === 0) return state;
+      const evidenceRefs = new Map(state.evidenceRefs);
+      const existing = evidenceRefs.get(key) ?? [];
+      evidenceRefs.set(key, [...existing, ...refs]);
+      return { ...state, evidenceRefs };
+    }
+
+    default:
+      return state;
+  }
+}
+
+export function getWorkItemStatus(
+  state: RunState,
+  workItemId: string
+): WorkItem['status'] | null {
+  return state.workItems.get(workItemId)?.status ?? null;
+}
+
+export function getAttemptCount(state: RunState, workItemId: string): number {
+  return state.attempts.get(workItemId)?.length ?? 0;
+}
+
+export function getRetryCount(state: RunState, workItemId: string): number {
+  return state.retryCounts.get(workItemId) ?? 0;
+}
+
+export function getPolicyDecision(state: RunState, workItemId: string): PolicyDecisionRecord | null {
+  return state.policyDecisions.get(workItemId) ?? null;
+}
+
+export function getVerificationStatus(state: RunState, workItemId: string): 'started' | 'completed' | 'failed' | null {
+  return state.verificationStatus.get(workItemId) ?? null;
+}
+
+export function getEvidenceRefs(state: RunState, workItemId: string): string[] {
+  return state.evidenceRefs.get(workItemId) ?? [];
+}
+
+export function getToolFailures(state: RunState, workItemId: string): ToolFailureRecord[] {
+  return state.toolFailures.get(workItemId) ?? [];
+}

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

@@ -0,0 +1,132 @@
+import type { TaskExecutor } from './scheduler';
+import type { WorkspaceManager } from '../workspace/workspace-manager';
+import type { AgentRole, AgentActionLog } from './agent-roles';
+
+export type AgentStatus = 'idle' | 'running' | 'paused' | 'failed' | 'timeout';
+
+export interface AgentHeartbeat {
+  agent_id: string;
+  last_seen: string;
+  current_task: string | null;
+  status: AgentStatus;
+}
+
+export interface RegisteredAgent {
+  id: string;
+  executor: TaskExecutor;
+  workspaceManager: WorkspaceManager;
+  assignedTaskIds: string[];
+  heartbeat: AgentHeartbeat;
+  role?: AgentRole;
+  actionLog: AgentActionLog[];
+}
+
+export class AgentRegistry {
+  private agents = new Map<string, RegisteredAgent>();
+  private readonly heartbeatTimeoutMs: number;
+
+  constructor(heartbeatTimeoutMs = 30_000) {
+    this.heartbeatTimeoutMs = heartbeatTimeoutMs;
+  }
+
+  register(
+    id: string,
+    executor: TaskExecutor,
+    workspaceManager: WorkspaceManager,
+    assignedTaskIds: string[] = [],
+    role?: AgentRole
+  ): RegisteredAgent {
+    if (this.agents.has(id)) throw new Error(`Agent "${id}" is already registered`);
+    const agent: RegisteredAgent = {
+      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: string): void {
+    this.agents.delete(id);
+  }
+
+  beat(id: string, currentTask: string | null = null): void {
+    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: string, status: AgentStatus): void {
+    const agent = this.agents.get(id);
+    if (agent) agent.heartbeat.status = status;
+  }
+
+  isAlive(id: string): boolean {
+    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(): RegisteredAgent[] {
+    return [...this.agents.values()].filter((a) => !this.isAlive(a.id));
+  }
+
+  liveAgents(): RegisteredAgent[] {
+    return [...this.agents.values()].filter((a) => this.isAlive(a.id));
+  }
+
+  get(id: string): RegisteredAgent | null {
+    return this.agents.get(id) ?? null;
+  }
+
+  list(): RegisteredAgent[] {
+    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: string): string[] {
+    const fallback = this.agents.get(fallbackAgentId);
+    if (!fallback) throw new Error(`Fallback agent "${fallbackAgentId}" not found`);
+
+    const orphaned: string[] = [];
+    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: AgentRole): RegisteredAgent[] {
+    return [...this.agents.values()].filter((a) => a.role === role);
+  }
+
+  /** Append an action log entry for a registered agent (no-op if unknown) */
+  logAction(agentId: string, log: AgentActionLog): void {
+    const agent = this.agents.get(agentId);
+    if (agent) agent.actionLog.push(log);
+  }
+
+  clear(): void {
+    this.agents.clear();
+  }
+}

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

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