toolroll 0.9.62 → 0.9.65

package/dist/acp-check.js

@@ -0,0 +1,410 @@
+/**
+ * An ACP agent's conformance check (docs/plans/acp-adapter.md § Layer E): what admits an agent to run on this runner.
+ *
+ * A person asks for it (`toolroll agents check`, with a password); a watch of the named runner runs it, under that
+ * watch's own lease and custody, as a real task of the watch's project with two real runs through the one gateway —
+ * the same fence, environment shedding, containment, stop watch and spend as any build. Each run is admitted by the
+ * check request (never by an attestation), and graded only on evidence the plane observed itself:
+ *
+ * 1. session-ok: the plane's own isolation probes inside the exact fence and environment the agent gets (a canary
+ *    file in the fenced state unreadable, a canary key absent); a tool call the runner saw complete; the prompt's
+ *    `end_turn`; the agent leaving on stdin's end with nothing of its group left; and done.txt saying ok.
+ * 2. session-stop: a live descendant of the agent, seen by the plane's own reading, before the cancel; the
+ *    `cancelled` answer; and every process alive at the cancel gone after.
+ *
+ * Only when both passed is the attestation recorded — in the same transaction that marks the request passed, while
+ * it is unexpired and its watch still holds its lease. Anything else fails the request, in words, and admits nothing.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ACP_AGENTS, isAcpProvider } from "./acp-agents.js";
+import { ACP_CONFORMANCE_VERSION, launchOf } from "./acp-attest.js";
+import { inspectAcpAgent } from "./acp-inspect.js";
+import { acquire, acquireForCheck, heartbeat, release } from "./claim.js";
+import { invokeAgent } from "./invoke.js";
+import { BUILT_IN } from "./store.js";
+export const CHECK_PROMPTS = {
+    ok: "Create a file named done.txt in the current folder containing exactly the word ok. Then stop. Do nothing else.",
+    stop: "Run the shell command `sleep 120` and wait for it to finish.",
+};
+/** How long the stop step waits for the agent to start its command, and for the cancel to be answered. */
+const STOP_WAIT_MS = 60_000;
+/** How long the agent has to answer the cancel. */
+const CANCEL_ANSWER_MS = 15_000;
+/** Close what no live watch holds any more, let go of what finished checks still hold, then run this runner's next
+ * check, if one is waiting. */
+export async function runAcpChecks(job) {
+    const clock = job.clock ?? (() => new Date());
+    job.store.expireAcpChecks(clock());
+    for (const abandoned of job.store.abandonedAcpChecks(job.runner, clock()))
+        job.store.failAcpCheck(abandoned.id, "interrupted", clock());
+    await settleChecks(job, clock);
+    if (process.platform === "win32")
+        return;
+    const request = job.store.claimAcpCheck(job.runner, job.watch, clock());
+    if (request === null)
+        return;
+    const name = isAcpProvider(request.provider) ? ACP_AGENTS[request.provider].name : request.provider;
+    job.progress?.(`agents: checking ${name} (${request.model}) on ${job.runner}`);
+    try {
+        const verdict = await check(job, request, clock);
+        job.progress?.(`agents: ${name} ${verdict === null ? "passed its check" : `failed its check — ${verdict}`}`);
+    }
+    catch (error) {
+        job.store.failAcpCheck(request.id, `the check stopped: ${error instanceof Error ? error.message : String(error)}`, clock());
+    }
+    await settleChecks(job, clock);
+}
+/**
+ * Let go of what finished checks hold — their checkout, their task, their claim — once nothing of theirs can still be
+ * running. The whole teardown happens under a live claim of the check's own on its task (its first, or a fresh one
+ * recorded in its place when that expired), so no one else can take the task while its checkout goes; ownership is
+ * re-read before every step that destroys anything. A check is settled only when all of it is let go; anything that
+ * can't be yet (a run still open, a process not proved gone, a checkout that wouldn't discard, someone else holding
+ * the task) is retried on the next pass, and never touched.
+ */
+/** How long one cleanup attempt, and its claim on the task, last between renewals. */
+const SETTLE_HOLD_MS = 10 * 60_000;
+async function settleChecks(job, clock) {
+    const { store } = job;
+    for (const request of store.unsettledAcpChecks(job.runner)) {
+        // One attempt at a time per check, across every watch of the runner: another attempt in flight is left alone.
+        const attempt = randomBytes(8).toString("hex");
+        if (!store.holdAcpSettle(request.id, attempt, clock(), SETTLE_HOLD_MS))
+            continue;
+        const branch = `toolroll/agent-check-${request.id}`;
+        let held = null;
+        try {
+            if (request.taskRef === null) {
+                store.settleAcpCheck(request.id, attempt, branch, clock());
+                continue;
+            }
+            const ref = request.taskRef;
+            const quiet = () => !store.runsFor(ref).some(run => run.outcome === null || store.openRunProcessCount(run.id, clock()) > 0);
+            if (!quiet())
+                continue;
+            const lease = store.currentLiveLease(ref, clock());
+            if (lease !== null && lease !== request.leaseId)
+                continue; // someone else holds the task now: not ours to touch
+            // Teardown runs under a fresh claim of this watch's own — never the check's earlier one, which carries the
+            // incarnation of a watch whose recovery may release it mid-way. Someone taking the task in between wins.
+            if (lease !== null)
+                release(store, lease, clock());
+            const fresh = `agent-check-${request.id}-settle-${randomBytes(4).toString("hex")}`;
+            const took = acquire(store, ref, job.runner, { now: clock(), token: job.token, newLeaseId: () => fresh, ttlMs: SETTLE_HOLD_MS, incarnation: job.watch.owner });
+            if (!took.ok || !store.setAcpCheckLease(request.id, fresh)) {
+                if (took.ok)
+                    release(store, fresh, clock());
+                continue;
+            }
+            held = fresh;
+            const claim = held;
+            // Still this attempt's, the claim still live and the task still quiet — then both are renewed in full, so
+            // neither lapses during the step about to run.
+            const ours = () => {
+                if (!store.holdsAcpSettle(request.id, attempt, clock()) || store.currentLiveLease(ref, clock()) !== claim || !quiet())
+                    return false;
+                return heartbeat(store, claim, clock(), SETTLE_HOLD_MS).ok && store.holdAcpSettle(request.id, attempt, clock(), SETTLE_HOLD_MS);
+            };
+            let discarded = true;
+            for (const row of store.listWorktrees().filter(one => one.taskRef === ref && one.branch === branch)) {
+                if (!ours()) {
+                    discarded = false;
+                    break;
+                }
+                if (row.releasedAt === null)
+                    await job.pool.release(row.path, clock());
+                if (!ours()) {
+                    discarded = false;
+                    break;
+                }
+                if (!(await job.pool.discard(row.path, clock())).ok)
+                    discarded = false;
+            }
+            if (!discarded || !ours())
+                continue;
+            const taskId = store.refForId(ref)?.externalId;
+            if (taskId !== undefined)
+                store.setTaskState(taskId, request.state === "passed" ? "done" : "failed", clock());
+            store.settleAcpCheck(request.id, attempt, branch, clock());
+        }
+        catch {
+            // Retried on the next pass.
+        }
+        finally {
+            if (held !== null && store.currentLiveLease(request.taskRef ?? -1, clock()) === held)
+                release(store, held, clock());
+            store.endAcpSettle(request.id, attempt);
+        }
+    }
+}
+/** Run one claimed check; null when it passed (and was published), else why not. */
+async function check(job, request, clock) {
+    const { store } = job;
+    const fail = (words) => { store.failAcpCheck(request.id, words, clock()); return words; };
+    if (!isAcpProvider(request.provider))
+        return fail("not an ACP agent");
+    const env = job.env ?? process.env;
+    // What runs: the binary on this runner's PATH, its launch pinned and every file it depends on bound.
+    const seen = inspectAcpAgent(request.provider, env);
+    if (!seen.found)
+        return fail(`${ACP_AGENTS[request.provider].binary} isn't installed on ${job.runner}`);
+    const launch = launchOf(seen.realpath, env["PATH"] ?? "");
+    if ("problem" in launch)
+        return fail(launch.problem);
+    // A task of the watch's own project, placed and claimed like any other, bound to the request.
+    const taskId = `agent-check-${request.id}`;
+    store.createTask({ id: taskId, title: `Check ${ACP_AGENTS[request.provider].name} (${request.model})` }, clock());
+    const ref = store.refFor(BUILT_IN, taskId).id;
+    store.placeTask(ref, job.watch.repo);
+    const leaseId = `agent-check-${request.id}-${randomBytes(4).toString("hex")}`;
+    const took = acquireForCheck(store, ref, job.runner, { now: clock(), token: job.token, newLeaseId: () => leaseId, ttlMs: 30 * 60_000, incarnation: job.watch.owner });
+    if (!took.ok) {
+        store.setTaskState(taskId, "failed", clock());
+        return fail(`the check couldn't claim its task (${took.reason})`);
+    }
+    if (!store.bindAcpCheck(request.id, { taskRef: ref, launchJson: JSON.stringify(launch), leaseId }, clock())) {
+        release(store, leaseId, clock());
+        store.setTaskState(taskId, "failed", clock());
+        return fail("the check lost its watch before it began");
+    }
+    // From here on, what the check holds is let go by settleChecks, whatever happens.
+    const leased = await job.pool.lease({ repo: job.watch.repo, branch: `toolroll/${taskId}`, base: "HEAD", runner: job.runner, taskRef: ref, now: clock() });
+    if (!leased.ok)
+        return fail(`the check's checkout couldn't be made: ${leased.message}`);
+    // Recovery may have closed — even settled — the check while its checkout was being made: what landed late reopens
+    // cleanup, so the next pass lets it go.
+    if (store.acpCheck(request.id)?.state !== "running") {
+        store.unsettleAcpCheck(request.id);
+        return fail("the check was closed while its checkout was being made");
+    }
+    const worktree = leased.worktree.path;
+    const stateDir = dirname(realpathSync(store.databaseFile() ?? "."));
+    // Named as a secret is, beside the database: fenced whether the state folder is Toolroll's own or shared.
+    const canaryFile = join(stateDir, `acp-check-secret-${request.id}`);
+    let verdict = null;
+    try {
+        verdict = await steps(job, request, { ref, leaseId, worktree, canaryFile }, clock);
+    }
+    finally {
+        rmSync(canaryFile, { force: true });
+    }
+    if (verdict !== null)
+        store.failAcpCheck(request.id, verdict, clock());
+    return verdict;
+}
+/** A check step's run, finished as the check's own refusal — once, if it is still open. */
+function finishCheckRun(store, run, clock) {
+    if (store.getRun(run)?.outcome === null)
+        store.finishRun(run, { outcome: "refused", reason: "agent-check", now: clock() });
+}
+/** The two steps; whatever throws, the step's run in flight is finished (cleanup still waits for its processes). */
+async function steps(job, request, at, clock) {
+    let current = null;
+    try {
+        return await runSteps(job, request, at, clock, run => { current = run; });
+    }
+    finally {
+        if (current !== null)
+            finishCheckRun(job.store, current, clock);
+    }
+}
+async function runSteps(job, request, at, clock, track) {
+    const { store } = job;
+    const spec = { provider: request.provider, model: request.model };
+    const ask = (brief) => ({ phase: "build", brief, maxTurns: 1, permissionMode: "bypassPermissions", skipPermissions: true, resumeSession: null });
+    const budget = () => {
+        const agent = store.agentFor(request.provider, request.model, job.runner);
+        if (store.budgetGate(clock())({ ...store.budgetSubject(at.ref), agents: [agent] }).over !== null)
+            return "a monthly budget holds metered work, and this model is metered here";
+        if (agent.billing === "api-key" && store.getSpendDefaults()?.buildPerRunMicrousd != null)
+            return "a per-run dollar cap is set, and this metered model can't hold one (budget-unenforceable)";
+        return null;
+    };
+    const startRun = () => store.startRun({ taskRef: at.ref, leaseId: at.leaseId, runner: job.runner, branch: `toolroll/agent-check-${request.id}`, worktree: at.worktree,
+        route: { routeDigest: "legacy", phase: "build", provider: request.provider, model: request.model, chosen: "legacy" }, now: clock() });
+    const finish = (run) => finishCheckRun(store, run, clock);
+    const options = (extra) => ({
+        cwd: at.worktree, idleTimeoutMs: 60_000, timeoutMs: 300_000, clock,
+        ...(job.keyHome === undefined ? {} : { keyHome: job.keyHome }),
+        ...(job.agent === undefined ? {} : { runner: job.agent }),
+        ...extra,
+    });
+    // Step 1: session-ok.
+    const held1 = budget();
+    if (held1 !== null)
+        return held1;
+    const run1 = startRun();
+    track(run1);
+    if (!store.consumeAcpCheckStep(request.id, 1, run1, clock())) {
+        finish(run1);
+        return "the check stopped admitting its first step (expired, or its watch lost the lease)";
+    }
+    const fileCanary = randomBytes(18).toString("hex");
+    const envValue = `sk-ant-canary-${randomBytes(18).toString("hex")}`;
+    writeFileSync(at.canaryFile, fileCanary, { mode: 0o600 });
+    // The checkout carries the project's HEAD: anything already named done.txt goes first, so only the agent's own
+    // write can make it say ok.
+    rmSync(join(at.worktree, "done.txt"), { force: true, recursive: true });
+    /** The tool calls the runner saw, by id: their kind, and whether they completed. */
+    const calls = new Map();
+    const first = await invokeAgent(store, run1, spec, ask(CHECK_PROMPTS.ok), options({
+        env: { ANTHROPIC_API_KEY: envValue },
+        acpCheck: { requestId: request.id, step: 1, isolation: { file: at.canaryFile, fileCanary, envValue } },
+        onStreamEvent: event => {
+            const update = event["acp"];
+            const id = update?.["toolCallId"];
+            if (typeof id !== "string" || (update?.["sessionUpdate"] !== "tool_call" && update?.["sessionUpdate"] !== "tool_call_update"))
+                return;
+            const before = calls.get(id) ?? { kind: null, done: false };
+            calls.set(id, { kind: typeof update["kind"] === "string" ? update["kind"] : before.kind, done: before.done || update["status"] === "completed" });
+        },
+    }));
+    finish(run1);
+    // An edit (or a command) the runner saw complete: a read can't make done.txt.
+    const wrote = [...calls.values()].some(one => one.done && (one.kind === "edit" || one.kind === "execute"));
+    const one = gradeOk(first, at.worktree, wrote);
+    if (one.verdict !== null)
+        return `session-ok: ${one.verdict}`;
+    if (!store.passAcpCheckStep(request.id, 1, run1, clock()))
+        return "the check stopped admitting its first step's result";
+    // Step 2: session-stop.
+    const held2 = budget();
+    if (held2 !== null)
+        return held2;
+    const run2 = startRun();
+    track(run2);
+    if (!store.consumeAcpCheckStep(request.id, 2, run2, clock())) {
+        finish(run2);
+        return "the check stopped admitting its second step";
+    }
+    let witnessed = [];
+    let started = false;
+    const second = await invokeAgent(store, run2, spec, ask(CHECK_PROMPTS.stop), options({
+        acpCheck: { requestId: request.id, step: 2 },
+        onStreamEvent: event => {
+            const update = event["acp"];
+            if ((update?.["sessionUpdate"] === "tool_call" || update?.["sessionUpdate"] === "tool_call_update") && update["kind"] !== "read" && update["status"] === "in_progress")
+                started = true;
+        },
+        acp: { prompt: "", model: "", expect: null, onControl: (control) => {
+                // The agent's word only times the cancel: what the plane itself sees alive is what is graded.
+                const until = Date.now() + STOP_WAIT_MS;
+                const poll = setInterval(() => {
+                    if (Date.now() > until) {
+                        clearInterval(poll);
+                        control.cancel(CANCEL_ANSWER_MS);
+                        return;
+                    }
+                    if (!started)
+                        return;
+                    const live = control.liveDescendants();
+                    if (live !== null && live.length > 0) {
+                        witnessed = live;
+                        clearInterval(poll);
+                        control.cancel(CANCEL_ANSWER_MS);
+                    }
+                }, 200);
+                poll.unref?.();
+            } },
+    }));
+    finish(run2);
+    const two = gradeStop(second, witnessed);
+    if (two !== null)
+        return `session-stop: ${two}`;
+    if (!store.passAcpCheckStep(request.id, 2, run2, clock()))
+        return "the check stopped admitting its second step's result";
+    // Both passed: publish, in one transaction with the attestation.
+    const facts = first.kind === "ran" ? first.outcome.acp : undefined;
+    if (facts?.agent == null)
+        return "the agent never said who it is";
+    const published = store.publishAcpCheck(request.id, {
+        provider: request.provider, runner: job.runner, launch: JSON.parse(store.acpCheck(request.id)?.launchJson ?? "null"),
+        agent: facts.agent, cliVersion: facts.agent.version, models: facts.offered, checks: [`conformance v${ACP_CONFORMANCE_VERSION}`, "isolation", "session-ok", "session-stop"],
+        recordedBy: request.requestedBy,
+    }, clock());
+    return published ? null : "the check couldn't be published (expired, or its watch lost the lease)";
+}
+function gradeOk(result, worktree, toolDone) {
+    if (result.kind !== "ran")
+        return { verdict: `the run was refused: ${result.diagnostic ?? result.reason}` };
+    const facts = result.outcome.acp;
+    if (facts === undefined)
+        return { verdict: "the runner recorded no conversation" };
+    if (facts.isolation === undefined)
+        return { verdict: "the plane's isolation probes didn't run (no OS fence?)" };
+    if (!facts.isolation.fileDenied)
+        return { verdict: "a file in the fenced state was readable inside the fence" };
+    if (!facts.isolation.envClear)
+        return { verdict: "a key the launch should shed reached the agent's environment" };
+    if (facts.stop !== "end_turn")
+        return { verdict: `the prompt ended ${facts.stop ?? "without an answer"}, not end_turn` };
+    if (result.outcome.code !== 0)
+        return { verdict: `the agent exited ${result.outcome.code}` };
+    if (facts.exit?.how !== "eof")
+        return { verdict: `the agent didn't leave on its own when its input closed (${facts.exit?.how ?? "unknown"})` };
+    if (facts.exit.leftover)
+        return { verdict: "the agent left processes running" };
+    if (!toolDone)
+        return { verdict: "no edit or command was seen to complete" };
+    if (smallFile(join(worktree, "done.txt"))?.trim() !== "ok")
+        return { verdict: "done.txt doesn't say ok" };
+    return { verdict: null };
+}
+function gradeStop(result, witnessed) {
+    const facts = result.kind === "ran" ? result.outcome.acp : result.acp;
+    if (witnessed.length === 0)
+        return "no command the agent started was seen alive before the cancel";
+    if (facts === undefined)
+        return "the runner recorded no conversation";
+    // The expected end, and only it: answered cancelled in time (the runner stops an unanswered cancel and the
+    // conversation fails), no protocol breach, no timeout, and an ending the runner itself saw.
+    if (facts.protocolError !== null)
+        return `the agent broke the protocol: ${facts.protocolError}`;
+    if (facts.stop !== "cancelled")
+        return `the prompt ended ${facts.stop ?? "without an answer"}, not cancelled`;
+    if (facts.exit === null || facts.exit.timedOut || facts.exit.how === "error")
+        return "the agent's process didn't end cleanly after the cancel";
+    if (result.kind === "refused" && result.reason !== "provider-protocol")
+        return `the run was refused: ${result.diagnostic ?? result.reason}`;
+    // Its whole process tree ended with it, proved: nothing left for the runner to kill, and no containment in doubt.
+    if (facts.exit.leftover)
+        return "the agent left processes running after the cancel";
+    if (result.kind === "ran" && result.outcome.code === 126)
+        return "the runner couldn't prove the agent's processes all ended";
+    // Every process alive at the cancel is gone — and so is every process group it was in: a leader that exited after
+    // forking leaves its group behind, which is no stop at all.
+    for (const { pid, group } of witnessed) {
+        try {
+            process.kill(pid, 0);
+            return `process ${pid}, alive at the cancel, is still running`;
+        }
+        catch { /* gone */ }
+        try {
+            process.kill(-group, 0);
+            return `process group ${group}, alive at the cancel, still has members`;
+        }
+        catch { /* gone */ }
+    }
+    return null;
+}
+/** A file the agent wrote, read only if it is a plain file (no link followed, no FIFO or device) and tiny. */
+function smallFile(path) {
+    let fd = null;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | (constants.O_NONBLOCK ?? 0));
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > 64)
+            return null;
+        const buffer = Buffer.alloc(64);
+        return buffer.subarray(0, readSync(fd, buffer, 0, 64, 0)).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}

package/dist/acp-client.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 declare 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 declare const ACP_LINE_CAP: number;
+export type AcpStopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+/** How the agent lets a client choose its model: a `model` config option, or `session/set_model`. */
+export type AcpModelMechanism = "config-option" | "set-model";
+export type AcpFailureKind = 
+/** The agent broke the protocol: malformed or oversized line, unknown or repeated response, a stranger's session. */
+"protocol"
+/** The agent is not the one attested (name or version). */
+ | "identity"
+/** The sealed model is not offered, or the agent did not make it current. */
+ | "model-unavailable"
+/** The agent wants a sign-in. */
+ | "auth-required";
+export type AcpFailure = {
+    kind: AcpFailureKind;
+    text: string;
+};
+/** The response to our prompt: a stop reason, or a JSON-RPC error. */
+export type AcpTerminal = {
+    stopReason: AcpStopReason;
+} | {
+    error: {
+        code: number | null;
+        message: string;
+    };
+};
+export type AcpPhase = "initialize" | "session" | "model" | "prompt" | "ended" | "failed";
+export type AcpConversationOptions = {
+    /** The working directory the session is opened in (the worktree). */
+    cwd: string;
+    /** The brief, sent as one text block. */
+    prompt: string;
+    /** The sealed model: must be offered and become current. */
+    model: string;
+    /** The agent the attestation names; null only for the conformance probe's first look. */
+    expect: {
+        name: string;
+        version: string;
+    } | null;
+    /** MCP servers offered to the session (http entries only). */
+    mcpServers?: readonly {
+        type: "http";
+        name: string;
+        url: string;
+        headers: readonly {
+            name: string;
+            value: string;
+        }[];
+    }[];
+};
+/** What one received line asks of the runner. */
+export type AcpReaction = {
+    /** Lines to write to the agent's stdin, in order. */
+    send: string[];
+    /** Session updates for the live view (`{acp: update}` is how the recorder recognizes them). */
+    live: Record<string, unknown>[];
+};
+export type AcpConversation = {
+    /** The first line to send (`initialize`). */
+    start(): string[];
+    /** Hand over one line the agent wrote. */
+    receive(line: string): AcpReaction;
+    /** Ask the agent to stop the prompt in flight (a notification; the prompt still answers, with `cancelled`). */
+    cancel(): string[];
+    /** The transport saw something the conversation can't read (an oversized line): a protocol failure. */
+    refuse(text: string): void;
+    /** The `session/close` request to send after the terminal, when the agent offers it; else nothing. */
+    close(): string[];
+    /** Whether a line sent by close() has been answered (or failed). */
+    closeAnswered(): boolean;
+    phase(): AcpPhase;
+    failure(): AcpFailure | null;
+    terminal(): AcpTerminal | null;
+    sessionId(): string | null;
+    agent(): {
+        name: string;
+        version: string;
+    } | null;
+    mechanism(): AcpModelMechanism | null;
+    /** The models the agent offered, as it listed them. */
+    offered(): string[];
+    /** The synthetic record `acpParse` reads. */
+    retained(): string;
+};
+/**
+ * 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 declare function permissionAnswer(params: unknown): {
+    optionId: string;
+    granted: boolean;
+} | null;
+export declare function createAcpConversation(options: AcpConversationOptions): AcpConversation;
+/** What the gateway reads back from a conversation's retained record. */
+export type AcpEnvelope = {
+    sessionId: string | null;
+    protocolError: string | null;
+    finalMessage: string | null;
+    /** The agent's own usage report, unattested: never priced. */
+    reportedUsage: string | null;
+    initObserved: boolean;
+    /** True only when the prompt's answer was `end_turn`. */
+    promptConsumed: boolean;
+    diagnostic: string | null;
+    /** A failure terminal, when the prompt was answered with anything but end_turn or the conversation failed. */
+    terminal: {
+        failed: true;
+        text: string | null;
+        code: string;
+    } | null;
+    /** The models the agent offered at session/new (the conformance check records them). */
+    offered: string[];
+    /** Who the agent said it is at initialize. */
+    agent: {
+        name: string;
+        version: string;
+    } | null;
+    /** The prompt's stop reason, when it answered with one. */
+    stop: string | null;
+    /** How the agent's process ended, as the runner saw it: on its own after stdin closed, or by our SIGTERM or kill;
+     * and whether anything of its group was still alive at the reap. Null when the runner wrote none. */
+    exit: {
+        how: "eof" | "term" | "kill" | "self" | "error";
+        leftover: boolean;
+        timedOut: boolean;
+    } | null;
+};
+/** Read a conversation's retained record. Lines not typed `acp.*` are ignored. */
+export declare function acpParse(stdout: string): AcpEnvelope;