@livekit/agents 1.1.0 → 1.2.0

package/src/inference/utils.ts

@@ -3,9 +3,37 @@
 // SPDX-License-Identifier: Apache-2.0
 import { AccessToken } from 'livekit-server-sdk';
 import { WebSocket } from 'ws';
-import { APIConnectionError, APIStatusError } from '../index.js';
+import { APIConnectionError, APIStatusError } from '../_exceptions.js';
 
-export type AnyModels = string & NonNullable<unknown>;
+export type AnyString = string & NonNullable<unknown>;
+
+/** Default production inference URL */
+export const DEFAULT_INFERENCE_URL = 'https://agent-gateway.livekit.cloud/v1';
+
+/** Staging inference URL */
+export const STAGING_INFERENCE_URL = 'https://agent-gateway.staging.livekit.cloud/v1';
+
+/**
+ * Get the default inference URL based on the environment.
+ *
+ * Priority:
+ * 1. LIVEKIT_INFERENCE_URL if set
+ * 2. If LIVEKIT_URL contains '.staging.livekit.cloud', use staging gateway
+ * 3. Otherwise, use production gateway
+ */
+export function getDefaultInferenceUrl(): string {
+  const inferenceUrl = process.env.LIVEKIT_INFERENCE_URL;
+  if (inferenceUrl) {
+    return inferenceUrl;
+  }
+
+  const livekitUrl = process.env.LIVEKIT_URL || '';
+  if (livekitUrl.includes('.staging.livekit.cloud')) {
+    return STAGING_INFERENCE_URL;
+  }
+
+  return DEFAULT_INFERENCE_URL;
+}
 
 export async function createAccessToken(
   apiKey: string,

package/src/ipc/inference_proc_executor.ts

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { ChildProcess } from 'node:child_process';
 import { fork } from 'node:child_process';
+import { extname } from 'node:path';
 import { log } from '../log.js';
 import { shortuuid } from '../utils.js';
 import type { InferenceExecutor } from './inference_executor.js';
@@ -18,6 +19,8 @@ class PendingInference {
   }
 }
 
+const currentFileExtension = extname(import.meta.url);
+
 export class InferenceProcExecutor extends SupervisedProc implements InferenceExecutor {
   #runners: { [id: string]: string };
   #activeRequests: { [id: string]: PendingInference } = {};
@@ -55,9 +58,14 @@ export class InferenceProcExecutor extends SupervisedProc implements InferenceEx
   }
 
   createProcess(): ChildProcess {
-    return fork(new URL('./inference_proc_lazy_main.js', import.meta.url), [
-      JSON.stringify(this.#runners),
-    ]);
+    const forkUrl = new URL(`./inference_proc_lazy_main${currentFileExtension}`, import.meta.url);
+
+    // When running via tsx/ts-node (TypeScript files), we need to inherit the parent's
+    // execArgv so the child process can also execute TypeScript with the same loader
+    const isTypeScript = currentFileExtension === '.ts';
+    const forkOptions = isTypeScript ? { execArgv: process.execArgv } : undefined;
+
+    return fork(forkUrl, [JSON.stringify(this.#runners)], forkOptions);
   }
 
   async mainTask(proc: ChildProcess) {

package/src/ipc/inference_proc_lazy_main.ts

@@ -36,7 +36,19 @@ const ORPHANED_TIMEOUT = 15 * 1000;
 
     const runners: { [id: string]: InferenceRunner } = await Promise.all(
       Object.entries(JSON.parse(process.argv[2]!)).map(async ([k, v]) => {
-        return [k, await import(v as string).then((m) => new m.default())];
+        return [
+          k,
+          await import(v as string).then((m) => {
+            // Handle both ESM (m.default is the class) and CJS (m.default.default is the class)
+            const Runner = typeof m.default === 'function' ? m.default : m.default?.default;
+            if (typeof Runner !== 'function') {
+              throw new Error(
+                `Unable to load inference runner: Missing or invalid default export in ${v}`,
+              );
+            }
+            return new Runner();
+          }),
+        ];
       }),
     ).then(Object.fromEntries);
 

package/src/ipc/job_proc_executor.ts

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import type { ChildProcess } from 'node:child_process';
 import { fork } from 'node:child_process';
+import { extname } from 'node:path';
 import type { RunningJobInfo } from '../job.js';
 import { log } from '../log.js';
 import type { InferenceExecutor } from './inference_executor.js';
@@ -11,6 +12,8 @@ import { JobStatus } from './job_executor.js';
 import type { IPCMessage } from './message.js';
 import { SupervisedProc } from './supervised_proc.js';
 
+const currentFileExtension = extname(import.meta.url);
+
 export class JobProcExecutor extends SupervisedProc implements JobExecutor {
   #userArgs?: any; // eslint-disable-line @typescript-eslint/no-explicit-any
   #jobStatus?: JobStatus;
@@ -64,7 +67,14 @@ export class JobProcExecutor extends SupervisedProc implements JobExecutor {
   }
 
   createProcess(): ChildProcess {
-    return fork(new URL('./job_proc_lazy_main.js', import.meta.url), [this.#agent]);
+    const forkUrl = new URL(`./job_proc_lazy_main${currentFileExtension}`, import.meta.url);
+
+    // When running via tsx/ts-node (TypeScript files), we need to inherit the parent's
+    // execArgv so the child process can also execute TypeScript with the same loader
+    const isTypeScript = currentFileExtension === '.ts';
+    const forkOptions = isTypeScript ? { execArgv: process.execArgv } : undefined;
+
+    return fork(forkUrl, [this.#agent], forkOptions);
   }
 
   async mainTask(proc: ChildProcess) {

package/src/ipc/job_proc_lazy_main.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { Room, RoomEvent } from '@livekit/rtc-node';
+import { Room, RoomEvent, dispose } from '@livekit/rtc-node';
 import { EventEmitter, once } from 'node:events';
 import { pathToFileURL } from 'node:url';
 import type { Logger } from 'pino';
@@ -15,6 +15,25 @@ import type { IPCMessage } from './message.js';
 
 const ORPHANED_TIMEOUT = 15 * 1000;
 
+const safeSend = (msg: IPCMessage): boolean => {
+  try {
+    if (process.connected && process.send) {
+      process.send(msg);
+      return true;
+    }
+    return false;
+  } catch (error) {
+    // Channel closed is expected during graceful shutdown
+    // Log at debug level to avoid noise in production logs
+    if (error instanceof Error && error.message.includes('Channel closed')) {
+      log().debug({ msgCase: msg.case }, 'IPC channel closed, message not sent');
+    } else {
+      log().error({ error, msgCase: msg.case }, 'IPC send failed unexpectedly');
+    }
+    return false;
+  }
+};
+
 type JobTask = {
   ctx: JobContext;
   task: Promise<void>;
@@ -50,7 +69,10 @@ class InfClient implements InferenceExecutor {
 
   async doInference(method: string, data: unknown): Promise<unknown> {
     const requestId = shortuuid('inference_job_');
-    process.send!({ case: 'inferenceRequest', value: { requestId, method, data } });
+    if (!safeSend({ case: 'inferenceRequest', value: { requestId, method, data } })) {
+      throw new Error('IPC channel closed');
+    }
+
     this.#requests[requestId] = new PendingInference();
     const resp = await this.#requests[requestId]!.promise;
     if (resp.error) {
@@ -88,7 +110,7 @@ const startJob = (
 
   const ctx = new JobContext(proc, info, room, onConnect, onShutdown, new InfClient());
 
-  const task = new Promise<void>(async () => {
+  const task = (async () => {
     const unconnectedTimeout = setTimeout(() => {
       if (!(connect || shutdown)) {
         logger.warn(
@@ -98,16 +120,44 @@ const startJob = (
       }
     }, 10000);
 
-    // Run the job function within the AsyncLocalStorage context
-    await runWithJobContextAsync(ctx, () => func(ctx)).finally(() => {
-      clearTimeout(unconnectedTimeout);
-    });
-
-    await once(closeEvent, 'close').then((close) => {
-      logger.debug('shutting down');
+    try {
+      // Run the job function within the AsyncLocalStorage context
+      await runWithJobContextAsync(ctx, async () => {
+        const { tracer, traceTypes } = await import('../telemetry/index.js');
+        return tracer.startActiveSpan(
+          async (span) => {
+            span.setAttribute(traceTypes.ATTR_JOB_ID, info.job.id);
+            span.setAttribute(traceTypes.ATTR_AGENT_NAME, info.job.agentName);
+            span.setAttribute(traceTypes.ATTR_ROOM_NAME, info.job.room?.name ?? '');
+            return func(ctx);
+          },
+          { name: 'job_entrypoint' },
+        );
+      }).finally(() => {
+        clearTimeout(unconnectedTimeout);
+      });
+
+      await once(closeEvent, 'close').then((close) => {
+        logger.debug('shutting down');
+        shutdown = true;
+        safeSend({ case: 'exiting', value: { reason: close[1] } });
+      });
+    } catch (error) {
+      logger.error({ error }, 'error in entry function');
       shutdown = true;
-      process.send!({ case: 'exiting', value: { reason: close[1] } });
-    });
+      safeSend({
+        case: 'exiting',
+        value: { reason: error instanceof Error ? error.message : String(error) },
+      });
+    }
+
+    // Close the primary agent session if it exists
+    if (ctx._primaryAgentSession) {
+      await ctx._primaryAgentSession.close();
+    }
+
+    // Generate and save/upload session report
+    await ctx._onSessionEnd();
 
     await room.disconnect();
     logger.debug('disconnected from room');
@@ -117,12 +167,12 @@ const startJob = (
       shutdownTasks.push(callback());
     }
     await Promise.all(shutdownTasks).catch((error) =>
-      logger.error('error while shutting down the job', error),
+      logger.error({ error }, 'error while shutting down the job'),
     );
 
-    process.send!({ case: 'done' });
+    safeSend({ case: 'done', value: undefined });
     joinFuture.resolve();
-  });
+  })();
 
   return { ctx, task };
 };
@@ -137,7 +187,11 @@ const startJob = (
     //   [2] import.meta.filename of function containing entry file
     const moduleFile = process.argv[2];
     const agent: Agent = await import(pathToFileURL(moduleFile!).pathname).then((module) => {
-      const agent = module.default;
+      // Handle both ESM (module.default is the agent) and CJS (module.default.default is the agent)
+      const agent =
+        typeof module.default === 'function' || isAgent(module.default)
+          ? module.default
+          : module.default?.default;
       if (agent === undefined || !isAgent(agent)) {
         throw new Error(`Unable to load agent: Missing or invalid default export in ${moduleFile}`);
       }
@@ -170,13 +224,13 @@ const startJob = (
     let logger = log().child({ pid: proc.pid });
 
     process.on('unhandledRejection', (reason) => {
-      logger.error(reason);
+      logger.debug({ error: reason }, 'Unhandled promise rejection');
     });
 
     logger.debug('initializing job runner');
-    agent.prewarm(proc);
+    await agent.prewarm(proc);
     logger.debug('job runner initialized');
-    process.send({ case: 'initializeResponse' });
+    safeSend({ case: 'initializeResponse', value: undefined });
 
     let job: JobTask | undefined = undefined;
     const closeEvent = new EventEmitter();
@@ -190,7 +244,7 @@ const startJob = (
       switch (msg.case) {
         case 'pingRequest': {
           orphanedTimeout.refresh();
-          process.send!({
+          safeSend({
             case: 'pongResponse',
             value: { lastTimestamp: msg.value.timestamp, timestamp: Date.now() },
           });
@@ -222,6 +276,18 @@ const startJob = (
 
     await join.await;
 
+    // Dispose native FFI resources (Rust FfiServer, tokio runtimes, libwebrtc)
+    // before process.exit() to prevent libc++abi mutex crash during teardown.
+    // Without this, process.exit() can kill the process while native threads are
+    // still running, causing: "mutex lock failed: Invalid argument"
+    // See: https://github.com/livekit/node-sdks/issues/564
+    try {
+      await dispose();
+      logger.debug('native resources disposed');
+    } catch (error) {
+      logger.warn({ error }, 'failed to dispose native resources');
+    }
+
     logger.debug('Job process shutdown');
     process.exit(0);
   }

package/src/ipc/supervised_proc.test.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2024 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { fork, spawn } from 'node:child_process';
+import { unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import pidusage from 'pidusage';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const childScript = join(tmpdir(), 'test_child.mjs');
+
+beforeAll(() => {
+  writeFileSync(
+    childScript,
+    `process.on('message', (msg) => process.send?.({ echo: msg }));
+     setInterval(() => {}, 1000);`,
+  );
+});
+
+afterAll(() => {
+  try {
+    unlinkSync(childScript);
+  } catch {}
+});
+
+async function getChildMemoryUsageMB(pid: number | undefined): Promise<number> {
+  if (!pid) return 0;
+  try {
+    const stats = await pidusage(pid);
+    return stats.memory / (1024 * 1024);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT' || code === 'ESRCH') {
+      return 0;
+    }
+    throw err;
+  }
+}
+
+describe('pidusage on dead process', () => {
+  it('raw pidusage throws on dead pid', async () => {
+    const child = spawn('sleep', ['10']);
+    const pid = child.pid!;
+
+    child.kill('SIGKILL');
+    await new Promise<void>((r) => child.on('exit', r));
+
+    await expect(pidusage(pid)).rejects.toThrow();
+  });
+
+  it('fixed version returns 0 instead of crashing', async () => {
+    const child = spawn('sleep', ['10']);
+    const pid = child.pid!;
+
+    child.kill('SIGKILL');
+    await new Promise<void>((r) => child.on('exit', r));
+
+    const mem = await getChildMemoryUsageMB(pid);
+    expect(mem).toBe(0);
+  });
+
+  it('handles concurrent calls on dying process', async () => {
+    const child = spawn('sleep', ['10']);
+    const pid = child.pid!;
+    const exitPromise = new Promise<void>((r) => child.on('exit', r));
+
+    child.kill('SIGKILL');
+
+    const results = await Promise.all([
+      getChildMemoryUsageMB(pid),
+      getChildMemoryUsageMB(pid),
+      getChildMemoryUsageMB(pid),
+    ]);
+
+    await exitPromise;
+    expect(results.every((r) => r === 0)).toBe(true);
+  });
+});
+
+describe('IPC send on dead process', () => {
+  it('child.connected becomes false when child dies', async () => {
+    const child = fork(childScript, [], { stdio: ['pipe', 'pipe', 'pipe', 'ipc'] });
+    const exitPromise = new Promise<void>((r) => child.on('exit', r));
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(child.connected).toBe(true);
+
+    child.kill('SIGKILL');
+    await exitPromise;
+
+    expect(child.connected).toBe(false);
+  });
+
+  it('checking connected before send prevents crash', async () => {
+    const child = fork(childScript, [], { stdio: ['pipe', 'pipe', 'pipe', 'ipc'] });
+    const exitPromise = new Promise<void>((r) => child.on('exit', r));
+
+    // Suppress EPIPE errors that can occur due to race conditions between
+    // child.connected check and the actual pipe state
+    child.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code !== 'EPIPE') throw err;
+    });
+
+    let sent = 0;
+    let skipped = 0;
+
+    const interval = setInterval(() => {
+      if (child.connected) {
+        child.send({ ping: Date.now() });
+        sent++;
+      } else {
+        skipped++;
+      }
+    }, 20);
+
+    await new Promise((r) => setTimeout(r, 60));
+    child.kill('SIGKILL');
+    await exitPromise;
+    await new Promise((r) => setTimeout(r, 80));
+    clearInterval(interval);
+
+    expect(sent).toBeGreaterThan(0);
+    expect(skipped).toBeGreaterThan(0);
+  });
+});
+
+describe('timer cleanup', () => {
+  it('clearInterval stops the interval', async () => {
+    let count = 0;
+    const interval = setInterval(() => count++, 30);
+
+    await new Promise((r) => setTimeout(r, 80));
+    const countAtClear = count;
+    clearInterval(interval);
+
+    await new Promise((r) => setTimeout(r, 80));
+    expect(count).toBe(countAtClear);
+  });
+
+  it('double clear is safe', () => {
+    const interval = setInterval(() => {}, 100);
+    const timeout = setTimeout(() => {}, 1000);
+
+    clearInterval(interval);
+    clearTimeout(timeout);
+
+    expect(() => {
+      clearInterval(interval);
+      clearTimeout(timeout);
+    }).not.toThrow();
+  });
+});

package/src/ipc/supervised_proc.ts

@@ -10,12 +10,19 @@ import { Future } from '../utils.js';
 import type { IPCMessage } from './message.js';
 
 export interface ProcOpts {
+  /** Timeout for process initialization in milliseconds. */
   initializeTimeout: number;
+  /** Timeout for process shutdown in milliseconds. */
   closeTimeout: number;
+  /** Memory usage warning threshold in megabytes. */
   memoryWarnMB: number;
+  /** Memory usage limit in megabytes. */
   memoryLimitMB: number;
+  /** Interval for health check pings in milliseconds. */
   pingInterval: number;
+  /** Timeout waiting for pong response in milliseconds. */
   pingTimeout: number;
+  /** Threshold for warning about unresponsive processes in milliseconds. */
   highPingThreshold: number;
 }
 
@@ -59,6 +66,10 @@ export abstract class SupervisedProc {
     return this.#started;
   }
 
+  get isAlive(): boolean {
+    return this.#started && !this.#closing && !!this.proc?.connected;
+  }
+
   get runningJob(): RunningJobInfo | undefined {
     return this.#runningJob;
   }
@@ -80,7 +91,9 @@ export abstract class SupervisedProc {
     await this.init.await;
 
     this.#pingInterval = setInterval(() => {
-      this.proc!.send({ case: 'pingRequest', value: { timestamp: Date.now() } });
+      if (this.proc?.connected) {
+        this.proc.send({ case: 'pingRequest', value: { timestamp: Date.now() } });
+      }
     }, this.#opts.pingInterval);
 
     this.#pongTimeout = setTimeout(() => {
@@ -141,6 +154,7 @@ export abstract class SupervisedProc {
     });
 
     this.proc!.on('exit', () => {
+      this.clearTimers();
       this.#join.resolve();
     });
 
@@ -159,14 +173,16 @@ export abstract class SupervisedProc {
 
   async initialize() {
     const timer = setTimeout(() => {
-      const err = new Error('runner initialization timed out');
-      this.init.reject(err);
-      throw err;
+      this.init.reject(new Error('runner initialization timed out'));
     }, this.#opts.initializeTimeout);
-    this.proc!.send({
+    if (!this.proc?.connected) {
+      this.init.reject(new Error('process not connected'));
+      return;
+    }
+    this.proc.send({
       case: 'initializeRequest',
       value: {
-        loggerOptions,
+        loggerOptions: loggerOptions(),
         pingInterval: this.#opts.pingInterval,
         pingTimeout: this.#opts.pingTimeout,
         highPingThreshold: this.#opts.highPingThreshold,
@@ -187,7 +203,9 @@ export abstract class SupervisedProc {
     }
     this.#closing = true;
 
-    this.proc!.send({ case: 'shutdownRequest' });
+    if (this.proc?.connected) {
+      this.proc.send({ case: 'shutdownRequest' });
+    }
 
     const timer = setTimeout(() => {
       this.#logger.error('job shutdown is taking too much time');
@@ -203,8 +221,11 @@ export abstract class SupervisedProc {
     if (this.#runningJob) {
       throw new Error('executor already has a running job');
     }
+    if (!this.proc?.connected) {
+      throw new Error('process not connected');
+    }
     this.#runningJob = info;
-    this.proc!.send({ case: 'startJobRequest', value: { runningJob: info } });
+    this.proc.send({ case: 'startJobRequest', value: { runningJob: info } });
   }
 
   private async getChildMemoryUsageMB(): Promise<number> {
@@ -212,8 +233,16 @@ export abstract class SupervisedProc {
     if (!pid) {
       return 0;
     }
-    const stats = await pidusage(pid);
-    return stats.memory / (1024 * 1024); // Convert bytes to MB
+    try {
+      const stats = await pidusage(pid);
+      return stats.memory / (1024 * 1024);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || code === 'ESRCH') {
+        return 0;
+      }
+      throw err;
+    }
   }
 
   private clearTimers() {