@schlessera/brain-ui-server 0.17.0 → 0.19.0

package/src/activity/push-sender.ts

@@ -0,0 +1,215 @@
+/**
+ * The accelerator tier: web push delivery for pending notification intents.
+ *
+ * VAPID keys are generated at first boot into their own table (see migration
+ * 008 for why not the settings KV) and never leave the process. Payloads are
+ * MINIMIZED — title + outcome word + a deep link — because push renders on
+ * lock screens outside the app's auth; detail lives behind the authenticated
+ * tap-through.
+ *
+ * Delivery marks the intent sent/send_failed; the inbox (guaranteed tier)
+ * is untouched by any of it. A 404/410 response prunes the subscription —
+ * the push service says that device is gone. When every send in a pass
+ * fails, that is the all-devices signal (VAPID invalidated by a KV
+ * wipe/restore, typically) and it is logged loudly; the client surfaces a
+ * re-enable prompt when its subscription check disagrees with the server.
+ */
+import type { Database } from "bun:sqlite";
+import type { Logger } from "@opentelemetry/api-logs";
+import webpush from "web-push";
+
+import type { ActivityNotifier } from "./notify.js";
+
+export interface PushSubscriptionRow {
+  endpoint: string;
+  p256dh: string;
+  auth: string;
+  label: string | null;
+  createdAt: number;
+  lastUsedAt: number | null;
+}
+
+export interface PushSender {
+  publicKey(): string;
+  subscribe(sub: { endpoint: string; keys: { p256dh: string; auth: string } }, label?: string): void;
+  unsubscribe(endpoint: string): boolean;
+  subscriptions(): PushSubscriptionRow[];
+  /** Deliver pending intents to every subscription. Returns sends attempted. */
+  deliverPending(notifier: ActivityNotifier): Promise<number>;
+}
+
+export interface CreatePushSenderOptions {
+  /** Injection seam for tests — the real webpush.sendNotification otherwise. */
+  send?: (
+    subscription: { endpoint: string; keys: { p256dh: string; auth: string } },
+    payload: string,
+    options: {
+      vapidDetails: { subject: string; publicKey: string; privateKey: string };
+      timeout?: number;
+    }
+  ) => Promise<unknown>;
+  /** `mailto:` or https contact required by the VAPID spec. */
+  subject?: string;
+  log?: Logger;
+}
+
+/** Per-send cap: a hung push service rejects instead of wedging the
+ *  delivering guard (the tick's reentrancy flag) forever. */
+const SEND_TIMEOUT_MS = 10_000;
+
+export function createPushSender(
+  db: Database,
+  options: CreatePushSenderOptions = {}
+): PushSender {
+  const log = options.log;
+  const subject = options.subject ?? "mailto:admin@localhost";
+  const send =
+    options.send ??
+    ((sub, payload, opts) =>
+      webpush.sendNotification(
+        { endpoint: sub.endpoint, keys: sub.keys },
+        payload,
+        { vapidDetails: opts.vapidDetails, timeout: opts.timeout }
+      ));
+
+  // Generate-once VAPID keys. Concurrent first boots are safe: the INSERT is
+  // OR IGNORE and the read-back wins.
+  function vapid(): { publicKey: string; privateKey: string } {
+    const row = db
+      .query("SELECT public_key AS publicKey, private_key AS privateKey FROM vapid_keys WHERE id = 1")
+      .get() as { publicKey: string; privateKey: string } | null;
+    if (row) return row;
+    const generated = webpush.generateVAPIDKeys();
+    db.query(
+      "INSERT OR IGNORE INTO vapid_keys (id, public_key, private_key, created_at) VALUES (1, ?, ?, ?)"
+    ).run(generated.publicKey, generated.privateKey, Date.now());
+    return vapid();
+  }
+
+  function rows(): PushSubscriptionRow[] {
+    return (
+      db.query("SELECT * FROM push_subscriptions ORDER BY created_at").all() as any[]
+    ).map((r) => ({
+      endpoint: r.endpoint,
+      p256dh: r.p256dh,
+      auth: r.auth,
+      label: r.label,
+      createdAt: r.created_at,
+      lastUsedAt: r.last_used_at,
+    }));
+  }
+
+  return {
+    publicKey() {
+      return vapid().publicKey;
+    },
+
+    subscribe(sub, label) {
+      db.query(
+        `INSERT INTO push_subscriptions (endpoint, p256dh, auth, label, created_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(endpoint) DO UPDATE SET p256dh = excluded.p256dh, auth = excluded.auth`
+      ).run(sub.endpoint, sub.keys.p256dh, sub.keys.auth, label ?? null, Date.now());
+    },
+
+    unsubscribe(endpoint) {
+      return db.query("DELETE FROM push_subscriptions WHERE endpoint = ?").run(endpoint)
+        .changes > 0;
+    },
+
+    subscriptions: rows,
+
+    async deliverPending(notifier) {
+      const pending = notifier.pending();
+      if (pending.length === 0) return 0;
+      if (rows().length === 0) {
+        // No devices: the inbox already has it; nothing to deliver. Leave
+        // the intents pending so a device subscribing later still gets them
+        // if they are fresh, and the boot sweep can retry.
+        return 0;
+      }
+      const keys = vapid();
+      let attempts = 0;
+
+      for (const intent of pending) {
+        // Re-read per intent: an endpoint pruned as dead during the previous
+        // intent's pass must not be attempted again in this one.
+        const subs = rows();
+        if (subs.length === 0) break;
+        // Minimized payload; the tag coalesces repeats per run across devices.
+        const payload = JSON.stringify({
+          title: intent.title,
+          body: intent.body,
+          tag: `brain-activity:${intent.runId}`,
+          url: `/#/activity/${encodeURIComponent(intent.runId)}`,
+        });
+        attempts += subs.length;
+        const results = await Promise.allSettled(
+          subs.map((sub) =>
+            send(
+              { endpoint: sub.endpoint, keys: { p256dh: sub.p256dh, auth: sub.auth } },
+              payload,
+              {
+                vapidDetails: { subject, publicKey: keys.publicKey, privateKey: keys.privateKey },
+                timeout: SEND_TIMEOUT_MS,
+              }
+            )
+          )
+        );
+        // DB writes only after the whole settled pass — never concurrent
+        // with in-flight sends against the same handle.
+        let delivered = 0;
+        const touched: string[] = [];
+        const dead: string[] = [];
+        results.forEach((result, i) => {
+          const sub = subs[i]!;
+          if (result.status === "fulfilled") {
+            delivered++;
+            touched.push(sub.endpoint);
+            return;
+          }
+          const err = result.reason;
+          const status = (err as { statusCode?: number }).statusCode;
+          if (status === 404 || status === 410) {
+            // The push service says this device is gone.
+            dead.push(sub.endpoint);
+            log?.emit({
+              severityText: "INFO",
+              body: "pruned dead push subscription",
+              attributes: { status: status },
+            });
+          } else {
+            log?.emit({
+              severityText: "WARN",
+              body: "push send failed",
+              attributes: {
+                error: err instanceof Error ? err.message : String(err),
+                ...(status ? { status } : {}),
+              },
+            });
+          }
+        });
+        for (const endpoint of touched) {
+          db.query("UPDATE push_subscriptions SET last_used_at = ? WHERE endpoint = ?").run(
+            Date.now(),
+            endpoint
+          );
+        }
+        for (const endpoint of dead) {
+          db.query("DELETE FROM push_subscriptions WHERE endpoint = ?").run(endpoint);
+        }
+        notifier.markDelivered(intent.id, delivered > 0 ? "sent" : "send_failed");
+        if (delivered === 0) {
+          // Every device failed — the all-devices signal (invalid VAPID after
+          // a restore, typically). Loud, because it is silent on every phone.
+          log?.emit({
+            severityText: "ERROR",
+            body: "push delivery failed on every subscription",
+            attributes: { subscriptions: subs.length },
+          });
+        }
+      }
+      return attempts;
+    },
+  };
+}

package/src/activity/query.ts

@@ -0,0 +1,160 @@
+/**
+ * The agent-facing read over the activity record — the same data the UI
+ * reads, shaped for model consumption and served through the backend
+ * bridge's `queryActivity` seam (the MCP tool calls it).
+ *
+ * Read-only by construction: nothing here writes. Free-text fields that
+ * originated outside the primary agent's own context (failure reasons /
+ * stderr tails, subagent transcript excerpts) are DATA, not instructions —
+ * the tool layer labels them as such before they reach a model.
+ */
+import type { Database } from "bun:sqlite";
+import type { ActivityQuery, ActivityQueryResult } from "@schlessera/brain-ui-sdk/server";
+import { isFailureOutcome } from "@schlessera/brain-ui-sdk/protocol";
+
+import { latestActivityDigest } from "./digest.js";
+import type { ActivityNotifier } from "./notify.js";
+import { rowToRunRollup, type ActivityStore, type SpanRow } from "./store.js";
+
+export function runActivityQuery(
+  db: Database,
+  store: ActivityStore,
+  query: ActivityQuery,
+  notifier?: ActivityNotifier
+): ActivityQueryResult {
+  const limit = Math.min(Math.max(query.limit ?? 20, 1), 100);
+  const hoursBack = Math.min(Math.max(query.hoursBack ?? 24, 1), 24 * 90);
+  const since = Date.now() - hoursBack * 60 * 60 * 1000;
+
+  switch (query.scope) {
+    case "running": {
+      return {
+        running: store.openRootSpans().map(liveSummary),
+      };
+    }
+
+    case "recent": {
+      const rows = (
+        db
+          .query(
+            "SELECT * FROM activity_run_rollups WHERE started_at >= ? ORDER BY started_at DESC LIMIT ?"
+          )
+          .all(since, limit) as any[]
+      ).map(rowToRunRollup);
+      return {
+        windowHours: hoursBack,
+        running: store.openRootSpans().map(liveSummary),
+        finished: rows.map((r) => ({
+          runId: r.runId,
+          origin: r.origin,
+          name: r.name,
+          jobName: r.jobName,
+          sessionId: r.sessionId,
+          startedAt: iso(r.startedAt),
+          outcome: r.outcome,
+          durationMs: r.durationMs,
+          costUsd: r.costUsd,
+          failureReason: r.failureReason,
+        })),
+      };
+    }
+
+    case "run": {
+      if (!query.runId) return { error: "scope 'run' needs runId" };
+      const snapshot = store.snapshotRun(query.runId);
+      if (snapshot) {
+        return {
+          runId: query.runId,
+          spans: snapshot.spans.map((s) => ({
+            spanId: s.spanId,
+            parent: s.parentSpanId,
+            name: s.name,
+            kind: s.kind,
+            startedAt: iso(s.startedAt),
+            endedAt: s.endedAt ? iso(s.endedAt) : null,
+            outcome: s.outcome,
+            reason: s.outcomeReason,
+            costUsd: s.usage.costUsd,
+            tokens:
+              s.usage.inputTokens !== undefined || s.usage.outputTokens !== undefined
+                ? { in: s.usage.inputTokens, out: s.usage.outputTokens }
+                : undefined,
+          })),
+        };
+      }
+      const row = db
+        .query("SELECT * FROM activity_run_rollups WHERE run_id = ?")
+        .get(query.runId) as any;
+      if (!row) return { error: `unknown run ${query.runId}` };
+      const rollup = rowToRunRollup(row);
+      return {
+        runId: query.runId,
+        detailPruned: true,
+        rollup: {
+          name: rollup.name,
+          jobName: rollup.jobName,
+          outcome: rollup.outcome,
+          startedAt: iso(rollup.startedAt),
+          durationMs: rollup.durationMs,
+          costUsd: rollup.costUsd,
+          failureReason: rollup.failureReason,
+        },
+      };
+    }
+
+    case "rollups": {
+      const rows = (
+        db
+          .query("SELECT * FROM activity_run_rollups WHERE started_at >= ?")
+          .all(since) as any[]
+      ).map(rowToRunRollup);
+      const digest = latestActivityDigest(db);
+      return {
+        windowHours: hoursBack,
+        runs: rows.length,
+        failures: rows.filter((r) => isFailureOutcome(r.outcome)).length,
+        costUsd: round(rows.reduce((a, r) => a + (r.costUsd ?? 0), 0)),
+        inputTokens: rows.reduce((a, r) => a + (r.inputTokens ?? 0), 0),
+        outputTokens: rows.reduce((a, r) => a + (r.outputTokens ?? 0), 0),
+        ...(digest ? { lastDigestAt: iso(digest.generatedAt) } : {}),
+      };
+    }
+
+    case "inbox": {
+      // The unacknowledged notification inbox — the same list the UI shows.
+      if (!notifier) return { error: "inbox unavailable" };
+      return {
+        intents: notifier.inbox(limit).map((i) => ({
+          kind: i.kind,
+          title: i.title,
+          status: i.status,
+          createdAt: iso(i.createdAt),
+          runId: i.runId,
+        })),
+      };
+    }
+
+    default:
+      return { error: `unknown scope` };
+  }
+}
+
+function liveSummary(span: SpanRow) {
+  return {
+    runId: span.runId,
+    origin: span.origin,
+    name: span.name,
+    jobName: span.jobName,
+    sessionId: span.sessionId,
+    startedAt: iso(span.startedAt),
+    elapsedMs: Date.now() - span.startedAt,
+  };
+}
+
+function iso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+function round(n: number): number {
+  return Math.round(n * 10000) / 10000;
+}

package/src/activity/recorder.ts

@@ -0,0 +1,261 @@
+/**
+ * Per-turn span derivation: the host-side half of activity recording.
+ *
+ * The host already sees everything a baseline trace needs — the frames it
+ * relays (tool starts/results, the terminal result), its own approval flow
+ * (wait time, denials), and the turn lifecycle it owns (timeout, cancel).
+ * A `TurnRecorder` turns that stream into spans, so EVERY backend gets a
+ * full activity tree with zero backend work; the bridge's activity side
+ * channel enriches with what only the backend sees (subagent lifecycle,
+ * usage, transcripts).
+ *
+ * Terminal-write precedence (the write-once race): enrichment arrives on the
+ * same ordered call path as frames, and the recorder buffers the result
+ * frame's outcome/usage rather than closing the root span on sight. The ONE
+ * terminal write for the root happens in `finish()` — after the backend's
+ * startTurn resolved, when everything that could refine the outcome has
+ * drained. Frame-derived outcome is the fallback, never a competing writer.
+ *
+ * Nothing here may fail the observed turn: every public method catches and
+ * drops its own errors.
+ */
+import type {
+  BackendActivityEvent,
+  ServerMessage,
+  TurnUsage,
+} from "@schlessera/brain-ui-sdk/server";
+import type { Logger } from "@opentelemetry/api-logs";
+
+import type { ActivityStore, SpanOutcome, SpanUsage } from "./store.js";
+
+export interface TurnRecorderDeps {
+  store: ActivityStore;
+  /** Called after any committed write so the live stream can pump. */
+  onWrite?: () => void;
+  log?: Logger;
+}
+
+export interface TurnRecorder {
+  /** The run id (one run per turn). */
+  readonly runId: string;
+  observeFrame(msg: ServerMessage): void;
+  observeActivity(event: BackendActivityEvent): void;
+  /** The user's approval decision arrived for a gated tool call. */
+  onApprovalDecision(toolUseId: string, allowed: boolean): void;
+  /**
+   * Close the turn: merge the buffered result enrichment into the root's
+   * single terminal write, cascade-cancel anything left open, roll up.
+   */
+  finish(disposition: "success" | "error" | "cancelled" | "timeout"): void;
+}
+
+export function createTurnRecorder(
+  deps: TurnRecorderDeps,
+  turn: { turnId: string; sessionId: string | null }
+): TurnRecorder {
+  const { store, onWrite, log } = deps;
+  const runId = turn.turnId;
+  const rootSpanId = `${runId}:turn`;
+  let sessionId = turn.sessionId ?? undefined;
+  let rootStarted = false;
+  let finished = false;
+  /** Buffered terminal enrichment from the result frame. */
+  let resultOutcome: SpanOutcome | null = null;
+  let resultUsage: SpanUsage | undefined;
+  let resultAttrs: Record<string, unknown> | undefined;
+
+  const guard = (fn: () => void) => {
+    try {
+      fn();
+    } catch (err) {
+      log?.emit({
+        severityText: "WARN",
+        body: "activity recording failed; dropping",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
+    }
+  };
+
+  function ensureRoot() {
+    if (rootStarted) return;
+    rootStarted = true;
+    store.startSpan({
+      spanId: rootSpanId,
+      runId,
+      name: "invoke_agent",
+      kind: "turn",
+      origin: "session",
+      sessionId,
+      attrs: { "gen_ai.operation.name": "invoke_agent" },
+    });
+    onWrite?.();
+  }
+
+  function usageFromTurnUsage(usage: TurnUsage): SpanUsage {
+    const models = usage.perModel ? Object.keys(usage.perModel) : [];
+    return {
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheCreationTokens: usage.cacheCreationTokens,
+      model: models.length === 1 ? models[0] : undefined,
+    };
+  }
+
+  return {
+    runId,
+
+    observeFrame(msg) {
+      guard(() => {
+        if (finished) return;
+        switch (msg.type) {
+          case "session_info": {
+            sessionId = msg.sessionId;
+            ensureRoot();
+            // The root may have been opened before the session had a name.
+            store.patchSpan(rootSpanId, { attrs: { "session.id": msg.sessionId } });
+            onWrite?.();
+            break;
+          }
+          case "tool_use_start": {
+            ensureRoot();
+            const isSubagent = msg.toolName === "Agent";
+            store.startSpan({
+              spanId: msg.toolUseId,
+              runId,
+              parentSpanId: msg.parentToolUseId ?? rootSpanId,
+              name: `execute_tool ${msg.toolName}`,
+              kind: isSubagent ? "subagent" : "tool",
+              origin: "session",
+              sessionId,
+              attrs: {
+                "gen_ai.operation.name": isSubagent ? "invoke_agent" : "execute_tool",
+                "gen_ai.tool.name": msg.toolName,
+              },
+            });
+            onWrite?.();
+            break;
+          }
+          case "tool_approval_request": {
+            // The span exists (tool_use_start preceded it). Nothing to write:
+            // startedAt already marks the wait's beginning; the grant stamps
+            // the wait/execution boundary.
+            break;
+          }
+          case "tool_result": {
+            // endSpan is write-once: a span already closed (a denial landed
+            // the outcome first) rejects this as a no-op, and an unknown
+            // span id is equally a no-op — no bookkeeping set needed.
+            const outcome: SpanOutcome = msg.isError ? "error" : "success";
+            store.endSpan(msg.toolUseId, {
+              outcome,
+              reason: outcome === "error" ? clip(msg.output, 500) : undefined,
+            });
+            onWrite?.();
+            break;
+          }
+          case "result": {
+            // Buffered — the single terminal write happens in finish().
+            resultOutcome =
+              msg.outcome === "success"
+                ? "success"
+                : msg.outcome === "cancelled"
+                  ? "cancelled"
+                  : msg.outcomeDetail === "max_turns" || msg.outcomeDetail === "max_budget"
+                    ? "timeout"
+                    : "error";
+            if (msg.usage) resultUsage = usageFromTurnUsage(msg.usage);
+            if (typeof msg.costUsd === "number") {
+              resultUsage = { ...(resultUsage ?? {}), costUsd: msg.costUsd };
+            }
+            resultAttrs = {
+              ...(msg.outcomeDetail ? { "outcome.detail": msg.outcomeDetail } : {}),
+              ...(msg.usage?.perModel
+                ? { "gen_ai.usage.per_model": msg.usage.perModel }
+                : {}),
+            };
+            break;
+          }
+          default:
+            break;
+        }
+      });
+    },
+
+    observeActivity(event) {
+      guard(() => {
+        if (finished) return;
+        switch (event.kind) {
+          case "subagent_started": {
+            store.patchSpan(event.toolUseId, {
+              attrs: {
+                "subagent.type": event.subagentType,
+                "subagent.description": event.description,
+              },
+            });
+            onWrite?.();
+            break;
+          }
+          case "subagent_status": {
+            const attrs = {
+              ...(event.usage ? { "subagent.total_tokens": event.usage.totalTokens } : {}),
+              ...(event.summary ? { "subagent.summary": event.summary } : {}),
+            };
+            if (Object.keys(attrs).length > 0) {
+              store.patchSpan(event.toolUseId, { attrs });
+              onWrite?.();
+            }
+            break;
+          }
+          case "subagent_transcript": {
+            store.appendEvent(event.toolUseId, `transcript_${event.role}`, event.text);
+            onWrite?.();
+            break;
+          }
+        }
+      });
+    },
+
+    onApprovalDecision(toolUseId, allowed) {
+      guard(() => {
+        if (allowed) {
+          // Everything before this moment was approval wait, not execution.
+          store.patchSpan(toolUseId, { waitUntil: Date.now() });
+        } else {
+          // The denied outcome lands now — write-once makes the backend's
+          // later error tool_result a no-op on this span.
+          store.endSpan(toolUseId, { outcome: "denied", reason: "user declined" });
+        }
+        onWrite?.();
+      });
+    },
+
+    finish(disposition) {
+      guard(() => {
+        if (finished) return;
+        finished = true;
+        ensureRoot();
+        // Merged precedence: the buffered result enrichment refines the
+        // host's own disposition; the host wins only where the backend said
+        // nothing. Cancellation/timeout are host-owned facts and always win.
+        const outcome: SpanOutcome =
+          disposition === "cancelled" || disposition === "timeout"
+            ? disposition
+            : (resultOutcome ?? disposition);
+        store.endSpan(rootSpanId, {
+          outcome,
+          usage: resultUsage,
+          attrs: resultAttrs,
+        });
+        // Anything still open died with the turn.
+        store.cascadeClose(runId, "cancelled", `turn ${outcome}`);
+        store.rollupRun(runId);
+        onWrite?.();
+      });
+    },
+  };
+}
+
+function clip(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max) : text;
+}