@livekit/agents 1.0.47 → 1.0.49

package/src/beta/workflows/task_group.ts

@@ -0,0 +1,194 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import type { ChatContext } from '../../llm/chat_context.js';
+import { LLM, ToolError, ToolFlag, tool } from '../../llm/index.js';
+import { AgentTask } from '../../voice/agent.js';
+
+interface FactoryInfo {
+  taskFactory: () => AgentTask;
+  id: string;
+  description: string;
+}
+
+export interface TaskGroupResult {
+  taskResults: Record<string, unknown>;
+}
+
+export interface TaskCompletedEvent {
+  agentTask: AgentTask;
+  taskId: string;
+  result: unknown;
+}
+
+class OutOfScopeError extends ToolError {
+  readonly targetTaskIds: string[];
+
+  constructor(targetTaskIds: string[]) {
+    super('out_of_scope');
+    this.targetTaskIds = targetTaskIds;
+  }
+}
+
+export interface TaskGroupOptions {
+  summarizeChatCtx?: boolean;
+  returnExceptions?: boolean;
+  chatCtx?: ChatContext;
+  onTaskCompleted?: (event: TaskCompletedEvent) => Promise<void>;
+}
+
+export class TaskGroup extends AgentTask<TaskGroupResult> {
+  private _summarizeChatCtx: boolean;
+  private _returnExceptions: boolean;
+  private _visitedTasks = new Set<string>();
+  private _registeredFactories = new Map<string, FactoryInfo>();
+  private _taskCompletedCallback?: (event: TaskCompletedEvent) => Promise<void>;
+  private _currentTask?: AgentTask;
+
+  constructor(options: TaskGroupOptions = {}) {
+    const { summarizeChatCtx = true, returnExceptions = false, chatCtx, onTaskCompleted } = options;
+
+    super({ instructions: '*empty*', chatCtx });
+
+    this._summarizeChatCtx = summarizeChatCtx;
+    this._returnExceptions = returnExceptions;
+    this._taskCompletedCallback = onTaskCompleted;
+  }
+
+  add(task: () => AgentTask, { id, description }: { id: string; description: string }): this {
+    this._registeredFactories.set(id, { taskFactory: task, id, description });
+    return this;
+  }
+
+  async onEnter(): Promise<void> {
+    const taskStack = [...this._registeredFactories.keys()];
+    const taskResults: Record<string, unknown> = {};
+
+    while (taskStack.length > 0) {
+      const taskId = taskStack.shift()!;
+      const factoryInfo = this._registeredFactories.get(taskId)!;
+
+      this._currentTask = factoryInfo.taskFactory();
+
+      const sharedChatCtx = this._chatCtx.copy();
+      await this._currentTask.updateChatCtx(sharedChatCtx);
+
+      const outOfScopeTool = this.buildOutOfScopeTool(taskId);
+      if (outOfScopeTool) {
+        await this._currentTask.updateTools({
+          ...this._currentTask.toolCtx,
+          out_of_scope: outOfScopeTool,
+        });
+      }
+
+      try {
+        this._visitedTasks.add(taskId);
+        const res = await this._currentTask.run();
+        taskResults[taskId] = res;
+
+        if (this._taskCompletedCallback) {
+          await this._taskCompletedCallback({
+            agentTask: this._currentTask,
+            taskId,
+            result: res,
+          });
+        }
+      } catch (e) {
+        if (e instanceof OutOfScopeError) {
+          taskStack.unshift(taskId);
+          for (let i = e.targetTaskIds.length - 1; i >= 0; i--) {
+            taskStack.unshift(e.targetTaskIds[i]!);
+          }
+          continue;
+        }
+
+        if (this._returnExceptions) {
+          taskResults[taskId] = e;
+          continue;
+        } else {
+          this.complete(e instanceof Error ? e : new Error(String(e)));
+          return;
+        }
+      }
+    }
+
+    try {
+      if (this._summarizeChatCtx) {
+        const sessionLlm = this.session.llm;
+        if (!(sessionLlm instanceof LLM)) {
+          throw new Error('summarizeChatCtx requires a standard LLM on the session');
+        }
+
+        // TODO(parity): Add excludeConfigUpdate when AgentConfigUpdate is ported
+        const ctxToSummarize = this._chatCtx.copy({
+          excludeInstructions: true,
+          excludeHandoff: true,
+          excludeEmptyMessage: true,
+          excludeFunctionCall: true,
+        });
+
+        const summarizedChatCtx = await ctxToSummarize._summarize(sessionLlm, {
+          keepLastTurns: 0,
+        });
+        await this.updateChatCtx(summarizedChatCtx);
+      }
+    } catch (e) {
+      this.complete(new Error(`failed to summarize the chat_ctx: ${e}`));
+      return;
+    }
+
+    this.complete({ taskResults });
+  }
+
+  private buildOutOfScopeTool(activeTaskId: string) {
+    if (this._visitedTasks.size === 0) {
+      return undefined;
+    }
+
+    const regressionTaskIds = new Set(this._visitedTasks);
+    regressionTaskIds.delete(activeTaskId);
+
+    if (regressionTaskIds.size === 0) {
+      return undefined;
+    }
+
+    const taskRepr: Record<string, string> = {};
+    for (const [id, info] of this._registeredFactories) {
+      if (regressionTaskIds.has(id)) {
+        taskRepr[id] = info.description;
+      }
+    }
+
+    const taskIdValues = [...regressionTaskIds] as [string, ...string[]];
+
+    const description =
+      'Call to regress to other tasks according to what the user requested to modify, return the corresponding task ids. ' +
+      'For example, if the user wants to change their email and there is a task with id "email_task" with a description of "Collect the user\'s email", return the id ("get_email_task"). ' +
+      'If the user requests to regress to multiple tasks, such as changing their phone number and email, return both task ids in the order they were requested. ' +
+      `The following are the IDs and their corresponding task description. ${JSON.stringify(taskRepr)}`;
+
+    const currentTask = this._currentTask;
+    const registeredFactories = this._registeredFactories;
+    const visitedTasks = this._visitedTasks;
+
+    return tool({
+      description,
+      flags: ToolFlag.IGNORE_ON_ENTER,
+      parameters: z.object({
+        task_ids: z.array(z.enum(taskIdValues)).describe('The IDs of the tasks requested'),
+      }),
+      execute: async ({ task_ids }: { task_ids: string[] }) => {
+        for (const tid of task_ids) {
+          if (!registeredFactories.has(tid) || !visitedTasks.has(tid)) {
+            throw new ToolError(`Unable to regress, invalid task id ${tid}`);
+          }
+        }
+
+        if (currentTask && !currentTask.done) {
+          currentTask.complete(new OutOfScopeError(task_ids));
+        }
+      },
+    });
+  }
+}

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/index.ts

@@ -9,6 +9,7 @@
  * @see {@link https://docs.livekit.io/agents/overview | LiveKit Agents documentation}
  * @packageDocumentation
  */
+import * as beta from './beta/index.js';
 import * as cli from './cli.js';
 import * as inference from './inference/index.js';
 import * as ipc from './ipc/index.js';
@@ -37,4 +38,4 @@ export * from './version.js';
 export { createTimedString, isTimedString, type TimedString } from './voice/io.js';
 export * from './worker.js';
 
-export { cli, inference, ipc, llm, metrics, stream, stt, telemetry, tokenize, tts, voice };
+export { beta, cli, inference, ipc, llm, metrics, stream, stt, telemetry, tokenize, tts, voice };

package/src/inference/llm.ts

@@ -17,6 +17,8 @@ import { type AnyString, createAccessToken } from './utils.js';
 const DEFAULT_BASE_URL = 'https://agent-gateway.livekit.cloud/v1';
 
 export type OpenAIModels =
+  | 'openai/gpt-5.4'
+  | 'openai/gpt-5.3-chat-latest'
   | 'openai/gpt-5.2'
   | 'openai/gpt-5.2-chat-latest'
   | 'openai/gpt-5.1'

package/src/inference/tts.ts

@@ -62,7 +62,14 @@ export interface DeepgramTTSOptions {}
 
 export interface RimeOptions {}
 
-export interface InworldOptions {}
+export interface InworldOptions {
+  /** Controls how fast the voice speaks. 1.0 is normal speed, 0.5 is half, 1.5 is 1.5x. Default: 1.0. */
+  speaking_rate?: number;
+  /** Controls randomness in the output. Recommended between 0.6 and 1.1. Default: 1.1. */
+  temperature?: number;
+  /** Controls text normalization. "ON" expands numbers, dates, abbreviations. "OFF" reads text as written. Default: "ON". */
+  text_normalization?: 'ON' | 'OFF';
+}
 
 type _TTSModels =
   | CartesiaModels