@livekit/agents 0.0.0-20260120144724

package/dist/job.cjs

@@ -0,0 +1,373 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var job_exports = {};
+__export(job_exports, {
+  AutoSubscribe: () => AutoSubscribe,
+  FunctionExistsError: () => FunctionExistsError,
+  JobContext: () => JobContext,
+  JobProcess: () => JobProcess,
+  JobRequest: () => JobRequest,
+  getJobContext: () => getJobContext,
+  runWithJobContext: () => runWithJobContext,
+  runWithJobContextAsync: () => runWithJobContextAsync
+});
+module.exports = __toCommonJS(job_exports);
+var import_rtc_node = require("@livekit/rtc-node");
+var import_node_async_hooks = require("node:async_hooks");
+var os = __toESM(require("node:os"), 1);
+var path = __toESM(require("node:path"), 1);
+var import_log = require("./log.cjs");
+var import_telemetry = require("./telemetry/index.cjs");
+var import_utils = require("./utils.cjs");
+var import_report = require("./voice/report.cjs");
+const jobContextStorage = new import_node_async_hooks.AsyncLocalStorage();
+function getJobContext() {
+  const ctx = jobContextStorage.getStore();
+  if (!ctx) {
+    throw new Error("no job context found, are you running this code inside a job entrypoint?");
+  }
+  return ctx;
+}
+function runWithJobContext(context, fn) {
+  return jobContextStorage.run(context, fn);
+}
+function runWithJobContextAsync(context, fn) {
+  return jobContextStorage.run(context, fn);
+}
+var AutoSubscribe = /* @__PURE__ */ ((AutoSubscribe2) => {
+  AutoSubscribe2[AutoSubscribe2["SUBSCRIBE_ALL"] = 0] = "SUBSCRIBE_ALL";
+  AutoSubscribe2[AutoSubscribe2["SUBSCRIBE_NONE"] = 1] = "SUBSCRIBE_NONE";
+  AutoSubscribe2[AutoSubscribe2["VIDEO_ONLY"] = 2] = "VIDEO_ONLY";
+  AutoSubscribe2[AutoSubscribe2["AUDIO_ONLY"] = 3] = "AUDIO_ONLY";
+  return AutoSubscribe2;
+})(AutoSubscribe || {});
+class FunctionExistsError extends Error {
+  constructor(msg) {
+    super(msg);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+class JobContext {
+  #proc;
+  #info;
+  #room;
+  #onConnect;
+  #onShutdown;
+  /** @internal */
+  shutdownCallbacks = [];
+  #participantEntrypoints = [];
+  #participantTasks = {};
+  #logger;
+  #inferenceExecutor;
+  /** @internal */
+  _primaryAgentSession;
+  /** @internal */
+  _sessionDirectory;
+  connected = false;
+  constructor(proc, info, room, onConnect, onShutdown, inferenceExecutor) {
+    var _a;
+    this.#proc = proc;
+    this.#info = info;
+    this.#room = room;
+    this.#onConnect = onConnect;
+    this.#onShutdown = onShutdown;
+    this.onParticipantConnected = this.onParticipantConnected.bind(this);
+    this.#room.on(import_rtc_node.RoomEvent.ParticipantConnected, this.onParticipantConnected);
+    this.#logger = (0, import_log.log)().child({
+      jobId: this.#info.job.id,
+      roomName: (_a = this.#info.job.room) == null ? void 0 : _a.name
+    });
+    this.#inferenceExecutor = inferenceExecutor;
+    this._sessionDirectory = path.join(os.tmpdir(), "livekit-agents", `job-${this.#info.job.id}`);
+  }
+  get proc() {
+    return this.#proc;
+  }
+  get job() {
+    return this.#info.job;
+  }
+  get workerId() {
+    return this.#info.workerId;
+  }
+  /** @returns The room the agent was called into */
+  get room() {
+    return this.#room;
+  }
+  get info() {
+    return this.#info;
+  }
+  /** @returns The agent's participant if connected to the room, otherwise `undefined` */
+  get agent() {
+    return this.#room.localParticipant;
+  }
+  /** @returns The global inference executor */
+  get inferenceExecutor() {
+    return this.#inferenceExecutor;
+  }
+  /**
+   * @returns The session directory for storing recordings and session data.
+   */
+  get sessionDirectory() {
+    return this._sessionDirectory;
+  }
+  /** Adds a promise to be awaited when {@link JobContext.shutdown | shutdown} is called. */
+  addShutdownCallback(callback) {
+    this.shutdownCallbacks.push(callback);
+  }
+  async waitForParticipant(identity) {
+    if (!this.#room.isConnected) {
+      throw new Error("room is not connected");
+    }
+    for (const p of this.#room.remoteParticipants.values()) {
+      if ((!identity || p.identity === identity) && p.info.kind != import_rtc_node.ParticipantKind.AGENT) {
+        return p;
+      }
+    }
+    return new Promise((resolve, reject) => {
+      const onParticipantConnected = (participant) => {
+        if ((!identity || participant.identity === identity) && participant.info.kind != import_rtc_node.ParticipantKind.AGENT) {
+          clearHandlers();
+          resolve(participant);
+        }
+      };
+      const onDisconnected = () => {
+        clearHandlers();
+        reject(new Error("Room disconnected while waiting for participant"));
+      };
+      const clearHandlers = () => {
+        this.#room.off(import_rtc_node.RoomEvent.ParticipantConnected, onParticipantConnected);
+        this.#room.off(import_rtc_node.RoomEvent.Disconnected, onDisconnected);
+      };
+      this.#room.on(import_rtc_node.RoomEvent.ParticipantConnected, onParticipantConnected);
+      this.#room.on(import_rtc_node.RoomEvent.Disconnected, onDisconnected);
+    });
+  }
+  /**
+   * Connects the agent to the room.
+   *
+   * @remarks
+   * It is recommended to run this command as early in the function as possible, as executing it
+   * later may cause noticeable delay between user and agent joins.
+   *
+   * @see {@link https://github.com/livekit/node-sdks/tree/main/packages/livekit-rtc#readme |
+   * @livekit/rtc-node} for more information about the parameters.
+   */
+  async connect(e2ee, autoSubscribe = 0 /* SUBSCRIBE_ALL */, rtcConfig) {
+    if (this.connected) {
+      return;
+    }
+    const opts = {
+      e2ee,
+      autoSubscribe: autoSubscribe == 0 /* SUBSCRIBE_ALL */,
+      rtcConfig,
+      dynacast: false
+    };
+    await this.#room.connect(this.#info.url, this.#info.token, opts);
+    this.#onConnect();
+    this.#room.remoteParticipants.forEach(this.onParticipantConnected);
+    if ([3 /* AUDIO_ONLY */, 2 /* VIDEO_ONLY */].includes(autoSubscribe)) {
+      this.#room.remoteParticipants.forEach((p) => {
+        p.trackPublications.forEach((pub) => {
+          if (autoSubscribe === 3 /* AUDIO_ONLY */ && pub.kind === import_rtc_node.TrackKind.KIND_AUDIO || autoSubscribe === 2 /* VIDEO_ONLY */ && pub.kind === import_rtc_node.TrackKind.KIND_VIDEO) {
+            pub.setSubscribed(true);
+          }
+        });
+      });
+    }
+    this.connected = true;
+  }
+  makeSessionReport(session) {
+    var _a, _b;
+    const targetSession = session || this._primaryAgentSession;
+    if (!targetSession) {
+      throw new Error("Cannot prepare report, no AgentSession was found");
+    }
+    const recorderIO = targetSession._recorderIO;
+    if (recorderIO && recorderIO.recording) {
+      throw new Error("Cannot create the AgentSession report, the RecorderIO is still recording");
+    }
+    return (0, import_report.createSessionReport)({
+      jobId: this.job.id,
+      roomId: ((_a = this.job.room) == null ? void 0 : _a.sid) || "",
+      room: ((_b = this.job.room) == null ? void 0 : _b.name) || "",
+      options: targetSession.options,
+      events: targetSession._recordedEvents,
+      enableRecording: targetSession._enableRecording,
+      chatHistory: targetSession.history.copy(),
+      startedAt: targetSession._startedAt,
+      audioRecordingPath: recorderIO == null ? void 0 : recorderIO.outputPath,
+      audioRecordingStartedAt: recorderIO == null ? void 0 : recorderIO.recordingStartedAt
+    });
+  }
+  async _onSessionEnd() {
+    const session = this._primaryAgentSession;
+    if (!session) {
+      return;
+    }
+    const report = this.makeSessionReport(session);
+    const url = new URL(this.#info.url);
+    if (report.enableRecording && (0, import_utils.isCloud)(url)) {
+      try {
+        await (0, import_telemetry.uploadSessionReport)({
+          agentName: this.job.agentName,
+          cloudHostname: url.hostname,
+          report
+        });
+        this.#logger.info(
+          {
+            jobId: report.jobId,
+            roomId: report.roomId
+          },
+          "Session report uploaded to LiveKit Cloud"
+        );
+      } catch (error) {
+        this.#logger.error({ error }, "Failed to upload session report");
+      }
+    }
+    this.#logger.debug(
+      {
+        jobId: report.jobId,
+        roomId: report.roomId,
+        eventsCount: report.events.length
+      },
+      "Session ended, report generated"
+    );
+    session._recordedEvents = [];
+    try {
+      await (0, import_telemetry.flushOtelLogs)();
+    } catch (error) {
+      this.#logger.error({ error }, "Failed to flush OTEL logs");
+    }
+  }
+  /**
+   * Gracefully shuts down the job, and runs all shutdown promises.
+   *
+   * @param reason - Optional reason for shutdown
+   */
+  shutdown(reason = "") {
+    this.#onShutdown(reason);
+  }
+  /** @internal */
+  onParticipantConnected(p) {
+    var _a;
+    for (const callback of this.#participantEntrypoints) {
+      if (((_a = this.#participantTasks[p.identity]) == null ? void 0 : _a.callback) == callback) {
+        this.#logger.warn(
+          "a participant has joined before a prior prticipant task matching the same identity has finished:",
+          p.identity
+        );
+      }
+      const result = callback(this, p);
+      result.finally(() => delete this.#participantTasks[p.identity]);
+      this.#participantTasks[p.identity] = { callback, result };
+    }
+  }
+  /**
+   * Adds a promise to be awaited whenever a new participant joins the room.
+   *
+   * @throws {@link FunctionExistsError} if an entrypoint already exists
+   */
+  addParticipantEntrypoint(callback) {
+    if (this.#participantEntrypoints.includes(callback)) {
+      throw new FunctionExistsError("entrypoints cannot be added more than once");
+    }
+    this.#participantEntrypoints.push(callback);
+  }
+  async initRecording() {
+    const url = new URL(this.#info.url);
+    if (!(0, import_utils.isCloud)(url)) {
+      return;
+    }
+    this.#logger.debug({ hostname: url.hostname }, "Configuring session recording (cloud tracer)");
+    await (0, import_telemetry.setupCloudTracer)({
+      roomId: this.job.room.sid,
+      jobId: this.job.id,
+      cloudHostname: url.hostname
+    });
+  }
+}
+class JobProcess {
+  #pid = process.pid;
+  userData = {};
+  get pid() {
+    return this.#pid;
+  }
+}
+class JobRequest {
+  #job;
+  #onReject;
+  #onAccept;
+  /** @internal */
+  constructor(job, onReject, onAccept) {
+    this.#job = job;
+    this.#onReject = onReject;
+    this.#onAccept = onAccept;
+  }
+  /** @returns The ID of the job, set by the LiveKit server */
+  get id() {
+    return this.#job.id;
+  }
+  /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */
+  get job() {
+    return this.#job;
+  }
+  /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */
+  get room() {
+    return this.#job.room;
+  }
+  /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */
+  get publisher() {
+    return this.#job.participant;
+  }
+  /** @returns The agent's name, as set in {@link WorkerOptions} */
+  get agentName() {
+    return this.#job.agentName;
+  }
+  /** Rejects the job. */
+  async reject() {
+    await this.#onReject();
+  }
+  /** Accepts the job, launching it on an idle child process. */
+  async accept(name = "", identity = "", metadata = "", attributes) {
+    if (identity === "") identity = "agent-" + this.id;
+    this.#onAccept({ name, identity, metadata, attributes });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AutoSubscribe,
+  FunctionExistsError,
+  JobContext,
+  JobProcess,
+  JobRequest,
+  getJobContext,
+  runWithJobContext,
+  runWithJobContextAsync
+});
+//# sourceMappingURL=job.cjs.map

package/dist/job.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/job.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2024 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type * as proto from '@livekit/protocol';\nimport type {\n  E2EEOptions,\n  LocalParticipant,\n  RemoteParticipant,\n  Room,\n  RtcConfiguration,\n} from '@livekit/rtc-node';\nimport { ParticipantKind, RoomEvent, TrackKind } from '@livekit/rtc-node';\nimport { AsyncLocalStorage } from 'node:async_hooks';\nimport * as os from 'node:os';\nimport * as path from 'node:path';\nimport type { Logger } from 'pino';\nimport type { InferenceExecutor } from './ipc/inference_executor.js';\nimport { log } from './log.js';\nimport { flushOtelLogs, setupCloudTracer, uploadSessionReport } from './telemetry/index.js';\nimport { isCloud } from './utils.js';\nimport type { AgentSession } from './voice/agent_session.js';\nimport { type SessionReport, createSessionReport } from './voice/report.js';\n\n// AsyncLocalStorage for job context, similar to Python's contextvars\nconst jobContextStorage = new AsyncLocalStorage<JobContext>();\n\n/**\n * Returns the current job context.\n *\n * @throws {Error} if no job context is found\n */\nexport function getJobContext(): JobContext {\n  const ctx = jobContextStorage.getStore();\n  if (!ctx) {\n    throw new Error('no job context found, are you running this code inside a job entrypoint?');\n  }\n  return ctx;\n}\n\n/**\n * Runs a function within a job context, similar to Python's contextvars.\n * @internal\n */\nexport function runWithJobContext<T>(context: JobContext, fn: () => T): T {\n  return jobContextStorage.run(context, fn);\n}\n\n/**\n * Runs an async function within a job context, similar to Python's contextvars.\n * @internal\n */\nexport function runWithJobContextAsync<T>(context: JobContext, fn: () => Promise<T>): Promise<T> {\n  return jobContextStorage.run(context, fn);\n}\n\n/** Which tracks, if any, should the agent automatically subscribe to? */\nexport enum AutoSubscribe {\n  SUBSCRIBE_ALL,\n  SUBSCRIBE_NONE,\n  VIDEO_ONLY,\n  AUDIO_ONLY,\n}\n\nexport type JobAcceptArguments = {\n  name: string;\n  identity: string;\n  metadata: string;\n  attributes?: { [key: string]: string };\n};\n\nexport type RunningJobInfo = {\n  acceptArguments: JobAcceptArguments;\n  job: proto.Job;\n  url: string;\n  token: string;\n  workerId: string;\n};\n\n/** Attempted to add a function callback, but the function already exists. */\nexport class FunctionExistsError extends Error {\n  constructor(msg?: string) {\n    super(msg);\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** The job and environment context as seen by the agent, accessible by the entrypoint function. */\nexport class JobContext {\n  #proc: JobProcess;\n  #info: RunningJobInfo;\n  #room: Room;\n  #onConnect: () => void;\n  #onShutdown: (s: string) => void;\n  /** @internal */\n  shutdownCallbacks: (() => Promise<void>)[] = [];\n  #participantEntrypoints: ((job: JobContext, p: RemoteParticipant) => Promise<void>)[] = [];\n  #participantTasks: {\n    [id: string]: {\n      callback: (job: JobContext, p: RemoteParticipant) => Promise<void>;\n      result: Promise<void>;\n    };\n  } = {};\n  #logger: Logger;\n  #inferenceExecutor: InferenceExecutor;\n\n  /** @internal */\n  _primaryAgentSession?: AgentSession;\n\n  /** @internal */\n  _sessionDirectory: string;\n\n  private connected: boolean = false;\n\n  constructor(\n    proc: JobProcess,\n    info: RunningJobInfo,\n    room: Room,\n    onConnect: () => void,\n    onShutdown: (s: string) => void,\n    inferenceExecutor: InferenceExecutor,\n  ) {\n    this.#proc = proc;\n    this.#info = info;\n    this.#room = room;\n    this.#onConnect = onConnect;\n    this.#onShutdown = onShutdown;\n    this.onParticipantConnected = this.onParticipantConnected.bind(this);\n    this.#room.on(RoomEvent.ParticipantConnected, this.onParticipantConnected);\n    this.#logger = log().child({\n      jobId: this.#info.job.id,\n      roomName: this.#info.job.room?.name,\n    });\n    this.#inferenceExecutor = inferenceExecutor;\n    this._sessionDirectory = path.join(os.tmpdir(), 'livekit-agents', `job-${this.#info.job.id}`);\n  }\n\n  get proc(): JobProcess {\n    return this.#proc;\n  }\n\n  get job(): proto.Job {\n    return this.#info.job;\n  }\n\n  get workerId(): string {\n    return this.#info.workerId;\n  }\n\n  /** @returns The room the agent was called into */\n  get room(): Room {\n    return this.#room;\n  }\n\n  get info(): RunningJobInfo {\n    return this.#info;\n  }\n\n  /** @returns The agent's participant if connected to the room, otherwise `undefined` */\n  get agent(): LocalParticipant | undefined {\n    return this.#room.localParticipant;\n  }\n\n  /** @returns The global inference executor */\n  get inferenceExecutor(): InferenceExecutor {\n    return this.#inferenceExecutor;\n  }\n\n  /**\n   * @returns The session directory for storing recordings and session data.\n   */\n  get sessionDirectory(): string {\n    return this._sessionDirectory;\n  }\n\n  /** Adds a promise to be awaited when {@link JobContext.shutdown | shutdown} is called. */\n  addShutdownCallback(callback: () => Promise<void>) {\n    this.shutdownCallbacks.push(callback);\n  }\n\n  async waitForParticipant(identity?: string): Promise<RemoteParticipant> {\n    if (!this.#room.isConnected) {\n      throw new Error('room is not connected');\n    }\n\n    for (const p of this.#room.remoteParticipants.values()) {\n      if ((!identity || p.identity === identity) && p.info.kind != ParticipantKind.AGENT) {\n        return p;\n      }\n    }\n\n    return new Promise((resolve, reject) => {\n      const onParticipantConnected = (participant: RemoteParticipant) => {\n        if (\n          (!identity || participant.identity === identity) &&\n          participant.info.kind != ParticipantKind.AGENT\n        ) {\n          clearHandlers();\n          resolve(participant);\n        }\n      };\n      const onDisconnected = () => {\n        clearHandlers();\n        reject(new Error('Room disconnected while waiting for participant'));\n      };\n\n      const clearHandlers = () => {\n        this.#room.off(RoomEvent.ParticipantConnected, onParticipantConnected);\n        this.#room.off(RoomEvent.Disconnected, onDisconnected);\n      };\n\n      this.#room.on(RoomEvent.ParticipantConnected, onParticipantConnected);\n      this.#room.on(RoomEvent.Disconnected, onDisconnected);\n    });\n  }\n\n  /**\n   * Connects the agent to the room.\n   *\n   * @remarks\n   * It is recommended to run this command as early in the function as possible, as executing it\n   * later may cause noticeable delay between user and agent joins.\n   *\n   * @see {@link https://github.com/livekit/node-sdks/tree/main/packages/livekit-rtc#readme |\n   * @livekit/rtc-node} for more information about the parameters.\n   */\n  async connect(\n    e2ee?: E2EEOptions,\n    autoSubscribe: AutoSubscribe = AutoSubscribe.SUBSCRIBE_ALL,\n    rtcConfig?: RtcConfiguration,\n  ) {\n    if (this.connected) {\n      return;\n    }\n\n    const opts = {\n      e2ee,\n      autoSubscribe: autoSubscribe == AutoSubscribe.SUBSCRIBE_ALL,\n      rtcConfig,\n      dynacast: false,\n    };\n\n    await this.#room.connect(this.#info.url, this.#info.token, opts);\n    this.#onConnect();\n\n    this.#room.remoteParticipants.forEach(this.onParticipantConnected);\n\n    if ([AutoSubscribe.AUDIO_ONLY, AutoSubscribe.VIDEO_ONLY].includes(autoSubscribe)) {\n      this.#room.remoteParticipants.forEach((p) => {\n        p.trackPublications.forEach((pub) => {\n          if (\n            (autoSubscribe === AutoSubscribe.AUDIO_ONLY && pub.kind === TrackKind.KIND_AUDIO) ||\n            (autoSubscribe === AutoSubscribe.VIDEO_ONLY && pub.kind === TrackKind.KIND_VIDEO)\n          ) {\n            pub.setSubscribed(true);\n          }\n        });\n      });\n    }\n    this.connected = true;\n  }\n\n  makeSessionReport(session?: AgentSession): SessionReport {\n    const targetSession = session || this._primaryAgentSession;\n\n    if (!targetSession) {\n      throw new Error('Cannot prepare report, no AgentSession was found');\n    }\n\n    const recorderIO = targetSession._recorderIO;\n\n    if (recorderIO && recorderIO.recording) {\n      throw new Error('Cannot create the AgentSession report, the RecorderIO is still recording');\n    }\n\n    return createSessionReport({\n      jobId: this.job.id,\n      roomId: this.job.room?.sid || '',\n      room: this.job.room?.name || '',\n      options: targetSession.options,\n      events: targetSession._recordedEvents,\n      enableRecording: targetSession._enableRecording,\n      chatHistory: targetSession.history.copy(),\n      startedAt: targetSession._startedAt,\n      audioRecordingPath: recorderIO?.outputPath,\n      audioRecordingStartedAt: recorderIO?.recordingStartedAt,\n    });\n  }\n\n  async _onSessionEnd(): Promise<void> {\n    const session = this._primaryAgentSession;\n    if (!session) {\n      return;\n    }\n\n    const report = this.makeSessionReport(session);\n\n    // TODO(brian): Implement CLI/console\n\n    // Upload session report to LiveKit Cloud if enabled\n    const url = new URL(this.#info.url);\n\n    if (report.enableRecording && isCloud(url)) {\n      try {\n        await uploadSessionReport({\n          agentName: this.job.agentName,\n          cloudHostname: url.hostname,\n          report,\n        });\n        this.#logger.info(\n          {\n            jobId: report.jobId,\n            roomId: report.roomId,\n          },\n          'Session report uploaded to LiveKit Cloud',\n        );\n      } catch (error) {\n        this.#logger.error({ error }, 'Failed to upload session report');\n      }\n    }\n\n    this.#logger.debug(\n      {\n        jobId: report.jobId,\n        roomId: report.roomId,\n        eventsCount: report.events.length,\n      },\n      'Session ended, report generated',\n    );\n\n    // Explicitly clear the recorded events to avoid leaking memory\n    session._recordedEvents = [];\n\n    try {\n      await flushOtelLogs();\n    } catch (error) {\n      this.#logger.error({ error }, 'Failed to flush OTEL logs');\n    }\n  }\n\n  /**\n   * Gracefully shuts down the job, and runs all shutdown promises.\n   *\n   * @param reason - Optional reason for shutdown\n   */\n  shutdown(reason = '') {\n    this.#onShutdown(reason);\n  }\n\n  /** @internal */\n  onParticipantConnected(p: RemoteParticipant) {\n    for (const callback of this.#participantEntrypoints) {\n      if (this.#participantTasks[p.identity!]?.callback == callback) {\n        this.#logger.warn(\n          'a participant has joined before a prior prticipant task matching the same identity has finished:',\n          p.identity,\n        );\n      }\n      const result = callback(this, p);\n      result.finally(() => delete this.#participantTasks[p.identity!]);\n      this.#participantTasks[p.identity!] = { callback, result };\n    }\n  }\n\n  /**\n   * Adds a promise to be awaited whenever a new participant joins the room.\n   *\n   * @throws {@link FunctionExistsError} if an entrypoint already exists\n   */\n  addParticipantEntrypoint(callback: (job: JobContext, p: RemoteParticipant) => Promise<void>) {\n    if (this.#participantEntrypoints.includes(callback)) {\n      throw new FunctionExistsError('entrypoints cannot be added more than once');\n    }\n\n    this.#participantEntrypoints.push(callback);\n  }\n\n  async initRecording() {\n    const url = new URL(this.#info.url);\n    if (!isCloud(url)) {\n      return;\n    }\n\n    this.#logger.debug({ hostname: url.hostname }, 'Configuring session recording (cloud tracer)');\n    await setupCloudTracer({\n      roomId: this.job.room!.sid,\n      jobId: this.job.id,\n      cloudHostname: url.hostname,\n    });\n  }\n}\n\nexport class JobProcess {\n  #pid = process.pid;\n  userData: { [id: string]: unknown } = {};\n\n  get pid(): number {\n    return this.#pid;\n  }\n}\n\n/**\n * A request sent by the server to spawn a new agent job.\n *\n * @remarks\n * For most applications, this is best left to the default, which simply accepts the job and\n * handles the logic inside the entrypoint function. This class is useful for vetting which\n * requests should fill idle processes and which should be outright rejected.\n */\nexport class JobRequest {\n  #job: proto.Job;\n  #onReject: () => Promise<void>;\n  #onAccept: (args: JobAcceptArguments) => Promise<void>;\n\n  /** @internal */\n  constructor(\n    job: proto.Job,\n    onReject: () => Promise<void>,\n    onAccept: (args: JobAcceptArguments) => Promise<void>,\n  ) {\n    this.#job = job;\n    this.#onReject = onReject;\n    this.#onAccept = onAccept;\n  }\n\n  /** @returns The ID of the job, set by the LiveKit server */\n  get id(): string {\n    return this.#job.id;\n  }\n\n  /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */\n  get job(): proto.Job {\n    return this.#job;\n  }\n\n  /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */\n  get room(): proto.Room | undefined {\n    return this.#job.room;\n  }\n\n  /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */\n  get publisher(): proto.ParticipantInfo | undefined {\n    return this.#job.participant;\n  }\n\n  /** @returns The agent's name, as set in {@link WorkerOptions} */\n  get agentName(): string {\n    return this.#job.agentName;\n  }\n\n  /** Rejects the job. */\n  async reject() {\n    await this.#onReject();\n  }\n\n  /** Accepts the job, launching it on an idle child process. */\n  async accept(name = '', identity = '', metadata = '', attributes?: { [key: string]: string }) {\n    if (identity === '') identity = 'agent-' + this.id;\n\n    this.#onAccept({ name, identity, metadata, attributes });\n  }\n}\n"],"mappings":"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","names":["AutoSubscribe"]}

package/dist/job.d.cts

@@ -0,0 +1,141 @@
+import type * as proto from '@livekit/protocol';
+import type { E2EEOptions, LocalParticipant, RemoteParticipant, Room, RtcConfiguration } from '@livekit/rtc-node';
+import type { InferenceExecutor } from './ipc/inference_executor.js';
+import type { AgentSession } from './voice/agent_session.js';
+import { type SessionReport } from './voice/report.js';
+/**
+ * Returns the current job context.
+ *
+ * @throws {Error} if no job context is found
+ */
+export declare function getJobContext(): JobContext;
+/**
+ * Runs a function within a job context, similar to Python's contextvars.
+ * @internal
+ */
+export declare function runWithJobContext<T>(context: JobContext, fn: () => T): T;
+/**
+ * Runs an async function within a job context, similar to Python's contextvars.
+ * @internal
+ */
+export declare function runWithJobContextAsync<T>(context: JobContext, fn: () => Promise<T>): Promise<T>;
+/** Which tracks, if any, should the agent automatically subscribe to? */
+export declare enum AutoSubscribe {
+    SUBSCRIBE_ALL = 0,
+    SUBSCRIBE_NONE = 1,
+    VIDEO_ONLY = 2,
+    AUDIO_ONLY = 3
+}
+export type JobAcceptArguments = {
+    name: string;
+    identity: string;
+    metadata: string;
+    attributes?: {
+        [key: string]: string;
+    };
+};
+export type RunningJobInfo = {
+    acceptArguments: JobAcceptArguments;
+    job: proto.Job;
+    url: string;
+    token: string;
+    workerId: string;
+};
+/** Attempted to add a function callback, but the function already exists. */
+export declare class FunctionExistsError extends Error {
+    constructor(msg?: string);
+}
+/** The job and environment context as seen by the agent, accessible by the entrypoint function. */
+export declare class JobContext {
+    #private;
+    /** @internal */
+    shutdownCallbacks: (() => Promise<void>)[];
+    /** @internal */
+    _primaryAgentSession?: AgentSession;
+    /** @internal */
+    _sessionDirectory: string;
+    private connected;
+    constructor(proc: JobProcess, info: RunningJobInfo, room: Room, onConnect: () => void, onShutdown: (s: string) => void, inferenceExecutor: InferenceExecutor);
+    get proc(): JobProcess;
+    get job(): proto.Job;
+    get workerId(): string;
+    /** @returns The room the agent was called into */
+    get room(): Room;
+    get info(): RunningJobInfo;
+    /** @returns The agent's participant if connected to the room, otherwise `undefined` */
+    get agent(): LocalParticipant | undefined;
+    /** @returns The global inference executor */
+    get inferenceExecutor(): InferenceExecutor;
+    /**
+     * @returns The session directory for storing recordings and session data.
+     */
+    get sessionDirectory(): string;
+    /** Adds a promise to be awaited when {@link JobContext.shutdown | shutdown} is called. */
+    addShutdownCallback(callback: () => Promise<void>): void;
+    waitForParticipant(identity?: string): Promise<RemoteParticipant>;
+    /**
+     * Connects the agent to the room.
+     *
+     * @remarks
+     * It is recommended to run this command as early in the function as possible, as executing it
+     * later may cause noticeable delay between user and agent joins.
+     *
+     * @see {@link https://github.com/livekit/node-sdks/tree/main/packages/livekit-rtc#readme |
+     * @livekit/rtc-node} for more information about the parameters.
+     */
+    connect(e2ee?: E2EEOptions, autoSubscribe?: AutoSubscribe, rtcConfig?: RtcConfiguration): Promise<void>;
+    makeSessionReport(session?: AgentSession): SessionReport;
+    _onSessionEnd(): Promise<void>;
+    /**
+     * Gracefully shuts down the job, and runs all shutdown promises.
+     *
+     * @param reason - Optional reason for shutdown
+     */
+    shutdown(reason?: string): void;
+    /** @internal */
+    onParticipantConnected(p: RemoteParticipant): void;
+    /**
+     * Adds a promise to be awaited whenever a new participant joins the room.
+     *
+     * @throws {@link FunctionExistsError} if an entrypoint already exists
+     */
+    addParticipantEntrypoint(callback: (job: JobContext, p: RemoteParticipant) => Promise<void>): void;
+    initRecording(): Promise<void>;
+}
+export declare class JobProcess {
+    #private;
+    userData: {
+        [id: string]: unknown;
+    };
+    get pid(): number;
+}
+/**
+ * A request sent by the server to spawn a new agent job.
+ *
+ * @remarks
+ * For most applications, this is best left to the default, which simply accepts the job and
+ * handles the logic inside the entrypoint function. This class is useful for vetting which
+ * requests should fill idle processes and which should be outright rejected.
+ */
+export declare class JobRequest {
+    #private;
+    /** @internal */
+    constructor(job: proto.Job, onReject: () => Promise<void>, onAccept: (args: JobAcceptArguments) => Promise<void>);
+    /** @returns The ID of the job, set by the LiveKit server */
+    get id(): string;
+    /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */
+    get job(): proto.Job;
+    /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */
+    get room(): proto.Room | undefined;
+    /** @see {@link https://www.npmjs.com/package/@livekit/protocol | @livekit/protocol} */
+    get publisher(): proto.ParticipantInfo | undefined;
+    /** @returns The agent's name, as set in {@link WorkerOptions} */
+    get agentName(): string;
+    /** Rejects the job. */
+    reject(): Promise<void>;
+    /** Accepts the job, launching it on an idle child process. */
+    accept(name?: string, identity?: string, metadata?: string, attributes?: {
+        [key: string]: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=job.d.ts.map