@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/providers/resolved-model-policy.ts

@@ -0,0 +1,406 @@
+import type { ModelCapabilities, OcxProviderConfig } from "../types";
+import { MODEL_ADAPTER_OVERRIDE_ALLOWED, pinnedWireAdapter } from "../types";
+import { isCanonicalOpenAiForwardProvider } from "./openai-tiers";
+import { resolveProviderAuthTransport } from "./fastwire";
+import { registryEntrySupportsLiveModelDiscovery } from "./static-model-discovery";
+import type { InboundWire, ProviderRegistryEntry, ResponsesTerminalRepairPolicy } from "./registry/types";
+import {
+  anthropicFamilyContextWindow,
+  detachedClone,
+  legacyModelValue,
+  legacyModelSource,
+  mapFill,
+  nestedMapFill,
+  positiveCapMap,
+  recursivelyFreeze,
+  resolvedBaseUrl,
+  sameStringArray,
+  scalar,
+  stableUnion,
+  staticHeaders,
+  wireDefault,
+  type StaticPolicySource,
+} from "./resolved-model-policy-merge";
+export type { StaticPolicySource } from "./resolved-model-policy-merge";
+export type StaticProviderPolicyField =
+  | "adapter" | "baseUrl" | "apiKeyTransport" | "headers" | "authMode" | "codexAccountMode"
+  | "responsesPath" | "chatCompletionsPath" | "keyOptional" | "freeTier" | "modelSuffixBracketStrip"
+  | "defaultModel" | "models" | "liveModels" | "contextWindow" | "modelContextWindows"
+  | "modelDisplayNames" | "modelInputModalities" | "modelMaxInputTokens" | "defaultMaxOutputTokens"
+  | "modelMaxOutputTokens" | "reasoningEfforts" | "modelReasoningEfforts" | "modelReasoningEffortsAuthoritative"
+  | "modelDefaultReasoningEfforts" | "reasoningEffortMap" | "modelReasoningEffortMap"
+  | "reasoningWireFormat" | "noVisionModels" | "noReasoningModels" | "noTemperatureModels"
+  | "noTopPModels" | "noPenaltyModels" | "noJsonSchemaModels" | "parallelToolCalls"
+  | "promptCacheKey" | "chatServiceTier" | "openaiChatEofTolerance" | "statelessResponses"
+  | "requiresAdjacentResponsesToolResults" | "requiresPairedResponsesToolResults" | "annotateEmptyToolOutputs"
+  | "fastWire" | "supportsServiceTier" | "modelSupportsServiceTier" | "supportsOpenAiWebSearchToolFields"
+  | "supportsResponsesCustomTools" | "preserveResponsesReasoningContent" | "dropResponsesReasoningItems"
+  | "modelSupportsReasoningSummaries"
+  | "supportsVerbosity" | "modelSupportsVerbosity" | "responsesItemIdRepair" | "autoToolChoiceOnlyModels"
+  | "preserveReasoningContentModels" | "requiresReasoningPlaceholderModels" | "reasoningSplitModels"
+  | "reasoningDetailsModels" | "thinkingToggleModels" | "thinkingBudgetModels" | "showThinkingSummary"
+  | "escapeBuiltinToolNames" | "googleMode" | "project" | "location" | "modelCapabilities"
+  | "modelAutoCompactTokenLimits" | "modelSuppressSyntheticMax" | "modelReasoningSummaryDelivery"
+  | "codexToolMode" | "modelAdapters";
+type StaticProviderPolicyShape = Pick<OcxProviderConfig, StaticProviderPolicyField>;
+export type ResolvedProviderStaticPolicy = Readonly<Partial<StaticProviderPolicyShape>> & Readonly<{
+  adapter: string;
+  baseUrl: string;
+}>;
+export interface ResolvedPerModelStaticPolicy {
+  readonly adapter: string;
+  readonly contextWindow?: number;
+  readonly inputModalities?: readonly string[];
+  readonly maxInputTokens?: number;
+  readonly maxOutputTokens?: number;
+  readonly reasoningEfforts?: readonly string[];
+  readonly defaultReasoningEffort?: string;
+  readonly supportsReasoningSummaries?: boolean;
+  readonly supportsVerbosity?: boolean;
+  readonly supportsServiceTier?: boolean;
+  readonly fastTierDescription?: string;
+  readonly directReasoningEffort?: boolean;
+  readonly responsesUpstreamStreaming?: boolean;
+  readonly responsesTerminalRepair?: Readonly<ResponsesTerminalRepairPolicy>;
+}
+export interface ResolvedModelPolicy {
+  readonly version: 1;
+  readonly providerName: string;
+  readonly modelId: string;
+  readonly transportMatchedRegistry: boolean;
+  readonly effectiveAlias?: string | null;
+  readonly provider: ResolvedProviderStaticPolicy;
+  readonly model: Readonly<ResolvedPerModelStaticPolicy>;
+  readonly provenance: Readonly<{
+    alias: StaticPolicySource;
+    provider: Readonly<Partial<Record<StaticProviderPolicyField, StaticPolicySource>>>;
+    model: Readonly<Partial<Record<keyof ResolvedPerModelStaticPolicy, StaticPolicySource>>>;
+  }>;
+}
+export interface ResolveModelPolicyInput {
+  readonly providerName: string;
+  /** Final wire identity after resolveModelAlias and resolveOpenAiVirtualModel; public selection stays diagnostic-only. */
+  readonly modelId: string;
+  readonly provider: Readonly<OcxProviderConfig>;
+  readonly registryEntry?: Readonly<ProviderRegistryEntry>;
+  readonly transportMatchedRegistry: boolean;
+  readonly inboundWire?: InboundWire;
+  /** Exact post-rewrite model capability declaration captured by the caller. */
+  readonly modelCapabilities?: Readonly<ModelCapabilities>;
+  /** Credential-free live admission result: key only after a usable override, otherwise the registry mode. */
+  readonly effectiveAuth?: Readonly<{ authMode: NonNullable<OcxProviderConfig["authMode"]> }>;
+  /** Capture-time collision-aware alias decision. Omit to use provider then registry fallback. */
+  readonly effectiveAlias?: string | null;
+  readonly effectiveAliasSource?: Exclude<StaticPolicySource, "hard-pin" | "provider-default">;
+}
+export interface ObservedModelLimits {
+  readonly contextWindow?: number;
+  readonly maxInputTokens?: number;
+  readonly maxOutputTokens?: number;
+}
+/** Call-local projection: observed values stay outside ResolvedModelPolicy and may only narrow caps. */
+export function clampObservedModelLimits(
+  policy: Readonly<Pick<ResolvedPerModelStaticPolicy, "contextWindow" | "maxInputTokens" | "maxOutputTokens">>,
+  observed: Readonly<ObservedModelLimits>,
+): Readonly<ObservedModelLimits> {
+  const clamp = (staticCap: number | undefined, observedValue: number | undefined): number | undefined => {
+    if (observedValue === undefined) return staticCap;
+    return staticCap === undefined ? observedValue : Math.min(staticCap, observedValue);
+  };
+  const contextWindow = clamp(policy.contextWindow, observed.contextWindow);
+  const clampedMaxInputTokens = clamp(policy.maxInputTokens, observed.maxInputTokens);
+  const maxInputTokens = clampedMaxInputTokens !== undefined && contextWindow !== undefined
+    ? Math.min(clampedMaxInputTokens, contextWindow)
+    : clampedMaxInputTokens;
+  const maxOutputTokens = clamp(policy.maxOutputTokens, observed.maxOutputTokens);
+  return Object.freeze({
+    ...(contextWindow !== undefined ? { contextWindow } : {}),
+    ...(maxInputTokens !== undefined ? { maxInputTokens } : {}),
+    ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+  });
+}
+export function resolveModelPolicy(input: ResolveModelPolicyInput): ResolvedModelPolicy {
+  const entry = input.transportMatchedRegistry ? input.registryEntry : undefined;
+  const provider = input.provider;
+  const providerPolicy: Partial<StaticProviderPolicyShape> = {};
+  const providerProvenance: Partial<Record<StaticProviderPolicyField, StaticPolicySource>> = {};
+  const [baseUrl, baseUrlSource] = resolvedBaseUrl(entry, provider);
+  const put = <K extends StaticProviderPolicyField>(key: K, value: StaticProviderPolicyShape[K] | undefined, source: StaticPolicySource): void => {
+    if (value !== undefined) providerPolicy[key] = detachedClone(value) as never;
+    providerProvenance[key] = source;
+  };
+  const putScalar = <K extends StaticProviderPolicyField>(key: K, registryValue: StaticProviderPolicyShape[K] | undefined): void => {
+    const [value, source] = scalar(provider[key], registryValue);
+    put(key, value, source);
+  };
+  const putUnion = (key: StaticProviderPolicyField, registryValue: readonly string[] | undefined): void => {
+    const [value, source] = stableUnion(registryValue, provider[key] as string[] | undefined);
+    put(key, value as never, source);
+  };
+  const putMergedMap = <K extends StaticProviderPolicyField, T>(
+    key: K,
+    registryValue: Readonly<Record<string, T>> | undefined,
+    operatorValue: Readonly<Record<string, T>> | undefined,
+  ): void => {
+    const [value, source] = mapFill(registryValue, operatorValue);
+    put(key, value as StaticProviderPolicyShape[K], source);
+  };
+  put("adapter", entry?.adapter ?? provider.adapter, entry ? "registry" : "operator");
+  put("baseUrl", baseUrl, baseUrlSource);
+  putScalar("apiKeyTransport", entry?.apiKeyTransport);
+  const [headers, headersSource] = staticHeaders(entry?.staticHeaders, provider.headers);
+  put("headers", headers, headersSource);
+  const resolvedAuthMode = input.effectiveAuth?.authMode
+    ?? (entry?.authKind === "forward" || entry?.authKind === "oauth"
+      ? entry.authKind
+      : provider.authMode === "forward" ? undefined : provider.authMode ?? entry?.authKind);
+  put("authMode", resolvedAuthMode, input.effectiveAuth
+    ? "captured-auth"
+    : entry?.authKind === "forward" || entry?.authKind === "oauth" ? "registry"
+    : provider.authMode !== undefined ? "operator" : entry ? "registry" : "unknown");
+  putScalar("codexAccountMode", entry?.codexAccountMode);
+  const keyAuthDefaults = entry?.allowKeyAuthOverride === true
+    && resolvedAuthMode === "key"
+    && ["authorization_bearer", "x_api_key"].includes(resolveProviderAuthTransport(
+      provider.adapter,
+      resolvedAuthMode,
+      provider.apiKeyTransport,
+    ))
+    ? entry.keyAuthServiceTier
+    : undefined;
+  for (const key of [
+    "responsesPath", "chatCompletionsPath", "keyOptional", "freeTier", "modelSuffixBracketStrip",
+    "defaultModel", "models", "liveModels", "contextWindow", "defaultMaxOutputTokens",
+    "reasoningWireFormat", "parallelToolCalls", "promptCacheKey",
+    "openaiChatEofTolerance", "statelessResponses",
+    "requiresAdjacentResponsesToolResults", "requiresPairedResponsesToolResults",
+    "annotateEmptyToolOutputs", "fastWire", "supportsServiceTier",
+    "supportsOpenAiWebSearchToolFields", "supportsResponsesCustomTools",
+    "preserveResponsesReasoningContent", "dropResponsesReasoningItems",
+    "supportsVerbosity", "responsesItemIdRepair",
+    "showThinkingSummary", "escapeBuiltinToolNames", "googleMode", "project", "location",
+  ] as const) putScalar(key, entry?.[key] as StaticProviderPolicyShape[typeof key] | undefined);
+  const legacyClinePassLadder = entry !== undefined && input.providerName === "cline-pass"
+    && provider.reasoningWireFormat === "gateway-object"
+    && sameStringArray(provider.reasoningEfforts, ["low"]);
+  put("reasoningEfforts", legacyClinePassLadder ? entry?.reasoningEfforts : provider.reasoningEfforts ?? entry?.reasoningEfforts,
+    legacyClinePassLadder || provider.reasoningEfforts === undefined ? entry?.reasoningEfforts ? "registry" : "unknown" : "operator");
+  put("chatServiceTier", provider.chatServiceTier ?? keyAuthDefaults?.chatServiceTier ?? entry?.chatServiceTier,
+    provider.chatServiceTier !== undefined ? "operator" : keyAuthDefaults?.chatServiceTier !== undefined ? "registry" : entry?.chatServiceTier !== undefined ? "registry" : "unknown");
+  put("supportsServiceTier", provider.supportsServiceTier ?? keyAuthDefaults?.supportsServiceTier ?? entry?.supportsServiceTier,
+    provider.supportsServiceTier !== undefined ? "operator" : keyAuthDefaults?.supportsServiceTier !== undefined ? "registry" : entry?.supportsServiceTier !== undefined ? "registry" : "unknown");
+  if (entry && !registryEntrySupportsLiveModelDiscovery(entry)) put("liveModels", false, "registry");
+  putMergedMap("modelDisplayNames", entry?.modelDisplayNames, provider.modelDisplayNames);
+  putMergedMap("modelInputModalities", entry?.modelInputModalities, provider.modelInputModalities);
+  putMergedMap("modelMaxOutputTokens", entry?.modelMaxOutputTokens, provider.modelMaxOutputTokens);
+  putMergedMap("modelReasoningEfforts", entry?.modelReasoningEfforts, provider.modelReasoningEfforts);
+  // Operator-only: no registry entry declares it, and it decides whether the map above is the
+  // wire contract or only the catalog's. A policy reader that omitted it would report the same
+  // effective ladder for two providers that send different efforts.
+  put("modelReasoningEffortsAuthoritative", provider.modelReasoningEffortsAuthoritative,
+    provider.modelReasoningEffortsAuthoritative !== undefined ? "operator" : "unknown");
+  putMergedMap("modelDefaultReasoningEfforts", entry?.modelDefaultReasoningEfforts, provider.modelDefaultReasoningEfforts);
+  const registryServiceTier = !entry?.modelServiceTierCapabilityBaseUrlGuard
+    || entry.modelServiceTierCapabilityBaseUrlGuard(provider.baseUrl)
+    ? entry?.modelSupportsServiceTier
+    : undefined;
+  const registryServiceTierDefaults = registryServiceTier || keyAuthDefaults?.modelSupportsServiceTier
+    ? { ...(registryServiceTier ?? {}), ...(keyAuthDefaults?.modelSupportsServiceTier ?? {}) }
+    : undefined;
+  putMergedMap("modelSupportsServiceTier", registryServiceTierDefaults, provider.modelSupportsServiceTier);
+  putMergedMap("modelSupportsReasoningSummaries", entry?.modelSupportsReasoningSummaries, provider.modelSupportsReasoningSummaries);
+  putMergedMap("modelSupportsVerbosity", entry?.modelSupportsVerbosity, provider.modelSupportsVerbosity);
+  for (const key of [
+    "modelCapabilities", "modelAutoCompactTokenLimits", "modelSuppressSyntheticMax",
+    "modelReasoningSummaryDelivery", "codexToolMode", "modelAdapters",
+  ] as const) putScalar(key, undefined);
+  for (const key of ["modelContextWindows", "modelMaxInputTokens"] as const) {
+    const [value, source] = input.providerName === "openai-apikey"
+      ? positiveCapMap(entry?.[key], provider[key])
+      : mapFill(entry?.[key], provider[key]);
+    put(key, value, source);
+  }
+  const [effortMap, effortMapSource] = mapFill(entry?.reasoningEffortMap, provider.reasoningEffortMap);
+  put("reasoningEffortMap", effortMap, effortMapSource);
+  const [modelEffortMap, modelEffortMapSource] = nestedMapFill(entry?.modelReasoningEffortMap, provider.modelReasoningEffortMap);
+  put("modelReasoningEffortMap", modelEffortMap, modelEffortMapSource);
+  for (const key of [
+    "noVisionModels", "noReasoningModels", "noTemperatureModels", "noTopPModels",
+    "noPenaltyModels", "noJsonSchemaModels", "autoToolChoiceOnlyModels",
+    "preserveReasoningContentModels", "requiresReasoningPlaceholderModels",
+    "reasoningSplitModels", "reasoningDetailsModels", "thinkingToggleModels", "thinkingBudgetModels",
+  ] as const) putUnion(key, entry?.[key]);
+  for (const directModel of entry?.directReasoningEffortModels ?? []) {
+    const staleBudget = [directModel, ...(entry?.thinkingBudgetModels ?? [])];
+    const routedStaleBudget = [...(entry?.thinkingBudgetModels ?? []), directModel];
+    if (sameStringArray(provider.thinkingBudgetModels, staleBudget)
+      || sameStringArray(provider.thinkingBudgetModels, routedStaleBudget)) {
+      providerPolicy.thinkingBudgetModels = [...(entry?.thinkingBudgetModels ?? [])];
+      providerProvenance.thinkingBudgetModels = "registry";
+    }
+    const explicitEfforts = Object.entries(provider.modelReasoningEfforts ?? {})
+      .filter(([key]) => key.toLowerCase() === directModel.toLowerCase());
+    if (explicitEfforts.length > 0) {
+      for (const key of Object.keys(providerPolicy.modelReasoningEfforts ?? {})) {
+        if (key.toLowerCase() === directModel.toLowerCase()) delete providerPolicy.modelReasoningEfforts![key];
+      }
+      for (const [key, value] of explicitEfforts) (providerPolicy.modelReasoningEfforts ??= {})[key] = [...value];
+    } else if (entry?.modelReasoningEfforts?.[directModel] !== undefined) {
+      (providerPolicy.modelReasoningEfforts ??= {})[directModel] = [...entry.modelReasoningEfforts[directModel]!];
+    }
+    const explicitDefault = Object.entries(provider.modelDefaultReasoningEfforts ?? {})
+      .filter(([key]) => key.toLowerCase() === directModel.toLowerCase());
+    if (explicitDefault.length > 0) {
+      for (const key of Object.keys(providerPolicy.modelDefaultReasoningEfforts ?? {})) {
+        if (key.toLowerCase() === directModel.toLowerCase()) delete providerPolicy.modelDefaultReasoningEfforts![key];
+      }
+      for (const [key, value] of explicitDefault) (providerPolicy.modelDefaultReasoningEfforts ??= {})[key] = value;
+    } else if (entry?.modelDefaultReasoningEfforts?.[directModel] !== undefined) {
+      (providerPolicy.modelDefaultReasoningEfforts ??= {})[directModel] = entry.modelDefaultReasoningEfforts[directModel]!;
+    }
+    const explicitMap = Object.entries(provider.modelReasoningEffortMap ?? {})
+      .filter(([key]) => key.toLowerCase() === directModel.toLowerCase());
+    for (const key of Object.keys(providerPolicy.modelReasoningEffortMap ?? {})) {
+      if (key.toLowerCase() === directModel.toLowerCase()) delete providerPolicy.modelReasoningEffortMap![key];
+    }
+    if (explicitMap.length > 0) {
+      for (const [key, value] of explicitMap) (providerPolicy.modelReasoningEffortMap ??= {})[key] = { ...value };
+    } else {
+      (providerPolicy.modelReasoningEffortMap ??= {})[directModel] = {};
+    }
+  }
+  const modelValue = <T>(record: Readonly<Record<string, T>> | undefined): T | undefined =>
+    legacyModelValue(record, input.modelId);
+  const modelSource = <T>(operator: Readonly<Record<string, T>> | undefined, registry: Readonly<Record<string, T>> | undefined): StaticPolicySource =>
+    legacyModelSource(operator, registry, input.modelId);
+  const modelOrProviderSource = <T>(
+    operatorMap: Readonly<Record<string, T>> | undefined, registryMap: Readonly<Record<string, T>> | undefined,
+    operatorDefault: T | undefined, registryDefault: T | undefined,
+  ): StaticPolicySource => {
+    const exact = modelSource(operatorMap, registryMap);
+    return exact !== "unknown" ? exact : operatorDefault !== undefined ? "operator" : registryDefault !== undefined ? "registry" : "unknown";
+  };
+  const configuredAdapter = provider.modelAdapters?.[input.modelId];
+  const pin = pinnedWireAdapter(input.providerName, input.modelId);
+  const normalizedModelId = input.modelId.trim().toLowerCase();
+  const registryWire = wireDefault(entry?.modelWireDefaults?.[normalizedModelId], provider, entry,
+    input.inboundWire ?? "responses", resolvedAuthMode);
+  const explicitWire = configuredAdapter && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(configuredAdapter)
+    ? configuredAdapter
+    : undefined;
+  const providerAdapter = providerPolicy.adapter ?? provider.adapter;
+  const effectiveProviderForWire = resolvedAuthMode === provider.authMode
+    ? provider
+    : { ...provider, authMode: resolvedAuthMode };
+  const canonicalForward = isCanonicalOpenAiForwardProvider(effectiveProviderForWire);
+  const adapter = pin
+    ?? (!canonicalForward ? explicitWire ?? registryWire : undefined)
+    ?? providerAdapter;
+  const adapterSource: StaticPolicySource = pin
+    ? "hard-pin"
+    : explicitWire && !canonicalForward
+      ? "operator"
+      : registryWire && !canonicalForward
+        ? "registry"
+        : "provider-default";
+  const declaredModalities = input.modelCapabilities?.inputModalities;
+  const capabilityModalities = Array.isArray(declaredModalities) && declaredModalities.length > 0
+    ? [...declaredModalities]
+    : undefined;
+  const exactContextWindow = modelValue(providerPolicy.modelContextWindows);
+  const familyContextWindow = providerPolicy.adapter === "anthropic"
+    ? anthropicFamilyContextWindow(providerPolicy.modelContextWindows, input.modelId)
+    : undefined;
+  const modelContextWindow = exactContextWindow ?? familyContextWindow ?? providerPolicy.contextWindow;
+  const exactMaxInputTokens = modelValue(providerPolicy.modelMaxInputTokens);
+  const modelMaxInputTokens = exactMaxInputTokens !== undefined && modelContextWindow !== undefined
+    ? Math.min(exactMaxInputTokens, modelContextWindow)
+    : exactMaxInputTokens;
+  const exactMaxOutputTokens = modelValue(providerPolicy.modelMaxOutputTokens);
+  const modelMaxOutputTokens = exactMaxOutputTokens ?? providerPolicy.defaultMaxOutputTokens;
+  const modelReasoningEfforts = modelValue(providerPolicy.modelReasoningEfforts) ?? providerPolicy.reasoningEfforts;
+  const modelSupportsReasoningSummaries = modelValue(providerPolicy.modelSupportsReasoningSummaries)
+    ?? (modelValue(providerPolicy.modelReasoningSummaryDelivery) !== undefined ? true : undefined);
+  const modelSupportsVerbosity = modelValue(providerPolicy.modelSupportsVerbosity) ?? providerPolicy.supportsVerbosity;
+  const modelSupportsServiceTier = modelValue(providerPolicy.modelSupportsServiceTier) ?? providerPolicy.supportsServiceTier;
+  const model: ResolvedPerModelStaticPolicy = {
+    adapter,
+    ...(modelContextWindow !== undefined ? { contextWindow: modelContextWindow } : {}),
+    ...(capabilityModalities ?? modelValue(providerPolicy.modelInputModalities) !== undefined
+      ? { inputModalities: capabilityModalities ?? modelValue(providerPolicy.modelInputModalities) }
+      : {}),
+    ...(modelMaxInputTokens !== undefined ? { maxInputTokens: modelMaxInputTokens } : {}),
+    ...(modelMaxOutputTokens !== undefined ? { maxOutputTokens: modelMaxOutputTokens } : {}),
+    ...(modelReasoningEfforts !== undefined ? { reasoningEfforts: modelReasoningEfforts } : {}),
+    ...(modelValue(providerPolicy.modelDefaultReasoningEfforts) !== undefined ? { defaultReasoningEffort: modelValue(providerPolicy.modelDefaultReasoningEfforts) } : {}),
+    ...(modelSupportsReasoningSummaries !== undefined ? { supportsReasoningSummaries: modelSupportsReasoningSummaries } : {}),
+    ...(modelSupportsVerbosity !== undefined ? { supportsVerbosity: modelSupportsVerbosity } : {}),
+    ...(modelSupportsServiceTier !== undefined ? { supportsServiceTier: modelSupportsServiceTier } : {}),
+    ...(modelSupportsServiceTier === true && entry?.fastTierDescription !== undefined
+      ? { fastTierDescription: entry.fastTierDescription }
+      : {}),
+    ...(entry?.directReasoningEffortModels?.includes(input.modelId) ? { directReasoningEffort: true } : {}),
+    ...(entry?.modelResponsesUpstreamStreaming?.[normalizedModelId] !== undefined
+      ? { responsesUpstreamStreaming: entry.modelResponsesUpstreamStreaming[normalizedModelId] }
+      : {}),
+    ...(entry?.modelResponsesTerminalRepair?.[normalizedModelId] !== undefined
+      ? { responsesTerminalRepair: entry.modelResponsesTerminalRepair[normalizedModelId] }
+      : {}),
+  };
+  const modelProvenance: Partial<Record<keyof ResolvedPerModelStaticPolicy, StaticPolicySource>> = {
+    adapter: adapterSource,
+  };
+  modelProvenance.contextWindow = modelOrProviderSource(provider.modelContextWindows, entry?.modelContextWindows, provider.contextWindow, entry?.contextWindow);
+  if (modelProvenance.contextWindow === "unknown" && familyContextWindow !== undefined) {
+    modelProvenance.contextWindow = anthropicFamilyContextWindow(provider.modelContextWindows, input.modelId) !== undefined
+      ? "operator"
+      : "registry";
+  }
+  modelProvenance.inputModalities = capabilityModalities
+    ? "operator-capability"
+    : modelSource(provider.modelInputModalities, entry?.modelInputModalities);
+  modelProvenance.maxInputTokens = modelSource(provider.modelMaxInputTokens, entry?.modelMaxInputTokens);
+  modelProvenance.maxOutputTokens = modelOrProviderSource(
+    provider.modelMaxOutputTokens,
+    entry?.modelMaxOutputTokens,
+    provider.defaultMaxOutputTokens,
+    entry?.defaultMaxOutputTokens,
+  );
+  modelProvenance.reasoningEfforts = modelOrProviderSource(provider.modelReasoningEfforts, entry?.modelReasoningEfforts, provider.reasoningEfforts, entry?.reasoningEfforts);
+  modelProvenance.defaultReasoningEffort = modelSource(
+    provider.modelDefaultReasoningEfforts,
+    entry?.modelDefaultReasoningEfforts,
+  );
+  modelProvenance.supportsReasoningSummaries = modelSource(provider.modelSupportsReasoningSummaries, entry?.modelSupportsReasoningSummaries);
+  if (modelProvenance.supportsReasoningSummaries === "unknown" && modelValue(provider.modelReasoningSummaryDelivery) !== undefined) {
+    modelProvenance.supportsReasoningSummaries = "operator";
+  }
+  modelProvenance.supportsVerbosity = modelOrProviderSource(provider.modelSupportsVerbosity, entry?.modelSupportsVerbosity, provider.supportsVerbosity, entry?.supportsVerbosity);
+  const exactServiceTierSource = modelSource(provider.modelSupportsServiceTier, registryServiceTierDefaults);
+  modelProvenance.supportsServiceTier = exactServiceTierSource !== "unknown" ? exactServiceTierSource
+    : providerProvenance.supportsServiceTier ?? "unknown";
+  modelProvenance.responsesUpstreamStreaming = model.responsesUpstreamStreaming === undefined ? "unknown" : "registry";
+  modelProvenance.responsesTerminalRepair = model.responsesTerminalRepair === undefined ? "unknown" : "registry";
+  modelProvenance.fastTierDescription = model.fastTierDescription === undefined ? "unknown" : "registry";
+  modelProvenance.directReasoningEffort = model.directReasoningEffort === undefined ? "unknown" : "registry";
+  const alias = input.effectiveAlias !== undefined
+    ? input.effectiveAlias
+    : provider.alias !== undefined
+      ? provider.alias
+      : entry?.alias;
+  const aliasSource: StaticPolicySource = input.effectiveAlias !== undefined
+    ? input.effectiveAliasSource ?? "operator"
+    : provider.alias !== undefined
+      ? "operator"
+    : entry?.alias !== undefined ? "registry" : "unknown";
+  return recursivelyFreeze(detachedClone({
+    version: 1 as const,
+    providerName: input.providerName,
+    modelId: input.modelId,
+    transportMatchedRegistry: entry !== undefined,
+    ...(alias !== undefined ? { effectiveAlias: alias } : {}),
+    provider: providerPolicy as ResolvedProviderStaticPolicy,
+    model,
+    provenance: { alias: aliasSource, provider: providerProvenance, model: modelProvenance },
+  }));
+}

package/src/providers/stale-vision-classification-migration.ts

@@ -0,0 +1,137 @@
+/**
+ * Repair vision classifications a saved config inherited from a stale registry seed.
+ *
+ * `enrichProviderFromRegistry` is fill-only and asymmetric, which is right for a hand-tuned
+ * value but freezes a wrong one:
+ *
+ * - `noVisionModels` is filled ALL-OR-NOTHING (`if (!prov.noVisionModels && seed.noVisionModels)`),
+ *   so a config saved while the list was current keeps that list forever.
+ * - `modelInputModalities` is filled per-key BENEATH the saved value, so a saved `["text"]` for
+ *   one id survives every later registry correction.
+ *
+ * Correcting the registry therefore fixes new installs only. This projection is the other half.
+ * It repairs the two saved values a stale seed left behind, in both states that reach a running
+ * process:
+ *
+ * - the full pair: modalities still exactly the stale declaration, and the id in the list. Both
+ *   are rewritten.
+ * - the half-repaired row: modalities already corrected but the id still in the list. The
+ *   sidecar predicate reads `noVisionModels` BEFORE the modality list, so that row keeps
+ *   stripping images until the name goes as well; this projection removes it and leaves the
+ *   modalities untouched.
+ *
+ * The paired modalities value is the guard in both states, which is also why it has to be
+ * readable: a name in the list with no modality declaration beside it is ambiguous — either a
+ * half-finished repair or an entry the operator added on purpose — and this projection does not
+ * guess which. It leaves that row alone.
+ *
+ * Identity is the same rule enrichment uses, read from the same helper: the registry must still
+ * own the row (`providerMatchesRegistryTransport`, the check `enrichProviderFromRegistry` makes
+ * before it writes registry metadata) and the row must still be on the entry's adapter.
+ * `opencode-go` is an existing key preset without `preserveCustomDestination`, so the id alone
+ * claims a row — exactly as it does for enrichment — while an entry that opts into destination
+ * preservation narrows this projection for free.
+ *
+ * Nothing here writes `modelCapabilities`. That is the dedicated per-model axis, it outranks
+ * every source this file touches, and it is where a deliberate text-only override belongs
+ * (`ocx provider edit <provider> --model <id> --text-only` writes it).
+ *
+ * Scope is deliberately one entry. The Go gateway's `deepseek-v4.1-flash` was declared text-only
+ * from jawcode metadata and was measured natively multimodal on 2026-09-19 (see the note at that
+ * entry in `registry/entries-core.ts`). Its sibling `deepseek-v4-flash` still rejects images
+ * upstream, and the sibling Zen tiers (`opencode-zen`, `opencode-free`) could not be probed at
+ * all — an unverified tier is not evidence, so neither is touched here.
+ */
+import { PROVIDER_REGISTRY, providerMatchesRegistryTransport } from "./registry";
+import type { OcxConfig } from "../types";
+
+export interface StaleVisionClassification {
+  /** Registry provider id whose saved rows may carry the wrong classification. */
+  provider: string;
+  model: string;
+  /** The stale saved modalities this migration is allowed to replace, and nothing else. */
+  fromModalities: string[];
+  toModalities: string[];
+}
+
+export interface StaleVisionClassificationProjection {
+  config: OcxConfig;
+  changed: boolean;
+  warnings: string[];
+}
+
+export const STALE_VISION_CLASSIFICATIONS: readonly StaleVisionClassification[] = [
+  {
+    provider: "opencode-go",
+    model: "deepseek-v4.1-flash",
+    fromModalities: ["text"],
+    toModalities: ["text", "image"],
+  },
+];
+
+/**
+ * Whether the registry still owns the row whose saved values would be rewritten.
+ *
+ * `providerMatchesRegistryTransport` is the rule enrichment applies, so this projection and the
+ * fill that put the stale values there answer identity the same way. Adapter equality stays as
+ * an additional tightening: a row moved onto another wire is not the row the seed described,
+ * however the registry entry is pinned.
+ */
+function providerStillMatchesRegistry(id: string, prov: OcxConfig["providers"][string]): boolean {
+  const entry = PROVIDER_REGISTRY.find(row => row.id === id);
+  if (entry === undefined || entry.adapter !== prov.adapter) return false;
+  return providerMatchesRegistryTransport(id, prov);
+}
+
+function sameModalities(current: unknown, expected: readonly string[]): boolean {
+  return Array.isArray(current)
+    && current.length === expected.length
+    && current.every((value, index) => value === expected[index]);
+}
+
+/** Pure projection. The caller decides whether to persist. */
+export function projectStaleVisionClassifications(
+  config: OcxConfig,
+  entries: readonly StaleVisionClassification[] = STALE_VISION_CLASSIFICATIONS,
+): StaleVisionClassificationProjection {
+  const warnings: string[] = [];
+  const repaired = new Map<string, string[]>();
+
+  for (const entry of entries) {
+    const prov = config.providers?.[entry.provider];
+    if (!prov) continue;
+    if (!providerStillMatchesRegistry(entry.provider, prov)) continue;
+    const modalities = prov.modelInputModalities;
+    if (!modalities) continue;
+    // The paired modalities value is the guard, and it decides which of the two states above this
+    // row is in. Anything else is a declaration this file does not own.
+    const saved = modalities[entry.model];
+    const stale = sameModalities(saved, entry.fromModalities);
+    const alreadyMigrated = sameModalities(saved, entry.toModalities);
+    if (!stale && !alreadyMigrated) continue;
+    const visionList = Array.isArray(prov.noVisionModels) ? prov.noVisionModels : undefined;
+    const listed = visionList !== undefined && visionList.includes(entry.model);
+    // Half-repaired rows have nothing left to do once the name is gone; the full pair is rewritten
+    // whether or not the name was ever listed, because `derive.ts` fills the two fields
+    // independently and a per-key modality fill can land without the all-or-nothing list.
+    if (!stale && !listed) continue;
+    if (stale) modalities[entry.model] = [...entry.toModalities];
+    if (visionList !== undefined && listed) {
+      prov.noVisionModels = visionList.filter(id => id !== entry.model);
+    }
+    const repairedList = repaired.get(entry.provider) ?? [];
+    repairedList.push(stale
+      ? `${entry.model} ${entry.fromModalities.join("+")} -> ${entry.toModalities.join("+")}`
+      : `${entry.model} dropped from noVisionModels (modalities already ${entry.toModalities.join("+")})`);
+    repaired.set(entry.provider, repairedList);
+  }
+
+  for (const [provider, list] of repaired) {
+    warnings.push(
+      `repaired the stale registry vision seed for ${list.length} model(s) on "${provider}": `
+      + `${list.join(", ")}.`,
+    );
+  }
+
+  return { config, changed: repaired.size > 0, warnings };
+}

package/src/responses/apply-patch-envelope.ts

@@ -34,18 +34,6 @@ function stripMarkdownCodeFence(text: string, toolName: string): string {
   return match ? match[1] : text;
 }
 
-/**
- * The single-field wrappers `unwrapFreeformToolInput` accepts for one tool name, besides the
- * canonical `input`.
- *
- * Exported so the streaming side can hold a buffer that is still turning into one of these.
- * A second list of key names beside this one is how the streamed bytes and the completed item
- * come to disagree, which is the defect it exists to prevent (#5047).
- */
-export function freeformFallbackKeys(toolName: string): readonly string[] {
-  return FREEFORM_FALLBACK_KEYS[toolName] ?? [];
-}
-
 /** Unwrap the `{input:string}` function-call wrapper used for freeform tools. */
 export function unwrapFreeformToolInput(argumentsText: unknown, toolName = ""): string {
   if (typeof argumentsText !== "string") return "";