@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/tools/human-input.js

@@ -0,0 +1,227 @@
+/**
+ * The human-input channel (plan-mode §3.5 / §5.1) — types, the fail-closed
+ * default gate, and the two pure normalizers that repair whatever the model
+ * actually sent.
+ *
+ * Everything here is pure except the type declarations: no Ink, no React, no
+ * `node:*`. `tools/` is inside the glyph scanner's scope, so every literal is
+ * ASCII.
+ *
+ * WHY THE NORMALIZERS ARE THE ONLY AUTHORITY ON THE LIMITS (P0-4). The
+ * model-facing schemas in `plan-tools.ts` declare SHAPE only — `type`,
+ * `required`, `default` — and put every bound in the `description`. They used to
+ * carry `minItems` / `maxItems` / `maxLength`, and that had two failure modes at
+ * once: `ToolExecutor` rejected a six-question call outright with `Invalid
+ * parameters: ...` before any repair could run, wasting a full research turn on
+ * a cosmetic defect; and `ajv` is an OPTIONAL dependency of core, so without it
+ * the fallback validator checks `required` plus primitive types only and the
+ * same call sailed through. One design, two behaviours, selected by whether an
+ * optional install step succeeded. Bounds live here instead, where they are
+ * deterministic and unit-tested.
+ */
+import { OTHER_OPTION_LABEL } from '../agent/agent-mode.js';
+/**
+ * Fails CLOSED. The headless default — forgetting to pass a gate must refuse,
+ * never hang and never assume yes.
+ */
+export const DENY_ALL_HUMAN_INPUT = {
+    neverPrompts: true,
+    canPrompt: () => false,
+    request: async () => null,
+};
+// ---------------------------------------------------------------------------
+// Limits (the single authority; see the module header for why not the schema)
+// ---------------------------------------------------------------------------
+export const QUESTION_LIMITS = {
+    maxQuestions: 5,
+    minOptions: 2,
+    maxOptions: 4,
+    headerChars: 12,
+    questionChars: 300,
+    labelChars: 60,
+    optionDescriptionChars: 120,
+};
+export const PLAN_LIMITS = {
+    titleChars: 80,
+    summaryChars: 600,
+    maxSteps: 20,
+    stepTitleChars: 100,
+    stepDetailChars: 400,
+    maxFiles: 30,
+    maxRisks: 10,
+    maxOpenQuestions: 10,
+};
+/** How far back a truncation will look for a space before cutting hard. */
+const WORD_BOUNDARY_WINDOW = 12;
+// ---------------------------------------------------------------------------
+// Small pure helpers
+// ---------------------------------------------------------------------------
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Trim to `max` characters, preferring a word boundary within the last
+ * `WORD_BOUNDARY_WINDOW` characters. Cutting a sentence mid-word reads as
+ * corruption; cutting it at a space reads as a summary.
+ */
+export function clampText(raw, max) {
+    const text = asString(raw).trim();
+    if (text.length <= max)
+        return text;
+    const head = text.slice(0, max);
+    const space = head.lastIndexOf(' ');
+    if (space >= max - WORD_BOUNDARY_WINDOW && space > 0)
+        return head.slice(0, space).trimEnd();
+    return head.trimEnd();
+}
+/**
+ * DROP FIRST, CAP SECOND, and it matters.
+ *
+ * Capping the raw array first would let blank or duplicate entries consume slots
+ * the model meant for real content: a list of 30 paths with two repeats would
+ * come back with 28 real ones and no way to tell that anything was lost.
+ */
+function nonEmptyStrings(raw, max, dedupe = false) {
+    const cleaned = asArray(raw)
+        .map((v) => asString(v).trim())
+        .filter((s) => s.length > 0);
+    return (dedupe ? [...new Set(cleaned)] : cleaned).slice(0, max);
+}
+// ---------------------------------------------------------------------------
+// normalizeQuestions
+// ---------------------------------------------------------------------------
+/**
+ * Repair whatever the model sent into something renderable.
+ *
+ * Returns `[]` when nothing survives, which the tool turns into the one hard
+ * failure this path has. Every rule below is reachable precisely BECAUSE the
+ * schema stopped declaring the bounds (P0-4); with `minItems` / `maxItems` in
+ * the schema, `ajv` rejected the call first and rules 1 and 4 were dead code.
+ */
+export function normalizeQuestions(raw) {
+    const out = [];
+    // Rule 1a: keep the first N questions.
+    for (const item of asArray(raw).slice(0, QUESTION_LIMITS.maxQuestions)) {
+        const question = normalizeOneQuestion(asRecord(item), out.length);
+        if (question)
+            out.push(question);
+    }
+    return out;
+}
+function normalizeOneQuestion(src, index) {
+    const text = clampText(src.question, QUESTION_LIMITS.questionChars);
+    if (text.length === 0)
+        return null;
+    // Rule 1b + 1c: at least 2 options, at most 4.
+    const rawOptions = asArray(src.options).slice(0, QUESTION_LIMITS.maxOptions);
+    const options = [];
+    const seen = new Set();
+    for (const rawOption of rawOptions) {
+        const record = asRecord(rawOption);
+        const label = clampText(record.label, QUESTION_LIMITS.labelChars);
+        if (label.length === 0)
+            continue;
+        // Rule 4: deduplicate labels case-insensitively. Two options the user cannot
+        // tell apart is worse than one option fewer.
+        const key = label.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        options.push({
+            label,
+            description: clampText(record.description, QUESTION_LIMITS.optionDescriptionChars),
+            recommended: record.recommended === true,
+            isOther: false,
+        });
+    }
+    if (options.length < QUESTION_LIMITS.minOptions)
+        return null;
+    // Rules 2 and 3: exactly one recommended, always. The recommended option is
+    // the wizard's initial highlight, so "none" and "several" are both unusable.
+    const firstRecommended = options.findIndex((o) => o.recommended);
+    options.forEach((option, i) => {
+        option.recommended = i === (firstRecommended === -1 ? 0 : firstRecommended);
+    });
+    // Rule 5: the synthetic free-text escape hatch, unless the model already
+    // supplied something that reads as one.
+    if (!options.some((o) => /^other/i.test(o.label))) {
+        options.push({ label: OTHER_OPTION_LABEL, description: '', recommended: false, isOther: true });
+    }
+    else {
+        const existing = options.find((o) => /^other/i.test(o.label));
+        existing.isOther = true;
+    }
+    const id = asString(src.id).trim();
+    return {
+        id: id.length > 0 ? id : `q${index + 1}`,
+        header: clampText(src.header, QUESTION_LIMITS.headerChars) || `Q${index + 1}`,
+        question: text,
+        options,
+        allowMultiple: src.allowMultiple === true,
+    };
+}
+// ---------------------------------------------------------------------------
+// normalizePlan
+// ---------------------------------------------------------------------------
+/**
+ * Repair a submitted plan. Returns `null` only when no step survives — the one
+ * hard failure, because there is then nothing left to review.
+ *
+ * A plan that is one step over the cap is still a plan, and rejecting it costs a
+ * full research turn to regain nothing. Truncation is silent to the model but
+ * VISIBLE to the user: the review overlay's position indicator counts the real
+ * rows, so a clipped plan cannot masquerade as complete.
+ */
+export function normalizePlan(raw) {
+    const src = asRecord(raw);
+    // Same drop-first, cap-second discipline as `nonEmptyStrings`: a blank-titled
+    // step is noise, and letting it consume one of the twenty slots would silently
+    // discard a real step at the other end.
+    const steps = [];
+    for (const rawStep of asArray(src.steps)) {
+        const record = asRecord(rawStep);
+        const title = clampText(record.title, PLAN_LIMITS.stepTitleChars);
+        if (title.length === 0)
+            continue;
+        steps.push({ title, detail: clampText(record.detail, PLAN_LIMITS.stepDetailChars) });
+        if (steps.length === PLAN_LIMITS.maxSteps)
+            break;
+    }
+    if (steps.length === 0)
+        return null;
+    return {
+        title: clampText(src.title, PLAN_LIMITS.titleChars) || 'Untitled plan',
+        summary: clampText(src.summary, PLAN_LIMITS.summaryChars),
+        steps,
+        // Exact deduplication, NOT case-insensitive: POSIX paths are case-sensitive
+        // and two casings are two files.
+        filesTouched: nonEmptyStrings(src.filesTouched, PLAN_LIMITS.maxFiles, true),
+        risks: nonEmptyStrings(src.risks, PLAN_LIMITS.maxRisks),
+        openQuestions: nonEmptyStrings(src.openQuestions, PLAN_LIMITS.maxOpenQuestions),
+    };
+}
+/**
+ * Render the `ask_user` result: one human-readable line so the transcript
+ * preview is legible without parsing, then the JSON the model reads.
+ *
+ * `asked` is passed separately rather than derived from `answers.length`
+ * because a cancelled wizard returns fewer answers than it asked for, and
+ * "answered 1 of 3" is the whole information content of that line.
+ */
+export function formatAnswersResult(shape, asked) {
+    const headline = shape.cancelled
+        ? 'User dismissed the questions.'
+        : `User answered ${shape.answers.length} of ${asked} questions.`;
+    const guidance = shape.cancelled
+        ? ' Proceed with your best assumptions and say what you assumed.'
+        : '';
+    return `${headline}${guidance}\n${JSON.stringify(shape, null, 2)}`;
+}

package/dist/tools/index.d.ts

@@ -9,6 +9,7 @@
  * before the tool runs.
  */
 import { type AgentTool, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+import type { AgentMode } from '../agent/agent-mode.js';
 export interface ConfirmRequest {
     tool: string;
     summary: string;
@@ -36,7 +37,10 @@ export interface BuiltinToolsOptions {
      * changes mid-turn (a `skill` call adds to it, a rescan can empty it), and a
      * cached decision would ignore the skill the model just loaded.
      *
-     * Omitting this leaves every tool unwrapped — see the early return below.
+     * Omitting this leaves every tool unwrapped BY THIS GATE — see the first of
+     * the two independent guards at the end of `createBuiltinTools`. It used to be
+     * an early return, and P0-1 replaced it precisely because an early return also
+     * skipped the plan-mode gate below it (R2-P2-3).
      */
     toolPolicy?: () => ToolPolicyDecision;
     /**
@@ -52,6 +56,22 @@ export interface BuiltinToolsOptions {
         verdict: ToolPolicyVerdict;
         sourceNames: string[];
     }) => void;
+    /**
+     * Read the mode AT CALL TIME. Never cache: the mode can flip mid-run when the
+     * user approves a plan, and a cached `'plan'` would refuse the very work the
+     * user just authorized.
+     *
+     * Omitting this leaves every tool unwrapped by THIS gate — see the second,
+     * INDEPENDENT guard at the end of `createBuiltinTools`, which is what keeps
+     * the 7-tool / 11-tool baselines byte-identical (I-S1 / AC-G17).
+     */
+    agentMode?: () => AgentMode;
+    /**
+     * `ask_user` / `submit_plan`, appended verbatim. Empty in headless mode, where
+     * no overlay can be rendered and showing the model a tool it cannot use just
+     * burns a turn.
+     */
+    planTools?: AgentTool[];
 }
 /**
  * Tools the ceiling always permits (D-G6). The ONLY place that knows which of
@@ -68,7 +88,19 @@ 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"];
+export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan"];
+/**
+ * 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
+ * already names in prose above.
+ *
+ * It lives HERE, next to the floor, rather than in `agent/agent-mode.ts` with
+ * the rest of the mode vocabulary. The invariant worth having is that these two
+ * sets PARTITION `HOST_TOOL_NAMES`, and a partition test is only as trustworthy
+ * as the distance between the two definitions it compares. Splitting them
+ * across modules is how they drift.
+ */
+export declare const PLAN_MODE_BLOCKED_TOOLS: ReadonlySet<string>;
 /**
  * Every tool name this host CAN register (7 built-ins + 4 skill tools).
  *
@@ -89,5 +121,5 @@ export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob"
  * 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"];
+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"];
 export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -9,6 +9,7 @@
  * before the tool runs.
  */
 import { errorResult, evaluateToolCall, } from '@aragon-agent/core';
+import { planRefusal, submitPlanRefusal } from '../agent/agent-mode.js';
 import { makeReadFile, makeWriteFile, makeEditFile, makeListDir } from './fs-tools.js';
 import { makeGlob, makeGrep } from './search-tools.js';
 import { makeBash } from './bash-tool.js';
@@ -35,7 +36,35 @@ export const SKILL_TOOL_FLOOR = [
     'grep',
     'skill',
     'skill_find',
+    // The two human-input tools join the floor for the same reason `skill` /
+    // `skill_find` did: a skill that declares `allowed-tools` without naming them
+    // would make `ask_user` unreachable and dead-end plan mode — the exact dead
+    // end iteration 2 of the skills work spent a round removing. Neither is a
+    // filesystem mutation, so the ceiling loses nothing it was protecting.
+    // (`submit_plan` does mutate the SESSION MODE, which is why the floor is now
+    // described as "everything that cannot write to disk" rather than
+    // "read-only".)
+    'ask_user',
+    'submit_plan',
 ];
+/**
+ * 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
+ * already names in prose above.
+ *
+ * It lives HERE, next to the floor, rather than in `agent/agent-mode.ts` with
+ * the rest of the mode vocabulary. The invariant worth having is that these two
+ * sets PARTITION `HOST_TOOL_NAMES`, and a partition test is only as trustworthy
+ * as the distance between the two definitions it compares. Splitting them
+ * across modules is how they drift.
+ */
+export const PLAN_MODE_BLOCKED_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'bash',
+    'skill_install',
+    'skill_create',
+]);
 /**
  * Every tool name this host CAN register (7 built-ins + 4 skill tools).
  *
@@ -68,6 +97,8 @@ export const HOST_TOOL_NAMES = [
     'skill_find',
     'skill_install',
     'skill_create',
+    'ask_user',
+    'submit_plan',
 ];
 function summarize(toolName, params) {
     if (toolName === 'bash')
@@ -121,6 +152,42 @@ function withToolPolicy(tool, getDecision, notify) {
         },
     };
 }
+/**
+ * Wrap a tool in the plan-mode read-only gate. Same `{...tool, execute}` shape
+ * as `withConfirmation` / `withToolPolicy`, so nothing in the engine needs to
+ * know this happened.
+ *
+ * Read-only becomes a property of the WIRING rather than a promise in a prompt:
+ * the badge says PLAN because these five cannot run, not because the model was
+ * asked nicely.
+ *
+ * CODEACT IS NOT A HOLE TODAY, AND THAT IS WORTH WRITING DOWN. The
+ * ```execute-js``` path in the core agent loop runs through `ctx.sandbox`, not
+ * through any `AgentTool`, so no tool wrapper can see it. The CLI passes no
+ * `sandbox` to `new Agent(...)`, which makes the path inert. Anyone wiring a
+ * sandbox later must gate it as well, or plan mode gains a shell by the back
+ * door.
+ */
+function withPlanModeGate(tool, getMode) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const mode = getMode();
+            if (mode === 'plan' && PLAN_MODE_BLOCKED_TOOLS.has(tool.name)) {
+                return errorResult(planRefusal(tool.name));
+            }
+            // Asymmetric on purpose: `ask_user` is available in BOTH modes, because a
+            // clarifying question is never harmful and refusing a tool the model can
+            // see just burns a turn. `submit_plan` mutates the session mode and only
+            // means something while a plan is being reviewed.
+            if (mode !== 'plan' && tool.name === 'submit_plan') {
+                return errorResult(submitPlanRefusal());
+            }
+            return original(id, params, ctx);
+        },
+    };
+}
 export function createBuiltinTools(options) {
     const deps = { getCwd: options.getCwd };
     let tools = [
@@ -139,19 +206,39 @@ export function createBuiltinTools(options) {
     if (options.skillTools && options.skillTools.length > 0) {
         tools = [...tools, ...options.skillTools];
     }
+    if (options.planTools && options.planTools.length > 0) {
+        tools = [...tools, ...options.planTools];
+    }
     // No decision provider (`--no-skills`, or a caller that never enabled the
-    // policy) means the tools go out exactly as they came in.
+    // policy) means the ceiling adds nothing.
     //
-    // A ceiling that always says "allow" would behave identically, so this early
-    // return buys nothing at run time — it buys the ability to PROVE the claim.
-    // AC-G17 asserts object identity on this path; with a wrapper in place, "the
+    // A ceiling that always says "allow" would behave identically, so skipping it
+    // buys nothing at run time — it buys the ability to PROVE the claim. AC-G17
+    // asserts object identity on this path; with a wrapper in place, "the
     // `--no-skills` path is unchanged from iteration 2" would demote from a fact
     // anyone can check to an argument someone has to trust.
-    if (!options.toolPolicy)
-        return tools;
+    //
     // Outermost on purpose (D-G11). Asking a human "run bash?", waiting for them
     // to say yes, and only then reporting that policy refused it is the worst
-    // available ordering. The ceiling needs no I/O, so it goes first.
-    const getDecision = options.toolPolicy;
-    return tools.map((t) => withToolPolicy(t, getDecision, options.onToolPolicyEvent));
+    // available ordering. The ceiling needs no I/O, so it goes before confirmation.
+    if (options.toolPolicy) {
+        const getDecision = options.toolPolicy;
+        tools = tools.map((t) => withToolPolicy(t, getDecision, options.onToolPolicyEvent));
+    }
+    // TWO OPTIONS, TWO INDEPENDENT GUARDS, NO SHARED EXIT.
+    //
+    // This used to be a single `if (!options.toolPolicy) return tools;` early
+    // return ending the function. That return sits BEFORE the plan gate, and
+    // `--no-skills` / `ARAGON_SKILLS=0` supply no decision provider — so
+    // `aragon --no-skills --plan` returned before the gate was applied and ran
+    // with write_file / edit_file / bash fully live while the badge said PLAN.
+    // If you ever collapse these two guards back into one, that is the bug you
+    // are reintroducing, and nothing reports it (AC-P20 / I-P3).
+    //
+    // The plan gate is applied LAST, which makes it OUTERMOST at call time: it
+    // needs no I/O and no state, so it must not sit behind a human wait.
+    if (!options.agentMode)
+        return tools;
+    const getMode = options.agentMode;
+    return tools.map((t) => withPlanModeGate(t, getMode));
 }

package/dist/tools/plan-tools.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `ask_user` and `submit_plan` — the two tools that only exist because a human
+ * is attached (plan-mode §4.1 / §4.2 / §5.3).
+ *
+ * ASCII ONLY: `tools/` is inside the glyph scanner's scope.
+ *
+ * THE SCHEMAS DECLARE SHAPE, NOT POLICY (P0-4). `type`, `required` and `default`
+ * stay, because a `questions` value that is not an array has nothing for a
+ * normalizer to repair and both validator strategies agree on that check.
+ * Everything else — how many questions, how many options, how long a header may
+ * be — lives in the `description`, which is what the model actually reads, and
+ * is enforced by `normalizeQuestions` / `normalizePlan`. Putting `maxItems: 5`
+ * in the schema instead had two failure modes at once: with `ajv` present
+ * `ToolExecutor` rejected a six-question call outright and the repair rules were
+ * dead code; without it (ajv is an OPTIONAL dependency of core) the same call
+ * sailed straight through to the repair path. One design, two behaviours,
+ * selected by whether an optional install step succeeded.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import { type HumanInputGate } from './human-input.js';
+/** The outcome of trying to spend one `ask_user` round. */
+export interface AskRoundTicket {
+    ok: boolean;
+    used: number;
+    remaining: number;
+    max: number;
+}
+export interface PlanToolsOptions {
+    gate: HumanInputGate;
+    /**
+     * Spend one `ask_user` round. The counter is owned by the controller because
+     * it resets per user turn, and the controller is the only object that sees a
+     * turn begin.
+     */
+    takeAskRound: () => AskRoundTicket;
+    /**
+     * Run `fn` with the idle watchdog paused. `try/finally` inside, so a throw in
+     * the overlay path cannot leave the watchdog disarmed for the rest of the run.
+     */
+    withHumanWait: <T>(fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Approve the plan: flip the session to Build IMMEDIATELY, mid-run.
+     *
+     * This is the one place a `plan -> build` transition is not deferred to
+     * `agent_end`, and the asymmetry is the whole point: the user has just read
+     * the plan and authorized exactly this work. A stray `Shift+Tab` has not.
+     */
+    onPlanApproved: () => void;
+}
+/**
+ * Build the plan tools, or `[]` for a channel that can never reach a human.
+ *
+ * KEYED ON `neverPrompts`, NOT `canPrompt()` (P0-3). This function runs inside
+ * `makeController()`, and in the interactive path the bridge handler is still
+ * null there — the App attaches it later, in an effect. So `canPrompt()` is
+ * false for EVERY session at this moment, and gating registration on it would
+ * ship plan mode with no `ask_user` and no `submit_plan`, in every interactive
+ * session, with nothing anywhere reporting it.
+ *
+ * Registration is a one-time structural question ("can this channel ever reach a
+ * human?"). `canPrompt()` answers a live one ("is one attached right now?") and
+ * is checked again inside each tool, where it belongs.
+ */
+export declare function createPlanTools(opts: PlanToolsOptions): AgentTool[];