@pi-archimedes/subagent 2.2.0 → 2.4.0

package/src/stream.test.ts

@@ -2,7 +2,8 @@ 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";
+import { getBus, Events } from "@pi-archimedes/core/bus";
+import { streamEvents, type StreamCallbacks } from "./stream.js";
 
 type FakeChild = ChildProcess & { stdout: PassThrough; stderr: PassThrough };
 
@@ -16,9 +17,12 @@ function fakeChild(): FakeChild {
   return child;
 }
 
-async function finishWith(events: Array<Record<string, unknown>>) {
+async function finishWith(
+  events: Array<Record<string, unknown>>,
+  callbacks: StreamCallbacks = {},
+) {
   const child = fakeChild();
-  const result = streamEvents(child);
+  const result = streamEvents(child, callbacks);
   for (const event of events) {
     child.stdout.write(`${JSON.stringify(event)}\n`);
   }
@@ -26,6 +30,7 @@ async function finishWith(events: Array<Record<string, unknown>>) {
   return result;
 }
 
+
 describe("streamEvents session identity", () => {
   it("returns the logical child Pi session ID", async () => {
     const result = await finishWith([{
@@ -45,3 +50,262 @@ describe("streamEvents session identity", () => {
     expect(result.childSessionId).toBeUndefined();
   });
 });
+
+describe("streamEvents todo mirroring", () => {
+  const start = {
+    type: "tool_execution_start",
+    toolCallId: "t1",
+    toolName: "manage_todo_list",
+    args: {
+      operation: "write",
+      todoList: [{ id: 1, title: "Fix auth", status: "not-started" }],
+    },
+  } as unknown as Record<string, unknown>;
+
+  it("mirrors the child-accepted state from result.details.todos", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const clears: Array<{ source: string }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+    const offClear = getBus().on(Events.TODOS_CLEAR, (p: unknown) =>
+      clears.push(p as { source: string }),
+    );
+
+    await finishWith(
+      [
+        start,
+        {
+          type: "tool_execution_end",
+          toolCallId: "t1",
+          toolName: "manage_todo_list",
+          isError: false,
+          result: {
+            content: [{ type: "text", text: "ok" }],
+            details: {
+              operation: "write",
+              todos: [{ content: "Fix auth", status: "pending" }],
+            },
+          },
+        },
+      ],
+      { agent: "t-acc" },
+    );
+    off();
+    offClear();
+
+    expect(updates).toHaveLength(1);
+    expect(updates[0]!.source).toBe("subagent:t-acc");
+    expect(updates[0]!.todos).toEqual([
+      { content: "Fix auth", status: "pending" },
+    ]);
+    // Bus re-drains queued events (emitted while unsubscribed) to the next
+    // subscriber, so stale "subagent:general" clears from earlier tests may
+    // be present — assert on the per-agent source instead of the raw count.
+    expect(clears.filter((c) => c.source === "subagent:t-acc")).toHaveLength(1);
+  });
+
+  it("mirrors nothing when the tool returned a validation rejection (result.isError)", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+
+    await finishWith(
+      [
+        start,
+        {
+          type: "tool_execution_end",
+          toolCallId: "t1",
+          toolName: "manage_todo_list",
+          isError: false,
+          result: {
+            content: [{ type: "text", text: "Validation failed" }],
+            details: {
+              operation: "write",
+              todos: [{ content: "Old item", status: "completed" }],
+              error: "Item 1: missing or invalid 'content'",
+            },
+            isError: true,
+          },
+        },
+      ],
+      { agent: "t-rej" },
+    );
+    off();
+
+    expect(updates).toHaveLength(0);
+  });
+
+  it("mirrors nothing when the harness reported an error (event.isError)", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+
+    await finishWith(
+      [
+        start,
+        {
+          type: "tool_execution_end",
+          toolCallId: "t1",
+          toolName: "manage_todo_list",
+          isError: true,
+          result: {
+            content: [{ type: "text", text: "Aborted" }],
+            details: {},
+          },
+        },
+      ],
+      { agent: "t-rej2" },
+    );
+    off();
+
+    expect(updates).toHaveLength(0);
+  });
+
+  it("falls back to normalized raw args when the accepted result has no details", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+
+    await finishWith(
+      [
+        start,
+        {
+          type: "tool_execution_end",
+          toolCallId: "t1",
+          toolName: "manage_todo_list",
+          isError: false,
+          result: { content: [{ type: "text", text: "ok" }] },
+        },
+      ],
+      { agent: "t-nodetails" },
+    );
+    off();
+
+    expect(updates).toHaveLength(1);
+    expect(updates[0]!.source).toBe("subagent:t-nodetails");
+    expect(updates[0]!.todos).toEqual([
+      { content: "Fix auth", status: "pending" },
+    ]);
+  });
+
+  it("does not crash or emit when the end event has no matching start", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+
+    const result = await finishWith(
+      [
+        {
+          type: "tool_execution_end",
+          toolCallId: "orphan",
+          toolName: "manage_todo_list",
+          isError: false,
+          result: { content: [{ type: "text", text: "ok" }] },
+        },
+      ],
+      { agent: "t-orphan" },
+    );
+    off();
+
+    expect(result.exitCode).toBe(0);
+    expect(updates).toHaveLength(0);
+  });
+
+  it("does not emit for non-todo tools with todoList-shaped args", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+
+    await finishWith(
+      [
+        {
+          type: "tool_execution_start",
+          toolCallId: "b1",
+          toolName: "bash",
+          args: {
+            operation: "write",
+            todoList: [{ content: "Fix auth", status: "pending" }],
+          },
+        },
+        {
+          type: "tool_execution_end",
+          toolCallId: "b1",
+          toolName: "bash",
+          isError: false,
+          result: {
+            content: [{ type: "text", text: "ok" }],
+            details: {
+              operation: "write",
+              todos: [{ content: "Fix auth", status: "pending" }],
+            },
+          },
+        },
+      ],
+      { agent: "t-bash" },
+    );
+    off();
+
+    expect(updates).toHaveLength(0);
+  });
+
+  it("uses a unique per-child source when the child provides a session id", async () => {
+    const updates: Array<{ source: string; todos: unknown[] }> = [];
+    const clears: Array<{ source: string }> = [];
+    const off = getBus().on(Events.TODOS_UPDATE, (p: unknown) =>
+      updates.push(p as (typeof updates)[number]),
+    );
+    const offClear = getBus().on(Events.TODOS_CLEAR, (p: unknown) =>
+      clears.push(p as { source: string }),
+    );
+
+    const agent = "t-unique";
+    const idA = "11111111-1111-7111-8111-111111111111";
+    const idB = "22222222-2222-7222-8222-222222222222";
+
+    const accepted = {
+      type: "tool_execution_end",
+      toolCallId: "t1",
+      toolName: "manage_todo_list",
+      isError: false,
+      result: {
+        content: [{ type: "text", text: "ok" }],
+        details: {
+          operation: "write",
+          todos: [{ content: "Fix auth", status: "pending" }],
+        },
+      },
+    } as unknown as Record<string, unknown>;
+
+    // Two concurrent children, same agent, distinct session ids.
+    await finishWith(
+      [{ type: "session", id: idA }, start, accepted],
+      { agent },
+    );
+    await finishWith(
+      [{ type: "session", id: idB }, start, accepted],
+      { agent },
+    );
+    off();
+    offClear();
+
+    const sources = updates.map((u) => u.source);
+    // Each child gets its own suffixed source equal to subagent:<agent>:<uuid>.
+    expect(sources).toContain(`subagent:${agent}:${idA}`);
+    expect(sources).toContain(`subagent:${agent}:${idB}`);
+    // The two concurrent children must NOT share a single source.
+    expect(sources.filter((s) => s.startsWith(`subagent:${agent}:`))).toEqual([
+      `subagent:${agent}:${idA}`,
+      `subagent:${agent}:${idB}`,
+    ]);
+    // The clear on close carries the same suffixed source for each child.
+    expect(clears.filter((c) => c.source === `subagent:${agent}:${idA}`)).toHaveLength(1);
+    expect(clears.filter((c) => c.source === `subagent:${agent}:${idB}`)).toHaveLength(1);
+  });
+});
+

package/src/stream.ts

@@ -2,6 +2,7 @@ import { createInterface } from "node:readline";
 import type { ChildProcess } from "node:child_process";
 import type { StreamState, SubagentProgress, SubagentResult } from "./types.js";
 import { getBus, Events } from "@pi-archimedes/core/bus";
+import { normalizeTodoItems } from "@pi-archimedes/todo/prepare-args";
 import {
   type JsonEvent,
   handleToolStart,
@@ -111,6 +112,12 @@ export function streamEvents(
 
     const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
 
+    // toolCallId → raw todoList from tool_execution_start, consumed by the
+    // matching tool_execution_end. pi emits tool_execution_start with the
+    // raw (pre-prepareToolCall) arguments, so these may be unrepaired.
+    const pendingTodoArgs = new Map<string, unknown[]>();
+    let subagentSource = `subagent:${callbacks.agent ?? "general"}`;
+
     rl.on("line", (line) => {
       const trimmed = line.trim();
       if (!trimmed) return;
@@ -130,26 +137,46 @@ export function streamEvents(
         case "session": {
           if (typeof event.id === "string" && event.id) {
             state.childSessionId = event.id;
+            // A child with a session id gets a unique per-child todo source so
+            // concurrent children sharing an agent name don't clobber each
+            // other's accepted state when one clears on exit. Children without
+            // a session id (e.g. tests) keep the legacy subagent:<agent> form.
+            subagentSource = `subagent:${callbacks.agent ?? "general"}:${event.id}`;
           }
           break;
         }
         case "tool_execution_start": {
           handleToolStart(state, event);
           emitProgress();
-          // Forward manage_todo_list writes to the parent's todo widget
-          if (event.toolName === "manage_todo_list") {
+          if (event.toolName === "manage_todo_list" && typeof event.toolCallId === "string") {
             const args = event.args as Record<string, unknown> | undefined;
-            const todoList = args?.todoList as Array<unknown> | undefined;
+            const todoList = args?.todoList;
             if (Array.isArray(todoList)) {
-              getBus().emit(Events.TODOS_UPDATE, {
-                source: `subagent:${callbacks.agent ?? "general"}`,
-                todos: todoList,
-              });
+              pendingTodoArgs.set(event.toolCallId, todoList);
             }
           }
           break;
         }
         case "tool_execution_end": {
+          if (event.toolName === "manage_todo_list") {
+            const id = typeof event.toolCallId === "string" ? event.toolCallId : undefined;
+            const stowed = id ? pendingTodoArgs.get(id) : undefined;
+            if (id) pendingTodoArgs.delete(id);
+            const result = event.result as Record<string, unknown> | undefined;
+            // Tool-level failure (todo's execute() RETURNS {isError:true} on validation
+            // rejection — it does not throw) arrives as event.isError=false with
+            // result.isError=true. Harness failures (abort, not-found, block, throw)
+            // arrive as event.isError=true. Check BOTH — the same convention
+            // handleToolResult in handlers.ts already uses.
+            const failed = event.isError === true || result?.isError === true;
+            if (!failed) {
+              const detailsTodos = (result?.details as Record<string, unknown> | undefined)?.todos;
+              const todos = normalizeTodoItems(Array.isArray(detailsTodos) ? detailsTodos : stowed);
+              if (todos) {
+                getBus().emit(Events.TODOS_UPDATE, { source: subagentSource, todos });
+              }
+            }
+          }
           handleToolEnd(state);
           emitProgress();
           handleToolResult(state, event);
@@ -218,7 +245,7 @@ export function streamEvents(
 
       // Clear subagent todos from the bus on exit
       getBus().emit(Events.TODOS_CLEAR, {
-        source: `subagent:${callbacks.agent ?? "general"}`,
+        source: subagentSource,
       });
 
       resolve(result);

package/src/tool-schema.ts

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+
+// ── JSON Schema for tool parameters (TypeBox) ──────────────────────────────
+
+const TaskItem = Type.Object({
+  agent: Type.Optional(Type.String({
+    description: "Agent name for this task (optional). If omitted, runs config-less.",
+  })),
+  task: Type.String(),
+  model: Type.Optional(Type.String()),
+  cwd: Type.Optional(Type.String()),
+});
+
+export const SUBAGENT_PARAMS_SCHEMA = Type.Object({
+  agent: Type.Optional(Type.String({
+    description: "Agent name (optional). If omitted, the subagent runs config-less — parent's current model, all tools, no system-prompt override. Call list_agents to see available agents.",
+  })),
+  task: Type.Optional(Type.String({
+    description: "Task description for the subagent. Required when not using 'tasks' array.",
+  })),
+  tasks: Type.Optional(Type.Array(TaskItem, {
+    description: "Multiple tasks for parallel execution. Required when not using 'task'.",
+  })),
+  model: Type.Optional(Type.String({
+    description: "Model override for the subagent",
+  })),
+  async: Type.Optional(Type.Boolean({
+    description: "Run asynchronously (fire-and-forget)",
+  })),
+  cwd: Type.Optional(Type.String({
+    description: "Working directory for the subagent",
+  })),
+});