@tanstack/ai-client 0.18.5 → 0.19.0

package/dist/esm/audio-recorder.d.ts

@@ -0,0 +1,76 @@
+import { AudioPart } from '@tanstack/ai/client';
+/** Lifecycle state of an {@link AudioRecorder}. */
+export type AudioRecorderState = 'idle' | 'recording' | 'stopping';
+export interface AudioRecorderOptions {
+    /** Constraints forwarded to `getUserMedia({ audio })`. Defaults to `true`. */
+    audio?: MediaTrackConstraints | boolean;
+    /**
+     * Preferred recorder mime type. Used only when
+     * `MediaRecorder.isTypeSupported` reports it; otherwise the browser default
+     * is used.
+     */
+    mimeType?: string;
+    /** Fired on `getUserMedia` rejection (permission denied) or recorder error. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Resolves the value `stop()` produces from a recorder transform callback.
+ *
+ * - If the callback returns a value — sync or async — that value's awaited type
+ *   is used (a returned `null` is a real value and is preserved).
+ * - If the callback returns nothing (`void`/`undefined`), or is absent, falls
+ *   back to {@link AudioRecording}.
+ *
+ * @template TFn - The transform callback type (or undefined if not provided)
+ */
+export type InferAudioRecordingOutput<TFn> = TFn extends (recording: AudioRecording) => infer R ? [Exclude<Awaited<R>, void | undefined>] extends [never] ? AudioRecording : Exclude<Awaited<R>, void | undefined> : AudioRecording;
+export interface AudioRecording {
+    /** The raw recorded media blob. */
+    blob: Blob;
+    /** Base64 of the recorded bytes (no `data:` prefix). */
+    base64: string;
+    /** The recorder's native mime type, e.g. `audio/webm;codecs=opus`. */
+    mimeType: string;
+    /** Recording length in milliseconds. */
+    durationMs: number;
+    /**
+     * Ready-to-use audio content part for `sendMessage`/generation prompts:
+     * `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`.
+     */
+    part: AudioPart;
+}
+/**
+ * Framework-agnostic browser audio recorder. Wraps `getUserMedia` +
+ * `MediaRecorder`, returns the recorder's native output (no transcode), and
+ * builds a plug-and-play {@link AudioRecording.part}.
+ */
+export declare class AudioRecorder {
+    private readonly options;
+    private recorder;
+    private stream;
+    private chunks;
+    private startedAt;
+    private _state;
+    private starting;
+    private pendingCancel;
+    private readonly listeners;
+    private stopResolve;
+    private stopReject;
+    constructor(options?: AudioRecorderOptions);
+    /** Feature-detect the browser media APIs. SSR/Worker-safe. */
+    static isSupported(): boolean;
+    get state(): AudioRecorderState;
+    subscribe(cb: (state: AudioRecorderState) => void): () => void;
+    private setState;
+    start(): Promise<void>;
+    stop(): Promise<AudioRecording>;
+    cancel(): void;
+    private finalize;
+    private handleError;
+    /** Invoke the user onError callback, isolating a throw so it can't disrupt
+     * internal state teardown or strand a pending promise. */
+    private notifyError;
+    private releaseStream;
+    /** Detach all event handlers so a stale recorder can't mutate our state. */
+    private detachRecorder;
+}

package/dist/esm/audio-recorder.js

@@ -0,0 +1,215 @@
+import { arrayBufferToBase64 } from "@tanstack/ai-utils";
+class AudioRecorder {
+  options;
+  recorder = null;
+  stream = null;
+  chunks = [];
+  startedAt = 0;
+  _state = "idle";
+  // True while start() is awaiting getUserMedia (state is still 'idle' then).
+  starting = false;
+  // Set by cancel()/teardown during that window so start() releases the
+  // freshly acquired stream instead of beginning a leaked recording.
+  pendingCancel = false;
+  listeners = /* @__PURE__ */ new Set();
+  stopResolve = null;
+  stopReject = null;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /** Feature-detect the browser media APIs. SSR/Worker-safe. */
+  static isSupported() {
+    return typeof navigator !== "undefined" && typeof navigator.mediaDevices !== "undefined" && typeof navigator.mediaDevices.getUserMedia === "function" && typeof MediaRecorder !== "undefined";
+  }
+  get state() {
+    return this._state;
+  }
+  subscribe(cb) {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+  setState(state) {
+    this._state = state;
+    for (const cb of this.listeners) {
+      cb(state);
+    }
+  }
+  async start() {
+    if (this._state !== "idle" || this.starting) {
+      return;
+    }
+    this.starting = true;
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: this.options.audio ?? true
+      });
+      if (this.pendingCancel) {
+        stream.getTracks().forEach((t) => t.stop());
+        return;
+      }
+      this.stream = stream;
+      const wanted = this.options.mimeType;
+      const useMimeType = wanted && typeof MediaRecorder.isTypeSupported === "function" && MediaRecorder.isTypeSupported(wanted) ? wanted : void 0;
+      const recorder = useMimeType ? new MediaRecorder(stream, { mimeType: useMimeType }) : new MediaRecorder(stream);
+      this.chunks = [];
+      recorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          this.chunks.push(e.data);
+        }
+      };
+      recorder.onstop = () => {
+        void this.finalize();
+      };
+      recorder.onerror = (event) => {
+        const detail = "error" in event && event.error instanceof Error ? event.error : new Error("Audio recording failed");
+        this.handleError(detail);
+      };
+      this.recorder = recorder;
+      this.startedAt = Date.now();
+      recorder.start();
+      this.setState("recording");
+    } catch (err) {
+      this.releaseStream();
+      this.recorder = null;
+      const error = err instanceof Error ? err : new Error("Failed to start recording");
+      this.setState("idle");
+      this.notifyError(error);
+      throw error;
+    } finally {
+      this.starting = false;
+      this.pendingCancel = false;
+    }
+  }
+  stop() {
+    if (this._state !== "recording" || !this.recorder) {
+      return Promise.reject(
+        new Error("AudioRecorder.stop() called while not recording")
+      );
+    }
+    this.setState("stopping");
+    const recorder = this.recorder;
+    return new Promise((resolve, reject) => {
+      const watchdog = setTimeout(() => {
+        if (this._state !== "stopping") {
+          return;
+        }
+        this.detachRecorder();
+        if (this.chunks.length > 0) {
+          void this.finalize();
+        } else {
+          this.handleError(
+            new Error("Recording stop timed out after 10s with no audio")
+          );
+        }
+      }, 1e4);
+      this.stopResolve = (rec) => {
+        clearTimeout(watchdog);
+        resolve(rec);
+      };
+      this.stopReject = (err) => {
+        clearTimeout(watchdog);
+        reject(err);
+      };
+      recorder.stop();
+    });
+  }
+  cancel() {
+    if (this.starting) {
+      this.pendingCancel = true;
+      return;
+    }
+    if (this._state === "idle") {
+      return;
+    }
+    const recorder = this.recorder;
+    if (recorder) {
+      this.detachRecorder();
+      try {
+        recorder.stop();
+      } catch (err) {
+        if (!(err instanceof DOMException && err.name === "InvalidStateError")) {
+          this.notifyError(
+            err instanceof Error ? err : new Error("Failed to stop recorder")
+          );
+        }
+      }
+    }
+    this.releaseStream();
+    this.recorder = null;
+    this.chunks = [];
+    const reject = this.stopReject;
+    this.stopResolve = null;
+    this.stopReject = null;
+    this.setState("idle");
+    reject?.(new Error("Recording cancelled"));
+  }
+  async finalize() {
+    const mimeType = this.recorder?.mimeType || "audio/webm";
+    const durationMs = Date.now() - this.startedAt;
+    try {
+      const blob = new Blob(this.chunks, { type: mimeType });
+      const base64 = arrayBufferToBase64(await blob.arrayBuffer());
+      const recording = {
+        blob,
+        base64,
+        mimeType,
+        durationMs,
+        part: {
+          type: "audio",
+          source: { type: "data", value: base64, mimeType }
+        }
+      };
+      this.releaseStream();
+      this.recorder = null;
+      this.chunks = [];
+      const resolve = this.stopResolve;
+      this.stopResolve = null;
+      this.stopReject = null;
+      this.setState("idle");
+      resolve?.(recording);
+    } catch (err) {
+      this.handleError(
+        err instanceof Error ? err : new Error("Failed to finalize recording")
+      );
+    }
+  }
+  handleError(error) {
+    this.releaseStream();
+    this.recorder = null;
+    this.chunks = [];
+    const reject = this.stopReject;
+    this.stopResolve = null;
+    this.stopReject = null;
+    this.setState("idle");
+    reject?.(error);
+    this.notifyError(error);
+  }
+  /** Invoke the user onError callback, isolating a throw so it can't disrupt
+   * internal state teardown or strand a pending promise. */
+  notifyError(error) {
+    try {
+      this.options.onError?.(error);
+    } catch {
+    }
+  }
+  releaseStream() {
+    this.stream?.getTracks().forEach((t) => t.stop());
+    this.stream = null;
+  }
+  /** Detach all event handlers so a stale recorder can't mutate our state. */
+  detachRecorder() {
+    const recorder = this.recorder;
+    if (!recorder) {
+      return;
+    }
+    recorder.onstop = null;
+    recorder.onerror = null;
+    recorder.ondataavailable = null;
+  }
+}
+export {
+  AudioRecorder
+};
+//# sourceMappingURL=audio-recorder.js.map

package/dist/esm/audio-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-recorder.js","sources":["../../src/audio-recorder.ts"],"sourcesContent":["import { arrayBufferToBase64 } from '@tanstack/ai-utils'\nimport type { AudioPart } from '@tanstack/ai/client'\n\n/** Lifecycle state of an {@link AudioRecorder}. */\nexport type AudioRecorderState = 'idle' | 'recording' | 'stopping'\n\nexport interface AudioRecorderOptions {\n  /** Constraints forwarded to `getUserMedia({ audio })`. Defaults to `true`. */\n  audio?: MediaTrackConstraints | boolean\n  /**\n   * Preferred recorder mime type. Used only when\n   * `MediaRecorder.isTypeSupported` reports it; otherwise the browser default\n   * is used.\n   */\n  mimeType?: string\n  /** Fired on `getUserMedia` rejection (permission denied) or recorder error. */\n  onError?: (error: Error) => void\n}\n\n/**\n * Resolves the value `stop()` produces from a recorder transform callback.\n *\n * - If the callback returns a value — sync or async — that value's awaited type\n *   is used (a returned `null` is a real value and is preserved).\n * - If the callback returns nothing (`void`/`undefined`), or is absent, falls\n *   back to {@link AudioRecording}.\n *\n * @template TFn - The transform callback type (or undefined if not provided)\n */\nexport type InferAudioRecordingOutput<TFn> = TFn extends (\n  recording: AudioRecording,\n) => infer R\n  ? [Exclude<Awaited<R>, void | undefined>] extends [never]\n    ? AudioRecording\n    : Exclude<Awaited<R>, void | undefined>\n  : AudioRecording\n\nexport interface AudioRecording {\n  /** The raw recorded media blob. */\n  blob: Blob\n  /** Base64 of the recorded bytes (no `data:` prefix). */\n  base64: string\n  /** The recorder's native mime type, e.g. `audio/webm;codecs=opus`. */\n  mimeType: string\n  /** Recording length in milliseconds. */\n  durationMs: number\n  /**\n   * Ready-to-use audio content part for `sendMessage`/generation prompts:\n   * `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`.\n   */\n  part: AudioPart\n}\n\n/**\n * Framework-agnostic browser audio recorder. Wraps `getUserMedia` +\n * `MediaRecorder`, returns the recorder's native output (no transcode), and\n * builds a plug-and-play {@link AudioRecording.part}.\n */\nexport class AudioRecorder {\n  private readonly options: AudioRecorderOptions\n  private recorder: MediaRecorder | null = null\n  private stream: MediaStream | null = null\n  private chunks: Array<Blob> = []\n  private startedAt = 0\n  private _state: AudioRecorderState = 'idle'\n  // True while start() is awaiting getUserMedia (state is still 'idle' then).\n  private starting = false\n  // Set by cancel()/teardown during that window so start() releases the\n  // freshly acquired stream instead of beginning a leaked recording.\n  private pendingCancel = false\n  private readonly listeners = new Set<(state: AudioRecorderState) => void>()\n  private stopResolve: ((recording: AudioRecording) => void) | null = null\n  private stopReject: ((error: Error) => void) | null = null\n\n  constructor(options: AudioRecorderOptions = {}) {\n    this.options = options\n  }\n\n  /** Feature-detect the browser media APIs. SSR/Worker-safe. */\n  static isSupported(): boolean {\n    return (\n      typeof navigator !== 'undefined' &&\n      typeof navigator.mediaDevices !== 'undefined' &&\n      typeof navigator.mediaDevices.getUserMedia === 'function' &&\n      typeof MediaRecorder !== 'undefined'\n    )\n  }\n\n  get state(): AudioRecorderState {\n    return this._state\n  }\n\n  subscribe(cb: (state: AudioRecorderState) => void): () => void {\n    this.listeners.add(cb)\n    return () => {\n      this.listeners.delete(cb)\n    }\n  }\n\n  private setState(state: AudioRecorderState): void {\n    this._state = state\n    for (const cb of this.listeners) {\n      cb(state)\n    }\n  }\n\n  async start(): Promise<void> {\n    if (this._state !== 'idle' || this.starting) {\n      return\n    }\n    this.starting = true\n    try {\n      const stream = await navigator.mediaDevices.getUserMedia({\n        audio: this.options.audio ?? true,\n      })\n      // cancel()/teardown ran while we were awaiting the mic: release the\n      // freshly acquired stream and bail rather than starting a recording the\n      // caller can no longer stop (a leaked live microphone).\n      if (this.pendingCancel) {\n        stream.getTracks().forEach((t) => t.stop())\n        return\n      }\n      this.stream = stream\n      const wanted = this.options.mimeType\n      const useMimeType =\n        wanted &&\n        typeof MediaRecorder.isTypeSupported === 'function' &&\n        MediaRecorder.isTypeSupported(wanted)\n          ? wanted\n          : undefined\n      const recorder = useMimeType\n        ? new MediaRecorder(stream, { mimeType: useMimeType })\n        : new MediaRecorder(stream)\n      this.chunks = []\n      recorder.ondataavailable = (e) => {\n        if (e.data.size > 0) {\n          this.chunks.push(e.data)\n        }\n      }\n      recorder.onstop = () => {\n        void this.finalize()\n      }\n      recorder.onerror = (event) => {\n        const detail =\n          'error' in event && event.error instanceof Error\n            ? event.error\n            : new Error('Audio recording failed')\n        this.handleError(detail)\n      }\n      this.recorder = recorder\n      this.startedAt = Date.now()\n      recorder.start()\n      this.setState('recording')\n    } catch (err) {\n      this.releaseStream()\n      this.recorder = null\n      const error =\n        err instanceof Error ? err : new Error('Failed to start recording')\n      this.setState('idle')\n      this.notifyError(error)\n      throw error\n    } finally {\n      this.starting = false\n      // Reset here (not before the await) so a cancel() that arrives mid-start\n      // is observed above; clearing it afterward keeps the next start() clean.\n      this.pendingCancel = false\n    }\n  }\n\n  stop(): Promise<AudioRecording> {\n    if (this._state !== 'recording' || !this.recorder) {\n      return Promise.reject(\n        new Error('AudioRecorder.stop() called while not recording'),\n      )\n    }\n    this.setState('stopping')\n    const recorder = this.recorder\n    return new Promise<AudioRecording>((resolve, reject) => {\n      // Some browsers/codecs never fire onstop; this watchdog unwedges the\n      // recorder instead of leaking this promise forever.\n      const watchdog = setTimeout(() => {\n        if (this._state !== 'stopping') {\n          return\n        }\n        // Detach handlers so a late onstop/onerror from the stalled recorder\n        // can't reach back in and fire finalize()/onError a second time.\n        this.detachRecorder()\n        if (this.chunks.length > 0) {\n          // onstop never fired, but ondataavailable already delivered the\n          // audio — finalize from the buffered chunks rather than discarding a\n          // recording the user successfully captured.\n          void this.finalize()\n        } else {\n          this.handleError(\n            new Error('Recording stop timed out after 10s with no audio'),\n          )\n        }\n      }, 10_000)\n      this.stopResolve = (rec) => {\n        clearTimeout(watchdog)\n        resolve(rec)\n      }\n      this.stopReject = (err) => {\n        clearTimeout(watchdog)\n        reject(err)\n      }\n      recorder.stop()\n    })\n  }\n\n  cancel(): void {\n    if (this.starting) {\n      // A start() is awaiting getUserMedia; flag it so the resolved stream is\n      // released instead of beginning a recording with no handle to stop it.\n      this.pendingCancel = true\n      return\n    }\n    if (this._state === 'idle') {\n      return\n    }\n    const recorder = this.recorder\n    if (recorder) {\n      // Detach handlers so finalize()/onError never run for a discarded\n      // recording.\n      this.detachRecorder()\n      try {\n        recorder.stop()\n      } catch (err) {\n        // Stopping an already-inactive recorder throws InvalidStateError —\n        // that's expected here. Anything else is unexpected; surface it rather\n        // than swallowing it silently.\n        if (\n          !(err instanceof DOMException && err.name === 'InvalidStateError')\n        ) {\n          this.notifyError(\n            err instanceof Error ? err : new Error('Failed to stop recorder'),\n          )\n        }\n      }\n    }\n    this.releaseStream()\n    this.recorder = null\n    this.chunks = []\n    const reject = this.stopReject\n    this.stopResolve = null\n    this.stopReject = null\n    this.setState('idle')\n    reject?.(new Error('Recording cancelled'))\n  }\n\n  private async finalize(): Promise<void> {\n    const mimeType = this.recorder?.mimeType || 'audio/webm'\n    const durationMs = Date.now() - this.startedAt\n    try {\n      const blob = new Blob(this.chunks, { type: mimeType })\n      const base64 = arrayBufferToBase64(await blob.arrayBuffer())\n      const recording: AudioRecording = {\n        blob,\n        base64,\n        mimeType,\n        durationMs,\n        part: {\n          type: 'audio',\n          source: { type: 'data', value: base64, mimeType },\n        },\n      }\n      this.releaseStream()\n      this.recorder = null\n      this.chunks = []\n      const resolve = this.stopResolve\n      this.stopResolve = null\n      this.stopReject = null\n      this.setState('idle')\n      resolve?.(recording)\n    } catch (err) {\n      this.handleError(\n        err instanceof Error ? err : new Error('Failed to finalize recording'),\n      )\n    }\n  }\n\n  private handleError(error: Error): void {\n    this.releaseStream()\n    this.recorder = null\n    this.chunks = []\n    const reject = this.stopReject\n    this.stopResolve = null\n    this.stopReject = null\n    this.setState('idle')\n    // Settle the pending stop() promise before invoking the user callback so a\n    // throwing onError can't strand the awaiter (the two error channels are\n    // independent — see start()/stop() docs).\n    reject?.(error)\n    this.notifyError(error)\n  }\n\n  /** Invoke the user onError callback, isolating a throw so it can't disrupt\n   * internal state teardown or strand a pending promise. */\n  private notifyError(error: Error): void {\n    try {\n      this.options.onError?.(error)\n    } catch {\n      // A user onError that throws must not propagate into recorder internals.\n    }\n  }\n\n  private releaseStream(): void {\n    this.stream?.getTracks().forEach((t) => t.stop())\n    this.stream = null\n  }\n\n  /** Detach all event handlers so a stale recorder can't mutate our state. */\n  private detachRecorder(): void {\n    const recorder = this.recorder\n    if (!recorder) {\n      return\n    }\n    recorder.onstop = null\n    recorder.onerror = null\n    recorder.ondataavailable = null\n  }\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,264 @@
+import { AnyClientTool, ModelMessage, StreamChunk } from '@tanstack/ai/client';
+import { ConnectionAdapter } from './connection-adapters.js';
+import { ChatClientOptions, ChatClientState, ChatFetcher, ConnectionStatus, MultimodalContent, UIMessage } from './types.js';
+type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>> = {
+    connection?: ConnectionAdapter;
+    fetcher?: ChatFetcher;
+    /** @deprecated Use `forwardedProps` instead. */
+    body?: Record<string, any>;
+    forwardedProps?: Record<string, any>;
+    tools?: TTools;
+    onResponse?: (response?: Response) => void | Promise<void>;
+    onChunk?: (chunk: StreamChunk) => void;
+    onFinish?: (message: UIMessage) => void;
+    onError?: (error: Error) => void;
+    onSubscriptionChange?: (isSubscribed: boolean) => void;
+    onConnectionStatusChange?: (status: ConnectionStatus) => void;
+    onSessionGeneratingChange?: (isGenerating: boolean) => void;
+    onCustomEvent?: (eventType: string, data: unknown, context: {
+        toolCallId?: string;
+    }) => void;
+};
+type ClientToolResult = {
+    toolCallId: string;
+    tool: string;
+    output: any;
+    state?: 'output-available' | 'output-error';
+    errorText?: string;
+};
+export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = unknown> {
+    private readonly processor;
+    private connection;
+    private readonly uniqueId;
+    private readonly threadId;
+    private readonly persistor?;
+    private currentRunId;
+    private bodyOption;
+    private forwardedPropsOption;
+    private context;
+    private pendingMessageBody;
+    private isLoading;
+    private isSubscribed;
+    private error;
+    private status;
+    private connectionStatus;
+    private abortController;
+    private readonly clientToolsRef;
+    private readonly devtoolsBridge;
+    /**
+     * Alias for `this.events`. The bridge installs an
+     * emitter that auto-attaches run/thread context and auto-emits a
+     * snapshot after every event, so chat-client only ever calls
+     * `this.events.X(...)` exactly like it did before devtools landed.
+     */
+    private readonly events;
+    private currentStreamId;
+    private currentMessageId;
+    private readonly postStreamActions;
+    private readonly pendingToolExecutions;
+    private activeClientTools;
+    private activeContext;
+    private continuationPending;
+    private subscriptionAbortController;
+    private processingResolve;
+    private errorReportedGeneration;
+    private streamGeneration;
+    private continuationSkipped;
+    private draining;
+    private sessionGenerating;
+    private readonly activeRunIds;
+    private devtoolsMounted;
+    private readonly callbacksRef;
+    constructor(options: ChatClientOptions<TTools, TContext>);
+    mountDevtools(): void;
+    /**
+     * Drain a runId-less RUN_ERROR that belongs to a cleared run the client is
+     * still tracking. The persistor owns the cleared-run bookkeeping; the client
+     * owns the active-run / session / processing state.
+     */
+    private drainIgnoredRunlessChunk;
+    private updateRunLifecycle;
+    private generateUniqueId;
+    private setIsLoading;
+    private setStatus;
+    private setIsSubscribed;
+    private setConnectionStatus;
+    private setSessionGenerating;
+    private resetSessionGenerating;
+    private setError;
+    private buildDevtoolsBridgeOptions;
+    private getDevtoolsSnapshot;
+    private findMessageIdForToolCall;
+    private abortSubscriptionLoop;
+    private resolveProcessing;
+    private cancelInFlightStream;
+    private reportStreamError;
+    /**
+     * Start the background subscription loop.
+     */
+    private startSubscription;
+    /**
+     * Consume chunks from the connection subscription.
+     */
+    private consumeSubscription;
+    /**
+     * Ensure subscription loop is running, starting it if needed.
+     */
+    private ensureSubscription;
+    /**
+     * Create a promise that resolves when onStreamEnd fires.
+     * Used by streamResponse to await processing completion.
+     */
+    private waitForProcessing;
+    /**
+     * Send a message and stream the response.
+     * Supports both simple string content and multimodal content (images, audio, video, documents).
+     *
+     * @param content - The message content. Can be:
+     *   - A simple string for text-only messages
+     *   - 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.
+     *
+     * @example
+     * ```ts
+     * // Simple text message
+     * await client.sendMessage('Hello!')
+     *
+     * // Text message with custom body params
+     * await client.sendMessage('Hello!', { temperature: 0.7 })
+     *
+     * // Multimodal message with image
+     * await client.sendMessage({
+     *   content: [
+     *     { type: 'text', content: 'What is in this image?' },
+     *     { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }
+     *   ]
+     * })
+     *
+     * // Multimodal message with custom ID and body params
+     * await client.sendMessage(
+     *   {
+     *     content: [
+     *       { type: 'text', content: 'Describe this audio' },
+     *       { type: 'audio', source: { type: 'data', value: 'base64...' } }
+     *     ],
+     *     id: 'custom-message-id'
+     *   },
+     *   { model: 'gpt-4-audio' }
+     * )
+     * ```
+     */
+    sendMessage(content: string | MultimodalContent, body?: Record<string, any>): Promise<void>;
+    /**
+     * Normalize the message input to extract content and optional id.
+     * Trims string content automatically.
+     */
+    private normalizeMessageInput;
+    /**
+     * Append a message and stream the response
+     */
+    append(message: UIMessage | ModelMessage): Promise<void>;
+    /**
+     * Stream a response from the LLM.
+     * Returns true if the stream completed successfully, false on abort or error.
+     */
+    private streamResponse;
+    /**
+     * Start the client subscription loop.
+     * This controls the connection lifecycle independently from request lifecycle.
+     */
+    subscribe(options?: {
+        restart?: boolean;
+    }): void;
+    /**
+     * Unsubscribe and fully tear down live behavior.
+     * This aborts an in-flight request and the subscription loop.
+     */
+    unsubscribe(): void;
+    /**
+     * Reload the last assistant message
+     */
+    reload(): Promise<void>;
+    /**
+     * Stop the current stream
+     */
+    stop(): void;
+    /**
+     * Clear all messages
+     */
+    clear(): void;
+    /**
+     * Add the result of a client-side tool execution
+     */
+    addToolResult(result: ClientToolResult): Promise<void>;
+    private addToolResultForClientTool;
+    private validateClientToolOutput;
+    /**
+     * Respond to a tool approval request
+     */
+    addToolApprovalResponse(response: {
+        id: string;
+        approved: boolean;
+    }): Promise<void>;
+    /**
+     * Queue an action to be executed after the current stream ends
+     */
+    private queuePostStreamAction;
+    /**
+     * Drain and execute all queued post-stream actions
+     */
+    private drainPostStreamActions;
+    /**
+     * Check if we should continue the flow and do so if needed
+     */
+    private checkForContinuation;
+    /**
+     * Check if all tool calls are complete and we should auto-send.
+     * Requires that there is at least one tool call in the last assistant message;
+     * a text-only response has nothing to auto-send.
+     */
+    private shouldAutoSend;
+    /**
+     * Get current messages
+     */
+    getMessages(): Array<UIMessage<TTools>>;
+    /**
+     * Get loading state
+     */
+    getIsLoading(): boolean;
+    /**
+     * Get current status
+     */
+    getStatus(): ChatClientState;
+    /**
+     * Get whether the subscription loop is active
+     */
+    getIsSubscribed(): boolean;
+    /**
+     * Get current connection lifecycle status
+     */
+    getConnectionStatus(): ConnectionStatus;
+    /**
+     * Whether the shared session is actively generating.
+     * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+     * Unlike `isLoading` (request-local), this reflects shared generation
+     * activity visible to all subscribers (e.g. across tabs/devices).
+     */
+    getSessionGenerating(): boolean;
+    /**
+     * Get current error
+     */
+    getError(): Error | undefined;
+    /**
+     * Manually set messages
+     */
+    setMessagesManually(messages: Array<UIMessage<TTools>>): void;
+    /**
+     * Update options refs (for use in React hooks to avoid recreating client)
+     */
+    updateOptions(options: ChatClientUpdateOptionsWithoutContext<TTools>): void;
+    updateOptions(options: ChatClientUpdateOptionsWithoutContext<TTools> & Pick<ChatClientOptions<TTools, TContext>, 'context'>): void;
+    dispose(): void;
+}
+export {};