@schlessera/brain-ui-react 0.35.0 → 0.36.0

package/src/lib/tool-names.ts

@@ -1,10 +1,22 @@
 /**
- * MCP-prefixed names of brain-ui's own in-process tools, as they appear in the
- * tool-call stream. Kept in one place so the timeline, history reconstruction,
- * and per-tool rendering all agree on the identifiers.
+ * Names of brain-ui's own in-process tools, as they appear in the tool-call
+ * stream. The names themselves come from the SDK's tool contracts — this
+ * module only derives the per-backend spellings the client has to match, so
+ * the timeline, history reconstruction and per-tool rendering all agree.
  */
-export const ASK_USER_TOOL_NAME = "mcp__brain-ui__ask_user";
-export const GET_LOCATION_TOOL_NAME = "mcp__brain-ui__get_current_location";
+
+import {
+  ASK_USER_CONTRACT,
+  GET_CURRENT_LOCATION_CONTRACT,
+  SHOW_BLOCK_CONTRACT,
+  visibleToolName,
+} from "@schlessera/brain-ui-sdk/client";
+
+export const ASK_USER_TOOL_NAME = visibleToolName(ASK_USER_CONTRACT.name, "claude");
+export const GET_LOCATION_TOOL_NAME = visibleToolName(
+  GET_CURRENT_LOCATION_CONTRACT.name,
+  "claude"
+);
 
 const LEGACY_MCP_PREFIX = "mcp__brain_ui__";
 const MCP_PREFIX = "mcp__brain-ui__";
@@ -22,11 +34,22 @@ export function normalizeToolName(name: string): string {
 }
 
 // The pi backend registers its ask-user tool under the bare name.
-const PI_ASK_USER_TOOL_NAME = "ask_user";
+const PI_ASK_USER_TOOL_NAME = visibleToolName(ASK_USER_CONTRACT.name, "pi");
 
 export const isAskUserTool = (name: string | undefined): boolean =>
   !!name &&
   (normalizeToolName(name) === ASK_USER_TOOL_NAME ||
     name === PI_ASK_USER_TOOL_NAME);
-export const isLocationTool = (name: string | undefined): boolean =>
-  !!name && normalizeToolName(name) === GET_LOCATION_TOOL_NAME;
+
+const SHOW_BLOCK_TOOL_NAME = visibleToolName(SHOW_BLOCK_CONTRACT.name, "claude");
+const PI_SHOW_BLOCK_TOOL_NAME = visibleToolName(SHOW_BLOCK_CONTRACT.name, "pi");
+
+/** A `show_block` call, under either backend's spelling (D41). */
+export const isShowBlockTool = (name: string | undefined): boolean =>
+  !!name &&
+  (normalizeToolName(name) === SHOW_BLOCK_TOOL_NAME ||
+    name === PI_SHOW_BLOCK_TOOL_NAME);
+
+// `isLocationTool` used to live here and was never called: the location result
+// is rendered by the contract-bound renderer now, which matches every spelling
+// of the name rather than the MCP-prefixed one alone.

package/src/root-context.tsx

@@ -0,0 +1,40 @@
+import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { useStore } from "zustand";
+import type { ExtractState, StoreApi } from "zustand/vanilla";
+import { defaultRoot } from "./default-root.js";
+import { createBrainUiRoot, type BrainUiRoot } from "./root.js";
+import type { BrainStores } from "./stores/create-stores.js";
+
+const RootContext = createContext<BrainUiRoot | null>(null);
+
+/** Supply a root explicitly when its lifetime extends beyond this subtree. */
+export function BrainUiProvider({ root, children }: { root?: BrainUiRoot; children: ReactNode }) {
+  const [owned] = useState(() => createBrainUiRoot());
+  const lifetimeRef = useRef({ generation: 0 });
+  useEffect(() => {
+    const lifetime = lifetimeRef.current;
+    const generation = ++lifetime.generation;
+    return () => {
+      // StrictMode replays effects using the same root. Dispose only when no
+      // replacement setup took ownership before this microtask runs.
+      queueMicrotask(() => { if (generation === lifetime.generation) owned.dispose(); });
+    };
+  }, [owned]);
+  return <RootContext.Provider value={root ?? owned}>{children}</RootContext.Provider>;
+}
+
+export function useBrainUiRoot(): BrainUiRoot {
+  return useContext(RootContext) ?? defaultRoot;
+}
+
+export function useBrainApi() { return useBrainUiRoot().api; }
+export function useBrainConfig() { return useBrainUiRoot().config; }
+
+/** The key carries the selected store's state type through the root lookup. */
+export function useRootStore<K extends keyof BrainStores, T>(
+  key: K,
+  selector: (state: ExtractState<BrainStores[K]>) => T,
+): T {
+  const store = useBrainUiRoot().stores[key] as StoreApi<ExtractState<BrainStores[K]>>;
+  return useStore<StoreApi<ExtractState<BrainStores[K]>>, T>(store, selector);
+}

package/src/root.ts

@@ -0,0 +1,83 @@
+import { createToolRendererRegistry, createAsrClientRegistry, type AsrClientRegistry, type ToolRendererRegistry } from "@schlessera/brain-ui-sdk/client";
+import { createBrainUiConfig, type BrainUiConfig } from "./config.js";
+import { createBrainApi, type BrainApi } from "./lib/api-client.js";
+import { apiBaseFor, getBackendUrlFor, getWsUrlFor } from "./lib/backend.js";
+import { createBrainStores, type BrainStores } from "./stores/create-stores.js";
+import { createWebSocketClient } from "./connection.js";
+
+export interface BrainUiRootOptions {
+  config?: Partial<BrainUiConfig>;
+  api?: BrainApi;
+  request?: (url: string, init?: RequestInit) => Promise<Response>;
+  /** Stable, distinct prefix per embedder. Omit for an ephemeral isolated root. */
+  storagePrefix?: string;
+  /** null disables persistence (SSR, stories, tests). */
+  storage?: Storage | null;
+}
+
+/** Dependencies the connection closes over; none are resolved from React. */
+export interface BrainUiServices {
+  config: BrainUiConfig;
+  api: BrainApi;
+  request: (url: string, init?: RequestInit) => Promise<Response>;
+  stores: BrainStores;
+  renderers: ToolRendererRegistry;
+  asr: AsrClientRegistry;
+  apiBase: () => string;
+  backendUrl: (path: string) => string;
+  wsUrl: () => string;
+  /** Mounted connectivity poller for this root, if any. */
+  recheckVpn: () => void;
+  registerVpnRecheck: (callback: () => void) => () => void;
+}
+
+export interface BrainUiRoot extends BrainUiServices {
+  connection: ReturnType<typeof createWebSocketClient>;
+  dispose: () => void;
+}
+
+/** Construct isolated state without opening a socket or starting a poller. */
+export function createBrainUiRoot(options: BrainUiRootOptions = {}): BrainUiRoot {
+  return createRoot(options, createBrainUiConfig(options.config));
+}
+
+/** @internal The default application supplies its existing mutable config. */
+export function createRoot(
+  options: BrainUiRootOptions,
+  config: BrainUiConfig,
+  renderers = createToolRendererRegistry(),
+  asr = createAsrClientRegistry(),
+): BrainUiRoot {
+  const request = options.request ?? ((url: string, init?: RequestInit) => fetch(url, init));
+  const apiBase = () => apiBaseFor(config);
+  const api = options.api ?? createBrainApi(apiBase, request);
+  const prefix = options.storagePrefix ?? `brain-ui:${crypto.randomUUID()}`;
+  const stores = createBrainStores({
+    api, apiBase, request,
+    storage: () => options.storage !== undefined ? options.storage
+      : typeof localStorage === "undefined" ? null : localStorage,
+    storageKey: (key) => prefix ? `${prefix}:${key}` : key,
+  });
+  let vpnRecheck: (() => void) | null = null;
+  const services: BrainUiServices = {
+    config, api, request, stores, renderers, asr, apiBase,
+    backendUrl: (path) => getBackendUrlFor(config, path),
+    wsUrl: () => getWsUrlFor(config),
+    recheckVpn: () => vpnRecheck?.(),
+    registerVpnRecheck(callback) {
+      vpnRecheck = callback;
+      return () => { if (vpnRecheck === callback) vpnRecheck = null; };
+    },
+  };
+  const connection = createWebSocketClient(services);
+  return Object.assign(services, {
+    connection,
+    dispose() {
+      connection.dispose();
+      stores.activity.dispose();
+      stores.graph.dispose();
+      stores.file.getState().reset();
+      vpnRecheck = null;
+    },
+  });
+}

package/src/stores/activity-state.ts

@@ -0,0 +1,295 @@
+import { createStore } from "zustand/vanilla";
+import type { StoreEnvironment } from "./store-environment.js";
+import type { ActivityState, MirrorMaps } from "./activity-store-types.js";
+import {
+  evictRun,
+  insertEvent,
+  pruneTerminalRuns,
+  rootSpanOf,
+} from "./activity-store-helpers.js";
+
+export {
+  EMPTY_EVENTS,
+  childSpans,
+  eventsFor,
+  narrativeEventsFor,
+  payloadEventsFor,
+  runEvents,
+  runSpans,
+  spanForTool,
+  subagentSpans,
+  timingFor,
+} from "./activity-store-helpers.js";
+
+/** How many finished runs' details are fetched when a session opens. */
+const HISTORY_RUN_LIMIT = 10;
+
+/**
+ * Client mirror of the server's activity record, fed by the snapshot-then-
+ * delta stream. The server computes; this store only holds and indexes what
+ * arrived — no aggregation, no derived rollups (those come from the REST
+ * activity API).
+ *
+ * Ordering contract (AE6): a snapshot sets the per-run high-water seq; a
+ * delta at or below it is DISCARDED (its content is already in the
+ * snapshot). Applying a delta is idempotent — span deltas upsert by spanId,
+ * event deltas insert-if-absent by (spanId, eventIndex) — so a duplicate
+ * delivery can never corrupt state. The guard is symmetric: a snapshot
+ * whose per-run high-water is STRICTLY LOWER than what is held (a stale
+ * frame racing a reconnect) is skipped for that run; an equal value still
+ * applies, so chunked append frames keep working.
+ *
+ * Bounded mirror: at most MAX_TERMINAL_RUNS finished runs are held — once a
+ * run past the cap, the oldest terminal runs (by root start time) are
+ * evicted wholesale (spans, events, high-water, reverse index). Live runs
+ * are never evicted; evicted history remains fetchable over REST.
+ */
+export function createActivityStore(env: StoreEnvironment) {
+  const { api } = env;
+  let disposed = false;
+  const store = createStore<ActivityState>((set, get) => ({
+    supported: false,
+    subscribed: {},
+    connectionEpoch: 0,
+    spans: {},
+    events: {},
+    highWater: {},
+    deltaSeq: {},
+    spanRun: {},
+
+    inbox: [],
+
+    loadInbox: async () => {
+      try {
+        const { intents } = await api.activityInbox();
+        if (!disposed) set({ inbox: intents });
+      } catch {
+        // Badge absence over a crash — the inbox is reachable from Activity.
+      }
+    },
+
+    acknowledgeIntent: async (id) => {
+      set((s) => ({ inbox: s.inbox.filter((i) => i.id !== id) }));
+      try {
+        await api.activityInboxAck(id);
+      } catch {
+        // Optimistic removal stands; the next load re-syncs.
+      }
+    },
+
+    acknowledgeAllIntents: async () => {
+      set({ inbox: [] });
+      try {
+        await api.activityInboxAckAll();
+      } catch {
+        // Same optimistic policy.
+      }
+    },
+
+    setSupported: (supported) => {
+      set({ supported });
+      if (supported) startInboxPolling();
+      else stopInboxPolling();
+    },
+
+    resetSubscriptions: () => set({ subscribed: {} }),
+
+    bumpConnectionEpoch: () => set((s) => ({ connectionEpoch: s.connectionEpoch + 1 })),
+
+    markSubscribed: (sessionId) =>
+      set((s) => ({ subscribed: { ...s.subscribed, [sessionId]: true } })),
+
+    applySnapshot: (msg) => {
+      set((s) => {
+        const maps: MirrorMaps = {
+          spans: { ...s.spans },
+          events: { ...s.events },
+          highWater: { ...s.highWater },
+          deltaSeq: { ...s.deltaSeq },
+          spanRun: { ...s.spanRun },
+        };
+        // Staleness guard: a run whose incoming high-water is strictly below
+        // what is held (snapshot floor or an applied delta) carries older
+        // state than what already applied — skip its spans/events. Equal
+        // still applies (chunked append frames).
+        const stale = new Set<string>();
+        for (const [runId, seq] of Object.entries(msg.highWaterSeq)) {
+          const held = Math.max(maps.highWater[runId] ?? 0, maps.deltaSeq[runId] ?? 0);
+          if (seq < held) stale.add(runId);
+          else maps.highWater[runId] = seq;
+        }
+        for (const span of msg.spans) {
+          if (stale.has(span.runId)) continue;
+          maps.spans[span.runId] = { ...(maps.spans[span.runId] ?? {}), [span.spanId]: span };
+          maps.spanRun[span.spanId] = span.runId;
+        }
+        for (const event of msg.events) {
+          const runId = maps.spanRun[event.spanId];
+          if (runId !== undefined && stale.has(runId)) continue;
+          maps.events[event.spanId] = insertEvent(maps.events[event.spanId], event);
+        }
+        // Scope eviction: a fresh session/index snapshot is authoritative for
+        // its scope. A held run that still looks live but is absent from the
+        // frame's high-water map is a ghost — the server says it is not
+        // running any more (its REST history remains fetchable).
+        if (!msg.append && (msg.view === "session" || msg.view === "index")) {
+          for (const [runId, byId] of Object.entries(maps.spans)) {
+            if (runId in msg.highWaterSeq) continue;
+            const root = rootSpanOf(byId);
+            if (!root || root.outcome !== undefined) continue;
+            const inScope = msg.view === "index" || root.sessionId === msg.sessionId;
+            if (inScope) evictRun(maps, runId);
+          }
+        }
+        pruneTerminalRuns(maps);
+        return maps;
+      });
+    },
+
+    applyDelta: (msg) => {
+      const s = get();
+      if (msg.seq <= (s.highWater[msg.runId] ?? 0)) return;
+      if (msg.span) {
+        const span = msg.span;
+        set((prev) => ({
+          spans: {
+            ...prev.spans,
+            [msg.runId]: { ...(prev.spans[msg.runId] ?? {}), [span.spanId]: span },
+          },
+          // Recording the applied seq keeps the snapshot staleness guard
+          // honest: a snapshot frame older than this delta must not roll it back.
+          deltaSeq: {
+            ...prev.deltaSeq,
+            [msg.runId]: Math.max(prev.deltaSeq[msg.runId] ?? 0, msg.seq),
+          },
+          // The mapping is almost always already present — re-spreading it on
+          // every delta would churn a large object for nothing.
+          ...(prev.spanRun[span.spanId] === msg.runId
+            ? {}
+            : { spanRun: { ...prev.spanRun, [span.spanId]: msg.runId } }),
+        }));
+        // A root span closing may push the mirror past the terminal-run cap.
+        if (span.parentSpanId === undefined && span.outcome !== undefined) {
+          const prev = get();
+          const maps: MirrorMaps = {
+            spans: { ...prev.spans },
+            events: { ...prev.events },
+            highWater: { ...prev.highWater },
+            deltaSeq: { ...prev.deltaSeq },
+            spanRun: { ...prev.spanRun },
+          };
+          if (pruneTerminalRuns(maps)) set(maps);
+        }
+      } else if (msg.event) {
+        const event = msg.event;
+        set((prev) => ({
+          events: { ...prev.events, [event.spanId]: insertEvent(prev.events[event.spanId], event) },
+          deltaSeq: {
+            ...prev.deltaSeq,
+            [msg.runId]: Math.max(prev.deltaSeq[msg.runId] ?? 0, msg.seq),
+          },
+          ...(prev.spanRun[event.spanId] !== undefined
+            ? {}
+            : { spanRun: { ...prev.spanRun, [event.spanId]: msg.runId } }),
+        }));
+      }
+    },
+
+    clear: () => set({ spans: {}, events: {}, highWater: {}, deltaSeq: {}, spanRun: {} }),
+  }));
+
+  /** One badge poller per page lifetime — the inbox is cheap and the badge
+   *  must be honest even when the Activity surface never opens. */
+  let inboxPoller: ReturnType<typeof setInterval> | null = null;
+  function startInboxPolling() {
+    if (inboxPoller || disposed) return;
+    void store.getState().loadInbox();
+    inboxPoller = setInterval(() => {
+      void store.getState().loadInbox();
+    }, 60_000);
+  }
+
+  /** Runs whose history has been fetched already (per page lifetime). */
+  const loadedHistorySessions = new Set<string>();
+
+  /**
+   * Pull a session's recent FINISHED runs from the REST activity API into the
+   * store. The live subscription's snapshot carries open runs only; this is
+   * what makes duration badges on history-loaded messages real (AE2) — span
+   * ids are tool-use ids, so the timeline's timing lookup starts hitting.
+   * Fire-and-forget; a failure just leaves badges absent, as before.
+   */
+  async function loadSessionActivityHistory(sessionId: string): Promise<void> {
+    if (loadedHistorySessions.has(sessionId)) return;
+    loadedHistorySessions.add(sessionId);
+    try {
+      const { history } = await api.activityRuns({ session: sessionId, limit: HISTORY_RUN_LIMIT });
+      const state = store.getState();
+      const details = await Promise.all(
+        history
+          .slice(0, HISTORY_RUN_LIMIT)
+          .filter((run) => !run.detailPruned)
+          .map((run) => api.activityRun(run.runId))
+      );
+      if (disposed) return;
+      for (const detail of details) {
+        if (detail.detailPruned || !detail.spans) continue;
+        state.applySnapshot({
+          type: "activity_snapshot",
+          view: "run",
+          runId: detail.runId,
+          spans: detail.spans,
+          events: detail.events ?? [],
+          highWaterSeq: { [detail.runId]: detail.highWaterSeq ?? 0 },
+        });
+      }
+    } catch {
+      // History timing is an enhancement; the transcript renders without it.
+      loadedHistorySessions.delete(sessionId);
+    }
+  }
+
+  /** Runs whose payload events have been backfilled over REST (per page lifetime). */
+  const payloadLoadedRuns = new Set<string>();
+
+  /**
+   * Backfill one finished run's tool payload events into the mirror. The
+   * history fetch above and the run-list default deliberately skip payload
+   * bodies — they exist for duration badges, not drill-ins — so the first
+   * expanded payload view of a history span pulls the full detail
+   * (`include=payloads`) and merges it. Live runs never need this: their
+   * payload events ride the delta stream. The merge is safe because a snapshot
+   * at the same high-water still applies and events insert-if-absent.
+   */
+  async function loadSpanPayloads(spanId: string): Promise<void> {
+    const state = store.getState();
+    const runId = state.spanRun[spanId];
+    if (!runId || payloadLoadedRuns.has(runId)) return;
+    const root = rootSpanOf(state.spans[runId] ?? {});
+    if (!root || root.outcome === undefined) return;
+    payloadLoadedRuns.add(runId);
+    try {
+      const detail = await api.activityRun(runId, { includePayloads: true });
+      if (disposed || detail.detailPruned || !detail.spans) return;
+      store.getState().applySnapshot({
+        type: "activity_snapshot",
+        view: "run",
+        runId,
+        spans: detail.spans,
+        events: detail.events ?? [],
+        highWaterSeq: { [runId]: detail.highWaterSeq ?? 0 },
+      });
+    } catch {
+      // Payloads are an enhancement; the row keeps its no-payload notice.
+      payloadLoadedRuns.delete(runId);
+    }
+  }
+  function stopInboxPolling() {
+    if (inboxPoller) clearInterval(inboxPoller);
+    inboxPoller = null;
+  }
+  return Object.assign(store, {
+    loadSessionActivityHistory, loadSpanPayloads,
+    dispose() { disposed = true; stopInboxPolling(); loadedHistorySessions.clear(); payloadLoadedRuns.clear(); },
+  });
+}