cartethyia 2.7.4 → 2.7.6

package/src/console/share/share-router.ts

@@ -41,6 +41,77 @@ const MIN_TOKEN_LENGTH = 20;
  */
 const SHARE_STATS_STREAM_INTERVAL_MS = 30_000;
 
+/**
+ * A subscriber of the process-wide share-stats sampler. A recipient is keyed
+ * by its family (`tenantId` + template key) so one sampler tick can push to
+ * many links without a per-connection timer.
+ */
+type ShareStatsListener = (family: ShareFamilyStats) => void;
+
+/**
+ * One sampler per gateway for share-stats SSE delivery. Previously each
+ * `/share/:token/stats/stream` connection ran its own 30s timer and re-read
+ * the family rollup; with N open tabs that is N timers and N rollups all
+ * reading the same data. Now a single process-level sampler ticks on the
+ * shared cadence and fans each computed rollup out to the subscribers whose
+ * family it matches. Timers run only while at least one stream is open.
+ */
+function createShareStatsSampler(config: {
+  readonly db: CartethyiaDatabase;
+  readonly shareStore: ShareLinkStore;
+  readonly stats: ShareStatsPort;
+}): { subscribe(token: string, listener: ShareStatsListener): () => void } {
+  const subscribers = new Map<string, Set<ShareStatsListener>>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const tick = async (): Promise<void> => {
+    // One resolve per family token: a recipient with several tabs shares one
+    // rollup, and a family with no open stream is never computed.
+    const tokens = new Set(subscribers.keys());
+    for (const token of tokens) {
+      const listeners = subscribers.get(token);
+      if (listeners === undefined || listeners.size === 0) continue;
+      try {
+        const family = await resolveFamilyStats(config.db, config.shareStore, config.stats, token);
+        if (family === null) continue;
+        for (const listener of listeners) listener(family);
+      } catch {
+        // A transient read must not interrupt the sampler.
+      }
+    }
+  };
+
+  const start = (): void => {
+    if (timer !== undefined) return;
+    timer = setTimeout(async function run() {
+      timer = setTimeout(run, SHARE_STATS_STREAM_INTERVAL_MS);
+      await tick();
+    }, SHARE_STATS_STREAM_INTERVAL_MS);
+  };
+
+  const stop = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  return {
+    subscribe(token, listener) {
+      let listeners = subscribers.get(token);
+      if (listeners === undefined) {
+        listeners = new Set();
+        subscribers.set(token, listeners);
+      }
+      listeners.add(listener);
+      if (subscribers.size > 0) start();
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) subscribers.delete(token);
+        if (subscribers.size === 0) stop();
+      };
+    },
+  };
+}
+
 /**
  * Context and capabilities for one allowed model, sourced from the public
  * catalog. Every field is nullable/optional so the page can show what is known
@@ -56,7 +127,7 @@ export interface ShareModelInfo {
   readonly webSearch: boolean;
 }
 
-export interface ShareRouterOptions {
+interface ShareRouterOptions {
   readonly db: CartethyiaDatabase;
   readonly shareStore: ShareLinkStore;
   /** Resolves the normalized client IP through the trusted-proxy boundary. */
@@ -263,6 +334,12 @@ async function resolveFamilyStats(
 /** Creates the public enrollment page and one-time shared-key issuance route. */
 export function createShareRouter(options: ShareRouterOptions): AnyElysia {
   const { db, shareStore } = options;
+  // The sampler is shared by every stats stream this router serves; it is a
+  // no-op when the composition omits `stats` (tests that do not exercise the
+  // stream), because `tick` never runs with no subscribers.
+  const statsSampler = options.stats === undefined
+    ? undefined
+    : createShareStatsSampler({ db, shareStore, stats: options.stats });
 
   return new Elysia()
     /**
@@ -296,6 +373,7 @@ export function createShareRouter(options: ShareRouterOptions): AnyElysia {
         oneTimeLimit: row.lifetimeTokenBudget,
         requestsPerMinute: row.requestsPerMinute,
         maxConcurrentRequests: row.maxConcurrentRequests,
+        concurrencyScope: row.concurrencyScope ?? "family",
         modelPrefix: row.modelPrefix,
         models,
         modelInfo,
@@ -442,48 +520,38 @@ export function createShareRouter(options: ShareRouterOptions): AnyElysia {
     /**
      * Live family activity for the share page's stats section, pushed over SSE.
      *
-     * The stream sends one snapshot immediately on connect, then re-reads on a
-     * short cadence so the recipient watches the shared quota move instead of
-     * refreshing. Telemetry is buffered server-side and drained in under a
-     * second, so a DB re-read on this cadence is as fresh as an event bus would
-     * be. Same bearer token and same masked-IP rollup as the one-shot route; a
-     * token that stops resolving closes the stream rather than reporting zeros.
+     * The stream sends one snapshot immediately on connect, then pushes on a
+     * shared sampler cadence so the recipient watches the shared quota move
+     * instead of refreshing. Telemetry is buffered server-side and drained in
+     * under a second, so the sampler's DB re-read is as fresh as an event bus
+     * would be. Same bearer token and same masked-IP rollup as the one-shot
+     * route; a token that stops resolving closes the stream rather than
+     * reporting zeros.
      */
     .get("/share/:token/stats/stream", async ({ params, request }) => {
       if (typeof params.token !== "string") return notFound();
       const token = params.token;
       if (token.length < MIN_TOKEN_LENGTH) return notFound();
       const stats = options.stats;
-      if (!stats) return json({ error: { code: "stats_unavailable", message: "Stats are unavailable" } }, 503);
+      if (!stats || statsSampler === undefined) {
+        return json({ error: { code: "stats_unavailable", message: "Stats are unavailable" } }, 503);
+      }
+      const sampler = statsSampler;
       return consoleSseResponse(
         createConsoleSseStream(request.signal, (sender) => {
-          let closed = false;
-          let timer: ReturnType<typeof setTimeout> | undefined;
-          const push = async () => {
-            const family = await resolveFamilyStats(db, shareStore, stats, token);
-            if (closed) return;
+          const unsubscribe = sampler.subscribe(token, (family) => sender.send("stats", family));
+          // Bootstrap: deliver the link's current rollup immediately, and close
+          // the stream if the token no longer resolves — the same terminal
+          // behavior the per-connection timer had on a dead link.
+          void resolveFamilyStats(db, shareStore, stats, token).then((family) => {
             if (family === null) {
               sender.send("error", { code: "link_not_found" });
-              closed = true;
-              return;
+              unsubscribe();
+            } else {
+              sender.send("stats", family);
             }
-            sender.send("stats", family);
-          };
-          const schedule = () => {
-            timer = setTimeout(() => {
-              if (closed) return;
-              void push().finally(() => {
-                if (!closed) schedule();
-              });
-            }, SHARE_STATS_STREAM_INTERVAL_MS);
-          };
-          void push().finally(() => {
-            if (!closed) schedule();
-          });
-          return () => {
-            closed = true;
-            clearTimeout(timer);
-          };
+          }).catch(() => undefined);
+          return unsubscribe;
         }),
       );
     })

package/src/console/share/share-stats.ts

@@ -30,7 +30,7 @@ import { cachedRead } from "../shared/read-through-cache";
 import { utcDayStart, utcMonthStart } from "../shared/day";
 
 /** Totals for the whole share family, all-time plus the windows the UI draws. */
-export interface ShareFamilyTotals {
+interface ShareFamilyTotals {
   readonly requests: number;
   readonly errors: number;
   readonly inputTokens: number;
@@ -45,7 +45,7 @@ export interface ShareFamilyTotals {
 }
 
 /** One hour bucket of the last 24 hours, oldest first. */
-export interface ShareHourlyBucket {
+interface ShareHourlyBucket {
   /** ISO instant at the top of the hour. */
   readonly hour: string;
   readonly requests: number;
@@ -53,7 +53,7 @@ export interface ShareHourlyBucket {
   readonly tokens: number;
 }
 
-export interface ShareTopModel {
+interface ShareTopModel {
   readonly modelId: string;
   readonly requests: number;
   readonly tokens: number;
@@ -63,7 +63,7 @@ export interface ShareTopModel {
   readonly avgTtfbMs: number | null;
 }
 
-export interface ShareTopClientIp {
+interface ShareTopClientIp {
   /** Always masked: this payload is served to the recipient, not the tenant. */
   readonly ip: string;
   readonly requests: number;
@@ -371,11 +371,9 @@ async function computeFamilyStatsBody(
       .where(eq(apiKeys.id, templateKeyId))
       .limit(1),
   ]);
-  // Cumulative family spend: the template's own counter plus the telemetry
-  // total. The counter is a manually-configured seed (an operator limit), not
-  // traffic, and it is never reset; azmetry rows for revoked/deleted children
-  // likewise stay counted, so the running total is monotonic and consistent
-  // across the overview, the share dialog, and this page.
+  // Cumulative family spend: the template's own counter is the live
+  // accumulator (updated by every recipient commit), so it IS the total.
+  // Telemetry still drives the bounded daily/monthly windows below.
   const templateLifetime = Number(template[0]?.lifetime ?? 0);
 
   // The ranked tables need real events, bounded to the 24-hour window. The
@@ -398,10 +396,10 @@ async function computeFamilyStatsBody(
   });
   rollup.totals = {
     ...rollup.totals,
-    // The template counter is the seed on the running total, not a distinct
-    // bucket: daily/monthly windows are telemetry-only (the counter has no
-    // time axis), so those keep their own sums.
-    totalTokens: templateLifetime + kpi.tokens,
+    // The template counter IS the running family total (live accumulator).
+    // Daily/monthly windows stay telemetry-only (the counter has no time
+    // axis), so those keep their own sums.
+    totalTokens: templateLifetime,
     todayTokens,
     monthTokens,
     // Lifetime counts come from the durable rollup, not the page: a family

package/src/console/share/share-usage.ts

@@ -13,7 +13,7 @@ import { apiKeys, telemetryUsageTotals } from "../../persistence/schema";
 import { shouldMaskClientIp } from "../shared/ip-privacy";
 import { utcDayStart } from "../shared/day";
 
-export interface SharedKeyTokenUsage {
+interface SharedKeyTokenUsage {
   readonly requests: number;
   readonly errors: number;
   readonly inputTokens: number;

package/src/console/shared/errors.ts

@@ -7,7 +7,7 @@ import { formatPublicErrorMessage } from "../../protocol/gateway-error";
 // (or the storage-layer BackupError, same code/status/message shape) and
 // shapes it through errorResponse; guards narrow to TenantAccessDecision.
 
-export interface ErrorResponseOptions {
+interface ErrorResponseOptions {
   readonly detailsPolicy?: "omit" | "include-if-present" | "always-include";
 }
 
@@ -105,7 +105,7 @@ export function requireAnyScope(
   return access;
 }
 
-export type TenantAccessDecision = AccessDecision & { readonly tenantId: string };
+type TenantAccessDecision = AccessDecision & { readonly tenantId: string };
 
 export function requireTenantScope(
   access: AccessDecision | undefined,

package/src/console/shared/object.ts

@@ -0,0 +1,18 @@
+/**
+ * Builds an object from `source`, omitting absent values.
+ *
+ * The console domains hand-roll the same `...(x === undefined ? {} : { x })`
+ * field-omission spread many times (key create/update patches, response
+ * sanitizers). This is the single helper for that pattern; `omitNull` extends
+ * it to also drop `null` values (the `== null` variant), matching call sites
+ * that treat null as "clear this field" rather than "set it to null".
+ */
+export function pickDefined<T extends object>(source: T, omitNull = false): { [K in keyof T]?: Exclude<T[K], undefined> } {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    if (omitNull && value === null) continue;
+    out[key] = value;
+  }
+  return out as { [K in keyof T]?: Exclude<T[K], undefined> };
+}

package/src/console/shared/read-through-cache.ts

@@ -31,7 +31,7 @@
 import { createHash } from "node:crypto";
 
 /** The slice of Redis this cache needs, so it can be tested without a server. */
-export interface ReadThroughCacheClient {
+interface ReadThroughCacheClient {
   get(key: string): Promise<string | null>;
   set(key: string, value: string, mode: "EX", ttlSeconds: number): Promise<unknown>;
 }
@@ -41,7 +41,7 @@ export interface ReadThroughCacheClient {
  * more often pass a shorter TTL; this value suits the dashboard's polling
  * cadence and the append-only telemetry log.
  */
-export const READ_THROUGH_DEFAULT_TTL_SECONDS = 10;
+const READ_THROUGH_DEFAULT_TTL_SECONDS = 10;
 
 /** The cached value plus the strong validator for the bytes it serializes to. */
 export interface CachedResult<T> {
@@ -59,7 +59,7 @@ function etagFor(bytes: string): string {
 }
 
 /** The sibling key holding the validator, so a cached body is never re-hashed. */
-export function etagKey(key: string): string {
+function etagKey(key: string): string {
   return `${key}:etag`;
 }
 
@@ -196,7 +196,7 @@ export function conditionalResponse<T>(
 }
 
 /** True when an `If-None-Match` header names this validator. */
-export function matchesEtag(header: string | null, etag: string): boolean {
+function matchesEtag(header: string | null, etag: string): boolean {
   if (header === null) return false;
   const trimmed = header.trim();
   if (trimmed === "*") return true;

package/src/console/shared/transaction.ts

@@ -0,0 +1,14 @@
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+
+/**
+ * Casts a Drizzle nested-transaction handle to the shared database type.
+ *
+ * Drizzle types a nested transaction callback with the dialect's own
+ * transaction handle, which differs from `CartethyiaDatabase`. The cast is
+ * required (both drivers implement the surface stores use), but it is a type
+ * hole every time it appears raw — so it is centralized here rather than
+ * scattered across call sites.
+ */
+export function asConsoleDb(tx: unknown): CartethyiaDatabase {
+  return tx as unknown as CartethyiaDatabase;
+}

package/src/console/system-prompt/contracts.ts

@@ -16,33 +16,70 @@ export interface PromptSetting {
 export const PROMPT_MODES = ["append", "override"] as const;
 export type PromptMode = (typeof PROMPT_MODES)[number];
 
-/** Per-provider entry: follow the tenant's global prompt, or carry a custom one. */
-export interface ProviderPromptEntry {
-  readonly followGlobal: boolean;
-  /** Present and used only when `followGlobal` is false. */
-  readonly setting?: PromptSetting;
+/**
+ * A named, reusable prompt. Scopes reference presets by id instead of each
+ * carrying its own text, so one tone/ruleset can be applied to many scopes.
+ */
+export interface SystemPromptPreset {
+  readonly id: string;
+  readonly name: string;
+  readonly enabled: boolean;
+  readonly mode: PromptMode;
+  readonly text: string;
 }
 
+/**
+ * How one scope decides what to inject. Modes:
+ *
+ * - `off`    — explicitly inject nothing for this scope; scope-specific stop,
+ *              does NOT fall through to the global prompt.
+ * - `global`  — follow the tenant's global prompt (the default posture).
+ * - `preset`  — use the referenced named preset (disabled preset = no inject).
+ * - `custom`  — carry this scope's own prompt inline.
+ *
+ * A scope with no entry at all behaves as `global` (resolution falls through
+ * to the global prompt), so omitting a key is the same as an explicit
+ * `{ kind: "global" }` reference. The global scope itself never uses
+ * `{ kind: "global" }` — it is `null` (off), a preset, or a custom setting.
+ */
+export type ScopePromptRef =
+  | { readonly kind: "off" }
+  | { readonly kind: "global" }
+  | { readonly kind: "preset"; readonly presetId: string }
+  | { readonly kind: "custom"; readonly setting: PromptSetting };
+
 /** The full per-tenant configuration, one row in `tenant_system_prompts`. */
 export interface TenantSystemPrompts {
-  /** `null` = never configured — distinct from an explicit disabled setting. */
-  readonly global: PromptSetting | null;
-  /** providerId → entry */
-  readonly providers: Readonly<Record<string, ProviderPromptEntry>>;
-  /** `${providerId}::${modelId}` → setting */
-  readonly models: Readonly<Record<string, PromptSetting>>;
+  /** `null` = no global injection — distinct from an explicit disabled setting. */
+  readonly global: ScopePromptRef | null;
+  /** preset id → preset */
+  readonly presets: Readonly<Record<string, SystemPromptPreset>>;
+  /** providerId → ref */
+  readonly providers: Readonly<Record<string, ScopePromptRef>>;
+  /** `${providerId}::${modelId}` → ref */
+  readonly models: Readonly<Record<string, ScopePromptRef>>;
+  /** combo name → ref */
+  readonly combos: Readonly<Record<string, ScopePromptRef>>;
+  /** alias name → ref */
+  readonly aliases: Readonly<Record<string, ScopePromptRef>>;
 }
 
 /** Empty configuration: nothing configured anywhere. */
 export const EMPTY_TENANT_SYSTEM_PROMPTS: TenantSystemPrompts = {
   global: null,
+  presets: {},
   providers: {},
   models: {},
+  combos: {},
+  aliases: {},
 };
 
 /** Maximum stored text per scope (5 MB). Enforced at the console API. */
 export const SYSTEM_PROMPT_TEXT_CAP_BYTES = 5_000_000;
 
+/** Maximum stored preset-name length. Enforced at the console API. */
+export const SYSTEM_PROMPT_PRESET_NAME_CAP = 200;
+
 /**
  * Marker wrapping tenant text injected into a provider wire whose upstream
  * validates the system prompt as a channel identity (the buddy family). The
@@ -52,12 +89,21 @@ export const SYSTEM_PROMPT_TEXT_CAP_BYTES = 5_000_000;
 export const SYSTEM_PROMPT_WRAPPER_PREFIX = "<cartethyia:system-prompt>";
 export const SYSTEM_PROMPT_WRAPPER_SUFFIX = "</cartethyia:system-prompt>";
 
+/** Maximum number of presets stored for one tenant. */
+export const SYSTEM_PROMPT_PRESET_LIMIT = 64;
+
 /** Maximum number of per-provider entries stored for one tenant. */
 export const SYSTEM_PROMPT_PROVIDER_LIMIT = 256;
 
 /** Maximum number of per-model entries stored for one tenant. */
 export const SYSTEM_PROMPT_MODEL_LIMIT = 512;
 
+/** Maximum number of per-combo entries stored for one tenant. */
+export const SYSTEM_PROMPT_COMBO_LIMIT = 512;
+
+/** Maximum number of per-alias entries stored for one tenant. */
+export const SYSTEM_PROMPT_ALIAS_LIMIT = 512;
+
 /**
  * Providers whose upstream validates the fixed system prompt as a channel
  * identity. Their system turn must keep the fixed prompt as the opener, so
@@ -66,7 +112,7 @@ export const SYSTEM_PROMPT_MODEL_LIMIT = 512;
  * `override` mode is not honoured for these providers — it would strip the
  * identity and the upstream would refuse the request.
  */
-export const WRAPPED_INJECTION_PROVIDERS: ReadonlySet<string> = new Set([
+const WRAPPED_INJECTION_PROVIDERS: ReadonlySet<string> = new Set([
   "cb", // CodeBuddy International
   "cbcn", // CodeBuddy CN
   "workbuddy",
@@ -100,3 +146,34 @@ export function isPromptSetting(value: unknown): value is PromptSetting {
     typeof candidate.text === "string"
   );
 }
+
+/** True when the value is a well-formed preset (shape only, not size). */
+export function isSystemPromptPreset(value: unknown): value is SystemPromptPreset {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<SystemPromptPreset>;
+  return (
+    typeof candidate.id === "string" &&
+    candidate.id.length > 0 &&
+    typeof candidate.name === "string" &&
+    candidate.name.length > 0 &&
+    typeof candidate.enabled === "boolean" &&
+    typeof candidate.mode === "string" &&
+    (PROMPT_MODES as readonly string[]).includes(candidate.mode) &&
+    typeof candidate.text === "string"
+  );
+}
+
+/** True when the value is a well-formed scope reference (shape only). */
+export function isScopePromptRef(value: unknown): value is ScopePromptRef {
+  if (typeof value !== "object" || value === null) return false;
+  const kind = (value as { kind?: unknown }).kind;
+  if (kind === "off" || kind === "global") return true;
+  if (kind === "preset") {
+    const presetId = (value as { presetId?: unknown }).presetId;
+    return typeof presetId === "string" && presetId.length > 0;
+  }
+  if (kind === "custom") {
+    return isPromptSetting((value as { setting?: unknown }).setting);
+  }
+  return false;
+}