@livekit/agents 1.1.0 → 1.2.1

package/src/job.ts

@@ -11,9 +11,15 @@ import type {
 } from '@livekit/rtc-node';
 import { ParticipantKind, RoomEvent, TrackKind } from '@livekit/rtc-node';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import type { Logger } from 'pino';
 import type { InferenceExecutor } from './ipc/inference_executor.js';
 import { log } from './log.js';
+import { flushOtelLogs, setupCloudTracer, uploadSessionReport } from './telemetry/index.js';
+import { isCloud } from './utils.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>();
@@ -97,6 +103,12 @@ export class JobContext {
   #logger: Logger;
   #inferenceExecutor: InferenceExecutor;
 
+  /** @internal */
+  _primaryAgentSession?: AgentSession;
+
+  /** @internal */
+  _sessionDirectory: string;
+
   private connected: boolean = false;
 
   constructor(
@@ -114,8 +126,12 @@ export class JobContext {
     this.#onShutdown = onShutdown;
     this.onParticipantConnected = this.onParticipantConnected.bind(this);
     this.#room.on(RoomEvent.ParticipantConnected, this.onParticipantConnected);
-    this.#logger = log().child({ info: this.#info });
+    this.#logger = log().child({
+      jobId: this.#info.job.id,
+      roomName: this.#info.job.room?.name,
+    });
     this.#inferenceExecutor = inferenceExecutor;
+    this._sessionDirectory = path.join(os.tmpdir(), 'livekit-agents', `job-${this.#info.job.id}`);
   }
 
   get proc(): JobProcess {
@@ -135,6 +151,10 @@ export class JobContext {
     return this.#room;
   }
 
+  get info(): RunningJobInfo {
+    return this.#info;
+  }
+
   /** @returns The agent's participant if connected to the room, otherwise `undefined` */
   get agent(): LocalParticipant | undefined {
     return this.#room.localParticipant;
@@ -145,6 +165,13 @@ export class JobContext {
     return this.#inferenceExecutor;
   }
 
+  /**
+   * @returns The session directory for storing recordings and session data.
+   */
+  get sessionDirectory(): string {
+    return this._sessionDirectory;
+  }
+
   /** Adds a promise to be awaited when {@link JobContext.shutdown | shutdown} is called. */
   addShutdownCallback(callback: () => Promise<void>) {
     this.shutdownCallbacks.push(callback);
@@ -232,6 +259,84 @@ 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');
+    }
+
+    const recorderIO = targetSession._recorderIO;
+
+    if (recorderIO && recorderIO.recording) {
+      throw new Error('Cannot create the AgentSession report, the RecorderIO is still recording');
+    }
+
+    return createSessionReport({
+      jobId: this.job.id,
+      roomId: this.job.room?.sid || '',
+      room: this.job.room?.name || '',
+      options: targetSession.sessionOptions,
+      events: targetSession._recordedEvents,
+      enableRecording: targetSession._enableRecording,
+      chatHistory: targetSession.history.copy(),
+      startedAt: targetSession._startedAt,
+      audioRecordingPath: recorderIO?.outputPath,
+      audioRecordingStartedAt: recorderIO?.recordingStartedAt,
+    });
+  }
+
+  async _onSessionEnd(): Promise<void> {
+    const session = this._primaryAgentSession;
+    if (!session) {
+      return;
+    }
+
+    const report = this.makeSessionReport(session);
+
+    // TODO(brian): Implement CLI/console
+
+    // Upload session report to LiveKit Cloud if enabled
+    const url = new URL(this.#info.url);
+
+    if (report.enableRecording && isCloud(url)) {
+      try {
+        await 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',
+    );
+
+    // Explicitly clear the recorded events to avoid leaking memory
+    session._recordedEvents = [];
+
+    try {
+      await flushOtelLogs();
+    } catch (error) {
+      this.#logger.error({ error }, 'Failed to flush OTEL logs');
+    }
+  }
+
   /**
    * Gracefully shuts down the job, and runs all shutdown promises.
    *
@@ -268,6 +373,20 @@ export class JobContext {
 
     this.#participantEntrypoints.push(callback);
   }
+
+  async initRecording() {
+    const url = new URL(this.#info.url);
+    if (!isCloud(url)) {
+      return;
+    }
+
+    this.#logger.debug({ hostname: url.hostname }, 'Configuring session recording (cloud tracer)');
+    await setupCloudTracer({
+      roomId: this.job.room!.sid,
+      jobId: this.job.id,
+      cloudHostname: url.hostname,
+    });
+  }
 }
 
 export class JobProcess {

package/src/language.test.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import {
+  areLanguagesEquivalent,
+  getBaseLanguage,
+  getIsoLanguage,
+  getLanguageRegion,
+  normalizeLanguage,
+  toLanguageName,
+} from './language.js';
+
+describe('normalizeLanguage', () => {
+  it('normalizes language names', () => {
+    expect(normalizeLanguage('english')).toBe('en');
+  });
+
+  it('normalizes iso 639-3 codes', () => {
+    expect(normalizeLanguage('eng')).toBe('en');
+  });
+
+  it('normalizes bcp-47 casing and separators', () => {
+    expect(normalizeLanguage('en_us')).toBe('en-US');
+    expect(normalizeLanguage('zh_hans_cn')).toBe('zh-Hans-CN');
+  });
+
+  it('preserves iso 639-3 in compound tags', () => {
+    expect(normalizeLanguage('cmn_hans_cn')).toBe('cmn-Hans-CN');
+  });
+
+  it('passes unknown codes through in lowercase', () => {
+    expect(normalizeLanguage('MULTI')).toBe('multi');
+  });
+
+  it('preserves empty string sentinel', () => {
+    expect(normalizeLanguage('')).toBe('');
+  });
+});
+
+describe('language helpers', () => {
+  it('extracts base language', () => {
+    expect(getBaseLanguage('cmn-Hans-CN')).toBe('zh');
+  });
+
+  it('builds iso language tag', () => {
+    expect(getIsoLanguage('cmn-Hans-CN')).toBe('zh-CN');
+  });
+
+  it('extracts region', () => {
+    expect(getLanguageRegion('en-US')).toBe('US');
+  });
+
+  it('maps normalized code back to language name', () => {
+    expect(toLanguageName('eng')).toBe('english');
+  });
+
+  it('compares equivalent representations', () => {
+    expect(areLanguagesEquivalent('english', 'en')).toBe(true);
+    expect(areLanguagesEquivalent('en_us', 'en-US')).toBe(true);
+  });
+});

package/src/language.ts

@@ -0,0 +1,380 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+export const KNOWN_LANGUAGE_CODES = [
+  'af',
+  'am',
+  'ar',
+  'as',
+  'az',
+  'be',
+  'bg',
+  'bn',
+  'bs',
+  'ca',
+  'cs',
+  'cy',
+  'da',
+  'de',
+  'el',
+  'en',
+  'es',
+  'et',
+  'eu',
+  'fa',
+  'ff',
+  'fi',
+  'fr',
+  'ga',
+  'gl',
+  'gu',
+  'ha',
+  'he',
+  'hi',
+  'hr',
+  'hu',
+  'hy',
+  'id',
+  'ig',
+  'is',
+  'it',
+  'ja',
+  'jv',
+  'ka',
+  'kk',
+  'km',
+  'kn',
+  'ko',
+  'ku',
+  'ky',
+  'lb',
+  'lg',
+  'ln',
+  'lo',
+  'lt',
+  'lv',
+  'mi',
+  'mk',
+  'ml',
+  'mn',
+  'mr',
+  'ms',
+  'mt',
+  'my',
+  'ne',
+  'nl',
+  'no',
+  'ny',
+  'oc',
+  'or',
+  'pa',
+  'pl',
+  'ps',
+  'pt',
+  'ro',
+  'ru',
+  'sd',
+  'sk',
+  'sl',
+  'sn',
+  'so',
+  'sq',
+  'sr',
+  'sv',
+  'sw',
+  'ta',
+  'te',
+  'tg',
+  'th',
+  'tl',
+  'tr',
+  'uk',
+  'ur',
+  'uz',
+  'vi',
+  'wo',
+  'xh',
+  'yo',
+  'zh',
+  'zu',
+] as const;
+
+export type KnownLanguageCode = (typeof KNOWN_LANGUAGE_CODES)[number];
+
+declare const languageCodeBrand: unique symbol;
+
+export type LanguageCode = string & { readonly [languageCodeBrand]: 'LanguageCode' };
+
+export function asLanguageCode(language: string): LanguageCode {
+  return language as LanguageCode;
+}
+
+const ISO_639_3_TO_1: Record<string, string | undefined> = {
+  afr: 'af',
+  amh: 'am',
+  ara: 'ar',
+  hye: 'hy',
+  asm: 'as',
+  ast: undefined,
+  aze: 'az',
+  bel: 'be',
+  ben: 'bn',
+  bos: 'bs',
+  bul: 'bg',
+  mya: 'my',
+  yue: undefined,
+  cat: 'ca',
+  ceb: undefined,
+  cmn: 'zh',
+  nya: 'ny',
+  hrv: 'hr',
+  ces: 'cs',
+  dan: 'da',
+  nld: 'nl',
+  eng: 'en',
+  est: 'et',
+  fil: undefined,
+  fin: 'fi',
+  fra: 'fr',
+  ful: 'ff',
+  glg: 'gl',
+  lug: 'lg',
+  kat: 'ka',
+  deu: 'de',
+  ell: 'el',
+  guj: 'gu',
+  hau: 'ha',
+  heb: 'he',
+  hin: 'hi',
+  hun: 'hu',
+  isl: 'is',
+  ibo: 'ig',
+  ind: 'id',
+  gle: 'ga',
+  ita: 'it',
+  jpn: 'ja',
+  jav: 'jv',
+  kea: undefined,
+  kan: 'kn',
+  kaz: 'kk',
+  khm: 'km',
+  kor: 'ko',
+  kur: 'ku',
+  kir: 'ky',
+  lao: 'lo',
+  lav: 'lv',
+  lin: 'ln',
+  lit: 'lt',
+  luo: undefined,
+  ltz: 'lb',
+  mkd: 'mk',
+  msa: 'ms',
+  mal: 'ml',
+  mlt: 'mt',
+  zho: 'zh',
+  mri: 'mi',
+  mar: 'mr',
+  mon: 'mn',
+  nep: 'ne',
+  nso: undefined,
+  nor: 'no',
+  oci: 'oc',
+  ori: 'or',
+  pus: 'ps',
+  fas: 'fa',
+  pol: 'pl',
+  por: 'pt',
+  pan: 'pa',
+  ron: 'ro',
+  rus: 'ru',
+  srp: 'sr',
+  sna: 'sn',
+  snd: 'sd',
+  slk: 'sk',
+  slv: 'sl',
+  som: 'so',
+  spa: 'es',
+  swa: 'sw',
+  swe: 'sv',
+  tam: 'ta',
+  tgk: 'tg',
+  tel: 'te',
+  tha: 'th',
+  tur: 'tr',
+  ukr: 'uk',
+  umb: undefined,
+  urd: 'ur',
+  uzb: 'uz',
+  vie: 'vi',
+  cym: 'cy',
+  wol: 'wo',
+  xho: 'xh',
+  zul: 'zu',
+};
+
+const LANGUAGE_NAMES_TO_CODE: Record<string, string> = {
+  afrikaans: 'af',
+  albanian: 'sq',
+  amharic: 'am',
+  arabic: 'ar',
+  armenian: 'hy',
+  azerbaijani: 'az',
+  basque: 'eu',
+  belarusian: 'be',
+  bengali: 'bn',
+  bosnian: 'bs',
+  bulgarian: 'bg',
+  burmese: 'my',
+  catalan: 'ca',
+  chinese: 'zh',
+  croatian: 'hr',
+  czech: 'cs',
+  danish: 'da',
+  dutch: 'nl',
+  english: 'en',
+  estonian: 'et',
+  finnish: 'fi',
+  french: 'fr',
+  galician: 'gl',
+  georgian: 'ka',
+  german: 'de',
+  greek: 'el',
+  gujarati: 'gu',
+  hausa: 'ha',
+  hebrew: 'he',
+  hindi: 'hi',
+  hungarian: 'hu',
+  icelandic: 'is',
+  indonesian: 'id',
+  irish: 'ga',
+  italian: 'it',
+  japanese: 'ja',
+  javanese: 'jv',
+  kannada: 'kn',
+  kazakh: 'kk',
+  khmer: 'km',
+  korean: 'ko',
+  kurdish: 'ku',
+  kyrgyz: 'ky',
+  lao: 'lo',
+  latvian: 'lv',
+  lingala: 'ln',
+  lithuanian: 'lt',
+  luxembourgish: 'lb',
+  macedonian: 'mk',
+  malay: 'ms',
+  malayalam: 'ml',
+  maltese: 'mt',
+  maori: 'mi',
+  marathi: 'mr',
+  mongolian: 'mn',
+  nepali: 'ne',
+  norwegian: 'no',
+  occitan: 'oc',
+  oriya: 'or',
+  pashto: 'ps',
+  persian: 'fa',
+  polish: 'pl',
+  portuguese: 'pt',
+  punjabi: 'pa',
+  romanian: 'ro',
+  russian: 'ru',
+  serbian: 'sr',
+  shona: 'sn',
+  sindhi: 'sd',
+  slovak: 'sk',
+  slovene: 'sl',
+  slovenian: 'sl',
+  somali: 'so',
+  spanish: 'es',
+  swahili: 'sw',
+  swedish: 'sv',
+  tagalog: 'tl',
+  tamil: 'ta',
+  tajik: 'tg',
+  telugu: 'te',
+  thai: 'th',
+  turkish: 'tr',
+  ukrainian: 'uk',
+  urdu: 'ur',
+  uzbek: 'uz',
+  vietnamese: 'vi',
+  welsh: 'cy',
+  wolof: 'wo',
+  xhosa: 'xh',
+  yoruba: 'yo',
+  zulu: 'zu',
+};
+
+const CODE_TO_LANGUAGE_NAME: Record<string, string> = Object.fromEntries(
+  Object.entries(LANGUAGE_NAMES_TO_CODE).map(([name, code]) => [code, name]),
+);
+
+CODE_TO_LANGUAGE_NAME.sl = 'slovene';
+
+export function normalizeLanguage(language: string): LanguageCode {
+  const lowered = language.trim().toLowerCase();
+  if (lowered === '') {
+    return asLanguageCode('');
+  }
+
+  if (lowered in LANGUAGE_NAMES_TO_CODE) {
+    return asLanguageCode(LANGUAGE_NAMES_TO_CODE[lowered]!);
+  }
+
+  if (lowered in ISO_639_3_TO_1) {
+    return asLanguageCode(ISO_639_3_TO_1[lowered] ?? lowered);
+  }
+
+  const parts = lowered.replaceAll('_', '-').split('-');
+  if (parts.length >= 2) {
+    const [base, ...rest] = parts;
+    return asLanguageCode(
+      [
+        base,
+        ...rest.map((part) => {
+          if (part.length === 4) {
+            return part.charAt(0).toUpperCase() + part.slice(1);
+          }
+          return part.toUpperCase();
+        }),
+      ].join('-'),
+    );
+  }
+
+  return asLanguageCode(lowered);
+}
+
+export function getBaseLanguage(language: string): string {
+  const normalized = normalizeLanguage(language);
+  const [base = ''] = normalized.split('-');
+  return ISO_639_3_TO_1[base] ?? base;
+}
+
+export function getIsoLanguage(language: string): string {
+  const normalized = normalizeLanguage(language);
+  const region = getLanguageRegion(normalized);
+  const baseLanguage = getBaseLanguage(normalized);
+  return region ? `${baseLanguage}-${region}` : baseLanguage;
+}
+
+export function getLanguageRegion(language: string): string | undefined {
+  const normalized = normalizeLanguage(language);
+  const [, ...parts] = normalized.split('-');
+  return parts.find((part) => part.length === 2);
+}
+
+export function toLanguageName(language: string): string | undefined {
+  return CODE_TO_LANGUAGE_NAME[getBaseLanguage(language)];
+}
+
+export function areLanguagesEquivalent(
+  left: string | null | undefined,
+  right: string | null | undefined,
+): boolean {
+  if (left == null || right == null) {
+    return left === right;
+  }
+  return normalizeLanguage(left) === normalizeLanguage(right);
+}