@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/exec/bridge/limits.js

@@ -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 const BRIDGE_LIMITS = {
+    /** One NDJSON frame. A larger line is skipped, never fatal. */
+    maxFrameBytes: 1_048_576,
+    /** Declared caller tools in one `tool_register` frame. */
+    maxCallerTools: 32,
+    maxCallerToolNameChars: 40,
+    maxCallerToolSchemaBytes: 16_384,
+    maxCallerToolDescriptionChars: 1_024,
+    /** Mirrors Core's `ToolExecutor` default `maxOutputSize` (executor.ts:42). */
+    maxCallerToolResultBytes: 100_000,
+    /** Concurrent in-flight caller tools. Over the cap, the call is refused. */
+    maxOutstandingCallerTools: 8,
+    /** Concurrent unanswered decisions, lead plus every subagent. */
+    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.
+     */
+    maxSettledIds: 256,
+    /** Default and hard ceiling for one decision's deadline. */
+    defaultDecisionTimeoutMs: 300_000,
+    maxDecisionTimeoutMs: 1_800_000,
+    /** Caller tool timeouts: the flag's default, and its hard ceiling. */
+    defaultCallerToolTimeoutMs: 60_000,
+    maxCallerToolTimeoutMs: 600_000,
+    /**
+     * 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.
+     */
+    maxDenyReasonChars: 500,
+    maxPlanFeedbackChars: 2_000,
+    maxCustomAnswerChars: 2_000,
+    /** `tool_invoke.input` is echoed back so the caller can act on it. */
+    maxInvokeInputChars: 16_384,
+    /** stdout backpressure watermarks. See `writer.ts`. */
+    softPendingBytes: 4_194_304,
+    hardPendingBytes: 16_777_216,
+};

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

@@ -0,0 +1,17 @@
+export interface NdjsonSplitterOptions {
+    /**
+     * Structural ceiling for one frame. `BRIDGE_LIMITS.maxFrameBytes` unless a
+     * caller is deliberately testing the boundary with a smaller one.
+     */
+    maxFrameBytes?: number;
+    /** One complete line, terminator removed. Never called for an empty line. */
+    onLine: (line: string) => void;
+    /** A line was dropped for exceeding the ceiling. */
+    onTooLarge?: (bytes: number) => void;
+}
+export interface NdjsonSplitter {
+    push(chunk: string | Buffer): void;
+    /** Deliver a final line that arrived without a trailing newline. */
+    end(): void;
+}
+export declare function createNdjsonSplitter(options: NdjsonSplitterOptions): NdjsonSplitter;

package/dist/exec/bridge/ndjson.js

@@ -0,0 +1,83 @@
+/**
+ * NDJSON line splitting, shared by `--input-format stream-json` and `bridge`.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE, AND EXTRACTED RATHER THAN COPIED. Both input formats read newline-delimited
+ * JSON off stdin and both must treat a bad line as non-fatal; a second copy of the
+ * splitting loop would be a second place for the `\r` rule below to be forgotten.
+ *
+ * THE `\r` RULE IS NOT A HYPOTHETICAL. This project ships Windows-first, and a
+ * caller on Windows that writes `JSON + "\r\n"` puts a carriage return at the end
+ * of every line. `JSON.parse` tolerates it, but the string we hand to a
+ * `content` field would then carry a stray `\r`, which reaches the model as part
+ * of a tool result. So the terminator is trimmed BEFORE the byte count and BEFORE
+ * parsing, in that order: counting the raw line first would reject a frame that is
+ * exactly at the cap only because of a line ending nobody meant to send.
+ */
+import { BRIDGE_LIMITS } from './limits.js';
+export function createNdjsonSplitter(options) {
+    const maxBytes = options.maxFrameBytes ?? BRIDGE_LIMITS.maxFrameBytes;
+    let buffer = '';
+    /**
+     * `true` while discarding the tail of an over-long line.
+     *
+     * WITHOUT THIS the reader would buffer an unbounded amount of memory waiting for
+     * a newline that may never come - a caller that never sends one (a corrupted
+     * pipe, a writer stuck mid-frame) would exhaust the process instead of costing
+     * one skipped frame.
+     */
+    let discarding = false;
+    const deliver = (raw) => {
+        if (discarding) {
+            discarding = false;
+            return;
+        }
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.trim().length === 0)
+            return;
+        const bytes = Buffer.byteLength(line, 'utf-8');
+        if (bytes > maxBytes) {
+            options.onTooLarge?.(bytes);
+            return;
+        }
+        options.onLine(line);
+    };
+    return {
+        push(chunk) {
+            buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+            for (;;) {
+                const index = buffer.indexOf('\n');
+                if (index < 0) {
+                    // No terminator yet. An over-long partial line is dropped NOW rather
+                    // than kept until one arrives; see `discarding`.
+                    //
+                    // ALREADY DISCARDING MEANS RETAIN NOTHING, not merely "do not report
+                    // again": the flag only exists so the caller is told once, and keeping
+                    // the tail would reintroduce the unbounded growth this branch was
+                    // written to prevent - a caller that streams 100 MiB with no newline
+                    // would still hold all of it.
+                    if (discarding) {
+                        buffer = '';
+                        return;
+                    }
+                    const bytes = Buffer.byteLength(buffer, 'utf-8');
+                    if (bytes > maxBytes) {
+                        options.onTooLarge?.(bytes);
+                        buffer = '';
+                        discarding = true;
+                    }
+                    return;
+                }
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                deliver(line);
+            }
+        },
+        end() {
+            if (buffer.length > 0)
+                deliver(buffer);
+            buffer = '';
+        },
+    };
+}

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

@@ -0,0 +1,70 @@
+import type { AgentScope, PendingKindValue } from './protocol.js';
+export type PendingKind = PendingKindValue;
+export interface PendingMeta {
+    tool?: string;
+    callId?: string;
+    agent?: AgentScope;
+}
+/** What an entry resolves with. Never rejects; see `DecisionOutcome`. */
+export type PendingOutcome<T> = {
+    outcome: 'settled';
+    value: T;
+} | {
+    outcome: 'timeout';
+    deadlineAt: number;
+} | {
+    outcome: 'aborted';
+} | {
+    outcome: 'closed';
+    reason: string;
+};
+export interface PendingCreateOptions {
+    kind: PendingKind;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    meta?: PendingMeta;
+}
+export interface PendingHandle<T> {
+    requestId: string;
+    createdAt: number;
+    deadlineAt: number;
+    settled: Promise<PendingOutcome<T>>;
+}
+/**
+ * `kind_mismatch` is NOT a duplicate and NOT unknown: the two frames really do
+ * refer to this request id, they just answer the wrong one of the two questions
+ * this table multiplexes. The entry must survive, because the party on the other
+ * end is still waiting for its own answer (AC-55).
+ */
+export type PendingAnswerResult = 'ok' | 'duplicate' | 'unknown' | 'kind_mismatch';
+export interface PendingTable {
+    /** `null` at capacity: refuse immediately rather than queueing. */
+    create<T>(options: PendingCreateOptions): PendingHandle<T> | null;
+    answer(requestId: string, kind: PendingKind, value: unknown): PendingAnswerResult;
+    /** Turn abort / interrupt / EOF: every entry resolves `aborted`, synchronously. */
+    abortAll(): void;
+    /** Server shutdown: every entry resolves `closed`. */
+    closeAll(reason: string): void;
+    size(): number;
+    kindOf(requestId: string): PendingKind | undefined;
+    metaOf(requestId: string): PendingMeta | undefined;
+    /** Ids still awaiting an answer, for tests and for `close()` logging. */
+    pendingIds(): string[];
+    /**
+     * Was this id settled BY AN ANSWER recently enough to still be remembered?
+     *
+     * The entry itself is gone once settled, so without this probe a second answer
+     * is indistinguishable from an answer to an id that never existed - and those
+     * two are different codes on purpose (`bridge_duplicate_response` vs
+     * `bridge_unknown_request`). Timeouts, aborts and closures are deliberately NOT
+     * remembered: answering one of those is "too late", not "twice".
+     */
+    wasAnswered(requestId: string): boolean;
+}
+export interface PendingTableOptions {
+    now?: () => number;
+    maxDecisions?: number;
+    maxCallerTools?: number;
+    maxSettledIds?: number;
+}
+export declare function createPendingTable(options?: PendingTableOptions): PendingTable;

package/dist/exec/bridge/pending.js

@@ -0,0 +1,132 @@
+/**
+ * The pending-request table: one entry per unanswered request, in either direction.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * ONE TABLE FOR TWO TRAFFIC DIRECTIONS, DELIBERATELY (headless-host-bridge section 1.3).
+ * A `decision_request` is the CLI asking the caller, a `tool_invoke` is the caller
+ * serving the CLI; both need an id, a deadline, settle-once, cancellation and a
+ * capacity ceiling. Two implementations would be two sets of rules about what a
+ * duplicate answer means, and the second one would be written by someone reading
+ * the first one. `kind` is what keeps them distinguishable, and it is also what
+ * makes `bridge_kind_mismatch` detectable at all.
+ *
+ * SETTLE-ONCE IS THE WHOLE STATE MACHINE. `done` is the only authority: a second
+ * `answer()` for the same id returns `duplicate` and changes nothing, and an
+ * `answer()` for an id that was never allocated returns `unknown`. Neither case
+ * changes the outcome the waiting tool already received.
+ */
+import { BRIDGE_LIMITS } from './limits.js';
+export function createPendingTable(options = {}) {
+    const now = options.now ?? Date.now;
+    const maxDecisions = options.maxDecisions ?? BRIDGE_LIMITS.maxOutstandingDecisions;
+    const maxCallerTools = options.maxCallerTools ?? BRIDGE_LIMITS.maxOutstandingCallerTools;
+    const maxSettled = options.maxSettledIds ?? BRIDGE_LIMITS.maxSettledIds;
+    const entries = new Map();
+    /** Bounded FIFO of ids settled by an ANSWER recently; see `maxSettledIds`. */
+    const settledIds = [];
+    let counter = 0;
+    const countOf = (kind) => {
+        let total = 0;
+        for (const entry of entries.values())
+            if (entry.kind === kind)
+                total += 1;
+        return total;
+    };
+    const remember = (requestId) => {
+        settledIds.push(requestId);
+        if (settledIds.length > maxSettled)
+            settledIds.shift();
+    };
+    const settleEntry = (entry, outcome, answered = false) => {
+        if (entry.done)
+            return false;
+        entry.done = true;
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.detachAbort?.();
+        entries.delete(entry.requestId);
+        if (answered)
+            remember(entry.requestId);
+        // RESOLVING IS SYNCHRONOUS HERE, which is what AC-49 depends on: when the
+        // turn aborts, every waiting tool is settled inside the abort listener's own
+        // tick, so it can finish inside the executor's 5 s grace window instead of
+        // being abandoned with the executor's own wording.
+        entry.settle(outcome);
+        return true;
+    };
+    return {
+        create(create) {
+            const cap = create.kind === 'decision' ? maxDecisions : maxCallerTools;
+            if (countOf(create.kind) >= cap)
+                return null;
+            counter += 1;
+            const createdAt = now();
+            const entry = {
+                requestId: `req_${counter}`,
+                kind: create.kind,
+                createdAt,
+                deadlineAt: createdAt + create.timeoutMs,
+                meta: create.meta ?? {},
+                done: false,
+                settle: () => { },
+            };
+            let resolveOutcome = () => { };
+            const settled = new Promise((resolve) => {
+                resolveOutcome = resolve;
+            });
+            entry.settle = resolveOutcome;
+            entries.set(entry.requestId, entry);
+            entry.timer = setTimeout(() => {
+                settleEntry(entry, { outcome: 'timeout', deadlineAt: entry.deadlineAt });
+            }, Math.max(0, create.timeoutMs));
+            // `unref` so a pending deadline can never be the reason the process stays
+            // alive: the run has its own reason to be running, and this timer is not it.
+            entry.timer.unref?.();
+            const signal = create.signal;
+            if (signal?.aborted) {
+                // ALREADY ABORTED, SO SETTLE NOW RATHER THAN ARMING A LISTENER. The
+                // executor abandons a tool 5 s after abort; a wait that only learned about
+                // the abort later would surface as "did not stop within 5000ms of abort"
+                // instead of "the turn was interrupted" (AC-49).
+                settleEntry(entry, { outcome: 'aborted' });
+            }
+            else if (signal) {
+                const onAbort = () => {
+                    settleEntry(entry, { outcome: 'aborted' });
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                entry.detachAbort = () => signal.removeEventListener('abort', onAbort);
+            }
+            return {
+                requestId: entry.requestId,
+                createdAt: entry.createdAt,
+                deadlineAt: entry.deadlineAt,
+                settled: settled,
+            };
+        },
+        answer(requestId, kind, value) {
+            const entry = entries.get(requestId);
+            if (!entry)
+                return settledIds.includes(requestId) ? 'duplicate' : 'unknown';
+            if (entry.kind !== kind)
+                return 'kind_mismatch';
+            return settleEntry(entry, { outcome: 'settled', value }, true) ? 'ok' : 'duplicate';
+        },
+        abortAll() {
+            for (const entry of [...entries.values()]) {
+                settleEntry(entry, { outcome: 'aborted' });
+            }
+        },
+        closeAll(reason) {
+            for (const entry of [...entries.values()]) {
+                settleEntry(entry, { outcome: 'closed', reason });
+            }
+        },
+        size: () => entries.size,
+        kindOf: (requestId) => entries.get(requestId)?.kind,
+        metaOf: (requestId) => entries.get(requestId)?.meta,
+        pendingIds: () => [...entries.keys()],
+        wasAnswered: (requestId) => settledIds.includes(requestId),
+    };
+}