cartethyia 2.7.8 → 2.7.9

package/src/providers/integrations/gemini.ts

@@ -241,7 +241,7 @@ class GeminiAdapter implements ProviderAdapter {
         let seq = 1;
         yield { type: "response_start", sequence_number: seq++, model: request.model } as CanonicalEvent;
         if (output.thought) {
-          yield { type: "content_delta", sequence_number: seq++, content: { kind: "reasoning", payload: null, summary: output.thought } } as CanonicalEvent;
+          yield { type: "content_delta", sequence_number: seq++, content: { kind: "reasoning", payload: null, summary: output.thought, ...(output.thoughtSignature ? { signature: output.thoughtSignature } : {}) } } as CanonicalEvent;
         }
         if (output.text) {
           yield { type: "content_delta", sequence_number: seq++, content: { kind: "text", text: output.text } } as CanonicalEvent;
@@ -277,7 +277,7 @@ class GeminiAdapter implements ProviderAdapter {
         const { candidate: cand, parts } = geminiCandidate(parsed);
         const output = responseParts(parts);
         if (output.thought) {
-          yield { type: "content_delta", sequence_number: seq++, content: { kind: "reasoning", payload: null, summary: output.thought } } as CanonicalEvent;
+          yield { type: "content_delta", sequence_number: seq++, content: { kind: "reasoning", payload: null, summary: output.thought, ...(output.thoughtSignature ? { signature: output.thoughtSignature } : {}) } } as CanonicalEvent;
         }
         if (output.text) {
           yield { type: "content_delta", sequence_number: seq++, content: { kind: "text", text: output.text } } as CanonicalEvent;

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

@@ -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/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/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-oauth.ts

@@ -0,0 +1,170 @@
+// Perch OAuth client — Supabase PKCE browser flow + refresh.
+//
+// Perch authentication is Supabase GoTrue (project
+// zlfuvsfjtgsdtqcaykia.supabase.co) with Google/GitHub providers. The web
+// client ships only the publishable key (`sb_publishable_...`), which is
+// accepted as `apikey` for authorize/token. The authorization code exchange
+// is GoTrue-specific: `grant_type=pkce` with `auth_code` as the field name
+// (NOT `authorization_code`/`code` — both are rejected with
+// `unsupported_grant_type` / `validation_failed`), plus `code_verifier`.
+//
+// The browser flow is a loopback redirect (`http://127.0.0.1:<port>/callback`)
+// exactly like the desktop app's own sign-in controller.
+//
+// After exchange, the official CLI stamps `user_metadata.signup_source=cli`
+// (used by the server for surface entitlement); we repeat that so the account
+// is recognized as a CLI surface.
+
+import { OAuthClient } from "../../authentication/oauth-client";
+import type { OAuthAuthorizeRequest, OAuthExchangeResult } from "../../authentication/oauth-flow-store";
+import { postJsonTokenRequest } from "../../authentication/oauth-flow-store";
+import type { OAuthTokenRefreshResult } from "../../authentication/oauth-refresh-service";
+import {
+  PERCH_APP_URL,
+  PERCH_SUPABASE_HOST,
+  PERCH_SUPABASE_PUBLISHABLE_KEY,
+} from "./perch-realm";
+
+const PERCH_SUPABASE_URL = `https://${PERCH_SUPABASE_HOST}`;
+const PERCH_AUTHORIZE_PATH = "/auth/v1/authorize";
+const PERCH_TOKEN_PATH = "/auth/v1/token";
+const PERCH_GRANT_PKCE = "pkce";
+const PERCH_GRANT_REFRESH = "refresh_token";
+const PERCH_APISEY_COOKIE = "apikey";
+
+export class PerchOAuthClient extends OAuthClient {
+  readonly supportsDeviceCode = false;
+  override readonly supportsBrowserCode = true;
+  protected readonly providerLabel = "Perch";
+  protected readonly clientId = PERCH_SUPABASE_PUBLISHABLE_KEY;
+  protected readonly tokenUrl = `${PERCH_SUPABASE_URL}${PERCH_TOKEN_PATH}`;
+  protected override readonly authorizeUrl = `${PERCH_SUPABASE_URL}${PERCH_AUTHORIZE_PATH}`;
+  // Google validates scopes for accounts that never approved this client; a
+  // missing scope answers `Error 400: invalid_request / Missing required
+  // parameter: scope` (flowName=GeneralOAuthFlow). These are the GoTrue
+  // default Google scopes, sent explicitly.
+  protected readonly scopes = "openid email profile";
+
+  /** Loopback callback path (the desktop app uses the same shape). */
+  override readonly browserRedirectUri = "http://127.0.0.1:1455/callback";
+
+  /**
+   * GoTrue token responses carry the signed-in user (`user.email`). Without
+   * this the exchange falls back to the provider id as the account label and
+   * every login of every Perch account collides on the same identity
+   * fingerprint — the second login replaces the first instead of adding a new
+   * row.
+   */
+  protected override extractAccountLabel(data: unknown): string | undefined {
+    const body = data as { user?: { email?: unknown } } | null | undefined;
+    const email = typeof body?.user?.email === "string" ? body.user.email.trim() : "";
+    return email.length > 0 ? email : undefined;
+  }
+
+  protected override extraAuthorizeParams(): Record<string, string> | undefined {
+    return {
+      provider: "google",
+    };
+  }
+
+  /**
+   * Supabase's authorize endpoint speaks `redirect_to`, not the RFC-style
+   * `redirect_uri` the shared PKCE helper emits — a call redirected to a
+   * `redirect_uri` value lands on a Supabase error page.
+   *
+   * GoTrue does NOT echo the `state` parameter on the callback — the redirect
+   * back to `redirect_to` carries only `?code=...` (verified live). The
+   * console's callback listener correlates by `state` and fails closed when
+   * state is absent, so the state is embedded in `redirect_to` itself:
+   * `http://127.0.0.1:1455/callback?state=<state>`. Supabase preserves the
+   * query it was given and appends `code`, so the callback carries both.
+   */
+  override buildAuthorizeUrl(request: OAuthAuthorizeRequest): string {
+    const redirectTo = new URL(request.redirectUri);
+    redirectTo.searchParams.set("state", request.state);
+    const params = new URLSearchParams({
+      provider: "google",
+      client_id: this.clientId,
+      response_type: "code",
+      redirect_to: redirectTo.toString(),
+      scope: this.scopes,
+      state: request.state,
+      code_challenge: request.codeChallenge,
+      code_challenge_method: "S256",
+    });
+    return `${this.authorizeUrl}?${params.toString()}`;
+  }
+
+  /**
+   * GoTrue exchange: `grant_type=pkce` (query) with `auth_code` (body) —
+   * not the RFC-style `authorization_code`/`code` pair the generic base
+   * class posts. GoTrue v2.197.0 accepts **only JSON** bodies here (a form
+   * body answers `bad_json`), so this overrides the form-encoded generic
+   * helper. The apikey goes in the header (not as `client_id`).
+   *
+   * The console's `exchangeCode` passes the flow state; it must be replayed
+   * in `redirect_to` exactly as `buildAuthorizeUrl` embedded it, because
+   * GoTrue compares the exchange redirect against the authorize one.
+   */
+  override async exchangeCode(
+    code: string,
+    codeVerifier: string,
+    redirectUri: string,
+    state?: string,
+  ): Promise<OAuthExchangeResult> {
+    const redirectTo = new URL(redirectUri);
+    if (state) redirectTo.searchParams.set("state", state);
+    const response = await postJsonTokenRequest({
+      url: `${this.tokenUrl}?grant_type=${PERCH_GRANT_PKCE}`,
+      fetchFn: this.fetchFn,
+      body: {
+        auth_code: code,
+        redirect_to: redirectTo.toString(),
+        code_verifier: codeVerifier,
+      },
+      headers: {
+        accept: "application/json",
+        [PERCH_APISEY_COOKIE]: PERCH_SUPABASE_PUBLISHABLE_KEY,
+      },
+      label: "Perch token exchange",
+    });
+    const result = this.toExchangeResult(this.parseTokenResponse(response));
+    await this.#stampCliSignup(result.access).catch(() => undefined);
+    return result;
+  }
+
+  override async refresh(refreshToken: string, signal?: AbortSignal): Promise<OAuthTokenRefreshResult> {
+    const response = await postJsonTokenRequest({
+      url: `${this.tokenUrl}?grant_type=${PERCH_GRANT_REFRESH}`,
+      fetchFn: this.fetchFn,
+      body: {
+        refresh_token: refreshToken,
+      },
+      headers: {
+        accept: "application/json",
+        [PERCH_APISEY_COOKIE]: PERCH_SUPABASE_PUBLISHABLE_KEY,
+      },
+      ...(signal === undefined ? {} : { signal }),
+      label: "Perch token refresh",
+    });
+    return this.toRefreshResult(this.parseTokenResponse(response));
+  }
+
+  /** The CLI stamps `signup_source=cli` after login; mirror it. */
+  async #stampCliSignup(access: string): Promise<void> {
+    await this.fetchFn(`${PERCH_SUPABASE_URL}/auth/v1/user`, {
+      method: "PUT",
+      headers: {
+        apikey: PERCH_SUPABASE_PUBLISHABLE_KEY,
+        Authorization: `Bearer ${access}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ data: { signup_source: "cli" } }),
+    });
+  }
+
+  /** The app origin the CLI writes into its session file. */
+  readonly appUrl = PERCH_APP_URL;
+}
+
+export const perchOAuthClient = new PerchOAuthClient();

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

@@ -0,0 +1,211 @@
+// Perch wire protocol (pure HTTP, reverse-engineered from the official CLI).
+//
+// The hosted inference surface is `POST /api/perch-terminal/model-call`. The
+// server surface-gates the call: it only accepts requests that carry the full
+// CLI turn envelope — a fresh turn ticket minted with `{surface:"cli"}`,
+// the Roost tier choice (`roostModelChoice`), the account attribution, and
+// the Saffron system-prompt prefix (the server fingerprints it). Without that
+// prompt the upstream answers `403 perch_surface_required` even with a valid
+// token and ticket (verified live 2026-11-08).
+//
+// The stream is plain SSE with JSON frames:
+//   data: {"type":"keepalive"}
+//   data: {"type":"answer_delta","text":"..."}
+//   data: {"type":"done","ok":true,"text":"...","model":"...","usage":{...}}
+//   data: {"type":"model_call_failed",...}
+//   data: {"type":"error","message":"..."}
+
+import type { CanonicalRequest } from "../../../protocol/canonical-model";
+// The prompt lives in a plain TS module: Bun's standalone binary has no
+// `saffron-system-prompt.txt` asset on disk, so a readFileSync()-backed
+// constant silently became a two-line stub in the compiled binary and the
+// upstream answered `403 perch_surface_required`.
+export { PERCH_SAFFRON_SYSTEM_PROMPT } from "./perch-system-prompt";
+import { PERCH_SAFFRON_SYSTEM_PROMPT } from "./perch-system-prompt";
+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";
+
+export interface PerchTurnContext {
+  readonly userId: string | null;
+  readonly workspaceId: string | null;
+  readonly orgId: string | null;
+  readonly planCode: string | null;
+  readonly runId: string;
+  /**
+   * Starter-pool pin (see `PERCH_STARTER_PINS`): when present the request
+   * carries the backing model id as `manualModelOptionId` +
+   * `preferredModelId` with `strictManual: true`, so the server actually
+   * serves the pinned model instead of the Roost default.
+   */
+  readonly pin?: string | undefined;
+  /** Roost tier for `roostModelChoice` (`standard` | `standard_max`). */
+  readonly roostTier?: string | undefined;
+}
+
+/**
+ * Builds the model-call body for one turn. The Saffron system-prompt prefix
+ * opens `request.messages` (required) and the caller's conversation follows.
+ * The tier is selected through `roostModelChoice` (`standard` | `standard 1m`).
+ */
+export function buildPerchModelCallBody(
+  request: CanonicalRequest,
+  tier: string,
+  ctx: PerchTurnContext,
+  preferredModelId = PERCH_DEFAULT_CHAT_MODEL,
+): Record<string, unknown> {
+  const messages: Record<string, unknown>[] = [];
+  const systemParts = [
+    ...(request.system ?? []),
+    ...(request.instructions ?? []),
+  ];
+  const systemText = systemParts
+    .map((part) => (part.kind === "text" ? part.text : ""))
+    .filter((t) => t.trim().length > 0)
+    .join("\n\n");
+  // The upstream fingerprints the *prefix* of the Saffron prompt, not the
+  // whole string (both the 28k original and this 432-char prefix answer 200,
+  // while a plain assistant placeholder answers 403). Keep Saffron as the
+  // opener unconditionally: a caller-supplied system turn is appended, never
+  // substituted, so live traffic cannot strip the surface identity. The probe
+  // path injects exactly this prefix via `systemPrompt()`, hence `startsWith`
+  // is a no-op there and the wire body stays byte-identical to the verified one.
+  const systemContent = systemText.startsWith(PERCH_SAFFRON_SYSTEM_PROMPT)
+    ? systemText
+    : systemText
+      ? `${PERCH_SAFFRON_SYSTEM_PROMPT}\n\n${systemText}`
+      : PERCH_SAFFRON_SYSTEM_PROMPT;
+  messages.push({ role: "system", content: systemContent });
+  for (const message of request.messages) {
+    const text = message.content
+      .map((part) => (part.kind === "text" ? part.text : ""))
+      .filter((t) => t.trim().length > 0)
+      .join("\n");
+    if (!text) continue;
+    messages.push({ role: message.role, content: text });
+  }
+  const maxTokens =
+    request.generation_controls.max_tokens ??
+    request.generation_controls.max_output_tokens ??
+    request.generation_controls.max_completion_tokens ??
+    32000;
+  const temperature = request.generation_controls.temperature ?? 0.6;
+  const runId = ctx.runId;
+  const pin = ctx.pin && ctx.pin !== "standard-max" ? ctx.pin : undefined;
+  const pinModel = pin ? PERCH_STARTER_PINS[pin]?.preferredModelId : undefined;
+  return {
+    request: {
+      messages,
+      temperature,
+      maxTokens: Number(maxTokens) || 32000,
+    },
+    runId,
+    lane: "chat",
+    strictManual: pinModel !== undefined,
+    preferredModelId: pinModel ?? preferredModelId,
+    avoidModelIds: [],
+    attribution: {
+      userId: ctx.userId,
+      workspaceId: ctx.workspaceId,
+      runId,
+      lane: "chat",
+      source: "cli",
+      billingMultiplier: null,
+    },
+    clientSurface: "cli",
+    resendAfterOutput: true,
+    roostModelChoice: ctx.roostTier ?? tier,
+    roostReasoning: true,
+    effort: { level: "high", orchestration: false },
+    ...(pinModel ? { manualModelOptionId: pinModel } : {}),
+  };
+}
+
+export interface PerchModelCallDone {
+  readonly ok: boolean;
+  readonly text: string;
+  readonly model: string;
+  readonly provider: string;
+  readonly usage?: Record<string, unknown>;
+  readonly error?: string;
+  readonly errorCode?: string;
+}
+
+export interface PerchSseEvent {
+  readonly type: string;
+  readonly data: Record<string, unknown>;
+}
+
+/** Parses an SSE body into JSON frames. */
+export function parsePerchSse(text: string): PerchSseEvent[] {
+  const events: PerchSseEvent[] = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.replace(/\r$/, "");
+    if (!line.startsWith("data:")) continue;
+    const payload = line.slice(5).trim();
+    if (!payload) continue;
+    try {
+      const data = JSON.parse(payload) as Record<string, unknown>;
+      if (typeof data["type"] === "string") {
+        events.push({ type: data["type"] as string, data });
+      }
+    } catch {
+      // Ignore non-JSON frames.
+    }
+  }
+  return events;
+}
+
+/** Extracts the final result from a completed stream. */
+export function summarizePerchStream(events: readonly PerchSseEvent[]): PerchModelCallDone {
+  let text = "";
+  let ok = false;
+  let model = "";
+  let provider = "";
+  let usage: Record<string, unknown> | undefined;
+  let error: string | undefined;
+  let errorCode: string | undefined;
+
+  for (const event of events) {
+    const d = event.data;
+    if (event.type === "answer_delta" && typeof d["text"] === "string") {
+      text += d["text"];
+    } else if (event.type === "reasoning_delta" && typeof d["text"] === "string") {
+      // Reasoning text is not part of the visible answer.
+      void d;
+    } else if (event.type === "done") {
+      ok = d["ok"] === true;
+      if (ok) {
+        if (typeof d["text"] === "string") text = d["text"];
+        if (typeof d["model"] === "string") model = d["model"];
+        if (typeof d["provider"] === "string") provider = d["provider"];
+        const usageRaw = d["usage"];
+        if (usageRaw && typeof usageRaw === "object") {
+          usage = usageRaw as Record<string, unknown>;
+        }
+      } else {
+        if (typeof d["error"] === "string") error = d["error"];
+        if (typeof d["errorCode"] === "string") errorCode = d["errorCode"];
+      }
+    } else if (event.type === "model_call_failed" || event.type === "error") {
+      if (error === undefined && typeof d["error"] === "string") error = d["error"];
+      if (errorCode === undefined && typeof d["errorCode"] === "string") errorCode = d["errorCode"];
+      if (errorCode === undefined && typeof d["code"] === "string") errorCode = d["code"] as string;
+    }
+  }
+  return { ok: ok || text.length > 0, text, model, provider, ...(usage ? { usage } : {}), ...(error ? { error } : {}), ...(errorCode ? { errorCode } : {}) };
+}
+
+/** Renders a canonical message list into a debug label (for capture). */
+export function summarizeMessages(request: CanonicalRequest): string {
+  return request.messages
+    .map((m) => `${m.role}:${m.content.map((p) => (p.kind === "text" ? p.text.length : 0)).reduce((a, b) => a + b, 0)}`)
+    .join("|");
+}