@schlessera/brain-ui-server 0.18.0 → 0.19.0

package/src/routes/activity.ts

@@ -0,0 +1,363 @@
+import { Hono } from "hono";
+import type { Database } from "bun:sqlite";
+import {
+  isFailureOutcome,
+  type ActivityAggregate,
+  type ActivityRollups,
+  type ActivityRunDetail,
+  type ActivityRunRollup,
+  type ActivityRunSummary,
+} from "@schlessera/brain-ui-sdk/protocol";
+
+import { rowToRunRollup, type ActivityStore } from "../activity/store.js";
+import { toWireEvent, toWireSpan } from "../activity/stream.js";
+import type { ActivityNotifier } from "../activity/notify.js";
+import {
+  dismissActivityDigest,
+  digestDismissedAt,
+  generateActivityDigest,
+  latestActivityDigest,
+} from "../activity/digest.js";
+import { getSetting, setSetting } from "../db/settings.js";
+
+/**
+ * The activity record's read API. Auth-guarded like every /api route (the
+ * record leaks strictly more than /api/status, which is itself deliberately
+ * behind the guard).
+ *
+ * Resolution rules (origin R26): a run id that ever existed resolves — to
+ * the full span tree while detail is retained, to its rollup ("detail
+ * pruned") afterwards; only never-existed ids 404. Cost/token aggregates
+ * read per-run rollups, which carry ROOT-span accounting only.
+ */
+export function createActivityRoutes(deps: {
+  db: Database;
+  store: ActivityStore;
+  notifier?: ActivityNotifier;
+}): Hono {
+  const { db, store, notifier } = deps;
+
+  return new Hono()
+    .get("/activity/digest", (c) => {
+      try {
+        // An authenticated fetch IS the app opening — the marker the next
+        // digest window's framing leans on.
+        setSetting(db, "activity.lastVisitAt", Date.now());
+        return c.json({
+          digest: latestActivityDigest(db),
+          dismissedAt: digestDismissedAt(db),
+        });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to load digest" },
+          500
+        );
+      }
+    })
+
+    .post("/activity/digest/dismiss", (c) => {
+      try {
+        dismissActivityDigest(db);
+        return c.json({ ok: true });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to dismiss" },
+          500
+        );
+      }
+    })
+
+    .post("/activity/digest/generate", (c) => {
+      // Manual trigger (the cron job calls generateActivityDigest directly
+      // through the script; this exists for dev and for a pull-to-refresh).
+      try {
+        return c.json({ digest: generateActivityDigest(db) });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to generate" },
+          500
+        );
+      }
+    })
+
+    .get("/activity/inbox", (c) => {
+      try {
+        return c.json({ intents: notifier?.inbox() ?? [] });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to list inbox" },
+          500
+        );
+      }
+    })
+
+    .post("/activity/inbox/ack-all", (c) => {
+      try {
+        return c.json({ acknowledged: notifier?.acknowledgeAll() ?? 0 });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to acknowledge" },
+          500
+        );
+      }
+    })
+
+    .post("/activity/inbox/:id/ack", (c) => {
+      const id = Number(c.req.param("id"));
+      if (!Number.isInteger(id) || id < 1) return c.json({ error: "Bad intent id" }, 400);
+      try {
+        const ok = notifier?.acknowledge(id) ?? false;
+        return ok ? c.json({ ok: true }) : c.json({ error: "Unknown intent" }, 404);
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to acknowledge" },
+          500
+        );
+      }
+    })
+    .get("/activity/runs", (c) => {
+      try {
+        const limit = Math.min(Math.max(Number(c.req.query("limit") ?? 50) || 50, 1), 200);
+        const before = Number(c.req.query("before")) || Date.now() + 1;
+        const origin = c.req.query("origin");
+        const job = c.req.query("job");
+        const session = c.req.query("session");
+        const status = c.req.query("status");
+
+        // Live first (open roots), then history from rollups. Rollups exist
+        // for every finished run (terminal writes upsert them), so one table
+        // serves the history list regardless of pruning state.
+        const live: ActivityRunSummary[] = store
+          .openRootSpans()
+          .filter((s) => !origin || s.origin === origin)
+          .filter((s) => !job || s.jobName === job)
+          .filter((s) => !session || s.sessionId === session)
+          .map((s) => ({
+            runId: s.runId,
+            origin: s.origin,
+            name: s.name,
+            sessionId: s.sessionId,
+            jobName: s.jobName,
+            startedAt: s.startedAt,
+            endedAt: null,
+            outcome: null,
+            running: true,
+            durationMs: null,
+            costUsd: s.usage.costUsd ?? null,
+            failureReason: null,
+            detailPruned: false,
+          }));
+
+        const filters: string[] = ["started_at < ?"];
+        const params: unknown[] = [before];
+        if (origin) {
+          filters.push("origin = ?");
+          params.push(origin);
+        }
+        if (job) {
+          filters.push("job_name = ?");
+          params.push(job);
+        }
+        if (session) {
+          filters.push("session_id = ?");
+          params.push(session);
+        }
+        if (status) {
+          filters.push("outcome = ?");
+          params.push(status);
+        }
+        if (live.length > 0) {
+          filters.push(`run_id NOT IN (${live.map(() => "?").join(", ")})`);
+          params.push(...live.map((r) => r.runId));
+        }
+        const history: ActivityRunSummary[] = (
+          db
+            .query(
+              `SELECT * FROM activity_run_rollups WHERE ${filters.join(" AND ")}
+               ORDER BY started_at DESC LIMIT ?`
+            )
+            .all(...(params as never[]), limit) as any[]
+        )
+          .map(rowToRunRollup)
+          .map((r) => ({
+            runId: r.runId,
+            origin: r.origin,
+            name: r.name,
+            sessionId: r.sessionId,
+            jobName: r.jobName,
+            startedAt: r.startedAt,
+            endedAt: r.endedAt,
+            outcome: r.outcome,
+            running: false,
+            durationMs: r.durationMs,
+            costUsd: r.costUsd,
+            failureReason: r.failureReason,
+            detailPruned: r.detailPruned,
+          }));
+
+        return c.json({ live, history });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to list activity" },
+          500
+        );
+      }
+    })
+
+    .get("/activity/runs/:runId", (c) => {
+      const runId = c.req.param("runId");
+      try {
+        const snapshot = store.snapshotRun(runId);
+        if (snapshot) {
+          // Through the SAME wire mappers the live stream uses: a raw
+          // SpanRow serializes null fields where the wire contract omits
+          // them, which broke the client's `outcome === undefined`
+          // liveness test on REST-loaded runs.
+          const detail: ActivityRunDetail = {
+            runId,
+            detailPruned: false,
+            spans: snapshot.spans.map(toWireSpan),
+            events: snapshot.events.map(toWireEvent),
+            highWaterSeq: snapshot.highWaterSeq,
+          };
+          return c.json(detail);
+        }
+        const row = db
+          .query("SELECT * FROM activity_run_rollups WHERE run_id = ?")
+          .get(runId) as any;
+        if (!row) return c.json({ error: "Unknown run" }, 404);
+        const r = rowToRunRollup(row);
+        const rollup: ActivityRunRollup = {
+          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,
+          failureReason: r.failureReason,
+        };
+        const detail: ActivityRunDetail = { runId, detailPruned: true, rollup };
+        return c.json(detail);
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to load run" },
+          500
+        );
+      }
+    })
+
+    .get("/activity/rollups", (c) => {
+      try {
+        const days = Math.min(Number(c.req.query("days") ?? 7) || 7, 90);
+        const since = Date.now() - days * 24 * 60 * 60 * 1000;
+        // The day boundary is the USER'S day, not UTC's — cron runs in UTC
+        // but nobody reviews spend in it. Configurable server-side.
+        const timeZone = getSetting<string>(db, "activity.timezone", "UTC");
+        const dayOf = makeDayFormatter(timeZone);
+
+        // Job/session aggregates group SQL-side; the per-day fold stays in
+        // JS because only Intl knows the configured timezone's day boundary.
+        const rows = db
+          .query(
+            `SELECT started_at, outcome, duration_ms, cost_usd, input_tokens,
+                    output_tokens, cache_read_tokens, cache_creation_tokens
+             FROM activity_run_rollups WHERE started_at >= ?`
+          )
+          .all(since) as any[];
+        const byDay = new Map<string, ActivityAggregate>();
+        for (const r of rows) {
+          add(byDay, dayOf(r.started_at), r);
+        }
+
+        const rollups: ActivityRollups = {
+          timeZone,
+          days: [...byDay.entries()]
+            .map(([key, a]) => ({ day: key, ...a }))
+            .sort((a, b) => (a.day < b.day ? 1 : -1)),
+          jobs: groupedAggregates(db, since, "job_name").map(({ key, ...a }) => ({
+            jobName: key,
+            ...a,
+          })),
+          sessions: groupedAggregates(db, since, "session_id").map(({ key, ...a }) => ({
+            sessionId: key,
+            ...a,
+          })),
+        };
+        return c.json(rollups);
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to aggregate" },
+          500
+        );
+      }
+    });
+}
+
+/**
+ * SQL-side aggregation per group key. The failure predicate mirrors the
+ * SDK's `isFailureOutcome` — it cannot be shared into SQL, so keep the two
+ * in sync.
+ */
+function groupedAggregates(
+  db: Database,
+  since: number,
+  column: "job_name" | "session_id"
+): Array<ActivityAggregate & { key: string }> {
+  return db
+    .query(
+      `SELECT ${column} AS key,
+              COUNT(*) AS runs,
+              SUM(CASE WHEN outcome IN ('error', 'timeout', 'interrupted') THEN 1 ELSE 0 END) AS failures,
+              SUM(COALESCE(cost_usd, 0)) AS costUsd,
+              SUM(COALESCE(input_tokens, 0)) AS inputTokens,
+              SUM(COALESCE(output_tokens, 0)) AS outputTokens,
+              SUM(COALESCE(cache_read_tokens, 0)) AS cacheReadTokens,
+              SUM(COALESCE(cache_creation_tokens, 0)) AS cacheCreationTokens,
+              SUM(COALESCE(duration_ms, 0)) AS durationMs
+       FROM activity_run_rollups
+       WHERE started_at >= ? AND ${column} IS NOT NULL
+       GROUP BY ${column}`
+    )
+    .all(since) as Array<ActivityAggregate & { key: string }>;
+}
+
+function add(map: Map<string, ActivityAggregate>, key: string, r: any): void {
+  const a =
+    map.get(key) ??
+    ({
+      runs: 0,
+      failures: 0,
+      costUsd: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+      durationMs: 0,
+    } satisfies ActivityAggregate);
+  a.runs += 1;
+  if (isFailureOutcome(r.outcome)) {
+    a.failures += 1;
+  }
+  a.costUsd += r.cost_usd ?? 0;
+  a.inputTokens += r.input_tokens ?? 0;
+  a.outputTokens += r.output_tokens ?? 0;
+  a.cacheReadTokens += r.cache_read_tokens ?? 0;
+  a.cacheCreationTokens += r.cache_creation_tokens ?? 0;
+  a.durationMs += r.duration_ms ?? 0;
+  map.set(key, a);
+}
+
+/** YYYY-MM-DD in the given zone; a bad zone degrades loudly to UTC once. */
+function makeDayFormatter(timeZone: string): (ms: number) => string {
+  let fmt: Intl.DateTimeFormat;
+  try {
+    fmt = new Intl.DateTimeFormat("en-CA", { timeZone, dateStyle: "short" });
+  } catch {
+    fmt = new Intl.DateTimeFormat("en-CA", { timeZone: "UTC", dateStyle: "short" });
+  }
+  return (ms) => fmt.format(new Date(ms));
+}

package/src/routes/push.ts

@@ -0,0 +1,90 @@
+import { Hono } from "hono";
+import { z } from "zod";
+
+import type { PushSender } from "../activity/push-sender.js";
+
+/**
+ * Push subscription lifecycle. Behind the auth guard by mount position —
+ * the public key is per-deployment (not build-time), and subscribing is a
+ * write into the notification fan-out, which only the authenticated user
+ * may do. The VAPID PRIVATE key has no route, here or anywhere.
+ */
+const subscribeSchema = z.object({
+  subscription: z.object({
+    endpoint: z.url().max(2048),
+    keys: z.object({
+      p256dh: z.string().min(1).max(512),
+      auth: z.string().min(1).max(512),
+    }),
+  }),
+  label: z.string().max(120).optional(),
+});
+
+const unsubscribeSchema = z.object({
+  endpoint: z.url().max(2048),
+});
+
+export function createPushRoutes(deps: { sender: PushSender }): Hono {
+  const { sender } = deps;
+
+  return new Hono()
+    .get("/push/public-key", (c) => {
+      try {
+        return c.json({ publicKey: sender.publicKey() });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Push unavailable" },
+          500
+        );
+      }
+    })
+
+    .get("/push/subscriptions", (c) => {
+      try {
+        // Endpoints are capability URLs — list only metadata.
+        return c.json({
+          subscriptions: sender.subscriptions().map((s) => ({
+            label: s.label,
+            createdAt: s.createdAt,
+            lastUsedAt: s.lastUsedAt,
+            // Enough for the client to recognize its own registration.
+            endpointHash: hashEndpoint(s.endpoint),
+          })),
+        });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Failed to list" },
+          500
+        );
+      }
+    })
+
+    .post("/push/subscribe", async (c) => {
+      try {
+        const body = subscribeSchema.parse(await c.req.json());
+        sender.subscribe(body.subscription, body.label);
+        return c.json({ ok: true });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Bad subscription" },
+          400
+        );
+      }
+    })
+
+    .post("/push/unsubscribe", async (c) => {
+      try {
+        const body = unsubscribeSchema.parse(await c.req.json());
+        return c.json({ removed: sender.unsubscribe(body.endpoint) });
+      } catch (err) {
+        return c.json(
+          { error: err instanceof Error ? err.message : "Bad request" },
+          400
+        );
+      }
+    });
+}
+
+function hashEndpoint(endpoint: string): string {
+  return new Bun.CryptoHasher("sha256").update(endpoint).digest("hex").slice(0, 16);
+}

package/src/routes/sessions.ts

@@ -19,13 +19,33 @@ export function createSessionRoutes(deps: {
   .get("/sessions", async (c) => {
     try {
       const backends = await registry.getBackends();
+      // The catalog's accounting (total_cost_usd, num_turns) was write-only
+      // for years on the default backend, whose listSessions hardcodes
+      // zeros — merge the stored numbers in so the drawer's cost renders
+      // from what the server actually recorded.
+      const accounting = new Map(
+        (
+          db
+            .query("SELECT id, total_cost_usd AS cost, num_turns AS turns FROM sessions")
+            .all() as Array<{ id: string; cost: number | null; turns: number | null }>
+        ).map((r) => [r.id, r])
+      );
       const sessions = (
         await Promise.all(
           backends.map(async (backend) =>
-            (await backend.listSessions()).map((session) => ({
-              ...session,
-              backendId: backend.id,
-            }))
+            (await backend.listSessions()).map((session) => {
+              const stored = accounting.get(session.id);
+              return {
+                ...session,
+                ...(stored?.cost && session.totalCostUsd === 0
+                  ? { totalCostUsd: stored.cost }
+                  : {}),
+                ...(stored?.turns && session.numTurns === 0
+                  ? { numTurns: stored.turns }
+                  : {}),
+                backendId: backend.id,
+              };
+            })
           )
         )
       )

package/src/ws/bridge.ts

@@ -1,4 +1,5 @@
 import type {
+  ActivityQuery,
   BackendBridge,
   PermissionDecision,
   AskUserResult,
@@ -8,13 +9,15 @@ import { BackendBusyError, BackendRequestError } from "@schlessera/brain-ui-sdk/
 import { withTurnScope } from "./frames.js";
 import type { RunningTurn } from "./turns.js";
 import type { WsHost } from "./host.js";
+import type { TurnRecorder } from "../activity/recorder.js";
 
 /** Build the per-turn bridge the backend drives. */
 export function makeBridge(
   host: WsHost,
   turn: RunningTurn,
   promptText: string,
-  backendId: string
+  backendId: string,
+  recorder?: TurnRecorder
 ): BackendBridge {
   const { coordinator, catalog } = host;
   // Capture the turn identity at construction: the slot's turnId is re-minted
@@ -22,6 +25,7 @@ export function makeBridge(
   // through this bridge after its startTurn resolved. Stamping from the live
   // field would attribute those to the NEXT turn.
   const turnId = turn.turnId;
+  const queryActivity = host.activity?.query;
   return {
     emit: (message) => {
       let msg = message;
@@ -36,6 +40,11 @@ export function makeBridge(
         // later fails or is cancelled must not leave an unowned transcript.
         catalog.persistSessionStub(msg.sessionId, promptText, turn.providerId, backendId);
       }
+      // Persist-then-emit: the span write commits before the frame goes out,
+      // so a subscriber's snapshot can never be behind what it just saw live.
+      // Late frames through a previous turn's bridge stay un-recorded — the
+      // recorder belongs to ONE turn identity.
+      if (turn.turnId === turnId) recorder?.observeFrame(msg);
       host.sendToClients(withTurnScope(msg, turn, turnId));
       if (msg.type === "result") {
         // Only the live turn's own result may set its disposition — a late
@@ -87,9 +96,27 @@ export function makeBridge(
           resolve({ behavior: "deny", message: "Duplicate tool-approval id" });
           return;
         }
-        coordinator.pendingApprovals.set(req.toolUseId, { turn, turnId, request: req, resolve });
+        // The decision stamps the wait/execution boundary on the tool span
+        // (grant) or lands the denied outcome (deny) before the backend's
+        // own error tool_result can mislabel it — write-once protects it.
+        const recorded = (decision: PermissionDecision) => {
+          recorder?.onApprovalDecision(req.toolUseId, decision.behavior === "allow");
+          resolve(decision);
+        };
+        coordinator.pendingApprovals.set(req.toolUseId, {
+          turn,
+          turnId,
+          request: req,
+          resolve: recorded,
+        });
       });
     },
+    ...(recorder
+      ? { activity: (event: Parameters<NonNullable<BackendBridge["activity"]>>[0]) => recorder.observeActivity(event) }
+      : {}),
+    ...(queryActivity
+      ? { queryActivity: async (query: ActivityQuery) => queryActivity(query) }
+      : {}),
     askUser: (requestId, questions) => {
       host.sendToClients(
         withTurnScope({ type: "ask_user_request", requestId, questions }, turn, turnId)

package/src/ws/connection.ts

@@ -75,7 +75,14 @@ export function createWsHandlers(host: WsHost) {
       host.sendMessage(ws, {
         type: "server_hello",
         protocolRev: PROTOCOL_REV,
-        capabilities: { multiSession: true, askUser: true, location: true },
+        capabilities: {
+          multiSession: true,
+          askUser: true,
+          location: true,
+          // Advertised only when this host records activity — a client on an
+          // activity-less host knows subscribing would be pointless.
+          ...(host.activity ? { activity: true } : {}),
+        },
       });
 
       // Snapshot-on-connect only for the single-running-session case (backward
@@ -214,6 +221,7 @@ export function createWsHandlers(host: WsHost) {
         host.reportAbnormalClose(code);
       }
       host.clients.remove(ws);
+      host.activity?.stream.dropConnection(ws);
       // Turns keep running in the background. Once the LAST client leaves,
       // reject only the requests that need a live client RIGHT NOW (location,
       // mask). Approvals and ask-user cards survive the disconnect and are

package/src/ws/dispatch.ts

@@ -177,6 +177,19 @@ export async function handleClientMessage(
       break;
     }
 
+    case "activity_subscribe": {
+      // View-scoped opt-in: without a subscription this connection never
+      // receives an activity frame. No turn correlation — subscriptions are
+      // connection state, not turn state.
+      host.activity?.stream.handleSubscribe(ws, msg);
+      break;
+    }
+
+    case "activity_unsubscribe": {
+      host.activity?.stream.handleUnsubscribe(ws, msg);
+      break;
+    }
+
     case "session_resume": {
       host.sendMessage(ws, {
         type: "session_info",

package/src/ws/host.ts

@@ -5,6 +5,16 @@ import type { SessionCatalog } from "./session-catalog.js";
 import type { BackendRegistry } from "../agent/backend.js";
 import { createSilentObservability, type Observability } from "../observability/index.js";
 import { FrameRateLimiter } from "./rate-limit.js";
+import type { ActivityStore } from "../activity/store.js";
+import type { ActivityStream } from "../activity/stream.js";
+
+/** The activity record and its live stream, when the host records activity. */
+export interface ActivityRuntime {
+  store: ActivityStore;
+  stream: ActivityStream;
+  /** Read seam for the agent-facing query tool (bridge.queryActivity). */
+  query?: (query: import("@schlessera/brain-ui-sdk/server").ActivityQuery) => Record<string, unknown>;
+}
 
 /** Host-side turn timeout. The backend no longer times out — the host owns it. */
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
@@ -65,6 +75,12 @@ export interface WsHostOptions {
    * fronting the socket with its own limiter wants.
    */
   wsRate?: { ratePerSecond: number; burst: number };
+  /**
+   * Activity recording (span store + live stream). Optional: a host without
+   * one records nothing and never sends activity frames — which is also what
+   * most existing tests want.
+   */
+  activity?: ActivityRuntime;
 }
 
 /** Identity of one turn, as it appears on a log record. */
@@ -102,6 +118,7 @@ export class WsHost {
   maxConcurrentSessions: () => number;
   readonly observability: Observability;
   readonly wsRate: { ratePerSecond: number; burst: number } | null;
+  readonly activity: ActivityRuntime | null;
   /** Scoped instruments, resolved once — `[ws]` is the existing log prefix. */
   readonly log: ReturnType<Observability["logger"]>;
   private readonly framesDropped: ReturnType<
@@ -130,6 +147,7 @@ export class WsHost {
     this.observability = options.observability ?? createSilentObservability();
     this.wsRate =
       options.wsRate && options.wsRate.ratePerSecond > 0 ? options.wsRate : null;
+    this.activity = options.activity ?? null;
     this.log = this.observability.logger("ws");
     const meter = this.observability.meter("ws");
     this.framesDropped = meter.createCounter("ws.frames.dropped", {