@ian-pascoe/pi-todo 0.1.3 → 0.2.0

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.84.1`.
+Requires Node `>=22.19.0` and Pi `>=0.99.0`.
 
 ## Install
 
@@ -24,12 +24,23 @@ The `todo` tool supports five actions:
 | `remove` | `id`                                         | Removes one Task                  |
 | `clear`  | —                                            | Removes every Task and resets IDs |
 
+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:
+
+| Action           | Script value                                                                 |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `list`           | `{ action: "list", tasks }`, each Task `{ id, title, description?, status }` |
+| `add` / `update` | `{ action, task }` with the resulting Task                                   |
+| `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.
 
 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.
 
+`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.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-todo",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [
@@ -33,9 +33,9 @@
     "provenance": true
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": ">=0.99.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": "*"
   },
   "engines": {

package/skills/pi-todo/SKILL.md

@@ -2,6 +2,7 @@
 name: pi-todo
 description: Diagnose Pi Todo when its tool, restored Todo List, model context, clear command, transcript rendering, or widget is missing or incorrect.
 license: MIT
+disable-model-invocation: true
 ---
 
 # Pi Todo

package/src/pi-todo-extension.ts

@@ -8,13 +8,16 @@ import {
   createEmptyTodoState,
   TODO_ACTIONS,
   TODO_STATUSES,
+  TodoToolOutputSchema,
   todoStatusMarker,
   type TodoActionInput,
   type TodoStateSnapshot,
   type TodoStatus,
   type TodoTask,
+  TodoOperationError,
   type TodoToolDetails,
 } from "./todo-list.js";
+import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 const TODO_STATE_ENTRY_TYPE = "pi-todo-state";
 const JOURNAL_FAULT = Symbol.for("@ian-pascoe/pi-todo/journal-fault");
@@ -158,13 +161,31 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
     label: "Todo",
     description: "Manage the current session branch's Todo List.",
     parameters: TodoParameters,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+    },
+    outputSchema: TodoToolOutputSchema,
     executionMode: "sequential",
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       signal?.throwIfAborted();
-      const result = runTodoAction(params, context);
+      let result: ReturnType<typeof runTodoAction>;
+      try {
+        result = runTodoAction(params, context);
+      } catch (cause) {
+        // Task-operation errors are model-fixable input errors; anything else is a journal failure.
+        if (cause instanceof TodoOperationError) throw cause;
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(`${message}\n\n${TROUBLESHOOTING_HINT}`, { cause });
+      }
       return {
         content: [{ type: "text", text: result.message }],
         details: result.details,
+        // Separate from `details` so the session's render shape and the script-facing value can
+        // evolve independently; today both use the same snake_case-compatible field names.
+        structuredContent: structuredClone(result.details),
       };
     },
     renderCall: (params, theme) => {

package/src/todo-list.ts

@@ -41,10 +41,15 @@ export type TodoActionInput = {
   readonly status?: TodoStatus;
 };
 
-/** Render details whose action discriminates list data from mutation acknowledgements. */
+/**
+ * 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.
+ */
 export type TodoToolDetails =
   | { readonly action: "list"; readonly tasks: readonly TodoTask[] }
-  | { readonly action: Exclude<TodoAction, "list"> };
+  | { readonly action: "add" | "update"; readonly task: TodoTask }
+  | { readonly action: "remove"; readonly id: TodoTaskId }
+  | { readonly action: "clear"; readonly cleared: number };
 
 const PositiveSafeIntegerRecord = Type.Integer({
   minimum: 1,
@@ -57,6 +62,32 @@ const TodoTaskRecord = Type.Object({
   status: StringEnum(TODO_STATUSES),
 });
 
+/**
+ * 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.
+ */
+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" }),
+    ),
+    task: Type.Optional(TodoTaskRecord),
+    id: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: Number.MAX_SAFE_INTEGER,
+        description: "remove: ID of the removed Task",
+      }),
+    ),
+    cleared: Type.Optional(
+      Type.Integer({ minimum: 0, description: "clear: number of Tasks removed" }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
 /** Serialized shape stored in a `pi-todo-state` session entry. */
 export const TodoStateRecord = Type.Object({
   nextId: PositiveSafeIntegerRecord,
@@ -158,7 +189,7 @@ export function applyTodoAction(
         ok: true,
         state: { nextId: state.nextId + 1, tasks: [...state.tasks, task] },
         message: `Added Task #${task.id}`,
-        details: { action: "add" },
+        details: { action: "add", task },
       };
     }
 
@@ -190,7 +221,7 @@ export function applyTodoAction(
             tasks: state.tasks.filter((candidate) => candidate.id !== task.id),
           },
           message: `Removed Task #${task.id}`,
-          details: { action: "remove" },
+          details: { action: "remove", id: task.id },
         };
       }
       if (
@@ -224,7 +255,7 @@ export function applyTodoAction(
           ),
         },
         message: `Updated Task #${task.id}`,
-        details: { action: "update" },
+        details: { action: "update", task: updatedTask },
       };
     }
 
@@ -234,7 +265,7 @@ export function applyTodoAction(
         ok: true,
         state: count > 0 || state.nextId !== 1 ? createEmptyTodoState() : state,
         message: `Cleared ${count} ${count === 1 ? "Task" : "Tasks"}`,
-        details: { action: "clear" },
+        details: { action: "clear", cleared: count },
       };
     }
   }

package/src/troubleshooting-skill.ts

@@ -0,0 +1,9 @@
+import { fileURLToPath } from "node:url";
+
+/** Absolute path of this package's user-invoked troubleshooting Skill. */
+export const TROUBLESHOOTING_SKILL_PATH = fileURLToPath(
+  new URL("../skills/pi-todo/SKILL.md", import.meta.url),
+);
+
+/** Model-facing pointer appended to failures this package's Skill diagnoses. */
+export const TROUBLESHOOTING_HINT = `For diagnosis, read the pi-todo troubleshooting Skill at ${TROUBLESHOOTING_SKILL_PATH}.`;