@pi-archimedes/todo 2.2.0 → 2.4.0

package/src/prepare-args.ts

@@ -0,0 +1,296 @@
+/**
+ * Compatibility shim for LLM tool-call arguments.
+ *
+ * Wires into the tool via `prepareArguments`, which pi runs BEFORE schema
+ * validation (and before `execute`). The model occasionally sends
+ * malformed-but-recoverable `manage_todo_list` arguments; observed in
+ * practice (frozen open-weight models, ADR 0009):
+ *
+ *   - `todoList` is a stringified JSON array instead of an array (sometimes
+ *     with mangled escaping, e.g. `"id": 1"` — an extra quote after the
+ *     number)
+ *   - items put the task text under `title`/`step` (shapes borrowed from
+ *     other harnesses) instead of the canonical `content`
+ *   - `id` is invented, omitted, or nulled — the canonical schema has NO
+ *     `id`; display numbering is array position, so it is stripped, not
+ *     repaired
+ *   - statuses come out dashed (a hyphenated variant of a canonical
+ *     value that then collapses to a no-separator form), or as plain
+ *     english synonyms ("doing", "done")
+ *   - items are plain strings
+ *   - stray top-level / per-item keys outside the schema
+ *
+ * Only *recoverable* deviations are repaired. Anything unrecoverable is
+ * passed through untouched so the standard validation error still surfaces
+ * with the real complaint. The public schema stays strict; this module is
+ * purely a repair layer.
+ */
+
+import type { ManageTodoListInput } from "./tool.js";
+import type { TodoItem, TodoStatus } from "./types.js";
+
+type Record_ = Record<string, unknown>;
+
+const VALID_STATUSES: ReadonlySet<string> = new Set<string>([
+  "pending",
+  "in_progress",
+  "completed",
+]);
+
+/**
+ * LLM synonyms for the three enum values, keyed by the collapsed form
+ * (lowercase, all whitespace/underscore/dash separators removed) so dashed,
+ * spaced, and underscored variants all land on the same key.
+ */
+const STATUS_ALIASES: ReadonlyMap<string, TodoStatus> = new Map<string, TodoStatus>([
+  ["done", "completed"],
+  ["complete", "completed"],
+  ["finished", "completed"],
+  ["closed", "completed"],
+  ["success", "completed"],
+  ["passed", "completed"],
+  ["doing", "in_progress"],
+  ["started", "in_progress"],
+  ["working", "in_progress"],
+  ["active", "in_progress"],
+  ["wip", "in_progress"],
+  ["ongoing", "in_progress"],
+  ["inprogress", "in_progress"],
+  ["pending", "pending"],
+  ["todo", "pending"],
+  ["planned", "pending"],
+  ["untouched", "pending"],
+  ["notstarted", "pending"],
+  ["unstarted", "pending"],
+  ["open", "pending"],
+]);
+
+/**
+ * Keys the model sometimes uses instead of `content`. Checked only when
+ * `content` itself is missing/empty, so a model that DID send `content` is
+ * never overwritten.
+ */
+const CONTENT_FALLBACK_KEYS = ["title", "step", "task", "text", "name", "label", "activeForm"] as const;
+const DESCRIPTION_FALLBACK_KEYS = ["details", "notes", "summary", "context"] as const;
+
+/** Reserved keys the last-resort text scan must never pick up. */
+const LAST_RESORT_SKIP_KEYS = new Set<string>([
+  "content",
+  ...(CONTENT_FALLBACK_KEYS as readonly string[]),
+  "description",
+  ...(DESCRIPTION_FALLBACK_KEYS as readonly string[]),
+  "status",
+  "id",
+]);
+
+const DERIVED_CONTENT_MAX = 60;
+
+function isRecord(value: unknown): value is Record_ {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function firstStringOf(record: Record_, keys: readonly string[]): string {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return "";
+}
+
+/**
+ * Collapse whitespace and cut at a word boundary so a derived `content`
+ * stays a short, human-readable label in the widget.
+ */
+export function deriveTitleFromDescription(description: string): string {
+  const flat = description.replace(/\s+/g, " ").trim();
+  if (flat.length <= DERIVED_CONTENT_MAX) return flat;
+  const cut = flat.slice(0, DERIVED_CONTENT_MAX);
+  const lastSpace = cut.lastIndexOf(" ");
+  const head = lastSpace > 0 ? cut.slice(0, lastSpace) : cut;
+  return `${head.trimEnd()}…`;
+}
+
+/**
+ * Normalize a raw status to the canonical enum. Accepts dashed/spaced/
+ * underscored variants and plain-english synonyms; anything unrecognized
+ * (incl. non-strings) falls back to `"pending"`. Kept permissive — this is
+ * the REPAIR layer. `state-manager.validate()` stays canonical-strict.
+ */
+export function normalizeStatus(raw: unknown): TodoStatus {
+  if (typeof raw !== "string") {
+    // Missing, null, number, … — no signal about intent.
+    return "pending";
+  }
+  const s = raw.trim().toLowerCase();
+  if (VALID_STATUSES.has(s)) return s as TodoStatus;
+  const collapsed = s.replace(/[\s_-]+/g, "");
+  return STATUS_ALIASES.get(collapsed) ?? "pending";
+}
+
+/**
+ * Normalize one todo item. Returns a fresh object containing ONLY the
+ * canonical keys `{content, description?, status}` — `id` is always dropped,
+ * extra keys are dropped (the schema rejects them with "must not have
+ * additional properties"). Unrecoverable items are returned as-is so the
+ * schema error keeps its meaning.
+ */
+export function normalizeTodoItem(raw: unknown, index: number): unknown {
+  // Laziest form: ["write tests", "deploy"]
+  if (typeof raw === "string") {
+    const text = raw.trim();
+    if (text === "") return raw;
+    return { content: deriveTitleFromDescription(text), status: "pending" as TodoStatus };
+  }
+
+  if (!isRecord(raw)) return raw; // null / number / nested array → schema error
+
+  const description =
+    (typeof raw.description === "string" ? raw.description.trim() : "") ||
+    firstStringOf(raw, DESCRIPTION_FALLBACK_KEYS);
+  let content =
+    (typeof raw.content === "string" ? raw.content.trim() : "") ||
+    firstStringOf(raw, CONTENT_FALLBACK_KEYS);
+  if (content === "" && description !== "") {
+    content = deriveTitleFromDescription(description);
+  }
+  // Last resort: any remaining non-empty string field that isn't a known
+  // alias/status/id. This alone is the catch-all.
+  if (content === "") {
+    for (const [key, value] of Object.entries(raw)) {
+      if (!LAST_RESORT_SKIP_KEYS.has(key) && typeof value === "string" && value.trim() !== "") {
+        content = value;
+        break;
+      }
+    }
+  }
+
+  // If both are empty this returns { content: "", status } — deliberately
+  // keeps an empty (valid-string) field so state-manager.validate() reports
+  // the missing `content` instead of the schema masking it.
+  return {
+    content,
+    ...(description !== "" ? { description } : {}),
+    status: normalizeStatus(raw.status),
+  };
+}
+
+/**
+ * Normalize a raw todo list (e.g. from bus payloads) into canonical
+ * TodoItems. Returns [] for an empty input array, undefined for anything
+ * unrecoverable. Used by the bus consumer (index.ts) and the subagent
+ * stream — where prepareArguments is NOT in the call path.
+ */
+export function normalizeTodoItems(raw: unknown): TodoItem[] | undefined {
+  let list: unknown[] | undefined;
+  if (Array.isArray(raw)) {
+    list = raw;
+  } else if (raw != null && looksLikeTodoItem(raw)) {
+    list = [raw];
+  } else {
+    return undefined;
+  }
+
+  const items = list.map((item, i) => normalizeTodoItem(item, i));
+  const surviving = items.filter(
+    (item): item is TodoItem =>
+      isRecord(item) &&
+      typeof item.content === "string" &&
+      item.content.trim() !== "" &&
+      typeof item.status === "string" &&
+      VALID_STATUSES.has(item.status),
+  );
+  if (items.length === 0) return [];
+  if (surviving.length === 0) return undefined;
+  return surviving;
+}
+
+/**
+ * Repair the occasional mangled JSON: `"id": 1"` (an extra quote after the
+ * number). The replacement is safe to apply blindly — that shape is invalid
+ * JSON to begin with.
+ */
+// The long backslash sequence is spelled out as char codes for robustness.
+const ID_FIX_PATTERN = String.fromCharCode(40, 34, 105, 100, 34, 92, 115, 42, 58, 92, 115, 42, 92, 100, 43, 41, 92, 34);
+const ID_QUOTE_FIX = new RegExp(ID_FIX_PATTERN, "g");
+function repairStringifiedJson(s: string): string {
+  return s.replace(ID_QUOTE_FIX, "$1");
+}
+
+function parseStringifiedList(raw: string): unknown {
+  try {
+    return JSON.parse(repairStringifiedJson(raw));
+  } catch {
+    return raw; // Unparseable — keep the string; schema error says "must be array"
+  }
+}
+
+function looksLikeTodoItem(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    ("content" in value ||
+      "title" in value ||
+      "step" in value ||
+      "description" in value ||
+      "status" in value)
+  );
+}
+
+/**
+ * Normalize the `todoList` argument. `kept` is false only when the field was
+ * absent and must not appear in the output object at all.
+ */
+function normalizeTodoList(raw: unknown): { value: unknown; kept: boolean } {
+  let value: unknown = raw;
+  if (typeof raw === "string") value = parseStringifiedList(raw);
+
+  if (value === null) {
+    // Required-schema fields reject null; dropping the key yields the clearer
+    // "todoList is required for write operation" from execute().
+    return { value: undefined, kept: true };
+  }
+
+  if (value === undefined) return { value, kept: false };
+
+  if (Array.isArray(value)) {
+    return { value: value.map((item, i) => normalizeTodoItem(item, i)), kept: true };
+  }
+
+  // A single bare item instead of an array.
+  if (looksLikeTodoItem(value)) {
+    return { value: [normalizeTodoItem(value, 0)], kept: true };
+  }
+
+  return { value, kept: true }; // Unmendable — original validation error stands
+}
+
+function normalizeOperation(raw: unknown, listPresent: boolean): "write" | "read" {
+  if (raw === "write" || raw === "read") return raw;
+  if (typeof raw === "string") {
+    const lowered = raw.trim().toLowerCase();
+    if (lowered === "write" || lowered === "read") return lowered;
+  }
+  // Model omitted/garbled the operation: a list implies a write.
+  return listPresent ? "write" : "read";
+}
+
+/**
+ * Repair raw `manage_todo_list` call arguments before schema validation.
+ * Never throws, never mutates its input, and passes through anything it
+ * cannot recover.
+ */
+export function prepareTodoArguments(args: unknown): ManageTodoListInput {
+  if (!isRecord(args)) return args as ManageTodoListInput;
+
+  const normalized =
+    args.todoList === undefined ? undefined : normalizeTodoList(args.todoList);
+  const present =
+    normalized !== undefined && normalized.kept && normalized.value !== undefined;
+
+  const out: Record_ = {
+    operation: normalizeOperation(args.operation, present),
+  };
+  if (present) {
+    out.todoList = (normalized as { value: unknown }).value;
+  }
+  return out as ManageTodoListInput;
+}

package/src/state-manager.test.ts

@@ -1,12 +1,12 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import * as fc from "fast-check";
 import { TodoStateManager } from "./state-manager.js";
-import type { TodoItem } from "./types.js";
+import type { TodoItem, TodoStatus } from "./types.js";
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
-function makeTodo(id: number, title: string, description: string, status: TodoItem["status"]): TodoItem {
-  return { id, title, description, status };
+function makeTodo(content: string, status: TodoStatus, description?: string): TodoItem {
+  return description === undefined ? { content, status } : { content, status, description };
 }
 
 // ── TodoStateManager ────────────────────────────────────────────────────────
@@ -29,9 +29,9 @@ describe("TodoStateManager", () => {
     });
 
     it("returns copy (mutations don't affect internal state)", () => {
-      manager.write([makeTodo(1, "Test", "desc", "not-started")]);
+      manager.write([makeTodo("Task", "pending")]);
       const copy = manager.read();
-      copy.push(makeTodo(2, "Injected", "desc", "not-started"));
+      copy.push(makeTodo("Injected", "pending"));
       expect(manager.read()).toHaveLength(1);
     });
   });
@@ -39,16 +39,16 @@ describe("TodoStateManager", () => {
   describe("write", () => {
     it("stores todos correctly", () => {
       manager.write([
-        makeTodo(1, "Task 1", "desc 1", "not-started"),
-        makeTodo(2, "Task 2", "desc 2", "in-progress"),
+        makeTodo("Task 1", "pending"),
+        makeTodo("Task 2", "in_progress"),
       ]);
       expect(manager.read()).toHaveLength(2);
-      expect(manager.read()[0]?.title).toBe("Task 1");
-      expect(manager.read()[1]?.status).toBe("in-progress");
+      expect(manager.read()[0]?.content).toBe("Task 1");
+      expect(manager.read()[1]?.status).toBe("in_progress");
     });
 
     it("with all completed schedules auto-clear", () => {
-      manager.write([makeTodo(1, "Done", "desc", "completed")]);
+      manager.write([makeTodo("Done", "completed")]);
       expect(manager.read()).toHaveLength(1);
       vi.advanceTimersByTime(2000);
       expect(manager.read()).toHaveLength(0);
@@ -56,8 +56,8 @@ describe("TodoStateManager", () => {
 
     it("does not schedule auto-clear when not all completed", () => {
       manager.write([
-        makeTodo(1, "Done", "desc", "completed"),
-        makeTodo(2, "Pending", "desc", "not-started"),
+        makeTodo("Done", "completed"),
+        makeTodo("Pending", "pending"),
       ]);
       vi.advanceTimersByTime(2000);
       expect(manager.read()).toHaveLength(2);
@@ -66,25 +66,25 @@ describe("TodoStateManager", () => {
 
   describe("clear", () => {
     it("empties todos", () => {
-      manager.write([makeTodo(1, "Task", "desc", "not-started")]);
+      manager.write([makeTodo("Task", "pending")]);
       manager.clear();
       expect(manager.read()).toEqual([]);
     });
   });
 
   describe("getStats", () => {
-    it("computes correct counts", () => {
+    it("computes correct counts incl. pending", () => {
       manager.write([
-        makeTodo(1, "A", "desc", "not-started"),
-        makeTodo(2, "B", "desc", "in-progress"),
-        makeTodo(3, "C", "desc", "completed"),
-        makeTodo(4, "D", "desc", "completed"),
+        makeTodo("A", "pending"),
+        makeTodo("B", "in_progress"),
+        makeTodo("C", "completed"),
+        makeTodo("D", "completed"),
       ]);
       expect(manager.getStats()).toEqual({
         total: 4,
         completed: 2,
         inProgress: 1,
-        notStarted: 1,
+        pending: 1,
       });
     });
 
@@ -93,38 +93,56 @@ describe("TodoStateManager", () => {
         total: 0,
         completed: 0,
         inProgress: 0,
-        notStarted: 0,
+        pending: 0,
       });
     });
   });
 
   describe("validate", () => {
-    it("catches missing fields", () => {
-      const result = manager.validate([{ id: 1, title: "", description: "", status: "" } as any]);
+    it("accepts canonical items with optional description", () => {
+      const result = manager.validate([
+        { content: "Task", status: "pending" },
+        { content: "Task 2", status: "in_progress", description: "desc" },
+        { content: "Task 3", status: "completed" },
+      ]);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toEqual([]);
+    });
+
+    it("rejects empty content", () => {
+      const result = manager.validate([{ content: "  ", status: "pending" }]);
       expect(result.valid).toBe(false);
-      expect(result.errors.length).toBeGreaterThan(0);
+      expect(result.errors.some((e) => e.includes("content"))).toBe(true);
     });
 
-    it("catches invalid status values", () => {
-      const result = manager.validate([{ id: 1, title: "Test", description: "desc", status: "invalid" } as any]);
+    it("rejects missing content", () => {
+      const result = manager.validate([{ status: "pending" } as unknown as TodoItem]);
       expect(result.valid).toBe(false);
-      expect(result.errors[0]).toContain("status");
+      expect(result.errors.some((e) => e.includes("content"))).toBe(true);
     });
 
-    it("catches non-array input", () => {
-      const result = manager.validate("not an array" as any);
+    it("rejects dashed legacy statuses (validate stays canonical-strict)", () => {
+      const result = manager.validate([{ content: "Test", status: "in-progress" } as unknown as TodoItem]);
       expect(result.valid).toBe(false);
-      expect(result.errors[0]).toBe("todoList must be an array");
+      expect(result.errors.some((e) => e.includes("pending, in_progress, completed"))).toBe(true);
     });
 
-    it("accepts valid input", () => {
-      const result = manager.validate([
-        makeTodo(1, "Task", "desc", "not-started"),
-        makeTodo(2, "Task 2", "desc", "in-progress"),
-        makeTodo(3, "Task 3", "desc", "completed"),
-      ]);
-      expect(result.valid).toBe(true);
-      expect(result.errors).toEqual([]);
+    it("rejects non-string description", () => {
+      const result = manager.validate([{ content: "x", status: "pending", description: 42 } as unknown as TodoItem]);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes("description"))).toBe(true);
+    });
+
+    it("rejects undefined items", () => {
+      const result = manager.validate([undefined, { content: "x", status: "pending" }] as unknown as TodoItem[]);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes("undefined item"))).toBe(true);
+    });
+
+    it("catches non-array input", () => {
+      const result = manager.validate("not an array" as unknown as TodoItem[]);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]).toBe("todoList must be an array");
     });
 
     it("property: validate(write(x)).valid === true after write (round-trip)", () => {
@@ -132,15 +150,14 @@ describe("TodoStateManager", () => {
         fc.property(
           fc.array(
             fc.record({
-              id: fc.nat({ max: 1000 }),
-              title: fc.string({ minLength: 1, maxLength: 50 }),
-              description: fc.string({ minLength: 1, maxLength: 100 }),
-              status: fc.oneof(fc.constant("not-started"), fc.constant("in-progress"), fc.constant("completed")),
+              content: fc.string({ minLength: 1, maxLength: 50 }),
+              description: fc.string({ minLength: 0, maxLength: 100 }),
+              status: fc.oneof(fc.constant("pending"), fc.constant("in_progress"), fc.constant("completed")),
             }),
           ),
           (todos) => {
             const mgr = new TodoStateManager();
-            mgr.write(todos as TodoItem[]);
+            mgr.write(todos.filter((t) => t.content.trim() !== "") as TodoItem[]);
             const readTodos = mgr.read();
             const result = mgr.validate(readTodos);
             if (!result.valid) {
@@ -152,4 +169,58 @@ describe("TodoStateManager", () => {
       );
     });
   });
+
+  describe("loadFromSession", () => {
+    function fakeCtx(branch: unknown[]): unknown {
+      return { sessionManager: { getBranch: () => branch } };
+    }
+
+    function toolResultEntry(details: unknown): unknown {
+      return { type: "message", message: { role: "toolResult", toolName: "manage_todo_list", details } };
+    }
+
+    it("normalizes legacy persisted items to canonical shape (id dropped)", () => {
+      const ctx = fakeCtx([
+        toolResultEntry({
+          todos: [{ id: 1, title: "Old", status: "not-started" }],
+        }),
+      ]);
+      manager.loadFromSession(ctx as never);
+      expect(manager.read()).toEqual([{ content: "Old", status: "pending" }]);
+    });
+
+    it("keeps current canonical items verbatim", () => {
+      const ctx = fakeCtx([
+        toolResultEntry({
+          todos: [
+            { content: "A", status: "in_progress" },
+            { content: "B", status: "completed", description: "d" },
+          ],
+        }),
+      ]);
+      manager.loadFromSession(ctx as never);
+      expect(manager.read()).toEqual([
+        { content: "A", status: "in_progress" },
+        { content: "B", status: "completed", description: "d" },
+      ]);
+    });
+
+    it("ignores other tools and non-message entries", () => {
+      const ctx = fakeCtx([
+        { type: "message", message: { role: "toolResult", toolName: "run_read", details: { todos: [] } } },
+        toolResultEntry({ todos: [{ content: "X", status: "pending" }] }),
+      ]);
+      manager.loadFromSession(ctx as never);
+      expect(manager.read()).toEqual([{ content: "X", status: "pending" }]);
+    });
+
+    it("ignores unrecoverable persisted entries (leaves earlier state)", () => {
+      const ctx = fakeCtx([
+        toolResultEntry({ todos: [{ content: "Good", status: "pending" }] }),
+        toolResultEntry({ todos: "a bare string" }),
+      ]);
+      manager.loadFromSession(ctx as never);
+      expect(manager.read()).toEqual([{ content: "Good", status: "pending" }]);
+    });
+  });
 });

package/src/state-manager.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { normalizeTodoItems } from "./prepare-args.js";
 import type { TodoItem, TodoStats, ValidationResult } from "./types.js";
 
 /** Manages the in-memory todo list state. */
@@ -27,9 +28,9 @@ export class TodoStateManager {
   getStats(): TodoStats {
     const total = this.todos.length;
     const completed = this.todos.filter((t) => t.status === "completed").length;
-    const inProgress = this.todos.filter((t) => t.status === "in-progress").length;
-    const notStarted = this.todos.filter((t) => t.status === "not-started").length;
-    return { total, completed, inProgress, notStarted };
+    const inProgress = this.todos.filter((t) => t.status === "in_progress").length;
+    const pending = this.todos.filter((t) => t.status === "pending").length;
+    return { total, completed, inProgress, pending };
   }
 
   validate(todos: TodoItem[]): ValidationResult {
@@ -37,7 +38,7 @@ export class TodoStateManager {
     if (!Array.isArray(todos)) {
       return { valid: false, errors: ["todoList must be an array"] };
     }
-    const validStatuses = new Set(["not-started", "in-progress", "completed"]);
+    const validStatuses = new Set(["pending", "in_progress", "completed"]);
     for (let i = 0; i < todos.length; i++) {
       const item = todos[i];
       const prefix = `Item ${i + 1}`;
@@ -45,19 +46,14 @@ export class TodoStateManager {
         errors.push(`${prefix}: undefined item`);
         continue;
       }
-      if (item.id == null) {
-        errors.push(`${prefix}: missing 'id'`);
-      } else if (typeof item.id !== "number") {
-        errors.push(`${prefix}: 'id' must be a number`);
+      if (typeof item.content !== "string" || item.content.trim() === "") {
+        errors.push(`${prefix}: missing or invalid 'content'`);
       }
-      if (!item.title || typeof item.title !== "string") {
-        errors.push(`${prefix}: missing or invalid 'title'`);
+      if (typeof item.status !== "string" || !validStatuses.has(item.status)) {
+        errors.push(`${prefix}: 'status' must be one of: pending, in_progress, completed`);
       }
-      if (!item.description || typeof item.description !== "string") {
-        errors.push(`${prefix}: missing or invalid 'description'`);
-      }
-      if (!item.status || !validStatuses.has(item.status)) {
-        errors.push(`${prefix}: 'status' must be one of: not-started, in-progress, completed`);
+      if (item.description !== undefined && typeof item.description !== "string") {
+        errors.push(`${prefix}: 'description' must be a string`);
       }
     }
     return { valid: errors.length === 0, errors };
@@ -69,9 +65,14 @@ export class TodoStateManager {
       if (entry.type !== "message") continue;
       const msg = entry.message;
       if (msg.role !== "toolResult" || msg.toolName !== "manage_todo_list") continue;
-      const details = msg.details as { todos?: TodoItem[] } | undefined;
-      if (details?.todos) {
-        this.todos = details.todos.map((t) => ({ ...t }));
+      const details = msg.details as { todos?: unknown } | undefined;
+      // Legacy persisted items (id / title / dashed or synonym
+      // statuses) and newer canonical items both go through the same
+      // normalizer. Unrecoverable entries
+      // leave state untouched for that entry.
+      const items = normalizeTodoItems(details?.todos);
+      if (items) {
+        this.todos = items.map((t) => ({ ...t }));
       }
     }
   }