@aragon-agent/cli 0.5.4 → 0.5.6

package/dist/agent/controller.d.ts

@@ -9,9 +9,10 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
-import type { CliConfig, TeamConfig, ThemeName } from '../config/schema.js';
+import type { CliConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
+import type { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
 import type { AgentMode } from './agent-mode.js';
@@ -48,6 +49,23 @@ export interface ControllerDeps {
      * wizard or a plan card.
      */
     humanInput?: HumanInputGate;
+    /**
+     * Whether this session could EVER render the todo rail (todo-plan-execution
+     * §3.7 / P1-6). Full-screen and interactive; `-p` and inline mode are false.
+     *
+     * It varies ONE SENTENCE of the `<todo_planning>` block, and nothing else.
+     * Telling the model "the user sees this list in a panel beside the
+     * conversation" under `-p` is the same error `composeSystemPrompt` already
+     * guards against for team mode with its two flags. Defaults to `false` so a
+     * caller that forgets it gets the honest sentence rather than a false claim
+     * about the user's screen.
+     *
+     * Deliberately STATIC (D-25). The two dynamic causes — a resize below
+     * `TODO_RAIL_MIN_TOTAL_COLS` and an open overlay — do NOT re-compose the
+     * prompt: rebuilding it on every resize would rewrite the system prompt
+     * mid-run, and the sentence is guidance rather than a contract.
+     */
+    todoPanelCapable?: boolean;
 }
 /** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
 export interface AgentModeState {
@@ -84,6 +102,11 @@ export declare class AgentController {
     private readonly teamRegistered;
     private teamEnabled;
     private readonly teamRuntime;
+    private readonly todoRegistered;
+    private todoEnabled;
+    private readonly todos;
+    /** Static: whether this session could ever render the rail. See the dep. */
+    private readonly todoPanelCapable;
     constructor(config: CliConfig, deps?: ControllerDeps);
     private resolveKey;
     /**
@@ -229,6 +252,53 @@ export declare class AgentController {
     subscribeTeam(listener: (event: TeamEvent) => void): () => void;
     /** Abort every child and clear timers. Idempotent; safe to call twice. */
     dispose(): void;
+    /** Whether `todo_write` is in `this.tools`. Fixed at construction (C-1). */
+    isTodoRegistered(): boolean;
+    /** Whether `todo_write` will actually write. Flipped live by `/todo on|off`. */
+    isTodoEnabled(): boolean;
+    /**
+     * Flip the live switch and RE-RENDER THE PROMPT.
+     *
+     * THE REBUILD IS NOT OPTIONAL (P1-1 / AC-37). `composeSystemPrompt()` gates
+     * `todoBlock` on `todoRegistered && todoEnabled`; without the rebuild
+     * `<todo_planning>` survives `/todo off`, every call comes back with
+     * `TODO_OFF_REFUSAL`, and the instructions telling the model to keep calling
+     * are still in its own context — a refusal loop it cannot diagnose.
+     *
+     * Turning it ON in a session that started with `--no-todo` deliberately does
+     * NOT register the tool: the array is immutable (C-1), and advertising an
+     * unregistered tool is the dead end `/team on` already documents. `/todo`
+     * reports that honestly by checking `isTodoRegistered()` first.
+     */
+    setTodoEnabled(enabled: boolean): void;
+    getTodoConfig(): TodoConfig;
+    /**
+     * Adopt a new todo config for this session.
+     *
+     * THIS EXISTS BECAUSE `persistConfig` DOES NOT TOUCH THE RUNTIME (P1-2 /
+     * AC-38). `App` reads `controller.getConfig()` on every render, and that
+     * returns THIS object; the App's `persistConfig` only writes the file. So
+     * `/todo panel off` must call both, exactly as `/team max` does — with only
+     * the persist call the command reports success and changes nothing until the
+     * next launch.
+     *
+     * Clamped here as well as on the persist path, so a bad value can reach
+     * neither the runtime nor the file. The prompt rebuild carries §3.7's
+     * `panelVisible` sentence, which is part of the block.
+     */
+    setTodoConfig(patch: Partial<TodoConfig>): TodoConfig;
+    getTodoSnapshot(): TodoSnapshot | null;
+    /**
+     * Subscribe to the CLI-local todo event stream.
+     *
+     * Returns a no-op unsubscribe when todo planning was off at construction, so
+     * every caller can subscribe unconditionally.
+     */
+    subscribeTodos(listener: TodoEventListener): () => void;
+    /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
+    restoreTodos(items: unknown): void;
+    /** `/todo clear`. A user override of a projection; refused mid-run by `/todo`. */
+    clearTodos(): void;
     setModel(provider: string, model: string, baseUrl?: string): void;
     setThinkingLevel(level: ThinkingLevel): void;
     setMaxTokens(value: number | undefined): void;

package/dist/agent/controller.js

@@ -9,7 +9,7 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
-import { clampTeamConfig, isAdapterProvider } from '../config/schema.js';
+import { clampTeamConfig, clampTodoConfig, isAdapterProvider } from '../config/schema.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
@@ -17,6 +17,9 @@ import { TeamRuntime } from '../team/runtime.js';
 import { TeamHumanQueue } from '../team/human-queue.js';
 import { createTaskTool } from '../team/task-tool.js';
 import { buildTeamBlock } from '../team/prompt.js';
+import { TodoStore } from '../todo/store.js';
+import { createTodoTool } from '../todo/todo-tool.js';
+import { buildTodoBlock } from '../todo/prompt.js';
 import { createPlanTools } from '../tools/plan-tools.js';
 import { DENY_ALL_HUMAN_INPUT } from '../tools/human-input.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
@@ -71,6 +74,26 @@ export class AgentController {
     teamRegistered;
     teamEnabled;
     teamRuntime;
+    // -----------------------------------------------------------------------
+    // Todo planning (todo-plan-execution §3.6a) — THE SAME TWO FLAGS, FOR THE
+    // SAME REASON.
+    //
+    // `todoRegistered` is decided ONCE, at construction: whether `todo_write` is
+    // in `this.tools` at all. The array is immutable for the life of the session
+    // (C-1), so `/todo on` in a session started with `--no-todo` CANNOT add it.
+    //
+    // `todoEnabled` is live. `/todo off` flips it, which makes `todo_write` refuse
+    // through its own closure AND drops `<todo_planning>` from the next prompt
+    // rebuild — and BOTH halves are required (P1-1). Flip the flag without the
+    // rebuild and the block survives `/todo off`: every call comes back with the
+    // refusal while the instructions telling the model to keep calling are still
+    // in its own context, so it cannot diagnose the loop.
+    // -----------------------------------------------------------------------
+    todoRegistered;
+    todoEnabled;
+    todos;
+    /** Static: whether this session could ever render the rail. See the dep. */
+    todoPanelCapable;
     constructor(config, deps = {}) {
         this.config = config;
         this.cwd = config.cwd;
@@ -104,6 +127,11 @@ export class AgentController {
             this.skills.reportUnknownForcedSkills();
         }
         const confirm = deps.confirm;
+        // --- Todo planning -----------------------------------------------------
+        this.todoRegistered = config.todo.enabled;
+        this.todoEnabled = config.todo.enabled;
+        this.todoPanelCapable = deps.todoPanelCapable === true;
+        this.todos = this.todoRegistered ? new TodoStore() : null;
         // --- Team mode ---------------------------------------------------------
         this.teamRegistered = config.team.enabled;
         this.teamEnabled = config.team.enabled;
@@ -167,6 +195,18 @@ export class AgentController {
                 withHumanWait: (fn) => this.withHumanWait(fn),
                 onPlanApproved: () => this.setAgentMode('build', { force: true }),
             }),
+            // THROUGH THE FACTORY for the reason `teamTools` records below (C-2), and
+            // empty when todo planning was off at construction — which leaves the
+            // array byte-identical to the pre-todo build (AC-30).
+            todoTools: this.todos
+                ? [
+                    createTodoTool({
+                        store: this.todos,
+                        // Read LIVE: `/todo off` flips the flag, it cannot unregister.
+                        isEnabled: () => this.todoEnabled,
+                    }),
+                ]
+                : [],
             // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
             // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
             // `createBuiltinTools` produces, so appending `task` here would turn that
@@ -286,6 +326,16 @@ export class AgentController {
                     maxConcurrent: this.config.team.maxConcurrent,
                 })
                 : '',
+            // BOTH FLAGS, exactly as team mode uses both, and for the identical
+            // reason: `todoRegistered` false means there is no `todo_write` to
+            // advertise, `todoEnabled` false means the user turned it off for this
+            // session, and advertising in either case would describe a capability the
+            // model does not have.
+            todoBlock: this.todoRegistered && this.todoEnabled
+                ? buildTodoBlock({
+                    panelVisible: this.todoPanelCapable && this.config.todo.panel,
+                })
+                : '',
         });
     }
     rebuildSystemPrompt() {
@@ -382,6 +432,11 @@ export class AgentController {
         // steering "actually, use Postgres" into a running plan is answering the
         // questions, not buying four more rounds of them.
         this.askRounds = 0;
+        // Same asymmetry, same reason (§3.5): a completed plan is dropped HERE
+        // rather than at `agent_end`, so the user gets their `7/7 done` moment, and
+        // an unfinished one survives "continue" / "now do the rest" but not four
+        // unrelated turns.
+        this.todos?.beginUserTurn();
         return this.agent.prompt(text);
     }
     abort() {
@@ -579,6 +634,80 @@ export class AgentController {
         this.teamRuntime?.dispose();
     }
     // -----------------------------------------------------------------------
+    // Todo planning (todo-plan-execution §3.6a)
+    // -----------------------------------------------------------------------
+    /** Whether `todo_write` is in `this.tools`. Fixed at construction (C-1). */
+    isTodoRegistered() {
+        return this.todoRegistered;
+    }
+    /** Whether `todo_write` will actually write. Flipped live by `/todo on|off`. */
+    isTodoEnabled() {
+        return this.todoEnabled;
+    }
+    /**
+     * Flip the live switch and RE-RENDER THE PROMPT.
+     *
+     * THE REBUILD IS NOT OPTIONAL (P1-1 / AC-37). `composeSystemPrompt()` gates
+     * `todoBlock` on `todoRegistered && todoEnabled`; without the rebuild
+     * `<todo_planning>` survives `/todo off`, every call comes back with
+     * `TODO_OFF_REFUSAL`, and the instructions telling the model to keep calling
+     * are still in its own context — a refusal loop it cannot diagnose.
+     *
+     * Turning it ON in a session that started with `--no-todo` deliberately does
+     * NOT register the tool: the array is immutable (C-1), and advertising an
+     * unregistered tool is the dead end `/team on` already documents. `/todo`
+     * reports that honestly by checking `isTodoRegistered()` first.
+     */
+    setTodoEnabled(enabled) {
+        this.todoEnabled = enabled;
+        this.rebuildSystemPrompt();
+    }
+    getTodoConfig() {
+        return this.config.todo;
+    }
+    /**
+     * Adopt a new todo config for this session.
+     *
+     * THIS EXISTS BECAUSE `persistConfig` DOES NOT TOUCH THE RUNTIME (P1-2 /
+     * AC-38). `App` reads `controller.getConfig()` on every render, and that
+     * returns THIS object; the App's `persistConfig` only writes the file. So
+     * `/todo panel off` must call both, exactly as `/team max` does — with only
+     * the persist call the command reports success and changes nothing until the
+     * next launch.
+     *
+     * Clamped here as well as on the persist path, so a bad value can reach
+     * neither the runtime nor the file. The prompt rebuild carries §3.7's
+     * `panelVisible` sentence, which is part of the block.
+     */
+    setTodoConfig(patch) {
+        const todo = clampTodoConfig({ ...this.config.todo, ...patch });
+        this.config = { ...this.config, todo };
+        this.rebuildSystemPrompt();
+        return todo;
+    }
+    getTodoSnapshot() {
+        return this.todos?.snapshot() ?? null;
+    }
+    /**
+     * Subscribe to the CLI-local todo event stream.
+     *
+     * Returns a no-op unsubscribe when todo planning was off at construction, so
+     * every caller can subscribe unconditionally.
+     */
+    subscribeTodos(listener) {
+        if (!this.todos)
+            return () => { };
+        return this.todos.subscribe(listener);
+    }
+    /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
+    restoreTodos(items) {
+        this.todos?.restore(items);
+    }
+    /** `/todo clear`. A user override of a projection; refused mid-run by `/todo`. */
+    clearTodos() {
+        this.todos?.clear('user');
+    }
+    // -----------------------------------------------------------------------
     // Mutators
     // -----------------------------------------------------------------------
     setModel(provider, model, baseUrl) {
@@ -620,6 +749,11 @@ export class AgentController {
         // A new conversation has no loaded skills, so the "already loaded earlier
         // in this conversation" hint would otherwise start lying (P2-9).
         this.skills.getRegistry().clearActive();
+        // `/reset` clears `messages`, so the belief that justifies the panel is gone
+        // with them and the list must go too (I-2). `/clear` reaches the transcript
+        // and NOT this method, which is the whole distinction: it tells the model
+        // nothing, so it may not change the list.
+        this.todos?.clear('reset');
     }
     /** Read-only view of the live system prompt (regression tests, /debug). */
     getSystemPrompt() {

package/dist/agent/headless.d.ts

@@ -7,6 +7,8 @@
 import type { AgentEvent, ModelInfo } from '@aragon-agent/core';
 import type { PreflightResult } from './controller.js';
 import type { TeamEvent } from '../team/types.js';
+import type { TodoEvent, TodoSnapshot } from '../todo/types.js';
+import { type FollowThroughMode } from '../todo/follow-through.js';
 /** The minimal controller surface headless mode needs (real or stubbed). */
 export interface HeadlessController {
     preflight(): PreflightResult;
@@ -24,11 +26,38 @@ export interface HeadlessController {
      * the `--no-team` headless path byte-identical to today's.
      */
     subscribeTeam?(listener: (event: TeamEvent) => void): () => void;
+    /**
+     * The CLI-local todo stream — OPTIONAL, for the identical reason
+     * `subscribeTeam` is (todo-plan-execution §3.12). This interface is minimal so
+     * tests can satisfy it with an object literal; making the member REQUIRED
+     * would break every existing stub for no benefit, and a controller with no
+     * store genuinely has no todo events. `runHeadless` calls it with `?.`, which
+     * keeps a `--no-todo` headless run byte-identical to today's.
+     */
+    subscribeTodos?(listener: (event: TodoEvent) => void): () => void;
+    /**
+     * The current plan — OPTIONAL, for the identical reason the two subscriptions
+     * above are (todo-plan-followthrough §3.6 rule 2). ABSENT MEANS THE
+     * CONTINUATION LOOP NEVER RUNS, which is what keeps a stubbed controller's
+     * stdout, stderr and exit code byte-identical to today's (AC-23).
+     */
+    getTodoSnapshot?(): TodoSnapshot | null;
 }
 export interface HeadlessOptions {
     quiet?: boolean;
     stdout?: NodeJS.WritableStream;
     stderr?: NodeJS.WritableStream;
+    /**
+     * Follow-through mode for `-p` (todo-plan-followthrough §3.6). Defaults to
+     * `'notify'`, so an omitted option behaves exactly as the resolved default
+     * config does.
+     *
+     * PASSED IN RATHER THAN READ OFF THE CONTROLLER, because `HeadlessController`
+     * is deliberately the minimal surface a test can satisfy with an object
+     * literal; `runOneShot` holds the real `AgentController` and reads
+     * `getTodoConfig().followThrough` there.
+     */
+    followThrough?: FollowThroughMode;
 }
 /** Run a single prompt headlessly and resolve with the process exit code. */
 export declare function runHeadless(controller: HeadlessController, prompt: string, options?: HeadlessOptions): Promise<number>;

package/dist/agent/headless.js

@@ -6,6 +6,7 @@
  */
 import { formatCost, formatTokens, formatDuration, computeCost } from './usage.js';
 import { formatStreamError } from './reducer.js';
+import { advanceBudget, decideFollowThrough, emptyBudget, } from '../todo/follow-through.js';
 /** Run a single prompt headlessly and resolve with the process exit code. */
 export async function runHeadless(controller, prompt, options = {}) {
     const out = options.stdout ?? process.stdout;
@@ -96,12 +97,96 @@ export async function runHeadless(controller, prompt, options = {}) {
                 `${event.outcome.aborted ? ' (aborted)' : ''}\n`);
         }
     });
+    // ONE LINE PER TRANSITION OF THE ACTIVE ITEM, not one per call: a model that
+    // rewrites the list without moving the cursor produces no output at all.
+    //
+    // These lines are interleaved with the generic `> todo_write (1ms)` pairs
+    // above, because that loop keys on the EVENT and not on the tool name (P2-2).
+    // `SELF_RENDERING_TOOLS` is a TRANSCRIPT concept and teaching this writer
+    // about it would put the same name in two places for a cosmetic gain on a
+    // stream that is already `--quiet`-able in full.
+    let announcedTotal = 0;
+    let lastActive = -1;
+    const unsubscribeTodos = controller.subscribeTodos?.((event) => {
+        if (quiet || event.type !== 'updated')
+            return;
+        const { total, doneCount, activeIndex, items } = event.snapshot;
+        if (total !== announcedTotal) {
+            announcedTotal = total;
+            err.write(`\n[todo] ${total} ${total === 1 ? 'step' : 'steps'} planned\n`);
+            lastActive = -1;
+        }
+        if (activeIndex < 0) {
+            if (lastActive !== -2) {
+                lastActive = -2;
+                err.write(`[todo] ${doneCount}/${total} done\n`);
+            }
+            return;
+        }
+        if (activeIndex === lastActive)
+            return;
+        lastActive = activeIndex;
+        err.write(`[todo] ${activeIndex + 1}/${total} ${items[activeIndex]?.content ?? ''}\n`);
+    });
+    // --- The bounded continuation loop (todo-plan-followthrough §3.6). --------
+    //
+    // THE THREE `unsubscribe` CALLS STAY OUTSIDE IT (rule 4). The loop wraps the
+    // whole `try/finally` rather than sitting inside it, because unsubscribing per
+    // iteration would silently cost iteration 2 onwards its `[todo]` progress
+    // lines, its team usage accounting and — worst — the `agent_end` handler that
+    // computes `errored`, so a failing second iteration would exit 0.
+    //
+    // Deciding the moment `prompt()` resolves is safe: `agent.prompt()` awaits
+    // `runLoopWithLifecycle()`, whose `finally` emits `agent_end` BEFORE resolving,
+    // and `emit` is synchronous — so `errored` and `sawTurnEnd` are already final.
+    const followThrough = options.followThrough ?? 'notify';
+    let budget = emptyBudget();
+    let wasAutoContinuation = false;
     try {
-        await controller.prompt(prompt);
+        let message = prompt;
+        for (;;) {
+            // PER-ITERATION RESET (rule 1). `sawTurnEnd` is the silent-failure
+            // detector; left sticky, a swallowed throw on iteration 2 is invisible
+            // because iteration 1 set the flag. `errored` is deliberately NOT reset —
+            // once a run has errored the exit code is 1 and the loop must stop.
+            sawTurnEnd = false;
+            await controller.prompt(message);
+            const snapshot = controller.getTodoSnapshot?.() ?? null;
+            budget = advanceBudget(budget, snapshot, wasAutoContinuation);
+            wasAutoContinuation = false;
+            const decision = decideFollowThrough({
+                mode: followThrough,
+                snapshot,
+                // `aborted` is STRUCTURALLY false here (C-2): `-p` has no Esc and
+                // installs no signal handler that marks one, so there is nothing to
+                // derive and nothing to plumb. An errored run takes the `notify` branch
+                // below and ends the loop, which is what keeps exit code 1 reachable.
+                runEnd: { aborted: false, errored },
+                budget,
+                interactive: false,
+            });
+            if (decision.kind === 'none')
+                break;
+            if (decision.kind === 'notify') {
+                if (!quiet)
+                    err.write(`\n[todo] ${decision.text}\n`);
+                break;
+            }
+            // CHARGED BEFORE THE RE-PROMPT, and this line is the whole of the headless
+            // cap (P1-2 / I-5 / AC-37). The TUI charges `used` in its grace-timer
+            // callback; headless has no timer, so without this `maxAutoContinuesPerList`
+            // would never bind in the one environment with no human to press Esc.
+            budget = { ...budget, used: budget.used + 1 };
+            wasAutoContinuation = true;
+            if (!quiet)
+                err.write(`\n[todo] ${decision.notice}\n`);
+            message = decision.message;
+        }
     }
     finally {
         unsubscribe();
         unsubscribeTeam?.();
+        unsubscribeTodos?.();
     }
     // Ensure a trailing newline so piped output is well-formed.
     if (wroteText)

package/dist/agent/reducer.d.ts

@@ -13,6 +13,7 @@
 import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agent/core';
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
+import type { TodoItem, TodoSnapshot } from '../todo/types.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
 export type Overlay = null | 'settings' | 'model' | 'help' | 'confirm' | 'question' | 'plan';
@@ -78,6 +79,34 @@ export type Entry = {
     aborted: boolean;
     durationMs?: number;
     active: boolean;
+}
+/**
+ * The turn's todo checklist (todo-plan-execution §3.8). ONE per user turn,
+ * rewritten in place — a 7-item list updated twice per item would otherwise be
+ * 14 near-identical tool cards in the one surface the user reads most.
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * `live: true` is normalized away ON LOAD, in `session/persist.ts`, for the
+ * same reason the team entry's `active` is (C-5): `Transcript`'s settled
+ * boundary is MONOTONIC, so an entry that never settles never reaches
+ * `<Static>` and is re-rendered on every frame for the rest of the session.
+ */
+ | {
+    id: string;
+    kind: 'todo';
+    items: TodoItem[];
+    doneCount: number;
+    total: number;
+    /** The turn that owns this card is still running, so it may be rewritten. */
+    live: boolean;
+    /**
+     * Set by `normalizeLoadedEntries` on a card saved while its run was live
+     * (P2-6). The todo analogue of the team entry's `aborted`, and true for the
+     * same reason: the run behind it died with the process. Absent on every
+     * card this session produced.
+     */
+    interrupted?: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
@@ -112,9 +141,20 @@ export interface ViewState {
      * live dispatch to show (§6.4).
      */
     team: TeamSnapshot | null;
+    /**
+     * The live todo list, or `null` when there is none.
+     *
+     * NEVER PERSISTED HERE — `entries` is the history and `SavedSession.todos` is
+     * the list (§3.13). `null` is what leaves the rail unmounted entirely, which
+     * is why a session that never plans has byte-identical layout to a pre-feature
+     * build (AC-24).
+     */
+    todos: TodoSnapshot | null;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
+    /** The `kind: 'todo'` entry this turn is writing into. */
+    todoEntryId?: string;
     streamingId?: string;
     turnProduced: boolean;
     errorNoticed: boolean;
@@ -213,6 +253,11 @@ export type ViewAction = {
 } | {
     type: 'teamEnd';
     outcome: DispatchOutcome;
+} | {
+    type: 'todoUpdate';
+    snapshot: TodoSnapshot;
+} | {
+    type: 'todoCleared';
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;

package/dist/agent/reducer.js

@@ -28,8 +28,10 @@ export function initialViewState() {
         agentMode: 'build',
         pendingAgentMode: null,
         team: null,
+        todos: null,
         seq: 0,
         teamEntryId: undefined,
+        todoEntryId: undefined,
         streamingId: undefined,
         turnProduced: false,
         errorNoticed: false,
@@ -118,6 +120,20 @@ export function reduceEvent(event, cost) {
             return [];
     }
 }
+/**
+ * Tools that render their own transcript entry, so the generic tool card would
+ * be a duplicate. EXACTLY ONE MEMBER; read todo-plan-execution §3.8 before
+ * adding a second.
+ *
+ * SUPPRESSING ONLY `tool_call_start` IS SUFFICIENT, AND THAT IS THE WHOLE REASON
+ * THIS IS SAFE (D-10). Every later handler — `toolCallDelta` / `toolCallEnd` /
+ * `toolExecStart` / `toolExecEnd` — resolves its target through
+ * `findToolEntryId`, which returns `undefined` when no entry was created, and
+ * every one of them already early-returns on that. There is no fifth handler. A
+ * second suppression rule would be four more places to get the id matching
+ * wrong, for nothing.
+ */
+const SELF_RENDERING_TOOLS = new Set(['todo_write']);
 function reduceStreamEvent(se) {
     switch (se.type) {
         case 'thinking_start':
@@ -127,6 +143,8 @@ function reduceStreamEvent(se) {
         case 'text_delta':
             return [{ type: 'textDelta', delta: se.delta }];
         case 'tool_call_start':
+            if (SELF_RENDERING_TOOLS.has(se.toolName))
+                return [];
             return [
                 { type: 'toolCallStart', toolCallId: se.toolCallId, toolName: se.toolName },
             ];
@@ -201,6 +219,10 @@ export function viewReducer(state, action) {
                 seq,
                 entries: [...state.entries, entry],
                 streamingId: undefined,
+                // A new turn gets its own card, in that turn's position in the
+                // transcript. The PREVIOUS card stays exactly where it is — it is
+                // history, and history is not retracted.
+                todoEntryId: undefined,
                 turnProduced: false,
                 errorNoticed: false,
                 aborted: false,
@@ -346,6 +368,11 @@ export function viewReducer(state, action) {
                     { id: next.id, kind: 'notice', level: 'error', text: GENERIC_RUN_FAILURE },
                 ];
             }
+            // The card may now reach `<Static>` (C-5 / I-6): the turn that owns it is
+            // over, so nothing will rewrite it.
+            if (state.todoEntryId) {
+                entries = mapEntry(entries, state.todoEntryId, (e) => e.kind === 'todo' ? { ...e, live: false } : e);
+            }
             return { ...state, entries, seq, status: 'idle', streamingId: undefined };
         }
         case 'notice': {
@@ -379,6 +406,11 @@ export function viewReducer(state, action) {
                 streamingId: undefined,
                 expandedToolIds: {},
                 teamEntryId: undefined,
+                // The entry it pointed at is gone, so the id goes with it. `todos` is
+                // DELIBERATELY UNTOUCHED (I-2): `/clear` wipes the transcript and not
+                // the conversation, so the model still believes in the plan, and a panel
+                // that disagrees with the model is worse than no panel.
+                todoEntryId: undefined,
             };
         case 'resetConversation':
             return {
@@ -389,6 +421,11 @@ export function viewReducer(state, action) {
                 contextTokens: 0,
                 usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
                 teamEntryId: undefined,
+                // `/reset` clears `messages`, so the belief is gone and the list goes
+                // with it — the other half of I-2. `controller.clearMessages()` clears
+                // the STORE; this clears the mirror.
+                todos: null,
+                todoEntryId: undefined,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -496,13 +533,55 @@ export function viewReducer(state, action) {
             // "(dang you de shi hou)": it renders only while a dispatch is running.
             return { ...state, entries, team: null, teamEntryId: undefined };
         }
+        // --- Todo planning (todo-plan-execution §5.2) -------------------------
+        case 'todoUpdate': {
+            const entry = (id) => ({
+                id,
+                kind: 'todo',
+                items: action.snapshot.items,
+                doneCount: action.snapshot.doneCount,
+                total: action.snapshot.total,
+                live: true,
+            });
+            // Rewrite the turn's card when there is one; otherwise append and record
+            // its id. One `mapEntry` on the KNOWN id, never a scan.
+            if (state.todoEntryId) {
+                const known = state.todoEntryId;
+                return {
+                    ...state,
+                    todos: action.snapshot,
+                    entries: mapEntry(state.entries, known, (e) => e.kind === 'todo' ? { ...entry(known), live: e.live } : e),
+                };
+            }
+            const { id, seq } = nextId(state);
+            return {
+                ...state,
+                seq,
+                todos: action.snapshot,
+                entries: [...state.entries, entry(id)],
+                todoEntryId: id,
+            };
+        }
+        // THE ENTRY STAYS. It is history, and history is not retracted — only the
+        // live projection goes away, which is what unmounts the rail.
+        case 'todoCleared':
+            return { ...state, todos: null, todoEntryId: undefined };
         case 'restoreEntries': {
             // Adopt a seq beyond any restored id to keep future ids unique.
             const maxSeq = action.entries.reduce((acc, e) => {
                 const n = Number.parseInt(e.id.replace(/^e/, ''), 10);
                 return Number.isFinite(n) ? Math.max(acc, n) : acc;
             }, state.seq);
-            return { ...state, entries: [...action.entries], seq: maxSeq, teamEntryId: undefined };
+            return {
+                ...state,
+                entries: [...action.entries],
+                seq: maxSeq,
+                teamEntryId: undefined,
+                // As for `team`: the restored cards are history and no turn owns them.
+                // The LIST itself arrives separately, through `controller.restoreTodos`
+                // and the store's own event (§3.13).
+                todoEntryId: undefined,
+            };
         }
         default:
             return state;