@pi-archimedes/todo 1.2.0

package/README.md

@@ -0,0 +1,86 @@
+# @pi-archimedes/todo
+
+Todo list management with auto-clear and live subagent visibility for the [Pi coding agent](https://github.com/earendil-works/pi).
+
+## Features
+
+- **`manage_todo_list` tool** — structured todo tracking with `read` and `write` operations
+- **Auto-clear** — when all todos are completed, the list clears itself after a brief 2-second delay
+- **Multi-column widget** — main agent todos on the left, each subagent's todos in their own column to the right
+- **Live subagent visibility** — subagent todos stream through the core bus so you can see what they're working on
+- **`/todos` command** — toggle the widget or clear todos (`/todos clear`)
+- **Session persistence** — todos survive `/reload` via session branch reconstruction
+
+## Screenshots
+
+### Multiple todos with progress tracking
+
+Widget showing three todos with completion status — completed items dimmed with strikethrough, in-progress highlighted:
+
+![todos multiple todos](../../docs/images/todos-multiple-todos.png)
+
+### Main agent + subagent side by side
+
+Main agent todos (left) alongside a subagent's todos (right), separated by a divider. Subagent column auto-removes when the subagent finishes:
+
+![todos and subagent](../../docs/images/todos-and-subagent.png)
+
+## Installation
+
+```bash
+pi install @pi-archimedes/todo
+```
+
+Or install the full [pi-archimedes](../..) meta package for the integrated experience:
+
+```bash
+pi install pi-archimedes
+```
+
+## Usage
+
+### As a tool
+
+The `manage_todo_list` tool accepts two operations:
+
+**Read current todos:**
+
+```jsonc
+{
+  "operation": "read"
+}
+```
+
+**Write (replace) the todo list:**
+
+```jsonc
+{
+  "operation": "write",
+  "todoList": [
+    { "id": 1, "title": "Parse config files", "description": "Read and validate all config files", "status": "in-progress" },
+    { "id": 2, "title": "Build state manager", "description": "Implement TodoStateManager class", "status": "not-started" },
+    { "id": 3, "title": "Wire up widget", "description": "Connect widget to bus events", "status": "not-started" }
+  ]
+}
+```
+
+### As a command
+
+- `/todos` — toggle the todo widget visibility
+- `/todos clear` — clear all todos immediately
+
+## Todo statuses
+
+| Status | Icon | Description |
+|--------|------|-------------|
+| `not-started` | ○ | Not yet begun |
+| `in-progress` | ◉ | Currently being worked on |
+| `completed` | ✓ | Fully finished |
+
+## Auto-clear
+
+When all todos in the list are marked `completed`, the widget shows the all-done state for 2 seconds, then auto-clears. No need to manually run `/todos clear`.
+
+## Subagent integration
+
+When installed via `pi-archimedes` (the meta package), subagent todo events flow through `@pi-archimedes/core/bus` and appear as separate columns in the widget. Each subagent gets its own column labeled with its agent name. The column auto-removes when the subagent finishes.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@pi-archimedes/todo",
+  "version": "1.2.0",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "description": "Todo list tool with auto-clear and subagent visibility",
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "dependencies": {
+    "@pi-archimedes/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.1.0",
+    "@earendil-works/pi-coding-agent": ">=0.1.0",
+    "@earendil-works/pi-tui": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.0"
+  },
+  "pi": {
+    "image": "https://raw.githubusercontent.com/danielcherubini/pi-archimedes/main/docs/images/todos-and-subagent.png"
+  }
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { getBus, Events } from "@pi-archimedes/core/bus";
+import { TodoStateManager } from "./state-manager.js";
+import { createManageTodoListTool } from "./tool.js";
+import { updateWidget, clearWidget } from "./ui/todo-widget.js";
+import type { TodoItem } from "./types.js";
+
+export default function (pi: ExtensionAPI): void {
+  registerTodo(pi);
+}
+
+export function registerTodo(pi: ExtensionAPI): void {
+  const state = new TodoStateManager();
+  const subagentTodos = new Map<string, TodoItem[]>();
+  const unsubscribes: Array<() => void> = [];
+  let currentCtx: ExtensionContext | undefined;
+
+  const refreshWidget = () => {
+    if (currentCtx) {
+      updateWidget(state, currentCtx, subagentTodos);
+    }
+  };
+
+  // Subscribe to bus events for subagent todos
+  const unsubTodosUpdate = getBus().on(Events.TODOS_UPDATE, (payload: unknown) => {
+    const data = payload as { source: string; todos: TodoItem[] };
+    if (data.source === "main") return; // main handled locally
+    subagentTodos.set(data.source, data.todos);
+    refreshWidget();
+  });
+  unsubscribes.push(unsubTodosUpdate);
+
+  const unsubTodosClear = getBus().on(Events.TODOS_CLEAR, (payload: unknown) => {
+    const data = payload as { source: string };
+    subagentTodos.delete(data.source);
+    refreshWidget();
+  });
+  unsubscribes.push(unsubTodosClear);
+
+  // Reconstruct state from session on load/resume/fork/tree
+  const reconstructState = (ctx: ExtensionContext) => {
+    currentCtx = ctx;
+    state.loadFromSession(ctx);
+    updateWidget(state, ctx, subagentTodos);
+  };
+
+  pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
+
+  // Keep ctx reference fresh on every turn
+  pi.on("turn_start", async (_event, ctx) => {
+    currentCtx = ctx;
+  });
+
+  // Update widget after each turn (in case tool was called)
+  pi.on("turn_end", async (_event, ctx) => {
+    currentCtx = ctx;
+    updateWidget(state, ctx, subagentTodos);
+  });
+
+  // session_shutdown handler (top-level to prevent accumulation on /reload)
+  pi.on("session_shutdown", (_event, _ctx) => {
+    unsubscribes.forEach((unsub) => unsub());
+    unsubscribes.length = 0;
+    subagentTodos.clear();
+    state.cancelAutoClear();
+    if (currentCtx) {
+      clearWidget(currentCtx);
+    }
+  });
+
+  // Register the manage_todo_list tool
+  const tool = createManageTodoListTool(state, refreshWidget);
+  pi.registerTool(tool);
+
+  // Register /todos command
+  pi.registerCommand("todos", {
+    description: "Toggle todo list widget or clear todos (/todos clear)",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      currentCtx = ctx;
+
+      if (args?.trim().toLowerCase() === "clear") {
+        state.clear();
+        clearWidget(ctx);
+        ctx.ui.notify("Todo list cleared.", "info");
+        return;
+      }
+
+      const todos = state.read();
+      if (todos.length === 0) {
+        ctx.ui.notify("No todos. The LLM will create them when working on complex tasks.", "info");
+      } else {
+        updateWidget(state, ctx, subagentTodos);
+        const stats = state.getStats();
+        ctx.ui.notify(`${stats.completed}/${stats.total} todos completed.`, "info");
+      }
+    },
+  });
+}

package/src/state-manager.ts

@@ -0,0 +1,93 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TodoItem, TodoStats, ValidationResult } from "./types.js";
+
+/** Manages the in-memory todo list state. */
+export class TodoStateManager {
+  private todos: TodoItem[] = [];
+  private autoClearTimer: ReturnType<typeof setTimeout> | undefined;
+
+  read(): TodoItem[] {
+    return [...this.todos];
+  }
+
+  write(todos: TodoItem[]): void {
+    this.cancelAutoClear();
+    this.todos = todos.map((t) => ({ ...t }));
+    // If all completed and non-empty, schedule auto-clear
+    if (todos.length > 0 && todos.every((t) => t.status === "completed")) {
+      this.scheduleAutoClear(() => this.clear());
+    }
+  }
+
+  clear(): void {
+    this.cancelAutoClear();
+    this.todos = [];
+  }
+
+  getStats(): TodoStats {
+    const total = this.todos.length;
+    const completed = this.todos.filter((t) => t.status === "completed").length;
+    const inProgress = this.todos.filter((t) => t.status === "in-progress").length;
+    const notStarted = this.todos.filter((t) => t.status === "not-started").length;
+    return { total, completed, inProgress, notStarted };
+  }
+
+  validate(todos: TodoItem[]): ValidationResult {
+    const errors: string[] = [];
+    if (!Array.isArray(todos)) {
+      return { valid: false, errors: ["todoList must be an array"] };
+    }
+    const validStatuses = new Set(["not-started", "in-progress", "completed"]);
+    for (let i = 0; i < todos.length; i++) {
+      const item = todos[i];
+      const prefix = `Item ${i + 1}`;
+      if (!item) {
+        errors.push(`${prefix}: undefined item`);
+        continue;
+      }
+      if (item.id == null) {
+        errors.push(`${prefix}: missing 'id'`);
+      } else if (typeof item.id !== "number") {
+        errors.push(`${prefix}: 'id' must be a number`);
+      }
+      if (!item.title || typeof item.title !== "string") {
+        errors.push(`${prefix}: missing or invalid 'title'`);
+      }
+      if (!item.description || typeof item.description !== "string") {
+        errors.push(`${prefix}: missing or invalid 'description'`);
+      }
+      if (!item.status || !validStatuses.has(item.status)) {
+        errors.push(`${prefix}: 'status' must be one of: not-started, in-progress, completed`);
+      }
+    }
+    return { valid: errors.length === 0, errors };
+  }
+
+  loadFromSession(ctx: ExtensionContext): void {
+    this.todos = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "message") continue;
+      const msg = entry.message;
+      if (msg.role !== "toolResult" || msg.toolName !== "manage_todo_list") continue;
+      const details = msg.details as { todos?: TodoItem[] } | undefined;
+      if (details?.todos) {
+        this.todos = details.todos.map((t) => ({ ...t }));
+      }
+    }
+  }
+
+  scheduleAutoClear(callback: () => void): void {
+    this.cancelAutoClear();
+    this.autoClearTimer = setTimeout(() => {
+      this.autoClearTimer = undefined;
+      callback();
+    }, 2000);
+  }
+
+  cancelAutoClear(): void {
+    if (this.autoClearTimer) {
+      clearTimeout(this.autoClearTimer);
+      this.autoClearTimer = undefined;
+    }
+  }
+}

package/src/tool.ts

@@ -0,0 +1,196 @@
+import { type Static, StringEnum, Type } from "@earendil-works/pi-ai";
+import type { AgentToolResult, ExtensionContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { getBus, Events } from "@pi-archimedes/core/bus";
+import type { TodoStateManager } from "./state-manager.js";
+import { STATUS_ICONS } from "./types.js";
+import type { TodoDetails } from "./types.js";
+
+const TodoItemSchema = Type.Object({
+  id: Type.Number({ description: "Unique identifier for the todo. Use sequential numbers starting from 1." }),
+  title: Type.String({ description: "Concise action-oriented todo label (3-7 words). Displayed in UI." }),
+  description: Type.String({
+    description: "Detailed context, requirements, or implementation notes. Include file paths, specific methods, or acceptance criteria.",
+  }),
+  status: StringEnum(["not-started", "in-progress", "completed"] as const, {
+    description: "not-started: Not begun | in-progress: Currently working (multiple allowed for parallel work) | completed: Fully finished with no blockers",
+  }),
+});
+
+export const ManageTodoListParams = Type.Object({
+  operation: StringEnum(["write", "read"] as const, {
+    description: "write: Replace entire todo list with new content. read: Retrieve current todo list. ALWAYS provide complete list when writing - partial updates not supported.",
+  }),
+  todoList: Type.Optional(
+    Type.Array(TodoItemSchema, {
+      description: "Complete array of all todo items (required for write operation, ignored for read). Must include ALL items - both existing and new.",
+    })
+  ),
+});
+
+export type ManageTodoListInput = Static<typeof ManageTodoListParams>;
+
+export const TOOL_DESCRIPTION = `Manage a structured todo list to track progress and plan tasks throughout your coding session. Use this tool VERY frequently to ensure task visibility and proper planning.
+
+When to use this tool:
+- Complex multi-step work requiring planning and tracking
+- When user provides multiple tasks or requests (numbered, comma-separated)
+- After receiving new instructions that require multiple steps
+- BEFORE starting work on any todo (mark as in-progress)
+- IMMEDIATELY after completing each todo (mark completed individually)
+- When breaking down larger tasks into smaller actionable steps
+- To give users visibility into your progress and planning
+
+When NOT to use:
+- Single, trivial tasks that can be completed in one step
+- Purely conversational/informational requests
+- When just reading files or performing simple searches
+
+CRITICAL workflow:
+1. Plan tasks by writing todo list with specific, actionable items
+2. Mark todo(s) as in-progress before starting work
+3. Complete the work for that specific todo
+4. Mark that todo as completed IMMEDIATELY
+5. Move to next todo and repeat
+
+Todo states:
+- not-started: Todo not yet begun
+- in-progress: Currently working (multiple allowed for parallel work/subagents)
+- completed: Finished successfully
+
+IMPORTANT: Mark todos completed as soon as they are done. Do not batch completions.
+When all todos are completed, the list auto-clears after a brief delay.`;
+
+export function createManageTodoListTool(state: TodoStateManager, onUpdate: () => void) {
+  return {
+    name: "manage_todo_list",
+    label: "Todo List",
+    description: TOOL_DESCRIPTION,
+    parameters: ManageTodoListParams,
+
+    async execute(
+      _toolCallId: string,
+      params: ManageTodoListInput,
+      _signal: AbortSignal | undefined,
+      _onStreamUpdate: undefined,
+      _ctx: ExtensionContext
+    ) {
+      if (params.operation === "read") {
+        const todos = state.read();
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: todos.length
+                ? JSON.stringify(todos, null, 2)
+                : "No todos. Use write operation to create a todo list.",
+            },
+          ],
+          details: { operation: "read", todos } as TodoDetails,
+        };
+      }
+
+      // write
+      const todoList = params.todoList;
+      if (!todoList || !Array.isArray(todoList)) {
+        return {
+          content: [{ type: "text" as const, text: "Error: todoList is required for write operation." }],
+          details: { operation: "write", todos: state.read(), error: "todoList required" } as TodoDetails,
+          isError: true,
+        };
+      }
+
+      const validation = state.validate(todoList);
+      if (!validation.valid) {
+        return {
+          content: [{ type: "text" as const, text: `Validation failed:\n${validation.errors.map((e) => `  - ${e}`).join("\n")}` }],
+          details: { operation: "write", todos: state.read(), error: validation.errors.join("; ") } as TodoDetails,
+          isError: true,
+        };
+      }
+
+      state.write(todoList);
+      onUpdate();
+
+      // Emit bus event for widget update
+      try {
+        getBus().emit(Events.TODOS_UPDATE, { source: "main", todos: state.read() });
+      } catch {
+        // Bus may not be initialized in subagent child process — ignore
+      }
+
+      const stats = state.getStats();
+      const todos = state.read();
+
+      let message = `Todos have been modified successfully. ${stats.completed}/${stats.total} completed. Ensure that you continue to use the todo list to track your progress. Please proceed with the current tasks if applicable.`;
+
+      if (todoList.length < 3) {
+        message += `\n\nWarning: Small todo list (<3 items). This task might not need a todo list.`;
+      }
+
+      return {
+        content: [{ type: "text" as const, text: message }],
+        details: { operation: "write", todos } as TodoDetails,
+      };
+    },
+
+    renderCall(args: ManageTodoListInput, theme: Theme) {
+      let text = theme.fg("toolTitle", theme.bold("manage_todo_list "));
+      text += theme.fg("muted", args.operation);
+
+      if (args.operation === "write" && args.todoList) {
+        const count = args.todoList.length;
+        text += theme.fg("dim", ` (${count} item${count !== 1 ? "s" : ""})`);
+      }
+
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(
+      result: AgentToolResult<TodoDetails | undefined>,
+      { expanded }: ToolRenderResultOptions,
+      theme: Theme
+    ) {
+      const details = result.details;
+      if (!details) {
+        const first = result.content[0];
+        return new Text(first && "text" in first ? first.text : "", 0, 0);
+      }
+
+      if (details.error) {
+        return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
+      }
+
+      const todos = details.todos;
+      const completed = todos.filter((t) => t.status === "completed").length;
+      const total = todos.length;
+
+      if (total === 0) {
+        return new Text(theme.fg("dim", "No todos"), 0, 0);
+      }
+
+      let text = theme.fg("success", "✓ ") + theme.fg("muted", `${completed}/${total} completed`);
+
+      if (expanded) {
+        for (const todo of todos) {
+          const iconChar = STATUS_ICONS[todo.status] ?? "?";
+          const icon =
+            todo.status === "completed"
+              ? theme.fg("success", iconChar)
+              : todo.status === "in-progress"
+                ? theme.fg("warning", iconChar)
+                : theme.fg("dim", iconChar);
+          const title =
+            todo.status === "completed"
+              ? theme.fg("dim", theme.strikethrough(todo.title))
+              : todo.status === "in-progress"
+                ? theme.fg("warning", todo.title)
+                : theme.fg("muted", todo.title);
+          text += `\n  ${icon} ${theme.fg("accent", `${todo.id}.`)} ${title}`;
+        }
+      }
+
+      return new Text(text, 0, 0);
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Core types for the todo list extension.
+ */
+
+/** Status of a single todo item */
+export type TodoStatus = "not-started" | "in-progress" | "completed";
+
+/** A single todo item */
+export interface TodoItem {
+  /** Sequential identifier starting from 1 */
+  id: number;
+  /** Concise action-oriented label (3-7 words). Displayed in UI. */
+  title: string;
+  /** Detailed context, requirements, or implementation notes. */
+  description: string;
+  /** Current status. */
+  status: TodoStatus;
+}
+
+/** Stored in tool result details for session persistence */
+export interface TodoDetails {
+  operation: "read" | "write";
+  todos: TodoItem[];
+  error?: string;
+}
+
+/** Stats about the current todo list */
+export interface TodoStats {
+  total: number;
+  completed: number;
+  inProgress: number;
+  notStarted: number;
+}
+
+/** Validation result */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/** Status icons for each todo state */
+export const STATUS_ICONS: Record<TodoStatus, string> = {
+  "completed": "✓",
+  "in-progress": "◉ ",
+  "not-started": "○",
+};

package/src/ui/todo-widget.ts

@@ -0,0 +1,154 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { STATUS_ICONS } from "../types.js";
+import type { TodoItem } from "../types.js";
+import type { TodoStateManager } from "../state-manager.js";
+
+const WIDGET_ID = "todo-list";
+
+interface Column {
+  header: string;
+  todos: TodoItem[];
+}
+
+/**
+ * Update (or clear) the todo widget.
+ */
+export function updateWidget(
+  state: TodoStateManager,
+  ctx: ExtensionContext,
+  subagentTodos: Map<string, TodoItem[]>,
+): void {
+  const mainTodos = state.read();
+
+  // Hide widget if everything is empty
+  if (mainTodos.length === 0 && subagentTodos.size === 0) {
+    ctx.ui.setWidget(WIDGET_ID, undefined);
+    return;
+  }
+
+  ctx.ui.setWidget(WIDGET_ID, (_tui, theme) => {
+    // Re-read in case state changed since widget was set
+    const currentMain = state.read();
+    const currentSub = new Map(subagentTodos);
+
+    if (currentMain.length === 0 && currentSub.size === 0) {
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      return { render: () => [], invalidate: () => {} };
+    }
+
+    const currentStats = state.getStats();
+
+    // Build columns
+    const columns: Column[] = [];
+
+    // Main column (always first, no header label)
+    if (currentMain.length > 0) {
+      columns.push({ header: "", todos: currentMain });
+    }
+
+    // Subagent columns (sorted by source name)
+    const sortedSources = Array.from(currentSub.keys()).sort();
+    for (const source of sortedSources) {
+      const todos = currentSub.get(source)!;
+      if (todos.length > 0) {
+        const agentName = source.replace("subagent:", "");
+        columns.push({ header: `subagent (${agentName})`, todos });
+      }
+    }
+
+    if (columns.length === 0) {
+      return { render: () => [], invalidate: () => {} };
+    }
+
+    const maxRows = Math.max(...columns.map((c) => c.todos.length));
+
+    return {
+      render(width: number) {
+        const lines: string[] = [];
+
+        // Header line
+        const header =
+          theme.fg("accent", " Todo List ") +
+          theme.fg("muted", ` — ${currentStats.completed}/${currentStats.total} completed`);
+        lines.push(truncateToWidth(header, width));
+
+        // Calculate column widths
+        const numCols = columns.length;
+        const divider = theme.fg("dim", " │ ");
+        const dividerWidth = numCols > 1 ? (numCols - 1) * visibleWidth(divider) : 0;
+        const minColWidth = 20;
+        let colWidth = numCols > 0 ? Math.floor((width - dividerWidth) / numCols) : width;
+        colWidth = Math.max(colWidth, minColWidth);
+
+        // Render subagent headers on row 0
+        const hasSubHeader = columns.some((c) => c.header.length > 0);
+
+        for (let row = 0; row < maxRows; row++) {
+          const cellParts: string[] = [];
+
+          for (const column of columns) {
+            let cellText: string;
+
+            if (row === 0 && hasSubHeader && column.header) {
+              cellText = ` ${column.header}`;
+            } else if (row < column.todos.length) {
+              const todo = column.todos[row];
+              if (todo) {
+                const icon = getStatusIcon(todo.status, theme);
+                const idStr = theme.fg("accent", `${todo.id}.`);
+                const title = formatTodoTitle(todo, theme);
+                cellText = ` ${icon} ${idStr} ${title}`;
+              } else {
+                cellText = "";
+              }
+            } else {
+              cellText = "";
+            }
+
+            // Truncate and pad to column width
+            const visible = visibleWidth(cellText);
+            if (visible > colWidth) {
+              // Truncate
+              const truncated = truncateToWidth(cellText, colWidth);
+              cellParts.push(truncated);
+            } else {
+              // Pad
+              const padding = " ".repeat(colWidth - visible);
+              cellParts.push(cellText + padding);
+            }
+          }
+
+          // Join columns with dividers
+          let line = cellParts.join(divider);
+          lines.push(truncateToWidth(line, width));
+        }
+
+        return lines;
+      },
+      invalidate: () => {},
+    };
+  });
+}
+
+function getStatusIcon(status: TodoItem["status"], theme: Theme): string {
+  const icon = STATUS_ICONS[status] ?? "?";
+  if (status === "completed") return theme.fg("success", icon);
+  if (status === "in-progress") return theme.fg("warning", icon.trim());
+  return theme.fg("dim", icon);
+}
+
+function formatTodoTitle(todo: TodoItem, theme: Theme): string {
+  if (todo.status === "completed") {
+    return theme.fg("dim", theme.strikethrough(todo.title));
+  }
+  if (todo.status === "in-progress") {
+    return theme.fg("warning", todo.title);
+  }
+  return theme.fg("muted", todo.title);
+}
+
+/** Clear the widget */
+export function clearWidget(ctx: ExtensionContext): void {
+  ctx.ui.setWidget(WIDGET_ID, undefined);
+}