rovecode 0.3.2 → 0.4.0-beta.2

package/src/server/http.ts

@@ -1,291 +0,0 @@
-/** 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

@@ -1,246 +0,0 @@
-/** 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

@@ -1,102 +0,0 @@
-/** 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;
-}