@pi-archimedes/subagent 1.9.0 → 2.0.1

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.9.0",
+  "version": "2.0.1",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -11,7 +11,7 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "1.9.0"
+    "@pi-archimedes/core": "2.0.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",

package/src/index.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, TUI } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-// execute.js + agent-manager.js lazy-loaded below to keep subagent tool registration fast
+import { executeSubagent, executeParallel } from "./execute.js";
+// agent-manager.js lazy-loaded below to keep subagent tool registration fast
 import { renderSubagentResult } from "./render.js";
 import { discoverAgents, discoverAgentsAll, findAgent, formatAgentList } from "./agents.js";
 import { validateModel, firstError } from "./model-validation.js";
@@ -75,8 +76,6 @@ export function registerSubagent(pi: ExtensionAPI): void {
       onUpdate: ((update: SubagentToolResult) => void) | undefined,
       ctx: ExtensionContext,
     ): Promise<SubagentToolResult> {
-      // Lazy-load executor (spawn/stream/cost) — only when tool is actually invoked
-      const { executeSubagent, executeParallel } = await import("./execute.js");
       const agents = discoverAgents(ctx.cwd);
 
       // Parallel mode

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

@@ -40,6 +40,8 @@ export interface SubagentProgress {
 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;
@@ -63,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;