@tanstack/ai-client 0.22.1 → 0.23.0

package/dist/esm/client-persistor.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-persistor.js","sources":["../../src/client-persistor.ts"],"sourcesContent":["import { getChunkRunId } from './connection-adapters'\nimport type { StreamChunk } from '@tanstack/ai/client'\nimport type { ChatClientPersistence, UIMessage } from './types'\n\n// `StreamChunk` is a discriminated union; `toolCallId` / `messageId` /\n// `parentMessageId` exist on only some members. Narrow with `in` (matching\n// `getChunkRunId`) instead of asserting a shape, so the field's real type is\n// preserved and a protocol rename can't be read past silently.\nfunction getChunkToolCallId(chunk: StreamChunk): string | undefined {\n  return 'toolCallId' in chunk && typeof chunk.toolCallId === 'string'\n    ? chunk.toolCallId\n    : undefined\n}\n\nfunction getChunkMessageId(chunk: StreamChunk): string | undefined {\n  return 'messageId' in chunk && typeof chunk.messageId === 'string'\n    ? chunk.messageId\n    : undefined\n}\n\nfunction getChunkParentMessageId(chunk: StreamChunk): string | undefined {\n  return 'parentMessageId' in chunk && typeof chunk.parentMessageId === 'string'\n    ? chunk.parentMessageId\n    : undefined\n}\n\n/**\n * Encapsulates everything persistence-related for `ChatClient` so the client\n * itself stays focused on streaming and message state.\n *\n * Two responsibilities live here:\n *\n * 1. **Storage orchestration** — hydrate from `getItem(id)` on creation, save to\n *    `setItem(id, messages)` on every change through an ordered write queue, and\n *    `removeItem(id)` on clear. A generation counter discards stale writes when a\n *    removal or a newer conversation supersedes an in-flight async operation.\n * 2. **Clear-during-stream suppression** — when a conversation is cleared while a\n *    stream is still producing, late chunks for the cleared run(s) must not\n *    repopulate the now-empty state. The persistor tracks the cleared ids and\n *    decides, per chunk, whether the client should ignore it.\n *\n * All adapter calls are best-effort: a throwing or rejecting adapter is swallowed\n * so storage problems never break the chat.\n */\nexport class ChatPersistor {\n  // --- storage queue state ---\n  private skipNextPersist = false\n  private generation = 0\n  private queue: Promise<void> = Promise.resolve()\n  private queuePending = false\n  // Bumped on every message change; lets an in-flight async hydration detect\n  // that the message list moved on and avoid clobbering it.\n  private messagesGeneration = 0\n\n  // --- clear-during-stream suppression state ---\n  private readonly clearedMessageIds = new Set<string>()\n  private readonly clearedRunIds = new Set<string>()\n  private readonly ignoredActiveRunIds = new Set<string>()\n  private readonly clearedToolCallIds = new Set<string>()\n  private currentRunlessRunId: string | null = null\n\n  constructor(\n    private readonly adapter: ChatClientPersistence,\n    private readonly id: string,\n    private readonly applyMessages: (messages: Array<UIMessage>) => void,\n  ) {}\n\n  // ---------------------------------------------------------------------------\n  // Storage orchestration\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Synchronously read the persisted messages for constructor-time hydration.\n   * Returns the raw `getItem` result (which may be a promise for async stores).\n   */\n  readInitial():\n    | Array<UIMessage>\n    | null\n    | undefined\n    | Promise<Array<UIMessage> | null | undefined> {\n    try {\n      return this.adapter.getItem(this.id)\n    } catch {\n      return undefined\n    }\n  }\n\n  /**\n   * Apply messages from an async `getItem` once it resolves, unless the message\n   * list has already changed since hydration began.\n   */\n  hydrateAsync(\n    persistedMessages:\n      | Array<UIMessage>\n      | null\n      | undefined\n      | Promise<Array<UIMessage> | null | undefined>,\n  ): void {\n    if (!(persistedMessages instanceof Promise)) {\n      return\n    }\n\n    const hydrationGeneration = this.messagesGeneration\n    persistedMessages\n      .then((messages) => {\n        if (\n          Array.isArray(messages) &&\n          this.messagesGeneration === hydrationGeneration\n        ) {\n          this.applyMessages(messages)\n        }\n      })\n      .catch(() => {\n        // Persistence adapters are best-effort and must not break chat setup.\n      })\n  }\n\n  /**\n   * Record a message-list change and queue a `setItem` write for it. Skips a\n   * single write after {@link beginClear} so the clear's empty snapshot isn't\n   * persisted between `clearMessages()` and {@link remove}.\n   */\n  notifyMessagesChanged(messages: Array<UIMessage>): void {\n    this.messagesGeneration++\n    if (this.skipNextPersist) {\n      this.skipNextPersist = false\n      return\n    }\n    const generation = this.generation\n    const messagesSnapshot = [...messages]\n    this.runOperation(() => {\n      if (generation !== this.generation) {\n        return\n      }\n      return this.adapter.setItem(this.id, messagesSnapshot)\n    })\n  }\n\n  /** Remove the persisted conversation. Invalidates any queued writes. */\n  remove(): void {\n    const generation = ++this.generation\n    this.runOperation(() => {\n      if (generation !== this.generation) {\n        return\n      }\n      return this.adapter.removeItem(this.id)\n    })\n  }\n\n  private runOperation(operation: () => void | Promise<void>): void {\n    if (this.queuePending) {\n      const queued = this.queue.then(operation).catch(() => {\n        // Persistence adapters are best-effort and must not break chat updates.\n      })\n      this.queue = queued\n      void queued.finally(() => {\n        if (this.queue === queued) {\n          this.queuePending = false\n        }\n      })\n      return\n    }\n\n    try {\n      const result = operation()\n      if (result instanceof Promise) {\n        this.queuePending = true\n        const queued = result.catch(() => {\n          // Persistence adapters are best-effort and must not break chat updates.\n        })\n        this.queue = queued\n        void queued.finally(() => {\n          if (this.queue === queued) {\n            this.queuePending = false\n          }\n        })\n      }\n    } catch {\n      // Persistence adapters are best-effort and must not break chat updates.\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // Clear-during-stream suppression\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Capture the message/run ids that exist at the moment of a clear so chunks\n   * still arriving for them can be ignored.\n   */\n  snapshotClear(context: {\n    messages: Array<UIMessage>\n    activeRunIds: Set<string>\n    currentRunId: string | null\n  }): void {\n    for (const message of context.messages) {\n      this.clearedMessageIds.add(message.id)\n    }\n    for (const runId of context.activeRunIds) {\n      this.clearedRunIds.add(runId)\n      this.ignoredActiveRunIds.add(runId)\n    }\n    if (context.currentRunId) {\n      this.clearedRunIds.add(context.currentRunId)\n      this.ignoredActiveRunIds.add(context.currentRunId)\n    }\n  }\n\n  /** Mark that the next persisted message change (the clear itself) is skipped. */\n  beginClear(): void {\n    this.skipNextPersist = true\n  }\n\n  /** Whether a chunk belongs to cleared state and should not be processed. */\n  shouldIgnoreChunk(chunk: StreamChunk): boolean {\n    const runId = getChunkRunId(chunk)\n    if (runId && this.clearedRunIds.has(runId)) {\n      if (chunk.type === 'RUN_STARTED') {\n        this.ignoredActiveRunIds.add(runId)\n        this.currentRunlessRunId = runId\n      }\n      this.markIgnoredChunkIds(chunk)\n      return true\n    }\n\n    if (runId && this.ignoredActiveRunIds.has(runId)) {\n      this.markIgnoredChunkIds(chunk)\n      return true\n    }\n\n    if (this.isRunlessChunkFromIgnoredRun(chunk)) {\n      this.markIgnoredChunkIds(chunk)\n      return true\n    }\n\n    const toolCallId = getChunkToolCallId(chunk)\n    if (toolCallId && this.clearedToolCallIds.has(toolCallId)) {\n      return true\n    }\n\n    const parentMessageId = getChunkParentMessageId(chunk)\n    if (parentMessageId && this.clearedMessageIds.has(parentMessageId)) {\n      if (toolCallId) {\n        this.clearedToolCallIds.add(toolCallId)\n      }\n      return true\n    }\n\n    const messageId = getChunkMessageId(chunk)\n    if (!messageId) {\n      return false\n    }\n    if (this.clearedMessageIds.has(messageId)) {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * The owning client calls this when a run starts so runless content chunks\n   * (adapters that omit `runId` on content events) can be attributed to it.\n   */\n  onRunStarted(runId: string): void {\n    this.currentRunlessRunId = runId\n  }\n\n  /** Forget a settled run, advancing the runless pointer to another ignored run. */\n  onRunSettled(runId: string): void {\n    this.ignoredActiveRunIds.delete(runId)\n    this.clearedRunIds.delete(runId)\n    if (this.currentRunlessRunId === runId) {\n      this.currentRunlessRunId =\n        this.ignoredActiveRunIds.values().next().value ?? null\n    }\n  }\n\n  /** A session-level (runId-less) RUN_ERROR clears all ignored-run tracking. */\n  onSessionRunError(): void {\n    this.ignoredActiveRunIds.clear()\n    this.currentRunlessRunId = null\n  }\n\n  /** Clear the ignored-active-run markers (mirrors a session-generating reset). */\n  resetIgnored(): void {\n    this.ignoredActiveRunIds.clear()\n  }\n\n  /**\n   * Consume the current runless run id (if any), forgetting it. Used when an\n   * ignored, runId-less RUN_ERROR drains the run the client is still tracking.\n   */\n  takeRunlessRunId(): string | null {\n    const runId = this.currentRunlessRunId\n    if (!runId) return null\n    this.ignoredActiveRunIds.delete(runId)\n    this.clearedRunIds.delete(runId)\n    // Advance to another still-ignored run (mirroring `onRunSettled`) so that\n    // when two cleared runs drain concurrently, draining one via a runId-less\n    // RUN_ERROR doesn't stop suppressing the other's runless content.\n    this.currentRunlessRunId =\n      this.ignoredActiveRunIds.values().next().value ?? null\n    return runId\n  }\n\n  private markIgnoredChunkIds(chunk: StreamChunk): void {\n    const messageId = getChunkMessageId(chunk)\n    if (messageId) {\n      this.clearedMessageIds.add(messageId)\n    }\n    const toolCallId = getChunkToolCallId(chunk)\n    if (toolCallId) {\n      this.clearedToolCallIds.add(toolCallId)\n    }\n  }\n\n  private isRunlessChunkFromIgnoredRun(chunk: StreamChunk): boolean {\n    const runId = getChunkRunId(chunk)\n    if (runId || !this.currentRunlessRunId) return false\n    if (\n      !this.ignoredActiveRunIds.has(this.currentRunlessRunId) &&\n      !this.clearedRunIds.has(this.currentRunlessRunId)\n    ) {\n      return false\n    }\n    return (\n      chunk.type === 'TEXT_MESSAGE_START' ||\n      chunk.type === 'TEXT_MESSAGE_CONTENT' ||\n      chunk.type === 'TOOL_CALL_START' ||\n      chunk.type === 'TOOL_CALL_ARGS' ||\n      chunk.type === 'TOOL_CALL_END' ||\n      chunk.type === 'TOOL_CALL_RESULT' ||\n      chunk.type === 'MESSAGES_SNAPSHOT' ||\n      chunk.type === 'RUN_ERROR'\n    )\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"client-persistor.js","names":[],"sources":["../../src/client-persistor.ts"],"sourcesContent":["import { getChunkRunId } from './connection-adapters'\nimport type { StreamChunk } from '@tanstack/ai/client'\nimport type {\n  ChatClientPersistence,\n  ChatPersistedState,\n  ChatResumeSnapshot,\n  UIMessage,\n} from './types'\n\n/** Normalize a raw `getItem` result (legacy bare array or combined record). */\nfunction normalizePersistedState(\n  raw: ChatPersistedState | Array<UIMessage> | null | undefined,\n): ChatPersistedState | undefined {\n  if (Array.isArray(raw)) return { messages: raw }\n  if (raw && Array.isArray(raw.messages)) return raw\n  return undefined\n}\n\n// `StreamChunk` is a discriminated union; `toolCallId` / `messageId` /\n// `parentMessageId` exist on only some members. Narrow with `in` (matching\n// `getChunkRunId`) instead of asserting a shape, so the field's real type is\n// preserved and a protocol rename can't be read past silently.\nfunction getChunkToolCallId(chunk: StreamChunk): string | undefined {\n  return 'toolCallId' in chunk && typeof chunk.toolCallId === 'string'\n    ? chunk.toolCallId\n    : undefined\n}\n\nfunction getChunkMessageId(chunk: StreamChunk): string | undefined {\n  return 'messageId' in chunk && typeof chunk.messageId === 'string'\n    ? chunk.messageId\n    : undefined\n}\n\nfunction getChunkParentMessageId(chunk: StreamChunk): string | undefined {\n  return 'parentMessageId' in chunk && typeof chunk.parentMessageId === 'string'\n    ? chunk.parentMessageId\n    : undefined\n}\n\n/**\n * Encapsulates everything persistence-related for `ChatClient` so the client\n * itself stays focused on streaming and message state.\n *\n * Two responsibilities live here:\n *\n * 1. **Storage orchestration** — hydrate from `getItem(id)` on creation, save a\n *    combined `{ messages, resume? }` record via `setItem` on every change\n *    through an ordered write queue, and `removeItem(id)` on clear (or when\n *    both the transcript and resume pointer are empty). A generation counter\n *    discards stale writes when a removal or a newer conversation supersedes\n *    an in-flight async operation.\n * 2. **Clear-during-stream suppression** — when a conversation is cleared while a\n *    stream is still producing, late chunks for the cleared run(s) must not\n *    repopulate the now-empty state. The persistor tracks the cleared ids and\n *    decides, per chunk, whether the client should ignore it.\n *\n * All adapter calls are best-effort: a throwing or rejecting adapter is swallowed\n * so storage problems never break the chat.\n */\nexport class ChatPersistor {\n  // --- storage queue state ---\n  private skipNextPersist = false\n  private generation = 0\n  private queue: Promise<void> = Promise.resolve()\n  private queuePending = false\n  // Bumped on every message change; lets an in-flight async hydration detect\n  // that the message list moved on and avoid clobbering it.\n  private messagesGeneration = 0\n  // Latest messages + resume snapshot, written together as one combined record\n  // so a full page reload restores both from a single adapter key.\n  private lastMessages: Array<UIMessage> = []\n  private lastResume: ChatResumeSnapshot | null = null\n\n  // --- clear-during-stream suppression state ---\n  private readonly clearedMessageIds = new Set<string>()\n  private readonly clearedRunIds = new Set<string>()\n  private readonly ignoredActiveRunIds = new Set<string>()\n  private readonly clearedToolCallIds = new Set<string>()\n  private currentRunlessRunId: string | null = null\n\n  constructor(\n    private readonly adapter: ChatClientPersistence,\n    private readonly id: string,\n    private readonly applyMessages: (messages: Array<UIMessage>) => void,\n    private readonly applyResume?: (snapshot: ChatResumeSnapshot) => void,\n  ) {}\n\n  /** Persist the current state as one combined `{ messages, resume? }` record. */\n  private writeState(): void {\n    const messages = [...this.lastMessages]\n    // Nothing to persist (no transcript, no resume pointer): remove the key\n    // rather than writing an empty `{ messages: [] }`, so a cleared\n    // conversation does not leave a stale record behind.\n    if (messages.length === 0 && !this.lastResume) {\n      const generation = this.generation\n      this.runOperation(() => {\n        if (generation !== this.generation) {\n          return\n        }\n        return this.adapter.removeItem(this.id)\n      })\n      return\n    }\n    const generation = this.generation\n    const state: ChatPersistedState = {\n      messages,\n      ...(this.lastResume ? { resume: this.lastResume } : {}),\n    }\n    this.runOperation(() => {\n      if (generation !== this.generation) {\n        return\n      }\n      return this.adapter.setItem(this.id, state)\n    })\n  }\n\n  // ---------------------------------------------------------------------------\n  // Storage orchestration\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Synchronously read the persisted state for constructor-time hydration.\n   * Returns the normalized combined record, or a promise of it for async stores.\n   */\n  readInitial():\n    | ChatPersistedState\n    | undefined\n    | Promise<ChatPersistedState | undefined> {\n    try {\n      const raw = this.adapter.getItem(this.id)\n      if (raw instanceof Promise) {\n        return raw.then(normalizePersistedState).catch(() => undefined)\n      }\n      const state = normalizePersistedState(raw)\n      if (state) {\n        this.lastMessages = state.messages\n        this.lastResume = state.resume ?? null\n      }\n      return state\n    } catch {\n      return undefined\n    }\n  }\n\n  /**\n   * Apply state from an async `getItem` once it resolves, unless the message\n   * list has already changed since hydration began.\n   */\n  hydrateAsync(\n    persistedState:\n      | ChatPersistedState\n      | undefined\n      | Promise<ChatPersistedState | undefined>,\n  ): void {\n    if (!(persistedState instanceof Promise)) {\n      return\n    }\n\n    const hydrationGeneration = this.messagesGeneration\n    persistedState\n      .then((state) => {\n        if (!state || this.messagesGeneration !== hydrationGeneration) {\n          return\n        }\n        this.lastResume = state.resume ?? null\n        this.lastMessages = state.messages\n        this.applyMessages(state.messages)\n        if (state.resume && this.applyResume) {\n          this.applyResume(state.resume)\n        }\n      })\n      .catch(() => {\n        // Persistence adapters are best-effort and must not break chat setup.\n      })\n  }\n\n  /**\n   * Record a message-list change and queue a combined write for it. Skips a\n   * single write after {@link beginClear} so the clear's empty snapshot isn't\n   * persisted between `clearMessages()` and {@link remove}.\n   */\n  notifyMessagesChanged(messages: Array<UIMessage>): void {\n    this.messagesGeneration++\n    this.lastMessages = [...messages]\n    if (this.skipNextPersist) {\n      this.skipNextPersist = false\n      return\n    }\n    this.writeState()\n  }\n\n  /**\n   * Record the current resume snapshot (which run to rejoin / which interrupts\n   * are pending) and persist it alongside the messages. Pass `null` to clear it\n   * once the run reaches a non-interrupt terminal.\n   */\n  persistResumeSnapshot(snapshot: ChatResumeSnapshot | null): void {\n    this.lastResume = snapshot\n    if (this.skipNextPersist) {\n      return\n    }\n    this.writeState()\n  }\n\n  /** Remove the persisted conversation. Invalidates any queued writes. */\n  remove(): void {\n    this.lastMessages = []\n    this.lastResume = null\n    const generation = ++this.generation\n    this.runOperation(() => {\n      if (generation !== this.generation) {\n        return\n      }\n      return this.adapter.removeItem(this.id)\n    })\n  }\n\n  private runOperation(operation: () => void | Promise<void>): void {\n    if (this.queuePending) {\n      const queued = this.queue.then(operation).catch(() => {\n        // Persistence adapters are best-effort and must not break chat updates.\n      })\n      this.queue = queued\n      void queued.finally(() => {\n        if (this.queue === queued) {\n          this.queuePending = false\n        }\n      })\n      return\n    }\n\n    try {\n      const result = operation()\n      if (result instanceof Promise) {\n        this.queuePending = true\n        const queued = result.catch(() => {\n          // Persistence adapters are best-effort and must not break chat updates.\n        })\n        this.queue = queued\n        void queued.finally(() => {\n          if (this.queue === queued) {\n            this.queuePending = false\n          }\n        })\n      }\n    } catch {\n      // Persistence adapters are best-effort and must not break chat updates.\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // Clear-during-stream suppression\n  // ---------------------------------------------------------------------------\n\n  /**\n   * Capture the message/run ids that exist at the moment of a clear so chunks\n   * still arriving for them can be ignored.\n   */\n  snapshotClear(context: {\n    messages: Array<UIMessage>\n    activeRunIds: Set<string>\n    currentRunId: string | null\n  }): void {\n    for (const message of context.messages) {\n      this.clearedMessageIds.add(message.id)\n    }\n    for (const runId of context.activeRunIds) {\n      this.clearedRunIds.add(runId)\n      this.ignoredActiveRunIds.add(runId)\n    }\n    if (context.currentRunId) {\n      this.clearedRunIds.add(context.currentRunId)\n      this.ignoredActiveRunIds.add(context.currentRunId)\n    }\n  }\n\n  /** Mark that the next persisted message change (the clear itself) is skipped. */\n  beginClear(): void {\n    this.skipNextPersist = true\n  }\n\n  /** Whether a chunk belongs to cleared state and should not be processed. */\n  shouldIgnoreChunk(chunk: StreamChunk): boolean {\n    const runId = getChunkRunId(chunk)\n    if (runId && this.clearedRunIds.has(runId)) {\n      if (chunk.type === 'RUN_STARTED') {\n        this.ignoredActiveRunIds.add(runId)\n        this.currentRunlessRunId = runId\n      }\n      this.markIgnoredChunkIds(chunk)\n      return true\n    }\n\n    if (runId && this.ignoredActiveRunIds.has(runId)) {\n      this.markIgnoredChunkIds(chunk)\n      return true\n    }\n\n    if (this.isRunlessChunkFromIgnoredRun(chunk)) {\n      this.markIgnoredChunkIds(chunk)\n      return true\n    }\n\n    const toolCallId = getChunkToolCallId(chunk)\n    if (toolCallId && this.clearedToolCallIds.has(toolCallId)) {\n      return true\n    }\n\n    const parentMessageId = getChunkParentMessageId(chunk)\n    if (parentMessageId && this.clearedMessageIds.has(parentMessageId)) {\n      if (toolCallId) {\n        this.clearedToolCallIds.add(toolCallId)\n      }\n      return true\n    }\n\n    const messageId = getChunkMessageId(chunk)\n    if (!messageId) {\n      return false\n    }\n    if (this.clearedMessageIds.has(messageId)) {\n      return true\n    }\n\n    return false\n  }\n\n  /**\n   * The owning client calls this when a run starts so runless content chunks\n   * (adapters that omit `runId` on content events) can be attributed to it.\n   */\n  onRunStarted(runId: string): void {\n    this.currentRunlessRunId = runId\n  }\n\n  /** Forget a settled run, advancing the runless pointer to another ignored run. */\n  onRunSettled(runId: string): void {\n    this.ignoredActiveRunIds.delete(runId)\n    this.clearedRunIds.delete(runId)\n    if (this.currentRunlessRunId === runId) {\n      this.currentRunlessRunId =\n        this.ignoredActiveRunIds.values().next().value ?? null\n    }\n  }\n\n  /** A session-level (runId-less) RUN_ERROR clears all ignored-run tracking. */\n  onSessionRunError(): void {\n    this.ignoredActiveRunIds.clear()\n    this.currentRunlessRunId = null\n  }\n\n  /** Clear the ignored-active-run markers (mirrors a session-generating reset). */\n  resetIgnored(): void {\n    this.ignoredActiveRunIds.clear()\n  }\n\n  /**\n   * Consume the current runless run id (if any), forgetting it. Used when an\n   * ignored, runId-less RUN_ERROR drains the run the client is still tracking.\n   */\n  takeRunlessRunId(): string | null {\n    const runId = this.currentRunlessRunId\n    if (!runId) return null\n    this.ignoredActiveRunIds.delete(runId)\n    this.clearedRunIds.delete(runId)\n    // Advance to another still-ignored run (mirroring `onRunSettled`) so that\n    // when two cleared runs drain concurrently, draining one via a runId-less\n    // RUN_ERROR doesn't stop suppressing the other's runless content.\n    this.currentRunlessRunId =\n      this.ignoredActiveRunIds.values().next().value ?? null\n    return runId\n  }\n\n  private markIgnoredChunkIds(chunk: StreamChunk): void {\n    const messageId = getChunkMessageId(chunk)\n    if (messageId) {\n      this.clearedMessageIds.add(messageId)\n    }\n    const toolCallId = getChunkToolCallId(chunk)\n    if (toolCallId) {\n      this.clearedToolCallIds.add(toolCallId)\n    }\n  }\n\n  private isRunlessChunkFromIgnoredRun(chunk: StreamChunk): boolean {\n    const runId = getChunkRunId(chunk)\n    if (runId || !this.currentRunlessRunId) return false\n    if (\n      !this.ignoredActiveRunIds.has(this.currentRunlessRunId) &&\n      !this.clearedRunIds.has(this.currentRunlessRunId)\n    ) {\n      return false\n    }\n    return (\n      chunk.type === 'TEXT_MESSAGE_START' ||\n      chunk.type === 'TEXT_MESSAGE_CONTENT' ||\n      chunk.type === 'TOOL_CALL_START' ||\n      chunk.type === 'TOOL_CALL_ARGS' ||\n      chunk.type === 'TOOL_CALL_END' ||\n      chunk.type === 'TOOL_CALL_RESULT' ||\n      chunk.type === 'MESSAGES_SNAPSHOT' ||\n      chunk.type === 'RUN_ERROR'\n    )\n  }\n}\n"],"mappings":"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"}

package/dist/esm/connection-adapters.d.ts

@@ -1,5 +1,5 @@
-import { ModelMessage, StreamChunk, UIMessage } from '@tanstack/ai/client';
-import { ChatFetcher } from './types.js';
+import { ModelMessage, RunAgentResumeItem, StreamChunk, UIMessage } from '@tanstack/ai/client';
+import { ChatFetcher, ChatPendingInterrupt } from './types.js';
 /**
  * Resolve a chunk's run id, preferring the value on the chunk itself
  * (RUN_STARTED / RUN_FINISHED / RUN_ERROR carry one) and falling back to the
@@ -14,6 +14,41 @@ export declare function getChunkRunId(chunk: StreamChunk): string | undefined;
 export declare class StreamTruncatedError extends Error {
     constructor();
 }
+/**
+ * Thrown when a durable (id-tagged) run's stream ends with no terminal event
+ * and a reconnect makes no forward progress — the run cannot complete, so the
+ * consumer must not be left silently hanging on a stream that just stops.
+ */
+export declare class DurableStreamIncompleteError extends Error {
+    constructor();
+}
+/**
+ * Thrown when a durable run exceeds its reconnect ceiling. Bounds the
+ * otherwise-unbounded reconnect loop so a flapping producer (or a proxy that
+ * rolls the socket after every event) surfaces a failure instead of
+ * reconnecting without end.
+ */
+export declare class StreamReconnectLimitError extends Error {
+    constructor(attempts: number);
+}
+/**
+ * Reconnect bounding for resumable streams. A constant throttle delay prevents a
+ * hot loop against the origin, and the ceiling bounds a pathologically failing
+ * run — but only counts CONSECUTIVE reconnects that made no forward progress.
+ */
+export interface ReconnectOptions {
+    /**
+     * Ceiling on the number of CONSECUTIVE reconnects that deliver no new events,
+     * before failing with {@link StreamReconnectLimitError}. The counter resets to
+     * zero whenever a reconnect makes forward progress, so a healthy long run —
+     * even one behind a proxy that rolls the socket after every event — never
+     * approaches it; the ceiling only fires when the run is genuinely stuck
+     * (reconnecting repeatedly without receiving anything new). Default 5.
+     */
+    maxAttempts?: number;
+    /** Delay between reconnect attempts, in ms, to avoid hammering. Default 250. */
+    delayMs?: number;
+}
 /**
  * Per-send context provided by the chat client to the connection adapter.
  * The adapter combines this with serialized messages to build a full
@@ -23,6 +58,8 @@ export interface RunAgentInputContext {
     threadId: string;
     runId: string;
     parentRunId?: string;
+    /** AG-UI interrupt resume entries returned to the server on a follow-up run. */
+    resume?: Array<RunAgentResumeItem>;
     /** Client-declared tools to advertise in the request payload. */
     clientTools?: Array<{
         name: string;
@@ -37,6 +74,110 @@ export interface ConnectConnectionAdapter {
      * Connect and return an async iterable of StreamChunks.
      */
     connect: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal, runContext?: RunAgentInputContext) => AsyncIterable<StreamChunk>;
+    /**
+     * Fetch server-driven hydration for a generation `threadId`: the last
+     * generation's resume snapshot, plus a cursor to a run still generating if
+     * one exists. The generation client calls this itself on mount when
+     * `persistence: true` (no loader/prop) and repaints the snapshot — it never
+     * auto-starts a run. Read-only JSON GET (`?threadId`), so it is
+     * transport-agnostic. Optional and feature-detected exactly like the chat
+     * `hydrate` handler.
+     */
+    hydrateGeneration?: (threadId: string) => Promise<GenerationHydrationResult>;
+    /**
+     * Re-attach to a run that is still generating and replay it from the start
+     * (read-only `?offset=-1&runId` against the delivery-durability log). The
+     * generation client tails this on mount when hydration reports a run still in
+     * flight, so a dropped connection or a full reload finishes the generation in
+     * place — the same durability replay the chat client uses. Optional and
+     * feature-detected; present on `fetchServerSentEvents` / `fetchHttpStream`.
+     */
+    joinRun?: (runId: string, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>;
+    /**
+     * Fetch server-driven hydration for a chat `threadId`: the stored transcript
+     * plus a cursor to an in-flight run and any pending interrupts. The chat
+     * client calls this itself on mount when `persistence: true` (no loader/prop)
+     * and repaints it — it never auto-sends. Read-only JSON GET (`?threadId`), so
+     * it is transport-agnostic. Optional and feature-detected; present on
+     * `fetchServerSentEvents` / `fetchHttpStream`, and on `stream()` /
+     * `rpcStream()` when supplied via {@link StreamConnectionHandlers}.
+     */
+    hydrate?: (threadId: string) => Promise<ChatHydrationResult>;
+}
+/**
+ * Server-resolved hydration for a generation thread. `resumeSnapshot` is the
+ * last generation's lightweight snapshot (validated client-side before it is
+ * adopted); `activeRun` is a cursor to a run still generating for the thread
+ * (or `null`).
+ *
+ * Field-for-field compatible with `@tanstack/ai-persistence`'s
+ * `ReconstructedGeneration` (the body `reconstructGeneration` returns) — the
+ * client never imports that package, so this is a structural contract, not a
+ * shared type. Two deliberate widenings on this side: `schemaVersion` is
+ * optional (the server always writes `1`, but a hand-written fixture need not),
+ * and `status` also admits `'idle'`, which the server's mapper never emits.
+ * Only a client-local snapshot reaches it, when `stop()` retires a cancelled
+ * run.
+ */
+export interface GenerationHydrationResult {
+    resumeSnapshot: {
+        schemaVersion?: 1;
+        resumeState: {
+            threadId: string;
+            runId: string;
+        } | null;
+        status: 'idle' | 'running' | 'complete' | 'error';
+        result?: unknown;
+        error?: {
+            message: string;
+            code?: string;
+        };
+        activity?: string;
+    } | null;
+    activeRun: {
+        runId: string;
+    } | null;
+}
+/**
+ * Server-resolved hydration for a thread. `messages` is the stored transcript;
+ * `activeRun` is a cursor to a run still generating for the thread (or `null`).
+ * Keyed on the STABLE thread id — the client never handles a run id, so a turn
+ * that spans several runs (interrupt/tool continuations) reconnects correctly.
+ */
+export interface ChatHydrationResult {
+    messages: Array<UIMessage>;
+    activeRun: {
+        runId: string;
+    } | null;
+    /**
+     * Pending human-in-the-loop interrupts for the thread and the run they paused,
+     * so a reload (or another device) re-prompts the approval from the server. The
+     * client restores them exactly as a persisted resume snapshot would.
+     */
+    interrupts: {
+        runId: string;
+        pending: Array<ChatPendingInterrupt>;
+    } | null;
+}
+/**
+ * A {@link ConnectConnectionAdapter} that also supports joining an existing run
+ * (a second tab, or re-attaching after a full reload) via `joinRun`, replaying
+ * the ordered stream from the start off the server's delivery-durability sink.
+ */
+export interface ResumableConnectConnectionAdapter extends ConnectConnectionAdapter {
+    /**
+     * Join an in-flight or finished run by id, replaying from the start
+     * (`?offset=-1`). Read-only — sends no messages.
+     */
+    joinRun: (runId: string, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>;
+    /**
+     * Fetch server-authoritative hydration for `threadId`: the stored transcript,
+     * and a cursor to an in-flight run if one exists. The client calls this itself
+     * on mount (no loader/prop), then tails `activeRun` via `joinRun`. Read-only
+     * JSON GET (`?threadId`), so it is transport-agnostic regardless of how the
+     * delivery stream is served.
+     */
+    hydrate?: (threadId: string) => Promise<ChatHydrationResult>;
 }
 export interface SubscribeConnectionAdapter {
     /**
@@ -47,6 +188,19 @@ export interface SubscribeConnectionAdapter {
      * Send a request; chunks arrive through subscribe().
      */
     send: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal, runContext?: RunAgentInputContext) => Promise<void>;
+    /**
+     * Re-attach to an existing run by id, replaying its stream from the start off
+     * the server's delivery-durability sink. Present only when the underlying
+     * connection is resumable (a `ResumableConnectConnectionAdapter`). Used to
+     * rejoin an in-flight run after a full page reload.
+     */
+    joinRun?: (runId: string, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>;
+    /**
+     * Server-authoritative hydration for a thread (transcript + in-flight-run
+     * cursor). Present only when the underlying connection supports it. The client
+     * calls it on mount to re-hydrate without any app-side loader or prop.
+     */
+    hydrate?: (threadId: string) => Promise<ChatHydrationResult>;
 }
 /**
  * Connection adapter union.
@@ -69,6 +223,8 @@ export interface FetchConnectionOptions {
     signal?: AbortSignal;
     body?: Record<string, any>;
     fetchClient?: typeof globalThis.fetch;
+    /** Bounding for resumable-SSE reconnection (throttle delay + attempt ceiling). */
+    reconnect?: ReconnectOptions;
 }
 /**
  * Options for XHR-based connection adapters.
@@ -79,6 +235,8 @@ export interface XhrConnectionOptions {
     signal?: AbortSignal;
     body?: Record<string, any>;
     xhrFactory?: () => XMLHttpRequest;
+    /** Bounding for resumable reconnection (throttle delay + attempt ceiling). */
+    reconnect?: ReconnectOptions;
 }
 /**
  * Create a Server-Sent Events connection adapter
@@ -109,12 +267,12 @@ export interface XhrConnectionOptions {
  * const connection = fetchServerSentEvents('/api/chat', async () => ({
  *   body: {
  *     provider: 'openai',
- *     model: 'gpt-4o',
+ *     model: 'gpt-5.5',
  *   }
  * }));
  * ```
  */
-export declare function fetchServerSentEvents(url: string | (() => string), options?: FetchConnectionOptions | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>)): ConnectConnectionAdapter;
+export declare function fetchServerSentEvents(url: string | (() => string), options?: FetchConnectionOptions | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>)): ResumableConnectConnectionAdapter;
 /**
  * Create an HTTP streaming connection adapter (for raw streaming without SSE format)
  *
@@ -144,25 +302,67 @@ export declare function fetchServerSentEvents(url: string | (() => string), opti
  * const connection = fetchHttpStream('/api/chat', async () => ({
  *   body: {
  *     provider: 'openai',
- *     model: 'gpt-4o',
+ *     model: 'gpt-5.5',
  *   }
  * }));
  * ```
  */
-export declare function fetchHttpStream(url: string | (() => string), options?: FetchConnectionOptions | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>)): ConnectConnectionAdapter;
+export declare function fetchHttpStream(url: string | (() => string), options?: FetchConnectionOptions | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>)): ResumableConnectConnectionAdapter;
 type XhrConnectionOptionsResolver = XhrConnectionOptions | (() => XhrConnectionOptions | Promise<XhrConnectionOptions>);
 /**
  * Create an XMLHttpRequest-backed Server-Sent Events connection adapter.
+ *
+ * Resumable: against a durable (`id:`-tagged) server response, a dropped socket
+ * auto-reconnects with `Last-Event-ID` and de-dupes the replayed prefix, and
+ * `joinRun` attaches to an existing run from the start. A non-durable response
+ * is a single plain request, exactly as before.
  */
-export declare function xhrServerSentEvents(url: string | (() => string), options?: XhrConnectionOptionsResolver): ConnectConnectionAdapter;
+export declare function xhrServerSentEvents(url: string | (() => string), options?: XhrConnectionOptionsResolver): ResumableConnectConnectionAdapter;
 /**
  * Create an XMLHttpRequest-backed newline-delimited JSON stream adapter.
+ *
+ * Resumable: against a durable (envelope-tagged) server response, a dropped
+ * socket auto-reconnects with `Last-Event-ID` and de-dupes the replayed prefix,
+ * and `joinRun` attaches to an existing run from the start. A non-durable
+ * (bare-line) response is a single plain request, exactly as before.
  */
-export declare function xhrHttpStream(url: string | (() => string), options?: XhrConnectionOptionsResolver): ConnectConnectionAdapter;
+export declare function xhrHttpStream(url: string | (() => string), options?: XhrConnectionOptionsResolver): ResumableConnectConnectionAdapter;
+/**
+ * Optional persistence handlers for the lightweight adapters (`stream()`,
+ * `rpcStream()`). These are one-shot, request-scoped calls with no built-in
+ * GET endpoint or second channel, so hydration and run-rejoin only exist if
+ * the app supplies them — typically thin wrappers over TanStack Start server
+ * functions backed by `@tanstack/ai-persistence` (`getGenerationHydration`)
+ * and a delivery-durability log (`memoryStream` / `replayRunStream`).
+ *
+ * Each handler is spread onto the returned adapter only when defined, so
+ * feature detection (`connection.hydrateGeneration` etc.) keeps working.
+ */
+export interface StreamConnectionHandlers {
+    /**
+     * Server-driven chat hydration for `persistence: true`: the stored
+     * transcript for `threadId` plus a cursor to an in-flight run.
+     */
+    hydrate?: (threadId: string) => Promise<ChatHydrationResult>;
+    /**
+     * Server-driven generation hydration for `persistence: true`: the last
+     * generation's resume snapshot for `threadId` plus a cursor to a run still
+     * generating. See {@link ConnectConnectionAdapter.hydrateGeneration}.
+     */
+    hydrateGeneration?: (threadId: string) => Promise<GenerationHydrationResult>;
+    /**
+     * Re-attach to a run still generating and replay it from the start. See
+     * {@link ConnectConnectionAdapter.joinRun}.
+     */
+    joinRun?: (runId: string, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>;
+}
 /**
  * Create a direct stream connection adapter (for server functions or direct streams)
  *
  * @param streamFactory - A function that returns an async iterable of StreamChunks
+ * @param handlers - Optional persistence handlers (`hydrate`,
+ * `hydrateGeneration`, `joinRun`) that let server-driven persistence work
+ * without an HTTP endpoint — each is usually a one-line server-function call
  * @returns A connection adapter for direct streams
  *
  * @example
@@ -171,9 +371,18 @@ export declare function xhrHttpStream(url: string | (() => string), options?: Xh
  * const connection = stream(() => serverFunction({ messages }));
  *
  * const client = new ChatClient({ connection });
+ *
+ * // With generation persistence over server functions
+ * const connection = stream(
+ *   () => generateImageFn({ data: input }),
+ *   {
+ *     hydrateGeneration: (threadId) => getImageHydrationFn({ data: threadId }),
+ *     joinRun: (runId) => joinImageRunFn({ data: runId }),
+ *   },
+ * );
  * ```
  */
-export declare function stream(streamFactory: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>): ConnectConnectionAdapter;
+export declare function stream(streamFactory: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>, handlers?: StreamConnectionHandlers): ConnectConnectionAdapter;
 /**
  * Wrap a `ChatFetcher` as a `ConnectConnectionAdapter` so the chat client can
  * consume it through the same `subscribe`/`send` plumbing used for SSE /
@@ -187,6 +396,9 @@ export declare function fetcherToConnectionAdapter(fetcher: ChatFetcher): Connec
  * Create an RPC stream connection adapter (for RPC-based streaming like Cap'n Web RPC)
  *
  * @param rpcCall - A function that accepts messages and returns an async iterable of StreamChunks
+ * @param handlers - Optional persistence handlers (`hydrate`,
+ * `hydrateGeneration`, `joinRun`) that let server-driven persistence work
+ * without an HTTP endpoint — each is usually a one-line RPC call
  * @returns A connection adapter for RPC streams
  *
  * @example
@@ -197,7 +409,16 @@ export declare function fetcherToConnectionAdapter(fetcher: ChatFetcher): Connec
  * );
  *
  * const client = new ChatClient({ connection });
+ *
+ * // With generation persistence over RPC
+ * const connection = rpcStream(
+ *   (messages, data) => api.streamMurfResponse(messages, data),
+ *   {
+ *     hydrateGeneration: (threadId) => api.getGenerationHydration(threadId),
+ *     joinRun: (runId) => api.replayRun(runId),
+ *   },
+ * );
  * ```
  */
-export declare function rpcStream(rpcCall: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>): ConnectConnectionAdapter;
+export declare function rpcStream(rpcCall: (messages: Array<UIMessage> | Array<ModelMessage>, data?: Record<string, any>, abortSignal?: AbortSignal) => AsyncIterable<StreamChunk>, handlers?: StreamConnectionHandlers): ConnectConnectionAdapter;
 export {};