@agenticmail/core 0.9.15 → 0.9.20

package/dist/index.d.ts

@@ -220,6 +220,15 @@ interface AgenticMailConfig {
      * system event (visible in the web UI) but no email is sent.
      */
     operatorEmail?: string;
+    /**
+     * OpenAI API key — used only by the realtime voice bridge to open an
+     * OpenAI Realtime (`gpt-realtime`) session for live phone calls. When
+     * unset, phone missions still place and track calls (call-control),
+     * but a 46elks realtime-media WebSocket cannot be bridged to a
+     * conversational model. Read from the `OPENAI_API_KEY` env var or
+     * `config.json`. Optional — no other feature depends on it.
+     */
+    openaiApiKey?: string;
     masterKey: string;
     dataDir: string;
 }
@@ -1692,6 +1701,396 @@ declare class SmsPoller {
     private pollOnce;
 }
 
+/**
+ * Telegram Bot API client — dependency-free (global `fetch`, Node 22+).
+ *
+ * Ported and MERGED from two already-tuned internal sources (licensing
+ * confirmed by Ope, 2026-05-19 — plan §13.5):
+ *   - enterprise `agent-tools/tools/messaging/telegram.ts`
+ *     (`tgApi`, `stripMarkdown`, webhook management)
+ *   - agent-harness `fola-lib/telegram-api.mjs`
+ *     (auto-splitting `sendMessage`, the long-poll timeout discipline)
+ *
+ * Host-specific pieces are intentionally dropped to fit the single-tenant
+ * open-source product: the local Bot API server auto-detection
+ * (`http://localhost:8081`) and the filesystem media-download paths are
+ * Fola-host infrastructure, not channel logic.
+ *
+ * Secrets: the bot token rides in the request URL path. Every error this
+ * module surfaces is scrubbed with {@link redactBotToken} so a token can
+ * never reach a log line or an API response — matching the SMS/phone
+ * credential-handling bar.
+ */
+/** Official Telegram Bot API base. */
+declare const TELEGRAM_API_BASE = "https://api.telegram.org";
+/** Telegram's hard per-message ceiling is 4096 characters. */
+declare const TELEGRAM_MESSAGE_LIMIT = 4096;
+/** We split below the hard limit, leaving headroom for safety. */
+declare const TELEGRAM_CHUNK_SIZE = 4000;
+/** A failed Telegram Bot API call. `description` is the provider message. */
+declare class TelegramApiError extends Error {
+    readonly isTelegramApiError = true;
+    readonly description: string;
+    readonly errorCode?: number;
+    constructor(method: string, description: string, errorCode?: number);
+}
+/**
+ * Scrub bot tokens from any string before it can be logged or returned.
+ *
+ * A token looks like `<digits>:<35 url-safe chars>`. We redact both an
+ * explicitly-known token (exact match) and anything matching the generic
+ * token shape — so a token leaks neither when the caller knows it nor
+ * when it is buried in, say, a `fetch` failure message carrying the URL.
+ */
+declare function redactBotToken(text: string, token?: string): string;
+interface TelegramApiOptions {
+    /**
+     * Long-poll requests (`getUpdates` with a non-zero `timeout`) need an
+     * HTTP timeout longer than the server-side poll window, or the socket
+     * is torn down before Telegram replies.
+     */
+    longPoll?: boolean;
+}
+/**
+ * POST a Telegram Bot API method with a JSON body and return `result`.
+ * Throws {@link TelegramApiError} (token-scrubbed) on any failure.
+ */
+declare function callTelegramApi<T = unknown>(token: string, method: string, body?: Record<string, unknown>, options?: TelegramApiOptions): Promise<T>;
+/**
+ * Strip Markdown so agent replies arrive as clean plain text. Telegram's
+ * Markdown parse modes are bypassed entirely (no `parse_mode`) to avoid
+ * formatting collisions on arbitrary agent output.
+ */
+declare function stripTelegramMarkdown(text: string): string;
+/**
+ * Split text into <= `maxLen` chunks, cutting on a newline boundary when
+ * one is reasonably close so messages do not break mid-word.
+ */
+declare function splitTelegramMessage(text: string, maxLen?: number): string[];
+interface SendTelegramMessageOptions {
+    /** Reply to a specific message id in the chat. */
+    replyToMessageId?: number;
+    /** Deliver silently (no push notification). */
+    disableNotification?: boolean;
+}
+interface SendTelegramMessageResult {
+    /** message_id of each chunk Telegram accepted, in order. */
+    messageIds: number[];
+    /** Number of chunks the text was split into. */
+    chunks: number;
+}
+/**
+ * Send a text message, auto-splitting anything over the per-message
+ * ceiling. The reply target (if any) is attached only to the first
+ * chunk so a long reply still threads correctly.
+ */
+declare function sendTelegramMessage(token: string, chatId: string | number, text: string, options?: SendTelegramMessageOptions): Promise<SendTelegramMessageResult>;
+interface TelegramBotInfo {
+    id: number;
+    is_bot: boolean;
+    username?: string;
+    first_name?: string;
+}
+/** `getMe` — used to validate a token and capture the bot identity. */
+declare function getTelegramMe(token: string): Promise<TelegramBotInfo>;
+/** `getChat` — chat metadata (title, type, member count, ...). */
+declare function getTelegramChat(token: string, chatId: string | number): Promise<Record<string, unknown>>;
+interface GetUpdatesOptions {
+    /** Max updates per call (1-100). */
+    limit?: number;
+    /** Long-poll window in seconds (0 = short poll). */
+    timeoutSec?: number;
+}
+/** `getUpdates` long-poll — the poll-mode transport. */
+declare function getTelegramUpdates(token: string, offset: number, options?: GetUpdatesOptions): Promise<Array<Record<string, unknown>>>;
+interface SetWebhookOptions {
+    /**
+     * Shared secret echoed by Telegram in the
+     * `X-Telegram-Bot-Api-Secret-Token` header on every webhook delivery.
+     */
+    secretToken?: string;
+    /** Drop updates that queued up while no webhook was set. */
+    dropPendingUpdates?: boolean;
+}
+/** `setWebhook` — register the inbound webhook URL (webhook-mode transport). */
+declare function setTelegramWebhook(token: string, url: string, options?: SetWebhookOptions): Promise<boolean>;
+/** `deleteWebhook` — switch back to poll mode. */
+declare function deleteTelegramWebhook(token: string): Promise<boolean>;
+/** `getWebhookInfo` — current webhook status. */
+declare function getTelegramWebhookInfo(token: string): Promise<Record<string, unknown>>;
+
+/**
+ * Telegram update parsing — pure, dependency-free.
+ *
+ * Ported from the inbound-message handling in the agent-harness Fola
+ * bridge (`fola-telegram-bridge.mjs` — the `formatPrompt` header fields
+ * and the `STOP_WORDS` abort set), stripped of every Fola-host specific
+ * (session routing, the fola-claude prompt envelope, media downloads).
+ */
+type TelegramChatType = 'private' | 'group' | 'supergroup' | 'channel' | 'unknown';
+/** A normalized inbound Telegram text message. */
+interface ParsedTelegramMessage {
+    /** Telegram `update_id` — drives the poll offset. */
+    updateId: number;
+    /** `message_id` within the chat. */
+    messageId: number;
+    /** Chat id as a string (Telegram ids are 64-bit; strings avoid loss). */
+    chatId: string;
+    chatType: TelegramChatType;
+    chatTitle?: string;
+    /** Sender id as a string; falls back to the chat id for channel posts. */
+    fromId: string;
+    fromName: string;
+    fromUsername?: string;
+    /** Message text (or media caption). Always non-empty for a parsed result. */
+    text: string;
+    /** `message_id` of the message this one replies to, if any. */
+    replyToMessageId?: number;
+    /** Text of the replied-to message, when Telegram included it. */
+    replyToText?: string;
+    /** ISO-8601 timestamp derived from the Telegram `date` epoch. */
+    date: string;
+}
+/**
+ * Normalize a raw Telegram update into a {@link ParsedTelegramMessage},
+ * or `null` when it carries no usable text (callback queries, service
+ * messages, edits with no text, non-text media without a caption).
+ * Handles both `message` and `channel_post` envelopes.
+ */
+declare function parseTelegramUpdate(update: unknown): ParsedTelegramMessage | null;
+/**
+ * Words that, sent alone (case-insensitive, optional trailing
+ * punctuation), signal "abort whatever you are doing for me". Kept
+ * deliberately narrow — anything longer or ambiguous is a normal
+ * message. Ported verbatim from the Fola bridge.
+ */
+declare const TELEGRAM_STOP_WORDS: ReadonlySet<string>;
+/** True when `text` is a bare stop command. */
+declare function isTelegramStopCommand(text: string): boolean;
+/**
+ * Compute the next `getUpdates` offset from a batch: one past the
+ * highest `update_id` seen. Advancing the offset is what acknowledges
+ * updates to Telegram, so this must run on the raw batch even if
+ * individual updates fail to parse.
+ */
+declare function nextTelegramOffset(currentOffset: number, updates: Array<{
+    update_id?: unknown;
+}>): number;
+
+/**
+ * Telegram Manager — per-agent Telegram bot configuration + message log.
+ *
+ * Models the existing {@link import('../sms/manager.js').SmsManager} — the
+ * closest existing channel — so the hardening bar matches:
+ *   - Config lives in agent metadata under the `telegram` key.
+ *   - Credential fields (`botToken`, `webhookSecret`) are encrypted at
+ *     rest with the same AES-256-GCM scheme (`encryptSecret`) and
+ *     redacted on every read that leaves the process.
+ *   - Inbound/outbound messages are stored in a `telegram_messages` table.
+ *
+ * Single-tenant: there is no org / multi-tenant scoping and nothing is
+ * hardcoded — every bot token, chat id and operator identity is
+ * per-agent config supplied by the user.
+ */
+
+/** Transport mode: long-poll `getUpdates`, or a registered webhook. */
+type TelegramMode = 'poll' | 'webhook';
+interface TelegramConfig {
+    /** Whether the Telegram channel is active for this agent. */
+    enabled: boolean;
+    /** Bot API token from @BotFather. SECRET — encrypted at rest, redacted on read. */
+    botToken: string;
+    /** Bot @username (non-secret, for display). Captured from `getMe` at setup. */
+    botUsername?: string;
+    /** Numeric bot id (non-secret). Captured from `getMe` at setup. */
+    botId?: number;
+    /**
+     * Chat ids permitted to message the agent. EMPTY = nobody (fail-closed,
+     * same posture as the Fola bridge). The operator chat is always allowed.
+     */
+    allowedChatIds: string[];
+    /** Chat that receives `ask_operator` notifications + can approve (plan §13.4). */
+    operatorChatId?: string;
+    /** Inbound transport. */
+    mode: TelegramMode;
+    /** Public webhook URL (webhook mode only). */
+    webhookUrl?: string;
+    /**
+     * Shared secret echoed by Telegram in the
+     * `X-Telegram-Bot-Api-Secret-Token` header. SECRET — encrypted at
+     * rest, redacted on read. Doubles as the webhook routing key.
+     */
+    webhookSecret?: string;
+    /** Persisted `getUpdates` offset (poll mode). */
+    pollOffset?: number;
+    /** When the channel was configured. */
+    configuredAt: string;
+}
+interface TelegramMessage {
+    id: string;
+    agentId: string;
+    direction: 'inbound' | 'outbound';
+    chatId: string;
+    /** Telegram `message_id` (may be absent for a failed outbound attempt). */
+    telegramMessageId?: number;
+    /** Sender id (inbound only). */
+    fromId?: string;
+    text: string;
+    status: 'received' | 'sent' | 'failed' | 'pending';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+/** Telegram's `secret_token` charset, and our minimum entropy floor. */
+declare const TELEGRAM_WEBHOOK_SECRET_RE: RegExp;
+declare const TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH = 16;
+/**
+ * Redact the credential fields of a Telegram config for any value that
+ * leaves the process (API responses, logs). The bot token is collapsed
+ * to `***` entirely — never partially shown — matching the SMS bar and
+ * the plan §13.5 rule "no token ever in a log line or API response".
+ */
+declare function redactTelegramConfig(config: TelegramConfig): TelegramConfig;
+/**
+ * Allow-list gate for INBOUND messages. A chat may talk to the agent
+ * only if it is on `allowedChatIds` OR it is the configured operator
+ * chat. An empty allow-list means nobody — fail closed.
+ */
+declare function isTelegramChatAllowed(config: TelegramConfig, chatId: string): boolean;
+declare class TelegramManager {
+    private db;
+    private encryptionKey?;
+    private initialized;
+    /**
+     * Optional master key used to encrypt Telegram credentials at rest
+     * (the same AES-256-GCM scheme SMS/phone use). When absent (tests, or
+     * a deployment with no master key) configs are stored as-is and reads
+     * tolerate plaintext — upgrades and downgrades both stay safe.
+     */
+    constructor(db: Database, encryptionKey?: string | undefined);
+    private ensureTable;
+    /** Encrypt the credential fields of a config before persisting. */
+    private encryptConfig;
+    /** Decrypt the credential fields of a config after loading. */
+    private decryptConfig;
+    /** Normalize a stored/loaded config object, defaulting missing fields. */
+    private normalizeConfig;
+    /** Get the Telegram config from agent metadata (credentials decrypted). */
+    getConfig(agentId: string): TelegramConfig | null;
+    /** Save the Telegram config to agent metadata (credentials encrypted). */
+    saveConfig(agentId: string, config: TelegramConfig): void;
+    /** Remove the Telegram config from agent metadata. */
+    removeConfig(agentId: string): void;
+    /** Persist a new poll offset without touching the rest of the config. */
+    updatePollOffset(agentId: string, offset: number): void;
+    /**
+     * Resolve the agent that owns a webhook secret. Used to authenticate +
+     * route an inbound Telegram webhook delivery: a webhook carries no bot
+     * identity, so the `X-Telegram-Bot-Api-Secret-Token` header is the
+     * routing key. The comparison is constant-time, and a non-match
+     * returns `null` so the route can answer with a single uniform 403
+     * (no enumeration oracle — same posture as the SMS webhook).
+     */
+    findAgentByWebhookSecret(secret: string): {
+        agentId: string;
+        config: TelegramConfig;
+    } | null;
+    /** True if an inbound message with this Telegram id is already stored. */
+    inboundMessageExists(agentId: string, chatId: string, telegramMessageId: number): boolean;
+    /** Record an inbound Telegram message. */
+    recordInbound(agentId: string, input: {
+        chatId: string;
+        telegramMessageId: number;
+        fromId?: string;
+        text: string;
+        createdAt?: string;
+    }, metadata?: Record<string, unknown>): TelegramMessage;
+    /** Record an outbound Telegram message attempt. */
+    recordOutbound(agentId: string, input: {
+        chatId: string;
+        text: string;
+        telegramMessageId?: number;
+        status?: TelegramMessage['status'];
+    }, metadata?: Record<string, unknown>): TelegramMessage;
+    /** Update the status (+ optional metadata) of a stored message. */
+    updateStatus(id: string, status: TelegramMessage['status'], metadata?: Record<string, unknown>): void;
+    /** List stored Telegram messages for an agent, newest first. */
+    listMessages(agentId: string, opts?: {
+        direction?: 'inbound' | 'outbound';
+        chatId?: string;
+        limit?: number;
+        offset?: number;
+    }): TelegramMessage[];
+}
+
+/**
+ * Telegram ⇄ `ask_operator` bridge (plan §13.4 / §13.5) — pure helpers.
+ *
+ * The realtime voice agent's `ask_operator` tool records an *operator
+ * query* on the phone mission; the API exposes it through the
+ * operator-query endpoints. Email is the channel-agnostic default
+ * notifier (plan §5). This module makes Telegram a first-class
+ * notification + approval channel WITHOUT duplicating any of that
+ * machinery — it only:
+ *
+ *   1. {@link formatOperatorQueryTelegramMessage} — renders the
+ *      notification text the operator receives.
+ *   2. {@link parseTelegramOperatorReply} — parses the operator's
+ *      Telegram reply back into a `{ queryId, answer }`.
+ *
+ * The caller feeds the parsed result straight into the SAME
+ * `PhoneManager.answerOperatorQuery` the inbound email-reply hook uses.
+ */
+/**
+ * Token embedded in a notification so the operator's reply can be
+ * matched back to a query. Kept short — the operator may see it.
+ */
+declare const TELEGRAM_OPERATOR_QUERY_TAG = "AMQ";
+interface OperatorQueryNotificationInput {
+    queryId: string;
+    question: string;
+    callContext?: string;
+    urgency?: string;
+    missionId?: string;
+}
+/**
+ * Render the Telegram message body for an `ask_operator` notification.
+ * The trailing `[AMQ <id>]` token lets a reply be matched to the query
+ * even when the operator does not use Telegram's native reply gesture.
+ */
+declare function formatOperatorQueryTelegramMessage(input: OperatorQueryNotificationInput): string;
+/** A `kind` of `approve`/`deny` is a decision; `answer` is free-form. */
+type OperatorReplyKind = 'answer' | 'approve' | 'deny';
+interface ParsedOperatorReply {
+    /**
+     * Query id when the reply names one — explicitly (`/answer <id>`,
+     * an inline `oq_…` token) or implicitly (a native Telegram reply
+     * quoting a `[AMQ <id>]`-tagged notification). `undefined` when the
+     * reply is a bare message and the caller must resolve the target.
+     */
+    queryId?: string;
+    /** The answer text to record against the query. Always non-empty. */
+    answer: string;
+    kind: OperatorReplyKind;
+}
+/**
+ * Parse an operator's Telegram message into a {@link ParsedOperatorReply},
+ * or `null` when it carries no usable answer.
+ *
+ * Recognized forms (most explicit first):
+ *   - `/answer <queryId> <text>`
+ *   - `/approve [<queryId>] [note]` · `/deny [<queryId>] [note]`
+ *   - a plain message — `queryId` is taken from a quoted tagged
+ *     notification (`replyToText`) or an inline `oq_…` / `[AMQ …]` token,
+ *     and is otherwise left `undefined` for the caller to resolve.
+ *
+ * The `@botname` suffix Telegram appends to commands in groups
+ * (`/approve@mybot`) is tolerated.
+ */
+declare function parseTelegramOperatorReply(input: {
+    text: string;
+    replyToText?: string;
+}): ParsedOperatorReply | null;
+
 declare const ELKS_REALTIME_AUDIO_FORMATS: readonly ["ulaw", "pcm_16000", "pcm_24000", "wav"];
 type ElksRealtimeAudioFormat = typeof ELKS_REALTIME_AUDIO_FORMATS[number];
 interface ElksRealtimeHelloMessage {
@@ -1737,6 +2136,1090 @@ declare function buildElksHandshakeMessages(options?: {
     sendFormat?: ElksRealtimeAudioFormat;
 }): ElksRealtimeOutboundMessage[];
 
+/**
+ * Twilio Media Streams wire protocol.
+ *
+ * The realtime-voice counterpart of `realtime.ts` (the 46elks protocol).
+ * Twilio connects a call's audio to a WebSocket via a TwiML
+ * `<Connect><Stream url="wss://…"/></Connect>`; over that socket Twilio
+ * speaks JSON messages keyed by an `event` field.
+ *
+ * Inbound (Twilio → us):
+ *   - `{ event: "connected", protocol, version }`
+ *   - `{ event: "start", start: { streamSid, callSid, accountSid,
+ *                                 mediaFormat, tracks, customParameters } }`
+ *   - `{ event: "media", media: { payload: "<base64 µ-law>", track,
+ *                                 chunk, timestamp } }`
+ *   - `{ event: "stop", stop: { accountSid, callSid } }`
+ *   - `{ event: "mark", mark: { name } }`
+ *
+ * Outbound (us → Twilio) — every outbound frame must echo the
+ * `streamSid` Twilio handed us in the `start` event:
+ *   - `{ event: "media", streamSid, media: { payload: "<base64 µ-law>" } }`
+ *   - `{ event: "mark", streamSid, mark: { name } }`
+ *   - `{ event: "clear", streamSid }`  — flush buffered playback
+ *     (barge-in / interrupt; the analogue of 46elks `interrupt`).
+ *
+ * The audio is G.711 µ-law, 8 kHz, mono, base64 — unlike 46elks which
+ * uses linear PCM. OpenAI's GA Realtime API speaks µ-law natively
+ * (`{ type: "audio/pcmu" }` @ 8 kHz), so on a Twilio call the bridge
+ * does NO transcoding end to end.
+ *
+ * > The Media Streams message shapes above follow Twilio's public
+ * > `<Stream>` documentation. Verify against current docs before the
+ * > live smoke-test (same discipline as the 46elks / OpenAI wire notes).
+ */
+/** µ-law payload sample rate Twilio Media Streams uses, in Hz. */
+declare const TWILIO_MEDIA_SAMPLE_RATE = 8000;
+/** The `connected` handshake frame — first frame Twilio sends. */
+interface TwilioConnectedMessage {
+    event: 'connected';
+    protocol?: string;
+    version?: string;
+    [key: string]: unknown;
+}
+/**
+ * The `start` frame — carries the `streamSid` every outbound frame must
+ * echo, plus the `callSid` we resolve the phone mission from. Twilio
+ * sends exactly one `start` per stream, right after `connected`.
+ */
+interface TwilioStartMessage {
+    event: 'start';
+    /** Stream identifier — required on every outbound media/mark/clear. */
+    streamSid: string;
+    /** The call SID — matches the `sid` from the Calls.json response. */
+    callSid: string;
+    accountSid?: string;
+    mediaFormat?: {
+        encoding?: string;
+        sampleRate?: number;
+        channels?: number;
+    };
+    tracks?: string[];
+    /** `<Parameter>` values declared inside the TwiML `<Stream>`. */
+    customParameters?: Record<string, string>;
+    [key: string]: unknown;
+}
+/** A `media` frame — one small base64 µ-law audio chunk. */
+interface TwilioMediaMessage {
+    event: 'media';
+    /** Base64-encoded G.711 µ-law, 8 kHz mono. */
+    payload: string;
+    /** Inbound only: which leg the audio is from (`inbound`/`outbound`). */
+    track?: string;
+}
+/** The `stop` frame — Twilio has stopped streaming this call's audio. */
+interface TwilioStopMessage {
+    event: 'stop';
+    callSid?: string;
+    [key: string]: unknown;
+}
+/** A `mark` frame — a playback checkpoint echoed back when reached. */
+interface TwilioMarkMessage {
+    event: 'mark';
+    name: string;
+}
+type TwilioRealtimeInboundMessage = TwilioConnectedMessage | TwilioStartMessage | TwilioMediaMessage | TwilioStopMessage | TwilioMarkMessage;
+type TwilioRealtimeOutboundMessage = {
+    event: 'media';
+    streamSid: string;
+    media: {
+        payload: string;
+    };
+} | {
+    event: 'mark';
+    streamSid: string;
+    mark: {
+        name: string;
+    };
+} | {
+    event: 'clear';
+    streamSid: string;
+};
+/**
+ * Parse one raw inbound Twilio Media Streams frame. Accepts a JSON
+ * string or an already-parsed object. Throws on a malformed/unknown
+ * frame — the caller (the bridge) swallows the throw and ignores the
+ * frame, never tearing the call down for one bad message.
+ */
+declare function parseTwilioRealtimeMessage(input: unknown): TwilioRealtimeInboundMessage;
+/**
+ * Build an outbound `media` frame — synthesised agent audio for Twilio
+ * to play to the caller. `data` may be a base64 string or raw bytes.
+ * `streamSid` is the id Twilio handed us in the `start` event.
+ */
+declare function buildTwilioMediaMessage(streamSid: string, data: string | Uint8Array): TwilioRealtimeOutboundMessage;
+/**
+ * Build a `clear` frame — tells Twilio to flush any audio still
+ * buffered for playback. This is how barge-in / interrupt works on a
+ * Twilio call: when the caller starts talking the agent must stop
+ * mid-sentence, so we drop everything queued. (46elks calls this
+ * `interrupt`; Twilio calls it `clear`.)
+ */
+declare function buildTwilioClearMessage(streamSid: string): TwilioRealtimeOutboundMessage;
+/**
+ * Build a `mark` frame — a named playback checkpoint. Twilio echoes the
+ * mark back (as an inbound `mark` event) once the audio queued before
+ * it has actually been played to the caller. Useful for end-of-turn
+ * detection; the bridge does not require it but exposes the builder for
+ * parity with the protocol surface.
+ */
+declare function buildTwilioMarkMessage(streamSid: string, name: string): TwilioRealtimeOutboundMessage;
+
+/**
+ * Twilio webhook helpers — request-signature validation and TwiML
+ * generation.
+ *
+ * This is the call-control counterpart of the 46elks webhook handling
+ * in `manager.ts`. Twilio secures every webhook it sends with an
+ * `X-Twilio-Signature` header; we answer Twilio's voice webhook with
+ * TwiML (an XML document) that connects the call's audio to the
+ * realtime voice WebSocket.
+ *
+ * Everything here is pure (no I/O, no sockets) so it is fully
+ * unit-testable and keeps `@agenticmail/core` dependency-light.
+ */
+/**
+ * Compute the Twilio request signature for a webhook request.
+ *
+ * Twilio's scheme (per its Security docs): take the full request URL,
+ * then for an `application/x-www-form-urlencoded` POST append every
+ * POST parameter — sorted by key — as `key` immediately followed by
+ * `value`, with no separators. HMAC-SHA1 that string keyed by the
+ * account `AuthToken`, and base64-encode the digest. Twilio sends the
+ * result in the `X-Twilio-Signature` header.
+ *
+ * > Verify the exact construction against Twilio's current Security
+ * > documentation before the live smoke-test.
+ *
+ * @param authToken  the Twilio account AuthToken (the signing key)
+ * @param url        the full URL Twilio requested, exactly as configured
+ * @param params     the POST body parameters (form-encoded fields)
+ */
+declare function buildTwilioSignature(authToken: string, url: string, params?: Record<string, string>): string;
+/**
+ * Validate an `X-Twilio-Signature` header against the request, timing-
+ * safe. Fails closed: a missing/empty signature or token, or any
+ * mismatch, returns `false` — never throws. The comparison is constant-
+ * time so a caller cannot probe the expected signature byte by byte.
+ */
+declare function validateTwilioSignature(authToken: string, url: string, params: Record<string, string>, providedSignature: string): boolean;
+/**
+ * XML-escape a string for safe inclusion in a TwiML attribute or text
+ * node. TwiML is XML, so any value we interpolate (a websocket URL with
+ * query params, a `<Parameter>` value) must have its metacharacters
+ * escaped or a stray `&`/`"` would produce malformed XML.
+ */
+declare function escapeXml(value: string): string;
+interface TwilioStreamTwiMLOptions {
+    /** The `wss://…` URL Twilio should open a Media Stream to. */
+    streamUrl: string;
+    /**
+     * `<Parameter>` name/value pairs nested in the `<Stream>` — Twilio
+     * echoes them back inside the media-stream `start` event's
+     * `customParameters`. Used to carry the mission id / token so the
+     * media socket can be matched to its phone mission even though the
+     * `<Stream>` URL itself is fixed.
+     */
+    parameters?: Record<string, string>;
+}
+/**
+ * Build the TwiML returned from the Twilio voice webhook: a
+ * `<Connect><Stream>` document that hands the live call audio to our
+ * realtime voice WebSocket.
+ *
+ *   <?xml version="1.0" encoding="UTF-8"?>
+ *   <Response>
+ *     <Connect>
+ *       <Stream url="wss://host/path">
+ *         <Parameter name="missionId" value="…"/>
+ *       </Stream>
+ *     </Connect>
+ *   </Response>
+ *
+ * `<Connect><Stream>` (as opposed to `<Start><Stream>`) makes the
+ * stream bidirectional and keeps the call alive for its duration — the
+ * call ends when the stream ends. Every interpolated value is
+ * XML-escaped.
+ *
+ * > The `<Connect><Stream>` / `<Parameter>` TwiML verbs are per
+ * > Twilio's public Media Streams docs; verify against current docs
+ * > before the live smoke-test.
+ */
+declare function buildTwilioStreamTwiML(opts: TwilioStreamTwiMLOptions): string;
+/**
+ * Build a minimal `<Response><Say>…</Say></Response>` TwiML document —
+ * the fallback Twilio voice response when the realtime voice runtime
+ * cannot be connected (e.g. no OpenAI key). Mirrors the 46elks
+ * voice-start `play` action.
+ */
+declare function buildTwilioSayTwiML(message: string): string;
+
+/**
+ * Realtime voice WebSocket endpoint paths.
+ *
+ * These are the URL paths a phone carrier's media socket connects to.
+ * They live in `@agenticmail/core` (rather than only in the API
+ * package) because the {@link PhoneManager} needs the Twilio path to
+ * build the `<Stream url>` inside the TwiML it returns from the Twilio
+ * voice webhook. The API package mounts its WebSocket servers on the
+ * same constants, so the path is defined exactly once.
+ */
+/**
+ * Path the 46elks websocket-number's `websocket_url` points at. 46elks
+ * resolves the mission from the `hello` frame's `callid`, so the path
+ * carries no mission identity itself.
+ */
+declare const ELKS_REALTIME_WS_PATH = "/api/agenticmail/calls/realtime";
+/**
+ * Path a Twilio `<Connect><Stream>` connects to. The mission id + token
+ * ride as query params (and as `<Parameter>` values in the TwiML), so
+ * the media socket can be matched to its mission before the Twilio
+ * `start` frame even arrives.
+ */
+declare const TWILIO_REALTIME_WS_PATH = "/api/agenticmail/calls/twilio-stream";
+
+/**
+ * Realtime transport adapter — the provider-pluggable seam of the
+ * realtime voice bridge.
+ *
+ * `RealtimeVoiceBridge` is transport-agnostic on the *socket* side
+ * (it only ever sees abstract {@link RealtimeBridgePort}s), but the
+ * *messages* on the carrier side are provider-specific: 46elks speaks
+ * `hello`/`audio`/`bye` JSON over linear PCM, while Twilio Media Streams
+ * speaks `connected`/`start`/`media`/`stop` JSON over G.711 µ-law.
+ *
+ * A {@link RealtimeTransportAdapter} captures exactly those differences:
+ *   - how to interpret one inbound carrier frame ({@link parseInbound}),
+ *   - how to build the outbound control frames (handshake / audio /
+ *     interrupt / bye),
+ *   - and which OpenAI Realtime audio format the carrier's audio needs.
+ *
+ * Everything else — the OpenAI session lifecycle, function calling,
+ * barge-in handling, transcript accumulation, teardown — is identical
+ * across providers and lives once in the bridge. This is the
+ * "generalise the bridge" design: one bridge, one OpenAI side, a thin
+ * per-provider adapter, no duplicated conversation logic.
+ *
+ * Adapters are pure (no sockets, no I/O), so the bridge stays fully
+ * unit-testable and `@agenticmail/core` stays dependency-light.
+ */
+
+/** Provider identifier — kept in lockstep with `PhoneTransportProvider`. */
+type RealtimeTransportProvider = '46elks' | 'twilio';
+/**
+ * A normalised inbound carrier event. Provider message shapes are
+ * collapsed into this small, bridge-facing vocabulary so the bridge
+ * never has to branch on the provider:
+ *   - `hello`    — the call leg is live; carries the provider call id.
+ *                  (46elks `hello`; Twilio `start`. Twilio's `connected`
+ *                  frame is internal handshake noise → `ignore`.)
+ *   - `audio`    — one inbound audio frame (base64), to relay to OpenAI.
+ *   - `bye`      — the caller side ended the call.
+ *   - `ignore`   — a known-but-uninteresting frame (e.g. Twilio `mark`).
+ */
+type RealtimeInboundEvent = {
+    kind: 'hello';
+    callId: string;
+    from?: string;
+    to?: string;
+} | {
+    kind: 'audio';
+    data: string;
+} | {
+    kind: 'bye';
+    reason?: string;
+    message?: string;
+} | {
+    kind: 'ignore';
+};
+/**
+ * The provider-specific seam the bridge drives. One instance per call.
+ * Adapters that need per-call state (Twilio's `streamSid`) are
+ * stateful — {@link parseInbound} latches that state from the `hello`
+ * frame and the outbound builders read it back.
+ */
+interface RealtimeTransportAdapter {
+    /** Provider this adapter speaks for — used only for log/transcript text. */
+    readonly provider: RealtimeTransportProvider;
+    /**
+     * Prefix for the carrier-side `onEnd` reason strings (`<prefix>-bye`,
+     * `<prefix>-closed`, `<prefix>-error`). The 46elks adapter keeps the
+     * historical `elks` prefix so existing call sites + tests that match
+     * on `elks-bye` / `elks-closed` stay correct; Twilio uses `twilio`.
+     */
+    readonly endReasonPrefix: string;
+    /**
+     * The OpenAI Realtime audio format the carrier's audio requires.
+     * 46elks linear PCM → `audio/pcm` @ 24 kHz; Twilio G.711 µ-law →
+     * `audio/pcmu` @ 8 kHz. Used by `buildRealtimeSessionConfig` so the
+     * OpenAI session in/out format matches the carrier with no transcode.
+     */
+    readonly openaiAudioFormat: {
+        type: string;
+        rate?: number;
+    };
+    /**
+     * Normalise one raw inbound carrier frame. Throws on a malformed
+     * frame (the bridge catches the throw and ignores that frame). A
+     * well-formed but uninteresting frame returns `{ kind: 'ignore' }`.
+     */
+    parseInbound(raw: string | Record<string, unknown>): RealtimeInboundEvent;
+    /**
+     * Frames to send the carrier the moment the call leg is live (right
+     * after the `hello` event). 46elks needs a `listening`+`sending`
+     * format handshake; Twilio needs nothing, so this is `[]`.
+     */
+    buildHandshake(): Record<string, unknown>[];
+    /** Build one outbound audio frame (synthesised agent speech, base64). */
+    buildAudio(base64: string): Record<string, unknown>;
+    /**
+     * Build the barge-in frame — tells the carrier to drop buffered
+     * playback so the agent stops mid-sentence. 46elks `interrupt`;
+     * Twilio `clear`.
+     */
+    buildInterrupt(): Record<string, unknown>;
+    /**
+     * Build the end-of-call frame for the carrier, or `null` if the
+     * carrier has none (Twilio has no client-initiated stream-stop frame;
+     * the bridge just closes the socket).
+     */
+    buildBye(): Record<string, unknown> | null;
+}
+/**
+ * The 46elks realtime-media adapter — the original transport, behaviour
+ * unchanged. Audio is linear PCM, so the OpenAI session uses
+ * `audio/pcm` @ 24 kHz (matching 46elks `pcm_24000`).
+ */
+declare class ElksRealtimeTransport implements RealtimeTransportAdapter {
+    private readonly listenFormat;
+    private readonly sendFormat;
+    readonly provider: "46elks";
+    readonly endReasonPrefix = "elks";
+    readonly openaiAudioFormat: {
+        type: string;
+    };
+    constructor(listenFormat?: ElksRealtimeAudioFormat, sendFormat?: ElksRealtimeAudioFormat);
+    parseInbound(raw: string | Record<string, unknown>): RealtimeInboundEvent;
+    buildHandshake(): Record<string, unknown>[];
+    buildAudio(base64: string): Record<string, unknown>;
+    buildInterrupt(): Record<string, unknown>;
+    buildBye(): Record<string, unknown>;
+}
+/**
+ * The Twilio Media Streams adapter. Audio is G.711 µ-law @ 8 kHz, which
+ * the OpenAI GA Realtime API speaks natively (`audio/pcmu`) — so the
+ * bridge does NO transcoding for a Twilio call.
+ *
+ * Stateful per call: Twilio assigns a `streamSid` in the `start` frame
+ * that EVERY outbound frame must echo. {@link parseInbound} latches it
+ * on `start`; the outbound builders read it back. Building an outbound
+ * frame before `start` throws — but the bridge never does that (it only
+ * sends audio after the `hello` event, which `start` produces).
+ */
+declare class TwilioRealtimeTransport implements RealtimeTransportAdapter {
+    readonly provider: "twilio";
+    readonly endReasonPrefix = "twilio";
+    readonly openaiAudioFormat: {
+        type: string;
+    };
+    /** Latched from the Twilio `start` frame; required on every outbound. */
+    private streamSid;
+    /** The active `streamSid`, once the `start` frame has been seen. */
+    get currentStreamSid(): string;
+    parseInbound(raw: string | Record<string, unknown>): RealtimeInboundEvent;
+    buildHandshake(): Record<string, unknown>[];
+    buildAudio(base64: string): Record<string, unknown>;
+    buildInterrupt(): Record<string, unknown>;
+    buildBye(): Record<string, unknown> | null;
+}
+/** Construct the transport adapter for a provider. */
+declare function createRealtimeTransport(provider: RealtimeTransportProvider): RealtimeTransportAdapter;
+
+/**
+ * Realtime voice tools — the tool-using layer on top of the v0.9.52
+ * audio bridge (see `realtime-bridge.ts`).
+ *
+ * # What this file is
+ *
+ * v0.9.52 wired a 46elks ⇄ OpenAI Realtime audio bridge that could only
+ * *converse*. v0.9.53 turns the voice agent into something that can
+ * *act* on a live call: ask the human operator a question, look things
+ * up, tell the time. The enabler is OpenAI Realtime **function
+ * calling** — tools declared in `session.tools`, called by the model
+ * mid-call, dispatched here, and answered back over the wire.
+ *
+ * This module is the transport-agnostic half of that:
+ *   - {@link RealtimeToolDefinition} — the JSON-schema tool shapes the
+ *     bridge declares to OpenAI.
+ *   - {@link ToolExecutor} — the interface the bridge dispatches calls
+ *     into; {@link createToolExecutor} builds one from a handler map.
+ *   - The *pure / fast* tool implementations ({@link getDatetime},
+ *     {@link recallMemory}, {@link webSearch}) — no sockets, no DB
+ *     handles passed in directly, fully unit-testable.
+ *   - {@link pollForOperatorAnswer} — the poll loop `ask_operator` uses
+ *     to block (with an injectable clock + sleep) until the operator
+ *     answers or the hard timeout elapses.
+ *   - {@link parseOperatorQueryReply} — parses an operator's *email*
+ *     reply back into a query answer (the channel-agnostic default
+ *     notifier path, see the plan §5).
+ *
+ * The *side-effecting* wiring — actually recording an operator query on
+ * a mission, sending the notification email, calling a web-search API —
+ * lives in `@agenticmail/api`'s `realtime-ws.ts`, which builds a
+ * {@link ToolExecutor} per connection. Keeping that split means
+ * `@agenticmail/core` stays dependency-light and every piece here is
+ * testable with fakes.
+ *
+ * > NOTE on OpenAI Realtime GA event/field names: the function-calling
+ * > wire shapes (`session.tools`, `tool_choice`, `function_call_output`,
+ * > `response.function_call_arguments.done`) follow the plan. Any name
+ * > that could not be verified against the v0.9.52 code is flagged with
+ * > a comment in `realtime-bridge.ts` — verify against current OpenAI
+ * > docs before the live smoke test (same discipline as v0.9.52's
+ * > `response.output_audio.delta` vs legacy `response.audio.delta`).
+ */
+/**
+ * A function tool as declared in the OpenAI Realtime `session.tools`
+ * array. The shape is the GA `gpt-realtime` function-tool schema:
+ * `{ type: 'function', name, description, parameters: <JSON Schema> }`.
+ */
+interface RealtimeToolDefinition {
+    type: 'function';
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}
+/** A function call parsed off the wire and ready to dispatch. */
+interface RealtimeToolCall {
+    /** OpenAI `call_id` — echoed back on the `function_call_output`. */
+    callId: string;
+    /** The tool name the model chose. */
+    name: string;
+    /** Parsed `arguments` object (`{}` if the model sent none / invalid). */
+    arguments: Record<string, unknown>;
+}
+/** The result of executing a tool — `output` is a string for the model. */
+interface RealtimeToolResult {
+    /** Sent back verbatim as the `function_call_output` `output` field. */
+    output: string;
+}
+/**
+ * Dispatches a model tool call to its implementation. The bridge holds
+ * one of these (injected) and calls {@link execute} for every
+ * function call; it must always resolve (never reject) — a failing
+ * tool resolves to an `output` the model can read and recover from.
+ */
+interface ToolExecutor {
+    execute(call: RealtimeToolCall): Promise<RealtimeToolResult>;
+}
+/**
+ * One tool's implementation. Receives the parsed arguments + the raw
+ * call. May return a plain string or a value that is JSON-stringified.
+ * It MAY throw — {@link createToolExecutor} catches and turns a thrown
+ * error into a model-readable output, so a buggy tool never wedges the
+ * call.
+ */
+type RealtimeToolHandler = (args: Record<string, unknown>, call: RealtimeToolCall) => Promise<string | Record<string, unknown>> | string | Record<string, unknown>;
+/**
+ * Hard ceiling on how long `ask_operator` blocks waiting for an answer.
+ * Per Ope (2026-05-19): a human caller will hold ~5 minutes; past that
+ * the graceful path is a callback (plan §7), not an indefinite hold.
+ */
+declare const OPERATOR_QUERY_TIMEOUT_MS: number;
+/** How often `ask_operator` re-checks the query record for an answer. */
+declare const OPERATOR_QUERY_POLL_INTERVAL_MS = 3000;
+/**
+ * Returned to the model as the `ask_operator` tool output when the
+ * operator did not answer in time. Phrased as an instruction the model
+ * can act on — it must NOT invent an answer, it should tell the caller
+ * a follow-up / callback is coming (the bridge + API handle the actual
+ * callback-on-disconnect, see the plan §7).
+ */
+declare const OPERATOR_QUERY_TIMEOUT_SENTINEL: string;
+/**
+ * Subject-line tag used by the email notifier. The query id is embedded
+ * so an operator's *reply* can be parsed straight back into an answer
+ * ({@link parseOperatorQueryReply}) — the channel-agnostic default path.
+ */
+declare const OPERATOR_QUERY_SUBJECT_TAG = "AgenticMail Operator Query";
+/**
+ * Phase 1 keystone — human-in-the-loop. The model calls this when it
+ * needs information, a decision, or approval it does not have. It can
+ * take minutes to answer, so the model is instructed (see
+ * {@link buildRealtimeToolGuidance}) to put the caller on hold first.
+ */
+declare const ASK_OPERATOR_TOOL: RealtimeToolDefinition;
+/** Phase 2 — a web search. Returns the top results as text. */
+declare const WEB_SEARCH_TOOL: RealtimeToolDefinition;
+/** Phase 2 — searches the agent's own persistent memory. */
+declare const RECALL_MEMORY_TOOL: RealtimeToolDefinition;
+/** Phase 2 — the current date/time, for resolving "tomorrow" etc. */
+declare const GET_DATETIME_TOOL: RealtimeToolDefinition;
+/**
+ * Phase 2 (optional) — searches the agent's AgenticMail inbox. Defined
+ * here so the schema is canonical, but NOT wired into the default
+ * executor in `realtime-ws.ts` (it needs IMAP access); a deployment can
+ * opt in. Kept in the file so the tool surface is documented in one place.
+ */
+declare const SEARCH_EMAIL_TOOL: RealtimeToolDefinition;
+/** Every tool defined in this module, keyed by name. */
+declare const REALTIME_TOOL_DEFINITIONS: Record<string, RealtimeToolDefinition>;
+/**
+ * Build the natural-language guidance appended to the Realtime session
+ * `instructions` when tools are present. This is the *model-side* half
+ * of "keep the line warm" (plan §6): the model announces a hold before
+ * a slow tool and reassures the caller while it waits. The bridge-side
+ * safety net (the tool-call timeout) is in `realtime-bridge.ts`.
+ */
+declare function buildRealtimeToolGuidance(tools: readonly RealtimeToolDefinition[]): string;
+/**
+ * Build a {@link ToolExecutor} from a `name → handler` map. The
+ * executor:
+ *   - resolves an unknown tool name to a model-readable "not available"
+ *     output (never rejects),
+ *   - catches a thrown / rejected handler and turns it into a
+ *     model-readable failure output,
+ *   - JSON-stringifies a non-string handler return.
+ *
+ * So a single buggy or missing tool can never crash the bridge or
+ * wedge the call — the model just gets an output it can recover from.
+ */
+declare function createToolExecutor(handlers: Record<string, RealtimeToolHandler>): ToolExecutor;
+interface GetDatetimeOptions {
+    /** IANA timezone; defaults to UTC. */
+    timezone?: string;
+    /** Clock override for tests. */
+    now?: Date;
+}
+/**
+ * `get_datetime` — current date/time as a human-readable line plus the
+ * exact ISO timestamp. Pure: an injectable clock makes it deterministic
+ * in tests. An invalid timezone falls back to UTC rather than throwing.
+ */
+declare function getDatetime(options?: GetDatetimeOptions): string;
+/**
+ * Minimal structural interface for the bit of `AgentMemoryManager`
+ * {@link recallMemory} needs. Declared here so this module does not
+ * have to import the full memory manager — `AgentMemoryManager`
+ * satisfies it structurally.
+ */
+interface MemoryRecaller {
+    recall(agentId: string, query: string, limit?: number): Promise<Array<{
+        title: string;
+        content: string;
+    }>>;
+}
+/**
+ * `recall_memory` — query the agent's own persistent memory. Returns a
+ * compact numbered list, or a clear "nothing found" line so the model
+ * does not stall on an empty result.
+ */
+declare function recallMemory(memory: MemoryRecaller, agentId: string, query: string, limit?: number): Promise<string>;
+interface WebSearchOptions {
+    /**
+     * Search endpoint. Defaults to the DuckDuckGo HTML endpoint
+     * ({@link DEFAULT_WEB_SEARCH_ENDPOINT}) — free, no API key, per the
+     * scope decision (plan §13.1). Overridable for tests / a mirror.
+     */
+    endpoint?: string;
+    /** `fetch` override for tests. */
+    fetchFn?: typeof fetch;
+    /** Max results to fold into the output (default 5, capped at 10). */
+    maxResults?: number;
+}
+/**
+ * Default web-search endpoint — DuckDuckGo's keyless HTML results page.
+ * Chosen because it needs no API key or account (plan §13.1: "web_search
+ * → DuckDuckGo only, free, no key").
+ */
+declare const DEFAULT_WEB_SEARCH_ENDPOINT = "https://html.duckduckgo.com/html/";
+/**
+ * Untrusted-content marker prefixed to every non-empty `web_search`
+ * result block (v0.9.53 security review).
+ *
+ * Web-search results are scraped page titles + snippets — attacker-
+ * controllable text that the model consumes verbatim as a
+ * `function_call_output`. A page that ranks for the caller's query can
+ * plant instructions in its `<title>` or snippet; without an explicit
+ * delimiter the model may read them as commands rather than data — the
+ * classic search-result prompt-injection vector. This marker tells the
+ * model the block is strictly reference data and that any instructions
+ * inside it must be ignored.
+ *
+ * (The enterprise web-search tool wrapped results the same way via
+ * `wrapWebContent` / `externalContent.untrusted`; the fresh DuckDuckGo
+ * helper here re-establishes that defense without copying the file.)
+ */
+declare const WEB_SEARCH_UNTRUSTED_PREFIX: string;
+/**
+ * `web_search` — a keyless DuckDuckGo lookup returning the top results
+ * as text. Reimplemented fresh as a small HTML-scrape helper (plan
+ * §13.1 / the host's provenance note: do not copy the enterprise
+ * file). No API key is needed, so unlike the other tools this one is
+ * always available.
+ *
+ * Fails *soft*: a non-OK response, an unreadable body, or a thrown
+ * fetch all resolve to a model-readable line rather than throwing — a
+ * search outage must never kill a live call.
+ *
+ * > DuckDuckGo's HTML page is an unversioned scrape target, not a
+ * > documented API: the `result__a` / `result__snippet` selectors and
+ * > the `/l/?uddg=` redirect wrapper below match the endpoint today;
+ * > verify them before the live smoke test (same "verify the wire
+ * > shape" discipline as the OpenAI Realtime event names).
+ */
+declare function webSearch(query: string, options?: WebSearchOptions): Promise<string>;
+interface OperatorQueryPollOptions {
+    /** Hard timeout (default {@link OPERATOR_QUERY_TIMEOUT_MS}). */
+    timeoutMs?: number;
+    /** Poll interval (default {@link OPERATOR_QUERY_POLL_INTERVAL_MS}). */
+    pollIntervalMs?: number;
+    /** Clock override for tests (returns ms). */
+    now?: () => number;
+    /** Sleep override for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Abort handle — when `aborted` flips true the poll resolves null. */
+    signal?: {
+        readonly aborted: boolean;
+    };
+}
+/**
+ * Poll `readAnswer` until it yields a non-empty answer or the timeout
+ * elapses. Returns the trimmed answer, or `null` on timeout / abort.
+ *
+ * This is the loop `ask_operator` runs to *block* the tool call while
+ * it waits for the human. The clock + sleep are injectable so tests run
+ * the full timeout path in microseconds. The `signal` lets the caller
+ * abandon the wait early — e.g. the call dropped, so there is no point
+ * polling (the unanswered query then drives callback-on-disconnect).
+ */
+declare function pollForOperatorAnswer(readAnswer: () => Promise<string | null | undefined> | string | null | undefined, options?: OperatorQueryPollOptions): Promise<string | null>;
+/**
+ * Build the notification email subject for an operator query. The query
+ * id is embedded in a `[tag id]` token so the operator's reply (subject
+ * `Re: [tag id] …`) can be parsed straight back into an answer.
+ */
+declare function operatorQuerySubject(queryId: string, callContext?: string): string;
+/**
+ * Parse an operator's email reply into `{ queryId, answer }`, or `null`
+ * if the email is not an operator-query reply (no id token in the
+ * subject) or carries no usable answer text.
+ *
+ * This is the pure half of the channel-agnostic notifier (plan §5): the
+ * default notifier emails the operator; their reply lands back in the
+ * agent's inbox; the inbound mail hook runs this and posts the answer
+ * to the same query record the HTTP endpoint writes to.
+ */
+declare function parseOperatorQueryReply(input: {
+    subject?: string;
+    text?: string;
+}): {
+    queryId: string;
+    answer: string;
+} | null;
+/**
+ * Extract the bare email address from a `From`-style value, lowercased
+ * and trimmed. Accepts `"Name" <addr@host>`, `<addr@host>`, or a plain
+ * `addr@host`; returns `''` for an empty / unusable input.
+ */
+declare function extractEmailAddress(value: string | null | undefined): string;
+/**
+ * Fail-closed sender check for the operator email-reply answer path
+ * (plan §5; added in the v0.9.53 security review).
+ *
+ * An operator-query answer arriving by email is gated by the query id
+ * embedded in the subject — an unguessable 122-bit v4 UUID, but one that
+ * rides in *plaintext* subject lines through quoting, forwarding, and
+ * relay/provider logs. The id alone is therefore a materially weaker
+ * gate than the HMAC per-mission token used on the phone webhook (which
+ * only 46elks ever sees). So an emailed answer is accepted ONLY when its
+ * `From` address matches the configured operator address (case-
+ * insensitive, address-only).
+ *
+ * Returns `false` when no `operatorEmail` is configured — no operator
+ * means nobody is trusted (fail closed), so the email-reply path is
+ * simply inert on a deployment without one.
+ *
+ * NOTE: ultimate strength still depends on inbound SPF/DKIM rejecting a
+ * spoofed `From`; this check closes the casual-leak path — a leaked or
+ * forwarded subject token replied to from an arbitrary address.
+ */
+declare function isOperatorReplySender(from: string | null | undefined, operatorEmail: string | null | undefined): boolean;
+
+/**
+ * Realtime voice bridge — wires the OpenAI Realtime API to a phone
+ * carrier's realtime-media WebSocket so a phone mission can actually
+ * *converse*.
+ *
+ * # Shape of the integration
+ *
+ *   caller  ⇄  carrier  ⇄  (carrier media WebSocket)  ⇄  AgenticMail
+ *                                                         │
+ *                                          RealtimeVoiceBridge
+ *                                                         │
+ *                                      (OpenAI Realtime WebSocket)
+ *                                                         │
+ *                                                   gpt-realtime
+ *
+ * The carrier streams the live call audio to AgenticMail as JSON frames
+ * (base64 audio); AgenticMail relays them to OpenAI as
+ * `input_audio_buffer.append`; OpenAI streams synthesised speech back
+ * as `response.output_audio.delta`; AgenticMail relays that to the
+ * carrier. Server-side VAD on the OpenAI session handles turn-taking —
+ * no manual commit / response.create.
+ *
+ * # Provider-pluggable transport
+ *
+ * The carrier side speaks a provider-specific wire protocol — 46elks
+ * (`hello`/`audio`/`bye`, linear PCM) and Twilio Media Streams
+ * (`connected`/`start`/`media`/`stop`, G.711 µ-law). Those differences
+ * are isolated behind a {@link RealtimeTransportAdapter}: the bridge
+ * itself — OpenAI session lifecycle, function calling, barge-in,
+ * transcript, teardown — is identical across providers and lives here
+ * once. The bridge defaults to the 46elks adapter, so existing callers
+ * that pass no `transport` keep their exact prior behaviour.
+ *
+ * # Memory injection — the whole point
+ *
+ * Before the OpenAI session starts, the agent's persistent memory is
+ * rendered (`AgentMemoryManager.generateMemoryContext()`) and folded
+ * into the Realtime session `instructions`. The model is told to treat
+ * that block as *its own* long-term knowledge — so on the call it acts
+ * with full continuity, as if it had always known those things.
+ *
+ * # Why this file is transport-agnostic
+ *
+ * `RealtimeVoiceBridge` never touches a socket. It takes two abstract
+ * {@link RealtimeBridgePort}s (one per side) and is driven by
+ * `handle*Message` / `handle*Open` / `handle*Close` calls. The real
+ * WebSocket plumbing lives in `@agenticmail/api` (which has the `ws`
+ * dependency); tests drive the bridge with in-memory fake ports. This
+ * keeps `@agenticmail/core` dependency-free and the bridge logic fully
+ * unit-testable without a live OpenAI key or a carrier websocket number.
+ *
+ * The exact OpenAI Realtime wire shapes below are the GA `gpt-realtime`
+ * protocol (session config nested under `audio.input` / `audio.output`,
+ * `format` as an object, `response.output_audio.delta` for output). The
+ * legacy beta output event name `response.audio.delta` is also handled
+ * defensively — some `gpt-realtime` deployments still emit it.
+ */
+
+/** OpenAI Realtime WebSocket base URL (model passed as `?model=`). */
+declare const OPENAI_REALTIME_URL = "wss://api.openai.com/v1/realtime";
+/** GA Realtime model. */
+declare const DEFAULT_REALTIME_MODEL = "gpt-realtime";
+/** Default GA Realtime voice. */
+declare const DEFAULT_REALTIME_VOICE = "marin";
+/** PCM sample rate shared by 46elks `pcm_24000` and the OpenAI session. */
+declare const REALTIME_AUDIO_SAMPLE_RATE = 24000;
+/**
+ * #46-H1 — hard ceiling on a single inbound audio frame, measured in
+ * base64 characters. Realtime frames are tiny (20–100 ms of audio); a
+ * frame larger than this is either a buggy or a hostile peer trying to
+ * push an unbounded allocation through the bridge. Oversized frames are
+ * dropped, never forwarded. ~256 KiB of base64 ≈ 4 s of 24 kHz PCM16 —
+ * far above any legitimate realtime frame, so this never trims real
+ * speech, it only fences off abuse.
+ */
+declare const REALTIME_MAX_AUDIO_FRAME_BASE64: number;
+/**
+ * Bridge-side safety net for a slow tool call (plan §6). The model-side
+ * keeps the line warm (it announces a hold and reassures the caller);
+ * this is the floor under that — if a tool's `execute()` never settles
+ * (a hung `ask_operator`, a wedged search) the bridge still answers the
+ * model after this long so the call cannot be wedged forever. It is set
+ * deliberately ABOVE `OPERATOR_QUERY_TIMEOUT_MS` (5 min) so the tool's
+ * own graceful timeout sentinel normally wins the race; this only fires
+ * if the executor itself hangs.
+ */
+declare const REALTIME_TOOL_CALL_TIMEOUT_MS: number;
+interface RealtimeInstructionOptions {
+    /** The concrete objective of this call. */
+    task: string;
+    /** Rendered agent memory block (from `generateMemoryContext()`). */
+    memoryContext?: string;
+    /** The agent's display name, used in the persona line. */
+    agentName?: string;
+    /** Override the default persona preamble. */
+    persona?: string;
+    /**
+     * Natural-language tool-use guidance, appended as its own section.
+     * Normally produced by `buildRealtimeToolGuidance()` and folded in
+     * automatically by `buildRealtimeSessionConfig()` when tools are set.
+     */
+    toolGuidance?: string;
+}
+/**
+ * Compose the Realtime session `instructions` string. The agent's
+ * memory is presented as the model's *own* knowledge — not as external
+ * notes — so the call feels continuous with everything the agent has
+ * learned elsewhere.
+ */
+declare function buildRealtimeInstructions(opts: RealtimeInstructionOptions): string;
+interface RealtimeSessionConfigOptions extends RealtimeInstructionOptions {
+    /** OpenAI Realtime voice (default {@link DEFAULT_REALTIME_VOICE}). */
+    voice?: string;
+    /** OpenAI Realtime model (default {@link DEFAULT_REALTIME_MODEL}). */
+    model?: string;
+    /** Provide a fully-formed instruction string instead of composing one. */
+    instructions?: string;
+    /**
+     * Function tools to declare on the session. When present they are
+     * emitted under `session.tools` with a `tool_choice`, and (unless
+     * `instructions` is overridden) tool-use guidance is folded into the
+     * composed instructions automatically.
+     */
+    tools?: RealtimeToolDefinition[];
+    /** `tool_choice` override — defaults to `'auto'` when tools are set. */
+    toolChoice?: 'auto' | 'none' | 'required';
+    /**
+     * OpenAI Realtime audio format for the session's input AND output.
+     * Defaults to linear PCM @ 24 kHz (`{ type: 'audio/pcm', rate: 24000 }`)
+     * — the format a 46elks `pcm_24000` call needs. A Twilio call must
+     * pass `{ type: 'audio/pcmu', rate: 8000 }` (G.711 µ-law @ 8 kHz) so
+     * the OpenAI session speaks the carrier's native codec with NO
+     * transcoding. Normally sourced from a {@link RealtimeTransportAdapter}'s
+     * `openaiAudioFormat`.
+     */
+    audioFormat?: {
+        type: string;
+        rate?: number;
+    };
+}
+/** Default OpenAI Realtime audio format — linear PCM @ 24 kHz (46elks). */
+declare const DEFAULT_REALTIME_AUDIO_FORMAT: {
+    readonly type: "audio/pcm";
+};
+/**
+ * Build the `session.update` client event for the GA `gpt-realtime`
+ * API. Audio in/out default to PCM16 @ 24 kHz (matches 46elks
+ * `pcm_24000`); a Twilio call passes `audioFormat: { type: 'audio/pcmu',
+ * rate: 8000 }` so the session speaks G.711 µ-law natively. Turn-taking
+ * is server-side VAD, and the agent's memory is folded into
+ * `instructions`.
+ *
+ * When `tools` are supplied they are declared under `session.tools`
+ * with a `tool_choice` (default `'auto'`), and — unless the caller
+ * passed an explicit `instructions` string — natural-language tool-use
+ * guidance is appended to the composed instructions so the model knows
+ * to put the caller on hold before a slow tool (plan §6).
+ *
+ * > The `session.tools` / `tool_choice` field names follow the OpenAI
+ * > Realtime function-calling protocol per the plan §3, and the
+ * > `audio/pcmu` µ-law format token follows the OpenAI GA Realtime
+ * > audio-format protocol; verify both against current OpenAI docs
+ * > before the live smoke test.
+ */
+declare function buildRealtimeSessionConfig(opts: RealtimeSessionConfigOptions): Record<string, unknown>;
+/** Build the `wss://…/v1/realtime?model=…` URL for a model. */
+declare function buildOpenAIRealtimeUrl(model?: string): string;
+/** One side of the bridge — a JSON message sink that can be closed. */
+interface RealtimeBridgePort {
+    /** Send one JSON message to the peer. Must not throw. */
+    send(message: Record<string, unknown>): void;
+    /** Close the underlying connection. Must be idempotent. */
+    close(): void;
+}
+interface RealtimeBridgeTranscriptEntry {
+    source: 'system' | 'provider' | 'agent';
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+interface RealtimeVoiceBridgeOptions {
+    /**
+     * Port to the carrier realtime-media side. Named `elks` for backward
+     * compatibility (it predates the Twilio transport); `carrier` is the
+     * provider-neutral alias and takes precedence if both are given.
+     */
+    elks?: RealtimeBridgePort;
+    /** Provider-neutral alias for {@link elks} — the carrier media port. */
+    carrier?: RealtimeBridgePort;
+    /** Port to the OpenAI Realtime side. */
+    openai: RealtimeBridgePort;
+    /** `session.update` payload — sent to OpenAI once its socket opens. */
+    sessionConfig: Record<string, unknown>;
+    /**
+     * Carrier transport adapter — encodes/decodes the provider's wire
+     * protocol (46elks vs Twilio Media Streams). Defaults to the 46elks
+     * adapter, so callers that omit it keep the original behaviour.
+     */
+    transport?: RealtimeTransportAdapter;
+    /**
+     * 46elks-only: audio format we ask 46elks to send us (default
+     * `pcm_24000`). Ignored unless the default 46elks transport is used
+     * and no explicit `transport` was supplied.
+     */
+    listenFormat?: ElksRealtimeAudioFormat;
+    /**
+     * 46elks-only: audio format we declare for the audio we send 46elks
+     * (default `pcm_24000`). Ignored unless the default 46elks transport
+     * is used and no explicit `transport` was supplied.
+     */
+    sendFormat?: ElksRealtimeAudioFormat;
+    /** Per-frame base64 ceiling (default {@link REALTIME_MAX_AUDIO_FRAME_BASE64}). */
+    maxAudioFrameBase64?: number;
+    /**
+     * Dispatches the model's function calls. When omitted the bridge has
+     * no tools — a function call from the model is acknowledged with a
+     * "no tools available" output rather than left to wedge the model.
+     */
+    toolExecutor?: ToolExecutor;
+    /**
+     * Bridge-side safety-net timeout for a single tool call (default
+     * {@link REALTIME_TOOL_CALL_TIMEOUT_MS}). If the executor does not
+     * settle within this window the bridge answers the model itself so
+     * the call cannot be wedged by a hung tool.
+     */
+    maxToolCallMs?: number;
+    /** Sink for transcript / lifecycle entries worth persisting on the mission. */
+    onTranscript?: (entry: RealtimeBridgeTranscriptEntry) => void;
+    /**
+     * Called exactly once when the bridge has fully ended. `pendingToolCalls`
+     * is how many tool calls were still in flight at teardown — non-zero
+     * means the call dropped mid-tool (e.g. an unanswered `ask_operator`),
+     * which is the signal the API layer uses to arm callback-on-disconnect
+     * (plan §7).
+     */
+    onEnd?: (summary: {
+        reason: string;
+        pendingToolCalls: number;
+    }) => void;
+}
+/**
+ * Bridges a phone carrier's realtime-media connection to an OpenAI
+ * Realtime connection. Provider-pluggable: the carrier wire protocol
+ * (46elks vs Twilio Media Streams) is isolated in a
+ * {@link RealtimeTransportAdapter}; the conversation logic here is
+ * provider-neutral. The caller pumps raw messages in via
+ * `handleCarrierMessage` / `handleOpenAIMessage` and connection
+ * lifecycle via `handle*Open` / `handle*Close`. Every public method is
+ * safe to call after the bridge has ended (they become no-ops).
+ *
+ * The legacy `handleElks*` method names remain as thin aliases for the
+ * `handleCarrier*` methods so existing 46elks call sites and tests do
+ * not break.
+ */
+declare class RealtimeVoiceBridge {
+    private readonly carrier;
+    private readonly openai;
+    private readonly sessionConfig;
+    private readonly transport;
+    private readonly maxAudioFrameBase64;
+    private readonly toolExecutor?;
+    private readonly maxToolCallMs;
+    private readonly onTranscript?;
+    private readonly onEnd?;
+    /** Carrier `hello`/`start` received — the call leg is live. */
+    private helloSeen;
+    /** OpenAI socket open + `session.update` sent. */
+    private openaiReady;
+    /** Bridge has ended — all further input is ignored. */
+    private ended;
+    /** Carrier call id from the `hello` event (46elks `callid` / Twilio `callSid`). */
+    private callId;
+    /** Audio frames received before OpenAI was ready, flushed on open. */
+    private readonly pendingAudio;
+    /** Oversized-frame counter — reported once, not per frame. */
+    private droppedFrames;
+    private droppedFramesReported;
+    /** Accumulated assistant speech transcript for the current response. */
+    private assistantTranscript;
+    /**
+     * Function-call name keyed by `call_id`, captured from
+     * `response.output_item.added`. The later `*.arguments.done` event is
+     * not guaranteed to echo the tool name, so we remember it here.
+     */
+    private readonly toolCallNames;
+    /** `call_id`s whose tool call is currently executing. */
+    private readonly inFlightToolCalls;
+    constructor(opts: RealtimeVoiceBridgeOptions);
+    /** True once the bridge has ended. */
+    get isEnded(): boolean;
+    /** The carrier call id, once the `hello`/`start` event has been seen. */
+    get currentCallId(): string;
+    /** The carrier transport provider this bridge is running for. */
+    get provider(): string;
+    /** How many tool calls are executing right now. */
+    get pendingToolCalls(): number;
+    /** Call when the OpenAI socket opens — sends `session.update`. */
+    handleOpenAIOpen(): void;
+    /** Call when the OpenAI socket closes. */
+    handleOpenAIClose(): void;
+    /** Call when the OpenAI socket errors. */
+    handleOpenAIError(err: unknown): void;
+    /**
+     * Call when the carrier media socket closes. The `onEnd` reason is
+     * `<prefix>-closed`, where the prefix comes from the transport adapter
+     * (`elks` for 46elks, `twilio` for Twilio) — so historical 46elks
+     * reason strings (`elks-closed`) are preserved.
+     */
+    handleCarrierClose(): void;
+    /** Call when the carrier media socket errors. */
+    handleCarrierError(err: unknown): void;
+    /** @deprecated 46elks-era alias for {@link handleCarrierClose}. */
+    handleElksClose(): void;
+    /** @deprecated 46elks-era alias for {@link handleCarrierError}. */
+    handleElksError(err: unknown): void;
+    /**
+     * Feed one raw message from the carrier media socket. Accepts a JSON
+     * string or an already-parsed object. The transport adapter
+     * normalises the provider-specific frame; malformed frames throw out
+     * of the adapter and are ignored here (the bridge is never torn down
+     * for one bad frame).
+     */
+    handleCarrierMessage(raw: string | Record<string, unknown>): void;
+    /** @deprecated 46elks-era alias for {@link handleCarrierMessage}. */
+    handleElksMessage(raw: string | Record<string, unknown>): void;
+    /** Relay caller audio to OpenAI, enforcing the per-frame size cap. */
+    private forwardInboundAudio;
+    /**
+     * Feed one raw message from the OpenAI Realtime socket. Accepts a
+     * JSON string or an already-parsed object. Unknown event types are
+     * ignored.
+     */
+    handleOpenAIMessage(raw: string | Record<string, unknown>): void;
+    /** Relay synthesised agent audio to the carrier, enforcing the size cap. */
+    private forwardOutboundAudio;
+    /**
+     * Parse a `response.function_call_arguments.done` event and dispatch
+     * the tool call. Resolves `name` from the event or the map captured
+     * on `response.output_item.added`; parses `arguments` (a JSON string)
+     * defensively. Always answers the model — an unknown name, missing
+     * executor, or oversized fan-out each gets a model-readable output
+     * rather than being dropped (a dropped `call_id` wedges the model,
+     * which waits forever for its `function_call_output`).
+     */
+    private dispatchToolCall;
+    /** Execute one tool call, racing the executor against the safety-net timeout. */
+    private runToolCall;
+    /**
+     * Send a tool result back to OpenAI: a `function_call_output`
+     * conversation item, then `response.create` so the model resumes
+     * speaking with the result in hand.
+     *
+     * > `conversation.item.create` with `{ type: 'function_call_output',
+     * > call_id, output }` followed by `response.create` is the OpenAI
+     * > Realtime function-calling return path per the plan §3. Verify
+     * > against current OpenAI docs before the live smoke test.
+     */
+    private answerToolCall;
+    /**
+     * End the bridge. Idempotent — the first call wins, later calls are
+     * no-ops. Sends the carrier's end-of-call frame (if it has one — 46elks
+     * `bye`; Twilio has none), closes both ports, fires `onEnd`.
+     */
+    end(reason: string): void;
+    private noteDroppedFrame;
+    private emitTranscript;
+    private safeSend;
+}
+
 declare const PHONE_REGION_SCOPES: readonly ["AT", "DE", "EU", "WORLD"];
 type PhoneRegionScope = typeof PHONE_REGION_SCOPES[number];
 declare const TELEPHONY_TRANSPORT_CAPABILITIES: readonly ["sms", "call_control", "realtime_media", "recording_supported"];
@@ -1839,7 +3322,9 @@ declare function validatePhoneMissionStart(input: unknown, transport: unknown, o
     allowPremiumOrSpecialNumbers?: boolean;
 }): PhoneMissionStartValidationResult;
 
-type PhoneTransportProvider = '46elks';
+type PhoneTransportProvider = '46elks' | 'twilio';
+/** Providers that support starting outbound call-control missions. */
+declare const PHONE_CALL_CONTROL_PROVIDERS: readonly PhoneTransportProvider[];
 /**
  * Abuse / cost controls for the call-control surface. A phone mission
  * places a real, billed outbound call, so /calls/start needs hard limits
@@ -1881,6 +3366,29 @@ interface PhoneMissionTranscriptEntry {
     text: string;
     metadata?: Record<string, unknown>;
 }
+type OperatorQueryUrgency = 'normal' | 'high';
+/**
+ * A question the voice agent put to its human operator mid-call via the
+ * `ask_operator` tool (plan §4 / §5). Persisted on the mission under
+ * `metadata.operatorQueries[]` and exposed by the operator-query API
+ * endpoints. The bridge's `ask_operator` tool blocks polling this
+ * record until `answer` is set or the hard timeout elapses.
+ */
+interface PhoneOperatorQuery {
+    /** `oq_<uuid>` — unique across all missions. */
+    id: string;
+    /** The question, sanitised + length-bounded. */
+    question: string;
+    /** One-line context on the call, if the agent supplied it. */
+    callContext?: string;
+    urgency: OperatorQueryUrgency;
+    askedAt: string;
+    /** The operator's answer — set once, never overwritten (idempotent). */
+    answer?: string;
+    answeredAt?: string;
+    /** Channel the answer arrived on (e.g. `api`, `email`). */
+    answeredVia?: string;
+}
 interface PhoneCallMission {
     id: string;
     agentId: string;
@@ -1951,6 +3459,52 @@ declare class PhoneManager {
     private authenticateWebhook;
     handleVoiceStartWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneWebhookResult;
     handleHangupWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneCallMission;
+    /**
+     * Handle Twilio's voice webhook — the `Url` Twilio fetches when the
+     * outbound call connects. The mirror of {@link handleVoiceStartWebhook}
+     * for Twilio: it authenticates the per-mission token, transitions the
+     * mission to `connected`, and returns the TwiML to send back.
+     *
+     * `twiml` is a `<Connect><Stream>` document that wires the call's
+     * audio to the realtime voice WebSocket — the same realtime path the
+     * 46elks websocket-number uses. The route serves it with
+     * `Content-Type: text/xml`.
+     *
+     * Like the 46elks handler this is terminal-state-guarded (#43-H5,
+     * a late/replayed webhook cannot resurrect a finished mission) and
+     * idempotent (a duplicate is acknowledged with the same TwiML but
+     * changes nothing).
+     */
+    handleTwilioVoiceWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): {
+        mission: PhoneCallMission;
+        twiml: string;
+    };
+    /**
+     * Handle Twilio's status callback — the `StatusCallback` Twilio POSTs
+     * with the terminal call status. The mirror of
+     * {@link handleHangupWebhook} for Twilio. Idempotent + terminal-state
+     * guarded; records the reported `CallDuration` and accumulates cost
+     * from `Price` when Twilio supplied it (Twilio reports the final
+     * price asynchronously, so it may be absent on the first callback —
+     * the duration ceiling / rate limit / concurrency cap remain the
+     * preventive cost controls, #43-H2).
+     */
+    handleTwilioStatusWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneCallMission;
+    /**
+     * Build the TwiML for the Twilio voice webhook — a `<Connect><Stream>`
+     * pointing at the realtime voice WebSocket. The `<Stream>` URL is
+     * derived from `webhookBaseUrl` (https → wss); the per-mission token
+     * (#43-H7) rides as both a `<Parameter>` and a query param so the
+     * media socket can be matched to its mission.
+     */
+    private buildTwilioVoiceTwiML;
+    /**
+     * Read the call cost off a Twilio status callback (`Price`, a
+     * negative or string number), add it to the mission's running total,
+     * and flag a policy-cap breach (#43-H2). Twilio prices are reported
+     * as a negative amount (a debit); we use the absolute value.
+     */
+    private buildTwilioCostMetadataPatch;
     /**
      * Read the call cost off a 46elks hangup payload, add it to the
      * mission's running total, and flag a policy-cap breach (#43-H2).
@@ -1961,7 +3515,117 @@ declare class PhoneManager {
     private buildCostMetadataPatch;
     private buildVoiceStartAction;
     cancelMission(agentId: string, missionId: string): PhoneCallMission;
+    /**
+     * Resolve a mission by the provider's call id (the 46elks `callid`).
+     * The realtime voice bridge uses this to match an inbound 46elks
+     * realtime-media WebSocket — whose `hello` frame carries `callid` —
+     * back to the mission that placed the call, so the right agent's
+     * memory and task can be loaded into the OpenAI Realtime session.
+     */
+    findMissionByProviderCallId(providerCallId: string, agentId?: string): PhoneCallMission | null;
+    /**
+     * Append transcript entries produced by the realtime voice bridge and
+     * optionally transition the mission status. A mission already in a
+     * terminal state keeps that state — a late bridge event must not
+     * resurrect a completed/failed/cancelled mission (mirrors the
+     * terminal-state guard on the webhook handlers). No-op if the mission
+     * no longer exists.
+     */
+    recordRealtimeActivity(missionId: string, entries: PhoneMissionTranscriptEntry[], status?: PhoneMissionState): PhoneCallMission | null;
+    /**
+     * Record an operator query against a mission — the first step of the
+     * `ask_operator` tool (plan §4). Returns the persisted query; the
+     * bridge then polls {@link getOperatorQuery} for an answer. Throws on
+     * an unknown mission or an empty question.
+     */
+    addOperatorQuery(missionId: string, input: {
+        question: string;
+        callContext?: string;
+        urgency?: string;
+    }): {
+        mission: PhoneCallMission;
+        query: PhoneOperatorQuery;
+    };
+    /** List the operator queries recorded on a mission. */
+    listOperatorQueries(missionId: string, agentId?: string): PhoneOperatorQuery[];
+    /** Read one operator query, or null if the mission/query is unknown. */
+    getOperatorQuery(missionId: string, queryId: string, agentId?: string): PhoneOperatorQuery | null;
+    /**
+     * Resolve a mission + query by the query id alone — used by the
+     * inbound email-reply hook, which only has the id parsed out of the
+     * reply subject. A LIKE prefilter (id escaped so its `_`/`-` are
+     * literal) narrows the scan; the match is then verified exactly.
+     */
+    findMissionByOperatorQueryId(queryId: string): {
+        mission: PhoneCallMission;
+        query: PhoneOperatorQuery;
+    } | null;
+    /**
+     * Record the operator's answer to a query. Idempotent — the first
+     * answer wins; a later answer for the same query returns the existing
+     * record unchanged with `alreadyAnswered: true`, so a duplicate
+     * (e.g. an email reply AND an API POST) cannot fight. Returns null if
+     * the mission/query is unknown; throws on an empty answer.
+     */
+    answerOperatorQuery(missionId: string, queryId: string, answer: string, options?: {
+        via?: string;
+        agentId?: string;
+    }): {
+        mission: PhoneCallMission;
+        query: PhoneOperatorQuery;
+        alreadyAnswered: boolean;
+    } | null;
+    /**
+     * Flag a mission for callback-on-disconnect: the call dropped while
+     * an operator query was still unanswered, so once the operator
+     * answers the API should dial the caller back. Returns the mission
+     * unchanged (not flagged) if every query is already answered; null if
+     * the mission is unknown.
+     */
+    flagCallbackPending(missionId: string): PhoneCallMission | null;
+    /** Missions currently flagged for callback-on-disconnect. */
+    findCallbackPendingMissions(agentId?: string): PhoneCallMission[];
+    /**
+     * Trigger a callback (plan §7) when a callback-pending mission now has
+     * an answered query: re-dial the same number with a continuation task
+     * carrying the operator's answer. Returns the (updated) original
+     * mission + the new callback mission, or null if no callback is due.
+     *
+     * `callbackPending` is cleared BEFORE dialing so a concurrent second
+     * answer cannot double-dial; if the dial throws it is restored so the
+     * callback is not silently lost, and the error is rethrown.
+     */
+    triggerCallback(missionId: string, options?: StartPhoneCallOptions): Promise<{
+        mission: PhoneCallMission;
+        callbackMission: PhoneCallMission;
+    } | null>;
     private build46ElksCallRequest;
+    /**
+     * Build the Twilio outbound-call request — the mirror of
+     * {@link build46ElksCallRequest} for Twilio's Calls.json endpoint:
+     *
+     *   POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls.json
+     *
+     * with an `application/x-www-form-urlencoded` body. `From`/`To` are
+     * the numbers; `Url` is a TwiML webhook Twilio fetches when the call
+     * connects — it points at our voice-start webhook, which returns the
+     * `<Connect><Stream>` TwiML that wires the call's audio to the
+     * realtime voice WebSocket. `StatusCallback` is Twilio's hangup-
+     * equivalent — fired with the final call status (the analogue of the
+     * 46elks `whenhangup`). `TimeLimit` caps the call duration, re-clamped
+     * to the server ceiling (#43-H6) exactly as the 46elks `timeout` is.
+     *
+     * Both webhook URLs carry the per-mission HMAC token (#43-H7), never
+     * the raw `webhookSecret`. The Twilio `AccountSid` is `config.username`
+     * and the `AuthToken` is `config.password` (HTTP Basic on the request,
+     * and the key Twilio signs `X-Twilio-Signature` with).
+     *
+     * > The Calls.json endpoint path, the `From`/`To`/`Url`/
+     * > `StatusCallback`/`TimeLimit` body fields, and the `<Connect>
+     * > <Stream>` TwiML are per Twilio's public Programmable Voice docs;
+     * > verify against current docs before the live smoke-test.
+     */
+    private buildTwilioCallRequest;
     private insertMission;
     private updateProviderCall;
     private updateMissionStatus;
@@ -1971,6 +3635,10 @@ declare function buildPhoneTransportConfig(input: {
     phoneNumber?: unknown;
     username?: unknown;
     password?: unknown;
+    /** Twilio alias for {@link username} — the account SID. */
+    accountSid?: unknown;
+    /** Twilio alias for {@link password} — the account auth token. */
+    authToken?: unknown;
     webhookBaseUrl?: unknown;
     webhookSecret?: unknown;
     apiUrl?: unknown;
@@ -2772,6 +4440,333 @@ declare class SetupManager {
     isInitialized(): boolean;
 }
 
+/** External binary a media operation depends on. */
+type MediaBinary = 'ffmpeg' | 'ffprobe' | 'imagemagick' | 'whisper' | 'python' | 'edge-tts';
+/**
+ * Detection result for one external binary. `available: false` carries
+ * an actionable `installHint` the agent can relay to the operator.
+ */
+interface MediaCapability {
+    /** Binary identifier. */
+    binary: MediaBinary;
+    /** Whether the binary was found and is runnable. */
+    available: boolean;
+    /** Version string when detectable. */
+    version?: string;
+    /** Resolved path / command used to invoke it. */
+    command?: string;
+    /** Human-readable description of what it powers. */
+    description: string;
+    /** Install instructions, present when `available` is false. */
+    installHint?: string;
+}
+/** Aggregate media capability report — one entry per binary. */
+interface MediaCapabilityReport {
+    /** Per-binary detection results. */
+    capabilities: MediaCapability[];
+    /** True when at least ffmpeg + ffprobe are present (the baseline). */
+    ready: boolean;
+    /** When the report was generated. */
+    checkedAt: string;
+}
+/** Result envelope for an operation that produced an output file. */
+interface MediaFileResult {
+    ok: true;
+    /** Absolute path of the produced file. */
+    filePath: string;
+    /** Size of the produced file in bytes. */
+    sizeBytes: number;
+    /** Output container/format, when meaningful. */
+    format?: string;
+    /** Operation-specific extra fields. */
+    [key: string]: unknown;
+}
+interface TtsGenerateOptions {
+    /** Text to synthesise. */
+    text: string;
+    /** Voice preset name or a full Edge voice id. */
+    voice?: string;
+    /** Speaking rate, e.g. "+20%" / "-10%". */
+    rate?: string;
+    /** Pitch shift, e.g. "+5Hz" / "-10Hz". */
+    pitch?: string;
+}
+type ImageAction = 'resize' | 'crop' | 'rotate' | 'convert' | 'compress' | 'text_overlay' | 'flip' | 'blur' | 'sharpen' | 'grayscale';
+interface ImageEditOptions {
+    /** Absolute path to the input image. */
+    input: string;
+    /** Edit action to perform. */
+    action: ImageAction;
+    width?: number;
+    height?: number;
+    angle?: number;
+    format?: string;
+    quality?: number;
+    text?: string;
+    position?: string;
+    fontSize?: number;
+    fontColor?: string;
+    blurRadius?: number;
+    direction?: 'horizontal' | 'vertical';
+    offsetX?: number;
+    offsetY?: number;
+}
+type VideoAction = 'trim' | 'extract_frame' | 'extract_frames' | 'convert' | 'gif' | 'compress' | 'resize' | 'add_audio' | 'remove_audio' | 'speed' | 'color_grade' | 'transition' | 'text_overlay' | 'picture_in_picture' | 'split_screen' | 'ken_burns' | 'slow_motion' | 'watermark' | 'concatenate' | 'audio_mix' | 'auto_caption';
+interface VideoEditOptions {
+    /** Absolute path to the input video (or image for ken_burns). */
+    input: string;
+    /** Edit action to perform. */
+    action: VideoAction;
+    start?: string;
+    end?: string;
+    duration?: string;
+    timestamp?: string;
+    interval?: number;
+    format?: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    crf?: number;
+    audioPath?: string;
+    speedFactor?: number;
+    secondInput?: string;
+    transitionType?: string;
+    transitionDuration?: number;
+    text?: string;
+    fontSize?: number;
+    fontColor?: string;
+    textPosition?: string;
+    textBg?: string;
+    textStart?: string;
+    textEnd?: string;
+    overlayOpacity?: number;
+    overlayScale?: number;
+    watermarkPosition?: string;
+    watermarkPath?: string;
+    pipWidth?: number;
+    pipPosition?: string;
+    splitDirection?: 'horizontal' | 'vertical';
+    zoomDirection?: string;
+    zoomDuration?: number;
+    zoomFactor?: number;
+    files?: string[];
+    bgVolume?: string;
+    fgVolume?: string;
+    colorPreset?: string;
+    lutPath?: string;
+    captionColor?: string;
+    captionFontSize?: number;
+    /** Path to a whisper.cpp model file (.bin) — required for auto_caption. */
+    whisperModel?: string;
+}
+type AudioAction = 'trim' | 'convert' | 'merge' | 'volume' | 'speed' | 'extract' | 'reverse' | 'fade';
+interface AudioEditOptions {
+    /** Absolute path to the input audio (or video for `extract`). */
+    input?: string;
+    /** Edit action to perform. */
+    action: AudioAction;
+    start?: string;
+    end?: string;
+    duration?: string;
+    format?: string;
+    files?: string[];
+    volume?: string;
+    speedFactor?: number;
+    fadeType?: 'in' | 'out' | 'both';
+    fadeDuration?: number;
+}
+interface MediaStreamInfo {
+    type?: string;
+    codec?: string;
+    width?: number;
+    height?: number;
+    duration?: string;
+    bitRate?: string;
+    sampleRate?: string;
+    channels?: number;
+    fps?: string;
+}
+interface MediaInfoResult {
+    ok: true;
+    file: string;
+    format?: string;
+    duration?: string;
+    sizeBytes: number;
+    bitRate?: string;
+    streams: MediaStreamInfo[];
+}
+interface VideoUnderstandOptions {
+    /** Absolute path to the input video. */
+    input: string;
+    /** Seconds between extracted frames (default 3). */
+    frameInterval?: number;
+    /** Maximum number of frames to extract (default 30). */
+    maxFrames?: number;
+    /** Path to a whisper.cpp model file (.bin) — enables transcription. */
+    whisperModel?: string;
+}
+interface VideoTimelineEntry {
+    timeSeconds: number;
+    timeDisplay: string;
+    framePath: string;
+    spokenText: string;
+}
+interface VideoUnderstandResult {
+    ok: true;
+    video: string;
+    duration: number;
+    resolution: string;
+    totalFramesExtracted: number;
+    transcriptSegments: number;
+    timeline: VideoTimelineEntry[];
+    frameDir: string;
+    hint: string;
+}
+interface VoiceCloneOptions {
+    /** Text to speak in the cloned voice. */
+    text: string;
+    /** Absolute path to the reference audio sample (required). */
+    refAudio: string;
+    /** Transcript of the reference audio (required). */
+    refText: string;
+    /** Optional path to the Python interpreter with F5-TTS installed. */
+    pythonBin?: string;
+    /** Compute device passed to F5-TTS (default 'cpu'). */
+    device?: string;
+}
+
+interface MediaManagerOptions {
+    /**
+     * Directory media output files are written to. Created on first use.
+     * Defaults to `<dataDir>/media` when a dataDir is given, otherwise to
+     * `<os-tmp>/agenticmail-media`.
+     */
+    outputDir?: string;
+    /** AgenticMail data directory — used to derive a default outputDir. */
+    dataDir?: string;
+}
+declare class MediaManager {
+    private readonly outputDir;
+    constructor(options?: MediaManagerOptions);
+    /** Ensure the output directory exists; returns it. */
+    private ensureOutputDir;
+    /** Build an output path inside the managed output dir. */
+    private outPath;
+    /** Build a sub-directory inside the managed output dir. */
+    private outDir;
+    /** Stat a produced file into a {@link MediaFileResult} envelope. */
+    private fileResult;
+    /** Run ffmpeg with an argument array. */
+    private ffmpeg;
+    /** Run ImageMagick with an argument array (handles magick/convert). */
+    private magick;
+    /** Run an `identify`-style probe via the ImageMagick binary. */
+    private magickIdentify;
+    /** Probe a media file with ffprobe, returning parsed JSON. */
+    private ffprobe;
+    /** Return the media binary capability report (graceful-degradation surface). */
+    capabilities(opts?: {
+        force?: boolean;
+    }): MediaCapabilityReport;
+    /** List the built-in Edge TTS voice presets. */
+    listVoices(): {
+        presets: Array<{
+            name: string;
+            full: string;
+        }>;
+        default: string;
+    };
+    /**
+     * Synthesise speech with Edge TTS. node-edge-tts is an optional peer
+     * dependency — when it is absent this throws a clear, actionable
+     * error instead of crashing. The MP3 is transcoded to OGG/Opus when
+     * ffmpeg is available (so it can be sent as a voice note); otherwise
+     * the raw MP3 is returned.
+     */
+    ttsGenerate(opts: TtsGenerateOptions): Promise<MediaFileResult>;
+    /** Edit an image with ImageMagick. */
+    imageEdit(opts: ImageEditOptions): Promise<MediaFileResult>;
+    /** Edit audio with ffmpeg. */
+    audioEdit(opts: AudioEditOptions): Promise<MediaFileResult>;
+    /** Probe a media file's metadata with ffprobe. */
+    mediaInfo(input: string): Promise<MediaInfoResult>;
+    /** Edit a video with ffmpeg (+ ImageMagick for caption rendering). */
+    videoEdit(opts: VideoEditOptions): Promise<MediaFileResult>;
+    private videoColorGrade;
+    private videoTransition;
+    private videoTextOverlay;
+    private videoPictureInPicture;
+    private videoSplitScreen;
+    private videoKenBurns;
+    private videoSlowMotion;
+    private videoWatermark;
+    private videoConcatenate;
+    private videoAudioMix;
+    /**
+     * Burn dynamic word-chunked captions onto a video. Needs ffmpeg,
+     * ImageMagick, and whisper.cpp (with a model file). Mirrors the
+     * source MCP's CapCut-style caption renderer.
+     */
+    private videoAutoCaption;
+    /**
+     * Analyse a video — extract frames at intervals and (when a whisper
+     * model is given) transcribe the audio — and return a merged
+     * timeline of what is shown and said.
+     */
+    videoUnderstand(opts: VideoUnderstandOptions): Promise<VideoUnderstandResult>;
+    /**
+     * Synthesise speech in a reference voice with F5-TTS. Needs a Python
+     * interpreter that has the `f5-tts` and `soundfile` packages. The
+     * reference audio + transcript MUST be supplied by the caller — no
+     * built-in voice profile. The Python is run via execFile with an
+     * argument array; the script and its inputs are written to a temp
+     * file and passed by path, so no caller value is interpolated into a
+     * command line.
+     */
+    voiceClone(opts: VoiceCloneOptions): Promise<MediaFileResult>;
+    /** Parse a whisper-produced SRT (located by stem) into timed segments. */
+    private parseSrt;
+    /** Unlink a file, swallowing any error (cleanup best-effort). */
+    private tryUnlink;
+    /** Remove the SRT(s) produced for a given stem. */
+    private tryUnlinkSrt;
+    /** Recursively remove a directory, swallowing errors. */
+    private tryRmDir;
+}
+
+/**
+ * Detect whether a single binary is available. Result is cached; pass
+ * `{ force: true }` to re-probe (e.g. after the operator installs it).
+ */
+declare function detectBinary(binary: MediaBinary, opts?: {
+    force?: boolean;
+}): MediaCapability;
+/**
+ * Resolve the command name to invoke for a binary. Throws a clear,
+ * actionable error if the binary is not available — callers use this
+ * at the top of every media operation so a missing dependency fails
+ * fast with an install hint instead of an opaque ENOENT deep inside
+ * an execFile call.
+ */
+declare function requireBinary(binary: MediaBinary): string;
+/**
+ * Validate that a whisper.cpp model file exists on disk. whisper.cpp
+ * needs an explicit model path; this surfaces a clear error rather
+ * than letting the CLI fail cryptically.
+ */
+declare function requireWhisperModel(modelPath: string | undefined): string;
+/**
+ * Build the full media capability report — one entry per binary, plus
+ * a `ready` flag (true once ffmpeg + ffprobe, the baseline, are both
+ * present). Used by the health surface and the `media_capabilities`
+ * tool so an agent can see what is available before attempting an op.
+ */
+declare function getMediaCapabilities(opts?: {
+    force?: boolean;
+}): MediaCapabilityReport;
+/** Clear the detection cache — used by tests and after a re-install. */
+declare function clearMediaCapabilityCache(): void;
+
 /**
  * Stable thread-id derivation.
  *
@@ -3231,4 +5226,4 @@ declare class MemorySearchIndex {
     has(id: string): boolean;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_SESSION_MAX_AGE_MS, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type HostName, type HostSession, type HostSessionResumeMode, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, MemorySearchIndex, type MemorySource, type MemoryStats, type OpenClawPhoneMissionPolicy, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedSms, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEPHONY_TRANSPORT_CAPABILITIES, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildPhoneTransportConfig, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, inferPhoneRegion, isInternalEmail, isLoopbackMailHost, isPhoneRegionAllowed, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, stem, threadIdFor, tokenize, tryJoin, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile };
+export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SEARCH_EMAIL_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, requireBinary, requireWhisperModel, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateTwilioSignature, webSearch };