cartethyia 2.7.3 → 2.7.5

package/src/boot/lifecycle.ts

@@ -4,12 +4,13 @@ import { buildProductionDeps } from "./dependencies";
 import type { ProductionDeps } from "./dependencies";
 import { withTimeout } from "./timeout";
 import { resolveShutdownDrainWindowMs } from "../config/runtime";
+import { log } from "../observability/logger";
 
 export type ShutdownReason = "SIGTERM" | "SIGINT" | "reload" | "update";
-export type ShutdownState =
+type ShutdownState =
   "idle" | "stop_admitting" | "bounded_drain_wait" | "flush_telemetry" | "close_pools" | "done";
 
-export interface ShutdownHooks {
+interface ShutdownHooks {
   flushTelemetry?: (deadlineMs: number) => Promise<void>;
   closePools?: () => Promise<void>;
   abortInflight?: () => void;
@@ -107,7 +108,10 @@ export class ShutdownCoordinator {
         if (this.inflight.size > 0) {
           try {
             this.hooks.abortInflight?.();
-          } catch {
+          } catch (error) {
+            // A failed abort must not be silent: it leaks in-flight work into
+            // close_pools, which then closes pools under live requests.
+            log.warn("[shutdown] abort in-flight failed", error as Error);
           }
         }
         await this.waitForDrain(Date.now() + this.drainTimeoutMs);
@@ -156,14 +160,9 @@ export class ShutdownCoordinator {
     const remaining = Math.max(0, deadlineMs - Date.now());
     // No budget left: invoking the hook would start work with zero deadline
     // that withTimeout immediately cancels; skip straight to pool close.
-    if (remaining <= 0 || !this.hooks.flushTelemetry) {
-      if (remaining > 0 && !this.hooks.flushTelemetry) {
-        // bounded small delay to simulate flush
-        const wait = Math.min(remaining, 5);
-        await new Promise<void>((r) => setTimeout(r, wait));
-      }
-      return;
-    }
+    // Without a hook there is nothing to flush either — both cases return
+    // here and the drain proceeds to pool close.
+    if (remaining <= 0 || !this.hooks.flushTelemetry) return;
     try {
       await withTimeout(
         this.hooks.flushTelemetry(deadlineMs),
@@ -189,7 +188,7 @@ export class ShutdownCoordinator {
   }
 }
 
-export interface ElyxiaServer {
+interface ElyxiaServer {
   stop(closeActiveConnections?: boolean): unknown;
 }
 

package/src/config/cooldowns.ts

@@ -4,63 +4,67 @@
 
 import { CONFIG_SPEC, readInt } from "./spec";
 
-let _rateLimitCooldown: number | undefined;
+/** The spec row shape every cooldown resolver reads. */
+type CooldownSpecEntry = {
+  readonly kind: "int";
+  readonly default: number;
+  readonly min: number;
+  readonly max: number;
+};
+
+/** Shared cache keyed by env-var name, so one resolver per knob stays warm. */
+const cooldownCache = new Map<string, number>();
+
+function cachedCooldownMs(name: string, entry: CooldownSpecEntry): number {
+  const cached = cooldownCache.get(name);
+  if (cached !== undefined) return cached;
+  const value = readInt(name, entry);
+  cooldownCache.set(name, value);
+  return value;
+}
+
 /** Fallback cooldown for a provider rate limit (default 15m). */
 export function resolveAccountRateLimitCooldownMs(): number {
-  if (_rateLimitCooldown === undefined)
-    _rateLimitCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS,
   );
-  return _rateLimitCooldown;
 }
 
-let _quotaCooldown: number | undefined;
 /**
  * Fallback cooldown for provider quota exhaustion when the error states no
  * reset window (default 1h). A provider-specific rule (xAI Grok Build's
  * rolling 24-hour free-tier window) overrides it inside the classifier.
  */
 export function resolveAccountQuotaCooldownMs(): number {
-  if (_quotaCooldown === undefined)
-    _quotaCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS,
   );
-  return _quotaCooldown;
 }
 
-let _modelCapacityCooldown: number | undefined;
 /** Fallback cooldown for model-capacity overload (default 2m). */
 export function resolveAccountModelCapacityCooldownMs(): number {
-  if (_modelCapacityCooldown === undefined)
-    _modelCapacityCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS,
   );
-  return _modelCapacityCooldown;
 }
 
-let _transientCooldown: number | undefined;
 /** Backoff for a transient 5xx/network fault, recorded as `cooldown` (default 30s). */
 export function resolveAccountTransientCooldownMs(): number {
-  if (_transientCooldown === undefined)
-    _transientCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS,
   );
-  return _transientCooldown;
 }
 
-let _unclassifiedCooldown: number | undefined;
 /** Backoff for a failure no rule matched, recorded as `cooldown` (default 1m). */
 export function resolveAccountUnclassifiedCooldownMs(): number {
-  if (_unclassifiedCooldown === undefined)
-    _unclassifiedCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS,
   );
-  return _unclassifiedCooldown;
 }
 
 /**
@@ -71,25 +75,21 @@ export function resolveAccountUnclassifiedCooldownMs(): number {
  * window: an account that recovers on its own must not sit parked for a day
  * because a burst of 5xx happened to arrive while it was already cooling.
  */
-let _escalationMaxCooldown: number | undefined;
 export function resolveAccountCooldownEscalationMaxMs(): number {
-  if (_escalationMaxCooldown === undefined)
-    _escalationMaxCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS,
   );
-  return _escalationMaxCooldown;
 }
 
-let _poolCooldown: number | undefined;
 /** How long a proxy pool stays `cooldown` after a transport fault (default 2m). */
 export function resolvePoolCooldownMs(): number {
-  if (_poolCooldown === undefined)
-    _poolCooldown = readInt("CARTETHYIA_POOL_COOLDOWN_MS", CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS);
-  return _poolCooldown;
+  return cachedCooldownMs(
+    "CARTETHYIA_POOL_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS,
+  );
 }
 
-let _authRejectedCooldown: number | undefined;
 /**
  * Backoff for an auth rejection that names no revocation (default 5m).
  *
@@ -107,15 +107,12 @@ let _authRejectedCooldown: number | undefined;
  * rotation immediately, with no backoff to wait out.
  */
 export function resolveAccountAuthRejectedCooldownMs(): number {
-  if (_authRejectedCooldown === undefined)
-    _authRejectedCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS,
   );
-  return _authRejectedCooldown;
 }
 
-let _policyBlockCooldown: number | undefined;
 /**
  * Base backoff for the buddy policy/channel block (default 5m).
  *
@@ -132,15 +129,12 @@ let _policyBlockCooldown: number | undefined;
  * while a single bad prompt costs five minutes.
  */
 export function resolveAccountPolicyBlockCooldownMs(): number {
-  if (_policyBlockCooldown === undefined)
-    _policyBlockCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS,
   );
-  return _policyBlockCooldown;
 }
 
-let _disabledRecovery: number | undefined;
 /**
  * How long an **automatically** disabled account stays out of rotation (default 24h).
  *
@@ -160,27 +154,22 @@ let _disabledRecovery: number | undefined;
  * only reproduces the refusal. Set to `0` to make an automatic disable terminal.
  */
 export function resolveAccountDisabledRecoveryMs(): number {
-  if (_disabledRecovery === undefined)
-    _disabledRecovery = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS",
     CONFIG_SPEC.CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS,
   );
-  return _disabledRecovery;
 }
 
-let _poolProviderRateLimitCooldown: number | undefined;
 /**
  * Fallback cooldown for a provider-scoped egress 429 when the upstream named no
  * window (default 1h). See `CARTETHYIA_POOL_PROVIDER_RATE_LIMIT_COOLDOWN_MS`.
  * An upstream `retryAfterMs` always wins over this.
  */
 export function resolvePoolProviderRateLimitCooldownMs(): number {
-  if (_poolProviderRateLimitCooldown === undefined)
-    _poolProviderRateLimitCooldown = readInt(
+  return cachedCooldownMs(
     "CARTETHYIA_POOL_PROVIDER_RATE_LIMIT_COOLDOWN_MS",
     CONFIG_SPEC.CARTETHYIA_POOL_PROVIDER_RATE_LIMIT_COOLDOWN_MS,
   );
-  return _poolProviderRateLimitCooldown;
 }
 
 /**
@@ -188,15 +177,5 @@ export function resolvePoolProviderRateLimitCooldownMs(): number {
  * cooldown env-vars between test cases.
  */
 export function resetCooldownCacheForTests(): void {
-  _rateLimitCooldown = undefined;
-  _quotaCooldown = undefined;
-  _modelCapacityCooldown = undefined;
-  _transientCooldown = undefined;
-  _unclassifiedCooldown = undefined;
-  _escalationMaxCooldown = undefined;
-  _poolCooldown = undefined;
-  _poolProviderRateLimitCooldown = undefined;
-  _authRejectedCooldown = undefined;
-  _policyBlockCooldown = undefined;
-  _disabledRecovery = undefined;
+  cooldownCache.clear();
 }

package/src/config/network.ts

@@ -24,7 +24,7 @@ export type TrustedProxyMode = "disabled" | "trusted" | "platform";
  * naming CIDRs. It cannot be mistaken for an address, so the list form stays
  * unambiguous.
  */
-export const TRUSTED_PROXY_PLATFORM_TOKEN = "platform";
+const TRUSTED_PROXY_PLATFORM_TOKEN = "platform";
 
 /** Trusted reverse-proxy boundary used for forwarded client addresses. */
 export interface TrustedProxyBoundary {
@@ -111,10 +111,14 @@ export const DEFAULT_BOUNDS = {
    * the worker sweeps (`runGrowingWaves`, at most 5 concurrent), auth, and
    * readiness.
    *
-   * 20 leaves headroom over that without letting one process hold a large
+   * 16 leaves headroom over that without letting one process hold a large
    * share of the server's `max_connections` (Postgres defaults to 100), which
    * matters because the gateway is designed to run several processes behind
-   * `reusePort` — see `assertPoolFitsServerCapacity`.
+   * `reusePort` — see `assertPoolFitsServerCapacity`. With well-optimized
+   * queries a 16-connection pool sustains a hundred concurrent requests: the
+   * connections are held for microseconds per query, not for the whole
+   * request. If a burst still queues on the pool, fix the query/consumer
+   * that holds connections, rather than raising the ceiling.
    */
-  maxPostgresPoolSize: 8,
+  maxPostgresPoolSize: 16,
 } as const;

package/src/config/package-paths.ts

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
  * virtual `import.meta.dir`, so deployments can point this at the shipped
  * assets directory explicitly.
  */
-export function resolvePackageRoot(
+function resolvePackageRoot(
   moduleDir: string,
   configuredRoot: string | undefined,
 ): string {

package/src/config/providers.ts

@@ -4,20 +4,7 @@
  * public origin.
  */
 
-import { CONFIG_SPEC, readInt, readOptionalText, readRequired, readText } from "./spec";
-
-/** Reads and normalizes the public OAuth origin. */
-export function requirePublicOrigin(): string {
-  return readRequired("CARTETHYIA_PUBLIC_ORIGIN", CONFIG_SPEC.CARTETHYIA_PUBLIC_ORIGIN).replace(
-    /\/+$/,
-    "",
-  );
-}
-
-/** Builds the fixed OAuth callback URL for a provider id. */
-export function oauthCallbackUrl(providerId: string): string {
-  return `${requirePublicOrigin()}/console/api/providers/${providerId}/oauth/callback`;
-}
+import { CONFIG_SPEC, readInt, readOptionalText, readText } from "./spec";
 
 /**
  * Browser-authorize redirect URI for a provider.
@@ -103,3 +90,15 @@ export function resolveGithubEnterpriseDomain(): string {
     return "";
   }
 }
+
+/**
+ * How cached prompt tokens are accounted. Unknown values fall back to `real`
+ * so a typo cannot silently flip every provider to simplified accounting.
+ */
+export function resolveCacheMode(): "simplified" | "real" {
+  const raw = readText(
+    "CARTETHYIA_CACHE_MODE",
+    CONFIG_SPEC.CARTETHYIA_CACHE_MODE,
+  ).toLowerCase();
+  return raw === "simplified" ? "simplified" : "real";
+}

package/src/config/resources.ts

@@ -21,7 +21,6 @@ import { CONFIG_SPEC, readOptionalInt } from "./spec";
 /** Used when no limit is discoverable at all (native dev, macOS, Windows). */
 export const FALLBACK_MEMORY_LIMIT_BYTES = 512 * 1024 * 1024;
 
-
 /**
  * How many copies of a request body are resident at once.
  *
@@ -30,15 +29,12 @@ export const FALLBACK_MEMORY_LIMIT_BYTES = 512 * 1024 * 1024;
  * collection lags rather than keeping them to one. Budgeting one copy halves
  * the real peak and lets the process admit twice the concurrency it can hold.
  */
-export const REQUEST_BODY_TRANSIENT_COPIES = 2;
 
 /** Share of the memory limit all in-flight request bodies together may hold. */
-export const REQUEST_BODY_BUDGET_FRACTION = 0.25;
 
 /** Share of the memory limit kept free for allocation spikes and GC slack. */
 export const MEMORY_HEADROOM_FRACTION = 0.2;
 
-
 /**
  * Bytes kept free below the memory limit.
  *
@@ -51,7 +47,6 @@ export function deriveMemoryHeadroomBytes(memoryLimitBytes: number): number {
   return Math.ceil(memoryLimitBytes * MEMORY_HEADROOM_FRACTION);
 }
 
-
 /**
  * Slack added on top of every key's concurrency limit.
  *

package/src/config/runtime.ts

@@ -2,8 +2,7 @@
  * HTTP listener, dashboard runtime, and graceful-shutdown drain resolvers.
  */
 
-import { CONFIG_SPEC, readInt, readOptionalText } from "./spec";
-import { resolvePackagePath } from "./package-paths";
+import { CONFIG_SPEC, readInt, readOptionalText, readText } from "./spec";
 
 /** Resolves the HTTP listener port from the process environment. */
 export function resolvePort(): number {
@@ -12,9 +11,7 @@ export function resolvePort(): number {
 
 /** Resolves the dashboard static asset directory. */
 export function resolveDashboardDist(): string {
-  const raw = process.env.DASHBOARD_DIST?.trim();
-  if (!raw) return resolvePackagePath("dist", "dashboard");
-  return raw;
+  return readText("DASHBOARD_DIST", CONFIG_SPEC.DASHBOARD_DIST);
 }
 
 /**

package/src/config/spec.ts

@@ -297,6 +297,20 @@ export const CONFIG_SPEC = {
    * an operator on one has no other way to point the login at it.
    */
   CARTETHYIA_GITHUB_ENTERPRISE_DOMAIN: { kind: "text", default: "" },
+  // Only the literal true opts active ZCode accounts into daily gift claims.
+  CARTETHYIA_ZCODE_AUTO_CLAIM: { kind: "text", default: "false" },
+  /**
+   * How cached prompt tokens are accounted.
+   *
+   * - `simplified` (default): the request is cache-eligible when the provider
+   *   reports a cache hit (`cached_input_tokens > 0`); every input token is
+   *   then counted as cached. A reported `0` or an absent report are both a
+   *   cache miss and stay uncached.
+   * - `real`: the provider's reported cache numbers are kept as-is (the
+   *   pre-2.7.6 behavior). Use it when the exact per-provider split matters
+   *   more than a uniform hit-rate reading.
+   */
+  CARTETHYIA_CACHE_MODE: { kind: "text", default: "simplified" },
   /**
    * Free-tier OpenCode ids the listing still advertises but upstream refuses.
    * Replaces the bundled list outright; the single token `none` trusts the
@@ -330,8 +344,10 @@ export function readText(name: string, entry: TextConfigEntry): string {
 }
 
 /** Reads an optional string; empty or whitespace reads as absent. */
-export function readOptionalText(name: string, entry: OptionalTextConfigEntry): string | undefined {
-  void entry;
+export function readOptionalText(name: string, entry: ConfigEntry): string | undefined {
+  if (entry.kind !== "optional-text") {
+    throw new Error(`${name} must be declared optional-text in CONFIG_SPEC`);
+  }
   const raw = process.env[name]?.trim();
   return raw && raw.length > 0 ? raw : undefined;
 }
@@ -355,14 +371,18 @@ export function readRequired(name: string, entry: RequiredTextConfigEntry): stri
 }
 
 /** Reads a flag: enabled unless the literal `"false"` is set. */
-export function readFlag(name: string, entry: FlagConfigEntry): boolean {
-  void entry;
+export function readFlag(name: string, entry: ConfigEntry): boolean {
+  if (entry.kind !== "flag") {
+    throw new Error(`${name} must be declared flag in CONFIG_SPEC`);
+  }
   return process.env[name] !== "false";
 }
 
 /** Reads a comma-separated list, dropping empty entries. */
-export function readList(name: string, entry: ListConfigEntry): readonly string[] | undefined {
-  void entry;
+export function readList(name: string, entry: ConfigEntry): readonly string[] | undefined {
+  if (entry.kind !== "list") {
+    throw new Error(`${name} must be declared list in CONFIG_SPEC`);
+  }
   const entries = process.env[name]
     ?.split(",")
     .map((value) => value.trim())

package/src/console/api-keys/ban-constants.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure ban dropdown constants (reasons + durations), kept free of any `node:*`
+ * import so the dashboard can import them without evaluating Node-only modules.
+ *
+ * The dashboard mirrors these into its UI; the console API validates against
+ * the same lists. They used to live in `contracts.ts`, which also imports
+ * `hashSecret` (→ `security/crypto` → `node:crypto`) and `randomBytes` — so a
+ * browser bundle that imported any value from `contracts.ts` dragged the whole
+ * Node crypto chain along and blew up in the client (module externalized).
+ * Moving the pure lists here keeps one source of truth for the values while
+ * keeping the browser bundle clean.
+ */
+
+/** Ban reasons offered by the console dropdown. The first two are the operator's
+ * own: "Instant Ban — Suka suka Gw" for the arbitrary ban, and a template for
+ * suspicious traffic. The rest are generic, and an operator can still type a
+ * custom reason — the dropdown is a convenience, not a closed set. */
+export const API_KEY_BAN_REASONS: readonly { readonly value: string; readonly label: string }[] = [
+  { value: "instant_arbitrary", label: "Instant Ban — Suka suka Gw" },
+  { value: "traffic_suspicious", label: "Your traffic looks suspicious" },
+  { value: "abuse", label: "Abuse of the gateway" },
+  { value: "policy_violation", label: "Policy violation" },
+  { value: "compromised", label: "Key may be compromised" },
+  { value: "quota_exceeded", label: "Quota abused" },
+  { value: "other", label: "Other / custom" },
+] as const;
+
+/** Ban durations the console offers, in whole minutes. `null` is permanent.
+ * Mirrored by the dashboard (`dashboard/src/lib/ban-durations.ts`) so the UI
+ * and the API agree on one list. */
+export const BAN_DURATION_CHOICES: readonly { readonly minutes: number | null; readonly label: string }[] = [
+  { minutes: 60, label: "1 hour" },
+  { minutes: 6 * 60, label: "6 hours" },
+  { minutes: 12 * 60, label: "12 hours" },
+  { minutes: 24 * 60, label: "1 day" },
+  { minutes: 7 * 24 * 60, label: "7 days" },
+  { minutes: null, label: "Permanent" },
+] as const;