@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/channels/transports/common/dedup.js

@@ -0,0 +1,42 @@
+/**
+ * MessageDeduplicator — sliding TTL cache preventing duplicate message processing.
+ * Direct concept from ChannelHub core.
+ */
+export class MessageDeduplicator {
+    ttlMs;
+    maxSize;
+    seen = new Map();
+    constructor(ttlMs = 600_000, // 10 minutes
+    maxSize = 5_000) {
+        this.ttlMs = ttlMs;
+        this.maxSize = maxSize;
+    }
+    /**
+     * 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) {
+        const now = Date.now();
+        this.prune(now);
+        if (this.seen.has(messageId)) {
+            return false; // Duplicate!
+        }
+        if (this.seen.size >= this.maxSize) {
+            const oldestKey = this.seen.keys().next().value;
+            if (oldestKey)
+                this.seen.delete(oldestKey);
+        }
+        this.seen.set(messageId, now);
+        return true;
+    }
+    prune(now) {
+        for (const [id, timestamp] of this.seen.entries()) {
+            if (now - timestamp > this.ttlMs) {
+                this.seen.delete(id);
+            }
+            else {
+                break; // Map preserves insertion order, early exit
+            }
+        }
+    }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * HandoffManager — pauses automated bot responses when a human agent steps in.
+ * Ported concept from ChannelHub core.
+ */
+export declare class HandoffManager {
+    private readonly mutedUntil;
+    /**
+     * Mutes automated responses for `chatKey` (e.g. "telegram:12345") for `durationMs`.
+     */
+    takeover(chatKey: string, durationMs?: number): void;
+    /**
+     * Resumes automated bot responses immediately for `chatKey`.
+     */
+    resume(chatKey: string): void;
+    /**
+     * Checks if bot should stay quiet for `chatKey`.
+     */
+    isHandedOff(chatKey: string): boolean;
+}

package/dist/node_modules/@boombot/channels/transports/common/handoff.js

@@ -0,0 +1,32 @@
+/**
+ * HandoffManager — pauses automated bot responses when a human agent steps in.
+ * Ported concept from ChannelHub core.
+ */
+export class HandoffManager {
+    mutedUntil = new Map();
+    /**
+     * Mutes automated responses for `chatKey` (e.g. "telegram:12345") for `durationMs`.
+     */
+    takeover(chatKey, durationMs = 30 * 60 * 1000) {
+        this.mutedUntil.set(chatKey, Date.now() + durationMs);
+    }
+    /**
+     * Resumes automated bot responses immediately for `chatKey`.
+     */
+    resume(chatKey) {
+        this.mutedUntil.delete(chatKey);
+    }
+    /**
+     * Checks if bot should stay quiet for `chatKey`.
+     */
+    isHandedOff(chatKey) {
+        const expiresAt = this.mutedUntil.get(chatKey);
+        if (!expiresAt)
+            return false;
+        if (Date.now() > expiresAt) {
+            this.mutedUntil.delete(chatKey);
+            return false;
+        }
+        return true;
+    }
+}

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

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './dedup.js';
+export * from './handoff.js';

package/dist/node_modules/@boombot/channels/transports/common/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './dedup.js';
+export * from './handoff.js';

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

@@ -0,0 +1,99 @@
+import type { ChannelKind } from '@boombot/protocol';
+/** Runtime status of a channel transport, as seen by `channel.list`. */
+export type ChannelRuntimeStatus = 'connected' | 'disconnected' | 'error' | 'pending';
+/** Minimal structured logger the transports need. */
+export interface ChannelLogger {
+    info(message: string, meta?: Readonly<Record<string, unknown>>): void;
+    warn(message: string, meta?: Readonly<Record<string, unknown>>): void;
+    error(message: string, meta?: Readonly<Record<string, unknown>>): void;
+}
+/** Subset of the agent turn service used by inbound channel messages. */
+export interface TurnSubmitter {
+    submit(input: {
+        readonly input: string;
+        readonly channel: string;
+        readonly replyTo: string;
+    }): Promise<{
+        readonly turnId: string;
+        readonly sessionId: string;
+    }>;
+}
+/**
+ * Internal event-bus surface the channel service needs.
+ * `subscribe` is optional: the gateway's event bus (executor A) may or may
+ * not expose it yet. When present, the Telegram transport subscribes to
+ * {@link TURN_DONE_EVENT} to reply turn results back to the chat.
+ */
+export interface ChannelEventBus {
+    publish(type: string, payload: unknown): void;
+    subscribe?(type: string, handler: (payload: unknown) => void): () => void;
+}
+/**
+ * Name of the event carrying a finished agent turn.
+ *
+ * PROPOSAL for the coordinator (executor B owns the agent runtime):
+ * the gateway should publish `agent.turn.done` on the internal event bus
+ * when a turn completes, with a payload shaped like {@link TurnDonePayload}.
+ * This mirrors the existing SSE stream event `agent.turn.done`
+ * (packages/gateway-protocol `events.ts`) whose `output` field already
+ * carries the final assistant text — the internal event adds `channel` /
+ * `replyTo` so the channel service can route the reply. Until executor B
+ * implements it, the Telegram transport correlates via its own
+ * `pendingReplies` map (turnId → chatId recorded at submit time).
+ */
+export declare const TURN_DONE_EVENT = "agent.turn.done";
+/** Payload of {@link TURN_DONE_EVENT} on the internal event bus. */
+export interface TurnDonePayload {
+    readonly turnId: string;
+    readonly status: string;
+    /** Final assistant text (mirrors the SSE `agent.turn.done` `output`). */
+    readonly output?: string;
+    /** Error text when the turn failed. */
+    readonly error?: string;
+    /** Originating channel, e.g. 'telegram' (proposed addition). */
+    readonly channel?: string;
+    /** Where to send the reply, e.g. the Telegram chat id (proposed). */
+    readonly replyTo?: string;
+}
+/** Raw HTTP request passed to a platform webhook before parsing/signature checks. */
+export interface ChannelWebhookRequest {
+    readonly method: 'GET' | 'POST';
+    readonly rawBody: Buffer;
+    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    readonly query: URLSearchParams;
+}
+export interface ChannelWebhookResponse {
+    readonly status: number;
+    readonly contentType?: string;
+    readonly body?: string;
+}
+export interface InboundTransportOptions {
+    readonly turnService?: TurnSubmitter;
+    readonly subscribeTurnDone?: (handler: (payload: TurnDonePayload) => void) => () => void;
+}
+/** Type guard for {@link TurnDonePayload} (event bus carries `unknown`). */
+export declare function isTurnDonePayload(value: unknown): value is TurnDonePayload;
+/**
+ * A channel transport: owns the platform connection for one channel kind.
+ * Lifecycle: `start()` once at gateway boot, `stop()` on shutdown.
+ */
+export interface ChannelTransport {
+    readonly kind: ChannelKind;
+    readonly displayName: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Outbound send. Throws on delivery failure (never leaks secrets). */
+    send(target: string, text: string): Promise<void>;
+    handleWebhook?(request: ChannelWebhookRequest): Promise<ChannelWebhookResponse>;
+    getStatus(): {
+        status: ChannelRuntimeStatus;
+        detail?: string;
+    };
+}
+/**
+ * Read a JSON file, returning `undefined` when missing or unparseable.
+ * Used for transport state persisted under the gateway data dir.
+ */
+export declare function readJsonFile<T>(path: string): T | undefined;
+/** Write a JSON file, creating parent directories as needed. */
+export declare function writeJsonFile(path: string, value: unknown): void;

package/dist/node_modules/@boombot/channels/transports/common/types.js

@@ -0,0 +1,54 @@
+/**
+ * Shared contracts for the gateway channel transports
+ * (`channels/src/transports/*`).
+ *
+ * These transports are the gateway-side runtime for messaging channels.
+ * They use the global `fetch` and Node builtins only — no extra
+ * dependencies, no platform SDKs. They must NEVER import from
+ * `extensions/*` (boundary: apps never import extensions); the extension
+ * adapters (`extensions/<name>/src`) remain the plugin-facing `ChannelAdapter`
+ * surface.
+ *
+ * Secrets (bot tokens, API keys): read from config, sent once per request,
+ * never logged, never embedded in error text (SECURITY.md §5).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Name of the event carrying a finished agent turn.
+ *
+ * PROPOSAL for the coordinator (executor B owns the agent runtime):
+ * the gateway should publish `agent.turn.done` on the internal event bus
+ * when a turn completes, with a payload shaped like {@link TurnDonePayload}.
+ * This mirrors the existing SSE stream event `agent.turn.done`
+ * (packages/gateway-protocol `events.ts`) whose `output` field already
+ * carries the final assistant text — the internal event adds `channel` /
+ * `replyTo` so the channel service can route the reply. Until executor B
+ * implements it, the Telegram transport correlates via its own
+ * `pendingReplies` map (turnId → chatId recorded at submit time).
+ */
+export const TURN_DONE_EVENT = 'agent.turn.done';
+/** Type guard for {@link TurnDonePayload} (event bus carries `unknown`). */
+export function isTurnDonePayload(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.turnId === 'string');
+}
+/**
+ * Read a JSON file, returning `undefined` when missing or unparseable.
+ * Used for transport state persisted under the gateway data dir.
+ */
+export function readJsonFile(path) {
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write a JSON file, creating parent directories as needed. */
+export function writeJsonFile(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value), 'utf8');
+}

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

@@ -0,0 +1,2 @@
+/** Re-export from modular common package */
+export * from './common/index.js';

package/dist/node_modules/@boombot/channels/transports/common.js

@@ -0,0 +1,2 @@
+/** Re-export from modular common package */
+export * from './common/index.js';

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

@@ -0,0 +1 @@
+export { MessageDeduplicator } from '../common/dedup.js';

package/dist/node_modules/@boombot/channels/transports/dedup/index.js

@@ -0,0 +1 @@
+export { MessageDeduplicator } from '../common/dedup.js';

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

@@ -0,0 +1,2 @@
+/** Re-export from modular common package */
+export * from './common/dedup.js';

package/dist/node_modules/@boombot/channels/transports/dedup.js

@@ -0,0 +1,2 @@
+/** Re-export from modular common package */
+export * from './common/dedup.js';

package/dist/node_modules/@boombot/channels/transports/discord/index.d.ts

@@ -0,0 +1 @@
+export * from './transport.js';

package/dist/node_modules/@boombot/channels/transports/discord/index.js

@@ -0,0 +1 @@
+export * from './transport.js';

package/dist/node_modules/@boombot/channels/transports/discord/transport.d.ts

@@ -0,0 +1,36 @@
+import type { ChannelKind } from '@boombot/protocol';
+import { type ChannelLogger, type ChannelRuntimeStatus, type ChannelTransport, type ChannelWebhookRequest, type ChannelWebhookResponse, type InboundTransportOptions } from '../common/index.js';
+export interface DiscordTransportConfig {
+    readonly enabled?: boolean;
+    readonly botToken?: string;
+    readonly publicKey?: string;
+    readonly guildId?: string;
+    readonly allowlistChatIds?: readonly string[];
+}
+export declare class DiscordTransport implements ChannelTransport {
+    readonly kind: ChannelKind;
+    readonly displayName = "Discord";
+    private readonly enabled;
+    private readonly botToken;
+    private readonly publicKey;
+    private readonly allowlist;
+    private readonly log;
+    private readonly turnService;
+    private readonly subscribeTurnDone;
+    private readonly pendingReplies;
+    private readonly deduplicator;
+    private unsubscribeTurnDone;
+    private status;
+    private statusDetail;
+    constructor(config: DiscordTransportConfig, log: ChannelLogger, inbound?: InboundTransportOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getStatus(): {
+        status: ChannelRuntimeStatus;
+        detail?: string;
+    };
+    handleWebhook(request: ChannelWebhookRequest): Promise<ChannelWebhookResponse>;
+    send(target: string, text: string): Promise<void>;
+    private onTurnDone;
+    private followUp;
+}

package/dist/node_modules/@boombot/channels/transports/discord/transport.js

@@ -0,0 +1,199 @@
+import { createPublicKey, verify } from 'node:crypto';
+import {} from '../common/index.js';
+import { MessageDeduplicator } from '../common/index.js';
+const DISCORD_API_BASE = 'https://discord.com/api/v10';
+const MAX_TEXT_LENGTH = 2000;
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+export class DiscordTransport {
+    kind = 'discord';
+    displayName = 'Discord';
+    enabled;
+    botToken;
+    publicKey;
+    allowlist;
+    log;
+    turnService;
+    subscribeTurnDone;
+    pendingReplies = new Map();
+    deduplicator = new MessageDeduplicator();
+    unsubscribeTurnDone;
+    status = 'disconnected';
+    statusDetail = 'NOT_CONFIGURED';
+    constructor(config, log, inbound = {}) {
+        this.enabled = config.enabled !== false;
+        this.botToken = config.botToken?.trim() || undefined;
+        const key = config.publicKey?.trim();
+        this.publicKey = key !== undefined && /^[0-9a-f]{64}$/iu.test(key)
+            ? Buffer.from(key, 'hex')
+            : undefined;
+        this.allowlist = new Set(config.allowlistChatIds ?? []);
+        this.log = log;
+        this.turnService = inbound.turnService;
+        this.subscribeTurnDone = inbound.subscribeTurnDone;
+    }
+    async start() {
+        if (!this.enabled) {
+            this.statusDetail = 'DISABLED';
+            return;
+        }
+        this.unsubscribeTurnDone ??= this.subscribeTurnDone?.((payload) => this.onTurnDone(payload));
+        if (this.botToken === undefined) {
+            this.statusDetail = this.publicKey === undefined ? 'NOT_CONFIGURED' : 'INBOUND_ONLY';
+            return;
+        }
+        try {
+            const response = await fetch(`${DISCORD_API_BASE}/users/@me`, {
+                headers: { authorization: `Bot ${this.botToken}` },
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!response.ok) {
+                const data = (await response.json());
+                throw new Error(data.message ?? `HTTP ${response.status}`);
+            }
+            this.status = 'connected';
+            this.statusDetail = undefined;
+            this.log.info('discord: connected');
+        }
+        catch (error) {
+            this.status = 'error';
+            this.statusDetail = error instanceof Error ? error.message : 'CONNECT_FAILED';
+            this.log.error('discord: credential check failed', { detail: this.statusDetail });
+        }
+    }
+    async stop() {
+        this.unsubscribeTurnDone?.();
+        this.unsubscribeTurnDone = undefined;
+        this.pendingReplies.clear();
+        if (this.status === 'connected') {
+            this.status = 'disconnected';
+            this.statusDetail = 'STOPPED';
+        }
+    }
+    getStatus() {
+        return this.statusDetail === undefined
+            ? { status: this.status }
+            : { status: this.status, detail: this.statusDetail };
+    }
+    async handleWebhook(request) {
+        if (request.method !== 'POST')
+            return { status: 405 };
+        if (!this.enabled || this.publicKey === undefined)
+            return { status: 503 };
+        const signatureValue = request.headers['x-signature-ed25519'];
+        const timestampValue = request.headers['x-signature-timestamp'];
+        const signature = typeof signatureValue === 'string' ? signatureValue : (signatureValue?.[0] ?? '');
+        const timestamp = typeof timestampValue === 'string' ? timestampValue : (timestampValue?.[0] ?? '');
+        if (!/^[0-9a-f]{128}$/iu.test(signature) || timestamp === '')
+            return { status: 401 };
+        const key = createPublicKey({
+            key: Buffer.concat([ED25519_SPKI_PREFIX, this.publicKey]),
+            format: 'der',
+            type: 'spki',
+        });
+        if (!verify(null, Buffer.concat([Buffer.from(timestamp), request.rawBody]), key, Buffer.from(signature, 'hex'))) {
+            return { status: 401 };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(request.rawBody.toString('utf8'));
+        }
+        catch {
+            return { status: 400 };
+        }
+        if (!isRecord(parsed))
+            return { status: 400 };
+        const body = parsed;
+        if (body['type'] === 1)
+            return json({ type: 1 });
+        const channelId = typeof body['channel_id'] === 'string' ? body['channel_id'] : '';
+        const applicationId = typeof body['application_id'] === 'string' ? body['application_id'] : '';
+        const token = typeof body['token'] === 'string' ? body['token'] : '';
+        const interactionId = typeof body['id'] === 'string' ? body['id'] : '';
+        const data = body['data'];
+        const input = isRecord(data) ? firstStringOption(data['options']) : undefined;
+        if (body['type'] !== 2 || channelId === '' || applicationId === '' || token === '' ||
+            interactionId === '' || input === undefined || input.trim() === '')
+            return json({ type: 4, data: { content: 'A non-empty text option is required.', flags: 64 } });
+        if (!this.allowlist.has(channelId) || this.turnService === undefined) {
+            return json({ type: 4, data: { content: 'This channel is not allowed.', flags: 64 } });
+        }
+        if (!this.deduplicator.checkAndRecord(interactionId))
+            return json({ type: 5 });
+        try {
+            const result = await this.turnService.submit({ input, channel: 'discord', replyTo: channelId });
+            this.pendingReplies.set(result.turnId, { applicationId, token });
+        }
+        catch (error) {
+            this.log.error('discord: submit failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return json({ type: 4, data: { content: 'Agent unavailable.', flags: 64 } });
+        }
+        return json({ type: 5 });
+    }
+    async send(target, text) {
+        if (this.botToken === undefined)
+            throw new Error('NOT_CONFIGURED: discord botToken missing');
+        const channelId = target.trim();
+        if (channelId === '' || text.trim() === '')
+            throw new Error('INVALID_ARGUMENT: target/text empty');
+        const points = Array.from(text);
+        for (let index = 0; index < points.length; index += MAX_TEXT_LENGTH) {
+            const response = await fetch(`${DISCORD_API_BASE}/channels/${encodeURIComponent(channelId)}/messages`, {
+                method: 'POST',
+                headers: { authorization: `Bot ${this.botToken}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ content: points.slice(index, index + MAX_TEXT_LENGTH).join('') }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!response.ok) {
+                const data = await response.json().catch(() => undefined);
+                throw new Error(`SEND_FAILED: ${data?.message ?? `HTTP ${response.status}`}`);
+            }
+        }
+    }
+    onTurnDone(payload) {
+        const pending = this.pendingReplies.get(payload.turnId);
+        if (pending === undefined)
+            return;
+        this.pendingReplies.delete(payload.turnId);
+        const content = payload.status === 'completed'
+            ? (payload.output?.trim() || '(empty response)')
+            : `Turn failed${payload.error ? `: ${payload.error}` : ''}.`;
+        void this.followUp(pending, content).catch((error) => this.log.error('discord: reply failed', {
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    }
+    async followUp(pending, text) {
+        const points = Array.from(text);
+        for (let index = 0; index < points.length; index += MAX_TEXT_LENGTH) {
+            const response = await fetch(`${DISCORD_API_BASE}/webhooks/${encodeURIComponent(pending.applicationId)}/${encodeURIComponent(pending.token)}`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ content: points.slice(index, index + MAX_TEXT_LENGTH).join('') }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+        }
+    }
+}
+function firstStringOption(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    for (const option of value) {
+        if (!isRecord(option))
+            continue;
+        if (typeof option['value'] === 'string')
+            return option['value'];
+        const nested = firstStringOption(option['options']);
+        if (nested !== undefined)
+            return nested;
+    }
+    return undefined;
+}
+function json(body) {
+    return { status: 200, contentType: 'application/json; charset=utf-8', body: JSON.stringify(body) };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/node_modules/@boombot/channels/transports/discord.d.ts

@@ -0,0 +1,2 @@
+/** Re-export from modular discord package */
+export * from './discord/index.js';

package/dist/node_modules/@boombot/channels/transports/discord.js

@@ -0,0 +1,2 @@
+/** Re-export from modular discord package */
+export * from './discord/index.js';

package/dist/node_modules/@boombot/channels/transports/handoff.d.ts

@@ -0,0 +1,2 @@
+/** Re-export from modular common package */
+export * from './common/handoff.js';

package/dist/node_modules/@boombot/channels/transports/handoff.js

@@ -0,0 +1,2 @@
+/** Re-export from modular common package */
+export * from './common/handoff.js';

package/dist/node_modules/@boombot/channels/transports/messenger/index.d.ts

@@ -0,0 +1 @@
+export * from './transport.js';

package/dist/node_modules/@boombot/channels/transports/messenger/index.js

@@ -0,0 +1 @@
+export * from './transport.js';

package/dist/node_modules/@boombot/channels/transports/messenger/transport.d.ts

@@ -0,0 +1,34 @@
+import type { ChannelKind } from '@boombot/protocol';
+import { type ChannelLogger, type ChannelRuntimeStatus, type ChannelTransport, type ChannelWebhookRequest, type ChannelWebhookResponse, type InboundTransportOptions } from '../common/index.js';
+export interface MessengerTransportConfig extends InboundTransportOptions {
+    readonly enabled?: boolean;
+    readonly pageAccessToken?: string;
+    readonly appSecret?: string;
+    readonly verifyToken?: string;
+    readonly allowlistChatIds?: readonly string[];
+}
+export declare class MessengerTransport implements ChannelTransport {
+    readonly kind: ChannelKind;
+    readonly displayName = "Messenger";
+    private readonly enabled;
+    private readonly pageAccessToken;
+    private readonly appSecret;
+    private readonly verifyToken;
+    private readonly allowlist;
+    private readonly deduplicator;
+    private readonly pendingReplies;
+    private readonly log;
+    private status;
+    private statusDetail;
+    private readonly turnService;
+    private unsubscribeTurnDone;
+    constructor(config: MessengerTransportConfig, log: ChannelLogger);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    handleWebhook(request: ChannelWebhookRequest): Promise<ChannelWebhookResponse>;
+    send(target: string, text: string): Promise<void>;
+    getStatus(): {
+        status: ChannelRuntimeStatus;
+        detail?: string;
+    };
+}