@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/incremental-file.ts

@@ -0,0 +1,110 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { open as fsOpen, stat as fsStat } from "node:fs/promises";
+
+/** File identity and length captured for an incremental tail pass. */
+export interface IncrementalFileInfo {
+  size: number;
+  ino?: number;
+}
+
+/** Durable watermark for a single append-only file. */
+export interface IncrementalFilePosition {
+  path: string;
+  ino?: number;
+  offset: number;
+}
+
+export interface IncrementalFileLineBuffer {
+  partial?: Buffer;
+  /** An over-limit record is ignored until its terminating newline arrives. */
+  discarding?: boolean;
+}
+
+/** Consumer-owned line-size policy: providers have different valid record sizes. */
+export interface IncrementalFileLinePolicy {
+  maxPartialBytes: number;
+}
+
+export function statIncrementalFile(path: string): Promise<IncrementalFileInfo> {
+  return fsStat(path).then((stats) => ({ size: stats.size, ino: stats.ino }));
+}
+
+export function statIncrementalFileSync(path: string): IncrementalFileInfo {
+  const stats = statSync(path);
+  return { size: stats.size, ino: stats.ino };
+}
+
+export async function readIncrementalFileRange(path: string, start: number, end: number): Promise<Uint8Array> {
+  const handle = await fsOpen(path, "r");
+  try {
+    const length = Math.max(end - start, 0);
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, start);
+    return bytesRead === length ? buffer : buffer.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+
+export function readIncrementalFileRangeSync(path: string, start: number, end: number): Uint8Array {
+  const length = Math.max(end - start, 0);
+  const handle = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const bytesRead = readSync(handle, buffer, 0, length, start);
+    return bytesRead === length ? buffer : buffer.subarray(0, bytesRead);
+  } finally {
+    closeSync(handle);
+  }
+}
+
+/** A different path/inode or a shrink invalidates a previously committed offset. */
+export function incrementalFileNeedsReset(position: IncrementalFilePosition | undefined, path: string, info: IncrementalFileInfo): boolean {
+  if (!position || position.path !== path || info.size < position.offset) return true;
+  return info.ino !== undefined && position.ino !== undefined && info.ino !== position.ino;
+}
+
+/**
+ * Split an append-only JSONL byte stream without corrupting a line split across reads.
+ * A partial record is capped; once it exceeds the cap, skip that one record through its
+ * next newline rather than retaining/copying it on every heartbeat.
+ */
+export function splitIncrementalFileLines(previous: IncrementalFileLineBuffer, chunk: Uint8Array, policy: IncrementalFileLinePolicy): { lines: Buffer[]; buffer: IncrementalFileLineBuffer } {
+  const data = Buffer.from(chunk);
+  const lines: Buffer[] = [];
+  let start = 0;
+  let partial = previous.partial;
+  let discarding = previous.discarding === true;
+
+  if (discarding) {
+    const newline = data.indexOf(0x0a);
+    if (newline < 0) return { lines, buffer: { discarding: true } };
+    start = newline + 1;
+    discarding = false;
+  }
+
+  for (let index = start; index < data.length; index++) {
+    if (data[index] !== 0x0a) continue;
+    const segment = data.subarray(start, index);
+    if (partial) {
+      if (partial.length + segment.length <= policy.maxPartialBytes) lines.push(Buffer.concat([partial, segment]));
+      partial = undefined;
+    } else if (segment.length <= policy.maxPartialBytes) {
+      lines.push(segment);
+    }
+    start = index + 1;
+  }
+
+  const tail = data.subarray(start);
+  if (partial) {
+    if (partial.length + tail.length <= policy.maxPartialBytes) partial = Buffer.concat([partial, tail]);
+    else {
+      partial = undefined;
+      discarding = true;
+    }
+  } else if (tail.length) {
+    if (tail.length <= policy.maxPartialBytes) partial = Buffer.from(tail);
+    else discarding = true;
+  }
+  return { lines, buffer: { ...(partial ? { partial } : {}), ...(discarding ? { discarding } : {}) } };
+}

package/src/adapters/opencode-api.ts

@@ -0,0 +1,71 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { OPENAI_API_MODEL, isOpenAiApiModel, type ApiBudgetTokenUsage } from "@humwick/sdk";
+import { resolveKeyCredential } from "@humwick/sdk/child-env";
+import { isRecord } from "@humwick/sdk";
+import { openCodeTokenUsageRecord, openCodeMessageFinished, openCodeMessageModel, openCodeMessageObservedAt } from "./opencode-token-usage-capture";
+import type { SpawnArgs, RunnerSpawnConfig } from "../adapter";
+import { ApiBudgetAccounting } from "../api-budget-accounting";
+import { ProviderSubmitFailure } from "../provider-submit-failure";
+
+export function openCodeApiKey(config: RunnerSpawnConfig, model: string): string | undefined {
+  if (!isOpenAiApiModel("opencode", model)) return undefined;
+  if (model !== OPENAI_API_MODEL) throw new ProviderSubmitFailure("OpenAI API model has no supported budget price", false);
+  const file = config.providerConfig.env.OPENAI_API_KEY_FILE ?? config.env.OPENAI_API_KEY_FILE ?? process.env.OPENAI_API_KEY_FILE;
+  try { return resolveKeyCredential("OPENAI_API_KEY", config.env, file); }
+  catch (error) { throw new ProviderSubmitFailure(`OpenAI API billing needs a vault-bound OPENAI_API_KEY or OPENAI_API_KEY_FILE: ${(error as Error).message}`, false); }
+}
+
+/** Native OpenCode owns turns; the shared accountant owns money and retries. */
+export class OpenCodeApiBudget {
+  readonly ledger: ApiBudgetAccounting;
+  private heartbeat?: ReturnType<typeof setInterval>;
+
+  constructor(config: RunnerSpawnConfig) {
+    this.ledger = new ApiBudgetAccounting("openai-api", (action, body) => this.ledger.transport(config, action, { ...body, ...(action === "reserve" && relayEnv(config.env, "AGENT_RELAY_SPAWN_REQUEST_ID") ? { spawnRequestId: relayEnv(config.env, "AGENT_RELAY_SPAWN_REQUEST_ID") } : {}) }));
+  }
+
+  async start(sessionId: string): Promise<void> {
+    await this.ledger.reserve(sessionId);
+    this.heartbeat = setInterval(() => this.report(), 5_000);
+    this.heartbeat.unref?.();
+  }
+
+  observe(record: ApiBudgetTokenUsage): void {
+    this.ledger.observe(record);
+    this.report();
+  }
+
+  private report(): void {
+    this.ledger.queue(async () => { await this.ledger.report({ renew: true }); }, () => {});
+  }
+
+  async prepare(): Promise<void> {
+    await this.ledger.pending;
+    // A failed report keeps its batch for the next boundary/heartbeat; it never kills a turn.
+    const decision = await this.ledger.report({ renew: true });
+    if (!decision.allowed) throw new ProviderSubmitFailure(`OpenAI API budget held: ${decision.reason}`, true);
+  }
+
+  async settle(): Promise<void> {
+    clearInterval(this.heartbeat);
+    await this.ledger.settle();
+  }
+}
+
+/** Every session on the isolated server spends this launch's key, including native children. */
+export function captureOpenCodeApiUsage(budget: OpenCodeApiBudget | undefined, info: unknown, sessionId: string | undefined, model: string | undefined, messageId: string): void {
+  if (!budget || !openCodeMessageFinished(info)) return;
+  const record = openCodeTokenUsageRecord({ provider: "opencode", sessionId: sessionId ?? "unknown",
+    model: openCodeMessageModel(info) ?? model ?? "unknown", messageId,
+    tokens: isRecord(info) ? info.tokens : undefined, createdAt: openCodeMessageObservedAt(info), finished: true });
+  if (record) budget.observe(record);
+}
+
+export async function spawnOpenCodeServer(args: SpawnArgs, budget?: OpenCodeApiBudget): Promise<Bun.Subprocess> {
+  try {
+    return Bun.spawn([args.command, ...args.args], { cwd: args.cwd, env: args.env, stdin: "ignore", stdout: "inherit", stderr: "inherit" });
+  } catch (error) {
+    await budget?.settle().catch(() => {});
+    throw error;
+  }
+}

package/src/adapters/opencode-context.ts

@@ -0,0 +1,277 @@
+import type { ContextState } from "@humwick/sdk";
+import { providerContextState } from "../transcript-context";
+
+// #2355 — OpenCode's `/session/:id/message` response (and its `message.updated` SSE echo) carries
+// a per-assistant-message `tokens` object once the message finalizes: `{ input, output, reasoning,
+// cache: { read, write} }`, confirmed live against a real captured v1.18.21 session's SQLite
+// `message` table (issue #2355 investigation) — and, when present, a `total` leaf that is already
+// the sum of all of those (`input + output + reasoning + cache.read + cache.write`). Unlike Codex's
+// `thread/tokenUsage/updated` (which also carries `modelContextWindow`), OpenCode's wire never
+// reports the model's context-window size anywhere — so the window has to come from the static,
+// operator-declared catalog value (`providers/opencode.ts`) instead of the wire, and this helper
+// takes that resolved value as a plain parameter rather than trying to read it itself.
+//
+// `tokensUsed` here is genuinely LIVE (the provider's own reported per-turn total — input tokens
+// carried forward from prior turns via cache-read plus this turn's own output, i.e. what will be
+// resent as context on the next turn), but `windowTokens` is a DECLARED constant the wire never
+// confirms turn-to-turn. `confidence: "estimated"` (not "reported") makes that partial provenance
+// visible downstream instead of presenting the whole reading as fully API-confirmed.
+//
+// #2355 review (MED-1) — `tokensUsed === 0` is treated as NO SIGNAL, same as `undefined`, not as a
+// genuine zero-usage reading. `send()` calls this on EVERY completion, including a positively-parsed
+// EMPTY completion (`openCodeCompletion`'s `empty: true` path — #2389's deterministic-close path,
+// which reports `tokens: 0`). A finalized assistant message that actually engaged the model always
+// has `input > 0` (the prompt itself is never zero tokens), so a `total` of exactly 0 only ever
+// means "no usable token reading for this turn" — never "the context is now empty". Returning a real
+// ContextState at utilization:0 here would unconditionally overwrite `process.meta.context` with a
+// fabricated "context emptied" reading on every empty turn, flapping the warn/self-compact advisory
+// band on the server (it clears when utilization drops, then re-fires on the next real turn).
+export function openCodeContextState(input: { tokensUsed: number | undefined; windowTokens: number | undefined; now?: number }): ContextState | undefined {
+  const { tokensUsed, windowTokens, now = Date.now() } = input;
+  if (typeof tokensUsed !== "number" || !Number.isFinite(tokensUsed) || tokensUsed <= 0) return undefined;
+  if (typeof windowTokens !== "number" || !Number.isFinite(windowTokens) || windowTokens <= 0) return undefined;
+  return providerContextState(tokensUsed, windowTokens, now, "estimated");
+}
+import { errMessage } from "@humwick/sdk";
+import type { ManagedProcess, RunnerSpawnConfig } from "../adapter";
+import { PromptAcceptedError } from "../adapter";
+import { resolveRelayContext } from "../relay-instructions";
+import { launchWebTools } from "../web-tools";
+
+/** The immutable input and deferred marker for one logical OpenCode turn. */
+export interface OpenCodeRelayContextInput {
+  readonly text: string;
+  readonly emitsRelayContext: boolean;
+  readonly emitsLaunchContext: boolean;
+}
+
+/**
+ * #2534 — proof-of-acceptance watcher for one context-carrying outbound prompt. Armed at
+ * dispatch and consumed by the SSE `message.part.updated` door (or the bounded persisted-message
+ * reconciliation) the moment OpenCode positively persists the prompt as a user message —
+ * BEFORE the synchronous turn-completion await resolves, which on a long turn may only do so
+ * (or abort) up to the whole-turn deadline later.
+ */
+export interface OpenCodeContextAcceptance {
+  readonly sessionId: string;
+  readonly text: string;
+  readonly emitsRelayContext: boolean;
+  readonly emitsLaunchContext: boolean;
+  /**
+   * #2534 review round 2 (MED-2) — epoch ms when THIS arm was dispatched. Every arm of send()'s
+   * retry/re-roll loop dispatches the SAME immutable text into the SAME session, so the
+   * reconciliation's persisted match needs a per-arm discriminator beyond text equality: a
+   * persisted user message only proves THIS arm if it was created at or after this arm's
+   * dispatch (an earlier arm's identical persisted message must never match).
+   */
+  readonly dispatchedAt: number;
+  /**
+   * #2534 review (MED-2) — accepted verdict for THIS dispatch arm, set only by this arm's own
+   * door or reconciliation. The durable first-turn markers are process-scoped and the prepared
+   * context input is immutable across send()'s retry/re-roll loop, so a later arm that fails
+   * PRE-acceptance must never inherit an earlier arm's acceptance: keying the verdict to the
+   * markers alone would wrap that failure in PromptAcceptedError and drop the assignment as
+   * already-delivered. The flag dies with the arm in sendOpenCodeRelayTurn's finally.
+   */
+  consumed?: boolean;
+}
+
+const ACCEPTANCE_META_KEY = "pendingContextAcceptance";
+
+function openCodeLaunchContext(process: ManagedProcess): string | undefined {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  const text = config?.systemPromptAppend?.trim();
+  if (!text || process.meta?.launchContextSent) return undefined;
+  return [
+    "[agent-relay launch context]",
+    "The following context was attached when this provider session was launched. Treat it as background context, not as a user request and not as your own prior actions.",
+    text,
+  ].join("\n");
+}
+
+/**
+ * Prepare exactly one OpenCode turn with Relay context before its retry loop begins.
+ *
+ * This deliberately does not mutate `relayContextSent`: a missing client/session, or a client
+ * that throws before accepting a request, has not emitted the block and must leave the next
+ * RunnerCore retry eligible to carry it.
+ */
+export function prepareOpenCodeRelayContext(process: ManagedProcess, text: string): OpenCodeRelayContextInput {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  const context = resolveRelayContext({ slug: "relay.context.opencode", config, webTools: config ? { names: launchWebTools(config), claude: false } : undefined });
+  const emitsRelayContext = context.available && !process.meta?.relayContextSent;
+  const launchContext = openCodeLaunchContext(process);
+  return {
+    text: [emitsRelayContext ? context.text : undefined, launchContext, text].filter(Boolean).join("\n\n"),
+    emitsRelayContext,
+    emitsLaunchContext: launchContext !== undefined,
+  };
+}
+
+/** Record the first context only after the client has accepted the outbound request. */
+export function markOpenCodeRelayContextSent(process: ManagedProcess, input: OpenCodeRelayContextInput): void {
+  if (!input.emitsRelayContext && !input.emitsLaunchContext) return;
+  process.meta = {
+    ...(process.meta ?? {}),
+    ...(input.emitsRelayContext ? { relayContextSent: true } : {}),
+    ...(input.emitsLaunchContext ? { launchContextSent: true } : {}),
+  };
+}
+
+/** Record the marker only after OpenCode resolves the request, preserving rejected transport retries. */
+export async function sendOpenCodeRelayMessage<T>(client: { sendMessage(sessionId: string, text: string, model: string): Promise<T> }, process: ManagedProcess, sessionId: string, model: string, input: OpenCodeRelayContextInput): Promise<T> {
+  const response = await client.sendMessage(sessionId, input.text, model);
+  markOpenCodeRelayContextSent(process, input);
+  return response;
+}
+
+/**
+ * #2534 — arm the acceptance watcher just before a context-carrying POST is dispatched. A
+ * prompt that emits no first-turn context has nothing to protect and never arms one, so
+ * ordinary mid-session deliveries stay watcher-free.
+ */
+export function armOpenCodeContextAcceptance(process: ManagedProcess, input: OpenCodeRelayContextInput, sessionId: string): void {
+  if (!input.emitsRelayContext && !input.emitsLaunchContext) return;
+  process.meta = {
+    ...(process.meta ?? {}),
+    [ACCEPTANCE_META_KEY]: { sessionId, text: input.text, emitsRelayContext: input.emitsRelayContext, emitsLaunchContext: input.emitsLaunchContext, dispatchedAt: Date.now() } satisfies OpenCodeContextAcceptance,
+  };
+}
+
+/** Drop the watcher — once the dispatch attempt has settled (a positive consumption marks the
+ *  arm consumed in place; the arm's verdict must survive until reconcile runs on a failed await). */
+export function clearOpenCodeContextAcceptance(process: ManagedProcess): void {
+  if (!process.meta || !(ACCEPTANCE_META_KEY in process.meta)) return;
+  const { [ACCEPTANCE_META_KEY]: _dropped, ...rest } = process.meta;
+  process.meta = rest;
+}
+
+/**
+ * #2534 — consume the watcher from an observed persisted user text part. Identity is matched to
+ * THIS launch incarnation on three axes, all of which must hold:
+ * 1. the echo's session id equals the session the prompt was dispatched to, AND
+ * 2. that session is still the process's ACTIVE session (a stale-session echo from a superseded
+ *    incarnation must never mark), AND
+ * 3. the persisted text equals the exact outbound text (a ~48KB launch-prefixed prompt is its own
+ *    fingerprint — an operator-typed prompt on the same session can never collide).
+ * On a match the pending first-turn markers are consumed immediately and THIS arm is marked
+ * consumed; the watcher itself stays armed until the dispatch attempt settles, so the failed
+ * completion await can still consult the per-arm verdict (reconcileOpenCodeContextAcceptance).
+ */
+export function consumeOpenCodeContextAcceptance(process: ManagedProcess | undefined, eventSessionId: string | undefined, observedText: string | undefined): boolean {
+  const meta = process?.meta;
+  if (!meta) return false;
+  const pending = meta[ACCEPTANCE_META_KEY] as OpenCodeContextAcceptance | undefined;
+  if (!pending || typeof pending.sessionId !== "string" || typeof pending.text !== "string") return false;
+  if (!eventSessionId || eventSessionId !== pending.sessionId) return false;
+  if (meta.sessionId !== pending.sessionId) return false;
+  if (!observedText || observedText !== pending.text) return false;
+  // Mark the arm consumed BEFORE the marker write: markOpenCodeRelayContextSent REPLACES
+  // process.meta with a fresh object (spread), so a write into the old reference would be lost.
+  meta[ACCEPTANCE_META_KEY] = { ...pending, consumed: true };
+  markOpenCodeRelayContextSent(process, { text: pending.text, emitsRelayContext: pending.emitsRelayContext, emitsLaunchContext: pending.emitsLaunchContext });
+  return true;
+}
+
+/**
+ * #2534 — does the `GET /session/:id/message` body positively contain a persisted USER message
+ * whose text part equals `text` exactly AND that was created at or after `dispatchedAt`? The
+ * outbound launch-carrying prompt (role/memory/gate briefing prepended to the assignment) is its
+ * own fingerprint: a same-session prompt typed by the operator can never collide with it, so
+ * exact equality is the identity match. But equality alone is not per-arm: every arm of send()'s
+ * retry loop dispatches the SAME text into the SAME session, so an earlier arm's persisted
+ * message would match a later arm's pre-acceptance failure (#2534 review round 2, MED-2) — the
+ * real envelope's `info.time.created` (epoch ms, verified live against v1.18.21) is the
+ * discriminator: only messages created at or after THIS arm's dispatch can prove THIS arm.
+ * The response shape is parsed defensively — an unparsable body, or a match candidate with no
+ * usable `created` timestamp, confirms nothing (returns false; fail-closed).
+ */
+function sessionPersistsUserText(body: unknown, text: string, dispatchedAt: number): boolean {
+  if (!Array.isArray(body)) return false;
+  return body.some((entry) => {
+    if (typeof entry !== "object" || entry === null) return false;
+    const record = entry as { info?: unknown; role?: unknown; parts?: unknown; time?: unknown };
+    const info = typeof record.info === "object" && record.info !== null ? (record.info as { role?: unknown; parts?: unknown; time?: unknown }) : undefined;
+    const role = info ? info.role : record.role;
+    if (typeof role !== "string" || role !== "user") return false;
+    const parts = Array.isArray(record.parts) ? record.parts : info && Array.isArray(info.parts) ? info.parts : undefined;
+    if (!parts) return false;
+    const time = info ? info.time : record.time;
+    const created = typeof time === "object" && time !== null ? (time as { created?: unknown }).created : undefined;
+    if (typeof created !== "number" || !Number.isFinite(created) || created < dispatchedAt) return false;
+    return parts.some((part) => {
+      if (typeof part !== "object" || part === null) return false;
+      const partRecord = part as { type?: unknown; text?: unknown };
+      return partRecord.type === "text" && partRecord.text === text;
+    });
+  });
+}
+
+/**
+ * #2534 — best-effort acceptance proof for a failed completion await. The SSE door has usually
+ * already marked by now (proof 1); if not, read the session's persisted messages once, on the
+ * client's own short deadline, and consume the markers on an exact persisted-text match. Any
+ * reconciliation failure is swallowed: an unreachable server cannot confirm acceptance, so the
+ * markers stay false and the next attempt retries the launch text (fail-closed).
+ *
+ * #2534 review (MED-2) — the accepted short-circuit reads THIS dispatch arm's consumed flag,
+ * never the durable first-turn markers: the markers are process-scoped and survive across the
+ * send() retry/re-roll loop's arms, so keying to them would make any later arm that fails
+ * PRE-acceptance inherit an earlier arm's acceptance and report the assignment delivered.
+ *
+ * #2534 review round 2 (MED-2) — the persisted match is likewise arm-scoped: the reconciliation
+ * runs with THIS arm's dispatch timestamp, so an earlier arm's identical persisted user message
+ * (same immutable text, same session) can never prove a later arm's failed dispatch. Without a
+ * pending arm there is nothing to prove — fail closed.
+ */
+async function reconcileOpenCodeContextAcceptance(client: { sessionMessages?(sessionId: string): Promise<unknown> }, process: ManagedProcess, sessionId: string, input: OpenCodeRelayContextInput, narrate: ((body: string) => void) | undefined): Promise<boolean> {
+  if (!input.emitsRelayContext && !input.emitsLaunchContext) return false;
+  const pending = process.meta?.[ACCEPTANCE_META_KEY] as OpenCodeContextAcceptance | undefined;
+  if (pending?.consumed) return true;
+  if (!pending || typeof pending.dispatchedAt !== "number") return false;
+  if (typeof client.sessionMessages !== "function") return false;
+  try {
+    if (sessionPersistsUserText(await client.sessionMessages(sessionId), input.text, pending.dispatchedAt)) {
+      markOpenCodeRelayContextSent(process, input);
+      narrate?.(`OpenCode persisted the prompt (${input.text.length} chars) before the completion await failed; first-turn context marked consumed, not requeueing.`);
+      return true;
+    }
+  } catch {
+    // best-effort — see doc
+  }
+  return false;
+}
+
+/**
+ * #2534 — dispatch one attempt of the prepared turn, keeping first-turn marker consumption
+ * keyed to PROMPT ACCEPTANCE rather than to the completion await's return. OpenCode's
+ * `/message` POST is synchronous: it is ACCEPTED and its prompt persisted within moments of
+ * dispatch, but the await only resolves when the whole assistant turn ends — so on a long turn
+ * (up to the whole-turn deadline) the old await-then-mark order left `launchContextSent` false
+ * for the entire turn and re-prepended the full launch briefing to every message delivered
+ * after a timeout. Three acceptance proofs, in order of strength:
+ * 1. the SSE `message.part.updated` door (consumeOpenCodeContextAcceptance, wired into the
+ *    adapter's handleEvent) fires the moment the provider persists the prompt as a user text
+ *    part — marking mid-turn, long before the await settles;
+ * 2. a normal await RESOLUTION (a completed synchronous turn implies acceptance) — the
+ *    sendOpenCodeRelayMessage marking, unchanged;
+ * 3. when the await THROWS, a bounded persisted-message reconciliation: a user message whose
+ *    persisted text equals this exact outbound prompt proves acceptance, and the original
+ *    failure is re-thrown wrapped in PromptAcceptedError so RunnerCore does not requeue the
+ *    already-running assignment (attemptInitialPromptDelivery). If no proof materializes the
+ *    failure is re-thrown untouched and the markers stay false — a pre-acceptance rejection
+ *    (connect/readiness/transport failure) still retries the launch text, exactly as before.
+ */
+export async function sendOpenCodeRelayTurn<T>(client: { sendMessage(sessionId: string, text: string, model: string): Promise<T>; sessionMessages?(sessionId: string): Promise<unknown> }, process: ManagedProcess, sessionId: string, model: string, input: OpenCodeRelayContextInput, narrate?: (body: string) => void): Promise<T> {
+  armOpenCodeContextAcceptance(process, input, sessionId);
+  try {
+    return await sendOpenCodeRelayMessage(client, process, sessionId, model, input);
+  } catch (error) {
+    if (await reconcileOpenCodeContextAcceptance(client, process, sessionId, input, narrate)) {
+      throw new PromptAcceptedError(`OpenCode accepted the prompt (${input.text.length} chars) before the completion await failed: ${errMessage(error)}`, { cause: error });
+    }
+    throw error;
+  } finally {
+    clearOpenCodeContextAcceptance(process);
+  }
+}

package/src/adapters/opencode-model-registry.ts

@@ -0,0 +1,126 @@
+import { relayEnv, writeChildEnv } from "@humwick/sdk/env";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { openCodeModelRegistry, type OpenCodeModelId, type OpenCodeModelRegistry } from "@humwick/providers";
+import { errMessage, isRecord, stringValue } from "@humwick/sdk/types";
+import type { ProviderConfig, RunnerSpawnConfig } from "../adapter";
+import { logger } from "../logger";
+import { openCodeBackend, openCodeCustomBackendIDs, openCodeHostAuthKey, openCodeLaunchModel, openCodeModelRecord } from "./opencode-provider";
+import { openCodeMessageModel } from "./opencode-token-usage-capture";
+
+/**
+ * #2659 — the host's opencode model registry, used to normalize a launch model before spawn.
+ *
+ * Primary: `opencode models --pure` run with the launch env but isolated XDG config/data (the
+ * spawned server gets fresh isolated homes too), so it lists exactly the providers the server
+ * will have connected. Fallback: opencode's cached models.dev registry. Neither → undefined and
+ * the caller uses the static backend split.
+ */
+
+const PROBE_TIMEOUT_MS = 30_000;
+const cache = new Map<string, Promise<OpenCodeModelRegistry | undefined>>();
+
+export interface OpenCodeRegistryProbeDeps {
+  run?: (command: string[], env: Record<string, string>, timeoutMs: number) => Promise<{ exitCode: number; stdout: string }>;
+  readModelsDev?: (path: string) => string | undefined;
+}
+
+async function runProbe(command: string[], env: Record<string, string>, timeoutMs: number): Promise<{ exitCode: number; stdout: string }> {
+  const proc = Bun.spawn(command, { env, stdin: "ignore", stdout: "pipe", stderr: "ignore", timeout: timeoutMs, killSignal: "SIGKILL" });
+  const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return { exitCode, stdout };
+}
+
+function readFileOrUndefined(path: string): string | undefined {
+  try { return readFileSync(path, "utf8"); } catch { return undefined; }
+}
+
+/** Parse opencode's models.dev cache (`{ [providerID]: { models: { [modelID]: … } } }`). */
+export function parseModelsDevRegistry(text: string, extraProviders: Iterable<string>): OpenCodeModelRegistry | undefined {
+  let parsed: unknown;
+  try { parsed = JSON.parse(text); } catch { return undefined; }
+  if (!isRecord(parsed)) return undefined;
+  const ids: string[] = [];
+  for (const [providerID, entry] of Object.entries(parsed)) {
+    if (!isRecord(entry) || !isRecord(entry.models)) continue;
+    for (const modelID of Object.keys(entry.models)) ids.push(`${providerID}/${modelID}`);
+  }
+  return ids.length ? openCodeModelRegistry("models.dev", ids, extraProviders) : undefined;
+}
+
+export async function probeOpenCodeModelRegistry(
+  command: string,
+  env: Record<string, string>,
+  extraProviders: string[],
+  deps: OpenCodeRegistryProbeDeps = {},
+): Promise<OpenCodeModelRegistry | undefined> {
+  const scratch = mkdtempSync(join(tmpdir(), "agent-relay-opencode-models-"));
+  try {
+    const { exitCode, stdout } = await (deps.run ?? runProbe)(
+      [command, "models", "--pure"],
+      { ...env, XDG_CONFIG_HOME: join(scratch, "config"), XDG_DATA_HOME: join(scratch, "data"), XDG_STATE_HOME: join(scratch, "state") },
+      PROBE_TIMEOUT_MS,
+    );
+    const live = exitCode === 0 ? openCodeModelRegistry("live", stdout.split("\n"), extraProviders) : undefined;
+    if (live && live.models.size > 0) return live;
+    logger.warn("opencode", `model registry probe returned no models (exit ${exitCode}); falling back to the models.dev cache`);
+  } catch (error) {
+    logger.warn("opencode", `model registry probe failed: ${errMessage(error)}; falling back to the models.dev cache`);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  const cacheHome = env.XDG_CACHE_HOME || join(env.HOME || homedir(), ".cache");
+  const text = (deps.readModelsDev ?? readFileOrUndefined)(join(cacheHome, "opencode", "models.json"));
+  return text ? parseModelsDevRegistry(text, extraProviders) : undefined;
+}
+
+/** One probe per (command, credential set) per runner process; failures are not cached. */
+export function cachedOpenCodeModelRegistry(command: string, env: Record<string, string>, extraProviders: string[]): Promise<OpenCodeModelRegistry | undefined> {
+  const key = [command, ...Object.keys(env).filter((name) => name.endsWith("_API_KEY") && relayEnv(env, name)).sort()].join("\0");
+  const existing = cache.get(key);
+  if (existing) return existing;
+  const pending = probeOpenCodeModelRegistry(command, env, extraProviders).then((registry) => {
+    if (!registry) cache.delete(key);
+    return registry;
+  });
+  cache.set(key, pending);
+  return pending;
+}
+
+/**
+ * #2659 — normalize the launch model against the host's opencode registry BEFORE the server
+ * starts: a registry-listed id passes through unchanged, and an unknown/ambiguous id fails the
+ * spawn here with candidates instead of dying later as a provider 400.
+ */
+export async function resolveOpenCodeLaunchModel(
+  config: RunnerSpawnConfig,
+  providerConfig: ProviderConfig,
+  provider: string,
+  registryFor: typeof cachedOpenCodeModelRegistry = cachedOpenCodeModelRegistry,
+): Promise<OpenCodeModelId> {
+  const env: Record<string, string> = writeChildEnv({}, { ...config.env, ...providerConfig.env, PATH: config.env.PATH ?? providerConfig.env.PATH ?? process.env.PATH ?? "" });
+  // #2866 — the registry probe runs under fresh XDG roots too, so a hostAuth backend only lists
+  // its models when the host login key rides in as the backend's env credential.
+  const { backend } = openCodeBackend(provider);
+  if (backend.hostAuth && !relayEnv(env, backend.apiKeyEnvVar)) {
+    const hostKey = openCodeHostAuthKey(backend.opencodeProviderID, env);
+    if (hostKey) writeChildEnv(env, { [backend.apiKeyEnvVar]: hostKey });
+  }
+  const registry = await registryFor(providerConfig.command || "opencode", env, openCodeCustomBackendIDs());
+  const launch = openCodeLaunchModel(config.model, provider, openCodeModelRecord(config.modelRecord, provider), registry);
+  logger.info("opencode", `launch model ${JSON.stringify(config.modelRecord?.qualifiedModel ?? config.model ?? "(default)")} → ${launch.qualified} (${registry ? `${registry.source} registry, ${registry.models.size} models` : "static backend split"})`);
+  return launch;
+}
+
+/**
+ * #2659 — a model the human picked in the attached TUI rides on that prompt's user row
+ * (`info.model = {providerID, modelID}`). Adopt it as the session model so the next Relay chat
+ * turn keeps it instead of re-sending the launch model.
+ */
+export function adoptOpenCodeTerminalModel(meta: Record<string, unknown> | undefined, info: unknown): void {
+  const picked = isRecord(info) && isRecord(info.model) ? openCodeMessageModel(info.model) : undefined;
+  if (!meta || !picked || picked === meta.model) return;
+  logger.info("opencode", `terminal model switch: ${stringValue(meta.model) ?? "(unset)"} → ${picked}; Relay turns now use it`);
+  meta.model = picked;
+}