cartethyia 2.7.4 → 2.7.5

package/src/providers/provider-usage.ts

@@ -11,6 +11,7 @@ export interface OpenAiUsage {
   };
 }
 import { modelsDevCatalog } from "./discovery/models-dev-catalog";
+import { resolveCacheMode } from "../config/providers";
 
 /**
  * Extract cost multipliers from catalog model cost JSONB.
@@ -125,6 +126,36 @@ export function repriceUsage(
     : { ...usage, estimated_cost: estimatedCost };
 }
 
+/**
+ * Simplified cache accounting: when the provider reported a cache hit, the
+ * whole prompt counts as cached — request input ber-cache = cache-eligible →
+ * input = cache. The cache-write volume is already inside the all-in input
+ * total on cache-aware shapes, so it stays separate and is not double-counted
+ * as a hit. A reported `0` or an absent report stay a cache miss. In `real`
+ * mode the provider's reported split is kept as-is.
+ *
+ * Exported so the hand-built record producers (Cursor, Kiro) apply the same
+ * rule as `normalizeUsage`.
+ */
+export function applyCacheMode(usage: UsageRecord): UsageRecord {
+  if (resolveCacheMode() !== "simplified") return usage;
+  if (
+    typeof usage.cached_input_tokens === "number" &&
+    usage.cached_input_tokens > 0 &&
+    usage.input_tokens > 0
+  ) {
+    const writes =
+      typeof usage.cache_write_tokens === "number" ? Math.max(0, usage.cache_write_tokens) : 0;
+    const cached = Math.min(usage.input_tokens, Math.max(0, usage.input_tokens - writes));
+    return {
+      ...usage,
+      cached_input_tokens: cached,
+      uncached_input_tokens: 0,
+    };
+  }
+  return usage;
+}
+
 /**
  * Normalize provider-specific usage data into canonical UsageRecord.
  * Handles Anthropic (cache_read_input_tokens, cache_creation_input_tokens, output_tokens_details.thinking_tokens)
@@ -250,6 +281,21 @@ export function normalizeUsage(input: Record<string, unknown>): UsageRecord {
     input_tokens += cache_write_tokens;
   }
 
+  // Simplified cache accounting: a reported hit makes the whole prompt count as
+  // cached — request input ber-cache = cache-eligible → input = cache. The
+  // cache-write volume is already inside the all-in input total on cache-aware
+  // shapes, so it stays separate and is not double-counted as a hit. Applied
+  // before pricing so the estimated cost reads the same simplified split as the
+  // record.
+  if (typeof cached_input_tokens === "number" && cached_input_tokens > 0 && input_tokens > 0) {
+    if (resolveCacheMode() === "simplified") {
+      const writes =
+        typeof cache_write_tokens === "number" ? Math.max(0, cache_write_tokens) : 0;
+      cached_input_tokens = Math.min(input_tokens, Math.max(0, input_tokens - writes));
+      uncached_input_tokens = 0;
+    }
+  }
+
   // Handle reasoning tokens: Anthropic and OpenAI both use output_tokens_details
   let reasoning_tokens: number | "unavailable" = "unavailable";
   const details: NonNullable<UsageRecord["details"]> = {};
@@ -436,28 +482,47 @@ export function usageToMessagesWire(usage: UsageRecord | undefined): Record<stri
  * and event shapes — only the key lookup lives here, so a new upstream key
  * is added once and every reader picks it up.
  */
-export const REASONING_TEXT_KEYS: readonly string[] = ["reasoning_content", "reasoning"];
+export const REASONING_TEXT_KEYS: readonly string[] = [
+  "reasoning_content",
+  "reasoning",
+  "reasoning_summary",
+  "reasoning_summary_text",
+  "reasoning_text",
+];
+
+/**
+ * Extracts readable text from one reasoning value. Accepts a plain string and
+ * the object shapes upstreams use for reasoning deltas: `{text}`,
+ * `{summary}`, `{delta}` (Responses-style), or an array of parts.
+ */
+function reasoningTextValue(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    let text = "";
+    for (const part of value) {
+      const piece = reasoningTextValue(part);
+      if (piece !== undefined) text += piece;
+    }
+    return text.length > 0 ? text : undefined;
+  }
+  if (typeof value !== "object" || value === null) return undefined;
+  const rec = value as Record<string, unknown>;
+  for (const key of ["text", "summary", "delta", "content"]) {
+    const piece = reasoningTextValue(rec[key]);
+    if (piece !== undefined) return piece;
+  }
+  return undefined;
+}
 
 /** First string found under a known reasoning-text key, or undefined. */
 export function readReasoningText(source: Record<string, unknown>): string | undefined {
   for (const key of REASONING_TEXT_KEYS) {
-    const value = source[key];
-    if (typeof value === "string") return value;
+    const text = reasoningTextValue(source[key]);
+    if (text !== undefined) return text;
   }
   // Qwen/MiniMax-family `reasoning_details[]` parts carrying text fragments.
-  const details = source["reasoning_details"];
-  if (Array.isArray(details)) {
-    const text = details
-      .map((part) =>
-        typeof part === "string"
-          ? part
-          : typeof (part as Record<string, unknown>)?.["text"] === "string"
-            ? ((part as Record<string, unknown>)["text"] as string)
-            : "",
-      )
-      .join("");
-    if (text.length > 0) return text;
-  }
+  const details = reasoningTextValue(source["reasoning_details"]);
+  if (details !== undefined) return details;
   return undefined;
 }
 

package/src/providers/quota/cache.ts

@@ -318,6 +318,35 @@ export async function invalidateQuotaCache(
   }
 }
 
+/**
+ * Drops many accounts from one lens in a single pass.
+ *
+ * The batch-delete route clears several accounts' quota caches at once. The
+ * in-process tier is swept once (one `keys()` pass), and Redis is cleared with
+ * one pipeline, so the cost does not scale with per-account round trips.
+ */
+export async function invalidateQuotaCaches(
+  lens: string,
+  accountIds: readonly string[],
+  redis: RedisClient | undefined,
+): Promise<void> {
+  if (accountIds.length === 0) return;
+  const keys = accountIds.map((accountId) => quotaKey(lens, accountId));
+  const keySet = new Set(keys);
+  for (const key of inMemoryQuotaCache.keys()) {
+    if (keySet.has(key)) inMemoryQuotaCache.delete(key);
+  }
+  if (redis === undefined) return;
+  try {
+    const pipeline = redis.pipeline();
+    for (const key of keys) pipeline.del(key);
+    await pipeline.exec().catch(() => undefined);
+  } catch (error) {
+    metrics.quota_cache_invalidate_failed.inc(1);
+    log.warn("quota cache batch invalidate failed", { lens, error: String(error) });
+  }
+}
+
 /**
  * Drops one account from EVERY cache lens. Global accounts are shared, but a
  * release-N writer may have written the same account under a per-tenant lens,

package/src/providers/quota/quota-contracts.ts

@@ -18,6 +18,10 @@ export interface ProviderQuotaWindow {
   readonly remaining?: number | null;
   /** False means the timestamp is a hard expiry rather than a recurring reset. */
   readonly recurring?: boolean;
+  /** Exact routing model IDs this grant serves; absent means account-wide. */
+  readonly modelIds?: readonly string[];
+  /** Activation instant: future grants remain visible but cannot fund requests. */
+  readonly startsAt?: string | null;
 }
 
 export interface ProviderQuotaResult {

package/src/providers/quota/refresh.ts

@@ -15,8 +15,21 @@ import { fetchProviderQuota } from "./quota-support";
 import { type FetchLike, type ProviderQuotaResult } from "./quota-contracts";
 import type { ProviderId } from "../provider-contracts";
 import type { ProviderRegistry } from "../provider-registry";
-import { GLOBAL_QUOTA_LENS, setCachedQuota } from "./cache";
+import { quotaLens, setCachedQuota } from "./cache";
+import { persistQuotaSnapshot } from "./snapshot";
 import { asJsonbRecord } from "../../shared/coerce";
+import { KIRO_DEFAULT_LABELS } from "../integrations/kiro/kiro-oauth";
+
+/**
+ * The stock Kiro fallback labels as a SQL literal list. Built once from the
+ * canonical set (`KIRO_DEFAULT_LABELS`) and escaped for the single-quote SQL
+ * literal; the values are compile-time constants, so this fragment is static.
+ */
+const KIRO_DEFAULT_LABEL_IN = sql.raw(
+  [...KIRO_DEFAULT_LABELS]
+    .map((label) => `'${label.replace(/'/g, "''")}'`)
+    .join(", "),
+);
 
 /** Why an account quota refresh failed; `null` means the fetch succeeded. */
 export type QuotaRefreshFailureCode = "missing_credential" | "quota_fetch_failed";
@@ -52,7 +65,7 @@ export interface QuotaRefreshDeps {
    */
   readonly resolveCredential: (providerId: ProviderId, accountId: string) => Promise<string>;
   /** Marks a stored api_key credential with the upstream-distinguishable envelope. */
-  readonly markApiKeyCredential?: (providerId: string, credential: string) => string;
+  readonly markApiKeyCredential?: (providerId: string, credential: string) => Promise<string>;
   /** Invalidates the route snapshot when a stamped figure may exclude an account. */
   readonly snapshotInvalidator?: { invalidate(): unknown } | undefined;
 }
@@ -219,7 +232,7 @@ export interface QuotaRefreshTarget {
 
 /** Cache lens an account's quota belongs under. */
 export function targetLens(target: QuotaRefreshTarget): string {
-  return target.tenantId ?? GLOBAL_QUOTA_LENS;
+  return quotaLens(target.tenantId);
 }
 
 const TARGET_COLUMNS = {
@@ -352,7 +365,7 @@ async function runQuotaRefresh(
     // collector to the key-only probe, and OAuth credentials carry no key.
     const marked =
       target.credentialKind === "api_key"
-        ? (deps.markApiKeyCredential?.(target.providerId, credential) ?? credential)
+        ? (await deps.markApiKeyCredential?.(target.providerId, credential) ?? credential)
         : credential;
     try {
       const authState = asJsonbRecord(target.authState);
@@ -399,6 +412,15 @@ async function runQuotaRefresh(
       log.warn(`[quota] failed to record plan for account=${target.accountId}`, error as Error);
     }
   }
+  // Persist the whole successful read, not just the plan. The row survives a
+  // restart that empties the in-process cache, so a cold console open renders
+  // the last known balance instead of nothing (and the sweep refreshes it). A
+  // failed fetch leaves the previous snapshot in place — same reasoning as the
+  // plan column: failure is evidence about the network/credential, not that
+  // the account's balance changed.
+  if (quota.error === null) {
+    await persistQuotaSnapshot(deps.db, target.accountId, quota);
+  }
   // A quota surface that names the account adopts the identity — but only over
   // a default label. An operator's custom rename is never overwritten, and the
   // CASE keeps the read and the write in one statement so a concurrent rename
@@ -416,6 +438,7 @@ async function runQuotaRefresh(
           label: sql`CASE
             WHEN lower(trim(${providerAccounts.label})) = lower(trim(${providerAccounts.providerId})) THEN ${quota.accountLabel}
             WHEN ${providerAccounts.label} LIKE '%|%' THEN ${quota.accountLabel}
+            WHEN ${providerAccounts.label} IN (${KIRO_DEFAULT_LABEL_IN}) THEN ${quota.accountLabel}
             ELSE ${providerAccounts.label}
           END`,
         })

package/src/providers/quota/snapshot.ts

@@ -0,0 +1,94 @@
+/**
+ * Persisted quota snapshots.
+ *
+ * The in-process quota cache is a short TTL and empty on a cold start, so
+ * right after a restart the console would render no balance for every account
+ * until the sweep re-reads them — while Buddy's usage snapshots survived via a
+ * table. This is the generic counterpart: every provider's last successful
+ * quota read is persisted on the account row, and the console falls back to it
+ * when the cache is cold. A failed fetch leaves the previous snapshot in place,
+ * mirroring `quota_plan`.
+ */
+import { eq, inArray } from "drizzle-orm";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { providerAccounts, type ProviderQuotaResultSnapshot } from "../../persistence/schema";
+import type { ProviderQuotaResult } from "./quota-contracts";
+
+/**
+ * Parses the `quota_snapshot` column. Postgres' jsonb arrives as an object;
+ * SQLite's text-backed column arrives as a JSON string — accept both.
+ */
+function parseSnapshot(value: unknown): ProviderQuotaResultSnapshot | null {
+  if (value === null || value === undefined) return null;
+  let root: unknown = value;
+  if (typeof value === "string") {
+    try {
+      root = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof root !== "object" || root === null || Array.isArray(root)) return null;
+  const rec = root as Record<string, unknown>;
+  const { quota, fetchedAt } = rec;
+  if (typeof quota !== "object" || quota === null || typeof fetchedAt !== "string") return null;
+  return { quota: quota as ProviderQuotaResult, fetchedAt };
+}
+
+/** Stores one successful quota read on the account row. Never throws. */
+export async function persistQuotaSnapshot(
+  db: CartethyiaDatabase,
+  accountId: string,
+  quota: ProviderQuotaResult,
+  fetchedAt: Date = new Date(),
+): Promise<void> {
+  try {
+    await db
+      .update(providerAccounts)
+      .set({ quotaSnapshot: { quota, fetchedAt: fetchedAt.toISOString() } })
+      .where(eq(providerAccounts.id, accountId));
+  } catch {
+    // A snapshot that cannot be stored is a stale display, not an error the
+    // caller must handle.
+  }
+}
+
+/** Reads one account's last successful quota snapshot, if any. */
+export async function readQuotaSnapshot(
+  db: CartethyiaDatabase,
+  accountId: string,
+): Promise<ProviderQuotaResultSnapshot | null> {
+  try {
+    const rows = await db
+      .select({ quotaSnapshot: providerAccounts.quotaSnapshot })
+      .from(providerAccounts)
+      .where(eq(providerAccounts.id, accountId))
+      .limit(1);
+    return parseSnapshot(rows[0]?.quotaSnapshot);
+  } catch {
+    return null;
+  }
+}
+
+/** Batch read for one page render: one query for every account. */
+export async function readQuotaSnapshots(
+  db: CartethyiaDatabase,
+  accountIds: readonly string[],
+): Promise<Map<string, ProviderQuotaResultSnapshot>> {
+  const found = new Map<string, ProviderQuotaResultSnapshot>();
+  if (accountIds.length === 0) return found;
+  try {
+    const rows = await db
+      .select({ id: providerAccounts.id, quotaSnapshot: providerAccounts.quotaSnapshot })
+      .from(providerAccounts)
+      .where(inArray(providerAccounts.id, [...accountIds]));
+    for (const row of rows) {
+      const snapshot = parseSnapshot(row.quotaSnapshot);
+      if (snapshot) found.set(row.id, snapshot);
+    }
+  } catch {
+    // A read failure yields a partial map; callers already treat a missing
+    // entry as "no snapshot".
+  }
+  return found;
+}

package/src/providers/search/search-provider.ts

@@ -1,5 +1,3 @@
-import { asRecord } from "../../shared/coerce";
-
 /**
  * Declarative web-search provider adapters.
  *
@@ -161,4 +159,4 @@ function jsonFromEventStream(raw: string): unknown {
 
 }
 
-export { asRecord, stringField };
+export { stringField };

package/src/providers/search/search-providers.ts

@@ -9,7 +9,8 @@
  * normalization, which is what makes a provider's wire local to one spec.
  */
 import type { SearchParams, SearchProviderSpec, SearchRequestInit } from "./search-provider";
-import { asRecord, stringField } from "./search-provider";
+import { stringField } from "./search-provider";
+import { asRecord } from "../../shared/coerce";
 
 function domainFilterParams(filter: readonly string[] | undefined): {
   includes: string[];

package/src/security/abuse.ts

@@ -57,7 +57,7 @@ const BAN_ROUTE_KEY = "#ban";
  * `banThreshold` is both the identity-wide escalation threshold and the
  * highest count either ring must keep observable.
  */
-export interface IpAbuseAttempt {
+interface IpAbuseAttempt {
   readonly identity: string;
   readonly route: string;
   readonly now: number;
@@ -67,7 +67,7 @@ export interface IpAbuseAttempt {
 }
 
 /** What one admission step decided. */
-export interface IpAbuseOutcome {
+interface IpAbuseOutcome {
   /** The identity was already banned; nothing was incremented. */
   readonly banned: boolean;
   /** Attempts now in this route's window, including this one. `0` when banned. */
@@ -115,13 +115,13 @@ export interface IpAbuseStore {
   checkAndRecord(attempt: IpAbuseAttempt): Promise<IpAbuseOutcome>;
 }
 
-export interface IpAbuseProtectionServiceOptions {
+interface IpAbuseProtectionServiceOptions {
   readonly maxRequestsPerWindow?: number;
   readonly banThreshold?: number;
   readonly banDurationMs?: number;
 }
 
-export interface InMemoryIpAbuseStoreOptions {
+interface InMemoryIpAbuseStoreOptions {
   readonly windowMs?: number;
   readonly clock?: () => number;
   /** Distinct (identity, route) keys tracked before the oldest is evicted. */

package/src/security/admission/service.ts

@@ -12,7 +12,7 @@ import { admissionMetricLabel, reasonToGatewayError } from "./reasons";
 
 /** Persists reconciled lifetime token consumption for an API key. Injected so
  *  the in-memory admission service stays decoupled from Drizzle/Postgres. */
-export type LifetimeUsagePersister = (input: {
+type LifetimeUsagePersister = (input: {
   apiKeyId: string;
   delta: number;
 }) => Promise<void>;
@@ -23,7 +23,7 @@ export type LifetimeUsagePersister = (input: {
  * counter store only when it is about to seed a missing lifetime counter, so
  * the ≤3s-stale snapshot value cannot freeze a low baseline in place. Injected
  * so the admission module stays decoupled from Drizzle/Postgres. */
-export type FreshLifetimeConsumedReader = (apiKeyId: string) => Promise<number | undefined>;
+type FreshLifetimeConsumedReader = (apiKeyId: string) => Promise<number | undefined>;
 
 
 export class ApiKeyAdmissionService {

package/src/security/admission/ttl.ts

@@ -1,61 +1,61 @@
-/**
- * Lease and counter lifetimes, and the calendar bucket keys they key on.
- *
- * These live together because they are one arithmetic problem: a counter
- * must outlive the lease that charges it, and a lease key must outlive the
- * horizon the sweeper reads. Splitting them across files is how those
- * invariants silently break, so the reasoning stays in one place.
- */
-export const LEASE_TTL_MS = 3600_000;
-
-/**
- * The lease key's own Redis TTL is deliberately LONGER than the `expires_at`
- * horizon the lease hash records.
- *
- * `expires_at` is the moment the sweeper becomes allowed to reclaim the lease.
- * If the key TTL equalled that horizon, Redis would evict the hash at exactly
- * the moment `reapIfExpired` wanted to read it: `HGET state` would return nil,
- * the sweep would skip it, and a crash between reserve and release would strand
- * the held concurrency / tenant-concurrency slot for as long as the counter
- * keeps being refreshed — every later reserve re-arms the counter's own TTL, so
- * a key still in use never recovers its leaked slot. The grace window keeps the
- * hash readable for several sweep intervals past the horizon, so the recovery
- * path actually runs.
- *
- * Exported so the invariant is asserted directly: a lease key must outlive the
- * horizon it records by more than one sweep interval (`sweepLeases` runs every
- * 30s, wired in `runtime/dependencies.ts`).
- */
-const LEASE_TTL_GRACE_SECONDS = 120;
-/** Seconds after which a lease hash is reapable (`expires_at` horizon). */
-export const LEASE_REAP_HORIZON_SECONDS = Math.ceil(LEASE_TTL_MS / 1000);
-/** Seconds the lease hash itself lives; must exceed the reap horizon. */
-export const LEASE_KEY_TTL_SECONDS = LEASE_REAP_HORIZON_SECONDS + LEASE_TTL_GRACE_SECONDS;
-
-/**
- * TTLs for the token-budget counters, in seconds.
- *
- * Daily lives just past two days (a day bucket plus slack to cover a request
- * straddling midnight); monthly and lifetime share one 35-day window — long
- * enough that a month bucket is never evicted mid-month, and it is the *only*
- * thing bounding `admission:lifetime:*`, which has no natural bucket to expire
- * on. Every writer below must therefore carry its own TTL: a plain `SET`
- * without one creates a key that outlives every bucket it feeds.
- */
-export const DAILY_COUNTER_TTL_SECONDS = 172800;
-export const MONTHLY_COUNTER_TTL_SECONDS = 3024000;
-export const LIFETIME_COUNTER_TTL_SECONDS = 3024000;
-/** RPM window plus slack; concurrency slots are held for the request duration. */
-export const RPM_WINDOW_TTL_SECONDS = 65;
-// Must exceed the lease's own lifetime (`LEASE_TTL_MS` + grace), otherwise a
-// request held longer than this lets its concurrency counter expire underneath
-// a still-live lease and a later reserve INCRs from zero. Derived rather than
-// hard-coded so raising the lease TTL cannot silently reopen the hole.
-export const CONCURRENCY_TTL_SECONDS = LEASE_KEY_TTL_SECONDS;
-
-export function dailyBucket(now: number): string {
-  return new Date(now).toISOString().slice(0, 10);
-}
-export function monthlyBucket(now: number): string {
-  return new Date(now).toISOString().slice(0, 7);
-}
+/**
+ * Lease and counter lifetimes, and the calendar bucket keys they key on.
+ *
+ * These live together because they are one arithmetic problem: a counter
+ * must outlive the lease that charges it, and a lease key must outlive the
+ * horizon the sweeper reads. Splitting them across files is how those
+ * invariants silently break, so the reasoning stays in one place.
+ */
+export const LEASE_TTL_MS = 3600_000;
+
+/**
+ * The lease key's own Redis TTL is deliberately LONGER than the `expires_at`
+ * horizon the lease hash records.
+ *
+ * `expires_at` is the moment the sweeper becomes allowed to reclaim the lease.
+ * If the key TTL equalled that horizon, Redis would evict the hash at exactly
+ * the moment `reapIfExpired` wanted to read it: `HGET state` would return nil,
+ * the sweep would skip it, and a crash between reserve and release would strand
+ * the held concurrency / tenant-concurrency slot for as long as the counter
+ * keeps being refreshed — every later reserve re-arms the counter's own TTL, so
+ * a key still in use never recovers its leaked slot. The grace window keeps the
+ * hash readable for several sweep intervals past the horizon, so the recovery
+ * path actually runs.
+ *
+ * Exported so the invariant is asserted directly: a lease key must outlive the
+ * horizon it records by more than one sweep interval (`sweepLeases` runs every
+ * 30s, wired in `runtime/dependencies.ts`).
+ */
+const LEASE_TTL_GRACE_SECONDS = 120;
+/** Seconds after which a lease hash is reapable (`expires_at` horizon). */
+export const LEASE_REAP_HORIZON_SECONDS = Math.ceil(LEASE_TTL_MS / 1000);
+/** Seconds the lease hash itself lives; must exceed the reap horizon. */
+export const LEASE_KEY_TTL_SECONDS = LEASE_REAP_HORIZON_SECONDS + LEASE_TTL_GRACE_SECONDS;
+
+/**
+ * TTLs for the token-budget counters, in seconds.
+ *
+ * Daily lives just past two days (a day bucket plus slack to cover a request
+ * straddling midnight); monthly and lifetime share one 35-day window — long
+ * enough that a month bucket is never evicted mid-month, and it is the *only*
+ * thing bounding `admission:lifetime:*`, which has no natural bucket to expire
+ * on. Every writer below must therefore carry its own TTL: a plain `SET`
+ * without one creates a key that outlives every bucket it feeds.
+ */
+export const DAILY_COUNTER_TTL_SECONDS = 172800;
+export const MONTHLY_COUNTER_TTL_SECONDS = 3024000;
+export const LIFETIME_COUNTER_TTL_SECONDS = 3024000;
+/** RPM window plus slack; concurrency slots are held for the request duration. */
+export const RPM_WINDOW_TTL_SECONDS = 65;
+// Must exceed the lease's own lifetime (`LEASE_TTL_MS` + grace), otherwise a
+// request held longer than this lets its concurrency counter expire underneath
+// a still-live lease and a later reserve INCRs from zero. Derived rather than
+// hard-coded so raising the lease TTL cannot silently reopen the hole.
+export const CONCURRENCY_TTL_SECONDS = LEASE_KEY_TTL_SECONDS;
+
+export function dailyBucket(now: number): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+export function monthlyBucket(now: number): string {
+  return new Date(now).toISOString().slice(0, 7);
+}

package/src/security/api-key-auth.ts

@@ -118,7 +118,7 @@ function freezeList(
   return arr;
 }
 
-export function freezeSnapshot(s: ApiKeyAuthorizationSnapshot): ApiKeyAuthorizationSnapshot {
+function freezeSnapshot(s: ApiKeyAuthorizationSnapshot): ApiKeyAuthorizationSnapshot {
   const model_list = freezeList(s.model_list);
   const model_access_mode: ApiKeyModelAccessMode =
     s.model_access_mode === "blacklist" ? "blacklist" : "whitelist";
@@ -363,6 +363,12 @@ export async function resolveApiKeyAuthorization(
   // keep the issued row values forever. Reading the parent here makes denylist /
   // one-time / recurring edits apply on the next cache miss.
   const policy = parent ?? row;
+  // Share-template concurrency scope decides whether the family shares one
+  // admission counter (default `family`) or each recipient has its own
+  // (`per_key`). In `family` mode the child participates in the parent's
+  // counter namespace; in `per_key` mode the child is its own admission
+  // identity and carries its own cap.
+  const perKeyConcurrency = parent !== undefined && row.concurrencyScope === "per_key";
   // Only a `share` parent can have children, and children are the only thing
   // the SUM below can find. Every other key ran an aggregate that was certain
   // to return 0 — one extra Postgres round-trip on the auth path for nothing.
@@ -381,8 +387,10 @@ export async function resolveApiKeyAuthorization(
     api_key_id: row.id,
     tenant_id: row.tenantId,
     // Family quota / concurrency share one admission counter namespace so two
-    // recipients cannot each burn a full lifetime/daily budget.
-    ...(parent ? { admission_identity: parent.id } : {}),
+    // recipients cannot each burn a full lifetime/daily budget. In `per_key`
+    // concurrency mode the child is its own admission identity so its cap and
+    // counter are independent.
+    ...(parent && !perKeyConcurrency ? { admission_identity: parent.id } : {}),
     ...(policy.modelList ? { model_list: policy.modelList as string[] } : {}),
     model_access_mode: policy.modelAccessMode ?? "whitelist",
     ...(policy.clientRouterDenylist
@@ -393,7 +401,11 @@ export async function resolveApiKeyAuthorization(
     ...(policy.monthlyTokenLimit != null ? { monthly_tokens: policy.monthlyTokenLimit } : {}),
     ...(policy.lifetimeTokenBudget != null ? { lifetime_token_budget: policy.lifetimeTokenBudget } : {}),
     lifetime_tokens_consumed: consumed,
-    ...(policy.maxConcurrentRequests != null ? { max_concurrent: policy.maxConcurrentRequests } : {}),
+    // `per_key` mode: the child carries its own cap (copied at issue); family
+    // mode inherits the parent's cap.
+    ...((perKeyConcurrency ? row.maxConcurrentRequests : policy.maxConcurrentRequests) != null
+      ? { max_concurrent: perKeyConcurrency ? row.maxConcurrentRequests : policy.maxConcurrentRequests }
+      : {}),
     scopes,
   });
 

package/src/security/client-router-fingerprint.ts

@@ -21,7 +21,7 @@ import { getHeader as readRecordHeader } from "../protocol/canonical-model";
  * `id` is the stable token an operator stores in a key's denylist, so it is
  * part of the persisted contract and must not be renamed casually.
  */
-export interface ClientRouterDefinition {
+interface ClientRouterDefinition {
   readonly id: string;
   /** Human label for the dashboard. */
   readonly label: string;
@@ -40,7 +40,7 @@ export interface ClientRouterDefinition {
  * safe for a uniquely named header; a header whose value distinguishes it must
  * name a matcher instead.
  */
-export interface ClientRouterSignal {
+interface ClientRouterSignal {
   /** Header name, lowercase. */
   readonly field: string;
   /** Human description shown when the signal matches. */
@@ -114,14 +114,14 @@ export const CLIENT_ROUTERS: readonly ClientRouterDefinition[] = [
 const LEGACY_CLIENT_ROUTER_IDS: Readonly<Record<string, string>> = { omniroute: "9router" };
 
 /** A signal that matched, with the product it belongs to. */
-export interface MatchedClientSignal {
+interface MatchedClientSignal {
   readonly field: string;
   readonly description: string;
   /** The observed value, capped, for the operator's audit trail. */
   readonly value: string;
 }
 
-export interface ClientRouterMatch {
+interface ClientRouterMatch {
   readonly routerId: string;
   readonly label: string;
   readonly signals: readonly MatchedClientSignal[];

package/src/security/credential-codec.ts

@@ -22,7 +22,7 @@ import { isRecord } from "../protocol/codecs";
 const TEXT_DECODER = new TextDecoder();
 
 /** Decodes a stored secret: UTF-8 bytes or a string, trimmed. */
-export function decodeSecretText(secret: Uint8Array | string): string {
+function decodeSecretText(secret: Uint8Array | string): string {
   const raw = typeof secret === "string" ? secret : TEXT_DECODER.decode(secret);
   return raw.trim();
 }
@@ -48,7 +48,7 @@ function fieldString(record: Record<string, unknown>, key: string): string {
 }
 
 /** `{accessToken, orgId?}` — the Kilo Code envelope (org scoping is optional). */
-export interface KiloEnvelope {
+interface KiloEnvelope {
   readonly accessToken: string;
   /** Organization the gateway scopes requests to; absent when the profile omits one. */
   readonly orgId?: string;
@@ -79,7 +79,7 @@ export function decodeKiloCredential(secret: Uint8Array | string): KiloEnvelope
 }
 
 /** `{oauthAccessToken, apiKey}` — the Muse Code (Meta) envelope. */
-export interface MuseEnvelope {
+interface MuseEnvelope {
   readonly oauthAccessToken: string;
   readonly apiKey: string;
 }