@tanstack/ai 0.39.1 → 0.41.0

package/src/activities/chat/index.ts

@@ -45,6 +45,7 @@ import type {
 import type {
   AgentLoopStrategy,
   AnyTool,
+  ChatStream,
   ConstrainedModelMessage,
   CustomEvent,
   InferSchemaType,
@@ -69,7 +70,7 @@ import type {
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
-  SandboxFileEvent,
+  SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
 import type { CheckCoverage } from './middleware/builder'
@@ -404,7 +405,7 @@ export type TextActivityResult<
     : Promise<InferSchemaType<TSchema>>
   : [TStream] extends [false]
     ? Promise<string>
-    : AsyncIterable<StreamChunk>
+    : ChatStream
 
 // ===========================
 // ChatEngine Implementation
@@ -712,11 +713,30 @@ class TextEngine<
     // a `sandbox.file` custom chunk to be drained into the public stream.
     provideSandboxRuntime(this.middlewareCtx, {
       logger: this.logger,
-      emit: (event: SandboxFileEvent) => {
-        this.logger.sandbox(`file ${event.type} ${event.path}`, { event })
-        void this.middlewareRunner.runSandboxFile(this.middlewareCtx, event)
+      emit: (event: SandboxFileHookEvent) => {
+        this.logger.sandbox(`file ${event.type} ${event.path}`, {
+          event: {
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+          },
+        })
+        void this.middlewareRunner
+          .runSandboxFile(this.middlewareCtx, event)
+          .catch((err: unknown) => {
+            this.logger.errors('sandbox file hook failed', { error: err })
+          })
+        this.sandboxFileQueue.push(
+          this.createCustomEventChunk('sandbox.file', {
+            type: event.type,
+            path: event.path,
+            timestamp: event.timestamp,
+          }),
+        )
+      },
+      emitFileDiff: (value: { path: string; diff: string }) => {
         this.sandboxFileQueue.push(
-          this.createCustomEventChunk('sandbox.file', { ...event }),
+          this.createCustomEventChunk('sandbox.file.diff', value),
         )
       },
     })

package/src/activities/chat/messages.ts

@@ -444,12 +444,21 @@ export function modelMessageToUIMessage(
   // Handle tool calls
   if (modelMessage.toolCalls && modelMessage.toolCalls.length > 0) {
     for (const toolCall of modelMessage.toolCalls) {
+      // Model-message arguments are complete, so surface the parsed input.
+      // A malformed arguments string just leaves `input` undefined.
+      let input: unknown
+      try {
+        input = JSON.parse(toolCall.function.arguments)
+      } catch {
+        input = undefined
+      }
       parts.push({
         type: 'tool-call',
         id: toolCall.id,
         name: toolCall.function.name,
         arguments: toolCall.function.arguments,
         state: 'input-complete', // Model messages have complete arguments
+        ...(input !== undefined && { input }),
         ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
       })
     }

package/src/activities/chat/middleware/compose.ts

@@ -11,7 +11,7 @@ import type {
   ErrorInfo,
   FinishInfo,
   IterationInfo,
-  SandboxFileEvent,
+  SandboxFileHookEvent,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   ToolPhaseCompleteInfo,
@@ -352,7 +352,7 @@ export class MiddlewareRunner<TContext = unknown> {
    */
   async runSandboxFile(
     ctx: ChatMiddlewareContext<TContext>,
-    event: SandboxFileEvent,
+    event: SandboxFileHookEvent,
   ): Promise<void> {
     const typed = (
       {

package/src/activities/chat/middleware/index.ts

@@ -14,6 +14,7 @@ export type {
   AbortInfo,
   ErrorInfo,
   SandboxFileEvent,
+  SandboxFileHookEvent,
   ChatSandboxHooks,
 } from './types'
 

package/src/activities/chat/middleware/sandbox-runtime.ts

@@ -7,10 +7,12 @@
  */
 import { createCapability } from './capabilities'
 import type { InternalLogger } from '../../../logger/internal-logger'
-import type { SandboxFileEvent } from './types'
+import type { SandboxFileHookEvent } from './types'
 
 export interface SandboxRuntime {
-  emit: (event: SandboxFileEvent) => void
+  emit: (event: SandboxFileHookEvent) => void
+  /** Emit an opt-in per-file `sandbox.file.diff` CUSTOM chunk. */
+  emitFileDiff: (value: { path: string; diff: string }) => void
   logger: InternalLogger
 }
 

package/src/activities/chat/middleware/types.ts

@@ -21,6 +21,19 @@ export interface SandboxFileEvent {
   timestamp: number
 }
 
+/** The file event a sandbox hook receives: the serializable {@link SandboxFileEvent}
+ *  plus lazy, git-backed content accessors. Accessors compute on call, so a hook
+ *  that only reads `path`/`type` pays nothing. Never present on the serialized
+ *  `sandbox.file` CUSTOM chunk. */
+export interface SandboxFileHookEvent extends SandboxFileEvent {
+  /** Content at the session baseline (`''` for a new file or non-git workspace). */
+  before: () => Promise<string>
+  /** Current content (`''` when the event is a delete). */
+  after: () => Promise<string>
+  /** Unified patch vs the session baseline (synthesized add-patch when non-git). */
+  diff: () => Promise<string>
+}
+
 /**
  * Sandbox file-event hooks a chat middleware can declare. Fire server-side for
  * every file create/change/delete observed in the sandbox during the run.
@@ -28,19 +41,19 @@ export interface SandboxFileEvent {
 export interface ChatSandboxHooks<TContext = unknown> {
   onFile?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileCreate?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileChange?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
   onFileDelete?: (
     ctx: ChatMiddlewareContext<TContext>,
-    e: SandboxFileEvent,
+    e: SandboxFileHookEvent,
   ) => void | Promise<void>
 }
 

package/src/activities/chat/stream/message-updaters.ts

@@ -58,6 +58,8 @@ export function updateToolCallPart(
     name: string
     arguments: string
     state: ToolCallState
+    /** Parsed input — set when the arguments are complete. */
+    input?: unknown
     metadata?: Record<string, unknown>
   },
 ): Array<UIMessage> {
@@ -76,6 +78,9 @@ export function updateToolCallPart(
     // Gemini's thoughtSignature on TOOL_CALL_START) we must not lose it on
     // subsequent updates that don't re-supply it.
     const metadata = toolCall.metadata ?? existing?.metadata
+    // Same for the parsed input: it's supplied once at completion, so
+    // subsequent arg-less updates (approval, etc.) must not drop it.
+    const input = toolCall.input ?? existing?.input
 
     const toolCallPart: ToolCallPart = {
       type: 'tool-call',
@@ -83,9 +88,10 @@ export function updateToolCallPart(
       name: toolCall.name,
       arguments: toolCall.arguments,
       state: toolCall.state,
-      // Carry forward approval and output from the existing part
+      // Carry forward approval, output and parsed input from the existing part
       ...(existing?.approval && { approval: { ...existing.approval } }),
       ...(existing?.output !== undefined && { output: existing.output }),
+      ...(input !== undefined && { input }),
       ...(metadata !== undefined && { metadata }),
     }
 

package/src/activities/chat/stream/processor.ts

@@ -1298,15 +1298,35 @@ export class StreamProcessor {
       // received, back-fill the arguments string so the UIMessage ToolCallPart
       // carries the correct value (defensive against adapters that skip ARGS).
       if (chunk.input !== undefined && !existingToolCall.arguments) {
-        existingToolCall.arguments = JSON.stringify(chunk.input)
+        try {
+          existingToolCall.arguments = JSON.stringify(chunk.input)
+        } catch {
+          // circular refs, BigInt, etc. — leave arguments empty rather than
+          // aborting stream processing
+        }
       }
 
       const index = msgState.toolCallOrder.indexOf(chunk.toolCallId)
       this.completeToolCall(messageId, index, existingToolCall)
       // If TOOL_CALL_END provides parsed input, use it as the canonical parsed
       // arguments (overrides the accumulated string parse from completeToolCall)
+      // and refresh the rendered part's `input` so it reflects the canonical
+      // value rather than the possibly-divergent accumulated-args parse that
+      // completeToolCall wrote (e.g. an adapter that coerces values differently
+      // between the streamed args and the final structured input).
       if (chunk.input !== undefined) {
         existingToolCall.parsedArguments = chunk.input
+        this.messages = updateToolCallPart(this.messages, messageId, {
+          id: existingToolCall.id,
+          name: existingToolCall.name,
+          arguments: existingToolCall.arguments,
+          state: 'input-complete',
+          input: chunk.input,
+          ...(existingToolCall.metadata !== undefined && {
+            metadata: existingToolCall.metadata,
+          }),
+        })
+        this.emitMessagesChange()
       }
     }
 
@@ -1890,12 +1910,20 @@ export class StreamProcessor {
       return
     }
 
-    // Update UIMessage
+    // Update UIMessage. The arguments are complete now, so surface the parsed
+    // input on the part. For adapters that skip TOOL_CALL_ARGS the arguments
+    // string was back-filled from TOOL_CALL_END.input, so this parse matches
+    // the canonical input. If a TOOL_CALL_END.input diverges from the
+    // accumulated args, handleToolCallEndEvent re-updates the part with the
+    // canonical value after this call.
     this.messages = updateToolCallPart(this.messages, messageId, {
       id: toolCall.id,
       name: toolCall.name,
       arguments: toolCall.arguments,
       state: 'input-complete',
+      ...(toolCall.parsedArguments !== undefined && {
+        input: toolCall.parsedArguments,
+      }),
       ...(toolCall.metadata !== undefined && { metadata: toolCall.metadata }),
     })
     this.emitMessagesChange()

package/src/activities/chat/tools/tool-definition.ts

@@ -26,6 +26,10 @@ export interface ClientTool<
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
   TContext = unknown,
+  // Captured as a literal (`true` / `false`) so downstream types — notably
+  // the tool-call part's `approval` field — can be gated on it. Defaults to
+  // `false` when the tool config omits `needsApproval`.
+  TNeedsApproval extends boolean = false,
 > {
   __toolSide: 'client'
   name: TName
@@ -37,7 +41,7 @@ export interface ClientTool<
   // because `undefined` doesn't extend the schema constraint.
   inputSchema?: TInput
   outputSchema?: TOutput
-  needsApproval?: boolean
+  needsApproval?: TNeedsApproval
   lazy?: boolean
   metadata?: Record<string, unknown>
   execute?: ToolExecuteFunction<TInput, TOutput, TContext>
@@ -51,18 +55,22 @@ export interface ToolDefinitionInstance<
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
   TContext = unknown,
+  TNeedsApproval extends boolean = false,
 > extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'definition'
+  // Narrow the base `needsApproval?: boolean` to the captured literal so it
+  // survives into `ToolCallPartForTool`'s approval gate.
+  needsApproval?: TNeedsApproval
 }
 
 /**
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | (Omit<ClientTool<any, any, string, any>, 'execute'> & {
+  | (Omit<ClientTool<any, any, string, any, boolean>, 'execute'> & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
-  | (Omit<ToolDefinitionInstance<any, any, string, any>, 'execute'> & {
+  | (Omit<ToolDefinitionInstance<any, any, string, any, boolean>, 'execute'> & {
       execute?: ((args: any, context?: any) => any) | undefined
     })
 
@@ -100,12 +108,13 @@ export interface ToolDefinitionConfig<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
+  TNeedsApproval extends boolean = false,
 > {
   name: TName
   description: string
   inputSchema?: TInput
   outputSchema?: TOutput
-  needsApproval?: boolean
+  needsApproval?: TNeedsApproval
   lazy?: boolean
   metadata?: Record<string, unknown>
 }
@@ -117,7 +126,14 @@ export interface ToolDefinition<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
-> extends ToolDefinitionInstance<TInput, TOutput, TName> {
+  TNeedsApproval extends boolean = false,
+> extends ToolDefinitionInstance<
+  TInput,
+  TOutput,
+  TName,
+  unknown,
+  TNeedsApproval
+> {
   /**
    * Create a server-side tool with execute function
    */
@@ -126,11 +142,13 @@ export interface ToolDefinition<
   ) => ServerTool<TInput, TOutput, TName, TContext>
 
   /**
-   * Create a client-side tool with optional execute function
+   * Create a client-side tool with optional execute function.
+   * Carries the definition's `needsApproval` literal through to the client
+   * tool so the tool-call part's `approval` field stays gated on it.
    */
   client: <TContext = unknown>(
     execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-  ) => ClientTool<TInput, TOutput, TName, TContext>
+  ) => ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval>
 }
 
 /**
@@ -192,10 +210,14 @@ export function toolDefinition<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
+  // `const` forces the literal (`true` / `false`) to be captured from the
+  // config's optional `needsApproval` — without it TS widens to `boolean`,
+  // which collapses the approval gate in `ToolCallPartForTool`.
+  const TNeedsApproval extends boolean = false,
 >(
-  config: ToolDefinitionConfig<TInput, TOutput, TName>,
-): ToolDefinition<TInput, TOutput, TName> {
-  const definition: ToolDefinition<TInput, TOutput, TName> = {
+  config: ToolDefinitionConfig<TInput, TOutput, TName, TNeedsApproval>,
+): ToolDefinition<TInput, TOutput, TName, TNeedsApproval> {
+  const definition: ToolDefinition<TInput, TOutput, TName, TNeedsApproval> = {
     __toolSide: 'definition',
     ...config,
     server<TContext = unknown>(
@@ -210,7 +232,7 @@ export function toolDefinition<
 
     client<TContext = unknown>(
       execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
-    ): ClientTool<TInput, TOutput, TName, TContext> {
+    ): ClientTool<TInput, TOutput, TName, TContext, TNeedsApproval> {
       return {
         __toolSide: 'client',
         ...config,

package/src/activities/generateAudio/index.ts

@@ -14,10 +14,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { AudioAdapter } from './adapter'
 import type { AudioGenerationResult, StreamChunk } from '../../types'
 

package/src/activities/generateImage/index.ts

@@ -14,11 +14,11 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import { resolveMediaPrompt } from '../../utilities/media-prompt'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { ImageAdapter } from './adapter'
 import type {
   ImageGenerationResult,

package/src/activities/generateSpeech/index.ts

@@ -14,10 +14,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 

package/src/activities/generateTranscription/index.ts

@@ -14,12 +14,16 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { TranscriptionAdapter } from './adapter'
-import type { StreamChunk, TranscriptionResult } from '../../types'
+import type {
+  StreamChunk,
+  TranscriptionResponseFormat,
+  TranscriptionResult,
+} from '../../types'
 
 // ===========================
 // Activity Kind
@@ -67,7 +71,7 @@ export interface TranscriptionActivityOptions<
   /** An optional prompt to guide the transcription */
   prompt?: string
   /** The format of the transcription output */
-  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
+  responseFormat?: TranscriptionResponseFormat
   /** Provider-specific options for transcription */
   modelOptions?: TranscriptionProviderOptions<TAdapter>
   /**

package/src/activities/generateVideo/index.ts

@@ -17,10 +17,10 @@ import {
   runGenerationFinish,
   runGenerationStart,
   runGenerationUsage,
-} from '../middleware'
+} from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware } from '../middleware/types'
 import type { VideoAdapter } from './adapter'
 import type {
   MediaPrompt,
@@ -47,7 +47,7 @@ export const kind = 'video' as const
  * Extract provider options from a VideoAdapter via ~types.
  */
 export type VideoProviderOptions<TAdapter> =
-  TAdapter extends VideoAdapter<any, any, any, any>
+  TAdapter extends VideoAdapter<any, any, any, any, any, any>
     ? TAdapter['~types']['providerOptions']
     : object
 
@@ -55,7 +55,14 @@ export type VideoProviderOptions<TAdapter> =
  * Extract the size type for a VideoAdapter's model via ~types.
  */
 export type VideoSizeForAdapter<TAdapter> =
-  TAdapter extends VideoAdapter<infer TModel, any, any, infer TSizeMap>
+  TAdapter extends VideoAdapter<
+    infer TModel,
+    any,
+    any,
+    infer TSizeMap,
+    any,
+    any
+  >
     ? TModel extends keyof TSizeMap
       ? TSizeMap[TModel]
       : string
@@ -68,7 +75,14 @@ export type VideoSizeForAdapter<TAdapter> =
  * without a map fall back to the full MediaPrompt.
  */
 export type VideoPromptForAdapter<TAdapter> =
-  TAdapter extends VideoAdapter<infer TModel, any, any, any, infer ModsByName>
+  TAdapter extends VideoAdapter<
+    infer TModel,
+    any,
+    any,
+    any,
+    infer ModsByName,
+    any
+  >
     ? string extends keyof ModsByName
       ? MediaPrompt
       : TModel extends keyof ModsByName
@@ -108,7 +122,7 @@ function createId(prefix: string): string {
  * The model is extracted from the adapter's model property.
  */
 interface VideoActivityBaseOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 > {
   /** The video adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
@@ -124,7 +138,7 @@ interface VideoActivityBaseOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoCreateOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TStream extends boolean = false,
 > = VideoActivityBaseOptions<TAdapter> & {
   /** Request type - create a new job (default if not specified) */
@@ -191,7 +205,7 @@ export type VideoCreateOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export interface VideoStatusOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 > extends VideoActivityBaseOptions<TAdapter> {
   /** Request type - get job status */
   request: 'status'
@@ -205,7 +219,7 @@ export interface VideoStatusOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export interface VideoUrlOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 > extends VideoActivityBaseOptions<TAdapter> {
   /** Request type - get video URL */
   request: 'url'
@@ -220,7 +234,7 @@ export interface VideoUrlOptions<
  * @experimental Video generation is an experimental feature and may change.
  */
 export type VideoActivityOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TRequest extends 'create' | 'status' | 'url' = 'create',
   TStream extends boolean = false,
 > = TRequest extends 'status'
@@ -296,7 +310,7 @@ export type VideoActivityResult<
  * ```
  */
 export function generateVideo<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TStream extends boolean = false,
 >(
   options: VideoCreateOptions<TAdapter, TStream>,
@@ -314,7 +328,7 @@ export function generateVideo<
  * Internal implementation of non-streaming video job creation.
  */
 async function runCreateVideoJob<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
   const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
@@ -383,7 +397,7 @@ function sleep(ms: number): Promise<void> {
  * Handles the full job lifecycle: create job → poll for status → stream updates → yield final result.
  */
 async function* runStreamingVideoGeneration<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, true>): AsyncIterable<StreamChunk> {
   const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
@@ -582,7 +596,7 @@ async function* runStreamingVideoGeneration<
  * ```
  */
 export async function getVideoJobStatus<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
 >(options: {
   adapter: TAdapter & { kind: typeof kind }
   jobId: string
@@ -692,7 +706,7 @@ export async function getVideoJobStatus<
  * Create typed options for the generateVideo() function without executing.
  */
 export function createVideoOptions<
-  TAdapter extends VideoAdapter<string, any, any, any>,
+  TAdapter extends VideoAdapter<string, any, any, any, any, any>,
   TStream extends boolean = false,
 >(
   options: VideoCreateOptions<TAdapter, TStream>,

package/src/index.ts

@@ -121,6 +121,7 @@ export type {
   AbortInfo,
   ErrorInfo,
   SandboxFileEvent,
+  SandboxFileHookEvent,
   ChatSandboxHooks,
 } from './activities/chat/middleware/index'
 
@@ -178,12 +179,13 @@ export { normalizeSystemPrompts } from './system-prompts'
 export { detectImageMimeType } from './utils'
 
 // Realtime
-export { realtimeToken } from './realtime/index'
+export { realtimeToken, createRealtimeEventEmitter } from './realtime/index'
 export type {
   RealtimeToken,
   RealtimeTokenAdapter,
   RealtimeTokenOptions,
   RealtimeSessionConfig,
+  RealtimeToolConfig,
   VADConfig,
   RealtimeMessage,
   RealtimeMessagePart,

package/src/realtime/event-emitter.ts

@@ -0,0 +1,46 @@
+import type {
+  RealtimeEvent,
+  RealtimeEventHandler,
+  RealtimeEventPayloads,
+} from './types'
+
+/**
+ * Handlers are stored with a `never` payload so any specific
+ * `RealtimeEventHandler<TEvent>` is assignable in (contravariance), keeping the
+ * heterogeneous handler map type-safe without `any`. `emit` narrows back to the
+ * event's real payload type via its signature; the lone `as never` at the call
+ * site is the inverse of that stored `never`.
+ */
+type StoredHandler = (payload: never) => void
+
+export function createRealtimeEventEmitter() {
+  const eventHandlers = new Map<RealtimeEvent, Set<StoredHandler>>()
+
+  return {
+    emit<TEvent extends RealtimeEvent>(
+      event: TEvent,
+      payload: RealtimeEventPayloads[TEvent],
+    ) {
+      const handlers = eventHandlers.get(event)
+      if (!handlers) return
+      for (const handler of handlers) {
+        handler(payload as never)
+      }
+    },
+    on<TEvent extends RealtimeEvent>(
+      event: TEvent,
+      handler: RealtimeEventHandler<TEvent>,
+    ): () => void {
+      let handlers = eventHandlers.get(event)
+      if (!handlers) {
+        handlers = new Set<StoredHandler>()
+        eventHandlers.set(event, handlers)
+      }
+      handlers.add(handler)
+
+      return () => {
+        handlers.delete(handler)
+      }
+    },
+  }
+}

package/src/realtime/index.ts

@@ -1,5 +1,7 @@
 import type { RealtimeToken, RealtimeTokenOptions } from './types'
 
+export { createRealtimeEventEmitter } from './event-emitter'
+
 // Re-export all types
 export type * from './types'