@agenticmail/core 0.9.23 → 0.9.25

package/dist/index.d.ts

@@ -2732,6 +2732,21 @@ declare const GET_DATETIME_TOOL: RealtimeToolDefinition;
  * opt in. Kept in the file so the tool surface is documented in one place.
  */
 declare const SEARCH_EMAIL_TOOL: RealtimeToolDefinition;
+/**
+ * Phase 3 (skill library) — find the right skill playbook for the
+ * situation just hit on the call. Always call BEFORE {@link LOAD_SKILL_TOOL}
+ * so the loaded skill actually matches the situation. Fast (file-on-
+ * disk search) — a brief "one moment" is enough; no long hold needed.
+ */
+declare const SEARCH_SKILLS_TOOL: RealtimeToolDefinition;
+/**
+ * Phase 3 (skill library) — load a skill playbook into the session
+ * for the rest of the call. Tell the caller "hold on one moment"
+ * BEFORE calling — loading involves a `session.update` round-trip.
+ * Max two skills are loaded at once; a third FIFO-evicts the
+ * oldest (the bridge enforces this).
+ */
+declare const LOAD_SKILL_TOOL: RealtimeToolDefinition;
 /** Every tool defined in this module, keyed by name. */
 declare const REALTIME_TOOL_DEFINITIONS: Record<string, RealtimeToolDefinition>;
 /**
@@ -3202,6 +3217,26 @@ declare class RealtimeVoiceBridge {
     private readonly toolCallNames;
     /** `call_id`s whose tool call is currently executing. */
     private readonly inFlightToolCalls;
+    /**
+     * Mid-call skills loaded into the session so far, FIFO. Earliest at
+     * index 0; cap at {@link MAX_LOADED_SKILLS}. When a (cap+1)th skill
+     * is loaded the oldest one drops out — the model can't usefully
+     * hold five playbooks in working memory at once, so we keep the
+     * working set narrow on purpose.
+     */
+    private readonly loadedSkills;
+    /**
+     * The original `instructions` string from the session.update sent at
+     * open. We keep a private copy because every mid-call skill load
+     * issues a fresh `session.update` whose `instructions` is built as:
+     *
+     *     baseInstructions + "\n\n" + renderedSkill1 + "\n\n" + renderedSkill2 …
+     *
+     * Without this snapshot, successive loads would compound — the second
+     * load would see "base + skill1" as the base and append skill2 to
+     * THAT, eventually drifting unboundedly.
+     */
+    private baseInstructions;
     constructor(opts: RealtimeVoiceBridgeOptions);
     /** True once the bridge has ended. */
     get isEnded(): boolean;
@@ -3215,6 +3250,41 @@ declare class RealtimeVoiceBridge {
     handleOpenAIOpen(): void;
     /** Call when the OpenAI socket closes. */
     handleOpenAIClose(): void;
+    /**
+     * Load a skill playbook into the live OpenAI Realtime session for
+     * the rest of the call.
+     *
+     * Mechanics:
+     *   1. Resolve the skill JSON via the skills registry (file on disk).
+     *   2. Append the rendered skill text to the agent's working
+     *      instructions and re-send a `session.update` carrying ONLY
+     *      the new `instructions` field. The OpenAI Realtime API
+     *      supports partial session.update — we don't have to re-send
+     *      audio config, tools, voice, etc.
+     *   3. Track which skills are loaded so we (a) FIFO-evict the
+     *      oldest when the cap is hit and (b) include every still-
+     *      loaded skill in the next composed instructions.
+     *   4. Emit a transcript marker so the mission record shows the
+     *      adaptation ("[skill loaded: Negotiate a Bill Reduction
+     *      v1.0.0]"). Useful for post-call review and for the build
+     *      farm's telemetry on which skills actually got reached for.
+     *
+     * Returns an object the {@link load_skill} tool handler can serialise
+     * back to the model: `ok: true` plus the skill name + version on
+     * success, `ok: false` plus a short reason on failure (unknown id,
+     * call ended, registry I/O error). Never throws — a buggy registry
+     * or a missing file must not crash the bridge mid-call.
+     *
+     * Phase 2 of the skill library (`docs/skill-library-plan.md`).
+     */
+    loadSkillIntoSession(skillId: string): Promise<{
+        ok: boolean;
+        message: string;
+        name?: string;
+        version?: string;
+    }>;
+    /** The list of skills currently loaded into the session (FIFO-ordered). */
+    get loadedSkillIds(): readonly string[];
     /** Call when the OpenAI socket errors. */
     handleOpenAIError(err: unknown): void;
     /**
@@ -5290,4 +5360,299 @@ declare class MemorySearchIndex {
     has(id: string): boolean;
 }
 
-export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SEARCH_EMAIL_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, requireBinary, requireWhisperModel, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateTwilioSignature, webSearch };
+/**
+ * AgenticMail skill library — types.
+ *
+ * A "skill" is a structured how-to-act-like-a-skilled-human bundle for
+ * a single real-world task an agent might be asked to do: negotiate a
+ * bill, book a reservation, handle a debt collector, escalate to a
+ * supervisor. Each skill is a JSON document with a fixed schema (this
+ * file) so agents can load them on demand AND so humans / other agents
+ * can contribute new ones without writing TypeScript.
+ *
+ * The skill schema is deliberately verbose. A skill that an agent
+ * loads mid-call into its system prompt needs to teach it everything
+ * a human would intuitively know: what to open with, what objections
+ * to expect, how to phrase a graceful concession, when to walk away.
+ * Sparse skills ("just be assertive") do not actually transfer
+ * competence to a language model that has never made the call before.
+ *
+ * Why JSON, not Markdown / Python / a DSL:
+ *   - Stable, language-agnostic — community contributions can come
+ *     from anyone with a text editor; the schema validates and rejects
+ *     malformed contributions on PR.
+ *   - Embeddable in a Realtime API session.update — the JSON shape can
+ *     be rendered into a single `instructions` block at load time.
+ *   - Diffable on GitHub — reviewers can see exactly what changed,
+ *     phrase-by-phrase, in a PR.
+ *   - Searchable — registry-level fuzzy match on name / description /
+ *     tags / phrase contents works without any extra index layer.
+ *
+ * The schema is intentionally open to extension: every object has an
+ * optional `extra: Record<string, unknown>` escape hatch so a
+ * contributor can attach domain-specific fields without waiting for a
+ * core schema bump. The MCP `skill_load` tool returns the raw object,
+ * so an agent that recognises the extension can use it directly.
+ */
+/** Wire-format JSON skill — the on-disk file shape. */
+interface Skill {
+    /**
+     * Globally-unique slug. Lowercase, hyphenated, no spaces.
+     * Convention: `<verb>-<noun>` (`negotiate-bill-reduction`,
+     * `book-restaurant-reservation`). Used as the `skill_load` argument
+     * and as the JSON filename (`<id>.json`).
+     */
+    id: string;
+    /** Human-readable title, sentence case. */
+    name: string;
+    /**
+     * Semver. Bumped when the skill changes materially (new tactic
+     * added, deprecation, etc). Agents that loaded an older version
+     * mid-call keep their copy — versioning is for the registry, not
+     * the in-flight session.
+     */
+    version: string;
+    /**
+     * Coarse-grained category. Keep this list short and stable; tags
+     * are where the long tail lives.
+     */
+    category: SkillCategory;
+    /** Free-form lowercase tags for search. */
+    tags: string[];
+    /**
+     * One-sentence summary used in search results + the `skill_list`
+     * tool's response. The first 80 characters are what an agent sees
+     * when deciding whether to load the full skill.
+     */
+    description: string;
+    /**
+     * REQUIRED legal / safety disclaimer the agent must recite to the
+     * other party at the start of the call when this skill is loaded.
+     * Set to `null` for skills that need no disclaimer; set to a
+     * literal string for skills with legal / medical / financial
+     * sensitivity (debt collection, court representation, medical
+     * triage). The agent's system prompt is updated to make this
+     * disclaimer mandatory before any substantive turn.
+     */
+    disclaimer: string | null;
+    /** When + why to reach for this skill. */
+    context: SkillContext;
+    /**
+     * Three to seven principles the agent should internalise. These
+     * are the strategic frame — concrete phrasing lives in `phrases`
+     * and `tactics`. Mirror the kind of advice a friend who's GOOD at
+     * this thing would give you in a 30-second pep talk.
+     */
+    principles: string[];
+    /**
+     * Named scripted phrases. Keys are stable identifiers
+     * (`opener`, `objection_no_discounts`, `stall_thinking`) so a
+     * tactic can reference a phrase by key.
+     */
+    phrases: Record<string, string>;
+    /**
+     * Ordered list of specific moves to attempt, with their preconditions
+     * and scripts. Agents should try tactics in order, falling back to
+     * the next when the previous fails.
+     */
+    tactics: SkillTactic[];
+    /**
+     * Hard rules the agent must NOT cross. These are checked at every
+     * turn — if the agent is about to violate one, it should pull
+     * back, possibly via `ask_operator`. Examples: don't lie about
+     * the user's situation, don't commit money on the user's behalf
+     * without confirmation, don't be abusive.
+     */
+    boundaries: string[];
+    /** Signs the call is going well — keep doing what's working. */
+    success_signals: string[];
+    /** Signs the call is going badly — escalate or exit. */
+    failure_signals: string[];
+    /** How to end the call. Almost always invoked; design carefully. */
+    exit_strategy: SkillExitStrategy;
+    /**
+     * Information the agent needs from the operator (via task brief or
+     * `ask_operator` mid-call) BEFORE it can use this skill effectively.
+     * Used by the mission planner to flag missing context up front.
+     */
+    required_user_info: string[];
+    /** Free-form attribution: name or handle of the contributor. */
+    contributed_by: string;
+    /** ISO 8601. Set by the registry on first load if absent. */
+    created_at?: string;
+    /** ISO 8601. Bumped on every JSON edit. */
+    updated_at?: string;
+    /**
+     * Forward-compatible extension hatch. Domain-specific fields a
+     * contributor wants to attach without a core schema bump live
+     * here. Agents that recognise the extension key use it; others
+     * ignore it. Example: `extra.compliance_jurisdiction: 'US'`.
+     */
+    extra?: Record<string, unknown>;
+}
+/** Coarse-grained taxonomy. Extend ONLY via PR + a reviewer's nod. */
+type SkillCategory = 'negotiation' | 'customer-service' | 'reservations' | 'medical-admin' | 'legal-admin' | 'finance-admin' | 'real-estate' | 'travel' | 'subscription' | 'home-services' | 'social' | 'civic' | 'employment' | 'debt-collection' | 'other';
+/** When-to-use + preconditions block. */
+interface SkillContext {
+    /** Plain-language description of the situation this skill fits. */
+    when_to_use: string;
+    /** What must be true before the agent picks up the phone. */
+    preconditions: string[];
+    /**
+     * Realistic typical duration. Used to set the mission's
+     * `maxCallDurationSeconds` policy automatically if not overridden.
+     */
+    estimated_call_duration_minutes: number;
+}
+/** A single move the agent can try. */
+interface SkillTactic {
+    name: string;
+    /** When to deploy this tactic. */
+    when: string;
+    /**
+     * Verbatim script. The agent paraphrases to match its voice but
+     * keeps the structural moves (mirror, ask for retention, etc).
+     */
+    script: string;
+    /**
+     * Optional priority order (1 = try first). Defaults to array order.
+     * Lower-priority tactics are fallbacks.
+     */
+    priority?: number;
+}
+/** How to wrap the call up. Different ending for success vs failure. */
+interface SkillExitStrategy {
+    /** What to do / say when the call hit its goal. */
+    on_success: string;
+    /** What to do / say when the goal isn't reachable on this call. */
+    on_failure: string;
+    /**
+     * Optional follow-ups for the operator after the call ends —
+     * tasks like "email the rep's confirmation number" or "calendar a
+     * 30-day check-back". The mission report includes these.
+     */
+    follow_ups?: string[];
+}
+/** Skill summary returned by `skill_list` / `skill_search` (no body). */
+interface SkillSummary {
+    id: string;
+    name: string;
+    category: SkillCategory;
+    tags: string[];
+    description: string;
+    version: string;
+    disclaimer_required: boolean;
+    estimated_call_duration_minutes: number;
+}
+/** Failed-validation result from the schema validator. */
+interface SkillValidationError {
+    path: string;
+    message: string;
+}
+
+/**
+ * Skill registry — load, search, validate, list.
+ *
+ * Skills live in two places:
+ *
+ *   1. **Built-in** — JSON files bundled with `@agenticmail/core` at
+ *      `packages/core/src/skills/built-in/*.json`. These ship with
+ *      every install and form the starter library. Editing one in
+ *      a fork is fine, but the canonical copy is the one in the
+ *      monorepo — PRs to add or refine built-in skills are the
+ *      community contribution path.
+ *
+ *   2. **User-contributed** — JSON files dropped into
+ *      `~/.agenticmail/skills/*.json` at runtime. The registry
+ *      scans this directory on every `list` / `search` / `load`
+ *      call (cached for a few seconds) so a user can add a skill
+ *      without restarting the server. User-contributed skills
+ *      override built-ins when their `id` collides.
+ *
+ * The registry is filesystem-only — no DB. A skill is a leaf JSON
+ * file, easy to diff in git, easy to write by hand. Loading skills
+ * directly from `~/.agenticmail/skills/` (no manifest, no
+ * `enabled: true`) is deliberate: the simplest contribution path
+ * is "drop the file in, that's it."
+ */
+
+/** Manual cache invalidation — useful for tests + after a write. */
+declare function invalidateSkillCache(): void;
+/**
+ * Schema validator. Returns a list of (path, message) — empty list
+ * means the skill is structurally valid. Catches the classes of
+ * mistakes a contributor is most likely to make:
+ *
+ *   - Missing top-level required fields.
+ *   - Wrong types (`tactics` as object instead of array).
+ *   - Empty arrays where a non-empty one is required.
+ *   - Invalid `category` value.
+ *   - Tactic with empty `script`.
+ *
+ * Intentionally NOT a full JSON-schema implementation — the cost of
+ * a dependency on `ajv` or similar isn't justified for our shape.
+ */
+declare function validateSkill(s: unknown): SkillValidationError[];
+/** List all skills (summaries), optionally filtered. */
+declare function listSkills(opts?: {
+    category?: SkillCategory;
+    tag?: string;
+}): SkillSummary[];
+/**
+ * Search skills by free-text query, ranked by BM25F.
+ *
+ * Uses {@link MemorySearchIndex} — the same scorer that powers
+ * persistent agent memory. Field weighting puts name (title 3×) and
+ * tags (2×) above body content (1×), so an exact-name hit always beats
+ * a phrase-body match. Inverted posting lists mean scoring only touches
+ * docs that share at least one stem with the query — search cost grows
+ * with matches, not corpus size, so a 1,000-skill library scores in
+ * the same sub-millisecond range as a 10-skill one.
+ *
+ * Two behaviours worth knowing:
+ *
+ *   - **Stemming + stop-word removal.** "negotiating", "negotiate",
+ *     and "negotiation" all match the same skills. "the", "a", "for"
+ *     are dropped from the query.
+ *   - **Empty / no-match queries return an empty list**, not the full
+ *     library. The model should call `skill_list` if it wants
+ *     everything; `skill_search` is for "did anything match?".
+ *
+ * If the BM25F search returns nothing (typo, very rare phrase), we
+ * fall back to a tiny linear scan that catches substring hits the
+ * stemmer might have missed. Keeps the search forgiving without
+ * making the fast path slow.
+ */
+declare function searchSkills(query: string, limit?: number): SkillSummary[];
+/** Load the FULL skill body (everything an agent needs to act on it). */
+declare function loadSkill(id: string): Skill | null;
+/**
+ * Save a new or updated skill to `~/.agenticmail/skills/<id>.json`.
+ * Validates first; throws on invalid input. Bumps `updated_at`.
+ *
+ * Used by `agenticmail skill add` and by the future "build farm"
+ * agents that draft skills programmatically — the same path either
+ * way.
+ */
+declare function saveUserSkill(skill: Skill): {
+    path: string;
+};
+/** Where the user library lives (for surfacing in error messages / help). */
+declare function userSkillsDir(): string;
+
+/**
+ * Render a loaded skill into a single block of text suitable for
+ * injection into an OpenAI Realtime `session.update.instructions`
+ * (or any other plain-text system-prompt slot). The rendering is
+ * intentionally verbose — language models perform best when the
+ * tactical knowledge is spelled out narrative-style, not as a
+ * skeletal outline.
+ *
+ * Convention: every rendered skill starts with a marker so the
+ * agent can recognise it's operating with a loaded skill, and
+ * ends with a separator so additional skills (loaded later in the
+ * call) can be concatenated without ambiguity.
+ */
+declare function renderSkillAsPrompt(skill: Skill): string;
+
+export { AGENT_ROLES, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneConfirmPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveConfig, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };