zidane-ui 9.1.1 → 9.1.4

package/src/chat/headless/streams/store.ts

@@ -1,1107 +0,0 @@
-/**
- * The per-session stream store: every session's live transcript window and
- * run state, reduced from zidane's host signals, with per-session listeners
- * so a tick on one session never wakes the readers of another.
- *
- * State shape and merge semantics match `zidane/chat`'s `useStreamBuffer`:
- * same-owner same-kind markdown / thinking deltas coalesce onto the trailing
- * block; tool / tool-result / error / spawn-* events append verbatim;
- * `turn:end` and `run:end` finalize the trailing streaming markdown so the
- * renderer stops absorbing tokens. React-free: the desktop app binds it with
- * `useSyncExternalStore`, a {@link ChatHost} reads it through
- * `SessionStreams.transcript`.
- */
-import type { Owner, StreamEvent, SystemMdFile } from 'zidane/chat';
-import {
-  discardThinking,
-  finalizeStreamingMarkdownForOwner,
-  type MarkdownDeltaOptions,
-  type PromptSegmentRef,
-  reconcileEvents,
-  retagUserPromptEventsFromRefs,
-} from 'zidane/chat/pure';
-
-import type { ChatAttachment, ChatEvent } from '../host';
-import { inheritRowIdentity } from '../transcript/collapse';
-import { applyLiveEvent, closeThinkingSegment, finishLive } from './live-events';
-import { mergeLiveTail } from './merge';
-import type { DrainPlan } from './pacer';
-import { mergePromptPreviews, missingPreviewData } from './prompt-previews';
-import { defaultFrameScheduler, type FrameScheduler } from './scheduler';
-import type {
-  OtherStreamSignal,
-  SessionFallbackModel,
-  SessionPageState,
-  SessionRetryState,
-  SessionStreamPage,
-  SessionStreamSignal,
-} from './types';
-
-const PARENT_OWNER: Owner = 'parent';
-
-/**
- * Module-level stable empty array — returned by `getEventsSnapshot` when
- * the session has no entry yet. Keeping this reference identical across
- * calls avoids breaking downstream `useMemo([events])` deps when a
- * consumer mounts before its session hydrates.
- */
-const EMPTY_EVENTS: readonly ChatEvent[] = Object.freeze([]) as readonly ChatEvent[];
-
-/** Page-state snapshot for a session with no hydrated page — stable identity. */
-const NO_PAGE: SessionPageState = Object.freeze({ firstSeq: 0, hasMore: false, loadingEarlier: false });
-
-/**
- * Markdown merge options by default. No 64 KB segmenting: a reloaded
- * transcript shows each message whole (the renderer chunks long text
- * itself, see `markdown-chunks.ts`), so a split live message would carry
- * per-segment message actions that vanish on reload.
- */
-const WHOLE_MESSAGES: MarkdownDeltaOptions = { segmentChars: Number.POSITIVE_INFINITY };
-
-/** Notifications held for the next frame are delivered after this long when frames do not run (a hidden window). */
-const NOTIFY_FALLBACK_MS = 50;
-
-/** Options for {@link SessionStreamStore}. */
-export interface SessionStreamStoreOptions {
-  /** Frames and timers for batched notifications. Default: {@link defaultFrameScheduler}. */
-  scheduler?: FrameScheduler;
-  /** How streamed markdown merges. Default: one event per message (`segmentChars: Infinity`). */
-  markdown?: MarkdownDeltaOptions;
-  /** Deliver transcript-event notifications once per frame (`true`, the default) or at once (`false`). The state is current at once either way. */
-  batch?: boolean;
-}
-
-/** One write to a session's window, see {@link SessionStreamStore.write}. */
-export interface SessionStreamWrite {
-  /** Replaces the events. */
-  events?: readonly ChatEvent[];
-  /** Sets the run flag. */
-  running?: boolean;
-  /** Sets the page state (and so marks the window hydrated); `null` drops it. */
-  page?: SessionPageState | null;
-}
-
-/**
- * External store backing all per-session reads. Mutates the underlying
- * Maps in place and notifies only the per-`sessionId` listeners that
- * actually subscribed to the changed session — that's what isolates
- * sibling sessions from each other's stream churn. Every write path
- * replaces the session's events array, so identity says whether anything
- * landed in between (the run-end compaction and scrollback guards rely on
- * it).
- *
- * The reducer alone: {@link createSessionStreams} adds smooth-stream pacing,
- * lazy scrollback and run-end compaction around it.
- *
- * @typeParam K - The session key type (the desktop app's branded `SessionKey`). Default: `string`.
- */
-export class SessionStreamStore<K extends string = string> {
-  private _events = new Map<K, ChatEvent[]>();
-  private _running = new Map<K, boolean>();
-  private readonly _scheduler: FrameScheduler;
-  private readonly _markdown: MarkdownDeltaOptions;
-  private readonly _batch: boolean;
-  /** Bumped by every run-state change (`run:start`, `run:end`, `dropAll`): a snapshot fetched before a bump is stale. */
-  runStateVersion = 0;
-
-  /**
-   * @param options - The scheduler for batched notifications, the markdown merge rule and whether to batch.
-   */
-  constructor(options: SessionStreamStoreOptions = {}) {
-    this._scheduler = options.scheduler ?? defaultFrameScheduler;
-    this._markdown = options.markdown ?? WHOLE_MESSAGES;
-    this._batch = options.batch ?? true;
-  }
-  /**
-   * Per-session run-sticky fallback target — set by the `model:fallback`
-   * signal when the agent's stream failed terminally on the picked model
-   * and the run advanced down its fallback chain. Cleared on `run:start`
-   * (every run starts from the primary again). Read by the model pill so
-   * the user always sees the model ACTUALLY serving the run.
-   */
-  private _fallback = new Map<K, SessionFallbackModel>();
-  /**
-   * Per-session `SYSTEM.md` override the HOST composed the prompt with, or
-   * `null` when none applied. Pushed by the `system-md` signal at agent-build
-   * time.
-   *
-   * Not derivable in the renderer: the override is resolved where the prompt
-   * is composed, against a cwd and a `userInstructionsScope` this window does
-   * not own (under a daemon it is another process entirely). Surfaced because
-   * an override REPLACES the built-in doctrine — including the safety and git
-   * guidance — and does so without erroring.
-   */
-  private _systemMd = new Map<K, SystemMdFile | null>();
-  /**
-   * Per-session provider-retry state. Cleared on `run:end` rather than
-   * `run:start`: a terminal stream failure never streams again, so run end is
-   * the only guaranteed clear — the same backstop the TUI uses.
-   */
-  private _retry = new Map<K, SessionRetryState>();
-  /**
-   * Monotonically increasing per-session run-start counter — bumped on
-   * every `run:start` this window observes (including runs started by
-   * OTHER windows, which fan out through the same signal path). Read
-   * non-reactively by the re-convergence guard so a disk snapshot
-   * kicked off before a run started is dropped instead of clobbering
-   * the just-seeded stream.
-   */
-  private _runSeq = new Map<K, number>();
-  private _pages = new Map<K, SessionPageState>();
-  /**
-   * Texts of user prompts THIS window appended optimistically that still
-   * await their host echo. The host stamps `echo: true` on the broadcast
-   * of the sender's own prompt (send / steer paths) for EVERY peer — it
-   * cannot know which window originated the send — so the dedupe lives
-   * here: one pending entry consumes one echo (keeping the local copy,
-   * which carries refs + attachments the canonical event doesn't).
-   * Echo-tagged prompts with NO pending match are genuine remote sends
-   * (another window, a daemon-drained queued prompt) and must render.
-   * Leftovers (failed sends) are cleared at `run:end`.
-   */
-  private _pendingEcho = new Map<K, string[]>();
-  /**
-   * Image previews of prompts THIS window queued, FIFO per session, until
-   * the prompt shows up in the transcript (see `prompt-previews.ts`).
-   */
-  private _promptPreviews = new Map<K, Array<{ text: string; attachments: ChatAttachment[] }>>();
-  private _listenersBySession = new Map<K, Set<() => void>>();
-  private _listenersForHas = new Set<() => void>();
-
-  /**
-   * A session's events: the stored array itself (stable identity until a write), or a shared empty array.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getEventsSnapshot(sessionId: K | null): readonly ChatEvent[] {
-    if (!sessionId) {
-      return EMPTY_EVENTS;
-    }
-
-    return this._events.get(sessionId) ?? EMPTY_EVENTS;
-  }
-
-  /**
-   * Whether a run is in flight for the session.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getRunningSnapshot(sessionId: K | null): boolean {
-    if (!sessionId) {
-      return false;
-    }
-
-    return this._running.get(sessionId) ?? false;
-  }
-
-  /**
-   * Seed "running" from the store row for a run this window never saw
-   * start — a session driven by the daemon or another client, opened
-   * mid-run. Only ever sets TRUE: clearing belongs to `run:end` (or a
-   * runtime drop), since a list fetched just before a local run:start
-   * would otherwise flip a genuinely live session back to idle.
-   *
-   * @param sessionId - The session.
-   */
-  markRunning(sessionId: K): void {
-    if (this._running.get(sessionId)) {
-      return;
-    }
-
-    if (!this._events.has(sessionId)) {
-      this._events.set(sessionId, []);
-      this._notifyHas();
-    }
-
-    this._running.set(sessionId, true);
-    this._notifySession(sessionId);
-  }
-
-  /**
-   * How many runs this client saw start for the session (0 for none). Read non-reactively: a snapshot fetched before a run started is stale.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getRunSeqSnapshot(sessionId: K | null): number {
-    if (!sessionId) {
-      return 0;
-    }
-
-    return this._runSeq.get(sessionId) ?? 0;
-  }
-
-  /**
-   * Stable-reference snapshot (the stored object itself) — safe for
-   * `useSyncExternalStore`, which compares snapshots by identity.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getFallbackSnapshot(sessionId: K | null): SessionFallbackModel | null {
-    if (!sessionId) {
-      return null;
-    }
-
-    return this._fallback.get(sessionId) ?? null;
-  }
-
-  /**
-   * Seed the override from the main-process PULL (`sessions.systemMd`).
-   *
-   * The `system-md` signal only fires when an agent is BUILT, and agents are
-   * cached — so opening the app onto a warm session, or switching back to one,
-   * delivers no signal at all. Without this seed the badge is silent in the
-   * most common flow rather than an edge case, which is the wrong direction
-   * for a warning that the built-in doctrine has been replaced.
-   *
-   * Skipped while a live signal already holds a value for the session: the
-   * push is authoritative and may have landed while this fetch was in flight.
-   *
-   * @param sessionId - The session.
-   * @param file - The override, or `null` for none.
-   */
-  seedSystemMd(sessionId: K, file: SystemMdFile | null): void {
-    if (this._systemMd.has(sessionId)) {
-      return;
-    }
-
-    this._systemMd.set(sessionId, file);
-    this._notifySession(sessionId);
-  }
-
-  /**
-   * Stable-reference snapshot of the active `SYSTEM.md` override, for
-   * `useSyncExternalStore` (compared by identity, and the stored object is the
-   * one the signal delivered).
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getSystemMdSnapshot(sessionId: K | null): SystemMdFile | null {
-    if (!sessionId) {
-      return null;
-    }
-
-    return this._systemMd.get(sessionId) ?? null;
-  }
-
-  /**
-   * Stable-reference snapshot of in-flight provider-retry state.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getRetrySnapshot(sessionId: K | null): SessionRetryState | null {
-    if (!sessionId) {
-      return null;
-    }
-
-    return this._retry.get(sessionId) ?? null;
-  }
-
-  /**
-   * Whether the store holds any record for the session (live-only windows included; see `isHydrated`).
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  hasEvents(sessionId: K | null): boolean {
-    if (!sessionId) {
-      return false;
-    }
-
-    return this._events.has(sessionId);
-  }
-
-  /**
-   * Whether the session's window was hydrated from DISK (`setEventsPage`),
-   * as opposed to merely having a record. `markRunning` and every live
-   * signal seed `_events` for a session this window never loaded — a run
-   * driven by the TUI or another window — and `hasEvents` alone read those
-   * live-only windows as hydrated, so activation skipped `loadEvents` and
-   * the transcript showed nothing but the deltas that had arrived so far,
-   * with no page state to scroll back from.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  isHydrated(sessionId: K | null): boolean {
-    if (!sessionId) {
-      return false;
-    }
-
-    return this._pages.has(sessionId);
-  }
-
-  /**
-   * The session's scrollback bookkeeping (a shared empty state when it was never hydrated). Stable identity until a page write.
-   *
-   * @param sessionId - The session, or `null` for none.
-   */
-  getPageSnapshot(sessionId: K | null): SessionPageState {
-    if (!sessionId) {
-      return NO_PAGE;
-    }
-
-    return this._pages.get(sessionId) ?? NO_PAGE;
-  }
-
-  /**
-   * Hydrate one replay page as the session's full window — the
-   * `loadEvents` (tail page) path. One notify covers both the events
-   * swap and the page-state swap.
-   *
-   * @param sessionId - The session.
-   * @param page - The persisted page.
-   */
-  setEventsPage(sessionId: K, page: SessionStreamPage): void {
-    const had = this._events.has(sessionId);
-    const wasHydrated = this._pages.has(sessionId);
-    const prior = this._events.get(sessionId) ?? [];
-    /*
-     * Reuse the OBJECTS of events that are unchanged. Row identity in the
-     * timeline is keyed by event object (`rowIdFor`), so a page that merely
-     * re-states the same tool calls with fresh objects would remount every
-     * row: expanded tool results snap shut, `zg-row-enter` replays, the
-     * viewport jumps. Re-convergence (`sessions:changed` while another
-     * surface drives the session, run-end compaction, reconnect backfill)
-     * hits this path on every persisted turn.
-     *
-     * A window that was never hydrated holds ONLY live deltas (see
-     * `isHydrated`); the disk page goes in front of them and the not-yet-
-     * persisted suffix survives, instead of the page clobbering the stream.
-     */
-    const next = wasHydrated ? reconcileEvents(prior, page.events) : mergeLiveTail(prior, page.events);
-    // A prompt on show whose persisted copy replaces it (a new chat's first read) stays the same bubble.
-    inheritRowIdentity(prior, next);
-    this._events.set(sessionId, next);
-    this._pages.set(sessionId, { firstSeq: page.firstSeq, hasMore: page.hasMore, loadingEarlier: false });
-    this._notifySession(sessionId);
-
-    if (!had || !wasHydrated) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Splice an OLDER page in front of the hydrated window (lazy scrollback).
-   *
-   * @param sessionId - The session.
-   * @param page - The persisted page.
-   */
-  prependEventsPage(sessionId: K, page: SessionStreamPage): void {
-    const existing = this._events.get(sessionId) ?? [];
-    const wasHydrated = this._pages.has(sessionId);
-    this._events.set(sessionId, [...page.events, ...existing]);
-    this._pages.set(sessionId, { firstSeq: page.firstSeq, hasMore: page.hasMore, loadingEarlier: false });
-    this._notifySession(sessionId);
-
-    if (!wasHydrated) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Marks a fetch of the previous page in flight, or done.
-   *
-   * @param sessionId - The session.
-   * @param loading - Whether a fetch is in flight.
-   */
-  setLoadingEarlier(sessionId: K, loading: boolean): void {
-    const prior = this._pages.get(sessionId) ?? NO_PAGE;
-
-    if (prior.loadingEarlier === loading) {
-      return;
-    }
-
-    this._pages.set(sessionId, { ...prior, loadingEarlier: loading });
-    this._notifySession(sessionId);
-  }
-
-  /**
-   * Registers a listener for one session's changes. Returns the function that removes it.
-   *
-   * @param sessionId - The session, or `null` for none.
-   * @param listener - Called after the state changes.
-   */
-  subscribeSession(sessionId: K | null, listener: () => void): () => void {
-    /*
-     * `null` sessions need a still-callable subscription (returns a noop
-     * unsubscriber). `useSyncExternalStore` calls `subscribe` once on
-     * mount + on every snapshot identity change — we honor the signature
-     * even for "no session" callers so the empty-state Center doesn't
-     * crash.
-     */
-    if (!sessionId) {
-      return () => undefined;
-    }
-
-    let set = this._listenersBySession.get(sessionId);
-
-    if (!set) {
-      set = new Set();
-      this._listenersBySession.set(sessionId, set);
-    }
-
-    set.add(listener);
-
-    return () => {
-      const live = this._listenersBySession.get(sessionId);
-
-      if (!live) {
-        return;
-      }
-
-      live.delete(listener);
-
-      if (live.size === 0) {
-        this._listenersBySession.delete(sessionId);
-      }
-    };
-  }
-
-  /**
-   * Subscribe to "the set of known sessions changed" — used by
-   * `useHasEvents` so we only re-render the consumer when its target
-   * session flips between hydrated / not.
-   *
-   * @param listener - Called after the state changes.
-   */
-  subscribeHas(listener: () => void): () => void {
-    this._listenersForHas.add(listener);
-
-    return () => {
-      this._listenersForHas.delete(listener);
-    };
-  }
-
-  /**
-   * Drop EVERY session's transient state — used when the execution runtime
-   * changes underneath the window (`useDaemon` toggled: the authority for
-   * every transcript, run flag and per-run chip just moved to another
-   * process, or back). Unlike `evictExcept`, running sessions are NOT spared:
-   * a `running` flag from the previous runtime is exactly the kind of stale
-   * truth this exists to discard. Sessions re-hydrate through the ordinary
-   * cold path on next view, and the new runtime's `run:start`/`run:end`
-   * re-establish the flags.
-   */
-  dropAll(): void {
-    this.runStateVersion++;
-    const had = this._events.size > 0;
-    const sessionIds = new Set([...this._events.keys(), ...this._running.keys(), ...this._systemMd.keys()]);
-    this._events.clear();
-    this._running.clear();
-    this._runSeq.clear();
-    this._fallback.clear();
-    this._retry.clear();
-    this._systemMd.clear();
-    this._pages.clear();
-    // Echoes of sends made to the previous runtime never arrive, and no
-    // `run:end` from it will sweep them: left in place they would swallow an
-    // identical prompt sent through the new runtime.
-    this._pendingEcho.clear();
-
-    for (const sessionId of sessionIds) {
-      this._notifySession(sessionId);
-    }
-
-    if (had) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Empties a session's window and run state, and drops its hydration so the next activation reloads from disk.
-   *
-   * @param sessionId - The session.
-   */
-  reset(sessionId: K): void {
-    const had = this._events.has(sessionId);
-    const wasHydrated = this._pages.has(sessionId);
-    this._events.set(sessionId, []);
-    this._running.set(sessionId, false);
-    this._fallback.delete(sessionId);
-    this._retry.delete(sessionId);
-    this._systemMd.delete(sessionId);
-    this._pages.delete(sessionId);
-    this._notifySession(sessionId);
-
-    if (!had || wasHydrated) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Evict every hydrated window whose session id is not in `keep` — the
-   * memory bound for a long-lived window. Prewarm slides a window of
-   * likely-next sessions into the cache, and this slides old entries
-   * OUT, so a long browsing session does not accumulate one tail page per
-   * session ever visited. Revisiting an evicted session re-hydrates through the
-   * exact same `hydrated()` → `loadEvents` path a cold session uses.
-   *
-   * Never evicts:
-   *   - running sessions (live deltas exist only in this store — dropping
-   *     them would blank an in-flight background run's transcript);
-   *   - sessions with a scrollback fetch in flight (`loadingEarlier` —
-   *     the prepend landing after eviction would resurrect a window
-   *     containing ONLY the old page).
-   *
-   * @param keep - The sessions to keep.
-   */
-  evictExcept(keep: ReadonlySet<K>): void {
-    let dropped = false;
-
-    for (const sessionId of [...this._events.keys()]) {
-      if (keep.has(sessionId) || this._running.get(sessionId) || this._pages.get(sessionId)?.loadingEarlier) {
-        continue;
-      }
-
-      this._events.delete(sessionId);
-      this._running.delete(sessionId);
-      this._fallback.delete(sessionId);
-      this._retry.delete(sessionId);
-      /*
-       * `_systemMd` is deliberately NOT evicted here. This pass exists to
-       * bound the memory held by transcript EVENT windows; the override is one
-       * small object per session, and dropping it silently hides the badge
-       * warning that the built-in safety and git doctrine has been replaced —
-       * with no way to recover it until the agent is rebuilt.
-       */
-      this._pages.delete(sessionId);
-      this._notifySession(sessionId);
-      dropped = true;
-    }
-
-    if (dropped) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Drop a session entirely — called by `SessionsContext.deleteSession`
-   * so a removed row's stored events don't leak past the IPC delete.
-   *
-   * @param sessionId - The session.
-   */
-  drop(sessionId: K): void {
-    const had = this._events.has(sessionId) || this._running.has(sessionId);
-    this._events.delete(sessionId);
-    this._running.delete(sessionId);
-    this._runSeq.delete(sessionId);
-    this._fallback.delete(sessionId);
-    this._retry.delete(sessionId);
-    this._systemMd.delete(sessionId);
-    this._pages.delete(sessionId);
-    this._pendingEcho.delete(sessionId);
-    this._promptPreviews.delete(sessionId);
-
-    if (had) {
-      this._notifySession(sessionId);
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Remember the image previews of a prompt this window queued, so the copy
-   * that reaches the transcript later (host drain / push) keeps thumbnails.
-   * Bounded: a queue that never drains can't grow this without limit.
-   *
-   * @param sessionId - The session.
-   * @param text - The queued prompt's text.
-   * @param attachments - The prompt's attachments.
-   */
-  rememberPromptPreviews(sessionId: K, text: string, attachments: readonly ChatAttachment[]): void {
-    const withData = attachments.filter((a) => a.dataUrl !== undefined);
-    if (withData.length === 0) return;
-    const list = this._promptPreviews.get(sessionId) ?? [];
-    list.push({ text, attachments: withData });
-    this._promptPreviews.set(sessionId, list.slice(-16));
-  }
-
-  /**
-   * Unwind the latest `rememberPromptPreviews` entry for `text` after a failed enqueue.
-   *
-   * @param sessionId - The session.
-   * @param text - The queued prompt's text.
-   */
-  dropPromptPreviews(sessionId: K, text: string): void {
-    const list = this._promptPreviews.get(sessionId);
-    if (!list) return;
-    for (let i = list.length - 1; i >= 0; i--) {
-      if (list[i]!.text === text) {
-        list.splice(i, 1);
-        if (list.length === 0) this._promptPreviews.delete(sessionId);
-        return;
-      }
-    }
-  }
-
-  /**
-   * Follow a queued entry's text edit so its previews still match when it's sent.
-   *
-   * @param sessionId - The session.
-   * @param from - The queued prompt's text before the edit.
-   * @param to - Its text after the edit.
-   */
-  renamePromptPreviews(sessionId: K, from: string, to: string): void {
-    const list = this._promptPreviews.get(sessionId) ?? [];
-    for (let i = list.length - 1; i >= 0; i--) {
-      if (list[i]!.text === from) {
-        list[i]!.text = to;
-        return;
-      }
-    }
-  }
-
-  private takePromptPreviews(sessionId: K, text: string): ChatAttachment[] {
-    const list = this._promptPreviews.get(sessionId);
-    const index = list?.findIndex((entry) => entry.text === text) ?? -1;
-    if (!list || index === -1) return [];
-    const [taken] = list.splice(index, 1);
-    if (list.length === 0) this._promptPreviews.delete(sessionId);
-    return taken!.attachments;
-  }
-
-  /**
-   * Shows the user's prompt at once (optimistic append) and waits for its host echo, which is then dropped.
-   *
-   * @param sessionId - The session.
-   * @param text - The prompt text.
-   * @param refs - The completions the prompt used (skills, files), for its chips.
-   * @param rawAttachments - The prompt's attachments. Omitted for a pushed queued prompt, which takes the previews this client remembered for it.
-   */
-  appendUserPrompt(
-    sessionId: K,
-    text: string,
-    refs?: readonly PromptSegmentRef[],
-    rawAttachments?: readonly ChatAttachment[],
-  ): void {
-    const had = this._events.has(sessionId);
-    const events = this._events.get(sessionId)?.slice() ?? [];
-    /*
-     * A pushed queued entry is appended with no attachment list at all:
-     * restore its previews. A local send passes its own list (possibly
-     * empty), so it never inherits another prompt's previews.
-     */
-    const attachments =
-      rawAttachments === undefined || missingPreviewData(rawAttachments)
-        ? mergePromptPreviews(rawAttachments, this.takePromptPreviews(sessionId, text))
-        : rawAttachments;
-
-    /*
-     * `refs` only attaches when the user actually used a completion —
-     * bare prompts skip the field entirely so downstream `refs?.length`
-     * checks fast-path without a clone.
-     *
-     * `attachments` rides along on `ChatEvent` — canonical
-     * `StreamEvent` has no slot for it (TUI doesn't render inline
-     * images), but the GUI wire type extends it with the optional
-     * field.
-     */
-    const event: ChatEvent = {
-      kind: 'user-prompt',
-      text,
-      ...(refs && refs.length > 0 ? { refs: [...refs] } : {}),
-      ...(attachments && attachments.length > 0 ? { attachments: [...attachments] } : {}),
-    };
-    events.push(event);
-
-    const pending = this._pendingEcho.get(sessionId) ?? [];
-    pending.push(text);
-    this._pendingEcho.set(sessionId, pending);
-
-    this._events.set(sessionId, events);
-    this._notifySession(sessionId);
-
-    if (!had) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Unwind ONE pending echo after a FAILED send — a refused/errored send
-   * produces no run, so the `run:end` sweep never fires and the stale
-   * entry would silently swallow an identical remote prompt later.
-   *
-   * @param sessionId - The session.
-   * @param text - The prompt text.
-   */
-  dropPendingEcho(sessionId: K, text: string): void {
-    const pending = this._pendingEcho.get(sessionId);
-    const index = pending?.indexOf(text) ?? -1;
-
-    if (pending && index !== -1) {
-      pending.splice(index, 1);
-    }
-  }
-
-  /**
-   * The prompt texts this client appended that still await their host echo
-   * (see `appendUserPrompt`). The live list: an adapter that keeps its own
-   * echo rule (`createLiveState`) edits it in place.
-   *
-   * @param sessionId - The session.
-   */
-  pendingEchoes(sessionId: K): string[] {
-    let pending = this._pendingEcho.get(sessionId);
-
-    if (!pending) {
-      pending = [];
-      this._pendingEcho.set(sessionId, pending);
-    }
-
-    return pending;
-  }
-
-  /**
-   * Low-level write: sets any of a session's events, run flag and page state
-   * in one notification, with none of the signal rules (no finalize, no
-   * reconcile). For adapters that own their merge rules (`createLiveState`).
-   * The store keeps `events` as given and never mutates it.
-   *
-   * @param sessionId - The session.
-   * @param patch - The fields to set.
-   */
-  write(sessionId: K, patch: SessionStreamWrite): void {
-    const had = this._events.has(sessionId);
-    const wasHydrated = this._pages.has(sessionId);
-
-    if (patch.events !== undefined) {
-      this._events.set(sessionId, patch.events as ChatEvent[]);
-    } else if (!had) {
-      this._events.set(sessionId, []);
-    }
-
-    if (patch.running !== undefined) {
-      this._running.set(sessionId, patch.running);
-    }
-
-    if (patch.page === null) {
-      this._pages.delete(sessionId);
-    } else if (patch.page !== undefined) {
-      this._pages.set(sessionId, patch.page);
-    }
-
-    this._notifySession(sessionId);
-
-    if (!had || wasHydrated !== this._pages.has(sessionId)) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Appends a display-only error row (a send that failed before any run).
-   *
-   * @param sessionId - The session.
-   * @param text - The error message.
-   */
-  appendErrorEvent(sessionId: K, text: string): void {
-    const had = this._events.has(sessionId);
-    const events = this._events.get(sessionId)?.slice() ?? [];
-    events.push({ kind: 'error', text });
-    this._events.set(sessionId, events);
-    this._notifySession(sessionId);
-
-    if (!had) {
-      this._notifyHas();
-    }
-  }
-
-  /**
-   * Reduces one live signal into its session (see {@link SessionStreamSignal}). Signals of other kinds are ignored.
-   *
-   * @param input - The signal.
-   */
-  applySignal(input: SessionStreamSignal<K> | OtherStreamSignal): void {
-    const signal = input as SessionStreamSignal<K>;
-    switch (signal.kind) {
-      case 'run:start': {
-        this.runStateVersion++;
-        const had = this._events.has(signal.sessionId);
-
-        if (!had) {
-          this._events.set(signal.sessionId, []);
-          this._notifyHas();
-        }
-
-        this._running.set(signal.sessionId, true);
-        this._runSeq.set(signal.sessionId, (this._runSeq.get(signal.sessionId) ?? 0) + 1);
-        // Fallback is run-sticky — a new run starts from the primary, so
-        // the pill snaps back until (unless) this run falls back too.
-        this._fallback.delete(signal.sessionId);
-        this._notifySession(signal.sessionId);
-
-        return;
-      }
-      case 'run:end': {
-        this.runStateVersion++;
-        const prior = this._events.get(signal.sessionId) ?? [];
-
-        /*
-         * Finalize any in-flight streaming markdown first so its caret
-         * disappears and the final text persists.
-         */
-        // Run over: close every reasoning lane still open, whatever its owner
-        // (a worker aborted mid-thought gets no `turn:end`), so each row
-        // collapses with its duration.
-        let next = finishLive(prior);
-
-        /*
-         * When the run rejected, append an error row carrying the message.
-         * Without this the failure is silent — the user sees their prompt
-         * submitted, then nothing, with no clue why. The most common
-         * causes are provider auth issues, protocol-history rejections
-         * (unresolved tool_use from a prior session), and aborts.
-         */
-        if (!signal.ok && signal.error) {
-          next = [...next, { kind: 'error', text: signal.error, ...(signal.detail ? { detail: signal.detail } : {}) }];
-        }
-
-        const had = this._events.has(signal.sessionId);
-        this._events.set(signal.sessionId, next);
-        this._running.set(signal.sessionId, false);
-        // Retry can't outlive its run: a terminal failure never streams again,
-        // so nothing else would ever clear the indicator.
-        this._retry.delete(signal.sessionId);
-        // No echo can follow its run — drop leftovers (e.g. failed sends)
-        // so they can't swallow an identical future remote prompt.
-        this._pendingEcho.delete(signal.sessionId);
-        this._notifySession(signal.sessionId);
-
-        if (!had) {
-          this._notifyHas();
-        }
-
-        return;
-      }
-      case 'turn:end': {
-        const prior = this._events.get(signal.sessionId) ?? [];
-        const owner: Owner = signal.childId ?? PARENT_OWNER;
-        const had = this._events.has(signal.sessionId);
-        this._events.set(
-          signal.sessionId,
-          finalizeStreamingMarkdownForOwner(closeThinkingSegment(prior, owner), owner),
-        );
-        this._notifySession(signal.sessionId);
-
-        if (!had) {
-          this._notifyHas();
-        }
-
-        return;
-      }
-      case 'event': {
-        // The sender's own echo: consume exactly one pending optimistic
-        // append (see `_pendingEcho`) instead of rendering a duplicate.
-        if (signal.event.kind === 'user-prompt' && signal.echo) {
-          const pending = this._pendingEcho.get(signal.sessionId);
-          const index = pending?.indexOf(signal.event.text) ?? -1;
-
-          if (pending && index !== -1) {
-            pending.splice(index, 1);
-            return;
-          }
-        }
-
-        // A host-sent queued prompt carries attachment metadata only; paint
-        // the thumbnails this window kept when it queued the message.
-        let event = signal.event as ChatEvent;
-
-        if (event.kind === 'user-prompt' && missingPreviewData(event.attachments)) {
-          const previews = this.takePromptPreviews(signal.sessionId, event.text);
-          if (previews.length > 0) event = { ...event, attachments: mergePromptPreviews(event.attachments, previews) };
-        }
-
-        const had = this._events.has(signal.sessionId);
-        const prior = this._events.get(signal.sessionId) ?? [];
-        this._events.set(signal.sessionId, this._append(prior, event));
-        // Transcript events arrive at token rate (thinking deltas, tool bursts): the state is
-        // current at once, subscribers hear about it once per frame.
-        if (this._batch) this._notifySoon(signal.sessionId);
-        else this._notifySession(signal.sessionId);
-
-        if (!had) {
-          this._notifyHas();
-        }
-
-        return;
-      }
-      case 'model:fallback': {
-        this._fallback.set(signal.sessionId, signal.to);
-        if (signal.discardTurnId) this._discardThinking(signal.sessionId, 'parent', signal.discardTurnId);
-        this._notifySession(signal.sessionId);
-
-        return;
-      }
-      // `cache:break` falls to `default`: the transcript row arrives as a persisted notice `event`, filed after the turn it describes.
-      case 'stream:retry': {
-        this._retry.set(signal.sessionId, {
-          attempt: signal.attempt,
-          max: signal.max,
-          source: signal.source,
-        });
-        if (signal.discardTurnId) this._discardThinking(signal.sessionId, signal.source, signal.discardTurnId);
-        this._notifySession(signal.sessionId);
-
-        return;
-      }
-      case 'prompt-turns': {
-        /*
-         * Bind just-persisted prompt turns to their live `user-prompt` echoes so
-         * a prompt sent from THIS window becomes selectable (hover actions,
-         * edit, delete, fork) during the run — not only after the run-end
-         * hydration replaces the transcript. Same fix the TUI applies via
-         * `onPromptTurns`, on the same shared matcher. `ChatEvent` only
-         * narrows `attachments`, which the matcher reads structurally, so the
-         * cast back is safe.
-         */
-        const events = this._events.get(signal.sessionId);
-
-        if (!events || events.length === 0) {
-          return;
-        }
-
-        const next = retagUserPromptEventsFromRefs(events as unknown as StreamEvent[], signal.refs);
-
-        if (next !== events) {
-          // The bound prompt is the same bubble: its row keeps its key, so it updates in place
-          // instead of remounting (the send "blinked": the bubble rose a second time).
-          inheritRowIdentity(events, next);
-          this._events.set(signal.sessionId, next as unknown as ChatEvent[]);
-          this._notifySession(signal.sessionId);
-        }
-
-        return;
-      }
-      case 'stream:retry:cleared': {
-        /*
-         * Source-matched: a subagent stream dying must not clear a retry the
-         * PARENT stream is still in the middle of (and vice versa).
-         */
-        const current = this._retry.get(signal.sessionId);
-
-        if (current?.source === signal.source) {
-          this._retry.delete(signal.sessionId);
-          this._notifySession(signal.sessionId);
-        }
-
-        return;
-      }
-      case 'system-md': {
-        /*
-         * Which `SYSTEM.md` composed this session's prompt, or null for none.
-         *
-         * This must be surfaced, not merely stored: a `SYSTEM.md` REPLACES the
-         * built-in doctrine rather than appending to it, so an override in
-         * force means the safety and git guidance the user expects is gone —
-         * silently, since nothing errors. The host applies it wherever the
-         * prompt is composed, which can be another process.
-         */
-        this._systemMd.set(signal.sessionId, signal.file);
-        this._notifySession(signal.sessionId);
-
-        return;
-      }
-      default: {
-        return;
-      }
-    }
-  }
-
-  /**
-   * Apply a batch of synthesized smooth-stream deltas in one shot.
-   * Coalesces per-session work so a tick that touches sessions A and B
-   * fires exactly one notify per session — not one per delta.
-   *
-   * @param plan - The text released from the smooth-stream buckets.
-   */
-  applyDrainPlan(plan: readonly DrainPlan<K>[]): void {
-    if (plan.length === 0) {
-      return;
-    }
-
-    const touched = new Set<K>();
-
-    for (const entry of plan) {
-      const prior = this._events.get(entry.sessionId) ?? [];
-
-      const synthetic: StreamEvent = {
-        kind: 'markdown',
-        text: entry.text,
-        streaming: true,
-        ...(entry.childId ? { childId: entry.childId } : {}),
-        ...(entry.depth != null ? { depth: entry.depth } : {}),
-        ...(entry.turnId ? { turnId: entry.turnId } : {}),
-      };
-
-      this._events.set(entry.sessionId, this._append(prior, synthetic));
-      touched.add(entry.sessionId);
-    }
-
-    for (const sessionId of touched) {
-      this._notifySession(sessionId);
-    }
-  }
-
-  /** Sessions whose subscribers are owed a notification at the next frame (`_notifySoon`). */
-  private _pendingNotify = new Set<K>();
-  private _flushHandles: { raf: unknown; timer: unknown } = { raf: null, timer: null };
-
-  /**
-   * Coalesce notifications to one per frame. A frame callback when frames run, a
-   * timer when they don't (a hidden window throttles rAF; updates must still land).
-   */
-  private _notifySoon(sessionId: K): void {
-    this._pendingNotify.add(sessionId);
-    if (this._flushHandles.raf !== null || this._flushHandles.timer !== null) return;
-    const flush = () => this.flushNotifications();
-    this._flushHandles.raf = this._scheduler.frame(flush) ?? null;
-    this._flushHandles.timer = this._scheduler.timeout(flush, NOTIFY_FALLBACK_MS);
-  }
-
-  /** Deliver notifications `_notifySoon` held back (also called before anything that must be immediate). */
-  flushNotifications(): void {
-    const { raf, timer } = this._flushHandles;
-    if (raf !== null) this._scheduler.cancelFrame(raf);
-    if (timer !== null) this._scheduler.cancelTimeout(timer);
-    this._flushHandles = { raf: null, timer: null };
-    if (this._pendingNotify.size === 0) return;
-    const ids = [...this._pendingNotify];
-    this._pendingNotify.clear();
-    for (const id of ids) this._notifySession(id);
-  }
-
-  /** Drop a stalled attempt's reasoning lane: the retry (or next model) streams its own, and the saved turn never holds it. */
-  private _discardThinking(sessionId: K, source: string, turnId: string): void {
-    const events = this._events.get(sessionId);
-    if (!events) return;
-    const next = discardThinking(events, source, turnId);
-    if (next !== events) this._events.set(sessionId, next);
-  }
-
-  /**
-   * Append a fresh event with the kit's live rule (`applyLiveEvent`, the
-   * web chat's too): markdown / thinking deltas grow the owner's open block
-   * even when concurrent subagents rotate the tail between them, a new
-   * thinking lane is stamped with its start, any other event of an owner
-   * closes that owner's lane ("Thought for Ns"), and tool rows get their
-   * live arrival time (`receivedAt`, the fallback for a host that sends no
-   * timing of its own).
-   */
-  private _append(events: ChatEvent[], event: ChatEvent | StreamEvent): ChatEvent[] {
-    return applyLiveEvent<ChatEvent>(events, event as ChatEvent, Date.now(), this._markdown);
-  }
-
-  private _notifySession(sessionId: K): void {
-    // Anything owed to this session goes out with this notification.
-    this._pendingNotify.delete(sessionId);
-    const set = this._listenersBySession.get(sessionId);
-
-    if (set) {
-      for (const listener of set) {
-        listener();
-      }
-    }
-  }
-
-  private _notifyHas(): void {
-    for (const listener of this._listenersForHas) {
-      listener();
-    }
-  }
-}