@corbat-tech/coco 2.36.0 → 2.38.0

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import { z } from 'zod';
 import * as os4 from 'os';
 import os4__default, { homedir } from 'os';
 import * as fs35 from 'fs/promises';
-import fs35__default, { mkdir, writeFile, readFile, access, readdir, rm, constants } from 'fs/promises';
+import fs35__default, { mkdir, writeFile, readFile, access, constants, readdir, rm } from 'fs/promises';
 import JSON5 from 'json5';
 import * as crypto from 'crypto';
 import { randomUUID, randomBytes, createHash } from 'crypto';
@@ -40857,9 +40857,6 @@ function getSessionStore() {
   }
   return defaultStore;
 }
-function createSessionStore(config) {
-  return new SessionStore(config);
-}
 
 // src/cli/repl/commands/resume.ts
 function formatRelativeTime2(date) {
@@ -43230,6 +43227,145 @@ Response format (JSON only, no prose):
   return spec;
 }
 
+// src/runtime/multi-agent.ts
+function createAgentArtifact(input) {
+  return {
+    ...input,
+    id: input.id ?? `artifact-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
+    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createSummaryArtifact(output, metadata = {}) {
+  return createAgentArtifact({
+    kind: "summary",
+    content: output,
+    title: metadata.title ?? "Agent summary",
+    agentRunId: metadata.agentRunId,
+    taskId: metadata.taskId
+  });
+}
+function normalizeAgentRunResult(input) {
+  const completedAt = input.completedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const startedAt = input.startedAt ?? completedAt;
+  const status = input.status ?? (input.success ? "completed" : "failed");
+  const artifacts = input.artifacts && input.artifacts.length > 0 ? input.artifacts.map(cloneArtifact) : [createSummaryArtifact(input.output, { agentRunId: input.id, taskId: input.taskId })];
+  return {
+    id: input.id,
+    taskId: input.taskId,
+    role: input.role,
+    status,
+    success: input.success,
+    output: input.output,
+    artifacts,
+    toolsUsed: [...input.toolsUsed ?? []],
+    turns: input.turns ?? 0,
+    durationMs: input.durationMs ?? 0,
+    usage: input.usage,
+    error: input.error,
+    startedAt,
+    completedAt,
+    metadata: input.metadata
+  };
+}
+function validateAgentGraph(graph) {
+  const issues = [];
+  const nodeIds = /* @__PURE__ */ new Set();
+  const gateIds = new Set((graph.gates ?? []).map((gate) => gate.id));
+  if (graph.parallelism !== void 0 && graph.parallelism < 1) {
+    issues.push({
+      code: "invalid-parallelism",
+      message: "Graph parallelism must be greater than zero."
+    });
+  }
+  for (const node of graph.nodes) {
+    if (nodeIds.has(node.id)) {
+      issues.push({
+        code: "duplicate-node",
+        message: `Duplicate graph node '${node.id}'.`,
+        nodeId: node.id
+      });
+    }
+    nodeIds.add(node.id);
+    if (node.retryPolicy && node.retryPolicy.maxAttempts < 1) {
+      issues.push({
+        code: "invalid-retry-policy",
+        message: `Node '${node.id}' retry policy must allow at least one attempt.`,
+        nodeId: node.id
+      });
+    }
+    for (const dep of node.dependsOn ?? []) {
+      if (!nodeIds.has(dep) && !graph.nodes.some((candidate) => candidate.id === dep)) {
+        issues.push({
+          code: "missing-dependency",
+          message: `Node '${node.id}' depends on missing node '${dep}'.`,
+          nodeId: node.id
+        });
+      }
+    }
+    for (const gate of node.gates ?? []) {
+      if (!gateIds.has(gate)) {
+        issues.push({
+          code: "missing-gate",
+          message: `Node '${node.id}' references missing gate '${gate}'.`,
+          nodeId: node.id,
+          gateId: gate
+        });
+      }
+    }
+  }
+  for (const edge of graph.edges ?? []) {
+    if (!nodeIds.has(edge.from)) {
+      issues.push({
+        code: "missing-edge-node",
+        message: `Graph edge references missing source node '${edge.from}'.`,
+        nodeId: edge.from
+      });
+    }
+    if (!nodeIds.has(edge.to)) {
+      issues.push({
+        code: "missing-edge-node",
+        message: `Graph edge references missing target node '${edge.to}'.`,
+        nodeId: edge.to
+      });
+    }
+  }
+  const levels = buildExecutionLevels(graph, issues);
+  return { valid: issues.length === 0, issues, levels };
+}
+function buildExecutionLevels(graph, issues) {
+  const dependencies = /* @__PURE__ */ new Map();
+  for (const node of graph.nodes) {
+    dependencies.set(node.id, new Set(node.dependsOn ?? []));
+  }
+  for (const edge of graph.edges ?? []) {
+    if (dependencies.has(edge.to)) {
+      dependencies.get(edge.to).add(edge.from);
+    }
+  }
+  const completed = /* @__PURE__ */ new Set();
+  const levels = [];
+  while (completed.size < dependencies.size) {
+    const level = [...dependencies.entries()].filter(([id, deps]) => !completed.has(id) && [...deps].every((dep) => completed.has(dep))).map(([id]) => id);
+    if (level.length === 0) {
+      const remaining = [...dependencies.keys()].filter((id) => !completed.has(id));
+      issues.push({
+        code: "cycle",
+        message: `Graph contains a cycle involving: ${remaining.join(", ")}.`
+      });
+      return levels;
+    }
+    for (const id of level) completed.add(id);
+    levels.push(level);
+  }
+  return levels;
+}
+function cloneArtifact(artifact) {
+  return {
+    ...artifact,
+    metadata: artifact.metadata ? { ...artifact.metadata } : void 0
+  };
+}
+
 // src/agents/executor.ts
 var AgentExecutor = class {
   constructor(provider, toolRegistry) {
@@ -43243,6 +43379,7 @@ var AgentExecutor = class {
    */
   async execute(agent, task) {
     const startTime = Date.now();
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const toolsUsed = /* @__PURE__ */ new Set();
     const messages = [
       {
@@ -43253,6 +43390,8 @@ var AgentExecutor = class {
     const agentToolDefs = this.getToolDefinitionsForAgent(agent.allowedTools);
     let turn = 0;
     let totalTokens = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
     while (turn < agent.maxTurns) {
       turn++;
       try {
@@ -43261,16 +43400,23 @@ var AgentExecutor = class {
           system: agent.systemPrompt
         });
         const usage = response.usage;
+        totalInputTokens += usage?.inputTokens || 0;
+        totalOutputTokens += usage?.outputTokens || 0;
         totalTokens += (usage?.inputTokens || 0) + (usage?.outputTokens || 0);
         if (response.stopReason !== "tool_use" || response.toolCalls.length === 0) {
-          return {
+          return this.toAgentResult({
+            agent,
+            task,
             output: response.content,
             success: true,
             turns: turn,
             toolsUsed: Array.from(toolsUsed),
             tokensUsed: totalTokens,
-            duration: Date.now() - startTime
-          };
+            inputTokens: totalInputTokens,
+            outputTokens: totalOutputTokens,
+            duration: Date.now() - startTime,
+            startedAt
+          });
         }
         const assistantContent = [];
         if (response.content) {
@@ -43316,24 +43462,38 @@ var AgentExecutor = class {
           content: toolResults
         });
       } catch (error) {
-        return {
-          output: `Agent error on turn ${turn}: ${error instanceof Error ? error.message : String(error)}`,
+        const output2 = `Agent error on turn ${turn}: ${error instanceof Error ? error.message : String(error)}`;
+        return this.toAgentResult({
+          agent,
+          task,
+          output: output2,
           success: false,
           turns: turn,
           toolsUsed: Array.from(toolsUsed),
           tokensUsed: totalTokens,
-          duration: Date.now() - startTime
-        };
+          inputTokens: totalInputTokens,
+          outputTokens: totalOutputTokens,
+          duration: Date.now() - startTime,
+          startedAt,
+          error: output2
+        });
       }
     }
-    return {
-      output: "Agent reached maximum turns without completing task",
+    const output = "Agent reached maximum turns without completing task";
+    return this.toAgentResult({
+      agent,
+      task,
+      output,
       success: false,
       turns: turn,
       toolsUsed: Array.from(toolsUsed),
       tokensUsed: totalTokens,
-      duration: Date.now() - startTime
-    };
+      inputTokens: totalInputTokens,
+      outputTokens: totalOutputTokens,
+      duration: Date.now() - startTime,
+      startedAt,
+      error: output
+    });
   }
   /**
    * Build task prompt with context
@@ -43359,7 +43519,36 @@ Complete this task autonomously using the available tools. When done, provide a
     if (allowedToolNames.length === 0) return allDefs;
     return allDefs.filter((def) => allowedToolNames.includes(def.name));
   }
+  toAgentResult(input) {
+    const structuredResult = normalizeAgentRunResult({
+      id: `${input.task.id}-${Date.now().toString(36)}`,
+      taskId: input.task.id,
+      role: normalizeRole(input.agent.role),
+      success: input.success,
+      output: input.output,
+      turns: input.turns,
+      toolsUsed: input.toolsUsed,
+      durationMs: input.duration,
+      startedAt: input.startedAt,
+      usage: { inputTokens: input.inputTokens, outputTokens: input.outputTokens },
+      error: input.error,
+      metadata: { legacyRole: input.agent.role }
+    });
+    return {
+      output: input.output,
+      success: input.success,
+      turns: input.turns,
+      toolsUsed: input.toolsUsed,
+      tokensUsed: input.tokensUsed,
+      duration: input.duration,
+      artifacts: structuredResult.artifacts,
+      structuredResult
+    };
+  }
 };
+function normalizeRole(role) {
+  return role === "researcher" || role === "architect" || role === "editor" || role === "coder" || role === "tester" || role === "reviewer" || role === "optimizer" || role === "planner" ? role : "coder";
+}
 var AGENT_ROLES = {
   researcher: {
     role: "researcher",
@@ -44197,6 +44386,9 @@ var testTools = [runTestsTool, getCoverageTool, runTestFileTool];
 // src/tools/index.ts
 init_registry4();
 
+// src/tools/profiles.ts
+init_registry4();
+
 // src/tools/file.ts
 init_registry4();
 init_errors();
@@ -45823,11 +46015,15 @@ var AgentManager = class extends EventEmitter {
       failedAgent.status = "failed";
       failedAgent.error = error;
       failedAgent.completedAt = /* @__PURE__ */ new Date();
-      return {
+      return this.buildResult({
         agent: failedAgent,
         success: false,
-        output: error
-      };
+        output: error,
+        turns: 0,
+        toolsUsed: [],
+        startedAt: failedAgent.createdAt.toISOString(),
+        usage: { inputTokens: 0, outputTokens: 0 }
+      });
     }
     const agent = this.createAgent(type, task);
     this.activeAgents.set(agent.id, agent);
@@ -45879,11 +46075,15 @@ var AgentManager = class extends EventEmitter {
       options.onStatusChange?.(agent);
       this.logger.error(`Agent ${agent.id} failed unexpectedly`, { error: errorMessage });
       this.emitEvent("fail", agent);
-      return {
+      return this.buildResult({
         agent,
         success: false,
-        output: errorMessage
-      };
+        output: errorMessage,
+        turns: 0,
+        toolsUsed: [],
+        startedAt: agent.createdAt.toISOString(),
+        usage: { inputTokens: 0, outputTokens: 0 }
+      });
     }
   }
   /**
@@ -46004,6 +46204,8 @@ var AgentManager = class extends EventEmitter {
     let finalOutput = "";
     let iteration = 0;
     const maxTurns = config.maxTurns ?? 10;
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const toolsUsed = /* @__PURE__ */ new Set();
     while (iteration < maxTurns) {
       iteration++;
       if (options.signal?.aborted) {
@@ -46012,12 +46214,15 @@ var AgentManager = class extends EventEmitter {
         agent.completedAt = /* @__PURE__ */ new Date();
         this.moveToCompleted(agent.id);
         options.onStatusChange?.(agent);
-        return {
+        return this.buildResult({
           agent,
           success: false,
           output: "Agent execution was aborted",
+          turns: iteration,
+          toolsUsed: Array.from(toolsUsed),
+          startedAt,
           usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens }
-        };
+        });
       }
       const response = await this.provider.chatWithTools(messages, {
         system: config.systemPrompt,
@@ -46034,7 +46239,7 @@ var AgentManager = class extends EventEmitter {
         messages.push({ role: "assistant", content: response.content });
         break;
       }
-      const toolResults = await this.executeToolCalls(response.toolCalls, config);
+      const toolResults = await this.executeToolCalls(response.toolCalls, config, toolsUsed);
       const toolUses = response.toolCalls.map((tc) => ({
         type: "tool_use",
         id: tc.id,
@@ -46058,12 +46263,15 @@ var AgentManager = class extends EventEmitter {
       iterations: iteration,
       outputLength: finalOutput.length
     });
-    return {
+    return this.buildResult({
       agent,
       success: true,
       output: finalOutput,
+      turns: iteration,
+      toolsUsed: Array.from(toolsUsed),
+      startedAt,
       usage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens }
-    };
+    });
   }
   /**
    * Get tool definitions filtered for the agent's allowed tools
@@ -46076,10 +46284,11 @@ var AgentManager = class extends EventEmitter {
   /**
    * Execute tool calls and return results
    */
-  async executeToolCalls(toolCalls, config) {
+  async executeToolCalls(toolCalls, config, toolsUsed) {
     const results = [];
     const allowedTools = new Set(config.tools);
     for (const toolCall of toolCalls) {
+      toolsUsed.add(toolCall.name);
       if (!allowedTools.has(toolCall.name)) {
         results.push({
           type: "tool_result",
@@ -46120,6 +46329,33 @@ var AgentManager = class extends EventEmitter {
       this.abortControllers.delete(agentId);
     }
   }
+  buildResult(input) {
+    const structuredResult = normalizeAgentRunResult({
+      id: `${input.agent.id}-run`,
+      taskId: input.agent.id,
+      role: agentTypeToRuntimeRole(input.agent.type),
+      success: input.success,
+      output: input.output,
+      turns: input.turns,
+      toolsUsed: input.toolsUsed,
+      usage: input.usage,
+      startedAt: input.startedAt,
+      durationMs: input.agent.completedAt ? input.agent.completedAt.getTime() - input.agent.createdAt.getTime() : 0,
+      status: input.success ? "completed" : "failed",
+      error: input.success ? void 0 : input.agent.error,
+      metadata: { agentType: input.agent.type }
+    });
+    return {
+      agent: input.agent,
+      success: input.success,
+      output: input.output,
+      artifacts: structuredResult.artifacts,
+      structuredResult,
+      toolsUsed: input.toolsUsed,
+      turns: input.turns,
+      usage: input.usage
+    };
+  }
   /**
    * Emit an agent event
    */
@@ -46129,6 +46365,31 @@ var AgentManager = class extends EventEmitter {
     this.emit("agent", event);
   }
 };
+function agentTypeToRuntimeRole(type) {
+  switch (type) {
+    case "explore":
+      return "researcher";
+    case "plan":
+      return "planner";
+    case "test":
+    case "e2e":
+    case "tdd":
+      return "tester";
+    case "debug":
+    case "refactor":
+      return "coder";
+    case "review":
+      return "reviewer";
+    case "architect":
+      return "architect";
+    case "security":
+      return "security";
+    case "docs":
+      return "docs";
+    case "database":
+      return "database";
+  }
+}
 
 // src/agents/provider-bridge.ts
 var agentProvider = null;
@@ -52606,7 +52867,7 @@ var repoMapCommand = {
   }
 };
 
-// src/cli/repl/modes.ts
+// src/runtime/agent-modes.ts
 var AGENT_MODES = {
   ask: {
     id: "ask",
@@ -57374,6 +57635,39 @@ init_providers();
 
 // src/runtime/agent-runtime.ts
 init_env();
+
+// src/runtime/default-turn-runner.ts
+var DefaultRuntimeTurnRunner = class {
+  async run(input, context) {
+    const messages = [
+      ...context.session.messages,
+      {
+        role: "user",
+        content: input.content
+      }
+    ];
+    const response = await context.provider.chat(messages, {
+      model: input.options?.model,
+      maxTokens: input.options?.maxTokens,
+      temperature: input.options?.temperature,
+      stopSequences: input.options?.stopSequences,
+      system: context.session.instructions ?? input.options?.system,
+      timeout: input.options?.timeout,
+      signal: input.options?.signal,
+      thinking: input.options?.thinking
+    });
+    return {
+      sessionId: context.session.id,
+      content: response.content,
+      usage: response.usage,
+      model: response.model,
+      mode: context.session.mode
+    };
+  }
+};
+function createDefaultRuntimeTurnRunner() {
+  return new DefaultRuntimeTurnRunner();
+}
 var InMemoryEventLog = class {
   events = [];
   record(type, data = {}) {
@@ -57492,7 +57786,8 @@ var DESTRUCTIVE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "delete_file",
   "restore_checkpoint",
   "git_commit",
-  "git_push"
+  "git_push",
+  "request_human_escalation"
 ]);
 function riskForTool(tool) {
   if (READ_ONLY_TOOL_NAMES.has(tool.name)) return "read-only";
@@ -57525,6 +57820,22 @@ var DefaultPermissionPolicy = class {
     }
     return { allowed: true, risk };
   }
+  canExecuteToolInput(mode, tool, input) {
+    if (tool.name !== "run_linter") {
+      return this.canExecuteTool(mode, tool);
+    }
+    const definition = getAgentMode(mode);
+    const fixEnabled = input["fix"] === true;
+    const decision = fixEnabled ? { allowed: true, risk: "write" } : { allowed: true, risk: "read-only" };
+    if (definition.readOnly && fixEnabled) {
+      return {
+        allowed: false,
+        reason: `${definition.label} mode is read-only; run_linter with fix=true can modify files.`,
+        risk: "write"
+      };
+    }
+    return decision;
+  }
 };
 function createPermissionPolicy() {
   return new DefaultPermissionPolicy();
@@ -57566,6 +57877,353 @@ var ProviderRegistry = class {
 function createProviderRegistry() {
   return new ProviderRegistry();
 }
+function createSessionId() {
+  return `rt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function cloneSession(session) {
+  return structuredClone(session);
+}
+var InMemoryRuntimeSessionStore = class {
+  sessions = /* @__PURE__ */ new Map();
+  create(options = {}) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const session = {
+      id: options.id ?? createSessionId(),
+      createdAt: now,
+      updatedAt: now,
+      mode: options.mode ?? "ask",
+      messages: options.messages ? options.messages.map((message) => ({ ...message })) : [],
+      instructions: options.instructions,
+      metadata: { ...options.metadata }
+    };
+    this.sessions.set(session.id, cloneSession(session));
+    return cloneSession(session);
+  }
+  get(id) {
+    const session = this.sessions.get(id);
+    return session ? cloneSession(session) : void 0;
+  }
+  update(session) {
+    const updated = {
+      ...session,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      messages: session.messages.map((message) => ({ ...message })),
+      metadata: { ...session.metadata }
+    };
+    this.sessions.set(updated.id, cloneSession(updated));
+    return cloneSession(updated);
+  }
+  list() {
+    return [...this.sessions.values()].map(cloneSession);
+  }
+  delete(id) {
+    return this.sessions.delete(id);
+  }
+};
+function createRuntimeSessionStore() {
+  return new InMemoryRuntimeSessionStore();
+}
+
+// src/runtime/workflow-registry.ts
+function cloneWorkflow(workflow) {
+  return {
+    ...workflow,
+    checks: [...workflow.checks],
+    steps: workflow.steps.map((step) => ({
+      ...step,
+      requiredTools: [...step.requiredTools]
+    })),
+    nodes: workflow.nodes?.map((node) => ({
+      ...node,
+      dependsOn: node.dependsOn ? [...node.dependsOn] : void 0,
+      requiredTools: node.requiredTools ? [...node.requiredTools] : void 0,
+      gates: node.gates ? [...node.gates] : void 0,
+      retryPolicy: node.retryPolicy ? { ...node.retryPolicy } : void 0
+    })),
+    edges: workflow.edges?.map((edge) => ({ ...edge })),
+    gates: workflow.gates?.map((gate) => ({ ...gate })),
+    retryPolicy: workflow.retryPolicy ? { ...workflow.retryPolicy } : void 0
+  };
+}
+function workflowToAgentGraph(workflow) {
+  const nodes = workflow.nodes ?? workflow.steps.map((step, index) => ({
+    id: step.id,
+    description: step.description,
+    requiredTools: [...step.requiredTools],
+    risk: step.risk,
+    dependsOn: index > 0 ? [workflow.steps[index - 1].id] : []
+  }));
+  return {
+    nodes,
+    edges: workflow.edges,
+    gates: workflow.gates,
+    parallelism: workflow.parallelism
+  };
+}
+var WorkflowCatalog = class {
+  workflows = /* @__PURE__ */ new Map();
+  constructor(workflows = DEFAULT_WORKFLOWS) {
+    for (const workflow of workflows) {
+      this.register(workflow);
+    }
+  }
+  register(workflow) {
+    const validation = validateAgentGraph(workflowToAgentGraph(workflow));
+    if (!validation.valid) {
+      throw new Error(
+        `Invalid workflow graph for '${workflow.id}': ${validation.issues.map((issue) => issue.message).join("; ")}`
+      );
+    }
+    this.workflows.set(workflow.id, cloneWorkflow(workflow));
+  }
+  get(id) {
+    const workflow = this.workflows.get(id);
+    return workflow ? cloneWorkflow(workflow) : void 0;
+  }
+  list() {
+    return [...this.workflows.values()].map(cloneWorkflow).sort((a, b) => a.id.localeCompare(b.id));
+  }
+  createPlan(workflowId, input, eventLog) {
+    const workflow = this.get(workflowId);
+    if (!workflow) {
+      throw new Error(`Unknown workflow: ${workflowId}`);
+    }
+    const plan = {
+      id: `${workflowId}-${Date.now().toString(36)}`,
+      workflowId,
+      input,
+      status: "planned",
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    eventLog?.record("workflow.planned", {
+      workflowId,
+      planId: plan.id,
+      replayable: workflow.replayable,
+      checks: workflow.checks,
+      graphLevels: validateAgentGraph(workflowToAgentGraph(workflow)).levels
+    });
+    return plan;
+  }
+};
+var DEFAULT_WORKFLOWS = [
+  {
+    id: "architect-editor-verifier",
+    name: "Architect / Editor / Verifier",
+    description: "Plan read-only, apply approved changes, then verify and summarize risks.",
+    inputSchema: "task: string; approvedPlan?: string",
+    outputKind: "patch",
+    replayable: true,
+    checks: ["pnpm check", "diff summary", "review risks"],
+    steps: [
+      {
+        id: "architect",
+        description: "Inspect context and produce a read-only implementation plan.",
+        requiredTools: ["repo_context", "read_file", "git_diff"],
+        risk: "read-only"
+      },
+      {
+        id: "editor",
+        description: "Apply the approved plan without reinterpreting the objective.",
+        requiredTools: ["read_file", "edit_file", "write_file"],
+        risk: "write"
+      },
+      {
+        id: "verifier",
+        description: "Run checks, review diff, and report residual risk.",
+        requiredTools: ["bash_exec", "git_diff", "review_code"],
+        risk: "destructive"
+      }
+    ]
+  },
+  {
+    id: "provider-diagnosis",
+    name: "Provider Diagnosis",
+    description: "Probe provider/model capabilities, endpoint strategy, credentials, and fallbacks.",
+    inputSchema: "provider?: string; model?: string; live?: boolean",
+    outputKind: "json",
+    replayable: true,
+    checks: ["provider capability matrix", "optional live probe"],
+    steps: [
+      {
+        id: "capability",
+        description: "Resolve catalog metadata and runtime endpoint strategy.",
+        requiredTools: [],
+        risk: "read-only"
+      },
+      {
+        id: "fallbacks",
+        description: "Suggest fallback provider/model choices when unsupported.",
+        requiredTools: [],
+        risk: "read-only"
+      }
+    ]
+  },
+  {
+    id: "review-pr",
+    name: "Review PR",
+    description: "Review a branch or PR read-only and emit severity-ranked findings.",
+    inputSchema: "target: string",
+    outputKind: "markdown",
+    replayable: true,
+    checks: ["git diff", "tests gap review", "security review"],
+    steps: [
+      {
+        id: "collect-diff",
+        description: "Collect PR diff and related context.",
+        requiredTools: ["git_diff", "repo_context"],
+        risk: "read-only"
+      },
+      {
+        id: "findings",
+        description: "Produce prioritized findings with file and line references.",
+        requiredTools: ["read_file", "review_code"],
+        risk: "read-only"
+      }
+    ]
+  },
+  {
+    id: "best-of-n",
+    name: "Best Of N",
+    description: "Run multiple isolated attempts, score them, and select a winning patch.",
+    inputSchema: "task: string; attempts: number",
+    outputKind: "patch",
+    replayable: true,
+    checks: ["worktree isolation", "checks pass", "diff risk score"],
+    steps: [
+      {
+        id: "fanout",
+        description: "Create isolated attempts in temporary worktrees.",
+        requiredTools: ["git_status", "bash_exec"],
+        risk: "destructive"
+      },
+      {
+        id: "score",
+        description: "Run checks and compare quality, cost, latency, and diff risk.",
+        requiredTools: ["bash_exec", "git_diff"],
+        risk: "destructive"
+      },
+      {
+        id: "apply-winner",
+        description: "Apply the winning patch only if conservative checks pass.",
+        requiredTools: ["git_diff", "edit_file"],
+        risk: "write"
+      }
+    ]
+  },
+  {
+    id: "release",
+    name: "Release",
+    description: "Follow the project release skill: changelog, version bump, PR, merge, tag, publish verify.",
+    inputSchema: "bump?: patch|minor|major",
+    outputKind: "release",
+    replayable: true,
+    checks: ["pnpm check", "PR checks", "release.yml", "npm view"],
+    steps: [
+      {
+        id: "preflight",
+        description: "Verify branch, clean tree, GitHub auth, and remote state.",
+        requiredTools: ["git_status", "bash_exec"],
+        risk: "destructive"
+      },
+      {
+        id: "version",
+        description: "Update changelog and package versions using the release skill.",
+        requiredTools: ["read_file", "edit_file", "bash_exec"],
+        risk: "destructive"
+      },
+      {
+        id: "publish",
+        description: "Merge release PR, tag main, and verify release workflow outputs.",
+        requiredTools: ["bash_exec"],
+        risk: "destructive"
+      }
+    ]
+  }
+];
+function createWorkflowCatalog(workflows) {
+  return new WorkflowCatalog(workflows);
+}
+
+// src/runtime/workflow-engine.ts
+var WorkflowEngine = class {
+  constructor(catalog = createWorkflowCatalog(), eventLog = createEventLog()) {
+    this.catalog = catalog;
+    this.eventLog = eventLog;
+  }
+  catalog;
+  eventLog;
+  handlers = /* @__PURE__ */ new Map();
+  registerHandler(workflowId, handler) {
+    if (!this.catalog.get(workflowId)) {
+      throw new Error(`Unknown workflow: ${workflowId}`);
+    }
+    this.handlers.set(workflowId, handler);
+  }
+  createPlan(workflowId, input) {
+    return this.catalog.createPlan(workflowId, input, this.eventLog);
+  }
+  async run(request) {
+    const workflow = this.catalog.get(request.workflowId);
+    if (!workflow) {
+      throw new Error(`Unknown workflow: ${request.workflowId}`);
+    }
+    const handler = this.handlers.get(request.workflowId);
+    if (!handler) {
+      throw new Error(`No handler registered for workflow: ${request.workflowId}`);
+    }
+    const plan = request.plan ?? this.createPlan(request.workflowId, request.input);
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const runId = `${request.workflowId}-run-${Date.now().toString(36)}`;
+    this.eventLog.record("workflow.started", {
+      workflowId: request.workflowId,
+      planId: plan.id,
+      runId
+    });
+    try {
+      const output = await handler(request.input, {
+        workflow,
+        plan,
+        eventLog: this.eventLog
+      });
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const result = {
+        id: runId,
+        workflowId: request.workflowId,
+        status: "completed",
+        output,
+        startedAt,
+        completedAt
+      };
+      this.eventLog.record("workflow.completed", {
+        workflowId: request.workflowId,
+        planId: plan.id,
+        runId
+      });
+      return result;
+    } catch (error) {
+      const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+      const message = error instanceof Error ? error.message : String(error);
+      this.eventLog.record("workflow.failed", {
+        workflowId: request.workflowId,
+        planId: plan.id,
+        runId,
+        error: message
+      });
+      return {
+        id: runId,
+        workflowId: request.workflowId,
+        status: "failed",
+        output: null,
+        startedAt,
+        completedAt,
+        error: message
+      };
+    }
+  }
+};
+function createWorkflowEngine(catalog, eventLog) {
+  return new WorkflowEngine(catalog, eventLog);
+}
 
 // src/runtime/agent-runtime.ts
 var AgentRuntime = class {
@@ -57573,9 +58231,12 @@ var AgentRuntime = class {
     this.options = options;
     this.providerRegistry = createProviderRegistry();
     this.toolRegistry = options.toolRegistry ?? createFullToolRegistry();
-    this.sessionStore = options.sessionStore ?? createSessionStore({});
-    this.permissionPolicy = options.permissionPolicy ?? createPermissionPolicy();
+    this.sessionStore = options.sessionStore;
+    this.runtimeSessionStore = options.runtimeSessionStore ?? createRuntimeSessionStore();
     this.eventLog = options.eventLog ?? (options.eventLogPath ? createFileEventLog(options.eventLogPath) : createEventLog());
+    this.workflowEngine = options.workflowEngine ?? createWorkflowEngine(void 0, this.eventLog);
+    this.permissionPolicy = options.permissionPolicy ?? createPermissionPolicy();
+    this.turnRunner = options.turnRunner ?? createDefaultRuntimeTurnRunner();
     this.providerType = options.providerType;
     this.model = options.model ?? options.providerConfig?.model ?? getDefaultModel(options.providerType);
   }
@@ -57583,16 +58244,21 @@ var AgentRuntime = class {
   providerRegistry;
   toolRegistry;
   sessionStore;
+  runtimeSessionStore;
+  workflowEngine;
   permissionPolicy;
   eventLog;
+  turnRunner;
   providerType;
   model;
+  provider;
   async initialize() {
     const providerInjected = Boolean(this.options.provider);
     const provider = this.options.provider ?? await this.providerRegistry.createProvider(this.providerType, {
       ...this.options.providerConfig,
       model: this.getModel()
     });
+    this.provider = provider;
     this.publishToGlobalBridge(provider);
     this.eventLog.record(providerInjected ? "provider.attached" : "provider.created", {
       provider: this.providerType,
@@ -57607,6 +58273,7 @@ var AgentRuntime = class {
   updateProvider(providerType, model2, provider) {
     this.providerType = providerType;
     this.model = model2 ?? getDefaultModel(providerType);
+    this.provider = provider;
     this.publishToGlobalBridge(provider);
     this.eventLog.record("provider.updated", {
       provider: this.providerType,
@@ -57634,7 +58301,276 @@ var AgentRuntime = class {
       modes: listAgentModes()
     };
   }
-  assertToolAllowed(mode, toolName) {
+  createSession(options = {}) {
+    const session = this.runtimeSessionStore.create(options);
+    this.eventLog.record("session.created", {
+      sessionId: session.id,
+      mode: session.mode,
+      metadataKeys: Object.keys(session.metadata).sort()
+    });
+    return session;
+  }
+  getSession(sessionId) {
+    return this.runtimeSessionStore.get(sessionId);
+  }
+  listSessions() {
+    return this.runtimeSessionStore.list();
+  }
+  async runTurn(input) {
+    const provider = this.provider;
+    if (!provider) {
+      throw new Error("Runtime provider is not initialized.");
+    }
+    const session = input.sessionId ? this.runtimeSessionStore.get(input.sessionId) : this.createSession({ mode: input.mode, metadata: input.metadata });
+    if (!session) {
+      throw new Error(`Runtime session not found: ${input.sessionId}`);
+    }
+    const effectiveSession = input.mode && input.mode !== session.mode ? { ...session, mode: input.mode } : session;
+    this.eventLog.record("turn.started", {
+      sessionId: effectiveSession.id,
+      provider: this.providerType,
+      model: this.getModel(),
+      mode: effectiveSession.mode,
+      runtimeApi: true
+    });
+    try {
+      const result = await this.turnRunner.run(input, {
+        runtime: this,
+        session: effectiveSession,
+        provider,
+        toolRegistry: this.toolRegistry,
+        permissionPolicy: this.permissionPolicy,
+        eventLog: this.eventLog
+      });
+      const updatedSession = this.runtimeSessionStore.update({
+        ...effectiveSession,
+        messages: [
+          ...effectiveSession.messages,
+          { role: "user", content: input.content },
+          { role: "assistant", content: result.content }
+        ]
+      });
+      this.eventLog.record("session.updated", {
+        sessionId: updatedSession.id,
+        messages: updatedSession.messages.length
+      });
+      this.eventLog.record("turn.completed", {
+        sessionId: updatedSession.id,
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        model: result.model,
+        runtimeApi: true
+      });
+      return { ...result, sessionId: updatedSession.id, mode: updatedSession.mode };
+    } catch (error) {
+      this.eventLog.record("turn.failed", {
+        sessionId: effectiveSession.id,
+        error: error instanceof Error ? error.message : String(error),
+        runtimeApi: true
+      });
+      throw error;
+    }
+  }
+  async *streamTurn(input) {
+    const provider = this.provider;
+    if (!provider) {
+      throw new Error("Runtime provider is not initialized.");
+    }
+    const session = input.sessionId ? this.runtimeSessionStore.get(input.sessionId) : this.createSession({ mode: input.mode, metadata: input.metadata });
+    if (!session) {
+      throw new Error(`Runtime session not found: ${input.sessionId}`);
+    }
+    const effectiveSession = input.mode && input.mode !== session.mode ? { ...session, mode: input.mode } : session;
+    const messages = [
+      ...effectiveSession.messages,
+      {
+        role: "user",
+        content: input.content
+      }
+    ];
+    this.eventLog.record("turn.started", {
+      sessionId: effectiveSession.id,
+      provider: this.providerType,
+      model: this.getModel(),
+      mode: effectiveSession.mode,
+      streaming: true,
+      runtimeApi: true
+    });
+    let content = "";
+    let completed = false;
+    let failed = false;
+    try {
+      for await (const chunk of provider.stream(messages, {
+        model: input.options?.model,
+        maxTokens: input.options?.maxTokens,
+        temperature: input.options?.temperature,
+        stopSequences: input.options?.stopSequences,
+        system: effectiveSession.instructions ?? input.options?.system,
+        timeout: input.options?.timeout,
+        signal: input.options?.signal,
+        thinking: input.options?.thinking
+      })) {
+        if (chunk.type === "text" && chunk.text) {
+          content += chunk.text;
+          yield {
+            type: "text",
+            sessionId: effectiveSession.id,
+            text: chunk.text
+          };
+        }
+      }
+      const updatedSession = this.runtimeSessionStore.update({
+        ...effectiveSession,
+        messages: [
+          ...effectiveSession.messages,
+          { role: "user", content: input.content },
+          { role: "assistant", content }
+        ]
+      });
+      const result = {
+        sessionId: updatedSession.id,
+        content,
+        usage: {
+          inputTokens: provider.countTokens(input.content),
+          outputTokens: provider.countTokens(content),
+          estimated: true
+        },
+        model: input.options?.model ?? this.getModel(),
+        mode: updatedSession.mode
+      };
+      this.eventLog.record("session.updated", {
+        sessionId: updatedSession.id,
+        messages: updatedSession.messages.length
+      });
+      this.eventLog.record("turn.completed", {
+        sessionId: updatedSession.id,
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        model: result.model,
+        streaming: true,
+        runtimeApi: true
+      });
+      completed = true;
+      yield { type: "done", sessionId: updatedSession.id, result };
+    } catch (error) {
+      failed = true;
+      const message = error instanceof Error ? error.message : String(error);
+      this.eventLog.record("turn.failed", {
+        sessionId: effectiveSession.id,
+        error: message,
+        streaming: true,
+        runtimeApi: true
+      });
+      yield {
+        type: "error",
+        sessionId: effectiveSession.id,
+        error: message
+      };
+    } finally {
+      if (!completed && !failed) {
+        this.eventLog.record("turn.cancelled", {
+          sessionId: effectiveSession.id,
+          outputTokens: provider.countTokens(content),
+          streaming: true,
+          runtimeApi: true
+        });
+      }
+    }
+  }
+  async executeTool(input) {
+    const startedAt = performance.now();
+    const session = input.sessionId ? this.getSession(input.sessionId) : void 0;
+    if (input.sessionId && !session) {
+      const decision2 = {
+        allowed: false,
+        reason: `Runtime session not found: ${input.sessionId}`,
+        risk: "read-only"
+      };
+      this.eventLog.record("tool.blocked", {
+        sessionId: input.sessionId,
+        mode: input.mode ?? "ask",
+        tool: input.toolName,
+        reason: decision2.reason,
+        runtimeApi: true
+      });
+      return {
+        toolName: input.toolName,
+        success: false,
+        error: decision2.reason,
+        duration: performance.now() - startedAt,
+        decision: decision2
+      };
+    }
+    const mode = input.mode ?? session?.mode ?? "ask";
+    const tool = this.toolRegistry.get(input.toolName);
+    if (!tool) {
+      const decision2 = {
+        allowed: false,
+        reason: "Tool not registered.",
+        risk: "read-only"
+      };
+      this.eventLog.record("tool.blocked", {
+        sessionId: input.sessionId,
+        mode,
+        tool: input.toolName,
+        reason: decision2.reason,
+        runtimeApi: true
+      });
+      return {
+        toolName: input.toolName,
+        success: false,
+        error: decision2.reason,
+        duration: performance.now() - startedAt,
+        decision: decision2
+      };
+    }
+    const decision = this.permissionPolicy.canExecuteToolInput ? this.permissionPolicy.canExecuteToolInput(mode, tool, input.input) : this.permissionPolicy.canExecuteTool(mode, tool);
+    if (!decision.allowed || decision.requiresConfirmation && input.confirmed !== true) {
+      const reason = decision.reason ?? (decision.requiresConfirmation ? "Tool requires explicit runtime confirmation." : "Tool is not allowed.");
+      this.eventLog.record("tool.blocked", {
+        sessionId: input.sessionId,
+        mode,
+        tool: input.toolName,
+        reason,
+        risk: decision.risk,
+        requiresConfirmation: decision.requiresConfirmation,
+        runtimeApi: true
+      });
+      return {
+        toolName: input.toolName,
+        success: false,
+        error: reason,
+        duration: performance.now() - startedAt,
+        decision
+      };
+    }
+    this.eventLog.record("tool.started", {
+      sessionId: input.sessionId,
+      mode,
+      tool: input.toolName,
+      risk: decision.risk,
+      runtimeApi: true,
+      metadataKeys: Object.keys(input.metadata ?? {}).sort()
+    });
+    const result = await this.toolRegistry.execute(input.toolName, input.input);
+    this.eventLog.record("tool.completed", {
+      sessionId: input.sessionId,
+      mode,
+      tool: input.toolName,
+      success: result.success,
+      duration: result.duration,
+      runtimeApi: true
+    });
+    return {
+      toolName: input.toolName,
+      success: result.success,
+      output: result.data,
+      error: result.error,
+      duration: result.duration,
+      decision
+    };
+  }
+  assertToolAllowed(mode, toolName, input) {
     const tool = this.toolRegistry.get(toolName);
     if (!tool) {
       this.eventLog.record("tool.blocked", {
@@ -57644,7 +58580,7 @@ var AgentRuntime = class {
       });
       return false;
     }
-    const decision = this.permissionPolicy.canExecuteTool(mode, tool);
+    const decision = input && this.permissionPolicy.canExecuteToolInput ? this.permissionPolicy.canExecuteToolInput(mode, tool, input) : this.permissionPolicy.canExecuteTool(mode, tool);
     this.eventLog.record(decision.allowed ? "tool.allowed" : "tool.blocked", {
       mode,
       tool: toolName,
@@ -57659,6 +58595,118 @@ async function createAgentRuntime(options) {
   return runtime;
 }
 
+// src/runtime/tool-calling-turn-runner.ts
+function runtimeWithTools(runtime) {
+  if (runtime && typeof runtime === "object" && "executeTool" in runtime && typeof runtime.executeTool === "function") {
+    return runtime;
+  }
+  throw new Error("ToolCallingRuntimeTurnRunner requires a runtime with executeTool().");
+}
+function toolResultToContent(result) {
+  if (!result.success) {
+    return `Error: ${result.error ?? "Tool failed."}`;
+  }
+  if (typeof result.output === "string") return result.output;
+  return JSON.stringify(result.output ?? null);
+}
+var ToolCallingRuntimeTurnRunner = class {
+  maxToolIterations;
+  constructor(options = {}) {
+    this.maxToolIterations = options.maxToolIterations ?? 10;
+  }
+  async run(input, context) {
+    const runtime = runtimeWithTools(context.runtime);
+    const messages = [
+      ...context.session.messages,
+      {
+        role: "user",
+        content: input.content
+      }
+    ];
+    const tools = context.toolRegistry.getToolDefinitionsForLLM();
+    const confirmedTools = new Set(input.confirmedTools ?? []);
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let lastModel = input.options?.model ?? context.provider.id;
+    for (let iteration = 0; iteration < this.maxToolIterations; iteration++) {
+      const response = await context.provider.chatWithTools(messages, {
+        tools,
+        model: input.options?.model,
+        maxTokens: input.options?.maxTokens,
+        temperature: input.options?.temperature,
+        stopSequences: input.options?.stopSequences,
+        system: context.session.instructions ?? input.options?.system,
+        timeout: input.options?.timeout,
+        signal: input.options?.signal,
+        thinking: input.options?.thinking
+      });
+      inputTokens += response.usage.inputTokens;
+      outputTokens += response.usage.outputTokens;
+      lastModel = response.model;
+      if (response.stopReason !== "tool_use" || response.toolCalls.length === 0) {
+        return {
+          sessionId: context.session.id,
+          content: response.content,
+          usage: { inputTokens, outputTokens },
+          model: response.model,
+          mode: context.session.mode
+        };
+      }
+      const assistantContent = [];
+      if (response.content.trim().length > 0) {
+        assistantContent.push({ type: "text", text: response.content });
+      }
+      for (const toolCall of response.toolCalls) {
+        assistantContent.push({
+          type: "tool_use",
+          id: toolCall.id,
+          name: toolCall.name,
+          input: toolCall.input,
+          geminiThoughtSignature: toolCall.geminiThoughtSignature
+        });
+      }
+      messages.push({
+        role: "assistant",
+        content: assistantContent
+      });
+      const toolResults = [];
+      for (const toolCall of response.toolCalls) {
+        const result = await runtime.executeTool({
+          sessionId: context.session.id,
+          mode: context.session.mode,
+          toolName: toolCall.name,
+          input: toolCall.input,
+          confirmed: confirmedTools.has(toolCall.name),
+          metadata: input.metadata
+        });
+        toolResults.push({
+          type: "tool_result",
+          tool_use_id: toolCall.id,
+          content: toolResultToContent(result),
+          is_error: !result.success
+        });
+      }
+      messages.push({
+        role: "user",
+        content: toolResults
+      });
+    }
+    return {
+      sessionId: context.session.id,
+      content: "The tool-calling runtime reached its maximum tool iteration budget.",
+      usage: { inputTokens, outputTokens },
+      model: lastModel,
+      mode: context.session.mode
+    };
+  }
+};
+function createToolCallingRuntimeTurnRunner(options) {
+  return new ToolCallingRuntimeTurnRunner(options);
+}
+
+// src/runtime/blueprints.ts
+init_registry4();
+
 // src/cli/repl/index.ts
 init_version();
 init_trust_store();
@@ -59493,12 +60541,43 @@ ${stdinContent}
       model: session.config.provider.model || void 0,
       provider,
       eventLogPath: path39__default.join(options.projectPath, ".coco", "events", `${session.id}.jsonl`),
+      turnRunner: options.useRuntimeRunner ? createToolCallingRuntimeTurnRunner() : void 0,
       publishToGlobalBridge: true
     });
     session.runtime = runtime;
     const toolRegistry = runtime.toolRegistry;
     await loadAllowedPaths(options.projectPath);
     await initializeContextManager(session, provider);
+    if (options.useRuntimeRunner) {
+      const runtimeSession = runtime.createSession({
+        id: session.id,
+        mode: "build",
+        instructions: session.config.agent.systemPrompt || void 0,
+        metadata: {
+          surface: "cli",
+          product: "coco-code",
+          execution: "headless-runtime-runner"
+        }
+      });
+      const result2 = await runtime.runTurn({
+        sessionId: runtimeSession.id,
+        content: task,
+        metadata: { surface: "cli", product: "coco-code" }
+      });
+      const events = runtime.eventLog.list();
+      const headlessResult2 = {
+        success: true,
+        output: result2.content,
+        toolsExecuted: events.filter((event) => event.type === "tool.completed").length,
+        usage: result2.usage
+      };
+      if (options.outputFormat === "json") {
+        process.stdout.write(JSON.stringify(headlessResult2, null, 2) + "\n");
+      } else {
+        process.stdout.write(result2.content + "\n");
+      }
+      return headlessResult2;
+    }
     const result = await executeAgentTurn(session, task, provider, toolRegistry, {
       skipConfirmation: true,
       // No interactive confirmations in headless mode
@@ -59564,7 +60643,10 @@ program.command("setup").description("Configure AI provider and API key").action
     console.log("\n\u274C Setup cancelled.");
   }
 });
-program.command("chat", { isDefault: true }).description("Start interactive chat session with the agent").option("-m, --model <model>", "LLM model to use").option("--provider <provider>", "LLM provider (anthropic, openai, codex, gemini, kimi)").option("--editor-model <model>", "Cheap model for file edits (architect/editor split)").option("--weak-model <model>", "Cheap model for background tasks (compaction, summaries)").option("-p, --path <path>", "Project path", process.cwd()).option("-P, --print [task]", "Headless mode: run task and print output (no interactive UI)").option("--output <format>", "Output format for headless mode (text or json)", "text").option("--setup", "Run setup wizard before starting").action(
+program.command("chat", { isDefault: true }).description("Start interactive chat session with the agent").option("-m, --model <model>", "LLM model to use").option("--provider <provider>", "LLM provider (anthropic, openai, codex, gemini, kimi)").option("--editor-model <model>", "Cheap model for file edits (architect/editor split)").option("--weak-model <model>", "Cheap model for background tasks (compaction, summaries)").option("-p, --path <path>", "Project path", process.cwd()).option("-P, --print [task]", "Headless mode: run task and print output (no interactive UI)").option(
+  "--runtime-runner",
+  "Experimental: run headless tasks through the reusable runtime tool-calling runner"
+).option("--output <format>", "Output format for headless mode (text or json)", "text").option("--setup", "Run setup wizard before starting").action(
   async (options) => {
     if (options.setup) {
       const result = await runOnboardingV2();
@@ -59581,6 +60663,7 @@ program.command("chat", { isDefault: true }).description("Start interactive chat
         task,
         projectPath: options.path,
         outputFormat: options.output === "json" ? "json" : "text",
+        useRuntimeRunner: options.runtimeRunner === true,
         config: {
           provider: {
             type: providerType,