cartethyia 2.5.3 → 2.5.6

package/src/config/providers.ts

@@ -1,10 +1,10 @@
 /**
- * Provider-specific knobs config.ts formerly owned: Kimi OAuth/quota hosts,
- * the GitHub Enterprise domain for the Copilot device login, and the OAuth
- * callback URL builders built on the public origin.
+ * Provider-specific knobs: Kimi OAuth/quota hosts, the GitHub Enterprise domain
+ * for the Copilot device login, and the OAuth callback URL builders built on the
+ * public origin.
  */
 
-import { CONFIG_SPEC, readInt, readList, readRequired, readText } from "./spec";
+import { CONFIG_SPEC, readInt, readRequired, readText } from "./spec";
 
 /** Reads and normalizes the public OAuth origin. */
 export function requirePublicOrigin(): string {
@@ -64,14 +64,11 @@ export function resolveOpenCodeUnavailableFree():
   const raw = process.env.CARTETHYIA_OPENCODE_UNAVAILABLE_FREE?.trim();
   if (raw === undefined || raw === "") return undefined;
   if (raw.toLowerCase() === "none") return "none";
-  const parsed = readList(
-    "CARTETHYIA_OPENCODE_UNAVAILABLE_FREE",
-    CONFIG_SPEC.CARTETHYIA_OPENCODE_UNAVAILABLE_FREE,
-  );
-  // Separators only: readList drops the empties and yields nothing. Treating
+  // Separators only: dropping empties and yielding nothing. Treating
   // that as "trust everything" would un-block every refused model on a typo,
   // so it falls back to the bundled list instead.
-  return parsed === undefined || parsed.length === 0 ? undefined : parsed;
+  const entries = raw.split(",").map((v) => v.trim()).filter(Boolean);
+  return entries.length === 0 ? undefined : entries;
 }
 
 /**

package/src/config/runtime.ts

@@ -1,76 +1,76 @@
-/**
- * HTTP listener, dashboard runtime, and graceful-shutdown drain resolvers.
- */
-
-import { CONFIG_SPEC, readInt, readOptionalText, readText } from "./spec";
-import { resolvePackagePath } from "./package-paths";
-
-/** Resolves the HTTP listener port from the process environment. */
-export function resolvePort(): number {
-  return readInt("PORT", CONFIG_SPEC.PORT);
-}
-
-/** Resolves the dashboard static asset directory. */
-export function resolveDashboardDist(): string {
-  if (!process.env.DASHBOARD_DIST?.trim()) return resolvePackagePath("dist", "dashboard");
-  return readText("DASHBOARD_DIST", CONFIG_SPEC.DASHBOARD_DIST);
-}
-
-/**
- * Resolves the configured default gateway API key (`CARTETHYIA_API_KEY`), if
- * one is set. Consumers that need the raw secret — first-boot seeding and the
- * console's legacy-key recovery — read it here instead of probing
- * `process.env` directly.
- */
-export function resolveDefaultGatewayApiKey(): string | undefined {
-  return readOptionalText("CARTETHYIA_API_KEY", CONFIG_SPEC.CARTETHYIA_API_KEY);
-}
-
-/** Resolves the request-body ceiling shared by the Bun listener and ingress middleware. */
-export function resolveMaxBodyBytes(): number {
-  return readInt("CARTETHYIA_SERVER_MAX_BODY_BYTES", CONFIG_SPEC.CARTETHYIA_SERVER_MAX_BODY_BYTES);
-}
-
-/** Resolves the listener idle-socket timeout (seconds). */
-export function resolveIdleTimeout(): number {
-  return readInt("CARTETHYIA_SERVER_IDLE_TIMEOUT", CONFIG_SPEC.CARTETHYIA_SERVER_IDLE_TIMEOUT);
-}
-
-/** Resolves the graceful-shutdown drain window: time for in-flight requests to finish before abort. */
-export function resolveShutdownDrainWindowMs(): number {
-  return readInt(
-    "CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS",
-    CONFIG_SPEC.CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS,
-  );
-}
-
-/** Resolves the operator drain token, or `undefined` when the drain route is disabled. */
-export function resolveDrainToken(): string | undefined {
-  const raw = process.env.CARTETHYIA_DRAIN_TOKEN?.trim();
-  return raw !== undefined && raw.length > 0 ? raw : undefined;
-}
-
-/**
- * Whether Elysia precompiles route handlers at startup (AOT).
- *
- * Precompilation takes the eager validator branch, which calls TypeBox's
- * `SchemaCompile(schema)` and then reads `.buildResult.external` off the
- * result. In a source-run process that field is absent — the lazy
- * `require("typebox/schema")` resolves to a namespace that does not carry it —
- * and the process dies at the first schema-bearing route with
- * `undefined is not an object (evaluating 'this.tb.buildResult.external')`.
- * `scripts/binary/aot.ts` avoids this by rewriting the call site and bundling
- * the namespaces statically, so only the built artifact can actually take the
- * eager path.
- *
- * So: precompilation is on for production *builds*, and off for a source run
- * even when `NODE_ENV=production`. A deployment that runs
- * `bun run src/main.ts` must not be pushed onto the eager branch.
- *
- * `CARTETHYIA_SOURCE_RUN` marks a source run explicitly. It is set by
- * `scripts/deploy/*.sh`, which are the only supported way to run from source.
- */
-export function resolveElysiaPrecompile(): boolean {
-  if (process.env.CARTETHYIA_SOURCE_RUN === "1") return false;
-  return process.env.NODE_ENV === "production";
-}
+/**
+ * HTTP listener, dashboard runtime, and graceful-shutdown drain resolvers.
+ */
+
+import { CONFIG_SPEC, readInt, readOptionalText } from "./spec";
+import { resolvePackagePath } from "./package-paths";
+
+/** Resolves the HTTP listener port from the process environment. */
+export function resolvePort(): number {
+  return readInt("PORT", CONFIG_SPEC.PORT);
+}
+
+/** 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;
+}
+
+/**
+ * Resolves the configured default gateway API key (`CARTETHYIA_API_KEY`), if
+ * one is set. Consumers that need the raw secret — first-boot seeding and the
+ * console's key recovery from existing installations — read it here instead of
+ * probing `process.env` directly.
+ */
+export function resolveDefaultGatewayApiKey(): string | undefined {
+  return readOptionalText("CARTETHYIA_API_KEY", CONFIG_SPEC.CARTETHYIA_API_KEY);
+}
+
+/** Resolves the request-body ceiling shared by the Bun listener and ingress middleware. */
+export function resolveMaxBodyBytes(): number {
+  return readInt("CARTETHYIA_SERVER_MAX_BODY_BYTES", CONFIG_SPEC.CARTETHYIA_SERVER_MAX_BODY_BYTES);
+}
+
+/** Resolves the listener idle-socket timeout (seconds). */
+export function resolveIdleTimeout(): number {
+  return readInt("CARTETHYIA_SERVER_IDLE_TIMEOUT", CONFIG_SPEC.CARTETHYIA_SERVER_IDLE_TIMEOUT);
+}
+
+/** Resolves the graceful-shutdown drain window: time for in-flight requests to finish before abort. */
+export function resolveShutdownDrainWindowMs(): number {
+  return readInt(
+    "CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS",
+    CONFIG_SPEC.CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS,
+  );
+}
+
+/** Resolves the operator drain token, or `undefined` when the drain route is disabled. */
+export function resolveDrainToken(): string | undefined {
+  return readOptionalText("CARTETHYIA_DRAIN_TOKEN", CONFIG_SPEC.CARTETHYIA_DRAIN_TOKEN);
+}
+
+/**
+ * Whether Elysia precompiles route handlers at startup (AOT).
+ *
+ * Precompilation takes the eager validator branch, which calls TypeBox's
+ * `SchemaCompile(schema)` and then reads `.buildResult.external` off the
+ * result. In a source-run process that field is absent — the lazy
+ * `require("typebox/schema")` resolves to a namespace that does not carry it —
+ * and the process dies at the first schema-bearing route with
+ * `undefined is not an object (evaluating 'this.tb.buildResult.external')`.
+ * `scripts/build/aot.ts` avoids this by rewriting the call site and bundling
+ * the namespaces statically, so only the built artifact can actually take the
+ * eager path.
+ *
+ * So: precompilation is on for production *builds*, and off for a source run
+ * even when `NODE_ENV=production`. A deployment that runs
+ * `bun run src/main.ts` must not be pushed onto the eager branch.
+ *
+ * `CARTETHYIA_SOURCE_RUN` marks a source run explicitly. It is set by
+ * `scripts/deploy/*.sh`, which are the only supported way to run from source.
+ */
+export function resolveElysiaPrecompile(): boolean {
+  if (process.env.CARTETHYIA_SOURCE_RUN === "1") return false;
+  return process.env.NODE_ENV === "production";
+}

package/src/config/security.ts

@@ -37,6 +37,21 @@ export function resolveModelBanTtlMs(): number {
   return readInt("CARTETHYIA_MODEL_BAN_TTL_MS", CONFIG_SPEC.CARTETHYIA_MODEL_BAN_TTL_MS);
 }
 
+/**
+ * The longest model-abuse ban the console will record, however long a request
+ * asks for.
+ *
+ * A separate knob from the ban TTL because the two are different decisions:
+ * the TTL is what a graduated ban gets, this is the ceiling on what an
+ * operator may ask for by hand. Raising one was never meant to raise the other.
+ */
+export function resolveModelBanMaxTtlMs(): number {
+  return readInt(
+    "CARTETHYIA_MODEL_BAN_MAX_TTL_MS",
+    CONFIG_SPEC.CARTETHYIA_MODEL_BAN_MAX_TTL_MS,
+  );
+}
+
 /** Reads the application encryption key without caching it. */
 export function requireEncryptionKeyEnv(): string {
   return readRequired("CARTETHYIA_ENCRYPTION_KEY", CONFIG_SPEC.CARTETHYIA_ENCRYPTION_KEY);

package/src/config/spec.ts

@@ -148,7 +148,40 @@ export const CONFIG_SPEC = {
    */
   CARTETHYIA_DISABLED_TASKS: { kind: "list" },
 
+  /**
+   * How long a day's telemetry is kept, in days.
+   *
+   * The retention unit is the whole day: a day's event file and its index are
+   * deleted together, and the current day is never touched. Past this age an
+   * individual request no longer exists anywhere, so its detail is gone —
+   * totals, breakdowns and spend are unaffected, because the index keeps
+   * running sums rather than the rows.
+   *
+   * This is the knob that decides how long the request list, per-request
+   * filters, and the detail drawer stay complete.
+   */
   CARTETHYIA_TELEMETRY_RETENTION_DAYS: { kind: "int", default: 30, min: 3, max: 365 },
+  /**
+   * Age at which a request's detail is described as no longer stored.
+   *
+   * Retention itself is `CARTETHYIA_TELEMETRY_RETENTION_DAYS`; this only words
+   * the operator-facing message shown when a request that old is asked for.
+   */
+  CARTETHYIA_TELEMETRY_COMPACT_AFTER_DAYS: { kind: "int", default: 7, min: 1, max: 365 },
+  /**
+   * How often each day's index is brought up to date, in minutes.
+   *
+   * Bringing an index up to date means folding the bytes appended since the
+   * last pass — not re-reading the day. Reads fold before they answer too, so
+   * raising this does not make the numbers stale; it only leaves the on-disk
+   * index further behind, and the next read pays for the remainder.
+   */
+  CARTETHYIA_TELEMETRY_COMPACT_INTERVAL_MINUTES: {
+    kind: "int",
+    default: 60,
+    min: 5,
+    max: 1440,
+  },
   CARTETHYIA_TELEMETRY_PAYLOAD_MAX_BYTES: {
     kind: "int",
     default: 16 * 1024 * 1024,
@@ -191,10 +224,10 @@ export const CONFIG_SPEC = {
   /**
    * An unmapped upstream failure cools the account down for 15 minutes.
    *
-   * It used to be 60s, which put the account straight back into rotation and
-   * re-dialled an upstream that had just answered something this gateway does
-   * not understand — so the same unknown error was retried every minute, and
-   * an account that was actually broken contributed a steady stream of failed
+   * A shorter window puts the account straight back into rotation and re-dials
+   * an upstream that has just answered something this gateway does not
+   * understand — so the same unknown error is retried every minute, and an
+   * account that is actually broken contributes a steady stream of failed
    * attempts instead of one. Fifteen minutes is long enough for a transient
    * provider condition to clear on its own and short enough that no operator
    * action is needed to recover it. It is still a cooldown with a deadline,
@@ -224,6 +257,18 @@ export const CONFIG_SPEC = {
   CARTETHYIA_MODEL_STRIKE_THRESHOLD: { kind: "int", default: 10, min: 1, max: 100 },
   CARTETHYIA_MODEL_STRIKE_WINDOW_MS: { kind: "int", default: 1_800_000, min: 1_000, max: 86_400_000 },
   CARTETHYIA_MODEL_BAN_TTL_MS: { kind: "int", default: 21_600_000, min: 1_000, max: 604_800_000 },
+  /**
+   * The longest ban the console will record, however long a request asks for.
+   * The "Permanent" choice is a very long TTL rather than an unbounded one,
+   * and this is what keeps a typo in a duration from parking a caller for a
+   * decade.
+   */
+  CARTETHYIA_MODEL_BAN_MAX_TTL_MS: {
+    kind: "int",
+    default: 604_800_000,
+    min: 1_000,
+    max: 604_800_000,
+  },
   CARTETHYIA_ENCRYPTION_KEY: {
     kind: "required",
     error:
@@ -240,9 +285,9 @@ export const CONFIG_SPEC = {
   /**
    * Loopback port the browser-OAuth callback listener binds.
    *
-   * Configurable because the default is a fixed number and a busy port used to
-   * strand the operator: the login could not start and there was no way to move
-   * it. Codex's authorization server still expects 59653, so changing this
+   * Configurable because the default is a fixed number: a busy port would strand
+   * the operator, since the login could not start and there would be no way to
+   * move it. Codex's authorization server still expects 59653, so changing this
    * only helps the providers whose redirect URI is not allowlisted upstream.
    */
   CARTETHYIA_OAUTH_CALLBACK_PORT: { kind: "int", default: 59_653, min: 1_024, max: 65_535 },

package/src/config/telemetry.ts

@@ -19,3 +19,29 @@ export function resolveTelemetryPayloadMaxBytes(): number {
     CONFIG_SPEC.CARTETHYIA_TELEMETRY_PAYLOAD_MAX_BYTES,
   );
 }
+
+/**
+ * Age at which hourly telemetry files are compacted into a per-day summary.
+ *
+ * Clamped below the retention window: compacting at or past the delete age
+ * would fold a file and throw it away in the same pass, spending the read for
+ * totals that were about to be discarded.
+ */
+export function resolveTelemetryCompactAfterDays(): number {
+  const compacted = readInt(
+    "CARTETHYIA_TELEMETRY_COMPACT_AFTER_DAYS",
+    CONFIG_SPEC.CARTETHYIA_TELEMETRY_COMPACT_AFTER_DAYS,
+  );
+  return Math.min(compacted, resolveTelemetryRetentionDays());
+}
+
+/** Minutes between compaction passes. */
+export function resolveTelemetryCompactIntervalMs(): number {
+  const minutes = readInt(
+    "CARTETHYIA_TELEMETRY_COMPACT_INTERVAL_MINUTES",
+    CONFIG_SPEC.CARTETHYIA_TELEMETRY_COMPACT_INTERVAL_MINUTES,
+  );
+  return minutes * 60_000;
+}
+
+

package/src/config/timeouts.ts

@@ -51,12 +51,6 @@ let cachedUpstreamTimeoutMs: number | undefined;
 let cachedStreamStallTimeoutMs: number | undefined;
 let cachedInflightTtlSeconds: number | undefined;
 
-/** Clears the memoized timeout cache; tests that mutate env mid-process only. */
-export function resetTimeoutCacheForTests(): void {
-  cachedUpstreamTimeoutMs = undefined;
-  cachedStreamStallTimeoutMs = undefined;
-  cachedInflightTtlSeconds = undefined;
-}
 
 /**
  * Crash-recovery TTL, in seconds, for a distributed inflight slot.

package/src/console/admin/model-abuse/contracts.ts

@@ -1,16 +1,38 @@
-// Console surface for model-abuse bans: list active bans and lift one.
+// Console surface for model-abuse bans: list active bans, ban one, lift one.
 //
-// The strike layer (security/model-abuse.ts) bans a client address after
-// repeated invalid-model requests. A ban lapses on its own after its TTL, and
-// this is the escape hatch for lifting one early — a false positive (a shared
-// NAT, a client that genuinely mistyped) must be fixable without SQL. It is a
+// The strike layer (security/model-abuse.ts) bans a caller after repeated
+// invalid-model requests. A ban lapses on its own after its TTL, and this is
+// the escape hatch for lifting one early — a false positive (a shared NAT, a
+// client that genuinely mistyped) must be fixable without SQL. It is a
 // platform-admin surface: a ban is a security decision and the identity values
 // are cross-tenant.
 import type { AccessDecision } from "../../../security/access-control";
 import type { ModelStrikeService } from "../../../security/model-abuse";
 
+/**
+ * The ban durations the console offers, in whole minutes. `null` is the
+ * "Permanent" choice.
+ *
+ * Expressed in minutes rather than milliseconds because that is what an
+ * operator picks and what the label says — a millisecond constant here drifts
+ * from the copy the moment either changes.
+ */
+export const BAN_DURATION_CHOICES = [
+  { 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;
+
+/** The duration a bare "ban this user" click uses: the shortest one on offer. */
+export const DEFAULT_BAN_MINUTES = 60;
+
+/** Whole minutes the console accepts, or `null` for permanent. */
+export type BanDurationMinutes = (typeof BAN_DURATION_CHOICES)[number]["minutes"];
+
 export interface ModelAbuseRoutesConfig {
   readonly strikes: Pick<ModelStrikeService, "listBans" | "unban" | "ban">;
   readonly accessResolver: (request: Request) => AccessDecision | undefined;
 }
-

package/src/console/admin/model-abuse/routes.ts

@@ -1,16 +1,64 @@
 import { Elysia, t } from "elysia";
-import type { ModelAbuseBan } from "../../../security/model-abuse";
+import { PERMANENT_BAN_TTL_MS, type ModelAbuseBan } from "../../../security/model-abuse";
 import { ConsoleDomainError, errorResponse, requireGlobalAdmin } from "../../shared/errors";
-import type { ModelAbuseRoutesConfig } from "./contracts";
+import {
+  BAN_DURATION_CHOICES,
+  DEFAULT_BAN_MINUTES,
+  type ModelAbuseRoutesConfig,
+} from "./contracts";
 
 const unbanBody = t.Object({
+  /** The opaque member the listing reports, so a scoped ban lifts exactly it. */
   identity: t.String({ minLength: 1 }),
 });
 
 const banBody = t.Object({
   ip: t.String({ minLength: 1, maxLength: 45 }),
+  /**
+   * The key this ban is scoped to. Omitted or null is the blunt instrument:
+   * every key used from this address. That is a real choice an operator makes
+   * when the address is the problem, not a fallback for a missing value — so it
+   * is explicit in the body rather than inferred from an empty string.
+   */
+  apiKeyId: t.Optional(t.Union([t.String({ minLength: 1 }), t.Null()])),
+  /** Whole minutes, or null for permanent. Default one hour. */
+  minutes: t.Optional(t.Union([t.Number({ minimum: 1 }), t.Null()])),
+  /**
+   * Bans the address outright, whatever `apiKeyId` says. Kept as its own flag
+   * so "no key supplied" cannot quietly widen into "every key" — the two read
+   * the same in a body that only had the one field.
+   */
+  addressOnly: t.Optional(t.Boolean()),
 });
 
+/** The durations the route accepts, as whole minutes. `null` is permanent. */
+const ALLOWED_MINUTES = new Set<number | null>(
+  BAN_DURATION_CHOICES.map((choice) => choice.minutes),
+);
+
+/**
+ * How long a requested ban lasts, in milliseconds.
+ *
+ * `null` means permanent, which is a very long TTL rather than an unbounded
+ * ban: both stores lapse a ban by comparing an expiry to now, so a genuinely
+ * infinite ban would need a second mechanism and a second way to get it wrong.
+ *
+ * Anything not on the offered list is rejected rather than clamped. Clamping
+ * would answer a request for 90 days with a week and report success, and an
+ * operator who asked for the longer ban would believe they got it.
+ */
+function banTtlMs(minutes: number | null | undefined): number {
+  const chosen = minutes === undefined ? DEFAULT_BAN_MINUTES : minutes;
+  if (!ALLOWED_MINUTES.has(chosen)) {
+    throw new ConsoleDomainError(
+      "invalid_request",
+      400,
+      "Unsupported ban duration. Choose one of the offered durations.",
+    );
+  }
+  return chosen === null ? PERMANENT_BAN_TTL_MS : chosen * 60_000;
+}
+
 export function createModelAbuseRoutes(config: ModelAbuseRoutesConfig): Elysia {
   return new Elysia()
     .get("/model-bans", async ({ request, set }) => {
@@ -25,7 +73,12 @@ export function createModelAbuseRoutes(config: ModelAbuseRoutesConfig): Elysia {
     .post("/model-bans", { body: banBody }, async ({ request, body, set }) => {
       try {
         requireGlobalAdmin(config.accessResolver(request));
-        const ban = await config.strikes.ban(body.ip);
+        const ban = await config.strikes.ban({
+          ip: body.ip,
+          ...(body.apiKeyId === undefined ? {} : { apiKeyId: body.apiKeyId }),
+          ttlMs: banTtlMs(body.minutes),
+          ...(body.addressOnly === undefined ? {} : { addressOnly: body.addressOnly }),
+        });
         return { ban };
       } catch (e) {
         return errorResponse(e, set, "Model ban failed");

package/src/console/api-keys/bucket-spend.ts

@@ -2,7 +2,7 @@ import { eq } from "drizzle-orm";
 
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { apiKeys } from "../../persistence/schema";
-import { queryTelemetryEvents } from "../../observability/event-log";
+import { queryIndexedBuckets } from "../../observability/event-day-index";
 import { utcDayStart, utcMonthStart } from "../shared/day";
 
 /**
@@ -33,9 +33,20 @@ export async function familyBucketSpend(
     .where(eq(apiKeys.parentKeyId, keyId));
   const keyIds = [keyId, ...children.map((child) => child.id)];
   const spentSince = async (start: Date): Promise<number> => {
-    const events = await queryTelemetryEvents({ apiKeyIds: keyIds, since: start });
-    return events
-      .reduce((sum, event) => sum + (event.inputTokens ?? 0) + (event.outputTokens ?? 0), 0);
+    // Folded first, so the index covers every event written so far including the
+    // current day's — then read from the index alone.
+    //
+    // Deliberately not index *plus* events: they hold the same requests, and
+    // adding them doubled every bucket. Folding first is what makes the index
+    // sufficient on its own; the watermark is the point up to which it is
+    // complete.
+    const allowed = new Set(keyIds);
+    const indexed = await queryIndexedBuckets({ since: start, foldFirst: true }).catch(
+      () => [],
+    );
+    return indexed
+      .filter((bucket) => bucket.apiKeyId !== null && allowed.has(bucket.apiKeyId))
+      .reduce((sum, bucket) => sum + bucket.inputTokens + bucket.outputTokens, 0);
   };
   const [daily, monthly] = await Promise.all([
     spentSince(utcDayStart(now)),