@tanstack/ai-client 0.22.0 → 0.23.0

package/dist/esm/chat-client.d.ts

@@ -1,6 +1,6 @@
-import { AnyClientTool, ModelMessage, StreamChunk } from '@tanstack/ai/client';
+import { AnyClientTool, ModelMessage, RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client';
 import { ConnectionAdapter } from './connection-adapters.js';
-import { ChatClientOptions, ChatClientState, ChatFetcher, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
+import { BoundInterrupts, ChatClientOptions, ChatClientState, ChatFetcher, ChatInterrupt, ChatInterruptState, ChatResumeState, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
 type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>> = {
     connection?: ConnectionAdapter;
     fetcher?: ChatFetcher;
@@ -17,6 +17,13 @@ type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClien
     onConnectionStatusChange?: (status: ConnectionStatus) => void;
     onSessionGeneratingChange?: (isGenerating: boolean) => void;
     onQueueChange?: (queue: Array<QueuedMessage>) => void;
+    onResumeStateChange?: (resumeState: ChatResumeState | null, pendingInterrupts: BoundInterrupts<TTools>) => void;
+    /**
+     * Fires whenever the id of the run in flight changes: the new id when a run
+     * starts (including a rejoin), `null` when it settles.
+     */
+    onRunIdChange?: (runId: string | null) => void;
+    onInterruptStateChange?: (state: ChatInterruptState<TTools>) => void;
     onCustomEvent?: (eventType: string, data: unknown, context: {
         toolCallId?: string;
     }) => void;
@@ -42,7 +49,19 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private readonly uniqueId;
     private readonly threadId;
     private readonly persistor?;
+    private readonly clearedStreamTracker;
     private currentRunId;
+    private lastResume;
+    private rejoinedRunId;
+    private readonly interruptManager;
+    private activeInterruptSubmission;
+    private interruptSubmissionFailure;
+    private readonly joinedRunWaiters;
+    private pendingResumeParentRunId;
+    private pendingResumeThreadId;
+    private pendingResumeItems;
+    private activeResumeThreadId;
+    private activeResumeRunId;
     private bodyOption;
     private forwardedPropsOption;
     private context;
@@ -102,9 +121,74 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private draining;
     private sessionGenerating;
     private readonly activeRunIds;
+    /** Latched by `dispose()`; stops any late async callback starting new work. */
+    private disposed;
+    /** Whether a view is currently watching. See `attach` / `detach`. */
+    private tailing;
+    /** Constructor inputs `attach()` needs on every re-attach, not just the first. */
+    private readonly rejoinRunId;
+    private readonly cachesMessages;
     private devtoolsMounted;
     private readonly callbacksRef;
     constructor(options: ChatClientOptions<TTools, TContext>);
+    /**
+     * START TAILING: re-attach to an in-flight run so its chunks arrive here.
+     *
+     * Called by the constructor, and again by a UI wrapper every time its view
+     * mounts. Idempotent — attaching while already attached does nothing — so the
+     * constructor call and a wrapper's first mount cost one attach between them.
+     *
+     * Pairs with {@link detach}. The pair exists because tailing used to begin ONLY
+     * in the constructor, which meant a view could never stop tailing and then
+     * resume: unmount had to either keep the connection open or lose it for good.
+     * Keeping it open is what starved the page — a browser allows ~6 connections per
+     * origin, and one long-lived stream per view reaches that after a handful of
+     * views, after which every other request queues (measured: an in-page fetch took
+     * over two minutes while the same request from outside the browser took 17ms).
+     */
+    attach(): void;
+    /**
+     * STOP TAILING: drop the connection, keep everything else.
+     *
+     * Called by a UI wrapper when its view unmounts. The transcript, the resume
+     * pointer and the run id all stay, so a later {@link attach} repaints instantly
+     * and re-tails from the durable log — nothing is lost, because the run keeps
+     * going server-side and its log holds every chunk.
+     *
+     * Deliberately NOT `dispose()`: this client is expected back. And deliberately
+     * not `stop()`, which means "the user ended this run" — detaching says only that
+     * nobody is watching right now.
+     *
+     * `rejoinedRunId` is cleared so the next `attach` can re-join the same run;
+     * without that reset the guard in {@link maybeRejoinInFlight} would treat the
+     * run as already joined and the view would come back silent.
+     */
+    detach(): void;
+    private applyResumeSnapshot;
+    /**
+     * Apply a resume snapshot read from durable storage. Restores interrupt state,
+     * and for a bare in-flight run (no pending interrupts) also rejoins it. This is
+     * the async-store counterpart to the synchronous rejoin in the constructor:
+     * `applyResumeSnapshot` alone only handles interrupts, so an async store
+     * (`indexedDBPersistence`) would otherwise never rejoin a mid-stream run.
+     */
+    private applyPersistedResume;
+    /**
+     * Rejoin a persisted in-flight run, guarded so it fires at most once and never
+     * while another run is already active. Skipped when the connection is not
+     * resumable (`joinRun` absent), so a non-durable transport is a no-op.
+     */
+    private maybeRejoinInFlight;
+    /**
+     * Server-authoritative mount hydration (`persistence: true`). The client holds
+     * no transcript and no run pointer; on mount it asks the server — keyed by the
+     * stable threadId — for the stored transcript and whether a run is still
+     * generating. The transcript repaints immediately; an in-flight run is tailed
+     * through the same durability rejoin as a reload. Best-effort and
+     * non-blocking: a failure leaves the client empty rather than throwing, and a
+     * send that starts first owns the client (hydration then backs off).
+     */
+    private hydrateFromServer;
     mountDevtools(): void;
     /**
      * Drain a runId-less RUN_ERROR that belongs to a cleared run the client is
@@ -112,13 +196,57 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * owns the active-run / session / processing state.
      */
     private drainIgnoredRunlessChunk;
+    private retireIgnoredClearedTerminalChunk;
     private updateRunLifecycle;
+    /**
+     * Track interrupt state off the stream's terminal events. A RUN_FINISHED with
+     * an interrupt outcome records the pending interrupts + the run/thread to
+     * resume; any other terminal event for the tracked/current run clears that
+     * state. This is interrupt (state) resume — there is no delivery cursor.
+     */
+    private observeInterruptState;
+    /**
+     * The interrupt-resume state for the active/interrupted run (its run/thread
+     * ids), or null when there is nothing to resume. Apps can persist this to
+     * resume interrupts across a full reload.
+     */
+    getResumeState(): ChatResumeState | null;
+    /**
+     * The id of the run this client has in flight — one it started via a send or
+     * rejoined via `joinRun` — or null when there is none. Unlike
+     * {@link getResumeState}, this tracks ordinary runs too, not only one that is
+     * interrupted or being resumed. A run another client started and that arrives
+     * over a live subscription is not this client's run and is not reported here.
+     */
+    getCurrentRunId(): string | null;
+    private setCurrentRunId;
+    getInterruptState(): ChatInterruptState<TTools>;
+    getInterrupts(): BoundInterrupts<TTools>;
+    /** @deprecated Use getInterrupts(). */
+    getPendingInterrupts(): BoundInterrupts<TTools>;
+    resolveInterrupts(approved: boolean): void;
+    resolveInterrupts(resolver: (interrupt: ChatInterrupt<TTools>) => undefined): void;
+    cancelInterrupts(): void;
+    retryInterrupts(): void;
+    /** Unsafe low-level resume escape hatch. Prefer bound interrupt methods. */
+    resumeInterruptsUnsafe(resume: Array<RunAgentResumeItem>, state?: ChatResumeState): Promise<boolean>;
+    /** @deprecated Use bound interrupt methods or resumeInterruptsUnsafe(). */
+    resumeInterrupts(resume: Array<RunAgentResumeItem>, state?: ChatResumeState): Promise<boolean>;
+    private submitInterruptBatch;
+    private takeInterruptSubmissionFailure;
+    private interruptGeneration;
     private generateUniqueId;
     private setIsLoading;
     private setStatus;
     private setIsSubscribed;
     private setConnectionStatus;
     private setSessionGenerating;
+    private notifyResumeStateChange;
+    /**
+     * Build the durable resume snapshot from the current resume state + pending
+     * interrupt descriptors and hand it to the persistor (null clears it).
+     */
+    private persistResumeSnapshot;
     private resetSessionGenerating;
     private setError;
     private buildDevtoolsBridgeOptions;
@@ -136,6 +264,40 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * Consume chunks from the connection subscription.
      */
     private consumeSubscription;
+    /**
+     * Re-attach to an in-flight run after a full page reload, replaying its stream
+     * from the server's delivery-durability log via `joinRun` (which returns the
+     * whole run so far, then tails live to completion).
+     *
+     * The log is the single source of truth for the run, so we rebuild the
+     * in-flight assistant bubble from it rather than trying to reconcile the
+     * server-hydrated partial with the replay: on the first chunk that actually
+     * (re)builds a message we drop the hydrated in-flight assistant, and the
+     * replay reconstructs one clean bubble. Dropping only on real content (not on
+     * `RUN_STARTED`) means a rejoin that connects but delivers nothing can never
+     * leave an empty bubble behind.
+     *
+     * Bounded connect: a durable backend keeps a from-start join open waiting for
+     * a producer, so a stale pointer to an unknown/evicted run would otherwise pin
+     * the UI in a loading state for the backend's full first-chunk deadline. We
+     * give up after {@link REJOIN_CONNECT_DEADLINE_MS} if no chunk arrives and
+     * clear the dead pointer so it does not retry on the next load.
+     *
+     * Replay chunks are processed WITHOUT the per-chunk yield the live path uses,
+     * so the buffered prefix snaps in and only the genuinely-live tail streams at
+     * network speed — a reload looks like the run continued, not like it re-typed.
+     */
+    private resumeInFlightRun;
+    /**
+     * Drop a hydrated, still-in-flight assistant turn so a resume replay can
+     * rebuild it cleanly. Only touches a trailing assistant message (the shape a
+     * reload-mid-stream leaves); a thread whose last turn is a user message (run
+     * never produced, or already settled) is left untouched.
+     */
+    private dropTrailingInFlightAssistant;
+    private processIncomingChunk;
+    private isActiveInterruptSubmissionFailure;
+    private resolveJoinedRun;
     /**
      * Ensure subscription loop is running, starting it if needed.
      */
@@ -185,11 +347,18 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      *     ],
      *     id: 'custom-message-id'
      *   },
-     *   { model: 'gpt-4-audio' }
+     *   { model: 'gpt-5.5' }
      * )
      * ```
      */
     sendMessage(content: string | MultimodalContent, body?: Record<string, any>, sendOptions?: SendMessageOptions): Promise<void>;
+    /**
+     * True when the client still has user-actionable interrupts (or is mid
+     * resume submission). Staged/submitting items that are already being
+     * continued do not block a later turn once the resume stream has cleared
+     * resume state.
+     */
+    private hasBlockingInterrupts;
     /** True while a stream is active, a send is claiming the client, or the queue is draining. */
     private isSendBusy;
     private resolveBusyReason;