zidane-ui 9.1.1 → 9.1.4

package/src/chat/headless/streams/session-streams.ts

@@ -1,407 +0,0 @@
-/**
- * `createSessionStreams`: the session stream store with everything a live
- * client wraps around it. Smooth streaming paces streamed markdown per
- * (session, owner) on a once-per-frame ticker; lazy scrollback fetches the
- * page before a window; run-end compaction swaps an oversized background
- * window back to its disk tail page. React-free: frames and fetches are
- * injected.
- */
-import type { MarkdownDeltaOptions } from 'zidane/chat/pure';
-
-import type { Transcript } from '../host';
-import { SMOOTH_TICK_MS } from '../smooth-stream';
-import {
-  allBucketsEmpty,
-  type BucketMap,
-  getOrCreateBucket,
-  planDrainBeforeSignal,
-  planFullDrain,
-  planTickDrain,
-} from './pacer';
-import { defaultFrameScheduler, type FrameScheduler } from './scheduler';
-import { SessionStreamStore } from './store';
-import { storeTranscript } from './transcript';
-import type { OtherStreamSignal, SessionStreamPage, SessionStreamSignal } from './types';
-
-/**
- * Event count past which a session's live window is compacted back to the
- * on-disk tail page at the next run-end boundary. Sized well above a tail
- * page (at least 200 turns) so compaction only ever fires after genuinely
- * long runs, and comfortably below where the per-commit `collapseEvents`
- * walk starts eating the frame budget.
- */
-const EVENT_WINDOW_COMPACT_THRESHOLD = 2000;
-
-/** Options for {@link createSessionStreams}. */
-export interface SessionStreamsOptions<K extends string = string> {
-  /** Pace streamed markdown at a steady speed. A function is read on every signal, so a setting can flip it live (call {@link SessionStreams.drainSmoothing} when it turns off). Default: `false`. */
-  smooth?: boolean | (() => boolean);
-  /** Frames and timers for pacing and batched notifications. Default: {@link defaultFrameScheduler}. */
-  scheduler?: FrameScheduler;
-  /** How streamed markdown merges. Default: one event per message. */
-  markdown?: MarkdownDeltaOptions;
-  /** Loads a session's persisted tail page. Run-end compaction needs it; without it windows are never compacted. */
-  loadTail?(sessionId: K): Promise<SessionStreamPage>;
-  /** Loads the page before `beforeSeq`. {@link SessionStreams.loadEarlier} needs it. */
-  loadBefore?(sessionId: K, beforeSeq: number): Promise<SessionStreamPage>;
-  /** Event count past which a background window is compacted at run end. Default: 2000. */
-  compactAbove?: number;
-}
-
-/** What {@link SessionStreams.loadEarlier} reports back. */
-export interface LoadEarlierOptions {
-  /** Called once the fetch settles: `true` when the older page was spliced in. */
-  onSettled?: (prepended: boolean) => void;
-}
-
-/** The session stream store with pacing, scrollback and compaction. Created by {@link createSessionStreams}. */
-export interface SessionStreams<K extends string = string> {
-  /** The store: per-session snapshots (`get…Snapshot`), per-session subscriptions and the direct writes. */
-  readonly store: SessionStreamStore<K>;
-  /**
-   * Feeds one live signal in. With smoothing on, streamed markdown waits in its
-   * (session, owner) bucket and any other signal first drains the buckets it
-   * follows, so the transcript stays in causal order.
-   */
-  apply(signal: SessionStreamSignal<K> | OtherStreamSignal): void;
-  /** A session's transcript as a {@link ChatHost} hands it to the components (cached per session). */
-  transcript(sessionId: K): Transcript;
-  /** Empties a session's window and run state (and its smoothing bucket). */
-  reset(sessionId: K): void;
-  /** Forgets a session entirely (a deleted session). */
-  drop(sessionId: K): void;
-  /** Forgets every session (the runtime behind them changed). */
-  dropAll(): void;
-  /** Evicts hydrated windows outside `keep`; running and mid-scrollback sessions stay. */
-  evictExcept(keep: ReadonlySet<K>): void;
-  /** Ends a session's run without a host signal (the host says it is idle): drains its buckets, then applies `run:end`. */
-  confirmIdle(sessionId: K): void;
-  /**
-   * Fetches and splices the page before the session's window. Returns whether
-   * a fetch started (false while one is in flight, when history is complete,
-   * or without `loadBefore`). A page that lands after the window changed
-   * (reset, re-hydration) is dropped and reported as `onSettled(false)`.
-   */
-  loadEarlier(sessionId: K, options?: LoadEarlierOptions): boolean;
-  /** The session the user is looking at: run-end compaction skips it and catches up once it is backgrounded. */
-  noteActiveSession(sessionId: K | null): void;
-  /** Reveals every waiting smoothed delta at once and stops the ticker (smoothing was turned off). */
-  drainSmoothing(): void;
-  /** Stops the ticker and delivers held notifications. */
-  dispose(): void;
-}
-
-/**
- * Creates the session stream store with smooth streaming, lazy scrollback and
- * run-end compaction. Feed it a client's live signals with `apply`.
- *
- * @param options - Smoothing, the scheduler, the markdown rule and the page loaders.
- */
-export function createSessionStreams<K extends string = string>(
-  options: SessionStreamsOptions<K> = {},
-): SessionStreams<K> {
-  const scheduler = options.scheduler ?? defaultFrameScheduler;
-  const store = new SessionStreamStore<K>({
-    scheduler,
-    ...(options.markdown ? { markdown: options.markdown } : {}),
-  });
-  const smoothOption = options.smooth;
-  const isSmooth = typeof smoothOption === 'function' ? smoothOption : () => smoothOption ?? false;
-  const threshold = options.compactAbove ?? EVENT_WINDOW_COMPACT_THRESHOLD;
-
-  /*
-   * Bucket map: mutated from `apply` and the ticker. Drain plans synthesize
-   * matching events from the bucket so the store-side coalescing stays the
-   * single source of truth for the events array.
-   */
-  const buckets: BucketMap<K> = new Map();
-  /** The pending tick: a frame handle, or a timer's where there are no frames (`tickOnTimer`). */
-  let tickHandle: unknown = null;
-  let tickOnTimer = false;
-  let lastTick = 0;
-
-  const stopTicker = () => {
-    if (tickHandle === null) return;
-    if (tickOnTimer) scheduler.cancelTimeout(tickHandle);
-    else scheduler.cancelFrame(tickHandle);
-    tickHandle = null;
-  };
-
-  const nextTick = (tick: (now: number) => void) => {
-    tickHandle = scheduler.frame(tick) ?? null;
-    tickOnTimer = tickHandle === null;
-    if (tickOnTimer) tickHandle = scheduler.timeout(() => tick(scheduler.now()), SMOOTH_TICK_MS);
-  };
-
-  /*
-   * One drain per painted frame. A 16ms `setInterval` is not aligned to
-   * frames: under load (a scroll, a long commit) several ticks queue into
-   * one frame and each commits its own render, which is what made the
-   * transcript stutter when scrolled while a reply streamed. The drain
-   * scales by the real `dt`, so the reveal pace is unchanged; a hidden
-   * window pauses it, and the next frame catches up.
-   */
-  const ensureTicker = () => {
-    if (tickHandle !== null) return;
-
-    lastTick = scheduler.now();
-    const tick = (now: number) => {
-      const dt = Math.min(now - lastTick, SMOOTH_TICK_MS * 8);
-      lastTick = now;
-
-      const plan = planTickDrain(buckets, dt);
-
-      if (plan.length === 0 && allBucketsEmpty(buckets)) {
-        tickHandle = null;
-        return;
-      }
-
-      if (plan.length > 0) store.applyDrainPlan(plan);
-
-      nextTick(tick);
-    };
-    nextTick(tick);
-  };
-
-  /*
-   * The active session is exempt from run-end compaction — swapping the
-   * hydrated window for the disk tail page is invisible for background
-   * sessions but yanks the transcript under a user who is scrolled up
-   * reading. Deferred ids compact when the session is backgrounded
-   * (`noteActiveSession` with a different id).
-   */
-  let activeSession: K | null = null;
-  const deferredCompact = new Set<K>();
-
-  /*
-   * Live-window compaction. During a run the window only grows — every
-   * delta and tool event appends — and nothing bounds it (the paging model
-   * can't front-trim in place because live events carry no turn seq for the
-   * scrollback bookkeeping). So compact at the natural safe boundary
-   * instead: when a run ends with an oversized window, re-hydrate the tail
-   * page from disk — the same primitive session activation uses — which
-   * resets events AND page state consistently, so lazy scrollback keeps
-   * working.
-   *
-   * The reference-equality guard makes the swap race-free: EVERY store
-   * write path replaces the events array, so if the snapshot taken at
-   * run-end is still identical when the fetch resolves, nothing (a new
-   * run's deltas, an optimistic prompt echo, another signal) landed in
-   * between and the replay page supersedes exactly what we measured.
-   */
-  const compactSession = (sessionId: K) => {
-    const snapshot = store.getEventsSnapshot(sessionId);
-
-    if (snapshot.length <= threshold || !options.loadTail) return;
-
-    options
-      .loadTail(sessionId)
-      .then((page) => {
-        if (store.getEventsSnapshot(sessionId) === snapshot) store.setEventsPage(sessionId, page);
-      })
-      .catch(() => {
-        /* best-effort — an oversized window is degraded, not broken */
-      });
-  };
-
-  const compactAfterRunEnd = (signal: SessionStreamSignal<K>) => {
-    if (signal.kind !== 'run:end') return;
-
-    const { sessionId } = signal;
-
-    /*
-     * A failed run's error row exists ONLY in this store — the host
-     * broadcasts it but never persists it, so the disk tail page has no
-     * trace of the failure. Swapping the window would eat the feedback
-     * exactly where it matters most (long runs trip the threshold AND fail
-     * most often). Leave the terminal window big and drop any stale
-     * deferral so a later backgrounding drain can't perform the same swap.
-     */
-    if (!signal.ok) {
-      deferredCompact.delete(sessionId);
-      return;
-    }
-
-    if (sessionId === activeSession) {
-      deferredCompact.add(sessionId);
-      return;
-    }
-
-    // A deferred id that reaches run:end while backgrounded compacts here,
-    // so drop the deferral instead of leaving a stale entry behind.
-    deferredCompact.delete(sessionId);
-    compactSession(sessionId);
-  };
-
-  // A handle caches its last snapshot (the whole events array): it goes with the window it reads.
-  const transcripts = new Map<K, Transcript>();
-
-  const streams: SessionStreams<K> = {
-    store,
-    apply(input) {
-      const signal = input as SessionStreamSignal<K>;
-      /*
-       * Smooth streaming path. Markdown deltas enqueue into the per-(session,
-       * owner) bucket and return without touching store state; the ticker
-       * dispatches synthesized deltas at the paced cps. All other events
-       * drain the matching bucket first so ordering is preserved (a tool
-       * call must never land before the markdown that preceded it).
-       */
-      if (isSmooth()) {
-        if (signal.kind === 'event' && signal.event.kind === 'markdown' && signal.event.streaming) {
-          const { event } = signal;
-          const bucket = getOrCreateBucket(buckets, signal.sessionId, event.childId ?? 'parent');
-
-          /*
-           * Pin the bucket's ownership tags on its FIRST write (or on the
-           * first write after a drain emptied it). Without this, two rapid
-           * back-to-back turns for the same owner overwrite `turnId` on
-           * every delta — and any text still buffered from the previous turn
-           * gets re-tagged with the new turn's id, mis-grouping the
-           * select-turn highlight.
-           */
-          if (bucket.pending.length === 0) {
-            bucket.childId = event.childId;
-            bucket.depth = event.depth;
-            bucket.turnId = event.turnId;
-          }
-
-          bucket.pending += event.text;
-          ensureTicker();
-          return;
-        }
-
-        /*
-         * Non-markdown events still need their predecessor's bucket flushed
-         * before they apply so the transcript stays in causal order: the
-         * drain plan (computed against the buckets, leaving the remainder)
-         * goes in, then the signal.
-         */
-        const plan = planDrainBeforeSignal(buckets, signal);
-        if (plan.length > 0) store.applyDrainPlan(plan);
-
-        store.applySignal(signal);
-        compactAfterRunEnd(signal);
-
-        if (allBucketsEmpty(buckets)) stopTicker();
-        return;
-      }
-
-      store.applySignal(signal);
-      compactAfterRunEnd(signal);
-    },
-    transcript(sessionId) {
-      let transcript = transcripts.get(sessionId);
-      if (!transcript) {
-        transcript = storeTranscript(
-          store,
-          sessionId,
-          options.loadBefore ? () => void streams.loadEarlier(sessionId) : undefined,
-        );
-        transcripts.set(sessionId, transcript);
-      }
-      return transcript;
-    },
-    reset(sessionId) {
-      buckets.delete(sessionId);
-      store.reset(sessionId);
-    },
-    drop(sessionId) {
-      buckets.delete(sessionId);
-      transcripts.delete(sessionId);
-      store.drop(sessionId);
-    },
-    dropAll() {
-      buckets.clear();
-      transcripts.clear();
-      store.dropAll();
-    },
-    evictExcept(keep) {
-      // Mirror `reset`/`drop`: an evicted session's (empty, drained-at-
-      // run-end) bucket entry must not linger in the smooth-stream map.
-      for (const sessionId of [...buckets.keys()]) {
-        if (!keep.has(sessionId) && !store.getRunningSnapshot(sessionId)) buckets.delete(sessionId);
-      }
-      // The store's own rule: kept, running and mid-scrollback sessions stay.
-      for (const sessionId of [...transcripts.keys()]) {
-        if (
-          keep.has(sessionId) ||
-          store.getRunningSnapshot(sessionId) ||
-          store.getPageSnapshot(sessionId).loadingEarlier
-        )
-          continue;
-        transcripts.delete(sessionId);
-      }
-
-      store.evictExcept(keep);
-    },
-    confirmIdle(sessionId) {
-      const signal: SessionStreamSignal<K> = { kind: 'run:end', sessionId, ok: true };
-      store.applyDrainPlan(planDrainBeforeSignal(buckets, signal));
-      store.applySignal(signal);
-    },
-    loadEarlier(sessionId, opts) {
-      const page = store.getPageSnapshot(sessionId);
-      const loadBefore = options.loadBefore;
-
-      if (!loadBefore || !page.hasMore || page.loadingEarlier || page.firstSeq <= 0) return false;
-
-      store.setLoadingEarlier(sessionId, true);
-      /*
-       * Only the window this fetch was issued for may take the page. Every
-       * page-state write replaces the object, so identity says whether
-       * anything happened since: a reset / drop / runtime switch (prepending
-       * would resurrect a window holding only the old page) or a tail
-       * re-hydration (the page would land in front of a window it does not
-       * abut, or twice if another fetch started meanwhile).
-       */
-      const issued = store.getPageSnapshot(sessionId);
-      const current = () => store.getPageSnapshot(sessionId) === issued;
-
-      loadBefore(sessionId, page.firstSeq)
-        .then((older) => {
-          if (!current()) {
-            opts?.onSettled?.(false);
-            return;
-          }
-          store.prependEventsPage(sessionId, older);
-          opts?.onSettled?.(true);
-        })
-        .catch(() => {
-          if (current()) store.setLoadingEarlier(sessionId, false);
-          opts?.onSettled?.(false);
-        });
-
-      return true;
-    },
-    noteActiveSession(sessionId) {
-      activeSession = sessionId;
-
-      for (const deferred of [...deferredCompact]) {
-        if (deferred === sessionId) continue;
-
-        /*
-         * A running session still has streamed deltas that are not on disk
-         * yet — swapping in the tail page would drop them. Leave it deferred;
-         * its run:end compacts through the persistence-safe path above.
-         */
-        if (store.getRunningSnapshot(deferred)) continue;
-
-        deferredCompact.delete(deferred);
-        compactSession(deferred);
-      }
-    },
-    drainSmoothing() {
-      const plan = planFullDrain(buckets);
-      if (plan.length > 0) store.applyDrainPlan(plan);
-      stopTicker();
-    },
-    dispose() {
-      stopTicker();
-      // Cancels the store's pending frame / fallback timer.
-      store.flushNotifications();
-    },
-  };
-
-  return streams;
-}