This PR contains the following updates:
| Update | Change |
|---|---|
| lockFileMaintenance | All locks refreshed |
---
> [!WARNING]
> Some dependencies could not be looked up. Check the [Dependency
Dashboard](../issues/9505) for more information.
🔧 This Pull Request updates lock files to use the latest dependency
versions.
---
### Configuration
📅 **Schedule**: (UTC)
- Branch creation
- "before 6am on wednesday"
- Automerge
- At any time (no schedule defined)
🚦 **Automerge**: Enabled.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.
👻 **Immortal**: This PR will be recreated if closed unmerged. Get
[config
help](https://redirect.github.com/renovatebot/renovate/discussions) if
that's undesired.
---
- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box
---
This PR has been generated by [Mend Renovate
CLI](https://redirect.github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiI0NC4xOTAuMCIsInVwZGF0ZWRJblZlciI6IjQ0LjE5MC4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJhdXRvbWF0aW9uIl19-->
---------
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
Enables `no-else-return: error` in the root Oxlint config and removes
186 redundant `else` branches across 111 source/test files. Existing
rule defaults are retained.
Reviewed every code diff for behavior preservation. An independent
TypeScript AST comparison confirms that changes are limited to removing
`else` after returning branches, with the same expressions, statement
order, return values, and `try`/`catch`/`finally` boundaries. All
181,158 identifier occurrences retain their bindings. The recorder
replay path keeps an explicit block: flattening it would shadow the
earlier request `body` with the response `body` and introduce a
temporal-dead-zone error.
Extends the existing monorepo optimized-dependency test to assert that a
raw TypeScript workspace package, including its enum and transitive
dependency, still executes in the production bundle.
Validation: the root rule-only scan passes on 15,273 files with zero
diagnostics; formatting and `git diff --check` pass. Schema
compatibility tests: 1,060 passed, 9 skipped. Recorder runtime tests: 21
passed. The core selection initially passed 3,513 tests; rerunning the
suites requiring local server/cache access passed 185 tests, with one
remaining cache-file assertion also reproduced on unchanged `main`.
Remaining validation limits: four asset-download cases cannot reach
`placehold.co`; the changed-file lint run reports six import-order
errors reproduced on unchanged files from `main`. Deployer unit tests
and the monorepo test could not run because this checkout lacks required
package dependencies (`fs-extra`/workspace links and `get-port`,
respectively). These limits are left visible for CI. No changeset is
included because this is a behavior-preserving lint cleanup.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR makes the code easier to read by removing `else` branches that
are not needed after a return. It also enables a rule that catches those
branches and adds a test for loading a raw TypeScript workspace package
in a production bundle.
## Summary
- Enables Oxlint’s `no-else-return` rule at error severity and removes
186 redundant `else` branches across 111 files.
- Extends the monorepo optimized-dependencies test to check a raw
TypeScript workspace package, its enum, and a transitive dependency.
- Updates the deployer’s transpile-package path pattern.
- In workflow event processing, a truthy branch index with no matching
child now falls through to publish a skipped-step end event. Previously,
this case published no event.
- Keeps the recorder replay block explicit to avoid request/response
`body` shadowing and a temporal-dead-zone error.
## Validation
Reported checks passed: the rule-only scan across 15,273 files,
formatting, `git diff --check`, schema compatibility tests (1,060
passed, 9 skipped), recorder runtime tests (21 passed), and an initial
core test selection (3,513 passed).
Some test limits remain. Four asset-download cases could not reach
`placehold.co`. Changed-file lint reported six import-order errors that
also occur on unchanged files from `main`. Deployer unit tests and the
monorepo test could not run because dependencies were unavailable. On
rerun, suites requiring local server/cache access had 185 passes; one
cache-file assertion also reproduced on unchanged `main`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Prepare the LiveKit 0.5.0 release with opt-in call recording and Studio
playback. `dispatchVoiceSession()` and `liveKitConnectionRoute()` can
create a fresh room with LiveKit auto egress before dispatching the
agent. The recording route resolves an authorized trace to a short-lived
playback URL, and Studio exposes it through **Review Audio**.
```ts
await dispatchVoiceSession({
roomName: `call-${crypto.randomUUID()}`,
metadata: { agentId: 'support' },
recording, // Server-side LiveKit output settings.
});
```
Recording review requires an explicit `authorize({ traceId, context })`
callback. Only `true` permits trace lookup and playback URL resolution;
missing policies fail at registration. Recording room conflicts return
HTTP 409. The example and documentation cover S3 configuration, scoped
permissions, consent, and recording lifecycle implications. Browser
recording creation and playback in the unauthenticated example require
an explicit local-demo opt-in and are disabled in production.
The browser-safe `@mastra/livekit/client` entry point provides
`getLiveKitRecording(client, traceId)`, preserving the client's
authentication and request configuration. Studio uses the supported
React hook subpaths from main.
The integration also adds common per-turn metrics, speech-flush
boundaries, and an `onSpeechComplete` hook. `onTurnComplete` retains its
generation-only behavior. Custom reply-generator consumers must handle
flush boundaries, and `MastraLLM` integrations should use
`mastraLLMNode`. Playback completion describes server delivery, not
proof that the listener heard the audio.
The VAD opt-out is fixed. LiveKit Agents 1.7.1 is the supported minimum
and migration target, with matching plugin peer ranges and upgrade
instructions. The planned stable release remains **0.5.0**.
### Validation
- All 280 LiveKit tests across 22 files passed.
- All 18 Studio voice and recording-review tests passed.
- A local synthetic probe passed 96 example route-policy cases covering
room creation, dispatch, unrecorded tokens, storage access, and denied
playback.
- LiveKit, React SDK, shared Studio UI, and production Studio builds
passed.
- LiveKit, Studio, and voice-agent example typechecks passed; focused
lint and documentation checks passed.
- Production bundle inspection confirmed that the recording client adds
no LiveKit server or worker modules to the browser bundle.
- Changeset planning retains the 0.5.0 release target.
The core working-memory configuration fix and its regression tests are
in #26090 for separate review.
**─────── TLDR ───────**
> Studio's voice-call button is disabled with a setup hint when the
server has no LiveKit connection route, instead of failing after the
click.
Clicking the phone icon in an agent chat posted to a route that only
exists once `liveKitConnectionRoute()` is in `server.apiRoutes`; without
it the call died with a toast after the click. The server now reports
whether that default route is mounted, and Studio disables the idle
control on a `false`.
### Behavior changed
agent chat, server without the LiveKit route
├─ **was** — phone button live; click fails with a toast
after the request
└─ **now** — button dimmed but focusable, tooltip says to
configure `@mastra/livekit`, no request sent
agent chat, server older than this change (no flag in the response)
└─ **unchanged** — button live, the call starts as before
route mounted under a custom `path`
├─ **was** — click fails, Studio posts to the default path
└─ **now** — button disabled with the same setup tooltip
an active call
└─ **unchanged** — the end-call control is never gated


### Shape changed
| | | |
|---|---|---|
| **+** | `useIsLiveKitAvailable` | mirrors `useIsCmsAvailable`, one
consumer |
| **+** | `defaultSystemPackages` | default MSW answer for
`/api/system/packages`, suite-wide |
the contract the reviewer approves
`GET /api/system/packages` →
`liveKitConnectionRouteEnabled: boolean`, required ·
`VoiceCallControls.isLiveKitAvailable`
The field is required, so any hand-written `GetSystemPackagesResponse`
fixture must add it; every one in this repo did, the platform repo has
none.
### Decisions
- **detect the exact default `POST` path, not the installed package** —
it is the route Studio calls, so a custom path or method reports
`false`, which is what the click would have done; a marker on the route
object is one field away if you want custom paths to count
- **fail open on old servers and on a failed packages request** — a
missing flag must not hide a working button; `!== false` is the whole
rule
- **`aria-disabled`, not `disabled`** — a disabled button cannot take
focus, so the setup tooltip would be unreachable by keyboard; `start()`
ignores the click instead
---
> ██████████████████ **tests** `+176 −10` — 76% of the additions
> ████ **source** `+39 −5`
> ██ **changeset** `+15`
> █ **generated** `+1`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
Studio now checks if the server has LiveKit voice-call support before
starting a call. If support is missing, Studio disables the call button
and explains how to configure `@mastra/livekit`.
## Changes
- Added `liveKitConnectionRouteEnabled` to `GET /api/system/packages`.
- Detects only the default `POST /voice/livekit/connection-details`
route.
- Added `useIsLiveKitAvailable` to gate new voice calls.
- Added disabled styling, accessibility state, and setup tooltip to the
idle call button.
- Kept legacy servers and failed package requests permissive.
- Added shared MSW fixtures and coverage for unavailable and legacy
server responses.
- Added changesets for `@internal/playground`, `@mastra/client-js`, and
`@mastra/server`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
LiveKit's `preemptiveGeneration` starts the Mastra agent's reply on
interim transcripts and discards runs whose transcript changes. The
`@mastra/livekit` plugin can't distinguish a speculative run from a real
turn, so with `memory` set every run persisted partial user and
assistant messages to the thread — the only "fix" was turning preemptive
generation off and losing its latency win (~225 ms end-of-turn-to-TTS in
the reporter's measurements).
`@mastra/core` already supports a per-call `memory.options.readOnly`
that reads thread history without persisting, but
`MastraVoiceAgentMemory` was a closed `{ thread, resource }` shape and
the remote transport rebuilt that shape explicitly, so there was no
supported way to reach it.
This PR:
- Adds `options?: AgentMemoryOption['options']` to
`MastraVoiceAgentMemory` (in-process path already spreads the object;
now typed).
- Forwards `options` in the remote transport's request body as
`memory.options` (server schema and handler already accept it).
- Corrects the worker/plugin comments — discarded speculations persist
partial **assistant** replies too, not just user messages.
- Documents a "Preemptive generation with memory" recipe: `options: {
readOnly: true }` plus persisting committed turns from LiveKit's
`ConversationItemAdded` event (idempotent via LiveKit message ids).
- Changeset (`@mastra/livekit` patch).
Not in scope: auto-detecting speculative runs inside the plugin —
LiveKit gives `chat()`/`llmNode` no marker, so this remains an opt-in
caller pattern.
Closes#22873
## Test plan
- [x] New unit tests: `bridge.test.ts` (options reach `agent.stream`),
`llm-plugin.test.ts` (options reach the generator ctx unchanged),
`remote.test.ts` (options forwarded in the HTTP body; existing
body-shape assertions unchanged).
- [x] `pnpm vitest run` in `integrations/livekit` — 196 passed.
- [x] `tsc --noEmit`, `pnpm lint`, `pnpm build:lib` clean.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
LiveKit can now run speculative voice turns without saving partial
messages. Callers can pass `memory.options.readOnly: true` to read
conversation history without changing it, then save committed turns
separately and safely retry those saves.
## What changed
- Added per-call `memory.options` support to `MastraVoiceAgentMemory`.
- Forwarded memory options through local and remote reply generators.
- Updated documentation and comments to cover partial user and assistant
message persistence.
- Added guidance for caller-managed, idempotent persistence of committed
turns using stable LiveKit message IDs.
- Added tests for local and remote option forwarding.
- Added a patch changeset for `@mastra/livekit`.
Automatic detection of speculative runs remains out of scope.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: mvp-joe <84737340+mvp-joe@users.noreply.github.com>
Co-authored-by: Mastra Code (anthropic/claude-fable-5-1) <noreply@mastra.ai>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
## @mastra/client-js@1.42.5-alpha.5
### Patch Changes
- Added the optional `hasBrowser` field to the serialized agent response
type. ([#22789](https://github.com/mastra-ai/mastra/pull/22789))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/react@1.4.10-alpha.6
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148),
[`b114e78`](b114e787e8)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/client-js@1.42.5-alpha.5
## @mastra/deployer-cloud@1.64.0-alpha.5
### Patch Changes
- Updated dependencies
[[`b114e78`](b114e787e8),
[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/deployer@1.64.0-alpha.5
- @mastra/core@1.64.0-alpha.5
## @mastra/longmemeval@1.1.23-alpha.6
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/libsql@1.22.3-alpha.1
## @mastra/livekit@0.3.1-alpha.1
### Patch Changes
- `@mastra/livekit/worker` now exports `MastraVoiceAgent` and
`createMastraVoiceAgent` (with the `MastraVoiceAgentOptions` and
`MastraStreamOptions` types). This is the `voice.Agent` subclass
`createLiveKitWorker()` builds per session, so you can construct it
yourself when you own the `voice.AgentSession` — for example to test a
Mastra-backed agent with `@livekit/agents`' `voice.testing` harness
without speech-to-text, text-to-speech, or a running worker.
([#22820](https://github.com/mastra-ai/mastra/pull/22820))
```ts
import { initializeLogger, voice } from '@livekit/agents';
import { createMastraVoiceAgent } from '@mastra/livekit/worker';
initializeLogger({ level: 'silent', pretty: false }); // required
outside a LiveKit worker
const session = new voice.AgentSession();
await session.start({ agent: createMastraVoiceAgent({ agent:
supportAgent, memory: false }) });
const result = session.run({ userInput: 'What are your opening hours?'
});
await result.wait();
result.expect.nextEvent().isMessage({ role: 'assistant' });
```
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/opencode@0.1.23-alpha.6
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/libsql@1.22.3-alpha.1
## @mastra/factory@0.12.0-alpha.9
### Patch Changes
- **Session status**
([#22786](https://github.com/mastra-ai/mastra/pull/22786))
- Fixed session status disagreeing between sidebar rows, board cards,
and the open chat.
- Running, setting up, and waiting-on-you states now read the same after
a reload and in every tab.
- Removed the per-browser "your turn" mark; a card waiting on a person
is marked from the card itself, and a finished session with nothing
waiting shows as idle.
**Chat**
- Fixed the favicon claiming the session awaits input while history is
still loading.
- Allow steering or stopping a running session as soon as it is
connected.
**Done sound**
- Plays once when a run watched in this tab ends.
- A run started from a work item with comments shows its prompt as the
collapsed skill row again, with the item's discussion in its own
collapsible row beside it, instead of one raw message wide enough to
break the page. Only that discussion may follow the skill envelope;
anything else keeps the message raw.
([#22551](https://github.com/mastra-ai/mastra/pull/22551))
The Mastra Code terminal folds the same prompt into its skill row.
- **Session comments panel**
([#22551](https://github.com/mastra-ai/mastra/pull/22551))
The comments panel opens at half the height of the chat and grows with
the conversation up to the full column, instead of opening full height
around an empty feed. It morphs open from the workspace card. The
composer is a flush bar at the bottom edge and takes focus as the panel
opens. A comment that lands while you are watching rises into place.
Editing a comment saves on Enter and keeps Shift+Enter for a new line,
with Cancel and Save inside the bottom right of the field. The edit
field grows with its text up to ten lines, then scrolls, with no resize
handle. The workspace card's corners are concentric with the rows inside
it. Session rows in the sidebar no longer open their hover details on a
touch viewport, where the card could only appear behind the tap that
already navigated away.
**Board cards**
A sent comment lands in the feed as soon as the server stores it, with
no dimmed placeholder. A failed send keeps the draft and shows the
error. Opening a card widens a copy of it over the card, every row
anchored where the card had it, and pulls a tray out from beneath, a
little narrower than the copy, so opening moves nothing you were about
to click. Hovering a card no longer floats its full title over it; the
open copy shows it whole.
The tray holds one timeline in time order: the item's runs, moves and
comments, with the composer at the bottom. The description heads that
stream in a block of its own, an Activity rule between them. The tray
opens at its full height whatever the stream holds, waits for the
description and the comments together, and lands them one after another,
so nothing shifts once it loads.
Cards share a minimum height, with their bottom row pinned to the bottom
edge. That row leads with one small button, the likeliest next click:
the item's run, Retry after a failure, the suggested run while one
waits, Open session while one runs. It lights up only while the card
waits on you, to release a suggested run, retry a failure, or answer a
session that asked. It goes quiet the moment a run is starting, so a lit
button on the board always means your turn. A card in a lane leads with
that lane's own run. The other buttons sit tucked under the first like
pulled tabs, on the card and in its open copy alike. While a session
runs, no rival run is offered beside it. The suggestion itself is a
badge in the status row. The last worker sits at the right of the bottom
row, the name before the picture, and the External badge sits at the
right of its own row above. An expand icon appears beside the card's
menu on hover, in the spot where the open copy puts Collapse. The copy
names its source link with the item's icon and number instead of an
arrow. The card's corners round a little more, concentric with the
buttons in them, and the empty state of a column rounds its corners the
same way.
**Intake and the rest of the board**
An intake candidate opens the same way, its run buttons in the copy and
its description in the tray. Labels stay on one line that scrolls
sideways instead of wrapping. A card near the bottom of the window opens
its tray above the card instead of climbing to fit, and in the last
column the tray slides left by its overflow while the copy stays over
the card. The board dims under the open card, and a click on the dim
closes it without pressing whatever sat underneath.
**On a phone**
The sheet opens straight onto the same timeline and composer, and hugs
its content instead of opening at a fixed height.
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/code-sdk@1.6.0-alpha.7
## create-factory@0.1.15-alpha.6
### Patch Changes
- Updated dependencies
[[`b114e78`](b114e787e8)]:
- mastra@1.27.3-alpha.6
## @mastra/code-sdk@1.6.0-alpha.7
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`285ce1c`](285ce1c139),
[`045c3c7`](045c3c78f2),
[`f01f822`](f01f822cbe),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/mcp@1.17.3-alpha.1
- @mastra/libsql@1.22.3-alpha.1
- @mastra/pg@1.22.3-alpha.1
## mastracode@0.38.0-alpha.6
### Patch Changes
- A run started from a work item with comments shows its prompt as the
collapsed skill row again, with the item's discussion in its own
collapsible row beside it, instead of one raw message wide enough to
break the page. Only that discussion may follow the skill envelope;
anything else keeps the message raw.
([#22551](https://github.com/mastra-ai/mastra/pull/22551))
The Mastra Code terminal folds the same prompt into its skill row.
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`285ce1c`](285ce1c139),
[`045c3c7`](045c3c78f2),
[`f01f822`](f01f822cbe),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/mcp@1.17.3-alpha.1
- @mastra/libsql@1.22.3-alpha.1
- @mastra/pg@1.22.3-alpha.1
- @mastra/code-sdk@1.6.0-alpha.7
## mastra@1.27.3-alpha.6
### Patch Changes
- Fixed the Studio browser viewer never mounting for CLI browser
providers like @mastra/browser-viewer. Studio now gates the browser
session probe and screencast stream on the agent's `hasBrowser`
capability instead of the SDK browser tool count. Fixes
https://github.com/mastra-ai/mastra/issues/22535
([#22789](https://github.com/mastra-ai/mastra/pull/22789))
- Updated dependencies
[[`b114e78`](b114e787e8),
[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/deployer@1.64.0-alpha.5
- @mastra/core@1.64.0-alpha.5
## @mastra/core@1.64.0-alpha.5
### Patch Changes
- Fixed `SlashCommandChannelHandler`,
`SlashCommandChannelHandlerConfig`, and `SlashCommandEvent` not being
exported from `@mastra/core/channels`. Standalone slash-command handlers
can now be typed directly instead of reaching through
`ChannelHandlers['onSlashCommand']`.
([#22814](https://github.com/mastra-ai/mastra/pull/22814))
```ts
import type { SlashCommandChannelHandler } from '@mastra/core/channels';
const onSlashCommand: SlashCommandChannelHandler = async (event,
defaultHandler) => {
if (event.command === '/help') {
await event.channel.post('Available commands: /help');
return;
}
await defaultHandler();
};
```
- Exported the validateToolOutput helper from @mastra/core/tools so
integrations can validate tool results against a schema and produce the
same structured validation error as createTool.
([#22779](https://github.com/mastra-ai/mastra/pull/22779))
- Fixed signals sent after DurableAgent recovery so they are drained by
the resumed run.
([#22781](https://github.com/mastra-ai/mastra/pull/22781))
- Fixed background tasks advertising the `_background` override to every
tool. Previously, enabling `backgroundTasks` on the Mastra instance
injected the `_background` field into every tool's input schema and
listed every tool as background-eligible in the system prompt, even when
neither the agent nor the tool opted in. Now only tools that are
actually background-eligible — via the agent's `backgroundTasks.tools`
config or the tool's own `background: { enabled: true }` — advertise the
override, matching the runtime dispatch behavior. This removes roughly
2,000 characters of prompt overhead per ineligible tool and stops the
model from being told it can background tools it cannot. Fixes
[#22724](https://github.com/mastra-ai/mastra/issues/22724).
([#22777](https://github.com/mastra-ai/mastra/pull/22777))
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
## @mastra/deployer@1.64.0-alpha.5
### Patch Changes
- Fixed the browser screencast stream and session probe not finding
workspace-level CLI browser providers. The server's browser stream
`getToolset` now falls back to the agent's workspace browser when no
agent-level browser is configured. Fixes
https://github.com/mastra-ai/mastra/issues/22535
([#22789](https://github.com/mastra-ai/mastra/pull/22789))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/mcp@1.17.3-alpha.1
### Patch Changes
- Fixed MCP tools not validating structured tool results against the
tool's output schema. Tools rebuilt from a cached catalog with
toolFromDefinition / toolsFromDefinitions (and live-discovered tools
whose result bypasses the SDK check) now validate structuredContent
before it reaches the model, and return the same structured validation
error that createTool produces on mismatch. Valid results, in-band tool
errors, and results without structuredContent are unchanged. Fixes
https://github.com/mastra-ai/mastra/issues/22549
([#22779](https://github.com/mastra-ai/mastra/pull/22779))
- Required @mastra/core 1.64 or newer so MCP can use the tool output
validation API added in that release.
([#22817](https://github.com/mastra-ai/mastra/pull/22817))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/mcp-docs-server@1.2.23-alpha.11
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`285ce1c`](285ce1c139),
[`045c3c7`](045c3c78f2),
[`f01f822`](f01f822cbe),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/mcp@1.17.3-alpha.1
## @mastra/playground-ui@51.4.0-alpha.8
### Patch Changes
- Redesigned the trace side panel summary in Studio. The metadata grid
was replaced with a compact, single-line description under the trace
title using icons and tooltips for the linked entity, start time,
duration, input and output tokens, and estimated cost. The "Details" tab
is now labeled "Spans", and secondary trace header actions are
consolidated into a single actions menu.
([#22804](https://github.com/mastra-ai/mastra/pull/22804))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148),
[`b114e78`](b114e787e8)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/client-js@1.42.5-alpha.5
- @mastra/react@1.4.10-alpha.6
## @mastra/server@1.64.0-alpha.5
### Patch Changes
- Serialized agents now report a `hasBrowser` capability flag that is
true for agent-level SDK browsers and workspace-level CLI browsers
(which expose no SDK tools). Fixes
https://github.com/mastra-ai/mastra/issues/22535
([#22789](https://github.com/mastra-ai/mastra/pull/22789))
- Fixed the Studio browser viewer checking whether the wrong thread's
browser was running. When a viewer connected for a specific thread, the
server asked the browser toolset about the globally "current" thread
instead of the viewer's thread, which could log "Browser ready" and
"Browser not running" for the same thread and leave the viewer stuck
waiting. The viewer's thread ID is now passed through so the check
answers for the right thread. Fixes
https://github.com/mastra-ai/mastra/issues/22538
([#22815](https://github.com/mastra-ai/mastra/pull/22815))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/elysia@0.1.4-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/express@1.5.8-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/fastify@1.5.8-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/hono@1.7.6-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/koa@1.7.8-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/nestjs@0.2.23-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
## @mastra/next@0.2.22-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
- @mastra/hono@1.7.6-alpha.5
## @mastra/tanstack-start@0.2.22-alpha.5
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b114e78`](b114e787e8),
[`045c3c7`](045c3c78f2),
[`74df727`](74df727e27),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/server@1.64.0-alpha.5
- @mastra/hono@1.7.6-alpha.5
## @mastra/dsql@1.3.4-alpha.1
### Patch Changes
- Fixed memory thread and resource timestamps being written in the
server's local timezone. `createdAt` and `updatedAt` are now stored as
UTC, so both timestamp column variants hold the same instant regardless
of where the process runs.
([#22818](https://github.com/mastra-ai/mastra/pull/22818))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/libsql@1.22.3-alpha.1
### Patch Changes
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/mongodb@1.18.5-alpha.1
### Patch Changes
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/mssql@1.7.4-alpha.1
### Patch Changes
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/mysql@0.8.5-alpha.1
### Patch Changes
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/pg@1.22.3-alpha.1
### Patch Changes
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/spanner@1.6.4-alpha.1
### Patch Changes
- Fixed scheduled workflows disappearing from Studio's Schedules tab for
dynamically created workflows. Dynamic workflow definitions now persist
their schedule configuration, so schedules are re-declared after a
restart instead of being deleted as orphans. Schedules of dynamic
workflows that fail to load are also kept instead of being swept. Fixes
https://github.com/mastra-ai/mastra/issues/22756
([#22778](https://github.com/mastra-ai/mastra/pull/22778))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/turso@0.1.3-alpha.1
### Patch Changes
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/libsql@1.22.3-alpha.1
## @mastra/temporal@0.4.2-alpha.5
### Patch Changes
- Updated dependencies
[[`b114e78`](b114e787e8),
[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/deployer@1.64.0-alpha.5
- @mastra/core@1.64.0-alpha.5
## @mastra/e2b@0.11.0-alpha.3
### Patch Changes
- Fixed repo templates silently degrading to a repo-less template on
hosts without a `git` binary (deployed Mastra servers), which made every
session cold-clone at runtime. GitHub (github.com) clone URLs now
resolve the default-branch head through the GitHub REST API; other hosts
keep using `git ls-remote`.
([#22833](https://github.com/mastra-ai/mastra/pull/22833))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## @mastra/platform-workspace@1.5.0-alpha.3
### Patch Changes
- Fixed repo templates silently degrading to a repo-less template on
hosts without a `git` binary (deployed Mastra servers), which made every
session cold-clone at runtime. GitHub (github.com) clone URLs now
resolve the default-branch head through the GitHub REST API; other hosts
keep using `git ls-remote`.
([#22833](https://github.com/mastra-ai/mastra/pull/22833))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148)]:
- @mastra/core@1.64.0-alpha.5
## create-mastra@1.27.3-alpha.6
## @internal/playground@1.27.3-alpha.6
### Patch Changes
- Fixed Studio-generated forms silently dropping `Date`, `File`, `Blob`,
`Map`, and other non-plain object values before validation and
submission. The empty-value cleanup now only recurses into arrays and
plain objects, so typed schema fields such as `z.date()` receive their
values intact. Fixes
[#22736](https://github.com/mastra-ai/mastra/issues/22736).
([#22819](https://github.com/mastra-ai/mastra/pull/22819))
- Updated dependencies
[[`decd47d`](decd47d0db),
[`285ce1c`](285ce1c139),
[`5b5e3cc`](5b5e3cc006),
[`b66b233`](b66b23374a),
[`045c3c7`](045c3c78f2),
[`d53a056`](d53a056148),
[`b114e78`](b114e787e8)]:
- @mastra/core@1.64.0-alpha.5
- @mastra/playground-ui@51.4.0-alpha.8
- @mastra/client-js@1.42.5-alpha.5
- @mastra/react@1.4.10-alpha.6
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Description
This is the final PR of the stack split from #19019: memory
summarization (#19135, merged) → **livekit worker configuration +
MastraLLM plugin + voice-agent example (this PR)**. The example PR
(#19137) was consolidated into this one after review feedback landed, so
the package changes and the runnable example that exercises them ship
and get reviewed together.
> **Note for reviewers:** Tyler's split request listed the worker
`configuration` surface; the `MastraLLM` plugin work landed on the
original branch after that comment. Both are `@mastra/livekit` package
code, so they ride together here — happy to split the plugin into its
own 4th PR if you'd rather review it separately.
### `@mastra/livekit` — new grouped `configuration` worker option
One home for conversation & compliance policy on `createLiveKitWorker`,
so each control doesn't become another top-level option:
- **`configuration.greeting` — AI disclosure controls.** `text` spoken
at call start; `allowInterruptions: false` so a legally-required AI
disclosure plays through and can't be barged over (EU AI Act Art. 50);
`awaitPlayout: true` holds post-greeting work (persistence,
`onSessionStart`) until it finishes; `persist` saves it to the memory
thread; `repeatEvery`/`repeatText` re-disclose periodically on long
calls, spoken at the next turn boundary, never mid-sentence (CA SB
243-style requirements).
- **Per-tenant dynamic greeting.** `greeting.text` also accepts a
resolver `({ metadata, requestContext, roomName, ctx }) => string |
undefined`, resolved once per call *post-connect* — so one shared
multi-tenant agent opens with each tenant's own brand/disclosure
phrasing keyed off dispatch metadata / request context.
- **`configuration.stt` / `configuration.tts` — per-call resolvers.**
Pick the transcriber and voice per call — one voice or language per
tenant — falling back to the top-level `stt`/`tts` when they return
`undefined`.
- **`configuration.consentPolicy` — named consent model.** (Renamed from
`requireConsent` per review — it is declarative only; the worker
enforces nothing by itself.) Declares the data-use consents a call needs
as an extensible named set (starting with `summaryStorage`);
requirements are surfaced on `onCallEnd` for enforcement. Paired with
**`createConsentTool`** (new server-safe root export): captures each `{
item, granted }` decision at runtime with the caller identity from tool
context and hands it to an app-owned store.
- **`configuration.endCall` — agent-initiated hang-up.** Paired with
**`createEndCallTool`** (new server-safe root export). The worker waits
for the goodbye to finish playing out (`waitForAgentDoneSpeaking`,
capped by `maxWaitMs`), optionally speaks a non-interruptible closing
`message`, then deletes the room and shuts down the job — running
`onCallEnd` exactly as a caller hang-up does. Works on both the agent
and workflow reply paths.
- **Backwards compatible.** The released top-level `greeting` /
`persistGreeting` options remain as deprecated aliases;
`configuration.greeting` wins field-by-field.
### `@mastra/livekit/plugin` — `MastraLLM`, use Mastra as the LLM inside
a customer-owned LiveKit session
Until now, using Mastra for voice meant Mastra ran the *whole* call.
`MastraLLM` flips the ownership: the customer keeps their own LiveKit
`AgentSession` — their STT/TTS vendors, turn detection, deployment — and
drops Mastra into the LLM slot as a standard `llm.LLM` plugin.
- **New `@mastra/livekit/plugin` subpath export** (root stays
server-safe): `MastraLLM extends llm.LLM`, plugs straight into
`voice.AgentSession({ llm: new MastraLLM(...) })`.
- **Three interchangeable brain sources** (exactly one required):
`remote` (HTTP/SSE to a running Mastra server via
`createRemoteAgentReplyGenerator`, with abort propagation and
configurable timeouts), `agent` (in-process), or `generate` (fully
custom).
- **Mastra features surface cleanly:** thread/resource memory plumbed
per call; shared message ids dedupe what the server already persisted;
LiveKit-side `instructions` filtered rather than double-applied;
`memory` + LiveKit's preemptive generation guarded and documented.
- **Interrupted turns self-heal:** on barge-in the server skips
persisting the unheard reply; the plugin records only what the caller
actually heard, flags it interrupted, and reconciles it into memory on
the next turn.
- **Hooks:** `toolFeedback` (spoken filler while a tool runs),
`onToolCall`, `onTurnComplete` (per-turn
text/tool-calls/interrupted/usage, off the audio path).
`createLiveKitWorker` gained the same `onToolCall`/`onTurnComplete`
hooks, since both paths now share one reply seam.
### Drift fix vs the original branch
`main` bumped `@livekit/agents` 1.4.11 → 1.5.0 after #19019 branched.
1.5.0 turns `ToolContext` into a class that `AgentSession` always passes
to `llm.chat()` — `Object.keys()` on it saw only private fields, so
`MastraLLM`'s ignored-tools warning fired on every session (even
tool-less) with garbage names. Fixed in a dedicated commit (262d90d7fc):
tool names now come from the instance's `flatten()`, with plain-map
fallback for 1.4; two regression tests added.
## Scope
- All `integrations/livekit` changes: `configuration`
(greeting/consent/endCall/stt/tts), consent + end-call tools,
`MastraLLM` plugin, remote SSE transport, reply-seam hooks, README
- Docs: LiveKit voice guide (wrapper-vs-plugin comparison,
preemptive-generation warning) + full reference entries
- Changesets: 3 × `@mastra/livekit` minor (configuration, stt/tts
resolvers, plugin)
## Also included (consolidated from #19137)
- `examples/voice-agent`: permissive default worker + regulated demo
(consent-gated summarization) + customer-owned-session plugin worker
- `@mastra/memory` summarization — PR 1 (#19135); the README's
`memory.summarizeThread()` mentions depend on it, hence the stack order
## Verification
- `pnpm vitest run` in `integrations/livekit` — 186/186 passing across
15 files (was 184; +2 regression tests for the 1.5.0 ToolContext fix)
- `tsc --noEmit`, `pnpm build:lib`, `pnpm lint` — clean
- Verified live over LiveKit + Studio voice mode on the original branch:
disclosure playout, consent capture, agent-initiated hang-up, and the
plugin end-to-end against a remote Mastra server (barge-in
reconciliation, spoken tool feedback, `onTurnComplete` usage)
## Type of change
- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR upgrades the LiveKit voice agent so you can control—per call—how
it introduces itself, when/what consent it asks for, and how it ends
(including letting the agent hang up). It also adds a new
`@mastra/livekit/plugin` entry so customers can plug Mastra
(`MastraLLM`) into their own LiveKit `AgentSession`, plus tools to
record consent and trigger a safe end-call flow.
## Summary
- Updated `createLiveKitWorker` with a grouped per-call `configuration`
option for:
- greeting / AI disclosure behavior,
- consent via a named `consentPolicy` model,
- optional agent-initiated hang-up via `endCall`,
- per-call `stt`/`tts` resolvers (run once per call) with fallback to
legacy top-level `stt`/`tts`.
- Kept legacy top-level `greeting` and `persistGreeting` as deprecated
aliases, with `configuration.greeting.*` taking precedence.
- Added new server-safe root exports:
- `createConsentTool` to record runtime consent decisions (including
caller identity fields) using schema validation and an `onGrant`
persistence callback.
- `createEndCallTool` to let the agent end the call after an optional
goodbye/closing workflow, while ensuring shutdown flow continues even if
bookkeeping fails (warns instead of breaking execution).
- Introduced `@mastra/livekit/plugin` with `MastraLLM`, a LiveKit
LLM-component for customer-owned `AgentSession`s, supporting exactly one
reply source: `remote`, `agent`, or `generate`.
- Includes remote HTTP/SSE reply generation, interrupted-turn
“self-healing” memory reconciliation, tool activity hooks
(`toolFeedback`, `onToolCall`, `onTurnComplete`), and token usage
surfaced via `result.usage`.
- Improved worker robustness and observability:
- AI re-disclosure reminders,
- mid-stream `onToolCall` notifications,
- stable message `id` propagation and filtering of LiveKit-injected
instruction messages,
- wired `configuration.endCall` into the workflow reply path,
- tightened watchdog + hook error handling, plus regression tests.
- Consolidated and refreshed `examples/voice-agent` (including new
regulated and plugin worker scripts) and updated LiveKit docs/reference
to reflect the new grouped configuration, `consentPolicy` rename, and
`@mastra/livekit/plugin` entrypoint.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
LiveKit runs the audio loop (WebRTC, streaming STT, semantic turn
detection, barge-in, TTS); the Mastra agent generates every reply with
its own model, tools, and memory via an llmNode bridge. Includes a
Studio voice mode (phone button, live captions, per-call memory
threads), a call-center example app, docs, and changesets.
**@mikhael28 -** Building on Shane's foundation, the integration picked
up several capabilities during development to bring it closer to
production-ready:
- **Workflow-driven replies.** Beyond the agent path, a turn's reply can
now be generated by a Mastra workflow that runs once to completion per
detected turn (`createWorkflowReplyGenerator`), with a
`pipeAgentReplyToWriter` helper that streams the agent's text *and*
forwards its tool calls into a workflow step. The workflow path is at
full feature parity with the agent path.
- **Per-turn and end-of-call lifecycle hooks.** `onTurnComplete` runs
after each reply finishes streaming (off the audio path,
fire-and-forget) and `onCallEnd` runs once when the call ends (awaited
within LiveKit's shutdown grace window). Together they give a clean seam
for memory maintenance, CRM writes, analytics, and flushing
observational memory once per call — none of it adding to the caller's
latency.
- **Voice-call observability.** Each session opens a root "voice call"
trace: LiveKit's STT/TTS/turn-detection/VAD metrics attach as child
spans, per-turn agent runs nest underneath, and the call closes with a
token/audio usage roll-up.
- **Working + observational memory showcase.** The example app
demonstrates layering per-caller working memory and observational memory
into a live voice agent, with a deterministic end-of-call reconciliation
pass.
- **Production hardening from review.** Config-validation guards
(mutually-exclusive reply sources, dispatch credential checks),
structured logging through the Mastra logger, backpressure and
cancellation safety on barge-in, and two full rounds of CodeRabbit
feedback addressed.
## Description
<!-- Required: Provide a brief description of the changes in this PR.
-->
## Related issue(s)
<!-- Required: Link to the issue(s) this PR addresses, e.g. with: Fixes
#123. PRs without linked issues may be closed. -->
## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] I have linked the related issue(s) in the description above
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds a “talk by phone” voice mode to Mastra Studio. When you
click the phone button, LiveKit handles the audio + live captions, and
Mastra decides what to say back—without waiting for the caller to finish
(you can interrupt/“barge in” mid-sentence).
## Overview
Introduces a new `@mastra/livekit` integration that turns Mastra agents
into realtime, interruptible voice agents by wiring LiveKit’s audio loop
(WebRTC, STT, VAD/turn detection, barge-in, TTS) to Mastra’s normal
reply generation. Studio/Playground adds a voice call UI with a phone
button, live captions, agent state indicators, and per-call “voice
thread” continuity alongside text chat.
## Core integration: `@mastra/livekit`
- **LiveKit ↔ Mastra bridge (`bridge.ts`)**: `MastraVoiceAgent` /
`createMastraVoiceAgent` streams Mastra outputs into LiveKit voice
responses, supports tool-call “spoken feedback”, and implements barge-in
by canceling/aborting the active Mastra generation.
- **Worker support (`worker.ts`, `worker-setup.ts`, `run.ts`)**:
`createLiveKitWorker` + `runLiveKitWorker` configure STT/TTS/VAD/turn
detection, end-of-utterance (turn) handling, optional greetings, and
per-call lifecycle hooks. When memory is enabled, the worker ensures a
dedicated voice thread and can persist spoken greetings.
- **Reply generation options (agent or workflow)**: per-turn replies can
be produced via a Mastra **agent stream** or a **workflow**
(run-to-completion per detected turn), with a shared generation seam for
streaming text + tool calls.
- **Server routing + dispatch**
- `liveKitConnectionRoute()` mints LiveKit connection-details tokens and
embeds typed session metadata (e.g., `agentId`, `threadId`,
`resourceId`).
- `dispatchVoiceSession()` programmatically creates LiveKit dispatches
(server-side), reading `LIVEKIT_*` env vars when not provided.
- **Session/message helpers**
- `metadata.ts` provides typed parse/serialize helpers for session
metadata.
- `messages.ts` converts LiveKit chat context into Mastra “turn”
messages and can extract only “new turns” to avoid duplicating persisted
history.
- `voice-thread.ts` creates/ensures the per-call “Voice call” memory
thread and persists the spoken greeting (skipping empty greetings).
- **Observability (`observability.ts`)**: optional voice-call tracing
with a root “voice call” span, nested turn metrics, and per-model usage
rollups.
## Studio/Playground voice mode (UI)
- Adds a voice domain with `useVoiceCall()` to fetch connection details,
connect to a LiveKit room, enable the microphone, and stream/aggregate
captions into UI state (with stale-async protection via epochs/abort).
- Adds:
- `VoiceCallButton` (idle/connecting/active + start/stop)
- `VoiceCallPanel` (agent state + latest user/agent caption)
- Wires the phone button into the chat composer so starting a call
refreshes the correct thread/messages and keeps voice + text in the same
memory continuity.
## Example app: Meridian Trades call center
Adds `examples/voice-agent`, a working call-center voice demo using
`@mastra/livekit`, including:
- A caller-facing `callCenterAgent` plus a fast `triageAgent` intent
classifier.
- Call-center CRM-style tools (customer lookup, availability,
booking/rescheduling/cancellation) and intake reconciliation.
- Two interchangeable voice worker entrypoints (agent-driven vs
workflow-driven) with feature parity.
- Seeded in-memory scheduling data, deterministic end-of-call
reconciliation, per-caller memory layers, and a single-file SQLite trace
output.
## Tests, docs, and release notes
- Adds unit tests for the LiveKit↔Mastra bridge (streaming, tool
feedback, barge-in/abort behavior), message extraction, session metadata
parsing/round-trips, route token minting, worker/session setup, workflow
reply generation, observability, and the Playground voice call
lifecycle.
- Adds LiveKit documentation (guide + API reference) and sidebar
entries.
- Adds Changesets for the new `@mastra/livekit` package and for Studio
voice mode changes (including new per-turn/per-call lifecycle hook
coverage).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: mikhael28 <mikhael@hey.com>