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

package/dist/channels/index.d.ts

@@ -1,616 +1,4 @@
-import { A as AgentInput, d as AgentOutput } from '../types-BWoRx1ZE.js';
-import { Participant } from 'toolpack-sdk';
+export { B as BaseChannel, D as DiscordChannel, b as DiscordChannelConfig, E as EmailChannel, c as EmailChannelConfig, d as SMSChannel, e as SMSChannelConfig, f as ScheduledChannel, g as ScheduledChannelConfig, i as SlackChannel, j as SlackChannelConfig, T as TelegramChannel, k as TelegramChannelConfig, W as WebhookChannel, l as WebhookChannelConfig } from '../index-o8Lbzv5N.js';
+import '../types-TB6yypig.js';
+import 'toolpack-sdk';
 import 'events';
-
-/**
- * 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>;
-}
-
-/**
- * Configuration options for ScheduledChannel.
- */
-interface ScheduledChannelConfig {
-    /** Optional name for the channel - required for sendTo() routing */
-    name?: string;
-    /**
-     * Cron expression - supports full cron syntax including wildcards, ranges, steps, and lists.
-     * Supports both 5-field (min hour dom month dow) and 6-field (sec min hour dom month dow) expressions.
-     * Examples: '0 9 * * 1-5' for 9am weekdays, or '0 * /15 * * * *' for every 15 minutes (6-field)
-     */
-    cron: string;
-    /** Optional intent to pre-set in AgentInput */
-    intent?: string;
-    /** Optional message to send to the agent on each trigger */
-    message?: string;
-    /**
-     * Where to deliver the output. Supported protocols:
-     *
-     * - `webhook:<https-url>` — POSTs JSON `{ output, metadata, timestamp }` to the URL.
-     *
-     * For Slack delivery, attach a named `SlackChannel` to the same agent and
-     * route from inside `run()`:
-     *
-     * ```ts
-     * agent.channels = [
-     *   new ScheduledChannel({ name: 'daily', cron: '0 9 * * 1-5', notify: 'webhook:...' }),
-     *   new SlackChannel({ name: 'kore-slack', channel: '#project-kore', token, signingSecret }),
-     * ];
-     *
-     * async run(input) {
-     *   const report = await this.buildReport();
-     *   await this.sendTo('kore-slack', report);
-     *   return { output: report };
-     * }
-     * ```
-     *
-     * This keeps Slack credentials, thread routing, and multi-channel listening
-     * in one place (`SlackChannel`) instead of duplicated inside `ScheduledChannel`.
-     */
-    notify: string;
-}
-/**
- * Scheduled channel that runs agents on a cron schedule.
- * Delivers output to the configured notification destination.
- */
-declare class ScheduledChannel extends BaseChannel {
-    readonly isTriggerChannel = true;
-    private config;
-    private timer?;
-    constructor(config: ScheduledChannelConfig);
-    /**
-     * Start the cron scheduler.
-     */
-    listen(): void;
-    /**
-     * Send the agent output to the configured notify destination.
-     * @param output The agent output to send
-     */
-    send(output: AgentOutput): Promise<void>;
-    /**
-     * Normalize the scheduled trigger into AgentInput.
-     * Sets the intent and generates a date-keyed conversationId.
-     * @param _incoming Ignored for scheduled triggers
-     * @returns Normalized AgentInput
-     */
-    normalize(_incoming: unknown): AgentInput;
-    /**
-     * Send output to a webhook URL.
-     */
-    private sendToWebhook;
-    /**
-     * Calculate next run time using cron-parser.
-     */
-    private getNextRunTime;
-    /**
-     * Schedule the next run.
-     */
-    private scheduleNextRun;
-    /**
-     * Trigger the scheduled task.
-     */
-    private trigger;
-    /**
-     * Stop the scheduler.
-     */
-    stop(): Promise<void>;
-}
-
-/**
- * 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>;
-}
-
-/**
- * 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 */
-    guildId: string;
-    /** Target channel ID */
-    channelId: string;
-}
-/**
- * Discord channel for two-way Discord bot integration.
- * Receives messages from guild channels or DMs and replies in-thread.
- */
-declare class DiscordChannel extends BaseChannel {
-    readonly isTriggerChannel = false;
-    private config;
-    private client?;
-    constructor(config: DiscordChannelConfig);
-    /**
-     * Start listening for Discord messages.
-     */
-    listen(): void;
-    /**
-     * Send a message to Discord.
-     * @param output The agent output to send
-     */
-    send(output: AgentOutput): Promise<void>;
-    /**
-     * Normalize a Discord message into AgentInput.
-     * @param incoming Discord message object
-     * @returns Normalized AgentInput
-     */
-    normalize(incoming: unknown): AgentInput;
-    /**
-     * Handle incoming Discord messages.
-     */
-    private handleDiscordMessage;
-    /**
-     * Stop the Discord client.
-     */
-    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, DiscordChannel, type DiscordChannelConfig, EmailChannel, type EmailChannelConfig, SMSChannel, type SMSChannelConfig, ScheduledChannel, type ScheduledChannelConfig, SlackChannel, type SlackChannelConfig, TelegramChannel, type TelegramChannelConfig, WebhookChannel, type WebhookChannelConfig };