cartethyia 2.7.9 → 2.8.0

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

@@ -40,10 +40,9 @@ 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,
+  traeCoreForAccount,
+  traePayHostForAccount,
   type TraeRealm,
 } from "./trae-realm";
 
@@ -326,27 +325,6 @@ function logTraeQuotaMiss(errors: readonly string[]): void {
  * whose pay host is unreachable still has a readable meter, and reporting
  * "no quota" for it would park an account that can still serve.
  */
-/**
- * The core host for this account.
- *
- * A provisioned region overrides the realm default: an `sg` account sent to the
- * US core is answered 401 code 1001, which looks exactly like a dead token.
- */
-function coreHost(region: string, config: (typeof TRAE_REALMS)[TraeRealm]): string {
-  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,
@@ -412,13 +390,13 @@ export async function fetchTraeQuota(
    * realm is tried: one of them accepts, and that is the answer.
    */
   const tryRealms = async (
-    path: (config: (typeof TRAE_REALMS)[TraeRealm]) => string,
+    path: (realm: TraeRealm) => string,
     surface: string,
     parse: (payload: unknown) => { readonly windows: readonly ProviderQuotaWindow[]; readonly plan: string | null },
   ): Promise<{ readonly windows: readonly ProviderQuotaWindow[]; readonly plan: string | null } | null> => {
     for (const candidate of realm === "cn" ? (["cn", "intl"] as const) : (["intl", "cn"] as const)) {
       try {
-        const payload = await call(candidate, path(TRAE_REALMS[candidate]), surface);
+        const payload = await call(candidate, path(candidate), surface);
         return parse(payload);
       } catch (error) {
         errors.push(`${candidate} ${surface}: ${cleanError(error)}`);
@@ -427,11 +405,11 @@ export async function fetchTraeQuota(
     return null;
   };
 
-  const session = await tryRealms((config) => coreHost(region, config) + TRAE_SESSION_USAGE_PATH, "session usage", parseSessionUsage);
+  const session = await tryRealms((r) => traeCoreForAccount(r, region) + TRAE_SESSION_USAGE_PATH, "session usage", parseSessionUsage);
   // 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 entitlement = await tryRealms((r) => traePayHostForAccount(r, region) + entPath, "entitlement", parseEntitlement);
 
   const windows = [...(session?.windows ?? []), ...(entitlement?.windows ?? [])];
   if (!session && !entitlement) {

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

@@ -12,6 +12,9 @@
 /** One Trae deployment. */
 export type TraeRealm = "intl" | "cn";
 
+/** Provider ids served by the Trae integration (intl + CN). */
+export const TRAE_PROVIDER_IDS: ReadonlySet<string> = new Set(["trae", "traecn"]);
+
 /** Per-realm upstream addresses, client identity, and auth scheme. */
 export interface TraeRealmConfig {
   /** Data-plane host: chat + model list (`/api/ide/v1/*`). */
@@ -245,3 +248,38 @@ export function traeAccountCandidates(realm: TraeRealm): readonly string[] {
   const config = TRAE_REALMS[realm];
   return [config.account, ...config.accountFallbacks];
 }
+
+/**
+ * The core host for this account.
+ *
+ * A provisioned region overrides the realm default: an `sg` account sent to the
+ * US core is answered 401 code 1001 (which looks exactly like a dead token), so
+ * the region lookup must win when it is known. Falling back to the realm keeps
+ * older accounts (stored before the region was captured) working exactly as
+ * before.
+ */
+export function traeCoreForAccount(
+  realm: TraeRealm,
+  region: string,
+): string {
+  const regional = TRAE_REGION_CORE_HOSTS[region];
+  if (regional !== undefined) return regional;
+  return traeCoreCandidates(realm)[0] ?? "";
+}
+
+/**
+ * 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). Falls back to the
+ * realm default host when no region is provisioned.
+ */
+export function traePayHostForAccount(
+  realm: TraeRealm,
+  region: string,
+): string {
+  const regional = TRAE_REGION_PAY_HOSTS[region];
+  if (regional !== undefined) return regional;
+  return TRAE_REALMS[realm].pay;
+}

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

@@ -31,7 +31,7 @@ import {
   TRAE_AGENT_ENDPOINT,
   TRAE_CHAT_ENDPOINT,
 } from "./trae-protocol";
-import { TRAE_REGION_CORE_HOSTS, traeCoreCandidates, TRAE_MODEL_LIST_PATH, TRAE_AGENT_FUNCTION, type TraeRealm } from "./trae-realm";
+import { traeCoreForAccount, TRAE_MODEL_LIST_PATH, TRAE_AGENT_FUNCTION, type TraeRealm } from "./trae-realm";
 
 export interface TraeAdapterOptions {
   readonly providerId?: string;
@@ -269,7 +269,11 @@ class TraeAdapter implements ProviderAdapter {
       trafficType: agentSurface ? "agent" : "chat",
     });
 
-    const primary = traeCoreForAccount(this.realm, context.credential.auth_state);
+    const region =
+      typeof context.credential.auth_state?.["region"] === "string"
+        ? context.credential.auth_state["region"].toLowerCase()
+        : "";
+    const primary = traeCoreForAccount(this.realm, region);
     const path = agentSurface ? TRAE_AGENT_ENDPOINT : TRAE_CHAT_ENDPOINT;
     const url =
       candidate.endpoint_path && candidate.endpoint_path.startsWith("http")
@@ -572,10 +576,7 @@ export async function discoverTraeModels(input: {
     uid: input.uid,
     appVersion: getTraeVersion(),
   });
-  const core = traeCoreForAccount(
-    input.realm,
-    input.region === undefined ? undefined : { region: input.region },
-  );
+  const core = traeCoreForAccount(input.realm, (input.region ?? "").toLowerCase());
 
   if (input.realm === "intl") {
     // The agent picker: the only surface that lists the intl roster's configs.
@@ -649,21 +650,3 @@ export async function discoverTraeModels(input: {
 }
 
 export { TRAE_CN_MODELS, TRAE_INTL_MODELS };
-
-/**
- * Core host for one account.
- *
- * An intl account is provisioned into a region and its token only authenticates
- * against that region's host, so the account's own `region` wins over the
- * realm default. Falling back to the realm keeps older accounts (stored before
- * the region was captured) working exactly as before.
- */
-function traeCoreForAccount(
-  realm: TraeRealm,
-  authState: Readonly<Record<string, unknown>> | undefined,
-): string {
-  const region = typeof authState?.["region"] === "string" ? authState["region"].toLowerCase() : "";
-  const regional = TRAE_REGION_CORE_HOSTS[region];
-  if (regional !== undefined) return regional;
-  return traeCoreCandidates(realm)[0] ?? "";
-}

package/src/providers/integrations/zcode-start-plan/provider.ts

@@ -1,16 +1,41 @@
 /**
- * ZCode Start Plan uses the client's three-block Messages prompt fingerprint.
- * Caller instructions remain inside the third block; a fourth block is refused.
- * The bundled prompt/version pair is kept together to preserve upstream bytes.
- * Reference provenance and bounded live acceptance evidence: provider guide.
+ * ZCode Start Plan provider integration.
+ *
+ * The plan lane is an Anthropic Messages endpoint that only accepts the
+ * dressed ZCode client request (see `dress`): the gateway content-inspects the
+ * `system` field and refuses a request without the exact three-block identity
+ * fingerprint with `405 {code:3012}`. The credential is a ZCode login JWT —
+ * pasted, or minted by the sign-in flow (`oauth.ts`).
+ *
+ * Wire facts mirrored from the donor gateway (verified live 2026-10-30):
+ * - `anthropic-beta: mid-conversation-system-2026-04-07` rides every request.
+ * - `metadata.user_id` is a JSON string `{"device_id","account_uuid","session_id"}`
+ *   the gateway reads for attribution; it lives in the body, not a header.
+ * - The LLM identity face carries per-request correlation ids: `x-session-id`,
+ *   `x-request-id`, `x-zcode-trace-id`, `x-query-id`, `x-zcode-query-source`.
+ * - Errors inside an HTTP 200 response come as a `{code,msg,logid}` envelope
+ *   (`1113` grant spent, `3009` model concurrency, `3012` identity gate) and
+ *   are mapped through the shared `classifyUpstreamError`.
  */
 import { randomUUID } from "node:crypto";
 import { release as osRelease } from "node:os";
 
-import type { ApiKeyProviderSpec } from "../../configured-provider";
 import { defineModel } from "../../provider-model-definition";
 import type { ModelDefinition } from "../../provider-model-definition";
 import { getOrCreateInstallId } from "../shared/install-id";
+import { resolveInboundSessionId } from "../../operations/session-resolution";
+import { assertCredentialKind, assertWireFamily } from "../../provider-contracts";
+import type { ProviderAdapter, ProviderDispatchContext, ProviderDispatchTarget } from "../../provider-contracts";
+import { GatewayError } from "../../../protocol/gateway-error";
+import { applyParamQuirks } from "../../../protocol/translation/quirks";
+import { buildClaudeMessagesRequest, filterClaudeCustomHeaders } from "../shared/claude-messages";
+import { mapClaudeHttpError } from "../../../protocol/messages-errors";
+import { isRecord } from "../../../protocol/codecs";
+import { classifyUpstreamError, upstreamErrorIdentifier, upstreamMessageAsIs } from "../../../transport/failure-policy";
+import { parseClaudeSseStream, claudeResponseToEvents } from "../../../protocol/response/messages";
+import { createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
+import type { CanonicalEvent, CanonicalRequest } from "../../../protocol/canonical-model";
+import { parseJwt } from "../../authentication/jwt-validator";
 import prompt from "./zcode_prompt.json";
 
 const CLI_PREFIX: string = prompt.cliPrefix;
@@ -21,8 +46,18 @@ export const ZCODE_START_PLAN_PROVIDER_ID = "zcode-start" as const;
 export const ZCODE_START_PLAN_ENDPOINT_PATH = "/v1/messages" as const;
 export const ZCODE_START_PLAN_BASE_URL = "https://zcode.z.ai/api/v1/zcode-plan/anthropic" as const;
 
-/** Client version the plan endpoint expects in the identity headers. */
+/**
+ * Client version the plan endpoint expects in the identity headers. This is
+ * kept in step with the bundled prompt asset (`zcode_prompt.json`, 3.14.5):
+ * the gateway content-inspects the system blocks, and a version/prompt split
+ * (e.g. 3.16.3 headers over 3.14.5 blocks) risks the 3012 identity gate. Bump
+ * both together only after re-capturing the live blocks and re-verifying.
+ */
 const APP_VERSION = "3.14.5";
+/** Anthropic beta the desktop client sends on the plan lane (captured live). */
+const ANTHROPIC_BETA = "mid-conversation-system-2026-04-07";
+/** The plan gateway enforces a serial per-account in-flight limit; 8192 is the desktop default. */
+const DEFAULT_MAX_TOKENS = 8192;
 
 type Loose = Record<string, unknown>;
 type TextBlock = { type: "text"; text: string; cache_control?: { type: "ephemeral" } };
@@ -40,26 +75,47 @@ function environmentBlock(provider: string, model: string): string {
     .replace("{model}", model);
 }
 
+/** The account uuid carried by the plan JWT, for metadata attribution. */
+function jwtUserId(credential: { secret?: Uint8Array | undefined } | undefined): string {
+  if (!credential?.secret || credential.secret.length === 0) return "";
+  try {
+    const token = new TextDecoder().decode(credential.secret);
+    const parsed = parseJwt(token);
+    const userId = parsed?.payload?.["user_id"];
+    return typeof userId === "string" ? userId : "";
+  } catch {
+    return "";
+  }
+}
+
 /** Identity headers every dispatch carries; the adapter adds Authorization. */
-async function identityHeaders(): Promise<Record<string, string>> {
+async function identityHeaders(context: ProviderDispatchContext): Promise<Record<string, string>> {
+  const sessionId = resolveInboundSessionId(context) ?? `session_${randomUUID().replace(/-/g, "").slice(0, 32)}`;
+  const requestId = randomUUID();
+  const traceId = randomUUID();
+  const queryId = `01a1${requestId.slice(4).replace(/-/g, "").slice(0, 28)}`;
+  const deviceMid = await getOrCreateInstallId("zcode-start-plan");
   return {
     "user-agent": `ZCode/${APP_VERSION} ai-sdk/anthropic/3.0.81`,
     "http-referer": "https://zcode.z.ai",
-    "x-title": "Z Code@cli",
+    "x-title": "Z Code@electron",
     "x-zcode-app-version": APP_VERSION,
     "x-zcode-agent": "glm",
     "x-release-channel": "production",
     "x-client-language": "en-US",
     "x-client-timezone": "Asia/Jakarta",
-    "x-platform": "linux",
+    "x-platform": "linux-x64",
     "x-os-category": "linux",
     "x-os-version": osRelease(),
-    "x-request-id": randomUUID(),
+    "x-request-id": requestId,
+    "x-query-id": queryId,
+    "x-zcode-trace-id": traceId,
     "x-zcode-session-type": "main",
-    "x-zcode-trace-id": randomUUID(),
-    // Keep the persisted install-id filename stable across the provider-ID rename.
-    "x-device-mid": await getOrCreateInstallId("zcode-start-plan"),
+    "x-zcode-query-source": "main_turn",
+    "x-session-id": sessionId,
+    "x-device-mid": deviceMid,
     "anthropic-version": "2023-06-01",
+    "anthropic-beta": ANTHROPIC_BETA,
   };
 }
 
@@ -119,13 +175,160 @@ export const ZCODE_START_PLAN_MODELS: readonly ModelDefinition[] = [
   }),
 ];
 
-/** Start Plan adapter spec: direct upstream, prompt fingerprint, no sidecar. */
-export const ZCODE_START_PLAN_SPEC: ApiKeyProviderSpec = {
-  provider_id: ZCODE_START_PLAN_PROVIDER_ID,
-  base_url: ZCODE_START_PLAN_BASE_URL,
-  endpoint_paths_by_wire_family: { messages: ZCODE_START_PLAN_ENDPOINT_PATH },
-  buildExtraHeaders: () => identityHeaders(),
-  prePayload: (payload) => {
-    dress(payload as Loose);
-  },
-};
+/** True when the body is the ZCode `{code,msg,logid}` business-error envelope. */
+function isZcodeEnvelopeError(body: Record<string, unknown>): boolean {
+  if (body["success"] === false) return true;
+  const code = body["code"];
+  return code !== undefined && ![0, 200, "0", "200"].includes(code as string | number);
+}
+
+/**
+ * Plan-lane Messages adapter. Unlike the plain Anthropic adapter it must (a)
+ * dress the three-block system fingerprint, (b) inject `metadata.user_id`, and
+ * (c) treat a `{code,msg}` envelope inside an HTTP 200 as a refusal — the
+ * gateway reports business errors on success statuses.
+ */
+export class ZcodeStartPlanAdapter implements ProviderAdapter {
+  readonly provider_id = ZCODE_START_PLAN_PROVIDER_ID;
+  private readonly fetchFn: typeof fetch;
+  private readonly baseUrl: string;
+
+  constructor(fetchImpl?: typeof fetch, baseUrl?: string) {
+    this.fetchFn = fetchImpl ?? globalThis.fetch;
+    this.baseUrl = (baseUrl ?? ZCODE_START_PLAN_BASE_URL).replace(/\/+$/, "");
+  }
+
+  async *dispatch(
+    request: CanonicalRequest,
+    candidate: ProviderDispatchTarget,
+    context: ProviderDispatchContext,
+  ): AsyncIterable<CanonicalEvent> {
+    if (candidate.wire_family !== "messages") {
+      assertWireFamily(candidate, "messages", "zcode-start messages leg");
+    }
+    if (context.credential.credential_kind !== "api_key") {
+      assertCredentialKind(context.credential, "api_key", "zcode-start");
+    }
+    if (context.credential.secret === undefined || context.credential.secret.length === 0) {
+      throw new GatewayError(
+        "invalid_request",
+        400,
+        "zcode-start: plan JWT is missing a secret value (request {requestId}). Wrong key, right door — check the credential 🔑",
+      );
+    }
+    const planJwt = new TextDecoder().decode(context.credential.secret);
+    const sessionId = resolveInboundSessionId(context, request) ?? `session_${randomUUID().replace(/-/g, "").slice(0, 32)}`;
+    const deviceMid = await getOrCreateInstallId("zcode-start-plan");
+    const accountUuid = jwtUserId(context.credential);
+    const customHeaders = filterClaudeCustomHeaders({
+      ...context.credential.custom_headers,
+    });
+    const outbound = buildClaudeMessagesRequest({
+      request: applyParamQuirks(request, candidate.provider_id),
+      authHeader: "bearer",
+      credential: { secret: planJwt, customHeaders },
+      baseUrl: this.baseUrl,
+      endpointPath: candidate.endpoint_path,
+      mutatePayload: (payload) => {
+        dress(payload);
+        const metadata = (isRecord(payload["metadata"]) ? payload["metadata"] : {}) as Loose;
+        metadata["user_id"] = JSON.stringify({
+          device_id: deviceMid,
+          account_uuid: accountUuid,
+          session_id: sessionId,
+        });
+        payload.metadata = metadata;
+        if (payload["max_tokens"] == null) payload["max_tokens"] = DEFAULT_MAX_TOKENS;
+        return payload;
+      },
+    });
+    Object.assign(outbound.headers, await identityHeaders(context));
+
+    const outboundFetch = context.outbound_fetch ?? this.fetchFn;
+    const lifecycle = createUpstreamDeadlineLifecycle(context);
+    let response: Response;
+    try {
+      response = await outboundFetch(outbound.url, {
+        method: "POST",
+        headers: outbound.headers,
+        body: outbound.body,
+        signal: lifecycle.signal,
+      });
+    } catch (error: unknown) {
+      lifecycle.release();
+      if (error instanceof GatewayError) throw error;
+      throw new GatewayError(
+        "transport_unavailable",
+        502,
+        `zcode-start upstream fetch failed: ${(error as Error)?.message ?? String(error)}`,
+        {},
+        "network",
+      );
+    }
+    lifecycle.release();
+
+    if (!response.ok) {
+      const bodyText = await response.text().catch(() => "");
+      throw mapClaudeHttpError(response.status, bodyText, response.headers);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.toLowerCase().includes("text/event-stream") || request.stream) {
+      if (response.body === null) {
+        throw new GatewayError(
+          "platform_unavailable",
+          502,
+          "zcode-start returned no stream body (request {requestId}). The upstream came back empty-handed — retry 🌙",
+          {},
+          "upstream",
+        );
+      }
+      yield* parseClaudeSseStream(response.body, context.abort_signal, false);
+      return;
+    }
+    const bodyText = await response.text().catch(() => "");
+    let json: unknown;
+    try {
+      json = JSON.parse(bodyText) as unknown;
+    } catch {
+      const upstreamText = upstreamMessageAsIs(bodyText, "");
+      throw new GatewayError(
+        "platform_unavailable",
+        502,
+        upstreamText.message || "zcode-start response is not valid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙",
+        { raw: bodyText.slice(0, 4096) },
+        "upstream",
+      );
+    }
+    if (!isRecord(json)) {
+      throw new GatewayError(
+        "platform_unavailable",
+        502,
+        "zcode-start response must be an object (request {requestId}). The upstream came back empty-handed — retry 🌙",
+        {},
+        "upstream",
+      );
+    }
+    if (isZcodeEnvelopeError(json)) {
+      const identifier = upstreamErrorIdentifier(json);
+      const classification = classifyUpstreamError(undefined, identifier);
+      const upstreamText = upstreamMessageAsIs(json, "");
+      throw new GatewayError(
+        classification.code,
+        classification.status,
+        upstreamText.message || "zcode-start reported an upstream error",
+        {
+          providerId: this.provider_id,
+          ...(identifier === undefined ? {} : { providerCode: identifier }),
+          ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
+          raw: bodyText.slice(0, 4096),
+        },
+        classification.origin,
+      );
+    }
+    yield* claudeResponseToEvents(json, request, false);
+  }
+}
+
+export function createZcodeStartPlanAdapter(fetchImpl?: typeof fetch): ProviderAdapter {
+  return new ZcodeStartPlanAdapter(fetchImpl);
+}

package/src/providers/integrations/zcode-start-plan/quota.ts

@@ -1,9 +1,23 @@
+import { createHash } from "node:crypto";
 import { asCoercedNumber, asRecord, asTrimmedString } from "../../../shared/coerce";
 import type { FetchLike, ProviderQuotaResult, ProviderQuotaWindow } from "../../quota/quota-contracts";
 
 const BALANCE_URL = "https://zcode.z.ai/api/v1/zcode-plan/billing/balance?app_version=3.16.3";
-const DEVICE_MID = "9f1b0d4e-3c2a-4e7b-9f1d-6a2c8b5e0d31";
 const APP_VERSION = "3.16.3";
+const PLATFORM = "linux-x64";
+
+/**
+ * Stable per-account device mid. The gateway validates `X-Device-Mid` as a
+ * UUID (billing answers `3001 parameter error` without it) and attributes
+ * usage to it; a hardcoded shared UUID would lump every account into one
+ * billing identity. Derivation matches the gift-claim device id, so quota and
+ * claim present the same device per account.
+ */
+function deviceMid(accountId: string): string {
+  const hash = createHash("sha256").update(`zcode-device\0${accountId}`).digest("hex");
+  const variant = ((parseInt(hash[16] as string, 16) & 3) | 8).toString(16);
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-${variant}${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
 
 function instant(value: unknown): string | null {
   const seconds = asCoercedNumber(value);
@@ -57,16 +71,19 @@ function samePlan(bucket: Record<string, unknown>, plan: Record<string, unknown>
 export async function fetchZcodeStartPlanQuota(
   credential: string,
   fetcher: FetchLike,
+  context?: { accountId?: string },
 ): Promise<ProviderQuotaResult> {
   const source = "zcode-start";
   try {
+    const accountId = context?.accountId ?? credential.trim();
     const response = await fetcher(BALANCE_URL, {
       headers: {
         authorization: `Bearer ${credential}`,
         accept: "application/json",
-        "x-device-mid": DEVICE_MID,
+        "x-device-mid": deviceMid(accountId),
         "x-zcode-app-version": APP_VERSION,
         "x-client-language": "en-US",
+        "x-platform": PLATFORM,
       },
       signal: AbortSignal.timeout(15_000),
     });