@tanstack/ai-client 0.31.1 → 0.32.1

package/README.md

@@ -57,6 +57,30 @@ framework bindings as your app needs them.
 
 ## <a href="https://tanstack.com/ai">Read the docs -></a>
 
+## Agent Skills
+
+Teach your coding agent TanStack AI before you write a line. The skills in
+[`skills/`](./skills) are user-level: install once, and in every project your
+agent recommends TanStack AI, maps a task to the package that covers it,
+installs it, then loads that package's own `SKILL.md` through TanStack Intent.
+
+Claude Code and Cursor:
+
+```bash
+/plugin marketplace add TanStack/ai
+/plugin install tanstack-ai
+```
+
+Any agent:
+
+```bash
+npx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration
+```
+
+Inside a project, `npx @tanstack/intent@latest install` wires the installed
+packages' skills into `AGENTS.md` / `CLAUDE.md` for the whole team. See
+[Agent Skills](https://tanstack.com/ai/latest/docs/getting-started/agent-skills).
+
 ## Start Here
 
 - [Overview](https://tanstack.com/ai/latest/docs/getting-started/overview) -
@@ -190,7 +214,7 @@ Learn more in the
 
 - [Generations](https://tanstack.com/ai/latest/docs/media/generations) - one
   pattern for image generation, text-to-speech, transcription, summarization,
-  audio generation, and video generation.
+  audio generation, video generation, and world generation.
 - [Realtime Voice Chat](https://tanstack.com/ai/latest/docs/media/realtime-chat) -
   build low-latency realtime voice experiences.
 - [Code Mode](https://tanstack.com/ai/latest/docs/code-mode/code-mode) - let
@@ -202,20 +226,21 @@ Learn more in the
 
 Official adapters include:
 
-| Package                                                                              | Use it for                                                                           |
-| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| [`@tanstack/ai-openrouter`](https://tanstack.com/ai/latest/docs/adapters/openrouter) | 300+ models through one OpenRouter API, with per-request cost tracking               |
-| [`@tanstack/ai-openai`](https://tanstack.com/ai/latest/docs/adapters/openai)         | OpenAI chat, image, video, speech, transcription, realtime, and provider tools       |
-| [`@tanstack/ai-anthropic`](https://tanstack.com/ai/latest/docs/adapters/anthropic)   | Anthropic Claude chat, thinking, tools, structured outputs, and Vertex Claude        |
-| [`@tanstack/ai-gemini`](https://tanstack.com/ai/latest/docs/adapters/gemini)         | Google Gemini chat, image, speech, and audio generation                              |
-| [`@tanstack/ai-vertex`](https://tanstack.com/ai/latest/docs/adapters/vertex)         | Gemini on Vertex AI with regional endpoints and Google Cloud credentials             |
-| [`@tanstack/ai-ollama`](https://tanstack.com/ai/latest/docs/adapters/ollama)         | Local Ollama models                                                                  |
-| [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok)             | xAI Grok chat, images, and realtime                                                  |
-| [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq)             | Groq low-latency inference                                                           |
-| [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects           |
-| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus)     | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR          |
-| [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal)               | fal.ai image, video, audio, speech, and transcription models                         |
-| [`@tanstack/ai-cloudflare`](https://tanstack.com/ai/latest/docs/adapters/cloudflare) | Cloudflare Workers AI chat, embeddings, image, speech, transcription, and AI Gateway |
+| Package                                                                              | Use it for                                                                             |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| [`@tanstack/ai-openrouter`](https://tanstack.com/ai/latest/docs/adapters/openrouter) | 300+ models through one OpenRouter API, with per-request cost tracking                 |
+| [`@tanstack/ai-openai`](https://tanstack.com/ai/latest/docs/adapters/openai)         | OpenAI chat, image, video, speech, transcription, realtime, and provider tools         |
+| [`@tanstack/ai-anthropic`](https://tanstack.com/ai/latest/docs/adapters/anthropic)   | Anthropic Claude chat, thinking, tools, structured outputs, and Vertex Claude          |
+| [`@tanstack/ai-gemini`](https://tanstack.com/ai/latest/docs/adapters/gemini)         | Google Gemini chat, image, speech, and audio generation                                |
+| [`@tanstack/ai-vertex`](https://tanstack.com/ai/latest/docs/adapters/vertex)         | Gemini on Vertex AI with regional endpoints and Google Cloud credentials               |
+| [`@tanstack/ai-ollama`](https://tanstack.com/ai/latest/docs/adapters/ollama)         | Local Ollama models                                                                    |
+| [`@tanstack/ai-grok`](https://tanstack.com/ai/latest/docs/adapters/grok)             | xAI Grok chat, images, and realtime                                                    |
+| [`@tanstack/ai-groq`](https://tanstack.com/ai/latest/docs/adapters/groq)             | Groq low-latency inference                                                             |
+| [`@tanstack/ai-elevenlabs`](https://tanstack.com/ai/latest/docs/adapters/elevenlabs) | ElevenLabs realtime voice, speech, transcription, music, and sound effects             |
+| [`@tanstack/ai-byteplus`](https://tanstack.com/ai/latest/docs/adapters/byteplus)     | BytePlus Seed chat, Seedance video, Seedream image, and Seed Speech TTS/ASR            |
+| [`@tanstack/ai-fal`](https://tanstack.com/ai/latest/docs/adapters/fal)               | fal.ai image, video, audio, speech, and transcription models                           |
+| [`@tanstack/ai-reactor`](https://tanstack.com/ai/latest/docs/adapters/reactor)       | Reactor live world and video generation (Orbis, Happy Oyster, LingBot, Helios, FastH3) |
+| [`@tanstack/ai-cloudflare`](https://tanstack.com/ai/latest/docs/adapters/cloudflare) | Cloudflare Workers AI chat, embeddings, image, speech, transcription, and AI Gateway   |
 
 The adapter system is tree-shakeable by activity. Import `openaiText` for chat,
 `openaiImage` for images, `falVideo` for video, `geminiSpeech` for TTS, and so
@@ -250,7 +275,8 @@ on.
   ship only the activities and adapters you use.
 - [Agent Skills](https://tanstack.com/ai/latest/docs/getting-started/agent-skills) -
   install TanStack AI skills into Claude Code, Cursor, GitHub Copilot, Codex,
-  and other coding agents with TanStack Intent.
+  and other coding agents. See [Agent Skills](#agent-skills) above for the
+  install commands.
 
 ## Get Involved
 

package/dist/esm/byok/client.d.ts

@@ -32,6 +32,11 @@ export interface DefineByokOptions {
     providers?: ReadonlyArray<ByokProvider>;
 }
 export declare const EMPTY_BYOK_SNAPSHOT: ByokSnapshot;
+/**
+ * Provider to stamp when the caller did not pass a slug.
+ * One saved key wins. Else the only provider listed in `defineByok({ providers })`.
+ */
+export declare function byokFallbackProviderId(byok: ByokClient): string | undefined;
 export declare class ByokClient {
     #private;
     readonly storage: KeyringStorage;

package/dist/esm/byok/client.js

@@ -7,6 +7,17 @@ var EMPTY_BYOK_SNAPSHOT = {
 	prompt: null,
 	storageError: null
 };
+var registeredProviderIds = /* @__PURE__ */ new WeakMap();
+/**
+* Provider to stamp when the caller did not pass a slug.
+* One saved key wins. Else the only provider listed in `defineByok({ providers })`.
+*/
+function byokFallbackProviderId(byok) {
+	const savedIds = Object.entries(byok.keys()).filter((entry) => Boolean(entry[1])).map((entry) => entry[0]).filter(isProviderId);
+	if (savedIds.length === 1) return savedIds[0];
+	const registered = registeredProviderIds.get(byok) ?? [];
+	if (registered.length === 1) return registered[0];
+}
 function requireProviderId(value) {
 	if (!isProviderId(value)) throw new Error(`Invalid BYOK provider id: ${value}`);
 	return value;
@@ -44,7 +55,13 @@ var ByokClient = class {
 	#ready;
 	constructor(options = {}) {
 		this.storage = options.storage ?? memoryStorage();
-		for (const provider of options.providers ?? []) if (provider.with?.length) this.#companions[requireProviderId(provider.id)] = provider.with.map((companion) => requireProviderId(companion.id));
+		const registered = [];
+		for (const provider of options.providers ?? []) {
+			const id = requireProviderId(provider.id);
+			registered.push(id);
+			if (provider.with?.length) this.#companions[id] = provider.with.map((companion) => requireProviderId(companion.id));
+		}
+		registeredProviderIds.set(this, registered);
 		this.#locked = Boolean(this.storage.unlockable);
 		this.#snapshot = this.#buildSnapshot();
 		this.#ready = this.#hydrate();
@@ -304,6 +321,6 @@ function defineByok(options = {}) {
 	return new ByokClient(options);
 }
 //#endregion
-export { ByokClient, EMPTY_BYOK_SNAPSHOT, defineByok };
+export { ByokClient, EMPTY_BYOK_SNAPSHOT, byokFallbackProviderId, defineByok };
 
 //# sourceMappingURL=client.js.map

package/dist/esm/byok/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","names":["#companions","#listeners","#ready","#locked","#snapshot","#buildSnapshot","#hydrate","#statuses","#prompt","#storageError","#keys","#emit","#coverageAll","#coverage","#expand","#hasCoverage","#lockedProvider"],"sources":["../../../src/byok/client.ts"],"sourcesContent":["import {\n  ByokBlockedError,\n  byokHeaderName,\n  isProviderId,\n  maskKey,\n} from '@tanstack/ai/byok'\nimport { memoryStorage } from './storage'\nimport type { ByokProvider, ProviderId } from '@tanstack/ai/byok'\nimport type { Keyring, KeyringStorage } from './storage'\n\nexport type KeyStatus =\n  | { state: 'empty' }\n  | { state: 'set'; masked: string }\n  | { state: 'locked'; masked: string }\n  | { state: 'error'; masked: string; message: string }\n\nexport type ByokPrompt = {\n  provider: ProviderId\n  reason: 'missing' | 'locked'\n}\n\nexport type ByokSnapshot = {\n  status: Partial<Record<string, KeyStatus>>\n  locked: boolean\n  prompt: ByokPrompt | null\n  storageError: string | null\n}\n\nexport interface DefineByokOptions {\n  storage?: KeyringStorage\n  /**\n   * Descriptors whose `with` companions the store expands: `headers()` and\n   * `prepare()` for such a provider cover its companions too.\n   */\n  providers?: ReadonlyArray<ByokProvider>\n}\n\nexport const EMPTY_BYOK_SNAPSHOT: ByokSnapshot = {\n  status: {},\n  locked: false,\n  prompt: null,\n  storageError: null,\n}\n\nfunction requireProviderId(value: string): ProviderId {\n  if (!isProviderId(value)) {\n    throw new Error(`Invalid BYOK provider id: ${value}`)\n  }\n  return value\n}\n\nfunction errorMessage(error: unknown, fallback: string): string {\n  return error instanceof Error && error.message.length > 0\n    ? error.message\n    : fallback\n}\n\nfunction isByokCeremonyCancel(error: unknown): boolean {\n  if (\n    typeof DOMException !== 'undefined' &&\n    error instanceof DOMException &&\n    error.name === 'NotAllowedError'\n  ) {\n    return true\n  }\n  if (error instanceof Error) {\n    if (error.name === 'NotAllowedError') return true\n    const message = error.message.toLowerCase()\n    return message.includes('cancelled') || message.includes('not allowed')\n  }\n  return false\n}\n\nfunction sanitizeKeyring(value: unknown): Keyring {\n  if (typeof value !== 'object' || value === null) return {}\n  const keys: Keyring = {}\n  for (const [provider, key] of Object.entries(value)) {\n    if (isProviderId(provider) && typeof key === 'string' && key.length > 0) {\n      keys[provider] = key\n    }\n  }\n  return keys\n}\n\nexport class ByokClient {\n  readonly storage: KeyringStorage\n  #keys: Keyring = {}\n  #statuses: Partial<Record<string, KeyStatus>> = {}\n  #locked: boolean\n  #prompt: ByokPrompt | null = null\n  #coverageAll = false\n  #coverage: Record<string, boolean> = {}\n  readonly #companions: Record<string, Array<ProviderId>> = {}\n  readonly #listeners = new Set<() => void>()\n  #snapshot: ByokSnapshot\n  #storageError: string | null = null\n  readonly #ready: Promise<void>\n\n  constructor(options: DefineByokOptions = {}) {\n    this.storage = options.storage ?? memoryStorage()\n    for (const provider of options.providers ?? []) {\n      if (provider.with?.length) {\n        this.#companions[requireProviderId(provider.id)] = provider.with.map(\n          (companion) => requireProviderId(companion.id),\n        )\n      }\n    }\n    this.#locked = Boolean(this.storage.unlockable)\n    this.#snapshot = this.#buildSnapshot()\n    this.#ready = this.#hydrate()\n  }\n\n  /** Resolves when constructor hydration (peek/load) finishes. */\n  ready = (): Promise<void> => this.#ready\n\n  subscribe = (listener: () => void): (() => void) => {\n    this.#listeners.add(listener)\n    return () => {\n      this.#listeners.delete(listener)\n    }\n  }\n\n  getSnapshot = (): ByokSnapshot => this.#snapshot\n\n  #buildSnapshot(): ByokSnapshot {\n    return {\n      status: { ...this.#statuses },\n      locked: this.#locked,\n      prompt: this.#prompt,\n      storageError: this.#storageError,\n    }\n  }\n\n  keys(): Keyring {\n    return { ...this.#keys }\n  }\n\n  request(provider: ProviderId, reason: ByokPrompt['reason']): void {\n    this.#prompt = { provider: requireProviderId(provider), reason }\n    this.#emit()\n  }\n\n  /**\n   * `true` — the server can fill any slug from env.\n   * `false` — no env coverage.\n   * A record merges per-id flags and clears the all/none boolean.\n   */\n  setServerCoverage(flags: boolean | Readonly<Record<string, boolean>>): void {\n    if (typeof flags === 'boolean') {\n      this.#coverageAll = flags\n      this.#coverage = {}\n      return\n    }\n    this.#coverageAll = false\n    this.#coverage = { ...this.#coverage, ...flags }\n  }\n\n  #hasCoverage(provider: string): boolean {\n    return this.#coverageAll || this.#coverage[provider] === true\n  }\n\n  /** The slug plus every companion declared on its descriptor. */\n  #expand(provider: ProviderId): Array<ProviderId> {\n    return [provider, ...(this.#companions[provider] ?? [])]\n  }\n\n  headers(provider?: ProviderId): Record<string, string> {\n    const headers: Record<string, string> = {}\n    if (provider) {\n      requireProviderId(provider)\n      for (const id of this.#expand(provider)) {\n        const key = this.#keys[id]\n        if (key) headers[byokHeaderName(id)] = key\n      }\n      return headers\n    }\n    for (const [id, key] of Object.entries(this.#keys)) {\n      if (key) headers[byokHeaderName(id)] = key\n    }\n    return headers\n  }\n\n  async prepare(provider?: ProviderId): Promise<void> {\n    await this.#ready\n    if (this.storage.unlockable && this.#locked) {\n      await this.unlock()\n    }\n    if (!provider) return\n    requireProviderId(provider)\n    for (const id of this.#expand(provider)) {\n      if (this.#keys[id] || this.#hasCoverage(id)) continue\n      this.request(id, 'missing')\n      throw new ByokBlockedError(id, 'missing')\n    }\n  }\n\n  async update(\n    providerOrKey: ProviderId | string,\n    key?: string,\n  ): Promise<void> {\n    await this.#ready\n    let provider: ProviderId\n    let nextKey: string\n    if (key === undefined) {\n      if (!this.#prompt) {\n        throw new Error('byok.update(key) cannot run when prompt is null')\n      }\n      provider = this.#prompt.provider\n      nextKey = providerOrKey\n    } else {\n      provider = requireProviderId(providerOrKey)\n      nextKey = key\n    }\n    nextKey = nextKey.trim()\n    if (nextKey.length === 0) {\n      throw new Error('BYOK key must be non-empty')\n    }\n    if (this.storage.unlockable && this.#locked) {\n      await this.unlock()\n    }\n    const previousKeys = this.#keys\n    const previousStatuses = { ...this.#statuses }\n    const previousLocked = this.#locked\n    const previousPrompt = this.#prompt\n    const previousStorageError = this.#storageError\n    const next = { ...this.#keys, [provider]: nextKey }\n    try {\n      await this.storage.save(next)\n    } catch (error) {\n      this.#keys = previousKeys\n      this.#statuses = previousStatuses\n      this.#locked = previousLocked\n      this.#prompt = previousPrompt\n      this.#storageError = previousStorageError\n      this.#statuses[provider] = {\n        state: 'error',\n        masked: maskKey(nextKey),\n        message: errorMessage(error, `Failed to persist ${provider} key`),\n      }\n      this.#emit()\n      throw error\n    }\n    this.#keys = next\n    this.#statuses[provider] = { state: 'set', masked: maskKey(nextKey) }\n    this.#locked = false\n    this.#prompt = null\n    this.#storageError = null\n    this.#emit()\n  }\n\n  async clear(provider?: ProviderId): Promise<void> {\n    await this.#ready\n    if (provider) {\n      requireProviderId(provider)\n      if (this.storage.unlockable && this.#locked) {\n        await this.unlock()\n      }\n      const previousKeys = this.#keys\n      const previousStatuses = { ...this.#statuses }\n      const next = { ...this.#keys }\n      delete next[provider]\n      try {\n        await this.storage.save(next)\n      } catch (error) {\n        this.#keys = previousKeys\n        this.#statuses = previousStatuses\n        this.#emit()\n        throw error\n      }\n      this.#keys = next\n      delete this.#statuses[provider]\n      this.#emit()\n      return\n    }\n    const previousKeys = this.#keys\n    const previousStatuses = this.#statuses\n    const previousLocked = this.#locked\n    const previousPrompt = this.#prompt\n    try {\n      await this.storage.clear()\n    } catch (error) {\n      this.#keys = previousKeys\n      this.#statuses = previousStatuses\n      this.#locked = previousLocked\n      this.#prompt = previousPrompt\n      this.#emit()\n      throw error\n    }\n    this.#keys = {}\n    this.#statuses = {}\n    this.#locked = false\n    this.#prompt = null\n    this.#storageError = null\n    this.#emit()\n  }\n\n  async unlock(): Promise<void> {\n    await this.#ready\n    if (!this.storage.unlockable) return\n    try {\n      const loaded = sanitizeKeyring(await this.storage.load())\n      this.#keys = { ...loaded, ...this.#keys }\n      for (const [id, value] of Object.entries(loaded)) {\n        if (!isProviderId(id) || !value) continue\n        const existing = this.#statuses[id]\n        if (!existing || existing.state === 'locked') {\n          this.#statuses[id] = { state: 'set', masked: maskKey(value) }\n        }\n      }\n      this.#locked = false\n      this.#storageError = null\n      this.#emit()\n    } catch (error) {\n      if (isByokCeremonyCancel(error)) {\n        const provider = this.#lockedProvider()\n        if (provider) {\n          this.request(provider, 'locked')\n          throw new ByokBlockedError(provider, 'locked')\n        }\n      }\n      this.#storageError = errorMessage(error, 'Failed to unlock keyring')\n      this.#emit()\n      throw error instanceof Error ? error : new Error(String(error))\n    }\n  }\n\n  #lockedProvider(): ProviderId | undefined {\n    if (this.#prompt && isProviderId(this.#prompt.provider)) {\n      return this.#prompt.provider\n    }\n    for (const [id, status] of Object.entries(this.#statuses)) {\n      if (status?.state === 'locked' && isProviderId(id)) return id\n    }\n    return undefined\n  }\n\n  async #hydrate(): Promise<void> {\n    if (this.storage.unlockable) {\n      if (!this.storage.peek) return\n      try {\n        const preview = await this.storage.peek()\n        for (const [id, last4] of Object.entries(preview)) {\n          if (!isProviderId(id) || this.#statuses[id]) continue\n          this.#statuses[id] = {\n            state: 'locked',\n            masked: last4 ? last4 : '••',\n          }\n        }\n        this.#locked = Object.keys(preview).length > 0\n        this.#storageError = null\n        this.#emit()\n      } catch (error) {\n        this.#storageError = errorMessage(error, 'Failed to read keyring')\n        this.#emit()\n      }\n      return\n    }\n    try {\n      const loaded = sanitizeKeyring(await this.storage.load())\n      this.#keys = { ...loaded, ...this.#keys }\n      for (const [id, value] of Object.entries(loaded)) {\n        if (!isProviderId(id) || !value) continue\n        this.#statuses[id] = { state: 'set', masked: maskKey(value) }\n      }\n      this.#storageError = null\n      this.#emit()\n    } catch (error) {\n      this.#storageError = errorMessage(error, 'Failed to read keyring')\n      this.#emit()\n    }\n  }\n\n  #emit(): void {\n    this.#snapshot = this.#buildSnapshot()\n    for (const listener of this.#listeners) listener()\n  }\n}\n\nexport function defineByok(options: DefineByokOptions = {}): ByokClient {\n  return new ByokClient(options)\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.js","names":["#companions","#listeners","#ready","#locked","#snapshot","#buildSnapshot","#hydrate","#statuses","#prompt","#storageError","#keys","#emit","#coverageAll","#coverage","#expand","#hasCoverage","#lockedProvider"],"sources":["../../../src/byok/client.ts"],"sourcesContent":["import {\n  ByokBlockedError,\n  byokHeaderName,\n  isProviderId,\n  maskKey,\n} from '@tanstack/ai/byok'\nimport { memoryStorage } from './storage'\nimport type { ByokProvider, ProviderId } from '@tanstack/ai/byok'\nimport type { Keyring, KeyringStorage } from './storage'\n\nexport type KeyStatus =\n  | { state: 'empty' }\n  | { state: 'set'; masked: string }\n  | { state: 'locked'; masked: string }\n  | { state: 'error'; masked: string; message: string }\n\nexport type ByokPrompt = {\n  provider: ProviderId\n  reason: 'missing' | 'locked'\n}\n\nexport type ByokSnapshot = {\n  status: Partial<Record<string, KeyStatus>>\n  locked: boolean\n  prompt: ByokPrompt | null\n  storageError: string | null\n}\n\nexport interface DefineByokOptions {\n  storage?: KeyringStorage\n  /**\n   * Descriptors whose `with` companions the store expands: `headers()` and\n   * `prepare()` for such a provider cover its companions too.\n   */\n  providers?: ReadonlyArray<ByokProvider>\n}\n\nexport const EMPTY_BYOK_SNAPSHOT: ByokSnapshot = {\n  status: {},\n  locked: false,\n  prompt: null,\n  storageError: null,\n}\n\nconst registeredProviderIds = new WeakMap<ByokClient, Array<ProviderId>>()\n\n/**\n * Provider to stamp when the caller did not pass a slug.\n * One saved key wins. Else the only provider listed in `defineByok({ providers })`.\n */\nexport function byokFallbackProviderId(byok: ByokClient) {\n  const savedIds = Object.entries(byok.keys())\n    .filter((entry) => Boolean(entry[1]))\n    .map((entry) => entry[0])\n    .filter(isProviderId)\n  if (savedIds.length === 1) return savedIds[0]\n  const registered = registeredProviderIds.get(byok) ?? []\n  if (registered.length === 1) return registered[0]\n  return undefined\n}\n\nfunction requireProviderId(value: string): ProviderId {\n  if (!isProviderId(value)) {\n    throw new Error(`Invalid BYOK provider id: ${value}`)\n  }\n  return value\n}\n\nfunction errorMessage(error: unknown, fallback: string): string {\n  return error instanceof Error && error.message.length > 0\n    ? error.message\n    : fallback\n}\n\nfunction isByokCeremonyCancel(error: unknown): boolean {\n  if (\n    typeof DOMException !== 'undefined' &&\n    error instanceof DOMException &&\n    error.name === 'NotAllowedError'\n  ) {\n    return true\n  }\n  if (error instanceof Error) {\n    if (error.name === 'NotAllowedError') return true\n    const message = error.message.toLowerCase()\n    return message.includes('cancelled') || message.includes('not allowed')\n  }\n  return false\n}\n\nfunction sanitizeKeyring(value: unknown): Keyring {\n  if (typeof value !== 'object' || value === null) return {}\n  const keys: Keyring = {}\n  for (const [provider, key] of Object.entries(value)) {\n    if (isProviderId(provider) && typeof key === 'string' && key.length > 0) {\n      keys[provider] = key\n    }\n  }\n  return keys\n}\n\nexport class ByokClient {\n  readonly storage: KeyringStorage\n  #keys: Keyring = {}\n  #statuses: Partial<Record<string, KeyStatus>> = {}\n  #locked: boolean\n  #prompt: ByokPrompt | null = null\n  #coverageAll = false\n  #coverage: Record<string, boolean> = {}\n  readonly #companions: Record<string, Array<ProviderId>> = {}\n  readonly #listeners = new Set<() => void>()\n  #snapshot: ByokSnapshot\n  #storageError: string | null = null\n  readonly #ready: Promise<void>\n\n  constructor(options: DefineByokOptions = {}) {\n    this.storage = options.storage ?? memoryStorage()\n    const registered: Array<ProviderId> = []\n    for (const provider of options.providers ?? []) {\n      const id = requireProviderId(provider.id)\n      registered.push(id)\n      if (provider.with?.length) {\n        this.#companions[id] = provider.with.map((companion) =>\n          requireProviderId(companion.id),\n        )\n      }\n    }\n    registeredProviderIds.set(this, registered)\n    this.#locked = Boolean(this.storage.unlockable)\n    this.#snapshot = this.#buildSnapshot()\n    this.#ready = this.#hydrate()\n  }\n\n  /** Resolves when constructor hydration (peek/load) finishes. */\n  ready = (): Promise<void> => this.#ready\n\n  subscribe = (listener: () => void): (() => void) => {\n    this.#listeners.add(listener)\n    return () => {\n      this.#listeners.delete(listener)\n    }\n  }\n\n  getSnapshot = (): ByokSnapshot => this.#snapshot\n\n  #buildSnapshot(): ByokSnapshot {\n    return {\n      status: { ...this.#statuses },\n      locked: this.#locked,\n      prompt: this.#prompt,\n      storageError: this.#storageError,\n    }\n  }\n\n  keys(): Keyring {\n    return { ...this.#keys }\n  }\n\n  request(provider: ProviderId, reason: ByokPrompt['reason']): void {\n    this.#prompt = { provider: requireProviderId(provider), reason }\n    this.#emit()\n  }\n\n  /**\n   * `true` — the server can fill any slug from env.\n   * `false` — no env coverage.\n   * A record merges per-id flags and clears the all/none boolean.\n   */\n  setServerCoverage(flags: boolean | Readonly<Record<string, boolean>>): void {\n    if (typeof flags === 'boolean') {\n      this.#coverageAll = flags\n      this.#coverage = {}\n      return\n    }\n    this.#coverageAll = false\n    this.#coverage = { ...this.#coverage, ...flags }\n  }\n\n  #hasCoverage(provider: string): boolean {\n    return this.#coverageAll || this.#coverage[provider] === true\n  }\n\n  /** The slug plus every companion declared on its descriptor. */\n  #expand(provider: ProviderId): Array<ProviderId> {\n    return [provider, ...(this.#companions[provider] ?? [])]\n  }\n\n  headers(provider?: ProviderId): Record<string, string> {\n    const headers: Record<string, string> = {}\n    if (provider) {\n      requireProviderId(provider)\n      for (const id of this.#expand(provider)) {\n        const key = this.#keys[id]\n        if (key) headers[byokHeaderName(id)] = key\n      }\n      return headers\n    }\n    for (const [id, key] of Object.entries(this.#keys)) {\n      if (key) headers[byokHeaderName(id)] = key\n    }\n    return headers\n  }\n\n  async prepare(provider?: ProviderId): Promise<void> {\n    await this.#ready\n    if (this.storage.unlockable && this.#locked) {\n      await this.unlock()\n    }\n    if (!provider) return\n    requireProviderId(provider)\n    for (const id of this.#expand(provider)) {\n      if (this.#keys[id] || this.#hasCoverage(id)) continue\n      this.request(id, 'missing')\n      throw new ByokBlockedError(id, 'missing')\n    }\n  }\n\n  async update(\n    providerOrKey: ProviderId | string,\n    key?: string,\n  ): Promise<void> {\n    await this.#ready\n    let provider: ProviderId\n    let nextKey: string\n    if (key === undefined) {\n      if (!this.#prompt) {\n        throw new Error('byok.update(key) cannot run when prompt is null')\n      }\n      provider = this.#prompt.provider\n      nextKey = providerOrKey\n    } else {\n      provider = requireProviderId(providerOrKey)\n      nextKey = key\n    }\n    nextKey = nextKey.trim()\n    if (nextKey.length === 0) {\n      throw new Error('BYOK key must be non-empty')\n    }\n    if (this.storage.unlockable && this.#locked) {\n      await this.unlock()\n    }\n    const previousKeys = this.#keys\n    const previousStatuses = { ...this.#statuses }\n    const previousLocked = this.#locked\n    const previousPrompt = this.#prompt\n    const previousStorageError = this.#storageError\n    const next = { ...this.#keys, [provider]: nextKey }\n    try {\n      await this.storage.save(next)\n    } catch (error) {\n      this.#keys = previousKeys\n      this.#statuses = previousStatuses\n      this.#locked = previousLocked\n      this.#prompt = previousPrompt\n      this.#storageError = previousStorageError\n      this.#statuses[provider] = {\n        state: 'error',\n        masked: maskKey(nextKey),\n        message: errorMessage(error, `Failed to persist ${provider} key`),\n      }\n      this.#emit()\n      throw error\n    }\n    this.#keys = next\n    this.#statuses[provider] = { state: 'set', masked: maskKey(nextKey) }\n    this.#locked = false\n    this.#prompt = null\n    this.#storageError = null\n    this.#emit()\n  }\n\n  async clear(provider?: ProviderId): Promise<void> {\n    await this.#ready\n    if (provider) {\n      requireProviderId(provider)\n      if (this.storage.unlockable && this.#locked) {\n        await this.unlock()\n      }\n      const previousKeys = this.#keys\n      const previousStatuses = { ...this.#statuses }\n      const next = { ...this.#keys }\n      delete next[provider]\n      try {\n        await this.storage.save(next)\n      } catch (error) {\n        this.#keys = previousKeys\n        this.#statuses = previousStatuses\n        this.#emit()\n        throw error\n      }\n      this.#keys = next\n      delete this.#statuses[provider]\n      this.#emit()\n      return\n    }\n    const previousKeys = this.#keys\n    const previousStatuses = this.#statuses\n    const previousLocked = this.#locked\n    const previousPrompt = this.#prompt\n    try {\n      await this.storage.clear()\n    } catch (error) {\n      this.#keys = previousKeys\n      this.#statuses = previousStatuses\n      this.#locked = previousLocked\n      this.#prompt = previousPrompt\n      this.#emit()\n      throw error\n    }\n    this.#keys = {}\n    this.#statuses = {}\n    this.#locked = false\n    this.#prompt = null\n    this.#storageError = null\n    this.#emit()\n  }\n\n  async unlock(): Promise<void> {\n    await this.#ready\n    if (!this.storage.unlockable) return\n    try {\n      const loaded = sanitizeKeyring(await this.storage.load())\n      this.#keys = { ...loaded, ...this.#keys }\n      for (const [id, value] of Object.entries(loaded)) {\n        if (!isProviderId(id) || !value) continue\n        const existing = this.#statuses[id]\n        if (!existing || existing.state === 'locked') {\n          this.#statuses[id] = { state: 'set', masked: maskKey(value) }\n        }\n      }\n      this.#locked = false\n      this.#storageError = null\n      this.#emit()\n    } catch (error) {\n      if (isByokCeremonyCancel(error)) {\n        const provider = this.#lockedProvider()\n        if (provider) {\n          this.request(provider, 'locked')\n          throw new ByokBlockedError(provider, 'locked')\n        }\n      }\n      this.#storageError = errorMessage(error, 'Failed to unlock keyring')\n      this.#emit()\n      throw error instanceof Error ? error : new Error(String(error))\n    }\n  }\n\n  #lockedProvider(): ProviderId | undefined {\n    if (this.#prompt && isProviderId(this.#prompt.provider)) {\n      return this.#prompt.provider\n    }\n    for (const [id, status] of Object.entries(this.#statuses)) {\n      if (status?.state === 'locked' && isProviderId(id)) return id\n    }\n    return undefined\n  }\n\n  async #hydrate(): Promise<void> {\n    if (this.storage.unlockable) {\n      if (!this.storage.peek) return\n      try {\n        const preview = await this.storage.peek()\n        for (const [id, last4] of Object.entries(preview)) {\n          if (!isProviderId(id) || this.#statuses[id]) continue\n          this.#statuses[id] = {\n            state: 'locked',\n            masked: last4 ? last4 : '••',\n          }\n        }\n        this.#locked = Object.keys(preview).length > 0\n        this.#storageError = null\n        this.#emit()\n      } catch (error) {\n        this.#storageError = errorMessage(error, 'Failed to read keyring')\n        this.#emit()\n      }\n      return\n    }\n    try {\n      const loaded = sanitizeKeyring(await this.storage.load())\n      this.#keys = { ...loaded, ...this.#keys }\n      for (const [id, value] of Object.entries(loaded)) {\n        if (!isProviderId(id) || !value) continue\n        this.#statuses[id] = { state: 'set', masked: maskKey(value) }\n      }\n      this.#storageError = null\n      this.#emit()\n    } catch (error) {\n      this.#storageError = errorMessage(error, 'Failed to read keyring')\n      this.#emit()\n    }\n  }\n\n  #emit(): void {\n    this.#snapshot = this.#buildSnapshot()\n    for (const listener of this.#listeners) listener()\n  }\n}\n\nexport function defineByok(options: DefineByokOptions = {}): ByokClient {\n  return new ByokClient(options)\n}\n"],"mappings":"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"}

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

@@ -58,6 +58,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private readonly clearedStreamTracker;
     private currentRunId;
     private lastResume;
+    private readonly runParents;
+    private readonly supersededInterruptRunIds;
     private rejoinedRunId;
     private readonly interruptManager;
     private activeInterruptSubmission;
@@ -144,6 +146,16 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     /** Constructor inputs `attach()` needs on every re-attach, not just the first. */
     private readonly rejoinRunId;
     private readonly cachesMessages;
+    /**
+     * Newest-window size from `history.pageSize`. Only set when
+     * `persistence === true`.
+     */
+    private readonly historyPageSize;
+    private hasOlderMessages;
+    private olderMessagesCursor;
+    private readonly knownServerMessageIds;
+    private loadOlderMessagesInFlight;
+    private historyGeneration;
     private devtoolsMounted;
     private readonly callbacksRef;
     constructor(options: ChatClientOptions<TTools, TContext, TInterrupts>);
@@ -222,6 +234,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * state. This is interrupt (state) resume — there is no delivery cursor.
      */
     private observeInterruptState;
+    /** Walk parentRunId links and mark this run plus its ancestors as answered. */
+    private markLineageAnswered;
     /**
      * 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
@@ -470,6 +484,23 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * Get current messages
      */
     getMessages(): Array<UIMessage<TTools>>;
+    /**
+     * True when the last hydrate or older-page response said more messages exist.
+     */
+    getHasOlderMessages(): boolean;
+    /**
+     * Fetch the next older window and put it in front of the painted messages.
+     *
+     * No-op when there is no older page, no cursor, or a page load is already
+     * running. A network failure rejects and leaves the painted messages as they
+     * are; {@link getHasOlderMessages} stays true.
+     */
+    loadOlderMessages(): Promise<void>;
+    private resetHistoryPaging;
+    private applyHydrationPage;
+    private rememberServerMessageIds;
+    private rememberProcessorMessageIds;
+    private messagesForSend;
     /**
      * True when an interrupt (or another direct send) claimed the client during
      * a drain. Read via a method so cross-await mutations are not constant-folded

package/dist/esm/chat-client.js

@@ -1,3 +1,4 @@
+import { byokFallbackProviderId } from "./byok/client.js";
 import { prepareResolvedByokHeaders, resolveByokProviderId } from "./byok/resolve.js";
 import { createNoOpChatDevtoolsBridge } from "./devtools-noop.js";
 import { normalizeMessagesDates } from "./message-date-normalizer.js";
@@ -140,6 +141,7 @@ var REJOIN_REBUILD_TRIGGERS = /* @__PURE__ */ new Set([
 	"TOOL_CALL_START",
 	"MESSAGES_SNAPSHOT"
 ]);
+var MAX_RUN_LINEAGE_DEPTH = 64;
 var ChatClient = class {
 	processor;
 	connection;
@@ -149,6 +151,8 @@ var ChatClient = class {
 	clearedStreamTracker = new ClearedStreamTracker();
 	currentRunId = null;
 	lastResume = null;
+	runParents = /* @__PURE__ */ new Map();
+	supersededInterruptRunIds = /* @__PURE__ */ new Set();
 	rejoinedRunId = null;
 	interruptManager;
 	activeInterruptSubmission;
@@ -235,6 +239,16 @@ var ChatClient = class {
 	/** Constructor inputs `attach()` needs on every re-attach, not just the first. */
 	rejoinRunId;
 	cachesMessages;
+	/**
+	* Newest-window size from `history.pageSize`. Only set when
+	* `persistence === true`.
+	*/
+	historyPageSize;
+	hasOlderMessages = false;
+	olderMessagesCursor;
+	knownServerMessageIds = /* @__PURE__ */ new Set();
+	loadOlderMessagesInFlight = false;
+	historyGeneration = 0;
 	devtoolsMounted = false;
 	callbacksRef;
 	constructor(options) {
@@ -245,10 +259,12 @@ var ChatClient = class {
 		if (options.persistence === true) {
 			if (!options.threadId) throw new Error("[TanStack AI] persistence needs a stable `threadId` to key on. Pass a threadId from your app (for example support-42).");
 			cachesMessages = false;
+			this.historyPageSize = options.history?.pageSize;
 		} else if (options.persistence) {
 			if (!options.threadId) throw new Error("[TanStack AI] persistence needs a stable `threadId` to key on. Pass a threadId from your app (for example support-42).");
 			this.persistor = new ChatPersistor(options.persistence, options.threadId, (messages) => this.processor.setMessages(messages), (snapshot) => this.applyPersistedResume(snapshot));
-		}
+			this.historyPageSize = void 0;
+		} else this.historyPageSize = void 0;
 		this.bodyOption = options.body || {};
 		this.forwardedPropsOption = options.forwardedProps || {};
 		this.byok = options.byok;
@@ -506,16 +522,25 @@ var ChatClient = class {
 		if (!hydrate) return;
 		if (this.isLoading || this.abortController) return;
 		if (this.disposed) return;
+		const pageSize = this.historyPageSize;
+		const hydrateOptions = pageSize === void 0 ? void 0 : { limit: pageSize };
 		(async () => {
 			let result;
+			const generation = this.historyGeneration;
 			try {
-				result = await hydrate(this.threadId);
+				result = await hydrate(this.threadId, hydrateOptions);
 			} catch {
 				return;
 			}
+			if (generation !== this.historyGeneration) return;
 			if (this.disposed || !this.tailing) return;
 			if (this.isLoading || this.abortController) return;
-			if (result.messages.length > 0) this.processor.setMessages(normalizeMessagesDates(result.messages));
+			this.applyHydrationPage(result.page);
+			if (result.messages.length > 0) {
+				const windowMessages = normalizeMessagesDates(result.messages);
+				this.processor.setMessages(windowMessages);
+				this.rememberServerMessageIds(windowMessages);
+			}
 			if (result.interrupts && result.interrupts.pending.length > 0) this.applyResumeSnapshot({
 				resumeState: {
 					threadId: this.threadId,
@@ -561,15 +586,28 @@ var ChatClient = class {
 	updateRunLifecycle(chunk, options) {
 		if (chunk.type === "RUN_STARTED") {
 			const chunkRunId = getChunkRunId$1(chunk) ?? chunk.runId;
+			const parentRunId = "parentRunId" in chunk && typeof chunk.parentRunId === "string" ? chunk.parentRunId : void 0;
+			if (parentRunId) {
+				this.runParents.set(chunkRunId, parentRunId);
+				if (this.supersededInterruptRunIds.has(chunkRunId)) this.markLineageAnswered(parentRunId);
+			}
 			this.activeResumeThreadId = "threadId" in chunk && typeof chunk.threadId === "string" ? chunk.threadId : this.activeResumeThreadId;
 			this.activeResumeRunId = chunkRunId;
-			this.activeRunIds.add(chunkRunId);
-			this.clearedStreamTracker.onRunStarted(chunkRunId);
-			this.setSessionGenerating(true);
-			if (this.persistor && this.connection.joinRun && !this.lastResume) this.persistResumeSnapshot({
+			const isAnsweredReplayStart = this.supersededInterruptRunIds.has(chunkRunId) && !this.isLoading;
+			if (!isAnsweredReplayStart) {
+				this.activeRunIds.add(chunkRunId);
+				this.clearedStreamTracker.onRunStarted(chunkRunId);
+				this.setSessionGenerating(true);
+			}
+			if (this.persistor && this.connection.joinRun && !this.lastResume && !isAnsweredReplayStart) this.persistResumeSnapshot({
 				threadId: this.activeResumeThreadId ?? this.threadId,
 				runId: chunkRunId
 			});
+			if (this.lastResume && this.supersededInterruptRunIds.has(this.lastResume.runId)) {
+				this.lastResume = null;
+				this.persistor?.persistResumeSnapshot(null);
+				this.interruptManager.reset();
+			}
 			return;
 		}
 		if (chunk.type !== "RUN_FINISHED" && chunk.type !== "RUN_ERROR") return;
@@ -596,8 +634,10 @@ var ChatClient = class {
 		if (this.activeInterruptSubmission && chunk.type === "RUN_ERROR") return;
 		const runId = getChunkRunId$1(chunk);
 		const threadId = "threadId" in chunk && typeof chunk.threadId === "string" ? chunk.threadId : this.activeResumeThreadId;
+		if (runId && !isIntermediateToolTurn(chunk) && (chunk.type === "RUN_ERROR" || chunk.type === "RUN_FINISHED" && chunk.outcome?.type !== "interrupt")) this.markLineageAnswered(runId);
 		if (chunk.type === "RUN_FINISHED" && chunk.outcome?.type === "interrupt") {
 			const interruptedRunId = this.currentRunId ?? runId ?? this.activeResumeRunId ?? "";
+			if (interruptedRunId && this.supersededInterruptRunIds.has(interruptedRunId)) return;
 			this.lastResume = {
 				threadId: threadId ?? this.threadId,
 				runId: interruptedRunId
@@ -616,7 +656,8 @@ var ChatClient = class {
 		const isActiveStreamRunTerminal = Boolean(this.isLoading && runId && (runId === this.activeResumeRunId || runId === this.currentRunId));
 		const isCurrentStreamTerminal = this.isLoading && chunk.type === "RUN_FINISHED" && !runId;
 		const isActiveInterruptSubmissionTerminal = Boolean(this.activeInterruptSubmission && this.isLoading && chunk.type === "RUN_FINISHED" && chunk.outcome?.type !== "interrupt");
-		if (isRunlessSessionError || isTrackedRunTerminal || isCurrentRunTerminal || isActiveStreamRunTerminal || isCurrentStreamTerminal || isActiveInterruptSubmissionTerminal) {
+		const isLineageDescendantTerminal = Boolean(this.lastResume && this.supersededInterruptRunIds.has(this.lastResume.runId));
+		if (isRunlessSessionError || isTrackedRunTerminal || isCurrentRunTerminal || isActiveStreamRunTerminal || isCurrentStreamTerminal || isActiveInterruptSubmissionTerminal || isLineageDescendantTerminal) {
 			this.lastResume = null;
 			this.persistor?.persistResumeSnapshot(null);
 			this.interruptManager.reset();
@@ -624,6 +665,17 @@ var ChatClient = class {
 		}
 		this.notifyResumeStateChange("live");
 	}
+	/** Walk parentRunId links and mark this run plus its ancestors as answered. */
+	markLineageAnswered(runId) {
+		let current = runId;
+		let hops = 0;
+		while (current !== void 0 && hops < MAX_RUN_LINEAGE_DEPTH) {
+			if (this.supersededInterruptRunIds.has(current)) return;
+			this.supersededInterruptRunIds.add(current);
+			current = this.runParents.get(current);
+			hops++;
+		}
+	}
 	/**
 	* 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
@@ -1275,7 +1327,7 @@ var ChatClient = class {
 		let activeDevtoolsRunId = null;
 		let runTerminalEventEmitted = false;
 		try {
-			const messages = this.processor.getMessages();
+			const messages = this.messagesForSend(this.processor.getMessages());
 			const clientTools = new Map(this.clientToolsRef.current);
 			const runtimeContext = this.context;
 			await this.callbacksRef.current.onResponse();
@@ -1296,7 +1348,7 @@ var ChatClient = class {
 			const processingComplete = this.waitForProcessing();
 			let byokHeaders;
 			if (this.byok) {
-				const provider = resolveByokProviderId(this.byokProvider, mergedBody.provider);
+				const provider = resolveByokProviderId(this.byokProvider, mergedBody.provider, byokFallbackProviderId(this.byok));
 				byokHeaders = await prepareResolvedByokHeaders(this.byok, provider);
 			}
 			const runContext = {
@@ -1368,6 +1420,7 @@ var ChatClient = class {
 				}
 				await this.drainPostStreamActions();
 				if (streamCompletedSuccessfully) {
+					this.rememberProcessorMessageIds();
 					if (this.status !== "ready") this.setStatus("ready");
 					if (!this.messageQueueDraining) await this.drainQueue();
 				} else this.flushQueue();
@@ -1446,6 +1499,7 @@ var ChatClient = class {
 		} else if (this.activeRunIds.size > 0) this.resetSessionGenerating({ preserveClearedStreamTracking: true });
 		this.persistor?.beginClear();
 		this.processor.clearMessages();
+		this.resetHistoryPaging();
 		this.discardPendingSends();
 		this.persistor?.remove();
 		this.lastResume = null;
@@ -1586,6 +1640,79 @@ var ChatClient = class {
 		return this.processor.getMessages();
 	}
 	/**
+	* True when the last hydrate or older-page response said more messages exist.
+	*/
+	getHasOlderMessages() {
+		return this.hasOlderMessages;
+	}
+	/**
+	* Fetch the next older window and put it in front of the painted messages.
+	*
+	* No-op when there is no older page, no cursor, or a page load is already
+	* running. A network failure rejects and leaves the painted messages as they
+	* are; {@link getHasOlderMessages} stays true.
+	*/
+	async loadOlderMessages() {
+		const hydrate = this.connection.hydrate;
+		if (hydrate === void 0) return;
+		if (this.disposed) return;
+		if (!this.hasOlderMessages) return;
+		const cursor = this.olderMessagesCursor;
+		if (cursor === void 0) return;
+		if (this.loadOlderMessagesInFlight) return;
+		const hydrateOptions = { before: cursor };
+		if (this.historyPageSize !== void 0) hydrateOptions.limit = this.historyPageSize;
+		this.loadOlderMessagesInFlight = true;
+		const generation = this.historyGeneration;
+		try {
+			const result = await hydrate(this.threadId, hydrateOptions);
+			if (this.disposed) return;
+			if (generation !== this.historyGeneration) return;
+			const olderMessages = normalizeMessagesDates(result.messages);
+			if (olderMessages.length === 0) throw new Error("Older page was empty");
+			this.applyHydrationPage(result.page);
+			this.processor.prependMessages(olderMessages);
+			this.rememberServerMessageIds(olderMessages);
+		} finally {
+			this.loadOlderMessagesInFlight = false;
+		}
+	}
+	resetHistoryPaging() {
+		this.hasOlderMessages = false;
+		this.olderMessagesCursor = void 0;
+		this.knownServerMessageIds.clear();
+		this.historyGeneration++;
+	}
+	applyHydrationPage(page) {
+		if (page?.truncated === true) {
+			this.hasOlderMessages = true;
+			this.olderMessagesCursor = page.cursor;
+			return;
+		}
+		this.hasOlderMessages = false;
+		this.olderMessagesCursor = void 0;
+	}
+	rememberServerMessageIds(messages) {
+		const ids = messages.map((message) => message.id);
+		for (const id of ids) this.knownServerMessageIds.add(id);
+	}
+	rememberProcessorMessageIds() {
+		if (this.historyPageSize === void 0) return;
+		this.rememberServerMessageIds(this.processor.getMessages());
+	}
+	messagesForSend(messages) {
+		if (this.historyPageSize === void 0) return messages;
+		const unknownMessages = [];
+		for (const message of messages) {
+			if (this.knownServerMessageIds.has(message.id)) continue;
+			unknownMessages.push(message);
+		}
+		if (unknownMessages.length > 0) return unknownMessages;
+		const lastUserIndex = messages.findLastIndex((message) => message.role === "user");
+		if (lastUserIndex === -1) return [];
+		return messages.slice(lastUserIndex);
+	}
+	/**
 	* True when an interrupt (or another direct send) claimed the client during
 	* a drain. Read via a method so cross-await mutations are not constant-folded
 	* by control-flow analysis.