@pi-archimedes/subagent 1.8.3 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Cherubini and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,10 +5,11 @@ Subagent dispatch with live TUI streaming and cost tracking for the [Pi coding a
 ## Features
 
 - **Single & parallel execution** — dispatch one task or fan out multiple tasks across different agents simultaneously
-- **Live TUI streaming** — watch subagent progress in real-time with tool calls, token counts, and cost updates
+- **Live TUI streaming** — watch subagent progress in real-time with color-coded tool calls (grey while running, green/red on completion), readable argument previews, token counts, and cost updates
 - **Agent discovery** — auto-discovers agents from `.pi/agents/*.md` files at project, user, and global scope
 - **Per-agent model override** — each subagent can use its own model, falling back to the parent's selection
 - **Cost tracking** — detailed token usage (input, output, cache read/write) and cost per subagent, emitted through the core bus for the footer to consume
+- **Trace correlation** — results expose the ephemeral child's logical Pi session UUID as optional `childSessionId` when Pi emits a valid session event
 - **`/agents` command** — full CRUD TUI for managing agent definitions with model picker, tool picker, and cross-scope collision warnings (available via the meta package)
 
 ## Screenshots

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/subagent",
-  "version": "1.8.3",
+  "version": "2.0.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.8.3"
+    "@pi-archimedes/core": "2.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/compact.ts

@@ -1,5 +1,5 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolResult } from "./types.js";
+import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolCall, SubagentToolResult } from "./types.js";
 import { formatTokens, formatDuration, formatCost, truncLine, buildStatsLine, buildAgentLabel } from "./format.js";
 
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
@@ -14,7 +14,7 @@ interface ActivityData {
   finalOutput: string | undefined;
   status: "running" | "completed" | "failed" | undefined;
   error: string | undefined;
-  toolCalls?: string[] | undefined;
+  toolCalls?: (SubagentToolCall | string)[] | undefined;
 }
 
 export function buildActivityLine(
@@ -35,7 +35,7 @@ export function buildActivityLine(
     return theme.fg("error", "✗ Failed");
   }
 
-  // Running: show the current tool with live duration
+  // Running: show the current tool with live duration (grey while running)
   if (data.currentTool) {
     const arrow = theme.fg("muted", "↳ ");
     const argsPreview = data.currentToolArgs
@@ -44,7 +44,7 @@ export function buildActivityLine(
     const durationPart = data.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - data.currentToolStartedAt)
       : "";
-    let line = theme.fg("syntaxFunction", data.currentTool);
+    let line = theme.fg("muted", data.currentTool);
     if (argsPreview) {
       line += theme.fg("dim", ": " + argsPreview);
     }
@@ -55,9 +55,21 @@ export function buildActivityLine(
   }
 
   // Running, no active tool: show the most recently completed tool call
+  // Color only the tool name green (success) or red (error)
   if (data.toolCalls && data.toolCalls.length > 0) {
     const lastCall = data.toolCalls[data.toolCalls.length - 1];
-    if (lastCall) return theme.fg("muted", "↳ " + lastCall);
+    if (lastCall) {
+      if (typeof lastCall === "string") {
+        return theme.fg("dim", "↳ " + truncLine(lastCall, 60));
+      }
+      const color = lastCall.error ? "error" : "success";
+      const arrow = theme.fg("muted", "↳ ");
+      const name = theme.fg(color, lastCall.name);
+      const argsPart = lastCall.argsPreview
+        ? theme.fg("dim", ": " + truncLine(lastCall.argsPreview, 60))
+        : "";
+      return arrow + name + argsPart;
+    }
   }
 
   // Running, no tool history: show first line of streamed output if any

package/src/expanded.ts

@@ -1,9 +1,25 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { SubagentDetails, SubagentProgress, SubagentResult } from "./types.js";
+import type { SubagentDetails, SubagentProgress, SubagentResult, SubagentToolCall } from "./types.js";
 import { formatTokens, formatDuration, truncLine, buildStatsLine, buildAgentLabel } from "./format.js";
 
 type Theme = { fg: (token: string, text: string) => string; bold: (text: string) => string };
 
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function formatToolCall(call: SubagentToolCall | string, theme: Theme): string {
+  // Backward compat: old persisted sessions may have toolCalls as string[]
+  if (typeof call === "string") {
+    return theme.fg("dim", "↳ " + call);
+  }
+  const arrow = theme.fg("muted", "↳ ");
+  const color = call.error ? "error" : "success";
+  const name = theme.fg(color, call.name);
+  const argsPart = call.argsPreview
+    ? theme.fg("dim", ": " + call.argsPreview)
+    : "";
+  return arrow + name + argsPart;
+}
+
 // ── Expanded completed result ───────────────────────────────────────────────
 
 export function buildExpandedText(
@@ -43,7 +59,7 @@ export function buildExpandedText(
   if (toolCalls && toolCalls.length > 0) {
     lines.push("");
     for (const call of toolCalls) {
-      lines.push(theme.fg("dim", "↳ " + call));
+      lines.push(formatToolCall(call, theme));
     }
   }
 
@@ -116,7 +132,7 @@ export function renderProgressExpanded(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "↳ " + call));
+      lines.push(formatToolCall(call, theme));
     }
   }
 
@@ -129,7 +145,7 @@ export function renderProgressExpanded(
     const durationPart = progress.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
       : "";
-    let line = theme.fg("syntaxFunction", progress.currentTool);
+    let line = theme.fg("muted", progress.currentTool);
     if (argsPreview) {
       line += theme.fg("dim", ": " + argsPreview);
     }
@@ -192,7 +208,7 @@ export function buildProgressExpandedText(
   if (progress.toolCalls && progress.toolCalls.length > 0) {
     lines.push("");
     for (const call of progress.toolCalls) {
-      lines.push(theme.fg("dim", "↳ " + call));
+      lines.push(formatToolCall(call, theme));
     }
   }
 
@@ -204,7 +220,7 @@ export function buildProgressExpandedText(
     const durationPart = progress.currentToolStartedAt
       ? " | " + formatDuration(Date.now() - progress.currentToolStartedAt)
       : "";
-    let line = theme.fg("syntaxFunction", progress.currentTool);
+    let line = theme.fg("muted", progress.currentTool);
     if (argsPreview) {
       line += theme.fg("dim", ": " + argsPreview);
     }

package/src/handlers.ts

@@ -50,11 +50,16 @@ export function extractArgsPreview(args: unknown): string {
 export function handleToolStart(state: StreamState, event: JsonEvent): void {
   state.toolCount++;
   state.currentTool = event.toolName as string;
-  state.currentToolArgs = JSON.stringify(event.args);
+  // Use extractArgsPreview instead of JSON.stringify for readable display
+  const argsPreview = extractArgsPreview(event.args);
+  state.currentToolArgs = argsPreview;
   state.currentToolStartedAt = Date.now();
   // Record tool call with args preview
-  const argsPreview = extractArgsPreview(event.args);
-  state.toolCalls.push(`${state.currentTool}: ${argsPreview}`);
+  state.toolCalls.push({
+    name: state.currentTool,
+    argsPreview,
+    error: false,
+  });
   if (state.toolCalls.length > TOOL_CALLS_MAX) {
     state.toolCalls.splice(0, state.toolCalls.length - TOOL_CALLS_MAX);
   }
@@ -75,6 +80,14 @@ export function handleToolEnd(state: StreamState): void {
  */
 export function handleToolResult(state: StreamState, event: JsonEvent): void {
   const result = event.result as Record<string, unknown> | undefined;
+
+  // Mark the last tool call as errored if the result indicates an error
+  const lastCall = state.toolCalls[state.toolCalls.length - 1];
+  const isError = event.isError === true || result?.isError === true;
+  if (lastCall && lastCall.name === (event.toolName as string) && isError) {
+    lastCall.error = true;
+  }
+
   if (!result) return;
 
   const toolName = (event.toolName as string) ?? "tool";

package/src/stream.test.ts

@@ -0,0 +1,47 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { ChildProcess } from "node:child_process";
+import { describe, expect, it } from "vitest";
+import { streamEvents } from "./stream.js";
+
+type FakeChild = ChildProcess & { stdout: PassThrough; stderr: PassThrough };
+
+function fakeChild(): FakeChild {
+  const child = new EventEmitter() as FakeChild;
+  Object.assign(child, {
+    stdout: new PassThrough(),
+    stderr: new PassThrough(),
+    kill: () => true,
+  });
+  return child;
+}
+
+async function finishWith(events: Array<Record<string, unknown>>) {
+  const child = fakeChild();
+  const result = streamEvents(child);
+  for (const event of events) {
+    child.stdout.write(`${JSON.stringify(event)}\n`);
+  }
+  child.emit("close", 0);
+  return result;
+}
+
+describe("streamEvents session identity", () => {
+  it("returns the logical child Pi session ID", async () => {
+    const result = await finishWith([{
+      type: "session",
+      id: "00000000-0000-7000-8000-000000000003",
+    }]);
+
+    expect(result.childSessionId).toBe("00000000-0000-7000-8000-000000000003");
+  });
+
+  it("omits the child session ID when no valid session event arrives", async () => {
+    const result = await finishWith([
+      { type: "session" },
+      { type: "session", id: 42 },
+    ]);
+
+    expect(result.childSessionId).toBeUndefined();
+  });
+});

package/src/stream.ts

@@ -127,6 +127,12 @@ export function streamEvents(
       clearStartupTimer();
 
       switch (event.type) {
+        case "session": {
+          if (typeof event.id === "string" && event.id) {
+            state.childSessionId = event.id;
+          }
+          break;
+        }
         case "tool_execution_start": {
           handleToolStart(state, event);
           emitProgress();
@@ -163,7 +169,7 @@ export function streamEvents(
           handleAgentEnd(state, event);
           break;
         }
-        // Ignore: session, agent_start, message_start, message_update, turn_end, tool_execution_update
+        // Ignore: agent_start, message_start, message_update, turn_end, tool_execution_update
       }
     });
 
@@ -183,6 +189,7 @@ export function streamEvents(
       const result: SubagentResult = {
         agent: callbacks.agent ?? "subagent",
         task: callbacks.task ?? "",
+        ...(state.childSessionId ? { childSessionId: state.childSessionId } : {}),
         exitCode,
         model: state.model,
         usage: {

package/src/types.ts

@@ -7,6 +7,12 @@ export interface SubagentUsage {
   turns: number;
 }
 
+export interface SubagentToolCall {
+  name: string;
+  argsPreview: string;
+  error: boolean;
+}
+
 export interface SubagentProgress {
   agent: string;
   status: "running" | "completed" | "failed";
@@ -27,13 +33,15 @@ export interface SubagentProgress {
   output: string | undefined;
   /** Last N lines of assistant text for live display */
   recentOutput: string[] | undefined;
-  /** History of tool calls: "toolName: args_preview" */
-  toolCalls: string[] | undefined;
+  /** History of tool calls with status tracking */
+  toolCalls: SubagentToolCall[] | undefined;
 }
 
 export interface SubagentResult {
   agent: string;
   task: string;
+  /** Logical Pi session UUID for this spawned subagent process. */
+  childSessionId?: string;
   exitCode: number;
   usage: SubagentUsage;
   model: string | undefined;
@@ -57,6 +65,7 @@ export interface SubagentDetails {
 
 /** Mutable state during streaming — shared between stream.ts and handlers.ts */
 export interface StreamState {
+  childSessionId?: string;
   toolCount: number;
   turnCount: number;
   totalInput: number;
@@ -70,7 +79,7 @@ export interface StreamState {
   model: string | undefined;
   accumulatedOutput: string[];
   recentOutput: string[];
-  toolCalls: string[];
+  toolCalls: SubagentToolCall[];
   finalOutput: string | undefined;
 }