@hienlh/ppm 0.23.9 → 0.23.11

package/src/web/hooks/use-agent-session-stream.ts

@@ -0,0 +1,134 @@
+/**
+ * Follow one Agent card's or teammate's work session live, from the transcript hub on
+ * `/ws/global`.
+ *
+ * Generalises the old per-teammate HTTP poll (`use-member-transcript-tail.ts`) to the hub
+ * protocol: a subscription is never queued while the socket is down — `sendIfOpen` drops it
+ * instead, because a queued subscribe would replay later with a cursor that is already
+ * stale by the time the flush happens. `onGlobalReady` (fired on every connect and every
+ * reconnect) is what actually (re)subscribes, using the cursor the last response handed
+ * back, so a reconnect resumes with no gap and no duplicate instead of going quiet.
+ */
+import { useEffect, useMemo, useState } from "react";
+import { onGlobalReady, sendIfOpen } from "@/lib/global-ws-channel";
+import { applyEnvelopeBatch, type StreamEntry } from "@/lib/agent-session-stream-merge";
+import type {
+  AgentTranscriptCursor,
+  AgentTranscriptErrorCode,
+  AgentTranscriptErrorMsg,
+  AgentTranscriptEventsMsg,
+  AgentTranscriptProviderId,
+  AgentTranscriptSourceKind,
+} from "../../shared/agent-transcript-protocol";
+import type { ChatEvent } from "../../types/chat";
+
+export interface UseAgentSessionStreamOptions {
+  projectName: string;
+  providerId: AgentTranscriptProviderId;
+  sessionId: string;
+  source: AgentTranscriptSourceKind;
+  /** Steps already held in chat memory — shown while the transcript stream is unavailable. */
+  fallbackEvents?: ChatEvent[];
+}
+
+export interface UseAgentSessionStream {
+  events: ChatEvent[];
+  /** True only once the server has answered with at least one readable file for this
+   *  source. False before the first response, and after one that found no transcript (old
+   *  session, never had one, or an error) — `events` falls back to `fallbackEvents` both
+   *  times, so a window shows what is already known rather than a blank list while the
+   *  first page is still in flight. */
+  available: boolean;
+  running: boolean;
+  loading: boolean;
+  error: AgentTranscriptErrorCode | null;
+}
+
+function newSubId(): string {
+  return `ats-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function useAgentSessionStream(opts: UseAgentSessionStreamOptions): UseAgentSessionStream {
+  const { projectName, providerId, sessionId, source, fallbackEvents } = opts;
+  const [entries, setEntries] = useState<StreamEntry[]>([]);
+  // False until the first response says otherwise, so a window opened with fallback events
+  // shows them immediately instead of a blank list while the first page is in flight.
+  const [available, setAvailable] = useState(false);
+  const [running, setRunning] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<AgentTranscriptErrorCode | null>(null);
+
+  // Any of these changing is a different subscription, not a resume of the same one —
+  // JSON-stringified so the effect only re-runs when the actual identity changes, not on
+  // every render a caller passes a fresh `source` object literal.
+  const sourceKey = JSON.stringify([projectName, providerId, sessionId, source]);
+
+  useEffect(() => {
+    const subId = newSubId();
+    let entriesBuf: StreamEntry[] = [];
+    let cursor: AgentTranscriptCursor | undefined;
+    setEntries([]);
+    setAvailable(false);
+    setRunning(false);
+    setLoading(true);
+    setError(null);
+
+    const subscribe = () => {
+      sendIfOpen(
+        JSON.stringify({
+          type: "agent-transcript:subscribe",
+          subId,
+          projectName,
+          providerId,
+          sessionId,
+          source,
+          ...(cursor ? { cursor } : {}),
+        }),
+      );
+    };
+
+    const onEvents = (e: Event) => {
+      const data = (e as CustomEvent<AgentTranscriptEventsMsg>).detail;
+      if (data.subId !== subId) return;
+      entriesBuf = applyEnvelopeBatch(entriesBuf, data);
+      cursor = data.cursor;
+      setEntries(entriesBuf);
+      setAvailable(data.available);
+      setRunning(data.running);
+      setLoading(false);
+      setError(null);
+    };
+
+    const onError = (e: Event) => {
+      const data = (e as CustomEvent<AgentTranscriptErrorMsg>).detail;
+      if (data.subId !== subId) return;
+      setAvailable(false);
+      setLoading(false);
+      setError(data.code);
+    };
+
+    window.addEventListener("agent-transcript:events", onEvents);
+    window.addEventListener("agent-transcript:error", onError);
+    const stopResubscribing = onGlobalReady(subscribe);
+    subscribe();
+
+    return () => {
+      window.removeEventListener("agent-transcript:events", onEvents);
+      window.removeEventListener("agent-transcript:error", onError);
+      stopResubscribing();
+      sendIfOpen(JSON.stringify({ type: "agent-transcript:unsubscribe", subId }));
+    };
+    // sourceKey captures every real dependency (projectName/providerId/sessionId/source).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sourceKey]);
+
+  const events = useMemo(() => entries.map((e) => e.ev), [entries]);
+
+  return {
+    events: available ? events : (fallbackEvents ?? []),
+    available,
+    running,
+    loading,
+    error,
+  };
+}

package/src/web/hooks/use-chat.ts

@@ -16,6 +16,13 @@ import type { ChatWsServerMessage, SessionPhase, BackgroundShell, VersionGroup }
 import { useBackgroundOutputStore } from "../stores/background-output-store";
 import { useSessionListStore } from "@/stores/session-list-store";
 import { projectRefForName } from "@/stores/session-list-sync-triggers";
+import { applyChildToParent, slimHistoryEvents } from "@/lib/agent-step-summary";
+
+/** Slim every Agent/Task card a provider stamped `transcriptAvailable` on, walking
+ *  in from the REST history response before it ever reaches React state. */
+function slimHistoryMessages(messages: ChatMessage[]): ChatMessage[] {
+  return messages.map((m) => (m.events ? { ...m, events: slimHistoryEvents(m.events) } : m));
+}
 
 interface ApprovalRequest {
   requestId: string;
@@ -316,12 +323,8 @@ export function useChat(
         const event = events[i]!;
         if (event.type !== "tool_use") continue;
         if ((event.tool === "Agent" || event.tool === "Task") && (event as any).toolUseId === parentToolUseId) {
-          const children = [...(event.children ?? [])];
-          const id = (childEvent as any).toolUseId as string | undefined;
-          const duplicate = id ? children.findIndex((c) => c.type === childEvent.type && (c as any).toolUseId === id) : -1;
-          if (duplicate === -1) children.push(childEvent);
-          else children[duplicate] = childEvent;
-          return [[...events.slice(0, i), { ...event, children }, ...events.slice(i + 1)], true];
+          const updated = applyChildToParent(event, childEvent);
+          return [[...events.slice(0, i), updated, ...events.slice(i + 1)], true];
         }
         if (event.children?.length) {
           const [children, found] = append(event.children);
@@ -360,16 +363,7 @@ export function useChat(
       }
       if (idx === -1) return prev;
       const msg = prev[idx]!;
-      const events = msg.events!.map((e) => {
-        if (!isParent(e) || e.type !== "tool_use") return e;
-        const children = [...(e.children ?? [])];
-        // Replays can redeliver id-bearing children — upsert instead of duplicating
-        const cid = (childEvent as any).toolUseId as string | undefined;
-        const dup = cid ? children.findIndex((c) => c.type === childEvent.type && (c as any).toolUseId === cid) : -1;
-        if (dup !== -1) children[dup] = childEvent;
-        else children.push(childEvent);
-        return { ...e, children };
-      });
+      const events = msg.events!.map((e) => (isParent(e) ? applyChildToParent(e, childEvent) : e));
       return [...prev.slice(0, idx), { ...msg, events }, ...prev.slice(idx + 1)];
     });
     return true;
@@ -1237,7 +1231,7 @@ export function useChat(
           // cached bundle from before the upgrade would otherwise render an empty
           // history with no error.
           const payload = Array.isArray(data) ? { messages: data, versionMap: {} } : data;
-          let history: ChatMessage[] = Array.isArray(payload?.messages) ? payload.messages : [];
+          let history: ChatMessage[] = slimHistoryMessages(Array.isArray(payload?.messages) ? payload.messages : []);
           if (payload?.versionMap) setVersionMap(payload.versionMap);
           // The server served this transcript from a different id than the one
           // asked for: the provider had renamed the session and this tab kept the
@@ -1529,7 +1523,7 @@ export function useChat(
         if (Array.isArray(payload?.messages) && payload.messages.length > 0) {
           historyReconciledRef.current++;
           if (syncRafRef.current) { clearTimeout(syncRafRef.current); syncRafRef.current = 0; }
-          setMessages(payload.messages);
+          setMessages(slimHistoryMessages(payload.messages));
           streamingContentRef.current = "";
           streamingEventsRef.current = [];
         }

package/src/web/hooks/use-global-events.ts

@@ -5,6 +5,14 @@ import { useNotificationStore } from "@/stores/notification-store";
 import { useStreamingStore } from "@/stores/streaming-store";
 import { syncRunningSessions } from "@/lib/sync-running-sessions";
 import { syncAllKnownProjects } from "@/stores/session-list-sync-triggers";
+import { notifyGlobalReady, sendIfOpen, setGlobalWsClient } from "@/lib/global-ws-channel";
+
+/** How often the client pings — well under the server's own idle timeout, so a live but
+ *  silent socket never gets reaped as dead. */
+const PING_INTERVAL_MS = 20_000;
+/** No message (including a pong) for this long means the socket is dead even though it
+ *  never fired close/error — force a fresh connect rather than waiting on the browser. */
+const IDLE_TIMEOUT_MS = 45_000;
 
 /**
  * App-wide event bus client (`/ws/global`).
@@ -30,8 +38,18 @@ import { syncAllKnownProjects } from "@/stores/session-list-sync-triggers";
  *   `design:comments_changed`). A design's `.design/` folder is not watched, so these
  *   are the only signal that its snapshots or comments changed.
  *
+ * - `agent-transcript:events` / `agent-transcript:error` / `agent-activity` → re-dispatched
+ *   as window events for `useAgentSessionStream` and the running-agents bar. Several of
+ *   those hooks can be subscribed at once (one per open session window), each filtering the
+ *   broadcast down to its own `subId` — same pattern as the other re-dispatches here.
+ *
  * Also tells the server which project to watch, so file watching follows the
  * active project instead of depending on a chat socket existing.
+ *
+ * Registers its `WsClient` with `global-ws-channel` and pings every 20s: the hub protocol's
+ * subscriptions (`useAgentSessionStream`) must never queue a send while this socket is
+ * down, so they need to know the instant it actually goes idle rather than only on the next
+ * browser-level close/error.
  */
 export function useGlobalEvents(enabled: boolean, projectName?: string): void {
   const clientRef = useRef<WsClient | null>(null);
@@ -44,8 +62,11 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
     if (!enabled) return;
 
     const token = getAuthToken();
-    const client = new WsClient(`/ws/global${token ? `?token=${encodeURIComponent(token)}` : ""}`);
+    const client = new WsClient(`/ws/global${token ? `?token=${encodeURIComponent(token)}` : ""}`, {
+      idleTimeoutMs: IDLE_TIMEOUT_MS,
+    });
     clientRef.current = client;
+    setGlobalWsClient(client);
 
     const unsubscribe = client.onMessage((event) => {
       let data: { type?: string; [k: string]: unknown };
@@ -68,6 +89,7 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
         // device renamed, pinned or deleted a session) — re-sync every
         // project this browser already knows about.
         syncAllKnownProjects();
+        notifyGlobalReady();
         return;
       }
 
@@ -103,17 +125,28 @@ export function useGlobalEvents(enabled: boolean, projectName?: string): void {
         return;
       }
 
-      if (type.startsWith("jira:") || type.startsWith("tunnel:") || type.startsWith("design:")) {
+      if (
+        type.startsWith("jira:")
+        || type.startsWith("tunnel:")
+        || type.startsWith("design:")
+        || type.startsWith("agent-transcript:")
+        || type === "agent-activity"
+      ) {
         window.dispatchEvent(new CustomEvent(type, { detail: data }));
       }
     });
 
     client.connect();
+    const pingTimer = setInterval(() => {
+      sendIfOpen(JSON.stringify({ type: "ping" }));
+    }, PING_INTERVAL_MS);
 
     return () => {
+      clearInterval(pingTimer);
       unsubscribe();
       client.disconnect();
       clientRef.current = null;
+      setGlobalWsClient(null);
     };
   }, [enabled]);
 

package/src/web/lib/agent-session-stream-merge.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure event-buffer reducer for the agent session stream hook.
+ *
+ * Split out from the hook itself so the ordering/de-dupe/replace/reset/cap rules are
+ * testable under `bun:test` with no WebSocket, no React and no store to mount. Two pushes
+ * for the same subscription are not guaranteed to arrive in `ts` order (a live tick can
+ * land while a catch-up backlog is still draining), and a Codex `replace` updates a step
+ * already shown in place rather than appending a new one.
+ */
+import type { AgentTranscriptEventsMsg } from "../../shared/agent-transcript-protocol";
+import type { ChatEvent } from "../../types/chat";
+
+/** One accumulated step, kept alongside its de-dupe key and timestamp for re-ordering. */
+export interface StreamEntry {
+  k: string;
+  ts: number;
+  ev: ChatEvent;
+}
+
+/** Mirrors the hub's own per-subscription cap so a long session stays renderable. */
+export const MAX_STREAM_ENTRIES = 2000;
+
+/**
+ * Apply one `agent-transcript:events` page to the entries accumulated so far.
+ *
+ * `reset` discards everything first — a truncated/rotated file or a Codex compaction means
+ * the server is telling us history itself changed, not just that more of it arrived.
+ * Otherwise: a `k` already held is either a `replace` (update in place) or a plain duplicate
+ * from an overlapping catch-up/live-tick window (skipped); a new `k` is inserted at the
+ * position its `ts` sorts into rather than appended blindly.
+ */
+export function applyEnvelopeBatch(
+  current: StreamEntry[],
+  batch: AgentTranscriptEventsMsg,
+): StreamEntry[] {
+  const next = batch.reset ? [] : current.slice();
+  for (const { ev, ts, k, replace } of batch.events) {
+    const existingIndex = next.findIndex((e) => e.k === k);
+    if (existingIndex !== -1) {
+      if (replace) next[existingIndex] = { k, ts, ev };
+      continue;
+    }
+    let insertAt = next.length;
+    while (insertAt > 0 && next[insertAt - 1]!.ts > ts) insertAt--;
+    next.splice(insertAt, 0, { k, ts, ev });
+  }
+  return next.length > MAX_STREAM_ENTRIES ? next.slice(next.length - MAX_STREAM_ENTRIES) : next;
+}

package/src/web/lib/agent-step-summary.ts

@@ -0,0 +1,331 @@
+/**
+ * Pure helpers behind the Agent/Task card's one-line summary and the chat's
+ * slimmed in-memory record of a subagent's work — no React, so this is directly
+ * unit-testable and reusable from `use-chat.ts`'s live routing.
+ *
+ * A "step" is a distinct child `tool_use` id. A card's own direct children count
+ * one step each — including a nested Agent/Task call, which counts once for
+ * spawning it — and that nested call's *own* subtree is then summed in on top
+ * (`recursiveStepCount`), so the number shown on a one-line card equals the
+ * live session window's flat count of every `tool_use` in the whole on-disk
+ * transcript, not just this card's immediate children. `stepIds` is a Set-like
+ * array of ids so a WS replay re-delivering the same `tool_use` never
+ * double-counts — the one thing today's `children.length` badge could not
+ * guarantee.
+ *
+ * "Kept children" are what stays in memory once the full list is gone: nested
+ * Agent/Task stubs (recursively slimmed the same way, so a further-nested card
+ * still routes and lists correctly) and file-mutation tool_use/tool_result
+ * pairs (the change tray reads these). Everything else that would otherwise be
+ * silently dropped goes into a bounded ring buffer instead — the fallback shown
+ * when no on-disk transcript exists to stream from.
+ */
+import type { ChatEvent } from "../../types/chat";
+import { basename } from "./utils";
+import { FILE_MUTATION_TOOLS } from "./aggregate-turn-file-changes";
+
+/** Live cards keep at most this many "other" (not kept) child events. */
+export const MAX_RECENT_CHILDREN = 200;
+
+/** Ring buffer also evicts oldest-first once its serialized size passes this — a handful of
+ *  multi-MB tool outputs would otherwise fit comfortably under the 200-entry count cap while
+ *  still holding many megabytes per live card. */
+export const MAX_RECENT_BYTES = 256 * 1024;
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+/** "1 step" / "N steps" — every place a card shows its step count uses this instead of
+ *  hardcoding the plural, which read as "1 steps" for a single-step agent. */
+export function formatStepCount(count: number): string {
+  return `${count} step${count === 1 ? "" : "s"}`;
+}
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? value.slice(0, max) + "…" : value;
+}
+
+/** Plain-text one-line description of a `tool_use` step — the same wording as
+ *  the JSX `ToolSummary` in `tool-cards.tsx`, minus the markup, so it fits the
+ *  card's "current step" line and is usable from a DOM-free test. */
+export function describeStep(ev: ChatEvent): string {
+  if (ev.type !== "tool_use") return "";
+  const tool = ev.tool;
+  const input = ev.input && typeof ev.input === "object" ? (ev.input as Record<string, unknown>) : {};
+  switch (tool) {
+    case "Read":
+    case "Write":
+    case "Edit":
+    case "MultiEdit":
+    case "NotebookEdit": {
+      const path = str(input.notebook_path || input.file_path);
+      return path ? `${tool} ${basename(path)}` : tool;
+    }
+    case "Bash":
+    case "PowerShell": {
+      const preview = input.description ? str(input.description) : str(input.command);
+      return truncate(preview, 60) || tool;
+    }
+    case "Glob":
+      return `Glob ${str(input.pattern)}`;
+    case "Grep":
+      return `Grep ${truncate(str(input.pattern), 40)}`;
+    case "WebSearch":
+      return `Search ${truncate(str(input.query), 50)}`;
+    case "WebFetch":
+      return `Fetch ${truncate(str(input.url), 50)}`;
+    case "ToolSearch":
+      return `Search ${truncate(str(input.query), 50)}`;
+    case "Agent":
+    case "Task": {
+      const name = typeof input.name === "string" && input.name.trim() ? input.name.trim() : null;
+      const task = truncate(str(input.description || input.prompt), 44);
+      if (name) return task ? `${name} · ${task}` : name;
+      return task || tool;
+    }
+    case "SendMessage":
+      return `Message ${truncate(str(input.to), 30)}`.trim();
+    case "TodoWrite":
+      return "Todo update";
+    case "AskUserQuestion":
+      return "Question";
+    case "ScheduleWakeup":
+      return "Scheduled wakeup";
+    case "TaskCreate":
+      return truncate(str(input.subject), 60) || tool;
+    case "TaskUpdate":
+      return `Task #${str(input.taskId)} → ${str(input.status)}`;
+    case "TaskStop":
+      return `Task #${str(input.taskId)} stopped`;
+    case "ImageGen":
+      return "Image generation";
+    default:
+      return tool;
+  }
+}
+
+/** A `tool_use` child that survives slimming on its own account. */
+function isKeptToolUse(tool: string): boolean {
+  return tool === "Agent" || tool === "Task" || FILE_MUTATION_TOOLS.has(tool);
+}
+
+export interface SlimAgentChildren {
+  /** Distinct child `tool_use` ids counted as steps, in arrival order. */
+  stepIds: string[];
+  /** Plain-text description of the most recent step, if any arrived. */
+  lastStep?: string;
+  /** Nested Agent/Task stubs (recursively slimmed) + file-mutation tool_use/result pairs. */
+  kept: ChatEvent[];
+}
+
+/**
+ * Recompute a subagent's `{stepIds, lastStep, kept}` from its full child list —
+ * used for a from-scratch reduction (history load for a card whose provider
+ * stamped `transcriptAvailable`, or any caller that only has the raw array and
+ * no running per-card state to update incrementally).
+ */
+export function slimAgentChildren(children: ChatEvent[] | undefined): SlimAgentChildren {
+  const stepIds: string[] = [];
+  const kept: ChatEvent[] = [];
+  const keptToolUseIds = new Set<string>();
+  let lastStep: string | undefined;
+
+  (children ?? []).forEach((ev, i) => {
+    if (ev.type === "tool_use") {
+      stepIds.push(ev.toolUseId ?? `idx:${i}`);
+      const desc = describeStep(ev);
+      if (desc) lastStep = desc;
+      if (isKeptToolUse(ev.tool)) {
+        const isAgent = ev.tool === "Agent" || ev.tool === "Task";
+        if (isAgent) {
+          const nested = slimAgentChildren(ev.children);
+          kept.push({
+            ...ev,
+            children: nested.kept,
+            stepIds: nested.stepIds,
+            stepCount: nested.stepIds.length,
+            lastStep: nested.lastStep,
+          });
+        } else {
+          kept.push(ev);
+        }
+        if (ev.toolUseId) keptToolUseIds.add(ev.toolUseId);
+      }
+    } else if (ev.type === "tool_result") {
+      if (ev.toolUseId && keptToolUseIds.has(ev.toolUseId)) kept.push(ev);
+    }
+    // text/thinking/other event kinds are never kept in the slimmed set.
+  });
+
+  return { stepIds, lastStep, kept };
+}
+
+/**
+ * Recursive count of every `tool_use` across a card's whole subtree: this card's own direct
+ * steps (a nested Agent/Task counted once, for spawning it) plus, for each such nested card,
+ * everything further inside it. A nested Agent/Task stub is always kept in `.children` (never
+ * the ring buffer — see `isKeptToolUse`), so its own `stepCount`/`stepIds` is always the latest
+ * value live-routed into it, and summing over `.children` here never revisits the same id
+ * twice: the nested card's own direct count already excludes its own id.
+ */
+export function recursiveStepCount(tool: Extract<ChatEvent, { type: "tool_use" }>): number {
+  const direct = tool.stepCount ?? tool.stepIds?.length ?? slimAgentChildren(tool.children).stepIds.length;
+  let total = direct;
+  for (const child of tool.children ?? []) {
+    if (child.type === "tool_use" && (child.tool === "Agent" || child.tool === "Task")) {
+      total += recursiveStepCount(child);
+    }
+  }
+  return total;
+}
+
+/** `{stepCount, lastStep}` for the one-line card: `stepCount` is always the recursive total
+ *  (see `recursiveStepCount`) so it equals the session window's flat count; `lastStep` prefers
+ *  the field a live card or a slimmed history card already carries, and only falls back to
+ *  recomputing from `children` when unset (e.g. a card rendered straight from a server search
+ *  result, or an unstamped history card that kept its full list). */
+export function agentStepInfo(tool: Extract<ChatEvent, { type: "tool_use" }>): { stepCount: number; lastStep?: string } {
+  const stepCount = recursiveStepCount(tool);
+  if (tool.stepCount != null) return { stepCount, lastStep: tool.lastStep };
+  const { lastStep } = slimAgentChildren(tool.children);
+  return { stepCount, lastStep };
+}
+
+function approxByteSize(ev: ChatEvent): number {
+  try { return JSON.stringify(ev).length; } catch { return 0; }
+}
+
+/** Drop oldest entries (keeping at least one) while the buffer's approximate serialized
+ *  size exceeds `MAX_RECENT_BYTES` — a count cap alone lets a handful of huge tool outputs
+ *  through untouched. */
+function capByBytes(buffer: ChatEvent[]): ChatEvent[] {
+  let total = buffer.reduce((sum, e) => sum + approxByteSize(e), 0);
+  let start = 0;
+  while (total > MAX_RECENT_BYTES && start < buffer.length - 1) {
+    total -= approxByteSize(buffer[start]!);
+    start++;
+  }
+  return start > 0 ? buffer.slice(start) : buffer;
+}
+
+/**
+ * Upsert `ev` into a bounded ring buffer: a WS replay re-delivering the same
+ * `toolUseId` replaces the existing entry in place instead of growing the
+ * buffer, and anything past `MAX_RECENT_CHILDREN` (count) or `MAX_RECENT_BYTES`
+ * (approximate serialized size) is dropped from the front.
+ *
+ * `seq` stamps the entry's `arrivalSeq` for `mergeFallbackEvents` to later
+ * interleave this buffer back together with the kept `children` list in the
+ * order events actually arrived — omitted by direct/standalone callers that
+ * have no parent-level counter to hand it a value.
+ */
+export function pushRecentChild(buffer: ChatEvent[], ev: ChatEvent, seq?: number): ChatEvent[] {
+  const id = (ev as { toolUseId?: string }).toolUseId;
+  if (id) {
+    const idx = buffer.findIndex((e) => e.type === ev.type && (e as { toolUseId?: string }).toolUseId === id);
+    if (idx !== -1) {
+      const preserved = (buffer[idx] as { arrivalSeq?: number }).arrivalSeq;
+      const next = [...buffer];
+      next[idx] = (seq != null ? { ...ev, arrivalSeq: preserved } : ev) as ChatEvent;
+      return next;
+    }
+  }
+  const stamped = seq != null ? ({ ...ev, arrivalSeq: seq } as ChatEvent) : ev;
+  const next = [...buffer, stamped];
+  const capped = next.length > MAX_RECENT_CHILDREN ? next.slice(next.length - MAX_RECENT_CHILDREN) : next;
+  return capByBytes(capped);
+}
+
+/**
+ * Merge kept `children` with the bounded "other" ring buffer back into the order events
+ * actually arrived in: splitting live arrivals into a kept list and a ring buffer by
+ * kind (nested-agent/file-mutation vs everything else) loses the interleaving between them —
+ * a plain concatenation showed every edit before the reads that actually preceded it. Each
+ * entry's `arrivalSeq` (stamped by `applyChildToParent`/`pushRecentChild`) says where it
+ * really sorts; an entry with none (never live-routed, e.g. a history-loaded card, which
+ * never populates both lists at once) keeps its position within its own list.
+ */
+export function mergeFallbackEvents(kept: ChatEvent[], recent: ChatEvent[]): ChatEvent[] {
+  const tag = (list: ChatEvent[]) =>
+    list.map((ev, i) => ({ ev, seq: (ev as { arrivalSeq?: number }).arrivalSeq ?? i }));
+  return [...tag(kept), ...tag(recent)]
+    .sort((a, b) => a.seq - b.seq)
+    .map((e) => e.ev);
+}
+
+/**
+ * Apply one newly-arrived child event to its Agent/Task parent, updating
+ * `stepIds`/`stepCount`/`lastStep` and routing the child into either the kept
+ * `children` (nested stub or file mutation, upserted by id the same way the
+ * pre-slimming code deduped a replay) or the `recentChildren` ring buffer.
+ *
+ * Every routed child is stamped with the parent's monotonic `childSeq` (preserved rather
+ * than reassigned when the upsert is an update-in-place, e.g. a tool_result arriving for an
+ * already-kept tool_use) — the arrival order `mergeFallbackEvents` needs to interleave
+ * `children` and `recentChildren` back together correctly.
+ */
+export function applyChildToParent(parent: ChatEvent, childEvent: ChatEvent): ChatEvent {
+  if (parent.type !== "tool_use") return parent;
+
+  let stepIds = parent.stepIds;
+  let lastStep = parent.lastStep;
+  if (childEvent.type === "tool_use") {
+    const id = childEvent.toolUseId;
+    if (!id || !stepIds?.includes(id)) stepIds = [...(stepIds ?? []), id ?? `idx:${stepIds?.length ?? 0}`];
+    const desc = describeStep(childEvent);
+    if (desc) lastStep = desc;
+  }
+
+  const seq = parent.childSeq ?? 0;
+
+  const upsertKept = (list: ChatEvent[]): ChatEvent[] => {
+    const id = (childEvent as { toolUseId?: string }).toolUseId;
+    const idx = id ? list.findIndex((c) => c.type === childEvent.type && (c as { toolUseId?: string }).toolUseId === id) : -1;
+    if (idx !== -1) {
+      const preserved = (list[idx] as { arrivalSeq?: number }).arrivalSeq;
+      const next = [...list];
+      next[idx] = { ...childEvent, arrivalSeq: preserved } as ChatEvent;
+      return next;
+    }
+    return [...list, { ...childEvent, arrivalSeq: seq } as ChatEvent];
+  };
+
+  const children = parent.children ?? [];
+  const recentChildren = parent.recentChildren ?? [];
+  const isKeptToolUseChild = childEvent.type === "tool_use" && isKeptToolUse(childEvent.tool);
+  const matchesKeptToolUse = (id: string | undefined) =>
+    !!id && children.some((c) => c.type === "tool_use" && c.toolUseId === id);
+
+  let nextChildren = children;
+  let nextRecent = recentChildren;
+  if (isKeptToolUseChild) {
+    nextChildren = upsertKept(children);
+  } else if (childEvent.type === "tool_result" && matchesKeptToolUse(childEvent.toolUseId)) {
+    nextChildren = upsertKept(children);
+  } else {
+    nextRecent = pushRecentChild(recentChildren, childEvent, seq);
+  }
+
+  return {
+    ...parent,
+    children: nextChildren,
+    recentChildren: nextRecent,
+    stepIds,
+    stepCount: stepIds?.length,
+    lastStep,
+    childSeq: seq + 1,
+  };
+}
+
+/** Walk a history message tree, slimming every Agent/Task card a provider
+ *  stamped `transcriptAvailable` on; an unstamped card keeps its full children
+ *  (there is no disk source to fall back to, so it stays the fallback itself). */
+export function slimHistoryEvents(events: ChatEvent[] | undefined): ChatEvent[] | undefined {
+  if (!events) return events;
+  return events.map((ev) => {
+    if (ev.type !== "tool_use" || (ev.tool !== "Agent" && ev.tool !== "Task") || !ev.transcriptAvailable) return ev;
+    const { stepIds, lastStep, kept } = slimAgentChildren(ev.children);
+    return { ...ev, children: kept, stepIds, stepCount: stepIds.length, lastStep };
+  });
+}