@ian-pascoe/pi-todo 0.1.1 → 0.1.3

package/README.md

@@ -26,12 +26,18 @@ The `todo` tool supports five actions:
 
 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.
 
-The extension appends the current Todo List as hidden tail context before each model request. It does not modify the system prompt or tool description as the list changes, preserving the cacheable prompt prefix.
+Each changed Todo List is projected from its immutable session state entry as a hidden full snapshot at a fixed conversation position. Mutations inside a tool group appear after all sibling results; later requests keep earlier snapshots in place. Clearing the list produces an explicit empty 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 mutations follow chronologically. This preserves previously written conversation cache prefixes between checkpoints; it does not guarantee provider cache hits.
 
 ## UI and persistence
 
 In interactive mode, a compact widget above the editor shows status counts and up to five Tasks. Tool calls and results use custom transcript rendering. `/todo clear` confirms before manually clearing the list.
 
-State is stored only in Pi session entries. It follows the active session branch and survives reloads, restarts, and compaction. The package has no settings or external state.
+State is stored only in `pi-todo-state` session entries, without a second message journal. It follows the active session branch and survives reloads, restarts, and compaction. Legacy state entries use the same projection. The package has no settings or external state.
+
+A failed journal write leaves acknowledged Todo state unchanged and disables Todo in that loaded session, including across `/reload`. Pi has an existing persistence limitation: subsequent entries can reference the unwritten entry, so reopening may omit earlier history from the selected branch even though it remains in the file. Todo does not repair session history; recovery is outside this cache-prefix change.
+
+Missing or ambiguous conversation anchors abort the request instead of silently relocating snapshots. Extensions that rewrite those anchors are unsupported.
 
 This is privileged extension code: review it before installing it into an agent that can access local files, tools, or credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-todo",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [

package/src/pi-todo-extension.ts

@@ -2,15 +2,12 @@ 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 { Type } from "typebox";
-import { Value } from "typebox/value";
+import { projectTodoContext, todoStateFromEntry } from "./todo-context.js";
 import {
   applyTodoAction,
   createEmptyTodoState,
-  formatTodoList,
-  parseTodoStateSnapshot,
   TODO_ACTIONS,
   TODO_STATUSES,
-  TodoStateRecord,
   todoStatusMarker,
   type TodoActionInput,
   type TodoStateSnapshot,
@@ -20,6 +17,17 @@ import {
 } from "./todo-list.js";
 
 const TODO_STATE_ENTRY_TYPE = "pi-todo-state";
+const JOURNAL_FAULT = Symbol.for("@ian-pascoe/pi-todo/journal-fault");
+
+function assertTodoJournalReadable(context: ExtensionContext): void {
+  const manager = context.sessionManager;
+  const marker = Object.getOwnPropertyDescriptor(manager, JOURNAL_FAULT);
+  if (marker !== undefined && marker.value === manager.getHeader()) {
+    throw new Error(
+      "Todo journal write failed; Todo is disabled in this loaded session, including after /reload",
+    );
+  }
+}
 const TODO_WIDGET_ID = "pi-todo";
 const TODO_WIDGET_STATUS_ORDER: readonly TodoStatus[] = ["active", "pending", "completed"];
 const TODO_COLLAPSED_TASK_LIMIT = 5;
@@ -44,14 +52,7 @@ const TodoParameters = Type.Object({
 
 function restoreTodoState(context: ExtensionContext): TodoStateSnapshot {
   for (const entry of context.sessionManager.getBranch().toReversed()) {
-    if (
-      entry.type !== "custom" ||
-      entry.customType !== TODO_STATE_ENTRY_TYPE ||
-      !Value.Check(TodoStateRecord, entry.data)
-    ) {
-      continue;
-    }
-    const snapshot = parseTodoStateSnapshot(entry.data);
+    const snapshot = todoStateFromEntry(entry);
     if (snapshot) return snapshot;
   }
   return createEmptyTodoState();
@@ -113,32 +114,43 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
     );
   };
   const commitTodoState = (snapshot: TodoStateSnapshot, context: ExtensionContext): void => {
+    try {
+      pi.appendEntry(TODO_STATE_ENTRY_TYPE, snapshot);
+    } catch (cause) {
+      // Todo-owned metadata survives /reload; no Pi-owned journal or agent fields are changed.
+      Object.defineProperty(context.sessionManager, JOURNAL_FAULT, {
+        value: context.sessionManager.getHeader(),
+        configurable: true,
+      });
+      context.abort();
+      throw cause;
+    }
     state = snapshot;
-    pi.appendEntry(TODO_STATE_ENTRY_TYPE, state);
     updateTodoWidget(context);
   };
   const runTodoAction = (input: TodoActionInput, context: ExtensionContext) => {
+    assertTodoJournalReadable(context);
     const result = applyTodoAction(state, input);
     if (!result.ok) throw result.error;
     if (result.state !== state) commitTodoState(result.state, context);
     return result;
   };
   const restoreState = (context: ExtensionContext): void => {
+    assertTodoJournalReadable(context);
     state = restoreTodoState(context);
     updateTodoWidget(context);
   };
   pi.on("session_start", (_event, context) => restoreState(context));
   pi.on("session_tree", (_event, context) => restoreState(context));
-  pi.on("context", (event) => {
-    if (state.tasks.length === 0) return;
-    const todoListMessage = {
-      role: "custom",
-      customType: "pi-todo-context",
-      content: `Todo List:\n${formatTodoList(state.tasks)}`,
-      display: false,
-      timestamp: 0,
-    } as const;
-    return { messages: [...event.messages, todoListMessage] };
+  pi.on("context", (event, context) => {
+    try {
+      assertTodoJournalReadable(context);
+      return { messages: projectTodoContext(context.sessionManager.getBranch(), event.messages) };
+    } catch (cause) {
+      // Pi logs context exceptions and continues; abort the active run as well.
+      context.abort();
+      throw cause;
+    }
   });
 
   pi.registerTool<typeof TodoParameters, TodoToolDetails | undefined>({
@@ -147,7 +159,8 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
     description: "Manage the current session branch's Todo List.",
     parameters: TodoParameters,
     executionMode: "sequential",
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
+    async execute(_toolCallId, params, signal, _onUpdate, context) {
+      signal?.throwIfAborted();
       const result = runTodoAction(params, context);
       return {
         content: [{ type: "text", text: result.message }],

package/src/todo-context.ts

@@ -0,0 +1,155 @@
+import { isDeepStrictEqual } from "node:util";
+import {
+  buildSessionContext,
+  type ContextEvent,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import {
+  formatTodoList,
+  parseTodoStateSnapshot,
+  TodoStateRecord,
+  type TodoStateSnapshot,
+} from "./todo-list.js";
+
+type Message = ContextEvent["messages"][number];
+const ProjectionDetails = Type.Object(
+  {
+    version: Type.Literal(1),
+    stateEntryId: Type.String(),
+    checkpointId: Type.Union([Type.String(), Type.Null()]),
+  },
+  { additionalProperties: false },
+);
+
+/** Context handlers never receive system messages, so anchors must skip Pi's system state. */
+function conversationMessage(entry: SessionEntry): Message | undefined {
+  return buildSessionContext([entry], entry.id).messages.find(
+    (message) => message.role !== "system",
+  );
+}
+
+/** Validates both the serialized shape and Todo List invariants at the journal boundary. */
+export function todoStateFromEntry(entry: SessionEntry): TodoStateSnapshot | undefined {
+  if (
+    entry.type !== "custom" ||
+    entry.customType !== "pi-todo-state" ||
+    !Value.Check(TodoStateRecord, entry.data)
+  )
+    return undefined;
+  return parseTodoStateSnapshot(entry.data);
+}
+
+function snapshotMessage(
+  entry: SessionEntry,
+  state: TodoStateSnapshot,
+  checkpointId: string | null,
+): Message {
+  return {
+    role: "custom",
+    customType: "pi-todo-context",
+    display: false,
+    content: `Todo List:\n${formatTodoList(state.tasks)}`,
+    timestamp: Date.parse(entry.timestamp),
+    details: { version: 1, stateEntryId: entry.id, checkpointId },
+  };
+}
+
+/** Reprojects only Todo-owned snapshots at immutable journal boundaries, never at the live tail. */
+export function projectTodoContext(
+  branch: readonly SessionEntry[],
+  incoming: ContextEvent["messages"],
+): ContextEvent["messages"] {
+  const messages = incoming.filter(
+    (message) =>
+      !(
+        message.role === "custom" &&
+        message.customType === "pi-todo-context" &&
+        Value.Check(ProjectionDetails, message.details)
+      ),
+  );
+  if (!branch.some((entry) => todoStateFromEntry(entry))) return messages;
+  const checkpoint = branch.findLast((entry) => entry.type === "compaction");
+  let start = 0;
+  let anchor: Message | undefined;
+  let previousContent: string | undefined;
+  const insertions = new Map<number, Message[]>();
+  let previousIndex = -1;
+  const insert = (snapshot: Message): void => {
+    let index = -1;
+    if (anchor) {
+      // ponytail: linear exact matching per mutation; index fingerprints if large journals make this measurable.
+      const matches = messages.flatMap((message, i) =>
+        isDeepStrictEqual(message, anchor) ? [i] : [],
+      );
+      if (matches.length !== 1)
+        throw new Error(
+          "Todo context anchor is missing or ambiguous; cannot preserve snapshot order",
+        );
+      index = matches[0]!;
+    }
+    if (index < previousIndex) throw new Error("Todo context anchors are reordered");
+    previousIndex = index;
+    const group = insertions.get(index) ?? [];
+    group.push(snapshot);
+    insertions.set(index, group);
+  };
+  if (checkpoint) {
+    start = branch.findIndex((entry) => entry.id === checkpoint.firstKeptEntryId);
+    const checkpointIndex = branch.indexOf(checkpoint);
+    if (start < 0 || start > checkpointIndex)
+      throw new Error("Todo checkpoint cutoff is unavailable");
+    anchor = conversationMessage(checkpoint);
+    for (const entry of branch.slice(0, start).toReversed()) {
+      const state = todoStateFromEntry(entry);
+      if (!state) continue;
+      previousContent = formatTodoList(state.tasks);
+      insert(snapshotMessage(entry, state, checkpoint.id));
+      break;
+    }
+  }
+  const outstanding = new Map<string, number>();
+  let pending: Message[] = [];
+  for (const entry of branch.slice(start)) {
+    if (entry === checkpoint) continue;
+    const state = todoStateFromEntry(entry);
+    if (state) {
+      const content = formatTodoList(state.tasks);
+      if (
+        content !== previousContent &&
+        (previousContent !== undefined || state.tasks.length > 0)
+      ) {
+        const snapshot = snapshotMessage(entry, state, null);
+        if (outstanding.size > 0) pending.push(snapshot);
+        else insert(snapshot);
+      }
+      previousContent = content;
+      continue;
+    }
+    const message = conversationMessage(entry);
+    if (!message) continue;
+    if (message.role === "assistant") {
+      if (outstanding.size > 0 && pending.length > 0)
+        throw new Error("Todo mutation has an incomplete tool group");
+      outstanding.clear();
+      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") {
+      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.length > 0) {
+      for (const snapshot of pending) insert(snapshot);
+      pending = [];
+    }
+  }
+  if (pending.length > 0) throw new Error("Todo mutation has an incomplete tool group");
+  return [
+    ...(insertions.get(-1) ?? []),
+    ...messages.flatMap((message, index) => [message, ...(insertions.get(index) ?? [])]),
+  ];
+}