@open-everywhere/adapters 0.7.0 → 0.8.0

package/agent/aws/sso.ts

@@ -18,8 +18,6 @@ import { makePkce, makeState } from "../oe-oauth/pkce.js";
 /** A `fetch`-shaped transport — the DI seam the offline test injects (defaults to global fetch). */
 export type FetchLike = typeof fetch;
 
-// Core owns the canonical const; re-exported here so this module's existing consumers keep resolving it.
-export { OE_AWS_SSO_CALLBACK_PATH };
 
 /** Default OAuth scopes for the Identity Center link. `openid` is LOAD-BEARING, not decoration: it is
  *  what makes the token response carry an id-token, and the id-token's `sub` is the only statement of

package/agent/instrumentation.ts

@@ -10,14 +10,16 @@
 //     every environment. Without it, eve records content for public conversations and in
 //     development. A destination cannot restore what this ceiling removes.
 //   - `otlpDestination` (the app's `otlp` slot): the consumer's OTLP collector, from the standard
-//     `OTEL_EXPORTER_OTLP_*` variables, as an eve destination. With no endpoint it is disabled.
+//     `OTEL_EXPORTER_OTLP_*` variables, and Vercel's OTel collector, from the `VERCEL_OTEL_ENDPOINTS*`
+//     variables the platform sets, as one eve destination. With neither, it is disabled.
 //
 // `scripts/instrumentation-hosted-boot-test.ts` boots both slots through eve's registration path
 // with the env Vercel creates.
 
 import { disableInstrumentation } from "eve/instrumentation";
-import { otel, otelIntegration, type OtelDeclaration, type SpanExporter } from "eve/instrumentation/otel";
+import { otel, otelIntegration, type OtelDeclaration, type SpanExporter, type SpanProcessor } from "eve/instrumentation/otel";
 import { OTLPHttpJsonTraceExporter, OTLPHttpProtoTraceExporter } from "@vercel/otel";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { installLogShipping, initTelemetry } from "@open-everywhere/core/agent/adapter-api.js";
 
 /** Metadata only: emit the span, record neither content direction. */
@@ -95,7 +97,68 @@ function otlpExporter(target: OtlpTarget): SpanExporter {
   return target.protocol === "http/json" ? new OTLPHttpJsonTraceExporter(config) : new OTLPHttpProtoTraceExporter(config);
 }
 
+/**
+ * Vercel's OTel collector (OPE-2358). On Vercel, an OpenTelemetry integration from the Vercel
+ * Marketplace receives spans through a collector on the function's own host. The platform names it
+ * with `VERCEL_OTEL_ENDPOINTS`, `VERCEL_OTEL_ENDPOINTS_PORT` and `VERCEL_OTEL_ENDPOINTS_PROTOCOL`.
+ * `registerOTel`'s `"auto"` span processor exported to it; eve's pipeline passes no `"auto"`, so
+ * this destination replaces it. The URL shape, the port default and the protocol rule are
+ * `@vercel/otel`'s own: `http/protobuf` selects protobuf and every other value selects JSON.
+ * `undefined` when the platform set no collector.
+ */
+export function resolveVercelCollectorTarget(env: NodeJS.ProcessEnv = process.env): OtlpTarget | undefined {
+  if (!env.VERCEL_OTEL_ENDPOINTS) return undefined;
+  const port = env.VERCEL_OTEL_ENDPOINTS_PORT || "4318";
+  const protocol: OtlpProtocol = (env.VERCEL_OTEL_ENDPOINTS_PROTOCOL || "http/protobuf") === "http/protobuf" ? "http/protobuf" : "http/json";
+  return { url: `http://localhost:${port}/v1/traces`, protocol, headers: {} };
+}
+
+/** The key under which the Vercel runtime publishes the current request's context. */
+const VERCEL_REQUEST_CONTEXT = Symbol.for("@vercel/request-context");
+
+interface VercelRequestContext {
+  readonly telemetry?: { readonly traceDrains?: readonly unknown[] };
+}
+
+/**
+ * True when the current Vercel request reports trace drains. The runtime then delivers spans to
+ * those drains itself, from eve's Agent Runs export (`telemetry.reportSpans`), so the collector
+ * would deliver every span a second time. `@vercel/otel` skips its collector on the same signal.
+ * An app that turns Agent Runs off then sends nothing to its trace drains; this destination does not
+ * cover that case.
+ */
+export function vercelTraceDrainsConfigured(): boolean {
+  const store = (globalThis as Record<symbol, { get?: () => VercelRequestContext | undefined } | undefined>)[VERCEL_REQUEST_CONTEXT];
+  return (store?.get?.()?.telemetry?.traceDrains?.length ?? 0) > 0;
+}
+
+/** Wrap the collector's processor so that it skips every span while trace drains are configured. */
+function skipWhenTraceDrains(inner: BatchSpanProcessor): SpanProcessor {
+  return {
+    onStart: (span, context) => {
+      if (!vercelTraceDrainsConfigured()) inner.onStart(span as never, context as never);
+    },
+    onEnd: (span) => {
+      if (!vercelTraceDrainsConfigured()) inner.onEnd(span as never);
+    },
+    forceFlush: () => inner.forceFlush(),
+    shutdown: () => inner.shutdown(),
+  };
+}
+
 const OTLP_TARGET = resolveOtlpTarget();
+const VERCEL_COLLECTOR_TARGET = resolveVercelCollectorTarget();
 
-/** The consumer's OTLP collector as an eve destination, or disabled when no endpoint is set. */
-export const otlpDestination = OTLP_TARGET === undefined ? disableInstrumentation() : otelIntegration({ traceExporter: otlpExporter(OTLP_TARGET) });
+/**
+ * The consumer's OTLP collector and Vercel's OTel collector, as ONE eve destination: the `otlp` slot
+ * file every app already has carries both, so a scaffolded app needs no new file. Disabled when
+ * neither is configured. Both obey the `otel` slot's trace policy.
+ */
+export const otlpDestination =
+  OTLP_TARGET === undefined && VERCEL_COLLECTOR_TARGET === undefined
+    ? disableInstrumentation()
+    : otelIntegration({
+        ...(OTLP_TARGET === undefined ? {} : { traceExporter: otlpExporter(OTLP_TARGET) }),
+        spanProcessors:
+          VERCEL_COLLECTOR_TARGET === undefined ? [] : [skipWhenTraceDrains(new BatchSpanProcessor(otlpExporter(VERCEL_COLLECTOR_TARGET) as never))],
+      });

package/agent/model/approval-judge.ts

@@ -1,13 +1,13 @@
 // Gateway transport for the approval judge — core owns the seam; this owns the vendor call on the fixed
 // `judge` model role. NO scope routing: the judge must not inherit whatever a domain routed its seat onto.
 
-import { gateway, generateText } from "ai";
+import { generateText } from "ai";
 import {
   type ApprovalJudgeCompletion,
   type JudgePass,
   registerApprovalJudgeCompletion,
 } from "@open-everywhere/core/agent/adapter-api.js";
-import { applyGatewayOptions, type GatewayRoutedDefaults } from "./gateway.js";
+import { applyGatewayOptions, gatewayLanguageModel, type GatewayRoutedDefaults } from "./gateway.js";
 
 /**
  * Output budget for the scrutiny pass. A reasoning model spends reasoning tokens INSIDE the budget, so a
@@ -37,7 +37,7 @@ function gatewayApprovalJudgeCompletion(defaults: GatewayRoutedDefaults): Approv
   return async (prompt, pass) => {
     const s = approvalJudgeCallSettings(pass, defaults);
     const { text } = await generateText({
-      model: gateway(s.id),
+      model: gatewayLanguageModel(s.id, defaults.via),
       prompt,
       ...(s.maxOutputTokens !== undefined ? { maxOutputTokens: s.maxOutputTokens } : {}),
       ...(s.providerOptions !== undefined

package/agent/model/dream-judge.ts

@@ -1,7 +1,7 @@
 // Gateway transport for the dream judge — core owns the seam; this owns one completion on the `utility`
 // role. The SCOPE locates the route: a channel key, a silo's owning domain, else `org`. It FAILS QUIET.
 
-import { gateway, generateText } from "ai";
+import { generateText } from "ai";
 import {
   type ModelRoute,
   modelRouteFor,
@@ -16,7 +16,7 @@ import {
   registerFailureFacetJudge,
   stampModelCall,
 } from "@open-everywhere/core/agent/adapter-api.js";
-import { applyGatewayOptions, type GatewayRoutedDefaults } from "./gateway.js";
+import { applyGatewayOptions, gatewayLanguageModel, type GatewayRoutedDefaults } from "./gateway.js";
 
 /**
  * The effective `utility` route for a dream scope (channel key | silo name | other).
@@ -47,10 +47,12 @@ export function utilityRouteForScope(scope: string): ModelRoute {
 export function dreamCallSettings(
   route: ModelRoute,
   defaults: GatewayRoutedDefaults,
-): { id: string; reasoning?: ModelRoute["reasoning"]; providerOptions?: Record<string, unknown> } {
+): { id: string; via?: string; reasoning?: ModelRoute["reasoning"]; providerOptions?: Record<string, unknown> } {
   const id = route.id ?? defaults.id;
   const options = applyGatewayOptions(route, {}, { id, defaultId: defaults.id }, defaults.gateway);
-  return { id, reasoning: route.reasoning, providerOptions: options.providerOptions };
+  // The route's `via` wins over the role's (OPE-2556); absent both, the adapter uses the `gateway` target.
+  const via = route.via ?? defaults.via;
+  return { id, ...(via !== undefined ? { via } : {}), reasoning: route.reasoning, providerOptions: options.providerOptions };
 }
 
 /**
@@ -60,7 +62,7 @@ export function dreamCallSettings(
 export function resolvedDreamCallSettings(
   scope: string,
   defaults: GatewayRoutedDefaults,
-): { id: string; reasoning?: ModelRoute["reasoning"]; providerOptions?: Record<string, unknown> } {
+): { id: string; via?: string; reasoning?: ModelRoute["reasoning"]; providerOptions?: Record<string, unknown> } {
   const s = dreamCallSettings(utilityRouteForScope(scope), defaults);
   stampModelCall(s.id);
   return s;
@@ -71,7 +73,7 @@ function gatewayDreamCompletion(defaults: GatewayRoutedDefaults): DreamCompletio
   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

package/agent/model/gateway-probe.ts

@@ -12,6 +12,12 @@
 //   ② REACHABILITY, from one GET of the gateway's PUBLIC model catalog — the same unauthenticated
 //      endpoint `scripts/seed-model-catalog-cache.ts` reads.
 //
+//   ③ THE MODEL CONFIG (OPE-2556), when the app registered its models: one GET of the public
+//      `/v1/models/<id>/endpoints` read per model, judged against `models.targets` and `models.dataPolicy`
+//      (model-config-check.ts). A demand no provider can meet turns the row "no". The route is public, so the
+//      detail names no model, provider or target, and counts nothing. The answer is cached for ten minutes, so an
+//      anonymous caller cannot make the route fan out a read per request.
+//
 // It does NOT prove the deployment's credential is ACCEPTED: the only call that proves that is an
 // inference call, which is neither cheap nor free, and a status route an unbounded caller can poke
 // must not be able to spend money. The detail string says so in as many words, because a status
@@ -20,7 +26,17 @@
 // FAIL-SOFT and BOUNDED: a 2-second abort, and any throw answers "no" with no vendor error text
 // forwarded (a fetch failure's message carries the host, and the status route is public).
 
-import { registerStatusProbe, onVercel, type ProbeAnswer } from "@open-everywhere/core/agent/adapter-api.js";
+import {
+  DEFAULT_MODEL_VIA,
+  getSettings,
+  modelTargetFor,
+  registerStatusProbe,
+  onVercel,
+  type ProbeAnswer,
+  type ResolvableModel,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { checkModelConfig, type ConfigCheckResult } from "./model-config-check.js";
+import { targetBaseUrl } from "./target-url.js";
 
 /** The gateway's PUBLIC, unauthenticated model catalog — eve's own `AI_GATEWAY_MODELS_CATALOG_URL`. */
 export const GATEWAY_CATALOG_URL = "https://ai-gateway.vercel.sh/v1/models/catalog";
@@ -28,13 +44,19 @@ export const GATEWAY_CATALOG_URL = "https://ai-gateway.vercel.sh/v1/models/catal
 /** How long the probe waits before it calls the gateway unreachable. */
 export const GATEWAY_PROBE_TIMEOUT_MS = 2_000;
 
+/** The `gateway` target's base URL: `models.targets.gateway.url`, else the deprecated `OE_AI_GATEWAY_URL` in `env`. */
+function gatewayBaseUrl(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const targets = getSettings().models.targets;
+  return targetBaseUrl(DEFAULT_MODEL_VIA, modelTargetFor(DEFAULT_MODEL_VIA, targets), env);
+}
+
 /**
- * The catalog URL this deployment probes. `OE_AI_GATEWAY_URL` retargets the whole gateway (a relay,
- * an on-prem proxy, a fixture), and it names the CHAT base (`…/v4/ai`), so the catalog is taken
- * from its ORIGIN rather than appended to it.
+ * The catalog URL this deployment probes. The `gateway` target's url (or the deprecated `OE_AI_GATEWAY_URL`)
+ * retargets the whole gateway (a relay, an on-prem proxy, a fixture), and it names the CHAT base (`…/v4/ai`), so the
+ * catalog is taken from its ORIGIN rather than appended to it.
  */
 export function gatewayCatalogUrl(env: NodeJS.ProcessEnv = process.env): string {
-  const override = env.OE_AI_GATEWAY_URL?.trim();
+  const override = gatewayBaseUrl(env);
   if (!override) return GATEWAY_CATALOG_URL;
   try {
     return `${new URL(override).origin}/v1/models/catalog`;
@@ -49,6 +71,65 @@ export interface GatewayProbeDeps {
   readonly env?: NodeJS.ProcessEnv;
   readonly fetchImpl?: typeof globalThis.fetch;
   readonly vercel?: boolean;
+  /** The models to run the config check on. Absent: the registered list, else no config check. */
+  readonly models?: () => readonly ResolvableModel[];
+  /** The config-check cache. Absent: the module's own. */
+  readonly cache?: ConfigCheckCache;
+  readonly now?: () => number;
+}
+
+/** How long one config-check answer is reused. */
+const MODEL_CONFIG_CHECK_TTL_MS = 10 * 60_000;
+
+/** A one-entry cache of the last config-check answer. */
+export interface ConfigCheckCache {
+  value?: { readonly at: number; readonly result: ConfigCheckResult };
+}
+const CONFIG_CHECK_CACHE: ConfigCheckCache = {};
+
+let registeredModels: (() => readonly ResolvableModel[]) | undefined;
+
+/**
+ * Register the models the deployment can resolve, so the `model-route` probe also runs the live config check.
+ * Called once from the app's boot wiring, beside the other registrations.
+ */
+export function registerModelConfigCheck(models: () => readonly ResolvableModel[]): void {
+  registeredModels = models;
+}
+
+/** The config-check answer in closed-vocabulary words, for the PUBLIC status route. Pure. */
+function publicConfigWords(r: ConfigCheckResult): string {
+  if (r.met === "no") return "the model config has a models.dataPolicy, providers.only or target dataPolicy demand that no provider can serve for at least one model — run `npm run check:model-config` for the names";
+  // An unused `providers.only` name is a warning on a config that was fully measured: say so, not "not measured".
+  if (r.met === "unknown" && r.findings.every((f) => f.row.endsWith(".providers.only"))) {
+    return "the model config can be served; a providers.only name serves none of the checked models — run `npm run check:model-config` for the names";
+  }
+  if (r.met === "unknown") return "the model config was not fully measured — run `npm run check:model-config` for the details";
+  return "the model config can be served";
+}
+
+/** Run the config check, or reuse an answer younger than {@link MODEL_CONFIG_CHECK_TTL_MS}. Never throws. */
+async function cachedConfigCheck(deps: GatewayProbeDeps, models: () => readonly ResolvableModel[]): Promise<ConfigCheckResult> {
+  const cache = deps.cache ?? CONFIG_CHECK_CACHE;
+  const now = (deps.now ?? Date.now)();
+  if (cache.value !== undefined && now - cache.value.at < MODEL_CONFIG_CHECK_TTL_MS) return cache.value.result;
+  const env = deps.env ?? process.env;
+  let result: ConfigCheckResult;
+  try {
+    const settings = getSettings().models;
+    result = await checkModelConfig({
+      models: models(),
+      targets: settings.targets,
+      policy: settings.dataPolicy,
+      baseUrlFor: (via) => targetBaseUrl(via, modelTargetFor(via, settings.targets), env),
+      timeoutMs: GATEWAY_PROBE_TIMEOUT_MS,
+      ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+    });
+  } catch {
+    result = { met: "unknown", findings: [{ met: "unknown", row: "config", detail: "the model config could not be read" }], checked: 0 };
+  }
+  cache.value = { at: now, result };
+  return result;
 }
 
 /** Run the probe once. Exported so a test drives every arm with no network. */
@@ -61,10 +142,10 @@ export async function probeGatewayRoute(deps: GatewayProbeDeps = {}): Promise<Pr
   // owes nobody a model catalog and may need no key of ours. Both of this probe's facts are then
   // about the shipped Vercel gateway, not about the route the deployment actually uses — and
   // "measured, and it does not hold" would be false for a deployment whose models route fine.
-  const retargeted = (env.OE_AI_GATEWAY_URL ?? "").trim().length > 0;
+  const retargeted = gatewayBaseUrl(env) !== undefined;
   if (!vercel && !keySet) {
     if (retargeted) {
-      return { met: "unknown", detail: "the model route is retargeted by OE_AI_GATEWAY_URL and holds no AI_GATEWAY_API_KEY — a relay may need neither, so this was not measured" };
+      return { met: "unknown", detail: "the model route is retargeted (models.targets.gateway.url) and holds no AI_GATEWAY_API_KEY — a relay may need neither, so this was not measured" };
     }
     return { met: "no", detail: "no gateway credential: off Vercel the deployment needs AI_GATEWAY_API_KEY (on Vercel, OIDC authenticates it)" };
   }
@@ -83,10 +164,15 @@ export async function probeGatewayRoute(deps: GatewayProbeDeps = {}): Promise<Pr
       }
       return { met: "no", detail: `the model gateway answered HTTP ${res.status} to a catalog read; the credential posture is ${credential}` };
     }
-    return {
-      met: "yes",
-      detail: `the model gateway answered a catalog read and the credential posture is ${credential} — this does not prove an inference call is authorised`,
-    };
+    const reached = `the model gateway answered a catalog read and the credential posture is ${credential} — this does not prove an inference call is authorised`;
+    const models = deps.models ?? registeredModels;
+    if (models === undefined) return { met: "yes", detail: reached };
+    // ③ The config check. A demand no provider can meet makes the row "no": every call of that model would fail closed.
+    // An unknown part keeps "yes", because the route itself was measured, and the detail says what was not.
+    // 🔴 THE STATUS ROUTE IS PUBLIC, so the detail is closed-vocabulary prose: no model id, no provider slug, no target
+    // name and no count. `npm run check:model-config` names them, from the app.
+    const check = await cachedConfigCheck(deps, models);
+    return { met: check.met === "no" ? "no" : "yes", detail: `${reached}; ${publicConfigWords(check)}` };
   } catch {
     return { met: "no", detail: `the model gateway did not answer within ${GATEWAY_PROBE_TIMEOUT_MS} ms; the credential posture is ${credential}` };
   } finally {

package/agent/model/gateway-vision.ts

@@ -1,7 +1,9 @@
-// Gateway transport for the image describer — core owns the seam. Zero-data-retention is enforced AT THE
-// GATEWAY by org policy; the call is fail-closed, reports its own spend, and must NOT stamp the model.
+// Gateway transport for the image describer — core owns the seam. The model comes from gateway.ts, so the call
+// carries `models.dataPolicy` (OPE-2535); a gateway's own org policy applies on top. The call is fail-closed,
+// reports its own spend, and must NOT stamp the model.
 
-import { gateway, generateText } from "ai";
+import { generateText } from "ai";
+import { gatewayLanguageModel } from "./gateway.js";
 import {
   type ImageDescribeRequest,
   type ImageDescribeResult,
@@ -14,9 +16,11 @@ import {
 export interface GatewayVisionDefaults {
   /** Gateway vision model id, e.g. "alibaba/qwen3-vl-instruct". */
   readonly id: string;
+  /** The `models.targets` entry the call goes through (OPE-2556). Absent: `gateway`. */
+  readonly via?: string;
   /**
-   * providerOptions.gateway for the call, forwarded verbatim. Absent in the reference config: ZDR is the
-   * gateway's org policy now. A self-host wanting a per-call posture passes one here.
+   * providerOptions.gateway for the call, forwarded verbatim. Absent in the reference config. The deployment's
+   * `models.dataPolicy` rows ride the call whatever this holds, and win over it.
    */
   readonly gateway?: Record<string, unknown>;
 }
@@ -128,7 +132,7 @@ export function gatewayImageDescriber(defaults: GatewayVisionDefaults): ImageDes
       let res: { text: string } & VisionCallTelemetry;
       try {
         res = await generateText({
-          model: gateway(defaults.id),
+          model: gatewayLanguageModel(defaults.id, defaults.via),
           messages: [
             {
               role: "user",