@ian-pascoe/pi-todo 0.3.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,6 +33,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                |
 | `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.4.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,
@@ -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-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 },
       };
     }