@schlessera/brain-ui-server 0.17.0 → 0.19.0

package/src/activity/runtime.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 } 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";
+
+// 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 }
+): ActivityRuntime {
+  const { log } = deps;
+  const store = createActivityStore(db);
+  const stream = createActivityStream(store, 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) },
+    });
+  }
+
+  const notifier = createActivityNotifier({
+    db,
+    store,
+    isWatched: (scope) => stream.isWatched(scope),
+    log,
+  });
+  const pushSender = createPushSender(db, { log });
+
+  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();
+        store.prune({
+          // Full detail survives until the digest has covered it; the hard
+          // ceiling bounds growth even if the digest job silently dies.
+          digestFloorAt: digestRetentionFloor(db),
+          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),
+  };
+}