@open-everywhere/adapters 0.1.3 → 0.1.4

package/agent/model/gateway-probe.ts

@@ -0,0 +1,100 @@
+// THE MODEL-ROUTE PROBE (OPE-2230) — the live half of the deployment-status surface's
+// `model-route` requirement (`@open-everywhere/core/agent/ops/status.ts`).
+//
+// IT LIVES HERE because the gateway's URL is a VENDOR BINDING, and core carries none. Core defines
+// the seam (`registerStatusProbe`); the app's boot wiring calls `registerGatewayRouteProbe()`.
+//
+// 🔴 WHAT IT MEASURES, AND WHAT IT DOES NOT. Two cheap facts:
+//
+//   ① CREDENTIAL POSTURE, from env alone. On Vercel a deployed project authenticates to the
+//      gateway with OIDC and there is no key to hold, so the posture is satisfied by the platform.
+//      Off Vercel it needs `AI_GATEWAY_API_KEY`.
+//   ② REACHABILITY, from one GET of the gateway's PUBLIC model catalog — the same unauthenticated
+//      endpoint `scripts/seed-model-catalog-cache.ts` reads.
+//
+// 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
+// field that is read as more than it measured is worse than no field.
+//
+// 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";
+
+/** 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";
+
+/** How long the probe waits before it calls the gateway unreachable. */
+export const GATEWAY_PROBE_TIMEOUT_MS = 2_000;
+
+/**
+ * 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.
+ */
+export function gatewayCatalogUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.OE_AI_GATEWAY_URL?.trim();
+  if (!override) return GATEWAY_CATALOG_URL;
+  try {
+    return `${new URL(override).origin}/v1/models/catalog`;
+  } catch {
+    // An unparseable override is the operator's problem, and the probe is not where it should
+    // surface: fall back to the default target rather than answer a misleading "unreachable".
+    return GATEWAY_CATALOG_URL;
+  }
+}
+
+export interface GatewayProbeDeps {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly fetchImpl?: typeof globalThis.fetch;
+  readonly vercel?: boolean;
+}
+
+/** Run the probe once. Exported so a test drives every arm with no network. */
+export async function probeGatewayRoute(deps: GatewayProbeDeps = {}): Promise<ProbeAnswer> {
+  const env = deps.env ?? process.env;
+  const vercel = deps.vercel ?? onVercel();
+  const keySet = (env.AI_GATEWAY_API_KEY ?? "").trim().length > 0;
+  // 🔴 A RETARGETED GATEWAY IS NOT MEASURABLE BY THIS PROBE, so it reads "unknown" and never "no".
+  // The deployment contract blesses `OE_AI_GATEWAY_URL` pointed at a compatible relay, and a relay
+  // 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;
+  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: "no", detail: "no gateway credential: off Vercel the deployment needs AI_GATEWAY_API_KEY (on Vercel, OIDC authenticates it)" };
+  }
+  const credential = vercel ? "OIDC on Vercel" : "AI_GATEWAY_API_KEY";
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const controller = new AbortController();
+  const fuse = setTimeout(() => controller.abort(), GATEWAY_PROBE_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(gatewayCatalogUrl(env), { method: "GET", signal: controller.signal });
+    if (!res.ok) {
+      // A 404 or 405 from a RETARGETED gateway means "this endpoint is not served here", which is a
+      // fact about the catalog route and not about the model route. Anything else — a 5xx, a 401 —
+      // is the relay failing, and stays a "no".
+      if (retargeted && (res.status === 404 || res.status === 405)) {
+        return { met: "unknown", detail: `the retargeted model gateway does not serve a model catalog (HTTP ${res.status}), so reachability was not measured; the credential posture is ${credential}` };
+      }
+      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`,
+    };
+  } catch {
+    return { met: "no", detail: `the model gateway did not answer within ${GATEWAY_PROBE_TIMEOUT_MS} ms; the credential posture is ${credential}` };
+  } finally {
+    clearTimeout(fuse);
+  }
+}
+
+/** Wire the probe into the deployment-status surface. Called once, from the app's boot wiring. */
+export function registerGatewayRouteProbe(): void {
+  registerStatusProbe("model-route", () => probeGatewayRoute());
+}

package/dist/agent/model/gateway-probe.d.ts

@@ -0,0 +1,21 @@
+import { type ProbeAnswer } from "@open-everywhere/core/agent/adapter-api.js";
+/** The gateway's PUBLIC, unauthenticated model catalog — eve's own `AI_GATEWAY_MODELS_CATALOG_URL`. */
+export declare const GATEWAY_CATALOG_URL = "https://ai-gateway.vercel.sh/v1/models/catalog";
+/** How long the probe waits before it calls the gateway unreachable. */
+export declare const GATEWAY_PROBE_TIMEOUT_MS = 2000;
+/**
+ * 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.
+ */
+export declare function gatewayCatalogUrl(env?: NodeJS.ProcessEnv): string;
+export interface GatewayProbeDeps {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly fetchImpl?: typeof globalThis.fetch;
+    readonly vercel?: boolean;
+}
+/** Run the probe once. Exported so a test drives every arm with no network. */
+export declare function probeGatewayRoute(deps?: GatewayProbeDeps): Promise<ProbeAnswer>;
+/** Wire the probe into the deployment-status surface. Called once, from the app's boot wiring. */
+export declare function registerGatewayRouteProbe(): void;
+//# sourceMappingURL=gateway-probe.d.ts.map

package/dist/agent/model/gateway-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-probe.d.ts","sourceRoot":"","sources":["../../../agent/model/gateway-probe.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAE7G,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,mDAAmD,CAAC;AAEpF,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAU9E;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,+EAA+E;AAC/E,wBAAsB,iBAAiB,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAwCzF;AAED,kGAAkG;AAClG,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/agent/model/gateway-probe.js

@@ -0,0 +1,93 @@
+// THE MODEL-ROUTE PROBE (OPE-2230) — the live half of the deployment-status surface's
+// `model-route` requirement (`@open-everywhere/core/agent/ops/status.ts`).
+//
+// IT LIVES HERE because the gateway's URL is a VENDOR BINDING, and core carries none. Core defines
+// the seam (`registerStatusProbe`); the app's boot wiring calls `registerGatewayRouteProbe()`.
+//
+// 🔴 WHAT IT MEASURES, AND WHAT IT DOES NOT. Two cheap facts:
+//
+//   ① CREDENTIAL POSTURE, from env alone. On Vercel a deployed project authenticates to the
+//      gateway with OIDC and there is no key to hold, so the posture is satisfied by the platform.
+//      Off Vercel it needs `AI_GATEWAY_API_KEY`.
+//   ② REACHABILITY, from one GET of the gateway's PUBLIC model catalog — the same unauthenticated
+//      endpoint `scripts/seed-model-catalog-cache.ts` reads.
+//
+// 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
+// field that is read as more than it measured is worse than no field.
+//
+// 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 } from "@open-everywhere/core/agent/adapter-api.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";
+/** How long the probe waits before it calls the gateway unreachable. */
+export const GATEWAY_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * 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.
+ */
+export function gatewayCatalogUrl(env = process.env) {
+    const override = env.OE_AI_GATEWAY_URL?.trim();
+    if (!override)
+        return GATEWAY_CATALOG_URL;
+    try {
+        return `${new URL(override).origin}/v1/models/catalog`;
+    }
+    catch {
+        // An unparseable override is the operator's problem, and the probe is not where it should
+        // surface: fall back to the default target rather than answer a misleading "unreachable".
+        return GATEWAY_CATALOG_URL;
+    }
+}
+/** Run the probe once. Exported so a test drives every arm with no network. */
+export async function probeGatewayRoute(deps = {}) {
+    const env = deps.env ?? process.env;
+    const vercel = deps.vercel ?? onVercel();
+    const keySet = (env.AI_GATEWAY_API_KEY ?? "").trim().length > 0;
+    // 🔴 A RETARGETED GATEWAY IS NOT MEASURABLE BY THIS PROBE, so it reads "unknown" and never "no".
+    // The deployment contract blesses `OE_AI_GATEWAY_URL` pointed at a compatible relay, and a relay
+    // 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;
+    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: "no", detail: "no gateway credential: off Vercel the deployment needs AI_GATEWAY_API_KEY (on Vercel, OIDC authenticates it)" };
+    }
+    const credential = vercel ? "OIDC on Vercel" : "AI_GATEWAY_API_KEY";
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const controller = new AbortController();
+    const fuse = setTimeout(() => controller.abort(), GATEWAY_PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetchImpl(gatewayCatalogUrl(env), { method: "GET", signal: controller.signal });
+        if (!res.ok) {
+            // A 404 or 405 from a RETARGETED gateway means "this endpoint is not served here", which is a
+            // fact about the catalog route and not about the model route. Anything else — a 5xx, a 401 —
+            // is the relay failing, and stays a "no".
+            if (retargeted && (res.status === 404 || res.status === 405)) {
+                return { met: "unknown", detail: `the retargeted model gateway does not serve a model catalog (HTTP ${res.status}), so reachability was not measured; the credential posture is ${credential}` };
+            }
+            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`,
+        };
+    }
+    catch {
+        return { met: "no", detail: `the model gateway did not answer within ${GATEWAY_PROBE_TIMEOUT_MS} ms; the credential posture is ${credential}` };
+    }
+    finally {
+        clearTimeout(fuse);
+    }
+}
+/** Wire the probe into the deployment-status surface. Called once, from the app's boot wiring. */
+export function registerGatewayRouteProbe() {
+    registerStatusProbe("model-route", () => probeGatewayRoute());
+}
+//# sourceMappingURL=gateway-probe.js.map

package/dist/agent/model/gateway-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-probe.js","sourceRoot":"","sources":["../../../agent/model/gateway-probe.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-everywhere/adapters",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Open Everywhere adapters — the reference Vercel-hosted backends: AI Gateway models and pricing, Sandbox, Blob, Neon, OpenTelemetry, AWS and Okta.",
   "keywords": [
     "agent",
@@ -105,6 +105,10 @@
       "types": "./dist/agent/model/dream-judge.d.ts",
       "default": "./dist/agent/model/dream-judge.js"
     },
+    "./agent/model/gateway-probe.js": {
+      "types": "./dist/agent/model/gateway-probe.d.ts",
+      "default": "./dist/agent/model/gateway-probe.js"
+    },
     "./agent/model/gateway-vision.js": {
       "types": "./dist/agent/model/gateway-vision.d.ts",
       "default": "./dist/agent/model/gateway-vision.js"
@@ -167,7 +171,7 @@
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "npm run test:chain",
-    "test:chain": "npm run test:instrumentation && npm run test:sandbox-lifecycle && npm run test:sandbox-guard && npm run test:sandbox-extend && npm run test:model-gateway && npm run test:dream-judge-gateway && npm run test:approval-judge-gateway && npm run test:gateway-vision && npm run test:oe-oauth && npm run test:oe-oauth-static && npm run test:agent-browser && npm run test:neon-pool-error && npm run test:aws-adapter && npm run test:aws-sso && npm run test:okta-directory",
+    "test:chain": "npm run test:instrumentation && npm run test:sandbox-lifecycle && npm run test:sandbox-guard && npm run test:sandbox-extend && npm run test:model-gateway && npm run test:gateway-probe && npm run test:dream-judge-gateway && npm run test:approval-judge-gateway && npm run test:gateway-vision && npm run test:oe-oauth && npm run test:oe-oauth-static && npm run test:agent-browser && npm run test:neon-pool-error && npm run test:aws-adapter && npm run test:aws-sso && npm run test:okta-directory",
     "test:aws-adapter": "tsx scripts/aws-adapter-test.ts",
     "test:okta-directory": "tsx scripts/okta-directory-test.ts",
     "test:aws-sso": "tsx scripts/aws-sso-test.ts",
@@ -180,6 +184,7 @@
     "test:sandbox-guard": "tsx scripts/sandbox-live-guard-test.ts",
     "test:sandbox-live": "tsx scripts/sandbox-live-test.ts",
     "test:sandbox-extend": "tsx scripts/sandbox-extend-test.ts",
+    "test:gateway-probe": "NODE_NO_WARNINGS=1 tsx scripts/gateway-probe-test.ts",
     "test:model-gateway": "tsx scripts/model-gateway-test.ts",
     "test:dream-judge-gateway": "tsx scripts/dream-judge-gateway-test.ts",
     "test:approval-judge-gateway": "tsx scripts/approval-judge-gateway-test.ts",
@@ -187,7 +192,7 @@
   },
   "dependencies": {
     "@neondatabase/serverless": "^1.1.0",
-    "@open-everywhere/core": "0.1.3",
+    "@open-everywhere/core": "0.1.4",
     "@vercel/blob": "^2.6.1",
     "@vercel/otel": "^2.1.3",
     "@vercel/sandbox": "^3.2.1",