@toolpack-sdk/agents 2.0.0-alpha.1 → 2.0.0

package/dist/index-o8Lbzv5N.d.ts

@@ -0,0 +1,927 @@
+import { A as AgentInput, e as AgentOutput } from './types-TB6yypig.js';
+import { Participant } from 'toolpack-sdk';
+
+/**
+ * Abstract base class for all agent channels.
+ * Channels handle the two-way communication between the external world and agents.
+ */
+declare abstract class BaseChannel {
+    /** Optional name for the channel - required for sendTo() routing */
+    name?: string;
+    /**
+     * Whether this is a trigger channel (no human recipient).
+     * Trigger channels like ScheduledChannel cannot use this.ask() since there's no human to answer.
+     * Conversation channels (Slack, Telegram, Webhook) can use this.ask().
+     */
+    abstract readonly isTriggerChannel: boolean;
+    /** Message handler set by AgentRegistry */
+    protected _handler?: (input: AgentInput) => Promise<void>;
+    /**
+     * Start listening for incoming messages.
+     * Called by AgentRegistry when the SDK initializes.
+     */
+    abstract listen(): void;
+    /**
+     * Send output back to the external world.
+     * @param output The agent's output to deliver
+     */
+    abstract send(output: AgentOutput): Promise<void>;
+    /**
+     * Normalize an incoming event into AgentInput.
+     * Each channel implementation maps its specific event format.
+     * @param incoming Raw event from the external source
+     * @returns Normalized AgentInput
+     */
+    abstract normalize(incoming: unknown): AgentInput;
+    /**
+     * Set the message handler. Called by AgentRegistry.
+     * @param handler Function to call when a message arrives
+     */
+    onMessage(handler: (input: AgentInput) => Promise<void>): void;
+    /**
+     * Helper to call the handler if set.
+     * @param input The normalized agent input
+     */
+    protected handleMessage(input: AgentInput): Promise<void>;
+}
+
+/**
+ * Configuration options for SlackChannel.
+ */
+interface SlackChannelConfig {
+    /** Optional name for the channel - required for sendTo() routing */
+    name?: string;
+    /**
+     * Which Slack channel(s) this instance listens to and replies into.
+     *
+     * - `string` (e.g. `'#support'` or `'C12345'`) — single channel (back-compat).
+     * - `string[]` — multiple channels; inbound events outside this list are dropped.
+     * - `null` / omitted — listen to every channel the bot is invited to.
+     *
+     * **Matching:** compared verbatim against `event.channel` from the Slack payload.
+     * Slack events carry channel IDs (`C...`), so pass IDs here for deterministic
+     * filtering. If you pass a display name like `'#general'`, it must match the
+     * raw string Slack sends — usually an ID, not a name. DMs (`im`/`mpim`) are
+     * always accepted regardless of this list.
+     *
+     * **Outbound:** when sending, `metadata.channelId` (set by `normalize()`) wins.
+     * If absent, the fallback is: `string` → itself; `string[]` → first element;
+     * `null` → error (must provide `metadata.channelId`).
+     */
+    channel?: string | string[] | null;
+    /** Slack bot token (starts with 'xoxb-') */
+    token: string;
+    /** Slack app signing secret for request verification */
+    signingSecret: string;
+    /** Optional port for the HTTP server (default: 3000) */
+    port?: number;
+    /**
+     * Allowlist of bot identities whose Slack messages should be processed when
+     * strict mode is desired.
+     *
+     * Behavior:
+     * - Omitted: non-self bot messages are accepted by default (Option B).
+     * - Provided (including empty array): only listed bots are accepted.
+     *
+     * Each entry is matched against **both** `event.bot_id` (a `B...` integration
+     * id) and `event.user` (a `U...` user id), since Slack events carry both and
+     * developers frequently know one but not the other. Pass whichever you have —
+     * typically the peer agent's `SlackChannel.botUserId` (a `U...` value).
+     *
+     * Note: for normal multi-agent teams you do **not** need to list peers here —
+     * non-self bot messages are allowed by default. Use this field only when you
+     * want strict, allowlist-only acceptance. To suppress specific noisy bots
+     * (e.g. GitHub, CI) while keeping the default-allow behavior, prefer
+     * {@link SlackChannelConfig.blockedBotIds}.
+     *
+     * Example (strict mode): `allowedBotIds: [ramDevAgent.slackChannel.botUserId, 'B_YALINA_BOT']`
+     */
+    allowedBotIds?: string[];
+    /**
+     * Blocklist of bot identities that should always be ignored.
+     *
+     * Matched against both `event.bot_id` (B...) and `event.user` (U...).
+     * Takes precedence over `allowedBotIds` and the default allow behavior.
+     */
+    blockedBotIds?: string[];
+}
+/**
+ * Slack channel for two-way Slack integration.
+ * Receives messages from users and replies in-thread.
+ */
+declare class SlackChannel extends BaseChannel {
+    readonly isTriggerChannel = false;
+    private config;
+    private server?;
+    /**
+     * Per-process cache of resolved participants keyed by Slack user id.
+     * Populated lazily by `resolveParticipant()`. Invalidated on `user_change`
+     * events via `invalidateParticipant()`.
+     */
+    private participantCache;
+    /**
+     * The bot's Slack user id (e.g. `'U_BOT123'`), populated by the startup
+     * self-check (`auth.test`) when `listen()` is called.
+     *
+     * Pass this to `AssemblerOptions.agentAliases` so the assembler's
+     * addressed-only mode can match `<@U_BOT123>` mentions against this agent:
+     * ```ts
+     * assemblePrompt(store, conversationId, agent.name, agent.name, {
+     *   agentAliases: [slackChannel.botUserId].filter(Boolean) as string[],
+     * });
+     * ```
+     */
+    botUserId?: string;
+    /**
+     * Normalized allowlist of channel identifiers, or `null` to accept any channel.
+     * Derived from `config.channel` at construction time.
+     */
+    private allowedChannels;
+    constructor(config: SlackChannelConfig);
+    /**
+     * Start listening for Slack events via HTTP webhook.
+     *
+     * Performs a startup self-check (`auth.test`) after the server is ready.
+     * The bot user id is stored on `this.botUserId` for use in `agentAliases`.
+     */
+    listen(): void;
+    /**
+     * Calls Slack's `auth.test` API to verify credentials and log the bot's
+     * identity. Stores `botUserId` for use in `AssemblerOptions.agentAliases`.
+     * Non-fatal — a failed check logs a warning but does not stop the server.
+     */
+    private runStartupCheck;
+    /**
+     * Verify a Slack request signature using HMAC-SHA256.
+     *
+     * Implements Slack's signing secret verification spec:
+     * https://api.slack.com/authentication/verifying-requests-from-slack
+     *
+     * - Rejects requests with a timestamp older than 5 minutes (replay protection).
+     * - Uses `timingSafeEqual` to prevent timing-oracle attacks.
+     *
+     * Returns `false` for any missing, malformed, or invalid input so that the
+     * caller can respond with 401 without leaking which check failed.
+     */
+    verifySignature(headers: Record<string, string | string[] | undefined>, rawBody: string): boolean;
+    /**
+     * Send a message back to Slack.
+     * @param output The agent output to send
+     */
+    send(output: AgentOutput): Promise<void>;
+    /**
+     * Normalize a Slack event into AgentInput.
+     * @param incoming Slack event payload
+     * @returns Normalized AgentInput
+     */
+    normalize(incoming: unknown): AgentInput;
+    /**
+     * Resolve a richer `Participant` (with `displayName`) for a normalized input.
+     *
+     * Uses Slack's `users.info` API and an in-process cache. Returns `undefined`
+     * if the input has no user id or if the lookup fails; callers fall back to
+     * the bare id. Never throws.
+     *
+     * Cache invalidation is handled externally via `invalidateParticipant()`,
+     * typically wired to the Slack `user_change` event.
+     */
+    resolveParticipant(input: AgentInput): Promise<Participant | undefined>;
+    /**
+     * Invalidate a cached participant. Call this from a `user_change`
+     * Slack event handler to force a refresh on the next lookup.
+     */
+    invalidateParticipant(userId: string): void;
+    /**
+     * Decide whether an incoming Slack event should be normalised and dispatched
+     * to the agent.
+     *
+     * Rules, applied in order:
+     * 1. Only `message` and `app_mention` events are processed; others are dropped.
+     * 2. Channel allowlist (from `config.channel`): events outside the allowlist
+     *    are dropped. DMs (`im`/`mpim`) always pass because they are per-user, not
+     *    per-channel. Skipped entirely when `config.channel` is null/omitted.
+     * 3. **Self-suppression (automatic):** events where `event.user` matches this
+     *    channel's own `botUserId` are dropped. This prevents agents from looping
+     *    on their own posts and requires no configuration — `botUserId` is
+     *    discovered via `auth.test` at startup.
+     * 4. Events without `bot_id` (human messages) pass.
+     * 5. Explicit blocklist check (`blockedBotIds`) runs first for bot messages.
+     * 6. If `allowedBotIds` is provided, strict mode applies: only listed bots
+     *    pass (matched against both `bot_id` and `user`).
+     * 7. If `allowedBotIds` is omitted, other bot messages pass by default.
+     *
+     * Exposed for direct unit testing; not intended as a public API.
+     */
+    shouldProcessEvent(event: Record<string, unknown>): boolean;
+    /**
+     * Handle incoming HTTP requests from Slack.
+     */
+    private handleRequest;
+    /**
+     * Stop the HTTP server.
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Configuration options for WebhookChannel.
+ */
+interface WebhookChannelConfig {
+    /** Optional name for the channel - required for sendTo() routing */
+    name?: string;
+    /** HTTP path to listen on (e.g., '/agent/support') */
+    path: string;
+    /** Optional port for the HTTP server (default: 3000) */
+    port?: number;
+}
+/**
+ * Webhook channel that exposes an HTTP endpoint.
+ * Receives HTTP requests and responds with agent output.
+ */
+declare class WebhookChannel extends BaseChannel {
+    readonly isTriggerChannel = false;
+    private config;
+    private server?;
+    private pendingResponses;
+    constructor(config: WebhookChannelConfig);
+    /**
+     * Start listening for HTTP requests.
+     */
+    listen(): void;
+    /**
+     * Send the agent output as an HTTP response.
+     * @param output The agent output to send
+     */
+    send(output: AgentOutput): Promise<void>;
+    /**
+     * Normalize an HTTP request into AgentInput.
+     * @param incoming HTTP request body with headers
+     * @returns Normalized AgentInput
+     */
+    normalize(incoming: unknown): AgentInput;
+    /**
+     * Handle incoming HTTP requests.
+     */
+    private handleRequest;
+    /**
+     * Generate a unique session ID.
+     */
+    private generateSessionId;
+    /**
+     * Stop the HTTP server.
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Scheduler types — shared across SchedulerStore, scheduler tools, and ScheduledChannel.
+ */
+type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * A single scheduled job record.
+ */
+interface ScheduledJob {
+    /** Unique identifier (UUIDv4). */
+    id: string;
+    /** Name of the channel this job belongs to (for multi-channel routing). */
+    channelName?: string;
+    /** Next execution time in epoch ms. */
+    nextRunAt: number;
+    /**
+     * Cron expression for recurring jobs.
+     * Undefined for one-shot jobs.
+     */
+    cron?: string;
+    /** Intent hint forwarded to AgentInput. */
+    intent?: string;
+    /** Message forwarded to AgentInput. */
+    message?: string;
+    /** Extra data merged into AgentInput.data. */
+    payload?: Record<string, unknown>;
+    /** Current lifecycle status. */
+    status: JobStatus;
+    /** Epoch ms of the last execution. */
+    lastRunAt?: number;
+    /** Error message from the last failed execution. */
+    lastError?: string;
+    /** Epoch ms when the job was created. */
+    createdAt: number;
+}
+/**
+ * Options for creating a new scheduled job.
+ * Exactly one of `cron` (recurring) or `runAt` (one-shot) must be provided.
+ */
+interface CreateJobOptions {
+    /** Channel name to scope this job to. */
+    channelName?: string;
+    /** Intent hint for the agent. */
+    intent?: string;
+    /** Message for the agent. */
+    message?: string;
+    /** Extra data merged into AgentInput.data. */
+    payload?: Record<string, unknown>;
+    /**
+     * Cron expression for recurring jobs.
+     * Supports 5-field (min hour dom month dow) and 6-field (sec min hour dom month dow).
+     */
+    cron?: string;
+    /**
+     * Exact time for one-shot jobs.
+     * Accepts a Date object or epoch ms.
+     */
+    runAt?: Date | number;
+}
+/**
+ * Result of a create operation — includes a duplicate flag if dedup matched.
+ */
+interface CreateJobResult {
+    job: ScheduledJob;
+    /** True if an existing pending job matched the dedup key (job was not re-created). */
+    duplicate: boolean;
+}
+
+/**
+ * SQLite-backed persistent store for scheduled jobs.
+ *
+ * @example
+ * ```ts
+ * const store = new SchedulerStore({ dbPath: './scheduler.db' });
+ *
+ * // Create a recurring job
+ * const { job } = store.create({
+ *   intent: 'weekly_report',
+ *   cron: '0 9 * * 1',
+ *   message: 'Generate weekly summary',
+ * });
+ *
+ * // Create a one-shot job
+ * store.create({
+ *   intent: 'onboarding_followup',
+ *   runAt: new Date('2026-06-01T10:00:00Z'),
+ * });
+ * ```
+ */
+declare class SchedulerStore {
+    private db;
+    constructor({ dbPath }?: {
+        dbPath?: string;
+    });
+    private _migrate;
+    /**
+     * Create a new scheduled job.
+     *
+     * **Deduplication** — before inserting, checks for an existing `pending` job
+     * with the same key:
+     * - Recurring (`cron`): matched on `(intent, cron, channel_name)`
+     * - One-shot (`runAt`): matched on `(intent, next_run_at, channel_name)`
+     *
+     * Returns the existing job with `duplicate: true` instead of creating a duplicate.
+     */
+    create(opts: CreateJobOptions): CreateJobResult;
+    /**
+     * Get a single job by ID.
+     */
+    get(id: string): ScheduledJob | undefined;
+    /**
+     * List jobs, optionally filtered by status and channel.
+     */
+    list(filter?: {
+        status?: JobStatus | 'all';
+        channelName?: string;
+        limit?: number;
+    }): ScheduledJob[];
+    /**
+     * Return all pending jobs whose nextRunAt <= now (due or overdue).
+     * Used by ScheduledChannel for missed-run recovery and normal polling.
+     * Pass `channelName` to scope results to a specific channel.
+     */
+    getDue(now?: number, channelName?: string): ScheduledJob[];
+    /**
+     * Return the single next pending job (earliest nextRunAt).
+     * Used by ScheduledChannel to calculate optimal sleep duration.
+     */
+    getNextPending(channelName?: string): ScheduledJob | undefined;
+    /**
+     * Update an existing pending job.
+     */
+    update(id: string, updates: {
+        cron?: string;
+        message?: string;
+        intent?: string;
+        runAt?: Date | number;
+        payload?: Record<string, unknown>;
+    }): ScheduledJob | undefined;
+    /**
+     * Cancel a pending job. Returns true if cancelled, false if not found or not pending.
+     */
+    cancel(id: string): boolean;
+    /**
+     * Reset any jobs stuck in `running` state back to `pending`.
+     *
+     * Should be called once on ScheduledChannel startup. A job can get stuck as
+     * `running` if the process crashes after `markRunning()` but before
+     * `markCompleted()` or `markFailed()`. Without this call those jobs would
+     * never be retried since `getDue()` only returns `pending` jobs.
+     *
+     * Pass `channelName` to scope the reset to a specific channel.
+     *
+     * @returns The number of jobs reset.
+     */
+    resetStuck(channelName?: string): number;
+    /** Mark a job as running (called before execution). */
+    markRunning(id: string): void;
+    /** Mark a completed job. For recurring jobs, calculates and sets the next run time. */
+    markCompleted(id: string): void;
+    /** Mark a job as failed and store the error. Recurring jobs are rescheduled. */
+    markFailed(id: string, error: string): void;
+    private _getById;
+    private _findDuplicate;
+    /** Close the underlying database connection. */
+    close(): void;
+}
+
+/**
+ * Configuration for ScheduledChannel.
+ *
+ * Provide `cron` for a simple static schedule, `store` for dynamic agent-driven
+ * scheduling, or both — the store takes precedence when both are supplied, and
+ * the `cron` is seeded into the store as an initial job on `listen()`.
+ *
+ * Output delivery is the agent's responsibility. Use `sendTo()` inside
+ * `invokeAgent()` to route results to a named channel (Slack, webhook, etc.).
+ */
+interface ScheduledChannelConfig {
+    /** Optional name — required for `sendTo()` routing in multi-channel setups. */
+    name?: string;
+    /**
+     * Static cron expression.
+     * Used directly when no `store` is provided.
+     * When a `store` is also provided, this is seeded into the store as an
+     * initial recurring job (subject to deduplication).
+     *
+     * Supports 5-field (min hour dom month dow) and 6-field (sec min hour dom month dow).
+     * Example: `'0 9 * * 1-5'` for 9am on weekdays.
+     */
+    cron?: string;
+    /**
+     * Dynamic scheduler store.
+     * When provided, the channel polls the store for due jobs instead of (or in
+     * addition to) the static cron. The store drives all scheduling decisions,
+     * enabling agents to schedule their own future invocations via scheduler tools.
+     */
+    store?: SchedulerStore;
+    /** Default intent forwarded to AgentInput when no job-level intent is set. */
+    intent?: string;
+    /** Default message forwarded to AgentInput when no job-level message is set. */
+    message?: string;
+    /**
+     * How often (in ms) to poll the store for new jobs when it is currently empty.
+     * Agents that create new jobs via `scheduler.create` while the store is idle
+     * will be picked up within this interval.
+     *
+     * Default: `30_000` (30 seconds).
+     */
+    idlePollMs?: number;
+}
+/**
+ * A trigger-only channel that runs agents on a cron schedule or via a
+ * dynamic SchedulerStore.
+ *
+ * - No `notify` option — output delivery is the agent's responsibility.
+ * - `isTriggerChannel = true` — `this.ask()` is not available inside triggered runs.
+ * - When a `store` is provided, supports missed-run recovery on startup and
+ *   lets agents schedule their own future invocations using `scheduler.*` tools.
+ *
+ * @example Static cron
+ * ```ts
+ * const channel = new ScheduledChannel({
+ *   name: 'daily',
+ *   cron: '0 9 * * 1-5',
+ *   intent: 'daily_report',
+ * });
+ * ```
+ *
+ * @example Dynamic store (agent-driven scheduling)
+ * ```ts
+ * const store = new SchedulerStore({ dbPath: './scheduler.db' });
+ *
+ * const channel = new ScheduledChannel({
+ *   name: 'dynamic',
+ *   store,
+ * });
+ *
+ * // Agent tools: scheduler.create / scheduler.list / scheduler.cancel / scheduler.update
+ * ```
+ *
+ * @example Both — static seed + dynamic store
+ * ```ts
+ * const store = new SchedulerStore({ dbPath: './scheduler.db' });
+ *
+ * const channel = new ScheduledChannel({
+ *   name: 'hybrid',
+ *   cron: '0 9 * * 1-5',  // seeded into store on listen()
+ *   store,
+ *   intent: 'morning_check',
+ *   idlePollMs: 10_000,   // check for agent-created jobs every 10s when idle
+ * });
+ * ```
+ */
+declare class ScheduledChannel extends BaseChannel {
+    readonly isTriggerChannel = true;
+    private config;
+    private timer?;
+    private _stopped;
+    /**
+     * Incremented each time `listen()` is called. Callbacks capture the value at
+     * the moment they are created; if it no longer matches `_generation` by the
+     * time they resume, they know a new listen-cycle has started and self-cancel.
+     * This prevents a stop()+listen() during an in-flight async callback from
+     * spawning a second independent timer loop.
+     */
+    private _generation;
+    constructor(config: ScheduledChannelConfig);
+    /**
+     * Start the scheduler.
+     *
+     * - Static-only mode: sets up a recurring setTimeout loop.
+     * - Store mode: seeds the static cron (if any), recovers missed runs, then
+     *   sets up a smart-sleep loop driven by the store's next pending job.
+     */
+    listen(): void;
+    /**
+     * Stop the scheduler and clear any pending timer.
+     */
+    stop(): Promise<void>;
+    /**
+     * ScheduledChannel is a pure trigger — output delivery is handled by the
+     * agent via `sendTo()`. This method is intentionally a no-op.
+     */
+    send(_output: AgentOutput): Promise<void>;
+    /**
+     * Normalize a scheduled trigger (or store job) into AgentInput.
+     *
+     * @param incoming A ScheduledJob from the store, or null for static cron triggers.
+     */
+    normalize(incoming: unknown): AgentInput;
+    private _listenStatic;
+    private _scheduleNextStatic;
+    private _triggerStatic;
+    private _listenWithStore;
+    private _scheduleNextFromStore;
+    private _triggerJob;
+    private _nextRunFromCron;
+}
+
+/**
+ * Configuration options for TelegramChannel.
+ */
+interface TelegramChannelConfig {
+    /** Optional name for the channel - required for sendTo() routing */
+    name?: string;
+    /** Telegram bot token (from @BotFather) */
+    token: string;
+    /** Optional webhook URL for receiving updates (if not using polling) */
+    webhookUrl?: string;
+}
+/**
+ * Telegram channel for two-way Telegram bot integration.
+ * Receives messages from users and sends replies.
+ */
+declare class TelegramChannel extends BaseChannel {
+    readonly isTriggerChannel = false;
+    private config;
+    private offset;
+    private pollingInterval?;
+    private server?;
+    /**
+     * The bot's Telegram user id (numeric, as a string), populated by the
+     * startup self-check (`getMe`) when `listen()` is called.
+     *
+     * Pass this to `AssemblerOptions.agentAliases` so the assembler's
+     * addressed-only mode can match `text_mention` entities whose user id
+     * equals this value.
+     */
+    botUserId?: string;
+    /** The bot's @username (without the @), populated by the `getMe` check. */
+    botUsername?: string;
+    constructor(config: TelegramChannelConfig);
+    /**
+     * Start listening for Telegram updates.
+     * Uses either webhook or polling mode depending on configuration.
+     */
+    listen(): void;
+    /**
+     * Calls Telegram's `getMe` API to verify the token and log the bot's
+     * identity. Stores `botUserId` and `botUsername` for use in
+     * `AssemblerOptions.agentAliases`. Non-fatal — a failed check logs a
+     * warning but does not stop the channel.
+     */
+    private runStartupCheck;
+    /**
+     * Send a message back to Telegram.
+     * @param output The agent output to send
+     */
+    send(output: AgentOutput): Promise<void>;
+    /**
+     * Normalize a Telegram update into AgentInput.
+     * @param incoming Telegram update object
+     * @returns Normalized AgentInput
+     */
+    normalize(incoming: unknown): AgentInput;
+    /**
+     * Start polling for updates.
+     */
+    private startPolling;
+    /**
+     * Poll for updates from Telegram.
+     */
+    private pollUpdates;
+    /**
+     * Start webhook server for receiving updates.
+     */
+    private startWebhook;
+    /**
+     * Set webhook URL with Telegram.
+     */
+    private setWebhook;
+    /**
+     * Handle incoming webhook requests from Telegram.
+     */
+    private handleWebhookRequest;
+    /**
+     * Stop the channel (polling or webhook).
+     */
+    stop(): Promise<void>;
+}
+
+interface DiscordAuthor {
+    id: string;
+    username: string;
+    globalName?: string | null;
+    bot?: boolean;
+    system?: boolean;
+}
+interface DiscordChannelInfo {
+    type?: number;
+    name?: string;
+}
+interface DiscordThread {
+    id: string;
+}
+/** Minimal shape of a discord.js Message used by this channel. */
+interface DiscordMessage {
+    id?: string;
+    content?: string;
+    channelId?: string;
+    guildId?: string;
+    /** Present on webhook-originated messages; absent on normal user messages. */
+    webhookId?: string;
+    author?: DiscordAuthor;
+    channel?: DiscordChannelInfo;
+    thread?: DiscordThread;
+}
+/**
+ * Configuration options for DiscordChannel.
+ */
+interface DiscordChannelConfig {
+    /** Optional name for the channel — required for sendTo() routing. */
+    name?: string;
+    /** Discord bot token. */
+    token: string;
+    /**
+     * Target guild (server) ID filter.
+     * When set, only messages from this guild pass through.
+     * DMs (which carry no guildId) are dropped when this is configured.
+     * Omit to allow messages from all guilds and DMs.
+     */
+    guildId?: string;
+    /**
+     * Target channel ID filter.
+     *   - `string`  — only messages in this channel pass through.
+     *   - `string[]` — only messages in one of these channels pass through.
+     *   - `null` / `undefined` — no channel filter; all channels in the guild pass.
+     *
+     * Also used as the default destination when send() has no metadata.channelId.
+     */
+    channelId?: string | string[] | null;
+    /**
+     * Bot user IDs that are explicitly allowed to pass through.
+     * When set, only bots in this list are processed; all other bots are dropped.
+     * blockedBotIds takes precedence — a bot in both lists is always dropped.
+     * When omitted, ALL bots are dropped by default.
+     */
+    allowedBotIds?: string[];
+    /**
+     * Bot user IDs that are explicitly blocked.
+     * Checked before allowedBotIds; matching bots are always dropped.
+     */
+    blockedBotIds?: string[];
+}
+/**
+ * DiscordChannel — full-featured Discord bot channel.
+ *
+ * Capabilities beyond the basic implementation:
+ *
+ * 1. shouldProcessEvent() — ordered, deterministic filtering:
+ *    system/webhook messages → self-suppression → guild filter → channel allowlist
+ *    → bot blocklist → bot allowlist → default-drop bots → pass.
+ *    All filtering happens in code, not in the LLM prompt.
+ *
+ * 2. normalize() — extracts @mention user IDs (<@id> and <@!id>) from content
+ *    and exposes them as context.mentions (the key the capture interceptor reads
+ *    for addressed-only mode). Also sets context.isMentioned when the bot is tagged.
+ *
+ * 3. resolveParticipant() — fetches richer user info (globalName / avatar) from
+ *    the Discord REST API with an in-process per-channel cache.
+ *    Call invalidateParticipant(userId) when a `userUpdate` event fires.
+ *
+ * 4. send() — priority chain: threadId metadata → channelId metadata → first
+ *    configured channel → throws if nothing is resolvable.
+ *
+ * 5. Multi-channel support — channelId accepts string, string[], or null/undefined.
+ *
+ * 6. Bot self-suppression — botUserId is captured from the `ready` event so our
+ *    own echoes are dropped without a separate lookup.
+ *
+ * 7. userUpdate wiring — participant cache entries are invalidated automatically
+ *    when Discord fires a userUpdate event.
+ */
+declare class DiscordChannel extends BaseChannel {
+    readonly isTriggerChannel = false;
+    protected readonly config: DiscordChannelConfig;
+    /** Normalised set of allowed channel IDs (empty = no filter). */
+    private readonly allowedChannelIds;
+    /**
+     * The bot's own Discord user ID — populated after the `ready` event.
+     *
+     * Expose this to agent code for use in `agentAliases` (addressed-only mode):
+     * ```ts
+     * agentAliases: [discordChannel.botUserId].filter(Boolean) as string[]
+     * ```
+     */
+    botUserId?: string;
+    /** In-process participant cache keyed by Discord user ID. */
+    private readonly participantCache;
+    /** discord.js Client instance (populated by listen()). */
+    private client?;
+    constructor(config: DiscordChannelConfig);
+    /**
+     * Deterministic gate applied before any message reaches the LLM.
+     *
+     * Rules (applied in order; first match wins):
+     *   1. No author OR webhook message → drop (system embeds, webhooks).
+     *   2. Author is the bot itself → drop (echo suppression).
+     *   3. guildId filter configured and message doesn't match → drop (incl. DMs).
+     *   4. channelId allowlist configured and message not in it → drop.
+     *   5. Author is a bot / system:
+     *      a. blockedBotIds matches → drop.
+     *      b. allowedBotIds set and not in list → drop.
+     *      c. No allowedBotIds → drop all bots by default.
+     *   6. All checks passed → process.
+     */
+    shouldProcessEvent(message: DiscordMessage): boolean;
+    normalize(incoming: unknown): AgentInput;
+    /**
+     * Resolve a richer Participant (with displayName) from the Discord REST API.
+     *
+     * Successful results are cached in-process for the lifetime of the channel.
+     * Call invalidateParticipant(userId) when a `userUpdate` event fires.
+     *
+     * On API error or network failure, returns a bare `{ kind, id }` participant
+     * without caching so the next invocation will retry — matching the behavior
+     * of SlackChannel. Never throws.
+     */
+    resolveParticipant(input: AgentInput): Promise<Participant | undefined>;
+    /**
+     * Remove a cached participant entry.
+     * Call this when Discord fires a `userUpdate` event so the next interaction
+     * fetches fresh data from the API.
+     */
+    invalidateParticipant(userId: string): void;
+    send(output: AgentOutput): Promise<void>;
+    listen(): void;
+    stop(): Promise<void>;
+}
+
+/**
+ * Configuration options for EmailChannel.
+ */
+interface EmailChannelConfig {
+    /** Optional name for the channel - required for sendTo() routing */
+    name?: string;
+    /** Sender email address */
+    from: string;
+    /** Recipient email address(es) - for scheduled/outbound emails */
+    to: string | string[];
+    /** SMTP configuration */
+    smtp: {
+        host: string;
+        port: number;
+        auth: {
+            user: string;
+            pass: string;
+        };
+        secure?: boolean;
+    };
+    /** Optional subject line template */
+    subject?: string;
+}
+/**
+ * Email channel for sending outbound emails via SMTP.
+ * This is an outbound-only channel - for inbound email handling,
+ * use a custom email-reader tool + WebhookChannel.
+ */
+declare class EmailChannel extends BaseChannel {
+    readonly isTriggerChannel = true;
+    private config;
+    private transporter?;
+    constructor(config: EmailChannelConfig);
+    /**
+     * Initialize the email transporter.
+     * EmailChannel is outbound-only, so listen() just sets up the transporter.
+     */
+    listen(): void;
+    /**
+     * Send an email with the agent's output.
+     * @param output The agent output to send
+     */
+    send(output: AgentOutput): Promise<void>;
+    /**
+     * EmailChannel is outbound-only and doesn't receive messages.
+     * This method should not be called.
+     */
+    normalize(_incoming: unknown): never;
+    /**
+     * Format plain text as HTML for better email rendering.
+     */
+    private formatAsHtml;
+    /**
+     * Close the email transporter.
+     */
+    stop(): Promise<void>;
+}
+
+/**
+ * Configuration options for SMSChannel (Twilio).
+ */
+interface SMSChannelConfig {
+    /** Optional name for the channel - required for sendTo() routing */
+    name?: string;
+    /** Twilio Account SID */
+    accountSid: string;
+    /** Twilio Auth Token */
+    authToken: string;
+    /** Twilio phone number (sender) */
+    from: string;
+    /** Recipient phone number - for outbound/scheduled SMS */
+    to?: string;
+    /** Optional webhook path for inbound SMS (e.g., '/sms/webhook') */
+    webhookPath?: string;
+    /** Optional port for the HTTP server (default: 3000) */
+    port?: number;
+}
+/**
+ * SMS channel for Twilio integration.
+ * Can be configured as:
+ * - Two-way: Set webhookPath to receive inbound SMS and reply
+ * - Outbound-only: Set 'to' without webhookPath for scheduled/triggered SMS
+ */
+declare class SMSChannel extends BaseChannel {
+    private config;
+    private twilioClient?;
+    private server?;
+    constructor(config: SMSChannelConfig);
+    /**
+     * Two-way when webhookPath is set, outbound-only otherwise.
+     */
+    get isTriggerChannel(): boolean;
+    /**
+     * Start listening for inbound SMS via Twilio webhook (if webhookPath is set).
+     */
+    listen(): void;
+    /**
+     * Send an SMS message.
+     * @param output The agent output to send
+     */
+    send(output: AgentOutput): Promise<void>;
+    /**
+     * Normalize a Twilio webhook payload into AgentInput.
+     * @param incoming Twilio webhook payload
+     * @returns Normalized AgentInput
+     */
+    normalize(incoming: unknown): AgentInput;
+    /**
+     * Start HTTP server to receive Twilio webhooks.
+     */
+    private startWebhookServer;
+    /**
+     * Handle incoming webhook requests from Twilio.
+     */
+    private handleWebhookRequest;
+    /**
+     * Stop the webhook server.
+     */
+    stop(): Promise<void>;
+}
+
+export { BaseChannel as B, type CreateJobOptions as C, DiscordChannel as D, EmailChannel as E, type JobStatus as J, SchedulerStore as S, TelegramChannel as T, WebhookChannel as W, type CreateJobResult as a, type DiscordChannelConfig as b, type EmailChannelConfig as c, SMSChannel as d, type SMSChannelConfig as e, ScheduledChannel as f, type ScheduledChannelConfig as g, type ScheduledJob as h, SlackChannel as i, type SlackChannelConfig as j, type TelegramChannelConfig as k, type WebhookChannelConfig as l };