cartethyia 2.4.6 → 2.5.0

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

@@ -0,0 +1,450 @@
+// Qoder model catalogs, one per realm, plus the live listing that supersedes them.
+//
+// The two realms publish different rosters: the donor's snapshot files
+// (`qoder_catalog_cn.json`, `qoder_catalog_intl.json`) disagree on 5 keys and on
+// the context window of the keys they share. A single merged list therefore
+// advertises models a given account cannot reach, and hides the ones only the
+// other realm serves — so each realm keeps its own static floor.
+//
+// The static rows are the *offline floor*, not the truth: the authoritative list
+// is `/algo/api/v2/model/list` for the account's own realm (`discoverQoderModels`).
+import { GatewayError } from "../../../protocol/gateway-error";
+import { defineModel } from "../../provider-model-definition";
+import type { ModelDefinition } from "../../provider-model-definition";
+import { QODER_CHAT_PATH, QODER_MODELS_PATH, qoderGatewayCandidates, type QoderRealm } from "./qoder-realm";
+import { qoderVirtualIdFor, QODER_VIRTUAL_MODELS } from "./qoder-virtual";
+
+/** One upstream catalog row, as `/algo/api/v2/model/list` reports it. */
+export interface QoderCatalogEntry {
+  readonly key: string;
+  readonly displayName: string;
+  readonly isVl: boolean;
+  readonly isReasoning: boolean;
+  /**
+   * Largest window this model can be switched to.
+   *
+   * Upstream states two different numbers: `max_input_tokens` is the window
+   * *currently selected* (often 180k), while `context_config` lists the
+   * selectable windows — `{"200K":…, "400K":…, "1M":…}` — which for the same
+   * row go up to 1M. Taking `max_input_tokens` alone published and dispatched
+   * the smaller figure, so Qoder was told the conversation was 180k when the
+   * account could use 1M.
+   */
+  readonly maxInputTokens: number | undefined;
+  readonly enable: boolean;
+  /**
+   * Whether upstream publishes this row as free.
+   *
+   * Qoder states it per row (`is_free`) and it is not inferable: `price_factor`
+   * is 0 on both free and some billed rows, and the lite-plan flag describes a
+   * plan tier rather than a model. So the free tier is read from this field
+   * instead of being hardcoded as a list, which is what lets a plan change
+   * move a model between tiers without a code change.
+   */
+  readonly isFree: boolean;
+}
+
+/**
+ * The widest selectable window on one catalog row.
+ *
+ * `context_config` is the authority when present: it names every window the
+ * account can switch to, whereas `max_input_tokens` only names the one active
+ * now. Absent both, `undefined` — an unknown window is not zero.
+ */
+export function qoderMaxContextWindow(raw: unknown): number | undefined {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const record = raw as Record<string, unknown>;
+  const candidates: number[] = [];
+  const config = record["context_config"];
+  if (config !== null && typeof config === "object" && !Array.isArray(config)) {
+    for (const option of Object.values(config as Record<string, unknown>)) {
+      if (option === null || typeof option !== "object" || Array.isArray(option)) continue;
+      const tokenCount = (option as Record<string, unknown>)["token_count"];
+      if (typeof tokenCount === "number" && Number.isFinite(tokenCount) && tokenCount > 0) {
+        candidates.push(Math.floor(tokenCount));
+      }
+    }
+  }
+  const stated = record["max_input_tokens"];
+  if (typeof stated === "number" && Number.isFinite(stated) && stated > 0) {
+    candidates.push(Math.floor(stated));
+  }
+  return candidates.length === 0 ? undefined : Math.max(...candidates);
+}
+
+/** One static row's shape, mirrored on `QODER_MODEL_CONFIGS` in `qoder.ts`. */
+interface QoderModelConfig {
+  readonly id: string;
+  readonly display_name: string;
+  readonly max_input_tokens: number;
+  readonly max_output_tokens?: number;
+  readonly is_vl: boolean;
+  readonly is_reasoning: boolean;
+  /**
+   * Whether upstream publishes this row as free. Absent means upstream did not
+   * state it for the row, which is not the same as false — only an explicit
+   * `false` marks the model as billed.
+   */
+  readonly is_free?: boolean;
+}
+
+/**
+ * China roster (14 keys).
+ *
+ * Captured from the donor's `qoder_catalog_cn.json`, which is the decoded
+ * `chat` array of a real CN account's model list.
+ */
+export const QODER_CN_MODEL_CONFIGS: Readonly<Record<string, QoderModelConfig>> = {
+  auto: { id: "auto", display_name: "Auto", max_output_tokens: 64000, max_input_tokens: 200000, is_vl: true, is_reasoning: true },
+  qmodel_38max: { id: "qmodel_38max", display_name: "Qwen3.8-Max", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  qfmodel: { id: "qfmodel", display_name: "Qwen3.8-Flash", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  qmodel_latest: { id: "qmodel_latest", display_name: "Qwen3.7-Max", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  qmodel: { id: "qmodel", display_name: "Qwen3.7-Plus", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  q37fmodel: { id: "q37fmodel", display_name: "Qwen3.7-Flash", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  dmodel: { id: "dmodel", display_name: "DeepSeek-V4-Pro", max_output_tokens: 384000, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  dfmodel: { id: "dfmodel", display_name: "DeepSeek-Flash", max_output_tokens: 384000, max_input_tokens: 1000000, is_vl: true, is_reasoning: false },
+  gmodel: { id: "gmodel", display_name: "GLM-5.3", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  gfmodel: { id: "gfmodel", display_name: "GLM-5.3-Flash", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  gm51model: { id: "gm51model", display_name: "GLM-5.2", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  kmodel_latest: { id: "kmodel_latest", display_name: "Kimi-K3", max_output_tokens: 131072, max_input_tokens: 1000000, is_vl: true, is_reasoning: false },
+  kmodel: { id: "kmodel", display_name: "Kimi-K2.8-Preview", max_output_tokens: 65536, max_input_tokens: 1000000, is_vl: true, is_reasoning: true },
+  mmodel: { id: "mmodel", display_name: "MiniMax-M2.7", max_output_tokens: 131072, max_input_tokens: 200000, is_vl: false, is_reasoning: false },
+};
+
+/**
+ * Global/intl roster (17 keys), from the donor's `qoder_catalog_intl.json`.
+ *
+ * Note how the shared keys differ from CN — `auto` is non-reasoning here and
+ * `qmodel` carries a 1M window. That is why the rosters are not merged.
+ */
+export const QODER_INTL_MODEL_CONFIGS: Readonly<Record<string, QoderModelConfig>> = {
+  auto: { id: "auto", display_name: "Auto", max_input_tokens: 200000, max_output_tokens: 64_000, is_vl: true, is_reasoning: false },
+  ultimate: { id: "ultimate", display_name: "Ultimate", max_input_tokens: 1000000, max_output_tokens: 128_000, is_vl: true, is_free: false, is_reasoning: true },
+  // `fast` is what the live roster reports today; `performance` is the older
+  // key for the same slot. Both are kept so a hand-added model id written
+  // against either name still resolves — the roster is the offline floor, and
+  // discovery supersedes it on the first successful fetch.
+  fast: { id: "fast", display_name: "Fast", max_input_tokens: 1000000, max_output_tokens: 64_000, is_vl: true, is_reasoning: false },
+  performance: { id: "performance", display_name: "Performance", max_input_tokens: 1000000, max_output_tokens: 64_000, is_vl: true, is_reasoning: false },
+  efficient: { id: "efficient", display_name: "Efficient", max_input_tokens: 200000, max_output_tokens: 64_000, is_vl: true, is_reasoning: false },
+  smodel: { id: "smodel", display_name: "Sonus", max_input_tokens: 1000000, max_output_tokens: 128_000, is_vl: true, is_free: false, is_reasoning: true },
+  cmodel: { id: "cmodel", display_name: "Cantus", max_input_tokens: 1000000, max_output_tokens: 128_000, is_vl: true, is_free: false, is_reasoning: true },
+  qmodel_38max: { id: "qmodel_38max", display_name: "Qwen3.8-Max", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: true },
+  qfmodel: { id: "qfmodel", display_name: "Qwen3.8-Flash", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: true, is_reasoning: true },
+  qmodel_latest: { id: "qmodel_latest", display_name: "Qwen3.7-Max", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: false },
+  qmodel: { id: "qmodel", display_name: "Qwen3.7-Plus", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: false },
+  kmodel_latest: { id: "kmodel_latest", display_name: "Kimi-K3", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: false, is_reasoning: false },
+  kmodel: { id: "kmodel", display_name: "Kimi-K2.8-Preview", max_input_tokens: 1000000, max_output_tokens: 65_536, is_vl: true, is_free: false, is_reasoning: false },
+  gmodel: { id: "gmodel", display_name: "GLM-5.3", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: false, is_reasoning: true },
+  gfmodel: { id: "gfmodel", display_name: "GLM-5.3-Flash", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: true },
+  dmodel: { id: "dmodel", display_name: "DeepSeek-V4-Pro", max_input_tokens: 1000000, max_output_tokens: 384_000, is_vl: true, is_free: false, is_reasoning: true },
+  dfmodel: { id: "dfmodel", display_name: "DeepSeek-Flash", max_input_tokens: 1000000, max_output_tokens: 384_000, is_vl: true, is_free: true, is_reasoning: true },
+  mmodel: { id: "mmodel", display_name: "MiniMax-M3", max_input_tokens: 1000000, max_output_tokens: 512_000, is_vl: true, is_free: false, is_reasoning: false },
+};
+
+/**
+ * Output ceilings are stated per row, not derived.
+ *
+ * Qoder's `/model/list` reports no output limit at all — none of the 21 fields
+ * it returns for any row mentions output — so these come from the static
+ * roster, set to what the same model is filed at elsewhere in the catalog
+ * (DeepSeek-V4 at 384k, GLM/Qwen/Kimi/MiniMax at 131k, the GPT-class slots at
+ * 128k). The 32k that used to be hardcoded here applied to every row alike,
+ * which is what made the whole catalog look capped at one number.
+ *
+ * A row with no stated ceiling leaves `out` unset so `defineModel` can still
+ * consult the base catalog rather than publishing a guess.
+ */
+
+function qoderModels(
+  configs: Readonly<Record<string, QoderModelConfig>>,
+  providerId: string,
+): readonly ModelDefinition[] {
+  return Object.entries(configs).map(([id, cfg]) =>
+    defineModel({
+      id,
+      providerId,
+      wireFamily: "chat",
+      endpoint: QODER_CHAT_PATH,
+      ctx: cfg.max_input_tokens,
+      ...(cfg.max_output_tokens === undefined ? {} : { out: cfg.max_output_tokens }),
+      vision: cfg.is_vl,
+      reasoning: cfg.is_reasoning,
+      // Only an explicit `true` marks the row free; an unstated flag is left
+      // unset so nothing claims a tier the roster did not state.
+      ...(cfg.is_free === undefined ? {} : { free: cfg.is_free, freeTier: cfg.is_free }),
+    }),
+  );
+}
+
+/** Static offline catalog for the China realm. */
+export const QODER_CN_MODELS: readonly ModelDefinition[] = qoderModels(QODER_CN_MODEL_CONFIGS, "qodercn");
+
+/** Static offline catalog for the global/intl realm. */
+const QODER_INTL_ROSTER: readonly ModelDefinition[] = qoderModels(QODER_INTL_MODEL_CONFIGS, "qoder");
+
+/**
+ * Virtual rows, one per roster key that has a caller-facing name.
+ *
+ * A virtual row inherits its target's limits and capabilities rather than
+ * restating them: the two ids are the same upstream model, so a window or a
+ * vision flag that disagreed between them would be a lie in one of the two
+ * places. A target this realm does not serve contributes no row, which is what
+ * keeps the CN and intl catalogs honest about their own rosters.
+ */
+export function qoderVirtualModels(
+  roster: readonly ModelDefinition[],
+  providerId: string,
+): readonly ModelDefinition[] {
+  const byId = new Map(roster.map((row) => [row.modelId, row]));
+  const rows: ModelDefinition[] = [];
+  for (const virtual of QODER_VIRTUAL_MODELS) {
+    const target = byId.get(virtual.target);
+    if (target === undefined) continue;
+    rows.push(
+      defineModel({
+        id: virtual.id,
+        providerId,
+        wireFamily: "chat",
+        endpoint: QODER_CHAT_PATH,
+        // `null`, not a number: an unknown window is unknown, and `defineModel`
+        // substitutes the shared unfiled fallback for null — the same marker a
+        // hand-added row gets.
+        ctx: target.contextLimit ?? null,
+        ...(target.outputLimit === null ? {} : { out: target.outputLimit }),
+        vision: target.modalities.input.includes("image"),
+        reasoning: target.reasoning ?? false,
+        toolCall: target.toolCall ?? false,
+        // The same model under its caller-facing name belongs to the same tier,
+        // so the pill follows the roster row rather than being restated.
+        ...(target.freeTier === undefined ? {} : { free: target.freeTier, freeTier: target.freeTier }),
+      }),
+    );
+  }
+  return rows;
+}
+
+/**
+ * Static offline catalog for the global/intl realm.
+ *
+ * A roster key that has a caller-facing name is published under that name
+ * only: upstream's keys are opaque slots (`dfmodel`, `cmodel`), and offering
+ * both the slot and its name shows one model twice under two ids nobody can
+ * tell apart. A key with no known name is kept as-is — an unnamed slot is
+ * still reachable, and inventing a name for it would assert what upstream
+ * never stated.
+ *
+ * The key remains what dispatch sends; see `qoder-virtual.ts`.
+ */
+export const QODER_INTL_MODELS: readonly ModelDefinition[] = [
+  ...QODER_INTL_ROSTER.filter((row) => qoderVirtualIdFor(row.modelId) === undefined),
+  ...qoderVirtualModels(QODER_INTL_ROSTER, "qoder"),
+];
+
+/**
+ * Reads upstream's `{"chat": [...]}` envelope.
+ *
+ * Rows without a usable `key` are dropped rather than coerced: a model id the
+ * upstream did not state would become an unroutable catalog row.
+ */
+export function mapQoderCatalogResponse(raw: unknown): QoderCatalogEntry[] {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return [];
+  const chat = (raw as Record<string, unknown>)["chat"];
+  if (!Array.isArray(chat)) return [];
+  const entries: QoderCatalogEntry[] = [];
+  for (const row of chat) {
+    if (row === null || typeof row !== "object" || Array.isArray(row)) continue;
+    const record = row as Record<string, unknown>;
+    const key = record["key"];
+    if (typeof key !== "string" || key.trim().length === 0) continue;
+    const displayName = record["display_name"];
+    entries.push({
+      key: key.trim(),
+      displayName: typeof displayName === "string" && displayName.length > 0 ? displayName : key.trim(),
+      isVl: record["is_vl"] === true,
+      isReasoning: record["is_reasoning"] === true,
+      maxInputTokens: qoderMaxContextWindow(record),
+      isFree: record["is_free"] === true,
+      // Absent means "not stated", which is not the same as disabled.
+      enable: record["enable"] !== false,
+    });
+  }
+  return entries;
+}
+
+/** Projects one live catalog row onto a Cartethyia catalog row. */
+export function qoderCatalogModel(
+  entry: QoderCatalogEntry,
+  providerId: string,
+): ModelDefinition {
+  return defineModel({
+    id: entry.key,
+    providerId,
+    wireFamily: "chat",
+    endpoint: QODER_CHAT_PATH,
+    // `null`, not omitted: an upstream row that stated no window is unknown,
+    // not unlimited, and `defineModel` substitutes its own "unfiled" estimate
+    // for null — the same marker a hand-added row gets.
+    ctx: entry.maxInputTokens ?? null,
+    vision: entry.isVl,
+    reasoning: entry.isReasoning,
+    // Free tier straight from upstream's own flag, so the pill on a model card
+    // tracks the plan rather than a hardcoded id list. Both statements hold:
+    // a free row bills zero per token and belongs to the provider's free tier.
+    free: entry.isFree,
+    freeTier: entry.isFree,
+  });
+}
+
+/**
+ * Header factory for one signed request.
+ *
+ * Injected rather than imported: the COSY signer lives in `qoder.ts`, which
+ * imports this module's rosters — importing it back would be a cycle. The
+ * callback receives the URL and the exact body that will be sent, because the
+ * signature covers both.
+ */
+export type QoderSigner = (url: string, body: string) => Promise<Record<string, string>>;
+
+/**
+ * The account's own live model list.
+ *
+ * Two details are load-bearing and non-obvious:
+ *
+ * - the request is a **GET that carries the signed body**. A bare GET answers
+ *   403, because the server validates signature against body; the donor
+ *   (`read_dynamic_models`) signs `{}` and sends it as the GET's data.
+ * - the signature covers only the path, so switching gateway hosts between
+ *   attempts does not invalidate it.
+ *
+ * Hosts are tried primary → fallbacks (intl has three, CN one) and the first
+ * host that answers with a usable list wins.
+ *
+ * Signing is injected, never reimplemented: `headers(url, body)` is the COSY
+ * signer from `qoder.ts`, passed in because that module imports this one and
+ * importing it back would be a cycle. `encode` is the same arrangement for
+ * Qoder's scrambled body alphabet — omitted, the literal `{}` is both signed
+ * and sent, which is what a caller whose signer already binds the credential
+ * wants.
+ *
+ * `fetcher` is optional in the type but required at runtime, and there is
+ * deliberately no global-`fetch` default: a test cannot reach the network by
+ * accident, and production is forced through the SSRF-validated egress
+ * (`network/outbound-fetch.ts`). That egress is a `node:http` path, which is
+ * also the only way a body reaches the wire on a GET — `fetch` itself rejects
+ * `GET` + `body` with "request with GET/HEAD method cannot have body".
+ */
+/**
+ * How long one realm's live list is reused, in milliseconds.
+ *
+ * The roster is account-wide and changes rarely — upstream adds or retires a
+ * key, it does not reshuffle per request — so every catalog refresh inside the
+ * window would re-sign and re-fetch an identical list. The donor caches the
+ * same way (`fetch_models`, 300 s per realm).
+ */
+const DISCOVERY_CACHE_TTL_MS = 300_000;
+
+/** One realm's cached roster, with the instant it was read. */
+interface CachedRoster {
+  readonly at: number;
+  readonly models: readonly ModelDefinition[];
+}
+
+/** Per-realm live-list cache; keyed by realm, not by account. */
+const discoveryCache = new Map<QoderRealm, CachedRoster>();
+
+/**
+ * Drops one realm's cached list.
+ *
+ * Exported for tests: the cache is module state, so a test that builds a
+ * roster and then asserts a fresh fetch would otherwise read the entry the
+ * previous assertion left behind.
+ */
+export function resetQoderDiscoveryCache(realm?: QoderRealm): void {
+  if (realm === undefined) discoveryCache.clear();
+  else discoveryCache.delete(realm);
+}
+
+export async function discoverQoderModels(input: {
+  readonly realm: QoderRealm;
+  /** Account secret the injected signer signs with; blank fails fast. */
+  readonly credential: string;
+  readonly headers: QoderSigner;
+  readonly fetcher?: typeof fetch;
+  readonly signal?: AbortSignal;
+  /** Defaults to the realm's bundled provider id (`qodercn` | `qoder`). */
+  readonly providerId?: string;
+  /** Body encoder; Qoder uses its own scrambled base64 alphabet. */
+  readonly encode?: (body: Uint8Array) => string;
+}): Promise<readonly ModelDefinition[]> {
+  const providerId = input.providerId ?? (input.realm === "cn" ? "qodercn" : "qoder");
+  const cached = discoveryCache.get(input.realm);
+  if (cached !== undefined && Date.now() - cached.at < DISCOVERY_CACHE_TTL_MS) {
+    return cached.models;
+  }
+  // The credential belongs to the caller and is never echoed into `details`;
+  // this only refuses the case where discovery was asked for without one,
+  // which would otherwise surface as an opaque 403 from upstream.
+  if (typeof input.credential !== "string" || input.credential.trim().length === 0) {
+    throw new GatewayError(
+      "authentication_failed",
+      401,
+      "Qoder model discovery requires an account credential.",
+      { providerId, realm: input.realm },
+    );
+  }
+  const fetcher = input.fetcher;
+  if (fetcher === undefined) {
+    throw new GatewayError(
+      "invalid_request",
+      400,
+      "Qoder model discovery requires a validated outbound fetch",
+      { providerId, realm: input.realm },
+    );
+  }
+  const signedBody =
+    input.encode === undefined ? "{}" : input.encode(new TextEncoder().encode("{}"));
+  let lastError: unknown;
+  for (const host of qoderGatewayCandidates(input.realm)) {
+    const url = `${host}${QODER_MODELS_PATH}`;
+    try {
+      const headers = await input.headers(url, signedBody);
+      const response = await fetcher(url, {
+        method: "GET",
+        headers: headers as unknown as HeadersInit,
+        // The signed body must accompany the GET or upstream refuses it.
+        body: signedBody,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      });
+      if (!response.ok) {
+        lastError = new Error(`Qoder model list answered ${response.status}`);
+        continue;
+      }
+      const entries = mapQoderCatalogResponse((await response.json()) as unknown);
+      // Emptiness is judged after `enable` filtering, not before: a roster
+      // whose every row is disabled has no usable model and must fall through
+      // to the next host rather than return an empty catalog.
+      const enabled = entries.filter((entry) => entry.enable);
+      if (enabled.length === 0) {
+        lastError = new Error("Qoder model list returned no usable models");
+        continue;
+      }
+      const models = enabled.map((entry) => qoderCatalogModel(entry, providerId));
+      // Cached only after a host actually answered: a failure must stay
+      // retryable on the next call rather than being frozen for five minutes.
+      discoveryCache.set(input.realm, { at: Date.now(), models });
+      return models;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw new GatewayError(
+    "transport_unavailable",
+    502,
+    `Qoder model discovery failed for ${input.realm}: ${
+      lastError instanceof Error ? lastError.message : "unknown error"
+    }`,
+    { providerId, realm: input.realm },
+    "upstream",
+  );
+}