cartethyia 0.0.0-stage → 2.3.0

package/src/providers/operations/client-versions.ts

@@ -0,0 +1,607 @@
+/**
+ * Central client-version sources and resolvers for provider integrations.
+ *
+ * Every entry follows the same discovered → pinned fallback order.
+ * Provider-specific header builders remain next to their integrations, while
+ * the network source and resolver state live in this table.
+ */
+import {
+  createClientVersionResolver,
+  isSemverish,
+  type ClientVersionResolver,
+  type ClientVersionSnapshot,
+} from "./client-version-resolver";
+import {
+  buildGrokAuthUserAgent as buildGrokAuthUserAgentString,
+  buildGrokShellUserAgent,
+} from "./cli-platform";
+
+async function qoderVersion(response: Response): Promise<string | null> {
+  try {
+    const parsed = (await response.json()) as { version?: unknown };
+    return isSemverish(parsed.version) ? parsed.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function clineClientVersion(response: Response): Promise<string | null> {
+  const data = (await response.json()) as { version?: unknown };
+  return isSemverish(data.version) ? data.version.trim() : null;
+}
+
+async function clineSdkVersion(response: Response): Promise<string | null> {
+  const data = (await response.json()) as {
+    version?: unknown;
+    "dist-tags"?: { latest?: unknown };
+  };
+  const candidate = data.version ?? data["dist-tags"]?.latest;
+  return isSemverish(candidate) ? candidate.trim() : null;
+}
+
+async function kimiVersion(response: Response): Promise<string | null> {
+  const data = (await response.json()) as { info?: { version?: unknown } };
+  return isSemverish(data.info?.version) ? data.info.version.trim() : null;
+}
+
+async function workbuddyDesktopVersion(response: Response): Promise<string | null> {
+  try {
+    const data = (await response.json()) as { version?: unknown; productVersion?: unknown };
+    const candidate = data.productVersion ?? data.version;
+    return typeof candidate === "string" && /^\d+\.\d+\.\d+(?:\.\d+)?(?:[-+][\w.-]+)?$/.test(candidate.trim())
+      ? candidate.trim()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function kiroCaskVersion(response: Response): Promise<string | null> {
+  try {
+    const data = (await response.json()) as { version?: unknown };
+    return isSemverish(data.version) ? data.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function codeBuddyCnVersion(response: Response): Promise<string | null> {
+  try {
+    const data = (await response.json()) as { version?: unknown };
+    if (typeof data.version !== "string") return null;
+    const match = /^\d+\.\d+\.\d+\.\d+/.exec(data.version.trim());
+    return match?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function kiroVersion(response: Response): Promise<string | null> {
+  const body = await response.text();
+  const version =
+    /currentVersion["\\]*\s*:\s*["\\]*([\d.]+)/.exec(body)?.[1] ??
+    /\bIDE\s+([\d.]+)[^<]*Latest/.exec(body)?.[1];
+  return isSemverish(version) ? version : null;
+}
+
+async function antigravityVersion(response: Response): Promise<string | null> {
+  const body = await response.text();
+  for (const line of body.split(/\r?\n/)) {
+    const match = /^\s*version\s*:\s*(?:"([^"]*)"|'([^']*)'|([^\s#]+))\s*(?:#.*)?$/.exec(line);
+    if (!match) continue;
+    const version = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+    return isSemverish(version) ? version : null;
+  }
+  return null;
+}
+/**
+ * GitHub release tag (`v3.14.3` → `3.14.3`). Tags carry the leading `v`
+ * by convention while the gateway stamps bare versions, so the prefix is
+ * stripped rather than rejected by the semver check.
+ */
+async function githubReleaseVersion(response: Response): Promise<string | null> {
+  try {
+    const data = (await response.json()) as { tag_name?: unknown; name?: unknown };
+    const raw = data.tag_name ?? data.name;
+    const candidate = typeof raw === "string" && raw.startsWith("v") ? raw.slice(1) : raw;
+    return isSemverish(candidate) ? (candidate as string).trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Runtime SDK version stamped into the Kiro data-plane User-Agent.
+ *
+ * Pinned rather than discovered: the generation surface is served by the client
+ * the IDE ships, not by a release we can track, so the shipped build is the
+ * only source of truth. The agent compiles its generation client from
+ * `@aws/codewhisperer-streaming-client`, and that package's own version is the
+ * value the client stamps.
+ *
+ * How to rediscover it — take it from the shipped build, never from guesswork:
+ *   1. The IDE installer is published on the vendor's download feed under a
+ *      path that repeats the version:
+ *      `https://prod.download.desktop.kiro.dev/releases/stable/win32-x64/signed/<v>/kiro-ide-<v>-stable-win32-x64.exe`
+ *   2. Unpack it. The exe's payload is an LZMA stream behind a 4-byte tag:
+ *      `7z x` the exe, drop the 4-byte tag from the extracted `[0]`, then
+ *      `7z x` that as LZMA.
+ *   3. In the unpacked payload, locate the agent bundle — the region defining
+ *      `getCodeWhispererStreamingClient` — and read the aliased package
+ *      metadata inside it: `"@aws/codewhisperer-streaming-client" … version:"x.y.z"`.
+ *      Use that one. One installer also embeds other bundles carrying older
+ *      copies of the same package, so a bare version match is not evidence.
+ *
+ * The discovery source below only supplies the *IDE* version that follows the
+ * `KiroIDE` device marker.
+ */
+const KIRO_RUNTIME_SDK_VERSION = "1.0.39";
+
+/**
+ * AWS SSO OIDC SDK version stamped into login and token-refresh User-Agents.
+ *
+ * Distinct from the runtime SDK above because the upstream sees them as two
+ * different AWS SDK clients: `oidc.{region}.amazonaws.com` is served by
+ * `aws-sdk-js` sso-oidc, while the generation surface reports the
+ * `codewhispererstreaming` client.
+ */
+const KIRO_SSO_SDK_VERSION = "3.980.0";
+
+/**
+ * Runtime segments the observed Kiro client reports.
+ *
+ * `win32#<build>` is the host Windows release, so it varies by machine and this
+ * is the shape a Windows 11 client produces.
+ *
+ * The `md/nodejs#` segment is the runtime the client executes under, not the
+ * host's Node: the IDE is an Electron app, so it is Electron's bundled Node.
+ * Rediscover both from the same unpacked payload — the app's `package.json`
+ * pins `"electron": "<version>"`, and that Electron release's metadata gives
+ * the Node version to stamp here.
+ */
+const KIRO_SYSTEM_VERSION = "win32#10.0.22631";
+/** Node version the observed Kiro client reports (Electron's bundled Node). */
+const KIRO_NODE_VERSION = "24.18.0";
+
+/** Ordered upstream sources and pinned fallbacks for every client version. */
+export const VERSION_SOURCES = {
+  antigravity: {
+    key: "antigravity",
+    fallback: "2.24.0",
+    sources: [
+      {
+        url: "https://antigravity-hub-auto-updater-974169037036.us-central1.run.app/manifest/latest-arm64-mac.yml",
+        extract: antigravityVersion,
+      },
+    ],
+  },
+  qoder: {
+    key: "qoder",
+    fallback: "1.1.73",
+    sources: [
+      {
+        url: "https://registry.npmjs.org/@qoder-ai/qodercli/latest",
+        extract: qoderVersion,
+      },
+    ],
+  },
+  opencode: {
+    key: "opencode",
+    // The v1 package (`opencode-ai`) stopped at 1.18. The v2 line publishes
+    // under `@opencode/cli`, and this feed is what its own installer reads.
+    fallback: "2.0.32",
+    minVersion: "2.0.0",
+    sources: [{ url: "https://opencode.ai/update/api/latest/cli/npm" }],
+  },
+  commandcode: {
+    key: "commandcode",
+    fallback: "1.84.0",
+    sources: [{ url: "https://registry.npmjs.org/command-code/latest" }],
+  },
+  grok: {
+    key: "grok",
+    fallback: "1.0.62",
+    sources: [
+      { url: "https://storage.googleapis.com/grok-build-public-artifacts/cli/stable" },
+      { url: "https://registry.npmjs.org/@xai-official/grok/latest" },
+    ],
+  },
+  clineClient: {
+    key: "cline-client",
+    fallback: "4.1.25",
+    minVersion: "4.1.23",
+    sources: [
+      {
+        url: "https://raw.githubusercontent.com/cline/cline/main/apps/vscode/package.json",
+        extract: clineClientVersion,
+      },
+    ],
+  },
+  clineSdk: {
+    key: "cline-sdk",
+    fallback: "0.0.95",
+    sources: [{ url: "https://registry.npmjs.org/@cline/sdk/latest", extract: clineSdkVersion }],
+  },
+  codex: {
+    key: "codex",
+    fallback: "0.163.0",
+    sources: [{ url: "https://registry.npmjs.org/@openai/codex/latest" }],
+  },
+  workbuddyClient: {
+    key: "workbuddy-client",
+    fallback: "5.8.4.41366630",
+    sources: [
+      {
+        url: "https://www.workbuddy.ai/v2/update?platform=workbuddy-win32-x64-user",
+        extract: workbuddyDesktopVersion,
+      },
+      {
+        url: "https://www.workbuddy.ai/v2/update?platform=workbuddy-darwin-arm64",
+        extract: workbuddyDesktopVersion,
+      },
+    ],
+  },
+  workbuddyCnClient: {
+    key: "workbuddy-cn-client",
+    fallback: "5.8.3.41334564",
+    sources: [
+      {
+        url: "https://www.workbuddy.cn/v2/update?platform=workbuddy-win32-x64-user",
+        extract: workbuddyDesktopVersion,
+      },
+      {
+        url: "https://www.workbuddy.cn/v2/update?platform=workbuddy-darwin-arm64",
+        extract: workbuddyDesktopVersion,
+      },
+    ],
+  },
+  workbuddyCli: {
+    key: "workbuddy",
+    fallback: "2.168.2",
+    sources: [
+      { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
+      { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
+    ],
+  },
+  kimiCli: {
+    key: "kimi-cli",
+    fallback: "1.52.0",
+    sources: [{ url: "https://pypi.org/pypi/kimi-cli/json", extract: kimiVersion }],
+  },
+  kiro: {
+    key: "kiro",
+    fallback: "1.3.11",
+    sources: [
+      {
+        // Kiro's downloads page no longer exposes a stable version string.
+        // Homebrew tracks the official installer URL and exposes its version
+        // as JSON; keep the product page parser as a fallback.
+        url: "https://formulae.brew.sh/api/cask/kiro.json",
+        extract: kiroCaskVersion,
+      },
+      { url: "https://kiro.dev/downloads/", extract: kiroVersion },
+    ],
+  },
+  codebuddy: {
+    key: "codebuddy",
+    fallback: "2.168.2",
+    sources: [
+      { url: "https://registry.npmjs.org/@tencent-ai/codebuddy-code/latest" },
+      { url: "https://registry.npmmirror.com/@tencent-ai/codebuddy-code/latest" },
+    ],
+  },
+  codebuddyCn: {
+    key: "codebuddy-cn",
+    fallback: "4.12.2.41207131",
+    sources: [
+      {
+        // Official CN builds are listed by Homebrew's maintained cask feed;
+        // its version points at the current Tencent CN desktop artifact.
+        url: "https://formulae.brew.sh/api/cask/codebuddy-cn.json",
+        extract: codeBuddyCnVersion,
+      },
+    ],
+  },
+  claudeCli: {
+    key: "claude-cli",
+    // Current `@anthropic-ai/claude-code` release, so the billing
+    // `cc_version=` suffix and the `claude-cli/` User-Agent stay on what
+    // upstream ships.
+    fallback: "2.1.302",
+    sources: [{ url: "https://registry.npmjs.org/@anthropic-ai/claude-code/latest" }],
+  },
+  claudeSdk: {
+    key: "claude-sdk",
+    // The `@anthropic-ai/sdk` version *bundled inside the Claude Code
+    // release* — the value stamped into the OAuth refresh User-Agent template
+    // (`anthropic-sdk-typescript/{claude_code_sdk_version} userOAuthProvider`).
+    // npm's standalone SDK is a different release line and is deliberately not
+    // discovered: it would advertise a version Claude Code never bundled. Bump
+    // alongside the CLI. Read it from the shipped native binary, which defines
+    // the version string the template interpolates — never from guesswork.
+    fallback: "0.128.0",
+    sources: [],
+  },
+  github: {
+    key: "github-copilot-chat",
+    fallback: "0.43.0",
+    sources: [
+      {
+        url: "https://api.github.com/repos/microsoft/vscode-copilot-chat/releases/latest",
+        extract: githubReleaseVersion,
+      },
+    ],
+  },
+  kilo: {
+    key: "kilo-code",
+    fallback: "7.8.14",
+    sources: [{ url: "https://open-vsx.org/api/kilocode/kilo-code" }],
+  },
+  muse: {
+    key: "muse-code",
+    fallback: "1.4.10-R6427.1",
+    sources: [{ url: "https://api.meta.ai/muse-code/channels/muse-stable" }],
+  },
+  zcode: {
+    key: "zcode",
+    fallback: "3.14.3",
+    sources: [
+      {
+        url: "https://api.github.com/repos/zai-org/ZCode/releases/latest",
+        extract: githubReleaseVersion,
+      },
+    ],
+  },
+} as const;
+
+const resolvers = {
+  antigravity: createClientVersionResolver({ ...VERSION_SOURCES.antigravity, client: "antigravity" }),
+  qoder: createClientVersionResolver({ ...VERSION_SOURCES.qoder, client: "qoder" }),
+  opencode: createClientVersionResolver({ ...VERSION_SOURCES.opencode, client: "opencode" }),
+  commandcode: createClientVersionResolver({ ...VERSION_SOURCES.commandcode, client: "command-code" }),
+  grok: createClientVersionResolver({ ...VERSION_SOURCES.grok, client: "grok" }),
+  clineClient: createClientVersionResolver({ ...VERSION_SOURCES.clineClient, client: "cline" }),
+  clineSdk: createClientVersionResolver({ ...VERSION_SOURCES.clineSdk, client: "cline-sdk" }),
+  codex: createClientVersionResolver({ ...VERSION_SOURCES.codex, client: "codex" }),
+  workbuddyClient: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyClient, client: "workbuddy" }),
+  workbuddyCnClient: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyCnClient, client: "workbuddy-cn" }),
+  workbuddyCli: createClientVersionResolver({ ...VERSION_SOURCES.workbuddyCli, client: "codebuddy" }),
+  kimiCli: createClientVersionResolver({ ...VERSION_SOURCES.kimiCli, client: "kimi" }),
+  codebuddy: createClientVersionResolver({ ...VERSION_SOURCES.codebuddy, client: "codebuddy" }),
+  codebuddyCn: createClientVersionResolver({ ...VERSION_SOURCES.codebuddyCn, client: "codebuddy" }),
+  claudeCli: createClientVersionResolver({ ...VERSION_SOURCES.claudeCli, client: "claude" }),
+  claudeSdk: createClientVersionResolver({ ...VERSION_SOURCES.claudeSdk, client: "claude-sdk" }),
+  kiro: createClientVersionResolver({ ...VERSION_SOURCES.kiro, client: "kiro" }),
+  github: createClientVersionResolver({ ...VERSION_SOURCES.github, client: "github-copilot" }),
+  kilo: createClientVersionResolver({ ...VERSION_SOURCES.kilo, client: "kilo" }),
+  muse: createClientVersionResolver({ ...VERSION_SOURCES.muse, client: "muse" }),
+  zcode: createClientVersionResolver({ ...VERSION_SOURCES.zcode, client: "zcode" }),
+} satisfies Record<keyof typeof VERSION_SOURCES, ClientVersionResolver>;
+const PROVIDER_VERSION_RESOLVERS: Readonly<Record<string, ClientVersionResolver>> = {
+  antigravity: resolvers.antigravity,
+  grok: resolvers.grok,
+  xai: resolvers.grok,
+  opencode: resolvers.opencode,
+  "opencode-zen": resolvers.opencode,
+  "opencode-go": resolvers.opencode,
+  cline: resolvers.clineClient,
+  codex: resolvers.codex,
+  qoder: resolvers.qoder,
+  commandcode: resolvers.commandcode,
+  workbuddy: resolvers.workbuddyClient,
+  workbuddycn: resolvers.workbuddyCnClient,
+  cb: resolvers.codebuddy,
+  cbcn: resolvers.codebuddyCn,
+  kimi: resolvers.kimiCli,
+  kiro: resolvers.kiro,
+  anthropic: resolvers.claudeCli,
+  claude: resolvers.claudeCli,
+  github: resolvers.github,
+  kilo: resolvers.kilo,
+  muse: resolvers.muse,
+  zcode: resolvers.zcode,
+};
+
+/** Returns the current client version without performing network I/O. */
+export function getProviderClientVersion(providerId: string): ClientVersionSnapshot | undefined {
+  return PROVIDER_VERSION_RESOLVERS[providerId.trim().toLowerCase()]?.snapshot();
+}
+
+/** Live Codex and Claude CLI versions for route-identity choices. */
+export function getRouteIdentityVersions(): {
+  readonly codex: string;
+  readonly claude: string;
+} {
+  return { codex: getCodexVersion(), claude: getClaudeCliVersion() };
+}
+
+/** Refreshes every provider version resolver in parallel; failures keep fallbacks. */
+export async function refreshProviderClientVersions(): Promise<void> {
+  const resolversToRefresh = [...new Set(Object.values(PROVIDER_VERSION_RESOLVERS))];
+  await Promise.allSettled(resolversToRefresh.map((resolver) => resolver.ensure()));
+}
+
+/** One client identity still running on its pinned fallback. */
+export interface PinnedClientVersion {
+  readonly client: string;
+  /** The fallback in force, which is what every request is currently sending. */
+  readonly version: string;
+  /** The lowest version the upstream accepted when it last answered. */
+  readonly minVersion?: string;
+}
+
+/**
+ * Client identities whose version discovery has not succeeded.
+ *
+ * Every header this module builds is version-aware, and a provider that starts
+ * gating on it refuses with wording indistinguishable from a dead credential —
+ * Cline's is "please make sure you're using the latest version and
+ * re-authenticate". That makes a stuck fallback an operational fact an operator
+ * needs *before* it presents as an auth failure, and until now nothing could
+ * tell a pinned fallback from a discovered version: only the synchronous getter
+ * was exported, so the `source` the resolver already tracked was unreadable
+ * outside this module.
+ *
+ * Read-only and never fetched: this reports what is in force right now, for the
+ * same reason the getters never fetch. An empty list is the healthy answer.
+ */
+export function pinnedClientVersions(): readonly PinnedClientVersion[] {
+  const pinned: PinnedClientVersion[] = [];
+  for (const resolver of new Set(Object.values(PROVIDER_VERSION_RESOLVERS))) {
+    const snapshot = resolver.snapshot();
+    if (snapshot.source !== "fallback") continue;
+    pinned.push({
+      client: snapshot.client,
+      version: snapshot.version,
+      ...(resolver.minVersion === undefined ? {} : { minVersion: resolver.minVersion }),
+    });
+  }
+  return pinned;
+}
+
+/**
+ * The accessors every table entry needs, generated from its resolver.
+ *
+ * Request paths only use the synchronous getter. Network discovery belongs to
+ * `refreshProviderClientVersions`, so dispatch and OAuth flows never wait on a
+ * version endpoint.
+ */
+function accessor<K extends keyof typeof resolvers>(name: K): {
+  readonly get: () => string;
+  readonly adopt: (version: string) => void;
+  readonly reset: (version?: string | null) => void;
+} {
+  const resolver = resolvers[name];
+  return {
+    get: () => resolver.get(),
+    adopt: (version: string) => {
+      resolver.adopt(version);
+    },
+    reset: (version?: string | null) => {
+      resolver.reset(version);
+    },
+  };
+}
+
+export const getQoderVersion = accessor("qoder").get;
+export const getAntigravityVersion = accessor("antigravity").get;
+
+export const getOpenCodeVersion = accessor("opencode").get;
+
+export const getCommandCodeVersion = accessor("commandcode").get;
+
+export const getGrokVersion = accessor("grok").get;
+
+export function buildGrokUserAgent(version = getGrokVersion()): string {
+  return buildGrokShellUserAgent(version);
+}
+
+export function buildGrokAuthUserAgent(version = getGrokVersion()): string {
+  return buildGrokAuthUserAgentString(version);
+}
+
+
+export const getClineClientVersion = accessor("clineClient").get;
+export const getClineSdkVersion = accessor("clineSdk").get;
+export const _resetClineClientVersionCache = accessor("clineClient").reset;
+export const _resetClineSdkVersionCache = accessor("clineSdk").reset;
+
+export const getCodexVersion = accessor("codex").get;
+
+export const getWorkBuddyClientVersion = accessor("workbuddyClient").get;
+export const getWorkBuddyCnClientVersion = accessor("workbuddyCnClient").get;
+export const getWorkBuddyCliVersion = accessor("workbuddyCli").get;
+
+export function buildWorkBuddyUserAgent(
+  clientVersion = getWorkBuddyClientVersion(),
+  cliVersion = getWorkBuddyCliVersion(),
+): string {
+  return `WorkBuddy/${clientVersion} WorkBuddy AI/${clientVersion} CLI/${cliVersion}`;
+}
+
+export const _resetWorkBuddyCnClientVersionCache = accessor("workbuddyCnClient").reset;
+
+export const getKimiCliVersion = accessor("kimiCli").get;
+
+export const getCodeBuddyVersion = accessor("codebuddy").get;
+export const getCodeBuddyCnVersion = accessor("codebuddyCn").get;
+export function buildCodeBuddyUserAgent(
+  identity: "IDE" | "CLI",
+  version = identity === "CLI" ? getCodeBuddyCnVersion() : getCodeBuddyVersion(),
+): string {
+  return `${identity}/${version} CodeBuddy/${version}`;
+}
+
+export const _resetCodeBuddyVersionCache = accessor("codebuddy").reset;
+export const _resetCodeBuddyCnVersionCache = accessor("codebuddyCn").reset;
+
+export const getClaudeCliVersion = accessor("claudeCli").get;
+export const adoptClaudeCliVersion = accessor("claudeCli").adopt;
+export const _resetClaudeCliVersionCache = accessor("claudeCli").reset;
+export const getClaudeSdkVersion = accessor("claudeSdk").get;
+
+export const getKiroVersion = accessor("kiro").get;
+
+/**
+ * Builds the `x-amz-user-agent` companion header for the generation surface.
+ *
+ * The upstream pairs this with `user-agent` on every generation request; the
+ * short form carries the SDK identity and the `KiroIDE-{version}-{machineId}`
+ * device marker and nothing else.
+ */
+export function buildKiroAmzUserAgent(version = getKiroVersion(), machineId = ""): string {
+  return `aws-sdk-js/${KIRO_RUNTIME_SDK_VERSION} KiroIDE-${version}-${machineId}`;
+}
+
+/**
+ * Builds the full data-plane `user-agent`.
+ *
+ * Shape: SDK version, `ua/2.1`, the OS and node segments, the API and module
+ * markers, and the `KiroIDE-{version}-{machineId}` device marker. The device
+ * marker is the part the upstream correlates on, so it is never omitted — a
+ * blank machine id advertises the account as a device with no identity, which
+ * is a shape no real client produces.
+ */
+export function buildKiroUserAgent(version = getKiroVersion(), machineId = ""): string {
+  return (
+    `aws-sdk-js/${KIRO_RUNTIME_SDK_VERSION} ua/2.1 ` +
+    `os/${KIRO_SYSTEM_VERSION} lang/js md/nodejs#${KIRO_NODE_VERSION} ` +
+    `api/codewhispererstreaming#${KIRO_RUNTIME_SDK_VERSION} m/E ` +
+    `KiroIDE-${version}-${machineId}`
+  );
+}
+
+/**
+ * Builds the `x-amz-user-agent` companion for an AWS SSO OIDC request.
+ *
+ * The login and token-refresh surfaces are served by a different AWS SDK
+ * client, so they carry that client's version and no device marker — the
+ * observed client does not send one there.
+ */
+export function buildKiroSsoAmzUserAgent(): string {
+  return `aws-sdk-js/${KIRO_SSO_SDK_VERSION} KiroIDE`;
+}
+
+/** Builds the full `user-agent` for an AWS SSO OIDC request. */
+export function buildKiroSsoUserAgent(): string {
+  return (
+    `aws-sdk-js/${KIRO_SSO_SDK_VERSION} ua/2.1 ` +
+    `os/${KIRO_SYSTEM_VERSION} lang/js md/nodejs#${KIRO_NODE_VERSION} ` +
+    `api/sso-oidc#${KIRO_SSO_SDK_VERSION} m/E KiroIDE`
+  );
+}
+
+/**
+ * Builds the `user-agent` the model-catalog and usage surfaces expect.
+ *
+ * Their observed client identifies as `codewhispererruntime` rather than
+ * `codewhispererstreaming`, and carries the `m/N,E` module marker.
+ */
+export function buildKiroRuntimeUserAgent(version = getKiroVersion(), machineId = ""): string {
+  return (
+    `aws-sdk-js/${KIRO_RUNTIME_SDK_VERSION} ua/2.1 ` +
+    `os/${KIRO_SYSTEM_VERSION} lang/js md/nodejs#${KIRO_NODE_VERSION} ` +
+    `api/codewhispererruntime#${KIRO_RUNTIME_SDK_VERSION} m/N,E ` +
+    `KiroIDE-${version}-${machineId}`
+  );
+}

package/src/providers/operations/custom-cli-headers.ts

@@ -0,0 +1,72 @@
+/**
+ * Custom provider CLI identity headers.
+ *
+ * Emits official CLI headers for OpenAI-compatible (Codex CLI) and
+ * Anthropic-compatible (Claude Code CLI) endpoints so upstream requests
+ * reflect realistic first-party tooling instead of naked node/bun user agents.
+ *
+ * Both sides read their version from the live resolver getters rather than the
+ * frozen `claude-fingerprint` constants: those constants are evaluated once at
+ * module load from the pinned fallback and never move, so a custom Anthropic
+ * endpoint would have shipped the pinned Claude CLI version forever even after
+ * discovery resolved a newer one. The getters are synchronous and TTL-cached,
+ * so this costs a cache read per dispatch.
+ */
+import {
+  getClaudeCliVersion,
+  getClaudeSdkVersion,
+  getCodexVersion,
+} from "./client-versions";
+import { buildCodexUserAgent } from "./cli-platform";
+import type { WireFamily } from "../../protocol/canonical-model";
+
+/** Builds Codex CLI identity headers for OpenAI-compatible wire families. */
+export function buildCustomCodexCliHeaders(): Record<string, string> {
+  const version = getCodexVersion();
+  return {
+    "user-agent": buildCodexUserAgent(version),
+    originator: "codex_cli_rs",
+  };
+}
+
+/**
+ * The Claude Code User-Agent, on the live CLI version.
+ *
+ * This is the route-level default for a provider whose operator set no client
+ * identity of their own: a bare API key identifies as the Claude Code CLI
+ * rather than as nothing. It used to be the Codex CLI identity
+ * (`codex_cli_rs/…`), which named a different vendor's client on requests that
+ * most often reached neither — an upstream that keys on the client string
+ * would act on it.
+ *
+ * The version comes from the live getter for the same reason
+ * {@link buildCustomClaudeCliHeaders} does: the pinned `claude-fingerprint`
+ * constants are evaluated once at module load and never move, so a default
+ * built from them would send a Claude CLI version the client stopped shipping
+ * and still answer to.
+ */
+export function buildClaudeCliUserAgent(): string {
+  return `claude-cli/${getClaudeCliVersion()} (external, cli)`;
+}
+
+/** Builds Claude Code CLI identity headers for Anthropic-compatible wire families. */
+export function buildCustomClaudeCliHeaders(): Record<string, string> {
+  return {
+    "User-Agent": buildClaudeCliUserAgent(),
+    "x-app": "cli",
+    "X-Stainless-Package-Version": getClaudeSdkVersion(),
+    "X-Stainless-Runtime": "node",
+    "X-Stainless-Retry-Count": "0",
+  };
+}
+
+/**
+ * Returns the appropriate CLI headers based on target wire family.
+ * Messages wire family gets Claude CLI headers; chat / responses get Codex CLI headers.
+ */
+export function resolveCustomCliHeaders(wireFamily: WireFamily): Record<string, string> {
+  if (wireFamily === "messages") {
+    return buildCustomClaudeCliHeaders();
+  }
+  return buildCustomCodexCliHeaders();
+}

package/src/providers/operations/gateway-user-agent.ts

@@ -0,0 +1,15 @@
+import { CARTETHYIA_VERSION } from "../../version";
+
+/**
+ * Gateway identity stamped on outbound upstream traffic.
+ *
+ * `Cartethyia/<version>` rides the dispatch path only for providers that
+ * explicitly opt in (`gatewayUserAgent: true` on their spec/registration).
+ * Providers with their own first-party identity — Codex (`codex_cli_rs`),
+ * Claude Code (`claude-cli`), and any adapter stamping bespoke headers —
+ * are never touched: cloaking those would break the identity the upstream
+ * expects. BYOK custom providers keep their official CLI cloaking unless
+ * the operator explicitly provisions the gateway agent instead.
+ */
+export const GATEWAY_USER_AGENT = `Cartethyia/${CARTETHYIA_VERSION}` as const;
+