@ian-pascoe/pi-todo 0.4.0 → 0.6.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.99.0`.
+Requires Node `>=22.19.0` and Pi `>=1.1.0`.
 
 ## Install
 
@@ -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.6.0",
   "private": false,
   "description": "Minimal session-native Todo List for Pi agents.",
   "keywords": [
@@ -32,10 +32,13 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "@ian-pascoe/pi-utils": "^0.5.0"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.99.0",
-    "@earendil-works/pi-coding-agent": ">=0.99.0",
-    "@earendil-works/pi-tui": ">=0.99.0",
+    "@earendil-works/pi-ai": ">=1.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
     "typebox": "*"
   },
   "engines": {

package/src/pi-todo-extension.ts

@@ -1,6 +1,7 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { type Component } from "@earendil-works/pi-tui";
+import { noticeText } from "@ian-pascoe/pi-utils/ui";
 import { Type } from "typebox";
 import { projectTodoContext, todoStateFromEntry } from "./todo-context.js";
 import {
@@ -10,14 +11,13 @@ import {
   TODO_ACTIONS,
   TODO_STATUSES,
   TodoToolOutputSchema,
-  todoStatusMarker,
   type TodoActionInput,
   type TodoStateSnapshot,
-  type TodoStatus,
   type TodoTask,
   TodoOperationError,
   type TodoToolDetails,
 } from "./todo-list.js";
+import { renderTodoCall, renderTodoResult, renderTodoWidget } from "./todo-render.js";
 import { TROUBLESHOOTING_HINT } from "./troubleshooting-skill.js";
 
 const TODO_STATE_ENTRY_TYPE = "pi-todo-state";
@@ -33,8 +33,6 @@ function assertTodoJournalReadable(context: ExtensionContext): void {
   }
 }
 const TODO_WIDGET_ID = "pi-todo";
-const TODO_WIDGET_STATUS_ORDER: readonly TodoStatus[] = ["active", "pending", "completed"];
-const TODO_COLLAPSED_TASK_LIMIT = 5;
 
 const TodoParameters = Type.Object({
   action: StringEnum(TODO_ACTIONS),
@@ -42,16 +40,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 +70,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",
+    }),
   ),
 });
 
@@ -83,19 +111,6 @@ function restoreTodoState(context: ExtensionContext): TodoStateSnapshot {
   return createEmptyTodoState();
 }
 
-function renderTodoTaskLine(task: TodoTask, theme: Theme): string {
-  const markerColor =
-    task.status === "active" ? "accent" : task.status === "completed" ? "success" : "muted";
-  const title =
-    task.status === "active"
-      ? theme.bold(task.title)
-      : task.status === "completed"
-        ? theme.strikethrough(task.title)
-        : task.title;
-  const titleColor = task.status === "completed" ? "dim" : "text";
-  return `${theme.fg(markerColor, todoStatusMarker(task.status))} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(titleColor, title)}`;
-}
-
 class TodoWidget implements Component {
   constructor(
     private readonly tasks: readonly TodoTask[],
@@ -105,25 +120,7 @@ class TodoWidget implements Component {
   invalidate(): void {}
 
   render(width: number): string[] {
-    const active = this.tasks.filter((task) => task.status === "active").length;
-    const pending = this.tasks.filter((task) => task.status === "pending").length;
-    const completed = this.tasks.length - active - pending;
-    const header =
-      this.theme.fg("toolTitle", this.theme.bold("TODO")) +
-      this.theme.fg("muted", `  ${active} active · ${pending} pending · ${completed} completed`);
-    const orderedTasks = this.tasks.toSorted((left, right) => {
-      const statusDifference =
-        TODO_WIDGET_STATUS_ORDER.indexOf(left.status) -
-        TODO_WIDGET_STATUS_ORDER.indexOf(right.status);
-      return statusDifference === 0 ? left.id - right.id : statusDifference;
-    });
-    const lines = [header];
-    for (const task of orderedTasks.slice(0, TODO_COLLAPSED_TASK_LIMIT)) {
-      lines.push(renderTodoTaskLine(task, this.theme));
-    }
-    const remaining = orderedTasks.length - TODO_COLLAPSED_TASK_LIMIT;
-    if (remaining > 0) lines.push(this.theme.fg("dim", `… ${remaining} more`));
-    return lines.map((line) => truncateToWidth(line, width, "…"));
+    return renderTodoWidget(this.tasks, this.theme, width);
   }
 }
 
@@ -210,41 +207,9 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
         structuredContent: structuredClone(result.details),
       };
     },
-    renderCall: (params, theme) => {
-      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) => {
-      const text = result.content.find((item) => item.type === "text");
-      if (!result.details) {
-        return new Text(theme.fg("error", text?.text ?? "Todo operation failed"), 0, 0);
-      }
-      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 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) {
-            lines.push(
-              ...task.description.split("\n").map((line) => theme.fg("dim", `    ${line}`)),
-            );
-          }
-        }
-        const remaining = tasks.length - visibleTasks.length;
-        if (remaining > 0) lines.push(theme.fg("dim", `… ${remaining} more`));
-        return new Text(lines.join("\n"), 0, 0);
-      }
-      return new Text(theme.fg("success", "✓ ") + theme.fg("muted", text?.text ?? "Done"), 0, 0);
-    },
+    renderCall: (params, theme, context) => renderTodoCall(params, theme, context),
+    renderResult: (result, options, theme, context) =>
+      renderTodoResult(result, options, theme, context),
   });
 
   pi.registerCommand("todo", {
@@ -259,7 +224,7 @@ export default function piTodoExtension(pi: ExtensionAPI): void {
         return;
       }
       if (context.mode !== "tui") {
-        context.ui.notify("/todo clear requires interactive mode", "error");
+        context.ui.notify(noticeText("Todo", "/todo clear requires interactive mode"), "error");
         return;
       }
       await context.waitForIdle();

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 },
       };
     }
 

package/src/todo-render.ts

@@ -0,0 +1,153 @@
+import type { AgentToolResult, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { type Component, Container, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import {
+  appendDurationFooter,
+  callDurationFooter,
+  COLLAPSED_LINES,
+  type DurationContext,
+  expandHint,
+  previewBody,
+  SEPARATOR,
+  toolHeader,
+  type UiTheme,
+  widgetLines,
+} from "@ian-pascoe/pi-utils/ui";
+import {
+  formatTaskCount,
+  type TodoActionInput,
+  type TodoTask,
+  type TodoToolDetails,
+} from "./todo-list.js";
+
+/** The theme methods the Todo renderers draw with. */
+export type TodoRenderTheme = Pick<UiTheme, "fg" | "bold" | "strikethrough">;
+
+const TODO_WIDGET_STATUS_ORDER: readonly TodoTask["status"][] = ["active", "pending", "completed"];
+
+const CHECKBOX_FILL = { pending: " ", active: ">", completed: "x" } as const;
+const CHECKBOX_COLOR = { pending: "muted", active: "accent", completed: "success" } as const;
+
+/**
+ * One Task row. The `[ ]`/`[>]`/`[x]` checkbox is the documented exception to the no-marks rule
+ * for tool rows: it shows the Task's state, not the tool's outcome.
+ */
+export function renderTodoTaskLine(task: TodoTask, theme: TodoRenderTheme): string {
+  const box =
+    theme.fg("dim", "[") +
+    theme.fg(CHECKBOX_COLOR[task.status], CHECKBOX_FILL[task.status]) +
+    theme.fg("dim", "]");
+  const title =
+    task.status === "active"
+      ? theme.bold(task.title)
+      : task.status === "completed"
+        ? theme.strikethrough(task.title)
+        : task.title;
+  const titleColor = task.status === "completed" ? "dim" : "text";
+  return `${box} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(titleColor, title)}`;
+}
+
+/** The Todo Widget lines: Active Tasks first, then pending, then completed, in at most 10 lines. */
+export function renderTodoWidget(
+  tasks: readonly TodoTask[],
+  theme: TodoRenderTheme,
+  width: number,
+): string[] {
+  const active = tasks.filter((task) => task.status === "active").length;
+  const pending = tasks.filter((task) => task.status === "pending").length;
+  const completed = tasks.length - active - pending;
+  const orderedTasks = tasks.toSorted((left, right) => {
+    const statusDifference =
+      TODO_WIDGET_STATUS_ORDER.indexOf(left.status) -
+      TODO_WIDGET_STATUS_ORDER.indexOf(right.status);
+    return statusDifference === 0 ? left.id - right.id : statusDifference;
+  });
+  return widgetLines(theme, {
+    title: "Todo",
+    counts: [`${active} active`, `${pending} pending`, `${completed} completed`].join(SEPARATOR),
+    rows: orderedTasks.map((task) => renderTodoTaskLine(task, theme)),
+  }).map((line) => truncateToWidth(line, width, "..."));
+}
+
+function callArguments(params: TodoActionInput): string | undefined {
+  const parts: string[] = [];
+  if (params.id !== undefined) parts.push(`#${params.id}`);
+  if (params.action === "add" && params.title) parts.push(`"${params.title}"`);
+  if (params.action === "add" && params.tasks) parts.push(formatTaskCount(params.tasks.length));
+  if (params.action === "update" && params.updates) {
+    parts.push(formatTaskCount(params.updates.length));
+  }
+  return parts.length === 0 ? undefined : parts.join(" ");
+}
+
+/** The `todo` call row: bold `todo`, the action in `accent`, arguments in `muted`, then `Elapsed`. */
+export function renderTodoCall(
+  params: TodoActionInput,
+  theme: TodoRenderTheme,
+  context: DurationContext,
+): Component {
+  const container = new Container();
+  container.addChild(
+    new Text(toolHeader(theme, "todo", params.action, callArguments(params)), 0, 0),
+  );
+  container.addChild(callDurationFooter(theme, context));
+  return container;
+}
+
+function taskListLines(
+  action: "list" | "add" | "update",
+  tasks: readonly TodoTask[],
+  theme: TodoRenderTheme,
+  expanded: boolean,
+): string[] {
+  const verb = action === "add" ? "Added " : action === "update" ? "Updated " : "";
+  const lines = [theme.fg("muted", `${verb}${formatTaskCount(tasks.length)}:`)];
+  if (expanded) {
+    for (const task of tasks) {
+      lines.push(renderTodoTaskLine(task, theme));
+      if (task.description) {
+        lines.push(...task.description.split("\n").map((line) => theme.fg("dim", `    ${line}`)));
+      }
+    }
+    return lines;
+  }
+  lines.push(
+    ...tasks.slice(0, COLLAPSED_LINES.list).map((task) => renderTodoTaskLine(task, theme)),
+  );
+  const hidden = tasks.length - COLLAPSED_LINES.list;
+  if (hidden > 0) lines.push(expandHint(theme, hidden));
+  return lines;
+}
+
+/**
+ * The `todo` result row. A Task list is the Nearest Built-in `ls` (20 rows collapsed, Pi's Expand
+ * Hint beyond that); a failure shows its text in `error`. Every result ends with `Took`.
+ */
+export function renderTodoResult(
+  result: AgentToolResult<TodoToolDetails | undefined>,
+  options: ToolRenderResultOptions,
+  theme: TodoRenderTheme,
+  context: DurationContext,
+): Component {
+  const text = result.content.find((item) => item.type === "text")?.text;
+  let body: string[];
+  if (!result.details) {
+    body = previewBody(theme, (text ?? "Todo operation failed").split("\n"), {
+      limit: COLLAPSED_LINES.fallback,
+      expanded: options.expanded,
+      color: "error",
+    });
+  } else if ("tasks" in result.details && result.details.tasks.length > 0) {
+    body = taskListLines(result.details.action, result.details.tasks, theme, options.expanded);
+  } else {
+    const message = "tasks" in result.details ? "Todo List is empty" : (text ?? "Done");
+    body = previewBody(theme, message.split("\n"), {
+      limit: COLLAPSED_LINES.fallback,
+      expanded: options.expanded,
+    });
+  }
+  const container = new Container();
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(body.join("\n"), 0, 0));
+  appendDurationFooter(container, theme, context, { isPartial: options.isPartial });
+  return container;
+}