@pi-archimedes/subagent 2.10.4 → 2.11.0

package/src/format.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { truncLine, formatParallelResults } from "./format.js";
+import { formatParallelResults } from "./format.js";
 import type { SubagentResult } from "./types.js";
 
 function makeResult(overrides: Partial<SubagentResult> = {}): SubagentResult {
@@ -17,33 +17,14 @@ function makeResult(overrides: Partial<SubagentResult> = {}): SubagentResult {
   };
 }
 
-// ── truncLine ───────────────────────────────────────────────────────────────
+// ── Row truncation: moved ─────────────────────────────────────────────────
 
-describe("truncLine", () => {
-  it("returns text unchanged when within limit", () => {
-    expect(truncLine("hello", 10)).toBe("hello");
-  });
-
-  it("truncates with '...' when exceeding limit", () => {
-    expect(truncLine("hello world", 8)).toBe("hello...");
-  });
-
-  it("stops at newline boundary instead of bleeding into next line", () => {
-    expect(truncLine("line one\nline two\nline three", 15)).toBe("line one...");
-  });
-
-  it("truncates first line if it itself exceeds limit", () => {
-    expect(truncLine("this is a very long first line\nsecond", 12)).toBe("this is a...");
-  });
-
-  it("handles multiple consecutive newlines", () => {
-    expect(truncLine("a\n\n\nb", 10)).toBe("a...");
-  });
-
-  it("handles text starting with newline", () => {
-    expect(truncLine("\nhello", 10)).toBe("...");
-  });
-});
+// The character cap this section used to pin (`truncLine`, at 60/80 characters)
+// is gone. Rows are now cut at the width pi renders them at, which keeps the two
+// properties the cap existed for — the ellipsis stays inside the styled span, and
+// a newline is a hard boundary — while letting a row fill the frame. Those
+// properties are pinned with measured bytes in `row-block.test.ts`, and the width
+// contract itself in `tool-row.width-audit.test.ts`.
 
 describe("formatParallelResults", () => {
   it("renders header + body per task with exactly one blank line between sections", () => {
@@ -90,9 +71,9 @@ describe("formatParallelResults", () => {
     expect(formatParallelResults([r])).toBe("✗ test-agent 5 tools · 0k tok · 3s\nspawn failed");
   });
 
-  it("prefers finalOutput over error when both are set", () => {
+  it("prefers finalOutput as the body when both are set, and still marks the failure", () => {
     const r = makeResult({ finalOutput: "out", error: "boom" });
-    expect(formatParallelResults([r])).toBe("✓ test-agent 5 tools · 0k tok · 3s\nout");
+    expect(formatParallelResults([r])).toBe("✗ test-agent 5 tools · 0k tok · 3s\nout");
   });
 
   it("keeps internal newlines in a multi-line body and trims only the tail", () => {
@@ -117,3 +98,64 @@ describe("formatParallelResults", () => {
     );
   });
 });
+
+describe("formatParallelResults: run outcomes", () => {
+  it("says truncated on the header row of a cut-off result", () => {
+    const out = formatParallelResults([
+      makeResult({ outcome: "truncated", finalOutput: "partial answer" }),
+    ]);
+    expect(out.split("\n")[0]).toMatch(/truncated/i);
+    expect(out).toContain("partial answer");
+  });
+
+  it("marks a run that failed at exit 0 with ✗, because the exit code is not the signal", () => {
+    // `--mode json` — what the child actually runs — never maps `stopReason`
+    // onto the exit code (that mapping is print mode's text branch), so a child
+    // whose last response errored exits **0**. `streamEvents` reports that as
+    // `error` with no `outcome`; a header that read only `exitCode` handed the
+    // calling model a ✓ for a run that produced nothing, while `index.ts` set
+    // `isError` on the very same result.
+    const out = formatParallelResults([
+      makeResult({ exitCode: 0, error: "401 unauthorized" }),
+    ]);
+    expect(out.split("\n")[0]?.startsWith("✗")).toBe(true);
+    expect(out).toContain("401 unauthorized");
+  });
+
+  it("marks a run the parent cancelled through the bridge (exit 0, error set)", () => {
+    // The bridge contract: a local cancel settles as a FAILED result carrying
+    // error "cancelled" and exitCode 0 — same shape, same wrong ✓ without the
+    // error check.
+    const out = formatParallelResults([
+      makeResult({ exitCode: 0, error: "cancelled" }),
+    ]);
+    expect(out.split("\n")[0]?.startsWith("✗")).toBe(true);
+  });
+
+  it("never shows a success marker for a result the tool reports as an error", () => {
+    // The single assertion that ties the two halves together: `index.ts` decides
+    // `isError` from `error`, so the header has to agree with it.
+    const out = formatParallelResults([
+      makeResult({ exitCode: 0, error: "boom" }),
+      makeResult({ agent: "ok", exitCode: 0, finalOutput: "fine" }),
+    ]);
+    const rows = out.split("\n").filter((l) => l.startsWith("✓") || l.startsWith("✗"));
+    expect(rows[0]).toContain("✗");
+    expect(rows[1]).toContain("✓");
+  });
+
+  it("says aborted on the header row of a cancelled result", () => {
+    const out = formatParallelResults([makeResult({ outcome: "aborted" })]);
+    expect(out.split("\n")[0]).toMatch(/aborted/i);
+  });
+
+  it("leaves a completed header byte-identical to the pre-outcome contract", () => {
+    const r = makeResult({
+      outcome: "completed",
+      agent: "reviewer",
+      progressSummary: { toolCount: 4, tokens: 2000, durationMs: 12000 },
+      finalOutput: "Looks good.",
+    });
+    expect(formatParallelResults([r])).toBe("✓ reviewer 4 tools · 2k tok · 12s\nLooks good.");
+  });
+});

package/src/format.ts

@@ -1,4 +1,4 @@
-import type { SubagentResult } from "./types.js";
+import type { RunOutcome, SubagentResult } from "./types.js";
 
 export function formatTokens(n: number): string {
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
@@ -22,27 +22,6 @@ export function formatCost(cost: number): string {
   return "$" + cost.toFixed(2);
 }
 
-/**
- * Truncate plain text to a max character length, appending "..." if truncated.
- *
- * Unlike truncateToWidth from pi-tui, this does not handle wide characters or
- * measure ANSI display width. The benefit: the "..." is plain text so it
- * inherits any ANSI color wrapper applied around the result (pi-tui's
- * truncateToWidth appends "..." after closing color codes, leaving it unstyled).
- *
- * If the text contains newlines, truncates at the first newline boundary
- * rather than bleeding into the next line.
- */
-export function truncLine(text: string, maxLen: number): string {
-  // Check for newline first — it's a hard boundary regardless of length
-  const nlIdx = text.indexOf("\n");
-  if (nlIdx !== -1) {
-    return text.slice(0, nlIdx).slice(0, maxLen - 3) + "...";
-  }
-  if (text.length <= maxLen) return text;
-  return text.slice(0, maxLen - 3) + "...";
-}
-
 /**
  * Renders one section per parallel result. The header line is intentionally
  * byte-identical to the pre-#55 metrics summary (a contract, not an
@@ -50,20 +29,84 @@ export function truncLine(text: string, maxLen: number): string {
  * (finalOutput ?? error ?? "completed"), `trimEnd()`-ed so sections stay
  * separated by exactly one blank line, and is deliberately untruncated by
  * design (see docs/decisions/0020-subagent-parallel-full-output.md).
+ *
+ * A run that merely completed keeps that header exactly as it was. A truncated
+ * or aborted one says so on the row, because a "✓" the calling model has no way
+ * to check would be the worse kind of lie.
+ *
+ * The failure check reads `error`, not the exit code, and comes before the
+ * success marker: a `--mode json` child whose last response errored **exits 0**
+ * (`stream.ts` turns that into `error` with no `outcome`), and `index.ts` calls
+ * the same result `isError`. A header keyed off `exitCode` alone told the model
+ * the opposite of the flag on the tool result it was reading.
  */
 export function formatParallelResults(results: SubagentResult[]): string {
   const sections = results.map((r) => {
-    const status = r.exitCode === 0 ? "✓" : "✗";
+    const status =
+      r.outcome === "truncated"
+        ? "⚠ truncated"
+        : r.outcome === "aborted"
+          ? "⚠ aborted"
+          : r.error || r.exitCode !== 0
+            ? "✗"
+            : "✓";
     const summary = r.progressSummary
       ? `${r.progressSummary.toolCount} tools · ${Math.round(r.progressSummary.tokens / 1000)}k tok · ${Math.round(r.progressSummary.durationMs / 1000)}s`
       : "";
     const header = `${status} ${r.agent}${summary ? " " + summary : ""}`;
-    const body = (r.finalOutput ?? r.error ?? "completed").trimEnd();
+    const body = (r.finalOutput ?? r.error ?? fallbackBody(r)).trimEnd();
     return `${header}\n${body}`;
   });
   return sections.join("\n\n");
 }
 
+/** What to say when a result has neither output nor an error to show. */
+function fallbackBody(result: SubagentResult): string {
+  return result.outcome ? "(no output)" : "completed";
+}
+
+/**
+ * The single-run result text the calling model reads.
+ *
+ * The outcome is spelled out in words as well as carried in
+ * `details.results[].outcome`, because `content` is the half of the contract the
+ * model is guaranteed to see — and "this answer was cut off" is not something it
+ * can recover from the answer itself.
+ */
+export function formatSingleResult(result: SubagentResult): string {
+  const body = result.finalOutput ?? result.error ?? fallbackBody(result);
+  const note =
+    result.outcome === "truncated"
+      ? "[truncated: the subagent reached its output token limit — the answer above is partial]"
+      : result.outcome === "aborted"
+        ? "[aborted: the subagent run was cancelled — anything above is partial]"
+        : undefined;
+  return note ? `${body}\n\n${note}` : body;
+}
+
+/**
+ * The finished-run row, shared by the compact and expanded views.
+ *
+ * `undefined` means "nothing to report yet" (the run is still going), which is
+ * what leaves the callers' running / tool-call rendering untouched.
+ *
+ * The error text is not capped here: rows are cut at the width pi renders them
+ * at, by `RowBlock` (see `row-block.ts`). A fixed character cap is what made
+ * these rows die at a third of the frame on a wide terminal.
+ */
+export function buildOutcomeLine(
+  data: { outcome?: RunOutcome | undefined; error: string | undefined },
+  theme: { fg: (token: string, text: string) => string },
+): string | undefined {
+  if (data.error) return theme.fg("error", "✗ " + data.error);
+  if (data.outcome === "truncated") {
+    return theme.fg("warning", "⚠ Truncated — hit the output token limit, answer is partial");
+  }
+  if (data.outcome === "aborted") return theme.fg("warning", "⚠ Aborted");
+  if (data.outcome === "completed") return theme.fg("success", "✓ Done");
+  return undefined;
+}
+
 export interface StatsData {
   turns: number | undefined;
   toolCount: number | undefined;
@@ -96,9 +139,9 @@ export function buildStatsLine(
   return parts.map(p => theme.fg("dim", "· " + p)).join(" ");
 }
 
-// Build an agent label for display: "agentName: truncated task preview".
-// Truncation width of 60 keeps compact rows readable on standard terminal widths
-// while still showing meaningful task context.
+// Build an agent label for display: "agentName: task preview".
+// The task is passed through whole: the row it lands on is cut at the render
+// width by `RowBlock`, so the preview fills whatever frame pi draws it in.
 export function buildAgentLabel(
   agent: string,
   task: string | undefined,
@@ -106,7 +149,7 @@ export function buildAgentLabel(
 ): string {
   const name = theme.bold(agent);
   if (task) {
-    return name + theme.fg("dim", ": " + truncLine(task, 60));
+    return name + theme.fg("dim", ": " + task);
   }
   return name;
 }

package/src/frontmatter-io.test.ts

@@ -1,6 +1,13 @@
 import { describe, it, expect } from "vitest";
 import * as fc from "fast-check";
 import { validateAgentName, serializeAgent, AGENT_NAME_REGEX } from "./frontmatter-io.js";
+// Imported here rather than inside the tests below: nothing in this file mocks
+// `parseFrontmatter`, so a dynamic `await import()` in a test body only served
+// to charge whichever test ran first with loading the whole pi-coding-agent
+// package — measured at 2.6s alone, 6-7.8s on a loaded machine, against a 5s
+// per-test timeout. That is the "Test timed out in 5000ms" flake, and it lands
+// on collection instead, where no test budget is spent.
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
@@ -117,3 +124,58 @@ describe("serializeAgent", () => {
     );
   });
 });
+
+// ── mcp round-trip (the writer's half of ADR 0028) ──────────────────────────
+
+describe("serializeAgent: mcp opt-in", () => {
+  it("writes the mcp key when the agent opts in", () => {
+    const output = serializeAgent(makeAgent({ tools: ["read", "bash"], mcp: true }));
+    expect(output).toContain("mcp: true");
+  });
+
+  it("writes no mcp key when the field is absent or false (closed is the default)", () => {
+    expect(serializeAgent(makeAgent({ tools: ["read"] }))).not.toContain("mcp:");
+    expect(serializeAgent(makeAgent({ tools: ["read"], mcp: false }))).not.toContain("mcp:");
+  });
+
+  it("survives a write → read round trip as a real boolean, not a string", () => {
+    const output = serializeAgent(makeAgent({ tools: ["read", "bash"], mcp: true }));
+    const { frontmatter } = parseFrontmatter(output);
+    expect(frontmatter.mcp).toBe(true);
+  });
+
+  it("keeps the tools list intact alongside the mcp key", () => {
+    const output = serializeAgent(makeAgent({ tools: ["read", "bash"], mcp: true }));
+    expect(output).toContain("tools: read, bash");
+    expect(output).toContain("mcp: true");
+  });
+});
+
+// ── One `tools:` key, whatever the config object looks like ───────────────
+
+describe("serializeAgent: never writes two tools keys", () => {
+  // The read path preserves an unreadable `tools:` in `extraFields` so a save
+  // cannot delete a line the user typed, while `applyToolEntries` owns the real
+  // `tools` field. If both are populated the file gets two `tools:` keys and the
+  // last one wins on the next read — which is the broken one.
+  const toolsKeys = (yaml: string): string[] =>
+    yaml.split("\n").filter((line) => /^tools:/.test(line));
+
+  it("writes the real field and drops the preserved raw value when both exist", () => {
+    const output = serializeAgent(
+      makeAgent({ tools: ["read"], extraFields: { tools: "read, +web_search", owner: "x" } }),
+    );
+    expect(toolsKeys(output)).toEqual(["tools: read"]);
+    expect(parseFrontmatter(output).frontmatter.tools).toBe("read");
+    // The unrelated extra still round-trips.
+    expect(output).toContain("owner: x");
+  });
+
+  it("still writes a preserved raw value when there is no parsed list to replace it", () => {
+    // This is the preservation the read path promised: an agent whose `tools:`
+    // was rejected keeps its line on save, rather than being silently rewritten
+    // without it.
+    const output = serializeAgent(makeAgent({ extraFields: { tools: "read, +web_search" } }));
+    expect(toolsKeys(output)).toEqual(["tools: read, +web_search"]);
+  });
+});

package/src/frontmatter-io.ts

@@ -65,8 +65,17 @@ export function serializeAgent(config: AgentConfig): string {
   lines.push(`description: ${quoteYamlValue(config.description)}`);
 
   // Optional known fields
-  if (config.tools && config.tools.length > 0) {
-    lines.push(`tools: ${quoteYamlValue(config.tools.join(", "))}`);
+  const toolsLine =
+    config.tools && config.tools.length > 0
+      ? `tools: ${quoteYamlValue(config.tools.join(", "))}`
+      : undefined;
+  if (toolsLine !== undefined) {
+    lines.push(toolsLine);
+  }
+  // Only the opt-in is written: a closed allowlist is the default, so the
+  // absence of the key is the meaningful statement (ADR 0028).
+  if (config.mcp === true) {
+    lines.push("mcp: true");
   }
   if (config.model) {
     lines.push(`model: ${quoteYamlValue(config.model)}`);
@@ -78,6 +87,11 @@ export function serializeAgent(config: AgentConfig): string {
   // Extra fields (sorted alphabetically)
   if (config.extraFields) {
     for (const key of Object.keys(config.extraFields).sort()) {
+      // `extraFields.tools` is the read path's copy of a `tools:` line it could
+      // not read, kept so a save cannot delete it. It only gets to speak for
+      // `tools:` when there is no parsed list to speak for it — otherwise this
+      // loop writes a second `tools:` key and the later one wins on reload.
+      if (key === "tools" && toolsLine !== undefined) continue;
       const value = config.extraFields[key]!;
       if (typeof value === "string") {
         lines.push(`${key}: ${quoteYamlValue(value)}`);

package/src/handlers.test.ts

@@ -4,9 +4,27 @@ import { extractArgsPreview } from "./handlers.js";
 // ── extractArgsPreview ──────────────────────────────────────────────────────
 
 describe("extractArgsPreview", () => {
-  it("returns string args truncated", () => {
-    const long = "a".repeat(200);
-    expect(extractArgsPreview(long)).toBe("a".repeat(120));
+  // The preview feeds a transcript row, and the row is what decides how much of
+  // it fits (`RowBlock` cuts at the width pi renders at). A cap here is therefore
+  // a second, invisible limit: cut it tighter than any terminal is wide and the
+  // row stops short of the frame with no cut marker, which is the defect #108
+  // set out to remove. pi's own bash row keeps the command whole for the same
+  // reason. It stays bounded, because the preview is carried in the streamed
+  // progress object for the life of the run.
+  it("keeps enough of a long command for a wide frame to draw", () => {
+    const long = "a".repeat(300);
+    expect(extractArgsPreview(long)).toBe(long);
+  });
+
+  it("still bounds what it returns, since the preview is streamed", () => {
+    const preview = extractArgsPreview("a".repeat(100_000));
+    expect(preview.length).toBeLessThan(1_000);
+  });
+
+  it("bounds the serialised form of object args too", () => {
+    const preview = extractArgsPreview({ a: "b".repeat(100_000), c: 1 });
+    expect(preview.length).toBeLessThan(1_000);
+    expect(preview.length).toBeGreaterThanOrEqual(300);
   });
 
   it("replaces newlines in string args", () => {

package/src/handlers.ts

@@ -1,7 +1,19 @@
 import type { StreamState } from "./types.js";
 
 // Truncation limits for previews
-const ARGS_PREVIEW_MAX = 120;
+//
+// The args preview is drawn on a transcript row, and the row is what decides how
+// much of it fits: `RowBlock` cuts at the width pi hands `render()` (see
+// `row-block.ts`). A cap here is therefore a second, invisible character limit —
+// the very defect #108 removed — because a preview shorter than the frame ends
+// mid-word with no cut marker. pi's own bash row keeps the command whole for the
+// same reason (`formatShellCall`). So this bound sits above anything a terminal
+// can draw, and exists only to keep the preview from growing the streamed
+// progress object without limit (it is carried for the life of the run).
+const ARGS_PREVIEW_MAX = 512;
+// `recentOutput` is carried in the progress object but drawn by no row, so it
+// keeps the old, tighter bound: widening it would only grow what is streamed.
+const OUTPUT_LINE_MAX = 120;
 const TOOL_CALLS_MAX = 50;
 const RECENT_OUTPUT_MAX = 50;
 
@@ -97,13 +109,13 @@ export function handleToolResult(state: StreamState, event: JsonEvent): void {
 
   if (typeof content === "string" && content.trim()) {
     const lines = content.split("\n").filter((l) => l.trim());
-    state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
+    state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, OUTPUT_LINE_MAX)}`);
   } else if (Array.isArray(content)) {
     for (const part of content) {
       if (part.type === "text" && (part.text as string)?.trim()) {
         const text = part.text as string;
         const lines = text.split("\n").filter((l) => l.trim());
-        state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, ARGS_PREVIEW_MAX)}`);
+        state.recentOutput.push(`[${toolName}] ${lines[0]?.slice(0, OUTPUT_LINE_MAX)}`);
         break;
       }
     }
@@ -126,6 +138,13 @@ export function handleMessageEnd(state: StreamState, event: JsonEvent): void {
     state.model = message.model as string;
   }
 
+  // How this response ended. The LAST assistant message's stopReason is what
+  // decides the run's outcome (`length` ⇒ truncated, `aborted` ⇒ cancelled,
+  // `error` ⇒ failed) — the exit code cannot tell them apart.
+  if (typeof message.stopReason === "string") {
+    state.lastStopReason = message.stopReason;
+  }
+
   // Collect text + thinking output
   const content = message.content as Array<Record<string, unknown>> | string | undefined;
   if (typeof content === "string" && content.trim()) {