@iislee/opencodex 2.11.0 → 2.31.0

package/src/types/request.ts

@@ -0,0 +1,384 @@
+import type { KiroOAuthMetadata } from "../oauth/types";
+import type { OcxTool, OcxToolChoice } from "./tools";
+import type { TierDecision, TierObservationContext } from "./provider";
+
+/** Exact provider/credential namespace for process-local reasoning replay. */
+export interface OcxReasoningReplayIdentity {
+  providerName: string;
+  /** Opaque process-local digest of the exact upstream destination. */
+  providerDestinationIdentity: string;
+  /**
+   * The same destination, digested WITHOUT the process-local random key, so it can key a
+   * durable store. Absent when no base URL was resolvable.
+   */
+  providerDestinationDurableIdentity?: string;
+  adapterName: string;
+  modelId: string;
+  /** Opaque process-local credential identity; never a raw token or API key. */
+  credentialIdentity: string;
+  /**
+   * Salted-HMAC credential identity that survives restarts, for the durable
+   * thought-signature store (#1926). Absent when no durable identity could be
+   * derived — the durable store then refuses to key the entry (fail closed).
+   */
+  credentialDurableIdentity?: string;
+}
+
+/**
+ * Stable holder shared by parsed-request copies and already-created bridges.
+ * Credential/provider rotation replaces `current` atomically without replacing
+ * the holder, so late tool-call cache writes see the active physical identity.
+ */
+export interface OcxReasoningReplayScopeRef {
+  readonly clientThreadId: string;
+  current?: Readonly<OcxReasoningReplayIdentity>;
+}
+
+export interface OcxParsedRequest {
+  modelId: string;
+  /** Client-facing model selector retained for Anthropic routes after wire-model normalization. */
+  _responseModelId?: string;
+  /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */
+  _openAiVirtualSelectedModelId?: string;
+  previousResponseId?: string;
+  context: OcxContext;
+  stream: boolean;
+  options: OcxRequestOptions;
+  _rawBody?: unknown;
+  /**
+   * Boundary between replayed history and this turn's newly appended input. Usually the
+   * items the proxy restored from local previous_response_id state; also set when the
+   * CLIENT already carried that history verbatim and the proxy skipped the prepend.
+   */
+  _replayPrefixLen?: number;
+  /** Parsed-message index before the first conversational item in a continuation's current delta. */
+  _continuationConversationMessageIndex?: number;
+  /**
+   * True when the full history for a previous_response_id request is present in the input —
+   * whether the proxy expanded it or the client already sent it. Consumers read this as
+   * "this request is self-contained", never as "the proxy mutated it".
+   */
+  _previousResponseInputExpanded?: boolean;
+  /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */
+  _cursorConversationId?: string;
+  /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
+  _clientThreadId?: string;
+  /** Provider/account/model-bound namespace for process-local raw-reasoning replay. */
+  _reasoningReplayScope?: OcxReasoningReplayScopeRef;
+  /**
+   * Set by bindRouteReasoningReplayScope after a proven serving-identity change, or by
+   * prepareOpaqueBlobRecovery after an authoritative rejection; consumers strip replayed blobs.
+   */
+  _stripReasoningEncryptedContent?: boolean;
+  /**
+   * Optional authenticated tenant/operator namespace for Cursor thread→conversation derivation.
+   * When absent (single-operator local proxy), derivation stays local-scoped.
+   */
+  _cursorIdentityScope?: string;
+  /**
+   * True for helper/shadow/compaction turns that must not append into the main Cursor conversation
+   * derived from the parent thread id.
+   */
+  _cursorIsolateConversation?: boolean;
+  /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
+  _kiroAuthContext?: Pick<KiroOAuthMetadata, "profileArn" | "apiRegion" | "ssoRegion">;
+  /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
+  _providerContinuation?: OcxProviderContinuationState;
+  /** Persisted continuation considered only after the final physical route is known. */
+  _providerContinuationCandidate?: OcxProviderContinuationState;
+  /** Exact process-local route owner attached to newly persisted provider state. */
+  _providerContinuationOwner?: OcxProviderContinuationOwner;
+  /**
+   * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
+   * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
+   * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
+   */
+  _webSearch?: Record<string, unknown>;
+  /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
+  _imageGeneration?: { toolNames: Set<string>; originalTool?: Record<string, unknown> };
+  /**
+   * True when Codex requested structured output (`text.format` = json_schema/json_object). The
+   * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
+   * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output.
+   */
+  _structuredOutput?: boolean;
+  /**
+   * True when the input carried `{type:"compaction_trigger"}` — Codex remote compaction v2 asking
+   * this turn to produce a `{type:"compaction"}` output item. Routed adapters can't natively;
+   * the server runs the model as a summarizer and the bridge emits a synthetic compaction item
+   * (see src/responses/compaction.ts).
+   */
+  _compactionRequest?: boolean;
+  /**
+   * True when the current request newly introduced a stored compaction summary/marker. Historical
+   * markers restored by previous_response_id expansion were already acknowledged and do not reset
+   * provider-private continuation caches again on every later turn.
+   */
+  _contextCompactionBoundary?: boolean;
+}
+
+export interface OcxContext {
+  systemPrompt?: string[];
+  messages: OcxMessage[];
+  tools?: OcxTool[];
+}
+
+export type OcxMessage =
+  | OcxUserMessage
+  | OcxAssistantMessage
+  | OcxDeveloperMessage
+  | OcxToolResultMessage;
+
+export interface OcxUserMessage {
+  role: "user";
+  content: string | OcxContentPart[];
+  timestamp: number;
+}
+
+export interface OcxAssistantMessage {
+  role: "assistant";
+  content: OcxAssistantContentPart[];
+  /** Responses message phase, preserved when replaying translated provider output. */
+  phase?: OcxMessagePhase;
+  model?: string;
+  timestamp: number;
+  /**
+   * Kiro `reasoningContent.redactedContent` for THIS assistant turn — an opaque encrypted blob
+   * Kiro replays to preserve model reasoning across turns. Provider-specific and unrenderable, so
+   * it rides the message rather than a content part: any other adapter simply ignores it.
+   */
+  kiroRedactedReasoning?: string;
+}
+
+export interface OcxDeveloperMessage {
+  role: "developer";
+  content: string | OcxContentPart[];
+  timestamp: number;
+}
+
+export interface OcxToolResultMessage {
+  role: "toolResult";
+  toolCallId: string;
+  toolName: string;
+  /** MCP namespace from the originating tool call, if any. */
+  toolNamespace?: string;
+  /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */
+  content: string | OcxContentPart[];
+  /** True when the Responses result contained opaque encrypted output Kiro cannot translate. */
+  containsEncryptedContent?: boolean;
+  isError: boolean;
+  timestamp: number;
+}
+
+export interface OcxTextContent {
+  type: "text";
+  text: string;
+}
+
+export interface OcxImageContent {
+  type: "image";
+  /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */
+  imageUrl: string;
+  /** Fidelity hint from Codex: "low" | "high" | "auto". */
+  detail?: string;
+}
+
+/** A user/developer message content part: text or an image (vision). */
+export type OcxContentPart = OcxTextContent | OcxImageContent;
+
+export interface OcxThinkingContent {
+  type: "thinking";
+  thinking: string;
+  signature?: string;
+  itemId?: string;
+  /** Raw Anthropic redacted_thinking block payloads to replay verbatim (order preserved). */
+  redacted?: string[];
+}
+
+export interface OcxToolCall {
+  type: "toolCall";
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  customWireName?: string;
+  thoughtSignature?: string;
+  /**
+   * Provider-issued opaque metadata that must survive the whole round trip unchanged
+   * (issue #1735). A signed Gemini part is only valid when its signature comes back on the
+   * SAME part it was issued for, so this travels with the individual tool call rather than
+   * being matched by name/arguments after the fact.
+   */
+  providerMetadata?: OcxProviderOpaqueToolCallMetadata;
+  /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
+  namespace?: string;
+}
+
+/**
+ * Opaque, provider-scoped tool-call metadata. Values are never parsed, merged, re-encoded, or
+ * synthesized — they are carried verbatim or not at all.
+ */
+export interface OcxProviderOpaqueToolCallMetadata {
+  google?: {
+    thoughtSignature?: string;
+  };
+}
+
+export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
+export interface OcxRequestOptions {
+  maxOutputTokens?: number;
+  temperature?: number;
+  topP?: number;
+  stopSequences?: string[];
+  toolChoice?: OcxToolChoice;
+  parallelToolCalls?: boolean;
+  reasoning?: string;
+  hideThinkingSummary?: boolean;
+  serviceTier?: string;
+  /** Final outbound tier action, resolved after the provider/model wire is settled. */
+  tierDecision?: TierDecision;
+  /** Internal B0 observation inputs; adapters combine these with the wire they actually serialize. */
+  tierObservation?: TierObservationContext;
+  presencePenalty?: number;
+  frequencyPenalty?: number;
+  /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */
+  promptCacheKey?: string;
+  /**
+   * Responses `text.format` (json_schema / json_object), preserved for adapters whose
+   * upstream wire has an equivalent. The openai-chat adapter re-nests it as chat
+   * `response_format`, the exact inverse of responseFormatToText in src/chat/inbound.ts.
+   * The native passthrough ignores it (it forwards `_rawBody.text` verbatim) and Kiro
+   * keeps rejecting structured output via `_structuredOutput`.
+   */
+  textFormat?: {
+    type: "json_schema" | "json_object";
+    name?: string;
+    description?: string;
+    schema?: Record<string, unknown>;
+    strict?: boolean;
+  };
+}
+
+export type OcxMessagePhase = "commentary" | "final_answer";
+
+/** Non-secret, process-local owner fence for provider-private continuation state. */
+export interface OcxProviderContinuationOwner {
+  [field: string]: string | number;
+  version: 1;
+  providerName: string;
+  providerDestinationIdentity: string;
+  adapterName: string;
+  modelId: string;
+  credentialIdentity: string;
+}
+
+/**
+ * Provider-private state that must follow a locally expanded `previous_response_id` chain.
+ * Kept out of public Responses output and persisted only in the bounded local continuation cache.
+ */
+export interface OcxProviderContinuationState {
+  /** Proxy-authored owner metadata; stripped before provider adapters receive the state. */
+  __ocxOwner?: OcxProviderContinuationOwner;
+  cursor?: {
+    [field: string]: unknown;
+    conversationId?: string;
+    checkpointUsable?: boolean;
+    /** Opaque process-local Cursor ConversationStateStructure snapshot ref. Never raw protobuf. */
+    checkpointRef?: string;
+  };
+  kiro?: {
+    [field: string]: unknown;
+    conversationId?: string;
+  };
+  [provider: string]: Record<string, unknown> | undefined;
+}
+
+export type AdapterEvent =
+  | { type: "heartbeat" }
+  | { type: "text_delta"; text: string; phase?: OcxMessagePhase }
+  | { type: "thinking_delta"; thinking: string }
+  // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and
+  // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
+  | { type: "thinking_signature"; signature: string }
+  | { type: "redacted_thinking"; data: string }
+  // Kiro reasoning round-trip: the encrypted `redactedContent` blob for the CURRENT assistant turn.
+  // Never rendered — it only rides the reasoning item's envelope so the next request can replay it.
+  | { type: "kiro_redacted_reasoning"; data: string }
+  | { type: "reasoning_raw_delta"; text: string }
+  | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata }
+  | { type: "tool_call_delta"; arguments: string }
+  | { type: "tool_call_end" }
+  /** Internal boundary between a guarded first pass and its one-shot continuation. */
+  | { type: "assistant_boundary" }
+  // Native web-search activity surfaced by the web-search sidecar so Codex renders a "Searched the
+  // web" cell. Emitted as a lifecycle PAIR at real wall-clock moments by src/web-search/loop.ts
+  // (routed adapters never emit these): `begin` right before the sidecar runs so Codex shows the
+  // "Searching the web" spinner, then `end` once it resolves. The bridge maps begin → an
+  // output_item.added(in_progress) and end → the matching output_item.done(completed|failed) under
+  // the SAME output index, so the activity animates instead of flashing completed instantly.
+  | { type: "web_search_call_begin"; id: string }
+  | { type: "web_search_call_end"; id: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[] }
+  | {
+      type: "done";
+      usage?: OcxUsage;
+      stopReason?: string;
+      endTurn?: boolean;
+      providerState?: OcxProviderContinuationState;
+    }
+  | {
+      type: "incomplete";
+      reason: string;
+      message?: string;
+      usage?: OcxUsage;
+      retryable?: boolean;
+      endTurn?: boolean;
+      providerState?: OcxProviderContinuationState;
+    }
+  // `usage` carries best-effort partial consumption when a turn dies before a clean done
+  // (e.g. cursor upstream 502 mid-stream), so failed requests can log real token counts.
+  | {
+      type: "error";
+      message: string;
+      usage?: OcxUsage;
+      /** Authoritative upstream/proxy status when known; avoids message-based classification. */
+      status?: number;
+      /** Responses error type and code when the adapter has a structured provider failure. */
+      errorType?: string;
+      code?: string;
+      retryable?: boolean;
+    };
+
+/**
+ * A web source backing a search answer. Surfaced on the search-end event and rendered by the bridge
+ * as a `url_citation` annotation on the following assistant message (the desktop app's Sources chip
+ * reads these; the TUI ignores annotations, so this is additive).
+ */
+export interface OcxUrlCitation {
+  url: string;
+  title?: string;
+}
+
+/**
+ * Canonical usage convention (devlog/260711_claude_inbound/070):
+ * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes
+ *   (OpenAI Responses convention). Anthropic parse sites normalize into this shape.
+ * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`).
+ * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when
+ *   the provider reports both; reads mirror `cachedInputTokens`.
+ * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top.
+ */
+export interface OcxUsage {
+  inputTokens: number;
+  outputTokens: number;
+  /**
+   * Absolute active-context size after the response. Stateful providers can expose this separately
+   * from their per-attempt usage. Responses serialization derives the input side from
+   * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice.
+   */
+  contextTotalTokens?: number;
+  totalTokens?: number;
+  cachedInputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  reasoningOutputTokens?: number;
+  estimated?: boolean;
+}

package/src/types/tools.ts

@@ -0,0 +1,131 @@
+export interface OcxTool {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  strict?: boolean;
+  /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
+  namespace?: string;
+  /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
+  freeform?: boolean;
+  /** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
+  toolSearch?: boolean;
+  /** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
+  loadedFromToolSearch?: boolean;
+  /** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
+  cursorStructuredEdit?: true;
+  /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
+  webSearch?: boolean;
+  /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
+  imageGeneration?: boolean;
+  /** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
+  videoGeneration?: boolean;
+}
+
+/**
+ * Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
+ * "<namespace>__<name>" so they survive the chat-completions function-tool format;
+ * the proxy maps this back to {namespace, name} on the return trip (Codex routes MCP
+ * calls by an explicit `namespace` field, not by parsing the name).
+ */
+export function namespacedToolName(namespace: string | undefined, name: string): string {
+  return namespace ? `${namespace}__${name}` : name;
+}
+
+export function toolChoiceAliases(tool: Pick<OcxTool, "namespace" | "name">): string[] {
+  const wireName = namespacedToolName(tool.namespace, tool.name);
+  return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];
+}
+
+function sameToolIdentity(
+  left: Pick<OcxTool, "namespace" | "name">,
+  right: Pick<OcxTool, "namespace" | "name">,
+): boolean {
+  return left.namespace === right.namespace && left.name === right.name;
+}
+
+/**
+ * All tools that could be selected by one client-facing name. Bare logical names are included
+ * here because they are a compatibility selector for namespaced tools, while wire and dotted
+ * aliases come from `toolChoiceAliases`. A selector with more than one candidate is invalid.
+ */
+export function toolChoiceCandidates(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  name: string,
+): Pick<OcxTool, "namespace" | "name">[] {
+  if (!tools) return [];
+  const candidates: Pick<OcxTool, "namespace" | "name">[] = [];
+  for (const tool of tools) {
+    if (tool.name !== name && !toolChoiceAliases(tool).includes(name)) continue;
+    if (!candidates.some(candidate => sameToolIdentity(candidate, tool))) candidates.push(tool);
+  }
+  return candidates;
+}
+
+/**
+ * Newer Codex clients can select a tool nested in a namespace by its bare name. Resolve that
+ * shorthand only when the request contains one tool with the logical name, so an ambiguous name
+ * cannot authorize a tool from an unintended namespace.
+ */
+export function toolAllowedByChoice(
+  tool: Pick<OcxTool, "namespace" | "name">,
+  allowedTools: ReadonlySet<string>,
+  tools?: readonly Pick<OcxTool, "namespace" | "name">[],
+): boolean {
+  if (!tools) return toolChoiceAliases(tool).some(name => allowedTools.has(name));
+  for (const name of [...toolChoiceAliases(tool), tool.name]) {
+    if (!allowedTools.has(name)) continue;
+    const candidates = toolChoiceCandidates(tools, name);
+    if (candidates.length === 1 && sameToolIdentity(candidates[0], tool)) return true;
+  }
+  return false;
+}
+
+export function resolveToolChoiceWireName(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined, name: string): string {
+  const candidates = toolChoiceCandidates(tools, name);
+  if (candidates.length === 1) {
+    const match = candidates[0];
+    return namespacedToolName(match.namespace, match.name);
+  }
+  // Keep unknown/ambiguous names unchanged for callers that only serialize a selector. The
+  // catalog-aware predicate rejects them, and parseRequest rejects ambiguous request selectors.
+  return name;
+}
+
+/**
+ * Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
+ * id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
+ * `gpt-oss:120b`/`gpt-oss:20b`. Colon-less ids (e.g. `grok-build-0.1`) still match exactly only.
+ */
+export function modelInList(list: string[] | undefined, modelId: string): boolean {
+  if (!list || list.length === 0) return false;
+  if (list.includes(modelId)) return true;
+  const colon = modelId.indexOf(":");
+  return colon > 0 && list.includes(modelId.slice(0, colon));
+}
+
+export type OcxToolChoice =
+  | "auto"
+  | "none"
+  | "required"
+  | { name: string }
+  | { allowedTools: string[]; mode: "auto" | "required" };
+
+export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is { allowedTools: string[]; mode: "auto" | "required" } {
+  return typeof value === "object" && value !== null && "allowedTools" in value;
+}
+
+/** Compile the request's tool-choice policy into a reusable advertisement/restoration predicate. */
+export function toolChoiceToolPredicate(
+  choice: OcxToolChoice | undefined,
+  tools?: readonly Pick<OcxTool, "namespace" | "name">[],
+): (tool: Pick<OcxTool, "namespace" | "name">) => boolean {
+  if (!choice || choice === "auto" || choice === "required") return () => true;
+  if (choice === "none") return () => false;
+  if (isAllowedToolChoice(choice)) {
+    const allowed = new Set(choice.allowedTools);
+    return tool => toolAllowedByChoice(tool, allowed, tools);
+  }
+  if (!tools) return tool => toolChoiceAliases(tool).includes(choice.name);
+  const candidates = toolChoiceCandidates(tools, choice.name);
+  return tool => candidates.length === 1 && sameToolIdentity(candidates[0], tool);
+}

package/src/types/wire.ts

@@ -0,0 +1,80 @@
+/**
+ * Accepted values for the per-provider upstream HTTP-version pin (#1668). Shared by the
+ * zod load schema, the management write boundary (POST/PATCH), and the fetch runtime, so
+ * a value that one boundary accepts can never be rejected by another.
+ */
+export const UPSTREAM_HTTP_VERSION_VALUES = [
+  "auto",
+  "http1.1",
+  "h1",
+  "http2",
+  "h2",
+] as const;
+
+export type UpstreamHttpVersion = (typeof UPSTREAM_HTTP_VERSION_VALUES)[number];
+
+export const REASONING_SUMMARY_DELIVERY_VALUES = [
+  "sequential",
+  "sequential_cutoff",
+  "concurrent",
+  "concurrent_cutoff",
+] as const;
+
+export type ReasoningSummaryDelivery = typeof REASONING_SUMMARY_DELIVERY_VALUES[number];
+
+/** Trusted runtime ownership for Codex-account credentials. Never persisted per provider. */
+export type CodexAccountMode = "direct" | "pool";
+
+export const OPENAI_PROVIDER_TIER_VERSION = 2 as const;
+
+/**
+ * Wires that a per-model `modelAdapters` override may select.
+ *
+ * Deliberately narrow: provider-specific adapters (cursor, kiro, google, ...) carry
+ * their own credential and base-URL semantics, so exposing them here would widen the
+ * auth boundary rather than pick a wire. Widening this set needs a per-adapter
+ * credential threat model first (#404).
+ */
+export const MODEL_ADAPTER_OVERRIDE_ALLOWED: ReadonlySet<string> = new Set([
+  "openai-chat",
+  "openai-responses",
+]);
+
+/**
+ * Providers whose listed model ids must be driven over the Anthropic wire even when
+ * the provider's configured adapter says otherwise — the upstream only speaks
+ * Anthropic for these models.
+ */
+const ANTHROPIC_WIRE_MODELS: Record<string, ReadonlySet<string>> = {
+  "opencode-go": new Set(["minimax-m2.5", "minimax-m2.7", "minimax-m3"]),
+};
+
+function anthropicWireModelsForProvider(providerName: string): ReadonlySet<string> | undefined {
+  return Object.hasOwn(ANTHROPIC_WIRE_MODELS, providerName)
+    ? ANTHROPIC_WIRE_MODELS[providerName]
+    : undefined;
+}
+
+/** Detached provider-local hard-pin table for pure wire-policy resolution. */
+export function captureWireAdapterHardPins(providerName: string): Readonly<Record<string, string>> {
+  const models = anthropicWireModelsForProvider(providerName);
+  if (!models) return Object.freeze({});
+  return Object.freeze(Object.fromEntries([...models].map(modelId => [modelId, "anthropic"])));
+}
+
+/**
+ * True when the upstream speaks exactly one wire for this model, so a configured
+ * override must not apply.
+ *
+ * Deliberately independent of the provider's current adapter: the wire resolver runs
+ * more than once per request, and a check phrased as "pin differs from the current
+ * adapter" would pass on the first pass and then let the override win on the second.
+ */
+export function isWirePinnedModel(providerName: string, modelId: string): boolean {
+  return anthropicWireModelsForProvider(providerName)?.has(modelId) ?? false;
+}
+
+/** The wire a pinned model must use, or undefined when the model is not pinned. */
+export function pinnedWireAdapter(providerName: string, modelId: string): string | undefined {
+  return isWirePinnedModel(providerName, modelId) ? "anthropic" : undefined;
+}