@schlessera/brain-ui-server 0.34.0 → 0.35.0

package/src/activity/store.ts

@@ -38,6 +38,8 @@ import {
   resolveStandalonePricingConfig,
 } from "../config/env.js";
 import { createModelPricing, type PricingRates } from "../pricing/model-pricing.js";
+import type { PrincipalKind } from "../db/principals.js";
+import { ACTIVITY_SQL } from "./sql.js";
 
 export const SPAN_OUTCOMES = [
   "success",
@@ -52,6 +54,12 @@ export type SpanOutcome = (typeof SPAN_OUTCOMES)[number];
 export type SpanKind = "turn" | "tool" | "subagent" | "cron";
 export type SpanOrigin = "session" | "cron";
 
+function isPrincipalKind(value: unknown): value is PrincipalKind {
+  return (
+    value === "owner" || value === "agent" || value === "ambient" || value === "system"
+  );
+}
+
 /** Token usage as spans carry it — OTel GenAI attribute semantics. */
 export interface SpanUsage {
   inputTokens?: number;
@@ -71,6 +79,7 @@ export interface SpanRow {
   origin: SpanOrigin;
   sessionId: string | null;
   jobName: string | null;
+  principalId: string | null;
   attrs: Record<string, unknown>;
   startedAt: number;
   waitUntil: number | null;
@@ -98,6 +107,9 @@ export interface RunRollupRow {
   name: string;
   sessionId: string | null;
   jobName: string | null;
+  principalId: string | null;
+  principalLabel: string | null;
+  principalKind: PrincipalKind | null;
   startedAt: number;
   endedAt: number | null;
   outcome: SpanOutcome | null;
@@ -130,6 +142,9 @@ export function rowToRunRollup(r: any): RunRollupRow {
     name: r.name,
     sessionId: r.session_id,
     jobName: r.job_name,
+    principalId: r.principal_id ?? null,
+    principalLabel: r.principal_label ?? null,
+    principalKind: isPrincipalKind(r.principal_kind) ? r.principal_kind : null,
     startedAt: r.started_at,
     endedAt: r.ended_at,
     outcome: r.outcome,
@@ -182,6 +197,7 @@ export interface StartSpanInput {
   origin: SpanOrigin;
   sessionId?: string;
   jobName?: string;
+  principalId?: string;
   attrs?: Record<string, unknown>;
   startedAt?: number;
 }
@@ -236,7 +252,12 @@ export interface ActivityStore {
   /** Non-terminal field updates (usage enrichment, wait boundary, attrs). */
   patchSpan(
     spanId: string,
-    patch: { attrs?: Record<string, unknown>; usage?: SpanUsage; waitUntil?: number }
+    patch: {
+      principalId?: string;
+      attrs?: Record<string, unknown>;
+      usage?: SpanUsage;
+      waitUntil?: number;
+    }
   ): boolean;
   /**
    * Append one event; null (nothing written) for an unknown span. `cap`
@@ -327,15 +348,13 @@ export function createActivityStore(
 
   function nextSeq(runId: string): number {
     const row = db
-      .query("SELECT COALESCE(MAX(seq), 0) AS hi FROM activity_changes WHERE run_id = ?")
+      .query(ACTIVITY_SQL.nextSeq)
       .get(runId) as { hi: number };
     return row.hi + 1;
   }
 
   function logChange(runId: string, seq: number, spanId: string, eventIndex?: number) {
-    db.query(
-      "INSERT INTO activity_changes (run_id, seq, span_id, event_index) VALUES (?, ?, ?, ?)"
-    ).run(runId, seq, spanId, eventIndex ?? null);
+    db.query(ACTIVITY_SQL.insertChange).run(runId, seq, spanId, eventIndex ?? null);
   }
 
   function rowToSpan(r: any): SpanRow {
@@ -348,6 +367,7 @@ export function createActivityStore(
       origin: r.origin,
       sessionId: r.session_id,
       jobName: r.job_name,
+      principalId: r.principal_id ?? null,
       attrs: safeParse(r.attrs) ?? {},
       startedAt: r.started_at,
       waitUntil: r.wait_until,
@@ -380,20 +400,20 @@ export function createActivityStore(
   }
 
   function getSpanRaw(spanId: string): SpanRow | null {
-    const r = db.query("SELECT * FROM activity_spans WHERE span_id = ?").get(spanId);
+    const r = db.query(ACTIVITY_SQL.spanById).get(spanId);
     return r ? rowToSpan(r) : null;
   }
 
   function runHighWaterSeqRaw(runId: string): number {
     const row = db
-      .query("SELECT COALESCE(MAX(seq), 0) AS hi FROM activity_changes WHERE run_id = ?")
+      .query(ACTIVITY_SQL.nextSeq)
       .get(runId) as { hi: number };
     return row.hi;
   }
 
   function endSpanInTx(spanId: string, input: EndSpanInput): boolean {
     const existing = db
-      .query("SELECT run_id, outcome, attrs FROM activity_spans WHERE span_id = ?")
+      .query(ACTIVITY_SQL.spanStateById)
       .get(spanId) as { run_id: string; outcome: string | null; attrs: string | null } | null;
     if (!existing || existing.outcome !== null) return false;
 
@@ -402,16 +422,7 @@ export function createActivityStore(
       ? JSON.stringify({ ...(safeParse(existing.attrs) ?? {}), ...input.attrs })
       : existing.attrs;
     const u = input.usage ?? {};
-    db.query(
-      `UPDATE activity_spans SET outcome = ?, outcome_reason = ?, ended_at = ?, attrs = ?,
-         input_tokens = COALESCE(?, input_tokens),
-         output_tokens = COALESCE(?, output_tokens),
-         cache_read_tokens = COALESCE(?, cache_read_tokens),
-         cache_creation_tokens = COALESCE(?, cache_creation_tokens),
-         cost_usd = COALESCE(?, cost_usd),
-         model = COALESCE(?, model)
-       WHERE span_id = ?`
-    ).run(
+    db.query(ACTIVITY_SQL.endSpan).run(
       input.outcome,
       input.reason ?? null,
       endedAt,
@@ -431,9 +442,7 @@ export function createActivityStore(
   /** Close every open span of the run (children first) and roll it up. */
   function closeRunInTx(runId: string, outcome: SpanOutcome, reason: string): number {
     const open = db
-      .query(
-        "SELECT span_id FROM activity_spans WHERE run_id = ? AND outcome IS NULL ORDER BY started_at DESC"
-      )
+      .query(ACTIVITY_SQL.openSpansByRun)
       .all(runId) as Array<{ span_id: string }>;
     let closed = 0;
     for (const { span_id } of open) {
@@ -445,7 +454,7 @@ export function createActivityStore(
 
   function rollupRunInTx(runId: string) {
     const spans = db
-      .query("SELECT * FROM activity_spans WHERE run_id = ? ORDER BY started_at")
+      .query(ACTIVITY_SQL.spansByRun)
       .all(runId)
       .map(rowToSpan);
     if (spans.length === 0) return;
@@ -504,39 +513,14 @@ export function createActivityStore(
             ? (priced.estimate ? 1 : 0)
             : null;
     const costUsd = root.usage.costUsd ?? priced?.costUsd ?? null;
+    const principal = root.principalId
+      ? (db
+          .query("SELECT label, kind FROM principals WHERE id = ?")
+          .get(root.principalId) as { label: string; kind: PrincipalKind } | null)
+      : null;
 
     db.query(
-      `INSERT INTO activity_run_rollups
-         (run_id, origin, name, session_id, job_name, started_at, ended_at, outcome,
-          duration_ms, span_count, input_tokens, output_tokens, cache_read_tokens,
-          cache_creation_tokens, cost_usd, effective_cost_usd, billing_mode,
-          pricing_estimate, failure_reason, detail_pruned)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
-       ON CONFLICT(run_id) DO UPDATE SET
-         ended_at = excluded.ended_at, outcome = excluded.outcome,
-         duration_ms = excluded.duration_ms, span_count = excluded.span_count,
-         input_tokens = excluded.input_tokens, output_tokens = excluded.output_tokens,
-         cache_read_tokens = excluded.cache_read_tokens,
-         cache_creation_tokens = excluded.cache_creation_tokens,
-         cost_usd = COALESCE(activity_run_rollups.cost_usd, excluded.cost_usd),
-         effective_cost_usd = CASE
-           WHEN activity_run_rollups.effective_cost_usd IS NOT NULL
-             THEN activity_run_rollups.effective_cost_usd
-           WHEN activity_run_rollups.billing_mode IS NULL
-             OR activity_run_rollups.billing_mode = excluded.billing_mode
-             THEN excluded.effective_cost_usd
-           ELSE NULL
-         END,
-         billing_mode = COALESCE(activity_run_rollups.billing_mode, excluded.billing_mode),
-         pricing_estimate = CASE
-           WHEN activity_run_rollups.pricing_estimate IS NOT NULL
-             THEN activity_run_rollups.pricing_estimate
-           WHEN activity_run_rollups.billing_mode IS NULL
-             OR activity_run_rollups.billing_mode = excluded.billing_mode
-             THEN excluded.pricing_estimate
-           ELSE NULL
-         END,
-         failure_reason = excluded.failure_reason`
+      ACTIVITY_SQL.upsertRollup
       // Every cost column is FROZEN at first non-NULL write (AE5): a re-rollup
       // after a pricing refresh must not silently reprice history — only a
       // still-NULL slot may be filled by a later computation. cost_usd gets
@@ -553,6 +537,9 @@ export function createActivityStore(
       root.name,
       root.sessionId,
       root.jobName,
+      root.principalId,
+      principal?.label ?? null,
+      principal?.kind ?? null,
       root.startedAt,
       root.endedAt,
       root.outcome,
@@ -576,12 +563,7 @@ export function createActivityStore(
     startSpan(input) {
       return inWrite(() => {
         const startedAt = input.startedAt ?? Date.now();
-        db.query(
-          `INSERT INTO activity_spans
-             (span_id, run_id, parent_span_id, name, kind, origin, session_id, job_name,
-              attrs, started_at, writer, last_heartbeat_at)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
-        ).run(
+        db.query(ACTIVITY_SQL.insertSpan).run(
           input.spanId,
           input.runId,
           input.parentSpanId ?? null,
@@ -590,6 +572,7 @@ export function createActivityStore(
           input.origin,
           input.sessionId ?? null,
           input.jobName ?? null,
+          input.principalId ?? null,
           input.attrs ? JSON.stringify(input.attrs) : null,
           startedAt,
           writer,
@@ -607,23 +590,15 @@ export function createActivityStore(
     patchSpan(spanId, patch) {
       return inWrite(() => {
         const existing = db
-          .query("SELECT run_id, outcome, attrs FROM activity_spans WHERE span_id = ?")
+          .query(ACTIVITY_SQL.spanStateById)
           .get(spanId) as { run_id: string; outcome: string | null; attrs: string | null } | null;
         if (!existing || existing.outcome !== null) return false;
         const attrs = patch.attrs
           ? JSON.stringify({ ...(safeParse(existing.attrs) ?? {}), ...patch.attrs })
           : existing.attrs;
         const u = patch.usage ?? {};
-        db.query(
-          `UPDATE activity_spans SET attrs = ?, wait_until = COALESCE(?, wait_until),
-             input_tokens = COALESCE(?, input_tokens),
-             output_tokens = COALESCE(?, output_tokens),
-             cache_read_tokens = COALESCE(?, cache_read_tokens),
-             cache_creation_tokens = COALESCE(?, cache_creation_tokens),
-             cost_usd = COALESCE(?, cost_usd),
-             model = COALESCE(?, model)
-           WHERE span_id = ?`
-        ).run(
+        db.query(ACTIVITY_SQL.patchSpan).run(
+          patch.principalId ?? null,
           attrs,
           patch.waitUntil ?? null,
           u.inputTokens ?? null,
@@ -642,19 +617,21 @@ export function createActivityStore(
     appendEvent(spanId, eventType, payload, ts, cap) {
       return inWrite(() => {
         const span = db
-          .query("SELECT run_id FROM activity_spans WHERE span_id = ?")
+          .query(ACTIVITY_SQL.spanRunById)
           .get(spanId) as { run_id: string } | null;
         if (!span) return null;
         const next = db
-          .query(
-            "SELECT COALESCE(MAX(event_index), -1) + 1 AS idx FROM activity_events WHERE span_id = ?"
-          )
+          .query(ACTIVITY_SQL.nextEventIndex)
           .get(spanId) as { idx: number };
         const stored = capPayload(payload, cap);
         const at = ts ?? Date.now();
-        db.query(
-          "INSERT INTO activity_events (span_id, event_index, ts, event_type, payload) VALUES (?, ?, ?, ?, ?)"
-        ).run(spanId, next.idx, at, eventType, JSON.stringify(stored));
+        db.query(ACTIVITY_SQL.insertEvent).run(
+          spanId,
+          next.idx,
+          at,
+          eventType,
+          JSON.stringify(stored)
+        );
         logChange(span.run_id, nextSeq(span.run_id), spanId, next.idx);
         // Built from the values just written — no read-back needed.
         return {
@@ -672,9 +649,7 @@ export function createActivityStore(
       inWrite(() => {
         // Deliberately NOT change-logged: a heartbeat is liveness metadata,
         // not activity the client needs a delta for.
-        db.query(
-          "UPDATE activity_spans SET last_heartbeat_at = ? WHERE span_id = ? AND outcome IS NULL"
-        ).run(at ?? Date.now(), spanId);
+        db.query(ACTIVITY_SQL.heartbeat).run(at ?? Date.now(), spanId);
       });
     },
 
@@ -697,9 +672,7 @@ export function createActivityStore(
       // loop re-checks open-ness inside the transaction (endSpanInTx is
       // write-once), so a race just skips.
       const open = db
-        .query(
-          "SELECT DISTINCT run_id FROM activity_spans WHERE outcome IS NULL AND origin = 'session'"
-        )
+        .query(ACTIVITY_SQL.openSessionRuns)
         .all() as Array<{ run_id: string }>;
       if (open.length === 0) return 0;
       getPricing(); // construct outside the write lock; rollup reuses it
@@ -718,11 +691,7 @@ export function createActivityStore(
       // legitimately long, quiet run with a live writer is never killed.
       // Candidate read outside the write transaction, same as sweepOwnOrphans.
       const staleRoots = db
-        .query(
-          `SELECT span_id, run_id FROM activity_spans
-           WHERE outcome IS NULL AND parent_span_id IS NULL
-             AND writer != ? AND COALESCE(last_heartbeat_at, started_at) < ?`
-        )
+        .query(ACTIVITY_SQL.staleRoots)
         .all(writer, cutoff) as Array<{ span_id: string; run_id: string }>;
       if (staleRoots.length === 0) return 0;
       getPricing(); // construct outside the write lock; rollup reuses it
@@ -739,9 +708,7 @@ export function createActivityStore(
       const cutoff = (now ?? Date.now()) - thresholdMs;
       return (
         db
-          .query(
-            "SELECT * FROM activity_spans WHERE outcome IS NULL AND parent_span_id IS NULL AND started_at < ?"
-          )
+          .query(ACTIVITY_SQL.stuckRoots)
           .all(cutoff) as any[]
       ).map(rowToSpan);
     },
@@ -751,23 +718,10 @@ export function createActivityStore(
       // change whose span/event row was pruned drops out via the join, same
       // as the old per-row miss.
       const spanRows = db
-        .query(
-          `SELECT c.change_id, c.run_id, c.seq, s.*
-           FROM activity_changes c
-           JOIN activity_spans s ON s.span_id = c.span_id
-           WHERE c.change_id > ? AND c.event_index IS NULL
-           ORDER BY c.change_id LIMIT ?`
-        )
+        .query(ACTIVITY_SQL.spanChanges)
         .all(changeCursor, limit) as any[];
       const eventRows = db
-        .query(
-          `SELECT c.change_id, c.run_id, c.seq, e.*
-           FROM activity_changes c
-           JOIN activity_events e
-             ON e.span_id = c.span_id AND e.event_index = c.event_index
-           WHERE c.change_id > ? AND c.event_index IS NOT NULL
-           ORDER BY c.change_id LIMIT ?`
-        )
+        .query(ACTIVITY_SQL.eventChanges)
         .all(changeCursor, limit) as any[];
       const changes: ActivityChange[] = [
         ...spanRows.map(
@@ -795,22 +749,14 @@ export function createActivityStore(
 
     terminalRootChangesSince(changeCursor, limit = 500) {
       const rows = db
-        .query(
-          `SELECT MAX(c.change_id) AS change_id, s.*
-           FROM activity_changes c
-           JOIN activity_spans s ON s.span_id = c.span_id
-           WHERE c.change_id > ? AND c.event_index IS NULL
-             AND s.parent_span_id IS NULL AND s.outcome IS NOT NULL
-           GROUP BY s.span_id
-           ORDER BY change_id LIMIT ?`
-        )
+        .query(ACTIVITY_SQL.terminalRootChanges)
         .all(changeCursor, limit) as any[];
       return rows.map((r) => ({ changeId: r.change_id, span: rowToSpan(r) }));
     },
 
     latestChangeCursor() {
       const row = db
-        .query("SELECT COALESCE(MAX(change_id), 0) AS hi FROM activity_changes")
+        .query(ACTIVITY_SQL.latestChangeCursor)
         .get() as { hi: number };
       return row.hi;
     },
@@ -822,21 +768,17 @@ export function createActivityStore(
       return db.transaction(() => {
         const spans = (
           db
-            .query("SELECT * FROM activity_spans WHERE run_id = ? ORDER BY started_at")
+            .query(ACTIVITY_SQL.spansByRun)
             .all(runId) as any[]
         ).map(rowToSpan);
         if (spans.length === 0) return null;
         const events = (
           db
-            .query(
-              `SELECT e.* FROM activity_events e
-               JOIN activity_spans s ON s.span_id = e.span_id
-               WHERE s.run_id = ? ORDER BY e.ts, e.event_index`
-            )
+            .query(ACTIVITY_SQL.eventsByRun)
             .all(runId) as any[]
         ).map(rowToEvent);
         const cursor = db
-          .query("SELECT COALESCE(MAX(change_id), 0) AS hi FROM activity_changes")
+          .query(ACTIVITY_SQL.latestChangeCursor)
           .get() as { hi: number };
         return {
           runId,
@@ -855,9 +797,7 @@ export function createActivityStore(
     openRootSpans() {
       return (
         db
-          .query(
-            "SELECT * FROM activity_spans WHERE outcome IS NULL AND parent_span_id IS NULL ORDER BY started_at DESC"
-          )
+          .query(ACTIVITY_SQL.openRootSpans)
           .all() as any[]
       ).map(rowToSpan);
     },
@@ -887,46 +827,24 @@ export function createActivityStore(
         // run — that terminal write is what made the run prunable), guarded
         // against any run that still has an open span.
         const candidates = db
-          .query(
-            `SELECT run_id, ended_at AS ended FROM activity_run_rollups r
-             WHERE detail_pruned = 0 AND ended_at IS NOT NULL
-               AND ((ended_at < ? AND ended_at < ?) OR ended_at < ?)
-               AND NOT EXISTS (
-                 SELECT 1 FROM activity_spans s
-                 WHERE s.run_id = r.run_id AND s.outcome IS NULL
-               )
-             LIMIT ?`
-          )
+          .query(ACTIVITY_SQL.pruneCandidates)
           .all(floor, retentionCutoff, ceiling, batch) as Array<{ run_id: string; ended: number }>;
         let spansDeleted = 0;
         for (const { run_id, ended } of candidates) {
-          db.query(
-            "UPDATE activity_run_rollups SET detail_pruned = 1 WHERE run_id = ?"
-          ).run(run_id);
+          db.query(ACTIVITY_SQL.markDetailPruned).run(run_id);
           if (ended >= floor) {
             // Pruned by the hard ceiling alone — the digest never covered
             // this run; make the coverage gap visible on the rollup.
-            db.query(
-              "UPDATE activity_run_rollups SET failure_reason = COALESCE(failure_reason, 'digest coverage gap') WHERE run_id = ?"
-            ).run(run_id);
+            db.query(ACTIVITY_SQL.markDigestCoverageGap).run(run_id);
           }
-          db.query(
-            `DELETE FROM activity_events WHERE span_id IN
-               (SELECT span_id FROM activity_spans WHERE run_id = ?)`
-          ).run(run_id);
-          const res = db.query("DELETE FROM activity_spans WHERE run_id = ?").run(run_id);
+          db.query(ACTIVITY_SQL.deleteEventsByRun).run(run_id);
+          const res = db.query(ACTIVITY_SQL.deleteSpansByRun).run(run_id);
           spansDeleted += res.changes;
-          db.query("DELETE FROM activity_changes WHERE run_id = ?").run(run_id);
+          db.query(ACTIVITY_SQL.deleteChangesByRun).run(run_id);
         }
         // The change log only serves live polling; rows this deep in the past
         // are unreachable by any live cursor. Keep runs with open spans.
-        db.query(
-          `DELETE FROM activity_changes WHERE change_id < (
-             SELECT COALESCE(MAX(change_id), 0) FROM activity_changes
-           ) - 100000 AND run_id NOT IN (
-             SELECT DISTINCT run_id FROM activity_spans WHERE outcome IS NULL
-           )`
-        ).run();
+        db.query(ACTIVITY_SQL.compactChanges).run();
         return { runsPruned: candidates.length, spansDeleted };
       });
     },

package/src/activity/stream.ts

@@ -77,6 +77,7 @@ export function toWireSpan(span: SpanRow): ActivitySpan {
     origin: span.origin,
     sessionId: span.sessionId ?? undefined,
     jobName: span.jobName ?? undefined,
+    principalId: span.principalId ?? undefined,
     startedAt: span.startedAt,
     waitUntil: span.waitUntil ?? undefined,
     endedAt: span.endedAt ?? undefined,
@@ -122,6 +123,9 @@ export function toWireRollup(r: RunRollupRow): ActivityRunRollup {
     name: r.name,
     sessionId: r.sessionId,
     jobName: r.jobName,
+    principalId: r.principalId,
+    principalLabel: r.principalLabel,
+    principalKind: r.principalKind,
     startedAt: r.startedAt,
     endedAt: r.endedAt,
     outcome: r.outcome,
@@ -136,10 +140,12 @@ export function toWireRollup(r: RunRollupRow): ActivityRunRollup {
 }
 
 export interface ActivityStream {
-  handleSubscribe(ws: WSContext, msg: ClientActivitySubscribe): void;
+  handleSubscribe(ws: WSContext, msg: ClientActivitySubscribe, principalId: string): void;
   handleUnsubscribe(ws: WSContext, msg: ClientActivityUnsubscribe): void;
   /** Forget a closed socket. */
   dropConnection(ws: WSContext): void;
+  /** Forget every subscription attached by one revoked principal. */
+  dropFor(principalId: string): void;
   /** Drain new committed changes to subscribers. Reentrancy-safe. */
   pump(): void;
   /** Whether any connection currently watches the given session's activity. */
@@ -150,7 +156,10 @@ export interface ActivityStream {
 }
 
 export function createActivityStream(store: ActivityStore, log?: Logger): ActivityStream {
-  const subscriptions = new Map<WSContext, Subscription[]>();
+  const subscriptions = new Map<
+    unknown,
+    { ws: WSContext; principalId: string; subscriptions: Subscription[] }
+  >();
   let cursor = store.latestChangeCursor();
   let pumping = false;
   let pollHandle: ReturnType<typeof setInterval> | null = null;
@@ -222,9 +231,9 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
           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);
+          for (const entry of subscriptions.values()) {
+            if (entry.subscriptions.some((s) => matches(s, change.runId, span))) {
+              sendTo(entry.ws, frame);
             }
           }
         }
@@ -310,7 +319,7 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
   }
 
   return {
-    handleSubscribe(ws, msg) {
+    handleSubscribe(ws, msg, principalId) {
       // 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)) {
@@ -321,9 +330,11 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
         ...(msg.sessionId ? { sessionId: msg.sessionId } : {}),
         ...(msg.runId ? { runId: msg.runId } : {}),
       };
-      const list = subscriptions.get(ws) ?? [];
+      const identity = ws.raw ?? ws;
+      const existing = subscriptions.get(identity);
+      const list = existing?.subscriptions ?? [];
       if (!list.some((s) => subKey(s) === subKey(sub))) list.push(sub);
-      subscriptions.set(ws, list);
+      subscriptions.set(identity, { ws, principalId, subscriptions: list });
       ensurePolling();
       try {
         sendSnapshot(ws, sub);
@@ -337,29 +348,38 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
     },
 
     handleUnsubscribe(ws, msg) {
-      const list = subscriptions.get(ws);
-      if (!list) return;
+      const identity = ws.raw ?? ws;
+      const entry = subscriptions.get(identity);
+      if (!entry) 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);
+      const remaining = entry.subscriptions.filter((s) => subKey(s) !== key);
+      if (remaining.length > 0) {
+        subscriptions.set(identity, { ...entry, ws, subscriptions: remaining });
+      } else subscriptions.delete(identity);
       stopPollingIfIdle();
     },
 
     dropConnection(ws) {
-      subscriptions.delete(ws);
+      subscriptions.delete(ws.raw ?? ws);
+      stopPollingIfIdle();
+    },
+
+    dropFor(principalId) {
+      for (const [identity, entry] of subscriptions) {
+        if (entry.principalId === principalId) subscriptions.delete(identity);
+      }
       stopPollingIfIdle();
     },
 
     pump,
 
     isWatched(scope) {
-      for (const subs of subscriptions.values()) {
-        for (const s of subs) {
+      for (const entry of subscriptions.values()) {
+        for (const s of entry.subscriptions) {
           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)
@@ -371,7 +391,7 @@ export function createActivityStream(store: ActivityStore, log?: Logger): Activi
 
     subscriptionCount() {
       let n = 0;
-      for (const subs of subscriptions.values()) n += subs.length;
+      for (const entry of subscriptions.values()) n += entry.subscriptions.length;
       return n;
     },
 

package/src/app-env.ts

@@ -0,0 +1,8 @@
+import type { Principal } from "./db/principals.js";
+
+/** Request-scoped values populated by the authentication boundary. */
+export type AppEnv = {
+  Variables: {
+    principal?: Principal;
+  };
+};