zidane-ui 9.1.13 → 9.1.16

package/dist/chat/headless/streams/store.d.ts

@@ -1,10 +1,19 @@
 import { ChatAttachment, ChatEvent } from "../host.js";
-import { FrameScheduler } from "./scheduler.js";
 import { OtherStreamSignal, SessionFallbackModel, SessionPageState, SessionRetryState, SessionStreamPage, SessionStreamSignal } from "./types.js";
 import { DrainPlan } from "./pacer.js";
-import { MarkdownDeltaOptions, PromptSegmentRef } from "zidane/chat/pure";
+import { FrameScheduler } from "./scheduler.js";
+import { HistoryChange, HistorySince, MarkdownDeltaOptions, PromptSegmentRef } from "zidane/chat/pure";
 import { SystemMdFile } from "zidane/chat";
 //#region src/chat/headless/streams/store.d.ts
+/** A prompt this client appended optimistically, awaiting its host echo (`SessionStreamStore.pendingEchoes`). */
+interface PendingEcho {
+  /** The prompt text. */
+  text: string;
+  /** The id the send gave the message, when it gave one. */
+  clientMessageId?: string;
+  /** The row the client appended. The echo gives it its turn id. */
+  event: ChatEvent;
+}
 /** Options for {@link SessionStreamStore}. */
 interface SessionStreamStoreOptions {
   /** Frames and timers for batched notifications. Default: {@link defaultFrameScheduler}. */
@@ -86,15 +95,17 @@ declare class SessionStreamStore<K extends string = string> {
   private _runSeq;
   private _pages;
   /**
-   * 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).
+   * 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 sent the prompt, so the dedupe lives here. One pending entry
+   * consumes one echo and keeps the local copy, which carries refs and
+   * attachments that the canonical event does not.
    * 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`.
+   * The echo matches by the sender's message id when both carry one, else
+   * by text, and gives the local row its turn id. Leftovers (failed sends)
+   * are cleared at `run:end`.
    */
   private _pendingEcho;
   /**
@@ -102,6 +113,39 @@ declare class SessionStreamStore<K extends string = string> {
    * the prompt shows up in the transcript (see `prompt-previews.ts`).
    */
   private _promptPreviews;
+  /** The history position each window applied last (`applyHistory`). It is the window's bookmark in the session's history. */
+  private _historyPos;
+  /** The numbering of each window's `_historyPos` (`HistoryPosition.historyId`), when known. */
+  private _historyId;
+  /** Windows to fetch again when their run ends (`takeRefetchDue`, `markRefetchDue`). */
+  private _refetchDue;
+  /**
+   * Windows whose rows are behind their history position. A write asked for a
+   * tail read that has not landed yet (in flight, failed, or waiting for the
+   * run's end). The position stays the newest write seen, so a read older than
+   * it is stale. But it is not a bookmark. The reconnect ladder reads the tail,
+   * and a later write also reads the tail instead of applying in place.
+   */
+  private _tailDue;
+  /** Per window, the numberings it left for another numbering. A read in one of them is older than the window. */
+  private _retiredHistoryIds;
+  /**
+   * Windows that saw their current run start (`run:start`, live or replayed).
+   * If a run ends in a hydrated window that never saw it start, the window
+   * missed the run's first rows. This happens after a drop that main could not
+   * replay, or when the window opened mid-run. The rows it read meanwhile also
+   * sit below the rows it streamed since. So it reads its tail at the run's
+   * end (`takeRefetchDue`).
+   */
+  private _runStarted;
+  /**
+   * Windows that streamed rows since their last run boundary (a run's start or
+   * end, a page read). With `_running`, it tells a run whose start went by
+   * apart from a send that the host refused before it started. A refused send
+   * streams nothing, and its error row lives only in this store. Reading the
+   * tail drops that row.
+   */
+  private _runActivity;
   private _listenersBySession;
   private _listenersForHas;
   /**
@@ -194,14 +238,98 @@ declare class SessionStreamStore<K extends string = string> {
    */
   getPageSnapshot(sessionId: K | null): SessionPageState;
   /**
-   * 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.
+   * 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. Returns `false` and changes nothing
+   * when the page is older than a write the window applied since.
    *
    * @param sessionId - The session.
    * @param page - The persisted page.
    */
-  setEventsPage(sessionId: K, page: SessionStreamPage): void;
+  setEventsPage(sessionId: K, page: SessionStreamPage): boolean;
+  /**
+   * Applies one history write (`history:changed`) to the session's window.
+   * It uses the shared rule (`applyHistoryOp`, `zidane/chat/pure`). A
+   * streamed append changes nothing. An append that never streamed adds the
+   * rows it carries. A rewrite or a missed write asks for a fetch.
+   *
+   * Returns `true` when the caller must fetch the session's tail now and
+   * replace the window with it (`setEventsPage`). A window whose run streams
+   * fetches at the run's end instead (`takeRefetchDue`), and a window never
+   * hydrated is left to its first read.
+   *
+   * @param sessionId - The session.
+   * @param change - The write, as the signal carries it.
+   */
+  applyHistory(sessionId: K, change: HistoryChange): boolean;
+  /**
+   * Applies a shared history rule's answer to the window. Its position moves
+   * first. Then its rows change, or it asks for a tail read. It returns `true`
+   * for a read now. While the run streams, the read waits for the run's end.
+   * A window whose rows are behind (`_tailDue`) reads its tail on any write
+   * that moves it. It does not apply the write to rows that miss the earlier one.
+   */
+  private _applyHistoryResult;
+  /**
+   * Applies the reconnect ladder's second step to the session's window. That
+   * step brings the rows of the turns appended after its position
+   * (`sessions.historySince`, the shared `applyHistorySince`). Returns `true`
+   * when the caller must fetch the tail now (as {@link applyHistory} does).
+   *
+   * @param sessionId - The session.
+   * @param since - The rows and the position they bring the window to.
+   */
+  applyHistorySince(sessionId: K, since: HistorySince<ChatEvent>): boolean;
+  /**
+   * Moves the window to `pos` after an adapter's own hydrate replaced it with
+   * a tail read at `pos`. Returns `stale` if the read is older than a write
+   * the window applied since. The adapter then reads it again.
+   *
+   * @param sessionId - The session.
+   * @param pos - The read's position, when the host named one.
+   * @param historyId - The numbering `pos` counts in, when the host named one.
+   */
+  adoptHistoryPos(sessionId: K, pos: number | undefined, historyId?: string): 'fresh' | 'stale';
+  /** `readFreshness` against what the window applied, and the numberings it left. */
+  private _freshness;
+  /** What the window applied last, for the shared history rules. */
+  private _historyContext;
+  /** Sets the window at `pos` of numbering `historyId`. If the numbering is unknown, none is kept. */
+  private _setHistoryPos;
+  /**
+   * Whether the session's window must be fetched again now that its run ended
+   * (see `applyHistory`, `markRefetchDue`). Clears the flag.
+   *
+   * @param sessionId - The session.
+   */
+  takeRefetchDue(sessionId: K): boolean;
+  /**
+   * Asks for the session's window to be read again at its run's end (`takeRefetchDue`). It is for a read dropped
+   * because a run streamed when it came back, or for a read that kept coming back older than the window.
+   *
+   * @param sessionId - The session.
+   */
+  markRefetchDue(sessionId: K): void;
+  /**
+   * Whether the session's rows are behind its history position. This is so
+   * when a write asked for a tail read that has not landed (in flight, failed,
+   * or waiting for the run's end). The reconnect ladder then reads the tail.
+   *
+   * @param sessionId - The session.
+   */
+  isTailDue(sessionId: K): boolean;
+  /**
+   * The history position the session's window applied last. It is `undefined` before its first `history:changed` or positioned page.
+   *
+   * @param sessionId - The session.
+   */
+  getHistoryPosSnapshot(sessionId: K): number | undefined;
+  /**
+   * The numbering of {@link getHistoryPosSnapshot}'s position, when known.
+   *
+   * @param sessionId - The session.
+   */
+  getHistoryIdSnapshot(sessionId: K): string | undefined;
   /**
    * Splice an OLDER page in front of the hydrated window (lazy scrollback).
    *
@@ -306,8 +434,9 @@ declare class SessionStreamStore<K extends string = string> {
    * @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.
+   * @param clientMessageId - The id the send gave the message (`SendOptions.clientMessageId`). The store matches the echo by it.
    */
-  appendUserPrompt(sessionId: K, text: string, refs?: readonly PromptSegmentRef[], rawAttachments?: readonly ChatAttachment[]): void;
+  appendUserPrompt(sessionId: K, text: string, refs?: readonly PromptSegmentRef[], rawAttachments?: readonly ChatAttachment[], clientMessageId?: string): void;
   /**
    * 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
@@ -324,7 +453,7 @@ declare class SessionStreamStore<K extends string = string> {
    *
    * @param sessionId - The session.
    */
-  pendingEchoes(sessionId: K): string[];
+  pendingEchoes(sessionId: K): PendingEcho[];
   /**
    * 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
@@ -366,6 +495,23 @@ declare class SessionStreamStore<K extends string = string> {
   private _notifySoon;
   /** Deliver notifications `_notifySoon` held back (also called before anything that must be immediate). */
   flushNotifications(): void;
+  /**
+   * Returns `live` without the prompts that this client appended and that the
+   * page already holds. These prompts still await their echo. They match by the
+   * send's message id, which the saved prompt carries (`origin.messageId`).
+   * Their pending entries stay, so the echo is still consumed. It binds
+   * nothing, because the row is gone.
+   */
+  private _withoutSavedLocalPrompts;
+  /**
+   * Puts the host's exchange separator before the oldest prompt that this
+   * client appended and whose echo has not come yet (`appendUserPrompt`).
+   * Returns false when no such prompt is on show. The separator then appends
+   * like any event.
+   */
+  private _separateLocalPrompt;
+  /** Gives this client's optimistic prompt row the turn id its echo carries. A row that a reload replaced is left alone. */
+  private _bindLocalPrompt;
   /** Drop a stalled attempt's reasoning lane: the retry (or next model) streams its own, and the saved turn never holds it. */
   private _discardThinking;
   /**
@@ -382,4 +528,4 @@ declare class SessionStreamStore<K extends string = string> {
   private _notifyHas;
 }
 //#endregion
-export { SessionStreamStore, SessionStreamStoreOptions, SessionStreamWrite };
+export { PendingEcho, SessionStreamStore, SessionStreamStoreOptions, SessionStreamWrite };