@schlessera/brain-ui-server 0.18.0 → 0.20.0

package/src/activity/recorder.ts

@@ -0,0 +1,313 @@
+/**
+ * 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 {
+  SPAN_OP_EXECUTE_TOOL,
+  SPAN_OP_INVOKE_AGENT,
+  SPAN_TOOL_NAME_PREFIX,
+  type BillingMode,
+} from "@schlessera/brain-ui-sdk/protocol";
+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;
+    /** The RESOLVED inference profile this turn runs on (post pin-drop fallback). */
+    profileId?: string;
+    /** Billing classification of that profile, resolved at run start (U3). */
+    billingMode?: BillingMode;
+  }
+): 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: SPAN_OP_INVOKE_AGENT,
+      kind: "turn",
+      origin: "session",
+      sessionId,
+      // Profile + billing ride the ROOT span so the rollup can price the run
+      // without any registry or env lookup of its own (a root missing the
+      // billing attr falls back to env classification at rollup time).
+      attrs: {
+        "gen_ai.operation.name": SPAN_OP_INVOKE_AGENT,
+        ...(turn.profileId ? { "brain.profile_id": turn.profileId } : {}),
+        ...(turn.billingMode ? { "brain.billing_mode": turn.billingMode } : {}),
+      },
+    });
+    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: `${SPAN_TOOL_NAME_PREFIX}${msg.toolName}`,
+              kind: isSubagent ? "subagent" : "tool",
+              origin: "session",
+              sessionId,
+              attrs: {
+                "gen_ai.operation.name": isSubagent ? SPAN_OP_INVOKE_AGENT : SPAN_OP_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_use_complete": {
+            // The complete input object in one frame — tool_input_delta
+            // frames stay ignored, no accumulation needed. Recorded as a
+            // span event so the Activity drill-in can expand the call (R14).
+            store.appendEvent(
+              msg.toolUseId,
+              "tool_input",
+              safeStringify(msg.input),
+              undefined,
+              PAYLOAD_EVENT_CAP
+            );
+            onWrite?.();
+            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,
+            });
+            // Error output rides along too — a failed call's output is what
+            // the drill-in needs most. appendEvent no-ops on unknown spans.
+            store.appendEvent(msg.toolUseId, "tool_output", msg.output, undefined, PAYLOAD_EVENT_CAP);
+            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;
+}
+
+/** Cap for recorded tool input/output payload events — roomier than the
+ *  500-char outcome-reason clip, still far under the store's 16 KB event cap.
+ *  Passed to appendEvent, whose clipping sets the wire `truncated` flag. */
+const PAYLOAD_EVENT_CAP = 4096;
+
+/** Tool inputs are arbitrary values: serialization must never take the turn
+ *  down with it (BigInt members throw; a toJSON can return undefined). */
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/activity/runtime.ts

@@ -0,0 +1,169 @@
+/**
+ * The activity runtime: everything the activity record needs to live inside
+ * one app instance — store, live stream, notifier, push sender, the boot
+ * orphan sweep, and the always-on lifecycle tick (stale sweep, notification
+ * detection, push delivery, hourly prune). `createApp` constructs one and
+ * wires its pieces into the host, routes, and bridge; `close()` releases the
+ * interval and subscriptions.
+ *
+ * Nothing here may block boot or fail the observed work: the sweep and every
+ * tick pass log and continue on failure.
+ */
+import type { Database } from "bun:sqlite";
+import type { Logger } from "@opentelemetry/api-logs";
+import type { ActivityQuery, ActivityQueryResult } from "@schlessera/brain-ui-sdk/server";
+
+import { createActivityStore, type ActivityStore, type RollupPricing } from "./store.js";
+import { createActivityStream, type ActivityStream } from "./stream.js";
+import { createActivityNotifier, type ActivityNotifier } from "./notify.js";
+import { createPushSender, type PushSender } from "./push-sender.js";
+import { digestRetentionFloor } from "./digest.js";
+import { runActivityQuery } from "./query.js";
+import { getDetailRetentionDays } from "../db/settings.js";
+
+// Activity lifecycle cadence. The stale threshold must comfortably exceed
+// the cron wrapper's heartbeat interval (~30s) so a live writer is never
+// swept; the tick doubles as the always-on low-frequency sweep the
+// notification layer extends.
+const ACTIVITY_TICK_MS = 20_000;
+const ACTIVITY_STALE_AFTER_MS = 2 * 60 * 1000;
+const ACTIVITY_PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+const ACTIVITY_HARD_CEILING_MS = 90 * 24 * 60 * 60 * 1000;
+/** Acknowledged notification intents are kept this long, then deleted. */
+const INTENT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+export interface ActivityRuntime {
+  store: ActivityStore;
+  stream: ActivityStream;
+  notifier: ActivityNotifier;
+  pushSender: PushSender;
+  /** The agent-facing read seam (bridge.queryActivity). */
+  query(query: ActivityQuery): ActivityQueryResult;
+  close(): void;
+}
+
+export function createActivityRuntime(
+  db: Database,
+  deps: {
+    log: Logger;
+    /**
+     * The app's shared model-pricing instance, for rollup-time effective
+     * cost. Optional so embedders without one fall back to the store's own
+     * env-derived default (the same instance shape, just not shared).
+     */
+    pricing?: RollupPricing;
+  }
+): ActivityRuntime {
+  const { log } = deps;
+  const store = createActivityStore(db, deps.pricing ? { pricing: deps.pricing } : {});
+  const stream = createActivityStream(store, log);
+
+  // The notifier is created BEFORE the boot sweep: its change cursor starts
+  // at the current head, so the terminal changes the sweep writes are above
+  // it and the first tick turns restart-interrupted runs into failure
+  // intents. Created after, the sweep's changes would sit below the cursor
+  // and a turn killed by a restart would never be notified.
+  const notifier = createActivityNotifier({
+    db,
+    store,
+    isWatched: (scope) => stream.isWatched(scope),
+    log,
+  });
+  const pushSender = createPushSender(db, { log });
+
+  // Boot sweep: close this server's orphans from a previous life (interrupted).
+  try {
+    const orphans = store.sweepOwnOrphans();
+    if (orphans > 0) {
+      log.emit({
+        severityText: "WARN",
+        body: "closed orphaned activity spans from a previous process",
+        attributes: { count: orphans },
+      });
+    }
+  } catch (err) {
+    log.emit({
+      severityText: "WARN",
+      body: "boot activity sweep failed",
+      attributes: { error: err instanceof Error ? err.message : String(err) },
+    });
+  }
+
+  let delivering = false;
+  let lastPrune = 0;
+  const tick = setInterval(() => {
+    try {
+      const stale = store.sweepStale(ACTIVITY_STALE_AFTER_MS);
+      if (stale > 0) {
+        log.emit({
+          severityText: "WARN",
+          body: "closed stale activity spans (writer went silent)",
+          attributes: { count: stale },
+        });
+        stream.pump();
+      }
+      notifier.tick();
+      // Async delivery, reentrancy-guarded: a slow push service must not
+      // stack passes; the next tick simply retries what stayed pending.
+      if (!delivering) {
+        delivering = true;
+        void pushSender
+          .deliverPending(notifier)
+          .catch((err) =>
+            log.emit({
+              severityText: "WARN",
+              body: "push delivery pass failed",
+              attributes: { error: err instanceof Error ? err.message : String(err) },
+            })
+          )
+          .finally(() => {
+            delivering = false;
+          });
+      }
+      if (Date.now() - lastPrune > ACTIVITY_PRUNE_INTERVAL_MS) {
+        lastPrune = Date.now();
+        // Self-heal the pricing table on server traffic: without this, a
+        // long-lived server rolls up from whatever the boot-time refresh
+        // fetched. Single-flight + TTL inside ensureFresh make the hourly
+        // call free when fresh. The rollup path itself stays synchronous —
+        // never refresh from inside the store.
+        const pricing = deps.pricing as
+          | { ensureFresh?: () => Promise<void> }
+          | undefined;
+        if (typeof pricing?.ensureFresh === "function") {
+          void pricing.ensureFresh().catch(() => {});
+        }
+        store.prune({
+          // Full detail survives until the digest has covered it AND the
+          // retention window has passed; the hard ceiling bounds growth even
+          // if the digest job silently dies. The setting is read every pass
+          // so a change applies without a restart.
+          digestFloorAt: digestRetentionFloor(db),
+          detailRetentionMs: getDetailRetentionDays(db, log) * 24 * 60 * 60 * 1000,
+          hardCeilingMs: ACTIVITY_HARD_CEILING_MS,
+        });
+        notifier.pruneAcknowledged(INTENT_RETENTION_MS);
+      }
+    } catch (err) {
+      log.emit({
+        severityText: "WARN",
+        body: "activity tick failed",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
+    }
+  }, ACTIVITY_TICK_MS);
+  // A Bun interval would otherwise keep a closed test app's process alive.
+  if (typeof tick === "object" && "unref" in tick) tick.unref();
+
+  return {
+    store,
+    stream,
+    notifier,
+    pushSender,
+    query: (query) => runActivityQuery(db, store, query, notifier),
+    close() {
+      clearInterval(tick);
+      stream.close();
+    },
+  };
+}

package/src/activity/span-sink.ts

@@ -0,0 +1,152 @@
+/**
+ * The span-sink JSONL contract: how an agent-running cron step reports its
+ * activity to the wrapper that records the run.
+ *
+ * The wrapper (brain-ui's cron-run.ts) exports a file path in
+ * `BRAIN_ACTIVITY_SPAN_SINK`; the child process appends one JSON object per
+ * line and never reads the file back. The wrapper ingests incrementally
+ * (liveness) and once at exit (completeness), attaching everything under the
+ * run's root span. No core call site emits this yet — the contract ships
+ * first, fixture-verified, and producers arrive when core grows an agent
+ * loop (see the plan's Deferred to Follow-Up Work).
+ *
+ * Line shapes (unknown fields ignored, malformed lines skipped and counted):
+ *
+ *   {"type":"span_start","spanId":"s1","name":"execute_tool Read","ts":123,
+ *    "parentSpanId":"s0"?, "kind":"tool"?}
+ *   {"type":"span_end","spanId":"s1","outcome":"success","ts":124,
+ *    "reason":"..."?, "usage":{"inputTokens":1,...}?}
+ *   {"type":"event","spanId":"s1","eventType":"text","payload":...,"ts":125}
+ */
+import { readFileSync } from "fs";
+
+import { SPAN_OUTCOMES, type ActivityStore, type SpanOutcome, type SpanUsage } from "./store.js";
+
+export interface SpanSinkContext {
+  /** The run every ingested span belongs to. */
+  runId: string;
+  /** Parent for lines that name none — the cron root span. */
+  rootSpanId: string;
+  jobName?: string;
+}
+
+export interface SpanSinkResult {
+  /** Byte offset consumed so far — pass back on the next incremental call. */
+  offset: number;
+  ingested: number;
+  skipped: number;
+}
+
+/**
+ * Ingest new complete lines from a span-sink file. Incremental: pass the
+ * previous call's `offset`; a partial trailing line is left for next time.
+ * A missing file is an empty result, not an error — the child may simply
+ * never have emitted.
+ */
+export function ingestSpanSink(
+  store: ActivityStore,
+  path: string,
+  context: SpanSinkContext,
+  offset = 0
+): SpanSinkResult {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return { offset, ingested: 0, skipped: 0 };
+  }
+  if (text.length <= offset) return { offset, ingested: 0, skipped: 0 };
+
+  const chunk = text.slice(offset);
+  const lastNewline = chunk.lastIndexOf("\n");
+  if (lastNewline === -1) return { offset, ingested: 0, skipped: 0 };
+  const complete = chunk.slice(0, lastNewline);
+  const consumed = offset + lastNewline + 1;
+
+  let ingested = 0;
+  let skipped = 0;
+  for (const line of complete.split("\n")) {
+    if (!line.trim()) continue;
+    if (applyLine(store, line, context)) ingested++;
+    else skipped++;
+  }
+  return { offset: consumed, ingested, skipped };
+}
+
+function applyLine(store: ActivityStore, line: string, context: SpanSinkContext): boolean {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return false;
+  }
+  if (!parsed || typeof parsed !== "object") return false;
+  const spanId = str(parsed.spanId);
+  if (!spanId) return false;
+  // Sink span ids are namespaced by run so two runs' children can never
+  // collide in the shared store.
+  const scopedId = `${context.runId}:${spanId}`;
+
+  try {
+    switch (parsed.type) {
+      case "span_start": {
+        const name = str(parsed.name);
+        if (!name) return false;
+        const parent = str(parsed.parentSpanId);
+        store.startSpan({
+          spanId: scopedId,
+          runId: context.runId,
+          parentSpanId: parent ? `${context.runId}:${parent}` : context.rootSpanId,
+          name,
+          kind: parsed.kind === "subagent" ? "subagent" : "tool",
+          origin: "cron",
+          jobName: context.jobName,
+          startedAt: num(parsed.ts),
+        });
+        return true;
+      }
+      case "span_end": {
+        const outcome = str(parsed.outcome);
+        if (!outcome || !(SPAN_OUTCOMES as readonly string[]).includes(outcome)) return false;
+        return store.endSpan(scopedId, {
+          outcome: outcome as SpanOutcome,
+          reason: str(parsed.reason),
+          endedAt: num(parsed.ts),
+          usage: usageOf(parsed.usage),
+        });
+      }
+      case "event": {
+        const eventType = str(parsed.eventType);
+        if (!eventType) return false;
+        return store.appendEvent(scopedId, eventType, parsed.payload, num(parsed.ts)) !== null;
+      }
+      default:
+        return false;
+    }
+  } catch {
+    // A duplicate span_start (replayed line) or similar must not abort the
+    // whole ingest.
+    return false;
+  }
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+function usageOf(v: unknown): SpanUsage | undefined {
+  if (!v || typeof v !== "object") return undefined;
+  const u = v as Record<string, unknown>;
+  return {
+    inputTokens: num(u.inputTokens),
+    outputTokens: num(u.outputTokens),
+    cacheReadTokens: num(u.cacheReadTokens),
+    cacheCreationTokens: num(u.cacheCreationTokens),
+    costUsd: num(u.costUsd),
+    model: str(u.model),
+  };
+}