@tanstack/ai-client 0.12.0 → 0.13.0

package/dist/esm/generation-client.js

@@ -1,16 +1,26 @@
 import { GENERATION_EVENTS } from "./generation-types.js";
+import { createNoOpGenerationDevtoolsBridge } from "./devtools-noop.js";
 import { parseSSEResponse } from "./sse-parser.js";
 class GenerationClient {
   connection;
   fetcher;
+  uniqueId;
+  devtoolsMetadata;
+  devtoolsBridge;
+  threadId;
   body;
   result = null;
+  input = null;
+  progress = null;
   isLoading = false;
   error = void 0;
   status = "idle";
   abortController = null;
   callbacksRef;
+  devtoolsMounted = false;
   constructor(options) {
+    this.uniqueId = options.id ?? this.generateUniqueId("generation");
+    this.threadId = this.uniqueId;
     this.connection = options.connection;
     this.fetcher = options.fetcher;
     this.body = options.body ?? {};
@@ -24,6 +34,32 @@ class GenerationClient {
       onErrorChange: options.onErrorChange,
       onStatusChange: options.onStatusChange
     };
+    this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools);
+    this.devtoolsBridge = (options.devtoolsBridgeFactory ?? createNoOpGenerationDevtoolsBridge)(this.buildDevtoolsBridgeOptions());
+  }
+  buildDevtoolsBridgeOptions() {
+    return {
+      hookId: this.uniqueId,
+      clientId: this.uniqueId,
+      threadId: this.threadId,
+      metadata: this.devtoolsMetadata,
+      getCoreState: () => ({
+        input: this.input,
+        result: this.result,
+        progress: this.progress,
+        status: this.status,
+        isLoading: this.isLoading,
+        ...this.error ? { error: this.error.message } : {}
+      })
+    };
+  }
+  mountDevtools() {
+    if (this.devtoolsMounted) {
+      return;
+    }
+    this.devtoolsMounted = true;
+    this.devtoolsBridge.emitRegistered();
+    this.devtoolsBridge.emitSnapshot();
   }
   /**
    * Trigger a generation request.
@@ -31,7 +67,11 @@ class GenerationClient {
    * while already generating will be a no-op.
    */
   async generate(input) {
+    this.mountDevtools();
     if (this.isLoading) return;
+    this.input = input;
+    this.progress = null;
+    const runId = this.devtoolsBridge.beginRun(input);
     this.setIsLoading(true);
     this.setStatus("generating");
     this.setError(void 0);
@@ -43,25 +83,45 @@ class GenerationClient {
         const result = await this.fetcher(input, { signal });
         if (signal.aborted) return;
         if (result instanceof Response) {
-          await this.processStream(parseSSEResponse(result, signal));
+          await this.processStream(parseSSEResponse(result, signal), runId);
         } else {
+          this.devtoolsBridge.ensureRunStarted(runId);
           this.setResult(result);
           this.setStatus("success");
         }
       } else if (this.connection) {
         const mergedData = { ...this.body, ...input };
-        const stream = this.connection.connect([], mergedData, signal);
-        await this.processStream(stream);
+        const stream = this.connection.connect(
+          [],
+          mergedData,
+          signal,
+          this.createRunContext(runId)
+        );
+        await this.processStream(stream, runId);
       } else {
         throw new Error(
           "GenerationClient requires either a connection or fetcher option"
         );
       }
+      if (!signal.aborted && this.status === "success") {
+        this.progress = completeProgressValue(this.progress);
+        this.devtoolsBridge.finishRun(
+          this.devtoolsBridge.getActiveRunId() ?? runId,
+          "run:completed",
+          "completed"
+        );
+      }
     } catch (err) {
       if (signal.aborted) return;
       const error = err instanceof Error ? err : new Error(String(err));
       this.setError(error);
       this.setStatus("error");
+      this.devtoolsBridge.finishRun(
+        this.devtoolsBridge.getActiveRunId() ?? runId,
+        "run:errored",
+        "errored",
+        error.message
+      );
       this.callbacksRef.onError?.(error);
     } finally {
       this.abortController = null;
@@ -71,25 +131,38 @@ class GenerationClient {
   /**
    * Process a stream of AG-UI events from the streaming connection adapter.
    */
-  async processStream(source) {
+  async processStream(source, fallbackRunId) {
+    let streamRunId;
     for await (const chunk of source) {
       if (this.abortController?.signal.aborted) break;
       this.callbacksRef.onChunk?.(chunk);
+      const chunkRunId = "runId" in chunk && typeof chunk.runId === "string" ? chunk.runId : void 0;
       switch (chunk.type) {
+        case "RUN_STARTED": {
+          streamRunId = chunk.runId;
+          this.devtoolsBridge.ensureRunStarted(chunk.runId);
+          break;
+        }
         case "CUSTOM": {
+          this.devtoolsBridge.ensureRunStarted(streamRunId ?? fallbackRunId);
           if (chunk.name === GENERATION_EVENTS.RESULT) {
             this.setResult(chunk.value);
           } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {
             const { progress, message } = chunk.value;
-            this.callbacksRef.onProgress?.(progress, message);
+            this.setProgress(progress, message);
           }
           break;
         }
         case "RUN_FINISHED": {
+          streamRunId = chunk.runId;
+          this.devtoolsBridge.ensureRunStarted(chunk.runId);
           this.setStatus("success");
           break;
         }
         case "RUN_ERROR": {
+          this.devtoolsBridge.ensureRunStarted(
+            chunkRunId ?? streamRunId ?? fallbackRunId
+          );
           const msg = chunk.message || chunk.error?.message || "An error occurred";
           throw new Error(msg);
         }
@@ -100,6 +173,7 @@ class GenerationClient {
    * Abort any in-flight generation request.
    */
   stop() {
+    const runId = this.devtoolsBridge.getActiveRunId();
     if (this.abortController) {
       this.abortController.abort();
       this.abortController = null;
@@ -107,6 +181,9 @@ class GenerationClient {
     this.setIsLoading(false);
     if (this.status === "generating") {
       this.setStatus("idle");
+      if (runId) {
+        this.devtoolsBridge.finishRun(runId, "run:cancelled", "cancelled");
+      }
     }
   }
   /**
@@ -115,8 +192,12 @@ class GenerationClient {
   reset() {
     this.stop();
     this.setResult(null);
+    this.input = null;
+    this.progress = null;
+    this.devtoolsBridge.resetRuns();
     this.setError(void 0);
     this.setStatus("idle");
+    this.devtoolsBridge.emitState();
   }
   /**
    * Update options without recreating the client.
@@ -138,6 +219,11 @@ class GenerationClient {
       this.callbacksRef.onChunk = options.onChunk;
     }
   }
+  dispose() {
+    this.stop();
+    this.devtoolsBridge.dispose();
+    this.devtoolsMounted = false;
+  }
   // ===========================
   // Getters
   // ===========================
@@ -160,34 +246,78 @@ class GenerationClient {
     if (rawResult === null) {
       this.result = null;
       this.callbacksRef.onResultChange?.(null);
+      this.devtoolsBridge.recordResultChange();
       return;
     }
     if (this.callbacksRef.onResult) {
       const transformed = this.callbacksRef.onResult(rawResult);
       if (transformed === null) {
+        this.devtoolsBridge.emitState();
         return;
       }
       if (transformed !== void 0) {
         this.result = transformed;
         this.callbacksRef.onResultChange?.(this.result);
+        this.devtoolsBridge.recordResultChange();
         return;
       }
     }
     this.result = rawResult;
     this.callbacksRef.onResultChange?.(this.result);
+    this.devtoolsBridge.recordResultChange();
   }
   setIsLoading(isLoading) {
     this.isLoading = isLoading;
     this.callbacksRef.onLoadingChange?.(isLoading);
+    this.devtoolsBridge.recordLoadingChange();
   }
   setError(error) {
     this.error = error;
     this.callbacksRef.onErrorChange?.(error);
+    this.devtoolsBridge.recordErrorChange(error);
   }
   setStatus(status) {
     this.status = status;
     this.callbacksRef.onStatusChange?.(status);
+    this.devtoolsBridge.recordStatusChange(status);
+  }
+  setProgress(value, message) {
+    this.progress = {
+      value,
+      ...message ? { message } : {}
+    };
+    if (message === void 0) {
+      this.callbacksRef.onProgress?.(value);
+    } else {
+      this.callbacksRef.onProgress?.(value, message);
+    }
+    this.devtoolsBridge.recordProgressChange();
   }
+  createDevtoolsMetadata(metadata) {
+    return {
+      hookName: metadata?.hookName ?? "useGeneration",
+      ...metadata?.framework ? { framework: metadata.framework } : {},
+      ...metadata?.outputKind ? { outputKind: metadata.outputKind } : {},
+      ...metadata?.name ? { name: metadata.name } : {}
+    };
+  }
+  generateUniqueId(prefix) {
+    return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+  }
+  createRunContext(runId) {
+    return {
+      threadId: this.threadId,
+      runId
+    };
+  }
+}
+function completeProgressValue(progress) {
+  if (!progress) return null;
+  const message = progress.message;
+  return {
+    value: 100,
+    ...message ? { message } : {}
+  };
 }
 export {
   GenerationClient

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

@@ -1 +1 @@
-{"version":3,"file":"generation-client.js","sources":["../../src/generation-client.ts"],"sourcesContent":["import { GENERATION_EVENTS } from './generation-types'\nimport { parseSSEResponse } from './sse-parser'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type { ConnectConnectionAdapter } from './connection-adapters'\nimport type {\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n} from './generation-types'\n\n/**\n * Callbacks stored in a ref so hooks can update them without recreating the client.\n */\n// All optional fields explicitly allow `| undefined` so callers can spread\n// option bags (where each callback may be `undefined`) into the callbacks\n// ref under `exactOptionalPropertyTypes`.\ninterface GenerationCallbacks<TResult, TOutput> {\n  onResult?: ((result: TResult) => TOutput | null | void) | undefined\n  onError?: ((error: Error) => void) | undefined\n  onProgress?: ((progress: number, message?: string) => void) | undefined\n  onChunk?: ((chunk: StreamChunk) => void) | undefined\n  onResultChange?: ((result: TOutput | null) => void) | undefined\n  onLoadingChange?: ((isLoading: boolean) => void) | undefined\n  onErrorChange?: ((error: Error | undefined) => void) | undefined\n  onStatusChange?: ((status: GenerationClientState) => void) | undefined\n}\n\n/**\n * A lightweight, generic client for one-shot generation tasks\n * (image, speech, transcription, summarize).\n *\n * Supports two transport modes:\n * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom).\n *   Server wraps results in StreamChunk events with CUSTOM event names.\n * - **Fetcher** — Direct async function call. No streaming protocol needed.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```typescript\n * // With streaming connection adapter\n * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({\n *   connection: fetchServerSentEvents('/api/generate/image'),\n *   onResultChange: setResult,\n *   onLoadingChange: setIsLoading,\n * })\n *\n * // With fetcher (direct)\n * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({\n *   fetcher: async (input) => {\n *     const res = await fetch('/api/generate/image', {\n *       method: 'POST',\n *       body: JSON.stringify(input),\n *     })\n *     return res.json()\n *   },\n * })\n *\n * await client.generate({ prompt: 'A sunset over mountains' })\n * ```\n */\nexport class GenerationClient<\n  TInput extends Record<string, any>,\n  TResult,\n  TOutput = TResult,\n> {\n  private readonly connection: ConnectConnectionAdapter | undefined\n  private readonly fetcher: GenerationFetcher<TInput, TResult> | undefined\n  private body: Record<string, any>\n  private result: TOutput | null = null\n  private isLoading = false\n  private error: Error | undefined = undefined\n  private status: GenerationClientState = 'idle'\n  private abortController: AbortController | null = null\n  private readonly callbacksRef: GenerationCallbacks<TResult, TOutput>\n\n  constructor(\n    options: GenerationClientOptions<TInput, TResult, TOutput> &\n      (\n        | { connection: ConnectConnectionAdapter; fetcher?: never }\n        | {\n            fetcher: GenerationFetcher<TInput, TResult>\n            connection?: never\n          }\n      ),\n  ) {\n    this.connection = options.connection\n    this.fetcher = options.fetcher\n    this.body = options.body ?? {}\n\n    this.callbacksRef = {\n      onResult: options.onResult,\n      onError: options.onError,\n      onProgress: options.onProgress,\n      onChunk: options.onChunk,\n      onResultChange: options.onResultChange,\n      onLoadingChange: options.onLoadingChange,\n      onErrorChange: options.onErrorChange,\n      onStatusChange: options.onStatusChange,\n    }\n  }\n\n  /**\n   * Trigger a generation request.\n   * Only one generation can be in-flight at a time; calling generate()\n   * while already generating will be a no-op.\n   */\n  async generate(input: TInput): Promise<void> {\n    if (this.isLoading) return\n\n    this.setIsLoading(true)\n    this.setStatus('generating')\n    this.setError(undefined)\n\n    const abortController = new AbortController()\n    this.abortController = abortController\n    const { signal } = abortController\n\n    try {\n      if (this.fetcher) {\n        // Direct fetch path\n        const result = await this.fetcher(input, { signal })\n        if (signal.aborted) return\n        if (result instanceof Response) {\n          // Server function returned SSE Response — parse stream\n          await this.processStream(parseSSEResponse(result, signal))\n        } else {\n          this.setResult(result)\n          this.setStatus('success')\n        }\n      } else if (this.connection) {\n        // Streaming adapter path\n        const mergedData = { ...this.body, ...input }\n        const stream = this.connection.connect([], mergedData, signal)\n        await this.processStream(stream)\n      } else {\n        throw new Error(\n          'GenerationClient requires either a connection or fetcher option',\n        )\n      }\n    } catch (err: any) {\n      if (signal.aborted) return\n      const error = err instanceof Error ? err : new Error(String(err))\n      this.setError(error)\n      this.setStatus('error')\n      this.callbacksRef.onError?.(error)\n    } finally {\n      this.abortController = null\n      this.setIsLoading(false)\n    }\n  }\n\n  /**\n   * Process a stream of AG-UI events from the streaming connection adapter.\n   */\n  private async processStream(\n    source: AsyncIterable<StreamChunk>,\n  ): Promise<void> {\n    for await (const chunk of source) {\n      if (this.abortController?.signal.aborted) break\n\n      this.callbacksRef.onChunk?.(chunk)\n\n      // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType has ~22 variants; this consumer only handles the subset relevant to generation lifecycle.\n      switch (chunk.type) {\n        case 'CUSTOM': {\n          if (chunk.name === GENERATION_EVENTS.RESULT) {\n            this.setResult(chunk.value as TResult)\n          } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {\n            const { progress, message } = chunk.value as {\n              progress: number\n              message?: string\n            }\n            this.callbacksRef.onProgress?.(progress, message)\n          }\n          break\n        }\n        case 'RUN_FINISHED': {\n          this.setStatus('success')\n          break\n        }\n        case 'RUN_ERROR': {\n          // Prefer spec `message`; fall back to deprecated `error.message`\n          const msg =\n            (chunk.message as string | undefined) ||\n            chunk.error?.message ||\n            'An error occurred'\n          throw new Error(msg)\n        }\n        default:\n          break\n      }\n    }\n  }\n\n  /**\n   * Abort any in-flight generation request.\n   */\n  stop(): void {\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    this.setIsLoading(false)\n    if (this.status === 'generating') {\n      this.setStatus('idle')\n    }\n  }\n\n  /**\n   * Clear the result, error, and return to idle state.\n   */\n  reset(): void {\n    this.stop()\n    this.setResult(null)\n    this.setError(undefined)\n    this.setStatus('idle')\n  }\n\n  /**\n   * Update options without recreating the client.\n   */\n  updateOptions(\n    options: Partial<\n      Pick<\n        GenerationClientOptions<TInput, TResult, TOutput>,\n        'body' | 'onResult' | 'onError' | 'onProgress' | 'onChunk'\n      >\n    >,\n  ): void {\n    if (options.body !== undefined) {\n      this.body = options.body ?? {}\n    }\n    if (options.onResult !== undefined) {\n      this.callbacksRef.onResult = options.onResult\n    }\n    if (options.onError !== undefined) {\n      this.callbacksRef.onError = options.onError\n    }\n    if (options.onProgress !== undefined) {\n      this.callbacksRef.onProgress = options.onProgress\n    }\n    if (options.onChunk !== undefined) {\n      this.callbacksRef.onChunk = options.onChunk\n    }\n  }\n\n  // ===========================\n  // Getters\n  // ===========================\n\n  getResult(): TOutput | null {\n    return this.result\n  }\n\n  getIsLoading(): boolean {\n    return this.isLoading\n  }\n\n  getError(): Error | undefined {\n    return this.error\n  }\n\n  getStatus(): GenerationClientState {\n    return this.status\n  }\n\n  // ===========================\n  // Private state setters\n  // ===========================\n\n  private setResult(rawResult: TResult | null): void {\n    if (rawResult === null) {\n      this.result = null\n      this.callbacksRef.onResultChange?.(null)\n      return\n    }\n\n    if (this.callbacksRef.onResult) {\n      const transformed = this.callbacksRef.onResult(rawResult)\n      if (transformed === null) {\n        // null return → keep previous result unchanged\n        return\n      }\n      if (transformed !== undefined) {\n        // Non-null, non-undefined → use transformed value\n        this.result = transformed\n        this.callbacksRef.onResultChange?.(this.result)\n        return\n      }\n    }\n\n    // No onResult callback, or callback returned void → use raw value\n    this.result = rawResult as TOutput\n    this.callbacksRef.onResultChange?.(this.result)\n  }\n\n  private setIsLoading(isLoading: boolean): void {\n    this.isLoading = isLoading\n    this.callbacksRef.onLoadingChange?.(isLoading)\n  }\n\n  private setError(error: Error | undefined): void {\n    this.error = error\n    this.callbacksRef.onErrorChange?.(error)\n  }\n\n  private setStatus(status: GenerationClientState): void {\n    this.status = status\n    this.callbacksRef.onStatusChange?.(status)\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"generation-client.js","sources":["../../src/generation-client.ts"],"sourcesContent":["import { GENERATION_EVENTS } from './generation-types'\nimport { createNoOpGenerationDevtoolsBridge } from './devtools-noop'\nimport { parseSSEResponse } from './sse-parser'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type {\n  ConnectConnectionAdapter,\n  RunAgentInputContext,\n} from './connection-adapters'\nimport type {\n  AIDevtoolsClientMetadata,\n  AIDevtoolsGenerationProgress,\n  GenerationDevtoolsBridge,\n  GenerationDevtoolsBridgeOptions,\n} from './devtools'\nimport type {\n  GenerationClientOptions,\n  GenerationClientState,\n  GenerationFetcher,\n} from './generation-types'\n\n/**\n * Callbacks stored in a ref so hooks can update them without recreating the client.\n */\n// All optional fields explicitly allow `| undefined` so callers can spread\n// option bags (where each callback may be `undefined`) into the callbacks\n// ref under `exactOptionalPropertyTypes`.\ninterface GenerationCallbacks<TResult, TOutput> {\n  onResult?: ((result: TResult) => TOutput | null | void) | undefined\n  onError?: ((error: Error) => void) | undefined\n  onProgress?: ((progress: number, message?: string) => void) | undefined\n  onChunk?: ((chunk: StreamChunk) => void) | undefined\n  onResultChange?: ((result: TOutput | null) => void) | undefined\n  onLoadingChange?: ((isLoading: boolean) => void) | undefined\n  onErrorChange?: ((error: Error | undefined) => void) | undefined\n  onStatusChange?: ((status: GenerationClientState) => void) | undefined\n}\n\n/**\n * A lightweight, generic client for one-shot generation tasks\n * (image, speech, transcription, summarize).\n *\n * Supports two transport modes:\n * - **ConnectConnectionAdapter** — Streaming transport (SSE, HTTP stream, custom).\n *   Server wraps results in StreamChunk events with CUSTOM event names.\n * - **Fetcher** — Direct async function call. No streaming protocol needed.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n *\n * @example\n * ```typescript\n * // With streaming connection adapter\n * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({\n *   connection: fetchServerSentEvents('/api/generate/image'),\n *   onResultChange: setResult,\n *   onLoadingChange: setIsLoading,\n * })\n *\n * // With fetcher (direct)\n * const client = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({\n *   fetcher: async (input) => {\n *     const res = await fetch('/api/generate/image', {\n *       method: 'POST',\n *       body: JSON.stringify(input),\n *     })\n *     return res.json()\n *   },\n * })\n *\n * await client.generate({ prompt: 'A sunset over mountains' })\n * ```\n */\nexport class GenerationClient<\n  TInput extends Record<string, any>,\n  TResult,\n  TOutput = TResult,\n> {\n  private readonly connection: ConnectConnectionAdapter | undefined\n  private readonly fetcher: GenerationFetcher<TInput, TResult> | undefined\n  private readonly uniqueId: string\n  private readonly devtoolsMetadata: AIDevtoolsClientMetadata\n  private readonly devtoolsBridge: GenerationDevtoolsBridge<TOutput>\n  private readonly threadId: string\n  private body: Record<string, any>\n  private result: TOutput | null = null\n  private input: TInput | null = null\n  private progress: AIDevtoolsGenerationProgress | null = null\n  private isLoading = false\n  private error: Error | undefined = undefined\n  private status: GenerationClientState = 'idle'\n  private abortController: AbortController | null = null\n  private readonly callbacksRef: GenerationCallbacks<TResult, TOutput>\n  private devtoolsMounted = false\n\n  constructor(\n    options: GenerationClientOptions<TInput, TResult, TOutput> &\n      (\n        | { connection: ConnectConnectionAdapter; fetcher?: never }\n        | {\n            fetcher: GenerationFetcher<TInput, TResult>\n            connection?: never\n          }\n      ),\n  ) {\n    this.uniqueId = options.id ?? this.generateUniqueId('generation')\n    this.threadId = this.uniqueId\n    this.connection = options.connection\n    this.fetcher = options.fetcher\n    this.body = options.body ?? {}\n\n    this.callbacksRef = {\n      onResult: options.onResult,\n      onError: options.onError,\n      onProgress: options.onProgress,\n      onChunk: options.onChunk,\n      onResultChange: options.onResultChange,\n      onLoadingChange: options.onLoadingChange,\n      onErrorChange: options.onErrorChange,\n      onStatusChange: options.onStatusChange,\n    }\n\n    this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools)\n    this.devtoolsBridge = (\n      options.devtoolsBridgeFactory ?? createNoOpGenerationDevtoolsBridge\n    )<TOutput>(this.buildDevtoolsBridgeOptions())\n  }\n\n  private buildDevtoolsBridgeOptions(): GenerationDevtoolsBridgeOptions<TOutput> {\n    return {\n      hookId: this.uniqueId,\n      clientId: this.uniqueId,\n      threadId: this.threadId,\n      metadata: this.devtoolsMetadata,\n      getCoreState: () => ({\n        input: this.input,\n        result: this.result,\n        progress: this.progress,\n        status: this.status,\n        isLoading: this.isLoading,\n        ...(this.error ? { error: this.error.message } : {}),\n      }),\n    }\n  }\n\n  mountDevtools(): void {\n    if (this.devtoolsMounted) {\n      return\n    }\n\n    this.devtoolsMounted = true\n    this.devtoolsBridge.emitRegistered()\n    this.devtoolsBridge.emitSnapshot()\n  }\n\n  /**\n   * Trigger a generation request.\n   * Only one generation can be in-flight at a time; calling generate()\n   * while already generating will be a no-op.\n   */\n  async generate(input: TInput): Promise<void> {\n    this.mountDevtools()\n    if (this.isLoading) return\n\n    this.input = input\n    this.progress = null\n    const runId = this.devtoolsBridge.beginRun(input)\n    this.setIsLoading(true)\n    this.setStatus('generating')\n    this.setError(undefined)\n\n    const abortController = new AbortController()\n    this.abortController = abortController\n    const { signal } = abortController\n\n    try {\n      if (this.fetcher) {\n        // Direct fetch path\n        const result = await this.fetcher(input, { signal })\n        if (signal.aborted) return\n        if (result instanceof Response) {\n          // Server function returned SSE Response — parse stream\n          await this.processStream(parseSSEResponse(result, signal), runId)\n        } else {\n          this.devtoolsBridge.ensureRunStarted(runId)\n          this.setResult(result)\n          this.setStatus('success')\n        }\n      } else if (this.connection) {\n        // Streaming adapter path\n        const mergedData = { ...this.body, ...input }\n        const stream = this.connection.connect(\n          [],\n          mergedData,\n          signal,\n          this.createRunContext(runId),\n        )\n        await this.processStream(stream, runId)\n      } else {\n        throw new Error(\n          'GenerationClient requires either a connection or fetcher option',\n        )\n      }\n      if (!signal.aborted && this.status === 'success') {\n        // Bump progress to 100 on successful completion so devtools\n        // snapshots reflect the final state. The bridge mirrors this in\n        // the run's recorded progress, but the snapshot reads `progress`\n        // from the client's core state.\n        this.progress = completeProgressValue(this.progress)\n        this.devtoolsBridge.finishRun(\n          this.devtoolsBridge.getActiveRunId() ?? runId,\n          'run:completed',\n          'completed',\n        )\n      }\n    } catch (err: unknown) {\n      if (signal.aborted) return\n      const error = err instanceof Error ? err : new Error(String(err))\n      this.setError(error)\n      this.setStatus('error')\n      this.devtoolsBridge.finishRun(\n        this.devtoolsBridge.getActiveRunId() ?? runId,\n        'run:errored',\n        'errored',\n        error.message,\n      )\n      this.callbacksRef.onError?.(error)\n    } finally {\n      this.abortController = null\n      this.setIsLoading(false)\n    }\n  }\n\n  /**\n   * Process a stream of AG-UI events from the streaming connection adapter.\n   */\n  private async processStream(\n    source: AsyncIterable<StreamChunk>,\n    fallbackRunId: string,\n  ): Promise<void> {\n    let streamRunId: string | undefined\n\n    for await (const chunk of source) {\n      if (this.abortController?.signal.aborted) break\n\n      this.callbacksRef.onChunk?.(chunk)\n      const chunkRunId =\n        'runId' in chunk && typeof chunk.runId === 'string'\n          ? chunk.runId\n          : undefined\n\n      // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- AG-UI EventType has ~22 variants; this consumer only handles the subset relevant to generation lifecycle.\n      switch (chunk.type) {\n        case 'RUN_STARTED': {\n          streamRunId = chunk.runId\n          this.devtoolsBridge.ensureRunStarted(chunk.runId)\n          break\n        }\n        case 'CUSTOM': {\n          this.devtoolsBridge.ensureRunStarted(streamRunId ?? fallbackRunId)\n          if (chunk.name === GENERATION_EVENTS.RESULT) {\n            this.setResult(chunk.value as TResult)\n          } else if (chunk.name === GENERATION_EVENTS.PROGRESS) {\n            const { progress, message } = chunk.value as {\n              progress: number\n              message?: string\n            }\n            this.setProgress(progress, message)\n          }\n          break\n        }\n        case 'RUN_FINISHED': {\n          streamRunId = chunk.runId\n          this.devtoolsBridge.ensureRunStarted(chunk.runId)\n          this.setStatus('success')\n          break\n        }\n        case 'RUN_ERROR': {\n          this.devtoolsBridge.ensureRunStarted(\n            chunkRunId ?? streamRunId ?? fallbackRunId,\n          )\n          // Prefer spec `message`; fall back to deprecated `error.message`\n          const msg =\n            (chunk.message as string | undefined) ||\n            chunk.error?.message ||\n            'An error occurred'\n          throw new Error(msg)\n        }\n        default:\n          break\n      }\n    }\n  }\n\n  /**\n   * Abort any in-flight generation request.\n   */\n  stop(): void {\n    const runId = this.devtoolsBridge.getActiveRunId()\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    this.setIsLoading(false)\n    if (this.status === 'generating') {\n      this.setStatus('idle')\n      if (runId) {\n        this.devtoolsBridge.finishRun(runId, 'run:cancelled', 'cancelled')\n      }\n    }\n  }\n\n  /**\n   * Clear the result, error, and return to idle state.\n   */\n  reset(): void {\n    this.stop()\n    this.setResult(null)\n    this.input = null\n    this.progress = null\n    this.devtoolsBridge.resetRuns()\n    this.setError(undefined)\n    this.setStatus('idle')\n    this.devtoolsBridge.emitState()\n  }\n\n  /**\n   * Update options without recreating the client.\n   */\n  updateOptions(\n    options: Partial<\n      Pick<\n        GenerationClientOptions<TInput, TResult, TOutput>,\n        'body' | 'onResult' | 'onError' | 'onProgress' | 'onChunk'\n      >\n    >,\n  ): void {\n    if (options.body !== undefined) {\n      this.body = options.body ?? {}\n    }\n    if (options.onResult !== undefined) {\n      this.callbacksRef.onResult = options.onResult\n    }\n    if (options.onError !== undefined) {\n      this.callbacksRef.onError = options.onError\n    }\n    if (options.onProgress !== undefined) {\n      this.callbacksRef.onProgress = options.onProgress\n    }\n    if (options.onChunk !== undefined) {\n      this.callbacksRef.onChunk = options.onChunk\n    }\n  }\n\n  dispose(): void {\n    this.stop()\n    this.devtoolsBridge.dispose()\n    this.devtoolsMounted = false\n  }\n\n  // ===========================\n  // Getters\n  // ===========================\n\n  getResult(): TOutput | null {\n    return this.result\n  }\n\n  getIsLoading(): boolean {\n    return this.isLoading\n  }\n\n  getError(): Error | undefined {\n    return this.error\n  }\n\n  getStatus(): GenerationClientState {\n    return this.status\n  }\n\n  // ===========================\n  // Private state setters\n  // ===========================\n\n  private setResult(rawResult: TResult | null): void {\n    if (rawResult === null) {\n      this.result = null\n      this.callbacksRef.onResultChange?.(null)\n      this.devtoolsBridge.recordResultChange()\n      return\n    }\n\n    if (this.callbacksRef.onResult) {\n      const transformed = this.callbacksRef.onResult(rawResult)\n      if (transformed === null) {\n        // null return → keep previous result unchanged, just re-emit\n        this.devtoolsBridge.emitState()\n        return\n      }\n      if (transformed !== undefined) {\n        // Non-null, non-undefined → use transformed value\n        this.result = transformed\n        this.callbacksRef.onResultChange?.(this.result)\n        this.devtoolsBridge.recordResultChange()\n        return\n      }\n    }\n\n    // No onResult callback, or callback returned void → use raw value as\n    // TOutput. When the caller did not supply an onResult transform,\n    // `TOutput` defaults to `TResult`, so the runtime cast is sound.\n    // eslint-disable-next-line no-restricted-syntax -- TOutput defaults to TResult when no onResult transform is supplied\n    this.result = rawResult as unknown as TOutput\n    this.callbacksRef.onResultChange?.(this.result)\n    this.devtoolsBridge.recordResultChange()\n  }\n\n  private setIsLoading(isLoading: boolean): void {\n    this.isLoading = isLoading\n    this.callbacksRef.onLoadingChange?.(isLoading)\n    this.devtoolsBridge.recordLoadingChange()\n  }\n\n  private setError(error: Error | undefined): void {\n    this.error = error\n    this.callbacksRef.onErrorChange?.(error)\n    this.devtoolsBridge.recordErrorChange(error)\n  }\n\n  private setStatus(status: GenerationClientState): void {\n    this.status = status\n    this.callbacksRef.onStatusChange?.(status)\n    this.devtoolsBridge.recordStatusChange(status)\n  }\n\n  private setProgress(value: number, message?: string): void {\n    this.progress = {\n      value,\n      ...(message ? { message } : {}),\n    }\n    if (message === undefined) {\n      this.callbacksRef.onProgress?.(value)\n    } else {\n      this.callbacksRef.onProgress?.(value, message)\n    }\n    this.devtoolsBridge.recordProgressChange()\n  }\n\n  private createDevtoolsMetadata(\n    metadata?: Partial<AIDevtoolsClientMetadata>,\n  ): AIDevtoolsClientMetadata {\n    return {\n      hookName: metadata?.hookName ?? 'useGeneration',\n      ...(metadata?.framework ? { framework: metadata.framework } : {}),\n      ...(metadata?.outputKind ? { outputKind: metadata.outputKind } : {}),\n      ...(metadata?.name ? { name: metadata.name } : {}),\n    }\n  }\n\n  private generateUniqueId(prefix: string): string {\n    return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n  }\n\n  private createRunContext(runId: string): RunAgentInputContext {\n    return {\n      threadId: this.threadId,\n      runId,\n    }\n  }\n}\n\nfunction completeProgressValue(\n  progress: AIDevtoolsGenerationProgress | null,\n): AIDevtoolsGenerationProgress | null {\n  if (!progress) return null\n  const message = progress.message\n  return {\n    value: 100,\n    ...(message ? { message } : {}),\n  }\n}\n"],"names":[],"mappings":";;;AAwEO,MAAM,iBAIX;AAAA,EACiB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACT;AAAA,EACA,SAAyB;AAAA,EACzB,QAAuB;AAAA,EACvB,WAAgD;AAAA,EAChD,YAAY;AAAA,EACZ,QAA2B;AAAA,EAC3B,SAAgC;AAAA,EAChC,kBAA0C;AAAA,EACjC;AAAA,EACT,kBAAkB;AAAA,EAE1B,YACE,SAQA;AACA,SAAK,WAAW,QAAQ,MAAM,KAAK,iBAAiB,YAAY;AAChE,SAAK,WAAW,KAAK;AACrB,SAAK,aAAa,QAAQ;AAC1B,SAAK,UAAU,QAAQ;AACvB,SAAK,OAAO,QAAQ,QAAQ,CAAA;AAE5B,SAAK,eAAe;AAAA,MAClB,UAAU,QAAQ;AAAA,MAClB,SAAS,QAAQ;AAAA,MACjB,YAAY,QAAQ;AAAA,MACpB,SAAS,QAAQ;AAAA,MACjB,gBAAgB,QAAQ;AAAA,MACxB,iBAAiB,QAAQ;AAAA,MACzB,eAAe,QAAQ;AAAA,MACvB,gBAAgB,QAAQ;AAAA,IAAA;AAG1B,SAAK,mBAAmB,KAAK,uBAAuB,QAAQ,QAAQ;AACpE,SAAK,kBACH,QAAQ,yBAAyB,oCACxB,KAAK,4BAA4B;AAAA,EAC9C;AAAA,EAEQ,6BAAuE;AAC7E,WAAO;AAAA,MACL,QAAQ,KAAK;AAAA,MACb,UAAU,KAAK;AAAA,MACf,UAAU,KAAK;AAAA,MACf,UAAU,KAAK;AAAA,MACf,cAAc,OAAO;AAAA,QACnB,OAAO,KAAK;AAAA,QACZ,QAAQ,KAAK;AAAA,QACb,UAAU,KAAK;AAAA,QACf,QAAQ,KAAK;AAAA,QACb,WAAW,KAAK;AAAA,QAChB,GAAI,KAAK,QAAQ,EAAE,OAAO,KAAK,MAAM,YAAY,CAAA;AAAA,MAAC;AAAA,IACpD;AAAA,EAEJ;AAAA,EAEA,gBAAsB;AACpB,QAAI,KAAK,iBAAiB;AACxB;AAAA,IACF;AAEA,SAAK,kBAAkB;AACvB,SAAK,eAAe,eAAA;AACpB,SAAK,eAAe,aAAA;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,SAAS,OAA8B;AAC3C,SAAK,cAAA;AACL,QAAI,KAAK,UAAW;AAEpB,SAAK,QAAQ;AACb,SAAK,WAAW;AAChB,UAAM,QAAQ,KAAK,eAAe,SAAS,KAAK;AAChD,SAAK,aAAa,IAAI;AACtB,SAAK,UAAU,YAAY;AAC3B,SAAK,SAAS,MAAS;AAEvB,UAAM,kBAAkB,IAAI,gBAAA;AAC5B,SAAK,kBAAkB;AACvB,UAAM,EAAE,WAAW;AAEnB,QAAI;AACF,UAAI,KAAK,SAAS;AAEhB,cAAM,SAAS,MAAM,KAAK,QAAQ,OAAO,EAAE,QAAQ;AACnD,YAAI,OAAO,QAAS;AACpB,YAAI,kBAAkB,UAAU;AAE9B,gBAAM,KAAK,cAAc,iBAAiB,QAAQ,MAAM,GAAG,KAAK;AAAA,QAClE,OAAO;AACL,eAAK,eAAe,iBAAiB,KAAK;AAC1C,eAAK,UAAU,MAAM;AACrB,eAAK,UAAU,SAAS;AAAA,QAC1B;AAAA,MACF,WAAW,KAAK,YAAY;AAE1B,cAAM,aAAa,EAAE,GAAG,KAAK,MAAM,GAAG,MAAA;AACtC,cAAM,SAAS,KAAK,WAAW;AAAA,UAC7B,CAAA;AAAA,UACA;AAAA,UACA;AAAA,UACA,KAAK,iBAAiB,KAAK;AAAA,QAAA;AAE7B,cAAM,KAAK,cAAc,QAAQ,KAAK;AAAA,MACxC,OAAO;AACL,cAAM,IAAI;AAAA,UACR;AAAA,QAAA;AAAA,MAEJ;AACA,UAAI,CAAC,OAAO,WAAW,KAAK,WAAW,WAAW;AAKhD,aAAK,WAAW,sBAAsB,KAAK,QAAQ;AACnD,aAAK,eAAe;AAAA,UAClB,KAAK,eAAe,eAAA,KAAoB;AAAA,UACxC;AAAA,UACA;AAAA,QAAA;AAAA,MAEJ;AAAA,IACF,SAAS,KAAc;AACrB,UAAI,OAAO,QAAS;AACpB,YAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;AAChE,WAAK,SAAS,KAAK;AACnB,WAAK,UAAU,OAAO;AACtB,WAAK,eAAe;AAAA,QAClB,KAAK,eAAe,eAAA,KAAoB;AAAA,QACxC;AAAA,QACA;AAAA,QACA,MAAM;AAAA,MAAA;AAER,WAAK,aAAa,UAAU,KAAK;AAAA,IACnC,UAAA;AACE,WAAK,kBAAkB;AACvB,WAAK,aAAa,KAAK;AAAA,IACzB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,MAAc,cACZ,QACA,eACe;AACf,QAAI;AAEJ,qBAAiB,SAAS,QAAQ;AAChC,UAAI,KAAK,iBAAiB,OAAO,QAAS;AAE1C,WAAK,aAAa,UAAU,KAAK;AACjC,YAAM,aACJ,WAAW,SAAS,OAAO,MAAM,UAAU,WACvC,MAAM,QACN;AAGN,cAAQ,MAAM,MAAA;AAAA,QACZ,KAAK,eAAe;AAClB,wBAAc,MAAM;AACpB,eAAK,eAAe,iBAAiB,MAAM,KAAK;AAChD;AAAA,QACF;AAAA,QACA,KAAK,UAAU;AACb,eAAK,eAAe,iBAAiB,eAAe,aAAa;AACjE,cAAI,MAAM,SAAS,kBAAkB,QAAQ;AAC3C,iBAAK,UAAU,MAAM,KAAgB;AAAA,UACvC,WAAW,MAAM,SAAS,kBAAkB,UAAU;AACpD,kBAAM,EAAE,UAAU,QAAA,IAAY,MAAM;AAIpC,iBAAK,YAAY,UAAU,OAAO;AAAA,UACpC;AACA;AAAA,QACF;AAAA,QACA,KAAK,gBAAgB;AACnB,wBAAc,MAAM;AACpB,eAAK,eAAe,iBAAiB,MAAM,KAAK;AAChD,eAAK,UAAU,SAAS;AACxB;AAAA,QACF;AAAA,QACA,KAAK,aAAa;AAChB,eAAK,eAAe;AAAA,YAClB,cAAc,eAAe;AAAA,UAAA;AAG/B,gBAAM,MACH,MAAM,WACP,MAAM,OAAO,WACb;AACF,gBAAM,IAAI,MAAM,GAAG;AAAA,QACrB;AAAA,MAEE;AAAA,IAEN;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAa;AACX,UAAM,QAAQ,KAAK,eAAe,eAAA;AAClC,QAAI,KAAK,iBAAiB;AACxB,WAAK,gBAAgB,MAAA;AACrB,WAAK,kBAAkB;AAAA,IACzB;AACA,SAAK,aAAa,KAAK;AACvB,QAAI,KAAK,WAAW,cAAc;AAChC,WAAK,UAAU,MAAM;AACrB,UAAI,OAAO;AACT,aAAK,eAAe,UAAU,OAAO,iBAAiB,WAAW;AAAA,MACnE;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACZ,SAAK,KAAA;AACL,SAAK,UAAU,IAAI;AACnB,SAAK,QAAQ;AACb,SAAK,WAAW;AAChB,SAAK,eAAe,UAAA;AACpB,SAAK,SAAS,MAAS;AACvB,SAAK,UAAU,MAAM;AACrB,SAAK,eAAe,UAAA;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA,EAKA,cACE,SAMM;AACN,QAAI,QAAQ,SAAS,QAAW;AAC9B,WAAK,OAAO,QAAQ,QAAQ,CAAA;AAAA,IAC9B;AACA,QAAI,QAAQ,aAAa,QAAW;AAClC,WAAK,aAAa,WAAW,QAAQ;AAAA,IACvC;AACA,QAAI,QAAQ,YAAY,QAAW;AACjC,WAAK,aAAa,UAAU,QAAQ;AAAA,IACtC;AACA,QAAI,QAAQ,eAAe,QAAW;AACpC,WAAK,aAAa,aAAa,QAAQ;AAAA,IACzC;AACA,QAAI,QAAQ,YAAY,QAAW;AACjC,WAAK,aAAa,UAAU,QAAQ;AAAA,IACtC;AAAA,EACF;AAAA,EAEA,UAAgB;AACd,SAAK,KAAA;AACL,SAAK,eAAe,QAAA;AACpB,SAAK,kBAAkB;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA,EAMA,YAA4B;AAC1B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,eAAwB;AACtB,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,WAA8B;AAC5B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,YAAmC;AACjC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA,EAMQ,UAAU,WAAiC;AACjD,QAAI,cAAc,MAAM;AACtB,WAAK,SAAS;AACd,WAAK,aAAa,iBAAiB,IAAI;AACvC,WAAK,eAAe,mBAAA;AACpB;AAAA,IACF;AAEA,QAAI,KAAK,aAAa,UAAU;AAC9B,YAAM,cAAc,KAAK,aAAa,SAAS,SAAS;AACxD,UAAI,gBAAgB,MAAM;AAExB,aAAK,eAAe,UAAA;AACpB;AAAA,MACF;AACA,UAAI,gBAAgB,QAAW;AAE7B,aAAK,SAAS;AACd,aAAK,aAAa,iBAAiB,KAAK,MAAM;AAC9C,aAAK,eAAe,mBAAA;AACpB;AAAA,MACF;AAAA,IACF;AAMA,SAAK,SAAS;AACd,SAAK,aAAa,iBAAiB,KAAK,MAAM;AAC9C,SAAK,eAAe,mBAAA;AAAA,EACtB;AAAA,EAEQ,aAAa,WAA0B;AAC7C,SAAK,YAAY;AACjB,SAAK,aAAa,kBAAkB,SAAS;AAC7C,SAAK,eAAe,oBAAA;AAAA,EACtB;AAAA,EAEQ,SAAS,OAAgC;AAC/C,SAAK,QAAQ;AACb,SAAK,aAAa,gBAAgB,KAAK;AACvC,SAAK,eAAe,kBAAkB,KAAK;AAAA,EAC7C;AAAA,EAEQ,UAAU,QAAqC;AACrD,SAAK,SAAS;AACd,SAAK,aAAa,iBAAiB,MAAM;AACzC,SAAK,eAAe,mBAAmB,MAAM;AAAA,EAC/C;AAAA,EAEQ,YAAY,OAAe,SAAwB;AACzD,SAAK,WAAW;AAAA,MACd;AAAA,MACA,GAAI,UAAU,EAAE,YAAY,CAAA;AAAA,IAAC;AAE/B,QAAI,YAAY,QAAW;AACzB,WAAK,aAAa,aAAa,KAAK;AAAA,IACtC,OAAO;AACL,WAAK,aAAa,aAAa,OAAO,OAAO;AAAA,IAC/C;AACA,SAAK,eAAe,qBAAA;AAAA,EACtB;AAAA,EAEQ,uBACN,UAC0B;AAC1B,WAAO;AAAA,MACL,UAAU,UAAU,YAAY;AAAA,MAChC,GAAI,UAAU,YAAY,EAAE,WAAW,SAAS,UAAA,IAAc,CAAA;AAAA,MAC9D,GAAI,UAAU,aAAa,EAAE,YAAY,SAAS,WAAA,IAAe,CAAA;AAAA,MACjE,GAAI,UAAU,OAAO,EAAE,MAAM,SAAS,KAAA,IAAS,CAAA;AAAA,IAAC;AAAA,EAEpD;AAAA,EAEQ,iBAAiB,QAAwB;AAC/C,WAAO,GAAG,MAAM,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAAA,EAC3E;AAAA,EAEQ,iBAAiB,OAAqC;AAC5D,WAAO;AAAA,MACL,UAAU,KAAK;AAAA,MACf;AAAA,IAAA;AAAA,EAEJ;AACF;AAEA,SAAS,sBACP,UACqC;AACrC,MAAI,CAAC,SAAU,QAAO;AACtB,QAAM,UAAU,SAAS;AACzB,SAAO;AAAA,IACL,OAAO;AAAA,IACP,GAAI,UAAU,EAAE,YAAY,CAAA;AAAA,EAAC;AAEjC;"}

package/dist/esm/generation-types.d.ts

@@ -1,5 +1,7 @@
 import { StreamChunk } from '@tanstack/ai';
 import { ConnectConnectionAdapter } from './connection-adapters.js';
+import { AIDevtoolsClientMetadata } from './devtools.js';
+import { GenerationDevtoolsBridgeFactory, VideoDevtoolsBridgeFactory } from './devtools-noop.js';
 /**
  * Infers the output type from an `onResult` callback's return type.
  *
@@ -71,6 +73,13 @@ export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
     id?: string;
     /** Additional body parameters to send with connect-based adapter requests */
     body?: Record<string, any>;
+    /** Metadata used to register this generation hook with TanStack AI Devtools */
+    devtools?: Partial<AIDevtoolsClientMetadata>;
+    /**
+     * Factory that constructs the devtools bridge. Default is a no-op
+     * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
+     */
+    devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory;
     /**
      * Callback when a result is received. Can optionally return a transformed value
      * that replaces the stored result.
@@ -126,7 +135,12 @@ export interface VideoGenerateResult {
 /**
  * Options for the VideoGenerationClient.
  */
-export interface VideoGenerationClientOptions<TOutput = VideoGenerateResult> extends GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput> {
+export interface VideoGenerationClientOptions<TOutput = VideoGenerateResult> extends Omit<GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>, 'devtoolsBridgeFactory'> {
+    /**
+     * Factory that constructs the video devtools bridge. Default is a no-op
+     * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
+     */
+    devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory;
     /** Callback when a video job is created */
     onJobCreated?: (jobId: string) => void;
     /** Callback on each status update */

package/dist/esm/generation-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"generation-types.js","sources":["../../src/generation-types.ts"],"sourcesContent":["import type { StreamChunk } from '@tanstack/ai'\nimport type { ConnectConnectionAdapter } from './connection-adapters'\n\n// ===========================\n// Inference Utilities\n// ===========================\n\n/**\n * Infers the output type from an `onResult` callback's return type.\n *\n * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.\n * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.\n *\n * @template TResult - The raw result type from the generation\n * @template TFn - The onResult callback type (or undefined if not provided)\n */\nexport type InferGenerationOutput<TResult, TFn> = TFn extends (\n  result: any,\n) => infer R\n  ? [Exclude<R, null | void | undefined>] extends [never]\n    ? TResult\n    : Exclude<R, null | void | undefined>\n  : TResult\n\n// ===========================\n// State\n// ===========================\n\n/**\n * State machine for generation clients.\n * Simpler than ChatClientState since generation is a single request/response cycle.\n */\nexport type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'\n\n// ===========================\n// Event Constants\n// ===========================\n\n/**\n * Well-known CUSTOM event names used by generation clients.\n * These events are emitted by the server-side streaming helpers\n * and consumed by the client-side GenerationClient.\n */\nexport const GENERATION_EVENTS = {\n  /** The generation result payload */\n  RESULT: 'generation:result',\n  /** Progress update (0-100) with optional message */\n  PROGRESS: 'generation:progress',\n  /** Video job created with jobId */\n  VIDEO_JOB_CREATED: 'video:job:created',\n  /** Video job status update */\n  VIDEO_STATUS: 'video:status',\n} as const\n\n// ===========================\n// Transport Types\n// ===========================\n\n/**\n * Options passed to a fetcher function by the generation client.\n */\nexport interface GenerationFetcherOptions {\n  /** AbortSignal that is triggered when the user calls `stop()` */\n  signal: AbortSignal\n}\n\n/**\n * A direct async function that performs a generation request.\n *\n * Can return the result directly, or return a `Response` with an SSE body\n * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).\n * When a `Response` is returned, the client will parse it as an SSE stream.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n */\nexport type GenerationFetcher<TInput, TResult> = (\n  input: TInput,\n  options?: GenerationFetcherOptions,\n) => Promise<TResult | Response>\n\n/**\n * Transport configuration for generation clients.\n * Supports either a connect-based streaming adapter or a direct fetcher function.\n */\nexport type GenerationTransport<TInput, TResult> =\n  | { connection: ConnectConnectionAdapter; fetcher?: never }\n  | { fetcher: GenerationFetcher<TInput, TResult>; connection?: never }\n\n// ===========================\n// Client Options\n// ===========================\n\n/**\n * Options for the GenerationClient.\n *\n * @template TInput - The input type for the generation request (used by consuming code)\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention -- _TInput is unused in the interface body but part of the public positional generic API (callers supply it for inference)\nexport interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {\n  /** Unique identifier for this generation client instance */\n  id?: string\n\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n\n  /**\n   * Callback when a result is received. Can optionally return a transformed value\n   * that replaces the stored result.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: TResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n\n  // Framework state callbacks (set by hooks, not users)\n  /** @internal Called when result changes */\n  onResultChange?: (result: TOutput | null) => void\n  /** @internal Called when loading state changes */\n  onLoadingChange?: (isLoading: boolean) => void\n  /** @internal Called when error state changes */\n  onErrorChange?: (error: Error | undefined) => void\n  /** @internal Called when generation status changes */\n  onStatusChange?: (status: GenerationClientState) => void\n}\n\n// ===========================\n// Video-Specific Options\n// ===========================\n\n/**\n * Video status information returned during job polling.\n */\nexport interface VideoStatusInfo {\n  /** Job identifier */\n  jobId: string\n  /** Current status of the video generation job */\n  status: 'pending' | 'processing' | 'completed' | 'failed'\n  /** Progress percentage (0-100), if available */\n  progress?: number\n  /** URL to the generated video (when completed) */\n  url?: string\n  /** Error message if status is 'failed' */\n  error?: string\n}\n\n/**\n * Composite result for video generation (job completion).\n */\nexport interface VideoGenerateResult {\n  /** Job identifier */\n  jobId: string\n  /** Final status */\n  status: 'completed'\n  /** URL to the generated video */\n  url: string\n  /** When the URL expires, if applicable */\n  expiresAt?: Date\n}\n\n/**\n * Options for the VideoGenerationClient.\n */\nexport interface VideoGenerationClientOptions<\n  TOutput = VideoGenerateResult,\n> extends GenerationClientOptions<\n  VideoGenerateInput,\n  VideoGenerateResult,\n  TOutput\n> {\n  /** Callback when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n\n  // Framework state callbacks\n  /** @internal Called when jobId changes */\n  onJobIdChange?: (jobId: string | null) => void\n  /** @internal Called when video status changes */\n  onVideoStatusChange?: (status: VideoStatusInfo | null) => void\n}\n\n// ===========================\n// Input Types\n// ===========================\n\n/**\n * Input for image generation.\n */\nexport interface ImageGenerateInput {\n  /** Text description of the desired image(s) */\n  prompt: string\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: string\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio generation (music, sound effects).\n */\nexport interface AudioGenerateInput {\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text-to-speech generation.\n */\nexport interface SpeechGenerateInput {\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio transcription.\n */\nexport interface TranscriptionGenerateInput {\n  /** The audio data to transcribe - can be base64 string, File, Blob, or ArrayBuffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text summarization.\n */\nexport interface SummarizeGenerateInput {\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary */\n  maxLength?: number\n  /** Style of the summary */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics to focus on */\n  focus?: Array<string>\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for video generation.\n */\nexport interface VideoGenerateInput {\n  /** Text description of the desired video */\n  prompt: string\n  /** Video size — format depends on provider (e.g., \"16:9\", \"1280x720\") */\n  size?: string\n  /** Video duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n"],"names":[],"mappings":"AA2CO,MAAM,oBAAoB;AAAA;AAAA,EAE/B,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,mBAAmB;AAAA;AAAA,EAEnB,cAAc;AAChB;"}
+{"version":3,"file":"generation-types.js","sources":["../../src/generation-types.ts"],"sourcesContent":["import type { StreamChunk } from '@tanstack/ai'\nimport type { ConnectConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type {\n  GenerationDevtoolsBridgeFactory,\n  VideoDevtoolsBridgeFactory,\n} from './devtools-noop'\n\n// ===========================\n// Inference Utilities\n// ===========================\n\n/**\n * Infers the output type from an `onResult` callback's return type.\n *\n * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.\n * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.\n *\n * @template TResult - The raw result type from the generation\n * @template TFn - The onResult callback type (or undefined if not provided)\n */\nexport type InferGenerationOutput<TResult, TFn> = TFn extends (\n  result: any,\n) => infer R\n  ? [Exclude<R, null | void | undefined>] extends [never]\n    ? TResult\n    : Exclude<R, null | void | undefined>\n  : TResult\n\n// ===========================\n// State\n// ===========================\n\n/**\n * State machine for generation clients.\n * Simpler than ChatClientState since generation is a single request/response cycle.\n */\nexport type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'\n\n// ===========================\n// Event Constants\n// ===========================\n\n/**\n * Well-known CUSTOM event names used by generation clients.\n * These events are emitted by the server-side streaming helpers\n * and consumed by the client-side GenerationClient.\n */\nexport const GENERATION_EVENTS = {\n  /** The generation result payload */\n  RESULT: 'generation:result',\n  /** Progress update (0-100) with optional message */\n  PROGRESS: 'generation:progress',\n  /** Video job created with jobId */\n  VIDEO_JOB_CREATED: 'video:job:created',\n  /** Video job status update */\n  VIDEO_STATUS: 'video:status',\n} as const\n\n// ===========================\n// Transport Types\n// ===========================\n\n/**\n * Options passed to a fetcher function by the generation client.\n */\nexport interface GenerationFetcherOptions {\n  /** AbortSignal that is triggered when the user calls `stop()` */\n  signal: AbortSignal\n}\n\n/**\n * A direct async function that performs a generation request.\n *\n * Can return the result directly, or return a `Response` with an SSE body\n * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).\n * When a `Response` is returned, the client will parse it as an SSE stream.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n */\nexport type GenerationFetcher<TInput, TResult> = (\n  input: TInput,\n  options?: GenerationFetcherOptions,\n) => Promise<TResult | Response>\n\n/**\n * Transport configuration for generation clients.\n * Supports either a connect-based streaming adapter or a direct fetcher function.\n */\nexport type GenerationTransport<TInput, TResult> =\n  | { connection: ConnectConnectionAdapter; fetcher?: never }\n  | { fetcher: GenerationFetcher<TInput, TResult>; connection?: never }\n\n// ===========================\n// Client Options\n// ===========================\n\n/**\n * Options for the GenerationClient.\n *\n * @template TInput - The input type for the generation request (used by consuming code)\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention -- _TInput is unused in the interface body but part of the public positional generic API (callers supply it for inference)\nexport interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {\n  /** Unique identifier for this generation client instance */\n  id?: string\n\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n\n  /** Metadata used to register this generation hook with TanStack AI Devtools */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory\n\n  /**\n   * Callback when a result is received. Can optionally return a transformed value\n   * that replaces the stored result.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: TResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n\n  // Framework state callbacks (set by hooks, not users)\n  /** @internal Called when result changes */\n  onResultChange?: (result: TOutput | null) => void\n  /** @internal Called when loading state changes */\n  onLoadingChange?: (isLoading: boolean) => void\n  /** @internal Called when error state changes */\n  onErrorChange?: (error: Error | undefined) => void\n  /** @internal Called when generation status changes */\n  onStatusChange?: (status: GenerationClientState) => void\n}\n\n// ===========================\n// Video-Specific Options\n// ===========================\n\n/**\n * Video status information returned during job polling.\n */\nexport interface VideoStatusInfo {\n  /** Job identifier */\n  jobId: string\n  /** Current status of the video generation job */\n  status: 'pending' | 'processing' | 'completed' | 'failed'\n  /** Progress percentage (0-100), if available */\n  progress?: number\n  /** URL to the generated video (when completed) */\n  url?: string\n  /** Error message if status is 'failed' */\n  error?: string\n}\n\n/**\n * Composite result for video generation (job completion).\n */\nexport interface VideoGenerateResult {\n  /** Job identifier */\n  jobId: string\n  /** Final status */\n  status: 'completed'\n  /** URL to the generated video */\n  url: string\n  /** When the URL expires, if applicable */\n  expiresAt?: Date\n}\n\n/**\n * Options for the VideoGenerationClient.\n */\nexport interface VideoGenerationClientOptions<\n  TOutput = VideoGenerateResult,\n> extends Omit<\n  GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>,\n  'devtoolsBridgeFactory'\n> {\n  /**\n   * Factory that constructs the video devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory\n\n  /** Callback when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n\n  // Framework state callbacks\n  /** @internal Called when jobId changes */\n  onJobIdChange?: (jobId: string | null) => void\n  /** @internal Called when video status changes */\n  onVideoStatusChange?: (status: VideoStatusInfo | null) => void\n}\n\n// ===========================\n// Input Types\n// ===========================\n\n/**\n * Input for image generation.\n */\nexport interface ImageGenerateInput {\n  /** Text description of the desired image(s) */\n  prompt: string\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: string\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio generation (music, sound effects).\n */\nexport interface AudioGenerateInput {\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text-to-speech generation.\n */\nexport interface SpeechGenerateInput {\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio transcription.\n */\nexport interface TranscriptionGenerateInput {\n  /** The audio data to transcribe - can be base64 string, File, Blob, or ArrayBuffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text summarization.\n */\nexport interface SummarizeGenerateInput {\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary */\n  maxLength?: number\n  /** Style of the summary */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics to focus on */\n  focus?: Array<string>\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for video generation.\n */\nexport interface VideoGenerateInput {\n  /** Text description of the desired video */\n  prompt: string\n  /** Video size — format depends on provider (e.g., \"16:9\", \"1280x720\") */\n  size?: string\n  /** Video duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n"],"names":[],"mappings":"AAgDO,MAAM,oBAAoB;AAAA;AAAA,EAE/B,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,mBAAmB;AAAA;AAAA,EAEnB,cAAc;AAChB;"}

package/dist/esm/index.d.ts

@@ -6,6 +6,7 @@ export type { UIMessage, MessagePart, TextPart, ToolCallPart, ToolResultPart, Th
 export type { InferGenerationOutput, GenerationClientState, GenerationClientOptions, GenerationFetcher, GenerationFetcherOptions, GenerationTransport, VideoGenerationClientOptions, VideoStatusInfo, VideoGenerateResult, ImageGenerateInput, AudioGenerateInput, SpeechGenerateInput, TranscriptionGenerateInput, SummarizeGenerateInput, VideoGenerateInput, } from './generation-types.js';
 export { GENERATION_EVENTS } from './generation-types.js';
 export { clientTools, createChatClientOptions } from './types.js';
+export { createAIDevtoolsGenerationPreview, type AIDevtoolsClientMetadata, type AIDevtoolsDisplayOptions, type AIDevtoolsGenerationMediaItem, type AIDevtoolsGenerationPreview, type AIDevtoolsGenerationProgress, type AIDevtoolsGenerationVideoJob, } from './devtools.js';
 export type { ExtractToolNames, ExtractToolInput, ExtractToolOutput, } from './tool-types.js';
 export type { AnyClientTool } from '@tanstack/ai';
 export type { RealtimeAdapter, RealtimeConnection, RealtimeClientOptions, RealtimeClientState, RealtimeStateChangeCallback, } from './realtime-types.js';

package/dist/esm/index.js

@@ -4,6 +4,7 @@ import { GenerationClient } from "./generation-client.js";
 import { VideoGenerationClient } from "./video-generation-client.js";
 import { GENERATION_EVENTS } from "./generation-types.js";
 import { clientTools, createChatClientOptions } from "./types.js";
+import { createAIDevtoolsGenerationPreview } from "./devtools.js";
 import { StreamTruncatedError, fetchHttpStream, fetchServerSentEvents, rpcStream, stream } from "./connection-adapters.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PartialJSONParser, PunctuationStrategy, StreamProcessor, WordBoundaryStrategy, convertMessagesToModelMessages, defaultJSONParser, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, uiMessageToModelMessages } from "@tanstack/ai";
 export {
@@ -22,6 +23,7 @@ export {
   WordBoundaryStrategy,
   clientTools,
   convertMessagesToModelMessages,
+  createAIDevtoolsGenerationPreview,
   createChatClientOptions,
   defaultJSONParser,
   fetchHttpStream,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}

package/dist/esm/types.d.ts

@@ -1,5 +1,7 @@
 import { AnyClientTool, AudioPart, ChunkStrategy, ContentPart, DocumentPart, ImagePart, InferToolInput, InferToolOutput, ModelMessage, StreamChunk, StructuredOutputPart, VideoPart } from '@tanstack/ai';
 import { ConnectionAdapter } from './connection-adapters.js';
+import { AIDevtoolsClientMetadata } from './devtools.js';
+import { ChatDevtoolsBridgeFactory } from './devtools-noop.js';
 export type { StructuredOutputPart } from '@tanstack/ai';
 /**
  * `messages` is the full UIMessage history (not a delta). `data` is the
@@ -192,7 +194,7 @@ export interface UIMessage<TTools extends ReadonlyArray<AnyClientTool> = any, TD
  * Options for `ChatClient`. Exactly one of `connection` or `fetcher` must be
  * provided — the type-level XOR is enforced via `ChatTransport`.
  */
-export type ChatClientOptions<TTools extends ReadonlyArray<AnyClientTool> = any> = {
+export type ChatClientOptions<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = unknown> = {
     /**
      * Initial messages to populate the chat
      */
@@ -289,6 +291,22 @@ export type ChatClientOptions<TTools extends ReadonlyArray<AnyClientTool> = any>
      * When provided, tools with execute functions will be called automatically
      */
     tools?: TTools;
+    /**
+     * Client-local context passed to client-side tool execution.
+     */
+    context?: TContext;
+    /**
+     * Devtools hook metadata for this client instance.
+     */
+    devtools?: Partial<AIDevtoolsClientMetadata>;
+    /**
+     * Factory that constructs the devtools bridge. Default is a no-op
+     * factory, which keeps `@tanstack/ai-client/devtools` (the heavy
+     * bridge implementation) out of the main entry's bundle. Frameworks
+     * that need live devtools should pass the real factory from
+     * `@tanstack/ai-client/devtools`.
+     */
+    devtoolsBridgeFactory?: ChatDevtoolsBridgeFactory;
     /**
      * Stream processing options (optional)
      * Configure chunking strategy
@@ -337,7 +355,7 @@ export declare function clientTools<const T extends Array<AnyClientTool>>(...too
  * type MyMessages = InferChatMessages<typeof chatOptions>
  * ```
  */
-export declare function createChatClientOptions<const TTools extends ReadonlyArray<AnyClientTool>>(options: ChatClientOptions<TTools>): ChatClientOptions<TTools>;
+export declare function createChatClientOptions<const TTools extends ReadonlyArray<AnyClientTool>, TContext = unknown>(options: ChatClientOptions<TTools, TContext>): ChatClientOptions<TTools, TContext>;
 /**
  * Extract the message type from chat options
  *
@@ -352,4 +370,4 @@ export declare function createChatClientOptions<const TTools extends ReadonlyArr
  * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>
  * ```
  */
-export type InferChatMessages<T> = T extends ChatClientOptions<infer TTools> ? Array<UIMessage<TTools>> : never;
+export type InferChatMessages<T> = T extends ChatClientOptions<infer TTools, any> ? Array<UIMessage<TTools>> : never;

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  AnyClientTool,\n  AudioPart,\n  ChunkStrategy,\n  ContentPart,\n  DocumentPart,\n  ImagePart,\n  InferToolInput,\n  InferToolOutput,\n  ModelMessage,\n  StreamChunk,\n  StructuredOutputPart,\n  VideoPart,\n} from '@tanstack/ai'\nimport type { ConnectionAdapter } from './connection-adapters'\n\nexport type { StructuredOutputPart } from '@tanstack/ai'\n\n/**\n * `messages` is the full UIMessage history (not a delta). `data` is the\n * merged body — `ChatClientOptions.body` plus any per-call data passed to\n * `sendMessage(...)`. `threadId` / `runId` are the AG-UI correlation ids\n * the chat client uses to track this turn — forward them to your server\n * if it needs to correlate requests.\n */\nexport interface ChatFetcherInput {\n  messages: Array<UIMessage>\n  data?: Record<string, unknown>\n  threadId: string\n  runId: string\n}\n\nexport interface ChatFetcherOptions {\n  /** Fires when `stop()` is called or the request is superseded. */\n  signal: AbortSignal\n}\n\n/**\n * Direct function that performs a chat request. Mirrors\n * `GenerationFetcher`. Returns either a `Response` (SSE body parsed by the\n * chat client) or an `AsyncIterable<StreamChunk>` (yielded directly). May\n * return the value synchronously, as a `Promise`, or as an async generator\n * (`async function*`) — the chat client awaits whichever shape is returned.\n *\n * @example\n * ```ts\n * useChat({\n *   fetcher: ({ messages }, { signal }) =>\n *     chatFn({ data: { messages }, signal }),\n * })\n * ```\n */\nexport type ChatFetcher = (\n  input: ChatFetcherInput,\n  options: ChatFetcherOptions,\n) =>\n  | Response\n  | AsyncIterable<StreamChunk>\n  | Promise<Response | AsyncIterable<StreamChunk>>\n\n/**\n * Distributive `Omit` — applies `Omit<O, K>` per branch of a union so\n * discriminated unions survive omission. Plain `Omit` collapses unions\n * into a single object shape, which would erase the `ChatTransport` XOR\n * when framework hooks omit React-managed callbacks from\n * `ChatClientOptions`.\n */\nexport type DistributedOmit<\n  TObject,\n  TKeys extends keyof any,\n> = TObject extends unknown ? Omit<TObject, TKeys> : never\n\n/**\n * Discriminated union enforcing that exactly one of `connection` or\n * `fetcher` is provided. Mirrors `GenerationTransport`.\n */\nexport type ChatTransport =\n  | { connection: ConnectionAdapter; fetcher?: never }\n  | { fetcher: ChatFetcher; connection?: never }\n\n/**\n * Tool call states - track the lifecycle of a tool call\n */\nexport type ToolCallState =\n  | 'awaiting-input' // Received start but no arguments yet\n  | 'input-streaming' // Partial arguments received\n  | 'input-complete' // All arguments received\n  | 'approval-requested' // Waiting for user approval\n  | 'approval-responded' // User has approved/denied\n  | 'complete' // Result is complete\n\n/**\n * Tool result states - track the lifecycle of a tool result\n */\nexport type ToolResultState =\n  | 'streaming' // Placeholder for future streamed output\n  | 'complete' // Result is complete\n  | 'error' // Error occurred\n\n/**\n * ChatClient state - track the lifecycle of a chat\n */\nexport type ChatClientState = 'ready' | 'submitted' | 'streaming' | 'error'\n\n/**\n * Connection lifecycle state for the subscription loop.\n */\nexport type ConnectionStatus =\n  | 'disconnected'\n  | 'connecting'\n  | 'connected'\n  | 'error'\n\n/**\n * Multimodal content input for sending messages with rich media.\n * Allows sending text, images, audio, video, and documents to the LLM.\n *\n * @example\n * ```ts\n * // Send an image with a question\n * client.sendMessage({\n *   content: [\n *     { type: 'text', content: 'What is in this image?' },\n *     { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }\n *   ],\n *   id: 'custom-message-id' // optional\n * })\n * ```\n */\nexport interface MultimodalContent {\n  /**\n   * The content of the message.\n   * Can be a simple string or an array of content parts for multimodal messages.\n   */\n  content: string | Array<ContentPart>\n  /**\n   * Optional custom ID for the message.\n   * If not provided, a unique ID will be generated.\n   */\n  id?: string\n}\n\n/**\n * Message parts - building blocks of UIMessage\n */\nexport interface TextPart {\n  type: 'text'\n  content: string\n}\n\n/**\n * Helper type that creates a tool-call part for a specific tool.\n * This is a conditional type to enable proper distribution over union types,\n * creating a discriminated union where `name` is the discriminant.\n */\ntype ToolCallPartForTool<T> = T extends AnyClientTool\n  ? {\n      type: 'tool-call'\n      id: string\n      name: T['name']\n      arguments: string // JSON string (may be incomplete)\n      /** Parsed tool input (typed from inputSchema) */\n      input?: InferToolInput<T>\n      state: ToolCallState\n      /** Approval metadata if tool requires user approval */\n      approval?: {\n        id: string // Unique approval ID\n        needsApproval: boolean // Always true if present\n        approved?: boolean // User's decision (undefined until responded)\n      }\n      /** Tool execution output (for client tools or after approval) */\n      output?: InferToolOutput<T>\n    }\n  : never\n\n/**\n * Fallback tool-call part type when tools are not typed\n */\ntype UntypedToolCallPart = {\n  type: 'tool-call'\n  id: string\n  name: string\n  arguments: string\n  input?: any\n  state: ToolCallState\n  approval?: {\n    id: string\n    needsApproval: boolean\n    approved?: boolean\n  }\n  output?: any\n}\n\n/**\n * Tool call part that creates a proper discriminated union.\n * When TTools is typed, checking `part.name === 'toolName'` will narrow\n * `part.output` to the correct type for that tool.\n *\n * The discriminant is `name`, so code like:\n * ```ts\n * if (part.name === 'recommendGuitar') {\n *   // part.output is now typed to the recommendGuitar tool's output\n * }\n * ```\n */\nexport type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> =\n  // Check if we have a concrete tools array (not 'any' or 'never')\n  [TTools] extends [never]\n    ? UntypedToolCallPart\n    : unknown extends TTools\n      ? UntypedToolCallPart\n      : TTools extends ReadonlyArray<infer Tool>\n        ? Tool extends AnyClientTool\n          ? ToolCallPartForTool<Tool>\n          : UntypedToolCallPart\n        : UntypedToolCallPart\n\nexport interface ToolResultPart {\n  type: 'tool-result'\n  toolCallId: string\n  content: string\n  state: ToolResultState\n  error?: string // Error message if state is \"error\"\n}\n\nexport interface ThinkingPart {\n  type: 'thinking'\n  content: string\n}\n\nexport type MessagePart<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> =\n  | TextPart\n  | ImagePart\n  | AudioPart\n  | VideoPart\n  | DocumentPart\n  | ToolCallPart<TTools>\n  | ToolResultPart\n  | ThinkingPart\n  | StructuredOutputPart<TData>\n\n/**\n * UIMessage - Domain-specific message format optimized for building chat UIs\n * Contains parts that can be text, tool calls, or tool results.\n *\n * `TTools` narrows the tool-call/result part types based on the registered\n * tools. `TData` is the schema-inferred type for any `structured-output` part\n * on the message — defaulted to `unknown` so untyped consumers (the core\n * stream processor, the wire converter) don't need to thread a schema generic\n * everywhere; the hook layer (`useChat({ outputSchema })`) substitutes it on\n * the public return so `m.parts.find(p => p.type === 'structured-output').data`\n * is typed without manual casts.\n */\nexport interface UIMessage<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> {\n  id: string\n  role: 'system' | 'user' | 'assistant'\n  parts: Array<MessagePart<TTools, TData>>\n  createdAt?: Date\n}\n\n/**\n * Options for `ChatClient`. Exactly one of `connection` or `fetcher` must be\n * provided — the type-level XOR is enforced via `ChatTransport`.\n */\nexport type ChatClientOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n> = {\n  /**\n   * Initial messages to populate the chat\n   */\n  initialMessages?: Array<UIMessage<TTools>>\n\n  /**\n   * Unique identifier for this chat instance\n   * Used for managing multiple chats\n   */\n  id?: string\n\n  /**\n   * Thread ID to use for this chat session. Persists across sends within\n   * the session. If omitted, a unique thread ID is generated.\n   */\n  threadId?: string\n\n  /**\n   * Arbitrary client-controlled JSON forwarded to the server in the\n   * AG-UI `RunAgentInput.forwardedProps` field. Use this for per-session\n   * options like provider/model selection or feature flags that the\n   * server endpoint should read.\n   *\n   * Replaces the legacy `body` option. If both are provided,\n   * `forwardedProps` wins on key collision.\n   */\n  forwardedProps?: Record<string, any>\n\n  /**\n   * @deprecated Use `forwardedProps` instead. `body` continues to work\n   * unchanged — its values are merged into the AG-UI\n   * `RunAgentInput.forwardedProps` field on the wire and are also\n   * mirrored under the legacy `data` field for servers that have not\n   * migrated yet. Will be removed in a future major release.\n   */\n  body?: Record<string, any>\n\n  /**\n   * Callback when a response is received\n   */\n  onResponse?: (response?: Response) => void | Promise<void>\n\n  /**\n   * Callback when a stream chunk is received\n   */\n  onChunk?: (chunk: StreamChunk) => void\n\n  /**\n   * Callback when the response is finished\n   */\n  onFinish?: (message: UIMessage<TTools>) => void\n\n  /**\n   * Callback when an error occurs\n   */\n  onError?: (error: Error) => void\n\n  /**\n   * Callback when messages change\n   */\n  onMessagesChange?: (messages: Array<UIMessage<TTools>>) => void\n\n  /**\n   * Callback when loading state changes\n   */\n  onLoadingChange?: (isLoading: boolean) => void\n\n  /**\n   * Callback when error state changes\n   */\n  onErrorChange?: (error: Error | undefined) => void\n\n  /**\n   * Callback when chat status changes\n   */\n  onStatusChange?: (status: ChatClientState) => void\n\n  /**\n   * Callback when subscription lifecycle changes.\n   * This is independent from request lifecycle (`isLoading`, `status`).\n   */\n  onSubscriptionChange?: (isSubscribed: boolean) => void\n\n  /**\n   * Callback when connection lifecycle changes.\n   */\n  onConnectionStatusChange?: (status: ConnectionStatus) => void\n\n  /**\n   * Callback when session generation activity changes.\n   * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).\n   * Unlike `onLoadingChange` (request-local), this reflects shared generation\n   * activity visible to all subscribers (e.g. across tabs/devices).\n   */\n  onSessionGeneratingChange?: (isGenerating: boolean) => void\n\n  /**\n   * Callback when a custom event is received from a server-side tool.\n   * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.\n   *\n   * @param eventType - The name of the custom event\n   * @param data - The event payload data\n   * @param context - Additional context including the toolCallId that emitted the event\n   */\n  onCustomEvent?: (\n    eventType: string,\n    data: unknown,\n    context: { toolCallId?: string },\n  ) => void\n\n  /**\n   * Client-side tools with execution logic\n   * When provided, tools with execute functions will be called automatically\n   */\n  tools?: TTools\n\n  /**\n   * Stream processing options (optional)\n   * Configure chunking strategy\n   */\n  streamProcessor?: {\n    /**\n     * Strategy for when to emit text updates\n     * Defaults to ImmediateStrategy (every chunk)\n     */\n    chunkStrategy?: ChunkStrategy\n  }\n} & ChatTransport\n\nexport interface ChatRequestBody {\n  messages: Array<ModelMessage>\n  data?: Record<string, any>\n}\n\n/**\n * Create a typed array of client tools with proper type inference.\n * This eliminates the need for `as const` when defining tool arrays.\n *\n * @example\n * ```ts\n * const tools = clientTools(\n *   myTool1.client(() => result1),\n *   myTool2.client(() => result2),\n * )\n *\n * // tools is now properly typed as a tuple with literal tool names\n * // This enables type narrowing when checking part.name === 'toolName'\n * ```\n */\nexport function clientTools<const T extends Array<AnyClientTool>>(\n  ...tools: T\n): T {\n  return tools\n}\n\n/**\n * Helper to create typed chat client options\n * Use this to get proper type inference for messages\n *\n * @example\n * ```ts\n * const tools = clientTools(myTool1, myTool2)\n *\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools,\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * ```\n */\nexport function createChatClientOptions<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n>(options: ChatClientOptions<TTools>): ChatClientOptions<TTools> {\n  return options\n}\n\n/**\n * Extract the message type from chat options\n *\n * @example\n * ```ts\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools: [myTool1, myTool2],\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>\n * ```\n */\nexport type InferChatMessages<T> =\n  T extends ChatClientOptions<infer TTools> ? Array<UIMessage<TTools>> : never\n"],"names":[],"mappings":"AAsaO,SAAS,eACX,OACA;AACH,SAAO;AACT;AAkBO,SAAS,wBAEd,SAA+D;AAC/D,SAAO;AACT;"}
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  AnyClientTool,\n  AudioPart,\n  ChunkStrategy,\n  ContentPart,\n  DocumentPart,\n  ImagePart,\n  InferToolInput,\n  InferToolOutput,\n  ModelMessage,\n  StreamChunk,\n  StructuredOutputPart,\n  VideoPart,\n} from '@tanstack/ai'\nimport type { ConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type { ChatDevtoolsBridgeFactory } from './devtools-noop'\n\nexport type { StructuredOutputPart } from '@tanstack/ai'\n\n/**\n * `messages` is the full UIMessage history (not a delta). `data` is the\n * merged body — `ChatClientOptions.body` plus any per-call data passed to\n * `sendMessage(...)`. `threadId` / `runId` are the AG-UI correlation ids\n * the chat client uses to track this turn — forward them to your server\n * if it needs to correlate requests.\n */\nexport interface ChatFetcherInput {\n  messages: Array<UIMessage>\n  data?: Record<string, unknown>\n  threadId: string\n  runId: string\n}\n\nexport interface ChatFetcherOptions {\n  /** Fires when `stop()` is called or the request is superseded. */\n  signal: AbortSignal\n}\n\n/**\n * Direct function that performs a chat request. Mirrors\n * `GenerationFetcher`. Returns either a `Response` (SSE body parsed by the\n * chat client) or an `AsyncIterable<StreamChunk>` (yielded directly). May\n * return the value synchronously, as a `Promise`, or as an async generator\n * (`async function*`) — the chat client awaits whichever shape is returned.\n *\n * @example\n * ```ts\n * useChat({\n *   fetcher: ({ messages }, { signal }) =>\n *     chatFn({ data: { messages }, signal }),\n * })\n * ```\n */\nexport type ChatFetcher = (\n  input: ChatFetcherInput,\n  options: ChatFetcherOptions,\n) =>\n  | Response\n  | AsyncIterable<StreamChunk>\n  | Promise<Response | AsyncIterable<StreamChunk>>\n\n/**\n * Distributive `Omit` — applies `Omit<O, K>` per branch of a union so\n * discriminated unions survive omission. Plain `Omit` collapses unions\n * into a single object shape, which would erase the `ChatTransport` XOR\n * when framework hooks omit React-managed callbacks from\n * `ChatClientOptions`.\n */\nexport type DistributedOmit<\n  TObject,\n  TKeys extends keyof any,\n> = TObject extends unknown ? Omit<TObject, TKeys> : never\n\n/**\n * Discriminated union enforcing that exactly one of `connection` or\n * `fetcher` is provided. Mirrors `GenerationTransport`.\n */\nexport type ChatTransport =\n  | { connection: ConnectionAdapter; fetcher?: never }\n  | { fetcher: ChatFetcher; connection?: never }\n\n/**\n * Tool call states - track the lifecycle of a tool call\n */\nexport type ToolCallState =\n  | 'awaiting-input' // Received start but no arguments yet\n  | 'input-streaming' // Partial arguments received\n  | 'input-complete' // All arguments received\n  | 'approval-requested' // Waiting for user approval\n  | 'approval-responded' // User has approved/denied\n  | 'complete' // Result is complete\n\n/**\n * Tool result states - track the lifecycle of a tool result\n */\nexport type ToolResultState =\n  | 'streaming' // Placeholder for future streamed output\n  | 'complete' // Result is complete\n  | 'error' // Error occurred\n\n/**\n * ChatClient state - track the lifecycle of a chat\n */\nexport type ChatClientState = 'ready' | 'submitted' | 'streaming' | 'error'\n\n/**\n * Connection lifecycle state for the subscription loop.\n */\nexport type ConnectionStatus =\n  | 'disconnected'\n  | 'connecting'\n  | 'connected'\n  | 'error'\n\n/**\n * Multimodal content input for sending messages with rich media.\n * Allows sending text, images, audio, video, and documents to the LLM.\n *\n * @example\n * ```ts\n * // Send an image with a question\n * client.sendMessage({\n *   content: [\n *     { type: 'text', content: 'What is in this image?' },\n *     { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }\n *   ],\n *   id: 'custom-message-id' // optional\n * })\n * ```\n */\nexport interface MultimodalContent {\n  /**\n   * The content of the message.\n   * Can be a simple string or an array of content parts for multimodal messages.\n   */\n  content: string | Array<ContentPart>\n  /**\n   * Optional custom ID for the message.\n   * If not provided, a unique ID will be generated.\n   */\n  id?: string\n}\n\n/**\n * Message parts - building blocks of UIMessage\n */\nexport interface TextPart {\n  type: 'text'\n  content: string\n}\n\n/**\n * Helper type that creates a tool-call part for a specific tool.\n * This is a conditional type to enable proper distribution over union types,\n * creating a discriminated union where `name` is the discriminant.\n */\ntype ToolCallPartForTool<T> = T extends AnyClientTool\n  ? {\n      type: 'tool-call'\n      id: string\n      name: T['name']\n      arguments: string // JSON string (may be incomplete)\n      /** Parsed tool input (typed from inputSchema) */\n      input?: InferToolInput<T>\n      state: ToolCallState\n      /** Approval metadata if tool requires user approval */\n      approval?: {\n        id: string // Unique approval ID\n        needsApproval: boolean // Always true if present\n        approved?: boolean // User's decision (undefined until responded)\n      }\n      /** Tool execution output (for client tools or after approval) */\n      output?: InferToolOutput<T>\n    }\n  : never\n\n/**\n * Fallback tool-call part type when tools are not typed\n */\ntype UntypedToolCallPart = {\n  type: 'tool-call'\n  id: string\n  name: string\n  arguments: string\n  input?: any\n  state: ToolCallState\n  approval?: {\n    id: string\n    needsApproval: boolean\n    approved?: boolean\n  }\n  output?: any\n}\n\n/**\n * Tool call part that creates a proper discriminated union.\n * When TTools is typed, checking `part.name === 'toolName'` will narrow\n * `part.output` to the correct type for that tool.\n *\n * The discriminant is `name`, so code like:\n * ```ts\n * if (part.name === 'recommendGuitar') {\n *   // part.output is now typed to the recommendGuitar tool's output\n * }\n * ```\n */\nexport type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> =\n  // Check if we have a concrete tools array (not 'any' or 'never')\n  [TTools] extends [never]\n    ? UntypedToolCallPart\n    : unknown extends TTools\n      ? UntypedToolCallPart\n      : TTools extends ReadonlyArray<infer Tool>\n        ? Tool extends AnyClientTool\n          ? ToolCallPartForTool<Tool>\n          : UntypedToolCallPart\n        : UntypedToolCallPart\n\nexport interface ToolResultPart {\n  type: 'tool-result'\n  toolCallId: string\n  content: string\n  state: ToolResultState\n  error?: string // Error message if state is \"error\"\n}\n\nexport interface ThinkingPart {\n  type: 'thinking'\n  content: string\n}\n\nexport type MessagePart<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> =\n  | TextPart\n  | ImagePart\n  | AudioPart\n  | VideoPart\n  | DocumentPart\n  | ToolCallPart<TTools>\n  | ToolResultPart\n  | ThinkingPart\n  | StructuredOutputPart<TData>\n\n/**\n * UIMessage - Domain-specific message format optimized for building chat UIs\n * Contains parts that can be text, tool calls, or tool results.\n *\n * `TTools` narrows the tool-call/result part types based on the registered\n * tools. `TData` is the schema-inferred type for any `structured-output` part\n * on the message — defaulted to `unknown` so untyped consumers (the core\n * stream processor, the wire converter) don't need to thread a schema generic\n * everywhere; the hook layer (`useChat({ outputSchema })`) substitutes it on\n * the public return so `m.parts.find(p => p.type === 'structured-output').data`\n * is typed without manual casts.\n */\nexport interface UIMessage<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> {\n  id: string\n  role: 'system' | 'user' | 'assistant'\n  parts: Array<MessagePart<TTools, TData>>\n  createdAt?: Date\n}\n\n/**\n * Options for `ChatClient`. Exactly one of `connection` or `fetcher` must be\n * provided — the type-level XOR is enforced via `ChatTransport`.\n */\nexport type ChatClientOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TContext = unknown,\n> = {\n  /**\n   * Initial messages to populate the chat\n   */\n  initialMessages?: Array<UIMessage<TTools>>\n\n  /**\n   * Unique identifier for this chat instance\n   * Used for managing multiple chats\n   */\n  id?: string\n\n  /**\n   * Thread ID to use for this chat session. Persists across sends within\n   * the session. If omitted, a unique thread ID is generated.\n   */\n  threadId?: string\n\n  /**\n   * Arbitrary client-controlled JSON forwarded to the server in the\n   * AG-UI `RunAgentInput.forwardedProps` field. Use this for per-session\n   * options like provider/model selection or feature flags that the\n   * server endpoint should read.\n   *\n   * Replaces the legacy `body` option. If both are provided,\n   * `forwardedProps` wins on key collision.\n   */\n  forwardedProps?: Record<string, any>\n\n  /**\n   * @deprecated Use `forwardedProps` instead. `body` continues to work\n   * unchanged — its values are merged into the AG-UI\n   * `RunAgentInput.forwardedProps` field on the wire and are also\n   * mirrored under the legacy `data` field for servers that have not\n   * migrated yet. Will be removed in a future major release.\n   */\n  body?: Record<string, any>\n\n  /**\n   * Callback when a response is received\n   */\n  onResponse?: (response?: Response) => void | Promise<void>\n\n  /**\n   * Callback when a stream chunk is received\n   */\n  onChunk?: (chunk: StreamChunk) => void\n\n  /**\n   * Callback when the response is finished\n   */\n  onFinish?: (message: UIMessage<TTools>) => void\n\n  /**\n   * Callback when an error occurs\n   */\n  onError?: (error: Error) => void\n\n  /**\n   * Callback when messages change\n   */\n  onMessagesChange?: (messages: Array<UIMessage<TTools>>) => void\n\n  /**\n   * Callback when loading state changes\n   */\n  onLoadingChange?: (isLoading: boolean) => void\n\n  /**\n   * Callback when error state changes\n   */\n  onErrorChange?: (error: Error | undefined) => void\n\n  /**\n   * Callback when chat status changes\n   */\n  onStatusChange?: (status: ChatClientState) => void\n\n  /**\n   * Callback when subscription lifecycle changes.\n   * This is independent from request lifecycle (`isLoading`, `status`).\n   */\n  onSubscriptionChange?: (isSubscribed: boolean) => void\n\n  /**\n   * Callback when connection lifecycle changes.\n   */\n  onConnectionStatusChange?: (status: ConnectionStatus) => void\n\n  /**\n   * Callback when session generation activity changes.\n   * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).\n   * Unlike `onLoadingChange` (request-local), this reflects shared generation\n   * activity visible to all subscribers (e.g. across tabs/devices).\n   */\n  onSessionGeneratingChange?: (isGenerating: boolean) => void\n\n  /**\n   * Callback when a custom event is received from a server-side tool.\n   * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.\n   *\n   * @param eventType - The name of the custom event\n   * @param data - The event payload data\n   * @param context - Additional context including the toolCallId that emitted the event\n   */\n  onCustomEvent?: (\n    eventType: string,\n    data: unknown,\n    context: { toolCallId?: string },\n  ) => void\n\n  /**\n   * Client-side tools with execution logic\n   * When provided, tools with execute functions will be called automatically\n   */\n  tools?: TTools\n\n  /**\n   * Client-local context passed to client-side tool execution.\n   */\n  context?: TContext\n\n  /**\n   * Devtools hook metadata for this client instance.\n   */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory, which keeps `@tanstack/ai-client/devtools` (the heavy\n   * bridge implementation) out of the main entry's bundle. Frameworks\n   * that need live devtools should pass the real factory from\n   * `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: ChatDevtoolsBridgeFactory\n\n  /**\n   * Stream processing options (optional)\n   * Configure chunking strategy\n   */\n  streamProcessor?: {\n    /**\n     * Strategy for when to emit text updates\n     * Defaults to ImmediateStrategy (every chunk)\n     */\n    chunkStrategy?: ChunkStrategy\n  }\n} & ChatTransport\n\nexport interface ChatRequestBody {\n  messages: Array<ModelMessage>\n  data?: Record<string, any>\n}\n\n/**\n * Create a typed array of client tools with proper type inference.\n * This eliminates the need for `as const` when defining tool arrays.\n *\n * @example\n * ```ts\n * const tools = clientTools(\n *   myTool1.client(() => result1),\n *   myTool2.client(() => result2),\n * )\n *\n * // tools is now properly typed as a tuple with literal tool names\n * // This enables type narrowing when checking part.name === 'toolName'\n * ```\n */\nexport function clientTools<const T extends Array<AnyClientTool>>(\n  ...tools: T\n): T {\n  return tools\n}\n\n/**\n * Helper to create typed chat client options\n * Use this to get proper type inference for messages\n *\n * @example\n * ```ts\n * const tools = clientTools(myTool1, myTool2)\n *\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools,\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * ```\n */\nexport function createChatClientOptions<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = unknown,\n>(\n  options: ChatClientOptions<TTools, TContext>,\n): ChatClientOptions<TTools, TContext> {\n  return options\n}\n\n/**\n * Extract the message type from chat options\n *\n * @example\n * ```ts\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools: [myTool1, myTool2],\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>\n * ```\n */\nexport type InferChatMessages<T> =\n  T extends ChatClientOptions<infer TTools, any>\n    ? Array<UIMessage<TTools>>\n    : never\n"],"names":[],"mappings":"AA4bO,SAAS,eACX,OACA;AACH,SAAO;AACT;AAkBO,SAAS,wBAId,SACqC;AACrC,SAAO;AACT;"}