@komaa/standin-sdk 0.1.0

package/dist/plugins/livekit/handler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The relay: one Microsoft Teams call on one side, one LiveKit room on the other.
+ *
+ * Unlike the provider plugins, there is no model here and no tools to
+ * answer. LiveKit is a room your own agent joins, so this side publishes the
+ * caller's voice, subscribes to the agent's, and relays call context as room
+ * data on two topics the agent can subscribe to.
+ *
+ * Your agent therefore needs no Microsoft Teams awareness at all. It sees a
+ * participant who talks, and optionally two topics that tell it who is calling
+ * and when to say goodbye.
+ *
+ * The Python twin is `standin.plugins.livekit`, which additionally arms
+ * itself from inside a LiveKit worker. This one is explicit: you build the
+ * handler yourself.
+ */
+import { type GateDecision } from "../../gate.js";
+import type { CallHandler, CallSession } from "../../handler.js";
+import { type LiveKitConfig } from "./config.js";
+import { type RoomHandlers, type RoomPort } from "./room.js";
+/** How the handler reaches LiveKit. Replaceable so tests need no framework. */
+export type Connect = (config: LiveKitConfig, callId: string, metadata: Record<string, string>, handlers: RoomHandlers) => Promise<RoomPort>;
+/** Options for {@link LiveKitHandler}. */
+export interface LiveKitHandlerOptions {
+    /**
+     * What addresses the assistant in a meeting.
+     *
+     * Empty by default, which leaves the group gate inert: an agent that answers
+     * everything keeps answering everything, and nothing changes for it.
+     */
+    wakePhrases?: readonly string[];
+    config?: LiveKitConfig;
+    connect?: Connect;
+}
+/** One Microsoft Teams call answered by one LiveKit agent. */
+export declare class LiveKitHandler implements CallHandler {
+    #private;
+    constructor(options?: LiveKitHandlerOptions);
+    /**
+     * What the gate decided about the caller's last finished turn.
+     *
+     * `undefined` until a turn has been decided, and on a call where transcripts
+     * never arrive. An agent that wants to stay out of a meeting it was not
+     * addressed in reads this; one that does not can ignore it entirely.
+     */
+    get lastDecision(): GateDecision | undefined;
+    onStart(session: CallSession): Promise<void>;
+    /** The caller's voice, published into the room as a track. */
+    onCallerAudio(pcm: Buffer): Promise<void>;
+    /** Call context, published on a topic the agent can subscribe to. */
+    onContext(text: string): Promise<void>;
+    /**
+     * The closing line, published on its own topic so an agent can tell it apart
+     * from ordinary context and interrupt itself to say it.
+     */
+    onGoodbye(text: string): Promise<void>;
+    aclose(): Promise<void>;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/plugins/livekit/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/plugins/livekit/handler.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIjE,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AAKnB,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,CACpB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,QAAQ,EAAE,YAAY,KACnB,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,8DAA8D;AAC9D,qBAAa,cAAe,YAAW,WAAW;;gBAcpC,OAAO,GAAE,qBAA0B;IAQ/C;;;;;;OAMG;IACH,IAAI,YAAY,IAAI,YAAY,GAAG,SAAS,CAE3C;IAEK,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgFlD,8DAA8D;IACxD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B/C,qEAAqE;IAC/D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAItC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CA0B9B"}

package/dist/plugins/livekit/handler.js

@@ -0,0 +1,211 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * The relay: one Microsoft Teams call on one side, one LiveKit room on the other.
+ *
+ * Unlike the provider plugins, there is no model here and no tools to
+ * answer. LiveKit is a room your own agent joins, so this side publishes the
+ * caller's voice, subscribes to the agent's, and relays call context as room
+ * data on two topics the agent can subscribe to.
+ *
+ * Your agent therefore needs no Microsoft Teams awareness at all. It sees a
+ * participant who talks, and optionally two topics that tell it who is calling
+ * and when to say goodbye.
+ *
+ * The Python twin is `standin.plugins.livekit`, which additionally arms
+ * itself from inside a LiveKit worker. This one is explicit: you build the
+ * handler yourself.
+ */
+import { GroupGate, isAddressed } from "../../gate.js";
+import { logger } from "../../log.js";
+import { StartupBuffer } from "../../startup.js";
+import { TileStream } from "../../tile.js";
+import { liveKitConfigFromEnv } from "./config.js";
+import { TOPIC_CONTEXT, TOPIC_GOODBYE, contextPayload, connectRoom, } from "./room.js";
+/** Caller audio that arrives while the room is still being joined. */
+const MAX_PENDING_AUDIO = 200;
+/** One Microsoft Teams call answered by one LiveKit agent. */
+export class LiveKitHandler {
+    #config;
+    #connect;
+    #call;
+    #room;
+    #closed = false;
+    // Holds BOTH the caller's first words and the first context, so neither
+    // is lost while the provider is still connecting.
+    #pending = new StartupBuffer();
+    #tile;
+    #stopRelay;
+    #gate;
+    #lastDecision;
+    constructor(options = {}) {
+        this.#config = options.config ?? liveKitConfigFromEnv();
+        this.#connect = options.connect ?? connectRoom;
+        this.#wakePhrases = options.wakePhrases ?? [];
+    }
+    #wakePhrases;
+    /**
+     * What the gate decided about the caller's last finished turn.
+     *
+     * `undefined` until a turn has been decided, and on a call where transcripts
+     * never arrive. An agent that wants to stay out of a meeting it was not
+     * addressed in reads this; one that does not can ignore it entirely.
+     */
+    get lastDecision() {
+        return this.#lastDecision;
+    }
+    async onStart(session) {
+        this.#call = session;
+        // Armed from the call's own thread. On a one-to-one call it is inert, so a
+        // plugin that never configures a wake phrase behaves exactly as before.
+        this.#gate = new GroupGate({
+            wakePhrases: this.#wakePhrases,
+            threadId: session.start.threadId ?? "",
+        });
+        const caller = session.start.caller;
+        // Job metadata is how the agent learns who is calling. Absent fields stay
+        // absent rather than becoming a shared default, so two anonymous callers
+        // never look like the same person.
+        //
+        // The KEY NAMES are a cross-language contract, not a local choice. The
+        // Python SDK's CallInfo.from_job reads exactly these, and returns a blank
+        // record for metadata in any other shape, so an agent dispatched from here
+        // and written in Python would otherwise see no caller at all.
+        const metadata = {
+            source: "msteams",
+            call_id: session.callId,
+            call_direction: session.start.direction,
+        };
+        if (caller.displayName)
+            metadata.caller_name = caller.displayName;
+        if (caller.aadId)
+            metadata.user_id = caller.aadId;
+        if (caller.tenantId)
+            metadata.tenant_id = caller.tenantId;
+        if (session.start.threadId)
+            metadata.thread_id = session.start.threadId;
+        let room;
+        try {
+            room = await this.#connect(this.#config, session.callId, metadata, {
+                onAgentAudio: (pcm) => this.#onAgentAudio(pcm),
+                onClosed: (reason) => this.#onClosed(reason),
+                // The agent's own audio is what "answered" means. Without this the
+                // core reaper would end a call an agent HAS taken but that is still
+                // listening.
+                onAnswered: () => session.markAnswered(),
+                onCallerTranscript: (text, final) => this.#onCallerTranscript(text, final),
+            });
+        }
+        catch (err) {
+            logger.error(`standin: could not join the LiveKit room: ${String(err)}`);
+            await session.end("agent-unavailable");
+            return;
+        }
+        // The call can end during the join above.
+        if (this.#closed) {
+            await room.aclose();
+            return;
+        }
+        this.#room = room;
+        await this.#pending.release((pcm) => room.sendCallerAudio(pcm), (text) => void room.publish(TOPIC_CONTEXT, contextPayload(text)));
+        if (this.#pending.dropped.audio || this.#pending.dropped.context) {
+            logger.info("standin: the caller outran the agent starting up; some early input was dropped");
+        }
+        // The agent's own face on the tile, when it publishes one. On by default:
+        // an agent that publishes video almost always means it for the caller.
+        if (this.#config.tileVideo !== "off" && room.startAvatarRelay) {
+            const tile = new TileStream(session, { fps: this.#config.tileVideoFps });
+            await tile.start();
+            this.#tile = tile;
+            try {
+                this.#stopRelay = await room.startAvatarRelay({
+                    offerRgb: (rgb, width, height) => tile.offerRgb(rgb, width, height),
+                });
+            }
+            catch (err) {
+                // A tile that will not start is not a call that should fail.
+                logger.warn(`standin: could not start the avatar relay: ${String(err)}`);
+            }
+        }
+    }
+    /** The caller's voice, published into the room as a track. */
+    async onCallerAudio(pcm) {
+        const room = this.#room;
+        if (room === undefined || !room.isOpen) {
+            this.#pending.audio(pcm);
+            return;
+        }
+        room.sendCallerAudio(pcm);
+    }
+    /**
+     * What the caller said, fed to the group gate.
+     *
+     * A partial may only NOTICE the wake phrase, never decide a turn. Deciding on
+     * a partial returns "do not respond" for a turn that is about to address the
+     * assistant, and the answer to a turn that DID address it gets cut.
+     *
+     * The text is never logged or kept: it is read for this decision and dropped.
+     */
+    #onCallerTranscript(text, final) {
+        const gate = this.#gate;
+        if (gate === undefined)
+            return;
+        if (!final) {
+            // Stamps the window when the phrase is heard mid-turn, and cannot close
+            // it: the window is a timestamp, so a missed phrase self-heals by clock
+            // rather than stranding the agent silent for the meeting.
+            if (isAddressed(text, gate.wakePhrases))
+                gate.decide(text, Date.now());
+            return;
+        }
+        this.#lastDecision = gate.decide(text, Date.now());
+    }
+    /** Call context, published on a topic the agent can subscribe to. */
+    async onContext(text) {
+        const room = this.#room;
+        if (room === undefined) {
+            // Held rather than dropped: a data packet reaches only participants
+            // connected at that instant, and the first context lands before the
+            // dispatched agent has joined.
+            this.#pending.context(text);
+            return;
+        }
+        await room.publish(TOPIC_CONTEXT, contextPayload(text));
+    }
+    /**
+     * The closing line, published on its own topic so an agent can tell it apart
+     * from ordinary context and interrupt itself to say it.
+     */
+    async onGoodbye(text) {
+        await this.#room?.publish(TOPIC_GOODBYE, contextPayload(text));
+    }
+    async aclose() {
+        this.#closed = true;
+        this.#stopRelay?.();
+        this.#stopRelay = undefined;
+        const tile = this.#tile;
+        this.#tile = undefined;
+        if (tile !== undefined)
+            await tile.aclose();
+        const room = this.#room;
+        this.#room = undefined;
+        if (room !== undefined) {
+            try {
+                await room.aclose();
+            }
+            catch {
+                // Teardown must not throw: the slot is freed either way.
+            }
+        }
+    }
+    async #onAgentAudio(pcm) {
+        if (pcm.length > 0)
+            await this.#call?.sendAudio(pcm);
+    }
+    async #onClosed(reason) {
+        logger.info(`standin: the LiveKit room ended (${reason})`);
+        if (!this.#closed)
+            await this.#call?.end("agent-disconnected");
+    }
+}
+//# sourceMappingURL=handler.js.map

package/dist/plugins/livekit/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/plugins/livekit/handler.ts"],"names":[],"mappings":"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"}

package/dist/plugins/livekit/index.d.ts

@@ -0,0 +1,6 @@
+export { liveKitConfigFromEnv, type LiveKitConfig } from "./config.js";
+export { LiveKitHandler, type Connect, type LiveKitHandlerOptions, } from "./handler.js";
+export { TOPIC_CONTEXT, TOPIC_GOODBYE, contextPayload, connectRoom, type RoomHandlers, type RoomPort, } from "./room.js";
+/** Answer Microsoft Teams calls with LiveKit until the process is interrupted. */
+export declare function serve(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/livekit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/livekit/index.ts"],"names":[],"mappings":"AAmDA,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,cAAc,EACd,KAAK,OAAO,EACZ,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,QAAQ,GACd,MAAM,WAAW,CAAC;AAEnB,kFAAkF;AAClF,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAgB3C"}

package/dist/plugins/livekit/index.js

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * Answer Microsoft Teams calls with a LiveKit agent.
+ *
+ * StandIn answers the Microsoft Teams call and dials this worker. This
+ * plugin answers that dial, creates one LiveKit room per call, dispatches
+ * your agent into it, and relays the audio both ways.
+ *
+ * Your agent needs no Microsoft Teams awareness: it sees a participant who
+ * talks. Who is calling arrives as job metadata, and call context arrives on two
+ * room data topics, `msteams.context` and `msteams.goodbye`, which are the same
+ * strings the Python SDK uses.
+ *
+ * This is the one plugin with dependencies of its own, because joining a
+ * room means running LiveKit's client:
+ *
+ * ```bash
+ * npm install @komaa/standin-sdk @livekit/rtc-node livekit-server-sdk
+ *
+ * export STANDIN_SECRET=...       # your StandIn connection secret
+ * export LIVEKIT_URL=wss://...
+ * export LIVEKIT_API_KEY=...
+ * export LIVEKIT_API_SECRET=...
+ * export LIVEKIT_AGENT_NAME=standin-msteams
+ * ```
+ *
+ * ```ts
+ * import { CallServer } from "@komaa/standin-sdk";
+ * import { LiveKitHandler } from "@komaa/standin-sdk/livekit";
+ *
+ * const server = new CallServer({ handlerFactory: () => new LiveKitHandler() });
+ * await server.start();
+ * ```
+ *
+ * This plugin relays AUDIO. It does not put the agent's own avatar video on
+ * the bot's tile: StandIn renders the avatar, and a LiveKit-side video relay is
+ * not implemented here. `CallSession.express` and `sendSpeechMarks` still drive
+ * the avatar, and the caller hears the agent either way.
+ *
+ * Those two packages are optional peers: they are imported only when this
+ * module is reached, so the core and every other plugin install without
+ * them. Writing the agent in Python instead? `standin.plugins.livekit`
+ * does the same thing and additionally arms itself from inside your worker.
+ */
+import { CallServer } from "../../index.js";
+import { LiveKitHandler } from "./handler.js";
+import { liveKitConfigFromEnv } from "./config.js";
+export { liveKitConfigFromEnv } from "./config.js";
+export { LiveKitHandler, } from "./handler.js";
+export { TOPIC_CONTEXT, TOPIC_GOODBYE, contextPayload, connectRoom, } from "./room.js";
+/** Answer Microsoft Teams calls with LiveKit until the process is interrupted. */
+export async function serve() {
+    const config = liveKitConfigFromEnv();
+    const server = new CallServer({
+        handlerFactory: () => new LiveKitHandler({ config }),
+    });
+    await server.start();
+    await new Promise((resolve) => {
+        const stop = () => {
+            resolve();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    await server.aclose();
+}
+//# sourceMappingURL=index.js.map

package/dist/plugins/livekit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/plugins/livekit/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,+BAA+B;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,oBAAoB,EAAsB,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,cAAc,GAGf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,WAAW,GAGZ,MAAM,WAAW,CAAC;AAEnB,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,KAAK;IACzB,MAAM,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC;QAC5B,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KACrD,CAAC,CAAC;IACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IAErB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;AACxB,CAAC"}

package/dist/plugins/livekit/room.d.ts

@@ -0,0 +1,117 @@
+import type { LiveKitConfig } from "./config.js";
+/** Non-interrupting call context, published into the room as data. */
+export declare const TOPIC_CONTEXT = "msteams.context";
+/** The closing line StandIn wants spoken before the call ends. */
+export declare const TOPIC_GOODBYE = "msteams.goodbye";
+/** LiveKit's own transcription topic. Both sides of the call publish on it. */
+export declare const TOPIC_TRANSCRIPTION = "lk.transcription";
+/** Which track a transcript stream is OF. Absent on some publishers. */
+export declare const ATTRIBUTE_TRANSCRIBED_TRACK_ID = "lk.transcribed_track_id";
+/** Marks the closing header of a finished turn. */
+export declare const ATTRIBUTE_TRANSCRIPTION_FINAL = "lk.transcription_final";
+/** The identity this plugin joins under. */
+export declare const LOCAL_IDENTITY = "standin-msteams";
+/** What a LiveKit text stream gives us, narrowed to what is read here. */
+export interface TextStreamReader {
+    readonly info?: {
+        readonly attributes?: Record<string, string>;
+    };
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+}
+/** How a transcript stream is classified and delivered. */
+export interface TranscriptRoute {
+    callerTrackSid: () => string | undefined;
+    localIdentity: string;
+    agentIdentity: () => string | undefined;
+    isClosed: () => boolean;
+    deliver: (text: string, final: boolean) => void | Promise<void>;
+}
+/**
+ * Whether this transcript is of the CALLER rather than of the agent.
+ *
+ * The track id is exact when present. Without it, the sender identity is the
+ * fallback: livekit publishes a participant's transcript under that
+ * participant's identity, and ours is the caller's audio.
+ */
+export declare function isCallerTranscript(attributes: Record<string, string> | undefined, senderIdentity: string | undefined, route: {
+    callerTrackSid?: string;
+    localIdentity: string;
+    agentIdentity?: string;
+}): boolean;
+/**
+ * Read one transcript stream to its end and report the caller's words.
+ *
+ * Every stream is drained, including one this call ignores: an abandoned reader
+ * keeps its subscription for the life of the process, and the agent publishes
+ * one stream per turn.
+ *
+ * Each yield is the cumulative transcript so far, so every yield is delivered as
+ * a partial and the last one as final. A partial exists so a wake phrase is
+ * noticed as it is said; only a finished turn is a turn.
+ */
+export declare function readTranscript(reader: TextStreamReader, senderIdentity: string | undefined, route: TranscriptRoute): Promise<void>;
+/**
+ * What goes on a topic: a JSON object carrying `text`, never the bare string.
+ *
+ * This is a cross-language contract. The Python SDK's `TeamsCall._on_data`
+ * json-decodes the packet and requires a dict with a `text` string, so a bare
+ * string is dropped in silence at the far end: every context sentence and the
+ * goodbye would reach nothing.
+ */
+export declare function contextPayload(text: string): string;
+/** A sink the avatar relay pushes encoded frames into. */
+export interface TileSink {
+    offerRgb(rgb: Buffer, width: number, height: number): void;
+}
+/** What the handler needs from a joined room. Tests substitute their own. */
+export interface RoomPort {
+    /**
+     * Start relaying the agent's own avatar video onto the bot's tile.
+     *
+     * Optional, and absent on a room that has no video to relay. It returns a
+     * stop function rather than taking a lifetime, because a track swap must
+     * replace the drain rather than stack a second one on top of it.
+     */
+    startAvatarRelay?(sink: TileSink): Promise<() => void>;
+    readonly isOpen: boolean;
+    /** The identity of the participant whose audio is relayed to the caller. */
+    readonly agentIdentity: string | undefined;
+    /** Publish one frame of the caller's voice into the room. */
+    sendCallerAudio(pcm: Buffer): void;
+    /**
+     * Publish one payload for the agent to read, verbatim.
+     *
+     * The caller builds the payload. Its SHAPE is a cross-language contract, not
+     * a transport detail: see {@link contextPayload}.
+     */
+    publish(topic: string, payload: string): Promise<void>;
+    aclose(): Promise<void>;
+}
+/** What a joined room tells the handler. */
+export interface RoomHandlers {
+    /** Agent audio at the wire rate, ready for the caller. */
+    onAgentAudio: (pcm: Buffer) => void | Promise<void>;
+    /** The room or the agent is gone, with the reason. */
+    onClosed: (reason: string) => void | Promise<void>;
+    /**
+     * What the caller said, as it is said.
+     *
+     * Called with the transcript so far and whether the turn has finished. A
+     * partial exists so a wake phrase is noticed as it is spoken; only a finished
+     * turn is a turn, and a partial must never be able to close the follow-up
+     * window.
+     *
+     * The text is for deciding whether to answer. It is never logged or stored.
+     */
+    onCallerTranscript?: (text: string, final: boolean) => void | Promise<void>;
+    /**
+     * An agent has actually taken the call.
+     *
+     * Fired on the agent's first AUDIO track, not on a participant connecting:
+     * monitors, recorders and avatar workers all connect, and none of them is an
+     * agent answering.
+     */
+    onAnswered?: () => void;
+}
+export declare function connectRoom(config: LiveKitConfig, callId: string, metadata: Record<string, string>, handlers: RoomHandlers): Promise<RoomPort>;
+//# sourceMappingURL=room.d.ts.map

package/dist/plugins/livekit/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../../src/plugins/livekit/room.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,sEAAsE;AACtE,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,kEAAkE;AAClE,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD,wEAAwE;AACxE,eAAO,MAAM,8BAA8B,4BAA4B,CAAC;AAExE,mDAAmD;AACnD,eAAO,MAAM,6BAA6B,2BAA2B,CAAC;AAEtE,4CAA4C;AAC5C,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IACjE,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;CACjD;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC9C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,KAAK,EAAE;IACL,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,OAAO,CAaT;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,gBAAgB,EACxB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAKD,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5D;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,6DAA6D;IAC7D,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,sDAAsD;IACtD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AA0CD,wBAAsB,WAAW,CAC/B,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,QAAQ,CAAC,CA8WnB"}