rovecode 0.3.2

package/src/server/http.ts

@@ -0,0 +1,291 @@
+/** Headless HTTP server (port #19): pattern-level port of opencode's client/server
+ *  split (MIT, snapshot research/source_snapshots/opencode-2026).
+ *
+ *  Patterns ported (citations against the snapshot):
+ *  - client/server split: the TUI/CLI are HTTP clients of a headless server —
+ *    packages/opencode/src/cli/cmd/serve.ts:6-24 (serve command → Server.listen),
+ *    packages/sdk/js (client generated from the server's OpenAPI spec),
+ *    packages/opencode/src/cli/cmd/tui.ts:11 (TUI imports @opencode-ai/sdk).
+ *  - session surface: routes/instance/httpapi/groups/session.ts — root "/session"
+ *    (:29), create POST (:203), prompt POST (:316), list GET (:111).
+ *  - GET /doc serving the OpenAPI JSON: routes/instance/httpapi/server.ts:190
+ *    (docRoute) + :188 (lazy spec build). We hand-author the object (openapi.ts).
+ *  - SSE event streaming: routes/instance/httpapi/handlers/event.ts:69-85
+ *    (text/event-stream response, no-cache headers).
+ *  - loopback bind by default: cli/network.ts:12-15 (hostname default "127.0.0.1").
+ *
+ *  NOT ported: opencode's implementation is Effect-based (server.ts imports
+ *  effect / @effect/platform-node / effect/unstable/httpapi). ADR-001 rejects
+ *  Effect idioms — this file is plain Bun.serve + the ONE agentLoop (ADR-003)
+ *  reused via createRuntime. v1 approvals are policy-only: no interactive
+ *  approver over HTTP; a permission rule with effect "prompt" fails the tool
+ *  call at the registry seam (core/tools.ts:87-93). See APPROVALS_NOTE in /doc.
+ *
+ *  Never-throw seam: route handlers are wrapped — an exception becomes a JSON
+ *  500; a mid-stream loop error becomes a final run_end error frame, never a
+ *  socket reset or a crashed server. */
+
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { bootRuntime, type Runtime } from "../cli/runtime.ts";
+import { noModelHint } from "../core/voice.ts";
+import { SandboxConfigError } from "../core/sandbox-config.ts";
+import { agentLoop, SteeringQueue } from "../core/loop.ts";
+import { listSessions } from "../core/session.ts";
+import type { ModelRef, RunEvent, StreamFn } from "../core/types.ts";
+import { buildOpenApiDoc } from "./openapi.ts";
+
+export const DEFAULT_PORT = 4100;
+export const DEFAULT_HOSTNAME = "127.0.0.1";
+/** request-body bound: prompt bodies over this fail with a clean JSON 413
+ *  (checked against content-length before the body is read). Bun.serve's
+ *  maxRequestBodySize is set to 2× this as a transport ceiling for clients
+ *  that lie about / omit content-length (chunked): those are cut at the
+ *  socket instead of ballooning RSS. */
+export const MAX_BODY_BYTES = 1024 * 1024;
+
+export interface ServerOptions {
+  /** TCP port; default 4100; 0 = ephemeral (tests) */
+  port?: number;
+  /** bind address; default 127.0.0.1 (loopback-only, opencode cli/network.ts:15) */
+  hostname?: string;
+  /** project root; sessions live in <cwd>/.rovecode/sessions */
+  cwd?: string;
+  /** injectable provider stream (tests); undefined = resolve from env; null = no stream */
+  stream?: StreamFn | null;
+  /** allow-all permission rules; default false = policy rules with prompt-effect
+   *  gates, which FAIL over HTTP (no approver) — see APPROVALS_NOTE */
+  yolo?: boolean;
+}
+
+export interface RovecodeServer {
+  port: number;
+  hostname: string;
+  url: string;
+  /** closes the listener and in-flight SSE sockets, aborts every in-flight
+   *  run's controller (port #21: the in-flight provider fetch and tool
+   *  subprocesses die mid-turn), then closes every session runtime's MCP
+   *  children. Returns without awaiting the aborted generators' final settle. */
+  stop(): Promise<void>;
+}
+
+interface SessionEntry {
+  runtime: Runtime;
+  running: boolean;
+  /** the in-flight run's controller (port #21) — DELETE /session/:id/prompt and
+   *  stop() abort it; null when idle. Cleared by the pump's settle, like `running`. */
+  abort: AbortController | null;
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** SSE framing (bar): `event: <type>\ndata: <json>\n\n`. */
+function frame(ev: RunEvent): string {
+  return `event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`;
+}
+
+/** Pump loop events into an SSE response; the stream closes on run_end.
+ *  Client disconnects abort the run's controller (port #21): the in-flight
+ *  provider fetch dies and tool subprocesses are killed mid-turn, then the
+ *  generator settles at its next suspension point. `running` is cleared ONLY
+ *  from the pump's finally — when the generator has actually released the
+ *  session — so the 409 one-run-per-session invariant holds across
+ *  disconnects (MED-F1). */
+function sseResponse(run: AsyncGenerator<RunEvent>, onSettled: () => void, abort: () => void): Response {
+  const enc = new TextEncoder();
+  let settled = false;
+  const settle = () => { if (!settled) { settled = true; onSettled(); } };
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      try {
+        for await (const ev of run) {
+          controller.enqueue(enc.encode(frame(ev)));
+          if (ev.type === "run_end") break; // bar: stream closes on run_end
+        }
+      } catch (e) {
+        // never-throw seam: a loop/enqueue error becomes a terminal error frame
+        const end: RunEvent = { type: "run_end", status: "error", summary: e instanceof Error ? e.message : String(e) };
+        try { controller.enqueue(enc.encode(frame(end))); } catch { /* consumer gone */ }
+      } finally {
+        settle();
+        try { controller.close(); } catch { /* cancelled/closed already */ }
+      }
+    },
+    cancel() {
+      // client hung up mid-run: abort the run's controller (kills the in-flight
+      // fetch / tool subprocesses — port #21), then close the generator as the
+      // follow-through. Do NOT settle here: the pump's finally settles
+      // truthfully once the generator finishes; an eager settle let a second
+      // run share this session's store (MED-F1).
+      abort();
+      void Promise.resolve(run.return(undefined)).catch(() => {});
+    },
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      // headers per opencode handlers/event.ts:78-83
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache, no-transform",
+      "x-accel-buffering": "no",
+    },
+  });
+}
+
+function bodyText(body: unknown): string | null {
+  if (body && typeof body === "object" && typeof (body as { text?: unknown }).text === "string") {
+    return (body as { text: string }).text;
+  }
+  return null;
+}
+
+function bodyModel(body: unknown): ModelRef | null {
+  if (body && typeof body === "object" && (body as { model?: unknown }).model && typeof (body as { model?: unknown }).model === "object") {
+    const m = (body as { model: { provider?: unknown; model?: unknown } }).model;
+    if (typeof m.provider === "string" && typeof m.model === "string") return { provider: m.provider, model: m.model };
+  }
+  return null;
+}
+
+export function startServer(opts: ServerOptions = {}): RovecodeServer {
+  const hostname = opts.hostname ?? DEFAULT_HOSTNAME;
+  const cwd = opts.cwd ?? process.cwd();
+  const sessionsRoot = join(cwd, ".rovecode", "sessions");
+  const yolo = opts.yolo ?? false;
+  const sessions = new Map<string, SessionEntry>();
+
+  const createSession = async (): Promise<Response> => {
+    const id = randomUUID();
+    // Reuse the ONE runtime construction every surface uses (cli/runtime.ts):
+    // same stores, same tools, same provider resolution. Injectable stream for tests.
+    let runtime: Runtime;
+    try {
+      runtime = await bootRuntime({ cwd, sessionId: id, stream: opts.stream });
+    } catch (e) {
+      // port #27: sandbox misconfig / unavailable configured rung → 503 with the
+      // one-line message (the server cwd cannot provide the requested executor)
+      if (e instanceof SandboxConfigError) return json({ error: e.message }, 503);
+      throw e; // never-throw seam below turns anything else into a JSON 500
+    }
+    sessions.set(id, { runtime, running: false, abort: null });
+    return json({ id }, 201);
+  };
+
+  const prompt = async (id: string, req: Request): Promise<Response> => {
+    const entry = sessions.get(id);
+    if (!entry) return json({ error: `unknown session ${id}` }, 404);
+    // LOW-MED-F4: bound the request body BEFORE reading it (declared size), and
+    // the parsed text after — an unbounded body was a local RSS balloon.
+    const declared = Number(req.headers.get("content-length") ?? "0");
+    if (declared > MAX_BODY_BYTES) return json({ error: `request body too large (max ${MAX_BODY_BYTES} bytes)` }, 413);
+    let body: unknown;
+    try { body = await req.json(); } catch { return json({ error: "body must be JSON" }, 400); }
+    const text = bodyText(body);
+    if (text === null) return json({ error: 'body must be {"text": string}' }, 400);
+    if (text.length > MAX_BODY_BYTES) return json({ error: `text too large (max ${MAX_BODY_BYTES} chars)` }, 413);
+    if (entry.running) return json({ error: "a run is already in progress for this session" }, 409);
+    const rt = entry.runtime;
+    const stream = rt.stream;
+    // live: a provider added after boot (rovecode provider add / auth set) serves the next request
+    const noProvider = rt.noProviderReason();
+    if (!stream || noProvider !== null) return json({ error: noProvider ?? noModelHint("cli") }, 503);
+    const model: ModelRef = bodyModel(body) ?? { provider: rt.provider?.id ?? "mock", model: rt.defaultModel || "default" };
+    const def = rt.buildDef(model);
+    // no interactive ApprovalFn — buildCfg installs the port-#9 exec-policy wrapper:
+    // allow-listed argv auto-runs, forbidden is denied, prompt-classified fails closed
+    // as tool_call_failed/permission_denied (core/tools.ts:87-93)
+    const cfg = rt.buildCfg(yolo, undefined);
+    const ac = new AbortController(); // port #21: one controller per run
+    rt.tasks.bindRun(ac.signal); // port #26: DELETE / disconnect / stop() also cancel the run's background tasks
+    const run = agentLoop(def, text, {}, cfg, {
+      stream, registry: rt.registry, store: rt.store,
+      tools: rt.registry.list().map((t) => t.schema), guard: rt.guard, planReminder: rt.planReminder,
+      hooks: rt.hooks, // port #29: .rovecode/hooks.{ts,js} of the server cwd
+      cwd: rt.cwd, // session cwd reaches ToolContext (same gap as ACP HIGH-G1)
+      signal: ac.signal, // port #21: DELETE / disconnect / stop() kill in-flight work
+    }, rt.steering); // port #26: the session's queue — background-task notes land on the next prompt
+    entry.running = true;
+    entry.abort = ac;
+    return sseResponse(run, () => { entry.running = false; entry.abort = null; }, () => ac.abort());
+  };
+
+  /** DELETE /session/:id/prompt — cancel the in-flight run (port #21). Aborting
+   *  the controller kills the provider fetch / tool subprocesses; the run's own
+   *  SSE stream then ends with run_end status "stopped". `running` still clears
+   *  only from the pump's settle, so the 409 invariant is untouched: the session
+   *  frees when the generator has actually released it. opencode exposes the
+   *  same operation as POST /session/:sessionID/abort → SessionPrompt.cancel
+   *  (routes/instance/httpapi/groups/session.ts:91,253; handlers/session.ts:232). */
+  const cancelPrompt = (id: string): Response => {
+    const entry = sessions.get(id);
+    if (!entry) return json({ error: `unknown session ${id}` }, 404);
+    const live = entry.abort !== null;
+    entry.abort?.abort();
+    return json({ cancelled: live });
+  };
+
+  /** GET /session/:id/tasks — background-task status (port #26): the session runtime's
+   *  TaskManager snapshot (TaskInfo[], oldest first). opencode exposes the same registry
+   *  through its job service (packages/core/src/background-job.ts list/get). */
+  const listTasks = (id: string): Response => {
+    const entry = sessions.get(id);
+    if (!entry) return json({ error: `unknown session ${id}` }, 404);
+    return json(entry.runtime.tasks.list());
+  };
+
+  const route = async (req: Request): Promise<Response> => {
+    const path = new URL(req.url).pathname;
+    if (req.method === "POST" && path === "/session") return createSession();
+    const m = /^\/session\/([^/]+)\/prompt$/.exec(path);
+    if (req.method === "POST" && m) return prompt(m[1]!, req);
+    if (req.method === "DELETE" && m) return cancelPrompt(m[1]!);
+    const t = /^\/session\/([^/]+)\/tasks$/.exec(path);
+    if (req.method === "GET" && t) return listTasks(t[1]!);
+    if (req.method === "GET" && path === "/sessions") return json(listSessions(sessionsRoot));
+    if (req.method === "GET" && path === "/doc") return json(buildOpenApiDoc(api.url));
+    return json({ error: `no route for ${req.method} ${path}` }, 404);
+  };
+
+  const server = Bun.serve({
+    hostname,
+    port: opts.port ?? DEFAULT_PORT,
+    idleTimeout: 0, // SSE runs outlive Bun's default idle timeout
+    // transport ceiling (LOW-MED-F4): bodies without/with a lying content-length
+    // are cut here (socket close); declared oversizes get a clean 413 in prompt()
+    maxRequestBodySize: MAX_BODY_BYTES * 2,
+    async fetch(req) {
+      // never-throw seam: handler exceptions become JSON 500s, the server survives
+      try { return await route(req); }
+      catch (e) { return json({ error: e instanceof Error ? e.message : String(e) }, 500); }
+    },
+  });
+
+  const api: RovecodeServer = {
+    port: server.port ?? 0,
+    hostname,
+    url: `http://${hostname}:${server.port}`,
+    async stop() {
+      await server.stop(true);
+      // port #21: abort every in-flight run — the provider fetch and tool
+      // subprocesses die now instead of running on after the sockets closed.
+      for (const entry of sessions.values()) entry.abort?.abort();
+      for (const { runtime } of sessions.values()) runtime.tasks.cancelAll(); // port #26: background children die with the server, never after it
+      // MED-F3: reap MCP children — every POST /session spawns one set via
+      // createRuntime; without this an unauthenticated loopback port is an
+      // unbounded local spawn primitive that outlives the server.
+      const closing: Promise<unknown>[] = [];
+      for (const { runtime } of sessions.values()) {
+        runtime.bashJobs.dispose(); // #55: background shell jobs die with their session
+        closing.push(runtime.hooks.close()); // port #29: session_close per session runtime
+        if (runtime.mcp) closing.push(runtime.mcp.close().catch(() => {}));
+      }
+      await Promise.all(closing);
+    },
+  };
+  return api;
+}

package/src/server/openapi.ts

@@ -0,0 +1,246 @@
+/** Hand-authored OpenAPI 3.1 document for the rovecode server surface (port #19).
+ *  opencode serves its spec at GET /doc — packages/opencode/src/server/routes/
+ *  instance/httpapi/server.ts:190 (route) + :188 (lazy OpenApi.fromApi(PublicApi))
+ *  — and generates its client SDK from that spec (packages/sdk/js, @hey-api/openapi-ts).
+ *  Their spec is derived from Effect httpapi endpoint schemas; ADR-001 rejects Effect
+ *  idioms, and this surface is five routes, so the object is written by hand — no
+ *  codegen dependency, the doc IS the source of truth for what the server exposes. */
+
+/** Honesty note (bar requirement): served verbatim in the doc so HTTP clients know
+ *  interactive approvals do not exist in v1. */
+export const APPROVALS_NOTE =
+  "v1 approvals are policy-only: the server runs with rule-based permissions and has no " +
+  "interactive approver over HTTP. A tool call whose permission rule resolves to effect " +
+  "\"prompt\" is NOT paused for approval — it surfaces as a failed tool call " +
+  "(tool_call_failed, reason permission_denied, \"approval required but no approver " +
+  "connected\") and the run continues. Start the server with --yolo (allow-all rules) " +
+  "or provide allow rules to let gated tools run.";
+
+/** RunEvent discriminator values (src/core/types.ts RunEvent union). Hand-listed:
+ *  types are erased at runtime, and the doc is hand-authored by design. */
+export const RUN_EVENT_TYPES = [
+  "run_start", "turn_start", "message_update", "reasoning_update",
+  "tool_execution_start", "tool_execution_update", "tool_execution_end",
+  "tool_call_failed", "compaction", "turn_end", "steer", "run_end",
+] as const;
+
+const errorResponse = (description: string) => ({
+  description,
+  content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } },
+});
+
+/** Build the OpenAPI 3.1 object. `serverUrl` is the actually-bound base URL. */
+export function buildOpenApiDoc(serverUrl: string): Record<string, unknown> {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "rovecode server",
+      version: "0.1.0",
+      description:
+        "Headless HTTP surface over the one rovecode agent loop (ADR-003). " +
+        "Five routes: create a session, prompt it (SSE stream of typed run events; " +
+        "DELETE the same path cancels the in-flight run mid-turn), " +
+        "list its background tasks, list sessions, and this document. " + APPROVALS_NOTE,
+    },
+    servers: [{ url: serverUrl }],
+    paths: {
+      "/session": {
+        post: {
+          operationId: "session.create",
+          summary: "Create a new session",
+          description: "Creates a session backed by the append-only JSONL session store and returns its id.",
+          responses: {
+            "201": {
+              description: "Session created",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["id"],
+                    properties: { id: { type: "string", description: "Session id (also the session directory name)" } },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/session/{id}/prompt": {
+        post: {
+          operationId: "session.prompt",
+          summary: "Run the agent loop on a session and stream its events",
+          description:
+            "Runs one agent loop over the session with the given text as the goal. " +
+            "The response is a Server-Sent Events stream: each event is framed as " +
+            "`event: <RunEvent.type>` + `data: <RunEvent JSON>`, and the stream closes " +
+            "after the terminal run_end event. " + APPROVALS_NOTE,
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "string" }, description: "Session id from POST /session" },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  required: ["text"],
+                  properties: {
+                    text: { type: "string", description: "The user goal for this run" },
+                    model: {
+                      type: "object",
+                      description: "Optional model override; defaults to the server's resolved provider/model",
+                      required: ["provider", "model"],
+                      properties: { provider: { type: "string" }, model: { type: "string" } },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description: "SSE stream of RunEvent frames; closes after run_end",
+              content: { "text/event-stream": { schema: { $ref: "#/components/schemas/RunEvent" } } },
+            },
+            "400": errorResponse("Body is not JSON or lacks a string `text`"),
+            "404": errorResponse("Unknown session id"),
+            "409": errorResponse("A run is already in progress for this session"),
+            "503": errorResponse("No provider configured — run `rovecode setup` (or rovecode provider add + rovecode auth set, or set ROVECODE_BASE_URL/ROVECODE_API_KEY)"),
+          },
+        },
+        delete: {
+          operationId: "session.cancel",
+          summary: "Cancel the in-flight run on a session",
+          description:
+            "Aborts the running prompt's AbortController: the in-flight provider fetch and " +
+            "tool subprocesses are killed mid-turn, and the run's SSE stream ends with a " +
+            "run_end event of status \"stopped\". The session stays busy (409 on new prompts) " +
+            "until that stream has actually settled. Idempotent: cancelling an idle session " +
+            "returns cancelled: false.",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "string" }, description: "Session id from POST /session" },
+          ],
+          responses: {
+            "200": {
+              description: "Cancellation signalled (cancelled: true) or nothing was running (cancelled: false)",
+              content: {
+                "application/json": {
+                  schema: {
+                    type: "object",
+                    required: ["cancelled"],
+                    properties: { cancelled: { type: "boolean" } },
+                  },
+                },
+              },
+            },
+            "404": errorResponse("Unknown session id"),
+          },
+        },
+      },
+      "/session/{id}/tasks": {
+        get: {
+          operationId: "session.tasks",
+          summary: "List the session's background subagent tasks",
+          description:
+            "Snapshot of the session's background tasks (port #26): child agent sessions started by " +
+            "the `task` tool, oldest first, with status queued|running|done|failed|cancelled, timing, " +
+            "the child's final text (done) or error (failed). Tasks are process-local and not durable " +
+            "across server restarts. Completion notes reach the model as steering on the session's next prompt.",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: "string" }, description: "Session id from POST /session" },
+          ],
+          responses: {
+            "200": {
+              description: "Task snapshots",
+              content: {
+                "application/json": {
+                  schema: { type: "array", items: { $ref: "#/components/schemas/TaskInfo" } },
+                },
+              },
+            },
+            "404": errorResponse("Unknown session id"),
+          },
+        },
+      },
+      "/sessions": {
+        get: {
+          operationId: "session.list",
+          summary: "List sessions",
+          description: "Scans the session root and returns summaries, sorted by updatedAt descending. Corrupt or foreign directories are skipped, never errors.",
+          responses: {
+            "200": {
+              description: "Session summaries",
+              content: {
+                "application/json": {
+                  schema: { type: "array", items: { $ref: "#/components/schemas/SessionSummary" } },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/doc": {
+        get: {
+          operationId: "doc",
+          summary: "This OpenAPI 3.1 document",
+          description: "Returns the OpenAPI 3.1 JSON describing exactly this server surface.",
+          responses: {
+            "200": { description: "OpenAPI 3.1 document", content: { "application/json": { schema: { type: "object" } } } },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        Error: {
+          type: "object",
+          required: ["error"],
+          properties: { error: { type: "string" } },
+        },
+        SessionSummary: {
+          type: "object",
+          required: ["id", "createdAt", "updatedAt", "entryCount", "preview"],
+          properties: {
+            id: { type: "string" },
+            createdAt: { type: "number" },
+            updatedAt: { type: "number" },
+            entryCount: { type: "number" },
+            preview: { type: "string", description: "First user-message text, single line, ≤80 chars" },
+          },
+        },
+        RunEvent: {
+          type: "object",
+          description:
+            "Typed agent-loop event (src/core/types.ts RunEvent union), discriminated by `type`. " +
+            "The SSE `event:` field always equals this `type` field.",
+          required: ["type"],
+          properties: {
+            type: { type: "string", enum: [...RUN_EVENT_TYPES] },
+          },
+          additionalProperties: true,
+        },
+        TaskInfo: {
+          type: "object",
+          description: "Background subagent task snapshot (src/core/tasks.ts TaskInfo).",
+          required: ["id", "label", "agent", "goal", "isolated", "depth", "status", "createdAt"],
+          properties: {
+            id: { type: "string", description: "Task id (t1, t2, …; scoped to the session)" },
+            label: { type: "string" },
+            agent: { type: "string", description: "Agent definition the child runs" },
+            goal: { type: "string", description: "Bounded preview of the child's goal (≤200 chars)" },
+            isolated: { type: "boolean", description: "Ran in a worktree copy; file changes merge back as a patch on success" },
+            depth: { type: "number", description: "Child depth (root-started tasks run at 1)" },
+            status: { type: "string", enum: ["queued", "running", "done", "failed", "cancelled"] },
+            createdAt: { type: "number" },
+            startedAt: { type: "number" },
+            finishedAt: { type: "number" },
+            summary: { type: "string", description: "The child's final text (status done), ≤4000 chars" },
+            error: { type: "string", description: "Failure reason (status failed) or \"cancelled\"" },
+            usage: { type: "object", properties: { input: { type: "number" }, output: { type: "number" } } },
+            patchLines: { type: "number", description: "Isolated children: line count of the merged-back patch" },
+          },
+        },
+      },
+    },
+  };
+}

package/src/sextant/card-hits.ts

@@ -0,0 +1,102 @@
+/** Click zones for the modal card (approval verdicts, question options, free text, skip).
+ *
+ *  Why this exists: the card is the single most frequent interaction in the surface — every gated
+ *  edit, every shell command, every ask_user question goes through it — and until now it answered
+ *  only to the arrow keys. Clicking `allow` did nothing at all: keys.ts's onMouse walks the hit zones
+ *  the drawers registered that frame, and nobody registered any for the card, so the click fell
+ *  through to the "focus the panel under the pointer" fallback. That is the complaint "most things do
+ *  not respond to clicks, it only works with the arrow keys", in its most-used place.
+ *
+ *  Geometry, not painting: draw-messages.ts owns how the card looks, this file owns where its targets
+ *  landed. The two are kept honest by deriving everything from the SAME exported helpers the painter
+ *  uses (areas, cardShape, cardRows) rather than re-deriving row counts — a second copy of the layout
+ *  arithmetic would drift the moment the card grew a row.
+ *
+ *  Two subtleties the card forces:
+ *    - The card is CLIPPED from the top when it does not fit (draw-messages keeps the tail so the
+ *      buttons stay reachable), so a row's screen y is its index minus the hidden count, and a target
+ *      scrolled off the top has no zone at all rather than a wrong one.
+ *    - The approval verdicts share ONE row, laid out horizontally, so they need x ranges; the question
+ *      card gives every option its own row.
+ *
+ *  `confirm` is false for exactly one target, the free-text row: clicking it means "I want to type
+ *  here", not "submit an empty answer". Every other target is a labelled button, and a click on a
+ *  button is the decision — the same as clicking OK in any dialog. */
+
+import { areas, cardRows, cardShape, questionRows, SKIP_LABEL, VERDICT_LABEL } from "./draw-messages.ts";
+import { inner } from "./draw-util.ts";
+import { strWidth } from "./screen.ts";
+import type { Rect, SextantState, Theme } from "./types.ts";
+
+export interface CardHit {
+  rect: Rect;
+  /** the value card.selected takes when this target is clicked */
+  index: number;
+  /** replay Enter after selecting (a button); false leaves the caret on the row (free text) */
+  confirm: boolean;
+}
+
+/** button() in draw-messages renders a label as ` label `, and the verdict row separates them by two
+ *  spaces at indent 2. */
+const BUTTON_PAD = 2;
+const BUTTON_GAP = 2;
+const ROW_INDENT = 2;
+
+/** The card's clickable targets in screen coordinates, or [] when no card is open, the panel is too
+ *  small to draw one, or every target is clipped away. `rect` is the messages panel, as passed to
+ *  drawMessages. */
+export function cardHits(rect: Rect, s: SextantState, theme: Theme): CardHit[] {
+  const card = s.card;
+  if (card === null || card === undefined) return [];
+  if (rect.w < 4 || rect.h < 3) return []; // drawMessages paints nothing at all below this
+  const B = inner(rect);
+  const { cardH, msgH, maxDetail } = areas(B, s);
+  if (cardH <= 0) return [];
+
+  const all = cardRows(card, B.w, maxDetail, theme);
+  // when the card is taller than its slot the painter keeps the TAIL: rows [hidden..] are on screen
+  const hidden = all.length - cardH;
+  const yOf = (i: number): number | null => {
+    const v = i - hidden;
+    return v < 0 || v >= cardH ? null : B.y + msgH + v;
+  };
+  const out: CardHit[] = [];
+
+  if (card.kind === "approval") {
+    // the verdicts are the last row, so they survive clipping — that is why the painter keeps the tail
+    const y = yOf(all.length - 1);
+    if (y === null) return [];
+    let x = B.x + ROW_INDENT;
+    for (const [i, v] of card.verdicts.entries()) {
+      const w = strWidth(VERDICT_LABEL[v] ?? String(v)) + BUTTON_PAD;
+      if (x + w > B.x + B.w) break; // a verdict pushed past the right edge was never drawn
+      out.push({ rect: { x, y, w, h: 1 }, index: i, confirm: true });
+      x += w + BUTTON_GAP;
+    }
+    return out;
+  }
+
+  // question card: blank, q question rows, one row per option, [free text, wrapped], skip, hint.
+  // The row arithmetic comes from questionRows — the same helper the painter and the caret use — so
+  // the three cannot disagree; cardShape is still consulted for the clip.
+  const opts = card.prompt.options ?? [];
+  const { q, freeRows } = questionRows(card, B.w);
+  const shape = cardShape(card, B.w, maxDetail);
+  if (shape.total !== 1 + q + opts.length + freeRows + 2) return []; // the painter and the helper disagree: register nothing rather than wrong zones
+  const push = (rowIndex: number, index: number, w: number, confirm: boolean, h = 1): void => {
+    const y = yOf(rowIndex);
+    if (y !== null && w > 0) out.push({ rect: { x: B.x + ROW_INDENT, y, w, h }, index, confirm });
+  };
+  const full = Math.max(0, B.w - ROW_INDENT);
+  for (const [i, o] of opts.entries()) push(1 + q + i, i, Math.min(strWidth(o) + BUTTON_PAD, full), true);
+  // the free-text field is one zone across all its wrapped rows: select it, do not answer for the human.
+  // Rows clipped off the top shrink the zone from above (the first visible row is where it starts).
+  if (freeRows > 0) {
+    const first = 1 + q + opts.length;
+    const visibleFrom = Math.max(first, hidden);
+    const rows = first + freeRows - visibleFrom;
+    if (rows > 0) push(visibleFrom, opts.length, full, false, rows);
+  }
+  push(1 + q + opts.length + freeRows, opts.length + (freeRows > 0 ? 1 : 0), Math.min(strWidth(SKIP_LABEL) + BUTTON_PAD, full), true);
+  return out;
+}