@aragon-agent/cli 0.6.37 → 0.6.39

package/dist/exec/threads/runtime.js

@@ -0,0 +1,523 @@
+/**
+ * One thread: its controller, its bridge server, its runner, its lifecycle
+ * (headless-threads-and-lifecycle-hooks section 2.3.4).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE CONSTRUCTION ORDER IS THE DESIGN, and every step exists because putting it later
+ * leaves something half-built:
+ *
+ *   1. session identity and the lock (done by the registry, BEFORE this object exists, so a
+ *      refusal never leaves a constructed controller behind);
+ *   2. the hook runtime (a plain object over the shared writer - no controller needed, and
+ *      the controller needs it, so it must come first);
+ *   3. the bridge server, with a controller BOX rather than a controller - the server's
+ *      ports reach the controller that does not exist yet, exactly as the single-run path
+ *      solves it;
+ *   4. the controller, with this thread's gates, result tool and hook runner;
+ *   5. the runner, `attach`, then `attachBridge` with this thread's own source;
+ *   6. `preflight()`, whose failure ends THIS thread and nothing else;
+ *   7. `thread_state{opened}`.
+ *
+ * WHAT IS SHARED: the writer (one global `seq`), the emitter (one `result`), the admission
+ * gate and the registry. What is NOT: everything else. That list is I-T2, and it is a
+ * consequence of this file owning its objects rather than a rule anyone has to remember.
+ */
+import { computeCost } from '../../agent/usage.js';
+import { ExecRunner } from '../runner.js';
+import { createBridgeServer } from '../bridge/server.js';
+import { LEAD_SCOPE } from '../bridge/protocol.js';
+import { createCallerTools } from '../bridge/caller-tools.js';
+import { createCallerApprovalGate, createCallerHumanInputGate, createCallerToolGate, } from '../bridge/decisions.js';
+import { createHookRuntime } from '../hooks/index.js';
+import { resolvePermission } from '../permission.js';
+import { RESULT_LIMITS } from '../result/limits.js';
+import { createResultSink } from '../result/sink.js';
+import { createSubmitResultTool, SUBMIT_RESULT_TOOL } from '../result/tool.js';
+import { buildStructuredResultBlock } from '../result/prompt.js';
+import { DEFAULT_THREAD_ID } from './identity.js';
+export class ThreadOpenError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ThreadOpenError';
+    }
+}
+export function createThreadRuntime(deps) {
+    let state = 'opening';
+    let controller = null;
+    let server = null;
+    let runner = null;
+    let hooks = null;
+    let requests = 0;
+    let turns = 0;
+    let usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    let cost = { amount: 0, currency: 'USD', known: false };
+    let isError = false;
+    let endReason;
+    let openedAt = deps.now();
+    let closedAt;
+    let logDisposers = [];
+    let drain = null;
+    let drainedPromise = null;
+    /** The controller box the server's ports read (step 3 of the header's order). */
+    const box = { controller: null };
+    let parkedSpecs = null;
+    const finish = (reason) => {
+        if (state === 'closed')
+            return;
+        state = 'closed';
+        endReason = reason;
+        closedAt = deps.now();
+        drain?.();
+        drain = null;
+    };
+    const account = () => ({
+        threadId: deps.threadId,
+        sessionId: deps.sessionId,
+        requests,
+        turns,
+        usage,
+        cost,
+        isError,
+        reason: endReason ?? 'closed',
+    });
+    const summarize = () => ({
+        threadId: deps.threadId,
+        sessionId: deps.sessionId,
+        state,
+        requests,
+        turns,
+        inFlight: false,
+    });
+    const emitThreadState = (phase) => {
+        const current = account();
+        deps.emitter.emit({
+            type: 'thread',
+            sessionId: deps.sessionId,
+            threadId: deps.threadId,
+            phase,
+            ...(phase === 'closed'
+                ? {
+                    reason: current.reason,
+                    requests: current.requests,
+                    turns: current.turns,
+                    durationMs: Math.max(0, (closedAt ?? deps.now()) - openedAt),
+                    usage: current.usage,
+                    cost: current.cost,
+                    isError: current.isError,
+                }
+                : {}),
+        });
+    };
+    const applySpecs = (specs) => {
+        if (!box.controller || !server) {
+            parkedSpecs = specs;
+            return;
+        }
+        box.controller.applyCallerTools(createCallerTools(specs, server, deps.options.callerToolTimeoutMs));
+    };
+    const openInternal = async () => {
+        // The one source this runtime serves; `run()` re-states it, and this is the copy the
+        // bridge channel is wired to.
+        const source = deps.source;
+        // --- 2. the hook runtime, BEFORE the controller that consumes it. ---
+        hooks = createHookRuntime({
+            sessionId: deps.sessionId,
+            // THE SHARED WRITER, NOT THE SERVER: the controller is constructed with the runner's
+            // hook port, and `writer` is the one object that stamps `seq` on every line anyway.
+            write: (event) => deps.writer.write({ ...event, threadId: deps.threadId }),
+            knownTools: () => {
+                const names = new Set((box.controller?.listTools() ?? []).map((t) => t.name));
+                for (const name of box.controller?.callerToolNames() ?? [])
+                    names.add(name);
+                return names;
+            },
+            timeoutMs: deps.hookTimeoutMs,
+            policy: () => deps.options.onHookTimeout,
+            now: deps.now,
+        });
+        // --- 3. the server, whose ports reach a controller that does not exist yet. ---
+        server = createBridgeServer({
+            writer: deps.writer,
+            sessionId: deps.sessionId,
+            now: deps.now,
+            decisionTimeoutMs: deps.options.decisionTimeoutMs,
+            callerToolTimeoutMs: deps.options.callerToolTimeoutMs,
+            ports: {
+                applyCallerTools: applySpecs,
+                isTurnActive: () => box.controller?.isRunning() === true,
+                callerToolNames: () => box.controller?.callerToolNames() ?? [],
+                getAgentMode: () => box.controller?.getAgentMode() ?? 'build',
+            },
+            hookPorts: {
+                register: (frame) => {
+                    const ack = hooks?.register(frame) ?? {
+                        accepted: false,
+                        code: 'hook_requires_bridge',
+                        message: 'Lifecycle hooks are not available on this thread.',
+                    };
+                    deps.writer.write({
+                        type: 'ack',
+                        ...(frame.id ? { id: frame.id } : {}),
+                        threadId: deps.threadId,
+                        accepted: ack.accepted,
+                        ...(ack.code ? { code: ack.code } : {}),
+                        ...(ack.message ? { message: ack.message } : {}),
+                        ...(ack.hooks ? { hooks: ack.hooks } : {}),
+                        ...(ack.warnings ? { warnings: ack.warnings } : {}),
+                    });
+                },
+                answer: (frame) => hooks?.answer(frame) ?? false,
+            },
+            onAudit: (record) => {
+                // A HOOK DECISION IS AUDITED ON THE HOOK CHANNEL, not double-counted here: the
+                // `hook_resolved` frame already carries outcome and code, and a second line would
+                // make one decision look like two.
+                if (record.kind === 'hook')
+                    return;
+            },
+        });
+        const permission = resolvePermission({
+            mode: deps.options.permissionMode,
+            allow: deps.options.allowTools,
+            deny: deps.options.denyTools,
+        });
+        const resultSink = deps.resultSpec ? createResultSink({ now: deps.now }) : null;
+        const resultTool = deps.resultSpec && resultSink
+            ? createSubmitResultTool({ spec: deps.resultSpec, sink: resultSink })
+            : undefined;
+        const structuredResultBlock = deps.resultSpec
+            ? buildStructuredResultBlock({
+                toolName: SUBMIT_RESULT_TOOL,
+                hasDefinitions: deps.resultSpec.hasDefinitions,
+                repairTurns: deps.options.resultRepairTurns ?? RESULT_LIMITS.defaultRepairTurns,
+            })
+            : '';
+        const gateScope = LEAD_SCOPE;
+        const allow = new Set(deps.options.allowTools);
+        const gateFor = (scope) => createCallerToolGate({
+            server: server,
+            mode: deps.options.permissionMode,
+            allow,
+            scope,
+            decisionTimeoutMs: deps.options.decisionTimeoutMs,
+        });
+        // --- 4. the controller. ---
+        const created = deps.makeController(deps.options.permissionMode === 'plan' ? { ...deps.flags, plan: true } : deps.flags, {
+            ...(permission ? { permission } : {}),
+            ...(resultTool ? { resultTool } : {}),
+            ...(structuredResultBlock ? { structuredResultBlock } : {}),
+            ...(hooks ? { hookRunner: hooks.toolRunner } : {}),
+            toolGate: gateFor(gateScope),
+            // ONE TABLE, ONE SET OF IDS, ONE CAPACITY, exactly as the single-run path wires it.
+            toolGateForChild: (label) => gateFor({ id: label, label, depth: 1 }),
+            approval: createCallerApprovalGate(server),
+            humanInput: createCallerHumanInputGate(server),
+            decisionBudgetMs: deps.options.decisionTimeoutMs,
+            // THE TWO FLAGS THAT MAKE PROCESS-LEVEL LOG MOUNTS HAPPEN ONCE (P1-8). `threadId`
+            // stamps this thread; `processLevelMounts` is true for exactly one construction in
+            // the process - the default thread's - because a mount guarded on `threadId` would
+            // never run at all (the default thread has an id too).
+            threadId: deps.threadId,
+            processLevelMounts: deps.threadId === DEFAULT_THREAD_ID,
+            onAttach: (disposers) => {
+                logDisposers = disposers;
+            },
+        });
+        controller = created;
+        box.controller = created;
+        if (parkedSpecs) {
+            const specs = parkedSpecs;
+            parkedSpecs = null;
+            applySpecs(specs);
+        }
+        // --- 5. the runner. ---
+        runner = new ExecRunner({
+            emitter: deps.emitter,
+            sessionId: deps.sessionId,
+            threadId: deps.threadId,
+            // PROCESS-LEVEL CEILINGS STAY PROCESS-LEVEL (section 2.3.8b): `--max-turns` is refused
+            // with `--threads`, and `--max-duration` is one timer owned by `executeThreads`, so
+            // neither may be re-installed here.
+            ...(deps.options.requestMaxTurns !== undefined
+                ? { requestMaxTurns: deps.options.requestMaxTurns }
+                : {}),
+            ...(deps.options.requestMaxDurationMs !== undefined
+                ? { requestMaxDurationMs: deps.options.requestMaxDurationMs }
+                : {}),
+            ...(resultSink
+                ? {
+                    resultSink,
+                    ...(deps.resultSpec ? { resultSchemaName: deps.resultSpec.name } : {}),
+                    resultRepairTurns: deps.options.resultRepairTurns ?? RESULT_LIMITS.defaultRepairTurns,
+                    onResultUnsatisfied: deps.options.onResultUnsatisfied ?? 'error',
+                }
+                : {}),
+            cost: (reading, compaction) => threadCost(created, reading, compaction),
+            partialMessages: deps.options.partialMessages,
+            includeThinking: deps.options.includeThinking,
+            followThrough: created.getTodoConfig().followThrough,
+            quiet: deps.options.quiet,
+            stderr: process.stderr,
+            now: deps.now,
+            // THE TERMINATOR BELONGS TO THE PROCESS, NOT TO THIS RUNNER (section 2.3.8a).
+            installSignalTerminator: false,
+            // THE ADMISSION SLOT IS FREED THROUGH THE SOURCE THAT TOOK IT.
+            //
+            // `gate.release()` called from anywhere else leaves the source's `holding` flag set,
+            // and a source that believes it still holds a slot never acquires again: from that
+            // thread's SECOND request onward `--thread-concurrency` would silently stop applying,
+            // while every subsequent direct release threw "without a matching acquire". The
+            // release is idempotent (`holding` guards it), so a request that never acquired -
+            // impossible today, but cheap to be sure about - is a no-op.
+            onRequestSettled: () => {
+                requests += 1;
+                deps.source.release();
+            },
+            ...(hooks
+                ? {
+                    hookPort: {
+                        promptPre: (input) => hooks
+                            ? hooks.promptPre({
+                                text: input.text,
+                                queued: input.queued,
+                                requestId: input.requestId,
+                            })
+                            : Promise.resolve({ action: 'allow' }),
+                    },
+                    beforeTurn: (info) => hooks
+                        ? hooks.beforeTurn({
+                            turn: info.turn,
+                            source: info.source,
+                            requestId: info.requestId,
+                        })
+                        : Promise.resolve(undefined),
+                }
+                : {}),
+        });
+        runner.attach(created);
+        // THE BRIDGE CHANNEL, WITH THIS THREAD'S OWN SOURCE (section 2.3.4 step 5).
+        //
+        // THE WHOLE FRAME CONTRACT DEPENDS ON THIS CALL: the server's turn ports are installed
+        // here and the runner's `bridge` / `bridgeSource` fields are assigned here - which is what
+        // makes a served prompt write `ack{accepted:true, requestSeq}`, a turn write
+        // `request_end`, a `steer` reach `queueUserMessage`, and `interrupt{requestId}` reach
+        // `cancelQueued`. Without it a thread-mode run is silent on every one of those, and
+        // `cancel_request` is dropped without a receipt.
+        runner.attachBridge(server, source);
+        // --- 6. preflight. A failure here ends this thread and none of the others. ---
+        const pre = created.preflight();
+        if (!pre.ok) {
+            isError = true;
+            emitThreadState('opened');
+            finish('error');
+            throw new ThreadOpenError('thread_open_failed', pre.message ?? 'Configuration error.');
+        }
+        state = 'open';
+        openedAt = deps.now();
+        // `opened` IS ANNOUNCED BY THE REGISTRY, NOT HERE (implementation note): the process
+        // `system/init` line must precede the first thread event, and init needs the controller
+        // this method has just built. Announcing from here would queue `thread{opened}` ahead of
+        // init in the writer, which flushes strictly in arrival order.
+    };
+    const dispose = () => {
+        // A SLOT CANNOT OUTLIVE THE THREAD THAT TOOK IT: if the run ends while a request still
+        // held one (an aborted close, a provider error between two turns), the gate would keep
+        // that slot for the rest of the process and every other thread would queue behind a
+        // tenant that no longer exists. `release()` is idempotent.
+        deps.source.release();
+        hooks?.close();
+        for (const off of logDisposers.splice(0)) {
+            try {
+                off();
+            }
+            catch {
+                // A disposer that was already torn down is not a reason to skip the rest, and
+                // reporting it here would replace the thread's own account with a stack trace.
+            }
+        }
+        if (runner) {
+            const stats = runner.stats();
+            turns = stats.turns;
+            usage = {
+                inputTokens: stats.usage.inputTokens,
+                outputTokens: stats.usage.outputTokens,
+                totalTokens: stats.usage.inputTokens + stats.usage.outputTokens,
+            };
+            if (controller)
+                cost = threadCost(controller, stats.usage, stats.compactionBilling);
+            // A TIMEOUT THAT FIRED ON THIS THREAD IS A THREAD-LEVEL FACT even though the timer is
+            // process-level: the account has to say why this conversation stopped.
+            if (stats.stopReason === 'timeout' && endReason !== 'error')
+                endReason ??= 'timeout';
+            if (stats.errored)
+                isError = true;
+            runner.detach();
+            runner = null;
+        }
+        const owned = controller;
+        controller = null;
+        box.controller = null;
+        if (owned) {
+            if (deps.sessionFile !== null) {
+                try {
+                    deps.persist({
+                        sessionId: deps.sessionId,
+                        controller: owned,
+                        turns,
+                        usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
+                        at: deps.now(),
+                    });
+                }
+                catch {
+                    // PERSIST FIRST, ANNOUNCE SECOND, AND A FAILED PERSIST IS NOT A FAILED RUN: the
+                    // caller still receives the account, and the next invocation starts fresh.
+                }
+            }
+            try {
+                owned.dispose();
+            }
+            catch {
+                deps.writer.write({
+                    type: 'error',
+                    sessionId: deps.sessionId,
+                    threadId: deps.threadId,
+                    fatal: false,
+                    code: 'thread_dispose_failed',
+                    message: `Thread "${deps.threadId}" could not dispose its controller cleanly.`,
+                });
+            }
+        }
+        deps.lock?.release();
+        void server?.close('run_finished');
+    };
+    return {
+        threadId: deps.threadId,
+        sessionId: deps.sessionId,
+        sessionFile: deps.sessionFile,
+        state: () => state,
+        async open() {
+            await openInternal();
+        },
+        async run(source) {
+            if (!runner)
+                throw new Error('ThreadRuntime.run() before open()');
+            // ONE SOURCE PER RUNTIME, ENFORCED RATHER THAN ASSUMED: `open()` wired the bridge
+            // channel to `deps.source`, so a different queue here would leave the two disagreeing
+            // about which prompt is in flight, and `cancelQueued` would answer about the wrong one.
+            if (source !== deps.source) {
+                throw new Error("ThreadRuntime.run() received a source that is not this thread's queue");
+            }
+            try {
+                await runner.run(source);
+            }
+            catch (error) {
+                // ONE TENANT'S PROVIDER ERROR IS NOT THE PROCESS'S (I-T4). The runner has recorded
+                // the error and re-thrown; absorbing it here is what keeps the other conversations
+                // - and the process's `result` - alive.
+                isError = true;
+                endReason ??= 'error';
+                deps.writer.write({
+                    type: 'error',
+                    sessionId: deps.sessionId,
+                    threadId: deps.threadId,
+                    fatal: false,
+                    code: 'agent_error',
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                const reason = endReason ?? (isError ? 'error' : 'closed');
+                dispose();
+                finish(reason);
+                emitThreadState('closed');
+            }
+        },
+        requestClose(mode) {
+            if (state === 'closed')
+                return;
+            state = 'closing';
+            emitThreadState('closing');
+            // EVERY IN-FLIGHT HOOK SETTLES NOW: a hook waiting for an answer on a thread that is
+            // closing would otherwise hold the request open until its timeout (I-H2's spirit).
+            hooks?.abortAll();
+            if (mode === 'abort') {
+                runner?.cancelRequest(undefined, undefined);
+                endReason ??= 'aborted';
+                return;
+            }
+            endReason ??= 'closed';
+        },
+        drained() {
+            if (state === 'closed')
+                return Promise.resolve();
+            drainedPromise ??= new Promise((resolve) => {
+                drain = resolve;
+            });
+            return drainedPromise;
+        },
+        interrupt() {
+            runner?.requestInterrupt();
+        },
+        timeout() {
+            // THE SAME ABORT PATH AS A SIGNAL, with the reason that makes `result` honest. The
+            // process timer is `executeThreads`' single owner; a thread only reports it.
+            endReason ??= 'timeout';
+            runner?.requestInterrupt();
+        },
+        summarize,
+        account,
+        hooks: () => hooks,
+        announceOpened: () => emitThreadState('opened'),
+        describe() {
+            const config = box.controller?.getConfig();
+            return {
+                model: {
+                    provider: config?.provider ?? 'unknown',
+                    id: config?.model ?? 'unknown',
+                    baseUrl: config?.baseUrl ?? null,
+                },
+                cwd: box.controller?.getCwd() ?? process.cwd(),
+                tools: (box.controller?.listTools() ?? []).map((tool) => tool.name),
+                sessionId: deps.sessionId,
+                sessionFile: deps.sessionFile,
+            };
+        },
+        handleControl(frame) {
+            server?.handleFrame(frame);
+        },
+        server: () => server,
+        flushCallerTools() {
+            if (parkedSpecs)
+                applySpecs(parkedSpecs);
+        },
+    };
+}
+/**
+ * The cost of one thread's usage.
+ *
+ * A LOCAL WRAPPER OVER `computeCost`, deliberately: `exec/index.ts`'s `buildCost` takes the
+ * composition root's controller, and importing it here would make
+ * `exec/index.ts -> threads -> exec/index.ts` a cycle. The shared authority is
+ * `computeCost`; this is the four-line projection between them.
+ */
+function threadCost(controller, reading, compaction) {
+    const config = controller.getConfig();
+    const known = compaction?.pricingUnknown !== true &&
+        controller.isPricedModel({ providerId: config.provider, modelId: config.model });
+    const main = {
+        inputTokens: reading.inputTokens - (compaction?.usage.inputTokens ?? 0),
+        outputTokens: reading.outputTokens - (compaction?.usage.outputTokens ?? 0),
+        cacheReadTokens: (reading.cacheReadTokens ?? 0) - (compaction?.usage.cacheReadTokens ?? 0),
+        cacheWriteTokens: (reading.cacheWriteTokens ?? 0) - (compaction?.usage.cacheWriteTokens ?? 0),
+    };
+    return {
+        amount: known
+            ? computeCost(main, controller.getModelInfo().cost) + (compaction?.costUsd ?? 0)
+            : 0,
+        currency: 'USD',
+        known,
+    };
+}

package/dist/exec/threads/thread-source.d.ts

@@ -0,0 +1,20 @@
+import type { BridgePromptSource } from '../bridge/source.js';
+import { type AdmissionGate } from './gate.js';
+export interface ThreadPromptSource extends BridgePromptSource {
+    /** Prompts accepted but not yet served, for `thread_list`. */
+    waiting(): number;
+}
+/** The write side: what the dispatch source uses to feed this thread. */
+export interface ThreadSource extends ThreadPromptSource {
+    /** Accept a prompt. Never rejects: a finished source drops it (the router acks first). */
+    push(text: string, requestId: string, queued?: boolean): void;
+    /** No more prompts will arrive (`end` frame, EOF, or a close). */
+    finish(): void;
+    /** Release a held slot; called by the runtime when a request settles, and on close. */
+    release(): void;
+}
+export interface ThreadSourceOptions {
+    threadId: string;
+    gate: AdmissionGate;
+}
+export declare function createThreadSource(options: ThreadSourceOptions): ThreadSource;

package/dist/exec/threads/thread-source.js

@@ -0,0 +1,134 @@
+import { GateClosedError } from './gate.js';
+export function createThreadSource(options) {
+    const queue = [];
+    let parked = [];
+    let finished = false;
+    let inFlight = false;
+    let last;
+    let deliveredId;
+    /** Every id ever served, so a finished turn is `unknown` rather than `in_flight`. */
+    const taken = [];
+    let holding = false;
+    const wake = () => {
+        const waiting = parked;
+        parked = [];
+        for (const resolve of waiting)
+            resolve(null);
+    };
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        // EVERY PARKED `next()` RESOLVES NOW, so a run that was waiting for input ends
+        // instead of hanging the process it is supposed to be releasing.
+        wake();
+    };
+    /**
+     * Wait until there is something to serve.
+     *
+     * Returns the index of a servable prompt, or `null` when the source is finished and
+     * drained. PARKED RESOLVERS ARE RE-CHECKED IN A LOOP because `cancelQueued` can
+     * remove the very prompt a waiter was woken for.
+     */
+    const takeCandidate = async () => {
+        for (;;) {
+            const candidate = queue[0];
+            if (candidate) {
+                if (!holding) {
+                    try {
+                        await options.gate.acquire(options.threadId);
+                    }
+                    catch (err) {
+                        // THE GATE CLOSED: the process is shutting down, so this source ends rather
+                        // than reporting a prompt it could never be allowed to run.
+                        if (err instanceof GateClosedError)
+                            return null;
+                        throw err;
+                    }
+                    holding = true;
+                }
+                // The prompt may have been cancelled while this thread queued for a slot.
+                const now = queue[0];
+                if (now)
+                    return now;
+                // THE SLOT IS HANDED BACK, NOT CARRIED AWAY: `now` is undefined only when the queue
+                // drained under us, and continuing to the `parked` branch below while `holding` is
+                // true would leave this thread holding a slot with no request in flight - forever,
+                // because nothing else can release it. With `--thread-concurrency 1` that starves
+                // every other tenant.
+                release();
+                continue;
+            }
+            if (finished)
+                return null;
+            await new Promise((resolve) => parked.push(resolve));
+        }
+    };
+    const release = () => {
+        if (!holding)
+            return;
+        holding = false;
+        try {
+            options.gate.release(options.threadId);
+        }
+        catch {
+            // A double release after `gate.close()` is not worth failing a completed request
+            // over; the gate is being torn down and every slot is about to be discarded.
+        }
+    };
+    return {
+        async next() {
+            const candidate = await takeCandidate();
+            if (!candidate) {
+                inFlight = false;
+                last = undefined;
+                return null;
+            }
+            const index = queue.indexOf(candidate);
+            if (index >= 0)
+                queue.splice(index, 1);
+            inFlight = true;
+            taken.push(candidate.requestId);
+            deliveredId = candidate.requestId;
+            last = {
+                text: candidate.text,
+                requestId: candidate.requestId,
+                queued: candidate.queued === true,
+            };
+            return candidate.text;
+        },
+        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`, NEVER `in_flight` - the rule the bridge source
+            // records at length; answering otherwise makes a late cancel abort a healthy run.
+            return 'unknown';
+        },
+        isFinished: () => finished,
+        queueDepth: () => queue.length,
+        waiting: () => queue.length,
+        push(text, requestId, queued) {
+            if (finished)
+                return;
+            // `queued` IS CAPTURED AT ARRIVAL for the same reason the bridge source captures
+            // it there: by the time the runner asks, "was something ahead of me" is always
+            // false and the field would be useless.
+            const wasQueued = queued ?? (inFlight || queue.length > 0);
+            queue.push({ text, requestId, queued: wasQueued });
+            // A parked waiter is released with `null` (its loop re-checks the queue), which
+            // keeps one wake-up path instead of two that can disagree.
+            wake();
+        },
+        finish,
+        close() {
+            finish();
+        },
+        release,
+    };
+}