cartethyia 2.7.3 → 2.7.5

package/src/providers/integrations/shared/connect.ts

@@ -5,24 +5,6 @@
 // end-of-stream trailer. Compression and trailer semantics stay at the call
 // sites; this module owns only the envelope arithmetic.
 
-/** Payload is gzip-compressed. */
-export const CONNECT_COMPRESSED_FLAG = 0x01;
-/** Frame carries the end-of-stream trailer rather than a message. */
-export const CONNECT_END_STREAM_FLAG = 0x02;
-
-/** One decoded Connect envelope. */
-interface ConnectFrame {
-  readonly flags: number;
-  readonly payload: Uint8Array;
-}
-
-interface ConsumeConnectFramesOptions {
-  /** Reject frames whose declared payload exceeds this many bytes. */
-  readonly maxPayloadBytes?: number;
-  /** Builds the error thrown for an oversized frame; defaults to a plain `Error`. */
-  readonly oversizeError?: (declaredLength: number) => Error;
-}
-
 /** Initial allocation for a frame buffer that has not received a chunk yet. */
 const FRAME_BUFFER_MIN_BYTES = 4096;
 /** Ceiling on the spare capacity kept above the live length when growing. */
@@ -84,39 +66,3 @@ export class FrameBuffer {
     this.start = 0;
   }
 }
-
-/** Wraps `payload` in a 5-byte Connect envelope. */
-export function frameConnectMessage(payload: Uint8Array, flags = 0) {
-  const frame = Buffer.alloc(5 + payload.length);
-  frame.writeUInt8(flags, 0);
-  frame.writeUInt32BE(payload.length, 1);
-  frame.set(payload, 5);
-  return frame;
-}
-
-/**
- * Splits every complete Connect frame out of `buffer`, in order. Returns the
- * trailing bytes that do not yet form a complete frame so a streaming caller
- * can prepend them to the next chunk and call again.
- */
-export function consumeConnectFrames(
-  buffer: Buffer,
-  options: ConsumeConnectFramesOptions = {},
-): { frames: ConnectFrame[]; rest: Buffer } {
-  const frames: ConnectFrame[] = [];
-  let pending = buffer;
-  while (pending.length >= 5) {
-    const flags = pending[0] ?? 0;
-    const length = pending.readUInt32BE(1);
-    if (options.maxPayloadBytes !== undefined && length > options.maxPayloadBytes) {
-      throw (
-        options.oversizeError?.(length) ??
-        new Error(`Connect frame length ${length} exceeds cap`)
-      );
-    }
-    if (pending.length < 5 + length) break;
-    frames.push({ flags, payload: pending.subarray(5, 5 + length) });
-    pending = pending.subarray(5 + length);
-  }
-  return { frames, rest: pending };
-}

package/src/providers/integrations/shared/hash.ts

@@ -0,0 +1,15 @@
+/**
+ * 32-bit FNV-1a hash.
+ *
+ * Single source for the two former inline copies (claude `hashBody`,
+ * cursor `cursorAccountTag`). Fast, deterministic, sufficient for cache
+ * identity / short display tags — not a cryptographic hash.
+ */
+export function fnv1a32(input: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}

package/src/providers/integrations/shared/session-cache.ts

@@ -0,0 +1,136 @@
+// Shared session-cache estimation factory.
+//
+// The Kiro and Trae adapters both need to ESTIMATE prompt-cache hits locally
+// because their upstream surfaces never report them. Their logic is
+// byte-identical modulo the provider header comment, so it lives here once —
+// but the state must stay per-provider: a factory call creates a private Map
+// per integration, so cross-provider session-id collisions can never
+// contaminate each other's estimates. Call each provider's wrapper
+// (kiro-cache.ts / trae-cache.ts); do not import this module directly.
+
+import { createHash } from "node:crypto";
+import type { CanonicalMessage, UsageRecord } from "../../../protocol/canonical-model";
+
+/** Bounded in-memory tracker: one entry per session, oldest evicted first. */
+export const SESSION_CACHE_MAX_SESSIONS = 512;
+
+interface SessionCacheEntry {
+  /** hash(full messages) -> reported input tokens for that exact list. */
+  readonly seen: Map<string, number>;
+  /** Insertion order for bounded eviction. */
+  readonly order: string[];
+}
+
+export interface SessionCache {
+  estimate(
+    record: UsageRecord,
+    sessionId: string | undefined,
+    messages: readonly CanonicalMessage[] | undefined,
+  ): UsageRecord;
+  resetForTesting(): void;
+}
+
+function hashOf(messages: readonly CanonicalMessage[]): string {
+  return createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+}
+
+/**
+ * Creates an isolated session-cache estimator: its own private session Map,
+ * bounded at SESSION_CACHE_MAX_SESSIONS with per-entry oldest-first eviction.
+ */
+export function createSessionCache(): SessionCache {
+  const sessions = new Map<string, SessionCacheEntry>();
+
+  function sessionFor(sessionId: string): SessionCacheEntry {
+    let entry = sessions.get(sessionId);
+    if (!entry) {
+      entry = { seen: new Map(), order: [] };
+      sessions.set(sessionId, entry);
+    }
+    return entry;
+  }
+
+  function remember(sessionId: string, fullHash: string, inputTokens: number): void {
+    const entry = sessionFor(sessionId);
+    if (!entry.seen.has(fullHash)) {
+      entry.order.push(fullHash);
+      if (entry.order.length > SESSION_CACHE_MAX_SESSIONS) {
+        const oldest = entry.order.shift();
+        if (oldest !== undefined) entry.seen.delete(oldest);
+      }
+    }
+    entry.seen.set(fullHash, inputTokens);
+    if (sessions.size > SESSION_CACHE_MAX_SESSIONS) {
+      const oldestSession = sessions.keys().next().value;
+      if (oldestSession !== undefined) sessions.delete(oldestSession);
+    }
+  }
+
+  return {
+    estimate(record, sessionId, messages) {
+      if (!sessionId || !messages || messages.length === 0) return record;
+      const upstreamReported =
+        typeof record.cached_input_tokens === "number" && record.cached_input_tokens > 0;
+      if (upstreamReported) return record;
+
+      const fullHash = hashOf(messages);
+      const entry = sessions.get(sessionId);
+
+      if (entry) {
+        // Longest prefix that matches a previously sent complete request.
+        for (let len = messages.length; len >= 1; len -= 1) {
+          const prefix = messages.slice(0, len);
+          const tokens = entry.seen.get(hashOf(prefix));
+          if (tokens === undefined) continue;
+          if (len === messages.length) {
+            // Byte-identical request: the whole input came from cache.
+            return {
+              ...record,
+              cached_input_tokens: record.input_tokens,
+              uncached_input_tokens: 0,
+            };
+          }
+          const cached = Math.min(tokens, record.input_tokens);
+          return {
+            ...record,
+            cached_input_tokens: cached,
+            uncached_input_tokens: Math.max(0, record.input_tokens - cached),
+          };
+        }
+      }
+
+      remember(sessionId, fullHash, record.input_tokens);
+      return record;
+    },
+
+    resetForTesting() {
+      sessions.clear();
+    },
+  };
+}
+
+/**
+ * Estimates how much of this request's input was served from cache.
+ *
+ * The longest prefix of `messages` that was ever sent as a complete request in
+ * this session is considered cached, and its recorded token count is the
+ * cached portion — if that prefix is the whole request, everything was cached.
+ * This models how upstream prompt caching actually behaves (byte-identical
+ * prefix reuse) without trusting a counter the upstream never reports.
+ *
+ * Returns the record unchanged when there is nothing to estimate (no session,
+ * no history, or upstream already reported a real hit).
+ */
+export function estimateSessionCache(
+  cache: SessionCache,
+  record: UsageRecord,
+  sessionId: string | undefined,
+  messages: readonly CanonicalMessage[] | undefined,
+): UsageRecord {
+  return cache.estimate(record, sessionId, messages);
+}
+
+/** Drops all tracked sessions in this cache. Test-only. */
+export function resetSessionCacheForTesting(cache: SessionCache): void {
+  cache.resetForTesting();
+}

package/src/providers/integrations/tokenharbor.ts

@@ -71,11 +71,11 @@ export const TOKENHARBOR_FALLBACK_MODELS: readonly ModelDefinition[] = [
 function tokenharborPrePayload(payload: Record<string, unknown>): void {
   const model = payload["model"];
   if (typeof model !== "string" || model.length === 0) {
-    throw new GatewayError("invalid_request", 400, "TokenHarbor model is required");
+    throw new GatewayError("invalid_request", 400, "TokenHarbor model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   // Strip accidental query-string smuggling (mirrors the factory's own guard)
   if (model.includes("?")) {
-    throw new GatewayError("invalid_request", 400, "TokenHarbor model must not contain query string");
+    throw new GatewayError("invalid_request", 400, "TokenHarbor model must not contain query string (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
 }
 

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

@@ -7,104 +7,24 @@
 // conversation we ESTIMATE the hit locally. This only fills the gap when
 // upstream reports nothing (0 or unavailable); a genuine upstream report (>0)
 // is trusted and left untouched.
+//
+// The state lives in a factory-created instance, so Trae's sessions are fully
+// isolated from Kiro's (and any other consumer of the shared factory).
 
-import { createHash } from "node:crypto";
 import type { CanonicalMessage, UsageRecord } from "../../../protocol/canonical-model";
+import { createSessionCache, estimateSessionCache, resetSessionCacheForTesting } from "../shared/session-cache";
 
-/** Bounded in-memory tracker: one entry per session, oldest evicted first. */
-const MAX_SESSIONS = 512;
-
-interface TraeSessionCacheEntry {
-  /** hash(full messages) -> reported input tokens for that exact list. */
-  readonly seen: Map<string, number>;
-  /** Insertion order for bounded eviction. */
-  readonly order: string[];
-}
-
-const sessions = new Map<string, TraeSessionCacheEntry>();
+const cache = createSessionCache();
 
-function hashOf(messages: readonly CanonicalMessage[]): string {
-  return createHash("sha256").update(JSON.stringify(messages)).digest("hex");
-}
-
-function sessionFor(sessionId: string): TraeSessionCacheEntry {
-  let entry = sessions.get(sessionId);
-  if (!entry) {
-    entry = { seen: new Map(), order: [] };
-    sessions.set(sessionId, entry);
-  }
-  return entry;
-}
-
-function remember(sessionId: string, fullHash: string, inputTokens: number): void {
-  const entry = sessionFor(sessionId);
-  if (!entry.seen.has(fullHash)) {
-    entry.order.push(fullHash);
-    if (entry.order.length > MAX_SESSIONS) {
-      const oldest = entry.order.shift();
-      if (oldest !== undefined) entry.seen.delete(oldest);
-    }
-  }
-  entry.seen.set(fullHash, inputTokens);
-  if (sessions.size > MAX_SESSIONS) {
-    const oldestSession = sessions.keys().next().value;
-    if (oldestSession !== undefined) sessions.delete(oldestSession);
-  }
-}
-
-/**
- * Estimates how much of this request's input was served from cache.
- *
- * The longest prefix of `messages` that was ever sent as a complete request in
- * this session is considered cached, and its recorded token count is the
- * cached portion — if that prefix is the whole request, everything was cached.
- * This models how upstream prompt caching actually behaves (byte-identical
- * prefix reuse) without trusting a counter the upstream never reports.
- *
- * Returns the record unchanged when there is nothing to estimate (no session,
- * no history, or upstream already reported a real hit).
- */
 export function estimateTraeSessionCache(
   record: UsageRecord,
   sessionId: string | undefined,
   messages: readonly CanonicalMessage[] | undefined,
 ): UsageRecord {
-  if (!sessionId || !messages || messages.length === 0) return record;
-  const upstreamReported =
-    typeof record.cached_input_tokens === "number" && record.cached_input_tokens > 0;
-  if (upstreamReported) return record;
-
-  const fullHash = hashOf(messages);
-  const entry = sessions.get(sessionId);
-
-  if (entry) {
-    // Longest prefix that matches a previously sent complete request.
-    for (let len = messages.length; len >= 1; len -= 1) {
-      const prefix = messages.slice(0, len);
-      const tokens = entry.seen.get(hashOf(prefix));
-      if (tokens === undefined) continue;
-      if (len === messages.length) {
-        // Byte-identical request: the whole input came from cache.
-        return {
-          ...record,
-          cached_input_tokens: record.input_tokens,
-          uncached_input_tokens: 0,
-        };
-      }
-      const cached = Math.min(tokens, record.input_tokens);
-      return {
-        ...record,
-        cached_input_tokens: cached,
-        uncached_input_tokens: Math.max(0, record.input_tokens - cached),
-      };
-    }
-  }
-
-  remember(sessionId, fullHash, record.input_tokens);
-  return record;
+  return estimateSessionCache(cache, record, sessionId, messages);
 }
 
 /** Drops all tracked sessions. Test-only. */
 export function resetTraeSessionCacheForTesting(): void {
-  sessions.clear();
+  resetSessionCacheForTesting(cache);
 }

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

@@ -12,7 +12,7 @@
 // intl stays on its static roster and says so via `modelListSupported`.
 
 import { defineModel, type ModelDefinition } from "../../provider-model-definition";
-import { TRAE_AGENT_CHAT_PATH, TRAE_CHAT_PATH, type TraeRealm } from "./trae-realm";
+import { TRAE_AGENT_CHAT_PATH, TRAE_CHAT_PATH } from "./trae-realm";
 
 /** One roster row, as upstream describes it. */
 export interface TraeModelRow {
@@ -135,11 +135,6 @@ function traeModels(rows: readonly TraeModelRow[], providerId: string): readonly
 export const TRAE_CN_MODELS: readonly ModelDefinition[] = traeModels(TRAE_CN_ROWS, "traecn");
 export const TRAE_INTL_MODELS: readonly ModelDefinition[] = traeModels(TRAE_INTL_ROWS, "trae");
 
-/** Roster for a realm. */
-export function traeStaticModels(realm: TraeRealm): readonly ModelDefinition[] {
-  return realm === "cn" ? TRAE_CN_MODELS : TRAE_INTL_MODELS;
-}
-
 /**
  * Reads the largest context window out of one upstream model object.
  *

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

@@ -13,11 +13,11 @@
 // `iter_events` in `trae_client.py`).
 
 import type { CanonicalRequest, ContentPart } from "../../../protocol/canonical-model";
+import { resolveWireMaxTokens } from "../../../protocol/translation/quirks";
 import {
   TRAE_AGENT_CHAT_PATH,
   TRAE_AGENT_FUNCTION,
   TRAE_CHAT_PATH,
-  TRAE_MODEL_LIST_PATH,
   TRAE_REALMS,
   type TraeRealm,
 } from "./trae-realm";
@@ -161,6 +161,7 @@ export function buildTraeChatBody(
   request: CanonicalRequest,
   realm: TraeRealm,
   sessionId?: string,
+  maxOutputTokens?: number,
 ): TraeChatBody {
   if (modelId.length === 0) throw new Error("trae model name is required");
 
@@ -257,13 +258,26 @@ export function buildTraeChatBody(
       },
     }));
   }
+  const requestedMaxTokens =
+    typeof controls.max_tokens === "number" && Number.isFinite(controls.max_tokens)
+      ? controls.max_tokens
+      : undefined;
   const options: Record<string, unknown> = {
     temperature: controls.temperature,
     top_p: controls.top_p,
-    max_tokens: controls.max_tokens,
     stop: controls.stop,
-
   };
+  // Route a numeric `max_tokens` through the shared chat-wire bound so it is
+  // floored to the wire minimum and clamped to the model's roster output limit
+  // — it must never balloon unboundedly (the roster's `out` is the ceiling).
+  // Non-numeric values keep the previous verbatim passthrough, and an absent
+  // value still omits the field (the chat bound must not invent a default here).
+  options["max_tokens"] =
+    requestedMaxTokens === undefined
+      ? controls.max_tokens
+      : resolveWireMaxTokens("chat", { max_tokens: requestedMaxTokens }, {
+          ...(maxOutputTokens === undefined ? {} : { maxOutputTokens }),
+        });
   for (const key of PASSTHROUGH_OPTIONS) {
     const value = options[key];
     if (value !== undefined && value !== null) body[key] = value;
@@ -272,13 +286,8 @@ export function buildTraeChatBody(
 }
 
 /** Body for the live model list. Upstream requires a body even to list. */
-export function buildTraeModelListBody(): Record<string, unknown> {
-  return { type: "chat" };
-}
-
 export const TRAE_CHAT_ENDPOINT = TRAE_CHAT_PATH;
 export const TRAE_AGENT_ENDPOINT = TRAE_AGENT_CHAT_PATH;
-export const TRAE_MODEL_LIST_ENDPOINT = TRAE_MODEL_LIST_PATH;
 
 /**
  * Rewrites a chat-surface body into the agent surface's shape.

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

@@ -88,7 +88,6 @@ export const TRAE_AUTH_CODE_EXCHANGE_PATHS: readonly string[] = [
   "/trae/api/v3/oauth/ExchangeToken",
   "/cloudide/api/v3/public/oauth/ExchangeToken",
 ];
-export const TRAE_TEMP_TOKEN_PATH = "/cloudide/api/v3/trae/GenerateTempToken";
 export const TRAE_GET_USER_INFO_PATH = "/cloudide/api/v3/trae/GetUserInfo";
 
 /** Browser-login path on the host `GetLoginGuidance` names. */
@@ -123,13 +122,7 @@ 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_ACTIVITY_PATH = "/api/v1/commercial/get_user_activity";
 export const TRAE_ENT_USAGE_PATH = "/trae/api/v1/pay/ide_user_ent_usage";
-export const TRAE_PAY_STATUS_PATH = "/trae/api/v1/pay/ide_user_pay_status";
-
-/** Growth paths, relative to the realm's `ug` host. CN-only upstream. */
-export const TRAE_CHECKIN_STATUS_PATH = "/trae/api/v2/ug/checkin_credits/status";
-export const TRAE_CHECKIN_CLAIM_PATH = "/trae/api/v2/ug/checkin_credits/claim";
 
 /**
  * Realm → deployment.

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

@@ -7,9 +7,10 @@
 import { GatewayError } from "../../../protocol/gateway-error";
 import type { CanonicalEvent, CanonicalMessage, CanonicalRequest, CanonicalStopReason } from "../../../protocol/canonical-model";
 import type { UsageRecord } from "../../../protocol/canonical-model";
-import { usageFromProvider } from "../../provider-usage";
+import { applyCacheMode, usageFromProvider } from "../../provider-usage";
 import {
   readCredentialSecret,
+  assertWireFamily,
   type ProviderAdapter,
   type ProviderDispatchContext,
   type ProviderDispatchTarget,
@@ -67,7 +68,7 @@ const STOP_REASONS: Readonly<Record<string, CanonicalStopReason>> = {
 function traeAuth(secret: string, accountId: string | undefined): TraeAuth {
   const token = extractToken(secret);
   if (token === undefined) {
-    throw new GatewayError("authentication_failed", 401, "Trae credential has no access token", {}, "upstream");
+    throw new GatewayError("authentication_failed", 401, "Trae credential has no access token (request {requestId}). Wrong key, right door — check the credential 🔑", {}, "upstream");
   }
   return { token, uid: accountId ?? "" };
 }
@@ -102,7 +103,11 @@ function extractToken(secret: string): string | undefined {
  *   `quota_exceeded` 429, not a platform fault.
  * - Everything else is a platform fault (`platform_unavailable`).
  */
-function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
+function throwTraeUpstreamError(
+  codeRaw: unknown,
+  messageRaw: unknown,
+  providerId?: string,
+): never {
   const code =
     typeof codeRaw === "number" || typeof codeRaw === "string" ? String(codeRaw) : undefined;
   const message =
@@ -116,8 +121,13 @@ function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
     throw new GatewayError(
       "authentication_failed",
       401,
-      `Trae could not authenticate the account (upstream code 1001): ${message}`,
-      { providerCode: "1001", providerStatus: 1001, credentialEvidence: true },
+      `Trae could not authenticate the account (upstream code 1001): ${message} (request {requestId}). Wrong key, right door — check the credential 🔑`,
+      {
+        providerCode: "1001",
+        providerStatus: 1001,
+        credentialEvidence: true,
+        ...(providerId ? { providerId } : {}),
+      },
       "upstream",
     );
   }
@@ -127,13 +137,39 @@ function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
     throw new GatewayError(
       "quota_exceeded",
       429,
-      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message}`,
-      { providerCode: code ?? "4008", providerStatus: code === "4008" ? 4008 : 429 },
+      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message} (request {requestId}). You've maxed this window — pace yourself ⏳`,
+      {
+        providerCode: code ?? "4008",
+        providerStatus: code === "4008" ? 4008 : 429,
+        ...(providerId ? { providerId } : {}),
+      },
       "upstream",
     );
   }
 
-  throw new GatewayError("platform_unavailable", 502, message, {}, "upstream");
+  // Trae answers `4013 "AI service is not available in the current region now."`
+  // when the upstream does not serve the account's region. That is a durable
+  // verdict, not a transient transport fault: the account reproduces it on
+  // every request until the region opens, so it must cool hard rather than be
+  // re-dialled every thirty seconds. The classifier scopes this to the account
+  // (`trae-region-unavailable`) — never the proxy pool.
+  if (code === "4013" || lower.includes("not available in the current region")) {
+    throw new GatewayError(
+      "platform_unavailable",
+      502,
+      message,
+      { providerCode: "4013", ...(providerId ? { providerId } : {}) },
+      "upstream",
+    );
+  }
+
+  throw new GatewayError(
+    "platform_unavailable",
+    502,
+    message,
+    { ...(providerId ? { providerId } : {}) },
+    "upstream",
+  );
 }
 
 class TraeAdapter implements ProviderAdapter {
@@ -152,11 +188,7 @@ class TraeAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `trae supports chat only, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, "chat", "trae");
     }
     const secret = readCredentialSecret(context.credential, "Trae credential is required");
     const modelId = candidate.model_id || request.model;
@@ -175,7 +207,13 @@ class TraeAdapter implements ProviderAdapter {
      * hash) and thread it through.
      */
     const sessionId = request.session_id ?? resolvePromptCacheKey(request, context);
-    const body = buildTraeChatBody(modelId, request, this.realm, sessionId);
+    const body = buildTraeChatBody(
+      modelId,
+      request,
+      this.realm,
+      sessionId,
+      candidate.output_limit ?? undefined,
+    );
     // The cache estimator is scoped per (session, model): upstream cache keys
     // are model-specific, so two models sharing a conversation id must not
     // treat each other's identical prefixes as hits.
@@ -214,7 +252,7 @@ class TraeAdapter implements ProviderAdapter {
       });
       if (!response.ok) throw await mapUpstreamHttpError(response, this.provider_id);
       if (!response.body) {
-        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body", {}, "upstream");
+        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       }
       // Headers arrived, so the pre-stream deadline has served its purpose;
       // from here the gateway's own stall watchdog governs the body.
@@ -270,7 +308,7 @@ class TraeAdapter implements ProviderAdapter {
       }
       if (frame.event === "error") {
         const data = frame.data as { message?: unknown; code?: unknown };
-        throwTraeUpstreamError(data.code, data.message);
+        throwTraeUpstreamError(data.code, data.message, this.provider_id);
       }
       if (typeof frame.data !== "object" || frame.data === null) continue;
       const record = frame.data as Record<string, unknown>;
@@ -283,7 +321,7 @@ class TraeAdapter implements ProviderAdapter {
         const nested = record["error"] as Record<string, unknown> | undefined;
         const code = record["code"] ?? nested?.["code"];
         const message = record["message"] ?? nested?.["message"];
-        throwTraeUpstreamError(code, message);
+        throwTraeUpstreamError(code, message, this.provider_id);
       }
       /**
        * Two frame layouts reach here and both are live.
@@ -441,8 +479,10 @@ class TraeAdapter implements ProviderAdapter {
     const record = usageFromProvider(usage);
     if (record === undefined) return undefined;
     // Trae's agent surface never reports prompt-cache hits; for repeated
-    // prefixes we estimate them locally (see trae-cache.ts).
-    return estimateTraeSessionCache(record, sessionId, messages);
+    // prefixes we estimate them locally (see trae-cache.ts). Then the
+    // operator's cache mode decides whether a hit makes the whole input count
+    // as cached.
+    return applyCacheMode(estimateTraeSessionCache(record, sessionId, messages));
   }
 
 }

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

@@ -44,10 +44,10 @@ const XAI_AUTH_SERVER = {
 } as const;
 
 export { XAI_AUTH_SERVER };
-export const XAI_CLIENT_ID = XAI_AUTH_SERVER.clientId;
-export const XAI_DEVICE_URL = XAI_AUTH_SERVER.deviceUrl;
-export const XAI_TOKEN_URL = XAI_AUTH_SERVER.tokenUrl;
-export const XAI_USERINFO_URL = XAI_AUTH_SERVER.userinfoUrl;
+const XAI_CLIENT_ID = XAI_AUTH_SERVER.clientId;
+const XAI_DEVICE_URL = XAI_AUTH_SERVER.deviceUrl;
+const XAI_TOKEN_URL = XAI_AUTH_SERVER.tokenUrl;
+const XAI_USERINFO_URL = XAI_AUTH_SERVER.userinfoUrl;
 
 /**
  * Scopes the subscription token needs.
@@ -56,7 +56,7 @@ export const XAI_USERINFO_URL = XAI_AUTH_SERVER.userinfoUrl;
  * what admits the token to `api.x.ai`. The rest are the OIDC identity scopes the
  * userinfo label is read from.
  */
-export const XAI_SCOPE = [
+const XAI_SCOPE = [
   "openid",
   "profile",
   "email",

package/src/providers/integrations/zcode/oauth.ts

@@ -78,7 +78,7 @@ function unwrapEnvelope(body: unknown, operation: string): unknown {
       // codebase is 401. A 400 told the client to fix its body when the real
       // action is to fix the credential — and HTTP itself reserves 401 for
       // exactly this, so a standard client reads the class from the status.
-      throw new GatewayError("authentication_failed", 401, `Z.AI ${message}`, { providerId: "zcode" });
+      throw new GatewayError("authentication_failed", 401, `Z.AI ${message} (request {requestId}). Wrong key, right door — check the credential 🔑`, { providerId: "zcode" });
     }
   }
   return root.data ?? body;