cartethyia 2.7.8 → 2.7.9

package/src/protocol/upstream/send-claude-messages.ts

@@ -10,6 +10,7 @@ import { applyRouteUserAgent, type ProviderDispatchContext } from "../../provide
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from '../../providers/operations/upstream-deadline';
 import { mapClaudeHttpError } from '../messages-errors';
 import { isRecord } from '../codecs';
+import { upstreamMessageAsIs, MAX_UPSTREAM_ERROR_BYTES } from '../../transport/failure-policy';
 import { parseClaudeSseStream, claudeResponseToEvents } from '../response/messages';
 
 export async function* sendClaudeMessagesRequest(
@@ -67,20 +68,30 @@ export async function* sendClaudeMessagesRequest(
   try {
     json = JSON.parse(body) as unknown;
   } catch {
+    const fallback = "Claude response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙";
+    const upstreamText = upstreamMessageAsIs(body, "");
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙",
-      {},
+      upstreamText.message || fallback,
+      {
+        raw: body.slice(0, MAX_UPSTREAM_ERROR_BYTES),
+        ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
+      },
       "upstream",
     );
   }
   if (!isRecord(json)) {
+    const fallback = "Claude response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙";
+    const upstreamText = upstreamMessageAsIs(body, "");
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Claude response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙",
-      {},
+      upstreamText.message || fallback,
+      {
+        raw: body.slice(0, MAX_UPSTREAM_ERROR_BYTES),
+        ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
+      },
       "upstream",
     );
   }

package/src/protocol/upstream-parsing.ts

@@ -71,7 +71,7 @@ export function parseUpstreamBackoff(headers: {
  *
  *   - **Relative** — "quota will reset in 3 hours", "try again in 30s".
  *   - **Absolute** — "your usage will reset at 2026-09-24 02:12:51 UTC+8"
- *     (WorkBuddy/CodeBuddy `6004`). An absolute stamp is *not* a duration, and
+ *     (CodeBuddy `6004`). An absolute stamp is *not* a duration, and
  *     the relative-only pattern silently missed it, so the account fell back to
  *     the generic 15-minute default while the provider had actually parked it
  *     for the rest of the window — the account kept re-entering rotation and

package/src/providers/adapters/compatible-adapter.ts

@@ -6,9 +6,9 @@ import {
   isContextLengthFailure,
   throwIfHtmlResponse,
   mapUpstreamHttpError,
-  extractUpstreamMessage,
   extractHtmlTitle,
   upstreamErrorIdentifier,
+  upstreamMessageAsIs,
 } from "../../transport/failure-policy";
 import { applyRouteUserAgent, type ProviderDispatchTarget, type ProviderId, type ProviderDispatchContext } from "../provider-contracts";
 import { BaseProviderAdapter } from "./base-adapter";
@@ -439,11 +439,12 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
         }
         json = parsed as Record<string, unknown>;
       } catch {
-        const summary = extractHtmlTitle(raw) || raw.trim() || `HTTP ${res.status}`;
+        const fallback = `Upstream returned a non-JSON response: ${extractHtmlTitle(raw) || raw.trim() || `HTTP ${res.status}`} (request {requestId}). The connection ghosted us — come back in a moment 👻`;
+        const upstreamText = upstreamMessageAsIs(raw, "");
         throw new GatewayError(
           "transport_unavailable",
           502,
-          `Upstream returned a non-JSON response: ${summary} (request {requestId}). The connection ghosted us — come back in a moment 👻`.slice(0, 320),
+          `${upstreamText.message || fallback}`.slice(0, 500),
           { upstreamStatus: res.status, contentType },
           "upstream",
         );
@@ -485,15 +486,16 @@ export class OpenAICompatibleAdapter extends BaseProviderAdapter {
         const classification = isContextLengthFailure(json)
           ? { code: "context_length_exceeded" as const, status: 413, origin: "upstream" as const, credentialEvidence: false, rateLimitScope: undefined }
           : classifyUpstreamError(providerStatus, identifier);
-        const message = extractUpstreamMessage(json) || "Upstream reported an error";
+        const upstreamText = upstreamMessageAsIs(json, "");
         throw new GatewayError(
           classification.code,
           classification.status,
-          message,
+          upstreamText.message || "Upstream reported an error",
           {
             providerId: this.provider_id,
             ...(providerStatus === undefined ? {} : { providerStatus }),
             ...(identifier === undefined ? {} : { providerCode: identifier }),
+            ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
             ...(classification.credentialEvidence ? { credentialEvidence: true } : {}),
             ...(classification.rateLimitScope
               ? { rateLimitScope: classification.rateLimitScope }

package/src/providers/authentication/oauth-refresh-service.ts

@@ -169,6 +169,22 @@ async function releaseLease(
     );
 }
 
+/**
+ * D21 invariant guard: a refresh is not a health verdict, so mutating the
+ * account's `status` here would silently re-enable an account a refresh was
+ * never meant to resurrect. The `.set()` calls in `persistRefreshed` accept
+ * `status` at the type level (it is a column on `provider_accounts`), so the
+ * guard is a runtime assertion that fails loudly in development instead of
+ * letting a future edit change health state from the refresh path.
+ */
+function assertRefreshNeverMutatesStatus(set: Record<string, unknown>): void {
+  if ("status" in set) {
+    throw new Error(
+      "persistRefreshed must never write `status`; a refresh is not a health verdict",
+    );
+  }
+}
+
 /** Persists a successful refresh and releases the lease, fenced on still holding it. */
 async function persistRefreshed(
   db: CartethyiaDatabase,
@@ -177,16 +193,21 @@ async function persistRefreshed(
   result: OAuthTokenRefreshResult,
 ): Promise<boolean> {
   return db.transaction(async (tx) => {
+    // This function must never write `status`; a refresh is not a health
+    // verdict. The guard below makes an accidental status write a loud dev
+    // failure rather than a silent re-enable.
+    const oauthSet = {
+      ...(result.refresh === undefined
+        ? {}
+        : { refreshCiphertext: encryptCredential(result.refresh) }),
+      expiresAt: result.expiresAt,
+      leaseOwner: null,
+      leaseExpiresAt: null,
+    };
+    assertRefreshNeverMutatesStatus(oauthSet);
     const leaseRows = await tx
       .update(providerOauthStates)
-      .set({
-        ...(result.refresh === undefined
-          ? {}
-          : { refreshCiphertext: encryptCredential(result.refresh) }),
-        expiresAt: result.expiresAt,
-        leaseOwner: null,
-        leaseExpiresAt: null,
-      })
+      .set(oauthSet)
       .where(
         and(
           eq(providerOauthStates.providerAccountId, accountId),
@@ -195,23 +216,27 @@ async function persistRefreshed(
       )
       .returning({ id: providerOauthStates.providerAccountId });
     if (leaseRows.length === 0) return false;
+    const accountSet = {
+      credentialCiphertext: encryptCredential(result.access),
+      // Only what the refresh reported: a refresher that learned nothing new
+      // leaves the stored configuration alone rather than blanking it.
+      // A learned identity only replaces a default label — an operator's
+      // custom rename is never overwritten. The CASE keeps the read and the
+      // write in one statement, so a concurrent rename cannot lose to the
+      // refresh's learned identity.
+      ...(result.accountLabel === undefined
+        ? {}
+        : {
+          label: sql`CASE WHEN lower(trim(${providerAccounts.label})) = lower(trim(${providerAccounts.providerId})) THEN ${result.accountLabel} ELSE ${providerAccounts.label} END`,
+        }),
+      ...(result.auth_state === undefined ? {} : { authState: result.auth_state }),
+    };
+    // The second half of the D21 invariant: the credential write must never
+    // touch the account's health state either.
+    assertRefreshNeverMutatesStatus(accountSet);
     await tx
       .update(providerAccounts)
-      .set({
-        credentialCiphertext: encryptCredential(result.access),
-        // Only what the refresh reported: a refresher that learned nothing new
-        // leaves the stored configuration alone rather than blanking it.
-        // A learned identity only replaces a default label — an operator's
-        // custom rename is never overwritten. The CASE keeps the read and the
-        // write in one statement, so a concurrent rename cannot lose to the
-        // refresh's learned identity.
-        ...(result.accountLabel === undefined
-          ? {}
-          : {
-            label: sql`CASE WHEN lower(trim(${providerAccounts.label})) = lower(trim(${providerAccounts.providerId})) THEN ${result.accountLabel} ELSE ${providerAccounts.label} END`,
-          }),
-        ...(result.auth_state === undefined ? {} : { authState: result.auth_state }),
-      })
+      .set(accountSet)
       .where(eq(providerAccounts.id, accountId));
     invalidateCredentialCache(accountId);
     return true;
@@ -240,12 +265,21 @@ function buildRefreshContext(row: AccountRow, includeAccessToken: boolean): OAut
 /**
  * Marks an account permanently unusable after a definitive refresh failure,
  * fenced on the lease.
+ *
+ * @param preserveOperatorDisable When true, an account that is already
+ *   `disabled` with no `cooldownUntil` — the operator's own disable — keeps its
+ *   lack of a recovery deadline (D23). A machine disable (this function being
+ *   the machine) always writes a deadline for itself, but it must not convert
+ *   an operator's terminal decision into a recoverable one: adding a deadline
+ *   to an operator-disabled row is what made the Recover button appear on an
+ *   account the operator disabled on purpose.
  */
 async function disableAccount(
   db: CartethyiaDatabase,
   accountId: string,
   owner: string,
   message: string,
+  options: { readonly preserveOperatorDisable?: boolean } = {},
 ): Promise<void> {
   await db.transaction(async (tx) => {
     const leaseRows = await tx
@@ -260,6 +294,22 @@ async function disableAccount(
       .returning({ id: providerOauthStates.providerAccountId });
     if (leaseRows.length === 0) return;
     const disabledRecoveryMs = resolveAccountDisabledRecoveryMs();
+    // D23: read the row before writing so an operator disable (status `disabled`
+    // with no deadline) is not upgraded with a machine recovery deadline. The
+    // read is cheap and the lease already serializes refresh writers.
+    let isOperatorDisable = false;
+    if (options.preserveOperatorDisable === true) {
+      const rows = await tx
+        .select({
+          status: providerAccounts.status,
+          cooldownUntil: providerAccounts.cooldownUntil,
+        })
+        .from(providerAccounts)
+        .where(eq(providerAccounts.id, accountId))
+        .limit(1);
+      const row = rows[0];
+      isOperatorDisable = row?.status === "disabled" && row.cooldownUntil == null;
+    }
     await tx
       .update(providerAccounts)
       .set({
@@ -277,8 +327,10 @@ async function disableAccount(
         // parks the credential for good. The deadline is also what distinguishes
         // this (machine-disabled) from an operator's own disable, which leaves
         // `cooldownUntil` null and is therefore never swept. See
-        // `resolveAccountDisabledRecoveryMs`.
-        ...(disabledRecoveryMs > 0
+        // `resolveAccountDisabledRecoveryMs`. An operator-disabled row keeps its
+        // `null` deadline (D23): the machine must not make the operator's
+        // terminal disable look recoverable.
+        ...(!isOperatorDisable && disabledRecoveryMs > 0
           ? { cooldownUntil: new Date(Date.now() + disabledRecoveryMs) }
           : {}),
       })
@@ -299,20 +351,33 @@ async function disableAccount(
  * operator or an explicit recovery may re-enable it), while an `active` one
  * stays `active`. The static marker and the error clearing are orthogonal to
  * the account's health state.
+ *
+ * D24: for a `disabled` row the error fields are deliberately kept. Once the
+ * account is parked, `lastErrorCategory` is the only record of *why* (e.g.
+ * `auth_invalidated` → "Re-login required"); wiping it on the static
+ * annotation would leave a disabled account with no diagnosable reason. An
+ * `active` row still clears them — there the error is stale by definition.
  */
 async function markStaticToken(db: CartethyiaDatabase, accountId: string): Promise<void> {
+  const rows = await db
+    .select({ status: providerAccounts.status })
+    .from(providerAccounts)
+    .where(eq(providerAccounts.id, accountId))
+    .limit(1);
+  const isDisabled = rows[0]?.status === "disabled";
   await db
     .update(providerAccounts)
     .set({
       staticToken: true,
+      cooldownUntil: null,
       // A static token is a normal, usable credential, not an error state: any
       // error left by the failed refresh would otherwise keep the row reading
       // "Re-login required" while it is in fact serving. Mirrors the console's
-      // static-token toggle.
-      cooldownUntil: null,
-      lastError: null,
-      lastErrorCategory: null,
-      lastErrorAt: null,
+      // static-token toggle. For a `disabled` row the category is preserved
+      // (D24), because there it is the diagnosis, not a stale artifact.
+      ...(isDisabled
+        ? {}
+        : { lastError: null, lastErrorCategory: null, lastErrorAt: null }),
     })
     .where(eq(providerAccounts.id, accountId));
 }
@@ -362,7 +427,8 @@ function failureStatus(error: unknown): number | undefined {
  * still perfectly usable. This pass re-reads those rows once at startup and
  * moves each to where it now belongs:
  *
- *  - access token still usable ⇒ static token, back to `active`;
+ *  - access token still usable ⇒ static token; the account stays `disabled`;
+ *    only an operator can re-enable it;
  *  - otherwise ⇒ the `auth_invalidated` category the console renders as
  *    "Re-login required" and the quota sweep excludes.
  *
@@ -495,15 +561,20 @@ export class OAuthRefreshService {
    * that just refreshed cannot cause the caller to reuse a dead cached
    * secret. Returns the current decrypted access token, or `null` when the
    * account isn't OAuth, has no stored refresh token, or refresh failed.
+   *
+   * `opts.origin` labels who asked for the refresh (`ui`/`sweep`/`dispatch`)
+   * and is carried on the `token_refresh` log lines (D26). The origin is
+   * observational only — it never changes what a refresh does.
    */
   async ensureFreshAccessToken(
     accountId: string,
     refresher: OAuthTokenRefresher,
-    opts: { force?: boolean; skewMs?: number } = {},
+    opts: { force?: boolean; skewMs?: number; origin?: "ui" | "sweep" | "dispatch" } = {},
   ): Promise<string | null> {
     const force = opts.force === true;
     // No explicit skew: the per-provider lead is applied at load time.
     const skewMs = opts.skewMs;
+    const origin = opts.origin ?? "sweep";
     // Forced refreshes get their own in-flight slot so they don't merge with
     // a raced non-force call that would otherwise short-circuit.
     const key = force ? `${accountId}:force` : accountId;
@@ -518,7 +589,7 @@ export class OAuthRefreshService {
       const oldestKey = this.#inFlight.keys().next().value;
       if (oldestKey !== undefined) this.#inFlight.delete(oldestKey);
     }
-    const task = this.#refreshIfDue(accountId, refresher, skewMs, force).finally(() => {
+    const task = this.#refreshIfDue(accountId, refresher, skewMs, force, origin).finally(() => {
       this.#inFlight.delete(key);
     });
     this.#inFlight.set(key, task);
@@ -530,6 +601,7 @@ export class OAuthRefreshService {
     refresher: OAuthTokenRefresher,
     skewMs: number | undefined,
     force: boolean,
+    origin: "ui" | "sweep" | "dispatch",
   ): Promise<string | null> {
     const account = await loadAccountWithFreshness(this.#db, accountId, skewMs);
     if (!account || account.row.credentialKind !== "oauth") return null;
@@ -547,18 +619,24 @@ export class OAuthRefreshService {
         ? decryptCredentialToString(row.credentialCiphertext)
         : null;
     }
-    return this.#refreshNow(row, refresher, skewMs);
+    return this.#refreshNow(row, refresher, skewMs, origin);
   }
 
   async #refreshNow(
     row: AccountRow,
     refresher: OAuthTokenRefresher,
     skewMs: number | undefined,
+    origin: "ui" | "sweep" | "dispatch",
   ): Promise<string | null> {
+    // D26: statusBefore is read once up front (the row projection used by the
+    // refresh path does not carry status) and statusAfter is re-read after any
+    // mutation, so the log proves a refresh never flipped the account.
+    const statusBefore = await readAccountStatus(this.#db, row.id);
     pushStructuredConsoleLog("info", "OAuth token refresh started", {
       event: "token_refresh",
       accountId: row.id,
       providerId: row.providerId,
+      details: { origin, statusBefore },
     });
     const owner = randomUUID();
     const leased = await acquireLease(this.#db, row.id, owner);
@@ -583,6 +661,7 @@ export class OAuthRefreshService {
         accountId: row.id,
         providerId: row.providerId,
         errorCode: "static_token",
+        details: { origin },
       });
       return null;
     }
@@ -594,12 +673,20 @@ export class OAuthRefreshService {
         buildRefreshContext(row, refresher.requiresAccessToken === true),
       );
       const persisted = await persistRefreshed(this.#db, row.id, owner, result);
+      // D26: `statusAfter` is re-read from the DB rather than assumed — a
+      // successful refresh never changes `status`, and the log proves it.
+      const statusAfter = await readAccountStatus(this.#db, row.id);
       pushStructuredConsoleLog(persisted ? "info" : "warn", persisted ? "OAuth token refresh completed" : "OAuth token refresh lost lease", {
         event: "token_refresh",
         accountId: row.id,
         providerId: row.providerId,
         ...(persisted ? {} : { errorCode: "refresh_lease_lost" }),
-        details: { expiresAt: result.expiresAt.toISOString() },
+        details: {
+          expiresAt: result.expiresAt.toISOString(),
+          origin,
+          statusBefore,
+          statusAfter,
+        },
       });
       return persisted ? result.access : null;
     } catch (error) {
@@ -612,6 +699,7 @@ export class OAuthRefreshService {
         accountId: row.id,
         providerId: row.providerId,
         errorCode: classification,
+        details: { origin, statusBefore },
       });
       if (classification === "definitive") {
         // A definitive refresh failure means the refresh grant is dead — but
@@ -627,14 +715,29 @@ export class OAuthRefreshService {
         if (accessUsability === "usable") {
           await releaseLease(this.#db, row.id, owner);
           await markStaticToken(this.#db, row.id);
+          const statusAfter = await readAccountStatus(this.#db, row.id);
           pushStructuredConsoleLog("info", "OAuth refresh failed; access token still valid, marking static", {
             event: "token_refresh",
             accountId: row.id,
             providerId: row.providerId,
             errorCode: "static_token",
+            details: { origin, statusBefore, statusAfter },
           });
         } else {
-          await disableAccount(this.#db, row.id, owner, failureMessage(error));
+          await disableAccount(this.#db, row.id, owner, failureMessage(error), {
+            // D23: a definitive refresh failure must not turn an operator's
+            // disable into a machine-recoverable one. If the row is already
+            // `disabled` without a deadline, leave it that way.
+            preserveOperatorDisable: true,
+          });
+          const statusAfter = await readAccountStatus(this.#db, row.id);
+          pushStructuredConsoleLog("warn", "OAuth refresh failed definitively; account disabled for re-auth", {
+            event: "token_refresh",
+            accountId: row.id,
+            providerId: row.providerId,
+            errorCode: classification,
+            details: { origin, statusBefore, statusAfter },
+          });
         }
       } else {
         await releaseLease(this.#db, row.id, owner);
@@ -643,3 +746,13 @@ export class OAuthRefreshService {
     }
   }
 }
+
+/** Reads one account's status (used only for logging/observability, D26). */
+async function readAccountStatus(db: CartethyiaDatabase, accountId: string): Promise<string | undefined> {
+  const rows = await db
+    .select({ status: providerAccounts.status })
+    .from(providerAccounts)
+    .where(eq(providerAccounts.id, accountId))
+    .limit(1);
+  return rows[0]?.status;
+}

package/src/providers/default-registry.ts

@@ -84,12 +84,15 @@ function traeDiscovery(
     if (rows.length === 0) return realm === "cn" ? TRAE_CN_MODELS : TRAE_INTL_MODELS;
     const fallback = realm === "cn" ? TRAE_CN_MODELS : TRAE_INTL_MODELS;
     const byId = new Map(fallback.map((model) => [model.modelId, model]));
+    // Return everything the upstream picker reports — the live listing is the
+    // truth for the account, including configs absent from the static roster.
+    // The static roster is only the fallback when discovery fails. A config
+    // discovered upstream gets the realm's first row as a template so it is
+    // routable with the shape this provider serves, carrying the window
+    // upstream reported.
     return rows.map((row) => {
       const existing = byId.get(row.id);
       if (existing === undefined) {
-        // Discovered upstream but absent from the static roster: clone the
-        // realm's first row so a new model is routable with the shape this
-        // provider serves, carrying the window upstream reported.
         const template = fallback[0];
         if (template === undefined) return undefined;
         return { ...template, modelId: row.id, contextLimit: row.ctx ?? null };
@@ -315,6 +318,20 @@ export const PROVIDER_CAPABILITIES = {
         ...(fetcher === undefined ? {} : { fetcher }),
       }),
   },
+  devin: {
+    // Devin's chat wire is a Connect-RPC protobuf stream; the path is pinned
+    // here so a probe verifies dispatch actually calls it.
+    endpointPathsByWireFamily: { chat: "/exa.api_server_pb.ApiServerService/GetChatMessage" },
+    loadAdapter: async () => (await import("./integrations/devin/devin")).devinAdapter,
+    loadModels: async () => (await import("./integrations/devin/devin-catalog")).DEVIN_MODELS,
+    loadAuthentication: oauthCapability(() => import("./integrations/devin/devin-auth"), "devinOAuthClient"),
+    loadQuotaCollector: quotaCapability(() => import("./integrations/devin/devin-quota"), "fetchDevinQuota"),
+    loadModelDiscovery: async () => async ({ credential, fetcher }) =>
+      (await import("./integrations/devin/devin-catalog")).discoverDevinModels({
+        credential,
+        ...(fetcher === undefined ? {} : { fetcher }),
+      }),
+  },
   cerebras: {
     endpointPathsByWireFamily: { chat: "/chat/completions" },
     loadAdapter: async () => createApiKeyAdapter((await import("./integrations/cerebras")).CEREBRAS_SPEC),
@@ -514,6 +531,51 @@ export const PROVIDER_CAPABILITIES = {
     loadQuotaCollector: quotaCapability(() => import("./integrations/trae/trae-quota"), "fetchTraeCnQuota"),
     loadModelDiscovery: traeDiscovery("cn", "traecn"),
   },
+  freepi: {
+    loadAdapter: async () => (await import("./integrations/freepi/freepi")).createFreepiAdapter(),
+    loadModels: async () => (await import("./integrations/freepi/freepi-catalog")).FREEPI_MODELS,
+    // Free-pi login is a GitHub device flow; the issued JWT is the credential.
+    loadAuthentication: oauthCapability(() => import("./integrations/freepi/freepi-oauth"), "freepiOAuthClient"),
+    loadQuotaCollector: quotaCapability(() => import("./integrations/freepi/freepi-quota"), "fetchFreepiQuota"),
+    // Live `/client-version` (Bearer) is the catalog source; the static roster
+    // is the offline fallback.
+    loadModelDiscovery: async () => async (request: Parameters<ProviderModelDiscovery>[0]) => {
+      const { discoverFreepiModels } = await import("./integrations/freepi/freepi-discovery");
+      const { FREEPI_MODELS } = await import("./integrations/freepi/freepi-catalog");
+      const secret = request.credential.trim();
+      const fetcher = request.fetcher as unknown as typeof fetch | undefined;
+      if (secret.length === 0 || fetcher === undefined) return FREEPI_MODELS;
+      let token = secret;
+      if (secret.startsWith("{")) {
+        try {
+          const parsed = JSON.parse(secret) as Record<string, unknown>;
+          const found = ["accessToken", "access_token", "token"].find(
+            (key) => typeof parsed[key] === "string" && (parsed[key] as string).length > 0,
+          );
+          if (found !== undefined) token = parsed[found] as string;
+        } catch {
+          // Use the raw secret as the token.
+        }
+      }
+      const rows = await discoverFreepiModels({ token, fetcher });
+      if (rows.length === 0) return FREEPI_MODELS;
+      return rows;
+    },
+  },
+  perch: {
+    loadAdapter: async () => (await import("./integrations/perch/perch")).createPerchAdapter(),
+    loadModels: async () => (await import("./integrations/perch/perch-catalog")).PERCH_MODELS,
+    // Perch login is Supabase PKCE (Google/GitHub); the session blob
+    // (access/refresh token) is the credential, and the CLI refreshes it.
+    loadAuthentication: oauthCapability(() => import("./integrations/perch/perch-oauth"), "perchOAuthClient", { withRefresher: true }),
+    loadQuotaCollector: quotaCapability(() => import("./integrations/perch/perch-quota"), "fetchPerchQuota"),
+    // The hosted API exposes no public model list — Roost tiers are the only
+    // surface the CLI accepts, so discovery returns the static roster.
+    loadModelDiscovery: async () => async () => {
+      const { PERCH_MODELS } = await import("./integrations/perch/perch-catalog");
+      return PERCH_MODELS;
+    },
+  },
   inferhub: {
     loadAdapter: async () => (await import("./integrations/inferhub")).createInferhubAdapter(),
     // Live `/v1/models` is the primary source: the marketplace republishes its
@@ -527,6 +589,9 @@ export const PROVIDER_CAPABILITIES = {
   hermes: {
     loadAdapter: async () => createApiKeyAdapter((await import("./integrations/hermes")).HERMES_SPEC),
     loadModels: async () => (await import("./integrations/hermes")).HERMES_MODELS,
+    // Hermes accepts both API keys and the Nous Portal device-code OAuth flow
+    // (subscription route). The OAuth client is refreshable.
+    loadAuthentication: oauthCapability(() => import("./integrations/hermes/hermes-oauth"), "hermesOAuthClient", { withRefresher: true }),
     // `/v1/models` is open and states each row's real limits, so the free
     // allowance tracks upstream instead of a hand-kept list. The static list
     // above stays as the offline fallback for a fetch that fails.

package/src/providers/discovery/discovery-types.ts

@@ -58,6 +58,11 @@ export const PROBE_REASONING_EFFORTS = ["auto", "minimal", "low", "medium", "hig
 /** One accepted probe reasoning effort. `auto` means "send no reasoning intent". */
 export type ProbeReasoningEffort = (typeof PROBE_REASONING_EFFORTS)[number];
 
+/** Modelprobe modes as a runtime tuple, so the route schema projects one list. */
+export const PROBE_MODES = ["fast", "detail"] as const;
+/** `detail` is the default when `mode` is absent (D39). */
+export type ProbeMode = (typeof PROBE_MODES)[number];
+
 /** Request accepted for a one-shot model connectivity test. `route`
  * disambiguates when a model id is registered under multiple endpoint
  * paths; omit it to probe against the model's already-registered wire
@@ -85,6 +90,13 @@ export interface ProbeModelRequest {
    * result the richest available source of truth.
    */
   surface?: "default" | "cosy" | "grpc" | "ide";
+  /**
+   * `fast` is a cheap liveness check: 32 output tokens, a 10s timeout, no
+   * retry, no payload-body capture, compact telemetry, and an 80-char sample.
+   * `detail` (the default when absent) is the full diagnostic probe.
+   * Health recording is identical in both modes.
+   */
+  mode?: ProbeMode;
 }
 export interface ProbeModelResult {
   accountId?: string;