@aragon-agent/cli 0.6.38 → 0.6.40

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

@@ -0,0 +1,58 @@
+/**
+ * `--input-format bridge`: one stdin stream, demultiplexed into turns and control.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * TWO KINDS OF FRAME ARRIVE ON THE SAME PIPE and they must not be confused:
+ *
+ *   TURN frames    `prompt` (and the v1 `user`) queue a message for the runner.
+ *   CONTROL frames `decision`, `tool_result`, `tool_register`, `ping`, `steer`,
+ *                  `interrupt` are answers to something already in flight and are
+ *                  routed straight to the server.
+ *
+ * The distinction is not cosmetic. A control frame that waited behind a turn would
+ * deadlock the run it is trying to unblock - a `decision` answer arriving while the
+ * tool that asked is still executing is the NORMAL case, not an edge case.
+ *
+ * UNLIKE `stdin-stream.ts` THIS SOURCE REMEMBERS METADATA PER PROMPT. A bridge
+ * prompt carries the caller's own id, and the turn that id starts has to be
+ * reportable in `user` / `turn_state` / `assistant` / `tool_call` / `tool_result`
+ * events. `lastPrompt()` is that channel; it is read once, synchronously, right
+ * after `next()` resolves, and it is deliberately NOT part of `next()`'s return
+ * value so `stdin-stream.ts` can keep serving plain strings (and its existing test
+ * can keep asserting exactly that).
+ */
+import type { ExecPrompt, ExecPromptSource } from '../runner.js';
+import type { BridgeServer } from './server.js';
+export interface BridgeSourceOptions {
+    input: NodeJS.ReadableStream;
+    server: BridgeServer;
+    /** A non-fatal frame problem, already carrying its `error.code`. */
+    onBadLine: (code: string, message: string) => void;
+}
+export interface BridgePromptSource extends ExecPromptSource {
+    /**
+     * Remove a QUEUED turn by the caller's id.
+     *
+     * Used by `interrupt{requestId}`: a caller that deletes its own queued message
+     * before it runs is the one case of cancellation that needs no abort at all.
+     */
+    cancelQueued(requestId: string): 'cancelled' | 'in_flight' | 'unknown';
+    isFinished(): boolean;
+    /** How many turns are waiting. Reported for tests and for `/status`-style views. */
+    queueDepth(): number;
+    /**
+     * Stop reading stdin and let the process exit.
+     *
+     * A CALLER THAT SENDS `end` HAS ALREADY SAID IT HAS NOTHING MORE TO SAY, and it
+     * is entitled to keep its own pipe open while it reads `result` - the reference
+     * host does exactly that. A `data` listener left attached would hold this
+     * process's event loop open forever, so the run would print `result`, exit
+     * nothing, and look hung while reporting success. Removing the listeners and
+     * pausing the stream is what turns "the run is over" into "the process ends".
+     */
+    close(): void;
+}
+export declare function createBridgePromptSource(options: BridgeSourceOptions): BridgePromptSource;
+/** The bridge source's own view of the id space, for tests and for `ack` wiring. */
+export declare function bridgePromptId(prompt: ExecPrompt | undefined): string | undefined;

package/dist/exec/bridge/source.js

@@ -0,0 +1,145 @@
+import { createNdjsonSplitter } from './ndjson.js';
+import { parseBridgeInput } from './protocol.js';
+export function createBridgePromptSource(options) {
+    const queue = [];
+    const waiting = [];
+    let finished = false;
+    /** A prompt has been handed over and the runner has not asked for the next. */
+    let inFlight = false;
+    let last;
+    let deliveredId;
+    /** Ids already handed to the runner, so `interrupt` can tell queued from running. */
+    const taken = [];
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        // NO MORE ANSWERS CAN ARRIVE, SO NOTHING MAY KEEP WAITING FOR ONE (section
+        // 2.3.8 rows 1-2). Without this, `end` or EOF with an unanswered decision
+        // leaves the run parked for the whole `--decision-timeout` (300 s by default)
+        // and then reports `timeout` instead of the truth, which is that the caller
+        // went away. It runs BEFORE the parked `next()` is released: the reverse order
+        // would let the run finish and report `result` while its tool still waited.
+        options.server.abortInFlight();
+        // Everything still parked resolves with `null` so a `next()` in flight when
+        // the pipe closes ends the run instead of hanging it forever.
+        while (waiting.length > 0)
+            waiting.shift()?.(null);
+    };
+    const acceptPrompt = (frame) => {
+        // `queued` IS CAPTURED HERE, AT ARRIVAL, because that is the only moment the
+        // question means anything: "was something already ahead of me?". By the time
+        // the runner picks this up the answer is always "no", which would make the
+        // field useless to a caller deciding whether to send a fourth message.
+        const queued = inFlight || queue.length > 0;
+        const requestId = frame.id ?? `prompt_${taken.length + queue.length + 1}`;
+        const resolve = waiting.shift();
+        if (resolve) {
+            inFlight = true;
+            taken.push(requestId);
+            deliveredId = requestId;
+            last = { text: frame.text, requestId, queued };
+            resolve(frame.text);
+            return;
+        }
+        // NOTHING IS RESET HERE. `last` describes the prompt just HANDED OVER, and the
+        // runner reads it one microtask later; clearing it for a queued arrival would
+        // wipe the metadata of a delivery that happened in the same chunk - the turn
+        // would lose its `requestId` and its `ack` entirely. `next()` clears it when
+        // there is nothing left to describe.
+        queue.push({ text: frame.text, requestId, queued });
+    };
+    const handleLine = (line) => {
+        const parsed = parseBridgeInput(line);
+        if (!parsed.ok) {
+            options.onBadLine(parsed.code, parsed.message);
+            return;
+        }
+        // `end` MEANS "NO MORE TURNS", NOT "NO MORE FRAMES".
+        //
+        // The v1 rule - after `end`, nothing else is a turn - is preserved exactly. But
+        // a bridge caller legitimately says "that is my last prompt" while a turn is
+        // still running, and then answers the decisions that turn produces; dropping
+        // those frames would deadlock the run until the decision deadline fired. So
+        // turn frames stop at `end` and control frames do not. After `result`, the
+        // server is closed and everything is ignored, which is the rule the design
+        // actually states.
+        if (parsed.frame.type === 'prompt') {
+            if (finished)
+                return;
+            acceptPrompt(parsed.frame);
+            return;
+        }
+        if (parsed.frame.type === 'end') {
+            finish();
+            return;
+        }
+        if (parsed.frame.type === 'ignored')
+            return;
+        options.server.handleFrame(parsed.frame);
+    };
+    const splitter = createNdjsonSplitter({
+        onLine: handleLine,
+        onTooLarge: (bytes) => {
+            options.onBadLine('bridge_frame_too_large', `Skipped a bridge frame of ${bytes} bytes.`);
+        },
+    });
+    const onData = (chunk) => splitter.push(chunk);
+    const onEnd = () => {
+        splitter.end();
+        finish();
+    };
+    const onError = () => finish();
+    options.input.setEncoding?.('utf-8');
+    options.input.on('data', onData);
+    options.input.on('end', onEnd);
+    options.input.on('error', onError);
+    return {
+        next: () => {
+            const queued = queue.shift();
+            if (queued) {
+                inFlight = true;
+                taken.push(queued.requestId);
+                deliveredId = queued.requestId;
+                last = { text: queued.text, requestId: queued.requestId, queued: queued.queued };
+                return Promise.resolve(queued.text);
+            }
+            // NOBODY IS QUEUED, SO NO TURN IS RUNNING. This is also what makes the next
+            // arriving prompt report `queued:false`, which is how a caller knows its
+            // message started driving the run.
+            inFlight = false;
+            last = undefined;
+            if (finished)
+                return Promise.resolve(null);
+            return new Promise((resolve) => waiting.push(resolve));
+        },
+        lastPrompt: () => last,
+        cancelQueued(requestId) {
+            const index = queue.findIndex((item) => item.requestId === requestId);
+            if (index >= 0) {
+                queue.splice(index, 1);
+                return 'cancelled';
+            }
+            if (requestId === deliveredId && inFlight)
+                return 'in_flight';
+            // A FINISHED TURN IS `unknown`, NOT `in_flight`. `taken` remembers every id
+            // ever delivered, so answering `in_flight` for one of those would make the
+            // runner abort a healthy run because the caller cancelled a message that had
+            // already been answered.
+            return 'unknown';
+        },
+        isFinished: () => finished,
+        queueDepth: () => queue.length,
+        close: () => {
+            finished = true;
+            options.input.removeListener('data', onData);
+            options.input.removeListener('end', onEnd);
+            options.input.removeListener('error', onError);
+            options.input.pause?.();
+        },
+    };
+}
+/** The bridge source's own view of the id space, for tests and for `ack` wiring. */
+export function bridgePromptId(prompt) {
+    return prompt?.requestId;
+}

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

@@ -0,0 +1,26 @@
+export interface BridgeWriterOptions {
+    out: NodeJS.WritableStream;
+    /** Stamped onto the `caller_not_reading` error this writer emits itself. */
+    sessionId: string;
+    softPendingBytes?: number;
+    hardPendingBytes?: number;
+    /** Invoked ONCE, when the hard watermark is crossed. The run aborts from here. */
+    onHardLimit?: () => void;
+}
+export interface BridgeWriter {
+    /** Stamp, serialize and write (or queue, before `open()`). */
+    write(event: Record<string, unknown>): void;
+    /** True once `system/init` has been written. */
+    isOpened(): boolean;
+    /** The highest `seq` written so far; `0` before anything. */
+    currentSeq(): number;
+    /** Bytes written and not yet accepted by the transport. */
+    pendingBytes(): number;
+    /** Await `drain` at a TURN BOUNDARY only - never per frame. */
+    drainIfNeeded(): Promise<void>;
+    /** Everything queued plus everything in flight. Called before `result` is written. */
+    flush(): Promise<void>;
+    /** Idempotent. No writes are accepted afterwards. */
+    close(): Promise<void>;
+}
+export declare function createBridgeWriter(options: BridgeWriterOptions): BridgeWriter;

package/dist/exec/bridge/writer.js

@@ -0,0 +1,156 @@
+/**
+ * The ONLY object that writes stdout in bridge mode (headless-host-bridge section 2.4.5).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THREE JOBS, AND EACH OF THEM IS A CONTRACT SOMETHING ELSE RELIES ON:
+ *
+ *   1. `seq`. Every line that leaves this process gets a gap-free, monotonically
+ *      increasing number, assigned HERE and nowhere else, which is what lets a
+ *      caller detect a dropped line and sort what it received.
+ *   2. `opened`. Nothing at all is written before `system/init`. The stdin source
+ *      starts reading about eighty lines before the emitter exists, so an early
+ *      `tool_register` or `prompt` can legitimately be answered before `init` has
+ *      been built; without this queue the `ack` would win the race and break the
+ *      one contract every wrapper builds its read loop on - `init` first,
+ *      `result` last (`exec/index.ts:70-79` records why that matters: a wrapper
+ *      that gets a `result` with no `init` cannot tell "never started" from
+ *      "failed").
+ *   3. Backpressure. A caller that never drains stdout must not be able to wedge
+ *      the agent inside a `write()` call, and must not be able to make this
+ *      process buffer without limit either. Soft and hard watermarks, both from
+ *      `BRIDGE_LIMITS`; the hard one fails the run loudly instead of growing.
+ */
+import { BRIDGE_LIMITS } from './limits.js';
+/** Identify the init event without importing the event module (keeps this pure). */
+function isInitEvent(event) {
+    return event.type === 'system' && event.subtype === 'init';
+}
+export function createBridgeWriter(options) {
+    const out = options.out;
+    const soft = options.softPendingBytes ?? BRIDGE_LIMITS.softPendingBytes;
+    const hard = options.hardPendingBytes ?? BRIDGE_LIMITS.hardPendingBytes;
+    let seq = 0;
+    let opened = false;
+    let closed = false;
+    let hardLimited = false;
+    let pendingBytes = 0;
+    const queue = [];
+    let drainWaiters = [];
+    const releaseDrainWaiters = () => {
+        const waiters = drainWaiters;
+        drainWaiters = [];
+        for (const resolve of waiters)
+            resolve();
+    };
+    // ONE listener for the life of the writer, attached lazily: a test double with
+    // no `on()` simply never reports backpressure, which is the honest reading of a
+    // stream that always accepts.
+    if (typeof out.on === 'function') {
+        out.on('drain', () => {
+            pendingBytes = 0;
+            releaseDrainWaiters();
+        });
+    }
+    const rawWrite = (event) => {
+        seq += 1;
+        const line = `${JSON.stringify({ ...event, seq })}\n`;
+        try {
+            // ONLY A REFUSED WRITE IS BACKLOG. `write()` returning `true` means the
+            // stream took the chunk - counting it anyway would report a caller as "not
+            // reading" merely because it is reading normally, and every flush would wait
+            // for a `drain` event that is never coming.
+            const accepted = out.write(line);
+            if (accepted === false)
+                pendingBytes += Buffer.byteLength(line, 'utf-8');
+        }
+        catch {
+            // A write that throws means the pipe is gone. The run is over either way;
+            // throwing from here would replace the caller-facing `result` with a stack
+            // trace, which is strictly less information.
+            pendingBytes = 0;
+        }
+    };
+    const enforceHardLimit = () => {
+        if (hardLimited)
+            return;
+        hardLimited = true;
+        // THE ONE FRAME THAT BYPASSES THE QUEUE. Telling the caller it is not reading
+        // is worthless if the telling itself waits behind the backlog it is about.
+        rawWrite({
+            type: 'error',
+            sessionId: options.sessionId,
+            fatal: true,
+            code: 'caller_not_reading',
+            message: `The caller has not read stdout for ${hard} bytes. ` +
+                'The run is aborting rather than buffering without limit.',
+        });
+        options.onHardLimit?.();
+    };
+    const writeNow = (event) => {
+        if (pendingBytes >= hard)
+            enforceHardLimit();
+        rawWrite(event);
+    };
+    const write = (event) => {
+        if (closed)
+            return;
+        if (isInitEvent(event)) {
+            writeNow(event);
+            opened = true;
+            // ARRIVAL ORDER, not priority: an `ack` that came before `init` was
+            // scheduled keeps its position relative to every other queued frame.
+            for (const queued of queue.splice(0))
+                writeNow(queued);
+            return;
+        }
+        if (!opened) {
+            queue.push(event);
+            return;
+        }
+        writeNow(event);
+    };
+    const drainIfNeeded = async () => {
+        if (pendingBytes < soft)
+            return;
+        // A caller that is reading will emit `drain`; one that is not will cross the
+        // hard watermark instead, and `enforceHardLimit` wakes this waiter.
+        await new Promise((resolve) => {
+            if (pendingBytes < soft) {
+                resolve();
+                return;
+            }
+            drainWaiters.push(resolve);
+            const timer = setTimeout(resolve, 1_000);
+            timer.unref?.();
+        });
+    };
+    return {
+        write,
+        isOpened: () => opened,
+        currentSeq: () => seq,
+        pendingBytes: () => pendingBytes,
+        drainIfNeeded,
+        async flush() {
+            if (pendingBytes <= 0)
+                return;
+            await new Promise((resolve) => {
+                drainWaiters.push(resolve);
+                const timer = setTimeout(() => {
+                    pendingBytes = 0;
+                    releaseDrainWaiters();
+                    resolve();
+                }, 200);
+                timer.unref?.();
+            });
+        },
+        async close() {
+            if (closed)
+                return;
+            for (const queued of queue.splice(0))
+                writeNow(queued);
+            closed = true;
+            releaseDrainWaiters();
+        },
+    };
+}

package/dist/exec/cli-commands.js

@@ -24,7 +24,7 @@ export function registerExecCommand(program, toFlags, deps) {
         .description('Headless, machine-facing run: JSON events, sessions, tool permissions, budgets')
         .argument('[prompt]', 'The prompt (or use --prompt-file, or pipe it on stdin)')
         .option('--output-format <fmt>', 'text | json | stream-json (default: text)')
-        .option('--input-format <fmt>', 'text | stream-json (needs --output-format stream-json)')
+        .option('--input-format <fmt>', 'text | stream-json | bridge (the last two need --output-format stream-json)')
         .option('--partial-messages', 'Emit text_delta events (stream-json only)')
         .option('--include-thinking', 'Emit thinking events (stream-json only)')
         .option('--prompt-file <path>', 'Read the prompt from a file')
@@ -35,7 +35,35 @@ export function registerExecCommand(program, toFlags, deps) {
         .option('--max-turns <n>', 'Stop after n assistant turns (exit 3)')
         .option('--max-duration <ms>', 'Stop after ms of wall clock (exit 3). --idle-timeout still applies to a silent ' +
         'stretch inside the run, and --tool-timeout to a single tool call')
-        .option('--permission-mode <m>', 'auto | plan | strict (default: auto)')
+        .option('--permission-mode <m>', 'auto | plan | strict | ask (default: auto). `ask` needs --input-format bridge: ' +
+        'it makes each mutating tool wait for the caller to allow it')
+        // THE FOUR BRIDGE BUDGETS. Declared here rather than hidden in `bridge/` so
+        // `aragon exec --help` is the complete list of what a caller can tune; the
+        // cross-checks that refuse them outside bridge mode live in `options.ts`.
+        .option('--decision-timeout <ms>', 'How long the caller has to answer one decision (bridge only; default 300000)')
+        .option('--on-decision-timeout <mode>', 'deny | error: what an unanswered decision means for the turn (bridge only; ' +
+        'default deny)')
+        .option('--caller-tool-timeout <ms>', 'Ceiling for one caller tool call (bridge only; default 60000)')
+        // THE STRUCTURED RESULT AND THE TWO PER-REQUEST BUDGETS. Declared here for the
+        // reason the four bridge budgets are: `aragon exec --help` has to be the complete
+        // list of what a caller can tune, and the cross-checks that refuse a combination
+        // live in `options.ts`, where they are unit-testable.
+        .option('--result-schema <path>', 'Validate the final answer against this JSON Schema and return it as ' +
+        '`result.structured` (json / stream-json / bridge)')
+        .option('--result-repair-turns <n>', 'How many times the model is asked to fix a rejected result (0-2; default 1)')
+        .option('--on-result-unsatisfied <mode>', 'error | continue: what an unsubmitted result means for the run (default error)')
+        .option('--request-max-turns <n>', 'Stop ONE request after n assistant turns, keeping the process alive (bridge only)')
+        .option('--request-max-duration <ms>', 'Stop ONE request after ms of wall clock, keeping the process alive (bridge only)')
+        // THE THREAD AND HOOK FLAGS (headless-threads-and-lifecycle-hooks section 4.1).
+        // Declared here for the reason the four bridge budgets are: `aragon exec --help` has to be
+        // the complete list of what a caller can tune, and the cross-checks that refuse a
+        // combination live in `options.ts`, where they are unit-testable.
+        .option('--threads', 'Serve N isolated conversations from one process (needs --input-format bridge and ' +
+        '--output-format stream-json). Open them with thread_open on stdin')
+        .option('--max-open-threads <n>', 'How many threads may exist at once, 1-8 (thread mode; default 4)')
+        .option('--thread-concurrency <n>', 'How many threads may hold a request in flight (thread mode; default 2)')
+        .option('--hook-timeout <ms>', 'Ceiling for one caller lifecycle hook round trip (bridge only; default 5000)')
+        .option('--on-hook-timeout <mode>', 'deny | allow | error: what an unanswered hook means (bridge only; default deny)')
         .option('--allow-tool <names>', 'Add tools to the baseline (repeatable; comma-separated accepted)', collect)
         .option('--deny-tool <names>', 'Remove tools; wins over --allow-tool (repeatable; comma-separated accepted)', collect)
         .option('--append-system-prompt <text>', 'Append text to the builtin system prompt')

package/dist/exec/emitter.d.ts

@@ -16,6 +16,7 @@
  * error, budget and signal - rather than true for the paths someone remembered.
  */
 import type { ExecEvent, ExecInitParams, ExecResultEvent, ExecResultParams } from './events.js';
+import type { BridgeWriter } from './bridge/writer.js';
 export interface ExecEmitter {
     init(params: ExecInitParams): void;
     /** Every non-`result` event. Ignored wholesale by `text` and `json`. */
@@ -70,11 +71,24 @@ export declare class JsonEmitter implements ExecEmitter {
  */
 export declare class StreamJsonEmitter implements ExecEmitter {
     private readonly out;
+    private readonly writer?;
     private done;
-    constructor(out: NodeJS.WritableStream);
+    /**
+     * `writer` is ABSENT IN EVERY NON-BRIDGE RUN, and that absence is the whole
+     * compatibility story (I-1): with no writer the three methods below fall through
+     * to the exact `this.out.write(toNdjsonLine(...))` they have always done, so
+     * `stream-json` stays byte-identical while bridge mode gains `seq`, the `init`
+     * queue and backpressure from one object.
+     *
+     * It is not the emitter that stamps `seq` - a stamp belongs where EVERY line
+     * passes, and bridge events (`ack`, `decision_request`) are produced by the
+     * server, which never sees this class.
+     */
+    constructor(out: NodeJS.WritableStream, writer?: BridgeWriter | undefined);
     init(params: ExecInitParams): void;
     emit(event: ExecEvent): void;
     result(params: ExecResultParams): void;
+    private write;
     emitted(): ExecResultEvent | null;
 }
-export declare function createEmitter(format: 'text' | 'json' | 'stream-json', out: NodeJS.WritableStream): ExecEmitter;
+export declare function createEmitter(format: 'text' | 'json' | 'stream-json', out: NodeJS.WritableStream, writer?: BridgeWriter): ExecEmitter;

package/dist/exec/emitter.js

@@ -94,34 +94,54 @@ export class JsonEmitter {
  */
 export class StreamJsonEmitter {
     out;
+    writer;
     done = null;
-    constructor(out) {
+    /**
+     * `writer` is ABSENT IN EVERY NON-BRIDGE RUN, and that absence is the whole
+     * compatibility story (I-1): with no writer the three methods below fall through
+     * to the exact `this.out.write(toNdjsonLine(...))` they have always done, so
+     * `stream-json` stays byte-identical while bridge mode gains `seq`, the `init`
+     * queue and backpressure from one object.
+     *
+     * It is not the emitter that stamps `seq` - a stamp belongs where EVERY line
+     * passes, and bridge events (`ack`, `decision_request`) are produced by the
+     * server, which never sees this class.
+     */
+    constructor(out, writer) {
         this.out = out;
+        this.writer = writer;
     }
     init(params) {
         if (this.done)
             return;
-        this.out.write(toNdjsonLine(buildInitEvent(params)));
+        this.write(buildInitEvent(params));
     }
     emit(event) {
         if (this.done)
             return;
-        this.out.write(toNdjsonLine(event));
+        this.write(event);
     }
     result(params) {
         if (this.done)
             return;
         this.done = buildResultEvent(params);
-        this.out.write(toNdjsonLine(this.done));
+        this.write(this.done);
+    }
+    write(event) {
+        if (this.writer) {
+            this.writer.write(event);
+            return;
+        }
+        this.out.write(toNdjsonLine(event));
     }
     emitted() {
         return this.done;
     }
 }
-export function createEmitter(format, out) {
+export function createEmitter(format, out, writer) {
     if (format === 'json')
         return new JsonEmitter(out);
     if (format === 'stream-json')
-        return new StreamJsonEmitter(out);
+        return new StreamJsonEmitter(out, writer);
     return new TextEmitter();
 }