@mastra/livekit 0.0.0-aggregate-trace-20261015182851

package/dist/plugin-entry.cjs

@@ -0,0 +1,222 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_turn_metrics = require("./turn-metrics-CtVHHdJj.cjs");
+const require_remote = require("./remote-GSOxa--f.cjs");
+let _livekit_agents = require("@livekit/agents");
+let _mastra_core_request_context = require("@mastra/core/request-context");
+//#region src/llm-plugin.ts
+function toRequestContext(value) {
+	if (!value) return void 0;
+	if (value instanceof _mastra_core_request_context.RequestContext) return value;
+	return new _mastra_core_request_context.RequestContext(Object.entries(value));
+}
+function mapUsageToLiveKit(usage) {
+	return {
+		completionTokens: usage.completionTokens,
+		promptTokens: usage.promptTokens,
+		promptCachedTokens: usage.promptCachedTokens,
+		totalTokens: usage.totalTokens
+	};
+}
+/**
+* Tool names carried by a `toolCtx`, across @livekit/agents versions: 1.5+ always passes a
+* `ToolContext` class instance (tools behind getters, `Object.keys` sees only private fields),
+* while 1.4 and the object shorthand pass a plain name→tool map.
+*/
+function livekitToolNames(toolCtx) {
+	const instance = toolCtx;
+	if (typeof instance.flatten === "function") return instance.flatten().map((tool) => {
+		const { id, name } = tool;
+		return id ?? name ?? "unknown";
+	});
+	return Object.keys(toolCtx);
+}
+/**
+* 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 },
+*   }),
+* });
+* ```
+*/
+var MastraLLM = class extends _livekit_agents.llm.LLM {
+	#model;
+	#onTurnMetrics;
+	#memory;
+	#requestContext;
+	/** Non-remote sources are built once; remote is built per turn so it can pick up `connOptions.timeoutMs`. */
+	#staticGenerator;
+	#remoteOptions;
+	#warnedToolCtx = false;
+	constructor(options) {
+		super();
+		this.#onTurnMetrics = options.onTurnMetrics;
+		const sources = [
+			options.remote ? "remote" : void 0,
+			options.agent ? "agent" : void 0,
+			options.generate ? "generate" : void 0
+		].filter(Boolean);
+		if (sources.length !== 1) throw new Error(`@mastra/livekit: MastraLLM requires exactly one reply source — \`remote\`, \`agent\`, or \`generate\` — but got ${sources.length === 0 ? "none" : sources.join(" + ")}.`);
+		this.#memory = options.memory ?? false;
+		this.#requestContext = toRequestContext(options.requestContext);
+		if (options.remote) {
+			this.#model = options.remote.agentId;
+			this.#remoteOptions = {
+				...options.remote,
+				toolFeedback: options.toolFeedback,
+				onToolCall: options.onToolCall,
+				onTurnComplete: options.onTurnComplete
+			};
+		} else if (options.agent) {
+			this.#model = options.agent.id ?? options.agent.name;
+			this.#staticGenerator = require_remote.createAgentReplyGenerator({
+				agent: options.agent,
+				toolFeedback: options.toolFeedback,
+				onToolCall: options.onToolCall,
+				onTurnComplete: options.onTurnComplete
+			});
+		} else {
+			this.#model = "mastra-generator";
+			this.#staticGenerator = options.generate;
+		}
+	}
+	label() {
+		return "mastra.MastraLLM";
+	}
+	get model() {
+		return this.#model;
+	}
+	get provider() {
+		return "mastra";
+	}
+	/**
+	* 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`).
+	*/
+	resolveGenerator(connOptions) {
+		if (this.#staticGenerator) return this.#staticGenerator;
+		const remote = this.#remoteOptions;
+		return require_remote.createRemoteAgentReplyGenerator({
+			...remote,
+			retries: 0,
+			timeoutMs: remote.timeoutMs ?? connOptions.timeoutMs
+		});
+	}
+	chat({ chatCtx, toolCtx, connOptions = _livekit_agents.DEFAULT_API_CONNECT_OPTIONS }) {
+		if (!this.#warnedToolCtx && toolCtx) {
+			const ignored = livekitToolNames(toolCtx);
+			if (ignored.length > 0) {
+				this.#warnedToolCtx = true;
+				console.warn(`@mastra/livekit: MastraLLM ignores LiveKit-side tools (${ignored.join(", ")}). Tools are defined and executed server-side on the Mastra agent — move them there.`);
+			}
+		}
+		return new MastraLLMStream(this, {
+			chatCtx,
+			toolCtx,
+			connOptions,
+			generator: this.resolveGenerator(connOptions),
+			onTurnMetrics: this.#onTurnMetrics,
+			memory: this.#memory,
+			requestContext: this.#requestContext
+		});
+	}
+	/** No-op in v1: nothing in the LiveKit session/worker ever calls `prewarm()` automatically. */
+	prewarm() {}
+};
+/**
+* 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.
+*/
+var MastraLLMStream = class extends _livekit_agents.llm.LLMStream {
+	#generator;
+	#onTurnMetrics;
+	#memory;
+	#requestContext;
+	constructor(mastraLLM, options) {
+		super(mastraLLM, {
+			chatCtx: options.chatCtx,
+			toolCtx: options.toolCtx,
+			connOptions: options.connOptions
+		});
+		this.#generator = options.generator;
+		this.#onTurnMetrics = options.onTurnMetrics;
+		this.#memory = options.memory;
+		this.#requestContext = options.requestContext;
+	}
+	async run() {
+		const messages = this.#memory === false ? require_remote.chatContextToMessages(this.chatCtx) : require_remote.extractNewTurnMessages(this.chatCtx);
+		if (messages.length === 0) return;
+		let usage;
+		const turnCtx = {
+			messages,
+			chatCtx: this.chatCtx,
+			memory: this.#memory,
+			requestContext: this.#requestContext,
+			onUsage: (turnUsage) => {
+				usage = turnUsage;
+			}
+		};
+		const { reply, identity } = await require_remote.instrumentVoiceReply(this.#generator, turnCtx, this.#onTurnMetrics);
+		if (!reply) return;
+		if (this.abortController.signal.aborted) {
+			await reply.cancel().catch(() => {});
+			return;
+		}
+		const id = identity.attemptId;
+		const reader = reply.getReader();
+		const onAbort = () => void reader.cancel().catch(() => {});
+		this.abortController.signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (this.abortController.signal.aborted) break;
+				if (value) this.queue.put({
+					id,
+					delta: {
+						role: "assistant",
+						...typeof value === "string" ? { content: value } : {},
+						extra: {
+							[require_turn_metrics.VOICE_TURN_METADATA]: identity,
+							[require_turn_metrics.VOICE_FLUSH_METADATA]: typeof value !== "string"
+						}
+					}
+				});
+			}
+		} catch (error) {
+			if (this.abortController.signal.aborted) return;
+			throw error;
+		} finally {
+			this.abortController.signal.removeEventListener("abort", onAbort);
+		}
+		if (this.abortController.signal.aborted) return;
+		if (usage) this.queue.put({
+			id,
+			usage: mapUsageToLiveKit(usage)
+		});
+	}
+};
+//#endregion
+exports.MastraLLM = MastraLLM;
+exports.VOICE_TEXT_FLUSH = require_turn_metrics.VOICE_TEXT_FLUSH;
+exports.createRemoteAgentReplyGenerator = require_remote.createRemoteAgentReplyGenerator;
+exports.mastraLLMNode = require_remote.mastraLLMNode;
+exports.observeVoiceSession = require_remote.observeVoiceSession;
+
+//# sourceMappingURL=plugin-entry.cjs.map

package/dist/plugin-entry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-entry.cjs","names":["RequestContext","llm","#model","#onTurnMetrics","#memory","#requestContext","#staticGenerator","#remoteOptions","createAgentReplyGenerator","createRemoteAgentReplyGenerator","DEFAULT_API_CONNECT_OPTIONS","#warnedToolCtx","#generator","chatContextToMessages","extractNewTurnMessages","instrumentVoiceReply","VOICE_TURN_METADATA","VOICE_FLUSH_METADATA"],"sources":["../src/llm-plugin.ts"],"sourcesContent":["import { DEFAULT_API_CONNECT_OPTIONS, llm } from '@livekit/agents';\nimport type { APIConnectOptions } from '@livekit/agents';\nimport type { Agent as MastraAgent } from '@mastra/core/agent';\nimport { RequestContext } from '@mastra/core/request-context';\nimport { createAgentReplyGenerator, instrumentVoiceReply } from './bridge';\nimport type {\n  MastraVoiceAgentMemory,\n  VoiceReplyGenerator,\n  VoiceToolCall,\n  VoiceTurnCompleteHook,\n  VoiceTurnContext,\n  VoiceTurnUsage,\n} from './bridge';\nimport { chatContextToMessages, extractNewTurnMessages } from './messages';\nimport { createRemoteAgentReplyGenerator } from './remote';\nimport type { RemoteMastraAgentOptions } from './remote';\nimport type { VoiceTurnMetricsHook } from './turn-metrics';\nimport { VOICE_FLUSH_METADATA, VOICE_TURN_METADATA } from './turn-metrics';\n\nexport type { RemoteMastraAgentOptions } from './remote';\n\n/**\n * Options for {@link MastraLLM}. Provide **exactly one** reply source — `remote` (the headline: a\n * Mastra app on a remote server), `agent` (an in-process Mastra agent), or `generate` (a custom\n * {@link VoiceReplyGenerator}). The `toolFeedback` / `onToolCall` / `onTurnComplete` hooks apply to\n * the `remote` and `agent` sources; a `generate` source owns its own hooks.\n */\nexport interface MastraLLMOptions {\n  /** Per-attempt metrics; use observeVoiceSession for playback metrics. */\n  onTurnMetrics?: VoiceTurnMetricsHook;\n  /** Remote Mastra server. Provide exactly one of `remote`, `agent`, `generate`. */\n  remote?: RemoteMastraAgentOptions;\n  /** In-process Mastra agent (reuses `createAgentReplyGenerator`). */\n  agent?: MastraAgent;\n  /** Custom reply source (escape hatch; owns its own tool-feedback / turn-complete behavior). */\n  generate?: VoiceReplyGenerator;\n\n  /**\n   * Conversation persistence, resolved by the customer per call (from SIP/caller identity). When set,\n   * only messages new since the agent last spoke are sent each turn and Mastra Memory supplies\n   * history. When omitted/false, the full LiveKit chat context is sent every turn.\n   *\n   * NOTE: incompatible with the session's `preemptiveGeneration` option — a speculative turn\n   * persists a partial user message and a partial reply before being discarded. Leave preemptive\n   * generation off when using `memory`, or set `memory.options.readOnly` and persist committed\n   * turns yourself from the session's conversation-item events.\n   *\n   * The plugin cannot detect the combination at runtime, so this stays a documented constraint\n   * rather than a warning: the LLM interface never receives the session (so the option can't be\n   * read), a preemptive `chat()` is shape-identical to a real turn (LiveKit drives the same\n   * `generateReply` with a draft transcript and no marker), and the observable signature — a\n   * cancelled stream followed by a `chat()` whose trailing user message changed — is exactly what\n   * an ordinary barge-in correction looks like, so a heuristic would warn on every barge-in.\n   */\n  memory?: MastraVoiceAgentMemory | false;\n  /** Request context forwarded to generation (tenant, dialed number, ...). */\n  requestContext?: RequestContext | Record<string, unknown>;\n\n  /** Speak a short filler while a (server-side) tool runs. Applies to the `remote`/`agent` sources. */\n  toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;\n  /** Notified as each tool-call chunk arrives, mid-stream. Applies to the `remote`/`agent` sources. */\n  onToolCall?: (toolCall: VoiceToolCall) => void;\n  /** Fired off the audio path after each reply finishes. Applies to the `remote`/`agent` sources. */\n  onTurnComplete?: VoiceTurnCompleteHook;\n}\n\nfunction toRequestContext(value: RequestContext | Record<string, unknown> | undefined): RequestContext | undefined {\n  if (!value) return undefined;\n  if (value instanceof RequestContext) return value;\n  return new RequestContext<unknown>(Object.entries(value));\n}\n\nfunction mapUsageToLiveKit(usage: VoiceTurnUsage): llm.CompletionUsage {\n  return {\n    completionTokens: usage.completionTokens,\n    promptTokens: usage.promptTokens,\n    promptCachedTokens: usage.promptCachedTokens,\n    totalTokens: usage.totalTokens,\n  };\n}\n\n/**\n * Tool names carried by a `toolCtx`, across @livekit/agents versions: 1.5+ always passes a\n * `ToolContext` class instance (tools behind getters, `Object.keys` sees only private fields),\n * while 1.4 and the object shorthand pass a plain name→tool map.\n */\nfunction livekitToolNames(toolCtx: object): string[] {\n  const instance = toolCtx as { flatten?: unknown };\n  if (typeof instance.flatten === 'function') {\n    return (instance.flatten as () => object[])().map(tool => {\n      const { id, name } = tool as { id?: string; name?: string };\n      return id ?? name ?? 'unknown';\n    });\n  }\n  return Object.keys(toolCtx);\n}\n\n/**\n * A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Drop it into the `llm` slot of a\n * customer-owned `voice.AgentSession` and the Mastra app (agent loop, tools, memory, observability)\n * runs wherever it's deployed — most importantly on a **remote** Mastra server reached over HTTP.\n *\n * Tools are defined and executed **server-side** on the Mastra agent; LiveKit-side `toolCtx` is\n * ignored (with a one-time warning). Tool activity surfaces via `toolFeedback` (spoken) and\n * `onToolCall` / `onTurnComplete` (programmatic). `voice.Agent` instructions do **not** reach the\n * Mastra agent — put instructions on the Mastra agent instead.\n *\n * @example\n * ```ts\n * const session = new voice.AgentSession({\n *   stt: 'deepgram/nova-3',\n *   tts: 'cartesia/sonic-3',\n *   llm: new MastraLLM({\n *     remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'callCenter' },\n *     memory: { thread: callId, resource: callerId },\n *   }),\n * });\n * ```\n */\nexport class MastraLLM extends llm.LLM {\n  readonly #model: string;\n  readonly #onTurnMetrics?: VoiceTurnMetricsHook;\n  readonly #memory: MastraVoiceAgentMemory | false;\n  readonly #requestContext?: RequestContext;\n  /** Non-remote sources are built once; remote is built per turn so it can pick up `connOptions.timeoutMs`. */\n  readonly #staticGenerator?: VoiceReplyGenerator;\n  readonly #remoteOptions?: RemoteMastraAgentOptions & {\n    toolFeedback?: MastraLLMOptions['toolFeedback'];\n    onToolCall?: MastraLLMOptions['onToolCall'];\n    onTurnComplete?: VoiceTurnCompleteHook;\n  };\n  #warnedToolCtx = false;\n\n  constructor(options: MastraLLMOptions) {\n    super();\n    this.#onTurnMetrics = options.onTurnMetrics;\n    const sources = [\n      options.remote ? 'remote' : undefined,\n      options.agent ? 'agent' : undefined,\n      options.generate ? 'generate' : undefined,\n    ].filter(Boolean) as string[];\n    if (sources.length !== 1) {\n      throw new Error(\n        `@mastra/livekit: MastraLLM requires exactly one reply source — \\`remote\\`, \\`agent\\`, or \\`generate\\` — ` +\n          `but got ${sources.length === 0 ? 'none' : sources.join(' + ')}.`,\n      );\n    }\n\n    this.#memory = options.memory ?? false;\n    this.#requestContext = toRequestContext(options.requestContext);\n\n    if (options.remote) {\n      this.#model = options.remote.agentId;\n      this.#remoteOptions = {\n        ...options.remote,\n        toolFeedback: options.toolFeedback,\n        onToolCall: options.onToolCall,\n        onTurnComplete: options.onTurnComplete,\n      };\n    } else if (options.agent) {\n      this.#model = options.agent.id ?? options.agent.name;\n      this.#staticGenerator = createAgentReplyGenerator({\n        agent: options.agent,\n        toolFeedback: options.toolFeedback,\n        onToolCall: options.onToolCall,\n        onTurnComplete: options.onTurnComplete,\n      });\n    } else {\n      this.#model = 'mastra-generator';\n      this.#staticGenerator = options.generate;\n    }\n  }\n\n  label(): string {\n    return 'mastra.MastraLLM';\n  }\n\n  override get model(): string {\n    return this.#model;\n  }\n\n  override get provider(): string {\n    return 'mastra';\n  }\n\n  /**\n   * Resolves the reply generator for a turn. Non-remote sources are built once; the remote transport\n   * is built per turn so its connect + first-token timeout can come from the session's\n   * `connOptions.timeoutMs`, with base-class retries owning retry (transport `retries: 0`).\n   */\n  private resolveGenerator(connOptions: APIConnectOptions): VoiceReplyGenerator {\n    if (this.#staticGenerator) return this.#staticGenerator;\n    const remote = this.#remoteOptions!;\n    return createRemoteAgentReplyGenerator({\n      ...remote,\n      retries: 0,\n      timeoutMs: remote.timeoutMs ?? connOptions.timeoutMs,\n    });\n  }\n\n  override chat({\n    chatCtx,\n    toolCtx,\n    connOptions = DEFAULT_API_CONNECT_OPTIONS,\n  }: {\n    chatCtx: llm.ChatContext;\n    toolCtx?: llm.ToolContext;\n    connOptions?: APIConnectOptions;\n    parallelToolCalls?: boolean;\n    toolChoice?: llm.ToolChoice;\n    extraKwargs?: Record<string, unknown>;\n  }): llm.LLMStream {\n    // Tools run server-side; warn once if the customer wired LiveKit-side tools.\n    if (!this.#warnedToolCtx && toolCtx) {\n      const ignored = livekitToolNames(toolCtx);\n      if (ignored.length > 0) {\n        this.#warnedToolCtx = true;\n        console.warn(\n          `@mastra/livekit: MastraLLM ignores LiveKit-side tools (${ignored.join(', ')}). ` +\n            `Tools are defined and executed server-side on the Mastra agent — move them there.`,\n        );\n      }\n    }\n    return new MastraLLMStream(this, {\n      chatCtx,\n      toolCtx,\n      connOptions,\n      generator: this.resolveGenerator(connOptions),\n      onTurnMetrics: this.#onTurnMetrics,\n      memory: this.#memory,\n      requestContext: this.#requestContext,\n    });\n  }\n\n  /** No-op in v1: nothing in the LiveKit session/worker ever calls `prewarm()` automatically. */\n  override prewarm(): void {}\n}\n\ninterface MastraLLMStreamOptions {\n  onTurnMetrics?: VoiceTurnMetricsHook;\n  chatCtx: llm.ChatContext;\n  toolCtx?: llm.ToolContext;\n  connOptions: APIConnectOptions;\n  generator: VoiceReplyGenerator;\n  memory: MastraVoiceAgentMemory | false;\n  requestContext?: RequestContext;\n}\n\n/**\n * The `llm.LLMStream` `MastraLLM` returns per turn. `run()` extracts the turn's messages, drives\n * the reply generator, and pushes assistant `ChatChunk`s into `this.queue` (NOT `this.output` — the\n * base class drains queue → output and computes TTFT / duration / usage). Barge-in aborts via\n * `this.abortController` and `run()` returns silently.\n */\nclass MastraLLMStream extends llm.LLMStream {\n  readonly #generator: VoiceReplyGenerator;\n  readonly #onTurnMetrics?: VoiceTurnMetricsHook;\n  readonly #memory: MastraVoiceAgentMemory | false;\n  readonly #requestContext?: RequestContext;\n\n  constructor(mastraLLM: MastraLLM, options: MastraLLMStreamOptions) {\n    super(mastraLLM, { chatCtx: options.chatCtx, toolCtx: options.toolCtx, connOptions: options.connOptions });\n    this.#generator = options.generator;\n    this.#onTurnMetrics = options.onTurnMetrics;\n    this.#memory = options.memory;\n    this.#requestContext = options.requestContext;\n  }\n\n  protected async run(): Promise<void> {\n    const messages =\n      this.#memory === false ? chatContextToMessages(this.chatCtx) : extractNewTurnMessages(this.chatCtx);\n    // No new input to answer → close without a request (equivalent to the wrapper returning null).\n    if (messages.length === 0) return;\n\n    let usage: VoiceTurnUsage | undefined;\n    const turnCtx: VoiceTurnContext = {\n      messages,\n      chatCtx: this.chatCtx,\n      memory: this.#memory,\n      requestContext: this.#requestContext,\n      onUsage: turnUsage => {\n        usage = turnUsage;\n      },\n    };\n\n    const { reply, identity } = await instrumentVoiceReply(this.#generator, turnCtx, this.#onTurnMetrics);\n    if (!reply) return;\n    if (this.abortController.signal.aborted) {\n      await reply.cancel().catch(() => {});\n      return;\n    }\n\n    // A single provider response id ties all of this turn's chunks together for the base class metrics.\n    const id = identity.attemptId;\n    const reader = reply.getReader();\n    const onAbort = () => void reader.cancel().catch(() => {});\n    this.abortController.signal.addEventListener('abort', onAbort, { once: true });\n    try {\n      for (;;) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        if (this.abortController.signal.aborted) break;\n        if (value)\n          this.queue.put({\n            id,\n            delta: {\n              role: 'assistant',\n              ...(typeof value === 'string' ? { content: value } : {}),\n              extra: { [VOICE_TURN_METADATA]: identity, [VOICE_FLUSH_METADATA]: typeof value !== 'string' },\n            },\n          });\n      }\n    } catch (error) {\n      // Barge-in tears down the reply stream; that surfaces as a read rejection but is not a failure.\n      if (this.abortController.signal.aborted) return;\n      throw error;\n    } finally {\n      this.abortController.signal.removeEventListener('abort', onAbort);\n    }\n    // Return silently on barge-in — throwing would feed the base class's error/retry machinery.\n    if (this.abortController.signal.aborted) return;\n    // Final usage-only chunk → the base class reads usage from the last chunk that carries it.\n    if (usage) this.queue.put({ id, usage: mapUsageToLiveKit(usage) });\n  }\n}\n\nexport { MastraLLMStream };\n"],"mappings":"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"}

package/dist/plugin-entry.d.ts

@@ -0,0 +1,10 @@
+export { MastraLLM } from './llm-plugin.js';
+export type { MastraLLMOptions } from './llm-plugin.js';
+export { createRemoteAgentReplyGenerator } from './remote.js';
+export type { RemoteMastraAgentOptions, RemoteAgentReplyGeneratorOptions } from './remote.js';
+export type { MastraVoiceAgentMemory, VoiceReplyGenerator, VoiceToolCall, VoiceTurnCompleteContext, VoiceTurnCompleteHook, VoiceTurnContext, VoiceTurnResult, VoiceTurnUsage, } from './bridge.js';
+export { observeVoiceSession, mastraLLMNode } from './speech.js';
+export type { ObserveVoiceSessionOptions } from './speech.js';
+export { VOICE_TEXT_FLUSH } from './turn-metrics.js';
+export type { VoiceReplyChunk, VoiceOutcome, VoiceTurnIdentity, VoiceToolTiming, VoiceGenerationMetrics, VoiceSpeechMetrics, VoiceTurnMetrics, VoiceTurnMetricsHook, VoiceSpeechResult, VoiceSpeechCompleteHook, } from './turn-metrics.js';
+//# sourceMappingURL=plugin-entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-entry.d.ts","sourceRoot":"","sources":["../src/plugin-entry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,gCAAgC,EAAE,MAAM,UAAU,CAAC;AAC3F,YAAY,EACV,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC"}

package/dist/plugin-entry.js

@@ -0,0 +1,217 @@
+import { n as VOICE_TEXT_FLUSH, r as VOICE_TURN_METADATA, t as VOICE_FLUSH_METADATA } from "./turn-metrics-CqqzdLDe.js";
+import { a as createAgentReplyGenerator, c as chatContextToMessages, l as extractNewTurnMessages, n as mastraLLMNode, r as observeVoiceSession, s as instrumentVoiceReply, t as createRemoteAgentReplyGenerator } from "./remote-CIMCGicy.js";
+import { DEFAULT_API_CONNECT_OPTIONS, llm } from "@livekit/agents";
+import { RequestContext } from "@mastra/core/request-context";
+//#region src/llm-plugin.ts
+function toRequestContext(value) {
+	if (!value) return void 0;
+	if (value instanceof RequestContext) return value;
+	return new RequestContext(Object.entries(value));
+}
+function mapUsageToLiveKit(usage) {
+	return {
+		completionTokens: usage.completionTokens,
+		promptTokens: usage.promptTokens,
+		promptCachedTokens: usage.promptCachedTokens,
+		totalTokens: usage.totalTokens
+	};
+}
+/**
+* Tool names carried by a `toolCtx`, across @livekit/agents versions: 1.5+ always passes a
+* `ToolContext` class instance (tools behind getters, `Object.keys` sees only private fields),
+* while 1.4 and the object shorthand pass a plain name→tool map.
+*/
+function livekitToolNames(toolCtx) {
+	const instance = toolCtx;
+	if (typeof instance.flatten === "function") return instance.flatten().map((tool) => {
+		const { id, name } = tool;
+		return id ?? name ?? "unknown";
+	});
+	return Object.keys(toolCtx);
+}
+/**
+* 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 },
+*   }),
+* });
+* ```
+*/
+var MastraLLM = class extends llm.LLM {
+	#model;
+	#onTurnMetrics;
+	#memory;
+	#requestContext;
+	/** Non-remote sources are built once; remote is built per turn so it can pick up `connOptions.timeoutMs`. */
+	#staticGenerator;
+	#remoteOptions;
+	#warnedToolCtx = false;
+	constructor(options) {
+		super();
+		this.#onTurnMetrics = options.onTurnMetrics;
+		const sources = [
+			options.remote ? "remote" : void 0,
+			options.agent ? "agent" : void 0,
+			options.generate ? "generate" : void 0
+		].filter(Boolean);
+		if (sources.length !== 1) throw new Error(`@mastra/livekit: MastraLLM requires exactly one reply source — \`remote\`, \`agent\`, or \`generate\` — but got ${sources.length === 0 ? "none" : sources.join(" + ")}.`);
+		this.#memory = options.memory ?? false;
+		this.#requestContext = toRequestContext(options.requestContext);
+		if (options.remote) {
+			this.#model = options.remote.agentId;
+			this.#remoteOptions = {
+				...options.remote,
+				toolFeedback: options.toolFeedback,
+				onToolCall: options.onToolCall,
+				onTurnComplete: options.onTurnComplete
+			};
+		} else if (options.agent) {
+			this.#model = options.agent.id ?? options.agent.name;
+			this.#staticGenerator = createAgentReplyGenerator({
+				agent: options.agent,
+				toolFeedback: options.toolFeedback,
+				onToolCall: options.onToolCall,
+				onTurnComplete: options.onTurnComplete
+			});
+		} else {
+			this.#model = "mastra-generator";
+			this.#staticGenerator = options.generate;
+		}
+	}
+	label() {
+		return "mastra.MastraLLM";
+	}
+	get model() {
+		return this.#model;
+	}
+	get provider() {
+		return "mastra";
+	}
+	/**
+	* 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`).
+	*/
+	resolveGenerator(connOptions) {
+		if (this.#staticGenerator) return this.#staticGenerator;
+		const remote = this.#remoteOptions;
+		return createRemoteAgentReplyGenerator({
+			...remote,
+			retries: 0,
+			timeoutMs: remote.timeoutMs ?? connOptions.timeoutMs
+		});
+	}
+	chat({ chatCtx, toolCtx, connOptions = DEFAULT_API_CONNECT_OPTIONS }) {
+		if (!this.#warnedToolCtx && toolCtx) {
+			const ignored = livekitToolNames(toolCtx);
+			if (ignored.length > 0) {
+				this.#warnedToolCtx = true;
+				console.warn(`@mastra/livekit: MastraLLM ignores LiveKit-side tools (${ignored.join(", ")}). Tools are defined and executed server-side on the Mastra agent — move them there.`);
+			}
+		}
+		return new MastraLLMStream(this, {
+			chatCtx,
+			toolCtx,
+			connOptions,
+			generator: this.resolveGenerator(connOptions),
+			onTurnMetrics: this.#onTurnMetrics,
+			memory: this.#memory,
+			requestContext: this.#requestContext
+		});
+	}
+	/** No-op in v1: nothing in the LiveKit session/worker ever calls `prewarm()` automatically. */
+	prewarm() {}
+};
+/**
+* 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.
+*/
+var MastraLLMStream = class extends llm.LLMStream {
+	#generator;
+	#onTurnMetrics;
+	#memory;
+	#requestContext;
+	constructor(mastraLLM, options) {
+		super(mastraLLM, {
+			chatCtx: options.chatCtx,
+			toolCtx: options.toolCtx,
+			connOptions: options.connOptions
+		});
+		this.#generator = options.generator;
+		this.#onTurnMetrics = options.onTurnMetrics;
+		this.#memory = options.memory;
+		this.#requestContext = options.requestContext;
+	}
+	async run() {
+		const messages = this.#memory === false ? chatContextToMessages(this.chatCtx) : extractNewTurnMessages(this.chatCtx);
+		if (messages.length === 0) return;
+		let usage;
+		const turnCtx = {
+			messages,
+			chatCtx: this.chatCtx,
+			memory: this.#memory,
+			requestContext: this.#requestContext,
+			onUsage: (turnUsage) => {
+				usage = turnUsage;
+			}
+		};
+		const { reply, identity } = await instrumentVoiceReply(this.#generator, turnCtx, this.#onTurnMetrics);
+		if (!reply) return;
+		if (this.abortController.signal.aborted) {
+			await reply.cancel().catch(() => {});
+			return;
+		}
+		const id = identity.attemptId;
+		const reader = reply.getReader();
+		const onAbort = () => void reader.cancel().catch(() => {});
+		this.abortController.signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				if (this.abortController.signal.aborted) break;
+				if (value) this.queue.put({
+					id,
+					delta: {
+						role: "assistant",
+						...typeof value === "string" ? { content: value } : {},
+						extra: {
+							[VOICE_TURN_METADATA]: identity,
+							[VOICE_FLUSH_METADATA]: typeof value !== "string"
+						}
+					}
+				});
+			}
+		} catch (error) {
+			if (this.abortController.signal.aborted) return;
+			throw error;
+		} finally {
+			this.abortController.signal.removeEventListener("abort", onAbort);
+		}
+		if (this.abortController.signal.aborted) return;
+		if (usage) this.queue.put({
+			id,
+			usage: mapUsageToLiveKit(usage)
+		});
+	}
+};
+//#endregion
+export { MastraLLM, VOICE_TEXT_FLUSH, createRemoteAgentReplyGenerator, mastraLLMNode, observeVoiceSession };
+
+//# sourceMappingURL=plugin-entry.js.map

package/dist/plugin-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-entry.js","names":["#model","#onTurnMetrics","#memory","#requestContext","#staticGenerator","#remoteOptions","#warnedToolCtx","#generator"],"sources":["../src/llm-plugin.ts"],"sourcesContent":["import { DEFAULT_API_CONNECT_OPTIONS, llm } from '@livekit/agents';\nimport type { APIConnectOptions } from '@livekit/agents';\nimport type { Agent as MastraAgent } from '@mastra/core/agent';\nimport { RequestContext } from '@mastra/core/request-context';\nimport { createAgentReplyGenerator, instrumentVoiceReply } from './bridge';\nimport type {\n  MastraVoiceAgentMemory,\n  VoiceReplyGenerator,\n  VoiceToolCall,\n  VoiceTurnCompleteHook,\n  VoiceTurnContext,\n  VoiceTurnUsage,\n} from './bridge';\nimport { chatContextToMessages, extractNewTurnMessages } from './messages';\nimport { createRemoteAgentReplyGenerator } from './remote';\nimport type { RemoteMastraAgentOptions } from './remote';\nimport type { VoiceTurnMetricsHook } from './turn-metrics';\nimport { VOICE_FLUSH_METADATA, VOICE_TURN_METADATA } from './turn-metrics';\n\nexport type { RemoteMastraAgentOptions } from './remote';\n\n/**\n * Options for {@link MastraLLM}. Provide **exactly one** reply source — `remote` (the headline: a\n * Mastra app on a remote server), `agent` (an in-process Mastra agent), or `generate` (a custom\n * {@link VoiceReplyGenerator}). The `toolFeedback` / `onToolCall` / `onTurnComplete` hooks apply to\n * the `remote` and `agent` sources; a `generate` source owns its own hooks.\n */\nexport interface MastraLLMOptions {\n  /** Per-attempt metrics; use observeVoiceSession for playback metrics. */\n  onTurnMetrics?: VoiceTurnMetricsHook;\n  /** Remote Mastra server. Provide exactly one of `remote`, `agent`, `generate`. */\n  remote?: RemoteMastraAgentOptions;\n  /** In-process Mastra agent (reuses `createAgentReplyGenerator`). */\n  agent?: MastraAgent;\n  /** Custom reply source (escape hatch; owns its own tool-feedback / turn-complete behavior). */\n  generate?: VoiceReplyGenerator;\n\n  /**\n   * Conversation persistence, resolved by the customer per call (from SIP/caller identity). When set,\n   * only messages new since the agent last spoke are sent each turn and Mastra Memory supplies\n   * history. When omitted/false, the full LiveKit chat context is sent every turn.\n   *\n   * NOTE: incompatible with the session's `preemptiveGeneration` option — a speculative turn\n   * persists a partial user message and a partial reply before being discarded. Leave preemptive\n   * generation off when using `memory`, or set `memory.options.readOnly` and persist committed\n   * turns yourself from the session's conversation-item events.\n   *\n   * The plugin cannot detect the combination at runtime, so this stays a documented constraint\n   * rather than a warning: the LLM interface never receives the session (so the option can't be\n   * read), a preemptive `chat()` is shape-identical to a real turn (LiveKit drives the same\n   * `generateReply` with a draft transcript and no marker), and the observable signature — a\n   * cancelled stream followed by a `chat()` whose trailing user message changed — is exactly what\n   * an ordinary barge-in correction looks like, so a heuristic would warn on every barge-in.\n   */\n  memory?: MastraVoiceAgentMemory | false;\n  /** Request context forwarded to generation (tenant, dialed number, ...). */\n  requestContext?: RequestContext | Record<string, unknown>;\n\n  /** Speak a short filler while a (server-side) tool runs. Applies to the `remote`/`agent` sources. */\n  toolFeedback?: (toolCall: VoiceToolCall) => string | undefined | void;\n  /** Notified as each tool-call chunk arrives, mid-stream. Applies to the `remote`/`agent` sources. */\n  onToolCall?: (toolCall: VoiceToolCall) => void;\n  /** Fired off the audio path after each reply finishes. Applies to the `remote`/`agent` sources. */\n  onTurnComplete?: VoiceTurnCompleteHook;\n}\n\nfunction toRequestContext(value: RequestContext | Record<string, unknown> | undefined): RequestContext | undefined {\n  if (!value) return undefined;\n  if (value instanceof RequestContext) return value;\n  return new RequestContext<unknown>(Object.entries(value));\n}\n\nfunction mapUsageToLiveKit(usage: VoiceTurnUsage): llm.CompletionUsage {\n  return {\n    completionTokens: usage.completionTokens,\n    promptTokens: usage.promptTokens,\n    promptCachedTokens: usage.promptCachedTokens,\n    totalTokens: usage.totalTokens,\n  };\n}\n\n/**\n * Tool names carried by a `toolCtx`, across @livekit/agents versions: 1.5+ always passes a\n * `ToolContext` class instance (tools behind getters, `Object.keys` sees only private fields),\n * while 1.4 and the object shorthand pass a plain name→tool map.\n */\nfunction livekitToolNames(toolCtx: object): string[] {\n  const instance = toolCtx as { flatten?: unknown };\n  if (typeof instance.flatten === 'function') {\n    return (instance.flatten as () => object[])().map(tool => {\n      const { id, name } = tool as { id?: string; name?: string };\n      return id ?? name ?? 'unknown';\n    });\n  }\n  return Object.keys(toolCtx);\n}\n\n/**\n * A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Drop it into the `llm` slot of a\n * customer-owned `voice.AgentSession` and the Mastra app (agent loop, tools, memory, observability)\n * runs wherever it's deployed — most importantly on a **remote** Mastra server reached over HTTP.\n *\n * Tools are defined and executed **server-side** on the Mastra agent; LiveKit-side `toolCtx` is\n * ignored (with a one-time warning). Tool activity surfaces via `toolFeedback` (spoken) and\n * `onToolCall` / `onTurnComplete` (programmatic). `voice.Agent` instructions do **not** reach the\n * Mastra agent — put instructions on the Mastra agent instead.\n *\n * @example\n * ```ts\n * const session = new voice.AgentSession({\n *   stt: 'deepgram/nova-3',\n *   tts: 'cartesia/sonic-3',\n *   llm: new MastraLLM({\n *     remote: { baseUrl: process.env.MASTRA_URL!, agentId: 'callCenter' },\n *     memory: { thread: callId, resource: callerId },\n *   }),\n * });\n * ```\n */\nexport class MastraLLM extends llm.LLM {\n  readonly #model: string;\n  readonly #onTurnMetrics?: VoiceTurnMetricsHook;\n  readonly #memory: MastraVoiceAgentMemory | false;\n  readonly #requestContext?: RequestContext;\n  /** Non-remote sources are built once; remote is built per turn so it can pick up `connOptions.timeoutMs`. */\n  readonly #staticGenerator?: VoiceReplyGenerator;\n  readonly #remoteOptions?: RemoteMastraAgentOptions & {\n    toolFeedback?: MastraLLMOptions['toolFeedback'];\n    onToolCall?: MastraLLMOptions['onToolCall'];\n    onTurnComplete?: VoiceTurnCompleteHook;\n  };\n  #warnedToolCtx = false;\n\n  constructor(options: MastraLLMOptions) {\n    super();\n    this.#onTurnMetrics = options.onTurnMetrics;\n    const sources = [\n      options.remote ? 'remote' : undefined,\n      options.agent ? 'agent' : undefined,\n      options.generate ? 'generate' : undefined,\n    ].filter(Boolean) as string[];\n    if (sources.length !== 1) {\n      throw new Error(\n        `@mastra/livekit: MastraLLM requires exactly one reply source — \\`remote\\`, \\`agent\\`, or \\`generate\\` — ` +\n          `but got ${sources.length === 0 ? 'none' : sources.join(' + ')}.`,\n      );\n    }\n\n    this.#memory = options.memory ?? false;\n    this.#requestContext = toRequestContext(options.requestContext);\n\n    if (options.remote) {\n      this.#model = options.remote.agentId;\n      this.#remoteOptions = {\n        ...options.remote,\n        toolFeedback: options.toolFeedback,\n        onToolCall: options.onToolCall,\n        onTurnComplete: options.onTurnComplete,\n      };\n    } else if (options.agent) {\n      this.#model = options.agent.id ?? options.agent.name;\n      this.#staticGenerator = createAgentReplyGenerator({\n        agent: options.agent,\n        toolFeedback: options.toolFeedback,\n        onToolCall: options.onToolCall,\n        onTurnComplete: options.onTurnComplete,\n      });\n    } else {\n      this.#model = 'mastra-generator';\n      this.#staticGenerator = options.generate;\n    }\n  }\n\n  label(): string {\n    return 'mastra.MastraLLM';\n  }\n\n  override get model(): string {\n    return this.#model;\n  }\n\n  override get provider(): string {\n    return 'mastra';\n  }\n\n  /**\n   * Resolves the reply generator for a turn. Non-remote sources are built once; the remote transport\n   * is built per turn so its connect + first-token timeout can come from the session's\n   * `connOptions.timeoutMs`, with base-class retries owning retry (transport `retries: 0`).\n   */\n  private resolveGenerator(connOptions: APIConnectOptions): VoiceReplyGenerator {\n    if (this.#staticGenerator) return this.#staticGenerator;\n    const remote = this.#remoteOptions!;\n    return createRemoteAgentReplyGenerator({\n      ...remote,\n      retries: 0,\n      timeoutMs: remote.timeoutMs ?? connOptions.timeoutMs,\n    });\n  }\n\n  override chat({\n    chatCtx,\n    toolCtx,\n    connOptions = DEFAULT_API_CONNECT_OPTIONS,\n  }: {\n    chatCtx: llm.ChatContext;\n    toolCtx?: llm.ToolContext;\n    connOptions?: APIConnectOptions;\n    parallelToolCalls?: boolean;\n    toolChoice?: llm.ToolChoice;\n    extraKwargs?: Record<string, unknown>;\n  }): llm.LLMStream {\n    // Tools run server-side; warn once if the customer wired LiveKit-side tools.\n    if (!this.#warnedToolCtx && toolCtx) {\n      const ignored = livekitToolNames(toolCtx);\n      if (ignored.length > 0) {\n        this.#warnedToolCtx = true;\n        console.warn(\n          `@mastra/livekit: MastraLLM ignores LiveKit-side tools (${ignored.join(', ')}). ` +\n            `Tools are defined and executed server-side on the Mastra agent — move them there.`,\n        );\n      }\n    }\n    return new MastraLLMStream(this, {\n      chatCtx,\n      toolCtx,\n      connOptions,\n      generator: this.resolveGenerator(connOptions),\n      onTurnMetrics: this.#onTurnMetrics,\n      memory: this.#memory,\n      requestContext: this.#requestContext,\n    });\n  }\n\n  /** No-op in v1: nothing in the LiveKit session/worker ever calls `prewarm()` automatically. */\n  override prewarm(): void {}\n}\n\ninterface MastraLLMStreamOptions {\n  onTurnMetrics?: VoiceTurnMetricsHook;\n  chatCtx: llm.ChatContext;\n  toolCtx?: llm.ToolContext;\n  connOptions: APIConnectOptions;\n  generator: VoiceReplyGenerator;\n  memory: MastraVoiceAgentMemory | false;\n  requestContext?: RequestContext;\n}\n\n/**\n * The `llm.LLMStream` `MastraLLM` returns per turn. `run()` extracts the turn's messages, drives\n * the reply generator, and pushes assistant `ChatChunk`s into `this.queue` (NOT `this.output` — the\n * base class drains queue → output and computes TTFT / duration / usage). Barge-in aborts via\n * `this.abortController` and `run()` returns silently.\n */\nclass MastraLLMStream extends llm.LLMStream {\n  readonly #generator: VoiceReplyGenerator;\n  readonly #onTurnMetrics?: VoiceTurnMetricsHook;\n  readonly #memory: MastraVoiceAgentMemory | false;\n  readonly #requestContext?: RequestContext;\n\n  constructor(mastraLLM: MastraLLM, options: MastraLLMStreamOptions) {\n    super(mastraLLM, { chatCtx: options.chatCtx, toolCtx: options.toolCtx, connOptions: options.connOptions });\n    this.#generator = options.generator;\n    this.#onTurnMetrics = options.onTurnMetrics;\n    this.#memory = options.memory;\n    this.#requestContext = options.requestContext;\n  }\n\n  protected async run(): Promise<void> {\n    const messages =\n      this.#memory === false ? chatContextToMessages(this.chatCtx) : extractNewTurnMessages(this.chatCtx);\n    // No new input to answer → close without a request (equivalent to the wrapper returning null).\n    if (messages.length === 0) return;\n\n    let usage: VoiceTurnUsage | undefined;\n    const turnCtx: VoiceTurnContext = {\n      messages,\n      chatCtx: this.chatCtx,\n      memory: this.#memory,\n      requestContext: this.#requestContext,\n      onUsage: turnUsage => {\n        usage = turnUsage;\n      },\n    };\n\n    const { reply, identity } = await instrumentVoiceReply(this.#generator, turnCtx, this.#onTurnMetrics);\n    if (!reply) return;\n    if (this.abortController.signal.aborted) {\n      await reply.cancel().catch(() => {});\n      return;\n    }\n\n    // A single provider response id ties all of this turn's chunks together for the base class metrics.\n    const id = identity.attemptId;\n    const reader = reply.getReader();\n    const onAbort = () => void reader.cancel().catch(() => {});\n    this.abortController.signal.addEventListener('abort', onAbort, { once: true });\n    try {\n      for (;;) {\n        const { done, value } = await reader.read();\n        if (done) break;\n        if (this.abortController.signal.aborted) break;\n        if (value)\n          this.queue.put({\n            id,\n            delta: {\n              role: 'assistant',\n              ...(typeof value === 'string' ? { content: value } : {}),\n              extra: { [VOICE_TURN_METADATA]: identity, [VOICE_FLUSH_METADATA]: typeof value !== 'string' },\n            },\n          });\n      }\n    } catch (error) {\n      // Barge-in tears down the reply stream; that surfaces as a read rejection but is not a failure.\n      if (this.abortController.signal.aborted) return;\n      throw error;\n    } finally {\n      this.abortController.signal.removeEventListener('abort', onAbort);\n    }\n    // Return silently on barge-in — throwing would feed the base class's error/retry machinery.\n    if (this.abortController.signal.aborted) return;\n    // Final usage-only chunk → the base class reads usage from the last chunk that carries it.\n    if (usage) this.queue.put({ id, usage: mapUsageToLiveKit(usage) });\n  }\n}\n\nexport { MastraLLMStream };\n"],"mappings":"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"}

package/dist/recording-route.d.ts

@@ -0,0 +1,31 @@
+import type { ApiRoute, ContextWithMastra } from '@mastra/core/server';
+import type { SpanRecord } from '@mastra/core/storage';
+import { z } from 'zod/v4';
+import type { LiveKitRecording } from './recording-types.js';
+export declare const recordingSchema: z.ZodObject<{
+    url: z.ZodURL;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export interface LiveKitRecordingResolverArgs {
+    traceId: string;
+    /** Taken from the stored voice call span, never from the browser request. */
+    roomName: string;
+    span: SpanRecord;
+    context: ContextWithMastra;
+}
+export interface LiveKitRecordingRouteOptions {
+    /** Studio discovers this route at its default path: /voice/livekit/recordings/:traceId. */
+    path?: string;
+    /** Defaults to true. Only disable for a local demo. */
+    requiresAuth?: boolean;
+    /** Required trace-specific access policy. Only true permits trace lookup and URL resolution. */
+    authorize: (args: {
+        traceId: string;
+        context: ContextWithMastra;
+    }) => boolean | Promise<boolean>;
+    /** Return a playable URL, or undefined if the recording is not available yet. */
+    resolveRecording: (args: LiveKitRecordingResolverArgs) => Promise<LiveKitRecording | undefined>;
+}
+/** Resolves a voice call trace to a recording without persisting signed URLs in traces. */
+export declare function liveKitRecordingRoute(options: LiveKitRecordingRouteOptions): ApiRoute;
+//# sourceMappingURL=recording-route.d.ts.map

package/dist/recording-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording-route.d.ts","sourceRoot":"","sources":["../src/recording-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAA4B,MAAM,mBAAmB,CAAC;AAGpF,eAAO,MAAM,eAAe;;;iBAGY,CAAC;AAEzC,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gGAAgG;IAChG,SAAS,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAA;KAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjG,iFAAiF;IACjF,gBAAgB,EAAE,CAAC,IAAI,EAAE,4BAA4B,KAAK,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;CACjG;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,QAAQ,CA4CrF"}

package/dist/recording-types.d.ts

@@ -0,0 +1,11 @@
+/** A playback URL, normally signed with a short expiry by your storage provider. */
+export interface LiveKitRecording {
+    url: string;
+    expiresAt?: string;
+}
+export type LiveKitRecordingResponse = ({
+    status: 'ready';
+} & LiveKitRecording) | {
+    status: 'unavailable';
+};
+//# sourceMappingURL=recording-types.d.ts.map

package/dist/recording-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording-types.d.ts","sourceRoot":"","sources":["../src/recording-types.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,wBAAwB,GAAG,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,CAAC,GAAG;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC"}

package/dist/recording.d.ts

@@ -0,0 +1,21 @@
+import { RoomEgress } from 'livekit-server-sdk';
+/**
+ * LiveKit auto-egress settings, accepted as a plain object or a RoomEgress instance.
+ * Use `room.audioOnly` and `room.fileOutputs` for a single mixed audio recording.
+ * Storage credentials belong here on the server, never in session metadata or tokens.
+ */
+export type LiveKitRecordingOptions = NonNullable<ConstructorParameters<typeof RoomEgress>[0]>;
+/** A recording-enabled session cannot reuse an existing LiveKit room. */
+export declare class LiveKitRecordingRoomConflictError extends Error {
+    readonly roomName: string;
+    constructor(roomName: string);
+}
+/** Creates a fresh room with recording configured before any agent or caller joins. */
+export declare function createRecordingRoom(options: {
+    roomName: string;
+    serverUrl: string;
+    apiKey: string;
+    apiSecret: string;
+    recording: LiveKitRecordingOptions;
+}): Promise<import("livekit-server-sdk").Room>;
+//# sourceMappingURL=recording.d.ts.map

package/dist/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../src/recording.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAqB,MAAM,oBAAoB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/F,yEAAyE;AACzE,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,YAAY,QAAQ,EAAE,MAAM,EAM3B;CACF;AAED,uFAAuF;AACvF,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,uBAAuB,CAAC;CACpC,8CAeA"}