@ian-pascoe/pi-todo 0.3.0 → 0.5.0

package/README.md

@@ -16,13 +16,19 @@ 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                    |
+| `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:
 
@@ -30,6 +36,8 @@ 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.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [

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,
@@ -41,16 +42,67 @@ 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 or updates",
     }),
   ),
-  title: Type.Optional(Type.String({ description: "Task title for add or update" })),
   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 or updates",
+    }),
+  ),
+  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",
+      },
+    ),
+  ),
+  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; not allowed with updates",
     }),
   ),
-  status: Type.Optional(StringEnum(TODO_STATUSES)),
 });
 
 function restoreTodoState(context: ExtensionContext): TodoStateSnapshot {
@@ -192,6 +244,13 @@ 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)}`);
+      }
+      if (params.action === "update" && params.updates) {
+        text += theme.fg("dim", ` ${formatTaskCount(params.updates.length)}`);
+      }
       return new Text(text, 0, 0);
     },
     renderResult: (result, { expanded }, theme) => {
@@ -199,13 +258,13 @@ 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 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));
           if (expanded && task.description) {
@@ -244,7 +303,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-list.ts

@@ -32,21 +32,39 @@ export type TodoStateSnapshot = {
   readonly tasks: readonly TodoTask[];
 };
 
+/** One Task to create within a batch `add`. */
+export type TodoTaskDraft = {
+  readonly title: string;
+  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;
   readonly id?: number;
   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 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` 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"; 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 };
@@ -64,14 +82,18 @@ 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` 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" }),
+      Type.Array(TodoTaskRecord, {
+        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),
     id: Type.Optional(
@@ -157,6 +179,199 @@ 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<T extends object>(
+  value: T | 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 },
+  };
+}
+
+/** 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,
@@ -171,31 +386,17 @@ 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": {
       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`);
       }
@@ -224,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 },
       };
     }
 
@@ -264,7 +440,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 },
       };
     }