@agenticmail/core 0.9.20 → 0.9.22

package/dist/index.d.ts

@@ -1274,822 +1274,886 @@ declare class TunnelManager {
     }>;
 }
 
-interface LocalSmtpConfig {
-    host: string;
-    port: number;
-    user: string;
-    pass: string;
-}
-interface GatewayManagerOptions {
-    db: Database;
-    stalwart: StalwartAdmin;
-    accountManager?: AccountManager;
-    localSmtp?: LocalSmtpConfig;
-    onInboundMail?: (agentName: string, mail: InboundEmail) => void | Promise<void>;
-    /** Master key used to encrypt credentials at rest in SQLite. */
-    encryptionKey?: string;
+/**
+ * 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);
 }
 /**
- * GatewayManager orchestrates relay and domain modes for sending/receiving
- * real internet email. It coordinates between the relay gateway, Cloudflare
- * services (DNS, tunnels, registrar), and the local Stalwart instance.
+ * 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 class GatewayManager {
-    private options;
-    private db;
-    private stalwart;
-    private accountManager;
-    private relay;
-    private config;
-    private cfClient;
-    private tunnel;
-    private dnsConfigurator;
-    private domainPurchaser;
-    private smsManager;
-    private smsPollers;
-    private encryptionKey;
-    constructor(options: GatewayManagerOptions);
-    /**
-     * Check if a message has already been delivered to an agent (deduplication).
-     */
-    isAlreadyDelivered(messageId: string, agentName: string): boolean;
-    /**
-     * Record that a message was delivered to an agent.
-     */
-    recordDelivery(messageId: string, agentName: string): void;
-    /**
-     * Built-in inbound mail handler: delivers relay inbound mail to agent's local Stalwart mailbox.
-     * Authenticates as the agent to send to their own mailbox (Stalwart requires sender = auth user).
-     *
-     * Also intercepts owner replies to approval notification emails — if the reply says
-     * "approve" or "reject", the pending outbound email is automatically processed.
-     */
-    private deliverInboundLocally;
-    /**
-     * Check if an inbound email is a reply to a pending approval notification.
-     * If the reply body starts with "approve"/"yes" or "reject"/"no", automatically
-     * process the pending email (send it or discard it) and confirm to the owner.
-     */
-    private tryProcessApprovalReply;
-    /**
-     * Execute approval of a pending outbound email: look up the agent, reconstitute
-     * attachments, and send the email via gateway routing or local SMTP.
-     */
-    private executeApproval;
-    /**
-     * Send a confirmation email back to the owner after processing an approval reply.
-     */
-    private sendApprovalConfirmation;
-    setupRelay(config: RelayConfig, options?: {
-        defaultAgentName?: string;
-        defaultAgentRole?: AgentRole;
-        skipDefaultAgent?: boolean;
-    }): Promise<{
-        agent?: Agent;
-    }>;
-    setupDomain(options: {
-        cloudflareToken: string;
-        cloudflareAccountId: string;
-        domain?: string;
-        purchase?: {
-            keywords: string[];
-            tld?: string;
-        };
-        outboundWorkerUrl?: string;
-        outboundSecret?: string;
-        gmailRelay?: {
-            email: string;
-            appPassword: string;
-        };
-    }): Promise<{
-        domain: string;
-        dnsConfigured: boolean;
-        tunnelId: string;
-        outboundRelay?: {
-            configured: boolean;
-            provider: string;
-        };
-        nextSteps?: string[];
-    }>;
-    /**
-     * Send a test email through the gateway without requiring a real agent.
-     * In relay mode, uses "test" as the sub-address.
-     * In domain mode, uses the first available agent (Stalwart needs real credentials).
-     */
-    sendTestEmail(to: string): Promise<SendResultWithRaw | null>;
-    /**
-     * Route an outbound email. If the destination is external and a gateway
-     * is configured, send via the appropriate channel.
-     * Returns null if the mail should be sent via local Stalwart.
-     */
-    routeOutbound(agentName: string, mail: SendMailOptions): Promise<SendResultWithRaw | null>;
-    /**
-     * Send email by submitting to local Stalwart via SMTP (port 587).
-     * Stalwart handles DKIM signing and delivery (direct or via relay).
-     * Reply-To is set to the agent's domain email so replies come back
-     * to the domain (handled by Cloudflare Email Routing → inbound Worker).
-     */
-    private sendViaStalwart;
-    getStatus(): GatewayStatus;
-    getMode(): GatewayMode;
-    getConfig(): GatewayConfig;
-    getStalwart(): StalwartAdmin;
-    getDomainPurchaser(): DomainPurchaser | null;
-    getDNSConfigurator(): DNSConfigurator | null;
-    getTunnelManager(): TunnelManager | null;
-    getRelay(): RelayGateway;
-    /**
-     * Search the connected relay account (Gmail/Outlook) for emails matching criteria.
-     * Returns empty array if relay is not configured.
-     */
-    searchRelay(criteria: {
-        from?: string;
-        to?: string;
-        subject?: string;
-        text?: string;
-        since?: Date;
-        before?: Date;
-        seen?: boolean;
-    }, maxResults?: number): Promise<RelaySearchResult[]>;
+declare function redactBotToken(text: string, token?: string): string;
+interface TelegramApiOptions {
     /**
-     * Import an email from the connected relay account into an agent's local inbox.
-     * Fetches the full message from relay IMAP and delivers it locally, preserving
-     * all headers (Message-ID, In-Reply-To, References) for thread continuity.
+     * 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.
      */
-    importRelayMessage(relayUid: number, agentName: string): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    longPoll?: boolean;
     /**
-     * Start SMS pollers for all agents that have separate GV Gmail credentials.
-     * Agents with sameAsRelay=true are handled in deliverInboundLocally.
+     * External abort — lets a long-running poll loop cancel the in-flight
+     * request when the caller wants to shut down without waiting for the
+     * Telegram timeout. Composed with the internal request-timeout signal
+     * via {@link AbortSignal.any}.
      */
-    private startSmsPollers;
-    shutdown(): Promise<void>;
+    signal?: AbortSignal;
+}
+/**
+ * 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;
+    /** Cancel the in-flight long-poll (used by `TelegramPoller.stop()`). */
+    signal?: AbortSignal;
+}
+/** `getUpdates` long-poll — the poll-mode transport. */
+declare function getTelegramUpdates(token: string, offset: number, options?: GetUpdatesOptions): Promise<Array<Record<string, unknown>>>;
+interface SetWebhookOptions {
     /**
-     * Resume gateway from saved config (e.g., after server restart).
-     *
-     * Issue #31 — On a Docker container restart the API can come up
-     * before Stalwart / Gmail IMAP / DNS is reachable, so the very first
-     * setup() can fail with a transient network error. Previously that
-     * single failure was logged and never retried, leaving polling
-     * permanently dead until someone noticed and manually revived the
-     * relay. We now schedule background retries with exponential backoff
-     * (5s, 10s, 20s, 40s, 60s cap, indefinite) so the relay
-     * self-recovers as soon as the dependency is reachable again.
+     * Shared secret echoed by Telegram in the
+     * `X-Telegram-Bot-Api-Secret-Token` header on every webhook delivery.
      */
-    resume(): Promise<void>;
-    private _resumeRetryTimer;
-    private _resumeRetryAttempt;
-    private _resumeRelayOnce;
-    private _scheduleRelayResumeRetry;
-    private loadConfig;
-    private saveConfig;
-    private saveLastSeenUid;
-    private loadLastSeenUid;
+    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>>;
 
-interface RelayBridgeOptions {
-    /** Port for the HTTP bridge server */
-    port: number;
-    /** Shared secret for authenticating requests */
-    secret: string;
-    /** Local Stalwart SMTP host (default: 127.0.0.1) */
-    smtpHost?: string;
-    /** Local Stalwart SMTP submission port (default: 587) */
-    smtpPort?: number;
-    /** Stalwart auth credentials for the sending agent */
-    smtpUser: string;
-    smtpPass: string;
-}
 /**
- * RelayBridge — A local HTTP-to-SMTP bridge that submits email to Stalwart.
- *
- * Stalwart then handles DKIM signing, MX resolution, and direct delivery
- * to the recipient's mail server on port 25. FROM is preserved exactly.
- *
- * This bridge is exposed via Cloudflare Tunnel so Cloudflare Workers
- * (which can't connect to port 25) can trigger outbound email through it.
+ * Telegram update parsing — pure, dependency-free.
  *
- * For production, deploy on a VPS with proper PTR/FCrDNS for reliable
- * delivery to all providers (Gmail, Outlook, etc.).
+ * 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).
  */
-declare class RelayBridge {
-    private server;
-    private options;
-    constructor(options: RelayBridgeOptions);
-    start(): Promise<void>;
-    stop(): void;
-    private handleRequest;
-    private submitToStalwart;
+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;
 }
-declare function startRelayBridge(options: RelayBridgeOptions): RelayBridge;
+/**
+ * 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;
 
 /**
- * SMS Manager - provider-backed SMS integration
+ * Telegram Manager — per-agent Telegram bot configuration + message log.
  *
- * How it works:
- * 1. User chooses a provider for the agent phone number
- * 2. Google Voice uses email forwarding/web instructions
- * 3. 46elks uses direct API sends and inbound webhooks
- * 4. All inbound/outbound messages are stored in the SMS table
+ * 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.
  *
- * SMS config is stored in agent metadata under the "sms" key.
- */
-
-interface SmsConfig {
-    /** Whether SMS is enabled for this agent */
-    enabled: boolean;
-    /** Phone number in E.164 format where possible */
-    phoneNumber: string;
-    /** The email address Google Voice forwards SMS to (the Gmail used for GV signup) */
-    forwardingEmail?: string;
-    /** App password for forwarding email (only needed if different from relay email) */
-    forwardingPassword?: string;
-    /** Whether the GV Gmail is the same as the relay email */
-    sameAsRelay?: boolean;
-    /** SMS provider */
-    provider: 'google_voice' | '46elks';
-    /** 46elks API username */
-    username?: string;
-    /** 46elks API password */
-    password?: string;
-    /** Provider API base URL override */
-    apiUrl?: string;
-    /** Secret required on inbound provider webhooks */
+ * 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;
-    /** When SMS was configured */
+    /** Persisted `getUpdates` offset (poll mode). */
+    pollOffset?: number;
+    /** When the channel was configured. */
     configuredAt: string;
 }
-interface ParsedSms {
-    from: string;
-    body: string;
-    timestamp: string;
-    raw?: string;
-}
-interface SmsMessage {
+interface TelegramMessage {
     id: string;
     agentId: string;
     direction: 'inbound' | 'outbound';
-    phoneNumber: string;
-    body: string;
-    status: 'pending' | 'sent' | 'delivered' | 'failed' | 'received';
+    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>;
 }
-interface SendSmsInput {
-    to: string;
-    body: string;
-    dryRun?: boolean;
-}
-interface SendSmsResult {
-    provider: SmsConfig['provider'];
-    id?: string;
-    status: string;
-    from: string;
-    to: string;
-    body: string;
-    raw?: unknown;
-}
-interface InboundSmsEvent {
-    provider: SmsConfig['provider'];
-    id?: string;
-    from: string;
-    to: string;
-    body: string;
-    timestamp: string;
-    raw?: unknown;
-}
-interface SmsProvider {
-    id: SmsConfig['provider'];
-    sendSms(config: SmsConfig, input: SendSmsInput): Promise<SendSmsResult>;
-    parseInboundSms(payload: Record<string, unknown>): InboundSmsEvent | null;
-}
-declare function redactSmsConfig(config: SmsConfig): SmsConfig;
-declare function getSmsProvider(provider: SmsConfig['provider']): SmsProvider;
-declare function mapProviderSmsStatus(status: string): SmsMessage['status'];
-/** Normalize a phone number to E.164-ish format (+1XXXXXXXXXX) */
-declare function normalizePhoneNumber(raw: string): string | null;
-/** Validate a phone number (basic) */
-declare function isValidPhoneNumber(phone: string): boolean;
+/** 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;
 /**
- * Parse an SMS forwarded from Google Voice via email.
- * Google Voice forwards SMS with a specific format.
- *
- * Known sender addresses:
- * - voice-noreply@google.com
- * - *@txt.voice.google.com
- * - Google Voice <voice-noreply@google.com>
+ * 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 parseGoogleVoiceSms(emailBody: string, emailFrom: string): ParsedSms | null;
+declare function redactTelegramConfig(config: TelegramConfig): TelegramConfig;
 /**
- * Extract verification codes from SMS body.
- * Supports common formats: 6-digit, 4-digit, alphanumeric codes.
+ * 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 extractVerificationCode(smsBody: string): string | null;
-declare class SmsManager {
+declare function isTelegramChatAllowed(config: TelegramConfig, chatId: string): boolean;
+declare class TelegramManager {
     private db;
     private encryptionKey?;
     private initialized;
     /**
-     * Optional master key used to encrypt SMS credentials at rest (same
-     * AES-256-GCM scheme GatewayManager uses for relay/domain secrets).
-     * When absent (e.g. tests, or a deployment with no master key) configs
-     * are stored as-is and reads tolerate plaintext — so upgrades and
-     * downgrades both stay safe.
+     * 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);
-    /** Encrypt the credential fields of an SMS config before persisting. */
+    private ensureTable;
+    /** Encrypt the credential fields of a config before persisting. */
     private encryptConfig;
-    /** Decrypt the credential fields of an SMS config after loading. */
+    /** Decrypt the credential fields of a config after loading. */
     private decryptConfig;
-    private ensureTable;
-    /** Get SMS config from agent metadata (credential fields decrypted). */
-    getSmsConfig(agentId: string): SmsConfig | null;
-    /** Save SMS config to agent metadata (credential fields encrypted). */
-    saveSmsConfig(agentId: string, config: SmsConfig): void;
+    /** 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 operator's "where do I get pinged" address from an
-     * agent's SMS config. Used by the dispatcher's bridge-escalation
-     * path: when sub-agents mail a bridge with no fresh host session
-     * available, we email the operator a digest at this address. Their
-     * phone's Gmail push notification surfaces it within seconds —
-     * effectively a free, programmatic alert channel.
-     *
-     * Returns the configured `forwardingEmail` (the same Gmail Google
-     * Voice forwards inbound SMS to, which the operator already has
-     * push notifications enabled for) when SMS is configured AND
-     * enabled. Returns null otherwise — caller falls through to a
-     * silent log + system event.
-     *
-     * Why we don't try real-SMS delivery yet: Google Voice's
-     * `<number>@txt.voice.google.com` email-to-SMS gateway was
-     * deprecated by Google years ago. A future `carrier` field on
-     * SmsConfig (Verizon vtext.com / AT&T txt.att.net / etc) will let
-     * the operator opt into actual SMS, but that's a follow-up — the
-     * email path already gets the operator a phone notification.
+     * 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).
      */
-    getAlertEmail(agentId: string): string | null;
-    /** Remove SMS config from agent metadata */
-    removeSmsConfig(agentId: string): void;
-    /** Find the agent whose SMS config owns a phone number. */
-    findAgentBySmsNumber(phoneNumber: string, provider?: SmsConfig['provider']): {
+    findAgentByWebhookSecret(secret: string): {
         agentId: string;
-        config: SmsConfig;
+        config: TelegramConfig;
     } | null;
-    /** Record an inbound SMS (parsed from email or provider webhook) */
-    recordInbound(agentId: string, parsed: ParsedSms, metadata?: Record<string, unknown>): SmsMessage;
-    /** Record an outbound SMS attempt */
-    recordOutbound(agentId: string, phoneNumber: string, body: string, status?: 'pending' | 'sent' | 'failed', metadata?: Record<string, unknown>): SmsMessage;
-    /** Update SMS status and optional provider metadata */
-    updateStatus(id: string, status: SmsMessage['status'], metadata?: Record<string, unknown>): void;
-    /** List SMS messages for an agent */
+    /** 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;
-    }): SmsMessage[];
-    /** Check for recent verification codes in inbound SMS */
-    checkForVerificationCode(agentId: string, minutesBack?: number): {
-        code: string;
-        from: string;
-        body: string;
-        receivedAt: string;
-    } | null;
-}
-/**
- * SmsPoller — Polls for Google Voice SMS forwarded emails.
- *
- * Two modes:
- * 1. **Same email** (sameAsRelay=true): Hooks into the relay's onInboundMail callback.
- *    The relay poll already fetches emails; SmsPoller filters for GV forwarded SMS.
- * 2. **Separate email** (sameAsRelay=false): Runs its own IMAP poll against the GV Gmail
- *    using the separate credentials (forwardingEmail + forwardingPassword).
- *
- * Parsed SMS messages are stored in the sms_messages table.
- */
-declare class SmsPoller {
-    private smsManager;
-    private agentId;
-    private config;
-    private pollTimer;
-    private polling;
-    private lastSeenUid;
-    private firstPollDone;
-    private consecutiveFailures;
-    private readonly POLL_INTERVAL_MS;
-    private readonly MAX_BACKOFF_MS;
-    private readonly CONNECT_TIMEOUT_MS;
-    /** Callback for new inbound SMS */
-    onSmsReceived: ((agentId: string, sms: ParsedSms) => void | Promise<void>) | null;
-    constructor(smsManager: SmsManager, agentId: string, config: SmsConfig);
-    /** Whether this poller needs its own IMAP connection (separate Gmail) */
-    get needsSeparatePoll(): boolean;
-    /**
-     * Process an email from the relay poll (same-email mode).
-     * Called by the relay gateway's onInboundMail when it detects a GV email.
-     * Returns true if the email was an SMS and was processed.
-     */
-    processRelayEmail(from: string, subject: string, body: string): boolean;
-    /**
-     * Start polling the separate GV Gmail for SMS (separate-email mode).
-     * Only call this if needsSeparatePoll is true.
-     */
-    startPolling(): Promise<void>;
-    stopPolling(): void;
-    private scheduleNext;
-    private pollOnce;
+    }): TelegramMessage[];
 }
 
 /**
- * Telegram Bot API client — dependency-free (global `fetch`, Node 22+).
+ * Telegram ⇄ `ask_operator` bridge (plan §13.4 / §13.5) — pure helpers.
  *
- * 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)
+ * 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:
  *
- * 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.
+ *   1. {@link formatOperatorQueryTelegramMessage} — renders the
+ *      notification text the operator receives.
+ *   2. {@link parseTelegramOperatorReply} — parses the operator's
+ *      Telegram reply back into a `{ queryId, answer }`.
  *
- * 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.
+ * The caller feeds the parsed result straight into the SAME
+ * `PhoneManager.answerOperatorQuery` the inbound email-reply hook uses.
  */
-/** 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);
+/**
+ * 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;
 }
 /**
- * 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.
+ * 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 redactBotToken(text: string, token?: string): string;
-interface TelegramApiOptions {
+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 {
     /**
-     * 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.
+     * 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.
      */
-    longPoll?: boolean;
+    queryId?: string;
+    /** The answer text to record against the query. Always non-empty. */
+    answer: string;
+    kind: OperatorReplyKind;
 }
 /**
- * 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.
+ * 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 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;
+declare function parseTelegramOperatorReply(input: {
+    text: string;
+    replyToText?: string;
+}): ParsedOperatorReply | null;
+
+interface LocalSmtpConfig {
+    host: string;
+    port: number;
+    user: string;
+    pass: string;
 }
-interface SendTelegramMessageResult {
-    /** message_id of each chunk Telegram accepted, in order. */
-    messageIds: number[];
-    /** Number of chunks the text was split into. */
-    chunks: number;
+interface GatewayManagerOptions {
+    db: Database;
+    stalwart: StalwartAdmin;
+    accountManager?: AccountManager;
+    localSmtp?: LocalSmtpConfig;
+    onInboundMail?: (agentName: string, mail: InboundEmail) => void | Promise<void>;
+    /** Master key used to encrypt credentials at rest in SQLite. */
+    encryptionKey?: string;
 }
 /**
- * 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.
+ * GatewayManager orchestrates relay and domain modes for sending/receiving
+ * real internet email. It coordinates between the relay gateway, Cloudflare
+ * services (DNS, tunnels, registrar), and the local Stalwart instance.
  */
-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 {
+declare class GatewayManager {
+    private options;
+    private db;
+    private stalwart;
+    private accountManager;
+    private relay;
+    private config;
+    private cfClient;
+    private tunnel;
+    private dnsConfigurator;
+    private domainPurchaser;
+    private smsManager;
+    private smsPollers;
+    private telegramManager;
+    private telegramPollers;
+    private encryptionKey;
+    constructor(options: GatewayManagerOptions);
+    /**
+     * Check if a message has already been delivered to an agent (deduplication).
+     */
+    isAlreadyDelivered(messageId: string, agentName: string): boolean;
+    /**
+     * Record that a message was delivered to an agent.
+     */
+    recordDelivery(messageId: string, agentName: string): void;
+    /**
+     * Built-in inbound mail handler: delivers relay inbound mail to agent's local Stalwart mailbox.
+     * Authenticates as the agent to send to their own mailbox (Stalwart requires sender = auth user).
+     *
+     * Also intercepts owner replies to approval notification emails — if the reply says
+     * "approve" or "reject", the pending outbound email is automatically processed.
+     */
+    private deliverInboundLocally;
+    /**
+     * Check if an inbound email is a reply to a pending approval notification.
+     * If the reply body starts with "approve"/"yes" or "reject"/"no", automatically
+     * process the pending email (send it or discard it) and confirm to the owner.
+     */
+    private tryProcessApprovalReply;
+    /**
+     * Execute approval of a pending outbound email: look up the agent, reconstitute
+     * attachments, and send the email via gateway routing or local SMTP.
+     */
+    private executeApproval;
+    /**
+     * Send a confirmation email back to the owner after processing an approval reply.
+     */
+    private sendApprovalConfirmation;
+    setupRelay(config: RelayConfig, options?: {
+        defaultAgentName?: string;
+        defaultAgentRole?: AgentRole;
+        skipDefaultAgent?: boolean;
+    }): Promise<{
+        agent?: Agent;
+    }>;
+    setupDomain(options: {
+        cloudflareToken: string;
+        cloudflareAccountId: string;
+        domain?: string;
+        purchase?: {
+            keywords: string[];
+            tld?: string;
+        };
+        outboundWorkerUrl?: string;
+        outboundSecret?: string;
+        gmailRelay?: {
+            email: string;
+            appPassword: string;
+        };
+    }): Promise<{
+        domain: string;
+        dnsConfigured: boolean;
+        tunnelId: string;
+        outboundRelay?: {
+            configured: boolean;
+            provider: string;
+        };
+        nextSteps?: string[];
+    }>;
+    /**
+     * Send a test email through the gateway without requiring a real agent.
+     * In relay mode, uses "test" as the sub-address.
+     * In domain mode, uses the first available agent (Stalwart needs real credentials).
+     */
+    sendTestEmail(to: string): Promise<SendResultWithRaw | null>;
+    /**
+     * Route an outbound email. If the destination is external and a gateway
+     * is configured, send via the appropriate channel.
+     * Returns null if the mail should be sent via local Stalwart.
+     */
+    routeOutbound(agentName: string, mail: SendMailOptions): Promise<SendResultWithRaw | null>;
+    /**
+     * Send email by submitting to local Stalwart via SMTP (port 587).
+     * Stalwart handles DKIM signing and delivery (direct or via relay).
+     * Reply-To is set to the agent's domain email so replies come back
+     * to the domain (handled by Cloudflare Email Routing → inbound Worker).
+     */
+    private sendViaStalwart;
+    getStatus(): GatewayStatus;
+    getMode(): GatewayMode;
+    getConfig(): GatewayConfig;
+    getStalwart(): StalwartAdmin;
+    getDomainPurchaser(): DomainPurchaser | null;
+    getDNSConfigurator(): DNSConfigurator | null;
+    getTunnelManager(): TunnelManager | null;
+    getRelay(): RelayGateway;
     /**
-     * Shared secret echoed by Telegram in the
-     * `X-Telegram-Bot-Api-Secret-Token` header on every webhook delivery.
+     * Search the connected relay account (Gmail/Outlook) for emails matching criteria.
+     * Returns empty array if relay is not configured.
      */
-    secretToken?: string;
-    /** Drop updates that queued up while no webhook was set. */
-    dropPendingUpdates?: boolean;
+    searchRelay(criteria: {
+        from?: string;
+        to?: string;
+        subject?: string;
+        text?: string;
+        since?: Date;
+        before?: Date;
+        seen?: boolean;
+    }, maxResults?: number): Promise<RelaySearchResult[]>;
+    /**
+     * Import an email from the connected relay account into an agent's local inbox.
+     * Fetches the full message from relay IMAP and delivers it locally, preserving
+     * all headers (Message-ID, In-Reply-To, References) for thread continuity.
+     */
+    importRelayMessage(relayUid: number, agentName: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Start SMS pollers for all agents that have separate GV Gmail credentials.
+     * Agents with sameAsRelay=true are handled in deliverInboundLocally.
+     */
+    private startSmsPollers;
+    /**
+     * Start a long-poll loop for every agent whose Telegram channel is
+     * configured + enabled + in poll mode. Webhook-mode agents skip — the
+     * webhook route already calls back into the same agent-wake bridge.
+     *
+     * Each new inbound Telegram message (that isn't an operator-query
+     * reply) is converted to a synthetic email and delivered into the
+     * agent's INBOX via the existing local-SMTP path — the very same
+     * delivery the relay uses for real email. This makes the existing
+     * IMAP IDLE → claudecode dispatcher path light up exactly as it
+     * would for a real inbound mail, so the agent gets a Claude turn
+     * without any new dispatcher plumbing. The body of the synthetic
+     * mail tells the agent the message came from Telegram and that it
+     * MUST reply via the `telegram_send` MCP tool, not via email.
+     */
+    private startTelegramPollers;
+    /**
+     * Start (or restart) the Telegram poller for one agent. Idempotent —
+     * a prior poller is stopped first so re-running `/telegram/setup`
+     * picks up the new token / allow-list cleanly.
+     *
+     * Public so the API layer can poke the gateway after a successful
+     * `/telegram/setup` without waiting for the next server restart.
+     */
+    startTelegramPollerForAgent(agentId: string, agentName?: string): Promise<void>;
+    /** Stop a single agent's Telegram poller (called on disable). */
+    stopTelegramPollerForAgent(agentId: string): Promise<void>;
+    /**
+     * Convert one new inbound Telegram message into a synthetic email
+     * landing in the agent's INBOX, so the dispatcher wakes the agent.
+     *
+     * Two short-circuits before delivery:
+     *
+     *   1. If the message is from the configured operator's chat AND
+     *      looks like an operator-query reply (parsed by
+     *      `parseTelegramOperatorReply`), it's an answer to an in-flight
+     *      voice mission, not free-form chat — the HTTP webhook/poll
+     *      route already handles those by calling into the phone
+     *      manager, and the route does NOT need an agent turn. The poller
+     *      hands them off the same way: we just skip the wake here.
+     *
+     *   2. Plain `/start` (BotFather's default first DM) is a Telegram
+     *      housekeeping nudge — replying with an LLM turn for "/start"
+     *      would be embarrassing. Skip it.
+     *
+     * Everything else: synthesise the email and deliver.
+     */
+    /**
+     * Public wrapper around the bridge — the Telegram webhook route calls
+     * this directly so push-mode and poll-mode share the wake path.
+     */
+    bridgeTelegramInbound(agentId: string, parsed: ParsedTelegramMessage, config: TelegramConfig): Promise<void>;
+    private bridgeInboundTelegram;
+    shutdown(): Promise<void>;
+    /**
+     * Resume gateway from saved config (e.g., after server restart).
+     *
+     * Issue #31 — On a Docker container restart the API can come up
+     * before Stalwart / Gmail IMAP / DNS is reachable, so the very first
+     * setup() can fail with a transient network error. Previously that
+     * single failure was logged and never retried, leaving polling
+     * permanently dead until someone noticed and manually revived the
+     * relay. We now schedule background retries with exponential backoff
+     * (5s, 10s, 20s, 40s, 60s cap, indefinite) so the relay
+     * self-recovers as soon as the dependency is reachable again.
+     */
+    resume(): Promise<void>;
+    private _resumeRetryTimer;
+    private _resumeRetryAttempt;
+    private _resumeRelayOnce;
+    private _scheduleRelayResumeRetry;
+    private loadConfig;
+    private saveConfig;
+    private saveLastSeenUid;
+    private loadLastSeenUid;
 }
-/** `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>>;
 
+interface RelayBridgeOptions {
+    /** Port for the HTTP bridge server */
+    port: number;
+    /** Shared secret for authenticating requests */
+    secret: string;
+    /** Local Stalwart SMTP host (default: 127.0.0.1) */
+    smtpHost?: string;
+    /** Local Stalwart SMTP submission port (default: 587) */
+    smtpPort?: number;
+    /** Stalwart auth credentials for the sending agent */
+    smtpUser: string;
+    smtpPass: string;
+}
 /**
- * Telegram update parsing — pure, dependency-free.
+ * RelayBridge — A local HTTP-to-SMTP bridge that submits email to Stalwart.
  *
- * 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).
+ * Stalwart then handles DKIM signing, MX resolution, and direct delivery
+ * to the recipient's mail server on port 25. FROM is preserved exactly.
+ *
+ * This bridge is exposed via Cloudflare Tunnel so Cloudflare Workers
+ * (which can't connect to port 25) can trigger outbound email through it.
+ *
+ * For production, deploy on a VPS with proper PTR/FCrDNS for reliable
+ * delivery to all providers (Gmail, Outlook, etc.).
  */
-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;
+declare class RelayBridge {
+    private server;
+    private options;
+    constructor(options: RelayBridgeOptions);
+    start(): Promise<void>;
+    stop(): void;
+    private handleRequest;
+    private submitToStalwart;
 }
-/**
- * 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;
+declare function startRelayBridge(options: RelayBridgeOptions): RelayBridge;
 
 /**
- * Telegram Manager — per-agent Telegram bot configuration + message log.
+ * SMS Manager - provider-backed SMS integration
  *
- * 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.
+ * How it works:
+ * 1. User chooses a provider for the agent phone number
+ * 2. Google Voice uses email forwarding/web instructions
+ * 3. 46elks uses direct API sends and inbound webhooks
+ * 4. All inbound/outbound messages are stored in the SMS 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.
+ * SMS config is stored in agent metadata under the "sms" key.
  */
 
-/** Transport mode: long-poll `getUpdates`, or a registered webhook. */
-type TelegramMode = 'poll' | 'webhook';
-interface TelegramConfig {
-    /** Whether the Telegram channel is active for this agent. */
+interface SmsConfig {
+    /** Whether SMS is enabled 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.
-     */
+    /** Phone number in E.164 format where possible */
+    phoneNumber: string;
+    /** The email address Google Voice forwards SMS to (the Gmail used for GV signup) */
+    forwardingEmail?: string;
+    /** App password for forwarding email (only needed if different from relay email) */
+    forwardingPassword?: string;
+    /** Whether the GV Gmail is the same as the relay email */
+    sameAsRelay?: boolean;
+    /** SMS provider */
+    provider: 'google_voice' | '46elks';
+    /** 46elks API username */
+    username?: string;
+    /** 46elks API password */
+    password?: string;
+    /** Provider API base URL override */
+    apiUrl?: string;
+    /** Secret required on inbound provider webhooks */
     webhookSecret?: string;
-    /** Persisted `getUpdates` offset (poll mode). */
-    pollOffset?: number;
-    /** When the channel was configured. */
+    /** When SMS 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>;
+interface ParsedSms {
+    from: string;
+    body: string;
+    timestamp: string;
+    raw?: string;
+}
+interface SmsMessage {
+    id: string;
+    agentId: string;
+    direction: 'inbound' | 'outbound';
+    phoneNumber: string;
+    body: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed' | 'received';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+interface SendSmsInput {
+    to: string;
+    body: string;
+    dryRun?: boolean;
+}
+interface SendSmsResult {
+    provider: SmsConfig['provider'];
+    id?: string;
+    status: string;
+    from: string;
+    to: string;
+    body: string;
+    raw?: unknown;
+}
+interface InboundSmsEvent {
+    provider: SmsConfig['provider'];
+    id?: string;
+    from: string;
+    to: string;
+    body: string;
+    timestamp: string;
+    raw?: 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;
+interface SmsProvider {
+    id: SmsConfig['provider'];
+    sendSms(config: SmsConfig, input: SendSmsInput): Promise<SendSmsResult>;
+    parseInboundSms(payload: Record<string, unknown>): InboundSmsEvent | null;
+}
+declare function redactSmsConfig(config: SmsConfig): SmsConfig;
+declare function getSmsProvider(provider: SmsConfig['provider']): SmsProvider;
+declare function mapProviderSmsStatus(status: string): SmsMessage['status'];
+/** Normalize a phone number to E.164-ish format (+1XXXXXXXXXX) */
+declare function normalizePhoneNumber(raw: string): string | null;
+/** Validate a phone number (basic) */
+declare function isValidPhoneNumber(phone: string): boolean;
 /**
- * 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".
+ * Parse an SMS forwarded from Google Voice via email.
+ * Google Voice forwards SMS with a specific format.
+ *
+ * Known sender addresses:
+ * - voice-noreply@google.com
+ * - *@txt.voice.google.com
+ * - Google Voice <voice-noreply@google.com>
  */
-declare function redactTelegramConfig(config: TelegramConfig): TelegramConfig;
+declare function parseGoogleVoiceSms(emailBody: string, emailFrom: string): ParsedSms | null;
 /**
- * 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.
+ * Extract verification codes from SMS body.
+ * Supports common formats: 6-digit, 4-digit, alphanumeric codes.
  */
-declare function isTelegramChatAllowed(config: TelegramConfig, chatId: string): boolean;
-declare class TelegramManager {
+declare function extractVerificationCode(smsBody: string): string | null;
+declare class SmsManager {
     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.
+     * Optional master key used to encrypt SMS credentials at rest (same
+     * AES-256-GCM scheme GatewayManager uses for relay/domain secrets).
+     * When absent (e.g. tests, or a deployment with no master key) configs
+     * are stored as-is and reads tolerate plaintext — so upgrades and
+     * downgrades both stay safe.
      */
     constructor(db: Database, encryptionKey?: string | undefined);
-    private ensureTable;
-    /** Encrypt the credential fields of a config before persisting. */
+    /** Encrypt the credential fields of an SMS config before persisting. */
     private encryptConfig;
-    /** Decrypt the credential fields of a config after loading. */
+    /** Decrypt the credential fields of an SMS 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;
+    private ensureTable;
+    /** Get SMS config from agent metadata (credential fields decrypted). */
+    getSmsConfig(agentId: string): SmsConfig | null;
+    /** Save SMS config to agent metadata (credential fields encrypted). */
+    saveSmsConfig(agentId: string, config: SmsConfig): 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).
+     * Resolve the operator's "where do I get pinged" address from an
+     * agent's SMS config. Used by the dispatcher's bridge-escalation
+     * path: when sub-agents mail a bridge with no fresh host session
+     * available, we email the operator a digest at this address. Their
+     * phone's Gmail push notification surfaces it within seconds —
+     * effectively a free, programmatic alert channel.
+     *
+     * Returns the configured `forwardingEmail` (the same Gmail Google
+     * Voice forwards inbound SMS to, which the operator already has
+     * push notifications enabled for) when SMS is configured AND
+     * enabled. Returns null otherwise — caller falls through to a
+     * silent log + system event.
+     *
+     * Why we don't try real-SMS delivery yet: Google Voice's
+     * `<number>@txt.voice.google.com` email-to-SMS gateway was
+     * deprecated by Google years ago. A future `carrier` field on
+     * SmsConfig (Verizon vtext.com / AT&T txt.att.net / etc) will let
+     * the operator opt into actual SMS, but that's a follow-up — the
+     * email path already gets the operator a phone notification.
      */
-    findAgentByWebhookSecret(secret: string): {
+    getAlertEmail(agentId: string): string | null;
+    /** Remove SMS config from agent metadata */
+    removeSmsConfig(agentId: string): void;
+    /** Find the agent whose SMS config owns a phone number. */
+    findAgentBySmsNumber(phoneNumber: string, provider?: SmsConfig['provider']): {
         agentId: string;
-        config: TelegramConfig;
+        config: SmsConfig;
     } | 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. */
+    /** Record an inbound SMS (parsed from email or provider webhook) */
+    recordInbound(agentId: string, parsed: ParsedSms, metadata?: Record<string, unknown>): SmsMessage;
+    /** Record an outbound SMS attempt */
+    recordOutbound(agentId: string, phoneNumber: string, body: string, status?: 'pending' | 'sent' | 'failed', metadata?: Record<string, unknown>): SmsMessage;
+    /** Update SMS status and optional provider metadata */
+    updateStatus(id: string, status: SmsMessage['status'], metadata?: Record<string, unknown>): void;
+    /** List SMS messages for an agent */
     listMessages(agentId: string, opts?: {
         direction?: 'inbound' | 'outbound';
-        chatId?: string;
         limit?: number;
         offset?: number;
-    }): TelegramMessage[];
+    }): SmsMessage[];
+    /** Check for recent verification codes in inbound SMS */
+    checkForVerificationCode(agentId: string, minutesBack?: number): {
+        code: string;
+        from: string;
+        body: string;
+        receivedAt: string;
+    } | null;
 }
-
 /**
- * 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:
+ * SmsPoller — Polls for Google Voice SMS forwarded emails.
  *
- *   1. {@link formatOperatorQueryTelegramMessage} — renders the
- *      notification text the operator receives.
- *   2. {@link parseTelegramOperatorReply} — parses the operator's
- *      Telegram reply back into a `{ queryId, answer }`.
+ * Two modes:
+ * 1. **Same email** (sameAsRelay=true): Hooks into the relay's onInboundMail callback.
+ *    The relay poll already fetches emails; SmsPoller filters for GV forwarded SMS.
+ * 2. **Separate email** (sameAsRelay=false): Runs its own IMAP poll against the GV Gmail
+ *    using the separate credentials (forwardingEmail + forwardingPassword).
  *
- * 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.
+ * Parsed SMS messages are stored in the sms_messages table.
  */
-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 {
+declare class SmsPoller {
+    private smsManager;
+    private agentId;
+    private config;
+    private pollTimer;
+    private polling;
+    private lastSeenUid;
+    private firstPollDone;
+    private consecutiveFailures;
+    private readonly POLL_INTERVAL_MS;
+    private readonly MAX_BACKOFF_MS;
+    private readonly CONNECT_TIMEOUT_MS;
+    /** Callback for new inbound SMS */
+    onSmsReceived: ((agentId: string, sms: ParsedSms) => void | Promise<void>) | null;
+    constructor(smsManager: SmsManager, agentId: string, config: SmsConfig);
+    /** Whether this poller needs its own IMAP connection (separate Gmail) */
+    get needsSeparatePoll(): boolean;
     /**
-     * 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.
+     * Process an email from the relay poll (same-email mode).
+     * Called by the relay gateway's onInboundMail when it detects a GV email.
+     * Returns true if the email was an SMS and was processed.
      */
-    queryId?: string;
-    /** The answer text to record against the query. Always non-empty. */
-    answer: string;
-    kind: OperatorReplyKind;
+    processRelayEmail(from: string, subject: string, body: string): boolean;
+    /**
+     * Start polling the separate GV Gmail for SMS (separate-email mode).
+     * Only call this if needsSeparatePoll is true.
+     */
+    startPolling(): Promise<void>;
+    stopPolling(): void;
+    private scheduleNext;
+    private pollOnce;
 }
-/**
- * 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];
@@ -3728,14 +3792,14 @@ declare function debugWarn(tag: string, message: string): void;
  * # Examples
  *
  * ```ts
- * // Safe: resolves to /home/ope/.codex/agents/agenticmail-fola.toml
- * safeJoin('/home/ope/.codex/agents', 'agenticmail-fola.toml');
+ * // Safe: resolves to /home/alice/.codex/agents/agenticmail-cli.toml
+ * safeJoin('/home/alice/.codex/agents', 'agenticmail-cli.toml');
  *
  * // Throws: '../etc/passwd' resolves outside the base dir
- * safeJoin('/home/ope/.codex/agents', '../etc/passwd');
+ * safeJoin('/home/alice/.codex/agents', '../etc/passwd');
  *
  * // Throws: an absolute path bypasses the base dir
- * safeJoin('/home/ope/.codex/agents', '/etc/passwd');
+ * safeJoin('/home/alice/.codex/agents', '/etc/passwd');
  * ```
  */