@ian-pascoe/pi-todo 0.6.2 → 0.6.4

package/README.md

@@ -43,9 +43,11 @@ 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, 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.
+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 definition stay the same for the whole session.
 
-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.
+The tool adds one line to the Available tools section of Pi's default system prompt (`todo: Track this session's Tasks in the Todo List`) and one guideline: when the Todo List has Tasks, mark a Task active when you start it and completed as soon as it is done, and bring the list up to date before context is compacted. Both are fixed text, so they never change the prompt prefix. A custom system prompt (`SYSTEM.md`) omits tool snippets and guidelines, as Pi does for every tool.
+
+After compaction, a fixed baseline immediately after the summary restores the state from before the retained Tail. Retained and newer tool groups follow chronologically. When the Todo List still has unfinished Tasks at the checkpoint, a **Checkpoint Snapshot** follows the retained Tail, where the next Context Window resumes: it repeats the list as compaction left it and asks the agent to reconcile it with the work already done and the plan carried forward (a Handoff's own next steps otherwise quietly replace the list). It replaces the Tail's last Snapshot when that sits at the same position and shows the same list, such as the baseline when the Tail is empty, so the list is not printed twice. An empty or fully completed list adds none. This preserves previously written conversation cache prefixes between checkpoints; it does not guarantee provider cache hits.
 
 `todo` declares MCP-style `annotations`: not read-only, but non-destructive (it only appends to the session's own journal), not idempotent, and closed-world. Pi reports them through `pi.getAllTools()` for permission extensions and does not send them to model providers.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-todo",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [
@@ -33,7 +33,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.6.0"
+    "@ian-pascoe/pi-utils": "^0.7.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": ">=1.1.0",

package/src/pi-todo-extension.ts

@@ -40,6 +40,11 @@ function assertTodoJournalReadable(context: ExtensionContext): void {
 }
 const TODO_WIDGET_ID = "pi-todo";
 
+/** Static system prompt lines, so they never move the cache prefix within a session. */
+export const TODO_PROMPT_SNIPPET = "Track this session's Tasks in the Todo List";
+export const TODO_PROMPT_GUIDELINE =
+  "When the Todo List has Tasks, keep it current: mark a Task active when you start it and completed as soon as it is done, and bring it up to date before context is compacted.";
+
 const TodoParameters = Type.Object({
   action: StringEnum(TODO_ACTIONS),
   id: Type.Optional(
@@ -185,6 +190,8 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
     name: "todo",
     label: "Todo",
     description: "Manage the current session branch's Todo List.",
+    promptSnippet: TODO_PROMPT_SNIPPET,
+    promptGuidelines: [TODO_PROMPT_GUIDELINE],
     parameters: TodoParameters,
     annotations: {
       readOnlyHint: false,

package/src/todo-context.ts

@@ -17,6 +17,9 @@ 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):";
+/** Closes a Checkpoint Snapshot: a Handoff's own plan otherwise silently replaces the Todo List. */
+export const CHECKPOINT_INSTRUCTION =
+  "Context was compacted while Tasks were unfinished. Before continuing, reconcile this Todo List with the work already done and the plan carried forward: mark finished Tasks completed, remove abandoned ones, and keep it current as you work.";
 const ListDetails = Type.Object({ tasks: Type.Array(Type.Unknown()) });
 const ProjectionDetails = Type.Object(
   {
@@ -124,12 +127,14 @@ function snapshotMessage(
   entry: SessionEntry,
   state: TodoStateSnapshot,
   checkpointId: string | null,
+  instruction?: string,
 ): Message {
+  const list = `${SNAPSHOT_HEADER}\n${formatTodoList(state.tasks)}`;
   return {
     role: "custom",
     customType: "pi-todo-context",
     display: false,
-    content: `${SNAPSHOT_HEADER}\n${formatTodoList(state.tasks)}`,
+    content: instruction === undefined ? list : `${list}\n\n${instruction}`,
     timestamp: Date.parse(entry.timestamp),
     details: { version: 1, stateEntryId: entry.id, checkpointId },
   };
@@ -153,9 +158,12 @@ export function projectTodoContext(
   let start = 0;
   let anchor: Message | undefined;
   let previousContent: string | undefined;
+  // The latest state at the point being projected; at the checkpoint, the state it compacted.
+  let current: { entry: SessionEntry; state: TodoStateSnapshot } | undefined;
   const insertions = new Map<number, Message[]>();
   let previousIndex = -1;
-  const insert = (snapshot: Message): void => {
+  /** `supersedes` replaces the last Snapshot at the same position when it shows the same list. */
+  const insert = (snapshot: Message, supersedes?: string): void => {
     let index = -1;
     if (anchor) {
       // ponytail: linear exact matching per mutation; index fingerprints if large journals make this measurable.
@@ -171,6 +179,8 @@ export function projectTodoContext(
     if (index < previousIndex) throw new Error("Todo context anchors are reordered");
     previousIndex = index;
     const group = insertions.get(index) ?? [];
+    const last = group.at(-1);
+    if (last?.role === "custom" && last.content === supersedes) group.pop();
     group.push(snapshot);
     insertions.set(index, group);
   };
@@ -183,11 +193,26 @@ export function projectTodoContext(
     for (const entry of branch.slice(0, start).toReversed()) {
       const state = todoStateFromEntry(entry);
       if (!state) continue;
+      current = { entry, state };
       previousContent = formatTodoList(state.tasks);
       insert(snapshotMessage(entry, state, checkpoint.id));
       break;
     }
   }
+  /**
+   * After the retained Tail, where the next Context Window resumes, unfinished Tasks get one
+   * Checkpoint Snapshot asking the agent to reconcile them. It replaces an identical Snapshot at the
+   * same position, such as the baseline when the Tail is empty, rather than repeating the list.
+   */
+  const projectCheckpoint = (checkpointId: string): void => {
+    if (!current?.state.tasks.some((task) => task.status !== "completed")) return;
+    const { entry, state } = current;
+    previousContent = formatTodoList(state.tasks);
+    insert(
+      snapshotMessage(entry, state, checkpointId, CHECKPOINT_INSTRUCTION),
+      `${SNAPSHOT_HEADER}\n${previousContent}`,
+    );
+  };
   const outstanding = new Map<string, number>();
   // 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.
@@ -206,9 +231,13 @@ export function projectTodoContext(
     previousContent = content;
   };
   for (const entry of branch.slice(start)) {
-    if (entry === checkpoint) continue;
+    if (entry === checkpoint) {
+      projectCheckpoint(entry.id);
+      continue;
+    }
     const state = todoStateFromEntry(entry);
     if (state) {
+      current = { entry, state };
       if (outstanding.size > 0) pending = { entry, state };
       else project(entry, state);
       continue;