cartethyia 2.5.4 → 2.5.7

package/src/providers/operations/account-reset-service.ts

@@ -608,7 +608,7 @@ function describeResetCode(code: string): string {
 /**
  * Writes the outcome to `health_events` and, on success, restores the account to
  * `active` so it rejoins dispatch rotation immediately rather than waiting out a
- * cooldown that no longer reflects reality.
+ * cooldown that the reset has already cleared.
  */
 async function recordResetActivity(
   db: CartethyiaDatabase,

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

@@ -332,9 +332,9 @@ export const VERSION_SOURCES = {
     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.
+        // Kiro's downloads page exposes no 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,
       },
@@ -488,8 +488,8 @@ const PROVIDER_VERSION_RESOLVERS: Readonly<Record<string, ClientVersionResolver>
   "opencode-zen": resolvers.opencode,
   "opencode-go": resolvers.opencode,
   // The identity this provider is dispatched under is the CLI's, so the route
-  // identity reports the CLI version. `clineClient` (the VS Code extension
-  // manifest) is no longer the client this provider claims to be.
+  // identity reports the CLI version, not the VS Code extension manifest
+  // (`clineClient`).
   cline: resolvers.clineCli,
   codex: resolvers.codex,
   qoder: resolvers.qoder,
@@ -670,7 +670,7 @@ export function buildCodeBuddyUserAgent(
 ): string {
   // 1:1 with codebuddy2api's identity_headers(): the CLI profile uses ONE version
   // (the npm CLI package pin) for both halves, and the IDE profile uses the other
-  // product's version. This previously always used `version`, so "CLI" produced
+  // product's version. Using `version` for both would make "CLI" produce
   // `CLI/<ide> CodeBuddy/<ide>` — a CLI claiming the desktop build.
   const resolved = identity === "CLI" ? cnVersion : version;
   return `${identity}/${resolved} CodeBuddy/${resolved}`;

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

@@ -34,10 +34,9 @@ export function buildCustomCodexCliHeaders(): Record<string, string> {
  *
  * 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.
+ * rather than as nothing. The Codex CLI identity (`codex_cli_rs/…`) would name
+ * a different vendor's client on requests that most often reach 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`

package/src/providers/operations/provider-catalog-seeder.ts

@@ -1,95 +1,95 @@
-/** Durable materialization of bundled provider model metadata. */
-import { and, eq, sql } from "drizzle-orm";
-import type { CartethyiaDatabase } from "../../persistence/db-handle";
-import { models } from "../../persistence/schema";
-import type { ModelDefinition } from "../provider-model-definition";
-
-/** Persists compiled provider model metadata and reconciles drifted capability flags. */
-export async function seedBundledModels(
-  db: CartethyiaDatabase,
-  builtinModels: ReadonlyMap<string, readonly ModelDefinition[]>,
-): Promise<void> {
-  for (const [providerId, definitions] of builtinModels) {
-    if (definitions.length === 0) continue;
-    // Drop builtin rows the current catalog no longer declares, including rows
-    // whose model id is still present but whose endpoint path drifted (e.g. a
-    // provider that moved from `/chat/completions` to `/v2/chat/completions`).
-    // The unique key is (provider, model, endpoint), so a changed endpoint
-    // would otherwise insert a second row and leave the stale route behind —
-    // the model list would then show duplicates and probes could hit the dead
-    // path. Composite `NOT IN` keeps exactly the (model, endpoint) pairs the
-    // catalog owns.
-    const pairs = definitions.map(
-      (definition) => sql`(${definition.modelId}, ${definition.endpointPath})`,
-    );
-    await db
-      .delete(models)
-      .where(
-        and(
-          eq(models.providerId, providerId),
-          eq(models.source, "builtin"),
-          sql`(${models.modelId}, ${models.endpointPath}) NOT IN (${sql.join(pairs, sql`, `)})`,
-        ),
-      );
-  }
-  const now = new Date();
-  const seen = new Set<string>();
-  const rows = [...builtinModels.entries()].flatMap(([providerId, definitions]) =>
-    definitions.flatMap((definition) => {
-      const key = `${providerId}\u0000${definition.modelId}\u0000${definition.endpointPath}`;
-      if (seen.has(key)) return [];
-      seen.add(key);
-      return [
-        {
-          providerId,
-          modelId: definition.modelId,
-          wireFamily: definition.wireFamily,
-          serviceKind: definition.serviceKind ?? "llm",
-          endpointPath: definition.endpointPath,
-          contextLimit: definition.contextLimit,
-          outputLimit: definition.outputLimit,
-          modalities: definition.modalities,
-          reasoning: definition.reasoning,
-          toolCall: definition.toolCall,
-          cost: definition.cost,
-          // A static row either knows it is refused on a free plan or says
-          // nothing. Never coerced to false: the column is three-valued, and
-          // "nobody established it" is not the same claim as "served on free".
-          proOnly: definition.proOnly ?? null,
-          // Same three-valued rule for the inverse: the provider's directory
-          // states the tier, so the flag is carried rather than derived.
-          freeTier: definition.freeTier ?? null,
-          source: "builtin",
-          sourceUpdatedAt: now,
-          enabled: true,
-        },
-      ];
-    }),
-  );
-  if (rows.length === 0) return;
-  // Reconcile static metadata on conflict rather than skipping: capability
-  // flags (toolCall/reasoning/webSearch), wire family, limits, and cost can
-  // drift on a pre-existing row (e.g. a discovery seeded `tool_call=false`
-  // before the static catalog was corrected). `source` is forced back to
-  // `builtin`: a fetch upsert may have flipped a builtin row to `discovered`,
-  // and the static catalog owns these ids. `enabled` is operator-owned and
-  // must never be reset here.
-  await db.insert(models).values(rows).onConflictDoUpdate({
-    target: [models.providerId, models.modelId, models.endpointPath],
-    set: {
-      wireFamily: sql`excluded.wire_family`,
-      serviceKind: sql`excluded.service_kind`,
-      endpointPath: sql`excluded.endpoint_path`,
-      contextLimit: sql`excluded.context_limit`,
-      outputLimit: sql`excluded.output_limit`,
-      modalities: sql`excluded.modalities`,
-      reasoning: sql`excluded.reasoning`,
-      toolCall: sql`excluded.tool_call`,
-      cost: sql`excluded.cost`,
-      proOnly: sql`excluded.pro_only`,
-      freeTier: sql`excluded.free_tier`,
-      source: sql`'builtin'`,
-      sourceUpdatedAt: sql`excluded.source_updated_at`,
-    },
-  });
-}
+/** Durable materialization of bundled provider model metadata. */
+import { and, eq, sql } from "drizzle-orm";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { models } from "../../persistence/schema";
+import type { ModelDefinition } from "../provider-model-definition";
+
+/** Persists compiled provider model metadata and reconciles drifted capability flags. */
+export async function seedBundledModels(
+  db: CartethyiaDatabase,
+  builtinModels: ReadonlyMap<string, readonly ModelDefinition[]>,
+): Promise<void> {
+  for (const [providerId, definitions] of builtinModels) {
+    if (definitions.length === 0) continue;
+    // Drop builtin rows the current catalog no longer declares, including rows
+    // whose model id is still present but whose endpoint path drifted (e.g. a
+    // provider that moved from `/chat/completions` to `/v2/chat/completions`).
+    // The unique key is (provider, model, endpoint), so a changed endpoint
+    // would otherwise insert a second row and leave the stale route behind —
+    // the model list then shows duplicates and probes can hit the dead path.
+    // Composite `NOT IN` keeps exactly the (model, endpoint) pairs the catalog
+    // owns.
+    const pairs = definitions.map(
+      (definition) => sql`(${definition.modelId}, ${definition.endpointPath})`,
+    );
+    await db
+      .delete(models)
+      .where(
+        and(
+          eq(models.providerId, providerId),
+          eq(models.source, "builtin"),
+          sql`(${models.modelId}, ${models.endpointPath}) NOT IN (${sql.join(pairs, sql`, `)})`,
+        ),
+      );
+  }
+  const now = new Date();
+  const seen = new Set<string>();
+  const rows = [...builtinModels.entries()].flatMap(([providerId, definitions]) =>
+    definitions.flatMap((definition) => {
+      const key = `${providerId}\u0000${definition.modelId}\u0000${definition.endpointPath}`;
+      if (seen.has(key)) return [];
+      seen.add(key);
+      return [
+        {
+          providerId,
+          modelId: definition.modelId,
+          wireFamily: definition.wireFamily,
+          serviceKind: definition.serviceKind ?? "llm",
+          endpointPath: definition.endpointPath,
+          contextLimit: definition.contextLimit,
+          outputLimit: definition.outputLimit,
+          modalities: definition.modalities,
+          reasoning: definition.reasoning,
+          toolCall: definition.toolCall,
+          cost: definition.cost,
+          // A static row either knows it is refused on a free plan or says
+          // nothing. Never coerced to false: the column is three-valued, and
+          // "nobody established it" is not the same claim as "served on free".
+          proOnly: definition.proOnly ?? null,
+          // Same three-valued rule for the inverse: the provider's directory
+          // states the tier, so the flag is carried rather than derived.
+          freeTier: definition.freeTier ?? null,
+          source: "builtin",
+          sourceUpdatedAt: now,
+          enabled: true,
+        },
+      ];
+    }),
+  );
+  if (rows.length === 0) return;
+  // Reconcile static metadata on conflict rather than skipping: capability
+  // flags (toolCall/reasoning/webSearch), wire family, limits, and cost can
+  // drift on a pre-existing row (e.g. a discovery seeded `tool_call=false`
+  // before the static catalog was corrected). `source` is forced back to
+  // `builtin`: a fetch upsert may have flipped a builtin row to `discovered`,
+  // and the static catalog owns these ids. `enabled` is operator-owned and
+  // must never be reset here.
+  await db.insert(models).values(rows).onConflictDoUpdate({
+    target: [models.providerId, models.modelId, models.endpointPath],
+    set: {
+      wireFamily: sql`excluded.wire_family`,
+      serviceKind: sql`excluded.service_kind`,
+      endpointPath: sql`excluded.endpoint_path`,
+      contextLimit: sql`excluded.context_limit`,
+      outputLimit: sql`excluded.output_limit`,
+      modalities: sql`excluded.modalities`,
+      reasoning: sql`excluded.reasoning`,
+      toolCall: sql`excluded.tool_call`,
+      cost: sql`excluded.cost`,
+      proOnly: sql`excluded.pro_only`,
+      freeTier: sql`excluded.free_tier`,
+      source: sql`'builtin'`,
+      sourceUpdatedAt: sql`excluded.source_updated_at`,
+    },
+  });
+}

package/src/providers/operations/provider-catalog-service.ts

@@ -134,7 +134,7 @@ export async function seedBundledProviders(db: CartethyiaDatabase): Promise<void
  * console-created provider carries a tenant — so an unowned id absent from the
  * bundle is an orphan by construction, and a tenant-owned BYOK row is never in
  * scope. The model seeder prunes its retired rows the same way; this is the
- * provider-level half that was missing.
+ * provider-level half.
  *
  * Separate from {@link seedBundledProviders} rather than folded into it: the
  * harness calls that seeder on import to converge a shared database, and a
@@ -226,9 +226,8 @@ export async function bundledModelCatalog(
 
 /**
  * Re-seeds the compiled catalogs, called when a provider gains an account after
- * boot. Seeding is no longer account-gated, so this is now simply the same walk
- * as at boot; it exists because an account makes the rows routable and the
- * snapshot must reflect that without waiting for a restart.
+ * boot. It runs the same walk as at boot: an account makes the rows routable and
+ * the snapshot must reflect that without waiting for a restart.
  *
  * Gated on {@link currentCatalogRevision}: this is the seeder the snapshot
  * builder calls on every rebuild, and the invalidation that triggers it is a

package/src/providers/provider-metadata.ts

@@ -415,18 +415,14 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
 /**
  * Web search is a route of its own, never a model capability.
  *
- * There used to be a manual list of providers "whose hosted search had been
- * proven", and a `providerSupportsWebSearch` helper that consulted it. Both are
- * gone. A model row no longer advertises search, and a provider serves search
+ * A model row does not advertise search, and a provider serves search
  * purely by declaring a `serviceKind: "websearch"` catalog row — which is what
  * Exa, Parallel, and Gemini do. Those rows answer `POST /v1/search` and are
  * never reached from a chat turn.
  *
- * The reason is that the flag was never a capability gate: `deriveRequiredCapabilities`
- * deliberately does not derive `web_search`, so no chat request was ever
- * filtered or degraded by it. Its only real effect was to smuggle `llm` rows
- * (Codex, Antigravity) into the fallback candidate list as if they were search
- * routes, and to show a badge in the console. The fallback is gone too: a chat
+ * A search flag is not a capability gate: `deriveRequiredCapabilities`
+ * deliberately does not derive `web_search`, so no chat request is
+ * filtered or degraded by it. A chat
  * turn is dispatched once to the route its model selects, and a hosted search
  * declaration is answered by that upstream, not executed by the gateway.
  */

package/src/providers/provider-registry.ts

@@ -38,8 +38,8 @@ export interface ProviderModule {
  * `upstream_host` is the SSRF-validated network-binding target for this
  * provider — carried on the same registration object as the adapter loader
  * so adding a provider touches one call-site instead of a second map kept
- * in sync by hand elsewhere (`transport/dispatch/proxy-request.ts` used to hardcode this
- * separately; `providers/operations/provider-catalog-service.ts` now derives it from here).
+ * in sync by hand elsewhere; `providers/operations/provider-catalog-service.ts`
+ * derives it from here.
  */
 export interface ProviderRegistration {
   readonly provider_id: ProviderId;
@@ -240,11 +240,10 @@ export class ProviderRegistry {
    * check — no module is loaded — for list projections that must hide the
    * "Fetch models" control from providers with no discovery endpoint.
    *
-   * This is the question the projection should be asking. "Is this a builtin?"
-   * was a proxy for it that was true for every provider when the catalog had no
-   * discovery-backed builtins, and wrong for every one added since: a builtin
-   * that registers a resolver cannot list any model until an operator runs a
-   * sync, so hiding the control leaves it permanently empty.
+   * This is the question the projection should be asking; "is this a builtin?"
+   * is not a proxy for it. A builtin that registers a resolver cannot list any
+   * model until an operator runs a sync, so hiding the control on the strength
+   * of builtin status alone leaves it permanently empty.
    */
   hasModelDiscovery(providerId: string): boolean {
     return this.#registrations.get(parseProviderId(providerId))?.loadModelDiscovery !== undefined;

package/src/providers/provider-usage.ts

@@ -195,7 +195,7 @@ export function normalizeUsage(input: Record<string, unknown>): UsageRecord {
   // the zeroed `*_tokens_details.cached_tokens` those bridges also emit.
   // Flat `cached_tokens` is the intermediate shape `mapGeminiUsage`
   // (Gemini/Antigravity) and CommandCode emit; `cachedContentTokenCount` is
-  // Gemini's raw `usageMetadata` field. Both were previously dropped.
+  // Gemini's raw `usageMetadata` field. Both are consumed here.
   if (
     cached_input_tokens === "unavailable" &&
     typeof input.cached_tokens === "number"

package/src/security/abuse.ts

@@ -78,10 +78,10 @@ export interface IpAbuseOutcome {
    *
    * The store is the only component that knows this: a ban's remainder is its
    * marker's TTL, and a rate-limited window's remainder is the age of its
-   * oldest attempt. Both are server state. The middleware used to answer every
-   * 429 with a fixed `retry-after: 3600`, which told a client hitting a 60-second
-   * window to wait sixty times longer than it had to — and told a client whose
-   * ban had nearly elapsed to wait the full hour again.
+   * oldest attempt. Both are server state. Answering every 429 with a fixed
+   * `retry-after: 3600` would tell a client hitting a 60-second window to wait
+   * sixty times longer than it had to — and tell a client whose ban had nearly
+   * elapsed to wait the full hour again.
    */
   readonly retryAfterMs: number;
 }
@@ -224,7 +224,7 @@ export class InMemoryIpAbuseStore implements IpAbuseStore {
 
   /** Evicts the oldest entries of `map` down to `maxKeys` in a single pass so
    *  an adversarial fan-out over unique identities cannot pin memory. Deleting
-   *  one entry at a time was O(1) but starved reclaim. */
+   *  one entry at a time is O(1) but starves reclaim. */
   private evictOldest<K, V>(map: Map<K, V>): void {
     if (map.size < this.maxKeys) return;
     let toEvict = map.size - this.maxKeys + 1;
@@ -251,10 +251,10 @@ export class InMemoryIpAbuseStore implements IpAbuseStore {
   /**
    * Outage injection for tests, mirroring the store's own reachability.
    *
-   * The service no longer probes the store before using it: every method below
+   * The service does not probe the store before using it: every method below
    * throws when the store is unreachable, and the service's catch maps that to
-   * a bounded `admission_unavailable`. Keeping a separate probe would only add
-   * a round trip to every request on the Redis store.
+   * a bounded `admission_unavailable`. A separate probe would only add a round
+   * trip to every request on the Redis store.
    */
   private assertAvailable(): void {
     if (this.failing) throw new Error("ip store unavailable");
@@ -421,7 +421,12 @@ export class IpAbuseProtectionService {
 
       if (outcome.banned) {
         throw new GatewayError("quota_exceeded", 429, "This address is temporarily banned for too many failed requests. Wait for the ban to lift, then slow down.", {
-          reason: "admission-unavailable",
+          // Distinguishes this from the rate-limited 429 below and from an API
+          // key's own budget. It used to be "admission-unavailable", which is
+          // the label for an *unreachable* store — so every refusal from this
+          // layer claimed an outage that had not happened, and a client could
+          // not tell "banned" from "over the window" from "store is down".
+          reason: "ip-banned",
           ip,
           route: input.route,
           // Measured by the store: the ban marker's remaining TTL. Carried as
@@ -433,7 +438,7 @@ export class IpAbuseProtectionService {
 
       if (outcome.count > this.maxRequestsPerWindow) {
         throw new GatewayError("quota_exceeded", 429, "This address is sending requests faster than the abuse limit allows. Back off and retry after the window rolls over.", {
-          reason: "admission-unavailable",
+          reason: "ip-rate-limited",
           ip,
           route: input.route,
           count: outcome.count,