@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/todo/todo-tool.js

@@ -0,0 +1,134 @@
+/**
+ * `todo_write` — the ONLY writer of `TodoStore` (todo-plan-execution §3.3 /
+ * §4.1).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * FULL-LIST REPLACEMENT, NO INCREMENTAL OPERATIONS (D-1). A delta protocol
+ * (`todo_add` / `todo_complete`) lets the model's belief and the rendered panel
+ * drift apart with nothing anywhere able to notice, and needs an id the model
+ * must keep stable across calls - a field it will eventually get wrong. A full
+ * replacement is idempotent, order-free and self-healing.
+ *
+ * THE SCHEMA DECLARES SHAPE, NOT POLICY (C-8): no `enum`, no `maxItems`, no
+ * `minItems`, and `activeForm` is not `required`. `ajv` is an OPTIONAL
+ * dependency of core, so any of those would reject a payload where it happens to
+ * be installed and repair the identical payload where it is not.
+ *
+ * PURE STATE: no filesystem, no network, no child process, no human wait. It
+ * therefore must NOT be routed through `withPausedWatchdog` (C-9) -
+ * `IdleWatchdog.pause()` is a boolean rather than a counter, so a nested
+ * pause/resume around an instant call would re-arm the watchdog inside an outer
+ * human wait.
+ */
+import { errorResult, textResult } from '@aragon-agent/core';
+import { TODO_LIMITS } from './limits.js';
+/**
+ * Turned off mid-session. A NON-ERROR result on purpose: the user turned a
+ * display off, the model did nothing wrong, and an error result invites a retry.
+ */
+export const TODO_OFF_REFUSAL = 'Todo planning is off for this session. Just do the work and say what you did.';
+/** The structural half of R-c: a one-step list is not a plan. */
+export const TOO_SMALL_REFUSAL = 'A one-step list is not a plan. Just do the work and summarize when you are done.';
+/**
+ * The model-facing description. Deliberately close to Claude Code's `TodoWrite`
+ * (R-f): what a model already knows about that tool transfers directly, and a
+ * model's priors are worth more than our naming taste - the same argument
+ * `team/task-tool.ts` records for mirroring `Task`.
+ */
+const TODO_WRITE_DESCRIPTION = 'Record and update the plan for a multi-step task. Send the complete list every time - ' +
+    'this tool replaces the whole list. Use it for work with three or more distinct steps, ' +
+    'and skip it entirely for anything you can finish in one or two. Exactly one item may be ' +
+    '`in_progress`; mark an item `completed` and the next one `in_progress` in the same call, ' +
+    `the moment the step is done. At most ${TODO_LIMITS.maxItems} items; extras are dropped, so ` +
+    'keep within it. This list is how the user follows a long task, so keep it current.';
+export function createTodoTool(deps) {
+    return {
+        name: 'todo_write',
+        label: 'Update todos',
+        description: TODO_WRITE_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                todos: {
+                    type: 'array',
+                    description: 'The COMPLETE list, every time. This replaces the previous list; there is ' +
+                        'no add or update operation.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            content: {
+                                type: 'string',
+                                description: `Imperative, <= ${TODO_LIMITS.contentChars} chars. What the step is. ` +
+                                    'e.g. "Add the rail to AppShell".',
+                            },
+                            activeForm: {
+                                type: 'string',
+                                description: `Present continuous, <= ${TODO_LIMITS.activeFormChars} chars, shown while ` +
+                                    'this step is in progress. e.g. "Adding the rail to AppShell".',
+                            },
+                            status: {
+                                type: 'string',
+                                description: 'pending | in_progress | completed. Exactly one item may be in_progress.',
+                            },
+                        },
+                        required: ['content', 'status'],
+                    },
+                },
+            },
+            required: ['todos'],
+        },
+        async execute(_id, params) {
+            // 1. Turned off mid-session. The tool array is immutable for the life of
+            //    the session (C-1), so `/todo off` cannot unregister - it flips this
+            //    closure instead.
+            if (!deps.isEnabled()) {
+                deps.store.reject(TODO_OFF_REFUSAL);
+                return textResult(TODO_OFF_REFUSAL);
+            }
+            const todos = params.todos;
+            // 2. GATED ON AN EMPTY STORE, and that gate is the whole subtlety.
+            //    Shrinking an EXISTING list to one item is legitimate - the model
+            //    merged two steps - so the guard must fire only on a fresh plan.
+            if (deps.store.isEmpty() &&
+                Array.isArray(todos) &&
+                todos.length < TODO_LIMITS.minFreshItems) {
+                deps.store.reject(TOO_SMALL_REFUSAL);
+                return textResult(TOO_SMALL_REFUSAL);
+            }
+            // 3. Repair, never reject. Zero survivors is the single hard failure, and
+            //    it leaves the previous list untouched (AC-9).
+            const result = deps.store.write(todos);
+            if (result.items.length === 0) {
+                return errorResult('No usable todo items: each needs a non-empty content string.');
+            }
+            return textResult(buildResultText(result.items, result.repairs));
+        },
+    };
+}
+/**
+ * The tool result — THE SINGLE STRONGEST LEVER ON R-b ("one at a time"), because
+ * unlike the system prompt it is re-read on every single call. There is
+ * deliberately NO RATE LIMIT to compete with it: a cap would fire exactly when
+ * the model is being most diligent and produce a refusal it cannot act on, and
+ * the costs a cap would have contained are already gone (§3.8 collapses N calls
+ * into ONE transcript entry, and the store is memory-only).
+ */
+function buildResultText(items, repairs) {
+    const done = items.filter((item) => item.status === 'completed').length;
+    const activeIndex = items.findIndex((item) => item.status === 'in_progress');
+    const lines = [`Todos updated. ${done}/${items.length} done.`];
+    if (activeIndex >= 0) {
+        lines.push(`In progress: ${items[activeIndex].activeForm}`);
+        const next = items.slice(activeIndex + 1).find((item) => item.status === 'pending');
+        if (next)
+            lines.push(`Next: ${next.content}`);
+        lines.push('Call todo_write again the moment that item is finished - exactly one item in', 'progress at a time, and do not batch several completions into one call.');
+    }
+    else {
+        lines.push('Every item is complete. Tell the user what you did.');
+    }
+    for (const repair of repairs)
+        lines.push(`Note: ${repair}`);
+    return lines.join('\n');
+}

package/dist/todo/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime shapes for the todo subsystem (todo-plan-execution §5.1).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * `TodoEvent` is CLI-LOCAL and is deliberately NOT a member of core's
+ * `AgentEvent` union (D-11), exactly as `TeamEvent` is not: core freezes its
+ * runtime export list (`public-api.test.ts`) and forbids host coupling
+ * (`no-host-coupling.test.ts`), so a new event member would break the first and
+ * teach core about a host shape it has no business defining.
+ */
+/**
+ * Re-exported so `config/schema.ts` can name the mode without importing the
+ * decision module (todo-plan-followthrough §3.1). TYPE-ONLY, so the apparent
+ * cycle `types -> follow-through -> types` is erased at compile time and there
+ * is no runtime import at all.
+ */
+export type { FollowThroughMode } from './follow-through.js';
+export type TodoStatus = 'pending' | 'in_progress' | 'completed';
+export interface TodoItem {
+    /** Imperative, sanitized, <= TODO_LIMITS.contentChars. */
+    content: string;
+    /** Present continuous, shown while in progress. Falls back to `content`. */
+    activeForm: string;
+    status: TodoStatus;
+}
+/** The immutable projection the UI renders. Rebuilt on every write. */
+export interface TodoSnapshot {
+    items: TodoItem[];
+    total: number;
+    doneCount: number;
+    /** Index of the single in_progress item, or -1 when everything is completed. */
+    activeIndex: number;
+    /**
+     * Stamped by an INJECTED clock (`TodoStore`'s constructor takes
+     * `now?: () => number`, defaulting to `Date.now`), for the reason `TeamPanel`
+     * takes a `now?` prop: a snapshot test that reads the wall clock is a test
+     * that fails on a slow machine and nowhere else (P2-4).
+     */
+    updatedAt: number;
+}
+/**
+ * Why a list went away.
+ *
+ *   `user`  - `/todo clear`.
+ *   `reset` - `/reset`, or a `/resume` whose file carried no list (§3.13).
+ *   `turn`  - every item was completed when the next user turn started.
+ *   `stale` - unfinished, and unwritten for more than `TODO_LIMITS.staleTurns`
+ *             consecutive turns (§3.2 / P1-7).
+ */
+export type TodoClearReason = 'user' | 'reset' | 'turn' | 'stale';
+export type TodoEvent = {
+    type: 'updated';
+    snapshot: TodoSnapshot;
+} | {
+    type: 'rejected';
+    reason: string;
+} | {
+    type: 'cleared';
+    reason: TodoClearReason;
+};
+export type TodoEventListener = (event: TodoEvent) => void;

package/dist/todo/types.js

@@ -0,0 +1,12 @@
+/**
+ * Runtime shapes for the todo subsystem (todo-plan-execution §5.1).
+ *
+ * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
+ *
+ * `TodoEvent` is CLI-LOCAL and is deliberately NOT a member of core's
+ * `AgentEvent` union (D-11), exactly as `TeamEvent` is not: core freezes its
+ * runtime export list (`public-api.test.ts`) and forbids host coupling
+ * (`no-host-coupling.test.ts`), so a new event member would break the first and
+ * teach core about a host shape it has no business defining.
+ */
+export {};

package/dist/tools/index.d.ts

@@ -85,6 +85,20 @@ export interface BuiltinToolsOptions {
      * burns a turn.
      */
     planTools?: AgentTool[];
+    /**
+     * `todo_write`, appended verbatim (todo-plan-execution §3.6).
+     *
+     * THROUGH THE FACTORY FOR THE REASON `teamTools` RECORDS BELOW (C-2):
+     * `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what this factory
+     * PRODUCES, so appending `todo_write` in `AgentController` after the factory
+     * returned would turn C7 red with a message about two lists of names that
+     * says nothing about todos.
+     *
+     * An empty array (the `--no-todo` path) leaves the tool list byte-identical to
+     * the pre-todo build — AC-30, provable by object identity exactly as
+     * `--no-skills` and `--no-team` are.
+     */
+    todoTools?: AgentTool[];
     /**
      * Team-mode tools, appended verbatim. The lead gets `[task]`; a subagent gets
      * `[team_send, team_wait]`.
@@ -134,7 +148,7 @@ export interface BuiltinToolsOptions {
  * is the whole of what this mechanism is worth, and saying so plainly beats
  * implying it covers more.
  */
-export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task"];
+export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write"];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
  * within `HOST_TOOL_NAMES` — "the five that change something", the set this file
@@ -167,5 +181,5 @@ export declare const PLAN_MODE_BLOCKED_TOOLS: ReadonlySet<string>;
  * declaration MEANS, and that reading must not change with how the CLI was
  * started.
  */
-export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "task"];
+export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "task"];
 export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -52,6 +52,13 @@ export const SKILL_TOOL_FLOOR = [
     // level down, with the child inheriting `agentMode` through the same closure.
     // Blocking it would forfeit parallel research, which is plan mode's best use.
     'task',
+    // `todo_write` joins the floor rather than the blocked set (D-12), and the
+    // partition test below is what forces that choice to be conscious. A todo list
+    // is a DISPLAY: it writes no file and runs no shell. More concretely, a skill
+    // whose `allowed-tools` omitted it would make the planning UI unreachable
+    // inside that skill's frame — the identical dead end that put `ask_user` /
+    // `submit_plan` / `task` here.
+    'todo_write',
 ];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
@@ -105,6 +112,7 @@ export const HOST_TOOL_NAMES = [
     'skill_create',
     'ask_user',
     'submit_plan',
+    'todo_write',
     // `team_send` / `team_wait` are DELIBERATELY ABSENT (P2-5). This constant
     // answers "can a skill's `allowed-tools` declaration ever take effect?", and
     // those two are never registered on a lead — so a skill naming them genuinely
@@ -227,6 +235,11 @@ export function createBuiltinTools(options) {
     if (options.planTools && options.planTools.length > 0) {
         tools = [...tools, ...options.planTools];
     }
+    // AFTER `planTools`, BEFORE `teamTools`, so a lead's `task` stays last and
+    // `HOST_TOOL_NAMES` changes by one insertion rather than a reshuffle.
+    if (options.todoTools && options.todoTools.length > 0) {
+        tools = [...tools, ...options.todoTools];
+    }
     // BEFORE both wrappers, so the lead's `task` is covered by the plan gate and
     // the ceiling like everything else, and a child's comm tools are covered by
     // everything except the ceiling (see `policyExempt`).