allaboard 0.0.0-stage → 0.5.0

package/dist/agent/claude/module.js

@@ -0,0 +1,82 @@
+/** The Claude back end as the registry holds it: the entry `claude`. */
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
+import { AgentConfigError } from "../seam.js";
+import { ClaudeBackend } from "./backend.js";
+// Claude Code's own variables the owner may set in the daemon's file; each reaches a thread's
+// session as written, and Claude Code judges its value. `BASH_DEFAULT_TIMEOUT_MS`, in
+// milliseconds, is how long a command may run: above 30 minutes it also replaces the limit a
+// session of the SDK puts on a command in the background, which a terminal session does not
+// have (tools reference, "Time limit for background commands", read 2026-10-13).
+// `CLAUDE_CONFIG_DIR` is the folder of a login of its own, for an instance that drives a second
+// Claude Code account (environment variables page, "useful for running multiple accounts side by
+// side", read 2026-10-17); it is handled below, since the daemon reads the folder too.
+export const VARIABLES = ["BASH_DEFAULT_TIMEOUT_MS", "CLAUDE_CONFIG_DIR"];
+/**
+ * The declared variables the owner's file sets, each read by its name: the daemon hands a module
+ * its variables readable by lookup and shown by nothing, so a spread of them copies none.
+ */
+function set(variables) {
+    const found = {};
+    for (const name of VARIABLES) {
+        const value = variables[name];
+        if (value !== undefined)
+            found[name] = value;
+    }
+    return found;
+}
+/**
+ * The folder the owner's file names, else the one the daemon's environment holds (an empty one is
+ * none), `~` read as the home and `${HOME}` already expanded by the daemon; undefined when neither
+ * names one. Refused unless absolute: a relative path would read from the working directory, the
+ * terminal's folder in one run and `/` under launchd. The value is passed on as written once the
+ * tilde is read: Claude Code keys the Keychain entry of a login by the folder's string, so a
+ * trailing slash is another entry. (The core's `expandUser` is not importable from an agent
+ * module, so the tilde is read here.)
+ */
+function configDirOf(written, home) {
+    const inherited = written === undefined ? process.env.CLAUDE_CONFIG_DIR || undefined : undefined;
+    const value = written ?? inherited;
+    if (value === undefined)
+        return undefined;
+    // Concatenated, not joined: `join` would rewrite `~/./work` or a doubled slash, and the Keychain
+    // entry follows the string.
+    const expanded = value === "~" || value.startsWith("~/") ? home + value.slice(1) : value;
+    if (!isAbsolute(expanded)) {
+        const where = inherited === undefined ? "" : ", set in the daemon's environment and not in .env,";
+        throw new AgentConfigError(`CLAUDE_CONFIG_DIR${where} must be an absolute path, or one starting with ~/; it is "${value}"`);
+    }
+    return expanded;
+}
+/**
+ * The entry that builds the Claude back end. `options` are what a test replaces: the SDK's
+ * query, the owner's home, the usage probe's start.
+ */
+export function claudeAgent(options = {}) {
+    return {
+        required: [],
+        optional: VARIABLES,
+        build: (context) => {
+            const variables = set(context.variables);
+            const configDir = configDirOf(variables.CLAUDE_CONFIG_DIR, options.home ?? homedir());
+            if (configDir !== undefined) {
+                variables.CLAUDE_CONFIG_DIR = configDir;
+                // The SDK's `listSessions`, which the back end calls in the daemon's own process, has no
+                // option for the folder (`ListSessionsOptions`, sdk.d.ts 0.3.301) and reads
+                // `process.env.CLAUDE_CONFIG_DIR` (bundled sdk.mjs, not documented): without this, it
+                // would look in the default login's folder, and `!resume` and the Home tab's session
+                // list would come up empty. (The cleanup reads the back end's own projects folder and
+                // is not affected.) It is written once, at build. The usage probe's bare session passes
+                // no `env`, so the SDK gives it this environment, and the limits it reads are those of
+                // this login.
+                process.env.CLAUDE_CONFIG_DIR = configDir;
+            }
+            return new ClaudeBackend({
+                clock: context.clock,
+                variables,
+                ...(configDir !== undefined && { configDir }),
+                ...options,
+            });
+        },
+    };
+}

package/dist/agent/claude/prompt.js

@@ -0,0 +1,24 @@
+function contentOf(prompt) {
+    if (typeof prompt.content === "string")
+        return prompt.content;
+    return prompt.content.map((part) => {
+        if (part.type === "text")
+            return { type: "text", text: part.text };
+        // The core admits the image types Claude takes and no other (`attachments.IMAGE_TYPES`),
+        // so the seam's plain string is one of the SDK's four here.
+        const media_type = part.mediaType;
+        return { type: "image", source: { type: "base64", media_type, data: part.data } };
+    });
+}
+/**
+ * `prompt` as the one user message of a turn, under its id: the message the SDK itself builds
+ * for a string, plus the uuid. The id is a UUID the core made.
+ */
+export function userMessage(prompt) {
+    return {
+        type: "user",
+        message: { role: "user", content: contentOf(prompt) },
+        parent_tool_use_id: null,
+        uuid: prompt.id,
+    };
+}

package/dist/agent/claude/record.js

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+/**
+ * Claude Code's record of the owner, `.claude.json`: in the folder `CLAUDE_CONFIG_DIR` names when
+ * the login has its own (measured 2026-10-17, CLI 2.1.301: with the variable set, the file is
+ * written inside that folder), else in the home.
+ */
+export function recordPath(home, configDir) {
+    return join(configDir ?? home, ".claude.json");
+}

package/dist/agent/claude/requests.js

@@ -0,0 +1,122 @@
+import { isRecord } from "../../values.js";
+import { string, words } from "./wire.js";
+export const QUESTION_TOOL = "AskUserQuestion";
+function optionOf(value) {
+    if (!isRecord(value))
+        return null;
+    const label = string(value.label);
+    if (label === null)
+        return null;
+    return { label, description: words(value.description), preview: words(value.preview) };
+}
+function questionOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.options))
+        return null;
+    const text = string(value.question);
+    if (text === null)
+        return null;
+    const options = [];
+    for (const entry of value.options) {
+        const option = optionOf(entry);
+        if (option === null)
+            return null;
+        options.push(option);
+    }
+    return {
+        header: string(value.header) ?? "",
+        text,
+        multiSelect: value.multiSelect === true,
+        options,
+    };
+}
+/**
+ * The questions of an `AskUserQuestion` input, or null when it holds none or one the form
+ * cannot show (a shape other than the measured one): the call then asks as any other tool.
+ */
+function questionsOf(input) {
+    if (!Array.isArray(input.questions) || input.questions.length === 0)
+        return null;
+    const questions = [];
+    for (const entry of input.questions) {
+        const question = questionOf(entry);
+        if (question === null)
+            return null;
+        questions.push(question);
+    }
+    return questions;
+}
+/** One call of the permission callback as the request the core shows. */
+export function toRequest(toolName, input, context) {
+    const callId = words(context.toolUseID);
+    const questions = toolName === QUESTION_TOOL ? questionsOf(input) : null;
+    if (questions !== null) {
+        return {
+            type: "question",
+            callId,
+            toolName,
+            title: words(context.title),
+            questions,
+        };
+    }
+    return {
+        type: "permission",
+        callId,
+        toolName,
+        input,
+        title: words(context.title),
+        description: words(context.description),
+    };
+}
+/** The owner's answer to a permission request for a call that had `input`. */
+export function permissionResult(answer, input) {
+    if (!answer.allow)
+        return { behavior: "deny", message: answer.message };
+    return { behavior: "allow", updatedInput: { ...input } };
+}
+/**
+ * The annotations of an answer, keyed by question text (`sdk-tools.d.ts` 0.3.301). The terminal
+ * sends the preview of the option picked with a single-select answer, and the model reads it
+ * back as `selected preview:` (measured 2026-10-16); an answer typed under Other matches no
+ * option and carries none.
+ */
+function annotationsOf(answer, questions) {
+    const found = {};
+    for (const entry of questions) {
+        const question = questionOf(entry);
+        if (question === null)
+            continue;
+        const annotation = {};
+        const note = Object.hasOwn(answer.notes, question.text) ? answer.notes[question.text] : "";
+        if (note)
+            annotation.notes = note;
+        const given = Object.hasOwn(answer.answers, question.text)
+            ? answer.answers[question.text]
+            : null;
+        if (typeof given === "string" && !question.multiSelect) {
+            const preview = question.options.find((option) => option.label === given)?.preview;
+            if (preview)
+                annotation.preview = preview;
+        }
+        if (Object.keys(annotation).length > 0)
+            found[question.text] = annotation;
+    }
+    return found;
+}
+/**
+ * The owner's answer to a question whose call had `input`: the questions as Claude Code wrote
+ * them, with the answer of each under its text, and the annotations when there are any.
+ */
+export function questionResult(answer, input) {
+    if (!answer.answered)
+        return { behavior: "deny", message: answer.message };
+    const questions = Array.isArray(input.questions) ? input.questions : [];
+    const annotations = annotationsOf(answer, questions);
+    return {
+        behavior: "allow",
+        updatedInput: {
+            questions,
+            answers: answer.answers,
+            ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+        },
+    };
+}

package/dist/agent/claude/session.js

@@ -0,0 +1,441 @@
+/**
+ * One Claude Code session over a single `query()` with streaming input.
+ *
+ * The SDK's `query()` starts one Claude Code process. Prompts reach it through an async iterable
+ * the session keeps open, so a prompt can be sent at any moment, in the middle of a turn too
+ * (`replay-user-messages` makes Claude Code say which prompts it took). Everything the process
+ * says comes back as the records of the query's stream, which a `Translator` turns into the
+ * seam's events, and as the calls of the permission callback and of the two hooks the daemon
+ * registers. A task of its own (`#pump`) reads that stream.
+ */
+import { randomUUID } from "node:crypto";
+import { query as sdkQuery, } from "@anthropic-ai/claude-agent-sdk";
+import { getLogger } from "../../log.js";
+import { errorName, isRecord } from "../../values.js";
+import { ResumeRefused, } from "../seam.js";
+import { CAPABILITIES } from "./capabilities.js";
+import { postModelSwitchHookEvents, postToolUseHookEvents, stopHookEvents } from "./hooks.js";
+import { agentInfo, contextUsage as contextUsageOf } from "./info.js";
+import { userMessage } from "./prompt.js";
+import { permissionResult, questionResult, toRequest } from "./requests.js";
+import { Translator } from "./translate.js";
+export const logger = getLogger("allaboard.agent.claude.session");
+// The reason given when the stream ends without an exception.
+const PROCESS_EXITED = "the Claude Code process exited";
+// How the SDK says the process ended, and the name each way is given (issue #238). It throws a
+// plain `Error` for these, with no class and no code to tell them by, and its troubleshooting
+// page says to match on the message (code.claude.com/docs/en/agent-sdk/troubleshooting, read
+// 2026-10-11): a nonzero exit, a signal, and an error result the CLI reported before it exited.
+// Only the start of the message is read; what follows is the CLI's own words.
+const LOST_PROCESS = [
+    ["Claude Code process exited with code ", "ProcessExited"],
+    ["Claude Code process terminated by signal ", "ProcessKilled"],
+    ["Claude Code returned an error result: ", "ErrorResult"],
+];
+/**
+ * The name of a failure of the SDK: `errorName`, except for an error that names itself no more
+ * than `Error` and whose message starts as one of `LOST_PROCESS`.
+ */
+function lostName(error) {
+    const name = errorName(error);
+    if (name !== "Error" || !(error instanceof Error))
+        return name;
+    return LOST_PROCESS.find(([start]) => error.message.startsWith(start))?.[1] ?? name;
+}
+/** A Claude Code process that ended, named for how it did; the SDK's own error is its cause. */
+export class ProcessLostError extends Error {
+    constructor(name, cause) {
+        super("the Claude Code process ended", { cause });
+        this.name = name;
+    }
+}
+/** `error` as it leaves this class: under its name when it says the process ended, else itself. */
+function underItsName(error) {
+    const name = lostName(error);
+    return name === errorName(error) ? error : new ProcessLostError(name, error);
+}
+// What a call is told when nobody could be asked about it. This layer does not import
+// `src/core/`, so the core's own text for it (`APPROVAL_UNPOSTED`) is not reused, and it knows
+// no chat, so it names none.
+const REQUEST_UNSHOWN = "allaboard could not show this request to the owner, so nobody approved it.";
+/** A session was used after it ended: closed, or its process lost. */
+export class SessionClosedError extends Error {
+    name = "SessionClosedError";
+    constructor() {
+        super("the Claude Code session is closed");
+    }
+}
+/**
+ * An unbounded queue read as an async iterable by one consumer. `end` lets what was pushed be
+ * read first, then finishes; a `return` from the consumer (a `break`) leaves the queue as it is.
+ */
+export class AsyncQueue {
+    #items = [];
+    #ended = false;
+    #wake = null;
+    push(item) {
+        if (this.#ended)
+            return;
+        this.#items.push(item);
+        this.#signal();
+    }
+    end() {
+        this.#ended = true;
+        this.#signal();
+    }
+    #signal() {
+        const wake = this.#wake;
+        this.#wake = null;
+        wake?.();
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                while (this.#items.length === 0 && !this.#ended) {
+                    await new Promise((resolve) => {
+                        this.#wake = resolve;
+                    });
+                }
+                const item = this.#items.shift();
+                if (item === undefined)
+                    return { done: true, value: undefined };
+                return { done: false, value: item };
+            },
+            return: async () => ({ done: true, value: undefined }),
+        };
+    }
+}
+// The modes Claude Code takes (`PermissionMode` of the SDK). More than the three roles
+// `CAPABILITIES` declares: the core hands back the mode a session started in, which the owner's
+// own settings choose (`acceptEdits`, `plan`, `dontAsk`), when a bypass is switched off.
+const PERMISSION_MODES = new Set([
+    "default",
+    "acceptEdits",
+    "bypassPermissions",
+    "plan",
+    "dontAsk",
+    "auto",
+]);
+// Claude Code's own system prompt, which a terminal session works under. With no `systemPrompt`
+// the SDK sends a minimal one, "that covers tool calling but omits the rest of the `claude_code`
+// preset's content" (Modifying system prompts, read 2026-10-13): 679 characters against about
+// 10,000, measured the same day on the first request of both (Claude Code 2.1.296, issue #300).
+// Claude Code records the prompt on a session's first request and reuses it until a compaction.
+const SYSTEM_PROMPT = { type: "preset", preset: "claude_code" };
+// What an interactive session has by default and a session of the SDK does not (sub-agents and
+// environment variables pages, read 2026-10-13). Fork mode: every subagent runs in the
+// background and the Agent tool loses `run_in_background`; off, Claude picks foreground or
+// background, and picked each once in two identical runs. The refill of a session's web
+// searches: 100 an hour in the terminal, none otherwise.
+const TERMINAL_DEFAULTS = {
+    CLAUDE_CODE_FORK_SUBAGENT: "1",
+    CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR: "100",
+};
+// What the daemon asks a session to say on its stream (environment variables page, read
+// 2026-10-14): `session_state_changed` records, which carry whether Claude Code is running,
+// idle or waiting for an answer. Off by default, in the terminal too.
+const SESSION_SIGNALS = {
+    CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+};
+// A level outside what `CAPABILITIES` declares, or a mode Claude Code does not take, is refused
+// (the seam's contract).
+function effortOf(level) {
+    if (!CAPABILITIES.effortLevels.includes(level)) {
+        throw new RangeError(`unknown effort level: ${level}`);
+    }
+    return level;
+}
+function modeOf(mode) {
+    if (!PERMISSION_MODES.has(mode))
+        throw new RangeError(`unknown permission mode: ${mode}`);
+    return mode;
+}
+export class ClaudeSession {
+    events;
+    #config;
+    #translator = new Translator();
+    #queue = new AsyncQueue();
+    #input = new AsyncQueue();
+    #query;
+    #finished;
+    #closing = false;
+    #ended = false;
+    #started = false;
+    #command = null;
+    // An error result arrived before the process answered the start: a resume it refused.
+    #startRefused = false;
+    /** Spawns the Claude Code process: `ready` says when it answered. */
+    constructor(config, requests, queryFunction = sdkQuery) {
+        this.#config = config;
+        this.events = this.#queue;
+        this.#query = queryFunction({
+            prompt: this.#input,
+            options: this.#options(requests),
+        });
+        this.#finished = this.#pump();
+    }
+    #options(requests) {
+        const { folder, resume, model, effort, chrome, bare, variables } = this.#config;
+        // Makes bypass possible, not active: `setPermissionMode` switches it on the live session.
+        // `replay-user-messages` (CLI reference): Claude Code re-emits each prompt with the uuid the
+        // daemon sent it under, which tells a prompt it took into a running turn from one that waits
+        // for a turn of its own. The owner's "Enabled by default" reaches an interactive session
+        // only: here `--chrome` is what connects Claude Code's Chrome integration.
+        const extraArgs = { "replay-user-messages": null };
+        if (chrome)
+            extraArgs.chrome = null;
+        return {
+            cwd: folder,
+            ...(resume !== null && { resume }),
+            // The effort `/effort` set does not survive a resume (measured 2026-09-28), so the daemon
+            // keeps it per thread and passes it back here.
+            ...(effort !== null && { effort: effortOf(effort) }),
+            ...(model !== null && { model }),
+            settingSources: [...this.#config.settingsSources],
+            includePartialMessages: true,
+            ...(!bare && {
+                allowDangerouslySkipPermissions: true,
+                systemPrompt: SYSTEM_PROMPT,
+                // `env` replaces the environment the process would inherit, so the daemon's own is
+                // passed on: over the terminal's defaults, and under what the owner's file sets. What
+                // the daemon reads from the stream is not the owner's to turn off.
+                env: { ...TERMINAL_DEFAULTS, ...process.env, ...variables, ...SESSION_SIGNALS },
+            }),
+            extraArgs,
+            canUseTool: async (toolName, input, context) => {
+                // A callback that rejects is answered with a `control_response` of subtype `error`
+                // (`handleControlRequest`, SDK 0.3.296), which is not a deny. A request nobody could be
+                // asked about is refused here, and only the error's name is kept: its message may quote
+                // the tool's input.
+                try {
+                    const request = toRequest(toolName, input, context);
+                    if (request.type === "question") {
+                        return questionResult(await requests.question(request, context.signal), input);
+                    }
+                    return permissionResult(await requests.permission(request, context.signal), input);
+                }
+                catch (error) {
+                    logger.error(`could not ask the owner about a call: ${errorName(error)}`);
+                    return { behavior: "deny", message: REQUEST_UNSHOWN };
+                }
+            },
+            // The Stop hook's input carries the effort level Claude Code runs at: the footer's only
+            // source for it, since no message reports it. Every hook input carries the `cwd` the
+            // session works in; PostToolUse reports it after each tool, so a turn stopped or failed
+            // before its Stop still moves the footer's branch. PostModelSwitch names the model a
+            // `/model` command switched to, before the command's result: the context usage still
+            // names the old one after a command.
+            hooks: {
+                Stop: [{ hooks: [this.#hook(stopHookEvents)] }],
+                PostToolUse: [{ hooks: [this.#hook(postToolUseHookEvents)] }],
+                PostModelSwitch: [{ hooks: [this.#hook(postModelSwitchHookEvents)] }],
+            },
+            // The process's stderr may quote the conversation: only its size is kept.
+            stderr: (line) => logger.debug(`claude stderr: ${line.length} chars`),
+        };
+    }
+    #hook(events) {
+        return async (input) => {
+            // A hook of the hidden command's turn (Stop, PostToolUse) is as much the command's as its
+            // records: nothing of it reaches the core.
+            if (this.#command !== null)
+                return {};
+            for (const event of events(input))
+                this.#queue.push(event);
+            return {};
+        };
+    }
+    /**
+     * Reads a record of the hidden model command: none reaches the core. The `result` settles the
+     * wait. The command's own `completed` settles it too (a no-op after the result) and ends the
+     * hiding; so does its own `cancelled`, the other terminal state `sdk.d.ts` documents (0.3.301,
+     * the comment of `cancel_queued`: "a terminal 'cancelled' lifecycle"), which fails a caller that had no result.
+     */
+    #readCommand(command, record) {
+        if (!isRecord(record))
+            return;
+        if (record.type === "result")
+            command.settle();
+        if (record.type !== "command_lifecycle" || record.command_uuid !== command.id)
+            return;
+        if (record.state === "completed") {
+            command.settle();
+            this.#command = null;
+        }
+        else if (record.state === "cancelled") {
+            command.settle(new Error("the model command was cancelled"));
+            this.#command = null;
+        }
+    }
+    /** Reads the query's stream until it ends, whatever ends it; never rejects. */
+    async #pump() {
+        let reason = PROCESS_EXITED;
+        try {
+            for await (const record of this.#query) {
+                if (!this.#started && isRecord(record) && record.type === "result") {
+                    this.#startRefused = record.is_error === true;
+                }
+                if (this.#command !== null) {
+                    this.#readCommand(this.#command, record);
+                    continue;
+                }
+                try {
+                    for (const event of this.#translator.translate(record))
+                        this.#queue.push(event);
+                }
+                catch (error) {
+                    // One record that fails to read must not end the session.
+                    logger.error(`could not read a record: ${errorName(error)}`);
+                }
+            }
+        }
+        catch (error) {
+            reason = lostName(error);
+        }
+        this.#ended = true;
+        this.#command?.settle(new SessionClosedError());
+        if (!this.#closing) {
+            logger.error(`session stopped: ${reason}`);
+            this.#queue.push({ type: "process_lost", reason });
+        }
+        this.#queue.end();
+        // The process may still be running (a stream that failed): reap it.
+        try {
+            this.#query.close();
+        }
+        catch (error) {
+            logger.error(`could not close the process: ${errorName(error)}`);
+        }
+    }
+    /**
+     * Resolves once Claude Code answered the start. Rejects with `ResumeRefused` when it refused to
+     * resume the stored session, and with the failure itself otherwise; the session is closed then.
+     */
+    async ready() {
+        try {
+            await this.#query.initializationResult();
+            this.#started = true;
+        }
+        catch (error) {
+            // The stream is read to its end first: the error result it carries tells a refused resume
+            // from a process that failed to start.
+            await this.close();
+            if (this.#config.resume !== null && this.#startRefused)
+                throw new ResumeRefused({ cause: error });
+            throw underItsName(error);
+        }
+    }
+    /**
+     * Asks the query. The SDK rejects a request with the error that ended the process, when it
+     * did: that one leaves under its name, as the stream's own end does.
+     */
+    async #ask(request) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            throw underItsName(error);
+        }
+    }
+    async send(prompt) {
+        if (this.#closing || this.#ended)
+            throw new SessionClosedError();
+        // Before the push: the replay can come back before this call returns.
+        this.#translator.promptSent(prompt.id);
+        this.#input.push(userMessage(prompt));
+    }
+    async interrupt() {
+        // An interrupt while the model command runs rejects `setModel` and closes the session (the
+        // seam's contract): what the command's turn would still write is never read for a state.
+        const command = this.#command;
+        if (command !== null && !command.settled) {
+            command.settle(new Error("the model command was interrupted"));
+            await this.close();
+            return;
+        }
+        await this.#ask(() => this.#query.interrupt());
+    }
+    async stopTask(taskId) {
+        await this.#ask(() => this.#query.stopTask(taskId));
+    }
+    async setPermissionMode(mode) {
+        await this.#ask(() => this.#query.setPermissionMode(modeOf(mode)));
+    }
+    /**
+     * Runs Claude Code's own `/model` on the idle session and resolves once its turn is over; the
+     * turn is read here and no event of it reaches the core. The SDK's `setModel` is not used: it
+     * leaves an override that a later `/model` to the default model's alias does not undo
+     * (measured 2026-10-16, SDK 0.3.301, issue #333). A model the initialization result does not
+     * list is refused, since Claude Code answers an unknown one as a success.
+     */
+    async setModel(model) {
+        if (this.#closing || this.#ended)
+            throw new SessionClosedError();
+        if (model !== null && !(await this.info()).models.some((entry) => entry.value === model)) {
+            throw new RangeError(`unknown model: ${model}`);
+        }
+        // The session may have ended during the await above, and `#pump` found no command to end.
+        if (this.#closing || this.#ended)
+            throw new SessionClosedError();
+        // The guard and the marker follow each other with no await between them: two callers cannot
+        // both pass. A second command is refused, not queued: the setup lock already serializes its
+        // one caller, so a second is a defect. The hidden tail of one that has settled does not count.
+        if (this.#command !== null && !this.#command.settled) {
+            throw new Error("a model command is already running");
+        }
+        const id = randomUUID();
+        const done = new Promise((resolve, reject) => {
+            const command = {
+                id,
+                settled: false,
+                settle: (error) => {
+                    if (command.settled)
+                        return;
+                    command.settled = true;
+                    if (error === undefined)
+                        resolve();
+                    else
+                        reject(error);
+                },
+            };
+            this.#command = command;
+        });
+        this.#input.push(userMessage({ id, content: `/model ${model ?? "default"}` }));
+        await done;
+    }
+    /**
+     * Live, with no reconnect (`applyFlagSettings`, SDK 0.3.296): 36 ms in the spike's measurement,
+     * 28 ms in the back end's own live check, both on 2026-10-10.
+     */
+    async setEffort(level) {
+        const effortLevel = level === null ? null : effortOf(level);
+        await this.#ask(() => this.#query.applyFlagSettings({ effortLevel }));
+    }
+    async contextUsage() {
+        return contextUsageOf(await this.#ask(() => this.#query.getContextUsage()));
+    }
+    /**
+     * The initialization result holds the models, the commands with their aliases and the mode the
+     * session started in (measured 2026-10-10 on SDK 0.3.296): nothing else is asked.
+     */
+    async info() {
+        return agentInfo(await this.#ask(() => this.#query.initializationResult()));
+    }
+    /**
+     * Ends the input, closes the query and resolves once its stream has ended, so that a new
+     * session may resume the same id right after (the process needs real time to flush).
+     */
+    async close() {
+        if (!this.#closing) {
+            this.#closing = true;
+            this.#input.end();
+            try {
+                this.#query.close();
+            }
+            catch (error) {
+                logger.error(`could not close the process: ${errorName(error)}`);
+            }
+        }
+        await this.#finished;
+    }
+}