cartethyia 2.7.8 → 2.8.0

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

@@ -0,0 +1,94 @@
+// Hermes / Nous Portal OAuth client — RFC 8628 device flow + refresh.
+//
+// The Hermes Agent (Nous Research) offers a portal subscription via OAuth:
+// `hermes setup --portal` runs a device-code flow against Nous Portal, and
+// the resulting access token is an inference-scoped JWT spent on the
+// OpenAI-compatible inference API. API keys still work for the free roster;
+// this OAuth path is the subscription route (300+ models + paid tiers).
+//
+// Wire sourced from the official Hermes Agent source:
+//   - start:  POST {portal}/api/oauth/device/code  (form: client_id, scope)
+//   - poll:   POST {portal}/api/oauth/token        (form: grant_type=device_code,
+//              client_id, device_code) → {access_token, refresh_token, …}
+//   - refresh: POST {portal}/api/oauth/token        (form: grant_type=refresh_token,
+//              client_id, refresh_token)
+
+import { OAuthDeviceFlow } from "../../authentication/oauth-device-flow";
+import type {
+  OAuthDeviceFlowContext,
+  OAuthDevicePollResult,
+  OAuthDeviceStartResult,
+} from "../../authentication/oauth-flow-store";
+import type { OAuthTokenRefreshResult } from "../../authentication/oauth-refresh-service";
+import { postFormTokenRequest } from "../../authentication/oauth-flow-store";
+
+const NOUS_PORTAL_URL = "https://portal.nousresearch.com";
+const NOUS_CLIENT_ID = "hermes-cli";
+const NOUS_SCOPE = "inference:invoke";
+const NOUS_DEVICE_CODE_PATH = "/api/oauth/device/code";
+const NOUS_TOKEN_PATH = "/api/oauth/token";
+
+const FORM_HEADERS = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+
+export class HermesOAuthClient extends OAuthDeviceFlow {
+  readonly supportsDeviceCode = true;
+  readonly supportsBrowserCode = false;
+  protected readonly providerLabel = "Hermes / Nous Portal";
+  protected readonly clientId = NOUS_CLIENT_ID;
+  protected readonly tokenUrl = `${NOUS_PORTAL_URL}${NOUS_TOKEN_PATH}`;
+  protected readonly scopes = NOUS_SCOPE;
+
+  override async startDeviceAuth(context?: OAuthDeviceFlowContext): Promise<OAuthDeviceStartResult> {
+    const started = await this.startGenericDeviceAuth({
+      tokenUrl: this.tokenUrl,
+      deviceAuthUrl: `${NOUS_PORTAL_URL}${NOUS_DEVICE_CODE_PATH}`,
+      clientId: NOUS_CLIENT_ID,
+      scope: NOUS_SCOPE,
+      formHeaders: FORM_HEADERS,
+      startParams: context?.parameters ?? {},
+    });
+    return { ...started, providerState: JSON.stringify({ device_code: started.deviceAuthId }) };
+  }
+
+  override async pollDeviceAuth(
+    deviceAuthId: string,
+    _context?: OAuthDeviceFlowContext,
+  ): Promise<OAuthDevicePollResult> {
+    // The generic poll posts the device code and parses RFC 8628 error codes
+    // (`authorization_pending`/`slow_down` → pending). Its `complete` result
+    // is already a normalized OAuthExchangeResult.
+    return this.pollGenericDeviceAuth(deviceAuthId, {
+      tokenUrl: this.tokenUrl,
+      deviceAuthUrl: `${NOUS_PORTAL_URL}${NOUS_DEVICE_CODE_PATH}`,
+      clientId: NOUS_CLIENT_ID,
+      scope: NOUS_SCOPE,
+      formHeaders: FORM_HEADERS,
+    });
+  }
+
+  override async refresh(refreshToken: string, signal?: AbortSignal): Promise<OAuthTokenRefreshResult> {
+    const payload = await postFormTokenRequest({
+      url: this.tokenUrl,
+      fetchFn: this.fetchFn,
+      params: {
+        grant_type: "refresh_token",
+        client_id: NOUS_CLIENT_ID,
+        refresh_token: refreshToken,
+      },
+      headers: FORM_HEADERS,
+      signal,
+      label: "Hermes / Nous Portal token refresh",
+    });
+    const record = payload as Record<string, unknown>;
+    const access = typeof record["access_token"] === "string" ? record["access_token"] : "";
+    if (!access) throw new Error("Hermes / Nous Portal refresh returned no access_token");
+    const expiresIn = typeof record["expires_in"] === "number" ? record["expires_in"] : 3600;
+    return {
+      access,
+      ...(typeof record["refresh_token"] === "string" ? { refresh: record["refresh_token"] as string } : {}),
+      expiresAt: new Date(Date.now() + expiresIn * 1000),
+    };
+  }
+}
+
+export const hermesOAuthClient = new HermesOAuthClient();

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.
@@ -78,28 +78,20 @@ export const HERMES_MODELS: readonly ModelDefinition[] = [
   //
   // `meituan/longcat-2.0:free` is excluded: the catalog still lists the id, but
   // dispatching it answers 404 "This model is no longer free", so listing it
-  // would be a card that can only ever fail. `meituan/longcat-2.5-preview:free`
+  // would be a card that can only ever fail. `meituan/longcat-2.5:free`
   // is listed instead and answers 200.
   //
   // `stepfun/step-5-preview:free` is excluded: it is absent from the live catalog
   // entirely and dispatching it answers 404 "This model's free period has
   // ended" — a retired row, not a capacity blip, so it cannot be left in.
   //
-  // Output caps are the catalog's own `top_provider.max_completion_tokens`,
-  // which differ per row: `poolside/laguna-xs-2.1:free` is 32768 while its
-  // sibling `laguna-s` is 131072, so a uniform value overstates one of them.
-  defineModel({ id: "poolside/laguna-s-2.1:free", ctx: 262144, out: 131072, reasoning: true, free: true, freeTier: true }),
-  defineModel({ id: "poolside/laguna-xs-2.1:free", ctx: 262144, out: 32768, reasoning: true, free: true, freeTier: true }),
-  defineModel({ id: "stepfun/step-3.7-flash:free", ctx: 262144, out: 256000, vision: true, reasoning: true, free: true, freeTier: true }),
+  // `poolside/laguna-s-2.1:free`, `poolside/laguna-xs-2.1:free`, and
+  // `stepfun/step-3.7-flash:free` are removed too: they fail at dispatch.
   defineModel({ id: "upstage/solar-mini4:free", ctx: 524288, out: 131072, reasoning: true, free: true, freeTier: true }),
   defineModel({ id: "reflection/beam-1.0-501b-a23b:free", ctx: 262144, out: 131072, reasoning: true, free: true, freeTier: true }),
   // Vision-corrected against the live catalog: `architecture.input_modalities`
   // lists `image` for this row, so it was published without vision it has.
-  defineModel({ id: "meituan/longcat-2.5-preview:free", ctx: 1048576, out: 131072, vision: true, reasoning: true, free: true, freeTier: true }),
-  // Added after a live read: the catalog carries it, it is free, and a dispatch
-  // answers 200 — it was simply absent from this list, so a client asking for
-  // it resolved to nothing. 262144 out is the catalog's own cap.
-  defineModel({ id: "ornith/ornith-1.5-122b:free", ctx: 262144, out: 262144, vision: true, reasoning: true, free: true, freeTier: true }),
+  defineModel({ id: "meituan/longcat-2.5:free", ctx: 1048576, out: 131072, vision: true, reasoning: true, free: true, freeTier: true }),
 ];
 
 

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/fingerprint.ts

@@ -9,7 +9,7 @@ import { createHash, randomBytes } from "node:crypto";
  * can pin the exact identity sent before discovery resolves. Keep both in
  * lockstep when the CLI releases.
  */
-export const OPENCODE_CLIENT_VERSION = "2.2.5";
+export const OPENCODE_CLIENT_VERSION = "2.2.6";
 
 let lastTimestamp = 0;
 let sequenceCounter = 0;

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-catalog.ts

@@ -0,0 +1,105 @@
+// Perch model roster.
+//
+// Perch's hosted model layer ("Roost") exposes tier labels rather than raw
+// model ids: `standard` and `standard_max` are the tiers included in the free
+// Starter plan. In addition, the plan pins a small "Starter" model pool
+// (`PERCH_STARTER_PINS`) whose pins are verified live 2026-11-08:
+// `glm-5.3-flash-starter`, `deepseek-flash-starter`, and `crouton-alpha`
+// answer 200 and the server reports the pinned backing model; `beam` was not
+// verified (turn rate limit). Paid `pro` tiers are deliberately absent.
+//
+// Model ids here are the gateway-facing ids; the adapter maps them to the
+// upstream wire (Roost tier + backing pin) via `PERCH_STARTER_PINS` /
+// `roostModelChoice` — the upstream itself hides real model names.
+
+import { defineModel, type ModelDefinition } from "../../provider-model-definition";
+import {
+  PERCH_CONTEXT_STANDARD,
+  PERCH_CONTEXT_STANDARD_1M,
+  PERCH_PROVIDER_ID,
+  PERCH_STARTER_PINS,
+} from "./perch-realm";
+
+interface PerchRow {
+  readonly id: string;
+  readonly displayName: string;
+  readonly ctx: number;
+  /**
+   * Output ceiling. When absent it falls back to the CLI's `sUr` resolution
+   * (`perchOutputTokens`); starter-pool rows carry the client card's own
+   * `maxOutputTokens` (2.4.125) so a big request is not clamped below what
+   * the upstream actually serves.
+   */
+  readonly out?: number;
+  /** `undefined` = plain Roost tier; else starter-pool pin id. */
+  readonly pin?: string;
+}
+
+/** Roost tier sent for the plain tier rows (CLI canonical tier ids). */
+const TIER_ROOST_TIERS: Readonly<Record<string, string>> = {
+  standard: "standard",
+  "standard 1m": "standard_max",
+};
+
+const PERCH_ROWS: readonly PerchRow[] = [
+  { id: "standard", displayName: "Roost Standard", ctx: PERCH_CONTEXT_STANDARD },
+  { id: "standard 1m", displayName: "Roost Standard 1M", ctx: PERCH_CONTEXT_STANDARD_1M },
+  // Starter-pool pins — context/output per the client's published cards
+  // (2.4.125): glm-5.3-flash 1048576, crouton-alpha 1048576 / 943718,
+  // beam-1.0 1048576 / 131072, deepseek-v4.1-flash-1017-starter 1048576 /
+  // 131072.
+  { id: "glm-5.3-flash-starter", displayName: "GLM 5.3 Flash (Starter)", ctx: PERCH_CONTEXT_STANDARD_1M, out: 131_072, pin: "glm-5.3-flash-starter" },
+  { id: "deepseek-flash-starter", displayName: "DeepSeek V4.1 Flash 1017 (Starter)", ctx: PERCH_CONTEXT_STANDARD_1M, out: 131_072, pin: "deepseek-flash-starter" },
+  { id: "crouton-alpha", displayName: "Crouton Alpha (Stealth)", ctx: PERCH_CONTEXT_STANDARD_1M, out: 943_718, pin: "crouton-alpha" },
+  { id: "beam-1.0-starter", displayName: "Beam 1.0 (Starter)", ctx: PERCH_CONTEXT_STANDARD_1M, out: 131_072, pin: "beam-1.0-starter" },
+  // Pinned 1M tier: the CLI normalizes `standard 1m` → `standard_max`; the
+  // adapter keys `roostModelChoice` off the catalog id so the right tier is
+  // sent even though the id is a label.
+  { id: "standard 1m", displayName: "Roost Standard 1M", ctx: PERCH_CONTEXT_STANDARD_1M, pin: "standard-max" },
+];
+
+/**
+ * Output cap per model, mirroring the CLI's own resolution (`sUr` in the
+ * bundled `perch.mjs`): up to 8k context → 4096, up to 32k → 8192, above
+ * 32k → 32768. Derive per model from its context window, never hardcode.
+ */
+function perchOutputTokens(contextWindow: number): number {
+  if (contextWindow <= 8_000) return 4_096;
+  if (contextWindow <= 32_000) return 8_192;
+  return 32_768;
+}
+
+export const PERCH_MODELS: readonly ModelDefinition[] = PERCH_ROWS.map((row) =>
+  defineModel({
+    id: row.id,
+    providerId: PERCH_PROVIDER_ID,
+    wireFamily: "chat",
+    endpoint: "/api/perch-terminal/model-call",
+    ctx: row.ctx,
+    out: row.out ?? perchOutputTokens(row.ctx),
+    // The tier surfaces are chat-text; no modality claims beyond that. No
+    // `free`/`freeTier` flag is set: the upstream does not expose a
+    // per-model plan list (cli-plan only reports planRequired), and a free
+    // claim would be an unverified assertion rather than upstream truth.
+    vision: false,
+    reasoning: false,
+    toolCall: false,
+  }),
+);
+
+/** Model-id → starter pin, for the adapter's dispatch-time lookup. */
+export const PERCH_MODEL_PINS: Readonly<Record<string, string | undefined>> = Object.fromEntries(
+  PERCH_ROWS.map((row) => [row.id, row.pin]),
+);
+
+/** Model-id → Roost tier, for the adapter's dispatch-time lookup. */
+export const PERCH_MODEL_ROOST_TIERS: Readonly<Record<string, string>> = Object.fromEntries(
+  PERCH_ROWS.map((row) => [
+    row.id,
+    row.pin === undefined
+      ? TIER_ROOST_TIERS[row.id] ?? "standard"
+      : row.pin === "standard-max"
+        ? "standard_max"
+        : PERCH_STARTER_PINS[row.pin]?.roostTier ?? "standard",
+  ]),
+);

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;
+  }
+}