@agenticmail/core 0.9.12 → 0.9.14

package/dist/index.d.cts

@@ -505,6 +505,22 @@ interface SendResultWithRaw extends SendResult {
     /** Raw RFC822 message bytes (for appending to Sent folder) */
     raw: Buffer;
 }
+/** True for loopback hosts — the bundled local mail server lives here. */
+declare function isLoopbackMailHost(host: string | undefined): boolean;
+/**
+ * Resolve the effective TLS `rejectUnauthorized` for a mail connection.
+ *
+ * GHSA-wjjv-3mj2-39hf made certificate verification the default — but
+ * the bundled local mail server (Stalwart on 127.0.0.1) presents a
+ * self-signed certificate, so verifying it always fails and breaks
+ * local agent-to-agent mail out of the box. A self-signed cert on a
+ * loopback address is not a meaningful MITM surface, so for loopback
+ * hosts verification defaults OFF. Remote hosts still verify by
+ * default. An explicit `tlsRejectUnauthorized` option always wins
+ * either way, so a deployment can still force-verify localhost or
+ * opt a remote host out if it really needs to.
+ */
+declare function resolveTlsRejectUnauthorized(host: string | undefined, explicit: boolean | undefined): boolean;
 declare class MailSender {
     private options;
     private transporter;
@@ -1676,6 +1692,293 @@ declare class SmsPoller {
     private pollOnce;
 }
 
+declare const ELKS_REALTIME_AUDIO_FORMATS: readonly ["ulaw", "pcm_16000", "pcm_24000", "wav"];
+type ElksRealtimeAudioFormat = typeof ELKS_REALTIME_AUDIO_FORMATS[number];
+interface ElksRealtimeHelloMessage {
+    t: 'hello';
+    callid: string;
+    from: string;
+    to: string;
+    [key: string]: unknown;
+}
+interface ElksRealtimeAudioMessage {
+    t: 'audio';
+    data: string;
+}
+interface ElksRealtimeByeMessage {
+    t: 'bye';
+    reason?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+type ElksRealtimeInboundMessage = ElksRealtimeHelloMessage | ElksRealtimeAudioMessage | ElksRealtimeByeMessage;
+type ElksRealtimeOutboundMessage = {
+    t: 'listening';
+    format: ElksRealtimeAudioFormat;
+} | {
+    t: 'sending';
+    format: ElksRealtimeAudioFormat;
+} | {
+    t: 'audio';
+    data: string;
+} | {
+    t: 'interrupt';
+} | {
+    t: 'bye';
+};
+declare function parseElksRealtimeMessage(input: unknown): ElksRealtimeInboundMessage;
+declare function buildElksListeningMessage(format?: ElksRealtimeAudioFormat): ElksRealtimeOutboundMessage;
+declare function buildElksSendingMessage(format?: ElksRealtimeAudioFormat): ElksRealtimeOutboundMessage;
+declare function buildElksAudioMessage(data: string | Uint8Array): ElksRealtimeOutboundMessage;
+declare function buildElksInterruptMessage(): ElksRealtimeOutboundMessage;
+declare function buildElksByeMessage(): ElksRealtimeOutboundMessage;
+declare function buildElksHandshakeMessages(options?: {
+    listenFormat?: ElksRealtimeAudioFormat;
+    sendFormat?: ElksRealtimeAudioFormat;
+}): ElksRealtimeOutboundMessage[];
+
+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"];
+type TelephonyTransportCapability = typeof TELEPHONY_TRANSPORT_CAPABILITIES[number];
+declare const PHONE_MISSION_STATES: readonly ["draft", "approved", "dialing", "connected", "conversing", "needs_operator", "completed", "failed", "cancelled"];
+type PhoneMissionState = typeof PHONE_MISSION_STATES[number];
+type PhoneNumberRisk = 'invalid' | 'standard' | 'premium_or_special';
+/**
+ * Server-side hard ceilings for a phone mission policy.
+ *
+ * Hardening (#42-H1 / #43-H2) — `policy` is supplied by the calling agent,
+ * so a caller-set `maxCallDurationSeconds: 999999` or `maxCostPerMission:
+ * 1e9` is self-authorized and meaningless as a limit. These constants are
+ * the real ceiling: `validatePhoneMissionPolicy` clamps every caller value
+ * down to (at most) the server cap, so the effective policy can only ever
+ * be MORE restrictive than the server, never less. A phone mission places
+ * real, billed calls — these bounds are the financial blast-radius cap.
+ */
+declare const PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+declare const PHONE_SERVER_MAX_COST_PER_MISSION = 5;
+declare const PHONE_SERVER_MAX_ATTEMPTS = 3;
+/** Hard cap on the free-text `task` fed to the voice runtime. */
+declare const PHONE_TASK_MAX_LENGTH = 2000;
+interface PhoneConfirmPolicy {
+    paymentDetails: 'never';
+    contractCommitment: 'never';
+    costOverLimit: 'needs_operator';
+    sensitivePersonalData: 'needs_operator';
+    unclearAlternative: 'needs_operator';
+}
+interface PhoneAlternativePolicy {
+    maxTimeShiftMinutes: number;
+}
+interface OpenClawPhoneMissionPolicy {
+    policyVersion: 1;
+    regionAllowlist: PhoneRegionScope[];
+    maxCallDurationSeconds: number;
+    maxCostPerMission: number;
+    maxAttempts: number;
+    transcriptEnabled: boolean;
+    recordingEnabled: boolean;
+    confirmPolicy: PhoneConfirmPolicy;
+    alternativePolicy: PhoneAlternativePolicy;
+}
+interface StartPhoneMissionInput {
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    voiceRuntimeRef?: string;
+}
+interface PhoneTransportProfile {
+    provider: string;
+    phoneNumber: string;
+    capabilities: TelephonyTransportCapability[];
+    supportedRegions: PhoneRegionScope[];
+}
+interface PhoneMissionValidationIssue {
+    code: string;
+    field: string;
+    message: string;
+}
+type PhoneMissionValidationResult = {
+    ok: true;
+    policy: OpenClawPhoneMissionPolicy;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+type PhoneTransportValidationResult = {
+    ok: true;
+    transport: PhoneTransportProfile;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+interface ValidatedPhoneMissionStart {
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    targetRegion: PhoneRegionScope;
+    transport: PhoneTransportProfile;
+    voiceRuntimeRef?: string;
+}
+type PhoneMissionStartValidationResult = {
+    ok: true;
+    mission: ValidatedPhoneMissionStart;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+declare function validatePhoneMissionPolicy(policy: unknown): PhoneMissionValidationResult;
+declare function validatePhoneTransportProfile(transport: unknown): PhoneTransportValidationResult;
+declare function inferPhoneRegion(phoneNumber: string): PhoneRegionScope | null;
+declare function isPhoneRegionAllowed(region: PhoneRegionScope, allowlist: readonly PhoneRegionScope[]): boolean;
+declare function classifyPhoneNumberRisk(phoneNumber: string): PhoneNumberRisk;
+declare function validatePhoneMissionStart(input: unknown, transport: unknown, options?: {
+    allowPremiumOrSpecialNumbers?: boolean;
+}): PhoneMissionStartValidationResult;
+
+type PhoneTransportProvider = '46elks';
+/**
+ * Abuse / cost controls for the call-control surface. A phone mission
+ * places a real, billed outbound call, so /calls/start needs hard limits
+ * that the caller cannot raise (see #43-H1).
+ */
+declare const PHONE_RATE_LIMIT_PER_MINUTE = 5;
+declare const PHONE_RATE_LIMIT_PER_HOUR = 30;
+declare const PHONE_MAX_CONCURRENT_MISSIONS = 3;
+/** Minimum entropy for an agent-supplied webhook secret (#43-H8). */
+declare const PHONE_MIN_WEBHOOK_SECRET_LENGTH = 24;
+/**
+ * Thrown by the webhook handlers for ANY authentication failure —
+ * unknown mission, missing token, or wrong token alike. Uniform on
+ * purpose: the route maps it to a single 403 + generic body so an
+ * unauthenticated caller cannot tell a real missionId from a fake one
+ * (#43-H3 — the 404-vs-403 enumeration oracle).
+ */
+declare class PhoneWebhookAuthError extends Error {
+    readonly isPhoneWebhookAuthError = true;
+    constructor();
+}
+/** Thrown when /calls/start is refused by a rate/concurrency limit (#43-H1). */
+declare class PhoneRateLimitError extends Error {
+    readonly isPhoneRateLimitError = true;
+    constructor(message: string);
+}
+interface PhoneTransportConfig extends PhoneTransportProfile {
+    provider: PhoneTransportProvider;
+    username: string;
+    password: string;
+    webhookBaseUrl: string;
+    webhookSecret: string;
+    apiUrl?: string;
+    configuredAt: string;
+}
+interface PhoneMissionTranscriptEntry {
+    at: string;
+    source: 'system' | 'provider' | 'agent' | 'operator';
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+interface PhoneCallMission {
+    id: string;
+    agentId: string;
+    status: PhoneMissionState;
+    from: string;
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    transport: PhoneTransportProfile;
+    provider: PhoneTransportProvider;
+    providerCallId?: string;
+    transcript: PhoneMissionTranscriptEntry[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface StartPhoneCallOptions {
+    dryRun?: boolean;
+    fetchFn?: typeof fetch;
+    now?: Date;
+}
+interface StartPhoneCallResult {
+    mission: PhoneCallMission;
+    providerRequest?: {
+        url: string;
+        body: Record<string, string>;
+    };
+    providerResponse?: unknown;
+}
+interface PhoneWebhookResult {
+    mission: PhoneCallMission;
+    action: Record<string, unknown>;
+}
+declare function redactPhoneTransportConfig(config: PhoneTransportConfig): PhoneTransportConfig;
+declare class PhoneManager {
+    private db;
+    private encryptionKey?;
+    private initialized;
+    /** Per-agent outbound-call timestamps (ms) for the in-memory rate limiter. */
+    private readonly callTimestamps;
+    constructor(db: Database, encryptionKey?: string | undefined);
+    /**
+     * Abuse / cost gate for /calls/start (#43-H1). Each non-dry-run call is
+     * a real billed outbound call, so before dialing we enforce:
+     *   - a hard cap on concurrently-active (non-terminal) missions, and
+     *   - a per-agent token-bucket rate limit (per-minute + per-hour).
+     * Throws {@link PhoneRateLimitError} (-> HTTP 429) when a limit is hit.
+     * Call only on the real path — dry runs place no call and are exempt.
+     */
+    private enforceCallLimits;
+    private encryptConfig;
+    private decryptConfig;
+    private ensureTables;
+    getPhoneTransportConfig(agentId: string): PhoneTransportConfig | null;
+    savePhoneTransportConfig(agentId: string, config: PhoneTransportConfig): PhoneTransportConfig;
+    getMission(missionId: string, agentId?: string): PhoneCallMission | null;
+    listMissions(agentId: string, opts?: {
+        limit?: number;
+        offset?: number;
+        status?: PhoneMissionState;
+    }): PhoneCallMission[];
+    startMission(agentId: string, input: StartPhoneMissionInput, options?: StartPhoneCallOptions): Promise<StartPhoneCallResult>;
+    /**
+     * Verify a webhook request and return the mission, or throw a uniform
+     * {@link PhoneWebhookAuthError} for ANY failure (unknown mission, no
+     * token, wrong token). Uniform on purpose — no 404-vs-403 oracle.
+     */
+    private authenticateWebhook;
+    handleVoiceStartWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneWebhookResult;
+    handleHangupWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneCallMission;
+    /**
+     * 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).
+     * Cost is only knowable post-call from the provider — the preventive
+     * cost controls are the duration ceiling, rate limit, and concurrency
+     * cap; this is the after-the-fact accounting + alerting.
+     */
+    private buildCostMetadataPatch;
+    private buildVoiceStartAction;
+    cancelMission(agentId: string, missionId: string): PhoneCallMission;
+    private build46ElksCallRequest;
+    private insertMission;
+    private updateProviderCall;
+    private updateMissionStatus;
+}
+declare function buildPhoneTransportConfig(input: {
+    provider?: unknown;
+    phoneNumber?: unknown;
+    username?: unknown;
+    password?: unknown;
+    webhookBaseUrl?: unknown;
+    webhookSecret?: unknown;
+    apiUrl?: unknown;
+    capabilities?: unknown;
+    supportedRegions?: unknown;
+    configuredAt?: string;
+}): PhoneTransportConfig;
+
 /**
  * AgenticMail Anonymous Telemetry
  *
@@ -2719,4 +3022,4 @@ declare class AgentMemoryStore {
     renderForPrompt(memory: AgentMemoryRead | null): string;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, 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, 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, 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, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, PathTraversalError, 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, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, 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, 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, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, 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 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, threadIdFor, tryJoin, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile };

package/dist/index.d.ts

@@ -505,6 +505,22 @@ interface SendResultWithRaw extends SendResult {
     /** Raw RFC822 message bytes (for appending to Sent folder) */
     raw: Buffer;
 }
+/** True for loopback hosts — the bundled local mail server lives here. */
+declare function isLoopbackMailHost(host: string | undefined): boolean;
+/**
+ * Resolve the effective TLS `rejectUnauthorized` for a mail connection.
+ *
+ * GHSA-wjjv-3mj2-39hf made certificate verification the default — but
+ * the bundled local mail server (Stalwart on 127.0.0.1) presents a
+ * self-signed certificate, so verifying it always fails and breaks
+ * local agent-to-agent mail out of the box. A self-signed cert on a
+ * loopback address is not a meaningful MITM surface, so for loopback
+ * hosts verification defaults OFF. Remote hosts still verify by
+ * default. An explicit `tlsRejectUnauthorized` option always wins
+ * either way, so a deployment can still force-verify localhost or
+ * opt a remote host out if it really needs to.
+ */
+declare function resolveTlsRejectUnauthorized(host: string | undefined, explicit: boolean | undefined): boolean;
 declare class MailSender {
     private options;
     private transporter;
@@ -1676,6 +1692,293 @@ declare class SmsPoller {
     private pollOnce;
 }
 
+declare const ELKS_REALTIME_AUDIO_FORMATS: readonly ["ulaw", "pcm_16000", "pcm_24000", "wav"];
+type ElksRealtimeAudioFormat = typeof ELKS_REALTIME_AUDIO_FORMATS[number];
+interface ElksRealtimeHelloMessage {
+    t: 'hello';
+    callid: string;
+    from: string;
+    to: string;
+    [key: string]: unknown;
+}
+interface ElksRealtimeAudioMessage {
+    t: 'audio';
+    data: string;
+}
+interface ElksRealtimeByeMessage {
+    t: 'bye';
+    reason?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+type ElksRealtimeInboundMessage = ElksRealtimeHelloMessage | ElksRealtimeAudioMessage | ElksRealtimeByeMessage;
+type ElksRealtimeOutboundMessage = {
+    t: 'listening';
+    format: ElksRealtimeAudioFormat;
+} | {
+    t: 'sending';
+    format: ElksRealtimeAudioFormat;
+} | {
+    t: 'audio';
+    data: string;
+} | {
+    t: 'interrupt';
+} | {
+    t: 'bye';
+};
+declare function parseElksRealtimeMessage(input: unknown): ElksRealtimeInboundMessage;
+declare function buildElksListeningMessage(format?: ElksRealtimeAudioFormat): ElksRealtimeOutboundMessage;
+declare function buildElksSendingMessage(format?: ElksRealtimeAudioFormat): ElksRealtimeOutboundMessage;
+declare function buildElksAudioMessage(data: string | Uint8Array): ElksRealtimeOutboundMessage;
+declare function buildElksInterruptMessage(): ElksRealtimeOutboundMessage;
+declare function buildElksByeMessage(): ElksRealtimeOutboundMessage;
+declare function buildElksHandshakeMessages(options?: {
+    listenFormat?: ElksRealtimeAudioFormat;
+    sendFormat?: ElksRealtimeAudioFormat;
+}): ElksRealtimeOutboundMessage[];
+
+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"];
+type TelephonyTransportCapability = typeof TELEPHONY_TRANSPORT_CAPABILITIES[number];
+declare const PHONE_MISSION_STATES: readonly ["draft", "approved", "dialing", "connected", "conversing", "needs_operator", "completed", "failed", "cancelled"];
+type PhoneMissionState = typeof PHONE_MISSION_STATES[number];
+type PhoneNumberRisk = 'invalid' | 'standard' | 'premium_or_special';
+/**
+ * Server-side hard ceilings for a phone mission policy.
+ *
+ * Hardening (#42-H1 / #43-H2) — `policy` is supplied by the calling agent,
+ * so a caller-set `maxCallDurationSeconds: 999999` or `maxCostPerMission:
+ * 1e9` is self-authorized and meaningless as a limit. These constants are
+ * the real ceiling: `validatePhoneMissionPolicy` clamps every caller value
+ * down to (at most) the server cap, so the effective policy can only ever
+ * be MORE restrictive than the server, never less. A phone mission places
+ * real, billed calls — these bounds are the financial blast-radius cap.
+ */
+declare const PHONE_SERVER_MAX_CALL_DURATION_SECONDS = 3600;
+declare const PHONE_SERVER_MAX_COST_PER_MISSION = 5;
+declare const PHONE_SERVER_MAX_ATTEMPTS = 3;
+/** Hard cap on the free-text `task` fed to the voice runtime. */
+declare const PHONE_TASK_MAX_LENGTH = 2000;
+interface PhoneConfirmPolicy {
+    paymentDetails: 'never';
+    contractCommitment: 'never';
+    costOverLimit: 'needs_operator';
+    sensitivePersonalData: 'needs_operator';
+    unclearAlternative: 'needs_operator';
+}
+interface PhoneAlternativePolicy {
+    maxTimeShiftMinutes: number;
+}
+interface OpenClawPhoneMissionPolicy {
+    policyVersion: 1;
+    regionAllowlist: PhoneRegionScope[];
+    maxCallDurationSeconds: number;
+    maxCostPerMission: number;
+    maxAttempts: number;
+    transcriptEnabled: boolean;
+    recordingEnabled: boolean;
+    confirmPolicy: PhoneConfirmPolicy;
+    alternativePolicy: PhoneAlternativePolicy;
+}
+interface StartPhoneMissionInput {
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    voiceRuntimeRef?: string;
+}
+interface PhoneTransportProfile {
+    provider: string;
+    phoneNumber: string;
+    capabilities: TelephonyTransportCapability[];
+    supportedRegions: PhoneRegionScope[];
+}
+interface PhoneMissionValidationIssue {
+    code: string;
+    field: string;
+    message: string;
+}
+type PhoneMissionValidationResult = {
+    ok: true;
+    policy: OpenClawPhoneMissionPolicy;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+type PhoneTransportValidationResult = {
+    ok: true;
+    transport: PhoneTransportProfile;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+interface ValidatedPhoneMissionStart {
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    targetRegion: PhoneRegionScope;
+    transport: PhoneTransportProfile;
+    voiceRuntimeRef?: string;
+}
+type PhoneMissionStartValidationResult = {
+    ok: true;
+    mission: ValidatedPhoneMissionStart;
+    issues: [];
+} | {
+    ok: false;
+    issues: PhoneMissionValidationIssue[];
+};
+declare function validatePhoneMissionPolicy(policy: unknown): PhoneMissionValidationResult;
+declare function validatePhoneTransportProfile(transport: unknown): PhoneTransportValidationResult;
+declare function inferPhoneRegion(phoneNumber: string): PhoneRegionScope | null;
+declare function isPhoneRegionAllowed(region: PhoneRegionScope, allowlist: readonly PhoneRegionScope[]): boolean;
+declare function classifyPhoneNumberRisk(phoneNumber: string): PhoneNumberRisk;
+declare function validatePhoneMissionStart(input: unknown, transport: unknown, options?: {
+    allowPremiumOrSpecialNumbers?: boolean;
+}): PhoneMissionStartValidationResult;
+
+type PhoneTransportProvider = '46elks';
+/**
+ * Abuse / cost controls for the call-control surface. A phone mission
+ * places a real, billed outbound call, so /calls/start needs hard limits
+ * that the caller cannot raise (see #43-H1).
+ */
+declare const PHONE_RATE_LIMIT_PER_MINUTE = 5;
+declare const PHONE_RATE_LIMIT_PER_HOUR = 30;
+declare const PHONE_MAX_CONCURRENT_MISSIONS = 3;
+/** Minimum entropy for an agent-supplied webhook secret (#43-H8). */
+declare const PHONE_MIN_WEBHOOK_SECRET_LENGTH = 24;
+/**
+ * Thrown by the webhook handlers for ANY authentication failure —
+ * unknown mission, missing token, or wrong token alike. Uniform on
+ * purpose: the route maps it to a single 403 + generic body so an
+ * unauthenticated caller cannot tell a real missionId from a fake one
+ * (#43-H3 — the 404-vs-403 enumeration oracle).
+ */
+declare class PhoneWebhookAuthError extends Error {
+    readonly isPhoneWebhookAuthError = true;
+    constructor();
+}
+/** Thrown when /calls/start is refused by a rate/concurrency limit (#43-H1). */
+declare class PhoneRateLimitError extends Error {
+    readonly isPhoneRateLimitError = true;
+    constructor(message: string);
+}
+interface PhoneTransportConfig extends PhoneTransportProfile {
+    provider: PhoneTransportProvider;
+    username: string;
+    password: string;
+    webhookBaseUrl: string;
+    webhookSecret: string;
+    apiUrl?: string;
+    configuredAt: string;
+}
+interface PhoneMissionTranscriptEntry {
+    at: string;
+    source: 'system' | 'provider' | 'agent' | 'operator';
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+interface PhoneCallMission {
+    id: string;
+    agentId: string;
+    status: PhoneMissionState;
+    from: string;
+    to: string;
+    task: string;
+    policy: OpenClawPhoneMissionPolicy;
+    transport: PhoneTransportProfile;
+    provider: PhoneTransportProvider;
+    providerCallId?: string;
+    transcript: PhoneMissionTranscriptEntry[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface StartPhoneCallOptions {
+    dryRun?: boolean;
+    fetchFn?: typeof fetch;
+    now?: Date;
+}
+interface StartPhoneCallResult {
+    mission: PhoneCallMission;
+    providerRequest?: {
+        url: string;
+        body: Record<string, string>;
+    };
+    providerResponse?: unknown;
+}
+interface PhoneWebhookResult {
+    mission: PhoneCallMission;
+    action: Record<string, unknown>;
+}
+declare function redactPhoneTransportConfig(config: PhoneTransportConfig): PhoneTransportConfig;
+declare class PhoneManager {
+    private db;
+    private encryptionKey?;
+    private initialized;
+    /** Per-agent outbound-call timestamps (ms) for the in-memory rate limiter. */
+    private readonly callTimestamps;
+    constructor(db: Database, encryptionKey?: string | undefined);
+    /**
+     * Abuse / cost gate for /calls/start (#43-H1). Each non-dry-run call is
+     * a real billed outbound call, so before dialing we enforce:
+     *   - a hard cap on concurrently-active (non-terminal) missions, and
+     *   - a per-agent token-bucket rate limit (per-minute + per-hour).
+     * Throws {@link PhoneRateLimitError} (-> HTTP 429) when a limit is hit.
+     * Call only on the real path — dry runs place no call and are exempt.
+     */
+    private enforceCallLimits;
+    private encryptConfig;
+    private decryptConfig;
+    private ensureTables;
+    getPhoneTransportConfig(agentId: string): PhoneTransportConfig | null;
+    savePhoneTransportConfig(agentId: string, config: PhoneTransportConfig): PhoneTransportConfig;
+    getMission(missionId: string, agentId?: string): PhoneCallMission | null;
+    listMissions(agentId: string, opts?: {
+        limit?: number;
+        offset?: number;
+        status?: PhoneMissionState;
+    }): PhoneCallMission[];
+    startMission(agentId: string, input: StartPhoneMissionInput, options?: StartPhoneCallOptions): Promise<StartPhoneCallResult>;
+    /**
+     * Verify a webhook request and return the mission, or throw a uniform
+     * {@link PhoneWebhookAuthError} for ANY failure (unknown mission, no
+     * token, wrong token). Uniform on purpose — no 404-vs-403 oracle.
+     */
+    private authenticateWebhook;
+    handleVoiceStartWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneWebhookResult;
+    handleHangupWebhook(missionId: string, providedToken: string, payload?: Record<string, unknown>): PhoneCallMission;
+    /**
+     * 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).
+     * Cost is only knowable post-call from the provider — the preventive
+     * cost controls are the duration ceiling, rate limit, and concurrency
+     * cap; this is the after-the-fact accounting + alerting.
+     */
+    private buildCostMetadataPatch;
+    private buildVoiceStartAction;
+    cancelMission(agentId: string, missionId: string): PhoneCallMission;
+    private build46ElksCallRequest;
+    private insertMission;
+    private updateProviderCall;
+    private updateMissionStatus;
+}
+declare function buildPhoneTransportConfig(input: {
+    provider?: unknown;
+    phoneNumber?: unknown;
+    username?: unknown;
+    password?: unknown;
+    webhookBaseUrl?: unknown;
+    webhookSecret?: unknown;
+    apiUrl?: unknown;
+    capabilities?: unknown;
+    supportedRegions?: unknown;
+    configuredAt?: string;
+}): PhoneTransportConfig;
+
 /**
  * AgenticMail Anonymous Telemetry
  *
@@ -2719,4 +3022,4 @@ declare class AgentMemoryStore {
     renderForPrompt(memory: AgentMemoryRead | null): string;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, 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, 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, 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, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, PathTraversalError, 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, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, 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, 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, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, 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 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, threadIdFor, tryJoin, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile };