@schlessera/brain-ui-server 0.17.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
@@ -52,6 +61,16 @@ export function makeBridge(
       }
     },
     requestPermission: (req) => {
+      if (!host.clients.hasClients()) {
+        // Not a failure — the card is parked and re-delivered on reconnect
+        // (see resendPendingInteractive) — but the wait was invisible before
+        // this line existed, and it is bounded only by the turn timeout.
+        host.log.emit({
+          severityText: "WARN",
+          body: "approval requested with no client connected; holding for reconnect",
+          attributes: { "tool.name": req.toolName, "toolUse.id": req.toolUseId },
+        });
+      }
       host.sendToClients(
         withTurnScope(
           {
@@ -77,9 +96,27 @@ export function makeBridge(
           resolve({ behavior: "deny", message: "Duplicate tool-approval id" });
           return;
         }
-        coordinator.pendingApprovals.set(req.toolUseId, { turn, turnId, 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)
@@ -96,7 +133,14 @@ export function makeBridge(
           reject(new Error("Duplicate ask-user request id"));
           return;
         }
-        coordinator.pendingAskUser.set(requestId, { turn, turnId, resolve, reject });
+        coordinator.pendingAskUser.set(requestId, {
+          turn,
+          turnId,
+          requestId,
+          questions,
+          resolve,
+          reject,
+        });
       });
     },
     getLocation: (options) => {

package/src/ws/connection.ts

@@ -2,6 +2,45 @@ import { upgradeWebSocket, websocket } from "hono/bun";
 import { PROTOCOL_REV } from "@schlessera/brain-ui-sdk/protocol";
 import { parseClientMessage } from "@schlessera/brain-ui-sdk/schemas";
 import { withTurnScope } from "./frames.js";
+import type { WSContext as WSContextType } from "./clients.js";
+
+/**
+ * Re-send every pending approval and ask-user card to a client that just
+ * connected. These survive disconnects (see drainClientBoundForTurn) precisely
+ * so this re-delivery can happen: a phone that dropped its socket at screen
+ * lock reconnects and finds the card waiting instead of a dead turn. The
+ * frames carry their original turn scope, so answering them resolves the
+ * correct turn's promise through the normal dispatch path.
+ */
+function resendPendingInteractive(host: WsHost, ws: WSContextType): void {
+  const { coordinator } = host;
+  for (const p of coordinator.pendingApprovals.values()) {
+    host.sendMessage(
+      ws,
+      withTurnScope(
+        {
+          type: "tool_approval_request",
+          toolUseId: p.request.toolUseId,
+          toolName: p.request.toolName,
+          input: p.request.input,
+          description: p.request.description,
+        },
+        p.turn,
+        p.turnId
+      )
+    );
+  }
+  for (const p of coordinator.pendingAskUser.values()) {
+    host.sendMessage(
+      ws,
+      withTurnScope(
+        { type: "ask_user_request", requestId: p.requestId, questions: p.questions },
+        p.turn,
+        p.turnId
+      )
+    );
+  }
+}
 import { sendSessionHistory } from "./history.js";
 import { handleClientMessage, type ConnectionState } from "./dispatch.js";
 import type { WsHost } from "./host.js";
@@ -36,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
@@ -88,6 +134,7 @@ export function createWsHandlers(host: WsHost) {
               turn
             )
           );
+          resendPendingInteractive(host, ws);
         }
         return;
       }
@@ -98,6 +145,7 @@ export function createWsHandlers(host: WsHost) {
         status: "idle",
         detail: `Connected to ${host.appName}`,
       });
+      resendPendingInteractive(host, ws);
     },
 
     onMessage(evt: MessageEvent, ws: WSContext) {
@@ -173,12 +221,16 @@ export function createWsHandlers(host: WsHost) {
         host.reportAbnormalClose(code);
       }
       host.clients.remove(ws);
-      // Turns keep running in the background. Only reject pending interactive
-      // requests once the LAST client leaves — while another client remains it
-      // can still answer them.
+      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
+      // re-delivered on reconnect — a phone drops its socket at every screen
+      // lock, and denying pending approvals on that signal killed real work.
+      // The turn timeout remains their upper bound.
       if (host.clients.hasClients()) return;
       for (const turn of host.coordinator.running) {
-        host.coordinator.drainPendingForTurn(turn, "Client disconnected");
+        host.coordinator.drainClientBoundForTurn(turn, "Client disconnected");
       }
     },
   };