rovecode 0.4.0-beta.3 → 0.4.0

package/src/telemetry/otel.ts

@@ -0,0 +1,353 @@
+/** PORT #39 — OpenTelemetry span export over the port-#29 hook seam (ADR-010: spans exportable as
+ *  OTel; per-step token/latency/cost accounting). A consumer of core/hooks.ts, nothing more: it is a
+ *  HookSet attached with `hooks.add(set, "otel")`, so the loop/tools/runner stay untouched.
+ *
+ *  Shape — ONE trace per run: `rovecode.run` (pre_run → post_run) ⊃ `rovecode.turn` (turn_start → turn_end,
+ *  one per model iteration) ⊃ `rovecode.tool` (pre_tool → post_tool; parent = the turn that ISSUED the
+ *  call). The loop yields turn_end BEFORE it executes the turn's calls (core/loop.ts:232 then :295),
+ *  so a tool span starts after its parent turn ended — OTLP permits a child to outlive its parent and
+ *  the run span brackets everything; keeping the turn = the model step keeps its latency honest.
+ *  Per-step accounting reads the ONE source of usage, the session store (Message.usage/origin — the
+ *  tui/cost.ts + cli/output.ts idiom): each turn span carries the tokens/cost of the assistant message
+ *  it appended, the run span the sums since the run began; latency is the span itself. Compactions
+ *  and calls that never reached pre_tool (policy deny, unknown tool, truncated) become span EVENTS on
+ *  the current turn (`rovecode.compaction`, `rovecode.tool_call_failed`) — a zero-length "step" is noise as a
+ *  span. Attribute policy follows pi (telemetry/README.md:387-389): ids, sizes and outcomes only —
+ *  never the goal, tool args/output, headers or credentials (output_bytes, not output).
+ *
+ *  Export — hand-encoded OTLP/HTTP JSON (ExportTraceServiceRequest; OTLP/JSON mapping: ids as hex,
+ *  int64 as decimal strings, enums as integers) POSTed ONCE per run at post_run to <endpoint>/v1/traces
+ *  (ROVECODE_OTEL_ENDPOINT with or without the suffix; ROVECODE_OTEL_HEADERS "k=v,k2=v2" ride along). The POST
+ *  is fire-and-forget on a 5s REF'D timer (hooks.ts withTimeout idiom — Bun unrefs AbortSignal.timeout),
+ *  tracked so flush() and session_close await the outstanding ones; post_run never blocks the run and
+ *  the export path never throws. A failed export is ONE bounded warning: direct consumers pass
+ *  onWarning; the runtime wiring has no write access to hooks.warnings, so the set remembers the
+ *  failure and raises it from its NEXT lifecycle hook (pre_run of the following run, or session_close),
+ *  which the runner's isolation records as exactly one note ("otel: … hook threw: OTLP export to …
+ *  failed …") that every surface already streams. The raise happens after that hook's own work.
+ *
+ *  ZERO OVERHEAD OFF — cli/runtime.ts calls createOtelHooks ONLY when ROVECODE_OTEL_ENDPOINT is set; off,
+ *  no set is attached and the runner's tap short-circuits (hooks.ts:272). otelDebug.constructed is the
+ *  spy the off-path test pins ("exporter never constructed").
+ *
+ *  Run boundaries (fix-wave 4, #39): post_run is the export trigger, and core/loop.ts fires it for a
+ *  run whose CONSUMER closed the generator (serve disconnect, ACP cancel, TUI Esc: hooks.ts
+ *  observer.close) with status "stopped" — cancelled runs export and release their RunState;
+ *  session_close still drains a leftover state (a generator dropped without .return()) as "stopped"
+ *  before its flush. Tool spans are keyed per issuing turn, so a call id a provider reuses across
+ *  turns (the SSE adapter's `tc<idx>` fallback, providers/stream.ts) is one span PER TURN.
+ *  `rovecode.tool_calls` counts ISSUED calls — dispatched (spans) plus never-dispatched (tool_call_failed
+ *  events) — the same count as `rovecode run --output json` toolCalls (cli/output.ts keys per issuing turn
+ *  too, LOW-B), with ONE residual: a run aborted while a call waited between its pre_tool hook and its
+ *  execution (tools.ts:141 returns without an event) has that call as a span but no toolCalls entry —
+ *  the hook side saw pre_tool, the event side saw nothing. A guard-stubbed
+ *  call (tool events without a pre_tool) carries rovecode.failure_reason=loop_guard. An endpoint that is
+ *  not an absolute http(s) URL (`http://`, `host:4318`) disables export with ONE note instead of a
+ *  5 s stall per run against host "v1".
+ *
+ *  Sources (pi @ 853a80d, MIT — naming/shape reference, no code copied; header credit only):
+ *  - packages/agent/src/harness/telemetry.ts:235-256 `pi.harness.run` (outcome attribute; status error
+ *    when the run fails), :327-352 `pi.harness.turn` ("one assistant response and its tool batch",
+ *    parent run), :399-451 `pi.harness.tool` (parents turn|run; `pi.tool.name`, `pi.tool.call_id`,
+ *    `pi.tool.is_error`; status error when execution returns an error) → rovecode.run / rovecode.turn /
+ *    rovecode.tool with rovecode.status, rovecode.turn, rovecode.tool, rovecode.call_id, rovecode.ok.
+ *  - :94-103 `pi.ai.usage.{input,output,cache_read,cache_write}_tokens` + `.cost`, :88-92
+ *    `pi.ai.response.stop_reason`, :55-64 `pi.ai.provider`/`pi.ai.model`, :194 `pi.session.id` →
+ *    rovecode.tokens.{input,output,cacheRead,cacheWrite} (NormalizedUsage spelling), rovecode.cost_usd,
+ *    rovecode.stop_reason, rovecode.model.provider/model, rovecode.session_id.
+ *  Deviations: pi ships no exporter (telemetry/README.md:11 — adapter-owned) and records no timestamps
+ *  (memory.ts:203-218); rovecode ships the OTLP/HTTP exporter and wall-clock ns times. */
+
+import { randomBytes } from "node:crypto";
+import type { HookCtx, HookSet, HookToolCall, RunResult } from "../core/hooks.ts";
+import type { Message, RunEvent, ToolOutput } from "../core/types.ts";
+import { costUsd, type PricingRow } from "../core/usage.ts";
+import { ModelCatalog } from "../providers/catalog.ts";
+import { bool, dbl, encodeTraceRequest, int, str, type OtelSpan, type OtlpValue } from "./otlp.ts";
+
+// wire types + encoder live in otlp.ts (pure); re-exported so this stays the module consumers import
+export { encodeTraceRequest, unixNano, type OtelSpan, type OtlpKeyValue, type OtlpSpan, type OtlpTraceRequest, type OtlpValue } from "./otlp.ts";
+
+export const DEFAULT_EXPORT_TIMEOUT_MS = 5000;
+export const OTLP_TRACES_PATH = "/v1/traces";
+/** test spy: exporters constructed in this process — the off-path bar is "never constructed" */
+export const otelDebug = { constructed: 0 };
+
+/** ModelCatalog.lookup's shape (cli/output.ts PricingSource); tests inject fixed pricing */
+export interface PricingSource { lookup(provider: string, model: string): { pricing?: PricingRow } | undefined }
+
+export interface OtelOptions {
+  /** collector base URL (…/v1/traces is appended) or the full traces URL */
+  endpoint: string;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+  /** wall clock in ms (fractions kept); default performance.timeOrigin + performance.now() */
+  now?: () => number;
+  /** resource service.name; default "rovecode" */
+  serviceName?: string;
+  /** live view of the session store — usage/origin per assistant message */
+  messages: () => Message[];
+  /** per-message pricing (Message.origin → row); default: a ModelCatalog built at the first export */
+  pricing?: PricingSource;
+  timeoutMs?: number;
+  /** export failures for direct consumers; absent → raised through the runner (header) */
+  onWarning?: (note: string) => void;
+}
+export interface OtelHooks extends HookSet {
+  flush(): Promise<void>;
+  /** runs recorded but not yet exported — 0 once every run reached post_run (diagnostic seam) */
+  openRuns(): number;
+}
+
+// ---------- per-run state ----------
+
+interface RunState {
+  run: OtelSpan; spans: OtelSpan[]; turn?: OtelSpan; lastTurn?: OtelSpan;
+  /** tool spans by `<issuing turn spanId>:<callId>` — a reused id is a new span in a new turn */
+  tools: Map<string, OtelSpan>;
+  /** issued calls: dispatched (spans) + never-dispatched (tool_call_failed events) */
+  calls: number;
+  /** store length at pre_run (run totals) and at the last turn_end (per-turn usage) */
+  baseline: number; seen: number;
+}
+
+const OK: OtelSpan["status"] = { code: 1 };
+const ERROR = (message: string): OtelSpan["status"] => ({ code: 2, message });
+
+// ---------- env / endpoint / headers ----------
+
+/** null unless ROVECODE_OTEL_ENDPOINT is set (blank = unset) — the runtime constructs nothing on null */
+export function otelOptionsFromEnv(env: Record<string, string | undefined> = process.env): Pick<OtelOptions, "endpoint" | "headers"> | null {
+  const endpoint = (env["ROVECODE_OTEL_ENDPOINT"] ?? "").trim();
+  return endpoint ? { endpoint, headers: parseOtelHeaders(env["ROVECODE_OTEL_HEADERS"]) } : null;
+}
+
+/** "k=v,k2=v2" (OTEL_EXPORTER_OTLP_HEADERS shape): first "=" splits, so values may contain "=";
+ *  blank or key-less entries are skipped; values are taken raw (no percent-decoding). */
+export function parseOtelHeaders(text: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const part of (text ?? "").split(",")) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    const key = part.slice(0, eq).trim();
+    if (key) out[key] = part.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+/** base URL or full traces URL (either, with or without trailing slashes) → <base>/v1/traces */
+export function normalizeEndpoint(endpoint: string): string {
+  const base = endpoint.trim().replace(/\/+$/, "");
+  return base.endsWith(OTLP_TRACES_PATH) ? base : base + OTLP_TRACES_PATH;
+}
+
+/** an absolute http(s) URL with a host — `http://` does not parse and `host:4318` parses host-less,
+ *  and both would normalize to `http:/v1/traces` (host "v1") and stall every export to the timeout */
+export function validEndpoint(endpoint: string): boolean {
+  try { const u = new URL(endpoint.trim()); return (u.protocol === "http:" || u.protocol === "https:") && u.hostname !== ""; } catch { return false; }
+}
+
+// ---------- the hook set ----------
+
+export function createOtelHooks(opts: OtelOptions): OtelHooks {
+  otelDebug.constructed++;
+  const url = normalizeEndpoint(opts.endpoint);
+  const headers = { ...(opts.headers ?? {}), "content-type": "application/json" };
+  const fetchFn = opts.fetch ?? fetch;
+  const now = opts.now ?? defaultNow;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_EXPORT_TIMEOUT_MS;
+  const service = opts.serviceName ?? "rovecode";
+  let pricing: PricingSource | undefined = opts.pricing;
+  const runs = new Map<string, RunState>();
+  const pending = new Set<Promise<void>>();
+  let failed = 0, lastFailure = "";
+
+  const stateOf = (ctx: HookCtx): RunState | undefined => (ctx.runId === undefined ? undefined : runs.get(ctx.runId));
+  const attach = (st: RunState, name: string, parent: OtelSpan): OtelSpan => {
+    const s: OtelSpan = { traceId: st.run.traceId, spanId: hex(8), parentSpanId: parent.spanId, name, start: now(), attrs: new Map(), events: [], status: { code: 0 } };
+    st.spans.push(s);
+    return s;
+  };
+  const end = (s: OtelSpan, status: OtelSpan["status"]): void => { if (s.end === undefined) { s.end = now(); s.status = status; } };
+  const event = (s: OtelSpan, name: string, attrs: [string, OtlpValue][]): void => { s.events.push({ name, time: now(), attrs: new Map(attrs) }); };
+  /** a call's parent = the turn that issued it (turn_end precedes the turn's tool events — header) */
+  const issuer = (st: RunState): OtelSpan => st.lastTurn ?? st.run;
+  const toolKey = (st: RunState, callId: string): string => `${issuer(st).spanId}:${callId}`;
+  /** the tool span for a call — opened by whichever of pre_tool / tool_execution_start arrives first;
+   *  a span the START event has to open never saw pre_tool: the loop-guard stub path (tools.ts:88-93) */
+  const openTool = (st: RunState, callId: string, tool?: string, fromStart = false): OtelSpan => {
+    const key = toolKey(st, callId);
+    let s = st.tools.get(key);
+    if (!s) {
+      s = attach(st, "rovecode.tool", issuer(st));
+      s.attrs.set("rovecode.call_id", str(callId));
+      if (fromStart) s.attrs.set("rovecode.failure_reason", str("loop_guard"));
+      st.tools.set(key, s);
+      st.calls++;
+    }
+    if (tool !== undefined && !s.attrs.has("rovecode.tool")) s.attrs.set("rovecode.tool", str(tool));
+    return s;
+  };
+  const settleTool = (s: OtelSpan, ok: boolean, output: string): void => {
+    if (s.end !== undefined) return; // post_tool already settled it; tool_execution_end only adds duration
+    s.attrs.set("rovecode.ok", bool(ok));
+    s.attrs.set("rovecode.output_bytes", int(Buffer.byteLength(output, "utf8")));
+    const name = s.attrs.get("rovecode.tool");
+    end(s, ok ? OK : ERROR(`tool ${name && "stringValue" in name ? name.stringValue : "call"} failed`));
+  };
+  /** tokens summed + cost priced PER MESSAGE at Message.origin (cli/output.ts summarize): any
+   *  usage-bearing message without catalog pricing → cost unknown → attribute omitted, never 0 */
+  const account = (s: OtelSpan, msgs: Message[]): void => {
+    const u = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    let cost: number | null = 0;
+    for (const m of msgs) {
+      if (!m.usage) continue;
+      const n = { input: m.usage.input, output: m.usage.output, cacheRead: m.usage.cacheRead ?? 0, cacheWrite: m.usage.cacheWrite ?? 0 };
+      u.input += n.input; u.output += n.output; u.cacheRead += n.cacheRead; u.cacheWrite += n.cacheWrite;
+      if (cost === null || (n.input === 0 && n.output === 0 && n.cacheRead === 0 && n.cacheWrite === 0)) continue;
+      const row = m.origin ? (pricing ??= new ModelCatalog()).lookup(m.origin.provider, m.origin.model)?.pricing : undefined;
+      const c = row ? costUsd(n, row) : undefined;
+      cost = c === undefined ? null : cost + c;
+    }
+    s.attrs.set("rovecode.tokens.input", int(u.input)); s.attrs.set("rovecode.tokens.output", int(u.output));
+    s.attrs.set("rovecode.tokens.cacheRead", int(u.cacheRead)); s.attrs.set("rovecode.tokens.cacheWrite", int(u.cacheWrite));
+    if (cost !== null) s.attrs.set("rovecode.cost_usd", dbl(cost));
+    const served = msgs.at(-1)?.origin; // the model that SERVED (router fallback may differ from the request)
+    if (served) { s.attrs.set("rovecode.model.provider", str(served.provider)); s.attrs.set("rovecode.model.model", str(served.model)); }
+  };
+
+  // --- export ---
+  const warn = (note: string): void => {
+    if (opts.onWarning) { opts.onWarning(note); return; }
+    failed++; lastFailure = note;
+  };
+  const fail = (reason: string): void => warn(`OTLP export to ${url} failed: ${reason}`);
+  const usable = validEndpoint(opts.endpoint); // ONE note at construction (raised by the first lifecycle hook), then no POSTs
+  if (!usable) warn(`ROVECODE_OTEL_ENDPOINT ${JSON.stringify(opts.endpoint)} is not an absolute http(s) URL — OTel export disabled`);
+  /** deferred failure → thrown from a lifecycle hook → one runner warning (header); no-op with onWarning */
+  const raise = (): void => {
+    if (failed === 0) return;
+    const n = failed; failed = 0;
+    throw new Error(n === 1 ? lastFailure : `${lastFailure} (${n} exports failed)`);
+  };
+  const post = async (body: string): Promise<void> => {
+    if (!usable) return;
+    const ac = new AbortController();
+    try {
+      const res = await withTimeout(fetchFn(url, { method: "POST", headers, body, signal: ac.signal }), timeoutMs, ac);
+      if (res === TIMED_OUT) { fail(`timed out after ${timeoutMs}ms`); return; }
+      await res.arrayBuffer().catch(() => undefined); // release the connection; a success body is `{}`
+      if (!res.ok) fail(`HTTP ${res.status}`);
+    } catch (e) { fail(errText(e)); }
+  };
+  const track = (p: Promise<void>): void => { pending.add(p); void p.then(() => { pending.delete(p); }); };
+  const flush = async (): Promise<void> => { while (pending.size > 0) await Promise.all([...pending]); };
+  /** the run's end: open turn/tool spans close here (status UNSET), totals + status land on the run
+   *  span, ONE POST — from post_run, or from session_close for a state no post_run ever released */
+  const finish = (st: RunState, status: RunResult["status"]): void => {
+    const t = now();
+    for (const s of st.spans) if (s.end === undefined && s !== st.run) s.end = t;
+    st.run.attrs.set("rovecode.status", str(status));
+    st.run.attrs.set("rovecode.turns", int(st.spans.filter((s) => s.name === "rovecode.turn").length));
+    st.run.attrs.set("rovecode.tool_calls", int(st.calls));
+    account(st.run, opts.messages().slice(st.baseline).filter((m) => m.role === "assistant"));
+    st.run.end = t;
+    st.run.status = status === "done" || status === "stopped" ? OK : ERROR(status); // budget/error did not complete
+    track(post(JSON.stringify(encodeTraceRequest(service, st.spans))));
+  };
+
+  return {
+    flush,
+    openRuns: () => runs.size,
+    pre_run(ctx) {
+      if (ctx.runId === undefined) return;
+      const run: OtelSpan = { traceId: hex(16), spanId: hex(8), name: "rovecode.run", start: now(), attrs: new Map(), events: [], status: { code: 0 } };
+      run.attrs.set("rovecode.session_id", str(ctx.sessionId)); run.attrs.set("rovecode.run_id", str(ctx.runId));
+      const len = opts.messages().length;
+      runs.set(ctx.runId, { run, spans: [run], tools: new Map(), calls: 0, baseline: len, seen: len });
+      raise();
+    },
+    on_event(ctx, ev: RunEvent) {
+      const st = stateOf(ctx);
+      if (!st) return;
+      switch (ev.type) {
+        case "turn_start": {
+          if (st.turn) end(st.turn, st.turn.status); // defensive: the loop never nests turns
+          st.turn = st.lastTurn = attach(st, "rovecode.turn", st.run);
+          st.turn.attrs.set("rovecode.turn", int(ev.turn));
+          break;
+        }
+        case "turn_end": {
+          const t = st.turn ?? st.lastTurn;
+          if (!t) break;
+          t.attrs.set("rovecode.stop_reason", str(ev.stopReason));
+          const msgs = opts.messages();
+          account(t, msgs.slice(st.seen).filter((m) => m.role === "assistant"));
+          st.seen = msgs.length;
+          end(t, ev.stopReason === "error" ? ERROR("error") : OK);
+          st.turn = undefined;
+          break;
+        }
+        case "tool_execution_start": openTool(st, ev.callId, ev.tool, true); break;
+        case "tool_execution_end": {
+          const s = openTool(st, ev.callId);
+          s.attrs.set("rovecode.duration_ms", int(ev.durationMs)); // the dispatcher's own measure (tools.ts:170)
+          settleTool(s, ev.ok, ev.output);
+          break;
+        }
+        case "tool_call_failed": {
+          const s = st.tools.get(toolKey(st, ev.callId));
+          if (s) { s.attrs.set("rovecode.ok", bool(false)); s.attrs.set("rovecode.failure_reason", str(ev.reason)); end(s, ERROR(ev.reason)); }
+          else { st.calls++; event(st.turn ?? st.lastTurn ?? st.run, "rovecode.tool_call_failed", [["rovecode.call_id", str(ev.callId)], ["rovecode.failure_reason", str(ev.reason)]]); }
+          break;
+        }
+        case "compaction":
+          event(st.turn ?? st.run, "rovecode.compaction", [
+            ["rovecode.compaction.strategy", str(ev.strategy)], ...(ev.trigger ? [["rovecode.compaction.trigger", str(ev.trigger)] as [string, OtlpValue]] : []),
+            ["rovecode.compaction.tokens_before", int(ev.tokensBefore)], ["rovecode.compaction.tokens_after", int(ev.tokensAfter)],
+          ]);
+          break;
+        default: break; // run_start/run_end ride pre_run/post_run; deltas, progress notes and steers are not spans
+      }
+    },
+    pre_tool(ctx, call: HookToolCall) { const st = stateOf(ctx); if (st) openTool(st, call.id, call.tool); },
+    post_tool(ctx, call: HookToolCall, result: ToolOutput) { const st = stateOf(ctx); if (st) settleTool(openTool(st, call.id, call.tool), result.ok, result.output); },
+    post_run(ctx, result: RunResult) {
+      const st = stateOf(ctx);
+      if (!st) return;
+      runs.delete(ctx.runId!);
+      finish(st, result.status);
+    },
+    async session_close() {
+      // belt and braces (#39 MED-1): a run whose generator was dropped without .return() never reached
+      // post_run — export what it recorded as "stopped" (open spans close UNSET) instead of leaking it
+      for (const [id, st] of runs) { runs.delete(id); finish(st, "stopped"); }
+      await flush(); raise();
+    },
+  };
+}
+
+// ---------- helpers ----------
+
+const defaultNow = (): number => performance.timeOrigin + performance.now();
+/** random hex id of `bytes` bytes; the all-zero id is invalid in OTel */
+function hex(bytes: number): string {
+  let h: string;
+  do h = randomBytes(bytes).toString("hex"); while (/^0+$/.test(h));
+  return h;
+}
+const TIMED_OUT: unique symbol = Symbol("rovecode.otel.timeout");
+/** resolves TIMED_OUT after ms on a REF'D timer and aborts the request's controller (hooks.ts idiom);
+ *  the race is independent of the fetch honoring the signal, so a stuck transport still settles */
+function withTimeout<T>(p: Promise<T>, ms: number, ac: AbortController): Promise<T | typeof TIMED_OUT> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { ac.abort(); resolve(TIMED_OUT); }, ms);
+    (timer as unknown as { ref?: () => void }).ref?.();
+    p.then((v) => { clearTimeout(timer); resolve(v); }, (e: unknown) => { clearTimeout(timer); reject(e); });
+  });
+}
+function errText(e: unknown): string {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null && typeof (e as { message?: unknown }).message === "string") return (e as { message: string }).message;
+  return String(e);
+}

package/src/telemetry/otlp.ts

@@ -0,0 +1,68 @@
+/** OTLP/HTTP JSON wire shapes + encoder for the port-#39 exporter (telemetry/otel.ts): the
+ *  ExportTraceServiceRequest subset rovecode emits, the mutable in-memory span record it fills while a
+ *  run is live, and the OTLP/JSON mapping rules — ids as hex, fixed64 times and int64 attributes as
+ *  decimal strings, enums as integers. Pure: no I/O, no clock, no state. Split out of otel.ts at the
+ *  400-line cap (fix-wave 4); otel.ts re-exports everything here, so its public surface is unchanged. */
+
+import pkg from "../../package.json";
+
+// ---------- wire types (OTLP/HTTP JSON, ExportTraceServiceRequest) ----------
+
+export type OtlpValue = { stringValue: string } | { intValue: string } | { doubleValue: number } | { boolValue: boolean };
+export interface OtlpKeyValue { key: string; value: OtlpValue }
+export interface OtlpSpan {
+  traceId: string; spanId: string; parentSpanId?: string; name: string; kind: number;
+  startTimeUnixNano: string; endTimeUnixNano: string;
+  attributes: OtlpKeyValue[];
+  events?: { name: string; timeUnixNano: string; attributes: OtlpKeyValue[] }[];
+  status: { code: number; message?: string };
+}
+export interface OtlpTraceRequest {
+  resourceSpans: {
+    resource: { attributes: OtlpKeyValue[] };
+    scopeSpans: { scope: { name: string; version?: string }; spans: OtlpSpan[] }[];
+  }[];
+}
+
+/** one recorded span; mutable until its run is exported (events arrive out of order — otel.ts header) */
+export interface OtelSpan {
+  traceId: string; spanId: string; parentSpanId?: string; name: string;
+  start: number; end?: number;
+  attrs: Map<string, OtlpValue>;
+  events: { name: string; time: number; attrs: Map<string, OtlpValue> }[];
+  status: { code: 0 | 1 | 2; message?: string };
+}
+
+export const str = (v: string): OtlpValue => ({ stringValue: v });
+export const int = (v: number): OtlpValue => ({ intValue: String(Math.trunc(v)) });
+export const dbl = (v: number): OtlpValue => ({ doubleValue: v });
+export const bool = (v: boolean): OtlpValue => ({ boolValue: v });
+
+// ---------- encoding ----------
+
+/** OTLP/JSON: ids hex (already), fixed64 times + int64 attrs as decimal strings, enums as integers */
+export function encodeTraceRequest(serviceName: string, spans: readonly OtelSpan[]): OtlpTraceRequest {
+  const kv = (m: Iterable<[string, OtlpValue]>): OtlpKeyValue[] => [...m].map(([key, value]) => ({ key, value }));
+  return {
+    resourceSpans: [{
+      resource: { attributes: kv([["service.name", str(serviceName)], ["service.version", str(pkg.version)]]) },
+      scopeSpans: [{
+        scope: { name: "rovecode", version: pkg.version },
+        spans: spans.map((s) => ({
+          traceId: s.traceId, spanId: s.spanId, ...(s.parentSpanId ? { parentSpanId: s.parentSpanId } : {}),
+          name: s.name, kind: 1, // SPAN_KIND_INTERNAL
+          startTimeUnixNano: unixNano(s.start), endTimeUnixNano: unixNano(s.end ?? s.start),
+          attributes: kv(s.attrs),
+          ...(s.events.length > 0 ? { events: s.events.map((e) => ({ name: e.name, timeUnixNano: unixNano(e.time), attributes: kv(e.attrs) })) } : {}),
+          status: s.status.message !== undefined ? { code: s.status.code, message: s.status.message } : { code: s.status.code },
+        })),
+      }],
+    }],
+  };
+}
+
+/** ms since epoch (fractions allowed) → exact unix-nano decimal string (no float rounding at 1e18) */
+export function unixNano(ms: number): string {
+  const whole = Math.floor(ms);
+  return (BigInt(whole) * 1_000_000n + BigInt(Math.round((ms - whole) * 1e6))).toString();
+}

package/src/tools/ask-user.ts

@@ -0,0 +1,156 @@
+/** PORT #33 — ask_user: one clarifying question per call, answered by the interactive surface.
+ *
+ *  The model asks a question (optional option labels + free text); the surface renders it and
+ *  the user's answer returns as the tool result. Surfaces without a human (run/serve/acp) never
+ *  bind an asker, so the tool fails CLOSED with an actionable error instead of hanging.
+ *
+ *  Sources (research/source_snapshots):
+ *   - opencode-2026 (MIT, ebece6e) packages/opencode/src/tool/question.ts:22-40 — the tool
+ *     contract: prompts with option labels, answers folded back into the tool output as the
+ *     selected label text (:30-36); packages/schema/src/v1/question.ts:15-28 — Option/Prompt
+ *     shape incl. `custom` (typed answer allowed, default true); question.txt usage notes
+ *     (recommended option first, no catch-all "Other" — the surface adds the free-text entry);
+ *     packages/opencode/src/question/index.ts:29-33 — a dismissed question is an ERROR the
+ *     model sees ("The user dismissed this question"), never a silent empty answer.
+ *   - gemini-cli (Apache-2.0, 0bd1d43) packages/cli/src/config/config.ts:794-803 — headless
+ *     behavior: with no human present ask_user is excluded and ASK_USER decisions translate to
+ *     DENY. rovecode keeps the tool registered on every surface (one registry for all of them) and
+ *     fails closed at execute time with a message that tells the model what to do instead.
+ *  Deviations: ONE question per call (sequential: true) instead of a batch of up to 4; options
+ *  are plain strings — the harness renders into 80 columns, not a web panel. No code copied.
+ */
+
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+
+/** What the surface must render: the question, optional option labels, and whether a typed
+ *  answer is accepted (default true — opencode `custom`, schema/v1/question.ts:26-28). */
+export interface QuestionPrompt {
+  question: string;
+  options?: string[];
+  allowFreeText?: boolean;
+}
+
+/** What the surface hands back: a picked option (index, label) or typed text. */
+export interface QuestionAnswer {
+  choice?: number;
+  label?: string;
+  text?: string;
+}
+
+/** The surface seam. Resolves null when the user declines; MUST honor `signal` (dismiss on
+ *  abort) — the tool races it regardless, so a deaf surface cannot pin the run. */
+export type AskFn = (q: QuestionPrompt, signal: AbortSignal) => Promise<QuestionAnswer | null>;
+
+export const MAX_OPTIONS = 8;
+export const MAX_OPTION_CHARS = 80;
+export const MAX_QUESTION_CHARS = 2000;
+
+export const ASK_USER_UNAVAILABLE =
+  "ask_user unavailable: no interactive user in this session (headless run/serve/acp) — proceed with your best judgment or stop";
+export const ASK_USER_ABORTED = "ask_user aborted";
+export const ASK_USER_DECLINED = "user declined to answer";
+
+/** Validate + normalize args. A string return is the error message (never throws). */
+export function parseQuestion(args: unknown): QuestionPrompt | string {
+  const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+  const question = typeof a.question === "string" ? a.question.trim() : "";
+  if (question === "") return "question must be a non-empty string";
+  if (question.length > MAX_QUESTION_CHARS) return `question too long (${question.length} chars, max ${MAX_QUESTION_CHARS})`;
+  let options: string[] | undefined;
+  if (a.options !== undefined && a.options !== null) {
+    if (!Array.isArray(a.options)) return "options must be an array of strings";
+    if (a.options.length > MAX_OPTIONS) return `too many options (${a.options.length}, max ${MAX_OPTIONS})`;
+    options = [];
+    for (const o of a.options) {
+      if (typeof o !== "string" || o.trim() === "") return "every option must be a non-empty string";
+      const label = o.trim();
+      if (label.length > MAX_OPTION_CHARS) return `option too long (${label.length} chars, max ${MAX_OPTION_CHARS}): ${label.slice(0, 40)}…`;
+      options.push(label);
+    }
+    if (options.length === 0) options = undefined;
+  }
+  if (a.allowFreeText !== undefined && typeof a.allowFreeText !== "boolean") return "allowFreeText must be a boolean";
+  const allowFreeText = a.allowFreeText !== false;
+  if (!options && !allowFreeText) return "nothing to answer with: provide options or allow free text";
+  return { question, ...(options ? { options } : {}), allowFreeText };
+}
+
+/** Fold the surface's answer into the model-facing result; garbage from a surface is an error. */
+function renderAnswer(a: QuestionAnswer, q: QuestionPrompt): ToolOutput {
+  const text = typeof a.text === "string" ? a.text.trim() : "";
+  if (text !== "") return { ok: true, output: `answer: ${text}`, data: { text } };
+  const options = q.options ?? [];
+  if (typeof a.choice === "number" && Number.isInteger(a.choice) && a.choice >= 0 && a.choice < options.length) {
+    const label = options[a.choice]!;
+    return { ok: true, output: `answer: ${label}`, data: { choice: a.choice, label } };
+  }
+  return { ok: false, output: "ask_user failed: the surface returned an unusable answer" };
+}
+
+/** Build the tool over a GETTER for the asker, so a surface can bind/unbind after registration
+ *  (runtime.setAskUser — the setBlockStore late-binding idiom). */
+export function askUserTool(getAsk: () => AskFn | undefined): Tool {
+  return {
+    schema: {
+      name: "ask_user",
+      description:
+        "Ask the user ONE clarifying question and wait for the answer. Use it when instructions are " +
+        "ambiguous, a decision has real consequences, or you must pick between approaches — do not guess. " +
+        `Give up to ${MAX_OPTIONS} short options (≤${MAX_OPTION_CHARS} chars each); the user may also type a ` +
+        "free-text answer unless allowFreeText is false. If you recommend an option, list it first and append " +
+        "\"(recommended)\"; never add an \"Other\" option — the free-text entry covers it. The result is " +
+        "`answer: <chosen option or typed text>`. A declined or aborted question, or a session with no " +
+        "interactive user (headless run/serve/acp), returns an error: then proceed with your best judgment or stop.",
+      args: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "the complete question — clear, specific, one decision" },
+          options: {
+            type: "array", items: { type: "string" }, maxItems: MAX_OPTIONS,
+            description: `up to ${MAX_OPTIONS} answer choices, ≤${MAX_OPTION_CHARS} chars each (recommended one first)`,
+          },
+          allowFreeText: { type: "boolean", description: "also accept a typed free-form answer (default true)" },
+        },
+        required: ["question"],
+      },
+    },
+    // kind "read" → action file.read. Asking the human must never itself need approval: the gated
+    // default rules (runtime.ts buildCfg) allow file.read, prompt file.write/shell.exec/spawn/
+    // tool.mcp_call, and deny-default everything else — a "custom" kind would map to
+    // `tool.ask_user`, which no rule allows (denied), and plan mode's blanket `tool.* deny`
+    // (modes.ts planModeRules) would lock the question tool out of exactly the mode where
+    // clarifying questions matter most, while file.read is re-allowed there. Non-mutating, so no
+    // checkpoint (MUTATING_KINDS = write/execute). With no `path`/`command` arg the policy
+    // resource is the tool name, so `file.read ask_user` can still be targeted precisely
+    // (same reasoning as memory/recall.ts:282-288).
+    kind: "read",
+    sequential: true, // one question at a time — never interleaved with sibling tool output
+    async execute(args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      const prompt = parseQuestion(args);
+      if (typeof prompt === "string") return { ok: false, output: `ask_user failed: ${prompt}` };
+      const ask = getAsk();
+      if (!ask) return { ok: false, output: ASK_USER_UNAVAILABLE }; // headless: fail closed, say why
+      if (ctx.signal.aborted) return { ok: false, output: ASK_USER_ABORTED };
+      let onAbort: (() => void) | undefined;
+      const aborted = new Promise<"aborted">((res) => {
+        onAbort = () => res("aborted");
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+      });
+      try {
+        // RACED, not merely awaited: a surface that ignores the signal must not pin the run.
+        // The executor form invokes ask() synchronously and turns a sync throw into a rejection.
+        const asked = new Promise<QuestionAnswer | null>((res) => res(ask(prompt, ctx.signal)));
+        const winner = await Promise.race([asked.then((answer) => ({ answer })), aborted]);
+        // an answer landing in the same tick as the abort is moot — the run is going away
+        if (winner === "aborted" || ctx.signal.aborted) return { ok: false, output: ASK_USER_ABORTED };
+        if (winner.answer === null) return { ok: false, output: ASK_USER_DECLINED };
+        return renderAnswer(winner.answer, prompt);
+      } catch (e) {
+        // never throw across the tool seam (ADR-005): surface failures become typed output
+        return { ok: false, output: `ask_user failed: ${e instanceof Error ? e.message : String(e)}` };
+      } finally {
+        if (onAbort) ctx.signal.removeEventListener("abort", onAbort);
+      }
+    },
+  };
+}