@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/responses/bridge-search-replay-cache.ts

@@ -0,0 +1,152 @@
+/**
+ * Process-local memo pairing a bridged hosted `web_search` cell with the destination's own
+ * call and the result the proxy executed for it (issue #4587).
+ *
+ * The web-search passthrough bridge (`src/web-search/passthrough-bridge.ts`) intercepts the
+ * destination's `function_call` named `web_search`, runs the search itself, and shows the
+ * caller a hosted `web_search_call` cell under a proxy-minted `ws_<uuid>` id. The caller
+ * stores that cell and replays it on every later turn. The destination, which never produced a
+ * `web_search_call` in its life, then sees an unknown item type carrying a query and sources
+ * but no result — so it usually just searches again.
+ *
+ * This memo is what lets the pre-dispatch rewrite in the Responses adapter put the destination's
+ * own `function_call` and `function_call_output` back in that item's place. It records exactly
+ * what `appendBridgeSearchTurn` would have written onto a continuation leg, so a replayed turn
+ * and a continued turn show the destination the same conversation.
+ *
+ * Scope. Entries are keyed by the upstream destination in addition to the cell id. The cell id is
+ * a v4 UUID minted here, so it cannot collide across conversations, but an unscoped key would let
+ * a history replayed against a DIFFERENT provider resurrect a call that provider never made.
+ *
+ * Bounds and privacy. Result text is web content the caller already received, but it is still
+ * request-derived data: it lives in memory only, is never logged, serialized, or exported, and is
+ * bounded by entry count, total bytes, and TTL so a long-lived proxy cannot grow without limit.
+ *
+ * A miss is deliberately indistinguishable from "no entry": the caller leaves the replayed item
+ * alone. Neither re-running the search nor inventing a result is an acceptable recovery.
+ */
+
+import { reasoningReplayDestinationIdentity } from "./reasoning-replay-cache";
+
+const MAX_ENTRIES = 64;
+const MAX_TOTAL_BYTES = 512 * 1024;
+const TTL_MS = 60 * 60 * 1000;
+
+export interface BridgeSearchReplayEntry {
+  /** The destination's own call id, as it appeared on the intercepted item. */
+  callId: string;
+  /** The destination's own item id, replayed when the upstream supplied one. */
+  sourceItemId?: string;
+  /** The tool name the destination called, recorded rather than assumed. */
+  name: string;
+  /** The intercepted call's complete arguments text. */
+  argumentsText: string;
+  /** The tool result the bridge produced for that call. */
+  output: string;
+}
+
+interface StoredEntry {
+  entry: BridgeSearchReplayEntry;
+  bytes: number;
+  at: number;
+}
+
+const entries = new Map<string, StoredEntry>();
+let totalBytes = 0;
+let clockForTests: (() => number) | null = null;
+
+const now = (): number => clockForTests?.() ?? Date.now();
+
+/**
+ * Identify the upstream destination a bridged search belongs to.
+ *
+ * Reuses the salted process-local destination digest the reasoning replay cache already defines,
+ * so both stores agree on what "the same upstream" means and neither invents a second notion of
+ * destination identity.
+ */
+export function bridgeSearchReplayScope(baseUrl: string | undefined): string | undefined {
+  return reasoningReplayDestinationIdentity(baseUrl);
+}
+
+function keyFor(scope: string, cellItemId: string): string {
+  return scope + "\u0000" + cellItemId;
+}
+
+function drop(key: string, stored: StoredEntry): void {
+  entries.delete(key);
+  totalBytes -= stored.bytes;
+}
+
+function sweep(at: number): void {
+  for (const [key, stored] of entries) {
+    if (at - stored.at >= TTL_MS) drop(key, stored);
+  }
+  // Map iteration is insertion-ordered, so the oldest surviving entry is always the first one.
+  while (entries.size > MAX_ENTRIES || totalBytes > MAX_TOTAL_BYTES) {
+    const oldest = entries.entries().next();
+    if (oldest.done) {
+      totalBytes = 0;
+      return;
+    }
+    drop(oldest.value[0], oldest.value[1]);
+  }
+}
+
+/**
+ * Record one executed bridged search.
+ *
+ * An entry with no call id is not recorded: the restore would have to emit a `function_call`
+ * without one, which is not a valid item and could not be paired with its output anyway.
+ */
+export function rememberBridgeSearchReplay(
+  scope: string | undefined,
+  cellItemId: string,
+  entry: BridgeSearchReplayEntry,
+): void {
+  if (!scope || cellItemId.length === 0 || entry.callId.length === 0) return;
+  const key = keyFor(scope, cellItemId);
+  const existing = entries.get(key);
+  if (existing) drop(key, existing);
+  const bytes = 2 * (
+    key.length
+    + entry.callId.length
+    + (entry.sourceItemId?.length ?? 0)
+    + entry.name.length
+    + entry.argumentsText.length
+    + entry.output.length
+  );
+  // A single oversized result is refused outright rather than evicting the whole store for it.
+  if (bytes > MAX_TOTAL_BYTES) return;
+  entries.set(key, { entry: { ...entry }, bytes, at: now() });
+  totalBytes += bytes;
+  sweep(now());
+}
+
+/**
+ * Look up one recorded search without consuming it.
+ *
+ * The same cell is replayed on every subsequent turn of the conversation, so a consuming read
+ * would restore the pair once and then silently stop. Expiry stays absolute: a conversation that
+ * outlives the TTL degrades to today's behaviour (the hosted cell replays unchanged) rather than
+ * pinning entries open for as long as anyone keeps talking.
+ */
+export function peekBridgeSearchReplay(
+  scope: string | undefined,
+  cellItemId: string,
+): BridgeSearchReplayEntry | undefined {
+  if (!scope || cellItemId.length === 0) return undefined;
+  const key = keyFor(scope, cellItemId);
+  const stored = entries.get(key);
+  if (!stored) return undefined;
+  if (now() - stored.at >= TTL_MS) {
+    drop(key, stored);
+    return undefined;
+  }
+  return stored.entry;
+}
+
+export function clearBridgeSearchReplayCacheForTests(clock?: (() => number) | null): void {
+  entries.clear();
+  totalBytes = 0;
+  clockForTests = clock ?? null;
+}

package/src/responses/code-mode-helper-compat.ts

@@ -9,33 +9,43 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-function unwrapPatchInput(value: string): string {
-  try {
-    const parsed: unknown = JSON.parse(value);
-    if (isPlainObject(parsed)) {
-      if (typeof parsed.input === "string") return parsed.input;
-      if (typeof parsed.patch === "string") return parsed.patch;
-    }
-  } catch {
-    // Native custom calls carry the patch body directly.
-  }
-  return value;
-}
-
 /**
  * Convert a nested Code Mode helper call into unified-exec JavaScript.
  *
  * Parsed values are serialized as data, never interpolated as source, so command and patch text
  * cannot escape the generated call. Invalid structured helper payloads are also passed as data so
  * nested-tool validation can reject them without evaluating provider text as JavaScript.
+ *
+ * `wireToolName` is the name the body actually arrived under, which is not always the helper:
+ * a provider that got the NAME right and the BODY wrong sends `exec`, and the apply-patch
+ * helper is inferred from the payload. Recognition and compilation must read ONE canonical
+ * body, so both unwrap under that same name — see the apply-patch branch below. It defaults to
+ * the helper name, which is correct for the name-based path where the wire name IS the helper.
  */
-export function compileCodeModeHelperInput(argumentsText: unknown, toolName: string): string {
+export function compileCodeModeHelperInput(
+  argumentsText: unknown,
+  toolName: string,
+  wireToolName?: string,
+): string {
   if (typeof argumentsText !== "string") return "";
   const helperName = toolName.startsWith("default.")
     ? toolName.slice("default.".length)
     : toolName;
   if (helperName === "apply_patch") {
-    const patch = normalizeApplyPatchDelimiters(unwrapPatchInput(argumentsText));
+    // `resolveCodeModeHelperName` decides this IS an apply-patch call by reading
+    // `unwrapFreeformToolInput(argumentsText, wireToolName)`, which strips an outer Markdown
+    // fence and accepts that name's fallback fields (#4983). Compiling from a narrower unwrap
+    // meant a body accepted through a fence or a fallback field reached `tools.apply_patch`
+    // still wrapped, so the host rejected the JSON or the fence instead of applying the patch
+    // (#5046). One unwrap, one body, one decision.
+    //
+    // The vocabulary is the WIRE name rather than the helper name on purpose. `{"patch": ...}`
+    // is an apply_patch wrapper and is not an `exec` fallback field, and the recognizer already
+    // declines it under `exec`; reading it here would compile a body that recognition rejected,
+    // which is exactly the drift a second, looser unwrap introduces.
+    const patch = normalizeApplyPatchDelimiters(
+      unwrapFreeformToolInput(argumentsText, wireToolName ?? helperName),
+    );
     return `const result = await tools.apply_patch(${JSON.stringify(patch)});\ntext(result);`;
   }
   let parsed: unknown = argumentsText;
@@ -106,5 +116,5 @@ export function resolveCodeModeHelperName(
   // `tools.apply_patch(...)` JavaScript would be the mis-route this repair exists to avoid.
   if (!declaresCodeModeExec(declaredNames)) return undefined;
   if (typeof argumentsText !== "string" || argumentsText === "") return undefined;
-  return isCompletePatchEnvelope(unwrapFreeformToolInput(argumentsText)) ? "apply_patch" : undefined;
+  return isCompletePatchEnvelope(unwrapFreeformToolInput(argumentsText, "exec")) ? "apply_patch" : undefined;
 }

package/src/responses/custom-tool-compat.ts

@@ -326,7 +326,7 @@ export function restoreRoutedCustomCalls(
         id: customToolItemId(item.id),
         name: aliased ? targetName : item.name,
         input: helper
-          ? compileCodeModeHelperInput(sourceInput, helper)
+          ? compileCodeModeHelperInput(sourceInput, helper, aliased ? String(item.name) : targetName)
           : repairFreeformToolInput(
             sourceInput,
             targetName,

package/src/responses/freeform-wrapper-scan.ts

@@ -0,0 +1,279 @@
+// Bounded classification of a PARTIAL freeform tool-call wrapper.
+//
+// `unwrapFreeformToolInput` decides the completed input with `JSON.parse`, which does not care
+// what order an object's properties arrive in or how their names are spelled. The streaming side
+// has to reach the same answer from a prefix, and it used to do that by comparing the buffer
+// against the literal `{"input":"`. Spellings `JSON.parse` calls identical therefore matched no
+// wrapper at all, streamed as raw JSON, and then completed as the unwrapped body:
+// `{"metadata":1,"input":"cmd"}` and `{"\u0069nput":"cmd"}` both previewed the whole object and
+// completed as `cmd` (#5151). #5047 and #5129 closed the compact and whitespace spellings of the
+// same disagreement; reordering and escaping are the two the literal matcher could never see,
+// because RFC 8259 objects are unordered and their names are strings with escapes.
+//
+// So the prefix is scanned as JSON instead of matched as text. The scan answers one question —
+// which wrapper, if any, the completed text will unwrap to — and it answers it three ways:
+//
+//   `input`  the canonical key is present with a string value, whatever preceded it and however
+//            its name was spelled. Its value can be decoded progressively, because
+//            `unwrapFreeformToolInput` gives an own `input` precedence over every other property.
+//   `raw`    no wrapper can apply, because the text is not an object or because it is one that
+//            `JSON.parse` will reject. Completion returns the buffer, so streaming it agrees.
+//   `hold`   undecided. A key that has not arrived yet can still change the answer, so nothing
+//            is published until the object parses and completion's own rule decides.
+//
+// The bound matters as much as the classification. A scan that walks the whole buffer on every
+// delta is quadratic in the argument size, so classification gives up after
+// `MAX_FREEFORM_WRAPPER_SCAN_CHARS` and holds. Giving up costs preview, never agreement: a held
+// buffer is still resolved by the authoritative parse at completion.
+
+/** The insignificant whitespace `JSON.parse` accepts between tokens. */
+export const JSON_WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
+
+/** The two-character escapes JSON defines, and nothing else. */
+export const JSON_ESCAPES = new Map<string, string>([
+  ['"', '"'], ["\\", "\\"], ["/", "/"],
+  ["b", "\b"], ["f", "\f"], ["n", "\n"], ["r", "\r"], ["t", "\t"],
+]);
+
+/**
+ * How far a classification scan walks before it gives up and holds.
+ *
+ * A wrapper's own structure — its property names and the small scalar siblings a model puts
+ * beside the body — lives at the front of the object. A buffer still undecided after this much
+ * scanning is one whose preceding values are large, and holding it is what the routed
+ * restoration path already does for every unrecognized object.
+ */
+export const MAX_FREEFORM_WRAPPER_SCAN_CHARS = 4096;
+
+const CANONICAL_KEY = "input";
+
+/** The buffer ends inside a token: what follows can still change the answer. */
+const HOLD = -1;
+/** `JSON.parse` will reject this text no matter what is appended to it. */
+const NEVER = -2;
+
+export type FreeformWrapperScan =
+  | { kind: "hold"; parse: boolean }
+  | { kind: "raw" }
+  | { kind: "input"; valueStart: number };
+
+/** Index of the first non-whitespace character at or after `from`, or HOLD past the end. */
+function skipWhitespace(text: string, from: number): number {
+  let i = from;
+  while (i < text.length && JSON_WHITESPACE.has(text[i]!)) i++;
+  return i < text.length ? i : HOLD;
+}
+
+/**
+ * Index just past the complete JSON string opening at `from`, or HOLD / NEVER.
+ *
+ * This reports a BOUNDARY where `decodeJsonStringPrefix` reports a decoded PREFIX: one has to
+ * fail on a truncated string and the other has to return what it decoded so far. They answer
+ * different questions about the same bytes and share one escape table so they cannot disagree
+ * about which escapes exist.
+ */
+function scanString(text: string, from: number): number {
+  let i = from + 1;
+  while (i < text.length) {
+    const c = text[i]!;
+    if (c === '"') return i + 1;
+    if (c === "\\") {
+      const n = text[i + 1];
+      if (n === undefined) return HOLD;
+      if (n === "u") {
+        const hex = text.slice(i + 2, i + 6);
+        if (hex.length < 4) return HOLD;
+        if (!/^[0-9a-fA-F]{4}$/.test(hex)) return NEVER;
+        i += 6;
+        continue;
+      }
+      if (!JSON_ESCAPES.has(n)) return NEVER;
+      i += 2;
+      continue;
+    }
+    // A literal control character is not legal inside a JSON string.
+    if (c.charCodeAt(0) <= 0x1f) return NEVER;
+    i++;
+  }
+  return HOLD;
+}
+
+const JSON_NUMBER_CHARS = /[-+0-9.eE]/;
+const JSON_NUMBER = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/;
+
+/** Index just past one complete scalar at `from`, or HOLD / NEVER. */
+function scanScalar(text: string, from: number): number {
+  const c = text[from]!;
+  if (c === '"') return scanString(text, from);
+  if (c === "t" || c === "f" || c === "n") {
+    const literal = c === "t" ? "true" : c === "f" ? "false" : "null";
+    if (text.startsWith(literal, from)) return from + literal.length;
+    return literal.startsWith(text.slice(from)) ? HOLD : NEVER;
+  }
+  let end = from;
+  while (end < text.length && JSON_NUMBER_CHARS.test(text[end]!)) end++;
+  if (end === from) return NEVER;
+  // A number running to the end of the buffer can still grow another digit or exponent.
+  if (end >= text.length) return HOLD;
+  return JSON_NUMBER.test(text.slice(from, end)) ? end : NEVER;
+}
+
+/** Index where the value of the member whose name opens at `from` begins, or HOLD / NEVER. */
+function scanMemberKey(text: string, from: number): number {
+  if (text[from] !== '"') return NEVER;
+  const nameEnd = scanString(text, from);
+  if (nameEnd < 0) return nameEnd;
+  const colon = skipWhitespace(text, nameEnd);
+  if (colon === HOLD) return HOLD;
+  if (text[colon] !== ":") return NEVER;
+  return skipWhitespace(text, colon + 1);
+}
+
+/**
+ * Index just past one complete JSON value at `from`, or HOLD / NEVER.
+ *
+ * Containers are walked with an explicit stack rather than recursion: the value being skipped
+ * is provider-controlled, and a deeply nested one must not be able to exhaust the call stack.
+ */
+function scanValue(text: string, from: number): number {
+  const closers: string[] = [];
+  let i = from;
+  for (;;) {
+    const c = text[i]!;
+    if (c === "{" || c === "[") {
+      const closer = c === "{" ? "}" : "]";
+      closers.push(closer);
+      const first = skipWhitespace(text, i + 1);
+      if (first === HOLD) return HOLD;
+      if (text[first] === closer) {
+        closers.pop();
+        i = first + 1;
+      } else if (closer === "}") {
+        const value = scanMemberKey(text, first);
+        if (value < 0) return value;
+        i = value;
+        continue;
+      } else {
+        i = first;
+        continue;
+      }
+    } else {
+      const end = scanScalar(text, i);
+      if (end < 0) return end;
+      i = end;
+    }
+
+    // One value is complete: close whatever it finished and find the next value, if any.
+    for (;;) {
+      if (closers.length === 0) return i;
+      const at = skipWhitespace(text, i);
+      if (at === HOLD) return HOLD;
+      const closer = closers[closers.length - 1]!;
+      if (text[at] === closer) {
+        closers.pop();
+        i = at + 1;
+        continue;
+      }
+      if (text[at] !== ",") return NEVER;
+      const next = skipWhitespace(text, at + 1);
+      if (next === HOLD) return HOLD;
+      if (closer === "}") {
+        const value = scanMemberKey(text, next);
+        if (value < 0) return value;
+        i = value;
+      } else {
+        i = next;
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * Which wrapper the completed text will unwrap to, as far as this prefix can say.
+ *
+ * Fallback keys are deliberately not recognized here. They only unwrap when exactly one of them
+ * carries a string, and a second one can still arrive, so no prefix decides them — which makes
+ * them indistinguishable from any other undecided object and lets one HOLD cover both.
+ */
+export function scanFreeformWrapper(text: string): FreeformWrapperScan {
+  // One clamp rather than a budget threaded through every helper. Every helper already holds
+  // when it runs off the end of what it can see, so a buffer whose classification needs more
+  // than this holds for exactly the right reason, and no scan can cost more than this many
+  // characters however large the arguments grow. Indices into the clamp are indices into the
+  // full text, because the clamp is a prefix of it.
+  const bounded = text.length > MAX_FREEFORM_WRAPPER_SCAN_CHARS
+    ? text.slice(0, MAX_FREEFORM_WRAPPER_SCAN_CHARS)
+    : text;
+  // `parse` is true only where this scan actually SAW the object close. Every other hold ran
+  // out of buffer or out of budget, and in both cases asking `JSON.parse` is work with no
+  // possible payoff: the first is provably incomplete, and the second would re-read a growing
+  // buffer on every delta that happens to end in a brace — repeated braces inside a long
+  // unterminated string are enough to make that quadratic. Holding a budget-exhausted prefix
+  // costs nothing that matters, because the value it would release arrives in the same instant
+  // as the authoritative completion that follows it.
+  const hold = (): FreeformWrapperScan => ({ kind: "hold", parse: false });
+  const open = skipWhitespace(bounded, 0);
+  if (open === HOLD) return hold();
+  // Not an object, so no wrapper rule reaches it: arrays, scalars and ordinary bodies all
+  // complete as themselves.
+  if (bounded[open] !== "{") return { kind: "raw" };
+
+  let i = open + 1;
+  for (;;) {
+    const at = skipWhitespace(bounded, i);
+    if (at === HOLD) return hold();
+    if (bounded[at] === "}") return afterTopLevelClose(bounded, at + 1);
+    if (bounded[at] !== '"') return { kind: "raw" };
+
+    const nameEnd = scanString(bounded, at);
+    if (nameEnd === HOLD) return hold();
+    if (nameEnd === NEVER) return { kind: "raw" };
+    let name: string;
+    try {
+      // The authoritative decoder for the name, so `{"\u0069nput":...}` resolves to the same
+      // key completion sees. Decoding it by hand here is the second implementation that would
+      // drift from `JSON.parse`, which is how this defect existed in the first place.
+      name = JSON.parse(bounded.slice(at, nameEnd)) as string;
+    } catch {
+      return { kind: "raw" };
+    }
+
+    const colon = skipWhitespace(bounded, nameEnd);
+    if (colon === HOLD) return hold();
+    if (bounded[colon] !== ":") return { kind: "raw" };
+    const valueAt = skipWhitespace(bounded, colon + 1);
+    if (valueAt === HOLD) return hold();
+
+    if (name === CANONICAL_KEY) {
+      // An own `input` wins over everything else in the object, so this is decidable now. A
+      // non-string value is decidable too, in the other direction: completion hands back the
+      // argument text unchanged rather than unwrapping a value it cannot use.
+      return bounded[valueAt] === '"'
+        ? { kind: "input", valueStart: valueAt + 1 }
+        : { kind: "raw" };
+    }
+
+    const valueEnd = scanValue(bounded, valueAt);
+    if (valueEnd === HOLD) return hold();
+    if (valueEnd === NEVER) return { kind: "raw" };
+
+    const next = skipWhitespace(bounded, valueEnd);
+    if (next === HOLD) return hold();
+    if (bounded[next] === ",") {
+      i = next + 1;
+      continue;
+    }
+    if (bounded[next] === "}") return afterTopLevelClose(bounded, next + 1);
+    return { kind: "raw" };
+  }
+}
+
+/**
+ * The object closed without a canonical key. Only whitespace may follow one that parses, so
+ * anything else makes the text raw; otherwise the completed parse decides between a fallback
+ * wrapper and no wrapper at all.
+ */
+function afterTopLevelClose(text: string, from: number): FreeformWrapperScan {
+  return skipWhitespace(text, from) === HOLD ? { kind: "hold", parse: true } : { kind: "raw" };
+}

package/src/responses/hosted-tool-policy.ts

@@ -10,7 +10,90 @@ const UNSUPPORTED_HOSTED_TOOLS: ReadonlyArray<{
   },
 ];
 
-/** True when forwarding this hosted tool to the model would be rejected upstream. */
-export function isHostedToolUnsupportedForModel(modelId: string, tool: string, baseUrl?: string): boolean {
+/**
+ * Hosted-tool declaration names an operator may list in `unsupportedHostedTools`.
+ *
+ * A gateway must be able to deny anything a client can send it, so this is the set of
+ * nameless hosted/private declaration types the proxy recognizes on a Responses request.
+ * It is deliberately a closed vocabulary: the provider config schema ends in
+ * `.passthrough()`, so an unvalidated misspelling would be accepted, persisted, and then
+ * silently strip nothing -- which is the exact 400 the operator set the field to avoid
+ * (the `codexToolMode` lesson in #2106).
+ */
+export const DECLARABLE_HOSTED_TOOL_TYPES: ReadonlySet<string> = new Set([
+  "web_search",
+  "web_search_preview",
+  "file_search",
+  "computer_use_preview",
+  "computer_use",
+  "code_interpreter",
+  "image_generation",
+  "image_gen",
+  "mcp",
+  "tool_search",
+  "local_shell",
+  "x_search",
+]);
+
+/**
+ * Spellings that name one capability. Declaring either member denies both, because the
+ * rest of the proxy already treats these as a single tool: the parser folds
+ * `web_search_preview` onto one name (`src/responses/parser-tools.ts`), Chat ingress
+ * accepts the pair together (`src/chat/inbound.ts`), and the canonical-field strip lists
+ * the pair in a single `toolTypes` set
+ * (`src/adapters/openai-responses/request-strips.ts`).
+ *
+ * Without the alias a capability declaration would be honoured for the spelling the
+ * operator happened to write and ignored for the one the client happened to send, which
+ * reproduces the original rejection while the config claims to have prevented it.
+ */
+const HOSTED_TOOL_ALIAS_GROUPS: ReadonlyArray<ReadonlySet<string>> = [
+  new Set(["web_search", "web_search_preview"]),
+  new Set(["image_generation", "image_gen"]),
+  new Set(["computer_use_preview", "computer_use"]),
+];
+
+const NO_DECLARED_HOSTED_TOOLS: ReadonlySet<string> = new Set();
+
+/**
+ * Expand a provider's declared denials through the alias groups once per request, so the
+ * per-tool predicate stays a set lookup. Returns a shared empty set when the provider
+ * declares nothing, keeping the common path allocation-free.
+ */
+export function declaredUnsupportedHostedTools(
+  provider?: { unsupportedHostedTools?: readonly string[] },
+): ReadonlySet<string> {
+  const declared = provider?.unsupportedHostedTools;
+  if (!Array.isArray(declared) || declared.length === 0) return NO_DECLARED_HOSTED_TOOLS;
+  const out = new Set<string>();
+  for (const raw of declared) {
+    if (typeof raw !== "string") continue;
+    const tool = raw.trim();
+    if (!tool) continue;
+    out.add(tool);
+    for (const group of HOSTED_TOOL_ALIAS_GROUPS) {
+      if (!group.has(tool)) continue;
+      for (const alias of group) out.add(alias);
+    }
+  }
+  return out.size > 0 ? out : NO_DECLARED_HOSTED_TOOLS;
+}
+
+/**
+ * True when forwarding this hosted tool to the model would be rejected upstream.
+ *
+ * `declaredUnsupported` is the provider's own capability declaration, expanded by
+ * `declaredUnsupportedHostedTools`. It is additive to the built-in table rather than a
+ * replacement for it: the table covers destinations that reject a tool regardless of how
+ * the operator configured them, so an operator who never heard of the field stays
+ * protected.
+ */
+export function isHostedToolUnsupportedForModel(
+  modelId: string,
+  tool: string,
+  baseUrl?: string,
+  declaredUnsupported?: ReadonlySet<string>,
+): boolean {
+  if (declaredUnsupported?.has(tool)) return true;
   return UNSUPPORTED_HOSTED_TOOLS.some(entry => entry.match(modelId, baseUrl) && entry.tools.has(tool));
 }