@pi9/todo 0.1.0

package/src/settings.ts

@@ -0,0 +1,160 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type TodoWidgetPlacement = "aboveEditor" | "belowEditor" | "off";
+export type TodoToolVisibility = "all" | "set-only" | "none";
+
+export interface TodoUiSettings {
+  widgetPlacement: TodoWidgetPlacement;
+  maxVisibleTasks: number;
+  fallbackGlyphs: boolean;
+  toolVisibility: TodoToolVisibility;
+}
+
+/** The portion of Pi's session context needed to load project-specific settings. */
+export interface TodoSettingsContext {
+  cwd: string;
+  isProjectTrusted(): boolean;
+}
+
+export interface TodoUiSettingsLoadResult {
+  settings: TodoUiSettings;
+  warning?: string;
+}
+
+export interface TodoUiSettingsStoreOptions {
+  globalSettingsPath?: string;
+  projectSettingsPath?: (cwd: string) => string;
+}
+
+export const DEFAULT_TODO_UI_SETTINGS: TodoUiSettings = {
+  widgetPlacement: "aboveEditor",
+  maxVisibleTasks: 5,
+  fallbackGlyphs: false,
+  toolVisibility: "set-only",
+};
+
+const WIDGET_PLACEMENTS = new Set<TodoWidgetPlacement>(["aboveEditor", "belowEditor", "off"]);
+const TOOL_VISIBILITIES = new Set<TodoToolVisibility>(["all", "set-only", "none"]);
+
+export function getTodoGlobalSettingsPath(): string {
+  return join(getAgentDir(), "todo", "settings.json");
+}
+
+export function getTodoProjectSettingsPath(cwd: string): string {
+  return join(cwd, CONFIG_DIR_NAME, "todo", "settings.json");
+}
+
+/**
+ * Loads global settings and, only for a trusted project, project-local overrides.
+ * Pass the event handler's `ctx` directly to `load` or `loadTodoUiSettings`.
+ */
+export class TodoUiSettingsStore {
+  private readonly globalSettingsPath: string;
+  private readonly projectSettingsPath: (cwd: string) => string;
+
+  constructor(options: TodoUiSettingsStoreOptions = {}) {
+    this.globalSettingsPath = options.globalSettingsPath ?? getTodoGlobalSettingsPath();
+    this.projectSettingsPath = options.projectSettingsPath ?? getTodoProjectSettingsPath;
+  }
+
+  async load(context?: TodoSettingsContext): Promise<TodoUiSettingsLoadResult> {
+    const settings = cloneDefaults();
+    const warnings: string[] = [];
+
+    await applyFile(this.globalSettingsPath, settings, warnings);
+
+    // Pi resolves trust before session handlers run. Never read project-controlled settings unless
+    // that resolved context says the project is trusted.
+    if (context && isTrusted(context)) {
+      await applyFile(this.projectSettingsPath(context.cwd), settings, warnings);
+    }
+
+    return { settings, ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}) };
+  }
+}
+
+/** Convenience API for loading settings from a Pi session/event context. */
+export async function loadTodoUiSettings(context?: TodoSettingsContext): Promise<TodoUiSettingsLoadResult> {
+  return new TodoUiSettingsStore().load(context);
+}
+
+/** Validates an object as a complete settings input, defaulting invalid or absent fields. */
+export function normalizeTodoUiSettings(value: unknown): TodoUiSettingsLoadResult {
+  const settings = cloneDefaults();
+  const warnings: string[] = [];
+  applySettings(value, settings, warnings);
+  return { settings, ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}) };
+}
+
+async function applyFile(path: string, settings: TodoUiSettings, warnings: string[]): Promise<void> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      warnings.push(`Could not read todo settings at ${path}; using available defaults.`);
+    }
+    return;
+  }
+
+  try {
+    applySettings(JSON.parse(raw) as unknown, settings, warnings);
+  } catch {
+    warnings.push(`Invalid todo settings at ${path}; using available defaults.`);
+  }
+}
+
+function applySettings(value: unknown, settings: TodoUiSettings, warnings: string[]): void {
+  if (!isRecord(value)) {
+    warnings.push("Invalid todo settings; using available defaults.");
+    return;
+  }
+
+  if (value.widgetPlacement !== undefined) {
+    if (WIDGET_PLACEMENTS.has(value.widgetPlacement as TodoWidgetPlacement)) {
+      settings.widgetPlacement = value.widgetPlacement as TodoWidgetPlacement;
+    } else {
+      warnings.push("Invalid todo widgetPlacement; ignoring value.");
+    }
+  }
+  if (value.maxVisibleTasks !== undefined) {
+    if (Number.isInteger(value.maxVisibleTasks) && (value.maxVisibleTasks as number) > 0) {
+      settings.maxVisibleTasks = value.maxVisibleTasks as number;
+    } else {
+      warnings.push("Invalid todo maxVisibleTasks; ignoring value.");
+    }
+  }
+  if (value.fallbackGlyphs !== undefined) {
+    if (typeof value.fallbackGlyphs === "boolean") {
+      settings.fallbackGlyphs = value.fallbackGlyphs;
+    } else {
+      warnings.push("Invalid todo fallbackGlyphs; ignoring value.");
+    }
+  }
+  if (value.toolVisibility !== undefined) {
+    if (TOOL_VISIBILITIES.has(value.toolVisibility as TodoToolVisibility)) {
+      settings.toolVisibility = value.toolVisibility as TodoToolVisibility;
+    } else {
+      warnings.push("Invalid todo toolVisibility; ignoring value.");
+    }
+  }
+}
+
+function cloneDefaults(): TodoUiSettings {
+  return { ...DEFAULT_TODO_UI_SETTINGS };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isTrusted(context: TodoSettingsContext): boolean {
+  try {
+    return context.isProjectTrusted();
+  } catch {
+    return false;
+  }
+}

package/src/state.ts

@@ -0,0 +1,203 @@
+import { TODO_ACTIONS, TODO_STATUSES, type TodoAction, type TodoPhase, type TodoPhaseInput, type TodoState, type TodoStatus, type TodoTransitionInput } from "./types.js";
+
+export function createTodoState(): TodoState {
+  return { phases: [] };
+}
+
+export function cloneTodoState(state: TodoState): TodoState {
+  return {
+    phases: state.phases.map((phase) => ({
+      name: phase.name,
+      tasks: phase.tasks.map((task) => ({ ...task })),
+    })),
+  };
+}
+
+/** Applies an action atomically without mutating the supplied state or action. */
+export function transitionTodoState(state: TodoState, action: TodoAction | unknown): TodoState {
+  assertState(state);
+  const input = record(action, "Todo action");
+  const actionName = input.action;
+  if (typeof actionName !== "string" || !(TODO_ACTIONS as readonly string[]).includes(actionName)) {
+    throw new Error(`Todo action must be one of: ${TODO_ACTIONS.join(", ")}.`);
+  }
+
+  const next = cloneTodoState(state);
+  switch (actionName) {
+    case "set":
+      assertOnlyFields(input, ["action", "phases"], "set");
+      next.phases = parsePhases(input.phases).map(newPhase);
+      break;
+    case "add":
+      assertOnlyFields(input, ["action", "phases"], "add");
+      addPhases(next, parsePhases(input.phases));
+      break;
+    case "transition":
+      assertOnlyFields(input, ["action", "transitions"], "transition");
+      applyTransitions(next, parseTransitions(input.transitions));
+      break;
+    case "view":
+      assertOnlyFields(input, ["action", "phase"], "view");
+      if (input.phase !== undefined) next.phases = [findPhase(next.phases, name(input.phase, "view phase"))];
+      break;
+  }
+
+  assertState(next);
+  return next;
+}
+
+export const applyTodoAction = transitionTodoState;
+
+function newPhase(input: TodoPhaseInput): TodoPhase {
+  return { name: input.name, tasks: input.tasks.map((task) => ({ name: task, status: "pending" })) };
+}
+
+function addPhases(state: TodoState, inputs: TodoPhaseInput[]): void {
+  if (!inputs.some((phase) => phase.tasks.length > 0)) {
+    throw new Error("add requires at least one task.");
+  }
+
+  for (const input of inputs) {
+    let phase = state.phases.find((candidate) => candidate.name === input.name);
+    if (!phase) {
+      phase = { name: input.name, tasks: [] };
+      state.phases.push(phase);
+    }
+    const names = new Set(phase.tasks.map((task) => task.name));
+    for (const task of input.tasks) {
+      if (names.has(task)) throw new Error(`Duplicate task name in phase ${input.name}: ${task}.`);
+      names.add(task);
+      phase.tasks.push({ name: task, status: "pending" });
+    }
+  }
+}
+
+function applyTransitions(state: TodoState, transitions: TodoTransitionInput[]): void {
+  if (transitions.length === 0) throw new Error("transition requires at least one status change.");
+  const addressed = new Set<string>();
+
+  for (const transition of transitions) {
+    const key = addressKey(transition.phase, transition.task);
+    if (addressed.has(key)) throw new Error(`Task may only be transitioned once per call: ${transition.phase} / ${transition.task}.`);
+    addressed.add(key);
+
+    const phase = state.phases.find((candidate) => candidate.name === transition.phase);
+    if (!phase) throw new Error(phaseNotFoundMessage(state.phases, transition.phase));
+    const task = phase.tasks.find((candidate) => candidate.name === transition.task);
+    if (!task) throw new Error(taskNotFoundMessage(phase, transition.task));
+    task.status = transition.status;
+  }
+}
+
+function parsePhases(value: unknown): TodoPhaseInput[] {
+  if (!Array.isArray(value)) throw new Error("phases must be an array.");
+  const phases = value.map((item, phaseIndex) => {
+    const input = record(item, `phases[${phaseIndex}]`);
+    assertOnlyFields(input, ["name", "tasks"], `phases[${phaseIndex}]`);
+    const phaseName = name(input.name, `phases[${phaseIndex}].name`);
+    if (!Array.isArray(input.tasks)) throw new Error(`phases[${phaseIndex}].tasks must be an array.`);
+    const tasks = input.tasks.map((task, taskIndex) => name(task, `phases[${phaseIndex}].tasks[${taskIndex}]`));
+    assertUnique(tasks, (task) => `Duplicate task name in phase ${phaseName}: ${task}.`);
+    return { name: phaseName, tasks };
+  });
+  assertUnique(phases.map((phase) => phase.name), (phase) => `Duplicate phase name: ${phase}.`);
+  return phases;
+}
+
+function parseTransitions(value: unknown): TodoTransitionInput[] {
+  if (!Array.isArray(value)) throw new Error("transitions must be an array.");
+  return value.map((item, index) => {
+    const input = record(item, `transitions[${index}]`);
+    assertOnlyFields(input, ["phase", "task", "status"], `transitions[${index}]`);
+    return {
+      phase: name(input.phase, `transitions[${index}].phase`),
+      task: name(input.task, `transitions[${index}].task`),
+      status: status(input.status, `transitions[${index}].status`),
+    };
+  });
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+  return value as Record<string, unknown>;
+}
+
+function name(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${label} must be a non-empty string.`);
+  if (value !== value.trim()) throw new Error(`${label} must not have leading or trailing whitespace.`);
+  return value;
+}
+
+function status(value: unknown, label: string): TodoStatus {
+  if (typeof value !== "string" || !(TODO_STATUSES as readonly string[]).includes(value)) {
+    throw new Error(`${label} must be one of: ${TODO_STATUSES.join(", ")}.`);
+  }
+  return value as TodoStatus;
+}
+
+function assertOnlyFields(input: Record<string, unknown>, allowed: string[], label: string): void {
+  const unexpected = Object.keys(input).find((key) => !allowed.includes(key));
+  if (unexpected) throw new Error(`${label} does not accept field: ${unexpected}.`);
+}
+
+function assertUnique(values: string[], message: (value: string) => string): void {
+  const seen = new Set<string>();
+  for (const value of values) {
+    if (seen.has(value)) throw new Error(message(value));
+    seen.add(value);
+  }
+}
+
+function findPhase(phases: TodoPhase[], phaseName: string): TodoPhase {
+  const phase = phases.find((candidate) => candidate.name === phaseName);
+  if (!phase) throw new Error(phaseNotFoundMessage(phases, phaseName));
+  return phase;
+}
+
+function phaseNotFoundMessage(phases: TodoPhase[], phaseName: string): string {
+  const names = phases.map((phase) => `- ${phase.name}`).join("\n");
+  return names ? `Phase not found: ${phaseName}.\n\nCurrent phases:\n${names}` : `Phase not found: ${phaseName}. The todo plan is empty.`;
+}
+
+function taskNotFoundMessage(phase: TodoPhase, taskName: string): string {
+  const names = phase.tasks.map((task) => `- ${task.name}`).join("\n");
+  return names
+    ? `Task not found: ${phase.name} / ${taskName}.\n\nCurrent tasks in ${phase.name}:\n${names}`
+    : `Task not found: ${phase.name} / ${taskName}. Phase ${phase.name} has no tasks.`;
+}
+
+export function todoAddressKey(phase: string, task: string): string {
+  return addressKey(phase, task);
+}
+
+function addressKey(phase: string, task: string): string {
+  return `${phase}\0${task}`;
+}
+
+function assertState(state: TodoState): void {
+  if (!state || typeof state !== "object" || !Array.isArray(state.phases)) throw new Error("Invalid todo state.");
+  const phaseNames = new Set<string>();
+  let activePhase: string | undefined;
+
+  for (const phase of state.phases) {
+    if (!phase || typeof phase !== "object" || !Array.isArray(phase.tasks)) throw new Error("Invalid todo state.");
+    const phaseName = name(phase.name, "phase name");
+    if (phaseNames.has(phaseName)) throw new Error("Invalid todo state: duplicate phase name.");
+    phaseNames.add(phaseName);
+
+    const taskNames = new Set<string>();
+    for (const task of phase.tasks) {
+      if (!task || typeof task !== "object") throw new Error("Invalid todo state.");
+      const taskName = name(task.name, "task name");
+      if (taskNames.has(taskName)) throw new Error("Invalid todo state: duplicate task name.");
+      if (!(TODO_STATUSES as readonly string[]).includes(task.status)) throw new Error("Invalid todo state.");
+      if (task.status === "in_progress") {
+        if (activePhase !== undefined && activePhase !== phaseName) {
+          throw new Error("Invalid todo state: in_progress tasks must all belong to one phase.");
+        }
+        activePhase = phaseName;
+      }
+      taskNames.add(taskName);
+    }
+  }
+}

package/src/tool-frame.ts

@@ -0,0 +1,136 @@
+import { Box, Text, type Component } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+export type TodoToolFrameState = "pending" | "success" | "error";
+export type TodoToolFrameContent = Component | string | readonly (Component | string)[] | null | undefined;
+export type TodoToolFrameTheme = Partial<Pick<Theme, "fg" | "bg" | "bold">>;
+
+export interface TodoToolFrameOptions {
+  title?: string;
+  action?: string;
+  state?: TodoToolFrameState;
+  content?: TodoToolFrameContent;
+  paddingX?: number;
+  paddingY?: number;
+  empty?: "hide" | "frame";
+}
+
+type FrameColor = Parameters<Theme["fg"]>[0];
+type FrameBackground = Parameters<Theme["bg"]>[0];
+
+type FrameStyle = {
+  state: FrameColor;
+  background: FrameBackground;
+  marker: string;
+};
+
+const FRAME_STYLES: Record<TodoToolFrameState, FrameStyle> = {
+  pending: {
+    state: "warning",
+    background: "toolPendingBg",
+    marker: "●",
+  },
+  success: {
+    state: "success",
+    background: "toolSuccessBg",
+    marker: "✓",
+  },
+  error: {
+    state: "error",
+    background: "toolErrorBg",
+    marker: "✗",
+  },
+};
+
+const DEFAULT_TITLE = "todo";
+
+export class TodoToolFrame implements Component {
+  constructor(
+    private readonly options: TodoToolFrameOptions,
+    private readonly theme?: TodoToolFrameTheme,
+  ) {}
+
+  invalidate(): void {
+    for (const entry of contentEntries(this.options.content)) {
+      if (typeof entry !== "string") entry.invalidate();
+    }
+  }
+
+  render(width: number): string[] {
+    const safeWidth = normalizeWidth(width);
+    const paddingX = normalizePadding(this.options.paddingX, 1);
+    const paddingY = normalizePadding(this.options.paddingY, 1);
+    const contentWidth = Math.max(1, safeWidth - paddingX * 2);
+    const content = this.options.content;
+    const hasContent = hasRenderableContent(content, contentWidth);
+
+    if (!hasContent && this.options.empty !== "frame") return [];
+
+    const state = this.options.state ?? "pending";
+    const style = FRAME_STYLES[state];
+    const boxPaddingX = Math.min(paddingX, Math.floor(safeWidth / 2));
+    const box = new Box(
+      boxPaddingX,
+      paddingY,
+      this.theme?.bg
+        ? (text: string) => this.theme!.bg!(style.background, text)
+        : undefined,
+    );
+
+    box.addChild(new Text(this.renderHeader(state, style), 0, 0));
+    if (hasContent) {
+      for (const entry of contentEntries(content)) {
+        box.addChild(typeof entry === "string"
+          ? new Text(this.paint("toolOutput", entry), 0, 0)
+          : entry);
+      }
+    }
+
+    return box.render(safeWidth);
+  }
+
+  private renderHeader(state: TodoToolFrameState, style: FrameStyle): string {
+    const title = normalizeLabel(this.options.title === undefined ? DEFAULT_TITLE : this.options.title);
+    const action = normalizeLabel(this.options.action);
+    const label = [title ? this.paint("toolTitle", this.bold(title)) : "", action ? this.paint("muted", action) : ""]
+      .filter(Boolean)
+      .join(" ");
+    const marker = this.paint(style.state, `${style.marker} ${state}`);
+    return [label, marker].filter(Boolean).join("  ");
+  }
+
+  private paint(color: FrameColor, text: string): string {
+    return this.theme?.fg ? this.theme.fg(color, text) : text;
+  }
+
+  private bold(text: string): string {
+    return this.theme?.bold ? this.theme.bold(text) : text;
+  }
+
+}
+
+function normalizeWidth(width: number): number {
+  return Math.max(1, Math.floor(width) || 1);
+}
+
+function normalizePadding(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(0, Math.floor(value));
+}
+
+function normalizeLabel(value: string | undefined): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function contentEntries(content: TodoToolFrameContent): readonly (Component | string)[] {
+  if (content === null || content === undefined) return [];
+  if (Array.isArray(content)) return content as readonly (Component | string)[];
+  return [content as Component | string];
+}
+
+function hasRenderableContent(content: TodoToolFrameContent, width: number): boolean {
+  return contentEntries(content).some((entry) => {
+    if (typeof entry === "string") return entry.trim().length > 0;
+    return entry.render(width).length > 0;
+  });
+}

package/src/tool.ts

@@ -0,0 +1,194 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, type Component } from "@earendil-works/pi-tui";
+import { formatTodoSummary } from "./format.js";
+import { restoreTodoState } from "./persistence.js";
+import { renderResult as renderTodoResult } from "./renderer.js";
+import { TodoToolFrame, type TodoToolFrameContent, type TodoToolFrameTheme } from "./tool-frame.js";
+import { TodoParamsSchema } from "./schema.js";
+import { DEFAULT_TODO_UI_SETTINGS, loadTodoUiSettings, type TodoUiSettings } from "./settings.js";
+import { createTodoState, todoAddressKey, transitionTodoState } from "./state.js";
+import { TODO_STATUSES, type TodoAction, type TodoAddress, type TodoState, type TodoToolDetails } from "./types.js";
+import { shouldRenderTodoAction } from "./visibility.js";
+import { updateTodoWidget } from "./widget.js";
+
+function taskStatuses(state: TodoState): Map<string, string> {
+  return new Map(state.phases.flatMap((phase) => phase.tasks.map((task) => [todoAddressKey(phase.name, task.name), task.status])));
+}
+
+function taskAddresses(state: TodoState): Map<string, TodoAddress> {
+  return new Map(state.phases.flatMap((phase) => phase.tasks.map((task) => {
+    const address = { phase: phase.name, task: task.name };
+    return [todoAddressKey(address.phase, address.task), address];
+  })));
+}
+
+function changedTasks(previous: TodoState, next: TodoState): TodoAddress[] {
+  const before = taskStatuses(previous);
+  const after = taskStatuses(next);
+  const addresses = taskAddresses(next);
+  return [...after.keys()].filter((key) => before.get(key) !== after.get(key)).map((key) => addresses.get(key)!);
+}
+
+function completedTasks(previous: TodoState, next: TodoState): TodoAddress[] {
+  const before = taskStatuses(previous);
+  return next.phases.flatMap((phase) => phase.tasks
+    .filter((task) => task.status === "completed" && before.has(todoAddressKey(phase.name, task.name)) && before.get(todoAddressKey(phase.name, task.name)) !== "completed")
+    .map((task) => ({ phase: phase.name, task: task.name })));
+}
+
+function createTodoFrame(
+  state: "pending" | "success" | "error",
+  action: string | undefined,
+  content: TodoToolFrameContent,
+  theme: TodoToolFrameTheme,
+): TodoToolFrame {
+  return new TodoToolFrame({
+    title: "todo",
+    action,
+    state,
+    content,
+    empty: "frame",
+  }, theme);
+}
+
+type TodoRenderInput = {
+  details?: TodoToolDetails;
+  content?: readonly { type?: string; text?: string }[];
+};
+type TodoRenderTheme = Parameters<typeof renderTodoResult>[2];
+type TrackedSetRenderer = { toolCallId: string; invalidate?: () => void };
+
+/** Expanded content for the one set result that is allowed to follow in-memory state. */
+class LiveSetResult implements Component {
+  constructor(
+    private readonly result: TodoRenderInput,
+    private readonly getState: () => TodoState,
+    private readonly isCurrent: () => boolean,
+    private readonly theme: TodoRenderTheme,
+    private readonly fallbackGlyphs: boolean,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const details = this.result.details;
+    const liveResult: TodoRenderInput = !this.isCurrent() || !details
+      ? this.result
+      : { ...this.result, details: { ...details, state: this.getState(), changedTasks: [] } };
+    return renderTodoResult(liveResult, { expanded: true }, this.theme, { fallbackGlyphs: this.fallbackGlyphs }).render(width);
+  }
+}
+
+export function registerTodoTool(pi: ExtensionAPI): void {
+  let state = createTodoState();
+  let settings: TodoUiSettings = { ...DEFAULT_TODO_UI_SETTINGS };
+  let queue: Promise<void> = Promise.resolve();
+  let latestSetRenderer: TrackedSetRenderer | undefined;
+
+  const invalidateLatestSetRenderer = (): void => {
+    latestSetRenderer?.invalidate?.();
+  };
+
+  const restore = (ctx: ExtensionContext): void => {
+    state = restoreTodoState(ctx);
+    invalidateLatestSetRenderer();
+    updateTodoWidget(ctx, state, settings);
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    const loaded = await loadTodoUiSettings(ctx);
+    settings = loaded.settings;
+    if (loaded.warning) ctx.ui.notify(loaded.warning, "warning");
+    restore(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => restore(ctx));
+
+  pi.registerTool({
+    name: "todo",
+    label: "Todo",
+    description: [
+      "Maintain a concise phased plan that reflects both intended work and current execution progress.",
+      "Actions:",
+      "  set: Replace the entire plan. All tasks reset to pending. Use only for a new plan or full re-plan.",
+      "  add: Append tasks or phases without touching existing work.",
+      "  transition: Update task statuses (" + TODO_STATUSES.join(", ") + ") by exact phase and task name.",
+      "  view: Return the plan, optionally filtered to one phase.",
+    ].join("\n"),
+    promptSnippet: "Track multi-step work with the todo tool; keep statuses current as you go",
+    promptGuidelines: [
+      "Use todo for non-trivial work with three or more distinct steps; skip todo for simple tasks.",
+      "Transition todo statuses immediately and honestly—mark tasks completed only when fully done, not merely attempted, and cancel abandoned tasks rather than leaving them pending.",
+      "Todo tasks in_progress must all belong to a single phase; finish or cancel a phase's active tasks before starting the next.",
+    ],
+    parameters: TodoParamsSchema,
+    renderShell: "self",
+
+    execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const run = queue.then(() => {
+        const previous = state;
+        const next = transitionTodoState(previous, params as TodoAction);
+        const details: TodoToolDetails = {
+          action: params.action,
+          state: next,
+          changedTasks: params.action === "view"
+            ? []
+            : params.action === "set"
+              ? [...taskAddresses(next).values()]
+              : changedTasks(previous, next),
+          completedTasks: params.action === "transition" ? completedTasks(previous, next) : [],
+        };
+        if (params.action !== "view") {
+          state = next;
+          invalidateLatestSetRenderer();
+        }
+        updateTodoWidget(ctx, state, settings);
+        return {
+          content: [{ type: "text" as const, text: formatTodoSummary(next) }],
+          details,
+        };
+      });
+      queue = run.then(() => undefined, () => undefined);
+      return run;
+    },
+
+    renderCall(args, theme, context) {
+      // The self shell replaces the call with the final result once execution settles. Keeping
+      // this slot empty after completion also prevents a visible call and result frame at once.
+      if (!context.isPartial || context.isError || !shouldRenderTodoAction(args.action, settings.toolVisibility)) {
+        return new Container();
+      }
+      return createTodoFrame("pending", args.action, undefined, theme);
+    },
+
+    renderResult(result, options, theme, context) {
+      const details = result.details as TodoToolDetails | undefined;
+      const action = details?.action ?? context.args.action;
+      if (!context.isError && !shouldRenderTodoAction(action, settings.toolVisibility)) return new Container();
+
+      const isSetResult = !context.isError && details?.action === "set";
+      if (isSetResult) {
+        if (!latestSetRenderer || latestSetRenderer.toolCallId !== context.toolCallId) {
+          latestSetRenderer = { toolCallId: context.toolCallId, invalidate: context.invalidate };
+        } else {
+          latestSetRenderer.invalidate = context.invalidate;
+        }
+      }
+
+      // Partial updates are represented by the pending call frame. This keeps streaming updates
+      // from briefly rendering two self-owned frames in one tool row.
+      if ((options.isPartial || context.isPartial) && !context.isError) return new Container();
+
+      const renderInput = result as TodoRenderInput;
+      const content = isSetResult && options.expanded
+        ? new LiveSetResult(
+          renderInput,
+          () => state,
+          () => latestSetRenderer?.toolCallId === context.toolCallId,
+          theme,
+          settings.fallbackGlyphs,
+        )
+        : renderTodoResult(renderInput, options, theme, { fallbackGlyphs: settings.fallbackGlyphs });
+      return createTodoFrame(context.isError ? "error" : "success", action, content, theme);
+    },
+  });
+}