@ian-pascoe/pi-todo 0.4.0 → 0.5.0

package/README.md

@@ -22,11 +22,14 @@ The `todo` tool supports five actions:
 | `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                    |
+| `update` | `updates: [{ id, status?, title?, description? }]`    | Updates several Tasks at once     |
 | `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 batch `update` changes every Task in `updates` atomically and the result lists them in request order. It writes one `pi-todo-state` session entry, so the tool group that made it projects a single Todo List Snapshot. If any ID is unknown or repeated, any title or description is empty, or any entry provides no title, description, or status, it changes no Task. `updates` must hold at least one entry and replaces `id`, `title`, `description`, and `status`: a request that gives both `updates` and any of those (a `null` description counts as absent) is rejected rather than guessed at. Per-Task fields other than `id`, `status`, `title`, and `description` are rejected too.
+
 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                                                                 |
@@ -34,6 +37,7 @@ 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                |
+| batch `update`   | `{ action: "update", tasks }` with the changed Tasks in request order        |
 | `remove`         | `{ action: "remove", id }`                                                   |
 | `clear`          | `{ action: "clear", cleared }` with the number of Tasks removed              |
 

package/package.json

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

package/src/pi-todo-extension.ts

@@ -42,16 +42,18 @@ const TodoParameters = Type.Object({
     Type.Integer({
       minimum: 1,
       maximum: Number.MAX_SAFE_INTEGER,
-      description: "Task ID for update or remove",
+      description: "Task ID for update or remove; not allowed with updates",
     }),
   ),
   title: Type.Optional(
-    Type.String({ description: "Task title for add or update; not allowed with tasks" }),
+    Type.String({
+      description: "Task title for add or update; not allowed with tasks or updates",
+    }),
   ),
   description: Type.Optional(
     Type.Union([Type.String(), Type.Null()], {
       description:
-        "Optional Task description; null removes it during update; not allowed with tasks",
+        "Optional Task description; null removes it during update; not allowed with tasks or updates",
     }),
   ),
   tasks: Type.Optional(
@@ -70,8 +72,36 @@ const TodoParameters = Type.Object({
       },
     ),
   ),
+  updates: Type.Optional(
+    Type.Array(
+      Type.Object(
+        {
+          id: Type.Integer({
+            minimum: 1,
+            maximum: Number.MAX_SAFE_INTEGER,
+            description: "Task ID",
+          }),
+          status: Type.Optional(StringEnum(TODO_STATUSES, { description: "New Task status" })),
+          title: Type.Optional(Type.String({ description: "New Task title" })),
+          description: Type.Optional(
+            Type.Union([Type.String(), Type.Null()], {
+              description: "New Task description; null removes it",
+            }),
+          ),
+        },
+        { additionalProperties: false },
+      ),
+      {
+        minItems: 1,
+        description:
+          "Task changes to apply in one call, all or none, one per Task ID; use instead of id, title, description, and status",
+      },
+    ),
+  ),
   status: Type.Optional(
-    StringEnum(TODO_STATUSES, { description: "Task status; for add, applies to every new Task" }),
+    StringEnum(TODO_STATUSES, {
+      description: "Task status; for add, applies to every new Task; not allowed with updates",
+    }),
   ),
 });
 
@@ -218,6 +248,9 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
         const count = params.tasks.length;
         text += theme.fg("dim", ` ${formatTaskCount(count)}`);
       }
+      if (params.action === "update" && params.updates) {
+        text += theme.fg("dim", ` ${formatTaskCount(params.updates.length)}`);
+      }
       return new Text(text, 0, 0);
     },
     renderResult: (result, { expanded }, theme) => {
@@ -229,7 +262,8 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
         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 heading = `${action === "add" ? "Added " : ""}${formatTaskCount(tasks.length)}:`;
+        const verb = action === "add" ? "Added " : action === "update" ? "Updated " : "";
+        const heading = `${verb}${formatTaskCount(tasks.length)}:`;
         const lines = [theme.fg("muted", heading)];
         for (const task of visibleTasks) {
           lines.push(renderTodoTaskLine(task, theme));

package/src/todo-list.ts

@@ -38,6 +38,14 @@ export type TodoTaskDraft = {
   readonly description?: string;
 };
 
+/** One Task change within a batch `update`. */
+export type TodoTaskChange = {
+  readonly id: number;
+  readonly title?: string;
+  readonly description?: string | null;
+  readonly status?: TodoStatus;
+};
+
 /** Boundary input shared by the Todo tool's five operations. */
 export type TodoActionInput = {
   readonly action: TodoAction;
@@ -45,17 +53,18 @@ export type TodoActionInput = {
   readonly title?: string;
   readonly description?: string | null;
   readonly tasks?: readonly TodoTaskDraft[];
+  readonly updates?: readonly TodoTaskChange[];
   readonly status?: TodoStatus;
 };
 
 /**
  * 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`.
+ * `add` and `update`, 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`; likewise a batch `update` returns the Tasks it changed as `tasks`.
  */
 export type TodoToolDetails =
-  | { readonly action: "list" | "add"; readonly tasks: readonly TodoTask[] }
+  | { readonly action: "list" | "add" | "update"; readonly tasks: readonly TodoTask[] }
   | { readonly action: "add" | "update"; readonly task: TodoTask }
   | { readonly action: "remove"; readonly id: TodoTaskId }
   | { readonly action: "clear"; readonly cleared: number };
@@ -74,14 +83,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` (and, for
- * `add`, whether the request carried `tasks`) says which other field is present.
+ * `add` and `update`, whether the request carried `tasks` or `updates`) 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; add with tasks: the Tasks created, in ID order",
+        description:
+          "list: every Task in ID order; add with tasks: the Tasks created, in ID order; update with updates: the Tasks changed, in request order",
       }),
     ),
     task: Type.Optional(TodoTaskRecord),
@@ -201,7 +212,9 @@ function parseTodoDraft(
   return { title: trimmedTitle, description: trimmedDescription };
 }
 
-function isTodoActionResult(value: ParsedTodoDraft | TodoActionResult): value is TodoActionResult {
+function isTodoActionResult<T extends object>(
+  value: T | TodoActionResult,
+): value is TodoActionResult {
   return "ok" in value;
 }
 
@@ -258,6 +271,107 @@ function addTasks(
   };
 }
 
+/** Replaces each changed Task in place, keeping Task order and the next ID. */
+function replaceTasks(state: TodoStateSnapshot, changed: readonly TodoTask[]): TodoStateSnapshot {
+  const byId = new Map(changed.map((task) => [task.id, task]));
+  return {
+    nextId: state.nextId,
+    tasks: state.tasks.map((candidate) => byId.get(candidate.id) ?? candidate),
+  };
+}
+
+/** Applies one change to a Task; `path` (e.g. `updates[1]`) locates a batch entry in failures. */
+function changeTask(
+  task: TodoTask,
+  change: Pick<TodoTaskChange, "title" | "description" | "status">,
+  path: string | undefined,
+): TodoTask | TodoActionResult {
+  if (
+    change.title === undefined &&
+    change.description === undefined &&
+    change.status === undefined
+  ) {
+    return todoOperationFailure(
+      "update",
+      path === undefined
+        ? "Todo update failed: provide a title, description, or status"
+        : `Todo update failed: ${path} must provide a title, description, or status`,
+    );
+  }
+  const title = change.title === undefined ? task.title : change.title.trim();
+  if (!title) {
+    return todoOperationFailure(
+      "update",
+      `Todo update failed: ${path ? `${path}.` : ""}title must not be empty`,
+    );
+  }
+  const description =
+    change.description === undefined ? task.description : change.description?.trim();
+  if (change.description !== undefined && change.description !== null && !description) {
+    return todoOperationFailure(
+      "update",
+      `Todo update failed: ${path ? `${path}.` : ""}description must not be empty`,
+    );
+  }
+  return newTodoTask(task.id, title, description, change.status ?? task.status);
+}
+
+/** Validates every change before applying any, so a batch is all-or-nothing. */
+function updateTasks(
+  state: TodoStateSnapshot,
+  input: TodoActionInput & { readonly updates: readonly TodoTaskChange[] },
+): TodoActionResult {
+  // Models often send null for omitted fields; Pi strips those except where null is valid, so a
+  // null description here is treated as absent, as for a batch add.
+  if (
+    input.id !== undefined ||
+    input.title !== undefined ||
+    (input.description ?? undefined) !== undefined ||
+    input.status !== undefined
+  ) {
+    return todoOperationFailure(
+      "update",
+      "Todo update failed: provide either id and fields or updates, not both",
+    );
+  }
+  if (input.updates.length === 0) {
+    return todoOperationFailure("update", "Todo update failed: updates must not be empty");
+  }
+  const seen = new Map<number, number>();
+  const changed: TodoTask[] = [];
+  for (const [index, change] of input.updates.entries()) {
+    const path = `updates[${index}]`;
+    const id = parseTodoTaskId(change.id);
+    if (id === undefined) {
+      return todoOperationFailure(
+        "update",
+        `Todo update failed: ${path}.id must be a positive safe integer`,
+      );
+    }
+    const first = seen.get(id);
+    if (first !== undefined) {
+      return todoOperationFailure(
+        "update",
+        `Todo update failed: ${path}.id #${id} duplicates updates[${first}].id`,
+      );
+    }
+    seen.set(id, index);
+    const task = state.tasks.find((candidate) => candidate.id === id);
+    if (!task) {
+      return todoOperationFailure("update", `Todo update failed: ${path}.id #${id} was not found`);
+    }
+    const result = changeTask(task, change, path);
+    if (isTodoActionResult(result)) return result;
+    changed.push(result);
+  }
+  return {
+    ok: true,
+    state: replaceTasks(state, changed),
+    message: `Updated ${formatTaskCount(changed.length)}\n${formatTodoList(changed)}`,
+    details: { action: "update", tasks: changed },
+  };
+}
+
 /** Applies one validated-by-schema tool request without performing session or UI effects. */
 export function applyTodoAction(
   state: TodoStateSnapshot,
@@ -280,6 +394,9 @@ export function applyTodoAction(
     case "update":
     case "remove": {
       const action = input.action;
+      if (action === "update" && input.updates !== undefined) {
+        return updateTasks(state, { ...input, updates: input.updates });
+      }
       if (input.id === undefined) {
         return todoOperationFailure(action, `Todo ${action} failed: id is required`);
       }
@@ -308,38 +425,13 @@ export function applyTodoAction(
           details: { action: "remove", id: task.id },
         };
       }
-      if (
-        input.title === undefined &&
-        input.description === undefined &&
-        input.status === undefined
-      ) {
-        return todoOperationFailure(
-          "update",
-          "Todo update failed: provide a title, description, or status",
-        );
-      }
-      const title = input.title === undefined ? task.title : input.title.trim();
-      if (!title) {
-        return todoOperationFailure("update", "Todo update failed: title must not be empty");
-      }
-      const description =
-        input.description === undefined ? task.description : input.description?.trim();
-      if (input.description !== undefined && input.description !== null && !description) {
-        return todoOperationFailure("update", "Todo update failed: description must not be empty");
-      }
-      const updatedTask: TodoTask = description
-        ? { id: task.id, title, description, status: input.status ?? task.status }
-        : { id: task.id, title, status: input.status ?? task.status };
+      const changed = changeTask(task, input, undefined);
+      if (isTodoActionResult(changed)) return changed;
       return {
         ok: true,
-        state: {
-          nextId: state.nextId,
-          tasks: state.tasks.map((candidate) =>
-            candidate.id === updatedTask.id ? updatedTask : candidate,
-          ),
-        },
+        state: replaceTasks(state, [changed]),
         message: `Updated Task #${task.id}`,
-        details: { action: "update", task: updatedTask },
+        details: { action: "update", task: changed },
       };
     }