realtime-voice-agents 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,920 @@
+import { n as BackgroundAudioPreset, r as BackgroundAudioSpec, t as BackgroundAudioOptions } from "./presets-Bf75YXs5.mjs";
+import { t as TypedEmitter } from "./events-BUMYdETO.mjs";
+import { _ as noopLogger, a as ProviderToolSchema, c as VadConfig, d as ProviderEvents, f as ProviderToolCall, g as consoleLogger, h as Logger, i as ProviderSessionInit, l as ProviderAudioDelta, m as ProviderCapabilities, n as ProviderFactory, o as SendTextOptions, p as ProviderUsage, r as ProviderFactoryContext, s as SendToolResultOptions, t as BaseRealtimeProvider, u as ProviderCloseInfo } from "./BaseRealtimeProvider-ClP8Wx1X.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 { i as TwilioRestClient, n as connectStreamTwiml } from "./twiml-z9LjoF4_.mjs";
+import { IncomingMessage } from "node:http";
+//#region src/tools/tool.d.ts
+/** Structural Zod schema shape — works with both Zod 3 and Zod 4. */
+interface ZodSchemaLike {
+  safeParse(data: unknown): {
+    success: true;
+    data: any;
+  } | {
+    success: false;
+    error: {
+      message?: string;
+      issues?: unknown[];
+    };
+  };
+}
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Output type of a Zod schema, for either Zod major. */
+type InferSchema<S> = IsAny<S> extends true ? any : S extends {
+  _zod: {
+    output: infer O;
+  };
+} ? O : S extends {
+  _output: infer O;
+} ? O : unknown;
+/**
+ * How a tool call is executed relative to the conversation:
+ * - `sync` — the model waits for the result before speaking (default)
+ * - `dispatch` — fire-and-forget: the model immediately gets `{status:'queued'}`
+ *   and keeps talking; the work runs detached
+ * - `deferred` — the model gets `{status:'pending'}` and keeps talking; the
+ *   real result is injected as a new turn when it arrives
+ * - `humanInTheLoop` — execution pauses for `session.approveTool()` /
+ *   `rejectTool()`; an approval event fires for your backend
+ */
+type ToolStrategy = 'sync' | 'dispatch' | 'deferred' | 'humanInTheLoop';
+interface ToolDefinition<S extends ZodSchemaLike = ZodSchemaLike, Out = unknown> {
+  /** Function name shown to the model: [a-zA-Z0-9_-], ≤64 chars. */
+  name: string;
+  description: string;
+  parameters: S;
+  execute: (input: InferSchema<S>, ctx: ToolContext) => Out | Promise<Out>;
+  strategy?: ToolStrategy;
+  /** Abort execute() and return a timeout error to the model. Default 15000. */
+  timeoutMs?: number;
+  /** Hold audio while the tool runs. `false` disables even bridge defaults. */
+  backgroundAudio?: BackgroundAudioSpec | false;
+  /** For `humanInTheLoop`: auto-reject if not approved in time. Default 30000. */
+  approvalTimeoutMs?: number;
+  /** May veto (throw) or replace the input. */
+  onBeforeExecute?: (input: InferSchema<S>, ctx: ToolContext) => void | InferSchema<S> | Promise<void | InferSchema<S>>;
+  /** May observe or replace the result sent to the model. */
+  onAfterExecute?: (result: Out, ctx: ToolContext) => void | unknown | Promise<void | unknown>;
+  /** May map an error to a model-visible payload (instead of a generic one). */
+  onError?: (error: unknown, ctx: ToolContext) => void | unknown | Promise<void | unknown>;
+}
+interface Tool<S extends ZodSchemaLike = any, Out = any> extends ToolDefinition<S, Out> {
+  strategy: ToolStrategy;
+  /** JSON Schema for the provider tool declaration (computed once). */
+  readonly parametersJsonSchema: Record<string, unknown>;
+}
+/** Define a provider-agnostic tool with a Zod parameters schema. */
+declare function tool<S extends ZodSchemaLike, Out>(definition: ToolDefinition<S, Out>): Tool<S, Out>;
+//#endregion
+//#region src/agents/Agent.d.ts
+interface AgentDefinition {
+  /** Human-readable name ("Billing Department"). */
+  name: string;
+  /** Stable id used in handoff tool names; derived from name if omitted. */
+  id?: string;
+  /** System instructions — static or computed from session context. */
+  instructions: string | ((context: SessionContext) => string);
+  voice?: string;
+  /** Provider model override for this agent (used where supported). */
+  model?: string;
+  tools?: Tool[];
+  /** Agents this one can hand the call to (transfer tools are generated). */
+  handoffs?: Agent[];
+  /** Shown to the transferring model as the transfer tool's description. */
+  handoffDescription?: string;
+  /** Provider-native session options for this agent (escape hatch). */
+  providerOptions?: Record<string, unknown>;
+}
+declare class Agent {
+  readonly id: string;
+  readonly name: string;
+  readonly voice?: string;
+  readonly model?: string;
+  readonly tools: Tool[];
+  readonly handoffs: Agent[];
+  readonly handoffDescription?: string;
+  readonly providerOptions?: Record<string, unknown>;
+  private readonly instructionsSource;
+  constructor(definition: AgentDefinition);
+  resolveInstructions(context: SessionContext): string;
+}
+/**
+ * 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.
+ */
+declare function collectAgentGraph(root: Agent): Map<string, Agent>;
+//#endregion
+//#region src/tools/context.d.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.
+ */
+declare class SessionContext {
+  private readonly data;
+  constructor(initial?: Record<string, unknown>);
+  get<T = unknown>(key: string): T | undefined;
+  set(key: string, value: unknown): void;
+  has(key: string): boolean;
+  delete(key: string): boolean;
+  toJSON(): Record<string, unknown>;
+}
+interface ToolCallInfo {
+  from?: string;
+  to?: string;
+  direction: 'inbound' | 'outbound';
+  customParameters: Record<string, string>;
+}
+/**
+ * Capability closures handed to tools — everything a tool may do to the live
+ * call without ever touching the engine, the provider socket, or the Twilio
+ * SDK (the sinwan ToolControl pattern).
+ */
+interface CallSessionFacade {
+  readonly callSid: string;
+  /** Inject a text turn (e.g. steer the model or log a system note). */
+  sendText(text: string, options?: {
+    role?: 'user' | 'system';
+    triggerResponse?: boolean;
+  }): void;
+  /** Gracefully end the call (goodbye-aware two-phase hangup). */
+  finishCall(options?: {
+    finalMessage?: string;
+  }): Promise<void>;
+  /** Transfer the PSTN leg to another number (announced, playout-aware). */
+  transferTo(phoneNumber: string, options?: {
+    callerId?: string;
+    announcement?: string;
+  }): Promise<void>;
+  /** Swap the active agent (multi-agent handoff). */
+  handoffTo(agent: Agent | string): Promise<void>;
+  /** Start/stop background audio manually. */
+  playBackgroundAudio(spec: BackgroundAudioSpec, options?: {
+    volume?: number;
+  }): Promise<void>;
+  stopBackgroundAudio(options?: {
+    fadeOutMs?: number;
+  }): Promise<void>;
+  /** Complete a `deferred` tool from outside its execute() promise. */
+  submitToolResult(toolCallId: string, result: unknown): void;
+}
+interface ToolContext {
+  callSid: string;
+  /** The agent this tool call belongs to. */
+  agent: Agent;
+  session: CallSessionFacade;
+  context: SessionContext;
+  callInfo: ToolCallInfo;
+  logger: Logger;
+  /** Aborted on tool timeout or call teardown — pass to fetch etc. */
+  signal: AbortSignal;
+  /** Provider tool-call id (correlates deferred results). */
+  toolCallId: string;
+}
+//#endregion
+//#region src/tools/middleware.d.ts
+interface ToolDecoration {
+  description?: string;
+  parameters?: Record<string, unknown>;
+}
+interface ToolMiddleware {
+  /** Rewrite the schema/description the model is shown for this tool. */
+  decorate?(tool: Tool): ToolDecoration | void;
+  /** Wrap execution; call `next()` to proceed inward, or short-circuit. */
+  wrapExecute?(tool: Tool, input: unknown, ctx: ToolContext, next: () => Promise<unknown>): Promise<unknown>;
+}
+/** Apply every middleware's decoration, first-registered first. */
+declare function decorateTool(tool: Tool, middlewares: readonly ToolMiddleware[]): {
+  description: string;
+  parameters: Record<string, unknown>;
+};
+/** Compose wrapExecute chains around an innermost executor. */
+declare function composeExecution(tool: Tool, input: unknown, ctx: ToolContext, middlewares: readonly ToolMiddleware[], innermost: () => Promise<unknown>): Promise<unknown>;
+//#endregion
+//#region src/interruption/InterruptionController.d.ts
+/**
+ * InterruptionController — decides whether a barge-in is honored.
+ *
+ * Gate order (first match wins): disabled → suspended (noise cooldown) →
+ * tool running → guard window. The guard window protects the start of a
+ * response for a flat duration measured from playback start (mark-echo
+ * truth, not generation time). To make the whole first turn uninterruptible,
+ * use `deafness.ignoreUserAudioUntilFirstTurnDone` instead.
+ *
+ * The rate limiter is the noisy-environment defense from production systems:
+ * too many barge-ins inside a sliding window suspends interruptions until the
+ * current playback ends, optionally injecting an instruction so the agent can
+ * say "please move somewhere quieter".
+ */
+interface InterruptionRateLimit {
+  windowMs: number;
+  /** Barge-ins inside the window that trip the limiter. */
+  threshold: number;
+  /** Injected once, on the rising edge, when the limiter trips. */
+  instruction?: string;
+}
+interface InterruptionSettings {
+  /** Master switch. Default true. */
+  enabled?: boolean;
+  /** No-barge window measured from playback start of each response, ms. */
+  guardDurationMs?: number;
+  /** Apply the guard only to the first response of the call. Default false. */
+  firstResponseOnly?: boolean;
+  rateLimit?: InterruptionRateLimit;
+}
+type InterruptionBlockCause = 'disabled' | 'guard' | 'rate_limit' | 'tool_running' | 'suspended';
+type InterruptionDecision = {
+  allow: true;
+} | {
+  allow: false;
+  cause: InterruptionBlockCause;
+  instruction?: string;
+};
+declare class InterruptionController {
+  private readonly settings;
+  private readonly now;
+  private responseIndex;
+  private guardStartedAt;
+  private guardResponseId;
+  /** The guarded response's audio has not finished (or been flushed) yet. */
+  private guardPlaybackOpen;
+  /** Responses that began while the guarded one was still playing. */
+  private deferredStarts;
+  private suspended;
+  private bargeInTimestamps;
+  constructor(settings?: InterruptionSettings, now?: () => number);
+  get isSuspended(): boolean;
+  /** A new response started generating: rotate the guard to it. */
+  onResponseStarted(responseId: string): void;
+  /** Playback of a response reached the caller: the guard clock starts now. */
+  onPlaybackStarted(responseId: string): void;
+  /** Current playback finished or was cleared: cooldown suspension ends. */
+  onPlaybackEnded(): void;
+  /**
+   * Evaluate a barge-in attempt (user speech while the agent is audible).
+   * Every attempt counts toward the rate limiter, including blocked ones.
+   */
+  evaluate(context: {
+    toolRunning: boolean;
+  }): InterruptionDecision;
+  private guardActive;
+}
+//#endregion
+//#region src/providers/base/reconnect.d.ts
+/** Exponential backoff with optional full jitter, shared by all providers. */
+interface ReconnectPolicy {
+  /** Attempts before giving up. 0 disables reconnection. */
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  /** Full jitter: each delay is uniform in [0, computed]. */
+  jitter: boolean;
+}
+declare const DEFAULT_RECONNECT_POLICY: ReconnectPolicy;
+//#endregion
+//#region src/bridge/config.d.ts
+interface GreetingOptions {
+  /**
+   * `agent-initiates`: the agent speaks first (silence on answer reads as a
+   * dropped call). `user-initiates`: wait for the caller.
+   */
+  mode: 'agent-initiates' | 'user-initiates';
+  /** Extra instructions for the opening response. */
+  instructions?: string;
+  /**
+   * Pre-synthesized greeting: burst-written to the caller while the provider
+   * connects (~seconds faster to first word). `audio` is 8 kHz μ-law (raw
+   * buffer or file path); `text` is what it says, used to keep the model from
+   * greeting twice.
+   */
+  preSynthesized?: {
+    audio: Buffer | string;
+    text: string;
+  };
+}
+interface DeafnessOptions {
+  /**
+   * Drop caller audio until the agent's first turn finishes playing.
+   * Protects the greeting from noisy pickups. Default true — except with
+   * `greeting.mode: 'user-initiates'`, where the caller must be heard to
+   * start the call at all, so the default flips to false. An explicit true
+   * is honored even there, but deafens the call until something else
+   * (an idle nudge, a tool) produces the agent's first turn.
+   */
+  ignoreUserAudioUntilFirstTurnDone?: boolean;
+  /** Drop caller audio while a foreground tool is running. Default true. */
+  muteDuringToolExecution?: boolean;
+  /**
+   * Drop caller audio while agent audio is audibly playing (half-duplex).
+   * Nothing said while the agent speaks reaches the provider — it is lost,
+   * not queued — so its VAD cannot fire mid-playback. (Speech that began
+   * just before playback started is already server-side and may still
+   * barge in per the interruption settings.) Extreme-noise environments
+   * only; prefer `interruptions.enabled: false` when caller speech should
+   * still be heard and answered afterwards. Default false.
+   */
+  muteWhileAgentSpeaking?: boolean;
+}
+interface IdleOptions {
+  /** Seconds of caller silence before the first nudge. */
+  timeoutSeconds: number;
+  /** Nudge instructions, escalated in order. */
+  prompts?: string[];
+  /** Nudges before giving up. Default = prompts.length. */
+  maxNudges?: number;
+  /** Goodbye instruction before hanging up. */
+  goodbye?: string;
+}
+interface HangupOptions {
+  /**
+   * Watchdog window: force hangup completion only after the pending goodbye
+   * shows no progress — no audio deltas, no response start, no mark echoes —
+   * for this long. Evidence re-arms the window, so a goodbye that is still
+   * being generated or played is never cut off, on any provider; a dead
+   * socket or a model that never says goodbye completes within one or two
+   * quiet windows. Default 7000.
+   */
+  markTimeoutMs: number;
+}
+interface SessionOptions {
+  greeting: GreetingOptions;
+  interruptions: InterruptionSettings;
+  deafness: DeafnessOptions;
+  idle?: IdleOptions;
+  maxCallDurationSeconds?: number;
+  reconnect: ReconnectPolicy;
+  hangup: HangupOptions;
+  /** Normalized VAD, mapped to the provider's native config. */
+  vad?: VadConfig | null;
+  /**
+   * `afterPlayback` (default): tool results wait until current agent audio
+   * finishes playing. `immediate`: send as soon as the tool completes.
+   */
+  toolResultDelivery: 'afterPlayback' | 'immediate';
+  /** Default hold audio for tools that don't specify their own. */
+  toolBackgroundAudio?: {
+    spec: BackgroundAudioSpec;
+  } & BackgroundAudioOptions;
+  /**
+   * When a handoff target declares a different voice on a provider that
+   * cannot change voice mid-session: `keep` (default) keeps the current
+   * voice; `reconnect` opens a fresh provider session with the new voice and
+   * carries context over (adds a beat of latency).
+   */
+  handoffVoicePolicy?: 'keep' | 'reconnect';
+  /** Hold audio covering the reconnect gap on handoffs that need one. */
+  handoffHold?: {
+    spec: BackgroundAudioSpec;
+  } & BackgroundAudioOptions;
+  /** Initial session context KV, available to tools and instructions. */
+  context?: Record<string, unknown>;
+  /** Handshake bounds for the Twilio start frame. */
+  handshake?: {
+    timeoutMs?: number;
+    maxPreStartMessages?: number;
+  };
+}
+declare const DEFAULT_SESSION_OPTIONS: SessionOptions;
+declare function resolveSessionOptions(partial?: Partial<SessionOptions>): SessionOptions;
+interface BuiltinToolsConfig {
+  /**
+   * Let the agent end the call gracefully: it is asked for a closing line,
+   * the goodbye's playout is watched via marks, then the leg completes.
+   */
+  finishCall?: boolean | {
+    description?: string;
+    farewellInstruction?: string;
+  };
+  /** Let the agent transfer the PSTN leg to a human/number. */
+  transferCall?: {
+    enabled: true;
+    /** Fallback when the model doesn't provide a number. */
+    defaultPhoneNumber?: string;
+    /** Caller id shown to the transferee. Defaults to bridge twilio.callerId. */
+    callerId?: string;
+    description?: string;
+    /** Spoken before transferring (out-of-band instruction). */
+    announcement?: string;
+  } | false;
+  /** Send an SMS via Twilio REST. */
+  sendSms?: {
+    enabled: true;
+    from?: string;
+    description?: string;
+  } | false;
+  /** Send a WhatsApp message via Twilio REST. */
+  sendWhatsapp?: {
+    enabled: true;
+    from?: string;
+    description?: string;
+  } | false;
+}
+interface TwilioRestOptions {
+  accountSid: string;
+  authToken: string;
+  /** Default caller id for transfers. */
+  callerId?: string;
+}
+interface BridgeConfig {
+  /** The (root) agent, or a resolver for multi-tenant routing per call. */
+  agent: Agent | ((start: TwilioStartEvent) => Agent | Promise<Agent>);
+  provider: ProviderFactory;
+  session?: Partial<SessionOptions> | ((start: TwilioStartEvent) => Partial<SessionOptions> | Promise<Partial<SessionOptions>>);
+  /** Twilio REST credentials — enables clean hangup, transfer, SMS/WhatsApp. */
+  twilio?: TwilioRestOptions;
+  builtinTools?: BuiltinToolsConfig;
+  store?: SessionStore;
+  /**
+   * Reject unauthorized streams before a session is created. Return false to
+   * close with 1008. Typical check: a signed token in customParameters.
+   */
+  validateConnection?: (start: TwilioStartEvent, request?: IncomingMessage) => boolean | Promise<boolean>;
+  logger?: Logger;
+}
+//#endregion
+//#region src/bridge/state.d.ts
+/**
+ * Call lifecycle:
+ * connecting → active → ending → ended
+ * (`awaiting_start` lives in the bridge's handshake, before a session exists.)
+ */
+type CallState = 'connecting' | 'active' | 'ending' | 'ended';
+type CallEndReason = 'agent-hangup' | 'caller-hangup' | 'transferred' | 'provider-failed' | 'max-duration' | 'idle-timeout' | 'bridge-closed' | 'error';
+//#endregion
+//#region src/bridge/events.d.ts
+interface CallStartedInfo {
+  callSid: string;
+  streamSid: string;
+  direction: 'inbound' | 'outbound';
+  from?: string;
+  to?: string;
+  customParameters: Record<string, string>;
+}
+interface ToolRunInfo {
+  toolCallId: string;
+  toolName: string;
+  strategy: string;
+  agentId: string;
+  input?: unknown;
+  result?: unknown;
+  error?: string;
+  durationMs?: number;
+}
+interface ApprovalRequestInfo {
+  approvalId: string;
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  agentId: string;
+  expiresAtMs: number;
+}
+interface SessionEventMap {
+  'call.started': (info: CallStartedInfo) => void;
+  'call.ended': (info: {
+    reason: CallEndReason;
+    durationMs: number;
+    usage: UsageInfo;
+  }) => void;
+  'call.failed': (error: Error) => void;
+  'provider.connected': () => void;
+  'provider.reconnecting': (info: {
+    attempt: number;
+    delayMs: number;
+  }) => void;
+  'provider.reconnected': () => void;
+  'provider.closed': (info: {
+    code?: number;
+    reason?: string;
+  }) => void;
+  /** Generation-side: the model started/finished producing a response. */
+  'agent.speech.started': (info: {
+    responseId: string;
+  }) => void;
+  'agent.speech.ended': (info: {
+    responseId: string;
+  }) => void;
+  /** Playback-side (mark-confirmed): what the caller actually hears. */
+  'playback.started': (info: {
+    responseId: string;
+  }) => void;
+  'playback.finished': (info: {
+    responseId: string;
+    playedMs: number;
+  }) => void;
+  'playback.interrupted': (info: {
+    responseId: string;
+    playedMs: number;
+  }) => void;
+  'user.speech.started': () => void;
+  'user.speech.ended': () => void;
+  'transcript.user': (entry: TranscriptEntry) => void;
+  'transcript.agent': (entry: TranscriptEntry) => void;
+  'tool.started': (info: ToolRunInfo) => void;
+  'tool.completed': (info: ToolRunInfo) => void;
+  'tool.failed': (info: ToolRunInfo) => void;
+  'tool.approval.required': (request: ApprovalRequestInfo) => void;
+  'agent.handoff': (info: {
+    from: Agent;
+    to: Agent;
+    reason?: string;
+  }) => void;
+  interruption: (info: {
+    responseId: string;
+    playedMs: number;
+  }) => void;
+  'interruption.blocked': (info: {
+    cause: string;
+  }) => void;
+  'background_audio.started': (info: {
+    preset?: string;
+  }) => void;
+  'background_audio.stopped': (info: {
+    preset?: string;
+  }) => void;
+  dtmf: (info: {
+    digit: string;
+  }) => void;
+  'usage.updated': (usage: UsageInfo, delta: ProviderUsage) => void;
+  error: (error: Error) => void;
+}
+interface BridgeEventMap {
+  'session.started': (session: CallSession) => void;
+  'session.ended': (info: {
+    callSid: string;
+    reason: CallEndReason;
+  }) => void;
+  'connection.rejected': (info: {
+    reason: string;
+  }) => void;
+  error: (error: Error) => void;
+}
+//#endregion
+//#region src/bridge/CallSession.d.ts
+interface CallSessionDeps {
+  transport: TwilioMediaTransport;
+  start: TwilioStartEvent;
+  providerFactory: ProviderFactory;
+  agent: Agent;
+  options: SessionOptions;
+  store: SessionStore;
+  logger: Logger;
+  builtinTools?: BuiltinToolsConfig;
+  rest?: TwilioRestClient;
+  restCallerId?: string;
+  answeredEarly?: boolean;
+  middlewares?: readonly ToolMiddleware[];
+  onEnded?: (callSid: string, reason: CallEndReason) => void;
+}
+declare class CallSession extends TypedEmitter<SessionEventMap> {
+  readonly callSid: string;
+  readonly streamSid: string;
+  readonly callInfo: ToolCallInfo;
+  readonly context: SessionContext;
+  private stateValue;
+  private readonly deps;
+  private readonly log;
+  private readonly tracker;
+  private readonly interruptions;
+  private readonly usageAccumulator;
+  private readonly toolQueue;
+  private readonly transcriptEntries;
+  private toolset;
+  private readonly startedAtMs;
+  private readonly interruptedResponses;
+  private readonly runningTools;
+  private readonly timers;
+  private provider;
+  private activeAgentValue;
+  private generating;
+  private currentResponseId;
+  private firstTurnDone;
+  /**
+   * 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.
+   */
+  private blockedUserTurn;
+  private greeted;
+  private answered;
+  private inboundBuffer;
+  private reconnectAttempt;
+  private reconnecting;
+  private pendingHangup;
+  private pendingTransfer;
+  private endedReason;
+  private hangupReason;
+  private readonly middlewares;
+  private readonly bgAudio;
+  /** Deferred tool calls awaiting a real result (execute() or submitToolResult). */
+  private readonly deferredPending;
+  /** Human-in-the-loop calls awaiting approve/reject. */
+  private readonly approvals;
+  /** Text turns to inject once the agent finishes speaking (deferred results). */
+  private pendingInjections;
+  private idleTimer;
+  private nudgeCount;
+  /** All agents reachable from the root via handoffs, by id. */
+  private readonly agents;
+  private readonly handoffHistory;
+  private handoffInProgress;
+  /** Pre-synthesized greeting playout state. */
+  private pregreeting;
+  constructor(deps: CallSessionDeps);
+  get state(): CallState;
+  get activeAgent(): Agent;
+  get usage(): UsageInfo;
+  get transcript(): readonly TranscriptEntry[];
+  /** Connect the provider and activate the call. Called by the bridge. */
+  begin(): Promise<void>;
+  /** The outbound leg was answered (host's Twilio status callback). */
+  notifyAnswered(): void;
+  sendText(text: string, options?: {
+    role?: 'user' | 'system';
+    triggerResponse?: boolean;
+  }): void;
+  updateInstructions(instructions: string): Promise<void>;
+  /** Manual barge-in: stop the agent mid-sentence. */
+  interrupt(): void;
+  /**
+   * 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?: {
+    finalMessage?: string;
+    immediate?: boolean;
+  }): Promise<void>;
+  /** Transfer the PSTN leg. Waits for current playback (and announcement). */
+  transferTo(phoneNumber: string, options?: {
+    callerId?: string;
+    announcement?: string;
+  }): Promise<void>;
+  /** Swap the active agent (swarm handoff). Accepts an Agent or its id. */
+  handoffTo(agent: Agent | string): Promise<void>;
+  /** Complete a `deferred` tool call from the host side. */
+  submitToolResult(toolCallId: string, result: unknown): void;
+  /** Start background audio manually (independent of tools). */
+  playBackgroundAudio(spec: BackgroundAudioSpec, options?: BackgroundAudioOptions): Promise<void>;
+  stopBackgroundAudio(options?: {
+    fadeOutMs?: number;
+  }): Promise<void>;
+  /** Immediate teardown (no goodbye). */
+  end(reason?: CallEndReason): Promise<void>;
+  private buildToolset;
+  private buildProviderInit;
+  private wireTransport;
+  /** Emit 'error'; when the host attached no listener, log instead of losing it. */
+  private emitError;
+  private wireProvider;
+  private handleInboundMedia;
+  private flushInboundBuffer;
+  private handleMarkEcho;
+  private onPlaybackFinished;
+  private handleBargeIn;
+  private performInterrupt;
+  private handleToolCall;
+  /** sync path (also the approved HITL path): hold audio, execute, deliver. */
+  private runForegroundTool;
+  /** dispatch/deferred body — no hold audio (the model keeps talking). */
+  private runDetachedTool;
+  /** Shared execution core: abort/timeout, middleware onion, per-tool hooks. */
+  private executeToolBody;
+  /** Inject a deferred result as a conversation turn (idempotent per call). */
+  private completeDeferred;
+  /** Complete a deferred tool from the host (webhook, operator console…). */
+  private completeDeferredFromHost;
+  private requestApproval;
+  /** Approve a pending humanInTheLoop tool call (optionally editing input). */
+  approveTool(approvalId: string, editedInput?: unknown): void;
+  /** Reject a pending humanInTheLoop tool call. */
+  rejectTool(approvalId: string, reason?: string): void;
+  private acquireHoldAudio;
+  /** Inject a text turn now, or after the agent finishes speaking. */
+  private injectOrQueueText;
+  private raceAbort;
+  private deliverToolResult;
+  private flushToolQueue;
+  private buildToolContext;
+  private maybeGreet;
+  private armHangup;
+  /** Evidence the goodbye is alive (generating or playing) — feeds the watchdog. */
+  private noteHangupProgress;
+  /**
+   * 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.
+   */
+  private armHangupWatchdog;
+  private maybeCompleteHangup;
+  private completeHangup;
+  private executePendingTransfer;
+  private scheduleReconnect;
+  private reconnectProvider;
+  /** After a reconnect the provider session is blank — restore conversational context. */
+  private reinjectHistory;
+  private performHandoff;
+  /**
+   * 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.
+   */
+  private playPreGreeting;
+  /** Armed whenever the agent goes quiet and we're waiting on the caller. */
+  private armIdleTimer;
+  private clearIdleTimer;
+  private onIdleTimeout;
+  private startMaxDurationWatchdog;
+  private fail;
+  private teardown;
+  private saveSnapshot;
+}
+//#endregion
+//#region src/bridge/TwilioRealtimeBridge.d.ts
+declare class TwilioRealtimeBridge extends TypedEmitter<BridgeEventMap> {
+  private readonly config;
+  private readonly logger;
+  private readonly store;
+  private readonly rest?;
+  private readonly sessionsBySid;
+  /** Status callbacks can beat the media stream; remember early answers. */
+  private readonly answeredEarly;
+  private readonly middlewares;
+  private closed;
+  constructor(config: BridgeConfig);
+  /** Attach one incoming Twilio Media Stream WebSocket. */
+  handleConnection(ws: WebSocketLike, request?: IncomingMessage): void;
+  /**
+   * Register cross-cutting tool middleware (first registered wraps
+   * outermost). Applies to sessions created after the call.
+   */
+  use(middleware: ToolMiddleware): this;
+  getSession(callSid: string): CallSession | undefined;
+  sessions(): ReadonlyMap<string, CallSession>;
+  /**
+   * Feed the outbound `answered` signal from your Twilio status callback so
+   * agent-initiated greetings fire when the human actually picks up.
+   */
+  notifyAnswered(callSid: string): void;
+  /** Deterministically end every active session and stop accepting new ones. */
+  close(): Promise<void>;
+  private handshake;
+  private onSessionEnded;
+}
+//#endregion
+//#region src/agents/handoff.d.ts
+declare const HANDOFF_MARKER: "__twilioRealtimeAgentsHandoff";
+interface HandoffDirective {
+  [HANDOFF_MARKER]: true;
+  targetAgentId: string;
+  reason?: string;
+}
+declare function isHandoffDirective(value: unknown): value is HandoffDirective;
+declare function handoffToolName(agentId: string): string;
+declare function createHandoffTool(target: Agent): Tool;
+//#endregion
+//#region src/greeting/capture.d.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`).
+ */
+interface CaptureGreetingOptions {
+  apiKey: string;
+  /** Exact text the greeting should say. */
+  text: string;
+  model?: string;
+  voice?: string;
+  /** OpenAI-compatible realtime endpoint (works for xAI too). */
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+}
+interface CapturedGreeting {
+  /** Raw 8 kHz μ-law audio, ready for the Twilio stream. */
+  audio: Buffer;
+  text: string;
+  durationMs: number;
+}
+declare function captureGreetingAudio(options: CaptureGreetingOptions): Promise<CapturedGreeting>;
+//#endregion
+//#region src/tools/json-schema.d.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.
+ */
+type AnyZod = any;
+declare function zodToJsonSchema(schema: AnyZod): Record<string, unknown>;
+//#endregion
+//#region src/tools/builtins/finishCall.d.ts
+interface FinishCallToolOptions {
+  description?: string;
+  /** Returned to the model as the tool result's instruction. */
+  farewellInstruction?: string;
+}
+/**
+ * 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.
+ */
+declare function createFinishCallTool(options?: FinishCallToolOptions): Tool<any, any>;
+//#endregion
+//#region src/tools/builtins/transferCall.d.ts
+interface TransferCallToolOptions {
+  defaultPhoneNumber?: string;
+  callerId?: string;
+  description?: string;
+  /** Spoken to the caller before the transfer executes. */
+  announcement?: string;
+}
+declare function createTransferCallTool(options?: TransferCallToolOptions): Tool<any, any>;
+//#endregion
+//#region src/playback/PlaybackTracker.d.ts
+interface MarkEchoResult {
+  kind: 'played' | 'flushed';
+  responseId: string;
+  playedMs: number;
+  /** First audible chunk of this response reached the caller. */
+  playbackStarted: boolean;
+  /** The last chunk of a completed response finished playing. */
+  playbackFinished: boolean;
+}
+declare class PlaybackTracker {
+  private epoch;
+  private markSeq;
+  private readonly marks;
+  private readonly responses;
+  private readonly now;
+  private readonly checkpointIntervalMs;
+  constructor(now?: () => number, options?: {
+    checkpointIntervalMs?: number;
+  });
+  /** Is `name` one of ours (as opposed to a host-app or background mark)? */
+  static isTrackedMark(name: string): boolean;
+  /**
+   * 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: string, chunkMs: number, itemId?: string): string | null;
+  /**
+   * 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: string): string | null;
+  private createMark;
+  /** Process a mark echo from Twilio. Returns null for unknown marks. */
+  onMarkEcho(name: string): MarkEchoResult | null;
+  /**
+   * 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(): Array<{
+    responseId: string;
+    playedMs: number;
+    itemId?: string;
+  }>;
+  /**
+   * 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: string): number;
+  /**
+   * Live responses with unplayed audio, with their current played-ms
+   * estimates — captured BEFORE onClear() freezes them, to feed truncation.
+   */
+  snapshotActive(): Array<{
+    responseId: string;
+    itemId?: string;
+    estimatedPlayedMs: number;
+  }>;
+  /** Any response with audio still unplayed (and not flushed)? */
+  isPlaybackActive(): boolean;
+  itemIdFor(responseId: string): string | undefined;
+  playedMsFor(responseId: string): number;
+  totalMsFor(responseId: string): number;
+  private ensureTrack;
+  /** Drop bookkeeping once a response is finished and every mark came home. */
+  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_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, type Logger, type MarkEchoResult, PlaybackTracker, type ProviderAudioDelta, type ProviderCapabilities, type ProviderCloseInfo, type ProviderEvents, type ProviderFactory, type ProviderFactoryContext, type ProviderSessionInit, type ProviderToolCall, type ProviderToolSchema, type ProviderUsage, type ReconnectPolicy, type SendTextOptions, type SendToolResultOptions, SessionContext, type SessionEventMap, type SessionOptions, type SessionStore, 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 VadConfig, type WebSocketLike, type ZodSchemaLike, captureGreetingAudio, collectAgentGraph, composeExecution, connectStreamTwiml, consoleLogger, createFinishCallTool, createHandoffTool, createTransferCallTool, decorateTool, emptyUsage, handoffToolName, isHandoffDirective, noopLogger, resolveSessionOptions, tool, zodToJsonSchema };