cartethyia 2.7.9 → 2.8.0

package/src/providers/integrations/grok/grok-oauth.ts

@@ -1,13 +1,14 @@
 /** xAI Grok Build device-code OAuth client. */
-import { devicePollBackoff, nonEmptyTrimmedString, parseDeviceAuthStart, postFormTokenRequest, readJsonResponse } from "../../authentication/oauth-flow-store";
+import { devicePollBackoff, nonEmptyTrimmedString, parseDeviceAuthStart, postFormTokenRequest, readJsonResponse, record } from "../../authentication/oauth-flow-store";
 import type {
   OAuthDeviceFlowContext,
   OAuthDevicePollResult,
   OAuthDeviceStartResult,
+  OAuthExchangeResult,
 } from "../../authentication/oauth-flow-store";
 import type { OAuthTokenRefreshResult } from "../../authentication/oauth-refresh-service";
 import { OAuthDeviceFlow } from "../../authentication/oauth-device-flow";
-import type { FetchLike } from "../../authentication/oauth-client";
+import type { FetchLike, NormalizedTokenResponse } from "../../authentication/oauth-client";
 import { XAI_AUTH_SERVER } from "../xai/xai-oauth";
 
 /**
@@ -178,56 +179,58 @@ export class GrokOAuthClient extends OAuthDeviceFlow {
   }
 
   override async pollDeviceAuth(deviceAuthId: string, _context?: OAuthDeviceFlowContext): Promise<OAuthDevicePollResult> {
-    const body = new URLSearchParams({
-      grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-      device_code: deviceAuthId,
-      client_id: GROK_CLIENT_ID,
-    });
-    const response = await this.fetchFn(GROK_TOKEN_URL, {
-      method: "POST",
-      headers: authHeaders(),
-      body,
+    return this.pollGenericDeviceAuth(deviceAuthId, {
+      tokenUrl: GROK_TOKEN_URL,
+      deviceAuthUrl: GROK_DEVICE_URL,
+      clientId: GROK_CLIENT_ID,
+      formHeaders: authHeaders(),
     });
-    const raw = await response.text();
-    let payload: TokenPayload;
-    try {
-      payload = JSON.parse(raw) as TokenPayload;
-    } catch {
-      return { status: "failed", reason: "grok token endpoint returned invalid JSON" };
-    }
-    const error = nonEmptyTrimmedString(payload.error);
-    const verdict = devicePollBackoff(error, payload.interval);
-    if (verdict !== undefined) return verdict;
-    if (!response.ok) {
-      return { status: "failed", reason: nonEmptyTrimmedString(payload.error_description) ?? error ?? `token polling failed (${response.status})` };
-    }
+  }
+
+  protected override unparsablePollReason(_status: number): string {
+    return "grok token endpoint returned invalid JSON";
+  }
+
+  protected override preVerdict(payload: unknown): OAuthDevicePollResult | undefined {
+    const root = record(payload) ?? {};
+    // Grok votes on the `error` field before the status: a 200 body can still
+    // state the poll state, and a pending/slow_down answer is honored wherever
+    // it appears on the wire.
+    return devicePollBackoff(nonEmptyTrimmedString(root.error), root.interval);
+  }
+
+  protected override pollFailureReason(
+    status: number,
+    errorKey: string | undefined,
+    errorDescription: string | undefined,
+  ): string {
+    // Grok's wire prefers the human-readable description over the error code,
+    // and falls back to the generic phrasing only when both are absent.
+    return nonEmptyTrimmedString(errorDescription) ?? nonEmptyTrimmedString(errorKey) ?? `token polling failed (${status})`;
+  }
+
+  protected override missingTokenReason(errorKey: string | undefined, errorDescription: string | undefined): string {
     // A 2xx is not by itself a completed authorization: the endpoint can answer
     // 200 with an `error` field and no token. Returning `failed` rather than
     // letting the shared parser throw keeps the verdict inside the poll
     // contract — the dashboard's poll error path stops polling but shows no
     // reason, so a throw would look like a spinner that never ends.
-    if (nonEmptyTrimmedString(payload.access_token) === undefined) {
-      return {
-        status: "failed",
-        reason:
-          nonEmptyTrimmedString(payload.error_description) ??
-          error ??
-          "grok token response omitted access_token",
-      };
-    }
-    const result = this.parseTokenResponse(payload);
-    const identity = await fetchGrokIdentity(result.access, this.fetchFn);
+    return nonEmptyTrimmedString(errorDescription) ?? nonEmptyTrimmedString(errorKey) ?? "grok token response omitted access_token";
+  }
+
+  protected override async afterDeviceTokenExchange(
+    _payload: unknown,
+    normalized: NormalizedTokenResponse,
+  ): Promise<OAuthExchangeResult> {
+    const identity = await fetchGrokIdentity(normalized.access, this.fetchFn);
     const authState = grokAuthState(identity);
-    return {
-      status: "complete",
-      result: this.toExchangeResult({
-        ...result,
-        ...(identity.label === undefined ? {} : { accountLabel: identity.label }),
-        // Omitted when the proxy reported nothing, which leaves any stored
-        // state alone rather than blanking it.
-        ...(authState === undefined ? {} : { auth_state: authState }),
-      }),
-    };
+    return this.toExchangeResult({
+      ...normalized,
+      ...(identity.label === undefined ? {} : { accountLabel: identity.label }),
+      // Omitted when the proxy reported nothing, which leaves any stored
+      // state alone rather than blanking it.
+      ...(authState === undefined ? {} : { auth_state: authState }),
+    });
   }
 
   override async refresh(refreshToken: string, signal?: AbortSignal): Promise<OAuthTokenRefreshResult> {

package/src/providers/integrations/grok/grok-ratelimit-store.ts

@@ -12,6 +12,7 @@
 // Keyed by account id: two Grok accounts carry different buckets, and a reading
 // filed against the wrong one is worse than no reading at all.
 
+import { TtlCache } from "../../../persistence/ttl-cache";
 import type { ProviderQuotaWindow } from "../../quota/quota-contracts";
 import { grokHeaderRequestsWindow, grokHeaderWindow, type GrokRateLimitReading } from "./grok-ratelimit";
 
@@ -27,39 +28,31 @@ const SNAPSHOT_TTL_MS = 5 * 60 * 1000;
 
 interface Snapshot {
   readonly windows: readonly ProviderQuotaWindow[];
-  readonly capturedAt: number;
 }
 
-const snapshots = new Map<string, Snapshot>();
+// Bounded FIFO cache keyed by account id; the TTL and `maxEntries` cap are
+// enforced by the cache itself (oldest-first eviction past 4096 entries).
+const snapshots = new TtlCache<Snapshot>({
+  ttlMs: SNAPSHOT_TTL_MS,
+  maxEntries: 4096,
+});
 
 /** Files a reading captured from a real dispatch against one account. */
 export function rememberGrokRateLimit(
   accountId: string,
   reading: GrokRateLimitReading,
-  now = Date.now(),
 ): void {
   const windows = [grokHeaderWindow(reading), grokHeaderRequestsWindow(reading)].filter(
     (value): value is ProviderQuotaWindow => value !== null,
   );
   if (windows.length === 0) return;
-  snapshots.set(accountId, { windows, capturedAt: now });
-  if (snapshots.size > 4096) {
-    // Bounded: an unbounded map keyed by account is a leak dressed as a cache.
-    for (const [key, value] of snapshots) {
-      if (now - value.capturedAt > SNAPSHOT_TTL_MS) snapshots.delete(key);
-    }
-  }
+  snapshots.set(accountId, { windows });
 }
 
 /** The stored window for one account, or `null` when none is fresh enough. */
-export function storedGrokRateLimit(accountId: string, now = Date.now()): readonly ProviderQuotaWindow[] | null {
+export function storedGrokRateLimit(accountId: string): readonly ProviderQuotaWindow[] | null {
   const snapshot = snapshots.get(accountId);
-  if (!snapshot) return null;
-  if (now - snapshot.capturedAt > SNAPSHOT_TTL_MS) {
-    snapshots.delete(accountId);
-    return null;
-  }
-  return snapshot.windows;
+  return snapshot?.windows ?? null;
 }
 
 /** Test seam. */

package/src/providers/integrations/grok/grok-turn-index.ts

@@ -13,19 +13,25 @@
  */
 
 import type { CanonicalRequest } from "../../../protocol/canonical-model";
+import { TtlCache } from "../../../persistence/ttl-cache";
 
 /** Idle window after which a session's remembered index is discarded. */
 const SESSION_TTL_MS = 30 * 60_000;
 
-/** Bound on remembered sessions; oldest insertion is evicted past this. */
+/** Bound on remembered sessions; least-recently-used is evicted past this. */
 const MAX_SESSIONS = 5_000;
 
 interface TurnEntry {
   readonly turn: number;
-  lastUsedAt: number;
 }
 
-const turns = new Map<string, TurnEntry>();
+// Bounded, LRU-ordered: a session re-inserts on every use so the newest
+// session is the last evicted, exactly as the previous delete-then-set Map.
+const turns = new TtlCache<TurnEntry>({
+  ttlMs: SESSION_TTL_MS,
+  maxEntries: MAX_SESSIONS,
+  lru: true,
+});
 const requestTurns = new WeakMap<object, number>();
 
 /** User turns in the request, floored at 1 (a turn is never index 0). */
@@ -58,25 +64,14 @@ export function resolveGrokTurnIndex(
   }
   if (sessionId === undefined || sessionId.length === 0) return fromInput;
 
-  const now = Date.now();
-  const previous = turns.get(sessionId);
-  const remembered =
-    previous !== undefined && now - previous.lastUsedAt <= SESSION_TTL_MS
-      ? previous.turn
-      : undefined;
+  const remembered = turns.get(sessionId)?.turn;
 
   // A full-history client already reports the true index; a delta-style client
   // reports 1 every time, so the stored index is advanced by one for it.
   const turn = remembered === undefined ? fromInput : Math.max(fromInput, remembered + 1);
 
   // Re-insert so the entry is newest for eviction order.
-  turns.delete(sessionId);
-  if (turns.size >= MAX_SESSIONS) {
-    const oldest = turns.keys().next();
-    if (!oldest.done) turns.delete(oldest.value);
-  }
-  turns.set(sessionId, { turn, lastUsedAt: now });
+  turns.set(sessionId, { turn });
   if (requestKey !== undefined) requestTurns.set(requestKey, turn);
   return turn;
 }
-

package/src/providers/integrations/{hermes.ts → hermes/hermes.ts}

@@ -1,10 +1,10 @@
-import type { CanonicalRequest } from "../../protocol/canonical-model";
-import type { ProviderDispatchTarget } from "../provider-contracts";
-import type { ApiKeyProviderSpec } from "../configured-provider";
-import { isRecord } from "../../protocol/codecs";
-import { boundedUpstreamArray, boundedUpstreamNumber, sanitizeUpstreamLabel } from "../provider-sanitize";
-import { getHermesVersion } from "../operations/client-versions";
-import { clineReasoningReplayPrepares } from "./buddy/buddy-chat-shared";
+import type { CanonicalRequest } from "../../../protocol/canonical-model";
+import type { ProviderDispatchTarget } from "../../provider-contracts";
+import type { ApiKeyProviderSpec } from "../../configured-provider";
+import { isRecord } from "../../../protocol/codecs";
+import { boundedUpstreamArray, boundedUpstreamNumber, sanitizeUpstreamLabel } from "../../provider-sanitize";
+import { getHermesVersion } from "../../operations/client-versions";
+import { clineReasoningReplayPrepares } from "../buddy/buddy-chat-shared";
 
 const HERMES_PROVIDER_ID = "hermes" as const;
 
@@ -57,8 +57,8 @@ function injectHermesTags(
 
 
 
-import { defineModel } from "../provider-model-definition";
-import type { ModelDefinition } from "../provider-model-definition";
+import { defineModel } from "../../provider-model-definition";
+import type { ModelDefinition } from "../../provider-model-definition";
 
 /**
  * Offline fallback: the free rows as the live catalog last reported them.

package/src/providers/integrations/hermes/index.ts

@@ -0,0 +1,2 @@
+export * from "./hermes";
+export * from "./hermes-oauth";

package/src/providers/integrations/kiro/kiro-catalog.ts

@@ -15,6 +15,22 @@ export const KIRO_GENERATE_PATH = "/generateAssistantResponse" as const;
 /** AWS region shape, checked before a region is interpolated into a URL. */
 export const AWS_REGION_PATTERN = /^[a-z]{2}-[a-z]+-\d{1,2}$/;
 
+/**
+ * Maps an auth method onto the `TokenType` header the 1.4.62 client sends.
+ *
+ * Observed map (`qje`): `api_key → API_KEY`, `external_idp → EXTERNAL_IDP`,
+ * `idc → SSO_OIDC`, `machine_token → KIRO_MACHINE_TOKEN`. Google/GitHub/
+ * Builder-ID sessions send no `TokenType` header. Every surface (dispatch,
+ * usage, discovery) must classify the same account identically or the upstream
+ * sees one credential as different token types across surfaces.
+ */
+export function kiroTokenTypeHeader(authMethod: string | undefined): string | undefined {
+  if (authMethod === "api_key") return "API_KEY";
+  if (authMethod === "external_idp") return "EXTERNAL_IDP";
+  if (authMethod === "idc") return "SSO_OIDC";
+  return undefined;
+}
+
 /** Fallback region when no (or an invalid) region is configured. */
 export const KIRO_DEFAULT_REGION = "us-east-1" as const;
 
@@ -37,7 +53,7 @@ export const KIRO_MANAGEMENT_HOST_TEMPLATE = "https://management.{region}.kiro.d
  * The upstream has no `minimal` or `max` tier on either schema, so the ladder
  * stops at `xhigh` and the builder maps the canonical extremes onto it.
  */
-const KIRO_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
+export const KIRO_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
 
 /**
  * One Kiro model row.

package/src/providers/integrations/kiro/kiro-discovery.ts

@@ -22,14 +22,19 @@ import {
 } from "../../operations/client-versions";
 import { machineIdForAuthState } from "./kiro-machine-id";
 import { resolveKiroProfileArn } from "./kiro-profile";
-import { AWS_REGION_PATTERN, KIRO_DEFAULT_REGION, KIRO_GENERATE_PATH, KIRO_MODELS, KIRO_MANAGEMENT_HOST_TEMPLATE } from "./kiro-catalog";
+import {
+  AWS_REGION_PATTERN,
+  KIRO_DEFAULT_REGION,
+  KIRO_EFFORTS,
+  KIRO_GENERATE_PATH,
+  KIRO_MODELS,
+  KIRO_MANAGEMENT_HOST_TEMPLATE,
+  kiroTokenTypeHeader,
+} from "./kiro-catalog";
 
 /** Longest model list this will read; the upstream sends a few dozen at most. */
 const MAX_DISCOVERED_MODELS = 500;
 
-/** Effort tiers the models that accept an effort field advertise. */
-const KIRO_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
-
 /** The management service target used in `x-amz-target`. */
 const KIRO_MANAGEMENT_TARGET = "KiroControlPlaneBearerService.ListAvailableModels" as const;
 
@@ -105,14 +110,7 @@ export async function fetchKiroModels(
     // `TokenType`; social/Builder-ID sessions send none. Mirror the client's
     // `qje` map and the probe verified against the live service.
     const authMethod = options.authState?.["authMethod"];
-    const tokenType =
-      authMethod === "api_key"
-        ? "API_KEY"
-        : authMethod === "external_idp"
-          ? "EXTERNAL_IDP"
-          : authMethod === "idc"
-            ? "SSO_OIDC"
-            : undefined;
+    const tokenType = kiroTokenTypeHeader(typeof authMethod === "string" ? authMethod : undefined);
     if (tokenType !== undefined) headers["TokenType"] = tokenType;
     response = await fetcher(`${host}/List-Available-Models?${params.toString()}`, {
       headers,

package/src/providers/integrations/kiro/kiro-quota.ts

@@ -34,7 +34,12 @@ import {
 } from "../../operations/client-versions";
 import { machineIdForAuthState } from "./kiro-machine-id";
 import { resolveKiroProfileArn } from "./kiro-profile";
-import { AWS_REGION_PATTERN, KIRO_DEFAULT_REGION, KIRO_MANAGEMENT_HOST_TEMPLATE } from "./kiro-catalog";
+import {
+  AWS_REGION_PATTERN,
+  KIRO_DEFAULT_REGION,
+  KIRO_MANAGEMENT_HOST_TEMPLATE,
+  kiroTokenTypeHeader,
+} from "./kiro-catalog";
 
 /**
  * The fetcher shape this module needs: a plain callable. `FetchLike` from the
@@ -82,9 +87,8 @@ function usageHeaders(credential: string, auth: KiroQuotaAuth): Record<string, s
     "user-agent": buildKiroRuntimeUserAgent(version, auth.machineId),
     "x-kiro-machineid": auth.machineId,
   };
-  if (auth.authMethod === "api_key") headers["TokenType"] = "API_KEY";
-  else if (auth.authMethod === "external_idp") headers["TokenType"] = "EXTERNAL_IDP";
-  else if (auth.authMethod === "idc") headers["TokenType"] = "SSO_OIDC";
+  const tokenType = kiroTokenTypeHeader(auth.authMethod);
+  if (tokenType !== undefined) headers["TokenType"] = tokenType;
   return headers;
 }
 

package/src/providers/integrations/kiro/kiro.ts

@@ -59,6 +59,7 @@ import {
   kiroContextWindow,
   KIRO_GENERATE_PATH,
   KIRO_RUNTIME_HOST_TEMPLATE,
+  kiroTokenTypeHeader,
 } from "./kiro-catalog";
 import { resolveInboundSessionId } from "../../operations/session-resolution";
 import { KiroStreamDecoder, isKiroTruncationReason, type KiroUsage } from "./kiro-stream";
@@ -180,19 +181,6 @@ export function kiroEndpoint(authState: KiroAuthState | undefined): string {
  */
 export const KIRO_RUNTIME_AWS_JSON_TARGET = "KiroRuntimeService.GenerateAssistantResponse" as const;
 
-/**
- * Maps an auth method onto the `TokenType` header the 1.4.62 client sends.
- *
- * Observed map (`qje`): `api_key → API_KEY`, `external_idp → EXTERNAL_IDP`,
- * `idc → SSO_OIDC`, `machine_token → KIRO_MACHINE_TOKEN`. Google/GitHub/
- * Builder-ID sessions send no `TokenType` header.
- */
-const KIRO_TOKEN_TYPE: Readonly<Record<string, string>> = {
-  api_key: "API_KEY",
-  external_idp: "EXTERNAL_IDP",
-  idc: "SSO_OIDC",
-};
-
 /**
  * Builds the request headers.
  *
@@ -230,7 +218,7 @@ export function kiroHeaders(
     "x-amz-user-agent": buildKiroAmzUserAgent(version, machineId),
     authorization: `Bearer ${secret}`,
   };
-  const tokenType = authMethod === undefined ? undefined : KIRO_TOKEN_TYPE[authMethod];
+  const tokenType = kiroTokenTypeHeader(authMethod);
   if (tokenType !== undefined) {
     headers["TokenType"] = tokenType;
   }
@@ -377,9 +365,17 @@ class KiroAdapter implements ProviderAdapter {
       effortPath !== undefined
         ? undefined
         : (request.reasoning?.budget_tokens ?? kiroThinkingBudgetForEffort(requestedEffort));
+    // One resolution per dispatch: the resolver mints a fresh UUID only when
+    // the request carries no session, conversation id, or derivable opening
+    // turn, so resolving twice here would give `conversationId` and
+    // `rootConversationId` two different UUIDs — contradicting the client rule
+    // (`rootConversationId ?? conversationId`). The same id feeds the session
+    // cache estimator at stream end, so its key matches what the request
+    // presented upstream.
+    const conversationId = resolveKiroConversationId(request, context);
     const built = buildKiroWireRequest(request, {
-      conversationId: resolveKiroConversationId(request, context),
-      rootConversationId: resolveKiroConversationId(request, context),
+      conversationId,
+      rootConversationId: conversationId,
       modelId,
       profileArn: resolveProfileArn(context),
       ...(effortPath === undefined || effort === undefined ? {} : { effortPath, effort }),
@@ -414,7 +410,7 @@ class KiroAdapter implements ProviderAdapter {
       }, "upstream");
     }
 
-    yield* this.#stream(response.body, built.value, request, context);
+    yield* this.#stream(response.body, built.value, request, conversationId);
   }
 
   /**
@@ -471,7 +467,7 @@ class KiroAdapter implements ProviderAdapter {
     stream: ReadableStream<Uint8Array>,
     built: KiroWireRequest,
     request: CanonicalRequest,
-    context: ProviderDispatchContext,
+    conversationId: string,
   ): AsyncIterable<CanonicalEvent> {
     const decoder = new KiroStreamDecoder();
     const reader = stream.getReader();
@@ -605,7 +601,7 @@ class KiroAdapter implements ProviderAdapter {
       reader.releaseLock();
     }
 
-    const finalUsage = kiroUsage(usage, request.model, outputText, request.messages, resolveKiroConversationId(request, context));
+    const finalUsage = kiroUsage(usage, request.model, outputText, request.messages, conversationId);
     yield {
       type: "usage",
       sequence_number: sequence++,

package/src/providers/integrations/ollamacloud/index.ts

@@ -0,0 +1,2 @@
+export * from "./models";
+export * from "./quota";

package/src/providers/integrations/{ollamacloud-models.ts → ollamacloud/models.ts}

@@ -16,8 +16,8 @@
  * All six serve the chat wire (none is a Responses-native id), and all report
  * `supported_in_api: true` on the live roster.
  */
-import { defineModel } from "../provider-model-definition";
-import type { ModelDefinition } from "../provider-model-definition";
+import { defineModel } from "../../provider-model-definition";
+import type { ModelDefinition } from "../../provider-model-definition";
 
 export const OLLAMACLOUD_PROVIDER_ID = "ollamacloud" as const;
 

package/src/providers/integrations/{ollamacloud-quota.ts → ollamacloud/quota.ts}

@@ -1,6 +1,6 @@
-import type { FetchLike, ProviderQuotaResult } from "../quota/quota-contracts";
-import { getJson, record, text } from "../quota/quota-contracts";
-import { parseQuotaWindows } from "../quota/quota-window-parser";
+import type { FetchLike, ProviderQuotaResult } from "../../quota/quota-contracts";
+import { getJson, record, text } from "../../quota/quota-contracts";
+import { parseQuotaWindows } from "../../quota/quota-window-parser";
 
 async function fetchPlan(fetcher: FetchLike, headers: Record<string, string>): Promise<string> {
   try {

package/src/providers/integrations/opencode/opencode-go-quota.ts

@@ -1,5 +1,6 @@
 import {
   getJson,
+  isoDate,
   type FetchLike,
   type ProviderQuotaResult,
   type ProviderQuotaWindow,
@@ -42,13 +43,6 @@ function labelFor(kind: string): string {
   return kind.charAt(0).toUpperCase() + kind.slice(1);
 }
 
-function resetIso(value: string | null | undefined): string | null {
-  if (typeof value !== "string" || value.trim() === "") return null;
-  const parsed = Date.parse(value);
-  if (!Number.isFinite(parsed)) return null;
-  return new Date(parsed).toISOString();
-}
-
 /**
  * One window, or `undefined` when the upstream omitted what makes it usable.
  *
@@ -75,7 +69,7 @@ function windowFor(
     accounting: "independent",
     usedPercent: percent,
     remainingPercent: 100 - percent,
-    resetsAt: resetIso(raw.resetsAt),
+    resetsAt: isoDate(raw.resetsAt),
   };
 }
 

package/src/providers/integrations/perch/perch-credential.ts

@@ -0,0 +1,25 @@
+// Perch credential-envelope parsing.
+//
+// Perch accounts authenticate via Supabase OAuth (PKCE), and the stored secret
+// is the OAuth envelope JSON with `accessToken` (or `access_token`). Both the
+// dispatch adapter and the quota collector need the access token out of that
+// envelope; the parse is shared here and each surface keeps its own fallback
+// for a secret that is not an envelope.
+
+/**
+ * Reads the access token out of a stored Perch OAuth envelope.
+ *
+ * Returns the token when the secret parses as JSON and carries `accessToken`
+ * (or `access_token`) as a string; `null` when it is not such an envelope
+ * (not JSON, or JSON without a token field). The caller decides what a
+ * `null` means for its surface.
+ */
+export function parsePerchCredentialToken(secret: string): string | null {
+  try {
+    const parsed = JSON.parse(secret) as Record<string, unknown>;
+    const found = parsed["accessToken"] ?? parsed["access_token"];
+    return typeof found === "string" ? found : null;
+  } catch {
+    return null;
+  }
+}

package/src/providers/integrations/perch/perch-protocol.ts

@@ -27,9 +27,6 @@ import { PERCH_STARTER_PINS } from "./perch-realm";
 /** Default hosted model id when the account endpoint is unreachable. */
 export const PERCH_DEFAULT_CHAT_MODEL = "wandb-kimi-k2-6";
 
-/** App origin (model-call + ticket + account + plan endpoints). */
-export const PERCH_APP_URL = "https://app.perchai.app";
-
 /** The CLI user-agent the upstream recognizes as a CLI surface. */
 export const PERCH_CLI_USER_AGENT = "perchai-cli/unknown";
 

package/src/providers/integrations/perch/perch-quota.ts

@@ -11,21 +11,7 @@ import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../
 import { cleanError, percentWindow, text } from "../../quota/quota-contracts";
 import type { QuotaCollectionContext } from "../../quota/quota-support";
 import { PERCH_APP_URL } from "./perch-realm";
-
-interface PerchSessionCredential {
-  readonly accessToken?: string;
-  readonly access_token?: string;
-}
-
-function credentialToken(credential: string): string {
-  try {
-    const parsed = JSON.parse(credential) as PerchSessionCredential;
-    const found = parsed.accessToken ?? parsed.access_token;
-    return typeof found === "string" ? found : "";
-  } catch {
-    return credential.trim();
-  }
-}
+import { parsePerchCredentialToken } from "./perch-credential";
 
 async function readAccount(
   baseUrl: string,
@@ -61,7 +47,7 @@ export async function fetchPerchQuota(
   _context?: QuotaCollectionContext,
 ): Promise<ProviderQuotaResult> {
   try {
-    const token = credentialToken(credential);
+    const token = parsePerchCredentialToken(credential) ?? "";
     const account = await readAccount(PERCH_APP_URL, token, fetcher);
     if (!account) {
       return { source: "perch", plan: null, windows: [], error: "Perch account endpoint unavailable" };

package/src/providers/integrations/perch/perch.ts

@@ -28,7 +28,6 @@ import {
 } from "../../provider-contracts";
 import { usageFromProvider } from "../../provider-usage";
 import {
-  PERCH_APP_URL,
   PERCH_CLI_USER_AGENT,
   PERCH_SAFFRON_SYSTEM_PROMPT,
   buildPerchModelCallBody,
@@ -39,7 +38,8 @@ import {
   PERCH_MODEL_PINS,
   PERCH_MODEL_ROOST_TIERS,
 } from "./perch-catalog";
-import { PERCH_PROVIDER_ID } from "./perch-realm";
+import { PERCH_APP_URL, PERCH_PROVIDER_ID } from "./perch-realm";
+import { parsePerchCredentialToken } from "./perch-credential";
 
 interface PerchAdapterOptions {
   readonly providerId?: string;
@@ -126,7 +126,7 @@ export class PerchAdapter implements ProviderAdapter {
     }
     const secret = readCredentialSecret(context.credential, "Perch credential is required");
     const modelId = candidate.model_id || request.model || "standard";
-    const access = secret.startsWith("{") ? parseAccessToken(secret) : secret.trim();
+    const access = parsePerchCredentialToken(secret) ?? secret.trim();
     // Probes pass a validated outbound fetch (with capture wrapped around it);
     // live dispatch passes one too. `globalThis.fetch` here silently split the
     // probe from the route's egress policy and left Request Detail empty.
@@ -281,16 +281,6 @@ function normalizePerchUsage(usage: Record<string, unknown>): Record<string, unk
   return out;
 }
 
-function parseAccessToken(secret: string): string {
-  try {
-    const parsed = JSON.parse(secret) as Record<string, unknown>;
-    const found = parsed["accessToken"] ?? parsed["access_token"];
-    return typeof found === "string" ? found : secret.trim();
-  } catch {
-    return secret.trim();
-  }
-}
-
 /**
  * Builds an upstream verdict for the Perch surface. `origin: "upstream"` is
  * what lets the account health machine see the failure: `attempt-finalize`