@livekit/agents 1.1.0-dev.0 → 1.2.0

package/src/voice/report.test.ts

@@ -3,10 +3,12 @@
 // SPDX-License-Identifier: Apache-2.0
 import { describe, expect, it } from 'vitest';
 import { ChatContext } from '../llm/chat_context.js';
-import type { VoiceOptions } from './agent_session.js';
+import type { AgentSessionOptions, VoiceOptions } from './agent_session.js';
 import { createSessionReport, sessionReportToJSON } from './report.js';
 
-function baseOptions(): VoiceOptions {
+type ReportOptions = AgentSessionOptions & Partial<VoiceOptions>;
+
+function baseOptions(): ReportOptions {
   return {
     maxToolSteps: 3,
     preemptiveGeneration: false,
@@ -16,7 +18,7 @@ function baseOptions(): VoiceOptions {
   };
 }
 
-function serializeOptions(options: VoiceOptions) {
+function serializeOptions(options: ReportOptions) {
   const report = createSessionReport({
     jobId: 'job',
     roomId: 'room-id',
@@ -94,6 +96,23 @@ describe('sessionReportToJSON', () => {
     });
   });
 
+  it('serializes allow_interruptions from interruption.enabled when present', () => {
+    const options = baseOptions();
+    options.allowInterruptions = true;
+    options.turnHandling = {
+      interruption: {
+        enabled: false,
+        mode: 'adaptive',
+      },
+    };
+
+    const serialized = serializeOptions(options);
+    expect(serialized).toMatchObject({
+      allow_interruptions: false,
+      max_tool_steps: 3,
+    });
+  });
+
   it('falls back to deprecated flat fields when turnHandling values are absent', () => {
     const options = baseOptions();
     options.allowInterruptions = false;

package/src/voice/report.ts

@@ -3,14 +3,16 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { ChatContext } from '../llm/chat_context.js';
 import { type ModelUsage, filterZeroValues } from '../metrics/model_usage.js';
-import type { VoiceOptions } from './agent_session.js';
+import type { AgentSessionOptions, VoiceOptions } from './agent_session.js';
 import type { AgentEvent } from './events.js';
 
+type ReportOptions = AgentSessionOptions & Partial<VoiceOptions>;
+
 export interface SessionReport {
   jobId: string;
   roomId: string;
   room: string;
-  options: VoiceOptions;
+  options: ReportOptions;
   events: AgentEvent[];
   chatHistory: ChatContext;
   enableRecording: boolean;
@@ -32,7 +34,7 @@ export interface SessionReportOptions {
   jobId: string;
   roomId: string;
   room: string;
-  options: VoiceOptions;
+  options: ReportOptions;
   events: AgentEvent[];
   chatHistory: ChatContext;
   enableRecording?: boolean;
@@ -76,22 +78,37 @@ export function createSessionReport(opts: SessionReportOptions): SessionReport {
 //   - Uploads to LiveKit Cloud observability endpoint with JWT auth
 export function sessionReportToJSON(report: SessionReport): Record<string, unknown> {
   const events: Record<string, unknown>[] = [];
-  const interruptionConfig = report.options.turnHandling?.interruption;
-  const endpointingConfig = report.options.turnHandling?.endpointing;
+  const options = report.options;
+  const interruptionConfig = options.turnHandling?.interruption;
+  const endpointingConfig = options.turnHandling?.endpointing;
 
   // Keep backwards compatibility with deprecated fields
   const allowInterruptions =
-    interruptionConfig?.mode !== undefined
-      ? interruptionConfig.mode !== false
-      : report.options.allowInterruptions;
+    interruptionConfig?.enabled !== undefined
+      ? interruptionConfig.enabled
+      : interruptionConfig?.mode !== undefined
+        ? true
+        : options.allowInterruptions ?? options.voiceOptions?.allowInterruptions;
   const discardAudioIfUninterruptible =
     interruptionConfig?.discardAudioIfUninterruptible ??
-    report.options.discardAudioIfUninterruptible;
+    options.discardAudioIfUninterruptible ??
+    options.voiceOptions?.discardAudioIfUninterruptible;
   const minInterruptionDuration =
-    interruptionConfig?.minDuration ?? report.options.minInterruptionDuration;
-  const minInterruptionWords = interruptionConfig?.minWords ?? report.options.minInterruptionWords;
-  const minEndpointingDelay = endpointingConfig?.minDelay ?? report.options.minEndpointingDelay;
-  const maxEndpointingDelay = endpointingConfig?.maxDelay ?? report.options.maxEndpointingDelay;
+    interruptionConfig?.minDuration ??
+    options.minInterruptionDuration ??
+    options.voiceOptions?.minInterruptionDuration;
+  const minInterruptionWords =
+    interruptionConfig?.minWords ??
+    options.minInterruptionWords ??
+    options.voiceOptions?.minInterruptionWords;
+  const minEndpointingDelay =
+    endpointingConfig?.minDelay ??
+    options.minEndpointingDelay ??
+    options.voiceOptions?.minEndpointingDelay;
+  const maxEndpointingDelay =
+    endpointingConfig?.maxDelay ??
+    options.maxEndpointingDelay ??
+    options.voiceOptions?.maxEndpointingDelay;
 
   for (const event of report.events) {
     if (event.type === 'metrics_collected') {
@@ -113,7 +130,7 @@ export function sessionReportToJSON(report: SessionReport): Record<string, unkno
       min_interruption_words: minInterruptionWords,
       min_endpointing_delay: minEndpointingDelay,
       max_endpointing_delay: maxEndpointingDelay,
-      max_tool_steps: report.options.maxToolSteps,
+      max_tool_steps: options.maxToolSteps,
     },
     chat_history: report.chatHistory.toJSON({ excludeTimestamp: false }),
     enable_user_data_training: report.enableRecording,

package/src/voice/room_io/room_io.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import type { TextStreamReader } from '@livekit/rtc-node';
 import {
   type AudioFrame,
   ConnectionState,
@@ -16,12 +17,11 @@ import {
   TrackSource,
 } from '@livekit/rtc-node';
 import type { WritableStreamDefaultWriter } from 'node:stream/web';
-import { ATTRIBUTE_PUBLISH_ON_BEHALF } from '../../constants.js';
+import { ATTRIBUTE_PUBLISH_ON_BEHALF, TOPIC_CHAT } from '../../constants.js';
 import { log } from '../../log.js';
 import { IdentityTransform } from '../../stream/identity_transform.js';
 import { Future, Task, waitForAbort } from '../../utils.js';
 import { type AgentSession } from '../agent_session.js';
-import type { TextInputCallback } from '../client_events.js';
 import {
   AgentSessionEventTypes,
   type AgentStateChangedEvent,
@@ -29,6 +29,7 @@ import {
   type UserInputTranscribedEvent,
 } from '../events.js';
 import type { AudioOutput, TextOutput } from '../io.js';
+import type { TextInputCallback } from '../remote_session.js';
 import { TranscriptionSynchronizer } from '../transcription/synchronizer.js';
 import { ParticipantAudioInputStream } from './_input.js';
 import {
@@ -127,6 +128,7 @@ export class RoomIO {
   private agentTranscriptOutput?: ParalellTextOutput;
   private transcriptionSynchronizer?: TranscriptionSynchronizer;
   private participantIdentity: string | null = null;
+  private textStreamHandlerRegistered = false;
 
   private participantAvailableFuture: Future<RemoteParticipant> = new Future();
   private roomConnectedFuture: Future<void> = new Future();
@@ -271,6 +273,37 @@ export class RoomIO {
     }
   };
 
+  private onUserTextInput = (reader: TextStreamReader, participantInfo: { identity: string }) => {
+    if (this.participantIdentity && participantInfo.identity !== this.participantIdentity) {
+      return;
+    }
+
+    const participant = this.room.remoteParticipants.get(participantInfo.identity);
+    if (!participant) {
+      this.logger.warn('participant not found, ignoring text input');
+      return;
+    }
+
+    const readText = async () => {
+      const text = await reader.readAll();
+
+      const textInputResult = this.inputOptions.textInputCallback!(this.agentSession, {
+        text,
+        info: reader.info,
+        participantIdentity: participantInfo.identity,
+      });
+
+      // check if callback is a Promise
+      if (textInputResult instanceof Promise) {
+        await textInputResult;
+      }
+    };
+
+    readText().catch((error) => {
+      this.logger.error({ error }, 'Error reading text input');
+    });
+  };
+
   private async forwardUserTranscript(signal: AbortSignal): Promise<void> {
     const reader = this.userTranscriptStream.readable.getReader();
     try {
@@ -402,6 +435,18 @@ export class RoomIO {
 
   start() {
     // -- create inputs --
+
+    if (this.inputOptions.textEnabled) {
+      try {
+        this.room.registerTextStreamHandler(TOPIC_CHAT, this.onUserTextInput);
+        this.textStreamHandlerRegistered = true;
+      } catch (error) {
+        if (this.inputOptions.textEnabled) {
+          this.logger.warn(`text stream handler for topic "${TOPIC_CHAT}" already set, ignoring`);
+        }
+      }
+    }
+
     if (this.inputOptions.audioEnabled) {
       this.audioInput = new ParticipantAudioInputStream({
         room: this.room,
@@ -476,6 +521,11 @@ export class RoomIO {
     this.agentSession.off(AgentSessionEventTypes.UserInputTranscribed, this.onUserInputTranscribed);
     this.agentSession.off(AgentSessionEventTypes.AgentStateChanged, this.onAgentStateChanged);
 
+    if (this.textStreamHandlerRegistered) {
+      this.room.unregisterTextStreamHandler(TOPIC_CHAT);
+      this.textStreamHandlerRegistered = false;
+    }
+
     await this.initTask?.cancelAndWait();
 
     // Close stream FIRST so reader.read() in forwardUserTranscript can exit.

package/src/voice/turn_config/interruption.ts

@@ -15,7 +15,7 @@ export interface InterruptionOptions {
    * voice-activity detection. `undefined` means auto-detect.
    * @defaultValue undefined
    */
-  mode: 'adaptive' | 'vad' | false | undefined;
+  mode: 'adaptive' | 'vad' | undefined;
   /**
    * When `true`, buffered audio is dropped while the agent is speaking and cannot be interrupted.
    * @defaultValue true

package/src/voice/turn_config/utils.test.ts

@@ -3,10 +3,11 @@
 // SPDX-License-Identifier: Apache-2.0
 import { beforeAll, describe, expect, it } from 'vitest';
 import { initializeLogger } from '../../log.js';
+import { defaultAgentSessionOptions } from '../agent_session.js';
 import { defaultEndpointingOptions } from './endpointing.js';
 import { defaultInterruptionOptions } from './interruption.js';
 import { defaultTurnHandlingOptions } from './turn_handling.js';
-import { migrateLegacyOptions } from './utils.js';
+import { migrateLegacyOptions, migrateTurnHandling } from './utils.js';
 
 beforeAll(() => {
   initializeLogger({ pretty: true, level: 'info' });
@@ -14,20 +15,20 @@ beforeAll(() => {
 
 describe('migrateLegacyOptions', () => {
   it('should return all defaults when no options are provided', () => {
-    const result = migrateLegacyOptions({});
+    const { agentSessionOptions: result } = migrateLegacyOptions({});
 
-    expect(result.options.turnHandling).toEqual({
+    expect(result.turnHandling).toEqual({
       turnDetection: defaultTurnHandlingOptions.turnDetection,
       endpointing: defaultEndpointingOptions,
       interruption: defaultInterruptionOptions,
     });
-    expect(result.options.maxToolSteps).toBe(3);
-    expect(result.options.preemptiveGeneration).toBe(false);
-    expect(result.options.userAwayTimeout).toBe(15.0);
+    expect(result.maxToolSteps).toBe(defaultAgentSessionOptions.maxToolSteps);
+    expect(result.preemptiveGeneration).toBe(defaultAgentSessionOptions.preemptiveGeneration);
+    expect(result.userAwayTimeout).toBe(defaultAgentSessionOptions.userAwayTimeout);
   });
 
   it('should migrate legacy flat fields into nested turnHandling config', () => {
-    const result = migrateLegacyOptions({
+    const { agentSessionOptions: result } = migrateLegacyOptions({
       voiceOptions: {
         minInterruptionDuration: 1000,
         minInterruptionWords: 3,
@@ -37,64 +38,111 @@ describe('migrateLegacyOptions', () => {
       },
     });
 
-    expect(result.options.turnHandling.interruption!.minDuration).toBe(1000);
-    expect(result.options.turnHandling.interruption!.minWords).toBe(3);
-    expect(result.options.turnHandling.interruption!.discardAudioIfUninterruptible).toBe(false);
-    expect(result.options.turnHandling.endpointing!.minDelay).toBe(800);
-    expect(result.options.turnHandling.endpointing!.maxDelay).toBe(5000);
+    expect(result.turnHandling.interruption!.minDuration).toBe(1000);
+    expect(result.turnHandling.interruption!.minWords).toBe(3);
+    expect(result.turnHandling.interruption!.discardAudioIfUninterruptible).toBe(false);
+    expect(result.turnHandling.endpointing!.minDelay).toBe(800);
+    expect(result.turnHandling.endpointing!.maxDelay).toBe(5000);
   });
 
   it('should set interruption.enabled to false when allowInterruptions is false', () => {
-    const result = migrateLegacyOptions({
-      options: {
-        allowInterruptions: false,
-      },
+    const { agentSessionOptions: result } = migrateLegacyOptions({
+      voiceOptions: { allowInterruptions: false },
     });
 
-    expect(result.options.turnHandling.interruption!.enabled).toBe(false);
+    expect(result.turnHandling.interruption!.enabled).toBe(false);
   });
 
-  it('should give options precedence over voiceOptions when both are provided', () => {
-    const result = migrateLegacyOptions({
+  it('should give top-level fields precedence over voiceOptions', () => {
+    const { agentSessionOptions: result } = migrateLegacyOptions({
       voiceOptions: {
         minInterruptionDuration: 1000,
         maxEndpointingDelay: 5000,
         maxToolSteps: 10,
       },
-      options: {
-        minInterruptionDuration: 2000,
-        maxEndpointingDelay: 8000,
-        maxToolSteps: 5,
-      },
-    });
-
-    expect(result.options.turnHandling.interruption!.minDuration).toBe(2000);
-    expect(result.options.turnHandling.endpointing!.maxDelay).toBe(8000);
-    expect(result.options.maxToolSteps).toBe(5);
-  });
-
-  it('should let explicit turnHandling override legacy flat fields', () => {
-    const result = migrateLegacyOptions({
-      options: {
-        minInterruptionDuration: 1000,
-        minEndpointingDelay: 800,
-        turnHandling: {
-          interruption: { minDuration: 3000 },
-          endpointing: { minDelay: 2000 },
+      turnHandling: {
+        interruption: {
+          minDuration: 2000,
+        },
+        endpointing: {
+          maxDelay: 8000,
         },
       },
+      maxToolSteps: 5,
     });
 
-    expect(result.options.turnHandling.interruption!.minDuration).toBe(3000);
-    expect(result.options.turnHandling.endpointing!.minDelay).toBe(2000);
+    expect(result.turnHandling.interruption!.minDuration).toBe(2000);
+    expect(result.turnHandling.endpointing!.maxDelay).toBe(8000);
+    expect(result.maxToolSteps).toBe(5);
   });
 
   it('should preserve top-level turnDetection in the result', () => {
-    const result = migrateLegacyOptions({
+    const { agentSessionOptions: result } = migrateLegacyOptions({
       turnDetection: 'vad',
     });
 
+    expect(result.turnHandling.turnDetection).toBe('vad');
+  });
+});
+
+describe('migrateTurnHandling', () => {
+  it('should return empty partial when no deprecated Agent fields are given', () => {
+    const result = migrateTurnHandling({});
+    expect(result).toEqual({});
+  });
+
+  it('should set interruption.enabled to false when allowInterruptions is false', () => {
+    const result = migrateTurnHandling({ allowInterruptions: false });
+    expect(result.interruption).toEqual({ enabled: false });
+    expect(result.endpointing).toBeUndefined();
+    expect(result.turnDetection).toBeUndefined();
+  });
+
+  it('should not set interruption when allowInterruptions is true or undefined', () => {
+    expect(migrateTurnHandling({ allowInterruptions: true })).toEqual({});
+    expect(migrateTurnHandling({ allowInterruptions: undefined })).toEqual({});
+  });
+
+  it('should map minEndpointingDelay to endpointing.minDelay', () => {
+    const result = migrateTurnHandling({ minEndpointingDelay: 800 });
+    expect(result.endpointing).toEqual({ minDelay: 800 });
+  });
+
+  it('should map maxEndpointingDelay to endpointing.maxDelay', () => {
+    const result = migrateTurnHandling({ maxEndpointingDelay: 5000 });
+    expect(result.endpointing).toEqual({ maxDelay: 5000 });
+  });
+
+  it('should pass through turnDetection', () => {
+    const result = migrateTurnHandling({ turnDetection: 'vad' });
     expect(result.turnDetection).toBe('vad');
-    expect(result.options.turnHandling.turnDetection).toBe('vad');
+  });
+
+  it('should combine all deprecated Agent fields', () => {
+    const result = migrateTurnHandling({
+      turnDetection: 'stt',
+      allowInterruptions: false,
+      minEndpointingDelay: 400,
+      maxEndpointingDelay: 3000,
+    });
+    expect(result.turnDetection).toBe('stt');
+    expect(result.interruption).toEqual({ enabled: false });
+    expect(result.endpointing).toEqual({ minDelay: 400, maxDelay: 3000 });
+  });
+
+  it('should ignore deprecated Agent fields when explicit turnHandling is provided', () => {
+    const turnHandling = {
+      endpointing: { minDelay: 999, maxDelay: 4000 },
+      interruption: { enabled: true },
+      turnDetection: 'vad' as const,
+    };
+    const result = migrateTurnHandling({
+      turnHandling,
+      turnDetection: 'stt',
+      allowInterruptions: false,
+      minEndpointingDelay: 100,
+      maxEndpointingDelay: 200,
+    });
+    expect(result).toEqual(turnHandling);
   });
 });

package/src/voice/turn_config/utils.ts

@@ -5,88 +5,105 @@ import { log } from '../../log.js';
 import {
   type AgentSessionOptions,
   type InternalSessionOptions,
-  defaultSessionOptions,
+  type TurnDetectionMode,
+  type VoiceOptions,
 } from '../agent_session.js';
 import { defaultEndpointingOptions } from './endpointing.js';
 import { defaultInterruptionOptions } from './interruption.js';
 import { type TurnHandlingOptions, defaultTurnHandlingOptions } from './turn_handling.js';
 
-export function migrateLegacyOptions<UserData>(
-  legacyOptions: AgentSessionOptions<UserData>,
-): AgentSessionOptions<UserData> & { options: InternalSessionOptions } {
+const defaultSessionOptions = {
+  maxToolSteps: 3,
+  preemptiveGeneration: true,
+  userAwayTimeout: 15.0,
+  aecWarmupDuration: 3000,
+  turnHandling: {},
+  useTtsAlignedTranscript: true,
+} as const satisfies AgentSessionOptions;
+
+const defaultLegacyVoiceOptions: VoiceOptions = {
+  minEndpointingDelay: defaultTurnHandlingOptions.endpointing.minDelay,
+  maxEndpointingDelay: defaultTurnHandlingOptions.endpointing.maxDelay,
+  maxToolSteps: defaultSessionOptions.maxToolSteps,
+  preemptiveGeneration: defaultSessionOptions.preemptiveGeneration,
+};
+
+export function migrateLegacyOptions<UserData>(legacyOptions: AgentSessionOptions<UserData>): {
+  agentSessionOptions: InternalSessionOptions<UserData>;
+  legacyVoiceOptions: VoiceOptions;
+} {
   const logger = log();
-  const { voiceOptions, turnDetection, options: sessionOptions, ...rest } = legacyOptions;
+  const {
+    voiceOptions,
+    turnDetection,
+    stt,
+    vad,
+    llm,
+    tts,
+    userData,
+    connOptions,
+    ...sessionOptions
+  } = legacyOptions;
 
-  if (voiceOptions !== undefined && sessionOptions !== undefined) {
+  if (voiceOptions !== undefined) {
     logger.warn(
-      'Both voiceOptions and options have been supplied as part of the AgentSessionOptions, voiceOptions will be merged with options taking precedence',
+      'voiceOptions is deprecated, use top-level SessionOptions fields on AgentSessionOptions instead',
     );
   }
 
-  // Preserve turnDetection before cloning since structuredClone converts class instances to plain objects
-  const originalTurnDetection =
-    sessionOptions?.turnHandling?.turnDetection ??
-    voiceOptions?.turnHandling?.turnDetection ??
-    turnDetection;
-
-  // Exclude potentially non-cloneable turnDetection objects before structuredClone.
-  // They are restored from originalTurnDetection below.
-  const cloneableVoiceOptions = voiceOptions
-    ? {
-        ...voiceOptions,
-        turnHandling: voiceOptions.turnHandling
-          ? { ...voiceOptions.turnHandling, turnDetection: undefined }
-          : voiceOptions.turnHandling,
-      }
-    : voiceOptions;
-  const cloneableSessionOptions = sessionOptions
-    ? {
-        ...sessionOptions,
-        turnHandling: sessionOptions.turnHandling
-          ? { ...sessionOptions.turnHandling, turnDetection: undefined }
-          : sessionOptions.turnHandling,
-      }
-    : sessionOptions;
-
-  const mergedOptions = structuredClone({ ...cloneableVoiceOptions, ...cloneableSessionOptions });
-
   const turnHandling: TurnHandlingOptions = {
     interruption: {
-      discardAudioIfUninterruptible: mergedOptions?.discardAudioIfUninterruptible,
-      minDuration: mergedOptions?.minInterruptionDuration,
-      minWords: mergedOptions?.minInterruptionWords,
+      discardAudioIfUninterruptible: voiceOptions?.discardAudioIfUninterruptible,
+      minDuration: voiceOptions?.minInterruptionDuration,
+      minWords: voiceOptions?.minInterruptionWords,
+      ...sessionOptions.turnHandling?.interruption,
     },
     endpointing: {
-      minDelay: mergedOptions?.minEndpointingDelay,
-      maxDelay: mergedOptions?.maxEndpointingDelay,
+      minDelay: voiceOptions?.minEndpointingDelay,
+      maxDelay: voiceOptions?.maxEndpointingDelay,
+      ...sessionOptions.turnHandling?.endpointing,
     },
 
-    ...mergedOptions.turnHandling,
-    // Restore original turnDetection after spread to preserve class instance with methods
-    // (structuredClone converts class instances to plain objects, losing prototype methods)
-    turnDetection: originalTurnDetection,
+    turnDetection: sessionOptions?.turnHandling?.turnDetection ?? turnDetection,
   } as const;
 
-  if (mergedOptions?.allowInterruptions === false) {
+  if (
+    voiceOptions?.allowInterruptions === false &&
+    turnHandling.interruption.enabled === undefined
+  ) {
     turnHandling.interruption.enabled = false;
   }
 
-  const optionsWithDefaults = {
+  const migratedVoiceOptions: AgentSessionOptions<UserData> = {};
+
+  if (voiceOptions?.maxToolSteps !== undefined) {
+    migratedVoiceOptions.maxToolSteps = voiceOptions.maxToolSteps;
+  }
+  if (voiceOptions?.preemptiveGeneration !== undefined) {
+    migratedVoiceOptions.preemptiveGeneration = voiceOptions.preemptiveGeneration;
+  }
+  if (voiceOptions?.userAwayTimeout !== undefined) {
+    migratedVoiceOptions.userAwayTimeout = voiceOptions.userAwayTimeout;
+  }
+
+  const legacyVoiceOptions = { ...defaultLegacyVoiceOptions, ...voiceOptions };
+
+  const agentSessionOptions = {
+    stt,
+    vad,
+    llm,
+    tts,
+    userData,
+    connOptions,
     ...defaultSessionOptions,
-    ...mergedOptions,
+    ...migratedVoiceOptions,
+    ...sessionOptions,
     turnHandling: mergeWithDefaults(turnHandling),
+    // repopulate the deprecated voice options with migrated options for backwards compatibility
+    voiceOptions: legacyVoiceOptions,
   };
 
-  const newAgentSessionOptions: AgentSessionOptions<UserData> & {
-    options: InternalSessionOptions;
-  } = {
-    ...rest,
-    options: optionsWithDefaults,
-    voiceOptions: optionsWithDefaults,
-    turnDetection: turnHandling.turnDetection,
-  };
-
-  return newAgentSessionOptions;
+  return { agentSessionOptions, legacyVoiceOptions };
 }
 
 /** Remove keys whose value is `undefined` so they don't shadow defaults when spread. */
@@ -101,3 +118,50 @@ export function mergeWithDefaults(config: TurnHandlingOptions) {
     interruption: { ...defaultInterruptionOptions, ...stripUndefined(config.interruption) },
   } as const;
 }
+
+/**
+ * Build a partial {@link TurnHandlingOptions} from deprecated Agent constructor fields.
+ * Mirrors the Python Agent compatibility path, but keeps the JS API surface explicit.
+ */
+export function migrateTurnHandling(opts: {
+  turnDetection?: TurnDetectionMode;
+  allowInterruptions?: boolean;
+  minEndpointingDelay?: number;
+  maxEndpointingDelay?: number;
+  turnHandling?: TurnHandlingOptions;
+}): Partial<TurnHandlingOptions> {
+  if (opts.turnHandling !== undefined) {
+    return opts.turnHandling;
+  }
+
+  const migrated: Partial<TurnHandlingOptions> = {};
+
+  const endpointing: Partial<TurnHandlingOptions['endpointing']> = {};
+  if (opts.minEndpointingDelay !== undefined) {
+    endpointing.minDelay = opts.minEndpointingDelay;
+  }
+  if (opts.maxEndpointingDelay !== undefined) {
+    endpointing.maxDelay = opts.maxEndpointingDelay;
+  }
+  if (Object.keys(endpointing).length > 0) {
+    migrated.endpointing = endpointing;
+  }
+
+  const interruption: Partial<TurnHandlingOptions['interruption']> = {};
+  if (opts.allowInterruptions === false) {
+    interruption.enabled = false;
+  }
+  if (Object.keys(interruption).length > 0) {
+    migrated.interruption = interruption;
+  }
+
+  if (opts.turnDetection !== undefined) {
+    migrated.turnDetection = opts.turnDetection;
+  }
+
+  return {
+    ...(migrated.endpointing ? { endpointing: migrated.endpointing } : {}),
+    ...(migrated.interruption ? { interruption: migrated.interruption } : {}),
+    ...(migrated.turnDetection !== undefined ? { turnDetection: migrated.turnDetection } : {}),
+  };
+}