@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/opencode-provider.ts

@@ -0,0 +1,169 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { OPENCODE_STATIC_BACKENDS, getAllManifests, getManifest, resolveOpenCodeModelId, splitQualifiedOpenCodeModel, type OpenCodeModelId, type OpenCodeModelRegistry, type ProviderManifest } from "@humwick/providers";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ResolvedModelRecord } from "@humwick/sdk/provider-catalog";
+export type { OpenCodeModelId } from "@humwick/providers";
+
+export interface OpenCodeBackend {
+  manifest: ProviderManifest;
+  backend: NonNullable<ProviderManifest["opencode"]>;
+}
+
+/** Resolve a manifest-backed OpenCode provider once, with a useful error at the adapter boundary. */
+export function openCodeBackend(provider: string): OpenCodeBackend {
+  const manifest = getManifest(provider);
+  if (!manifest?.opencode) throw new Error(`Provider ${provider} is not configured for the OpenCode adapter.`);
+  return { manifest, backend: manifest.opencode };
+}
+
+/**
+ * #2599 — resolve the payload record for THIS provider, or reject an unknown provider LOUD.
+ * A record whose providerModel/alias resolves against a DIFFERENT registered provider is a
+ * routing error, not a fallback: silently running it under the wrong backend namespace would
+ * launch the wrong model. The manifest fallback only applies when NO record is present at all.
+ */
+export function openCodeModelRecord(record: ResolvedModelRecord | undefined, provider: string): ResolvedModelRecord | undefined {
+  if (!record) return undefined;
+  openCodeBackend(provider); // hard, clear error for an unknown provider — same boundary as below.
+  return record;
+}
+
+/** The credential env var for a recognized backend id, or undefined for an unknown id. */
+export function openCodeBackendApiKeyEnvVar(backendID: string): string | undefined {
+  return OPENCODE_STATIC_BACKENDS[backendID]?.envVar;
+}
+
+/** Catalog alias → provider model (older runner protocols carry the alias without a record). */
+function openCodeAliasResolved(model: string | undefined, manifest: ProviderManifest, provider: string): string {
+  const alias = model?.trim() || manifest.catalog.defaultModel;
+  const raw = manifest.catalog.models.find((entry) => entry.alias === alias)?.providerModel || alias;
+  if (!raw) throw new Error(`OpenCode provider ${provider} has no default model.`);
+  return raw;
+}
+
+/**
+ * #2659 — the launch model: THE one normalization of a spawn's model through the shared seam
+ * (`resolveOpenCodeModelId`). A server-threaded record's qualified name wins over the alias.
+ * With a host registry (spawn), unknown/ambiguous ids throw with candidates; without one
+ * (static fallback) a known-backend first segment is structural, anything else is a
+ * default-backend model id.
+ */
+export function openCodeLaunchModel(model: string | undefined, provider = "opencode", record?: ResolvedModelRecord, registry?: OpenCodeModelRegistry): OpenCodeModelId {
+  const { manifest, backend } = openCodeBackend(provider);
+  const input = record?.qualifiedModel || openCodeAliasResolved(model, manifest, provider);
+  return resolveOpenCodeModelId(input, backend.opencodeProviderID, registry);
+}
+
+/** Qualified runtime name (`providerID/modelID`) for a model/record, static resolution. */
+export function openCodeQualifiedModel(model: string | undefined, provider = "opencode", record?: ResolvedModelRecord): string {
+  return openCodeLaunchModel(model, provider, record).qualified;
+}
+
+/** v1.18.21's session API separates provider id from model id; only the first slash is structural. */
+export function openCodeModelDescriptor(model: string | undefined, provider = "opencode", record?: ResolvedModelRecord): { providerID: string; modelID: string } {
+  const { backendID, modelID } = openCodeLaunchModel(model, provider, record);
+  return { providerID: backendID, modelID };
+}
+
+/**
+ * #2659 — the per-turn descriptor for an ALREADY-normalized qualified name (process meta.model).
+ * Never re-resolves: re-running the static split here re-prefixed live-only backends with the
+ * default backend on every chat turn.
+ */
+export function openCodeTurnDescriptor(qualified: string, provider = "opencode"): { providerID: string; modelID: string } {
+  const { backend } = openCodeBackend(provider);
+  const { backendID, modelID } = splitQualifiedOpenCodeModel(qualified, backend.opencodeProviderID);
+  return { providerID: backendID, modelID };
+}
+
+/**
+ * #2600 — the config-block + credential-env half of the per-model backend decision: the
+ * openCodeProviderID to key `provider.<id>` under, the apiKey env var the config references and
+ * the launch env must carry (undefined for a live-registry backend Relay has no credential
+ * mapping for — opencode then authenticates it from the inherited env itself), and any
+ * hand-configured npm/baseURL/extraOptions carried over from the Relay provider's own backend
+ * (the `zai` custom-endpoint shape).
+ */
+export function openCodeResolvedBackend(backendID: string, provider = "opencode"): {
+  opencodeProviderID: string;
+  apiKeyEnvVar?: string;
+  hostAuth?: boolean;
+  npm?: string;
+  baseURL?: string;
+  extraOptions?: Record<string, unknown>;
+} {
+  const { backend } = openCodeBackend(provider);
+  // Default backend: reuse the manifest's own hand-configuration byte-for-byte.
+  if (backendID === backend.opencodeProviderID) return { ...backend };
+  // A custom Relay provider aliased onto this backend (e.g. `zai/...` on `opencode` reuses the
+  // `zai` manifest's npm/baseURL/apiKeyEnvVar) so the config block matches a native launch.
+  const aliased = getAllManifests().find((entry) => entry.opencode?.opencodeProviderID === backendID)?.opencode;
+  if (aliased) return { ...aliased };
+  // Built-in backend: opencode ships the def; declare only the credential reference.
+  const apiKeyEnvVar = openCodeBackendApiKeyEnvVar(backendID);
+  return { opencodeProviderID: backendID, ...(apiKeyEnvVar ? { apiKeyEnvVar } : {}) };
+}
+
+/** Backend ids Relay itself configures (custom manifests) — always valid registry providers. */
+export function openCodeCustomBackendIDs(): string[] {
+  return getAllManifests().flatMap((entry) => entry.opencode && OPENCODE_STATIC_BACKENDS[entry.opencode.opencodeProviderID]?.custom ? [entry.opencode.opencodeProviderID] : []);
+}
+
+/** Read the current backend's declared context window from the manifest catalog. */
+export function openCodeContextWindowTokens(model: string | undefined, provider = "opencode", record?: ResolvedModelRecord): number | undefined {
+  // #2599 — precedence payload > manifest > undefined: the record's window wins; a malformed
+  // record window never reaches here (the shared parser drops it), so no second gate is needed.
+  if (typeof record?.contextWindowTokens === "number" && Number.isFinite(record.contextWindowTokens) && record.contextWindowTokens > 0) {
+    openCodeBackend(provider); // keep the unknown-provider hard error on the record path too.
+    return record.contextWindowTokens;
+  }
+  const { manifest } = openCodeBackend(provider);
+  const { modelID } = openCodeLaunchModel(model, provider);
+  const value = manifest.catalog.models.find((entry) => entry.alias === modelID || entry.providerModel === modelID)?.limits?.contextWindowTokens?.value;
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+/**
+ * #2599 — the record's explicit threshold, when present (precedence payload > manifest-derived).
+ * Returns undefined when the record carries none — the caller then derives from the window.
+ */
+export function openCodeContextThreshold(record: ResolvedModelRecord | undefined, provider = "opencode"): ResolvedModelRecord["contextThreshold"] {
+  if (!record?.contextThreshold) return undefined;
+  openCodeBackend(provider); // keep the unknown-provider hard error on the record path too.
+  return record.contextThreshold;
+}
+
+/**
+ * #2600/#2659 — the selected backend's credential from the runner or provider-config env
+ * (`||`: an empty runner var must not mask a provider-config key). A live-registry backend
+ * without a Relay credential mapping has none — opencode authenticates it from the inherited env.
+ */
+export function openCodeBackendCredential(apiKeyEnvVar: string | undefined, runnerEnv: Record<string, string>, providerEnv: Record<string, string>, hostAuthBackendID?: string): string | undefined {
+  if (!apiKeyEnvVar) return undefined;
+  const apiKey = relayEnv(runnerEnv, apiKeyEnvVar) || relayEnv(providerEnv, apiKeyEnvVar) || (hostAuthBackendID ? openCodeHostAuthKey(hostAuthBackendID, runnerEnv) : undefined);
+  if (!apiKey) throw new Error(`OpenCode requires ${apiKeyEnvVar} in the runner process or provider config environment${hostAuthBackendID ? ` (or an \`opencode auth login\` entry for ${hostAuthBackendID} on this host)` : ""}.`);
+  return apiKey;
+}
+
+/**
+ * #2866 — the host's own `opencode auth login` key (`<data home>/opencode/auth.json`), which the
+ * isolated XDG launch hides from the server. Only for manifests with `opencode.hostAuth`.
+ */
+export function openCodeHostAuthKey(backendID: string, env: Record<string, string>): string | undefined {
+  const dataHome = env.XDG_DATA_HOME || process.env.XDG_DATA_HOME || join(env.HOME || homedir(), ".local", "share");
+  try {
+    const entry = (JSON.parse(readFileSync(join(dataHome, "opencode", "auth.json"), "utf8")) as Record<string, unknown>)[backendID];
+    const key = typeof entry === "object" && entry !== null ? (entry as { key?: unknown }).key : undefined;
+    return typeof key === "string" && key.trim() ? key.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** #2659 — is the session still on its launch model (no terminal model switch adopted)? */
+export function openCodeOnLaunchModel(meta: Record<string, unknown> | undefined, model: string | undefined): boolean {
+  const launchModel = typeof meta?.launchModel === "string" ? meta.launchModel : undefined;
+  return !launchModel || !model || model === launchModel;
+}

package/src/adapters/opencode-server-retry.ts

@@ -0,0 +1,50 @@
+// #2775 — OpenCode's OWN in-session retry. On a retryable provider error OpenCode does not end the
+// turn: it reports `session.status` `{ type: "retry", attempt, message, next, action? }` and keeps
+// the synchronous /message POST open until it succeeds. A free-tier wall schedules `next` for the
+// daily reset (hours out), so the agent sat busy and silent. These pure helpers decide when that
+// retry is a wall to hold on, and what the operator sees meanwhile.
+
+import { isRecord, stringValue, type ProviderState } from "@humwick/sdk";
+import { buildRateLimitProviderState, isProviderUsageLimit } from "../rate-limit";
+
+export interface OpenCodeServerRetry {
+  attempt: number;
+  message: string;
+  /** `action.reason` when OpenCode classifies the refusal (e.g. `free_tier_limit`). */
+  reason?: string;
+  /** Unix ms of OpenCode's next attempt. */
+  next?: number;
+}
+
+/** A retry scheduled at least this far out is a wall, not a transient backoff. */
+export const OPENCODE_SERVER_RETRY_WALL_DELAY_MS = 5 * 60_000;
+/** OpenCode retries a throttle forever; past this many attempts we stop waiting and hold. */
+export const OPENCODE_SERVER_RETRY_MAX_ATTEMPTS = 5;
+
+export function parseOpenCodeServerRetry(status: unknown): OpenCodeServerRetry | undefined {
+  if (!isRecord(status) || status.type !== "retry") return undefined;
+  const action = isRecord(status.action) ? status.action : undefined;
+  const reason = stringValue(action?.reason);
+  return {
+    attempt: typeof status.attempt === "number" ? status.attempt : 1,
+    message: stringValue(status.message) ?? stringValue(action?.title) ?? "OpenCode is retrying the provider request",
+    ...(reason ? { reason } : {}),
+    ...(typeof status.next === "number" && Number.isFinite(status.next) ? { next: status.next } : {}),
+  };
+}
+
+export function isOpenCodeServerRetryWall(retry: OpenCodeServerRetry, nowMs: number = Date.now()): boolean {
+  return isProviderUsageLimit({ message: retry.message, ...(retry.reason ? { errorType: retry.reason } : {}) })
+    || retry.attempt > OPENCODE_SERVER_RETRY_MAX_ATTEMPTS
+    || (retry.next !== undefined && retry.next - nowMs >= OPENCODE_SERVER_RETRY_WALL_DELAY_MS);
+}
+
+/** The visible "still retrying" state for a transient OpenCode retry (see openCodeUpstreamRetryState for why the reason is not `rate_limit`). */
+export function openCodeServerRetryState(retry: OpenCodeServerRetry): ProviderState {
+  return {
+    ...buildRateLimitProviderState({ kind: "transient_overload", errorType: retry.reason ?? "provider_error", message: retry.message, source: "opencode" }),
+    reason: "provider-error",
+    label: `OpenCode provider error, retrying (attempt ${retry.attempt}): ${retry.message}`,
+    resumeAttempt: retry.attempt,
+  };
+}

package/src/adapters/opencode-soft-steer.ts

@@ -0,0 +1,302 @@
+// #2539 Phase B — OpenCode/ZAI non-destructive soft-steer lane.
+//
+// The soft op is `POST /session/:id/message` with a CALLER messageID + `noReply:true`: it
+// persists a user row WITHOUT joining/cancelling the active run, and the run's loop reloads
+// full messages at its next step, consuming the row there. LIVE-PROVEN on the pinned 1.18.21
+// binary (zai backend): ~9-21ms persist, zero aborts across mid-tool/multi/at-stop scenarios,
+// consumption visible as assistant steps with `info.parentID == the soft batch's user id`, and
+// the at-turn-stop race stranding the row until the NEXT turn consumes it — which is exactly
+// what the bounded idle-wake fallback covers.
+//
+// This module owns the pure/serial parts of that lane: the kill switch, batch composition, the
+// messageID mint, and the durable-until-consumed ledger (persistence != delivery). The adapter
+// (opencode.ts) owns the seams: the client POST, the SSE consumption door, the turn-close wake
+// hook and the session-swap call sites. Everything here is deliberately free of provider I/O so
+// the whole state machine is unit-testable without a server.
+
+import { randomBytes } from "node:crypto";
+import { errMessage, type Message } from "@humwick/sdk";
+import { providerMessageText } from "../adapter";
+import type { ProviderInputObserver } from "../adapter";
+import { logger } from "../logger";
+
+/**
+ * The one-row-per-batch marker the design mandates: tells the model the payload is a steer, not
+ * a new assignment, and that completed work must not be discarded to act on it.
+ */
+export const OPENCODE_SOFT_STEER_MARKER = "Agent Relay soft steer: incorporate at next safe step; do not discard completed work.";
+
+/** Short deadlines only — never the 60m whole-turn budget (#2539 design F). */
+export const OPENCODE_SOFT_STEER_POST_TIMEOUT_MS = 5_000;
+export const OPENCODE_SOFT_STEER_RECONCILE_TIMEOUT_MS = 5_000;
+
+/** Backpressure caps (design F): overflow defers back to the normal queue instead of unbounded ledger growth. */
+export const OPENCODE_SOFT_STEER_MAX_BATCHES = 32;
+export const OPENCODE_SOFT_STEER_MAX_BATCH_BYTES = 48 * 1024;
+
+/**
+ * The bounded idle-wake fallback: exactly ONE content-free wake turn when the provider goes idle
+ * with unconsumed batches. It carries NO new content (the steer rows are already persisted in the
+ * session context — proven live) and never resends the steer payload. Going through the normal
+ * `send()` turn gives the wake a real busy/idle pair and the full retry semantics instead of a
+ * second, parallel turn machinery.
+ */
+export const OPENCODE_SOFT_STEER_WAKE_TEXT = "Agent Relay: soft-steer guidance above is pending. Incorporate it now at this safe step; do not discard completed work. If nothing needs incorporating, reply with a single line: ACK.";
+
+/**
+ * Caller-side OpenCode messageID for a soft batch — `msg_` prefix (the shape the server accepts
+ * and echoes back verbatim, live-verified) plus a `relay` brand so an operator can recognize
+ * relay-injected rows in the session transcript at a glance.
+ */
+export function newSoftSteerMessageID(): string {
+  return `msg_relay${randomBytes(8).toString("hex")}`;
+}
+
+export interface ComposedSoftSteerBatch {
+  text: string;
+  included: Message[];
+  deferred: Message[];
+}
+
+/**
+ * Compose ALL selected messages into ONE OpenCode user row, sorted by Relay id (arrival order),
+ * under the byte cap. Messages that would overflow the cap are returned as `deferred` so the
+ * caller backpressures them into the normal queue instead of silently dropping them. At least
+ * one message is always included: an oversized single message rides the soft lane truncated by
+ * the provider's own rendering limits rather than being dropped.
+ */
+export function composeSoftSteerText(messages: Message[]): ComposedSoftSteerBatch {
+  const sorted = [...messages].sort((a, b) => a.id - b.id);
+  const sections: string[] = [];
+  const included: Message[] = [];
+  const deferred: Message[] = [];
+  // Per-message candidates are only the BYTE PROJECTION for the cap decision (they over-count
+  // by the guidance each per-message call appends, so the cap stays a safe upper bound); the
+  // final row is rendered ONCE below so the notification guidance appears once
+  // per batch, not once per message.
+  for (const message of sorted) {
+    const candidate = providerMessageText([message]);
+    const projected = sections.length === 0 ? candidate : `${sections.join("\n\n")}\n\n${candidate}`;
+    if (sections.length > 0 && Buffer.byteLength(projected, "utf8") > OPENCODE_SOFT_STEER_MAX_BATCH_BYTES) {
+      deferred.push(message);
+      continue;
+    }
+    sections.push(candidate);
+    included.push(message);
+  }
+  const text = sections.length > 0
+    ? `${OPENCODE_SOFT_STEER_MARKER}\n\n${providerMessageText(included)}`
+    : "";
+  return { text, included, deferred };
+}
+
+export interface SoftSteerEntry {
+  inputObserver?: ProviderInputObserver;
+  messageID: string;
+  relayIds: number[];
+  sessionId: string;
+  acceptedAt: number;
+}
+
+/**
+ * #2539 Phase A reconciliation — the ledger's settlement exits are the RUNNER's seams, handed in
+ * through ProviderDeliverContext (settleMidTurnConsumed / reofferMidTurnIds). The ledger never
+ * settles on its own: an absent callback is a fail-safe hold, never a silent settle.
+ */
+export interface SoftSteerCallbacks {
+  settleMidTurnConsumed?: (relayIds: number[]) => void;
+  reofferMidTurnIds?: (relayIds: number[]) => void;
+}
+
+export interface ArmedWake {
+  targets: string[];
+}
+
+/**
+ * Durable-until-consumed ledger for positively-persisted soft batches. "Durable" is scoped to
+ * the adapter instance lifetime on purpose: the runner holds the only authoritative queue, and
+ * every ledger exit (consumption, session replacement, shutdown) hands relay ids BACK to the
+ * runner through the settlement callbacks — the ledger itself never drops an id silently.
+ */
+export class OpenCodeSoftSteerLedger {
+  private entries = new Map<string, SoftSteerEntry>();
+  private callbacks: SoftSteerCallbacks = {};
+  private wake: ArmedWake | undefined;
+
+  setCallbacks(callbacks: SoftSteerCallbacks): void {
+    this.callbacks = callbacks;
+  }
+
+  isTrackedUserId(messageID: string): boolean {
+    return this.entries.has(messageID);
+  }
+
+  awaitingCount(): number {
+    return this.entries.size;
+  }
+
+  hasAwaiting(sessionId: string): boolean {
+    for (const entry of this.entries.values()) if (entry.sessionId === sessionId) return true;
+    return false;
+  }
+
+  /**
+   * Record a batch. Returns false when the ledger is at its backpressure cap — the caller must
+   * treat a POSITIVE persist as deferred (normal queue) instead of tracking it, so caps degrade
+   * to the old behavior rather than to dropped messages. An UNKNOWN-outcome batch must always be
+   * tracked (`force: true`): the cap gates new positive persists, never the resolvability of an
+   * already-attempted POST — an untracked unknown batch could never be resolved by the
+   * consumption door, session replacement, or shutdown reoffer, yet the deliverMidTurn contract
+   * reported it as held (silent loss).
+   */
+  noteBatch(messageID: string, relayIds: number[], sessionId: string, opts?: { force?: boolean; inputObserver?: ProviderInputObserver }): boolean {
+    if (!opts?.force && this.entries.size >= OPENCODE_SOFT_STEER_MAX_BATCHES) return false;
+    this.entries.set(messageID, { messageID, relayIds, sessionId, acceptedAt: Date.now(), inputObserver: opts?.inputObserver });
+    return true;
+  }
+
+  /**
+   * Consumption door: an assistant message whose `info.parentID` equals a tracked batch's user
+   * id proves the model consumed that batch (live-proven). FIFO settle: the matched batch and
+   * every OLDER pending batch settle together (the loop consumes rows in order, and an older
+   * row still unconsumed when a newer one is consumed is consumed by that same step's reload).
+   * Returns the settled relay ids — empty when the parent matches nothing tracked, or when
+   * settlement failed and the entries were re-inserted for a later attempt.
+   */
+  async consumeByParent(parentMessageID: string, sessionId: string): Promise<number[]> {
+    const matched = this.entries.get(parentMessageID);
+    if (!matched || matched.sessionId !== sessionId) return [];
+    const collected: SoftSteerEntry[] = [];
+    for (const [id, entry] of this.entries) {
+      collected.push(entry);
+      this.entries.delete(id);
+      if (id === parentMessageID) break;
+    }
+    return this.settle(collected, "consumed");
+  }
+
+  /**
+   * Session replacement (clear swap / reroll): batches bound to any OTHER session can never be
+   * consumed on the new one. Drop them and reoffer their relay ids to the normal queue — never a
+   * repost into the new session (that would duplicate content the new session intentionally
+   * starts without). Returns the reoffered relay ids — empty when nothing was pending, or when
+   * settlement failed and the entries were re-inserted for a later attempt.
+   */
+  async sessionReplaced(activeSessionId: string): Promise<number[]> {
+    const collected: SoftSteerEntry[] = [];
+    for (const [id, entry] of this.entries) {
+      if (entry.sessionId !== activeSessionId) {
+        collected.push(entry);
+        this.entries.delete(id);
+      }
+    }
+    return this.settle(collected, "reoffer");
+  }
+
+  /** Teardown: everything left goes back to the runner via the settlement callback. */
+  async reofferAll(): Promise<number[]> {
+    const collected = [...this.entries.values()];
+    this.entries.clear();
+    return this.settle(collected, "reoffer");
+  }
+
+  /**
+   * Arm the single bounded idle-wake over the awaiting batches of ONE session. Exactly one wake
+   * at a time (design F): a second call while one is pending is a no-op. Returns the wake token
+   * (target message ids snapshot) or undefined when there is nothing to wake for.
+   */
+  armWake(sessionId: string): ArmedWake | undefined {
+    if (this.wake) return undefined;
+    const targets: string[] = [];
+    for (const [id, entry] of this.entries) if (entry.sessionId === sessionId) targets.push(id);
+    if (targets.length === 0) return undefined;
+    this.wake = { targets };
+    return this.wake;
+  }
+
+  /**
+   * Wake turn completed successfully: settle its target batches (what they carried is provably
+   * in the session context the wake turn just ran against). Skips targets already settled by the
+   * consumption door mid-flight. Returns the settled relay ids — empty when a target was already
+   * settled, or when settlement failed and the entries were re-inserted for a later attempt.
+   * A FAILED wake turn must not call this at all: its entries stay pending for session
+   * replacement / shutdown reoffer (a failed session must not mark anything delivered).
+   */
+  async settleWakeTargets(wake: ArmedWake): Promise<number[]> {
+    const collected: SoftSteerEntry[] = [];
+    for (const id of wake.targets) {
+      const entry = this.entries.get(id);
+      if (!entry) continue;
+      collected.push(entry);
+      this.entries.delete(id);
+    }
+    return this.settle(collected, "consumed");
+  }
+
+  endWake(): void {
+    this.wake = undefined;
+  }
+
+  isWakePending(): boolean {
+    return this.wake !== undefined;
+  }
+
+  /**
+   * Fire settleMidTurnConsumed. Awaits the callback (the runner's settlement fns are async) and
+   * reports failure instead of swallowing it — a failed delivery report must fall back to reoffer,
+   * never vanish behind a log line. An ABSENT callback is a failure too (fail-safe): a runner
+   * wiring miss must hold the ids in the ledger for a later exit, never silently "settle" them.
+   */
+  async notifyConsumed(relayIds: number[]): Promise<boolean> {
+    if (relayIds.length === 0) return true;
+    if (!this.callbacks.settleMidTurnConsumed) {
+      logger.error("opencode", `soft-steer settleMidTurnConsumed callback ABSENT — holding ${relayIds.length} relay id(s) in the ledger (fail-safe, never silently settled)`);
+      return false;
+    }
+    try {
+      await this.callbacks.settleMidTurnConsumed(relayIds);
+      return true;
+    } catch (error) {
+      logger.error("opencode", `soft-steer settleMidTurnConsumed callback failed: ${errMessage(error)}`);
+      return false;
+    }
+  }
+
+  /** Fire onReoffer — same failure-visible contract as notifyConsumed, absent-callback fail-safe included. */
+  async notifyReoffer(relayIds: number[]): Promise<boolean> {
+    if (relayIds.length === 0) return true;
+    if (!this.callbacks.reofferMidTurnIds) {
+      logger.error("opencode", `soft-steer reofferMidTurnIds callback ABSENT — holding ${relayIds.length} relay id(s) in the ledger (fail-safe, never silently settled)`);
+      return false;
+    }
+    try {
+      await this.callbacks.reofferMidTurnIds(relayIds);
+      return true;
+    } catch (error) {
+      logger.error("opencode", `soft-steer reofferMidTurnIds callback failed: ${errMessage(error)}`);
+      return false;
+    }
+  }
+
+  /**
+   * Sole ledger-exit settlement path: a failed settleMidTurnConsumed falls back to
+   * reofferMidTurnIds (at-least-once
+   * — a duplicate delivery beats a silent loss), and if BOTH settlement callbacks fail the
+   * entries are re-inserted so a later exit (consumption door, session replacement, shutdown)
+   * can still resolve them. Robust to sync throws AND async rejections: the awaits observe
+   * both. Returns the settled relay ids, or [] when the entries were re-inserted.
+   */
+  private async settle(collected: SoftSteerEntry[], kind: "consumed" | "reoffer"): Promise<number[]> {
+    const relayIds = collected.flatMap((entry) => entry.relayIds);
+    if (relayIds.length === 0) return [];
+    if (kind === "consumed") for (const entry of collected) entry.inputObserver?.consumed();
+    const primary = kind === "consumed" ? await this.notifyConsumed(relayIds) : await this.notifyReoffer(relayIds);
+    if (primary) return relayIds;
+    if (kind === "consumed" && (await this.notifyReoffer(relayIds))) return relayIds;
+    // Map.set appends: a re-inserted OLDER entry may temporarily sit after newer batches —
+    // latency-only (the FIFO door settles it alongside a newer parent, and wake/reoffer exits
+    // scan the whole map). Intentional: every entry stays resolvable.
+    for (const entry of collected) this.entries.set(entry.messageID, entry);
+    return [];
+  }
+}

package/src/adapters/opencode-spawn.ts

@@ -0,0 +1,145 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sanitizeFsName } from "@humwick/sdk/fs-name";
+import { providerScratchEnvOf } from "@humwick/sdk/provider-scratch";
+import { openCodeProjectShellEnv } from "./project-shell";
+import { providerHomeRootFromEnv } from "../config";
+import { materializeProviderHome } from "../profile-home";
+import { syncOpenCodeRedactPlugin } from "../agent-redact";
+import type { ProviderConfig, RunnerSpawnConfig, SpawnArgs } from "../adapter";
+import { allocateLoopbackPort } from "../free-port";
+import { assembleLaunch, openCodeMcpConfigForLaunch } from "../launch-assembly";
+import { openCodePermissions, openCodeToolsConfig } from "./opencode-tools-config";
+import { openCodeApiKey } from "./opencode-api";
+import { openCodeBackend, openCodeBackendCredential, openCodeResolvedBackend, type OpenCodeModelId } from "./opencode-provider";
+
+export function assertOpenCodeApprovalMode(approvalMode: string | undefined): asserts approvalMode is "open" {
+  if (approvalMode !== "open") {
+    throw new Error(`OpenCode only supports approvalMode=open; received ${approvalMode ?? "unset"}. Guarded and read-only are not available and will not fall back to open.`);
+  }
+}
+
+// The relay owns this server's network boundary. In particular, keeping these values at the
+// front of argv is not enough: OpenCode accepts later values as overrides. Reject every spelling
+// that can alter the listener or turn on discovery/cross-origin access instead of trying to
+// sanitize and then silently changing a caller's intended command line.
+const MANAGED_SERVER_ARGUMENTS = new Set([
+  "--hostname", "--host", "-h",
+  "--port", "-p",
+  "--mdns", "--no-mdns",
+  "--cors", "--no-cors",
+]);
+
+export function assertOpenCodeManagedServerArgs(providerArgs: string[]): void {
+  for (const raw of providerArgs) {
+    const option = raw.split("=", 1)[0]!.toLowerCase();
+    if (MANAGED_SERVER_ARGUMENTS.has(option)) {
+      throw new Error(`OpenCode manages ${option}; providerArgs cannot override the loopback listener, managed port, mDNS, or CORS.`);
+    }
+  }
+}
+
+/** Prevent config substitution in caller-supplied model names (#2378). */
+export function assertOpenCodeSafeModel(model: string | undefined): void {
+  if (model?.includes("{")) {
+    throw new Error(`OpenCode model must not contain "{" (would be spliced by OpenCode's own {env:...}/{file:...} config substitution): received ${JSON.stringify(model)}`);
+  }
+}
+
+/** Preserve host gh auth while isolating OpenCode XDG state (#2531). */
+export function resolveGhConfigDir(inputEnv: Record<string, string | undefined>): string | undefined {
+  const explicit = inputEnv.GH_CONFIG_DIR;
+  if (explicit) return explicit;
+  const hostConfigHome = inputEnv.XDG_CONFIG_HOME;
+  if (hostConfigHome) return join(hostConfigHome, "gh");
+  const home = inputEnv.HOME;
+  if (home) return join(home, ".config", "gh");
+  return undefined;
+}
+
+export function buildOpenCodeSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig, provider: string, launch: OpenCodeModelId): SpawnArgs {
+  assertOpenCodeApprovalMode(config.approvalMode);
+  assertOpenCodeManagedServerArgs(config.providerArgs);
+  assertOpenCodeSafeModel(config.model);
+  assertOpenCodeSafeModel(config.modelRecord?.qualifiedModel);
+  openCodeBackend(provider);
+  // The selected model owns its backend and credential (#2599/#2600).
+  const resolved = openCodeResolvedBackend(launch.backendID, provider);
+  // `||`, not `??`: an empty-string runner env var must not mask a valid providerConfig key.
+  const apiKey = openCodeApiKey(config, launch.qualified) ?? openCodeBackendCredential(resolved.apiKeyEnvVar, config.env, providerConfig.env, resolved.hostAuth ? resolved.opencodeProviderID : undefined);
+  const assembled = assembleLaunch(provider, config, providerConfig);
+  const profile = sanitizeFsName(config.agentProfile?.name || config.profile || "default", { replacement: "-", lowercase: true });
+  const instanceId = sanitizeFsName(config.instanceId || config.runnerId, { replacement: "-", lowercase: true });
+  const root = join(providerHomeRootFromEnv(), provider, profile, instanceId);
+  materializeProviderHome(root, { provider: provider, profile, instanceId, agentId: config.agentId }, 0o700);
+  const xdgConfig = join(root, "config");
+  const xdgData = join(root, "data");
+  const xdgState = join(root, "state");
+  const xdgCache = join(root, "cache");
+  const configDir = join(xdgConfig, "opencode");
+  for (const path of [xdgConfig, xdgData, xdgState, xdgCache, configDir]) mkdirSync(path, { recursive: true, mode: 0o700 });
+  // Permission is pinned in the isolated server config. A guarded/read-only request rejects
+  // before this file is written, so a policy downgrade can never become a permissive launch.
+  const configFile = join(configDir, "opencode.json");
+  const mcp = openCodeMcpConfigForLaunch(config);
+  // Keep credentials out of disk config using native env references (#2378).
+  writeFileSync(configFile, `${JSON.stringify({
+    $schema: "https://opencode.ai/config.json",
+    model: launch.qualified,
+    ...(launch.backendID === "openai" ? { small_model: launch.qualified, enabled_providers: ["openai"] } : {}),
+    provider: {
+      [resolved.opencodeProviderID]: {
+        // A custom Relay backend (e.g. zai) carries its own adapter package; built-in
+        // backends (opencode, openrouter, anthropic, ...) ship inside opencode itself.
+        ...(resolved.npm ? { npm: resolved.npm } : {}),
+        options: { ...resolved.extraOptions, ...(launch.backendID === "openai" ? { baseURL: "https://api.openai.com/v1", serviceTier: "default" } : {}), ...(resolved.baseURL ? { baseURL: resolved.baseURL } : {}), ...(resolved.apiKeyEnvVar ? { apiKey: `{env:${resolved.apiKeyEnvVar}}` } : {}) },
+        models: { [launch.modelID]: launch.backendID === "openai" ? { limit: { context: 272_000, output: 128_000 } } : {} },
+      },
+    },
+    permission: openCodePermissions(config), ...(Object.keys(mcp).length ? { mcp } : {}), ...openCodeToolsConfig(config, Object.keys(mcp).length > 0),
+  }, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(configFile, 0o600);
+  // #3025 — `--pure` skips every plugin, so it is dropped only when agent-redact's plugin is in place.
+  const pure = syncOpenCodeRedactPlugin(configDir, assembled.redaction) ? [] : ["--pure"];
+  // Bridge gh from the host env before overlaying isolated XDG roots (#2531).
+  const ghConfigDir = resolveGhConfigDir({ ...config.env, ...providerConfig.env, ...assembled.env });
+  // #2719 — allocated, never derived from another port. `controlPort + 1_000` overflowed 65535
+  // whenever the OS handed the runner a high ephemeral control port (macOS: 49152-65535), and
+  // `serve --port 66178` did not fail loudly: opencode bound a different port, so readiness
+  // polled the wrong URL for 20s and the runner exited 1 with no report.
+  const port = allocateLoopbackPort();
+  const serverUrl = `http://127.0.0.1:${port}`;
+  const env: SpawnArgs["env"] = writeChildEnv({}, {
+    ...config.env,
+    ...providerConfig.env,
+    // #3084 — the runner already nested the agent's private TMPDIR under any provider-config one;
+    // the shell hooks keep it (and #2947's toolchain PATH) after a login profile runs.
+    ...providerScratchEnvOf(config.env),
+    ...openCodeProjectShellEnv(config.env),
+    ...assembled.env,
+    // #2531 — gh (and git credential helpers wrapping gh) read the HOST gh config even
+    // under the isolated XDG roots below. No other credential surface is bridged.
+    ...(ghConfigDir ? { GH_CONFIG_DIR: ghConfigDir } : {}),
+    XDG_CONFIG_HOME: xdgConfig,
+    XDG_DATA_HOME: xdgData,
+    XDG_STATE_HOME: xdgState,
+    XDG_CACHE_HOME: xdgCache,
+    // The server subprocess receives a deliberately assembled environment; retain the
+    // executable search path while keeping its XDG state isolated.
+    PATH: config.env.PATH ?? providerConfig.env.PATH ?? process.env.PATH ?? "",
+    ...(resolved.apiKeyEnvVar && apiKey ? { [resolved.apiKeyEnvVar]: apiKey } : {}),
+    OPENCODE_SERVER_PASSWORD: crypto.randomUUID(),
+    OPENCODE_SERVER_URL: serverUrl,
+    AGENT_RELAY_PROVIDER: provider,
+  });
+  if (launch.backendID === "openai") {
+    for (const key of ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN", "OPENCODE_API_KEY"]) writeChildEnv(env, {}, [key]);
+  }
+  return {
+    command: providerConfig.command || "opencode",
+    args: ["serve", ...pure, "--hostname", "127.0.0.1", "--port", String(port), ...assembled.args, ...config.providerArgs],
+    cwd: config.cwd,
+    env,
+  };
+}