@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/exec/bridge/caller-tools.js

@@ -0,0 +1,213 @@
+/**
+ * Caller-served tools: what a `tool_register` frame becomes, and how it runs.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ## I-12: THESE TOOLS LIVE OUTSIDE THE HOST'S JURISDICTION, ON PURPOSE
+ *
+ * Everything below is built HERE and handed straight to the registry. That means a
+ * caller tool is NOT covered by the plan gate, NOT covered by a skill's
+ * `allowed-tools` ceiling, and has no job-notice tail - because it never passes
+ * through `createBuiltinTools`, which is where all three wrappers are applied.
+ *
+ * This is a decision, not an oversight, and it is written down because the next
+ * person to read this file will otherwise assume the wrappers are there. The
+ * defences that DO apply are: plan mode refuses the whole `tool_register` frame
+ * (`plan_mode_read_only`), and a caller tool may not shadow any host, team or
+ * skill tool name (`caller_tool_conflict`). Both are refusals at registration
+ * time, which is the only moment this module can still see the caller's intent.
+ *
+ * ## Why `validateCallerTools` REFUSES WHOLE FRAMES
+ *
+ * A partially accepted registration would leave the registry holding a mixture of
+ * two declarations - the caller's old `db_query` and its new `db_write` - with
+ * nothing anywhere saying which of the two the model is now using. The caller's
+ * natural recovery ("just send the fixed list again") only works if the previous
+ * frame left no trace, so every check below runs BEFORE the first write.
+ */
+import { errorResult, textResult, } from '@aragon-agent/core';
+import { truncateToBytes } from '@aragon-agent/core/skills';
+import { BRIDGE_LIMITS } from './limits.js';
+const CALLER_TOOL_NAME = /^[a-z][a-z0-9_]{0,39}$/;
+function reject(code, message) {
+    return { ok: false, code, message };
+}
+/**
+ * Narrow whatever arrived in `tool_register.tools` into usable specs.
+ *
+ * `reserved` is a PARAMETER rather than an import so the caller decides what a
+ * name may not collide with - and so the test can hand over a two-name set instead
+ * of modelling the whole host.
+ */
+export function validateCallerTools(rawTools, reserved) {
+    if (rawTools.length === 0) {
+        // THE ONE ACCEPTED DEGENERATE FRAME: an empty array is "I serve nothing now",
+        // which is a real action and the only way to withdraw a tool mid-run.
+        return { ok: true, specs: [], warnings: [] };
+    }
+    if (rawTools.length > BRIDGE_LIMITS.maxCallerTools) {
+        return reject('caller_tools_too_many', `${rawTools.length} caller tools declared; the limit is ${BRIDGE_LIMITS.maxCallerTools}.`);
+    }
+    const specs = [];
+    const warnings = [];
+    const seen = new Set();
+    for (const raw of rawTools) {
+        const one = validateOne(raw, reserved, seen);
+        if (!one.ok)
+            return one;
+        specs.push(one.spec);
+        if (one.warning)
+            warnings.push(one.warning);
+    }
+    return { ok: true, specs, warnings };
+}
+function validateOne(raw, reserved, seen) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return reject('caller_tool_bad_schema', 'Every entry in "tools" must be an object.');
+    }
+    const record = raw;
+    const name = typeof record.name === 'string' ? record.name : '';
+    if (!CALLER_TOOL_NAME.test(name)) {
+        return reject('caller_tool_bad_name', `Caller tool name "${name}" must match ${String(CALLER_TOOL_NAME)} ` +
+            `(at most ${BRIDGE_LIMITS.maxCallerToolNameChars} characters).`);
+    }
+    if (reserved.has(name) || seen.has(name)) {
+        return reject('caller_tool_conflict', `Caller tool "${name}" collides with a tool this host already registers, ` +
+            'or with an earlier entry in this same frame.');
+    }
+    seen.add(name);
+    const parameters = record.parameters;
+    if (!parameters || typeof parameters !== 'object' || Array.isArray(parameters)) {
+        return reject('caller_tool_bad_schema', `Caller tool "${name}" needs a "parameters" object.`);
+    }
+    const schema = parameters;
+    if (schema.type !== 'object') {
+        return reject('caller_tool_bad_schema', `Caller tool "${name}" needs "parameters.type" to be "object".`);
+    }
+    if (Buffer.byteLength(JSON.stringify(schema), 'utf-8') > BRIDGE_LIMITS.maxCallerToolSchemaBytes) {
+        return reject('caller_tool_bad_schema', `Caller tool "${name}" has a schema larger than ${BRIDGE_LIMITS.maxCallerToolSchemaBytes} bytes.`);
+    }
+    const descriptionRaw = typeof record.description === 'string' ? record.description : '';
+    const clipped = descriptionRaw.length > BRIDGE_LIMITS.maxCallerToolDescriptionChars;
+    const description = clipped
+        ? descriptionRaw.slice(0, BRIDGE_LIMITS.maxCallerToolDescriptionChars)
+        : descriptionRaw;
+    const label = typeof record.label === 'string' && record.label.length > 0
+        ? record.label
+        : name;
+    const timeoutMs = typeof record.timeoutMs === 'number' && Number.isFinite(record.timeoutMs)
+        ? record.timeoutMs
+        : undefined;
+    const spec = {
+        name,
+        label,
+        description,
+        parameters: schema,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    };
+    // DESCRIPTION LENGTH IS A WARNING, NOT A REFUSAL: nothing about safety depends
+    // on it, and failing the whole frame over prose would cost the caller a round
+    // trip and teach it nothing.
+    return clipped
+        ? { ok: true, spec, warning: `Caller tool "${name}": description truncated to ${description.length} characters.` }
+        : { ok: true, spec };
+}
+/**
+ * The effective ceiling for one call: `min(spec.timeoutMs, --caller-tool-timeout)`.
+ *
+ * MIN, NOT MAX, because both numbers are ceilings on the same thing: the caller's
+ * own declaration is a promise about its implementation ("this query takes at most
+ * 20 s") and the flag is the run's budget. Taking the larger of the two would let
+ * a declared 600 s override a 10 s budget.
+ */
+export function resolveCallerToolTimeout(spec, defaultTimeoutMs) {
+    const declared = spec?.timeoutMs;
+    if (declared === undefined || !Number.isFinite(declared) || declared <= 0) {
+        return Math.min(defaultTimeoutMs, BRIDGE_LIMITS.maxCallerToolTimeoutMs);
+    }
+    return Math.min(declared, defaultTimeoutMs, BRIDGE_LIMITS.maxCallerToolTimeoutMs);
+}
+/**
+ * Turn specs into `AgentTool`s that round-trip through the server.
+ *
+ * EVERY PATH RETURNS A `ToolResult`. Nothing here throws: `ToolExecutor` would
+ * convert a throw into an error result of its own wording, and that wording says
+ * nothing about which of the four refusals happened.
+ */
+export function createCallerTools(specs, server, defaultTimeoutMs) {
+    return specs.map((spec) => makeCallerTool(spec, server, defaultTimeoutMs));
+}
+function makeCallerTool(spec, server, defaultTimeoutMs) {
+    return {
+        name: spec.name,
+        label: spec.label ?? spec.name,
+        description: spec.description,
+        parameters: spec.parameters,
+        async execute(toolCallId, params, ctx) {
+            const call = {
+                callId: toolCallId,
+                turn: server.currentTurn(),
+                tool: spec.name,
+                input: (params ?? {}),
+                timeoutMs: resolveCallerToolTimeout(spec, defaultTimeoutMs),
+                agent: { id: 'lead', label: 'lead', depth: 0 },
+            };
+            return server.invokeCallerTool(call, ctx.signal);
+        },
+    };
+}
+/**
+ * Coerce a `tool_result.content` into text, or refuse it.
+ *
+ * TEXT ONLY, THIS ROUND. An image part would need `imageResult` and the provider's
+ * multimodal path, which is a separate feature with its own budget questions; a
+ * half-support that silently dropped the image would be worse than a named
+ * refusal (`bridge_unsupported_content`).
+ */
+export function contentToText(content) {
+    if (typeof content === 'string')
+        return { ok: true, text: content };
+    if (!Array.isArray(content))
+        return { ok: false };
+    const parts = [];
+    for (const part of content) {
+        if (!part || typeof part !== 'object')
+            return { ok: false };
+        const block = part;
+        if (block.type !== 'text' || typeof block.text !== 'string')
+            return { ok: false };
+        parts.push(block.text);
+    }
+    return { ok: true, text: parts.join('\n') };
+}
+/**
+ * Clip to `maxCallerToolResultBytes` and SAY SO.
+ *
+ * The footer is not decoration: `ToolExecutor` already clips model-visible output
+ * at its own ceiling, so a silent second clip here would look like the tool
+ * returned less than it did, and the model would draw conclusions from a truncated
+ * table without being told it was truncated.
+ */
+export function clipCallerToolText(text) {
+    const budget = BRIDGE_LIMITS.maxCallerToolResultBytes;
+    if (Buffer.byteLength(text, 'utf-8') <= budget)
+        return text;
+    const head = truncateToBytes(text, budget);
+    return `${head}\n[truncated at ${budget} bytes]`;
+}
+/** Build the result a `tool_result` frame becomes, or a named refusal. */
+export function callerToolResult(content, isError) {
+    const text = contentToText(content);
+    if (!text.ok) {
+        throw new UnsupportedContentError();
+    }
+    const clipped = clipCallerToolText(text.text);
+    return isError ? errorResult(clipped) : textResult(clipped);
+}
+/** Thrown only so `server.ts` can map it to one error code in one place. */
+export class UnsupportedContentError extends Error {
+    constructor() {
+        super('Caller tools support text content only (bridge_unsupported_content).');
+        this.name = 'UnsupportedContentError';
+    }
+}

package/dist/exec/bridge/decisions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The three host gates, wired to the caller instead of to an overlay.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THREE GATES, THREE DIFFERENT CONTRACTS, ONE SERVER. They are not variations of
+ * one another and cannot be collapsed:
+ *
+ *   `ToolGate`       refuses with a MODEL-VISIBLE sentence (a tool result).
+ *   `HumanInputGate` resolves `null` on cancel and NEVER rejects.
+ *   `ApprovalGate`   answers a boolean, and only ever after `canPrompt()`.
+ *
+ * The mapping from a `DecisionOutcome` to each of those is the whole content of
+ * this file, and each mapping is justified where it happens. What they share is
+ * the pending table, the ids, the deadlines and the capacity ceiling - which is
+ * exactly why one protocol was worth building instead of three.
+ *
+ * `canPrompt()` IS A LIVE PROBE EVERYWHERE. All three read `server.isOpen()` on
+ * every call and none of them caches it: the value changes the moment the caller
+ * goes away, and a cached `true` would keep a headless run waiting for an answer
+ * from a process that has already exited.
+ */
+import type { ApprovalGate } from '../../skills/service.js';
+import type { HumanInputGate } from '../../tools/human-input.js';
+import type { ToolGate } from '../../tools/tool-gate.js';
+import type { PermissionMode } from '../permission.js';
+import { type AgentScope } from './protocol.js';
+import type { BridgeServer } from './server.js';
+export interface CallerToolGateOptions {
+    server: BridgeServer;
+    /** Only `ask` gates anything; every other mode registers and runs as today. */
+    mode: PermissionMode;
+    /** `--allow-tool`: PRE-AUTHORISED names, which never produce a request. */
+    allow: ReadonlySet<string>;
+    /** Who is calling: `{id,label,depth}`, so the caller can render the right chip. */
+    scope: AgentScope;
+    /**
+     * `--decision-timeout`, carried so a timeout can name how long it waited.
+     *
+     * NOT DERIVED FROM `deadlineAt`: the outcome reports when the deadline WAS, and
+     * `Date.now()` arithmetic against it would print a number that depends on how
+     * late the timer fired rather than on the budget the caller was given.
+     */
+    decisionTimeoutMs: number;
+}
+/**
+ * The tool-approval gate.
+ *
+ * THREE SHORT CIRCUITS, IN THIS ORDER, AND EACH ONE IS A TEST (AC-14 / AC-15):
+ *
+ *   1. the tool is not in `CALLER_GATED_TOOLS`          -> allow, never ask
+ *   2. the mode is not `ask`                            -> allow, never ask
+ *   3. the name was pre-authorised or allowed this run  -> allow, never ask
+ *
+ * THE SESSION SET LIVES HERE AND NOT IN `applies()`. `applies()` answers "does
+ * this tool have a gate at all" and must stay a pure function of the name, or the
+ * identity assertions that prove "no gate means no change" become undecidable.
+ */
+export declare function createCallerToolGate(options: CallerToolGateOptions): ToolGate;
+/**
+ * `skill_install` approval.
+ *
+ * `canPrompt()` IS THE WHOLE SAFETY MECHANISM: the installer probes it before
+ * asking, and the deny-all gate exists precisely so a headless run refuses
+ * unattended installs. Here "there is a human" means "the caller's pipe is open",
+ * which is true for exactly as long as the caller is listening.
+ */
+export declare function createCallerApprovalGate(server: BridgeServer): ApprovalGate;
+/**
+ * `ask_user` / `submit_plan` over the wire.
+ *
+ * `neverPrompts` IS DELIBERATELY ABSENT. It is the STATIC "nobody can ever answer"
+ * flag that `createPlanTools` keys registration off; setting it here would
+ * unregister both tools and a caller could never review a plan, which is the
+ * feature this mode exists for. Omitting it is the correct expression, not an
+ * oversight - the type makes it optional exactly for this gate.
+ */
+export declare function createCallerHumanInputGate(server: BridgeServer): HumanInputGate;

package/dist/exec/bridge/decisions.js

@@ -0,0 +1,116 @@
+import { denialMessage, interruptedMessage, timeoutMessage } from '../../tools/tool-gate.js';
+import { CALLER_GATED_TOOLS } from '../../tools/index.js';
+import { acceptsHumanAnswer, validateHumanResponse } from './human-answers.js';
+import { humanDecisionFrame, } from './protocol.js';
+/**
+ * The tool-approval gate.
+ *
+ * THREE SHORT CIRCUITS, IN THIS ORDER, AND EACH ONE IS A TEST (AC-14 / AC-15):
+ *
+ *   1. the tool is not in `CALLER_GATED_TOOLS`          -> allow, never ask
+ *   2. the mode is not `ask`                            -> allow, never ask
+ *   3. the name was pre-authorised or allowed this run  -> allow, never ask
+ *
+ * THE SESSION SET LIVES HERE AND NOT IN `applies()`. `applies()` answers "does
+ * this tool have a gate at all" and must stay a pure function of the name, or the
+ * identity assertions that prove "no gate means no change" become undecidable.
+ */
+export function createCallerToolGate(options) {
+    const { server, mode, allow, scope } = options;
+    /** `scope:'session'` answers, in memory only; never written to config (I-7). */
+    const sessionAllow = new Set();
+    return {
+        applies: (toolName) => CALLER_GATED_TOOLS.has(toolName),
+        async decide(request) {
+            if (mode !== 'ask')
+                return { allow: true };
+            if (allow.has(request.tool) || sessionAllow.has(request.tool))
+                return { allow: true };
+            const outcome = await server.requestDecision({
+                kind: 'tool',
+                tool: {
+                    name: request.tool,
+                    callId: request.callId,
+                    input: request.input,
+                    summary: request.summary,
+                    turn: request.turn ?? server.currentTurn(),
+                },
+                agent: scope,
+            }, request.signal, (answer) => answer.decision === 'allow' || answer.decision === 'deny');
+            return verdictOf(request.tool, outcome, sessionAllow, options.decisionTimeoutMs);
+        },
+    };
+}
+/**
+ * Map an outcome onto the sentence the model reads.
+ *
+ * FOUR DISTINCT TEXTS, NEVER ONE (see `tool-gate.ts`): "denied", "nobody answered
+ * within N ms", and "the turn was interrupted" lead a model to three different
+ * next actions, and the middle one is the only case where waiting longer would
+ * have helped.
+ */
+function verdictOf(tool, outcome, sessionAllow, decisionTimeoutMs) {
+    if (outcome.outcome === 'answered') {
+        if (outcome.answer.decision === 'allow') {
+            if (outcome.answer.scope === 'session')
+                sessionAllow.add(tool);
+            return { allow: true };
+        }
+        return {
+            allow: false,
+            ...(outcome.answer.reason ? { reason: outcome.answer.reason } : {}),
+            message: denialMessage(tool, outcome.answer.reason),
+        };
+    }
+    if (outcome.outcome === 'timeout') {
+        return {
+            allow: false,
+            reason: 'decision_timeout',
+            message: timeoutMessage(tool, decisionTimeoutMs),
+        };
+    }
+    if (outcome.outcome === 'aborted') {
+        return { allow: false, reason: 'turn_aborted', message: interruptedMessage(tool) };
+    }
+    return { allow: false, reason: outcome.reason, message: interruptedMessage(tool) };
+}
+/**
+ * `skill_install` approval.
+ *
+ * `canPrompt()` IS THE WHOLE SAFETY MECHANISM: the installer probes it before
+ * asking, and the deny-all gate exists precisely so a headless run refuses
+ * unattended installs. Here "there is a human" means "the caller's pipe is open",
+ * which is true for exactly as long as the caller is listening.
+ */
+export function createCallerApprovalGate(server) {
+    return {
+        canPrompt: () => server.isOpen(),
+        request: async (req) => {
+            const outcome = await server.requestDecision({ kind: 'skill_install', install: { tool: req.tool, summary: req.summary } }, req.signal, (answer) => answer.decision === 'allow' || answer.decision === 'deny');
+            return outcome.outcome === 'answered' && outcome.answer.decision === 'allow';
+        },
+    };
+}
+/**
+ * `ask_user` / `submit_plan` over the wire.
+ *
+ * `neverPrompts` IS DELIBERATELY ABSENT. It is the STATIC "nobody can ever answer"
+ * flag that `createPlanTools` keys registration off; setting it here would
+ * unregister both tools and a caller could never review a plan, which is the
+ * feature this mode exists for. Omitting it is the correct expression, not an
+ * oversight - the type makes it optional exactly for this gate.
+ */
+export function createCallerHumanInputGate(server) {
+    return {
+        canPrompt: () => server.isOpen(),
+        request: async (req, signal) => {
+            const outcome = await server.requestDecision(humanDecisionFrame(req), signal, (answer) => acceptsHumanAnswer(req.kind, answer));
+            // THE GATE CONTRACT IS "RESOLVES null, NEVER REJECTS". Everything that is
+            // not an answer is `null` - not an empty answer, which `plan-tools` would
+            // read as "the user answered nothing and agreed".
+            if (outcome.outcome !== 'answered')
+                return null;
+            return validateHumanResponse(req, outcome.answer);
+        },
+    };
+}

package/dist/exec/bridge/human-answers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The trust boundary for answers that came off a pipe.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * EVERY FIELD BELOW IS MODEL-VISIBLE AFTER THIS FUNCTION. An `ask_user` answer
+ * becomes a `tool_result`, a `submit_plan` verdict becomes the sentence the model
+ * reasons over, and both land in the next provider request. So this is the one
+ * place where "the caller said so" has to become "the CLI asserts so", and the
+ * rules are deliberately lossy: an answer that cannot be mapped onto a question
+ * the MODEL asked is dropped rather than repaired, because a fabricated answer is
+ * worse than a missing one - it reads as a fact.
+ *
+ * V11 IS THE SUBTLE ONE. `Answer.question` is free text that this file writes; it
+ * is never accepted from the frame. Otherwise an embedder could put arbitrary
+ * words into the model's context through a field the CLI never inspects, which
+ * would make the approval channel a prompt-injection channel.
+ */
+import { type HumanRequest, type HumanResponse } from '../../tools/human-input.js';
+import type { DecisionAnswer } from './protocol.js';
+/**
+ * V1/V10: is this frame usable at all?
+ *
+ * Used as the `validate` callback on `requestDecision`, so a mangled frame is
+ * reported as `decision_resolved{outcome:'error'}` instead of being settled as a
+ * legitimate refusal. It answers only "is there an answer here", never "is the
+ * answer good" - those are different failures and the codes differ
+ * (`bridge_frame_invalid` vs a dropped option).
+ */
+export declare function acceptsHumanAnswer(kind: 'questions' | 'plan', answer: DecisionAnswer): boolean;
+/**
+ * Turn an untrusted answer into the shape `tools/human-input.ts` defines.
+ *
+ * NEVER THROWS AND NEVER REJECTS: the gate this feeds has a documented "resolves
+ * null on cancel" contract, and an exception would break it at the one moment a
+ * headless run cannot afford a stack trace.
+ */
+export declare function validateHumanResponse(req: HumanRequest, answer: DecisionAnswer): HumanResponse | null;

package/dist/exec/bridge/human-answers.js

@@ -0,0 +1,164 @@
+/**
+ * The trust boundary for answers that came off a pipe.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * EVERY FIELD BELOW IS MODEL-VISIBLE AFTER THIS FUNCTION. An `ask_user` answer
+ * becomes a `tool_result`, a `submit_plan` verdict becomes the sentence the model
+ * reasons over, and both land in the next provider request. So this is the one
+ * place where "the caller said so" has to become "the CLI asserts so", and the
+ * rules are deliberately lossy: an answer that cannot be mapped onto a question
+ * the MODEL asked is dropped rather than repaired, because a fabricated answer is
+ * worse than a missing one - it reads as a fact.
+ *
+ * V11 IS THE SUBTLE ONE. `Answer.question` is free text that this file writes; it
+ * is never accepted from the frame. Otherwise an embedder could put arbitrary
+ * words into the model's context through a field the CLI never inspects, which
+ * would make the approval channel a prompt-injection channel.
+ */
+import { QUESTION_LIMITS } from '../../tools/human-input.js';
+import { BRIDGE_LIMITS } from './limits.js';
+/** The three plan verdicts. `revise` is only meaningful with feedback. */
+const PLAN_DECISIONS = ['approved', 'revise', 'dismissed'];
+/**
+ * V1/V10: is this frame usable at all?
+ *
+ * Used as the `validate` callback on `requestDecision`, so a mangled frame is
+ * reported as `decision_resolved{outcome:'error'}` instead of being settled as a
+ * legitimate refusal. It answers only "is there an answer here", never "is the
+ * answer good" - those are different failures and the codes differ
+ * (`bridge_frame_invalid` vs a dropped option).
+ */
+export function acceptsHumanAnswer(kind, answer) {
+    if (kind === 'questions') {
+        if (answer.cancelled === true)
+            return true;
+        return Array.isArray(answer.answers);
+    }
+    return typeof answer.planDecision === 'string';
+}
+/**
+ * Turn an untrusted answer into the shape `tools/human-input.ts` defines.
+ *
+ * NEVER THROWS AND NEVER REJECTS: the gate this feeds has a documented "resolves
+ * null on cancel" contract, and an exception would break it at the one moment a
+ * headless run cannot afford a stack trace.
+ */
+export function validateHumanResponse(req, answer) {
+    return req.kind === 'questions'
+        ? validateAnswers(req.questions, answer)
+        : validatePlanDecision(answer);
+}
+function validateAnswers(questions, answer) {
+    const raw = Array.isArray(answer.answers) ? answer.answers : [];
+    const answers = [];
+    const byId = new Map(questions.map((question) => [question.id, question]));
+    /**
+     * FIRST ANSWER WINS, and a repeat is dropped like any other unmappable entry.
+     *
+     * WITHOUT THIS the caller controls the COUNT: forty copies of one question's
+     * answer render as "User answered 40 of 2 questions", because
+     * `formatAnswersResult` counts entries rather than distinct ids.
+     */
+    const used = new Set();
+    for (const entry of raw) {
+        if (answers.length >= QUESTION_LIMITS.maxQuestions)
+            break;
+        const one = validateAnswer(entry, byId);
+        if (!one || used.has(one.id))
+            continue;
+        used.add(one.id);
+        answers.push(one);
+    }
+    // A completely empty, non-cancelled answer is a FAIL-CLOSED short circuit: the
+    // wizard contract distinguishes "the user cancelled" from "the user answered
+    // nothing", and reporting the second as the first would tell the model to
+    // proceed on assumptions nobody made.
+    if (answers.length === 0 && answer.cancelled !== true) {
+        return { kind: 'answers', answers: [], cancelled: true };
+    }
+    // PARTIAL ANSWERS ARE PRESERVED WITH `cancelled` (V6): `formatAnswersResult`
+    // already renders "User answered 1 of 3" and plan-tools already tolerates it.
+    return { kind: 'answers', answers, cancelled: answer.cancelled === true };
+}
+function validateAnswer(entry, byId) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return null;
+    const record = entry;
+    // V2: an id the model never asked about is dropped, not invented.
+    const question = typeof record.id === 'string' ? byId.get(record.id) : undefined;
+    if (!question)
+        return null;
+    const selected = selectLabels(question, record.selected);
+    if (selected.length === 0)
+        return null;
+    const custom = customText(question, selected, record.custom);
+    return {
+        id: question.id,
+        // V11: THE CLI'S TEXT, not the caller's. See the module header.
+        question: question.question,
+        selected,
+        custom,
+    };
+}
+/** V3 + V4: exact labels only, and one of them unless `allowMultiple`. */
+function selectLabels(question, raw) {
+    const wanted = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : [];
+    const labels = question.options.map((option) => option.label);
+    const selected = [];
+    for (const candidate of wanted) {
+        if (typeof candidate !== 'string')
+            continue;
+        if (!labels.includes(candidate))
+            continue;
+        if (selected.includes(candidate))
+            continue;
+        selected.push(candidate);
+        if (!question.allowMultiple)
+            break;
+    }
+    return selected;
+}
+/**
+ * V5: `custom` is only meaningful when the synthetic `Other` option was picked.
+ *
+ * THE TEXT IS DROPPED, THE CHOICE IS KEPT. A free-text field attached to a fixed
+ * choice is a contradiction the wizard cannot produce, so it is a caller bug - and
+ * the safe reading of a caller bug is to keep what was clearly asked for and
+ * discard the part that was not.
+ */
+function customText(question, selected, raw) {
+    const other = question.options.find((option) => option.isOther);
+    const otherChosen = other ? selected.includes(other.label) : false;
+    const text = typeof raw === 'string' ? raw.trim() : '';
+    if (text.length === 0)
+        return null;
+    // A free-text field attached to a fixed choice is a contradiction the wizard
+    // could not have produced, so the TEXT is dropped and the choice is kept.
+    if (!otherChosen)
+        return null;
+    return text.length <= BRIDGE_LIMITS.maxCustomAnswerChars
+        ? text
+        : text.slice(0, BRIDGE_LIMITS.maxCustomAnswerChars);
+}
+/**
+ * V8 + V9: the plan verdict.
+ *
+ * `revise` WITH NO FEEDBACK IS DOWNGRADED TO `dismissed`, deliberately. The
+ * alternative - passing it through - produces a model that re-submits the same
+ * plan unchanged, so the caller pays a full research turn to see its own plan
+ * again. "Dismissed" at least ends the loop with a defensible reading.
+ */
+function validatePlanDecision(answer) {
+    const raw = answer.planDecision;
+    if (typeof raw !== 'string' || !PLAN_DECISIONS.includes(raw))
+        return null;
+    const decision = raw;
+    const feedback = typeof answer.feedback === 'string'
+        ? answer.feedback.trim().slice(0, BRIDGE_LIMITS.maxPlanFeedbackChars)
+        : '';
+    if (decision === 'revise' && feedback.length === 0) {
+        return { kind: 'planDecision', decision: 'dismissed', feedback: '' };
+    }
+    return { kind: 'planDecision', decision, feedback };
+}

package/dist/exec/bridge/limits.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Every bound the bridge protocol has, in one object (headless-host-bridge I-6).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ONE AUTHORITY, NO LITERALS ELSEWHERE. "How long may a decision wait", "how many
+ * caller tools may exist", "how many bytes may one frame be" are all answers a
+ * caller can be told (`aragon info --json`) and a validator has to enforce. Two
+ * copies of a number are two answers the moment one of them is edited, and the
+ * pair that disagrees is always discovered in the field.
+ *
+ * STRUCTURAL, NOT POLICY. These are what a protocol frame can physically carry,
+ * which is the same distinction `config/schema.ts` draws for user-tunable keys
+ * (`.claude-index/index.md`, "limits.ts is structural"). Nothing here is
+ * persisted and nothing here is settable from `config.json`: the two timeouts
+ * have flags because they are per-invocation budgets, and every other number is
+ * a property of the wire format.
+ */
+export declare const BRIDGE_LIMITS: {
+    /** One NDJSON frame. A larger line is skipped, never fatal. */
+    readonly maxFrameBytes: 1048576;
+    /** Declared caller tools in one `tool_register` frame. */
+    readonly maxCallerTools: 32;
+    readonly maxCallerToolNameChars: 40;
+    readonly maxCallerToolSchemaBytes: 16384;
+    readonly maxCallerToolDescriptionChars: 1024;
+    /** Mirrors Core's `ToolExecutor` default `maxOutputSize` (executor.ts:42). */
+    readonly maxCallerToolResultBytes: 100000;
+    /** Concurrent in-flight caller tools. Over the cap, the call is refused. */
+    readonly maxOutstandingCallerTools: 8;
+    /** Concurrent unanswered decisions, lead plus every subagent. */
+    readonly maxOutstandingDecisions: 8;
+    /**
+     * Recently settled request ids remembered so a REPEATED answer can be answered
+     * as `bridge_duplicate_response` instead of `bridge_unknown_request`.
+     *
+     * The design dropped the 512-entry decision ledger (review P2-7) on the grounds
+     * that the pending table's settle-once already covered duplicate detection. That
+     * is true only while the entry is still IN the table: this table removes an
+     * entry the moment it settles, so without a small ring the very first repeat
+     * would be reported as an unknown request - a different code, and a misleading
+     * one, for a caller that answered twice. The ring has exactly one consumer (the
+     * duplicate branch in `pending.ts`), which is the condition P2-7 set for keeping
+     * any such state at all.
+     */
+    readonly maxSettledIds: 256;
+    /** Default and hard ceiling for one decision's deadline. */
+    readonly defaultDecisionTimeoutMs: 300000;
+    readonly maxDecisionTimeoutMs: 1800000;
+    /** Caller tool timeouts: the flag's default, and its hard ceiling. */
+    readonly defaultCallerToolTimeoutMs: 60000;
+    readonly maxCallerToolTimeoutMs: 600000;
+    /**
+     * Strings the caller supplies that end up in front of the model.
+     *
+     * BOUNDED BECAUSE THEY ARE MODEL-VISIBLE, not because they are expensive: a
+     * denial reason and plan feedback both reach the transcript, so an unbounded
+     * one is an unbounded line in every subsequent provider request.
+     */
+    readonly maxDenyReasonChars: 500;
+    readonly maxPlanFeedbackChars: 2000;
+    readonly maxCustomAnswerChars: 2000;
+    /** `tool_invoke.input` is echoed back so the caller can act on it. */
+    readonly maxInvokeInputChars: 16384;
+    /** stdout backpressure watermarks. See `writer.ts`. */
+    readonly softPendingBytes: 4194304;
+    readonly hardPendingBytes: 16777216;
+};