cartethyia 2.5.9 → 2.6.0

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

@@ -1,192 +1,193 @@
-// Qoder quota.
-//
-// `GET /api/v2/quota/usage` on the **openapi** host, with a plain bearer token
-// — no COSY signature on this surface, which is the one place the business API
-// differs from inference.
-//
-// The response carries two quota objects and they are not interchangeable:
-//
-// - `userQuota` is the plan allowance — what the account bought.
-// - `addOnQuota` is granted credits (daily check-in, promotions) — what it was
-//   given on top.
-//
-// The donor sums them into one balance, and that is right for a credit balance:
-// both are credits in the same unit and either can be spent. It would be wrong
-// for two *rate limits*, which is why these windows are marked `pooled` here
-// and the Trae request buckets are not.
-//
-// Teams add a third object (`orgResourcePackage`), a shared pool that sits
-// outside the account's own allowance. It is only real when it is available,
-// and an account whose plan is exhausted but whose shared pool still has
-// credit is *not* exhausted.
-
-import type {
-  FetchLike,
-  ProviderQuotaResult,
-  ProviderQuotaWindow,
-} from "../../quota/quota-contracts";
-import {
-  cleanError,
-  isoDate,
-  number,
-  percentWindow,
-  quotaRecord,
-  record,
-} from "../../quota/quota-contracts";
-import type { QuotaCollectionContext } from "../../quota/quota-support";
-import { QODER_REALMS, type QoderRealm } from "./qoder-realm";
-
-/** Paths on the realm's openapi host. */
-const QUOTA_PATH = "/api/v2/quota/usage";
-
-/** Shared-pool keys, in the order the donor tries them. */
-const SHARED_KEYS: readonly string[] = [
-  "orgResourcePackage",
-  "sharedQuota",
-  "teamQuota",
-  "poolQuota",
-  "sharedCredits",
-  "sharedCredit",
-];
-
-/**
- * Whether a shared pool is usable.
- *
- * Absent means "not declared unavailable", which is usable. Only an explicit
- * false/null/0 rules it out — reading absence as unavailable is what made a
- * team account with a live pool look exhausted.
- */
-function sharedAvailable(source: Record<string, unknown>): boolean {
-  const value = source["available"];
-  if (value === undefined || value === null) return true;
-  if (typeof value === "boolean") return value;
-  if (typeof value === "number") return value !== 0;
-  if (typeof value === "string") return value.trim().toLowerCase() !== "false";
-  return true;
-}
-
-function creditWindow(
-  kind: string,
-  label: string,
-  remaining: number | null,
-  limit: number | null,
-  resetsAt: string | null,
-): ProviderQuotaWindow | null {
-  if (remaining === null && limit === null) return null;
-  const used = remaining !== null && limit !== null ? limit - remaining : null;
-  return percentWindow(kind, label, null, resetsAt, used, limit, "pooled");
-}
-
-/**
- * Reads one Qoder account's quota.
- *
- * A degenerate body — both quota objects missing, or `isQuotaExceeded` with a
- * zero remaining *and* a zero total — is reported as an error rather than as a
- * zero balance. "No quota" parks the account; "could not read the quota" does
- * not, and those two are not the same claim.
- */
-/** Records an unreadable body where an operator can act on it, not as an error. */
-function logQoderQuotaMiss(detail: string): void {
-  console.warn(`[quota] qoder quota unreadable: ${detail}`);
-}
-
-export async function fetchQoderQuota(
-  credential: string,
-  fetcher: FetchLike,
-  context?: QuotaCollectionContext,
-): Promise<ProviderQuotaResult> {
-  const raw = context?.auth_state ?? {};
-  const realm: QoderRealm = raw["realm"] === "cn" || raw["region"] === "CN" ? "cn" : "intl";
-  const config = QODER_REALMS[realm];
-  const url = `${config.openapi}${QUOTA_PATH}`;
-
-  let payload: unknown;
-  try {
-    const response = await fetcher(url, {
-      method: "GET",
-      headers: {
-        accept: "application/json",
-        authorization: `Bearer ${credential}`,
-        "user-agent": config.userAgent,
-      },
-    });
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
-    payload = await response.json();
-  } catch (error) {
-    // Unreachable is not a balance. See the note on the degenerate branch.
-    logQoderQuotaMiss(cleanError(error));
-    return { source: "qoder", plan: null, windows: [], error: null };
-  }
-
-  const root = quotaRecord(payload);
-  const userQuota = record(root["userQuota"]);
-  const addOnQuota = record(root["addOnQuota"]);
-  const owned = [userQuota, addOnQuota].filter(
-    (value): value is Record<string, unknown> => value !== null,
-  );
-
-  const bothMissing = owned.length === 0;
-  // A live account on the free tier really does answer `userQuota` all zeroes
-  // with `isQuotaExceeded: true` — verified against a real credential:
-  // `{"isQuotaExceeded":true,"userQuota":{"total":0,"used":0,"remaining":0},
-  // "totalUsagePercentage":0.0,...}`. That is a balance of zero, not an
-  // unreadable body. Only a response with *both* quota objects absent is
-  // unreadable, and it is logged rather than returned — never as an error,
-  // which would cool the account.
-  const degenerate = bothMissing;
-  if (degenerate) {
-    // A body we cannot trust is not a zero balance, and it is not a failed
-    // read either: `error` is what flags the account `quota_fetch_failed` and
-    // cools it, so a shape we simply do not recognise would park a working
-    // account. Logged instead of returned.
-    logQoderQuotaMiss(
-      bothMissing
-        ? "Qoder quota response carried no quota objects."
-        : "Qoder reported quota exceeded with a zero total; not read as a balance.",
-    );
-    return { source: "qoder", plan: null, windows: [], error: null };
-  }
-
-  const resetsAt = isoDate(root["expiresAt"] ?? root["expireAt"] ?? root["expires_at"]);
-  const windows: ProviderQuotaWindow[] = [];
-  const plan = creditWindow("qoder:plan", "Plan credits", number(userQuota?.["remaining"]), number(userQuota?.["total"]), resetsAt);
-  if (plan) windows.push(plan);
-  const addOn = creditWindow("qoder:addon", "Granted credits", number(addOnQuota?.["remaining"]), number(addOnQuota?.["total"]), resetsAt);
-  if (addOn) windows.push(addOn);
-
-  for (const key of SHARED_KEYS) {
-    const shared = record(root[key]);
-    if (!shared) continue;
-    if (!sharedAvailable(shared)) continue;
-    const window = creditWindow(
-      "qoder:shared",
-      "Shared pool",
-      number(shared["remaining"]),
-      number(shared["cap"] ?? shared["total"]),
-      null,
-    );
-    if (window) windows.push(window);
-    break;
-  }
-
-  if (windows.length === 0) {
-    logQoderQuotaMiss("Qoder quota response carried no readable balance.");
-    return { source: "qoder", plan: null, windows: [], error: null };
-  }
-  return { source: "qoder", plan: null, windows, error: null };
-}
-
-/**
- * The `qodercn` provider's quota.
- *
- * Same collector, realm forced to `cn`: a CN account is refused by
- * `openapi.qoder.sh`, and the collector cannot see the provider id — the
- * context carries auth state only.
- */
-export function fetchQoderCnQuota(
-  credential: string,
-  fetcher: FetchLike,
-  context?: QuotaCollectionContext,
-): Promise<ProviderQuotaResult> {
-  return fetchQoderQuota(credential, fetcher, { ...context, auth_state: { ...(context?.auth_state ?? {}), realm: "cn" } });
-}
+// Qoder quota.
+//
+// `GET /api/v2/quota/usage` on the **openapi** host, with a plain bearer token
+// — no COSY signature on this surface, which is the one place the business API
+// differs from inference.
+//
+// The response carries two quota objects and they are not interchangeable:
+//
+// - `userQuota` is the plan allowance — what the account bought.
+// - `addOnQuota` is granted credits (daily check-in, promotions) — what it was
+//   given on top.
+//
+// The donor sums them into one balance, and that is right for a credit balance:
+// both are credits in the same unit and either can be spent. It would be wrong
+// for two *rate limits*, which is why these windows are marked `pooled` here
+// and the Trae request buckets are not.
+//
+// Teams add a third object (`orgResourcePackage`), a shared pool that sits
+// outside the account's own allowance. It is only real when it is available,
+// and an account whose plan is exhausted but whose shared pool still has
+// credit is *not* exhausted.
+
+import type {
+  FetchLike,
+  ProviderQuotaResult,
+  ProviderQuotaWindow,
+} from "../../quota/quota-contracts";
+import {
+  cleanError,
+  isoDate,
+  number,
+  percentWindow,
+  quotaRecord,
+  record,
+} from "../../quota/quota-contracts";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+import { log } from "../../../observability/logger";
+import { QODER_REALMS, type QoderRealm } from "./qoder-realm";
+
+/** Paths on the realm's openapi host. */
+const QUOTA_PATH = "/api/v2/quota/usage";
+
+/** Shared-pool keys, in the order the donor tries them. */
+const SHARED_KEYS: readonly string[] = [
+  "orgResourcePackage",
+  "sharedQuota",
+  "teamQuota",
+  "poolQuota",
+  "sharedCredits",
+  "sharedCredit",
+];
+
+/**
+ * Whether a shared pool is usable.
+ *
+ * Absent means "not declared unavailable", which is usable. Only an explicit
+ * false/null/0 rules it out — reading absence as unavailable is what made a
+ * team account with a live pool look exhausted.
+ */
+function sharedAvailable(source: Record<string, unknown>): boolean {
+  const value = source["available"];
+  if (value === undefined || value === null) return true;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") return value.trim().toLowerCase() !== "false";
+  return true;
+}
+
+function creditWindow(
+  kind: string,
+  label: string,
+  remaining: number | null,
+  limit: number | null,
+  resetsAt: string | null,
+): ProviderQuotaWindow | null {
+  if (remaining === null && limit === null) return null;
+  const used = remaining !== null && limit !== null ? limit - remaining : null;
+  return percentWindow(kind, label, null, resetsAt, used, limit, "pooled");
+}
+
+/**
+ * Reads one Qoder account's quota.
+ *
+ * A degenerate body — both quota objects missing, or `isQuotaExceeded` with a
+ * zero remaining *and* a zero total — is reported as an error rather than as a
+ * zero balance. "No quota" parks the account; "could not read the quota" does
+ * not, and those two are not the same claim.
+ */
+/** Records an unreadable body where an operator can act on it, not as an error. */
+function logQoderQuotaMiss(detail: string): void {
+  log.warn(`[quota] qoder quota unreadable: ${detail}`);
+}
+
+export async function fetchQoderQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  const raw = context?.auth_state ?? {};
+  const realm: QoderRealm = raw["realm"] === "cn" || raw["region"] === "CN" ? "cn" : "intl";
+  const config = QODER_REALMS[realm];
+  const url = `${config.openapi}${QUOTA_PATH}`;
+
+  let payload: unknown;
+  try {
+    const response = await fetcher(url, {
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${credential}`,
+        "user-agent": config.userAgent,
+      },
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    payload = await response.json();
+  } catch (error) {
+    // Unreachable is not a balance. See the note on the degenerate branch.
+    logQoderQuotaMiss(cleanError(error));
+    return { source: "qoder", plan: null, windows: [], error: null };
+  }
+
+  const root = quotaRecord(payload);
+  const userQuota = record(root["userQuota"]);
+  const addOnQuota = record(root["addOnQuota"]);
+  const owned = [userQuota, addOnQuota].filter(
+    (value): value is Record<string, unknown> => value !== null,
+  );
+
+  const bothMissing = owned.length === 0;
+  // A live account on the free tier really does answer `userQuota` all zeroes
+  // with `isQuotaExceeded: true` — verified against a real credential:
+  // `{"isQuotaExceeded":true,"userQuota":{"total":0,"used":0,"remaining":0},
+  // "totalUsagePercentage":0.0,...}`. That is a balance of zero, not an
+  // unreadable body. Only a response with *both* quota objects absent is
+  // unreadable, and it is logged rather than returned — never as an error,
+  // which would cool the account.
+  const degenerate = bothMissing;
+  if (degenerate) {
+    // A body we cannot trust is not a zero balance, and it is not a failed
+    // read either: `error` is what flags the account `quota_fetch_failed` and
+    // cools it, so a shape we simply do not recognise would park a working
+    // account. Logged instead of returned.
+    logQoderQuotaMiss(
+      bothMissing
+        ? "Qoder quota response carried no quota objects."
+        : "Qoder reported quota exceeded with a zero total; not read as a balance.",
+    );
+    return { source: "qoder", plan: null, windows: [], error: null };
+  }
+
+  const resetsAt = isoDate(root["expiresAt"] ?? root["expireAt"] ?? root["expires_at"]);
+  const windows: ProviderQuotaWindow[] = [];
+  const plan = creditWindow("qoder:plan", "Plan credits", number(userQuota?.["remaining"]), number(userQuota?.["total"]), resetsAt);
+  if (plan) windows.push(plan);
+  const addOn = creditWindow("qoder:addon", "Granted credits", number(addOnQuota?.["remaining"]), number(addOnQuota?.["total"]), resetsAt);
+  if (addOn) windows.push(addOn);
+
+  for (const key of SHARED_KEYS) {
+    const shared = record(root[key]);
+    if (!shared) continue;
+    if (!sharedAvailable(shared)) continue;
+    const window = creditWindow(
+      "qoder:shared",
+      "Shared pool",
+      number(shared["remaining"]),
+      number(shared["cap"] ?? shared["total"]),
+      null,
+    );
+    if (window) windows.push(window);
+    break;
+  }
+
+  if (windows.length === 0) {
+    logQoderQuotaMiss("Qoder quota response carried no readable balance.");
+    return { source: "qoder", plan: null, windows: [], error: null };
+  }
+  return { source: "qoder", plan: null, windows, error: null };
+}
+
+/**
+ * The `qodercn` provider's quota.
+ *
+ * Same collector, realm forced to `cn`: a CN account is refused by
+ * `openapi.qoder.sh`, and the collector cannot see the provider id — the
+ * context carries auth state only.
+ */
+export function fetchQoderCnQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  return fetchQoderQuota(credential, fetcher, { ...context, auth_state: { ...(context?.auth_state ?? {}), realm: "cn" } });
+}

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

@@ -1,106 +1,106 @@
-// Qoder realms: one vendor, two unrelated deployments.
-//
-// `qoder` (global / intl) and `qodercn` (China) share the wire protocol — COSY
-// signing, the scrambled body, the enveloped SSE stream — but nothing else
-// about the address: different gateway host, different openapi host, different
-// OAuth client id, different website, different UA, and a *different model
-// roster*. Treating them as one provider with a region flag is what made a CN
-// account dispatch to `*.qoder.sh` and be refused.
-//
-// Everything per-realm lives here so the adapter, the OAuth client, and the
-// discovery fetcher cannot drift apart on host, client id, or roster.
-//
-// Sourced from the donor hub `Public/qoder2api-hub` (`REALM_CONFIGS` in
-// `qoder_accounts.py`), which builds every upstream URL from this table.
-
-/** One Qoder deployment. */
-export type QoderRealm = "intl" | "cn";
-
-/** Per-realm upstream addresses and client identity. */
-export interface QoderRealmConfig {
-  /** Inference + model-list gateway host. */
-  readonly gateway: string;
-  /** Fallback gateway hosts, tried in order after `gateway`. */
-  readonly gatewayFallbacks: readonly string[];
-  /** Business API host (device token, userinfo, quota). */
-  readonly openapi: string;
-  /** Where the operator signs in. */
-  readonly website: string;
-  /** OAuth client id sent on the device-token exchange. */
-  readonly clientId: string;
-  /** Native redirect the desktop client registers. */
-  readonly redirectUri: string;
-  /** Upstream-facing User-Agent. */
-  readonly userAgent: string;
-}
-
-/** Chat + model-list paths, identical across realms. */
-export const QODER_CHAT_PATH =
-  "/algo/api/v2/service/pro/sse/agent_chat_generation?FetchKeys=llm_model_result&AgentId=agent_common&Encode=1";
-export const QODER_MODELS_PATH = "/algo/api/v2/model/list?Encode=1";
-
-/**
- * Realm → deployment.
- *
- * `intl` carries two gateway fallbacks (`api2`, `api3`); `cn` has exactly one
- * host and no resilience, which is upstream fact, not an oversight — the donor
- * loops `gateway + gatewayFallbacks` and gets one candidate for CN.
- */
-export const QODER_REALMS: Readonly<Record<QoderRealm, QoderRealmConfig>> = {
-  intl: {
-    gateway: "https://api1.qoder.sh",
-    gatewayFallbacks: ["https://api2.qoder.sh", "https://api3.qoder.sh"],
-    openapi: "https://openapi.qoder.sh",
-    website: "https://qoder.com",
-    clientId: "e883ade2-e6e3-4d6d-adf7-f92ceff5fdcb",
-    redirectUri: "qoder://aicoding.aicoding-agent/login-success",
-    userAgent: "Qoder/1.1.64",
-  },
-  cn: {
-    gateway: "https://gateway.qoder.com.cn",
-    gatewayFallbacks: [],
-    openapi: "https://openapi.qoder.com.cn",
-    website: "https://qoder.com.cn",
-    clientId: "1c5e33e1-364d-4ce6-b02c-acaa81274a5c",
-    redirectUri: "qoder-work-cn://",
-    userAgent: "QoderWork/1.1.64",
-  },
-};
-
-/** The realm one bundled provider id belongs to. */
-export function qoderRealmForProvider(providerId: string): QoderRealm {
-  return providerId === "qodercn" ? "cn" : "intl";
-}
-
-/** Gateway hosts for one realm, primary first. */
-export function qoderGatewayCandidates(realm: QoderRealm): readonly string[] {
-  const config = QODER_REALMS[realm];
-  return [config.gateway, ...config.gatewayFallbacks];
-}
-
-/**
- * Model keys that exist in exactly one realm.
- *
- * From the donor's `INTL_EXCLUSIVE` / `CN_EXCLUSIVE` tables. A request for one
- * of these on the wrong realm does not degrade — it is refused — so the roster
- * each realm publishes is the authority, not a union.
- */
-export const QODER_INTL_EXCLUSIVE: ReadonlySet<string> = new Set([
-  "fast",
-  "efficient",
-  "cmodel",
-  "smodel",
-  "ultimate",
-  "performance",
-]);
-
-export const QODER_CN_EXCLUSIVE: ReadonlySet<string> = new Set([
-  "q37fmodel",
-  "gm51model",
-]);
-
-/** True when this model key is served only by the other realm. */
-export function isForeignQoderModel(realm: QoderRealm, modelId: string): boolean {
-  const foreign = realm === "cn" ? QODER_INTL_EXCLUSIVE : QODER_CN_EXCLUSIVE;
-  return foreign.has(modelId.trim().toLowerCase());
-}
+// Qoder realms: one vendor, two unrelated deployments.
+//
+// `qoder` (global / intl) and `qodercn` (China) share the wire protocol — COSY
+// signing, the scrambled body, the enveloped SSE stream — but nothing else
+// about the address: different gateway host, different openapi host, different
+// OAuth client id, different website, different UA, and a *different model
+// roster*. Treating them as one provider with a region flag is what made a CN
+// account dispatch to `*.qoder.sh` and be refused.
+//
+// Everything per-realm lives here so the adapter, the OAuth client, and the
+// discovery fetcher cannot drift apart on host, client id, or roster.
+//
+// Sourced from the donor hub `Public/qoder2api-hub` (`REALM_CONFIGS` in
+// `qoder_accounts.py`), which builds every upstream URL from this table.
+
+/** One Qoder deployment. */
+export type QoderRealm = "intl" | "cn";
+
+/** Per-realm upstream addresses and client identity. */
+export interface QoderRealmConfig {
+  /** Inference + model-list gateway host. */
+  readonly gateway: string;
+  /** Fallback gateway hosts, tried in order after `gateway`. */
+  readonly gatewayFallbacks: readonly string[];
+  /** Business API host (device token, userinfo, quota). */
+  readonly openapi: string;
+  /** Where the operator signs in. */
+  readonly website: string;
+  /** OAuth client id sent on the device-token exchange. */
+  readonly clientId: string;
+  /** Native redirect the desktop client registers. */
+  readonly redirectUri: string;
+  /** Upstream-facing User-Agent. */
+  readonly userAgent: string;
+}
+
+/** Chat + model-list paths, identical across realms. */
+export const QODER_CHAT_PATH =
+  "/algo/api/v2/service/pro/sse/agent_chat_generation?FetchKeys=llm_model_result&AgentId=agent_common&Encode=1";
+export const QODER_MODELS_PATH = "/algo/api/v2/model/list?Encode=1";
+
+/**
+ * Realm → deployment.
+ *
+ * `intl` carries two gateway fallbacks (`api2`, `api3`); `cn` has exactly one
+ * host and no resilience, which is upstream fact, not an oversight — the donor
+ * loops `gateway + gatewayFallbacks` and gets one candidate for CN.
+ */
+export const QODER_REALMS: Readonly<Record<QoderRealm, QoderRealmConfig>> = {
+  intl: {
+    gateway: "https://api1.qoder.sh",
+    gatewayFallbacks: ["https://api2.qoder.sh", "https://api3.qoder.sh"],
+    openapi: "https://openapi.qoder.sh",
+    website: "https://qoder.com",
+    clientId: "e883ade2-e6e3-4d6d-adf7-f92ceff5fdcb",
+    redirectUri: "qoder://aicoding.aicoding-agent/login-success",
+    userAgent: "Qoder/1.1.64",
+  },
+  cn: {
+    gateway: "https://gateway.qoder.com.cn",
+    gatewayFallbacks: [],
+    openapi: "https://openapi.qoder.com.cn",
+    website: "https://qoder.com.cn",
+    clientId: "1c5e33e1-364d-4ce6-b02c-acaa81274a5c",
+    redirectUri: "qoder-work-cn://",
+    userAgent: "QoderWork/1.1.64",
+  },
+};
+
+/** The realm one bundled provider id belongs to. */
+export function qoderRealmForProvider(providerId: string): QoderRealm {
+  return providerId === "qodercn" ? "cn" : "intl";
+}
+
+/** Gateway hosts for one realm, primary first. */
+export function qoderGatewayCandidates(realm: QoderRealm): readonly string[] {
+  const config = QODER_REALMS[realm];
+  return [config.gateway, ...config.gatewayFallbacks];
+}
+
+/**
+ * Model keys that exist in exactly one realm.
+ *
+ * From the donor's `INTL_EXCLUSIVE` / `CN_EXCLUSIVE` tables. A request for one
+ * of these on the wrong realm does not degrade — it is refused — so the roster
+ * each realm publishes is the authority, not a union.
+ */
+export const QODER_INTL_EXCLUSIVE: ReadonlySet<string> = new Set([
+  "fast",
+  "efficient",
+  "cmodel",
+  "smodel",
+  "ultimate",
+  "performance",
+]);
+
+export const QODER_CN_EXCLUSIVE: ReadonlySet<string> = new Set([
+  "q37fmodel",
+  "gm51model",
+]);
+
+/** True when this model key is served only by the other realm. */
+export function isForeignQoderModel(realm: QoderRealm, modelId: string): boolean {
+  const foreign = realm === "cn" ? QODER_INTL_EXCLUSIVE : QODER_CN_EXCLUSIVE;
+  return foreign.has(modelId.trim().toLowerCase());
+}