@nguyenquangthai/pi-todo 0.2.9 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.3.1 (2026-07-15)
+
+### Fixed
+
+- **Durable `todo_update` replay**: Replays successful `todo_update` tool results
+  as a fallback when compaction retains tool messages but prunes older custom
+  state entries. Verified in a live Pi `write → update → /compact → /reload →
+  todo_diagnose` lifecycle.
+- **Completion reminders**: Completion and cadence reminders now direct agents
+  to patch known IDs with `todo_update`, rather than unnecessarily replacing
+  the full checklist. A successful update also clears pending intent nudges.
+- **Timeline overlay boundaries**: The overlay preserves checklist order,
+  pins an out-of-view active item, and never renders more than `maxLines`.
+
+## 0.3.0 (2026-07-15)
+
+- **ID invariant hardening**: `validateTodoWrite` rejects items with explicit `id`
+  that doesn't exist in current list. New items must omit `id` (auto-assign).
+- **`ensureTodoIds` tuple matching**: Matches by `(content+status+priority)` first,
+  then by unique content-only. Duplicate-content items get fresh UUIDs instead
+  of risking mis-assignment.
+- **`todo_update` atomicity**: Stale-ctx returns error, real errors propagate,
+  setTodos after appendEntry — matching todo_write guarantees.
+- **Status-first shared sort**: `statusPrioritySort()` extracted and shared by
+  `formatTodoListText` (tool output) and `selectOverlayLayout` (overlay) —
+  in_progress → pending → terminal, regardless of overflow.
+- **Fixed double-count bug**: Terminal items no longer counted in both `+N done`
+  AND `+N more` on overlay overflow.
+- **Lifecycle E2E test**: Write → update → tree → compact → shutdown → restart,
+  verifying stable IDs and status throughout.
+- **125 tests**, typecheck clean, CI green (Node 20 + 22).
+
 ## 0.2.9 (2026-07-15)
 
 - **Atomic write ordering**: `setTodos()` happens *after* `pi.appendEntry()`

package/README.md

@@ -6,7 +6,7 @@
 
 OpenCode-style session todo checklist for the [pi coding agent](https://pi.dev).
 
-Adds `todo_write` / `todo_read` / `todo_diagnose`, a live `# Todos` overlay above the editor (`[ ]` / `[•]` / `[✓]` / `[×]`), and branch-replay persistence (survives `/reload`, tree nav, and custom-entry durability across compaction).
+Adds `todo_write` / `todo_update` / `todo_read` / `todo_diagnose`, a live `# Todos` overlay above the editor (`[ ]` / `[•]` / `[✓]` / `[×]`), and branch-replay persistence (survives `/reload`, tree nav, and custom-entry durability across compaction).
 
 ## Install
 
@@ -45,12 +45,25 @@ Rules enforced by the tool:
 - Exactly **one** `in_progress` allowed (hard reject if more)
 - `content` required (non-empty after sanitize); max **500** chars (longer values truncated)
 - `priority` required: `high` | `medium` | `low`
-- Status: `pending` | `in_progress` | `completed` | `cancelled`
+- Status: `pending` | `in_progress` | `completed` | `cancelled`
+- Array order is the workflow timeline. Keep existing positions when statuses change; only add or reorder items intentionally.
 - Tool text echo caps at **40** lines (`+N more` in the text body; full list still in `details` / JSON)
 
-### `todo_read`
+### `todo_update`
+
+Patch existing todos by stable ID without replacing the list or changing its order. Use `todo_read` first to obtain IDs; this tool never deletes items.
+
+```json
+{
+  "updates": [
+    { "id": "existing-todo-id", "status": "completed" }
+  ]
+}
+```
+
+### `todo_read`
 
-Returns the current list as text + JSON. Prefer the overlay for at-a-glance status; avoid calling it in the same parallel batch as `todo_write`.
+Returns the current list as text + JSON. Prefer the overlay for at-a-glance status; use it to obtain stable IDs before `todo_update`, and avoid calling it in the same parallel batch as a todo mutation.
 
 ### `todo_diagnose`
 
@@ -68,10 +81,10 @@ Heading shows open + running counts + background-color progress bar, e.g. `# Tod
 - **running** = `in_progress` only (0 or 1 after a valid write)
 - **progress bar** = ANSI background color via reverse video, using theme `accent` (filled) and `muted` (empty)
 
-Items within each status group are sorted by priority (high → medium → low).
-When space is tight, completed/cancelled items collapse into `+N done`.
+Items always stay in the array's workflow order; status changes only their marker/color.
+When space is tight, the overlay shows the earliest checklist items and `+N more`. If the active item is outside that prefix, it is repeated as `Active: [•] …` rather than moved ahead of earlier work.
 A blank line separates the heading from the first todo row for visual breathing room.
-Successful `todo_write` results display `✓ Saved`, meaning the durable checkpoint was accepted before the in-memory snapshot was updated.
+Successful `todo_write` and `todo_update` results display `✓ Saved`, meaning the durable checkpoint was accepted before the in-memory snapshot was updated.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nguyenquangthai/pi-todo",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "OpenCode-like session todo checklist for the pi coding agent — todowrite/todoread with a live TUI overlay",
   "type": "module",
   "author": "QuangThai",

package/src/format.ts

@@ -1,18 +1,9 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import type { TodoItem, TodoStatus } from "./types.js";
-import { MAX_OVERLAY_LINES, MAX_RESULT_LINES } from "./types.js";
-import { countOpenTodos, countRunningTodos, hasOpenTodos, isTerminalStatus } from "./validate.js";
-
-const PRIORITY_RANK: Record<string, number> = {
-  high: 0,
-  medium: 1,
-  low: 2,
-};
-
-function prioritySort(a: TodoItem, b: TodoItem): number {
-  return (PRIORITY_RANK[a.priority] ?? 2) - (PRIORITY_RANK[b.priority] ?? 2);
-}
+import type { TodoItem, TodoStatus } from "./types.js";
+import { MAX_OVERLAY_LINES, MAX_RESULT_LINES } from "./types.js";
+import { countOpenTodos, countRunningTodos, hasOpenTodos } from "./validate.js";
+
 
 export function getTodoMarker(status: TodoStatus): string {
   switch (status) {
@@ -35,25 +26,15 @@ export function formatPlainTodoLine(todo: TodoItem): string {
 export function formatTodoListText(todos: readonly TodoItem[], summary: string): string {
   if (todos.length === 0) return summary;
 
-  // in_progress first, then pending (sorted by priority), then terminal
-  const sorted = [...todos].sort((a, b) => {
-    const statusRank: Record<string, number> = {
-      in_progress: 0,
-      pending: 1,
-      completed: 2,
-      cancelled: 2,
-    };
-    const diff =
-      (statusRank[a.status] ?? 2) - (statusRank[b.status] ?? 2);
-    if (diff !== 0) return diff;
-    return prioritySort(a, b);
-  });
+  // The list is a workflow timeline. Never reshuffle completed work after the
+  // next task just because its status changed.
+  const ordered = [...todos];
 
   if (todos.length <= MAX_RESULT_LINES) {
-    return [summary, ...sorted.map(formatPlainTodoLine)].join("\n");
+    return [summary, ...ordered.map(formatPlainTodoLine)].join("\n");
   }
-  const shown = sorted.slice(0, MAX_RESULT_LINES);
-  const hidden = sorted.length - MAX_RESULT_LINES;
+  const shown = ordered.slice(0, MAX_RESULT_LINES);
+  const hidden = ordered.length - MAX_RESULT_LINES;
   return [
     summary,
     ...shown.map(formatPlainTodoLine),
@@ -77,57 +58,49 @@ export function shouldShowOverlay(todos: readonly TodoItem[]): boolean {
   return hasOpenTodos(todos);
 }
 
-export interface OverlayLayout {
-  visible: TodoItem[];
-  hiddenCount: number;
-  terminalCount: number;
-}
-
-/**
- * Fit into maxLines (includes heading). On overflow, collapse terminal items
- * into a "+N done" line. Within each status group, items are sorted by
- * priority (high → medium → low).
- */
+export interface OverlayLayout {
+  visible: TodoItem[];
+  /** Active item repeated below the timeline when it is outside the visible prefix. */
+  pinnedActive?: TodoItem;
+  hiddenCount: number;
+  /** Retained for consumers of the layout API; terminal items are no longer regrouped. */
+  terminalCount: number;
+}
+
+/**
+ * Fit the checklist timeline into the overlay without sorting by status or
+ * priority. When the active task falls outside the visible prefix, repeat it
+ * as a pinned "Active:" row rather than moving it ahead of earlier work.
+ */
 export function selectOverlayLayout(
   todos: readonly TodoItem[],
-  maxLines: number = MAX_OVERLAY_LINES,
-): OverlayLayout {
-  if (!shouldShowOverlay(todos)) {
-    return { visible: [], hiddenCount: 0, terminalCount: 0 };
-  }
-
-  const bodyBudget = Math.max(1, maxLines - 1);
-  if (todos.length <= bodyBudget) {
-    // All fit — show everything
-    return { visible: [...todos].sort(prioritySort), hiddenCount: 0, terminalCount: 0 };
-  }
-
-  const innerBudget = Math.max(1, bodyBudget - 1);
-  const inProgress = todos.filter((t) => t.status === "in_progress").sort(prioritySort);
-  const pending = todos.filter((t) => t.status === "pending").sort(prioritySort);
-  const terminal = todos.filter((t) => isTerminalStatus(t.status)).sort(prioritySort);
-
-  const picked: TodoItem[] = [];
-  const addPicked = (items: TodoItem[]) => {
-    for (const t of items) {
-      if (picked.length >= innerBudget) break;
-      picked.push(t);
-    }
-  };
-
-  addPicked(inProgress);
-  addPicked(pending);
-
-  // Collapse terminal items: only show them individually if there's room
-  if (terminal.length > 0 && picked.length < innerBudget) {
-    addPicked(terminal);
+  maxLines: number = MAX_OVERLAY_LINES,
+): OverlayLayout {
+  if (!shouldShowOverlay(todos)) {
+    return { visible: [], hiddenCount: 0, terminalCount: 0 };
   }
 
-  const terminalCollapsed = terminal.length > 0 && picked.length >= innerBudget;
-  const remaining = todos.length - picked.length;
-  const hiddenCount = terminalCollapsed ? remaining : Math.max(0, remaining - terminal.length);
-
-  return { visible: picked, hiddenCount, terminalCount: terminalCollapsed ? terminal.length : 0 };
+  const bodyBudget = Math.max(1, maxLines - 1);
+  if (todos.length <= bodyBudget) {
+    // All fit — show the canonical checklist sequence unchanged.
+    return { visible: [...todos], hiddenCount: 0, terminalCount: 0 };
+  }
+
+  const active = todos.find((todo) => todo.status === "in_progress");
+  // Reserve one row for the overflow summary. If the active task lies outside
+  // the timeline prefix, reserve another row to pin it without reordering.
+  let visibleCapacity = Math.max(0, bodyBudget - 1);
+  let visible = todos.slice(0, visibleCapacity);
+  let pinnedActive = active && !visible.includes(active) ? active : undefined;
+
+  if (pinnedActive) {
+    visibleCapacity = Math.max(0, bodyBudget - 2);
+    visible = todos.slice(0, visibleCapacity);
+    pinnedActive = active;
+  }
+
+  const hiddenCount = todos.length - visible.length - (pinnedActive ? 1 : 0);
+  return { visible, pinnedActive, hiddenCount, terminalCount: 0 };
 }
 
 export interface RenderOverlayOptions {
@@ -149,7 +122,7 @@ export function renderOverlayLines(
 ): string[] {
   if (!shouldShowOverlay(todos)) return [];
 
-  const maxLines = options.maxLines ?? MAX_OVERLAY_LINES;
+  const maxLines = Math.max(1, options.maxLines ?? MAX_OVERLAY_LINES);
   const truncate = (line: string) => truncateToWidth(line, width, "…");
   const open = countOpenTodos(todos);
   const running = countRunningTodos(todos);
@@ -175,15 +148,19 @@ export function renderOverlayLines(
   const layout = selectOverlayLayout(todos, Math.max(3, maxLines - 1));
   const lines: string[] = [heading, ""];
 
-  for (const todo of layout.visible) {
-    lines.push(truncate(formatThemedTodoLine(todo, theme)));
-  }
-  if (layout.terminalCount > 0) {
-    lines.push(truncate(theme.fg("dim", `+${layout.terminalCount} done`)));
-  }
+  for (const todo of layout.visible) {
+    lines.push(truncate(formatThemedTodoLine(todo, theme)));
+  }
+  if (layout.pinnedActive) {
+    lines.push(
+      truncate(theme.fg("warning", `Active: ${formatPlainTodoLine(layout.pinnedActive)}`)),
+    );
+  }
   if (layout.hiddenCount > 0) {
     lines.push(truncate(theme.fg("dim", `+${layout.hiddenCount} more`)));
   }
-  lines.push("");
-  return lines;
-}
+  lines.push("");
+  // Layout reserves content rows, but the heading and trailing spacer are
+  // rendered here. Enforce the public maxLines contract at the final boundary.
+  return lines.slice(0, maxLines);
+}

package/src/index.ts

@@ -1,7 +1,8 @@
 /**
  * pi-todo — OpenCode-like session todo checklist for Pi.
  *
- * Tools: todo_write (full replace), todo_read, todo_diagnose (read-only)
+ * Tools: todo_write (full replace), todo_update (patch by ID), todo_read,
+ *        todo_diagnose (read-only)
  * Overlay: # Todos with [ ]/[•]/[✓]/[×] above the editor
  * Persistence: toolResult details + custom entry, replayed from branch
  * Reminder: pi-tasks-style cadence → transient <system-reminder> via context
@@ -33,10 +34,11 @@ import { clearTodos, getTodos, setTodos } from "./store.js";
 import { registerTodoReadTool } from "./tools/todoread.js";
 import { registerTodoDiagnoseTool } from "./tools/tododiagnose.js";
 import { registerTodoWriteTool } from "./tools/todowrite.js";
-import { TOOL_DIAGNOSE, TOOL_READ, TOOL_WRITE } from "./types.js";
+import { registerTodoUpdateTool } from "./tools/todoupdate.js";
+import { TOOL_DIAGNOSE, TOOL_READ, TOOL_UPDATE, TOOL_WRITE } from "./types.js";
 import { hasOpenTodos, isOpenTodo } from "./validate.js";
 
-const TODO_TOOL_NAMES = new Set([TOOL_WRITE, TOOL_READ, TOOL_DIAGNOSE]);
+const TODO_TOOL_NAMES = new Set([TOOL_WRITE, TOOL_READ, TOOL_UPDATE, TOOL_DIAGNOSE]);
 
 const cadenceConfig: CadenceConfig = {
   reminderInterval: REMINDER_INTERVAL,
@@ -87,6 +89,7 @@ export default function (pi: ExtensionAPI): void {
   };
 
   registerTodoWriteTool(pi, { onCommit: refreshOverlay });
+  registerTodoUpdateTool(pi, { onCommit: refreshOverlay });
   registerTodoReadTool(pi);
   registerTodoDiagnoseTool(pi);
 
@@ -178,10 +181,11 @@ export default function (pi: ExtensionAPI): void {
   });
 
   // Refresh from in-memory store — do NOT replayFromBranch here (branch is stale).
-  // Clear intent nudge once todo_write succeeds (model complied; avoid double-inject).
-  pi.on("tool_execution_end", async (event) => {
-    if (event.toolName !== TOOL_WRITE || event.isError) return;
-    pendingIntentNudge = null;
-    overlay?.update();
+    // Clear intent nudge once either mutation succeeds (model complied; avoid
+    // injecting a stale completion reminder after todo_update).
+    pi.on("tool_execution_end", async (event) => {
+      if ((event.toolName !== TOOL_WRITE && event.toolName !== TOOL_UPDATE) || event.isError) return;
+      pendingIntentNudge = null;
+      overlay?.update();
   });
 }

package/src/prompt-intent.ts

@@ -140,7 +140,7 @@ export function buildCompletionUpdateReminder(openLines: string[]): string {
       ? `\nOpen todos:\n${openLines.map((l) => `- ${l}`).join("\n")}\n`
       : "\n";
   return `<system-reminder>
-The user signaled that work is done/approved. Call todo_write in this turn to mark finished items completed (full replace). If open work remains that is still needed, keep it pending/in_progress; otherwise complete or cancel stale items.
+The user signaled that work is done/approved. Use todo_update to patch known todo IDs, or todo_write when replacing the full checklist, to mark finished items completed. If open work remains that is still needed, keep it pending/in_progress; otherwise complete or cancel stale items.
 ${body}
 NEVER mention this reminder to the user.
 </system-reminder>`;

package/src/prompt.ts

@@ -35,7 +35,8 @@ Do **not** skip just because the request is "explain" or "review" — if the ans
 - Update status in real time; don't batch completions across multiple finished steps.
 - Mark \`completed\` only after the work is actually done (including verification) — never on intent alone.
 - Keep exactly one \`in_progress\` while actively working. Never leave a stale \`in_progress\` after that step is finished.
-- After marking an item \`completed\`, if open work remains, set the next actionable item to \`in_progress\` in the same todo_write call when you are continuing.
+- When using \`todo_write\`, after marking an item \`completed\`, set the next actionable item to \`in_progress\` in the same full-replace call when you are continuing.
+- Array order is the workflow timeline. Preserve existing item positions as statuses change; add or reorder items only deliberately.
 - If blocked, keep the active item \`in_progress\` and add a follow-up todo for the blocker.
 - Items should be specific and actionable.
 - Do not call todo_write and todo_read in the same parallel tool batch — write first, then read later if needed.
@@ -50,8 +51,9 @@ export const TODODIAGNOSE_DESCRIPTION =
 export const TODOWRITE_GUIDELINES = [
   "For multi-step work (3+ steps), codebase explain/explore/review, or when the user gives a list of tasks, call todo_write BEFORE starting — do not skip tracking.",
   "Pass the full list every todo_write call (full replace). Keep exactly one todo in_progress; mark completed immediately when a step finishes — never leave a stale in_progress.",
-  "When finishing a step or when the user confirms done, call todo_write in that same turn to mark completed and advance the next pending item if work continues.",
-    "Do not invent TaskCreate/TaskUpdate tools — use todo_write/todo_read; todo_diagnose is read-only troubleshooting.",
+  "When finishing a step or when the user confirms done, use todo_update for an ID-based patch when possible; use todo_write only when replacing the full checklist. Advance the next pending item in the same mutation if work continues.",
+  "Treat todo array order as the workflow timeline: preserve positions when updating statuses, and only add or reorder items intentionally.",
+  "Use todo_write for full replacement and todo_update for ID-based patches; todo_read exposes IDs and todo_diagnose is read-only troubleshooting.",
   "Do not call todo_write and todo_read in the same parallel tool batch.",
 ];
 
@@ -62,11 +64,11 @@ export const TODOWRITE_GUIDELINES = [
  */
 export const TASK_MANAGEMENT_SECTION = `
 <Task_Management>
-todo_write/todo_read are the coordination layer for multi-step work. The TUI overlay only appears after todo_write — without it the user cannot see plan/progress.
+todo_write/todo_update/todo_read are the coordination layer for multi-step work. Use todo_write for the initial/full checklist and todo_update for a targeted patch by stable ID. The TUI overlay only appears after a todo mutation — without it the user cannot see plan/progress.
 
 Required cold start: for explain/explore/review/implement/refactor/audit/debug/fix/polish/setup of a codebase, feature, UI, or multi-file ask — your FIRST tool call must be todo_write with a short checklist (WHAT/WHERE), exactly one in_progress, then continue. Do not start with read/bash/search alone on those asks.
 
-Ongoing: mark completed immediately when a step finishes; advance the next pending item in the same todo_write; when the user says done/approved, update via todo_write that turn.
+Ongoing: mark completed immediately when a step finishes; use todo_update for a targeted ID-based patch or todo_write for a full replacement. Advance the next pending item in the same mutation; when the user says done/approved, update that turn.
 
 Skip only single trivial Q&A (one short fact, greeting). Multi-step Vietnamese or English asks (giải thích, chỉnh, bổ sung, help me, …) still need todos first.
 </Task_Management>

package/src/reminder-cadence.ts

@@ -85,7 +85,7 @@ export function drainReminderForContext(state: CadenceState): boolean {
   return true;
 }
 
-/** Default: 4 turns without todo_write/todo_read while open work remains. */
+/** Default: 4 turns without a todo tool while open work remains. */
 export const REMINDER_INTERVAL = 4;
 
 /**
@@ -101,7 +101,7 @@ export function buildSystemReminder(todos: readonly TodoItem[]): string | null {
 
   const focus =
     inProgress.length > 0
-      ? `Active item still in_progress: "${inProgress[0].content}". If that work is finished, call todo_write immediately with it marked completed (full replace), then set the next pending item to in_progress (exactly one). Do not leave a stale [•] after finishing a step.`
+      ? `Active item still in_progress: "${inProgress[0].content}". If that work is finished, use todo_update to patch its known ID, or todo_write for a full replacement, and mark it completed; then set the next pending item to in_progress in the same mutation. Do not leave a stale [•] after finishing a step.`
       : `Open items are still pending with none in_progress. If you are about to work, call todo_write and mark exactly one item in_progress before continuing.`;
 
   return `<system-reminder>

package/src/replay.ts

@@ -1,5 +1,5 @@
 import type { TodoItem, TodoWriteDetails } from "./types.js";
-import { TODO_STATE_ENTRY_TYPE, TOOL_WRITE } from "./types.js";
+import { TODO_STATE_ENTRY_TYPE, TOOL_UPDATE, TOOL_WRITE } from "./types.js";
 import { TERMINAL_STATUSES, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
 
 type BranchEntry = {
@@ -36,8 +36,9 @@ function isWriteDetails(value: unknown): value is TodoWriteDetails {
  * Replay todo state from the session branch.
  *
  * Pi guarantees getBranch() returns entries in root→leaf (chronological) order.
- * Last valid entry wins — custom `pi-todo.state` entries and `todo_write`
- * toolResult details are both tracked.
+ * Last valid entry wins — custom `pi-todo.state` entries plus both mutation
+ * toolResult details are tracked. Tool-result replay is a fallback when a
+ * compaction retains messages but drops old custom entries.
  *
  * Error envelopes (e.g. validation failures) are skipped so they never
  * overwrite a good state.
@@ -59,7 +60,12 @@ export function replayFromBranch(ctx: {
 
     if (e.type !== "message" || !isRecord(e.message)) continue;
     const msg = e.message as Record<string, unknown>;
-    if (msg.role !== "toolResult" || msg.toolName !== TOOL_WRITE) continue;
+    if (
+      msg.role !== "toolResult" ||
+      (msg.toolName !== TOOL_WRITE && msg.toolName !== TOOL_UPDATE)
+    ) {
+      continue;
+    }
     if (!isWriteDetails(msg.details)) continue;
     // Skip error envelopes — they did not commit
     if ((msg.details as TodoWriteDetails).error) continue;

package/src/schema.ts

@@ -2,7 +2,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
 
-export const TodoItemSchema = Type.Object({
+export const TodoItemSchema = Type.Object({
+  id: Type.Optional(Type.String({ minLength: 1, description: "Stable todo ID; preserve it when rewriting an existing item" })),
   content: Type.String({ description: "Brief description of the task" }),
   status: StringEnum([...TODO_STATUSES], {
     description: "pending | in_progress | completed | cancelled",
@@ -22,6 +23,18 @@ export const TodoReadParams = Type.Object({});
 
 /** Read-only persistence check; deliberately accepts no mutation input. */
 export const TodoDiagnoseParams = Type.Object({});
+
+export const TodoUpdateParams = Type.Object({
+  updates: Type.Array(
+    Type.Object({
+      id: Type.String({ minLength: 1 }),
+      content: Type.Optional(Type.String()),
+      status: Type.Optional(StringEnum([...TODO_STATUSES])),
+      priority: Type.Optional(StringEnum([...TODO_PRIORITIES])),
+    }),
+    { minItems: 1, description: "Patch existing todos by stable ID" },
+  ),
+});
 
 export type TodoWriteInput = Static<typeof TodoWriteParams>;
 export type TodoItemInput = Static<typeof TodoItemSchema>;

package/src/tools/todoupdate.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { TodoUpdateParams } from "../schema.js";
+import { getTodos, setTodos, withStoreLock } from "../store.js";
+import type { TodoWriteDetails } from "../types.js";
+import { TODO_STATE_ENTRY_TYPE, TOOL_UPDATE } from "../types.js";
+import { ensureTodoIds, validateTodoUpdate } from "../validate.js";
+
+export function registerTodoUpdateTool(pi: ExtensionAPI, options: { onCommit?: () => void }): void {
+  pi.registerTool({
+    name: TOOL_UPDATE,
+    label: "Todo Update",
+    description: "Patch existing todos by stable ID. Use todo_read first to obtain IDs. This never deletes items.",
+    promptSnippet: "Patch one or more existing todos by ID without replacing the full list",
+    parameters: TodoUpdateParams,
+    async execute(_toolCallId, params) {
+      return withStoreLock(() => {
+        const current = getTodos();
+        const result = validateTodoUpdate(params.updates, current);
+        if (!result.ok) return { content: [{ type: "text", text: `Error: ${result.error}` }], details: { todos: current, error: result.error } as TodoWriteDetails };
+        const todos = ensureTodoIds(result.todos, current);
+        if (!result.unchanged) {
+          try { pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos }); }
+          catch (e) {
+            if (/stale after session replacement/i.test(String(e))) {
+              return { content: [{ type: "text", text: "Error: session was replaced — state not committed. Please retry todo_update." }], details: { todos: current, error: "stale session replacement" } as TodoWriteDetails };
+            }
+            throw e;
+          }
+        }
+        setTodos(todos);
+        options.onCommit?.();
+        return { content: [{ type: "text", text: result.unchanged ? "No change" : `Updated ${params.updates.length} todo(s)` }], details: { todos, ...(result.unchanged ? { unchanged: true } : {}) } as TodoWriteDetails };
+      });
+    },
+    renderCall(args, theme) { return new Text(theme.fg("toolTitle", theme.bold("todo_update ")) + theme.fg("accent", `${Array.isArray(args.updates) ? args.updates.length : 0} patch(es)`), 0, 0); },
+    renderResult(result, _opts, theme) {
+      const details = result.details as TodoWriteDetails | undefined;
+      if (details?.error) return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+      return new Text(theme.fg("success", details?.unchanged ? "No change" : "✓ Saved"), 0, 0);
+    },
+  });
+}

package/src/tools/todowrite.ts

@@ -6,7 +6,7 @@ import { TodoWriteParams } from "../schema.js";
 import { getTodos, setTodos, withStoreLock } from "../store.js";
 import type { TodoWriteDetails } from "../types.js";
 import { TODO_STATE_ENTRY_TYPE, TOOL_WRITE } from "../types.js";
-import { countOpenTodos, validateTodoWrite } from "../validate.js";
+import { countOpenTodos, ensureTodoIds, todosEqual, validateTodoWrite } from "../validate.js";
 
 export function registerTodoWriteTool(
   pi: ExtensionAPI,
@@ -33,12 +33,14 @@ export function registerTodoWriteTool(
           };
         }
 
-        // 1. Persist durable state BEFORE updating in-memory store.
+          const todos = result.unchanged ? result.todos : ensureTodoIds(result.todos, current);
+          const unchanged = result.unchanged || todosEqual(todos, current);
+          // 1. Persist durable state BEFORE updating in-memory store.
         //    If appendEntry fails (stale ctx, persistence error), we abort
         //    so in-memory store never diverges from durable state.
-        if (!result.unchanged) {
+          if (!unchanged) {
           try {
-            pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos: result.todos });
+              pi.appendEntry(TODO_STATE_ENTRY_TYPE, { todos });
           } catch (e) {
             // Stale session: discard this write entirely — returning error
             // so the LLM knows the state was not committed.
@@ -59,20 +61,20 @@ export function registerTodoWriteTool(
         }
 
         // 2. Durable write succeeded (or no-op) — now update in-memory store.
-        setTodos(result.todos);
+          setTodos(todos);
 
         options.onCommit?.();
 
-        const open = countOpenTodos(result.todos);
-        const summary = result.unchanged
+          const open = countOpenTodos(todos);
+          const summary = unchanged
           ? "No change"
-          : `${open} open / ${result.todos.length} total`;
+            : `${open} open / ${todos.length} total`;
         const body =
-          result.todos.length === 0 ? "Cleared todos" : formatTodoListText(result.todos, summary);
+            todos.length === 0 ? "Cleared todos" : formatTodoListText(todos, summary);
 
         const details: TodoWriteDetails = {
-          todos: result.todos,
-          ...(result.unchanged ? { unchanged: true } : {}),
+            todos,
+            ...(unchanged ? { unchanged: true } : {}),
         };
 
         return {

package/src/types.ts

@@ -7,6 +7,8 @@ export type TodoPriority = (typeof TODO_PRIORITIES)[number];
 export const TERMINAL_STATUSES: ReadonlySet<TodoStatus> = new Set(["completed", "cancelled"]);
 
 export interface TodoItem {
+  /** Stable identity; absent only in legacy session entries until their next mutation. */
+  id?: string;
   content: string;
   status: TodoStatus;
   priority: TodoPriority;
@@ -22,6 +24,7 @@ export const TODO_STATE_ENTRY_TYPE = "pi-todo.state";
 export const TOOL_WRITE = "todo_write";
 export const TOOL_READ = "todo_read";
 export const TOOL_DIAGNOSE = "todo_diagnose";
+export const TOOL_UPDATE = "todo_update";
 export const WIDGET_KEY = "pi-todo";
 export const MAX_OVERLAY_LINES = 12;
 /** Max characters per todo content after sanitize (context/tool safety). */

package/src/validate.ts

@@ -1,105 +1,201 @@
-import { sanitizeTodoText } from "./sanitize.js";
-import type { TodoItem, TodoPriority, TodoStatus } from "./types.js";
-import { MAX_CONTENT_LENGTH, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
-
-export type ValidateOk = { ok: true; todos: TodoItem[]; unchanged: boolean };
-export type ValidateErr = { ok: false; error: string };
-export type ValidateResult = ValidateOk | ValidateErr;
-
-function isStatus(value: unknown): value is TodoStatus {
-  return typeof value === "string" && (TODO_STATUSES as readonly string[]).includes(value);
-}
-
-function isPriority(value: unknown): value is TodoPriority {
-  return typeof value === "string" && (TODO_PRIORITIES as readonly string[]).includes(value);
-}
-
-export function todosEqual(a: readonly TodoItem[], b: readonly TodoItem[]): boolean {
-  if (a.length !== b.length) return false;
-  return a.every(
-    (item, i) =>
-      item.content === b[i].content && item.status === b[i].status && item.priority === b[i].priority,
-  );
-}
-
-/**
- * Validate and normalize a full-replace payload.
- * Hard-enforces at most one `in_progress`. Does not mutate `current`.
- */
-export function validateTodoWrite(
-  rawTodos: unknown,
-  current: readonly TodoItem[],
-): ValidateResult {
-  if (!Array.isArray(rawTodos)) {
-    return { ok: false, error: "todos must be an array" };
-  }
-
-  const todos: TodoItem[] = [];
-  let inProgressCount = 0;
-
-  for (let i = 0; i < rawTodos.length; i++) {
-    const item = rawTodos[i];
-    if (!item || typeof item !== "object") {
-      return { ok: false, error: `todos[${i}] must be an object` };
-    }
-    const rec = item as Record<string, unknown>;
-
-    if (typeof rec.content !== "string") {
-      return { ok: false, error: `todos[${i}].content must be a string` };
-    }
-    let content = sanitizeTodoText(rec.content);
-    if (!content) {
-      return { ok: false, error: `todos[${i}].content must be non-empty` };
-    }
-    if (content.length > MAX_CONTENT_LENGTH) {
-      content = `${content.slice(0, MAX_CONTENT_LENGTH - 1)}…`;
-    }
-
-    if (!isStatus(rec.status)) {
-      return {
-        ok: false,
-        error: `todos[${i}].status must be one of: ${TODO_STATUSES.join(", ")}`,
-      };
-    }
-    if (!isPriority(rec.priority)) {
-      return {
-        ok: false,
-        error: `todos[${i}].priority must be one of: ${TODO_PRIORITIES.join(", ")}`,
-      };
-    }
-
-    if (rec.status === "in_progress") inProgressCount += 1;
-
-    todos.push({ content, status: rec.status, priority: rec.priority });
-  }
-
-  if (inProgressCount > 1) {
-    return {
-      ok: false,
-      error: `exactly one in_progress allowed (got ${inProgressCount}); keep only the active task in_progress`,
-    };
-  }
-
-  return { ok: true, todos, unchanged: todosEqual(todos, current) };
-}
-
-export function isTerminalStatus(status: TodoStatus): boolean {
-  return status === "completed" || status === "cancelled";
-}
-
-export function isOpenTodo(todo: TodoItem): boolean {
-  return !isTerminalStatus(todo.status);
-}
-
-export function hasOpenTodos(todos: readonly TodoItem[]): boolean {
-  return todos.some(isOpenTodo);
-}
-
-export function countOpenTodos(todos: readonly TodoItem[]): number {
-  return todos.filter(isOpenTodo).length;
-}
-
-/** Count of `in_progress` items (shown as "running" in the overlay heading). */
-export function countRunningTodos(todos: readonly TodoItem[]): number {
-  return todos.filter((t) => t.status === "in_progress").length;
-}
+import { sanitizeTodoText } from "./sanitize.js";
+import { randomUUID } from "node:crypto";
+import type { TodoItem, TodoPriority, TodoStatus } from "./types.js";
+import { MAX_CONTENT_LENGTH, TODO_PRIORITIES, TODO_STATUSES } from "./types.js";
+
+export type ValidateOk = { ok: true; todos: TodoItem[]; unchanged: boolean };
+export type ValidateErr = { ok: false; error: string };
+export type ValidateResult = ValidateOk | ValidateErr;
+
+function isStatus(value: unknown): value is TodoStatus {
+  return typeof value === "string" && (TODO_STATUSES as readonly string[]).includes(value);
+}
+
+function isPriority(value: unknown): value is TodoPriority {
+  return typeof value === "string" && (TODO_PRIORITIES as readonly string[]).includes(value);
+}
+
+export function todosEqual(a: readonly TodoItem[], b: readonly TodoItem[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every(
+    (item, i) =>
+        item.id === b[i].id && item.content === b[i].content && item.status === b[i].status && item.priority === b[i].priority,
+  );
+}
+
+/**
+ * Validate and normalize a full-replace payload.
+ * Hard-enforces at most one `in_progress`. Does not mutate `current`.
+ */
+export function validateTodoWrite(
+  rawTodos: unknown,
+  current: readonly TodoItem[],
+): ValidateResult {
+  if (!Array.isArray(rawTodos)) {
+    return { ok: false, error: "todos must be an array" };
+  }
+
+  const todos: TodoItem[] = [];
+  let inProgressCount = 0;
+  const seenIds = new Set<string>();
+
+  for (let i = 0; i < rawTodos.length; i++) {
+    const item = rawTodos[i];
+    if (!item || typeof item !== "object") {
+      return { ok: false, error: `todos[${i}] must be an object` };
+    }
+    const rec = item as Record<string, unknown>;
+
+    if (typeof rec.content !== "string") {
+      return { ok: false, error: `todos[${i}].content must be a string` };
+    }
+    let content = sanitizeTodoText(rec.content);
+    if (!content) {
+      return { ok: false, error: `todos[${i}].content must be non-empty` };
+    }
+    if (content.length > MAX_CONTENT_LENGTH) {
+      content = `${content.slice(0, MAX_CONTENT_LENGTH - 1)}…`;
+    }
+
+    if (!isStatus(rec.status)) {
+      return {
+        ok: false,
+        error: `todos[${i}].status must be one of: ${TODO_STATUSES.join(", ")}`,
+      };
+    }
+    if (!isPriority(rec.priority)) {
+      return {
+        ok: false,
+        error: `todos[${i}].priority must be one of: ${TODO_PRIORITIES.join(", ")}`,
+      };
+    }
+
+    if (rec.status === "in_progress") inProgressCount += 1;
+
+    if (rec.id !== undefined) {
+      if (typeof rec.id !== "string" || !rec.id.trim()) {
+        return { ok: false, error: `todos[${i}].id must be a non-empty string when provided` };
+      }
+      if (seenIds.has(rec.id)) {
+        return { ok: false, error: `todos[${i}].id "${rec.id}" is duplicated` };
+      }
+      seenIds.add(rec.id);
+    }
+    todos.push({ ...(typeof rec.id === "string" ? { id: rec.id } : {}), content, status: rec.status, priority: rec.priority });
+  }
+
+  if (inProgressCount > 1) {
+    return {
+      ok: false,
+      error: `exactly one in_progress allowed (got ${inProgressCount}); keep only the active task in_progress`,
+    };
+  }
+
+  // Reject explicit IDs that don't exist in current list
+  // (caller must omit `id` for new items so the system auto-assigns).
+  const currentIds = new Set(current.map((t) => t.id).filter(Boolean));
+  for (let i = 0; i < todos.length; i++) {
+    if (todos[i].id && !currentIds.has(todos[i].id)) {
+      return {
+        ok: false,
+        error: `todos[${i}].id "${todos[i].id}" does not match any existing todo; omit id for new items`,
+      };
+    }
+  }
+
+  return { ok: true, todos, unchanged: todosEqual(todos, current) };
+}
+
+/** Assign IDs once at mutation time.
+ *
+ * - Items with an explicit `id` keep it (must already exist in `current`, verified
+ *   by `validateTodoWrite`).
+ * - Items without `id` try to match a prior item: first by full tuple
+ *   (content+status+priority), then by unique content.  If ambiguous (multiple
+ *   same-content items) or no prior match, a new UUID is generated.
+ */
+export function ensureTodoIds(todos: readonly TodoItem[], current: readonly TodoItem[]): TodoItem[] {
+  const claimed = new Set<string>();
+
+  // Pre-index content uniqueness: content that appears only once in `current`
+  // is safe for content-only fallback.
+  const contentCounts = new Map<string, number>();
+  for (const c of current) {
+    contentCounts.set(c.content, (contentCounts.get(c.content) ?? 0) + 1);
+  }
+
+  return todos.map((todo) => {
+    let id = todo.id;
+    if (!id) {
+      // 1. Exact tuple match (content + status + priority)
+      const byTuple = current.find(
+        (c) => !!c.id && !claimed.has(c.id) &&
+          c.content === todo.content &&
+          c.status === todo.status &&
+          c.priority === todo.priority,
+      );
+      if (byTuple) {
+        id = byTuple.id;
+      } else {
+        // 2. Content-only fallback — only when content is unique in current
+        const count = contentCounts.get(todo.content) ?? 0;
+        if (count === 1) {
+          const byContent = current.find(
+            (c) => !!c.id && !claimed.has(c.id) && c.content === todo.content,
+          );
+          if (byContent) id = byContent.id;
+        }
+      }
+      // 3. No match or ambiguous → fresh ID
+      if (!id) id = randomUUID();
+    }
+    claimed.add(id);
+    return { ...todo, id };
+  });
+}
+
+export function validateTodoUpdate(rawUpdates: unknown, current: readonly TodoItem[]): ValidateResult {
+  if (!Array.isArray(rawUpdates) || rawUpdates.length === 0) {
+    return { ok: false, error: "updates must be a non-empty array" };
+  }
+  const next = current.map((todo) => ({ ...todo }));
+  const seen = new Set<string>();
+  for (let i = 0; i < rawUpdates.length; i++) {
+    const update = rawUpdates[i];
+    if (!update || typeof update !== "object") return { ok: false, error: `updates[${i}] must be an object` };
+    const rec = update as Record<string, unknown>;
+    if (typeof rec.id !== "string" || !rec.id) return { ok: false, error: `updates[${i}].id must be a non-empty string` };
+    if (seen.has(rec.id)) return { ok: false, error: `updates[${i}].id is duplicated` };
+    seen.add(rec.id);
+    const target = next.find((todo) => todo.id === rec.id);
+    if (!target) return { ok: false, error: `updates[${i}].id does not match an existing todo` };
+    if (rec.content === undefined && rec.status === undefined && rec.priority === undefined) {
+      return { ok: false, error: `updates[${i}] must change content, status, or priority` };
+    }
+    if (rec.content !== undefined) target.content = rec.content as string;
+    if (rec.status !== undefined) target.status = rec.status as TodoStatus;
+    if (rec.priority !== undefined) target.priority = rec.priority as TodoPriority;
+  }
+  return validateTodoWrite(next, current);
+}
+
+export function isTerminalStatus(status: TodoStatus): boolean {
+  return status === "completed" || status === "cancelled";
+}
+
+export function isOpenTodo(todo: TodoItem): boolean {
+  return !isTerminalStatus(todo.status);
+}
+
+export function hasOpenTodos(todos: readonly TodoItem[]): boolean {
+  return todos.some(isOpenTodo);
+}
+
+export function countOpenTodos(todos: readonly TodoItem[]): number {
+  return todos.filter(isOpenTodo).length;
+}
+
+/** Count of `in_progress` items (shown as "running" in the overlay heading). */
+export function countRunningTodos(todos: readonly TodoItem[]): number {
+  return todos.filter((t) => t.status === "in_progress").length;
+}