@riverai7z/pi-todo 0.1.0

package/DESIGN.md

@@ -0,0 +1,79 @@
+# Design
+
+## Scope
+
+This release implements Claude Code's structured task-list domain:
+
+- `TaskCreate`
+- `TaskGet`
+- `TaskList`
+- `TaskUpdate`
+
+Claude Code's `TaskOutput` and `TaskStop` operate on a different runtime registry containing background shells and subagents. Pi does not expose an equivalent shared registry to extensions. Those names remain reserved until a background-task producer and lifecycle contract are implemented; fake placeholder tools are deliberately avoided.
+
+## State model
+
+```text
+TaskState
+├── nextId: number
+└── tasks[]
+    ├── id, subject, description, activeForm?
+    ├── status: pending | in_progress | completed | deleted
+    ├── owner?
+    ├── blockedBy[]
+    └── metadata?
+```
+
+`blocks` is derived as the inverse of `blockedBy`, preventing the two directions from drifting. `deleted` is a tombstone rather than physical removal, preserving monotonic IDs and historical dependency references.
+
+Allowed status transitions:
+
+```text
+pending ───────► in_progress ───────► completed ───────► deleted
+   ▲                  ▲                    │
+   │                  └────────────────────┤
+   └───────────────────────────────────────┘
+
+in_progress may return to pending when work is released. Completed work may be reopened as pending or in_progress when verification or new requirements reveal more work. Deleted is terminal.
+```
+
+## Persistence and branch semantics
+
+No project task file is written. Every tool result stores a complete snapshot in `details`:
+
+```ts
+{
+  action: "create" | "get" | "list" | "update",
+  tasks: Task[],
+  nextId: number,
+  error?: string
+}
+```
+
+On `session_start`, `session_compact`, and `session_tree`, the extension walks the active session branch and restores the latest valid snapshot from any of the four tools. This gives `/reload`, compaction, forks, and tree navigation the same state semantics as the conversation branch.
+
+Live state is partitioned by Pi session ID. Only the foreground UI session owns the overlay, preventing child or detached sessions from replacing its widget.
+
+## Dependency invariants
+
+- Dependencies must reference existing, non-deleted tasks.
+- A task cannot depend on itself.
+- Updates are applied to a candidate graph and rejected if a cycle appears.
+- Completing or deleting a blocker resolves it for availability and display, while retaining the historical edge.
+
+## UI
+
+The overlay is mounted above the editor only when visible tasks exist. When space is constrained it prioritizes recently completed work, `in_progress`, unblocked `pending`, blocked `pending`, then older completed work. Its height responds to the terminal, Pi's tool expansion mode reveals the full list, and overflow is summarized by status. Completed rows remain visible for their turn and are hidden from the next turn's overlay without deleting task history. `/tasks` provides the complete grouped view. `Ctrl+Shift+T` toggles the overlay's collapsed state. The active task's `activeForm` (falling back to its subject) drives Pi's working message.
+
+## Future background-task phase
+
+A real `TaskOutput`/`TaskStop` phase should add:
+
+1. A producer tool for background shell or agent tasks.
+2. A process registry scoped to a Pi session.
+3. Abort-safe process-group termination.
+4. Output files with bounded reads and truncation.
+5. Completion notifications and shutdown cleanup.
+6. `TaskOutput` polling (`block`, `timeout`) and `TaskStop` validation matching Claude Code semantics.
+
+That runtime registry should remain separate from the structured task list even if both use task-like IDs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 River-Walras
+
+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,49 @@
+# pi-todo
+
+Claude Code-style structured task management for Pi.
+
+## Features
+
+- Four task-list tools with Claude Code-compatible responsibilities:
+  - `TaskCreate`
+  - `TaskGet`
+  - `TaskList`
+  - `TaskUpdate`
+- Status workflow: `pending` → `in_progress` → `completed`, plus terminal `deleted` tombstones.
+- Owners, metadata, `blocks`/`blockedBy` dependencies, cycle rejection, and unresolved-blocker filtering.
+- Session-local state reconstructed from tool-result `details`, so `/reload`, compaction, `/tree`, and forks preserve branch semantics without project files.
+- Live responsive task overlay above the editor, with blocked work deprioritized and categorized overflow.
+- `activeForm` drives Pi's working message while a task is in progress.
+- Completed rows are struck through, remain visible for the current turn, then leave the overlay without deleting history.
+- `/tasks` command for the complete grouped list.
+- `Ctrl+Shift+T` collapses or expands the overlay; Pi's tool expansion mode shows all tasks.
+
+`TaskOutput` and `TaskStop` belong to Claude Code's separate background-process task system. They are intentionally reserved until this package gains a Pi background-task producer; registering non-functional placeholders would mislead the model.
+
+## Install
+
+```bash
+pi install npm:@riverai7z/pi-todo
+```
+
+From this directory:
+
+```bash
+pi install .
+```
+
+For development:
+
+```bash
+pi -e ./index.ts
+```
+
+## Persistence model
+
+Every tool result contains a complete task-state snapshot in `details`. On session start, compaction, or tree navigation, the extension walks the active branch and restores the latest valid snapshot. Each Pi session has an isolated in-memory state slot, while the foreground session owns the overlay.
+
+## Design references
+
+- Claude Code `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate`
+- Pi's stateful todo extension example
+- `rpiv-mono/packages/rpiv-todo` session replay and overlay patterns

package/index.ts

@@ -0,0 +1,462 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type Static, Type } from "typebox";
+import { formatTaskLine, TaskOverlay } from "./overlay.js";
+import {
+  clearForegroundSession,
+  createTask,
+  deriveBlocks,
+  evictSession,
+  getForegroundSession,
+  getForegroundState,
+  getState,
+  getTask,
+  listTasks,
+  replayState,
+  replaceState,
+  sessionId,
+  setForegroundSession,
+  snapshot,
+  unresolvedBlockers,
+  updateTask,
+  type Task,
+  type TaskSnapshot,
+  type TaskStatus,
+} from "./state.js";
+
+const TASK_TOOL_NAMES = new Set(["TaskCreate", "TaskGet", "TaskList", "TaskUpdate"]);
+const TaskCreateSchema = Type.Object({
+  subject: Type.String({ minLength: 1, description: "A brief title for the task" }),
+  description: Type.String({ minLength: 1, description: "What needs to be done" }),
+  activeForm: Type.Optional(
+    Type.String({ description: "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")" }),
+  ),
+  metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata to attach to the task" })),
+});
+
+const TaskGetSchema = Type.Object({
+  taskId: Type.String({ description: "The ID of the task to retrieve" }),
+});
+
+const TaskListSchema = Type.Object({});
+
+const TaskUpdateSchema = Type.Object({
+  taskId: Type.String({ description: "The ID of the task to update" }),
+  subject: Type.Optional(Type.String({ description: "New subject for the task" })),
+  description: Type.Optional(Type.String({ description: "New description for the task" })),
+  activeForm: Type.Optional(
+    Type.String({ description: "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")" }),
+  ),
+  status: Type.Optional(
+    StringEnum(["pending", "in_progress", "completed", "deleted"] as const, {
+      description: "New status for the task",
+    }),
+  ),
+  addBlocks: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that this task blocks" })),
+  addBlockedBy: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that block this task" })),
+  owner: Type.Optional(Type.String({ description: "New owner for the task" })),
+  metadata: Type.Optional(
+    Type.Record(Type.String(), Type.Unknown(), {
+      description: "Metadata keys to merge into the task. Set a key to null to delete it.",
+    }),
+  ),
+});
+
+type TaskUpdateParams = Static<typeof TaskUpdateSchema>;
+
+const TASK_CREATE_DESCRIPTION = `Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+It also helps the user understand the progress of the task and overall progress of their requests.
+
+## When to Use This Tool
+
+Use this tool proactively in these scenarios:
+
+- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+- Plan mode - When using plan mode, create a task list to track the work
+- User explicitly requests todo list - When the user directly asks you to use the todo list
+- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+- After receiving new instructions - Immediately capture user requirements as tasks
+- When you start working on a task - Mark it as in_progress BEFORE beginning work
+- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+
+## When NOT to Use This Tool
+
+Skip using this tool when:
+- There is only a single, straightforward task
+- The task is trivial and tracking it provides no organizational benefit
+- The task can be completed in less than 3 trivial steps
+- The task is purely conversational or informational
+
+NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+## Task Fields
+
+- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+- **description**: What needs to be done
+- **activeForm** (optional): Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.
+
+All tasks are created with status \`pending\`.
+
+## Tips
+
+- Create tasks with clear, specific subjects that describe the outcome
+- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
+- Check TaskList first to avoid creating duplicate tasks`;
+
+const TASK_GET_DESCRIPTION = `Use this tool to retrieve a task by its ID from the task list.
+
+## When to Use This Tool
+
+- When you need the full description and context before starting work on a task
+- To understand task dependencies (what it blocks, what blocks it)
+- After being assigned a task, to get complete requirements
+
+## Output
+
+Returns full task details:
+- **subject**: Task title
+- **description**: Detailed requirements and context
+- **status**: 'pending', 'in_progress', or 'completed'
+- **blocks**: Tasks waiting on this one to complete
+- **blockedBy**: Tasks that must complete before this one can start
+
+## Tips
+
+- After fetching a task, verify its blockedBy list is empty before beginning work.
+- Use TaskList to see all tasks in summary form.`;
+
+const TASK_LIST_DESCRIPTION = `Use this tool to list all tasks in the task list.
+
+## When to Use This Tool
+
+- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
+- To check overall progress on the project
+- To find tasks that are blocked and need dependencies resolved
+- After completing a task, to check for newly unblocked work or claim the next available task
+- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+
+## Output
+
+Returns a summary of each task:
+- **id**: Task identifier (use with TaskGet, TaskUpdate)
+- **subject**: Brief description of the task
+- **status**: 'pending', 'in_progress', or 'completed'
+- **owner**: Agent ID if assigned, empty if available
+- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+
+Use TaskGet with a specific task ID to view full details including description and comments.`;
+
+const TASK_UPDATE_DESCRIPTION = `Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to \`deleted\` hides the task as a terminal tombstone in this Pi extension
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: \`pending\` → \`in_progress\` → \`completed\`
+
+Use \`deleted\` to hide a task as a terminal tombstone.
+
+## Staleness
+
+Make sure to read a task's latest state using \`TaskGet\` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+\`\`\`json
+{"taskId": "1", "status": "in_progress"}
+\`\`\`
+
+Mark task as completed after finishing work:
+\`\`\`json
+{"taskId": "1", "status": "completed"}
+\`\`\`
+
+Delete a task:
+\`\`\`json
+{"taskId": "1", "status": "deleted"}
+\`\`\`
+
+Claim a task by setting owner:
+\`\`\`json
+{"taskId": "1", "owner": "my-name"}
+\`\`\`
+
+Set up task dependencies:
+\`\`\`json
+{"taskId": "2", "addBlockedBy": ["1"]}
+\`\`\``;
+
+function textResult(text: string, details: TaskSnapshot) {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+function renderHeader(label: string, suffix: string, theme: Theme): Text {
+  return new Text(`${theme.fg("toolTitle", theme.bold(label))}${suffix ? ` ${theme.fg("muted", suffix)}` : ""}`, 0, 0);
+}
+
+function renderResult(result: { content: Array<{ type: string; text?: string }>; details?: unknown }, theme: Theme): Text {
+  const details = result.details as TaskSnapshot | undefined;
+  const raw = result.content.find((part) => part.type === "text")?.text ?? "";
+  return new Text(details?.error ? theme.fg("error", raw) : theme.fg("muted", raw), 0, 0);
+}
+
+function fullTaskText(task: Task, tasks: readonly Task[]): string {
+  const lines = [
+    `Task #${task.id}: ${task.subject}`,
+    `Status: ${task.status}`,
+    `Description: ${task.description}`,
+  ];
+  if (task.activeForm) lines.push(`Active form: ${task.activeForm}`);
+  if (task.owner) lines.push(`Owner: ${task.owner}`);
+  if (task.blockedBy.length) lines.push(`Blocked by: ${task.blockedBy.map((id) => `#${id}`).join(", ")}`);
+  const blocks = deriveBlocks(tasks, task.id);
+  if (blocks.length) lines.push(`Blocks: ${blocks.map((id) => `#${id}`).join(", ")}`);
+  if (task.metadata && Object.keys(task.metadata).length) lines.push(`Metadata: ${JSON.stringify(task.metadata)}`);
+  return lines.join("\n");
+}
+
+function hasUpdate(params: TaskUpdateParams): boolean {
+  return (
+    params.subject !== undefined ||
+    params.description !== undefined ||
+    params.activeForm !== undefined ||
+    params.status !== undefined ||
+    params.owner !== undefined ||
+    params.metadata !== undefined ||
+    (params.addBlocks?.length ?? 0) > 0 ||
+    (params.addBlockedBy?.length ?? 0) > 0
+  );
+}
+
+export default function (pi: ExtensionAPI): void {
+  const overlay = new TaskOverlay();
+  let foregroundUi: ExtensionUIContext | undefined;
+
+  const syncWorkingMessage = (): void => {
+    if (!foregroundUi) return;
+    const activeTask = getForegroundState().tasks.find((task) => task.status === "in_progress");
+    const message = activeTask ? activeTask.activeForm?.trim() || activeTask.subject : undefined;
+    foregroundUi.setWorkingMessage(message);
+  };
+
+  pi.registerTool({
+    name: "TaskCreate",
+    label: "TaskCreate",
+    description: TASK_CREATE_DESCRIPTION,
+    promptSnippet: "Create a task in the structured task list",
+    parameters: TaskCreateSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const id = sessionId(ctx);
+      if (!params.subject.trim() || !params.description.trim()) {
+        throw new Error("TaskCreate requires non-empty subject and description");
+      }
+      const { state, task } = createTask(id, params);
+      return textResult(`Task #${task.id} created successfully: ${task.subject}`, snapshot("create", state));
+    },
+    renderCall(args, theme) {
+      return renderHeader("TaskCreate", args.subject ? `“${args.subject}”` : "", theme);
+    },
+    renderResult(result, _options, theme) {
+      return renderResult(result, theme);
+    },
+  });
+
+  pi.registerTool({
+    name: "TaskGet",
+    label: "TaskGet",
+    description: TASK_GET_DESCRIPTION,
+    promptSnippet: "Retrieve a task by ID",
+    parameters: TaskGetSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const id = sessionId(ctx);
+      const state = getState(id);
+      const task = getTask(id, params.taskId);
+      if (!task) return textResult("Task not found", snapshot("get", state, "Task not found"));
+      return textResult(fullTaskText(task, state.tasks), snapshot("get", state));
+    },
+    renderCall(args, theme) {
+      return renderHeader("TaskGet", `#${args.taskId}`, theme);
+    },
+    renderResult(result, _options, theme) {
+      return renderResult(result, theme);
+    },
+  });
+
+  pi.registerTool({
+    name: "TaskList",
+    label: "TaskList",
+    description: TASK_LIST_DESCRIPTION,
+    promptSnippet: "List all structured tasks",
+    parameters: TaskListSchema,
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const id = sessionId(ctx);
+      const state = getState(id);
+      const tasks = listTasks(id);
+      const content = tasks.length
+        ? tasks
+            .map((task) => {
+              const owner = task.owner ? ` (${task.owner})` : "";
+              const blockedBy = unresolvedBlockers(task, state.tasks);
+              const blocked = blockedBy.length ? ` [blocked by ${blockedBy.map((value) => `#${value}`).join(", ")}]` : "";
+              return `#${task.id} [${task.status}] ${task.subject}${owner}${blocked}`;
+            })
+            .join("\n")
+        : "No tasks found";
+      return textResult(content, snapshot("list", state));
+    },
+    renderCall(_args, theme) {
+      return renderHeader("TaskList", "", theme);
+    },
+    renderResult(result, _options, theme) {
+      return renderResult(result, theme);
+    },
+  });
+
+  pi.registerTool({
+    name: "TaskUpdate",
+    label: "TaskUpdate",
+    description: TASK_UPDATE_DESCRIPTION,
+    promptSnippet: "Update a task or its dependencies",
+    parameters: TaskUpdateSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const id = sessionId(ctx);
+      if (!hasUpdate(params)) {
+        const state = getState(id);
+        const error = "TaskUpdate requires at least one field to change";
+        return textResult(error, snapshot("update", state, error));
+      }
+      const result = updateTask(id, params.taskId, params);
+      if (result.error) return textResult(result.error, snapshot("update", result.state, result.error));
+      const message = result.updatedFields.length
+        ? `Updated task #${params.taskId}: ${result.updatedFields.join(", ")}`
+        : `No change to task #${params.taskId}`;
+      return textResult(message, snapshot("update", result.state));
+    },
+    renderCall(args, theme) {
+      const status = args.status ? ` → ${args.status}` : "";
+      return renderHeader("TaskUpdate", `#${args.taskId}${status}`, theme);
+    },
+    renderResult(result, _options, theme) {
+      return renderResult(result, theme);
+    },
+  });
+
+  pi.registerCommand("tasks", {
+    description: "Show the current session's task list",
+    handler: async (_args, ctx) => {
+      const state = getState(sessionId(ctx));
+      const tasks = state.tasks.filter((task) => task.status !== "deleted");
+      if (tasks.length === 0) {
+        ctx.ui.notify("No tasks found", "info");
+        return;
+      }
+      const order: Exclude<TaskStatus, "deleted">[] = ["in_progress", "pending", "completed"];
+      const labels: Record<Exclude<TaskStatus, "deleted">, string> = {
+        in_progress: "In Progress",
+        pending: "Pending",
+        completed: "Completed",
+      };
+      const lines: string[] = [];
+      for (const status of order) {
+        const group = tasks.filter((task) => task.status === status);
+        if (!group.length) continue;
+        lines.push(`── ${labels[status]} ──`);
+        for (const task of group) lines.push(`  ${formatTaskLine(task, state.tasks, ctx.ui.theme)}`);
+      }
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  pi.registerShortcut("ctrl+shift+t", {
+    description: "Collapse or expand the task overlay",
+    handler: (ctx) => {
+      if (ctx.hasUI) overlay.toggle();
+    },
+  });
+
+  const replayAndRefresh = (ctx: Parameters<typeof sessionId>[0] & Parameters<typeof replayState>[0]): void => {
+    const id = sessionId(ctx);
+    replaceState(id, replayState(ctx));
+    if (id === getForegroundSession()) {
+      overlay.resetCompletedDisplayState();
+      overlay.update();
+      syncWorkingMessage();
+    }
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    const id = sessionId(ctx);
+    replaceState(id, replayState(ctx));
+    if (!ctx.hasUI) return;
+    if (!getForegroundSession()) setForegroundSession(id);
+    if (id === getForegroundSession()) {
+      foregroundUi = ctx.ui;
+      overlay.bind(ctx.ui);
+      syncWorkingMessage();
+    }
+  });
+
+  pi.on("session_compact", async (_event, ctx) => replayAndRefresh(ctx));
+  pi.on("session_tree", async (_event, ctx) => replayAndRefresh(ctx));
+
+  pi.on("tool_execution_end", async (event) => {
+    if (!TASK_TOOL_NAMES.has(event.toolName) || event.isError) return;
+    overlay.update();
+    syncWorkingMessage();
+  });
+
+  pi.on("agent_start", async () => {
+    overlay.hideCompletedTasksFromPreviousTurn();
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    const id = sessionId(ctx);
+    evictSession(id);
+    if (id === getForegroundSession()) {
+      try {
+        foregroundUi?.setWorkingMessage();
+        overlay.dispose();
+      } finally {
+        foregroundUi = undefined;
+        clearForegroundSession();
+      }
+    }
+  });
+}

package/overlay.ts

@@ -0,0 +1,234 @@
+import type { ExtensionUIContext, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { getForegroundState, unresolvedBlockers, type Task } from "./state.js";
+
+const WIDGET_KEY = "pi-todo";
+const MAX_LINES = 12;
+const RESERVED_TERMINAL_ROWS = 12;
+
+function sanitizeTerminalText(text: string): string {
+  return text
+    .replace(/(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/(?:\u001b\]|\u009d)[^\u0007\u009c\u001b]*(?:\u0007|\u009c|\u001b\\)?/g, "")
+    .replace(/\u001b./g, "")
+    .replace(/[\u2028\u2029]/g, " ")
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, (character) =>
+      character === "\n" || character === "\r" || character === "\t" ? " " : "",
+    )
+    .replace(/[\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "");
+}
+
+function statusGlyph(task: Task): string {
+  switch (task.status) {
+    case "pending":
+      return "○";
+    case "in_progress":
+      return "◐";
+    case "completed":
+      return "✓";
+    case "deleted":
+      return "×";
+  }
+}
+
+function statusColor(task: Task): "dim" | "accent" | "success" {
+  if (task.status === "in_progress") return "accent";
+  if (task.status === "completed") return "success";
+  return "dim";
+}
+
+export function formatTaskLine(task: Task, tasks: readonly Task[], theme: Theme, showId = true): string {
+  const blockers = unresolvedBlockers(task, tasks);
+  const id = showId ? `${theme.fg("accent", `#${task.id}`)} ` : "";
+  const owner = task.owner ? theme.fg("dim", ` @${sanitizeTerminalText(task.owner)}`) : "";
+  const blocked = blockers.length
+    ? theme.fg("warning", ` [blocked by ${blockers.map((value) => `#${value}`).join(", ")}]`)
+    : "";
+  const rawSubject = theme.fg(task.status === "completed" ? "dim" : "text", sanitizeTerminalText(task.subject));
+  const subject = task.status === "completed" ? theme.strikethrough(rawSubject) : rawSubject;
+  const activeForm =
+    task.status === "in_progress" && task.activeForm
+      ? theme.fg("dim", ` (${sanitizeTerminalText(task.activeForm)})`)
+      : "";
+  return `${theme.fg(statusColor(task), statusGlyph(task))} ${id}${subject}${activeForm}${owner}${blocked}`;
+}
+
+function byId(a: Task, b: Task): number {
+  return Number(a.id) - Number(b.id);
+}
+
+export class TaskOverlay {
+  private ui?: ExtensionUIContext;
+  private tui?: TUI;
+  private registered = false;
+  private collapsed = false;
+  private completedPendingHide = new Set<string>();
+  private hiddenCompleted = new Set<string>();
+  private recentCompleted = new Set<string>();
+  private previousStatuses = new Map<string, Task["status"]>();
+  private lastNextId?: number;
+
+  bind(ui: ExtensionUIContext): void {
+    if (this.ui !== ui) {
+      this.dispose();
+      this.ui = ui;
+    }
+    this.update();
+  }
+
+  update(): void {
+    if (!this.ui) return;
+    const visible = this.reconcileVisibleTasks();
+    if (visible.length === 0) {
+      if (this.registered) this.ui.setWidget(WIDGET_KEY, undefined);
+      this.registered = false;
+      this.tui = undefined;
+      return;
+    }
+
+    if (!this.registered) {
+      this.ui.setWidget(
+        WIDGET_KEY,
+        (tui, theme) => {
+          this.tui = tui;
+          return {
+            render: (width: number) => this.render(this.ui?.theme ?? theme, width),
+            invalidate: () => {},
+          };
+        },
+        { placement: "aboveEditor" },
+      );
+      this.registered = true;
+    } else {
+      this.tui?.requestRender();
+    }
+  }
+
+  toggle(): void {
+    if (!this.registered) return;
+    this.collapsed = !this.collapsed;
+    this.tui?.requestRender(true);
+  }
+
+  resetCompletedDisplayState(): void {
+    this.completedPendingHide.clear();
+    this.hiddenCompleted.clear();
+    this.recentCompleted.clear();
+    this.previousStatuses.clear();
+    this.lastNextId = undefined;
+  }
+
+  hideCompletedTasksFromPreviousTurn(): void {
+    if (this.completedPendingHide.size === 0) return;
+    for (const id of this.completedPendingHide) {
+      this.hiddenCompleted.add(id);
+      this.recentCompleted.delete(id);
+    }
+    this.completedPendingHide.clear();
+    this.update();
+  }
+
+  dispose(): void {
+    if (this.ui && this.registered) this.ui.setWidget(WIDGET_KEY, undefined);
+    this.ui = undefined;
+    this.tui = undefined;
+    this.registered = false;
+    this.collapsed = false;
+    this.resetCompletedDisplayState();
+  }
+
+  private reconcileVisibleTasks(): Task[] {
+    const state = getForegroundState();
+    if (this.lastNextId !== undefined && state.nextId < this.lastNextId) this.resetCompletedDisplayState();
+    this.lastNextId = state.nextId;
+
+    const currentIds = new Set(state.tasks.map((task) => task.id));
+    for (const task of state.tasks) {
+      const previous = this.previousStatuses.get(task.id);
+      if (task.status === "completed" && previous !== undefined && previous !== "completed") {
+        this.recentCompleted.add(task.id);
+        this.completedPendingHide.add(task.id);
+      }
+      if (task.status !== "completed") {
+        this.completedPendingHide.delete(task.id);
+        this.hiddenCompleted.delete(task.id);
+        this.recentCompleted.delete(task.id);
+      }
+      this.previousStatuses.set(task.id, task.status);
+    }
+    for (const id of this.previousStatuses.keys()) {
+      if (!currentIds.has(id)) this.previousStatuses.delete(id);
+    }
+
+    return state.tasks.filter((task) => task.status !== "deleted" && !this.hiddenCompleted.has(task.id));
+  }
+
+  private prioritized(tasks: Task[]): Task[] {
+    const recentCompleted = tasks.filter((task) => this.recentCompleted.has(task.id)).sort(byId);
+    const inProgress = tasks.filter((task) => task.status === "in_progress").sort(byId);
+    const pending = tasks
+      .filter((task) => task.status === "pending")
+      .sort((a, b) => {
+        const aBlocked = unresolvedBlockers(a, tasks).length > 0;
+        const bBlocked = unresolvedBlockers(b, tasks).length > 0;
+        return Number(aBlocked) - Number(bBlocked) || byId(a, b);
+      });
+    const olderCompleted = tasks
+      .filter((task) => task.status === "completed" && !this.recentCompleted.has(task.id))
+      .sort(byId);
+    return [...recentCompleted, ...inProgress, ...pending, ...olderCompleted];
+  }
+
+  private contentLineBudget(): number {
+    const rows = this.tui?.terminal.rows;
+    if (!rows) return MAX_LINES;
+    return Math.min(MAX_LINES, Math.max(3, rows - RESERVED_TERMINAL_ROWS));
+  }
+
+  private render(theme: Theme, width: number): string[] {
+    const tasks = this.reconcileVisibleTasks();
+    if (tasks.length === 0) return [];
+
+    const completed = tasks.filter((task) => task.status === "completed").length;
+    const active = tasks.some((task) => task.status === "pending" || task.status === "in_progress");
+    const heading = `${theme.fg(active ? "accent" : "dim", active ? "●" : "○")} ${theme.fg(
+      active ? "accent" : "dim",
+      `Tasks (${completed}/${tasks.length})`,
+    )}`;
+    const truncate = (line: string) => truncateToWidth(line, width, "…");
+    if (this.collapsed) return [truncate(heading), truncate(theme.fg("dim", "└─ ctrl+shift+t to expand")), ""];
+
+    const expanded = this.ui?.getToolsExpanded() === true;
+    const contentBudget = expanded ? tasks.length + 1 : this.contentLineBudget();
+    const bodyBudget = Math.max(1, contentBudget - 1);
+    const needsSummary = tasks.length > bodyBudget;
+    const shownCount = needsSummary ? Math.max(0, bodyBudget - 1) : tasks.length;
+    const ordered = needsSummary ? this.prioritized(tasks) : [...tasks].sort(byId);
+    const shown = ordered.slice(0, shownCount);
+    const hidden = ordered.slice(shownCount);
+
+    const lines = [truncate(heading)];
+    for (const task of shown) {
+      lines.push(truncate(`${theme.fg("dim", "├─")} ${formatTaskLine(task, tasks, theme)}`));
+      if (task.status === "completed") this.completedPendingHide.add(task.id);
+    }
+
+    if (hidden.length > 0) {
+      const parts: string[] = [];
+      const hiddenInProgress = hidden.filter((task) => task.status === "in_progress").length;
+      const hiddenPending = hidden.filter((task) => task.status === "pending").length;
+      const hiddenCompleted = hidden.filter((task) => task.status === "completed").length;
+      if (hiddenInProgress) parts.push(`${hiddenInProgress} in progress`);
+      if (hiddenPending) parts.push(`${hiddenPending} pending`);
+      if (hiddenCompleted) parts.push(`${hiddenCompleted} completed`);
+      lines.push(
+        truncate(`${theme.fg("dim", "└─")} ${theme.fg("dim", `+${hidden.length} more (${parts.join(", ")})`)}`),
+      );
+    } else if (lines.length > 1) {
+      lines[lines.length - 1] = lines[lines.length - 1].replace("├─", "└─");
+    }
+
+    lines.push("");
+    return lines;
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@riverai7z/pi-todo",
+  "version": "0.1.0",
+  "description": "Claude Code-style task list tools for Pi",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "todo",
+    "task-management"
+  ],
+  "files": [
+    "index.ts",
+    "state.ts",
+    "overlay.ts",
+    "README.md",
+    "DESIGN.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "dependencies": {
+    "typebox": "^1.1.24"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  }
+}

package/state.ts

@@ -0,0 +1,326 @@
+export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+
+export interface Task {
+  id: string;
+  subject: string;
+  description: string;
+  activeForm?: string;
+  status: TaskStatus;
+  owner?: string;
+  blockedBy: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface TaskState {
+  tasks: Task[];
+  nextId: number;
+}
+
+export interface TaskSnapshot {
+  action: "create" | "get" | "list" | "update";
+  tasks: Task[];
+  nextId: number;
+  error?: string;
+}
+
+const EMPTY_STATE: TaskState = { tasks: [], nextId: 1 };
+const TOOL_NAMES = new Set(["TaskCreate", "TaskGet", "TaskList", "TaskUpdate"]);
+const sessions = new Map<string, TaskState>();
+let foregroundSession = "";
+
+const VALID_TRANSITIONS: Record<TaskStatus, ReadonlySet<TaskStatus>> = {
+  pending: new Set(["in_progress", "completed", "deleted"]),
+  in_progress: new Set(["pending", "completed", "deleted"]),
+  completed: new Set(["pending", "in_progress", "deleted"]),
+  deleted: new Set(),
+};
+
+function cloneTask(task: Task): Task {
+  return {
+    ...task,
+    blockedBy: [...task.blockedBy],
+    ...(task.metadata ? { metadata: { ...task.metadata } } : {}),
+  };
+}
+
+function cloneState(state: TaskState): TaskState {
+  return { tasks: state.tasks.map(cloneTask), nextId: state.nextId };
+}
+
+function isTask(value: unknown): value is Task {
+  if (!value || typeof value !== "object") return false;
+  const task = value as Partial<Task>;
+  return (
+    typeof task.id === "string" &&
+    typeof task.subject === "string" &&
+    typeof task.description === "string" &&
+    ["pending", "in_progress", "completed", "deleted"].includes(task.status ?? "") &&
+    Array.isArray(task.blockedBy) &&
+    task.blockedBy.every((id) => typeof id === "string")
+  );
+}
+
+function isSnapshot(value: unknown): value is TaskSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const snapshot = value as Partial<TaskSnapshot>;
+  return Array.isArray(snapshot.tasks) && snapshot.tasks.every(isTask) && Number.isInteger(snapshot.nextId);
+}
+
+export function sessionId(ctx: { sessionManager: { getSessionId(): string } }): string {
+  return ctx.sessionManager.getSessionId() ?? "";
+}
+
+export function getState(id: string): TaskState {
+  return sessions.get(id) ?? cloneState(EMPTY_STATE);
+}
+
+export function getForegroundState(): TaskState {
+  return getState(foregroundSession);
+}
+
+export function setForegroundSession(id: string): void {
+  foregroundSession = id;
+}
+
+export function getForegroundSession(): string {
+  return foregroundSession;
+}
+
+export function clearForegroundSession(): void {
+  foregroundSession = "";
+}
+
+export function evictSession(id: string): void {
+  sessions.delete(id);
+}
+
+export function replayState(ctx: { sessionManager: { getBranch(): Iterable<unknown> } }): TaskState {
+  let state = cloneState(EMPTY_STATE);
+  for (const rawEntry of ctx.sessionManager.getBranch()) {
+    const entry = rawEntry as {
+      type?: string;
+      message?: { role?: string; toolName?: string; details?: unknown };
+    };
+    if (entry.type !== "message" || entry.message?.role !== "toolResult") continue;
+    if (!entry.message.toolName || !TOOL_NAMES.has(entry.message.toolName)) continue;
+    if (isSnapshot(entry.message.details)) {
+      state = { tasks: entry.message.details.tasks.map(cloneTask), nextId: entry.message.details.nextId };
+    }
+  }
+  return state;
+}
+
+export function replaceState(id: string, state: TaskState): void {
+  sessions.set(id, cloneState(state));
+}
+
+export function snapshot(action: TaskSnapshot["action"], state: TaskState, error?: string): TaskSnapshot {
+  return {
+    action,
+    tasks: state.tasks.map(cloneTask),
+    nextId: state.nextId,
+    ...(error ? { error } : {}),
+  };
+}
+
+export function deriveBlocks(tasks: readonly Task[], taskId: string): string[] {
+  return tasks.filter((task) => task.blockedBy.includes(taskId)).map((task) => task.id);
+}
+
+export function unresolvedBlockers(task: Task, tasks: readonly Task[]): string[] {
+  const resolved = new Set(
+    tasks.filter((candidate) => candidate.status === "completed" || candidate.status === "deleted").map((candidate) => candidate.id),
+  );
+  return task.blockedBy.filter((id) => !resolved.has(id));
+}
+
+function graphHasCycle(tasks: readonly Task[]): boolean {
+  const edges = new Map(tasks.map((task) => [task.id, task.blockedBy] as const));
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  const visit = (id: string): boolean => {
+    if (visiting.has(id)) return true;
+    if (visited.has(id)) return false;
+    visiting.add(id);
+    for (const dependency of edges.get(id) ?? []) {
+      if (visit(dependency)) return true;
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  };
+
+  return [...edges.keys()].some(visit);
+}
+
+function requireTask(tasks: readonly Task[], id: string, field: string): string | undefined {
+  const task = tasks.find((candidate) => candidate.id === id);
+  if (!task) return `${field}: task #${id} not found`;
+  if (task.status === "deleted") return `${field}: task #${id} is deleted`;
+  return undefined;
+}
+
+function mutateDependencies(
+  target: Task,
+  additions: readonly string[] = [],
+  removals: readonly string[] = [],
+): boolean {
+  const next = target.blockedBy.filter((dependency) => !removals.includes(dependency));
+  for (const dependency of additions) {
+    if (!next.includes(dependency)) next.push(dependency);
+  }
+  if (next.length === target.blockedBy.length && next.every((value, index) => value === target.blockedBy[index])) {
+    return false;
+  }
+  target.blockedBy = next;
+  return true;
+}
+
+export function createTask(
+  id: string,
+  input: {
+    subject: string;
+    description: string;
+    activeForm?: string;
+    metadata?: Record<string, unknown>;
+  },
+): { state: TaskState; task: Task } {
+  const current = getState(id);
+  const task: Task = {
+    id: String(current.nextId),
+    subject: input.subject.trim(),
+    description: input.description.trim(),
+    activeForm: input.activeForm?.trim() || undefined,
+    status: "pending",
+    blockedBy: [],
+    metadata: input.metadata ? { ...input.metadata } : undefined,
+  };
+  const state = { tasks: [...current.tasks.map(cloneTask), task], nextId: current.nextId + 1 };
+  sessions.set(id, state);
+  return { state, task };
+}
+
+export function getTask(id: string, taskId: string): Task | undefined {
+  return getState(id).tasks.find((task) => task.id === taskId);
+}
+
+export function listTasks(id: string, includeDeleted = false): Task[] {
+  return getState(id).tasks.filter((task) => includeDeleted || task.status !== "deleted");
+}
+
+export interface TaskUpdateInput {
+  subject?: string;
+  description?: string;
+  activeForm?: string;
+  status?: TaskStatus;
+  owner?: string;
+  addBlocks?: string[];
+  addBlockedBy?: string[];
+  removeBlocks?: string[];
+  removeBlockedBy?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export function updateTask(
+  session: string,
+  taskId: string,
+  input: TaskUpdateInput,
+): { state: TaskState; task?: Task; updatedFields: string[]; error?: string; statusChange?: { from: TaskStatus; to: TaskStatus } } {
+  const current = getState(session);
+  const tasks = current.tasks.map(cloneTask);
+  const index = tasks.findIndex((task) => task.id === taskId);
+  if (index < 0) return { state: current, updatedFields: [], error: "Task not found" };
+
+  const before = cloneTask(tasks[index]);
+  if (before.status === "deleted") {
+    return { state: current, task: before, updatedFields: [], error: `Task #${taskId} is deleted` };
+  }
+  if (input.subject !== undefined && !input.subject.trim()) {
+    return { state: current, task: before, updatedFields: [], error: "Task subject cannot be empty" };
+  }
+  if (input.description !== undefined && !input.description.trim()) {
+    return { state: current, task: before, updatedFields: [], error: "Task description cannot be empty" };
+  }
+  if (input.status && input.status !== before.status && !VALID_TRANSITIONS[before.status].has(input.status)) {
+    return {
+      state: current,
+      task: before,
+      updatedFields: [],
+      error: `Illegal status transition: ${before.status} → ${input.status}`,
+    };
+  }
+
+  for (const [field, ids] of [
+    ["addBlocks", input.addBlocks],
+    ["addBlockedBy", input.addBlockedBy],
+  ] as const) {
+    for (const dependencyId of ids ?? []) {
+      if (dependencyId === taskId) {
+        return { state: current, task: before, updatedFields: [], error: `Task #${taskId} cannot depend on itself` };
+      }
+      const error = requireTask(tasks, dependencyId, field);
+      if (error) return { state: current, task: before, updatedFields: [], error };
+    }
+  }
+
+  const updatedFields: string[] = [];
+  const task = tasks[index];
+  if (input.subject !== undefined && task.subject !== input.subject.trim()) {
+    task.subject = input.subject.trim();
+    updatedFields.push("subject");
+  }
+  if (input.description !== undefined && task.description !== input.description.trim()) {
+    task.description = input.description.trim();
+    updatedFields.push("description");
+  }
+  if (input.activeForm !== undefined && task.activeForm !== input.activeForm.trim()) {
+    task.activeForm = input.activeForm.trim();
+    updatedFields.push("activeForm");
+  }
+  if (input.owner !== undefined && task.owner !== input.owner.trim()) {
+    task.owner = input.owner.trim();
+    updatedFields.push("owner");
+  }
+
+  let statusChange: { from: TaskStatus; to: TaskStatus } | undefined;
+  if (input.status && input.status !== task.status) {
+    statusChange = { from: task.status, to: input.status };
+    task.status = input.status;
+    updatedFields.push("status");
+  }
+
+  if (mutateDependencies(task, input.addBlockedBy, input.removeBlockedBy)) updatedFields.push("blockedBy");
+
+  let blocksChanged = false;
+  for (const blockedId of input.addBlocks ?? []) {
+    const target = tasks.find((candidate) => candidate.id === blockedId)!;
+    if (mutateDependencies(target, [taskId])) blocksChanged = true;
+  }
+  for (const blockedId of input.removeBlocks ?? []) {
+    const target = tasks.find((candidate) => candidate.id === blockedId);
+    if (target && mutateDependencies(target, [], [taskId])) blocksChanged = true;
+  }
+  if (blocksChanged) updatedFields.push("blocks");
+
+  if (graphHasCycle(tasks)) {
+    return { state: current, task: before, updatedFields: [], error: "Dependency update would create a cycle" };
+  }
+
+  if (input.metadata !== undefined) {
+    const merged = { ...(task.metadata ?? {}) };
+    for (const [key, value] of Object.entries(input.metadata)) {
+      if (value === null) delete merged[key];
+      else merged[key] = value;
+    }
+    const next = Object.keys(merged).length ? merged : undefined;
+    if (JSON.stringify(next) !== JSON.stringify(task.metadata)) {
+      task.metadata = next;
+      updatedFields.push("metadata");
+    }
+  }
+
+  const state = { tasks, nextId: current.nextId };
+  sessions.set(session, state);
+  return { state, task: cloneTask(task), updatedFields, statusChange };
+}