cartethyia 2.7.8 → 2.7.9

package/src/providers/integrations/trae/trae-headers.ts

@@ -8,9 +8,9 @@
 //     X-Device-Type, X-Os-Version  (all encodeURIComponent'd)
 //   - User-Agent: TraeClient/TTNet
 //
-// The donor's data-plane implementation and the native Agent transport both
-// send x-ide-token alongside Authorization. Version headers remain separate:
-// they are not universally required by Agent and commercial requests.
+// The native Agent transport also sends x-ide-token alongside Authorization.
+// Version headers remain separate: they are not universally required by Agent
+// and commercial requests.
 
 import { createHash } from "node:crypto";
 import {
@@ -32,9 +32,9 @@ export interface TraeDeviceIdentity {
  * Derives the device pair the upstream client sends.
  *
  * Both are pure one-way derivations from the account id, so one account always
- * presents one device and two accounts never share one — the donor notes this
- * is the risk-control correlation surface, so a per-process random id would
- * look like many devices behind one account and a shared id would link them.
+ * presents one device and two accounts never share one — this is the
+ * risk-control correlation surface, so a per-process random id would look like
+ * many devices behind one account and a shared id would link them.
  */
 export function traeDeviceIdentity(uid: string): TraeDeviceIdentity {
   const seed = String(uid ?? "").trim() || "anonymous";
@@ -52,9 +52,9 @@ export function traeDeviceIdentity(uid: string): TraeDeviceIdentity {
 /**
  * OS string reported as `X-Os-Version`.
  *
- * The donor reads this from the host registry, which leaks the operator's real
- * Windows build to upstream. This gateway is not the operator's desktop, so a
- * fixed value of the same shape is both more private and more stable.
+ * Upstream reads this from the host registry, which would leak the operator's
+ * real Windows build. This gateway is not the operator's desktop, so a fixed
+ * value of the same shape is both more private and more stable.
  */
 export const TRAE_OS_VERSION = "Windows 11 Pro";
 
@@ -70,6 +70,13 @@ export interface TraeHeaderInput {
   readonly uid: string;
   /** Version code sent as `x-ide-version-code`. */
   readonly versionCode?: string;
+  /** Client semver (e.g. `3.6.13`), sent as `X-App-Version`/`x-ide-version`. */
+  readonly appVersion?: string;
+  /**
+   * Traffic class, sent as `request-traffic-type`. Defaults to `chat`;
+   * the agent surface overrides to `agent`.
+   */
+  readonly trafficType?: string;
   /** True for the streaming chat call, which overrides `Accept`. */
   readonly stream?: boolean;
   /** Extra/replacement headers, applied case-insensitively. */
@@ -79,7 +86,15 @@ export interface TraeHeaderInput {
 /**
  * Builds the header set for one Trae request.
  *
- * `null` in `extra` deletes the header, matching the donor's override rule.
+ * `null` in `extra` deletes the header.
+ *
+ * Deliberately does NOT send:
+ * - `x-ide-token` — the canonical client (Trae 1.107.1 bundle, commit
+ *   `b6786417`) does not send it on the chat/agent data plane; it is an
+ *   OAuth/business-host header only. Sending it changed nothing for auth but
+ *   diverges from the reference wire.
+ * - `store-country-code` — not sent on the data plane either. The pay/quota
+ *   collector adds it explicitly where the commercial surface requires it.
  */
 export function buildTraeHeaders(input: TraeHeaderInput): Record<string, string> {
   const config = TRAE_REALMS[input.realm];
@@ -88,7 +103,6 @@ export function buildTraeHeaders(input: TraeHeaderInput): Record<string, string>
     "X-App-Id": TRAE_APP_ID,
     "x-plugin-channel": TRAE_PLUGIN_CHANNEL,
     "x-ide-version-code": input.versionCode ?? config.versionCode,
-    "x-ide-token": input.token,
     Authorization: `Cloud-IDE-JWT ${input.token}`,
     "Content-Type": "application/json",
     Accept: "application/json",
@@ -99,6 +113,17 @@ export function buildTraeHeaders(input: TraeHeaderInput): Record<string, string>
     "X-Device-Brand": encodeURIComponent(TRAE_DEVICE_BRAND),
     "X-Device-Type": encodeURIComponent("windows"),
     "X-Os-Version": encodeURIComponent(TRAE_OS_VERSION),
+    // Semver + traffic-class headers the 3.6.13 harness sends; verified live
+    // (2026-11-06) that they are accepted and change nothing (A/B sweep
+    // identical). Only sent when the caller supplies a version.
+    ...(input.appVersion === undefined
+      ? {}
+      : {
+          "X-App-Version": input.appVersion,
+          "X-App-Version-Code": input.appVersion,
+          "x-ide-version": input.appVersion,
+        }),
+    "request-traffic-type": input.trafficType ?? "chat",
   };
 
   if (input.stream === true) {

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

@@ -1,7 +1,7 @@
 // Trae credential login and refresh.
 //
-// Trae has a real browser authorization flow, just not a device-code one: the
-// other donor's `start_login` answers `unsupported` for device authorization,
+// Trae has a real browser authorization flow, just not a device-code one: an
+// earlier probe of the device-authorization surface answered `unsupported`,
 // which is what led to the earlier claim that Trae had no OAuth login at all.
 // The browser path is `GetLoginGuidance` (discovers the login host) → the
 // operator signs in at `/authorization` → the callback carries a refresh token
@@ -18,9 +18,6 @@
 // NEW refresh token and invalidates the one sent. A refresh that persisted only
 // the access token would leave the account holding a dead refresh token and
 // unrecoverable on its next expiry.
-//
-// Sourced from the donor hub `Public/trae2api-hub` (`_refresh_account_request`
-// in `trae_client.py`).
 
 import { randomUUID } from "node:crypto";
 import { firstNonEmptyString as firstString } from "../../../shared/coerce";
@@ -50,10 +47,9 @@ const TRAE_OAUTH_USER_AGENT = "Trae/1.0.0 antigravity-cockpit-tools";
 /**
  * Plugin version the desktop client reports.
  *
- * Observed in a real authorize URL as `2.3.93439`. The donor sent `local`,
- * which is what the *web* build reports; the login page accepts it, but the
- * value is part of the fingerprint upstream correlates, so the desktop shape
- * is used here.
+ * Observed in a real authorize URL as `2.3.93439`. The web build reports
+ * `local`; the login page accepts it, but the value is part of the fingerprint
+ * upstream correlates, so the desktop shape is used here.
  */
 const TRAE_PLUGIN_VERSION = "2.3.93439";
 
@@ -61,9 +57,9 @@ const TRAE_PLUGIN_VERSION = "2.3.93439";
  * Device context for the login.
  *
  * Derived with the same function the data plane uses, so one account presents
- * one device across login and requests. A per-process random pair — what the
- * donor sends — made every gateway restart look like a brand new device to the
- * risk-control surface that correlates them.
+ * one device across login and requests. A per-process random pair would make
+ * every gateway restart look like a brand new device to the risk-control
+ * surface that correlates them.
  *
  * The seed is the login trace id because no account identity exists yet: the
  * authorize step is what produces the account.
@@ -102,10 +98,11 @@ interface TraeExchangeResponse extends TraeExchangeResult {
 
 export class TraeOAuthClient extends OAuthClient {
   /**
-   * Trae has no device-code flow — the donor's `start_login` answers
-   * `unsupported` for it — but it does have a browser authorization flow:
-   * `GetLoginGuidance` discovers the login host, the operator signs in there,
-   * and the callback carries a refresh token that `ExchangeToken` redeems.
+   * Trae has no device-code flow — an earlier probe of the device-authorization
+   * surface answered `unsupported` for it — but it does have a browser
+   * authorization flow: `GetLoginGuidance` discovers the login host, the
+   * operator signs in there, and the callback carries a refresh token that
+   * `ExchangeToken` redeems.
    *
    * Declaring only the browser half is what keeps the console from offering a
    * device login that cannot work.
@@ -691,7 +688,7 @@ interface TraeCallbackPayload {
  * Upstream has two shapes and the page picks by how the login started:
  *
  * - `?isRedirect=true&refreshToken=…&refreshExpireAt=…` — the refresh-token
- *   flow, which is what the donor implements.
+ *   flow.
  * - `?isRedirect=true&scope=trae&authCodeInfo={"AuthCode":…}&host=…` — the PKCE
  *   flow, which is what the live page actually produces here. The code inside
  *   `authCodeInfo` is what `public/oauth/ExchangeToken` redeems against the

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

@@ -8,9 +8,6 @@
 // 2. Message `content` must be an array of parts. A plain string is refused
 //    (400/4001), so every message is normalized to parts even when there is
 //    only text.
-//
-// Sourced from the donor hub `Public/trae2api-hub` (`build_chat_body` and
-// `iter_events` in `trae_client.py`).
 
 import type { CanonicalRequest, ContentPart } from "../../../protocol/canonical-model";
 import { resolveWireMaxTokens } from "../../../protocol/translation/quirks";
@@ -79,9 +76,9 @@ export interface TraeToolCall {
 /**
  * Generation fields upstream accepts.
  *
- * Undeclared fields are deliberately omitted: the donor notes that sending
- * anything outside this set risks a 4001, so `provider_options` is never
- * spread into the body wholesale.
+ * Undeclared fields are deliberately omitted: sending anything outside this
+ * set risks a 4001, so `provider_options` is never spread into the body
+ * wholesale.
  */
 const PASSTHROUGH_OPTIONS = ["temperature", "top_p", "max_tokens", "stop"] as const;
 

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

@@ -9,11 +9,11 @@
 // - `ide_user_ent_usage` on the **pay** host is the entitlement: which package
 //   the account holds and when it lapses.
 //
-// The donor reads both and lets either fail without the other, and that
-// tolerance is load-bearing here too: entitlement is a *pay* host, which is the
-// first thing a region-blocked or unpaid account loses. Letting a dead pay host
-// fail the whole read would report "no quota" for an account whose session
-// meter is perfectly readable — and "no quota" is what the router parks on.
+// Both are read and either may fail without the other: entitlement is a *pay*
+// host, which is the first thing a region-blocked or unpaid account loses.
+// Letting a dead pay host fail the whole read would report "no quota" for an
+// account whose session meter is perfectly readable — and "no quota" is what
+// the router parks on.
 //
 // Headers come from `buildTraeHeaders` rather than being rebuilt here: the
 // device fingerprint is derived from the uid, and an account that reports one
@@ -39,14 +39,16 @@ import { buildTraeHeaders } from "./trae-headers";
 import { log } from "../../../observability/logger";
 import {
   TRAE_ENT_USAGE_PATH,
+  TRAE_ENT_USAGE_PATH_V2,
   TRAE_REGION_CORE_HOSTS,
+  TRAE_REGION_PAY_HOSTS,
   TRAE_REALMS,
   TRAE_SESSION_USAGE_PATH,
   type TraeRealm,
 } from "./trae-realm";
 
 /**
- * The buckets `remain_usage` carries, in the order the donor reads them.
+ * The buckets `remain_usage` carries, in the order they are read.
  *
  * `advanced_model` and `premium_model_*` are request counts; `dollar_basic` and
  * `dollar_bonus` are spend balances. They are separate budgets and must never
@@ -210,30 +212,96 @@ function parseSessionUsage(payload: unknown): {
   return { windows, plan };
 }
 
-/** The entitlement package name and lapse, from the pay host. */
+/**
+ * The entitlement payload, from the pay host.
+ *
+ * Shape verified live (2026-11-06, intl Free plan):
+ *
+ *   {
+ *     "billing_version": 3,
+ *     "is_dollar_usage_billing": true,
+ *     "user_entitlement_pack_list": [{
+ *       "display_desc": "Free plan",
+ *       "entitlement_base_info": {
+ *         "end_time": 1796083199,
+ *         "quota": { "advanced_model_request_limit": 1000, ... }
+ *       },
+ *       "quota": { "advanced_model_request_limit": 1000, ... },
+ *       "usage": { "basic_usage_amount": 0, ... },
+ *       "status": 1,
+ *       "expire_time": 0
+ *     }]
+ *   }
+ *
+ * The v2 surface (CN realm) instead carries a `usage_summary` block:
+ *
+ *   { "total_amount": 900, "consumed_amount": 0.39, ... }
+ *
+ * Limits live in `entitlement_base_info.quota` (or the sibling `quota`)
+ * as `<bucket>_limit` fields. There is no consumed/remaining count in the
+ * v1 shape — `used` stays null, and the window reports just the cap.
+ */
 function parseEntitlement(payload: unknown): {
   readonly windows: readonly ProviderQuotaWindow[];
   readonly plan: string | null;
 } {
   const root = record(payload) ?? {};
   const data = record(root["data"]) ?? root;
-  const items = Array.isArray(data["entitlement_list"])
-    ? data["entitlement_list"]
-    : Array.isArray(data["list"])
-      ? data["list"]
+  const packs = Array.isArray(data["user_entitlement_pack_list"])
+    ? data["user_entitlement_pack_list"]
+    : Array.isArray(data["entitlement_list"])
+      ? data["entitlement_list"]
       : [];
   const windows: ProviderQuotaWindow[] = [];
   let plan: string | null = null;
-  for (const entry of items) {
-    const item = record(entry);
-    if (!item) continue;
-    const name = text(item["ent_title"] ?? item["name"] ?? item["package_name"]);
+
+  // The pack's `quota` block names its fields `<bucket>_limit` — with the
+  // word `request` inside for the model buckets (`advanced_model_request_limit`),
+  // and `usage_limit` for the dollar buckets (`basic_usage_limit`). Mapping
+  // them explicitly beats string-concatenating the bucket id.
+  const LIMIT_FIELDS: Readonly<Record<string, string>> = {
+    advanced_model: "advanced_model_request_limit",
+    premium_model_fast_request: "premium_model_fast_request_limit",
+    premium_model_slow_request: "premium_model_slow_request_limit",
+    dollar_basic: "basic_usage_limit",
+    dollar_bonus: "bonus_usage_limit",
+  };
+  const LABELS = new Map<string, string>([...REQUEST_BUCKETS, ...DOLLAR_BUCKETS]);
+
+  for (const entry of packs) {
+    const pack = record(entry);
+    if (!pack) continue;
+    const base = record(pack["entitlement_base_info"]) ?? {};
+    const quota = record(base["quota"]) ?? record(pack["quota"]) ?? {};
+    const name = text(pack["display_desc"]) ?? text(pack["name"]) ?? text(pack["title"]);
     if (!plan && name) plan = name;
-    const total = number(item["total"] ?? item["quota"] ?? item["advanced_model_request_limit"]);
-    const remaining = number(item["remain"] ?? item["remaining"] ?? item["remain_usage"]);
-    const resetsAt = isoDate(item["end_time"] ?? item["endTime"] ?? item["expires_at"]);
-    const window = bucketWindow(name ?? "Entitlement", remaining, total, resetsAt);
-    if (window) windows.push(window);
+    const resetsAt = isoDate(
+      number(base["end_time"]) ?? number(pack["end_time"]) ?? number(pack["expire_time"]),
+    );
+
+    // v2 surface (CN realm): the summary carries the total and consumed
+    // amounts; use it as a single window when present.
+    const summary = record(record(data["usage_summary"]) ?? record(pack["usage_summary"]));
+    if (summary) {
+      const window = bucketWindow(
+        name ?? "Plan",
+        number(summary["consumed_amount"]),
+        number(summary["total_amount"]),
+        resetsAt,
+      );
+      if (window) windows.push(window);
+      continue;
+    }
+
+    // v1 surface: `<bucket>_limit` fields, no consumption count — the cap
+    // is all this shape can report.
+    for (const [key, limitField] of Object.entries(LIMIT_FIELDS)) {
+      const limit = number(quota[limitField]);
+      if (limit === null) continue;
+      const label = LABELS.get(key) ?? key;
+      const window = percentWindow(`trae:${key}`, label, null, resetsAt, null, limit, "independent");
+      if (window) windows.push(window);
+    }
   }
   return { windows, plan };
 }
@@ -268,6 +336,17 @@ function coreHost(region: string, config: (typeof TRAE_REALMS)[TraeRealm]): stri
   return (region !== "" ? TRAE_REGION_CORE_HOSTS[region] : undefined) ?? config.core;
 }
 
+/**
+ * The pay host for this account.
+ *
+ * The pay surface correlates the credential against its region, too: an `sg`
+ * account sent to the US pay host is answered 401 code 1001, while the SG pay
+ * host accepts the same token (verified live 2026-11-06).
+ */
+function payHost(region: string, config: (typeof TRAE_REALMS)[TraeRealm]): string {
+  return (region !== "" ? TRAE_REGION_PAY_HOSTS[region] : undefined) ?? config.pay;
+}
+
 export async function fetchTraeQuota(
   credential: string,
   fetcher: FetchLike,
@@ -349,7 +428,10 @@ export async function fetchTraeQuota(
   };
 
   const session = await tryRealms((config) => coreHost(region, config) + TRAE_SESSION_USAGE_PATH, "session usage", parseSessionUsage);
-  const entitlement = await tryRealms((config) => config.pay + TRAE_ENT_USAGE_PATH, "entitlement", parseEntitlement);
+  // The entitlement path differs by realm: the CN realm answers v2 (v1 lacks
+  // `usage_summary` there), the intl realm answers v1 (v2 is a 404).
+  const entPath = realm === "cn" ? TRAE_ENT_USAGE_PATH_V2 : TRAE_ENT_USAGE_PATH;
+  const entitlement = await tryRealms((config) => payHost(region, config) + entPath, "entitlement", parseEntitlement);
 
   const windows = [...(session?.windows ?? []), ...(entitlement?.windows ?? [])];
   if (!session && !entitlement) {

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

@@ -1,17 +1,13 @@
-// Trae realms: one vendor, two unrelated deployments.
-//
-// `trae` (global / intl) and `traecn` (China) share the wire protocol — an
-// `x-ide-token` credential, a `model_name` body, an SSE stream — but nothing
-// else about the address: different core host, different account/oauth host,
-// different UA, a *different authorization scheme*, and a different model
-// roster. Treating them as one provider with a region flag is what would send
-// a CN account to `*.traeapi.us` and get it refused.
+// Regions are per-realm constants: `trae` (global / intl) and `traecn`
+// (China) share the wire protocol — an `x-ide-token` credential, a
+// `model_name` body, an SSE stream — but nothing else about the address:
+// different core host, different account/oauth host, different UA, a
+// *different authorization scheme*, and a different model roster. Treating
+// them as one provider with a region flag is what would send a CN account to
+// `*.traeapi.us` and get it refused.
 //
 // Everything per-realm lives here so the adapter, the auth builder, and the
 // discovery fetcher cannot drift apart on host, UA, or version code.
-//
-// Sourced from the donor hub `Public/trae2api-hub` (`REALMS` in
-// `trae_client.py`, `TRAEREALMS`-shaped config in `trae_accounts.py`).
 
 /** One Trae deployment. */
 export type TraeRealm = "intl" | "cn";
@@ -43,7 +39,7 @@ export interface TraeRealmConfig {
 /**
  * Chat path, identical across realms.
  *
- * The list endpoint takes a body (`{"type":"chat"}`); the donor posts it, so
+ * The list endpoint takes a body (`{"type":"chat"}`); upstream posts it, so
  * this is not a bare GET.
  */
 export const TRAE_CHAT_PATH = "/api/ide/v1/llm_raw_chat";
@@ -101,8 +97,8 @@ export const TRAE_AUTHORIZATION_PATH = "/authorization";
  * `/`, a trailing slash — is answered with "Login Failed" before the operator
  * gets to sign in, so the gateway's own `/callback` default cannot be used.
  *
- * The donor serves this on its own dynamic port; here the port comes from the
- * gateway's redirect setting and only the path is fixed.
+ * This gateway serves this on its own configured port and only the path is
+ * fixed.
  */
 export const TRAE_CALLBACK_PATH = "/authorize";
 
@@ -123,6 +119,14 @@ export const TRAE_LOGIN_GUIDANCE_URLS: readonly string[] = [
 /** Usage / entitlement paths, relative to the realm's `pay` host. */
 export const TRAE_SESSION_USAGE_PATH = "/api/v1/commercial/get_session_usage";
 export const TRAE_ENT_USAGE_PATH = "/trae/api/v1/pay/ide_user_ent_usage";
+/**
+ * The v2 entitlement path, used by the CN realm.
+ *
+ * Verified live (2026-11-06): the CN realm answers v2 — v1 lacks the
+ * `usage_summary` block there — while the intl realm answers v1 (v2 is a
+ * 404 on the intl pay host).
+ */
+export const TRAE_ENT_USAGE_PATH_V2 = "/trae/api/v2/pay/ide_user_ent_usage";
 
 /**
  * Realm → deployment.
@@ -169,7 +173,10 @@ export const TRAE_REALMS: Readonly<Record<TraeRealm, TraeRealmConfig>> = {
     coreFallbacks: ["https://core-normal.traeapi.us", "https://core-normal.trae.ai"],
     account: "https://grow-normal.trae.ai",
     accountFallbacks: ["https://grow-normal.traeapi.us"],
-    pay: "https://grow-normal.traeapi.us",
+    // SG default, like the core: the pay surface is region-correlated too, and
+    // the SG host answers an sg-provisioned (or region-unrecorded intl) account
+    // that the US host refuses with 401 code 1001 (verified live 2026-11-06).
+    pay: "https://grow-normal.trae.ai",
     ug: "https://grow-normal.traeapi.us",
     userAgent: "Trae/3.6.2",
     versionCode: "20260212",
@@ -196,6 +203,20 @@ export const TRAE_REGION_CORE_HOSTS: Readonly<Record<string, string>> = {
   us: "https://core-normal.traeapi.us",
 };
 
+/**
+ * Pay host per account region, when the login reported one.
+ *
+ * Verified live (2026-11-06): an `sg` account's token is refused by the US
+ * pay host with `401 code 1001` ("we are not able to authenticate you"), and
+ * accepted by the SG pay host. Same region-routing rule as the core host —
+ * the pay surface correlates the credential against its region, so a
+ * provisioned region must pick its own pay host too.
+ */
+export const TRAE_REGION_PAY_HOSTS: Readonly<Record<string, string>> = {
+  sg: "https://grow-normal.trae.ai",
+  us: "https://grow-normal.traeapi.us",
+};
+
 /** The app id is constant across realms. */
 export const TRAE_APP_ID = "6eefa01c-1036-4c7e-9ca5-d891f63bfcd8";
 

package/src/providers/integrations/trae/trae.ts

@@ -22,6 +22,7 @@ import { resolvePromptCacheKey } from "../../operations/session-resolution";
 import { estimateTraeSessionCache } from "./trae-cache";
 import { TRAE_CN_MODELS, TRAE_INTL_MODELS, traeMaxContextWindow } from "./trae-catalog";
 import { buildTraeHeaders } from "./trae-headers";
+import { getTraeVersion } from "../../operations/client-versions";
 import {
   buildTraeChatBody,
   isTraeAgentEndpoint,
@@ -30,7 +31,7 @@ import {
   TRAE_AGENT_ENDPOINT,
   TRAE_CHAT_ENDPOINT,
 } from "./trae-protocol";
-import { TRAE_REGION_CORE_HOSTS, traeCoreCandidates, type TraeRealm } from "./trae-realm";
+import { TRAE_REGION_CORE_HOSTS, traeCoreCandidates, TRAE_MODEL_LIST_PATH, TRAE_AGENT_FUNCTION, type TraeRealm } from "./trae-realm";
 
 export interface TraeAdapterOptions {
   readonly providerId?: string;
@@ -94,13 +95,22 @@ function extractToken(secret: string): string | undefined {
  * Maps a Trae upstream error (a named `error` SSE event, or an error object
  * in a frame body) to the canonical GatewayError.
  *
- * The mapping mirrors the reference bridge's `TRAE_ERROR_MAP`:
+ * Codes resolved from live probing (2026-11-06), not guessed:
  * - `1001` — "we are not able to authenticate you" — is a credential verdict.
  *   It must surface as account-scoped `authentication_failed` so the account
  *   is parked for re-login and failover tries a sibling — never the proxy
- *   pool.
+ *   pool. Note: the pay host answers it on *region mismatch* too (an sg
+ *   account sent to the us pay host), which is not the same as an expired
+ *   token — a token that answers `GetUserInfo` 200 is alive.
  * - `4008` / "exceeded the quota" — free-tier quota exhausted. That is a
  *   `quota_exceeded` 429, not a platform fault.
+ * - `1005` (extra `{"plan":N}`) and `4015` — entitlement verdicts. Verified
+ *   live: identical wire, a paid-capable account streams the same model fine
+ *   while a Free account is refused with these codes, and the refused
+ *   account's token still answers `GetUserInfo` 200. Neither auth nor
+ *   platform fault: `quota_exceeded`.
+ * - `4013` / region message — durable regional unavailability, scoped by the
+ *   classifier to the account (`trae-region-unavailable`).
  * - Everything else is a platform fault (`platform_unavailable`).
  */
 function throwTraeUpstreamError(
@@ -163,6 +173,27 @@ function throwTraeUpstreamError(
     );
   }
 
+  // `1005` and `4015` are entitlement verdicts, not auth failures and not
+  // platform faults. Verified live: the same wire streams fine on a
+  // paid-capable account while a Free account is refused with these codes,
+  // and the refused account's token still answers `GetUserInfo` 200. Treating
+  // them as auth would park the account for re-login pointlessly; treating
+  // them as platform faults would failover to another account that hits the
+  // same wall. They are `quota_exceeded` — the model/account cannot serve.
+  if (code === "1005" || code === "4015") {
+    throw new GatewayError(
+      "quota_exceeded",
+      429,
+      `Trae model not available on this account (upstream code ${code}): ${message} (request {requestId}). The model needs a plan or permission this account does not hold — pick another model or account ⏳`,
+      {
+        providerCode: code,
+        providerStatus: code === "1005" ? 1005 : 4015,
+        ...(providerId ? { providerId } : {}),
+      },
+      "upstream",
+    );
+  }
+
   throw new GatewayError(
     "platform_unavailable",
     502,
@@ -234,6 +265,8 @@ class TraeAdapter implements ProviderAdapter {
       token: auth.token,
       uid: auth.uid,
       stream: true,
+      appVersion: getTraeVersion(),
+      trafficType: agentSurface ? "agent" : "chat",
     });
 
     const primary = traeCoreForAccount(this.realm, context.credential.auth_state);
@@ -326,7 +359,7 @@ class TraeAdapter implements ProviderAdapter {
       /**
        * Two frame layouts reach here and both are live.
        *
-       * The donor's client nests the answer under `chunk`; the region host this
+       * Upstream's client nests the answer under `chunk`; the region host this
        * gateway talks to sends it flat — `event: output` with
        * `{"response":"…"}` — and reports usage as a separate `token_usage`
        * frame with the OpenAI spelling at the top level. Reading only `chunk`
@@ -503,6 +536,17 @@ export function createTraeCnAdapter(options: TraeAdapterOptions = {}): ProviderA
 /**
  * Live model discovery.
  *
+ * The source follows the realm, not one endpoint:
+ *
+ * - **intl** — the agent picker (`batch_get_detail_param` with
+ *   `function: solo_agent`), filtered to `usage == "chat_completion"` rows.
+ *   The chat `model_list` is NOT the intl source: it lists only the legacy
+ *   nine chat ids, and an agent roster row (`gpt-5-paygo`,
+ *   `deepseek-v4.1-flash`, `search_agent_*`, …) is absent from it (verified
+ *   live 2026-11-06). Reading it would replace the agent catalog with models
+ *   the agent surface rejects (`4023 model is unknown`).
+ * - **CN** — the chat `model_list`, which is the surface that serves CN.
+ *
  * The listing is per account region, not per realm: it answers on CN and on the
  * intl region host that serves the account (`coresg-normal.trae.ai` verified),
  * while the generic intl core answers `403 no schema found`. An empty result is
@@ -526,8 +570,54 @@ export async function discoverTraeModels(input: {
     realm: input.realm,
     token: input.token,
     uid: input.uid,
+    appVersion: getTraeVersion(),
   });
-  const url = `${traeCoreForAccount(input.realm, input.region === undefined ? undefined : { region: input.region })}/api/ide/v1/model_list`;
+  const core = traeCoreForAccount(
+    input.realm,
+    input.region === undefined ? undefined : { region: input.region },
+  );
+
+  if (input.realm === "intl") {
+    // The agent picker: the only surface that lists the intl roster's configs.
+    const url = `${core}/api/ide/v1/batch_get_detail_param`;
+    const response = await input.fetcher(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ functions: [TRAE_AGENT_FUNCTION], Request: {} }),
+      ...(input.signal ? { signal: input.signal } : {}),
+    });
+    if (!response.ok) return [];
+    const parsed = (await response.json()) as { function_configs?: unknown };
+    const groups = Array.isArray(parsed.function_configs) ? parsed.function_configs : [];
+    const out: { id: string; ctx: number | undefined }[] = [];
+    for (const group of groups) {
+      if (typeof group !== "object" || group === null) continue;
+      const list = (group as Record<string, unknown>)["config_info_list"];
+      if (!Array.isArray(list)) continue;
+      for (const entry of list) {
+        if (typeof entry !== "object" || entry === null) continue;
+        const row = entry as Record<string, unknown>;
+        // Only chat-capable configs are dispatch targets; fast_apply,
+        // title_generation, etc. are not.
+        if (String(row["usage"] ?? "") !== "chat_completion") continue;
+        const id = String(row["config_name"] ?? "").trim();
+        if (id.length === 0) continue;
+        // Context: the picker row carries `model_detail_list` with the real
+        // upstream rows; prefer the widest selectable window among them.
+        let ctx: number | undefined;
+        const details = Array.isArray(row["model_detail_list"]) ? row["model_detail_list"] : [];
+        for (const detail of details) {
+          const w = traeMaxContextWindow(detail);
+          if (w !== undefined && (ctx === undefined || w > ctx)) ctx = w;
+        }
+        out.push({ id, ctx });
+      }
+    }
+    return out;
+  }
+
+  // CN: the chat roster surface.
+  const url = `${core}${TRAE_MODEL_LIST_PATH}`;
   const response = await input.fetcher(url, {
     method: "POST",
     headers,
@@ -550,8 +640,8 @@ export async function discoverTraeModels(input: {
   return rows
     .filter((row): row is Record<string, unknown> => typeof row === "object" && row !== null)
     .map((row) => ({
-      // `model_name` is the key upstream's listing uses; the others are the
-      // spellings the older donors assumed.
+      // `model_name` is the key upstream's listing uses; `name`/`id` are
+      // spellings older snapshots assumed.
       id: String(row["model_name"] ?? row["name"] ?? row["id"] ?? "").trim(),
       ctx: traeMaxContextWindow(row),
     }))