@schlessera/brain-ui-server 0.18.0 → 0.20.0

package/src/activity/stream.ts

@@ -0,0 +1,396 @@
+/**
+ * Live activity streaming: view-scoped subscriptions, snapshot-then-delta.
+ *
+ * All emission is change-log driven — one code path for the server's own
+ * writes and a foreign writer's (the cron wrapper). A write on this process
+ * calls `pump()` directly (near-zero latency); foreign writes are picked up
+ * by a fast poll interval that runs ONLY while at least one subscription is
+ * live. The pump reads `changesSince(cursor)` and fans each committed change
+ * out as an `activity_delta` to matching subscribers, so ordering is the
+ * change log's and a delta can never precede its commit (persist-then-emit).
+ *
+ * The subscribe handler answers with a snapshot whose per-run high-water seq
+ * and pump baseline come from ONE store read transaction — there is no gap
+ * window between snapshot and first delta, and no duplication the client's
+ * seq-discard rule cannot handle.
+ *
+ * This is deliberately the only place broadcast is per-connection filtered;
+ * every other frame keeps the host's broadcast-to-all semantics.
+ */
+import {
+  SPAN_TOOL_NAME_PREFIX,
+  type ActivityRunRollup,
+  type ActivitySpan,
+  type ActivitySpanEvent,
+  type ClientActivitySubscribe,
+  type ClientActivityUnsubscribe,
+  type ServerActivityDelta,
+  type ServerActivitySnapshot,
+} from "@schlessera/brain-ui-sdk/protocol";
+import type { Logger } from "@opentelemetry/api-logs";
+
+import type { WSContext } from "../ws/clients.js";
+import { sendTo } from "../ws/clients.js";
+import type {
+  ActivityChange,
+  ActivityStore,
+  RunRollupRow,
+  SpanEventRow,
+  SpanRow,
+} from "./store.js";
+
+/** Events per snapshot frame — keeps each frame far below the WS size cap. */
+const SNAPSHOT_EVENT_CHUNK = 100;
+/** Spans per snapshot frame, same rationale. */
+const SNAPSHOT_SPAN_CHUNK = 100;
+/** Fast-poll cadence while subscriptions exist (foreign-writer liveness). */
+const POLL_INTERVAL_MS = 1500;
+
+const TOOL_NAME_PREFIX = SPAN_TOOL_NAME_PREFIX;
+
+interface Subscription {
+  view: "index" | "session" | "run";
+  sessionId?: string;
+  runId?: string;
+}
+
+/** Store row → wire span. Lifts the typed fields the protocol promotes
+ *  (toolName, subagent enrichment) out of the naming/attr conventions. */
+export function toWireSpan(span: SpanRow): ActivitySpan {
+  const isToolLike = span.kind === "tool" || span.kind === "subagent";
+  const toolName =
+    span.kind === "subagent" && span.name.startsWith(`${TOOL_NAME_PREFIX}Agent`)
+      ? "Agent"
+      : isToolLike && span.name.startsWith(TOOL_NAME_PREFIX)
+        ? span.name.slice(TOOL_NAME_PREFIX.length)
+        : isToolLike
+          ? span.name
+          : undefined;
+  const subagent = span.kind === "subagent" ? subagentOf(span.attrs) : undefined;
+  return {
+    spanId: span.spanId,
+    runId: span.runId,
+    parentSpanId: span.parentSpanId ?? undefined,
+    name: span.name,
+    ...(toolName !== undefined ? { toolName } : {}),
+    kind: span.kind,
+    origin: span.origin,
+    sessionId: span.sessionId ?? undefined,
+    jobName: span.jobName ?? undefined,
+    startedAt: span.startedAt,
+    waitUntil: span.waitUntil ?? undefined,
+    endedAt: span.endedAt ?? undefined,
+    outcome: span.outcome ?? undefined,
+    outcomeReason: span.outcomeReason ?? undefined,
+    usage: hasUsage(span) ? { ...span.usage } : undefined,
+    ...(subagent ? { subagent } : {}),
+    attrs: Object.keys(span.attrs).length > 0 ? span.attrs : undefined,
+  };
+}
+
+function subagentOf(attrs: Record<string, unknown>): ActivitySpan["subagent"] {
+  const type = attrs["subagent.type"];
+  const description = attrs["subagent.description"];
+  const summary = attrs["subagent.summary"];
+  const totalTokens = attrs["subagent.total_tokens"];
+  const subagent = {
+    ...(typeof type === "string" ? { type } : {}),
+    ...(typeof description === "string" ? { description } : {}),
+    ...(typeof summary === "string" ? { summary } : {}),
+    ...(typeof totalTokens === "number" ? { totalTokens } : {}),
+  };
+  return Object.keys(subagent).length > 0 ? subagent : undefined;
+}
+
+export function toWireEvent(event: SpanEventRow): ActivitySpanEvent {
+  return {
+    spanId: event.spanId,
+    eventIndex: event.eventIndex,
+    ts: event.ts,
+    eventType: event.eventType,
+    payload: event.payload,
+    ...(event.truncated ? { truncated: true } : {}),
+  };
+}
+
+/** Store rollup → wire rollup: nullable columns become omitted-when-null per
+ *  the optional wire contract (effectiveCostUsd stays explicit — null means
+ *  unknown, and omitting it would let a client mistake unknown for absent). */
+export function toWireRollup(r: RunRollupRow): ActivityRunRollup {
+  return {
+    origin: r.origin,
+    name: r.name,
+    sessionId: r.sessionId,
+    jobName: r.jobName,
+    startedAt: r.startedAt,
+    endedAt: r.endedAt,
+    outcome: r.outcome,
+    durationMs: r.durationMs,
+    spanCount: r.spanCount,
+    costUsd: r.costUsd,
+    effectiveCostUsd: r.effectiveCostUsd,
+    billingMode: r.billingMode ?? undefined,
+    pricingEstimate: r.pricingEstimate ?? undefined,
+    failureReason: r.failureReason,
+  };
+}
+
+export interface ActivityStream {
+  handleSubscribe(ws: WSContext, msg: ClientActivitySubscribe): void;
+  handleUnsubscribe(ws: WSContext, msg: ClientActivityUnsubscribe): void;
+  /** Forget a closed socket. */
+  dropConnection(ws: WSContext): void;
+  /** Drain new committed changes to subscribers. Reentrancy-safe. */
+  pump(): void;
+  /** Whether any connection currently watches the given session's activity. */
+  isWatched(scope: { sessionId?: string; runId?: string }): boolean;
+  /** Number of live subscriptions (all connections). */
+  subscriptionCount(): number;
+  close(): void;
+}
+
+export function createActivityStream(store: ActivityStore, log?: Logger): ActivityStream {
+  const subscriptions = new Map<WSContext, Subscription[]>();
+  let cursor = store.latestChangeCursor();
+  let pumping = false;
+  let pollHandle: ReturnType<typeof setInterval> | null = null;
+  /** runId → sessionId, learned from any span seen; a run's session never
+   *  changes, so entries are immutable. Replaces per-event store lookups
+   *  when matching event deltas against session-view subscriptions. */
+  const runSessions = new Map<string, string>();
+
+  function noteSpan(span: SpanRow): void {
+    if (span.sessionId && !runSessions.has(span.runId)) {
+      runSessions.set(span.runId, span.sessionId);
+    }
+  }
+
+  function subKey(s: Subscription): string {
+    return `${s.view}:${s.sessionId ?? ""}:${s.runId ?? ""}`;
+  }
+
+  function matches(sub: Subscription, runId: string, span?: SpanRow): boolean {
+    if (sub.view === "index") return true;
+    if (sub.view === "run") return sub.runId === runId;
+    // Session view: match by the span's session when we have it; event-only
+    // deltas resolve through the memoized run→session map.
+    if (span?.sessionId) return span.sessionId === sub.sessionId;
+    return runSessions.get(runId) === sub.sessionId;
+  }
+
+  function ensurePolling() {
+    if (pollHandle || subscriptions.size === 0) return;
+    pollHandle = setInterval(() => pump(), POLL_INTERVAL_MS);
+  }
+
+  function stopPollingIfIdle() {
+    if (pollHandle && subscriptions.size === 0) {
+      clearInterval(pollHandle);
+      pollHandle = null;
+    }
+  }
+
+  function deltaFrame(change: ActivityChange): ServerActivityDelta {
+    return change.kind === "span"
+      ? { type: "activity_delta", runId: change.runId, seq: change.seq, span: toWireSpan(change.span) }
+      : {
+          type: "activity_delta",
+          runId: change.runId,
+          seq: change.seq,
+          event: toWireEvent(change.event),
+        };
+  }
+
+  function pump(): void {
+    if (pumping) return;
+    pumping = true;
+    try {
+      // Nobody listening: skip the changes entirely, but keep the cursor at
+      // the log's head — otherwise the first subscriber's pump would replay
+      // history its snapshot already carries (harmless under the client's
+      // seq-discard rule, but pure waste). Side effects that must see every
+      // change (the notifier) keep their OWN cursor.
+      if (subscriptions.size === 0) {
+        cursor = store.latestChangeCursor();
+        return;
+      }
+      for (;;) {
+        const changes = store.changesSince(cursor, 200);
+        if (changes.length === 0) break;
+        for (const change of changes) {
+          cursor = change.changeId;
+          const span = change.kind === "span" ? change.span : undefined;
+          if (span) noteSpan(span);
+          const frame = deltaFrame(change);
+          for (const [ws, subs] of subscriptions) {
+            if (subs.some((s) => matches(s, change.runId, span))) {
+              sendTo(ws, frame);
+            }
+          }
+        }
+        if (changes.length < 200) break;
+      }
+    } catch (err) {
+      log?.emit({
+        severityText: "WARN",
+        body: "activity pump failed",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
+    } finally {
+      pumping = false;
+    }
+  }
+
+  function sendSnapshot(ws: WSContext, sub: Subscription): void {
+    let spans: SpanRow[] = [];
+    let events: SpanEventRow[] = [];
+    const highWater: Record<string, number> = {};
+
+    if (sub.view === "run" && sub.runId) {
+      const snap = store.snapshotRun(sub.runId);
+      if (snap) {
+        spans = snap.spans;
+        events = snap.events;
+        highWater[snap.runId] = snap.highWaterSeq;
+        // No pump-cursor rewind: the pump cursor can only LAG the snapshot
+        // read (it never runs ahead of the DB), so unpumped changes are
+        // already inside this snapshot's high-water and the client's
+        // seq-discard rule absorbs them when the pump catches up.
+      }
+    } else if (sub.view === "session" && sub.sessionId) {
+      for (const root of store.openRootSpans()) {
+        if (root.sessionId !== sub.sessionId) continue;
+        const snap = store.snapshotRun(root.runId);
+        if (!snap) continue;
+        spans = spans.concat(snap.spans);
+        events = events.concat(snap.events);
+        highWater[snap.runId] = snap.highWaterSeq;
+      }
+    } else {
+      // Index view: open roots only — history is the REST activity API's job.
+      for (const root of store.openRootSpans()) {
+        spans.push(root);
+        highWater[root.runId] = store.runHighWaterSeq(root.runId);
+      }
+    }
+    for (const span of spans) noteSpan(span);
+
+    const base: Omit<ServerActivitySnapshot, "spans" | "events"> = {
+      type: "activity_snapshot",
+      view: sub.view,
+      ...(sub.sessionId ? { sessionId: sub.sessionId } : {}),
+      ...(sub.runId ? { runId: sub.runId } : {}),
+      highWaterSeq: highWater,
+    };
+
+    // Chunk: first span/event batch in the base frame, then append frames
+    // for the rest (the client's applySnapshot merges append frames).
+    const wireSpans = spans.map(toWireSpan);
+    sendTo(ws, {
+      ...base,
+      spans: wireSpans.slice(0, SNAPSHOT_SPAN_CHUNK),
+      events: events.slice(0, SNAPSHOT_EVENT_CHUNK).map(toWireEvent),
+    });
+    for (let i = SNAPSHOT_SPAN_CHUNK; i < wireSpans.length; i += SNAPSHOT_SPAN_CHUNK) {
+      sendTo(ws, {
+        ...base,
+        spans: wireSpans.slice(i, i + SNAPSHOT_SPAN_CHUNK),
+        events: [],
+        append: true,
+      });
+    }
+    for (let i = SNAPSHOT_EVENT_CHUNK; i < events.length; i += SNAPSHOT_EVENT_CHUNK) {
+      sendTo(ws, {
+        ...base,
+        spans: [],
+        events: events.slice(i, i + SNAPSHOT_EVENT_CHUNK).map(toWireEvent),
+        append: true,
+      });
+    }
+  }
+
+  return {
+    handleSubscribe(ws, msg) {
+      // A scoped view without its scope id can never match anything and
+      // would only leak an all-runs snapshot shape — ignore it up front.
+      if ((msg.view === "session" && !msg.sessionId) || (msg.view === "run" && !msg.runId)) {
+        return;
+      }
+      const sub: Subscription = {
+        view: msg.view,
+        ...(msg.sessionId ? { sessionId: msg.sessionId } : {}),
+        ...(msg.runId ? { runId: msg.runId } : {}),
+      };
+      const list = subscriptions.get(ws) ?? [];
+      if (!list.some((s) => subKey(s) === subKey(sub))) list.push(sub);
+      subscriptions.set(ws, list);
+      ensurePolling();
+      try {
+        sendSnapshot(ws, sub);
+      } catch (err) {
+        log?.emit({
+          severityText: "WARN",
+          body: "activity snapshot failed",
+          attributes: { error: err instanceof Error ? err.message : String(err) },
+        });
+      }
+    },
+
+    handleUnsubscribe(ws, msg) {
+      const list = subscriptions.get(ws);
+      if (!list) return;
+      const key = subKey({
+        view: msg.view,
+        ...(msg.sessionId ? { sessionId: msg.sessionId } : {}),
+        ...(msg.runId ? { runId: msg.runId } : {}),
+      });
+      const remaining = list.filter((s) => subKey(s) !== key);
+      if (remaining.length > 0) subscriptions.set(ws, remaining);
+      else subscriptions.delete(ws);
+      stopPollingIfIdle();
+    },
+
+    dropConnection(ws) {
+      subscriptions.delete(ws);
+      stopPollingIfIdle();
+    },
+
+    pump,
+
+    isWatched(scope) {
+      for (const subs of subscriptions.values()) {
+        for (const s of subs) {
+          if (s.view === "index") return true;
+          if (scope.runId && s.view === "run" && s.runId === scope.runId) return true;
+          if (scope.sessionId && s.view === "session" && s.sessionId === scope.sessionId)
+            return true;
+        }
+      }
+      return false;
+    },
+
+    subscriptionCount() {
+      let n = 0;
+      for (const subs of subscriptions.values()) n += subs.length;
+      return n;
+    },
+
+    close() {
+      if (pollHandle) clearInterval(pollHandle);
+      pollHandle = null;
+      subscriptions.clear();
+    },
+  };
+}
+
+function hasUsage(span: SpanRow): boolean {
+  const u = span.usage;
+  return (
+    u.inputTokens !== undefined ||
+    u.outputTokens !== undefined ||
+    u.cacheReadTokens !== undefined ||
+    u.cacheCreationTokens !== undefined ||
+    u.costUsd !== undefined ||
+    u.model !== undefined
+  );
+}

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

@@ -8,6 +8,7 @@ import { resolveServerConfig, type ServerConfig } from "./config/env.js";
 import { createHealthRoutes, createStatusRoutes } from "./routes/health.js";
 import { createBrainRoutes } from "./routes/brain.js";
 import { createSessionRoutes } from "./routes/sessions.js";
+import { createActivityRoutes } from "./routes/activity.js";
 import { createVoiceRoutes } from "./routes/voice.js";
 import { createFilesRoutes } from "./routes/files.js";
 import { createShareRoutes, shareTargetFallbackRoutes } from "./routes/share.js";
@@ -32,7 +33,10 @@ 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,
   createBackendRegistry,
@@ -171,12 +175,31 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   const db = createUiDb(config.dbPath, { log: dbLog });
   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"),
+    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({
@@ -190,6 +213,11 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
       : {}),
     maxConcurrentSessions: () => config.maxConcurrentSessions,
     wsRate: config.wsRate,
+    activity: {
+      store: activity.store,
+      stream: activity.stream,
+      query: activity.query,
+    },
   });
   const wsUpgrade = createWsUpgrade(host);
   // One instrument for every way a login can fail — passkey ceremonies and
@@ -293,6 +321,10 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     createBrainRoutes({ brain, brainPath: config.brainPath, keyterms })
   );
   app.route("/api", createSessionRoutes({ registry, db }));
+  // Behind the guard by mount position, like /api/status: the activity
+  // record leaks strictly more (session activity, errors, spend).
+  app.route("/api", createActivityRoutes({ db, store: activity.store, notifier: activity.notifier }));
+  app.route("/api", createPushRoutes({ sender: activity.pushSender }));
   app.route("/api", createVoiceRoutes({ voice: config.voice, keyterms }));
   app.route(
     "/api",
@@ -310,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",
@@ -365,6 +397,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     isTurnActive: () => host.coordinator.isTurnActive(),
     cancelActiveTurns: () => host.coordinator.cancelAll("Server shutting down"),
     close: () => {
+      activity.close();
       db.close();
     },
   };