@schlessera/brain-ui-server 0.19.0 → 0.20.0

package/src/agent/backend.ts

@@ -1,7 +1,7 @@
 import type { Logger } from "@opentelemetry/api-logs";
 import { createRequire } from "module";
 import type { AgentConfig } from "../config/env.js";
-import type { ProviderInfo } from "@schlessera/brain-ui-sdk";
+import type { BillingMode, ProviderInfo } from "@schlessera/brain-ui-sdk";
 import type {
   AgentBackend,
   BackendCapabilities,
@@ -175,6 +175,12 @@ export interface BackendRegistryOptions {
    * sessions pinned to it. Defaults to "nothing hidden".
    */
   getHiddenModelIds?: () => string[];
+  /**
+   * Per-profile billing-mode overrides (from the app's settings table).
+   * Consulted LAST: an override wins over both the declared-credential rule
+   * and the ambient predicate. Defaults to "no overrides".
+   */
+  getBillingOverrides?: () => Record<string, BillingMode>;
   /**
    * Where the registry and its backends report. Adapted to the backends'
    * minimal callback ({@link BackendLogFn}) before crossing the package
@@ -197,9 +203,11 @@ export interface BackendRegistry {
   /** Resolve a persisted backend id, falling back for legacy/unknown sessions. */
   getBackendForSession(backendId: string | null | undefined): Promise<AgentBackend>;
   /**
-   * Every available profile, tagged with its owning backend id. Hidden
-   * profiles are omitted by default (this feeds the picker); the settings
-   * screen passes `includeHidden` to render the full catalog.
+   * Every available profile, tagged with its owning backend id and (when the
+   * registry can classify it) its resolved `billingMode` — settings override
+   * applied last. Hidden profiles are omitted by default (this feeds the
+   * picker); the settings screen passes `includeHidden` to render the full
+   * catalog.
    */
   listAllProviders(options?: { includeHidden?: boolean }): Promise<ProviderInfo[]>;
   /** Per-backend capability metadata exposed by the providers route. */
@@ -372,6 +380,32 @@ export function createBackendRegistry(
   let cachedRegistry: Promise<RegistrySnapshot> | null = null;
   let modelSource: ClaudeModelSource | null = null;
 
+  /**
+   * Declared profiles carrying their OWN credential env vars
+   * (authTokenEnv/apiKeyEnv) — api-billed regardless of the ambient
+   * credential. Populated when the Claude roster resolves, which happens
+   * before any profile can be listed or run.
+   */
+  const declaredApiProfileIds = new Set<string>();
+  /** The Claude backend's id, once built — profiles on any OTHER backend (pi) have no subscription path. */
+  let claudeBackendId: string | null = null;
+
+  /**
+   * Base billing classification for one roster entry, BEFORE the settings
+   * override (applied last by the shared accessor surface):
+   *   - a non-Claude backend (pi) → "api";
+   *   - a declared profile with explicit credentials → "api";
+   *   - everything ambient (built-in default, discovered models, declared
+   *     entries without their own credentials) → the env-resolved ambient
+   *     mode (subscription iff the OAuth token is present and no
+   *     ANTHROPIC_API_KEY — the Agent SDK's own precedence).
+   */
+  function classifyBilling(profile: ProviderInfo & { backendId: string }): BillingMode {
+    if (claudeBackendId === null || profile.backendId !== claudeBackendId) return "api";
+    if (declaredApiProfileIds.has(profile.id)) return "api";
+    return agent.ambientBilling;
+  }
+
   /**
    * Declared profiles (built-in default + BRAIN_UI_CLAUDE_PROFILES) plus every
    * discovered model whose id isn't already declared. Declared wins: the env
@@ -469,6 +503,9 @@ export function createBackendRegistry(
         );
       }
       seen.add(input.id);
+      // The same non-empty test defineProfiles applies to requiredEnvKeys: a
+      // profile bringing its own credential env var is api-billed.
+      if (input.authTokenEnv || input.apiKeyEnv) declaredApiProfileIds.add(input.id);
     }
 
     const declared = (inputs as ClaudeProfileInput[]).map((input) => ({
@@ -503,7 +540,7 @@ export function createBackendRegistry(
       ttlMs: agent.modelTtlMs,
     });
 
-    return claude.createClaudeBackend({
+    const backend = claude.createClaudeBackend({
       brainPath,
       claudeCodePath: agent.claudeCodePath,
       ...(backendLog ? { log: backendLog } : {}),
@@ -517,6 +554,8 @@ export function createBackendRegistry(
       profiles: () =>
         mergeDiscovered(claude, declared, modelSource?.list() ?? []),
     });
+    claudeBackendId = backend.id;
+    return backend;
   }
 
   async function buildPiBackend(): Promise<AgentBackend> {
@@ -566,7 +605,13 @@ export function createBackendRegistry(
       await getRegistry();
       return modelSource;
     },
-    options.log
+    options.log,
+    {
+      classify: classifyBilling,
+      ...(options.getBillingOverrides
+        ? { getOverrides: options.getBillingOverrides }
+        : {}),
+    }
   );
 }
 
@@ -579,14 +624,23 @@ export function createBackendRegistry(
 export function createStaticBackendRegistry(
   backends: AgentBackend[],
   defaultBackendId = backends[0]?.id ?? "",
-  options: { getHiddenModelIds?: () => string[]; log?: Logger } = {}
+  options: {
+    getHiddenModelIds?: () => string[];
+    getBillingOverrides?: () => Record<string, BillingMode>;
+    log?: Logger;
+  } = {}
 ): BackendRegistry {
   const snapshot = buildSnapshot(backends, defaultBackendId);
   return makeRegistry(
     async () => snapshot,
     options.getHiddenModelIds ?? (() => []),
     async () => null,
-    options.log
+    options.log,
+    // No classifier: an embedder's backends carry no credential topology this
+    // registry could reason about, so only an explicit override sets a mode.
+    options.getBillingOverrides
+      ? { getOverrides: options.getBillingOverrides }
+      : {}
   );
 }
 
@@ -595,7 +649,13 @@ function makeRegistry(
   getRegistry: () => Promise<RegistrySnapshot>,
   getHidden: () => string[],
   getModelSource: () => Promise<ModelDiscoverySource | null>,
-  log?: Logger
+  log?: Logger,
+  billing: {
+    /** Base classification per roster entry; absent = the registry cannot classify. */
+    classify?: (profile: ProviderInfo & { backendId: string }) => BillingMode;
+    /** Settings overrides, consulted LAST — an override wins over `classify`. */
+    getOverrides?: () => Record<string, BillingMode>;
+  } = {}
 ): BackendRegistry {
   let profileSnapshot: ProfileSnapshot | null = null;
 
@@ -641,6 +701,20 @@ function makeRegistry(
     }
   }
 
+  /** Same degradation discipline: a failed override read means derived modes apply. */
+  function billingOverrides(): Record<string, BillingMode> {
+    try {
+      return billing.getOverrides?.() ?? {};
+    } catch (err) {
+      log?.emit({
+        severityText: "WARN",
+        body: "could not read billing overrides; using derived billing modes",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
+      return {};
+    }
+  }
+
   return {
     async getBackends() {
       return (await getRegistry()).backends;
@@ -681,11 +755,18 @@ function makeRegistry(
       const registry = await getRegistry();
       const snapshot = await getProfileSnapshot();
       const hidden = options.includeHidden ? new Set<string>() : hiddenIds();
+      // Read fresh on every listing (not memoized with the snapshot), so a
+      // saved override is live for the very next run without invalidation.
+      const overrides = billingOverrides();
 
       return registry.backends.flatMap((backend) =>
         (snapshot.byBackend.get(backend.id) ?? [])
           .filter((profile) => !hidden.has(profile.id))
-          .map((profile) => ({ ...profile, backendId: backend.id }))
+          .map((profile) => {
+            const entry = { ...profile, backendId: backend.id };
+            const billingMode = overrides[profile.id] ?? billing.classify?.(entry);
+            return billingMode ? { ...entry, billingMode } : entry;
+          })
       );
     },
 

package/src/app.ts

@@ -33,8 +33,9 @@ import {
   type PasskeyContext,
 } from "./middleware/passkeys.js";
 import { createUiDb } from "./db/client.js";
-import { getHiddenModelIds } from "./db/settings.js";
+import { getBillingOverrides, getHiddenModelIds } from "./db/settings.js";
 import { createActivityRuntime } from "./activity/runtime.js";
+import { createModelPricing } from "./pricing/model-pricing.js";
 import { createPushRoutes } from "./routes/push.js";
 import {
   assertBackendResolvable,
@@ -175,15 +176,30 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   const brain = createBrainClient({ brainPath: config.brainPath });
   const cron = createCronScheduler({ db, brain, log: observability.logger("cron") });
 
+  // Model pricing for rollup-time effective cost: constructed here because
+  // the config owns enabled/TTL/brainPath, shared through the activity
+  // runtime. The first refresh warms in the background — ensureFresh never
+  // rejects and no rollup ever waits on the network (resolve() is sync).
+  const pricing = createModelPricing({
+    brainPath: config.brainPath,
+    enabled: config.pricing.enabled,
+    ttlMs: config.pricing.ttlMs,
+  });
+  void pricing.ensureFresh();
+
   // Activity record: span store + live stream + notifications + lifecycle
   // sweeps, owned by the runtime (see activity/runtime.ts).
-  const activity = createActivityRuntime(db, { log: observability.logger("activity") });
+  const activity = createActivityRuntime(db, {
+    log: observability.logger("activity"),
+    pricing,
+  });
   const registry =
     options.registry ??
     createBackendRegistry({
       brainPath: config.brainPath,
       agent: config.agent,
       getHiddenModelIds: () => getHiddenModelIds(db, dbLog),
+      getBillingOverrides: () => getBillingOverrides(db, dbLog),
       log: observability.logger("agent"),
     });
   const host = new WsHost({
@@ -326,7 +342,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   app.route("/api", createProviderRoutes({ registry }));
   app.route(
     "/api",
-    createModelRoutes({ registry, db, log: observability.logger("models") })
+    createModelRoutes({ registry, db, pricing, log: observability.logger("models") })
   );
   app.route(
     "/api",

package/src/config/env.ts

@@ -15,6 +15,8 @@
 
 import { join } from "path";
 
+import type { BillingMode } from "@schlessera/brain-ui-sdk/protocol";
+
 import { SEVERITIES, type Severity } from "../observability/types.js";
 import { envFlag } from "./env-core.js";
 
@@ -257,6 +259,25 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
     default: "(none)",
     required: false,
   },
+  {
+    name: "CLAUDE_CODE_OAUTH_TOKEN",
+    description:
+      "Consulted for PRESENCE only, to classify billing: with it set and no " +
+      "ANTHROPIC_API_KEY, ambient-credential Claude profiles (the built-in " +
+      "default and discovered models) count as subscription-billed. The token " +
+      "itself is consumed by the Claude backend / Agent SDK, not this package.",
+    default: null,
+    required: false,
+  },
+  {
+    name: "ANTHROPIC_API_KEY",
+    description:
+      "Consulted for PRESENCE only, to classify billing: when set it wins " +
+      "over CLAUDE_CODE_OAUTH_TOKEN (mirroring the Agent SDK's credential " +
+      "precedence), so ambient-credential profiles count as api-billed.",
+    default: null,
+    required: false,
+  },
   {
     name: "BRAIN_UI_MODEL_DISCOVERY",
     description:
@@ -270,10 +291,23 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
     default: "24",
     required: false,
   },
+  {
+    name: "BRAIN_UI_PRICING_DISCOVERY",
+    description:
+      'Remote model-pricing refresh (LiteLLM + OpenRouter catalogs); "0"/"off"/"false" disables, and runs then roll up with unknown effective cost. Defaults ON, except under a test runner (NODE_ENV=test) where it defaults OFF.',
+    default: "on (off under NODE_ENV=test)",
+    required: false,
+  },
+  {
+    name: "BRAIN_UI_PRICING_TTL_HOURS",
+    description: "How long a fetched model-pricing table stays fresh, in hours.",
+    default: "24",
+    required: false,
+  },
   {
     name: "NODE_ENV",
     description:
-      "Only consulted for test-runner detection: flips the model-discovery default to off under bun test. Never gates any security behavior.",
+      "Only consulted for test-runner detection: flips the model-discovery and pricing-discovery defaults to off under bun test. Never gates any security behavior.",
     default: "(unset)",
     required: false,
   },
@@ -347,6 +381,15 @@ export interface AgentConfig {
   profilesJson: string | null;
   modelDiscovery: boolean;
   modelTtlMs: number;
+  /**
+   * Billing classification for profiles running on AMBIENT credentials (the
+   * built-in default and discovered models): "subscription" iff the
+   * environment holds a CLAUDE_CODE_OAUTH_TOKEN and no ANTHROPIC_API_KEY —
+   * the same precedence the Agent SDK applies — else "api". Declared profiles
+   * carrying their own credential env vars are classified "api" by the
+   * registry regardless of this value.
+   */
+  ambientBilling: BillingMode;
 }
 
 export interface VoiceConfig {
@@ -380,6 +423,8 @@ export interface ServerConfig {
   webauthn: WebAuthnConfig;
   agent: AgentConfig;
   voice: VoiceConfig;
+  /** Model-pricing service (BRAIN_UI_PRICING_*); inline like wsRate. */
+  pricing: { enabled: boolean; ttlMs: number };
 }
 
 // --- resolver ----------------------------------------------------------------
@@ -438,12 +483,50 @@ function parseSeverity(raw: string | undefined): Severity {
 
 const AUTH_MODES: readonly AuthModeName[] = ["password", "tailscale", "proxy", "none"];
 
+/**
+ * Ambient billing classification from an environment (presence-only reads).
+ * The API key wins over the OAuth token — the Agent SDK's own precedence —
+ * and no usable credential at all classifies "api" (nothing
+ * subscription-billed can run without the token). Exported for the activity
+ * store's standalone default, so the cron wrapper classifies from the same
+ * predicate the server config does.
+ */
+export function resolveAmbientBillingMode(env: EnvRecord = process.env): BillingMode {
+  return !env.ANTHROPIC_API_KEY?.trim() && env.CLAUDE_CODE_OAUTH_TOKEN?.trim()
+    ? "subscription"
+    : "api";
+}
+
+/**
+ * THE derivation of the pricing config (kill switch, TTL, brain path) —
+ * consumed by resolveServerConfig and used directly by the cron wrapper's
+ * bare `createActivityStore(db)` path, where no ServerConfig exists. Kept
+ * here so process.env reads stay in the one chokepoint the env-access gate
+ * allows.
+ */
+export function resolveStandalonePricingConfig(env: EnvRecord = process.env): {
+  brainPath: string;
+  enabled: boolean;
+  ttlMs: number;
+} {
+  const ttlHours = Number(env.BRAIN_UI_PRICING_TTL_HOURS);
+  return {
+    brainPath: env.BRAIN_PATH || join(env.HOME || "/root", "brain"),
+    enabled: envFlag(env.BRAIN_UI_PRICING_DISCOVERY, env.NODE_ENV !== "test"),
+    ttlMs:
+      Number.isFinite(ttlHours) && ttlHours > 0
+        ? ttlHours * 60 * 60 * 1000
+        : 24 * 60 * 60 * 1000,
+  };
+}
+
 /**
  * Resolve an environment into a {@link ServerConfig}. Defaults to the real
  * process environment; tests pass their own record instead of mutating it.
  */
 export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig {
-  const brainPath = env.BRAIN_PATH || join(env.HOME || "/root", "brain");
+  const { brainPath, enabled: pricingEnabled, ttlMs: pricingTtlMs } =
+    resolveStandalonePricingConfig(env);
 
   const rawAuthMode = env.AUTH_MODE?.trim().toLowerCase() || null;
   const validMode = AUTH_MODES.find((mode) => mode === rawAuthMode) ?? null;
@@ -494,6 +577,7 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
       profilesJson: env.BRAIN_UI_CLAUDE_PROFILES?.trim() || null,
       modelDiscovery,
       modelTtlMs: ttlHours * 60 * 60 * 1000,
+      ambientBilling: resolveAmbientBillingMode(env),
     },
     logLevel: parseSeverity(env.BRAIN_UI_LOG_LEVEL),
     wsRate: {
@@ -506,6 +590,10 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
       keytermLimit: Number(env.VOICE_KEYTERM_LIMIT || 500),
       cacheDir: env.VOICE_CACHE_DIR || join(brainPath, ".brain-ui"),
     },
+    pricing: {
+      enabled: pricingEnabled,
+      ttlMs: pricingTtlMs,
+    },
   };
 }
 

package/src/db/settings.ts

@@ -8,8 +8,12 @@
 
 import type { Logger } from "@opentelemetry/api-logs";
 import type { Database } from "bun:sqlite";
+import { isBillingMode, type BillingMode } from "@schlessera/brain-ui-sdk/protocol";
 
 const HIDDEN_MODELS_KEY = "models.hidden";
+const BILLING_OVERRIDES_KEY = "models.billing";
+const DETAIL_RETENTION_KEY = "activity.retention.detailDays";
+const DETAIL_RETENTION_DEFAULT_DAYS = 7;
 
 export function getSetting<T>(db: Database, key: string, fallback: T, log?: Logger): T {
   const row = db
@@ -47,3 +51,55 @@ export function setHiddenModelIds(db: Database, ids: string[]): void {
   const unique = [...new Set(ids.filter((id) => typeof id === "string" && id))];
   setSetting(db, HIDDEN_MODELS_KEY, unique);
 }
+
+/**
+ * Per-profile billing-mode overrides: profile id → forced classification. A
+ * profile absent from the record is "auto" (the registry's derived mode
+ * applies). Anything that is not exactly "subscription" or "api" is dropped
+ * on read, so a corrupt row degrades to auto rather than misbilling.
+ */
+export function getBillingOverrides(
+  db: Database,
+  log?: Logger
+): Record<string, BillingMode> {
+  const value = getSetting<unknown>(db, BILLING_OVERRIDES_KEY, {}, log);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return Object.create(null);
+  }
+  // Null-prototype: profile ids are user-supplied strings — an id like
+  // "__proto__" must be an ordinary key, and a "constructor" lookup by a
+  // consumer must not resolve a prototype member.
+  const overrides: Record<string, BillingMode> = Object.create(null);
+  for (const [profileId, mode] of Object.entries(value)) {
+    if (isBillingMode(mode)) overrides[profileId] = mode;
+  }
+  return overrides;
+}
+
+/** Replace the override record (the client always sends the full record, not a delta). */
+export function setBillingOverrides(
+  db: Database,
+  overrides: Record<string, BillingMode>
+): void {
+  const clean = Object.fromEntries(
+    Object.entries(overrides).filter(
+      ([profileId, mode]) => profileId && isBillingMode(mode)
+    )
+  );
+  setSetting(db, BILLING_OVERRIDES_KEY, clean);
+}
+
+/** Minimum days a finished run keeps its detail (spans/events) before the
+ *  digest-covered prune may take it. 0 is valid (prune as soon as covered);
+ *  anything non-numeric or negative degrades to the default. */
+export function getDetailRetentionDays(db: Database, log?: Logger): number {
+  const value = getSetting<unknown>(db, DETAIL_RETENTION_KEY, DETAIL_RETENTION_DEFAULT_DAYS, log);
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return DETAIL_RETENTION_DEFAULT_DAYS;
+  }
+  return value;
+}
+
+export function setDetailRetentionDays(db: Database, days: number): void {
+  setSetting(db, DETAIL_RETENTION_KEY, days);
+}

package/src/index.ts

@@ -92,6 +92,7 @@ export {
   type SpanOutcome,
   type SpanUsage,
   type ActivityChange,
+  type RollupPricing,
 } from "./activity/store.js";
 export { createActivityStream, type ActivityStream } from "./activity/stream.js";
 export { ingestSpanSink } from "./activity/span-sink.js";