@fyeeme/pi-todo 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-09
+
+### Added
+
+- Phased todo tool for pi: nine operations (`init`/`start`/`done`/`rm`/`drop`/`block`/`unblock`/`append`/`view`) over phase/task state with oh-my-pi-verbatim semantics (batch-atomic duplicate rejection, single `in_progress` invariant with earliest-pending auto-promotion, drop = abandoned, block skips finished work).
+- Session persistence: full snapshot entry per mutation; branch-aware restore on session start/fork/tree navigation (`getBranch()`, so snapshots from abandoned branches no longer win the backward scan after `/fork` or `/tree`).
+- `/todo` command with oh-my-pi's full verb set — `edit`, `copy`, `export`, `import`, `append`, `start`, `done`, `drop`, `rm`, `help` — with quote-aware tokenizing, fuzzy task/phase matching, and the Markdown round-trip (`phasesToMarkdown`/`markdownToPhases` with blocker HTML comments and escaped-bracket tolerance). Every mutation injects omp's `<system-reminder>` developer message ("The user manually modified the todo list (...)"), with explicit do-not-recreate notes after removals.
+- Stop reminders matching omp `TodoTracker.checkCompletion`: a hidden `<system-reminder>` ("You stopped with N incomplete todo item(s)... (Reminder X/3)") queues a continuation turn, up to 3 attempts per user prompt, silent when the assistant's last line asks the user something (omp `isAwaitingUserAnswer`). The transcript note uses omp's `TodoReminderComponent` text: `⚠ N incomplete todos - reminder X/3` plus the italic unchecked list.
+- Transcript rendering ports omp's renderer: call line `⏳ Todo · <op> <task> · N items`, result header `☑ Todo · N tasks`, roman-numeral phase headers with `closed/total` progress, touched-phase collapsing, tree glyphs (`├─`/`└─`), omp checkbox glyph set with strikethrough closed rows, and the collapsed walking viewport (`#5873`: last closed row leads, active work first, `… N more todos` summary).
+- Tool prompt guidelines use omp's eager-todo wording.
+- `todo_updated` event-bus broadcast after every successful mutation (pi-goal todo-context integration point).
+- `test/omp-alignment.test.ts`: alignment suite pinning the markdown round-trip, roman numerals, collapsed-viewport selection, subagent-match helper, reminder guards, and summary text to omp sources verbatim.
+
+### Fixed
+
+- The `op` parameter uses `StringEnum` instead of a `Type.Union` of literals (Google API compatibility).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fyeeme
+
+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,92 @@
+# pi-todo
+
+Phased todo lists for [pi](https://github.com/earendil-works/pi-coding-agent) — the oh-my-pi todo tool migrated to a pi extension.
+
+The agent gets a `todo` tool: a phased task list (phases → tasks with lifecycle statuses) persisted with the session. You get a `/todo` command, a transcript reminder when the agent stops with unfinished work, and a `todo_updated` event other extensions can consume (pi-goal uses it to attach live progress state to goal continuations).
+
+## Install
+
+```bash
+pi install npm:@fyeeme/pi-todo
+```
+
+No configuration, no settings, no flags — installed means active. Works in TUI, RPC, and headless (`-p`) modes.
+
+## The tool
+
+Nine operations over `phases: [{ phase, items: string[] }]` state:
+
+| `op`       | Fields                    | Effect                                                    |
+| ---------- | ------------------------- | --------------------------------------------------------- |
+| `init`     | `list` (or flat `items`)  | Replace the whole list; all tasks start `pending`          |
+| `start`    | `task`                    | Mark `in_progress`; demotes every other `in_progress` task |
+| `done`     | `task` or `phase`         | Mark `completed`                                           |
+| `drop`     | `task` or `phase`         | Mark `abandoned` (never deleted)                           |
+| `block`    | `task` or `phase`, `reason?` | Park open work awaiting external input; one-line reason |
+| `unblock`  | `task` or `phase`         | `blocked` → `pending`, clears the note                     |
+| `rm`       | `task?` or `phase?`       | Remove a task / clear a phase / clear everything           |
+| `append`   | `phase`, `items`          | Add `pending` tasks; lazily creates the phase              |
+| `view`     | —                         | Read-only snapshot                                         |
+
+Semantics kept verbatim from oh-my-pi: batch-atomic duplicate rejection (a failing op applies nothing), a single `in_progress` invariant with the earliest pending task auto-promoted on every mutation, `block` never reopens finished work, `view` never writes.
+
+## Command
+
+The full oh-my-pi `/todo` verb set:
+
+```
+/todo                              Show current todos (Markdown checklist)
+/todo edit                         Round-trip todos through the editor
+/todo copy                         Print todos as Markdown
+/todo export [<path>]              Write todos to file (default: TODO.md)
+/todo import [<path>]              Replace todos from file (default: TODO.md)
+/todo append [<phase>] <task...>   Append a task; phase fuzzy-matched or auto-created
+/todo start  <task>                Mark task in_progress (fuzzy match)
+/todo done   [<task|phase>]        Mark task/phase/all completed
+/todo drop   [<task|phase>]        Mark task/phase/all abandoned
+/todo rm     [<task|phase>]        Remove task/phase/all
+```
+
+Every mutation commits a `<system-reminder>` hidden message telling the agent the user manually modified the list (with explicit intent notes after removals, so it never rebuilds cleared items).
+
+## Stop reminders
+
+When an agent run ends while tasks are still `pending`/`in_progress`, oh-my-pi's reminder loop kicks in: a hidden `<system-reminder>` message ("You stopped with N incomplete todo item(s)... (Reminder X/3)") is queued as a follow-up turn so the agent continues or marks work done, and a `⚠ N incomplete todos - reminder X/3` note is anchored in the transcript. The cycle allows 3 reminders, restarts on each new user prompt, and stays silent when the assistant's last line is a question to the user (the ball is in your court) or when only `blocked` tasks remain — those are parked awaiting external input.
+
+## Event contract
+
+After every successful mutation:
+
+```ts
+pi.events.emit("todo_updated", { phases }); // full snapshot; never on view/failure
+```
+
+### pi-goal integration
+
+[pi-goal](../pi-goal) embeds a `<todo_context>` block into its per-turn goal context when the `todo` tool is active and the list is non-empty — live progress state for autonomous goal continuations. pi-todo is fully usable without pi-goal; pi-goal degrades silently without pi-todo.
+
+## Persistence
+
+Every mutation appends a full `todo-phases` snapshot entry to the session. On session start (resume/fork/tree navigation/reload), the latest valid snapshot on the **current branch** wins, so navigating the session tree restores the todo state of that point in history. Malformed entries are skipped, never fatal.
+
+## Ported from oh-my-pi — what was dropped
+
+Source: `oh-my-pi/packages/coding-agent/src/tools/todo.ts` (plus reminder, slash-command helpers, prompts). Behavior semantics are ported verbatim; host-internal surfaces with no pi counterpart are not:
+
+| omp surface                                | Status in pi-todo                                        |
+| ------------------------------------------ | -------------------------------------------------------- |
+| mid-run todo nudge (tool-choice queue)      | Dropped — omp host-internal                               |
+| eager-todo / prewalk system-prompt arming   | Replaced by `promptGuidelines` on the tool definition     |
+| `/todo edit` + markdown round-trip          | Dropped — no host editor surface                          |
+| Sticky HUD / collapsed viewport / animations| Dropped — omp TUI-internal                                |
+| Subagent todo-match lighting                | Dropped — no subagent HUD contract                        |
+| `todo.enabled` settings gate                | Dropped — no settings API by design: installed means active |
+
+## Development
+
+```bash
+npm run typecheck   # from packages/extensions/pi-todo
+npm run test        # vitest
+```
+
+License: MIT

package/index.ts

@@ -0,0 +1,222 @@
+/**
+ * pi-todo — the oh-my-pi todo tool migrated to a pi extension.
+ *
+ * Source: oh-my-pi (github.com/can1357/oh-my-pi, a fork of badlogic/pi-mono)
+ *   - packages/coding-agent/src/tools/todo.ts (state + ops) → src/state.ts
+ *   - packages/coding-agent/src/tools/todo.ts (TodoTool)     → src/tool.ts
+ *   - packages/coding-agent/src/tools/todo.ts (renderer)     → src/render.ts
+ *   - packages/coding-agent/src/prompts/tools/todo.md        → src/prompts/todo.md
+ *   - packages/coding-agent/src/session/todo-tracker.ts (checkCompletion)
+ *                                                            → agent_end reminder loop
+ *   - packages/coding-agent/src/modes/components/todo-reminder.ts → reminder entry renderer
+ *   - packages/coding-agent/src/modes/controllers/todo-command-controller.ts
+ *                                                            → src/commands.ts
+ *
+ * Adaptations for pi's extension API (each maps an omp-internal surface to
+ * the public extension boundary):
+ *
+ *   omp surface                       → pi adaptation
+ *   ─────────────────────────────────────────────────────────────────────────
+ *   session getTodoPhases/setTodoPhases → closure state + pi.appendEntry
+ *                                         full-snapshot entries ("todo-phases")
+ *   restore via tool-result details     → session_start backward scan of the
+ *                                         current branch (appendEntry chains
+ *                                         off the leaf, so tree navigation
+ *                                         and forks restore branch-local state)
+ *   ArkType schema + lenientArgValidation
+ *                                     → TypeBox schema + prepareArguments
+ *                                         (missing-op inference before validation)
+ *   concurrency: "exclusive"           → executionMode: "sequential"
+ *   mergeCallAndResult renderer        → split renderCall/renderResult slots
+ *   eager-todo system-prompt prewalk   → promptGuidelines on the tool definition
+ *   developer-role injected messages   → pi.sendMessage display:false (custom
+ *                                         role; both /todo edits and stop
+ *                                         reminders)
+ *   TodoTracker.checkCompletion        → agent_end handler: same reminder text,
+ *                                         3-attempt cycle, question guard, and
+ *                                         followUp-triggered continuation
+ *   TodoReminderComponent (TUI box)    → "todo-reminder" entry renderer
+ *                                         (transcript-anchored, same text)
+ *   $EDITOR round-trip                 → ctx.ui.editor (Markdown round-trip)
+ *   mid-run nudge (tool-choice queue)  → dropped (omp host-internal)
+ *   subagent-match lighting            → dropped (omp host-internal provider)
+ *
+ * omp operation semantics are kept verbatim: batch-atomic duplicate
+ * rejection, single in_progress invariant with earliest-pending auto-promotion,
+ * drop = abandoned (never delete), block skips finished work, view is a read.
+ *
+ * Integration contract for other extensions:
+ *   - `pi.events.emit("todo_updated", { phases })` after every successful
+ *     mutation (never on view or failure)
+ *   - stop reminders count pending + in_progress only (blocked is parked)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+import { createTodoCommand } from "./src/commands.ts";
+import { isAwaitingUserAnswer, type TodoItem, type TodoPhase } from "./src/state.ts";
+import { createTodoTool } from "./src/tool.ts";
+import {
+	TODO_PHASES_ENTRY_TYPE,
+	TODO_REMINDER_ENTRY_TYPE,
+	restorePhasesFromEntries,
+} from "./src/restore.ts";
+
+/** omp settings todo.remindersMax default (3) — extensions have no settings. */
+const REMINDERS_MAX = 3;
+
+interface AssistantTextLike {
+	role?: string;
+	content?: unknown;
+}
+
+function assistantText(message: AssistantTextLike): string {
+	if (!Array.isArray(message.content)) return "";
+	return message.content
+		.filter((block): block is { type: string; text?: string } =>
+			!!block && typeof block === "object" && (block as { type?: unknown }).type === "text",
+		)
+		.map(block => block.text ?? "")
+		.join("\n")
+		.trim();
+}
+
+export default function piTodoExtension(pi: ExtensionAPI): void {
+	let phases: TodoPhase[] = [];
+	/** omp TodoTracker #reminderCount: reminders sent in the current cycle. */
+	let reminderCount = 0;
+	/** Last assistant reply text, for omp's awaiting-user-answer guard. */
+	let lastAssistantText = "";
+
+	const deps = {
+		getPhases: () => phases,
+		setPhases: (next: TodoPhase[]) => {
+			phases = next;
+		},
+		persist: (next: TodoPhase[]) => {
+			pi.appendEntry(TODO_PHASES_ENTRY_TYPE, { phases: clonePhasesForEntry(next) });
+		},
+		broadcast: (next: TodoPhase[]) => {
+			pi.events.emit("todo_updated", { phases: clonePhasesForEntry(next) });
+		},
+		// omp #commit injects a developer system-reminder after user edits.
+		sendHiddenMessage: (content: string) => {
+			pi.sendMessage({ customType: "todo-user-edit", content, display: false });
+		},
+	};
+
+	pi.registerTool(createTodoTool(deps));
+
+	pi.registerCommand("todo", {
+		description: "View or modify the agent's todo list",
+		handler: createTodoCommand(deps),
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		// Branch-aware restore: latest valid snapshot on the current branch wins.
+		// getBranch() excludes entries on abandoned branches created after a
+		// /fork or /tree navigation; getEntries() would let a later snapshot
+		// from an abandoned branch win the backward scan.
+		phases = restorePhasesFromEntries(ctx.sessionManager.getBranch());
+		reminderCount = 0;
+	});
+
+	pi.on("message_start", (event) => {
+		// omp resetCycle: a fresh user prompt starts a new reminder cycle.
+		if ((event.message as { role?: string }).role === "user") {
+			reminderCount = 0;
+		}
+	});
+
+	pi.on("agent_end", (event) => {
+		// Capture the last assistant text for the question guard BEFORE the
+		// reminder decision (omp checkCompletion sees the terminal message).
+		const messages = (event.messages ?? []) as AssistantTextLike[];
+		for (let i = messages.length - 1; i >= 0; i--) {
+			const message = messages[i];
+			if (message?.role === "assistant") {
+				lastAssistantText = assistantText(message);
+				break;
+			}
+		}
+		checkCompletion();
+	});
+
+	/** omp TodoTracker.checkCompletion: nag + auto-continue on open todos. */
+	function checkCompletion(): void {
+		if (reminderCount >= REMINDERS_MAX) return;
+		if (phases.length === 0) {
+			reminderCount = 0;
+			return;
+		}
+		const incompleteByPhase = phases
+			.map(phase => ({
+				name: phase.name,
+				tasks: phase.tasks.filter(task => task.status === "pending" || task.status === "in_progress"),
+			}))
+			.filter(phase => phase.tasks.length > 0);
+		const incomplete = incompleteByPhase.flatMap(phase => phase.tasks);
+		if (incomplete.length === 0) {
+			reminderCount = 0;
+			return;
+		}
+		// omp isAwaitingUserAnswer: the assistant ended by asking the user
+		// something — skip the reminder, the ball is in the user's court.
+		if (isAwaitingUserAnswer(lastAssistantText)) return;
+
+		reminderCount++;
+		const todoList = incompleteByPhase
+			.map(phase => `- ${phase.name}\n${phase.tasks.map(task => `  - ${task.content}`).join("\n")}`)
+			.join("\n");
+		const reminder =
+			`<system-reminder>\n` +
+			`You stopped with ${incomplete.length} incomplete todo item(s):\n${todoList}\n\n` +
+			`Please continue working on these tasks or mark them complete if finished.\n` +
+			`(Reminder ${reminderCount}/${REMINDERS_MAX})\n` +
+			`</system-reminder>`;
+		// omp: append developer message + scheduleAgentContinue.
+		pi.sendMessage(
+			{ customType: "todo-reminder", content: reminder, display: false },
+			{ triggerTurn: true, deliverAs: "followUp" },
+		);
+		pi.appendEntry(TODO_REMINDER_ENTRY_TYPE, {
+			count: incomplete.length,
+			attempt: reminderCount,
+			maxAttempts: REMINDERS_MAX,
+			todos: incomplete.map(task => ({ content: task.content, status: task.status })),
+		});
+	}
+
+	// omp TodoReminderComponent: warning box committed into the transcript —
+	// `⚠ N incomplete todos - reminder X/Y` + italic unchecked list.
+	pi.registerEntryRenderer<{
+		count?: number;
+		openCount?: number;
+		attempt?: number;
+		maxAttempts?: number;
+		todos?: TodoItem[];
+	}>(TODO_REMINDER_ENTRY_TYPE, (entry, _options, theme) => {
+		const data = entry.data;
+		const count = typeof data?.count === "number" ? data.count : typeof data?.openCount === "number" ? data.openCount : 0;
+		const attempt = typeof data?.attempt === "number" ? data.attempt : 1;
+		const maxAttempts = typeof data?.maxAttempts === "number" ? data.maxAttempts : REMINDERS_MAX;
+		const label = count === 1 ? "todo" : "todos";
+		const header = `⚠ ${count} incomplete ${label} - reminder ${attempt}/${maxAttempts}`;
+		const todos = Array.isArray(data?.todos) ? data.todos : [];
+		const list = todos.length > 0 ? `\n\n${theme.italic(todos.map(todo => `  ☐ ${todo.content}`).join("\n"))}` : "";
+		const component: Component = new Text(theme.fg("warning", header) + list, 0, 0);
+		return component;
+	});
+}
+
+/** Defensive clone for entries/events (omp TodoTracker.#clonePhases). */
+function clonePhasesForEntry(phases: TodoPhase[]): TodoPhase[] {
+	return phases.map(phase => ({
+		name: phase.name,
+		tasks: phase.tasks.map(task =>
+			task.blocker !== undefined
+				? { content: task.content, status: task.status, blocker: task.blocker }
+				: { content: task.content, status: task.status },
+		),
+	}));
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@fyeeme/pi-todo",
+	"version": "1.0.0",
+	"description": "Phased todo list tool for pi — nine operations (init/start/done/rm/drop/block/unblock/append/view) over phase/task state persisted with the session, a /todo command, stop-time reminders for unfinished work, and a todo_updated event bus broadcast for other extensions.",
+	"type": "module",
+	"license": "MIT",
+	"author": "fyeeme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fyeeme/pi-packages.git"
+	},
+	"bugs": {
+		"url": "https://github.com/fyeeme/pi-packages/issues"
+	},
+	"homepage": "https://github.com/fyeeme/pi-packages#readme",
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"extension",
+		"todo",
+		"tasks",
+		"phases",
+		"checklist",
+		"progress"
+	],
+	"files": [
+		"index.ts",
+		"src",
+		"test",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"scripts": {
+		"test": "vitest --run",
+		"typecheck": "tsc"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.84.1",
+		"@earendil-works/pi-tui": ">=0.84.1",
+		"typebox": ">=1.0.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "0.84.1",
+		"@earendil-works/pi-tui": "0.84.1",
+		"@types/node": "22.19.19",
+		"typescript": "5.9.3",
+		"vitest": "3.2.7"
+	}
+}