@schlessera/brain-ui-server 0.17.0 → 0.19.0

package/migrations/007_activity.sql

@@ -0,0 +1,114 @@
+-- Agent activity record: one span per unit of agent activity (turn, tool
+-- call, subagent run, cron run), forming a tree per run. Current state lives
+-- in activity_spans; append-only transcript/progress increments live in
+-- activity_events; every committed write also lands one row in
+-- activity_changes, which is BOTH the global change cursor (change_id, for
+-- the server's foreign-write poller) and the per-run sequence authority
+-- (seq, for the client's snapshot-then-delta discard rule).
+--
+-- Outcome is write-once: 'interrupted' is assigned only by a sweeper, never
+-- by a live writer. last_heartbeat_at is touched by external writers (the
+-- cron wrapper) so staleness is judged on heartbeat age, not span age.
+CREATE TABLE IF NOT EXISTS activity_spans (
+  span_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  parent_span_id TEXT,
+  name TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('turn', 'tool', 'subagent', 'cron')),
+  origin TEXT NOT NULL CHECK (origin IN ('session', 'cron')),
+  session_id TEXT,
+  job_name TEXT,
+  attrs TEXT,
+  started_at INTEGER NOT NULL,
+  wait_until INTEGER,
+  ended_at INTEGER,
+  outcome TEXT CHECK (outcome IN ('success', 'error', 'timeout', 'cancelled', 'denied', 'interrupted')),
+  outcome_reason TEXT,
+  input_tokens INTEGER,
+  output_tokens INTEGER,
+  cache_read_tokens INTEGER,
+  cache_creation_tokens INTEGER,
+  cost_usd REAL,
+  model TEXT,
+  writer TEXT NOT NULL,
+  last_heartbeat_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_activity_spans_run ON activity_spans(run_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_activity_spans_open ON activity_spans(started_at DESC) WHERE outcome IS NULL AND parent_span_id IS NULL;
+CREATE INDEX IF NOT EXISTS idx_activity_spans_session ON activity_spans(session_id, started_at DESC) WHERE session_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_activity_spans_job ON activity_spans(job_name, started_at DESC) WHERE job_name IS NOT NULL;
+
+-- Append-only span events (subagent transcript excerpts, progress notes).
+-- Payloads are capped at persist time (stored truncation marker) so a single
+-- WS delta can never approach the frame size cap.
+CREATE TABLE IF NOT EXISTS activity_events (
+  span_id TEXT NOT NULL,
+  event_index INTEGER NOT NULL,
+  ts INTEGER NOT NULL,
+  event_type TEXT NOT NULL,
+  payload TEXT,
+  PRIMARY KEY (span_id, event_index)
+);
+
+-- Change log: one row per committed write. change_id is the global monotonic
+-- cursor (a brand-new foreign run is discoverable only through this); seq is
+-- per-run monotonic and totally orders every delta-visible write within a
+-- run. event_index is NULL for span-state changes.
+CREATE TABLE IF NOT EXISTS activity_changes (
+  change_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  span_id TEXT NOT NULL,
+  event_index INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_activity_changes_run ON activity_changes(run_id, seq);
+
+-- Per-run rollups survive span pruning forever: any run id that ever existed
+-- resolves to at least this row ("detail pruned"), and cost/token aggregation
+-- reads ROOT rollups only (subagent usage is display-only enrichment —
+-- result-level accounting already includes subagent consumption).
+CREATE TABLE IF NOT EXISTS activity_run_rollups (
+  run_id TEXT PRIMARY KEY,
+  origin TEXT NOT NULL,
+  name TEXT NOT NULL,
+  session_id TEXT,
+  job_name TEXT,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  outcome TEXT,
+  duration_ms INTEGER,
+  span_count INTEGER NOT NULL DEFAULT 0,
+  input_tokens INTEGER,
+  output_tokens INTEGER,
+  cache_read_tokens INTEGER,
+  cache_creation_tokens INTEGER,
+  cost_usd REAL,
+  failure_reason TEXT,
+  detail_pruned INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_activity_rollups_started ON activity_run_rollups(started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_activity_rollups_job ON activity_run_rollups(job_name, started_at DESC) WHERE job_name IS NOT NULL;
+
+-- Notification intents: persisted with the triggering event so delivery is
+-- at-least-once (pending rows are swept on boot). status transitions:
+-- pending -> sent | send_failed | suppressed. tag deduplicates per run so
+-- repeats coalesce instead of stacking.
+CREATE TABLE IF NOT EXISTS notification_intents (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  span_id TEXT,
+  kind TEXT NOT NULL CHECK (kind IN ('failure', 'completion', 'stuck')),
+  tag TEXT NOT NULL,
+  title TEXT NOT NULL,
+  body TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'sent', 'send_failed', 'suppressed')),
+  acknowledged INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_notification_intents_status ON notification_intents(status, created_at);
+CREATE INDEX IF NOT EXISTS idx_notification_intents_tag ON notification_intents(tag, created_at DESC);

package/migrations/008_push_subscriptions.sql

@@ -0,0 +1,24 @@
+-- Web push: per-device subscriptions, modeled on passkey_credentials (the
+-- app is single-user — no user_id column; a row IS a device+browser).
+-- Endpoints are unique; a 404/410 on send prunes the row.
+CREATE TABLE IF NOT EXISTS push_subscriptions (
+  endpoint TEXT PRIMARY KEY,
+  p256dh TEXT NOT NULL,
+  auth TEXT NOT NULL,
+  label TEXT,
+  created_at INTEGER NOT NULL,
+  last_used_at INTEGER
+);
+
+-- The VAPID keypair, generated at first boot. DELIBERATELY its own table,
+-- not a settings-KV row: settings are non-secret preferences that a future
+-- list/export route may expose wholesale, while this private key must never
+-- ride along (a leak lets an attacker send authentic push to the user's
+-- device). Nothing may ever add a route that reads this table's private_key
+-- out of the process.
+CREATE TABLE IF NOT EXISTS vapid_keys (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  public_key TEXT NOT NULL,
+  private_key TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlessera/brain-ui-server",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "brain-kit chat-UI server: Hono app factory, WebSocket turn coordinator, auth (password/passkeys/tailscale/proxy), session catalog, and brain/files/voice routes",
   "license": "MIT",
   "keywords": [
@@ -48,11 +48,12 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "0.221.0",
-    "@schlessera/brain-render-template": "0.17.0",
-    "@schlessera/brain-ui-sdk": "0.17.0",
+    "@schlessera/brain-render-template": "0.19.0",
+    "@schlessera/brain-ui-sdk": "0.19.0",
     "@simplewebauthn/server": "^13.3.2",
     "hono": "^4",
     "ignore": "^7.0.5",
+    "web-push": "^3.6.7",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -73,6 +74,7 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
+    "@types/web-push": "^3.6.4",
     "typescript": "^6.0.3"
   }
 }

package/src/activity/digest.ts

@@ -0,0 +1,92 @@
+/**
+ * The while-you-were-away digest: a deterministic summary rendered from
+ * per-run rollups, produced by its OWN scheduled job (through the standard
+ * cron wrapper, so its runs land in the record like any other) — never a
+ * side effect of instrumentation.
+ *
+ * The digest's covered-until time is the retention floor: full-detail spans
+ * older than the last covered window are prunable, newer ones are not (the
+ * hard ceiling in the store bounds a broken digest job regardless). Windows
+ * are labeled — the card says WHAT period it covers rather than implying
+ * "now". The digest job's own runs are recorded but excluded from the
+ * notable list, or every digest would feature itself.
+ */
+import type { Database } from "bun:sqlite";
+import { isFailureOutcome, type ActivityDigest } from "@schlessera/brain-ui-sdk/protocol";
+
+import { getSetting, setSetting } from "../db/settings.js";
+import { rowToRunRollup } from "./store.js";
+
+export type { ActivityDigest } from "@schlessera/brain-ui-sdk/protocol";
+
+export const DIGEST_LATEST_KEY = "activity.digest.latest";
+export const DIGEST_COVERED_KEY = "activity.digest.coveredUntil";
+export const DIGEST_DISMISSED_KEY = "activity.digest.dismissedAt";
+export const DIGEST_JOB_NAME = "digest";
+
+/** First run ever: no covered-until marker — cap the window at 24h. */
+const FIRST_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/** Generate and persist the digest for [coveredUntil, now]. */
+export function generateActivityDigest(db: Database, now = Date.now()): ActivityDigest {
+  const covered = getSetting<number | null>(db, DIGEST_COVERED_KEY, null);
+  const windowStart = covered ?? now - FIRST_WINDOW_MS;
+
+  // Windowed on ended_at, not started_at: every FINISHED run gets
+  // exactly-once coverage — a run still open at generation is picked up by
+  // the NEXT digest once it ends, instead of falling between windows.
+  const rows = (
+    db
+      .query(
+        `SELECT * FROM activity_run_rollups
+         WHERE ended_at IS NOT NULL AND ended_at >= ? AND ended_at < ?
+         ORDER BY started_at DESC`
+      )
+      .all(windowStart, now) as any[]
+  ).map(rowToRunRollup);
+
+  const relevant = rows.filter((r) => r.jobName !== DIGEST_JOB_NAME);
+  const failures = relevant.filter((r) => isFailureOutcome(r.outcome));
+
+  const digest: ActivityDigest = {
+    generatedAt: now,
+    windowStart,
+    windowEnd: now,
+    runs: relevant.length,
+    failures: failures.length,
+    costUsd: relevant.reduce((a, r) => a + (r.costUsd ?? 0), 0),
+    inputTokens: relevant.reduce((a, r) => a + (r.inputTokens ?? 0), 0),
+    outputTokens: relevant.reduce((a, r) => a + (r.outputTokens ?? 0), 0),
+    notable: failures.slice(0, 10).map((r) => ({
+      runId: r.runId,
+      name: r.name,
+      jobName: r.jobName,
+      sessionId: r.sessionId,
+      outcome: r.outcome,
+      failureReason: r.failureReason,
+      startedAt: r.startedAt,
+    })),
+  };
+
+  setSetting(db, DIGEST_LATEST_KEY, digest);
+  setSetting(db, DIGEST_COVERED_KEY, now);
+  return digest;
+}
+
+/** The latest digest, or null before the first run. */
+export function latestActivityDigest(db: Database): ActivityDigest | null {
+  return getSetting<ActivityDigest | null>(db, DIGEST_LATEST_KEY, null);
+}
+
+/** The retention floor: never prune spans the digest has not covered. */
+export function digestRetentionFloor(db: Database): number {
+  return getSetting<number>(db, DIGEST_COVERED_KEY, 0);
+}
+
+export function dismissActivityDigest(db: Database, at = Date.now()): void {
+  setSetting(db, DIGEST_DISMISSED_KEY, at);
+}
+
+export function digestDismissedAt(db: Database): number {
+  return getSetting<number>(db, DIGEST_DISMISSED_KEY, 0);
+}

package/src/activity/notify.ts

@@ -0,0 +1,285 @@
+/**
+ * Notification intents: the at-least-once layer between the activity record
+ * and every delivery channel.
+ *
+ * An intent is persisted when the triggering condition is DETECTED (a
+ * terminal failure span, a stuck run) and carries its own lifecycle:
+ * pending -> sent | send_failed | suppressed. The in-app inbox is the
+ * guaranteed tier — it lists unacknowledged intents regardless of delivery
+ * status — and web push (the accelerator) marks sent/send_failed on top.
+ * Undelivered intents survive restarts by construction; the boot/tick sweep
+ * simply finds them still pending.
+ *
+ * Detection runs on the server's always-on tick with its OWN change-log
+ * cursor (the live stream's cursor only advances for subscribers), so a
+ * foreign writer's failure — the cron wrapper recording an error while
+ * nobody watches — is noticed within one tick, not at the next app open.
+ *
+ * Storm safety: a run-scoped tag deduplicates (one active intent per tag),
+ * per-job debounce collapses repeats, and a global creation rate cap stops
+ * one bad API key from paging for every job at once.
+ */
+import type { Database } from "bun:sqlite";
+import type { Logger } from "@opentelemetry/api-logs";
+import { isFailureOutcome } from "@schlessera/brain-ui-sdk/protocol";
+
+import { getSetting } from "../db/settings.js";
+import type { ActivityStore, SpanRow } from "./store.js";
+
+export type IntentKind = "failure" | "completion" | "stuck";
+
+export interface NotificationIntent {
+  id: number;
+  runId: string;
+  spanId: string | null;
+  kind: IntentKind;
+  tag: string;
+  title: string;
+  body: string;
+  status: "pending" | "sent" | "send_failed" | "suppressed";
+  acknowledged: boolean;
+  createdAt: number;
+}
+
+export interface ActivityNotifierDeps {
+  db: Database;
+  store: ActivityStore;
+  /** Was anyone watching this run/session when the event was recorded? */
+  isWatched: (scope: { runId?: string; sessionId?: string }) => boolean;
+  log?: Logger;
+}
+
+export interface ActivityNotifier {
+  /** Detect new terminal failures + stuck runs; create intents. */
+  tick(now?: number): void;
+  /** Unacknowledged intents, newest first (the inbox). */
+  inbox(limit?: number): NotificationIntent[];
+  /** Intents awaiting delivery (the push sender's queue). */
+  pending(limit?: number): NotificationIntent[];
+  markDelivered(id: number, status: "sent" | "send_failed"): void;
+  acknowledge(id: number): boolean;
+  acknowledgeAll(): number;
+  /** Retention: delete acknowledged intents untouched for longer than this. */
+  pruneAcknowledged(olderThanMs: number): number;
+}
+
+/** Global cap on intents CREATED per hour — failure-storm circuit. */
+const MAX_INTENTS_PER_HOUR = 20;
+/** Watchdog default: a live root run older than this is flagged as stuck. */
+const DEFAULT_STUCK_THRESHOLD_MS = 45 * 60 * 1000;
+
+export function createActivityNotifier(deps: ActivityNotifierDeps): ActivityNotifier {
+  const { db, store, isWatched, log } = deps;
+  let cursor = latestCursor(db);
+  /** Runs already flagged as stuck this process lifetime (tag also guards). */
+  const stuckFlagged = new Set<string>();
+
+  function latestCursor(database: Database): number {
+    const row = database
+      .query("SELECT COALESCE(MAX(change_id), 0) AS hi FROM activity_changes")
+      .get() as { hi: number };
+    return row.hi;
+  }
+
+  function createIntent(input: {
+    runId: string;
+    spanId?: string;
+    kind: IntentKind;
+    tag: string;
+    title: string;
+    body: string;
+    suppressed?: boolean;
+  }): void {
+    const now = Date.now();
+    // Tag dedupe: one live (unacknowledged) intent per tag — repeats coalesce.
+    const existing = db
+      .query(
+        "SELECT id FROM notification_intents WHERE tag = ? AND acknowledged = 0 LIMIT 1"
+      )
+      .get(input.tag);
+    if (existing) return;
+    // Global creation rate cap.
+    const recent = db
+      .query("SELECT COUNT(*) AS n FROM notification_intents WHERE created_at > ?")
+      .get(now - 60 * 60 * 1000) as { n: number };
+    const status =
+      input.suppressed || recent.n >= MAX_INTENTS_PER_HOUR ? "suppressed" : "pending";
+    db.query(
+      `INSERT INTO notification_intents
+         (run_id, span_id, kind, tag, title, body, status, acknowledged, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?)`
+    ).run(
+      input.runId,
+      input.spanId ?? null,
+      input.kind,
+      input.tag,
+      input.title,
+      input.body,
+      status,
+      now,
+      now
+    );
+    log?.emit({
+      severityText: "INFO",
+      body: "notification intent created",
+      attributes: { kind: input.kind, tag: input.tag, status },
+    });
+  }
+
+  function intentForSpan(span: SpanRow): void {
+    if (span.parentSpanId) return;
+    if (isFailureOutcome(span.outcome)) {
+      const label = span.jobName ?? span.name;
+      // "Unwatched" is evaluated when the failure is NOTICED — a live
+      // subscription to the run or its session means the user saw it happen,
+      // so the intent lands acknowledged-free but suppressed for delivery.
+      const watched = isWatched({
+        runId: span.runId,
+        ...(span.sessionId ? { sessionId: span.sessionId } : {}),
+      });
+      // Payload minimization: name + outcome word only. Lock screens render
+      // this outside the app's auth; detail is behind the tap-through.
+      createIntent({
+        runId: span.runId,
+        spanId: span.spanId,
+        kind: "failure",
+        tag: `failure:${span.jobName ?? span.sessionId ?? span.runId}`,
+        title: `${label} ${span.outcome === "interrupted" ? "was interrupted" : "failed"}`,
+        body: "Open to see the run.",
+        suppressed: watched,
+      });
+      return;
+    }
+    if (span.outcome === "success" && span.jobName) {
+      // Completion notifications are opt-in per job.
+      const optIn = getSetting<string[]>(db, "activity.notify.completions", [], log);
+      if (optIn.includes(span.jobName)) {
+        createIntent({
+          runId: span.runId,
+          spanId: span.spanId,
+          kind: "completion",
+          tag: `completion:${span.jobName}:${span.runId}`,
+          title: `${span.jobName} completed`,
+          body: "Open to see the run.",
+        });
+      }
+    }
+  }
+
+  return {
+    tick(now) {
+      try {
+        // New committed changes since our own cursor: terminal root spans
+        // among them become intents (SQL-side filter + join in the store).
+        // The head is read BEFORE the detection query so advancing past
+        // non-terminal changes can never skip a terminal write committed
+        // in between; a change seen twice is absorbed by the tag dedupe.
+        const head = latestCursor(db);
+        const rows = store.terminalRootChangesSince(cursor, 500);
+        for (const { span } of rows) intentForSpan(span);
+        const lastSeen = rows.length > 0 ? rows[rows.length - 1]!.changeId : cursor;
+        cursor = rows.length === 500 ? lastSeen : Math.max(head, lastSeen);
+
+        // Watchdog: an over-threshold LIVE root run is stuck — a signal, not
+        // an outcome. Threshold from settings, per-job override supported.
+        const defaultThreshold = getSetting<number>(
+          db,
+          "activity.watchdog.thresholdMs",
+          DEFAULT_STUCK_THRESHOLD_MS,
+          log
+        );
+        const overrides = getSetting<Record<string, number>>(
+          db,
+          "activity.watchdog.perJobMs",
+          {},
+          log
+        );
+        for (const span of store.findStuck(defaultThreshold, now)) {
+          if (stuckFlagged.has(span.runId)) continue;
+          const threshold = span.jobName ? (overrides[span.jobName] ?? defaultThreshold) : defaultThreshold;
+          if ((now ?? Date.now()) - span.startedAt < threshold) continue;
+          stuckFlagged.add(span.runId);
+          createIntent({
+            runId: span.runId,
+            spanId: span.spanId,
+            kind: "stuck",
+            tag: `stuck:${span.runId}`,
+            title: `${span.jobName ?? span.name} is taking unusually long`,
+            body: "Still running. Open to check on it.",
+          });
+        }
+      } catch (err) {
+        log?.emit({
+          severityText: "WARN",
+          body: "notifier tick failed",
+          attributes: { error: err instanceof Error ? err.message : String(err) },
+        });
+      }
+    },
+
+    inbox(limit = 50) {
+      return (
+        db
+          .query(
+            "SELECT * FROM notification_intents WHERE acknowledged = 0 ORDER BY created_at DESC LIMIT ?"
+          )
+          .all(limit) as any[]
+      ).map(rowToIntent);
+    },
+
+    pending(limit = 20) {
+      // Acknowledged means dismissed in the inbox — never push it later.
+      return (
+        db
+          .query(
+            "SELECT * FROM notification_intents WHERE status = 'pending' AND acknowledged = 0 ORDER BY created_at LIMIT ?"
+          )
+          .all(limit) as any[]
+      ).map(rowToIntent);
+    },
+
+    markDelivered(id, status) {
+      db.query("UPDATE notification_intents SET status = ?, updated_at = ? WHERE id = ?").run(
+        status,
+        Date.now(),
+        id
+      );
+    },
+
+    acknowledge(id) {
+      const res = db
+        .query("UPDATE notification_intents SET acknowledged = 1, updated_at = ? WHERE id = ?")
+        .run(Date.now(), id);
+      return res.changes > 0;
+    },
+
+    acknowledgeAll() {
+      const res = db
+        .query("UPDATE notification_intents SET acknowledged = 1, updated_at = ? WHERE acknowledged = 0")
+        .run(Date.now());
+      return res.changes;
+    },
+
+    pruneAcknowledged(olderThanMs) {
+      const res = db
+        .query("DELETE FROM notification_intents WHERE acknowledged = 1 AND updated_at < ?")
+        .run(Date.now() - olderThanMs);
+      return res.changes;
+    },
+  };
+}
+
+function rowToIntent(r: any): NotificationIntent {
+  return {
+    id: r.id,
+    runId: r.run_id,
+    spanId: r.span_id,
+    kind: r.kind,
+    tag: r.tag,
+    title: r.title,
+    body: r.body,
+    status: r.status,
+    acknowledged: r.acknowledged === 1,
+    createdAt: r.created_at,
+  };
+}