@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/exec/threads/registry.js

@@ -0,0 +1,427 @@
+/**
+ * The thread table and its state machine (headless-threads-and-lifecycle-hooks
+ * section 2.3.4).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ *    (absent) --thread_open--> opening --ack{accepted:true}--> open
+ *                                 |                              |
+ *                                 | ack{accepted:false}          | thread_close
+ *                                 v                              v
+ *                              (absent)                       closing
+ *                                                                | request settled,
+ *                                                                | controller disposed
+ *                                                                v
+ *                                                             closed --> (record kept)
+ *
+ * FOUR RULES THAT ARE EASY TO GET WRONG, AND ARE THEREFORE EXPLICIT HERE:
+ *
+ *   `opening` IS ASYNCHRONOUS AND ITS FRAMES ARE NOT DROPPED. `thread_open` constructs a
+ *   controller and takes a session lock while `handleLine` is synchronous, so a caller that
+ *   writes `thread_open` and `prompt` back to back - the normal Web-backend shape - must
+ *   have its prompt QUEUED, not discarded (I-T7).
+ *
+ *   A CLOSED THREAD KEEPS ITS RECORD. Its account belongs in `result.threads.items`, so
+ *   deleting it would make the process's answer disagree with the events the caller
+ *   already received - but it stops occupying `maxOpenThreads` and never holds a slot.
+ *
+ *   `interruptAll` ALSO FINISHES THE SOURCES. A process-level interrupt means "no more
+ *   work", not "abort what is running and then keep serving": without the second half, a
+ *   parked `next()` would keep the process alive after Ctrl-C.
+ *
+ *   THE DEFAULT THREAD HAS NO `ack`. Nobody sent a frame, so a receipt would be a reply to
+ *   a request that was never made. It is opened by `openDefault()`, which also gives
+ *   `executeThreads` the one chance to emit `system/init` BEFORE the first thread event.
+ */
+import { canOpen } from './capacity.js';
+import { DEFAULT_THREAD_ID, resolveThreadIdentity } from './identity.js';
+import { ThreadOpenError } from './runtime.js';
+import { createThreadSource } from './thread-source.js';
+import { withinRequestCap } from './capacity.js';
+export function createThreadRegistry(deps) {
+    const records = new Map();
+    /** Open order, so `result.threads.items` can be zipped with the events. */
+    const order = [];
+    /**
+     * One `drained()` per runtime, pushed the moment the runtime exists.
+     *
+     * A LIST, NOT A SNAPSHOT OF `records`, because the process's exit condition is "every
+     * thread that was ever opened has closed" and a snapshot taken before stdin has been read
+     * contains only `main` (section 2.3.3: the frames arrive after `openDefault()` returns).
+     * With a snapshot, `end` would be followed by `result` as soon as the DEFAULT thread
+     * finished, cutting off a tenant that was still mid-request - AC-36's exact claim.
+     */
+    const drains = [];
+    let promptCounter = 0;
+    let firstOpen = true;
+    const activeCount = () => {
+        let count = 0;
+        for (const record of records.values()) {
+            if (record.state !== 'closed')
+                count += 1;
+        }
+        return count;
+    };
+    const ack = (frameId, extra) => {
+        deps.write({ type: 'ack', ...(frameId ? { id: frameId } : {}), ...extra });
+    };
+    const refuse = (frameId, code, message, threadId) => {
+        ack(frameId, { ...(threadId ? { threadId } : {}), accepted: false, code, message });
+    };
+    const deliver = (record, text, frameId) => {
+        promptCounter += 1;
+        record.source.push(text, frameId ?? `prompt_${promptCounter}`);
+    };
+    /**
+     * The synchronous checks. Kept apart from `start()` so a refusal never creates a record -
+     * "no thread was created" is one of the acceptance criteria (AC-13) and a record that
+     * exists only to be deleted would make that claim harder to keep.
+     */
+    const admit = (threadId, explicitSessionId) => {
+        const capacity = canOpen({ active: activeCount(), maxOpenThreads: deps.maxOpenThreads });
+        if (capacity !== true) {
+            return {
+                ok: false,
+                code: capacity,
+                message: `At most ${deps.maxOpenThreads} threads may be open at once.`,
+            };
+        }
+        const identity = resolveThreadIdentity({
+            threadId,
+            baseSessionId: deps.baseSessionId,
+            ...(explicitSessionId !== undefined ? { explicitSessionId } : {}),
+            saving: deps.saving,
+        });
+        if (!identity.ok) {
+            return {
+                ok: false,
+                code: identity.code,
+                message: identity.code === 'thread_id_too_long'
+                    ? `Thread "${threadId}" derives a session id longer than 64 characters; ` +
+                        'shorten --session-id.'
+                    : `Thread id "${threadId}" must match [a-z0-9][a-z0-9_-]{0,31}, and any ` +
+                        'explicit sessionId must be a legal session id.',
+            };
+        }
+        const lock = deps.saving ? (deps.acquireLock?.(identity.sessionId) ?? null) : null;
+        if (deps.saving && !lock) {
+            return {
+                ok: false,
+                code: 'session_locked',
+                message: `Session "${identity.sessionId}" is held by another run.`,
+            };
+        }
+        return {
+            ok: true,
+            record: {
+                threadId,
+                sessionId: identity.sessionId,
+                sessionFile: deps.sessionFileFor?.(identity.sessionId) ?? null,
+                state: 'opening',
+                source: createThreadSource({ threadId, gate: deps.gate }),
+                runtime: null,
+                pendingPrompts: [],
+                pendingControls: [],
+                lock,
+            },
+        };
+    };
+    /** Construct, open and start one admitted thread. Throws `ThreadOpenError` on failure. */
+    const start = async (record) => {
+        const runtime = deps.makeRuntime({
+            threadId: record.threadId,
+            sessionId: record.sessionId,
+            sessionFile: record.sessionFile,
+            lock: record.lock,
+            source: record.source,
+        });
+        record.runtime = runtime;
+        // RECORDED BEFORE THE FIRST `await`, so a caller that asks "is everything closed?" the
+        // moment this thread exists cannot miss it.
+        drains.push(runtime.drained());
+        await runtime.open();
+        record.state = 'open';
+        if (firstOpen) {
+            firstOpen = false;
+            // THE ONE CHANCE TO WRITE `system/init` BEFORE ANY THREAD EVENT.
+            deps.onFirstOpen?.();
+        }
+        runtime.announceOpened();
+        if (record.closeAfterOpen !== undefined) {
+            // A `thread_close` THAT ARRIVED WHILE THIS THREAD WAS STILL OPENING (section 2.3.4).
+            // Honouring it here - instead of after the queued prompts - is what makes the ack
+            // truthful: the caller was told "closing", so nothing may be served first.
+            record.state = 'closing';
+            runtime.requestClose(record.closeAfterOpen);
+            record.source.finish();
+        }
+        else {
+            for (const prompt of record.pendingPrompts.splice(0)) {
+                deliver(record, prompt.text, prompt.frameId);
+            }
+            for (const control of record.pendingControls.splice(0)) {
+                runtime.handleControl(control);
+            }
+        }
+        // THE RUN LOOP STARTS IN BOTH CASES, WHICH IS NOT A DETAIL: `requestClose` only ASKS a
+        // runtime to shut down, and `drained()` resolves from inside `run()`'s own `finally`
+        // (dispose, then the account, then the latch). Returning before this call left a thread
+        // that was closed while still opening stuck in `closing` forever, so `registry.drained()`
+        // never resolved and the process never wrote its `result` - a hang for one frame order,
+        // and the commonest one a host produces (a batch of frames written in one chunk).
+        void (async () => {
+            await runtime.run(record.source);
+            record.state = 'closed';
+            record.lock?.release();
+            record.lock = null;
+        })();
+        return runtime;
+    };
+    const handleOpen = (frame) => {
+        const existing = records.get(frame.threadId);
+        if (existing) {
+            if (existing.state === 'opening' || existing.state === 'open') {
+                refuse(frame.id, 'thread_exists', `Thread "${frame.threadId}" is already open.`, frame.threadId);
+                return;
+            }
+            if (existing.state === 'closing') {
+                refuse(frame.id, 'thread_closing', `Thread "${frame.threadId}" is closing.`, frame.threadId);
+                return;
+            }
+            // A CLOSED RECORD IS NOT REUSED: two conversations under one id would make two
+            // `thread_state{closed}` events share a name, and a caller could not tell its
+            // accounting apart.
+            refuse(frame.id, 'thread_exists', `Thread "${frame.threadId}" was already used in this run; choose another id.`, frame.threadId);
+            return;
+        }
+        const admitted = admit(frame.threadId, frame.sessionId);
+        if (!admitted.ok) {
+            refuse(frame.id, admitted.code, admitted.message, frame.threadId);
+            return;
+        }
+        const record = admitted.record;
+        records.set(record.threadId, record);
+        order.push(record.threadId);
+        void (async () => {
+            try {
+                await start(record);
+                ack(frame.id, {
+                    threadId: record.threadId,
+                    accepted: true,
+                    sessionId: record.sessionId,
+                    sessionFile: record.sessionFile,
+                    resumed: false,
+                });
+            }
+            catch (error) {
+                record.state = 'closed';
+                record.lock?.release();
+                record.lock = null;
+                refuse(frame.id, error instanceof ThreadOpenError ? error.code : 'thread_open_failed', error instanceof Error ? error.message : 'The thread could not be opened.', record.threadId);
+            }
+        })();
+    };
+    const handleClose = (frame) => {
+        const record = records.get(frame.threadId);
+        if (!record) {
+            refuse(frame.id, 'unknown_thread', `Thread "${frame.threadId}" is not open.`, frame.threadId);
+            return;
+        }
+        if (record.state === 'closing') {
+            ack(frame.id, { threadId: frame.threadId, accepted: true, code: 'already_closing' });
+            return;
+        }
+        if (record.state === 'closed') {
+            refuse(frame.id, 'unknown_thread', `Thread "${frame.threadId}" is already closed.`, frame.threadId);
+            return;
+        }
+        if (record.state === 'opening' && record.closeAfterOpen !== undefined) {
+            // A SECOND CLOSE FOR A THREAD THAT IS STILL OPENING IS STILL A SECOND CLOSE (AC-33).
+            // The intent is already parked, so the answer is the same idempotent receipt the
+            // `closing` state gives - otherwise the caller cannot tell "recorded" from "ignored"
+            // in the one window where nothing has been announced yet.
+            ack(frame.id, { threadId: frame.threadId, accepted: true, code: 'already_closing' });
+            return;
+        }
+        ack(frame.id, { threadId: frame.threadId, accepted: true });
+        // THE RECORD MOVES TO `closing` HERE, not when the runtime finishes: everything that
+        // arrives between this frame and the last `request_end` must be answered
+        // `thread_closing` rather than accepted into a conversation that is ending.
+        if (record.state === 'opening') {
+            // NOT YET OPEN: park the intent and let `start()` act on it the moment the thread is
+            // usable, so a queued prompt is never served after the caller asked to close.
+            record.closeAfterOpen = frame.mode ?? 'settle';
+            return;
+        }
+        record.state = 'closing';
+        // THE SOURCE ENDS IN BOTH MODES: `settle` lets the request in flight finish and then
+        // ends the loop; `abort` cancels it and ends the loop now. Either way the thread reaches
+        // `closed` without waiting for a prompt that will never arrive.
+        record.runtime?.requestClose(frame.mode ?? 'settle');
+        record.source.finish();
+    };
+    const summaries = () => order.map((id) => {
+        const record = records.get(id);
+        if (!record) {
+            return {
+                threadId: id,
+                sessionId: '',
+                state: 'closed',
+                requests: 0,
+                turns: 0,
+                inFlight: false,
+            };
+        }
+        const summary = record.runtime?.summarize();
+        return summary
+            ? { ...summary, state: record.state }
+            : {
+                threadId: record.threadId,
+                sessionId: record.sessionId,
+                state: record.state,
+                requests: 0,
+                turns: 0,
+                inFlight: false,
+            };
+    });
+    const accounts = () => order
+        .map((id) => records.get(id)?.runtime?.account())
+        .filter((account) => account !== undefined);
+    /**
+     * Resolve once every thread that was ever opened has closed.
+     *
+     * WAITED IN WAVES, so a thread opened WHILE we were waiting is waited for too: each pass
+     * awaits only the runtimes that appeared since the previous one, and the loop exits when
+     * nothing new arrived - the only moment "every opened thread is closed" is really true.
+     */
+    const waitForDrains = async () => {
+        let awaited = 0;
+        for (;;) {
+            if (drains.length <= awaited)
+                return;
+            const next = drains.slice(awaited);
+            awaited = drains.length;
+            await Promise.all(next);
+        }
+    };
+    const closeAll = async (reason) => {
+        for (const record of records.values()) {
+            if (record.state === 'closed')
+                continue;
+            record.source.finish();
+            record.runtime?.requestClose(reason === 'aborted' ? 'abort' : 'settle');
+        }
+        // ONE WAIT PATH: the same waves `drained` uses, so a thread opened while closing is not cut
+        // off by this call either.
+        await waitForDrains();
+        return accounts();
+    };
+    return {
+        async openDefault() {
+            const admitted = admit(DEFAULT_THREAD_ID, undefined);
+            if (!admitted.ok) {
+                throw new ThreadOpenError(admitted.code === 'session_locked' ? 'session_locked' : 'thread_open_failed', admitted.message);
+            }
+            records.set(admitted.record.threadId, admitted.record);
+            order.push(admitted.record.threadId);
+            await start(admitted.record);
+        },
+        handleOpen,
+        handleClose,
+        handleList: (frame) => ack(frame.id, { accepted: true, threads: summaries() }),
+        deliverPrompt(threadId, text, frameId) {
+            const record = records.get(threadId);
+            if (!record || record.state === 'closed') {
+                refuse(frameId, 'unknown_thread', `Thread "${threadId}" is not open; send thread_open first.`, threadId);
+                deps.write({
+                    type: 'error',
+                    sessionId: deps.baseSessionId,
+                    threadId,
+                    fatal: false,
+                    code: 'unknown_thread',
+                    message: `A prompt named thread "${threadId}", which is not open.`,
+                });
+                return;
+            }
+            if (record.state === 'closing') {
+                refuse(frameId, 'thread_closing', `Thread "${threadId}" is closing; no new prompt is accepted.`, threadId);
+                return;
+            }
+            // THE LEAK GUARD IS A CEILING, NOT A NUMBER IN A TABLE (P2-4). A thread that has served
+            // `maxRequestsPerThread` requests is being used as a queue and should be closed and
+            // reopened; letting it refill forever would make one `result.threads.items` entry
+            // unbounded. Checked BEFORE the prompt is queued, so the caller gets a receipt.
+            const served = record.runtime?.summarize().requests ?? 0;
+            if (!withinRequestCap(served)) {
+                refuse(frameId, 'thread_capacity', `Thread "${threadId}" has served ${served} requests, its ceiling; ` +
+                    'close it and open another.', threadId);
+                return;
+            }
+            if (record.state === 'opening') {
+                record.pendingPrompts.push({ text, frameId });
+                return;
+            }
+            deliver(record, text, frameId);
+        },
+        deliverControl(threadId, frame) {
+            const record = records.get(threadId);
+            if (!record || record.state === 'closed') {
+                deps.write({
+                    type: 'error',
+                    sessionId: deps.baseSessionId,
+                    threadId,
+                    fatal: false,
+                    code: 'unknown_thread',
+                    message: `A "${frame.type}" frame named thread "${threadId}", which is not open.`,
+                });
+                return;
+            }
+            if (record.state === 'opening') {
+                record.pendingControls.push(frame);
+                return;
+            }
+            record.runtime?.handleControl(frame);
+        },
+        serverFor: (threadId) => records.get(threadId)?.runtime?.server() ?? undefined,
+        runtimeFor: (threadId) => records.get(threadId)?.runtime ?? undefined,
+        ids: () => [...order],
+        summaries,
+        rejectThreadedInterrupt(threadId, frameId) {
+            ack(frameId, {
+                threadId,
+                accepted: false,
+                code: 'interrupt_is_process_level',
+                message: 'interrupt stops the whole run. Use cancel_request{threadId} to stop one request.',
+            });
+        },
+        finishAll() {
+            for (const record of records.values())
+                record.source.finish();
+        },
+        drained: waitForDrains,
+        closeAll,
+        interruptAll(signo) {
+            for (const record of records.values()) {
+                if (record.state === 'closed')
+                    continue;
+                record.runtime?.interrupt();
+            }
+            // NO MORE WORK IS SERVED AFTER A PROCESS INTERRUPT (see the header).
+            for (const record of records.values())
+                record.source.finish();
+            void signo;
+        },
+        timeoutAll() {
+            for (const record of records.values()) {
+                if (record.state === 'closed')
+                    continue;
+                record.runtime?.timeout();
+            }
+            for (const record of records.values())
+                record.source.finish();
+        },
+        accounts,
+        openCount: activeCount,
+    };
+}
+export { DEFAULT_THREAD_ID };

package/dist/exec/threads/runtime.d.ts

@@ -0,0 +1,107 @@
+import type { AgentController } from '../../agent/controller.js';
+import type { CliFlags } from '../../config/load.js';
+import type { ExecEmitter } from '../emitter.js';
+import type { ExecOptions } from '../options.js';
+import { type BridgeServer } from '../bridge/server.js';
+import type { BridgeWriter } from '../bridge/writer.js';
+import { type BridgeInputFrame } from '../bridge/protocol.js';
+import { type HookRuntime } from '../hooks/index.js';
+import type { ResultSchemaSpec } from '../result/schema.js';
+import type { SessionLockHandle } from '../../session/store.js';
+import type { ExecControllerFactory } from '../index.js';
+import type { ThreadAccount } from './aggregate.js';
+import type { ThreadPromptSource, ThreadSource } from './thread-source.js';
+import type { ThreadSummary } from './registry.js';
+export type ThreadOpenCode = 'thread_id_invalid' | 'session_locked' | 'thread_limit' | 'thread_open_failed';
+export declare class ThreadOpenError extends Error {
+    readonly code: ThreadOpenCode;
+    constructor(code: ThreadOpenCode, message: string);
+}
+export interface ThreadPersistInput {
+    sessionId: string;
+    controller: AgentController;
+    turns: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    at: number;
+}
+export interface ThreadRuntimeDeps {
+    threadId: string;
+    sessionId: string;
+    /** `null` under `--no-save-session`. */
+    sessionFile: string | null;
+    flags: CliFlags;
+    options: ExecOptions;
+    version: string;
+    makeController: ExecControllerFactory;
+    emitter: ExecEmitter;
+    writer: BridgeWriter;
+    now: () => number;
+    resultSpec: ResultSchemaSpec | null;
+    /** The session lock, already taken by the registry, or `null` when nothing is saved. */
+    lock: SessionLockHandle | null;
+    /** Writes this thread's session file; supplied by `execute-threads`. */
+    persist: (input: ThreadPersistInput) => void;
+    /** `THREAD_LIMITS`-clamped `--hook-timeout`. */
+    hookTimeoutMs: number;
+    /**
+     * THIS THREAD'S OWN PROMPT QUEUE, and the object that owns its admission slot.
+     *
+     * A DEPENDENCY RATHER THAN AN ARGUMENT OF `run()` because the runner must be handed the
+     * bridge channel in `open()` - one step BEFORE `run()` is ever called (section 2.3.4,
+     * step 5). `runner.attachBridge(server, source)` is what installs the server's turn ports
+     * (`steer`, `interrupt{requestId}`, `cancel_request`) and what makes the runner's
+     * `bridge` field non-null, i.e. what makes a prompt get its `ack{accepted:true,
+     * requestSeq}` and a turn get its `request_end`. Omitting it is silent: the run serves
+     * every prompt and writes no receipt at all, which is the v1 regression (I-C4) section
+     * 2.3.3 spends a page preventing.
+     *
+     * THE SLOT IS RELEASED THROUGH THIS OBJECT TOO. `holding` lives inside the source, so
+     * freeing the gate from anywhere else leaves it set - see `onRequestSettled` below.
+     */
+    source: ThreadSource;
+}
+export interface ThreadRuntime {
+    readonly threadId: string;
+    readonly sessionId: string;
+    readonly sessionFile: string | null;
+    state(): 'opening' | 'open' | 'closing' | 'closed';
+    open(): Promise<void>;
+    /** Drive this thread's conversation until its source is finished. */
+    run(source: ThreadPromptSource): Promise<void>;
+    /** Begin shutting down; `drained()` resolves when it is finished. */
+    requestClose(mode: 'settle' | 'abort'): void;
+    /** Resolves once this thread is `closed` and its account is final. */
+    drained(): Promise<void>;
+    /** Process-level interrupt fan-out (section 2.3.8a). */
+    interrupt(): void;
+    /** Process-level timeout fan-out (section 2.3.8b). */
+    timeout(): void;
+    summarize(): ThreadSummary;
+    account(): ThreadAccount;
+    /** The hook table, so the router can answer `hook_answer` and `thread_list`. */
+    hooks(): HookRuntime | null;
+    /** Emit `thread_state{phase:'opened'}`. Called once, after `system/init`. */
+    announceOpened(): void;
+    /** The facts `system/init` needs from this thread's controller. */
+    describe(): {
+        model: {
+            provider: string;
+            id: string;
+            baseUrl: string | null;
+        };
+        cwd: string;
+        tools: string[];
+        sessionId: string;
+        sessionFile: string | null;
+    };
+    /** Route one control frame to this thread's own bridge server. */
+    handleControl(frame: BridgeInputFrame): void;
+    /** This thread's server, for `registry.serverFor` and for tests. */
+    server(): BridgeServer | null;
+    /** Apply a `tool_register` that arrived while this thread was still opening. */
+    flushCallerTools(): void;
+}
+export declare function createThreadRuntime(deps: ThreadRuntimeDeps): ThreadRuntime;