@tanstack/ai 0.6.3 → 0.8.1

package/dist/esm/middlewares/content-guard.js

@@ -0,0 +1,155 @@
+function applyRules(text, rules) {
+  let result = text;
+  for (const rule of rules) {
+    if ("pattern" in rule) {
+      result = result.replace(rule.pattern, rule.replacement);
+    } else {
+      result = rule.fn(result);
+    }
+  }
+  return result;
+}
+function contentGuardMiddleware(options) {
+  const {
+    rules,
+    strategy = "buffered",
+    bufferSize = 50,
+    blockOnMatch = false,
+    onFiltered
+  } = options;
+  if (strategy === "delta") {
+    return createDeltaStrategy(rules, blockOnMatch, onFiltered);
+  }
+  return createBufferedStrategy(rules, bufferSize, blockOnMatch, onFiltered);
+}
+function createDeltaStrategy(rules, blockOnMatch, onFiltered) {
+  return {
+    name: "content-guard",
+    onChunk(_ctx, chunk) {
+      if (chunk.type !== "TEXT_MESSAGE_CONTENT") return;
+      const original = chunk.delta;
+      const filtered = applyRules(original, rules);
+      if (filtered === original) return;
+      if (onFiltered) {
+        onFiltered({
+          messageId: chunk.messageId,
+          original,
+          filtered,
+          strategy: "delta"
+        });
+      }
+      if (blockOnMatch) return null;
+      return {
+        ...chunk,
+        delta: filtered,
+        content: void 0
+      };
+    }
+  };
+}
+function createBufferedStrategy(rules, bufferSize, blockOnMatch, onFiltered) {
+  let rawAccumulated = "";
+  let emittedFilteredLength = 0;
+  let lastMessageId = "";
+  function resetState() {
+    rawAccumulated = "";
+    emittedFilteredLength = 0;
+    lastMessageId = "";
+  }
+  function flushBuffer() {
+    if (rawAccumulated.length === 0) return null;
+    const filtered = applyRules(rawAccumulated, rules);
+    if (blockOnMatch && filtered !== rawAccumulated) {
+      if (onFiltered) {
+        onFiltered({
+          messageId: lastMessageId,
+          original: rawAccumulated,
+          filtered,
+          strategy: "buffered"
+        });
+      }
+      resetState();
+      return null;
+    }
+    const remaining = filtered.slice(emittedFilteredLength);
+    if (remaining.length > 0) {
+      if (filtered !== rawAccumulated && onFiltered) {
+        onFiltered({
+          messageId: lastMessageId,
+          original: rawAccumulated,
+          filtered,
+          strategy: "buffered"
+        });
+      }
+      const flushed = {
+        type: "TEXT_MESSAGE_CONTENT",
+        messageId: lastMessageId,
+        delta: remaining,
+        content: filtered,
+        timestamp: Date.now()
+      };
+      resetState();
+      return flushed;
+    }
+    resetState();
+    return null;
+  }
+  return {
+    name: "content-guard",
+    onStart() {
+      resetState();
+    },
+    onChunk(_ctx, chunk) {
+      if (chunk.type === "TEXT_MESSAGE_END" || chunk.type === "RUN_FINISHED") {
+        const flushed = flushBuffer();
+        if (flushed) return [flushed, chunk];
+        return;
+      }
+      if (chunk.type !== "TEXT_MESSAGE_CONTENT") return;
+      const pending = [];
+      if (lastMessageId && chunk.messageId !== lastMessageId) {
+        const flushed = flushBuffer();
+        if (flushed) pending.push(flushed);
+      }
+      rawAccumulated += chunk.delta;
+      lastMessageId = chunk.messageId;
+      const filtered = applyRules(rawAccumulated, rules);
+      const safeFilteredEnd = Math.max(0, filtered.length - bufferSize);
+      if (safeFilteredEnd <= emittedFilteredLength) {
+        return pending.length > 0 ? pending : null;
+      }
+      if (blockOnMatch && filtered !== rawAccumulated) {
+        if (onFiltered) {
+          onFiltered({
+            messageId: chunk.messageId,
+            original: rawAccumulated,
+            filtered,
+            strategy: "buffered"
+          });
+        }
+        return pending.length > 0 ? pending : null;
+      }
+      const newDelta = filtered.slice(emittedFilteredLength, safeFilteredEnd);
+      if (filtered !== rawAccumulated && onFiltered) {
+        onFiltered({
+          messageId: chunk.messageId,
+          original: rawAccumulated,
+          filtered,
+          strategy: "buffered"
+        });
+      }
+      emittedFilteredLength = safeFilteredEnd;
+      const emitChunk = {
+        ...chunk,
+        delta: newDelta,
+        content: filtered.slice(0, safeFilteredEnd)
+      };
+      pending.push(emitChunk);
+      return pending.length === 1 ? pending[0] : pending;
+    }
+  };
+}
+export {
+  contentGuardMiddleware
+};
+//# sourceMappingURL=content-guard.js.map

package/dist/esm/middlewares/content-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-guard.js","sources":["../../../src/middlewares/content-guard.ts"],"sourcesContent":["import type {\n  ChatMiddleware,\n  ChatMiddlewareContext,\n} from '../activities/chat/middleware/types'\nimport type { StreamChunk } from '../types'\n\n/**\n * A content guard rule — either a regex pattern with replacement, or a transform function.\n */\nexport type ContentGuardRule =\n  | { pattern: RegExp; replacement: string }\n  | { fn: (text: string) => string }\n\n/**\n * Information passed to the onFiltered callback.\n */\nexport interface ContentFilteredInfo {\n  /** The message ID being filtered */\n  messageId: string\n  /** The original text before filtering */\n  original: string\n  /** The filtered text after rules applied */\n  filtered: string\n  /** Which strategy was used */\n  strategy: 'delta' | 'buffered'\n}\n\n/**\n * Options for the content guard middleware.\n */\nexport interface ContentGuardMiddlewareOptions {\n  /**\n   * Rules to apply to text content. Each rule is either a regex pattern\n   * with a replacement string, or a custom transform function.\n   * Rules are applied in order. Each rule receives the output of the previous.\n   */\n  rules: Array<ContentGuardRule>\n\n  /**\n   * Matching strategy:\n   * - 'delta': Apply rules to each delta as it arrives. Fast, real-time,\n   *   but patterns spanning chunk boundaries may be missed.\n   * - 'buffered': Accumulate content and apply rules to settled portions,\n   *   holding back a look-behind buffer to catch cross-boundary patterns.\n   *\n   * @default 'buffered'\n   */\n  strategy?: 'delta' | 'buffered'\n\n  /**\n   * Number of characters to hold back before emitting (buffered strategy only).\n   * Should be at least as long as the longest pattern you expect to match.\n   * Buffer is flushed when the stream ends.\n   *\n   * @default 50\n   */\n  bufferSize?: number\n\n  /**\n   * If true, drop the entire chunk when any rule changes the content.\n   * @default false\n   */\n  blockOnMatch?: boolean\n\n  /**\n   * Callback when content is filtered by any rule.\n   */\n  onFiltered?: (info: ContentFilteredInfo) => void\n}\n\n/**\n * Apply all rules to a string, returning the transformed result.\n */\nfunction applyRules(text: string, rules: Array<ContentGuardRule>): string {\n  let result = text\n  for (const rule of rules) {\n    if ('pattern' in rule) {\n      result = result.replace(rule.pattern, rule.replacement)\n    } else {\n      result = rule.fn(result)\n    }\n  }\n  return result\n}\n\n/**\n * Creates a middleware that filters or transforms streamed text content.\n *\n * @example\n * ```ts\n * import { contentGuardMiddleware } from '@tanstack/ai/middlewares'\n *\n * const guard = contentGuardMiddleware({\n *   rules: [\n *     { pattern: /\\b\\d{3}-\\d{2}-\\d{4}\\b/g, replacement: '[SSN REDACTED]' },\n *   ],\n *   strategy: 'buffered',\n * })\n * ```\n */\nexport function contentGuardMiddleware(\n  options: ContentGuardMiddlewareOptions,\n): ChatMiddleware {\n  const {\n    rules,\n    strategy = 'buffered',\n    bufferSize = 50,\n    blockOnMatch = false,\n    onFiltered,\n  } = options\n\n  if (strategy === 'delta') {\n    return createDeltaStrategy(rules, blockOnMatch, onFiltered)\n  }\n  return createBufferedStrategy(rules, bufferSize, blockOnMatch, onFiltered)\n}\n\nfunction createDeltaStrategy(\n  rules: Array<ContentGuardRule>,\n  blockOnMatch: boolean,\n  onFiltered?: (info: ContentFilteredInfo) => void,\n): ChatMiddleware {\n  return {\n    name: 'content-guard',\n\n    onChunk(_ctx: ChatMiddlewareContext, chunk: StreamChunk) {\n      if (chunk.type !== 'TEXT_MESSAGE_CONTENT') return\n\n      const original = chunk.delta\n      const filtered = applyRules(original, rules)\n\n      if (filtered === original) return // unchanged, pass through\n\n      if (onFiltered) {\n        onFiltered({\n          messageId: chunk.messageId,\n          original,\n          filtered,\n          strategy: 'delta',\n        })\n      }\n\n      if (blockOnMatch) return null // drop chunk\n\n      return {\n        ...chunk,\n        delta: filtered,\n        content: undefined,\n      } as StreamChunk\n    },\n  }\n}\n\nfunction createBufferedStrategy(\n  rules: Array<ContentGuardRule>,\n  bufferSize: number,\n  blockOnMatch: boolean,\n  onFiltered?: (info: ContentFilteredInfo) => void,\n): ChatMiddleware {\n  let rawAccumulated = ''\n  let emittedFilteredLength = 0\n  let lastMessageId = ''\n\n  function resetState() {\n    rawAccumulated = ''\n    emittedFilteredLength = 0\n    lastMessageId = ''\n  }\n\n  function flushBuffer(): StreamChunk | null {\n    if (rawAccumulated.length === 0) return null\n\n    const filtered = applyRules(rawAccumulated, rules)\n\n    if (blockOnMatch && filtered !== rawAccumulated) {\n      if (onFiltered) {\n        onFiltered({\n          messageId: lastMessageId,\n          original: rawAccumulated,\n          filtered,\n          strategy: 'buffered',\n        })\n      }\n      resetState()\n      return null\n    }\n\n    const remaining = filtered.slice(emittedFilteredLength)\n    if (remaining.length > 0) {\n      if (filtered !== rawAccumulated && onFiltered) {\n        onFiltered({\n          messageId: lastMessageId,\n          original: rawAccumulated,\n          filtered,\n          strategy: 'buffered',\n        })\n      }\n\n      const flushed = {\n        type: 'TEXT_MESSAGE_CONTENT',\n        messageId: lastMessageId,\n        delta: remaining,\n        content: filtered,\n        timestamp: Date.now(),\n      } as StreamChunk\n\n      resetState()\n      return flushed\n    }\n\n    resetState()\n    return null\n  }\n\n  return {\n    name: 'content-guard',\n\n    onStart() {\n      resetState()\n    },\n\n    onChunk(_ctx: ChatMiddlewareContext, chunk: StreamChunk) {\n      // Flush buffer on stream end events\n      if (chunk.type === 'TEXT_MESSAGE_END' || chunk.type === 'RUN_FINISHED') {\n        const flushed = flushBuffer()\n        if (flushed) return [flushed, chunk]\n        return // pass through end event\n      }\n\n      if (chunk.type !== 'TEXT_MESSAGE_CONTENT') return // pass through\n\n      // Flush buffer on message boundary change\n      const pending: Array<StreamChunk> = []\n      if (lastMessageId && chunk.messageId !== lastMessageId) {\n        const flushed = flushBuffer()\n        if (flushed) pending.push(flushed)\n      }\n\n      rawAccumulated += chunk.delta\n      lastMessageId = chunk.messageId\n\n      // Apply rules to full accumulated text, buffer in filtered space\n      const filtered = applyRules(rawAccumulated, rules)\n      const safeFilteredEnd = Math.max(0, filtered.length - bufferSize)\n\n      if (safeFilteredEnd <= emittedFilteredLength) {\n        return pending.length > 0 ? pending : null\n      }\n\n      if (blockOnMatch && filtered !== rawAccumulated) {\n        if (onFiltered) {\n          onFiltered({\n            messageId: chunk.messageId,\n            original: rawAccumulated,\n            filtered,\n            strategy: 'buffered',\n          })\n        }\n        return pending.length > 0 ? pending : null\n      }\n\n      const newDelta = filtered.slice(emittedFilteredLength, safeFilteredEnd)\n\n      if (filtered !== rawAccumulated && onFiltered) {\n        onFiltered({\n          messageId: chunk.messageId,\n          original: rawAccumulated,\n          filtered,\n          strategy: 'buffered',\n        })\n      }\n\n      emittedFilteredLength = safeFilteredEnd\n\n      const emitChunk = {\n        ...chunk,\n        delta: newDelta,\n        content: filtered.slice(0, safeFilteredEnd),\n      } as StreamChunk\n\n      pending.push(emitChunk)\n      return pending.length === 1 ? pending[0]! : pending\n    },\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/middlewares/index.d.ts

@@ -0,0 +1,2 @@
+export { toolCacheMiddleware, type ToolCacheMiddlewareOptions, type ToolCacheStorage, type ToolCacheEntry, } from './tool-cache.js';
+export { contentGuardMiddleware, type ContentGuardMiddlewareOptions, type ContentGuardRule, type ContentFilteredInfo, } from './content-guard.js';

package/dist/esm/middlewares/index.js

@@ -0,0 +1,7 @@
+import { contentGuardMiddleware } from "./content-guard.js";
+import { toolCacheMiddleware } from "../activities/chat/middleware/tool-cache-middleware.js";
+export {
+  contentGuardMiddleware,
+  toolCacheMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/middlewares/index.js.map

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

package/dist/esm/middlewares/tool-cache.d.ts

@@ -0,0 +1 @@
+export { toolCacheMiddleware, type ToolCacheMiddlewareOptions, type ToolCacheStorage, type ToolCacheEntry, } from '../activities/chat/middleware/tool-cache-middleware.js';

package/dist/esm/realtime/index.d.ts

@@ -0,0 +1,30 @@
+import { RealtimeToken, RealtimeTokenOptions } from './types.js';
+export * from './types.js';
+/**
+ * Generate a realtime token using the provided adapter.
+ *
+ * This function is used on the server to generate ephemeral tokens
+ * that clients can use to establish realtime connections.
+ *
+ * @param options - Token generation options including the adapter
+ * @returns Promise resolving to a RealtimeToken
+ *
+ * @example
+ * ```typescript
+ * import { realtimeToken } from '@tanstack/ai'
+ * import { openaiRealtimeToken } from '@tanstack/ai-openai'
+ *
+ * // Server function (TanStack Start example)
+ * export const getRealtimeToken = createServerFn()
+ *   .handler(async () => {
+ *     return realtimeToken({
+ *       adapter: openaiRealtimeToken({
+ *         model: 'gpt-4o-realtime-preview',
+ *         voice: 'alloy',
+ *         instructions: 'You are a helpful assistant...',
+ *       }),
+ *     })
+ *   })
+ * ```
+ */
+export declare function realtimeToken(options: RealtimeTokenOptions): Promise<RealtimeToken>;

package/dist/esm/realtime/index.js

@@ -0,0 +1,8 @@
+async function realtimeToken(options) {
+  const { adapter } = options;
+  return adapter.generateToken();
+}
+export {
+  realtimeToken
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/realtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/realtime/index.ts"],"sourcesContent":["import type { RealtimeToken, RealtimeTokenOptions } from './types'\n\n// Re-export all types\nexport * from './types'\n\n/**\n * Generate a realtime token using the provided adapter.\n *\n * This function is used on the server to generate ephemeral tokens\n * that clients can use to establish realtime connections.\n *\n * @param options - Token generation options including the adapter\n * @returns Promise resolving to a RealtimeToken\n *\n * @example\n * ```typescript\n * import { realtimeToken } from '@tanstack/ai'\n * import { openaiRealtimeToken } from '@tanstack/ai-openai'\n *\n * // Server function (TanStack Start example)\n * export const getRealtimeToken = createServerFn()\n *   .handler(async () => {\n *     return realtimeToken({\n *       adapter: openaiRealtimeToken({\n *         model: 'gpt-4o-realtime-preview',\n *         voice: 'alloy',\n *         instructions: 'You are a helpful assistant...',\n *       }),\n *     })\n *   })\n * ```\n */\nexport async function realtimeToken(\n  options: RealtimeTokenOptions,\n): Promise<RealtimeToken> {\n  const { adapter } = options\n  return adapter.generateToken()\n}\n"],"names":[],"mappings":"AAgCA,eAAsB,cACpB,SACwB;AACxB,QAAM,EAAE,YAAY;AACpB,SAAO,QAAQ,cAAA;AACjB;"}

package/dist/esm/realtime/types.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Voice activity detection configuration
+ */
+export interface VADConfig {
+    /** Sensitivity threshold (0.0-1.0) */
+    threshold?: number;
+    /** Audio to include before speech detection (ms) */
+    prefixPaddingMs?: number;
+    /** Silence duration to end turn (ms) */
+    silenceDurationMs?: number;
+}
+/**
+ * Serializable tool descriptor for realtime session configuration.
+ * Contains only the metadata needed by providers, not Zod schemas or execute functions.
+ */
+export interface RealtimeToolConfig {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, any>;
+}
+/**
+ * Configuration for a realtime session
+ */
+export interface RealtimeSessionConfig {
+    /** Model to use for the session */
+    model?: string;
+    /** Voice to use for audio output */
+    voice?: string;
+    /** System instructions for the assistant */
+    instructions?: string;
+    /** Tools available in the session */
+    tools?: Array<RealtimeToolConfig>;
+    /** VAD mode */
+    vadMode?: 'server' | 'semantic' | 'manual';
+    /** VAD configuration */
+    vadConfig?: VADConfig;
+    /** Output modalities for responses (e.g., ['audio', 'text'], ['text']) */
+    outputModalities?: Array<'audio' | 'text'>;
+    /** Temperature for generation (provider-specific range, e.g., 0.6-1.2 for OpenAI) */
+    temperature?: number;
+    /** Maximum number of tokens in a response */
+    maxOutputTokens?: number | 'inf';
+    /** Eagerness level for semantic VAD ('low', 'medium', 'high') */
+    semanticEagerness?: 'low' | 'medium' | 'high';
+    /** Provider-specific options */
+    providerOptions?: Record<string, any>;
+}
+/**
+ * Token returned by the server for client authentication
+ */
+export interface RealtimeToken {
+    /** Provider identifier */
+    provider: string;
+    /** The ephemeral token value */
+    token: string;
+    /** Token expiration timestamp (ms since epoch) */
+    expiresAt: number;
+    /** Session configuration embedded in the token */
+    config: RealtimeSessionConfig;
+}
+/**
+ * Adapter interface for generating provider-specific tokens
+ */
+export interface RealtimeTokenAdapter {
+    /** Provider identifier */
+    provider: string;
+    /** Generate an ephemeral token for client use */
+    generateToken: () => Promise<RealtimeToken>;
+}
+/**
+ * Options for the realtimeToken function
+ */
+export interface RealtimeTokenOptions {
+    /** The token adapter to use */
+    adapter: RealtimeTokenAdapter;
+}
+/**
+ * Text content part in a realtime message
+ */
+export interface RealtimeTextPart {
+    type: 'text';
+    content: string;
+}
+/**
+ * Audio content part in a realtime message
+ */
+export interface RealtimeAudioPart {
+    type: 'audio';
+    /** Transcription of the audio */
+    transcript: string;
+    /** Raw audio data (optional, if stored) */
+    audioData?: ArrayBuffer;
+    /** Duration of the audio in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Tool call part in a realtime message
+ */
+export interface RealtimeToolCallPart {
+    type: 'tool-call';
+    id: string;
+    name: string;
+    arguments: string;
+    input?: unknown;
+    output?: unknown;
+}
+/**
+ * Tool result part in a realtime message
+ */
+export interface RealtimeToolResultPart {
+    type: 'tool-result';
+    toolCallId: string;
+    content: string;
+}
+/**
+ * Image content part in a realtime message
+ */
+export interface RealtimeImagePart {
+    type: 'image';
+    /** Base64-encoded image data or a URL */
+    data: string;
+    /** MIME type of the image (e.g., 'image/png', 'image/jpeg') */
+    mimeType: string;
+}
+/**
+ * Union of all realtime message parts
+ */
+export type RealtimeMessagePart = RealtimeTextPart | RealtimeAudioPart | RealtimeToolCallPart | RealtimeToolResultPart | RealtimeImagePart;
+/**
+ * A message in a realtime conversation
+ */
+export interface RealtimeMessage {
+    /** Unique message identifier */
+    id: string;
+    /** Message role */
+    role: 'user' | 'assistant';
+    /** Timestamp when the message was created */
+    timestamp: number;
+    /** Content parts of the message */
+    parts: Array<RealtimeMessagePart>;
+    /** Whether this message was interrupted */
+    interrupted?: boolean;
+    /** Reference to audio buffer if stored */
+    audioId?: string;
+    /** Duration of the audio in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Connection status of the realtime client
+ */
+export type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'error';
+/**
+ * Current mode of the realtime session
+ */
+export type RealtimeMode = 'idle' | 'listening' | 'thinking' | 'speaking';
+/**
+ * Interface for accessing audio visualization data
+ */
+export interface AudioVisualization {
+    /** Input volume level (0-1 normalized) */
+    readonly inputLevel: number;
+    /** Output volume level (0-1 normalized) */
+    readonly outputLevel: number;
+    /** Get frequency data for input audio visualization */
+    getInputFrequencyData: () => Uint8Array;
+    /** Get frequency data for output audio visualization */
+    getOutputFrequencyData: () => Uint8Array;
+    /** Get time domain data for input waveform */
+    getInputTimeDomainData: () => Uint8Array;
+    /** Get time domain data for output waveform */
+    getOutputTimeDomainData: () => Uint8Array;
+    /** Input sample rate */
+    readonly inputSampleRate: number;
+    /** Output sample rate */
+    readonly outputSampleRate: number;
+    /** Subscribe to raw input audio samples */
+    onInputAudio?: (callback: (samples: Float32Array, sampleRate: number) => void) => () => void;
+    /** Subscribe to raw output audio samples */
+    onOutputAudio?: (callback: (samples: Float32Array, sampleRate: number) => void) => () => void;
+}
+/**
+ * Events emitted by the realtime connection
+ */
+export type RealtimeEvent = 'status_change' | 'mode_change' | 'transcript' | 'audio_chunk' | 'tool_call' | 'message_complete' | 'interrupted' | 'error';
+/**
+ * Event payloads for realtime events
+ */
+export interface RealtimeEventPayloads {
+    status_change: {
+        status: RealtimeStatus;
+    };
+    mode_change: {
+        mode: RealtimeMode;
+    };
+    transcript: {
+        role: 'user' | 'assistant';
+        transcript: string;
+        isFinal: boolean;
+    };
+    audio_chunk: {
+        data: ArrayBuffer;
+        sampleRate: number;
+    };
+    tool_call: {
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    };
+    message_complete: {
+        message: RealtimeMessage;
+    };
+    interrupted: {
+        messageId?: string;
+    };
+    error: {
+        error: Error;
+    };
+}
+/**
+ * Handler type for realtime events
+ */
+export type RealtimeEventHandler<TEvent extends RealtimeEvent> = (payload: RealtimeEventPayloads[TEvent]) => void;
+/**
+ * Error codes for realtime errors
+ */
+export type RealtimeErrorCode = 'TOKEN_EXPIRED' | 'CONNECTION_FAILED' | 'PERMISSION_DENIED' | 'PROVIDER_ERROR' | 'UNKNOWN';
+/**
+ * Extended error with realtime-specific information
+ */
+export interface RealtimeError extends Error {
+    code: RealtimeErrorCode;
+    provider?: string;
+    details?: unknown;
+}

package/dist/esm/types.d.ts

@@ -605,7 +605,7 @@ export interface TextOptions<TProviderOptionsSuperset extends Record<string, any
  * Based on the AG-UI specification for agent-user interaction.
  * @see https://docs.ag-ui.com/concepts/events
  */
-export type AGUIEventType = 'RUN_STARTED' | 'RUN_FINISHED' | 'RUN_ERROR' | 'TEXT_MESSAGE_START' | 'TEXT_MESSAGE_CONTENT' | 'TEXT_MESSAGE_END' | 'TOOL_CALL_START' | 'TOOL_CALL_ARGS' | 'TOOL_CALL_END' | 'STEP_STARTED' | 'STEP_FINISHED' | 'STATE_SNAPSHOT' | 'STATE_DELTA' | 'CUSTOM';
+export type AGUIEventType = 'RUN_STARTED' | 'RUN_FINISHED' | 'RUN_ERROR' | 'TEXT_MESSAGE_START' | 'TEXT_MESSAGE_CONTENT' | 'TEXT_MESSAGE_END' | 'TOOL_CALL_START' | 'TOOL_CALL_ARGS' | 'TOOL_CALL_END' | 'STEP_STARTED' | 'STEP_FINISHED' | 'MESSAGES_SNAPSHOT' | 'STATE_SNAPSHOT' | 'STATE_DELTA' | 'CUSTOM';
 /**
  * Stream chunk/event types (AG-UI protocol).
  */
@@ -669,8 +669,8 @@ export interface TextMessageStartEvent extends BaseAGUIEvent {
     type: 'TEXT_MESSAGE_START';
     /** Unique identifier for this message */
     messageId: string;
-    /** Role is always assistant for generated messages */
-    role: 'assistant';
+    /** Role of the message sender */
+    role: 'user' | 'assistant' | 'system' | 'tool';
 }
 /**
  * Emitted when text content is generated (streaming tokens).
@@ -701,6 +701,8 @@ export interface ToolCallStartEvent extends BaseAGUIEvent {
     toolCallId: string;
     /** Name of the tool being called */
     toolName: string;
+    /** ID of the parent message that initiated this tool call */
+    parentMessageId?: string;
     /** Index for parallel tool calls */
     index?: number;
 }
@@ -752,6 +754,18 @@ export interface StepFinishedEvent extends BaseAGUIEvent {
     /** Full accumulated thinking content (optional, for debugging) */
     content?: string;
 }
+/**
+ * Emitted to provide a snapshot of all messages in a conversation.
+ *
+ * Unlike StateSnapshot (which carries arbitrary application state),
+ * MessagesSnapshot specifically delivers the conversation transcript.
+ * This is a first-class AG-UI event type.
+ */
+export interface MessagesSnapshotEvent extends BaseAGUIEvent {
+    type: 'MESSAGES_SNAPSHOT';
+    /** Complete array of messages in the conversation */
+    messages: Array<UIMessage>;
+}
 /**
  * Emitted to provide a full state snapshot.
  */
@@ -781,7 +795,7 @@ export interface CustomEvent extends BaseAGUIEvent {
 /**
  * Union of all AG-UI events.
  */
-export type AGUIEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | StepStartedEvent | StepFinishedEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent;
+export type AGUIEvent = RunStartedEvent | RunFinishedEvent | RunErrorEvent | TextMessageStartEvent | TextMessageContentEvent | TextMessageEndEvent | ToolCallStartEvent | ToolCallArgsEvent | ToolCallEndEvent | StepStartedEvent | StepFinishedEvent | MessagesSnapshotEvent | StateSnapshotEvent | StateDeltaEvent | CustomEvent;
 /**
  * Chunk returned by the SDK during streaming chat completions.
  * Uses the AG-UI protocol event format.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.6.3",
+  "version": "0.8.1",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -21,9 +21,9 @@
       "types": "./dist/esm/activities/index.d.ts",
       "import": "./dist/esm/activities/index.js"
     },
-    "./event-client": {
-      "types": "./dist/esm/event-client.d.ts",
-      "import": "./dist/esm/event-client.js"
+    "./middlewares": {
+      "types": "./dist/esm/middlewares/index.d.ts",
+      "import": "./dist/esm/middlewares/index.js"
     }
   },
   "sideEffects": false,
@@ -43,8 +43,8 @@
     "embeddings"
   ],
   "dependencies": {
-    "@tanstack/devtools-event-client": "^0.4.0",
-    "partial-json": "^0.1.7"
+    "partial-json": "^0.1.7",
+    "@tanstack/ai-event-client": "0.1.1"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",