@pi-archimedes/subagent 2.7.2 → 2.8.0

package/README.md

@@ -44,7 +44,7 @@ The `agent` field is optional — omitting it is not a built-in default agent, a
 }
 ```
 
-**The dispatch waits.** A call — single or parallel — blocks until every task completes and returns the combined results, each optionally carrying the child's `childSessionId`. There is an `async` field in the schema; the implementation ignores it, so don't plan on fire-and-forget: batch the work into `tasks` and let the call block on all of it.
+**The dispatch waits.** A call — single or parallel — blocks until every task completes and returns the combined results, each optionally carrying the child's `childSessionId`. There is an `async` field in the schema; the implementation ignores it, so don't plan on fire-and-forget: batch the work into `tasks` and let the call block on all of it. In parallel mode each result section carries the child's final output beneath its metrics line.
 
 ### Model and thinking resolution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -15,8 +15,8 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.7.2",
-    "@pi-archimedes/todo": "2.7.2"
+    "@pi-archimedes/core": "2.8.0",
+    "@pi-archimedes/todo": "2.8.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/format.test.ts

@@ -1,5 +1,21 @@
 import { describe, it, expect } from "vitest";
-import { truncLine } from "./format.js";
+import { truncLine, formatParallelResults } from "./format.js";
+import type { SubagentResult } from "./types.js";
+
+function makeResult(overrides: Partial<SubagentResult> = {}): SubagentResult {
+  return {
+    agent: "test-agent",
+    task: "do something",
+    exitCode: 0,
+    usage: { input: 100, output: 50, cacheRead: 0, cacheWrite: 0, cost: 0.01, turns: 3 },
+    model: "gpt-4",
+    finalOutput: undefined,
+    error: undefined,
+    progress: undefined,
+    progressSummary: { toolCount: 5, tokens: 150, durationMs: 3000 },
+    ...overrides,
+  };
+}
 
 // ── truncLine ───────────────────────────────────────────────────────────────
 
@@ -28,3 +44,76 @@ describe("truncLine", () => {
     expect(truncLine("\nhello", 10)).toBe("...");
   });
 });
+
+describe("formatParallelResults", () => {
+  it("renders header + body per task with exactly one blank line between sections", () => {
+    const r1 = makeResult({
+      agent: "researcher",
+      progressSummary: { toolCount: 31, tokens: 12345, durationMs: 153000 },
+      finalOutput: "Found the bug.\n", // trailing newline: pins trimEnd
+    });
+    const r2 = makeResult({
+      agent: "reviewer",
+      progressSummary: { toolCount: 4, tokens: 2000, durationMs: 12000 },
+      finalOutput: "Looks good.",
+    });
+    expect(formatParallelResults([r1, r2])).toBe(
+      "✓ researcher 31 tools · 12k tok · 153s\nFound the bug.\n\n✓ reviewer 4 tools · 2k tok · 12s\nLooks good.",
+    );
+  });
+
+  it("rounds tokens and duration with Math.round", () => {
+    const r = makeResult({
+      progressSummary: { toolCount: 1, tokens: 12500, durationMs: 154000 },
+      finalOutput: "x",
+    });
+    expect(formatParallelResults([r])).toBe("✓ test-agent 1 tools · 13k tok · 154s\nx");
+  });
+
+  it("renders header only when progressSummary is absent (synthetic case)", () => {
+    const r = makeResult({ progressSummary: undefined });
+    expect(formatParallelResults([r])).toBe("✓ test-agent\ncompleted");
+  });
+
+  it("uses the ✗ glyph for non-zero exit codes", () => {
+    const r = makeResult({ exitCode: 1, finalOutput: "done" });
+    expect(formatParallelResults([r])).toBe("✗ test-agent 5 tools · 0k tok · 3s\ndone");
+  });
+
+  it("falls back to 'completed' when there is no finalOutput and no error", () => {
+    const r = makeResult();
+    expect(formatParallelResults([r])).toBe("✓ test-agent 5 tools · 0k tok · 3s\ncompleted");
+  });
+
+  it("uses the error text as the body when there is no finalOutput", () => {
+    const r = makeResult({ exitCode: 1, error: "spawn failed" });
+    expect(formatParallelResults([r])).toBe("✗ test-agent 5 tools · 0k tok · 3s\nspawn failed");
+  });
+
+  it("prefers finalOutput over error when both are set", () => {
+    const r = makeResult({ finalOutput: "out", error: "boom" });
+    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", () => {
+    const r1 = makeResult({
+      agent: "researcher",
+      finalOutput: "line one\nline two\n",
+    });
+    const r2 = makeResult({
+      agent: "reviewer",
+      finalOutput: "second",
+    });
+    expect(formatParallelResults([r1, r2])).toBe(
+      "✓ researcher 5 tools · 0k tok · 3s\nline one\nline two\n\n✓ reviewer 5 tools · 0k tok · 3s\nsecond",
+    );
+  });
+
+  it("keeps duplicate agent names distinguishable by position and body", () => {
+    const a = makeResult({ agent: "researcher", finalOutput: "first" });
+    const b = makeResult({ agent: "researcher", finalOutput: "second" });
+    expect(formatParallelResults([a, b])).toBe(
+      "✓ researcher 5 tools · 0k tok · 3s\nfirst\n\n✓ researcher 5 tools · 0k tok · 3s\nsecond",
+    );
+  });
+});

package/src/format.ts

@@ -1,3 +1,5 @@
+import type { SubagentResult } from "./types.js";
+
 export function formatTokens(n: number): string {
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
   if (n >= 1_000) return Math.round(n / 1_000) + "k";
@@ -41,6 +43,27 @@ export function truncLine(text: string, maxLen: number): string {
   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
+ * accident); the body mirrors the single-mode fallback chain
+ * (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).
+ */
+export function formatParallelResults(results: SubagentResult[]): string {
+  const sections = results.map((r) => {
+    const status = 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();
+    return `${header}\n${body}`;
+  });
+  return sections.join("\n\n");
+}
+
 export interface StatsData {
   turns: number | undefined;
   toolCount: number | undefined;

package/src/index.ts

@@ -3,6 +3,7 @@ import { Text, type TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { SUBAGENT_PARAMS_SCHEMA } from "./tool-schema.js";
 import { executeSubagent, executeParallel } from "./execute.js";
+import { formatParallelResults } from "./format.js";
 // agent-manager.js lazy-loaded below to keep subagent tool registration fast
 import { renderSubagentResult } from "./render.js";
 import { OVERLAY_CHROME } from "@pi-archimedes/core/overlay";
@@ -110,7 +111,7 @@ export function registerSubagent(pi: ExtensionAPI): void {
         });
 
         return {
-          content: [{ type: "text", text: formatResultsSummary(results) }],
+          content: [{ type: "text", text: formatParallelResults(results) }],
           details: {
             mode: "parallel",
             results,
@@ -281,17 +282,6 @@ function formatProgressSummary(progress: SubagentProgress[]): string {
   return lines.join("\n");
 }
 
-function formatResultsSummary(results: SubagentResult[]): string {
-  const lines = results.map((r) => {
-    const status = 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`
-      : "";
-    return `${status} ${r.agent}${summary ? " " + summary : ""}`;
-  });
-  return lines.join("\n");
-}
-
 // ── Command registration ────────────────────────────────────────────────────
 
 export function registerAgentsCommand(pi: ExtensionAPI): void {

package/src/spawn.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import * as net from "node:net";
+import { getBus, Events } from "@pi-archimedes/core/bus";
+import { startAskSocketServer } from "./spawn.js";
+
+// startAskSocketServer is tested directly (not via spawnSubagent, which would
+// spawn a real `pi` process). The real bus is used — subscriptions are
+// unsubscribed in afterEach so they don't leak into other test files in the
+// same worker (the bus is a globalThis singleton).
+
+const cleanups: Array<() => void> = [];
+const unsubs: Array<() => void> = [];
+
+afterEach(() => {
+  unsubs.splice(0).forEach((u) => u());
+  cleanups.splice(0).forEach((c) => c());
+});
+
+function track(fn: () => void): void {
+  cleanups.push(fn);
+}
+
+function connectClient(socketPath: string): Promise<net.Socket> {
+  return new Promise((resolve, reject) => {
+    const client = net.connect(socketPath, () => resolve(client));
+    client.on("error", (err) => reject(err));
+  });
+}
+
+function writeAskRequest(client: net.Socket, requestId: string, toolCallId?: string): void {
+  client.write(
+    JSON.stringify({
+      type: "ask_request",
+      requestId,
+      toolCallId,
+      questions: [{ id: "q1", question: "Which?", options: [{ label: "A" }] }],
+    }) + "\n",
+  );
+}
+
+describe("startAskSocketServer", () => {
+  it("a child ask_request carrying toolCallId → the bus ASK_REQUEST carries the same toolCallId", async () => {
+    const { socketPath, cleanup } = startAskSocketServer("test-agent");
+    track(cleanup);
+    await new Promise((r) => setTimeout(r, 50)); // let the server listen
+
+    const requests: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_REQUEST, (p) => requests.push(p)));
+
+    const client = await connectClient(socketPath);
+    writeAskRequest(client, "req-1", "tool-9");
+
+    await vi.waitFor(() => expect(requests.length).toBe(1));
+    const req = requests[0] as { source: string; requestId: string; toolCallId?: string; questions: unknown[] };
+    expect(req.source).toBe("subagent:test-agent");
+    expect(req.requestId).toBe("req-1");
+    expect(req.toolCallId).toBe("tool-9");
+    expect(req.questions).toEqual([{ id: "q1", question: "Which?", options: [{ label: "A" }] }]);
+
+    // Deliver the response (drains pending) before closing so no ASK_CANCEL
+    // leaks onto the global bus queue for the next test
+    getBus().emit(Events.ASK_RESPONSE, {
+      requestId: "req-1",
+      cancelled: false,
+      results: [{ id: "q1", selectedOptions: ["A"] }],
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    client.destroy();
+    await new Promise((r) => setTimeout(r, 50)); // close handler ran (no-op)
+  });
+
+  it("closing the child socket → ASK_CANCEL for the pending requestId + source", async () => {
+    const { socketPath, cleanup } = startAskSocketServer("test-agent");
+    track(cleanup);
+    await new Promise((r) => setTimeout(r, 50)); // let the server listen
+
+    const cancels: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_CANCEL, (p) => cancels.push(p)));
+    const requests: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_REQUEST, (p) => requests.push(p)));
+
+    const client = await connectClient(socketPath);
+    writeAskRequest(client, "req-2");
+
+    // Wait until the request is registered (pending) before closing
+    await vi.waitFor(() => expect(requests.length).toBe(1));
+    client.destroy();
+
+    await vi.waitFor(() => expect(cancels.length).toBe(1));
+    expect(cancels[0]).toEqual({ requestId: "req-2", source: "subagent:test-agent" });
+  });
+
+  it("no ASK_CANCEL once the response has already been delivered (pending drained)", async () => {
+    const { socketPath, cleanup } = startAskSocketServer("test-agent");
+    track(cleanup);
+    await new Promise((r) => setTimeout(r, 50)); // let the server listen
+
+    const cancels: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_CANCEL, (p) => cancels.push(p)));
+    const requests: unknown[] = [];
+    unsubs.push(getBus().on(Events.ASK_REQUEST, (p) => requests.push(p)));
+
+    const client = await connectClient(socketPath);
+    writeAskRequest(client, "req-3");
+    await vi.waitFor(() => expect(requests.length).toBe(1));
+
+    // Deliver the response (drains pending) before the socket closes
+    getBus().emit(Events.ASK_RESPONSE, {
+      requestId: "req-3",
+      cancelled: false,
+      results: [{ id: "q1", selectedOptions: ["A"] }],
+    });
+    await new Promise((r) => setTimeout(r, 50));
+    client.destroy();
+    await new Promise((r) => setTimeout(r, 50)); // close handler ran
+
+    expect(cancels.length).toBe(0);
+  });
+});

package/src/spawn.ts

@@ -67,17 +67,22 @@ function resolvePiBinary(): string {
  * Start a Unix socket server that bridges the child's ask tool to the parent bus.
  *
  * The child's ask tool (in packages/ask) connects to PI_SUBAGENT_SOCKET and sends:
- *   { type: "ask_request", requestId, questions } as a JSON line
+ *   { type: "ask_request", requestId, questions, toolCallId } as a JSON line
  * and waits for:
  *   { type: "ask_response", requestId, cancelled, results } as a JSON line
  *
- * We forward the request onto the bus (ASK_REQUEST), the ask package shows the
- * parent TUI dialog, then emits ASK_RESPONSE on the bus, and we write it back
- * to the socket connection.
+ * We forward the request onto the bus (ASK_REQUEST, carrying toolCallId), the
+ * ask package (or the bridge, in bridge mode) answers it, then emits
+ * ASK_RESPONSE on the bus, and we write it back to the socket connection.
+ *
+ * When the socket closes (child exit, or the child's own 5-min timeout →
+ * socket.end()) we signal the bridge via ASK_CANCEL for any still-pending ask.
+ * We do NOT emit ASK_RESPONSE ourselves — the bridge is the sole emitter
+ * (no double-decrement of its refcount).
  *
  * Returns the socket path and a cleanup function.
  */
-function startAskSocketServer(agentName: string): { socketPath: string; cleanup: () => void } {
+export function startAskSocketServer(agentName: string): { socketPath: string; cleanup: () => void } {
   // Use named pipes on Windows, Unix domain sockets elsewhere.
   // Linux socket path limit is 108 chars — keep it short.
   const id = randomUUID().slice(0, 8);
@@ -110,6 +115,8 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
 
   const server = net.createServer((socket) => {
     let buffer = "";
+    // requestIds seen on this socket (for the ASK_CANCEL wiring below)
+    const socketRequestIds = new Set<string>();
 
     socket.on("data", (chunk: Buffer) => {
       buffer += chunk.toString("utf-8");
@@ -124,6 +131,7 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
             type: string;
             requestId: string;
             questions: unknown[];
+            toolCallId?: string;
           };
           if (msg.type === "ask_request") {
             // Register write-back so ASK_RESPONSE handler can find this socket
@@ -134,11 +142,14 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
                 // socket already closed
               }
             });
-            // Forward to bus — ask package will show the TUI dialog
+            socketRequestIds.add(msg.requestId);
+            // Forward to bus — the ask package (or the bridge, in bridge mode)
+            // answers it; toolCallId rides along for Client correlation
             getBus().emit(Events.ASK_REQUEST, {
               source: `subagent:${agentName}`,
               requestId: msg.requestId,
               questions: msg.questions,
+              toolCallId: msg.toolCallId,
             });
           }
         } catch {
@@ -147,6 +158,19 @@ function startAskSocketServer(agentName: string): { socketPath: string; cleanup:
       }
     });
 
+    // Child exit (or the child's own 5-min timeout → socket.end()) closes the
+    // socket: signal the bridge via ASK_CANCEL for any still-pending ask so it
+    // can cancel the relayed Client request. We only signal — the bridge is
+    // the sole ASK_RESPONSE emitter (no double-decrement of its refcount).
+    socket.on("close", () => {
+      for (const rid of socketRequestIds) {
+        if (pending.has(rid)) {
+          getBus().emit(Events.ASK_CANCEL, { requestId: rid, source: `subagent:${agentName}` });
+          pending.delete(rid);
+        }
+      }
+    });
+
     socket.on("error", () => { /* connection dropped */ });
   });
 
@@ -245,7 +269,12 @@ export function spawnSubagent(options: SpawnOptions): ChildProcess {
         forceKill.unref();
       }
     };
-    options.signal.addEventListener("abort", abortHandler, { once: true });
+    // A signal that is ALREADY aborted never dispatches its "abort" event (it
+    // fires exactly once, at abort time), so addEventListener alone would never
+    // kill the child — call the handler directly in that case. (kill is
+    // idempotent via the child.killed guard, so both branches coexist safely.)
+    if (options.signal.aborted) abortHandler();
+    else options.signal.addEventListener("abort", abortHandler, { once: true });
     child.on("exit", () => options.signal!.removeEventListener("abort", abortHandler));
   }