toolroll 0.9.63 → 0.9.65

package/dist/acp-client.js

@@ -0,0 +1,738 @@
+/**
+ * The Agent Client Protocol, from the plane's side (docs/plans/acp-adapter.md).
+ *
+ * ACP is JSON-RPC 2.0, one message per line, over the agent's stdio. This
+ * module is the whole conversation as a pure state machine: it is handed the
+ * agent's lines one at a time and answers with the lines to send back. It
+ * never spawns, reads a clock or touches a file — the runner (exec.ts) owns
+ * the process, the timers and the shutdown.
+ *
+ * One conversation is one build: `initialize`, `session/new` in the
+ * worktree, the sealed model selected and seen to be current, one
+ * `session/prompt` carrying the brief, then `session/update`s until the
+ * response to that prompt. Success is that response with
+ * `stopReason: "end_turn"` and nothing else — no update, exit code or
+ * message text can stand in for it.
+ *
+ * The plane offers no client capabilities (no file system, no terminal), so
+ * every agent request except `session/request_permission` is answered
+ * "method not found". A model is chosen only through a `model` config option,
+ * whose answer shows the model current: `session/set_model` answers with
+ * nothing to observe, so an agent that offers only that is refused until a
+ * fixture proves how it confirms. Builds are full access inside the OS fence, so a
+ * permission request is granted once (`allow_once`, never `allow_always`);
+ * the fence, not this answer, is the boundary — OpenCode runs commands
+ * without asking at all.
+ *
+ * What the runner keeps is not the agent's stream but a short synthetic
+ * record (`retained()`), one JSON object per line, typed `acp.*` — a type
+ * no agent can emit — which `acpParse` reads into the gateway's envelope.
+ */
+/** How many offered models a conversation keeps (each id ≤ 200 characters). */
+export const ACP_OFFERED_CAP = 2000;
+/** The largest line (UTF-8 bytes) the plane reads from an agent; a longer one is a protocol failure. */
+export const ACP_LINE_CAP = 1024 * 1024;
+const MESSAGE_CAP = 64 * 1024;
+const TEXT_CAP = 2048;
+const USAGE_CAP = 8 * 1024;
+const PROTOCOL_VERSION = 1;
+const STOP_REASONS = new Set(["end_turn", "max_tokens", "max_turn_requests", "refusal", "cancelled"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function bounded(text, cap) {
+    return text.length <= cap ? text : text.slice(0, cap);
+}
+function line(message) {
+    return JSON.stringify(message);
+}
+/** The model a `session/new` (or `set_config_option`) result offers, by mechanism. */
+function modelOffer(result) {
+    const options = result["configOptions"];
+    if (Array.isArray(options)) {
+        const model = options.find(one => isRecord(one) && one["id"] === "model" && one["type"] === "select");
+        if (isRecord(model) && Array.isArray(model["options"])) {
+            // Choices, or groups of choices — read as the same variant validation accepted: all choices, or all groups.
+            const options = model["options"];
+            const choices = options.every(configChoice) ? options : options.every(configGroup) ? options.flatMap(one => one["options"]) : [];
+            const offered = choices.flatMap(one => isRecord(one) && typeof one["value"] === "string" ? [one["value"]] : []);
+            return { mechanism: "config-option", offered, current: typeof model["currentValue"] === "string" ? model["currentValue"] : null };
+        }
+    }
+    const models = result["models"];
+    if (isRecord(models) && Array.isArray(models["availableModels"])) {
+        const offered = models["availableModels"].flatMap(one => isRecord(one) && typeof one["modelId"] === "string" ? [one["modelId"]] : []);
+        return { mechanism: "set-model", offered, current: typeof models["currentModelId"] === "string" ? models["currentModelId"] : null };
+    }
+    return null;
+}
+const OPTION_KINDS = new Set(["allow_once", "allow_always", "reject_once", "reject_always"]);
+/**
+ * The answer to a permission request: the `allow_once` option, else the `reject_once` one. The whole list must be
+ * well formed — every option an object with a non-empty id and a known kind, no id twice — or nothing is chosen: an
+ * id shared by "once" and "always" would make the answer mean either.
+ */
+export function permissionAnswer(params) {
+    if (!isRecord(params) || !meta(params) || !Array.isArray(params["options"]) || params["options"].length === 0 || params["options"].length > 16)
+        return null;
+    const options = [];
+    const ids = new Set();
+    for (const one of params["options"]) {
+        if (!isRecord(one) || typeof one["optionId"] !== "string" || one["optionId"] === "" || one["optionId"].length > 256)
+            return null;
+        if (typeof one["kind"] !== "string" || !OPTION_KINDS.has(one["kind"]))
+            return null;
+        if (typeof one["name"] !== "string" || !meta(one))
+            return null;
+        if (ids.has(one["optionId"]))
+            return null;
+        ids.add(one["optionId"]);
+        options.push({ optionId: one["optionId"], kind: one["kind"] });
+    }
+    const allow = options.find(one => one.kind === "allow_once");
+    if (allow !== undefined)
+        return { optionId: allow.optionId, granted: true };
+    const reject = options.find(one => one.kind === "reject_once");
+    if (reject !== undefined)
+        return { optionId: reject.optionId, granted: false };
+    return null;
+}
+const str = (value) => typeof value === "string";
+const TOOL_KINDS = new Set(["read", "edit", "delete", "move", "search", "execute", "think", "fetch", "switch_mode", "other"]);
+const TOOL_STATUSES = new Set(["pending", "in_progress", "completed", "failed"]);
+const PLAN_PRIORITIES = new Set(["high", "medium", "low"]);
+const PLAN_STATUSES = new Set(["pending", "in_progress", "completed"]);
+/** An optional field: absent, null, or of its type. */
+const optional = (value, is) => value === undefined || value === null || is(value);
+/** Each parsed wire object's number tokens, by key, exactly as written (acp-client's JSON.parse reviver records them). */
+const NUMBER_SOURCES = new WeakMap();
+/** The integer a JSON number token writes exactly (1e3, 1000.0, 0e-999 and 1.000…0 do), or null when it writes none. */
+function exactInteger(source) {
+    const parts = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(source);
+    if (parts === null)
+        return null;
+    let digits = `${parts[2]}${parts[3] ?? ""}`.replace(/^0+/, "");
+    if (digits === "")
+        return 0n; // zero, at any exponent
+    const trailing = digits.length - digits.replace(/0+$/, "").length;
+    digits = digits.slice(0, digits.length - trailing);
+    const exponent = Number(parts[4] ?? "0") - (parts[3]?.length ?? 0) + trailing;
+    if (!Number.isSafeInteger(exponent) || exponent < 0)
+        return null; // a fraction, or no number at all
+    if (digits.length + exponent > 400)
+        return null; // far past any field's range
+    const exact = BigInt(digits) * 10n ** BigInt(exponent);
+    return parts[1] === "-" ? -exact : exact;
+}
+/** `holder[key]` as an integer in [min, max]: on the wire, exactly the integer its token writes; built in memory, a safe one. */
+function wireInteger(holder, key, min, max) {
+    const value = holder[key];
+    if (typeof value !== "number")
+        return false;
+    // Every number the client reads came off the wire with its token: one without is refused, never taken as it reads.
+    const source = NUMBER_SOURCES.get(holder)?.get(key);
+    const exact = source === undefined ? null : exactInteger(source);
+    return exact !== null && exact >= min && exact <= max;
+}
+/** A number as the agent wrote it: past 2^53, its exact decimal string (when its token writes an integer). */
+function exactNumber(holder, key, item) {
+    if (Number.isSafeInteger(item))
+        return item;
+    const source = NUMBER_SOURCES.get(holder)?.get(key);
+    const exact = source === undefined ? null : exactInteger(source);
+    return exact === null ? item : exact.toString();
+}
+/** `holder[key]`, copied with every integer JavaScript would round (past 2^53) as its exact decimal string, so what
+ * is shown and kept is what the agent said — at any depth, in objects and arrays alike (iteratively: no nesting can
+ * exhaust the stack). Every key, `__proto__` included, is the copy's own data, never an inherited field. */
+function exactField(holder, key) {
+    const root = holder[key];
+    if (typeof root === "number")
+        return exactNumber(holder, key, root);
+    if (root === null || typeof root !== "object")
+        return root;
+    const fresh = (one) => (Array.isArray(one) ? [] : {});
+    const out = fresh(root);
+    const stack = [[root, out]];
+    for (let next = stack.pop(); next !== undefined; next = stack.pop()) {
+        const [source, target] = next;
+        const entries = Array.isArray(source) ? source.map((item, index) => [String(index), item]) : Object.entries(source);
+        for (const [name, item] of entries) {
+            let value = item;
+            if (typeof item === "number")
+                value = exactNumber(source, name, item);
+            else if (item !== null && typeof item === "object") {
+                value = fresh(item);
+                stack.push([item, value]);
+            }
+            Object.defineProperty(target, name, { value, enumerable: true, writable: true, configurable: true });
+        }
+    }
+    return out;
+}
+const optionalInteger = (holder, key, min, max) => holder[key] === undefined || holder[key] === null || wireInteger(holder, key, min, max);
+const INT64 = [-(2n ** 63n), 2n ** 63n - 1n];
+const UINT64 = [0n, 2n ** 64n - 1n];
+const UINT32 = [0n, 2n ** 32n - 1n];
+const INT32 = [-(2n ** 31n), 2n ** 31n - 1n];
+const bool = (value) => typeof value === "boolean";
+/** A list whose every entry passes. */
+const listOf = (is) => (value) => Array.isArray(value) && value.every(is);
+/** `_meta`, wherever the protocol allows it: absent, null, or an object. */
+const meta = (value) => optional(value["_meta"], isRecord);
+const ROLES = new Set(["user", "assistant"]);
+const annotations = (value) => optional(value, one => isRecord(one) && meta(one)
+    && optional(one["audience"], list => Array.isArray(list) && list.every(role => str(role) && ROLES.has(role)))
+    && optional(one["priority"], n => typeof n === "number" && Number.isFinite(n))
+    && optional(one["lastModified"], str));
+/** One ACP content block, every field the protocol defines for its type checked (text, image, audio, a resource link, an embedded resource). */
+function wellFormedContent(block) {
+    if (!isRecord(block) || !str(block["type"]) || !annotations(block["annotations"]) || !meta(block))
+        return false;
+    switch (block["type"]) {
+        case "text": return str(block["text"]);
+        case "image": return str(block["data"]) && str(block["mimeType"]) && optional(block["uri"], str);
+        case "audio": return str(block["data"]) && str(block["mimeType"]);
+        case "resource_link":
+            return str(block["uri"]) && str(block["name"]) && optional(block["mimeType"], str) && optional(block["title"], str)
+                && optional(block["description"], str) && optionalInteger(block, "size", ...INT64);
+        case "resource": {
+            // An embedded resource is one of two shapes — text contents or blob contents — beside its uri; a field the
+            // matched shape doesn't define is the agent's own, and isn't read.
+            const resource = block["resource"];
+            return isRecord(resource) && meta(resource) && str(resource["uri"]) && (str(resource["text"]) || str(resource["blob"]))
+                && optional(resource["mimeType"], str);
+        }
+        default: return false;
+    }
+}
+/** A tool call's content: content blocks, diffs, or terminals. */
+function wellFormedToolContent(item) {
+    if (!isRecord(item) || !str(item["type"]) || !meta(item))
+        return false;
+    if (item["type"] === "content")
+        return wellFormedContent(item["content"]);
+    if (item["type"] === "diff")
+        return str(item["path"]) && str(item["newText"]) && (item["oldText"] === undefined || item["oldText"] === null || str(item["oldText"]));
+    if (item["type"] === "terminal")
+        return str(item["terminalId"]);
+    return false;
+}
+/** The fields a tool call or its update may carry: each, when present, of the type the protocol gives it. */
+/** `initial`: a tool call's first report, whose fields are never null when present; an update's may be (unchanged). */
+function wellFormedToolFields(update, initial = false) {
+    if (!meta(update))
+        return false;
+    const field = (key, is) => initial ? absentOr(update[key], is) : optional(update[key], is);
+    if (!field("title", str))
+        return false;
+    if (!field("kind", one => str(one) && TOOL_KINDS.has(one)))
+        return false;
+    if (!field("status", one => str(one) && TOOL_STATUSES.has(one)))
+        return false;
+    if (!field("locations", list => Array.isArray(list) && list.every(one => isRecord(one) && meta(one) && str(one["path"]) && optionalInteger(one, "line", ...UINT32))))
+        return false;
+    if (!optional(update["name"], str))
+        return false;
+    if (update["content"] !== undefined && update["content"] !== null && !(Array.isArray(update["content"]) && update["content"].every(wellFormedToolContent)))
+        return false;
+    return true;
+}
+/** A session config option, every field its schema gives (a select's current value and choices, or groups of them). */
+const configChoice = (one) => isRecord(one) && meta(one) && str(one["value"]) && str(one["name"]) && optional(one["description"], str);
+const configGroup = (one) => isRecord(one) && meta(one) && str(one["group"]) && str(one["name"]) && listOf(configChoice)(one["options"]);
+function wellFormedConfigOption(option) {
+    if (!isRecord(option) || !meta(option) || !str(option["id"]) || !str(option["name"]) || !optional(option["description"], str)
+        || !optional(option["category"], str) || !str(option["type"]))
+        return false;
+    if (option["type"] !== "select")
+        return false;
+    const choices = option["options"];
+    return str(option["currentValue"]) && Array.isArray(choices) && (choices.every(configChoice) || choices.every(configGroup));
+}
+const wellFormedConfigOptions = listOf(wellFormedConfigOption);
+const sessionModes = (value) => isRecord(value) && meta(value) && str(value["currentModeId"])
+    && listOf(mode => isRecord(mode) && meta(mode) && str(mode["id"]) && str(mode["name"]) && optional(mode["description"], str))(value["availableModes"]);
+const sessionModels = (value) => isRecord(value) && meta(value) && str(value["currentModelId"])
+    && listOf(model => isRecord(model) && meta(model) && str(model["modelId"]) && str(model["name"]) && optional(model["description"], str))(value["availableModels"]);
+/** A field that may be left out but, when present, is never null. */
+const absentOr = (value, is) => value === undefined || is(value);
+const capabilities = (value, flags) => absentOr(value, one => isRecord(one) && meta(one) && flags.every(flag => absentOr(one[flag], bool)));
+/** The session capabilities the schema names (each an optional, nullable object); others are left uninterpreted. */
+const SESSION_CAPABILITIES = ["list", "delete", "additionalDirectories", "resume", "close"];
+/** initialize's answer, every field the schema gives it. */
+function wellFormedInitialize(result) {
+    const info = result["agentInfo"];
+    if (!meta(result) || !isRecord(info) || !meta(info) || !str(info["name"]) || !str(info["version"]) || !optional(info["title"], str))
+        return false;
+    if (!absentOr(result["authMethods"], listOf(method => isRecord(method) && meta(method) && str(method["id"]) && str(method["name"]) && optional(method["description"], str))))
+        return false;
+    return absentOr(result["agentCapabilities"], caps => isRecord(caps) && meta(caps) && absentOr(caps["loadSession"], bool)
+        && capabilities(caps["promptCapabilities"], ["image", "audio", "embeddedContext"])
+        && capabilities(caps["mcpCapabilities"], ["http", "sse"])
+        && absentOr(caps["sessionCapabilities"], sessions => isRecord(sessions) && meta(sessions)
+            && SESSION_CAPABILITIES.every(name => optional(sessions[name], entry => isRecord(entry) && meta(entry))))
+        && absentOr(caps["auth"], auth => isRecord(auth) && meta(auth) && optional(auth["logout"], logout => isRecord(logout) && meta(logout))));
+}
+/** session/new's answer: the id, and every field of the modes, models and config options it may carry. */
+function wellFormedNewSession(result) {
+    return meta(result) && optional(result["configOptions"], wellFormedConfigOptions) && optional(result["modes"], sessionModes) && optional(result["models"], sessionModels);
+}
+/** Whether a known update kind carries what it must; an unknown kind is left alone (not shown, not trusted). */
+function wellFormedUpdate(kind, update) {
+    const id = (key) => str(update[key]) && update[key] !== "" && update[key].length <= 256;
+    switch (kind) {
+        case "agent_message_chunk":
+        case "agent_thought_chunk":
+        case "user_message_chunk":
+            return wellFormedContent(update["content"]) && optional(update["messageId"], str);
+        case "tool_call":
+            // The first report of a call carries its content as a list when it carries any (null is for updates).
+            return id("toolCallId") && str(update["title"]) && update["content"] !== null && wellFormedToolFields(update, true);
+        case "tool_call_update":
+            return id("toolCallId") && wellFormedToolFields(update);
+        case "plan":
+            return Array.isArray(update["entries"]) && update["entries"].every(one => isRecord(one) && meta(one) && str(one["content"]) && str(one["priority"]) && PLAN_PRIORITIES.has(one["priority"]) && str(one["status"]) && PLAN_STATUSES.has(one["status"]));
+        case "available_commands_update":
+            return Array.isArray(update["availableCommands"]) && update["availableCommands"].every(one => isRecord(one) && meta(one) && str(one["name"]) && str(one["description"])
+                && optional(one["input"], input => isRecord(input) && meta(input) && str(input["hint"])));
+        case "current_mode_update":
+            return str(update["currentModeId"]);
+        case "config_option_update":
+            return wellFormedConfigOptions(update["configOptions"]);
+        case "session_info_update":
+            return optional(update["title"], str) && optional(update["updatedAt"], str);
+        case "usage_update":
+            return wireInteger(update, "used", ...UINT64) && wireInteger(update, "size", ...UINT64)
+                && optional(update["cost"], cost => isRecord(cost) && meta(cost) && typeof cost["amount"] === "number" && Number.isFinite(cost["amount"]) && str(cost["currency"]));
+        case "notice":
+            return str(update["severity"]) && str(update["title"]) && update["title"] !== "" && optional(update["description"], str);
+        case "compaction_update":
+            return str(update["compactionId"]) && str(update["status"]) && optional(update["summary"], listOf(wellFormedContent)) && optional(update["error"], str);
+        case "compaction_summary_chunk":
+            return str(update["compactionId"]) && wellFormedContent(update["content"]);
+        default:
+            return true;
+    }
+}
+/** The update kinds passed on to the live view: the ones the plane knows and never declined. Notices and compaction,
+ * which this client does not advertise, are validated when sent anyway, and go no further. */
+const KNOWN_UPDATES = new Set(["agent_message_chunk", "agent_thought_chunk", "user_message_chunk", "tool_call", "tool_call_update", "plan",
+    "available_commands_update", "current_mode_update", "config_option_update", "session_info_update", "usage_update"]);
+const AUTH_REQUIRED = -32000;
+export function createAcpConversation(options) {
+    let phase = "initialize";
+    let failure = null;
+    let terminal = null;
+    let sessionId = null;
+    let agent = null;
+    let canClose = false;
+    let closeId = null;
+    let closeDone = false;
+    let mechanism = null;
+    let offered = [];
+    let nextId = 0;
+    /** Set once the plane asked the prompt to stop: from then on every permission request is answered "cancelled". */
+    let cancelled = false;
+    /** Our requests not yet answered, by id. */
+    const pending = new Map();
+    /** Ids we have seen answered — a second answer to any of them is a protocol failure. */
+    const answered = new Set();
+    /** The words since the last tool call: the agent's last message. */
+    let message = "";
+    /** The agent's own accounts of what it used: the prompt answer's `usage`, and the last `usage_update`. Never priced. */
+    let promptUsage = null;
+    let usageUpdate = null;
+    const retained = [];
+    const keep = (record) => { retained.push(line(record)); };
+    const fail = (kind, text) => {
+        if (failure === null) {
+            failure = { kind, text: bounded(text, TEXT_CAP) };
+            keep({ type: "acp.failure", kind, text: failure.text });
+        }
+        phase = "failed";
+        return { send: [], live: [] };
+    };
+    const request = (method, params, purpose) => {
+        const id = ++nextId;
+        pending.set(id, purpose);
+        return line({ jsonrpc: "2.0", id, method, params });
+    };
+    /** A reply under the request's id, written as its token: an integer exactly (int64, past 2^53 too), a string, or null. */
+    const reply = (idToken, outcome) => {
+        const body = line({ jsonrpc: "2.0", ...outcome });
+        return `{"jsonrpc":"2.0","id":${idToken},${body.slice('{"jsonrpc":"2.0",'.length)}`;
+    };
+    const promptLine = () => {
+        phase = "prompt";
+        return request("session/prompt", { sessionId, prompt: [{ type: "text", text: options.prompt }] }, "prompt");
+    };
+    const onResult = (purpose, result, error) => {
+        const errorText = error === null ? "" : typeof error["message"] === "string" ? error["message"] : "the agent answered with an error";
+        const errorCode = error === null ? null : typeof error["code"] === "number" ? error["code"] : null;
+        if (purpose === "close") {
+            closeDone = true;
+            // An error to close is the agent's to have; an answer must be the empty object the schema gives it.
+            if (error === null && !(isRecord(result) && meta(result)))
+                return fail("protocol", "session/close was answered with something other than an object");
+            return { send: [], live: [] };
+        }
+        if (purpose === "prompt") {
+            if (error !== null) {
+                terminal = { error: { code: errorCode, message: bounded(errorText, TEXT_CAP) } };
+                keep({ type: "acp.terminal", error: terminal.error });
+                if (errorCode === AUTH_REQUIRED)
+                    return fail("auth-required", errorText);
+                phase = "ended";
+                return { send: [], live: [] };
+            }
+            const stop = isRecord(result) ? result["stopReason"] : undefined;
+            if (typeof stop !== "string" || !STOP_REASONS.has(stop))
+                return fail("protocol", "the prompt's answer carried no known stop reason");
+            if (!isRecord(result) || !meta(result))
+                return fail("protocol", "the prompt's answer carried a malformed _meta");
+            terminal = { stopReason: stop };
+            if (isRecord(result) && result["usage"] !== undefined)
+                promptUsage = exactField(result, "usage");
+            if (message !== "")
+                keep({ type: "acp.message", content: bounded(message, MESSAGE_CAP) });
+            keep({ type: "acp.terminal", stopReason: stop });
+            phase = "ended";
+            return { send: [], live: [] };
+        }
+        if (error !== null) {
+            if (errorCode === AUTH_REQUIRED)
+                return fail("auth-required", errorText);
+            return fail(purpose === "model" ? "model-unavailable" : "protocol", `${purpose}: ${errorText}`);
+        }
+        if (!isRecord(result))
+            return fail("protocol", `${purpose}: the answer was not an object`);
+        if (purpose === "initialize") {
+            if (!wireInteger(result, "protocolVersion", 0n, 65535n) || result["protocolVersion"] !== PROTOCOL_VERSION)
+                return fail("protocol", `the agent speaks protocol version ${String(result["protocolVersion"])}, not ${PROTOCOL_VERSION}`);
+            const info = result["agentInfo"];
+            if (!isRecord(info) || typeof info["name"] !== "string" || typeof info["version"] !== "string")
+                return fail("identity", "the agent did not say its name and version");
+            if (!wellFormedInitialize(result))
+                return fail("protocol", "initialize was answered with fields the protocol doesn't allow");
+            agent = { name: bounded(info["name"], 128), version: bounded(info["version"], 64) };
+            if (options.expect !== null && (agent.name !== options.expect.name || agent.version !== options.expect.version)) {
+                return fail("identity", `the agent is ${agent.name} ${agent.version}, not the checked ${options.expect.name} ${options.expect.version}`);
+            }
+            const capabilities = result["agentCapabilities"];
+            const sessions = isRecord(capabilities) ? capabilities["sessionCapabilities"] : undefined;
+            canClose = isRecord(sessions) && isRecord(sessions["close"]);
+            keep({ type: "acp.agent", name: agent.name, version: agent.version });
+            phase = "session";
+            return { send: [request("session/new", { cwd: options.cwd, mcpServers: options.mcpServers ?? [] }, "session/new")], live: [] };
+        }
+        if (purpose === "session/new") {
+            const id = result["sessionId"];
+            if (typeof id !== "string" || id.trim() === "" || id.length > 256)
+                return fail("protocol", "the session had no id");
+            if (!wellFormedNewSession(result))
+                return fail("protocol", "session/new was answered with fields the protocol doesn't allow");
+            sessionId = id;
+            keep({ type: "acp.session", sessionId: id });
+            const offer = modelOffer(result);
+            if (offer === null)
+                return fail("model-unavailable", "the agent offers no way to choose a model");
+            mechanism = offer.mechanism;
+            // An agent can offer many hundreds (OpenCode lists every model of every provider it knows): kept bounded, and
+            // the model asked for is always among them when offered.
+            offered = offer.offered.filter(one => one.length <= 200).slice(0, ACP_OFFERED_CAP);
+            if (offer.offered.includes(options.model) && !offered.includes(options.model))
+                offered.push(options.model);
+            keep({ type: "acp.offered", models: offered });
+            if (offer.mechanism !== "config-option")
+                return fail("model-unavailable", "the agent can't confirm which model it uses (it offers only session/set_model)");
+            if (!offer.offered.includes(options.model))
+                return fail("model-unavailable", `the agent doesn't offer ${options.model}`);
+            phase = "model";
+            return { send: [request("session/set_config_option", { sessionId: id, configId: "model", value: options.model }, "model")], live: [] };
+        }
+        // purpose === "model": the answer must be a well-formed set of config options, showing the model current.
+        if (!meta(result) || !wellFormedConfigOptions(result["configOptions"]))
+            return fail("model-unavailable", "the model choice was answered with malformed config options");
+        const chosen = modelOffer(result);
+        if (chosen === null || chosen.mechanism !== "config-option" || chosen.current !== options.model)
+            return fail("model-unavailable", `the agent did not make ${options.model} current`);
+        keep({ type: "acp.model", model: options.model, mechanism });
+        return { send: [promptLine()], live: [] };
+    };
+    const onUpdate = (params) => {
+        if (!isRecord(params) || !isRecord(params["update"]))
+            return fail("protocol", "a session update without an update");
+        if (sessionId === null || params["sessionId"] !== sessionId)
+            return fail("protocol", "an update for another session");
+        const update = params["update"];
+        const kind = update["sessionUpdate"];
+        if (typeof kind !== "string" || kind === "" || kind.length > 64)
+            return fail("protocol", "a session update without a kind");
+        if (!meta(update) || !meta(params))
+            return fail("protocol", "a session update whose _meta isn't an object");
+        if (!wellFormedUpdate(kind, update))
+            return fail("protocol", `a malformed ${kind} update`);
+        if (kind === "agent_message_chunk") {
+            const content = update["content"];
+            if (isRecord(content) && content["type"] === "text" && typeof content["text"] === "string" && message.length < MESSAGE_CAP) {
+                message = bounded(message + content["text"], MESSAGE_CAP);
+            }
+        }
+        else if (kind === "tool_call") {
+            message = "";
+        }
+        else if (kind === "usage_update") {
+            usageUpdate = exactField(params, "update");
+        }
+        return { send: [], live: KNOWN_UPDATES.has(kind) ? [exactField(params, "update")] : [] };
+    };
+    /** One line from the agent: what to send back, and what to show. */
+    const receiveLine = (raw) => {
+        if (raw.length > ACP_LINE_CAP || Buffer.byteLength(raw, "utf8") > ACP_LINE_CAP)
+            return fail("protocol", "the agent wrote a line too long to read");
+        if (raw.trim() === "")
+            return { send: [], live: [] };
+        let incoming;
+        try {
+            // Every number's token is kept beside it: where the client reads an integer (a location's line, a resource's
+            // size, an error's code, a usage count), it is exactly the integer on the wire — 1e3 is 1000, but
+            // 1.0000000000000001 is not 1. Opaque data (raw input and output, metadata) is never read, so never judged.
+            incoming = JSON.parse(raw, function (key, value, context) {
+                if (typeof value === "number" && context?.source !== undefined && this !== null && typeof this === "object") {
+                    const holder = this;
+                    const sources = NUMBER_SOURCES.get(holder) ?? new Map();
+                    sources.set(key, context.source);
+                    NUMBER_SOURCES.set(holder, sources);
+                }
+                return value;
+            });
+        }
+        catch {
+            return fail("protocol", "the agent wrote a line that is not JSON");
+        }
+        if (!isRecord(incoming) || incoming["jsonrpc"] !== "2.0")
+            return fail("protocol", "the agent wrote something that is not JSON-RPC 2.0");
+        // The message's own id is read by its token, as an exact integer (4, 4e0 and 4.0 are one id; 1.0000000000000001
+        // is none), so no reply goes out under, and no answer is taken for, an id other than the one on the wire.
+        const hasId = Object.prototype.hasOwnProperty.call(incoming, "id");
+        const id = incoming["id"];
+        let idToken = null;
+        let idNumber = null;
+        if (typeof id === "number") {
+            const source = NUMBER_SOURCES.get(incoming)?.get("id");
+            const exact = source === undefined ? null : exactInteger(source);
+            if (exact === null || exact < INT64[0] || exact > INT64[1])
+                return fail("protocol", "a message whose id isn't an integer");
+            idToken = exact.toString();
+            if (BigInt(Number(exact)) === exact && Number.isSafeInteger(Number(exact)))
+                idNumber = Number(exact);
+        }
+        else if (typeof id === "string" && id.length <= 256)
+            idToken = JSON.stringify(id);
+        else if (id === null && hasId)
+            idToken = "null";
+        const method = incoming["method"];
+        if (typeof method === "string") {
+            const params = incoming["params"];
+            // Anything that names a session must name ours.
+            if (isRecord(params) && params["sessionId"] !== undefined && params["sessionId"] !== sessionId)
+                return fail("protocol", "a message for another session");
+            if (!hasId) {
+                // A notification. Only session updates mean anything; the rest are ignored.
+                return method === "session/update" ? onUpdate(params) : { send: [], live: [] };
+            }
+            // An id we answer under goes back exactly as sent: an integer, a bounded string, or null.
+            if (idToken === null)
+                return fail("protocol", "an agent request with a malformed id");
+            if (method === "session/request_permission") {
+                if (!isRecord(params) || sessionId === null || params["sessionId"] !== sessionId)
+                    return fail("protocol", "a permission request for another session");
+                const call = params["toolCall"];
+                // The tool call it asks about must be as well formed as one sent in an update, or nothing is granted.
+                const answer = isRecord(call) && typeof call["toolCallId"] === "string" && call["toolCallId"] !== "" && call["toolCallId"].length <= 256 && wellFormedToolFields(call)
+                    ? permissionAnswer(params)
+                    : null;
+                const step = {
+                    sessionUpdate: "permission",
+                    toolCallId: isRecord(call) && typeof call["toolCallId"] === "string" ? call["toolCallId"] : null,
+                    title: isRecord(call) && typeof call["title"] === "string" ? call["title"] : null,
+                    kind: isRecord(call) && typeof call["kind"] === "string" ? call["kind"] : null,
+                };
+                // Granted only while our prompt runs and was not cancelled: before the model is confirmed, after the answer,
+                // or after a cancel, the request is answered "cancelled".
+                if (cancelled || phase !== "prompt") {
+                    return { send: [reply(idToken, { result: { outcome: { outcome: "cancelled" } } })], live: [{ ...step, granted: false }] };
+                }
+                if (answer === null) {
+                    return { send: [reply(idToken, { error: { code: -32602, message: "a permission request needs a tool call and an option this client can choose" } })], live: [{ ...step, granted: false }] };
+                }
+                return {
+                    send: [reply(idToken, { result: { outcome: { outcome: "selected", optionId: answer.optionId } } })],
+                    live: [{ ...step, granted: answer.granted }],
+                };
+            }
+            return { send: [reply(idToken, { error: { code: -32601, message: "this client offers no such method" } })], live: [] };
+        }
+        // A response to one of ours.
+        if (idNumber === null)
+            return fail("protocol", "a response with an id the plane never sent");
+        if (answered.has(idNumber))
+            return fail("protocol", "a second answer to the same request");
+        const purpose = pending.get(idNumber);
+        if (purpose === undefined)
+            return fail("protocol", "a response with an id the plane never sent");
+        pending.delete(idNumber);
+        answered.add(idNumber);
+        const hasResult = Object.prototype.hasOwnProperty.call(incoming, "result");
+        const hasError = Object.prototype.hasOwnProperty.call(incoming, "error");
+        if (hasResult === hasError)
+            return fail("protocol", "a response must carry a result or an error, not both or neither");
+        const error = incoming["error"];
+        if (hasError && !(isRecord(error) && wireInteger(error, "code", ...INT32) && typeof error["message"] === "string")) {
+            return fail("protocol", "a response with a malformed error");
+        }
+        return onResult(purpose, incoming["result"], hasError ? error : null);
+    };
+    return {
+        start() {
+            return [request("initialize", {
+                    protocolVersion: PROTOCOL_VERSION,
+                    clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+                }, "initialize")];
+        },
+        receive(raw) {
+            if (phase === "failed")
+                return { send: [], live: [] };
+            // Nothing the agent writes may throw out of the client: whatever does is the agent's protocol failure.
+            try {
+                return receiveLine(raw);
+            }
+            catch (error) {
+                return fail("protocol", `the agent wrote a message the client couldn't read (${error instanceof Error ? error.name : "error"})`);
+            }
+        },
+        cancel() {
+            if (phase !== "prompt" || sessionId === null)
+                return [];
+            cancelled = true;
+            return [line({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } })];
+        },
+        refuse(text) {
+            fail("protocol", text);
+        },
+        close() {
+            if (!canClose || sessionId === null || closeId !== null)
+                return [];
+            const sent = request("session/close", { sessionId }, "close");
+            closeId = nextId;
+            return [sent];
+        },
+        closeAnswered: () => closeDone || phase === "failed",
+        phase: () => phase,
+        failure: () => failure,
+        terminal: () => terminal,
+        sessionId: () => sessionId,
+        agent: () => agent,
+        mechanism: () => mechanism,
+        offered: () => offered.slice(),
+        retained: () => {
+            // The agent's own usage accounts ride every outcome — a failure spent too.
+            const usage = promptUsage === null && usageUpdate === null ? [] : [line({ type: "acp.reported", usage: bounded(JSON.stringify({ prompt: promptUsage, update: usageUpdate }), USAGE_CAP) })];
+            const all = [...retained, ...usage];
+            return all.length === 0 ? "" : `${all.join("\n")}\n`;
+        },
+    };
+}
+/** Read a conversation's retained record. Lines not typed `acp.*` are ignored. */
+export function acpParse(stdout) {
+    let agentSeen = false;
+    let sessionId = null;
+    let conflict = false;
+    let finalMessage = null;
+    let reportedUsage = null;
+    let stop = null;
+    let rpcError = null;
+    let terminals = 0;
+    let failure = null;
+    let offered = [];
+    let agent = null;
+    let exit = null;
+    for (const raw of stdout.split("\n")) {
+        if (raw.trim() === "")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(event))
+            continue;
+        const type = event["type"];
+        if (type === "acp.agent") {
+            agentSeen = true;
+            if (agent === null && typeof event["name"] === "string" && typeof event["version"] === "string")
+                agent = { name: event["name"], version: event["version"] };
+        }
+        else if (type === "acp.session" && typeof event["sessionId"] === "string") {
+            if (sessionId === null)
+                sessionId = event["sessionId"];
+            else if (sessionId !== event["sessionId"])
+                conflict = true;
+        }
+        else if (type === "acp.message" && typeof event["content"] === "string")
+            finalMessage = event["content"];
+        else if (type === "acp.reported" && typeof event["usage"] === "string")
+            reportedUsage = event["usage"];
+        else if (type === "acp.terminal") {
+            terminals += 1;
+            if (typeof event["stopReason"] === "string")
+                stop = event["stopReason"];
+            else if (isRecord(event["error"])) {
+                const error = event["error"];
+                rpcError = { code: typeof error["code"] === "number" ? error["code"] : null, message: typeof error["message"] === "string" ? error["message"] : "" };
+            }
+        }
+        else if (type === "acp.offered" && Array.isArray(event["models"])) {
+            offered = event["models"].filter((one) => typeof one === "string").slice(0, ACP_OFFERED_CAP + 1);
+        }
+        else if (type === "acp.exit" && typeof event["how"] === "string" && ["eof", "term", "kill", "self", "error"].includes(event["how"])) {
+            exit = { how: event["how"], leftover: event["leftover"] === true, timedOut: event["timedOut"] === true };
+        }
+        else if (type === "acp.failure" && failure === null) {
+            failure = { kind: typeof event["kind"] === "string" ? event["kind"] : "protocol", text: typeof event["text"] === "string" ? event["text"] : "" };
+        }
+    }
+    const protocolError = conflict
+        ? "the agent named two sessions"
+        : terminals > 1
+            ? "the prompt was answered twice"
+            : failure !== null && failure.kind === "protocol"
+                ? `the agent broke the protocol: ${failure.text}`
+                : null;
+    const success = protocolError === null && failure === null && terminals === 1 && stop === "end_turn";
+    const diagnostic = failure?.text ?? rpcError?.message ?? null;
+    const code = failure !== null
+        ? failure.kind
+        : rpcError !== null
+            ? `rpc:${rpcError.code ?? "?"}`
+            : stop !== null && stop !== "end_turn"
+                ? stop
+                : null;
+    return {
+        sessionId: conflict ? null : sessionId,
+        protocolError,
+        finalMessage,
+        reportedUsage,
+        initObserved: agentSeen && sessionId !== null,
+        promptConsumed: success,
+        diagnostic: diagnostic === "" ? null : diagnostic,
+        terminal: success || code === null ? null : { failed: true, text: diagnostic === "" ? null : diagnostic, code },
+        offered,
+        exit,
+        agent,
+        stop: terminals === 1 ? stop : null,
+    };
+}