rovecode 0.4.0-beta.2 → 0.4.0

package/src/account/login.ts

@@ -0,0 +1,158 @@
+/** RFC 8628 device authorization grant, client side — the half `rovecode login` runs.
+ *
+ *  The CLI asks the site's API for a code, shows the human where to approve it, and polls until a token
+ *  appears. `fetch`, `sleep` and `now` are injectable so the whole loop is unit-testable without a server
+ *  or a real clock. */
+
+import { loadOrCreateAccountKey, signProof, type AccountKey } from "./keys.ts";
+import { saveAccount, type LinkedAccount } from "./store";
+
+export interface DeviceCodeInfo {
+  userCode: string;
+  verificationUri: string;
+  expiresIn: number;
+}
+
+export interface DeviceLoginOptions {
+  apiBase: string;
+  clientId?: string;
+  scope?: string;
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+  /** the machine's PoP key; defaults to ~/.rovecode/account-key.json (created on first use) */
+  keys?: AccountKey;
+  /** called once with the code and URL to show the human */
+  onCode?: (info: DeviceCodeInfo) => void;
+}
+
+export type LoginResult = { ok: true; account: LinkedAccount } | { ok: false; reason: "denied" | "expired" | "invalid" | "network" };
+
+const defaultSleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+interface Probe {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+async function postJson(doFetch: typeof fetch, url: string, body: unknown): Promise<Probe | null> {
+  try {
+    const res = await doFetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+    return { status: res.status, body: await readJson(res) };
+  } catch {
+    return null;
+  }
+}
+
+async function readJson(res: Response): Promise<Record<string, unknown>> {
+  try {
+    const text = await res.text();
+    return text.trim() ? (JSON.parse(text) as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function runDeviceLogin(opts: DeviceLoginOptions): Promise<LoginResult> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const sleep = opts.sleep ?? defaultSleep;
+  const now = opts.now ?? (() => Date.now());
+  const base = opts.apiBase.replace(/\/+$/, "");
+
+  const keys = opts.keys ?? loadOrCreateAccountKey();
+  const start = await postJson(doFetch, `${base}/api/auth/device/code`, {
+    client_id: opts.clientId ?? "rovecode-cli",
+    scope: opts.scope,
+    public_jwk: keys.publicJwk,
+  });
+  if (!start || start.status !== 200) return { ok: false, reason: "network" };
+  const deviceCode = typeof start.body.device_code === "string" ? start.body.device_code : "";
+  const userCode = typeof start.body.user_code === "string" ? start.body.user_code : "";
+  if (!deviceCode || !userCode) return { ok: false, reason: "network" };
+
+  const expiresIn = typeof start.body.expires_in === "number" ? start.body.expires_in : 600;
+  let interval = typeof start.body.interval === "number" ? start.body.interval : 5;
+  const verificationUri = typeof start.body.verification_uri === "string" ? start.body.verification_uri : `${base}/cli-auth`;
+  opts.onCode?.({ userCode, verificationUri, expiresIn });
+
+  const deadline = now() + expiresIn * 1000;
+  while (now() < deadline) {
+    await sleep(interval * 1000);
+    const poll = await postJson(doFetch, `${base}/api/auth/device/token`, { device_code: deviceCode });
+    if (!poll) return { ok: false, reason: "network" };
+
+    if (poll.status === 200) {
+      const token = typeof poll.body.access_token === "string" ? poll.body.access_token : "";
+      if (!token) return { ok: false, reason: "network" };
+      const user = (poll.body.user ?? {}) as { id?: unknown; email?: unknown; name?: unknown };
+      const apiKey = typeof poll.body.api_key === "string" ? poll.body.api_key : "";
+      const account: LinkedAccount = {
+        token,
+        userId: typeof user.id === "string" ? user.id : "",
+        email: typeof user.email === "string" ? user.email : "",
+        name: typeof user.name === "string" ? user.name : "",
+        apiBase: base,
+        linkedAt: new Date(now()).toISOString(),
+        ...(apiKey ? { apiKey } : {}),
+      };
+      saveAccount(account);
+      return { ok: true, account };
+    }
+
+    switch (poll.body.error) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        interval += 5;
+        continue;
+      case "access_denied":
+        return { ok: false, reason: "denied" };
+      case "expired_token":
+        return { ok: false, reason: "expired" };
+      case "invalid_grant":
+        return { ok: false, reason: "invalid" };
+      default:
+        return { ok: false, reason: "network" };
+    }
+  }
+  return { ok: false, reason: "expired" };
+}
+
+/** Verify a hand-pasted `rc_live_…` token against /api/auth/me. A proof signed with this machine's key goes
+ *  along: a bound token answers only when the keys match (i.e. the token was issued to this machine); an
+ *  unbound legacy token still passes on bearer alone — the documented fallback. */
+export async function linkWithToken(
+  apiBase: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+  keys: AccountKey = loadOrCreateAccountKey(),
+  now: () => number = () => Date.now(),
+): Promise<LinkedAccount | null> {
+  const base = apiBase.replace(/\/+$/, "");
+  token = token.trim();
+  if (!token) return null;
+  const meUrl = `${base}/api/auth/me`;
+  try {
+    const res = await fetchImpl(meUrl, {
+      headers: {
+        authorization: `Bearer ${token}`,
+        dpop: signProof(keys, { htm: "GET", htu: meUrl, iat: Math.floor(now() / 1000), accessToken: token }),
+      },
+    });
+    if (!res.ok) return null;
+    const body = await readJson(res);
+    const user = (body.user ?? {}) as { id?: unknown; email?: unknown; name?: unknown };
+    const account: LinkedAccount = {
+      token,
+      userId: typeof user.id === "string" ? user.id : "",
+      email: typeof user.email === "string" ? user.email : "",
+      name: typeof user.name === "string" ? user.name : "",
+      apiBase: base,
+      linkedAt: new Date().toISOString(),
+    };
+    saveAccount(account);
+    return account;
+  } catch {
+    return null;
+  }
+}

package/src/account/provision.ts

@@ -0,0 +1,47 @@
+/** After a device login the CLI holds a rove_live_… inference key the site minted for it. This turns
+ *  that key into a ready-to-use "rovecode" provider — registered, key stored, made the default when
+ *  nothing else is — so `rovecode login` alone takes a fresh install to a working model. */
+
+import { saveCredential } from "../providers/auth.ts";
+import { ProviderRegistry } from "../providers/registry.ts";
+
+export const ROVECODE_BASE_URL = "https://api.rovecode.dev/v1";
+export const ROVECODE_KEY_ENV = "ROVECODE_API_KEY";
+export const ROVECODE_DEFAULT_MODEL = "grok-4.7";
+
+export interface ProvisionResult {
+  /** the provider entry was created now (false = it already existed) */
+  added: boolean;
+  keyStored: boolean;
+  /** it became the default model (false = the user already had a default — left untouched) */
+  defaulted: boolean;
+  error?: string;
+}
+
+export function ensureRovecodeProvider(apiKey: string, cwd: string = process.cwd()): ProvisionResult {
+  const reg = new ProviderRegistry(cwd);
+  let added = false;
+  if (reg.get("rovecode") === undefined) {
+    const r = reg.add(
+      {
+        id: "rovecode",
+        baseUrl: ROVECODE_BASE_URL,
+        protocol: "openai",
+        keyEnv: ROVECODE_KEY_ENV,
+        defaultModel: ROVECODE_DEFAULT_MODEL,
+      },
+      "user",
+    );
+    if ("error" in r) return { added: false, keyStored: false, defaulted: false, error: r.error };
+    added = true;
+  }
+  saveCredential("rovecode", apiKey, ROVECODE_KEY_ENV);
+  reg.refresh();
+
+  let defaulted = false;
+  if (reg.defaultRef() === null) {
+    const d = reg.setDefault(`rovecode/${ROVECODE_DEFAULT_MODEL}`, "user");
+    if (!("error" in d)) defaulted = true;
+  }
+  return { added, keyStored: true, defaulted };
+}

package/src/account/store.ts

@@ -0,0 +1,63 @@
+/** The linked rovecode account (device-flow login): what `rovecode login` writes and `rovecode account`
+ *  reads. Kept apart from providers/credentials.json on purpose — that file is the provider API keys the
+ *  router resolves, and an account token is neither a provider nor a model key. */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { rovecodeHome } from "../providers/auth.ts";
+
+export interface LinkedAccount {
+  /** the rc_live_… access token the site's device API issued */
+  token: string;
+  userId: string;
+  email: string;
+  name: string;
+  /** the API base that issued it — a token is only valid there */
+  apiBase: string;
+  /** the rove_live_… inference key minted alongside the login — the CLI configures the rovecode
+   *  provider with this so the user never touches the dashboard's key page */
+  apiKey?: string;
+  /** ISO 8601 */
+  linkedAt: string;
+}
+
+export function accountPath(): string {
+  return join(rovecodeHome(), "account.json");
+}
+
+export function loadAccount(): LinkedAccount | null {
+  try {
+    const parsed = JSON.parse(readFileSync(accountPath(), "utf8")) as Partial<LinkedAccount>;
+    if (typeof parsed.token !== "string" || parsed.token.length === 0) return null;
+    return {
+      token: parsed.token,
+      userId: typeof parsed.userId === "string" ? parsed.userId : "",
+      email: typeof parsed.email === "string" ? parsed.email : "",
+      name: typeof parsed.name === "string" ? parsed.name : "",
+      apiBase: typeof parsed.apiBase === "string" ? parsed.apiBase : "",
+      ...(typeof parsed.apiKey === "string" && parsed.apiKey.length > 0 ? { apiKey: parsed.apiKey } : {}),
+      linkedAt: typeof parsed.linkedAt === "string" ? parsed.linkedAt : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveAccount(account: LinkedAccount): void {
+  mkdirSync(rovecodeHome(), { recursive: true, mode: 0o700 });
+  const path = accountPath();
+  writeFileSync(path, JSON.stringify(account, null, 2) + "\n", { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* best-effort, same Windows caveat as providers/auth.ts */
+  }
+}
+
+/** returns false when there was nothing to remove */
+export function clearAccount(): boolean {
+  const path = accountPath();
+  if (!existsSync(path)) return false;
+  rmSync(path);
+  return true;
+}

package/src/acp/server.ts

@@ -0,0 +1,373 @@
+/** ACP agent endpoint (port #15): `rovecode acp` speaks Agent Client Protocol v1
+ *  over stdio via the official SDK (@zed-industries/agent-client-protocol@0.4.5,
+ *  Apache-2.0), mapped onto the ONE agentLoop (ADR-003).
+ *
+ *  Mapping:
+ *    initialize            → protocol v1 + capabilities (no loadSession; text + image prompts, port #34)
+ *    prompt image blocks   → ImagePart via imageFromBase64 (the bytes decide the type; the TUI's
+ *                            per-image size cap and ≤8-per-message count cap apply), staged on the
+ *                            session store so the loop's user message carries them (no loop change);
+ *                            any bad block → JSON-RPC invalid params {error} before a run starts
+ *    session/new           → bootRuntime (same stores/tools/config as repl/tui); a sandbox
+ *                            misconfig / unavailable rung in the client's cwd (port #27)
+ *                            → JSON-RPC invalid params {cwd, error: one-line message}
+ *    session/prompt        → agentLoop run; RunEvents stream out as session/update
+ *      message_update      → agent_message_chunk
+ *      tool_execution_*    → tool_call / tool_call_update
+ *      tool_call_failed    → tool_call created directly in "failed" status
+ *    approval (ADR-005)    → session/request_permission; declined/cancelled/unsupported → deny
+ *    run_end done/budget   → stopReason end_turn / max_turn_requests
+ *    run_end error         → JSON-RPC error response (RequestError is the ACP error
+ *                            channel — the SDK converts it to a wire-level response,
+ *                            so the never-throw seam ends at this boundary by design)
+ *    session/cancel        → aborts the run's AbortController (kills the in-flight
+ *                            provider fetch and tool subprocesses mid-turn — port #21),
+ *                            races any outstanding permission ask to deny, then closes
+ *                            the generator → "cancelled"
+ */
+
+import {
+  AgentSideConnection, RequestError, PROTOCOL_VERSION, ndJsonStream,
+  type Agent, type Stream,
+  type InitializeRequest, type InitializeResponse,
+  type AuthenticateRequest, type AuthenticateResponse,
+  type NewSessionRequest, type NewSessionResponse,
+  type PromptRequest, type PromptResponse, type CancelNotification,
+  type ContentBlock, type SessionNotification, type ToolCallContent,
+  type ToolKind as AcpToolKind,
+} from "@zed-industries/agent-client-protocol";
+import { basename } from "node:path";
+import { noModelHint } from "../core/voice.ts";
+import { Readable, Writable } from "node:stream";
+import { agentLoop, SteeringQueue } from "../core/loop.ts";
+import { bootRuntime, type Runtime } from "../cli/runtime.ts";
+import { checkImageCount, imageFromBase64 } from "../core/images.ts";
+import { SandboxConfigError } from "../core/sandbox-config.ts";
+import type { ApprovalFn, ImagePart, RunEvent, StreamFn } from "../core/types.ts";
+
+export interface AcpOptions {
+  /** test/dev override threaded into createRuntime; undefined = provider from env */
+  stream?: StreamFn | null;
+  /** allow-all permissions: no ACP permission round-trips (ROVECODE_YOLO parity) */
+  yolo?: boolean;
+}
+
+type SessionUpdate = SessionNotification["update"];
+type RunStatus = "done" | "stopped" | "error" | "budget";
+
+interface AcpSessionState {
+  rt: Runtime;
+  steering: SteeringQueue;
+  active: {
+    gen: AsyncGenerator<RunEvent>;
+    cancelled: boolean;
+    /** per-run controller (port #21): session/cancel aborts it, killing the
+     *  in-flight provider fetch and every ToolContext.signal consumer */
+    abort: AbortController;
+    /** resolves null when session/cancel lands — raced against an outstanding
+     *  request_permission so a hung client cannot wedge the session (HIGH-G2) */
+    onCancel: Promise<null>;
+    fireCancel: () => void;
+  } | null;
+  permSeq: number;
+}
+
+// ---------- translation helpers (RunEvent / house shapes → ACP shapes) ----------
+
+export interface PromptParts {
+  /** the loop's goal text: text blocks, resource links, inlined embedded text resources */
+  goal: string;
+  /** port #34: decoded image blocks, in prompt order */
+  images: ImagePart[];
+  /** the FIRST problem (unsupported/mismatched mime, oversize, more than 8 images) — the caller
+   *  rejects the whole prompt, nothing is half-sent */
+  error?: string;
+}
+
+/** Prompt content blocks → goal text + image parts. Baseline blocks (text, resource_link) per
+ *  spec; embedded text resources are inlined; image blocks decode through imageFromBase64 (the
+ *  bytes decide the type — a disagreeing mimeType is an error, like the TUI's loader) under the
+ *  same per-image size cap and per-message count cap as /attach; audio stays unsupported. */
+export function promptParts(blocks: ContentBlock[]): PromptParts {
+  const parts: string[] = [];
+  const images: ImagePart[] = [];
+  let error: string | undefined;
+  for (const b of blocks) {
+    if (b.type === "text") parts.push(b.text);
+    else if (b.type === "resource_link") parts.push(`[resource: ${b.uri}]`);
+    else if (b.type === "resource" && "text" in b.resource) {
+      parts.push(`<context uri="${b.resource.uri}">\n${b.resource.text}\n</context>`);
+    } else if (b.type === "image") {
+      const name = b.uri && !b.uri.startsWith("data:") ? basename(b.uri) : undefined; // display name: the file the client sent
+      const res = imageFromBase64(b.data, b.mimeType, name !== undefined ? { name } : {});
+      if ("error" in res) error ??= res.error; else images.push(res);
+    } else parts.push(`[unsupported ${b.type} content omitted]`);
+  }
+  error ??= checkImageCount(images.length);
+  const goal = parts.join("\n");
+  return error === undefined ? { goal, images } : { goal, images, error };
+}
+
+/** Text-only view of a prompt (image blocks travel separately — promptParts). */
+export function promptText(blocks: ContentBlock[]): string { return promptParts(blocks).goal; }
+
+const TOOL_KINDS: Record<string, AcpToolKind> = {
+  read: "read", edit: "edit", write: "edit", bash: "execute",
+  skill_view: "read", skills_list: "search", mcp_list: "search",
+  mcp_call: "other", memory_edit: "other", web_fetch: "fetch",
+};
+
+export function kindFor(tool: string): AcpToolKind {
+  return TOOL_KINDS[tool] ?? "other";
+}
+
+/** Human title for a tool call: name plus the most salient argument. */
+export function titleFor(tool: string, args: unknown): string {
+  if (args && typeof args === "object") {
+    const a = args as Record<string, unknown>;
+    const salient = a.path ?? a.command ?? a.name ?? a.url;
+    if (salient !== undefined) return `${tool}: ${String(salient).slice(0, 120)}`;
+  }
+  return tool;
+}
+
+function asRawInput(args: unknown): Record<string, unknown> {
+  if (args && typeof args === "object" && !Array.isArray(args)) return args as Record<string, unknown>;
+  return args === undefined ? {} : { value: args };
+}
+
+function textContent(text: string): ToolCallContent[] {
+  return [{ type: "content", content: { type: "text", text } }];
+}
+
+/** RunEvent → session/update payload; null for events with no ACP counterpart
+ *  (run_start, turn_start/end, steer, compaction — lifecycle stays house-side). */
+export function updateForEvent(ev: RunEvent): SessionUpdate | null {
+  switch (ev.type) {
+    case "message_update":
+      return { sessionUpdate: "agent_message_chunk", content: { type: "text", text: ev.delta } };
+    case "tool_execution_start":
+      return {
+        sessionUpdate: "tool_call", toolCallId: ev.callId, title: titleFor(ev.tool, ev.args),
+        kind: kindFor(ev.tool), status: "in_progress", rawInput: asRawInput(ev.args),
+      };
+    case "tool_execution_update":
+      return { sessionUpdate: "tool_call_update", toolCallId: ev.callId, content: textContent(ev.note) };
+    case "tool_execution_end":
+      return {
+        sessionUpdate: "tool_call_update", toolCallId: ev.callId,
+        status: ev.ok ? "completed" : "failed",
+        content: textContent(ev.output), rawOutput: { output: ev.output },
+      };
+    case "tool_call_failed":
+      // calls rejected before execution (permission_denied / truncated / not_found /
+      // invalid_args) never got a tool_call create — create directly in failed status
+      return {
+        sessionUpdate: "tool_call", toolCallId: ev.callId, title: `tool call failed (${ev.reason})`,
+        kind: "other", status: "failed", content: textContent(ev.detail),
+      };
+    default:
+      return null;
+  }
+}
+
+// ---------- the ACP agent ----------
+
+export class RovecodeAcpAgent implements Agent {
+  private readonly sessions = new Map<string, AcpSessionState>();
+
+  constructor(private readonly conn: AgentSideConnection, private readonly opts: AcpOptions = {}) {}
+
+  async initialize(_params: InitializeRequest): Promise<InitializeResponse> {
+    // we implement exactly v1: reply with our version; older clients disconnect (spec rule)
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      agentCapabilities: {
+        loadSession: false,
+        promptCapabilities: { image: true, audio: false, embeddedContext: true }, // image: port #34 (promptParts)
+      },
+      authMethods: [],
+    };
+  }
+
+  async authenticate(_params: AuthenticateRequest): Promise<AuthenticateResponse> {
+    return {}; // no auth methods advertised; provider credentials come from env
+  }
+
+  async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
+    // v1 scope: params.mcpServers is not wired into the runtime — the runtime
+    // already loads project-level .rovecode/mcp.json + .mcp.json (port #3)
+    let rt: Runtime;
+    try {
+      rt = await bootRuntime({ cwd: params.cwd, stream: this.opts.stream });
+    } catch (e) {
+      // port #27: the client's cwd asked for a rung this machine cannot provide (or
+      // its sandbox.json is broken) — invalid params carrying the one-line message,
+      // the same shape as "unknown session" below (the parameter names something
+      // we cannot serve); the agent process stays up for the next session/new
+      if (e instanceof SandboxConfigError) throw RequestError.invalidParams({ cwd: params.cwd, error: e.message });
+      throw e;
+    }
+    // live registry: once the user runs `rovecode provider add` / `rovecode auth set`, the next
+    // session/new succeeds without restarting the agent process
+    const noProvider = rt.noProviderReason();
+    if (!rt.stream || noProvider !== null) {
+      throw RequestError.authRequired({
+        details: noProvider ?? noModelHint("cli"),
+      });
+    }
+    this.sessions.set(rt.sessionId, { rt, steering: rt.steering, active: null, permSeq: 0 }); // port #26: runtime queue → task notes reach the next prompt
+    return { sessionId: rt.sessionId };
+  }
+
+  async prompt(params: PromptRequest): Promise<PromptResponse> {
+    const s = this.sessions.get(params.sessionId);
+    if (!s) throw RequestError.invalidParams({ sessionId: params.sessionId, error: "unknown session" });
+    if (s.active) throw RequestError.invalidRequest({ error: "a prompt is already running for this session" });
+    const stream = s.rt.stream;
+    const noProvider = s.rt.noProviderReason();
+    if (!stream || noProvider !== null) throw RequestError.authRequired(noProvider !== null ? { details: noProvider } : undefined);
+
+    const { goal, images, error } = promptParts(params.prompt);
+    // port #34: a bad image block (not png/jpeg/gif/webp, mime disagrees with the bytes, oversize,
+    // 9+ images) rejects the prompt as invalid params BEFORE any run — same "nothing staged" outcome
+    // as the TUI's error note; the session stays usable for the corrected prompt
+    if (error !== undefined) throw RequestError.invalidParams({ error });
+    const model = { provider: s.rt.provider?.id ?? "mock", model: s.rt.defaultModel || "default" };
+    const def = s.rt.buildDef(model);
+    const cfg = s.rt.buildCfg(this.opts.yolo ?? false, this.approvalFor(params.sessionId, s));
+    const abort = new AbortController(); // port #21: one controller per run
+    s.rt.tasks.bindRun(abort.signal); // port #26: session/cancel also cancels the run's background tasks
+    const deps = {
+      stream, registry: s.rt.registry, store: s.rt.store,
+      tools: s.rt.registry.list().map((t) => t.schema), guard: s.rt.guard,
+      hooks: s.rt.hooks, // port #29: .rovecode/hooks.{ts,js} of the session cwd
+      cwd: s.rt.cwd, // HIGH-G1: the client's authoritative session cwd reaches ToolContext
+      signal: abort.signal, // port #21: session/cancel kills in-flight fetch/tools mid-turn
+    };
+
+    // port #34: the store folds the staged images into the loop's user message when it lands in
+    // append() — the same seam TUI /attach uses; the active guard above means no other user entry
+    // can slip in between (task steers drain AFTER the goal message, loop.ts)
+    if (images.length > 0) s.rt.store.stageAttachments(images);
+    const gen = agentLoop(def, goal, {}, cfg, deps, s.steering);
+    let fireCancel: () => void = () => {};
+    const onCancel = new Promise<null>((resolve) => { fireCancel = () => resolve(null); });
+    const active = { gen, cancelled: false, abort, onCancel, fireCancel };
+    s.active = active;
+    let end: { status: RunStatus; summary: string } | null = null;
+    try {
+      for await (const ev of gen) {
+        if (active.cancelled) break; // session/cancel landed; loop finally aborts tools
+        if (ev.type === "run_end") { end = { status: ev.status, summary: ev.summary }; break; }
+        const update = updateForEvent(ev);
+        if (update) await this.conn.sessionUpdate({ sessionId: params.sessionId, update });
+      }
+    } finally {
+      s.active = null;
+    }
+
+    if (active.cancelled || end === null) return { stopReason: "cancelled" };
+    switch (end.status) {
+      case "done": return { stopReason: "end_turn" };
+      case "budget": return { stopReason: "max_turn_requests" };
+      case "stopped": return { stopReason: "cancelled" };
+      case "error": throw RequestError.internalError({ details: end.summary });
+    }
+  }
+
+  async cancel(params: CancelNotification): Promise<void> {
+    const active = this.sessions.get(params.sessionId)?.active;
+    if (!active) return;
+    active.cancelled = true;
+    // port #21: abort the run's controller FIRST — the in-flight provider fetch
+    // dies and tool subprocesses are killed mid-turn, so the generator below
+    // reaches a settle point quickly instead of finishing the turn.
+    active.abort.abort();
+    // HIGH-G2: unblock an outstanding request_permission (→ deny) — without
+    // this a crashed client / closed popup leaves the run suspended inside the
+    // approval await forever and the session permanently "already running".
+    active.fireCancel();
+    // close the generator as the follow-through: runs the loop's finally blocks.
+    // Queues behind any pending next(), so the settle stays cooperative.
+    await active.gen.return(undefined as never).then(() => undefined, () => undefined);
+  }
+
+  /** MED-G3: close every session runtime's MCP children. runAcpStdio calls this
+   *  when stdin closes — without it, `rovecode acp` in an MCP-configured project
+   *  outlives the client (children keep running until the parent is killed). */
+  async shutdown(): Promise<void> {
+    const closing: Promise<unknown>[] = [];
+    for (const s of this.sessions.values()) {
+      s.rt.tasks.cancelAll(); // port #26: background children die with the agent, never after it
+      closing.push(s.rt.hooks.close()); // port #29: session_close per session runtime
+      if (s.rt.mcp) closing.push(s.rt.mcp.close().catch(() => {}));
+    }
+    await Promise.all(closing);
+  }
+
+  /** ADR-005 approval seam → session/request_permission. Deny is the safe default:
+   *  declined, cancelled, unknown option, or a client that errors (unsupported). */
+  private approvalFor(sessionId: string, s: AcpSessionState): ApprovalFn {
+    return async (req) => {
+      const toolCallId = `perm-${++s.permSeq}`;
+      let outcome: { outcome: "cancelled" } | { outcome: "selected"; optionId: string };
+      try {
+        const ask = this.conn.requestPermission({
+          sessionId,
+          toolCall: {
+            toolCallId, title: titleFor(req.tool, req.revisedArgs), kind: kindFor(req.tool),
+            status: "pending", rawInput: asRawInput(req.revisedArgs),
+          },
+          options: [
+            { optionId: "allow-once", name: "Allow once", kind: "allow_once" },
+            { optionId: "allow-always", name: "Allow always", kind: "allow_always" },
+            { optionId: "reject-once", name: "Deny", kind: "reject_once" },
+          ],
+        });
+        void ask.then(() => undefined, () => undefined); // raced loser must not surface as unhandled
+        // HIGH-G2: session/cancel must be able to interrupt an outstanding ask
+        // (client crash / closed popup) — cancel wins the race and maps to deny
+        const resp = s.active ? await Promise.race([ask, s.active.onCancel]) : await ask;
+        if (resp === null) return "deny"; // cancelled mid-permission
+        outcome = resp.outcome;
+      } catch {
+        return "deny"; // client rejected the request itself → unsupported → deny
+      }
+      if (outcome.outcome !== "selected") return "deny";
+      if (outcome.optionId === "allow-once") return "once";
+      if (outcome.optionId === "allow-always") return "always";
+      return "deny";
+    };
+  }
+}
+
+// ---------- wiring ----------
+
+/** Attach an ACP agent to a bidirectional message stream (tests use an
+ *  in-process duplex; the CLI uses stdio via runAcpStdio). The agent handle is
+ *  returned alongside the connection so callers can shutdown() its sessions. */
+export function serveAcp(io: Stream, opts: AcpOptions = {}): { conn: AgentSideConnection; agent: RovecodeAcpAgent } {
+  let agent!: RovecodeAcpAgent; // the factory runs synchronously inside the ctor
+  const conn = new AgentSideConnection((c) => (agent = new RovecodeAcpAgent(c, opts)), io);
+  return { conn, agent };
+}
+
+/** `rovecode acp`: serve ACP v1 over stdio until the client closes stdin.
+ *  stdout carries protocol frames only — nothing else may print there. */
+export function runAcpStdio(opts: AcpOptions = {}): Promise<void> {
+  // node:stream/web and lib.dom stream types diverge on getReader() overloads;
+  // the runtime objects are the same web streams, so bridge via unknown
+  const io = ndJsonStream(
+    Writable.toWeb(process.stdout) as unknown as WritableStream<Uint8Array>,
+    Readable.toWeb(process.stdin) as unknown as ReadableStream<Uint8Array>,
+  );
+  const { agent } = serveAcp(io, opts);
+  return new Promise<void>((resolve) => {
+    // MED-G3: reap MCP children before resolving, or the process outlives a
+    // closed editor in MCP-configured projects (children hold the event loop)
+    const done = () => { void agent.shutdown().then(() => resolve(), () => resolve()); };
+    process.stdin.once("end", done);
+    process.stdin.once("close", done);
+  });
+}