@ian-pascoe/pi-todo 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2026 Ian Pascoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# Pi Todo
+
+`@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.84.1`.
+
+## Install
+
+```bash
+pi install npm:@ian-pascoe/pi-todo
+# or from this checkout
+pi -e ./src/index.ts
+```
+
+## Tool
+
+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 |
+
+Task status is `pending`, `active`, or `completed`; `add` defaults to `pending`. Tasks are flat, duplicate titles are allowed, and multiple Tasks may be active. Set `description` to `null` during `update` to remove it.
+
+The extension appends the current Todo List as hidden tail context before each model request. It does not modify the system prompt or tool description as the list changes, preserving the cacheable prompt prefix.
+
+## UI and persistence
+
+In interactive mode, a compact widget above the editor shows status counts and up to five Tasks. Tool calls and results use custom transcript rendering. `/todo clear` confirms before manually clearing the list.
+
+State is stored only in Pi session entries. It follows the active session branch and survives reloads, restarts, and compaction. The package has no settings or external state.
+
+This is privileged extension code: review it before installing it into an agent that can access local files, tools, or credentials.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ian-pascoe/pi-todo",
+  "version": "0.0.0",
+  "private": false,
+  "description": "Minimal session-native Todo List for Pi agents.",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "tasks",
+    "todo"
+  ],
+  "homepage": "https://github.com/ian-pascoe/pi-extensions/tree/main/packages/pi-todo",
+  "bugs": {
+    "url": "https://github.com/ian-pascoe/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Ian Pascoe <ian.g.pascoe@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ian-pascoe/pi-extensions.git",
+    "directory": "packages/pi-todo"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/pi-todo/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: pi-todo
+description: Diagnose Pi Todo when its tool, restored Todo List, model context, clear command, transcript rendering, or widget is missing or incorrect.
+license: MIT
+---
+
+# Pi Todo
+
+1. Read [`../../README.md`](../../README.md) for the expected tool, persistence, context, command, and widget behavior.
+2. Call `todo` with `action: "list"`; classify a missing tool as an extension-loading failure.
+3. Add one temporary Task, reload Pi, and list again. If it disappears, inspect the active branch for `pi-todo-state` custom entries.
+4. Compare the latest valid state entry with the model's hidden Todo List context and the interactive widget, then remove the temporary Task.
+5. Test `/todo clear` only after preserving any Tasks the user still needs.
+6. Treat the extension as configuration-free. Finish when tool state, active-branch restoration, model context, and interactive UI agree, or one named load, session, mode, or corrupted-entry boundary explains the mismatch.

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./pi-todo-extension.js";

package/src/pi-todo-extension.ts

@@ -0,0 +1,228 @@
+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 } from "typebox";
+import { Value } from "typebox/value";
+import {
+  applyTodoAction,
+  createEmptyTodoState,
+  formatTodoList,
+  parseTodoStateSnapshot,
+  TODO_ACTIONS,
+  TODO_STATUSES,
+  TodoStateRecord,
+  todoStatusMarker,
+  type TodoActionInput,
+  type TodoStateSnapshot,
+  type TodoStatus,
+  type TodoTask,
+  type TodoToolDetails,
+} from "./todo-list.js";
+
+const TODO_STATE_ENTRY_TYPE = "pi-todo-state";
+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),
+  id: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: Number.MAX_SAFE_INTEGER,
+      description: "Task ID for update or remove",
+    }),
+  ),
+  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",
+    }),
+  ),
+  status: Type.Optional(StringEnum(TODO_STATUSES)),
+});
+
+function restoreTodoState(context: ExtensionContext): TodoStateSnapshot {
+  for (const entry of context.sessionManager.getBranch().toReversed()) {
+    if (
+      entry.type !== "custom" ||
+      entry.customType !== TODO_STATE_ENTRY_TYPE ||
+      !Value.Check(TodoStateRecord, entry.data)
+    ) {
+      continue;
+    }
+    const snapshot = parseTodoStateSnapshot(entry.data);
+    if (snapshot) return snapshot;
+  }
+  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[],
+    private readonly theme: Theme,
+  ) {}
+
+  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, "…"));
+  }
+}
+
+/** Installs the session-native Todo List tool into Pi. */
+export default function piTodoExtension(pi: ExtensionAPI): void {
+  let state = createEmptyTodoState();
+
+  const updateTodoWidget = (context: ExtensionContext): void => {
+    if (context.mode !== "tui") return;
+    context.ui.setWidget(
+      TODO_WIDGET_ID,
+      state.tasks.length === 0 ? undefined : (_tui, theme) => new TodoWidget(state.tasks, theme),
+    );
+  };
+  const commitTodoState = (snapshot: TodoStateSnapshot, context: ExtensionContext): void => {
+    state = snapshot;
+    pi.appendEntry(TODO_STATE_ENTRY_TYPE, state);
+    updateTodoWidget(context);
+  };
+  const runTodoAction = (input: TodoActionInput, context: ExtensionContext) => {
+    const result = applyTodoAction(state, input);
+    if (!result.ok) throw result.error;
+    if (result.changed) commitTodoState(result.state, context);
+    return result;
+  };
+  const restoreState = (context: ExtensionContext): void => {
+    state = restoreTodoState(context);
+    updateTodoWidget(context);
+  };
+  pi.on("session_start", (_event, context) => restoreState(context));
+  pi.on("session_tree", (_event, context) => restoreState(context));
+  pi.on("context", (event) => {
+    if (state.tasks.length === 0) return;
+    const todoListMessage = {
+      role: "custom",
+      customType: "pi-todo-context",
+      content: `Todo List:\n${formatTodoList(state.tasks)}`,
+      display: false,
+      timestamp: 0,
+    } as const;
+    return { messages: [...event.messages, todoListMessage] };
+  });
+
+  pi.registerTool<typeof TodoParameters, TodoToolDetails | undefined>({
+    name: "todo",
+    label: "Todo",
+    description: "Manage the current session branch's Todo List.",
+    parameters: TodoParameters,
+    executionMode: "sequential",
+    async execute(_toolCallId, params, _signal, _onUpdate, context) {
+      const result = runTodoAction(params, context);
+      return {
+        content: [{ type: "text", text: result.message }],
+        details: 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}"`);
+      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?.type === "text" ? text.text : "Todo operation failed"),
+          0,
+          0,
+        );
+      }
+      if (result.details.action === "list") {
+        const tasks = result.details.tasks;
+        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"}:`),
+        ];
+        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?.type === "text" ? text.text : "Done"),
+        0,
+        0,
+      );
+    },
+  });
+
+  pi.registerCommand("todo", {
+    description: "Manage the Todo List",
+    getArgumentCompletions: (argumentPrefix) =>
+      "clear".startsWith(argumentPrefix.trim())
+        ? [{ value: "clear", label: "clear", description: "Clear the Todo List" }]
+        : null,
+    handler: async (args, context) => {
+      if (args.trim() !== "clear") {
+        context.ui.notify("Usage: /todo clear", "info");
+        return;
+      }
+      if (context.mode !== "tui") {
+        context.ui.notify("/todo clear requires interactive mode", "error");
+        return;
+      }
+      await context.waitForIdle();
+      if (state.tasks.length === 0) {
+        context.ui.notify("Todo List is already empty", "info");
+        return;
+      }
+      const confirmed = await context.ui.confirm(
+        "Clear Todo List",
+        `Remove all ${state.tasks.length} ${state.tasks.length === 1 ? "Task" : "Tasks"}?`,
+      );
+      if (!confirmed) return;
+      const result = runTodoAction({ action: "clear" }, context);
+      context.ui.notify(result.message, "info");
+    },
+  });
+}

package/src/todo-list.ts

@@ -0,0 +1,291 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+/** Agent-visible Todo List operations. */
+export const TODO_ACTIONS = ["list", "add", "update", "remove", "clear"] as const;
+
+/** Unconstrained Task lifecycle states. */
+export const TODO_STATUSES = ["pending", "active", "completed"] as const;
+
+/** One operation accepted by the Todo List. */
+export type TodoAction = (typeof TODO_ACTIONS)[number];
+
+/** One Task lifecycle state. */
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+
+declare const todoTaskIdBrand: unique symbol;
+
+/** Stable numeric identity for a Task while it exists. */
+export type TodoTaskId = number & { readonly [todoTaskIdBrand]: true };
+
+/** One flat unit of work in the Todo List. */
+export type TodoTask = {
+  readonly id: TodoTaskId;
+  readonly title: string;
+  readonly description?: string;
+  readonly status: TodoStatus;
+};
+
+/** Complete session-persisted Todo List state. */
+export type TodoStateSnapshot = {
+  readonly nextId: number;
+  readonly tasks: readonly TodoTask[];
+};
+
+/** 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 status?: TodoStatus;
+};
+
+/** Render details whose action discriminates list data from mutation acknowledgements. */
+export type TodoToolDetails =
+  | { readonly action: "list"; readonly tasks: readonly TodoTask[] }
+  | { readonly action: Exclude<TodoAction, "list"> };
+
+const PositiveSafeIntegerRecord = Type.Integer({
+  minimum: 1,
+  maximum: Number.MAX_SAFE_INTEGER,
+});
+const TodoTaskRecord = Type.Object({
+  id: PositiveSafeIntegerRecord,
+  title: Type.String({ minLength: 1 }),
+  description: Type.Optional(Type.String({ minLength: 1 })),
+  status: StringEnum(TODO_STATUSES),
+});
+
+/** Serialized shape stored in a `pi-todo-state` session entry. */
+export const TodoStateRecord = Type.Object({
+  nextId: PositiveSafeIntegerRecord,
+  tasks: Type.Array(TodoTaskRecord),
+});
+
+/** Expected Task-operation failure translated to a Pi tool error at the extension boundary. */
+export class TodoOperationError extends Error {
+  readonly _tag = "TodoOperationError" as const;
+
+  constructor(
+    readonly action: TodoAction,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Pure outcome of applying one Todo List operation. */
+export type TodoActionResult =
+  | {
+      readonly ok: true;
+      readonly changed: boolean;
+      readonly state: TodoStateSnapshot;
+      readonly message: string;
+      readonly details: TodoToolDetails;
+    }
+  | { readonly ok: false; readonly error: TodoOperationError };
+
+function parseTodoTaskId(value: number): TodoTaskId | undefined {
+  if (!Number.isSafeInteger(value) || value < 1) return undefined;
+  // SAFETY: The checks above establish the positive safe-integer Task ID invariant.
+  return value as TodoTaskId;
+}
+
+/** Creates an empty Todo List whose first Task receives ID 1. */
+export function createEmptyTodoState(): TodoStateSnapshot {
+  return { nextId: 1, tasks: [] };
+}
+
+/** Parses a structurally checked session record into ordered, immutable Todo List state. */
+export function parseTodoStateSnapshot(
+  input: Static<typeof TodoStateRecord>,
+): TodoStateSnapshot | undefined {
+  let previousId = 0;
+  const tasks: TodoTask[] = [];
+  for (const task of input.tasks) {
+    const id = parseTodoTaskId(task.id);
+    if (
+      id === undefined ||
+      id <= previousId ||
+      task.title.trim() !== task.title ||
+      (task.description !== undefined && task.description.trim() !== task.description)
+    ) {
+      return undefined;
+    }
+    tasks.push(
+      task.description === undefined
+        ? { id, title: task.title, status: task.status }
+        : { id, title: task.title, description: task.description, status: task.status },
+    );
+    previousId = id;
+  }
+  return input.nextId > previousId ? { nextId: input.nextId, tasks } : undefined;
+}
+
+function todoOperationFailure(action: TodoAction, message: string): TodoActionResult {
+  return { ok: false, error: new TodoOperationError(action, message) };
+}
+
+/** Applies one validated-by-schema tool request without performing session or UI effects. */
+export function applyTodoAction(
+  state: TodoStateSnapshot,
+  input: TodoActionInput,
+): TodoActionResult {
+  switch (input.action) {
+    case "list":
+      return {
+        ok: true,
+        changed: false,
+        state,
+        message: formatTodoList(state.tasks),
+        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,
+        changed: true,
+        state: { nextId: state.nextId + 1, tasks: [...state.tasks, task] },
+        message: `Added Task #${task.id}`,
+        details: { action: "add" },
+      };
+    }
+
+    case "update": {
+      if (input.id === undefined) {
+        return todoOperationFailure("update", "Todo update failed: id is required");
+      }
+      const id = parseTodoTaskId(input.id);
+      if (id === undefined) {
+        return todoOperationFailure(
+          "update",
+          "Todo update failed: id must be a positive safe integer",
+        );
+      }
+      const task = state.tasks.find((candidate) => candidate.id === id);
+      if (!task) {
+        return todoOperationFailure(
+          "update",
+          `Todo update failed: Task #${input.id} was not found`,
+        );
+      }
+      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 === null
+            ? undefined
+            : 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 };
+      return {
+        ok: true,
+        changed: true,
+        state: {
+          nextId: state.nextId,
+          tasks: state.tasks.map((candidate) =>
+            candidate.id === updatedTask.id ? updatedTask : candidate,
+          ),
+        },
+        message: `Updated Task #${task.id}`,
+        details: { action: "update" },
+      };
+    }
+
+    case "remove": {
+      if (input.id === undefined) {
+        return todoOperationFailure("remove", "Todo remove failed: id is required");
+      }
+      const id = parseTodoTaskId(input.id);
+      if (id === undefined) {
+        return todoOperationFailure(
+          "remove",
+          "Todo remove failed: id must be a positive safe integer",
+        );
+      }
+      const task = state.tasks.find((candidate) => candidate.id === id);
+      if (!task) {
+        return todoOperationFailure(
+          "remove",
+          `Todo remove failed: Task #${input.id} was not found`,
+        );
+      }
+      return {
+        ok: true,
+        changed: true,
+        state: {
+          nextId: state.nextId,
+          tasks: state.tasks.filter((candidate) => candidate.id !== task.id),
+        },
+        message: `Removed Task #${task.id}`,
+        details: { action: "remove" },
+      };
+    }
+
+    case "clear": {
+      const count = state.tasks.length;
+      return {
+        ok: true,
+        changed: count > 0 || state.nextId !== 1,
+        state: createEmptyTodoState(),
+        message: `Cleared ${count} ${count === 1 ? "Task" : "Tasks"}`,
+        details: { action: "clear" },
+      };
+    }
+  }
+}
+
+/** Returns the status marker shared by model context, transcript, and widget output. */
+export function todoStatusMarker(status: TodoStatus): "[ ]" | "[>]" | "[x]" {
+  if (status === "pending") return "[ ]";
+  return status === "active" ? "[>]" : "[x]";
+}
+
+function formatTodoDescription(description: string): string {
+  return description
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+}
+
+/** Formats the complete numeric-ID-ordered Todo List for tools and model context. */
+export function formatTodoList(tasks: readonly TodoTask[]): string {
+  if (tasks.length === 0) return "Todo List is empty";
+  return tasks
+    .map((task) => {
+      const description = task.description ? `\n${formatTodoDescription(task.description)}` : "";
+      return `${todoStatusMarker(task.status)} #${task.id} ${task.title}${description}`;
+    })
+    .join("\n");
+}