@tanstack/ai-client 0.26.0 → 0.28.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"passkey.js","names":[],"sources":["../../../src/byok/passkey.ts"],"sourcesContent":["import { isProviderId } from '@tanstack/ai/byok'\nimport { memoryStorage } from './storage'\nimport type { KeyPreview, Keyring, KeyringStorage } from './storage'\n\n/**\n * Passkey-encrypted keyring storage (WebAuthn PRF → HKDF → AES-256-GCM).\n *\n * The keyring is encrypted at rest in IndexedDB with an AES-256-GCM key derived\n * from a passkey's PRF output, unwrapped on demand with a biometric/PIN tap.\n * Decryption happens entirely client-side with the user present — no server,\n * no custodian.\n *\n * Honest scope: this protects against at-rest theft (stolen device,\n * storage-dumping extension, backups). It does NOT defeat live in-page XSS —\n * an attacker running JS in the origin after the user unlocks can read the\n * decrypted keys from memory.\n */\n\nconst STORE_NAME = 'keyring'\nconst RECORD_ID = 'default'\nconst HKDF_INFO = 'byok:keyring:v1'\nconst DEFAULT_DB = 'byok'\n\ninterface StoredRecord {\n  id: string\n  /** The passkey's raw credential id, replayed in the unlock ceremony. */\n  credentialId: ArrayBuffer\n  /** Fixed per-install PRF evaluation input (not secret). */\n  salt: ArrayBuffer\n  /** AES-GCM initialization vector for this ciphertext. */\n  iv: ArrayBuffer\n  /** Encrypted keyring JSON. */\n  ciphertext: ArrayBuffer\n  /**\n   * Unencrypted presence metadata (`provider → last 4`). Non-sensitive, so it\n   * can be read via {@link KeyringStorage.peek} without an unlock ceremony to\n   * show saved keys as \"locked\" after a refresh.\n   */\n  preview: KeyPreview\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\n/** Build the non-sensitive `provider → last 4` preview from a keyring. */\nfunction previewOf(keys: Keyring): KeyPreview {\n  const preview: KeyPreview = {}\n  for (const [provider, key] of Object.entries(keys)) {\n    if (!key || !isProviderId(provider)) continue\n    // Keys of length ≤ 4 would make last-4 the whole secret — store presence only.\n    preview[provider] = key.length > 4 ? key.slice(-4) : ''\n  }\n  return preview\n}\n\n/**\n * Whether the current environment exposes WebAuthn. Actual PRF support can\n * only be confirmed during registration; `passkeyStorage` throws if the\n * chosen authenticator does not support PRF.\n */\nexport function isPasskeyStorageSupported(): boolean {\n  return (\n    typeof globalThis !== 'undefined' &&\n    typeof globalThis.PublicKeyCredential !== 'undefined' &&\n    typeof globalThis.navigator !== 'undefined' &&\n    typeof globalThis.navigator.credentials.create === 'function'\n  )\n}\n\n// ---------------------------------------------------------------------------\n// Crypto (exported for testing; the WebAuthn ceremony below feeds `deriveAesKey`)\n// ---------------------------------------------------------------------------\n\n/** Derive a non-extractable AES-256-GCM key from a 32-byte PRF output. */\nexport async function deriveAesKey(\n  prfOutput: BufferSource,\n): Promise<CryptoKey> {\n  const base = await crypto.subtle.importKey('raw', prfOutput, 'HKDF', false, [\n    'deriveKey',\n  ])\n  return crypto.subtle.deriveKey(\n    {\n      name: 'HKDF',\n      hash: 'SHA-256',\n      salt: new Uint8Array(0),\n      info: new TextEncoder().encode(HKDF_INFO),\n    },\n    base,\n    { name: 'AES-GCM', length: 256 },\n    false,\n    ['encrypt', 'decrypt'],\n  )\n}\n\nexport async function encryptKeyring(\n  key: CryptoKey,\n  keys: Keyring,\n): Promise<{ iv: ArrayBuffer; ciphertext: ArrayBuffer }> {\n  const iv = crypto.getRandomValues(new Uint8Array(12))\n  const plaintext = new TextEncoder().encode(JSON.stringify(keys))\n  const ciphertext = await crypto.subtle.encrypt(\n    { name: 'AES-GCM', iv },\n    key,\n    plaintext,\n  )\n  return { iv: iv.buffer, ciphertext }\n}\n\nexport async function decryptKeyring(\n  key: CryptoKey,\n  iv: BufferSource,\n  ciphertext: BufferSource,\n): Promise<Keyring> {\n  const plaintext = await crypto.subtle.decrypt(\n    { name: 'AES-GCM', iv },\n    key,\n    ciphertext,\n  )\n  const parsed: unknown = JSON.parse(new TextDecoder().decode(plaintext))\n  return sanitizeKeyring(parsed)\n}\n\n// ---------------------------------------------------------------------------\n// IndexedDB\n// ---------------------------------------------------------------------------\n\nfunction openDb(dbName: string): Promise<IDBDatabase> {\n  return new Promise((resolve, reject) => {\n    const request = indexedDB.open(dbName, 1)\n    request.onupgradeneeded = () => {\n      request.result.createObjectStore(STORE_NAME, { keyPath: 'id' })\n    }\n    request.onsuccess = () => resolve(request.result)\n    request.onerror = () => reject(request.error)\n  })\n}\n\nfunction idbGet(dbName: string): Promise<StoredRecord | null> {\n  return openDb(dbName).then(\n    (db) =>\n      new Promise((resolve, reject) => {\n        const request = db\n          .transaction(STORE_NAME, 'readonly')\n          .objectStore(STORE_NAME)\n          .get(RECORD_ID)\n        request.onsuccess = () => resolve(request.result ?? null)\n        request.onerror = () => reject(request.error)\n      }),\n  )\n}\n\nfunction idbPut(dbName: string, record: StoredRecord): Promise<void> {\n  return openDb(dbName).then(\n    (db) =>\n      new Promise((resolve, reject) => {\n        const tx = db.transaction(STORE_NAME, 'readwrite')\n        tx.objectStore(STORE_NAME).put(record)\n        tx.oncomplete = () => resolve()\n        tx.onerror = () => reject(tx.error)\n      }),\n  )\n}\n\nfunction idbClear(dbName: string): Promise<void> {\n  return openDb(dbName).then(\n    (db) =>\n      new Promise((resolve, reject) => {\n        const tx = db.transaction(STORE_NAME, 'readwrite')\n        tx.objectStore(STORE_NAME).delete(RECORD_ID)\n        tx.oncomplete = () => resolve()\n        tx.onerror = () => reject(tx.error)\n      }),\n  )\n}\n\n// ---------------------------------------------------------------------------\n// WebAuthn ceremonies\n// ---------------------------------------------------------------------------\n\nfunction requirePublicKeyCredential(\n  credential: Credential | null,\n  action: string,\n): PublicKeyCredential {\n  if (!credential) throw new Error(`Passkey ${action} was cancelled`)\n  if (!(credential instanceof PublicKeyCredential)) {\n    throw new Error(`Unexpected credential type during ${action}`)\n  }\n  return credential\n}\n\nasync function registerPasskey(\n  rpName: string,\n  userName: string,\n  rpId?: string,\n): Promise<{\n  credentialId: ArrayBuffer\n  salt: Uint8Array<ArrayBuffer>\n  prf?: BufferSource\n}> {\n  const salt = crypto.getRandomValues(new Uint8Array(32))\n  const credential = requirePublicKeyCredential(\n    await navigator.credentials.create({\n      publicKey: {\n        challenge: crypto.getRandomValues(new Uint8Array(32)),\n        // Omit `id` to let the browser bind the passkey to the current origin's\n        // effective domain; set it to scope across subdomains of a self-host.\n        rp: rpId ? { name: rpName, id: rpId } : { name: rpName },\n        user: {\n          id: crypto.getRandomValues(new Uint8Array(16)),\n          name: userName,\n          displayName: userName,\n        },\n        pubKeyCredParams: [\n          { type: 'public-key', alg: -7 },\n          { type: 'public-key', alg: -257 },\n        ],\n        authenticatorSelection: {\n          residentKey: 'required',\n          userVerification: 'required',\n        },\n        extensions: { prf: { eval: { first: salt } } },\n      },\n    }),\n    'registration',\n  )\n\n  const prf = credential.getClientExtensionResults().prf\n  if (!prf?.enabled) {\n    throw new Error(\n      'This authenticator does not support the WebAuthn PRF extension',\n    )\n  }\n  return { credentialId: credential.rawId, salt, prf: prf.results?.first }\n}\n\nasync function evaluatePrf(\n  credentialId: BufferSource,\n  salt: BufferSource,\n): Promise<BufferSource> {\n  const credential = requirePublicKeyCredential(\n    await navigator.credentials.get({\n      publicKey: {\n        challenge: crypto.getRandomValues(new Uint8Array(32)),\n        allowCredentials: [{ type: 'public-key', id: credentialId }],\n        userVerification: 'required',\n        extensions: { prf: { eval: { first: salt } } },\n      },\n    }),\n    'unlock',\n  )\n  const result = credential.getClientExtensionResults().prf?.results?.first\n  if (!result) {\n    throw new Error('Authenticator did not return a PRF result')\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// Storage strategy\n// ---------------------------------------------------------------------------\n\nexport interface PasskeyStorageOptions {\n  /** Relying-party name shown in the passkey prompt. */\n  rpName?: string\n  /** Username label attached to the created passkey. */\n  userName?: string\n  /**\n   * WebAuthn Relying Party ID. Omit to bind the passkey to the current origin's\n   * effective domain (the default — no central/hardcoded domain). Set it to a\n   * registrable parent domain to share the credential across subdomains of your\n   * own deployment. The encrypted keyring is never portable across unrelated\n   * domains.\n   */\n  rpId?: string\n  /** IndexedDB database name. Defaults to `byok`. */\n  dbName?: string\n}\n\n/**\n * Passkey-encrypted persistence. `ByokClient` treats this as `unlockable`, so\n * nothing is decrypted until the user calls `unlock()` (or saves a key, which\n * registers a passkey on first use). The derived key is cached in memory for\n * the session so repeated saves don't re-prompt.\n */\nexport function passkeyStorage(\n  options: PasskeyStorageOptions = {},\n): KeyringStorage {\n  const rpName = options.rpName ?? 'BYOK'\n  const userName = options.userName ?? 'byok-keyring'\n  const { rpId } = options\n  const dbName = options.dbName ?? DEFAULT_DB\n\n  let cachedKey: CryptoKey | null = null\n  let cachedMeta: {\n    credentialId: ArrayBuffer\n    salt: Uint8Array<ArrayBuffer>\n  } | null = null\n\n  // Obtain the AES key, running exactly one WebAuthn ceremony if it isn't\n  // already cached for this session (unlock if a passkey exists, else register).\n  async function ensureKey(): Promise<{\n    key: CryptoKey\n    credentialId: ArrayBuffer\n    salt: Uint8Array<ArrayBuffer>\n  }> {\n    if (cachedKey && cachedMeta) {\n      return { key: cachedKey, ...cachedMeta }\n    }\n    const existing = await idbGet(dbName)\n    if (existing) {\n      const prf = await evaluatePrf(existing.credentialId, existing.salt)\n      cachedKey = await deriveAesKey(prf)\n      cachedMeta = {\n        credentialId: existing.credentialId,\n        salt: new Uint8Array(existing.salt),\n      }\n    } else {\n      const reg = await registerPasskey(rpName, userName, rpId)\n      const prf = reg.prf ?? (await evaluatePrf(reg.credentialId, reg.salt))\n      cachedKey = await deriveAesKey(prf)\n      cachedMeta = { credentialId: reg.credentialId, salt: reg.salt }\n    }\n    return { key: cachedKey, ...cachedMeta }\n  }\n\n  return {\n    id: 'passkey',\n    label: 'Passkey-encrypted (this device)',\n    persistent: true,\n    unlockable: true,\n    warning:\n      'Keys are encrypted with your passkey and unlocked with biometrics. ' +\n      'This protects saved keys if your device is stolen, but not against code ' +\n      'running on this page after you unlock.',\n    peek: async () => {\n      // Unencrypted last-4 sidecar — no key material, no unlock ceremony.\n      const existing = await idbGet(dbName)\n      return existing?.preview ?? {}\n    },\n    load: async () => {\n      const existing = await idbGet(dbName)\n      if (!existing) return {}\n      const { key } = await ensureKey()\n      return decryptKeyring(key, existing.iv, existing.ciphertext)\n    },\n    save: async (keys) => {\n      const existing = await idbGet(dbName)\n      const hasKeys = Object.values(keys).some(Boolean)\n      // First save with an empty keyring is a no-op — avoids a passkey ceremony\n      // when another storage tier writes an empty ring.\n      if (!hasKeys && !existing) return\n\n      const { key, credentialId, salt } = await ensureKey()\n      const { iv, ciphertext } = await encryptKeyring(key, keys)\n      await idbPut(dbName, {\n        id: RECORD_ID,\n        credentialId,\n        salt: salt.buffer,\n        iv,\n        ciphertext,\n        preview: previewOf(keys),\n      })\n    },\n    clear: async () => {\n      cachedKey = null\n      cachedMeta = null\n      await idbClear(dbName)\n    },\n  }\n}\n\n/**\n * Passkey-encrypted storage when WebAuthn is available in a secure context.\n * Otherwise session memory, with a warning — this is not an automatic PRF\n * fallback. First save still throws if the authenticator lacks PRF.\n */\nexport function defaultByokStorage(\n  options?: PasskeyStorageOptions,\n): KeyringStorage {\n  const secure =\n    typeof globalThis.isSecureContext !== 'boolean' ||\n    globalThis.isSecureContext\n  if (!isPasskeyStorageSupported() || !secure) {\n    return {\n      ...memoryStorage(),\n      warning:\n        'Passkeys are unavailable in this context. Keys stay in memory for this tab only.',\n    }\n  }\n  return passkeyStorage(options)\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,8 @@
+import { ProviderId } from '@tanstack/ai/byok';
+import { ByokClient } from './client.js';
+export declare function resolveByokProviderId(byokProvider: (() => string | undefined) | undefined, ...candidates: Array<unknown>): ProviderId | undefined;
+/**
+ * Prepare and stamp headers for one resolved slug. Throws instead of
+ * attaching every stored key when the slug is missing.
+ */
+export declare function prepareResolvedByokHeaders(byok: ByokClient, provider: ProviderId | undefined): Promise<Record<string, string>>;

package/dist/esm/byok/resolve.js

@@ -0,0 +1,20 @@
+import { ByokUnresolvedProviderError, isProviderId } from "@tanstack/ai/byok";
+//#region src/byok/resolve.ts
+function resolveByokProviderId(byokProvider, ...candidates) {
+	const fromFn = byokProvider?.();
+	if (isProviderId(fromFn)) return fromFn;
+	for (const candidate of candidates) if (isProviderId(candidate)) return candidate;
+}
+/**
+* Prepare and stamp headers for one resolved slug. Throws instead of
+* attaching every stored key when the slug is missing.
+*/
+async function prepareResolvedByokHeaders(byok, provider) {
+	if (!provider) throw new ByokUnresolvedProviderError();
+	await byok.prepare(provider);
+	return byok.headers(provider);
+}
+//#endregion
+export { prepareResolvedByokHeaders, resolveByokProviderId };
+
+//# sourceMappingURL=resolve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","names":[],"sources":["../../../src/byok/resolve.ts"],"sourcesContent":["import { ByokUnresolvedProviderError, isProviderId } from '@tanstack/ai/byok'\nimport type { ProviderId } from '@tanstack/ai/byok'\nimport type { ByokClient } from './client'\n\nexport function resolveByokProviderId(\n  byokProvider: (() => string | undefined) | undefined,\n  ...candidates: Array<unknown>\n): ProviderId | undefined {\n  const fromFn = byokProvider?.()\n  if (isProviderId(fromFn)) return fromFn\n  for (const candidate of candidates) {\n    if (isProviderId(candidate)) return candidate\n  }\n  return undefined\n}\n\n/**\n * Prepare and stamp headers for one resolved slug. Throws instead of\n * attaching every stored key when the slug is missing.\n */\nexport async function prepareResolvedByokHeaders(\n  byok: ByokClient,\n  provider: ProviderId | undefined,\n): Promise<Record<string, string>> {\n  if (!provider) {\n    throw new ByokUnresolvedProviderError()\n  }\n  await byok.prepare(provider)\n  return byok.headers(provider)\n}\n"],"mappings":";;AAIA,SAAgB,sBACd,cACA,GAAG,YACqB;CACxB,MAAM,SAAS,eAAe;CAC9B,IAAI,aAAa,MAAM,GAAG,OAAO;CACjC,KAAK,MAAM,aAAa,YACtB,IAAI,aAAa,SAAS,GAAG,OAAO;AAGxC;;;;;AAMA,eAAsB,2BACpB,MACA,UACiC;CACjC,IAAI,CAAC,UACH,MAAM,IAAI,4BAA4B;CAExC,MAAM,KAAK,QAAQ,QAAQ;CAC3B,OAAO,KAAK,QAAQ,QAAQ;AAC9B"}

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

@@ -0,0 +1,15 @@
+import { ProviderId } from '@tanstack/ai/byok';
+export type Keyring = Partial<Record<ProviderId, string>>;
+export type KeyPreview = Partial<Record<ProviderId, string>>;
+export interface KeyringStorage {
+    readonly id: string;
+    readonly label: string;
+    readonly persistent: boolean;
+    readonly unlockable?: boolean;
+    readonly warning?: string;
+    peek?: () => KeyPreview | Promise<KeyPreview>;
+    load: () => Keyring | Promise<Keyring>;
+    save: (keys: Keyring) => void | Promise<void>;
+    clear: () => void | Promise<void>;
+}
+export declare function memoryStorage(): KeyringStorage;

package/dist/esm/byok/storage.js

@@ -0,0 +1,16 @@
+//#region src/byok/storage.ts
+function memoryStorage() {
+	return {
+		id: "memory",
+		label: "Session only (not saved)",
+		persistent: false,
+		warning: "Keys stay in memory for this tab only. They are not saved across reloads.",
+		load: () => ({}),
+		save: () => {},
+		clear: () => {}
+	};
+}
+//#endregion
+export { memoryStorage };
+
+//# sourceMappingURL=storage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../../../src/byok/storage.ts"],"sourcesContent":["import type { ProviderId } from '@tanstack/ai/byok'\n\nexport type Keyring = Partial<Record<ProviderId, string>>\nexport type KeyPreview = Partial<Record<ProviderId, string>>\n\nexport interface KeyringStorage {\n  readonly id: string\n  readonly label: string\n  readonly persistent: boolean\n  readonly unlockable?: boolean\n  readonly warning?: string\n  peek?: () => KeyPreview | Promise<KeyPreview>\n  load: () => Keyring | Promise<Keyring>\n  save: (keys: Keyring) => void | Promise<void>\n  clear: () => void | Promise<void>\n}\n\nexport function memoryStorage(): KeyringStorage {\n  return {\n    id: 'memory',\n    label: 'Session only (not saved)',\n    persistent: false,\n    warning:\n      'Keys stay in memory for this tab only. They are not saved across reloads.',\n    load: () => ({}),\n    save: () => {},\n    clear: () => {},\n  }\n}\n"],"mappings":";AAiBA,SAAgB,gBAAgC;CAC9C,OAAO;EACL,IAAI;EACJ,OAAO;EACP,YAAY;EACZ,SACE;EACF,aAAa,CAAC;EACd,YAAY,CAAC;EACb,aAAa,CAAC;CAChB;AACF"}

package/dist/esm/byok.d.ts

@@ -0,0 +1,8 @@
+export { defineByok, ByokClient, EMPTY_BYOK_SNAPSHOT } from './byok/client.js';
+export type { ByokPrompt, ByokSnapshot, DefineByokOptions, KeyStatus, } from './byok/client.js';
+export { defineByokProvider } from '@tanstack/ai/byok';
+export type { ByokProvider, ByokProviderInit } from '@tanstack/ai/byok';
+export { memoryStorage } from './byok/storage.js';
+export type { KeyPreview, Keyring, KeyringStorage } from './byok/storage.js';
+export { defaultByokStorage, decryptKeyring, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, passkeyStorage, } from './byok/passkey.js';
+export type { PasskeyStorageOptions } from './byok/passkey.js';

package/dist/esm/byok.js

@@ -0,0 +1,5 @@
+import { memoryStorage } from "./byok/storage.js";
+import { ByokClient, EMPTY_BYOK_SNAPSHOT, defineByok } from "./byok/client.js";
+import { decryptKeyring, defaultByokStorage, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, passkeyStorage } from "./byok/passkey.js";
+import { defineByokProvider } from "@tanstack/ai/byok";
+export { ByokClient, EMPTY_BYOK_SNAPSHOT, decryptKeyring, defaultByokStorage, defineByok, defineByokProvider, deriveAesKey, encryptKeyring, isPasskeyStorageSupported, memoryStorage, passkeyStorage };

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

@@ -1,4 +1,5 @@
 import { AnyClientTool, InterruptDefinition, ModelMessage, RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client';
+import { ByokClient } from './byok.js';
 import { ConnectionAdapter } from './connection-adapters.js';
 import { BoundInterrupts, ChatClientOptions, ChatClientState, ChatFetcher, ChatInterruptState, ResolvableChatInterrupt, ChatResumeState, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
 type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>, TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> = readonly []> = {
@@ -7,6 +8,8 @@ type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClien
     /** @deprecated Use `forwardedProps` instead. */
     body?: Record<string, any>;
     forwardedProps?: Record<string, any>;
+    byok?: ByokClient;
+    byokProvider?: () => string | undefined;
     tools?: TTools;
     interrupts?: TInterrupts;
     queue?: QueueOption;
@@ -67,6 +70,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private activeResumeRunId;
     private bodyOption;
     private forwardedPropsOption;
+    private byok;
+    private byokProvider;
     private context;
     private pendingMessageBody;
     private queueConfig;
@@ -320,8 +325,12 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      *   - A MultimodalContent object with content array and optional custom ID
      * @param body - Optional body parameters to merge with the client's base body for this request.
      *               Uses shallow merge with per-message body taking priority.
-     * @param sendOptions - Per-call overrides, e.g. `{ whenBusy: 'interrupt' }` to
-     *                      override the configured queue policy for this one send.
+     * @param sendOptions - Per-call overrides. `{ whenBusy }` overrides the
+     *                      queue policy for this one send. `{ body }`
+     *                      shallow-merges with `body` and with the chat-level
+     *                      `body` / `forwardedProps`. `sendOptions.body` wins
+     *                      on key collisions. Framework hooks forward this
+     *                      object as their second argument.
      *
      * @example
      * ```ts
@@ -331,9 +340,13 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * // Text message with custom body params
      * await client.sendMessage('Hello!', { temperature: 0.7 })
      *
-     * // Per-call whenBusy override (body must still be the 2nd arg on ChatClient)
+     * // Per-call whenBusy override
      * await client.sendMessage('Urgent', undefined, { whenBusy: 'interrupt' })
      *
+     * // Per-call body via options. Same effect as the positional arg.
+     * // This is the shape the framework hooks (`useChat`, `injectChat`) forward.
+     * await client.sendMessage('Hello!', undefined, { body: { temperature: 0.7 } })
+     *
      * // Multimodal message with image
      * await client.sendMessage({
      *   content: [

package/dist/esm/chat-client.js

@@ -1,9 +1,11 @@
+import { prepareResolvedByokHeaders, resolveByokProviderId } from "./byok/resolve.js";
 import { createNoOpChatDevtoolsBridge } from "./devtools-noop.js";
 import { fetcherToConnectionAdapter, getChunkRunId as getChunkRunId$1, normalizeConnectionAdapter } from "./connection-adapters.js";
 import { ChatPersistor } from "./client-persistor.js";
 import { ClearedStreamTracker } from "./cleared-stream-tracker.js";
 import { InterruptManager } from "./interrupt-manager.js";
 import { StreamProcessor, convertSchemaToJsonSchema, generateMessageId, isStandardSchema, mergeMetadata, normalizeToUIMessage, parseWithStandardSchema, restoreInboundChunk, tanstackMetadata } from "@tanstack/ai/client";
+import { ByokBlockedError, ByokMissingError, ByokUnresolvedProviderError } from "@tanstack/ai/byok";
 //#region src/chat-client.ts
 function assertUniqueInterruptDefinitions(interrupts) {
 	const ids = /* @__PURE__ */ new Set();
@@ -148,6 +150,8 @@ var ChatClient = class {
 	activeResumeRunId = null;
 	bodyOption = {};
 	forwardedPropsOption = {};
+	byok;
+	byokProvider;
 	context = void 0;
 	pendingMessageBody = void 0;
 	queueConfig;
@@ -228,6 +232,8 @@ var ChatClient = class {
 		}
 		this.bodyOption = options.body || {};
 		this.forwardedPropsOption = options.forwardedProps || {};
+		this.byok = options.byok;
+		this.byokProvider = options.byokProvider;
 		this.context = options.context;
 		this.queueConfig = normalizeQueueOption(options.queue);
 		this.connection = normalizeConnectionAdapter(resolveTransport(options));
@@ -1027,8 +1033,12 @@ var ChatClient = class {
 	*   - A MultimodalContent object with content array and optional custom ID
 	* @param body - Optional body parameters to merge with the client's base body for this request.
 	*               Uses shallow merge with per-message body taking priority.
-	* @param sendOptions - Per-call overrides, e.g. `{ whenBusy: 'interrupt' }` to
-	*                      override the configured queue policy for this one send.
+	* @param sendOptions - Per-call overrides. `{ whenBusy }` overrides the
+	*                      queue policy for this one send. `{ body }`
+	*                      shallow-merges with `body` and with the chat-level
+	*                      `body` / `forwardedProps`. `sendOptions.body` wins
+	*                      on key collisions. Framework hooks forward this
+	*                      object as their second argument.
 	*
 	* @example
 	* ```ts
@@ -1038,9 +1048,13 @@ var ChatClient = class {
 	* // Text message with custom body params
 	* await client.sendMessage('Hello!', { temperature: 0.7 })
 	*
-	* // Per-call whenBusy override (body must still be the 2nd arg on ChatClient)
+	* // Per-call whenBusy override
 	* await client.sendMessage('Urgent', undefined, { whenBusy: 'interrupt' })
 	*
+	* // Per-call body via options. Same effect as the positional arg.
+	* // This is the shape the framework hooks (`useChat`, `injectChat`) forward.
+	* await client.sendMessage('Hello!', undefined, { body: { temperature: 0.7 } })
+	*
 	* // Multimodal message with image
 	* await client.sendMessage({
 	*   content: [
@@ -1066,11 +1080,15 @@ var ChatClient = class {
 		this.mountDevtools();
 		if (typeof content === "string" && !content.trim()) return;
 		if (this.hasBlockingInterrupts()) throw new Error("ChatClient: cannot send normal input while pending interrupts exist. Use resumeInterrupts() instead.");
+		const resolvedBody = {
+			...body,
+			...sendOptions?.body
+		};
 		if (this.isSendBusy()) {
 			const { action, id } = this.decideWhenBusy(content, sendOptions);
 			if (action === "drop") return;
 			if (action === "queue") {
-				this.enqueueMessage(content, body, id);
+				this.enqueueMessage(content, resolvedBody, id);
 				return;
 			}
 			this.stopMessageQueueDrain = true;
@@ -1079,7 +1097,7 @@ var ChatClient = class {
 			this.resetSessionGenerating();
 		} else this.sendInFlight = true;
 		try {
-			await this.deliverMessage(content, body);
+			await this.deliverMessage(content, resolvedBody);
 		} finally {
 			this.sendInFlight = false;
 		}
@@ -1247,6 +1265,11 @@ var ChatClient = class {
 			this.processor.prepareAssistantMessage();
 			this.ensureSubscription();
 			const processingComplete = this.waitForProcessing();
+			let byokHeaders;
+			if (this.byok) {
+				const provider = resolveByokProviderId(this.byokProvider, mergedBody.provider);
+				byokHeaders = await prepareResolvedByokHeaders(this.byok, provider);
+			}
 			const runContext = {
 				threadId: resumeThreadId ?? this.threadId,
 				runId,
@@ -1257,7 +1280,8 @@ var ChatClient = class {
 					parameters: t.inputSchema ? convertSchemaToJsonSchema(t.inputSchema) : { type: "object" }
 				})),
 				forwardedProps: { ...mergedBody },
-				...resumeItems ? { resume: resumeItems } : {}
+				...resumeItems ? { resume: resumeItems } : {},
+				...byokHeaders ? { headers: byokHeaders } : {}
 			};
 			this.devtoolsBridge.beginRun(runContext.runId, runContext.threadId);
 			activeDevtoolsRunId = runContext.runId;
@@ -1279,22 +1303,24 @@ var ChatClient = class {
 			this.processor.finalizeStream();
 			streamCompletedSuccessfully = true;
 		} catch (err) {
-			if (err instanceof Error) {
-				if (err.name === "AbortError") {
-					if (activeDevtoolsRunId) {
-						this.devtoolsBridge.emitRunLifecycle("run:cancelled", activeDevtoolsRunId, "cancelled");
-						runTerminalEventEmitted = true;
-					}
-					return false;
+			const error = err instanceof Error ? err : new Error(String(err));
+			if (error.name === "AbortError") {
+				if (activeDevtoolsRunId) {
+					this.devtoolsBridge.emitRunLifecycle("run:cancelled", activeDevtoolsRunId, "cancelled");
+					runTerminalEventEmitted = true;
 				}
-				if (generation === this.streamGeneration) {
-					this.reportStreamError(err);
-					if (activeDevtoolsRunId) {
-						this.devtoolsBridge.emitRunLifecycle("run:errored", activeDevtoolsRunId, "errored", { error: err.message });
-						runTerminalEventEmitted = true;
-					}
+				return false;
+			}
+			if (error instanceof ByokMissingError) this.byok?.request(error.provider, "missing");
+			if (error instanceof ByokBlockedError && error.reason === "locked") this.byok?.request(error.provider, "locked");
+			if (generation === this.streamGeneration) {
+				this.reportStreamError(error);
+				if (activeDevtoolsRunId) {
+					this.devtoolsBridge.emitRunLifecycle("run:errored", activeDevtoolsRunId, "errored", { error: error.message });
+					runTerminalEventEmitted = true;
 				}
 			}
+			if (generation === this.streamGeneration && (error instanceof ByokMissingError || error instanceof ByokBlockedError || error instanceof ByokUnresolvedProviderError)) throw error;
 		} finally {
 			if (generation === this.streamGeneration) {
 				this.currentStreamId = null;
@@ -1312,18 +1338,8 @@ var ChatClient = class {
 				}
 				await this.drainPostStreamActions();
 				if (streamCompletedSuccessfully) {
-					const lastPart = this.processor.getMessages().at(-1)?.parts.at(-1);
-					const { finishReason } = this.processor.getState();
-					if (lastPart?.type === "tool-result" && finishReason !== "stop" && this.shouldAutoSend()) try {
-						await this.checkForContinuation();
-					} catch (error) {
-						console.error("Failed to continue flow after tool result:", error);
-						await this.drainQueue();
-					}
-					else {
-						if (this.status !== "ready") this.setStatus("ready");
-						if (!this.messageQueueDraining) await this.drainQueue();
-					}
+					if (this.status !== "ready") this.setStatus("ready");
+					if (!this.messageQueueDraining) await this.drainQueue();
 				} else this.flushQueue();
 			}
 		}
@@ -1680,6 +1696,8 @@ var ChatClient = class {
 		}
 		if (options.body !== void 0) this.bodyOption = options.body;
 		if (options.forwardedProps !== void 0) this.forwardedPropsOption = options.forwardedProps;
+		if (options.byok !== void 0) this.byok = options.byok;
+		if (options.byokProvider !== void 0) this.byokProvider = options.byokProvider;
 		if ("context" in options) this.context = options.context;
 		if (options.tools !== void 0) {
 			this.interruptManager.updateTools(options.tools);