@agenticmail/core 0.9.13 → 0.9.15

package/dist/index.d.cts

@@ -1692,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
  *
@@ -2735,4 +3022,213 @@ 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, isLoopbackMailHost, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };
+/**
+ * Agent Memory Manager — persistent, evolving per-agent memory.
+ *
+ * Ported from the AgenticMail Enterprise engine memory system and
+ * adapted for the open-source single-tenant package: the multi-tenant
+ * `orgId` / organization concepts have been removed (memory here is
+ * personal to each agent), the database layer is the built-in
+ * `node:sqlite` `Database`, and agent deletion fully purges memory.
+ *
+ * Each agent gets a growing knowledge store that evolves over time,
+ * the way a human employee learns on the job:
+ * - Category-based organisation (knowledge, preference, correction,
+ *   skill, context, reflection, …).
+ * - Importance levels (critical / high / normal / low).
+ * - Confidence scores that decay for entries left unaccessed.
+ * - Access tracking so frequently-used knowledge ranks higher.
+ * - `generateMemoryContext()` — ranks + renders memory as a markdown
+ *   block for injection into an agent's prompt (or a voice session).
+ * - Pruning of expired / low-confidence entries.
+ *
+ * Design: an in-memory `Map` + BM25F search index fronts the
+ * `agent_memory` SQLite table. Reads hit memory; writes update both.
+ */
+
+type MemoryCategory = 'knowledge' | 'interaction_pattern' | 'preference' | 'correction' | 'skill' | 'context' | 'reflection' | 'session_learning' | 'system_notice';
+type MemoryImportance = 'critical' | 'high' | 'normal' | 'low';
+type MemorySource = 'interaction' | 'self_reflection' | 'correction' | 'system' | 'context_compaction' | 'transfer';
+declare const MEMORY_CATEGORIES: Record<MemoryCategory, {
+    label: string;
+    description: string;
+}>;
+interface AgentMemoryEntry {
+    id: string;
+    agentId: string;
+    category: MemoryCategory;
+    title: string;
+    content: string;
+    source: MemorySource;
+    importance: MemoryImportance;
+    confidence: number;
+    accessCount: number;
+    lastAccessedAt?: string;
+    expiresAt?: string;
+    tags: string[];
+    metadata: Record<string, any>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface MemoryStats {
+    totalEntries: number;
+    byCategory: Record<string, number>;
+    byImportance: Record<string, number>;
+    bySource: Record<string, number>;
+    avgConfidence: number;
+}
+/** Input shape for createMemory — id, timestamps, accessCount, and some fields have defaults. */
+type CreateMemoryInput = Omit<AgentMemoryEntry, 'id' | 'createdAt' | 'updatedAt' | 'accessCount' | 'confidence' | 'tags' | 'metadata' | 'lastAccessedAt' | 'expiresAt'> & {
+    confidence?: number;
+    tags?: string[];
+    metadata?: Record<string, any>;
+    lastAccessedAt?: string;
+    expiresAt?: string;
+};
+/** Input shape for updateMemory — partial updates merged with existing entry. */
+type UpdateMemoryInput = Partial<Omit<AgentMemoryEntry, 'id' | 'agentId' | 'createdAt'>>;
+/** Query options for filtering memory entries. */
+interface MemoryQueryOptions {
+    agentId: string;
+    category?: string;
+    importance?: string;
+    source?: string;
+    query?: string;
+    limit?: number;
+}
+declare class AgentMemoryManager {
+    private db;
+    private memories;
+    /** Per-agent index: agentId → Set of memory IDs for O(1) agent lookups */
+    private agentIndex;
+    /** Full-text search index (BM25F + stemming + inverted index) */
+    private searchIndex;
+    private initialized;
+    constructor(db: Database);
+    private ensureTable;
+    /** Run a write statement, swallowing errors with a log (memory must never crash a caller). */
+    private dbRun;
+    private dbAll;
+    private loadFromDb;
+    /** Add a memory ID to the per-agent index. */
+    private indexAdd;
+    /** Remove a memory ID from the per-agent index. */
+    private indexRemove;
+    /** Get all memory entries for an agent via the index. */
+    private getAgentMemories;
+    /** Store a memory with minimal input — the common "just remember this" case. */
+    storeMemory(agentId: string, opts: {
+        content: string;
+        category?: string;
+        importance?: string;
+        confidence?: number;
+        title?: string;
+        tags?: string[];
+    }): Promise<AgentMemoryEntry>;
+    /** Search memories by text query, sorted by relevance. */
+    recall(agentId: string, query: string, limit?: number): Promise<AgentMemoryEntry[]>;
+    /** Create a new memory entry with auto-generated id + timestamps. */
+    createMemory(input: CreateMemoryInput): Promise<AgentMemoryEntry>;
+    /** Update an existing memory entry by merging provided fields. */
+    updateMemory(id: string, updates: UpdateMemoryInput): Promise<AgentMemoryEntry | null>;
+    /** Delete a single memory entry. Returns true if it existed. */
+    deleteMemory(id: string): Promise<boolean>;
+    /**
+     * Purge every memory entry belonging to an agent — Map, per-agent
+     * index, search index, and the database row. Called when an agent is
+     * deleted so no orphaned memory is left behind.
+     * Returns the number of entries removed.
+     */
+    deleteAgentMemories(agentId: string): Promise<number>;
+    /** Retrieve a single memory entry by id. */
+    getMemory(id: string): Promise<AgentMemoryEntry | undefined>;
+    /** Query an agent's memory with optional category/importance/source filters + text search. */
+    queryMemories(opts: MemoryQueryOptions): Promise<AgentMemoryEntry[]>;
+    /** Memories created within the last N hours for an agent. */
+    getRecentMemories(agentId: string, hours?: number): Promise<AgentMemoryEntry[]>;
+    /** Bump access count + lastAccessedAt for a memory entry. */
+    recordAccess(memoryId: string): Promise<void>;
+    /**
+     * Render an agent's memory as a markdown block for prompt injection.
+     * Ranks entries by confidence × access × recency × importance, with a
+     * BM25F relevance boost when a query is supplied, groups by category,
+     * and truncates to ~maxTokens (estimated at 4 chars/token).
+     */
+    generateMemoryContext(agentId: string, query?: string, maxTokens?: number): Promise<string>;
+    /** Decay confidence for entries unaccessed for 7+ days. Critical entries are exempt. */
+    decayConfidence(agentId: string, decayRate?: number): Promise<number>;
+    /** Prune entries with confidence < 0.1 or past their expiresAt. */
+    pruneExpired(agentId?: string): Promise<number>;
+    /** Aggregate statistics for a specific agent's memory. */
+    getStats(agentId: string): Promise<MemoryStats>;
+    private computeStats;
+    private rowToEntry;
+}
+
+declare function stem(word: string): string;
+/** Tokenize text into stemmed, lowercase terms, filtering stop words. */
+declare function tokenize(text: string): string[];
+/**
+ * Pre-built inverted index for fast text search.
+ * Maintained incrementally — no re-indexing needed on queries.
+ *
+ * Structure:
+ *   term → Set<docId>              (posting list — which docs contain this term)
+ *   prefixMap: prefix → Set<stem>  (3-char prefixes → full stems for prefix matching)
+ *   docs: docId → DocRecord        (per-doc weighted TF and length)
+ *   idf: term → number             (pre-computed IDF, refreshed on mutations)
+ */
+declare class MemorySearchIndex {
+    /** Posting lists: stemmed term → Set of memory IDs containing it */
+    private postings;
+    /** Per-document metadata for BM25 scoring */
+    private docs;
+    /** Pre-computed IDF values. Stale flag triggers lazy recomputation. */
+    private idf;
+    private idfStale;
+    /** 3-character prefix map for prefix matching: prefix → Set of full stems */
+    private prefixMap;
+    /** Total weighted document length (for computing average) */
+    private totalWeightedLen;
+    get docCount(): number;
+    get avgDocLen(): number;
+    /**
+     * Index a memory entry. Extracts stems from title, content, and tags
+     * with field-specific weighting and builds posting lists.
+     */
+    addDocument(id: string, entry: {
+        title: string;
+        content: string;
+        tags: string[];
+    }): void;
+    /** Remove a document from the index. */
+    removeDocument(id: string): void;
+    /** Recompute IDF values for all terms. Called lazily before search. */
+    private refreshIdf;
+    /**
+     * Expand query terms with prefix matches.
+     * "deploy" → ["deploy", "deployment", "deploying", ...] (if they exist in the index)
+     */
+    private expandQueryTerms;
+    /**
+     * Compute bigram proximity boost: if two query terms appear adjacent
+     * in the document's stem sequence, boost the score.
+     */
+    private bigramProximityBoost;
+    /**
+     * Search the index for documents matching a query.
+     * Returns scored results sorted by BM25F relevance.
+     *
+     * @param query - Raw query string
+     * @param candidateIds - Optional: only score these document IDs (for agent-scoped search)
+     * @returns Array of { id, score } sorted by descending score
+     */
+    search(query: string, candidateIds?: Set<string>): Array<{
+        id: string;
+        score: number;
+    }>;
+    /** Check if a document exists in the index. */
+    has(id: string): boolean;
+}
+
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_SESSION_MAX_AGE_MS, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type HostName, type HostSession, type HostSessionResumeMode, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, MemorySearchIndex, type MemorySource, type MemoryStats, type OpenClawPhoneMissionPolicy, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedSms, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEPHONY_TRANSPORT_CAPABILITIES, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildPhoneTransportConfig, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, inferPhoneRegion, isInternalEmail, isLoopbackMailHost, isPhoneRegionAllowed, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, stem, threadIdFor, tokenize, tryJoin, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile };