@mastra/livekit 0.0.0-aggregate-trace-20261015182851

package/LICENSE.md

@@ -0,0 +1,32 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named `ee/` within this
+  repository, including but not limited to:
+  - `@mastra/core/auth/ee`
+  - `@mastra/core/agent-builder/ee`
+  - `@mastra/editor/ee`
+
+  is licensed under the license defined in [`ee/LICENSE`](https://github.com/mastra-ai/mastra/blob/main/ee/LICENSE).
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,48 @@
+# @mastra/livekit
+
+Realtime voice for [Mastra](https://mastra.ai) agents and workflows, powered by [LiveKit Agents](https://docs.livekit.io/agents/).
+
+LiveKit's agents framework owns the **audio loop** — WebRTC transport, voice activity detection (VAD), streaming speech-to-text (STT), semantic turn detection, barge-in, and text-to-speech (TTS). This package bridges **reply generation** to Mastra, so each detected user turn is answered by a Mastra **agent** (`agent.stream()`) or **workflow** — with your tools, memory, processors, and model routing all running inside Mastra.
+## Installation
+
+```bash
+npm install @mastra/livekit
+```
+
+## Usage
+
+Set `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET`. Add a connection route to your Mastra server so clients can receive a room token and dispatch the configured agent.
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { Mastra } from '@mastra/core/mastra';
+import { liveKitConnectionRoute } from '@mastra/livekit';
+
+const supportAgent = new Agent({
+  id: 'support',
+  name: 'Support agent',
+  instructions: 'Keep voice responses short and conversational.',
+  model: 'openai/gpt-5-mini',
+});
+
+export const mastra = new Mastra({
+  agents: { supportAgent },
+  server: {
+    apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })],
+  },
+});
+```
+
+Run a separate LiveKit worker to own the audio pipeline and call the agent for each detected turn. See the quickstart for the worker setup and required LiveKit plugins.
+
+## Documentation
+
+- [@mastra/livekit documentation](https://mastra.ai/integrations/voice/livekit)
+
+## Changelog
+
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/integrations/livekit/CHANGELOG.md) for version history and release notes.
+
+## Support
+
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/dist/bridge.d.ts

@@ -0,0 +1,256 @@
+import { ReadableStream } from 'node:stream/web';
+import { FlushSentinel, llm, voice } from '@livekit/agents';
+import type { Agent as MastraAgent, AgentExecutionOptionsBase, AgentMemoryOption } from '@mastra/core/agent';
+import type { TracingContext } from '@mastra/core/observability';
+import { RequestContext } from '@mastra/core/request-context';
+import type { VoiceTurnMessage } from './messages.js';
+import { createGenerationMetrics } from './turn-metrics.js';
+import type { VoiceReplyChunk, VoiceTurnMetricsHook } from './turn-metrics.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<T>(source: ReadableStream<T>, text: string): ReadableStream<T | 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-call Mastra memory config forwarded to the agent as `memory.options` (see core's
+     * `AgentMemoryOption`). The notable use is `{ readOnly: true }`: the agent still reads thread
+     * history but persists nothing, which keeps LiveKit's preemptive (speculative) turns from writing
+     * partial user and assistant messages to the thread. With `readOnly` the caller owns persistence
+     * of committed turns (e.g. from `onTurnComplete` via `memory.saveMessages`).
+     */
+    options?: AgentMemoryOption['options'];
+}
+/**
+ * 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 {
+    /** Stable user-turn identifier, supplied by the worker or plugin. */
+    turnId?: string;
+    /** Unique generation attempt identifier, including speculative replies and retries. */
+    attemptId?: string;
+    /** @internal Bridge-side timing collector. */
+    metrics?: ReturnType<typeof createGenerationMetrics>;
+    /**
+     * 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<VoiceReplyChunk> | null | Promise<ReadableStream<VoiceReplyChunk> | 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 {
+    /** Receives per-attempt generation metrics. Playback metrics come from observeVoiceSession. */
+    onTurnMetrics?: VoiceTurnMetricsHook;
+    /**
+     * 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 onTurnMetrics?;
+    private readonly reminder?;
+    constructor(options: MastraVoiceAgentOptions);
+    llmNode(chatCtx: llm.ChatContext, _toolCtx: llm.ToolContext, _modelSettings: voice.ModelSettings): Promise<ReadableStream<llm.ChatChunk | string | FlushSentinel> | null>;
+}
+export declare function createMastraVoiceAgent(options: MastraVoiceAgentOptions): MastraVoiceAgent;
+/** @internal Wrap every reply source, including custom generators, with one terminal metric. */
+export declare function instrumentVoiceReply(generator: VoiceReplyGenerator, ctx: VoiceTurnContext, onTurnMetrics?: VoiceTurnMetricsHook): Promise<{
+    reply: ReadableStream<VoiceReplyChunk> | null;
+    identity: {
+        turnId: string;
+        attemptId: string;
+    };
+}>;
+//# 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/client-entry.cjs

@@ -0,0 +1,17 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _mastra_client_js = require("@mastra/client-js");
+//#region src/client-entry.ts
+/** Requests a fresh playback URL using the client's authentication and fetch configuration. */
+function getLiveKitRecording(client, traceId, options) {
+	return new _mastra_client_js.MastraClient({
+		...client.options,
+		apiPrefix: ""
+	}).request(`/voice/livekit/recordings/${encodeURIComponent(traceId)}`, {
+		retries: 0,
+		signal: options?.signal
+	});
+}
+//#endregion
+exports.getLiveKitRecording = getLiveKitRecording;
+
+//# sourceMappingURL=client-entry.cjs.map

package/dist/client-entry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-entry.cjs","names":["MastraClient"],"sources":["../src/client-entry.ts"],"sourcesContent":["// Browser-safe entry point. Keep server routes, credentials, and worker runtimes out of this module.\nimport { MastraClient } from '@mastra/client-js';\nimport type { LiveKitRecordingResponse } from './recording-types';\n\nexport type { LiveKitRecording, LiveKitRecordingResponse } from './recording-types';\n\n/** Requests a fresh playback URL using the client's authentication and fetch configuration. */\nexport function getLiveKitRecording(\n  client: Pick<MastraClient, 'options'>,\n  traceId: string,\n  options?: { signal?: AbortSignal },\n): Promise<LiveKitRecordingResponse> {\n  // Custom integration routes mount at the server root, independently of apiPrefix.\n  // A separate client preserves the original client's routing and transport settings.\n  const integration = new MastraClient({ ...client.options, apiPrefix: '' });\n  return integration.request(`/voice/livekit/recordings/${encodeURIComponent(traceId)}`, {\n    retries: 0,\n    signal: options?.signal,\n  });\n}\n"],"mappings":";;;;AAOA,SAAgB,oBACd,QACA,SACA,SACmC;CAInC,OAAO,IADiBA,kBAAAA,aAAa;EAAE,GAAG,OAAO;EAAS,WAAW;CAAG,CACvD,CAAC,CAAC,QAAQ,6BAA6B,mBAAmB,OAAO,KAAK;EACrF,SAAS;EACT,QAAQ,SAAS;CACnB,CAAC;AACH"}

package/dist/client-entry.d.ts

@@ -0,0 +1,8 @@
+import { MastraClient } from '@mastra/client-js';
+import type { LiveKitRecordingResponse } from './recording-types.js';
+export type { LiveKitRecording, LiveKitRecordingResponse } from './recording-types.js';
+/** Requests a fresh playback URL using the client's authentication and fetch configuration. */
+export declare function getLiveKitRecording(client: Pick<MastraClient, 'options'>, traceId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<LiveKitRecordingResponse>;
+//# sourceMappingURL=client-entry.d.ts.map

package/dist/client-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-entry.d.ts","sourceRoot":"","sources":["../src/client-entry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAElE,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAEpF,+FAA+F;AAC/F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,EACrC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAQnC"}

package/dist/client-entry.js

@@ -0,0 +1,16 @@
+import { MastraClient } from "@mastra/client-js";
+//#region src/client-entry.ts
+/** Requests a fresh playback URL using the client's authentication and fetch configuration. */
+function getLiveKitRecording(client, traceId, options) {
+	return new MastraClient({
+		...client.options,
+		apiPrefix: ""
+	}).request(`/voice/livekit/recordings/${encodeURIComponent(traceId)}`, {
+		retries: 0,
+		signal: options?.signal
+	});
+}
+//#endregion
+export { getLiveKitRecording };
+
+//# sourceMappingURL=client-entry.js.map

package/dist/client-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-entry.js","names":[],"sources":["../src/client-entry.ts"],"sourcesContent":["// Browser-safe entry point. Keep server routes, credentials, and worker runtimes out of this module.\nimport { MastraClient } from '@mastra/client-js';\nimport type { LiveKitRecordingResponse } from './recording-types';\n\nexport type { LiveKitRecording, LiveKitRecordingResponse } from './recording-types';\n\n/** Requests a fresh playback URL using the client's authentication and fetch configuration. */\nexport function getLiveKitRecording(\n  client: Pick<MastraClient, 'options'>,\n  traceId: string,\n  options?: { signal?: AbortSignal },\n): Promise<LiveKitRecordingResponse> {\n  // Custom integration routes mount at the server root, independently of apiPrefix.\n  // A separate client preserves the original client's routing and transport settings.\n  const integration = new MastraClient({ ...client.options, apiPrefix: '' });\n  return integration.request(`/voice/livekit/recordings/${encodeURIComponent(traceId)}`, {\n    retries: 0,\n    signal: options?.signal,\n  });\n}\n"],"mappings":";;;AAOA,SAAgB,oBACd,QACA,SACA,SACmC;CAInC,OAAO,IADiB,aAAa;EAAE,GAAG,OAAO;EAAS,WAAW;CAAG,CACvD,CAAC,CAAC,QAAQ,6BAA6B,mBAAmB,OAAO,KAAK;EACrF,SAAS;EACT,QAAQ,SAAS;CACnB,CAAC;AACH"}

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,26 @@
+import type { LiveKitSessionMetadata } from './metadata.js';
+import type { LiveKitRecordingOptions } from './recording.js';
+export interface DispatchVoiceSessionOptions {
+    /**
+     * Room to dispatch the agent into (created on demand). With recording enabled, use a unique
+     * name for each call. An existing room throws LiveKitRecordingRoomConflictError.
+     */
+    roomName: string;
+    /** Must match the worker's `agentName`. Defaults to `'mastra-voice'`. */
+    agentName?: string;
+    metadata?: LiveKitSessionMetadata;
+    /** Create a fresh room with automatic recording before dispatch. Omit to keep dispatch-only behavior. */
+    recording?: LiveKitRecordingOptions;
+    /** 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,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,yGAAyG;IACzG,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,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,uDA0B9E"}

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"}