@ian-pascoe/pi-todo 0.6.0 → 0.6.2

package/README.md

@@ -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` result counts only when Pi recorded a nested `todo` call on it, so an unrelated script never replaces an earlier `todo` result. Such a group skips the same way when its result is successful, its output is at most 64 KiB, and the last Todo List it prints as JSON (such as a nested `todo` call's returned value) equals the complete final Todo List; Pi records nested calls without their results, so the script's output text is the only evidence, and a script that prints no list, a partial result, or a stale list still adds one. 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.6.0",
+  "version": "0.6.2",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [
@@ -33,7 +33,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.5.0"
+    "@ian-pascoe/pi-utils": "^0.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=1.1.0",

package/src/pi-todo-extension.ts

@@ -1,6 +1,12 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+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";
@@ -175,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.",
@@ -211,6 +217,7 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
     renderResult: (result, options, theme, context) =>
       renderTodoResult(result, options, theme, context),
   });
+  pi.registerTool(acceptNullForOptionalArguments(todoTool));
 
   pi.registerCommand("todo", {
     description: "Manage the Todo List",

package/src/todo-context.ts

@@ -4,18 +4,20 @@ import {
   type ContextEvent,
   type SessionEntry,
 } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import {
   formatTodoList,
   parseTodoStateSnapshot,
   TodoStateRecord,
+  TodoTaskRecord,
   type TodoStateSnapshot,
 } from "./todo-list.js";
 
 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 +45,81 @@ export function todoStateFromEntry(entry: SessionEntry): TodoStateSnapshot | und
   return parseTodoStateSnapshot(entry.data);
 }
 
+/** A printed result's `tasks`, or a bare non-empty Task array a script returned. */
+const ShownTasks = Type.Union([
+  Type.Object({ tasks: Type.Array(TodoTaskRecord) }),
+  Type.Array(TodoTaskRecord, { minItems: 1 }),
+]);
+/** Longer output is treated as not showing the list; Pi itself truncates output near this size. */
+const MAX_SCANNED_OUTPUT_CHARS = 65_536;
+
+/**
+ * The last Todo List a `codemode` script printed as JSON, however deeply it nested it.
+ *
+ * Deliberate coupling to codemode's output text: Pi records a script's nested calls on the
+ * `codemode` tool result without their results (`nestedCalls` holds names, arguments and
+ * statuses only), so what the model saw can only be read from the output. This is a best-effort
+ * dedupe: anything unrecognised keeps the Snapshot, which is always safe.
+ *
+ * One pass tracks bracket nesting and string state, and parses each balanced value that mentions
+ * Tasks, so the cost is bounded by output size times nesting depth.
+ */
+function lastListInText(text: string): readonly Static<typeof TodoTaskRecord>[] | undefined {
+  let last: readonly Static<typeof TodoTaskRecord>[] | undefined;
+  if (text.length > MAX_SCANNED_OUTPUT_CHARS) return last;
+  const opened: number[] = [];
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (inString) {
+      if (char === "\\") i++;
+      else if (char === '"') inString = false;
+    } else if (char === '"') inString = opened.length > 0;
+    else if (char === "{" || char === "[") opened.push(i);
+    else if (char === "}" || char === "]") {
+      const start = opened.pop();
+      if (start === undefined || text[start] !== (char === "}" ? "{" : "[")) {
+        opened.length = 0;
+        continue;
+      }
+      const candidate = text.slice(start, i + 1);
+      if (!candidate.includes('"title"') && !candidate.includes('"tasks"')) continue;
+      try {
+        const value = JSON.parse(candidate);
+        if (Value.Check(ShownTasks, value)) last = Array.isArray(value) ? value : value.tasks;
+      } catch {
+        // Not JSON: prose that merely contains brackets.
+      }
+    }
+  }
+  return last;
+}
+
+/** True when Pi recorded a nested `todo` call on this `codemode` result. */
+function codemodeCalledTodo(message: Message): boolean {
+  return (
+    message.role === "toolResult" &&
+    message.toolName === "codemode" &&
+    (message.nestedCalls?.calls ?? []).some((call) => call.name === "todo")
+  );
+}
+
+/**
+ * True when a successful `todo` result's details, or the last list the output of a successful
+ * `codemode` script that called `todo` printed, carry exactly the complete resulting list.
+ */
+function resultRendersList(message: Message | undefined, tasks: TodoStateSnapshot["tasks"]) {
+  if (message?.role !== "toolResult" || message.isError) return false;
+  if (message.toolName === "todo")
+    return (
+      Value.Check(ListDetails, message.details) && isDeepStrictEqual(message.details.tasks, tasks)
+    );
+  if (!codemodeCalledTodo(message)) return false;
+  const text = message.content.flatMap((block) => (block.type === "text" ? [block.text] : []));
+  const shown = lastListInText(text.join("\n"));
+  return shown !== undefined && isDeepStrictEqual(shown, tasks);
+}
+
 function snapshotMessage(
   entry: SessionEntry,
   state: TodoStateSnapshot,
@@ -112,11 +189,19 @@ export function projectTodoContext(
     }
   }
   const outstanding = new Map<string, number>();
-  // A tool group projects only its final state, once its last result has landed.
+  // A tool group projects only its final state, once its last result has landed. Nested `todo`
+  // calls in a `codemode` script leave no results in the journal, so the script's result stands in.
+  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 +219,20 @@ 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") {
+      // A `codemode` result counts only when it recorded a nested `todo` call.
+      if (message.toolName === "todo" || codemodeCalledTodo(message)) 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-list.ts

@@ -73,7 +73,7 @@ const PositiveSafeIntegerRecord = Type.Integer({
   minimum: 1,
   maximum: Number.MAX_SAFE_INTEGER,
 });
-const TodoTaskRecord = Type.Object({
+export const TodoTaskRecord = Type.Object({
   id: PositiveSafeIntegerRecord,
   title: Type.String({ minLength: 1 }),
   description: Type.Optional(Type.String({ minLength: 1 })),