@schlessera/brain-ui-server 0.18.0 → 0.20.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,187 @@
+/**
+ * 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, sumEffectiveCost, 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,
+          // Explicit nulls, never omitted: the model must be able to tell
+          // "unknown" (null) from "genuinely free" ($0) — AE3.
+          effectiveCostUsd: r.effectiveCostUsd,
+          billingMode: r.billingMode,
+          pricingEstimate: r.pricingEstimate,
+          failureReason: r.failureReason,
+        })),
+      };
+    }
+
+    case "run": {
+      if (!query.runId) return { error: "scope 'run' needs runId" };
+      const snapshot = store.snapshotRun(query.runId);
+      if (snapshot) {
+        // The cost facts live on the rollup, not the spans — attach them here
+        // the same way the REST detail route does, so the agent sees the
+        // frozen triple for a finished run without waiting for detail
+        // pruning. Explicit nulls (AE3): a still-running run has no rollup
+        // yet, and unknown must never read as $0.
+        const rollupRow = db
+          .query("SELECT * FROM activity_run_rollups WHERE run_id = ?")
+          .get(query.runId) as any;
+        const liveRollup = rollupRow ? rowToRunRollup(rollupRow) : null;
+        return {
+          runId: query.runId,
+          costUsd: liveRollup?.costUsd ?? null,
+          effectiveCostUsd: liveRollup?.effectiveCostUsd ?? null,
+          billingMode: liveRollup?.billingMode ?? null,
+          pricingEstimate: liveRollup?.pricingEstimate ?? null,
+          failureReason: liveRollup?.failureReason ?? null,
+          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,
+          effectiveCostUsd: rollup.effectiveCostUsd,
+          billingMode: rollup.billingMode,
+          pricingEstimate: rollup.pricingEstimate,
+          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);
+      const effective = sumEffectiveCost(rows);
+      return {
+        windowHours: hoursBack,
+        runs: rows.length,
+        failures: rows.filter((r) => isFailureOutcome(r.outcome)).length,
+        // Both sums are sum-of-KNOWNS; the runs excluded from the effective
+        // sum ride along as unpricedRuns so unknown never reads as $0 (AE3).
+        costUsd: round(rows.reduce((a, r) => a + (r.costUsd ?? 0), 0)),
+        effectiveCostUsd: round(effective.effectiveCostUsd),
+        unpricedRuns: effective.unpricedRuns,
+        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;
+}