@multiclawcli/core 0.4.0 → 0.5.1

package/dist/index.js

@@ -16,6 +16,7 @@ var TASK = `## Architecture Design
 
 ## API Specification
 {{file:api-spec.md}}
+{{upstreamOutputs}}
 
 ## Task
 Review the architecture design and API specification above. Output arch-review.md:
@@ -93,6 +94,7 @@ var TASK2 = `## Project
 ## Pipeline Agents
 The following agents will run in this pipeline (id: name):
 {{pipelineAgents}}
+{{upstreamOutputs}}
 
 ## Task
 Analyze the requirement and create three files in the current directory:
@@ -112,6 +114,7 @@ function architect(overrides) {
     name: "Architect",
     icon: "\u25C6",
     description: "designs the architecture",
+    role: "planner",
     runtime: "acp",
     models: { acp: "opus" },
     modelTier: "strong",
@@ -141,6 +144,7 @@ var TASK3 = `## Task Scope
 
 ## Plan
 {{agentPlan}}
+{{upstreamOutputs}}
 
 ---
 
@@ -200,6 +204,7 @@ var TASK4 = `## Project
 
 ## API Specification
 {{file:api-spec.md}}
+{{upstreamOutputs}}
 
 ## Task
 Perform a thorough code review of all implementation in the current directory and output code-review.md:
@@ -252,6 +257,7 @@ var TASK5 = `## Task Scope
 
 ## Plan
 {{agentPlan}}
+{{upstreamOutputs}}
 
 ---
 
@@ -302,6 +308,7 @@ var TASK6 = `## Task Scope
 
 ## Plan
 {{agentPlan}}
+{{upstreamOutputs}}
 
 ---
 
@@ -356,7 +363,7 @@ The console hands you the turns that came before this one. A requirement is ofte
 Output ONLY a single JSON object on its own line \u2014 no prose, no markdown fences:
 {"mode": "reply", "message": "your answer"}
 {"mode": "ask", "message": "your question"}
-{"mode": "run", "run": ["agent-id-1", "agent-id-2"]}`;
+{"mode": "run", "reason": "one sentence on why this set", "run": ["agent-id-1", "agent-id-2"]}`;
 var TASK7 = `## Project
 {{projectName}}
 
@@ -371,7 +378,7 @@ Read the codebase to understand the current state, then decide how to handle the
 Output a single JSON object \u2014 exactly one of:
 {"mode": "reply", "message": "your answer"}
 {"mode": "ask", "message": "your question"}
-{"mode": "run", "run": ["agent-id", ...]}
+{"mode": "run", "reason": "one sentence on why this set", "run": ["agent-id", ...]}
 Agent IDs must come from the Available Agents list above.`;
 function leader(overrides) {
   return {
@@ -403,6 +410,7 @@ Deliverables (save to the working directory):
 Principles: Output the document directly without preamble. Mark uncertain items as OP- (open questions) rather than guessing. Do not do technical architecture design. Do not write feature code.`;
 var TASK8 = `## Business Context
 {{requirement}}
+{{upstreamOutputs}}
 
 ## Task
 Based on the context above, create requirements.md in the current directory containing:
@@ -448,6 +456,7 @@ var TASK9 = `## Project
 
 ## Requirement
 {{requirement}}
+{{upstreamOutputs}}
 
 ## Task
 Perform an independent code review of all implementation in the current directory and output review.md:
@@ -494,6 +503,7 @@ var TASK10 = `## Task Scope
 
 ## Plan
 {{agentPlan}}
+{{upstreamOutputs}}
 
 ---
 
@@ -548,6 +558,7 @@ var TASK11 = `## Requirement
 
 ## UI Design Specification
 {{file:ui-design.md}}
+{{upstreamOutputs}}
 
 ## Task
 Review the UI design specification above and output ui-review.md:
@@ -596,6 +607,7 @@ var TASK12 = `## Task Scope
 
 ## Plan
 {{agentPlan}}
+{{upstreamOutputs}}
 
 ---
 
@@ -684,112 +696,6 @@ var EventBus = class {
 import * as fs4 from "fs";
 import * as path5 from "path";
 
-// src/utils/conversation.ts
-var MAX_CONVERSATION_TURNS = 6;
-var MAX_CONVERSATION_CHARS = 4e3;
-var MAX_ENTRY_CHARS = 600;
-var ELLIPSIS = "\u2026";
-function clip(text, max) {
-  const trimmed = text.trim();
-  if (trimmed.length <= max) return trimmed;
-  return `${trimmed.slice(0, Math.max(0, max - 1)).trimEnd()}${ELLIPSIS}`;
-}
-function entry(turn, index) {
-  const lines = [`${index}. user: ${clip(turn.requirement, MAX_ENTRY_CHARS)}`];
-  if (turn.reply) {
-    const verb = turn.reply.mode === "ask" ? "asked" : "answered";
-    lines.push(`   you ${verb}: ${clip(turn.reply.message, MAX_ENTRY_CHARS)}`);
-  }
-  return lines.join("\n");
-}
-function renderConversation(history) {
-  if (!history || history.length === 0) return "";
-  const recent = history.slice(-MAX_CONVERSATION_TURNS);
-  const first = history.length - recent.length;
-  const entries = recent.map((turn, i) => entry(turn, first + i + 1));
-  while (entries.length > 1 && entries.join("\n").length > MAX_CONVERSATION_CHARS) {
-    entries.shift();
-  }
-  const body = clip(entries.join("\n"), MAX_CONVERSATION_CHARS);
-  return `
-## Conversation so far
-
-Earlier turns of this session, oldest first:
-
-${body}
-`;
-}
-
-// src/utils/json.ts
-function extractJsonObjects(text) {
-  const objects = [];
-  let searchFrom = 0;
-  while (searchFrom < text.length) {
-    const start = text.indexOf("{", searchFrom);
-    if (start === -1) break;
-    const end = findMatchingBrace(text, start);
-    if (end !== -1) {
-      try {
-        objects.push(JSON.parse(text.slice(start, end + 1)));
-        searchFrom = end + 1;
-        continue;
-      } catch {
-      }
-    }
-    searchFrom = start + 1;
-  }
-  return objects;
-}
-function findMatchingBrace(text, start) {
-  let depth = 0;
-  let inString = false;
-  let escaped = false;
-  for (let i = start; i < text.length; i++) {
-    const ch = text[i];
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (ch === "\\") escaped = true;
-      else if (ch === '"') inString = false;
-      continue;
-    }
-    if (ch === '"') inString = true;
-    else if (ch === "{") depth++;
-    else if (ch === "}") {
-      depth--;
-      if (depth === 0) return i;
-    }
-  }
-  return -1;
-}
-
-// src/utils/leaderDecision.ts
-function parseLeaderDecision(text) {
-  for (const value of extractJsonObjects(text)) {
-    const decision = asDecision(value);
-    if (decision) return decision;
-  }
-  return void 0;
-}
-function asDecision(value) {
-  if (typeof value !== "object" || value === null) return void 0;
-  const record = value;
-  const mode = record.mode;
-  if (mode === "reply" || mode === "ask") {
-    const message = typeof record.message === "string" ? record.message.trim() : "";
-    return message ? { mode, message } : void 0;
-  }
-  if (mode === "run" || mode === void 0) {
-    const run = record.run;
-    if (!Array.isArray(run) || !run.every((id) => typeof id === "string")) return void 0;
-    return { mode: "run", run };
-  }
-  return void 0;
-}
-
-// src/orchestrator/AgentRunner.ts
-import * as fs3 from "fs";
-import * as path4 from "path";
-
 // src/providers/catalog.ts
 import * as path from "path";
 function normalizeCommandKey(command) {
@@ -933,7 +839,10 @@ function resolveCommand(agent, config) {
   return agent.command ?? config.defaults?.command ?? specForProvider(resolveProvider(agent, config))?.command ?? DEFAULT_COMMAND;
 }
 function resolveArgs(agent, config) {
-  return agent.args ?? specForProvider(resolveProvider(agent, config))?.args;
+  if (agent.args) return agent.args;
+  const command = agent.command ?? config.defaults?.command;
+  if (command) return specForCommand(command)?.args;
+  return specForProvider(resolveProvider(agent, config))?.args;
 }
 function resolveModel(agent, config) {
   if (agent.model) return agent.model;
@@ -960,6 +869,153 @@ function resolveAgentRuntime(agent, config) {
   };
 }
 
+// src/utils/conversation.ts
+var MAX_CONVERSATION_TURNS = 6;
+var MAX_CONVERSATION_CHARS = 4e3;
+var MAX_ENTRY_CHARS = 600;
+var ELLIPSIS = "\u2026";
+function clip(text, max) {
+  const trimmed = text.trim();
+  if (trimmed.length <= max) return trimmed;
+  return `${trimmed.slice(0, Math.max(0, max - 1)).trimEnd()}${ELLIPSIS}`;
+}
+function entry(turn, index) {
+  const lines = [`${index}. user: ${clip(turn.requirement, MAX_ENTRY_CHARS)}`];
+  if (turn.reply) {
+    const verb = turn.reply.mode === "ask" ? "asked" : "answered";
+    lines.push(`   you ${verb}: ${clip(turn.reply.message, MAX_ENTRY_CHARS)}`);
+  }
+  return lines.join("\n");
+}
+function renderConversation(history) {
+  if (!history || history.length === 0) return "";
+  const recent = history.slice(-MAX_CONVERSATION_TURNS);
+  const first = history.length - recent.length;
+  const entries = recent.map((turn, i) => entry(turn, first + i + 1));
+  while (entries.length > 1 && entries.join("\n").length > MAX_CONVERSATION_CHARS) {
+    entries.shift();
+  }
+  const body = clip(entries.join("\n"), MAX_CONVERSATION_CHARS);
+  return `
+## Conversation so far
+
+Earlier turns of this session, oldest first:
+
+${body}
+`;
+}
+
+// src/utils/json.ts
+function extractJsonObjects(text) {
+  const objects = [];
+  let searchFrom = 0;
+  while (searchFrom < text.length) {
+    const start = text.indexOf("{", searchFrom);
+    if (start === -1) break;
+    const end = findMatchingBrace(text, start);
+    if (end !== -1) {
+      try {
+        objects.push(JSON.parse(text.slice(start, end + 1)));
+        searchFrom = end + 1;
+        continue;
+      } catch {
+      }
+    }
+    searchFrom = start + 1;
+  }
+  return objects;
+}
+function findMatchingBrace(text, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+// src/utils/leaderDecision.ts
+function parseLeaderDecision(text) {
+  for (const value of extractJsonObjects(text)) {
+    const decision = asDecision(value);
+    if (decision) return decision;
+  }
+  return void 0;
+}
+function asDecision(value) {
+  if (typeof value !== "object" || value === null) return void 0;
+  const record = value;
+  const mode = record.mode;
+  if (mode === "reply" || mode === "ask") {
+    const message = typeof record.message === "string" ? record.message.trim() : "";
+    return message ? { mode, message } : void 0;
+  }
+  if (mode === "run" || mode === void 0) {
+    const run = record.run;
+    if (!Array.isArray(run) || !run.every((id) => typeof id === "string")) return void 0;
+    const reason = typeof record.reason === "string" ? record.reason.trim() : "";
+    return reason ? { mode: "run", run, reason } : { mode: "run", run };
+  }
+  return void 0;
+}
+
+// src/utils/upstream.ts
+var MAX_UPSTREAM_ENTRY_CHARS = 600;
+var MAX_UPSTREAM_CHARS = 4e3;
+var ELLIPSIS2 = "\u2026";
+var HEADER = "\n## What upstream produced\n\n";
+var TRAILER = "\n";
+function block(entries) {
+  return `${HEADER}${entries.join("\n")}${TRAILER}`;
+}
+function compact(text, max) {
+  const trimmed = text.trim();
+  if (trimmed.length <= max) return trimmed;
+  const marker = (count) => `${ELLIPSIS2} (${count} characters elided) ${ELLIPSIS2}`;
+  const reserved = marker(trimmed.length).length;
+  const keep = Math.max(0, max - reserved);
+  const head = Math.ceil(keep / 2);
+  const tail = keep - head;
+  const elided = trimmed.length - keep;
+  return `${trimmed.slice(0, head)}${marker(elided)}${trimmed.slice(trimmed.length - tail)}`;
+}
+function entry2(output) {
+  const label = `- ${output.name} (${output.agentId}):
+  `;
+  const budget = MAX_UPSTREAM_ENTRY_CHARS - label.length;
+  let body = compact(output.output, budget);
+  const newlines = body.length - body.replace(/\n/g, "").length;
+  if (label.length + body.length + 2 * newlines > MAX_UPSTREAM_ENTRY_CHARS) {
+    body = compact(output.output, budget - 2 * newlines);
+  }
+  return `${label}${body.replace(/\n/g, "\n  ")}`;
+}
+function renderUpstreamOutputs(outputs) {
+  if (outputs.length === 0) return "";
+  const entries = outputs.map(entry2);
+  while (entries.length > 1 && block(entries).length > MAX_UPSTREAM_CHARS) {
+    entries.shift();
+  }
+  return block(entries);
+}
+
+// src/orchestrator/AgentRunner.ts
+import * as fs3 from "fs";
+import * as path4 from "path";
+
 // src/runtime/AcpRuntime.ts
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
@@ -1019,6 +1075,17 @@ function isAbortError(err) {
   return err instanceof Error && err.name === ABORT_ERROR_NAME;
 }
 
+// src/utils/errors.ts
+var PermanentError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PermanentError";
+  }
+};
+function isPermanent(err) {
+  return err instanceof PermanentError;
+}
+
 // src/runtime/RuntimeBase.ts
 var RuntimeBase = class {
 };
@@ -1103,6 +1170,9 @@ function withAuthHint(acp, err) {
   }
   return error;
 }
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 var AcpRuntime = class extends RuntimeBase {
   constructor() {
     super(...arguments);
@@ -1120,7 +1190,7 @@ var AcpRuntime = class extends RuntimeBase {
       capabilities: {
         ...BASE_CAPABILITIES,
         tools: specForCommand(command)?.tools ?? false,
-        models: (specForCommand(command)?.modelSelection ?? "none") !== "none"
+        models: specForCommand(command)?.modelSelection === "config-option"
       }
     };
   }
@@ -1185,6 +1255,14 @@ ${task.prompt}` : task.prompt;
       const emit = (event) => {
         task.onEvent?.({ ...event, runId, agentId: task.agentId, seq: seq++ });
       };
+      const warn = (message) => {
+        if (task.onWarning) {
+          task.onWarning(message);
+          return;
+        }
+        process.stderr.write(`[multiclaw] Warning: ${message}
+`);
+      };
       let sessionId;
       let agentText = "";
       let errorOutput = "";
@@ -1255,7 +1333,7 @@ ${task.prompt}` : task.prompt;
             break;
           }
           case "plan": {
-            emit({ type: "plan", entries: update.entries.map((entry2) => entry2.content) });
+            emit({ type: "plan", entries: update.entries.map((entry3) => entry3.content) });
             break;
           }
           case "usage_update": {
@@ -1346,7 +1424,7 @@ ${task.prompt}` : task.prompt;
         settleReject(new Error(`${command} exited with code ${code}: ${errorOutput}`));
       });
       child.on("error", (err) => {
-        settleReject(new Error(`Failed to start ${command}: ${err.message}`));
+        settleReject(new PermanentError(`Failed to start ${command}: ${err.message}`));
       });
       const run = async () => {
         const init = await ctx.request(acp.methods.agent.initialize, {
@@ -1355,7 +1433,7 @@ ${task.prompt}` : task.prompt;
         emit({ type: "run_started", model: task.model });
         if (task.sessionId) {
           if (init.agentCapabilities?.loadSession !== true) {
-            throw new Error(
+            throw new PermanentError(
               `Agent does not support session/load (loadSession=false); cannot resume session ${task.sessionId}`
             );
           }
@@ -1389,9 +1467,8 @@ ${task.prompt}` : task.prompt;
         if (task.model && spec?.modelSelection === "config-option" && sessionId) {
           const known = discoveredModels.get(command);
           if (known && !known.includes(task.model)) {
-            process.stderr.write(
-              `[multiclaw] Warning: model "${task.model}" is not offered by ${command}; running with provider default.
-`
+            warn(
+              `model "${task.model}" is not offered by ${command}; running with the provider's default.`
             );
           } else {
             try {
@@ -1400,7 +1477,10 @@ ${task.prompt}` : task.prompt;
                 configId: "model",
                 value: task.model
               });
-            } catch {
+            } catch (err) {
+              warn(
+                `Could not set model "${task.model}" on ${command}; running with the provider's default (${errorMessage(err)}).`
+              );
             }
           }
         }
@@ -1492,6 +1572,7 @@ async function renderPrompt(template, context, workDir) {
 }
 
 // src/utils/retry.ts
+var DEFAULT_RETRY_DELAY_MS = 2e3;
 function sleep(ms, signal) {
   if (signal?.aborted) return Promise.reject(abortError());
   return new Promise((resolve4, reject) => {
@@ -1506,7 +1587,7 @@ function sleep(ms, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
-async function withRetry(fn, retries, onRetry, delayMs = 2e3, signal) {
+async function withRetry(fn, retries, onRetry, delayMs = DEFAULT_RETRY_DELAY_MS, signal, shouldRetry) {
   let lastError = new Error("Unknown error");
   for (let attempt = 1; attempt <= retries + 1; attempt++) {
     if (signal?.aborted) throw abortError();
@@ -1515,6 +1596,7 @@ async function withRetry(fn, retries, onRetry, delayMs = 2e3, signal) {
     } catch (err) {
       lastError = err;
       if (signal?.aborted) throw lastError;
+      if (shouldRetry && !shouldRetry(err, attempt)) throw lastError;
       if (attempt <= retries) {
         onRetry?.(attempt, err);
         await sleep(delayMs * attempt, signal);
@@ -1523,6 +1605,9 @@ async function withRetry(fn, retries, onRetry, delayMs = 2e3, signal) {
   }
   throw lastError;
 }
+function retryBudgetMs(perAttemptMs, retries, delayMs = DEFAULT_RETRY_DELAY_MS) {
+  return perAttemptMs * (retries + 1) + delayMs * retries * (retries + 1) / 2;
+}
 
 // src/utils/timeout.ts
 function withTimeout(factory, ms, label, signal) {
@@ -1550,6 +1635,31 @@ function withTimeout(factory, ms, label, signal) {
   });
 }
 
+// src/utils/toolSummary.ts
+var MAX_SUMMARY_COLUMNS = 120;
+function stringifySafe(value) {
+  if (typeof value === "string") return value;
+  if (value === void 0 || value === null) return "";
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+function firstLineTruncated(value) {
+  const text = stringifySafe(value);
+  const newline = text.indexOf("\n");
+  const firstLine = newline === -1 ? text : text.slice(0, newline);
+  if (firstLine.length <= MAX_SUMMARY_COLUMNS) return firstLine;
+  return `${firstLine.slice(0, MAX_SUMMARY_COLUMNS - 1)}\u2026`;
+}
+function summarizeToolInput(input) {
+  return firstLineTruncated(input);
+}
+function summarizeToolOutput(output) {
+  return firstLineTruncated(output);
+}
+
 // src/orchestrator/AgentRunner.ts
 var AgentRunner = class {
   constructor(eventBus, contextManager, globalWorkDir, config) {
@@ -1574,6 +1684,8 @@ var AgentRunner = class {
     });
     let attempts = 0;
     let output = "";
+    let usage;
+    let costUsd;
     try {
       const workDir = agent.workDir ? path4.resolve(this.globalWorkDir, agent.workDir) : this.globalWorkDir;
       fs3.mkdirSync(workDir, { recursive: true });
@@ -1581,7 +1693,7 @@ var AgentRunner = class {
       const retries = agent.retries ?? 0;
       const timeout = agent.timeout ?? 6e5;
       const tools = agent.tools ?? ["Read", "Write", "Bash"];
-      output = await withTimeout(
+      const completed = await withTimeout(
         (innerSignal) => withRetry(
           async (attempt) => {
             attempts = attempt;
@@ -1596,7 +1708,7 @@ var AgentRunner = class {
               agentPlan: agent.agentPlan ?? "No step-by-step plan was provided \u2014 use your judgement."
             };
             const prompt = await renderPrompt(agent.taskPrompt, agentContext, this.globalWorkDir);
-            return (await runtime.execute({
+            return await runtime.execute({
               agentId: agent.id,
               systemPrompt: agent.systemPrompt,
               prompt,
@@ -1605,6 +1717,11 @@ var AgentRunner = class {
               timeout,
               signal: innerSignal,
               model,
+              // Only the caller knows which session to continue; absent means a
+              // fresh one. It must stay `undefined` rather than `""` — the ACP
+              // runtime tests `if (task.sessionId)`, so an empty string would
+              // read as "load this session" for a session that does not exist.
+              sessionId: this.config.resume?.sessions?.[agent.id],
               // Resolve through provider/defaults exactly as the CLI's
               // availability gate does — an agent that pins `provider` (or
               // leans on `defaults`) must launch that provider's bridge, not
@@ -1612,16 +1729,44 @@ var AgentRunner = class {
               // here sent a `provider: "claude"` config straight to `opencode`.
               command: resolveCommand(agent, this.config),
               args: resolveArgs(agent, this.config),
+              // A runtime's diagnostics travel on the event bus rather than
+              // stderr: under the TUI's alternate screen a stderr write is
+              // never seen. The agent name prefixes the line so it is
+              // locatable in the one-row status area.
+              onWarning: (message) => {
+                this.eventBus.emit({
+                  type: "orchestration:warning",
+                  timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+                  payload: { message: `[${agent.name}] ${message}` }
+                });
+              },
               onEvent: (e) => {
                 if ((e.type === "message_delta" || e.type === "message") && e.role === "agent" && e.text) {
-                  this.eventBus.emit({
-                    type: "agent:output",
-                    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-                    payload: { agentId: agent.id, chunk: e.text }
-                  });
+                  this.emitOutput(agent.id, e.text);
+                  return;
+                }
+                if (e.type === "tool_call") {
+                  const summary = summarizeToolInput(e.input);
+                  this.emitOutput(
+                    agent.id,
+                    `
+\u203A ${e.name}${summary ? ` ${summary}` : ""}
+`,
+                    "tool"
+                  );
+                  return;
+                }
+                if (e.type === "tool_result") {
+                  const summary = summarizeToolOutput(e.output);
+                  this.emitOutput(
+                    agent.id,
+                    `  ${e.isError ? "\u2717" : "\u2713"} ${summary}
+`,
+                    e.isError ? "tool" : "tool-detail"
+                  );
                 }
               }
-            })).output;
+            });
           },
           retries,
           (attempt, err) => {
@@ -1637,13 +1782,21 @@ var AgentRunner = class {
               }
             });
           },
-          2e3,
-          innerSignal
+          DEFAULT_RETRY_DELAY_MS,
+          innerSignal,
+          // A permanent failure (a missing binary, an unsupported capability)
+          // will fail the same way on every attempt, so let the loop fail fast
+          // instead of burning the whole backoff budget on a doomed run.
+          (err) => !isPermanent(err)
         ),
-        timeout,
+        retryBudgetMs(timeout + KILL_ESCALATION_MS, retries),
         agent.name,
         signal
       );
+      output = completed.output;
+      usage = completed.usage;
+      costUsd = completed.costUsd;
+      const sessionId = completed.sessionId;
       const endTime = /* @__PURE__ */ new Date();
       const result = {
         agentId: agent.id,
@@ -1653,7 +1806,11 @@ var AgentRunner = class {
         duration: endTime.getTime() - startTime.getTime(),
         attempts,
         startTime: startTime.toISOString(),
-        endTime: endTime.toISOString()
+        endTime: endTime.toISOString(),
+        model,
+        ...usage ? { usage } : {},
+        ...costUsd !== void 0 ? { costUsd } : {},
+        ...sessionId ? { sessionId } : {}
       };
       this.eventBus.emit({
         type: "agent:complete",
@@ -1666,13 +1823,16 @@ var AgentRunner = class {
       const result = {
         agentId: agent.id,
         agentName: agent.name,
-        status: "failed",
+        // An abort is a cancellation, not a failure: the team stopped because it
+        // was told to, and the roster must not paint every agent as broken.
+        status: isAbortError(err) ? "cancelled" : "failed",
         output,
         duration: endTime.getTime() - startTime.getTime(),
         attempts,
         error: err.message,
         startTime: startTime.toISOString(),
-        endTime: endTime.toISOString()
+        endTime: endTime.toISOString(),
+        model
       };
       this.eventBus.emit({
         type: "agent:failed",
@@ -1682,6 +1842,19 @@ var AgentRunner = class {
       return result;
     }
   }
+  /**
+   * Publish one chunk of agent output.
+   *
+   * `kind` is omitted for text so the payload shape is unchanged for every
+   * consumer written before tool activity was surfaced.
+   */
+  emitOutput(agentId, chunk, kind) {
+    this.eventBus.emit({
+      type: "agent:output",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      payload: { agentId, chunk, ...kind ? { kind } : {} }
+    });
+  }
 };
 
 // src/orchestrator/ContextManager.ts
@@ -1736,8 +1909,33 @@ var Orchestrator = class {
     fs4.mkdirSync(this.workDir, { recursive: true });
     this.contextManager = new ContextManager(config.context);
     this.contextManager.set("conversation", renderConversation(config.history));
+    this.contextManager.set("upstreamOutputs", "");
     this.runner = new AgentRunner(this.eventBus, this.contextManager, this.workDir, config);
   }
+  async preview(options = {}) {
+    this.clearStaleTaskPlan();
+    const resolution = await this.resolveTurn(options.signal);
+    if (resolution.kind === "message") {
+      return {
+        name: this.config.name,
+        totalAgents: 0,
+        stages: [],
+        reply: { mode: resolution.mode, message: resolution.message },
+        ...this.requirementField()
+      };
+    }
+    const agents2 = resolution.agents;
+    this.contextManager.set("pipelineAgents", agents2.map((a) => `${a.id}: ${a.name}`).join("\n"));
+    const stages = this.buildStagesOrFallback(agents2, "Could not order the configured agents");
+    const stageInfos = this.stageInfos(stages);
+    return {
+      name: this.config.name,
+      totalAgents: agents2.length,
+      stages: stageInfos,
+      ...this.reasonField(resolution.reason),
+      ...this.requirementField()
+    };
+  }
   async run(options = {}) {
     const startTime = /* @__PURE__ */ new Date();
     this.clearStaleTaskPlan();
@@ -1749,20 +1947,7 @@ var Orchestrator = class {
     if (agents2.length === 0) return this.finishEmpty(startTime);
     this.contextManager.set("pipelineAgents", agents2.map((a) => `${a.id}: ${a.name}`).join("\n"));
     let stages = this.buildStagesOrFallback(agents2, "Could not order the configured agents");
-    const getModel = (agent) => {
-      return agent.model ?? agent.models?.[agent.runtime ?? "acp"];
-    };
-    const toStageInfos = (list) => list.map((stage, i) => ({
-      stageIndex: i,
-      agents: stage.map((a) => ({
-        id: a.id,
-        name: a.name,
-        icon: a.icon,
-        model: getModel(a),
-        description: a.description,
-        taskTitle: a.taskTitle
-      }))
-    }));
+    const toStageInfos = (list) => this.stageInfos(list);
     this.eventBus.emit({
       type: "orchestration:start",
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1770,12 +1955,14 @@ var Orchestrator = class {
         name: this.config.name,
         requirement: this.config.context?.requirement,
         totalAgents: agents2.length,
-        stages: toStageInfos(stages)
+        stages: toStageInfos(stages),
+        ...this.reasonField(resolution.reason)
       }
     });
     const results = [];
     let allSuccess = true;
     let cancelled = false;
+    let planApplied = false;
     for (let i = 0; i < stages.length; i++) {
       const stage = stages[i];
       this.eventBus.emit({
@@ -1785,12 +1972,19 @@ var Orchestrator = class {
       });
       const stageResults = await this.runStage(stage, options.signal);
       results.push(...stageResults);
+      this.contextManager.set(
+        "upstreamOutputs",
+        renderUpstreamOutputs(
+          results.filter((r) => r.status === "success").map((r) => ({ agentId: r.agentId, name: r.agentName, output: r.output }))
+        )
+      );
       if (options.signal?.aborted) {
         cancelled = true;
         allSuccess = false;
         break;
       }
-      if (i === 0 && stage.some((a) => a.id === "architect") && stageResults.some((r) => r.status === "success")) {
+      if (!planApplied && stage.some((a) => this.isPlanner(a)) && stageResults.some((r) => r.status === "success")) {
+        planApplied = true;
         await this.applyTaskPlan(agents2);
         stages = this.buildStagesOrFallback(
           agents2,
@@ -1827,6 +2021,7 @@ var Orchestrator = class {
       }
     }
     const endTime = /* @__PURE__ */ new Date();
+    const totalCostUsd = sumCosts(results);
     const result = {
       name: this.config.name,
       success: allSuccess,
@@ -1834,7 +2029,10 @@ var Orchestrator = class {
       agentResults: results,
       startTime: startTime.toISOString(),
       endTime: endTime.toISOString(),
-      ...cancelled ? { cancelled: true } : {}
+      ...cancelled ? { cancelled: true } : {},
+      ...totalCostUsd !== void 0 ? { totalCostUsd } : {},
+      ...this.reasonField(resolution.reason),
+      ...this.requirementField()
     };
     this.eventBus.emit({
       type: "orchestration:complete",
@@ -1843,6 +2041,20 @@ var Orchestrator = class {
     });
     return result;
   }
+  stageInfos(stages) {
+    const getModel = (agent) => resolveModel(agent, this.config);
+    return stages.map((stage, i) => ({
+      stageIndex: i,
+      agents: stage.map((a) => ({
+        id: a.id,
+        name: a.name,
+        icon: a.icon,
+        model: getModel(a),
+        description: a.description,
+        taskTitle: a.taskTitle
+      }))
+    }));
+  }
   /**
    * Order the agents into stages, degrading to declaration order if the graph is
    * broken.
@@ -1856,7 +2068,7 @@ var Orchestrator = class {
     try {
       return buildStages(agents2);
     } catch (err) {
-      this.warn(`${context} (${errorMessage(err)}) \u2014 running the agents in declaration order.`);
+      this.warn(`${context} (${errorMessage2(err)}) \u2014 running the agents in declaration order.`);
       return [agents2];
     }
   }
@@ -1880,6 +2092,12 @@ var Orchestrator = class {
    * job, and that is what `message` records.
    */
   async resolveTurn(signal) {
+    if (this.config.resume) {
+      return {
+        kind: "run",
+        agents: this.selectAgents(this.config.resume.agents, "The resume list")
+      };
+    }
     if (!this.config.leader || this.config.useLeader === false) {
       return { kind: "run", agents: this.configuredAgents() };
     }
@@ -1897,7 +2115,7 @@ var Orchestrator = class {
       if (decision.mode !== "run") {
         return { kind: "message", mode: decision.mode, message: decision.message };
       }
-      return { kind: "run", agents: this.selectAgents(decision.run) };
+      return { kind: "run", agents: this.selectAgents(decision.run), reason: decision.reason };
     }
     const message = result.output.trim();
     if (!message) {
@@ -1916,21 +2134,27 @@ var Orchestrator = class {
    * prevent, but for the in-memory fields rather than the file.
    */
   configuredAgents() {
-    return this.config.agents.map((a) => ({ ...a }));
+    return this.config.agents.map(
+      (a) => a.dependsOn ? { ...a, dependsOn: [...a.dependsOn] } : { ...a }
+    );
   }
   /**
-   * Narrow the configured team to the ids the leader named.
+   * Narrow the configured team to the ids `namedBy` asked for.
    *
    * Always a subset: an id that is not in the config is reported and dropped
    * rather than added, so a typo in a prompt cannot conjure an agent that has no
    * definition behind it.
+   *
+   * `namedBy` labels the warning. A resume names agents too — with no leader in
+   * the run at all — so blaming "the leader" for a bad resumed id would send the
+   * reader looking in the wrong place.
    */
-  selectAgents(run) {
+  selectAgents(run, namedBy = "The leader") {
     const runSet = new Set(run);
     const known = new Set(this.config.agents.map((a) => a.id));
     for (const id of run) {
       if (!known.has(id)) {
-        this.warn(`The leader named "${id}", which is not in the config \u2014 ignoring it.`);
+        this.warn(`${namedBy} named "${id}", which is not in the config \u2014 ignoring it.`);
       }
     }
     const skippedIds = new Set(this.config.agents.filter((a) => !runSet.has(a.id)).map((a) => a.id));
@@ -1951,13 +2175,28 @@ var Orchestrator = class {
     if (!maxConcurrency || agents2.length <= maxConcurrency) {
       return Promise.all(agents2.map((a) => this.runner.run(a, signal)));
     }
-    const results = [];
-    for (let i = 0; i < agents2.length; i += maxConcurrency) {
-      const batch = agents2.slice(i, i + maxConcurrency);
-      results.push(...await Promise.all(batch.map((a) => this.runner.run(a, signal))));
-    }
+    const results = new Array(agents2.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(maxConcurrency, agents2.length) }, async () => {
+      while (next < agents2.length) {
+        const index = next;
+        next += 1;
+        results[index] = await this.runner.run(agents2[index], signal);
+      }
+    });
+    await Promise.all(workers);
     return results;
   }
+  /**
+   * Whether `agent` owns task decomposition.
+   *
+   * The explicit `role` is the source of truth, so a config can name its planner
+   * anything. The id `"architect"` is kept as a fallback so every config written
+   * before `role` existed keeps working unchanged.
+   */
+  isPlanner(agent) {
+    return agent.role === "planner" || agent.id === "architect";
+  }
   async applyTaskPlan(agents2) {
     const taskPlanPath = path5.join(this.workDir, "task-plan.json");
     if (!fs4.existsSync(taskPlanPath)) return;
@@ -1966,7 +2205,7 @@ var Orchestrator = class {
       taskPlan = JSON.parse(fs4.readFileSync(taskPlanPath, "utf-8"));
     } catch (err) {
       this.warn(
-        `Could not parse task-plan.json \u2014 continuing with the original agent set: ${errorMessage(err)}`
+        `Could not parse task-plan.json \u2014 continuing with the original agent set: ${errorMessage2(err)}`
       );
       return;
     }
@@ -1996,6 +2235,26 @@ var Orchestrator = class {
       }
     }
   }
+  /**
+   * The `requirement` field for a result, present only when the caller set one.
+   *
+   * Spread into every result builder so all three outcomes carry it the same
+   * way: a completion event doubles as the report a resume driver reads back,
+   * and a requirement that never reaches the report cannot be resumed.
+   */
+  requirementField() {
+    const requirement = this.config.context?.requirement;
+    return requirement !== void 0 ? { requirement } : {};
+  }
+  /**
+   * The `selectionReason` field, present only when the leader explained itself.
+   *
+   * Omitted rather than sent as `undefined`/`""` so a run without an
+   * explanation stays byte-identical to one from before the field existed.
+   */
+  reasonField(reason) {
+    return reason ? { selectionReason: reason } : {};
+  }
   /**
    * Close out a turn the leader answered rather than planned.
    *
@@ -2012,7 +2271,8 @@ var Orchestrator = class {
       agentResults: [],
       startTime: startTime.toISOString(),
       endTime: endTime.toISOString(),
-      reply: { mode, message }
+      reply: { mode, message },
+      ...this.requirementField()
     };
     this.eventBus.emit({
       type: "orchestration:complete",
@@ -2047,7 +2307,8 @@ var Orchestrator = class {
       totalDuration: endTime.getTime() - startTime.getTime(),
       agentResults: [],
       startTime: startTime.toISOString(),
-      endTime: endTime.toISOString()
+      endTime: endTime.toISOString(),
+      ...this.requirementField()
     };
     this.eventBus.emit({
       type: "orchestration:complete",
@@ -2057,9 +2318,20 @@ var Orchestrator = class {
     return result;
   }
 };
-function errorMessage(err) {
+function errorMessage2(err) {
   return err instanceof Error ? err.message : String(err);
 }
+function sumCosts(results) {
+  let total = 0;
+  let reported = false;
+  for (const result of results) {
+    if (typeof result.costUsd === "number") {
+      total += result.costUsd;
+      reported = true;
+    }
+  }
+  return reported ? total : void 0;
+}
 
 // src/providers/detect.ts
 import { spawn as spawn2 } from "child_process";
@@ -2091,21 +2363,28 @@ async function detectProviders(opts) {
     const candidates = [spec.command, ...spec.aliases ?? []];
     let matched;
     let version;
+    let source = "path";
+    let resolvedPath;
     for (const cmd of candidates) {
       const exe = resolveExecutable(cmd);
       if (!exe) continue;
+      const bundled = exe !== cmd;
       if (spec.confirm) {
         if (opts?.withVersion) {
           const v = await versionFor(exe);
           if (v && spec.confirm(v)) {
             matched = cmd;
             version = v;
+            source = bundled ? "bundled" : "path";
+            resolvedPath = bundled ? exe : void 0;
             break;
           }
         }
         continue;
       }
       matched = cmd;
+      source = bundled ? "bundled" : "path";
+      resolvedPath = bundled ? exe : void 0;
       if (opts?.withVersion) {
         version = await versionFor(exe);
       }
@@ -2118,7 +2397,9 @@ async function detectProviders(opts) {
         command: matched,
         status: "present",
         version,
-        note: spec.auth.hint || void 0
+        note: spec.auth.hint || void 0,
+        source,
+        ...resolvedPath !== void 0 ? { resolvedPath } : {}
       });
     } else {
       results.push({
@@ -2135,6 +2416,22 @@ async function detectProviders(opts) {
 function presentProviders(detected) {
   return detected.filter((d) => d.status === "present").map((d) => d.id);
 }
+
+// src/utils/resumePlan.ts
+function describeResumePlan({ agents: agents2, sessions = {}, team }) {
+  const teamById = new Map(team.map((member) => [member.id, member]));
+  const running = new Set(agents2);
+  const clauses = agents2.map(
+    (id) => sessions[id] ? `${id} continues its session` : `${id} starts fresh`
+  );
+  for (const id of agents2) {
+    const dropped = (teamById.get(id)?.dependsOn ?? []).filter(
+      (dep) => teamById.has(dep) && !running.has(dep)
+    );
+    if (dropped.length > 0) clauses.push(`${id} runs without ${dropped.join(", ")}`);
+  }
+  return clauses.join("; ");
+}
 export {
   ABORT_ERROR_NAME,
   AcpRuntime,
@@ -2147,6 +2444,7 @@ export {
   agents,
   buildStages,
   defineConfig,
+  describeResumePlan,
   detectProviders,
   isAbortError,
   presentProviders,