@aragon-agent/cli 0.6.37 → 0.6.39

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

@@ -0,0 +1,142 @@
+/**
+ * The bridge server: one multiplexer for both directions of the channel.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * WHAT IT OWNS
+ *
+ *   - the pending table (ids, deadlines, settle-once, cancellation),
+ *   - the outbound frames that are NOT exec events (`decision_request`,
+ *     `tool_invoke`, `tool_cancel`, `ack`, `pong`),
+ *   - the caller-tool registry (validation and the turn-boundary write),
+ *   - the open/closed state every gate reads as `isOpen()`.
+ *
+ * WHAT IT DOES NOT OWN. It never prompts the model, never advances a turn and
+ * never writes `result`: the runner does the first two, `exec/index.ts` the third.
+ * The consequence worth stating is that `close()` can be called from any exit path
+ * without any of those owners being consulted.
+ *
+ * THE ONE ASYMMETRY THAT MATTERS. `requestDecision` resolves; it never rejects and
+ * never throws, even for a frame that arrived mangled. A gate is therefore allowed
+ * to `await` it without a `try`, and the fail-closed answer for anything untrusted
+ * is the same one for a timeout: "not allowed", with the reason written where the
+ * model cannot see it and the caller can.
+ */
+import { type ToolResult } from '@aragon-agent/core';
+import { type AgentScope, type BridgeInputFrame, type CallerToolCall, type CallerToolSpec, type DecisionAnswer, type DecisionAsk, type DecisionKind, type DecisionOutcome } from './protocol.js';
+import type { BridgeWriter } from './writer.js';
+/** What the host must provide for the frames that change host state. */
+export interface BridgeServerPorts {
+    /** Replace the caller-served tool set. ONLY called at a turn boundary. */
+    applyCallerTools: (tools: CallerToolSpec[]) => void;
+    /** True while `agent.state.isRunning` - registration must wait. */
+    isTurnActive: () => boolean;
+    /** The names the registry holds RIGHT NOW (the host's view of the union). */
+    callerToolNames: () => string[];
+    /** `'plan'` refuses `tool_register` outright. */
+    getAgentMode: () => 'build' | 'plan';
+}
+export interface BridgeTurnPorts {
+    /** `steer` frame: enqueue guidance, or refuse when the agent is idle. */
+    steer: (text: string, id: string | undefined) => void;
+    /** `interrupt` frame: cancel a queued turn, or abort the one in flight. */
+    interrupt: (requestId: string | undefined, id: string | undefined) => void;
+    /**
+     * `cancel_request` frame: stop ONE request and keep the process serving.
+     *
+     * The same two arguments as `interrupt` on purpose - the frame shapes are identical
+     * and the meaning is what differs - so an implementer cannot accidentally wire one
+     * into the other's slot without the types noticing.
+     */
+    cancelRequest: (requestId: string | undefined, id: string | undefined) => void;
+}
+export interface BridgeAuditRecord {
+    requestId: string;
+    kind: DecisionKind | 'caller_tool' | 'hook';
+    outcome: string;
+    tool?: string;
+    reason?: string;
+}
+/**
+ * The lifecycle-hook channel, as the server sees it
+ * (headless-threads-and-lifecycle-hooks section 2.4.2).
+ *
+ * WHY THE SERVER AND NOT THE SOURCE: `bridge/source.ts` routes every non-turn frame to
+ * `server.handleFrame` and is on this round's UNTOUCHED list, so the two hook frames have
+ * to be understood here. The server owns no hook state - it validates nothing, times
+ * nothing out and writes nothing on its own - which is what keeps this a two-case
+ * addition rather than a second dispatcher.
+ */
+export interface BridgeHookPorts {
+    /** `hook_register`: answer with the ids that are now live, or a refusal. */
+    register: (frame: Extract<BridgeInputFrame, {
+        type: 'hook_register';
+    }>) => void;
+    /**
+     * `hook_answer`: `true` when it named a live request. The port writes the ack itself
+     * when it returns `false`, because only it knows which code applies
+     * (`hook_not_registered`) and whether the frame even belongs to this channel.
+     */
+    answer: (frame: Extract<BridgeInputFrame, {
+        type: 'hook_answer';
+    }>) => boolean;
+}
+export interface BridgeServerOptions {
+    writer: BridgeWriter;
+    sessionId: string;
+    now?: () => number;
+    decisionTimeoutMs: number;
+    callerToolTimeoutMs: number;
+    ports: BridgeServerPorts;
+    /** Names a caller tool may not shadow. Defaults to host + subagent tool names. */
+    reservedToolNames?: ReadonlySet<string>;
+    /**
+     * The one structured audit line per decision (headless-host-bridge section 2.5).
+     *
+     * A CALLBACK RATHER THAN A LOGGER IMPORT, so this module stays testable without
+     * process state and so `exec/index.ts` remains the only place that decides what
+     * "logged" means.
+     */
+    onAudit?: (record: BridgeAuditRecord) => void;
+    /** A non-fatal protocol problem, for the same reason. */
+    onProtocolError?: (code: string, message: string) => void;
+    /**
+     * The hook channel, present only when this server is the `hook_register` destination
+     * (bridge mode; every thread's own server in thread mode).
+     *
+     * ABSENT MEANS THE FRAMES ARE REFUSED, not ignored: a caller that sent `hook_register` to
+     * a run without the channel must be told (`hook_requires_bridge`), because silence reads
+     * as "registered" and the next symptom is a redactor that never fires.
+     */
+    hookPorts?: BridgeHookPorts;
+}
+export interface BridgeServer {
+    isOpen(): boolean;
+    /** Resolves with a discriminated outcome; NEVER rejects. */
+    requestDecision(ask: DecisionAsk, signal?: AbortSignal, validate?: (answer: DecisionAnswer) => boolean): Promise<DecisionOutcome>;
+    invokeCallerTool(call: CallerToolCall, signal?: AbortSignal): Promise<ToolResult>;
+    /** Route one control frame. Turn frames are the source's business. */
+    handleFrame(frame: BridgeInputFrame): void;
+    /** Soft-limit backpressure, awaited at turn boundaries only. */
+    drainIfNeeded(): Promise<void>;
+    /** Settle everything, flush, and refuse all later frames. */
+    close(reason: 'run_finished' | 'caller_eof' | 'hard_limit'): Promise<void>;
+    /** Settle every unanswered decision as `aborted`; used on interrupt and EOF. */
+    abortInFlight(): void;
+    /** Names currently registered, for `ack.tools` and `info`. */
+    callerToolNames(): string[];
+    /** Write one outbound frame through the sealed writer. */
+    write(event: Record<string, unknown>): void;
+    /**
+     * Called by the runner as a turn begins: records the turn number and flushes a
+     * deferred `tool_register`. THE ONLY PLACE THE REGISTRY IS WRITTEN, which is what
+     * makes I-8 a structural fact rather than a promise.
+     */
+    beginTurn(turn: number): void;
+    currentTurn(): number;
+    /** Installed by `runner.attachBridge`; before that the frames are refused. */
+    attachTurnPorts(ports: BridgeTurnPorts): void;
+}
+export declare function createBridgeServer(options: BridgeServerOptions): BridgeServer;
+/** Re-exported so `decisions.ts` and the tests read one name. */
+export type { AgentScope };

package/dist/exec/bridge/server.js

@@ -0,0 +1,502 @@
+/**
+ * The bridge server: one multiplexer for both directions of the channel.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * WHAT IT OWNS
+ *
+ *   - the pending table (ids, deadlines, settle-once, cancellation),
+ *   - the outbound frames that are NOT exec events (`decision_request`,
+ *     `tool_invoke`, `tool_cancel`, `ack`, `pong`),
+ *   - the caller-tool registry (validation and the turn-boundary write),
+ *   - the open/closed state every gate reads as `isOpen()`.
+ *
+ * WHAT IT DOES NOT OWN. It never prompts the model, never advances a turn and
+ * never writes `result`: the runner does the first two, `exec/index.ts` the third.
+ * The consequence worth stating is that `close()` can be called from any exit path
+ * without any of those owners being consulted.
+ *
+ * THE ONE ASYMMETRY THAT MATTERS. `requestDecision` resolves; it never rejects and
+ * never throws, even for a frame that arrived mangled. A gate is therefore allowed
+ * to `await` it without a `try`, and the fail-closed answer for anything untrusted
+ * is the same one for a timeout: "not allowed", with the reason written where the
+ * model cannot see it and the caller can.
+ */
+import { errorResult } from '@aragon-agent/core';
+import { HOST_TOOL_NAMES } from '../../tools/index.js';
+import { TEAM_SUBAGENT_TOOL_NAMES } from '../../team/limits.js';
+import { BRIDGE_LIMITS } from './limits.js';
+import { createPendingTable } from './pending.js';
+import { LEAD_SCOPE, } from './protocol.js';
+import { UnsupportedContentError, callerToolResult, validateCallerTools, } from './caller-tools.js';
+export function createBridgeServer(options) {
+    const now = options.now ?? Date.now;
+    const sessionId = options.sessionId;
+    const writer = options.writer;
+    const pending = createPendingTable({ now });
+    const reserved = options.reservedToolNames ??
+        new Set([...HOST_TOOL_NAMES, ...TEAM_SUBAGENT_TOOL_NAMES]);
+    let open = true;
+    let turn = 0;
+    let turnPorts = null;
+    /** A validated set waiting for the next turn boundary (I-8). */
+    let deferredSpecs = null;
+    const write = (event) => writer.write(event);
+    const protocolError = (code, message) => {
+        write({ type: 'error', sessionId, fatal: false, code, message });
+        options.onProtocolError?.(code, message);
+    };
+    const audit = (record) => {
+        options.onAudit?.(record);
+    };
+    const isTurnActive = () => options.ports.isTurnActive();
+    const register = (specs, id) => {
+        const names = specs.map((spec) => spec.name);
+        if (isTurnActive()) {
+            // DEFERRED, AND THE ACK SAYS SO. Writing the live registry mid-turn is the
+            // hazard `submit_plan` already taught this codebase once: the engine is
+            // iterating it. `appliedAtTurn` is the promise that it will be there for the
+            // next request.
+            deferredSpecs = specs;
+            write({
+                type: 'ack',
+                ...(id ? { id } : {}),
+                accepted: true,
+                scope: 'lead',
+                tools: names,
+                appliedAtTurn: turn + 1,
+            });
+            return;
+        }
+        options.ports.applyCallerTools(specs);
+        write({
+            type: 'ack',
+            ...(id ? { id } : {}),
+            // `turn + 1` IN BOTH BRANCHES, so the field means one thing: "the earliest
+            // turn whose LLM request can see these tools". Before the first turn that is
+            // turn 1 (not 0, which reads as "a turn that never happened"), between turns
+            // it is the next one, and mid-turn it is the one after the current.
+            accepted: true,
+            scope: 'lead',
+            tools: names,
+            appliedAtTurn: turn + 1,
+        });
+    };
+    const handleToolRegister = (frame) => {
+        if (options.ports.getAgentMode() === 'plan') {
+            // WHOLE-FRAME REFUSAL, not "register and refuse at call time": plan mode's
+            // promise is read-only, and a caller tool's side effects are unknown to this
+            // process. Registering one would open an arbitrary hole in that promise.
+            write({
+                type: 'ack',
+                ...(frame.id ? { id: frame.id } : {}),
+                accepted: false,
+                code: 'plan_mode_read_only',
+                message: 'Plan mode refuses caller tools; send this frame again in build mode.',
+            });
+            return;
+        }
+        const validated = validateCallerTools(frame.tools, reserved);
+        if (!validated.ok) {
+            write({
+                type: 'ack',
+                ...(frame.id ? { id: frame.id } : {}),
+                accepted: false,
+                code: validated.code,
+                message: validated.message,
+            });
+            return;
+        }
+        register(validated.specs, frame.id);
+        if (validated.warnings.length > 0) {
+            write({
+                type: 'ack',
+                ...(frame.id ? { id: frame.id } : {}),
+                accepted: true,
+                scope: 'lead',
+                tools: validated.specs.map((spec) => spec.name),
+                warnings: validated.warnings,
+            });
+        }
+    };
+    const handleDecisionFrame = (frame) => {
+        const kind = pending.kindOf(frame.respondsTo);
+        if (kind === undefined) {
+            reportMissing(frame.respondsTo);
+            return;
+        }
+        if (kind !== 'decision') {
+            // THE OTHER TABLE'S QUESTION. Answering it here would settle a `tool_invoke`
+            // with a decision payload, so the entry must survive (AC-55).
+            protocolError('bridge_kind_mismatch', `"${frame.respondsTo}" awaits a caller tool result, not a decision.`);
+            return;
+        }
+        reportAnswer(frame.respondsTo, 'decision', frame);
+    };
+    const handleToolResultFrame = (frame) => {
+        const kind = pending.kindOf(frame.respondsTo);
+        if (kind === undefined) {
+            reportMissing(frame.respondsTo);
+            return;
+        }
+        if (kind !== 'caller_tool') {
+            protocolError('bridge_kind_mismatch', `"${frame.respondsTo}" awaits a decision, not a caller tool result.`);
+            return;
+        }
+        reportAnswer(frame.respondsTo, 'caller_tool', {
+            content: frame.content,
+            isError: frame.isError === true,
+        });
+    };
+    /**
+     * An answer that matched no live entry is ONE OF TWO THINGS, and the codes
+     * differ (section 2.3.8 rows 4 and 5): answered twice, or answered too late /
+     * never asked. The pending table remembers only the first kind, which is why it
+     * has to be asked rather than assumed.
+     */
+    const reportMissing = (requestId) => {
+        if (pending.wasAnswered(requestId)) {
+            protocolError('bridge_duplicate_response', `"${requestId}" was already answered.`);
+            return;
+        }
+        protocolError('bridge_unknown_request', `"${requestId}" is not an outstanding request.`);
+    };
+    const reportAnswer = (requestId, kind, value) => {
+        // A live entry of the WRONG kind never reaches here: the two frame handlers
+        // reject it above and leave the entry pending (AC-55).
+        if (pending.answer(requestId, kind, value) === 'ok')
+            return;
+        reportMissing(requestId);
+    };
+    const decisionFrame = (requestId, ask, createdAt, deadlineAt) => {
+        return {
+            type: 'decision_request',
+            requestId,
+            sessionId,
+            kind: ask.kind,
+            createdAt,
+            deadlineAt,
+            timeoutMs: options.decisionTimeoutMs,
+            ...(ask.kind === 'tool' ? { tool: { ...ask.tool, turn: ask.tool.turn || turn } } : {}),
+            ...(ask.kind === 'questions' ? { questions: ask.questions } : {}),
+            ...(ask.kind === 'plan' ? { plan: ask.plan } : {}),
+            ...(ask.kind === 'skill_install' ? { install: ask.install } : {}),
+            agent: ask.agent ?? LEAD_SCOPE,
+        };
+    };
+    return {
+        isOpen: () => open,
+        write,
+        beginTurn(nextTurn) {
+            turn = nextTurn;
+            if (!deferredSpecs)
+                return;
+            const specs = deferredSpecs;
+            deferredSpecs = null;
+            options.ports.applyCallerTools(specs);
+        },
+        currentTurn: () => turn,
+        attachTurnPorts(ports) {
+            turnPorts = ports;
+        },
+        callerToolNames() {
+            // A DEFERRED SET IS THE HONEST ANSWER: it is what the model will be able to
+            // call from the next turn, and `ack.appliedAtTurn` already told the caller
+            // when. Reporting the older names would make the ack contradict itself.
+            const deferred = deferredSpecs;
+            return deferred ? deferred.map((spec) => spec.name) : options.ports.callerToolNames();
+        },
+        async requestDecision(ask, signal, validate) {
+            if (!open)
+                return { outcome: 'closed', reason: 'server_closed' };
+            const handle = pending.create({
+                kind: 'decision',
+                timeoutMs: options.decisionTimeoutMs,
+                ...(signal ? { signal } : {}),
+                meta: {
+                    ...(ask.kind === 'tool' ? { tool: ask.tool.name, callId: ask.tool.callId } : {}),
+                    ...(ask.agent ? { agent: ask.agent } : {}),
+                },
+            });
+            if (!handle) {
+                // IMMEDIATE REFUSAL, NOT A QUEUE. Queueing would make a three-way fan-out
+                // look frozen; refusing is explainable and the model can route around it.
+                protocolError('bridge_decision_capacity', `More than ${BRIDGE_LIMITS.maxOutstandingDecisions} decisions are awaiting an answer.`);
+                audit({ requestId: '-', kind: ask.kind, outcome: 'deny', reason: 'decision_capacity' });
+                return { outcome: 'answered', answer: { decision: 'deny', reason: 'decision_capacity' } };
+            }
+            write(decisionFrame(handle.requestId, ask, handle.createdAt, handle.deadlineAt));
+            const settled = await handle.settled;
+            const answer = settled.outcome === 'settled'
+                ? clipAnswerReason(settled.value)
+                : undefined;
+            const rejected = answer !== undefined && validate !== undefined && !validate(answer);
+            const outcome = resolvedOutcome(settled.outcome, answer, rejected);
+            write({
+                type: 'decision_resolved',
+                requestId: handle.requestId,
+                sessionId,
+                kind: ask.kind,
+                outcome,
+                ...(answer?.scope ? { scope: answer.scope } : {}),
+                ...(answer?.reason && outcome === 'deny' ? { reason: clipReason(answer.reason) } : {}),
+            });
+            if (rejected) {
+                protocolError('bridge_frame_invalid', `The answer to "${handle.requestId}" was not a valid ${ask.kind} decision.`);
+            }
+            audit({
+                requestId: handle.requestId,
+                kind: ask.kind,
+                outcome,
+                ...(ask.kind === 'tool' ? { tool: ask.tool.name } : {}),
+                ...(answer?.reason ? { reason: clipReason(answer.reason) } : {}),
+            });
+            if (settled.outcome === 'settled') {
+                return { outcome: 'answered', answer: answer ?? {} };
+            }
+            if (settled.outcome === 'timeout') {
+                return { outcome: 'timeout', deadlineAt: settled.deadlineAt };
+            }
+            if (settled.outcome === 'aborted')
+                return { outcome: 'aborted' };
+            return { outcome: 'closed', reason: settled.reason };
+        },
+        async invokeCallerTool(call, signal) {
+            if (!open)
+                return errorResult('The caller channel is closed; this tool was not run.');
+            const handle = pending.create({
+                kind: 'caller_tool',
+                timeoutMs: call.timeoutMs,
+                ...(signal ? { signal } : {}),
+                meta: { tool: call.tool, callId: call.callId, agent: call.agent },
+            });
+            if (!handle) {
+                protocolError('bridge_caller_capacity', `More than ${BRIDGE_LIMITS.maxOutstandingCallerTools} caller tool calls are in flight.`);
+                return errorResult(`Caller tool "${call.tool}" was not run: too many caller tool calls are in flight.`);
+            }
+            write({
+                type: 'tool_invoke',
+                requestId: handle.requestId,
+                sessionId,
+                callId: call.callId,
+                turn: call.turn,
+                tool: call.tool,
+                input: truncateInput(call.input),
+                timeoutMs: call.timeoutMs,
+                deadlineAt: handle.deadlineAt,
+                agent: call.agent,
+            });
+            const settled = await handle.settled;
+            if (settled.outcome === 'settled') {
+                const built = buildCallerToolResult(call, settled.value, protocolError);
+                return built;
+            }
+            if (settled.outcome === 'timeout') {
+                write({
+                    type: 'tool_cancel',
+                    requestId: handle.requestId,
+                    sessionId,
+                    reason: 'timeout',
+                });
+                protocolError('caller_tool_timeout', `Caller tool "${call.tool}" did not answer within ${call.timeoutMs} ms.`);
+                return errorResult(`Caller tool "${call.tool}" did not answer within ${call.timeoutMs} ms.`);
+            }
+            if (settled.outcome === 'aborted') {
+                // MANDATORY, NOT DEFENSIVE: an unsettled caller tool is a `tool_use` with
+                // no `tool_result`, and the next provider request is an HTTP 400.
+                write({
+                    type: 'tool_cancel',
+                    requestId: handle.requestId,
+                    sessionId,
+                    reason: 'turn_aborted',
+                });
+                return errorResult(`Caller tool "${call.tool}" was cancelled: the turn was interrupted.`);
+            }
+            return errorResult(`Caller tool "${call.tool}" was cancelled: the caller channel closed.`);
+        },
+        handleFrame(frame) {
+            if (!open)
+                return;
+            switch (frame.type) {
+                case 'decision':
+                    handleDecisionFrame(frame);
+                    return;
+                case 'tool_result':
+                    handleToolResultFrame(frame);
+                    return;
+                case 'tool_register':
+                    handleToolRegister(frame);
+                    return;
+                case 'ping':
+                    write({ type: 'pong', ...(frame.id ? { id: frame.id } : {}), now: now() });
+                    return;
+                case 'steer':
+                    if (turnPorts)
+                        turnPorts.steer(frame.text, frame.id);
+                    else {
+                        write({
+                            type: 'ack',
+                            ...(frame.id ? { id: frame.id } : {}),
+                            accepted: false,
+                            code: 'not_running',
+                        });
+                    }
+                    return;
+                case 'interrupt':
+                    if (turnPorts)
+                        turnPorts.interrupt(frame.requestId, frame.id);
+                    return;
+                case 'cancel_request':
+                    // NO FALLBACK `ack` WHEN THE PORTS ARE MISSING, unlike `steer`: a frame that
+                    // arrives before `runner.attachBridge` names a request that cannot be in
+                    // flight yet, and inventing a refusal for it would be a lie about a state
+                    // that does not exist. The requester re-sends or times out - the same
+                    // contract `interrupt` already has.
+                    if (turnPorts)
+                        turnPorts.cancelRequest(frame.requestId, frame.id);
+                    return;
+                // THE THREE THREAD FRAMES, REFUSED WHERE THEY CANNOT BE ROUTED (AC-2).
+                //
+                // In thread mode they never reach this switch: `dispatch-source.ts` routes
+                // `thread_open`/`thread_close`/`thread_list` to the registry, which owns the state
+                // machine. So a thread frame arriving HERE means this run did not open `--threads`,
+                // and the answer must be a receipt rather than the `default` branch's silence - a
+                // wrapper that believed it had opened a thread would send prompts into `main` and
+                // receive answers to a conversation it never asked for.
+                case 'thread_open':
+                case 'thread_close':
+                case 'thread_list':
+                    write({
+                        type: 'ack',
+                        ...(frame.id ? { id: frame.id } : {}),
+                        accepted: false,
+                        code: 'threads_disabled',
+                        message: 'Threads are not enabled; start the run with --threads.',
+                    });
+                    return;
+                case 'hook_register':
+                    if (!options.hookPorts) {
+                        write({
+                            type: 'ack',
+                            ...(frame.id ? { id: frame.id } : {}),
+                            accepted: false,
+                            code: 'hook_requires_bridge',
+                            message: 'Lifecycle hooks need --input-format bridge; this run has no hook channel.',
+                        });
+                        return;
+                    }
+                    options.hookPorts.register(frame);
+                    return;
+                case 'hook_answer':
+                    if (!options.hookPorts) {
+                        write({
+                            type: 'ack',
+                            ...(frame.id ? { id: frame.id } : {}),
+                            accepted: false,
+                            code: 'hook_requires_bridge',
+                            message: 'Lifecycle hooks need --input-format bridge; this run has no hook channel.',
+                        });
+                        return;
+                    }
+                    // THE ANSWER IS NOT ACKED ON SUCCESS. `hook_answer` is an answer to an answer:
+                    // the fact the caller needs is `hook_resolved`, which the dispatcher writes for
+                    // the exact id. A second ack would be a third frame saying the same thing.
+                    if (!options.hookPorts.answer(frame)) {
+                        write({
+                            type: 'ack',
+                            ...(frame.id ? { id: frame.id } : {}),
+                            accepted: false,
+                            code: 'hook_not_registered',
+                            message: `"${frame.respondsTo}" is not an outstanding hook request.`,
+                        });
+                    }
+                    return;
+                default:
+                    // `prompt` / `user` / `end` belong to the source; an unknown type is
+                    // ignored by the parser long before it reaches this switch.
+                    return;
+            }
+        },
+        async drainIfNeeded() {
+            await writer.drainIfNeeded();
+        },
+        abortInFlight() {
+            // NO `tool_cancel` IS WRITTEN HERE, DELIBERATELY. Every in-flight caller
+            // tool is awaiting its own `handle.settled`, and that continuation already
+            // writes exactly one `tool_cancel{turn_aborted}` when it observes `aborted`
+            // (see `invokeCallerTool`). Emitting one here as well would put the same
+            // frame on the wire twice for one requestId, and a caller that tracks
+            // outstanding calls by id would count it twice.
+            pending.abortAll();
+        },
+        async close(reason) {
+            if (!open)
+                return;
+            open = false;
+            pending.closeAll(reason);
+            await writer.flush();
+        },
+    };
+}
+/** `allow` / `deny` / `error` for a settled decision; the frame's own outcome otherwise. */
+function resolvedOutcome(settled, answer, rejected) {
+    if (settled === 'timeout')
+        return 'timeout';
+    if (settled === 'aborted')
+        return 'aborted';
+    if (settled === 'closed')
+        return 'aborted';
+    if (rejected)
+        return 'error';
+    return answer?.decision === 'deny' ? 'deny' : 'allow';
+}
+/**
+ * Bound the one caller-supplied string that becomes MODEL-VISIBLE.
+ *
+ * `denialMessage` puts the reason into a `tool_result`, so `maxDenyReasonChars`
+ * has to be applied HERE - where the answer enters the CLI - rather than only on
+ * the echoed frame and the audit line. Otherwise a megabyte of "reason" would
+ * ride into every later provider request, which is exactly the unbounded
+ * prompt-injection lane the limit exists to close.
+ */
+function clipAnswerReason(answer) {
+    const reason = answer.reason;
+    if (typeof reason !== 'string')
+        return answer;
+    const clipped = clipReason(reason);
+    return clipped === reason ? answer : { ...answer, reason: clipped };
+}
+function clipReason(reason) {
+    return reason.length <= BRIDGE_LIMITS.maxDenyReasonChars
+        ? reason
+        : reason.slice(0, BRIDGE_LIMITS.maxDenyReasonChars);
+}
+/**
+ * Bound the echoed `input`. The caller needs it to act, so it travels - but a
+ * megabyte of SQL does not need to travel four times (invoke, event, result, log).
+ */
+function truncateInput(input) {
+    const serialized = JSON.stringify(input ?? {});
+    if (serialized.length <= BRIDGE_LIMITS.maxInvokeInputChars)
+        return input ?? {};
+    return { truncated: true, preview: serialized.slice(0, BRIDGE_LIMITS.maxInvokeInputChars) };
+}
+/**
+ * The `tool_result` payload as an `AgentTool` result.
+ *
+ * TWO FAILURE SHAPES, BOTH NAMED: content this build cannot accept (an `image`
+ * part, refused rather than silently dropped) and the caller's own `isError`. A
+ * third possibility - an exception escaping - would be converted by
+ * `ToolExecutor` into wording that says nothing about which of the two happened.
+ */
+function buildCallerToolResult(call, value, protocolError) {
+    try {
+        return callerToolResult(value.content, value.isError === true);
+    }
+    catch (e) {
+        if (!(e instanceof UnsupportedContentError))
+            throw e;
+        protocolError('bridge_unsupported_content', `Caller tool "${call.tool}": ${e.message}`);
+        return errorResult(`Caller tool "${call.tool}" returned content this build cannot accept: ${e.message}`);
+    }
+}