@pi9/todo 0.1.0 → 0.2.0

package/src/tool.ts

@@ -1,39 +1,43 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Container, type Component } from "@earendil-works/pi-tui";
-import { formatTodoSummary } from "./format.js";
+import { formatTodoCompactionContext, formatTodoSummary } from "./format.js";
 import { restoreTodoState } from "./persistence.js";
+import {
+  beginReminderAgentRun,
+  consumeDueReminder,
+  createReminderCadenceState,
+  noteReminderTurn,
+  noteTodoInteraction,
+  type ReminderCadenceConfig,
+} from "./reminder-cadence.js";
+import { formatTodoReminder } from "./reminder.js";
 import { renderResult as renderTodoResult } from "./renderer.js";
 import { TodoToolFrame, type TodoToolFrameContent, type TodoToolFrameTheme } from "./tool-frame.js";
 import { TodoParamsSchema } from "./schema.js";
-import { DEFAULT_TODO_UI_SETTINGS, loadTodoUiSettings, type TodoUiSettings } from "./settings.js";
+import { DEFAULT_TODO_SETTINGS, loadTodoSettings, type TodoSettings } from "./settings.js";
 import { createTodoState, todoAddressKey, transitionTodoState } from "./state.js";
-import { TODO_STATUSES, type TodoAction, type TodoAddress, type TodoState, type TodoToolDetails } from "./types.js";
+import type { TodoAddress, TodoState, TodoStatus, TodoToolDetails } from "./types.js";
 import { shouldRenderTodoAction } from "./visibility.js";
 import { updateTodoWidget } from "./widget.js";
 
-function taskStatuses(state: TodoState): Map<string, string> {
+function taskStatuses(state: TodoState): Map<string, TodoStatus> {
   return new Map(state.phases.flatMap((phase) => phase.tasks.map((task) => [todoAddressKey(phase.name, task.name), task.status])));
 }
 
-function taskAddresses(state: TodoState): Map<string, TodoAddress> {
-  return new Map(state.phases.flatMap((phase) => phase.tasks.map((task) => {
-    const address = { phase: phase.name, task: task.name };
-    return [todoAddressKey(address.phase, address.task), address];
+function taskAddresses(state: TodoState): TodoAddress[] {
+  return state.phases.flatMap((phase) => phase.tasks.map((task) => ({
+    phase: phase.name,
+    task: task.name,
   })));
 }
 
 function changedTasks(previous: TodoState, next: TodoState): TodoAddress[] {
   const before = taskStatuses(previous);
-  const after = taskStatuses(next);
-  const addresses = taskAddresses(next);
-  return [...after.keys()].filter((key) => before.get(key) !== after.get(key)).map((key) => addresses.get(key)!);
-}
-
-function completedTasks(previous: TodoState, next: TodoState): TodoAddress[] {
-  const before = taskStatuses(previous);
-  return next.phases.flatMap((phase) => phase.tasks
-    .filter((task) => task.status === "completed" && before.has(todoAddressKey(phase.name, task.name)) && before.get(todoAddressKey(phase.name, task.name)) !== "completed")
-    .map((task) => ({ phase: phase.name, task: task.name })));
+  return next.phases.flatMap((phase) => phase.tasks.flatMap((task) =>
+    before.get(todoAddressKey(phase.name, task.name)) === task.status
+      ? []
+      : [{ phase: phase.name, task: task.name }],
+  ));
 }
 
 function createTodoFrame(
@@ -58,6 +62,15 @@ type TodoRenderInput = {
 type TodoRenderTheme = Parameters<typeof renderTodoResult>[2];
 type TrackedSetRenderer = { toolCallId: string; invalidate?: () => void };
 
+function reminderConfig(settings: TodoSettings): ReminderCadenceConfig {
+  return {
+    minTurns: settings.reminderMinTurns,
+    maxTurns: settings.reminderMaxTurns,
+    outputTokens: settings.reminderOutputTokens,
+    maxPerRun: settings.reminderMaxPerRun,
+  };
+}
+
 /** Expanded content for the one set result that is allowed to follow in-memory state. */
 class LiveSetResult implements Component {
   constructor(
@@ -81,7 +94,10 @@ class LiveSetResult implements Component {
 
 export function registerTodoTool(pi: ExtensionAPI): void {
   let state = createTodoState();
-  let settings: TodoUiSettings = { ...DEFAULT_TODO_UI_SETTINGS };
+  let settings: TodoSettings = { ...DEFAULT_TODO_SETTINGS };
+  let reminderCadence = createReminderCadenceState();
+  let pendingCompactionContext: string | undefined;
+  let interactedWithTodoThisTurn = false;
   let queue: Promise<void> = Promise.resolve();
   let latestSetRenderer: TrackedSetRenderer | undefined;
 
@@ -95,30 +111,81 @@ export function registerTodoTool(pi: ExtensionAPI): void {
     updateTodoWidget(ctx, state, settings);
   };
 
+  const resetReminderTracking = (): void => {
+    reminderCadence = createReminderCadenceState();
+    interactedWithTodoThisTurn = false;
+  };
+
   pi.on("session_start", async (_event, ctx) => {
-    const loaded = await loadTodoUiSettings(ctx);
+    const loaded = await loadTodoSettings(ctx);
     settings = loaded.settings;
     if (loaded.warning) ctx.ui.notify(loaded.warning, "warning");
     restore(ctx);
+    pendingCompactionContext = undefined;
+    resetReminderTracking();
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    restore(ctx);
+    pendingCompactionContext = undefined;
+    resetReminderTracking();
+  });
+  pi.on("session_compact", () => {
+    pendingCompactionContext = formatTodoCompactionContext(state);
+    if (pendingCompactionContext) reminderCadence = noteTodoInteraction(reminderCadence);
+  });
+  pi.on("before_agent_start", () => {
+    reminderCadence = beginReminderAgentRun(reminderCadence);
+  });
+  pi.on("turn_end", (event) => {
+    reminderCadence = interactedWithTodoThisTurn
+      ? noteTodoInteraction(reminderCadence)
+      : noteReminderTurn(
+          reminderCadence,
+          event.message.role === "assistant" ? event.message.usage?.output ?? 0 : 0,
+        );
+    interactedWithTodoThisTurn = false;
+  });
+  pi.on("context", (event) => {
+    if (pendingCompactionContext) {
+      const content = pendingCompactionContext;
+      pendingCompactionContext = undefined;
+      return {
+        messages: [...event.messages, { role: "user", content, timestamp: Date.now() }],
+      };
+    }
+
+    if (!settings.dynamicReminders) return;
+
+    const reminder = formatTodoReminder(state);
+    if (!reminder) return;
+
+    const consumed = consumeDueReminder(reminderCadence, reminderConfig(settings));
+    if (!consumed.due) return;
+
+    reminderCadence = consumed.state;
+    return {
+      messages: [...event.messages, { role: "user", content: reminder, timestamp: Date.now() }],
+    };
   });
-  pi.on("session_tree", (_event, ctx) => restore(ctx));
 
   pi.registerTool({
     name: "todo",
     label: "Todo",
     description: [
-      "Maintain a concise phased plan that reflects both intended work and current execution progress.",
+      "Maintain a phased task plan.",
       "Actions:",
-      "  set: Replace the entire plan. All tasks reset to pending. Use only for a new plan or full re-plan.",
-      "  add: Append tasks or phases without touching existing work.",
-      "  transition: Update task statuses (" + TODO_STATUSES.join(", ") + ") by exact phase and task name.",
-      "  view: Return the plan, optionally filtered to one phase.",
+      "  set(phases): Replace the plan; supplied tasks start pending.",
+      "  add(phases): Add phases or tasks; preserve existing tasks and statuses.",
+      "  transition(transitions): Set statuses by exact phase and task names.",
+      "  view(phase?): Return the full plan or one exact phase.",
     ].join("\n"),
-    promptSnippet: "Track multi-step work with the todo tool; keep statuses current as you go",
+    promptSnippet: "Track multi-step work in a phased task plan",
     promptGuidelines: [
-      "Use todo for non-trivial work with three or more distinct steps; skip todo for simple tasks.",
-      "Transition todo statuses immediately and honestly—mark tasks completed only when fully done, not merely attempted, and cancel abandoned tasks rather than leaving them pending.",
-      "Todo tasks in_progress must all belong to a single phase; finish or cancel a phase's active tasks before starting the next.",
+      "Use todo for work with 3+ distinct steps; skip it for 1–2 steps.",
+      "Transition todo tasks immediately when work starts or ends; do not defer updates until the end.",
+      "Complete todo tasks only after the work is done and verified; cancel abandoned or obsolete tasks.",
+      "Add material new work to todo as new tasks rather than expanding existing task scope.",
+      "Keep `in_progress` todo tasks in one phase; complete or cancel them before starting another phase.",
     ],
     parameters: TodoParamsSchema,
     renderShell: "self",
@@ -126,22 +193,22 @@ export function registerTodoTool(pi: ExtensionAPI): void {
     execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const run = queue.then(() => {
         const previous = state;
-        const next = transitionTodoState(previous, params as TodoAction);
+        const next = transitionTodoState(previous, params);
         const details: TodoToolDetails = {
           action: params.action,
           state: next,
           changedTasks: params.action === "view"
             ? []
             : params.action === "set"
-              ? [...taskAddresses(next).values()]
+              ? taskAddresses(next)
               : changedTasks(previous, next),
-          completedTasks: params.action === "transition" ? completedTasks(previous, next) : [],
         };
         if (params.action !== "view") {
           state = next;
           invalidateLatestSetRenderer();
         }
         updateTodoWidget(ctx, state, settings);
+        interactedWithTodoThisTurn = true;
         return {
           content: [{ type: "text" as const, text: formatTodoSummary(next) }],
           details,

package/src/types.ts

@@ -1,63 +1,70 @@
 export const TODO_STATUSES = ["pending", "in_progress", "completed", "cancelled"] as const;
 export type TodoStatus = typeof TODO_STATUSES[number];
 
+export function isTodoStatus(value: unknown): value is TodoStatus {
+  return typeof value === "string" && (TODO_STATUSES as readonly string[]).includes(value);
+}
+
 export const TODO_ACTIONS = ["set", "add", "transition", "view"] as const;
 export type TodoActionName = typeof TODO_ACTIONS[number];
 
+export function isTodoActionName(value: unknown): value is TodoActionName {
+  return typeof value === "string" && (TODO_ACTIONS as readonly string[]).includes(value);
+}
+
 export type Todo = {
-  name: string;
-  status: TodoStatus;
+  readonly name: string;
+  readonly status: TodoStatus;
 };
 
 export type TodoPhase = {
-  name: string;
-  tasks: Todo[];
+  readonly name: string;
+  readonly tasks: readonly Todo[];
 };
 
 export type TodoState = {
-  phases: TodoPhase[];
+  readonly phases: readonly TodoPhase[];
 };
 
 export type TodoAddress = {
-  phase: string;
-  task: string;
+  readonly phase: string;
+  readonly task: string;
 };
 
 /** Persisted with a successful tool result so session state can be restored. */
 export type TodoToolDetails = {
-  action: TodoActionName;
-  state: TodoState;
-  changedTasks: TodoAddress[];
-  completedTasks: TodoAddress[];
+  readonly action: TodoActionName;
+  readonly state: TodoState;
+  readonly changedTasks: readonly TodoAddress[];
 };
 
 export type TodoPhaseInput = {
-  name: string;
-  tasks: string[];
+  readonly name: string;
+  readonly tasks: readonly string[];
 };
 
 export type TodoTransitionInput = TodoAddress & {
-  status: TodoStatus;
+  readonly status: TodoStatus;
 };
 
 export type SetTodoAction = {
-  action: "set";
-  phases: TodoPhaseInput[];
+  readonly action: "set";
+  readonly phases: readonly TodoPhaseInput[];
 };
 
 export type AddTodoAction = {
-  action: "add";
-  phases: TodoPhaseInput[];
+  readonly action: "add";
+  readonly phases: readonly TodoPhaseInput[];
 };
 
 export type TransitionTodoAction = {
-  action: "transition";
-  transitions: TodoTransitionInput[];
+  readonly action: "transition";
+  readonly transitions: readonly TodoTransitionInput[];
 };
 
 export type ViewTodoAction = {
-  action: "view";
-  phase?: string;
+  readonly action: "view";
+  readonly phase?: string;
 };
 
 export type TodoAction = SetTodoAction | AddTodoAction | TransitionTodoAction | ViewTodoAction;

package/src/visibility.ts

@@ -1,9 +1,5 @@
 import type { TodoToolVisibility } from "./settings.js";
-import { TODO_ACTIONS, type TodoActionName } from "./types.js";
-
-function isTodoActionName(action: unknown): action is TodoActionName {
-  return typeof action === "string" && (TODO_ACTIONS as readonly string[]).includes(action);
-}
+import { isTodoActionName } from "./types.js";
 
 /** Returns whether a successful todo action should be shown in tool output. */
 export function shouldRenderTodoAction(action: unknown, visibility: TodoToolVisibility): boolean {

package/src/widget-component.ts

@@ -1,4 +1,4 @@
-import { wrapTextWithAnsi, type Component, type TUI } from "@earendil-works/pi-tui";
+import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
 import type { TodoState } from "./types.js";
@@ -9,6 +9,10 @@ const DROPLET_DURATIONS_MS = [220, 110, 80, 100, 420] as const;
 const PI_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
 const PI_SPINNER_INTERVAL_MS = 80;
 
+type TodoWidgetComponentOptions = TodoWidgetLayoutOptions & {
+  blankLineBelow?: boolean;
+};
+
 /** A width-aware component for Pi's persistent widget area. */
 export class TodoWidgetComponent implements Component {
   private frameIndex = 0;
@@ -17,7 +21,7 @@ export class TodoWidgetComponent implements Component {
   constructor(
     private readonly state: TodoState,
     private readonly theme: Theme | undefined,
-    private readonly options: TodoWidgetLayoutOptions = {},
+    private readonly options: TodoWidgetComponentOptions = {},
     private readonly tui?: Pick<TUI, "requestRender">,
   ) {
     if (tui && state.phases.some(phase => phase.tasks.some(task => task.status === "in_progress"))) {
@@ -25,14 +29,17 @@ export class TodoWidgetComponent implements Component {
     }
   }
 
-  invalidate(): void { }
+  invalidate(): void {}
 
   render(width: number): string[] {
     const safeWidth = Math.max(1, Math.floor(width) || 1);
-    return renderTodoWidgetLines(this.state, this.theme, safeWidth, {
-      ...this.options,
+    const { blankLineBelow, ...layoutOptions } = this.options;
+    const lines = renderTodoWidgetLines(this.state, this.theme, safeWidth, {
+      ...layoutOptions,
       activeMarker: this.frames[this.frameIndex],
-    }).flatMap(line => wrapTextWithAnsi(line, safeWidth));
+    });
+    if (blankLineBelow && lines.length > 0) lines.push("");
+    return lines;
   }
 
   dispose(): void {

package/src/widget-layout.ts

@@ -1,7 +1,9 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
+import { formatTodoProgress, todoTasks } from "./format.js";
 import { todoGlyph } from "./glyphs.js";
+import { currentTodoPhaseIndex } from "./state.js";
 import type { Todo, TodoPhase, TodoState } from "./types.js";
 
 export type TodoWidgetLayoutOptions = {
@@ -14,10 +16,7 @@ type ThemeLike = Partial<Pick<Theme, "bold" | "fg" | "strikethrough">>;
 
 type DisplayTask = Todo & { taskIndex: number };
 
-/**
- * Produces compact widget rows. Every returned row is constrained to the supplied display width;
- * the component may subsequently wrap a row when a host chooses a narrower cell.
- */
+/** Produces compact widget rows constrained to the supplied display width. */
 export function renderTodoWidgetLines(
   state: TodoState | undefined,
   theme: ThemeLike | undefined,
@@ -25,15 +24,13 @@ export function renderTodoWidgetLines(
   options: TodoWidgetLayoutOptions = {},
 ): string[] {
   const safeWidth = Math.max(1, Math.floor(width) || 1);
-  const phases = Array.isArray(state?.phases) ? state.phases : [];
-  if (phases.length === 0 || !phases.some(phase => phase.tasks.length > 0)) return [];
-
-  const selectedPhaseIndex = selectPhase(phases);
+  const phases = state?.phases ?? [];
+  const selectedPhaseIndex = currentTodoPhaseIndex(phases);
   if (selectedPhaseIndex < 0) return [];
   const selectedPhase = phases[selectedPhaseIndex];
   const maxVisible = boundedMaxVisible(options.maxVisible);
   const selectedTasks = visibleTasks(selectedPhase.tasks, maxVisible);
-  const lines: string[] = [fit(toolTitle(summary(phases), theme), safeWidth)];
+  const lines: string[] = [fit(toolTitle(formatTodoProgress("Todos", todoTasks(state)), theme), safeWidth)];
 
   for (let phaseIndex = 0; phaseIndex < phases.length; phaseIndex++) {
     const phase = phases[phaseIndex];
@@ -58,55 +55,23 @@ export function renderTodoWidgetLines(
   return lines;
 }
 
-/** Alias kept for callers that prefer a builder-style name. */
-export const buildTodoWidgetLines = renderTodoWidgetLines;
-
 function boundedMaxVisible(value: number | undefined): number {
-  if (!Number.isFinite(value)) return 5;
-  return Math.max(1, Math.floor(value!));
-}
-
-function summary(phases: TodoPhase[]): string {
-  const tasks = phases.flatMap(phase => phase.tasks);
-  const active = tasks.filter(isActive).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(" · ");
+  if (value === undefined || !Number.isFinite(value)) return 5;
+  return Math.max(1, Math.floor(value));
 }
 
 function phaseTitle(phase: TodoPhase, phaseIndex: number, selected: boolean, theme: ThemeLike | undefined): string {
-  const title = `${phaseIndex + 1}. ${phaseSummary(phase)}`;
+  const title = `${phaseIndex + 1}. ${formatTodoProgress(phase.name, phase.tasks)}`;
   if (selected) return toolTitle(`  ${title}`, theme);
   return theme?.fg ? theme.fg("dim", `  ${title}`) : `  ${title}`;
 }
 
-function phaseSummary(phase: TodoPhase): string {
-  const active = phase.tasks.filter(isActive).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 toolTitle(text: string, theme: ThemeLike | undefined): string {
   const bold = theme?.bold ? theme.bold(text) : text;
   return theme?.fg ? theme.fg("toolTitle", bold) : bold;
 }
 
-function visibleTasks(tasks: Todo[], maxVisible: number): DisplayTask[] {
+function visibleTasks(tasks: readonly Todo[], maxVisible: number): DisplayTask[] {
   const ordered = tasks
     .map((task, taskIndex) => ({ ...task, taskIndex }))
     .filter(task => !isTerminal(task))
@@ -132,13 +97,7 @@ function taskPriority(task: Todo): number {
   return 2;
 }
 
-function selectPhase(phases: TodoPhase[]): number {
-  const active = phases.findIndex(phase => phase.tasks.some(isActive));
-  if (active >= 0) return active;
-  return phases.findIndex(phase => phase.tasks.some(task => task.status === "pending"));
-}
-
-function terminalTaskSummary(tasks: Todo[]): string | undefined {
+function terminalTaskSummary(tasks: readonly Todo[]): string | undefined {
   const completed = tasks.filter(task => task.status === "completed").length;
   const cancelled = tasks.filter(task => task.status === "cancelled").length;
   const parts = [

package/src/widget.ts

@@ -1,20 +1,14 @@
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 
+import type { TodoSettings } from "./settings.js";
 import type { TodoState } from "./types.js";
 import { TodoWidgetComponent } from "./widget-component.js";
 
-export type TodoWidgetPlacement = "belowEditor" | "aboveEditor" | "off";
-
-/**
- * Deliberately structural so this unit does not depend on the settings persistence layer.
- * The widget-prefixed forms allow a future settings module to expose namespaced UI settings.
- */
-export type TodoWidgetSettings = {
-  widgetPlacement?: TodoWidgetPlacement;
-  maxVisibleTasks?: number;
-  fallbackGlyphs?: boolean;
-};
+export type TodoWidgetSettings = Partial<Pick<
+  TodoSettings,
+  "widgetPlacement" | "maxVisibleTasks" | "fallbackGlyphs"
+>>;
 
 type WidgetComponentFactory = (tui: TUI, theme: Theme) => Component & { dispose?(): void };
 
@@ -39,19 +33,18 @@ export function updateTodoWidget(ctx: TodoWidgetContext | undefined, state: Todo
       return;
     }
 
-    const hasVisibleTasks = state?.phases.some(phase => phase.tasks.some(task =>
+    const visibleState = state?.phases.some(phase => phase.tasks.some(task =>
       task.status === "pending" || task.status === "in_progress",
-    )) ?? false;
-    const factory: WidgetComponentFactory | undefined = hasVisibleTasks
-      ? (tui, theme) => new TodoWidgetComponent(state!, theme, {
+    )) ? state : undefined;
+    const factory: WidgetComponentFactory | undefined = visibleState
+      ? (tui, theme) => new TodoWidgetComponent(visibleState, theme, {
           maxVisible: settings.maxVisibleTasks,
           fallbackGlyphs: settings.fallbackGlyphs,
+          blankLineBelow: placement === "aboveEditor",
         }, tui)
       : undefined;
     ctx.ui.setWidget("todo", factory, { placement });
   } catch (error) {
-    try {
-      ctx.ui.notify?.(`Todo widget update failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
-    } catch { }
+    ctx.ui.notify?.(`Todo widget update failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
   }
 }