realtime-voice-agents 2.0.0

package/dist/index.mjs

@@ -0,0 +1,2113 @@
+import { t as TypedEmitter } from "./events-BylBSBW-.mjs";
+import { a as noopLogger, i as consoleLogger, n as deepMerge, r as childLogger, t as BaseRealtimeProvider } from "./BaseRealtimeProvider-BQigr5mB.mjs";
+import { t as InMemorySessionStore } from "./InMemorySessionStore-DYParOJO.mjs";
+import { a as TwilioMediaTransport, r as connectStreamTwiml, t as TwilioRestClient } from "./rest-BYqiVOhe.mjs";
+import { a as mulawBytesToMs, i as base64ByteLength } from "./mulaw--cwU2c9L.mjs";
+import { t as BackgroundAudioPlayer } from "./BackgroundAudioPlayer-iMcivjis.mjs";
+import { t as buildSessionUpdate } from "./session-config-BVLl7-ha.mjs";
+import { readFileSync } from "node:fs";
+import * as z from "zod";
+import WebSocket$1 from "ws";
+//#region src/agents/Agent.ts
+function slugify(name) {
+	const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	if (!slug) throw new Error(`cannot derive an agent id from name "${name}"`);
+	return slug;
+}
+var Agent = class {
+	id;
+	name;
+	voice;
+	model;
+	tools;
+	handoffs;
+	handoffDescription;
+	providerOptions;
+	instructionsSource;
+	constructor(definition) {
+		this.id = definition.id ?? slugify(definition.name);
+		this.name = definition.name;
+		this.voice = definition.voice;
+		this.model = definition.model;
+		this.tools = definition.tools ?? [];
+		this.handoffs = definition.handoffs ?? [];
+		this.handoffDescription = definition.handoffDescription;
+		this.providerOptions = definition.providerOptions;
+		this.instructionsSource = definition.instructions;
+	}
+	resolveInstructions(context) {
+		return typeof this.instructionsSource === "function" ? this.instructionsSource(context) : this.instructionsSource;
+	}
+};
+/**
+* Walk the handoff graph (BFS) from a root agent. Cycles are fine — swarms
+* commonly hand back and forth. Two different Agent instances claiming the
+* same id is a configuration error caught here, at session build.
+*/
+function collectAgentGraph(root) {
+	const agents = /* @__PURE__ */ new Map();
+	const queue = [root];
+	while (queue.length > 0) {
+		const agent = queue.shift();
+		const existing = agents.get(agent.id);
+		if (existing === agent) continue;
+		if (existing) throw new Error(`duplicate agent id "${agent.id}" (two different Agent instances)`);
+		agents.set(agent.id, agent);
+		queue.push(...agent.handoffs);
+	}
+	return agents;
+}
+//#endregion
+//#region src/tools/json-schema.ts
+/**
+* Zod → JSON Schema for provider tool declarations.
+*
+* Zod 4 ships `z.toJSONSchema()` — used when available (zod is a required
+* peer). For Zod 3 (≥3.25) a minimal structural converter covers the subset
+* that makes sense for voice-agent tool parameters: objects, strings,
+* numbers, booleans, enums, literals, arrays, records, unions,
+* optional/nullable/default, descriptions.
+*/
+function zodToJsonSchema(schema) {
+	let result;
+	const native = z.toJSONSchema;
+	if (typeof native === "function" && isZod4Schema(schema)) try {
+		result = { ...native(schema, {
+			target: "draft-7",
+			io: "input"
+		}) };
+	} catch {
+		result = { type: "object" };
+	}
+	else result = convertZod3(schema);
+	delete result.$schema;
+	if (result.type === void 0 && !result.anyOf && !result.oneOf && !result.enum) result.type = "object";
+	return result;
+}
+/** Zod 4 schemas carry an internal `_zod` bag; Zod 3 uses `_def.typeName`. */
+function isZod4Schema(schema) {
+	return schema != null && typeof schema === "object" && "_zod" in schema;
+}
+function convertZod3(schema) {
+	const def = schema?._def;
+	if (!def) return { type: "object" };
+	const typeName = def.typeName ?? "";
+	const description = def.description;
+	const withDescription = (node) => description ? {
+		...node,
+		description
+	} : node;
+	switch (typeName) {
+		case "ZodObject": {
+			const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+			const properties = {};
+			const required = [];
+			for (const [key, value] of Object.entries(shape ?? {})) {
+				const child = value;
+				properties[key] = convertZod3(child);
+				if (!isOptionalZod3(child)) required.push(key);
+			}
+			return withDescription({
+				type: "object",
+				properties,
+				...required.length ? { required } : {},
+				additionalProperties: false
+			});
+		}
+		case "ZodString": return withDescription({ type: "string" });
+		case "ZodNumber": return withDescription({ type: "number" });
+		case "ZodBoolean": return withDescription({ type: "boolean" });
+		case "ZodEnum": return withDescription({
+			type: "string",
+			enum: def.values
+		});
+		case "ZodNativeEnum": return withDescription({ enum: Object.values(def.values ?? {}) });
+		case "ZodLiteral": return withDescription({ const: def.value });
+		case "ZodArray": return withDescription({
+			type: "array",
+			items: convertZod3(def.type)
+		});
+		case "ZodRecord": return withDescription({
+			type: "object",
+			additionalProperties: def.valueType ? convertZod3(def.valueType) : true
+		});
+		case "ZodUnion": return withDescription({ anyOf: (def.options ?? []).map(convertZod3) });
+		case "ZodOptional": return withDescription(convertZod3(def.innerType));
+		case "ZodNullable": return withDescription({ anyOf: [convertZod3(def.innerType), { type: "null" }] });
+		case "ZodDefault": return withDescription({
+			...convertZod3(def.innerType),
+			default: def.defaultValue?.()
+		});
+		case "ZodEffects": return withDescription(convertZod3(def.schema));
+		default: return withDescription({});
+	}
+}
+function isOptionalZod3(schema) {
+	const typeName = schema?._def?.typeName;
+	if (typeName === "ZodOptional" || typeName === "ZodDefault") return true;
+	if (typeName === "ZodEffects") return isOptionalZod3(schema._def.schema);
+	return false;
+}
+//#endregion
+//#region src/tools/tool.ts
+const NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Define a provider-agnostic tool with a Zod parameters schema. */
+function tool(definition) {
+	if (!NAME_PATTERN.test(definition.name)) throw new Error(`tool name "${definition.name}" is invalid (allowed: letters, digits, _ and -, max 64 chars)`);
+	return {
+		...definition,
+		strategy: definition.strategy ?? "sync",
+		parametersJsonSchema: zodToJsonSchema(definition.parameters)
+	};
+}
+//#endregion
+//#region src/agents/handoff.ts
+/**
+* Swarm-style handoffs (LangGraph-inspired): every agent listed in
+* `handoffs` gets an auto-generated `transfer_to_<id>` tool. The tool's
+* execute returns a Command-like directive; the session intercepts it,
+* delivers the tool result, and performs the swap — so tool-initiated and
+* programmatic (`session.handoffTo`) handoffs share one code path.
+*/
+const HANDOFF_MARKER = "__twilioRealtimeAgentsHandoff";
+function isHandoffDirective(value) {
+	return typeof value === "object" && value !== null && value[HANDOFF_MARKER] === true;
+}
+function handoffToolName(agentId) {
+	return `transfer_to_${agentId}`;
+}
+function createHandoffTool(target) {
+	return tool({
+		name: handoffToolName(target.id),
+		description: target.handoffDescription ?? `Transfer the conversation to ${target.name}. Use when the caller's request is better handled by ${target.name}.`,
+		parameters: z.object({ reason: z.string().optional().describe("Brief context for the receiving agent about why the caller was transferred") }),
+		execute: async (input) => ({
+			[HANDOFF_MARKER]: true,
+			targetAgentId: target.id,
+			reason: input.reason
+		})
+	});
+}
+//#endregion
+//#region src/interruption/InterruptionController.ts
+var InterruptionController = class {
+	settings;
+	now;
+	responseIndex = 0;
+	guardStartedAt = null;
+	guardResponseId = null;
+	/** The guarded response's audio has not finished (or been flushed) yet. */
+	guardPlaybackOpen = false;
+	/** Responses that began while the guarded one was still playing. */
+	deferredStarts = 0;
+	suspended = false;
+	bargeInTimestamps = [];
+	constructor(settings = {}, now = Date.now) {
+		this.settings = settings;
+		this.now = now;
+	}
+	get isSuspended() {
+		return this.suspended;
+	}
+	/** A new response started generating: rotate the guard to it. */
+	onResponseStarted(responseId) {
+		if (this.guardPlaybackOpen && this.guardActive()) {
+			this.deferredStarts++;
+			return;
+		}
+		this.responseIndex += 1 + this.deferredStarts;
+		this.deferredStarts = 0;
+		this.guardResponseId = responseId;
+		this.guardStartedAt = null;
+		this.guardPlaybackOpen = true;
+	}
+	/** Playback of a response reached the caller: the guard clock starts now. */
+	onPlaybackStarted(responseId) {
+		if (responseId === this.guardResponseId) this.guardStartedAt = this.now();
+	}
+	/** Current playback finished or was cleared: cooldown suspension ends. */
+	onPlaybackEnded() {
+		this.suspended = false;
+		this.guardPlaybackOpen = false;
+		if (this.deferredStarts > 0) {
+			this.responseIndex += this.deferredStarts;
+			this.deferredStarts = 0;
+		}
+	}
+	/**
+	* Evaluate a barge-in attempt (user speech while the agent is audible).
+	* Every attempt counts toward the rate limiter, including blocked ones.
+	*/
+	evaluate(context) {
+		if (this.settings.enabled === false) return {
+			allow: false,
+			cause: "disabled"
+		};
+		if (this.suspended) return {
+			allow: false,
+			cause: "suspended"
+		};
+		if (context.toolRunning) return {
+			allow: false,
+			cause: "tool_running"
+		};
+		const rateLimit = this.settings.rateLimit;
+		if (rateLimit) {
+			const now = this.now();
+			this.bargeInTimestamps = this.bargeInTimestamps.filter((ts) => now - ts <= rateLimit.windowMs);
+			this.bargeInTimestamps.push(now);
+			if (this.bargeInTimestamps.length >= rateLimit.threshold) {
+				this.suspended = true;
+				this.bargeInTimestamps = [];
+				return {
+					allow: false,
+					cause: "rate_limit",
+					instruction: rateLimit.instruction
+				};
+			}
+		}
+		if (this.guardActive()) return {
+			allow: false,
+			cause: "guard"
+		};
+		return { allow: true };
+	}
+	guardActive() {
+		const { guardDurationMs, firstResponseOnly } = this.settings;
+		if (!guardDurationMs) return false;
+		if (firstResponseOnly && this.responseIndex > 1) return false;
+		if (this.guardStartedAt === null) return true;
+		return this.now() - this.guardStartedAt < guardDurationMs;
+	}
+};
+//#endregion
+//#region src/playback/PlaybackTracker.ts
+/**
+* PlaybackTracker — the honest playback clock.
+*
+* Marks are interleaved into the outbound media stream at checkpoints — after
+* the FIRST audio chunk of a response (exact `playback.started`), then after
+* every ~1s of accumulated audio, and after the final chunk once generation
+* completes (exact `playback.finished`). Twilio plays media strictly in order
+* and echoes each mark when playout reaches it, so a mark echo is
+* hardware-level confirmation of what the caller has heard — unlike
+* generation-time events, which run seconds ahead of the phone line.
+*
+* Why checkpoints and not a mark per delta: field testing showed per-delta
+* marks (which double the message count on the Twilio socket) audibly degrade
+* playback smoothness, while sparse marks lose nothing — between echoes,
+* `estimatePlayedMs` interpolates with the wall clock, so truncate accuracy
+* is bounded by echo jitter, not by the checkpoint interval.
+*
+* Clear-epoch: `clear` flushes Twilio's buffer, and Twilio echoes the
+* discarded marks immediately. Bumping the epoch before sending `clear` lets
+* those echoes be classified as flushed instead of played, so `playedMs`
+* stays truthful — this number feeds `conversation.item.truncate`.
+*/
+const TRACKED_MARK_PREFIX = "tra:";
+const DEFAULT_CHECKPOINT_INTERVAL_MS = 1e3;
+var PlaybackTracker = class {
+	epoch = 0;
+	markSeq = 0;
+	marks = /* @__PURE__ */ new Map();
+	responses = /* @__PURE__ */ new Map();
+	now;
+	checkpointIntervalMs;
+	constructor(now = Date.now, options = {}) {
+		this.now = now;
+		this.checkpointIntervalMs = options.checkpointIntervalMs ?? DEFAULT_CHECKPOINT_INTERVAL_MS;
+	}
+	/** Is `name` one of ours (as opposed to a host-app or background mark)? */
+	static isTrackedMark(name) {
+		return name.startsWith(TRACKED_MARK_PREFIX);
+	}
+	/**
+	* Record an outgoing audio chunk. Returns a mark name to interleave after
+	* it when a checkpoint is due (first chunk of the response, or
+	* checkpointIntervalMs of audio accumulated since the last mark) — null
+	* otherwise.
+	*/
+	onAudioSent(responseId, chunkMs, itemId) {
+		const track = this.ensureTrack(responseId);
+		if (itemId && !track.itemId) track.itemId = itemId;
+		track.totalMs += chunkMs;
+		const firstChunk = track.markedMs === 0 && track.sentMarks === 0;
+		const intervalDue = track.totalMs - track.markedMs >= this.checkpointIntervalMs;
+		if (!firstChunk && !intervalDue) return null;
+		return this.createMark(track, false);
+	}
+	/**
+	* The response finished generating. If audio accumulated past the last
+	* checkpoint, returns a final tail mark that MUST be sent to Twilio (it is
+	* what makes `playback.finished` fire); otherwise flags the pending mark
+	* covering the full total as final and returns null.
+	*/
+	onGenerationDone(responseId) {
+		const track = this.responses.get(responseId);
+		if (!track) return null;
+		track.generationDone = true;
+		if (track.totalMs === 0) {
+			track.finished = true;
+			return null;
+		}
+		if (track.finished || track.flushed) return null;
+		let covered = false;
+		for (const record of this.marks.values()) if (record.responseId === responseId && record.cumulativeMs === track.totalMs) {
+			record.isFinal = true;
+			covered = true;
+		}
+		if (covered) return null;
+		if (track.playedMs >= track.totalMs) {
+			track.finished = true;
+			this.maybeForget(track);
+			return null;
+		}
+		return this.createMark(track, true);
+	}
+	createMark(track, isFinal) {
+		track.sentMarks++;
+		track.markedMs = track.totalMs;
+		const name = `${TRACKED_MARK_PREFIX}${++this.markSeq}`;
+		this.marks.set(name, {
+			responseId: track.responseId,
+			cumulativeMs: track.totalMs,
+			epoch: this.epoch,
+			isFinal
+		});
+		return name;
+	}
+	/** Process a mark echo from Twilio. Returns null for unknown marks. */
+	onMarkEcho(name) {
+		const record = this.marks.get(name);
+		if (!record) return null;
+		this.marks.delete(name);
+		const track = this.responses.get(record.responseId);
+		if (!track) return null;
+		track.echoedMarks++;
+		if (record.epoch !== this.epoch || track.flushed) {
+			this.maybeForget(track);
+			return {
+				kind: "flushed",
+				responseId: record.responseId,
+				playedMs: track.playedMs,
+				playbackStarted: false,
+				playbackFinished: false
+			};
+		}
+		track.playedMs = Math.max(track.playedMs, record.cumulativeMs);
+		track.lastEchoAtMs = this.now();
+		const playbackStarted = !track.playbackStarted;
+		track.playbackStarted = true;
+		let playbackFinished = false;
+		if (record.isFinal && track.generationDone && !track.finished) {
+			track.finished = true;
+			playbackFinished = true;
+		}
+		this.maybeForget(track);
+		return {
+			kind: "played",
+			responseId: record.responseId,
+			playedMs: track.playedMs,
+			playbackStarted,
+			playbackFinished
+		};
+	}
+	/**
+	* Bump the clear-epoch (call this immediately BEFORE sending `clear`).
+	* Every un-echoed mark becomes flushed; responses with unplayed audio are
+	* finalized at their current playedMs. Returns those interrupted responses.
+	*/
+	onClear() {
+		this.epoch++;
+		const interrupted = [];
+		for (const track of this.responses.values()) if (!track.finished && track.playedMs < track.totalMs) {
+			track.flushed = true;
+			track.finished = true;
+			interrupted.push({
+				responseId: track.responseId,
+				playedMs: track.playedMs,
+				itemId: track.itemId
+			});
+		}
+		return interrupted;
+	}
+	/**
+	* Best-estimate of what the caller has heard of `responseId` right now:
+	* last confirmed mark plus wall-clock elapsed since, clamped to the total.
+	*/
+	estimatePlayedMs(responseId) {
+		const track = this.responses.get(responseId);
+		if (!track) return 0;
+		if (track.finished || !track.playbackStarted || track.lastEchoAtMs === null) return track.playedMs;
+		const elapsed = this.now() - track.lastEchoAtMs;
+		return Math.min(track.playedMs + Math.max(0, elapsed), track.totalMs);
+	}
+	/**
+	* Live responses with unplayed audio, with their current played-ms
+	* estimates — captured BEFORE onClear() freezes them, to feed truncation.
+	*/
+	snapshotActive() {
+		const active = [];
+		for (const track of this.responses.values()) if (!track.finished && track.totalMs > 0) active.push({
+			responseId: track.responseId,
+			itemId: track.itemId,
+			estimatedPlayedMs: this.estimatePlayedMs(track.responseId)
+		});
+		return active;
+	}
+	/** Any response with audio still unplayed (and not flushed)? */
+	isPlaybackActive() {
+		for (const track of this.responses.values()) if (!track.finished && track.totalMs > 0) return true;
+		return false;
+	}
+	itemIdFor(responseId) {
+		return this.responses.get(responseId)?.itemId;
+	}
+	playedMsFor(responseId) {
+		return this.responses.get(responseId)?.playedMs ?? 0;
+	}
+	totalMsFor(responseId) {
+		return this.responses.get(responseId)?.totalMs ?? 0;
+	}
+	ensureTrack(responseId) {
+		let track = this.responses.get(responseId);
+		if (!track) {
+			track = {
+				responseId,
+				totalMs: 0,
+				markedMs: 0,
+				playedMs: 0,
+				sentMarks: 0,
+				echoedMarks: 0,
+				generationDone: false,
+				playbackStarted: false,
+				finished: false,
+				flushed: false,
+				lastEchoAtMs: null
+			};
+			this.responses.set(responseId, track);
+		}
+		return track;
+	}
+	/** Drop bookkeeping once a response is finished and every mark came home. */
+	maybeForget(track) {
+		if (track.finished && track.echoedMarks >= track.sentMarks) this.responses.delete(track.responseId);
+	}
+};
+//#endregion
+//#region src/providers/base/reconnect.ts
+const DEFAULT_RECONNECT_POLICY = {
+	maxAttempts: 5,
+	initialDelayMs: 250,
+	maxDelayMs: 8e3,
+	jitter: true
+};
+/** Deterministic (pre-jitter) delay for a 1-based attempt number. */
+function baseDelayForAttempt(policy, attempt) {
+	const exp = policy.initialDelayMs * 2 ** Math.max(0, attempt - 1);
+	return Math.min(exp, policy.maxDelayMs);
+}
+function delayForAttempt(policy, attempt, random = Math.random) {
+	const base = baseDelayForAttempt(policy, attempt);
+	return policy.jitter ? Math.floor(random() * base) : base;
+}
+//#endregion
+//#region src/session/transcript.ts
+/** Render a transcript for history re-injection after reconnect/handoff. */
+function formatTranscriptForInjection(entries, maxTurns = 30) {
+	return entries.slice(-maxTurns).map((entry) => `${entry.role === "user" ? "Caller" : "Agent"}: ${entry.text}`).join("\n");
+}
+//#endregion
+//#region src/session/usage.ts
+function emptyUsage() {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0,
+		inputTokenDetails: {
+			textTokens: 0,
+			audioTokens: 0,
+			cachedTokens: 0
+		},
+		outputTokenDetails: {
+			textTokens: 0,
+			audioTokens: 0
+		},
+		responses: 0
+	};
+}
+/** Sums per-response provider usage into call totals. */
+var UsageAccumulator = class {
+	usage = emptyUsage();
+	add(providerUsage) {
+		this.usage.inputTokens += providerUsage.inputTokens;
+		this.usage.outputTokens += providerUsage.outputTokens;
+		this.usage.totalTokens += providerUsage.totalTokens;
+		this.usage.inputTokenDetails.textTokens += providerUsage.inputTokenDetails?.textTokens ?? 0;
+		this.usage.inputTokenDetails.audioTokens += providerUsage.inputTokenDetails?.audioTokens ?? 0;
+		this.usage.inputTokenDetails.cachedTokens += providerUsage.inputTokenDetails?.cachedTokens ?? 0;
+		this.usage.outputTokenDetails.textTokens += providerUsage.outputTokenDetails?.textTokens ?? 0;
+		this.usage.outputTokenDetails.audioTokens += providerUsage.outputTokenDetails?.audioTokens ?? 0;
+		this.usage.responses += 1;
+		return this.snapshot();
+	}
+	snapshot() {
+		return structuredClone(this.usage);
+	}
+};
+//#endregion
+//#region src/tools/context.ts
+/**
+* Session-scoped key/value context: seeded at call start (tenant id, caller
+* profile, …), readable and writable from any tool during the call, carried
+* across agent handoffs, and included in store snapshots.
+*/
+var SessionContext = class {
+	data = /* @__PURE__ */ new Map();
+	constructor(initial) {
+		for (const [key, value] of Object.entries(initial ?? {})) this.data.set(key, value);
+	}
+	get(key) {
+		return this.data.get(key);
+	}
+	set(key, value) {
+		this.data.set(key, value);
+	}
+	has(key) {
+		return this.data.has(key);
+	}
+	delete(key) {
+		return this.data.delete(key);
+	}
+	toJSON() {
+		return Object.fromEntries(this.data);
+	}
+};
+//#endregion
+//#region src/tools/middleware.ts
+/** Apply every middleware's decoration, first-registered first. */
+function decorateTool(tool, middlewares) {
+	let description = tool.description;
+	let parameters = tool.parametersJsonSchema;
+	for (const middleware of middlewares) {
+		const decoration = middleware.decorate?.(tool);
+		if (decoration?.description !== void 0) description = decoration.description;
+		if (decoration?.parameters !== void 0) parameters = decoration.parameters;
+	}
+	return {
+		description,
+		parameters
+	};
+}
+/** Compose wrapExecute chains around an innermost executor. */
+function composeExecution(tool, input, ctx, middlewares, innermost) {
+	let chain = innermost;
+	for (const middleware of [...middlewares].reverse()) {
+		if (!middleware.wrapExecute) continue;
+		const next = chain;
+		chain = () => middleware.wrapExecute(tool, input, ctx, next);
+	}
+	return chain();
+}
+//#endregion
+//#region src/tools/result-queue.ts
+var ToolResultQueue = class {
+	items = [];
+	get size() {
+		return this.items.length;
+	}
+	enqueue(item) {
+		this.items.push(item);
+	}
+	/** Remove and return everything, in arrival order. */
+	drain() {
+		const drained = this.items;
+		this.items = [];
+		return drained;
+	}
+	clear() {
+		this.items = [];
+	}
+};
+//#endregion
+//#region src/tools/builtins/finishCall.ts
+const DEFAULT_DESCRIPTION$1 = "End the phone call when the conversation is complete, the caller says goodbye, or they ask to hang up. After calling this you will be asked to say one brief closing line; say it and then stop speaking.";
+const DEFAULT_FAREWELL_INSTRUCTION = "The call is now ending. Say one brief, warm goodbye line to the caller — in the language of the conversation — and then stop speaking entirely.";
+/**
+* Graceful hangup: the tool result *instructs* the model to say goodbye (so
+* the farewell is the model's own, in context and language), the session
+* watches the goodbye's playout via marks, and only then completes the leg.
+* A watchdog forces completion if the goodbye never materializes.
+*/
+function createFinishCallTool(options = {}) {
+	return tool({
+		name: "finish_call",
+		description: options.description ?? DEFAULT_DESCRIPTION$1,
+		parameters: z.object({ reason: z.string().optional().describe("Why the call is ending, for the call log") }),
+		execute: async (input, ctx) => {
+			ctx.logger.info("finish_call invoked", { reason: input.reason });
+			ctx.session.finishCall();
+			return {
+				status: "ending_call",
+				instruction: options.farewellInstruction ?? DEFAULT_FAREWELL_INSTRUCTION
+			};
+		}
+	});
+}
+//#endregion
+//#region src/tools/builtins/transferCall.ts
+const DEFAULT_DESCRIPTION = "Transfer this call to a human agent or an external phone number. Use when the caller asks for a person, or the request is beyond what you can handle.";
+function createTransferCallTool(options = {}) {
+	return tool({
+		name: "transfer_call",
+		description: options.description ?? DEFAULT_DESCRIPTION,
+		parameters: z.object({
+			phoneNumber: z.string().optional().describe("Destination in E.164 format (+15551234567). Omit to use the default."),
+			reason: z.string().optional().describe("Why the caller is being transferred")
+		}),
+		execute: async (input, ctx) => {
+			const target = input.phoneNumber ?? options.defaultPhoneNumber;
+			if (!target) return {
+				error: "no destination number available",
+				hint: "Ask the caller to hold and take a message instead."
+			};
+			ctx.session.transferTo(target, {
+				callerId: options.callerId,
+				announcement: options.announcement
+			});
+			return {
+				status: "transferring",
+				to: target
+			};
+		}
+	});
+}
+//#endregion
+//#region src/bridge/CallSession.ts
+/**
+* CallSession — the per-call orchestrator.
+*
+* One mutable object owns all live state for a call (no split-brain between a
+* store and hot data). The SessionStore only receives immutable snapshots at
+* checkpoints, never reads on the audio path. Teardown is centralized and
+* idempotent: every timer, tool AbortController, provider socket, and Twilio
+* socket is released exactly once.
+*/
+const MAX_BUFFERED_INBOUND_FRAMES = 250;
+var CallSession = class extends TypedEmitter {
+	callSid;
+	streamSid;
+	callInfo;
+	context;
+	stateValue = "connecting";
+	deps;
+	log;
+	tracker = new PlaybackTracker();
+	interruptions;
+	usageAccumulator = new UsageAccumulator();
+	toolQueue = new ToolResultQueue();
+	transcriptEntries = [];
+	toolset;
+	startedAtMs = Date.now();
+	interruptedResponses = /* @__PURE__ */ new Set();
+	runningTools = /* @__PURE__ */ new Map();
+	timers = /* @__PURE__ */ new Set();
+	provider = null;
+	activeAgentValue;
+	generating = false;
+	currentResponseId = null;
+	firstTurnDone = false;
+	/**
+	* A caller turn that a blocked barge-in swallowed. With bridge-owned
+	* interruptions the server no longer auto-responds while the protected
+	* response is active, so the bridge answers it after protected playback:
+	* 'speaking' → user started during a block; 'committed' → their turn ended
+	* (VAD committed it) and deserves a response once playback finishes.
+	*/
+	blockedUserTurn = "idle";
+	greeted = false;
+	answered;
+	inboundBuffer = [];
+	reconnectAttempt = 0;
+	reconnecting = false;
+	pendingHangup = null;
+	pendingTransfer = null;
+	endedReason = null;
+	hangupReason = "agent-hangup";
+	middlewares;
+	bgAudio;
+	/** Deferred tool calls awaiting a real result (execute() or submitToolResult). */
+	deferredPending = /* @__PURE__ */ new Map();
+	/** Human-in-the-loop calls awaiting approve/reject. */
+	approvals = /* @__PURE__ */ new Map();
+	/** Text turns to inject once the agent finishes speaking (deferred results). */
+	pendingInjections = [];
+	idleTimer = null;
+	nudgeCount = 0;
+	/** All agents reachable from the root via handoffs, by id. */
+	agents;
+	handoffHistory = [];
+	handoffInProgress = false;
+	/** Pre-synthesized greeting playout state. */
+	pregreeting = null;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+		this.callSid = deps.start.start.callSid;
+		this.streamSid = deps.start.start.streamSid ?? deps.start.streamSid;
+		this.log = childLogger(deps.logger, { callSid: this.callSid });
+		this.activeAgentValue = deps.agent;
+		this.context = new SessionContext(deps.options.context);
+		this.interruptions = new InterruptionController(deps.options.interruptions);
+		const params = deps.start.start.customParameters ?? {};
+		this.callInfo = {
+			direction: params.direction === "outbound" ? "outbound" : "inbound",
+			from: params.from,
+			to: params.to,
+			customParameters: params
+		};
+		this.answered = deps.answeredEarly === true || this.callInfo.direction === "inbound";
+		this.agents = collectAgentGraph(deps.agent);
+		this.middlewares = deps.middlewares ?? [];
+		this.bgAudio = new BackgroundAudioPlayer({
+			sendMedia: (payload) => {
+				if (this.stateValue === "active" && this.deps.transport.isOpen) this.deps.transport.sendMedia(payload);
+			},
+			onStarted: (info) => this.emit("background_audio.started", info),
+			onStopped: (info) => this.emit("background_audio.stopped", info)
+		});
+		this.toolset = this.buildToolset();
+		this.wireTransport();
+	}
+	get state() {
+		return this.stateValue;
+	}
+	get activeAgent() {
+		return this.activeAgentValue;
+	}
+	get usage() {
+		return this.usageAccumulator.snapshot();
+	}
+	get transcript() {
+		return this.transcriptEntries;
+	}
+	/** Connect the provider and activate the call. Called by the bridge. */
+	async begin() {
+		this.playPreGreeting();
+		try {
+			this.provider = this.deps.providerFactory({
+				logger: this.log,
+				callSid: this.callSid
+			});
+			this.wireProvider(this.provider);
+			await this.provider.connect(this.buildProviderInit());
+		} catch (error) {
+			this.fail(error instanceof Error ? error : new Error(String(error)), "provider-failed");
+			return;
+		}
+		if (this.stateValue !== "connecting") return;
+		this.stateValue = "active";
+		this.emit("provider.connected");
+		this.emit("call.started", {
+			callSid: this.callSid,
+			streamSid: this.streamSid,
+			direction: this.callInfo.direction,
+			from: this.callInfo.from,
+			to: this.callInfo.to,
+			customParameters: this.callInfo.customParameters
+		});
+		if (this.pregreeting) this.provider.sendText(this.pregreeting.text, {
+			role: "assistant",
+			triggerResponse: false
+		});
+		this.flushInboundBuffer();
+		this.startMaxDurationWatchdog();
+		this.armIdleTimer();
+		this.saveSnapshot();
+		this.maybeGreet();
+	}
+	/** The outbound leg was answered (host's Twilio status callback). */
+	notifyAnswered() {
+		if (this.answered) return;
+		this.answered = true;
+		this.maybeGreet();
+	}
+	sendText(text, options = {}) {
+		this.provider?.sendText(text, options);
+	}
+	async updateInstructions(instructions) {
+		await this.provider?.updateSession({ instructions });
+	}
+	/** Manual barge-in: stop the agent mid-sentence. */
+	interrupt() {
+		if (!this.generating && !this.tracker.isPlaybackActive()) return;
+		this.provider?.cancelResponse();
+		this.performInterrupt();
+	}
+	/**
+	* Gracefully end the call. With `finalMessage`, the agent speaks it first.
+	* With `immediate: true`, skip the goodbye and complete now. Resolves when
+	* the call has actually ended.
+	*/
+	finishCall(options = {}) {
+		if (this.stateValue === "ended") return Promise.resolve();
+		if (options.immediate) {
+			this.completeHangup();
+			return Promise.resolve();
+		}
+		if (options.finalMessage) this.provider?.createResponse({ instructions: `Say exactly this to the caller, then stop speaking: "${options.finalMessage}"` });
+		return this.armHangup();
+	}
+	/** Transfer the PSTN leg. Waits for current playback (and announcement). */
+	async transferTo(phoneNumber, options = {}) {
+		if (!this.deps.rest) throw new Error("transferTo requires Twilio REST credentials (BridgeConfig.twilio)");
+		if (this.stateValue === "ended" || this.stateValue === "ending") return;
+		this.pendingTransfer = {
+			phoneNumber,
+			callerId: options.callerId ?? this.deps.restCallerId
+		};
+		if (options.announcement) {
+			this.provider?.createResponse({ instructions: `Tell the caller now, briefly: "${options.announcement}". Then stop speaking.` });
+			return;
+		}
+		if (this.generating || this.tracker.isPlaybackActive()) return;
+		await this.executePendingTransfer();
+	}
+	/** Swap the active agent (swarm handoff). Accepts an Agent or its id. */
+	async handoffTo(agent) {
+		const targetId = typeof agent === "string" ? agent : agent.id;
+		const target = this.agents.get(targetId);
+		if (!target) throw new Error(`unknown agent "${targetId}" — agents must be reachable from the root agent's handoffs`);
+		await this.performHandoff(target);
+	}
+	/** Complete a `deferred` tool call from the host side. */
+	submitToolResult(toolCallId, result) {
+		this.completeDeferredFromHost(toolCallId, result);
+	}
+	/** Start background audio manually (independent of tools). */
+	async playBackgroundAudio(spec, options = {}) {
+		this.bgAudio.start(spec, {
+			startDelayMs: 0,
+			...options
+		});
+	}
+	async stopBackgroundAudio(options = {}) {
+		this.bgAudio.stop({ immediate: !options.fadeOutMs });
+	}
+	/** Immediate teardown (no goodbye). */
+	async end(reason = "agent-hangup") {
+		await this.teardown(reason);
+	}
+	buildToolset() {
+		const tools = /* @__PURE__ */ new Map();
+		const builtin = this.deps.builtinTools ?? {};
+		if (builtin.finishCall) {
+			const opts = typeof builtin.finishCall === "object" ? builtin.finishCall : {};
+			tools.set("finish_call", createFinishCallTool({
+				description: opts.description,
+				farewellInstruction: opts.farewellInstruction
+			}));
+		}
+		if (builtin.transferCall) {
+			const opts = builtin.transferCall;
+			tools.set("transfer_call", createTransferCallTool({
+				defaultPhoneNumber: opts.defaultPhoneNumber,
+				callerId: opts.callerId,
+				description: opts.description,
+				announcement: opts.announcement
+			}));
+		}
+		for (const target of this.activeAgentValue.handoffs) {
+			const handoffTool = createHandoffTool(target);
+			tools.set(handoffTool.name, handoffTool);
+		}
+		for (const tool of this.activeAgentValue.tools) {
+			if (tools.has(tool.name)) this.log.warn(`agent tool "${tool.name}" overrides a builtin of the same name`);
+			tools.set(tool.name, tool);
+		}
+		return tools;
+	}
+	buildProviderInit() {
+		return {
+			instructions: this.activeAgentValue.resolveInstructions(this.context) + (this.pregreeting ? `\n\nYou already opened the call by saying: "${this.pregreeting.text}". Do not greet again — continue the conversation from there.` : ""),
+			voice: this.activeAgentValue.voice,
+			vad: this.deps.options.vad,
+			bridgeOwnsInterruptions: true,
+			tools: [...this.toolset.values()].map((tool) => {
+				const decorated = decorateTool(tool, this.middlewares);
+				return {
+					name: tool.name,
+					description: decorated.description,
+					parameters: decorated.parameters
+				};
+			}),
+			providerOptions: this.activeAgentValue.providerOptions
+		};
+	}
+	wireTransport() {
+		const { transport } = this.deps;
+		transport.on("media", (event) => this.handleInboundMedia(event.media.payload));
+		transport.on("mark", (event) => this.handleMarkEcho(event.mark.name));
+		transport.on("dtmf", (event) => {
+			this.clearIdleTimer();
+			this.nudgeCount = 0;
+			this.emit("dtmf", { digit: event.dtmf.digit });
+		});
+		transport.on("stop", () => void this.teardown("caller-hangup"));
+		transport.on("close", () => void this.teardown("caller-hangup"));
+		transport.on("error", (error) => this.emitError(error));
+	}
+	/** Emit 'error'; when the host attached no listener, log instead of losing it. */
+	emitError(error) {
+		if (this.listenerCount("error") === 0) this.log.error("session error (no \"error\" listener attached)", { error: String(error) });
+		this.emit("error", error);
+	}
+	wireProvider(provider) {
+		provider.on("audio", (delta) => {
+			if (this.stateValue !== "active" && this.stateValue !== "ending") return;
+			if (!this.deps.transport.isOpen) return;
+			if (this.interruptedResponses.has(delta.responseId)) return;
+			this.bgAudio.notifyAgentAudio();
+			this.deps.transport.sendMedia(delta.base64Mulaw);
+			this.noteHangupProgress();
+			const chunkMs = base64ByteLength(delta.base64Mulaw) / 8;
+			const markName = this.tracker.onAudioSent(delta.responseId, chunkMs, delta.itemId);
+			if (markName) this.deps.transport.sendMark(markName);
+		});
+		provider.on("responseStarted", ({ responseId }) => {
+			this.generating = true;
+			this.currentResponseId = responseId;
+			this.blockedUserTurn = "idle";
+			if (this.pendingHangup) this.pendingHangup.sawResponse = true;
+			this.noteHangupProgress();
+			this.clearIdleTimer();
+			this.interruptions.onResponseStarted(responseId);
+			this.emit("agent.speech.started", { responseId });
+		});
+		provider.on("responseDone", ({ responseId, usage }) => {
+			this.generating = false;
+			const tailMark = this.tracker.onGenerationDone(responseId);
+			if (tailMark && this.deps.transport.isOpen) this.deps.transport.sendMark(tailMark);
+			this.emit("agent.speech.ended", { responseId });
+			if (usage) {
+				const total = this.usageAccumulator.add(usage);
+				this.emit("usage.updated", total, usage);
+			}
+			if (!this.tracker.isPlaybackActive()) {
+				if (this.runningTools.size === 0 && this.toolQueue.size === 0) this.firstTurnDone = true;
+				this.interruptions.onPlaybackEnded();
+				this.flushToolQueue();
+				this.executePendingTransfer();
+				this.maybeCompleteHangup();
+			}
+		});
+		provider.on("agentTranscript", ({ responseId, text }) => {
+			const entry = {
+				role: "agent",
+				text,
+				timestampMs: Date.now() - this.startedAtMs,
+				agentId: this.activeAgentValue.id,
+				...this.interruptedResponses.has(responseId) ? { interrupted: true } : {}
+			};
+			this.transcriptEntries.push(entry);
+			this.emit("transcript.agent", entry);
+		});
+		provider.on("userTranscript", ({ text }) => {
+			const entry = {
+				role: "user",
+				text,
+				timestampMs: Date.now() - this.startedAtMs
+			};
+			this.transcriptEntries.push(entry);
+			this.nudgeCount = 0;
+			this.emit("transcript.user", entry);
+		});
+		provider.on("userSpeechStarted", () => {
+			this.clearIdleTimer();
+			this.nudgeCount = 0;
+			this.emit("user.speech.started");
+			this.handleBargeIn();
+		});
+		provider.on("userSpeechStopped", () => {
+			if (this.blockedUserTurn === "speaking") this.blockedUserTurn = "committed";
+			this.emit("user.speech.ended");
+		});
+		provider.on("toolCall", (call) => void this.handleToolCall(call));
+		provider.on("error", (error) => this.emitError(error));
+		provider.on("close", (info) => {
+			if (this.stateValue === "ended" || this.stateValue === "ending") return;
+			if (this.handoffInProgress) return;
+			this.emit("provider.closed", {
+				code: info.code,
+				reason: info.reason
+			});
+			if (!info.retriable) {
+				this.fail(/* @__PURE__ */ new Error(`provider closed (${info.code} ${info.reason ?? ""})`), "provider-failed");
+				return;
+			}
+			this.scheduleReconnect();
+		});
+	}
+	handleInboundMedia(payload) {
+		if (this.stateValue === "ended" || this.stateValue === "ending") return;
+		if (this.pregreeting && !this.pregreeting.played) return;
+		if (this.deps.options.deafness.ignoreUserAudioUntilFirstTurnDone && !this.firstTurnDone) return;
+		if (this.deps.options.deafness.muteDuringToolExecution && this.runningTools.size > 0) return;
+		if (this.deps.options.deafness.muteWhileAgentSpeaking && this.tracker.isPlaybackActive()) return;
+		if (this.interruptions.isSuspended) return;
+		if (this.provider?.isConnected && !this.reconnecting) this.provider.sendAudio(payload);
+		else {
+			this.inboundBuffer.push(payload);
+			if (this.inboundBuffer.length > MAX_BUFFERED_INBOUND_FRAMES) this.inboundBuffer.shift();
+		}
+	}
+	flushInboundBuffer() {
+		if (!this.provider?.isConnected) return;
+		for (const payload of this.inboundBuffer) this.provider.sendAudio(payload);
+		this.inboundBuffer = [];
+	}
+	handleMarkEcho(name) {
+		if (name === PREGREETING_MARK) {
+			if (this.pregreeting && !this.pregreeting.played) {
+				this.pregreeting.played = true;
+				this.firstTurnDone = true;
+				this.emit("playback.finished", {
+					responseId: "pregreeting",
+					playedMs: this.pregreeting.durationMs
+				});
+				this.armIdleTimer();
+			}
+			return;
+		}
+		if (!PlaybackTracker.isTrackedMark(name)) return;
+		const result = this.tracker.onMarkEcho(name);
+		if (!result) return;
+		this.noteHangupProgress();
+		if (result.kind === "flushed") return;
+		if (result.playbackStarted) {
+			this.emit("playback.started", { responseId: result.responseId });
+			this.interruptions.onPlaybackStarted(result.responseId);
+		}
+		if (result.playbackFinished) this.onPlaybackFinished(result.responseId, result.playedMs);
+	}
+	onPlaybackFinished(responseId, playedMs) {
+		this.emit("playback.finished", {
+			responseId,
+			playedMs
+		});
+		this.firstTurnDone = true;
+		this.interruptions.onPlaybackEnded();
+		const hadQueuedToolResults = this.toolQueue.size > 0;
+		this.flushToolQueue();
+		this.executePendingTransfer();
+		this.maybeCompleteHangup();
+		if (this.blockedUserTurn === "committed") {
+			this.blockedUserTurn = "idle";
+			if (!hadQueuedToolResults && this.runningTools.size === 0) this.provider?.createResponse();
+		}
+		this.armIdleTimer();
+	}
+	handleBargeIn() {
+		if (!this.generating && !this.tracker.isPlaybackActive()) return;
+		const decision = this.interruptions.evaluate({ toolRunning: this.runningTools.size > 0 });
+		if (!decision.allow) {
+			if (decision.cause === "guard" || decision.cause === "disabled") this.blockedUserTurn = "speaking";
+			this.emit("interruption.blocked", { cause: decision.cause });
+			if (decision.instruction) this.provider?.sendText(decision.instruction, {
+				role: "system",
+				triggerResponse: true
+			});
+			return;
+		}
+		if (this.generating && this.provider?.capabilities.vadInterruptControl) this.provider.cancelResponse();
+		this.performInterrupt();
+	}
+	performInterrupt() {
+		const active = this.tracker.snapshotActive();
+		this.tracker.onClear();
+		this.interruptions.onPlaybackEnded();
+		if (this.deps.transport.isOpen) this.deps.transport.sendClear();
+		for (const response of active) {
+			this.interruptedResponses.add(response.responseId);
+			if (this.provider?.capabilities.truncate && response.itemId) this.provider.truncatePlayback(response.itemId, response.estimatedPlayedMs);
+			this.emit("playback.interrupted", {
+				responseId: response.responseId,
+				playedMs: response.estimatedPlayedMs
+			});
+			this.emit("interruption", {
+				responseId: response.responseId,
+				playedMs: response.estimatedPlayedMs
+			});
+		}
+		this.flushToolQueue();
+		if (this.pendingHangup?.sawResponse) this.completeHangup();
+	}
+	async handleToolCall(call) {
+		const tool = this.toolset.get(call.name);
+		const started = Date.now();
+		const baseInfo = {
+			toolCallId: call.id,
+			toolName: call.name,
+			agentId: this.activeAgentValue.id
+		};
+		if (!tool) {
+			this.log.warn(`model called unknown tool "${call.name}"`);
+			this.emit("tool.failed", {
+				...baseInfo,
+				strategy: "unknown",
+				error: "unknown tool"
+			});
+			this.deliverToolResult(call.id, { error: `Unknown tool: ${call.name}` });
+			return;
+		}
+		let rawInput;
+		try {
+			rawInput = call.argumentsJson.trim() === "" ? {} : JSON.parse(call.argumentsJson);
+		} catch {
+			this.deliverToolResult(call.id, {
+				error: "invalid_arguments",
+				message: "Tool arguments were not valid JSON. Retry with corrected arguments."
+			});
+			this.emit("tool.failed", {
+				...baseInfo,
+				strategy: tool.strategy,
+				error: "invalid JSON arguments"
+			});
+			return;
+		}
+		const parsed = tool.parameters.safeParse(rawInput);
+		if (!parsed.success) {
+			this.deliverToolResult(call.id, {
+				error: "validation_failed",
+				message: "Tool arguments failed validation. Fix them and retry.",
+				issues: parsed.error?.issues ?? []
+			});
+			this.emit("tool.failed", {
+				...baseInfo,
+				strategy: tool.strategy,
+				error: "argument validation failed"
+			});
+			return;
+		}
+		const input = parsed.data;
+		this.emit("tool.started", {
+			...baseInfo,
+			strategy: tool.strategy,
+			input
+		});
+		switch (tool.strategy) {
+			case "sync":
+				await this.runForegroundTool(tool, call, input, started);
+				break;
+			case "dispatch":
+				this.deliverToolResult(call.id, {
+					status: "queued",
+					note: "The task was dispatched and runs in the background. Continue the conversation naturally; do not mention internal processing."
+				});
+				this.runDetachedTool(tool, call, input, started, (outcome) => {
+					if (outcome.ok) this.emit("tool.completed", {
+						...baseInfo,
+						strategy: tool.strategy,
+						input,
+						result: outcome.result,
+						durationMs: Date.now() - started
+					});
+					else this.emit("tool.failed", {
+						...baseInfo,
+						strategy: tool.strategy,
+						error: outcome.message,
+						durationMs: Date.now() - started
+					});
+				});
+				break;
+			case "deferred":
+				this.deferredPending.set(call.id, { toolName: call.name });
+				this.deliverToolResult(call.id, {
+					status: "pending",
+					note: "The result is being prepared and will arrive shortly as a system message. Tell the caller you are looking into it and continue naturally."
+				});
+				this.runDetachedTool(tool, call, input, started, (outcome) => {
+					if (outcome.ok) {
+						this.completeDeferred(call.id, call.name, outcome.result);
+						this.emit("tool.completed", {
+							...baseInfo,
+							strategy: tool.strategy,
+							input,
+							result: outcome.result,
+							durationMs: Date.now() - started
+						});
+					} else {
+						this.completeDeferred(call.id, call.name, { error: outcome.message });
+						this.emit("tool.failed", {
+							...baseInfo,
+							strategy: tool.strategy,
+							error: outcome.message,
+							durationMs: Date.now() - started
+						});
+					}
+				});
+				break;
+			case "humanInTheLoop": this.requestApproval(tool, call, input);
+		}
+	}
+	/** sync path (also the approved HITL path): hold audio, execute, deliver. */
+	async runForegroundTool(tool, call, input, started) {
+		const baseInfo = {
+			toolCallId: call.id,
+			toolName: call.name,
+			agentId: this.activeAgentValue.id
+		};
+		this.acquireHoldAudio(call.id, tool);
+		try {
+			const outcome = await this.executeToolBody(tool, call, input);
+			if (outcome.ok && isHandoffDirective(outcome.result)) {
+				const directive = outcome.result;
+				const target = this.agents.get(directive.targetAgentId);
+				if (!target) {
+					this.deliverToolResult(call.id, { error: `unknown agent "${directive.targetAgentId}"` });
+					return;
+				}
+				this.deliverToolResult(call.id, {
+					status: "transferring_conversation",
+					to: target.name
+				}, false);
+				this.emit("tool.completed", {
+					...baseInfo,
+					strategy: tool.strategy,
+					input,
+					result: { handoffTo: target.id },
+					durationMs: Date.now() - started
+				});
+				await this.performHandoff(target, directive.reason);
+				return;
+			}
+			if (outcome.ok) {
+				this.deliverToolResult(call.id, outcome.result ?? { ok: true });
+				this.emit("tool.completed", {
+					...baseInfo,
+					strategy: tool.strategy,
+					input,
+					result: outcome.result,
+					durationMs: Date.now() - started
+				});
+				this.saveSnapshot();
+			} else {
+				this.deliverToolResult(call.id, outcome.payload);
+				this.emit("tool.failed", {
+					...baseInfo,
+					strategy: tool.strategy,
+					error: outcome.message,
+					durationMs: Date.now() - started
+				});
+			}
+		} finally {
+			this.bgAudio.release(call.id);
+		}
+	}
+	/** dispatch/deferred body — no hold audio (the model keeps talking). */
+	async runDetachedTool(tool, call, input, _started, onOutcome) {
+		onOutcome(await this.executeToolBody(tool, call, input));
+	}
+	/** Shared execution core: abort/timeout, middleware onion, per-tool hooks. */
+	async executeToolBody(tool, call, initialInput) {
+		const controller = new AbortController();
+		this.runningTools.set(call.id, controller);
+		const timeoutMs = tool.timeoutMs ?? 15e3;
+		const timeout = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("tool timed out")), timeoutMs);
+		this.timers.add(timeout);
+		const ctx = this.buildToolContext(call.id, controller.signal);
+		try {
+			let input = initialInput;
+			const innermost = async () => {
+				if (tool.onBeforeExecute) {
+					const replaced = await tool.onBeforeExecute(input, ctx);
+					if (replaced !== void 0) input = replaced;
+				}
+				let result = await this.raceAbort(Promise.resolve(tool.execute(input, ctx)), controller.signal);
+				if (tool.onAfterExecute) {
+					const replaced = await tool.onAfterExecute(result, ctx);
+					if (replaced !== void 0) result = replaced;
+				}
+				return result;
+			};
+			return {
+				ok: true,
+				result: await composeExecution(tool, input, ctx, this.middlewares, innermost)
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			let payload = {
+				error: "tool_failed",
+				message
+			};
+			if (tool.onError) try {
+				const replaced = await tool.onError(error, ctx);
+				if (replaced !== void 0) payload = replaced;
+			} catch {}
+			return {
+				ok: false,
+				payload,
+				message
+			};
+		} finally {
+			clearTimeout(timeout);
+			this.timers.delete(timeout);
+			this.runningTools.delete(call.id);
+		}
+	}
+	/** Inject a deferred result as a conversation turn (idempotent per call). */
+	completeDeferred(callId, toolName, result) {
+		if (!this.deferredPending.delete(callId)) return;
+		if (this.stateValue === "ended") return;
+		const text = `[Tool "${toolName}" finished] Result: ${safeJsonStringify(result)}. Share what is relevant with the caller now.`;
+		this.injectOrQueueText(text, true);
+	}
+	/** Complete a deferred tool from the host (webhook, operator console…). */
+	completeDeferredFromHost(toolCallId, result) {
+		const pending = this.deferredPending.get(toolCallId);
+		if (!pending) {
+			this.log.warn("submitToolResult for unknown/settled tool call", { toolCallId });
+			return;
+		}
+		this.completeDeferred(toolCallId, pending.toolName, result);
+	}
+	requestApproval(tool, call, input) {
+		const timeoutMs = tool.approvalTimeoutMs ?? 3e4;
+		const timer = setTimeout(() => {
+			this.rejectTool(call.id, "approval timed out");
+		}, timeoutMs);
+		timer.unref?.();
+		this.timers.add(timer);
+		this.approvals.set(call.id, {
+			call,
+			tool,
+			input,
+			timer
+		});
+		this.acquireHoldAudio(call.id, tool);
+		this.emit("tool.approval.required", {
+			approvalId: call.id,
+			toolCallId: call.id,
+			toolName: call.name,
+			input,
+			agentId: this.activeAgentValue.id,
+			expiresAtMs: Date.now() + timeoutMs
+		});
+	}
+	/** Approve a pending humanInTheLoop tool call (optionally editing input). */
+	approveTool(approvalId, editedInput) {
+		const entry = this.approvals.get(approvalId);
+		if (!entry) {
+			this.log.warn("approveTool for unknown approval", { approvalId });
+			return;
+		}
+		this.approvals.delete(approvalId);
+		clearTimeout(entry.timer);
+		this.timers.delete(entry.timer);
+		this.runForegroundTool(entry.tool, entry.call, editedInput !== void 0 ? editedInput : entry.input, Date.now());
+	}
+	/** Reject a pending humanInTheLoop tool call. */
+	rejectTool(approvalId, reason) {
+		const entry = this.approvals.get(approvalId);
+		if (!entry) return;
+		this.approvals.delete(approvalId);
+		clearTimeout(entry.timer);
+		this.timers.delete(entry.timer);
+		this.bgAudio.release(approvalId);
+		this.deliverToolResult(approvalId, {
+			error: "rejected",
+			message: reason ?? "A human operator declined this action. Tell the caller it cannot be done right now."
+		});
+		this.emit("tool.failed", {
+			toolCallId: approvalId,
+			toolName: entry.call.name,
+			strategy: entry.tool.strategy,
+			agentId: this.activeAgentValue.id,
+			error: reason ?? "rejected by operator"
+		});
+	}
+	acquireHoldAudio(holderId, tool) {
+		if (tool.backgroundAudio === false) return;
+		const sessionDefault = this.deps.options.toolBackgroundAudio;
+		const spec = tool.backgroundAudio ?? sessionDefault?.spec;
+		if (!spec) return;
+		this.bgAudio.acquire(holderId, spec, {
+			volume: sessionDefault?.volume,
+			fadeInMs: sessionDefault?.fadeInMs,
+			fadeOutMs: sessionDefault?.fadeOutMs,
+			startDelayMs: sessionDefault?.startDelayMs,
+			maxDurationMs: sessionDefault?.maxDurationMs
+		});
+	}
+	/** Inject a text turn now, or after the agent finishes speaking. */
+	injectOrQueueText(text, triggerResponse) {
+		if (this.generating || this.tracker.isPlaybackActive()) {
+			this.pendingInjections.push({
+				text,
+				triggerResponse
+			});
+			return;
+		}
+		this.provider?.sendText(text, {
+			role: "system",
+			triggerResponse
+		});
+	}
+	raceAbort(promise, signal) {
+		if (signal.aborted) return Promise.reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+		return new Promise((resolve, reject) => {
+			const onAbort = () => reject(signal.reason ?? /* @__PURE__ */ new Error("aborted"));
+			signal.addEventListener("abort", onAbort, { once: true });
+			promise.then((value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			}, (error) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(error);
+			});
+		});
+	}
+	deliverToolResult(callId, payload, triggerResponse = true) {
+		if (this.stateValue === "ended") return;
+		if (this.deps.options.toolResultDelivery === "afterPlayback" && (this.generating || this.tracker.isPlaybackActive())) {
+			this.toolQueue.enqueue({
+				callId,
+				toolName: "",
+				payload,
+				triggerResponse
+			});
+			return;
+		}
+		this.provider?.sendToolResult(callId, payload, { triggerResponse });
+	}
+	flushToolQueue() {
+		if (this.stateValue === "ended" || !this.provider?.isConnected) return;
+		const items = this.toolQueue.drain();
+		const wantTrigger = items.some((item) => item.triggerResponse);
+		for (const [index, item] of items.entries()) this.provider.sendToolResult(item.callId, item.payload, { triggerResponse: wantTrigger && index === items.length - 1 });
+		const injections = this.pendingInjections;
+		this.pendingInjections = [];
+		for (const injection of injections) this.provider.sendText(injection.text, {
+			role: "system",
+			triggerResponse: injection.triggerResponse
+		});
+	}
+	buildToolContext(toolCallId, signal) {
+		const session = {
+			callSid: this.callSid,
+			sendText: (text, options) => this.sendText(text, options),
+			finishCall: (options) => this.finishCall(options),
+			transferTo: (phoneNumber, options) => this.transferTo(phoneNumber, options),
+			handoffTo: (agent) => this.handoffTo(agent),
+			playBackgroundAudio: (spec, options) => this.playBackgroundAudio(spec, options),
+			stopBackgroundAudio: (options) => this.stopBackgroundAudio(options),
+			submitToolResult: (id, result) => this.submitToolResult(id, result)
+		};
+		return {
+			callSid: this.callSid,
+			agent: this.activeAgentValue,
+			session,
+			context: this.context,
+			callInfo: this.callInfo,
+			logger: this.log,
+			signal,
+			toolCallId
+		};
+	}
+	maybeGreet() {
+		if (this.greeted) return;
+		if (this.pregreeting) {
+			this.greeted = true;
+			return;
+		}
+		if (this.deps.options.greeting.mode !== "agent-initiates") return;
+		if (!this.provider?.isConnected) return;
+		if (this.callInfo.direction === "outbound" && !this.answered) return;
+		this.greeted = true;
+		this.provider.createResponse(this.deps.options.greeting.instructions ? { instructions: this.deps.options.greeting.instructions } : {});
+	}
+	armHangup() {
+		if (this.pendingHangup) return new Promise((resolve) => this.pendingHangup.resolvers.push(resolve));
+		this.pendingHangup = {
+			resolvers: [],
+			watchdog: this.armHangupWatchdog(),
+			sawResponse: false,
+			progress: 0,
+			progressAtCheck: 0
+		};
+		return new Promise((resolve) => this.pendingHangup.resolvers.push(resolve));
+	}
+	/** Evidence the goodbye is alive (generating or playing) — feeds the watchdog. */
+	noteHangupProgress() {
+		if (this.pendingHangup) this.pendingHangup.progress++;
+	}
+	/**
+	* Watchdog: forces completion only after a full quiet window — no deltas, no
+	* response start, no mark echoes for `markTimeoutMs`. Evidence re-arms it, so
+	* a slow or long goodbye is NEVER truncated mid-playout (wall-clock must not
+	* override live mark evidence); a dead socket or a model that never says
+	* goodbye still completes within one or two quiet windows.
+	*/
+	armHangupWatchdog() {
+		const timer = setTimeout(() => {
+			this.timers.delete(timer);
+			const pending = this.pendingHangup;
+			if (!pending) return;
+			if (pending.progress !== pending.progressAtCheck) {
+				pending.progressAtCheck = pending.progress;
+				pending.watchdog = this.armHangupWatchdog();
+				return;
+			}
+			this.log.warn("hangup watchdog fired — no goodbye progress for a full window");
+			this.completeHangup();
+		}, this.deps.options.hangup.markTimeoutMs);
+		timer.unref?.();
+		this.timers.add(timer);
+		return timer;
+	}
+	maybeCompleteHangup() {
+		if (!this.pendingHangup) return;
+		if (!this.pendingHangup.sawResponse) return;
+		if (this.generating || this.tracker.isPlaybackActive()) return;
+		this.completeHangup();
+	}
+	completeHangup() {
+		const pending = this.pendingHangup;
+		if (pending) {
+			clearTimeout(pending.watchdog);
+			this.timers.delete(pending.watchdog);
+		}
+		this.pendingHangup = null;
+		if (this.stateValue === "ended") {
+			pending?.resolvers.forEach((resolve) => resolve());
+			return;
+		}
+		this.stateValue = "ending";
+		const rest = this.deps.rest;
+		const reason = this.hangupReason;
+		const finish = () => void this.teardown(reason).then(() => {
+			pending?.resolvers.forEach((resolve) => resolve());
+		});
+		if (rest) rest.completeCall(this.callSid).catch((error) => this.log.warn("REST hangup failed; closing stream only", { error: String(error) })).finally(finish);
+		else finish();
+	}
+	async executePendingTransfer() {
+		const transfer = this.pendingTransfer;
+		if (!transfer || !this.deps.rest) return;
+		if (this.generating || this.tracker.isPlaybackActive()) return;
+		if (this.stateValue !== "active") return;
+		this.pendingTransfer = null;
+		this.stateValue = "ending";
+		try {
+			await this.deps.rest.transferCall(this.callSid, transfer.phoneNumber, { callerId: transfer.callerId });
+			await this.teardown("transferred");
+		} catch (error) {
+			this.stateValue = "active";
+			this.emitError(error instanceof Error ? error : new Error(String(error)));
+			this.log.error("transfer failed; call stays with the agent", { error: String(error) });
+		}
+	}
+	scheduleReconnect() {
+		const policy = this.deps.options.reconnect;
+		this.reconnectAttempt++;
+		if (this.reconnectAttempt > policy.maxAttempts) {
+			this.fail(/* @__PURE__ */ new Error(`provider reconnect exhausted after ${policy.maxAttempts} attempts`), "provider-failed");
+			return;
+		}
+		this.reconnecting = true;
+		const delayMs = delayForAttempt(policy, this.reconnectAttempt);
+		this.emit("provider.reconnecting", {
+			attempt: this.reconnectAttempt,
+			delayMs
+		});
+		const timer = setTimeout(() => {
+			this.timers.delete(timer);
+			this.reconnectProvider();
+		}, delayMs);
+		this.timers.add(timer);
+	}
+	async reconnectProvider() {
+		if (this.stateValue !== "active") return;
+		const provider = this.provider;
+		if (!provider) return;
+		try {
+			await provider.connect(this.buildProviderInit());
+		} catch (error) {
+			this.log.warn("reconnect attempt failed", {
+				attempt: this.reconnectAttempt,
+				error: String(error)
+			});
+			this.scheduleReconnect();
+			return;
+		}
+		if (this.stateValue !== "active") return;
+		this.reconnectAttempt = 0;
+		this.reconnecting = false;
+		if (!provider.didResume) this.reinjectHistory(provider);
+		this.flushInboundBuffer();
+		this.emit("provider.reconnected");
+	}
+	/** After a reconnect the provider session is blank — restore conversational context. */
+	reinjectHistory(provider) {
+		if (this.transcriptEntries.length === 0) return;
+		const summary = formatTranscriptForInjection(this.transcriptEntries);
+		provider.sendText(`Context: this phone call reconnected mid-conversation. Transcript so far:\n${summary}\nContinue naturally from where it left off; do not greet again.`, {
+			role: "system",
+			triggerResponse: false
+		});
+	}
+	async performHandoff(target, reason) {
+		if (this.stateValue !== "active" || !this.provider) return;
+		if (target.id === this.activeAgentValue.id) return;
+		const from = this.activeAgentValue;
+		this.activeAgentValue = target;
+		this.toolset = this.buildToolset();
+		this.handoffHistory.push({
+			from: from.id,
+			to: target.id,
+			atMs: Date.now() - this.startedAtMs
+		});
+		const continueInstruction = `You are now ${target.name}. Continue the SAME phone conversation naturally — acknowledge the caller and take over; do not restart with a cold greeting.` + (reason ? ` Transfer context: ${reason}.` : "");
+		const voiceChanges = target.voice !== void 0 && target.voice !== from.voice;
+		if (!(!this.provider.capabilities.sessionUpdate || voiceChanges && !this.provider.capabilities.voiceChangeMidSession && this.deps.options.handoffVoicePolicy === "reconnect")) {
+			if (voiceChanges && !this.provider.capabilities.voiceChangeMidSession) this.log.warn(`agent "${target.id}" declares voice "${target.voice}" but the provider cannot change voice mid-session — keeping the current voice (set handoffVoicePolicy: 'reconnect' to switch)`);
+			await this.provider.updateSession({
+				instructions: this.activeAgentValue.resolveInstructions(this.context),
+				tools: this.buildProviderInit().tools,
+				providerOptions: target.providerOptions
+			});
+			this.provider.createResponse({ instructions: continueInstruction });
+		} else {
+			this.handoffInProgress = true;
+			this.reconnecting = true;
+			const hold = this.deps.options.handoffHold;
+			if (hold) this.bgAudio.acquire("__handoff__", hold.spec, {
+				...hold,
+				startDelayMs: hold.startDelayMs ?? 300
+			});
+			try {
+				await this.provider.close();
+				await this.provider.connect({
+					...this.buildProviderInit(),
+					freshSession: true
+				});
+				this.reinjectHistory(this.provider);
+				this.provider.createResponse({ instructions: continueInstruction });
+			} catch (error) {
+				this.handoffInProgress = false;
+				this.reconnecting = false;
+				this.fail(error instanceof Error ? error : new Error(String(error)), "provider-failed");
+				return;
+			} finally {
+				this.bgAudio.release("__handoff__", { immediate: false });
+			}
+			this.handoffInProgress = false;
+			this.reconnecting = false;
+			this.flushInboundBuffer();
+		}
+		this.emit("agent.handoff", {
+			from,
+			to: target,
+			reason
+		});
+		this.saveSnapshot();
+	}
+	/**
+	* Burst-write a stored μ-law greeting straight onto the Twilio socket —
+	* no pacing loop (Twilio buffers and plays at line rate), so playback
+	* starts immediately while the provider session is still being built.
+	*/
+	playPreGreeting() {
+		const preSynthesized = this.deps.options.greeting.preSynthesized;
+		if (!preSynthesized || !this.deps.transport.isOpen) return;
+		let audio;
+		try {
+			audio = Buffer.isBuffer(preSynthesized.audio) ? preSynthesized.audio : readFileSync(preSynthesized.audio);
+		} catch (error) {
+			this.log.warn("pre-synthesized greeting unavailable — falling back to model greeting", { error: String(error) });
+			return;
+		}
+		if (audio.length === 0) return;
+		const durationMs = mulawBytesToMs(audio.length);
+		this.pregreeting = {
+			text: preSynthesized.text,
+			durationMs,
+			played: false
+		};
+		for (let offset = 0; offset < audio.length; offset += PREGREETING_CHUNK_BYTES) {
+			const chunk = audio.subarray(offset, Math.min(offset + PREGREETING_CHUNK_BYTES, audio.length));
+			this.deps.transport.sendMedia(chunk.toString("base64"));
+		}
+		this.deps.transport.sendMark(PREGREETING_MARK);
+		const entry = {
+			role: "agent",
+			text: preSynthesized.text,
+			timestampMs: 0,
+			agentId: this.activeAgentValue.id
+		};
+		this.transcriptEntries.push(entry);
+		this.emit("transcript.agent", entry);
+	}
+	/** Armed whenever the agent goes quiet and we're waiting on the caller. */
+	armIdleTimer() {
+		const idle = this.deps.options.idle;
+		if (!idle || this.stateValue !== "active" || this.pendingHangup) return;
+		this.clearIdleTimer();
+		this.idleTimer = setTimeout(() => {
+			this.idleTimer = null;
+			this.onIdleTimeout();
+		}, idle.timeoutSeconds * 1e3);
+		this.idleTimer.unref?.();
+	}
+	clearIdleTimer() {
+		if (this.idleTimer) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
+		}
+	}
+	onIdleTimeout() {
+		const idle = this.deps.options.idle;
+		if (!idle || this.stateValue !== "active" || !this.provider?.isConnected) return;
+		if (this.generating || this.tracker.isPlaybackActive() || this.runningTools.size > 0) {
+			this.armIdleTimer();
+			return;
+		}
+		const prompts = idle.prompts?.length ? idle.prompts : ["The caller has gone quiet. Gently check if they are still there."];
+		const maxNudges = idle.maxNudges ?? prompts.length;
+		if (this.nudgeCount < maxNudges) {
+			const prompt = prompts[Math.min(this.nudgeCount, prompts.length - 1)];
+			this.nudgeCount++;
+			this.provider.createResponse({ instructions: prompt });
+			return;
+		}
+		this.log.info("caller idle beyond nudges — ending call");
+		this.hangupReason = "idle-timeout";
+		this.provider.createResponse({ instructions: idle.goodbye ?? "You could not hear the caller anymore. Say a brief goodbye and that they are welcome to call back, then stop speaking." });
+		this.armHangup();
+	}
+	startMaxDurationWatchdog() {
+		const seconds = this.deps.options.maxCallDurationSeconds;
+		if (!seconds) return;
+		const timer = setTimeout(() => {
+			this.timers.delete(timer);
+			this.log.info("max call duration reached");
+			this.teardown("max-duration");
+		}, seconds * 1e3);
+		timer.unref?.();
+		this.timers.add(timer);
+	}
+	fail(error, reason) {
+		this.emit("call.failed", error);
+		this.teardown(reason);
+	}
+	async teardown(reason) {
+		if (this.stateValue === "ended") return;
+		this.stateValue = "ended";
+		this.endedReason = reason;
+		for (const timer of this.timers) clearTimeout(timer);
+		this.timers.clear();
+		this.clearIdleTimer();
+		this.bgAudio.stop({ immediate: true });
+		for (const controller of this.runningTools.values()) controller.abort(/* @__PURE__ */ new Error("call ended"));
+		this.runningTools.clear();
+		for (const approval of this.approvals.values()) clearTimeout(approval.timer);
+		this.approvals.clear();
+		this.deferredPending.clear();
+		this.pendingInjections = [];
+		this.toolQueue.clear();
+		this.inboundBuffer = [];
+		const pending = this.pendingHangup;
+		this.pendingHangup = null;
+		if (pending) {
+			clearTimeout(pending.watchdog);
+			pending.resolvers.forEach((resolve) => resolve());
+		}
+		const provider = this.provider;
+		this.provider = null;
+		if (provider) provider.removeAllListeners();
+		this.deps.transport.close();
+		const durationMs = Date.now() - this.startedAtMs;
+		this.emit("call.ended", {
+			reason,
+			durationMs,
+			usage: this.usage
+		});
+		if (provider) await provider.close().catch(() => {});
+		await this.saveSnapshot();
+		this.deps.onEnded?.(this.callSid, reason);
+	}
+	async saveSnapshot() {
+		const snapshot = {
+			callSid: this.callSid,
+			streamSid: this.streamSid,
+			state: this.stateValue,
+			activeAgentId: this.activeAgentValue.id,
+			transcript: [...this.transcriptEntries],
+			usage: this.usage,
+			context: this.context.toJSON(),
+			handoffHistory: [...this.handoffHistory],
+			startedAtMs: this.startedAtMs,
+			...this.stateValue === "ended" ? {
+				endedAtMs: Date.now(),
+				endReason: this.endedReason ?? void 0
+			} : {}
+		};
+		try {
+			await this.deps.store.save(snapshot);
+		} catch (error) {
+			this.log.warn("session store save failed", { error: String(error) });
+		}
+	}
+};
+const PREGREETING_MARK = "pre:greeting";
+/** 400ms per frame — matches production burst-write implementations. */
+const PREGREETING_CHUNK_BYTES = 3200;
+function safeJsonStringify(value) {
+	try {
+		return JSON.stringify(value) ?? "null";
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/bridge/config.ts
+const DEFAULT_SESSION_OPTIONS = {
+	greeting: { mode: "agent-initiates" },
+	interruptions: { enabled: true },
+	deafness: {
+		ignoreUserAudioUntilFirstTurnDone: true,
+		muteDuringToolExecution: true,
+		muteWhileAgentSpeaking: false
+	},
+	reconnect: DEFAULT_RECONNECT_POLICY,
+	hangup: { markTimeoutMs: 7e3 },
+	toolResultDelivery: "afterPlayback"
+};
+function resolveSessionOptions(partial) {
+	const resolved = deepMerge(structuredClone(DEFAULT_SESSION_OPTIONS), partial);
+	if (resolved.greeting.mode === "user-initiates" && partial?.deafness?.ignoreUserAudioUntilFirstTurnDone === void 0) resolved.deafness.ignoreUserAudioUntilFirstTurnDone = false;
+	return resolved;
+}
+//#endregion
+//#region src/bridge/TwilioRealtimeBridge.ts
+const MAX_ANSWERED_EARLY_ENTRIES = 1e3;
+var TwilioRealtimeBridge = class extends TypedEmitter {
+	config;
+	logger;
+	store;
+	rest;
+	sessionsBySid = /* @__PURE__ */ new Map();
+	/** Status callbacks can beat the media stream; remember early answers. */
+	answeredEarly = /* @__PURE__ */ new Set();
+	middlewares = [];
+	closed = false;
+	constructor(config) {
+		super();
+		this.config = config;
+		this.logger = config.logger ?? noopLogger;
+		this.store = config.store ?? new InMemorySessionStore();
+		if (config.twilio) this.rest = new TwilioRestClient({
+			accountSid: config.twilio.accountSid,
+			authToken: config.twilio.authToken,
+			callerId: config.twilio.callerId
+		});
+	}
+	/** Attach one incoming Twilio Media Stream WebSocket. */
+	handleConnection(ws, request) {
+		if (this.closed) {
+			try {
+				ws.close(1013, "bridge closed");
+			} catch {}
+			return;
+		}
+		const transport = new TwilioMediaTransport(ws);
+		this.handshake(transport, request);
+	}
+	/**
+	* Register cross-cutting tool middleware (first registered wraps
+	* outermost). Applies to sessions created after the call.
+	*/
+	use(middleware) {
+		this.middlewares.push(middleware);
+		return this;
+	}
+	getSession(callSid) {
+		return this.sessionsBySid.get(callSid);
+	}
+	sessions() {
+		return this.sessionsBySid;
+	}
+	/**
+	* Feed the outbound `answered` signal from your Twilio status callback so
+	* agent-initiated greetings fire when the human actually picks up.
+	*/
+	notifyAnswered(callSid) {
+		const session = this.sessionsBySid.get(callSid);
+		if (session) {
+			session.notifyAnswered();
+			return;
+		}
+		this.answeredEarly.add(callSid);
+		if (this.answeredEarly.size > MAX_ANSWERED_EARLY_ENTRIES) {
+			const oldest = this.answeredEarly.values().next().value;
+			if (oldest !== void 0) this.answeredEarly.delete(oldest);
+		}
+	}
+	/** Deterministically end every active session and stop accepting new ones. */
+	async close() {
+		this.closed = true;
+		const active = [...this.sessionsBySid.values()];
+		await Promise.allSettled(active.map((session) => session.end("bridge-closed")));
+		this.sessionsBySid.clear();
+	}
+	async handshake(transport, request) {
+		const handshakeOptions = typeof this.config.session === "object" ? this.config.session.handshake : void 0;
+		let start;
+		try {
+			start = await transport.awaitStart({
+				timeoutMs: handshakeOptions?.timeoutMs,
+				maxPreStartMessages: handshakeOptions?.maxPreStartMessages
+			});
+		} catch (error) {
+			this.logger.warn("media stream handshake failed", { error: String(error) });
+			this.emit("connection.rejected", { reason: "no-start-frame" });
+			transport.close(1008, "no start frame");
+			return;
+		}
+		const callSid = start.start.callSid;
+		try {
+			if (this.config.validateConnection) {
+				if (!await this.config.validateConnection(start, request)) {
+					this.emit("connection.rejected", { reason: "unauthorized" });
+					transport.close(1008, "unauthorized");
+					return;
+				}
+			}
+			if (this.sessionsBySid.has(callSid)) {
+				this.emit("connection.rejected", { reason: "duplicate-call" });
+				transport.close(1008, "duplicate stream for call");
+				return;
+			}
+			const agent = typeof this.config.agent === "function" ? await this.config.agent(start) : this.config.agent;
+			if (!(agent instanceof Agent)) throw new Error("BridgeConfig.agent must resolve to an Agent instance");
+			const options = resolveSessionOptions(typeof this.config.session === "function" ? await this.config.session(start) : this.config.session);
+			const answeredEarly = this.answeredEarly.delete(callSid);
+			const session = new CallSession({
+				transport,
+				start,
+				providerFactory: this.config.provider,
+				agent,
+				options,
+				store: this.store,
+				logger: this.logger,
+				builtinTools: this.config.builtinTools,
+				rest: this.rest,
+				restCallerId: this.config.twilio?.callerId,
+				middlewares: this.middlewares,
+				answeredEarly,
+				onEnded: (sid, reason) => this.onSessionEnded(sid, reason)
+			});
+			this.sessionsBySid.set(callSid, session);
+			this.emit("session.started", session);
+			await session.begin();
+		} catch (error) {
+			this.logger.error("failed to establish call session", {
+				callSid,
+				error: String(error)
+			});
+			this.emit("error", error instanceof Error ? error : new Error(String(error)));
+			this.sessionsBySid.delete(callSid);
+			transport.close(1011, "session setup failed");
+		}
+	}
+	onSessionEnded(callSid, reason) {
+		this.sessionsBySid.delete(callSid);
+		this.emit("session.ended", {
+			callSid,
+			reason
+		});
+	}
+};
+//#endregion
+//#region src/greeting/capture.ts
+/**
+* Capture a pre-synthesized greeting from a throwaway realtime session.
+*
+* Why not a TTS API? The realtime voice sets don't fully overlap the TTS
+* voice sets — capturing from a real session guarantees the stored greeting
+* sounds exactly like the live agent. Run this at deploy/config time and
+* store the returned μ-law buffer (it is Twilio wire format; pass it to
+* `greeting.preSynthesized.audio`).
+*/
+async function captureGreetingAudio(options) {
+	const url = `${options.baseUrl ?? "wss://api.openai.com/v1/realtime"}?model=${encodeURIComponent(options.model ?? "gpt-realtime")}`;
+	const ws = new WebSocket$1(url, { headers: {
+		Authorization: `Bearer ${options.apiKey}`,
+		...options.headers
+	} });
+	const chunks = [];
+	return new Promise((resolve, reject) => {
+		const timeoutMs = options.timeoutMs ?? 3e4;
+		const timer = setTimeout(() => {
+			try {
+				ws.close();
+			} catch {}
+			reject(/* @__PURE__ */ new Error(`greeting capture timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		timer.unref?.();
+		const finish = (error) => {
+			clearTimeout(timer);
+			try {
+				ws.close();
+			} catch {}
+			if (error) {
+				reject(error);
+				return;
+			}
+			const audio = Buffer.concat(chunks);
+			resolve({
+				audio,
+				text: options.text,
+				durationMs: audio.length / 8
+			});
+		};
+		ws.on("message", (raw) => {
+			let event;
+			try {
+				event = JSON.parse(raw.toString());
+			} catch {
+				return;
+			}
+			switch (event.type) {
+				case "session.created":
+					ws.send(JSON.stringify(buildSessionUpdate({
+						instructions: "You produce exact voice lines for a phone system.",
+						voice: options.voice,
+						vad: null,
+						transcription: false
+					}, { defaultVoice: options.voice })));
+					break;
+				case "session.updated":
+					ws.send(JSON.stringify({
+						type: "response.create",
+						response: { instructions: `Say exactly this, and nothing else: "${options.text}"` }
+					}));
+					break;
+				case "response.output_audio.delta":
+					if (typeof event.delta === "string") chunks.push(Buffer.from(event.delta, "base64"));
+					break;
+				case "response.done":
+					finish();
+					break;
+				case "error": finish(/* @__PURE__ */ new Error(`greeting capture failed: ${JSON.stringify(event.error ?? event)}`));
+			}
+		});
+		ws.on("error", (error) => finish(error instanceof Error ? error : new Error(String(error))));
+		ws.on("close", () => {
+			if (chunks.length > 0) finish();
+			else finish(/* @__PURE__ */ new Error("greeting capture connection closed before audio arrived"));
+		});
+	});
+}
+//#endregion
+export { Agent, BaseRealtimeProvider, CallSession, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, InMemorySessionStore, InterruptionController, PlaybackTracker, SessionContext, TwilioRealtimeBridge, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };