@open-everywhere/adapters 0.7.0 → 0.8.0

package/agent/model/gateway.ts

@@ -1,5 +1,17 @@
-// The Vercel AI Gateway model backend — the reference `ModelBackend`. Provider SELECTION is not pinned here:
-// that is a gateway-operator concern, and `ModelRoute.providers` is only an optional per-route preference.
+// The Vercel AI Gateway model backend — the reference `ModelBackend`. It serves every `models.targets` entry of kind
+// `vercel-ai-gateway` (OPE-2556): one provider per target, built at the target's first call from its `url`. The target's
+// `providers.only` is a demand on every call through it; its `providers.order` and a route's `providerOrder` are
+// preferences. A route or a stack role picks its target with `via` (absent: `gateway`).
+//
+// 🔴 THE ONE MODEL ADAPTER (OPE-2535). Every model call of this process reaches the gateway through THIS file:
+// the turn model, the side calls (dream, facet and approval judges, meeting recap, image describer, gateway
+// transcription), and a bare model id string (a declared subagent's `model`), which the AI SDK resolves through
+// the default provider this module installs. That provider sends each bare id through the target of the role that
+// names it, else the primary role's target (OPE-2566, core model/bare-model-via.ts). An app that registers no roles
+// sends every bare id through `gateway`, and the process says so once when another target exists.
+// Every model it hands out carries `models.dataPolicy` on every call (`policyModel`). A call that cannot carry the rows (a realtime client secret, a streaming-transcription token)
+// refuses under a policy or a `providers.only` row. Two exceptions: under `eve dev` eve resolves a literal id through its own local gateway, and a
+// default provider another module set first is kept behind a guard that refuses under a policy, and for a bare id whose target is not `gateway`. `npm run lint:model-adapter` refuses a module elsewhere that builds a gateway model itself.
 
 import { gateway, createGateway } from "ai";
 import {
@@ -7,19 +19,33 @@ import {
   type BindableContext,
   type ModelBackend,
   type RoutedCallOptions,
+  type ModelDataPolicy,
+  type ModelTarget,
+  DEFAULT_MODEL_VIA,
+  bareModelRoutesRegistered,
+  bareModelVia,
+  dataPolicyActive,
+  dataPolicyRows,
+  mergeDataPolicy,
+  getSettings,
   hostPlaneFetch,
   hostPlanePolicy,
   liveIdentity,
+  modelTargetFor,
   resolvePrimaryModel,
+  useSelfHostEgress,
 } from "@open-everywhere/core/agent/adapter-api.js";
+import { targetBaseUrl } from "./target-url.js";
+
+export { DEPRECATED_GATEWAY_URL_ENV, targetBaseUrl } from "./target-url.js";
 
 type GatewayModel = ReturnType<typeof gateway>;
+type GatewayProvider = typeof gateway;
 
-/**
- * THE GATEWAY TARGET — `OE_AI_GATEWAY_URL`, read once at module load: a target that changed mid-process would
- * send two calls in one turn to two providers. Unset ⇒ the plain `gateway` export, byte-identical.
- */
-const GATEWAY_BASE_URL = process.env.OE_AI_GATEWAY_URL?.trim();
+/** The deployment's targets, read at CALL time: settings register after this module loads. */
+function currentTargets(): ReturnType<typeof getSettings>["models"]["targets"] {
+  return getSettings().models.targets;
+}
 
 /** The gateway's own host when {@link GATEWAY_BASE_URL} is unset. It must match the `ai` package's default base URL. */
 export const DEFAULT_GATEWAY_HOST = "ai-gateway.vercel.sh";
@@ -34,8 +60,23 @@ export function gatewayHost(baseUrl: string | undefined): string {
   }
 }
 
-/** The one host this deployment's gateway calls reach — what every host-plane push must keep declaring. */
-export const GATEWAY_TARGET_HOST = gatewayHost(GATEWAY_BASE_URL);
+/** The base URL each target resolved at its first use. READ ONCE per process: a target that changed mid-process
+ *  would send two calls in one turn to two places. A change needs a restart. */
+const TARGET_URLS = new Map<string, string | undefined>();
+function resolvedTargetUrl(name: string): string | undefined {
+  if (!TARGET_URLS.has(name)) TARGET_URLS.set(name, targetBaseUrl(name, modelTargetFor(name, currentTargets())));
+  return TARGET_URLS.get(name);
+}
+
+/** The one host the `gateway` target's calls reach (its `url`, else the deprecated env var, else the default). */
+export function gatewayTargetHost(): string {
+  return gatewayHost(resolvedTargetUrl(DEFAULT_MODEL_VIA));
+}
+
+/** The hosts of every configured target — what every host-plane push must keep declaring. */
+function targetHosts(): string[] {
+  return Object.keys(currentTargets()).map((name) => gatewayHost(resolvedTargetUrl(name)));
+}
 
 /**
  * THE HOST-PLANE UNION (OPE-2470). The proxy REPLACES its host plane on every push; it never merges
@@ -44,9 +85,17 @@ export const GATEWAY_TARGET_HOST = gatewayHost(GATEWAY_BASE_URL);
  * non-gateway transcription routes never push lists that drop each other. A caller adds its hosts with
  * {@link sharedHostPlaneFetch} at boot; a grown set builds a new fetch, which pushes the union on its next call.
  */
-const HOST_PLANE_HOSTS: string[] = [GATEWAY_TARGET_HOST];
-let hostPlaneCurrent = hostPlaneFetch(HOST_PLANE_HOSTS);
-let hostPlaneBuiltFor = HOST_PLANE_HOSTS.length;
+const HOST_PLANE_HOSTS: string[] = [];
+let hostPlaneCurrent: typeof fetch | undefined;
+let hostPlaneBuiltFor = -1;
+let targetHostsSeeded = false;
+/** Add every target's host to the host plane, once. At CALL time: the targets are settings, which register after this
+ *  module loads. */
+function seedTargetHosts(): void {
+  if (targetHostsSeeded) return;
+  targetHostsSeeded = true;
+  for (const h of targetHosts()) if (!HOST_PLANE_HOSTS.includes(h)) HOST_PLANE_HOSTS.unshift(h);
+}
 /**
  * THE MODEL CALL'S TRANSPORT ON THE SELF-HOST PROXY TIER (OPE-2406). With an egress proxy wired, the model call goes out
  * on the app's HOST PLANE: the proxy decides it against the host-plane list (the gateway host, plus the hosts of any
@@ -54,11 +103,11 @@ let hostPlaneBuiltFor = HOST_PLANE_HOSTS.length;
  * its model while the session stays default-deny. Off that tier it is `undefined` and the provider keeps its default
  * fetch, byte-identical to before. On it, the fetch always uses the newest union.
  */
-const HOST_PLANE_FETCH: typeof fetch | undefined =
-  hostPlaneCurrent === undefined
-    ? undefined
-    : (input, init) => {
-        if (hostPlaneBuiltFor !== HOST_PLANE_HOSTS.length) {
+const HOST_PLANE_FETCH: typeof fetch | undefined = !useSelfHostEgress()
+  ? undefined
+  : (input, init) => {
+        seedTargetHosts();
+        if (hostPlaneCurrent === undefined || hostPlaneBuiltFor !== HOST_PLANE_HOSTS.length) {
           hostPlaneCurrent = hostPlaneFetch(HOST_PLANE_HOSTS);
           hostPlaneBuiltFor = HOST_PLANE_HOSTS.length;
         }
@@ -70,22 +119,386 @@ export function sharedHostPlaneFetch(hosts: readonly string[]): typeof fetch | u
   // Validate BEFORE the list grows: a wildcard host throws here, at registration, and never reaches the shared list,
   // where it would fail every model turn at the next rebuild. A blank name is skipped.
   const named = hosts.map((h) => h.trim()).filter((h) => h !== "");
-  if (HOST_PLANE_FETCH !== undefined) hostPlanePolicy([...HOST_PLANE_HOSTS, ...named]);
+  if (HOST_PLANE_FETCH !== undefined && named.length > 0) hostPlanePolicy(named);
   for (const h of named) if (!HOST_PLANE_HOSTS.includes(h)) HOST_PLANE_HOSTS.push(h);
   return HOST_PLANE_FETCH;
 }
 
-/** The gateway provider this backend resolves model ids through — retargeted only when
- *  {@link GATEWAY_BASE_URL} names a different host. */
-const provider =
-  GATEWAY_BASE_URL || HOST_PLANE_FETCH
-    ? createGateway({ ...(GATEWAY_BASE_URL ? { baseURL: GATEWAY_BASE_URL } : {}), ...(HOST_PLANE_FETCH ? { fetch: HOST_PLANE_FETCH } : {}) })
-    : gateway;
+/** One gateway provider per target, built at the target's first call. A target with no url off the proxy tier is the
+ *  plain `gateway` export, byte-identical to before. */
+const TARGET_PROVIDERS = new Map<string, GatewayProvider>();
+function targetProvider(via: string | undefined): GatewayProvider {
+  const name = via ?? DEFAULT_MODEL_VIA;
+  let p = TARGET_PROVIDERS.get(name);
+  if (p === undefined) {
+    const baseURL = resolvedTargetUrl(name);
+    p =
+      baseURL !== undefined || HOST_PLANE_FETCH !== undefined
+        ? createGateway({ ...(baseURL !== undefined ? { baseURL } : {}), ...(HOST_PLANE_FETCH !== undefined ? { fetch: HOST_PLANE_FETCH } : {}) })
+        : gateway;
+    TARGET_PROVIDERS.set(name, p);
+  }
+  return p;
+}
+
+// ── the data policy (OPE-2535) ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The Vercel AI Gateway options for one `models.dataPolicy`. Pure. An absent row adds no key, so the shipped `{}`
+ * changes no request byte.
+ */
+export function vercelDataPolicyOptions(p: ModelDataPolicy): Record<string, unknown> {
+  return {
+    ...(p.zeroRetention === true ? { zeroDataRetention: true } : {}),
+    ...(p.noTraining === true ? { disallowPromptTraining: true } : {}),
+    ...(p.region !== undefined ? { inferenceRegion: { scope: "zone", geoRegion: p.region } } : {}),
+  };
+}
+
+/** The call-options shape every model kind shares: language, transcription and embedding calls all carry it. */
+type ProviderOptionsCarrier = { readonly providerOptions?: Record<string, unknown> | undefined };
+
+/**
+ * Put the policy on one call's options. Pure. The policy's keys WIN over the call's own gateway keys, so a call
+ * cannot weaken a row (`zeroDataRetention: false` on a call is overwritten). Every other key passes through. A
+ * policy that demands nothing returns the options unchanged.
+ */
+export function withDataPolicy<T extends ProviderOptionsCarrier>(options: T, p: ModelDataPolicy): T {
+  return withTargetRows(options, undefined, p);
+}
+
+/** Whether a target or a policy demands anything of a call: a `models.dataPolicy` row, a `providers.only` row, or a
+ *  row of the target's own `dataPolicy`. */
+function demandsAnything(t: ModelTarget | undefined, p: ModelDataPolicy): boolean {
+  return dataPolicyActive(p) || (t?.providers?.only?.length ?? 0) > 0 || (t?.dataPolicy !== undefined && dataPolicyActive(t.dataPolicy));
+}
+
+/**
+ * The demands on a call, in the words of the settings file, for an error: `models.dataPolicy (region eu)`,
+ * `models.targets.gateway.providers.only (openai, azure)`, `models.targets.mistral.dataPolicy (zeroRetention)`, or
+ * several joined with " + ".
+ */
+export function demandLabel(p: ModelDataPolicy, t?: ModelTarget, via: string = DEFAULT_MODEL_VIA): string {
+  const parts: string[] = [];
+  if (dataPolicyActive(p)) parts.push(`models.dataPolicy (${dataPolicyRows(p).join(", ")})`);
+  const only = t?.providers?.only;
+  if (only !== undefined && only.length > 0) parts.push(`models.targets.${via}.providers.only (${only.join(", ")})`);
+  if (t?.dataPolicy !== undefined && dataPolicyActive(t.dataPolicy)) parts.push(`models.targets.${via}.dataPolicy (${dataPolicyRows(t.dataPolicy).join(", ")})`);
+  return parts.join(" + ");
+}
+
+/**
+ * Put a target's rows and the data policy on one call's options. Pure but for a refusal. The order of the merge:
+ *  1. the target's `options` are a FLOOR: a call's own key wins;
+ *  2. the target's `providers.order` applies when the call names no `order` (a route's `providerOrder` wins);
+ *  3. the target's `providers.only` is a DEMAND: a call's own `only` narrows it to the intersection, and an empty
+ *     intersection REFUSES (an empty `only` would read as no filter at all);
+ *  4. the policy's keys win over everything. The policy is `models.dataPolicy` plus the target's own `dataPolicy` rows
+ *     (OPE-2531): a target adds rows and never removes one.
+ * A target with no rows and a policy that demands nothing return the options unchanged, so the shipped value changes
+ * no request byte.
+ */
+export function withTargetRows<T extends ProviderOptionsCarrier>(options: T, t: ModelTarget | undefined, global: ModelDataPolicy, via: string = DEFAULT_MODEL_VIA): T {
+  const floor = t?.options;
+  const only = t?.providers?.only;
+  const order = t?.providers?.order;
+  let p: ModelDataPolicy;
+  try {
+    p = mergeDataPolicy(global, t?.dataPolicy);
+  } catch (err) {
+    throw new Error(`models.targets.${via}.dataPolicy: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+  }
+  if (floor === undefined && only === undefined && order === undefined && !dataPolicyActive(p)) return options;
+  const gw = (options.providerOptions?.["gateway"] ?? {}) as Record<string, unknown>;
+  const merged: Record<string, unknown> = { ...floor, ...gw };
+  if (order !== undefined && merged["order"] === undefined) merged["order"] = [...order];
+  if (only !== undefined) {
+    const own = Array.isArray(gw["only"]) ? (gw["only"] as unknown[]) : undefined;
+    const allowed = own === undefined ? [...only] : own.filter((s): s is string => typeof s === "string" && only.includes(s));
+    if (allowed.length === 0) {
+      throw new Error(`${demandLabel(global, t, via)}: the call's own provider list (${(own ?? []).join(", ")}) shares no provider with the target's, so it refuses`);
+    }
+    merged["only"] = allowed;
+  }
+  Object.assign(merged, vercelDataPolicyOptions(p));
+  return { ...options, providerOptions: { ...options.providerOptions, gateway: merged } };
+}
+
+/** The gateway's refusal when no provider meets a filter (a 400 `invalid_request_error`). Live text, 2026-10-14: "No provider for <id> supports the
+ *  requested inference region." and "No available providers match the 'only' filter". The SDK keeps only the
+ *  message (the error type is the generic `invalid_request_error`), so the match is on the text. */
+const NO_PROVIDER = /\bno (?:available )?providers?\b/i;
+
+/**
+ * Name the policy rows on a refusal the policy caused. A model with no provider that meets the rows fails with an
+ * error that says which rows, and which model: "models.dataPolicy (region eu): no provider serves …". Any other
+ * error, or any error with no policy set, passes through unchanged.
+ */
+export function dataPolicyCallError(modelId: string, p: ModelDataPolicy, err: unknown, t?: ModelTarget, via?: string): unknown {
+  if (!demandsAnything(t, p)) return err;
+  // Only a non-retryable 4xx is the policy's refusal. A 5xx with the same words is an outage: it passes unchanged,
+  // with its status and its retry flag, and it does not blame the rows.
+  const e = err as { statusCode?: unknown; isRetryable?: unknown };
+  if (typeof e?.statusCode !== "number" || e.statusCode < 400 || e.statusCode >= 500 || e.isRetryable === true) return err;
+  const msg = err instanceof Error ? err.message : String(err);
+  if (!NO_PROVIDER.test(msg)) return err;
+  return new Error(`${demandLabel(p, t, via)}: no provider serves "${modelId}" under these rows. The call fails closed and does not fall back. Gateway said: ${msg}`, { cause: err });
+}
+
+/** The deployment's data policy, read at CALL time: settings register after this module loads. */
+function currentDataPolicy(): ModelDataPolicy {
+  return getSettings().models.dataPolicy;
+}
+
+/** The model methods that send a request: every `do*` member (`doGenerate`, `doStream`, `doEmbed`, `doEvaluate`,
+ *  `doRerank`, video's `doStart`, batch's `doStartBatch`, …). Each takes the call options first. */
+const CALL_METHOD = /^do[A-Z]/;
+
+/** Call methods that send no `providerOptions` at all, so the rows cannot ride them: the realtime client secret.
+ *  Under a policy they refuse. */
+const ROWLESS_METHODS = new Set<string>(["doCreateClientSecret"]);
+
+/** Put the rows on a call's options, and for a batch on each request's own options too: the SDK sends a batch
+ *  request's `providerOptions` per request, so the top-level merge alone would leave a request's own `false`. */
+function withRowsFor(prop: string, options: ProviderOptionsCarrier, t: ModelTarget | undefined, p: ModelDataPolicy, via: string): ProviderOptionsCarrier {
+  const merged = withTargetRows(options, t, p, via);
+  const requests = (merged as { requests?: unknown }).requests;
+  if (prop !== "doStartBatch" || merged === options || !Array.isArray(requests)) return merged;
+  return {
+    ...merged,
+    requests: requests.map((r: unknown) => {
+      const req = r as { options?: ProviderOptionsCarrier } | null;
+      return req !== null && typeof req === "object" ? { ...req, options: withTargetRows(req.options ?? {}, t, p, via) } : r;
+    }),
+  } as ProviderOptionsCarrier;
+}
+
+/** The target a `via` names, read at CALL time. An unknown name throws: a call never guesses a target. */
+function currentTarget(via: string): ModelTarget {
+  return modelTargetFor(via, currentTargets());
+}
+
+/**
+ * Copy a provider member's own properties onto its wrapper. A function among them (`experimental_transcription.getToken`)
+ * mints a session token from the RAW model, and the client then opens the session itself, so the rows cannot ride it:
+ * under a policy it refuses. Used by both the policy provider and the foreign-provider guard.
+ */
+function withGuardedMemberProps<W extends (...a: unknown[]) => unknown>(wrapped: W, member: object, name: string, via: string = DEFAULT_MODEL_VIA): W {
+  for (const [k, v] of Object.entries(member)) {
+    (wrapped as unknown as Record<string, unknown>)[k] =
+      typeof v === "function"
+        ? (...args: unknown[]): unknown => {
+            const p = currentDataPolicy();
+            const t = currentTarget(via);
+            if (demandsAnything(t, p)) throw rowlessRefusal(p, `${name}.${k}`, t, via);
+            return (v as (...a: unknown[]) => unknown).apply(member, args);
+          }
+        : v;
+  }
+  return wrapped;
+}
+
+/** Refuse a call that cannot carry the rows. */
+function rowlessRefusal(p: ModelDataPolicy, what: string, t?: ModelTarget, via?: string): Error {
+  return new Error(`${demandLabel(p, t, via)}: ${what} cannot carry the rows, so it refuses`);
+}
+
+/**
+ * A model that carries the data policy on EVERY call it sends. A Proxy, so the model keeps its class, its
+ * `provider`, its `modelId` and every other member: eve and the AI SDK see the same object shape. Only the calls
+ * change: the policy merges into the options, and a refusal it caused names the rows.
+ */
+export function policyModel<M extends object>(model: M, via: string = DEFAULT_MODEL_VIA): M {
+  return new Proxy(model, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver) as unknown;
+      if (typeof prop !== "string" || !CALL_METHOD.test(prop) || typeof value !== "function") return value;
+      return async (options: unknown, ...rest: unknown[]) => {
+        const p = currentDataPolicy();
+        const t = currentTarget(via);
+        // A first argument that is not an options object has no `providerOptions` to carry the rows: refuse it under a
+        // demand rather than send it bare.
+        const isOptions = options !== null && typeof options === "object" && !Array.isArray(options);
+        if ((!isOptions || ROWLESS_METHODS.has(prop)) && demandsAnything(t, p)) throw rowlessRefusal(p, prop, t, via);
+        const sent = isOptions ? withRowsFor(prop, options as ProviderOptionsCarrier, t, p, via) : options;
+        try {
+          return await (value as (...a: unknown[]) => Promise<unknown>).call(receiver, sent, ...rest);
+        } catch (err) {
+          throw dataPolicyCallError(String((target as { modelId?: unknown }).modelId ?? "?"), p, err, t, via);
+        }
+      };
+    },
+  });
+}
+
+/** A gateway LANGUAGE model on the target `via` names (absent: `gateway`), with its url and the host-plane fetch,
+ *  carrying the target's rows and the data policy. The one way a module outside this file gets a gateway model. */
+export function gatewayLanguageModel(id: string, via?: string): GatewayModel {
+  return policyModel(targetProvider(via)(id), via ?? DEFAULT_MODEL_VIA);
+}
+
+/** Marks the policy provider, across bundle copies of this module, so a second copy does not mistake it for a
+ *  foreign provider. Answered by the proxy; the gateway provider itself is never written to. */
+const OWN_PROVIDER = Symbol.for("open-everywhere.gateway.policyProvider");
+
+/** The provider members that build nothing that sends a prompt: account reads and the tool catalogue. */
+const NON_MODEL_MEMBERS = new Set<PropertyKey>(["getAvailableModels", "getCredits", "getSpendReport", "getGenerationInfo", "tools"]);
+
+/**
+ * A provider whose every model-building member (`languageModel`, its `chat` alias, `evaluationModel`, `reranking`,
+ * `experimental_batch`, …) hands out policy models. A denylist, not an allow-list: a member the SDK adds later is
+ * wrapped by default. A member's own properties (`experimental_transcription.getToken`) stay on it.
+ */
+export function policyProvider<P extends object>(base: P): P {
+  return new Proxy(base, {
+    apply(target, thisArg, args: unknown[]) {
+      const m = Reflect.apply(target as (...a: unknown[]) => unknown, thisArg, args);
+      return m !== null && typeof m === "object" ? policyModel(m) : m;
+    },
+    get(target, prop, receiver) {
+      if (prop === OWN_PROVIDER) return true;
+      const value = Reflect.get(target, prop, receiver) as unknown;
+      if (typeof value !== "function" || NON_MODEL_MEMBERS.has(prop)) return value;
+      const wrapped = (...args: unknown[]): unknown => {
+        const m = (value as (...a: unknown[]) => unknown).apply(target, args);
+        return m !== null && typeof m === "object" ? policyModel(m) : m;
+      };
+      return withGuardedMemberProps(wrapped, value, String(prop));
+    },
+  });
+}
+
+/** The target a member call's bare id goes through: its first argument, else the deployment default. */
+function bareViaOf(args: readonly unknown[]): string {
+  noteUnregisteredBareIds();
+  return bareModelVia(typeof args[0] === "string" ? args[0] : "").via;
+}
+
+let bareGapNoted = false;
+
+/**
+ * An app that does not register its roles (`agent/model/models.ts` from before 0.8.0) sends every bare id through
+ * `gateway`. When `models.targets` names another target, that may leave the target a role names, so the process says so
+ * once, at the first bare-id call, and the call goes on through `gateway` (OPE-2566). An all-gateway app logs nothing.
+ */
+function noteUnregisteredBareIds(): void {
+  if (bareGapNoted || bareModelRoutesRegistered()) return;
+  if (!Object.keys(currentTargets()).some((k) => k !== DEFAULT_MODEL_VIA)) return;
+  bareGapNoted = true;
+  console.error(
+    "[open-everywhere:model] a bare model id (a declared subagent's model, eve evaluate()) goes via gateway, because agent/model/models.ts " +
+      "does not call registerBareModelRoutes. Add the line from the 0.8.0 template so it takes its role's target. npm run check:model-config names this too.",
+  );
+}
+
+/** Test seam: let the next bare-id call note the gap again. */
+export function _resetBareGapNoticeForTest(): void {
+  bareGapNoted = false;
+}
+
+/**
+ * THE BARE-ID PROVIDER (OPE-2566). A provider that sends each bare id through the target its role names
+ * (core model/bare-model-via.ts): the role that names the id, else the primary role's target, else `gateway`. Every
+ * model it builds is a policy model on that target, so the target's url, provider pin and data-policy rows ride the
+ * call. It reads the table at CALL time: the app registers its roles after this module loads. A member's own
+ * properties (`experimental_transcription.getToken`) and the account reads use the deployment default's target.
+ * Exported for tests.
+ */
+export function bareIdProvider(): GatewayProvider {
+  const build = (prop: PropertyKey | undefined, args: unknown[]): unknown => {
+    const via = bareViaOf(args);
+    const p = targetProvider(via);
+    const m = prop === undefined ? Reflect.apply(p as unknown as (...a: unknown[]) => unknown, undefined, args) : (Reflect.get(p, prop) as (...a: unknown[]) => unknown).apply(p, args);
+    return m !== null && typeof m === "object" ? policyModel(m, via) : m;
+  };
+  return new Proxy(function bareIdGateway() {} as unknown as GatewayProvider, {
+    apply: (_t, _thisArg, args: unknown[]) => build(undefined, args),
+    get: (_t, prop) => {
+      if (prop === OWN_PROVIDER) return true;
+      const via = bareModelVia("").via;
+      const value = Reflect.get(targetProvider(via), prop) as unknown;
+      if (typeof value !== "function" || NON_MODEL_MEMBERS.has(prop)) return value;
+      return withGuardedMemberProps((...args: unknown[]): unknown => build(prop, args), value, String(prop), via);
+    },
+    has: (_t, prop) => prop === OWN_PROVIDER || Reflect.has(targetProvider(bareModelVia("").via), prop),
+  });
+}
+
+/**
+ * THE DEFAULT PROVIDER. The AI SDK resolves a bare model id string through `globalThis.AI_SDK_DEFAULT_PROVIDER`,
+ * else its own plain `gateway`. eve passes a declared subagent's `model: "<id>"` to the SDK as that string, and
+ * eve's own `evaluate()` (auto-approval, auto routing, agentRouter) does the same. Without this those calls skip the
+ * data policy, the retarget and the host plane. This installs the bare-id provider there, so each call also goes
+ * through its role's target (OPE-2566).
+ *
+ * 🔴 A PROVIDER ANOTHER MODULE ALREADY SET is kept, because that module chose it. But it is not this adapter's, so
+ * it cannot carry the rows: under a data policy every call through it REFUSES (fail closed), and the boot says so.
+ */
+const sdkGlobal = globalThis as { AI_SDK_DEFAULT_PROVIDER?: unknown };
+const installed = sdkGlobal.AI_SDK_DEFAULT_PROVIDER;
+if (installed === undefined || installed === null) {
+  sdkGlobal.AI_SDK_DEFAULT_PROVIDER = bareIdProvider();
+} else if ((typeof installed === "object" || typeof installed === "function") && installed !== null && (installed as Record<symbol, unknown>)[OWN_PROVIDER] !== true) {
+  console.error(
+    "[open-everywhere:model] AI_SDK_DEFAULT_PROVIDER was already set by another module. A bare model id resolves through it, " +
+      "and it cannot carry models.dataPolicy, so under a data policy every such call refuses.",
+  );
+  sdkGlobal.AI_SDK_DEFAULT_PROVIDER = foreignProviderGuard(installed);
+}
+
+/**
+ * A foreign default provider, kept, behind a guard: with no policy it is untouched; under a policy every model call
+ * through it refuses, because nothing proves that provider honours the rows. The guard reads the target the bare id
+ * goes through (OPE-2566): that target's rows count, and a target other than `gateway` refuses too, because the
+ * foreign provider would send the call somewhere else. Exported for tests.
+ */
+export function foreignProviderGuard<P extends object>(base: P): P {
+  const guardModel = (m: object, via: string): object =>
+    new Proxy(m, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver) as unknown;
+        if (typeof prop !== "string" || !CALL_METHOD.test(prop) || typeof value !== "function") return value;
+        return async (...args: unknown[]) => {
+          if (via !== DEFAULT_MODEL_VIA) {
+            throw new Error(`this call goes through the target "${via}", but it resolved through a default provider that is not the gateway adapter's, so it cannot reach that target, and it refuses`);
+          }
+          const p = currentDataPolicy();
+          const t = currentTarget(via);
+          if (demandsAnything(t, p)) {
+            throw new Error(`${demandLabel(p, t)}: this call resolved through a default provider that is not the gateway adapter's, so it cannot carry the rows, and it refuses`);
+          }
+          return await (value as (...a: unknown[]) => Promise<unknown>).apply(receiver, args);
+        };
+      },
+    });
+  return new Proxy(base, {
+    apply(target, thisArg, args: unknown[]) {
+      const m = Reflect.apply(target as (...a: unknown[]) => unknown, thisArg, args);
+      return m !== null && typeof m === "object" ? guardModel(m, bareViaOf(args)) : m;
+    },
+    get(target, prop, receiver) {
+      // A second bundle copy of this module must not guard (and report) the same provider twice.
+      if (prop === OWN_PROVIDER) return true;
+      const value = Reflect.get(target, prop, receiver) as unknown;
+      if (typeof value !== "function" || NON_MODEL_MEMBERS.has(prop)) return value;
+      return withGuardedMemberProps(
+        (...args: unknown[]): unknown => {
+          const m = (value as (...a: unknown[]) => unknown).apply(target, args);
+          return m !== null && typeof m === "object" ? guardModel(m, bareViaOf(args)) : m;
+        },
+        value,
+        String(prop),
+      );
+    },
+  });
+}
 
 /** Static defaults for one routed slot — mirrors what a plain string config said. */
 export interface GatewayRoutedDefaults {
-  /** Default gateway model id (what unrouted channels use), e.g. "zai/glm-5.2". */
+  /** Default gateway model id (what unrouted channels use), e.g. "openai/gpt-6-luna". */
   readonly id: string;
+  /** The `models.targets` entry the role's calls go through (OPE-2556). A route's own `via` wins. Absent: `gateway`. */
+  readonly via?: string;
   /**
    * Gateway providerOptions applied when the CALL carries none — a floor, since turn calls carry their own.
    * Any gateway option is forwarded verbatim; this mapping has no allow-list of keys.
@@ -98,7 +511,8 @@ const PIN_KEYS = ["only", "order"] as const;
 
 /**
  * Map a route's provider hints onto one call's gateway options. Pure. A MODEL CHANGE strips the pin keys — a
- * pin set for one model is broken for another — and a route's `providers` becomes `order`, never `only`.
+ * pin set for one model is broken for another — and a route's `providerOrder` becomes `order`, never `only`. The
+ * target's own rows (`providers.only`, `providers.order`, `options`) join later, on every call (`withTargetRows`).
  */
 export function applyGatewayOptions(
   route: ModelRoute,
@@ -112,8 +526,8 @@ export function applyGatewayOptions(
     gatewayOpts = { ...base };
     for (const k of PIN_KEYS) delete gatewayOpts[k];
   }
-  if (route.providers !== undefined) {
-    gatewayOpts = { ...(gatewayOpts ?? {}), order: [...route.providers] };
+  if (route.providerOrder !== undefined) {
+    gatewayOpts = { ...(gatewayOpts ?? {}), order: [...route.providerOrder] };
     delete gatewayOpts["only"];
   }
   if (gatewayOpts === undefined) return options;
@@ -122,14 +536,14 @@ export function applyGatewayOptions(
 
 /** A gateway TRANSCRIPTION model, on the same provider (retarget and host-plane fetch included) the turn
  *  model uses. The meeting bot's `gateway` route (meeting-gateway.ts) reads it. */
-export function gatewayTranscriptionModel(id: string): ReturnType<typeof provider.transcriptionModel> {
-  return provider.transcriptionModel(id);
+export function gatewayTranscriptionModel(id: string): ReturnType<GatewayProvider["transcriptionModel"]> {
+  return policyModel(targetProvider(DEFAULT_MODEL_VIA).transcriptionModel(id));
 }
 
-/** The gateway ModelBackend (see core ModelBackend). */
-export function gatewayModelBackend(defaults?: Record<string, unknown>): ModelBackend<GatewayModel> {
+/** The gateway ModelBackend (see core ModelBackend). `via` is the role's target; a route's own `via` wins. */
+export function gatewayModelBackend(defaults?: Record<string, unknown>, via?: string): ModelBackend<GatewayModel> {
   return {
-    model: (id) => provider(id),
+    model: (id, routeVia) => gatewayLanguageModel(id, routeVia ?? via),
     applyOptions: (route, options, ids) => applyGatewayOptions(route, options, ids, defaults),
   };
 }
@@ -139,7 +553,7 @@ export function gatewayModelBackend(defaults?: Record<string, unknown>): ModelBa
  * scope. It ALWAYS returns a model, never null, and `event` carries the turn id this ctx does not.
  */
 export function gatewayModelResolver(primary: GatewayRoutedDefaults): (event: unknown, ctx: unknown) => Promise<GatewayModel> {
-  const deps = { ...liveIdentity, backend: gatewayModelBackend(primary.gateway) };
+  const deps = { ...liveIdentity, backend: gatewayModelBackend(primary.gateway, primary.via) };
   return (event, ctx) => resolvePrimaryModel(ctx as BindableContext, { primary: { id: primary.id } }, deps, event);
 }
 

package/agent/model/meeting-gateway.ts

@@ -1,5 +1,7 @@
-// The meeting bot's two model calls (OPE-2459): the `gateway` transcription route, and the recap completion.
-// Core owns both seams (meetings/transcription.ts); this file only fills them, so no meeting code calls a model SDK.
+// The meeting bot's two model calls (OPE-2459): the `gateway` transcription route, and the recap completion. Plus the
+// voice-clip transcriber (OPE-2524), which rides the same transcription role. Core owns every seam
+// (meetings/transcription.ts, channels/voice-clips.ts); this file only fills them, so no meeting or chat code calls a
+// model SDK.
 //
 // TRANSCRIPTION (OPE-2470): one audio chunk per call, along the STACK'S TRANSCRIPTION ROLE — a primary route and a
 // fallback route (transcription-routes.ts), named per stack in the app's `agent/model/stacks.ts`. A provider outage
@@ -10,12 +12,23 @@
 // LEGACY: `registerGatewayMeetingModels(defaults)` with no role keeps the one-model route on the policy's
 // `transcription.model`, for an app that has no transcription role yet.
 //
+// VOICE CLIPS (OPE-2524): a chat message's voice clip rides the SAME role, through {@link voiceClipTranscriber}. A
+// clip is one call, like one meeting chunk, so it gets the same primary, the same fallback and the same timeouts.
+//
 // RECAP: one tool-less completion on the scope's `utility` route — the same route and call shape the dream
 // judge uses. The prompt carries the fenced, untrusted transcript (core meetings/recap.ts).
 
-import { experimental_transcribe as transcribe, generateText, gateway } from "ai";
-import { registerMeetingCompletion, registerTranscriptionRoute, type MeetingCompletion, type TranscriptionInput, type TranscriptionRoute } from "@open-everywhere/core/agent/adapter-api.js";
-import { gatewayTranscriptionModel, type GatewayRoutedDefaults } from "./gateway.js";
+import { experimental_transcribe as transcribe, generateText } from "ai";
+import {
+  registerMeetingCompletion,
+  registerTranscriptionRoute,
+  registerVoiceTranscriber,
+  type MeetingCompletion,
+  type TranscriptionInput,
+  type TranscriptionRoute,
+  type VoiceTranscriber,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { gatewayLanguageModel, gatewayTranscriptionModel, type GatewayRoutedDefaults } from "./gateway.js";
 import { resolvedDreamCallSettings } from "./dream-judge.js";
 import { roleDisclosure, transcribeWithFallback, type RoleTranscript, type TranscriptionDeps, type TranscriptionRoleSpec } from "./transcription-routes.js";
 
@@ -65,11 +78,24 @@ export function stackTranscriptionRoute(role: TranscriptionRoleSpec, deps: Trans
   };
 }
 
+/**
+ * The voice-clip transcriber (core channels/voice-clips.ts) on the stack's transcription role. The spend row names the
+ * model of the route that ANSWERED, so a fall-through bills under the fallback's model and not the primary's.
+ */
+export function voiceClipTranscriber(role: TranscriptionRoleSpec, deps: TranscriptionDeps = {}): VoiceTranscriber {
+  const run = transcribeWithFallback(role, deps);
+  return async (clip) => {
+    // The message's deadline rides as the CALLER's abort, so a call past it stops and does not start the fallback.
+    const r = await run({ audio: clip.audio, mediaType: clip.mediaType, ...(clip.abortSignal ? { abortSignal: clip.abortSignal } : {}) });
+    return { text: r.text, model: r.route.id, ...(r.costUsd !== undefined ? { costUsd: r.costUsd } : {}) };
+  };
+}
+
 function gatewayMeetingCompletion(defaults: GatewayRoutedDefaults): MeetingCompletion {
   return async (scope, prompt) => {
     const s = resolvedDreamCallSettings(scope, defaults);
     const { text } = await generateText({
-      model: gateway(s.id),
+      model: gatewayLanguageModel(s.id, s.via),
       prompt,
       ...(s.reasoning !== undefined ? { reasoning: s.reasoning } : {}),
       ...(s.providerOptions !== undefined ? { providerOptions: s.providerOptions as Parameters<typeof generateText>[0]["providerOptions"] } : {}),
@@ -80,9 +106,13 @@ function gatewayMeetingCompletion(defaults: GatewayRoutedDefaults): MeetingCompl
 
 /**
  * Boot registration from agent.ts, beside the dream judge: the recap rides the `utility` defaults, and the
- * transcription route rides the stack's transcription role when the app passes one.
+ * transcription route rides the stack's transcription role when the app passes one. The role ALSO registers the
+ * voice-clip transcriber (OPE-2524), so an app that already passes its role hears voice clips with no app change.
  */
 export function registerGatewayMeetingModels(defaults: GatewayRoutedDefaults, transcription?: TranscriptionRoleSpec): void {
   registerTranscriptionRoute(transcription === undefined ? gatewayTranscriptionRoute() : stackTranscriptionRoute(transcription));
+  // Voice clips need the role: the legacy one-model route reads its model from the MEETING policy, and a chat message
+  // has no meeting policy. With no role, no transcriber registers, and a clip reaches the agent as unheard.
+  if (transcription !== undefined) registerVoiceTranscriber(voiceClipTranscriber(transcription));
   registerMeetingCompletion(gatewayMeetingCompletion(defaults));
 }