@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/vision/eligibility.ts

@@ -0,0 +1,229 @@
+/**
+ * Which models may serve AS the vision sidecar (the describer), as opposed to the
+ * models the sidecar describes FOR.
+ *
+ * Three rules make this non-obvious, and all are load-bearing:
+ *
+ * 1. `provider.noVisionModels` marks models the proxy describes images for, and
+ *    `applyProviderConfigHints` deliberately ADDS "image" to their advertised
+ *    input modalities so the Codex app does not block the attachment client-side.
+ *    A blind model therefore advertises image input. Membership in that list is a
+ *    hard disqualifier here, checked BEFORE the modality list it rewrote.
+ * 2. The catalog enriches configured providers from the registry before it
+ *    applies that rule. Eligibility must use the same effective provider policy,
+ *    including a `noVisionModels` list learned after the config was persisted.
+ * 3. Catalog rows frequently omit `inputModalities` entirely (the live
+ *    `/api/models` response carries none for either openai or anthropic rows).
+ *    Unknown is not zero: when no source can speak, the model stays eligible
+ *    rather than silently vanishing from the picker.
+ *    Native OpenAI metadata is likewise authoritative only for a native row or
+ *    the canonical OpenAI provider; a routed row with the same id owns its own
+ *    explicit modalities.
+ */
+import { modelInList, type OcxConfig, type OcxProviderConfig } from "../types";
+import { getModelMetadataCaseInsensitive, resolveMetadataProvider } from "../generated/model-metadata";
+import { nativeInputModalities } from "../codex/catalog/metadata";
+import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
+import { enrichProviderFromRegistry } from "../providers/derive";
+
+/** The two wire protocols `planVisionSidecar` can actually dispatch to. */
+export type VisionSidecarBackend = "openai" | "anthropic";
+
+/**
+ * Default entry per backend: cheap, image-capable, and present in every deployment. Offered
+ * whenever its side is enabled, and withheld only when that provider explicitly lists it as a
+ * model the sidecar describes FOR — never merely because a metadata table stayed silent.
+ */
+export const BASELINE_VISION_MODELS: Record<VisionSidecarBackend, string> = {
+  openai: "gpt-5.6-luna",
+  anthropic: "claude-haiku-4-5",
+};
+
+export interface VisionCandidateModel {
+  provider: string;
+  id: string;
+  inputModalities?: string[];
+  native?: boolean;
+}
+
+export interface VisionModelOption {
+  value: string;
+  label: string;
+  backend: VisionSidecarBackend;
+  /** True when the row is a guaranteed baseline rather than a catalog discovery. */
+  baseline?: boolean;
+}
+
+type EnrichedProviderCache = Map<string, OcxProviderConfig>;
+
+function advertisesImageInput(modalities: readonly string[] | undefined): boolean | undefined {
+  if (!modalities || modalities.length === 0) return undefined;
+  return modalities.includes("image");
+}
+
+/** Vendor-table modalities for a routed row, or undefined when the table has no opinion. */
+function metadataImageInput(provider: string, modelId: string): boolean | undefined {
+  const resolved = resolveMetadataProvider(provider) ?? provider;
+  const meta = getModelMetadataCaseInsensitive(resolved, modelId);
+  return advertisesImageInput(meta?.input);
+}
+
+/**
+ * Mirrors the catalog's registry enrichment without mutating saved configuration. The picker
+ * checks many rows from one provider, so its caller shares this small call-local cache.
+ */
+function enrichedProviderForVision(
+  config: Pick<OcxConfig, "providers">,
+  providerName: string,
+  cache: EnrichedProviderCache,
+): OcxProviderConfig | undefined {
+  const cached = cache.get(providerName);
+  if (cached) return cached;
+  const configured = config.providers?.[providerName];
+  if (!configured) return undefined;
+  const enriched = structuredClone(configured);
+  enrichProviderFromRegistry(providerName, enriched);
+  cache.set(providerName, enriched);
+  return enriched;
+}
+
+function isVisionSidecarConsumerWithCache(
+  config: Pick<OcxConfig, "providers">,
+  providerName: string,
+  modelId: string,
+  cache: EnrichedProviderCache,
+): boolean {
+  return modelInList(enrichedProviderForVision(config, providerName, cache)?.noVisionModels, modelId);
+}
+
+/**
+ * Is this model listed as one the sidecar describes FOR? Such a model cannot be
+ * the describer, and its advertised modalities are untrustworthy.
+ */
+export function isVisionSidecarConsumer(config: Pick<OcxConfig, "providers">, providerName: string, modelId: string): boolean {
+  return isVisionSidecarConsumerWithCache(config, providerName, modelId, new Map());
+}
+
+/**
+ * Can this model accept an image on the wire? Sources are consulted in descending
+ * trustworthiness; the first that speaks wins. `undefined` means nothing knows,
+ * which callers treat as eligible.
+ */
+export function modelAcceptsImageInput(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+): boolean | undefined {
+  return modelAcceptsImageInputWithCache(config, candidate, new Map());
+}
+
+function modelAcceptsImageInputWithCache(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+  cache: EnrichedProviderCache,
+): boolean | undefined {
+  if (isVisionSidecarConsumerWithCache(config, candidate.provider, candidate.id, cache)) return false;
+  if (candidate.native === true || (candidate.provider === "openai" && SUPPORTED_NATIVE_OPENAI_SLUGS.has(candidate.id))) {
+    return advertisesImageInput(nativeInputModalities(candidate.id)) ?? true;
+  }
+  const fromRow = advertisesImageInput(candidate.inputModalities);
+  if (fromRow !== undefined) return fromRow;
+  return metadataImageInput(candidate.provider, candidate.id);
+}
+
+/** Eligible = not a sidecar consumer, and not positively known to be text-only. */
+export function isVisionEligibleModel(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+): boolean {
+  return isVisionEligibleModelWithCache(config, candidate, new Map());
+}
+
+function isVisionEligibleModelWithCache(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+  cache: EnrichedProviderCache,
+): boolean {
+  return modelAcceptsImageInputWithCache(config, candidate, cache) !== false;
+}
+
+/** Which executor can describe through this row, or undefined when neither can. */
+export function visionBackendForCandidate(
+  config: Pick<OcxConfig, "providers">,
+  candidate: VisionCandidateModel,
+  anthropicProviderName?: string,
+): VisionSidecarBackend | undefined {
+  if (candidate.native || candidate.provider === "openai") return "openai";
+  // The runtime dispatches through exactly ONE Anthropic provider — the enabled OAuth row
+  // with a healthy active account that `findAnthropicVisionProvider` picks. Speaking the
+  // Messages wire is not enough: a key-auth row of the same adapter is unreachable, and an
+  // option that cannot be dispatched is worse than a missing one, because selecting it fails
+  // at describe time rather than at pick time.
+  //
+  // So the executor's name is REQUIRED for an Anthropic suggestion. When the caller has no
+  // executor to name, no catalog row qualifies; the side's baseline is added separately and
+  // keeps the picker populated. Narrowing here never widens the write gate, which is a
+  // different predicate (`modelAcceptsImageInput`) and still treats unknown as allowed.
+  if (anthropicProviderName === undefined) return undefined;
+  return candidate.provider === anthropicProviderName ? "anthropic" : undefined;
+}
+
+function baselineCandidate(
+  backend: VisionSidecarBackend,
+  anthropicProviderName: string | undefined,
+): VisionCandidateModel {
+  return {
+    provider: backend === "openai" ? "openai" : anthropicProviderName ?? "anthropic",
+    id: BASELINE_VISION_MODELS[backend],
+    // Both baselines are known image-capable. This makes their only exclusion path the
+    // provider's explicit consumer list, never a silent or stale metadata table.
+    inputModalities: ["text", "image"],
+  };
+}
+
+/**
+ * The picker's option list: every eligible row reachable by one of the two
+ * executors, plus each enabled side's baseline unless that baseline is explicitly
+ * excluded, de-duplicated and stably ordered (openai side first, baselines first
+ * within a side). Anthropic rows must belong to the OAuth provider that would
+ * actually execute them, so `anthropicProviderName` is what makes that side's
+ * catalog rows eligible at all.
+ *
+ * This is the SUGGESTION list (narrow): it emits only rows an executor can reach
+ * and some source has heard of. It is deliberately NOT the same set as the write
+ * gate. `modelAcceptsImageInput` answers "can we prove this model cannot see?"
+ * and is the only input to rejection. Absence from this list must never imply
+ * rejection — an unknown id stays eligible via the undefined → eligible fallback.
+ *
+ * De-duplication is by BARE model id, first eligible row wins. Two providers of
+ * the same adapter family can expose the same id; they resolve to the same
+ * backend, and only `value` reaches the client, so first-wins costs nothing.
+ */
+export function visionEligibleModelOptions(
+  config: Pick<OcxConfig, "providers">,
+  candidates: readonly VisionCandidateModel[],
+  enabledBackends: readonly VisionSidecarBackend[],
+  anthropicProviderName?: string,
+): VisionModelOption[] {
+  const enabled = new Set(enabledBackends);
+  const byValue = new Map<string, VisionModelOption>();
+  const enrichedProviders: EnrichedProviderCache = new Map();
+
+  for (const backend of ["openai", "anthropic"] as const) {
+    if (!enabled.has(backend)) continue;
+    const candidate = baselineCandidate(backend, anthropicProviderName);
+    if (!isVisionEligibleModelWithCache(config, candidate, enrichedProviders)) continue;
+    const id = candidate.id;
+    byValue.set(id, { value: id, label: id, backend, baseline: true });
+  }
+  for (const candidate of candidates) {
+    const backend = visionBackendForCandidate(config, candidate, anthropicProviderName);
+    if (!backend || !enabled.has(backend)) continue;
+    if (!isVisionEligibleModelWithCache(config, candidate, enrichedProviders)) continue;
+    if (byValue.has(candidate.id)) continue;
+    byValue.set(candidate.id, { value: candidate.id, label: candidate.id, backend });
+  }
+
+  const order = (option: VisionModelOption) =>
+    (option.backend === "openai" ? 0 : 2) + (option.baseline ? 0 : 1);
+  return [...byValue.values()].sort((a, b) => order(a) - order(b) || a.value.localeCompare(b.value));
+}

package/src/vision/index.ts

@@ -14,6 +14,15 @@ import type { TranslatorBudget } from "../lib/translator-budget";
 
 export { describeImage } from "./describe";
 export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
+export {
+  BASELINE_VISION_MODELS,
+  isVisionEligibleModel,
+  isVisionSidecarConsumer,
+  modelAcceptsImageInput,
+  visionBackendForCandidate,
+  visionEligibleModelOptions,
+} from "./eligibility";
+export type { VisionCandidateModel, VisionModelOption, VisionSidecarBackend } from "./eligibility";
 
 const DEFAULT_VISION_MODEL = "gpt-5.4-mini";
 const DEFAULT_ANTHROPIC_VISION_MODEL = "claude-sonnet-5";
@@ -192,6 +201,16 @@ export function resolveOpenAiVisionModel(config: Pick<OcxConfig, "visionSidecar"
   return config.visionSidecar?.model || DEFAULT_VISION_MODEL;
 }
 
+/** Effective describer model for the backend `planVisionSidecar` selected. */
+export function resolveEffectiveVisionModel(
+  config: Pick<OcxConfig, "visionSidecar">,
+  backend: "openai" | "anthropic",
+): string {
+  return backend === "anthropic"
+    ? config.visionSidecar?.model || DEFAULT_ANTHROPIC_VISION_MODEL
+    : resolveOpenAiVisionModel(config);
+}
+
 /** A user/developer/toolResult message can carry images (toolResult: e.g. Codex view_image output). */
 function carriesImages(role: string): boolean {
   return role === "user" || role === "developer" || role === "toolResult";
@@ -241,11 +260,11 @@ export function planVisionSidecar(
   if (cfg.enabled === false) return undefined;
   const anthropicSidecar = findAnthropicVisionProvider(config);
   const backend = resolveVisionBackend(cfg.backend, anthropicSidecar);
+  const model = resolveEffectiveVisionModel(config, backend);
   const maxDescriptionsPerTurn = resolveMaxDescriptionsPerTurn(cfg.maxDescriptionsPerTurn);
 
   if (backend === "anthropic") {
     if (!anthropicSidecar) return undefined;
-    const model = cfg.model || DEFAULT_ANTHROPIC_VISION_MODEL;
     return {
       backend,
       anthropicSidecar,
@@ -259,7 +278,6 @@ export function planVisionSidecar(
   }
 
   if (!openAiSidecar) return undefined;
-  const model = resolveOpenAiVisionModel(config);
   return {
     backend,
     forwardSidecar: openAiSidecar,

package/src/web-search/executor.ts

@@ -62,8 +62,8 @@ export async function runWebSearch(
     tool_choice: "auto",
     reasoning: { effort: settings.reasoning },
     // NOTE: the ChatGPT (codex) backend rejects `max_output_tokens` ("Unsupported parameter") and
-    // requires `store: false` — keep this body minimal. Answer length is capped downstream
-    // (format-result clamps the injected tool_result), so no upstream cap is needed.
+    // requires `store: false` — keep this body minimal. The shared SSE parser bounds raw response
+    // bytes before format-result applies its smaller display clamp.
     store: false,
     stream: true,
   };

package/src/web-search/index.ts

@@ -1,12 +1,13 @@
 import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
-import { modelInList } from "../types";
+import { modelInList, toolChoiceToolPredicate } from "../types";
 import type { SidecarSettings } from "./executor";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import { getAccountSet } from "../oauth/store";
 import { DEFAULT_STALL_TIMEOUT_SEC } from "../stall-timeout";
+import { buildWebSearchTool, extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "./synthetic-tool";
 
 export { runWithWebSearch } from "./loop";
-export { buildWebSearchTool, extractHostedWebSearch, WEB_SEARCH_TOOL_NAME } from "./synthetic-tool";
+export { buildWebSearchTool, extractHostedWebSearch, WEB_SEARCH_TOOL_NAME };
 export { runAnthropicWebSearch, parseAnthropicSidecarSSE } from "./anthropic-executor";
 
 const DEFAULT_SIDECAR_MODEL = "gpt-5.6-luna";
@@ -146,6 +147,7 @@ export function planWebSearch(
   openAiSidecar?: ResolvedOpenAiForwardSidecar,
 ): SidecarPlan | undefined {
   if (!parsed._webSearch || isPassthrough) return undefined;
+  if (!toolChoiceToolPredicate(parsed.options.toolChoice)(buildWebSearchTool())) return undefined;
   const cfg = config.webSearchSidecar ?? {};
   if (cfg.enabled === false) return undefined;
   const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;

package/src/web-search/loop.ts

@@ -1,6 +1,6 @@
 import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "../adapters/base";
 import type { AdapterEvent, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxThinkingContent, OcxUsage, RateLimitRetryPolicy } from "../types";
-import { namespacedToolName } from "../types";
+import { namespacedToolName, toolChoiceToolPredicate } from "../types";
 import type { AttemptRecoveryKind } from "../usage/log";
 import { bridgeToResponsesSSE } from "../bridge";
 import { runWebSearch, type SidecarOutcome, type SidecarOutcomeRecorder, type SidecarSettings } from "./executor";
@@ -693,7 +693,9 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
   const toolNsMap = new Map<string, { namespace: string; name: string }>();
   const freeform = new Set<string>();
   const toolSearch = new Set<string>();
+  const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice);
   for (const t of parsed.context.tools ?? []) {
+    if (!toolAllowed(t)) continue;
     if (t.namespace) toolNsMap.set(namespacedToolName(t.namespace, t.name), { namespace: t.namespace, name: t.name });
     if (t.freeform) freeform.add(t.name);
     if (t.toolSearch) toolSearch.add(t.name);

package/src/web-search/parse.ts

@@ -29,6 +29,10 @@ interface OutputItem {
   content?: OutputTextBlock[];
 }
 
+// ChatGPT's Codex backend does not accept `max_output_tokens` on sidecar requests. Bound the raw
+// streamed response here, before decoded text and authoritative/delta copies can accumulate.
+export const MAX_SIDECAR_RESPONSE_BYTES = 64 * 1024;
+
 /** Push a `url_citation` annotation as a source, de-duplicated by URL. */
 function collectAnnotation(ann: AnnotationLike | undefined, sources: WebSearchSource[], seen: Set<string>): void {
   if (!ann || ann.type !== "url_citation" || typeof ann.url !== "string" || seen.has(ann.url)) return;
@@ -49,7 +53,52 @@ function collectAnnotation(ann: AnnotationLike | undefined, sources: WebSearchSo
  */
 const URL_RE = /https?:\/\/[^\s<>()\[\]]+/;
 // A "Sources:" / "Source:" header, allowing markdown prefixes (#, *, -, >) and bold/italic wrappers.
-const SOURCES_HEADER_RE = /^\s*(?:#{1,6}\s*)?[-*>\s]*\**\s*sources?\s*\**\s*:?\s*\**\s*$/i;
+const SOURCES_WORD_RE = /^sources?/i;
+
+/** Match the legacy Sources-header grammar without overlapping regex quantifiers. */
+function isSourcesHeader(line: string): boolean {
+  let cursor = 0;
+  /** Match one code unit using JavaScript's existing `\s` semantics. */
+  const isWhitespace = (char: string | undefined): boolean => char !== undefined && /\s/u.test(char);
+  /** Advance over the current contiguous whitespace run. */
+  const skipWhitespace = (): void => {
+    while (isWhitespace(line[cursor])) cursor += 1;
+  };
+  /** Advance over the current contiguous Markdown-star run. */
+  const skipStars = (): void => {
+    while (line[cursor] === "*") cursor += 1;
+  };
+
+  skipWhitespace();
+  if (line[cursor] === "#") {
+    const start = cursor;
+    while (line[cursor] === "#") cursor += 1;
+    if (cursor - start > 6) return false;
+    skipWhitespace();
+  }
+
+  while (isWhitespace(line[cursor]) || line[cursor] === "-" || line[cursor] === "*" || line[cursor] === ">") {
+    cursor += 1;
+  }
+
+  const word = SOURCES_WORD_RE.exec(line.slice(cursor, cursor + 7));
+  if (!word) return false;
+  cursor += word[0].length;
+
+  // Preserve `\s*\**\s*:?\s*\**\s*$`: at most two star runs, with the optional
+  // colon between them. Either run may be empty, so `Sources:*` is one trailing run; three
+  // separated runs and a colon after the second run remain invalid.
+  skipWhitespace();
+  skipStars();
+  skipWhitespace();
+  if (line[cursor] === ":") {
+    cursor += 1;
+    skipWhitespace();
+  }
+  skipStars();
+  skipWhitespace();
+  return cursor === line.length;
+}
 
 /** Trim wrapping/trailing noise from a captured URL: angle brackets, then trailing punctuation. */
 function cleanUrl(url: string): string {
@@ -69,7 +118,7 @@ function extractTrailingSources(text: string): { text: string; sources: WebSearc
   // Find the LAST line that is a "Sources:" header (markdown prefixes allowed).
   let headerIdx = -1;
   for (let i = lines.length - 1; i >= 0; i--) {
-    if (SOURCES_HEADER_RE.test(lines[i])) { headerIdx = i; break; }
+    if (isSourcesHeader(lines[i])) { headerIdx = i; break; }
   }
   if (headerIdx === -1) return { text, sources: [] };
   const sources: WebSearchSource[] = [];
@@ -130,6 +179,15 @@ function fromOutputArray(output: OutputItem[], seen: Set<string>): WebSearchResu
   return { text, sources };
 }
 
+function cancelReaderWithoutWaiting(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  reason: string,
+): void {
+  try {
+    void reader.cancel(reason).catch(() => undefined);
+  } catch { /* best-effort body teardown */ }
+}
+
 /**
  * Parse the sidecar's streamed Responses SSE into a final answer + sources. Tolerant of the full set of
  * Responses streaming events: prefers the authoritative `response.completed` output[], then the
@@ -143,6 +201,7 @@ export async function parseSidecarSSE(response: Response): Promise<WebSearchResu
   const reader = response.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
+  let responseBytes = 0;
   const seen = new Set<string>();
   // Holder object — fields are mutated inside the closure, so they can't live as narrowed locals.
   const acc: {
@@ -197,13 +256,23 @@ export async function parseSidecarSSE(response: Response): Promise<WebSearchResu
     while (true) {
       const { done, value } = await reader.read();
       if (done) break;
-      buffer += decoder.decode(value, { stream: true });
+      const remaining = MAX_SIDECAR_RESPONSE_BYTES - responseBytes;
+      const accepted = value.byteLength <= remaining ? value : value.subarray(0, remaining);
+      responseBytes += accepted.byteLength;
+      buffer += decoder.decode(accepted, { stream: true });
       const lines = buffer.split("\n");
       buffer = lines.pop() ?? "";
       for (const line of lines) {
         const data = sseFieldValue(line, "data");
         if (data !== null) handle(data.trim());
       }
+      if (responseBytes >= MAX_SIDECAR_RESPONSE_BYTES) {
+        // Preserve complete events accepted up to the cap, but discard any unterminated line and
+        // TextDecoder carry. Do not let a rejecting/hung cancel turn bounded partial output into
+        // an error or keep this parser waiting on upstream teardown.
+        cancelReaderWithoutWaiting(reader, "sidecar response byte limit reached");
+        break;
+      }
     }
   } finally {
     reader.releaseLock();