@tanstack/ai-client 0.22.1 → 0.23.1

package/src/chat-client.ts

@@ -13,13 +13,18 @@ import {
   normalizeConnectionAdapter,
 } from './connection-adapters'
 import { ChatPersistor } from './client-persistor'
+import { ClearedStreamTracker } from './cleared-stream-tracker'
+import { InterruptManager } from './interrupt-manager'
 import type {
   AnyClientTool,
   ContentPart,
+  InterruptSubmissionError,
   ModelMessage,
+  RunAgentResumeItem,
   StreamChunk,
 } from '@tanstack/ai/client'
 import type {
+  ChatHydrationResult,
   ConnectionAdapter,
   SubscribeConnectionAdapter,
 } from './connection-adapters'
@@ -33,9 +38,15 @@ import type {
   ChatDevtoolsBridgeOptions,
 } from './devtools'
 import type {
+  BoundInterrupts,
   ChatClientOptions,
   ChatClientState,
   ChatFetcher,
+  ChatInterrupt,
+  ChatInterruptState,
+  ChatPendingInterrupt,
+  ChatResumeSnapshot,
+  ChatResumeState,
   ConnectionStatus,
   MessagePart,
   MultimodalContent,
@@ -48,6 +59,7 @@ import type {
   UIMessage,
   WhenBusy,
 } from './types'
+import type { InterruptManagerSubmission } from './interrupt-manager'
 
 /** Internal queue entry — public {@link QueuedMessage} plus optional per-send body. */
 interface InternalQueuedMessage extends QueuedMessage {
@@ -72,6 +84,16 @@ type ChatClientUpdateOptionsWithoutContext<
   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,
@@ -178,6 +200,74 @@ function mergeQueuedMessages(items: Array<InternalQueuedMessage>): {
   }
 }
 
+/**
+ * Extract a boolean approval decision from an AG-UI resume payload, if present.
+ * Tool-approval resolutions carry `{ approved: boolean, ... }`; generic
+ * interrupt payloads do not.
+ */
+function readApprovalApproved(payload: unknown): boolean | undefined {
+  if (
+    payload === null ||
+    typeof payload !== 'object' ||
+    Array.isArray(payload)
+  ) {
+    return undefined
+  }
+  if (!('approved' in payload) || typeof payload.approved !== 'boolean') {
+    return undefined
+  }
+  return payload.approved
+}
+
+function readResumeState(
+  snapshot: ChatResumeSnapshot,
+): ChatResumeState | undefined {
+  const value: unknown = snapshot
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('resumeState' in value)
+  ) {
+    return undefined
+  }
+  const resumeState = value.resumeState
+  if (
+    resumeState === null ||
+    typeof resumeState !== 'object' ||
+    !('threadId' in resumeState) ||
+    typeof resumeState.threadId !== 'string' ||
+    resumeState.threadId.length === 0 ||
+    !('runId' in resumeState) ||
+    typeof resumeState.runId !== 'string' ||
+    resumeState.runId.length === 0
+  ) {
+    return undefined
+  }
+  return { threadId: resumeState.threadId, runId: resumeState.runId }
+}
+
+/**
+ * How long a reload rejoin waits for its first chunk before giving up. A durable
+ * backend keeps a from-start join open waiting for a producer; without this
+ * bound a stale pointer to an unknown/evicted run would pin the UI loading for
+ * the backend's full first-chunk deadline (tens of seconds). Kept short so the
+ * client decides "reachable or not" quickly.
+ */
+const REJOIN_CONNECT_DEADLINE_MS = 2000
+
+/**
+ * Chunk types that (re)build the assistant message on a rejoin. The hydrated
+ * in-flight partial is dropped only when one of these arrives — never on
+ * `RUN_STARTED` alone — so a rejoin that connects but delivers no content cannot
+ * leave an empty assistant bubble.
+ */
+const REJOIN_REBUILD_TRIGGERS = new Set<string>([
+  'TEXT_MESSAGE_START',
+  'TEXT_MESSAGE_CONTENT',
+  'TOOL_CALL_START',
+  'MESSAGES_SNAPSHOT',
+])
+
 export class ChatClient<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = unknown,
@@ -186,11 +276,35 @@ export class ChatClient<
   private connection: SubscribeConnectionAdapter
   private readonly uniqueId: string
   private readonly threadId: string
-  // All persistence concerns (hydrate / save / clear, plus suppression of late
-  // chunks after a mid-stream clear) live in ChatPersistor so this class stays
-  // focused on streaming. Undefined when no `persistence` adapter is configured.
+  // Durable chat persistence (optional): messages + resume snapshot as one
+  // combined record, so a full page reload restores the transcript, rehydrates
+  // pending interrupts, and rejoins an in-flight run. Clear-during-stream
+  // suppression is always on via ClearedStreamTracker so `clear()` works
+  // without a storage adapter.
   private readonly persistor?: ChatPersistor
+  private readonly clearedStreamTracker = new ClearedStreamTracker()
   private currentRunId: string | null = null
+  // Interrupt-resume tracking: the run/thread of the most recent interrupted
+  // run, so approvals/client-tool results can be sent back. Cleared when the
+  // run terminates. This is STATE (interrupt) resume, not delivery/cursor.
+  private lastResume: ChatResumeState | null = null
+  // The in-flight run id already handed to `resumeInFlightRun`, so a persisted
+  // run is rejoined at most once even when both the sync read and the async
+  // hydrate surface the same resume pointer.
+  private rejoinedRunId: string | null = null
+  private readonly interruptManager: InterruptManager<TTools>
+  private activeInterruptSubmission: InterruptManagerSubmission | undefined
+  private interruptSubmissionFailure:
+    | { errors: ReadonlyArray<InterruptSubmissionError> }
+    | undefined
+  private readonly joinedRunWaiters = new Map<string, () => void>()
+  // When set, the next streamResponse() continues this interrupted run instead
+  // of starting a fresh run (consumed once).
+  private pendingResumeParentRunId: string | null = null
+  private pendingResumeThreadId: string | null = null
+  private pendingResumeItems: Array<RunAgentResumeItem> | null = null
+  private activeResumeThreadId: string | null = null
+  private activeResumeRunId: string | null = null
   // Track the legacy `body` option and the canonical `forwardedProps`
   // option as separate slots so that `updateOptions({ forwardedProps })`
   // doesn't wipe a previously-set `body` (and vice versa). They are
@@ -258,6 +372,13 @@ export class ChatClient<
   private draining = false
   private sessionGenerating = false
   private readonly activeRunIds = new Set<string>()
+  /** Latched by `dispose()`; stops any late async callback starting new work. */
+  private disposed = false
+  /** Whether a view is currently watching. See `attach` / `detach`. */
+  private tailing = false
+  /** Constructor inputs `attach()` needs on every re-attach, not just the first. */
+  private readonly rejoinRunId: string | null | undefined
+  private readonly cachesMessages: boolean
   private devtoolsMounted = false
 
   private readonly callbacksRef: {
@@ -274,6 +395,12 @@ export class ChatClient<
       onConnectionStatusChange: (status: ConnectionStatus) => void
       onSessionGeneratingChange: (isGenerating: boolean) => void
       onQueueChange: (queue: Array<QueuedMessage>) => void
+      onResumeStateChange: (
+        resumeState: ChatResumeState | null,
+        pendingInterrupts: BoundInterrupts<TTools>,
+      ) => void
+      onRunIdChange: (runId: string | null) => void
+      onInterruptStateChange: (state: ChatInterruptState<TTools>) => void
       onCustomEvent: (
         eventType: string,
         data: unknown,
@@ -283,13 +410,33 @@ export class ChatClient<
   }
 
   constructor(options: ChatClientOptions<TTools, TContext>) {
-    this.uniqueId = options.id || this.generateUniqueId('chat')
     this.threadId = options.threadId || this.generateUniqueId('thread')
-    if (options.persistence) {
+    // The instance/devtools id defaults to the threadId (the chat's identity),
+    // falling back to a generated id only when neither is set. `id` overrides it
+    // only for direct ChatClient users who key storage separately from the wire
+    // thread; the framework hooks never pass it.
+    this.uniqueId = options.id || this.threadId
+    // `persistence` is `false`/omitted (ephemeral, in-memory), `true`
+    // (server-authoritative: cache nothing client-side, hydrate the thread from
+    // the server by `threadId` on mount), or a storage adapter
+    // (client-authoritative: cache the transcript plus resume pointer). Only the
+    // server-authoritative mode turns transcript caching off; that is what gates
+    // the mount hydration and keeps a client record from shadowing server history.
+    let cachesMessages = true
+    if (options.persistence === true) {
+      cachesMessages = false
+    } else if (options.persistence) {
+      // A storage adapter: keep the combined record (transcript + resume pointer)
+      // in the browser. Persistence keys on `threadId` (the conversation
+      // identity) so a reload with the same `threadId` finds the same record;
+      // `id` overrides it only when set, for apps that key storage separately
+      // from the wire thread.
+      const persistenceKey = options.id ?? this.threadId
       this.persistor = new ChatPersistor(
         options.persistence,
-        this.uniqueId,
+        persistenceKey,
         (messages) => this.processor.setMessages(messages),
+        (snapshot) => this.applyPersistedResume(snapshot),
       )
     }
     // Both `body` (deprecated) and `forwardedProps` populate the AG-UI
@@ -332,17 +479,72 @@ export class ChatClient<
         onSessionGeneratingChange:
           options.onSessionGeneratingChange || (() => {}),
         onQueueChange: options.onQueueChange || (() => {}),
+        onResumeStateChange: options.onResumeStateChange || (() => {}),
+        onRunIdChange: options.onRunIdChange || (() => {}),
+        onInterruptStateChange: options.onInterruptStateChange || (() => {}),
         onCustomEvent: options.onCustomEvent || (() => {}),
       },
     }
 
+    this.interruptManager = new InterruptManager({
+      ...(options.tools !== undefined ? { tools: options.tools } : {}),
+      submit: (submission) => this.submitInterruptBatch(submission),
+      onChange: () => this.notifyResumeStateChange(),
+    })
+
+    // In-memory rehydrate of interrupt descriptors (e.g. after a page reload
+    // when the host supplies a snapshot). Durable storage of that snapshot is
+    // a persistence-stack concern — not wired here.
+    if (options.initialResumeSnapshot) {
+      this.applyResumeSnapshot(options.initialResumeSnapshot)
+    }
+
     // Create StreamProcessor with event handlers.
     // Use conditional spreads so we don't pass `undefined` into
     // `StreamProcessorOptions` fields under `exactOptionalPropertyTypes`.
-    const persistedMessages = this.persistor?.readInitial()
-    const initialMessages = Array.isArray(persistedMessages)
-      ? persistedMessages
+    const persistedState = this.persistor?.readInitial()
+    const syncPersistedState =
+      persistedState instanceof Promise ? undefined : persistedState
+    // A persistor exists only in client-authoritative mode, so a synchronously
+    // read record's transcript is the conversation; adopt it over host
+    // `initialMessages`. (Server-authoritative mode has no persistor and instead
+    // hydrates from the server on mount, keyed by threadId.)
+    const initialMessages = syncPersistedState
+      ? syncPersistedState.messages
       : options.initialMessages
+    // A durable snapshot read synchronously from storage wins over the
+    // in-memory `initialResumeSnapshot` fallback applied above. A snapshot with
+    // pending interrupts rehydrates the interrupt UI; a bare in-flight run is
+    // rejoined after the processor is ready (see `rejoinRunId` below).
+    let rejoinRunId: string | null = null
+    if (syncPersistedState?.resume) {
+      const snapshot = syncPersistedState.resume
+      const hasPendingInterrupts =
+        Array.isArray(snapshot.pendingInterrupts) &&
+        snapshot.pendingInterrupts.length > 0
+      if (hasPendingInterrupts) {
+        // Interrupts are run-scoped state, restored from the cached snapshot.
+        this.applyResumeSnapshot(snapshot)
+      } else if (snapshot.resumeState.runId) {
+        // A bare in-flight run pointer drives a client-authoritative rejoin.
+        rejoinRunId = snapshot.resumeState.runId
+      }
+    }
+    // A host-supplied `initialResumeSnapshot` carrying a bare in-flight run is
+    // rejoined too, not just its interrupts (which `applyResumeSnapshot` above
+    // already restored). This is how a server-authoritative app hands a FRESH
+    // client an in-flight run to tail — e.g. opening the thread on a second
+    // device / browser, where hydration reports the active run id but no local
+    // resume pointer exists. A run named by the persisted store wins.
+    if (!rejoinRunId && options.initialResumeSnapshot) {
+      const snapshot = options.initialResumeSnapshot
+      const hasPendingInterrupts =
+        Array.isArray(snapshot.pendingInterrupts) &&
+        snapshot.pendingInterrupts.length > 0
+      if (!hasPendingInterrupts && snapshot.resumeState.runId) {
+        rejoinRunId = snapshot.resumeState.runId
+      }
+    }
 
     this.processor = new StreamProcessor({
       ...(options.streamProcessor?.chunkStrategy
@@ -544,12 +746,230 @@ export class ChatClient<
           data: unknown,
           context: { toolCallId?: string },
         ) => {
+          // Server-side memory middleware transports its state as a `memory:state`
+          // CUSTOM event (its own event bus never reaches this browser runtime).
+          // Route it to the devtools bridge here — the designated custom-event
+          // path — then still forward to the app's callback.
+          if (eventType === 'memory:state') {
+            this.devtoolsBridge.recordMemoryState(data)
+          }
           this.callbacksRef.current.onCustomEvent(eventType, data, context)
         },
       },
     })
 
-    this.persistor?.hydrateAsync(persistedMessages)
+    this.persistor?.hydrateAsync(persistedState)
+
+    this.rejoinRunId = rejoinRunId
+    this.cachesMessages = cachesMessages
+    // NO TAILING HERE, deliberately. Constructing a client must not open a
+    // connection.
+    //
+    // A UI framework may build a client and then throw it away — React does it on
+    // every double-invoked render, and the discarded instance is never mounted, so
+    // nothing ever calls `detach()` or `dispose()` on it. When the constructor
+    // opened a stream, that stream became unreachable and held one of the browser's
+    // ~6 connections per origin until the page reloaded. Traced with CDP: connection
+    // ids 1374/1396/1428/1437 were still held after eight thread switches, and a
+    // later request waited 210 SECONDS for a free slot (`stallMs: 210752`).
+    //
+    // Guarding inside the client cannot fix that, because the leaking instance is
+    // the one the framework discarded — every guard runs on the instance it kept.
+    // Only "idle until a view attaches" makes a thrown-away client harmless.
+    //
+    // Callers therefore drive the lifecycle: `attach()` when a view mounts,
+    // `detach()` when it unmounts. Every framework wrapper in this repo does.
+  }
+
+  /**
+   * 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 {
+    if (this.disposed || this.tailing) return
+    this.tailing = true
+
+    // Full page reload with an in-flight run persisted (synchronous store):
+    // re-attach to it off the server's delivery-durability log so the stream
+    // finishes here. Async stores rejoin from `applyPersistedResume` once the
+    // hydrate resolves. Best-effort and non-blocking.
+    if (this.rejoinRunId) {
+      this.maybeRejoinInFlight(this.rejoinRunId)
+    }
+
+    // Server-authoritative (`persistence: true`): the client caches no transcript
+    // and no run pointer — it re-hydrates from the server on mount, keyed by the
+    // stable threadId. `hydrate` returns the stored transcript plus a cursor to
+    // any in-flight run, which is tailed via the same joinRun path. This is what
+    // makes reload AND a fresh device work with zero app glue (no loader/prop).
+    if (!this.cachesMessages && this.connection.hydrate) {
+      this.hydrateFromServer()
+    }
+  }
+
+  /**
+   * 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 {
+    if (!this.tailing) return
+    // BEFORE the abort, because `resumeInFlightRun`'s cleanup reads it: a join
+    // aborted before its first chunk normally means "this run is unreachable" and
+    // clears the resume pointer. A detach is not that — the run is fine and we
+    // intend to come back — so the pointer must survive.
+    this.tailing = false
+    this.cancelInFlightStream({ setReadyStatus: true })
+    this.rejoinedRunId = null
+  }
+
+  private applyResumeSnapshot(snapshot: ChatResumeSnapshot): void {
+    const resumeState = readResumeState(snapshot)
+    if (resumeState === undefined) {
+      this.interruptManager.reset()
+      return
+    }
+    this.lastResume = resumeState
+    const pendingInterrupts = Array.isArray(snapshot.pendingInterrupts)
+      ? snapshot.pendingInterrupts
+      : []
+    if (pendingInterrupts.length === 0) {
+      this.interruptManager.reset()
+      return
+    }
+    const generation = this.interruptGeneration(pendingInterrupts)
+    this.interruptManager.hydrate({
+      threadId: resumeState.threadId,
+      interruptedRunId: resumeState.runId,
+      generation,
+      interrupts: pendingInterrupts,
+    })
+  }
+
+  /**
+   * 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(snapshot: ChatResumeSnapshot): void {
+    this.applyResumeSnapshot(snapshot)
+    const hasInterrupts =
+      Array.isArray(snapshot.pendingInterrupts) &&
+      snapshot.pendingInterrupts.length > 0
+    const runId = snapshot.resumeState?.runId
+    // A cached run pointer only reaches here through the persistor, which exists
+    // only in client-authoritative mode, so a bare in-flight run rejoins here.
+    // (Server-authoritative reconnect is resolved from the server by threadId in
+    // `hydrateFromServer`.)
+    if (!hasInterrupts && runId) {
+      this.maybeRejoinInFlight(runId)
+    }
+  }
+
+  /**
+   * 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(runId: string): void {
+    if (!this.connection.joinRun) return
+    // A client with no view attached must never open a connection. `tailing` is
+    // the load-bearing half: a view switch calls `detach()`, NOT `dispose()`, and
+    // an in-flight hydration resolves a moment later and lands right here — so
+    // guarding only on `disposed` let every switch open a fresh tail that nothing
+    // would ever abort. Measured with CDP: connection ids 1366/1397/1429/1460 were
+    // still held after eight switches, and a later request waited 97 SECONDS for a
+    // slot (`stallMs: 97691`).
+    if (this.disposed || !this.tailing) return
+    if (this.rejoinedRunId === runId) return
+    // A fresh send (or an already-running rejoin) owns the client; don't stomp it.
+    if (this.isLoading || this.abortController) return
+    this.rejoinedRunId = runId
+    this.resumeInFlightRun(runId)
+  }
+
+  /**
+   * 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(): void {
+    const hydrate = this.connection.hydrate
+    if (!hydrate) return
+    if (this.isLoading || this.abortController) return
+    if (this.disposed) return
+    void (async () => {
+      let result: ChatHydrationResult
+      try {
+        result = await hydrate(this.threadId)
+      } catch {
+        return
+      }
+      // NO VIEW IS WATCHING ANY MORE (it unmounted while this fetch was in
+      // flight). Applying anything now is pointless, and one thing is actively
+      // harmful: the branch below calls `maybeRejoinInFlight`, which opens a TAIL.
+      // A tail started here belongs to a view that has gone, so nothing will ever
+      // abort it, and a browser allows only ~6 connections per origin — so a
+      // handful of switches starve the page and every later request queues.
+      //
+      // `!this.tailing` is the case that actually bites: a switch calls `detach()`,
+      // not `dispose()`, so a `disposed`-only check let the leak straight through.
+      if (this.disposed || !this.tailing) return
+      // A send may have started while the fetch was in flight — don't stomp it.
+      if (this.isLoading || this.abortController) return
+      if (result.messages.length > 0) {
+        this.processor.setMessages(result.messages)
+      }
+      if (result.interrupts && result.interrupts.pending.length > 0) {
+        // Pending interrupt = the thread is paused awaiting a human decision, so
+        // there is nothing to tail (no chunks stream until it resolves). Restore
+        // the approval/wait from the SERVER — identical to reconstructing it from
+        // a resume snapshot — so the reload re-prompts the decision and the resume
+        // targets the run it paused. This is checked BEFORE `activeRun` on
+        // purpose: a run that just paused can momentarily still read as `running`
+        // on the server, so a racing hydrate reports both an `activeRun` cursor
+        // AND the pending interrupt. Tailing that "active" run would drop the
+        // approval card (and hang on a stream that never comes), so the interrupt
+        // always wins.
+        this.applyResumeSnapshot({
+          resumeState: {
+            threadId: this.threadId,
+            runId: result.interrupts.runId,
+          },
+          pendingInterrupts: result.interrupts.pending,
+        })
+      } else if (result.activeRun?.runId) {
+        this.maybeRejoinInFlight(result.activeRun.runId)
+      }
+    })()
   }
 
   mountDevtools(): void {
@@ -568,22 +988,52 @@ export class ChatClient<
    */
   private drainIgnoredRunlessChunk(chunk: StreamChunk): void {
     if (chunk.type !== 'RUN_ERROR') return
-    const runId = this.persistor?.takeRunlessRunId()
+    const runId = this.clearedStreamTracker.takeRunlessRunId()
     if (!runId) return
     this.activeRunIds.delete(runId)
     this.setSessionGenerating(this.activeRunIds.size > 0)
     this.resolveProcessing()
   }
 
+  private retireIgnoredClearedTerminalChunk(chunk: StreamChunk): void {
+    if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') return
+    const runId =
+      getChunkRunId(chunk) ?? this.clearedStreamTracker.takeRunlessRunId()
+    if (!runId) return
+    this.activeRunIds.delete(runId)
+    this.setSessionGenerating(this.activeRunIds.size > 0)
+    if (!getChunkRunId(chunk)) {
+      this.resolveProcessing()
+    }
+  }
+
   private updateRunLifecycle(
     chunk: StreamChunk,
     options?: { resolveProcessing?: boolean },
   ): void {
     if (chunk.type === 'RUN_STARTED') {
       const chunkRunId = getChunkRunId(chunk) ?? chunk.runId
+      this.activeResumeThreadId =
+        'threadId' in chunk && typeof chunk.threadId === 'string'
+          ? chunk.threadId
+          : this.activeResumeThreadId
+      this.activeResumeRunId = chunkRunId
       this.activeRunIds.add(chunkRunId)
-      this.persistor?.onRunStarted(chunkRunId)
+      this.clearedStreamTracker.onRunStarted(chunkRunId)
       this.setSessionGenerating(true)
+      // Persist a live-run resume snapshot so a full page reload can rejoin this
+      // in-flight run via joinRun. Only a persistor writes it, and a persistor
+      // exists only in client-authoritative mode; server-authoritative reconnect
+      // is resolved from the server by threadId in `hydrateFromServer`, so no
+      // client-cached run pointer (which goes stale the moment a turn spans a
+      // second run) is ever written. Interrupt/terminal handling overwrites or
+      // clears it in observeInterruptState.
+      if (this.persistor && this.connection.joinRun && !this.lastResume) {
+        this.persistResumeSnapshot({
+          threadId: this.activeResumeThreadId ?? this.threadId,
+          runId: chunkRunId,
+        })
+      }
       return
     }
 
@@ -594,11 +1044,11 @@ export class ChatClient<
     const runId = getChunkRunId(chunk)
     if (runId) {
       this.activeRunIds.delete(runId)
-      this.persistor?.onRunSettled(runId)
+      this.clearedStreamTracker.onRunSettled(runId)
     } else if (chunk.type === 'RUN_ERROR') {
       // RUN_ERROR without runId is a session-level error; clear all runs.
       this.activeRunIds.clear()
-      this.persistor?.onSessionRunError()
+      this.clearedStreamTracker.onSessionRunError()
     }
     this.setSessionGenerating(this.activeRunIds.size > 0)
     if (options?.resolveProcessing !== false) {
@@ -606,6 +1056,260 @@ export class ChatClient<
     }
   }
 
+  /**
+   * 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(chunk: StreamChunk): void {
+    if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') {
+      return
+    }
+
+    if (this.activeInterruptSubmission && chunk.type === 'RUN_ERROR') {
+      return
+    }
+    const runId = getChunkRunId(chunk)
+    const threadId =
+      'threadId' in chunk && typeof chunk.threadId === 'string'
+        ? chunk.threadId
+        : this.activeResumeThreadId
+
+    if (chunk.type === 'RUN_FINISHED' && chunk.outcome?.type === 'interrupt') {
+      // Track the REQUEST run id (what the client sent) so a resume targets the
+      // same run even when provider events carry their own run id.
+      const interruptedRunId =
+        this.currentRunId ?? runId ?? this.activeResumeRunId ?? ''
+      this.lastResume = {
+        threadId: threadId ?? this.threadId,
+        runId: interruptedRunId,
+      }
+      this.interruptManager.hydrate({
+        threadId: this.lastResume.threadId,
+        interruptedRunId,
+        generation: this.interruptGeneration(chunk.outcome.interrupts),
+        interrupts: chunk.outcome.interrupts,
+      })
+      return
+    }
+
+    const isRunlessSessionError = chunk.type === 'RUN_ERROR' && !runId
+    const isTrackedRunTerminal = Boolean(
+      runId && this.lastResume?.runId === runId,
+    )
+    const isCurrentRunTerminal = Boolean(
+      (runId && this.currentRunId === runId) ||
+      (this.currentRunId && this.lastResume?.runId === this.currentRunId),
+    )
+    // Provider adapters sometimes stamp a different run id on continuation
+    // events than the client-generated request id. RUN_STARTED updates
+    // `activeResumeRunId`, so match that too.
+    const isActiveStreamRunTerminal = Boolean(
+      this.isLoading &&
+      runId &&
+      (runId === this.activeResumeRunId || runId === this.currentRunId),
+    )
+    const isCurrentStreamTerminal =
+      this.isLoading && chunk.type === 'RUN_FINISHED' && !runId
+    // A resume batch that finishes successfully (or with a non-interrupt
+    // terminal) must always clear pending interrupts — even when the provider
+    // run id does not correlate. Otherwise Approve works once but the UI
+    // keeps showing a stale prompt and blocks follow-up turns.
+    const isActiveInterruptSubmissionTerminal = Boolean(
+      this.activeInterruptSubmission &&
+      this.isLoading &&
+      chunk.type === 'RUN_FINISHED' &&
+      chunk.outcome?.type !== 'interrupt',
+    )
+    if (
+      isRunlessSessionError ||
+      isTrackedRunTerminal ||
+      isCurrentRunTerminal ||
+      isActiveStreamRunTerminal ||
+      isCurrentStreamTerminal ||
+      isActiveInterruptSubmissionTerminal
+    ) {
+      this.lastResume = null
+      // Run settled without an interrupt: drop the durable resume snapshot so a
+      // later reload does not try to rejoin a finished run.
+      this.persistor?.persistResumeSnapshot(null)
+      this.interruptManager.reset()
+      return
+    }
+    this.notifyResumeStateChange()
+  }
+
+  /**
+   * 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 {
+    return this.lastResume ? { ...this.lastResume } : 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 {
+    return this.currentRunId
+  }
+
+  private setCurrentRunId(runId: string | null): void {
+    if (this.currentRunId === runId) return
+    this.currentRunId = runId
+    this.callbacksRef.current.onRunIdChange(runId)
+  }
+
+  getInterruptState(): ChatInterruptState<TTools> {
+    return this.interruptManager.getState()
+  }
+
+  getInterrupts(): BoundInterrupts<TTools> {
+    return this.interruptManager.getInterrupts()
+  }
+
+  /** @deprecated Use getInterrupts(). */
+  getPendingInterrupts(): BoundInterrupts<TTools> {
+    return this.interruptManager.getInterrupts()
+  }
+
+  resolveInterrupts(approved: boolean): void
+  resolveInterrupts(
+    resolver: (interrupt: ChatInterrupt<TTools>) => undefined,
+  ): void
+  resolveInterrupts(
+    resolution: boolean | ((interrupt: ChatInterrupt<TTools>) => undefined),
+  ): void {
+    // Branch so TypeScript can select the InterruptManager.resolve overloads.
+    if (typeof resolution === 'boolean') {
+      this.interruptManager.resolve(resolution)
+      return
+    }
+    this.interruptManager.resolve(resolution)
+  }
+
+  cancelInterrupts(): void {
+    this.interruptManager.cancel()
+  }
+
+  retryInterrupts(): void {
+    this.interruptManager.retry()
+  }
+
+  /** Unsafe low-level resume escape hatch. Prefer bound interrupt methods. */
+  resumeInterruptsUnsafe(
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ): Promise<boolean> {
+    const target = state ?? this.lastResume
+    if (!target) return Promise.resolve(false)
+    // Auto-executed client tools resolve during the parent stream's
+    // `pendingToolExecutions` wait — while `isLoading` is still true.
+    // Defer the child continuation until that stream settles so we do not
+    // race the parent cleanup or return a false "could not start" failure.
+    if (this.isLoading) {
+      return new Promise<boolean>((resolve, reject) => {
+        this.queuePostStreamAction(async () => {
+          try {
+            resolve(await this.resumeInterruptsUnsafe(resume, target))
+          } catch (error) {
+            reject(error)
+          }
+        })
+      })
+    }
+    this.pendingResumeThreadId = target.threadId
+    this.pendingResumeParentRunId = target.runId
+    this.pendingResumeItems = [...resume]
+    return this.streamResponse()
+  }
+
+  /** @deprecated Use bound interrupt methods or resumeInterruptsUnsafe(). */
+  resumeInterrupts(
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ): Promise<boolean> {
+    return this.resumeInterruptsUnsafe(resume, state)
+  }
+
+  private async submitInterruptBatch(
+    submission: InterruptManagerSubmission,
+  ): Promise<void> {
+    this.activeInterruptSubmission = submission
+    this.interruptSubmissionFailure = undefined
+    // Reflect approval decisions in the local message tree immediately so a
+    // follow-up turn does not re-serialize tool-calls still stuck in
+    // `approval-requested` (issue #532).
+    for (const resolution of submission.resolutions) {
+      const approved = readApprovalApproved(resolution.payload)
+      if (approved === undefined) continue
+      const approvalId = resolution.interruptId
+      this.processor.addToolApprovalResponse(approvalId, approved)
+    }
+    const resumed = await this.resumeInterruptsUnsafe(
+      [...submission.resolutions],
+      {
+        threadId: submission.threadId,
+        runId: submission.interruptedRunId,
+      },
+    ).finally(() => {
+      this.activeInterruptSubmission = undefined
+    })
+    const failure = this.takeInterruptSubmissionFailure()
+    if (failure !== undefined) {
+      throw { errors: failure.errors }
+    }
+    if (!resumed) {
+      throw new Error('Interrupt continuation could not be started.')
+    }
+    // Belt-and-suspenders: if the continuation stream finished successfully
+    // but correlation failed to clear resume state, drop it now so the next
+    // user turn is not blocked by a stale interrupt prompt.
+    if (this.lastResume?.runId === submission.interruptedRunId) {
+      this.lastResume = null
+      this.interruptManager.reset()
+    }
+  }
+
+  private takeInterruptSubmissionFailure():
+    | { errors: ReadonlyArray<InterruptSubmissionError> }
+    | undefined {
+    const failure = this.interruptSubmissionFailure
+    this.interruptSubmissionFailure = undefined
+    return failure
+  }
+
+  private interruptGeneration(
+    interrupts: ReadonlyArray<ChatPendingInterrupt>,
+  ): number {
+    let generation: number | undefined
+    for (const interrupt of interrupts) {
+      const candidate: unknown =
+        interrupt.metadata?.['tanstack:interruptBinding']
+      if (
+        candidate === null ||
+        typeof candidate !== 'object' ||
+        !('generation' in candidate) ||
+        typeof candidate.generation !== 'number' ||
+        !Number.isInteger(candidate.generation) ||
+        candidate.generation < 0
+      ) {
+        return 0
+      }
+      if (generation !== undefined && generation !== candidate.generation) {
+        return 0
+      }
+      generation = candidate.generation
+    }
+    return generation ?? 0
+  }
+
   private generateUniqueId(prefix: string): string {
     return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
   }
@@ -641,9 +1345,47 @@ export class ChatClient<
     this.devtoolsBridge.emitSnapshot()
   }
 
-  private resetSessionGenerating(): void {
+  private notifyResumeStateChange(): void {
+    const resumeState = this.getResumeState()
+    // Persist (or clear) the durable resume snapshot so a full page reload can
+    // rehydrate pending interrupts and rejoin the run. Folded into the same
+    // persistence adapter that stores messages (one record per chat).
+    this.persistResumeSnapshot(resumeState)
+    this.callbacksRef.current.onResumeStateChange(
+      resumeState,
+      this.interruptManager.getInterrupts(),
+    )
+    this.callbacksRef.current.onInterruptStateChange(
+      this.interruptManager.getState(),
+    )
+  }
+
+  /**
+   * Build the durable resume snapshot from the current resume state + pending
+   * interrupt descriptors and hand it to the persistor (null clears it).
+   */
+  private persistResumeSnapshot(resumeState: ChatResumeState | null): void {
+    if (!this.persistor) return
+    if (!resumeState) {
+      this.persistor.persistResumeSnapshot(null)
+      return
+    }
+    const descriptors = this.interruptManager.getDescriptors()
+    this.persistor.persistResumeSnapshot({
+      resumeState,
+      ...(descriptors.length > 0
+        ? { pendingInterrupts: [...descriptors] }
+        : {}),
+    })
+  }
+
+  private resetSessionGenerating(options?: {
+    preserveClearedStreamTracking?: boolean
+  }): void {
     this.activeRunIds.clear()
-    this.persistor?.resetIgnored()
+    if (!options?.preserveClearedStreamTracking) {
+      this.clearedStreamTracker.resetActiveRuns()
+    }
     this.setSessionGenerating(false)
   }
 
@@ -793,33 +1535,204 @@ export class ChatClient<
     const stream = this.connection.subscribe(signal)
     for await (const chunk of stream) {
       if (signal.aborted) break
-      if (this.connectionStatus === 'connecting') {
-        this.setConnectionStatus('connected')
-      }
-      const shouldIgnore = this.persistor?.shouldIgnoreChunk(chunk) ?? false
-      if (shouldIgnore) {
-        if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
-          if (getChunkRunId(chunk)) {
-            this.updateRunLifecycle(chunk, { resolveProcessing: false })
-          } else {
-            this.drainIgnoredRunlessChunk(chunk)
+      await this.processIncomingChunk(chunk)
+    }
+  }
+
+  /**
+   * 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(runId: string): void {
+    const joinRun = this.connection.joinRun
+    if (!joinRun) return
+    const controller = new AbortController()
+    this.abortController = controller
+    this.setCurrentRunId(runId)
+    // Record the resume state in-memory BEFORE replaying. Otherwise the
+    // replayed `RUN_STARTED` (which carries the PROVIDER run id, not the
+    // client/durability-log run id the pointer is keyed by) trips the
+    // `!this.lastResume` guard in `updateRunLifecycle` and rewrites the
+    // persisted pointer with the provider id — so a SECOND reload would
+    // `joinRun` an id the log isn't keyed by and never re-attach.
+    this.lastResume = { threadId: this.threadId, runId }
+    this.setIsLoading(true)
+    this.setStatus('streaming')
+    void (async () => {
+      let rebuilt = false
+      let attached = false
+      // Whether the join FAILED (a thrown non-abort error before any chunk), as
+      // opposed to merely not delivering in time. Only a failure proves the
+      // pointer dead — see the `finally`.
+      let refused = false
+      const connectTimer = setTimeout(() => {
+        if (!attached) controller.abort()
+      }, REJOIN_CONNECT_DEADLINE_MS)
+      try {
+        for await (const chunk of joinRun(runId, controller.signal)) {
+          if (controller.signal.aborted) break
+          if (!attached) {
+            attached = true
+            clearTimeout(connectTimer)
           }
+          if (!rebuilt && REJOIN_REBUILD_TRIGGERS.has(chunk.type)) {
+            rebuilt = true
+            this.dropTrailingInFlightAssistant()
+          }
+          await this.processIncomingChunk(chunk, { defer: false })
+        }
+      } catch (error) {
+        // Pre-attach failures (unknown/evicted run, connect deadline abort)
+        // stay soft: keep the restored transcript. Post-attach transport/parser
+        // failures are real stream errors and must surface so the UI is not
+        // left truncated and silent.
+        const isAbort =
+          error instanceof Error &&
+          (error.name === 'AbortError' || error.name === 'TimeoutError')
+        if (!attached && !isAbort) refused = true
+        if (attached && !isAbort) {
+          this.reportStreamError(
+            error instanceof Error ? error : new Error(String(error)),
+          )
+        }
+      } finally {
+        clearTimeout(connectTimer)
+        if (!attached && refused && this.tailing && !this.disposed) {
+          // The server REFUSED the join (unknown / evicted run): the pointer is
+          // dead. Clear it so it does not retry and re-pin the UI on the next
+          // load. The server's persisted transcript is still loaded.
+          //
+          // A connect-deadline abort (or an external abort) deliberately does
+          // NOT clear it: the run may simply not have produced yet — a durable
+          // run whose middleware is still booting a sandbox emits nothing for
+          // a while — and clearing on a timeout would permanently orphan a run
+          // that is still going. The pointer survives for the next load, which
+          // costs that load one more bounded connect attempt.
+          //
+          // `tailing`/`disposed` guard the same pointer from the other side: a
+          // DETACH aborts before the first chunk exactly like an unreachable run
+          // does, and a refusal that lands after the view is gone belongs to
+          // nobody. `refused` already spares the timeout case; these two spare
+          // the "no view is watching any more" case, so the pointer only ever
+          // dies for a client that is still looking at the run.
+          this.lastResume = null
+          this.persistor?.persistResumeSnapshot(null)
+        }
+        if (this.abortController === controller) {
+          this.abortController = null
+          this.setIsLoading(false)
+          if (this.status === 'streaming') this.setStatus('ready')
+        }
+      }
+    })()
+  }
+
+  /**
+   * 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(): void {
+    const messages = this.processor.getMessages()
+    const last = messages[messages.length - 1]
+    if (last && last.role === 'assistant') {
+      this.processor.setMessages(messages.slice(0, -1))
+    }
+  }
+
+  private async processIncomingChunk(
+    chunk: StreamChunk,
+    options?: { defer?: boolean },
+  ): Promise<void> {
+    if (
+      chunk.type === 'RUN_ERROR' &&
+      this.isActiveInterruptSubmissionFailure(chunk)
+    ) {
+      this.interruptSubmissionFailure = {
+        errors: chunk['tanstack:interruptErrors'] ?? [],
+      }
+    }
+    if (this.connectionStatus === 'connecting') {
+      this.setConnectionStatus('connected')
+    }
+    const shouldIgnore = this.clearedStreamTracker.shouldIgnoreChunk(chunk)
+    if (shouldIgnore) {
+      if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
+        if (getChunkRunId(chunk)) {
+          this.updateRunLifecycle(chunk, { resolveProcessing: false })
+        } else {
+          this.drainIgnoredRunlessChunk(chunk)
         }
-        continue
+        this.retireIgnoredClearedTerminalChunk(chunk)
+        this.resolveJoinedRun(chunk)
       }
-      this.callbacksRef.current.onChunk(chunk)
-      this.devtoolsBridge.observeChunk(chunk)
-      this.processor.processChunk(chunk)
-      // Run lifecycle (active-run tracking, session-generating state, and
-      // processing resolution for RUN_FINISHED / RUN_ERROR) is handled in a
-      // single place so the ignored-chunk path above and this path can't
-      // diverge. RUN_ERROR carries its runId via the AG-UI passthrough so a
-      // per-run error only clears that run, while a runId-less RUN_ERROR is
-      // treated as a session-level error that clears every active run.
-      this.updateRunLifecycle(chunk)
-      // Yield control back to event loop for UI updates
+      return
+    }
+    this.callbacksRef.current.onChunk(chunk)
+    this.devtoolsBridge.observeChunk(chunk)
+    this.processor.processChunk(chunk)
+    this.updateRunLifecycle(chunk)
+    this.observeInterruptState(chunk)
+    // The live path yields a macrotask between chunks so React can paint each
+    // delta progressively. A resume replay passes `defer: false` to skip it, so
+    // the buffered backlog applies in one batch (instant catch-up) instead of
+    // re-typing the whole reply.
+    if (options?.defer !== false) {
       await new Promise((resolve) => setTimeout(resolve, 0))
     }
+    this.resolveJoinedRun(chunk)
+  }
+
+  private isActiveInterruptSubmissionFailure(
+    chunk: Extract<StreamChunk, { type: 'RUN_ERROR' }>,
+  ): boolean {
+    const submission = this.activeInterruptSubmission
+    const errors = chunk['tanstack:interruptErrors']
+    if (!submission || !errors || errors.length === 0) return false
+    const runId = getChunkRunId(chunk)
+    if (runId !== undefined && runId !== this.currentRunId) return false
+    if (
+      typeof chunk.threadId === 'string' &&
+      chunk.threadId !== submission.threadId
+    ) {
+      return false
+    }
+    return errors.every(
+      (error) =>
+        error.threadId === submission.threadId &&
+        error.interruptedRunId === submission.interruptedRunId &&
+        error.generation === submission.generation,
+    )
+  }
+
+  private resolveJoinedRun(chunk: StreamChunk): void {
+    if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') return
+    const runId = getChunkRunId(chunk)
+    if (runId === undefined) return
+    const resolve = this.joinedRunWaiters.get(runId)
+    if (resolve === undefined) return
+    this.joinedRunWaiters.delete(runId)
+    resolve()
   }
 
   /**
@@ -890,7 +1803,7 @@ export class ChatClient<
    *     ],
    *     id: 'custom-message-id'
    *   },
-   *   { model: 'gpt-4-audio' }
+   *   { model: 'gpt-5.5' }
    * )
    * ```
    */
@@ -904,6 +1817,11 @@ export class ChatClient<
     if (emptyMessage) {
       return
     }
+    if (this.hasBlockingInterrupts()) {
+      throw new Error(
+        'ChatClient: cannot send normal input while pending interrupts exist. Use resumeInterrupts() instead.',
+      )
+    }
 
     if (this.isSendBusy()) {
       const { action, id } = this.decideWhenBusy(content, sendOptions)
@@ -934,6 +1852,30 @@ export class ChatClient<
     }
   }
 
+  /**
+   * 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(): boolean {
+    if (!this.lastResume && !this.activeInterruptSubmission) {
+      return false
+    }
+    if (this.activeInterruptSubmission) {
+      return true
+    }
+    return this.interruptManager
+      .getInterrupts()
+      .some(
+        (item) =>
+          item.status === 'pending' ||
+          item.status === 'validating' ||
+          item.status === 'error' ||
+          item.status === 'staged',
+      )
+  }
+
   /** True while a stream is active, a send is claiming the client, or the queue is draining. */
   private isSendBusy(): boolean {
     return this.isLoading || this.sendInFlight || this.messageQueueDraining
@@ -1043,6 +1985,11 @@ export class ChatClient<
    */
   async append(message: UIMessage | ModelMessage): Promise<void> {
     this.mountDevtools()
+    if (this.hasBlockingInterrupts()) {
+      throw new Error(
+        'ChatClient: cannot append normal input while pending interrupts exist. Use resumeInterrupts() instead.',
+      )
+    }
     // Normalize the message to ensure it has id and createdAt
     const normalizedMessage = normalizeToUIMessage(message, generateMessageId)
 
@@ -1085,8 +2032,18 @@ export class ChatClient<
 
     // Track generation so a superseded stream's cleanup doesn't clobber the new one
     const generation = ++this.streamGeneration
+    // Native interrupt continuation is a fresh child run. The interrupted run
+    // is carried as parentRunId and the complete resolution batch as resume.
+    const resumeThreadId = this.pendingResumeThreadId
+    const resumeParentRunId = this.pendingResumeParentRunId
+    const resumeItems = this.pendingResumeItems
+    this.pendingResumeThreadId = null
+    this.pendingResumeParentRunId = null
+    this.pendingResumeItems = null
     const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
-    this.currentRunId = runId
+    this.setCurrentRunId(runId)
+    this.activeResumeThreadId = resumeThreadId ?? this.threadId
+    this.activeResumeRunId = runId
 
     this.setIsLoading(true)
     // Hand off from deliverClaim to isLoading so nested drain can call
@@ -1170,8 +2127,11 @@ export class ChatClient<
       // JSON Schema; sending a Standard Schema instance directly would
       // serialize to an unusable shape.
       const runContext = {
-        threadId: this.threadId,
+        threadId: resumeThreadId ?? this.threadId,
         runId,
+        ...(resumeParentRunId !== null
+          ? { parentRunId: resumeParentRunId }
+          : {}),
         clientTools: Array.from(clientTools.values()).map((t) => ({
           name: t.name,
           description: t.description,
@@ -1180,8 +2140,9 @@ export class ChatClient<
             : { type: 'object' },
         })),
         forwardedProps: { ...mergedBody },
+        ...(resumeItems ? { resume: resumeItems } : {}),
       }
-      this.devtoolsBridge.beginRun(runContext.runId, this.threadId)
+      this.devtoolsBridge.beginRun(runContext.runId, runContext.threadId)
       activeDevtoolsRunId = runContext.runId
       this.devtoolsBridge.emitRunLifecycle(
         'run:created',
@@ -1198,6 +2159,11 @@ export class ChatClient<
       // Send through normalized connection (pushes chunks to subscription queue)
       await this.connection.send(messages, mergedBody, signal, runContext)
 
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- mutated asynchronously during await
+      if (generation !== this.streamGeneration || signal.aborted) {
+        return false
+      }
+
       // Wait for subscription loop to finish processing all chunks
       await processingComplete
 
@@ -1264,7 +2230,7 @@ export class ChatClient<
         this.currentStreamId = null
         this.devtoolsBridge.setCurrentStreamId(null)
         this.currentMessageId = null
-        this.currentRunId = null
+        this.setCurrentRunId(null)
         this.activeClientTools = null
         this.activeContext = undefined
         this.abortController = null
@@ -1424,25 +2390,30 @@ export class ChatClient<
    * Clear all messages
    */
   clear(): void {
-    if (this.persistor) {
-      this.persistor.snapshotClear({
-        messages: this.processor.getMessages(),
-        activeRunIds: this.activeRunIds,
-        currentRunId: this.currentRunId,
-      })
-      if (this.isLoading) {
-        this.cancelInFlightStream({ setReadyStatus: true })
-        this.resetSessionGenerating()
-      } else if (this.activeRunIds.size > 0) {
-        this.resetSessionGenerating()
-      }
-      // Suppress persisting the empty snapshot that clearMessages emits, then
-      // remove the stored conversation outright.
-      this.persistor.beginClear()
+    const hadLocalStream = this.abortController !== null
+    this.clearedStreamTracker.snapshotClear({
+      messages: this.processor.getMessages(),
+      activeRunIds: this.activeRunIds,
+      currentRunId: this.currentRunId,
+    })
+    // Always cancel in-flight work so clear works without message persistence.
+    if (this.isLoading || hadLocalStream) {
+      this.cancelInFlightStream({ setReadyStatus: true })
+      this.resetSessionGenerating({ preserveClearedStreamTracking: true })
+    } else if (this.activeRunIds.size > 0) {
+      this.resetSessionGenerating({ preserveClearedStreamTracking: true })
     }
+    // Suppress persisting the empty snapshot that clearMessages emits, then
+    // remove the stored conversation outright.
+    this.persistor?.beginClear()
     this.processor.clearMessages()
     this.discardPendingSends()
     this.persistor?.remove()
+    this.lastResume = null
+    this.interruptManager.reset()
+    this.pendingResumeThreadId = null
+    this.pendingResumeParentRunId = null
+    this.pendingResumeItems = null
     this.setError(undefined)
     this.events.messagesCleared()
   }
@@ -1484,9 +2455,8 @@ export class ChatClient<
       context,
     )
 
-    // Forward an error message only for output-error results (with a fallback so
-    // a message-less `throw new Error()` still reaches the terminal 'error'
-    // state); a stray errorText on a successful result must not signal an error.
+    // Always update local message state so the tool-call part is terminal in
+    // the UI even when the AG-UI interrupt path owns server continuation.
     this.processor.addToolResult(
       result.toolCallId,
       result.output,
@@ -1494,6 +2464,19 @@ export class ChatClient<
         ? result.errorText || 'Tool execution failed'
         : undefined,
     )
+    this.devtoolsBridge.emitSnapshot()
+
+    const resolvedViaInterrupt = this.interruptManager.resolveClientToolOutput(
+      result.toolCallId,
+      result.state === 'output-error'
+        ? { error: result.errorText || 'Tool execution failed' }
+        : result.output,
+    )
+    if (resolvedViaInterrupt) {
+      // Interrupt manager stages/submits the resume batch (deferred until the
+      // parent stream settles when still loading). Skip legacy continuation.
+      return
+    }
 
     // If stream is in progress, queue continuation check for after it ends
     if (this.isLoading) {
@@ -1522,6 +2505,21 @@ export class ChatClient<
     id: string // approval.id, not toolCallId
     approved: boolean
   }): Promise<void> {
+    // Reflect the decision on the tool-call part so approval UIs that render
+    // from `part.state` (the deprecated pre-interrupt pattern) clear the prompt
+    // and show the response. The bound interrupt resolution below drives the
+    // actual continuation; this keeps the legacy message-state surface in sync.
+    this.processor.addToolApprovalResponse(response.id, response.approved)
+    this.devtoolsBridge.emitSnapshot()
+
+    if (
+      this.interruptManager.resolveToolApprovalDecision(
+        response.id,
+        response.approved,
+      )
+    ) {
+      return
+    }
     // Find the tool call ID from the approval ID
     const messages = this.processor.getMessages()
     let foundToolCallId: string | undefined
@@ -1866,6 +2864,7 @@ export class ChatClient<
       this.context = options.context
     }
     if (options.tools !== undefined) {
+      this.interruptManager.updateTools(options.tools)
       this.clientToolsRef.current = new Map()
       for (const tool of options.tools) {
         this.clientToolsRef.current.set(tool.name, tool)
@@ -1902,12 +2901,31 @@ export class ChatClient<
     if (options.onQueueChange !== undefined) {
       this.callbacksRef.current.onQueueChange = options.onQueueChange
     }
+    if (options.onResumeStateChange !== undefined) {
+      this.callbacksRef.current.onResumeStateChange =
+        options.onResumeStateChange
+    }
+    if (options.onRunIdChange !== undefined) {
+      this.callbacksRef.current.onRunIdChange = options.onRunIdChange
+    }
+    if (options.onInterruptStateChange !== undefined) {
+      this.callbacksRef.current.onInterruptStateChange =
+        options.onInterruptStateChange
+    }
     if (options.onCustomEvent !== undefined) {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent
     }
   }
 
   dispose(): void {
+    // FIRST, and latched: everything below is teardown, and an async callback that
+    // lands mid-teardown must not start new work. In particular a hydration fetch
+    // that resolves after this point must not open a tail — see `hydrateFromServer`.
+    this.disposed = true
+    // `unsubscribe()` below already aborts the in-flight stream (it calls
+    // `cancelInFlightStream({ abortSubscription: true })`), so disposal does drop
+    // an open tail. Verified by mutation: removing an extra abort here changes
+    // nothing, because unsubscribe covers it.
     this.unsubscribe()
     this.devtoolsBridge.dispose()
     this.devtoolsMounted = false