@open-everywhere/adapters 0.7.0 → 0.8.0

package/agent/model/model-config-check.ts

@@ -0,0 +1,243 @@
+// THE LIVE MODEL CONFIG CHECK (OPE-2556, the OPE-2535 ticket's comment #2). It answers, BEFORE a call fails, whether
+// the deployment's model config can be served: for each model the caller lists (the stack roles, the gateway
+// transcription routes, the domain and role routes, `models.force`), one GET of the gateway's
+// public `/v1/models/<id>/endpoints` read, and three questions:
+//
+//   ① does the model exist on the gateway?
+//   ② does at least one `providers.only` provider serve it? (A slug that serves none of the checked models gets a
+//      warning, because it is most likely a typo. It is not a failure: every call can still be served.)
+//   ③ does at least one allowed provider meet EVERY `models.dataPolicy` row at once (`has_zdr`, `has_no_training`,
+//      `inference_regions`)?
+//
+// A row no provider can meet is named before deploy, for example "region eu: no provider for deepseek/…".
+//
+// 🔴 THE ENDPOINT FIELDS ARE UNDOCUMENTED, so a missing field is UNKNOWN, never a pass. One rule reads more than a
+// field: `inference_regions`. Most endpoints omit it. When at least one endpoint of a model lists regions, an endpoint
+// that omits them is read as serving none of the listed regions: that is how the gateway answered on 2026-10-14
+// ("No provider for deepseek/deepseek-v4-flash-0731 supports the requested inference region", where only some
+// endpoints listed `us` and none listed `eu`). When no endpoint lists regions, the region row is unknown.
+//
+// It needs the network, so it is never an offline gate. Three readers run it: the deployment status probe
+// (`model-route`, gateway-probe.ts), which `create --check --host` and the setup skill read, and
+// `npm run check:model-config`, which runs it from the app (a clone or a scaffolded app) before a deploy.
+
+import { type ModelDataPolicy, type ModelTarget, mergeDataPolicy } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The default origin of the Vercel AI Gateway's public model reads. */
+const DEFAULT_GATEWAY_ORIGIN = "https://ai-gateway.vercel.sh";
+
+export type CheckVerdict = "yes" | "no" | "unknown";
+
+/** One endpoint (one provider serving one model), as the check reads it. `undefined` is an unknown field. */
+export interface EndpointFacts {
+  readonly provider: string;
+  readonly zdr: boolean | undefined;
+  readonly noTraining: boolean | undefined;
+  /** The regions the endpoint lists, or undefined when the endpoint omits the field. */
+  readonly regions: readonly string[] | undefined;
+}
+
+/** A model the deployment can resolve, and the target its calls go through. */
+export interface CheckedModel {
+  readonly id: string;
+  /** The `models.targets` entry (absent: `gateway`). */
+  readonly via?: string;
+}
+
+/** One problem or gap the check found. `row` names the demand in the settings file's words. */
+export interface ConfigFinding {
+  readonly met: Exclude<CheckVerdict, "yes">;
+  readonly model?: string;
+  readonly row: string;
+  readonly detail: string;
+}
+
+export interface ConfigCheckResult {
+  /** "no" when any finding is "no"; "unknown" when any is "unknown"; else "yes". */
+  readonly met: CheckVerdict;
+  readonly findings: readonly ConfigFinding[];
+  /** How many distinct (target, model) pairs were read. */
+  readonly checked: number;
+}
+
+/** The endpoints read for one model id under a target's base URL (or the default origin). The id keeps its slash. */
+export function modelEndpointsUrl(id: string, baseUrl?: string): string {
+  let origin = DEFAULT_GATEWAY_ORIGIN;
+  if (baseUrl !== undefined) {
+    try {
+      origin = new URL(baseUrl).origin;
+    } catch {
+      // The settings validator refuses an unparseable url; the default origin keeps the check honest.
+    }
+  }
+  return `${origin}/v1/models/${id.split("/").map(encodeURIComponent).join("/")}/endpoints`;
+}
+
+const asBool = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);
+
+/** Parse an `/endpoints` body into facts, or undefined when the body is not one. Pure. */
+export function parseEndpoints(body: unknown): EndpointFacts[] | undefined {
+  const eps = (body as { data?: { endpoints?: unknown } } | null)?.data?.endpoints;
+  if (!Array.isArray(eps)) return undefined;
+  const out: EndpointFacts[] = [];
+  for (const e of eps) {
+    if (e === null || typeof e !== "object") continue;
+    const r = e as Record<string, unknown>;
+    if (typeof r["provider_name"] !== "string") continue;
+    const regions = Array.isArray(r["inference_regions"])
+      ? (r["inference_regions"] as unknown[]).flatMap((x) => {
+          const g = (x as { geo_region?: unknown } | null)?.geo_region;
+          return typeof g === "string" ? [g] : [];
+        })
+      : undefined;
+    out.push({ provider: r["provider_name"], zdr: asBool(r["has_zdr"]), noTraining: asBool(r["has_no_training"]), regions });
+  }
+  return out;
+}
+
+const and = (a: CheckVerdict, b: CheckVerdict): CheckVerdict => (a === "no" || b === "no" ? "no" : a === "unknown" || b === "unknown" ? "unknown" : "yes");
+/** At least one provider: "yes" when one is, "no" when every one is not (or there is none), else "unknown". */
+const any = (vs: readonly CheckVerdict[]): CheckVerdict => (vs.includes("yes") ? "yes" : vs.every((v) => v === "no") ? "no" : "unknown");
+const fromBool = (b: boolean | undefined): CheckVerdict => (b === undefined ? "unknown" : b ? "yes" : "no");
+
+/** The policy's rows as (label, per-endpoint verdict) pairs. */
+function rowJudges(policy: ModelDataPolicy, eps: readonly EndpointFacts[]): { label: string; judge: (e: EndpointFacts) => CheckVerdict }[] {
+  const rows: { label: string; judge: (e: EndpointFacts) => CheckVerdict }[] = [];
+  if (policy.zeroRetention === true) rows.push({ label: "zeroRetention", judge: (e) => fromBool(e.zdr) });
+  if (policy.noTraining === true) rows.push({ label: "noTraining", judge: (e) => fromBool(e.noTraining) });
+  const region = policy.region;
+  if (region !== undefined) {
+    const listed = eps.some((e) => e.regions !== undefined);
+    rows.push({ label: `region ${region}`, judge: (e) => (e.regions !== undefined ? fromBool(e.regions.includes(region)) : listed ? "no" : "unknown") });
+  }
+  return rows;
+}
+
+/**
+ * Judge one model's endpoints against a target and the policy. Pure. Returns the findings ("no" and "unknown" only),
+ * so an empty list means every demand is met.
+ */
+export function judgeModelEndpoints(id: string, eps: readonly EndpointFacts[], target: ModelTarget, policy: ModelDataPolicy, via = "gateway"): ConfigFinding[] {
+  const findings: ConfigFinding[] = [];
+  const only = target.providers?.only;
+  const candidates = only === undefined ? eps : eps.filter((e) => only.includes(e.provider));
+  if (only !== undefined && candidates.length === 0) {
+    findings.push({ met: "no", model: id, row: `models.targets.${via}.providers.only`, detail: `providers.only: no allowed provider serves ${id}` });
+    return findings;
+  }
+  // The target's own `dataPolicy` rows join the deployment's (OPE-2531). Two different regions cannot both be met.
+  let merged: ModelDataPolicy;
+  try {
+    merged = mergeDataPolicy(policy, target.dataPolicy);
+  } catch {
+    findings.push({ met: "no", model: id, row: `models.targets.${via}.dataPolicy region`, detail: `region: models.dataPolicy and target ${via} name two different regions` });
+    return findings;
+  }
+  // The region evidence is read over ALL the model's endpoints: whether the gateway lists regions for this model at all.
+  const rows = rowJudges(merged, eps);
+  if (rows.length === 0) return findings;
+  const joint = any(candidates.map((e) => rows.reduce<CheckVerdict>((v, r) => and(v, r.judge(e)), "yes")));
+  if (joint === "yes") return findings;
+  // Name each row no provider can meet on its own; when every row is met by SOME provider, name them together.
+  const alone = rows.map((r) => ({ label: r.label, v: any(candidates.map(r.judge)) }));
+  const failing = alone.filter((r) => r.v === joint);
+  const named = failing.length > 0 ? failing.map((r) => r.label) : [rows.map((r) => r.label).join(" + ")];
+  // A row the deployment's own policy does not set came from the target: name the target's row (OPE-2531).
+  const ownRows = rowJudges(policy, eps).map((r) => r.label);
+  for (const label of named) {
+    findings.push({
+      met: joint,
+      model: id,
+      row: label
+        .split(" + ")
+        .map((l) => (ownRows.includes(l) ? `models.dataPolicy ${l}` : `models.targets.${via}.dataPolicy ${l}`))
+        .join(" + "),
+      detail: joint === "no" ? `${label}: no provider for ${id}` : `${label}: the gateway does not say whether a provider of ${id} meets it`,
+    });
+  }
+  return findings;
+}
+
+export interface ConfigCheckInput {
+  readonly models: readonly CheckedModel[];
+  readonly targets: Readonly<Record<string, ModelTarget>>;
+  readonly policy: ModelDataPolicy;
+  /** The base URL each target resolves to (absent: the default origin). */
+  readonly baseUrlFor: (via: string) => string | undefined;
+  readonly fetchImpl?: typeof globalThis.fetch;
+  /** One budget for every read. */
+  readonly timeoutMs?: number;
+}
+
+/**
+ * Run the check: one GET per distinct (target, model), in parallel, under one time budget. FAIL-SOFT: a read that
+ * fails or times out is "unknown" for that model, never a pass and never a throw. No vendor error text is forwarded.
+ */
+export async function checkModelConfig(input: ConfigCheckInput): Promise<ConfigCheckResult> {
+  const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+  const seen = new Map<string, CheckedModel & { via: string }>();
+  for (const m of input.models) {
+    const via = m.via ?? "gateway";
+    seen.set(`${via}\u0000${m.id}`, { id: m.id, via });
+  }
+  const controller = new AbortController();
+  const fuse = setTimeout(() => controller.abort(), input.timeoutMs ?? 5_000);
+  const servedBy = new Map<string, Set<string>>(); // via → providers that serve at least one checked model
+  try {
+    const perModel = await Promise.all(
+      [...seen.values()].map(async (m): Promise<ConfigFinding[]> => {
+        const target = input.targets[m.via];
+        if (target === undefined) return [{ met: "no", model: m.id, row: `via ${m.via}`, detail: `via ${m.via}: models.targets names no such target` }];
+        let res: Response;
+        try {
+          res = await fetchImpl(modelEndpointsUrl(m.id, input.baseUrlFor(m.via)), { method: "GET", signal: controller.signal });
+        } catch {
+          return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the gateway did not answer the endpoints read` }];
+        }
+        // A retargeted target (a relay) owes nobody this read: its 404 or 405 means "not served here", not "no such model".
+        const retargeted = input.baseUrlFor(m.via) !== undefined;
+        if (retargeted && (res.status === 404 || res.status === 405)) {
+          return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the target ${m.via} does not serve the endpoints read` }];
+        }
+        if (res.status === 404) return [{ met: "no", model: m.id, row: "model id", detail: `${m.id}: the gateway does not know this model` }];
+        if (!res.ok) return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the endpoints read answered HTTP ${res.status}` }];
+        let eps: EndpointFacts[] | undefined;
+        try {
+          eps = parseEndpoints(await res.json());
+        } catch {
+          eps = undefined;
+        }
+        if (eps === undefined) return [{ met: "unknown", model: m.id, row: "endpoints", detail: `${m.id}: the endpoints read is not in the expected shape` }];
+        const served = servedBy.get(m.via) ?? new Set<string>();
+        for (const e of eps) served.add(e.provider);
+        servedBy.set(m.via, served);
+        return judgeModelEndpoints(m.id, eps, target, input.policy, m.via);
+      }),
+    );
+    const findings = perModel.flat();
+    // A `providers.only` slug that serves none of the target's checked models: most likely a typo. It is a WARNING
+    // ("unknown"), never a "no": every call can still be served, and a deployer may list a provider for a later stack.
+    // Only judged when every model of the target was read, so a failed read never blames a slug.
+    for (const [via, served] of servedBy) {
+      const readAll = ![...seen.values()].some((m) => m.via === via && findings.some((f) => f.model === m.id && f.row === "endpoints"));
+      if (!readAll) continue;
+      for (const slug of input.targets[via]?.providers?.only ?? []) {
+        if (!served.has(slug)) findings.push({ met: "unknown", row: `models.targets.${via}.providers.only`, detail: `providers.only: "${slug}" serves none of the checked models` });
+      }
+    }
+    const met: CheckVerdict = findings.some((f) => f.met === "no") ? "no" : findings.length > 0 ? "unknown" : "yes";
+    return { met, findings, checked: seen.size };
+  } finally {
+    clearTimeout(fuse);
+  }
+}
+
+/** The result in one short line a person reads: "4 models checked, no problem", or the problems by name. Pure. */
+export function configCheckSummary(r: ConfigCheckResult): string {
+  const plural = r.checked === 1 ? "model" : "models";
+  if (r.findings.length === 0) return `model config: ${r.checked} ${plural} checked, every demand can be served`;
+  const no = r.findings.filter((f) => f.met === "no");
+  const shown = (no.length > 0 ? no : r.findings).map((f) => f.detail);
+  const head = no.length > 0 ? `${no.length} problem${no.length === 1 ? "" : "s"}` : "not fully measured";
+  return `model config: ${head} — ${shown.slice(0, 3).join("; ")}${shown.length > 3 ? `; and ${shown.length - 3} more` : ""}`;
+}

package/agent/model/target-url.ts

@@ -0,0 +1,38 @@
+// THE BASE URL OF A MODEL TARGET (OPE-2556) — `models.targets.<name>.url`, with the deprecated `OE_AI_GATEWAY_URL`
+// as the `gateway` target's fallback for one release. Its own module so the model adapter (gateway.ts) and the
+// status probe (gateway-probe.ts) resolve the same URL without the probe loading the adapter.
+
+import { DEFAULT_MODEL_VIA, type ModelTarget } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The deprecated env var that retargets the `gateway` target (OPE-2556: `models.targets.gateway.url` replaces it). */
+export const DEPRECATED_GATEWAY_URL_ENV = "OE_AI_GATEWAY_URL";
+
+const warned = new Set<string>();
+function warnOnce(key: string, message: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}
+
+/**
+ * THE BASE URL OF ONE TARGET. The target's `url` wins. The deprecated `OE_AI_GATEWAY_URL` still retargets the
+ * `gateway` target when its `url` is unset, for one release, with a warning. Absent both: the kind's default
+ * endpoint (`undefined`). Pure but for the warnings; exported for tests.
+ */
+export function targetBaseUrl(name: string, t: ModelTarget, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const fromEnv = name === DEFAULT_MODEL_VIA ? env[DEPRECATED_GATEWAY_URL_ENV]?.trim() || undefined : undefined;
+  if (t.url !== undefined) {
+    if (fromEnv !== undefined && fromEnv !== t.url) {
+      warnOnce("env-ignored", `[open-everywhere:model] ${DEPRECATED_GATEWAY_URL_ENV} is set and ignored: models.targets.${name}.url wins. Unset the env var.`);
+    }
+    return t.url;
+  }
+  if (fromEnv !== undefined) {
+    warnOnce(
+      "env-deprecated",
+      `[open-everywhere:model] ${DEPRECATED_GATEWAY_URL_ENV} is deprecated and goes away in the next release. Move it to models.targets.${name}.url in agent/settings/settings.ts.`,
+    );
+  }
+  return fromEnv;
+}
+

package/agent/model/transcription-routes.ts

@@ -18,12 +18,17 @@
 // provider allow-list, a timeout) tries the fallback route. Both fail ⇒ it throws one error that names both. It
 // never tries a third route: the stack names what may hear the meeting, and nothing else may.
 //
+// 🔴 THE DATA POLICY (OPE-2535). A `gateway` route carries `models.dataPolicy` on every call (gateway.ts). The
+// `deepinfra` route cannot carry it, so with any row set it REFUSES before a byte leaves, and the fallback rule
+// above does not let the audio go anywhere the policy did not allow. A `self-hosted` route is the deployer's own
+// server, so the policy's provider rows do not apply to it.
+//
 // 🔴 THE DISCLOSURE IS DERIVED. The approval card shows {@link roleDisclosure}, built from the SAME route list the
 // call walks, so the card cannot name one provider while the audio goes to another.
 
 import { experimental_transcribe as transcribe } from "ai";
-import { getOperatorSecret } from "@open-everywhere/core/agent/adapter-api.js";
-import { GATEWAY_TARGET_HOST, gatewayTranscriptionModel, sharedHostPlaneFetch } from "./gateway.js";
+import { type ModelDataPolicy, dataPolicyActive, dataPolicyRows, getOperatorSecret, getSettings } from "@open-everywhere/core/agent/adapter-api.js";
+import { gatewayTargetHost, gatewayTranscriptionModel, sharedHostPlaneFetch } from "./gateway.js";
 
 /** How a route reaches its model. */
 export type TranscriptionVia = "gateway" | "deepinfra" | "self-hosted";
@@ -82,6 +87,8 @@ export interface TranscriptionDeps {
   readonly attemptTimeoutMs?: number;
   /** Where a fall-through is reported. Default: `console.warn`. */
   readonly warn?: (message: string) => void;
+  /** The deployment's data policy, read per call. Default: `models.dataPolicy` from the settings. */
+  readonly dataPolicy?: () => ModelDataPolicy;
 }
 
 /** The secret-store name of the DeepInfra key. A fixed name in code, so no config line can point it at another secret. */
@@ -259,7 +266,7 @@ function selfHostedCall(f: typeof fetch) {
  * union and neither the turn model nor a transcription route drops the other's host.
  */
 export function roleHostPlaneHosts(role: TranscriptionRoleSpec): string[] {
-  const hosts = [GATEWAY_TARGET_HOST];
+  const hosts = [gatewayTargetHost()];
   for (const r of [role.primary, role.fallback]) {
     if (r === undefined || r.via === "gateway") continue;
     const h = routeHost(r);
@@ -277,7 +284,14 @@ export function routeTransport(r: TranscriptionRouteSpec, deps: TranscriptionDep
   const f = deps.fetch ?? (deps.hostPlane ?? sharedHostPlaneFetch)(roleHostPlaneHosts({ primary: r })) ?? lateFetch;
   if (r.via === "deepinfra") {
     const call = deepinfraCall(f, deps.secret ?? storeOnlySecret);
-    return (req) => call(r, req);
+    const policy = deps.dataPolicy ?? (() => getSettings().models.dataPolicy);
+    return async (req) => {
+      const p = policy();
+      if (dataPolicyActive(p)) {
+        throw new Error(`models.dataPolicy (${dataPolicyRows(p).join(", ")}): the deepinfra route cannot carry these rows, so it refuses`);
+      }
+      return await call(r, req);
+    };
   }
   const call = selfHostedCall(f);
   return (req) => call(r, req);

package/agent/oe-oauth/errors.ts

@@ -2,7 +2,7 @@
 // DUCK-TYPED across processes. SECURITY: no error here carries a token, a code, or a PKCE verifier.
 
 /** The subject an error is about, as a log-safe label (never an opaque token). */
-export function subjectLabel(subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }): string {
+function subjectLabel(subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }): string {
   return subject.type === "app" ? "app" : `user:${subject.id}`;
 }
 

package/agent/oe-oauth/token-vault.ts

@@ -601,20 +601,57 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
     });
   }
 
-  /** Purge a person's IdP grant: revoke the IdP refresh token at the IdP (best-effort), then delete the row. */
-  async function forgetIdpGrant(cfg: OeOauthXaaProviderConfig, subject: OeOauthSubject): Promise<boolean> {
+  /** How a failed IdP revocation is reported (OPE-2565): `idp:` and the issuer's host, the name an operator knows it by. */
+  function idpReportRef(cfg: OeOauthXaaProviderConfig): string {
+    try {
+      return `idp:${new URL(cfg.idpIssuer).host}`;
+    } catch {
+      return "idp:";
+    }
+  }
+
+  /**
+   * Run one revocation call, and retry it ONCE on a failure (OPE-2565). A second failure is warned and handed to
+   * `onUnrevoked`, so the purge's caller records it: the row is deleted anyway, and the token stays valid at the
+   * provider until it expires. Never throws — a vendor failure never blocks the local delete.
+   */
+  async function revokeWithRetry(providerRef: string, call: () => Promise<void>, onUnrevoked: ((providerRef: string) => void) | undefined, what: string): Promise<void> {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        await call();
+        return;
+      } catch (e) {
+        if (attempt < 2) continue;
+        // Message only: the client's errors are built never to carry token material.
+        console.warn(`[oe-oauth] ${what} failed twice for "${providerRef}" (purging locally anyway; the token stays valid there until it expires): ${e instanceof Error ? e.message : String(e)}`);
+        onUnrevoked?.(providerRef);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Purge a person's IdP grant: revoke the IdP refresh token at the IdP (one retry), then delete the row. A failure
+   * is reported as `idp:<issuer host>`, never under the connection's ref: the token that stays valid is the IdP
+   * grant, which every `xaa` connection on that IdP shares, so naming the connection would send the operator to
+   * the wrong system.
+   */
+  async function forgetIdpGrant(cfg: OeOauthXaaProviderConfig, subject: OeOauthSubject, onUnrevoked?: (providerRef: string) => void): Promise<boolean> {
     const gRef = idpRef(cfg, subject);
     return vault.withLock(gRef, async () => {
       const grant = await readJson<IdpGrantRecord>(gRef);
       if (grant) {
-        try {
-          const oidc = await oidcFor(cfg);
-          if (oidc.revocationEndpoint) {
-            await revokeTokenConfidential(oidc.revocationEndpoint, { token: grant.refreshToken, tokenTypeHint: "refresh_token" }, await xaaClient(cfg, "idp"), doFetch);
-          }
-        } catch (e) {
-          console.warn(`[oe-oauth] IdP revocation failed for "${cfg.ref}" (purging locally anyway): ${e instanceof Error ? e.message : String(e)}`);
-        }
+        await revokeWithRetry(
+          idpReportRef(cfg),
+          async () => {
+            const oidc = await oidcFor(cfg);
+            if (oidc.revocationEndpoint) {
+              await revokeTokenConfidential(oidc.revocationEndpoint, { token: grant.refreshToken, tokenTypeHint: "refresh_token" }, await xaaClient(cfg, "idp"), doFetch);
+            }
+          },
+          onUnrevoked,
+          "IdP revocation",
+        );
       }
       return vault.delete(gRef);
     });
@@ -669,8 +706,9 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
   /**
    * PURGE one (provider, subject) record: vendor revocation FIRST, then the at-rest row. The ORDER makes a
    * racing cross-process refresh benign; where a vendor cannot cascade, the access token lives out its TTL.
+   * A revocation call that fails is retried once; a second failure goes to `onUnrevoked` (OPE-2565).
    */
-  async function forget(providerRef: string, subject: OeOauthSubject): Promise<boolean> {
+  async function forget(providerRef: string, subject: OeOauthSubject, onUnrevoked?: (providerRef: string) => void): Promise<boolean> {
     const ref = tokRef(providerRef, subject);
     return vault.withLock(ref, async () => {
       const rec = await readJson<TokenRecord>(ref);
@@ -685,19 +723,23 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
         // whereas revoking an access token kills only that one.
         const token = rec.refreshToken ?? rec.accessToken;
         if (client?.revocationEndpoint && token) {
-          try {
-            const hint = rec.refreshToken ? ("refresh_token" as const) : ("access_token" as const);
-            if (cfg && isStaticConfidential(cfg)) {
-              await revokeTokenConfidential(client.revocationEndpoint, { token, tokenTypeHint: hint }, await confidentialClientFor(cfg), doFetch);
-            } else {
-              await revokeToken(client.revocationEndpoint, { token, clientId: client.clientId, tokenTypeHint: hint }, doFetch);
-            }
-          } catch (e) {
-            // A vendor failure NEVER blocks the local delete — leaving a secret at rest with us
-            // because someone else's server is down is the worse of the two outcomes. Message only:
-            // the client's errors are built never to carry token material.
-            console.warn(`[oe-oauth] revocation at the provider failed for "${providerRef}" (purging locally anyway): ${e instanceof Error ? e.message : String(e)}`);
-          }
+          const endpoint = client.revocationEndpoint;
+          const hint = rec.refreshToken ? ("refresh_token" as const) : ("access_token" as const);
+          // A vendor failure NEVER blocks the local delete — leaving a secret at rest with us because someone
+          // else's server is down is the worse of the two outcomes. It is no longer only a warning (OPE-2565):
+          // after one retry it is reported, and the purge's caller records it as a failure.
+          await revokeWithRetry(
+            providerRef,
+            async () => {
+              if (cfg && isStaticConfidential(cfg)) {
+                await revokeTokenConfidential(endpoint, { token, tokenTypeHint: hint }, await confidentialClientFor(cfg), doFetch);
+              } else {
+                await revokeToken(endpoint, { token, clientId: client.clientId, tokenTypeHint: hint }, doFetch);
+              }
+            },
+            onUnrevoked,
+            "revocation at the provider",
+          );
         }
       }
       // Runs even when there was no record to read (a corrupt/undecryptable envelope reads as null —
@@ -752,22 +794,50 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
     sweepExpiredPending,
 
     /**
-     * Purge EVERY configured provider's token record for `subject` — only the vault knows the full set. A
+     * Purge EVERY provider's token record for `subject` — the declared ones, and any undeclared one the vault
+     * still holds a row for (OPE-2560) — only the vault knows the full set. A
      * provider whose purge THROWS does not stop the others, and it rethrows only if every one failed.
      */
-    async forgetAll(subject: OeOauthSubject): Promise<number> {
+    async forgetAll(subject: OeOauthSubject, onUnrevoked?: (providerRef: string) => void): Promise<number> {
       let purged = 0;
       let failures = 0;
       let lastError: unknown;
       const all = providersNow();
       for (const providerRef of all.keys()) {
         try {
-          if (await forget(providerRef, subject)) purged++;
+          if (await forget(providerRef, subject, onUnrevoked)) purged++;
         } catch (e) {
           failures++;
           lastError = e;
         }
       }
+      // (OPE-2560) A token row for a connection that is NOT declared here is still a live grant at rest: a
+      // declaration an operator removed, or a process that declares none at all (the `oe erase` operator CLI
+      // loads no connection module). Its ref names the provider, so it goes through the same `forget`: revoked at
+      // the provider when the stored DCR client names a revocation endpoint, then deleted. A static provider's
+      // client lives only in its declaration, so with none its token is deleted locally and cannot be revoked.
+      // The ref is `oe-oauth:tok:<providerRef>:<subject key>`; a provider ref holds no ':', so the split is exact.
+      const tokPrefix = "oe-oauth:tok:";
+      const tokSuffix = `:${subjectKey(subject)}`;
+      let undeclaredAttempts = 0;
+      try {
+        for (const ref of await vault.listRefs(tokPrefix)) {
+          if (!ref.endsWith(tokSuffix)) continue;
+          const providerRef = ref.slice(tokPrefix.length, ref.length - tokSuffix.length);
+          if (providerRef.length === 0 || providerRef.includes(":") || all.has(providerRef)) continue;
+          undeclaredAttempts++;
+          try {
+            if (await forget(providerRef, subject, onUnrevoked)) purged++;
+          } catch (e) {
+            failures++;
+            lastError = e;
+          }
+        }
+      } catch (e) {
+        failures++;
+        lastError = e;
+        undeclaredAttempts++;
+      }
       // (OPE-2453) A person's IdP grant is shared by every `xaa` connection naming one IdP client, so it is purged
       // once per IdP client, after the per-connection rows. It is the credential that mints all of them.
       const seenIdp = new Set<string>();
@@ -775,7 +845,7 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
         if (!isXaa(cfg) || seenIdp.has(idpKey(cfg))) continue;
         seenIdp.add(idpKey(cfg));
         try {
-          if (await forgetIdpGrant(cfg, subject)) purged++;
+          if (await forgetIdpGrant(cfg, subject, onUnrevoked)) purged++;
         } catch (e) {
           failures++;
           lastError = e;
@@ -800,7 +870,7 @@ export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOau
       }
       // "Every purge attempt failed" counts only the attempts that ran: the orphan sweep is one attempt only when
       // it failed. Counting it always would let a purge where every provider failed return 0 with no error.
-      if (failures > 0 && purged === 0 && failures === all.size + seenIdp.size + (orphanFailed ? 1 : 0)) throw lastError;
+      if (failures > 0 && purged === 0 && failures === all.size + undeclaredAttempts + seenIdp.size + (orphanFailed ? 1 : 0)) throw lastError;
       return purged;
     },
 

package/agent/oe-oauth/user-auth-flow.ts

@@ -2,7 +2,7 @@
 // vault. The callback completer shares ONE vault instance, so the single-flight lock covers both paths.
 
 import type { TokenResult } from "eve/connections";
-import type { UserAuthFlowProvider, UserAuthSubject, UserTokenMintParams, OeOauthCallbackCompleter, CredentialPurgeHook } from "@open-everywhere/core/agent/adapter-api.js";
+import type { UserAuthFlowProvider, UserAuthSubject, UserTokenMintParams, OeOauthCallbackCompleter, CredentialPurgeHook, CredentialPurgeReport } from "@open-everywhere/core/agent/adapter-api.js";
 import { makeOeOauthTokenVault, type OeOauthProviderSource, type OeOauthVaultDeps, type OeOauthSubject } from "./token-vault.js";
 import { isUserAuthRequiredError } from "./errors.js";
 
@@ -66,8 +66,9 @@ export function makeOeOauth(
   // The credential-purge hook, sharing the mint methods' vault: whatever this adapter can MINT for a subject it
   // can also DESTROY. There is no app-subject purge — the service identity is not a person.
   const purge: CredentialPurgeHook = {
-    async purgeSubject(subjectId: string): Promise<number> {
-      return vault.forgetAll({ type: "user", id: subjectId });
+    async purgeSubject(subjectId: string, report?: CredentialPurgeReport): Promise<number> {
+      // OPE-2565: a revocation the provider refused twice is reported, so the purge's caller records it as a failure.
+      return vault.forgetAll({ type: "user", id: subjectId }, report ? (providerRef) => report.unrevoked(providerRef) : undefined);
     },
   };
 

package/agent/operator-holders.ts

@@ -0,0 +1,47 @@
+// THE HOLDERS AN OPERATOR PROCESS NEEDS TO END A PERSON'S AUTHORITY (OPE-2560) — the credential-purge
+// hooks and the long-lived box backend, registered for `oe erase` outside the deployed agent.
+//
+// WHY THIS IS NOT `registerDefaultAdapters()`. That call is the app's boot: it declares the provider
+// selection, runs every provider bundle's register(), reads the app's memory config and reconciles
+// slash commands. An operator process has none of the app's modules, and it needs none of that. It needs
+// exactly the two seams `revokeLinkSet` and `forgetBrowser` reach: the holders of per-person credentials,
+// and the backend that holds the person's saved browser profile.
+//
+// THE PURGE HOOKS ARE THE BOOT'S OWN. "oe-oauth" is the same hook `registerOeOauth()` registers. With no
+// connection module loaded it declares no provider, so its undeclared-token sweep (token-vault.ts
+// `forgetAll`) finds the person's rows by ref. "aws-sso" registers ALWAYS here, unlike at boot (where the
+// `aws.enabled` setting gates it): this process cannot read that setting, and a purge of a row that is not
+// there deletes nothing and returns 0.
+//
+// 🔴 THE BOX BACKEND IS NAMED, NEVER GUESSED. `selectLongLivedBoxBackend()` reads `onVercel()` and the
+// app's `sandbox` settings, and an operator's laptop has neither: it would pick docker for a Vercel
+// deployment, and a docker forget of a missing volume succeeds. The browser record would then be deleted
+// while the profile, with the person's logins, stayed on Vercel. So the operator names the backend
+// (`oe erase --box-backend vercel|docker`), and with none named no backend registers: core's
+// `forgetBrowser` then refuses and keeps the record.
+
+import { registerCredentialPurgeHook, registerLongLivedBoxBackend } from "@open-everywhere/core/agent/adapter-api.js";
+import { makeOeOauth } from "./oe-oauth/user-auth-flow.js";
+import { loadOeOauthConfig } from "./oe-oauth/config.js";
+import { makeAwsSsoPurgeHook } from "./aws/sso.js";
+import { createDockerBoxBackend, createVercelBoxBackend } from "./sandbox/long-lived-box.js";
+
+/** The box backends an operator can name: the two `selectLongLivedBoxBackend()` picks that can run a box (not justbash). */
+export const OPERATOR_BOX_BACKENDS = ["vercel", "docker"] as const;
+export type OperatorBoxBackend = (typeof OPERATOR_BOX_BACKENDS)[number];
+
+/** What {@link registerOperatorHolders} registered, for the CLI to print. */
+export interface OperatorHolders {
+  readonly purgeHooks: readonly string[];
+  readonly boxBackend: OperatorBoxBackend | undefined;
+}
+
+/** Register the purge hooks, and the named box backend when one is named. Idempotent overwrite. */
+export function registerOperatorHolders(opts: { readonly boxBackend?: OperatorBoxBackend } = {}): OperatorHolders {
+  const { purge } = makeOeOauth(() => loadOeOauthConfig() ?? new Map());
+  registerCredentialPurgeHook("oe-oauth", purge);
+  registerCredentialPurgeHook("aws-sso", makeAwsSsoPurgeHook());
+  if (opts.boxBackend === "vercel") registerLongLivedBoxBackend(createVercelBoxBackend());
+  else if (opts.boxBackend === "docker") registerLongLivedBoxBackend(createDockerBoxBackend());
+  return { purgeHooks: ["oe-oauth", "aws-sso"], boxBackend: opts.boxBackend };
+}

package/agent/postgres/neon.ts

@@ -85,7 +85,7 @@ interface NeonConfig {
  * Point the driver at a local `wsproxy` so it reaches a plain Postgres over the compose network. NO-OP unless
  * OE_NEON_WS_PROXY is set. Insecure WS is correct for a same-network local proxy ONLY, never a remote one.
  */
-export function configureLocalWsProxy(neonConfig: NeonConfig): void {
+function configureLocalWsProxy(neonConfig: NeonConfig): void {
   const proxy = process.env.OE_NEON_WS_PROXY?.trim();
   if (!proxy) return;
   neonConfig.wsProxy = (host, port) => `${proxy}/v1?address=${host}:${port}`;

package/dist/agent/aws/sso.d.ts

@@ -1,7 +1,6 @@
-import { checkAwsSsoIdentityBinding, OE_AWS_SSO_CALLBACK_PATH, type AwsCredentials, type AwsIdentityRequest, type AwsSsoLinkStore, type CredentialPurgeHook, type EncryptedKvVault } from "@open-everywhere/core/agent/adapter-api.js";
+import { checkAwsSsoIdentityBinding, type AwsCredentials, type AwsIdentityRequest, type AwsSsoLinkStore, type CredentialPurgeHook, type EncryptedKvVault } from "@open-everywhere/core/agent/adapter-api.js";
 /** A `fetch`-shaped transport — the DI seam the offline test injects (defaults to global fetch). */
 export type FetchLike = typeof fetch;
-export { OE_AWS_SSO_CALLBACK_PATH };
 /** The acting principal has not linked their Identity Center identity (or their token is dead and must
  *  be re-linked). Carries the authorization URL so the caller can relay a "connect your AWS account"
  *  link. Stable `code` so it is duck-typed (cross-module) as authorization-required, mirroring the

package/dist/agent/aws/sso.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sso.d.ts","sourceRoot":"","sources":["../../../agent/aws/sso.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACtB,MAAM,4CAA4C,CAAC;AAGpD,oGAAoG;AACpG,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;AAGrC,OAAO,EAAE,wBAAwB,EAAE,CAAC;AA4CpC;;;uEAGuE;AACvE,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,2BAA2B;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,YAAY,gBAAgB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAWhD;CACF;AAED;uFACuF;AACvF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAIxD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,gBAAqC,GAAG,eAAe,CAYjG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,gBAAqC,GAAG,mBAAmB,CAMrG;AAED;sEACsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,yGAAyG;AACzG,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6GAA6G;IAC7G,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;6GACyG;IACzG,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC;;;;2GAIuG;IACvG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,0BAA0B,CAAC;IAC1D,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,iCAAiC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,sGAAsG;AACtG,MAAM,WAAW,YAAY;IAC3B;;wFAEoF;IACpF,IAAI,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACvD;;6BAEyB;IACzB,SAAS,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D;;mGAE+F;IAC/F,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF;AAmBD;yGACyG;AACzG,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASrF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAa9E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,mBAAwB,GAAG,YAAY,CAoU7E"}
+{"version":3,"file":"sso.d.ts","sourceRoot":"","sources":["../../../agent/aws/sso.ts"],"names":[],"mappings":"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"}