@agnishc/edb-todo 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Initial release: `todo_write` and `todo_read` tools
+- Live widget above editor showing up to 4 active tasks
+- System-prompt injection before every agent turn to prevent goal drift
+- `/todos` command with full-screen interactive viewer and progress bar
+- Session branch reconstruction so task state survives `/tree` navigation and forking

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agnish Chakraborty
+
+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,41 @@
+# @agnishc/edb-todo
+
+A Pi CLI extension that gives the agent a structured task list to prevent **goal drift** — the tendency for agents to lose track of the original plan as context grows and tool calls accumulate.
+
+## How it works
+
+1. The agent calls `todo_write` to plan multi-step work as an explicit task list
+2. Before every agent turn, active tasks are injected into the system prompt so the model always knows what remains and what it's currently doing
+3. A live widget above the editor shows the current task list at all times
+4. State is reconstructed from the session branch, so `/tree` navigation and forking work correctly
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `todo_write` | Replace the entire task list (atomic update) — always pass all tasks |
+| `todo_read` | Read the current task list and statuses |
+
+## Task statuses
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| `pending` | `○` | Not started |
+| `in_progress` | `→` | Actively working — only one at a time |
+| `completed` | `✓` | Done |
+
+## Install
+
+```bash
+pi install npm:@agnishc/edb-todo
+```
+
+## Usage
+
+```
+/todos       — open the interactive full-screen task viewer
+```
+
+## License
+
+[MIT](LICENSE) © Agnish Chakraborty

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@agnishc/edb-todo",
+	"version": "0.1.0",
+	"description": "Pi extension: structured task list with live widget and system-prompt injection to prevent goal drift",
+	"keywords": ["pi-package", "pi-extension", "edb"],
+	"type": "module",
+	"license": "MIT",
+	"author": "Agnish Chakraborty",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agnishcc/pi-extention-monorepo.git",
+		"directory": "packages/edb-todo"
+	},
+	"homepage": "https://github.com/agnishcc/pi-extention-monorepo/tree/main/packages/edb-todo#readme",
+	"bugs": { "url": "https://github.com/agnishcc/pi-extention-monorepo/issues" },
+	"publishConfig": { "access": "public" },
+	"scripts": { "test": "vitest run" },
+	"files": ["src", "README.md", "LICENSE", "CHANGELOG.md"],
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-ai": "*",
+		"@mariozechner/pi-coding-agent": "*",
+		"@mariozechner/pi-tui": "*",
+		"typebox": "*"
+	}
+}

package/src/component.ts

@@ -0,0 +1,156 @@
+import { matchesKey, Text, truncateToWidth } from "@mariozechner/pi-tui";
+import type { Task, TaskDetails } from "./types";
+import { PRIORITY_ORDER, STATUS_ICON } from "./types";
+
+// ── /todos interactive viewer ──────────────────────────────────────────────────
+
+export class TodoViewComponent {
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+
+	constructor(
+		private readonly tasks: Task[],
+		private readonly theme: any,
+		private readonly onClose: () => void,
+	) {}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+			this.onClose();
+		}
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+
+		const lines: string[] = [];
+		const th = this.theme;
+
+		// ── Header ──
+		lines.push("");
+		const titleText = " Tasks ";
+		const sideLen = Math.max(0, width - titleText.length - 3);
+		const headerLine =
+			th.fg("borderMuted", "─".repeat(3)) + th.fg("accent", titleText) + th.fg("borderMuted", "─".repeat(sideLen));
+		lines.push(truncateToWidth(headerLine, width));
+		lines.push("");
+
+		if (this.tasks.length === 0) {
+			lines.push(truncateToWidth(`  ${th.fg("dim", "No tasks yet. Ask the agent to plan the work.")}`, width));
+		} else {
+			// ── Progress bar ──
+			const completedCount = this.tasks.filter((t) => t.status === "completed").length;
+			const total = this.tasks.length;
+			const barWidth = Math.min(24, width - 20);
+			const filled = total > 0 ? Math.round((completedCount / total) * barWidth) : 0;
+			const empty = barWidth - filled;
+			const bar = `[${th.fg("success", "█".repeat(filled))}${th.fg("dim", "░".repeat(empty))}]`;
+			lines.push(truncateToWidth(`  ${bar}  ${th.fg("muted", `${completedCount}/${total} done`)}`, width));
+			lines.push("");
+
+			// ── In Progress ──
+			const inProgress = this.tasks.filter((t) => t.status === "in_progress");
+			if (inProgress.length > 0) {
+				lines.push(truncateToWidth(`  ${th.fg("accent", "In Progress")}`, width));
+				for (const t of inProgress) lines.push(...this.renderTask(t, width));
+				lines.push("");
+			}
+
+			// ── Pending (sorted by priority) ──
+			const pending = this.tasks
+				.filter((t) => t.status === "pending")
+				.sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]);
+			if (pending.length > 0) {
+				lines.push(truncateToWidth(`  ${th.fg("muted", "Pending")}`, width));
+				for (const t of pending) lines.push(...this.renderTask(t, width));
+				lines.push("");
+			}
+
+			// ── Completed ──
+			const done = this.tasks.filter((t) => t.status === "completed");
+			if (done.length > 0) {
+				lines.push(truncateToWidth(`  ${th.fg("dim", "Completed")}`, width));
+				for (const t of done) lines.push(...this.renderTask(t, width));
+				lines.push("");
+			}
+		}
+
+		// ── Footer ──
+		lines.push(truncateToWidth(th.fg("borderMuted", "─".repeat(width)), width));
+		lines.push(truncateToWidth(`  ${th.fg("dim", "Press Escape to close")}`, width));
+		lines.push("");
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	private renderTask(task: Task, width: number): string[] {
+		const th = this.theme;
+
+		const icon =
+			task.status === "completed"
+				? th.fg("success", STATUS_ICON.completed)
+				: task.status === "in_progress"
+					? th.fg("accent", STATUS_ICON.in_progress)
+					: th.fg("dim", STATUS_ICON.pending);
+
+		const priorityColor = task.priority === "high" ? "error" : task.priority === "medium" ? "warning" : "dim";
+		const pLabel = th.fg(priorityColor, task.priority.toUpperCase().slice(0, 3));
+
+		const contentText =
+			task.status === "completed"
+				? th.fg("dim", th.strikethrough(task.content))
+				: task.status === "in_progress"
+					? th.fg("text", th.bold(task.content))
+					: th.fg("muted", task.content);
+
+		const idHint = th.fg("dim", ` [${task.id}]`);
+
+		return [truncateToWidth(`    ${icon} ${pLabel}  ${contentText}${idHint}`, width)];
+	}
+
+	// ── Tool result rendering ──────────────────────────────────────────────────
+
+	static renderTaskResult(details: TaskDetails | undefined, expanded: boolean, theme: any): any {
+		if (!details?.tasks?.length) {
+			return new Text(theme.fg("dim", "Task list cleared"), 0, 0);
+		}
+
+		const list = details.tasks;
+		const doneCount = list.filter((t) => t.status === "completed").length;
+		let output = theme.fg("muted", `${doneCount}/${list.length} completed`);
+
+		const display = expanded ? list : list.slice(0, 5);
+		for (const t of display) {
+			const icon =
+				t.status === "completed"
+					? theme.fg("success", STATUS_ICON.completed)
+					: t.status === "in_progress"
+						? theme.fg("accent", STATUS_ICON.in_progress)
+						: theme.fg("dim", STATUS_ICON.pending);
+
+			const pColor = t.priority === "high" ? "error" : t.priority === "medium" ? "warning" : "dim";
+			const pLabel = theme.fg(pColor, t.priority.toUpperCase().slice(0, 3));
+			const content =
+				t.status === "completed"
+					? theme.fg("dim", theme.strikethrough(t.content))
+					: t.status === "in_progress"
+						? theme.fg("text", theme.bold(t.content))
+						: theme.fg("muted", t.content);
+
+			output += `\n${icon} ${pLabel}  ${content}`;
+		}
+
+		if (!expanded && list.length > 5) {
+			output += `\n${theme.fg("dim", `... ${list.length - 5} more`)}`;
+		}
+
+		return new Text(output, 0, 0);
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+/**
+ * pi-todo
+ *
+ * Task management extension that prevents "goal drift" — the tendency for
+ * agents to lose track of the original plan as context grows.
+ *
+ * How it works:
+ *   1. The agent uses `todo_write` to plan multi-step work as structured tasks
+ *   2. Before every agent turn, active tasks are injected into the system prompt
+ *   3. A live widget above the editor shows the task list to the user
+ *   4. State is stored in tool-result details and reconstructed from the session
+ *      branch, so /tree navigation and forking work correctly
+ *
+ * Tools:   todo_write  — replace the entire task list (atomic update)
+ *          todo_read   — read the current task list
+ * Command: /todos      — open interactive full-screen task viewer
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "typebox";
+import { TodoViewComponent } from "./component";
+import { buildSystemPromptBlock, formatListForLLM } from "./prompt";
+import { TodoWriteParams } from "./schemas";
+import { generateId, reconstructState, setTasks, syncIdCounter, tasks, updateWidget } from "./state";
+import type { TaskDetails, TaskPriority, TaskStatus } from "./types";
+
+// ── Extension ──────────────────────────────────────────────────────────────────
+
+export default function todoExtension(pi: ExtensionAPI): void {
+	// ── Session lifecycle ──────────────────────────────────────────────────
+	pi.on("session_start", async (_event, ctx) => {
+		reconstructState(ctx);
+		updateWidget(ctx);
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		reconstructState(ctx);
+		updateWidget(ctx);
+	});
+
+	// ── System-prompt injection ────────────────────────────────────────────
+	// Active tasks are injected at the start of every agent turn so the model
+	// always knows its current plan — the core mechanism that prevents goal drift.
+	pi.on("before_agent_start", async (event, _ctx) => {
+		const block = buildSystemPromptBlock();
+		if (!block) return;
+		return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+	});
+
+	// ── Post-turn widget refresh ───────────────────────────────────────────
+	pi.on("agent_end", async (_event, ctx) => {
+		updateWidget(ctx);
+	});
+
+	// ── Tool: todo_write ───────────────────────────────────────────────────
+	pi.registerTool({
+		name: "todo_write",
+		label: "Tasks",
+		description:
+			"Write and manage your task list for complex, multi-step work. " +
+			"Provide the COMPLETE updated list — this REPLACES the current list entirely.",
+		promptSnippet:
+			"Create and update a structured task list with statuses (pending / in_progress / completed) and priorities",
+		promptGuidelines: [
+			"Use todo_write at the start of any complex, multi-step task to break the work into a clear plan. " +
+				"Tasks should be specific and atomic (one concrete action each).",
+			"Before starting a task, call todo_write to set it to 'in_progress'. " +
+				"Only one task should be 'in_progress' at a time unless tasks are genuinely parallel.",
+			"Immediately after completing a task, call todo_write to mark it 'completed'. " +
+				"Do not batch completions — mark each task done as soon as it is finished.",
+			"todo_write REPLACES the entire list. Always include ALL tasks (both changed and unchanged) in every call.",
+		],
+		parameters: TodoWriteParams,
+
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			setTasks(
+				params.tasks.map((t) => ({
+					id: t.id ?? generateId(),
+					content: t.content,
+					status: t.status as TaskStatus,
+					priority: t.priority as TaskPriority,
+				})),
+			);
+			syncIdCounter();
+			updateWidget(ctx);
+
+			return {
+				content: [{ type: "text", text: formatListForLLM() }],
+				details: { tasks: [...tasks] } satisfies TaskDetails,
+			};
+		},
+
+		renderCall(args, theme) {
+			const list = (args.tasks as any[]) ?? [];
+			const inProg = list.filter((t: any) => t.status === "in_progress").length;
+			const done = list.filter((t: any) => t.status === "completed").length;
+			const total = list.length;
+			let text = theme.fg("toolTitle", theme.bold("todo_write "));
+			text += theme.fg("muted", `${total} task${total !== 1 ? "s" : ""}`);
+			if (inProg > 0) text += `  ${theme.fg("accent", `→ ${inProg} active`)}`;
+			if (done > 0) text += `  ${theme.fg("success", `✓ ${done} done`)}`;
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			return TodoViewComponent.renderTaskResult(result.details as TaskDetails | undefined, expanded, theme);
+		},
+	});
+
+	// ── Tool: todo_read ────────────────────────────────────────────────────
+	pi.registerTool({
+		name: "todo_read",
+		label: "Tasks",
+		description: "Read the current task list. Use this to check your tasks and their statuses.",
+		promptSnippet: "Read the current task list and statuses",
+		parameters: Type.Object({}),
+
+		async execute() {
+			return {
+				content: [{ type: "text", text: formatListForLLM() }],
+				details: { tasks: [...tasks] } satisfies TaskDetails,
+			};
+		},
+
+		renderCall(_args, theme) {
+			return new Text(theme.fg("toolTitle", theme.bold("todo_read")), 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			return TodoViewComponent.renderTaskResult(result.details as TaskDetails | undefined, expanded, theme);
+		},
+	});
+
+	// ── Command: /todos ────────────────────────────────────────────────────
+	pi.registerCommand("todos", {
+		description: "Open the interactive task viewer",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify(tasks.length === 0 ? "No tasks yet." : formatListForLLM(), "info");
+				return;
+			}
+			await ctx.ui.custom<void>((_tui, theme, _kb, done) => {
+				return new TodoViewComponent(tasks, theme, () => done());
+			});
+		},
+	});
+}

package/src/prompt.ts

@@ -0,0 +1,49 @@
+import { activeTasks, tasks } from "./state";
+import { PRIORITY_ORDER, STATUS_ICON } from "./types";
+
+// ── System prompt injection ────────────────────────────────────────────────────
+
+/**
+ * Build a plain-text task block for system-prompt injection.
+ * Only injected when there are active (non-completed) tasks.
+ */
+export function buildSystemPromptBlock(): string {
+	const active = activeTasks();
+	if (active.length === 0) return "";
+
+	const lines: string[] = [
+		"## Current Task List",
+		"",
+		"You have the following tasks. Update them with `todo_write` as you work:",
+		"",
+	];
+
+	const inProg = active.filter((t) => t.status === "in_progress");
+	const pending = active
+		.filter((t) => t.status === "pending")
+		.sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]);
+
+	for (const t of [...inProg, ...pending]) {
+		const icon = STATUS_ICON[t.status];
+		const pLabel = `[${t.priority.toUpperCase().slice(0, 3)}]`;
+		const suffix = t.status === "in_progress" ? "  ← in progress" : "";
+		lines.push(`${icon} ${pLabel} ${t.content}${suffix}`);
+	}
+
+	const doneCount = tasks.filter((t) => t.status === "completed").length;
+	if (doneCount > 0) {
+		lines.push("", `${doneCount}/${tasks.length} tasks completed.`);
+	}
+
+	return lines.join("\n");
+}
+
+// ── LLM text formatter ─────────────────────────────────────────────────────────
+
+/** Plain text list returned inside tool results (visible to the LLM). */
+export function formatListForLLM(): string {
+	if (tasks.length === 0) return "Task list is empty.";
+	return tasks
+		.map((t) => `${STATUS_ICON[t.status]} [${t.priority.toUpperCase().slice(0, 3)}] [${t.id}] ${t.content}`)
+		.join("\n");
+}

package/src/schemas.ts

@@ -0,0 +1,35 @@
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "typebox";
+
+// ── Tool schemas ───────────────────────────────────────────────────────────────
+
+export const TaskSchema = Type.Object({
+	id: Type.Optional(
+		Type.String({
+			description:
+				"Unique task ID. Omit to auto-generate. " +
+				"When updating existing tasks use their current ID to preserve identity.",
+		}),
+	),
+	content: Type.String({
+		description: "Clear, actionable task description.",
+	}),
+	status: StringEnum(["pending", "in_progress", "completed"] as const, {
+		description:
+			"Task status. " +
+			"Set to 'in_progress' for the task you are actively working on right now. " +
+			"Only one task should be 'in_progress' at a time unless tasks are genuinely parallel.",
+	}),
+	priority: StringEnum(["high", "medium", "low"] as const, {
+		description: "Task priority.",
+	}),
+});
+
+export const TodoWriteParams = Type.Object({
+	tasks: Type.Array(TaskSchema, {
+		description:
+			"The COMPLETE, updated task list. " +
+			"This REPLACES the current list entirely — always include ALL tasks, " +
+			"both updated ones and unchanged ones.",
+	}),
+});

package/src/state.ts

@@ -0,0 +1,95 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { Task, TaskDetails } from "./types";
+import { PRIORITY_ORDER } from "./types";
+
+// ── Module state ───────────────────────────────────────────────────────────────
+
+export let tasks: Task[] = [];
+export let idCounter: number = 0;
+
+// ── State helpers ──────────────────────────────────────────────────────────────
+
+export function generateId(): string {
+	return `t${++idCounter}`;
+}
+
+export function activeTasks(): Task[] {
+	return tasks.filter((t) => t.status !== "completed");
+}
+
+export function setTasks(next: Task[]): void {
+	tasks = next;
+}
+
+export function syncIdCounter(): void {
+	for (const t of tasks) {
+		const m = t.id.match(/^t(\d+)$/);
+		if (m) idCounter = Math.max(idCounter, parseInt(m[1]!, 10));
+	}
+}
+
+// ── Session reconstruction ─────────────────────────────────────────────────────
+
+/**
+ * Reconstruct in-memory state by replaying the last todo_write on the branch.
+ * Ensures /tree navigation and forking work correctly.
+ */
+export function reconstructState(ctx: ExtensionContext): void {
+	tasks = [];
+	idCounter = 0;
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type !== "message") continue;
+		const msg = entry.message;
+		if (msg.role !== "toolResult" || msg.toolName !== "todo_write") continue;
+		const details = msg.details as TaskDetails | undefined;
+		if (details?.tasks) {
+			tasks = details.tasks;
+			syncIdCounter();
+		}
+	}
+}
+
+// ── Widget & status bar ────────────────────────────────────────────────────────
+
+export function updateWidget(ctx: ExtensionContext): void {
+	const active = activeTasks();
+
+	if (active.length === 0) {
+		ctx.ui.setWidget("pi-todo", undefined);
+		ctx.ui.setStatus("pi-todo", undefined);
+		return;
+	}
+
+	const th = ctx.ui.theme;
+	const inProg = active.filter((t) => t.status === "in_progress");
+	const pending = active.filter((t) => t.status === "pending");
+	const doneCount = tasks.filter((t) => t.status === "completed").length;
+
+	// ── Footer status ──
+	const parts: string[] = [];
+	if (inProg.length > 0) parts.push(th.fg("accent", `→ ${inProg.length} active`));
+	if (pending.length > 0) parts.push(th.fg("muted", `○ ${pending.length} pending`));
+	if (doneCount > 0) parts.push(th.fg("success", `✓ ${doneCount} done`));
+	ctx.ui.setStatus("pi-todo", parts.join("  "));
+
+	// ── Widget: show up to 4 active tasks ─────────────────────────────────
+	const displayTasks = [
+		...inProg,
+		...pending.sort((a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority]),
+	].slice(0, 4);
+
+	const widgetLines: string[] = [""];
+	for (const t of displayTasks) {
+		const icon = t.status === "in_progress" ? th.fg("accent", "→") : th.fg("dim", "○");
+		const pColor = t.priority === "high" ? "error" : t.priority === "medium" ? "warning" : "dim";
+		const pLabel = th.fg(pColor, t.priority.toUpperCase().slice(0, 3));
+		const content = t.status === "in_progress" ? th.fg("text", th.bold(t.content)) : th.fg("muted", t.content);
+		widgetLines.push(`  ${icon} ${pLabel}  ${content}`);
+	}
+	if (active.length > 4) {
+		widgetLines.push(`  ${th.fg("dim", `... ${active.length - 4} more  (/todos for full list)`)}`);
+	}
+	widgetLines.push("");
+
+	ctx.ui.setWidget("pi-todo", widgetLines);
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type TaskStatus = "pending" | "in_progress" | "completed";
+export type TaskPriority = "high" | "medium" | "low";
+
+export interface Task {
+	id: string;
+	content: string;
+	status: TaskStatus;
+	priority: TaskPriority;
+}
+
+export interface TaskDetails {
+	tasks: Task[];
+}
+
+// ── Visual constants ───────────────────────────────────────────────────────────
+
+export const STATUS_ICON: Record<TaskStatus, string> = {
+	pending: "○",
+	in_progress: "→",
+	completed: "✓",
+};
+
+export const PRIORITY_ORDER: Record<TaskPriority, number> = {
+	high: 0,
+	medium: 1,
+	low: 2,
+};