@mastra/mcp-docs-server 1.2.5-alpha.7 → 1.2.5-alpha.8

package/.docs/docs/agents/overview.md

@@ -4,7 +4,7 @@
 
 Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or multi-agent systems.
 
-**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs.
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.5`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.
 
 Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
 
@@ -54,7 +54,7 @@ export const weatherTool = createTool({
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). It's a bundled model gateway. Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Do not install any AI SDK package unless Mastra's documentation says otherwise.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 
@@ -77,6 +77,7 @@ export const weatherAgent = new Agent({
 
       Use the weatherTool to fetch current weather data.
 `,
+  // Use a string in provider/model format, not provider:model or a provider object.
   model: 'openai/gpt-5.5',
   tools: { weatherTool },
 })

package/.docs/docs/index.md

@@ -4,7 +4,7 @@
 
 Build AI agents your users actually depend on. Mastra is a TypeScript framework that gives you everything you need to prototype fast and ship with confidence. Create your first agent with a single command and start building.
 
-**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs.
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs. Important for later: Define `model` as a string in `provider/model` format, for example `openai/gpt-5.5`. For OpenAI, use `openai/<model>`, not `openai:<model>`, and don't import or pass a provider object.
 
 Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
 
@@ -54,7 +54,7 @@ export const weatherTool = createTool({
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). It's a bundled model gateway. Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Do not install any AI SDK package unless Mastra's documentation says otherwise.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 
@@ -77,6 +77,7 @@ export const weatherAgent = new Agent({
 
       Use the weatherTool to fetch current weather data.
 `,
+  // Use a string in provider/model format, not provider:model or a provider object.
   model: 'openai/gpt-5.5',
   tools: { weatherTool },
 })

package/.docs/docs/long-running-agents/schedules.md

@@ -6,13 +6,11 @@
 
 > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless `agent.generate()` run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 
-Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through `mastra.schedules`, the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) — pass `workflowId` instead of `agentId` to schedule a workflow.
+Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 
-## Prerequisites
-
-Schedules require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain, for example `@mastra/libsql`. Without one, `mastra.schedules.create()` throws.
+> **Note:** Schedules require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
 
 ## Quickstart
 
@@ -48,7 +46,7 @@ Mastra starts the scheduler the first time a schedule is created, then fires the
 
 Schedules fire on a cron expression. The `cron` field accepts a standard 5-, 6-, or 7-part cron expression, and it's validated when you create or update the schedule.
 
-Croner nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
+`croner` nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
 
 ```typescript
 // Every weekday at 9am
@@ -85,15 +83,9 @@ await mastra.schedules.create({
 })
 ```
 
-Threaded schedules accept extra fields that control how the signal behaves. They mirror the options [`agent.sendSignal`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
-
-- `signalType`: the [signal type](https://mastra.ai/docs/long-running-agents/signals) to send, for example `notification` or `system-reminder`. Defaults to `notification`.
-- `tagName`: the XML tag the signal renders as. Defaults to `schedule`, so a fire surfaces to the agent as `<schedule>…</schedule>`.
-- `attributes`: values rendered onto the signal's XML tag.
-- `ifActive`: behavior when the thread is already streaming, as `{ behavior, attributes }`. `behavior` is one of `deliver`, `persist`, or `discard`.
-- `ifIdle`: behavior when the thread is idle, as `{ behavior, attributes, streamOptions }`. `behavior` is one of `wake`, `persist`, or `discard`. `streamOptions.requestContext` is applied to the woken run.
+Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
 
-These fields require a `threadId`. Passing them on a threadless schedule throws.
+These fields require a `threadId`. For the full threaded input shape, see the [agent schedule input reference](https://mastra.ai/reference/schedules/overview).
 
 ```typescript
 await mastra.schedules.create({
@@ -116,39 +108,21 @@ await mastra.schedules.create({
 
 ## Managing schedules
 
-Use `mastra.schedules` for all schedule operations. To scope to a single agent, pass `agentId` to `create` or `list`.
+Use `mastra.schedules` for all schedule operations. The service can create, read, update, pause, resume, manually run, and delete schedules.
 
 ```typescript
-// Create
 const schedule = await mastra.schedules.create({
   agentId: 'pinger',
   cron: '0 * * * *',
   prompt: 'Status check.',
 })
 
-// Read
-await mastra.schedules.get(schedule.id)
-await mastra.schedules.list({ agentId: 'pinger' })
-
-// Update — changing cron or timezone recomputes the next fire time
-await mastra.schedules.update(schedule.id, { cron: '*/30 * * * *' })
-
-// Pause and resume
 await mastra.schedules.pause(schedule.id)
 await mastra.schedules.resume(schedule.id)
-
-// Fire once now, off-schedule
-await mastra.schedules.run(schedule.id)
-
-// Delete
-await mastra.schedules.delete(schedule.id)
+await mastra.schedules.run(schedule.id) // Fire once now, off-schedule
 ```
 
-A few rules worth knowing:
-
-- `pause` and `resume` are durable and idempotent. A paused schedule survives restarts, and `resume` recomputes the next fire time from now rather than firing backlogged runs.
-- `run` fires the schedule once immediately without affecting its cadence.
-- `list` filters by `agentId`, `workflowId`, `threadId`, `resourceId`, `name`, and `status`. Without a filter it returns every schedule, agent and workflow alike.
+`pause` and `resume` are durable. `run` fires the schedule once immediately without affecting its cadence. For the complete method list, filters, and patch fields, see the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
 
 ### Workflow schedules
 
@@ -166,7 +140,7 @@ Workflow schedules created this way are independent of the declarative `schedule
 
 ### Custom IDs
 
-By default `create` generates a random `agent_<uuid>` id. Pass `id` to choose a stable one, for example when you want a predictable handle to look up, update, or delete later:
+Pass `id` when you need a predictable handle to look up, update, or delete later.
 
 ```typescript
 await mastra.schedules.create({
@@ -175,14 +149,13 @@ await mastra.schedules.create({
   cron: '0 9 * * *',
   prompt: 'Summarize anything new since yesterday.',
 })
-// stored as `agent_nightly-summary`
 ```
 
-The id is normalized to `agent_<slug>`: the `agent_` prefix is added if missing and the rest is slugified. Workflow schedules normalize to `schedule_<slug>` instead. Creating a schedule with an id that already exists throws, so use `update` to change an existing one.
+See the [`create(input)` reference](https://mastra.ai/reference/schedules/overview) for ID normalization rules and duplicate ID behavior.
 
 ### From the client
 
-The same operations are available from `@mastra/client-js` over the `/api/schedules` routes (`client.createSchedule`, `client.listSchedules`, `client.runSchedule`, and so on), so you can manage schedules from a separate process or a UI.
+The same operations are available from `@mastra/client-js` over the `/api/schedules` routes, so you can manage schedules from a separate process or a UI. See the [client-js agent schedules reference](https://mastra.ai/reference/client-js/agents) for the client method list.
 
 ## Lifecycle hooks
 
@@ -223,5 +196,6 @@ Hook exceptions are caught and logged. They never re-route the worker or trigger
 
 ## Related
 
+- [`mastra.schedules`](https://mastra.ai/reference/schedules/overview): API reference for creating and managing schedules.
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): the delivery mechanism behind threaded schedules.
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): declare a cron schedule on a workflow definition.

package/.docs/docs/voice/livekit.md

@@ -0,0 +1,305 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Using LiveKit with Mastra
+
+[LiveKit](https://livekit.io) is an open source WebRTC platform for realtime audio and video. The [`@mastra/livekit`](https://mastra.ai/reference/voice/livekit) package connects Mastra agents to the [LiveKit Agents framework](https://docs.livekit.io/agents/): LiveKit owns the audio loop like voice activity detection, streaming speech-to-text, semantic turn detection, barge-in, and text-to-speech. Your Mastra agent generates every reply with its own model, tools, and memory.
+
+Use this integration when you need low-latency, interruptible voice conversations. For provider-based speech-to-speech without LiveKit, see [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech).
+
+## Quickstart
+
+These steps take you from an empty project to a voice agent you can talk to. A voice session has two moving parts you set up here: an API route on your Mastra server that hands out access tokens, and a separate worker process that runs the audio pipeline and calls your agent each turn.
+
+1. Install the integration package along with the LiveKit plugins for voice activity detection and turn detection:
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/livekit @livekit/agents @livekit/agents-plugin-silero @livekit/agents-plugin-livekit
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/livekit @livekit/agents @livekit/agents-plugin-silero @livekit/agents-plugin-livekit
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/livekit @livekit/agents @livekit/agents-plugin-silero @livekit/agents-plugin-livekit
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/livekit @livekit/agents @livekit/agents-plugin-silero @livekit/agents-plugin-livekit
+   ```
+
+2. Set your LiveKit credentials inside an `.env` file. Create a free project on [LiveKit Cloud](https://cloud.livekit.io), or run a local server with [`livekit-server --dev`](https://docs.livekit.io/home/self-hosting/local/):
+
+   ```bash
+   LIVEKIT_URL=wss://your-project.livekit.cloud
+   LIVEKIT_API_KEY=your-api-key
+   LIVEKIT_API_SECRET=your-api-secret
+   ```
+
+3. Add a voice agent to your Mastra instance and expose a connection route. The `liveKitConnectionRoute()` helper adds a `POST /voice/livekit/connection-details` endpoint that mints a LiveKit token and dispatches your agent into a room:
+
+   ```typescript
+   import { Mastra } from '@mastra/core/mastra'
+   import { Agent } from '@mastra/core/agent'
+   import { liveKitConnectionRoute } from '@mastra/livekit'
+
+   const supportAgent = new Agent({
+     id: 'support',
+     name: 'Support',
+     instructions: 'You are a friendly phone support agent. Keep replies short and conversational.',
+     model: 'openai/gpt-5-mini',
+   })
+
+   export const mastra = new Mastra({
+     agents: { support: supportAgent },
+     server: {
+       apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })],
+     },
+   })
+   ```
+
+4. Create the worker. It runs as a separate process, answers LiveKit sessions, and calls your agent each turn. Worker APIs live on the `@mastra/livekit/worker` entry point, so the Mastra server never loads the LiveKit agents runtime. This example uses LiveKit Inference model strings for speech-to-text and text-to-speech, so no provider plugins are required:
+
+   ```typescript
+   import { fileURLToPath } from 'node:url'
+   import { createLiveKitWorker, runLiveKitWorker } from '@mastra/livekit/worker'
+   import { mastra } from './index'
+
+   export default createLiveKitWorker({
+     mastra,
+     agent: 'support',
+     stt: 'deepgram/nova-3',
+     tts: 'cartesia/sonic-3',
+     turnDetection: 'multilingual',
+     greeting: 'Hi! How can I help you today?',
+   })
+
+   if (process.argv[1] === fileURLToPath(import.meta.url)) {
+     runLiveKitWorker({ entry: import.meta.url, agentName: 'mastra-voice' })
+   }
+   ```
+
+   The `agent` option selects which Mastra agent answers each session. Pass a fixed key as shown, or omit it to use the `agentId` from the dispatch metadata, so one worker can serve every agent on your Mastra instance.
+
+5. Download the turn detection and voice activity detection models once. Then run the worker in one terminal and your Mastra server in another:
+
+   ```bash
+   npx livekit-agents download-files
+   npx tsx src/mastra/voice-worker.ts dev
+   ```
+
+   **npm**:
+
+   ```bash
+   npm run dev
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run dev
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dev
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run dev
+   ```
+
+   The worker registers with your LiveKit server and waits for sessions, while `mastra dev` serves the connection route.
+
+6. Talk to your agent. Open the hosted [LiveKit Agents Playground](https://agents-playground.livekit.io) and connect it to your project to start a call without building a frontend.
+
+   To wire up your own app instead, call the connection route for a token. `POST /voice/livekit/connection-details` accepts optional `agentId`, `threadId`, and `resourceId` fields in the request body and returns:
+
+   ```json
+   {
+     "serverUrl": "wss://your-project.livekit.cloud",
+     "roomName": "mastra-voice-a1b2c3d4",
+     "participantName": "user-1",
+     "participantToken": "eyJhbGci..."
+   }
+   ```
+
+   This response matches the contract used by LiveKit's frontend starters, so apps built from [agent-starter-react](https://github.com/livekit-examples/agent-starter-react) or the [LiveKit React components](https://docs.livekit.io/reference/components/react/) work without changes.
+
+## Turn detection and interruptions
+
+LiveKit decides when the user finished speaking and when the agent was interrupted. The defaults work well; tune them with `turnHandling`:
+
+```typescript
+export default createLiveKitWorker({
+  mastra,
+  agent: 'support',
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  turnDetection: 'multilingual',
+  turnHandling: {
+    endpointing: { mode: 'dynamic', minDelay: 300, maxDelay: 3000 },
+    interruption: { minDuration: 500, resumeFalseInterruption: true },
+  },
+})
+```
+
+- `turnDetection: 'multilingual'`: Runs LiveKit's semantic end-of-turn model locally on CPU. It reads the live transcript to avoid cutting users off mid-thought. Use `'vad'` or `'stt'` for silence-based endpointing instead.
+- `endpointing`: Bounds how long the agent waits after the user stops speaking.
+- `interruption`: Controls barge-in. When the user speaks over the agent, LiveKit stops playback and cancels the in-flight Mastra stream, so token generation stops too.
+- `preemptiveGeneration`: Starts the Mastra agent's reply while the user is still finishing, hiding time-to-first-token. The worker disables it by default: each preemptive attempt runs the Mastra agent on an interim transcript, and every run persists the user message, which duplicates messages in the thread. Re-enable it with `preemptiveGeneration: { enabled: true }` if latency matters more than exact thread history.
+
+See the [LiveKit turn detection docs](https://docs.livekit.io/agents/logic/turns/) for all options.
+
+## Memory and threads
+
+When the resolved Mastra agent has memory configured, each call becomes one memory thread:
+
+- `thread` defaults to the `threadId` from dispatch metadata, then to the room name.
+- `resource` defaults to the `resourceId` from dispatch metadata, then to the thread. Send your end user's id here so calls group under the right user. Mastra Studio sends the agent id, matching how its sidebar lists threads.
+- When the thread doesn't exist yet, the worker creates it titled "Voice call" with metadata `{ source: 'livekit' }`, and the spoken greeting is saved as the first assistant message so the thread reads as a full call transcript (disable with `persistGreeting: false`).
+
+Each turn sends only the new user input; Mastra Memory supplies history, semantic recall, and working memory. Pin a session to an existing thread by passing `threadId` in the connection request body, which is useful for continuing a text conversation by voice. In Studio, starting a call from an open chat binds the call to that thread, and the transcript fills into the chat after each exchange.
+
+One caveat: when a user interrupts the agent, Mastra Memory stores the full generated reply even though the user only heard part of it. LiveKit's own transcript is truncated to what was spoken.
+
+## Speak while tools run
+
+Voice conversations can't go silent while a slow tool runs. Use `toolFeedback` to speak a short phrase when the Mastra agent starts a tool call:
+
+```typescript
+export default createLiveKitWorker({
+  mastra,
+  agent: 'support',
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  toolFeedback: ({ toolName }) =>
+    toolName === 'searchOrders' ? 'Let me look that up.' : undefined,
+})
+```
+
+The phrase is spoken as part of the reply and appears in the transcript.
+
+## Generate replies with a workflow
+
+By default the worker generates each reply with a Mastra agent. To run multi-step logic per turn (for example classify intent, route, call tools in sequence, then compose a reply), generate replies with a Mastra [workflow](https://mastra.ai/docs/workflows/overview) instead. Set `workflow` in place of `agent`.
+
+LiveKit still owns the audio loop and calls into Mastra once per turn, so the workflow runs to completion each turn. There is no suspend or resume, and no conversation state is carried between turns. Pass the transcript in through `workflowInput` so the workflow stays stateless:
+
+```typescript
+import { createLiveKitWorker, chatContextToMessages } from '@mastra/livekit/worker'
+import { mastra } from './index'
+
+export default createLiveKitWorker({
+  mastra,
+  workflow: 'phoneConversation',
+  workflowInput: ({ chatCtx }) => ({ history: chatContextToMessages(chatCtx) }),
+  replyStep: 'generateResponse',
+  stt: 'deepgram/nova-3',
+  tts: 'cartesia/sonic-3',
+  turnDetection: 'multilingual',
+})
+```
+
+A workflow streams structured step events, not text. To speak tokens as they generate, the reply step pipes its agent's text into the step `writer`:
+
+```typescript
+const generateResponse = createStep({
+  id: 'generateResponse',
+  // input and output schemas omitted
+  execute: async ({ inputData, mastra, writer, abortSignal }) => {
+    const stream = await mastra.getAgent('voice').stream(inputData.history, { abortSignal })
+    await stream.textStream.pipeTo(writer)
+    return { assistantMessage: await stream.text }
+  },
+})
+```
+
+- `replyStep`: Restricts spoken output to one step. Omit it to speak every step that writes to its `writer`.
+- `resultText`: A fallback that derives the reply from the final run result when no step streams text. Streaming through `writer` gives lower time-to-first-token, so prefer it.
+- `abortSignal`: Forward the step's `abortSignal` into `agent.stream()` so barge-in stops generation promptly. When the user interrupts, the worker cancels the run.
+- `generate`: For full control, pass a `generate` function instead. It can be any reply generator that turns a turn into a text stream.
+
+With a workflow, the worker doesn't persist turns automatically the way an agent's `stream()` does. Persist conversation history inside the workflow, or keep the LiveKit transcript as the source of truth and pass it in each turn.
+
+## Server-initiated sessions
+
+Use `dispatchVoiceSession()` to add a voice agent to a room from your own code, for example to join an existing room or to drive an outbound [SIP call](https://docs.livekit.io/sip/):
+
+```typescript
+import { dispatchVoiceSession } from '@mastra/livekit'
+
+await dispatchVoiceSession({
+  roomName: 'support-call-42',
+  agentName: 'mastra-voice',
+  metadata: { agentId: 'support', threadId: 'thread-42', resourceId: 'user-7' },
+})
+```
+
+## Observability
+
+When the Mastra instance has [observability](https://mastra.ai/docs/observability/overview) configured, the worker traces each call. It opens one `voice call` span per session and nests everything under it:
+
+- Every turn's Mastra agent run, with model generation, tool calls, and memory operations, exactly as a text chat records them.
+- A child span for each LiveKit pipeline metric: speech-to-text, text-to-speech, end-of-utterance (turn detection), voice activity detection, and the model's time-to-first-token. These carry the latency and audio measurements that text traces can't show.
+- A per-model usage roll-up (token, character, and audio totals for the whole call) written to the span when the session ends.
+
+The worker is a separate process, so point storage at a backend that accepts concurrent writes from both the server and the worker. SQLite-backed [LibSQL](https://mastra.ai/reference/storage/libsql) works; single-writer stores do not. Traces, memory, and threads can share one store:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { LibSQLStore } from '@mastra/libsql'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({ url: 'file:./voice-agent.db' }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'voice-agent',
+        exporters: [new MastraStorageExporter()],
+      },
+    },
+  }),
+})
+```
+
+Tracing is on by default. Pass `observability: false` to `createLiveKitWorker` to turn it off.
+
+## Deployment
+
+The worker is a separate process from your Mastra server. Deploy it as a long-running Node service with the production command:
+
+```bash
+node dist/voice-worker.js start
+```
+
+LiveKit's guidance on sizing, graceful shutdown, and hosting applies unchanged; see [Deploying agents](https://docs.livekit.io/agents/ops/deployment/). Workers connect outbound to LiveKit, so they don't need inbound ports.
+
+## How it works
+
+A LiveKit voice session involves three pieces:
+
+1. Your Mastra server mints a LiveKit access token and dispatches your agent into a room. The dispatch carries metadata such as the Mastra agent id, memory thread, and resource.
+2. A LiveKit agent worker (a separate long-running process) receives the job and runs the audio pipeline. Audio flows between the browser and the worker over WebRTC and never passes through your Mastra HTTP server.
+3. Each time the user finishes a turn, the worker calls the Mastra agent's `stream()` with the new input and speaks the streamed text. When the user interrupts, LiveKit cancels the stream and Mastra stops generating.
+
+Conversation history lives in Mastra Memory, so voice sessions and text chat can share one thread.
+
+## Related
+
+- [`@mastra/livekit` reference](https://mastra.ai/reference/voice/livekit)
+- [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech)
+- [Agent Memory](https://mastra.ai/docs/memory/overview)
+- [LiveKit Agents docs](https://docs.livekit.io/agents/)

package/.docs/reference/client-js/agents.md

@@ -494,6 +494,94 @@ if (output.finishReason === 'suspended') {
 }
 ```
 
+## Agent schedules
+
+Use the client SDK schedule methods to manage persisted agent schedules over the `/api/schedules` routes. For concepts and server-side examples, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules) and the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
+
+### `createSchedule()`
+
+Create an agent schedule by passing `agentId`.
+
+```typescript
+const schedule = await mastraClient.createSchedule({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Give me a status update.',
+})
+```
+
+### `listSchedules()`
+
+List agent schedules. Filter by fields such as `agentId`, `threadId`, `resourceId`, `name`, or `status`.
+
+```typescript
+const schedules = await mastraClient.listSchedules({
+  agentId: 'pinger',
+  status: 'active',
+})
+```
+
+### `getSchedule()`
+
+Fetch a single agent schedule by ID.
+
+```typescript
+const schedule = await mastraClient.getSchedule('agent_pinger')
+```
+
+### `updateSchedule()`
+
+Update an agent schedule. Agent schedules can update fields such as `cron`, `timezone`, `prompt`, `name`, signal delivery options, metadata, and `status`.
+
+```typescript
+const updated = await mastraClient.updateSchedule('agent_pinger', {
+  cron: '*/30 * * * *',
+  prompt: 'Give me a status update every 30 minutes.',
+})
+```
+
+### `deleteSchedule()`
+
+Delete an agent schedule.
+
+```typescript
+await mastraClient.deleteSchedule('agent_pinger')
+```
+
+### `runSchedule()`
+
+Fire an agent schedule once immediately without changing its cron cadence.
+
+```typescript
+const run = await mastraClient.runSchedule('agent_pinger')
+```
+
+### `pauseSchedule()`
+
+Pause an agent schedule so the scheduler stops firing it. Returns the updated schedule.
+
+```typescript
+await mastraClient.pauseSchedule('agent_pinger')
+```
+
+### `resumeSchedule()`
+
+Resume a paused agent schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule.
+
+```typescript
+await mastraClient.resumeSchedule('agent_pinger')
+```
+
+### `listScheduleTriggers()`
+
+List the trigger history for an agent schedule, including the joined run summary for each fire.
+
+```typescript
+const { triggers } = await mastraClient.listScheduleTriggers('agent_pinger', {
+  limit: 50,
+})
+```
+
 ## Client tools
 
 Client-side tools allow you to execute custom functions on the client side when the agent requests them.

package/.docs/reference/client-js/workflows.md

@@ -214,11 +214,23 @@ A workflow run result yields the following:
 
 ## Schedules
 
-Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing them at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
+Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing workflow schedules at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
+
+### `createSchedule()`
+
+Create a workflow schedule by passing `workflowId`.
+
+```typescript
+const schedule = await mastraClient.createSchedule({
+  workflowId: 'daily-report',
+  cron: '0 9 * * *',
+  inputData: { reportType: 'summary' },
+})
+```
 
 ### `listSchedules()`
 
-List all schedules, optionally filtered by workflow id or status.
+List workflow schedules, optionally filtered by workflow ID or status.
 
 ```typescript
 const schedules = await mastraClient.listSchedules({
@@ -229,15 +241,42 @@ const schedules = await mastraClient.listSchedules({
 
 ### `getSchedule()`
 
-Fetch a single schedule by id.
+Fetch a single workflow schedule by ID.
 
 ```typescript
 const schedule = await mastraClient.getSchedule('daily-report')
 ```
 
+### `updateSchedule()`
+
+Update a workflow schedule.
+
+```typescript
+const updated = await mastraClient.updateSchedule('daily-report', {
+  cron: '0 10 * * *',
+  inputData: { reportType: 'summary' },
+})
+```
+
+### `deleteSchedule()`
+
+Delete a workflow schedule.
+
+```typescript
+await mastraClient.deleteSchedule('daily-report')
+```
+
+### `runSchedule()`
+
+Fire a workflow schedule once immediately without changing its cron cadence.
+
+```typescript
+const run = await mastraClient.runSchedule('daily-report')
+```
+
 ### `pauseSchedule()`
 
-Pause a schedule so the scheduler stops firing it. Returns the updated schedule. Idempotent.
+Pause a schedule so the scheduler stops firing it. Returns the updated schedule.
 
 ```typescript
 await mastraClient.pauseSchedule('daily-report')
@@ -245,7 +284,7 @@ await mastraClient.pauseSchedule('daily-report')
 
 ### `resumeSchedule()`
 
-Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule. Idempotent.
+Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule.
 
 ```typescript
 await mastraClient.resumeSchedule('daily-report')
@@ -253,7 +292,7 @@ await mastraClient.resumeSchedule('daily-report')
 
 ### `listScheduleTriggers()`
 
-List the trigger history for a schedule, including the joined run summary for each fire.
+List the trigger history for a workflow schedule, including the joined run summary for each fire.
 
 ```typescript
 const { triggers } = await mastraClient.listScheduleTriggers('daily-report', {

package/.docs/reference/index.md

@@ -230,6 +230,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [rerank()](https://mastra.ai/reference/rag/rerank)
 - [rerankWithScorer()](https://mastra.ai/reference/rag/rerankWithScorer)
 - [.chunk()](https://mastra.ai/reference/rag/chunk)
+- [Overview](https://mastra.ai/reference/schedules/overview)
 - [createRoute()](https://mastra.ai/reference/server/create-route)
 - [Express Adapter](https://mastra.ai/reference/server/express-adapter)
 - [Fastify Adapter](https://mastra.ai/reference/server/fastify-adapter)
@@ -309,6 +310,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Google Gemini Live](https://mastra.ai/reference/voice/google-gemini-live)
 - [Inworld](https://mastra.ai/reference/voice/inworld)
 - [Inworld Realtime](https://mastra.ai/reference/voice/inworld-realtime)
+- [LiveKit](https://mastra.ai/reference/voice/livekit)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
 - [Murf](https://mastra.ai/reference/voice/murf)
 - [OpenAI](https://mastra.ai/reference/voice/openai)

package/.docs/reference/schedules/overview.md

@@ -0,0 +1,199 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# `mastra.schedules`
+
+**Added in:** `@mastra/core@1.50.0`
+
+`mastra.schedules` is the CRUD service for persisted cron schedules. Use it to create, list, update, pause, resume, manually run, and delete schedules for agents or workflows.
+
+For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules).
+
+## Usage example
+
+Create an agent schedule:
+
+```typescript
+const schedule = await mastra.schedules.create({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Give me a status update.',
+})
+```
+
+Create a workflow schedule:
+
+```typescript
+const schedule = await mastra.schedules.create({
+  workflowId: 'daily-report',
+  cron: '0 9 * * *',
+  inputData: { reportType: 'summary' },
+})
+```
+
+Schedules require a storage adapter that implements the schedules domain. Supported adapters include `@mastra/libsql`, `@mastra/pg`, `@mastra/mysql`, `@mastra/mongodb`, `@mastra/convex`, and `@mastra/spanner`.
+
+## Methods
+
+### Create schedules
+
+#### `create(input)`
+
+Creates an agent or workflow schedule. Pass `agentId` to create an agent schedule, or `workflowId` to create a workflow schedule.
+
+```typescript
+const schedule = await mastra.schedules.create({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Give me a status update.',
+})
+```
+
+##### Agent schedule input
+
+**id** (`string`): Optional stable schedule ID. The value is normalized to agent\_\<slug>. When omitted, Mastra generates an agent\_\<uuid> ID.
+
+**agentId** (`string`): ID of the agent to run on each schedule fire.
+
+**cron** (`string`): Cron expression for the schedule. Accepts 5-, 6-, or 7-part cron expressions and Croner nicknames.
+
+**prompt** (`string`): Prompt sent to the agent on each schedule fire.
+
+**name** (`string`): Free-form label for distinguishing multiple schedules on the same agent or thread.
+
+**timezone** (`string`): IANA timezone used to resolve cron fire times, for example America/New\_York.
+
+**threadId** (`string`): Thread that receives the scheduled signal. When omitted, each fire runs threadless with agent.generate().
+
+**resourceId** (`string`): Resource ID for threaded schedules. Required when threadId is set.
+
+**signalType** (`AgentSignalType`): Signal type for threaded schedule fires. Defaults to notification.
+
+**tagName** (`string`): XML tag name used to render the scheduled signal. Defaults to schedule.
+
+**attributes** (`AgentSignalAttributes`): Attributes rendered on the scheduled signal XML tag.
+
+**providerOptions** (`Record<string, unknown>`): JSON-safe provider options merged into the schedule signal payload on every fire.
+
+**ifActive** (`ScheduleIfActive`): Behavior when the target thread is actively streaming. Requires threadId.
+
+**ifIdle** (`ScheduleIfIdle`): Behavior when the target thread is idle. Requires threadId.
+
+**metadata** (`Record<string, unknown>`): Arbitrary metadata stored with the schedule row.
+
+**status** (`'active' | 'paused'`): Initial lifecycle status. Defaults to active. (Default: `'active'`)
+
+##### Workflow schedule input
+
+**id** (`string`): Optional stable schedule ID. The value is normalized to schedule\_\<slug>. When omitted, Mastra generates a schedule\_\<uuid> ID.
+
+**workflowId** (`string`): ID of the workflow to start on each schedule fire.
+
+**cron** (`string`): Cron expression for the schedule. Accepts 5-, 6-, or 7-part cron expressions and Croner nicknames.
+
+**timezone** (`string`): IANA timezone used to resolve cron fire times.
+
+**inputData** (`unknown`): Input data passed to the workflow run.
+
+**initialState** (`unknown`): Initial workflow state for the scheduled run.
+
+**requestContext** (`Record<string, unknown>`): Request context passed to the workflow run.
+
+**metadata** (`Record<string, unknown>`): Arbitrary metadata stored with the schedule row.
+
+**status** (`'active' | 'paused'`): Initial lifecycle status. Defaults to active. (Default: `'active'`)
+
+### Read schedules
+
+#### `get(id)`
+
+Gets a schedule by ID. Bare agent schedule IDs are also resolved to the normalized `agent_<slug>` form.
+
+```typescript
+const schedule = await mastra.schedules.get('pinger')
+```
+
+#### `list(filter?)`
+
+Lists schedules. Without a filter, it returns agent and workflow schedules.
+
+```typescript
+const schedules = await mastra.schedules.list({
+  agentId: 'pinger',
+  status: 'active',
+})
+```
+
+**filter** (`ListSchedulesFilter`): Optional filters for the list operation.
+
+**filter.agentId** (`string`): Return only agent schedules for this agent.
+
+**filter.workflowId** (`string`): Return only workflow schedules for this workflow.
+
+**filter.threadId** (`string`): Return only agent schedules for this thread.
+
+**filter.resourceId** (`string`): Return only agent schedules for this resource.
+
+**filter.name** (`string`): Return only agent schedules with this label.
+
+**filter.status** (`'active' | 'paused'`): Return only schedules with this status.
+
+### Update schedules
+
+#### `update(id, patch)`
+
+Updates a schedule. Changing `cron` or `timezone` recomputes the next fire time. Updating `status` from `paused` to `active` also recomputes the next fire time.
+
+```typescript
+const updated = await mastra.schedules.update('pinger', {
+  cron: '*/30 * * * *',
+  prompt: 'Give me a status update every 30 minutes.',
+})
+```
+
+Agent schedule patches can update `cron`, `timezone`, `prompt`, `name`, `signalType`, `tagName`, `attributes`, `providerOptions`, `ifActive`, `ifIdle`, `metadata`, and `status`. `threadId` and `resourceId` aren't patchable; create a new schedule when the thread target needs to change.
+
+Workflow schedule patches can update `cron`, `timezone`, `inputData`, `initialState`, `requestContext`, `metadata`, and `status`. Agent-only patch fields such as `prompt`, `signalType`, and `ifIdle` throw on workflow schedules.
+
+### Lifecycle
+
+#### `pause(id)`
+
+Pauses a schedule. Pausing is durable and idempotent.
+
+```typescript
+const paused = await mastra.schedules.pause('pinger')
+```
+
+#### `resume(id)`
+
+Resumes a paused schedule and recomputes the next fire time from the current time.
+
+```typescript
+const active = await mastra.schedules.resume('pinger')
+```
+
+#### `run(id)`
+
+Fires a schedule once immediately without changing its cron cadence.
+
+```typescript
+const run = await mastra.schedules.run('pinger')
+```
+
+For agent schedules, `claimId` uses `manual_<scheduleId>_<timestamp>`. For workflow schedules, `claimId` uses `sched_<scheduleId>_<timestamp>` and is reused as the workflow run ID.
+
+#### `delete(id)`
+
+Deletes a schedule. Deleting a missing schedule is a no-op.
+
+```typescript
+await mastra.schedules.delete('pinger')
+```
+
+## Schedule behavior
+
+- Agent schedule IDs use the `agent_` prefix. Workflow schedule IDs created through `mastra.schedules.create()` use the `schedule_` prefix.
+- Threaded agent schedules require `resourceId` when `threadId` is set.
+- `signalType`, `ifActive`, `ifIdle`, and `resourceId` require `threadId`.
+- Workflow schedules don't accept agent-only patch fields such as `prompt`, `signalType`, or `ifIdle`.
+- `run()` publishes a manual fire immediately and doesn't change the stored cron cadence.

package/.docs/reference/voice/livekit.md

@@ -0,0 +1,218 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# LiveKit
+
+The `@mastra/livekit` package connects Mastra agents to the LiveKit Agents framework. LiveKit runs the audio pipeline (voice activity detection, speech-to-text, turn detection, text-to-speech, barge-in) and the package bridges reply generation to a Mastra agent's `stream()` call.
+
+See [Using LiveKit with Mastra](https://mastra.ai/docs/voice/livekit) for setup and concepts.
+
+The package has two entry points, one per process:
+
+- `@mastra/livekit`: server-side APIs — [`liveKitConnectionRoute()`](#livekitconnectionroute), [`dispatchVoiceSession()`](#dispatchvoicesession), [`pipeAgentReplyToWriter()`](#pipeagentreplytowriter), and [`serializeSessionMetadata()`](#livekitsessionmetadata). Import these from Mastra server code. This entry never loads the LiveKit agents runtime.
+- `@mastra/livekit/worker`: the worker runtime — [`createLiveKitWorker()`](#createlivekitworker), [`runLiveKitWorker()`](#runlivekitworker), and [`chatContextToMessages()`](#chatcontexttomessages). Import it only from the worker entry file.
+
+## `createLiveKitWorker()`
+
+Builds a LiveKit agent definition that answers voice sessions with Mastra agents. Use it as the default export of your worker entry file.
+
+```typescript
+import { fileURLToPath } from 'node:url'
+import { createLiveKitWorker, runLiveKitWorker } from '@mastra/livekit/worker'
+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' })
+}
+```
+
+### Options
+
+**mastra** (`Mastra`): The Mastra instance whose agents handle voice sessions.
+
+**agent** (`string | (args) => string | Agent | Promise<string | Agent>`): Which Mastra agent answers each session: a fixed agent key or id, or a resolver called per session with the dispatch metadata and job context. Defaults to the agentId from the dispatch metadata.
+
+**workflow** (`string | Workflow | (args) => string | Promise<string>`): Generate each turn's reply with a Mastra workflow instead of an agent: a Workflow instance, a fixed workflow key or id, or a resolver that returns a workflow id per session. The workflow runs once to completion per turn (no suspend or resume). Mutually exclusive with agent; requires workflowInput.
+
+**workflowInput** (`(args: VoiceTurnContext & { metadata }) => unknown | Promise<unknown>`): Maps a turn into the workflow inputData. Required when workflow is set. A stateless mapping that passes the full transcript each turn avoids carrying conversation state in the workflow.
+
+**replyStep** (`string`): Only stream text from this workflow step id. Defaults to every step that writes to its writer.
+
+**resultText** (`(result: unknown) => string | undefined`): Fallback when the workflow streams no text via writer: derive the spoken reply from the final run result.
+
+**generate** (`VoiceReplyGenerator`): Lowest-level escape hatch: supply any reply generator directly (a custom workflow, remote bridge, and so on).
+
+**stt** (`STT | string`): Speech-to-text: a LiveKit plugin instance or an inference model string such as 'deepgram/nova-3'.
+
+**tts** (`TTS | string`): Text-to-speech: a LiveKit plugin instance or an inference model string such as 'cartesia/sonic-3'.
+
+**vad** (`VAD | 'silero' | false`): Voice activity detection. 'silero' loads the Silero VAD from @livekit/agents-plugin-silero during prewarm. Pass an instance to bring your own, or false to disable. (Default: `'silero'`)
+
+**turnDetection** (`'multilingual' | 'english' | TurnDetectionMode`): End-of-turn detection. 'multilingual' and 'english' load LiveKit's semantic turn detector from @livekit/agents-plugin-livekit. Other values such as 'vad', 'stt', or 'manual' pass through.
+
+**turnHandling** (`Partial<TurnHandlingOptions>`): Turn handling tuning: endpointing delays, interruption sensitivity, preemptive generation. The worker disables preemptiveGeneration unless set here — each preemptive attempt re-runs the Mastra agent and persists a duplicate user message.
+
+**sessionOptions** (`Partial<AgentSessionOptions>`): Extra LiveKit AgentSession options merged over what this helper builds.
+
+**memory** (`false | ((args) => { thread, resource } | false)`): Memory mapping. Defaults to { thread: metadata.threadId ?? room name, resource: metadata.resourceId ?? thread } when the resolved agent has memory configured. Pass false to disable, or a function to customize.
+
+**toolFeedback** (`(toolCall) => string | undefined`): Called when the Mastra agent starts a tool call mid-reply. Return a short phrase to speak while the tool runs.
+
+**greeting** (`string`): Static greeting spoken when the session starts.
+
+**persistGreeting** (`boolean`): Save the spoken greeting to the memory thread as an assistant message, making the saved thread a faithful call transcript. Only applies when a greeting is set and memory is enabled. (Default: `true`)
+
+**observability** (`boolean`): Trace each call when the Mastra instance has observability configured. Opens a voice call span per session: every turn's agent run nests under it, LiveKit's STT, TTS, end-of-utterance, VAD, and LLM latency metrics become child spans, and the span closes with a per-model usage roll-up. Pass false to disable. (Default: `true`)
+
+**inputOptions** (`Partial<RoomInputOptions>`): LiveKit room input options passed to session.start().
+
+**outputOptions** (`Partial<RoomOutputOptions>`): LiveKit room output options passed to session.start().
+
+**onSessionStart** (`(args: { session, ctx, agent, metadata }) => void | Promise<void>`): Called after the session starts. Attach event listeners or trigger replies here.
+
+## `runLiveKitWorker()`
+
+Starts the LiveKit worker CLI (`dev`, `start`, and `connect` subcommands) for a worker entry file. Call it from the file that default-exports the worker definition, guarded so it only runs when executed directly (the worker spawns a child process per session that re-imports the same file). Using this helper instead of `cli.runApp` from `@livekit/agents` guarantees the worker runtime and the bridge share one copy of the LiveKit SDK.
+
+### Options
+
+**entry** (`string | URL`): The worker entry module whose default export is the agent definition. Pass import.meta.url.
+
+**agentName** (`string`): LiveKit agent name for explicit dispatch. (Default: `'mastra-voice'`)
+
+**serverOptions** (`Partial<ServerOptions>`): Extra LiveKit ServerOptions merged over what this helper builds.
+
+## `pipeAgentReplyToWriter()`
+
+Streams a Mastra agent's reply into a workflow step's `writer` on the workflow reply path. It forwards the agent's text deltas, so text-to-speech starts before the full reply is ready, and its tool-call chunks, so `toolFeedback` fires and `onTurnComplete` sees the tool list. Piping only `stream.textStream` silently drops tool calls. Pass the step's `abortSignal` to `agent.stream()` so barge-in stops generation promptly.
+
+```typescript
+import { pipeAgentReplyToWriter } from '@mastra/livekit'
+
+const generateResponse = createStep({
+  id: 'generateResponse',
+  // input and output schemas omitted
+  execute: async ({ inputData, mastra, writer, abortSignal }) => {
+    const stream = await mastra.getAgent('support').stream(inputData.turn, { abortSignal })
+    const reply = await pipeAgentReplyToWriter(stream, writer)
+    return { reply }
+  },
+})
+```
+
+Returns: `Promise<string>`, the accumulated reply text.
+
+### Parameters
+
+**agentStream** (`AgentReplyStreamLike`): The stream returned by agent.stream() — anything exposing a fullStream async iterable.
+
+**writer** (`WritableStream<unknown>`): The workflow step's writer.
+
+## `chatContextToMessages()`
+
+Converts a LiveKit chat context into plain messages accepted by `agent.stream()`, excluding instructions and function calls. Use it in `workflowInput` to pass the full transcript into a stateless workflow.
+
+```typescript
+import { createLiveKitWorker, chatContextToMessages } from '@mastra/livekit/worker'
+
+export default createLiveKitWorker({
+  mastra,
+  workflow: 'phoneConversation',
+  workflowInput: ({ chatCtx }) => ({ history: chatContextToMessages(chatCtx) }),
+})
+```
+
+Returns: `VoiceTurnMessage[]`, where each entry is `{ role: 'system' | 'user' | 'assistant'; content: string }`.
+
+## `liveKitConnectionRoute()`
+
+Returns an [API route](https://mastra.ai/docs/server/custom-api-routes) that mints a LiveKit access token with the voice agent dispatched into the room. Frontends call it to join a session.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { liveKitConnectionRoute } from '@mastra/livekit'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })],
+  },
+})
+```
+
+The route accepts a JSON body with optional `agentId`, `threadId`, and `resourceId` fields and responds with `{ serverUrl, roomName, participantName, participantToken }`. The `threadId` defaults to the generated room name.
+
+### Options
+
+**path** (`string`): Route path. (Default: `'/voice/livekit/connection-details'`)
+
+**serverUrl** (`string`): LiveKit server URL. (Default: `process.env.LIVEKIT_URL`)
+
+**apiKey** (`string`): LiveKit API key. (Default: `process.env.LIVEKIT_API_KEY`)
+
+**apiSecret** (`string`): LiveKit API secret. (Default: `process.env.LIVEKIT_API_SECRET`)
+
+**agentName** (`string`): LiveKit agent name for explicit dispatch. Must match the worker's agentName. (Default: `'mastra-voice'`)
+
+**ttl** (`string | number`): Token time-to-live. (Default: `'15m'`)
+
+**requiresAuth** (`boolean`): Whether the route requires authentication. (Default: `true`)
+
+**roomName** (`string | (args) => string`): Room name or a function that derives one from the request.
+
+**participantIdentity** (`string | (args) => string`): Participant identity or a function that derives one from the request.
+
+**metadata** (`(args) => LiveKitSessionMetadata | Promise<LiveKitSessionMetadata>`): Builds the session metadata delivered to the worker. Defaults to passing through agentId, threadId, and resourceId from the request body.
+
+## `dispatchVoiceSession()`
+
+Dispatches a Mastra voice agent into a LiveKit room programmatically — for server-initiated sessions such as outbound calls.
+
+```typescript
+import { dispatchVoiceSession } from '@mastra/livekit'
+
+await dispatchVoiceSession({
+  roomName: 'support-call-42',
+  agentName: 'mastra-voice',
+  metadata: { agentId: 'support', threadId: 'thread-42' },
+})
+```
+
+### Options
+
+**roomName** (`string`): Room to dispatch the agent into. Created on demand.
+
+**agentName** (`string`): Must match the worker's agentName. (Default: `'mastra-voice'`)
+
+**metadata** (`LiveKitSessionMetadata`): Session metadata: agentId, threadId, resourceId, requestContext.
+
+**serverUrl** (`string`): LiveKit server URL. (Default: `process.env.LIVEKIT_URL`)
+
+**apiKey** (`string`): LiveKit API key. (Default: `process.env.LIVEKIT_API_KEY`)
+
+**apiSecret** (`string`): LiveKit API secret. (Default: `process.env.LIVEKIT_API_SECRET`)
+
+## `LiveKitSessionMetadata`
+
+The metadata passed from the Mastra server to the worker through LiveKit job dispatch.
+
+**agentId** (`string`): Mastra agent to run, by registered key or agent id.
+
+**threadId** (`string`): Memory thread id. Defaults to the LiveKit room name.
+
+**resourceId** (`string`): Memory resource id, typically the end user id.
+
+**requestContext** (`Record<string, unknown>`): Plain-object entries restored into a RequestContext for agent execution.
+
+The metadata travels as a JSON string. `liveKitConnectionRoute()` and `dispatchVoiceSession()` serialize it for you; use `serializeSessionMetadata(metadata)` when dispatching through your own code, or write the JSON directly in LiveKit-side configuration such as a SIP dispatch rule. Entries in `requestContext` reach the agent's dynamic instructions, tools, and input processors on every turn of the call.
+
+## Related
+
+- [Using LiveKit with Mastra](https://mastra.ai/docs/voice/livekit)
+- [LiveKit Agents docs](https://docs.livekit.io/agents/)

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.5-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [[`a0085fa`](https://github.com/mastra-ai/mastra/commit/a0085fa0934e52c37c8c8b3d75a6bb5cd199af36)]:
+  - @mastra/core@1.50.0-alpha.5
+
 ## 1.2.5-alpha.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.5-alpha.7",
+  "version": "1.2.5-alpha.8",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.13.1-alpha.0",
-    "@mastra/core": "1.50.0-alpha.4"
+    "@mastra/core": "1.50.0-alpha.5",
+    "@mastra/mcp": "^1.13.1-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,8 +46,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
     "@internal/lint": "0.0.111",
-    "@internal/types-builder": "0.0.86",
-    "@mastra/core": "1.50.0-alpha.4"
+    "@mastra/core": "1.50.0-alpha.5",
+    "@internal/types-builder": "0.0.86"
   },
   "homepage": "https://mastra.ai",
   "repository": {