cartethyia 2.7.3 → 2.7.5

package/src/persistence/stores/api-key-store.ts

@@ -1,11 +1,11 @@
 // Persisted API-key store: the console API-key domain and gateway authentication both consume this boundary.
 
-import { and, asc, count, desc, eq, inArray, isNotNull, isNull, sql } from "drizzle-orm";
+import { and, asc, count, desc, eq, inArray, isNotNull, isNull, lte, or, sql, type SQL } from "drizzle-orm";
 import { nextSortIndex, reorderSortIndex, type SortOrderDb } from "../sort-order";
 import { getDbHandle } from "../boot";
 import type { CartethyiaDatabase } from "../db-handle";
 import { lockRows } from "../dialect";
-import { apiKeys, shareLinks, sharePopups, telemetryUsageTotals, type ApiKeyMode, type ApiKeyModelAccessMode } from "../schema";
+import { apiKeys, shareLinks, sharePopups, telemetryUsageTotals, type ApiKeyMode, type ApiKeyModelAccessMode, type ApiKeyConcurrencyScope } from "../schema";
 import type { AccessScope } from "../../security/access-control";
 
 /** Sortable columns for the paged share-child listing (api_keys columns only). */
@@ -34,6 +34,18 @@ export interface SharedChildrenPage {
   readonly consumed: number;
 }
 
+/**
+ * SQL predicate: the key is not under an active ban. A ban is active while
+ * `banned_at` is set AND either `banned_until` is null (permanent) or still in
+ * the future — so a timed ban lapses on its own without a sweep.
+ */
+function notBannedSql(): SQL {
+  return or(
+    isNull(apiKeys.bannedAt),
+    and(isNotNull(apiKeys.bannedUntil), lte(apiKeys.bannedUntil, new Date())),
+  ) as SQL;
+}
+
 /** Persisted API key. Only its one-way hash authenticates; plaintext is never stored. */
 export interface ApiKeyRecord {
   readonly id: string;
@@ -66,6 +78,7 @@ export interface ApiKeyRecord {
   readonly monthlyTokenLimit?: number;
   readonly lifetimeTokenBudget?: number;
   readonly maxConcurrentRequests?: number;
+  readonly concurrencyScope?: ApiKeyConcurrencyScope;
   /** Share-template recipient slot cap; undefined = unlimited. */
   readonly maxChildren?: number;
   readonly modelPrefix?: string;
@@ -75,6 +88,11 @@ export interface ApiKeyRecord {
   readonly clientRouterDenylist?: readonly string[];
   readonly createdAt: Date;
   readonly revokedAt?: Date;
+  /** Ban state; see the schema column for the contract. */
+  readonly bannedAt?: Date;
+  readonly banReason?: string;
+  /** When the ban lifts on its own; null means permanent. */
+  readonly bannedUntil?: Date;
   readonly tokensConsumed: number;
 }
 
@@ -128,6 +146,9 @@ export interface ApiKeyPatch
     | "lifetimeTokenBudget"
     | "maxConcurrentRequests"
     | "maxChildren"
+    | "bannedAt"
+    | "banReason"
+    | "bannedUntil"
   > {
   readonly keyHash?: string | null;
   readonly keyEncrypted?: Buffer | null;
@@ -147,6 +168,11 @@ export interface ApiKeyPatch
   readonly lifetimeTokenBudget?: number | null;
   readonly maxConcurrentRequests?: number | null;
   readonly maxChildren?: number | null;
+  /** Ban state; a ban also disables the key, unban clears both columns entirely. */
+  readonly bannedAt?: Date | null;
+  readonly banReason?: string | null;
+  /** When the ban lifts on its own; null (explicit) means permanent. */
+  readonly bannedUntil?: Date | null;
 }
 
 interface PopupFields {
@@ -247,6 +273,20 @@ export interface ApiKeyStore {
   reorder(tenantId: string, keyIds: readonly string[]): Promise<void>;
   update(tenantId: string, keyId: string, patch: ApiKeyPatch): Promise<ApiKeyRecord | undefined>;
   revoke(tenantId: string, keyId: string, revokedAt: Date): Promise<boolean>;
+  /**
+   * Bans a key: records the operator's reason and (optionally) an expiry.
+   * `bannedUntil` null means permanent; absent defaults the the caller's
+   * choice. Returns false when the key is already revoked (a revoke is
+   * terminal).
+   */
+  ban(
+    tenantId: string,
+    keyId: string,
+    reason: string,
+    bannedUntil?: Date | null,
+  ): Promise<boolean>;
+  /** Unbans a key: clears the ban columns entirely — no metadata remains. */
+  unban(tenantId: string, keyId: string): Promise<boolean>;
   remove(tenantId: string, keyId: string): Promise<boolean>;
   findActiveByHash?(hash: string): Promise<typeof apiKeys.$inferSelect | undefined>;
   findActiveById?(keyId: string): Promise<typeof apiKeys.$inferSelect | undefined>;
@@ -305,6 +345,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       ...(row.maxConcurrentRequests === null
         ? {}
         : { maxConcurrentRequests: row.maxConcurrentRequests }),
+      ...(row.concurrencyScope
+        ? { concurrencyScope: row.concurrencyScope as ApiKeyConcurrencyScope }
+        : {}),
       ...(row.maxChildren === null ? {} : { maxChildren: row.maxChildren }),
       ...(row.modelPrefix === null ? {} : { modelPrefix: row.modelPrefix }),
       modelAccessMode: row.modelAccessMode,
@@ -314,6 +357,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
         : { clientRouterDenylist: row.clientRouterDenylist as string[] }),
       createdAt: row.createdAt,
       ...(row.revokedAt ? { revokedAt: row.revokedAt } : {}),
+      ...(row.bannedAt ? { bannedAt: row.bannedAt } : {}),
+      ...(row.banReason ? { banReason: row.banReason } : {}),
+      ...(row.bannedUntil ? { bannedUntil: row.bannedUntil } : {}),
       tokensConsumed: row.lifetimeTokensConsumed,
     };
   }
@@ -505,6 +551,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       monthlyTokenLimit: record.monthlyTokenLimit ?? null,
       lifetimeTokenBudget: record.lifetimeTokenBudget ?? null,
       maxConcurrentRequests: record.maxConcurrentRequests ?? null,
+      concurrencyScope: record.concurrencyScope ?? "family",
       maxChildren: record.maxChildren ?? null,
       modelPrefix: record.modelPrefix ?? null,
       modelAccessMode: record.modelAccessMode ?? "whitelist",
@@ -573,6 +620,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
           ...(patch.maxConcurrentRequests !== undefined
             ? { maxConcurrentRequests: patch.maxConcurrentRequests }
             : {}),
+          ...(patch.concurrencyScope !== undefined
+            ? { concurrencyScope: patch.concurrencyScope }
+            : {}),
           ...(patch.maxChildren !== undefined ? { maxChildren: patch.maxChildren } : {}),
           ...(patch.modelPrefix !== undefined ? { modelPrefix: patch.modelPrefix } : {}),
           ...(patch.modelAccessMode !== undefined ? { modelAccessMode: patch.modelAccessMode } : {}),
@@ -586,6 +636,8 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
           // silently dropped — a grant like `routing:cli_mapping` can be
           // turned on and never stick.
           ...(patch.scopes === undefined ? {} : { scopes: patch.scopes }),
+          ...(patch.bannedAt !== undefined ? { bannedAt: patch.bannedAt } : {}),
+          ...(patch.banReason !== undefined ? { banReason: patch.banReason } : {}),
         })
         .where(and(eq(apiKeys.tenantId, tenantId), eq(apiKeys.id, keyId)))
         .returning();
@@ -622,6 +674,55 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       return true;
     });
   }
+
+  async ban(
+    tenantId: string,
+    keyId: string,
+    reason: string,
+    bannedUntil?: Date | null,
+  ): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      const rows = await tx
+        .update(apiKeys)
+        .set({
+          bannedAt: new Date(),
+          banReason: reason,
+          // `banned_until` null = permanent. The key stays `enabled` as-is:
+          // the auth path refuses a banned key while `banned_at` is set and
+          // `banned_until` is null or future, so a timed ban lapses on its own
+          // without a sweep flipping `enabled` back.
+          ...(bannedUntil === undefined ? {} : { bannedUntil }),
+        })
+        .where(
+          and(
+            eq(apiKeys.tenantId, tenantId),
+            eq(apiKeys.id, keyId),
+            isNull(apiKeys.revokedAt),
+          ),
+        )
+        .returning({ id: apiKeys.id });
+      return rows.length > 0;
+    });
+  }
+
+  async unban(tenantId: string, keyId: string): Promise<boolean> {
+    return this.db.transaction(async (tx) => {
+      // Unban clears all three ban columns entirely — no tombstone, no leftover
+      // reason, no stale expiry. The key returns to its prior enabled state.
+      const rows = await tx
+        .update(apiKeys)
+        .set({ bannedAt: null, banReason: null, bannedUntil: null, enabled: true })
+        .where(
+          and(
+            eq(apiKeys.tenantId, tenantId),
+            eq(apiKeys.id, keyId),
+            isNull(apiKeys.revokedAt),
+          ),
+        )
+        .returning({ id: apiKeys.id });
+      return rows.length > 0;
+    });
+  }
   async remove(tenantId: string, keyId: string): Promise<boolean> {
     return this.db.transaction(async (tx) => {
       const rows = await tx
@@ -647,7 +748,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
     const rows = await this.db
       .select()
       .from(apiKeys)
-      .where(and(eq(apiKeys.keyHash, hash), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt)))
+      .where(and(eq(apiKeys.keyHash, hash), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt), notBannedSql()))
       .limit(1);
     return rows[0];
   }
@@ -658,7 +759,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
     const rows = await this.db
       .select()
       .from(apiKeys)
-      .where(and(eq(apiKeys.id, keyId), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt)))
+      .where(and(eq(apiKeys.id, keyId), eq(apiKeys.enabled, true), isNull(apiKeys.revokedAt), notBannedSql()))
       .limit(1);
     return rows[0];
   }
@@ -709,6 +810,7 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       lifetimeTokenBudget: integer("lifetime_token_budget"),
       lifetimeTokensConsumed: integer("lifetime_tokens_consumed") ?? 0,
       maxConcurrentRequests: integer("max_concurrent_requests"),
+      concurrencyScope: (text("concurrency_scope") ?? "family") as ApiKeyConcurrencyScope,
       modelAccessMode: (text("model_access_mode") ?? "whitelist") as ApiKeyModelAccessMode,
       modelList: json("model_list"),
       clientRouterDenylist: json("client_router_denylist"),
@@ -716,6 +818,9 @@ export class DrizzleApiKeyStore implements ApiKeyStore {
       createdAt: date("created_at") ?? new Date(0),
       enabled: flag("enabled"),
       revokedAt: date("revoked_at"),
+      bannedAt: date("banned_at"),
+      banReason: text("ban_reason"),
+      bannedUntil: date("banned_until"),
       keyPrefix: text("key_prefix"),
       keyEncrypted: raw["key_encrypted"] ?? null,
       notesTitle: text("notes_title"),

package/src/persistence/stores/share-store.ts

@@ -7,7 +7,7 @@ import { createHash, randomBytes, randomInt } from "node:crypto";
 import { and, desc, eq, isNull, or, sql, type SQL } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../db-handle";
 import { lockRows } from "../dialect";
-import { apiKeys, shareLinks, sharePopups, type ShareLinkKind, type ApiKeyModelAccessMode } from "../schema";
+import { apiKeys, shareLinks, sharePopups, type ShareLinkKind, type ApiKeyModelAccessMode, type ApiKeyConcurrencyScope } from "../schema";
 
 /** Hashes a share bearer token for storage and lookup. */
 /**
@@ -38,7 +38,7 @@ function addressMatches(address: string): SQL {
 }
 
 /** Newly created share-link metadata. */
-export interface ShareLinkRecord {
+interface ShareLinkRecord {
   readonly id: string;
   readonly apiKeyId: string;
   readonly kind: ShareLinkKind;
@@ -61,7 +61,7 @@ export interface ShareLinkSummary {
 }
 
 /** A stable link's encrypted token, or null when it predates token retention. */
-export interface ShareLinkToken {
+interface ShareLinkToken {
   readonly id: string;
   readonly apiKeyId: string;
   readonly kind: ShareLinkKind;
@@ -86,6 +86,7 @@ export interface ShareLinkPolicy {
   readonly monthlyTokenLimit: number | null;
   readonly lifetimeTokenBudget: number | null;
   readonly maxConcurrentRequests: number | null;
+  readonly concurrencyScope: ApiKeyConcurrencyScope;
   readonly modelAccessMode: ApiKeyModelAccessMode | null;
   readonly modelList: readonly string[] | null;
   readonly modelPrefix: string | null;
@@ -102,13 +103,13 @@ export interface ShareLinkPolicy {
 }
 
 /** Public template fields authorized for a valid enrollment-link lookup. */
-export interface ShareApiKeyRow extends ShareLinkPolicy {
+interface ShareApiKeyRow extends ShareLinkPolicy {
   readonly active: boolean;
   readonly createdAt: string;
 }
 
 /** A personal key revealed by its handoff link. */
-export interface ShareHandoffRow extends ShareLinkPolicy {
+interface ShareHandoffRow extends ShareLinkPolicy {
   /** Encrypted personal credential; null when the row predates secret storage. */
   readonly keyEncrypted: Buffer | null;
 }
@@ -118,7 +119,7 @@ export interface ShareHandoffRow extends ShareLinkPolicy {
  * public lookup answers with a discriminated result instead of the caller
  * guessing which endpoint to try.
  */
-export type ShareLinkResolution =
+type ShareLinkResolution =
   | { readonly kind: "enroll"; readonly key: ShareApiKeyRow }
   | { readonly kind: "handoff"; readonly key: ShareHandoffRow };
 
@@ -136,7 +137,7 @@ export type ShareLinkOutcome =
   | { readonly ok: true; readonly resolution: ShareLinkResolution }
   | { readonly ok: false; readonly refusal: ShareLinkRefusal };
 
-export interface SharedApiKeyMaterial {
+interface SharedApiKeyMaterial {
   readonly keyHash: string;
   readonly keyPrefix: string;
   readonly clientIp: string;
@@ -145,7 +146,7 @@ export interface SharedApiKeyMaterial {
   readonly nameHint?: string;
 }
 
-export type SharedApiKeyIssueResult =
+type SharedApiKeyIssueResult =
   | {
       readonly kind: "issued";
       readonly apiKeyId: string;
@@ -185,6 +186,7 @@ function mapShareRow(key: ApiKeyRow, link: ShareLinkRow, popup?: PopupRow): Shar
     monthlyTokenLimit: key.monthlyTokenLimit,
     lifetimeTokenBudget: key.lifetimeTokenBudget,
     maxConcurrentRequests: key.maxConcurrentRequests,
+    concurrencyScope: key.concurrencyScope ?? "family",
     modelAccessMode: key.modelAccessMode as ApiKeyModelAccessMode | null,
     modelList: key.modelList as readonly string[] | null,
     modelPrefix: key.modelPrefix,
@@ -213,6 +215,7 @@ function mapHandoffRow(key: ApiKeyRow, link: ShareLinkRow, popup?: PopupRow): Sh
     monthlyTokenLimit: key.monthlyTokenLimit,
     lifetimeTokenBudget: key.lifetimeTokenBudget,
     maxConcurrentRequests: key.maxConcurrentRequests,
+    concurrencyScope: key.concurrencyScope ?? "family",
     modelAccessMode: key.modelAccessMode as ApiKeyModelAccessMode | null,
     modelList: key.modelList as readonly string[] | null,
     modelPrefix: key.modelPrefix,
@@ -557,6 +560,12 @@ export class DrizzleShareLinkStore implements ShareLinkStore {
       // Nullable policy columns stay NULL; `model_access_mode` takes its
       // NOT NULL default ('whitelist'). Keep in sync with migration 0029 and
       // `normalizeShareChildPolicy` in `src/console/backup/store.ts`.
+      //
+      // Exception: a template with `concurrencyScope: "per_key"` lets each
+      // recipient carry its own concurrency cap, so the cap is copied to the
+      // child at issue (the child's admission identity is its own id, not the
+      // parent's). The `family` default keeps child caps NULL — they inherit
+      // the parent's cap through auth.
       const [child] = await tx
         .insert(apiKeys)
         .values({
@@ -571,6 +580,9 @@ export class DrizzleShareLinkStore implements ShareLinkStore {
           keyPrefix: material.keyPrefix,
           keyEncrypted: null,
           lifetimeTokensConsumed: 0,
+          ...(parent.concurrencyScope === "per_key"
+            ? { concurrencyScope: "per_key" as const, maxConcurrentRequests: parent.maxConcurrentRequests }
+            : {}),
         })
         .returning({ id: apiKeys.id, tenantId: apiKeys.tenantId, createdAt: apiKeys.createdAt });
       if (!child) throw new Error("shared API-key insert returned no row");

package/src/persistence/stores/telemetry-store.ts

@@ -55,7 +55,7 @@ function addUsageDelta(
   delta.outputTokens += row.outputTokens ?? 0;
 }
 
-function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
+export function aggregateUsage(rows: readonly (typeof telemetryEvents.$inferInsert)[]) {
   const deltas = new Map<string, UsageTotalDelta>();
   for (const row of rows) {
     addUsageDelta(deltas, row, "account", row.accountId);

package/src/persistence/system-prompt-store.ts

@@ -7,15 +7,20 @@ import { eq } from "drizzle-orm";
 import type { CartethyiaDatabase } from "./db-handle";
 import { tenantSystemPrompts } from "./schema";
 import type {
-  ProviderPromptEntry,
-  PromptSetting,
+  ScopePromptRef,
+  SystemPromptPreset,
   TenantSystemPrompts,
 } from "../console/system-prompt/contracts";
 import {
   EMPTY_TENANT_SYSTEM_PROMPTS,
+  SYSTEM_PROMPT_ALIAS_LIMIT,
+  SYSTEM_PROMPT_COMBO_LIMIT,
   SYSTEM_PROMPT_MODEL_LIMIT,
+  SYSTEM_PROMPT_PRESET_LIMIT,
   SYSTEM_PROMPT_PROVIDER_LIMIT,
   isPromptSetting,
+  isScopePromptRef,
+  isSystemPromptPreset,
   parseSystemPromptModelKey,
 } from "../console/system-prompt/contracts";
 import { bumpSettingsRevision } from "./settings-revision";
@@ -23,6 +28,24 @@ import { bumpSettingsRevision } from "./settings-revision";
 /** The stored row, normalized. Absent row reads as the empty configuration. */
 export type StoredTenantSystemPrompts = TenantSystemPrompts;
 
+/**
+ * Normalizes one scope reference value. Accepts the new `{ kind, ... }` shape
+ * and the legacy per-provider entry shape (`{ followGlobal, setting? }`) so a
+ * hand-edited or pre-migration row stays valid. Invalid values become
+ * `undefined` (the caller drops the key).
+ */
+function normalizeScopeRef(value: unknown, legacyProviderEntry?: boolean): ScopePromptRef | undefined {
+  if (isScopePromptRef(value)) return value;
+  if (legacyProviderEntry && typeof value === "object" && value !== null) {
+    const candidate = value as { followGlobal?: unknown; setting?: unknown };
+    if (candidate.followGlobal === true) return { kind: "global" };
+    if (candidate.followGlobal === false && isPromptSetting(candidate.setting)) {
+      return { kind: "custom", setting: candidate.setting };
+    }
+  }
+  return undefined;
+}
+
 /**
  * Reads the tenant's stored configuration, defensively normalized: a
  * hand-edited or legacy row must not poison the dispatch path, so malformed
@@ -35,8 +58,11 @@ export async function readTenantSystemPrompts(
   const rows = await db
     .select({
       global: tenantSystemPrompts.global,
+      presets: tenantSystemPrompts.presets,
       providers: tenantSystemPrompts.providers,
       models: tenantSystemPrompts.models,
+      combos: tenantSystemPrompts.combos,
+      aliases: tenantSystemPrompts.aliases,
     })
     .from(tenantSystemPrompts)
     .where(eq(tenantSystemPrompts.tenantId, tenantId))
@@ -44,30 +70,43 @@ export async function readTenantSystemPrompts(
   const row = rows[0];
   if (row === undefined) return EMPTY_TENANT_SYSTEM_PROMPTS;
 
-  const providers: Record<string, ProviderPromptEntry> = {};
-  for (const [providerId, entry] of Object.entries(row.providers ?? {})) {
-    if (typeof entry !== "object" || entry === null) continue;
-    const candidate = entry as Partial<ProviderPromptEntry>;
-    if (typeof candidate.followGlobal !== "boolean") continue;
-    if (candidate.followGlobal === false) {
-      if (!isPromptSetting(candidate.setting)) continue;
-      providers[providerId] = { followGlobal: false, setting: candidate.setting };
-    } else {
-      providers[providerId] = { followGlobal: true };
-    }
+  const presets: Record<string, SystemPromptPreset> = {};
+  for (const [id, preset] of Object.entries(row.presets ?? {})) {
+    if (isSystemPromptPreset(preset) && preset.id === id) presets[id] = preset;
   }
 
-  const models: Record<string, PromptSetting> = {};
-  for (const [key, setting] of Object.entries(row.models ?? {})) {
+  const providers: Record<string, ScopePromptRef> = {};
+  for (const [providerId, value] of Object.entries(row.providers ?? {})) {
+    const ref = normalizeScopeRef(value, true);
+    if (ref !== undefined) providers[providerId] = ref;
+  }
+
+  const models: Record<string, ScopePromptRef> = {};
+  for (const [key, value] of Object.entries(row.models ?? {})) {
     if (parseSystemPromptModelKey(key) === null) continue;
-    if (!isPromptSetting(setting)) continue;
-    models[key] = setting;
+    const ref = normalizeScopeRef(value);
+    if (ref !== undefined) models[key] = ref;
+  }
+
+  const combos: Record<string, ScopePromptRef> = {};
+  for (const [name, value] of Object.entries(row.combos ?? {})) {
+    const ref = normalizeScopeRef(value);
+    if (ref !== undefined) combos[name] = ref;
+  }
+
+  const aliases: Record<string, ScopePromptRef> = {};
+  for (const [name, value] of Object.entries(row.aliases ?? {})) {
+    const ref = normalizeScopeRef(value);
+    if (ref !== undefined) aliases[name] = ref;
   }
 
   return {
-    global: row.global !== null && isPromptSetting(row.global) ? row.global : null,
+    global: row.global !== null && isScopePromptRef(row.global) ? row.global : null,
+    presets,
     providers,
     models,
+    combos,
+    aliases,
   };
 }
 
@@ -79,12 +118,18 @@ export async function writeTenantSystemPrompts(
 ): Promise<void> {
   // Keep the row bounded even though the API already enforces the caps: a
   // direct store caller must not be able to plant an unbounded map.
+  const presets = Object.entries(next.presets).slice(0, SYSTEM_PROMPT_PRESET_LIMIT);
   const providers = Object.entries(next.providers).slice(0, SYSTEM_PROMPT_PROVIDER_LIMIT);
   const models = Object.entries(next.models).slice(0, SYSTEM_PROMPT_MODEL_LIMIT);
+  const combos = Object.entries(next.combos).slice(0, SYSTEM_PROMPT_COMBO_LIMIT);
+  const aliases = Object.entries(next.aliases).slice(0, SYSTEM_PROMPT_ALIAS_LIMIT);
   const values = {
     global: next.global,
+    presets: Object.fromEntries(presets),
     providers: Object.fromEntries(providers),
     models: Object.fromEntries(models),
+    combos: Object.fromEntries(combos),
+    aliases: Object.fromEntries(aliases),
     updatedAt: new Date(),
   };
   await db

package/src/persistence/tenant-preferences.ts

@@ -29,7 +29,7 @@ export class DrizzlePreferencesReader implements PreferencesReader {
   }
 }
 
-export interface CachedPreferencesReaderOptions {
+interface CachedPreferencesReaderOptions {
   readonly ttlMs?: number;
   readonly maxEntries?: number;
   readonly revision?: () => number;

package/src/persistence/ttl-cache.ts

@@ -7,13 +7,13 @@ import { dedupeRequest } from "../network/deduplication";
  * - Revision-aware key invalidation
  */
 
-export interface TtlCacheOptions {
+interface TtlCacheOptions {
   readonly ttlMs?: number;
   readonly maxEntries?: number;
   readonly now?: () => number;
 }
 
-export interface TtlCacheEntry<T> {
+interface TtlCacheEntry<T> {
   readonly value: T;
   readonly at: number;
 }
@@ -134,7 +134,7 @@ export class TtlCache<T> {
 }
 
 /** One TTL-sized cache inside a {@link TtlCacheFamily}. */
-export interface TtlCacheFamilyOptions {
+interface TtlCacheFamilyOptions {
   /** TTL applied when a caller does not pass its own. */
   readonly defaultTtlMs: number;
   /** Entry cap per TTL-sized cache. */

package/src/persistence/usage-flush.ts

@@ -65,14 +65,19 @@ async function writeLifetimeDeltas(
   // text and the join against a uuid key fails. SQLite stores the key as text
   // and rejects `UPDATE ... FROM (VALUES ...)` outright, so the same rows are
   // a SELECT with named columns instead.
-  const source = sqliteDialect()
+  const sqlite = sqliteDialect();
+  const source = sqlite
     ? `(${rows.map((row) => `SELECT '${row.apiKeyId}' AS id, ${row.delta} AS delta`).join(" UNION ALL ")})`
     : `(VALUES ${rows.map((row) => `('${row.apiKeyId}'::uuid, ${row.delta}::bigint)`).join(", ")}) AS v(id, delta)`;
+  // PostgreSQL already carries its alias in `source`; only the bare SQLite
+  // subquery needs the trailing alias appended. Emitting both (`AS v(id, delta) v`)
+  // is a syntax error on Postgres, so the flush silently never ran.
+  const from = sqlite ? `${source} v` : source;
   await db.execute(sql.raw(`
     UPDATE "api_keys"
     SET "lifetime_tokens_consumed" =
       COALESCE("api_keys"."lifetime_tokens_consumed", 0) + v.delta
-    FROM ${source} v
+    FROM ${from}
     WHERE "api_keys"."id" = v.id
   `));
 }

package/src/protocol/canonical-model.ts

@@ -614,7 +614,7 @@ export function hasEncryptedReasoning(parts: readonly ContentPart[]): boolean {
  * concurrent preflights would be an aliasing hazard; the memoized summary and
  * its extension set are treated as read-only.)
  */
-export interface PartSummary {
+interface PartSummary {
   readonly hasImage: boolean;
   readonly hasDocument: boolean;
   readonly hasAudio: boolean;

package/src/protocol/codecs.ts

@@ -89,7 +89,7 @@ export function hash32(input: string): number {
   return hash;
 }
 
-export const CLAUDE_TOOL_PREFIX = "_";
+const CLAUDE_TOOL_PREFIX = "_";
 
 export type ClaudeWireObject = Record<string, unknown>;
 
@@ -408,13 +408,9 @@ export function isClaudeBillingHeaderText(text: string): boolean {
 // Well-formed UTF-16 coercion
 
 export function toWellFormedString(value: string): string {
-  const maybe = value as unknown as { toWellFormed?: () => string };
-  if (typeof maybe.toWellFormed === "function") return maybe.toWellFormed();
-  // Fallback for runtimes without String.prototype.toWellFormed (replace lone surrogates)
-  return value.replace(
-    /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g,
-    "\uFFFD",
-  );
+  // String.prototype.toWellFormed is ES2024; guaranteed by Bun ≥1.4, the only
+  // supported runtime.
+  return value.toWellFormed();
 }
 
 export function toWellFormedDeep(value: unknown): unknown {
@@ -480,7 +476,7 @@ export function assertBoundedJsonDepth(value: unknown): void {
 
 function assertBoundedDepthWalk(value: unknown, depth: number): void {
   if (depth > MAX_JSON_DEPTH)
-    throw new GatewayError("invalid_request", 400, `The request body is nested deeper than this endpoint accepts (${MAX_JSON_DEPTH} levels). Flatten the payload.`);
+    throw new GatewayError("invalid_request", 400, `The request body is nested deeper than this endpoint accepts (${MAX_JSON_DEPTH} levels) (request {requestId}). Flatten the payload. Check the shape of what you sent — then resend 🪞`);
   if (Array.isArray(value)) {
     for (const item of value) assertBoundedDepthWalk(item, depth + 1);
     return;
@@ -873,7 +869,7 @@ export const BARE_ROOT_ENDPOINTS: Partial<Record<WireFamily, string>> = {
 };
 
 /** An image part's provider-neutral source, resolved from any supported origin shape. */
-export interface ResolvedImageSource {
+interface ResolvedImageSource {
   /** URL or `data:` URI. Mutually usable with `fileId`. */
   url?: string;
   /** Files API reference (Chat/Responses `file_id`). */
@@ -883,7 +879,7 @@ export interface ResolvedImageSource {
 }
 
 /** An RFC 2397 base64 `data:` URL split into the media type and bytes it carries. */
-export interface DataUrlPayload {
+interface DataUrlPayload {
   /** The declared media type (the `image/png` of `data:image/png;base64,…`). */
   readonly mediaType: string;
   /** The base64 payload, with the `data:` prefix and media type removed. */
@@ -1038,7 +1034,7 @@ export function filterProviderCustomHeaders(
   for (const [rawName, rawValue] of Object.entries(input)) {
     const name = rawName.toLowerCase();
     if (!HEADER_TOKEN.test(name)) {
-      throw new GatewayError("invalid_request", 400, `invalid custom header name: ${rawName}`, {
+      throw new GatewayError("invalid_request", 400, `invalid custom header name: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`, {
         header: rawName,
       });
     }
@@ -1047,7 +1043,7 @@ export function filterProviderCustomHeaders(
       extraReserved.has(name) ||
       name.startsWith("x-forwarded-")
     ) {
-      throw new GatewayError("invalid_request", 400, `custom header is protected: ${rawName}`, {
+      throw new GatewayError("invalid_request", 400, `custom header is protected: ${rawName} (request {requestId}). Not allowed by policy — no hard feelings 🫂`, {
         header: rawName,
       });
     }
@@ -1055,7 +1051,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value must be a string: ${rawName}`,
+        `custom header value must be a string: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         { header: rawName },
       );
     }
@@ -1063,7 +1059,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value exceeds 4KiB: ${rawName}`,
+        `custom header value exceeds 4KiB: ${rawName} (request {requestId}). We love long reads, but not that long 📚`,
         { header: rawName },
       );
     }
@@ -1071,7 +1067,7 @@ export function filterProviderCustomHeaders(
       throw new GatewayError(
         "invalid_request",
         400,
-        `custom header value contains control characters: ${rawName}`,
+        `custom header value contains control characters: ${rawName} (request {requestId}). Check the shape of what you sent — then resend 🪞`,
         { header: rawName },
       );
     }