@livekit/agents 1.0.18 → 1.0.20

package/dist/voice/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport * from './events.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,mBAA2E;AAC3E,2BAAuD;AACvD,0BAAc,8BALd;AAMA,0BAAc,kCANd;AAOA,0BAAc,wBAPd;AAQA,0BAAc,+BARd;AASA,yBAA2B;","names":[]}
+{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport * from './events.js';\nexport * from './report.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,mBAA2E;AAC3E,2BAAuD;AACvD,0BAAc,8BALd;AAMA,0BAAc,kCANd;AAOA,0BAAc,wBAPd;AAQA,0BAAc,wBARd;AASA,0BAAc,+BATd;AAUA,yBAA2B;","names":[]}

package/dist/voice/index.d.cts

@@ -3,6 +3,7 @@ export { AgentSession, type AgentSessionOptions } from './agent_session.js';
 export * from './avatar/index.js';
 export * from './background_audio.js';
 export * from './events.js';
+export * from './report.js';
 export * from './room_io/index.js';
 export { RunContext } from './run_context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/voice/index.d.ts

@@ -3,6 +3,7 @@ export { AgentSession, type AgentSessionOptions } from './agent_session.js';
 export * from './avatar/index.js';
 export * from './background_audio.js';
 export * from './events.js';
+export * from './report.js';
 export * from './room_io/index.js';
 export { RunContext } from './run_context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/voice/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/voice/index.js

@@ -3,6 +3,7 @@ import { AgentSession } from "./agent_session.js";
 export * from "./avatar/index.js";
 export * from "./background_audio.js";
 export * from "./events.js";
+export * from "./report.js";
 export * from "./room_io/index.js";
 import { RunContext } from "./run_context.js";
 export {

package/dist/voice/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport * from './events.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":"AAGA,SAAS,OAAO,oBAA2D;AAC3E,SAAS,oBAA8C;AACvD,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,kBAAkB;","names":[]}
+{"version":3,"sources":["../../src/voice/index.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nexport { Agent, StopResponse, type AgentOptions, type ModelSettings } from './agent.js';\nexport { AgentSession, type AgentSessionOptions } from './agent_session.js';\nexport * from './avatar/index.js';\nexport * from './background_audio.js';\nexport * from './events.js';\nexport * from './report.js';\nexport * from './room_io/index.js';\nexport { RunContext } from './run_context.js';\n"],"mappings":"AAGA,SAAS,OAAO,oBAA2D;AAC3E,SAAS,oBAA8C;AACvD,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,kBAAkB;","names":[]}

package/dist/voice/report.cjs

@@ -0,0 +1,69 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var report_exports = {};
+__export(report_exports, {
+  createSessionReport: () => createSessionReport,
+  sessionReportToJSON: () => sessionReportToJSON
+});
+module.exports = __toCommonJS(report_exports);
+function createSessionReport(opts) {
+  return {
+    jobId: opts.jobId,
+    roomId: opts.roomId,
+    room: opts.room,
+    options: opts.options,
+    events: opts.events,
+    chatHistory: opts.chatHistory,
+    enableUserDataTraining: opts.enableUserDataTraining ?? false,
+    timestamp: opts.timestamp ?? Date.now()
+  };
+}
+function sessionReportToJSON(report) {
+  const events = [];
+  for (const event of report.events) {
+    if (event.type === "metrics_collected") {
+      continue;
+    }
+    events.push({ ...event });
+  }
+  return {
+    job_id: report.jobId,
+    room_id: report.roomId,
+    room: report.room,
+    events,
+    options: {
+      allow_interruptions: report.options.allowInterruptions,
+      discard_audio_if_uninterruptible: report.options.discardAudioIfUninterruptible,
+      min_interruption_duration: report.options.minInterruptionDuration,
+      min_interruption_words: report.options.minInterruptionWords,
+      min_endpointing_delay: report.options.minEndpointingDelay,
+      max_endpointing_delay: report.options.maxEndpointingDelay,
+      max_tool_steps: report.options.maxToolSteps
+    },
+    chat_history: report.chatHistory.toJSON({ excludeTimestamp: false }),
+    enable_user_data_training: report.enableUserDataTraining,
+    timestamp: report.timestamp
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSessionReport,
+  sessionReportToJSON
+});
+//# sourceMappingURL=report.cjs.map

package/dist/voice/report.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/voice/report.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { ChatContext } from '../llm/chat_context.js';\nimport type { VoiceOptions } from './agent_session.js';\nimport type { AgentEvent } from './events.js';\n\nexport interface SessionReport {\n  jobId: string;\n  roomId: string;\n  room: string;\n  options: VoiceOptions;\n  events: AgentEvent[];\n  chatHistory: ChatContext;\n  enableUserDataTraining: boolean;\n  timestamp: number;\n}\n\nexport interface SessionReportOptions {\n  jobId: string;\n  roomId: string;\n  room: string;\n  options: VoiceOptions;\n  events: AgentEvent[];\n  chatHistory: ChatContext;\n  enableUserDataTraining?: boolean;\n  timestamp?: number;\n}\n\nexport function createSessionReport(opts: SessionReportOptions): SessionReport {\n  return {\n    jobId: opts.jobId,\n    roomId: opts.roomId,\n    room: opts.room,\n    options: opts.options,\n    events: opts.events,\n    chatHistory: opts.chatHistory,\n    enableUserDataTraining: opts.enableUserDataTraining ?? false,\n    timestamp: opts.timestamp ?? Date.now(),\n  };\n}\n\n// TODO(brian): PR5 - Add uploadSessionReport() function that creates multipart form with:\n//   - header: protobuf MetricsRecordingHeader (room_id, duration, start_time)\n//   - chat_history: JSON serialized chat history (use sessionReportToJSON)\n//   - audio: audio recording file if available (ogg format)\n//   - Uploads to LiveKit Cloud observability endpoint with JWT auth\nexport function sessionReportToJSON(report: SessionReport): Record<string, unknown> {\n  const events: Record<string, unknown>[] = [];\n\n  for (const event of report.events) {\n    if (event.type === 'metrics_collected') {\n      continue; // metrics are too noisy, Cloud is using the chat_history as the source of truth\n    }\n\n    events.push({ ...event });\n  }\n\n  return {\n    job_id: report.jobId,\n    room_id: report.roomId,\n    room: report.room,\n    events,\n    options: {\n      allow_interruptions: report.options.allowInterruptions,\n      discard_audio_if_uninterruptible: report.options.discardAudioIfUninterruptible,\n      min_interruption_duration: report.options.minInterruptionDuration,\n      min_interruption_words: report.options.minInterruptionWords,\n      min_endpointing_delay: report.options.minEndpointingDelay,\n      max_endpointing_delay: report.options.maxEndpointingDelay,\n      max_tool_steps: report.options.maxToolSteps,\n    },\n    chat_history: report.chatHistory.toJSON({ excludeTimestamp: false }),\n    enable_user_data_training: report.enableUserDataTraining,\n    timestamp: report.timestamp,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6BO,SAAS,oBAAoB,MAA2C;AAC7E,SAAO;AAAA,IACL,OAAO,KAAK;AAAA,IACZ,QAAQ,KAAK;AAAA,IACb,MAAM,KAAK;AAAA,IACX,SAAS,KAAK;AAAA,IACd,QAAQ,KAAK;AAAA,IACb,aAAa,KAAK;AAAA,IAClB,wBAAwB,KAAK,0BAA0B;AAAA,IACvD,WAAW,KAAK,aAAa,KAAK,IAAI;AAAA,EACxC;AACF;AAOO,SAAS,oBAAoB,QAAgD;AAClF,QAAM,SAAoC,CAAC;AAE3C,aAAW,SAAS,OAAO,QAAQ;AACjC,QAAI,MAAM,SAAS,qBAAqB;AACtC;AAAA,IACF;AAEA,WAAO,KAAK,EAAE,GAAG,MAAM,CAAC;AAAA,EAC1B;AAEA,SAAO;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,SAAS,OAAO;AAAA,IAChB,MAAM,OAAO;AAAA,IACb;AAAA,IACA,SAAS;AAAA,MACP,qBAAqB,OAAO,QAAQ;AAAA,MACpC,kCAAkC,OAAO,QAAQ;AAAA,MACjD,2BAA2B,OAAO,QAAQ;AAAA,MAC1C,wBAAwB,OAAO,QAAQ;AAAA,MACvC,uBAAuB,OAAO,QAAQ;AAAA,MACtC,uBAAuB,OAAO,QAAQ;AAAA,MACtC,gBAAgB,OAAO,QAAQ;AAAA,IACjC;AAAA,IACA,cAAc,OAAO,YAAY,OAAO,EAAE,kBAAkB,MAAM,CAAC;AAAA,IACnE,2BAA2B,OAAO;AAAA,IAClC,WAAW,OAAO;AAAA,EACpB;AACF;","names":[]}

package/dist/voice/report.d.cts

@@ -0,0 +1,26 @@
+import type { ChatContext } from '../llm/chat_context.js';
+import type { VoiceOptions } from './agent_session.js';
+import type { AgentEvent } from './events.js';
+export interface SessionReport {
+    jobId: string;
+    roomId: string;
+    room: string;
+    options: VoiceOptions;
+    events: AgentEvent[];
+    chatHistory: ChatContext;
+    enableUserDataTraining: boolean;
+    timestamp: number;
+}
+export interface SessionReportOptions {
+    jobId: string;
+    roomId: string;
+    room: string;
+    options: VoiceOptions;
+    events: AgentEvent[];
+    chatHistory: ChatContext;
+    enableUserDataTraining?: boolean;
+    timestamp?: number;
+}
+export declare function createSessionReport(opts: SessionReportOptions): SessionReport;
+export declare function sessionReportToJSON(report: SessionReport): Record<string, unknown>;
+//# sourceMappingURL=report.d.ts.map

package/dist/voice/report.d.ts

@@ -0,0 +1,26 @@
+import type { ChatContext } from '../llm/chat_context.js';
+import type { VoiceOptions } from './agent_session.js';
+import type { AgentEvent } from './events.js';
+export interface SessionReport {
+    jobId: string;
+    roomId: string;
+    room: string;
+    options: VoiceOptions;
+    events: AgentEvent[];
+    chatHistory: ChatContext;
+    enableUserDataTraining: boolean;
+    timestamp: number;
+}
+export interface SessionReportOptions {
+    jobId: string;
+    roomId: string;
+    room: string;
+    options: VoiceOptions;
+    events: AgentEvent[];
+    chatHistory: ChatContext;
+    enableUserDataTraining?: boolean;
+    timestamp?: number;
+}
+export declare function createSessionReport(opts: SessionReportOptions): SessionReport;
+export declare function sessionReportToJSON(report: SessionReport): Record<string, unknown>;
+//# sourceMappingURL=report.d.ts.map

package/dist/voice/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/voice/report.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,sBAAsB,EAAE,OAAO,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAW7E;AAOD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6BlF"}

package/dist/voice/report.js

@@ -0,0 +1,44 @@
+function createSessionReport(opts) {
+  return {
+    jobId: opts.jobId,
+    roomId: opts.roomId,
+    room: opts.room,
+    options: opts.options,
+    events: opts.events,
+    chatHistory: opts.chatHistory,
+    enableUserDataTraining: opts.enableUserDataTraining ?? false,
+    timestamp: opts.timestamp ?? Date.now()
+  };
+}
+function sessionReportToJSON(report) {
+  const events = [];
+  for (const event of report.events) {
+    if (event.type === "metrics_collected") {
+      continue;
+    }
+    events.push({ ...event });
+  }
+  return {
+    job_id: report.jobId,
+    room_id: report.roomId,
+    room: report.room,
+    events,
+    options: {
+      allow_interruptions: report.options.allowInterruptions,
+      discard_audio_if_uninterruptible: report.options.discardAudioIfUninterruptible,
+      min_interruption_duration: report.options.minInterruptionDuration,
+      min_interruption_words: report.options.minInterruptionWords,
+      min_endpointing_delay: report.options.minEndpointingDelay,
+      max_endpointing_delay: report.options.maxEndpointingDelay,
+      max_tool_steps: report.options.maxToolSteps
+    },
+    chat_history: report.chatHistory.toJSON({ excludeTimestamp: false }),
+    enable_user_data_training: report.enableUserDataTraining,
+    timestamp: report.timestamp
+  };
+}
+export {
+  createSessionReport,
+  sessionReportToJSON
+};
+//# sourceMappingURL=report.js.map

package/dist/voice/report.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/voice/report.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport type { ChatContext } from '../llm/chat_context.js';\nimport type { VoiceOptions } from './agent_session.js';\nimport type { AgentEvent } from './events.js';\n\nexport interface SessionReport {\n  jobId: string;\n  roomId: string;\n  room: string;\n  options: VoiceOptions;\n  events: AgentEvent[];\n  chatHistory: ChatContext;\n  enableUserDataTraining: boolean;\n  timestamp: number;\n}\n\nexport interface SessionReportOptions {\n  jobId: string;\n  roomId: string;\n  room: string;\n  options: VoiceOptions;\n  events: AgentEvent[];\n  chatHistory: ChatContext;\n  enableUserDataTraining?: boolean;\n  timestamp?: number;\n}\n\nexport function createSessionReport(opts: SessionReportOptions): SessionReport {\n  return {\n    jobId: opts.jobId,\n    roomId: opts.roomId,\n    room: opts.room,\n    options: opts.options,\n    events: opts.events,\n    chatHistory: opts.chatHistory,\n    enableUserDataTraining: opts.enableUserDataTraining ?? false,\n    timestamp: opts.timestamp ?? Date.now(),\n  };\n}\n\n// TODO(brian): PR5 - Add uploadSessionReport() function that creates multipart form with:\n//   - header: protobuf MetricsRecordingHeader (room_id, duration, start_time)\n//   - chat_history: JSON serialized chat history (use sessionReportToJSON)\n//   - audio: audio recording file if available (ogg format)\n//   - Uploads to LiveKit Cloud observability endpoint with JWT auth\nexport function sessionReportToJSON(report: SessionReport): Record<string, unknown> {\n  const events: Record<string, unknown>[] = [];\n\n  for (const event of report.events) {\n    if (event.type === 'metrics_collected') {\n      continue; // metrics are too noisy, Cloud is using the chat_history as the source of truth\n    }\n\n    events.push({ ...event });\n  }\n\n  return {\n    job_id: report.jobId,\n    room_id: report.roomId,\n    room: report.room,\n    events,\n    options: {\n      allow_interruptions: report.options.allowInterruptions,\n      discard_audio_if_uninterruptible: report.options.discardAudioIfUninterruptible,\n      min_interruption_duration: report.options.minInterruptionDuration,\n      min_interruption_words: report.options.minInterruptionWords,\n      min_endpointing_delay: report.options.minEndpointingDelay,\n      max_endpointing_delay: report.options.maxEndpointingDelay,\n      max_tool_steps: report.options.maxToolSteps,\n    },\n    chat_history: report.chatHistory.toJSON({ excludeTimestamp: false }),\n    enable_user_data_training: report.enableUserDataTraining,\n    timestamp: report.timestamp,\n  };\n}\n"],"mappings":"AA6BO,SAAS,oBAAoB,MAA2C;AAC7E,SAAO;AAAA,IACL,OAAO,KAAK;AAAA,IACZ,QAAQ,KAAK;AAAA,IACb,MAAM,KAAK;AAAA,IACX,SAAS,KAAK;AAAA,IACd,QAAQ,KAAK;AAAA,IACb,aAAa,KAAK;AAAA,IAClB,wBAAwB,KAAK,0BAA0B;AAAA,IACvD,WAAW,KAAK,aAAa,KAAK,IAAI;AAAA,EACxC;AACF;AAOO,SAAS,oBAAoB,QAAgD;AAClF,QAAM,SAAoC,CAAC;AAE3C,aAAW,SAAS,OAAO,QAAQ;AACjC,QAAI,MAAM,SAAS,qBAAqB;AACtC;AAAA,IACF;AAEA,WAAO,KAAK,EAAE,GAAG,MAAM,CAAC;AAAA,EAC1B;AAEA,SAAO;AAAA,IACL,QAAQ,OAAO;AAAA,IACf,SAAS,OAAO;AAAA,IAChB,MAAM,OAAO;AAAA,IACb;AAAA,IACA,SAAS;AAAA,MACP,qBAAqB,OAAO,QAAQ;AAAA,MACpC,kCAAkC,OAAO,QAAQ;AAAA,MACjD,2BAA2B,OAAO,QAAQ;AAAA,MAC1C,wBAAwB,OAAO,QAAQ;AAAA,MACvC,uBAAuB,OAAO,QAAQ;AAAA,MACtC,uBAAuB,OAAO,QAAQ;AAAA,MACtC,gBAAgB,OAAO,QAAQ;AAAA,IACjC;AAAA,IACA,cAAc,OAAO,YAAY,OAAO,EAAE,kBAAkB,MAAM,CAAC;AAAA,IACnE,2BAA2B,OAAO;AAAA,IAClC,WAAW,OAAO;AAAA,EACpB;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livekit/agents",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "LiveKit Agents - Node.js",
   "main": "dist/index.js",
   "require": "dist/index.cjs",
@@ -39,14 +39,21 @@
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "@livekit/mutex": "^1.1.1",
-    "@livekit/protocol": "^1.41.0",
+    "@livekit/protocol": "^1.43.0",
     "@livekit/typed-emitter": "^3.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.54.0",
+    "@opentelemetry/otlp-exporter-base": "^0.208.0",
+    "@opentelemetry/resources": "^1.28.0",
+    "@opentelemetry/sdk-trace-base": "^1.28.0",
+    "@opentelemetry/sdk-trace-node": "^1.28.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
     "@types/pidusage": "^2.0.5",
     "commander": "^12.0.0",
     "fluent-ffmpeg": "^2.1.3",
     "heap-js": "^2.6.0",
     "json-schema": "^0.4.0",
-    "livekit-server-sdk": "^2.13.3",
+    "livekit-server-sdk": "^2.14.1",
     "openai": "^6.8.1",
     "pidusage": "^4.0.1",
     "pino": "^8.19.0",

package/src/index.ts

@@ -16,6 +16,7 @@ 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 telemetry from './telemetry/index.js';
 import * as tokenize from './tokenize/index.js';
 import * as tts from './tts/index.js';
 import * as voice from './voice/index.js';
@@ -34,4 +35,4 @@ export * from './vad.js';
 export * from './version.js';
 export * from './worker.js';
 
-export { cli, inference, ipc, llm, metrics, stream, stt, tokenize, tts, voice };
+export { cli, inference, ipc, llm, metrics, stream, stt, telemetry, tokenize, tts, voice };

package/src/inference/tts.ts

@@ -421,7 +421,7 @@ export class SynthesizeStream<TModel extends TTSModels> extends BaseSynthesizeSt
         createRecvTask(),
       ]);
     } catch (e) {
-      this.#logger.error('Error in SynthesizeStream', { error: e });
+      this.#logger.error({ error: e }, 'Error in SynthesizeStream');
     } finally {
       resourceCleanup();
     }

package/src/ipc/job_proc_lazy_main.ts

@@ -88,7 +88,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(
@@ -109,6 +109,14 @@ const startJob = (
       process.send!({ case: 'exiting', value: { reason: close[1] } });
     });
 
+    // 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');
 
@@ -122,7 +130,7 @@ const startJob = (
 
     process.send!({ case: 'done' });
     joinFuture.resolve();
-  });
+  })();
 
   return { ctx, task };
 };

package/src/job.ts

@@ -14,6 +14,8 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import type { Logger } from 'pino';
 import type { InferenceExecutor } from './ipc/inference_executor.js';
 import { log } from './log.js';
+import type { AgentSession } from './voice/agent_session.js';
+import { type SessionReport, createSessionReport } from './voice/report.js';
 
 // AsyncLocalStorage for job context, similar to Python's contextvars
 const jobContextStorage = new AsyncLocalStorage<JobContext>();
@@ -79,6 +81,8 @@ export class FunctionExistsError extends Error {
 }
 
 /** The job and environment context as seen by the agent, accessible by the entrypoint function. */
+// TODO(brian): PR3 - Add @tracer.startActiveSpan('job_entrypoint') wrapper in entrypoint
+// TODO(brian): PR5 - Add uploadSessionReport() call in cleanup/session end
 export class JobContext {
   #proc: JobProcess;
   #info: RunningJobInfo;
@@ -97,6 +101,9 @@ export class JobContext {
   #logger: Logger;
   #inferenceExecutor: InferenceExecutor;
 
+  /** @internal */
+  _primaryAgentSession?: AgentSession;
+
   private connected: boolean = false;
 
   constructor(
@@ -232,6 +239,47 @@ export class JobContext {
     this.connected = true;
   }
 
+  makeSessionReport(session?: AgentSession): SessionReport {
+    const targetSession = session || this._primaryAgentSession;
+
+    if (!targetSession) {
+      throw new Error('Cannot prepare report, no AgentSession was found');
+    }
+
+    // TODO(brian): implement and check recorder io
+    // TODO(brian): PR5 - Ensure chat history serialization includes all required fields (use sessionReportToJSON helper)
+
+    return createSessionReport({
+      jobId: this.job.id,
+      roomId: this.job.room?.sid || '',
+      room: this.job.room?.name || '',
+      options: targetSession.options,
+      events: targetSession._recordedEvents,
+      enableUserDataTraining: true,
+      chatHistory: targetSession.history.copy(),
+    });
+  }
+
+  async _onSessionEnd(): Promise<void> {
+    const session = this._primaryAgentSession;
+    if (!session) {
+      return;
+    }
+
+    const report = this.makeSessionReport(session);
+
+    // TODO(brian): Implement CLI/console
+
+    // TODO(brian): PR5 - Call uploadSessionReport() if report.enableUserDataTraining is true
+    // TODO(brian): PR5 - Upload includes: multipart form with header (protobuf), chat_history (JSON), and audio recording (if available)
+
+    this.#logger.debug('Session ended, report generated', {
+      jobId: report.jobId,
+      roomId: report.roomId,
+      eventsCount: report.events.length,
+    });
+  }
+
   /**
    * Gracefully shuts down the job, and runs all shutdown promises.
    *

package/src/llm/chat_context.ts

@@ -300,7 +300,59 @@ export class FunctionCallOutput {
   }
 }
 
-export type ChatItem = ChatMessage | FunctionCall | FunctionCallOutput;
+export class AgentHandoffItem {
+  readonly id: string;
+
+  readonly type = 'agent_handoff' as const;
+
+  oldAgentId: string | undefined;
+
+  newAgentId: string;
+
+  createdAt: number;
+
+  constructor(params: {
+    oldAgentId?: string;
+    newAgentId: string;
+    id?: string;
+    createdAt?: number;
+  }) {
+    const { oldAgentId, newAgentId, id = shortuuid('item_'), createdAt = Date.now() } = params;
+    this.id = id;
+    this.oldAgentId = oldAgentId;
+    this.newAgentId = newAgentId;
+    this.createdAt = createdAt;
+  }
+
+  static create(params: {
+    oldAgentId?: string;
+    newAgentId: string;
+    id?: string;
+    createdAt?: number;
+  }) {
+    return new AgentHandoffItem(params);
+  }
+
+  toJSON(excludeTimestamp: boolean = false): JSONValue {
+    const result: JSONValue = {
+      id: this.id,
+      type: this.type,
+      newAgentId: this.newAgentId,
+    };
+
+    if (this.oldAgentId !== undefined) {
+      result.oldAgentId = this.oldAgentId;
+    }
+
+    if (!excludeTimestamp) {
+      result.createdAt = this.createdAt;
+    }
+
+    return result;
+  }
+}
+
+export type ChatItem = ChatMessage | FunctionCall | FunctionCallOutput | AgentHandoffItem;
 
 export class ChatContext {
   protected _items: ChatItem[];

package/src/llm/index.ts

@@ -17,6 +17,7 @@ export {
 } from './tool_context.js';
 
 export {
+  AgentHandoffItem,
   ChatContext,
   ChatMessage,
   createAudioContent,

package/src/llm/llm.ts

@@ -136,8 +136,10 @@ export abstract class LLMStream implements AsyncIterableIterator<ChatChunk> {
   }
 
   private async mainTask() {
+    // TODO(brian): PR3 - Add span wrapping: tracer.startActiveSpan('llm_request', ..., { endOnExit: false })
     for (let i = 0; i < this._connOptions.maxRetry + 1; i++) {
       try {
+        // TODO(brian): PR3 - Add span for retry attempts: tracer.startActiveSpan('llm_request_run', ...)
         return await this.run();
       } catch (error) {
         if (error instanceof APIError) {

package/src/llm/provider_format/google.test.ts

@@ -4,7 +4,12 @@
 import { VideoBufferType, VideoFrame } from '@livekit/rtc-node';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { initializeLogger } from '../../log.js';
-import { ChatContext, FunctionCall, FunctionCallOutput } from '../chat_context.js';
+import {
+  AgentHandoffItem,
+  ChatContext,
+  FunctionCall,
+  FunctionCallOutput,
+} from '../chat_context.js';
 import { serializeImage } from '../utils.js';
 import { toChatCtx } from './google.js';
 
@@ -769,4 +774,70 @@ describe('Google Provider Format - toChatCtx', () => {
     ]);
     expect(formatData.systemMessages).toBeNull();
   });
+
+  it('should filter out agent handoff items', async () => {
+    const ctx = ChatContext.empty();
+
+    ctx.addMessage({ role: 'user', content: 'Hello' });
+
+    // Insert an agent handoff item
+    const handoff = new AgentHandoffItem({
+      oldAgentId: 'agent_1',
+      newAgentId: 'agent_2',
+    });
+    ctx.insert(handoff);
+
+    ctx.addMessage({ role: 'assistant', content: 'Hi there!' });
+
+    const [result, formatData] = await toChatCtx(ctx, false);
+
+    // Agent handoff should be filtered out, only messages should remain
+    expect(result).toEqual([
+      {
+        role: 'user',
+        parts: [{ text: 'Hello' }],
+      },
+      {
+        role: 'model',
+        parts: [{ text: 'Hi there!' }],
+      },
+    ]);
+    expect(formatData.systemMessages).toBeNull();
+  });
+
+  it('should handle multiple agent handoffs without errors', async () => {
+    const ctx = ChatContext.empty();
+
+    ctx.addMessage({ role: 'user', content: 'Start' });
+
+    // Multiple handoffs
+    ctx.insert(new AgentHandoffItem({ oldAgentId: undefined, newAgentId: 'agent_1' }));
+    ctx.addMessage({ role: 'assistant', content: 'Response from agent 1' });
+
+    ctx.insert(new AgentHandoffItem({ oldAgentId: 'agent_1', newAgentId: 'agent_2' }));
+    ctx.addMessage({ role: 'assistant', content: 'Response from agent 2' });
+
+    ctx.insert(new AgentHandoffItem({ oldAgentId: 'agent_2', newAgentId: 'agent_3' }));
+    ctx.addMessage({ role: 'assistant', content: 'Response from agent 3' });
+
+    const [result, formatData] = await toChatCtx(ctx, false);
+
+    // All handoffs should be filtered out
+    // Note: Google provider groups consecutive messages by the same role
+    expect(result).toEqual([
+      {
+        role: 'user',
+        parts: [{ text: 'Start' }],
+      },
+      {
+        role: 'model',
+        parts: [
+          { text: 'Response from agent 1' },
+          { text: 'Response from agent 2' },
+          { text: 'Response from agent 3' },
+        ],
+      },
+    ]);
+    expect(formatData.systemMessages).toBeNull();
+  });
 });

package/src/llm/provider_format/openai.test.ts

@@ -4,7 +4,12 @@
 import { VideoBufferType, VideoFrame } from '@livekit/rtc-node';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { initializeLogger } from '../../log.js';
-import { ChatContext, FunctionCall, FunctionCallOutput } from '../chat_context.js';
+import {
+  AgentHandoffItem,
+  ChatContext,
+  FunctionCall,
+  FunctionCallOutput,
+} from '../chat_context.js';
 import { serializeImage } from '../utils.js';
 import { toChatCtx } from './openai.js';
 
@@ -578,4 +583,53 @@ describe('toChatCtx', () => {
       },
     ]);
   });
+
+  it('should filter out agent handoff items', async () => {
+    const ctx = ChatContext.empty();
+
+    ctx.addMessage({ role: 'user', content: 'Hello' });
+
+    // Insert an agent handoff item
+    const handoff = new AgentHandoffItem({
+      oldAgentId: 'agent_1',
+      newAgentId: 'agent_2',
+    });
+    ctx.insert(handoff);
+
+    ctx.addMessage({ role: 'assistant', content: 'Hi there!' });
+
+    const result = await toChatCtx(ctx);
+
+    // Agent handoff should be filtered out, only messages should remain
+    expect(result).toEqual([
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there!' },
+    ]);
+  });
+
+  it('should handle multiple agent handoffs without errors', async () => {
+    const ctx = ChatContext.empty();
+
+    ctx.addMessage({ role: 'user', content: 'Start' });
+
+    // Multiple handoffs
+    ctx.insert(new AgentHandoffItem({ oldAgentId: undefined, newAgentId: 'agent_1' }));
+    ctx.addMessage({ role: 'assistant', content: 'Response from agent 1' });
+
+    ctx.insert(new AgentHandoffItem({ oldAgentId: 'agent_1', newAgentId: 'agent_2' }));
+    ctx.addMessage({ role: 'assistant', content: 'Response from agent 2' });
+
+    ctx.insert(new AgentHandoffItem({ oldAgentId: 'agent_2', newAgentId: 'agent_3' }));
+    ctx.addMessage({ role: 'assistant', content: 'Response from agent 3' });
+
+    const result = await toChatCtx(ctx);
+
+    // All handoffs should be filtered out
+    expect(result).toEqual([
+      { role: 'user', content: 'Start' },
+      { role: 'assistant', content: 'Response from agent 1' },
+      { role: 'assistant', content: 'Response from agent 2' },
+      { role: 'assistant', content: 'Response from agent 3' },
+    ]);
+  });
 });

package/src/llm/provider_format/openai.ts

@@ -78,9 +78,10 @@ async function toChatItem(item: ChatItem) {
       tool_call_id: item.callId,
       content: item.output,
     };
-  } else {
-    throw new Error(`Unsupported item type: ${item['type']}`);
   }
+  // Skip other item types (e.g., agent_handoff)
+  // These should be filtered by groupToolCalls, but this is a safety net
+  throw new Error(`Unsupported item type: ${item['type']}`);
 }
 
 async function toImageContent(content: ImageContent) {

package/src/log.ts

@@ -42,4 +42,5 @@ export const initializeLogger = ({ pretty, level }: LoggerOptions) => {
   if (level) {
     logger.level = level;
   }
+  // TODO(brian): PR4 - Add Pino bridge to OTEL LoggingHandler for structured logging integration
 };