@pi9/todo 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @pi9/todo
 
-A phased, branch-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
+A phased, session-aware todo tool for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
 
 ## Features
 
@@ -15,74 +15,6 @@ A phased, branch-aware todo tool for the [Pi coding agent](https://github.com/ea
 
 Todo snapshots are stored in tool-result details, so `/tree` navigation restores the plan associated with that branch.
 
-## Tool contract
-
-The provider-facing schema is one flat object rather than a union, which keeps it compatible across Pi providers. Action-specific requirements are validated atomically by the tool.
-
-### Set the complete plan
-
-`set` discards the complete current plan and creates exactly the supplied phases and tasks. Every task starts `pending`. An empty `phases` array clears the plan.
-
-```json
-{
-  "action": "set",
-  "phases": [
-    {
-      "name": "Build",
-      "tasks": ["Implement session restoration", "Add integration coverage"]
-    }
-  ]
-}
-```
-
-### Add newly discovered work
-
-`add` creates missing phases or appends tasks to existing phases without changing current tasks or statuses. New tasks start `pending`.
-
-```json
-{
-  "action": "add",
-  "phases": [
-    {
-      "name": "Verify",
-      "tasks": ["Run the complete test suite"]
-    }
-  ]
-}
-```
-
-### Transition task statuses
-
-`transition` applies status changes atomically using exact phase and task names.
-
-```json
-{
-  "action": "transition",
-  "transitions": [
-    {
-      "phase": "Build",
-      "task": "Implement session restoration",
-      "status": "completed"
-    },
-    {
-      "phase": "Verify",
-      "task": "Run the complete test suite",
-      "status": "in_progress"
-    }
-  ]
-}
-```
-
-Phase names and task names are immutable. Task names must be unique within their phase. Cancel obsolete tasks instead of removing them; cancel and add a corrected task when its name needs to change. All `in_progress` tasks must belong to one phase.
-
-### View the plan
-
-`view` returns the complete plan or one exact phase:
-
-```json
-{ "action": "view", "phase": "Build" }
-```
-
 ## Install
 
 ```bash
@@ -104,7 +36,12 @@ The settings loader reads global settings from `~/.pi/agent/todo/settings.json`.
   "widgetPlacement": "aboveEditor",
   "maxVisibleTasks": 5,
   "fallbackGlyphs": false,
-  "toolVisibility": "set-only"
+  "toolVisibility": "set-only",
+  "dynamicReminders": true,
+  "reminderMinTurns": 4,
+  "reminderMaxTurns": 8,
+  "reminderOutputTokens": 16000,
+  "reminderMaxPerRun": 2
 }
 ```
 
@@ -118,6 +55,10 @@ The settings loader reads global settings from `~/.pi/agent/todo/settings.json`.
 
 Errors are always shown. Todo output uses native-style self-rendered shells, and hidden successful operations render zero lines. When expanded, the latest rendered `set` result on the active branch follows later additions and transitions; historical details and collapsed rendering remain unchanged.
 
+Dynamic reminders are transient user-role context messages: they are supplied to the model only for the current request and are never added to session history. A reminder is due only after `reminderMinTurns`, then when either `reminderMaxTurns` or `reminderOutputTokens` is reached, up to `reminderMaxPerRun` times per agent run. This guarded-OR cadence prevents reminders during short bursts while still catching either many small turns or a few output-heavy turns. Output tokens are counted because model-generated work, rather than prompt size, is the useful signal that a plan may have become stale. Any successful Todo action, including `view`, resets the turn/token window at the end of that turn; failed actions do not. Set `dynamicReminders` to `false` to disable reminders.
+
+After a successful manual, threshold, or overflow Pi compaction, the extension injects a one-shot transient full phased plan into the next model context build. It includes every phase and task with literal statuses, including `completed` and `cancelled` tasks and terminal-only plans; plans with zero tasks are skipped. This does not change Pi's compaction summary or session history. The injection takes priority over a due dynamic cadence reminder and resets its staleness window, regardless of `dynamicReminders`. Its pending state is in memory only and is cleared on session start/reload or `/tree` navigation, so it is not persisted across an extension reload before delivery.
+
 Settings load when a session starts. The widget refreshes after todo changes and `/tree` navigation. Set `widgetPlacement` to `"off"` to disable it.
 
 ## Development

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi9/todo",
-  "version": "0.1.0",
-  "description": "Pi extension for managing agent todo tasks.",
+  "version": "0.2.0",
+  "description": "Phased, session-aware todo planning for Pi agents.",
   "license": "MIT",
   "author": "Chase Cummings <chaseecummings@gmail.com>",
   "type": "module",

package/src/format.ts

@@ -1,6 +1,4 @@
-import type { Todo, TodoState } from "./types.js";
-
-export type PhasedTodo = Todo & { phase: string };
+import type { Todo, TodoState, TodoStatus } from "./types.js";
 
 export interface TodoCounts {
   open: number;
@@ -8,6 +6,8 @@ export interface TodoCounts {
   cancelled: number;
 }
 
+export type TodoStatusCounts = Record<TodoStatus, number>;
+
 /** A small, plain-text representation used in tool results and model context. */
 export function formatTodoSummary(state: TodoState | undefined): string {
   const tasks = todoTasks(state);
@@ -24,7 +24,8 @@ export function formatTodoSummary(state: TodoState | undefined): string {
 }
 
 export function formatTodoTaskLines(state: TodoState | undefined): string[] {
-  if (!state || state.phases.every((phase) => phase.tasks.length === 0)) return [];
+  if (!state) return [];
+
   const lines: string[] = [];
   for (const phase of state.phases) {
     if (phase.tasks.length === 0) continue;
@@ -34,17 +35,50 @@ export function formatTodoTaskLines(state: TodoState | undefined): string[] {
   return lines;
 }
 
-export function countTodos(state: TodoState | readonly Todo[] | undefined): TodoCounts {
-  const tasks = Array.isArray(state) ? state : todoTasks(state as TodoState | undefined);
-  let open = 0;
-  let completed = 0;
-  let cancelled = 0;
-  for (const task of tasks) {
-    if (task.status === "completed") completed++;
-    else if (task.status === "cancelled") cancelled++;
-    else open++;
-  }
-  return { open, completed, cancelled };
+/** Formats the complete one-shot Todo snapshot injected after compaction. */
+export function formatTodoCompactionContext(state: TodoState): string | undefined {
+  if (!state.phases.some((phase) => phase.tasks.length > 0)) return undefined;
+
+  const plan = state.phases.flatMap((phase) => [
+    `${phase.name}:`,
+    ...(phase.tasks.length === 0
+      ? ["  (no tasks)"]
+      : phase.tasks.map((task) => `  [${task.status}] ${task.name}`)),
+  ]);
+  return [
+    "<system-reminder source=\"todo-post-compaction\">",
+    "Todo plan after compaction:",
+    ...plan,
+    "Continue using this plan and keep task statuses current.",
+    "Do not mention this reminder to the user.",
+    "</system-reminder>",
+  ].join("\n");
+}
+
+export function countTodoStatuses(tasks: readonly Todo[]): TodoStatusCounts {
+  const counts: TodoStatusCounts = { pending: 0, in_progress: 0, completed: 0, cancelled: 0 };
+  for (const task of tasks) counts[task.status] += 1;
+  return counts;
+}
+
+export function countTodos(tasks: readonly Todo[]): TodoCounts {
+  const counts = countTodoStatuses(tasks);
+  return {
+    open: counts.pending + counts.in_progress,
+    completed: counts.completed,
+    cancelled: counts.cancelled,
+  };
+}
+
+export function formatTodoProgress(label: string, tasks: readonly Todo[]): string {
+  const counts = countTodoStatuses(tasks);
+  return [
+    label,
+    ...(counts.in_progress ? [`${counts.in_progress} active`] : []),
+    ...(counts.pending ? [`${counts.pending} pending`] : []),
+    ...(counts.completed ? [`${counts.completed} completed`] : []),
+    ...(counts.cancelled ? [`${counts.cancelled} cancelled`] : []),
+  ].join(" · ");
 }
 
 export function taskMarker(task: Pick<Todo, "status">): string {
@@ -56,6 +90,6 @@ export function taskMarker(task: Pick<Todo, "status">): string {
   }
 }
 
-export function todoTasks(state: TodoState | undefined): PhasedTodo[] {
-  return state?.phases.flatMap((phase) => phase.tasks.map((task) => ({ ...task, phase: phase.name }))) ?? [];
+export function todoTasks(state: TodoState | undefined): readonly Todo[] {
+  return state?.phases.flatMap((phase) => phase.tasks) ?? [];
 }

package/src/persistence.ts

@@ -1,79 +1,50 @@
-import { TODO_ACTIONS, TODO_STATUSES, type TodoState, type TodoToolDetails } from "./types.js";
+import { cloneTodoState, createTodoState, isTodoState } from "./state.js";
+import { isTodoActionName, type TodoActionName, type TodoState } from "./types.js";
 
 export const TODO_TOOL_NAME = "todo";
 
-export const createEmptyTodoState = (): TodoState => ({ phases: [] });
-
-export function cloneTodoState(state: TodoState): TodoState {
-  return structuredClone(state);
-}
-
 type BranchContext = {
   sessionManager: {
     getBranch(): readonly unknown[];
   };
 };
 
-type ToolResultEntry = {
+type TodoSnapshotDetails = {
+  action: TodoActionName;
+  state: TodoState;
+};
+
+type TodoResultEntry = {
   type: "message";
   message: {
     role: "toolResult";
-    toolName?: unknown;
+    toolName: typeof TODO_TOOL_NAME;
     isError?: unknown;
-    details?: unknown;
+    details: TodoSnapshotDetails;
   };
 };
 
-function isTodoState(value: unknown): value is TodoState {
-  if (typeof value !== "object" || value === null) return false;
-  const state = value as { phases?: unknown };
-  if (!Array.isArray(state.phases)) return false;
-
-  const phaseNames = new Set<string>();
-  let activePhase: string | undefined;
-  for (const value of state.phases) {
-    if (typeof value !== "object" || value === null) return false;
-    const phase = value as { name?: unknown; tasks?: unknown };
-    if (!validName(phase.name) || phaseNames.has(phase.name) || !Array.isArray(phase.tasks)) return false;
-    phaseNames.add(phase.name);
-
-    const taskNames = new Set<string>();
-    for (const value of phase.tasks) {
-      if (typeof value !== "object" || value === null) return false;
-      const task = value as { name?: unknown; status?: unknown };
-      if (!validName(task.name) || taskNames.has(task.name) || !(TODO_STATUSES as readonly unknown[]).includes(task.status)) return false;
-      if (task.status === "in_progress") {
-        if (activePhase !== undefined && activePhase !== phase.name) return false;
-        activePhase = phase.name;
-      }
-      taskNames.add(task.name);
-    }
-  }
-  return true;
-}
-
-function validName(value: unknown): value is string {
-  return typeof value === "string" && value !== "" && value === value.trim();
-}
-
-function isTodoToolDetails(value: unknown): value is TodoToolDetails {
-  if (typeof value !== "object" || value === null) return false;
+function isTodoSnapshotDetails(value: unknown): value is TodoSnapshotDetails {
+  if (!value || typeof value !== "object") return false;
   const details = value as { action?: unknown; state?: unknown };
-  return typeof details.action === "string"
-    && (TODO_ACTIONS as readonly string[]).includes(details.action)
-    && isTodoState(details.state);
+  return isTodoActionName(details.action) && isTodoState(details.state);
 }
 
-function isSuccessfulTodoResult(value: unknown): value is ToolResultEntry {
-  if (typeof value !== "object" || value === null) return false;
-  const entry = value as Partial<ToolResultEntry>;
-  return entry.type === "message"
-    && typeof entry.message === "object"
-    && entry.message !== null
-    && entry.message.role === "toolResult"
-    && entry.message.toolName === TODO_TOOL_NAME
-    && entry.message.isError !== true
-    && isTodoToolDetails(entry.message.details);
+function isSuccessfulTodoResult(value: unknown): value is TodoResultEntry {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as { type?: unknown; message?: unknown };
+  if (entry.type !== "message" || !entry.message || typeof entry.message !== "object") return false;
+
+  const message = entry.message as {
+    role?: unknown;
+    toolName?: unknown;
+    isError?: unknown;
+    details?: unknown;
+  };
+  return message.role === "toolResult"
+    && message.toolName === TODO_TOOL_NAME
+    && message.isError !== true
+    && isTodoSnapshotDetails(message.details);
 }
 
 /** Restores the latest successful todo snapshot from the current session branch. */
@@ -81,7 +52,7 @@ export function restoreTodoState(ctx: BranchContext): TodoState {
   const branch = ctx.sessionManager.getBranch();
   for (let index = branch.length - 1; index >= 0; index -= 1) {
     const entry = branch[index];
-    if (isSuccessfulTodoResult(entry)) return cloneTodoState((entry.message.details as TodoToolDetails).state);
+    if (isSuccessfulTodoResult(entry)) return cloneTodoState(entry.message.details.state);
   }
-  return createEmptyTodoState();
+  return createTodoState();
 }

package/src/reminder-cadence.ts

@@ -0,0 +1,59 @@
+export interface ReminderCadenceConfig {
+  readonly minTurns: number;
+  readonly maxTurns: number;
+  readonly outputTokens: number;
+  readonly maxPerRun: number;
+}
+
+export interface ReminderCadenceState {
+  readonly turns: number;
+  readonly outputTokens: number;
+  readonly remindersThisRun: number;
+}
+
+export function createReminderCadenceState(): ReminderCadenceState {
+  return { turns: 0, outputTokens: 0, remindersThisRun: 0 };
+}
+
+export function beginReminderAgentRun(state: ReminderCadenceState): ReminderCadenceState {
+  return { ...state, remindersThisRun: 0 };
+}
+
+export function noteReminderTurn(
+  state: ReminderCadenceState,
+  outputTokens: number = 0,
+): ReminderCadenceState {
+  return {
+    ...state,
+    turns: state.turns + 1,
+    outputTokens: state.outputTokens + validTokenCount(outputTokens),
+  };
+}
+
+export function noteTodoInteraction(state: ReminderCadenceState): ReminderCadenceState {
+  return { ...state, turns: 0, outputTokens: 0 };
+}
+
+export function consumeDueReminder(
+  state: ReminderCadenceState,
+  config: ReminderCadenceConfig,
+): { due: boolean; state: ReminderCadenceState } {
+  const minimumMet = state.turns >= config.minTurns;
+  const triggerMet = state.turns >= config.maxTurns || state.outputTokens >= config.outputTokens;
+  const belowCap = state.remindersThisRun < config.maxPerRun;
+
+  if (!minimumMet || !triggerMet || !belowCap) return { due: false, state };
+
+  return {
+    due: true,
+    state: {
+      turns: 0,
+      outputTokens: 0,
+      remindersThisRun: state.remindersThisRun + 1,
+    },
+  };
+}
+
+function validTokenCount(value: number): number {
+  return Number.isFinite(value) && value >= 0 ? value : 0;
+}

package/src/reminder.ts

@@ -0,0 +1,24 @@
+import { countTodoStatuses, todoTasks } from "./format.js";
+import { currentTodoPhaseIndex } from "./state.js";
+import type { TodoState } from "./types.js";
+
+/** Formats the transient model-context reminder for an unfinished todo plan. */
+export function formatTodoReminder(state: TodoState): string | undefined {
+  const activePhase = state.phases[currentTodoPhaseIndex(state.phases)];
+  if (!activePhase) return undefined;
+
+  const activeTasks = activePhase.tasks
+    .filter((task) => task.status === "in_progress")
+    .map((task) => task.name);
+  const counts = countTodoStatuses(todoTasks(state));
+
+  return [
+    "<system-reminder>",
+    `Active phase: ${activePhase.name}`,
+    activeTasks.length > 0 ? `In progress: ${activeTasks.join("; ")}` : "No task is in_progress.",
+    `Counts: ${counts.in_progress} in_progress, ${counts.pending} pending, ${counts.completed} completed, ${counts.cancelled} cancelled.`,
+    "Review and update the todo if task status has changed.",
+    "Do not mention this reminder to the user.",
+    "</system-reminder>",
+  ].join("\n");
+}

package/src/renderer.ts

@@ -1,23 +1,16 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 
-import { countTodos, formatTodoSummary, todoTasks, type PhasedTodo } from "./format.js";
+import { countTodos, formatTodoProgress, todoTasks } from "./format.js";
 import { todoGlyph } from "./glyphs.js";
-import type { TodoParams } from "./schema.js";
-import { todoAddressKey } from "./state.js";
-import type { Todo, TodoAddress, TodoPhase, TodoState, TodoToolDetails } from "./types.js";
+import { currentTodoPhaseIndex, todoAddressKey } from "./state.js";
+import type { Todo, TodoAddress, TodoToolDetails } from "./types.js";
 
 type ThemeLike = Partial<Pick<Theme, "fg" | "bold" | "strikethrough">>;
 type ThemeColor = Parameters<Theme["fg"]>[0];
 
 export type TodoRendererOptions = { fallbackGlyphs?: boolean };
 
-export function renderCall(params: TodoParams | undefined, theme?: ThemeLike): Text {
-  const action = params?.action;
-  const label = typeof action === "string" && action ? `todo ${action}` : "todo";
-  return new Text(paint(theme, "toolTitle", label), 0, 0);
-}
-
 export function renderResult(
   result: { details?: TodoToolDetails; content?: readonly { type?: string; text?: string }[] },
   options: { expanded?: boolean } = {},
@@ -30,15 +23,14 @@ export function renderResult(
   const tasks = todoTasks(state);
   if (tasks.length === 0 && state.phases.length === 0) return new Text(paint(theme, "muted", "No todo tasks."), 0, 0);
 
-  const counts = countTodos(state);
-  const header = todoHeader(counts);
+  const header = todoHeader(countTodos(tasks));
   if (options.expanded !== true) return new Text(collapsedText(header, tasks, theme, rendererOptions), 0, 0);
 
   const changed = new Set((result.details?.changedTasks ?? []).map(addressKey));
-  const selectedPhase = selectedPhaseIndex(state.phases);
-  const lines = [toolTitle(todoSummary(tasks), theme)];
+  const selectedPhase = currentTodoPhaseIndex(state.phases);
+  const lines = [toolTitle(formatTodoProgress("Todos", tasks), theme)];
   for (const [index, phase] of state.phases.entries()) {
-    const heading = `  ${index + 1}. ${phaseSummary(phase)}`;
+    const heading = `  ${index + 1}. ${formatTodoProgress(phase.name, phase.tasks)}`;
     lines.push(index === selectedPhase ? toolTitle(heading, theme) : paint(theme, "dim", heading));
     for (const task of orderedTasks(phase.tasks)) {
       lines.push(renderTask(phase.name, task, changed, theme, rendererOptions));
@@ -47,10 +39,6 @@ export function renderResult(
   return new Text(lines.join("\n"), 0, 0);
 }
 
-export function formatResultText(details: TodoToolDetails | undefined): string {
-  return formatTodoSummary(details?.state);
-}
-
 function todoHeader(counts: ReturnType<typeof countTodos>, title = "Todo"): string {
   return [
     `${title} · ${counts.open} open`,
@@ -59,47 +47,13 @@ function todoHeader(counts: ReturnType<typeof countTodos>, title = "Todo"): stri
   ].join(" · ");
 }
 
-function collapsedText(header: string, tasks: PhasedTodo[], theme: ThemeLike | undefined, options: TodoRendererOptions): string {
+function collapsedText(header: string, tasks: readonly Todo[], theme: ThemeLike | undefined, options: TodoRendererOptions): string {
   const active = tasks.find((task) => task.status === "in_progress");
   const activeText = active ? `Active: ${todoGlyph(active.status, options.fallbackGlyphs)} ${active.name}` : undefined;
   return [paint(theme, "muted", header), ...(activeText ? [paint(theme, "warning", activeText)] : []), paint(theme, "dim", "↵ expand")].join(" · ");
 }
 
-function todoSummary(tasks: Todo[]): string {
-  const active = tasks.filter((task) => task.status === "in_progress").length;
-  const pending = tasks.filter((task) => task.status === "pending").length;
-  const completed = tasks.filter((task) => task.status === "completed").length;
-  const cancelled = tasks.filter((task) => task.status === "cancelled").length;
-  return [
-    "Todos",
-    ...(active ? [`${active} active`] : []),
-    ...(pending ? [`${pending} pending`] : []),
-    ...(completed ? [`${completed} completed`] : []),
-    ...(cancelled ? [`${cancelled} cancelled`] : []),
-  ].join(" · ");
-}
-
-function phaseSummary(phase: TodoPhase): string {
-  const active = phase.tasks.filter((task) => task.status === "in_progress").length;
-  const pending = phase.tasks.filter((task) => task.status === "pending").length;
-  const completed = phase.tasks.filter((task) => task.status === "completed").length;
-  const cancelled = phase.tasks.filter((task) => task.status === "cancelled").length;
-  return [
-    phase.name,
-    ...(active ? [`${active} active`] : []),
-    ...(pending ? [`${pending} pending`] : []),
-    ...(completed ? [`${completed} completed`] : []),
-    ...(cancelled ? [`${cancelled} cancelled`] : []),
-  ].join(" · ");
-}
-
-function selectedPhaseIndex(phases: TodoPhase[]): number {
-  const active = phases.findIndex((phase) => phase.tasks.some((task) => task.status === "in_progress"));
-  if (active !== -1) return active;
-  return phases.findIndex((phase) => phase.tasks.some((task) => task.status === "pending"));
-}
-
-function orderedTasks(tasks: Todo[]): Todo[] {
+function orderedTasks(tasks: readonly Todo[]): Todo[] {
   return tasks
     .map((task, index) => ({ task, index }))
     .sort((left, right) => taskPriority(left.task) - taskPriority(right.task) || left.index - right.index)

package/src/schema.ts

@@ -1,18 +1,18 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { TODO_ACTIONS, TODO_STATUSES, type TodoActionName, type TodoPhaseInput, type TodoTransitionInput } from "./types.js";
+import { TODO_ACTIONS, TODO_STATUSES } from "./types.js";
 
 export const TodoPhaseSchema = Type.Object({
-  name: Type.String({ minLength: 1, description: "Immutable phase name, 1 or 2 words, unique." }),
+  name: Type.String({ minLength: 1, description: "Unique immutable phase name (1–2 words)." }),
   tasks: Type.Array(Type.String({
     minLength: 1,
-    description: "Immutable task name, ideally 5–10 words, what not how, unique within its phase.",
+    description: "Unique immutable task name within its phase; ideally 5–10 words describing what, not how.",
   })),
 }, { additionalProperties: false });
 
 export const TodoTransitionSchema = Type.Object({
-  phase: Type.String({ minLength: 1, description: "Exact immutable phase name." }),
-  task: Type.String({ minLength: 1, description: "Exact immutable task name within the phase." }),
+  phase: Type.String({ minLength: 1, description: "Exact phase name." }),
+  task: Type.String({ minLength: 1, description: "Exact task name within the phase." }),
   status: StringEnum(TODO_STATUSES, { description: "New task status." }),
 }, { additionalProperties: false });
 
@@ -21,15 +21,5 @@ export const TodoParamsSchema = Type.Object({
   action: StringEnum(TODO_ACTIONS),
   phases: Type.Optional(Type.Array(TodoPhaseSchema)),
   transitions: Type.Optional(Type.Array(TodoTransitionSchema, { minItems: 1 })),
-  phase: Type.Optional(Type.String({ minLength: 1, description: "Optional exact phase name used to filter view." })),
+  phase: Type.Optional(Type.String({ minLength: 1, description: "Exact phase to view; omit for the full plan." })),
 }, { additionalProperties: false });
-
-/** Broad parameter view used by tool render hooks. */
-export type TodoParams = {
-  action: TodoActionName;
-  phases?: TodoPhaseInput[];
-  transitions?: TodoTransitionInput[];
-  phase?: string;
-};
-
-export const TodoSchema = TodoParamsSchema;