@ian-pascoe/pi-todo 0.1.4 → 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.4",
+  "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/src/pi-todo-extension.ts

@@ -8,6 +8,7 @@ import {
   createEmptyTodoState,
   TODO_ACTIONS,
   TODO_STATUSES,
+  TodoToolOutputSchema,
   todoStatusMarker,
   type TodoActionInput,
   type TodoStateSnapshot,
@@ -160,6 +161,13 @@ 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();
@@ -175,6 +183,9 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
       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 },
       };
     }
   }