@mastra/livekit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,272 @@
 # @mastra/livekit
 
+## 0.3.0
+
+### Minor Changes
+
+- Added per-call speech-to-text and text-to-speech selection to `createLiveKitWorker`. Set the new `configuration.stt` and `configuration.tts` resolvers to pick the transcriber and voice for each call — one voice or language per tenant — keyed off the dispatch metadata and request context. Each resolver runs once per call and falls back to the top-level `stt` / `tts` option when it returns `undefined`. ([#19136](https://github.com/mastra-ai/mastra/pull/19136))
+
+  ```ts
+  export default createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3', // fallback voice
+    configuration: {
+      // Give each tenant its own voice, resolved per call from the dispatch metadata.
+      tts: ({ requestContext }) => tenantVoices[requestContext?.tenant as string],
+    },
+  });
+  ```
+
+  Previously the worker's speech pipeline was fixed at construction, so a multi-tenant worker could not vary voices or transcription per call. Customers who own their LiveKit session (the `MastraLLM` plugin path) already choose STT/TTS per call by construction; this brings the same flexibility to the batteries-included worker.
+
+- Added `MastraLLM`, a standard LiveKit LLM plugin, on the new `@mastra/livekit/plugin` entry point. Build your own `voice.AgentSession` and put a Mastra agent in the `llm` slot — the agent loop, tools, and memory run on a remote Mastra server reached over HTTP, so the worker process needs no Mastra app, database, or model provider keys. ([#19136](https://github.com/mastra-ai/mastra/pull/19136))
+
+  Before, the worker wrapper always owned the LiveKit session:
+
+  ```ts
+  import { createLiveKitWorker } from '@mastra/livekit/worker';
+  import { mastra } from './index';
+
+  export default createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+  });
+  ```
+
+  Now you can own the session and keep Mastra as the LLM component:
+
+  ```ts
+  import { voice } from '@livekit/agents';
+  import { MastraLLM } from '@mastra/livekit/plugin';
+
+  const session = new voice.AgentSession({
+    llm: new MastraLLM({
+      remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'support' },
+      memory: { thread: callId, resource: userId },
+    }),
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+    // Required with `memory`: LiveKit enables preemptive generation by default.
+    turnHandling: { preemptiveGeneration: { enabled: false } },
+  });
+  ```
+
+  `createLiveKitWorker` stays the batteries-included path; the plugin is the composable one. Tools keep running server-side on the Mastra agent, and interrupting the agent aborts the server-side generation.
+
+  **New transport and helpers**
+  - Added `createRemoteAgentReplyGenerator()`: streams replies from a remote Mastra server over HTTP with per-turn abort, LiveKit-typed errors, and a connect + first-token timeout. It also plugs into `createLiveKitWorker`'s `generate` option to run the existing worker against a remote server.
+  - Promoted `speakGreeting()`, `waitForAgentDoneSpeaking()`, and `runEndCall()` to public exports of `@mastra/livekit/worker`, so a worker that owns its session can rebuild the greeting and agent-initiated hang-up patterns in a few lines.
+
+  **Improvements to the existing worker**
+  - Interrupted turns now self-heal: when a caller interrupts a reply, nothing is persisted at that moment, and the part the caller actually heard is backfilled into the memory thread on the next turn — so saved transcripts match the call.
+  - Added an `onToolCall` hook that fires as each tool call starts mid-reply, the building block for tool-driven side effects such as analytics or hang-up.
+  - `onTurnComplete` now receives the turn's token usage as `result.usage`.
+
+- Added a `configuration` option to `createLiveKitWorker` — one grouped home for conversation and compliance controls, so these don't each become a separate top-level worker option. It ships with greeting/AI-disclosure controls, a consent model, and agent-initiated hang-up, and is where further compliance controls will land. ([#19136](https://github.com/mastra-ai/mastra/pull/19136))
+
+  **Greeting and AI disclosure**
+
+  `configuration.greeting` controls the opening line spoken at call start. Set `allowInterruptions: false` so a legally-required AI disclosure plays through and can't be talked over (EU AI Act Art. 50), `awaitPlayout: true` to hold post-greeting work until it finishes, and `repeatEvery` to re-disclose periodically on long calls (spoken at the next turn boundary, never mid-sentence).
+
+  ```ts
+  createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    configuration: {
+      greeting: {
+        text: 'You are speaking with an AI assistant. This call may be recorded. How can I help?',
+        allowInterruptions: false,
+        awaitPlayout: true,
+        repeatEvery: 3 * 60_000, // re-disclose ~every 3 minutes
+      },
+    },
+  });
+  ```
+
+  **Per-tenant greeting**
+
+  `greeting.text` also accepts a resolver, called once per call with the call context, so one multi-tenant agent can open differently per tenant based on the dispatch metadata:
+
+  ```ts
+  greeting: {
+    text: ({ metadata }) => `Thanks for calling ${tenantName(metadata)}. You're speaking with an AI assistant.`,
+    allowInterruptions: false,
+  }
+  ```
+
+  **Consent**
+
+  `configuration.consentPolicy` declares which data-use consents a call needs, as a named, extensible set (starting with `summaryStorage`) rather than one global flag. Declaring the policy enforces nothing by itself: the new `createConsentTool` captures the caller's decision at runtime — add it to your agent and it hands each decision to your own store — and your code enforces the requirement at `onCallEnd` (or before any consent-gated step).
+
+  ```ts
+  import { createConsentTool } from '@mastra/livekit';
+
+  // in your agent's tools:
+  recordConsent: createConsentTool({
+    items: ['summaryStorage'],
+    onGrant: async ({ item, granted, resourceId }) => {
+      if (resourceId) await db.saveConsent(resourceId, item, granted);
+    },
+  }),
+  ```
+
+  **Agent-initiated hang-up**
+
+  `configuration.endCall` lets the agent end the call itself. Add the new `createEndCallTool` to your agent and instruct it to say goodbye and then call the tool; the worker waits for the closing words to finish playing, holds a short audio drain (`drainMs`, default 800ms) so the tail of the goodbye isn't clipped while it's still buffered at the caller, then hangs up — running `onCallEnd` on the way out, exactly as a caller hang-up does. It works on both the agent and workflow reply paths.
+
+  ```ts
+  import { createEndCallTool } from '@mastra/livekit';
+
+  // in your agent's tools:
+  endCall: (createEndCallTool(),
+    // on the worker:
+    createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } }));
+  ```
+
+  **Backwards compatible**
+
+  The previous top-level `greeting` (string) and `persistGreeting` options still work as deprecated aliases for `configuration.greeting.text` and `configuration.greeting.persist`. When both are set, `configuration.greeting` wins field by field, so existing worker configs keep running unchanged.
+
+### Patch Changes
+
+- Updated dependencies [[`bd6d240`](https://github.com/mastra-ai/mastra/commit/bd6d2402db93dddaef0721667e7e8a030e7c6e16), [`0111486`](https://github.com/mastra-ai/mastra/commit/01114867612593eef5cfa2fda6a1194dfedda841), [`96a3749`](https://github.com/mastra-ai/mastra/commit/96a37492235f5b8076b3e3177d83ed5a5e44a640), [`fe1bda0`](https://github.com/mastra-ai/mastra/commit/fe1bda06f6af92a694a51712db747cda1e7185f0), [`25e7c12`](https://github.com/mastra-ai/mastra/commit/25e7c126a770069ae7fb7ecf1d2adb40e017b009), [`1ce5121`](https://github.com/mastra-ai/mastra/commit/1ce512155d122bb21f47d98383e82ffbf84b39e8), [`fb8aea3`](https://github.com/mastra-ai/mastra/commit/fb8aea384291e77311be3a64ee1717320d5c3c73), [`4adc391`](https://github.com/mastra-ai/mastra/commit/4adc3911075249c352bb4832d2471922826344de), [`a5c6337`](https://github.com/mastra-ai/mastra/commit/a5c6337d23c7686c81a32ce62f550f610543a240), [`3cfc47a`](https://github.com/mastra-ai/mastra/commit/3cfc47a6b89940aadd0f46fb01ae9624a73a865d), [`2bb7817`](https://github.com/mastra-ai/mastra/commit/2bb78176112fde628483de2830528f7eee911e56), [`51d9870`](https://github.com/mastra-ai/mastra/commit/51d987032c689c2855374d0f244f5d654da809d1), [`5cab274`](https://github.com/mastra-ai/mastra/commit/5cab2744250e22d12fefa7b32637dce224233cee), [`7fa27d3`](https://github.com/mastra-ai/mastra/commit/7fa27d3b6f5ed68cd34e454a4d3ad9c482a0cfbc), [`8b97958`](https://github.com/mastra-ai/mastra/commit/8b979589f9aa59ba67cac565949475f2ffeb4ac3), [`8410541`](https://github.com/mastra-ai/mastra/commit/84105412c60ecd3bb33a9838146f59c4b588228f), [`a58dcbb`](https://github.com/mastra-ai/mastra/commit/a58dcbb546d7e1d65ebdc1f39e55f0908fcd9391), [`aa38805`](https://github.com/mastra-ai/mastra/commit/aa38805b878b827403be785eb90688d7172f5a40), [`153bd3b`](https://github.com/mastra-ai/mastra/commit/153bd3b396bdfed6b74cf43de12db8fd2d83c04a), [`45a8e65`](https://github.com/mastra-ai/mastra/commit/45a8e65e1556d1362cb3f25187023c36de26661d), [`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`2d22570`](https://github.com/mastra-ai/mastra/commit/2d22570c7dfdd02123d0ecc529efb05ccba2d9fc), [`07bb863`](https://github.com/mastra-ai/mastra/commit/07bb8631919c6f7cf377dccd45b096e0f17fbed0), [`c8ed116`](https://github.com/mastra-ai/mastra/commit/c8ed11699f62bcac70102ab4ec84d80d20541da6), [`01b338c`](https://github.com/mastra-ai/mastra/commit/01b338c56271f0219606710e3e8b26dee27ac6c2), [`a99eae8`](https://github.com/mastra-ai/mastra/commit/a99eae8908e500c1b2d12f9d277be616b98617a5), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`edce8d2`](https://github.com/mastra-ai/mastra/commit/edce8d2769f19e27a05737c627af2d765472a4f8), [`8a586ec`](https://github.com/mastra-ai/mastra/commit/8a586eca9a4914f31dff6140d0d45ac375b00669), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`8b7361d`](https://github.com/mastra-ai/mastra/commit/8b7361d35de68b80d05d30a74e0c69e7218fd612), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2), [`3927473`](https://github.com/mastra-ai/mastra/commit/392747323ddb10c643d12be7b9ae913159dfaeed), [`dce50dc`](https://github.com/mastra-ai/mastra/commit/dce50dc9a1c1fcd0f427bb5f6250ec74910cb04b), [`fd13f8e`](https://github.com/mastra-ai/mastra/commit/fd13f8e21990f9904c3eedba3a626bb4a929cdb8), [`634caff`](https://github.com/mastra-ai/mastra/commit/634caff29a9200ad058b67d53f96d9e5832fb8a2), [`f703f87`](https://github.com/mastra-ai/mastra/commit/f703f878de072d51fda557f9c50867d8252bef05), [`3e26c87`](https://github.com/mastra-ai/mastra/commit/3e26c87de0c5bc2583b795ce6ca5889b6b161acb), [`33f2b88`](https://github.com/mastra-ai/mastra/commit/33f2b88842c09a567f906fac4cb61cd5277ced59), [`177010f`](https://github.com/mastra-ai/mastra/commit/177010ff096d2e4b28d89803be5b1a4cad2a0d6b), [`0ad646f`](https://github.com/mastra-ai/mastra/commit/0ad646f71a530f2454664299e5e01bfd13fa12e5), [`b486abf`](https://github.com/mastra-ai/mastra/commit/b486abfa2a7528c6f527e4015c819ea9fa54aaad), [`54a51e0`](https://github.com/mastra-ai/mastra/commit/54a51e0a484fe1ebad3fb1f7ef5282a075709eb7), [`c43f3a9`](https://github.com/mastra-ai/mastra/commit/c43f3a9d1efde99b38789364ba4d0ba670f430e3), [`a5008f2`](https://github.com/mastra-ai/mastra/commit/a5008f22ae710ad9402ea9f2547d8c02f74d384b), [`e2d5f37`](https://github.com/mastra-ai/mastra/commit/e2d5f373bd289be534d5f8694d34465010533df6), [`4ce0163`](https://github.com/mastra-ai/mastra/commit/4ce0163dc86e675a86809685c8ce6c49f1aeb87e), [`4378341`](https://github.com/mastra-ai/mastra/commit/43783412df5ea3dd35f5b1f6e4851e79c346fc89)]:
+  - @mastra/core@1.51.0
+
+## 0.3.0-alpha.0
+
+### Minor Changes
+
+- Added per-call speech-to-text and text-to-speech selection to `createLiveKitWorker`. Set the new `configuration.stt` and `configuration.tts` resolvers to pick the transcriber and voice for each call — one voice or language per tenant — keyed off the dispatch metadata and request context. Each resolver runs once per call and falls back to the top-level `stt` / `tts` option when it returns `undefined`. ([#19136](https://github.com/mastra-ai/mastra/pull/19136))
+
+  ```ts
+  export default createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3', // fallback voice
+    configuration: {
+      // Give each tenant its own voice, resolved per call from the dispatch metadata.
+      tts: ({ requestContext }) => tenantVoices[requestContext?.tenant as string],
+    },
+  });
+  ```
+
+  Previously the worker's speech pipeline was fixed at construction, so a multi-tenant worker could not vary voices or transcription per call. Customers who own their LiveKit session (the `MastraLLM` plugin path) already choose STT/TTS per call by construction; this brings the same flexibility to the batteries-included worker.
+
+- Added `MastraLLM`, a standard LiveKit LLM plugin, on the new `@mastra/livekit/plugin` entry point. Build your own `voice.AgentSession` and put a Mastra agent in the `llm` slot — the agent loop, tools, and memory run on a remote Mastra server reached over HTTP, so the worker process needs no Mastra app, database, or model provider keys. ([#19136](https://github.com/mastra-ai/mastra/pull/19136))
+
+  Before, the worker wrapper always owned the LiveKit session:
+
+  ```ts
+  import { createLiveKitWorker } from '@mastra/livekit/worker';
+  import { mastra } from './index';
+
+  export default createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+  });
+  ```
+
+  Now you can own the session and keep Mastra as the LLM component:
+
+  ```ts
+  import { voice } from '@livekit/agents';
+  import { MastraLLM } from '@mastra/livekit/plugin';
+
+  const session = new voice.AgentSession({
+    llm: new MastraLLM({
+      remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'support' },
+      memory: { thread: callId, resource: userId },
+    }),
+    stt: 'deepgram/nova-3',
+    tts: 'cartesia/sonic-3',
+    // Required with `memory`: LiveKit enables preemptive generation by default.
+    turnHandling: { preemptiveGeneration: { enabled: false } },
+  });
+  ```
+
+  `createLiveKitWorker` stays the batteries-included path; the plugin is the composable one. Tools keep running server-side on the Mastra agent, and interrupting the agent aborts the server-side generation.
+
+  **New transport and helpers**
+  - Added `createRemoteAgentReplyGenerator()`: streams replies from a remote Mastra server over HTTP with per-turn abort, LiveKit-typed errors, and a connect + first-token timeout. It also plugs into `createLiveKitWorker`'s `generate` option to run the existing worker against a remote server.
+  - Promoted `speakGreeting()`, `waitForAgentDoneSpeaking()`, and `runEndCall()` to public exports of `@mastra/livekit/worker`, so a worker that owns its session can rebuild the greeting and agent-initiated hang-up patterns in a few lines.
+
+  **Improvements to the existing worker**
+  - Interrupted turns now self-heal: when a caller interrupts a reply, nothing is persisted at that moment, and the part the caller actually heard is backfilled into the memory thread on the next turn — so saved transcripts match the call.
+  - Added an `onToolCall` hook that fires as each tool call starts mid-reply, the building block for tool-driven side effects such as analytics or hang-up.
+  - `onTurnComplete` now receives the turn's token usage as `result.usage`.
+
+- Added a `configuration` option to `createLiveKitWorker` — one grouped home for conversation and compliance controls, so these don't each become a separate top-level worker option. It ships with greeting/AI-disclosure controls, a consent model, and agent-initiated hang-up, and is where further compliance controls will land. ([#19136](https://github.com/mastra-ai/mastra/pull/19136))
+
+  **Greeting and AI disclosure**
+
+  `configuration.greeting` controls the opening line spoken at call start. Set `allowInterruptions: false` so a legally-required AI disclosure plays through and can't be talked over (EU AI Act Art. 50), `awaitPlayout: true` to hold post-greeting work until it finishes, and `repeatEvery` to re-disclose periodically on long calls (spoken at the next turn boundary, never mid-sentence).
+
+  ```ts
+  createLiveKitWorker({
+    mastra,
+    agent: 'support',
+    configuration: {
+      greeting: {
+        text: 'You are speaking with an AI assistant. This call may be recorded. How can I help?',
+        allowInterruptions: false,
+        awaitPlayout: true,
+        repeatEvery: 3 * 60_000, // re-disclose ~every 3 minutes
+      },
+    },
+  });
+  ```
+
+  **Per-tenant greeting**
+
+  `greeting.text` also accepts a resolver, called once per call with the call context, so one multi-tenant agent can open differently per tenant based on the dispatch metadata:
+
+  ```ts
+  greeting: {
+    text: ({ metadata }) => `Thanks for calling ${tenantName(metadata)}. You're speaking with an AI assistant.`,
+    allowInterruptions: false,
+  }
+  ```
+
+  **Consent**
+
+  `configuration.consentPolicy` declares which data-use consents a call needs, as a named, extensible set (starting with `summaryStorage`) rather than one global flag. Declaring the policy enforces nothing by itself: the new `createConsentTool` captures the caller's decision at runtime — add it to your agent and it hands each decision to your own store — and your code enforces the requirement at `onCallEnd` (or before any consent-gated step).
+
+  ```ts
+  import { createConsentTool } from '@mastra/livekit';
+
+  // in your agent's tools:
+  recordConsent: createConsentTool({
+    items: ['summaryStorage'],
+    onGrant: async ({ item, granted, resourceId }) => {
+      if (resourceId) await db.saveConsent(resourceId, item, granted);
+    },
+  }),
+  ```
+
+  **Agent-initiated hang-up**
+
+  `configuration.endCall` lets the agent end the call itself. Add the new `createEndCallTool` to your agent and instruct it to say goodbye and then call the tool; the worker waits for the closing words to finish playing, holds a short audio drain (`drainMs`, default 800ms) so the tail of the goodbye isn't clipped while it's still buffered at the caller, then hangs up — running `onCallEnd` on the way out, exactly as a caller hang-up does. It works on both the agent and workflow reply paths.
+
+  ```ts
+  import { createEndCallTool } from '@mastra/livekit';
+
+  // in your agent's tools:
+  endCall: (createEndCallTool(),
+    // on the worker:
+    createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } }));
+  ```
+
+  **Backwards compatible**
+
+  The previous top-level `greeting` (string) and `persistGreeting` options still work as deprecated aliases for `configuration.greeting.text` and `configuration.greeting.persist`. When both are set, `configuration.greeting` wins field by field, so existing worker configs keep running unchanged.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -14,7 +14,8 @@ caller speaks ─▶ VAD ─▶ STT ─▶ turn detection ─▶ [ Mastra agent
 - **Two reply paths** — answer turns with a Mastra **agent** (the default, richest path) or a Mastra **workflow** (run-to-completion per turn, e.g. deterministic intent routing). A low-level `generate` escape hatch accepts any custom reply generator.
 - **Full speech stack, pluggable** — STT/TTS as LiveKit inference model strings (`'deepgram/nova-3'`, `'cartesia/sonic-3'`) or your own plugin instances; Silero VAD and LiveKit multilingual/English turn detection; barge-in cancels in-flight generation automatically.
 - **Memory, scoped to the call** — `thread` = call, `resource` = caller, so a returning caller is recognized across calls. Up-front thread creation and greeting persistence keep the saved thread a faithful transcript. Works on the agent path and the workflow path (via `memoryInstance`).
-- **Lifecycle hooks** — `toolFeedback` (speak filler while a tool runs), `onTurnComplete` (post-turn, fire-and-forget, off the audio path), and `onCallEnd` (end-of-call, awaited within LiveKit's shutdown window — the place to flush observational memory).
+- **Lifecycle hooks** — `toolFeedback` (speak filler while a tool runs), `onTurnComplete` (post-turn, fire-and-forget, off the audio path), and `onCallEnd` (end-of-call, awaited within LiveKit's shutdown window — the place to summarize the finished call with `memory.summarizeThread()`).
+- **Compliance controls, grouped under `configuration`** — AI-disclosure greeting that can't be barged over (with a per-tenant resolver), periodic re-disclosure on long calls (`repeatEvery`), an extensible named consent model (`consentPolicy` declared on the worker, captured at runtime with `createConsentTool`), and agent-initiated hang-up (`endCall` + `createEndCallTool`) that waits for the goodbye to play out before disconnecting.
 - **Observability** — one `voice call` trace per session with LiveKit pipeline metrics and every Mastra run nested under it.
 - **Connection + dispatch helpers** — `liveKitConnectionRoute` mints tokens and dispatches the worker so a frontend can join.
 
@@ -33,10 +34,11 @@ Peer dependencies (`@mastra/core` and `@livekit/agents` are required; the two pl
 | `@livekit/agents-plugin-silero`  | the default `vad: 'silero'`                  |
 | `@livekit/agents-plugin-livekit` | `turnDetection: 'multilingual' \| 'english'` |
 
-The package has two entry points, one per process:
+The package has three entry points:
 
-- `@mastra/livekit` — server-side helpers (`liveKitConnectionRoute`, `dispatchVoiceSession`, `pipeAgentReplyToWriter`). Safe to import from Mastra server code; never loads the `@livekit/agents` runtime.
+- `@mastra/livekit` — server-side helpers (`liveKitConnectionRoute`, `dispatchVoiceSession`, `pipeAgentReplyToWriter`) and the agent tool factories (`createConsentTool`, `createEndCallTool` — they go on agents defined in server/shared code). Safe to import from Mastra server code; never loads the `@livekit/agents` runtime.
 - `@mastra/livekit/worker` — the worker runtime (`createLiveKitWorker`, `runLiveKitWorker`). Import it only from the worker entry file.
+- `@mastra/livekit/plugin` — the `MastraLLM` plugin, for customers who own their `voice.AgentSession` and want a Mastra agent in the `llm` slot (a standard LiveKit `llm.LLM`; in-process agent, remote Mastra server, or custom generator). Also loads the `@livekit/agents` runtime — keep it out of Mastra server code.
 
 ## Quick start
 
@@ -54,7 +56,9 @@ export default createLiveKitWorker({
   stt: 'deepgram/nova-3',
   tts: 'cartesia/sonic-3',
   turnDetection: 'multilingual',
-  greeting: 'Thanks for calling. How can I help?',
+  configuration: {
+    greeting: { text: 'Thanks for calling. How can I help?' },
+  },
 });
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -135,35 +139,145 @@ For full control, pass a `generate` function — any `VoiceReplyGenerator` that
 
 ## `createLiveKitWorker` options
 
-| Option                                              | Type                                      | Notes                                                                                                                                                                               |
-| --------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mastra`                                            | `Mastra`                                  | **Required.** The instance whose agents/workflows answer sessions.                                                                                                                  |
-| **Reply generation** (pick one)                     |                                           |                                                                                                                                                                                     |
-| `agent`                                             | `string \| Agent \| (args) => …`          | The agent that answers. Defaults to `metadata.agentId`.                                                                                                                             |
-| `workflow`                                          | `string \| Workflow \| (args) => string`  | Answer with a workflow instead. Requires `workflowInput`.                                                                                                                           |
-| `workflowInput`                                     | `(ctx & { metadata }) => inputData`       | Maps a turn into the workflow's `inputData`.                                                                                                                                        |
-| `replyStep`                                         | `string`                                  | Only stream text from this workflow step id.                                                                                                                                        |
-| `resultText`                                        | `(result) => string`                      | Fallback reply text when the workflow streams nothing.                                                                                                                              |
-| `generate`                                          | `VoiceReplyGenerator`                     | Lowest-level escape hatch.                                                                                                                                                          |
-| **Speech stack**                                    |                                           |                                                                                                                                                                                     |
-| `stt`                                               | plugin or `'provider/model'`              | Speech-to-text.                                                                                                                                                                     |
-| `tts`                                               | plugin or `'provider/model'`              | Text-to-speech.                                                                                                                                                                     |
-| `vad`                                               | `VAD \| 'silero' \| false`                | Voice activity detection. Defaults to `'silero'`.                                                                                                                                   |
-| `turnDetection`                                     | `'multilingual' \| 'english' \| …`        | End-of-turn detection.                                                                                                                                                              |
-| `turnHandling`                                      | `AgentSessionOptions['turnHandling']`     | Endpointing delays, interruption sensitivity, preemptive generation.                                                                                                                |
-| `sessionOptions` / `inputOptions` / `outputOptions` | partial LiveKit options                   | Merged over what the helper builds.                                                                                                                                                 |
-| **Memory**                                          |                                           |                                                                                                                                                                                     |
-| `memory`                                            | `false \| (args) => { thread, resource }` | Memory mapping. Defaults to `{ thread: metadata.threadId ?? room, resource: metadata.resourceId ?? thread }` when the agent has memory.                                             |
-| `memoryInstance`                                    | `Memory \| (args) => Memory`              | The `Memory` used to bootstrap the thread + persist the greeting on the **workflow/custom** path (no agent to source it from). Mastra storage is injected if the `Memory` has none. |
-| `greeting`                                          | `string`                                  | Spoken when the session starts.                                                                                                                                                     |
-| `persistGreeting`                                   | `boolean`                                 | Save the greeting to the thread. Defaults to `true`.                                                                                                                                |
-| **Lifecycle hooks**                                 |                                           |                                                                                                                                                                                     |
-| `toolFeedback`                                      | `(toolCall) => string \| void`            | Speak filler while a tool runs (agent + workflow).                                                                                                                                  |
-| `onTurnComplete`                                    | `VoiceTurnCompleteHook`                   | After each turn streams, **fire-and-forget**, off the audio path.                                                                                                                   |
-| `onCallEnd`                                         | `VoiceCallEndHook`                        | When the call ends, **awaited** within LiveKit's shutdown window.                                                                                                                   |
-| `onSessionStart`                                    | `(args) => …`                             | After the session starts — attach listeners, trigger replies, etc.                                                                                                                  |
-| **Other**                                           |                                           |                                                                                                                                                                                     |
-| `observability`                                     | `boolean`                                 | Voice-pipeline tracing. Defaults to `true`.                                                                                                                                         |
+| Option                                              | Type                                                  | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| --------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mastra`                                            | `Mastra`                                              | **Required.** The instance whose agents/workflows answer sessions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Reply generation** (pick one)                     |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `agent`                                             | `string \| Agent \| (args) => …`                      | The agent that answers. Defaults to `metadata.agentId`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `workflow`                                          | `string \| Workflow \| (args) => string`              | Answer with a workflow instead. Requires `workflowInput`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `workflowInput`                                     | `(ctx & { metadata }) => inputData`                   | Maps a turn into the workflow's `inputData`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `replyStep`                                         | `string`                                              | Only stream text from this workflow step id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `resultText`                                        | `(result) => string`                                  | Fallback reply text when the workflow streams nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `generate`                                          | `VoiceReplyGenerator`                                 | Lowest-level escape hatch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **Speech stack**                                    |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `stt`                                               | plugin or `'provider/model'`                          | Speech-to-text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `tts`                                               | plugin or `'provider/model'`                          | Text-to-speech.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `vad`                                               | `VAD \| 'silero' \| false`                            | Voice activity detection. Defaults to `'silero'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `turnDetection`                                     | `'multilingual' \| 'english' \| …`                    | End-of-turn detection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `turnHandling`                                      | `AgentSessionOptions['turnHandling']`                 | Endpointing delays, interruption sensitivity, preemptive generation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `sessionOptions` / `inputOptions` / `outputOptions` | partial LiveKit options                               | Merged over what the helper builds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| **Memory**                                          |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `memory`                                            | `false \| (args) => { thread, resource }`             | Memory mapping. Defaults to `{ thread: metadata.threadId ?? room, resource: metadata.resourceId ?? thread }` when the agent has memory.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `memoryInstance`                                    | `Memory \| (args) => Memory`                          | The `Memory` used to bootstrap the thread + persist the greeting on the **workflow/custom** path (no agent to source it from). Mastra storage is injected if the `Memory` has none.                                                                                                                                                                                                                                                                                                                                                            |
+| `configuration`                                     | `{ greeting?, consentPolicy?, endCall?, stt?, tts? }` | Grouped conversation & compliance config (see [Configuration](#configuration)). `greeting` (`text` — a string or a per-tenant resolver — plus `allowInterruptions`, `awaitPlayout`, `persist`, `repeatEvery`/`repeatText` for periodic AI re-disclosure), `consentPolicy` (extensible consent set, e.g. `summaryStorage`, surfaced on `onCallEnd`), `endCall` (agent-initiated hang-up; pair with `createEndCallTool`), and per-call `stt` / `tts` resolvers that pick this call's transcriber and voice (fall back to the top-level options). |
+| **Lifecycle hooks**                                 |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `toolFeedback`                                      | `(toolCall) => string \| void`                        | Speak filler while a tool runs (agent + workflow).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `onTurnComplete`                                    | `VoiceTurnCompleteHook`                               | After each turn streams, **fire-and-forget**, off the audio path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `onCallEnd`                                         | `VoiceCallEndHook`                                    | When the call ends, **awaited** within LiveKit's shutdown window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `onSessionStart`                                    | `(args) => …`                                         | After the session starts — attach listeners, trigger replies, etc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Other**                                           |                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `observability`                                     | `boolean`                                             | Voice-pipeline tracing. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+## Configuration
+
+`configuration` groups related conversation & compliance knobs in one place, so they don't each
+become a top-level worker option — and it's where further compliance controls land as they ship.
+
+```typescript
+createLiveKitWorker({
+  mastra,
+  agent: 'support',
+  configuration: {
+    greeting: {
+      // Spoken via TTS at call start (no model round-trip). Doubles as a required AI disclosure.
+      text: 'You are speaking with an AI assistant. This call may be recorded. How can I help?',
+      allowInterruptions: false, // caller can't barge over the disclosure (EU AI Act Art. 50)
+      awaitPlayout: true, // hold post-greeting work until the disclosure finishes
+      persist: true, // save it to the memory thread (default true)
+      // Periodic re-disclosure on long calls: once this interval elapses, the NEXT turn's reply is
+      // prefixed with a short "you're speaking with an AI" reminder (spoken at the turn boundary,
+      // never mid-turn). Omit to disable.
+      repeatEvery: 3 * 60_000, // ~every 3 minutes (California SB 243 and similar)
+      repeatText: 'Quick reminder — you are speaking with an AI assistant.', // optional; has a default
+    },
+    // Consent requirements — a named, extensible set. Each item is independently required and
+    // independently granted, so new items are added without one global "consented" flag.
+    consentPolicy: {
+      summaryStorage: true, // or { required: true, purpose: 'storing a summary of this call' }
+    },
+    // Let the agent end the call itself. Pair with a `createEndCallTool` tool on the agent; the
+    // worker waits for the agent's closing words to play out, then hangs up (running onCallEnd).
+    endCall: {
+      message: 'Thanks for calling. Goodbye!', // optional non-interruptible sign-off before hangup
+    },
+  },
+});
+```
+
+**Greeting / AI disclosure.** `text` is spoken at call start; `allowInterruptions: false` makes a
+required disclosure play through; `awaitPlayout: true` waits for it before anything else runs;
+`repeatEvery` re-discloses periodically on long calls. Under the EU AI Act (Art. 50) a person must be
+told they're interacting with an AI at the first interaction.
+
+**Per-tenant greeting.** `greeting.text` also takes a resolver — a function called once per call
+(post-connect) with the call context (`metadata`, `requestContext`, `roomName`, `ctx`). Return a
+greeting keyed off the dispatch metadata so one multi-tenant agent opens differently per tenant (the
+disclosure options still apply to whatever it returns; return `undefined` for no greeting):
+
+```typescript
+configuration: {
+  greeting: {
+    text: ({ requestContext }) => {
+      const tenant = TENANTS[requestContext?.tenantId as string];
+      return `Thanks for calling ${tenant?.name ?? 'us'}. You're speaking with an AI assistant.`;
+    },
+    allowInterruptions: false, // the disclosure still can't be barged over
+  },
+},
+```
+
+**Consent.** `consentPolicy` _declares_ which consents the call needs (starting with `summaryStorage`
+— consent to store a summary of the call). Capture the caller's decision at runtime with
+**`createConsentTool`** (exported from `@mastra/livekit`) — add it to your agent, and it reads the
+caller identity from the tool context and hands each decision to your store:
+
+```typescript
+import { createConsentTool } from '@mastra/livekit';
+
+// in your agent's tools:
+recordConsent: createConsentTool({
+  items: ['summaryStorage'],
+  onGrant: async ({ item, granted, resourceId }) => {
+    if (resourceId) await db.saveConsent(resourceId, item, granted); // your system of record
+  },
+}),
+```
+
+Then _enforce_ it: the requirements are surfaced on the `onCallEnd` hook (`args.configuration`), so
+you only run the consent-gated action — e.g. the `memory.summarizeThread()` call that stores the
+summary — when it isn't required or the caller granted it. Whether to gate at all is your policy
+call: a permissive deployment skips `consentPolicy` entirely and always summarizes, while a
+regulated one declares → captures → enforces (the runnable example ships both flavors). Further
+controls (recording notice, data retention, human handoff) are planned to land here too.
+
+**Agent-initiated hang-up.** `endCall` lets the agent end the call itself — say goodbye, then hang up.
+Enable it under `configuration`, and add a matching tool to the agent with **`createEndCallTool`**
+(both default to the tool name `'endCall'`). The tool only _signals_ intent — from inside
+`agent.stream()` it can't reach the room — so the worker owns the hang-up: on each turn it watches for
+the tool, waits for the agent's closing words to finish playing, holds a short drain (`drainMs`,
+default 800ms) so audio still buffered at the caller isn't clipped, then disconnects, running
+`onCallEnd` on the way out exactly as a caller hang-up does. It works on the
+agent and workflow reply paths.
+
+```typescript
+import { createEndCallTool } from '@mastra/livekit';
+
+// in your agent's tools:
+endCall: createEndCallTool({
+  // optional bookkeeping — the tool reads the caller identity from its context
+  onEndCall: ({ reason, resourceId }) => log.info('agent ended call', { reason, resourceId }),
+}),
+```
+
+Instruct the agent to say its goodbye and then call `endCall` as its final action. `endCall.message`
+adds a guaranteed non-interruptible sign-off spoken right before hanging up; `endCall.reason` sets the
+shutdown reason in LiveKit logs; `endCall.maxWaitMs` caps how long to wait for the closing words
+(default 30s). This is the AI-oversight companion to a future first-class human `handoff`.
+
+**Backwards compatibility.** The previous top-level `greeting` (string) and `persistGreeting` options
+still work — they're deprecated aliases for `configuration.greeting.text` and
+`configuration.greeting.persist`. If both are set, `configuration.greeting` wins field-by-field, so
+existing worker configs keep running unchanged while you migrate.
 
 ## Lifecycle hooks
 
@@ -184,9 +298,20 @@ createLiveKitWorker({
   },
 
   // 3. End-of-call: runs when the caller hangs up, AWAITED within LiveKit's shutdown grace window
-  //    (so it finishes before the process exits). The place for end-of-call memory maintenance.
-  onCallEnd: async ({ memory, memoryInstance }) => {
-    // e.g. flush observational memory once for the whole call instead of paying for it per turn.
+  //    (so it finishes before the process exits). The place for end-of-call work — e.g. summarize
+  //    the finished call into your own records. `memory.summarizeThread()` (@mastra/memory) runs a
+  //    one-shot summarization + structured extraction over the whole call, outside observational
+  //    memory's lifecycle — nothing is written back to memory; you decide where the result goes
+  //    (return value and/or each Extractor's `onExtracted` hook).
+  onCallEnd: async ({ memory }) => {
+    if (!memory) return;
+    await myMemory.summarizeThread({
+      // your app's `Memory` (from @mastra/memory)
+      model: 'openai/gpt-4.1-mini',
+      threadId: memory.thread,
+      resourceId: memory.resource,
+      instructions: 'Summarize this call for the business owner.',
+    });
   },
 });
 ```
@@ -293,7 +418,8 @@ Single-process HTTP hosts run the **Mastra server** as-is (`node .mastra/output/
 
 A complete, runnable reference lives in the Mastra monorepo at **[`examples/voice-agent`](https://github.com/mastra-ai/mastra/tree/main/examples/voice-agent)** — a trades-contractor front-desk voice agent that exercises nearly every feature here:
 
-- **Both entrypoints** — an agent worker (`pnpm worker`) and a workflow worker (`pnpm worker:workflow`, deterministic intent routing → memory-backed reply).
+- **Three workers, one agent name** (run one at a time): the default **agent** worker (`pnpm worker`) and **workflow** worker (`pnpm worker:workflow`, deterministic intent routing → memory-backed reply) are deliberately **permissive** — no consent friction, the end-of-call summary always runs. The **regulated** worker (`pnpm worker:regulated`, a "Northwind Financial" line) demonstrates every compliance control at once: non-interruptible AI disclosure, 45-second re-disclosure, a four-item runtime consent sweep with an audit ledger, agent-initiated hang-up with a compliance sign-off, and a consent-gated summary (no consent → no stored summary).
+- **End-of-call summarization** — every finished call is distilled into a structured record (summary, sentiment, requested services) via `memory.summarizeThread()` + an `Extractor` whose `onExtracted` hook writes to the app's own store, from the `onCallEnd` hook.
 - **Three memory layers** — working memory, semantic recall, and observational memory, all scoped to the caller.
 - **Tools + deterministic reconciliation**, a tenant-context input processor, the `toolFeedback` / `onTurnComplete` / `onCallEnd` hooks, and full observability.
 
@@ -310,7 +436,7 @@ pnpm worker:download-files      # one-time model download
 
 # in two terminals:
 pnpm dev                        # Mastra server + Studio at http://localhost:4111
-pnpm worker                     # the voice worker (or `pnpm worker:workflow`)
+pnpm worker                     # the voice worker (or `pnpm worker:workflow` / `pnpm worker:regulated`)
 ```
 
 See the example's own [`README.md`](https://github.com/mastra-ai/mastra/tree/main/examples/voice-agent) for the scenario walkthrough and the memory/latency design notes.