@livekit/agents 1.1.0 → 1.2.0

package/src/worker.ts

@@ -10,10 +10,11 @@ import {
   WorkerMessage,
   WorkerStatus,
 } from '@livekit/protocol';
-import { AccessToken, ParticipantInfo, RoomServiceClient } from 'livekit-server-sdk';
+import type { ParticipantInfo } from 'livekit-server-sdk';
+import { AccessToken, RoomServiceClient } from 'livekit-server-sdk';
 import { EventEmitter } from 'node:events';
-import os from 'node:os';
 import { WebSocket } from 'ws';
+import { getCpuMonitor } from './cpu.js';
 import { HTTPServer } from './http_server.js';
 import { InferenceRunner } from './inference_runner.js';
 import { InferenceProcExecutor } from './ipc/inference_proc_executor.js';
@@ -78,32 +79,11 @@ const defaultRequestFunc = async (ctx: JobRequest) => {
   await ctx.accept();
 };
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const defaultCpuLoad = async (worker: Worker): Promise<number> => {
-  return new Promise((resolve) => {
-    const cpus1 = os.cpus();
-
-    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 cpuMonitor = getCpuMonitor();
 
-        const total1 = Object.values(cpu1).reduce((acc, i) => acc + i, 0);
-        const total2 = Object.values(cpu2).reduce((acc, i) => acc + i, 0);
-
-        total += total2 - total1;
-      }
-
-      resolve(+(1 - idle / total).toFixed(2));
-    }, UPDATE_LOAD_INTERVAL);
-  });
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const defaultCpuLoad = async (_worker: AgentServer): Promise<number> => {
+  return cpuMonitor.cpuPercent(UPDATE_LOAD_INTERVAL);
 };
 
 /** Participant permissions to pass to every agent spun up by this worker. */
@@ -141,17 +121,17 @@ export class WorkerPermissions {
  *
  * This class is mostly useful in conjunction with {@link cli.runApp}.
  */
-export class WorkerOptions {
+export class ServerOptions {
   agent: string;
   requestFunc: (job: JobRequest) => Promise<void>;
-  loadFunc: (worker: Worker) => Promise<number>;
+  loadFunc: (worker: AgentServer) => Promise<number>;
   loadThreshold: number;
   numIdleProcesses: number;
   shutdownProcessTimeout: number;
   initializeProcessTimeout: number;
   permissions: WorkerPermissions;
   agentName: string;
-  workerType: JobType;
+  serverType: JobType;
   maxRetry: number;
   wsURL: string;
   apiKey?: string;
@@ -175,7 +155,7 @@ export class WorkerOptions {
     initializeProcessTimeout = 10 * 1000,
     permissions = new WorkerPermissions(),
     agentName = '',
-    workerType = JobType.JT_ROOM,
+    serverType = JobType.JT_ROOM,
     maxRetry = MAX_RECONNECT_ATTEMPTS,
     wsURL = 'ws://localhost:7880',
     apiKey = undefined,
@@ -195,7 +175,7 @@ export class WorkerOptions {
     agent: string;
     requestFunc?: (job: JobRequest) => Promise<void>;
     /** Called to determine the current load of the worker. Should return a value between 0 and 1. */
-    loadFunc?: (worker: Worker) => Promise<number>;
+    loadFunc?: (worker: AgentServer) => Promise<number>;
     /** When the load exceeds this threshold, the worker will be marked as unavailable. */
     loadThreshold?: number;
     numIdleProcesses?: number;
@@ -203,7 +183,7 @@ export class WorkerOptions {
     initializeProcessTimeout?: number;
     permissions?: WorkerPermissions;
     agentName?: string;
-    workerType?: JobType;
+    serverType?: JobType;
     maxRetry?: number;
     wsURL?: string;
     apiKey?: string;
@@ -228,7 +208,7 @@ export class WorkerOptions {
     this.initializeProcessTimeout = initializeProcessTimeout;
     this.permissions = permissions;
     this.agentName = agentName;
-    this.workerType = workerType;
+    this.serverType = serverType;
     this.maxRetry = maxRetry;
     this.wsURL = wsURL;
     this.apiKey = apiKey;
@@ -261,8 +241,8 @@ class PendingAssignment {
  * you don't have access to a command line, such as a headless program, or one that uses Agents
  * behind a wrapper.
  */
-export class Worker {
-  #opts: WorkerOptions;
+export class AgentServer {
+  #opts: ServerOptions;
   #procPool: ProcPool;
 
   #id = 'unregistered';
@@ -280,22 +260,22 @@ export class Worker {
   #inferenceExecutor?: InferenceProcExecutor;
 
   /* @throws {@link MissingCredentialsError} if URL, API key or API secret are missing */
-  constructor(opts: WorkerOptions) {
+  constructor(opts: ServerOptions) {
     opts.wsURL = opts.wsURL || process.env.LIVEKIT_URL || '';
     opts.apiKey = opts.apiKey || process.env.LIVEKIT_API_KEY || '';
     opts.apiSecret = opts.apiSecret || process.env.LIVEKIT_API_SECRET || '';
 
     if (opts.wsURL === '')
       throw new MissingCredentialsError(
-        'URL is required: Set LIVEKIT_URL, run with --url, or pass wsURL in WorkerOptions',
+        'URL is required: Set LIVEKIT_URL, run with --url, or pass wsURL in ServerOptions',
       );
     if (opts.apiKey === '')
       throw new MissingCredentialsError(
-        'API Key is required: Set LIVEKIT_API_KEY, run with --api-key, or pass apiKey in WorkerOptions',
+        'API Key is required: Set LIVEKIT_API_KEY, run with --api-key, or pass apiKey in ServerOptions',
       );
     if (opts.apiSecret === '')
       throw new MissingCredentialsError(
-        'API Secret is required: Set LIVEKIT_API_SECRET, run with --api-secret, or pass apiSecret in WorkerOptions',
+        'API Secret is required: Set LIVEKIT_API_SECRET, run with --api-secret, or pass apiSecret in ServerOptions',
       );
 
     if (opts.workerToken) {
@@ -338,16 +318,38 @@ export class Worker {
     );
 
     this.#opts = opts;
-    this.#httpServer = new HTTPServer(opts.host, opts.port, () => ({
+
+    const healthCheck = () => {
+      // Check if inference executor exists and is not alive
+      if (this.#inferenceExecutor && !this.#inferenceExecutor.isAlive) {
+        return { healthy: false, message: 'inference process not running' };
+      }
+
+      // Only healthy when fully connected with an active WebSocket
+      if (
+        this.#closed ||
+        this.#connecting ||
+        !this.#session ||
+        this.#session.readyState !== WebSocket.OPEN
+      ) {
+        return { healthy: false, message: 'not connected to livekit' };
+      }
+
+      return { healthy: true, message: 'OK' };
+    };
+
+    const getWorkerInfo = () => ({
       agent_name: opts.agentName,
-      worker_type: JobType[opts.workerType],
+      worker_type: JobType[opts.serverType],
       active_jobs: this.activeJobs.length,
       sdk_version: version,
       project_type: PROJECT_TYPE,
-    }));
+    });
+
+    this.#httpServer = new HTTPServer(opts.host, opts.port, healthCheck, getWorkerInfo);
   }
 
-  /* @throws {@link WorkerError} if worker failed to connect or already running */
+  /** @throws {@link WorkerError} if worker failed to connect or already running */
   async run() {
     if (!this.#closed) {
       throw new WorkerError('worker is already running');
@@ -383,7 +385,7 @@ export class Worker {
         try {
           await new Promise((resolve, reject) => {
             this.#session!.on('open', resolve);
-            this.#session!.on('error', (error) => reject(error.message));
+            this.#session!.on('error', (error) => reject(error));
             this.#session!.on('close', (code) => reject(`WebSocket returned ${code}`));
           });
 
@@ -391,14 +393,10 @@ export class Worker {
           this.#logger.debug('connected to LiveKit server');
           await this.#runWS(this.#session);
         } catch (e: unknown) {
-          if (e instanceof Error || e instanceof ErrorEvent) {
-            e = e.message;
-          }
-
           if (this.#closed) return;
           if (retries >= this.#opts.maxRetry) {
             throw new WorkerError(
-              `failed to connect to LiveKit server after ${retries} attempts: ${e}`,
+              `failed to connect to LiveKit server (${this.#opts.wsURL}) after ${retries} attempts: ${e}`,
             );
           }
 
@@ -406,7 +404,8 @@ export class Worker {
           const delay = Math.min(retries * 2, 10);
 
           this.#logger.warn(
-            `failed to connect to LiveKit server, retrying in ${delay} seconds: ${e} (${retries}/${this.#opts.maxRetry})`,
+            e,
+            `failed to connect to LiveKit server (${this.#opts.wsURL}), retrying in ${delay} seconds: (${retries}/${this.#opts.maxRetry})`,
           );
 
           await new Promise((resolve) => setTimeout(resolve, delay * 1000));
@@ -428,7 +427,7 @@ export class Worker {
       .map((proc) => proc.runningJob!);
   }
 
-  /* @throws {@link WorkerError} if worker did not drain in time */
+  /** @throws {@link WorkerError} if worker did not drain in time */
   async drain(timeout?: number) {
     if (this.#draining) {
       return;
@@ -610,7 +609,7 @@ export class Worker {
         message: {
           case: 'register',
           value: {
-            type: this.#opts.workerType,
+            type: this.#opts.serverType,
             agentName: this.#opts.agentName,
             allowedPermissions: new ParticipantPermission({
               canPublish: this.#opts.permissions.canPublish,
@@ -631,33 +630,38 @@ export class Worker {
       if (closingWS) clearInterval(loadMonitor);
 
       const oldStatus = currentStatus;
-      this.#opts.loadFunc(this).then((currentLoad: number) => {
-        const isFull = currentLoad >= this.#opts.loadThreshold;
-        const currentlyAvailable = !isFull;
-        currentStatus = currentlyAvailable ? WorkerStatus.WS_AVAILABLE : WorkerStatus.WS_FULL;
-
-        if (oldStatus != currentStatus) {
-          const extra = { load: currentLoad, loadThreshold: this.#opts.loadThreshold };
-          if (isFull) {
-            this.#logger.child(extra).info('worker is at full capacity, marking as unavailable');
-          } else {
-            this.#logger.child(extra).info('worker is below capacity, marking as available');
+      this.#opts
+        .loadFunc(this)
+        .then((currentLoad: number) => {
+          const isFull = currentLoad >= this.#opts.loadThreshold;
+          const currentlyAvailable = !isFull;
+          currentStatus = currentlyAvailable ? WorkerStatus.WS_AVAILABLE : WorkerStatus.WS_FULL;
+
+          if (oldStatus != currentStatus) {
+            const extra = { load: currentLoad, loadThreshold: this.#opts.loadThreshold };
+            if (isFull) {
+              this.#logger.child(extra).info('worker is at full capacity, marking as unavailable');
+            } else {
+              this.#logger.child(extra).info('worker is below capacity, marking as available');
+            }
           }
-        }
 
-        this.event.emit(
-          'worker_msg',
-          new WorkerMessage({
-            message: {
-              case: 'updateWorker',
-              value: {
-                load: currentLoad,
-                status: currentStatus,
+          this.event.emit(
+            'worker_msg',
+            new WorkerMessage({
+              message: {
+                case: 'updateWorker',
+                value: {
+                  load: currentLoad,
+                  status: currentStatus,
+                },
               },
-            },
-          }),
-        );
-      });
+            }),
+          );
+        })
+        .catch((e) => {
+          this.#logger.warn({ error: e }, 'failed to measure CPU load');
+        });
     }, UPDATE_LOAD_INTERVAL);
 
     await close;
@@ -728,7 +732,7 @@ export class Worker {
 
     const req = new JobRequest(msg.job!, onReject, onAccept);
     this.#logger
-      .child({ job: msg.job, resuming: msg.resuming, agentName: this.#opts.agentName })
+      .child({ jobId: msg.job?.id, resuming: msg.resuming, agentName: this.#opts.agentName })
       .info('received job request');
 
     const jobRequestTask = async () => {
@@ -788,3 +792,13 @@ export class Worker {
     await this.#close.await;
   }
 }
+
+/**
+ * @deprecated Use {@link AgentServer} instead. This alias is provided for backward compatibility.
+ */
+export const Worker = AgentServer;
+
+/**
+ * @deprecated Use {@link ServerOptions} instead. This alias is provided for backward compatibility.
+ */
+export const WorkerOptions = ServerOptions;

package/src/llm/__snapshots__/utils.test.ts.snap

@@ -1,65 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`oaiParams > common types 1`] = `
-{
-  "additionalProperties": false,
-  "properties": {
-    "address": {
-      "additionalProperties": false,
-      "properties": {
-        "city": {
-          "type": "string",
-        },
-        "state": {
-          "type": "string",
-        },
-        "street": {
-          "type": "string",
-        },
-        "zip": {
-          "type": "string",
-        },
-      },
-      "required": [
-        "street",
-        "city",
-        "state",
-        "zip",
-      ],
-      "type": "object",
-    },
-    "age": {
-      "type": "number",
-    },
-    "favoriteColor": {
-      "enum": [
-        "red",
-        "green",
-        "blue",
-      ],
-      "type": "string",
-    },
-    "hobbies": {
-      "items": {
-        "type": "string",
-      },
-      "type": "array",
-    },
-    "isStudent": {
-      "type": "boolean",
-    },
-    "name": {
-      "type": "string",
-    },
-  },
-  "required": [
-    "name",
-    "age",
-    "isStudent",
-    "hobbies",
-    "favoriteColor",
-    "address",
-  ],
-  "type": "object",
-}
-`;