@ian-pascoe/pi-todo 0.5.0 → 0.6.1

package/README.md

@@ -2,7 +2,7 @@
 
 `@ian-pascoe/pi-todo` gives Pi agents a minimal, session-native **Todo List** without imposing a planning workflow.
 
-Requires Node `>=22.19.0` and Pi `>=0.99.0`.
+Requires Node `>=22.19.0` and Pi `>=1.1.0`.
 
 ## Install
 
@@ -43,7 +43,7 @@ A Pi `codemode` script receives the result as an object (the tool declares an `o
 
 Task status is `pending`, `active`, or `completed`; `add` defaults to `pending`. Tasks are flat, duplicate titles are allowed, and multiple Tasks may be active. Set `description` to `null` during `update` to remove it.
 
-Each tool group that changes the Todo List is projected from the immutable session state entries as one hidden full **Todo List Snapshot** of the group's final state, at a fixed conversation position after all of the group's sibling results. A tool group is one assistant turn's tool calls, including several `todo` calls inside one `codemode` script, so ten calls in a script add one Todo List Snapshot, not ten. A group that ends in the state it began with adds none. A change made outside a tool group, such as `/todo clear`, still projects its own Todo List Snapshot right away. Each Todo List Snapshot starts with the header `Todo List state from the pi-todo extension (not a user message):` so it does not read like user input. Later requests keep earlier Todo List Snapshots in place. Clearing the list produces an explicit empty Todo List Snapshot. The system prompt and tool description do not change.
+Each tool group that changes the Todo List is projected from the immutable session state entries as one hidden full **Todo List Snapshot** of the group's final state, at a fixed conversation position after all of the group's sibling results. A tool group is one assistant turn's tool calls, including several `todo` calls inside one `codemode` script, so ten calls in a script add one Todo List Snapshot, not ten. A group that ends in the state it began with adds none, and so does a group whose last `todo` result is a successful `list`, batch `add`, or batch `update` whose `details.tasks` equal the complete final Todo List, since the model already saw that list. Partial results, such as a single `update` or a batch `update` of some Tasks, still add one. A `codemode` group never skips, because its result is not a `todo` result. A change made outside a tool group, such as `/todo clear`, still projects its own Todo List Snapshot right away. Each Todo List Snapshot starts with the header `Todo List state from the pi-todo extension (not a user message):` so it does not read like user input. Later requests keep earlier Todo List Snapshots in place. Clearing the list produces an explicit empty Todo List Snapshot. The system prompt and tool description do not change.
 
 After compaction, a fixed baseline immediately after the summary restores the state from before the retained Tail. Retained and newer tool groups follow chronologically. This preserves previously written conversation cache prefixes between checkpoints; it does not guarantee provider cache hits.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-todo",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [
@@ -32,10 +32,13 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.6.0"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.99.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.0",
-    "@earendil-works/pi-tui": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=1.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "engines": {

package/src/pi-todo-extension.ts

@@ -1,6 +1,13 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type Component } from "@earendil-works/pi-tui";
+import { acceptNullForOptionalArguments } from "@ian-pascoe/pi-utils/null-optional-arguments";
+import { noticeText } from "@ian-pascoe/pi-utils/ui";
 import { Type } from "typebox";
 import { projectTodoContext, todoStateFromEntry } from "./todo-context.js";
 import {
@@ -10,14 +17,13 @@ import {
   TODO_ACTIONS,
   TODO_STATUSES,
   TodoToolOutputSchema,
-  todoStatusMarker,
   type TodoActionInput,
   type TodoStateSnapshot,
-  type TodoStatus,
   type TodoTask,
   TodoOperationError,
   type TodoToolDetails,
 } from "./todo-list.js";
+import { renderTodoCall, renderTodoResult, renderTodoWidget } from "./todo-render.js";
 import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 const TODO_STATE_ENTRY_TYPE = "pi-todo-state";
@@ -33,8 +39,6 @@ function assertTodoJournalReadable(context: ExtensionContext): void {
   }
 }
 const TODO_WIDGET_ID = "pi-todo";
-const TODO_WIDGET_STATUS_ORDER: readonly TodoStatus[] = ["active", "pending", "completed"];
-const TODO_COLLAPSED_TASK_LIMIT = 5;
 
 const TodoParameters = Type.Object({
   action: StringEnum(TODO_ACTIONS),
@@ -113,19 +117,6 @@ function restoreTodoState(context: ExtensionContext): TodoStateSnapshot {
   return createEmptyTodoState();
 }
 
-function renderTodoTaskLine(task: TodoTask, theme: Theme): string {
-  const markerColor =
-    task.status === "active" ? "accent" : task.status === "completed" ? "success" : "muted";
-  const title =
-    task.status === "active"
-      ? theme.bold(task.title)
-      : task.status === "completed"
-        ? theme.strikethrough(task.title)
-        : task.title;
-  const titleColor = task.status === "completed" ? "dim" : "text";
-  return `${theme.fg(markerColor, todoStatusMarker(task.status))} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(titleColor, title)}`;
-}
-
 class TodoWidget implements Component {
   constructor(
     private readonly tasks: readonly TodoTask[],
@@ -135,25 +126,7 @@ class TodoWidget implements Component {
   invalidate(): void {}
 
   render(width: number): string[] {
-    const active = this.tasks.filter((task) => task.status === "active").length;
-    const pending = this.tasks.filter((task) => task.status === "pending").length;
-    const completed = this.tasks.length - active - pending;
-    const header =
-      this.theme.fg("toolTitle", this.theme.bold("TODO")) +
-      this.theme.fg("muted", `  ${active} active · ${pending} pending · ${completed} completed`);
-    const orderedTasks = this.tasks.toSorted((left, right) => {
-      const statusDifference =
-        TODO_WIDGET_STATUS_ORDER.indexOf(left.status) -
-        TODO_WIDGET_STATUS_ORDER.indexOf(right.status);
-      return statusDifference === 0 ? left.id - right.id : statusDifference;
-    });
-    const lines = [header];
-    for (const task of orderedTasks.slice(0, TODO_COLLAPSED_TASK_LIMIT)) {
-      lines.push(renderTodoTaskLine(task, this.theme));
-    }
-    const remaining = orderedTasks.length - TODO_COLLAPSED_TASK_LIMIT;
-    if (remaining > 0) lines.push(this.theme.fg("dim", `… ${remaining} more`));
-    return lines.map((line) => truncateToWidth(line, width, "…"));
+    return renderTodoWidget(this.tasks, this.theme, width);
   }
 }
 
@@ -208,7 +181,7 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
     }
   });
 
-  pi.registerTool<typeof TodoParameters, TodoToolDetails | undefined>({
+  const todoTool = defineTool<typeof TodoParameters, TodoToolDetails | undefined>({
     name: "todo",
     label: "Todo",
     description: "Manage the current session branch's Todo List.",
@@ -240,46 +213,11 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
         structuredContent: structuredClone(result.details),
       };
     },
-    renderCall: (params, theme) => {
-      let text = theme.fg("toolTitle", theme.bold("todo")) + theme.fg("muted", ` ${params.action}`);
-      if (params.id !== undefined) text += theme.fg("accent", ` #${params.id}`);
-      if (params.action === "add" && params.title) text += theme.fg("dim", ` "${params.title}"`);
-      if (params.action === "add" && params.tasks) {
-        const count = params.tasks.length;
-        text += theme.fg("dim", ` ${formatTaskCount(count)}`);
-      }
-      if (params.action === "update" && params.updates) {
-        text += theme.fg("dim", ` ${formatTaskCount(params.updates.length)}`);
-      }
-      return new Text(text, 0, 0);
-    },
-    renderResult: (result, { expanded }, theme) => {
-      const text = result.content.find((item) => item.type === "text");
-      if (!result.details) {
-        return new Text(theme.fg("error", text?.text ?? "Todo operation failed"), 0, 0);
-      }
-      if ("tasks" in result.details) {
-        const { action, tasks } = result.details;
-        if (tasks.length === 0) return new Text(theme.fg("dim", "Todo List is empty"), 0, 0);
-        const visibleTasks = expanded ? tasks : tasks.slice(0, TODO_COLLAPSED_TASK_LIMIT);
-        const verb = action === "add" ? "Added " : action === "update" ? "Updated " : "";
-        const heading = `${verb}${formatTaskCount(tasks.length)}:`;
-        const lines = [theme.fg("muted", heading)];
-        for (const task of visibleTasks) {
-          lines.push(renderTodoTaskLine(task, theme));
-          if (expanded && task.description) {
-            lines.push(
-              ...task.description.split("\n").map((line) => theme.fg("dim", `    ${line}`)),
-            );
-          }
-        }
-        const remaining = tasks.length - visibleTasks.length;
-        if (remaining > 0) lines.push(theme.fg("dim", `… ${remaining} more`));
-        return new Text(lines.join("\n"), 0, 0);
-      }
-      return new Text(theme.fg("success", "✓ ") + theme.fg("muted", text?.text ?? "Done"), 0, 0);
-    },
+    renderCall: (params, theme, context) => renderTodoCall(params, theme, context),
+    renderResult: (result, options, theme, context) =>
+      renderTodoResult(result, options, theme, context),
   });
+  pi.registerTool(acceptNullForOptionalArguments(todoTool));
 
   pi.registerCommand("todo", {
     description: "Manage the Todo List",
@@ -293,7 +231,7 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
         return;
       }
       if (context.mode !== "tui") {
-        context.ui.notify("/todo clear requires interactive mode", "error");
+        context.ui.notify(noticeText("Todo", "/todo clear requires interactive mode"), "error");
         return;
       }
       await context.waitForIdle();

package/src/todo-context.ts

@@ -16,6 +16,7 @@ import {
 type Message = ContextEvent["messages"][number];
 /** Marks a snapshot as extension state so the model does not read it as user-authored. */
 const SNAPSHOT_HEADER = "Todo List state from the pi-todo extension (not a user message):";
+const ListDetails = Type.Object({ tasks: Type.Array(Type.Unknown()) });
 const ProjectionDetails = Type.Object(
   {
     version: Type.Literal(1),
@@ -43,6 +44,15 @@ export function todoStateFromEntry(entry: SessionEntry): TodoStateSnapshot | und
   return parseTodoStateSnapshot(entry.data);
 }
 
+/** True when a successful `todo` result's details carry exactly the complete resulting list. */
+function resultRendersList(message: Message | undefined, tasks: TodoStateSnapshot["tasks"]) {
+  if (message?.role !== "toolResult" || message.toolName !== "todo" || message.isError)
+    return false;
+  return (
+    Value.Check(ListDetails, message.details) && isDeepStrictEqual(message.details.tasks, tasks)
+  );
+}
+
 function snapshotMessage(
   entry: SessionEntry,
   state: TodoStateSnapshot,
@@ -113,10 +123,17 @@ export function projectTodoContext(
   }
   const outstanding = new Map<string, number>();
   // A tool group projects only its final state, once its last result has landed.
+  let lastTodoResult: Message | undefined;
   let pending: { entry: SessionEntry; state: TodoStateSnapshot } | undefined;
-  const project = (entry: SessionEntry, state: TodoStateSnapshot): void => {
+  const project = (entry: SessionEntry, state: TodoStateSnapshot, finalResult?: Message): void => {
     const content = formatTodoList(state.tasks);
-    if (content !== previousContent && (previousContent !== undefined || state.tasks.length > 0))
+    // The model already saw this exact list in the group's last result; a Snapshot would repeat it.
+    const rendered = resultRendersList(finalResult, state.tasks);
+    if (
+      !rendered &&
+      content !== previousContent &&
+      (previousContent !== undefined || state.tasks.length > 0)
+    )
       insert(snapshotMessage(entry, state, null));
     previousContent = content;
   };
@@ -134,17 +151,19 @@ export function projectTodoContext(
       if (outstanding.size > 0 && pending)
         throw new Error("Todo mutation has an incomplete tool group");
       outstanding.clear();
+      lastTodoResult = undefined;
       for (const block of message.content)
         if (block.type === "toolCall")
           outstanding.set(block.id, (outstanding.get(block.id) ?? 0) + 1);
     } else if (message.role === "toolResult") {
+      if (message.toolName === "todo") lastTodoResult = message;
       const remaining = (outstanding.get(message.toolCallId) ?? 0) - 1;
       if (remaining > 0) outstanding.set(message.toolCallId, remaining);
       else outstanding.delete(message.toolCallId);
     }
     anchor = message;
     if (outstanding.size === 0 && pending) {
-      project(pending.entry, pending.state);
+      project(pending.entry, pending.state, lastTodoResult);
       pending = undefined;
     }
   }

package/src/todo-render.ts

@@ -0,0 +1,153 @@
+import type { AgentToolResult, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+  appendDurationFooter,
+  callDurationFooter,
+  COLLAPSED_LINES,
+  type DurationContext,
+  expandHint,
+  previewBody,
+  SEPARATOR,
+  toolHeader,
+  type UiTheme,
+  widgetLines,
+} from "@ian-pascoe/pi-utils/ui";
+import {
+  formatTaskCount,
+  type TodoActionInput,
+  type TodoTask,
+  type TodoToolDetails,
+} from "./todo-list.js";
+
+/** The theme methods the Todo renderers draw with. */
+export type TodoRenderTheme = Pick<UiTheme, "fg" | "bold" | "strikethrough">;
+
+const TODO_WIDGET_STATUS_ORDER: readonly TodoTask["status"][] = ["active", "pending", "completed"];
+
+const CHECKBOX_FILL = { pending: " ", active: ">", completed: "x" } as const;
+const CHECKBOX_COLOR = { pending: "muted", active: "accent", completed: "success" } as const;
+
+/**
+ * One Task row. The `[ ]`/`[>]`/`[x]` checkbox is the documented exception to the no-marks rule
+ * for tool rows: it shows the Task's state, not the tool's outcome.
+ */
+export function renderTodoTaskLine(task: TodoTask, theme: TodoRenderTheme): string {
+  const box =
+    theme.fg("dim", "[") +
+    theme.fg(CHECKBOX_COLOR[task.status], CHECKBOX_FILL[task.status]) +
+    theme.fg("dim", "]");
+  const title =
+    task.status === "active"
+      ? theme.bold(task.title)
+      : task.status === "completed"
+        ? theme.strikethrough(task.title)
+        : task.title;
+  const titleColor = task.status === "completed" ? "dim" : "text";
+  return `${box} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(titleColor, title)}`;
+}
+
+/** The Todo Widget lines: Active Tasks first, then pending, then completed, in at most 10 lines. */
+export function renderTodoWidget(
+  tasks: readonly TodoTask[],
+  theme: TodoRenderTheme,
+  width: number,
+): string[] {
+  const active = tasks.filter((task) => task.status === "active").length;
+  const pending = tasks.filter((task) => task.status === "pending").length;
+  const completed = tasks.length - active - pending;
+  const orderedTasks = tasks.toSorted((left, right) => {
+    const statusDifference =
+      TODO_WIDGET_STATUS_ORDER.indexOf(left.status) -
+      TODO_WIDGET_STATUS_ORDER.indexOf(right.status);
+    return statusDifference === 0 ? left.id - right.id : statusDifference;
+  });
+  return widgetLines(theme, {
+    title: "Todo",
+    counts: [`${active} active`, `${pending} pending`, `${completed} completed`].join(SEPARATOR),
+    rows: orderedTasks.map((task) => renderTodoTaskLine(task, theme)),
+  }).map((line) => truncateToWidth(line, width, "..."));
+}
+
+function callArguments(params: TodoActionInput): string | undefined {
+  const parts: string[] = [];
+  if (params.id !== undefined) parts.push(`#${params.id}`);
+  if (params.action === "add" && params.title) parts.push(`"${params.title}"`);
+  if (params.action === "add" && params.tasks) parts.push(formatTaskCount(params.tasks.length));
+  if (params.action === "update" && params.updates) {
+    parts.push(formatTaskCount(params.updates.length));
+  }
+  return parts.length === 0 ? undefined : parts.join(" ");
+}
+
+/** The `todo` call row: bold `todo`, the action in `accent`, arguments in `muted`, then `Elapsed`. */
+export function renderTodoCall(
+  params: TodoActionInput,
+  theme: TodoRenderTheme,
+  context: DurationContext,
+): Component {
+  const container = new Container();
+  container.addChild(
+    new Text(toolHeader(theme, "todo", params.action, callArguments(params)), 0, 0),
+  );
+  container.addChild(callDurationFooter(theme, context));
+  return container;
+}
+
+function taskListLines(
+  action: "list" | "add" | "update",
+  tasks: readonly TodoTask[],
+  theme: TodoRenderTheme,
+  expanded: boolean,
+): string[] {
+  const verb = action === "add" ? "Added " : action === "update" ? "Updated " : "";
+  const lines = [theme.fg("muted", `${verb}${formatTaskCount(tasks.length)}:`)];
+  if (expanded) {
+    for (const task of tasks) {
+      lines.push(renderTodoTaskLine(task, theme));
+      if (task.description) {
+        lines.push(...task.description.split("\n").map((line) => theme.fg("dim", `    ${line}`)));
+      }
+    }
+    return lines;
+  }
+  lines.push(
+    ...tasks.slice(0, COLLAPSED_LINES.list).map((task) => renderTodoTaskLine(task, theme)),
+  );
+  const hidden = tasks.length - COLLAPSED_LINES.list;
+  if (hidden > 0) lines.push(expandHint(theme, hidden));
+  return lines;
+}
+
+/**
+ * The `todo` result row. A Task list is the Nearest Built-in `ls` (20 rows collapsed, Pi's Expand
+ * Hint beyond that); a failure shows its text in `error`. Every result ends with `Took`.
+ */
+export function renderTodoResult(
+  result: AgentToolResult<TodoToolDetails | undefined>,
+  options: ToolRenderResultOptions,
+  theme: TodoRenderTheme,
+  context: DurationContext,
+): Component {
+  const text = result.content.find((item) => item.type === "text")?.text;
+  let body: string[];
+  if (!result.details) {
+    body = previewBody(theme, (text ?? "Todo operation failed").split("\n"), {
+      limit: COLLAPSED_LINES.fallback,
+      expanded: options.expanded,
+      color: "error",
+    });
+  } else if ("tasks" in result.details && result.details.tasks.length > 0) {
+    body = taskListLines(result.details.action, result.details.tasks, theme, options.expanded);
+  } else {
+    const message = "tasks" in result.details ? "Todo List is empty" : (text ?? "Done");
+    body = previewBody(theme, message.split("\n"), {
+      limit: COLLAPSED_LINES.fallback,
+      expanded: options.expanded,
+    });
+  }
+  const container = new Container();
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(body.join("\n"), 0, 0));
+  appendDurationFooter(container, theme, context, { isPartial: options.isPartial });
+  return container;
+}