@yansigit/opencodex 2.31.0

package/src/server/responses/responses-field-backfill.ts

@@ -0,0 +1,251 @@
+/**
+ * Stateless SSE block rewrite that backfills the `annotations` field on
+ * `output_text` content parts in Responses SSE events.
+ *
+ * The Responses API spec defines `annotations` as a required field on
+ * `OutputTextContent` (it is `Vec<Annotation>`, not `Option<Vec>`). Some
+ * upstream relays omit it when there are no annotations, which is technically
+ * spec-non-compliant. Strict deserializers — any client that follows the
+ * schema without `#[serde(default)]` on that field — fail with
+ * `missing field `annotations`` when the field is absent.
+ *
+ * This rewrite scans every SSE event for output_text content parts — whether
+ * they appear in item.content[], part, or response.output[].content[] — and
+ * adds annotations: [] if missing.
+ *
+ * Stateless: no retained buffers, no lifecycle tracking, no fail-closed.
+ * Existing values are always authoritative; only absent fields are added.
+ * The field is always valid on the wire, so adding it when absent is safe
+ * for all clients including Codex CLI/App.
+ */
+
+import {
+  replaceSseDataPayload,
+  sseDataPayload,
+  type SseBlockRewrite,
+} from "../sse-payload-rewrite";
+import { isCompactionItemType } from "../../responses/compaction";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** Wire prefixes for Responses output item ids, matching OpenAI's id shapes. */
+const ITEM_ID_PREFIXES: Readonly<Record<string, string>> = {
+  message: "msg_",
+  reasoning: "rs_",
+  function_call: "fc_",
+  custom_tool_call: "ctc_",
+  // A routed tool_search lowering is restored to `tool_search_call` without an id, so this
+  // backfill is what names it. The generic `item_` fallback is not merely cosmetic here:
+  // `stripInvalidItemIds` in the Responses adapter deletes any id whose prefix does not match
+  // the type, so an `item_`-named tool_search_call silently loses its id on the NEXT turn and
+  // the client sees an item it cannot correlate. The prefixes here must stay a superset of the
+  // ones that serializer enforces.
+  tool_search_call: "tsc_",
+  web_search_call: "ws_",
+  file_search_call: "fs_",
+  code_interpreter_call: "ci_",
+  computer_call: "cc_",
+  // The Responses wire type is `image_generation_call`; `image_gen_call` is kept only so a
+  // relay that emits the short spelling is not silently demoted to the generic `item_`.
+  image_generation_call: "ig_",
+  image_gen_call: "ig_",
+};
+
+/**
+ * Backfill a required id on an output item when absent. Strict Responses
+ * decoders (e.g. grok-build serde types) fail with "missing field id" when a
+ * message or reasoning item has no id, which some upstream relays omit. The
+ * generated id is deterministic per (type, output index) so it stays stable
+ * across streaming events that reference the same item.
+ */
+function backfillItemId(item: Record<string, unknown>, slot: ItemIdSlot): Record<string, unknown> {
+  if (typeof item.id === "string" && item.id.length > 0) return item;
+  const type = typeof item.type === "string" ? item.type : "";
+  const prefix = Object.prototype.hasOwnProperty.call(ITEM_ID_PREFIXES, type) ? ITEM_ID_PREFIXES[type] : "item_";
+  return { ...item, id: prefix + "ocx_" + (slot.kind === "index" ? String(slot.index) : "fallback_" + slot.ordinal) };
+}
+
+/**
+ * Which namespace a synthesized id comes from.
+ *
+ * Keeping the fallback counter in the SAME numeric namespace as real output indexes only
+ * pushed the collision out of reach rather than removing it: a response whose real index
+ * happened to be 1_000_001 would produce the same id as the first malformed-index fallback,
+ * and a duplicate id is exactly what this backfill exists to prevent. The namespaces are now
+ * lexically disjoint, so no index value can ever collide with a fallback.
+ */
+type ItemIdSlot = { kind: "index"; index: number } | { kind: "fallback"; ordinal: number };
+
+/**
+ * Monotonic ordinal for an event whose `output_index` is absent or malformed.
+ *
+ * Process-global rather than per-response because this module is stateless by design and the
+ * value only has to be unique, not meaningful. It carries its own `fallback_` namespace, so
+ * uniqueness no longer depends on a real index never reaching some arbitrary ceiling.
+ */
+let syntheticItemOrdinal = 0;
+function nextSyntheticItemSlot(): ItemIdSlot {
+  syntheticItemOrdinal += 1;
+  return { kind: "fallback", ordinal: syntheticItemOrdinal };
+}
+
+/**
+ * Backfill annotations: [] on an output_text content part if missing.
+ * Returns the same object reference if no change is needed.
+ */
+function backfillOutputTextPart(part: Record<string, unknown>): Record<string, unknown> {
+  if (part.type !== "output_text") return part;
+  // Only add annotations when the key is entirely absent — preserve any
+  // existing value (even null or a malformed type) so we never overwrite
+  // what the upstream actually sent.
+  if ("annotations" in part) return part;
+  return { ...part, annotations: [] };
+}
+
+/**
+ * Walk a content array and backfill output_text parts.
+ * Returns the same array reference if nothing changed.
+ */
+function backfillContentArray(content: unknown): unknown {
+  if (!Array.isArray(content)) return content;
+  let changed = false;
+  const repaired = content.map((part) => {
+    if (!isPlainObject(part)) return part;
+    const next = backfillOutputTextPart(part);
+    if (next !== part) changed = true;
+    return next;
+  });
+  return changed ? repaired : content;
+}
+
+/**
+ * Walk an output item and backfill output_text parts in its content.
+ * Also backfills a missing required id on the item itself.
+ * Returns the same object reference if nothing changed.
+ */
+function backfillOutputItem(item: unknown, slot: ItemIdSlot): unknown {
+  if (!isPlainObject(item)) return item;
+  // The compact wire family is the `/v1/responses/compact` format, not a Responses output item.
+  // Those items have no `id` in that contract, so synthesizing one changes a response body the
+  // client compares exactly — and the client replays the item on every later turn, where the
+  // minting backend rejects it as modified. The backfill exists to satisfy strict Responses
+  // decoders; a shape those decoders never see is outside its remit.
+  if (isCompactionItemType(item.type)) return item;
+  const content = item.content;
+  const repaired = backfillContentArray(content);
+  const withId = backfillItemId(item, slot);
+  if (repaired === content && withId === item) return item;
+  return { ...withId, ...(repaired === content ? {} : { content: repaired }) };
+}
+
+/**
+ * Walk a response object's output[] and backfill output_text parts.
+ * Returns the same object reference if nothing changed.
+ */
+function backfillResponseOutput(response: unknown): unknown {
+  if (!isPlainObject(response)) return response;
+  const output = response.output;
+  if (!Array.isArray(output)) return response;
+  let changed = false;
+  const repaired = output.map((item, idx) => {
+    if (!isPlainObject(item)) return item;
+    const next = backfillOutputItem(item, { kind: "index", index: idx });
+    if (next !== item) changed = true;
+    return next;
+  });
+  return changed ? { ...response, output: repaired } : response;
+}
+
+/**
+ * Statelessly rewrite one SSE event: backfill annotations
+ * on any output_text content part found in the event payload.
+ */
+function rewriteEvent(event: Record<string, unknown>): Record<string, unknown> {
+  const type = typeof event.type === "string" ? event.type : "";
+  let next = event;
+  let changed = false;
+
+  // output_item.added / output_item.done: item.content[] -> output_text parts
+  if ((type === "response.output_item.added" || type === "response.output_item.done")
+    && isPlainObject(event.item)) {
+    const rawIndex = event.output_index;
+    // A malformed or absent `output_index` must not collapse to 0: two such events would then
+    // both synthesize `msg_ocx_0`, and duplicate ids are the very thing this backfill exists to
+    // prevent. Fall back to a per-process counter so the synthesized id stays unique. Position
+    // is not recoverable in that case, but a unique id is what strict decoders require, and a
+    // well-formed stream still gets the stable index-derived id.
+    const item = typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0
+      ? backfillOutputItem(event.item, { kind: "index", index: rawIndex })
+      : backfillOutputItem(event.item, nextSyntheticItemSlot());
+    if (item !== event.item) {
+      next = { ...next, item };
+      changed = true;
+    }
+  }
+
+  // content_part.added / content_part.done: part -> output_text
+  if ((type === "response.content_part.added" || type === "response.content_part.done")
+    && isPlainObject(event.part)) {
+    const part = backfillOutputTextPart(event.part);
+    if (part !== event.part) {
+      next = { ...next, part };
+      changed = true;
+    }
+  }
+
+  // response.created / in_progress / completed / incomplete / failed:
+  // response.output[].content[] -> output_text parts
+  if (isPlainObject(event.response)) {
+    const response = backfillResponseOutput(event.response);
+    if (response !== event.response) {
+      next = { ...next, response };
+      changed = true;
+    }
+  }
+
+  return changed ? next : event;
+}
+
+/**
+ * Create a stateless SSE block rewrite that backfills annotations and
+ * on output_text content parts. Unconditional: the field is a required
+ * canonical Responses field, so adding it when absent is safe for all
+ * clients.
+ */
+export function createResponsesFieldBackfillBlockRewrite(): SseBlockRewrite {
+  const rewrite: SseBlockRewrite = (block: string): readonly string[] => {
+    const payload = sseDataPayload(block);
+    if (payload === null) return [block];
+    let event: unknown;
+    try {
+      event = JSON.parse(payload);
+    } catch {
+      return [block];
+    }
+    if (!isPlainObject(event)) return [block];
+    const rewritten = rewriteEvent(event);
+    if (rewritten === event) return [block];
+    return [replaceSseDataPayload(block, JSON.stringify(rewritten))];
+  };
+  return rewrite;
+}
+
+/**
+ * Backfill annotations on a non-streaming Responses JSON
+ * object. Mirrors the SSE block rewrite for the bounded-JSON passthrough
+ * path. Returns the original string if no change is needed.
+ */
+export function backfillResponsesFieldsJson(payload: string): string {
+  let response: unknown;
+  try {
+    response = JSON.parse(payload);
+  } catch {
+    return payload;
+  }
+  if (!isPlainObject(response)) return payload;
+  const repaired = backfillResponseOutput(response);
+  if (repaired === response) return payload;
+  return JSON.stringify(repaired);
+}

package/src/server/responses/terminal-guard.ts

@@ -0,0 +1,251 @@
+import type {
+  AdapterEvent,
+  OcxAssistantContentPart,
+  OcxAssistantMessage,
+  OcxParsedRequest,
+  OcxUsage,
+} from "../../types";
+
+const ACTIONABLE_REQUEST_RE = /(?:\b(?:add|change|check|continue|create|debug|delete|deploy|edit|execute|fix|implement|inspect|keep going|modify|patch|proceed|refactor|remove|review|run|test|update|write)\b|继续|接着|往下|升级|修改|改(?:一下|下)?|修复|实现|添加|新增|删除|重构|更新|运行|执行|检查|查看|排查|调试|创建|写入|提交|推送|部署|看下|改成|修一下)/iu;
+const PLAN_ONLY_REQUEST_RE = /(?:暂时不要(?:调用|使用)工具|不要调用工具|不用执行|只回复(?:计划|方案)|(?:只|先|给|说|写|出|来)(?:我)?(?:一个|个|一下|份)?[^。！？\n]{0,8}?(?:计划|方案|草案|提案|思路)|(?:计划|方案|草案|提案|思路)(?:就(?:行|好|可以)|即可)|\b(?:just give|provide)\s+(?:me\s+)?(?:a\s+)?plan\b|\b(?:do not|don't)\s+(?:use|call)\s+tools?\b|\b(?:write|draft|outline|propose|give|provide|create|make|share|suggest|sketch)\s+(?:me\s+)?(?:a\s+|an\s+|the\s+|your\s+)?(?:(?:brief|concise|short|detailed|high[-\s]?level|rough|quick|step[-\s]?by[-\s]?step|implementation|migration|refactor(?:ing)?|design|technical)\s+)*(?:plan|proposal|draft|outline|approach|strategy|design\s+doc)\b)/iu;
+const PLAN_INTENT_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|let me|next i)\b|我(?:先|会|将|接下来)|下一步)/iu;
+const PLAN_OR_COMPLETION_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|let me|next i|i(?:'|’)ve (?:already )?(?:added|applied|changed|completed|fixed|implemented|modified|updated))\b|\b(?:done|completed|fixed|implemented|updated|applied)\b|我(?:先|会|将|接下来)|下一步|已(?:经)?(?:修改|修复|完成|应用|更新|实现|处理)|完成了|已经好了)/iu;
+const WAITING_FOR_USER_RE = /(?:[?？]\s*$|需要我|请(?:确认|选择|提供)|是否|要不要|可以吗|\b(?:do you want|should i|which file|please confirm|please provide)\b)/iu;
+const EXPLICIT_CONTINUE_RE = /^(?:继续|接着|往下|go on|continue|proceed|keep going)\s*[.!。！]?$/iu;
+const MAX_ANNOUNCEMENT_CHARS = 280;
+
+export const TERMINAL_GUARD_NUDGE =
+  "你刚才只描述了计划，没有执行任何工具。不要再次解释计划，现在立即调用必要工具执行用户任务。" +
+  "只有工具返回后才总结；如果确实无法执行，请明确说明阻塞原因。";
+
+export type TerminalGuardDecision = "pass" | "continue" | "ambiguous";
+
+export interface TerminalTurnAnalysis {
+  decision: TerminalGuardDecision;
+  reason: "normal" | "waiting_for_user" | "no_tools" | "no_actionable_request" | "no_execution_claim" | "recent_tool_activity" | "substantive_answer" | "suspicious_no_tool";
+  assistantText: string;
+  userText: string;
+  hasToolCall: boolean;
+}
+
+function messageText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value
+    .filter((part): part is { type?: unknown; text?: unknown } => !!part && typeof part === "object")
+    .filter(part => part.type === "text" && typeof part.text === "string")
+    .map(part => part.text as string)
+    .join("");
+}
+
+function latestUserText(parsed: OcxParsedRequest): string {
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "user") return messageText(message.content);
+  }
+  return "";
+}
+
+function recentTurnHasToolActivity(parsed: OcxParsedRequest): boolean {
+  let latestUserIndex = -1;
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    if (parsed.context.messages[i]?.role === "user") {
+      latestUserIndex = i;
+      break;
+    }
+  }
+  if (latestUserIndex < 0) return false;
+  let lastAssistant: OcxAssistantMessage | undefined;
+  for (let i = latestUserIndex - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "assistant") {
+      lastAssistant = message;
+      break;
+    }
+  }
+  if (lastAssistant?.role === "assistant") {
+    const hasToolCall = lastAssistant.content.some(part => part.type === "toolCall");
+    const text = lastAssistant.content
+      .filter(part => part.type === "text")
+      .map(part => part.text)
+      .join("");
+    if (!hasToolCall && PLAN_INTENT_RE.test(text)) return false;
+  }
+  for (let i = latestUserIndex - 1; i >= 0 && parsed.context.messages[i]?.role !== "user"; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "toolResult") return true;
+    if (message.role === "assistant" && message.content.some(part => part.type === "toolCall")) return true;
+  }
+  return false;
+}
+
+function assistantText(events: readonly AdapterEvent[]): string {
+  return events
+    .filter((event): event is Extract<AdapterEvent, { type: "text_delta" }> => event.type === "text_delta")
+    .map(event => event.text)
+    .join("");
+}
+
+export function analyzeTerminalTurn(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): TerminalTurnAnalysis {
+  const userText = latestUserText(parsed);
+  const text = assistantText(events);
+  const hasToolCall = events.some(event => event.type === "tool_call_start");
+  if (hasToolCall) {
+    return { decision: "pass", reason: "normal", assistantText: text, userText, hasToolCall };
+  }
+  if (!parsed.context.tools || parsed.context.tools.length === 0 || parsed.options.toolChoice === "none") {
+    return { decision: "pass", reason: "no_tools", assistantText: text, userText, hasToolCall };
+  }
+  if (!ACTIONABLE_REQUEST_RE.test(userText)) {
+    return { decision: "pass", reason: "no_actionable_request", assistantText: text, userText, hasToolCall };
+  }
+  if (PLAN_ONLY_REQUEST_RE.test(userText)) {
+    return { decision: "pass", reason: "no_actionable_request", assistantText: text, userText, hasToolCall };
+  }
+  if (EXPLICIT_CONTINUE_RE.test(userText) && recentTurnHasToolActivity(parsed)) {
+    return { decision: "pass", reason: "recent_tool_activity", assistantText: text, userText, hasToolCall };
+  }
+  if (WAITING_FOR_USER_RE.test(text)) {
+    return { decision: "pass", reason: "waiting_for_user", assistantText: text, userText, hasToolCall };
+  }
+  if (text.trim().length > MAX_ANNOUNCEMENT_CHARS) {
+    return { decision: "pass", reason: "substantive_answer", assistantText: text, userText, hasToolCall };
+  }
+  if (!PLAN_OR_COMPLETION_RE.test(text)) {
+    return { decision: "ambiguous", reason: "no_execution_claim", assistantText: text, userText, hasToolCall };
+  }
+  return { decision: "continue", reason: "suspicious_no_tool", assistantText: text, userText, hasToolCall };
+}
+
+function assistantMessageFromEvents(events: readonly AdapterEvent[], timestamp: number): OcxAssistantMessage | undefined {
+  let text = "";
+  let thinking = "";
+  let signature: string | undefined;
+  const redacted: string[] = [];
+  for (const event of events) {
+    if (event.type === "text_delta") text += event.text;
+    else if (event.type === "thinking_delta") thinking += event.thinking;
+    else if (event.type === "thinking_signature") signature = event.signature;
+    else if (event.type === "redacted_thinking") redacted.push(event.data);
+  }
+  const content: OcxAssistantContentPart[] = [];
+  if (thinking || signature || redacted.length > 0) {
+    content.push({ type: "thinking", thinking, ...(signature ? { signature } : {}), ...(redacted.length > 0 ? { redacted } : {}) });
+  }
+  if (text) content.push({ type: "text", text });
+  if (content.length === 0) return undefined;
+  return { role: "assistant", content, timestamp };
+}
+
+export function buildContinuationRequest(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): OcxParsedRequest {
+  const messages = [...parsed.context.messages];
+  // One clock read for the whole rebuild. Two Date.now() calls could straddle a millisecond
+  // boundary, which made the retained-heartbeat contract test fail intermittently in CI on a
+  // 1ms skew between the assistant message and the nudge that follows it.
+  const timestamp = Date.now();
+  const assistant = assistantMessageFromEvents(events, timestamp);
+  if (assistant) messages.push(assistant);
+  messages.push({ role: "developer", content: TERMINAL_GUARD_NUDGE, timestamp });
+  return { ...parsed, context: { ...parsed.context, messages } };
+}
+
+export interface GuardedEventStreamOptions {
+  parsed: OcxParsedRequest;
+  firstEvents: AsyncIterable<AdapterEvent>;
+  continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+  adapterName?: string;
+  maxAutoContinuations?: number;
+}
+
+/**
+ * Events that are useful to the downstream stream consumer but carry no state used by the
+ * terminal-continuation decision or its rebuilt request. Keep them out of the retained event
+ * list so adapter liveness markers and arbitrarily large tool-argument fragments cannot make
+ * the guard's per-turn memory grow without adding any continuation semantics.
+ */
+export function isTerminalGuardPassthroughOnly(event: AdapterEvent): boolean {
+  return event.type === "heartbeat" || event.type === "tool_call_delta";
+}
+
+function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  const sumOptional = (key: keyof OcxUsage): number | undefined => {
+    const left = first[key];
+    const right = second[key];
+    return typeof left === "number" || typeof right === "number"
+      ? (typeof left === "number" ? left : 0) + (typeof right === "number" ? right : 0)
+      : undefined;
+  };
+  const cachedInputTokens = sumOptional("cachedInputTokens");
+  const cacheReadInputTokens = sumOptional("cacheReadInputTokens");
+  const cacheCreationInputTokens = sumOptional("cacheCreationInputTokens");
+  const reasoningOutputTokens = sumOptional("reasoningOutputTokens");
+  const inputTokens = first.inputTokens + second.inputTokens;
+  const outputTokens = first.outputTokens + second.outputTokens;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+    ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+    ...(reasoningOutputTokens !== undefined ? { reasoningOutputTokens } : {}),
+    ...(first.estimated || second.estimated ? { estimated: true } : {}),
+  };
+}
+
+/** Preserve normal terminals, but withhold one suspicious no-tool terminal for a bounded re-ask. */
+export async function* guardTerminalEventStream(options: GuardedEventStreamOptions): AsyncGenerator<AdapterEvent> {
+  const maxContinuations = Math.max(0, Math.min(2, Math.floor(options.maxAutoContinuations ?? 1)));
+  let parsed = options.parsed;
+  let continuations = 0;
+  let accumulatedUsage: OcxUsage | undefined;
+  let source: AsyncIterable<AdapterEvent> = options.firstEvents;
+
+  while (true) {
+    const seen: AdapterEvent[] = [];
+    let terminalSeen = false;
+    for await (const event of source) {
+      // Liveness markers and tool argument fragments are passed through to the bridge, but
+      // neither analyzeTerminalTurn nor buildContinuationRequest consumes them. Retaining the
+      // fragments would duplicate arbitrarily large argument payloads in `seen` for no effect.
+      if (isTerminalGuardPassthroughOnly(event)) {
+        yield event;
+        continue;
+      }
+      if (event.type === "done") {
+        terminalSeen = true;
+        const analysis = (options.adapterName === "anthropic" || options.adapterName === "openai-chat")
+          ? analyzeTerminalTurn(parsed, seen)
+          : { decision: "pass" as const };
+        const normalStop = event.stopReason !== "max_tokens" && event.stopReason !== "content_filter";
+        if (normalStop && analysis.decision === "continue" && continuations < maxContinuations) {
+          accumulatedUsage = mergeUsage(accumulatedUsage, event.usage);
+          continuations += 1;
+          parsed = buildContinuationRequest(parsed, seen);
+          yield { type: "assistant_boundary" };
+          try {
+            source = await options.continuation(parsed);
+          } catch (error) {
+            yield { type: "error", message: error instanceof Error ? error.message : String(error) };
+            return;
+          }
+          break;
+        }
+        const usage = mergeUsage(accumulatedUsage, event.usage);
+        yield usage ? { ...event, usage } : event;
+        return;
+      }
+      if (event.type === "incomplete" || event.type === "error") {
+        terminalSeen = true;
+        const usage = mergeUsage(accumulatedUsage, event.usage);
+        yield usage ? { ...event, usage } : event;
+        return;
+      }
+      seen.push(event);
+      yield event;
+    }
+    if (!terminalSeen) return;
+  }
+}

package/src/server/responses/upstream-error.ts

@@ -0,0 +1,53 @@
+/**
+ * Upstream connection failures share one message shape across the three catch sites in
+ * core.ts. A TLS certificate/hostname mismatch deserves its own wording: the generic
+ * "Provider unreachable" reads as if opencodex built a wrong endpoint, which sent issue
+ * #553 looking for an adapter URL bug that does not exist. Name the likely cause and the
+ * command that settles it.
+ */
+import { RequestPacingQueueOverloadError } from "../../providers/request-pacing";
+
+export function describeUpstreamConnectFailure(err: unknown, connectMs: number): string {
+  // Local pacing admission is not a transport failure. Let the outer response boundary
+  // preserve its retryable 429 identity instead of laundering it into a 502.
+  if (err instanceof RequestPacingQueueOverloadError) throw err;
+  if (err instanceof Error && err.name === "TimeoutError") {
+    return `Provider connect timeout after ${connectMs}ms`;
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  const code = err instanceof Error ? (err as { code?: unknown }).code : undefined;
+  // `code` is the reliable signal. The message fallback is anchored to the head because Bun
+  // renders this rejection as `ERR_TLS_CERT_ALTNAME_INVALID fetching "<url>"`; matching the
+  // bare substring anywhere would also fire on text that merely quotes the code back at us.
+  // Only transport failures reach these call sites, so that is defensive rather than load-bearing.
+  if (code === "ERR_TLS_CERT_ALTNAME_INVALID" || detail.startsWith("ERR_TLS_CERT_ALTNAME_INVALID")) {
+    const host = extractHostname(detail);
+    const target = host ?? "the provider host";
+    const probe = host ?? "<host>";
+    return `Provider TLS certificate does not match ${target}: ${redactUrlUserinfo(detail)}. `
+      + "opencodex did not rewrite this hostname — a certificate that does not cover it normally "
+      + "means TLS interception (corporate proxy, VPN, or local MITM tooling) or a poisoned DNS "
+      + `answer. Check with: openssl s_client -connect ${probe}:443 -servername ${probe} `
+      + "</dev/null | openssl x509 -noout -subject -ext subjectAltName";
+  }
+  return `Provider unreachable: ${redactUrlUserinfo(detail)}`;
+}
+
+/**
+ * A provider base URL may carry credentials as userinfo (`https://user:token@host/`), and the
+ * runtime error echoes the URL it was fetching. Strip it before the message reaches a client
+ * or a log line.
+ */
+function redactUrlUserinfo(detail: string): string {
+  return detail.replace(/(https?:\/\/)[^/\s"'@]*@/g, "$1<redacted>@");
+}
+
+function extractHostname(detail: string): string | null {
+  const match = detail.match(/https?:\/\/([^/\s"']+)/);
+  if (!match?.[1]) return null;
+  try {
+    return new URL(`https://${match[1]}`).hostname || null;
+  } catch {
+    return null;
+  }
+}