@pi-archimedes/todo 2.2.0 → 2.4.0

package/README.md

@@ -17,7 +17,7 @@ Track complex multi-step tasks structured in a todo list with automatic clearing
 
 ### Multiple todos with progress tracking
 
-Widget showing three todos with completion status — completed items dimmed with strikethrough, in-progress highlighted:
+Widget showing three todos with completion status — completed items dimmed with strikethrough, the item currently being worked on highlighted:
 
 ![todos multiple todos](../../docs/images/todos-multiple-todos.png)
 
@@ -59,9 +59,9 @@ The `manage_todo_list` tool accepts two operations:
 {
   "operation": "write",
   "todoList": [
-    { "id": 1, "title": "Parse config files", "description": "Read and validate all config files", "status": "in-progress" },
-    { "id": 2, "title": "Build state manager", "description": "Implement TodoStateManager class", "status": "not-started" },
-    { "id": 3, "title": "Wire up widget", "description": "Connect widget to bus events", "status": "not-started" }
+    { "content": "Parse config files", "description": "Read and validate all config files", "status": "in_progress" },
+    { "content": "Build state manager", "description": "Implement TodoStateManager class", "status": "pending" },
+    { "content": "Wire up widget", "description": "Connect widget to bus events", "status": "pending" }
   ]
 }
 ```
@@ -75,8 +75,8 @@ The `manage_todo_list` tool accepts two operations:
 
 | Status | Icon | Description |
 |--------|------|-------------|
-| `not-started` | ○ | Not yet begun |
-| `in-progress` | ◉ | Currently being worked on |
+| `pending` | ○ | Not yet begun |
+| `in_progress` | ◉ | Currently being worked on |
 | `completed` | ✓ | Fully finished |
 
 ## Auto-clear

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/todo",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -10,8 +10,12 @@
     "src"
   ],
   "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./prepare-args": "./src/prepare-args.ts"
+  },
   "dependencies": {
-    "@pi-archimedes/core": "2.2.0"
+    "@pi-archimedes/core": "2.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=0.1.0",
@@ -19,6 +23,9 @@
     "@earendil-works/pi-tui": ">=0.1.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/index.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Index-level test: the bus consumer guarantee.
+ *
+ * The parent todo widget receives subagent todo state ONLY via the
+ * TODOS_UPDATE bus event. These tests prove that whatever the producer
+ * emits (legacy shapes, garbage) the consumer stored in `subagentTodos`
+ * is always canonical — the widget can render real text and can never
+ * print the string "undefined".
+ */
+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 { registerTodo } from "./index.js";
+
+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: {} };
+
+  const pi = {
+    on(evt: string, fn: Function) {
+      handlers[evt] = fn;
+    },
+    registerTool(tool: any) {
+      registered.tool = tool;
+    },
+    registerCommand(name: string, def: unknown) {
+      registered.commands[name] = def;
+    },
+  } as unknown as ExtensionAPI;
+
+  const ctx = {
+    ui: {
+      setWidget(id: string, component: unknown) {
+        captured[id] = component;
+      },
+    },
+    sessionManager: { getBranch: () => [] },
+  } as any;
+
+  // The widget calls theme.fg / theme.strikethrough; same behavior these
+  // tests rely on (identity-ish, no ANSI) is enough to inspect the text.
+  const theme: any = {
+    fg: (_c: unknown, s: unknown) => String(s),
+    strikethrough: (s: unknown) => String(s),
+  };
+
+  function renderLines(): string[] {
+    // Read fresh on every render step — the factory can be replaced, or
+    // self-cleared to undefined, between steps.
+    const factory = captured["todo-list"] as
+      | ((_tui: unknown, t: unknown) => { render(width: number): string[]; invalidate(): void })
+      | undefined;
+    expect(typeof factory).toBe("function");
+    const comp = factory!(null, theme);
+    return comp.render(200);
+  }
+
+  beforeAll(() => {
+    registerTodo(pi as any);
+  });
+
+  it("normalizes a legacy subagent payload — renders real text, never 'undefined'", async () => {
+    // CRITICAL ordering: session_start must fire BEFORE seeding, because
+    // reconstructState → state.loadFromSession(ctx) resets the list from
+    // getBranch() (mock returns []), which would wipe the seed.
+    const start = handlers.session_start;
+    if (typeof start !== "function") throw new Error("session_start handler not registered");
+    let anyP: unknown;
+    anyP = start(undefined, ctx as any);
+    await anyP;
+
+    // Seed main state through the real tool.
+    const result = await registered.tool.execute(
+      "c1",
+      { operation: "write", todoList: [{ content: "Main task", status: "pending" }] },
+      undefined,
+      undefined,
+      ctx as any,
+    );
+    expect(result.isError).toBeFalsy();
+
+    // Legacy (old-schema) subagent payload: id/title/not-started.
+    getBus().emit(Events.TODOS_UPDATE, {
+      source: "subagent:fake1",
+      todos: [{ id: 1, title: "Old shape task", status: "not-started" }],
+    });
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(joined).toContain("Old shape task");
+    expect(joined).toContain("Main task");
+    expect(joined).not.toContain("undefined");
+  });
+
+  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, {
+        source: "subagent:fake2",
+        todos: [{ status: "pending" }],
+      });
+    }).not.toThrow();
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(joined).toContain("Main task");
+    expect(lines.some((l) => l.includes("subagent (fake2)"))).toBe(false);
+  });
+
+  it("TODOS_CLEAR removes the subagent column", () => {
+    getBus().emit(Events.TODOS_CLEAR, { source: "subagent:fake1" });
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(lines.some((l) => l.includes("subagent (fake1)"))).toBe(false);
+    expect(joined).toContain("Main task");
+  });
+
+  it("renders the plain agent name for a unique per-child (suffixed) source", async () => {
+    // Fresh setup mirroring test 1: session_start first (resets main), then
+    // seed main through the real tool, then a suffixed subagent bus emit.
+    const start = handlers.session_start;
+    if (typeof start !== "function") throw new Error("session_start handler not registered");
+    let anyP: unknown;
+    anyP = start(undefined, ctx as any);
+    await anyP;
+
+    const result = await registered.tool.execute(
+      "c1",
+      { operation: "write", todoList: [{ content: "Main task", status: "pending" }] },
+      undefined,
+      undefined,
+      ctx as any,
+    );
+    expect(result.isError).toBeFalsy();
+
+    // Per-child source now carries a suffix; the header must still render
+    // just the agent name, not the uuid.
+    getBus().emit(Events.TODOS_UPDATE, {
+      source: "subagent:fake1:aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
+      todos: [{ id: 1, title: "Old shape task", status: "not-started" }],
+    });
+
+    const lines = renderLines();
+    const joined = lines.join("\n");
+    expect(lines.some((l) => l.includes("subagent (fake1)"))).toBe(true);
+    expect(joined).toContain("Old shape task");
+    expect(joined).toContain("Main task");
+    expect(joined).not.toContain("undefined");
+  });
+
+  afterAll(() => {
+    // Unsubscribes the bus 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

@@ -2,6 +2,7 @@ import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@e
 import { getBus, Events } from "@pi-archimedes/core/bus";
 import { TodoStateManager } from "./state-manager.js";
 import { createManageTodoListTool } from "./tool.js";
+import { normalizeTodoItems } from "./prepare-args.js";
 import { updateWidget, clearWidget } from "./ui/todo-widget.js";
 import type { TodoItem } from "./types.js";
 
@@ -25,8 +26,17 @@ export function registerTodo(pi: ExtensionAPI): void {
   const unsubTodosUpdate = getBus().on(Events.TODOS_UPDATE, (payload: unknown) => {
     const data = payload as { source: string; todos: TodoItem[] };
     if (data.source === "main") return; // main handled locally
-    subagentTodos.set(data.source, data.todos);
-    refreshWidget();
+    // The consumer is the guarantee: producers (subagent stream, older
+    // child sessions) may emit raw or legacy shapes, so every incoming
+    // payload is normalized before it is stored. Unrecoverable payloads
+    // (normalizeTodoItems → undefined) and empty lists are not mirrored —
+    // the widget hides empty subagent columns, and TODOS_CLEAR/child-exit
+    // remain the lifecycle ends.
+    const normalized = normalizeTodoItems(data.todos);
+    if (normalized && normalized.length > 0) {
+      subagentTodos.set(data.source, normalized);
+      refreshWidget();
+    }
   });
   unsubscribes.push(unsubTodosUpdate);
 

package/src/prepare-args.test.ts

@@ -0,0 +1,274 @@
+import { describe, it, expect } from "vitest";
+import {
+  deriveTitleFromDescription,
+  normalizeTodoItem,
+  normalizeTodoItems,
+  prepareTodoArguments,
+} from "./prepare-args.js";
+
+// Arguments captured (after JSON decoding) from real failing tool calls in
+// archived sessions — the cases this module exists to repair.
+const REAL_STRINGIFIED_LIST =
+  '[{"id": 1", "title": "Catalog all undocumented env vars", "description": ' +
+  '"Compare env vars from all K8s manifests against what is in AI-SETUP.md", ' +
+  '"status": "completed"}, {"id": 2", "title": "Add K8s env vars section", ' +
+  '"description": "Document all container-level env vars", ' +
+  '"status": "in-progress"}]';
+
+// Legacy 4-field shape (id/title/description + dashed statuses) that older
+// sessions persisted — must normalize to the canonical {content, status}.
+const LEGACY_ITEM = { id: 1, title: "Fix auth", description: "Y", status: "not-started" };
+
+describe("prepareTodoArguments", () => {
+  it("passes through already-valid canonical arguments unchanged", () => {
+    const input = {
+      operation: "write",
+      todoList: [
+        { content: "Fix auth", status: "pending" as const },
+        { content: "Ship it", status: "completed" as const },
+      ],
+    };
+    const out = prepareTodoArguments(input);
+    expect(out).toEqual(input);
+    for (const item of out.todoList!) {
+      expect(Object.keys(item as Record<string, unknown>)).not.toContain("id");
+      expect(Object.keys(item as Record<string, unknown>)).not.toContain("title");
+    }
+  });
+
+  it("passes non-object arguments through untouched", () => {
+    for (const garbage of [null, undefined, 42, "write", [1, 2]]) {
+      expect(prepareTodoArguments(garbage)).toBe(garbage);
+    }
+  });
+
+  it("normalizes a legacy item (id/title/not-started) to canonical, dropping id", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [LEGACY_ITEM] });
+    expect(out.todoList).toEqual([{ content: "Fix auth", description: "Y", status: "pending" }]);
+  });
+
+  it("reads Codex-shaped items ({step, status}) into content", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ step: "X", status: "in_progress" }] });
+    expect(out.todoList).toEqual([{ content: "X", status: "in_progress" }]);
+  });
+
+  it("strips id (even null) and folds spaced statuses", () => {
+    const out = prepareTodoArguments({
+      operation: "write",
+      todoList: [{ id: null, content: "X", status: "in progress" }],
+    });
+    expect(out.todoList).toEqual([{ content: "X", status: "in_progress" }]);
+  });
+
+  it("recovers content from activeForm alone", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ activeForm: "Adding tests" }] });
+    expect(out.todoList).toEqual([{ content: "Adding tests", status: "pending" }]);
+  });
+
+  it("wraps bare-string items into canonical items", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: ["write tests", "deploy it"] });
+    expect(out.todoList).toEqual([
+      { content: "write tests", status: "pending" },
+      { content: "deploy it", status: "pending" },
+    ]);
+  });
+
+  it("parses a stringified todoList (real-world case, incl. mangled quotes)", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: REAL_STRINGIFIED_LIST });
+    expect(out.operation).toBe("write");
+    expect(out.todoList).toEqual([
+      {
+        content: "Catalog all undocumented env vars",
+        description: "Compare env vars from all K8s manifests against what is in AI-SETUP.md",
+        status: "completed",
+      },
+      {
+        content: "Add K8s env vars section",
+        description: "Document all container-level env vars",
+        status: "in_progress",
+      },
+    ]);
+  });
+
+  it("returns a stringified list it cannot parse, so the schema error still fires", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: "[{ def 《" });
+    expect(out.todoList).toBe("[{ def 《");
+  });
+
+  it("last-resort scan picks the first unreserved string field", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ instruction: "do X", status: "pending" }] });
+    expect(out.todoList).toEqual([{ content: "do X", status: "pending" }]);
+  });
+
+  it("last-resort scan does NOT pick up status or id values", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ id: 42, status: "bad" }] });
+    expect(out.todoList).toEqual([{ content: "", status: "pending" }]);
+  });
+
+  it("copies description from fallback keys (notes)", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [{ title: "X", notes: "n" }] });
+    expect(out.todoList).toEqual([{ content: "X", description: "n", status: "pending" }]);
+  });
+
+  it("normalizes status synonyms, spacing and dashes", () => {
+    const out = prepareTodoArguments({
+      operation: "write",
+      todoList: [
+        { content: "a", status: "In_Progress" },
+        { content: "b", status: "Done" },
+        { content: "c", status: "doing" },
+        { content: "d", status: "Pending" },
+        { content: "e", status: "CLOSED" },
+        { content: "f", status: "in-progress" },
+        { content: "g", status: "wip" },
+        { content: "h", status: "open" },
+        { content: "i" },
+      ],
+    });
+    const statuses = (out.todoList as Array<Record<string, unknown>>).map((item) => item?.status);
+    expect(statuses).toEqual([
+      "in_progress",
+      "completed",
+      "in_progress",
+      "pending",
+      "completed",
+      "in_progress",
+      "in_progress",
+      "pending",
+      "pending",
+    ]);
+  });
+
+  it("end-to-end: prepareTodoArguments emits operation and canonical list", () => {
+    const out = prepareTodoArguments({
+      operation: "write",
+      todoList: [{ content: "a", status: "pending" }, LEGACY_ITEM],
+    });
+    expect(out).toEqual({
+      operation: "write",
+      todoList: [
+        { content: "a", status: "pending" },
+        { content: "Fix auth", description: "Y", status: "pending" },
+      ],
+    });
+  });
+
+  it("infers operation from a present list, tolerates casing, and defaults to read", () => {
+    const withList = prepareTodoArguments({ operation: "WRITE-please", todoList: ["x"] });
+    expect(withList.operation).toBe("write");
+    const inferred = prepareTodoArguments({ todoList: ["x"] });
+    expect(inferred.operation).toBe("write");
+    const read = prepareTodoArguments({});
+    expect(read).toEqual({ operation: "read" });
+  });
+
+  it("drops a null todoList and doesn't fabricate one", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: null });
+    expect(out).toEqual({ operation: "write" });
+    expect(Object.hasOwn(out, "todoList")).toBe(false);
+  });
+
+  it("wraps a single bare object in an array and drops extra keys (item + top level)", () => {
+    const out = prepareTodoArguments({
+      operation: "write",
+      extraTop: "drop me",
+      todoList: { content: "a", fluff: true, status: "completed" },
+    });
+    expect(out).toEqual({ operation: "write", todoList: [{ content: "a", status: "completed" }] });
+  });
+
+  it("keeps null items null so the schema error stays meaningful", () => {
+    const out = prepareTodoArguments({ operation: "write", todoList: [null, "x"] });
+    expect(out.todoList).toEqual([null, { content: "x", status: "pending" }]);
+  });
+
+  it("is idempotent on repaired output", () => {
+    const once = prepareTodoArguments({ operation: "write", todoList: REAL_STRINGIFIED_LIST });
+    expect(prepareTodoArguments(once)).toEqual(once);
+    const legacy = prepareTodoArguments({ operation: "write", todoList: [LEGACY_ITEM] });
+    expect(prepareTodoArguments(legacy)).toEqual(legacy);
+  });
+});
+
+describe("normalizeTodoItem", () => {
+  it("returns a fresh canonical object (no id/title/description keys)", () => {
+    const out = normalizeTodoItem({ content: "Fix auth", status: "pending" }, 0);
+    expect(out).toEqual({ content: "Fix auth", status: "pending" });
+  });
+
+  it("keeps a textless item as an empty (valid-string) content item", () => {
+    expect(normalizeTodoItem({}, 0)).toEqual({ content: "", status: "pending" });
+  });
+
+  it("returns non-object items unchanged", () => {
+    expect(normalizeTodoItem(3, 0)).toBe(3);
+    expect(normalizeTodoItem("", 0)).toBe("");
+  });
+
+  it("derives content from description when only description was given", () => {
+    const desc = "Understand what c12d4a0 fixed and how the current base interacts with it";
+    const out = normalizeTodoItem({ description: desc, status: "in-progress" }, 0);
+    expect(out).toEqual({
+      content: deriveTitleFromDescription(desc),
+      description: desc,
+      status: "in_progress",
+    });
+  });
+});
+
+describe("normalizeTodoItems", () => {
+  it("returns canonical items as-is", () => {
+    expect(
+      normalizeTodoItems([
+        { content: "a", status: "pending" },
+        { content: "b", status: "in_progress" },
+      ])
+    ).toEqual([
+      { content: "a", status: "pending" },
+      { content: "b", status: "in_progress" },
+    ]);
+  });
+
+  it("normalizes legacy items", () => {
+    expect(normalizeTodoItems([LEGACY_ITEM])).toEqual([{ content: "Fix auth", description: "Y", status: "pending" }]);
+  });
+
+  it("returns [] for an empty input array", () => {
+    expect(normalizeTodoItems([])).toEqual([]);
+  });
+
+  it("returns undefined for null/undefined input", () => {
+    expect(normalizeTodoItems(null)).toBeUndefined();
+    expect(normalizeTodoItems(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when no item survives", () => {
+    expect(normalizeTodoItems([{ content: "", status: "pending" }])).toBeUndefined();
+    expect(normalizeTodoItems(["", null])).toBeUndefined();
+  });
+
+  it("wraps a single looks-like-todo object", () => {
+    expect(normalizeTodoItems({ title: "X", status: "not-started" })).toEqual([
+      { content: "X", status: "pending" },
+    ]);
+  });
+
+  it("returns undefined for unrelated values", () => {
+    expect(normalizeTodoItems(42)).toBeUndefined();
+    expect(normalizeTodoItems("a string")).toBeUndefined();
+  });
+});
+
+describe("deriveTitleFromDescription", () => {
+  it("returns short descriptions verbatim", () => {
+    expect(deriveTitleFromDescription("  Fix   the  build ")).toBe("Fix the build");
+  });
+
+  it("cuts long descriptions at a word boundary with an ellipsis", () => {
+    const long = "Understand what c12d4a0 fixed and how the current base interacts with it including patch 8";
+    const title = deriveTitleFromDescription(long);
+    expect(title.endsWith("…")).toBe(true);
+    expect(title.length).toBeLessThanOrEqual(61);
+    expect(title.endsWith(" ")).toBe(false);
+  });
+});