@mastra/livekit 0.0.0-buttoned-spandex-20260824090603

package/dist/bridge.d.ts

@@ -0,0 +1,229 @@
+import { ReadableStream } from 'node:stream/web';
+import { llm, voice } from '@livekit/agents';
+import type { Agent as MastraAgent, AgentExecutionOptionsBase } from '@mastra/core/agent';
+import type { TracingContext } from '@mastra/core/observability';
+import { RequestContext } from '@mastra/core/request-context';
+import type { VoiceTurnMessage } from './messages.js';
+/** Default spoken text for periodic AI re-disclosure. See {@link MastraVoiceAgentOptions.greetingReminder}. */
+export declare const DEFAULT_DISCLOSURE_REMINDER = "Just a reminder, you're speaking with an AI assistant.";
+/**
+ * Tracks periodic AI re-disclosure for a single call. `due()` returns the reminder text once
+ * `everyMs` has elapsed since the last disclosure (resetting the clock), otherwise `undefined`.
+ * Time is injectable so the interval logic is deterministically testable.
+ */
+export declare class DisclosureReminder {
+    private readonly everyMs;
+    private readonly text;
+    private lastAt;
+    constructor(everyMs: number, text: string, now?: number);
+    /** Call once per turn: the reminder text if it's due, else `undefined`. Does not reset the clock —
+     * call {@link DisclosureReminder.markDelivered} once the reminder is actually threaded into the
+     * outgoing reply, so a reminder that never makes it out isn't silently skipped for a full interval. */
+    due(now?: number): string | undefined;
+    /** Resets the clock. Call only once the reminder text from {@link due} was actually emitted. */
+    markDelivered(now?: number): void;
+}
+/**
+ * Wraps `source` in a stream that emits `text` as a single leading chunk (with a trailing space, so
+ * TTS pauses before the reply) before piping the rest of `source` through unchanged. Cancelling the
+ * wrapper cancels `source` — so barge-in still aborts the underlying generation.
+ */
+export declare function prependText(source: ReadableStream<string>, text: string): ReadableStream<string>;
+export type MastraStreamOptions = Partial<AgentExecutionOptionsBase<unknown>>;
+export interface VoiceToolCall {
+    toolCallId: string;
+    toolName: string;
+    args?: unknown;
+}
+/**
+ * Token usage for one turn, captured from the model's `finish` chunk. Field names mirror LiveKit's
+ * `CompletionUsage` so the plugin can forward it into `metrics_collected` without remapping.
+ */
+export interface VoiceTurnUsage {
+    /** Tokens in the prompt (LiveKit `promptTokens`). */
+    promptTokens: number;
+    /** Tokens in the completion (LiveKit `completionTokens`). */
+    completionTokens: number;
+    /** Cached prompt tokens (LiveKit `promptCachedTokens`). */
+    promptCachedTokens: number;
+    /** Total tokens for the turn. */
+    totalTokens: number;
+}
+/**
+ * Maps a Mastra `finish` chunk's usage (`payload.output.usage`, AI-SDK `LanguageModelUsage`) to the
+ * LiveKit-shaped {@link VoiceTurnUsage}, or `undefined` when the chunk carries no token counts.
+ * Handles both the flat V2 usage shape (`inputTokens`/`outputTokens`) and the nested V3 shape
+ * (`inputTokens.total`/`outputTokens.total`).
+ */
+export declare function mapTurnUsage(usage: unknown): VoiceTurnUsage | undefined;
+export interface MastraVoiceAgentMemory {
+    thread: string;
+    resource?: string;
+}
+/**
+ * Per-turn context handed to a {@link VoiceReplyGenerator}. LiveKit calls `llmNode` once per
+ * detected user turn; the bridge builds this context and asks the generator for the reply.
+ */
+export interface VoiceTurnContext {
+    /**
+     * The messages to generate a reply from. With Mastra Memory on, only the messages new since
+     * the agent last spoke (history comes from the thread); with memory off, the full session.
+     *
+     * For a workflow / custom generator: pass these straight to a memory-backed `agent.stream(...,
+     * { memory })` inside a step so the agent backfills history from the thread (no duplication). A
+     * stateless workflow that wants the entire transcript every turn should read `chatCtx` instead
+     * (e.g. `chatContextToMessages(chatCtx)`), since there is no thread to backfill from.
+     */
+    messages: VoiceTurnMessage[];
+    /** The raw LiveKit chat context, for generators that want the full transcript or message parts. */
+    chatCtx: llm.ChatContext;
+    /** Resolved memory mapping for the call, or `false` when memory is disabled. */
+    memory: MastraVoiceAgentMemory | false;
+    /** Request context forwarded to generation. */
+    requestContext?: RequestContext;
+    /** Voice-call span context, so each turn's generation nests under the call trace. */
+    tracingContext?: TracingContext;
+    /**
+     * Internal, per-turn side channel for token usage. A generator invokes this once, when the
+     * `finish` chunk carries usage, so the caller (e.g. `MastraLLMStream`) can attribute usage to
+     * exactly this turn — kept on the context (not on generator options) so overlapping turns from
+     * preemptive generation can't misattribute usage. Fire-and-forget; the generator does not await it.
+     */
+    onUsage?: (usage: VoiceTurnUsage) => void;
+}
+/**
+ * What a turn produced, handed to {@link VoiceTurnCompleteHook} after the reply finishes.
+ */
+export interface VoiceTurnResult {
+    /** The assistant reply text streamed this turn, accumulated from the model's text deltas. */
+    text: string;
+    /** Tool calls the agent made during the turn, in order. */
+    toolCalls: VoiceToolCall[];
+    /** True when barge-in cut the turn short before it finished streaming. */
+    interrupted: boolean;
+    /** Token usage for the turn when the model reported it in its `finish` chunk. */
+    usage?: VoiceTurnUsage;
+}
+/** {@link VoiceTurnContext} plus the reply it produced. Passed to {@link VoiceTurnCompleteHook}. */
+export interface VoiceTurnCompleteContext extends VoiceTurnContext {
+    /** The reply the agent produced this turn. */
+    result: VoiceTurnResult;
+}
+/**
+ * Called once per turn AFTER the reply has finished streaming to text-to-speech — off the audio
+ * path. It runs fire-and-forget: the turn does not await it, so post-turn work (memory
+ * maintenance, CRM writes, analytics) never delays what the caller hears or the next turn. A
+ * thrown error or rejected promise is logged, not propagated. Because the resolved `memory`
+ * mapping (`thread`/`resource`) is on the context, this is the place for a truly non-blocking
+ * `memory.updateWorkingMemory(...)`. See {@link MastraVoiceAgentOptions.onTurnComplete}.
+ */
+export type VoiceTurnCompleteHook = (ctx: VoiceTurnCompleteContext) => void | Promise<void>;
+/**
+ * Produces a stream of text deltas for one conversational turn, or `null` to stay silent.
+ * Cancelling the returned stream (LiveKit does this on barge-in) must abort the underlying
+ * generation. Built-in implementations: {@link createAgentReplyGenerator} (a Mastra agent) and
+ * `createWorkflowReplyGenerator` (a Mastra workflow).
+ */
+export type VoiceReplyGenerator = (ctx: VoiceTurnContext) => ReadableStream<string> | null | Promise<ReadableStream<string> | null>;
+export interface AgentReplyGeneratorOptions {
+    /** The Mastra agent that generates replies. Tools and memory run inside this agent. */
+    agent: MastraAgent;
+    /** Extra options merged into every `agent.stream()` call (e.g. `tracingContext`). */
+    streamOptions?: MastraStreamOptions;
+    /** Speak a short phrase while a tool call runs. See {@link MastraVoiceAgentOptions.toolFeedback}. */
+    toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;
+    /** Notified as each tool-call chunk arrives, mid-stream. See {@link MastraVoiceAgentOptions.onToolCall}. */
+    onToolCall?: (toolCall: VoiceToolCall) => void;
+    /** Fired off the audio path after the reply streams. See {@link MastraVoiceAgentOptions.onTurnComplete}. */
+    onTurnComplete?: VoiceTurnCompleteHook;
+}
+/**
+ * A {@link VoiceReplyGenerator} backed by a Mastra agent: runs the agent's full loop (model,
+ * tools, memory) and streams its text deltas. On barge-in the returned stream is cancelled,
+ * which aborts the in-flight `agent.stream()`.
+ */
+export declare function createAgentReplyGenerator(options: AgentReplyGeneratorOptions): VoiceReplyGenerator;
+export interface MastraVoiceAgentOptions {
+    /**
+     * The Mastra agent that generates replies. Tools and memory run inside this agent. Provide
+     * either this or {@link MastraVoiceAgentOptions.generate}.
+     */
+    agent?: MastraAgent;
+    /**
+     * A lower-level reply generator (e.g. from `createWorkflowReplyGenerator`). Use instead of
+     * `agent` to drive replies with a workflow or any custom generator.
+     */
+    generate?: VoiceReplyGenerator;
+    /**
+     * Conversation persistence. When set, only messages new since the agent last spoke are
+     * sent each turn and Mastra Memory supplies history. When `false`, the full LiveKit
+     * in-session context is sent on every turn instead.
+     */
+    memory?: MastraVoiceAgentMemory | false;
+    /** Request context entries forwarded to generation. */
+    requestContext?: RequestContext | Record<string, unknown>;
+    /**
+     * Called when the Mastra agent starts a tool call mid-reply. Return a short phrase (e.g. "Let
+     * me look that up.") to speak it while the tool runs; it also appears in the transcript. Return
+     * nothing to stay silent. Applies to the agent generator built here; the workflow generator
+     * takes its own equivalent via `createWorkflowReplyGenerator`.
+     */
+    toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;
+    /**
+     * Called as each tool call starts mid-reply (before the tool result is known), the building block
+     * for tool-driven side effects — analytics, agent-initiated hang-up — without waiting for the turn
+     * to finish. Runs synchronously on the stream; keep it cheap and non-throwing. Applies to the agent
+     * generator built here; the workflow generator surfaces tool calls via `onTurnComplete` instead.
+     */
+    onToolCall?: (toolCall: VoiceToolCall) => void;
+    /**
+     * Called once per turn after the reply has finished streaming to text-to-speech. Runs off the
+     * audio path and fire-and-forget — the turn does not await it — so post-turn memory
+     * maintenance, CRM writes, or analytics never delay the caller or the next turn. The context
+     * carries the produced reply ({@link VoiceTurnResult}) and the resolved `memory` mapping, so
+     * this is where a truly non-blocking `memory.updateWorkingMemory(...)` belongs. A thrown error
+     * or rejected promise is logged, not propagated. Applies to the agent generator built here; the
+     * workflow generator takes its own via `createWorkflowReplyGenerator`.
+     */
+    onTurnComplete?: VoiceTurnCompleteHook;
+    /**
+     * Periodic AI re-disclosure. When set, once `everyMs` has elapsed since the last disclosure the
+     * NEXT turn's reply is prefixed with `text` (spoken at the turn boundary, never mid-turn), so long
+     * calls keep re-disclosing the AI status. Applies to the agent and workflow/custom generators. The
+     * worker derives this from `configuration.greeting.repeatEvery` / `repeatText`; `text` defaults to
+     * {@link DEFAULT_DISCLOSURE_REMINDER}.
+     */
+    greetingReminder?: {
+        everyMs: number;
+        text?: string;
+    };
+    /** Extra options merged into every `agent.stream()` call (agent generator only). */
+    streamOptions?: MastraStreamOptions;
+    /** LiveKit agent instructions. Unused for reply generation (the Mastra agent/workflow applies its own). */
+    instructions?: string;
+    id?: voice.AgentOptions<unknown>['id'];
+    stt?: voice.AgentOptions<unknown>['stt'];
+    vad?: voice.AgentOptions<unknown>['vad'];
+    tts?: voice.AgentOptions<unknown>['tts'];
+    turnHandling?: voice.AgentOptions<unknown>['turnHandling'];
+}
+/**
+ * A LiveKit `voice.Agent` whose replies come from a Mastra agent or workflow.
+ *
+ * LiveKit keeps ownership of the audio loop (VAD, STT, turn detection, TTS, barge-in) and calls
+ * `llmNode` once per detected user turn; the node delegates to a {@link VoiceReplyGenerator}
+ * which streams text deltas back. On barge-in LiveKit cancels the returned stream, which aborts
+ * the in-flight generation.
+ */
+export declare class MastraVoiceAgent extends voice.Agent {
+    readonly mastraAgent?: MastraAgent;
+    readonly memory: MastraVoiceAgentMemory | false;
+    readonly requestContext?: RequestContext;
+    readonly streamOptions?: MastraStreamOptions;
+    private readonly replyGenerator;
+    private readonly reminder?;
+    constructor(options: MastraVoiceAgentOptions);
+    llmNode(chatCtx: llm.ChatContext, _toolCtx: llm.ToolContext, _modelSettings: voice.ModelSettings): Promise<ReadableStream<llm.ChatChunk | string> | null>;
+}
+export declare function createMastraVoiceAgent(options: MastraVoiceAgentOptions): MastraVoiceAgent;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

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

package/dist/consent.d.ts

@@ -0,0 +1,55 @@
+/** A consent decision captured from the caller during a call. */
+export interface ConsentGrant {
+    /**
+     * The consent item, matching a key in the worker's `configuration.consentPolicy` (e.g.
+     * `'summaryStorage'`).
+     */
+    item: string;
+    /** `true` if the caller agreed, `false` if they declined. */
+    granted: boolean;
+    /** The caller the grant belongs to (the memory `resource`), when the call is memory-scoped. */
+    resourceId?: string;
+    /** The call thread the grant was captured on, when the call is memory-scoped. */
+    threadId?: string;
+}
+export interface ConsentToolOptions {
+    /**
+     * Persist the caller's decision to YOUR system of record (database, CRM, consent ledger). Called
+     * each time the caller answers a consent question — keep it quick, it runs inside the turn. This
+     * tool owns extracting the caller's identity from the tool execution context; you own storage, so
+     * consent lives in a durable, compliant place rather than an opaque plugin store. Read those
+     * grants back at `onCallEnd` (or before any consent-gated step) to enforce the requirement.
+     */
+    onGrant: (grant: ConsentGrant) => void | Promise<void>;
+    /** Tool id the agent calls. Defaults to `'recordConsent'`. */
+    id?: string;
+    /** Override the description the model sees when deciding to call the tool. */
+    description?: string;
+    /** Restrict the accepted consent items to this set (becomes an enum). Defaults to any string. */
+    items?: readonly string[];
+}
+/**
+ * Builds a Mastra tool that captures the caller's consent decisions at runtime — the companion to
+ * the worker's `configuration.consentPolicy`, which only DECLARES which consents a call needs. Add
+ * it to the agent that answers the call; on each call the tool reads the caller's `resourceId` /
+ * `threadId` from its execution context and hands the decision to your `onGrant` store. The runtime
+ * grants live only where `onGrant` put them: enforce consent by reading them back from your own
+ * store — at `onCallEnd` or before any consent-gated action — cross-checking against the declared
+ * requirements in `VoiceCallEndArgs.configuration.consentPolicy` (the configuration carries the
+ * policy, never the grants).
+ *
+ * ```ts
+ * // agent tools
+ * recordConsent: createConsentTool({
+ *   items: ['summaryStorage'],
+ *   onGrant: async ({ item, granted, resourceId }) => {
+ *     if (resourceId) await db.saveConsent(resourceId, item, granted);
+ *   },
+ * }),
+ * ```
+ */
+export declare function createConsentTool(options: ConsentToolOptions): import("@mastra/core/tools").Tool<{
+    item: string;
+    granted: boolean;
+}, unknown, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, string, unknown>;
+//# sourceMappingURL=consent.d.ts.map

package/dist/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../src/consent.ts"],"names":[],"mappings":"AAMA,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB;;;6HAiB5D"}

package/dist/constants.d.ts

@@ -0,0 +1,3 @@
+/** Default LiveKit agent name used for explicit dispatch when none is configured. */
+export declare const DEFAULT_LIVEKIT_AGENT_NAME = "mastra-voice";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,iBAAiB,CAAC"}

package/dist/dispatch.d.ts

@@ -0,0 +1,20 @@
+import type { LiveKitSessionMetadata } from './metadata.js';
+export interface DispatchVoiceSessionOptions {
+    /** Room to dispatch the agent into (created on demand). */
+    roomName: string;
+    /** Must match the worker's `agentName`. Defaults to `'mastra-voice'`. */
+    agentName?: string;
+    metadata?: LiveKitSessionMetadata;
+    /** Defaults to `LIVEKIT_URL`. */
+    serverUrl?: string;
+    /** Defaults to `LIVEKIT_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `LIVEKIT_API_SECRET`. */
+    apiSecret?: string;
+}
+/**
+ * Programmatically dispatches a Mastra voice agent into a LiveKit room — for
+ * server-initiated sessions such as outbound calls or joining an existing room.
+ */
+export declare function dispatchVoiceSession(options: DispatchVoiceSessionOptions): Promise<import("livekit-server-sdk").AgentDispatch>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,2BAA2B;IAC1C,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,uDAgB9E"}

package/dist/end-call.d.ts

@@ -0,0 +1,50 @@
+/** Details of the agent's decision to end the call, handed to {@link EndCallToolOptions.onEndCall}. */
+export interface EndCallRequest {
+    /** Short reason the agent gave for ending the call, if any (e.g. "caller said goodbye"). */
+    reason?: string;
+    /** The caller the call belongs to (the memory `resource`), when the call is memory-scoped. */
+    resourceId?: string;
+    /** The call thread, when the call is memory-scoped. */
+    threadId?: string;
+}
+export interface EndCallToolOptions {
+    /**
+     * Tool id the agent calls to end the call. Must match the worker's
+     * `configuration.endCall.tool` (both default to `'endCall'`), since that's the name the worker
+     * watches for to hang up.
+     */
+    id?: string;
+    /** Override the description the model sees when deciding to call the tool. */
+    description?: string;
+    /**
+     * Optional bookkeeping hook, called when the agent invokes the tool (records the reason, marks
+     * the call resolved in your CRM, …). Runs inside the turn — keep it quick. It does NOT hang up
+     * the call; the worker does that once the agent's final words finish playing. The tool reads the
+     * caller's identity from its execution context and passes it here.
+     */
+    onEndCall?: (request: EndCallRequest) => void | Promise<void>;
+}
+/**
+ * Builds a Mastra tool the agent calls to end the call itself (say goodbye → hang up). It is the
+ * agent-visible half of agent-initiated hang-up: the tool only SIGNALS intent (and runs optional
+ * bookkeeping) — it can't reach the LiveKit room from inside `agent.stream()`. The worker owns the
+ * hang-up: with `configuration.endCall` set, it watches each turn for this tool, waits for the
+ * agent's closing words to finish playing, then disconnects (running `onCallEnd` on the way out).
+ * Keeping the tool inside the single agent means it stays visible/editable in Studio and works on
+ * the agent and workflow reply paths alike.
+ *
+ * ```ts
+ * // agent tools
+ * endCall: createEndCallTool({
+ *   onEndCall: ({ reason, resourceId }) => log.info('agent ended call', { reason, resourceId }),
+ * }),
+ * // worker
+ * createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } });
+ * ```
+ */
+export declare function createEndCallTool(options?: EndCallToolOptions): import("@mastra/core/tools").Tool<{
+    reason?: string | null | undefined;
+}, {
+    ended: boolean;
+}, unknown, unknown, import("@mastra/core/tools").ToolExecutionContext<unknown, unknown, unknown>, string, unknown>;
+//# sourceMappingURL=end-call.d.ts.map

package/dist/end-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"end-call.d.ts","sourceRoot":"","sources":["../src/end-call.ts"],"names":[],"mappings":"AAMA,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB;;;;oHA0BjE"}

package/dist/index.cjs

@@ -0,0 +1,189 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_workflow_generator = require("./workflow-generator-B67QrY8L.cjs");
+let crypto = require("crypto");
+let _livekit_protocol = require("@livekit/protocol");
+let livekit_server_sdk = require("livekit-server-sdk");
+let _mastra_core_tools = require("@mastra/core/tools");
+let zod = require("zod");
+//#region src/routes.ts
+function stringField(body, key) {
+	const value = body[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/**
+* An ApiRoute for `server.apiRoutes` that mints a LiveKit access token with the Mastra
+* voice agent dispatched into the room. Frontends call it to join a voice session:
+*
+* ```ts
+* export const mastra = new Mastra({
+*   agents: { support },
+*   server: { apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })] },
+* });
+* ```
+*/
+function liveKitConnectionRoute(options = {}) {
+	const handler = async (c) => {
+		const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;
+		const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;
+		const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;
+		if (!serverUrl || !apiKey || !apiSecret) return c.json({ error: "LiveKit is not configured. Set LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET (or pass serverUrl/apiKey/apiSecret to liveKitConnectionRoute)." }, 500);
+		const body = await c.req.json().then((parsed) => parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}).catch(() => ({}));
+		const args = {
+			body,
+			context: c
+		};
+		const metadata = options.metadata ? await options.metadata(args) : {
+			agentId: stringField(body, "agentId"),
+			threadId: stringField(body, "threadId"),
+			resourceId: stringField(body, "resourceId")
+		};
+		const roomName = typeof options.roomName === "function" ? options.roomName(args) : options.roomName ?? `mastra-voice-${(0, crypto.randomUUID)().slice(0, 8)}`;
+		const identity = typeof options.participantIdentity === "function" ? options.participantIdentity(args) : options.participantIdentity ?? metadata.resourceId ?? `user-${(0, crypto.randomUUID)().slice(0, 8)}`;
+		metadata.threadId ??= roomName;
+		const token = new livekit_server_sdk.AccessToken(apiKey, apiSecret, {
+			identity,
+			ttl: options.ttl ?? "15m"
+		});
+		token.addGrant({
+			room: roomName,
+			roomJoin: true,
+			canPublish: true,
+			canSubscribe: true,
+			canPublishData: true,
+			canUpdateOwnMetadata: true
+		});
+		token.roomConfig = new _livekit_protocol.RoomConfiguration({ agents: [new _livekit_protocol.RoomAgentDispatch({
+			agentName: options.agentName ?? "mastra-voice",
+			metadata: require_workflow_generator.serializeSessionMetadata(metadata)
+		})] });
+		const details = {
+			serverUrl,
+			roomName,
+			participantName: identity,
+			participantToken: await token.toJwt()
+		};
+		return c.json(details);
+	};
+	return {
+		path: options.path ?? "/voice/livekit/connection-details",
+		method: "POST",
+		requiresAuth: options.requiresAuth,
+		handler
+	};
+}
+//#endregion
+//#region src/dispatch.ts
+function toHttpUrl(url) {
+	return url.replace(/^ws/, "http");
+}
+/**
+* Programmatically dispatches a Mastra voice agent into a LiveKit room — for
+* server-initiated sessions such as outbound calls or joining an existing room.
+*/
+async function dispatchVoiceSession(options) {
+	const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;
+	const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;
+	const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;
+	if (!serverUrl) throw new Error("@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.");
+	if (!apiKey || !apiSecret) throw new Error("@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.");
+	return new livekit_server_sdk.AgentDispatchClient(toHttpUrl(serverUrl), apiKey, apiSecret).createDispatch(options.roomName, options.agentName ?? "mastra-voice", { metadata: require_workflow_generator.serializeSessionMetadata(options.metadata ?? {}) });
+}
+//#endregion
+//#region src/consent.ts
+const DEFAULT_DESCRIPTION$1 = "Record the caller's consent decision for a data-processing item (for example, storing a summary of the call). Call this as soon as the caller answers a consent question: granted = true if they agree, false if they decline. Do not proceed with an activity that requires consent until you have recorded the caller granting it.";
+/**
+* Builds a Mastra tool that captures the caller's consent decisions at runtime — the companion to
+* the worker's `configuration.consentPolicy`, which only DECLARES which consents a call needs. Add
+* it to the agent that answers the call; on each call the tool reads the caller's `resourceId` /
+* `threadId` from its execution context and hands the decision to your `onGrant` store. The runtime
+* grants live only where `onGrant` put them: enforce consent by reading them back from your own
+* store — at `onCallEnd` or before any consent-gated action — cross-checking against the declared
+* requirements in `VoiceCallEndArgs.configuration.consentPolicy` (the configuration carries the
+* policy, never the grants).
+*
+* ```ts
+* // agent tools
+* recordConsent: createConsentTool({
+*   items: ['summaryStorage'],
+*   onGrant: async ({ item, granted, resourceId }) => {
+*     if (resourceId) await db.saveConsent(resourceId, item, granted);
+*   },
+* }),
+* ```
+*/
+function createConsentTool(options) {
+	const items = options.items;
+	const itemSchema = items && items.length > 0 ? zod.z.enum([...items]) : zod.z.string();
+	return (0, _mastra_core_tools.createTool)({
+		id: options.id ?? "recordConsent",
+		description: options.description ?? DEFAULT_DESCRIPTION$1,
+		inputSchema: zod.z.object({
+			item: itemSchema.describe("The consent item the caller is answering for (matches the deployment's required consents)."),
+			granted: zod.z.boolean().describe("True if the caller agreed, false if they declined.")
+		}),
+		execute: async ({ item, granted }, { agent }) => {
+			await options.onGrant({
+				item,
+				granted,
+				resourceId: agent?.resourceId,
+				threadId: agent?.threadId
+			});
+			return {
+				recorded: true,
+				item,
+				granted
+			};
+		}
+	});
+}
+//#endregion
+//#region src/end-call.ts
+const DEFAULT_DESCRIPTION = "End the phone call. Call this only after you have said goodbye and there is nothing left to do — for example the caller says goodbye, or the task is complete and you have wrapped up. Say your closing line first, then call this as your final action; the call hangs up once your words finish playing. Your closing line must be a final statement, never a question — if you are asking the caller anything (for example whether they need anything else), do NOT call this in that reply; wait for their answer. Do not call it if the caller still needs something.";
+/**
+* Builds a Mastra tool the agent calls to end the call itself (say goodbye → hang up). It is the
+* agent-visible half of agent-initiated hang-up: the tool only SIGNALS intent (and runs optional
+* bookkeeping) — it can't reach the LiveKit room from inside `agent.stream()`. The worker owns the
+* hang-up: with `configuration.endCall` set, it watches each turn for this tool, waits for the
+* agent's closing words to finish playing, then disconnects (running `onCallEnd` on the way out).
+* Keeping the tool inside the single agent means it stays visible/editable in Studio and works on
+* the agent and workflow reply paths alike.
+*
+* ```ts
+* // agent tools
+* endCall: createEndCallTool({
+*   onEndCall: ({ reason, resourceId }) => log.info('agent ended call', { reason, resourceId }),
+* }),
+* // worker
+* createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } });
+* ```
+*/
+function createEndCallTool(options = {}) {
+	return (0, _mastra_core_tools.createTool)({
+		id: options.id ?? "endCall",
+		description: options.description ?? DEFAULT_DESCRIPTION,
+		inputSchema: zod.z.object({ reason: zod.z.string().nullish().describe("Short reason the call is ending, e.g. \"caller said goodbye\" or \"task complete\".") }),
+		outputSchema: zod.z.object({ ended: zod.z.boolean() }),
+		execute: async ({ reason }, { agent }) => {
+			try {
+				await options.onEndCall?.({
+					reason: reason ?? void 0,
+					resourceId: agent?.resourceId,
+					threadId: agent?.threadId
+				});
+			} catch (error) {
+				console.warn("@mastra/livekit: onEndCall hook threw", error);
+			}
+			return { ended: true };
+		}
+	});
+}
+//#endregion
+exports.DEFAULT_LIVEKIT_AGENT_NAME = require_workflow_generator.DEFAULT_LIVEKIT_AGENT_NAME;
+exports.createConsentTool = createConsentTool;
+exports.createEndCallTool = createEndCallTool;
+exports.dispatchVoiceSession = dispatchVoiceSession;
+exports.liveKitConnectionRoute = liveKitConnectionRoute;
+exports.pipeAgentReplyToWriter = require_workflow_generator.pipeAgentReplyToWriter;
+exports.serializeSessionMetadata = require_workflow_generator.serializeSessionMetadata;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["AccessToken","RoomConfiguration","RoomAgentDispatch","serializeSessionMetadata","AgentDispatchClient","serializeSessionMetadata","DEFAULT_DESCRIPTION","z","z"],"sources":["../src/routes.ts","../src/dispatch.ts","../src/consent.ts","../src/end-call.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport { RoomAgentDispatch, RoomConfiguration } from '@livekit/protocol';\nimport type { ContextWithMastra, ApiRoute } from '@mastra/core/server';\nimport { AccessToken } from 'livekit-server-sdk';\nimport { DEFAULT_LIVEKIT_AGENT_NAME } from './constants';\nimport { serializeSessionMetadata } from './metadata';\nimport type { LiveKitSessionMetadata } from './metadata';\n\n/** Response body of the connection-details route. Matches LiveKit's frontend starter contract. */\nexport interface LiveKitConnectionDetails {\n  serverUrl: string;\n  roomName: string;\n  participantName: string;\n  participantToken: string;\n}\n\nexport interface ConnectionRequestArgs {\n  body: Record<string, unknown>;\n  context: ContextWithMastra;\n}\n\nexport interface LiveKitConnectionRouteOptions {\n  /**\n   * Route path. Defaults to `/voice/livekit/connection-details`. Mastra reserves the\n   * `/api` prefix for built-in routes, so custom paths must not start with `/api`.\n   */\n  path?: string;\n  /** LiveKit server URL (`wss://...`). Defaults to `LIVEKIT_URL`. */\n  serverUrl?: string;\n  /** Defaults to `LIVEKIT_API_KEY`. */\n  apiKey?: string;\n  /** Defaults to `LIVEKIT_API_SECRET`. */\n  apiSecret?: string;\n  /** LiveKit agent name for explicit dispatch. Must match the worker's `agentName`. */\n  agentName?: string;\n  /** Token time-to-live. Defaults to `'15m'`. */\n  ttl?: string | number;\n  /** Defaults to `true` (Mastra custom routes require auth unless opted out). */\n  requiresAuth?: boolean;\n  roomName?: string | ((args: ConnectionRequestArgs) => string);\n  participantIdentity?: string | ((args: ConnectionRequestArgs) => string);\n  /**\n   * Session metadata delivered to the worker via agent dispatch. Defaults to passing\n   * through `agentId`, `threadId`, and `resourceId` from the request body.\n   */\n  metadata?: (args: ConnectionRequestArgs) => LiveKitSessionMetadata | Promise<LiveKitSessionMetadata>;\n}\n\nfunction stringField(body: Record<string, unknown>, key: string): string | undefined {\n  const value = body[key];\n  return typeof value === 'string' && value.length > 0 ? value : undefined;\n}\n\n/**\n * An ApiRoute for `server.apiRoutes` that mints a LiveKit access token with the Mastra\n * voice agent dispatched into the room. Frontends call it to join a voice session:\n *\n * ```ts\n * export const mastra = new Mastra({\n *   agents: { support },\n *   server: { apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })] },\n * });\n * ```\n */\nexport function liveKitConnectionRoute(options: LiveKitConnectionRouteOptions = {}): ApiRoute {\n  const handler = async (c: ContextWithMastra) => {\n    const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;\n    const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;\n    const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;\n    if (!serverUrl || !apiKey || !apiSecret) {\n      return c.json(\n        {\n          error:\n            'LiveKit is not configured. Set LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET ' +\n            '(or pass serverUrl/apiKey/apiSecret to liveKitConnectionRoute).',\n        },\n        500,\n      );\n    }\n\n    const body: Record<string, unknown> = await c.req\n      .json()\n      .then((parsed: unknown) =>\n        parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {},\n      )\n      .catch(() => ({}));\n    const args: ConnectionRequestArgs = { body, context: c };\n\n    const metadata: LiveKitSessionMetadata = options.metadata\n      ? await options.metadata(args)\n      : {\n          agentId: stringField(body, 'agentId'),\n          threadId: stringField(body, 'threadId'),\n          resourceId: stringField(body, 'resourceId'),\n        };\n\n    const roomName =\n      typeof options.roomName === 'function'\n        ? options.roomName(args)\n        : (options.roomName ?? `mastra-voice-${randomUUID().slice(0, 8)}`);\n    const identity =\n      typeof options.participantIdentity === 'function'\n        ? options.participantIdentity(args)\n        : (options.participantIdentity ?? metadata.resourceId ?? `user-${randomUUID().slice(0, 8)}`);\n    // One memory thread per room unless the caller pins a thread explicitly.\n    metadata.threadId ??= roomName;\n\n    const token = new AccessToken(apiKey, apiSecret, { identity, ttl: options.ttl ?? '15m' });\n    token.addGrant({\n      room: roomName,\n      roomJoin: true,\n      canPublish: true,\n      canSubscribe: true,\n      canPublishData: true,\n      canUpdateOwnMetadata: true,\n    });\n    token.roomConfig = new RoomConfiguration({\n      agents: [\n        new RoomAgentDispatch({\n          agentName: options.agentName ?? DEFAULT_LIVEKIT_AGENT_NAME,\n          metadata: serializeSessionMetadata(metadata),\n        }),\n      ],\n    });\n\n    const details: LiveKitConnectionDetails = {\n      serverUrl,\n      roomName,\n      participantName: identity,\n      participantToken: await token.toJwt(),\n    };\n    return c.json(details);\n  };\n\n  return {\n    path: options.path ?? '/voice/livekit/connection-details',\n    method: 'POST',\n    requiresAuth: options.requiresAuth,\n    handler,\n  } as ApiRoute;\n}\n","import { AgentDispatchClient } from 'livekit-server-sdk';\nimport { DEFAULT_LIVEKIT_AGENT_NAME } from './constants';\nimport { serializeSessionMetadata } from './metadata';\nimport type { LiveKitSessionMetadata } from './metadata';\n\nexport interface DispatchVoiceSessionOptions {\n  /** Room to dispatch the agent into (created on demand). */\n  roomName: string;\n  /** Must match the worker's `agentName`. Defaults to `'mastra-voice'`. */\n  agentName?: string;\n  metadata?: LiveKitSessionMetadata;\n  /** Defaults to `LIVEKIT_URL`. */\n  serverUrl?: string;\n  /** Defaults to `LIVEKIT_API_KEY`. */\n  apiKey?: string;\n  /** Defaults to `LIVEKIT_API_SECRET`. */\n  apiSecret?: string;\n}\n\nfunction toHttpUrl(url: string): string {\n  return url.replace(/^ws/, 'http');\n}\n\n/**\n * Programmatically dispatches a Mastra voice agent into a LiveKit room — for\n * server-initiated sessions such as outbound calls or joining an existing room.\n */\nexport async function dispatchVoiceSession(options: DispatchVoiceSessionOptions) {\n  const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;\n  const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;\n  const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;\n  if (!serverUrl) {\n    throw new Error('@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.');\n  }\n  if (!apiKey || !apiSecret) {\n    throw new Error(\n      '@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.',\n    );\n  }\n  const client = new AgentDispatchClient(toHttpUrl(serverUrl), apiKey, apiSecret);\n  return client.createDispatch(options.roomName, options.agentName ?? DEFAULT_LIVEKIT_AGENT_NAME, {\n    metadata: serializeSessionMetadata(options.metadata ?? {}),\n  });\n}\n","// Server-safe: only depends on `@mastra/core` + zod, never the `@livekit/agents` runtime — so it\n// can be added to agents defined in server/shared code and re-exported from the root entry\n// (`index.ts`). `index.test.ts` enforces that boundary.\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\n/** A consent decision captured from the caller during a call. */\nexport interface ConsentGrant {\n  /**\n   * The consent item, matching a key in the worker's `configuration.consentPolicy` (e.g.\n   * `'summaryStorage'`).\n   */\n  item: string;\n  /** `true` if the caller agreed, `false` if they declined. */\n  granted: boolean;\n  /** The caller the grant belongs to (the memory `resource`), when the call is memory-scoped. */\n  resourceId?: string;\n  /** The call thread the grant was captured on, when the call is memory-scoped. */\n  threadId?: string;\n}\n\nexport interface ConsentToolOptions {\n  /**\n   * Persist the caller's decision to YOUR system of record (database, CRM, consent ledger). Called\n   * each time the caller answers a consent question — keep it quick, it runs inside the turn. This\n   * tool owns extracting the caller's identity from the tool execution context; you own storage, so\n   * consent lives in a durable, compliant place rather than an opaque plugin store. Read those\n   * grants back at `onCallEnd` (or before any consent-gated step) to enforce the requirement.\n   */\n  onGrant: (grant: ConsentGrant) => void | Promise<void>;\n  /** Tool id the agent calls. Defaults to `'recordConsent'`. */\n  id?: string;\n  /** Override the description the model sees when deciding to call the tool. */\n  description?: string;\n  /** Restrict the accepted consent items to this set (becomes an enum). Defaults to any string. */\n  items?: readonly string[];\n}\n\nconst DEFAULT_DESCRIPTION =\n  \"Record the caller's consent decision for a data-processing item (for example, storing a summary \" +\n  'of the call). Call this as soon as the caller answers a consent question: granted = true if they ' +\n  'agree, false if they decline. Do not proceed with an activity that requires consent until you ' +\n  'have recorded the caller granting it.';\n\n/**\n * Builds a Mastra tool that captures the caller's consent decisions at runtime — the companion to\n * the worker's `configuration.consentPolicy`, which only DECLARES which consents a call needs. Add\n * it to the agent that answers the call; on each call the tool reads the caller's `resourceId` /\n * `threadId` from its execution context and hands the decision to your `onGrant` store. The runtime\n * grants live only where `onGrant` put them: enforce consent by reading them back from your own\n * store — at `onCallEnd` or before any consent-gated action — cross-checking against the declared\n * requirements in `VoiceCallEndArgs.configuration.consentPolicy` (the configuration carries the\n * policy, never the grants).\n *\n * ```ts\n * // agent tools\n * recordConsent: createConsentTool({\n *   items: ['summaryStorage'],\n *   onGrant: async ({ item, granted, resourceId }) => {\n *     if (resourceId) await db.saveConsent(resourceId, item, granted);\n *   },\n * }),\n * ```\n */\nexport function createConsentTool(options: ConsentToolOptions) {\n  const items = options.items;\n  const itemSchema = items && items.length > 0 ? z.enum([...items] as [string, ...string[]]) : z.string();\n  return createTool({\n    id: options.id ?? 'recordConsent',\n    description: options.description ?? DEFAULT_DESCRIPTION,\n    inputSchema: z.object({\n      item: itemSchema.describe(\n        \"The consent item the caller is answering for (matches the deployment's required consents).\",\n      ),\n      granted: z.boolean().describe('True if the caller agreed, false if they declined.'),\n    }),\n    execute: async ({ item, granted }, { agent }) => {\n      await options.onGrant({ item, granted, resourceId: agent?.resourceId, threadId: agent?.threadId });\n      return { recorded: true as const, item, granted };\n    },\n  });\n}\n","// Server-safe: only depends on `@mastra/core` + zod, never the `@livekit/agents` runtime — so it\n// can be added to agents defined in server/shared code and re-exported from the root entry\n// (`index.ts`). `index.test.ts` enforces that boundary.\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\n/** Details of the agent's decision to end the call, handed to {@link EndCallToolOptions.onEndCall}. */\nexport interface EndCallRequest {\n  /** Short reason the agent gave for ending the call, if any (e.g. \"caller said goodbye\"). */\n  reason?: string;\n  /** The caller the call belongs to (the memory `resource`), when the call is memory-scoped. */\n  resourceId?: string;\n  /** The call thread, when the call is memory-scoped. */\n  threadId?: string;\n}\n\nexport interface EndCallToolOptions {\n  /**\n   * Tool id the agent calls to end the call. Must match the worker's\n   * `configuration.endCall.tool` (both default to `'endCall'`), since that's the name the worker\n   * watches for to hang up.\n   */\n  id?: string;\n  /** Override the description the model sees when deciding to call the tool. */\n  description?: string;\n  /**\n   * Optional bookkeeping hook, called when the agent invokes the tool (records the reason, marks\n   * the call resolved in your CRM, …). Runs inside the turn — keep it quick. It does NOT hang up\n   * the call; the worker does that once the agent's final words finish playing. The tool reads the\n   * caller's identity from its execution context and passes it here.\n   */\n  onEndCall?: (request: EndCallRequest) => void | Promise<void>;\n}\n\nconst DEFAULT_DESCRIPTION =\n  'End the phone call. Call this only after you have said goodbye and there is nothing left to do — ' +\n  'for example the caller says goodbye, or the task is complete and you have wrapped up. Say your ' +\n  'closing line first, then call this as your final action; the call hangs up once your words finish ' +\n  'playing. Your closing line must be a final statement, never a question — if you are asking the ' +\n  'caller anything (for example whether they need anything else), do NOT call this in that reply; ' +\n  'wait for their answer. Do not call it if the caller still needs something.';\n\n/**\n * Builds a Mastra tool the agent calls to end the call itself (say goodbye → hang up). It is the\n * agent-visible half of agent-initiated hang-up: the tool only SIGNALS intent (and runs optional\n * bookkeeping) — it can't reach the LiveKit room from inside `agent.stream()`. The worker owns the\n * hang-up: with `configuration.endCall` set, it watches each turn for this tool, waits for the\n * agent's closing words to finish playing, then disconnects (running `onCallEnd` on the way out).\n * Keeping the tool inside the single agent means it stays visible/editable in Studio and works on\n * the agent and workflow reply paths alike.\n *\n * ```ts\n * // agent tools\n * endCall: createEndCallTool({\n *   onEndCall: ({ reason, resourceId }) => log.info('agent ended call', { reason, resourceId }),\n * }),\n * // worker\n * createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } });\n * ```\n */\nexport function createEndCallTool(options: EndCallToolOptions = {}) {\n  return createTool({\n    id: options.id ?? 'endCall',\n    description: options.description ?? DEFAULT_DESCRIPTION,\n    inputSchema: z.object({\n      reason: z\n        .string()\n        .nullish()\n        .describe('Short reason the call is ending, e.g. \"caller said goodbye\" or \"task complete\".'),\n    }),\n    outputSchema: z.object({ ended: z.boolean() }),\n    execute: async ({ reason }, { agent }) => {\n      try {\n        await options.onEndCall?.({\n          reason: reason ?? undefined,\n          resourceId: agent?.resourceId,\n          threadId: agent?.threadId,\n        });\n      } catch (error) {\n        // Bookkeeping is best-effort — the tool must still signal `{ ended: true }` so the worker's\n        // end-call detector runs and the call actually hangs up.\n        console.warn('@mastra/livekit: onEndCall hook threw', error);\n      }\n      return { ended: true as const };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { liveKitConnectionRoute } from './routes.js';
+export type { LiveKitConnectionRouteOptions, LiveKitConnectionDetails, ConnectionRequestArgs } from './routes.js';
+export { dispatchVoiceSession } from './dispatch.js';
+export type { DispatchVoiceSessionOptions } from './dispatch.js';
+export { serializeSessionMetadata } from './metadata.js';
+export type { LiveKitSessionMetadata } from './metadata.js';
+export { pipeAgentReplyToWriter } from './workflow-generator.js';
+export type { AgentReplyStreamLike } from './workflow-generator.js';
+export { createConsentTool } from './consent.js';
+export type { ConsentGrant, ConsentToolOptions } from './consent.js';
+export { createEndCallTool } from './end-call.js';
+export type { EndCallRequest, EndCallToolOptions } from './end-call.js';
+export { DEFAULT_LIVEKIT_AGENT_NAME } from './constants.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC/G,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}