@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/channels/service.js

@@ -0,0 +1,608 @@
+/**
+ * Channel service for the gateway runtime (phase 2).
+ *
+ * Owns every channel transport (`channels/src/transports/*`):
+ * starts the configured ones at boot, stops them cleanly on shutdown, and
+ * exposes the operations the command handlers need:
+ *
+ * - `list()` → `ChannelInfo[]` for the `channel.list` command (real status:
+ *   `connected` when creds are present and the transport is running,
+ *   `error` when creds exist but the platform rejected them,
+ *   `disconnected` when creds are missing — the NOT_CONFIGURED case).
+ * - `send(channel, target, text)` → outbound message via the transport.
+ * - `pair(channel)` / `unpair(channel, target)` → Telegram chat pairing
+ *   (`BOOM-######` codes) for Telegram and Zalo Personal.
+ *
+ * Integration contract (for executor A, who owns `context.ts`):
+ * the real `ServiceContext` must structurally satisfy
+ * {@link ChannelServiceContext} below (`config`, `dataDir`, `log`,
+ * `events`, optional `turnService`). `startChannelService` attaches the
+ * service at `ctx.channelService`; `getChannelService()` exposes the
+ * started instance to `handlers/channels.ts`.
+ *
+ * Secrets: channel configs carry tokens; they are passed to transports and
+ * never logged (SECURITY.md §5).
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { decryptSecret, encryptSecret, } from '@boombot/protocol';
+import { isTurnDonePayload, } from './transports/common.js';
+import { DiscordTransport, } from './transports/discord.js';
+import { MessengerTransport, } from './transports/messenger.js';
+import { SlackTransport, } from './transports/slack.js';
+import { TelegramTransport, TURN_DONE_EVENT, } from './transports/telegram.js';
+import { TikTokTransport, } from './transports/tiktok.js';
+import { WhatsAppTransport, } from './transports/whatsapp.js';
+import { createZaloPersonalClient, ZALO_QR_EVENT, ZaloPersonalTransport, } from './transports/zalo-personal.js';
+import { ZaloTransport, } from './transports/zalo.js';
+const DISPLAY_ORDER = [
+    'telegram',
+    'whatsapp',
+    'discord',
+    'slack',
+    'zalo',
+    'messenger',
+    'tiktok',
+];
+let activeService;
+const ZALO_PERMISSION_URL = 'https://oauth.zaloapp.com/v4/oa/permission';
+const ZALO_TOKEN_URL = 'https://oauth.zaloapp.com/v4/oa/access_token';
+const ZALO_CALLBACK_PATH = '/v1/channels/zalo/oauth/callback';
+const OAUTH_TTL_MS = 10 * 60 * 1000;
+const REFRESH_EARLY_MS = 5 * 60 * 1000;
+function parseZaloPersonalCredentials(raw) {
+    const value = JSON.parse(raw);
+    if (typeof value !== 'object' ||
+        value === null ||
+        typeof value.imei !== 'string' ||
+        typeof value.userAgent !== 'string' ||
+        !('cookie' in value)) {
+        throw new Error('invalid Zalo personal credentials');
+    }
+    return value;
+}
+function readCredentials(path, masterKey, log) {
+    if (!existsSync(path))
+        return {};
+    if (!masterKey) {
+        log.warn('channel credentials ignored: BOOMBOT_MASTER_KEY is missing');
+        return {};
+    }
+    try {
+        const stored = JSON.parse(readFileSync(path, 'utf8'));
+        if (stored.version !== 1)
+            throw new Error('unsupported store version');
+        return {
+            ...(stored.zaloMode ? { zaloMode: stored.zaloMode } : {}),
+            ...(stored.telegram
+                ? { telegramBotToken: decryptSecret(masterKey, stored.telegram.botTokenCipher) }
+                : {}),
+            ...(stored.zalo
+                ? {
+                    zalo: {
+                        appId: stored.zalo.appId,
+                        appSecret: decryptSecret(masterKey, stored.zalo.appSecretCipher),
+                        accessToken: decryptSecret(masterKey, stored.zalo.accessTokenCipher),
+                        refreshToken: decryptSecret(masterKey, stored.zalo.refreshTokenCipher),
+                        expiresAt: stored.zalo.expiresAt,
+                        ...(stored.zalo.oaId ? { oaId: stored.zalo.oaId } : {}),
+                    },
+                }
+                : {}),
+            ...(stored.zaloPersonal
+                ? {
+                    zaloPersonal: parseZaloPersonalCredentials(decryptSecret(masterKey, stored.zaloPersonal.credentialsCipher)),
+                }
+                : {}),
+        };
+    }
+    catch (error) {
+        log.error('channel credentials could not be read', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return {};
+    }
+}
+function writeCredentials(path, masterKey, credentials) {
+    const stored = {
+        version: 1,
+        ...(credentials.zaloMode ? { zaloMode: credentials.zaloMode } : {}),
+        ...(credentials.telegramBotToken
+            ? {
+                telegram: {
+                    botTokenCipher: encryptSecret(masterKey, credentials.telegramBotToken),
+                },
+            }
+            : {}),
+        ...(credentials.zalo
+            ? {
+                zalo: {
+                    appId: credentials.zalo.appId,
+                    appSecretCipher: encryptSecret(masterKey, credentials.zalo.appSecret),
+                    accessTokenCipher: encryptSecret(masterKey, credentials.zalo.accessToken),
+                    refreshTokenCipher: encryptSecret(masterKey, credentials.zalo.refreshToken),
+                    expiresAt: credentials.zalo.expiresAt,
+                    ...(credentials.zalo.oaId ? { oaId: credentials.zalo.oaId } : {}),
+                },
+            }
+            : {}),
+        ...(credentials.zaloPersonal
+            ? {
+                zaloPersonal: {
+                    credentialsCipher: encryptSecret(masterKey, JSON.stringify(credentials.zaloPersonal)),
+                },
+            }
+            : {}),
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp`;
+    writeFileSync(temporary, JSON.stringify(stored, null, 2), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    try {
+        chmodSync(temporary, 0o600);
+    }
+    catch {
+        // Windows ACLs do not follow POSIX chmod; encryption remains mandatory.
+    }
+    renameSync(temporary, path);
+}
+function parseZaloTokens(raw) {
+    const accessToken = typeof raw.access_token === 'string' ? raw.access_token : '';
+    const refreshToken = typeof raw.refresh_token === 'string' ? raw.refresh_token : '';
+    const expiresIn = Number(raw.expires_in);
+    if (accessToken === '' || refreshToken === '' || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+        throw new Error('ZALO_TOKEN_EXCHANGE_FAILED: invalid token response');
+    }
+    return {
+        accessToken,
+        refreshToken,
+        expiresAt: Date.now() + expiresIn * 1000,
+    };
+}
+/** The service started by `startChannelService`, if any. */
+export function getChannelService() {
+    return activeService;
+}
+class DefaultChannelService {
+    credentialPath;
+    credentials;
+    ctx;
+    log;
+    masterKey;
+    oauthSessions = new Map();
+    transports;
+    zaloQrAbort;
+    constructor(transports, ctx, credentials) {
+        this.transports = transports;
+        this.ctx = ctx;
+        this.credentials = credentials;
+        this.log = ctx.log;
+        this.credentialPath = join(ctx.dataDir, 'channels', 'credentials.json');
+        this.masterKey = process.env['BOOMBOT_MASTER_KEY']?.trim() || undefined;
+    }
+    async list() {
+        return this.transports.map((transport) => {
+            const { status } = transport.getStatus();
+            return {
+                id: transport.kind,
+                kind: transport.kind,
+                status,
+                displayName: transport.displayName,
+            };
+        });
+    }
+    stopPendingConnections() {
+        this.zaloQrAbort?.();
+        this.zaloQrAbort = undefined;
+    }
+    async send(channel, target, text) {
+        if (channel === 'zalo' && this.credentials.zaloMode !== 'personal') {
+            await this.refreshZaloIfNeeded();
+        }
+        await this.findTransport(channel).send(target, text);
+    }
+    async handleWebhook(channel, request) {
+        const transport = this.findTransportByKind(channel);
+        const handler = transport.handleWebhook;
+        if (handler === undefined)
+            return { status: 404 };
+        return handler.call(transport, request);
+    }
+    async connect(input) {
+        if (input.channel === 'telegram')
+            return this.connectTelegram(input.botToken);
+        return input.mode === 'personal'
+            ? this.startZaloPersonalQr()
+            : this.startZaloOAuth(input);
+    }
+    async completeZaloOAuth(params) {
+        const state = params.get('state') ?? '';
+        const session = this.oauthSessions.get(state);
+        this.oauthSessions.delete(state);
+        if (session === undefined || session.expiresAt <= Date.now()) {
+            throw new Error('ZALO_OAUTH_INVALID_STATE');
+        }
+        if (params.has('error'))
+            throw new Error('ZALO_OAUTH_DENIED');
+        const code = params.get('code')?.trim() ?? '';
+        if (code === '')
+            throw new Error('ZALO_OAUTH_MISSING_CODE');
+        const response = await fetch(ZALO_TOKEN_URL, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                secret_key: session.appSecret,
+            },
+            body: new URLSearchParams({
+                app_id: session.appId,
+                code,
+                grant_type: 'authorization_code',
+                code_verifier: session.codeVerifier,
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok)
+            throw new Error(`ZALO_TOKEN_EXCHANGE_FAILED: HTTP ${response.status}`);
+        const tokens = parseZaloTokens((await response.json()));
+        const oaId = params.get('oa_id')?.trim() || undefined;
+        const zalo = {
+            appId: session.appId,
+            appSecret: session.appSecret,
+            ...tokens,
+            ...(oaId ? { oaId } : {}),
+        };
+        const transport = new ZaloTransport({ oaToken: zalo.accessToken }, this.log);
+        await transport.start();
+        if (transport.getStatus().status !== 'connected') {
+            throw new Error('ZALO_CREDENTIAL_CHECK_FAILED');
+        }
+        this.credentials.zalo = zalo;
+        this.credentials.zaloMode = 'oa';
+        try {
+            this.persistCredentials();
+        }
+        catch (error) {
+            await transport.stop();
+            throw error;
+        }
+        await this.replaceTransport('zalo', transport);
+        this.log.info('zalo: OAuth connection completed', { oaId });
+    }
+    async pair(channel) {
+        const transport = this.findTransport(channel);
+        if (!(transport instanceof TelegramTransport) &&
+            !(transport instanceof ZaloPersonalTransport)) {
+            throw new Error(`PAIRING_UNSUPPORTED: pairing requires Telegram or Zalo Personal (requested: ${channel}).`);
+        }
+        const code = transport.createPairingCode();
+        this.log.info('channel.pair: pairing code created', { channel });
+        return code;
+    }
+    async unpair(channel, target) {
+        const transport = this.findTransport(channel);
+        if (transport instanceof ZaloPersonalTransport) {
+            transport.unpairThread(target);
+        }
+        else if (transport instanceof TelegramTransport) {
+            transport.unpairChat(target);
+        }
+        else {
+            throw new Error(`PAIRING_UNSUPPORTED: unpair requires Telegram or Zalo Personal (requested: ${channel}).`);
+        }
+        this.log.info('channel.unpair: chat removed from allowlist', { channel, target });
+    }
+    async connectTelegram(rawToken) {
+        const botToken = rawToken.trim();
+        if (!/^\d+:[A-Za-z0-9_-]{20,}$/.test(botToken)) {
+            throw new Error('INVALID_ARGUMENT: Telegram bot token format is invalid');
+        }
+        const current = this.findTransportByKind('telegram');
+        if (current.getStatus().status === 'connected') {
+            return { status: 'connected', displayName: current.displayName };
+        }
+        const transport = new TelegramTransport({
+            config: { ...(this.ctx.config.channels?.telegram ?? {}), botToken },
+            dataDir: this.ctx.dataDir,
+            log: this.log,
+            turnService: this.ctx.turnService,
+            subscribeTurnDone: makeTurnDoneSubscription(this.ctx.events),
+        });
+        await transport.start();
+        const status = transport.getStatus().status;
+        if (status !== 'connected' && status !== 'pending') {
+            await transport.stop();
+            throw new Error('INVALID_ARGUMENT: Telegram rejected the bot token');
+        }
+        this.credentials.telegramBotToken = botToken;
+        try {
+            this.persistCredentials();
+        }
+        catch (error) {
+            await transport.stop();
+            throw error;
+        }
+        await this.replaceTransport('telegram', transport);
+        return { status: 'connected', displayName: transport.displayName };
+    }
+    async startZaloPersonalQr() {
+        this.zaloQrAbort?.();
+        const zalo = createZaloPersonalClient();
+        let settled = false;
+        let resolveQr = () => { };
+        let rejectQr = () => { };
+        const qr = new Promise((resolve, reject) => {
+            resolveQr = resolve;
+            rejectQr = reject;
+        });
+        const login = zalo.loginQR({}, (event) => {
+            if (event.actions)
+                this.zaloQrAbort = event.actions.abort;
+            if (event.type === ZALO_QR_EVENT.QRCodeGenerated && event.data) {
+                settled = true;
+                resolveQr({
+                    status: 'qr_required',
+                    qrDataUrl: `data:image/png;base64,${event.data.image}`,
+                    expiresAt: new Date(Date.now() + 2 * 60 * 1000).toISOString(),
+                });
+            }
+            else if (!settled &&
+                (event.type === ZALO_QR_EVENT.QRCodeExpired ||
+                    event.type === ZALO_QR_EVENT.QRCodeDeclined)) {
+                rejectQr(new Error('ZALO_QR_EXPIRED'));
+            }
+        });
+        void login
+            .then((api) => this.completeZaloPersonalLogin(api))
+            .catch((error) => {
+            if (!settled)
+                rejectQr(error instanceof Error ? error : new Error(String(error)));
+            this.log.error('zalo personal: QR login failed', {
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        })
+            .finally(() => {
+            this.zaloQrAbort = undefined;
+        });
+        return qr;
+    }
+    async completeZaloPersonalLogin(api) {
+        const transport = new ZaloPersonalTransport({
+            api,
+            dataDir: this.ctx.dataDir,
+            log: this.log,
+            turnService: this.ctx.turnService,
+            subscribeTurnDone: makeTurnDoneSubscription(this.ctx.events),
+        });
+        await transport.start();
+        const status = transport.getStatus().status;
+        if (status !== 'connected' && status !== 'pending') {
+            await transport.stop();
+            throw new Error('ZALO_PERSONAL_LOGIN_FAILED');
+        }
+        const context = api.getContext();
+        this.credentials.zaloPersonal = {
+            imei: context.imei,
+            userAgent: context.userAgent,
+            language: context.language,
+            cookie: api.getCookie().serializeSync()?.cookies ?? [],
+        };
+        this.credentials.zaloMode = 'personal';
+        try {
+            this.persistCredentials();
+        }
+        catch (error) {
+            await transport.stop();
+            throw error;
+        }
+        await this.replaceTransport('zalo', transport);
+        this.log.info('zalo personal: QR connection completed');
+    }
+    startZaloOAuth(input) {
+        const configured = this.ctx.config.channels?.zalo;
+        const appId = input.appId?.trim() || configured?.appId?.trim() || this.credentials.zalo?.appId;
+        const appSecret = input.appSecret?.trim() || configured?.appSecret?.trim() || this.credentials.zalo?.appSecret;
+        if (!appId || !appSecret) {
+            throw new Error('NOT_CONFIGURED: Zalo OAuth requires appId and appSecret');
+        }
+        const redirect = new URL(input.redirectUri);
+        const local = ['localhost', '127.0.0.1', '::1'].includes(redirect.hostname);
+        if (redirect.pathname !== ZALO_CALLBACK_PATH ||
+            (redirect.protocol !== 'https:' && !(local && redirect.protocol === 'http:')) ||
+            redirect.username !== '' ||
+            redirect.password !== '' ||
+            redirect.hash !== '') {
+            throw new Error(`INVALID_ARGUMENT: redirectUri must be HTTPS and end with ${ZALO_CALLBACK_PATH}`);
+        }
+        const state = randomBytes(32).toString('base64url');
+        const codeVerifier = randomBytes(48).toString('base64url');
+        const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+        const expiresAt = Date.now() + OAUTH_TTL_MS;
+        for (const [key, value] of this.oauthSessions) {
+            if (value.expiresAt <= Date.now())
+                this.oauthSessions.delete(key);
+        }
+        this.oauthSessions.set(state, {
+            appId,
+            appSecret,
+            codeVerifier,
+            redirectUri: redirect.toString(),
+            expiresAt,
+        });
+        const authorizationUrl = new URL(ZALO_PERMISSION_URL);
+        authorizationUrl.search = new URLSearchParams({
+            app_id: appId,
+            redirect_uri: redirect.toString(),
+            code_challenge: codeChallenge,
+            state,
+        }).toString();
+        return {
+            status: 'authorization_required',
+            authorizationUrl: authorizationUrl.toString(),
+            expiresAt: new Date(expiresAt).toISOString(),
+        };
+    }
+    async refreshZaloIfNeeded() {
+        const current = this.credentials.zalo;
+        if (current === undefined || current.expiresAt > Date.now() + REFRESH_EARLY_MS)
+            return;
+        const response = await fetch(ZALO_TOKEN_URL, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                secret_key: current.appSecret,
+            },
+            body: new URLSearchParams({
+                app_id: current.appId,
+                refresh_token: current.refreshToken,
+                grant_type: 'refresh_token',
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok)
+            throw new Error(`ZALO_TOKEN_REFRESH_FAILED: HTTP ${response.status}`);
+        const tokens = parseZaloTokens((await response.json()));
+        const zalo = { ...current, ...tokens };
+        const transport = new ZaloTransport({ oaToken: zalo.accessToken }, this.log);
+        await transport.start();
+        if (transport.getStatus().status !== 'connected') {
+            throw new Error('ZALO_TOKEN_REFRESH_FAILED: credential check failed');
+        }
+        this.credentials.zalo = zalo;
+        this.persistCredentials();
+        await this.replaceTransport('zalo', transport);
+    }
+    persistCredentials() {
+        if (!this.masterKey) {
+            throw new Error('NOT_CONFIGURED: BOOMBOT_MASTER_KEY is required to store channel credentials');
+        }
+        writeCredentials(this.credentialPath, this.masterKey, this.credentials);
+    }
+    async replaceTransport(kind, replacement) {
+        const index = this.transports.findIndex((transport) => transport.kind === kind);
+        if (index === -1)
+            throw new Error(`UNKNOWN_CHANNEL: ${kind}`);
+        const previous = this.transports[index];
+        if (previous === undefined)
+            throw new Error(`UNKNOWN_CHANNEL: ${kind}`);
+        if (previous !== replacement)
+            await previous.stop();
+        this.transports[index] = replacement;
+    }
+    findTransportByKind(channel) {
+        const transport = this.transports.find((candidate) => candidate.kind === channel);
+        if (transport === undefined)
+            throw new Error(`UNKNOWN_CHANNEL: no channel "${channel}".`);
+        return transport;
+    }
+    findTransport(channel) {
+        const transport = this.findTransportByKind(channel);
+        if (transport.getStatus().status === 'disconnected') {
+            throw new Error(`NOT_CONFIGURED: channel "${channel}" is not configured.`);
+        }
+        return transport;
+    }
+}
+/**
+ * Wire the internal event bus to the Telegram transport's turn-reply hook.
+ * When the gateway publishes `agent.turn.done` (executor B, see
+ * `TURN_DONE_EVENT` in channels/common.ts), the payload is validated and
+ * forwarded; anything else is ignored.
+ */
+function makeTurnDoneSubscription(events) {
+    const subscribe = events.subscribe;
+    if (subscribe === undefined) {
+        return undefined;
+    }
+    return (handler) => subscribe(TURN_DONE_EVENT, (raw) => {
+        if (isTurnDonePayload(raw)) {
+            handler(raw);
+        }
+    });
+}
+/**
+ * Start every configured channel transport.
+ *
+ * Telegram runs its long-polling loop in the background (with backoff);
+ * WhatsApp/Discord/Slack expose signed HTTP webhooks. A transport that fails to
+ * start is left in `error` status and never blocks the others.
+ *
+ * @returns a stop function that shuts every transport down cleanly.
+ */
+export async function startChannelService(ctx) {
+    const channelConfigs = ctx.config.channels ?? {};
+    const credentials = readCredentials(join(ctx.dataDir, 'channels', 'credentials.json'), process.env['BOOMBOT_MASTER_KEY']?.trim() || undefined, ctx.log);
+    if (channelConfigs.zalo?.oaToken) {
+        credentials.zalo = undefined;
+        credentials.zaloMode = 'oa';
+    }
+    const transports = [];
+    const telegram = new TelegramTransport({
+        config: {
+            ...(channelConfigs.telegram ?? {}),
+            botToken: channelConfigs.telegram?.botToken ?? credentials.telegramBotToken,
+        },
+        dataDir: ctx.dataDir,
+        log: ctx.log,
+        turnService: ctx.turnService,
+        subscribeTurnDone: makeTurnDoneSubscription(ctx.events),
+    });
+    transports.push(telegram);
+    const inbound = {
+        turnService: ctx.turnService,
+        subscribeTurnDone: makeTurnDoneSubscription(ctx.events),
+    };
+    transports.push(new WhatsAppTransport(channelConfigs.whatsapp ?? {}, ctx.log, inbound));
+    transports.push(new DiscordTransport(channelConfigs.discord ?? {}, ctx.log, inbound));
+    transports.push(new SlackTransport(channelConfigs.slack ?? {}, ctx.log, inbound));
+    transports.push(credentials.zaloMode === 'personal' && credentials.zaloPersonal
+        ? new ZaloPersonalTransport({
+            credentials: credentials.zaloPersonal,
+            dataDir: ctx.dataDir,
+            log: ctx.log,
+            turnService: ctx.turnService,
+            subscribeTurnDone: makeTurnDoneSubscription(ctx.events),
+        })
+        : new ZaloTransport({
+            ...(channelConfigs.zalo ?? {}),
+            oaToken: channelConfigs.zalo?.oaToken ?? credentials.zalo?.accessToken,
+        }, ctx.log));
+    const messengerTransport = new MessengerTransport({
+        ...(channelConfigs.messenger ?? {}),
+        turnService: ctx.turnService,
+        subscribeTurnDone: makeTurnDoneSubscription(ctx.events),
+    }, ctx.log);
+    transports.push(messengerTransport);
+    transports.push(new TikTokTransport(channelConfigs.tiktok ?? {}, ctx.log));
+    for (const transport of transports) {
+        try {
+            await transport.start();
+        }
+        catch (err) {
+            // Never let one channel break gateway boot; it stays in error status.
+            ctx.log.error(`channel ${transport.kind}: start failed`, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Keep a stable, documented order for channel.list.
+    transports.sort((a, b) => DISPLAY_ORDER.indexOf(a.kind) - DISPLAY_ORDER.indexOf(b.kind));
+    const service = new DefaultChannelService(transports, ctx, credentials);
+    ctx.channelService = service;
+    activeService = service;
+    return async () => {
+        service.stopPendingConnections();
+        for (const transport of transports) {
+            try {
+                await transport.stop();
+            }
+            catch (err) {
+                ctx.log.error(`channel ${transport.kind}: stop failed`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    };
+}

package/dist/node_modules/@boombot/channels/tool.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCall, ToolDefinition, ToolResult } from '@boombot/core';
+export declare const CHANNEL_SEND_TOOL_NAME = "channel.send";
+export declare const channelSendDefinition: ToolDefinition;
+export interface ChannelSendService {
+    send(channel: string, target: string, text: string): Promise<void>;
+}
+export interface ChannelToolRegistry {
+    registerTool(definition: ToolDefinition, handler: (call: ToolCall, signal?: AbortSignal) => Promise<ToolResult> | ToolResult): void;
+}
+export declare function registerChannelTool(registry: ChannelToolRegistry, service: ChannelSendService): void;

package/dist/node_modules/@boombot/channels/tool.js

@@ -0,0 +1,46 @@
+export const CHANNEL_SEND_TOOL_NAME = 'channel.send';
+export const channelSendDefinition = {
+    name: CHANNEL_SEND_TOOL_NAME,
+    description: 'Send a text message through a configured messaging channel after operator approval.',
+    parameters: {
+        type: 'object',
+        properties: {
+            channel: { type: 'string', description: 'Configured channel kind, for example telegram.' },
+            target: { type: 'string', description: 'Channel-specific recipient or chat id.' },
+            text: { type: 'string', description: 'Message text to send.' },
+        },
+        required: ['channel', 'target', 'text'],
+        additionalProperties: false,
+    },
+};
+function requiredString(call, key) {
+    const value = call.arguments[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`'${key}' must be a non-empty string`);
+    }
+    return value.trim();
+}
+export function registerChannelTool(registry, service) {
+    registry.registerTool(channelSendDefinition, async (call) => {
+        try {
+            const channel = requiredString(call, 'channel');
+            const target = requiredString(call, 'target');
+            const text = requiredString(call, 'text');
+            await service.send(channel, target, text);
+            return {
+                callId: call.id,
+                name: call.name,
+                output: `Message sent through ${channel}.`,
+                error: false,
+            };
+        }
+        catch (error) {
+            return {
+                callId: call.id,
+                name: call.name,
+                output: `channel.send: ${error instanceof Error ? error.message : 'unknown error'}`,
+                error: true,
+            };
+        }
+    });
+}

package/dist/node_modules/@boombot/channels/transports/common/dedup.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MessageDeduplicator — sliding TTL cache preventing duplicate message processing.
+ * Direct concept from ChannelHub core.
+ */
+export declare class MessageDeduplicator {
+    private readonly ttlMs;
+    private readonly maxSize;
+    private readonly seen;
+    constructor(ttlMs?: number, // 10 minutes
+    maxSize?: number);
+    /**
+     * Returns true if the messageId is seen for the first time.
+     * Returns false if it has already been processed within the TTL window.
+     */
+    checkAndRecord(messageId: string): boolean;
+    private prune;
+}