@mastra/livekit 0.0.0-livekit-alpha-v1-20260624034109

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @mastra/livekit
+
+## 0.0.0-livekit-alpha-v1-20260624034109
+
+### Minor Changes
+
+- Added `@mastra/livekit`, a new package that turns Mastra agents into realtime voice agents using LiveKit. ([`f9221f9`](https://github.com/mastra-ai/mastra/commit/f9221f984e636bae56a770688ab2b8b46a17282f))
+
+  LiveKit's agents framework runs the audio loop — WebRTC transport, voice activity detection, streaming speech-to-text, semantic turn detection, and barge-in — while your Mastra agent generates every reply with its own model, tools, and memory. When a caller interrupts the agent, LiveKit cancels the in-flight stream and Mastra stops generating.
+
+  **What's included**
+  - `createLiveKitWorker()`: builds a LiveKit agent worker that answers voice sessions with your Mastra agents
+  - `runLiveKitWorker()`: starts the worker CLI (`dev`/`start`) for a worker entry file
+  - `createMastraVoiceAgent()`: the lower-level bridge for custom worker setups
+  - `liveKitConnectionRoute()`: an API route that mints LiveKit tokens and dispatches the voice agent into a room
+  - `dispatchVoiceSession()`: programmatic dispatch for server-initiated sessions such as outbound calls
+  - Built-in observability: when the Mastra instance has observability configured, each call opens a `voice call` trace that nests every turn's agent run and adds a child span for LiveKit's speech-to-text, text-to-speech, turn-detection, and LLM latency metrics, closing with a per-model token, character, and audio usage roll-up. On by default; pass `observability: false` to disable.
+
+  ```ts
+  // src/mastra/voice-worker.ts
+  import { createLiveKitWorker } from '@mastra/livekit';
+  import { mastra } from './index';
+
+  export default createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+    turnDetection: 'multilingual',
+  });
+  ```
+
+  See the [LiveKit voice guide](https://mastra.ai/docs/voice/livekit) for setup.
+
+### Patch Changes
+
+- Added a voice call mode to the Studio agent chat. When the Mastra server exposes a LiveKit connection route (from `@mastra/livekit`) and a voice worker is running, a phone button in the chat composer starts a realtime voice session with the agent: live captions, agent state (listening, thinking, speaking), and barge-in all surface in the chat, and the conversation lands in the same memory thread as text chat. ([`f9221f9`](https://github.com/mastra-ai/mastra/commit/f9221f984e636bae56a770688ab2b8b46a17282f))
+
+- Updated dependencies [[`5bd72d2`](https://github.com/mastra-ai/mastra/commit/5bd72d255f45b5ea8ab342643bd463814a980a24), [`1cc9ee1`](https://github.com/mastra-ai/mastra/commit/1cc9ee1ba51db53020a735626d33017a60b4b5b3), [`417baae`](https://github.com/mastra-ai/mastra/commit/417baae40b995db5819c845036947f0c27dc1c00), [`65f255a`](https://github.com/mastra-ai/mastra/commit/65f255a38667beb6ceeadabfa9eb5059bfec8298), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`30ebaf0`](https://github.com/mastra-ai/mastra/commit/30ebaf07bed5f4d30f2f257836c15d1bf7e40aae), [`5704634`](https://github.com/mastra-ai/mastra/commit/5704634b22133167dea337a942a34f57aaa3fa14), [`5c4e9a4`](https://github.com/mastra-ai/mastra/commit/5c4e9a4cfb2216bb3ea7f8988ad3727f3b92bb3a), [`4a88c6e`](https://github.com/mastra-ai/mastra/commit/4a88c6e2bdce316f8d7551b4ec3449b0b06fc71c), [`417baae`](https://github.com/mastra-ai/mastra/commit/417baae40b995db5819c845036947f0c27dc1c00), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`25961e3`](https://github.com/mastra-ai/mastra/commit/25961e3260ff3b1464637af8fcdb36210551c39f), [`6a1428a`](https://github.com/mastra-ai/mastra/commit/6a1428a23133fc070fc6c1caa08d28f3ba4fe5ff), [`87a17ef`](https://github.com/mastra-ai/mastra/commit/87a17efbd725aca6639febdc5e69e2abb3048689), [`e11ff30`](https://github.com/mastra-ai/mastra/commit/e11ff301408bf1731dca2fb7fbfcd8c819500a35), [`7794d71`](https://github.com/mastra-ai/mastra/commit/7794d71872c68733a30e028dfb7b1705daf6c5d2), [`9d2c946`](https://github.com/mastra-ai/mastra/commit/9d2c946d0859e90ae4bcec5beeb1da7398d2ad1e), [`c0eda2b`](https://github.com/mastra-ai/mastra/commit/c0eda2bcd91a228427314b12c91d8b147f3a739f), [`c0eda2b`](https://github.com/mastra-ai/mastra/commit/c0eda2bcd91a228427314b12c91d8b147f3a739f), [`b13925b`](https://github.com/mastra-ai/mastra/commit/b13925bfa91aa8700f56fa54a9ce707ee7e4ba62), [`f1ec385`](https://github.com/mastra-ai/mastra/commit/f1ec385386f62b1a0847ec5353ae2bb169d1c3d9), [`e14986f`](https://github.com/mastra-ai/mastra/commit/e14986f6e5478d6384d04ff9a7f9a79a46a8b529), [`24912b1`](https://github.com/mastra-ai/mastra/commit/24912b1f855d29ec36af4ef4bde1f7417e20cdf5), [`bf94ec6`](https://github.com/mastra-ai/mastra/commit/bf94ec68192d9f16e46ef7e5ac36370aeeddf35d), [`a29f371`](https://github.com/mastra-ai/mastra/commit/a29f371aef629ac8562661524a497127e93b5131), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`073f910`](https://github.com/mastra-ai/mastra/commit/073f910481e7d94b95ba3830f96531774ae95d33), [`0be490f`](https://github.com/mastra-ai/mastra/commit/0be490fabb538c5a7de796ea0aff7d04a0bea1f3), [`0be490f`](https://github.com/mastra-ai/mastra/commit/0be490fabb538c5a7de796ea0aff7d04a0bea1f3), [`ebbe1d3`](https://github.com/mastra-ai/mastra/commit/ebbe1d31a965a3adb0e728758f326b8122b4b55f), [`974f614`](https://github.com/mastra-ai/mastra/commit/974f614e083bd68278536f94453f7b320b86a3c7), [`975c59a`](https://github.com/mastra-ai/mastra/commit/975c59ae363ee275fc55062392e1ffd2cbccbd53), [`1f97ce5`](https://github.com/mastra-ai/mastra/commit/1f97ce5695463bebb4eaacf501da6fb403e20885), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`7f51548`](https://github.com/mastra-ai/mastra/commit/7f515481213780be7047cef00640b9d35f3d545c), [`64f58c0`](https://github.com/mastra-ai/mastra/commit/64f58c04e78b40137497d47f781e897e416f22a5), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`ebbe1d3`](https://github.com/mastra-ai/mastra/commit/ebbe1d31a965a3adb0e728758f326b8122b4b55f), [`417baae`](https://github.com/mastra-ai/mastra/commit/417baae40b995db5819c845036947f0c27dc1c00), [`8e25a78`](https://github.com/mastra-ai/mastra/commit/8e25a78e0597575f0b0729bae8c5e190c84869b5), [`417baae`](https://github.com/mastra-ai/mastra/commit/417baae40b995db5819c845036947f0c27dc1c00), [`f3f0c9d`](https://github.com/mastra-ai/mastra/commit/f3f0c9d7c878db5a13177871ce3523a14f14b311), [`a5b22d3`](https://github.com/mastra-ai/mastra/commit/a5b22d314d62a68d801886a8d3d0eb6c089473db), [`31be1cf`](https://github.com/mastra-ai/mastra/commit/31be1cf5f2a7b5eef12f6123a40653b4d8115c16), [`417baae`](https://github.com/mastra-ai/mastra/commit/417baae40b995db5819c845036947f0c27dc1c00), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858), [`74955f9`](https://github.com/mastra-ai/mastra/commit/74955f9120cde8b1d8ce4399232b4033236be858)]:
+  - @mastra/core@0.0.0-livekit-alpha-v1-20260624034109

package/LICENSE.md

@@ -0,0 +1,30 @@
+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:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `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,63 @@
+# @mastra/livekit
+
+LiveKit voice integration for Mastra agents. LiveKit's agents framework runs the audio loop — WebRTC transport, voice activity detection, streaming speech-to-text, semantic turn detection, barge-in, and text-to-speech — and this package bridges reply generation to a Mastra agent's `stream()` call, so tools, memory, and model routing all run inside Mastra.
+
+## Installation
+
+```bash
+npm install @mastra/livekit @livekit/agents @livekit/agents-plugin-silero @livekit/agents-plugin-livekit
+```
+
+## Usage
+
+Create a worker entry file:
+
+```typescript
+// src/mastra/voice-worker.ts
+import { fileURLToPath } from 'node:url';
+import { createLiveKitWorker, runLiveKitWorker } from '@mastra/livekit';
+import { mastra } from './index';
+
+export default createLiveKitWorker({
+  mastra,
+  agent: 'support',
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  turnDetection: 'multilingual',
+});
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  runLiveKitWorker({ entry: import.meta.url, agentName: 'mastra-voice' });
+}
+```
+
+Add a connection endpoint so frontends can join voice sessions:
+
+```typescript
+// src/mastra/index.ts
+import { Mastra } from '@mastra/core/mastra';
+import { liveKitConnectionRoute } from '@mastra/livekit';
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })],
+  },
+});
+```
+
+Run the worker alongside your Mastra server:
+
+```bash
+npx livekit-agents download-files
+npx tsx src/mastra/voice-worker.ts dev
+```
+
+## Observability
+
+When the Mastra instance has observability configured, the worker traces each call. It opens one `voice call` span per session, nests every turn's Mastra agent run under it, and adds a child span for each LiveKit pipeline metric — speech-to-text, text-to-speech, end-of-utterance, voice activity detection, and LLM time-to-first-token. The span closes with a per-model token, character, and audio usage roll-up. Tracing is on by default; pass `observability: false` to `createLiveKitWorker` to disable it.
+
+## Documentation
+
+- [Using LiveKit with Mastra](https://mastra.ai/docs/voice/livekit)
+- [`@mastra/livekit` reference](https://mastra.ai/reference/voice/livekit)
+- [LiveKit Agents docs](https://docs.livekit.io/agents/)

package/dist/bridge.d.ts

@@ -0,0 +1,60 @@
+import { ReadableStream } from 'node:stream/web';
+import { llm, voice } from '@livekit/agents';
+import type { Agent as MastraAgent, AgentExecutionOptionsBase } from '@mastra/core/agent';
+import { RequestContext } from '@mastra/core/request-context';
+export type MastraStreamOptions = Partial<AgentExecutionOptionsBase<unknown>>;
+export interface VoiceToolCall {
+    toolCallId: string;
+    toolName: string;
+    args?: unknown;
+}
+export interface MastraVoiceAgentMemory {
+    thread: string;
+    resource?: string;
+}
+export interface MastraVoiceAgentOptions {
+    /** The Mastra agent that generates replies. Tools and memory run inside this agent. */
+    agent: MastraAgent;
+    /**
+     * 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 `agent.stream()`. */
+    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.
+     */
+    toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;
+    /** Extra options merged into every `agent.stream()` call. */
+    streamOptions?: MastraStreamOptions;
+    /** LiveKit agent instructions. Unused for reply generation (the Mastra agent 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.
+ *
+ * LiveKit keeps ownership of the audio loop (VAD, STT, turn detection, TTS, barge-in)
+ * and calls `llmNode` to generate each reply; the node runs the Mastra agent's full
+ * loop — model, tools, memory — and streams text deltas back. On barge-in LiveKit
+ * cancels the returned stream, which aborts the in-flight Mastra stream.
+ */
+export declare class MastraVoiceAgent extends voice.Agent {
+    readonly mastraAgent: MastraAgent;
+    readonly memory: MastraVoiceAgentMemory | false;
+    readonly requestContext?: RequestContext;
+    readonly toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;
+    readonly streamOptions?: MastraStreamOptions;
+    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":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,IAAI,WAAW,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAM9D,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,yBAAyB,CAAC,OAAO,CAAC,CAAC,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,KAAK,EAAE,WAAW,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,sBAAsB,GAAG,KAAK,CAAC;IACxC,6DAA6D;IAC7D,cAAc,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1D;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACtE,6DAA6D;IAC7D,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACvC,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,CAAC;CAC5D;AAiCD;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK,CAAC,KAAK;IAC/C,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,KAAK,CAAC;IAChD,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAC;gBAEjC,OAAO,EAAE,uBAAuB;IAiB7B,OAAO,CACpB,OAAO,EAAE,GAAG,CAAC,WAAW,EACxB,QAAQ,EAAE,GAAG,CAAC,WAAW,EACzB,cAAc,EAAE,KAAK,CAAC,aAAa,GAClC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC;CAkD1D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAEzF"}

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