@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/gateway/turns/vision-tool.js

@@ -0,0 +1,120 @@
+import sharp from 'sharp';
+import { extractImageText, prepareImage } from '../services/image-pipeline.js';
+import { validateImageSource } from '../services/vision-payload.js';
+export const VISION_ANALYZE_TOOL_NAME = 'vision_analyze';
+export const visionAnalyzeDefinition = {
+    name: VISION_ANALYZE_TOOL_NAME,
+    description: 'Inspect an image locally with fast Sharp preprocessing, high-res crop/zoom, and local OCR. Use whenever the user shares an image, provides a screenshot, or requests reading text/diagrams/details.',
+    parameters: {
+        type: 'object',
+        properties: {
+            imageUrl: {
+                type: 'string',
+                description: 'Image data URL (data:image/*;base64). Remote URLs and filesystem paths are not accepted by this tool.'
+            },
+            question: {
+                type: 'string',
+                description: 'Question or instruction about what to analyze or extract from the image.',
+            },
+            region: {
+                type: 'array',
+                items: { type: 'number' },
+                description: 'Optional [left, top, right, bottom] bounding box coordinates in original pixels to crop and zoom without downscaling.',
+            },
+            mode: {
+                type: 'string',
+                enum: ['auto', 'ocr', 'metadata'],
+                description: 'Processing mode: auto (OCR if text-oriented), ocr (force local OCR), or metadata (dimensions and format only).',
+            },
+            language: {
+                type: 'string',
+                description: 'Optional OCR language code (e.g. eng, vie, eng+vie). Defaults to eng.',
+            },
+        },
+        required: ['imageUrl', 'question'],
+        additionalProperties: false,
+    },
+};
+/** Fetch or load bytes from remote URLs, data URLs, or local filesystem paths. */
+async function resolveImageBytes(source) {
+    const trimmed = source.trim();
+    if (trimmed.startsWith('data:')) {
+        validateImageSource(trimmed);
+        const commaIndex = trimmed.indexOf(',');
+        if (commaIndex === -1)
+            throw new Error('Malformed data URL.');
+        return Buffer.from(trimmed.slice(commaIndex + 1), 'base64');
+    }
+    throw new Error('vision_analyze accepts only data:image/*;base64 URLs.');
+}
+export function createVisionToolExecutor() {
+    return async (args) => {
+        try {
+            const originalBytes = await resolveImageBytes(args.imageUrl);
+            const pipeline = sharp(originalBytes, { failOn: 'error' });
+            const meta = await pipeline.metadata();
+            const origWidth = meta.width ?? 0;
+            const origHeight = meta.height ?? 0;
+            let targetBytes = originalBytes;
+            let isCropped = false;
+            if (Array.isArray(args.region) && args.region.length === 4) {
+                const coords = args.region.map(Number);
+                if (!coords.every(Number.isFinite))
+                    throw new Error('Region coordinates must be finite numbers.');
+                const x1 = Math.max(0, Math.round(coords[0]));
+                const y1 = Math.max(0, Math.round(coords[1]));
+                const x2 = Math.max(0, Math.round(coords[2]));
+                const y2 = Math.max(0, Math.round(coords[3]));
+                const left = Math.min(x1, x2);
+                const top = Math.min(y1, y2);
+                const width = Math.min(origWidth - left, Math.abs(x2 - x1));
+                const height = Math.min(origHeight - top, Math.abs(y2 - y1));
+                if (width > 0 && height > 0) {
+                    targetBytes = await sharp(originalBytes)
+                        .extract({ left, top, width, height })
+                        .png()
+                        .toBuffer();
+                    isCropped = true;
+                }
+            }
+            const prepared = await prepareImage(targetBytes, { thumbnailWidth: 1536 });
+            const isOcrRequested = args.mode === 'ocr' || (args.mode !== 'metadata' && /read|text|invoice|number|code|ocr|chữ|số/i.test(args.question));
+            let ocrText = '';
+            if (isOcrRequested) {
+                const isVietnamese = /[àáạảãâầấậẩẫăằắặẳẵèéẹẻẽêềếệểễìíịỉĩòóọỏõôồốộổỗơờớợởỡùúụủũưừứựửữỳýỵỷỹđ]/i.test(args.question) ||
+                    /tiếng việt|tieng viet|việt|hóa đơn/i.test(args.question);
+                const language = args.language ?? (isVietnamese ? 'vie' : 'eng');
+                ocrText = await extractImageText(targetBytes, language);
+            }
+            const summary = {
+                question: args.question,
+                originalDimensions: { width: origWidth, height: origHeight },
+                cropped: isCropped,
+                processedDimensions: { width: prepared.width, height: prepared.height },
+                sha256: prepared.sha256,
+                extractedText: ocrText !== '' ? ocrText : undefined,
+            };
+            return { output: JSON.stringify(summary, null, 2), error: false };
+        }
+        catch (err) {
+            return {
+                output: `vision_analyze error: ${err instanceof Error ? err.message : String(err)}`,
+                error: true,
+            };
+        }
+    };
+}
+export function registerVisionTool(registry) {
+    const executor = createVisionToolExecutor();
+    registry.registerTool(visionAnalyzeDefinition, async (call, signal) => {
+        signal?.throwIfAborted();
+        const args = call.arguments;
+        const res = await executor(args);
+        return {
+            callId: call.id,
+            name: call.name,
+            output: res.output,
+            error: res.error,
+        };
+    });
+}

package/dist/gateway/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * Minimal command registry surface.
+ * Executor A's real registry must satisfy this structurally
+ * (`register(type, handler)`); extra dispatch features are fine.
+ */
+export interface ChannelCommandRegistry {
+    register(type: string, handler: (payload: unknown) => Promise<unknown>): void;
+}
+export declare function registerChannelHandlers(registry: ChannelCommandRegistry): void;

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

@@ -0,0 +1,109 @@
+/**
+ * Command handlers for channel commands (phase 2).
+ *
+ * Registers:
+ * - `channel.list` — real transport status, conforming to the
+ *   `channelSchema` wire contract (status ∈ connected/disconnected/error;
+ *   missing creds map to `disconnected`).
+ * - `channel.connect` — validates Telegram, starts Zalo OA OAuth, or returns a
+ *   Zalo Personal login QR.
+ * - `channel.pair` — new (additive). Creates an `BOOM-######` pairing code
+ *   for a channel; response `{ code }`. Schema lives in
+ *   `packages/gateway-protocol/src/commands-channels.ts`
+ *   (`EXTRA_COMMAND_DEFS`); the payload is re-validated here with the same
+ *   rules so this file does not depend on the protocol barrel re-export
+ *   (which the coordinator adds to `index.ts`).
+ * - `channel.unpair` — new (additive). Removes a chat from a channel's
+ *   allowlist; response `{ ok: true }`.
+ *
+ * Integration contract (for executor A/B, who own the server dispatch):
+ * `registry.register(type, handler)` wires a command type to an async
+ * handler receiving the validated payload. The service instance comes from
+ * `getChannelService()` — call `startChannelService()` before
+ * `registerChannelHandlers()`. Payload validation errors throw
+ * `ProtocolError('INVALID_PAYLOAD')`, matching `parseCommand` semantics.
+ */
+import { CHANNEL_EXTRA_COMMAND_DEFS, ProtocolError, } from '@boombot/protocol';
+import { getChannelService, } from './service.js';
+function requireChannelService() {
+    const service = getChannelService();
+    if (service === undefined) {
+        throw new Error('ChannelService has not been started — call startChannelService() before registerChannelHandlers().');
+    }
+    return service;
+}
+function asRecord(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new ProtocolError('INVALID_PAYLOAD', 'Payload must be an object.', { payload });
+    }
+    return payload;
+}
+/** Mirrors the `channel.pair` payload schema in EXTRA_COMMAND_DEFS. */
+function parsePairPayload(payload) {
+    const record = asRecord(payload);
+    const channel = record['channel'];
+    if (typeof channel !== 'string' || channel.trim() === '') {
+        throw new ProtocolError('INVALID_PAYLOAD', 'channel.pair requires payload { channel: string }.', { payload });
+    }
+    return { channel: channel.trim() };
+}
+function parseConnectPayload(payload) {
+    const parsed = CHANNEL_EXTRA_COMMAND_DEFS['channel.connect'].payload.safeParse(payload);
+    if (!parsed.success) {
+        throw new ProtocolError('INVALID_PAYLOAD', 'Invalid channel.connect payload.', {
+            issues: parsed.error.issues,
+        });
+    }
+    return parsed.data;
+}
+/** Mirrors the `channel.unpair` payload schema in EXTRA_COMMAND_DEFS. */
+function parseUnpairPayload(payload) {
+    const record = asRecord(payload);
+    const channel = record['channel'];
+    const target = record['target'];
+    if (typeof channel !== 'string' || channel.trim() === '') {
+        throw new ProtocolError('INVALID_PAYLOAD', 'channel.unpair requires payload { channel: string, target: string }.', { payload });
+    }
+    if (typeof target !== 'string' || target.trim() === '') {
+        throw new ProtocolError('INVALID_PAYLOAD', 'channel.unpair requires payload { channel: string, target: string }.', { payload });
+    }
+    return { channel: channel.trim(), target: target.trim() };
+}
+export function registerChannelHandlers(registry) {
+    // Transports throw plain `Error("NOT_CONFIGURED: <reason>")` when the
+    // channel isn't set up. Translate to a coded ProtocolError so the wire
+    // carries NOT_CONFIGURED (503) instead of a generic 500.
+    const guarded = (handler) => {
+        return async (payload) => {
+            try {
+                return await handler(payload);
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.startsWith('NOT_CONFIGURED')) {
+                    throw new ProtocolError('NOT_CONFIGURED', error.message);
+                }
+                if (error instanceof Error && error.message.startsWith('INVALID_ARGUMENT')) {
+                    throw new ProtocolError('INVALID_PAYLOAD', error.message);
+                }
+                throw error;
+            }
+        };
+    };
+    registry.register('channel.list', async () => {
+        const channels = await requireChannelService().list();
+        return { channels };
+    });
+    registry.register('channel.connect', guarded(async (payload) => {
+        return requireChannelService().connect(parseConnectPayload(payload));
+    }));
+    registry.register('channel.pair', guarded(async (payload) => {
+        const { channel } = parsePairPayload(payload);
+        const code = await requireChannelService().pair(channel);
+        return { code };
+    }));
+    registry.register('channel.unpair', guarded(async (payload) => {
+        const { channel, target } = parseUnpairPayload(payload);
+        await requireChannelService().unpair(channel, target);
+        return { ok: true };
+    }));
+}

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

@@ -0,0 +1,12 @@
+export * from './handlers.js';
+export * from './service.js';
+export * from './tool.js';
+export * from './transports/common.js';
+export * from './transports/discord.js';
+export * from './transports/messenger.js';
+export * from './transports/slack.js';
+export * from './transports/telegram.js';
+export * from './transports/tiktok.js';
+export * from './transports/whatsapp.js';
+export * from './transports/zalo-personal.js';
+export * from './transports/zalo.js';

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

@@ -0,0 +1,12 @@
+export * from './handlers.js';
+export * from './service.js';
+export * from './tool.js';
+export * from './transports/common.js';
+export * from './transports/discord.js';
+export * from './transports/messenger.js';
+export * from './transports/slack.js';
+export * from './transports/telegram.js';
+export * from './transports/tiktok.js';
+export * from './transports/whatsapp.js';
+export * from './transports/zalo-personal.js';
+export * from './transports/zalo.js';

package/dist/node_modules/@boombot/channels/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@boombot/channels",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  }
+}

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

@@ -0,0 +1,62 @@
+import { type ChannelInfo, type CommandPayload, type CommandResponse } from '@boombot/protocol';
+import { type ChannelEventBus, type ChannelLogger, type ChannelWebhookRequest, type ChannelWebhookResponse, type TurnSubmitter } from './transports/common.js';
+import { type DiscordTransportConfig } from './transports/discord.js';
+import { type MessengerTransportConfig } from './transports/messenger.js';
+import { type SlackTransportConfig } from './transports/slack.js';
+import { type TelegramTransportConfig } from './transports/telegram.js';
+import { type TikTokTransportConfig } from './transports/tiktok.js';
+import { type WhatsAppTransportConfig } from './transports/whatsapp.js';
+import { type ZaloTransportConfig } from './transports/zalo.js';
+/** Per-channel config block, read from the gateway config file. */
+export interface ChannelsConfig {
+    readonly telegram?: TelegramTransportConfig;
+    readonly whatsapp?: WhatsAppTransportConfig;
+    readonly discord?: DiscordTransportConfig;
+    readonly slack?: SlackTransportConfig;
+    readonly zalo?: ZaloTransportConfig;
+    readonly messenger?: MessengerTransportConfig;
+    readonly tiktok?: TikTokTransportConfig;
+}
+/**
+ * Minimal context the channel service needs.
+ * The gateway's real `ServiceContext` (executor A) must satisfy this
+ * structurally; extra fields are fine.
+ */
+export interface ChannelServiceContext {
+    readonly config: {
+        readonly channels?: ChannelsConfig;
+    };
+    readonly dataDir: string;
+    readonly log: ChannelLogger;
+    readonly events: ChannelEventBus;
+    readonly turnService?: TurnSubmitter;
+    /** Attached by `startChannelService`. */
+    channelService?: ChannelService;
+}
+/** Operations exposed to command handlers and (later) agent tools. */
+export interface ChannelService {
+    list(): Promise<ChannelInfo[]>;
+    send(channel: string, target: string, text: string): Promise<void>;
+    handleWebhook(channel: string, request: ChannelWebhookRequest): Promise<ChannelWebhookResponse>;
+    connect(input: CommandPayload<'channel.connect'>): Promise<CommandResponse<'channel.connect'>>;
+    completeZaloOAuth(params: URLSearchParams): Promise<void>;
+    /**
+     * Create a pairing code (`BOOM-######`) for a channel.
+     * Supported by Telegram and Zalo Personal; other channels throw.
+     */
+    pair(channel: string): Promise<string>;
+    /** Remove `target` from a channel's allowlist. */
+    unpair(channel: string, target: string): Promise<void>;
+}
+/** The service started by `startChannelService`, if any. */
+export declare function getChannelService(): ChannelService | undefined;
+/**
+ * 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 declare function startChannelService(ctx: ChannelServiceContext): Promise<() => Promise<void>>;