@narumitw/pi-todo 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+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,146 @@
+# ✅ pi-todo — Keep Multi-Step Work Visible
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-todo)](https://www.npmjs.com/package/@narumitw/pi-todo)
+[![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+Give coding agents a focused todo list for tracking multi-step work above Pi's editor.
+
+The list follows the active session branch and disappears cleanly when no tracked work remains or the session ends.
+
+## ✨ Features
+
+- Registers one `update_todo_list` tool with clear guidance for meaningful multi-step work.
+- Keeps task text concise and action-oriented, with at most one task in progress.
+- Shows a compact themed task list and completion count above the editor in TUI mode.
+- Restores the latest valid list when Pi starts a session or navigates between branches.
+- Restores the exact current list to model context only when compaction removes its latest visible successful tool update.
+- Sanitizes terminal and bidirectional controls before rendering model-provided text.
+- Works without settings, files, network access, or external services.
+
+## 📦 Install
+
+Install persistently from npm:
+
+```bash
+pi install npm:@narumitw/pi-todo
+```
+
+Try from npm without installing permanently:
+
+```bash
+pi -e npm:@narumitw/pi-todo
+```
+
+Build and load this package directly from a repository checkout:
+
+```bash
+npm --workspace @narumitw/pi-todo run build
+pi --no-extensions -e ./packages/pi-todo
+```
+
+The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
+
+Pi extensions run with the user's permissions, so install only trusted code.
+
+## 🚀 Quick start
+
+Ask Pi to perform work with multiple meaningful steps.
+
+The agent can create a concise list through `update_todo_list`, mark one task `in_progress`, and revise the list when the plan changes.
+
+Stable tool guidance tells the agent to update the list immediately after task status changes and to reconcile it before progress reports or the final response.
+
+The agent sends the complete current list with every update and sends an empty list when no tracked work remains.
+
+## 🛠️ Tools
+
+### `update_todo_list`
+
+Replace the complete current todo list for the active session.
+
+Each item has this shape:
+
+```json
+{
+  "text": "Run the focused tests",
+  "status": "in_progress"
+}
+```
+
+Accepted statuses are `pending`, `in_progress`, and `completed`.
+
+A list may contain up to 50 items, each item may contain up to 300 characters, and at most one item may be `in_progress`.
+
+The tool result stores a versioned snapshot in the session branch so branch navigation can reconstruct the latest valid list.
+
+Branch reconstruction also accepts valid results stored under the previous `todo_widget` name, but the extension only registers `update_todo_list` for new calls.
+
+During ordinary turns, the model reads the complete list from the persisted `update_todo_list` assistant tool call, while its successful result confirms the active state and preserves append-only prompt history.
+
+If compaction or branch context construction removes that matching call/result pair, the extension appends one hidden, non-persistent state-only fallback containing the current list as JSON data.
+
+The fallback stays at the end of model context until a later valid todo tool call and successful result become visible, and it is omitted when the list is cleared.
+
+In TUI mode, updates appear immediately in a widget above the editor.
+
+The widget header shows completed and total task counts, followed by themed completed, in-progress, and pending rows.
+Long task text wraps to the available terminal width with continuation lines aligned beneath the text.
+
+In RPC, print, and JSON modes, the tool still returns structured details but does not create a visual widget.
+
+## 🔒 Security and privacy
+
+The extension does not read or write files, start processes, access credentials, or make network requests.
+
+Task text is stored in Pi's normal session tool results and therefore follows the user's existing session persistence choices.
+
+Terminal escape sequences, control characters, and bidirectional display controls are removed at the rendering boundary without changing the stored tool payload.
+
+## 🚧 Limitations
+
+- The visual widget uses a fixed position above the editor and is available only in TUI mode.
+- The extension provides a model tool rather than a slash command or manual task editor.
+- The extension reminds the model to update statuses but cannot infer task completion or force a tool call.
+- Branch reconstruction uses only valid versioned `update_todo_list` or legacy `todo_widget` tool results on the active branch.
+- The widget has no independent scrolling or height-based collapsing, so Pi may clip later rows when terminal height is constrained.
+
+## 🗂️ Package layout
+
+```text
+packages/pi-todo/
+├── dist/
+│   └── index.ts              # Generated Jiti runtime entrypoint
+├── scripts/
+│   └── build-runtime.mjs     # Deterministic runtime builder and validator
+├── src/
+│   ├── index.ts              # Thin authoritative extension forwarder
+│   └── todo-widget.ts        # Tool, lifecycle, state reconstruction, and rendering
+├── test/
+│   ├── build-runtime.test.ts # Build, boundary, and Jiti loader coverage
+│   └── todo-widget.test.ts   # Extension behavior coverage
+├── LICENSE
+├── README.md
+├── package.json
+└── tsconfig.json
+```
+
+The package exposes its Pi extension through `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./dist/index.ts"]
+  }
+}
+```
+
+## 🔎 Keywords
+
+Pi extension, coding agent, todo list, task progress, session widget, TypeScript Pi package.
+
+## 📄 License
+
+MIT.
+
+See [`LICENSE`](./LICENSE).

package/dist/index.ts

@@ -0,0 +1,264 @@
+// @generated by scripts/build-runtime.mjs; do not edit.
+// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
+
+// src/todo-widget.ts
+import { StringEnum } from "@earendil-works/pi-ai";
+import { stripTerminalSequences, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+var TOOL_NAME = "update_todo_list";
+var WIDGET_KEY = "todo";
+var TODO_CONTEXT_MESSAGE_TYPE = "todo-list-status";
+var TODO_CONTEXT_VERSION = 1;
+var TODO_DETAILS_VERSION = 1;
+var MAX_TODO_ITEMS = 50;
+var MAX_TODO_TEXT_LENGTH = 300;
+var WIDGET_OPTIONS = { placement: "aboveEditor" };
+var LEGACY_TOOL_NAME = "todo_widget";
+var TODO_STATUSES = ["pending", "in_progress", "completed"];
+var BIDI_CONTROLS = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+var TodoParameters = Type.Object({
+  items: Type.Array(
+    Type.Object({
+      text: Type.String({
+        minLength: 1,
+        maxLength: MAX_TODO_TEXT_LENGTH,
+        description: "A concise, action-oriented task"
+      }),
+      status: StringEnum(TODO_STATUSES, {
+        description: "The task's current status"
+      })
+    }),
+    {
+      maxItems: MAX_TODO_ITEMS,
+      description: "The complete current todo list; send an empty list to clear it"
+    }
+  )
+});
+function todoWidgetExtension(pi) {
+  let activeSession;
+  let items = [];
+  const ownsSession = (ctx) => ctx.sessionManager === activeSession;
+  const publish = (ctx) => {
+    if (!ownsSession(ctx) || ctx.mode !== "tui") return;
+    if (items.length === 0) {
+      ctx.ui.setWidget(WIDGET_KEY, void 0);
+      return;
+    }
+    const snapshot = cloneItems(items);
+    ctx.ui.setWidget(
+      WIDGET_KEY,
+      (_tui, theme) => ({
+        render: (width) => renderTodoWidget(snapshot, theme, width),
+        invalidate: () => {
+        }
+      }),
+      WIDGET_OPTIONS
+    );
+  };
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: "Todo List",
+    description: "Replace the current session todo list with the complete supplied list. Call update_todo_list whenever actual task state changes; keep at most one item in_progress and send an empty list to clear it.",
+    promptSnippet: "Maintain the complete session todo list as multi-step work progresses",
+    promptGuidelines: [
+      "Use update_todo_list to track work with multiple meaningful steps; skip it for simple, single-step tasks.",
+      "Use update_todo_list to keep the list aligned with actual work: mark a task in_progress before starting it, mark it completed as soon as it finishes, and revise the list before continuing when the plan changes.",
+      "Before a progress report or final response, call update_todo_list to reconcile every item with actual work; do not report completion while the list is stale.",
+      "On every update_todo_list call, send the complete current list, keep at most one task in_progress, and send an empty list when no tracked work remains."
+    ],
+    parameters: TodoParameters,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      if (!ownsSession(ctx)) {
+        throw new Error("Cannot update the todo list because the session changed.");
+      }
+      validateItems(params.items);
+      items = cloneItems(params.items);
+      publish(ctx);
+      const details = {
+        version: TODO_DETAILS_VERSION,
+        items: cloneItems(items)
+      };
+      if (items.length === 0) {
+        return {
+          content: [{ type: "text", text: "Todo list cleared." }],
+          details
+        };
+      }
+      const completed = items.filter((item) => item.status === "completed").length;
+      const inProgress = items.some((item) => item.status === "in_progress");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Todo list updated: ${completed} of ${items.length} complete${inProgress ? "; 1 in progress" : ""}.`
+          }
+        ],
+        details
+      };
+    }
+  });
+  pi.on("session_start", (_event, ctx) => {
+    activeSession = ctx.sessionManager;
+    items = reconstructItems(ctx.sessionManager.getBranch());
+    publish(ctx);
+  });
+  pi.on("context", (event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    const messages = reconcileTodoContext(event.messages, items);
+    if (messages !== event.messages) return { messages };
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    items = reconstructItems(ctx.sessionManager.getBranch());
+    publish(ctx);
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    if (ctx.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, void 0);
+    items = [];
+    activeSession = void 0;
+  });
+}
+function renderTodoWidget(items, theme, width) {
+  const completed = items.filter((item) => item.status === "completed").length;
+  const divider = theme.fg("borderMuted", "\u2500".repeat(Math.max(0, width)));
+  const lines = [divider, theme.fg("muted", `Todo \xB7 ${completed}/${items.length} complete`)];
+  const renderWidth = Math.max(0, width);
+  for (const item of items) {
+    const text = sanitizeTodoText(item.text);
+    let prefix;
+    let styledText;
+    switch (item.status) {
+      case "completed":
+        prefix = theme.fg("success", "\u2713 ");
+        styledText = theme.fg("muted", theme.strikethrough(text));
+        break;
+      case "in_progress":
+        prefix = theme.fg("accent", "\u25B6 ");
+        styledText = theme.fg("accent", theme.bold(text));
+        break;
+      case "pending":
+        prefix = theme.fg("dim", "\u25CB ");
+        styledText = theme.fg("text", text);
+        break;
+    }
+    if (renderWidth <= 2) {
+      lines.push(prefix);
+      continue;
+    }
+    const wrappedText = wrapTextWithAnsi(styledText, renderWidth - 2);
+    lines.push(...wrappedText.map((line, index) => `${index === 0 ? prefix : "  "}${line}`));
+  }
+  return lines.map((line) => truncateToWidth(line, renderWidth, ""));
+}
+function reconcileTodoContext(messages, items) {
+  const existing = messages.filter(isTodoContextMessage);
+  const withoutExisting = messages.filter((message) => !isTodoContextMessage(message));
+  const content = items.length > 0 && !hasModelVisibleTodoState(withoutExisting, items) ? todoContextContent(items) : void 0;
+  if (existing.length === 1 && messages.at(-1) === existing[0] && existing[0]?.content === content) {
+    return messages;
+  }
+  if (existing.length === 0 && content === void 0) return messages;
+  if (content === void 0) return withoutExisting;
+  return [
+    ...withoutExisting,
+    {
+      role: "custom",
+      customType: TODO_CONTEXT_MESSAGE_TYPE,
+      content,
+      display: false,
+      details: { version: TODO_CONTEXT_VERSION },
+      timestamp: 0
+    }
+  ];
+}
+function sanitizeTodoText(value) {
+  let text = "";
+  for (const character of stripTerminalSequences(value).replace(BIDI_CONTROLS, "")) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    const isControl = codePoint <= 31 || codePoint >= 127 && codePoint <= 159;
+    text += isControl ? " " : character;
+  }
+  return text.replace(/\s+/gu, " ").trim();
+}
+function todoContextContent(items) {
+  return `[PI TODO STATUS v${TODO_CONTEXT_VERSION}]
+Current todo list as JSON data:
+${JSON.stringify(items)}`;
+}
+function hasModelVisibleTodoState(messages, items) {
+  const currentResults = /* @__PURE__ */ new Map();
+  for (const message of messages) {
+    if (message.role === "toolResult" && !message.isError && (message.toolName === TOOL_NAME || message.toolName === LEGACY_TOOL_NAME) && isTodoDetails(message.details) && todoItemsEqual(message.details.items, items)) {
+      currentResults.set(message.toolCallId, message.toolName);
+    }
+  }
+  if (currentResults.size === 0) return false;
+  return messages.some(
+    (message) => message.role === "assistant" && message.content.some(
+      (content) => content.type === "toolCall" && currentResults.get(content.id) === content.name && isTodoToolArguments(content.arguments) && todoItemsEqual(content.arguments.items, items)
+    )
+  );
+}
+function isTodoToolArguments(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return isTodoItems(value.items);
+}
+function isTodoContextMessage(message) {
+  return message.role === "custom" && message.customType === TODO_CONTEXT_MESSAGE_TYPE;
+}
+function validateItems(items) {
+  for (const [index, item] of items.entries()) {
+    if (item.text.trim().length === 0) {
+      throw new Error(`Todo item ${index + 1} must contain non-whitespace text.`);
+    }
+  }
+  const currentCount = items.filter((item) => item.status === "in_progress").length;
+  if (currentCount > 1) {
+    throw new Error("Todo list can contain at most one in_progress item.");
+  }
+}
+function reconstructItems(entries) {
+  let restored = [];
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (message.role !== "toolResult" || message.toolName !== TOOL_NAME && message.toolName !== LEGACY_TOOL_NAME) {
+      continue;
+    }
+    if (!isTodoDetails(message.details)) continue;
+    restored = cloneItems(message.details.items);
+  }
+  return restored;
+}
+function isTodoDetails(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value;
+  return record.version === TODO_DETAILS_VERSION && isTodoItems(record.items);
+}
+function isTodoItems(value) {
+  if (!Array.isArray(value) || value.length > MAX_TODO_ITEMS) return false;
+  let currentCount = 0;
+  for (const item of value) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) return false;
+    const candidate = item;
+    if (typeof candidate.text !== "string" || candidate.text.length === 0 || candidate.text.length > MAX_TODO_TEXT_LENGTH || candidate.text.trim().length === 0 || !TODO_STATUSES.includes(candidate.status)) {
+      return false;
+    }
+    if (candidate.status === "in_progress") currentCount += 1;
+  }
+  return currentCount <= 1;
+}
+function todoItemsEqual(left, right) {
+  return left.length === right.length && left.every(
+    (item, index) => item.text === right[index]?.text && item.status === right[index]?.status
+  );
+}
+function cloneItems(items) {
+  return items.map((item) => ({ text: item.text, status: item.status }));
+}
+export {
+  todoWidgetExtension as default
+};
+//# sourceMappingURL=index.ts.map

package/dist/index.ts.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/todo-widget.ts"],
+  "sourcesContent": ["import { StringEnum } from \"@earendil-works/pi-ai\";\nimport type {\n\tContextEvent,\n\tExtensionAPI,\n\tExtensionContext,\n\tSessionEntry,\n\tTheme,\n} from \"@earendil-works/pi-coding-agent\";\nimport { stripTerminalSequences, truncateToWidth, wrapTextWithAnsi } from \"@earendil-works/pi-tui\";\nimport { Type } from \"typebox\";\n\nexport const TOOL_NAME = \"update_todo_list\";\nexport const WIDGET_KEY = \"todo\";\nexport const TODO_CONTEXT_MESSAGE_TYPE = \"todo-list-status\";\nexport const TODO_CONTEXT_VERSION = 1;\nexport const TODO_DETAILS_VERSION = 1;\nexport const MAX_TODO_ITEMS = 50;\nexport const MAX_TODO_TEXT_LENGTH = 300;\n\nconst WIDGET_OPTIONS = { placement: \"aboveEditor\" } as const;\nconst LEGACY_TOOL_NAME = \"todo_widget\";\nconst TODO_STATUSES = [\"pending\", \"in_progress\", \"completed\"] as const;\nconst BIDI_CONTROLS = /[\\u061c\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069]/gu;\n\ntype TodoStatus = (typeof TODO_STATUSES)[number];\n\nexport interface TodoItem {\n\ttext: string;\n\tstatus: TodoStatus;\n}\n\nexport interface TodoDetails {\n\tversion: typeof TODO_DETAILS_VERSION;\n\titems: TodoItem[];\n}\n\nconst TodoParameters = Type.Object({\n\titems: Type.Array(\n\t\tType.Object({\n\t\t\ttext: Type.String({\n\t\t\t\tminLength: 1,\n\t\t\t\tmaxLength: MAX_TODO_TEXT_LENGTH,\n\t\t\t\tdescription: \"A concise, action-oriented task\",\n\t\t\t}),\n\t\t\tstatus: StringEnum(TODO_STATUSES, {\n\t\t\t\tdescription: \"The task's current status\",\n\t\t\t}),\n\t\t}),\n\t\t{\n\t\t\tmaxItems: MAX_TODO_ITEMS,\n\t\t\tdescription: \"The complete current todo list; send an empty list to clear it\",\n\t\t},\n\t),\n});\n\nexport default function todoWidgetExtension(pi: ExtensionAPI): void {\n\tlet activeSession: ExtensionContext[\"sessionManager\"] | undefined;\n\tlet items: TodoItem[] = [];\n\n\tconst ownsSession = (ctx: ExtensionContext): boolean => ctx.sessionManager === activeSession;\n\n\tconst publish = (ctx: ExtensionContext): void => {\n\t\tif (!ownsSession(ctx) || ctx.mode !== \"tui\") return;\n\t\tif (items.length === 0) {\n\t\t\tctx.ui.setWidget(WIDGET_KEY, undefined);\n\t\t\treturn;\n\t\t}\n\n\t\tconst snapshot = cloneItems(items);\n\t\tctx.ui.setWidget(\n\t\t\tWIDGET_KEY,\n\t\t\t(_tui, theme) => ({\n\t\t\t\trender: (width) => renderTodoWidget(snapshot, theme, width),\n\t\t\t\tinvalidate: () => {},\n\t\t\t}),\n\t\t\tWIDGET_OPTIONS,\n\t\t);\n\t};\n\n\tpi.registerTool({\n\t\tname: TOOL_NAME,\n\t\tlabel: \"Todo List\",\n\t\tdescription:\n\t\t\t\"Replace the current session todo list with the complete supplied list. Call update_todo_list whenever actual task state changes; keep at most one item in_progress and send an empty list to clear it.\",\n\t\tpromptSnippet: \"Maintain the complete session todo list as multi-step work progresses\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use update_todo_list to track work with multiple meaningful steps; skip it for simple, single-step tasks.\",\n\t\t\t\"Use update_todo_list to keep the list aligned with actual work: mark a task in_progress before starting it, mark it completed as soon as it finishes, and revise the list before continuing when the plan changes.\",\n\t\t\t\"Before a progress report or final response, call update_todo_list to reconcile every item with actual work; do not report completion while the list is stale.\",\n\t\t\t\"On every update_todo_list call, send the complete current list, keep at most one task in_progress, and send an empty list when no tracked work remains.\",\n\t\t],\n\t\tparameters: TodoParameters,\n\t\tasync execute(_toolCallId, params, signal, _onUpdate, ctx) {\n\t\t\tsignal?.throwIfAborted();\n\t\t\tif (!ownsSession(ctx)) {\n\t\t\t\tthrow new Error(\"Cannot update the todo list because the session changed.\");\n\t\t\t}\n\t\t\tvalidateItems(params.items);\n\n\t\t\titems = cloneItems(params.items);\n\t\t\tpublish(ctx);\n\n\t\t\tconst details: TodoDetails = {\n\t\t\t\tversion: TODO_DETAILS_VERSION,\n\t\t\t\titems: cloneItems(items),\n\t\t\t};\n\t\t\tif (items.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: \"Todo list cleared.\" }],\n\t\t\t\t\tdetails,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst completed = items.filter((item) => item.status === \"completed\").length;\n\t\t\tconst inProgress = items.some((item) => item.status === \"in_progress\");\n\t\t\treturn {\n\t\t\t\tcontent: [\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\ttext: `Todo list updated: ${completed} of ${items.length} complete${inProgress ? \"; 1 in progress\" : \"\"}.`,\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tdetails,\n\t\t\t};\n\t\t},\n\t});\n\n\tpi.on(\"session_start\", (_event, ctx) => {\n\t\tactiveSession = ctx.sessionManager;\n\t\titems = reconstructItems(ctx.sessionManager.getBranch());\n\t\tpublish(ctx);\n\t});\n\n\tpi.on(\"context\", (event, ctx) => {\n\t\tif (!ownsSession(ctx)) return;\n\t\tconst messages = reconcileTodoContext(event.messages, items);\n\t\tif (messages !== event.messages) return { messages };\n\t});\n\n\tpi.on(\"session_tree\", (_event, ctx) => {\n\t\tif (!ownsSession(ctx)) return;\n\t\titems = reconstructItems(ctx.sessionManager.getBranch());\n\t\tpublish(ctx);\n\t});\n\n\tpi.on(\"session_shutdown\", (_event, ctx) => {\n\t\tif (!ownsSession(ctx)) return;\n\t\tif (ctx.mode === \"tui\") ctx.ui.setWidget(WIDGET_KEY, undefined);\n\t\titems = [];\n\t\tactiveSession = undefined;\n\t});\n}\n\nexport function renderTodoWidget(\n\titems: readonly TodoItem[],\n\ttheme: Theme,\n\twidth: number,\n): string[] {\n\tconst completed = items.filter((item) => item.status === \"completed\").length;\n\tconst divider = theme.fg(\"borderMuted\", \"\u2500\".repeat(Math.max(0, width)));\n\tconst lines = [divider, theme.fg(\"muted\", `Todo \u00B7 ${completed}/${items.length} complete`)];\n\n\tconst renderWidth = Math.max(0, width);\n\tfor (const item of items) {\n\t\tconst text = sanitizeTodoText(item.text);\n\t\tlet prefix: string;\n\t\tlet styledText: string;\n\t\tswitch (item.status) {\n\t\t\tcase \"completed\":\n\t\t\t\tprefix = theme.fg(\"success\", \"\u2713 \");\n\t\t\t\tstyledText = theme.fg(\"muted\", theme.strikethrough(text));\n\t\t\t\tbreak;\n\t\t\tcase \"in_progress\":\n\t\t\t\tprefix = theme.fg(\"accent\", \"\u25B6 \");\n\t\t\t\tstyledText = theme.fg(\"accent\", theme.bold(text));\n\t\t\t\tbreak;\n\t\t\tcase \"pending\":\n\t\t\t\tprefix = theme.fg(\"dim\", \"\u25CB \");\n\t\t\t\tstyledText = theme.fg(\"text\", text);\n\t\t\t\tbreak;\n\t\t}\n\n\t\tif (renderWidth <= 2) {\n\t\t\tlines.push(prefix);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst wrappedText = wrapTextWithAnsi(styledText, renderWidth - 2);\n\t\tlines.push(...wrappedText.map((line, index) => `${index === 0 ? prefix : \"  \"}${line}`));\n\t}\n\n\treturn lines.map((line) => truncateToWidth(line, renderWidth, \"\"));\n}\n\nexport function reconcileTodoContext(\n\tmessages: ContextEvent[\"messages\"],\n\titems: readonly TodoItem[],\n): ContextEvent[\"messages\"] {\n\tconst existing = messages.filter(isTodoContextMessage);\n\tconst withoutExisting = messages.filter((message) => !isTodoContextMessage(message));\n\tconst content =\n\t\titems.length > 0 && !hasModelVisibleTodoState(withoutExisting, items)\n\t\t\t? todoContextContent(items)\n\t\t\t: undefined;\n\tif (\n\t\texisting.length === 1 &&\n\t\tmessages.at(-1) === existing[0] &&\n\t\texisting[0]?.content === content\n\t) {\n\t\treturn messages;\n\t}\n\tif (existing.length === 0 && content === undefined) return messages;\n\n\tif (content === undefined) return withoutExisting;\n\treturn [\n\t\t...withoutExisting,\n\t\t{\n\t\t\trole: \"custom\",\n\t\t\tcustomType: TODO_CONTEXT_MESSAGE_TYPE,\n\t\t\tcontent,\n\t\t\tdisplay: false,\n\t\t\tdetails: { version: TODO_CONTEXT_VERSION },\n\t\t\ttimestamp: 0,\n\t\t},\n\t];\n}\n\nexport function sanitizeTodoText(value: string): string {\n\tlet text = \"\";\n\tfor (const character of stripTerminalSequences(value).replace(BIDI_CONTROLS, \"\")) {\n\t\tconst codePoint = character.codePointAt(0) ?? 0;\n\t\tconst isControl = codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);\n\t\ttext += isControl ? \" \" : character;\n\t}\n\treturn text.replace(/\\s+/gu, \" \").trim();\n}\n\nfunction todoContextContent(items: readonly TodoItem[]): string {\n\treturn `[PI TODO STATUS v${TODO_CONTEXT_VERSION}]\nCurrent todo list as JSON data:\n${JSON.stringify(items)}`;\n}\n\nfunction hasModelVisibleTodoState(\n\tmessages: ContextEvent[\"messages\"],\n\titems: readonly TodoItem[],\n): boolean {\n\tconst currentResults = new Map<string, string>();\n\tfor (const message of messages) {\n\t\tif (\n\t\t\tmessage.role === \"toolResult\" &&\n\t\t\t!message.isError &&\n\t\t\t(message.toolName === TOOL_NAME || message.toolName === LEGACY_TOOL_NAME) &&\n\t\t\tisTodoDetails(message.details) &&\n\t\t\ttodoItemsEqual(message.details.items, items)\n\t\t) {\n\t\t\tcurrentResults.set(message.toolCallId, message.toolName);\n\t\t}\n\t}\n\tif (currentResults.size === 0) return false;\n\n\treturn messages.some(\n\t\t(message) =>\n\t\t\tmessage.role === \"assistant\" &&\n\t\t\tmessage.content.some(\n\t\t\t\t(content) =>\n\t\t\t\t\tcontent.type === \"toolCall\" &&\n\t\t\t\t\tcurrentResults.get(content.id) === content.name &&\n\t\t\t\t\tisTodoToolArguments(content.arguments) &&\n\t\t\t\t\ttodoItemsEqual(content.arguments.items, items),\n\t\t\t),\n\t);\n}\n\nfunction isTodoToolArguments(value: unknown): value is { items: TodoItem[] } {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n\treturn isTodoItems((value as Record<string, unknown>).items);\n}\n\nfunction isTodoContextMessage(\n\tmessage: ContextEvent[\"messages\"][number],\n): message is ContextEvent[\"messages\"][number] & { content: string } {\n\treturn message.role === \"custom\" && message.customType === TODO_CONTEXT_MESSAGE_TYPE;\n}\n\nfunction validateItems(items: readonly TodoItem[]): void {\n\tfor (const [index, item] of items.entries()) {\n\t\tif (item.text.trim().length === 0) {\n\t\t\tthrow new Error(`Todo item ${index + 1} must contain non-whitespace text.`);\n\t\t}\n\t}\n\n\tconst currentCount = items.filter((item) => item.status === \"in_progress\").length;\n\tif (currentCount > 1) {\n\t\tthrow new Error(\"Todo list can contain at most one in_progress item.\");\n\t}\n}\n\nfunction reconstructItems(entries: readonly SessionEntry[]): TodoItem[] {\n\tlet restored: TodoItem[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\") continue;\n\t\tconst message = entry.message;\n\t\tif (\n\t\t\tmessage.role !== \"toolResult\" ||\n\t\t\t(message.toolName !== TOOL_NAME && message.toolName !== LEGACY_TOOL_NAME)\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!isTodoDetails(message.details)) continue;\n\t\trestored = cloneItems(message.details.items);\n\t}\n\treturn restored;\n}\n\nfunction isTodoDetails(value: unknown): value is TodoDetails {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return false;\n\tconst record = value as Record<string, unknown>;\n\treturn record.version === TODO_DETAILS_VERSION && isTodoItems(record.items);\n}\n\nfunction isTodoItems(value: unknown): value is TodoItem[] {\n\tif (!Array.isArray(value) || value.length > MAX_TODO_ITEMS) return false;\n\n\tlet currentCount = 0;\n\tfor (const item of value) {\n\t\tif (typeof item !== \"object\" || item === null || Array.isArray(item)) return false;\n\t\tconst candidate = item as Record<string, unknown>;\n\t\tif (\n\t\t\ttypeof candidate.text !== \"string\" ||\n\t\t\tcandidate.text.length === 0 ||\n\t\t\tcandidate.text.length > MAX_TODO_TEXT_LENGTH ||\n\t\t\tcandidate.text.trim().length === 0 ||\n\t\t\t!TODO_STATUSES.includes(candidate.status as TodoStatus)\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\tif (candidate.status === \"in_progress\") currentCount += 1;\n\t}\n\treturn currentCount <= 1;\n}\n\nfunction todoItemsEqual(left: readonly TodoItem[], right: readonly TodoItem[]): boolean {\n\treturn (\n\t\tleft.length === right.length &&\n\t\tleft.every(\n\t\t\t(item, index) => item.text === right[index]?.text && item.status === right[index]?.status,\n\t\t)\n\t);\n}\n\nfunction cloneItems(items: readonly TodoItem[]): TodoItem[] {\n\treturn items.map((item) => ({ text: item.text, status: item.status }));\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@narumitw/pi-todo",
+	"version": "0.0.0",
+	"description": "Pi extension that gives coding agents a persistent session todo widget.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"todo",
+		"task-list",
+		"coding-agent"
+	],
+	"files": [
+		"src",
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./dist/index.ts"
+		]
+	},
+	"piExtension": {
+		"lifecycle": "stable"
+	},
+	"scripts": {
+		"build": "node scripts/build-runtime.mjs",
+		"check": "npm run build && biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"prepack": "npm run build",
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.10",
+		"@earendil-works/pi-ai": "0.84.3",
+		"@earendil-works/pi-coding-agent": "0.84.3",
+		"@earendil-works/pi-tui": "0.84.3",
+		"@types/node": "26.2.0",
+		"esbuild": "0.28.2",
+		"typebox": "1.3.18",
+		"typescript": "7.0.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/narumiruna/pi-extensions.git",
+		"directory": "packages/pi-todo"
+	}
+}

package/src/index.ts

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

package/src/todo-widget.ts

@@ -0,0 +1,354 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type {
+	ContextEvent,
+	ExtensionAPI,
+	ExtensionContext,
+	SessionEntry,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+export const TOOL_NAME = "update_todo_list";
+export const WIDGET_KEY = "todo";
+export const TODO_CONTEXT_MESSAGE_TYPE = "todo-list-status";
+export const TODO_CONTEXT_VERSION = 1;
+export const TODO_DETAILS_VERSION = 1;
+export const MAX_TODO_ITEMS = 50;
+export const MAX_TODO_TEXT_LENGTH = 300;
+
+const WIDGET_OPTIONS = { placement: "aboveEditor" } as const;
+const LEGACY_TOOL_NAME = "todo_widget";
+const TODO_STATUSES = ["pending", "in_progress", "completed"] as const;
+const BIDI_CONTROLS = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+
+type TodoStatus = (typeof TODO_STATUSES)[number];
+
+export interface TodoItem {
+	text: string;
+	status: TodoStatus;
+}
+
+export interface TodoDetails {
+	version: typeof TODO_DETAILS_VERSION;
+	items: TodoItem[];
+}
+
+const TodoParameters = Type.Object({
+	items: Type.Array(
+		Type.Object({
+			text: Type.String({
+				minLength: 1,
+				maxLength: MAX_TODO_TEXT_LENGTH,
+				description: "A concise, action-oriented task",
+			}),
+			status: StringEnum(TODO_STATUSES, {
+				description: "The task's current status",
+			}),
+		}),
+		{
+			maxItems: MAX_TODO_ITEMS,
+			description: "The complete current todo list; send an empty list to clear it",
+		},
+	),
+});
+
+export default function todoWidgetExtension(pi: ExtensionAPI): void {
+	let activeSession: ExtensionContext["sessionManager"] | undefined;
+	let items: TodoItem[] = [];
+
+	const ownsSession = (ctx: ExtensionContext): boolean => ctx.sessionManager === activeSession;
+
+	const publish = (ctx: ExtensionContext): void => {
+		if (!ownsSession(ctx) || ctx.mode !== "tui") return;
+		if (items.length === 0) {
+			ctx.ui.setWidget(WIDGET_KEY, undefined);
+			return;
+		}
+
+		const snapshot = cloneItems(items);
+		ctx.ui.setWidget(
+			WIDGET_KEY,
+			(_tui, theme) => ({
+				render: (width) => renderTodoWidget(snapshot, theme, width),
+				invalidate: () => {},
+			}),
+			WIDGET_OPTIONS,
+		);
+	};
+
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: "Todo List",
+		description:
+			"Replace the current session todo list with the complete supplied list. Call update_todo_list whenever actual task state changes; keep at most one item in_progress and send an empty list to clear it.",
+		promptSnippet: "Maintain the complete session todo list as multi-step work progresses",
+		promptGuidelines: [
+			"Use update_todo_list to track work with multiple meaningful steps; skip it for simple, single-step tasks.",
+			"Use update_todo_list to keep the list aligned with actual work: mark a task in_progress before starting it, mark it completed as soon as it finishes, and revise the list before continuing when the plan changes.",
+			"Before a progress report or final response, call update_todo_list to reconcile every item with actual work; do not report completion while the list is stale.",
+			"On every update_todo_list call, send the complete current list, keep at most one task in_progress, and send an empty list when no tracked work remains.",
+		],
+		parameters: TodoParameters,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			signal?.throwIfAborted();
+			if (!ownsSession(ctx)) {
+				throw new Error("Cannot update the todo list because the session changed.");
+			}
+			validateItems(params.items);
+
+			items = cloneItems(params.items);
+			publish(ctx);
+
+			const details: TodoDetails = {
+				version: TODO_DETAILS_VERSION,
+				items: cloneItems(items),
+			};
+			if (items.length === 0) {
+				return {
+					content: [{ type: "text", text: "Todo list cleared." }],
+					details,
+				};
+			}
+
+			const completed = items.filter((item) => item.status === "completed").length;
+			const inProgress = items.some((item) => item.status === "in_progress");
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Todo list updated: ${completed} of ${items.length} complete${inProgress ? "; 1 in progress" : ""}.`,
+					},
+				],
+				details,
+			};
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		activeSession = ctx.sessionManager;
+		items = reconstructItems(ctx.sessionManager.getBranch());
+		publish(ctx);
+	});
+
+	pi.on("context", (event, ctx) => {
+		if (!ownsSession(ctx)) return;
+		const messages = reconcileTodoContext(event.messages, items);
+		if (messages !== event.messages) return { messages };
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		if (!ownsSession(ctx)) return;
+		items = reconstructItems(ctx.sessionManager.getBranch());
+		publish(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (!ownsSession(ctx)) return;
+		if (ctx.mode === "tui") ctx.ui.setWidget(WIDGET_KEY, undefined);
+		items = [];
+		activeSession = undefined;
+	});
+}
+
+export function renderTodoWidget(
+	items: readonly TodoItem[],
+	theme: Theme,
+	width: number,
+): string[] {
+	const completed = items.filter((item) => item.status === "completed").length;
+	const divider = theme.fg("borderMuted", "─".repeat(Math.max(0, width)));
+	const lines = [divider, theme.fg("muted", `Todo · ${completed}/${items.length} complete`)];
+
+	const renderWidth = Math.max(0, width);
+	for (const item of items) {
+		const text = sanitizeTodoText(item.text);
+		let prefix: string;
+		let styledText: string;
+		switch (item.status) {
+			case "completed":
+				prefix = theme.fg("success", "✓ ");
+				styledText = theme.fg("muted", theme.strikethrough(text));
+				break;
+			case "in_progress":
+				prefix = theme.fg("accent", "▶ ");
+				styledText = theme.fg("accent", theme.bold(text));
+				break;
+			case "pending":
+				prefix = theme.fg("dim", "○ ");
+				styledText = theme.fg("text", text);
+				break;
+		}
+
+		if (renderWidth <= 2) {
+			lines.push(prefix);
+			continue;
+		}
+
+		const wrappedText = wrapTextWithAnsi(styledText, renderWidth - 2);
+		lines.push(...wrappedText.map((line, index) => `${index === 0 ? prefix : "  "}${line}`));
+	}
+
+	return lines.map((line) => truncateToWidth(line, renderWidth, ""));
+}
+
+export function reconcileTodoContext(
+	messages: ContextEvent["messages"],
+	items: readonly TodoItem[],
+): ContextEvent["messages"] {
+	const existing = messages.filter(isTodoContextMessage);
+	const withoutExisting = messages.filter((message) => !isTodoContextMessage(message));
+	const content =
+		items.length > 0 && !hasModelVisibleTodoState(withoutExisting, items)
+			? todoContextContent(items)
+			: undefined;
+	if (
+		existing.length === 1 &&
+		messages.at(-1) === existing[0] &&
+		existing[0]?.content === content
+	) {
+		return messages;
+	}
+	if (existing.length === 0 && content === undefined) return messages;
+
+	if (content === undefined) return withoutExisting;
+	return [
+		...withoutExisting,
+		{
+			role: "custom",
+			customType: TODO_CONTEXT_MESSAGE_TYPE,
+			content,
+			display: false,
+			details: { version: TODO_CONTEXT_VERSION },
+			timestamp: 0,
+		},
+	];
+}
+
+export function sanitizeTodoText(value: string): string {
+	let text = "";
+	for (const character of stripTerminalSequences(value).replace(BIDI_CONTROLS, "")) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		const isControl = codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+		text += isControl ? " " : character;
+	}
+	return text.replace(/\s+/gu, " ").trim();
+}
+
+function todoContextContent(items: readonly TodoItem[]): string {
+	return `[PI TODO STATUS v${TODO_CONTEXT_VERSION}]
+Current todo list as JSON data:
+${JSON.stringify(items)}`;
+}
+
+function hasModelVisibleTodoState(
+	messages: ContextEvent["messages"],
+	items: readonly TodoItem[],
+): boolean {
+	const currentResults = new Map<string, string>();
+	for (const message of messages) {
+		if (
+			message.role === "toolResult" &&
+			!message.isError &&
+			(message.toolName === TOOL_NAME || message.toolName === LEGACY_TOOL_NAME) &&
+			isTodoDetails(message.details) &&
+			todoItemsEqual(message.details.items, items)
+		) {
+			currentResults.set(message.toolCallId, message.toolName);
+		}
+	}
+	if (currentResults.size === 0) return false;
+
+	return messages.some(
+		(message) =>
+			message.role === "assistant" &&
+			message.content.some(
+				(content) =>
+					content.type === "toolCall" &&
+					currentResults.get(content.id) === content.name &&
+					isTodoToolArguments(content.arguments) &&
+					todoItemsEqual(content.arguments.items, items),
+			),
+	);
+}
+
+function isTodoToolArguments(value: unknown): value is { items: TodoItem[] } {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return isTodoItems((value as Record<string, unknown>).items);
+}
+
+function isTodoContextMessage(
+	message: ContextEvent["messages"][number],
+): message is ContextEvent["messages"][number] & { content: string } {
+	return message.role === "custom" && message.customType === TODO_CONTEXT_MESSAGE_TYPE;
+}
+
+function validateItems(items: readonly TodoItem[]): void {
+	for (const [index, item] of items.entries()) {
+		if (item.text.trim().length === 0) {
+			throw new Error(`Todo item ${index + 1} must contain non-whitespace text.`);
+		}
+	}
+
+	const currentCount = items.filter((item) => item.status === "in_progress").length;
+	if (currentCount > 1) {
+		throw new Error("Todo list can contain at most one in_progress item.");
+	}
+}
+
+function reconstructItems(entries: readonly SessionEntry[]): TodoItem[] {
+	let restored: TodoItem[] = [];
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const message = entry.message;
+		if (
+			message.role !== "toolResult" ||
+			(message.toolName !== TOOL_NAME && message.toolName !== LEGACY_TOOL_NAME)
+		) {
+			continue;
+		}
+		if (!isTodoDetails(message.details)) continue;
+		restored = cloneItems(message.details.items);
+	}
+	return restored;
+}
+
+function isTodoDetails(value: unknown): value is TodoDetails {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	return record.version === TODO_DETAILS_VERSION && isTodoItems(record.items);
+}
+
+function isTodoItems(value: unknown): value is TodoItem[] {
+	if (!Array.isArray(value) || value.length > MAX_TODO_ITEMS) return false;
+
+	let currentCount = 0;
+	for (const item of value) {
+		if (typeof item !== "object" || item === null || Array.isArray(item)) return false;
+		const candidate = item as Record<string, unknown>;
+		if (
+			typeof candidate.text !== "string" ||
+			candidate.text.length === 0 ||
+			candidate.text.length > MAX_TODO_TEXT_LENGTH ||
+			candidate.text.trim().length === 0 ||
+			!TODO_STATUSES.includes(candidate.status as TodoStatus)
+		) {
+			return false;
+		}
+		if (candidate.status === "in_progress") currentCount += 1;
+	}
+	return currentCount <= 1;
+}
+
+function todoItemsEqual(left: readonly TodoItem[], right: readonly TodoItem[]): boolean {
+	return (
+		left.length === right.length &&
+		left.every(
+			(item, index) => item.text === right[index]?.text && item.status === right[index]?.status,
+		)
+	);
+}
+
+function cloneItems(items: readonly TodoItem[]): TodoItem[] {
+	return items.map((item) => ({ text: item.text, status: item.status }));
+}