cartethyia 2.7.0 → 2.7.1

package/src/providers/integrations/shared/install-id.ts

@@ -25,6 +25,7 @@ import { mkdir, open, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { log } from "../../../observability/logger";
+import { resolveInstallIdDir } from "../../../config/providers";
 
 /** Overrides the directory the install ids are persisted in. */
 const INSTALL_ID_DIR_ENV = "CARTETHYIA_INSTALL_ID_DIR";
@@ -40,7 +41,7 @@ const INSTALL_ID_DIR_ENV = "CARTETHYIA_INSTALL_ID_DIR";
  */
 function installIdDirectories(): readonly string[] {
   const candidates: string[] = [];
-  const configured = process.env[INSTALL_ID_DIR_ENV]?.trim();
+  const configured = resolveInstallIdDir()?.trim();
   if (configured && configured.length > 0) candidates.push(configured);
   const home = (process.env["HOME"] ?? process.env["USERPROFILE"])?.trim();
   if (home && home.length > 0) candidates.push(join(home, ".cartethyia"));

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

@@ -0,0 +1,110 @@
+// Trae session-cache estimation.
+//
+// Trae's agent surface does not report prompt-cache hits: the upstream metadata
+// carries `prompt_cache_pool_record: null` and every cache counter
+// (`cache_read_input_tokens`, `cached_tokens`) stays 0 even for byte-identical
+// prefixes. The underlying models do cache those prefixes, so for the same
+// 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.
+
+import { createHash } from "node:crypto";
+import type { CanonicalMessage, UsageRecord } from "../../../protocol/canonical-model";
+
+/** 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>();
+
+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;
+}
+
+/** Drops all tracked sessions. Test-only. */
+export function resetTraeSessionCacheForTesting(): void {
+  sessions.clear();
+}

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

@@ -505,9 +505,15 @@ export class TraeOAuthClient extends OAuthClient {
   override async refresh(
     refreshToken: string,
     signal?: AbortSignal,
-    context?: { readonly account_id?: string },
+    context?: { readonly account_id?: string; readonly auth_state?: Readonly<Record<string, unknown>> },
   ): Promise<OAuthTokenRefreshResult> {
-    return this.refreshWithUser(refreshToken, context?.account_id ?? "", signal);
+    // The exchange is addressed per Trae account, not per gateway account row:
+    // `UserID` must be the upstream user id. The login flow stores it in
+    // `auth_state.userId`, and re-imports carry it the same way — preferring it
+    // over `account_id` keeps refresh working for accounts whose row id is not
+    // the upstream user id (any account created before the id was persisted).
+    const upstreamUserId = firstString(context?.auth_state ?? {}, ["userId", "user_id", "uid"]);
+    return this.refreshWithUser(refreshToken, upstreamUserId ?? context?.account_id ?? "", signal);
   }
 
   async #exchange(
@@ -577,12 +583,15 @@ function parsedResult(
   refresh: string,
   isStatic: boolean,
 ): OAuthExchangeResult {
+  const state: Record<string, unknown> = {};
+  if (isStatic) state["staticToken"] = true;
+  if (parsed.userId !== undefined) state["userId"] = parsed.userId;
   return {
     access,
     refresh,
     expiresAt:
       parsed.expiresAtMs === undefined ? new Date(Date.now() + 3600_000) : new Date(parsed.expiresAtMs),
-    ...(isStatic ? { auth_state: { staticToken: true } } : {}),
+    ...(Object.keys(state).length === 0 ? {} : { auth_state: state }),
     ...(parsed.email === undefined ? {} : { accountLabel: parsed.email }),
   };
 }
@@ -619,7 +628,12 @@ function parseExport(credential: string): TraeExport | undefined {
   const refresh = firstString(parsed, ["refreshToken", "refresh_token", "refresh"]);
   const expiresAtMs = firstNumber(parsed, ["expiredAt", "expiresAt", "TokenExpireAt", "tokenExpireAt"]);
   const email = firstString(parsed, ["email", "userEmail", "accountLabel"]);
-  const userId = firstString(parsed, ["userId", "user_id", "uid", "UserID"]);
+  // The exporter nests the user id under `authState`; a hand-built export may
+  // carry it at the top level instead.
+  const authState = firstRecord(parsed, ["authState", "auth_state"]);
+  const userId =
+    firstString(authState ?? {}, ["userId", "user_id", "uid", "UserID"]) ??
+    firstString(parsed, ["userId", "user_id", "uid", "UserID"]);
   return {
     access,
     ...(refresh === undefined ? {} : { refresh }),
@@ -629,6 +643,17 @@ function parseExport(credential: string): TraeExport | undefined {
   };
 }
 
+/** First object value present under any of `keys`, or undefined. */
+function firstRecord(record: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+  }
+  return undefined;
+}
+
 function firstNumber(record: Record<string, unknown>, keys: readonly string[]): number | undefined {
   for (const key of keys) {
     const value = record[key];

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

@@ -160,6 +160,7 @@ export function buildTraeChatBody(
   modelId: string,
   request: CanonicalRequest,
   realm: TraeRealm,
+  sessionId?: string,
 ): TraeChatBody {
   if (modelId.length === 0) throw new Error("trae model name is required");
 
@@ -235,7 +236,7 @@ export function buildTraeChatBody(
     stream: request.stream,
     region: config.region,
     ai_region: config.region,
-    ...(request.session_id ? { session_id: request.session_id } : {}),
+    ...(request.session_id ?? sessionId ? { session_id: request.session_id ?? sessionId } : {}),
   };
   /**
    * Tool declarations, with `parameters` serialized to a string.

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

@@ -5,7 +5,8 @@
 // `Authorization: Cloud-IDE-JWT <token>` per the Trae 1.107.1 bundle.
 
 import { GatewayError } from "../../../protocol/gateway-error";
-import type { CanonicalEvent, CanonicalRequest, CanonicalStopReason } from "../../../protocol/canonical-model";
+import type { CanonicalEvent, CanonicalMessage, CanonicalRequest, CanonicalStopReason } from "../../../protocol/canonical-model";
+import type { UsageRecord } from "../../../protocol/canonical-model";
 import { usageFromProvider } from "../../provider-usage";
 import {
   readCredentialSecret,
@@ -16,6 +17,8 @@ import {
 } from "../../provider-contracts";
 import { mapUpstreamHttpError } from "../../../transport/failure-policy";
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
+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 {
@@ -86,6 +89,53 @@ function extractToken(secret: string): string | undefined {
   return trimmed.length > 0 ? trimmed : 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`:
+ * - `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.
+ * - `4008` / "exceeded the quota" — free-tier quota exhausted. That is a
+ *   `quota_exceeded` 429, not a platform fault.
+ * - Everything else is a platform fault (`platform_unavailable`).
+ */
+function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
+  const code =
+    typeof codeRaw === "number" || typeof codeRaw === "string" ? String(codeRaw) : undefined;
+  const message =
+    typeof messageRaw === "string" && messageRaw.trim().length > 0
+      ? messageRaw.trim()
+      : code !== undefined
+        ? `Trae stream error (upstream code ${code})`
+        : "Trae stream error";
+
+  if (code === "1001") {
+    throw new GatewayError(
+      "authentication_failed",
+      401,
+      `Trae could not authenticate the account (upstream code 1001): ${message}`,
+      { providerCode: "1001", providerStatus: 1001, credentialEvidence: true },
+      "upstream",
+    );
+  }
+
+  const lower = message.toLowerCase();
+  if (code === "4008" || lower.includes("exceeded the quota") || lower.includes("quota")) {
+    throw new GatewayError(
+      "quota_exceeded",
+      429,
+      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message}`,
+      { providerCode: code ?? "4008", providerStatus: code === "4008" ? 4008 : 429 },
+      "upstream",
+    );
+  }
+
+  throw new GatewayError("platform_unavailable", 502, message, {}, "upstream");
+}
+
 class TraeAdapter implements ProviderAdapter {
   readonly provider_id: ProviderId;
   private readonly realm: TraeRealm;
@@ -115,7 +165,21 @@ class TraeAdapter implements ProviderAdapter {
       (context.outbound_fetch as unknown as typeof fetch | undefined) ?? this.fetchFn;
 
     const auth = traeAuth(secret, context.credential.account_id);
-    const body = buildTraeChatBody(modelId, request, this.realm);
+    /**
+     * Trae keeps upstream prompt-cache state keyed by the request's
+     * `session_id`. The canonical request rarely carries one (surfaces do not
+     * populate it), so without this the body always omitted `session_id` and
+     * upstream treated every turn as a fresh context — `cached_tokens: 0`
+     * even for byte-identical prefixes. Resolve the same session/cache key the
+     * other adapters use (caller key → inbound session headers → opening-turn
+     * hash) and thread it through.
+     */
+    const sessionId = request.session_id ?? resolvePromptCacheKey(request, context);
+    const body = buildTraeChatBody(modelId, request, this.realm, sessionId);
+    // 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.
+    const cacheSessionKey = sessionId === undefined ? undefined : `${modelId}:${sessionId}`;
     /**
      * The endpoint follows the model, not the provider.
      *
@@ -159,6 +223,8 @@ class TraeAdapter implements ProviderAdapter {
         response.body as ReadableStream<Uint8Array>,
         lifecycle.signal,
         request.model,
+        cacheSessionKey,
+        request.messages,
       );
     } catch (err: unknown) {
       const abortError = abortGatewayError(lifecycle, err, context.abort_signal);
@@ -173,6 +239,8 @@ class TraeAdapter implements ProviderAdapter {
     body: ReadableStream<Uint8Array>,
     _signal: AbortSignal,
     requestModel: string,
+    sessionId?: string,
+    messages?: readonly CanonicalMessage[],
   ): AsyncIterable<CanonicalEvent> {
     let seq = 1;
     yield { type: "response_start", sequence_number: seq++, model: requestModel } as CanonicalEvent;
@@ -202,15 +270,21 @@ class TraeAdapter implements ProviderAdapter {
       }
       if (frame.event === "error") {
         const data = frame.data as { message?: unknown; code?: unknown };
-        const message = typeof data.message === "string" && data.message.length > 0
-          ? data.message
-          : typeof data.code === "number" || typeof data.code === "string"
-            ? `Trae stream error (upstream code ${data.code})`
-            : "Trae stream error";
-        throw new GatewayError("platform_unavailable", 502, message, {}, "upstream");
+        throwTraeUpstreamError(data.code, data.message);
       }
       if (typeof frame.data !== "object" || frame.data === null) continue;
       const record = frame.data as Record<string, unknown>;
+      // The upstream can answer with an error object in the frame body rather
+      // than a named `error` event — e.g. HTTP 200 carrying `{"code":1001,
+      // "message":"…"}` (sometimes nested under an `error` key). Detect both
+      // spellings so a rejected turn surfaces as the real error instead of an
+      // empty stream that ends with a normal `stop`.
+      if (record["code"] !== undefined || (typeof record["error"] === "object" && record["error"] !== null)) {
+        const nested = record["error"] as Record<string, unknown> | undefined;
+        const code = record["code"] ?? nested?.["code"];
+        const message = record["message"] ?? nested?.["message"];
+        throwTraeUpstreamError(code, message);
+      }
       /**
        * Two frame layouts reach here and both are live.
        *
@@ -278,16 +352,25 @@ class TraeAdapter implements ProviderAdapter {
       }
     }
 
-    if (usage !== undefined) {
-      yield* this.#usageEvent(usage, seq++);
+    // Assess the raw usage exactly once per request, then reuse the result for
+    // both the `usage` event and the terminal. Assessing twice would let the
+    // terminal see the `usage` event's own history entry and misreport a cache
+    // hit on the very first request.
+    const assessed = usage === undefined ? undefined : this.#assessUsage(usage, sessionId, messages);
+    if (assessed !== undefined) {
+      yield { type: "usage", sequence_number: seq++, usage: assessed } as unknown as CanonicalEvent;
     }
     // The canonical terminal is `terminal`; a stream that ends without one is
-    // read as "the upstream never reported a result".
+    // read as "the upstream never reported a result". The assessed usage is
+    // carried on the terminal itself (matching the other adapters) so the
+    // non-streaming path records the real token counts instead of falling back
+    // to the request estimate.
     yield {
       type: "terminal",
       sequence_number: seq,
       state: "complete",
       stop_reason: stopReason,
+      ...(assessed === undefined ? {} : { usage: assessed }),
     } as unknown as CanonicalEvent;
   }
 
@@ -348,20 +431,20 @@ class TraeAdapter implements ProviderAdapter {
     }
   }
 
-  /**
-   * Emits the terminal usage event, or none at all.
-   *
-   * Trae reports usage with the OpenAI spelling (`prompt_tokens` /
-   * `completion_tokens`). `usageFromProvider` normalizes both spellings and
-   * returns `undefined` when nothing was actually reported, and an absent
-   * usage event is correct in that case — emitting zeros would record a
-   * request that cost nothing.
-   */
-  async *#usageEvent(usage: Record<string, unknown>, seq: number): AsyncIterable<CanonicalEvent> {
+  /** Normalizes + cache-assesses one raw upstream usage frame, if any. */
+  #assessUsage(
+    usage: Record<string, unknown> | undefined,
+    sessionId?: string,
+    messages?: readonly CanonicalMessage[],
+  ): UsageRecord | undefined {
+    if (usage === undefined) return undefined;
     const record = usageFromProvider(usage);
-    if (record === undefined) return;
-    yield { type: "usage", sequence_number: seq, usage: record } as unknown as CanonicalEvent;
+    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);
   }
+
 }
 
 export function createTraeAdapter(options: TraeAdapterOptions = {}): ProviderAdapter {