@pi9/todo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chase Cummings
+
+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,128 @@
+# @pi9/todo
+
+A phased, branch-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
+
+## Features
+
+- Concise phased plans with immutable task names
+- Destructive plan replacement and non-destructive task addition
+- Atomic status transitions addressed by exact phase and task names
+- Explicit `pending`, `in_progress`, `completed`, and `cancelled` statuses
+- State restored from the active Pi session branch
+- A persistent, configurable todo widget above or below the editor
+- Rich tool rendering with active-task summaries and expandable phase progress
+- Native-style self-rendered tool shells with no extra spacing for hidden activity
+
+Todo snapshots are stored in tool-result details, so `/tree` navigation restores the plan associated with that branch.
+
+## Tool contract
+
+The provider-facing schema is one flat object rather than a union, which keeps it compatible across Pi providers. Action-specific requirements are validated atomically by the tool.
+
+### Set the complete plan
+
+`set` discards the complete current plan and creates exactly the supplied phases and tasks. Every task starts `pending`. An empty `phases` array clears the plan.
+
+```json
+{
+  "action": "set",
+  "phases": [
+    {
+      "name": "Build",
+      "tasks": ["Implement session restoration", "Add integration coverage"]
+    }
+  ]
+}
+```
+
+### Add newly discovered work
+
+`add` creates missing phases or appends tasks to existing phases without changing current tasks or statuses. New tasks start `pending`.
+
+```json
+{
+  "action": "add",
+  "phases": [
+    {
+      "name": "Verify",
+      "tasks": ["Run the complete test suite"]
+    }
+  ]
+}
+```
+
+### Transition task statuses
+
+`transition` applies status changes atomically using exact phase and task names.
+
+```json
+{
+  "action": "transition",
+  "transitions": [
+    {
+      "phase": "Build",
+      "task": "Implement session restoration",
+      "status": "completed"
+    },
+    {
+      "phase": "Verify",
+      "task": "Run the complete test suite",
+      "status": "in_progress"
+    }
+  ]
+}
+```
+
+Phase names and task names are immutable. Task names must be unique within their phase. Cancel obsolete tasks instead of removing them; cancel and add a corrected task when its name needs to change. All `in_progress` tasks must belong to one phase.
+
+### View the plan
+
+`view` returns the complete plan or one exact phase:
+
+```json
+{ "action": "view", "phase": "Build" }
+```
+
+## Install
+
+```bash
+pi install npm:@pi9/todo
+```
+
+For local development:
+
+```bash
+pi -e ./packages/todo/src/index.ts
+```
+
+## UI settings
+
+The settings loader reads global settings from `~/.pi/agent/todo/settings.json`. For a trusted project, `.pi/todo/settings.json` overrides the global values. Pi's project-trust decision is required before the project file is read; an untrusted project cannot affect these settings.
+
+```json
+{
+  "widgetPlacement": "aboveEditor",
+  "maxVisibleTasks": 5,
+  "fallbackGlyphs": false,
+  "toolVisibility": "set-only"
+}
+```
+
+`widgetPlacement` accepts `"aboveEditor"`, `"belowEditor"`, or `"off"`. `maxVisibleTasks` must be a positive integer, and `fallbackGlyphs` must be a boolean. Nerd Font status glyphs are the default; set `fallbackGlyphs` to `true` to use broadly supported Unicode symbols instead.
+
+`toolVisibility` controls Todo tool output in the terminal UI only:
+
+- `"all"` shows every Todo action.
+- `"set-only"` shows only `set` operations.
+- `"none"` hides normal Todo activity.
+
+Errors are always shown. Todo output uses native-style self-rendered shells, and hidden successful operations render zero lines. When expanded, the latest rendered `set` result on the active branch follows later additions and transitions; historical details and collapsed rendering remain unchanged.
+
+Settings load when a session starts. The widget refreshes after todo changes and `/tree` navigation. Set `widgetPlacement` to `"off"` to disable it.
+
+## Development
+
+```bash
+npm run typecheck --workspace @pi9/todo
+npm test --workspace @pi9/todo
+```

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@pi9/todo",
+  "version": "0.1.0",
+  "description": "Pi extension for managing agent todo tasks.",
+  "license": "MIT",
+  "author": "Chase Cummings <chaseecummings@gmail.com>",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Chase-C/pi9.git",
+    "directory": "packages/todo"
+  },
+  "bugs": {
+    "url": "https://github.com/Chase-C/pi9/issues"
+  },
+  "homepage": "https://github.com/Chase-C/pi9/tree/main/packages/todo#readme",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "pi9",
+    "todo"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [],
+    "prompts": []
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@types/node": "^24.0.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.6"
+  }
+}

package/src/format.ts

@@ -0,0 +1,61 @@
+import type { Todo, TodoState } from "./types.js";
+
+export type PhasedTodo = Todo & { phase: string };
+
+export interface TodoCounts {
+  open: number;
+  completed: number;
+  cancelled: number;
+}
+
+/** A small, plain-text representation used in tool results and model context. */
+export function formatTodoSummary(state: TodoState | undefined): string {
+  const tasks = todoTasks(state);
+  if (tasks.length === 0) return "No todo tasks.";
+
+  const counts = countTodos(tasks);
+  const summary = [
+    `${counts.open} open`,
+    ...(counts.completed ? [`${counts.completed} completed`] : []),
+    ...(counts.cancelled ? [`${counts.cancelled} cancelled`] : []),
+  ].join(" · ");
+
+  return [`Todo: ${summary}`, ...formatTodoTaskLines(state)].join("\n");
+}
+
+export function formatTodoTaskLines(state: TodoState | undefined): string[] {
+  if (!state || state.phases.every((phase) => phase.tasks.length === 0)) return [];
+  const lines: string[] = [];
+  for (const phase of state.phases) {
+    if (phase.tasks.length === 0) continue;
+    lines.push(`${phase.name}:`);
+    lines.push(...phase.tasks.map((task) => `  ${taskMarker(task)} ${task.name}`));
+  }
+  return lines;
+}
+
+export function countTodos(state: TodoState | readonly Todo[] | undefined): TodoCounts {
+  const tasks = Array.isArray(state) ? state : todoTasks(state as TodoState | undefined);
+  let open = 0;
+  let completed = 0;
+  let cancelled = 0;
+  for (const task of tasks) {
+    if (task.status === "completed") completed++;
+    else if (task.status === "cancelled") cancelled++;
+    else open++;
+  }
+  return { open, completed, cancelled };
+}
+
+export function taskMarker(task: Pick<Todo, "status">): string {
+  switch (task.status) {
+    case "completed": return "✓";
+    case "in_progress": return "▶";
+    case "cancelled": return "×";
+    default: return "○";
+  }
+}
+
+export function todoTasks(state: TodoState | undefined): PhasedTodo[] {
+  return state?.phases.flatMap((phase) => phase.tasks.map((task) => ({ ...task, phase: phase.name }))) ?? [];
+}

package/src/glyphs.ts

@@ -0,0 +1,21 @@
+import type { TodoStatus } from "./types.js";
+
+export type TodoGlyphs = Record<TodoStatus, string>;
+
+export const NERD_FONT_TODO_GLYPHS: TodoGlyphs = {
+  pending: "󰄰",
+  in_progress: "󰻃",
+  completed: "󰄴",
+  cancelled: "󰍷",
+};
+
+export const FALLBACK_TODO_GLYPHS: TodoGlyphs = {
+  pending: "○",
+  in_progress: "▶",
+  completed: "✓",
+  cancelled: "×",
+};
+
+export function todoGlyph(status: TodoStatus, fallbackGlyphs = false): string {
+  return (fallbackGlyphs ? FALLBACK_TODO_GLYPHS : NERD_FONT_TODO_GLYPHS)[status];
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTodoTool } from "./tool.js";
+
+export default function todoExtension(pi: ExtensionAPI): void {
+  registerTodoTool(pi);
+}

package/src/persistence.ts

@@ -0,0 +1,87 @@
+import { TODO_ACTIONS, TODO_STATUSES, type TodoState, type TodoToolDetails } from "./types.js";
+
+export const TODO_TOOL_NAME = "todo";
+
+export const createEmptyTodoState = (): TodoState => ({ phases: [] });
+
+export function cloneTodoState(state: TodoState): TodoState {
+  return structuredClone(state);
+}
+
+type BranchContext = {
+  sessionManager: {
+    getBranch(): readonly unknown[];
+  };
+};
+
+type ToolResultEntry = {
+  type: "message";
+  message: {
+    role: "toolResult";
+    toolName?: unknown;
+    isError?: unknown;
+    details?: unknown;
+  };
+};
+
+function isTodoState(value: unknown): value is TodoState {
+  if (typeof value !== "object" || value === null) return false;
+  const state = value as { phases?: unknown };
+  if (!Array.isArray(state.phases)) return false;
+
+  const phaseNames = new Set<string>();
+  let activePhase: string | undefined;
+  for (const value of state.phases) {
+    if (typeof value !== "object" || value === null) return false;
+    const phase = value as { name?: unknown; tasks?: unknown };
+    if (!validName(phase.name) || phaseNames.has(phase.name) || !Array.isArray(phase.tasks)) return false;
+    phaseNames.add(phase.name);
+
+    const taskNames = new Set<string>();
+    for (const value of phase.tasks) {
+      if (typeof value !== "object" || value === null) return false;
+      const task = value as { name?: unknown; status?: unknown };
+      if (!validName(task.name) || taskNames.has(task.name) || !(TODO_STATUSES as readonly unknown[]).includes(task.status)) return false;
+      if (task.status === "in_progress") {
+        if (activePhase !== undefined && activePhase !== phase.name) return false;
+        activePhase = phase.name;
+      }
+      taskNames.add(task.name);
+    }
+  }
+  return true;
+}
+
+function validName(value: unknown): value is string {
+  return typeof value === "string" && value !== "" && value === value.trim();
+}
+
+function isTodoToolDetails(value: unknown): value is TodoToolDetails {
+  if (typeof value !== "object" || value === null) return false;
+  const details = value as { action?: unknown; state?: unknown };
+  return typeof details.action === "string"
+    && (TODO_ACTIONS as readonly string[]).includes(details.action)
+    && isTodoState(details.state);
+}
+
+function isSuccessfulTodoResult(value: unknown): value is ToolResultEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as Partial<ToolResultEntry>;
+  return entry.type === "message"
+    && typeof entry.message === "object"
+    && entry.message !== null
+    && entry.message.role === "toolResult"
+    && entry.message.toolName === TODO_TOOL_NAME
+    && entry.message.isError !== true
+    && isTodoToolDetails(entry.message.details);
+}
+
+/** Restores the latest successful todo snapshot from the current session branch. */
+export function restoreTodoState(ctx: BranchContext): TodoState {
+  const branch = ctx.sessionManager.getBranch();
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (isSuccessfulTodoResult(entry)) return cloneTodoState((entry.message.details as TodoToolDetails).state);
+  }
+  return createEmptyTodoState();
+}

package/src/renderer.ts

@@ -0,0 +1,147 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { countTodos, formatTodoSummary, todoTasks, type PhasedTodo } from "./format.js";
+import { todoGlyph } from "./glyphs.js";
+import type { TodoParams } from "./schema.js";
+import { todoAddressKey } from "./state.js";
+import type { Todo, TodoAddress, TodoPhase, TodoState, TodoToolDetails } from "./types.js";
+
+type ThemeLike = Partial<Pick<Theme, "fg" | "bold" | "strikethrough">>;
+type ThemeColor = Parameters<Theme["fg"]>[0];
+
+export type TodoRendererOptions = { fallbackGlyphs?: boolean };
+
+export function renderCall(params: TodoParams | undefined, theme?: ThemeLike): Text {
+  const action = params?.action;
+  const label = typeof action === "string" && action ? `todo ${action}` : "todo";
+  return new Text(paint(theme, "toolTitle", label), 0, 0);
+}
+
+export function renderResult(
+  result: { details?: TodoToolDetails; content?: readonly { type?: string; text?: string }[] },
+  options: { expanded?: boolean } = {},
+  theme?: ThemeLike,
+  rendererOptions: TodoRendererOptions = {},
+): Text {
+  const state = result.details?.state;
+  if (!state) return new Text(fallbackText(result), 0, 0);
+
+  const tasks = todoTasks(state);
+  if (tasks.length === 0 && state.phases.length === 0) return new Text(paint(theme, "muted", "No todo tasks."), 0, 0);
+
+  const counts = countTodos(state);
+  const header = todoHeader(counts);
+  if (options.expanded !== true) return new Text(collapsedText(header, tasks, theme, rendererOptions), 0, 0);
+
+  const changed = new Set((result.details?.changedTasks ?? []).map(addressKey));
+  const selectedPhase = selectedPhaseIndex(state.phases);
+  const lines = [toolTitle(todoSummary(tasks), theme)];
+  for (const [index, phase] of state.phases.entries()) {
+    const heading = `  ${index + 1}. ${phaseSummary(phase)}`;
+    lines.push(index === selectedPhase ? toolTitle(heading, theme) : paint(theme, "dim", heading));
+    for (const task of orderedTasks(phase.tasks)) {
+      lines.push(renderTask(phase.name, task, changed, theme, rendererOptions));
+    }
+  }
+  return new Text(lines.join("\n"), 0, 0);
+}
+
+export function formatResultText(details: TodoToolDetails | undefined): string {
+  return formatTodoSummary(details?.state);
+}
+
+function todoHeader(counts: ReturnType<typeof countTodos>, title = "Todo"): string {
+  return [
+    `${title} · ${counts.open} open`,
+    ...(counts.completed ? [`${counts.completed} completed`] : []),
+    ...(counts.cancelled ? [`${counts.cancelled} cancelled`] : []),
+  ].join(" · ");
+}
+
+function collapsedText(header: string, tasks: PhasedTodo[], theme: ThemeLike | undefined, options: TodoRendererOptions): string {
+  const active = tasks.find((task) => task.status === "in_progress");
+  const activeText = active ? `Active: ${todoGlyph(active.status, options.fallbackGlyphs)} ${active.name}` : undefined;
+  return [paint(theme, "muted", header), ...(activeText ? [paint(theme, "warning", activeText)] : []), paint(theme, "dim", "↵ expand")].join(" · ");
+}
+
+function todoSummary(tasks: Todo[]): string {
+  const active = tasks.filter((task) => task.status === "in_progress").length;
+  const pending = tasks.filter((task) => task.status === "pending").length;
+  const completed = tasks.filter((task) => task.status === "completed").length;
+  const cancelled = tasks.filter((task) => task.status === "cancelled").length;
+  return [
+    "Todos",
+    ...(active ? [`${active} active`] : []),
+    ...(pending ? [`${pending} pending`] : []),
+    ...(completed ? [`${completed} completed`] : []),
+    ...(cancelled ? [`${cancelled} cancelled`] : []),
+  ].join(" · ");
+}
+
+function phaseSummary(phase: TodoPhase): string {
+  const active = phase.tasks.filter((task) => task.status === "in_progress").length;
+  const pending = phase.tasks.filter((task) => task.status === "pending").length;
+  const completed = phase.tasks.filter((task) => task.status === "completed").length;
+  const cancelled = phase.tasks.filter((task) => task.status === "cancelled").length;
+  return [
+    phase.name,
+    ...(active ? [`${active} active`] : []),
+    ...(pending ? [`${pending} pending`] : []),
+    ...(completed ? [`${completed} completed`] : []),
+    ...(cancelled ? [`${cancelled} cancelled`] : []),
+  ].join(" · ");
+}
+
+function selectedPhaseIndex(phases: TodoPhase[]): number {
+  const active = phases.findIndex((phase) => phase.tasks.some((task) => task.status === "in_progress"));
+  if (active !== -1) return active;
+  return phases.findIndex((phase) => phase.tasks.some((task) => task.status === "pending"));
+}
+
+function orderedTasks(tasks: Todo[]): Todo[] {
+  return tasks
+    .map((task, index) => ({ task, index }))
+    .sort((left, right) => taskPriority(left.task) - taskPriority(right.task) || left.index - right.index)
+    .map(({ task }) => task);
+}
+
+function taskPriority(task: Todo): number {
+  if (task.status === "in_progress") return 0;
+  if (task.status === "pending") return 1;
+  return 2;
+}
+
+function renderTask(phase: string, task: Todo, changed: Set<string>, theme: ThemeLike | undefined, options: TodoRendererOptions): string {
+  const text = isTerminal(task) && theme?.strikethrough ? theme.strikethrough(task.name) : task.name;
+  let line = `    ${todoGlyph(task.status, options.fallbackGlyphs)} ${text}`;
+  if ((task.status === "in_progress" || changed.has(todoAddressKey(phase, task.name))) && theme?.bold) line = theme.bold(line);
+  return paint(theme, statusColor(task.status), line);
+}
+
+function isTerminal(task: Todo): boolean {
+  return task.status === "completed" || task.status === "cancelled";
+}
+
+function addressKey(address: TodoAddress): string {
+  return todoAddressKey(address.phase, address.task);
+}
+
+function statusColor(status: string): ThemeColor {
+  if (status === "completed") return "success";
+  if (status === "in_progress") return "text";
+  return "dim";
+}
+
+function toolTitle(text: string, theme: ThemeLike | undefined): string {
+  const title = theme?.bold ? theme.bold(text) : text;
+  return paint(theme, "toolTitle", title);
+}
+
+function paint(theme: ThemeLike | undefined, color: ThemeColor, text: string): string {
+  return theme?.fg ? theme.fg(color, text) : text;
+}
+
+function fallbackText(result: { content?: readonly { type?: string; text?: string }[] }): string {
+  return result.content?.find((part) => part.type === "text")?.text || "No todo tasks.";
+}

package/src/schema.ts

@@ -0,0 +1,35 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { TODO_ACTIONS, TODO_STATUSES, type TodoActionName, type TodoPhaseInput, type TodoTransitionInput } from "./types.js";
+
+export const TodoPhaseSchema = Type.Object({
+  name: Type.String({ minLength: 1, description: "Immutable phase name, 1 or 2 words, unique." }),
+  tasks: Type.Array(Type.String({
+    minLength: 1,
+    description: "Immutable task name, ideally 5–10 words, what not how, unique within its phase.",
+  })),
+}, { additionalProperties: false });
+
+export const TodoTransitionSchema = Type.Object({
+  phase: Type.String({ minLength: 1, description: "Exact immutable phase name." }),
+  task: Type.String({ minLength: 1, description: "Exact immutable task name within the phase." }),
+  status: StringEnum(TODO_STATUSES, { description: "New task status." }),
+}, { additionalProperties: false });
+
+/** Flat provider-facing schema. Action-specific requirements are enforced by the transition. */
+export const TodoParamsSchema = Type.Object({
+  action: StringEnum(TODO_ACTIONS),
+  phases: Type.Optional(Type.Array(TodoPhaseSchema)),
+  transitions: Type.Optional(Type.Array(TodoTransitionSchema, { minItems: 1 })),
+  phase: Type.Optional(Type.String({ minLength: 1, description: "Optional exact phase name used to filter view." })),
+}, { additionalProperties: false });
+
+/** Broad parameter view used by tool render hooks. */
+export type TodoParams = {
+  action: TodoActionName;
+  phases?: TodoPhaseInput[];
+  transitions?: TodoTransitionInput[];
+  phase?: string;
+};
+
+export const TodoSchema = TodoParamsSchema;