@mastra/livekit 0.0.0 → 0.2.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# @mastra/livekit
+
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added `@mastra/livekit`, a new package that turns Mastra agents into realtime voice agents using LiveKit. ([#17896](https://github.com/mastra-ai/mastra/pull/17896))
+
+  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.
+
+  **Build a voice worker**
+  - `createLiveKitWorker()` builds a LiveKit worker that answers voice sessions with your Mastra agents; `runLiveKitWorker()` starts its CLI (`dev`/`start`). Both live on the `@mastra/livekit/worker` entry point.
+  - `liveKitConnectionRoute()` is an API route that mints LiveKit tokens and dispatches the voice agent into a room; `dispatchVoiceSession()` does the same programmatically for server-initiated sessions like outbound calls. These live on the `@mastra/livekit` entry point, which is safe to import from Mastra server code — it never loads the LiveKit agents runtime.
+
+  ```ts
+  // src/mastra/voice-worker.ts
+  import { createLiveKitWorker } from '@mastra/livekit/worker';
+  import { mastra } from './index';
+
+  export default createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+    turnDetection: 'multilingual',
+  });
+  ```
+
+  **Drive replies with an agent or a workflow**
+
+  Each turn's reply can come from a Mastra agent (the default) or a Mastra workflow. With a workflow, LiveKit still owns the audio loop and calls into Mastra once per turn, so the workflow runs to completion each turn (no suspend/resume) — pass the transcript in, stream the reply out.
+  - `workflow` / `workflowInput` options on `createLiveKitWorker()` drive replies with a workflow.
+  - `pipeAgentReplyToWriter(agentStream, writer)` streams an agent's reply from inside a workflow step, forwarding both its words and its tool calls (piping only the text would drop the tool calls).
+  - `generate` is an escape hatch to plug in any custom reply generator.
+
+  ```ts
+  export default createLiveKitWorker({
+    mastra,
+    workflow: 'phoneConversation',
+    workflowInput: ({ messages }) => ({ turn: messages }),
+    replyStep: 'generateResponse',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+  });
+  ```
+
+  **Run work after each turn and at the end of the call**
+  - `onTurnComplete` runs once per turn, right after the reply finishes playing. It runs in the background — the worker never waits for it — so you can save memory, update your CRM, or record analytics without adding any delay for the caller or the next reply. It also runs with `result.interrupted: true` when the caller talks over the agent.
+  - `onCallEnd` runs once when the call ends. Unlike `onTurnComplete`, the worker waits for it to finish before exiting, so it's the place for end-of-call work like summarizing the whole conversation into long-term memory once.
+  - `toolFeedback` speaks a short phrase while a tool runs; `memoryInstance` gives the workflow path a `Memory` instance to open the call's thread and save the greeting, so the saved conversation is complete — greeting included — like the agent path.
+
+  Both hooks work whether you drive replies with an agent or a workflow.
+
+  ```ts
+  createLiveKitWorker({
+    mastra,
+    agent: 'callCenter',
+    onTurnComplete: async ({ result, memory }) => {
+      if (memory) await crm.logContact(memory.resource, result.text);
+    },
+    onCallEnd: async ({ memory }) => {
+      // After the caller hangs up: save a lasting summary of the call.
+    },
+  });
+  ```
+
+  **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 child spans for LiveKit's speech-to-text, text-to-speech, turn-detection, and LLM latency, closing with a per-model token, character, and audio usage roll-up. On by default; pass `observability: false` to disable.
+
+  **Studio voice mode**
+
+  Studio's agent chat gains a voice call mode: when the Mastra server exposes a LiveKit connection route 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.
+
+  See the [LiveKit voice guide](https://mastra.ai/docs/voice/livekit) for setup.
+
+### Patch Changes
+
+- Updated dependencies [[`a0085fa`](https://github.com/mastra-ai/mastra/commit/a0085fa0934e52c37c8c8b3d75a6bb5cd199af36)]:
+  - @mastra/core@1.50.0-alpha.5

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

@@ -1,6 +1,22 @@
 # @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.
+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.
+
+```
+caller speaks ─▶ VAD ─▶ STT ─▶ turn detection ─▶ [ Mastra agent / workflow ] ─▶ TTS ─▶ caller hears
+                  (LiveKit owns the audio loop)        (this package bridges replies)
+```
+
+## What's in the box
+
+- **Two reply paths** — answer turns with a Mastra **agent** (the default, richest path) or a Mastra **workflow** (run-to-completion per turn, e.g. deterministic intent routing). A low-level `generate` escape hatch accepts any custom reply generator.
+- **Full speech stack, pluggable** — STT/TTS as LiveKit inference model strings (`'deepgram/nova-3'`, `'cartesia/sonic-3'`) or your own plugin instances; Silero VAD and LiveKit multilingual/English turn detection; barge-in cancels in-flight generation automatically.
+- **Memory, scoped to the call** — `thread` = call, `resource` = caller, so a returning caller is recognized across calls. Up-front thread creation and greeting persistence keep the saved thread a faithful transcript. Works on the agent path and the workflow path (via `memoryInstance`).
+- **Lifecycle hooks** — `toolFeedback` (speak filler while a tool runs), `onTurnComplete` (post-turn, fire-and-forget, off the audio path), and `onCallEnd` (end-of-call, awaited within LiveKit's shutdown window — the place to flush observational memory).
+- **Observability** — one `voice call` trace per session with LiveKit pipeline metrics and every Mastra run nested under it.
+- **Connection + dispatch helpers** — `liveKitConnectionRoute` mints tokens and dispatches the worker so a frontend can join.
 
 ## Installation
 
@@ -8,22 +24,37 @@ LiveKit voice integration for Mastra agents. LiveKit's agents framework runs the
 npm install @mastra/livekit @livekit/agents @livekit/agents-plugin-silero @livekit/agents-plugin-livekit
 ```
 
-## Usage
+Peer dependencies (`@mastra/core` and `@livekit/agents` are required; the two plugins are optional but enable the defaults):
 
-Create a worker entry file:
+| Package                          | Needed for                                   |
+| -------------------------------- | -------------------------------------------- |
+| `@mastra/core`                   | the Mastra agent/workflow you bridge to      |
+| `@livekit/agents`                | the audio loop runtime                       |
+| `@livekit/agents-plugin-silero`  | the default `vad: 'silero'`                  |
+| `@livekit/agents-plugin-livekit` | `turnDetection: 'multilingual' \| 'english'` |
+
+The package has two entry points, one per process:
+
+- `@mastra/livekit` — server-side helpers (`liveKitConnectionRoute`, `dispatchVoiceSession`, `pipeAgentReplyToWriter`). Safe to import from Mastra server code; never loads the `@livekit/agents` runtime.
+- `@mastra/livekit/worker` — the worker runtime (`createLiveKitWorker`, `runLiveKitWorker`). Import it only from the worker entry file.
+
+## Quick start
+
+A worker is a standalone Node process that connects to LiveKit and answers sessions. Define it with `createLiveKitWorker` and run it with `runLiveKitWorker`:
 
 ```typescript
 // src/mastra/voice-worker.ts
 import { fileURLToPath } from 'node:url';
-import { createLiveKitWorker, runLiveKitWorker } from '@mastra/livekit';
+import { createLiveKitWorker, runLiveKitWorker } from '@mastra/livekit/worker';
 import { mastra } from './index';
 
 export default createLiveKitWorker({
   mastra,
-  agent: 'support',
+  agent: 'support', // a Mastra agent key/id (or a resolver, or use `workflow` instead)
   stt: 'deepgram/nova-3',
   tts: 'cartesia/sonic-3',
   turnDetection: 'multilingual',
+  greeting: 'Thanks for calling. How can I help?',
 });
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -31,7 +62,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 }
 ```
 
-Add a connection endpoint so frontends can join voice sessions:
+Add a connection endpoint to your Mastra server so a frontend can join, then dispatch the worker:
 
 ```typescript
 // src/mastra/index.ts
@@ -48,10 +79,242 @@ export const mastra = new Mastra({
 Run the worker alongside your Mastra server:
 
 ```bash
-npx livekit-agents download-files
+npx livekit-agents download-files   # one-time: turn-detection + VAD model files
 npx tsx src/mastra/voice-worker.ts dev
 ```
 
+The model strings (`deepgram/nova-3`, `cartesia/sonic-3`) route through **LiveKit Cloud inference**, so with a LiveKit Cloud project you don't need separate Deepgram/Cartesia accounts — only your `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` (plus whatever key your Mastra model needs). To bring your own providers, pass plugin instances to `stt` / `tts` instead of strings.
+
+## Reply paths
+
+### Agent (default)
+
+Pass `agent` (a key/id, an `Agent` instance, or a resolver). The agent runs its full loop each turn — model, tools, memory, processors — and streams its text deltas to TTS. Barge-in cancels the in-flight `agent.stream()`.
+
+### Workflow
+
+Pass `workflow` + `workflowInput` instead of `agent` (mutually exclusive). LiveKit owns the turn boundary, so the workflow runs **once to completion per turn** — no suspend/resume. Use it for deterministic per-turn structure (e.g. classify intent, then reply).
+
+```typescript
+import { createLiveKitWorker, chatContextToMessages } from '@mastra/livekit/worker';
+
+export default createLiveKitWorker({
+  mastra,
+  workflow: 'phoneConversation',
+  workflowInput: ({ messages, memory }) => ({ turn: messages, memory: memory || undefined }),
+  replyStep: 'generateResponse', // only stream text from this step (optional)
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  turnDetection: 'multilingual',
+});
+```
+
+In the reply-producing step, use **`pipeAgentReplyToWriter`** to forward the agent's reply into the step `writer`. It streams text deltas (so TTS starts early) **and** tool-call chunks (so `toolFeedback` fires and `onTurnComplete` sees the tool list) — unlike piping only `.textStream`, which silently drops tool calls:
+
+```typescript
+import { pipeAgentReplyToWriter } from '@mastra/livekit';
+
+const generateResponse = createStep({
+  id: 'generateResponse',
+  execute: async ({ inputData, mastra, writer, abortSignal }) => {
+    const stream = await mastra.getAgent('support').stream(inputData.turn, {
+      memory: inputData.memory, // engages working memory, recall, etc.
+      abortSignal, // lets barge-in stop generation promptly
+    });
+    const reply = await pipeAgentReplyToWriter(stream, writer);
+    return { reply };
+  },
+});
+```
+
+A step that writes no text stays silent unless you pass `resultText` to derive the reply from the final run result.
+
+### Custom (`generate`)
+
+For full control, pass a `generate` function — any `VoiceReplyGenerator` that turns a turn into a `ReadableStream<string>` (a remote bridge, a bespoke pipeline, …).
+
+## `createLiveKitWorker` options
+
+| Option                                              | Type                                      | Notes                                                                                                                                                                               |
+| --------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mastra`                                            | `Mastra`                                  | **Required.** The instance whose agents/workflows answer sessions.                                                                                                                  |
+| **Reply generation** (pick one)                     |                                           |                                                                                                                                                                                     |
+| `agent`                                             | `string \| Agent \| (args) => …`          | The agent that answers. Defaults to `metadata.agentId`.                                                                                                                             |
+| `workflow`                                          | `string \| Workflow \| (args) => string`  | Answer with a workflow instead. Requires `workflowInput`.                                                                                                                           |
+| `workflowInput`                                     | `(ctx & { metadata }) => inputData`       | Maps a turn into the workflow's `inputData`.                                                                                                                                        |
+| `replyStep`                                         | `string`                                  | Only stream text from this workflow step id.                                                                                                                                        |
+| `resultText`                                        | `(result) => string`                      | Fallback reply text when the workflow streams nothing.                                                                                                                              |
+| `generate`                                          | `VoiceReplyGenerator`                     | Lowest-level escape hatch.                                                                                                                                                          |
+| **Speech stack**                                    |                                           |                                                                                                                                                                                     |
+| `stt`                                               | plugin or `'provider/model'`              | Speech-to-text.                                                                                                                                                                     |
+| `tts`                                               | plugin or `'provider/model'`              | Text-to-speech.                                                                                                                                                                     |
+| `vad`                                               | `VAD \| 'silero' \| false`                | Voice activity detection. Defaults to `'silero'`.                                                                                                                                   |
+| `turnDetection`                                     | `'multilingual' \| 'english' \| …`        | End-of-turn detection.                                                                                                                                                              |
+| `turnHandling`                                      | `AgentSessionOptions['turnHandling']`     | Endpointing delays, interruption sensitivity, preemptive generation.                                                                                                                |
+| `sessionOptions` / `inputOptions` / `outputOptions` | partial LiveKit options                   | Merged over what the helper builds.                                                                                                                                                 |
+| **Memory**                                          |                                           |                                                                                                                                                                                     |
+| `memory`                                            | `false \| (args) => { thread, resource }` | Memory mapping. Defaults to `{ thread: metadata.threadId ?? room, resource: metadata.resourceId ?? thread }` when the agent has memory.                                             |
+| `memoryInstance`                                    | `Memory \| (args) => Memory`              | The `Memory` used to bootstrap the thread + persist the greeting on the **workflow/custom** path (no agent to source it from). Mastra storage is injected if the `Memory` has none. |
+| `greeting`                                          | `string`                                  | Spoken when the session starts.                                                                                                                                                     |
+| `persistGreeting`                                   | `boolean`                                 | Save the greeting to the thread. Defaults to `true`.                                                                                                                                |
+| **Lifecycle hooks**                                 |                                           |                                                                                                                                                                                     |
+| `toolFeedback`                                      | `(toolCall) => string \| void`            | Speak filler while a tool runs (agent + workflow).                                                                                                                                  |
+| `onTurnComplete`                                    | `VoiceTurnCompleteHook`                   | After each turn streams, **fire-and-forget**, off the audio path.                                                                                                                   |
+| `onCallEnd`                                         | `VoiceCallEndHook`                        | When the call ends, **awaited** within LiveKit's shutdown window.                                                                                                                   |
+| `onSessionStart`                                    | `(args) => …`                             | After the session starts — attach listeners, trigger replies, etc.                                                                                                                  |
+| **Other**                                           |                                           |                                                                                                                                                                                     |
+| `observability`                                     | `boolean`                                 | Voice-pipeline tracing. Defaults to `true`.                                                                                                                                         |
+
+## Lifecycle hooks
+
+Three hooks let you do work around a turn without adding to the caller's latency:
+
+```typescript
+createLiveKitWorker({
+  mastra,
+  agent: 'support',
+
+  // 1. In-turn: speak a short phrase while a tool runs, so the caller isn't left in silence.
+  toolFeedback: ({ toolName }) => (toolName === 'lookupOrder' ? 'Let me pull that up.' : undefined),
+
+  // 2. Post-turn: fire-and-forget AFTER the reply has streamed — the worker never awaits it, so it
+  //    can't delay the caller or the next turn. Carries the produced reply + the memory mapping.
+  onTurnComplete: async ({ result, memory }) => {
+    if (memory) await crm.logContact(memory.resource, result.text); // result.text/toolCalls/interrupted
+  },
+
+  // 3. End-of-call: runs when the caller hangs up, AWAITED within LiveKit's shutdown grace window
+  //    (so it finishes before the process exits). The place for end-of-call memory maintenance.
+  onCallEnd: async ({ memory, memoryInstance }) => {
+    // e.g. flush observational memory once for the whole call instead of paying for it per turn.
+  },
+});
+```
+
+`onTurnComplete` and `toolFeedback` work on the **workflow** path too (the reply step must surface tool calls via `pipeAgentReplyToWriter`).
+
+## Joining a call: `liveKitConnectionRoute`
+
+Mounts an API route on your Mastra server that mints a LiveKit token and dispatches the worker by `agentName`. Frontends `POST` to it to get connection details.
+
+| Option                               | Default                                                  | Notes                                               |
+| ------------------------------------ | -------------------------------------------------------- | --------------------------------------------------- |
+| `path`                               | `/voice/livekit/connection-details`                      | Must not start with `/api`.                         |
+| `serverUrl` / `apiKey` / `apiSecret` | `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET` | LiveKit credentials.                                |
+| `agentName`                          | —                                                        | Must match the worker's `agentName`.                |
+| `ttl`                                | `'15m'`                                                  | Token lifetime.                                     |
+| `requiresAuth`                       | `true`                                                   | Mastra custom routes require auth unless opted out. |
+| `roomName` / `participantIdentity`   | generated                                                | String or `(args) => string`.                       |
+| `metadata`                           | passes `agentId`/`threadId`/`resourceId`                 | Session metadata delivered to the worker.           |
+
+For programmatic dispatch (no HTTP), use `dispatchVoiceSession`.
+
+## Running the worker: `runLiveKitWorker`
+
+Starts the LiveKit agent worker CLI (`dev` / `start` / `connect`) for your entry file.
+
+| Option          | Default          | Notes                                               |
+| --------------- | ---------------- | --------------------------------------------------- |
+| `entry`         | —                | The worker module; pass `import.meta.url`.          |
+| `agentName`     | `'mastra-voice'` | Dispatch name; must match `liveKitConnectionRoute`. |
+| `serverOptions` | —                | Extra LiveKit `ServerOptions`.                      |
+
+## Observability
+
+When the Mastra instance has observability configured, the worker opens one `voice call` span per session, nests every turn's Mastra run under it, and adds child spans for LiveKit pipeline metrics — STT, TTS, end-of-utterance, VAD, and LLM time-to-first-token — closing with a per-model token/character/audio usage roll-up. On by default; pass `observability: false` to disable.
+
+## Deployment
+
+A voice deployment is **two long-running processes** plus a LiveKit media server:
+
+| Component                | What runs it                                                        | Notes                                                                                                     |
+| ------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| **LiveKit media server** | LiveKit Cloud, or self-hosted `livekit-server` + Redis              | WebRTC transport. Both processes below need its `LIVEKIT_URL` / `LIVEKIT_API_KEY` / `LIVEKIT_API_SECRET`. |
+| **Mastra HTTP server**   | `mastra build` → `node .mastra/output/index.mjs`                    | Your agents/workflows + `liveKitConnectionRoute` (mints tokens, dispatches the worker).                   |
+| **LiveKit worker**       | your worker entry → `runLiveKitWorker` (LiveKit Agents CLI `start`) | Connects **outbound** to the media server and answers calls. Not an HTTP server.                          |
+
+The worker is a **separate process**: `mastra build` bundles only your `Mastra` instance and `src/mastra/tools/**` — never the worker entry, because nothing imports it. `liveKitConnectionRoute`, by contrast, is an `apiRoute`, so it ships inside the server build automatically. The server and worker therefore build and run independently and can live on different hosts, as long as they share a LiveKit project and the same `agentName`.
+
+> Note: `mastra worker build` is unrelated — it bundles Mastra's own pubsub/scheduler workflow workers (`mastra.startWorkers()`), not this LiveKit worker.
+
+### Building the worker
+
+The worker imports `@livekit/agents` (plus the optional plugins) and your `Mastra` instance, then runs the LiveKit Agents CLI. Two build-time essentials:
+
+- **Run `start`, not `dev`, in production** — `dev` is hot-reload only.
+- **Pre-download the model files** so they're baked into the image instead of fetched on cold start:
+
+```bash
+node --import tsx src/mastra/voice-worker.ts download-files   # Silero VAD + turn-detector ONNX
+```
+
+Running the worker with `tsx` against source avoids bundling LiveKit's native deps (onnxruntime, …). If you do, make `tsx` and the `@livekit/agents*` packages **real** dependencies (not devDependencies) in the deployed image.
+
+### Docker
+
+Build the server with `mastra build`, bake the model files, then run the two processes. **Recommended: one image, two services** — workers scale by call volume and the HTTP server scales by request volume, so keep them independent:
+
+```dockerfile
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npx mastra build
+RUN node --import tsx src/mastra/voice-worker.ts download-files
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=build /app /app
+ENV NODE_ENV=production
+EXPOSE 4111
+# server service: CMD ["node", ".mastra/output/index.mjs"]
+# worker service: CMD ["node", "--import", "tsx", "src/mastra/voice-worker.ts", "start"]
+```
+
+To run **both in one container** (single-tenant boxes, demos), supervise them with `bash` so the container exits — and is restarted by the orchestrator — if either dies:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+node .mastra/output/index.mjs &
+node --import tsx src/mastra/voice-worker.ts start &
+wait -n
+exit 1
+```
+
+This is simpler, but it couples two processes that have opposite scaling curves and no independent autoscaling — prefer the split for anything beyond a demo.
+
+### Managed platforms (Mastra Cloud, Railway, Cloud Run, …)
+
+Single-process HTTP hosts run the **Mastra server** as-is (`node .mastra/output/index.mjs`). They can't host the worker — it isn't an HTTP server, it isn't in the build output, and it's a long-lived outbound connection. Deploy the **hybrid**: the server on the managed platform (it still mints tokens and dispatches via the bundled connection route), and the worker on any plain process host (a dedicated Railway/Fly/Render service, a VM, a Kubernetes `Deployment`, ECS, …). Point both at the same LiveKit project, keep ≥1 always-on worker instance (no scale-to-zero, so it stays registered), and inject the shared `LIVEKIT_*` env into both.
+
+## Runnable example
+
+A complete, runnable reference lives in the Mastra monorepo at **[`examples/voice-agent`](https://github.com/mastra-ai/mastra/tree/main/examples/voice-agent)** — a trades-contractor front-desk voice agent that exercises nearly every feature here:
+
+- **Both entrypoints** — an agent worker (`pnpm worker`) and a workflow worker (`pnpm worker:workflow`, deterministic intent routing → memory-backed reply).
+- **Three memory layers** — working memory, semantic recall, and observational memory, all scoped to the caller.
+- **Tools + deterministic reconciliation**, a tenant-context input processor, the `toolFeedback` / `onTurnComplete` / `onCallEnd` hooks, and full observability.
+
+To run it:
+
+```bash
+git clone https://github.com/mastra-ai/mastra
+cd mastra && pnpm install && pnpm build:packages   # build the workspace packages
+
+cd examples/voice-agent
+cp .env.example .env            # add LiveKit Cloud creds + your model key (e.g. OPENAI_API_KEY)
+pnpm install
+pnpm worker:download-files      # one-time model download
+
+# in two terminals:
+pnpm dev                        # Mastra server + Studio at http://localhost:4111
+pnpm worker                     # the voice worker (or `pnpm worker:workflow`)
+```
+
+See the example's own [`README.md`](https://github.com/mastra-ai/mastra/tree/main/examples/voice-agent) for the scenario walkthrough and the memory/latency design notes.
+
 ## Documentation
 
 - [Using LiveKit with Mastra](https://mastra.ai/docs/voice/livekit)

package/dist/bridge.d.ts

@@ -0,0 +1,153 @@
+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';
+export type MastraStreamOptions = Partial<AgentExecutionOptionsBase<unknown>>;
+export interface VoiceToolCall {
+    toolCallId: string;
+    toolName: string;
+    args?: unknown;
+}
+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;
+}
+/**
+ * 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;
+}
+/** {@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;
+    /** 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 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;
+    /** 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;
+    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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"}