@schlessera/brain-ui-react 0.19.0 → 0.21.0

package/src/components/activity/span-bits.tsx

@@ -1,8 +1,20 @@
-import { isFailureOutcome } from "@schlessera/brain-ui-sdk/protocol";
-import type { ActivitySpan, ActivitySpanOutcome } from "@schlessera/brain-ui-sdk/protocol";
+import { useEffect } from "react";
+import { useShallow } from "zustand/react/shallow";
+import { isFailureOutcome, SPAN_TOOL_NAME_PREFIX } from "@schlessera/brain-ui-sdk/protocol";
+import type {
+  ActivitySpan,
+  ActivitySpanEvent,
+  ActivitySpanOutcome,
+  BillingMode,
+} from "@schlessera/brain-ui-sdk/protocol";
 
+import {
+  useActivityStore,
+  payloadEventsFor,
+  loadSpanPayloads,
+} from "../../stores/activity-store.js";
 import { cn } from "../../lib/utils.js";
-import { getToolLabel } from "../chat/tool-views.js";
+import { getToolLabel, formatTokenCount } from "../chat/tool-views.js";
 
 /**
  * THE status dot for activity spans — one outcome→color mapping so every
@@ -52,7 +64,175 @@ export function spanToolLabel(span: ActivitySpan): string {
   if (span.toolName) return getToolLabel(span.toolName);
   if (span.kind === "turn") return "Turn";
   if (span.kind === "cron") return span.jobName ?? span.name;
-  return getToolLabel(span.name.replace(/^execute_tool /, ""));
+  return getToolLabel(
+    span.name.startsWith(SPAN_TOOL_NAME_PREFIX)
+      ? span.name.slice(SPAN_TOOL_NAME_PREFIX.length)
+      : span.name
+  );
+}
+
+/**
+ * The recorded input/output of one tool span, expanded under its row — the
+ * ONE payload renderer shared by the subagent drill-in and the run detail.
+ * Mounted only while expanded (collapsed rows never subscribe). A span with
+ * no payload events (recorded before capture shipped) states so instead of
+ * offering an empty block (AE7); a payload clipped at persist time carries
+ * the wire `truncated` flag, rendered as a hint line under the block.
+ */
+export function SpanPayload({ spanId }: { spanId: string }) {
+  const events = useActivityStore(useShallow((s) => payloadEventsFor(s, spanId)));
+  // History fetches skip payload bodies (they exist for duration badges);
+  // the first expand of a finished run backfills them over REST. A no-op for
+  // live runs (payloads ride the WS deltas) and once per run thereafter.
+  useEffect(() => {
+    if (events.length === 0) void loadSpanPayloads(spanId);
+  }, [spanId, events.length]);
+  if (events.length === 0) {
+    return (
+      <p className="px-2 py-1 text-[11px] text-muted-foreground/60">
+        No payload recorded for this run.
+      </p>
+    );
+  }
+  return (
+    <div className="space-y-1.5 px-2 py-1">
+      {events.map((event) => (
+        <SpanEventBlock key={`${event.spanId}:${event.eventIndex}`} event={event} />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Display label for a span event type. Known types get prose; an unknown one
+ * (a span-sink producer is free to invent them) prints its own type rather
+ * than being mislabelled as output.
+ */
+export function eventTypeLabel(eventType: string): string {
+  if (eventType === "tool_input") return "Input";
+  if (eventType === "tool_output") return "Output";
+  if (eventType.startsWith("transcript_")) return `Transcript · ${eventType.slice("transcript_".length)}`;
+  if (eventType === "job_output") return "Job output";
+  return eventType.replace(/_/g, " ");
+}
+
+/**
+ * ONE labelled block per recorded event — the shared renderer behind the tool
+ * payload expander and the run detail's narrative stream, so every event type
+ * lands somewhere visible instead of only the two the expander knows.
+ */
+export function SpanEventBlock({ event }: { event: ActivitySpanEvent }) {
+  const text =
+    typeof event.payload === "string" ? event.payload : JSON.stringify(event.payload, null, 2);
+  return (
+    <div>
+      <div className="mb-0.5 text-[10px] uppercase text-muted-foreground/60">
+        {eventTypeLabel(event.eventType)}
+      </div>
+      <pre className="max-h-56 overflow-auto whitespace-pre-wrap break-words rounded-md bg-background/60 p-2 font-[family-name:var(--font-mono)] text-[11px] leading-relaxed text-muted-foreground">
+        {text}
+      </pre>
+      {event.truncated && (
+        <p className="mt-0.5 text-[10px] italic text-muted-foreground/60">… truncated</p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * A span's own token/model line, or null when the backend recorded no usage
+ * for it (every tool span, and any cron root without a span-sink producer).
+ * Cache reads are named separately: they are the cheap half of the bill and
+ * folding them into "in" would misstate what the run actually consumed.
+ */
+export function formatSpanUsage(span: ActivitySpan): string | null {
+  const usage = span.usage;
+  if (!usage) return null;
+  const parts: string[] = [];
+  if (usage.model) parts.push(usage.model);
+  if (usage.inputTokens) parts.push(`${formatTokenCount(usage.inputTokens)} in`);
+  if (usage.outputTokens) parts.push(`${formatTokenCount(usage.outputTokens)} out`);
+  if (usage.cacheReadTokens) parts.push(`${formatTokenCount(usage.cacheReadTokens)} cached`);
+  if (usage.cacheCreationTokens)
+    parts.push(`${formatTokenCount(usage.cacheCreationTokens)} cache write`);
+  return parts.length > 0 ? parts.join(" · ") : null;
+}
+
+/**
+ * THE effective-cost glyph — one three-state rule so no surface ever renders
+ * an unknown cost as $0.00 (AE3): absent/NULL is "—" (we don't know), 0 is
+ * "subbed" when the run was subscription-billed and "free" otherwise (a
+ * genuinely zero-rate model, e.g. an OpenRouter free tier), positive is
+ * dollars, "~"-prefixed when computed from estimated rates. Sub-cent costs
+ * floor at "<$0.01" rather than rounding down to a zero look-alike.
+ *
+ * The zero split matters: a seat plan absorbing the run and a model that
+ * costs nothing are both $0 additive, but only one of them stays $0 once the
+ * subscription is cancelled.
+ */
+export function formatEffectiveCost(
+  costUsd: number | null | undefined,
+  estimate?: boolean,
+  billingMode?: BillingMode | null
+): string {
+  if (costUsd === null || costUsd === undefined) return "—";
+  if (costUsd === 0) return billingMode === "subscription" ? "subbed" : "free";
+  const amount = costUsd < 0.005 ? "<$0.01" : `$${costUsd.toFixed(2)}`;
+  return estimate ? `~${amount}` : amount;
+}
+
+/**
+ * An aggregate's effective-cost sum. Sums exclude unknown-cost runs, so a
+ * nonzero `unpricedRuns` makes the number a floor ("≥ $X"), never a total.
+ * A known sub-cent sum floors at "<$0.01" like the per-run glyph — only an
+ * exact 0 (genuinely nothing to add up) renders "$0.00" (AE3).
+ */
+export function formatAggregateCost(effectiveUsd: number, unpricedRuns: number): string {
+  const amount =
+    effectiveUsd > 0 && effectiveUsd < 0.005 ? "<$0.01" : `$${effectiveUsd.toFixed(2)}`;
+  return unpricedRuns > 0 ? `≥ ${amount}` : amount;
+}
+
+/**
+ * A run row's cost text, three-way on `effectiveCostUsd`: ABSENT means a
+ * pre-pricing server never sent the field — fall back to the original
+ * list-cost rendering (a positive `costUsd`, else nothing) instead of
+ * claiming unknown; explicit null means THIS server computed "unknown" and
+ * renders the em dash; a number goes through `formatEffectiveCost` (AE3).
+ */
+export function runCostText(run: {
+  costUsd: number | null;
+  effectiveCostUsd?: number | null;
+  pricingEstimate?: boolean;
+  billingMode?: BillingMode | null;
+}): string | null {
+  if (run.effectiveCostUsd === undefined) {
+    return run.costUsd !== null && run.costUsd > 0 ? `$${run.costUsd.toFixed(2)}` : null;
+  }
+  return formatEffectiveCost(run.effectiveCostUsd, run.pricingEstimate, run.billingMode);
+}
+
+/**
+ * The digest card's cost clause (no leading separator), effective-only, or
+ * null for "say nothing". A digest persisted before pricing shipped carries
+ * neither new field and keeps its old list-cost clause.
+ */
+export function digestCostClause(digest: {
+  costUsd: number;
+  effectiveCostUsd?: number;
+  unpricedRuns?: number;
+}): string | null {
+  if (digest.effectiveCostUsd === undefined) {
+    return digest.costUsd > 0 ? `$${digest.costUsd.toFixed(2)} spent` : null;
+  }
+  const unpriced = digest.unpricedRuns ?? 0;
+  const qualifier = unpriced > 0 ? ` (${unpriced} unpriced)` : "";
+  if (digest.effectiveCostUsd > 0) {
+    return `${formatAggregateCost(digest.effectiveCostUsd, unpriced)} spent${qualifier}`;
+  }
+  // Known-zero spend: nothing to add up, but the unknowns still get named.
+  if (unpriced > 0) return `${unpriced} unpriced`;
+  return "free";
 }
 
 /** The "9+" unread-count bubble shared by the rail and the tab bar. Hidden at 0. */

package/src/components/chat/subagent-view.tsx

@@ -1,5 +1,5 @@
-import { useMemo } from "react";
-import { ArrowLeft, Bot, Check, X } from "lucide-react";
+import { useMemo, useState } from "react";
+import { ArrowLeft, Bot, Check, ChevronRight, X } from "lucide-react";
 import { motion } from "framer-motion";
 import { useShallow } from "zustand/react/shallow";
 import { isFailureOutcome } from "@schlessera/brain-ui-sdk/protocol";
@@ -10,7 +10,7 @@ import { useUIStore } from "../../stores/ui-store.js";
 import { useChatStore, activeChat } from "../../stores/chat-store.js";
 import { cn } from "../../lib/utils.js";
 import { getToolLabel, formatDuration } from "./tool-views.js";
-import { SpanStatusDot, spanToolLabel } from "../activity/span-bits.js";
+import { SpanPayload, SpanStatusDot, spanToolLabel } from "../activity/span-bits.js";
 
 /**
  * Drill-in view of one subagent: the span tree under its Agent tool call,
@@ -171,33 +171,43 @@ function BackButton({ onClick }: { onClick: () => void }) {
 }
 
 function SpanRow({ span, onOpen }: { span: ActivitySpan; onOpen?: () => void }) {
+  // Tool rows expand to their recorded payload (AE7); a pre-feature span
+  // expands to the no-payload notice, so the affordance stays uniform.
+  const [expanded, setExpanded] = useState(false);
   const running = span.outcome === undefined;
   const failed = isFailureOutcome(span.outcome);
+  const expandable = !onOpen && span.kind === "tool";
   const duration =
     span.endedAt !== undefined
       ? formatDuration(span.endedAt - (span.waitUntil ?? span.startedAt))
       : null;
   return (
-    <motion.div
-      initial={{ opacity: 0, y: 2 }}
-      animate={{ opacity: 1, y: 0 }}
-      className={cn(
-        "flex items-center gap-2 rounded-md px-2 py-1.5 text-xs",
-        failed ? "text-destructive/80" : "text-muted-foreground",
-        onOpen && "cursor-pointer hover:text-foreground"
-      )}
-      onClick={onOpen}
-    >
-      <SpanStatusDot span={span} className="h-2 w-2" />
-      <span className="font-[family-name:var(--font-mono)] font-medium">
-        {spanToolLabel(span)}
-      </span>
-      {span.outcome && span.outcome !== "success" && (
-        <span className="text-[10px] uppercase">{span.outcome}</span>
-      )}
-      <span className="ml-auto font-[family-name:var(--font-mono)] text-[10px] text-muted-foreground/50">
-        {duration ?? (running ? "…" : "")}
-      </span>
+    <motion.div initial={{ opacity: 0, y: 2 }} animate={{ opacity: 1, y: 0 }}>
+      <div
+        className={cn(
+          "flex items-center gap-2 rounded-md px-2 py-1.5 text-xs",
+          failed ? "text-destructive/80" : "text-muted-foreground",
+          (onOpen || expandable) && "cursor-pointer hover:text-foreground"
+        )}
+        onClick={onOpen ?? (expandable ? () => setExpanded((v) => !v) : undefined)}
+      >
+        <SpanStatusDot span={span} className="h-2 w-2" />
+        <span className="font-[family-name:var(--font-mono)] font-medium">
+          {spanToolLabel(span)}
+        </span>
+        {span.outcome && span.outcome !== "success" && (
+          <span className="text-[10px] uppercase">{span.outcome}</span>
+        )}
+        <span className="ml-auto font-[family-name:var(--font-mono)] text-[10px] text-muted-foreground/50">
+          {duration ?? (running ? "…" : "")}
+        </span>
+        {expandable && (
+          <ChevronRight
+            className={cn("h-3 w-3 shrink-0 transition-transform", expanded && "rotate-90")}
+          />
+        )}
+      </div>
+      {expanded && <SpanPayload spanId={span.spanId} />}
     </motion.div>
   );
 }

package/src/components/settings/models-tab.tsx

@@ -1,6 +1,7 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { Eye, EyeOff, Loader2, RefreshCw } from "lucide-react";
 import type {
+  BillingMode,
   ModelCatalogEntry,
   ModelCatalogResponse,
 } from "@schlessera/brain-ui-sdk/protocol";
@@ -21,6 +22,9 @@ export function ModelsTab({ active }: { active: boolean }) {
   const [refreshing, setRefreshing] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const loadProviders = useProviderStore((s) => s.loadProviders);
+  const commitGate = useRef(createRequestGate());
+  /** Serializes full-record PUTs — see commitCatalog. */
+  const commitQueue = useRef<Promise<void>>(Promise.resolve());
 
   useEffect(() => {
     if (!active) return;
@@ -45,34 +49,86 @@ export function ModelsTab({ active }: { active: boolean }) {
     };
   }, [active]);
 
+  /**
+   * Optimistic-update skeleton shared by the hidden toggle and the billing
+   * select: the change is the user's own click, so reflect it immediately,
+   * commit, then reload the composer picker's own roster copy (fetched once
+   * on mount, it would otherwise lag until a page reload). A failed write
+   * rolls back and surfaces the error.
+   *
+   * Ordered through `createRequestGate`: two rows edited within one
+   * round-trip interleave, and without the guard the FIRST response (or its
+   * failure rollback) lands last and silently overwrites the newer edit. A
+   * superseded response/rollback is dropped — the newer request's payload
+   * was built on top of this one's optimistic state, so it already carries
+   * this change (and its own catch surfaces any error that still matters).
+   */
+  async function commitCatalog(
+    optimistic: ModelCatalogResponse,
+    commit: () => Promise<ModelCatalogResponse>
+  ) {
+    const isCurrent = commitGate.current.begin();
+    const previous = catalog;
+    setCatalog(optimistic);
+    setError(null);
+    // The gate drops superseded RESPONSES; this queue serializes the WRITES.
+    // Both matter: the server stores full records, so two concurrent PUTs
+    // could land older-last and silently clobber the newer record server-side
+    // even while the client looked right. Each commit waits for the previous
+    // one to settle; payloads are built on optimistic state, so the newest
+    // write already carries every earlier edit.
+    const run = commitQueue.current.then(async () => {
+      try {
+        const confirmed = await commit();
+        if (isCurrent()) setCatalog(confirmed);
+        void loadProviders();
+      } catch (err) {
+        if (isCurrent()) {
+          setCatalog(previous);
+          setError(err instanceof Error ? err.message : "Could not save");
+        }
+      }
+    });
+    commitQueue.current = run;
+    await run;
+  }
+
   async function toggleHidden(entry: ModelCatalogEntry) {
     if (!catalog) return;
-    const previous = catalog;
     const hidden = catalog.models
       .filter((model) =>
         model.id === entry.id ? !entry.hidden : model.hidden
       )
       .map((model) => model.id);
 
-    // Optimistic: the list is the user's own click, so reflect it immediately
-    // and roll back if the write fails.
-    setCatalog({
-      ...catalog,
-      models: catalog.models.map((model) =>
-        model.id === entry.id ? { ...model, hidden: !model.hidden } : model
-      ),
-    });
-    setError(null);
-    try {
-      setCatalog(await api.setHiddenModels(hidden));
-      // The composer's picker holds its own copy of the roster, fetched once on
-      // mount — without this it keeps offering a model the user just hid until
-      // the page is reloaded.
-      void loadProviders();
-    } catch (err) {
-      setCatalog(previous);
-      setError(err instanceof Error ? err.message : "Could not save");
-    }
+    await commitCatalog(
+      {
+        ...catalog,
+        models: catalog.models.map((model) =>
+          model.id === entry.id ? { ...model, hidden: !model.hidden } : model
+        ),
+      },
+      () => api.setHiddenModels(hidden)
+    );
+  }
+
+  async function changeBilling(entry: ModelCatalogEntry, next: BillingMode | "auto") {
+    if (!catalog) return;
+
+    // What "auto" resolves to is only known server-side, so switching back to
+    // auto keeps the current resolved mode until the confirmed catalog
+    // corrects it a beat later.
+    await commitCatalog(
+      {
+        ...catalog,
+        models: catalog.models.map((model) => {
+          if (model.id !== entry.id) return model;
+          const { billingOverride: _cleared, ...base } = model;
+          return next === "auto" ? base : { ...base, billingOverride: next, billingMode: next };
+        }),
+      },
+      () => api.setBillingOverrides(nextBillingOverrides(catalog.models, entry.id, next))
+    );
   }
 
   async function onRefresh() {
@@ -115,6 +171,7 @@ export function ModelsTab({ active }: { active: boolean }) {
                 key={entry.id}
                 entry={entry}
                 onToggle={() => toggleHidden(entry)}
+                onBilling={(next) => changeBilling(entry, next)}
               />
             ))}
             {catalog?.models.length === 0 && (
@@ -162,12 +219,51 @@ export function ModelsTab({ active }: { active: boolean }) {
   );
 }
 
+/**
+ * Request-ordering guard for optimistic commits: `begin()` claims a token
+ * and returns a predicate that holds only while no later request has begun.
+ * An older in-flight request must never write over a newer edit's state.
+ */
+export function createRequestGate(): { begin: () => () => boolean } {
+  let seq = 0;
+  return {
+    begin() {
+      const token = ++seq;
+      return () => seq === token;
+    },
+  };
+}
+
+/**
+ * The billing-override record PUT after changing one profile: every other
+ * profile keeps its stored override, the changed one is set — or, for "auto",
+ * REMOVED, never stored as a redundant explicit value.
+ */
+export function nextBillingOverrides(
+  models: ModelCatalogEntry[],
+  id: string,
+  next: BillingMode | "auto"
+): Record<string, BillingMode> {
+  const billing: Record<string, BillingMode> = {};
+  for (const model of models) {
+    const value = model.id === id ? (next === "auto" ? undefined : next) : model.billingOverride;
+    if (value) billing[model.id] = value;
+  }
+  return billing;
+}
+
+function billingLabel(mode: BillingMode): string {
+  return mode === "api" ? "API" : "Subscription";
+}
+
 function ModelRow({
   entry,
   onToggle,
+  onBilling,
 }: {
   entry: ModelCatalogEntry;
   onToggle: () => void;
+  onBilling: (next: BillingMode | "auto") => void;
 }) {
   const Icon = entry.hidden ? EyeOff : Eye;
   return (
@@ -185,6 +281,24 @@ function ModelRow({
           {entry.source === "declared" ? " · configured" : ""}
         </p>
       </div>
+      {/* Tri-state billing: the collapsed control always reads as the
+          RESOLVED mode — the Auto option carries what auto resolves to, so
+          "Auto (subscription)" and a forced "Subscription" are both legible
+          at a glance. */}
+      <select
+        value={entry.billingOverride ?? "auto"}
+        onChange={(e) => onBilling(e.target.value as BillingMode | "auto")}
+        aria-label={`Billing for ${entry.label}`}
+        className="h-8 shrink-0 rounded-lg border border-border-subtle bg-surface px-1.5 text-[11px] text-muted-foreground transition-colors hover:border-primary hover:text-foreground"
+      >
+        <option value="auto">
+          {!entry.billingOverride && entry.billingMode
+            ? `Auto (${billingLabel(entry.billingMode).toLowerCase()})`
+            : "Auto"}
+        </option>
+        <option value="subscription">Subscription</option>
+        <option value="api">API</option>
+      </select>
       <button
         onClick={onToggle}
         title={entry.hidden ? "Show in picker" : "Hide from picker"}

package/src/lib/api-client.ts

@@ -6,6 +6,7 @@ import type {
   PronunciationOverride,
   ProviderInfo,
   PasskeySummary,
+  BillingMode,
   ModelCatalogResponse,
   ActivityRunSummary,
   ActivityRunDetail,
@@ -52,6 +53,23 @@ export interface BrainSearchResponse {
   warnings: string[];
 }
 
+/**
+ * Pricing-table freshness (GET /api/models/pricing) — mirrors the server
+ * pricing service's state. The route is additive: an older server 404s, and
+ * callers treat the rejection as "no freshness signal, show nothing".
+ */
+export interface PricingState {
+  enabled: boolean;
+  /** When a refresh last succeeded (either source); null when none ever has. */
+  fetchedAt: number | null;
+  /** The current table is older than the TTL (or was never fetched). */
+  stale: boolean;
+  /** What the table is served from: remote data (cache included) or the bundled snapshot. */
+  source: "remote" | "snapshot";
+  /** Last refresh failure, if the current table is served despite one. */
+  error?: string;
+}
+
 /** Backend id + capability flags the client renders behavior from. */
 export interface BackendInfo {
   id: string;
@@ -181,6 +199,16 @@ export const api = {
       body: JSON.stringify({ hidden }),
     }),
 
+  /** Replace the billing-override record (full record, not a delta); returns the new catalog. */
+  setBillingOverrides: (billing: Record<string, BillingMode>) =>
+    fetchJson<ModelCatalogResponse>("/models/billing", {
+      method: "PUT",
+      body: JSON.stringify({ billing }),
+    }),
+
+  /** Pricing-table freshness for the Activity staleness indicator (see `PricingState`). */
+  pricingState: () => fetchJson<PricingState>("/models/pricing"),
+
   /** Force a discovery refresh, bypassing the TTL. */
   refreshModels: () =>
     fetchJson<ModelCatalogResponse>("/models/refresh", { method: "POST" }),
@@ -261,8 +289,16 @@ export const api = {
           .join("&")
     ),
 
-  activityRun: (runId: string) =>
-    fetchJson<ActivityRunDetail>(`/activity/runs/${encodeURIComponent(runId)}`),
+  /**
+   * One run's detail. Payload bodies (tool_input/tool_output events) are
+   * excluded by default — the session-history fetch only needs span timings —
+   * and opted into by the drill-in views via `includePayloads`.
+   */
+  activityRun: (runId: string, opts?: { includePayloads?: boolean }) =>
+    fetchJson<ActivityRunDetail>(
+      `/activity/runs/${encodeURIComponent(runId)}` +
+        (opts?.includePayloads ? "?include=payloads" : "")
+    ),
 
   activityRollups: (days?: number) =>
     fetchJson<ActivityRollups>(`/activity/rollups${days ? `?days=${days}` : ""}`),

package/src/stores/activity-store.ts

@@ -273,6 +273,42 @@ export async function loadSessionActivityHistory(sessionId: string): Promise<voi
   }
 }
 
+/** 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.
+ */
+export async function loadSpanPayloads(spanId: string): Promise<void> {
+  const state = useActivityStore.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 (detail.detailPruned || !detail.spans) return;
+    useActivityStore.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);
+  }
+}
+
 /** The four indexes that make up the mirror, mutated together during merges. */
 interface MirrorMaps {
   spans: Record<string, Record<string, ActivitySpan>>;
@@ -371,6 +407,52 @@ export function eventsFor(state: ActivityState, spanId: string): ActivitySpanEve
   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];