@agnishc/edb-todo 0.8.1 → 0.10.3

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [0.10.3] - 2026-05-15
+
+## [0.9.0] - 2026-05-15
+
+### Added
+- `todo_create` tool — create individual tasks with `content`, `description`, `priority`, `activeForm`, and `metadata`
+- `todo_get` tool — retrieve full task details: description, dependencies (`blocks`/`blockedBy`), metadata
+- `todo_update` tool — update individual tasks (status, content, description, priority, owner); add dependency edges (`addBlocks`/`addBlockedBy`); `status: "deleted"` permanently removes the task
+- **File-backed storage** — tasks now persist to disk with file locking and atomic writes
+  - `memory`: in-memory only (lost on session end)
+  - `session` *(default)*: per-session file at `<cwd>/.pi/tasks/tasks-<sessionId>.json`
+  - `project`: shared across all sessions at `<cwd>/.pi/tasks/tasks.json`
+- **Dependency management** — bidirectional `blocks`/`blockedBy` edges with cycle detection and warnings
+- **Auto-clear completed tasks** — configurable via settings: `never` / `on_list_complete` *(default)* / `on_task_complete`; turn-based delay so completions linger briefly before disappearing
+- **Settings panel** — `/todos → ⚙ Settings` opens a native TUI settings panel (taskScope + autoClearCompleted); saved to `<cwd>/.pi/tasks-config.json`
+- **System-reminder injection** — periodic `<system-reminder>` nudges appended to non-task tool results after `REMINDER_INTERVAL` turns of inactivity, encouraging the model to keep tasks up to date
+- **Enhanced widget** — animated star spinner (✳✴✵…) for in-progress tasks, elapsed time display (e.g. `42s`, `2m 5s`), blocked-by hints inline
+- `PI_TODO` environment variable override: `off` (memory only), named list (`~/.pi/tasks/<name>.json`), or absolute/relative path
+- `/todos` command now shows a select-based menu with View / Clear completed / Clear all / Settings
+
+### Changed
+- Widget placement changed from status bar to **above editor** (persistent, always visible)
+- Session state no longer reconstructed from tool-result branch entries — file-backed store is the source of truth
+- `todo_write` now merges `blocks`, `blockedBy`, and `metadata` from existing tasks when a task ID is reused (non-destructive for dependency edges)
+- System prompt injection now includes task IDs and blocked-by info
+- `priorityLabel` now correctly outputs `High`/`Medium`/`Low`
+
+## [0.8.2] - 2026-05-11
+
+### Added
+- `todo_remove` tool — permanently remove tasks by ID
+- Interactive keyboard navigation in `/todos` viewer (↑↓/jk, g/G, Home/End)
+- Toggle completed task visibility with `c` key in `/todos` viewer
+- Timestamps on tasks: `createdAt`, `startedAt`, `completedAt`
+- Status transition tracking — timestamps update automatically when tasks move between states
+- Percentage display in progress bar
+
+### Changed
+- Replaced module-level mutable globals (`tasks`, `idCounter`) with `TodoStore` class
+- Deduplicated rendering logic — shared `priorityColor()`, `priorityLabel()` helpers used everywhere
+- Priority labels now display as `High`/`Medium`/`Low` instead of `HIG`/`MED`/`LOW`
+- In-progress icon changed from `→` to `●` for visual consistency
+- `/todos` viewer now shows cursor indicator (`❯`) on focused task
+- Section headers show task counts
+- Updated widget status bar to use `●` for active count
+- `todo_write` prompt guidelines now explicitly state completed tasks are never auto-deleted
+
+### Fixed
+- Rendering inconsistency between widget, viewer, and tool results — all now use the same styling
+
 ## [0.8.1] - 2026-05-11
 
 ## [0.6.0] - 2026-05-11

package/README.md

@@ -2,38 +2,171 @@
 
 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.
 
+## Features
+
+- **6 LLM tools** — `TaskCreate`, `TaskList`, `TaskGet`, `TaskUpdate`, `TaskOutput`, `TaskStop` — matching pi-tasks behavior
+- **Persistent widget** — live task list above the editor with animated spinner (✳✽), elapsed time, and blocked-by hints
+- **File-backed storage** — memory / session / project scope with file locking and atomic writes
+- **Dependency management** — bidirectional `blocks` / `blockedBy` edges with cycle detection
+- **Auto-clear completed tasks** — configurable: never / on_list_complete / on_task_complete
+- **System-reminder injection** — periodic nudges when task tools haven't been used recently
+- **Settings panel** — `/todos → ⚙ Settings` (task storage + auto-clear, saved to `tasks-config.json`)
+- **Priority system** — high / medium / low with color coding (Red / Yellow / Dim)
+
 ## 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
+1. The agent uses `TaskCreate` to plan multi-step work as a structured task list
+2. Before every agent turn, active tasks are injected into the system prompt
+3. A live widget above the editor shows tasks with status icons and elapsed time for active tasks
+4. Tasks persist to disk per-session (or project-wide) and survive session resume
+5. Completed tasks remain visible until auto-cleared or manually removed
 
 ## 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 |
+### `TaskCreate`
 
-## Task statuses
+Create a structured task. Used proactively for complex multi-step work.
 
-| Status | Icon | Meaning |
-|--------|------|---------|
-| `pending` | `○` | Not started |
-| `in_progress` | `→` | Actively working — only one at a time |
-| `completed` | `✓` | Done |
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | ✓ | Brief actionable title in imperative form |
+| `description` | string | | Detailed context and acceptance criteria |
+| `priority` | `high` \| `medium` \| `low` | | Default: `medium` |
+| `activeForm` | string | | Spinner text when in_progress (e.g., "Running tests") |
+| `metadata` | object | | Arbitrary key-value pairs |
 
-## Install
+### `TaskList`
+
+List all tasks sorted by status (pending first, then in_progress, then completed) and ID.
+
+Returns each task's id, content, status, priority, and open blockedBy entries.
+
+### `TaskGet`
+
+Get full details for a specific task by ID — including description, dependencies, and metadata.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | The task ID |
+
+### `TaskUpdate`
+
+Update task fields, status, and dependencies.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | string | Task ID (required) |
+| `status` | `pending` \| `in_progress` \| `completed` \| `deleted` | New status (`deleted` permanently removes) |
+| `content` | string | New title |
+| `description` | string | New description |
+| `priority` | `high` \| `medium` \| `low` | New priority |
+| `activeForm` | string | Spinner text |
+| `owner` | string | Agent/owner name |
+| `metadata` | object | Shallow merge (set key to `null` to delete) |
+| `addBlocks` | string[] | Task IDs this task blocks |
+| `addBlockedBy` | string[] | Task IDs that block this task |
+
+Setting `status: "deleted"` permanently removes the task and cleans up all dependency edges.
+
+Dependencies are bidirectional — `addBlocks: ["t2"]` on task `t1` also adds `blockedBy: ["t1"]` to task `t2`.
+
+### `TaskOutput`
+
+Retrieve output from a running or completed background task process.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `task_id` | string | — | Task ID (required) |
+| `block` | boolean | `true` | Wait for completion |
+| `timeout` | number | `30000` | Max wait time in ms (max 600000) |
+
+### `TaskStop`
+
+Stop a running background task process. Sends SIGTERM, waits 5 seconds, then SIGKILL. Marks the task as completed.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `task_id` | string | Task ID to stop |
+
+## Task lifecycle
+
+```
+pending → in_progress → completed
+                      → deleted  (permanently removed)
+```
+
+## Dependency management
 
 ```bash
-pi install npm:@agnishc/edb-todo
+# Task t2 cannot start until t1 is completed
+TaskUpdate { id: "t2", addBlockedBy: ["t1"] }
 ```
 
-## Usage
+Edges are bidirectional. The widget and `TaskList` show open blockers inline (`› blocked by #t1`). Cycles and self-dependencies produce warnings but are stored.
+
+## Task storage
+
+Configured via `/todos → ⚙ Settings` or the `PI_TODO` environment variable:
+
+| Mode | File | Behaviour |
+|------|------|-----------|
+| `memory` | *(none)* | In-memory only — tasks lost when session ends |
+| `session` *(default)* | `<cwd>/.pi/tasks/tasks-<sessionId>.json` | Per-session, survives resume |
+| `project` | `<cwd>/.pi/tasks/tasks.json` | Shared across all sessions in the project |
+
+Settings are saved to `<cwd>/.pi/tasks-config.json`.
+
+### Environment variable override
 
+| Variable | Value | Behaviour |
+|----------|-------|-----------|
+| `PI_TODO` | `off` | In-memory only (CI/automation) |
+| `PI_TODO` | `sprint-1` | Named shared list at `~/.pi/tasks/sprint-1.json` |
+| `PI_TODO` | `/abs/path.json` | Explicit absolute file path |
+
+## Auto-clear completed tasks
+
+| Mode | Behaviour |
+|------|-----------|
+| `never` | Completed tasks stay visible until manually cleared |
+| `on_list_complete` *(default)* | Cleared after all tasks complete and a few idle turns pass |
+| `on_task_complete` | Each task cleared individually a few turns after completion |
+
+## Widget
+
+Persistent task list rendered above the editor:
+
+```
+● 4 tasks (1 done, 1 in progress, 2 open)
+  ✔ Design the API
+  ✳ Implementing auth…  (42s)
+  ◻ Write tests  › blocked by #t2
+  ◻ Update docs
 ```
-/todos       — open the interactive full-screen task viewer
+
+| Icon | Meaning |
+|------|---------|
+| `✔` | Completed (strikethrough + dim) |
+| `◼` | In-progress |
+| `✳`/`✽` | Animated spinner — actively executing (shows elapsed time) |
+| `◻` | Pending |
+
+## `/todos` command
+
+```
+/todos  — open the interactive task manager
+```
+
+Menu options:
+- **View all tasks** — select a task to start / complete / delete it
+- **Clear completed** — remove all completed tasks
+- **Clear all** — remove all tasks
+- **⚙ Settings** — configure task storage and auto-clear
+
+## Install
+
+```bash
+pi install npm:@agnishc/edb-todo
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agnishc/edb-todo",
-	"version": "0.8.1",
+	"version": "0.10.3",
 	"description": "Pi extension: structured task list with live widget and system-prompt injection to prevent goal drift",
 	"keywords": [
 		"pi-package",

package/src/auto-clear.ts

@@ -0,0 +1,87 @@
+/**
+ * auto-clear.ts — Turn-based auto-clearing of completed tasks.
+ *
+ * Two modes:
+ * - "on_task_complete": each completed task gets its own countdown, deleted individually
+ * - "on_list_complete": countdown starts when ALL tasks are completed, cleared as a batch
+ */
+
+import type { FileTaskStore } from "./file-store.js";
+
+export type AutoClearMode = "never" | "on_list_complete" | "on_task_complete";
+
+export class AutoClearManager {
+	/** Per-task: turn when task was marked completed ("on_task_complete" mode). */
+	private completedAtTurn = new Map<string, number>();
+	/** Turn when ALL tasks became completed ("on_list_complete" mode). */
+	private allCompletedAtTurn: number | null = null;
+
+	constructor(
+		public getStore: () => FileTaskStore,
+		private getMode: () => AutoClearMode,
+		/** How many turns completed tasks linger before auto-clearing. */
+		private clearDelayTurns = 4,
+	) {}
+
+	/** Record a task completion. Call after updating status. */
+	trackCompletion(taskId: string, currentTurn: number): void {
+		const mode = this.getMode();
+		if (mode === "never") return;
+
+		if (mode === "on_task_complete") {
+			this.completedAtTurn.set(taskId, currentTurn);
+		} else if (mode === "on_list_complete") {
+			this.checkAllCompleted(currentTurn);
+		}
+	}
+
+	private checkAllCompleted(currentTurn: number): void {
+		const tasks = this.getStore().list();
+		if (tasks.length > 0 && tasks.every((t) => t.status === "completed")) {
+			if (this.allCompletedAtTurn === null) this.allCompletedAtTurn = currentTurn;
+		} else {
+			this.allCompletedAtTurn = null;
+		}
+	}
+
+	/** Reset batch countdown (e.g., when a new task is created). */
+	resetBatchCountdown(): void {
+		this.allCompletedAtTurn = null;
+	}
+
+	/** Reset all tracking state (e.g., on new session). */
+	reset(): void {
+		this.completedAtTurn.clear();
+		this.allCompletedAtTurn = null;
+	}
+
+	/**
+	 * Called on each turn start. Deletes tasks whose linger period has expired.
+	 * Returns true if any tasks were cleared.
+	 */
+	onTurnStart(currentTurn: number): boolean {
+		const mode = this.getMode();
+		let cleared = false;
+
+		if (mode === "on_task_complete") {
+			for (const [taskId, turn] of this.completedAtTurn) {
+				const task = this.getStore().get(taskId);
+				if (!task || task.status !== "completed") {
+					this.completedAtTurn.delete(taskId);
+				} else if (currentTurn - turn >= this.clearDelayTurns) {
+					this.getStore().delete(taskId);
+					this.completedAtTurn.delete(taskId);
+					cleared = true;
+				}
+			}
+		} else if (mode === "on_list_complete" && this.allCompletedAtTurn !== null) {
+			if (currentTurn - this.allCompletedAtTurn >= this.clearDelayTurns) {
+				this.getStore().clearCompleted();
+				this.allCompletedAtTurn = null;
+				cleared = true;
+			}
+		}
+
+		return cleared;
+	}
+}