This PR contains the following updates: | Package | Type | Update | Change | Pending | |---|---|---|---|---| | [@better-auth/drizzle-adapter@<1.7.7](https://www.better-auth.com/docs/adapters/drizzle) ([source](https://redirect.github.com/better-auth/better-auth/tree/HEAD/packages/drizzle-adapter)) | pnpm-workspace.overrides | patch | [`1.7.18` → `1.7.22`](https://renovatebot.com/diffs/npm/@better-auth%2fdrizzle-adapter/1.7.18/1.7.22) | `1.7.25` (+2) | | [better-auth](https://better-auth.com) ([source](https://redirect.github.com/better-auth/better-auth/tree/HEAD/packages/better-auth)) | pnpm-workspace.overrides | patch | [`^1.7.18` → `^1.7.22`](https://renovatebot.com/diffs/npm/better-auth/1.7.18/1.7.22) | `1.7.25` (+2) | | [better-auth](https://better-auth.com) ([source](https://redirect.github.com/better-auth/better-auth/tree/HEAD/packages/better-auth)) | dependencies | patch | [`^1.7.18` → `^1.7.22`](https://renovatebot.com/diffs/npm/better-auth/1.7.18/1.7.22) | `1.7.25` (+2) | --- > [!WARNING] > Some dependencies could not be looked up. Check the [Dependency Dashboard](../issues/9505) for more information. --- ### Release Notes <details> <summary>better-auth/better-auth (@​better-auth/drizzle-adapter@<1.7.7)</summary> ### [`v1.7.22`](https://redirect.github.com/better-auth/better-auth/blob/HEAD/packages/drizzle-adapter/CHANGELOG.md#1722) [Compare Source](https://redirect.github.com/better-auth/better-auth/compare/v1.7.21...v1.7.22) ##### Patch Changes - [#​12333](https://redirect.github.com/better-auth/better-auth/pull/12333) [`6536174`]( |
History
|
|
|---|---|---|
| .. | ||
| scripts | ||
| src/mastra | ||
| .env.example | ||
| .gitignore | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| tsconfig.json | ||
Voice agent example — Meridian Trades call center
A call center voice agent for a fictional trades contractor, built with @mastra/livekit. LiveKit runs the audio loop (WebRTC, speech-to-text, semantic turn detection, barge-in, text-to-speech); Mastra generates every reply.
The example ships interchangeable entrypoints, one for each way @mastra/livekit can generate replies:
- Agent worker (
pnpm worker): each turn is answered by a Mastra agent loop — model, tools, and memory. - Workflow worker (
pnpm worker:workflow): each turn is generated by a Mastra workflow that runs once to completion per turn. - Plugin worker (
pnpm worker:plugin): a customer-ownedvoice.AgentSessionwith theMastraLLMplugin in thellmslot, talking to the Mastra server over HTTP — see Plugin worker. - Regulated worker (
pnpm worker:regulated): every compliance control at once, answering with thesuperRegulatedagent.
Run one at a time — all register with LiveKit under the same agent name (mastra-voice by default). Set LIVEKIT_AGENT_NAME to the same value in the server and worker environments to isolate a test deployment from other workers in your LiveKit project.
The demo assistant "Jordan" works the front desk of Meridian Trades, a contractor that sends out tradespeople for plumbing, electrical work, roofing, carpentry, and painting. A site visit is when a tradesperson comes out to assess the job and give a quote. Every call follows one of four paths, which Jordan routes between by listening:
- New lead — qualify the job (trade, property, rough scope) and capture it.
- Roof inspection — collect the property address and zip, then run a service-area check (
checkServiceArea) before promising a visit; out-of-area callers are offered a callback instead. - General callback — take a name, number, and reason.
- Existing customer / scheduling — look the caller up and book, reschedule, or cancel a site visit.
At the end of the call a single deterministic reconciliation pass (finalizeIntake) validates the collected fields for the path, re-checks the service area for inspections, and submits one record with a reference number to read back. Jordan's tools:
lookupCustomer,checkAvailability,bookAppointment,rescheduleAppointment,cancelAppointment— the scheduling "CRM"checkServiceArea— service-area (zip) validation for inspectionsfinalizeIntake— the end-of-call reconciliation that submits lead / inspection / callback records
Why an agent and not a workflow? This mirrors a real customer's scenarios (lead capture, inspection intake with a service-area gate, general callback) using the agent loop as the per-turn engine. Determinism lives in code, not in driving the call as a workflow: tenant context is injected by an input processor (src/mastra/processors/workspace-context.ts, a stand-in for a per-tenant Firebase lookup keyed by the dialed number), the service-area gate and reconciliation are tools backed by a mock backend (src/mastra/backend.ts), and caller state is held in three layers of caller-scoped memory (see Memory and latency) so a returning caller is recognized.
The "CRM" is in-memory and seeded with three customers. Try: Shane Thomas, 555-0142 (has a visit booked already), Sam Bhagwat (555-0177), Abhi Aiyer (555-0163). In-area zips include 94103 and 94110; 90210 is out of area.
Customer lookup results are reused throughout a call. The agent should only retry when the caller supplies new or corrected identifying information, not after an address or ZIP-code update. An unmatched caller is captured as a lead, inspection request, or callback for office follow-up: this demo has no customer-creation tool, so only a matched customer can receive a confirmed booking. The agent finishes necessary tool calls before asking its next question, then waits for the caller.
Agent vs. workflow entrypoint
Both workers wire the same audio pipeline and the same brand; they differ only in how a turn becomes a reply.
The agent worker (src/mastra/voice-worker.ts) passes a Mastra agent to createLiveKitWorker. The agent runs its own loop each turn, calls tools, and persists the conversation to a Mastra memory thread. The worker scopes memory per call — thread is the call, resource is the caller — so memory carries the caller's details across calls: hang up, call back, and Jordan recalls who you are (see Memory and latency). This is the richer, primary path and the one the four scenarios above run on.
The workflow worker (src/mastra/voice-worker-workflow.ts) passes a workflow plus a workflowInput mapper. LiveKit owns the turn boundary, so the phoneConversation workflow (src/mastra/workflows/phone-conversation.ts) runs once to completion per turn — there is no suspend/resume. Each turn it:
- Classifies the caller's intent (
classifyIntentstep, using the smalltriageagent) into a constrained enum —lead,inspection,callback,existing_job, orgeneral. This is the workflow's value over instructions-only routing: an explicit, inspectable step pins the scenario before the reply, instead of the agent discovering it mid-sentence. - Generates the spoken reply (
generateResponsestep) with the fullcallCenteragent and that intent's focus in front. It calls@mastra/livekit'spipeAgentReplyToWriter(stream, writer)helper, which forwards the agent's text deltas (so text-to-speech starts early) and its tool-call chunks (sotoolFeedbackfires and theonTurnCompletetool list is populated) — unlike piping only.textStream, which silently drops tool calls.
The reworked workflow worker is at feature parity with the agent worker. It shares the same callCenterMemory (src/mastra/memory.ts): the worker's memoryInstance bootstraps the call thread and persists the greeting, and the reply step's memory-backed agent.stream(..., { memory }) backfills prior turns from the thread, persists this turn, and engages all three memory layers — so a returning caller is recognized on the workflow path too. The same toolFeedback and post-turn onTurnComplete CRM log run here as well. Conversation state lives in memory (thread = call, resource = caller), not in the workflow, so the workflow stays stateless between turns.
Plugin worker: own the session, keep Mastra's brain
The plugin worker (src/mastra/voice-worker-plugin.ts) inverts the ownership model. The other workers hand the session to createLiveKitWorker and configure it through Mastra options; here the file builds the LiveKit voice.AgentSession itself — every session option, lifecycle hook, and node override belongs to this file — and Mastra occupies only the llm slot:
import { MastraLLM } from '@mastra/livekit/plugin';
const session = new voice.AgentSession({
llm: new MastraLLM({
remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'callCenter' },
memory: { thread, resource },
}),
stt: 'deepgram/nova-3',
tts: 'cartesia/sonic-3',
// ...
});
The Mastra app — agent loop, tools, all three memory layers, observability — runs on the server (pnpm dev), reached over HTTP/SSE. The worker process carries no Mastra app, no database, and no model-provider keys, so it can be deployed anywhere that can reach the server (set MASTRA_URL). Barge-in still aborts the in-flight server generation, and interrupted turns self-heal into the memory thread on the following turn.
Because the customer owns the session, the wrapper's conveniences are rebuilt in a few lines each — which is exactly what this entrypoint demonstrates: the greeting is spoken with speakGreeting (or plain session.say), and agent-initiated hang-up pairs MastraLLM's onToolCall with runEndCall — when the server-side agent calls its endCall tool, the worker waits for the goodbye to finish playing and disconnects. Note the voice.Agent instructions in this file never reach the Mastra agent; the server-side agent's instructions are authoritative.
Memory and latency
The agent (src/mastra/agents/call-center-agent.ts) uses three layers of memory, all scoped to the caller (resource) so they carry across calls:
- Working memory — the structured fields collected during this call (name, number, trade, address, zip, which path it is), so Jordan never asks twice.
- Semantic recall — pulls the most relevant snippets of the caller's prior calls into context. Backed by a
LibSQLVectorindex in the samevoice-agent.dband an embedder. - Observational memory — a background Observer agent distills durable facts about the caller and injects them into later calls.
On a phone call latency is the product, so each layer is tuned for it:
- Recall runs before the reply, so it's kept small. Semantic recall is synchronous — it happens before the model generates — so
topKis3with a tight message range. Every extra hit is time the caller waits through. The embedder is the OpenAI router the agent model already uses (one small, cached call per turn); swap in a local embedder such as@mastra/fastembedto drop that network round-trip. - Observational memory runs inline — so it's kept cheap and flushed at call end. Despite the "background" framing, the OM observer runs as an input-step processor inside the agent loop: it blocks the turn while it distills. Measured on a reasoning model (gpt-5-mini) it stalled a turn ~25s. Two things keep it off the caller's clock: a fast, non-reasoning observer model (
gpt-4.1-mini), and — the real fix — theonCallEndhook, which distills the whole call into durable memory once, after the caller hangs up (flushObservationalMemoryinsrc/mastra/memory.ts), entirely off the audio path. The inlinemessageTokensthreshold is a backstop;observe()still respects it, so the end-of-call flush distills once the call accumulated enough unobserved tokens to be worth it. (Future direction: aforceoption onobserve()would let the flush distill regardless of length, so even a very short call is captured and the inline threshold could be raised high for zero in-call OM cost — see the@mastra/livekitTODO.) - Working-memory writes never touch the audio path. The memory config sets
workingMemory.agentManaged: false, so the main agent gets working memory as read-only context — noupdateWorkingMemorytool is injected at all — andsummarizeCallruns aWorkingMemoryExtractoronce at call end to write the caller's collected fields. Compared to the in-loop tool this removes two failure modes measured on live calls — models re-stating the reply after the tool result (the caller hears the answer twice) and writing memory before replying (seconds of dead air) — and it drops the extra model step from every memory-writing turn. (The fuller form,observationalMemory.observation.manageWorkingMemory: true, also updates the fields whenever the Observer fires mid-call; it currently crashes with resource-scoped working memory — core bug, tracked in the package TODO.) - Everything else post-turn runs off the audio path.
createLiveKitWorkertakes anonTurnCompletehook that fires after the reply has streamed to text-to-speech, fire-and-forget — the worker never awaits it, so it can't add to the caller's latency or delay the next turn. This worker uses it to log every turn to the contact "CRM" (recordContactinsrc/mastra/backend.ts); it's also the right place for a fully-backgroundedmemory.updateWorkingMemory(...). The hook receives the produced reply (result.text,result.toolCalls,result.interrupted) and the call'smemorymapping.
The trade-off: working memory updates on the Observer's cadence (or at call end), not per turn. Mid-call, "never ask twice" is covered by
lastMessageskeeping the whole call in context; working memory's job is carrying the fields to the next call.
Setup
-
Create a free LiveKit Cloud project at cloud.livekit.io, then copy the URL, API key, and secret from Settings → API Keys. The free tier includes inference credit, so the Deepgram/Cartesia model strings work without separate accounts.
-
Copy
.env.exampleto.envand fill in the LiveKit credentials and yourOPENAI_API_KEY. -
Install dependencies (this example links the workspace packages, so build the monorepo packages first if you haven't):
pnpm install pnpm worker:download-files # one-time: downloads the configured worker's model filesUse plain
pnpm install— this example is its own pnpm workspace root. Do not pass--ignore-workspace: that drops the localpnpm-workspace.yamloverrides and installs published Mastra packages from the registry instead of the linked monorepo packages. If that happens, deletenode_modulesandpnpm-lock.yaml, then runpnpm installagain and check the install output shows<- ../../packages/corestyle links.
Run
Three processes. Pick one worker (agent or workflow):
# 1. Mastra server (API on :4111)
pnpm dev
# 2a. Agent worker — answers each turn with the callCenter agent loop
pnpm worker
# …or…
# 2b. Workflow worker — answers each turn with the phoneConversation workflow
pnpm worker:workflow
# …or…
# 2c. Plugin worker — customer-owned session, MastraLLM reaches the server over HTTP
pnpm worker:plugin
# …or…
# 2d. Regulated worker — Northwind Financial demo: consent sweep, agent-initiated hang-up, compliance sign-off
pnpm worker:regulated
# 3. Studio with voice mode (from the monorepo, served on :5173)
pnpm --dir ../.. dev:playground
Or combine 1 and 3 with pnpm dev:ui and run a worker in a second terminal.
Test the call
Open Studio, point it at http://localhost:4111, and open the Meridian Trades Front Desk agent chat. Click the phone button in the composer and allow microphone access. You should hear Jordan's greeting.
Things to try (the four scenarios run on the agent worker):
- Lead: "Hi, I'm after a quote to repaint my hallway and stairs." — Jordan qualifies the trade and scope, then captures the lead and reads back a reference number.
- Roof inspection, in area: "I'd like someone to look at my roof. The address is 12 Market Street, zip nine four one zero three." — Jordan checks the service area and captures an inspection request for office follow-up; a confirmed booking requires an existing customer record.
- Roof inspection, out of area: give zip 90210 instead — Jordan apologizes that it's outside the service area and offers a callback.
- Callback: "Can someone just call me back about a fence?" — Jordan takes a name, number, and reason.
- Returning caller / scheduling: "Hi, it's Shane Thomas, five five five, zero one four two." — account lookup plus scheduling, with filler speech while tools run.
- Pause mid-sentence ("I was wondering if… hmm…") — the semantic turn detector should wait for you to finish.
- Interrupt Jordan while it's speaking — playback stops and it listens (barge-in).
- Hang up, then call again from the same caller: because all three memory layers are scoped to the caller (
resource), Jordan greets you by name and recalls what the earlier call was about (via semantic recall) instead of starting over.
The same calls work against either worker. The agent worker discovers the scenario from its instructions mid-call; the workflow worker classifies the intent in an explicit step first, then replies with the full agent. Both share the same tools, service-area gate, reconciliation, and caller-scoped memory, so cross-call recognition and the post-turn CRM log work on either path.
Record calls (optional)
Recording is disabled by default. To record Meridian calls into one mixed OGG audio file, configure a writable S3 bucket and set these values in .env:
LIVEKIT_RECORDING_ENABLED=true
LIVEKIT_RECORDING_REVIEW_LOCAL_DEMO=true
RECORDINGS_S3_BUCKET=your-recordings-bucket
RECORDINGS_S3_REGION=us-east-1
RECORDINGS_S3_ACCESS_KEY=your-storage-access-key
RECORDINGS_S3_SECRET=your-storage-secret
Use LiveKit Cloud or deploy LiveKit's egress service yourself. Restart the Mastra server after changing .env. The shared server-only configuration in src/mastra/livekit.ts validates the storage settings and saves files under voice-agent/{room_name}.ogg. Always use a unique room name so each call maps to one file. It doesn't change the recording settings inside your LiveKit Cloud project.
For browser calls, start the default worker and open Meridian Trades Front Desk in Studio. The connection route applies recording only when agentId is callCenter or call-center, LIVEKIT_RECORDING_REVIEW_LOCAL_DEMO=true, and NODE_ENV is not production. Without that local-demo opt-in, browser calls remain unrecorded even when LIVEKIT_RECORDING_ENABLED=true. It creates a fresh room, configures recording, and dispatches the agent before returning connection details. Storage credentials aren't included in the participant token or dispatch metadata. The frontend request and response formats stay unchanged.
For a server-initiated session, run:
pnpm recording:dispatch
This calls dispatchVoiceSession({ recording }) with a unique room name and prints the room and dispatch IDs. It doesn't dial anyone. In your phone integration, await this step before adding a SIP participant to that room. The script starts the agent and recording even if no caller joins, so close the test room in LiveKit when finished.
What enabling recording changes
- Recording starts at room creation. Requesting browser connection details starts it, even if the browser never connects. Recording and storage usage can therefore begin before a call is answered.
- Consent tools don't control recording.
createConsentTool()andconfiguration.consentPolicydon't start, pause, or stop egress. This example excludes the regulated agent from automatic recording; keep the flag off when runningworker:regulated. If consent must be obtained during the call before capturing audio, use LiveKit's explicit egress APIs after consent instead of this option. - Every recorded session needs a fresh room. Existing rooms are rejected. Coordinate room creation in your application; the existence check isn't an atomic reservation. Reuse an existing room's join token flow for reconnects, rather than requesting a new recorded session with that name.
- Setup errors stop the request. Missing settings fail before room creation. LiveKit room or dispatch failures prevent the route from issuing a token. A room created before a later failure can remain active; inspect and close failed test rooms rather than retrying the same name.
- A successful dispatch isn't a completed file. Egress follows the room lifecycle and finishes asynchronously. Disconnecting only the agent doesn't prove the recording has ended. Check the
egress_endedevent, a successful egress status, and its file results before offering a recording to an end user. - Audio storage is separate from Mastra memory. Deleting a memory thread or running
pnpm cleandoesn't delete S3 recordings. Your application owns bucket access, retention, and any authenticated download links.
To verify a recording, make a short test call with speech from both sides, end the room, and inspect its egress job in LiveKit. Wait for completion, then download the OGG file from your S3 bucket and listen for both the caller and Jordan. A joined agent, a returned token, or an active egress job alone doesn't verify the final audio file.
See the recording guide for other storage providers and per-session configuration callbacks.
Review a call in Studio
For a browser-call test with real AWS S3 credentials, follow Test recording with AWS S3 below.
For local playback, set LIVEKIT_RECORDING_REVIEW_LOCAL_DEMO=true in .env and restart pnpm dev. The example denies recording access by default; this explicit demo policy permits browser recording and playback of all traces, and disables both when NODE_ENV=production. Recording creation also requires LIVEKIT_RECORDING_ENABLED=true.
Open a voice call trace under Observability → Traces, then select Review Audio in the trace panel. The player supports playback, pause, and seeking. If the upload is still finishing, select Refresh recording when the file is ready. Closing the dialog stops playback; reopening it requests a new link.
The registered liveKitRecordingRoute() reads the room name from the stored trace. src/mastra/recording-playback.ts checks for voice-agent/<room-name>.ogg in S3 and creates a playback URL that expires after 15 minutes. The browser receives the signed URL, never the S3 secret. Historical recordings remain reviewable when LIVEKIT_RECORDING_ENABLED is set back to false, provided the storage settings and objects remain available.
The configured S3 credentials now need s3:GetObject for playback as well as upload permissions. s3:ListBucket allows S3 to report a missing file as 404; without it, missing files may appear as access errors. You can use separate read credentials in the playback resolver. For S3-compatible storage, set RECORDINGS_S3_ENDPOINT to an endpoint reachable by the recording service, the Mastra server, and the browser.
This example disables authentication on both custom routes for local development. Before deployment, restore requiresAuth: true, configure server authentication, and replace the local-demo recording gate with an application policy that limits who can start recordings. Apply per-user rate limits or session quotas. Replace the demo authorize({ traceId, context }) callback with a check of the authenticated user's access to the requested trace. The callback is required even when authentication is disabled. Returning anything other than true denies access before trace lookup or URL signing. Signed URLs grant temporary access to an individual file and must not be logged or stored in trace metadata. Existing timestamped recordings need a room-to-object mapping in the resolver; this example looks up the exact filename shown above.
Test recording with AWS S3
Use a private bucket with Block Public Access enabled. For a production bucket, use a dedicated test credential scoped to voice-agent/. The example passes the upload credential to LiveKit and uses it on the Mastra server to sign playback links. The following same-account identity policy grants access to recording objects without administrator permissions. Replace YOUR_BUCKET_NAME in both resources:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "RecordingObjects",
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload"],
"Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/voice-agent/*"
},
{
"Sid": "RecognizeMissingRecordings",
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
}
]
}
s3:PutObjectlets LiveKit upload the file, including multipart upload parts and completion.s3:GetObjectcovers the server'sHeadObjectcheck and playback through a signed URL.s3:AbortMultipartUploadlets the uploader clean up an unfinished multipart upload.s3:ListBucketlets the existence check distinguish a missing object from denied access. It also permits listing object names in this bucket. Omit it if that access is prohibited; existing files still play, but missing files can show a load error instead of an unavailable message.
This policy doesn't grant deletion. Bucket policies and organization restrictions still apply. A customer-managed KMS key also requires kms:GenerateDataKey for uploads and kms:Decrypt for multipart uploads and playback, with the appropriate key policy. See AWS object permissions, multipart permissions, and KMS permissions.
The example uses an explicit access-key/secret pair. It doesn't read an AWS CLI profile or forward AWS_SESSION_TOKEN. Temporary STS credentials require adding session-token support to both upload and playback configuration before use. Both LiveKit Cloud and the browser must be able to reach S3; a bucket restricted exclusively to a private VPC endpoint won't work with this path.
- Configure the recording variables above in
.env, along with the LiveKit and model credentials from Setup. SetLIVEKIT_AGENT_NAME=mastra-recording-review-testin both server and worker environments. For AWS S3, removeRECORDINGS_S3_ENDPOINTentirely; an empty value fails URL validation, and a leftover local endpoint prevents Cloud uploads. - Start the Mastra server, the default
pnpm worker, and Studio as described in Setup. Use only one worker with this agent name. Keep the unauthenticated demo server local. In Studio, verify that Observability → Traces loads before placing a call. The server and worker must share a trace store that supports Studio's trace queries; use a shared PostgreSQL observability store if your installed LibSQL version doesn't support them. Don't share a DuckDB file between these separate processes. - Open Meridian Trades Front Desk, select the voice control, and allow microphone access. Say “This is recording test alpha” and ask Jordan a question. Let both speakers finish at least one turn. Use fictional details; recording starts before any in-call consent conversation and incurs provider and storage usage.
- Note the room name from the worker or LiveKit room list. End the call and ensure no participants remain in the room. Wait for its egress job to complete successfully in LiveKit, then confirm that
voice-agent/<room-name>.oggexists in S3 and has a nonzero size. - Open the call's voice call trace and confirm that
metadata.roomNamematches the room and object. Select Review Audio and play it. Check both speakers, pause, seeking, and that closing the dialog stops playback. Reopening requests a new signed URL; Refresh recording retries after upload completion or URL expiry. - Make a second call saying “recording test beta”. Its trace must play beta, while reopening the first trace must still play alpha. This verifies the trace-to-room-to-object mapping.
- Set
LIVEKIT_RECORDING_ENABLED=false, restart the server, and make a fresh call. It must not create a new recording. Existing recordings remain reviewable while their objects and storage credentials are available.
For a phone test, dispatch into a fresh room with pnpm recording:dispatch, then use your existing SIP integration to add an authorized test destination to that exact room. Dispatch doesn't dial the phone. After speaking in both directions and ending the room, repeat the egress, S3, and trace playback checks above. Delete test objects according to your bucket's retention process; cleaning the local example database doesn't remove them.
Traces
The example ships with Mastra Observability enabled. Every voice turn the worker handles — the agent run or workflow run, model calls, tool executions — is exported to the shared LibSQL database, so after a call you can open Observability in Studio to inspect the traces. With the workflow worker, each turn's workflow run nests under the same voice call span.
Everything (memory, threads, traces) lives in one voice-agent.db file at the project root. SQLite handles the server and the voice worker writing concurrently; single-writer stores such as DuckDB don't work here because the worker is a separate process.
Troubleshooting
- "LiveKit is not configured" toast in Studio: the Mastra server can't see your
.env— restartpnpm devafter editing it. - Worker connects but never joins a call: the server and worker must use the same
LIVEKIT_AGENT_NAME(defaults tomastra-voice). Make sure only one worker is running for that name. - Recording is enabled but no file appears: check the egress job's final status and error in LiveKit, bucket permissions, and the configured region. A local filepath alone isn't a downloadable recording on LiveKit Cloud.
- Connected but silent: check the worker terminal — STT/TTS model errors (for example, exhausted inference credit) appear there.
- "Required model files not found locally" on worker start: the turn-detection model cache is tied to the installed dependency tree, so reinstalling dependencies can orphan it. Run
pnpm worker:download-filesagain. - "Thread not found" in the server terminal: the database file was recreated while the server or worker was still running — a running process keeps writing to the deleted file while a restarted one opens a fresh empty file, so they silently diverge. This happens when
pnpm clean(which deletes*.db) runs while either process is up. Stop the server and the worker, then clean, then start both together. Conversations from before the clean are gone; start a new chat. - "This storage provider does not support batch creating logs/metrics": a one-time notice that LibSQL doesn't persist observability logs locally. Traces still work; the exporter drops those events after the first attempt.