@schlessera/brain-ui-server 0.18.0 → 0.20.0

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/cron/scheduler.ts

@@ -115,15 +115,35 @@ export function createCronScheduler(deps: {
 
   return {
     getCronStatus() {
-      return jobs.map((job) => {
-        const lastRun = db
-          .query(
-            "SELECT * FROM cron_runs WHERE job_name = ? ORDER BY started_at DESC LIMIT 1"
-          )
-          .get(job.name) as any;
-
+      // Every job name that ever recorded a run, not just the two in-process
+      // triggers: module jobs and the maintain/digest crontab entries land in
+      // cron_runs through the same recorder and were previously invisible
+      // here (the "cron-status name gap"). The in-process names are unioned
+      // in so a fresh deployment still lists them before their first run.
+      // One window query yields each job's latest run.
+      const lastRuns = db
+        .query(
+          `SELECT job_name, started_at, status, duration_ms, error_message FROM (
+             SELECT *, ROW_NUMBER() OVER (
+               PARTITION BY job_name ORDER BY started_at DESC
+             ) AS rn FROM cron_runs
+           ) WHERE rn = 1 ORDER BY job_name`
+        )
+        .all() as Array<{
+        job_name: string;
+        started_at: number;
+        status: string;
+        duration_ms: number | null;
+        error_message: string | null;
+      }>;
+      const byName = new Map(lastRuns.map((r) => [r.job_name, r]));
+      const names = [
+        ...new Set([...jobs.map((j) => j.name), ...lastRuns.map((r) => r.job_name)]),
+      ];
+      return names.map((name) => {
+        const lastRun = byName.get(name);
         return {
-          name: job.name,
+          name,
           lastRunAt: lastRun?.started_at ?? null,
           lastStatus: lastRun?.status ?? null,
           lastDurationMs: lastRun?.duration_ms ?? null,

package/src/db/client.ts

@@ -26,6 +26,12 @@ export function createUiDb(dbPath: string, options: CreateUiDbOptions = {}): Dat
   const db = new Database(dbPath, { create: true });
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
+  // Two processes write this database (the server and the cron wrapper). The
+  // timeout makes a writer wait for a held lock instead of failing on it.
+  // It does NOT rescue a deferred transaction that loses the snapshot-upgrade
+  // race (that still throws SQLITE_BUSY) — which is why activity writes use
+  // immediate transactions; see src/activity/store.ts.
+  db.exec("PRAGMA busy_timeout = 5000");
   runMigrations(db, options.log);
   return db;
 }
@@ -67,11 +73,30 @@ function runMigrations(database: Database, log?: Logger) {
     log?.emit({ severityText: "INFO", body: "applying migration", attributes: { file } });
     const sql = readFileSync(join(migrationsDir, file), "utf-8");
 
-    database.transaction(() => {
-      database.exec(sql);
-      database
-        .prepare("INSERT INTO _migrations (filename, applied_at) VALUES (?, ?)")
-        .run(file, Date.now());
-    })();
+    try {
+      database.transaction(() => {
+        database.exec(sql);
+        database
+          .prepare("INSERT INTO _migrations (filename, applied_at) VALUES (?, ?)")
+          .run(file, Date.now());
+      })();
+    } catch (err) {
+      // Two processes racing a first boot: the loser's transaction fails on
+      // the UNIQUE _migrations.filename insert (or on DDL the winner already
+      // ran). If the file is now recorded as applied, treat it as such and
+      // move on; anything else is a real migration failure.
+      const nowApplied = database
+        .query("SELECT 1 FROM _migrations WHERE filename = ?")
+        .get(file);
+      const uniqueViolation =
+        err instanceof Error &&
+        err.message.includes("UNIQUE constraint failed: _migrations.filename");
+      if (!nowApplied && !uniqueViolation) throw err;
+      log?.emit({
+        severityText: "INFO",
+        body: "migration applied concurrently by another process; skipping",
+        attributes: { file },
+      });
+    }
   }
 }

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

@@ -80,6 +80,29 @@ export { createBrainClient, type BrainClient } from "./brain/client.js";
 // `cronJobs` reflects what actually ran.
 export { recordCronRun, type CronRunRecord } from "./cron/scheduler.js";
 
+// The activity record. The cron wrapper is a second PROCESS writing spans
+// into the same store (root span + heartbeat + span-sink ingest); everything
+// else consumes it through the app.
+export {
+  createActivityStore,
+  SPAN_OUTCOMES,
+  type ActivityStore,
+  type SpanRow,
+  type SpanEventRow,
+  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";
+export {
+  generateActivityDigest,
+  latestActivityDigest,
+  DIGEST_JOB_NAME,
+  type ActivityDigest,
+} from "./activity/digest.js";
+
 // Share staging: a deployment can sweep expired staging dirs at boot; the
 // intake route also sweeps opportunistically on every share.
 export { pruneShareStaging, shareStagingRoot } from "./share/staging.js";