cartethyia 2.7.4 → 2.7.6

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 {

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,21 @@ export function resolveGithubEnterpriseDomain(): string {
     return "";
   }
 }
+
+export type GithubCopilotMode = "opencode-copilot" | "vscode-client-real";
+
+/**
+ * Which GitHub Copilot wire identity the adapter uses. Defaults to
+ * `opencode-copilot` (raw GitHub OAuth token + minimal OpenCode headers),
+ * which is the proven-most-stable path (one token, no mint expiry). The
+ * `vscode-client-real` mode matches the VS Code reference client exactly but
+ * requires a freshly minted Copilot token.
+ */
+export function resolveGithubCopilotMode(): GithubCopilotMode {
+  const raw = readText(
+    "CARTETHYIA_GITHUB_COPILOT_MODE",
+    CONFIG_SPEC.CARTETHYIA_GITHUB_COPILOT_MODE,
+  ).trim().toLowerCase();
+  if (raw === "vscode-client-real") return "vscode-client-real";
+  return "opencode-copilot";
+}

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

@@ -188,6 +188,13 @@ export const CONFIG_SPEC = {
     min: 1 * 1024 * 1024,
     max: 16 * 1024 * 1024,
   },
+  // Input-token accounting for usage display. Providers disagree on whether
+  // `input_tokens` already includes cached tokens: OpenAI/DeepSeek report the
+  // inclusive total with a cached subset, while Anthropic reports fresh-only
+  // with cache reads separate. `inclusive` (default) folds cache into input so
+  // every provider reads alike — IN is always the whole prompt and CACHED its
+  // subset. `as-is` keeps the raw upstream semantics.
+  CARTETHYIA_USAGE_INPUT_MODE: { kind: "text", default: "inclusive" },
 
   // Upstream request timeout + retry backoff
   //
@@ -297,6 +304,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: "" },
+  /**
+   * Which wire identity the GitHub Copilot Auto/chat path presents to the
+   * upstream:
+   *
+   * - `opencode-copilot` (default): the long-lived GitHub OAuth token + minimal
+   *   OpenCode headers. One token, no mint step, no short-lived minted-token
+   *   expiry. This is the most stable in practice.
+   * - `vscode-client-real`: a freshly minted Copilot token + the full VS Code
+   *   reference headers. Matches the VS Code client exactly, but requires the
+   *   minted token (expires ~25 min) and the reference identity.
+   */
+  CARTETHYIA_GITHUB_COPILOT_MODE: { kind: "text", default: "opencode-copilot" },
+  // Only the literal true opts active ZCode accounts into daily gift claims.
+  CARTETHYIA_ZCODE_AUTO_CLAIM: { kind: "text", default: "false" },
   /**
    * Free-tier OpenCode ids the listing still advertises but upstream refuses.
    * Replaces the bundled list outright; the single token `none` trusts the
@@ -330,8 +351,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 +378,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/config/usage.ts

@@ -0,0 +1,27 @@
+/**
+ * Usage input-token accounting mode.
+ *
+ * Providers disagree on whether `input_tokens` already includes cached tokens.
+ * OpenAI/DeepSeek report the inclusive total with a cached subset; Anthropic
+ * reports fresh-only with cache reads (and writes) separate. `normalizeUsage`
+ * reads this mode to decide whether to fold cache into input so every provider
+ * reads alike (`inclusive`, the default) or to keep the raw upstream semantics
+ * (`as-is`).
+ */
+
+import { CONFIG_SPEC, readText } from "./spec";
+
+export type UsageInputMode = "inclusive" | "as-is";
+
+/** Resolves the operator's chosen accounting mode; defaults to inclusive. */
+export function resolveUsageInputMode(): UsageInputMode {
+  const raw = readText(
+    "CARTETHYIA_USAGE_INPUT_MODE",
+    CONFIG_SPEC.CARTETHYIA_USAGE_INPUT_MODE,
+  )
+    .trim()
+    .toLowerCase();
+  if (raw === "inclusive") return "inclusive";
+  if (raw === "as-is") return "as-is";
+  throw new Error('CARTETHYIA_USAGE_INPUT_MODE must be "inclusive" or "as-is"');
+}

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;