@livekit/agents 1.0.48 → 1.1.0-dev.0

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

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { beforeAll, describe, expect, it } from 'vitest';
+import { initializeLogger } from '../../log.js';
+import { defaultEndpointingOptions } from './endpointing.js';
+import { defaultInterruptionOptions } from './interruption.js';
+import { defaultTurnHandlingOptions } from './turn_handling.js';
+import { migrateLegacyOptions } from './utils.js';
+
+beforeAll(() => {
+  initializeLogger({ pretty: true, level: 'info' });
+});
+
+describe('migrateLegacyOptions', () => {
+  it('should return all defaults when no options are provided', () => {
+    const result = migrateLegacyOptions({});
+
+    expect(result.options.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);
+  });
+
+  it('should migrate legacy flat fields into nested turnHandling config', () => {
+    const result = migrateLegacyOptions({
+      voiceOptions: {
+        minInterruptionDuration: 1000,
+        minInterruptionWords: 3,
+        discardAudioIfUninterruptible: false,
+        minEndpointingDelay: 800,
+        maxEndpointingDelay: 5000,
+      },
+    });
+
+    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);
+  });
+
+  it('should set interruption.enabled to false when allowInterruptions is false', () => {
+    const result = migrateLegacyOptions({
+      options: {
+        allowInterruptions: false,
+      },
+    });
+
+    expect(result.options.turnHandling.interruption!.enabled).toBe(false);
+  });
+
+  it('should give options precedence over voiceOptions when both are provided', () => {
+    const 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 },
+        },
+      },
+    });
+
+    expect(result.options.turnHandling.interruption!.minDuration).toBe(3000);
+    expect(result.options.turnHandling.endpointing!.minDelay).toBe(2000);
+  });
+
+  it('should preserve top-level turnDetection in the result', () => {
+    const result = migrateLegacyOptions({
+      turnDetection: 'vad',
+    });
+
+    expect(result.turnDetection).toBe('vad');
+    expect(result.options.turnHandling.turnDetection).toBe('vad');
+  });
+});

package/src/voice/turn_config/utils.ts

@@ -0,0 +1,103 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { log } from '../../log.js';
+import {
+  type AgentSessionOptions,
+  type InternalSessionOptions,
+  defaultSessionOptions,
+} 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 logger = log();
+  const { voiceOptions, turnDetection, options: sessionOptions, ...rest } = legacyOptions;
+
+  if (voiceOptions !== undefined && sessionOptions !== undefined) {
+    logger.warn(
+      'Both voiceOptions and options have been supplied as part of the AgentSessionOptions, voiceOptions will be merged with options taking precedence',
+    );
+  }
+
+  // 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,
+    },
+    endpointing: {
+      minDelay: mergedOptions?.minEndpointingDelay,
+      maxDelay: mergedOptions?.maxEndpointingDelay,
+    },
+
+    ...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,
+  } as const;
+
+  if (mergedOptions?.allowInterruptions === false) {
+    turnHandling.interruption.enabled = false;
+  }
+
+  const optionsWithDefaults = {
+    ...defaultSessionOptions,
+    ...mergedOptions,
+    turnHandling: mergeWithDefaults(turnHandling),
+  };
+
+  const newAgentSessionOptions: AgentSessionOptions<UserData> & {
+    options: InternalSessionOptions;
+  } = {
+    ...rest,
+    options: optionsWithDefaults,
+    voiceOptions: optionsWithDefaults,
+    turnDetection: turnHandling.turnDetection,
+  };
+
+  return newAgentSessionOptions;
+}
+
+/** Remove keys whose value is `undefined` so they don't shadow defaults when spread. */
+export function stripUndefined<T extends object>(obj: T): Partial<T> {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as Partial<T>;
+}
+
+export function mergeWithDefaults(config: TurnHandlingOptions) {
+  return {
+    turnDetection: config.turnDetection ?? defaultTurnHandlingOptions.turnDetection,
+    endpointing: { ...defaultEndpointingOptions, ...stripUndefined(config.endpointing) },
+    interruption: { ...defaultInterruptionOptions, ...stripUndefined(config.interruption) },
+  } as const;
+}