@mastra/livekit 0.0.0-buttoned-spandex-20260824090603

package/dist/index.js

@@ -0,0 +1,182 @@
+import { a as DEFAULT_LIVEKIT_AGENT_NAME, i as serializeSessionMetadata, n as pipeAgentReplyToWriter } from "./workflow-generator-BtfClQcM.js";
+import { randomUUID } from "crypto";
+import { RoomAgentDispatch, RoomConfiguration } from "@livekit/protocol";
+import { AccessToken, AgentDispatchClient } from "livekit-server-sdk";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+//#region src/routes.ts
+function stringField(body, key) {
+	const value = body[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/**
+* An ApiRoute for `server.apiRoutes` that mints a LiveKit access token with the Mastra
+* voice agent dispatched into the room. Frontends call it to join a voice session:
+*
+* ```ts
+* export const mastra = new Mastra({
+*   agents: { support },
+*   server: { apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })] },
+* });
+* ```
+*/
+function liveKitConnectionRoute(options = {}) {
+	const handler = async (c) => {
+		const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;
+		const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;
+		const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;
+		if (!serverUrl || !apiKey || !apiSecret) return c.json({ error: "LiveKit is not configured. Set LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET (or pass serverUrl/apiKey/apiSecret to liveKitConnectionRoute)." }, 500);
+		const body = await c.req.json().then((parsed) => parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}).catch(() => ({}));
+		const args = {
+			body,
+			context: c
+		};
+		const metadata = options.metadata ? await options.metadata(args) : {
+			agentId: stringField(body, "agentId"),
+			threadId: stringField(body, "threadId"),
+			resourceId: stringField(body, "resourceId")
+		};
+		const roomName = typeof options.roomName === "function" ? options.roomName(args) : options.roomName ?? `mastra-voice-${randomUUID().slice(0, 8)}`;
+		const identity = typeof options.participantIdentity === "function" ? options.participantIdentity(args) : options.participantIdentity ?? metadata.resourceId ?? `user-${randomUUID().slice(0, 8)}`;
+		metadata.threadId ??= roomName;
+		const token = new AccessToken(apiKey, apiSecret, {
+			identity,
+			ttl: options.ttl ?? "15m"
+		});
+		token.addGrant({
+			room: roomName,
+			roomJoin: true,
+			canPublish: true,
+			canSubscribe: true,
+			canPublishData: true,
+			canUpdateOwnMetadata: true
+		});
+		token.roomConfig = new RoomConfiguration({ agents: [new RoomAgentDispatch({
+			agentName: options.agentName ?? "mastra-voice",
+			metadata: serializeSessionMetadata(metadata)
+		})] });
+		const details = {
+			serverUrl,
+			roomName,
+			participantName: identity,
+			participantToken: await token.toJwt()
+		};
+		return c.json(details);
+	};
+	return {
+		path: options.path ?? "/voice/livekit/connection-details",
+		method: "POST",
+		requiresAuth: options.requiresAuth,
+		handler
+	};
+}
+//#endregion
+//#region src/dispatch.ts
+function toHttpUrl(url) {
+	return url.replace(/^ws/, "http");
+}
+/**
+* Programmatically dispatches a Mastra voice agent into a LiveKit room — for
+* server-initiated sessions such as outbound calls or joining an existing room.
+*/
+async function dispatchVoiceSession(options) {
+	const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;
+	const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;
+	const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;
+	if (!serverUrl) throw new Error("@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.");
+	if (!apiKey || !apiSecret) throw new Error("@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.");
+	return new AgentDispatchClient(toHttpUrl(serverUrl), apiKey, apiSecret).createDispatch(options.roomName, options.agentName ?? "mastra-voice", { metadata: serializeSessionMetadata(options.metadata ?? {}) });
+}
+//#endregion
+//#region src/consent.ts
+const DEFAULT_DESCRIPTION$1 = "Record the caller's consent decision for a data-processing item (for example, storing a summary of the call). Call this as soon as the caller answers a consent question: granted = true if they agree, false if they decline. Do not proceed with an activity that requires consent until you have recorded the caller granting it.";
+/**
+* Builds a Mastra tool that captures the caller's consent decisions at runtime — the companion to
+* the worker's `configuration.consentPolicy`, which only DECLARES which consents a call needs. Add
+* it to the agent that answers the call; on each call the tool reads the caller's `resourceId` /
+* `threadId` from its execution context and hands the decision to your `onGrant` store. The runtime
+* grants live only where `onGrant` put them: enforce consent by reading them back from your own
+* store — at `onCallEnd` or before any consent-gated action — cross-checking against the declared
+* requirements in `VoiceCallEndArgs.configuration.consentPolicy` (the configuration carries the
+* policy, never the grants).
+*
+* ```ts
+* // agent tools
+* recordConsent: createConsentTool({
+*   items: ['summaryStorage'],
+*   onGrant: async ({ item, granted, resourceId }) => {
+*     if (resourceId) await db.saveConsent(resourceId, item, granted);
+*   },
+* }),
+* ```
+*/
+function createConsentTool(options) {
+	const items = options.items;
+	const itemSchema = items && items.length > 0 ? z.enum([...items]) : z.string();
+	return createTool({
+		id: options.id ?? "recordConsent",
+		description: options.description ?? DEFAULT_DESCRIPTION$1,
+		inputSchema: z.object({
+			item: itemSchema.describe("The consent item the caller is answering for (matches the deployment's required consents)."),
+			granted: z.boolean().describe("True if the caller agreed, false if they declined.")
+		}),
+		execute: async ({ item, granted }, { agent }) => {
+			await options.onGrant({
+				item,
+				granted,
+				resourceId: agent?.resourceId,
+				threadId: agent?.threadId
+			});
+			return {
+				recorded: true,
+				item,
+				granted
+			};
+		}
+	});
+}
+//#endregion
+//#region src/end-call.ts
+const DEFAULT_DESCRIPTION = "End the phone call. Call this only after you have said goodbye and there is nothing left to do — for example the caller says goodbye, or the task is complete and you have wrapped up. Say your closing line first, then call this as your final action; the call hangs up once your words finish playing. Your closing line must be a final statement, never a question — if you are asking the caller anything (for example whether they need anything else), do NOT call this in that reply; wait for their answer. Do not call it if the caller still needs something.";
+/**
+* Builds a Mastra tool the agent calls to end the call itself (say goodbye → hang up). It is the
+* agent-visible half of agent-initiated hang-up: the tool only SIGNALS intent (and runs optional
+* bookkeeping) — it can't reach the LiveKit room from inside `agent.stream()`. The worker owns the
+* hang-up: with `configuration.endCall` set, it watches each turn for this tool, waits for the
+* agent's closing words to finish playing, then disconnects (running `onCallEnd` on the way out).
+* Keeping the tool inside the single agent means it stays visible/editable in Studio and works on
+* the agent and workflow reply paths alike.
+*
+* ```ts
+* // agent tools
+* endCall: createEndCallTool({
+*   onEndCall: ({ reason, resourceId }) => log.info('agent ended call', { reason, resourceId }),
+* }),
+* // worker
+* createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } });
+* ```
+*/
+function createEndCallTool(options = {}) {
+	return createTool({
+		id: options.id ?? "endCall",
+		description: options.description ?? DEFAULT_DESCRIPTION,
+		inputSchema: z.object({ reason: z.string().nullish().describe("Short reason the call is ending, e.g. \"caller said goodbye\" or \"task complete\".") }),
+		outputSchema: z.object({ ended: z.boolean() }),
+		execute: async ({ reason }, { agent }) => {
+			try {
+				await options.onEndCall?.({
+					reason: reason ?? void 0,
+					resourceId: agent?.resourceId,
+					threadId: agent?.threadId
+				});
+			} catch (error) {
+				console.warn("@mastra/livekit: onEndCall hook threw", error);
+			}
+			return { ended: true };
+		}
+	});
+}
+//#endregion
+export { DEFAULT_LIVEKIT_AGENT_NAME, createConsentTool, createEndCallTool, dispatchVoiceSession, liveKitConnectionRoute, pipeAgentReplyToWriter, serializeSessionMetadata };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["DEFAULT_DESCRIPTION"],"sources":["../src/routes.ts","../src/dispatch.ts","../src/consent.ts","../src/end-call.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport { RoomAgentDispatch, RoomConfiguration } from '@livekit/protocol';\nimport type { ContextWithMastra, ApiRoute } from '@mastra/core/server';\nimport { AccessToken } from 'livekit-server-sdk';\nimport { DEFAULT_LIVEKIT_AGENT_NAME } from './constants';\nimport { serializeSessionMetadata } from './metadata';\nimport type { LiveKitSessionMetadata } from './metadata';\n\n/** Response body of the connection-details route. Matches LiveKit's frontend starter contract. */\nexport interface LiveKitConnectionDetails {\n  serverUrl: string;\n  roomName: string;\n  participantName: string;\n  participantToken: string;\n}\n\nexport interface ConnectionRequestArgs {\n  body: Record<string, unknown>;\n  context: ContextWithMastra;\n}\n\nexport interface LiveKitConnectionRouteOptions {\n  /**\n   * Route path. Defaults to `/voice/livekit/connection-details`. Mastra reserves the\n   * `/api` prefix for built-in routes, so custom paths must not start with `/api`.\n   */\n  path?: string;\n  /** LiveKit server URL (`wss://...`). Defaults to `LIVEKIT_URL`. */\n  serverUrl?: string;\n  /** Defaults to `LIVEKIT_API_KEY`. */\n  apiKey?: string;\n  /** Defaults to `LIVEKIT_API_SECRET`. */\n  apiSecret?: string;\n  /** LiveKit agent name for explicit dispatch. Must match the worker's `agentName`. */\n  agentName?: string;\n  /** Token time-to-live. Defaults to `'15m'`. */\n  ttl?: string | number;\n  /** Defaults to `true` (Mastra custom routes require auth unless opted out). */\n  requiresAuth?: boolean;\n  roomName?: string | ((args: ConnectionRequestArgs) => string);\n  participantIdentity?: string | ((args: ConnectionRequestArgs) => string);\n  /**\n   * Session metadata delivered to the worker via agent dispatch. Defaults to passing\n   * through `agentId`, `threadId`, and `resourceId` from the request body.\n   */\n  metadata?: (args: ConnectionRequestArgs) => LiveKitSessionMetadata | Promise<LiveKitSessionMetadata>;\n}\n\nfunction stringField(body: Record<string, unknown>, key: string): string | undefined {\n  const value = body[key];\n  return typeof value === 'string' && value.length > 0 ? value : undefined;\n}\n\n/**\n * An ApiRoute for `server.apiRoutes` that mints a LiveKit access token with the Mastra\n * voice agent dispatched into the room. Frontends call it to join a voice session:\n *\n * ```ts\n * export const mastra = new Mastra({\n *   agents: { support },\n *   server: { apiRoutes: [liveKitConnectionRoute({ agentName: 'mastra-voice' })] },\n * });\n * ```\n */\nexport function liveKitConnectionRoute(options: LiveKitConnectionRouteOptions = {}): ApiRoute {\n  const handler = async (c: ContextWithMastra) => {\n    const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;\n    const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;\n    const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;\n    if (!serverUrl || !apiKey || !apiSecret) {\n      return c.json(\n        {\n          error:\n            'LiveKit is not configured. Set LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET ' +\n            '(or pass serverUrl/apiKey/apiSecret to liveKitConnectionRoute).',\n        },\n        500,\n      );\n    }\n\n    const body: Record<string, unknown> = await c.req\n      .json()\n      .then((parsed: unknown) =>\n        parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {},\n      )\n      .catch(() => ({}));\n    const args: ConnectionRequestArgs = { body, context: c };\n\n    const metadata: LiveKitSessionMetadata = options.metadata\n      ? await options.metadata(args)\n      : {\n          agentId: stringField(body, 'agentId'),\n          threadId: stringField(body, 'threadId'),\n          resourceId: stringField(body, 'resourceId'),\n        };\n\n    const roomName =\n      typeof options.roomName === 'function'\n        ? options.roomName(args)\n        : (options.roomName ?? `mastra-voice-${randomUUID().slice(0, 8)}`);\n    const identity =\n      typeof options.participantIdentity === 'function'\n        ? options.participantIdentity(args)\n        : (options.participantIdentity ?? metadata.resourceId ?? `user-${randomUUID().slice(0, 8)}`);\n    // One memory thread per room unless the caller pins a thread explicitly.\n    metadata.threadId ??= roomName;\n\n    const token = new AccessToken(apiKey, apiSecret, { identity, ttl: options.ttl ?? '15m' });\n    token.addGrant({\n      room: roomName,\n      roomJoin: true,\n      canPublish: true,\n      canSubscribe: true,\n      canPublishData: true,\n      canUpdateOwnMetadata: true,\n    });\n    token.roomConfig = new RoomConfiguration({\n      agents: [\n        new RoomAgentDispatch({\n          agentName: options.agentName ?? DEFAULT_LIVEKIT_AGENT_NAME,\n          metadata: serializeSessionMetadata(metadata),\n        }),\n      ],\n    });\n\n    const details: LiveKitConnectionDetails = {\n      serverUrl,\n      roomName,\n      participantName: identity,\n      participantToken: await token.toJwt(),\n    };\n    return c.json(details);\n  };\n\n  return {\n    path: options.path ?? '/voice/livekit/connection-details',\n    method: 'POST',\n    requiresAuth: options.requiresAuth,\n    handler,\n  } as ApiRoute;\n}\n","import { AgentDispatchClient } from 'livekit-server-sdk';\nimport { DEFAULT_LIVEKIT_AGENT_NAME } from './constants';\nimport { serializeSessionMetadata } from './metadata';\nimport type { LiveKitSessionMetadata } from './metadata';\n\nexport interface DispatchVoiceSessionOptions {\n  /** Room to dispatch the agent into (created on demand). */\n  roomName: string;\n  /** Must match the worker's `agentName`. Defaults to `'mastra-voice'`. */\n  agentName?: string;\n  metadata?: LiveKitSessionMetadata;\n  /** Defaults to `LIVEKIT_URL`. */\n  serverUrl?: string;\n  /** Defaults to `LIVEKIT_API_KEY`. */\n  apiKey?: string;\n  /** Defaults to `LIVEKIT_API_SECRET`. */\n  apiSecret?: string;\n}\n\nfunction toHttpUrl(url: string): string {\n  return url.replace(/^ws/, 'http');\n}\n\n/**\n * Programmatically dispatches a Mastra voice agent into a LiveKit room — for\n * server-initiated sessions such as outbound calls or joining an existing room.\n */\nexport async function dispatchVoiceSession(options: DispatchVoiceSessionOptions) {\n  const serverUrl = options.serverUrl ?? process.env.LIVEKIT_URL;\n  const apiKey = options.apiKey ?? process.env.LIVEKIT_API_KEY;\n  const apiSecret = options.apiSecret ?? process.env.LIVEKIT_API_SECRET;\n  if (!serverUrl) {\n    throw new Error('@mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispatchVoiceSession.');\n  }\n  if (!apiKey || !apiSecret) {\n    throw new Error(\n      '@mastra/livekit: set LIVEKIT_API_KEY and LIVEKIT_API_SECRET or pass apiKey/apiSecret to dispatchVoiceSession.',\n    );\n  }\n  const client = new AgentDispatchClient(toHttpUrl(serverUrl), apiKey, apiSecret);\n  return client.createDispatch(options.roomName, options.agentName ?? DEFAULT_LIVEKIT_AGENT_NAME, {\n    metadata: serializeSessionMetadata(options.metadata ?? {}),\n  });\n}\n","// Server-safe: only depends on `@mastra/core` + zod, never the `@livekit/agents` runtime — so it\n// can be added to agents defined in server/shared code and re-exported from the root entry\n// (`index.ts`). `index.test.ts` enforces that boundary.\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\n/** A consent decision captured from the caller during a call. */\nexport interface ConsentGrant {\n  /**\n   * The consent item, matching a key in the worker's `configuration.consentPolicy` (e.g.\n   * `'summaryStorage'`).\n   */\n  item: string;\n  /** `true` if the caller agreed, `false` if they declined. */\n  granted: boolean;\n  /** The caller the grant belongs to (the memory `resource`), when the call is memory-scoped. */\n  resourceId?: string;\n  /** The call thread the grant was captured on, when the call is memory-scoped. */\n  threadId?: string;\n}\n\nexport interface ConsentToolOptions {\n  /**\n   * Persist the caller's decision to YOUR system of record (database, CRM, consent ledger). Called\n   * each time the caller answers a consent question — keep it quick, it runs inside the turn. This\n   * tool owns extracting the caller's identity from the tool execution context; you own storage, so\n   * consent lives in a durable, compliant place rather than an opaque plugin store. Read those\n   * grants back at `onCallEnd` (or before any consent-gated step) to enforce the requirement.\n   */\n  onGrant: (grant: ConsentGrant) => void | Promise<void>;\n  /** Tool id the agent calls. Defaults to `'recordConsent'`. */\n  id?: string;\n  /** Override the description the model sees when deciding to call the tool. */\n  description?: string;\n  /** Restrict the accepted consent items to this set (becomes an enum). Defaults to any string. */\n  items?: readonly string[];\n}\n\nconst DEFAULT_DESCRIPTION =\n  \"Record the caller's consent decision for a data-processing item (for example, storing a summary \" +\n  'of the call). Call this as soon as the caller answers a consent question: granted = true if they ' +\n  'agree, false if they decline. Do not proceed with an activity that requires consent until you ' +\n  'have recorded the caller granting it.';\n\n/**\n * Builds a Mastra tool that captures the caller's consent decisions at runtime — the companion to\n * the worker's `configuration.consentPolicy`, which only DECLARES which consents a call needs. Add\n * it to the agent that answers the call; on each call the tool reads the caller's `resourceId` /\n * `threadId` from its execution context and hands the decision to your `onGrant` store. The runtime\n * grants live only where `onGrant` put them: enforce consent by reading them back from your own\n * store — at `onCallEnd` or before any consent-gated action — cross-checking against the declared\n * requirements in `VoiceCallEndArgs.configuration.consentPolicy` (the configuration carries the\n * policy, never the grants).\n *\n * ```ts\n * // agent tools\n * recordConsent: createConsentTool({\n *   items: ['summaryStorage'],\n *   onGrant: async ({ item, granted, resourceId }) => {\n *     if (resourceId) await db.saveConsent(resourceId, item, granted);\n *   },\n * }),\n * ```\n */\nexport function createConsentTool(options: ConsentToolOptions) {\n  const items = options.items;\n  const itemSchema = items && items.length > 0 ? z.enum([...items] as [string, ...string[]]) : z.string();\n  return createTool({\n    id: options.id ?? 'recordConsent',\n    description: options.description ?? DEFAULT_DESCRIPTION,\n    inputSchema: z.object({\n      item: itemSchema.describe(\n        \"The consent item the caller is answering for (matches the deployment's required consents).\",\n      ),\n      granted: z.boolean().describe('True if the caller agreed, false if they declined.'),\n    }),\n    execute: async ({ item, granted }, { agent }) => {\n      await options.onGrant({ item, granted, resourceId: agent?.resourceId, threadId: agent?.threadId });\n      return { recorded: true as const, item, granted };\n    },\n  });\n}\n","// Server-safe: only depends on `@mastra/core` + zod, never the `@livekit/agents` runtime — so it\n// can be added to agents defined in server/shared code and re-exported from the root entry\n// (`index.ts`). `index.test.ts` enforces that boundary.\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\n/** Details of the agent's decision to end the call, handed to {@link EndCallToolOptions.onEndCall}. */\nexport interface EndCallRequest {\n  /** Short reason the agent gave for ending the call, if any (e.g. \"caller said goodbye\"). */\n  reason?: string;\n  /** The caller the call belongs to (the memory `resource`), when the call is memory-scoped. */\n  resourceId?: string;\n  /** The call thread, when the call is memory-scoped. */\n  threadId?: string;\n}\n\nexport interface EndCallToolOptions {\n  /**\n   * Tool id the agent calls to end the call. Must match the worker's\n   * `configuration.endCall.tool` (both default to `'endCall'`), since that's the name the worker\n   * watches for to hang up.\n   */\n  id?: string;\n  /** Override the description the model sees when deciding to call the tool. */\n  description?: string;\n  /**\n   * Optional bookkeeping hook, called when the agent invokes the tool (records the reason, marks\n   * the call resolved in your CRM, …). Runs inside the turn — keep it quick. It does NOT hang up\n   * the call; the worker does that once the agent's final words finish playing. The tool reads the\n   * caller's identity from its execution context and passes it here.\n   */\n  onEndCall?: (request: EndCallRequest) => void | Promise<void>;\n}\n\nconst DEFAULT_DESCRIPTION =\n  'End the phone call. Call this only after you have said goodbye and there is nothing left to do — ' +\n  'for example the caller says goodbye, or the task is complete and you have wrapped up. Say your ' +\n  'closing line first, then call this as your final action; the call hangs up once your words finish ' +\n  'playing. Your closing line must be a final statement, never a question — if you are asking the ' +\n  'caller anything (for example whether they need anything else), do NOT call this in that reply; ' +\n  'wait for their answer. Do not call it if the caller still needs something.';\n\n/**\n * Builds a Mastra tool the agent calls to end the call itself (say goodbye → hang up). It is the\n * agent-visible half of agent-initiated hang-up: the tool only SIGNALS intent (and runs optional\n * bookkeeping) — it can't reach the LiveKit room from inside `agent.stream()`. The worker owns the\n * hang-up: with `configuration.endCall` set, it watches each turn for this tool, waits for the\n * agent's closing words to finish playing, then disconnects (running `onCallEnd` on the way out).\n * Keeping the tool inside the single agent means it stays visible/editable in Studio and works on\n * the agent and workflow reply paths alike.\n *\n * ```ts\n * // agent tools\n * endCall: createEndCallTool({\n *   onEndCall: ({ reason, resourceId }) => log.info('agent ended call', { reason, resourceId }),\n * }),\n * // worker\n * createLiveKitWorker({ mastra, agent: 'support', configuration: { endCall: {} } });\n * ```\n */\nexport function createEndCallTool(options: EndCallToolOptions = {}) {\n  return createTool({\n    id: options.id ?? 'endCall',\n    description: options.description ?? DEFAULT_DESCRIPTION,\n    inputSchema: z.object({\n      reason: z\n        .string()\n        .nullish()\n        .describe('Short reason the call is ending, e.g. \"caller said goodbye\" or \"task complete\".'),\n    }),\n    outputSchema: z.object({ ended: z.boolean() }),\n    execute: async ({ reason }, { agent }) => {\n      try {\n        await options.onEndCall?.({\n          reason: reason ?? undefined,\n          resourceId: agent?.resourceId,\n          threadId: agent?.threadId,\n        });\n      } catch (error) {\n        // Bookkeeping is best-effort — the tool must still signal `{ ended: true }` so the worker's\n        // end-call detector runs and the call actually hangs up.\n        console.warn('@mastra/livekit: onEndCall hook threw', error);\n      }\n      return { ended: true as const };\n    },\n  });\n}\n"],"mappings":";;;;;;;AAgDA,SAAS,YAAY,MAA+B,KAAiC;CACnF,MAAM,QAAQ,KAAK;CACnB,OAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ,KAAA;AACjE;;;;;;;;;;;;AAaA,SAAgB,uBAAuB,UAAyC,CAAC,GAAa;CAC5F,MAAM,UAAU,OAAO,MAAyB;EAC9C,MAAM,YAAY,QAAQ,aAAa,QAAQ,IAAI;EACnD,MAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI;EAC7C,MAAM,YAAY,QAAQ,aAAa,QAAQ,IAAI;EACnD,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,WAC5B,OAAO,EAAE,KACP,EACE,OACE,sJAEJ,GACA,GACF;EAGF,MAAM,OAAgC,MAAM,EAAE,IAC3C,KAAK,CAAC,CACN,MAAM,WACL,UAAU,OAAO,WAAW,YAAY,CAAC,MAAM,QAAQ,MAAM,IAAK,SAAqC,CAAC,CAC1G,CAAC,CACA,aAAa,CAAC,EAAE;EACnB,MAAM,OAA8B;GAAE;GAAM,SAAS;EAAE;EAEvD,MAAM,WAAmC,QAAQ,WAC7C,MAAM,QAAQ,SAAS,IAAI,IAC3B;GACE,SAAS,YAAY,MAAM,SAAS;GACpC,UAAU,YAAY,MAAM,UAAU;GACtC,YAAY,YAAY,MAAM,YAAY;EAC5C;EAEJ,MAAM,WACJ,OAAO,QAAQ,aAAa,aACxB,QAAQ,SAAS,IAAI,IACpB,QAAQ,YAAY,gBAAgB,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;EAClE,MAAM,WACJ,OAAO,QAAQ,wBAAwB,aACnC,QAAQ,oBAAoB,IAAI,IAC/B,QAAQ,uBAAuB,SAAS,cAAc,QAAQ,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;EAE5F,SAAS,aAAa;EAEtB,MAAM,QAAQ,IAAI,YAAY,QAAQ,WAAW;GAAE;GAAU,KAAK,QAAQ,OAAO;EAAM,CAAC;EACxF,MAAM,SAAS;GACb,MAAM;GACN,UAAU;GACV,YAAY;GACZ,cAAc;GACd,gBAAgB;GAChB,sBAAsB;EACxB,CAAC;EACD,MAAM,aAAa,IAAI,kBAAkB,EACvC,QAAQ,CACN,IAAI,kBAAkB;GACpB,WAAW,QAAQ,aAAA;GACnB,UAAU,yBAAyB,QAAQ;EAC7C,CAAC,CACH,EACF,CAAC;EAED,MAAM,UAAoC;GACxC;GACA;GACA,iBAAiB;GACjB,kBAAkB,MAAM,MAAM,MAAM;EACtC;EACA,OAAO,EAAE,KAAK,OAAO;CACvB;CAEA,OAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,QAAQ;EACR,cAAc,QAAQ;EACtB;CACF;AACF;;;ACzHA,SAAS,UAAU,KAAqB;CACtC,OAAO,IAAI,QAAQ,OAAO,MAAM;AAClC;;;;;AAMA,eAAsB,qBAAqB,SAAsC;CAC/E,MAAM,YAAY,QAAQ,aAAa,QAAQ,IAAI;CACnD,MAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI;CAC7C,MAAM,YAAY,QAAQ,aAAa,QAAQ,IAAI;CACnD,IAAI,CAAC,WACH,MAAM,IAAI,MAAM,6EAA6E;CAE/F,IAAI,CAAC,UAAU,CAAC,WACd,MAAM,IAAI,MACR,+GACF;CAGF,OAAO,IADY,oBAAoB,UAAU,SAAS,GAAG,QAAQ,SACzD,CAAC,CAAC,eAAe,QAAQ,UAAU,QAAQ,aAAA,gBAAyC,EAC9F,UAAU,yBAAyB,QAAQ,YAAY,CAAC,CAAC,EAC3D,CAAC;AACH;;;ACLA,MAAMA,wBACJ;;;;;;;;;;;;;;;;;;;;;AAyBF,SAAgB,kBAAkB,SAA6B;CAC7D,MAAM,QAAQ,QAAQ;CACtB,MAAM,aAAa,SAAS,MAAM,SAAS,IAAI,EAAE,KAAK,CAAC,GAAG,KAAK,CAA0B,IAAI,EAAE,OAAO;CACtG,OAAO,WAAW;EAChB,IAAI,QAAQ,MAAM;EAClB,aAAa,QAAQ,eAAeA;EACpC,aAAa,EAAE,OAAO;GACpB,MAAM,WAAW,SACf,4FACF;GACA,SAAS,EAAE,QAAQ,CAAC,CAAC,SAAS,oDAAoD;EACpF,CAAC;EACD,SAAS,OAAO,EAAE,MAAM,WAAW,EAAE,YAAY;GAC/C,MAAM,QAAQ,QAAQ;IAAE;IAAM;IAAS,YAAY,OAAO;IAAY,UAAU,OAAO;GAAS,CAAC;GACjG,OAAO;IAAE,UAAU;IAAe;IAAM;GAAQ;EAClD;CACF,CAAC;AACH;;;AC/CA,MAAM,sBACJ;;;;;;;;;;;;;;;;;;;AAyBF,SAAgB,kBAAkB,UAA8B,CAAC,GAAG;CAClE,OAAO,WAAW;EAChB,IAAI,QAAQ,MAAM;EAClB,aAAa,QAAQ,eAAe;EACpC,aAAa,EAAE,OAAO,EACpB,QAAQ,EACL,OAAO,CAAC,CACR,QAAQ,CAAC,CACT,SAAS,qFAAiF,EAC/F,CAAC;EACD,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;EAC7C,SAAS,OAAO,EAAE,UAAU,EAAE,YAAY;GACxC,IAAI;IACF,MAAM,QAAQ,YAAY;KACxB,QAAQ,UAAU,KAAA;KAClB,YAAY,OAAO;KACnB,UAAU,OAAO;IACnB,CAAC;GACH,SAAS,OAAO;IAGd,QAAQ,KAAK,yCAAyC,KAAK;GAC7D;GACA,OAAO,EAAE,OAAO,KAAc;EAChC;CACF,CAAC;AACH"}

package/dist/llm-plugin.d.ts

@@ -0,0 +1,112 @@
+import { llm } from '@livekit/agents';
+import type { APIConnectOptions } from '@livekit/agents';
+import type { Agent as MastraAgent } from '@mastra/core/agent';
+import { RequestContext } from '@mastra/core/request-context';
+import type { MastraVoiceAgentMemory, VoiceReplyGenerator, VoiceToolCall, VoiceTurnCompleteHook } from './bridge.js';
+import type { RemoteMastraAgentOptions } from './remote.js';
+export type { RemoteMastraAgentOptions } from './remote.js';
+/**
+ * Options for {@link MastraLLM}. Provide **exactly one** reply source — `remote` (the headline: a
+ * Mastra app on a remote server), `agent` (an in-process Mastra agent), or `generate` (a custom
+ * {@link VoiceReplyGenerator}). The `toolFeedback` / `onToolCall` / `onTurnComplete` hooks apply to
+ * the `remote` and `agent` sources; a `generate` source owns its own hooks.
+ */
+export interface MastraLLMOptions {
+    /** Remote Mastra server. Provide exactly one of `remote`, `agent`, `generate`. */
+    remote?: RemoteMastraAgentOptions;
+    /** In-process Mastra agent (reuses `createAgentReplyGenerator`). */
+    agent?: MastraAgent;
+    /** Custom reply source (escape hatch; owns its own tool-feedback / turn-complete behavior). */
+    generate?: VoiceReplyGenerator;
+    /**
+     * Conversation persistence, resolved by the customer per call (from SIP/caller identity). When set,
+     * only messages new since the agent last spoke are sent each turn and Mastra Memory supplies
+     * history. When omitted/false, the full LiveKit chat context is sent every turn.
+     *
+     * NOTE: incompatible with the session's `preemptiveGeneration` option — a speculative turn that
+     * completes before being discarded pollutes the thread. Leave preemptive generation off when
+     * using `memory`.
+     *
+     * The plugin cannot detect the combination at runtime, so this stays a documented constraint
+     * rather than a warning: the LLM interface never receives the session (so the option can't be
+     * read), a preemptive `chat()` is shape-identical to a real turn (LiveKit drives the same
+     * `generateReply` with a draft transcript and no marker), and the observable signature — a
+     * cancelled stream followed by a `chat()` whose trailing user message changed — is exactly what
+     * an ordinary barge-in correction looks like, so a heuristic would warn on every barge-in.
+     */
+    memory?: MastraVoiceAgentMemory | false;
+    /** Request context forwarded to generation (tenant, dialed number, ...). */
+    requestContext?: RequestContext | Record<string, unknown>;
+    /** Speak a short filler while a (server-side) tool runs. Applies to the `remote`/`agent` sources. */
+    toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;
+    /** Notified as each tool-call chunk arrives, mid-stream. Applies to the `remote`/`agent` sources. */
+    onToolCall?: (toolCall: VoiceToolCall) => void;
+    /** Fired off the audio path after each reply finishes. Applies to the `remote`/`agent` sources. */
+    onTurnComplete?: VoiceTurnCompleteHook;
+}
+/**
+ * A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Drop it into the `llm` slot of a
+ * customer-owned `voice.AgentSession` and the Mastra app (agent loop, tools, memory, observability)
+ * runs wherever it's deployed — most importantly on a **remote** Mastra server reached over HTTP.
+ *
+ * Tools are defined and executed **server-side** on the Mastra agent; LiveKit-side `toolCtx` is
+ * ignored (with a one-time warning). Tool activity surfaces via `toolFeedback` (spoken) and
+ * `onToolCall` / `onTurnComplete` (programmatic). `voice.Agent` instructions do **not** reach the
+ * Mastra agent — put instructions on the Mastra agent instead.
+ *
+ * @example
+ * ```ts
+ * const session = new voice.AgentSession({
+ *   stt: 'deepgram/nova-3',
+ *   tts: 'cartesia/sonic-3',
+ *   llm: new MastraLLM({
+ *     remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'callCenter' },
+ *     memory: { thread: callId, resource: callerId },
+ *   }),
+ * });
+ * ```
+ */
+export declare class MastraLLM extends llm.LLM {
+    #private;
+    constructor(options: MastraLLMOptions);
+    label(): string;
+    get model(): string;
+    get provider(): string;
+    /**
+     * Resolves the reply generator for a turn. Non-remote sources are built once; the remote transport
+     * is built per turn so its connect + first-token timeout can come from the session's
+     * `connOptions.timeoutMs`, with base-class retries owning retry (transport `retries: 0`).
+     */
+    private resolveGenerator;
+    chat({ chatCtx, toolCtx, connOptions, }: {
+        chatCtx: llm.ChatContext;
+        toolCtx?: llm.ToolContext;
+        connOptions?: APIConnectOptions;
+        parallelToolCalls?: boolean;
+        toolChoice?: llm.ToolChoice;
+        extraKwargs?: Record<string, unknown>;
+    }): llm.LLMStream;
+    /** No-op in v1: nothing in the LiveKit session/worker ever calls `prewarm()` automatically. */
+    prewarm(): void;
+}
+interface MastraLLMStreamOptions {
+    chatCtx: llm.ChatContext;
+    toolCtx?: llm.ToolContext;
+    connOptions: APIConnectOptions;
+    generator: VoiceReplyGenerator;
+    memory: MastraVoiceAgentMemory | false;
+    requestContext?: RequestContext;
+}
+/**
+ * The `llm.LLMStream` `MastraLLM` returns per turn. `run()` extracts the turn's messages, drives
+ * the reply generator, and pushes assistant `ChatChunk`s into `this.queue` (NOT `this.output` — the
+ * base class drains queue → output and computes TTFT / duration / usage). Barge-in aborts via
+ * `this.abortController` and `run()` returns silently.
+ */
+declare class MastraLLMStream extends llm.LLMStream {
+    #private;
+    constructor(mastraLLM: MastraLLM, options: MastraLLMStreamOptions);
+    protected run(): Promise<void>;
+}
+export { MastraLLMStream };
+//# sourceMappingURL=llm-plugin.d.ts.map

package/dist/llm-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-plugin.d.ts","sourceRoot":"","sources":["../src/llm-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,GAAG,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EAGtB,MAAM,UAAU,CAAC;AAGlB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAEzD,YAAY,EAAE,wBAAwB,EAAE,MAAM,UAAU,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,oEAAoE;IACpE,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAE/B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,sBAAsB,GAAG,KAAK,CAAC;IACxC,4EAA4E;IAC5E,cAAc,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE1D,qGAAqG;IACrG,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACtE,qGAAqG;IACrG,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,mGAAmG;IACnG,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACxC;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,SAAU,SAAQ,GAAG,CAAC,GAAG;;gBAaxB,OAAO,EAAE,gBAAgB;IAuCrC,KAAK,IAAI,MAAM;IAIf,IAAa,KAAK,IAAI,MAAM,CAE3B;IAED,IAAa,QAAQ,IAAI,MAAM,CAE9B;IAED;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAUf,IAAI,CAAC,EACZ,OAAO,EACP,OAAO,EACP,WAAyC,GAC1C,EAAE;QACD,OAAO,EAAE,GAAG,CAAC,WAAW,CAAC;QACzB,OAAO,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC;QAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAC;QAChC,iBAAiB,CAAC,EAAE,OAAO,CAAC;QAC5B,UAAU,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC;QAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvC,GAAG,GAAG,CAAC,SAAS;IAsBjB,+FAA+F;IACtF,OAAO,IAAI,IAAI;CACzB;AAED,UAAU,sBAAsB;IAC9B,OAAO,EAAE,GAAG,CAAC,WAAW,CAAC;IACzB,OAAO,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC;IAC1B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,MAAM,EAAE,sBAAsB,GAAG,KAAK,CAAC;IACvC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;GAKG;AACH,cAAM,eAAgB,SAAQ,GAAG,CAAC,SAAS;;gBAK7B,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,sBAAsB;cAOjD,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAgDrC;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,50 @@
+import type { llm } from '@livekit/agents';
+/**
+ * Fixed id LiveKit gives the customer Agent's instructions when it injects them as a leading
+ * `role: 'system'` message into the chat context passed to `chat()` / `llmNode`. We drop this
+ * item so the server-side Mastra agent's own system prompt is authoritative.
+ */
+export declare const LIVEKIT_INSTRUCTIONS_MESSAGE_ID = "lk.agent_task.instructions";
+/**
+ * A message bound for `agent.stream(...)` (in-process) or the Mastra server stream route (remote).
+ * `id` carries the LiveKit `ChatMessage.id` so the server can dedupe/upsert by id — making
+ * base-class retries, preemptive double-sends, and the interrupted-turn reconciliation recipe idempotent.
+ */
+export type VoiceTurnMessage = {
+    role: 'system';
+    content: string;
+    id?: string;
+} | {
+    role: 'user';
+    content: string;
+    id?: string;
+} | {
+    role: 'assistant';
+    content: string;
+    id?: string;
+};
+/**
+ * Extracts only the messages added since the agent last spoke. Used when Mastra Memory is
+ * the source of truth for conversation history: prior turns are already persisted in the
+ * thread, so re-sending them would duplicate history.
+ *
+ * Two extensions over the naive "slice after the last assistant message":
+ *
+ * - **Interrupted-turn self-heal:** when the last assistant message was cut off by barge-in
+ *   (`interrupted: true`), the server never persisted it — aborted runs skip persistence — so
+ *   its heard-only text is missing from the thread. Re-send that fragment (ordered first) this
+ *   turn to backfill it. It stops being "the last assistant message" once a full reply lands,
+ *   so each interrupted fragment is sent exactly once, on the following turn.
+ * - **Instructions filter:** LiveKit injects the customer Agent's `instructions` as a
+ *   leading `system` message ({@link LIVEKIT_INSTRUCTIONS_MESSAGE_ID}); the server-side Mastra
+ *   agent owns its own system prompt, so drop it (it would otherwise ship on the first turn,
+ *   before any assistant message).
+ */
+export declare function extractNewTurnMessages(chatCtx: llm.ChatContext): VoiceTurnMessage[];
+/**
+ * Converts the full LiveKit chat context to Mastra messages. Used when the bridge runs
+ * without Mastra Memory and LiveKit's in-session context is the only history. The agent's
+ * LiveKit-level instructions are excluded — the Mastra agent applies its own instructions.
+ */
+export declare function chatContextToMessages(chatCtx: llm.ChatContext): VoiceTurnMessage[];
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AA2BxD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,GAAG,CAAC,WAAW,GAAG,gBAAgB,EAAE,CAuBnF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,GAAG,CAAC,WAAW,GAAG,gBAAgB,EAAE,CAQlF"}

package/dist/metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Session metadata passed from the Mastra server to the LiveKit agent worker through
+ * LiveKit's job dispatch metadata (a plain string, so this is JSON-serialized).
+ */
+export interface LiveKitSessionMetadata {
+    /** Mastra agent to run, by registered key or agent id. */
+    agentId?: string;
+    /** Memory thread id. Defaults to the LiveKit room name when omitted. */
+    threadId?: string;
+    /** Memory resource id (typically the end user id). */
+    resourceId?: string;
+    /** Plain-object entries restored into a RequestContext for agent execution. */
+    requestContext?: Record<string, unknown>;
+}
+export declare function parseSessionMetadata(raw: string | undefined | null): LiveKitSessionMetadata;
+export declare function serializeSessionMetadata(metadata: LiveKitSessionMetadata): string;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,sBAAsB,CAW3F;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAEjF"}

package/dist/observability.d.ts

@@ -0,0 +1,46 @@
+import { voice } from '@livekit/agents';
+import type { Mastra } from '@mastra/core/mastra';
+import { SpanType } from '@mastra/core/observability';
+import type { Span, TracingContext } from '@mastra/core/observability';
+import type { RequestContext } from '@mastra/core/request-context';
+import type { LiveKitSessionMetadata } from './metadata.js';
+export interface VoiceCallObservabilityOptions {
+    /** The Mastra instance whose observability config receives the spans. */
+    mastra: Mastra;
+    /** Resolved Mastra agent id/key answering the call (for span attribution). */
+    agentId: string;
+    /** LiveKit room name for this session. */
+    roomName: string;
+    /** Dispatch metadata for the session. */
+    metadata: LiveKitSessionMetadata;
+    /** Request context forwarded to span sampling. */
+    requestContext?: RequestContext;
+}
+export interface VoiceCallObservability {
+    /** The root `voice call` span. Each turn's agent run and every pipeline metric nests under it. */
+    readonly span: Span<SpanType.GENERIC>;
+    /** Thread into the bridge's `streamOptions` so each turn's agent run nests under the call. */
+    readonly tracingContext: TracingContext;
+    /** Subscribe to the session's `metrics_collected` events. Call once, before `session.start()`. */
+    attach(session: voice.AgentSession): void;
+    /** Close the call span with the usage roll-up. Idempotent; safe to call from a shutdown hook. */
+    finalize(options?: {
+        error?: unknown;
+    }): void;
+}
+/**
+ * Opens a `voice call` trace for one LiveKit session and bridges LiveKit's voice-pipeline
+ * metrics into Mastra observability.
+ *
+ * The returned root span groups everything about the call: each conversation turn's Mastra
+ * agent run (nested via {@link VoiceCallObservability.tracingContext}) plus an event span for
+ * every STT, TTS, end-of-utterance, VAD, and LLM-latency metric LiveKit emits. Metrics are
+ * point-in-time, so they're recorded as event spans (no duration) with the value in the name.
+ * The root closes on the session `close` event with a per-model usage roll-up (token, character,
+ * and audio totals for the whole call) from a `ModelUsageCollector`.
+ *
+ * Returns `undefined` when the Mastra instance has no observability configured, so callers
+ * can treat instrumentation as a no-op without branching on config.
+ */
+export declare function startVoiceCallObservability(options: VoiceCallObservabilityOptions): VoiceCallObservability | undefined;
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAmB,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,kDAAkD;IAClD,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,kGAAkG;IAClG,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;IAC1C,iGAAiG;IACjG,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/C;AAgGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,6BAA6B,GACrC,sBAAsB,GAAG,SAAS,CAsDpC"}