@livekit/agents 1.1.0 → 1.2.1

package/src/cpu.test.ts

@@ -0,0 +1,239 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { CGroupV1CpuMonitor, CGroupV2CpuMonitor, DefaultCpuMonitor, getCpuMonitor } from './cpu.js';
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => ''),
+}));
+
+const mockExistsSync = vi.mocked(existsSync);
+const mockReadFileSync = vi.mocked(readFileSync);
+
+describe('cpu', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete process.env.NUM_CPUS;
+  });
+
+  afterEach(() => {
+    delete process.env.NUM_CPUS;
+  });
+
+  describe('getCpuMonitor', () => {
+    it('returns CGroupV2CpuMonitor when /sys/fs/cgroup/cpu.stat exists', () => {
+      mockExistsSync.mockImplementation((p) => p === '/sys/fs/cgroup/cpu.stat');
+      const monitor = getCpuMonitor();
+      expect(monitor).toBeInstanceOf(CGroupV2CpuMonitor);
+    });
+
+    it('returns CGroupV1CpuMonitor when cgroup v1 paths exist', () => {
+      mockExistsSync.mockImplementation((p) => p === '/sys/fs/cgroup/cpuacct/cpuacct.usage');
+      const monitor = getCpuMonitor();
+      expect(monitor).toBeInstanceOf(CGroupV1CpuMonitor);
+    });
+
+    it('returns DefaultCpuMonitor when no cgroup paths exist', () => {
+      mockExistsSync.mockReturnValue(false);
+      const monitor = getCpuMonitor();
+      expect(monitor).toBeInstanceOf(DefaultCpuMonitor);
+    });
+  });
+
+  describe('DefaultCpuMonitor', () => {
+    it('returns os.cpus().length for cpuCount', () => {
+      const monitor = new DefaultCpuMonitor();
+      expect(monitor.cpuCount()).toBe(os.cpus().length);
+    });
+
+    it('respects NUM_CPUS env var', () => {
+      process.env.NUM_CPUS = '4.5';
+      const monitor = new DefaultCpuMonitor();
+      expect(monitor.cpuCount()).toBe(4.5);
+    });
+
+    it('ignores invalid NUM_CPUS', () => {
+      process.env.NUM_CPUS = 'notanumber';
+      const monitor = new DefaultCpuMonitor();
+      expect(monitor.cpuCount()).toBe(os.cpus().length);
+    });
+
+    it('cpuPercent returns value in [0, 1]', async () => {
+      const monitor = new DefaultCpuMonitor();
+      const result = await monitor.cpuPercent(50);
+      expect(result).toBeGreaterThanOrEqual(0);
+      expect(result).toBeLessThanOrEqual(1);
+    }, 10_000);
+  });
+
+  describe('CGroupV2CpuMonitor', () => {
+    it('returns quota/period for cpuCount', () => {
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu.max') return '200000 100000';
+        return '';
+      });
+      const monitor = new CGroupV2CpuMonitor();
+      expect(monitor.cpuCount()).toBe(2);
+    });
+
+    it('falls back to os.cpus().length when quota is max', () => {
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu.max') return 'max 100000';
+        return '';
+      });
+      const monitor = new CGroupV2CpuMonitor();
+      expect(monitor.cpuCount()).toBe(os.cpus().length);
+    });
+
+    it('handles missing cpu.max gracefully', () => {
+      mockReadFileSync.mockImplementation(() => {
+        throw new Error('ENOENT');
+      });
+      const monitor = new CGroupV2CpuMonitor();
+      expect(monitor.cpuCount()).toBe(os.cpus().length);
+    });
+
+    it('respects NUM_CPUS env var', () => {
+      process.env.NUM_CPUS = '3';
+      const monitor = new CGroupV2CpuMonitor();
+      expect(monitor.cpuCount()).toBe(3);
+    });
+
+    it('cpuPercent computes correct value from usage_usec deltas', async () => {
+      let callCount = 0;
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu.stat') {
+          callCount++;
+          // Two reads: 1,000,000 usec apart => 1s of CPU usage over the interval
+          return callCount <= 1
+            ? 'usage_usec 1000000\nuser_usec 800000\nsystem_usec 200000'
+            : 'usage_usec 2000000\nuser_usec 1600000\nsystem_usec 400000';
+        }
+        if (String(p) === '/sys/fs/cgroup/cpu.max') return '200000 100000';
+        return '';
+      });
+      const monitor = new CGroupV2CpuMonitor();
+      // interval=100ms, 2 cpus, 1s of usage => 1/(0.1*2) = 5, clamped to 1
+      const result = await monitor.cpuPercent(100);
+      expect(result).toBe(1);
+    }, 10_000);
+
+    it('cpuPercent returns fractional load', async () => {
+      let callCount = 0;
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu.stat') {
+          callCount++;
+          // 50,000 usec delta => 0.05s of CPU over 0.1s on 2 cpus => 0.05/(0.1*2) = 0.25
+          return callCount <= 1 ? 'usage_usec 1000000\n' : 'usage_usec 1050000\n';
+        }
+        if (String(p) === '/sys/fs/cgroup/cpu.max') return '200000 100000';
+        return '';
+      });
+      const monitor = new CGroupV2CpuMonitor();
+      const result = await monitor.cpuPercent(100);
+      expect(result).toBeCloseTo(0.25, 1);
+    }, 10_000);
+
+    it('throws when usage_usec is missing from cpu.stat', async () => {
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu.stat') return 'user_usec 800000\nsystem_usec 200000';
+        return '';
+      });
+      const monitor = new CGroupV2CpuMonitor();
+      await expect(() => monitor.cpuPercent(50)).rejects.toThrow('Failed to read CPU usage');
+    });
+  });
+
+  describe('CGroupV1CpuMonitor', () => {
+    it('returns quota/period for cpuCount', () => {
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_quota_us') return '200000';
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_period_us') return '100000';
+        return '';
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      expect(monitor.cpuCount()).toBe(2);
+    });
+
+    it('defaults to 2.0 when quota is -1', () => {
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_quota_us') return '-1';
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_period_us') return '100000';
+        return '';
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      expect(monitor.cpuCount()).toBe(2.0);
+    });
+
+    it('defaults to 2.0 when quota file is unreadable', () => {
+      mockReadFileSync.mockImplementation(() => {
+        throw new Error('ENOENT');
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      expect(monitor.cpuCount()).toBe(2.0);
+    });
+
+    it('clamps cpuCount to minimum 1.0', () => {
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_quota_us') return '50000';
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_period_us') return '100000';
+        return '';
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      expect(monitor.cpuCount()).toBe(1.0);
+    });
+
+    it('respects NUM_CPUS env var', () => {
+      process.env.NUM_CPUS = '8';
+      const monitor = new CGroupV1CpuMonitor();
+      expect(monitor.cpuCount()).toBe(8);
+    });
+
+    it('cpuPercent computes correct value from nanosecond deltas', async () => {
+      let callCount = 0;
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpuacct/cpuacct.usage') {
+          callCount++;
+          // 100_000_000 ns delta = 0.1s CPU over 0.1s interval on 2 cpus => 0.1/(0.1*2) = 0.5
+          return callCount <= 1 ? '1000000000' : '1100000000';
+        }
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_quota_us') return '200000';
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_period_us') return '100000';
+        return '';
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      const result = await monitor.cpuPercent(100);
+      expect(result).toBeCloseTo(0.5, 1);
+    }, 10_000);
+
+    it('clamps cpuPercent output to [0, 1]', async () => {
+      let callCount = 0;
+      mockReadFileSync.mockImplementation((p) => {
+        if (String(p) === '/sys/fs/cgroup/cpuacct/cpuacct.usage') {
+          callCount++;
+          // Huge delta => would exceed 1.0 without clamping
+          return callCount <= 1 ? '0' : '10000000000';
+        }
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_quota_us') return '100000';
+        if (String(p) === '/sys/fs/cgroup/cpu/cpu.cfs_period_us') return '100000';
+        return '';
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      const result = await monitor.cpuPercent(100);
+      expect(result).toBeLessThanOrEqual(1);
+      expect(result).toBeGreaterThanOrEqual(0);
+    }, 10_000);
+
+    it('throws when cpuacct.usage is unreadable', async () => {
+      mockReadFileSync.mockImplementation(() => {
+        throw new Error('ENOENT');
+      });
+      const monitor = new CGroupV1CpuMonitor();
+      await expect(() => monitor.cpuPercent(50)).rejects.toThrow('Failed to read cpuacct.usage');
+    });
+  });
+});

package/src/cpu.ts

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+
+/** @internal */
+export interface CpuMonitor {
+  cpuCount(): number;
+  cpuPercent(intervalMs: number): Promise<number>;
+}
+
+function cpuCountFromEnv(): number | undefined {
+  const raw = process.env.NUM_CPUS;
+  if (raw === undefined) return undefined;
+  const parsed = parseFloat(raw);
+  if (Number.isNaN(parsed)) {
+    console.warn('Failed to parse NUM_CPUS from environment');
+    return undefined;
+  }
+  return parsed;
+}
+
+/** @internal */
+export class DefaultCpuMonitor implements CpuMonitor {
+  cpuCount(): number {
+    return cpuCountFromEnv() ?? (os.cpus().length || 1);
+  }
+
+  cpuPercent(intervalMs: number): Promise<number> {
+    return new Promise((resolve) => {
+      const cpus1 = os.cpus();
+      const timer = setTimeout(() => {
+        const cpus2 = os.cpus();
+        let idle = 0;
+        let total = 0;
+        for (let i = 0; i < cpus1.length; i++) {
+          const cpu1 = cpus1[i]!.times;
+          const cpu2 = cpus2[i]!.times;
+          idle += cpu2.idle - cpu1.idle;
+          const total1 = Object.values(cpu1).reduce((acc, v) => acc + v, 0);
+          const total2 = Object.values(cpu2).reduce((acc, v) => acc + v, 0);
+          total += total2 - total1;
+        }
+        resolve(total === 0 ? 0 : Math.max(Math.min(+(1 - idle / total).toFixed(2), 1), 0));
+      }, intervalMs);
+      timer.unref();
+    });
+  }
+}
+
+/** @internal */
+export class CGroupV2CpuMonitor implements CpuMonitor {
+  cpuCount(): number {
+    const envCpus = cpuCountFromEnv();
+    if (envCpus !== undefined) return envCpus;
+    const [quota, period] = this.#readCpuMax();
+    if (quota === 'max') return os.cpus().length || 1;
+    return parseInt(quota) / period;
+  }
+
+  cpuPercent(intervalMs: number): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const usageStart = this.#readCpuUsage();
+      const timer = setTimeout(() => {
+        try {
+          const usageEnd = this.#readCpuUsage();
+          const usageDiffUsec = usageEnd - usageStart;
+          const usageSeconds = usageDiffUsec / 1_000_000;
+          const numCpus = this.cpuCount();
+          const intervalSeconds = intervalMs / 1000;
+          const percent = usageSeconds / (intervalSeconds * numCpus);
+          resolve(Math.max(Math.min(percent, 1), 0));
+        } catch (e) {
+          reject(e);
+        }
+      }, intervalMs);
+      timer.unref();
+    });
+  }
+
+  #readCpuMax(): [string, number] {
+    try {
+      const data = readFileSync('/sys/fs/cgroup/cpu.max', 'utf-8').trim().split(/\s+/);
+      const quota = data[0] ?? 'max';
+      const period = data[1] ? parseInt(data[1]) : 100_000;
+      return [quota, Number.isNaN(period) ? 100_000 : period];
+    } catch {
+      return ['max', 100_000];
+    }
+  }
+
+  #readCpuUsage(): number {
+    const content = readFileSync('/sys/fs/cgroup/cpu.stat', 'utf-8');
+    for (const line of content.split('\n')) {
+      if (line.startsWith('usage_usec')) {
+        return parseInt(line.split(/\s+/)[1]!);
+      }
+    }
+    throw new Error('Failed to read CPU usage from /sys/fs/cgroup/cpu.stat');
+  }
+}
+
+/** @internal */
+export class CGroupV1CpuMonitor implements CpuMonitor {
+  cpuCount(): number {
+    const envCpus = cpuCountFromEnv();
+    if (envCpus !== undefined) return envCpus;
+    const [quota, period] = this.#readCfsQuotaAndPeriod();
+    if (quota === null || quota < 0 || period === null || period <= 0) {
+      // do not use the host CPU count as it could overstate the number available to the container
+      return 2.0;
+    }
+    return Math.max(quota / period, 1.0);
+  }
+
+  cpuPercent(intervalMs: number): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const usageStart = this.#readCpuacctUsage();
+      const timer = setTimeout(() => {
+        try {
+          const usageEnd = this.#readCpuacctUsage();
+          const usageDiffNs = usageEnd - usageStart;
+          const usageSeconds = usageDiffNs / 1_000_000_000;
+          const numCpus = this.cpuCount();
+          const intervalSeconds = intervalMs / 1000;
+          const percent = usageSeconds / (intervalSeconds * numCpus);
+          resolve(Math.max(Math.min(percent, 1.0), 0.0));
+        } catch (e) {
+          reject(e);
+        }
+      }, intervalMs);
+      timer.unref();
+    });
+  }
+
+  #readCfsQuotaAndPeriod(): [number | null, number | null] {
+    const quota = readFirstInt('/sys/fs/cgroup/cpu/cpu.cfs_quota_us');
+    const period = readFirstInt('/sys/fs/cgroup/cpu/cpu.cfs_period_us');
+    return [quota, period];
+  }
+
+  #readCpuacctUsage(): number {
+    const value = readFirstInt('/sys/fs/cgroup/cpuacct/cpuacct.usage');
+    if (value === null) {
+      throw new Error('Failed to read cpuacct.usage for cgroup v1');
+    }
+    return value;
+  }
+}
+
+function readFirstInt(path: string): number | null {
+  try {
+    const val = parseInt(readFileSync(path, 'utf-8').trim());
+    return Number.isNaN(val) ? null : val;
+  } catch {
+    return null;
+  }
+}
+
+function isCGroupV2(): boolean {
+  return existsSync('/sys/fs/cgroup/cpu.stat');
+}
+
+function isCGroupV1(): boolean {
+  return existsSync('/sys/fs/cgroup/cpuacct/cpuacct.usage');
+}
+
+export function getCpuMonitor(): CpuMonitor {
+  if (isCGroupV2()) return new CGroupV2CpuMonitor();
+  if (isCGroupV1()) return new CGroupV1CpuMonitor();
+  return new DefaultCpuMonitor();
+}

package/src/http_server.ts

@@ -4,10 +4,10 @@
 import { type IncomingMessage, type Server, type ServerResponse, createServer } from 'node:http';
 import { log } from './log.js';
 
-const healthCheck = async (res: ServerResponse) => {
-  res.writeHead(200);
-  res.end('OK');
-};
+export interface HealthCheckResult {
+  healthy: boolean;
+  message: string;
+}
 
 interface WorkerResponse {
   agent_name: string;
@@ -23,13 +23,25 @@ export class HTTPServer {
   app: Server;
   #logger = log();
 
-  constructor(host: string, port: number, workerListener: () => WorkerResponse) {
+  constructor(
+    host: string,
+    port: number,
+    healthCheckListener: () => HealthCheckResult,
+    workerListener: () => WorkerResponse,
+  ) {
     this.host = host;
     this.port = port;
 
     this.app = createServer((req: IncomingMessage, res: ServerResponse) => {
       if (req.url === '/') {
-        healthCheck(res);
+        const result = healthCheckListener();
+        if (result.healthy) {
+          res.writeHead(200);
+          res.end(result.message);
+        } else {
+          res.writeHead(503);
+          res.end(result.message);
+        }
       } else if (req.url === '/worker') {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify(workerListener()));

package/src/index.ts

@@ -9,29 +9,31 @@
  * @see {@link https://docs.livekit.io/agents/overview | LiveKit Agents documentation}
  * @packageDocumentation
  */
-import * as cli from './cli.js';
-import * as inference from './inference/index.js';
-import * as ipc from './ipc/index.js';
-import * as llm from './llm/index.js';
-import * as metrics from './metrics/index.js';
-import * as stream from './stream/index.js';
-import * as stt from './stt/index.js';
-import * as tokenize from './tokenize/index.js';
-import * as tts from './tts/index.js';
-import * as voice from './voice/index.js';
-
 export * from './_exceptions.js';
 export * from './audio.js';
+export * as beta from './beta/index.js';
+export * as cli from './cli.js';
+export * from './connection_pool.js';
 export * from './generator.js';
+export * as inference from './inference/index.js';
 export * from './inference_runner.js';
+export * as ipc from './ipc/index.js';
 export * from './job.js';
+export * from './language.js';
+export * as llm from './llm/index.js';
 export * from './log.js';
+export * as metrics from './metrics/index.js';
 export * from './plugin.js';
+export * as stream from './stream/index.js';
+export * as stt from './stt/index.js';
+export * as telemetry from './telemetry/index.js';
+export * as tokenize from './tokenize/index.js';
 export * from './transcription.js';
+export * as tts from './tts/index.js';
 export * from './types.js';
 export * from './utils.js';
 export * from './vad.js';
 export * from './version.js';
+export * as voice from './voice/index.js';
+export { createTimedString, isTimedString, type TimedString } from './voice/io.js';
 export * from './worker.js';
-
-export { cli, inference, ipc, llm, metrics, stream, stt, tokenize, tts, voice };

package/src/inference/api_protos.ts

@@ -50,8 +50,8 @@ export const ttsSessionClosedEventSchema = z.object({
 
 export const ttsErrorEventSchema = z.object({
   type: z.literal('error'),
-  message: z.string(),
-  session_id: z.string(),
+  message: z.string().optional(),
+  session_id: z.string().optional(),
 });
 
 export const ttsClientEventSchema = z.discriminatedUnion('type', [
@@ -80,3 +80,86 @@ export type TtsSessionClosedEvent = z.infer<typeof ttsSessionClosedEventSchema>;
 export type TtsErrorEvent = z.infer<typeof ttsErrorEventSchema>;
 export type TtsClientEvent = z.infer<typeof ttsClientEventSchema>;
 export type TtsServerEvent = z.infer<typeof ttsServerEventSchema>;
+
+// ============================================================================
+// STT Schemas
+// ============================================================================
+
+// Word-level timing data
+export const sttWordSchema = z.object({
+  word: z.string().optional().default(''),
+  start: z.number().optional().default(0),
+  end: z.number().optional().default(0),
+  confidence: z.number().optional().default(0.0),
+  extra: z.unknown().nullable().optional(),
+});
+
+// Interim transcript event
+export const sttInterimTranscriptEventSchema = z.object({
+  type: z.literal('interim_transcript'),
+  session_id: z.string().optional(),
+  transcript: z.string().optional().default(''),
+  language: z.string().optional().default(''),
+  start: z.number().optional().default(0),
+  duration: z.number().optional().default(0),
+  confidence: z.number().optional().default(1.0),
+  words: z.array(sttWordSchema).optional().default([]),
+  extra: z.unknown().nullable().optional(),
+});
+
+// Final transcript event
+export const sttFinalTranscriptEventSchema = z.object({
+  type: z.literal('final_transcript'),
+  session_id: z.string().optional(),
+  transcript: z.string().optional().default(''),
+  language: z.string().optional().default(''),
+  start: z.number().optional().default(0),
+  duration: z.number().optional().default(0),
+  confidence: z.number().optional().default(1.0),
+  words: z.array(sttWordSchema).optional().default([]),
+  extra: z.unknown().nullable().optional(),
+});
+
+// Session created event
+export const sttSessionCreatedEventSchema = z.object({
+  type: z.literal('session.created'),
+  session_id: z.string().optional(),
+});
+
+// Session finalized event
+export const sttSessionFinalizedEventSchema = z.object({
+  type: z.literal('session.finalized'),
+});
+
+// Session closed event
+export const sttSessionClosedEventSchema = z.object({
+  type: z.literal('session.closed'),
+});
+
+// Error event
+export const sttErrorEventSchema = z.object({
+  type: z.literal('error'),
+  message: z.string().optional(),
+  code: z.string().optional(),
+});
+
+// Discriminated union for all STT server events
+export const sttServerEventSchema = z.discriminatedUnion('type', [
+  sttSessionCreatedEventSchema,
+  sttSessionFinalizedEventSchema,
+  sttSessionClosedEventSchema,
+  sttInterimTranscriptEventSchema,
+  sttFinalTranscriptEventSchema,
+  sttErrorEventSchema,
+]);
+
+// Type exports for STT
+export type SttWord = z.infer<typeof sttWordSchema>;
+export type SttInterimTranscriptEvent = z.infer<typeof sttInterimTranscriptEventSchema>;
+export type SttFinalTranscriptEvent = z.infer<typeof sttFinalTranscriptEventSchema>;
+export type SttTranscriptEvent = SttInterimTranscriptEvent | SttFinalTranscriptEvent;
+export type SttSessionCreatedEvent = z.infer<typeof sttSessionCreatedEventSchema>;
+export type SttSessionFinalizedEvent = z.infer<typeof sttSessionFinalizedEventSchema>;
+export type SttSessionClosedEvent = z.infer<typeof sttSessionClosedEventSchema>;
+export type SttErrorEvent = z.infer<typeof sttErrorEventSchema>;
+export type SttServerEvent = z.infer<typeof sttServerEventSchema>;

package/src/inference/index.ts

@@ -5,8 +5,36 @@ import * as llm from './llm.js';
 import * as stt from './stt.js';
 import * as tts from './tts.js';
 
-export { LLM, LLMStream, type AzureModels, type LLMModels, type LLMOptions } from './llm.js';
-export type { GatewayOptions, InferenceLLMOptions } from './llm.js';
-export { STT, type STTLanguages, type STTModels, type STTOptions } from './stt.js';
-export { TTS, type TTSModels, type TTSOptions } from './tts.js';
+export {
+  LLM,
+  LLMStream,
+  type ChatCompletionOptions,
+  type GatewayOptions,
+  type InferenceLLMOptions,
+  type LLMModels,
+} from './llm.js';
+
+export {
+  normalizeSTTFallback,
+  parseSTTModelString,
+  STT,
+  type STTFallbackModel,
+  type STTFallbackModelType,
+  type STTLanguages,
+  type STTModels,
+  type ModelWithLanguage as STTModelString,
+  type STTOptions,
+} from './stt.js';
+
+export {
+  normalizeTTSFallback,
+  parseTTSModelString,
+  TTS,
+  type TTSFallbackModel,
+  type TTSFallbackModelType,
+  type TTSModels,
+  type ModelWithVoice as TTSModelString,
+  type TTSOptions,
+} from './tts.js';
+
 export { llm, stt, tts };

package/src/inference/interruption/defaults.ts

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { ApiConnectOptions } from './interruption_stream.js';
+import type { InterruptionOptions } from './types.js';
+
+export const MIN_INTERRUPTION_DURATION_IN_S = 0.025 * 2; // 25ms per frame, 2 consecutive frames
+export const THRESHOLD = 0.5;
+export const MAX_AUDIO_DURATION_IN_S = 3.0;
+export const AUDIO_PREFIX_DURATION_IN_S = 0.5;
+export const DETECTION_INTERVAL_IN_S = 0.1;
+export const REMOTE_INFERENCE_TIMEOUT_IN_S = 0.7;
+export const SAMPLE_RATE = 16000;
+export const FRAMES_PER_SECOND = 40;
+export const FRAME_DURATION_IN_S = 0.025; // 25ms per frame
+
+export const apiConnectDefaults: ApiConnectOptions = {
+  maxRetries: 3,
+  retryInterval: 2_000,
+  timeout: 10_000,
+} as const;
+
+/**
+ * Calculate the retry interval using exponential backoff with jitter.
+ * Matches the Python implementation's _interval_for_retry behavior.
+ */
+export function intervalForRetry(
+  attempt: number,
+  baseInterval: number = apiConnectDefaults.retryInterval,
+): number {
+  // Exponential backoff: baseInterval * 2^attempt with some jitter
+  const exponentialDelay = baseInterval * Math.pow(2, attempt);
+  // Add jitter (0-25% of the delay)
+  const jitter = exponentialDelay * Math.random() * 0.25;
+  return exponentialDelay + jitter;
+}
+
+// baseUrl and useProxy are resolved dynamically in the constructor
+// to respect LIVEKIT_REMOTE_EOT_URL environment variable
+export const interruptionOptionDefaults: Omit<InterruptionOptions, 'baseUrl' | 'useProxy'> = {
+  sampleRate: SAMPLE_RATE,
+  threshold: THRESHOLD,
+  minFrames: Math.ceil(MIN_INTERRUPTION_DURATION_IN_S * FRAMES_PER_SECOND),
+  maxAudioDurationInS: MAX_AUDIO_DURATION_IN_S,
+  audioPrefixDurationInS: AUDIO_PREFIX_DURATION_IN_S,
+  detectionIntervalInS: DETECTION_INTERVAL_IN_S,
+  inferenceTimeout: REMOTE_INFERENCE_TIMEOUT_IN_S * 1_000,
+  apiKey: process.env.LIVEKIT_API_KEY || '',
+  apiSecret: process.env.LIVEKIT_API_SECRET || '',
+  minInterruptionDurationInS: MIN_INTERRUPTION_DURATION_IN_S,
+} as const;