@schlessera/brain-ui-react 0.34.0 → 0.35.0

package/src/hooks/websocket-handlers/chat.ts

@@ -0,0 +1,210 @@
+import { activeChat, useChatStore } from "../../stores/chat-store.js";
+import type { ChatMessage, ToolCall, AskUserExchange } from "../../stores/chat-store.js";
+import type {
+  AskUserQuestion,
+  ServerMessage,
+  SessionHistoryMessage,
+} from "@schlessera/brain-ui-sdk/protocol";
+import { isAskUserTool } from "../../lib/tool-names.js";
+import type { ServerMessageHandlerMap } from "./types.js";
+
+type ChatFrame =
+  | "text_delta"
+  | "thinking_delta"
+  | "tool_use_start"
+  | "tool_input_delta"
+  | "tool_use_complete"
+  | "tool_approval_request"
+  | "tool_result"
+  | "ask_user_request"
+  | "result"
+  | "session_history"
+  | "status";
+
+let historyMessageCounter = 0;
+function historyId() {
+  return `hist-${++historyMessageCounter}-${Date.now()}`;
+}
+
+function convertHistoryMessage(msg: SessionHistoryMessage): ChatMessage {
+  // Fallback for history without chronological parts: synthesize the legacy
+  // grouped order (thinking, tools, text).
+  const parts =
+    msg.parts ??
+    [
+      ...(msg.thinking ? [{ kind: "thinking", text: msg.thinking } as const] : []),
+      ...msg.toolCalls.map((_, i) => ({ kind: "tool", toolIndex: i }) as const),
+      ...(msg.content ? [{ kind: "text", text: msg.content } as const] : []),
+    ];
+  const askUserExchanges = reconstructAskUserExchanges(msg.toolCalls);
+  return {
+    id: historyId(),
+    role: msg.role,
+    content: msg.content,
+    thinking: msg.thinking,
+    toolCalls: msg.toolCalls.map((tc): ToolCall => ({
+      id: tc.id,
+      name: tc.name,
+      input: tc.input,
+      inputJson: JSON.stringify(tc.input, null, 2),
+      output: tc.output,
+      isError: tc.isError,
+      status: "complete",
+    })),
+    parts,
+    isStreaming: false,
+    timestamp: Date.now(),
+    ...(askUserExchanges ? { askUserExchanges } : {}),
+    ...(msg.attachmentCount ? { attachmentCount: msg.attachmentCount } : {}),
+  };
+}
+
+/** Rebuild ask_user exchanges from a resumed message's tool calls. */
+function isBareAnswersMap(v: unknown): v is Record<string, string> {
+  return (
+    !!v &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    Object.values(v).every((x) => typeof x === "string")
+  );
+}
+
+function reconstructAskUserExchanges(
+  toolCalls: SessionHistoryMessage["toolCalls"]
+): AskUserExchange[] | undefined {
+  const exchanges: AskUserExchange[] = [];
+  for (const tc of toolCalls) {
+    if (!isAskUserTool(tc.name)) continue;
+    const questions = (tc.input?.questions as AskUserQuestion[]) ?? [];
+    const exchange: AskUserExchange = { requestId: tc.id, questions };
+    if (tc.output) {
+      try {
+        const payload = JSON.parse(tc.output) as {
+          answers?: Record<string, string>;
+          annotations?: AskUserExchange["annotations"];
+        };
+        if (payload && typeof payload === "object" && payload.answers) {
+          exchange.answers = payload.answers;
+          exchange.annotations = payload.annotations;
+        } else if (isBareAnswersMap(payload)) {
+          // The pi backend persists the bare answers map, without the
+          // `{answers}` envelope the Claude tool writes.
+          exchange.answers = payload;
+        }
+      } catch {
+        // Non-JSON output means the question was dismissed or errored out.
+        exchange.cancelled = true;
+      }
+    }
+    if (tc.isError && !exchange.answers) exchange.cancelled = true;
+    exchanges.push(exchange);
+  }
+  return exchanges.length ? exchanges : undefined;
+}
+
+/** Map a frame to the run-state its session should show in the session list. */
+export function runStateForFrame(msg: ServerMessage): "streaming" | "queued" | "idle" {
+  if (msg.type === "result" || msg.type === "error") return "idle";
+  if (msg.type === "status") {
+    if (msg.status === "queued") return "queued";
+    if (msg.status === "idle" || msg.status === "cancelled") return "idle";
+  }
+  return "streaming";
+}
+
+export const chatFrameHandlers = {
+  text_delta: (msg, context) => {
+    // Opening the bubble stays immediate — the first token should show a
+    // message starting, and every later delta needs isStreaming to be true.
+    if (!context.buffer()?.isStreaming) {
+      context.state.startAssistantMessage(context.key);
+    }
+    context.enqueueDelta(context.key, "text", msg.text);
+  },
+  thinking_delta: (msg, context) => {
+    if (!context.buffer()?.isStreaming) {
+      context.state.startAssistantMessage(context.key);
+    }
+    context.enqueueDelta(context.key, "thinking", msg.text);
+  },
+  tool_use_start: (msg, context) => {
+    // A tool call INSIDE a subagent nests under its Agent entry, rendered
+    // from the activity stream — putting it in the flat transcript would
+    // interleave fan-out work with the main turn's steps.
+    if (msg.parentToolUseId) return;
+    context.state.startToolCall(context.key, msg.toolUseId, msg.toolName);
+  },
+  tool_input_delta: (msg, context) => {
+    context.state.appendToolInput(context.key, msg.partialJson);
+  },
+  tool_use_complete: (msg, context) => {
+    // Subagent tool calls render nested (activity stream), and the flat
+    // store's name-based fallback match must never see them.
+    if (msg.parentToolUseId) return;
+    context.state.completeToolCall(context.key, msg.toolUseId, msg.toolName, msg.input);
+  },
+  tool_approval_request: (msg, context) => {
+    context.state.requestToolApproval(
+      context.key,
+      msg.toolUseId,
+      msg.toolName,
+      msg.input,
+      msg.description,
+      msg.kind
+    );
+  },
+  tool_result: (msg, context) => {
+    context.state.setToolResult(context.key, msg.toolUseId, msg.output, msg.isError);
+    // Once the agent receives the ask_user tool result, the exchange is
+    // complete — drop any leftover ask_user UI state.
+    const chat = context.buffer();
+    if (chat?.askUser?.answers || chat?.askUser?.cancelled) {
+      context.state.clearAskUser(context.key);
+    }
+  },
+  ask_user_request: (msg, context) => {
+    context.state.setAskUserRequest(context.key, msg.requestId, msg.questions);
+  },
+  result: (msg, context) => {
+    context.state.finishAssistantMessage(context.key);
+    context.resyncIfNeeded(msg.sessionId);
+  },
+  session_history: (msg, context) => {
+    const converted = msg.messages.map(convertHistoryMessage);
+    if (msg.append) {
+      context.state.appendMessages(context.key, converted);
+    } else {
+      // First (replacing) chunk = fresh authoritative transcript. Cancel any
+      // pending reconnect resync so we don't redundantly re-fetch it, and
+      // mark this session cold-resumed so idle-status handling doesn't loop.
+      context.state.setMessages(context.key, converted);
+      context.markHistoryReplaced(context.key);
+    }
+  },
+  status: (msg, context) => {
+    // Only finish streaming if this buffer actually started it
+    if (
+      (msg.status === "idle" || msg.status === "cancelled") &&
+      context.buffer()?.isStreaming
+    ) {
+      context.state.finishAssistantMessage(context.key);
+    }
+    // A session that finished while we were offline never delivers its
+    // `result` — the idle status on reconnect is the cue to resync. Keyed to
+    // THIS frame's session: a background session settling must not consume
+    // (or trigger) the active session's pending resync.
+    if (msg.status === "idle" || msg.status === "cancelled") {
+      const current = useChatStore.getState();
+      context.resyncIfNeeded(context.frameSessionId ?? current.activeSessionId);
+      // Cold load: we hold a stored session id but an empty transcript and
+      // the server is idle (so it sent no snapshot). Fetch the history.
+      // Only the active session's own (or an unscoped legacy) idle counts.
+      if (!context.frameSessionId || context.frameSessionId === current.activeSessionId) {
+        context.coldResumeIfNeeded(
+          current.activeSessionId,
+          activeChat(current).messages.length
+        );
+      }
+    }
+  },
+} satisfies ServerMessageHandlerMap<ChatFrame>;

package/src/hooks/websocket-handlers/connection.ts

@@ -0,0 +1,30 @@
+import { useActivityStore } from "../../stores/activity-store.js";
+import { useConnectionStore } from "../../stores/connection-store.js";
+import type { ServerMessageHandlerMap } from "./types.js";
+
+type ConnectionFrame = "server_hello" | "location_request" | "error";
+
+export const connectionFrameHandlers = {
+  server_hello: (msg, context) => {
+    useActivityStore.getState().setSupported(msg.capabilities?.activity === true);
+    // A new hello means a new connection: server-side subscriptions are gone.
+    useActivityStore.getState().resetSubscriptions();
+    // …and view-owned subscriptions (the Activity index) must re-send too.
+    useActivityStore.getState().bumpConnectionEpoch();
+    context.ensureActivitySubscription(context.state.activeSessionId);
+  },
+  location_request: (msg, context) => {
+    context.requestBrowserLocation(msg);
+  },
+  error: (msg, context) => {
+    // ALWAYS recorded. Appending to the transcript only works while a
+    // message is streaming, and this used to be the whole handler — so an
+    // error arriving between turns (a rejected frame, a failed resume) was
+    // dropped as silently on the client as it was on the server.
+    useConnectionStore.getState().reportError(msg.code, msg.message);
+    if (context.buffer()?.isStreaming) {
+      context.state.appendText(context.key, `\n\n**Error:** ${msg.message}`);
+      context.state.finishAssistantMessage(context.key);
+    }
+  },
+} satisfies ServerMessageHandlerMap<ConnectionFrame>;

package/src/hooks/websocket-handlers/index.ts

@@ -0,0 +1,59 @@
+import type { ServerMessage } from "@schlessera/brain-ui-sdk/protocol";
+import { activityFrameHandlers } from "./activity.js";
+import { chatFrameHandlers } from "./chat.js";
+import { connectionFrameHandlers } from "./connection.js";
+import { maskFrameHandlers } from "./mask.js";
+import { providerFrameHandlers } from "./provider.js";
+import type {
+  DispatchContext,
+  ServerMessageHandlerMap,
+  ServerMessageType,
+} from "./types.js";
+
+type HandlerKeys<T> = T extends unknown ? keyof T : never;
+type ClaimedFrame = HandlerKeys<
+  | typeof chatFrameHandlers
+  | typeof activityFrameHandlers
+  | typeof maskFrameHandlers
+  | typeof providerFrameHandlers
+  | typeof connectionFrameHandlers
+>;
+type DuplicateFrame =
+  | Extract<
+      keyof typeof chatFrameHandlers,
+      | keyof typeof activityFrameHandlers
+      | keyof typeof maskFrameHandlers
+      | keyof typeof providerFrameHandlers
+      | keyof typeof connectionFrameHandlers
+    >
+  | Extract<
+      keyof typeof activityFrameHandlers,
+      | keyof typeof maskFrameHandlers
+      | keyof typeof providerFrameHandlers
+      | keyof typeof connectionFrameHandlers
+    >
+  | Extract<
+      keyof typeof maskFrameHandlers,
+      keyof typeof providerFrameHandlers | keyof typeof connectionFrameHandlers
+    >
+  | Extract<keyof typeof providerFrameHandlers, keyof typeof connectionFrameHandlers>;
+
+type Assert<T extends true> = T;
+type Equal<A, B> = [A, B] extends [B, A] ? true : false;
+type _EveryFrameClaimed = Assert<Equal<ClaimedFrame, ServerMessageType>>;
+type _NoFrameClaimedTwice = Assert<Equal<DuplicateFrame, never>>;
+
+const serverMessageHandlers = {
+  ...chatFrameHandlers,
+  ...activityFrameHandlers,
+  ...maskFrameHandlers,
+  ...providerFrameHandlers,
+  ...connectionFrameHandlers,
+} satisfies ServerMessageHandlerMap<ServerMessageType>;
+
+export function dispatchServerMessage(msg: ServerMessage, context: DispatchContext): void {
+  // The mapped type preserves the message/handler correlation. TypeScript
+  // loses that correlation at an indexed union access, so restore it only at
+  // this single composition boundary.
+  serverMessageHandlers[msg.type](msg as never, context);
+}

package/src/hooks/websocket-handlers/mask.ts

@@ -0,0 +1,17 @@
+import { useMaskStore } from "../../stores/mask-store.js";
+import type { ServerMessageHandlerMap } from "./types.js";
+
+type MaskFrame = "mask_request";
+
+export const maskFrameHandlers = {
+  mask_request: (msg) => {
+    // Opens the editor; the answer travels back from the component, because
+    // only the user can say which part of the picture they meant.
+    useMaskStore.getState().open({
+      requestId: msg.requestId,
+      imagePath: msg.imagePath,
+      ...(msg.instruction ? { instruction: msg.instruction } : {}),
+      ...(msg.turnId ? { turnId: msg.turnId } : {}),
+    });
+  },
+} satisfies ServerMessageHandlerMap<MaskFrame>;

package/src/hooks/websocket-handlers/provider.ts

@@ -0,0 +1,35 @@
+import { useChatStore } from "../../stores/chat-store.js";
+import { useProviderStore } from "../../stores/provider-store.js";
+import type { ServerMessageHandlerMap } from "./types.js";
+
+type ProviderFrame = "session_info";
+
+export const providerFrameHandlers = {
+  session_info: (msg, context) => {
+    context.ensureActivitySubscription(msg.sessionId);
+    // Record backend ownership for renderer scoping — for ANY session, since
+    // background sessions keep their own transcript buffers. Older servers
+    // omit backendId; derive it from the pinned profile when still possible
+    // (fails only for since-hidden profiles, which then use the default).
+    const ownerBackendId =
+      msg.backendId ??
+      useProviderStore
+        .getState()
+        .available.find((p) => p.id === msg.providerId)?.backendId;
+    if (ownerBackendId) {
+      useChatStore.getState().setSessionBackend(msg.sessionId, ownerBackendId);
+    }
+    // bindDraftSession in the dispatcher handled draft adoption; an info frame
+    // may still re-pin the provider picker when it concerns the session in view.
+    const current = useChatStore.getState();
+    if (context.frameSessionId && context.frameSessionId === current.activeSessionId) {
+      useProviderStore.getState().setPinned(msg.providerId ?? null);
+      // Reattachment on a fresh connection: enter streaming mode so deltas
+      // append to a live assistant message instead of vanishing.
+      const chat = current.buffers[context.frameSessionId];
+      if (chat && !chat.isStreaming && chat.messages.length === 0) {
+        current.startAssistantMessage(context.frameSessionId);
+      }
+    }
+  },
+} satisfies ServerMessageHandlerMap<ProviderFrame>;

package/src/hooks/websocket-handlers/types.ts

@@ -0,0 +1,27 @@
+import type { ServerMessage } from "@schlessera/brain-ui-sdk/protocol";
+import type { ChatKey, SessionChat } from "../../stores/chat-store.js";
+import { useChatStore } from "../../stores/chat-store.js";
+
+export type ServerMessageType = ServerMessage["type"];
+
+export interface DispatchContext {
+  state: ReturnType<typeof useChatStore.getState>;
+  frameSessionId: string | undefined;
+  key: ChatKey;
+  buffer: () => SessionChat | null | undefined;
+  enqueueDelta: (key: ChatKey, kind: "text" | "thinking", text: string) => void;
+  ensureActivitySubscription: (sessionId: string | null | undefined) => void;
+  requestBrowserLocation: (
+    msg: Extract<ServerMessage, { type: "location_request" }>
+  ) => void;
+  resyncIfNeeded: (sessionId: string | null) => void;
+  coldResumeIfNeeded: (sessionId: string | null, messageCount: number) => void;
+  markHistoryReplaced: (key: ChatKey) => void;
+}
+
+export type ServerMessageHandlerMap<T extends ServerMessageType> = {
+  [K in T]: (
+    msg: Extract<ServerMessage, { type: K }>,
+    context: DispatchContext
+  ) => void;
+};

package/src/lib/api-client.ts

@@ -81,6 +81,26 @@ export interface BackendInfo {
   };
 }
 
+/** One active browser/device or delegated agent credential. */
+export interface PrincipalSummary {
+  id: string;
+  kind: "owner" | "agent" | "ambient" | "system";
+  auth_method: "password" | "passkey" | "delegated" | "ambient";
+  label: string;
+  created_at: number;
+  expires_at: number;
+  last_seen_at: number | null;
+  is_own: boolean;
+}
+
+/** The response to minting an agent. `cookie` is intentionally returned once. */
+export interface MintedAgent {
+  id: string;
+  label: string;
+  expiresAt: number;
+  cookie: string;
+}
+
 /** Auth status of one configured pi provider (mirror of the server view). */
 export interface PiAuthProviderStatus {
   providerId: string;
@@ -242,13 +262,18 @@ export const api = {
     }),
 
   brainAdd: (content: string, opts?: { type?: string; title?: string; tags?: string[] }) =>
-    fetchJson<{ success: boolean }>("/brain/add", {
+    fetchJson<{ success: boolean; path?: string; indexed?: boolean; indexError?: string }>("/brain/add", {
       method: "POST",
       body: JSON.stringify({ content, ...opts }),
     }),
 
+  brainIndex: () => fetchJson<{ success: boolean }>("/brain/index", {
+    method: "POST", body: "{}",
+  }),
+
   sessions: () =>
     fetchJson<{
+      unavailableBackends?: string[];
       sessions: Array<{
         id: string;
         title: string | null;
@@ -448,6 +473,20 @@ export const api = {
   logout: () =>
     fetchJson<{ ok: true }>("/auth/logout", { method: "POST" }),
 
+  principals: () =>
+    fetchJson<{ principals: PrincipalSummary[] }>("/auth/principals"),
+
+  principalMint: (label: string, ttlDays: number) =>
+    fetchJson<MintedAgent>("/auth/principals", {
+      method: "POST",
+      body: JSON.stringify({ label, ttlDays }),
+    }),
+
+  principalRevoke: (id: string) =>
+    fetchJson<{ ok: true }>(`/auth/principals/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+    }),
+
   /** Which login methods the server offers (public; drives the login screen). */
   authMethods: () =>
     fetchJson<{ password: boolean; passkey: boolean }>("/auth/methods"),

package/src/lib/format-time.ts

@@ -0,0 +1,20 @@
+/** Relative timestamp for list rows ("3m ago"); dates beyond a week. */
+export function formatRelativeTime(ms: number): string {
+  const diff = Date.now() - ms;
+  const future = diff < 0;
+  const distance = Math.abs(diff);
+  if (distance < 60_000) return future ? "in less than a minute" : "just now";
+  const minutes = future
+    ? Math.ceil(distance / 60_000)
+    : Math.floor(distance / 60_000);
+  if (minutes < 60) return future ? `in ${minutes}m` : `${minutes}m ago`;
+  const hours = future
+    ? Math.ceil(distance / 3_600_000)
+    : Math.floor(distance / 3_600_000);
+  if (hours < 24) return future ? `in ${hours}h` : `${hours}h ago`;
+  const days = future
+    ? Math.ceil(distance / 86_400_000)
+    : Math.floor(distance / 86_400_000);
+  if (days < 7) return future ? `in ${days}d` : `${days}d ago`;
+  return new Date(ms).toLocaleDateString();
+}

package/src/lib/push-registration.ts

@@ -0,0 +1,29 @@
+import { api } from "./api-client.js";
+
+/**
+ * Re-assert an existing browser subscription after authentication changes.
+ * This does not request permission or create a subscription: it only binds an
+ * already-enabled endpoint to the newly issued server principal.
+ */
+export async function rebindPushSubscriptionAfterLogin(): Promise<void> {
+  if (
+    typeof Notification === "undefined" ||
+    Notification.permission !== "granted" ||
+    typeof navigator === "undefined" ||
+    !("serviceWorker" in navigator)
+  ) {
+    return;
+  }
+
+  // Capture before awaiting: the page may begin navigating immediately after
+  // login while the service-worker readiness promise settles.
+  const serviceWorker = navigator.serviceWorker;
+  const label =
+    typeof navigator.userAgent === "string"
+      ? navigator.userAgent.slice(0, 100)
+      : undefined;
+  const registration = await serviceWorker.ready;
+  const subscription = await registration.pushManager.getSubscription();
+  if (!subscription) return;
+  await api.pushSubscribe(subscription.toJSON(), label);
+}

package/src/stores/activity-store-helpers.ts

@@ -0,0 +1,164 @@
+import type { ActivitySpan, ActivitySpanEvent } from "@schlessera/brain-ui-sdk/protocol";
+import type { ActivityState, MirrorMaps } from "./activity-store-types.js";
+
+/** Bound on the mirror: how many TERMINAL runs stay held. Live runs never count. */
+const MAX_TERMINAL_RUNS = 50;
+
+export function rootSpanOf(byId: Record<string, ActivitySpan>): ActivitySpan | undefined {
+  return Object.values(byId).find((span) => span.parentSpanId === undefined);
+}
+
+/** Drop a whole run from the mirror — spans, events, high-water, reverse index. */
+export function evictRun(maps: MirrorMaps, runId: string): void {
+  for (const spanId of Object.keys(maps.spans[runId] ?? {})) {
+    delete maps.events[spanId];
+    delete maps.spanRun[spanId];
+  }
+  delete maps.spans[runId];
+  delete maps.highWater[runId];
+  delete maps.deltaSeq[runId];
+}
+
+/**
+ * Enforce the terminal-run bound in place. Returns whether anything was
+ * evicted. Runs whose root span is still open (or unknown) are never touched.
+ */
+export function pruneTerminalRuns(maps: MirrorMaps): boolean {
+  const terminal: Array<{ runId: string; startedAt: number }> = [];
+  for (const [runId, byId] of Object.entries(maps.spans)) {
+    const root = rootSpanOf(byId);
+    if (root && root.outcome !== undefined) {
+      terminal.push({ runId, startedAt: root.startedAt });
+    }
+  }
+  if (terminal.length <= MAX_TERMINAL_RUNS) return false;
+  terminal.sort((a, b) => a.startedAt - b.startedAt);
+  for (const { runId } of terminal.slice(0, terminal.length - MAX_TERMINAL_RUNS)) {
+    evictRun(maps, runId);
+  }
+  return true;
+}
+
+export function insertEvent(
+  list: ActivitySpanEvent[] | undefined,
+  event: ActivitySpanEvent
+): ActivitySpanEvent[] {
+  const existing = list ?? [];
+  if (existing.some((e) => e.eventIndex === event.eventIndex)) return existing;
+  const next = [...existing, event];
+  next.sort((a, b) => a.eventIndex - b.eventIndex);
+  return next;
+}
+
+// --- Selectors (plain functions over the state, like activeChat) ---
+
+/** All spans of a run, roots first, then by start time. */
+export function runSpans(state: ActivityState, runId: string): ActivitySpan[] {
+  const byId = state.spans[runId];
+  if (!byId) return [];
+  return Object.values(byId).sort(
+    (a, b) =>
+      (a.parentSpanId ? 1 : 0) - (b.parentSpanId ? 1 : 0) || a.startedAt - b.startedAt
+  );
+}
+
+/** Direct children of a span (e.g. the tool calls inside a subagent). */
+export function childSpans(state: ActivityState, parentSpanId: string): ActivitySpan[] {
+  const runId = state.spanRun[parentSpanId];
+  if (!runId) return [];
+  return Object.values(state.spans[runId] ?? {})
+    .filter((s) => s.parentSpanId === parentSpanId)
+    .sort((a, b) => a.startedAt - b.startedAt);
+}
+
+/** The subagent spans spawned by a turn's Agent tool calls, live status included. */
+export function subagentSpans(state: ActivityState, sessionId: string): ActivitySpan[] {
+  const out: ActivitySpan[] = [];
+  for (const byId of Object.values(state.spans)) {
+    for (const span of Object.values(byId)) {
+      if (span.kind === "subagent" && span.sessionId === sessionId) out.push(span);
+    }
+  }
+  return out.sort((a, b) => a.startedAt - b.startedAt);
+}
+
+/** Stable empty result for `eventsFor` — a fresh `[]` per call would defeat
+ *  reference-equality checks in zustand selectors. */
+export const EMPTY_EVENTS: ActivitySpanEvent[] = Object.freeze(
+  [] as ActivitySpanEvent[]
+) as ActivitySpanEvent[];
+
+/** Ordered events of a span; the shared frozen empty array when none. */
+export function eventsFor(state: ActivityState, spanId: string): ActivitySpanEvent[] {
+  return state.events[spanId] ?? EMPTY_EVENTS;
+}
+
+/** Payload event types the tool expander owns — every OTHER type belongs to
+ *  the narrative stream (`narrativeEventsFor`) so nothing recorded is
+ *  rendered nowhere. */
+const TOOL_PAYLOAD_TYPES = new Set(["tool_input", "tool_output"]);
+
+/**
+ * The recorded input/output payload events of a tool span (AE7). Returns a
+ * fresh array per call — subscribe through `useShallow` (like `childSpans`).
+ */
+export function payloadEventsFor(state: ActivityState, spanId: string): ActivitySpanEvent[] {
+  const events = state.events[spanId];
+  if (!events) return EMPTY_EVENTS;
+  const payloads = events.filter((e) => TOOL_PAYLOAD_TYPES.has(e.eventType));
+  return payloads.length > 0 ? payloads : EMPTY_EVENTS;
+}
+
+/**
+ * Everything recorded against a span that is NOT a tool input/output payload:
+ * transcript excerpts, job output, and any span-sink event type a producer
+ * invents. Rendered as the span's narrative so an unknown type degrades to a
+ * labelled block rather than to invisibility.
+ */
+export function narrativeEventsFor(
+  state: ActivityState,
+  spanId: string
+): ActivitySpanEvent[] {
+  const events = state.events[spanId];
+  if (!events) return EMPTY_EVENTS;
+  const rest = events.filter((e) => !TOOL_PAYLOAD_TYPES.has(e.eventType));
+  return rest.length > 0 ? rest : EMPTY_EVENTS;
+}
+
+/** Every event recorded under a run, ordered by time — the run detail's
+ *  narrative stream and the raw-trace dump both read through this. */
+export function runEvents(state: ActivityState, runId: string): ActivitySpanEvent[] {
+  const byId = state.spans[runId];
+  if (!byId) return EMPTY_EVENTS;
+  const out: ActivitySpanEvent[] = [];
+  for (const spanId of Object.keys(byId)) {
+    const events = state.events[spanId];
+    if (events) out.push(...events);
+  }
+  if (out.length === 0) return EMPTY_EVENTS;
+  return out.sort((a, b) => a.ts - b.ts || a.eventIndex - b.eventIndex);
+}
+
+/** The span behind one tool call (span ids ARE toolUseIds), if streamed. */
+export function spanForTool(state: ActivityState, toolUseId: string): ActivitySpan | null {
+  const runId = state.spanRun[toolUseId];
+  return runId ? (state.spans[runId]?.[toolUseId] ?? null) : null;
+}
+
+/**
+ * Server-stamped timing for a tool call. One clock for live and reloaded
+ * views: when the activity stream carries the span, its timestamps win over
+ * client stamps (AE2 — live and revisit must render identical timings).
+ * `waitUntil` marks the approval-wait/execution boundary.
+ */
+export function timingFor(
+  state: ActivityState,
+  toolUseId: string
+): { startedAt: number; endedAt?: number } | null {
+  const span = spanForTool(state, toolUseId);
+  if (!span) return null;
+  return {
+    startedAt: span.waitUntil ?? span.startedAt,
+    ...(span.endedAt !== undefined ? { endedAt: span.endedAt } : {}),
+  };
+}