@pi-archimedes/todo 2.10.4 → 2.11.1

package/README.md

@@ -44,7 +44,7 @@ Two operations, `write` and `read`:
   "todoList": [
     { "content": "Parse config files", "description": "Read and validate settings", "status": "completed" },
     { "content": "Build state manager", "description": "Implement reactive store", "status": "in_progress" },
-    { "content": "Connect UI widget", "description": "Bind to core bus events", "status": "pending" }
+    { "content": "Connect UI widget", "description": "Bind to the shared event channels", "status": "pending" }
   ]
 }
 ```
@@ -68,6 +68,6 @@ When every task reaches `completed`, the widget shows a brief confirmation, then
 
 ## Part of the suite
 
-With subagents running alongside in the [full suite](https://github.com/danielcherubini/pi-archimedes), each child gets its own named column to the right of yours — it appears on the child's first non-empty todo update over core's bus (empty updates are ignored; it does not appear when the worker merely starts), and it is removed when the child exits. The 2-second auto-clear is local to whatever list completed — a child clearing its own list does not dismiss the column in your session. On/off is managed by the suite: toggle via `/plugins` (`archimedes.todo.enabled`, default on).
+With subagents running alongside in the [full suite](https://github.com/danielcherubini/pi-archimedes), each child gets its own named column to the right of yours — it appears on the child's first non-empty todo update over the host's event bus, `pi.events` (empty updates are ignored; it does not appear when the worker merely starts), and it is removed when the child exits. The 2-second auto-clear is local to whatever list completed — a child clearing its own list does not dismiss the column in your session. On/off is managed by the suite: toggle via `/plugins` (`archimedes.todo.enabled`, default on).
 
 ← [Back to pi-archimedes](https://github.com/danielcherubini/pi-archimedes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/todo",
-  "version": "2.10.4",
+  "version": "2.11.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -19,17 +19,19 @@
     "./prepare-args": "./src/prepare-args.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.10.4"
+    "@pi-archimedes/core": "2.11.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.1.0",
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0"
+    "@earendil-works/pi-ai": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
+    "typebox": ">=1.1.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.87.0",
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
+    "typebox": "^1.1.38",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/host-bus.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Cross-package transport: `subagent` emits, `todo` receives — on ONE host
+ * event bus, which is the property the retired `globalThis` bus used to
+ * provide by being process-wide.
+ *
+ * This is the unit-level shape of the headless proof in the migration report:
+ * two packages, two `ExtensionAPI` handles, one delivery. The bus object here
+ * stands in for the host's `createEventBus()`; what it must not be is a third
+ * package — nothing may own the transport any more.
+ *
+ * Red-first note: before the migration this failed because both sides talked to
+ * `getBus()` (the `globalThis` singleton) and ignored the handle handed to
+ * them, so the shared bus below saw nothing.
+ */
+import { describe, it, expect } from "vitest";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTodo } from "./index.js";
+
+/** The channel literal — the wire contract, not an import, on purpose. */
+const TODOS_UPDATE = "archimedes:todos_update";
+const TODOS_CLEAR = "archimedes:todos_clear";
+
+function fakeBus() {
+  const listeners = new Map<string, Array<(data: unknown) => void>>();
+  return {
+    emit(channel: string, data: unknown): void {
+      for (const handler of [...(listeners.get(channel) ?? [])]) handler(data);
+    },
+    on(channel: string, handler: (data: unknown) => void): () => void {
+      const subs = listeners.get(channel) ?? [];
+      subs.push(handler);
+      listeners.set(channel, subs);
+      return () => {
+        const current = listeners.get(channel) ?? [];
+        const idx = current.indexOf(handler);
+        if (idx !== -1) current.splice(idx, 1);
+      };
+    },
+    listenerCount(channel: string): number {
+      return (listeners.get(channel) ?? []).length;
+    },
+  };
+}
+
+function fakePi(bus: ReturnType<typeof fakeBus>) {
+  const handlers = new Map<string, Array<(e: unknown, ctx: unknown) => unknown>>();
+  const captured: { widget?: unknown; tools: Record<string, any> } = { tools: {} };
+  const ctx = {
+    ui: { setWidget: (_id: string, factory: unknown) => { captured.widget = factory; } },
+    sessionManager: { getBranch: () => [] },
+  };
+  const pi = {
+    on(event: string, handler: (e: unknown, ctx: unknown) => unknown) {
+      const list = handlers.get(event) ?? [];
+      list.push(handler);
+      handlers.set(event, list);
+      return () => {
+        const current = handlers.get(event) ?? [];
+        const idx = current.indexOf(handler);
+        if (idx !== -1) current.splice(idx, 1);
+      };
+    },
+    registerTool(tool: any) {
+      captured.tools[tool.name] = tool;
+    },
+    registerCommand() {},
+    events: bus,
+  };
+  const fire = async (event: string, e: unknown = { type: event }) => {
+    for (const handler of [...(handlers.get(event) ?? [])]) await handler(e, ctx);
+  };
+  return { pi: pi as unknown as ExtensionAPI, fire, ctx, captured };
+}
+
+const theme: any = { fg: (_c: unknown, s: unknown) => String(s), strikethrough: (s: unknown) => String(s) };
+
+function widgetLines(widget: unknown): string[] {
+  expect(typeof widget).toBe("function");
+  return (widget as (tui: unknown, t: unknown) => { render(w: number): string[] })(null, theme).render(200);
+}
+
+describe("todo receives subagent todos over the host bus", () => {
+  it("a subscriber registered before the emitter receives the update", async () => {
+    const bus = fakeBus();
+    const todo = fakePi(bus);
+
+    // todo subscribes FIRST (registration time, as it does today) ...
+    registerTodo(todo.pi);
+    await todo.fire("session_start");
+    expect(bus.listenerCount(TODOS_UPDATE)).toBe(1);
+
+    // ... and only then does a producer emit, from another package's handle.
+    bus.emit(TODOS_UPDATE, {
+      source: "subagent:explorer",
+      todos: [{ content: "Read the bridge", status: "in_progress" }],
+    });
+
+    const lines = widgetLines(todo.captured.widget).join("\n");
+    expect(lines).toContain("Read the bridge");
+    // The widget renders the agent NAME for a subagent column, not the raw
+    // "subagent:<name>" source — that mapping is the todo package's contract.
+    expect(lines).toContain("subagent (explorer)");
+  });
+
+  it("TODOS_CLEAR drops the column", async () => {
+    const bus = fakeBus();
+    const todo = fakePi(bus);
+    registerTodo(todo.pi);
+    await todo.fire("session_start");
+    // A main todo keeps the widget installed, so the assertion below is about
+    // the subagent column disappearing and not about the widget going away.
+    await todo.captured.tools.manage_todo_list.execute(
+      "c1",
+      { operation: "write", todoList: [{ content: "Keep the bar up", status: "pending" }] },
+      undefined,
+      undefined,
+      todo.ctx as any,
+    );
+
+    bus.emit(TODOS_UPDATE, { source: "subagent:explorer", todos: [{ content: "Temp", status: "pending" }] });
+    expect(widgetLines(todo.captured.widget).join("\n")).toContain("Temp");
+
+    bus.emit(TODOS_CLEAR, { source: "subagent:explorer" });
+    const after = widgetLines(todo.captured.widget).join("\n");
+    expect(after).not.toContain("Temp");
+    expect(after).toContain("Keep the bar up");
+  });
+
+  /**
+   * The AGENTS.md accumulation rule, made observable. Two `session_start`s in
+   * one session must not stack a second subscription — that is how a per-session
+   * `events.on()` double-delivers.
+   */
+  it("two session_starts do not cause two deliveries of one event", async () => {
+    const bus = fakeBus();
+    const todo = fakePi(bus);
+    registerTodo(todo.pi);
+    await todo.fire("session_start");
+    await todo.fire("session_start");
+    expect(bus.listenerCount(TODOS_UPDATE)).toBe(1);
+
+    const seen: unknown[] = [];
+    bus.on(TODOS_UPDATE, (p) => seen.push(p));
+    bus.emit(TODOS_UPDATE, { source: "subagent:x", todos: [{ content: "Once", status: "pending" }] });
+    expect(seen).toHaveLength(1);
+  });
+
+  it("session_shutdown unsubscribes, so a dead session stops receiving", async () => {
+    const bus = fakeBus();
+    const todo = fakePi(bus);
+    registerTodo(todo.pi);
+    await todo.fire("session_start");
+    await todo.fire("session_shutdown", { type: "session_shutdown", reason: "new" });
+    expect(bus.listenerCount(TODOS_UPDATE)).toBe(0);
+    expect(bus.listenerCount(TODOS_CLEAR)).toBe(0);
+  });
+
+  /**
+   * Three session generations on one handle, the pessimistic shape: pi gives
+   * each session its own bus today (a fresh resource loader per session), but a
+   * `session_start` also fires twice per replacement in RPC mode, and a dropped
+   * unsubscribe is invisible until something accumulates. Each generation gets a
+   * fresh `registerTodo` (pi re-runs the factory), two `session_start`s, and one
+   * emit — and must see exactly one delivery, with nothing left alive at the end.
+   */
+  it("three generations on one bus: one delivery each, nothing left subscribed", async () => {
+    const bus = fakeBus();
+    for (let generation = 1; generation <= 3; generation += 1) {
+      const todo = fakePi(bus);
+      registerTodo(todo.pi);
+      await todo.fire("session_start");
+      await todo.fire("session_start");
+      expect(bus.listenerCount(TODOS_UPDATE)).toBe(1);
+      expect(bus.listenerCount(TODOS_CLEAR)).toBe(1);
+
+      const seen: unknown[] = [];
+      const unsub = bus.on(TODOS_UPDATE, (p) => seen.push(p));
+      bus.emit(TODOS_UPDATE, {
+        source: `subagent:gen${generation}`,
+        todos: [{ content: `gen${generation}`, status: "pending" }],
+      });
+      expect(seen).toHaveLength(1);
+      unsub();
+
+      await todo.fire("session_shutdown", { type: "session_shutdown", reason: "new" });
+      expect(bus.listenerCount(TODOS_UPDATE)).toBe(0);
+      expect(bus.listenerCount(TODOS_CLEAR)).toBe(0);
+    }
+  });
+});
+
+describe("todo's own writes reach the bus a subscriber already holds", () => {
+  it("the tool emits TODOS_UPDATE on the handle it was given", async () => {
+    const bus = fakeBus();
+    const todo = fakePi(bus);
+    registerTodo(todo.pi);
+    await todo.fire("session_start");
+
+    const seen: unknown[] = [];
+    bus.on(TODOS_UPDATE, (p) => seen.push(p));
+
+    await todo.captured.tools.manage_todo_list.execute(
+      "c1",
+      { operation: "write", todoList: [{ content: "Write the bus out", status: "pending" }] },
+      undefined,
+      undefined,
+      todo.ctx as any,
+    );
+
+    expect(seen).toHaveLength(1);
+    expect((seen[0] as { source: string }).source).toBe("main");
+    expect((seen[0] as { todos: unknown[] }).todos).toEqual([
+      { content: "Write the bus out", status: "pending" },
+    ]);
+  });
+});

package/src/index.test.ts

@@ -9,14 +9,37 @@
  */
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import { Events } from "@pi-archimedes/core/events";
 import { registerTodo } from "./index.js";
 
+/** Stands in for the host's `createEventBus()` (the `pi.events` contract). */
+function fakeBus() {
+  const listeners = new Map<string, Array<(data: unknown) => void>>();
+  return {
+    emit(channel: string, data: unknown): void {
+      for (const handler of [...(listeners.get(channel) ?? [])]) handler(data);
+    },
+    on(channel: string, handler: (data: unknown) => void): () => void {
+      const subs = listeners.get(channel) ?? [];
+      subs.push(handler);
+      listeners.set(channel, subs);
+      return () => {
+        const current = listeners.get(channel) ?? [];
+        const idx = current.indexOf(handler);
+        if (idx !== -1) current.splice(idx, 1);
+      };
+    },
+  };
+}
+
 describe("todo index — bus consumer normalization", () => {
   const captured: Record<string, unknown> = {};
   const handlers: Record<string, Function> = {};
   const registered: { tool?: any; commands: Record<string, unknown> } = { commands: {} };
 
+  /** The handle `registerTodo` subscribes on and the tool emits on. */
+  const bus = fakeBus();
+
   const pi = {
     on(evt: string, fn: Function) {
       handlers[evt] = fn;
@@ -27,6 +50,7 @@ describe("todo index — bus consumer normalization", () => {
     registerCommand(name: string, def: unknown) {
       registered.commands[name] = def;
     },
+    events: bus,
   } as unknown as ExtensionAPI;
 
   const ctx = {
@@ -81,7 +105,7 @@ describe("todo index — bus consumer normalization", () => {
     expect(result.isError).toBeFalsy();
 
     // Legacy (old-schema) subagent payload: id/title/not-started.
-    getBus().emit(Events.TODOS_UPDATE, {
+    bus.emit(Events.TODOS_UPDATE, {
       source: "subagent:fake1",
       todos: [{ id: 1, title: "Old shape task", status: "not-started" }],
     });
@@ -96,8 +120,8 @@ describe("todo index — bus consumer normalization", () => {
   it("ignores unrecoverable payloads without crashing (no phantom column)", () => {
     // State from the previous test persists (same registered instance).
     expect(() => {
-      getBus().emit(Events.TODOS_UPDATE, { source: "subagent:fake2", todos: "garbage" });
-      getBus().emit(Events.TODOS_UPDATE, {
+      bus.emit(Events.TODOS_UPDATE, { source: "subagent:fake2", todos: "garbage" });
+      bus.emit(Events.TODOS_UPDATE, {
         source: "subagent:fake2",
         todos: [{ status: "pending" }],
       });
@@ -110,7 +134,7 @@ describe("todo index — bus consumer normalization", () => {
   });
 
   it("TODOS_CLEAR removes the subagent column", () => {
-    getBus().emit(Events.TODOS_CLEAR, { source: "subagent:fake1" });
+    bus.emit(Events.TODOS_CLEAR, { source: "subagent:fake1" });
 
     const lines = renderLines();
     const joined = lines.join("\n");
@@ -138,7 +162,7 @@ describe("todo index — bus consumer normalization", () => {
 
     // Per-child source now carries a suffix; the header must still render
     // just the agent name, not the uuid.
-    getBus().emit(Events.TODOS_UPDATE, {
+    bus.emit(Events.TODOS_UPDATE, {
       source: "subagent:fake1:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
       todos: [{ id: 1, title: "Old shape task", status: "not-started" }],
     });
@@ -152,7 +176,7 @@ describe("todo index — bus consumer normalization", () => {
   });
 
   afterAll(() => {
-    // Unsubscribes the bus listeners registered by registerTodo and
+    // Unsubscribes the handle listeners registered by registerTodo and
     // clears state (fixture uses a pending item, so no auto-clear timer
     // is pending, but cancel defensively).
     handlers.session_shutdown?.(undefined, ctx as any);

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import { Events } from "@pi-archimedes/core/events";
 import { TodoStateManager } from "./state-manager.js";
 import { createManageTodoListTool } from "./tool.js";
 import { normalizeTodoItems } from "./prepare-args.js";
@@ -22,8 +22,13 @@ export function registerTodo(pi: ExtensionAPI): void {
     }
   };
 
-  // Subscribe to bus events for subagent todos
-  const unsubTodosUpdate = getBus().on(Events.TODOS_UPDATE, (payload: unknown) => {
+  // Subscribe on the host handle for subagent todos. Registered here, at
+  // extension-load time, not inside a session handler: the host drops these
+  // subscriptions when the runtime is invalidated, and the factories run again
+  // for the next session, so this is exactly once per session — and it keeps
+  // the subscription live before the first turn, which is when a child can
+  // first report todos. `session_shutdown` below is its counterpart.
+  const unsubTodosUpdate = pi.events.on(Events.TODOS_UPDATE, (payload: unknown) => {
     const data = payload as { source: string; todos: TodoItem[] };
     if (data.source === "main") return; // main handled locally
     // The consumer is the guarantee: producers (subagent stream, older
@@ -40,7 +45,7 @@ export function registerTodo(pi: ExtensionAPI): void {
   });
   unsubscribes.push(unsubTodosUpdate);
 
-  const unsubTodosClear = getBus().on(Events.TODOS_CLEAR, (payload: unknown) => {
+  const unsubTodosClear = pi.events.on(Events.TODOS_CLEAR, (payload: unknown) => {
     const data = payload as { source: string };
     subagentTodos.delete(data.source);
     refreshWidget();
@@ -80,7 +85,7 @@ export function registerTodo(pi: ExtensionAPI): void {
   });
 
   // Register the manage_todo_list tool
-  const tool = createManageTodoListTool(state, refreshWidget);
+  const tool = createManageTodoListTool(state, refreshWidget, pi.events);
   pi.registerTool(tool);
 
   // Register /todos command

package/src/tool.output-schema.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Task 11 item 2 — the machine-readable half of `manage_todo_list`.
+ *
+ * pi 1.2.0 hands a codemode script the tool's `structuredContent` instead of its
+ * text, but only when the tool declares an `outputSchema`
+ * (`pi: dist/extensions/codemode/execute.js`, `toScriptValue()`), and it never
+ * validates one against the other. So the schema is a promise with no runtime
+ * referee: these tests are the referee. Every payload below is produced by
+ * running the real handler, and checked against the schema the same registered
+ * tool declares — not against a hand-copied shape.
+ *
+ * The failure paths are asserted too, and one of them is a decision rather than
+ * a fact: a failure result carries NO structured content, so a script keeps
+ * rejecting with the text it rejects with today. See `tool.ts`.
+ */
+
+import { describe, it, expect } from "vitest";
+import { Value } from "typebox/value";
+import { createManageTodoListTool } from "./tool.js";
+import { TodoStateManager } from "./state-manager.js";
+
+const noopEvents = { emit: () => {}, on: () => () => {} } as never;
+
+function harness() {
+  const tool = createManageTodoListTool(new TodoStateManager(), () => {}, noopEvents);
+  return {
+    tool,
+    call: (params: Record<string, unknown>) =>
+      tool.execute("call-1", params as never, undefined, undefined, {} as never),
+  };
+}
+
+/** Validate a real result's structured content against the schema on the tool. */
+function check(tool: { outputSchema?: unknown }, value: unknown): boolean {
+  expect(tool.outputSchema, "tool declares no outputSchema").toBeDefined();
+  return Value.Check(tool.outputSchema as never, value);
+}
+
+describe("manage_todo_list outputSchema declaration", () => {
+  it("declares an output schema shaped like the structured content", () => {
+    const { tool } = harness();
+    expect(tool.outputSchema).toBeDefined();
+    expect((tool.outputSchema as { properties?: Record<string, unknown> }).properties).toHaveProperty("todos");
+  });
+});
+
+describe("manage_todo_list structuredContent", () => {
+  it("read with an empty list → { operation: read, todos: [] }, valid against the schema", async () => {
+    const { tool, call } = harness();
+    const result = await call({ operation: "read" });
+    expect(result.structuredContent).toEqual({ operation: "read", todos: [] });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("read after a write → the stored list, items exactly as the model wrote them", async () => {
+    const { tool, call } = harness();
+    await call({
+      operation: "write",
+      todoList: [
+        { content: "One", status: "pending" },
+        { content: "Two", status: "in_progress", description: "with context" },
+      ],
+    });
+    const result = await call({ operation: "read" });
+    expect(result.structuredContent).toEqual({
+      operation: "read",
+      todos: [
+        { content: "One", status: "pending" },
+        { content: "Two", status: "in_progress", description: "with context" },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("write success → { operation: write, todos } matching the schema, content text untouched", async () => {
+    const { tool, call } = harness();
+    const result = await call({
+      operation: "write",
+      todoList: [{ content: "Ship it", status: "completed" }],
+    });
+    expect(result.isError).toBeUndefined();
+    expect(result.structuredContent).toEqual({
+      operation: "write",
+      todos: [{ content: "Ship it", status: "completed" }],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+    // The model-facing text is unchanged: models and this suite's other tests read it.
+    expect(result.content[0]!.text).toContain("1/1 completed");
+  });
+
+  it("write without a todoList → isError, and NO structured content (scripts keep rejecting with the text)", async () => {
+    const { call } = harness();
+    const result = await call({ operation: "write" });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toBe("Error: todoList is required for write operation.");
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("write that fails validation → isError, no structured content, content text untouched", async () => {
+    const { call } = harness();
+    const result = await call({
+      operation: "write",
+      todoList: [{ content: "   ", status: "pending" }],
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toContain("Validation failed:");
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("write of an empty list → { operation: write, todos: [] }, valid (a cleared list is an answer)", async () => {
+    const { tool, call } = harness();
+    const result = await call({ operation: "write", todoList: [] });
+    expect(result.isError).toBeUndefined();
+    expect(result.structuredContent).toEqual({ operation: "write", todos: [] });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+});

package/src/tool.test.ts

@@ -22,7 +22,12 @@ const theme = {
   strikethrough: (text: unknown) => `[s]${text}`,
 } as unknown as Theme;
 
-const tool = createManageTodoListTool(new TodoStateManager(), () => {});
+// The tool emits on the handle it is handed; this one has no listeners, so the
+// emits are inert here (the emit contract lives in `host-bus.test.ts`).
+const tool = createManageTodoListTool(new TodoStateManager(), () => {}, {
+  emit: () => {},
+  on: () => () => {},
+});
 
 function renderLines(result: AgentToolResult<TodoDetails | undefined>, expanded: boolean): string {
   const view = tool.renderResult(result, { expanded, isPartial: false }, theme) as {

package/src/tool.ts

@@ -1,12 +1,12 @@
 import { type Static, StringEnum, Type } from "@earendil-works/pi-ai";
-import type { AgentToolResult, ExtensionContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, EventBus, ExtensionContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { getBus, Events } from "@pi-archimedes/core/bus";
+import { Events, emitOn } from "@pi-archimedes/core/events";
 import { renderToolHeader, renderStatusLabel } from "@pi-archimedes/core/tool-render";
 import { prepareTodoArguments } from "./prepare-args.js";
 import type { TodoStateManager } from "./state-manager.js";
 import { STATUS_ICONS } from "./types.js";
-import type { TodoDetails } from "./types.js";
+import type { TodoDetails, TodoItem, TodoStatus } from "./types.js";
 
 const TodoItemSchema = Type.Object({
   content: Type.String({
@@ -33,6 +33,55 @@ export const ManageTodoListParams = Type.Object({
 
 export type ManageTodoListInput = Static<typeof ManageTodoListParams>;
 
+/**
+ * The machine-readable result, for programmatic callers.
+ *
+ * `structuredContent` mirrors `details` on success — the list as it now stands,
+ * which is the whole answer for both operations. pi hands it to a codemode
+ * script *instead of* the text, but only when the tool declares this schema, and
+ * it never checks one against the other (`pi: dist/extensions/codemode/execute.js`,
+ * `toScriptValue()`), so `tool.output-schema.test.ts` is the referee: it runs the
+ * handler and validates the payload against this schema.
+ *
+ * Failure results carry none of it. pi's own `bash` does attach structured
+ * content to a non-zero exit, because there the failing command *is* the
+ * observation; here every failure is a call that produced no observation (no
+ * list supplied, or a list the validator rejected), and pi's codemode script
+ * keeps rejecting with the text — same as before this schema existed.
+ */
+const TodoItemOutputSchema = Type.Object({
+  content: Type.String(),
+  status: StringEnum(["pending", "in_progress", "completed"] as const),
+  description: Type.Optional(Type.String()),
+});
+
+export const ManageTodoListOutput = Type.Object({
+  /** Which operation ran; the shape is the same for both. */
+  operation: StringEnum(["read", "write"] as const),
+  /** The list as it stands after the call. */
+  todos: Type.Array(TodoItemOutputSchema),
+});
+
+/**
+ * The JSON-shaped copy of a stored item. `TodoItem` is an interface, which
+ * TypeScript will not match against `JsonValue`'s index signature, and copying
+ * also pins the payload to exactly the three fields the schema declares.
+ */
+type TodoItemOutput = { content: string; status: TodoStatus; description?: string };
+
+function toOutputTodos(todos: TodoItem[]): TodoItemOutput[] {
+  return todos.map((item) => ({
+    content: item.content,
+    status: item.status,
+    ...(item.description !== undefined && { description: item.description }),
+  }));
+}
+
+/** `{ operation, todos }` — the successful result of either operation. */
+function todoOutput(operation: "read" | "write", todos: TodoItem[]): { operation: "read" | "write"; todos: TodoItemOutput[] } {
+  return { operation, todos: toOutputTodos(todos) };
+}
+
 export const TOOL_DESCRIPTION = `Manage a structured todo list to track progress and plan tasks throughout your coding session. Use this tool VERY frequently to ensure task visibility and proper planning.
 
 When to use this tool:
@@ -69,12 +118,22 @@ Todo states:
 IMPORTANT: Mark todos completed as soon as they are done. Do not batch completions.
 When all todos are completed, the list auto-clears after a brief delay.`;
 
-export function createManageTodoListTool(state: TodoStateManager, onUpdate: () => void) {
+/**
+ * Build the `manage_todo_list` tool.
+ *
+ * @param events the caller's host handle (`pi.events`). The tool is a factory,
+ *               not an extension, so it has no `pi` of its own — the handle is
+ *               injected rather than reached for, which is what keeps the suite
+ *               free of a `globalThis` bus. A child pi runs the same tool with
+ *               its OWN handle, and its writes stay inside the child.
+ */
+export function createManageTodoListTool(state: TodoStateManager, onUpdate: () => void, events: EventBus) {
   return {
     name: "manage_todo_list",
     label: "Todo List",
     description: TOOL_DESCRIPTION,
     parameters: ManageTodoListParams,
+    outputSchema: ManageTodoListOutput,
 
     // Repair common model mistakes (stringified arrays, missing
     // title/status, bare-string items) BEFORE schema validation. See
@@ -100,6 +159,7 @@ export function createManageTodoListTool(state: TodoStateManager, onUpdate: () =
             },
           ],
           details: { operation: "read", todos } as TodoDetails,
+          structuredContent: todoOutput("read", todos),
         };
       }
 
@@ -125,12 +185,11 @@ export function createManageTodoListTool(state: TodoStateManager, onUpdate: () =
       state.write(todoList);
       onUpdate();
 
-      // Emit bus event for widget update
-      try {
-        getBus().emit(Events.TODOS_UPDATE, { source: "main", todos: state.read() });
-      } catch {
-        // Bus may not be initialized in subagent child process — ignore
-      }
+      // Announce the new list on the handle: the bridge relays it to the
+      // desktop as a `todos_update` frame (and any other in-process listener,
+      // e.g. a second todo instance, sees the same payload). `onUpdate()` above
+      // is the local widget path; this is the outward one.
+      emitOn(events, Events.TODOS_UPDATE, { source: "main", todos: state.read() });
 
       const stats = state.getStats();
       const todos = state.read();
@@ -144,6 +203,7 @@ export function createManageTodoListTool(state: TodoStateManager, onUpdate: () =
       return {
         content: [{ type: "text" as const, text: message }],
         details: { operation: "write", todos } as TodoDetails,
+        structuredContent: todoOutput("write", todos),
       };
     },