cartethyia 2.4.6 → 2.5.0

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

@@ -0,0 +1,400 @@
+// Trae wire protocol: request body and SSE translation.
+//
+// Two upstream rules drive everything here:
+//
+// 1. The model key is `model_name`, not `model`. Sending `model` is silently
+//    ignored and upstream answers with its default model, so the caller gets a
+//    different model than it asked for with no error.
+// 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 {
+  TRAE_AGENT_CHAT_PATH,
+  TRAE_AGENT_FUNCTION,
+  TRAE_CHAT_PATH,
+  TRAE_MODEL_LIST_PATH,
+  TRAE_REALMS,
+  type TraeRealm,
+} from "./trae-realm";
+
+/** Upstream chat body. */
+export interface TraeChatBody {
+  readonly model_name: string;
+  readonly messages: readonly TraeMessage[];
+  readonly stream: boolean;
+  readonly region: string;
+  readonly ai_region: string;
+  readonly temperature?: number;
+  readonly top_p?: number;
+  readonly max_tokens?: number;
+  readonly stop?: readonly string[];
+  readonly presence_penalty?: number;
+  readonly frequency_penalty?: number;
+  readonly session_id?: string;
+  /** Tool declarations; `parameters` is a JSON string, not a schema object. */
+  readonly tools?: readonly TraeToolDeclaration[];
+}
+
+/** One declared tool, in the shape upstream binds. */
+export interface TraeToolDeclaration {
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: string;
+  };
+}
+
+export interface TraeMessage {
+  readonly role: "system" | "user" | "assistant" | "tool";
+  readonly content: readonly TraeContentPart[];
+  readonly tool_call_id?: string;
+  readonly tool_calls?: readonly TraeToolCall[];
+}
+
+export type TraeContentPart =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "image_url"; readonly image_url: { readonly url: string } };
+
+/**
+ * One tool call, in the shape upstream's protobuf expects.
+ *
+ * The nested key is `function_call`, not OpenAI's `function`, and `Name` is a
+ * **required** field on replay: an assistant turn sent back with
+ * `function: {name: ""}` is rejected before it reaches the model with
+ * `required field Name is not set`. Both spellings therefore have to carry the
+ * name, and the arguments stay a JSON string rather than an object.
+ */
+export interface TraeToolCall {
+  readonly id: string;
+  readonly type: "function";
+  readonly function_call: { readonly name: string; readonly arguments: string };
+}
+
+/**
+ * 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.
+ */
+const PASSTHROUGH_OPTIONS = ["temperature", "top_p", "max_tokens", "stop"] as const;
+
+function textOf(part: ContentPart): string {
+  return part.kind === "text" ? part.text : "";
+}
+
+/**
+ * Renders an image part as a URL upstream accepts.
+ *
+ * The canonical image payload is opaque (`payload`), because every surface
+ * spells an image differently: base64 with a media type, a bare URL, or a
+ * provider file id. Only the first two have an upstream representation, so a
+ * payload this adapter cannot recognize is dropped rather than sent as a
+ * malformed data URI.
+ */
+function dataUriOf(part: Extract<ContentPart, { kind: "image" }>): string | undefined {
+  const payload = part.payload;
+  if (typeof payload === "string") {
+    return /^https?:\/\//i.test(payload) ? payload : undefined;
+  }
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const record = payload as Record<string, unknown>;
+  const url = record["url"];
+  if (typeof url === "string" && url.length > 0) return url;
+  const data = record["data"];
+  const mediaType = record["media_type"] ?? record["mediaType"];
+  if (typeof data === "string" && typeof mediaType === "string") {
+    // `data` may already carry its own `data:` prefix from a previous hop.
+    return data.startsWith("data:") ? data : `data:${mediaType};base64,${data}`;
+  }
+  const b64 = record["b64_json"] ?? record["base64"];
+  if (typeof b64 === "string" && typeof mediaType === "string") {
+    return `data:${mediaType};base64,${b64}`;
+  }
+  return undefined;
+}
+
+/** Maps one canonical part onto the upstream part shape. */
+function toTraePart(part: ContentPart): TraeContentPart | undefined {
+  if (part.kind === "text") return { type: "text", text: part.text };
+  if (part.kind === "image") {
+    const url = dataUriOf(part);
+    return url === undefined ? undefined : { type: "image_url", image_url: { url } };
+  }
+  return undefined;
+}
+
+/** Serializes tool-call arguments, which arrive parsed rather than as text. */
+function toolArguments(args: unknown): string {
+  if (typeof args === "string") return args;
+  try {
+    return JSON.stringify(args ?? {});
+  } catch {
+    return "{}";
+  }
+}
+
+/** Flattens a tool result's content to the single string upstream takes. */
+function toolResultText(content: readonly ContentPart[] | string): string {
+  if (typeof content === "string") return content;
+  return content
+    .map((part) => (part.kind === "text" ? part.text : ""))
+    .filter((text) => text.length > 0)
+    .join("\n");
+}
+
+/**
+ * Builds the upstream chat body from a canonical request.
+ *
+ * System content is promoted to a leading `system` message: upstream has no
+ * separate system field, and dropping it (rather than promoting it) is what
+ * silently loses the caller's instructions.
+ */
+export function buildTraeChatBody(
+  modelId: string,
+  request: CanonicalRequest,
+  realm: TraeRealm,
+): TraeChatBody {
+  if (modelId.length === 0) throw new Error("trae model name is required");
+
+  const messages: TraeMessage[] = [];
+  const systemParts: string[] = [];
+  for (const part of request.system ?? []) {
+    const text = textOf(part);
+    if (text.length > 0) systemParts.push(text);
+  }
+  for (const part of request.instructions ?? []) {
+    const text = textOf(part);
+    if (text.length > 0) systemParts.push(text);
+  }
+  if (systemParts.length > 0) {
+    messages.push({ role: "system", content: [{ type: "text", text: systemParts.join("\n\n") }] });
+  }
+
+  for (const message of request.messages) {
+    // `system` was promoted into the leading turn above; appending it again
+    // would leave a second, late instruction turn. `developer` has no upstream
+    // equivalent and is folded into the same leading turn rather than dropped.
+    if (message.role === "system" || message.role === "developer") {
+      const text = message.content.map(textOf).filter((t) => t.length > 0).join("\n\n");
+      if (text.length > 0) systemParts.push(text);
+      continue;
+    }
+    const parts: TraeContentPart[] = [];
+    const toolCalls: TraeToolCall[] = [];
+    let toolResult: { callId: string; text: string } | undefined;
+    for (const part of message.content) {
+      if (part.kind === "toolCall") {
+        toolCalls.push({
+          id: part.call_id,
+          type: "function",
+          function_call: { name: part.name, arguments: toolArguments(part.arguments) },
+        });
+        continue;
+      }
+      if (part.kind === "toolResult") {
+        toolResult = { callId: part.call_id, text: toolResultText(part.content) };
+        continue;
+      }
+      const mapped = toTraePart(part);
+      if (mapped !== undefined) parts.push(mapped);
+    }
+
+    // A tool answer becomes its own `tool` turn, which is the only shape
+    // upstream accepts for it — leaving it inside the assistant turn is
+    // rejected as a broken tool sequence.
+    if (toolResult !== undefined) {
+      messages.push({
+        role: "tool",
+        content: [{ type: "text", text: toolResult.text }],
+        tool_call_id: toolResult.callId,
+      });
+      continue;
+    }
+    // Empty turns are skipped: upstream rejects them, and emitting
+    // `content: ""` turns leaves a ghost turn in the conversation.
+    if (parts.length === 0 && toolCalls.length === 0) continue;
+    messages.push({
+      role: message.role === "assistant" ? "assistant" : "user",
+      content: parts.length > 0 ? parts : [{ type: "text", text: "" }],
+      ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+    });
+  }
+
+  const config = TRAE_REALMS[realm];
+  const controls = request.generation_controls;
+  const body: Record<string, unknown> = {
+    model_name: modelId,
+    messages,
+    stream: request.stream,
+    region: config.region,
+    ai_region: config.region,
+    ...(request.session_id ? { session_id: request.session_id } : {}),
+  };
+  /**
+   * Tool declarations, with `parameters` serialized to a string.
+   *
+   * Upstream's `FunctionDefinition` types that field as a Go `string`, so an
+   * object is rejected outright: `cannot unmarshal object into Go struct field
+   * FunctionDefinition.tools.function.parameters of type string`. Sending the
+   * schema as a JSON string is the only shape it binds.
+   */
+  const tools = request.tools;
+  if (tools !== undefined && tools.length > 0) {
+    body["tools"] = tools.map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        ...(tool.description ? { description: tool.description } : {}),
+        parameters: toolArguments(tool.jsonSchema),
+      },
+    }));
+  }
+  const options: Record<string, unknown> = {
+    temperature: controls.temperature,
+    top_p: controls.top_p,
+    max_tokens: controls.max_tokens,
+    stop: controls.stop,
+
+  };
+  for (const key of PASSTHROUGH_OPTIONS) {
+    const value = options[key];
+    if (value !== undefined && value !== null) body[key] = value;
+  }
+  return body as unknown as TraeChatBody;
+}
+
+/** 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.
+ *
+ * Two changes, both required and neither optional:
+ *
+ * 1. The model key moves from `model_name` to `config_name`, and
+ *    `config_source: 1` is added. Without `config_source` the server resolves
+ *    the right upstream model and then streams nothing at all, which presents
+ *    as a broken model rather than a missing field.
+ * 2. `function` selects the roster. Without it the call fails before model
+ *    resolution with `[LLMUtilsChat.resolveByUsage] function is empty`.
+ *
+ * Everything else — messages, generation controls, session id — is carried
+ * over unchanged; the agent surface reads the same message shape.
+ */
+export function toTraeAgentBody(body: TraeChatBody): Record<string, unknown> {
+  const draft = body as unknown as Record<string, unknown>;
+  const rewritten: Record<string, unknown> = { function: TRAE_AGENT_FUNCTION };
+  for (const [key, value] of Object.entries(draft)) {
+    if (key === "model_name") continue;
+    rewritten[key] = value;
+  }
+  rewritten["config_name"] = draft["model_name"];
+  rewritten["config_source"] = 1;
+  return rewritten;
+}
+
+/**
+ * True when a dispatch target belongs to the agent surface.
+ *
+ * Compared by suffix so an absolute URL target still resolves: a catalog row
+ * may carry a full `https://…/api/agent/v3/llm_utils_chat` rather than a bare
+ * path, and prefixing host logic elsewhere must not flip the surface.
+ */
+export function isTraeAgentEndpoint(endpointPath: string | null | undefined): boolean {
+  if (typeof endpointPath !== "string" || endpointPath.length === 0) return true;
+  return endpointPath.endsWith(TRAE_AGENT_CHAT_PATH);
+}
+
+/** One parsed SSE frame. */
+export interface TraeSseFrame {
+  readonly event: string;
+  readonly data: unknown;
+}
+
+/**
+ * Parses an SSE byte stream into frames.
+ *
+ * The done sentinel is a `data:` payload equal to `[DONE]`, which upstream
+ * sends instead of a named `done` event. Comment lines (leading `:`) are
+ * heartbeats and are skipped rather than treated as data.
+ */
+export async function* parseTraeSse(
+  body: ReadableStream<Uint8Array>,
+): AsyncIterable<TraeSseFrame> {
+  const decoder = new TextDecoder();
+  const reader = body.getReader();
+  let buffer = "";
+  let event = "message";
+  let data: string[] = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).replace(/\r$/, "");
+        buffer = buffer.slice(newline + 1);
+        if (line === "") {
+          if (data.length > 0) {
+            const payload = data.join("\n");
+            data = [];
+            if (payload.trim() === "[DONE]") {
+              yield { event: "done", data: { finish_reason: "stop" } };
+            } else {
+              let parsed: unknown = payload;
+              try {
+                parsed = JSON.parse(payload);
+              } catch {
+                // Upstream occasionally emits non-JSON keepalives; a frame we
+                // cannot parse is dropped rather than failing the stream.
+                parsed = payload;
+              }
+              yield { event, data: parsed };
+            }
+            event = "message";
+          }
+        } else if (line.startsWith(":")) {
+          continue;
+        } else {
+          const separator = line.indexOf(":");
+          const field = separator < 0 ? line : line.slice(0, separator);
+          let value = separator < 0 ? "" : line.slice(separator + 1);
+          if (value.startsWith(" ")) value = value.slice(1);
+          if (field === "event") event = value;
+          else if (field === "data") data.push(value);
+        }
+        newline = buffer.indexOf("\n");
+      }
+    }
+    if (data.length > 0) {
+      const payload = data.join("\n");
+      if (payload.trim() === "[DONE]") {
+        yield { event: "done", data: { finish_reason: "stop" } };
+      } else {
+        let parsed: unknown = payload;
+        try {
+          parsed = JSON.parse(payload);
+        } catch {
+          parsed = payload;
+        }
+        yield { event, data: parsed };
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

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

@@ -0,0 +1,220 @@
+// 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.
+//
+// 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";
+
+/** Per-realm upstream addresses, client identity, and auth scheme. */
+export interface TraeRealmConfig {
+  /** Data-plane host: chat + model list (`/api/ide/v1/*`). */
+  readonly core: string;
+  /** Fallback core hosts, tried in order after `core`. */
+  readonly coreFallbacks: readonly string[];
+  /** Business host: CloudIDE OAuth token exchange, entitlement. */
+  readonly account: string;
+  /** Fallback account hosts. */
+  readonly accountFallbacks: readonly string[];
+  /** Entitlement / payment host. */
+  readonly pay: string;
+  /** Growth host (daily check-in credits). CN-only in practice. */
+  readonly ug: string;
+  /** Upstream-facing User-Agent for the non-chat endpoints. */
+  readonly userAgent: string;
+  /** Version code sent as `x-ide-version-code`. */
+  readonly versionCode: string;
+  /** Region tag sent in the request body. */
+  readonly region: string;
+  /** True when this realm's `/api/ide/v1/model_list` answers. */
+  readonly modelListSupported: boolean;
+}
+
+/**
+ * Chat path, identical across realms.
+ *
+ * The list endpoint takes a body (`{"type":"chat"}`); the donor posts it, so
+ * this is not a bare GET.
+ */
+export const TRAE_CHAT_PATH = "/api/ide/v1/llm_raw_chat";
+export const TRAE_MODEL_LIST_PATH = "/api/ide/v1/model_list";
+
+/**
+ * Agent path, serving the IDE picker's roster.
+ *
+ * A different surface from {@link TRAE_CHAT_PATH}, not a version of it: this
+ * one selects models by `config_name` + `config_source` and ignores
+ * `model_name` entirely, so the two rosters cannot be merged into one call.
+ */
+export const TRAE_AGENT_CHAT_PATH = "/api/agent/v3/llm_utils_chat";
+
+/**
+ * Resolves which roster the agent surface serves for an account.
+ *
+ * `solo_agent` holds the picker's chat-capable configs. Other values are
+ * either rejected (`solo_coder` is `4001 param is invalid`) or resolve to a
+ * different, non-chat set.
+ */
+export const TRAE_AGENT_FUNCTION = "solo_agent";
+
+/** OAuth / business paths, relative to the realm's `account` host. */
+export const TRAE_EXCHANGE_TOKEN_PATH = "/cloudide/api/v3/trae/oauth/ExchangeToken";
+
+/**
+ * Endpoints that redeem a PKCE `AuthCode`, tried in order.
+ *
+ * Distinct from {@link TRAE_EXCHANGE_TOKEN_PATH}, which is the authenticated
+ * refresh-token rotation and refuses an `AuthCode` with "Invalid param".
+ *
+ * The `/trae/api/v3` form is tried first because it is the one that answers:
+ * the `/cloudide/api/v3/public` form returns 500 for every input, including a
+ * garbage code, with an internal DNS failure (`cloudide.coreservice.apiserver`),
+ * so it is kept only as a fallback in case that is repaired.
+ *
+ * Sourced from the login page's own client (`TraeExchangeTokenV2` and
+ * `PublicExchangeToken` in `9839.*.js`).
+ */
+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. */
+export const TRAE_AUTHORIZATION_PATH = "/authorization";
+
+/**
+ * Path the login page will accept as `auth_callback_url`.
+ *
+ * Verified against the live page: it renders the login form only when the
+ * callback path is `/authorize`. Any other path — `/callback`, `/auth/callback`,
+ * `/`, 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.
+ */
+export const TRAE_CALLBACK_PATH = "/authorize";
+
+/**
+ * Login-guidance endpoints, tried in order.
+ *
+ * This is the one Trae OAuth step that is not per-realm: the guidance call is
+ * what *discovers* the login host, so asking a realm's own account host would
+ * presuppose the answer. Verified live: all three answer 200 and return
+ * `Result.LoginHost` (`www.trae.ai`).
+ */
+export const TRAE_LOGIN_GUIDANCE_URLS: readonly string[] = [
+  "https://api.marscode.com/cloudide/api/v3/trae/GetLoginGuidance",
+  "https://api.trae.ai/cloudide/api/v3/trae/GetLoginGuidance",
+  "https://www.trae.ai/cloudide/api/v3/trae/GetLoginGuidance",
+];
+
+/** 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.
+ *
+ * `intl` carries two core fallbacks and an account fallback; `cn` has exactly
+ * one host per role. That is upstream fact, not an oversight.
+ *
+ * `modelListSupported` is false for intl: upstream answers
+ * `403 no schema found` there, so discovery must not pretend a live fetch
+ * succeeded and must fall back to the static roster.
+ */
+export const TRAE_REALMS: Readonly<Record<TraeRealm, TraeRealmConfig>> = {
+  cn: {
+    // Resolved dynamically by the client. `api.trae.com.cn` only serves
+    // CloudIDE/OAuth/pay — `/api/ide/v1/*` there is a 404.
+    core: "https://trae-api-cn.mchost.guru",
+    coreFallbacks: [],
+    account: "https://api.trae.com.cn",
+    accountFallbacks: [],
+    pay: "https://api.trae.com.cn",
+    // The check-in routes are registered on `api.trae.cn` only; the same path
+    // on `api.trae.com.cn` is a 404.
+    ug: "https://api.trae.cn",
+    userAgent: "Trae CN/3.4.3",
+    versionCode: "20260212",
+    region: "CN",
+    modelListSupported: true,
+  },
+  intl: {
+    core: "https://core-normal.traeapi.us",
+    coreFallbacks: ["https://core-normal.trae.ai", "https://coresg-normal.trae.ai"],
+    account: "https://grow-normal.trae.ai",
+    accountFallbacks: ["https://grow-normal.traeapi.us"],
+    pay: "https://grow-normal.traeapi.us",
+    ug: "https://grow-normal.traeapi.us",
+    userAgent: "Trae/3.6.2",
+    versionCode: "20260212",
+    region: "US",
+    // Verified against an SG account: the region host answers `model_list`.
+    modelListSupported: true,
+  },
+};
+
+/**
+ * Data-plane host per account region, when the login reported one.
+ *
+ * An intl account is provisioned into a region and its token only authenticates
+ * against that region's core host. Verified: a `userRegion=sg` account sent to
+ * `core-normal.traeapi.us` answers `1001 "we are not able to authenticate you"`,
+ * while `coresg-normal.trae.ai` accepts the same token and streams normally.
+ * Without this, a correct login produced an account that could never dispatch.
+ *
+ * `store-country-code` follows the same value: the US host was rejecting the
+ * token *and* the roster it serves is a different catalog.
+ */
+export const TRAE_REGION_CORE_HOSTS: Readonly<Record<string, string>> = {
+  sg: "https://coresg-normal.trae.ai",
+  us: "https://core-normal.traeapi.us",
+};
+
+/** The app id is constant across realms. */
+export const TRAE_APP_ID = "6eefa01c-1036-4c7e-9ca5-d891f63bfcd8";
+
+/** Plugin channel, constant across realms. */
+export const TRAE_PLUGIN_CHANNEL = "icube-ai";
+
+/**
+ * Provider id → realm.
+ *
+ * CN is a separate provider id rather than a flag on `trae`, matching
+ * `qodercn`/`cbcn`: the two deployments share no host, no OAuth client, and no
+ * model roster, so a single provider could not describe either one.
+ */
+export function traeRealmForProvider(providerId: string): TraeRealm {
+  return providerId === "traecn" ? "cn" : "intl";
+}
+
+/** Data-plane host candidates in failover order: primary first, then fallbacks. */
+export function traeCoreCandidates(realm: TraeRealm): readonly string[] {
+  const config = TRAE_REALMS[realm];
+  return [config.core, ...config.coreFallbacks];
+}
+
+/** Business host candidates in failover order. */
+export function traeAccountCandidates(realm: TraeRealm): readonly string[] {
+  const config = TRAE_REALMS[realm];
+  return [config.account, ...config.accountFallbacks];
+}