@ian-pascoe/pi-todo 0.2.0 → 0.4.0

package/README.md

@@ -16,13 +16,16 @@ pi -e ./src/index.ts
 
 The `todo` tool supports five actions:
 
-| Action   | Input                                        | Result                            |
-| -------- | -------------------------------------------- | --------------------------------- |
-| `list`   | —                                            | Lists every Task                  |
-| `add`    | `title`, optional `description` and `status` | Adds a Task                       |
-| `update` | `id`, plus fields to change                  | Updates a Task                    |
-| `remove` | `id`                                         | Removes one Task                  |
-| `clear`  | —                                            | Removes every Task and resets IDs |
+| Action   | Input                                                 | Result                            |
+| -------- | ----------------------------------------------------- | --------------------------------- |
+| `list`   | —                                                     | Lists every Task                  |
+| `add`    | `title`, optional `description` and `status`          | Adds a Task                       |
+| `add`    | `tasks: [{ title, description? }]`, optional `status` | Adds several Tasks at once        |
+| `update` | `id`, plus fields to change                           | Updates a Task                    |
+| `remove` | `id`                                                  | Removes one Task                  |
+| `clear`  | —                                                     | Removes every Task and resets IDs |
+
+A batch `add` creates every Task in `tasks` atomically, with sequential IDs, and the result lists them. It writes one `pi-todo-state` session entry, so the tool group that made it projects a single Todo List Snapshot. If any title or description is empty, or the Task IDs would run out, it creates no Task. `tasks` must hold at least one entry and replaces `title`/`description`: a request that gives both `tasks` and `title` or a non-null `description` is rejected rather than guessed at. Per-Task fields other than `title` and `description` are rejected too. A top-level `status` applies to every new Task.
 
 A Pi `codemode` script receives the result as an object (the tool declares an `outputSchema`) instead of the text (its field names are already single words, so they match Pi's snake_case convention); the model still reads the same text, and failures still throw:
 
@@ -30,14 +33,15 @@ A Pi `codemode` script receives the result as an object (the tool declares an `o
 | ---------------- | ---------------------------------------------------------------------------- |
 | `list`           | `{ action: "list", tasks }`, each Task `{ id, title, description?, status }` |
 | `add` / `update` | `{ action, task }` with the resulting Task                                   |
+| batch `add`      | `{ action: "add", tasks }` with the created Tasks in ID order                |
 | `remove`         | `{ action: "remove", id }`                                                   |
 | `clear`          | `{ action: "clear", cleared }` with the number of Tasks removed              |
 
 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 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.
+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.
 
-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.
+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.
 
 `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.
 
@@ -49,6 +53,6 @@ State is stored only in `pi-todo-state` session entries, without a second messag
 
 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.
+Missing or ambiguous conversation anchors abort the request instead of silently relocating Todo List 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.2.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [
@@ -50,7 +50,7 @@
     ]
   },
   "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/src/pi-todo-extension.ts

@@ -6,6 +6,7 @@ import { projectTodoContext, todoStateFromEntry } from "./todo-context.js";
 import {
   applyTodoAction,
   createEmptyTodoState,
+  formatTaskCount,
   TODO_ACTIONS,
   TODO_STATUSES,
   TodoToolOutputSchema,
@@ -44,13 +45,34 @@ const TodoParameters = Type.Object({
       description: "Task ID for update or remove",
     }),
   ),
-  title: Type.Optional(Type.String({ description: "Task title for add or update" })),
+  title: Type.Optional(
+    Type.String({ description: "Task title for add or update; not allowed with tasks" }),
+  ),
   description: Type.Optional(
     Type.Union([Type.String(), Type.Null()], {
-      description: "Optional Task description; null removes it during update",
+      description:
+        "Optional Task description; null removes it during update; not allowed with tasks",
     }),
   ),
-  status: Type.Optional(StringEnum(TODO_STATUSES)),
+  tasks: Type.Optional(
+    Type.Array(
+      Type.Object(
+        {
+          title: Type.String({ description: "Task title" }),
+          description: Type.Optional(Type.String({ description: "Optional Task description" })),
+        },
+        { additionalProperties: false },
+      ),
+      {
+        minItems: 1,
+        description:
+          "Tasks to add in one call, all or none, with sequential IDs; use instead of title and description",
+      },
+    ),
+  ),
+  status: Type.Optional(
+    StringEnum(TODO_STATUSES, { description: "Task status; for add, applies to every new Task" }),
+  ),
 });
 
 function restoreTodoState(context: ExtensionContext): TodoStateSnapshot {
@@ -192,6 +214,10 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
       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)}`);
+      }
       return new Text(text, 0, 0);
     },
     renderResult: (result, { expanded }, theme) => {
@@ -199,13 +225,12 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
       if (!result.details) {
         return new Text(theme.fg("error", text?.text ?? "Todo operation failed"), 0, 0);
       }
-      if (result.details.action === "list") {
-        const tasks = result.details.tasks;
+      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 lines = [
-          theme.fg("muted", `${tasks.length} ${tasks.length === 1 ? "Task" : "Tasks"}:`),
-        ];
+        const heading = `${action === "add" ? "Added " : ""}${formatTaskCount(tasks.length)}:`;
+        const lines = [theme.fg("muted", heading)];
         for (const task of visibleTasks) {
           lines.push(renderTodoTaskLine(task, theme));
           if (expanded && task.description) {
@@ -244,7 +269,7 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
       }
       const confirmed = await context.ui.confirm(
         "Clear Todo List",
-        `Remove all ${state.tasks.length} ${state.tasks.length === 1 ? "Task" : "Tasks"}?`,
+        `Remove all ${formatTaskCount(state.tasks.length)}?`,
       );
       if (!confirmed) return;
       const result = runTodoAction({ action: "clear" }, context);

package/src/todo-context.ts

@@ -14,6 +14,8 @@ import {
 } 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 ProjectionDetails = Type.Object(
   {
     version: Type.Literal(1),
@@ -50,7 +52,7 @@ function snapshotMessage(
     role: "custom",
     customType: "pi-todo-context",
     display: false,
-    content: `Todo List:\n${formatTodoList(state.tasks)}`,
+    content: `${SNAPSHOT_HEADER}\n${formatTodoList(state.tasks)}`,
     timestamp: Date.parse(entry.timestamp),
     details: { version: 1, stateEntryId: entry.id, checkpointId },
   };
@@ -110,27 +112,26 @@ export function projectTodoContext(
     }
   }
   const outstanding = new Map<string, number>();
-  let pending: Message[] = [];
+  // A tool group projects only its final state, once its last result has landed.
+  let pending: { entry: SessionEntry; state: TodoStateSnapshot } | undefined;
+  const project = (entry: SessionEntry, state: TodoStateSnapshot): void => {
+    const content = formatTodoList(state.tasks);
+    if (content !== previousContent && (previousContent !== undefined || state.tasks.length > 0))
+      insert(snapshotMessage(entry, state, null));
+    previousContent = content;
+  };
   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;
+      if (outstanding.size > 0) pending = { entry, state };
+      else project(entry, state);
       continue;
     }
     const message = conversationMessage(entry);
     if (!message) continue;
     if (message.role === "assistant") {
-      if (outstanding.size > 0 && pending.length > 0)
+      if (outstanding.size > 0 && pending)
         throw new Error("Todo mutation has an incomplete tool group");
       outstanding.clear();
       for (const block of message.content)
@@ -142,12 +143,12 @@ export function projectTodoContext(
       else outstanding.delete(message.toolCallId);
     }
     anchor = message;
-    if (outstanding.size === 0 && pending.length > 0) {
-      for (const snapshot of pending) insert(snapshot);
-      pending = [];
+    if (outstanding.size === 0 && pending) {
+      project(pending.entry, pending.state);
+      pending = undefined;
     }
   }
-  if (pending.length > 0) throw new Error("Todo mutation has an incomplete tool group");
+  if (pending) throw new Error("Todo mutation has an incomplete tool group");
   return [
     ...(insertions.get(-1) ?? []),
     ...messages.flatMap((message, index) => [message, ...(insertions.get(index) ?? [])]),

package/src/todo-list.ts

@@ -32,21 +32,30 @@ export type TodoStateSnapshot = {
   readonly tasks: readonly TodoTask[];
 };
 
+/** One Task to create within a batch `add`. */
+export type TodoTaskDraft = {
+  readonly title: string;
+  readonly description?: string;
+};
+
 /** Boundary input shared by the Todo tool's five operations. */
 export type TodoActionInput = {
   readonly action: TodoAction;
   readonly id?: number;
   readonly title?: string;
   readonly description?: string | null;
+  readonly tasks?: readonly TodoTaskDraft[];
   readonly status?: TodoStatus;
 };
 
 /**
- * Render details and the tool's structured result. The action discriminates the list from the
- * Task a mutation added or updated, the ID it removed, and the count it cleared.
+ * Render details and the tool's structured result. The action, plus `tasks` versus `task` for
+ * `add`, discriminates the list from the Task(s) a mutation added or updated, the ID it removed,
+ * and the count it cleared. A batch `add` returns the Tasks it created as `tasks`; a single `add`
+ * returns `task`.
  */
 export type TodoToolDetails =
-  | { readonly action: "list"; readonly tasks: readonly TodoTask[] }
+  | { readonly action: "list" | "add"; readonly tasks: readonly TodoTask[] }
   | { readonly action: "add" | "update"; readonly task: TodoTask }
   | { readonly action: "remove"; readonly id: TodoTaskId }
   | { readonly action: "clear"; readonly cleared: number };
@@ -64,14 +73,16 @@ const TodoTaskRecord = Type.Object({
 
 /**
  * JSON Schema of the `todo` tool's `structuredContent`, which codemode scripts receive instead of
- * the model-facing text. Flat so Pi's one-line script declaration stays compact; `action` says
- * which other field is present.
+ * the model-facing text. Flat so Pi's one-line script declaration stays compact; `action` (and, for
+ * `add`, whether the request carried `tasks`) says which other field is present.
  */
 export const TodoToolOutputSchema = Type.Object(
   {
     action: StringEnum(TODO_ACTIONS, { description: "The operation that ran" }),
     tasks: Type.Optional(
-      Type.Array(TodoTaskRecord, { description: "list: every Task in ID order" }),
+      Type.Array(TodoTaskRecord, {
+        description: "list: every Task in ID order; add with tasks: the Tasks created, in ID order",
+      }),
     ),
     task: Type.Optional(TodoTaskRecord),
     id: Type.Optional(
@@ -157,6 +168,96 @@ function todoOperationFailure(action: TodoAction, message: string): TodoActionRe
   return { ok: false, error: new TodoOperationError(action, message) };
 }
 
+function newTodoTask(
+  id: TodoTaskId,
+  title: string,
+  description: string | undefined,
+  status: TodoStatus,
+): TodoTask {
+  return description ? { id, title, description, status } : { id, title, status };
+}
+
+/** Counts Tasks in model-facing text: "1 Task", "3 Tasks". */
+export function formatTaskCount(count: number): string {
+  return `${count} ${count === 1 ? "Task" : "Tasks"}`;
+}
+
+type ParsedTodoDraft = { readonly title: string; readonly description: string | undefined };
+
+/** Trims and validates one Task to add; `field` prefixes the field name in the failure message. */
+function parseTodoDraft(
+  title: string | undefined,
+  description: string | null | undefined,
+  field: string,
+): ParsedTodoDraft | TodoActionResult {
+  const trimmedTitle = title?.trim();
+  if (!trimmedTitle) {
+    return todoOperationFailure("add", `Todo add failed: ${field}title must not be empty`);
+  }
+  const trimmedDescription = description?.trim();
+  if (description !== undefined && description !== null && !trimmedDescription) {
+    return todoOperationFailure("add", `Todo add failed: ${field}description must not be empty`);
+  }
+  return { title: trimmedTitle, description: trimmedDescription };
+}
+
+function isTodoActionResult(value: ParsedTodoDraft | TodoActionResult): value is TodoActionResult {
+  return "ok" in value;
+}
+
+function addTask(state: TodoStateSnapshot, input: TodoActionInput): TodoActionResult {
+  const draft = parseTodoDraft(input.title, input.description, "");
+  if (isTodoActionResult(draft)) return draft;
+  const id = parseTodoTaskId(state.nextId);
+  if (id === undefined || state.nextId === Number.MAX_SAFE_INTEGER) {
+    return todoOperationFailure("add", "Todo add failed: Task ID limit reached");
+  }
+  const task = newTodoTask(id, draft.title, draft.description, input.status ?? "pending");
+  return {
+    ok: true,
+    state: { nextId: state.nextId + 1, tasks: [...state.tasks, task] },
+    message: `Added Task #${task.id}`,
+    details: { action: "add", task },
+  };
+}
+
+/** Validates every draft before creating any Task, so a batch is all-or-nothing. */
+function addTasks(
+  state: TodoStateSnapshot,
+  input: TodoActionInput & { readonly tasks: readonly TodoTaskDraft[] },
+): TodoActionResult {
+  // A null description is "absent" for add, as it is for a single Task.
+  if (input.title !== undefined || (input.description ?? undefined) !== undefined) {
+    return todoOperationFailure("add", "Todo add failed: provide either title or tasks, not both");
+  }
+  if (input.tasks.length === 0) {
+    return todoOperationFailure("add", "Todo add failed: tasks must not be empty");
+  }
+  const drafts: ParsedTodoDraft[] = [];
+  for (const [index, task] of input.tasks.entries()) {
+    const draft = parseTodoDraft(task.title, task.description, `tasks[${index}].`);
+    if (isTodoActionResult(draft)) return draft;
+    drafts.push(draft);
+  }
+  // The last Task's successor ID must stay a safe integer so the saved state restores.
+  const exceedsIdLimit = state.nextId + drafts.length > Number.MAX_SAFE_INTEGER;
+  const status = input.status ?? "pending";
+  const added: TodoTask[] = [];
+  for (const [index, { title, description }] of drafts.entries()) {
+    const id = parseTodoTaskId(state.nextId + index);
+    if (id === undefined || exceedsIdLimit) {
+      return todoOperationFailure("add", "Todo add failed: Task ID limit reached");
+    }
+    added.push(newTodoTask(id, title, description, status));
+  }
+  return {
+    ok: true,
+    state: { nextId: state.nextId + added.length, tasks: [...state.tasks, ...added] },
+    message: `Added ${formatTaskCount(added.length)}\n${formatTodoList(added)}`,
+    details: { action: "add", tasks: added },
+  };
+}
+
 /** Applies one validated-by-schema tool request without performing session or UI effects. */
 export function applyTodoAction(
   state: TodoStateSnapshot,
@@ -171,27 +272,10 @@ export function applyTodoAction(
         details: { action: "list", tasks: state.tasks },
       };
 
-    case "add": {
-      const title = input.title?.trim();
-      if (!title) return todoOperationFailure("add", "Todo add failed: title must not be empty");
-      const description = input.description?.trim();
-      if (input.description !== undefined && input.description !== null && !description) {
-        return todoOperationFailure("add", "Todo add failed: description must not be empty");
-      }
-      const id = parseTodoTaskId(state.nextId);
-      if (id === undefined || state.nextId === Number.MAX_SAFE_INTEGER) {
-        return todoOperationFailure("add", "Todo add failed: Task ID limit reached");
-      }
-      const task: TodoTask = description
-        ? { id, title, description, status: input.status ?? "pending" }
-        : { id, title, status: input.status ?? "pending" };
-      return {
-        ok: true,
-        state: { nextId: state.nextId + 1, tasks: [...state.tasks, task] },
-        message: `Added Task #${task.id}`,
-        details: { action: "add", task },
-      };
-    }
+    case "add":
+      return input.tasks === undefined
+        ? addTask(state, input)
+        : addTasks(state, { ...input, tasks: input.tasks });
 
     case "update":
     case "remove": {
@@ -264,7 +348,7 @@ export function applyTodoAction(
       return {
         ok: true,
         state: count > 0 || state.nextId !== 1 ? createEmptyTodoState() : state,
-        message: `Cleared ${count} ${count === 1 ? "Task" : "Tasks"}`,
+        message: `Cleared ${formatTaskCount(count)}`,
         details: { action: "clear", cleared: count },
       };
     }