failproofai 1.0.7-beta.2 → 1.0.8-beta.0

package/src/hooks/semantic/jev-client.ts

@@ -2,15 +2,33 @@
  * The client for Jev, and the provider layer that turns a customer's own
  * config (BYOK, `jev-config.ts`) into a transport.
  *
- * # Five routes, two wire shapes
+ * # Six routes, two wire shapes
  *
- * | Provider   | Endpoint                                              | Default model        |
- * |------------|-------------------------------------------------------|----------------------|
- * | typesafe   | `https://api.typesafe.ai/v1/systemone`                | `jev-1.13.0`         |
- * | openrouter | `https://openrouter.ai/api/v1/systemone`              | `typesafe/jev-1.13`  |
- * | vercel     | `https://ai-gateway.vercel.sh/typesafe/v1/systemone`  | `typesafe-ai/jev`    |
- * | cloudflare | `https://api.cloudflare.com/client/v4/accounts/<id>/ai/run` | `typesafe/jev` |
- * | custom     | `<baseUrl>/systemone`                                 | `jev-1.13.0`         |
+ * | Provider    | Endpoint                                              | Default model        |
+ * |-------------|-------------------------------------------------------|----------------------|
+ * | typesafe    | `https://api.typesafe.ai/v1/systemone`                | `jev-1.13.0`         |
+ * | openrouter  | `https://openrouter.ai/api/v1/systemone`              | `typesafe/jev-1.13`  |
+ * | vercel      | `https://ai-gateway.vercel.sh/typesafe/v1/systemone`  | `typesafe-ai/jev`    |
+ * | cloudflare  | `https://api.cloudflare.com/client/v4/accounts/<id>/ai/run` | `typesafe/jev` |
+ * | custom      | `<baseUrl>/systemone`                                 | `jev-1.13.0`         |
+ * | failproofai | `<Cloud origin>/enforcement/v1/jev/systemone`         | `jev-1.13.0`         |
+ *
+ * `failproofai` is FailproofAI Cloud: the machine's own Cloud key (the `jev`
+ * slot of `credentials.json`, see `jev-config.ts`) as the bearer, the org's
+ * plan allowance as the budget. The server forces `jev-1.13.0` and passes
+ * TypeSafe's answer through with its `model`, so this route accepts only a
+ * reported 1.13 model, never silence. Its documented statuses map like every
+ * other route's: 402 `{"error":"out_of_credits"}` → `out-of-credits` (the body
+ * never says "model execution failed"), 400/401/403/413/422/429/502/503 →
+ * `http-<status>`, and a redirect is refused. After a 429 the route sends
+ * nothing for as long as its `Retry-After` asks (capped; `cloudRetryAfter`).
+ *
+ * `baseUrl` is a BASE — the provider's version root — and `/systemone` is this
+ * file's own suffix (`nativeEndpoint`). Measured 2026-09-25, unauthenticated:
+ * `POST <base>/systemone` answers 403 / 401 / 400 / 401 on the four bases above
+ * and NEVER 404, so a 404 from it is evidence that the base is wrong rather
+ * than that the service is down — which is what `postJson` says when it sees
+ * one.
  *
  * TypeSafe, OpenRouter, Vercel and a custom URL all take TypeSafe's native body
  * `{model, state, questions}` and answer `{model, answers, usage}`, so one
@@ -25,6 +43,62 @@
  * Auth everywhere is `Authorization: Bearer <key>`. The key never appears in an
  * error message: provider error text is passed through with the key scrubbed.
  *
+ * # `GET <base>/models`: two shapes, and only one of them answers the question
+ *
+ * Measured 2026-09-25, unauthenticated except where noted:
+ *
+ * | base                                     | status | body                                                   |
+ * |------------------------------------------|--------|--------------------------------------------------------|
+ * | `https://api.typesafe.ai/v1`             | 403    | `{detail:{error_type,message}}`                        |
+ * | `https://openrouter.ai/api/v1`           | 200    | `{data:[{id,canonical_slug,name,…}]}` — OpenAI shape   |
+ * | `https://ai-gateway.vercel.sh/typesafe/v1` | 200  | `{models:[{name,description,release_date}]}` — TypeSafe shape |
+ * | a LiteLLM proxy (`…/typesafe/v1`)        | 401    | `{error:{message,type,param,code}}`                     |
+ * | the same proxy, with a key               | 200    | TypeSafe shape: `jev-latest`, `jev-preview`             |
+ *
+ * `readJevModelList` parses both shapes, and `parseJevModelList` reports "could
+ * not read the list" rather than throwing, because a proxy may serve neither.
+ *
+ * The two shapes do not mean the same thing, and only one of them may be used to
+ * REFUSE a model (`jev setup`, see `listDescribesSystemOne`):
+ *
+ * - The TypeSafe shape is the System One inventory of the base it was read from,
+ *   as ALIASES. Vercel's typesafe-scoped passthrough and a LiteLLM passthrough
+ *   both return it. It is not exhaustive: the models.aikin.club upstream lists
+ *   only `jev-latest` and `jev-preview`, yet its `/systemone` answers
+ *   `jev-1.13.0` (and "Unknown model" for `jev-1.13` or `jev-1.13.5`; measured
+ *   2026-09-27). So it may refuse an unlisted alias, never a versioned id.
+ * - The OpenAI shape is a gateway's chat-completions catalog, and demonstrably
+ *   does not enumerate `/systemone`: OpenRouter's 458-model catalog contains no
+ *   Jev entry of any spelling, while `POST https://openrouter.ai/api/v1/systemone`
+ *   exists (401, not 404) and this table addresses it as `typesafe/jev-1.13`. So
+ *   an OpenAI-shaped list is shown to a person and never used to refuse one.
+ *
+ * # Vercel names the same model twice, once per base
+ *
+ * `JEV_PROVIDER_DEFAULTS.vercel.model` is `typesafe-ai/jev` while Vercel's own
+ * `/typesafe/v1/models` calls it `jev`. Both are real, at two different bases
+ * (measured 2026-09-25):
+ *
+ * - `GET https://ai-gateway.vercel.sh/v1/models` — the gateway's own
+ *   OpenAI-shaped catalog, 390 models — carries exactly one match:
+ *   `{id: "typesafe-ai/jev", owned_by: "typesafe-ai", name: "Jev", type: "evaluation"}`.
+ *   `<owner>/<model>` is how that catalog addresses every model in it
+ *   (`alibaba/qwen-3-14b`, …), so the longer form is the GATEWAY-level id.
+ * - `GET https://ai-gateway.vercel.sh/typesafe/v1/models` — the typesafe-scoped
+ *   passthrough, which is the base we POST to — reports the provider-native
+ *   `jev`.
+ *
+ * Which one `POST /typesafe/v1/systemone` wants cannot be settled from outside:
+ * that route validates the BODY before the key (400 `model: Invalid input:
+ * expected string, received undefined` with no model, 401 `Authentication
+ * failed` with any model, valid or not), so an unauthenticated probe cannot
+ * distinguish a model it knows from one it does not. The default is therefore
+ * left as it is — it is what the route was configured and verified with — and
+ * `modelListHasModel` treats a listed `jev` as covering a configured
+ * `typesafe-ai/jev`, since Vercel's two catalogs differ by exactly that
+ * `<owner>/` prefix. Settling it needs one authenticated request with each
+ * spelling.
+ *
  * # Which Jev answered
  *
  * The decision thresholds were calibrated against Jev 1.13, so `readAnswers`
@@ -50,6 +124,14 @@
  * `cloudflare-error`, `cloudflare-incomplete`, `malformed`, `model-mismatch`,
  * `config`.
  *
+ * The CODE is the stable part — the activity store keeps a closed list of them
+ * (`JEV_REASON_CODE_LIST`, and its twin in `fpai-collect`) — so the provider's
+ * own sentence goes in the MESSAGE, which nothing parses.
+ * `providerErrorDetail` reads it out of whichever envelope arrived; all three
+ * observed shapes are in that comment, and one of them (TypeSafe's
+ * `{detail:{message}}`) used to be dropped on the floor, which is how "Must
+ * supply an API key!" reached a person as the bare words `HTTP 403`.
+ *
  * # When the provider refuses the call
  *
  * A refusal is not spread evenly over the traffic: the provider is likeliest to
@@ -91,8 +173,9 @@ import { JEV_REASON_PROVIDER_REFUSED } from "../jev-activity";
 import {
   CLOUDFLARE_ACCOUNT_ID_RE,
   isCalibratedJevModel,
+  isModelIdShaped,
   jevModelVersion,
-  validateJevConfig,
+  validateLoadedJevConfig,
   type JevConfig,
   type JevProviderKind,
 } from "./jev-config";
@@ -120,6 +203,10 @@ export const JEV_PROVIDER_DEFAULTS = {
   vercel: { baseUrl: "https://ai-gateway.vercel.sh/typesafe/v1", model: VERCEL_JEV_MODEL },
   cloudflare: { baseUrl: "https://api.cloudflare.com/client/v4", model: CLOUDFLARE_JEV_MODEL },
   custom: { baseUrl: null, model: "jev-1.13.0" },
+  // No default base: it is the Cloud origin this machine connected to, written
+  // into jev.json by `config --token` and checked against the credential's own
+  // origin by the loader. The server forces `jev-1.13.0` whatever is sent.
+  failproofai: { baseUrl: null, model: "jev-1.13.0" },
 } as const satisfies Record<JevProviderKind, { baseUrl: string | null; model: string }>;
 
 /**
@@ -139,10 +226,17 @@ export class JevError extends Error {
    * cloudflare-error, cloudflare-incomplete, malformed, model-mismatch, config.
    */
   readonly code: string;
-  constructor(code: string, message: string) {
-    super(message);
+  /**
+   * An HTTP 429's `Retry-After` header, verbatim (null when it sent none).
+   * Recorded for every route and read by the FailproofAI Cloud one only (see
+   * `cloudRetryAfter`); a BYOK route behaves exactly as it did without it.
+   */
+  readonly retryAfter: string | null;
+  constructor(code: string, message: string, opts: { retryAfter?: string | null } = {}) {
+    super(printable(message));
     this.name = "JevError";
     this.code = code;
+    this.retryAfter = opts.retryAfter ?? null;
   }
 }
 
@@ -200,8 +294,42 @@ export function transportFor(provider: JevProvider): JevTransport {
 
 const MAX_ERROR_DETAIL = 300;
 
-/** The provider's own words about a failure, from whichever envelope it uses, with the key scrubbed. */
-function errorDetail(body: unknown, secret: string): string {
+/**
+ * The provider's own words about a failure, from whichever envelope it uses,
+ * with the key scrubbed. Every shape below was observed live; none is guessed at,
+ * because a shape nobody has seen adds a branch that can only ever misread a
+ * body some future provider sends.
+ *
+ * | shape                       | seen on                                              |
+ * |-----------------------------|------------------------------------------------------|
+ * | `{errors:[{message}]}`      | Cloudflare Workers AI                                |
+ * | `{error:{message}}`         | OpenRouter, and LiteLLM-style proxies                |
+ * | `{error:"…"}`               | gateways that report an upstream failure as a string |
+ * | `{message}`                 | Vercel AI Gateway (`400 model: Invalid input: …`)    |
+ * | `{detail:{message}}`        | TypeSafe direct (`403 Must supply an API key!`)      |
+ * | `{detail:"…"}`              | a FastAPI 404 behind a proxy (`Not Found`)           |
+ *
+ * `{detail:{message}}` is the one that was missing, and it is TypeSafe's own —
+ * so the provider this whole file exists to talk to was the one provider whose
+ * explanation never reached a screen.
+ *
+ * `{error:"<code>", message:"…"}` is FailproofAI Cloud's own error body (its
+ * Jev route's contract, `{"error":"forbidden","message":"… jev:evaluate …"}`).
+ * Read as `{error:"…"}` alone it reported the bare word `forbidden` and dropped
+ * the sentence naming the missing permission, so when both are strings both
+ * are kept, code first.
+ */
+/**
+ * Provider text with its control characters (C0, DEL, C1) replaced by spaces.
+ * Error text is printed to a terminal, where OSC 52 writes the clipboard, OSC 8
+ * plants a link and ESC[2J erases the real diagnostic. Every field it is used
+ * for is one line.
+ */
+export function printable(s: string): string {
+  return s.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
+}
+
+export function providerErrorDetail(body: unknown, secret: string): string {
   const b = body as {
     errors?: Array<{ message?: unknown }>;
     error?: unknown;
@@ -213,15 +341,24 @@ function errorDetail(body: unknown, secret: string): string {
     if (Array.isArray(b.errors)) {
       detail = b.errors.map((e) => (typeof e?.message === "string" ? e.message : "")).filter(Boolean).join("; ");
     }
-    if (!detail && b.error && typeof b.error === "object") {
-      const m = (b.error as { message?: unknown }).message;
-      if (typeof m === "string") detail = m;
+    if (!detail && typeof b.error === "string" && b.error && typeof b.message === "string" && b.message) {
+      detail = `${b.error}: ${b.message}`;
     }
-    if (!detail && typeof b.error === "string") detail = b.error;
+    if (!detail) detail = messageOf(b.error);
     if (!detail && typeof b.message === "string") detail = b.message;
-    if (!detail && typeof b.detail === "string") detail = b.detail;
+    if (!detail) detail = messageOf(b.detail);
   }
-  return scrubSecret(detail, secret).slice(0, MAX_ERROR_DETAIL);
+  return printable(scrubSecret(detail, secret)).slice(0, MAX_ERROR_DETAIL);
+}
+
+/** An envelope member that is either the sentence itself or an object carrying it. */
+function messageOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const m = (value as { message?: unknown }).message;
+    if (typeof m === "string") return m;
+  }
+  return "";
 }
 
 /**
@@ -279,12 +416,51 @@ function paymentRequiredCode(detail: string): string {
   return MODEL_EXECUTION_402_RE.test(detail) ? JEV_REASON_PROVIDER_REFUSED : "out-of-credits";
 }
 
+/** Whether this URL is one THIS file built by appending its own suffix (see `nativeEndpoint`). */
+function isSystemOneUrl(url: string): boolean {
+  try {
+    return /\/systemone$/i.test(new URL(url).pathname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The message for a failed status, which is the provider's own sentence when it
+ * sent one — except for a 404 on `<base>/systemone`, which needs saying rather
+ * than repeating.
+ *
+ * `/systemone` is appended here, not typed by the customer, and every provider
+ * serves it at its version root: measured 2026-09-25, an unauthenticated POST to
+ * that path answers 403 / 401 / 400 / 401 on TypeSafe, OpenRouter, Vercel and a
+ * LiteLLM proxy, and 404 on none of them. So a 404 there is near-certain evidence
+ * that the BASE is wrong — and the body is no help, because the one seen in the
+ * field said `Not Found` and nothing else. The URL is named because it is the
+ * constructed one, which is what the person has to compare against what they
+ * typed; it goes through `displayEndpoint`, so a base carrying a token in its
+ * query string does not put it in an error message.
+ */
+function httpFailureMessage(status: number, url: string, detail: string, derivedBase = false): string {
+  // A base URL the connection supplied is nobody's typo: a Cloud 404 is a
+  // server without the route, which `jev test`'s remedy line says.
+  if (status === 404 && derivedBase) return `nothing is served at ${displayEndpoint(url)}${detail ? ` (${detail})` : ""}`;
+  if (status === 404 && isSystemOneUrl(url)) {
+    // No `HTTP 404:` prefix: every caller prints the code beside the message.
+    return (
+      `nothing is served at ${displayEndpoint(url)}${detail ? ` (${detail})` : ""}. ` +
+      "`/systemone` is appended to the base URL you configured, and every Jev route serves it at the provider's version root — " +
+      "so this is a base URL that is wrong, not a provider that is down."
+    );
+  }
+  return detail || `HTTP ${status}`;
+}
+
 /** A redirect, including the opaque form a browser-style fetch returns for `redirect: "manual"` (status 0). */
 function isRedirect(res: Response): boolean {
   return res.type === "opaqueredirect" || (res.status >= 300 && res.status < 400);
 }
 
-async function postJson(url: string, bearer: string, body: unknown, signal: AbortSignal): Promise<unknown> {
+async function postJson(url: string, bearer: string, body: unknown, signal: AbortSignal, derivedBase = false): Promise<unknown> {
   let res: Response;
   try {
     res = await fetch(url, {
@@ -311,6 +487,8 @@ async function postJson(url: string, bearer: string, body: unknown, signal: Abor
     const status = res.status >= 300 && res.status < 400 ? String(res.status) : "3xx";
     throw new JevError(`http-${status}`, `HTTP ${status}: the endpoint answered with a redirect, which is never followed`);
   }
+  // Kept for a 429 and a 503: the statuses whose header says when to ask again.
+  const retryAfter = res.status === 429 || res.status === 503 ? res.headers.get("retry-after") : null;
   let parsed: unknown;
   try {
     parsed = await res.json();
@@ -319,18 +497,20 @@ async function postJson(url: string, bearer: string, body: unknown, signal: Abor
     // No provider words to read, so nothing distinguishes a refusal from an
     // empty account: the status's own meaning stands (see `paymentRequiredCode`).
     if (res.status === 402) throw new JevError("out-of-credits", "HTTP 402: the account is out of credits");
-    if (!res.ok) throw new JevError(`http-${res.status}`, `HTTP ${res.status}`);
+    // A 404 needs no body to be diagnosed, and the ones seen in the field carry
+    // none worth reading: the URL is the diagnosis (see `httpFailureMessage`).
+    if (!res.ok) throw new JevError(`http-${res.status}`, httpFailureMessage(res.status, url, "", derivedBase), { retryAfter });
     throw new JevError("malformed", "response body is not JSON");
   }
   if (res.status === 402) {
     // A refusal is only ever recognised FROM the provider's words, so a 402
     // with none is `out-of-credits` and this message fits it. Anything the
     // provider did say is the message, refusal or not.
-    const detail = errorDetail(parsed, bearer);
+    const detail = providerErrorDetail(parsed, bearer);
     throw new JevError(paymentRequiredCode(detail), detail || "HTTP 402: the account is out of credits");
   }
   if (!res.ok) {
-    throw new JevError(`http-${res.status}`, errorDetail(parsed, bearer) || `HTTP ${res.status}`);
+    throw new JevError(`http-${res.status}`, httpFailureMessage(res.status, url, providerErrorDetail(parsed, bearer), derivedBase), { retryAfter });
   }
   return parsed;
 }
@@ -354,6 +534,8 @@ export interface NativeTransportOptions {
   aliases?: readonly string[];
   /** Whether an answer with no `model` at all is accepted (as unverified) rather than refused. */
   allowUnreported?: boolean;
+  /** The base URL came from a connection, not from the person (FailproofAI Cloud). */
+  derivedBase?: boolean;
 }
 
 /**
@@ -368,7 +550,7 @@ function normalizeNative(body: unknown, sentModel: string, opts: NativeTransport
     // Gateways sometimes report an upstream failure inside a 200.
     if (b.error !== undefined) {
       const code = typeof b.error === "object" && b.error !== null ? (b.error as { code?: unknown }).code : undefined;
-      const detail = errorDetail(body, opts.apiKey) || "the provider reported an error";
+      const detail = providerErrorDetail(body, opts.apiKey) || "the provider reported an error";
       // Same two meanings, one layer in; same rule (see `paymentRequiredCode`).
       if (code === 402 || code === "402") throw new JevError(paymentRequiredCode(detail), detail);
       if (typeof code === "number" && (code === 429 || code >= 500)) throw new JevError(`http-${code}`, detail);
@@ -401,7 +583,7 @@ export function nativeTransport(opts: NativeTransportOptions): JevTransport {
   return async (request, signal) => {
     const model = opts.model ?? request.model;
     const body = { ...request, model, ...(opts.extraBody ?? {}) };
-    return normalizeNative(await postJson(opts.url, opts.apiKey, body, signal), model, opts);
+    return normalizeNative(await postJson(opts.url, opts.apiKey, body, signal, opts.derivedBase), model, opts);
   };
 }
 
@@ -536,14 +718,19 @@ export interface JevRoute {
   modelIsDefault: boolean;
 }
 
-function nativeEndpoint(baseUrl: string): string {
+export function nativeEndpoint(baseUrl: string): string {
   const url = new URL(baseUrl);
   if (!/\/systemone$/.test(url.pathname)) url.pathname = `${url.pathname.replace(/\/+$/, "")}/systemone`;
   return url.toString();
 }
 
+/**
+ * A config as the loader produced it, validated again. `validateLoadedJevConfig`
+ * rather than `validateJevConfig`, because the FailproofAI Cloud provider's key
+ * is filled in from `credentials.json` and would be refused as a file field.
+ */
 function validated(cfg: JevConfig): JevConfig {
-  const v = validateJevConfig(cfg);
+  const v = validateLoadedJevConfig(cfg);
   if (!v.ok) throw new JevError("config", v.problem);
   return v.value;
 }
@@ -558,7 +745,7 @@ export function jevRoute(input: JevConfig): JevRoute {
     return { via: "cloudflare", endpoint: cloudflareEndpoint(cfg.accountId as string, cfg.baseUrl), model, modelIsDefault };
   }
   const base = cfg.baseUrl ?? defaults.baseUrl;
-  if (!base) throw new JevError("config", "provider custom needs a baseUrl");
+  if (!base) throw new JevError("config", `provider ${cfg.provider} needs a baseUrl`);
   return { via: cfg.provider, endpoint: nativeEndpoint(base), model, modelIsDefault };
 }
 
@@ -573,6 +760,311 @@ export function displayEndpoint(endpoint: string): string {
   }
 }
 
+/**
+ * Why a URL given where a base belongs is refused, in one sentence shared by
+ * `jev setup` and the dashboard's save, built from the transport's own URL so
+ * neither describes a request it does not make: a `/systemone` URL is used as
+ * it is (never doubled); any other would be asked at `<url>/systemone`.
+ */
+export function endpointAsBaseReason(given: string): string {
+  const asked = nativeEndpoint(given);
+  return asked === new URL(given).toString()
+    ? "That is already the Jev endpoint itself: this field takes the base it sits under (where <base>/models is read), and failproofai adds /systemone on its own."
+    : `A Jev request goes to <base>/systemone, and failproofai appends that itself, so ${displayEndpoint(given)} would be asked at ${displayEndpoint(asked)}.`;
+}
+
+// ── The model list ───────────────────────────────────────────────────────────
+
+/**
+ * Which envelope a model list arrived in. The difference decides what may be
+ * DONE with it, not just how it is parsed — see the header.
+ */
+export type JevModelListShape =
+  /** `{models:[{name, description?, release_date?}]}` — the System One inventory of this base. */
+  | "typesafe"
+  /** `{data:[{id, name?}]}` — a gateway's chat catalog, which does not enumerate `/systemone`. */
+  | "openai";
+
+export interface JevModelListRead {
+  ok: true;
+  shape: JevModelListShape;
+  /** Model ids, in the order the provider gave them, deduplicated. */
+  models: string[];
+}
+
+export interface JevModelListUnread {
+  ok: false;
+  /** Why, in words meant for a person. Never a code: nothing stores or branches on this. */
+  reason: string;
+  /** The HTTP status, when the read got that far. */
+  status?: number;
+}
+
+export type JevModelListResult = JevModelListRead | JevModelListUnread;
+
+/**
+ * A model list read is a diagnostic, and the whole point of it is to be
+ * available BEFORE a config is written — so it gets its own budget rather than
+ * the config's `timeoutMs`, which is sized for the hook path (3000 ms, and every
+ * millisecond of it lands on a tool call).
+ */
+export const JEV_MODEL_LIST_TIMEOUT_MS = 2_500;
+
+/**
+ * Names kept from one list. OpenRouter's catalog is 458 entries and a proxy's
+ * could be anything; this is a terminal, and a bound here is cheaper than a
+ * bound at every place that prints one.
+ */
+const MAX_LISTED_MODELS = 200;
+
+/**
+ * `<base>/models`, or null where there is no such thing.
+ *
+ * Cloudflare is the null: Workers AI has no `<base>/models` — the run endpoint is
+ * `/accounts/<id>/ai/run` and its inventory lives behind a different API — so
+ * nothing here can read a list for it, and every caller treats that exactly like
+ * a list it failed to read.
+ *
+ * A base that names the full request URL (`…/v1/systemone`, which `jev setup`
+ * now refuses but an older file may carry) still has its version root one
+ * segment up, and that is where the list is.
+ */
+export function jevModelsUrl(input: JevConfig): string | null {
+  const cfg = validated(input);
+  // FailproofAI Cloud pins the model server-side and serves no list.
+  if (cfg.provider === "cloudflare" || cfg.provider === "failproofai") return null;
+  const base = cfg.baseUrl ?? JEV_PROVIDER_DEFAULTS[cfg.provider].baseUrl;
+  return base ? modelsUrlForBase(base) : null;
+}
+
+/** `<base>/models` for a base URL, keeping any query string the base carried. */
+export function modelsUrlForBase(base: string): string | null {
+  try {
+    const url = new URL(base);
+    url.pathname = `${url.pathname.replace(/\/systemone$/i, "").replace(/\/+$/, "")}/models`;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The model ids in a list body, or why it could not be read. Never throws: a
+ * customer's proxy may serve neither shape, or an HTML error page, and an
+ * unreadable list must leave every caller exactly where it was.
+ *
+ * `secret` is the key the list was fetched with. Names are scrubbed of it and
+ * then kept only if they are SHAPED like model ids, because these strings come
+ * from a remote endpoint and are about to be printed on a terminal — a name
+ * carrying control characters, or a kilobyte of them, is not a name.
+ *
+ * A shape that is present but yields no usable name is reported as unread rather
+ * than as "this endpoint has no models": an empty list is far likelier to be a
+ * shape misread than a provider serving nothing, and "unread" is the direction
+ * that changes no behaviour.
+ */
+export function parseJevModelList(body: unknown, secret = ""): JevModelListResult {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, reason: "the list endpoint did not answer with a JSON object" };
+  }
+  const b = body as { models?: unknown; data?: unknown };
+  for (const [shape, entries, keys] of [
+    ["typesafe", b.models, ["name"]],
+    ["openai", b.data, ["id", "name"]],
+  ] as Array<[JevModelListShape, unknown, string[]]>) {
+    if (!Array.isArray(entries)) continue;
+    const models = listedModelNames(entries, keys, secret);
+    return models.length > 0 ? { ok: true, shape, models } : { ok: false, reason: "the list named no models this build could read" };
+  }
+  return { ok: false, reason: "the list endpoint answered in a shape this build does not know (neither {models:[…]} nor {data:[…]})" };
+}
+
+function listedModelNames(entries: unknown[], keys: string[], secret: string): string[] {
+  const out: string[] = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const row = entry as Record<string, unknown>;
+    for (const key of keys) {
+      const raw = row[key];
+      if (typeof raw !== "string" || raw === "") continue;
+      const name = scrubSecret(raw, secret);
+      if (isModelIdShaped(name) && !out.includes(name)) out.push(name);
+      break;
+    }
+    if (out.length >= MAX_LISTED_MODELS) break;
+  }
+  return out;
+}
+
+/**
+ * `GET <base>/models`. Returns a reading or a reason, never a throw, because
+ * every caller's fallback is to carry on as if the endpoint served no list.
+ *
+ * `apiKey` may be null: Vercel's and OpenRouter's lists are public, and reading
+ * one with no key is better than not reading it. Redirects are not followed, for
+ * the reason `postJson` gives — a list read is less dangerous than an answer, but
+ * an endpoint that moves this GET somewhere unchecked has not earned the key that
+ * would ride along with it.
+ */
+export async function readJevModelList(url: string, apiKey: string | null, signal: AbortSignal): Promise<JevModelListResult> {
+  const secret = apiKey ?? "";
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json", ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}) },
+      signal,
+      redirect: "manual",
+    });
+  } catch (err) {
+    if (signal.aborted) return { ok: false, reason: `it did not answer within ${JEV_MODEL_LIST_TIMEOUT_MS} ms` };
+    return { ok: false, reason: printable(scrubSecret(err instanceof Error ? err.message : String(err), secret)).slice(0, MAX_ERROR_DETAIL) };
+  }
+  if (isRedirect(res)) {
+    try {
+      void res.body?.cancel().catch(() => {});
+    } catch {
+      // The body is irrelevant; freeing it is best effort.
+    }
+    return { ok: false, reason: "it answered with a redirect, which is never followed" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = await res.json();
+  } catch {
+    if (signal.aborted) return { ok: false, reason: `it did not answer within ${JEV_MODEL_LIST_TIMEOUT_MS} ms` };
+    return { ok: false, reason: `HTTP ${res.status}: it answered with no JSON`, status: res.status };
+  }
+  if (!res.ok) {
+    // The provider's own sentence, from whichever envelope — which for a list
+    // read is usually "Must supply an API key!", and is the answer.
+    const detail = providerErrorDetail(parsed, secret);
+    return { ok: false, reason: detail ? `HTTP ${res.status}: ${detail}` : `HTTP ${res.status}`, status: res.status };
+  }
+  return parseJevModelList(parsed, secret);
+}
+
+/**
+ * Whether a reading is authoritative about what `<base>/systemone` accepts, and
+ * so may be used to REFUSE a model rather than only to show one.
+ *
+ * Only the TypeSafe shape is. The evidence is in the header: OpenRouter serves an
+ * OpenAI-shaped catalog of 458 models with no Jev entry in it, while its
+ * `/systemone` exists and is addressed as `typesafe/jev-1.13` — so refusing on an
+ * OpenAI-shaped list would refuse a route that works.
+ */
+export function listDescribesSystemOne(list: JevModelListRead): boolean {
+  return list.shape === "typesafe";
+}
+
+/**
+ * Whether a list covers a configured model id.
+ *
+ * Exact match, or the id without an `<owner>/` prefix. That second case is
+ * measured, not a convenience: Vercel names one model `typesafe-ai/jev` in its
+ * gateway catalog and `jev` in the typesafe-scoped list at the base we POST to,
+ * differing by exactly that prefix (see the header).
+ *
+ * A versioned id (`jev-1.13.0`) always counts: a list names aliases, and cannot
+ * prove one absent (see the header).
+ */
+export function modelListHasModel(list: JevModelListRead, model: string): boolean {
+  if (jevModelVersion(model) !== null) return true;
+  if (list.models.includes(model)) return true;
+  const slash = model.lastIndexOf("/");
+  return slash > 0 && list.models.includes(model.slice(slash + 1));
+}
+
+// ── FailproofAI Cloud: Retry-After ───────────────────────────────────────────
+//
+// FailproofAI Cloud rate-limits Jev per org and globally, and its 429 carries
+// `Retry-After: <seconds to the window's end>` (contract §2). Every call that
+// ignores it spends a round trip — up to the hook's whole timeout, on the tool
+// call's critical path — to learn the same 429, and adds to the load that
+// caused it. So after a 429 the Cloud route goes quiet for as long as the
+// server asked: calls fall back at once with the same `http-429`, and send
+// nothing.
+//
+// Module-level, like the throttle's cache and bucket (`jev-throttle.ts`): the
+// daemon's warm worker builds a new transport per hook event and lives for
+// hours, so the process is what has to remember. Keyed by the endpoint, so a
+// reconnect to another Cloud is not held to the old one's window.
+//
+// The Cloud route only. A BYOK provider's 429 keeps doing exactly what it did
+// (the throttle empties its bucket), because nothing here knows what its
+// `Retry-After` means or whether it sends one.
+
+/** The longest cool-down a Retry-After can set: a hook never goes quiet for longer on the server's say-so. */
+export const JEV_CLOUD_RETRY_AFTER_CAP_MS = 60_000;
+/** The cool-down after a 429 whose Retry-After is missing or unreadable. */
+export const JEV_CLOUD_RETRY_AFTER_DEFAULT_MS = 5_000;
+
+const cloudCooldown = { endpoint: "", until: Number.NEGATIVE_INFINITY, code: "http-429" };
+
+/** Forget any cool-down. For tests, which share this module's state within a file. */
+export function resetJevCloudCooldown(): void {
+  cloudCooldown.endpoint = "";
+  cloudCooldown.until = Number.NEGATIVE_INFINITY;
+  cloudCooldown.code = "http-429";
+}
+
+/** RFC 9110's IMF-fixdate, the one HTTP-date form a sender generates: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const IMF_FIXDATE_RE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+
+/**
+ * How long a `Retry-After` asks for, in ms, within [0, cap]. Delay-seconds
+ * (what FailproofAI Cloud sends) or an IMF-fixdate; anything else — absent,
+ * negative, fractional, garbage — is the small default. Matched by shape
+ * before `Date.parse` sees it, because that parser reads `-5` or `1.5` as a
+ * date in the past, which would be no cool-down at all.
+ */
+export function retryAfterMs(header: string | null | undefined, nowEpochMs: number = Date.now()): number {
+  const raw = header?.trim() ?? "";
+  let ms: number;
+  if (/^\d{1,10}$/.test(raw)) {
+    ms = Number(raw) * 1000;
+  } else if (IMF_FIXDATE_RE.test(raw) && Number.isFinite(Date.parse(raw))) {
+    ms = Date.parse(raw) - nowEpochMs;
+  } else {
+    return JEV_CLOUD_RETRY_AFTER_DEFAULT_MS;
+  }
+  return Math.min(JEV_CLOUD_RETRY_AFTER_CAP_MS, Math.max(0, ms));
+}
+
+/**
+ * The Cloud transport, quiet for as long as the last 429's Retry-After asked —
+ * and after a 503 too. The server's 503 is an operator state (no model
+ * gateway, an org not provisioned yet, the gateway down) that waiting does not
+ * fix, so without a Retry-After it holds the longest this ever does, and a held
+ * call keeps the code that started it rather than reading as a rate limit.
+ */
+function cloudRetryAfter(endpoint: string, transport: JevTransport): JevTransport {
+  return async (request, signal) => {
+    const now = performance.now();
+    if (cloudCooldown.endpoint === endpoint && now < cloudCooldown.until) {
+      const seconds = Math.max(1, Math.ceil((cloudCooldown.until - now) / 1000));
+      throw new JevError(
+        cloudCooldown.code,
+        cloudCooldown.code === "http-503"
+          ? `FailproofAI Cloud could not serve Jev; asking again in ${seconds}s, so this one was not sent`
+          : `FailproofAI Cloud asked for no Jev requests for ${seconds}s more (Retry-After), so this one was not sent`,
+      );
+    }
+    try {
+      return await transport(request, signal);
+    } catch (err) {
+      if (err instanceof JevError && (err.code === "http-429" || err.code === "http-503")) {
+        cloudCooldown.endpoint = endpoint;
+        cloudCooldown.code = err.code;
+        cloudCooldown.until =
+          performance.now() +
+          (err.code === "http-503" && err.retryAfter === null ? JEV_CLOUD_RETRY_AFTER_CAP_MS : retryAfterMs(err.retryAfter));
+      }
+      throw err;
+    }
+  };
+}
+
 /**
  * The transport for a customer's own Jev config, which provider it goes
  * through, and the model id to put in the request (pass it to the evaluator as
@@ -639,5 +1131,25 @@ export function transportForConfig(input: JevConfig): { transport: JevTransport;
         via: "custom",
         model: route.model,
       };
+    case "failproofai":
+      return {
+        transport: cloudRetryAfter(
+          route.endpoint,
+          nativeTransport({
+            url: route.endpoint,
+            apiKey: cfg.apiKey,
+            model: route.model,
+            // FailproofAI Cloud forces `jev-1.13.0` server-side and passes
+            // TypeSafe's answer through untouched, `model` included — so an
+            // answer that names no model, or an alias, is not one this route
+            // produces, and is refused (`model-mismatch`) rather than trusted.
+            // `readAnswers` then holds the reported id to the 1.13 family.
+            allowUnreported: false,
+            derivedBase: true,
+          }),
+        ),
+        via: "failproofai",
+        model: route.model,
+      };
   }
 }