realtime-voice-agents 2.3.0 → 2.4.0

package/README.md

@@ -184,6 +184,10 @@ const receptionist = new Agent({ name: 'Receptionist', instructions: '…', hand
 
 Each agent in `handoffs` becomes a `transfer_to_<id>` tool. On handoff the session settles the function call, swaps instructions + tools (`session.update` on OpenAI/xAI; close-and-reopen with context carry on Gemini), and triggers a natural continuation — the caller never hears a seam. Also available programmatically: `session.handoffTo('billing')`. Cycles are fine (billing can hand back).
 
+**An agent that just took over cannot transfer again until the caller speaks.** The transfer tool is refused (`agent.handoff.blocked` fires, the model is told why, the active agent does not change); a caller turn — speech or a keypad entry — unlocks it. This makes transfer loops structurally impossible rather than merely discouraged: given the same replayed transcript, each incoming agent otherwise re-derives intent, decides the request is somebody else's, and passes it on. The trade-off is that a pure router node costs an extra caller turn, so direct arcs between agents beat hub-and-spoke. `session.handoffTo()` is host intent and bypasses the lock (it still arms it for the agent it installs).
+
+The context an incoming agent receives is attributed, not flat: each replayed line names the agent that said it, and completed transfers appear as `[transfer] A -> B (reason: …)` lines — so it can see what was already answered and already routed.
+
 ## Built-in call controls
 
 ```ts
@@ -301,7 +305,7 @@ session.on('dtmf', ({ digit }) => {
 
 ## Events (session)
 
-`call.started/ended/failed` · `provider.connected/fallback/reconnecting/reconnected/closed` · `agent.speech.started/ended` (generation) · **`playback.started/finished/interrupted`** (what the caller heard, mark-confirmed) · `user.speech.started/ended` · `transcript.user/agent` · `tool.started/completed/failed` · `tool.approval.required` · `agent.handoff` · `interruption` / `interruption.blocked` · `vad.suggestion` / `vad.adjusted` (noise-adaptive VAD) · `background_audio.started/stopped` · `dtmf` (raw keypress) · `keypad.entry` / `keypad.cleared` (keypad input) · `usage.updated` · `error`.
+`call.started/ended/failed` · `provider.connected/fallback/reconnecting/reconnected/closed` · `agent.speech.started/ended` (generation) · **`playback.started/finished/interrupted`** (what the caller heard, mark-confirmed) · `user.speech.started/ended` · `transcript.user/agent` · `tool.started/completed/failed` · `tool.approval.required` · `agent.handoff` / `agent.handoff.blocked` · `interruption` / `interruption.blocked` · `vad.suggestion` / `vad.adjusted` (noise-adaptive VAD) · `background_audio.started/stopped` · `dtmf` (raw keypress) · `keypad.entry` / `keypad.cleared` (keypad input) · `usage.updated` · `error`.
 
 ```ts
 bridge.on('session.started', (session) => {

package/dist/{InMemorySessionStore-B5_rq61L.d.cts → InMemorySessionStore-CRBmmCA6.d.cts}

@@ -9,6 +9,14 @@ interface TranscriptEntry {
   /** The caller cut this utterance off mid-playback. */
   interrupted?: boolean;
 }
+/** One completed transfer, as recorded in the session's handoff history. */
+interface HandoffRecord {
+  from: string;
+  to: string;
+  /** Milliseconds since call start. */
+  atMs: number;
+  reason?: string;
+}
 //#endregion
 //#region src/session/usage.d.ts
 /** Accumulated token consumption for a call, normalized across providers. */
@@ -40,11 +48,7 @@ interface CallSnapshot {
   transcript: TranscriptEntry[];
   usage: UsageInfo;
   context: Record<string, unknown>;
-  handoffHistory: Array<{
-    from: string;
-    to: string;
-    atMs: number;
-  }>;
+  handoffHistory: HandoffRecord[];
   /** Gemini session-resumption handle, when the provider supplies one. */
   resumptionHandle?: string;
   startedAtMs: number;
@@ -80,4 +84,4 @@ declare class InMemorySessionStore implements SessionStore {
   list(): CallSnapshot[];
 }
 //#endregion
-export { emptyUsage as a, UsageInfo as i, SessionStore as n, TranscriptEntry as o, CallSnapshot as r, InMemorySessionStore as t };
+export { emptyUsage as a, UsageInfo as i, SessionStore as n, HandoffRecord as o, CallSnapshot as r, TranscriptEntry as s, InMemorySessionStore as t };

package/dist/{InMemorySessionStore-B5_rq61L.d.mts → InMemorySessionStore-CRBmmCA6.d.mts}

@@ -9,6 +9,14 @@ interface TranscriptEntry {
   /** The caller cut this utterance off mid-playback. */
   interrupted?: boolean;
 }
+/** One completed transfer, as recorded in the session's handoff history. */
+interface HandoffRecord {
+  from: string;
+  to: string;
+  /** Milliseconds since call start. */
+  atMs: number;
+  reason?: string;
+}
 //#endregion
 //#region src/session/usage.d.ts
 /** Accumulated token consumption for a call, normalized across providers. */
@@ -40,11 +48,7 @@ interface CallSnapshot {
   transcript: TranscriptEntry[];
   usage: UsageInfo;
   context: Record<string, unknown>;
-  handoffHistory: Array<{
-    from: string;
-    to: string;
-    atMs: number;
-  }>;
+  handoffHistory: HandoffRecord[];
   /** Gemini session-resumption handle, when the provider supplies one. */
   resumptionHandle?: string;
   startedAtMs: number;
@@ -80,4 +84,4 @@ declare class InMemorySessionStore implements SessionStore {
   list(): CallSnapshot[];
 }
 //#endregion
-export { emptyUsage as a, UsageInfo as i, SessionStore as n, TranscriptEntry as o, CallSnapshot as r, InMemorySessionStore as t };
+export { emptyUsage as a, UsageInfo as i, SessionStore as n, HandoffRecord as o, CallSnapshot as r, TranscriptEntry as s, InMemorySessionStore as t };

package/dist/index.cjs

@@ -800,9 +800,34 @@ function delayForAttempt(policy, attempt, random = Math.random) {
 }
 //#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");
+/**
+* Render a transcript for history re-injection after reconnect/handoff.
+*
+* Agent lines are attributed to the agent that said them and completed
+* transfers are interleaved as `[transfer]` lines: an incoming agent handed a
+* flat `Agent:` dialogue re-derives intent from scratch, decides the request
+* belongs to somebody else, and transfers on — agents ping-ponging with no
+* caller turn between them (field bug, Aug 2026). Replaying WHO said what and
+* WHAT was already routed is what stops the second lap.
+*/
+function formatTranscriptForInjection(entries, options = {}) {
+	const { maxTurns = 30, agentNames, handoffs = [] } = options;
+	const recent = entries.slice(-maxTurns);
+	if (recent.length === 0) return "";
+	const nameOf = (agentId) => (agentId ? agentNames?.get(agentId) : void 0) ?? agentId ?? "Agent";
+	const windowStartMs = recent[0].timestampMs;
+	const lines = recent.map((entry) => ({
+		atMs: entry.timestampMs,
+		text: entry.role === "user" ? `Caller: ${entry.text}` : `${nameOf(entry.agentId)}: ${entry.text}`
+	}));
+	for (const handoff of handoffs) {
+		if (handoff.atMs < windowStartMs) continue;
+		lines.push({
+			atMs: handoff.atMs,
+			text: `[transfer] ${nameOf(handoff.from)} -> ${nameOf(handoff.to)}` + (handoff.reason ? ` (reason: ${handoff.reason})` : "")
+		});
+	}
+	return lines.sort((a, b) => a.atMs - b.atMs).map((line) => line.text).join("\n");
 }
 //#endregion
 //#region src/session/usage.ts
@@ -1049,6 +1074,15 @@ var CallSession = class extends require_events.TypedEmitter {
 	agents;
 	handoffHistory = [];
 	handoffInProgress = false;
+	/**
+	* An agent that just took over cannot transfer again until the caller has
+	* spoken. Without it every incoming agent re-derives intent from the same
+	* replayed transcript, decides the request is not its own, and transfers on
+	* — agents ping-ponging with no caller turn between them (field bug, Aug
+	* 2026). Programmatic `handoffTo()` is host intent and bypasses the lock,
+	* but still arms it for the agent it installs.
+	*/
+	handoffLockedUntilCallerTurn = false;
 	/** Pre-synthesized greeting playout state. */
 	pregreeting = null;
 	/** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -1432,11 +1466,13 @@ var CallSession = class extends require_events.TypedEmitter {
 			};
 			this.transcriptEntries.push(entry);
 			this.nudgeCount = 0;
+			this.handoffLockedUntilCallerTurn = false;
 			this.emit("transcript.user", entry);
 		});
 		provider.on("userSpeechStarted", () => {
 			this.userSpeechActive = true;
 			this.userSpeechStartedAtMs = Date.now();
+			this.handoffLockedUntilCallerTurn = false;
 			this.clearIdleTimer();
 			this.nudgeCount = 0;
 			this.emit("user.speech.started");
@@ -1732,6 +1768,17 @@ var CallSession = class extends require_events.TypedEmitter {
 					this.deliverToolResult(call.id, { error: `unknown agent "${directive.targetAgentId}"` });
 					return;
 				}
+				if (this.handoffLockedUntilCallerTurn) {
+					this.rejectHandoff(target, directive.reason, call.id);
+					this.emit("tool.completed", {
+						...baseInfo,
+						strategy: tool.strategy,
+						input,
+						result: { handoffBlocked: target.id },
+						durationMs: Date.now() - started
+					});
+					return;
+				}
 				this.deliverToolResult(call.id, {
 					status: "transferring_conversation",
 					to: target.name
@@ -2115,22 +2162,46 @@ var CallSession = class extends require_events.TypedEmitter {
 	/** 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.`, {
+		const summary = formatTranscriptForInjection(this.transcriptEntries, {
+			agentNames: new Map([...this.agents].map(([id, agent]) => [id, agent.name])),
+			handoffs: this.handoffHistory
+		});
+		provider.sendText(`Context: this phone call reconnected mid-conversation. You are ${this.activeAgentValue.name}. Each line below names who said it; \`[transfer]\` lines are routing that ALREADY happened.\n${summary}\nAnything already answered or already routed above must not be routed again. Continue naturally from where it left off; do not greet again.`, {
 			role: "system",
 			triggerResponse: false
 		});
 	}
+	/**
+	* Refuse a model-initiated transfer from an agent the caller has not spoken
+	* to yet. The refusal must reach the model as the tool result, or it simply
+	* calls the same transfer tool again on its next turn.
+	*/
+	rejectHandoff(target, reason, callId) {
+		const from = this.activeAgentValue;
+		this.log.warn(`blocked transfer ${from.id} -> ${target.id}: the caller has not spoken since the last one`);
+		this.deliverToolResult(callId, {
+			error: "transfer_rejected",
+			message: "You just took over this call and the caller has not spoken since. Do not transfer again yet — handle their request yourself, or ask them what they need. You may transfer once they reply."
+		});
+		this.emit("agent.handoff.blocked", {
+			from,
+			to: target,
+			reason,
+			cause: "no-caller-turn"
+		});
+	}
 	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.handoffLockedUntilCallerTurn = true;
 		this.toolset = this.buildToolset();
 		this.handoffHistory.push({
 			from: from.id,
 			to: target.id,
-			atMs: Date.now() - this.startedAtMs
+			atMs: Date.now() - this.startedAtMs,
+			...reason ? { reason } : {}
 		});
 		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;
@@ -2219,6 +2290,7 @@ var CallSession = class extends require_events.TypedEmitter {
 		this.keypadCollector.press(key);
 	}
 	onKeypadEntry(entry) {
+		this.handoffLockedUntilCallerTurn = false;
 		this.emit("keypad.entry", entry);
 		const message = this.deps.options.keypad?.message;
 		if (message === false) return;

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { n as BackgroundAudioPreset, r as BackgroundAudioSpec, t as BackgroundAu
 import { t as TypedEmitter } from "./events-BUMYdETO.cjs";
 import { _ as Logger, a as ProviderToolSchema, c as SessionUpdateOptions, d as ProviderCloseInfo, f as ProviderEvents, g as VadTuningProfile, h as ProviderCapabilities, i as ProviderSessionInit, l as VadConfig, m as ProviderUsage, n as ProviderFactory, o as SendTextOptions, p as ProviderToolCall, r as ProviderFactoryContext, s as SendToolResultOptions, t as BaseRealtimeProvider, u as ProviderAudioDelta, v as consoleLogger, y as noopLogger } from "./BaseRealtimeProvider-BL75_HHh.cjs";
 import { i as WebSocketLike, m as TwilioStartEvent, r as TwilioMediaTransport } from "./transport-B_PJFIVd.cjs";
-import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.cjs";
+import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.cjs";
 import { i as TwilioRestClient, n as connectStreamTwiml } from "./twiml-z9LjoF4_.cjs";
 import { IncomingMessage } from "node:http";
 //#region src/tools/tool.d.ts
@@ -798,6 +798,16 @@ interface SessionEventMap {
     to: Agent;
     reason?: string;
   }) => void;
+  /**
+   * A transfer the model asked for was refused. Fires INSTEAD of
+   * `agent.handoff` — the active agent did not change.
+   */
+  'agent.handoff.blocked': (info: {
+    from: Agent;
+    to: Agent;
+    reason?: string;
+    cause: string;
+  }) => void;
   interruption: (info: {
     responseId: string;
     playedMs: number;
@@ -920,6 +930,15 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private readonly agents;
   private readonly handoffHistory;
   private handoffInProgress;
+  /**
+   * An agent that just took over cannot transfer again until the caller has
+   * spoken. Without it every incoming agent re-derives intent from the same
+   * replayed transcript, decides the request is not its own, and transfers on
+   * — agents ping-ponging with no caller turn between them (field bug, Aug
+   * 2026). Programmatic `handoffTo()` is host intent and bypasses the lock,
+   * but still arms it for the agent it installs.
+   */
+  private handoffLockedUntilCallerTurn;
   /** Pre-synthesized greeting playout state. */
   private pregreeting;
   /** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -1069,6 +1088,12 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private reconnectProvider;
   /** After a reconnect the provider session is blank — restore conversational context. */
   private reinjectHistory;
+  /**
+   * Refuse a model-initiated transfer from an agent the caller has not spoken
+   * to yet. The refusal must reach the model as the tool result, or it simply
+   * calls the same transfer tool again on its next turn.
+   */
+  private rejectHandoff;
   private performHandoff;
   /**
    * Burst-write a stored μ-law greeting straight onto the Twilio socket —
@@ -1271,4 +1296,4 @@ declare class PlaybackTracker {
   private maybeForget;
 }
 //#endregion
-export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, KeypadCollector, type KeypadCollectorHooks, type KeypadEntry, type KeypadEntryReason, type KeypadHandle, type KeypadKeyKind, type KeypadOptions, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderFallbackInfo, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };
+export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HandoffRecord, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, KeypadCollector, type KeypadCollectorHooks, type KeypadEntry, type KeypadEntryReason, type KeypadHandle, type KeypadKeyKind, type KeypadOptions, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderFallbackInfo, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { n as BackgroundAudioPreset, r as BackgroundAudioSpec, t as BackgroundAu
 import { t as TypedEmitter } from "./events-BUMYdETO.mjs";
 import { _ as Logger, a as ProviderToolSchema, c as SessionUpdateOptions, d as ProviderCloseInfo, f as ProviderEvents, g as VadTuningProfile, h as ProviderCapabilities, i as ProviderSessionInit, l as VadConfig, m as ProviderUsage, n as ProviderFactory, o as SendTextOptions, p as ProviderToolCall, r as ProviderFactoryContext, s as SendToolResultOptions, t as BaseRealtimeProvider, u as ProviderAudioDelta, v as consoleLogger, y as noopLogger } from "./BaseRealtimeProvider-CWJ81HIt.mjs";
 import { i as WebSocketLike, m as TwilioStartEvent, r as TwilioMediaTransport } from "./transport-CEaLFV4E.mjs";
-import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.mjs";
+import { a as emptyUsage, i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.mjs";
 import { i as TwilioRestClient, n as connectStreamTwiml } from "./twiml-z9LjoF4_.mjs";
 import { IncomingMessage } from "node:http";
 //#region src/tools/tool.d.ts
@@ -798,6 +798,16 @@ interface SessionEventMap {
     to: Agent;
     reason?: string;
   }) => void;
+  /**
+   * A transfer the model asked for was refused. Fires INSTEAD of
+   * `agent.handoff` — the active agent did not change.
+   */
+  'agent.handoff.blocked': (info: {
+    from: Agent;
+    to: Agent;
+    reason?: string;
+    cause: string;
+  }) => void;
   interruption: (info: {
     responseId: string;
     playedMs: number;
@@ -920,6 +930,15 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private readonly agents;
   private readonly handoffHistory;
   private handoffInProgress;
+  /**
+   * An agent that just took over cannot transfer again until the caller has
+   * spoken. Without it every incoming agent re-derives intent from the same
+   * replayed transcript, decides the request is not its own, and transfers on
+   * — agents ping-ponging with no caller turn between them (field bug, Aug
+   * 2026). Programmatic `handoffTo()` is host intent and bypasses the lock,
+   * but still arms it for the agent it installs.
+   */
+  private handoffLockedUntilCallerTurn;
   /** Pre-synthesized greeting playout state. */
   private pregreeting;
   /** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -1069,6 +1088,12 @@ declare class CallSession extends TypedEmitter<SessionEventMap> {
   private reconnectProvider;
   /** After a reconnect the provider session is blank — restore conversational context. */
   private reinjectHistory;
+  /**
+   * Refuse a model-initiated transfer from an agent the caller has not spoken
+   * to yet. The refusal must reach the model as the tool result, or it simply
+   * calls the same transfer tool again on its next turn.
+   */
+  private rejectHandoff;
   private performHandoff;
   /**
    * Burst-write a stored μ-law greeting straight onto the Twilio socket —
@@ -1271,4 +1296,4 @@ declare class PlaybackTracker {
   private maybeForget;
 }
 //#endregion
-export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, KeypadCollector, type KeypadCollectorHooks, type KeypadEntry, type KeypadEntryReason, type KeypadHandle, type KeypadKeyKind, type KeypadOptions, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderFallbackInfo, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };
+export { Agent, type AgentDefinition, type ApprovalRequestInfo, type BackgroundAudioOptions, type BackgroundAudioPreset, type BackgroundAudioSpec, BaseRealtimeProvider, type BridgeConfig, type BridgeEventMap, type BuiltinToolsConfig, type CallEndReason, CallSession, type CallSessionFacade, type CallSnapshot, type CallStartedInfo, type CallState, type CaptureGreetingOptions, type CapturedGreeting, DEFAULT_KEYPAD_CLEAR_MESSAGE, DEFAULT_KEYPAD_INSTRUCTIONS, DEFAULT_KEYPAD_OPTIONS, DEFAULT_RECONNECT_POLICY, DEFAULT_SESSION_OPTIONS, type DeafnessOptions, type FinishCallToolOptions, type GreetingOptions, type HandoffDirective, type HandoffRecord, type HangupOptions, type IdleOptions, InMemorySessionStore, type InferSchema, type InterruptionBlockCause, InterruptionController, type InterruptionDecision, type InterruptionRateLimit, type InterruptionSettings, KeypadCollector, type KeypadCollectorHooks, type KeypadEntry, type KeypadEntryReason, type KeypadHandle, type KeypadKeyKind, type KeypadOptions, type Logger, type MarkEchoResult, NoiseAdaptiveVadController, type NoiseAdaptiveVadOptions, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderFallbackInfo, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, type SessionUpdateOptions, type Tool, type ToolCallInfo, type ToolContext, type ToolDecoration, type ToolDefinition, type ToolMiddleware, type ToolRunInfo, type ToolStrategy, type TranscriptEntry, type TransferCallToolOptions, TwilioRealtimeBridge, type TwilioRestOptions, type TwilioStartEvent, type UsageInfo, type VadAdjustment, type VadConfig, type VadNoiseMetrics, type VadSuggestionInfo, type VadTuningProfile, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, defaultKeypadMessage, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };

package/dist/index.mjs

@@ -796,9 +796,34 @@ function delayForAttempt(policy, attempt, random = Math.random) {
 }
 //#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");
+/**
+* Render a transcript for history re-injection after reconnect/handoff.
+*
+* Agent lines are attributed to the agent that said them and completed
+* transfers are interleaved as `[transfer]` lines: an incoming agent handed a
+* flat `Agent:` dialogue re-derives intent from scratch, decides the request
+* belongs to somebody else, and transfers on — agents ping-ponging with no
+* caller turn between them (field bug, Aug 2026). Replaying WHO said what and
+* WHAT was already routed is what stops the second lap.
+*/
+function formatTranscriptForInjection(entries, options = {}) {
+	const { maxTurns = 30, agentNames, handoffs = [] } = options;
+	const recent = entries.slice(-maxTurns);
+	if (recent.length === 0) return "";
+	const nameOf = (agentId) => (agentId ? agentNames?.get(agentId) : void 0) ?? agentId ?? "Agent";
+	const windowStartMs = recent[0].timestampMs;
+	const lines = recent.map((entry) => ({
+		atMs: entry.timestampMs,
+		text: entry.role === "user" ? `Caller: ${entry.text}` : `${nameOf(entry.agentId)}: ${entry.text}`
+	}));
+	for (const handoff of handoffs) {
+		if (handoff.atMs < windowStartMs) continue;
+		lines.push({
+			atMs: handoff.atMs,
+			text: `[transfer] ${nameOf(handoff.from)} -> ${nameOf(handoff.to)}` + (handoff.reason ? ` (reason: ${handoff.reason})` : "")
+		});
+	}
+	return lines.sort((a, b) => a.atMs - b.atMs).map((line) => line.text).join("\n");
 }
 //#endregion
 //#region src/session/usage.ts
@@ -1045,6 +1070,15 @@ var CallSession = class extends TypedEmitter {
 	agents;
 	handoffHistory = [];
 	handoffInProgress = false;
+	/**
+	* An agent that just took over cannot transfer again until the caller has
+	* spoken. Without it every incoming agent re-derives intent from the same
+	* replayed transcript, decides the request is not its own, and transfers on
+	* — agents ping-ponging with no caller turn between them (field bug, Aug
+	* 2026). Programmatic `handoffTo()` is host intent and bypasses the lock,
+	* but still arms it for the agent it installs.
+	*/
+	handoffLockedUntilCallerTurn = false;
 	/** Pre-synthesized greeting playout state. */
 	pregreeting = null;
 	/** Noise-adaptive VAD (opt-in); built after connect from the provider's ACKed config. */
@@ -1428,11 +1462,13 @@ var CallSession = class extends TypedEmitter {
 			};
 			this.transcriptEntries.push(entry);
 			this.nudgeCount = 0;
+			this.handoffLockedUntilCallerTurn = false;
 			this.emit("transcript.user", entry);
 		});
 		provider.on("userSpeechStarted", () => {
 			this.userSpeechActive = true;
 			this.userSpeechStartedAtMs = Date.now();
+			this.handoffLockedUntilCallerTurn = false;
 			this.clearIdleTimer();
 			this.nudgeCount = 0;
 			this.emit("user.speech.started");
@@ -1728,6 +1764,17 @@ var CallSession = class extends TypedEmitter {
 					this.deliverToolResult(call.id, { error: `unknown agent "${directive.targetAgentId}"` });
 					return;
 				}
+				if (this.handoffLockedUntilCallerTurn) {
+					this.rejectHandoff(target, directive.reason, call.id);
+					this.emit("tool.completed", {
+						...baseInfo,
+						strategy: tool.strategy,
+						input,
+						result: { handoffBlocked: target.id },
+						durationMs: Date.now() - started
+					});
+					return;
+				}
 				this.deliverToolResult(call.id, {
 					status: "transferring_conversation",
 					to: target.name
@@ -2111,22 +2158,46 @@ var CallSession = class extends TypedEmitter {
 	/** 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.`, {
+		const summary = formatTranscriptForInjection(this.transcriptEntries, {
+			agentNames: new Map([...this.agents].map(([id, agent]) => [id, agent.name])),
+			handoffs: this.handoffHistory
+		});
+		provider.sendText(`Context: this phone call reconnected mid-conversation. You are ${this.activeAgentValue.name}. Each line below names who said it; \`[transfer]\` lines are routing that ALREADY happened.\n${summary}\nAnything already answered or already routed above must not be routed again. Continue naturally from where it left off; do not greet again.`, {
 			role: "system",
 			triggerResponse: false
 		});
 	}
+	/**
+	* Refuse a model-initiated transfer from an agent the caller has not spoken
+	* to yet. The refusal must reach the model as the tool result, or it simply
+	* calls the same transfer tool again on its next turn.
+	*/
+	rejectHandoff(target, reason, callId) {
+		const from = this.activeAgentValue;
+		this.log.warn(`blocked transfer ${from.id} -> ${target.id}: the caller has not spoken since the last one`);
+		this.deliverToolResult(callId, {
+			error: "transfer_rejected",
+			message: "You just took over this call and the caller has not spoken since. Do not transfer again yet — handle their request yourself, or ask them what they need. You may transfer once they reply."
+		});
+		this.emit("agent.handoff.blocked", {
+			from,
+			to: target,
+			reason,
+			cause: "no-caller-turn"
+		});
+	}
 	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.handoffLockedUntilCallerTurn = true;
 		this.toolset = this.buildToolset();
 		this.handoffHistory.push({
 			from: from.id,
 			to: target.id,
-			atMs: Date.now() - this.startedAtMs
+			atMs: Date.now() - this.startedAtMs,
+			...reason ? { reason } : {}
 		});
 		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;
@@ -2215,6 +2286,7 @@ var CallSession = class extends TypedEmitter {
 		this.keypadCollector.press(key);
 	}
 	onKeypadEntry(entry) {
+		this.handoffLockedUntilCallerTurn = false;
 		this.emit("keypad.entry", entry);
 		const message = this.deps.options.keypad?.message;
 		if (message === false) return;

package/dist/store.d.cts

@@ -1,2 +1,2 @@
-import { i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.cjs";
-export { type CallSnapshot, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };
+import { i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.cjs";
+export { type CallSnapshot, type HandoffRecord, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };

package/dist/store.d.mts

@@ -1,2 +1,2 @@
-import { i as UsageInfo, n as SessionStore, o as TranscriptEntry, r as CallSnapshot, t as InMemorySessionStore } from "./InMemorySessionStore-B5_rq61L.mjs";
-export { type CallSnapshot, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };
+import { i as UsageInfo, n as SessionStore, o as HandoffRecord, r as CallSnapshot, s as TranscriptEntry, t as InMemorySessionStore } from "./InMemorySessionStore-CRBmmCA6.mjs";
+export { type CallSnapshot, type HandoffRecord, InMemorySessionStore, type SessionStore, type TranscriptEntry, type UsageInfo };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-voice-agents",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Provider-agnostic bridge between Twilio Media Streams and realtime speech-to-speech AI APIs (OpenAI Realtime, xAI Grok Voice, Gemini Live). Multi-agent handoffs, Zod tools with execution strategies, mark-based playback tracking, interruption guards, and hold audio — for Node.js voice agents over the phone.",
   "keywords": [
     "twilio",