cartethyia 2.7.8 → 2.8.0

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,208 @@
+// 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";
+
+/** 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("|");
+}

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

@@ -0,0 +1,123 @@
+// Perch quota collector.
+//
+// Reads the account's plan/allowance surface from the hosted API
+// (`GET /api/perchai/account` with the stored access token). The account
+// endpoint reports `planCode`, `planName`, `membershipRole`, usage meters
+// (`usageMeter.monthlyUsd`, `roostRolling`), and `tierSelectionRequired`.
+// Reads are Bearer-authenticated; never throws — a failed read returns a
+// null result so the router treats it as unknown rather than dead.
+
+import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
+import { cleanError, percentWindow, text } from "../../quota/quota-contracts";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+import { PERCH_APP_URL } from "./perch-realm";
+import { parsePerchCredentialToken } from "./perch-credential";
+
+async function readAccount(
+  baseUrl: string,
+  token: string,
+  fetcher: FetchLike,
+): Promise<Record<string, unknown> | null> {
+  if (!token) return null;
+  return fetcher(`${baseUrl}/api/perchai/account`, {
+    method: "GET",
+    headers: {
+      accept: "application/json",
+      authorization: `Bearer ${token}`,
+    },
+    signal: AbortSignal.timeout(15_000),
+  })
+    .then(async (res) => {
+      if (!res.ok) return null;
+      try {
+        return (await res.json()) as Record<string, unknown>;
+      } catch {
+        return null;
+      }
+    })
+    .catch(() => null);
+}
+
+const USD_WINDOW_KIND = "usd_monthly";
+
+/** Reads the account quota and returns a normalized result. */
+export async function fetchPerchQuota(
+  credential: string,
+  fetcher: FetchLike,
+  _context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  try {
+    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" };
+    }
+    const session = account["session"] as Record<string, unknown> | undefined;
+    const plan = session && typeof session["planCode"] === "string" ? text(session["planCode"]) : null;
+    const meter = account["usageMeter"] as Record<string, unknown> | undefined;
+    const windows: ProviderQuotaWindow[] = [];
+
+    const monthlyUsd = meter?.["monthlyUsd"];
+    if (typeof monthlyUsd === "number") {
+      // Starter includes $20/month of hosted usage; reset at month end.
+      const used = monthlyUsd as number;
+      const limit = 20;
+      windows.push(
+        percentWindow(
+          USD_WINDOW_KIND,
+          "Monthly USD usage",
+          used > 0 ? (used / limit) * 100 : 0,
+          null,
+          used,
+          limit,
+          "pooled",
+        ),
+      );
+    }
+
+    const roost = meter?.["roostRolling"] as Record<string, unknown> | undefined;
+    if (roost && typeof roost["window5hCapUsd"] === "number") {
+      const cap = roost["window5hCapUsd"] as number;
+      const used = typeof roost["window5hUsd"] === "number" ? (roost["window5hUsd"] as number) : 0;
+      windows.push(
+        percentWindow(
+          "usd_5h",
+          "Roost 5-hour rolling",
+          cap > 0 ? (used / cap) * 100 : 0,
+          null,
+          used,
+          cap,
+          "independent",
+        ),
+      );
+    }
+    if (roost && typeof roost["window7dCapUsd"] === "number") {
+      const cap = roost["window7dCapUsd"] as number;
+      const used = typeof roost["window7dUsd"] === "number" ? (roost["window7dUsd"] as number) : 0;
+      windows.push(
+        percentWindow(
+          "usd_weekly",
+          "Roost weekly rolling",
+          cap > 0 ? (used / cap) * 100 : 0,
+          null,
+          used,
+          cap,
+          "independent",
+        ),
+      );
+    }
+
+    const profile = account["profile"] as Record<string, unknown> | undefined;
+    const email = profile && typeof profile["email"] === "string" ? text(profile["email"]) : undefined;
+
+    return {
+      source: "perch",
+      plan,
+      windows,
+      error: null,
+      ...(email ? { accountLabel: email } : {}),
+    };
+  } catch (error) {
+    return { source: "perch", plan: null, windows: [], error: cleanError(error) };
+  }
+}

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

@@ -0,0 +1,82 @@
+// Perch realm constants.
+//
+// Perch (perchai.app) is an AI operator platform. Accounts authenticate via
+// Supabase OAuth (Google/GitHub) with PKCE; the data plane is direct HTTP
+// (`POST /api/perch-terminal/model-call`) with a CLI turn ticket — no CLI
+// process, desktop app, MCP, or ACP transport. Free Starter accounts route
+// through the Roost `standard` / `standard_max` tiers.
+//
+// Wire facts (probed live 2026-11-08 on a Google OAuth account):
+//   - Supabase project host: zlfuvsfjtgsdtqcaykia.supabase.co
+//   - Publishable key used as `apikey` for OAuth flows (Raw JWT anon key is
+//     not shipped to the bundle; `sb_publishable_...` works for authorize +
+//     token exchange).
+//   - Authorize: GET /auth/v1/authorize?provider=google&redirect_to=...
+//     &client_id=<publishable>&code_challenge=...&code_challenge_method=S256
+//   - Token: POST /auth/v1/token?grant_type=pkce with `auth_code`
+//     (NOT `code` — GoTrue v2.197.0 rejects `authorization_code`), plus
+//     `code_verifier`.
+//   - Refresh: POST /auth/v1/token?grant_type=refresh_token.
+//   - Plan selection (Starter free): GET/POST /api/perch-terminal/cli-plan
+//     (POST body {plan:"starter", noticeVersion}).
+//   - Inference: the hosted model-call API is surface-gated
+//     (`perch_surface_required`) and requires the full CLI turn envelope:
+//     turn ticket, attribution, Roost tier, and the Saffron system-prompt
+//     prefix (see perch.ts / perch-protocol.ts).
+
+/** Default Supabase project host for Perch accounts. */
+export const PERCH_SUPABASE_HOST = "zlfuvsfjtgsdtqcaykia.supabase.co";
+
+/** Supabase publishable key (used as `apikey`; not a JWT). */
+export const PERCH_SUPABASE_PUBLISHABLE_KEY = "sb_publishable_w4R_pNkUpygBFIljZCoOlA_67ACg0FO";
+
+/** Hosted app origin (the CLI's `appUrl`). */
+export const PERCH_APP_URL = "https://app.perchai.app";
+
+/** Provider id used by the registry. */
+export const PERCH_PROVIDER_ID = "perch";
+
+/** Context windows reported for the Roost tiers (client claims, 2.4.125). */
+export const PERCH_CONTEXT_STANDARD = 200_000;
+export const PERCH_CONTEXT_STANDARD_1M = 1_000_000;
+
+/**
+ * Starter-pool model pins.
+ *
+ * Perch surfaces a fixed set of "Starter" model options on the free plan
+ * (bundle `k8e` / `zre`). A pin is selected by sending the upstream *backing*
+ * model id as `manualModelOptionId` (+ `preferredModelId`) with
+ * `strictManual: true` — verified live 2026-11-08: `glm-5.3-flash-starter`
+ * answered `model=z-ai/glm-5.3-flash`, `crouton-alpha` answered
+ * `model=stealth/crouton-alpha`, `deepseek-flash-starter` answered
+ * `model=deepseek-v4.1-flash-1017`. Sending only `preferredModelId` is
+ * ignored by the server (it falls back to the Roost default). `beam` and the
+ * slot backings were not verified (turn rate limit).
+ */
+export interface PerchStarterPin {
+  /** Roost tier to send alongside the pin. */
+  readonly roostTier: string;
+  /** The upstream backing model id (openrouter/…). */
+  readonly preferredModelId: string;
+}
+
+export const PERCH_STARTER_PINS: Readonly<Record<string, PerchStarterPin>> = {
+  "glm-5.3-flash-starter": {
+    roostTier: "standard",
+    preferredModelId: "openrouter-z-ai-glm-5-3-flash-crusoe",
+  },
+  "deepseek-flash-starter": {
+    roostTier: "standard",
+    preferredModelId: "openrouter-deepseek-deepseek-v4-1-flash-crusoe",
+  },
+  "crouton-alpha": {
+    roostTier: "standard",
+    preferredModelId: "openrouter-stealth-crouton-alpha",
+  },
+  "beam-1.0-starter": {
+    roostTier: "standard",
+    preferredModelId: "openrouter-reflection-beam-1-0-501b-a23b",
+  },
+};
+
+

package/src/providers/integrations/perch/perch-system-prompt.ts

@@ -0,0 +1,13 @@
+// Perch required system prompt — TypeScript, Perch adapter, Bun standalone binary.
+//
+// This literal is the shipped value. The standalone binary cannot read
+// `saffron-system-prompt.txt` from disk: Bun bundles JS but not runtime
+// readFileSync() assets, so the old file-backed constant silently fell back
+// to a two-line stub in dist/cartethyia.exe and the upstream answered
+// `403 perch_surface_required`. Keep this in sync with the research copy in
+// saffron-system-prompt.txt (a test asserts they match).
+//
+// Verified live 2026-11-08: the full 28k Saffron prompt answers, this
+// trimmed prefix answers, a plain assistant placeholder returns 403.
+
+export const PERCH_SAFFRON_SYSTEM_PROMPT: string = "You are Saffron — Perch's workspace operator.\n\nSharp, experienced, been around long enough to know what matters and what's noise.\nYou work with analysts, operators, and founders on financial analysis, audits,\ndocument review, and whatever the workspace needs. You have opinions. You're direct.\nYou genuinely enjoy finding something interesting buried in a mess.\n\nYou're not an assistant. You're the operator who gets the work done.\n";