@livekit/agents-plugin-protoface 1.5.3

package/dist/api.test.cjs

@@ -0,0 +1,55 @@
+"use strict";
+var import_vitest = require("vitest");
+var import_api = require("./api.cjs");
+(0, import_vitest.describe)("ProtofaceAPI", () => {
+  (0, import_vitest.afterEach)(() => {
+    import_vitest.vi.unstubAllEnvs();
+    import_vitest.vi.unstubAllGlobals();
+  });
+  (0, import_vitest.it)("requires an API key", () => {
+    import_vitest.vi.stubEnv("PROTOFACE_API_KEY", "");
+    (0, import_vitest.expect)(() => new import_api.ProtofaceAPI()).toThrow(import_api.ProtofaceException);
+  });
+  (0, import_vitest.it)("uses env configuration and sends the expected start session request", async () => {
+    import_vitest.vi.stubEnv("PROTOFACE_API_KEY", "sk_test");
+    import_vitest.vi.stubEnv("PROTOFACE_API_URL", "https://api.example.test/");
+    const fetchMock = import_vitest.vi.fn(async () => new Response('{"id":"sess_test"}', { status: 200 }));
+    import_vitest.vi.stubGlobal("fetch", fetchMock);
+    const client = new import_api.ProtofaceAPI();
+    const session = await client.startSession({
+      avatarId: "av_test",
+      transport: { type: "livekit" },
+      maxDurationMs: 12e4
+    });
+    (0, import_vitest.expect)(session).toEqual({ id: "sess_test" });
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledTimes(1);
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledWith(
+      "https://api.example.test/v1/sessions",
+      import_vitest.expect.objectContaining({
+        method: "POST",
+        headers: import_vitest.expect.objectContaining({
+          accept: "application/json",
+          authorization: "Bearer sk_test",
+          "content-type": "application/json",
+          "user-agent": "@livekit/agents-plugin-protoface/0.0.0-test"
+        }),
+        body: JSON.stringify({
+          avatar_id: "av_test",
+          transport: { type: "livekit" },
+          max_duration_seconds: 120
+        })
+      })
+    );
+  });
+  (0, import_vitest.it)("ends a session", async () => {
+    const fetchMock = import_vitest.vi.fn(async () => new Response("{}", { status: 200 }));
+    import_vitest.vi.stubGlobal("fetch", fetchMock);
+    const client = new import_api.ProtofaceAPI({ apiKey: "sk_test", apiUrl: "https://api.example.test" });
+    await (0, import_vitest.expect)(client.endSession("sess_test")).resolves.toEqual({});
+    (0, import_vitest.expect)(fetchMock).toHaveBeenCalledWith(
+      "https://api.example.test/v1/sessions/sess_test/end",
+      import_vitest.expect.objectContaining({ method: "POST" })
+    );
+  });
+});
+//# sourceMappingURL=api.test.cjs.map

package/dist/api.test.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { afterEach, describe, expect, it, vi } from 'vitest';\nimport { ProtofaceAPI, ProtofaceException } from './api.js';\n\ndescribe('ProtofaceAPI', () => {\n  afterEach(() => {\n    vi.unstubAllEnvs();\n    vi.unstubAllGlobals();\n  });\n\n  it('requires an API key', () => {\n    vi.stubEnv('PROTOFACE_API_KEY', '');\n\n    expect(() => new ProtofaceAPI()).toThrow(ProtofaceException);\n  });\n\n  it('uses env configuration and sends the expected start session request', async () => {\n    vi.stubEnv('PROTOFACE_API_KEY', 'sk_test');\n    vi.stubEnv('PROTOFACE_API_URL', 'https://api.example.test/');\n    const fetchMock = vi.fn(async () => new Response('{\"id\":\"sess_test\"}', { status: 200 }));\n    vi.stubGlobal('fetch', fetchMock);\n\n    const client = new ProtofaceAPI();\n    const session = await client.startSession({\n      avatarId: 'av_test',\n      transport: { type: 'livekit' },\n      maxDurationMs: 120_000,\n    });\n\n    expect(session).toEqual({ id: 'sess_test' });\n    expect(fetchMock).toHaveBeenCalledTimes(1);\n    expect(fetchMock).toHaveBeenCalledWith(\n      'https://api.example.test/v1/sessions',\n      expect.objectContaining({\n        method: 'POST',\n        headers: expect.objectContaining({\n          accept: 'application/json',\n          authorization: 'Bearer sk_test',\n          'content-type': 'application/json',\n          'user-agent': '@livekit/agents-plugin-protoface/0.0.0-test',\n        }),\n        body: JSON.stringify({\n          avatar_id: 'av_test',\n          transport: { type: 'livekit' },\n          max_duration_seconds: 120,\n        }),\n      }),\n    );\n  });\n\n  it('ends a session', async () => {\n    const fetchMock = vi.fn(async () => new Response('{}', { status: 200 }));\n    vi.stubGlobal('fetch', fetchMock);\n\n    const client = new ProtofaceAPI({ apiKey: 'sk_test', apiUrl: 'https://api.example.test' });\n    await expect(client.endSession('sess_test')).resolves.toEqual({});\n\n    expect(fetchMock).toHaveBeenCalledWith(\n      'https://api.example.test/v1/sessions/sess_test/end',\n      expect.objectContaining({ method: 'POST' }),\n    );\n  });\n});\n"],"mappings":";AAGA,oBAAoD;AACpD,iBAAiD;AAAA,IAEjD,wBAAS,gBAAgB,MAAM;AAC7B,+BAAU,MAAM;AACd,qBAAG,cAAc;AACjB,qBAAG,iBAAiB;AAAA,EACtB,CAAC;AAED,wBAAG,uBAAuB,MAAM;AAC9B,qBAAG,QAAQ,qBAAqB,EAAE;AAElC,8BAAO,MAAM,IAAI,wBAAa,CAAC,EAAE,QAAQ,6BAAkB;AAAA,EAC7D,CAAC;AAED,wBAAG,uEAAuE,YAAY;AACpF,qBAAG,QAAQ,qBAAqB,SAAS;AACzC,qBAAG,QAAQ,qBAAqB,2BAA2B;AAC3D,UAAM,YAAY,iBAAG,GAAG,YAAY,IAAI,SAAS,sBAAsB,EAAE,QAAQ,IAAI,CAAC,CAAC;AACvF,qBAAG,WAAW,SAAS,SAAS;AAEhC,UAAM,SAAS,IAAI,wBAAa;AAChC,UAAM,UAAU,MAAM,OAAO,aAAa;AAAA,MACxC,UAAU;AAAA,MACV,WAAW,EAAE,MAAM,UAAU;AAAA,MAC7B,eAAe;AAAA,IACjB,CAAC;AAED,8BAAO,OAAO,EAAE,QAAQ,EAAE,IAAI,YAAY,CAAC;AAC3C,8BAAO,SAAS,EAAE,sBAAsB,CAAC;AACzC,8BAAO,SAAS,EAAE;AAAA,MAChB;AAAA,MACA,qBAAO,iBAAiB;AAAA,QACtB,QAAQ;AAAA,QACR,SAAS,qBAAO,iBAAiB;AAAA,UAC/B,QAAQ;AAAA,UACR,eAAe;AAAA,UACf,gBAAgB;AAAA,UAChB,cAAc;AAAA,QAChB,CAAC;AAAA,QACD,MAAM,KAAK,UAAU;AAAA,UACnB,WAAW;AAAA,UACX,WAAW,EAAE,MAAM,UAAU;AAAA,UAC7B,sBAAsB;AAAA,QACxB,CAAC;AAAA,MACH,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AAED,wBAAG,kBAAkB,YAAY;AAC/B,UAAM,YAAY,iBAAG,GAAG,YAAY,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC,CAAC;AACvE,qBAAG,WAAW,SAAS,SAAS;AAEhC,UAAM,SAAS,IAAI,wBAAa,EAAE,QAAQ,WAAW,QAAQ,2BAA2B,CAAC;AACzF,cAAM,sBAAO,OAAO,WAAW,WAAW,CAAC,EAAE,SAAS,QAAQ,CAAC,CAAC;AAEhE,8BAAO,SAAS,EAAE;AAAA,MAChB;AAAA,MACA,qBAAO,iBAAiB,EAAE,QAAQ,OAAO,CAAC;AAAA,IAC5C;AAAA,EACF,CAAC;AACH,CAAC;","names":[]}

package/dist/api.test.d.cts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.test.d.ts.map

package/dist/api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.test.d.ts.map

package/dist/api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../src/api.test.ts"],"names":[],"mappings":""}

package/dist/api.test.js

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ProtofaceAPI, ProtofaceException } from "./api.js";
+describe("ProtofaceAPI", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+  });
+  it("requires an API key", () => {
+    vi.stubEnv("PROTOFACE_API_KEY", "");
+    expect(() => new ProtofaceAPI()).toThrow(ProtofaceException);
+  });
+  it("uses env configuration and sends the expected start session request", async () => {
+    vi.stubEnv("PROTOFACE_API_KEY", "sk_test");
+    vi.stubEnv("PROTOFACE_API_URL", "https://api.example.test/");
+    const fetchMock = vi.fn(async () => new Response('{"id":"sess_test"}', { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const client = new ProtofaceAPI();
+    const session = await client.startSession({
+      avatarId: "av_test",
+      transport: { type: "livekit" },
+      maxDurationMs: 12e4
+    });
+    expect(session).toEqual({ id: "sess_test" });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://api.example.test/v1/sessions",
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          accept: "application/json",
+          authorization: "Bearer sk_test",
+          "content-type": "application/json",
+          "user-agent": "@livekit/agents-plugin-protoface/0.0.0-test"
+        }),
+        body: JSON.stringify({
+          avatar_id: "av_test",
+          transport: { type: "livekit" },
+          max_duration_seconds: 120
+        })
+      })
+    );
+  });
+  it("ends a session", async () => {
+    const fetchMock = vi.fn(async () => new Response("{}", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    const client = new ProtofaceAPI({ apiKey: "sk_test", apiUrl: "https://api.example.test" });
+    await expect(client.endSession("sess_test")).resolves.toEqual({});
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://api.example.test/v1/sessions/sess_test/end",
+      expect.objectContaining({ method: "POST" })
+    );
+  });
+});
+//# sourceMappingURL=api.test.js.map

package/dist/api.test.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/api.test.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport { afterEach, describe, expect, it, vi } from 'vitest';\nimport { ProtofaceAPI, ProtofaceException } from './api.js';\n\ndescribe('ProtofaceAPI', () => {\n  afterEach(() => {\n    vi.unstubAllEnvs();\n    vi.unstubAllGlobals();\n  });\n\n  it('requires an API key', () => {\n    vi.stubEnv('PROTOFACE_API_KEY', '');\n\n    expect(() => new ProtofaceAPI()).toThrow(ProtofaceException);\n  });\n\n  it('uses env configuration and sends the expected start session request', async () => {\n    vi.stubEnv('PROTOFACE_API_KEY', 'sk_test');\n    vi.stubEnv('PROTOFACE_API_URL', 'https://api.example.test/');\n    const fetchMock = vi.fn(async () => new Response('{\"id\":\"sess_test\"}', { status: 200 }));\n    vi.stubGlobal('fetch', fetchMock);\n\n    const client = new ProtofaceAPI();\n    const session = await client.startSession({\n      avatarId: 'av_test',\n      transport: { type: 'livekit' },\n      maxDurationMs: 120_000,\n    });\n\n    expect(session).toEqual({ id: 'sess_test' });\n    expect(fetchMock).toHaveBeenCalledTimes(1);\n    expect(fetchMock).toHaveBeenCalledWith(\n      'https://api.example.test/v1/sessions',\n      expect.objectContaining({\n        method: 'POST',\n        headers: expect.objectContaining({\n          accept: 'application/json',\n          authorization: 'Bearer sk_test',\n          'content-type': 'application/json',\n          'user-agent': '@livekit/agents-plugin-protoface/0.0.0-test',\n        }),\n        body: JSON.stringify({\n          avatar_id: 'av_test',\n          transport: { type: 'livekit' },\n          max_duration_seconds: 120,\n        }),\n      }),\n    );\n  });\n\n  it('ends a session', async () => {\n    const fetchMock = vi.fn(async () => new Response('{}', { status: 200 }));\n    vi.stubGlobal('fetch', fetchMock);\n\n    const client = new ProtofaceAPI({ apiKey: 'sk_test', apiUrl: 'https://api.example.test' });\n    await expect(client.endSession('sess_test')).resolves.toEqual({});\n\n    expect(fetchMock).toHaveBeenCalledWith(\n      'https://api.example.test/v1/sessions/sess_test/end',\n      expect.objectContaining({ method: 'POST' }),\n    );\n  });\n});\n"],"mappings":"AAGA,SAAS,WAAW,UAAU,QAAQ,IAAI,UAAU;AACpD,SAAS,cAAc,0BAA0B;AAEjD,SAAS,gBAAgB,MAAM;AAC7B,YAAU,MAAM;AACd,OAAG,cAAc;AACjB,OAAG,iBAAiB;AAAA,EACtB,CAAC;AAED,KAAG,uBAAuB,MAAM;AAC9B,OAAG,QAAQ,qBAAqB,EAAE;AAElC,WAAO,MAAM,IAAI,aAAa,CAAC,EAAE,QAAQ,kBAAkB;AAAA,EAC7D,CAAC;AAED,KAAG,uEAAuE,YAAY;AACpF,OAAG,QAAQ,qBAAqB,SAAS;AACzC,OAAG,QAAQ,qBAAqB,2BAA2B;AAC3D,UAAM,YAAY,GAAG,GAAG,YAAY,IAAI,SAAS,sBAAsB,EAAE,QAAQ,IAAI,CAAC,CAAC;AACvF,OAAG,WAAW,SAAS,SAAS;AAEhC,UAAM,SAAS,IAAI,aAAa;AAChC,UAAM,UAAU,MAAM,OAAO,aAAa;AAAA,MACxC,UAAU;AAAA,MACV,WAAW,EAAE,MAAM,UAAU;AAAA,MAC7B,eAAe;AAAA,IACjB,CAAC;AAED,WAAO,OAAO,EAAE,QAAQ,EAAE,IAAI,YAAY,CAAC;AAC3C,WAAO,SAAS,EAAE,sBAAsB,CAAC;AACzC,WAAO,SAAS,EAAE;AAAA,MAChB;AAAA,MACA,OAAO,iBAAiB;AAAA,QACtB,QAAQ;AAAA,QACR,SAAS,OAAO,iBAAiB;AAAA,UAC/B,QAAQ;AAAA,UACR,eAAe;AAAA,UACf,gBAAgB;AAAA,UAChB,cAAc;AAAA,QAChB,CAAC;AAAA,QACD,MAAM,KAAK,UAAU;AAAA,UACnB,WAAW;AAAA,UACX,WAAW,EAAE,MAAM,UAAU;AAAA,UAC7B,sBAAsB;AAAA,QACxB,CAAC;AAAA,MACH,CAAC;AAAA,IACH;AAAA,EACF,CAAC;AAED,KAAG,kBAAkB,YAAY;AAC/B,UAAM,YAAY,GAAG,GAAG,YAAY,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC,CAAC;AACvE,OAAG,WAAW,SAAS,SAAS;AAEhC,UAAM,SAAS,IAAI,aAAa,EAAE,QAAQ,WAAW,QAAQ,2BAA2B,CAAC;AACzF,UAAM,OAAO,OAAO,WAAW,WAAW,CAAC,EAAE,SAAS,QAAQ,CAAC,CAAC;AAEhE,WAAO,SAAS,EAAE;AAAA,MAChB;AAAA,MACA,OAAO,iBAAiB,EAAE,QAAQ,OAAO,CAAC;AAAA,IAC5C;AAAA,EACF,CAAC;AACH,CAAC;","names":[]}

package/dist/avatar.cjs

@@ -0,0 +1,160 @@
+"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 avatar_exports = {};
+__export(avatar_exports, {
+  AvatarSession: () => AvatarSession,
+  DEFAULT_STOCK_AVATAR_ID: () => DEFAULT_STOCK_AVATAR_ID
+});
+module.exports = __toCommonJS(avatar_exports);
+var import_agents = require("@livekit/agents");
+var import_rtc_node = require("@livekit/rtc-node");
+var import_livekit_server_sdk = require("livekit-server-sdk");
+var import_api = require("./api.cjs");
+var import_log = require("./log.cjs");
+const DEFAULT_STOCK_AVATAR_ID = "av_stock_001";
+const ATTRIBUTE_PUBLISH_ON_BEHALF = "lk.publish_on_behalf";
+const SAMPLE_RATE = 16e3;
+const AVATAR_AGENT_IDENTITY = "protoface-avatar-agent";
+const AVATAR_AGENT_NAME = "protoface-avatar-agent";
+class AvatarSession extends import_agents.voice.AvatarSession {
+  avatarId;
+  maxDurationMs;
+  avatarParticipantIdentity;
+  avatarParticipantName;
+  api;
+  sessionIdValue = null;
+  #logger = (0, import_log.log)();
+  constructor(options = {}) {
+    super();
+    this.avatarId = options.avatarId ?? DEFAULT_STOCK_AVATAR_ID;
+    this.maxDurationMs = options.maxDurationMs;
+    this.avatarParticipantIdentity = options.avatarParticipantIdentity || AVATAR_AGENT_IDENTITY;
+    this.avatarParticipantName = options.avatarParticipantName || AVATAR_AGENT_NAME;
+    this.api = new import_api.ProtofaceAPI({
+      apiKey: options.apiKey,
+      apiUrl: options.apiUrl,
+      connOptions: options.connOptions ?? import_agents.DEFAULT_API_CONNECT_OPTIONS
+    });
+  }
+  get avatarIdentity() {
+    return this.avatarParticipantIdentity;
+  }
+  get provider() {
+    return "protoface";
+  }
+  /** Protoface session ID after `start()` succeeds, otherwise `null`. */
+  get sessionId() {
+    return this.sessionIdValue;
+  }
+  async start(agentSession, room, options = {}) {
+    if (this.sessionIdValue !== null) {
+      throw new Error("AvatarSession.start() called twice; create a new AvatarSession.");
+    }
+    await super.start(agentSession, room);
+    const livekitUrl = options.livekitUrl ?? process.env.LIVEKIT_URL;
+    const livekitApiKey = options.livekitApiKey ?? process.env.LIVEKIT_API_KEY;
+    const livekitApiSecret = options.livekitApiSecret ?? process.env.LIVEKIT_API_SECRET;
+    if (!livekitUrl || !livekitApiKey || !livekitApiSecret) {
+      throw new import_api.ProtofaceException(
+        "livekitUrl, livekitApiKey, and livekitApiSecret must be set by arguments or environment variables"
+      );
+    }
+    const workerToken = await this.mintWorkerToken({ room, livekitApiKey, livekitApiSecret });
+    const session = await this.api.startSession({
+      avatarId: this.avatarId,
+      transport: {
+        type: "livekit",
+        url: livekitUrl,
+        room_name: room.name,
+        worker_token: workerToken,
+        worker_identity: this.avatarParticipantIdentity,
+        audio_source: "data_stream"
+      },
+      maxDurationMs: this.maxDurationMs
+    });
+    if (typeof session.id !== "string") {
+      throw new import_api.ProtofaceException("Protoface API response missing session id");
+    }
+    this.sessionIdValue = session.id;
+    this.#logger.debug(
+      { sessionId: this.sessionIdValue, avatarId: this.avatarId },
+      "protoface session started"
+    );
+    agentSession.output.audio = new import_agents.voice.DataStreamAudioOutput({
+      room,
+      destinationIdentity: this.avatarParticipantIdentity,
+      sampleRate: SAMPLE_RATE,
+      waitRemoteTrack: import_rtc_node.TrackKind.KIND_VIDEO
+    });
+  }
+  async aclose() {
+    const sessionId = this.sessionIdValue;
+    this.sessionIdValue = null;
+    try {
+      if (sessionId !== null) {
+        try {
+          await this.api.endSession(sessionId);
+        } catch (error) {
+          this.#logger.warn({ error: String(error), sessionId }, "failed to end protoface session");
+        }
+      }
+    } finally {
+      await super.aclose();
+    }
+  }
+  async mintWorkerToken({
+    room,
+    livekitApiKey,
+    livekitApiSecret
+  }) {
+    var _a;
+    let localParticipantIdentity = "";
+    try {
+      const jobCtx = (0, import_agents.getJobContext)();
+      localParticipantIdentity = ((_a = jobCtx.agent) == null ? void 0 : _a.identity) || "";
+    } catch {
+    }
+    if (!localParticipantIdentity && room.isConnected && room.localParticipant) {
+      localParticipantIdentity = room.localParticipant.identity;
+    }
+    if (!localParticipantIdentity) {
+      throw new import_api.ProtofaceException("failed to get local participant identity");
+    }
+    const token = new import_livekit_server_sdk.AccessToken(livekitApiKey, livekitApiSecret, {
+      identity: this.avatarParticipantIdentity,
+      name: this.avatarParticipantName
+    });
+    token.kind = "agent";
+    token.attributes = { [ATTRIBUTE_PUBLISH_ON_BEHALF]: localParticipantIdentity };
+    token.addGrant({
+      roomJoin: true,
+      room: room.name,
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: true
+    });
+    return token.toJwt();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AvatarSession,
+  DEFAULT_STOCK_AVATAR_ID
+});
+//# sourceMappingURL=avatar.cjs.map

package/dist/avatar.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/avatar.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport {\n  type APIConnectOptions,\n  DEFAULT_API_CONNECT_OPTIONS,\n  getJobContext,\n  voice,\n} from '@livekit/agents';\nimport type { Room } from '@livekit/rtc-node';\nimport { TrackKind } from '@livekit/rtc-node';\nimport type { VideoGrant } from 'livekit-server-sdk';\nimport { AccessToken } from 'livekit-server-sdk';\nimport { ProtofaceAPI, ProtofaceException } from './api.js';\nimport { log } from './log.js';\n\n/** @public */\nexport const DEFAULT_STOCK_AVATAR_ID = 'av_stock_001';\n\nconst ATTRIBUTE_PUBLISH_ON_BEHALF = 'lk.publish_on_behalf';\nconst SAMPLE_RATE = 16000;\nconst AVATAR_AGENT_IDENTITY = 'protoface-avatar-agent';\nconst AVATAR_AGENT_NAME = 'protoface-avatar-agent';\n\n/** @public */\nexport interface AvatarSessionOptions {\n  /** Protoface avatar ID to render. Defaults to the stable stock avatar ID `av_stock_001`. */\n  avatarId?: string;\n  /** Override the Protoface API base URL. */\n  apiUrl?: string | null;\n  /** Protoface API key. Falls back to the `PROTOFACE_API_KEY` env var. */\n  apiKey?: string | null;\n  /** Optional maximum session duration in milliseconds. */\n  maxDurationMs?: number | null;\n  /** Identity for the avatar participant. Defaults to `protoface-avatar-agent`. */\n  avatarParticipantIdentity?: string | null;\n  /** Display name for the avatar participant. Defaults to `protoface-avatar-agent`. */\n  avatarParticipantName?: string | null;\n  /** API retry/timeout options. */\n  connOptions?: APIConnectOptions;\n}\n\n/**\n * Optional LiveKit credentials for {@link AvatarSession.start}; falls back to env vars.\n *\n * @public\n */\nexport interface StartOptions {\n  livekitUrl?: string | null;\n  livekitApiKey?: string | null;\n  livekitApiSecret?: string | null;\n}\n\n/**\n * A Protoface avatar session for LiveKit Agents.\n *\n * @public\n */\nexport class AvatarSession extends voice.AvatarSession {\n  private avatarId: string;\n  private maxDurationMs?: number | null;\n  private avatarParticipantIdentity: string;\n  private avatarParticipantName: string;\n  private api: ProtofaceAPI;\n  private sessionIdValue: string | null = null;\n\n  #logger = log();\n\n  constructor(options: AvatarSessionOptions = {}) {\n    super();\n    this.avatarId = options.avatarId ?? DEFAULT_STOCK_AVATAR_ID;\n    this.maxDurationMs = options.maxDurationMs;\n    this.avatarParticipantIdentity = options.avatarParticipantIdentity || AVATAR_AGENT_IDENTITY;\n    this.avatarParticipantName = options.avatarParticipantName || AVATAR_AGENT_NAME;\n    this.api = new ProtofaceAPI({\n      apiKey: options.apiKey,\n      apiUrl: options.apiUrl,\n      connOptions: options.connOptions ?? DEFAULT_API_CONNECT_OPTIONS,\n    });\n  }\n\n  override get avatarIdentity(): string {\n    return this.avatarParticipantIdentity;\n  }\n\n  override get provider(): string {\n    return 'protoface';\n  }\n\n  /** Protoface session ID after `start()` succeeds, otherwise `null`. */\n  get sessionId(): string | null {\n    return this.sessionIdValue;\n  }\n\n  async start(\n    agentSession: voice.AgentSession,\n    room: Room,\n    options: StartOptions = {},\n  ): Promise<void> {\n    if (this.sessionIdValue !== null) {\n      throw new Error('AvatarSession.start() called twice; create a new AvatarSession.');\n    }\n\n    await super.start(agentSession, room);\n\n    const livekitUrl = options.livekitUrl ?? process.env.LIVEKIT_URL;\n    const livekitApiKey = options.livekitApiKey ?? process.env.LIVEKIT_API_KEY;\n    const livekitApiSecret = options.livekitApiSecret ?? process.env.LIVEKIT_API_SECRET;\n    if (!livekitUrl || !livekitApiKey || !livekitApiSecret) {\n      throw new ProtofaceException(\n        'livekitUrl, livekitApiKey, and livekitApiSecret must be set by arguments or environment variables',\n      );\n    }\n\n    const workerToken = await this.mintWorkerToken({ room, livekitApiKey, livekitApiSecret });\n    const session = await this.api.startSession({\n      avatarId: this.avatarId,\n      transport: {\n        type: 'livekit',\n        url: livekitUrl,\n        room_name: room.name,\n        worker_token: workerToken,\n        worker_identity: this.avatarParticipantIdentity,\n        audio_source: 'data_stream',\n      },\n      maxDurationMs: this.maxDurationMs,\n    });\n\n    if (typeof session.id !== 'string') {\n      throw new ProtofaceException('Protoface API response missing session id');\n    }\n\n    this.sessionIdValue = session.id;\n    this.#logger.debug(\n      { sessionId: this.sessionIdValue, avatarId: this.avatarId },\n      'protoface session started',\n    );\n\n    agentSession.output.audio = new voice.DataStreamAudioOutput({\n      room,\n      destinationIdentity: this.avatarParticipantIdentity,\n      sampleRate: SAMPLE_RATE,\n      waitRemoteTrack: TrackKind.KIND_VIDEO,\n    });\n  }\n\n  async aclose(): Promise<void> {\n    const sessionId = this.sessionIdValue;\n    this.sessionIdValue = null;\n    try {\n      if (sessionId !== null) {\n        try {\n          await this.api.endSession(sessionId);\n        } catch (error) {\n          this.#logger.warn({ error: String(error), sessionId }, 'failed to end protoface session');\n        }\n      }\n    } finally {\n      await super.aclose();\n    }\n  }\n\n  private async mintWorkerToken({\n    room,\n    livekitApiKey,\n    livekitApiSecret,\n  }: {\n    room: Room;\n    livekitApiKey: string;\n    livekitApiSecret: string;\n  }): Promise<string> {\n    let localParticipantIdentity = '';\n    try {\n      const jobCtx = getJobContext();\n      localParticipantIdentity = jobCtx.agent?.identity || '';\n    } catch {\n      // Fall back to the connected room below when no job context is available.\n    }\n\n    if (!localParticipantIdentity && room.isConnected && room.localParticipant) {\n      localParticipantIdentity = room.localParticipant.identity;\n    }\n\n    if (!localParticipantIdentity) {\n      throw new ProtofaceException('failed to get local participant identity');\n    }\n\n    const token = new AccessToken(livekitApiKey, livekitApiSecret, {\n      identity: this.avatarParticipantIdentity,\n      name: this.avatarParticipantName,\n    });\n    token.kind = 'agent';\n    token.attributes = { [ATTRIBUTE_PUBLISH_ON_BEHALF]: localParticipantIdentity };\n    token.addGrant({\n      roomJoin: true,\n      room: room.name,\n      canPublish: true,\n      canSubscribe: true,\n      canPublishData: true,\n    } as VideoGrant);\n\n    return token.toJwt();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/avatar.d.cts

@@ -0,0 +1,54 @@
+import { type APIConnectOptions, voice } from '@livekit/agents';
+import type { Room } from '@livekit/rtc-node';
+/** @public */
+export declare const DEFAULT_STOCK_AVATAR_ID = "av_stock_001";
+/** @public */
+export interface AvatarSessionOptions {
+    /** Protoface avatar ID to render. Defaults to the stable stock avatar ID `av_stock_001`. */
+    avatarId?: string;
+    /** Override the Protoface API base URL. */
+    apiUrl?: string | null;
+    /** Protoface API key. Falls back to the `PROTOFACE_API_KEY` env var. */
+    apiKey?: string | null;
+    /** Optional maximum session duration in milliseconds. */
+    maxDurationMs?: number | null;
+    /** Identity for the avatar participant. Defaults to `protoface-avatar-agent`. */
+    avatarParticipantIdentity?: string | null;
+    /** Display name for the avatar participant. Defaults to `protoface-avatar-agent`. */
+    avatarParticipantName?: string | null;
+    /** API retry/timeout options. */
+    connOptions?: APIConnectOptions;
+}
+/**
+ * Optional LiveKit credentials for {@link AvatarSession.start}; falls back to env vars.
+ *
+ * @public
+ */
+export interface StartOptions {
+    livekitUrl?: string | null;
+    livekitApiKey?: string | null;
+    livekitApiSecret?: string | null;
+}
+/**
+ * A Protoface avatar session for LiveKit Agents.
+ *
+ * @public
+ */
+export declare class AvatarSession extends voice.AvatarSession {
+    #private;
+    private avatarId;
+    private maxDurationMs?;
+    private avatarParticipantIdentity;
+    private avatarParticipantName;
+    private api;
+    private sessionIdValue;
+    constructor(options?: AvatarSessionOptions);
+    get avatarIdentity(): string;
+    get provider(): string;
+    /** Protoface session ID after `start()` succeeds, otherwise `null`. */
+    get sessionId(): string | null;
+    start(agentSession: voice.AgentSession, room: Room, options?: StartOptions): Promise<void>;
+    aclose(): Promise<void>;
+    private mintWorkerToken;
+}
+//# sourceMappingURL=avatar.d.ts.map

package/dist/avatar.d.ts

@@ -0,0 +1,54 @@
+import { type APIConnectOptions, voice } from '@livekit/agents';
+import type { Room } from '@livekit/rtc-node';
+/** @public */
+export declare const DEFAULT_STOCK_AVATAR_ID = "av_stock_001";
+/** @public */
+export interface AvatarSessionOptions {
+    /** Protoface avatar ID to render. Defaults to the stable stock avatar ID `av_stock_001`. */
+    avatarId?: string;
+    /** Override the Protoface API base URL. */
+    apiUrl?: string | null;
+    /** Protoface API key. Falls back to the `PROTOFACE_API_KEY` env var. */
+    apiKey?: string | null;
+    /** Optional maximum session duration in milliseconds. */
+    maxDurationMs?: number | null;
+    /** Identity for the avatar participant. Defaults to `protoface-avatar-agent`. */
+    avatarParticipantIdentity?: string | null;
+    /** Display name for the avatar participant. Defaults to `protoface-avatar-agent`. */
+    avatarParticipantName?: string | null;
+    /** API retry/timeout options. */
+    connOptions?: APIConnectOptions;
+}
+/**
+ * Optional LiveKit credentials for {@link AvatarSession.start}; falls back to env vars.
+ *
+ * @public
+ */
+export interface StartOptions {
+    livekitUrl?: string | null;
+    livekitApiKey?: string | null;
+    livekitApiSecret?: string | null;
+}
+/**
+ * A Protoface avatar session for LiveKit Agents.
+ *
+ * @public
+ */
+export declare class AvatarSession extends voice.AvatarSession {
+    #private;
+    private avatarId;
+    private maxDurationMs?;
+    private avatarParticipantIdentity;
+    private avatarParticipantName;
+    private api;
+    private sessionIdValue;
+    constructor(options?: AvatarSessionOptions);
+    get avatarIdentity(): string;
+    get provider(): string;
+    /** Protoface session ID after `start()` succeeds, otherwise `null`. */
+    get sessionId(): string | null;
+    start(agentSession: voice.AgentSession, room: Room, options?: StartOptions): Promise<void>;
+    aclose(): Promise<void>;
+    private mintWorkerToken;
+}
+//# sourceMappingURL=avatar.d.ts.map

package/dist/avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../src/avatar.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,iBAAiB,EAGtB,KAAK,EACN,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAO9C,cAAc;AACd,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAOtD,cAAc;AACd,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iFAAiF;IACjF,yBAAyB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,qFAAqF;IACrF,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,iCAAiC;IACjC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK,CAAC,aAAa;;IACpD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,yBAAyB,CAAS;IAC1C,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,cAAc,CAAuB;gBAIjC,OAAO,GAAE,oBAAyB;IAa9C,IAAa,cAAc,IAAI,MAAM,CAEpC;IAED,IAAa,QAAQ,IAAI,MAAM,CAE9B;IAED,uEAAuE;IACvE,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAEK,KAAK,CACT,YAAY,EAAE,KAAK,CAAC,YAAY,EAChC,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAgDV,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBf,eAAe;CAyC9B"}

package/dist/avatar.js

@@ -0,0 +1,139 @@
+import {
+  DEFAULT_API_CONNECT_OPTIONS,
+  getJobContext,
+  voice
+} from "@livekit/agents";
+import { TrackKind } from "@livekit/rtc-node";
+import { AccessToken } from "livekit-server-sdk";
+import { ProtofaceAPI, ProtofaceException } from "./api.js";
+import { log } from "./log.js";
+const DEFAULT_STOCK_AVATAR_ID = "av_stock_001";
+const ATTRIBUTE_PUBLISH_ON_BEHALF = "lk.publish_on_behalf";
+const SAMPLE_RATE = 16e3;
+const AVATAR_AGENT_IDENTITY = "protoface-avatar-agent";
+const AVATAR_AGENT_NAME = "protoface-avatar-agent";
+class AvatarSession extends voice.AvatarSession {
+  avatarId;
+  maxDurationMs;
+  avatarParticipantIdentity;
+  avatarParticipantName;
+  api;
+  sessionIdValue = null;
+  #logger = log();
+  constructor(options = {}) {
+    super();
+    this.avatarId = options.avatarId ?? DEFAULT_STOCK_AVATAR_ID;
+    this.maxDurationMs = options.maxDurationMs;
+    this.avatarParticipantIdentity = options.avatarParticipantIdentity || AVATAR_AGENT_IDENTITY;
+    this.avatarParticipantName = options.avatarParticipantName || AVATAR_AGENT_NAME;
+    this.api = new ProtofaceAPI({
+      apiKey: options.apiKey,
+      apiUrl: options.apiUrl,
+      connOptions: options.connOptions ?? DEFAULT_API_CONNECT_OPTIONS
+    });
+  }
+  get avatarIdentity() {
+    return this.avatarParticipantIdentity;
+  }
+  get provider() {
+    return "protoface";
+  }
+  /** Protoface session ID after `start()` succeeds, otherwise `null`. */
+  get sessionId() {
+    return this.sessionIdValue;
+  }
+  async start(agentSession, room, options = {}) {
+    if (this.sessionIdValue !== null) {
+      throw new Error("AvatarSession.start() called twice; create a new AvatarSession.");
+    }
+    await super.start(agentSession, room);
+    const livekitUrl = options.livekitUrl ?? process.env.LIVEKIT_URL;
+    const livekitApiKey = options.livekitApiKey ?? process.env.LIVEKIT_API_KEY;
+    const livekitApiSecret = options.livekitApiSecret ?? process.env.LIVEKIT_API_SECRET;
+    if (!livekitUrl || !livekitApiKey || !livekitApiSecret) {
+      throw new ProtofaceException(
+        "livekitUrl, livekitApiKey, and livekitApiSecret must be set by arguments or environment variables"
+      );
+    }
+    const workerToken = await this.mintWorkerToken({ room, livekitApiKey, livekitApiSecret });
+    const session = await this.api.startSession({
+      avatarId: this.avatarId,
+      transport: {
+        type: "livekit",
+        url: livekitUrl,
+        room_name: room.name,
+        worker_token: workerToken,
+        worker_identity: this.avatarParticipantIdentity,
+        audio_source: "data_stream"
+      },
+      maxDurationMs: this.maxDurationMs
+    });
+    if (typeof session.id !== "string") {
+      throw new ProtofaceException("Protoface API response missing session id");
+    }
+    this.sessionIdValue = session.id;
+    this.#logger.debug(
+      { sessionId: this.sessionIdValue, avatarId: this.avatarId },
+      "protoface session started"
+    );
+    agentSession.output.audio = new voice.DataStreamAudioOutput({
+      room,
+      destinationIdentity: this.avatarParticipantIdentity,
+      sampleRate: SAMPLE_RATE,
+      waitRemoteTrack: TrackKind.KIND_VIDEO
+    });
+  }
+  async aclose() {
+    const sessionId = this.sessionIdValue;
+    this.sessionIdValue = null;
+    try {
+      if (sessionId !== null) {
+        try {
+          await this.api.endSession(sessionId);
+        } catch (error) {
+          this.#logger.warn({ error: String(error), sessionId }, "failed to end protoface session");
+        }
+      }
+    } finally {
+      await super.aclose();
+    }
+  }
+  async mintWorkerToken({
+    room,
+    livekitApiKey,
+    livekitApiSecret
+  }) {
+    var _a;
+    let localParticipantIdentity = "";
+    try {
+      const jobCtx = getJobContext();
+      localParticipantIdentity = ((_a = jobCtx.agent) == null ? void 0 : _a.identity) || "";
+    } catch {
+    }
+    if (!localParticipantIdentity && room.isConnected && room.localParticipant) {
+      localParticipantIdentity = room.localParticipant.identity;
+    }
+    if (!localParticipantIdentity) {
+      throw new ProtofaceException("failed to get local participant identity");
+    }
+    const token = new AccessToken(livekitApiKey, livekitApiSecret, {
+      identity: this.avatarParticipantIdentity,
+      name: this.avatarParticipantName
+    });
+    token.kind = "agent";
+    token.attributes = { [ATTRIBUTE_PUBLISH_ON_BEHALF]: localParticipantIdentity };
+    token.addGrant({
+      roomJoin: true,
+      room: room.name,
+      canPublish: true,
+      canSubscribe: true,
+      canPublishData: true
+    });
+    return token.toJwt();
+  }
+}
+export {
+  AvatarSession,
+  DEFAULT_STOCK_AVATAR_ID
+};
+//# sourceMappingURL=avatar.js.map

package/dist/avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/avatar.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2026 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport {\n  type APIConnectOptions,\n  DEFAULT_API_CONNECT_OPTIONS,\n  getJobContext,\n  voice,\n} from '@livekit/agents';\nimport type { Room } from '@livekit/rtc-node';\nimport { TrackKind } from '@livekit/rtc-node';\nimport type { VideoGrant } from 'livekit-server-sdk';\nimport { AccessToken } from 'livekit-server-sdk';\nimport { ProtofaceAPI, ProtofaceException } from './api.js';\nimport { log } from './log.js';\n\n/** @public */\nexport const DEFAULT_STOCK_AVATAR_ID = 'av_stock_001';\n\nconst ATTRIBUTE_PUBLISH_ON_BEHALF = 'lk.publish_on_behalf';\nconst SAMPLE_RATE = 16000;\nconst AVATAR_AGENT_IDENTITY = 'protoface-avatar-agent';\nconst AVATAR_AGENT_NAME = 'protoface-avatar-agent';\n\n/** @public */\nexport interface AvatarSessionOptions {\n  /** Protoface avatar ID to render. Defaults to the stable stock avatar ID `av_stock_001`. */\n  avatarId?: string;\n  /** Override the Protoface API base URL. */\n  apiUrl?: string | null;\n  /** Protoface API key. Falls back to the `PROTOFACE_API_KEY` env var. */\n  apiKey?: string | null;\n  /** Optional maximum session duration in milliseconds. */\n  maxDurationMs?: number | null;\n  /** Identity for the avatar participant. Defaults to `protoface-avatar-agent`. */\n  avatarParticipantIdentity?: string | null;\n  /** Display name for the avatar participant. Defaults to `protoface-avatar-agent`. */\n  avatarParticipantName?: string | null;\n  /** API retry/timeout options. */\n  connOptions?: APIConnectOptions;\n}\n\n/**\n * Optional LiveKit credentials for {@link AvatarSession.start}; falls back to env vars.\n *\n * @public\n */\nexport interface StartOptions {\n  livekitUrl?: string | null;\n  livekitApiKey?: string | null;\n  livekitApiSecret?: string | null;\n}\n\n/**\n * A Protoface avatar session for LiveKit Agents.\n *\n * @public\n */\nexport class AvatarSession extends voice.AvatarSession {\n  private avatarId: string;\n  private maxDurationMs?: number | null;\n  private avatarParticipantIdentity: string;\n  private avatarParticipantName: string;\n  private api: ProtofaceAPI;\n  private sessionIdValue: string | null = null;\n\n  #logger = log();\n\n  constructor(options: AvatarSessionOptions = {}) {\n    super();\n    this.avatarId = options.avatarId ?? DEFAULT_STOCK_AVATAR_ID;\n    this.maxDurationMs = options.maxDurationMs;\n    this.avatarParticipantIdentity = options.avatarParticipantIdentity || AVATAR_AGENT_IDENTITY;\n    this.avatarParticipantName = options.avatarParticipantName || AVATAR_AGENT_NAME;\n    this.api = new ProtofaceAPI({\n      apiKey: options.apiKey,\n      apiUrl: options.apiUrl,\n      connOptions: options.connOptions ?? DEFAULT_API_CONNECT_OPTIONS,\n    });\n  }\n\n  override get avatarIdentity(): string {\n    return this.avatarParticipantIdentity;\n  }\n\n  override get provider(): string {\n    return 'protoface';\n  }\n\n  /** Protoface session ID after `start()` succeeds, otherwise `null`. */\n  get sessionId(): string | null {\n    return this.sessionIdValue;\n  }\n\n  async start(\n    agentSession: voice.AgentSession,\n    room: Room,\n    options: StartOptions = {},\n  ): Promise<void> {\n    if (this.sessionIdValue !== null) {\n      throw new Error('AvatarSession.start() called twice; create a new AvatarSession.');\n    }\n\n    await super.start(agentSession, room);\n\n    const livekitUrl = options.livekitUrl ?? process.env.LIVEKIT_URL;\n    const livekitApiKey = options.livekitApiKey ?? process.env.LIVEKIT_API_KEY;\n    const livekitApiSecret = options.livekitApiSecret ?? process.env.LIVEKIT_API_SECRET;\n    if (!livekitUrl || !livekitApiKey || !livekitApiSecret) {\n      throw new ProtofaceException(\n        'livekitUrl, livekitApiKey, and livekitApiSecret must be set by arguments or environment variables',\n      );\n    }\n\n    const workerToken = await this.mintWorkerToken({ room, livekitApiKey, livekitApiSecret });\n    const session = await this.api.startSession({\n      avatarId: this.avatarId,\n      transport: {\n        type: 'livekit',\n        url: livekitUrl,\n        room_name: room.name,\n        worker_token: workerToken,\n        worker_identity: this.avatarParticipantIdentity,\n        audio_source: 'data_stream',\n      },\n      maxDurationMs: this.maxDurationMs,\n    });\n\n    if (typeof session.id !== 'string') {\n      throw new ProtofaceException('Protoface API response missing session id');\n    }\n\n    this.sessionIdValue = session.id;\n    this.#logger.debug(\n      { sessionId: this.sessionIdValue, avatarId: this.avatarId },\n      'protoface session started',\n    );\n\n    agentSession.output.audio = new voice.DataStreamAudioOutput({\n      room,\n      destinationIdentity: this.avatarParticipantIdentity,\n      sampleRate: SAMPLE_RATE,\n      waitRemoteTrack: TrackKind.KIND_VIDEO,\n    });\n  }\n\n  async aclose(): Promise<void> {\n    const sessionId = this.sessionIdValue;\n    this.sessionIdValue = null;\n    try {\n      if (sessionId !== null) {\n        try {\n          await this.api.endSession(sessionId);\n        } catch (error) {\n          this.#logger.warn({ error: String(error), sessionId }, 'failed to end protoface session');\n        }\n      }\n    } finally {\n      await super.aclose();\n    }\n  }\n\n  private async mintWorkerToken({\n    room,\n    livekitApiKey,\n    livekitApiSecret,\n  }: {\n    room: Room;\n    livekitApiKey: string;\n    livekitApiSecret: string;\n  }): Promise<string> {\n    let localParticipantIdentity = '';\n    try {\n      const jobCtx = getJobContext();\n      localParticipantIdentity = jobCtx.agent?.identity || '';\n    } catch {\n      // Fall back to the connected room below when no job context is available.\n    }\n\n    if (!localParticipantIdentity && room.isConnected && room.localParticipant) {\n      localParticipantIdentity = room.localParticipant.identity;\n    }\n\n    if (!localParticipantIdentity) {\n      throw new ProtofaceException('failed to get local participant identity');\n    }\n\n    const token = new AccessToken(livekitApiKey, livekitApiSecret, {\n      identity: this.avatarParticipantIdentity,\n      name: this.avatarParticipantName,\n    });\n    token.kind = 'agent';\n    token.attributes = { [ATTRIBUTE_PUBLISH_ON_BEHALF]: localParticipantIdentity };\n    token.addGrant({\n      roomJoin: true,\n      room: room.name,\n      canPublish: true,\n      canSubscribe: true,\n      canPublishData: true,\n    } as VideoGrant);\n\n    return token.toJwt();\n  }\n}\n"],"mappings":"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","names":[]}