@adonis-agora/agent 0.62.0 → 0.63.0

package/dist/src/channels/adapters/telegram.js

@@ -0,0 +1,196 @@
+import { ChannelDeliveryError, ChannelMediaTooLargeError, fetchBytes, postJson, record, safeEqual, sizeOf, str, } from '../http.js';
+import { unescapeTelegramMarkdown } from '../markdown.js';
+/** Telegram's limits: message text, buttons we put in one keyboard. */
+const MAX_TEXT = 4096;
+const MAX_BUTTONS = 8;
+/** The file a message carries: the largest photo size, a document, a voice note, audio, video, a sticker. */
+function mediaOf(message) {
+    const photo = Array.isArray(message.photo) ? record(message.photo.at(-1)) : undefined;
+    const candidates = [
+        ['image', photo, 'image/jpeg'],
+        ['document', record(message.document), undefined],
+        ['audio', record(message.voice), 'audio/ogg'],
+        ['audio', record(message.audio), undefined],
+        ['video', record(message.video), 'video/mp4'],
+        ['video', record(message.video_note), 'video/mp4'],
+        [
+            'sticker',
+            record(message.sticker),
+            record(message.sticker)?.is_animated === true
+                ? 'application/x-tgsticker'
+                : record(message.sticker)?.is_video === true
+                    ? 'video/webm'
+                    : 'image/webp',
+        ],
+    ];
+    for (const [kind, body, implied] of candidates) {
+        const fileId = str(body?.file_id);
+        if (!body || fileId === undefined)
+            continue;
+        const contentType = str(body.mime_type) ?? implied;
+        const filename = str(body.file_name);
+        const sizeBytes = sizeOf(body.file_size);
+        return {
+            kind,
+            ref: fileId,
+            ...(contentType !== undefined ? { contentType } : {}),
+            ...(filename !== undefined ? { filename } : {}),
+            ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+        };
+    }
+    return undefined;
+}
+/** The label of the inline button with `data` on the message it was pressed on. */
+function pressedLabel(message, data) {
+    const rows = record(message?.reply_markup)?.inline_keyboard;
+    if (!Array.isArray(rows))
+        return undefined;
+    for (const row of rows) {
+        if (!Array.isArray(row))
+            continue;
+        for (const button of row) {
+            if (record(button)?.callback_data === data)
+                return str(record(button)?.text);
+        }
+    }
+    return undefined;
+}
+/**
+ * A Telegram bot over the [Bot API](https://core.telegram.org/bots/api) webhook. Register it with
+ * `setWebhook({ url, secret_token, allowed_updates: ['message', 'callback_query'] })`.
+ *
+ * Reads text messages, media (photos, documents, voice notes, audio, video, stickers — downloaded
+ * with `getFile`, which serves up to 20 MB) and inline-keyboard presses (`callback_query`, answered with
+ * `answerCallbackQuery` and the keyboard removed so it cannot be pressed twice); ignores bots and
+ * (unless `groups`) group chats. Sends `sendMessage` in MarkdownV2 — when Telegram refuses the
+ * formatting, the same text goes again as plain text.
+ */
+export function telegram(options) {
+    const name = options.name ?? 'telegram';
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const markdown = options.markdown !== false;
+    const origin = (options.apiUrl ?? 'https://api.telegram.org').replace(/\/+$/, '');
+    const api = `${origin}/bot${options.botToken}`;
+    const call = (method, body) => postJson(name, fetcher, `${api}/${method}`, {}, body, timeoutMs);
+    const privateOnly = (chat) => options.groups === true || chat?.type === 'private';
+    return {
+        name,
+        capabilities: {
+            buttons: MAX_BUTTONS,
+            markdown: markdown ? 'telegram' : 'none',
+            maxLength: MAX_TEXT,
+        },
+        verify(request) {
+            return safeEqual(request.header('x-telegram-bot-api-secret-token'), options.secretToken);
+        },
+        parse(body) {
+            const update = record(body);
+            const updateId = update?.update_id;
+            if (typeof updateId !== 'number' && typeof updateId !== 'string')
+                return null;
+            const id = String(updateId);
+            const message = record(update?.message);
+            if (message) {
+                const chat = record(message.chat);
+                const from = record(message.from);
+                const media = mediaOf(message);
+                const text = (str(message.text) ?? str(message.caption) ?? '').trim();
+                if (!chat || !from || from.is_bot === true || !privateOnly(chat))
+                    return null;
+                if (text === '' && !media)
+                    return null;
+                return {
+                    id,
+                    from: String(from.id),
+                    conversation: String(chat.id),
+                    text,
+                    ...(media ? { media: [media] } : {}),
+                    raw: update,
+                };
+            }
+            const query = record(update?.callback_query);
+            if (query) {
+                const from = record(query.from);
+                const pressedOn = record(query.message);
+                const chat = record(pressedOn?.chat);
+                const data = str(query.data);
+                if (!from || !chat || !data || from.is_bot === true || !privateOnly(chat))
+                    return null;
+                return {
+                    id,
+                    from: String(from.id),
+                    conversation: String(chat.id),
+                    text: pressedLabel(pressedOn, data) ?? data,
+                    buttonId: data,
+                    raw: update,
+                };
+            }
+            return null;
+        },
+        async acknowledge(message) {
+            const query = record(record(message.raw)?.callback_query);
+            const queryId = str(query?.id);
+            if (queryId === undefined)
+                return;
+            await call('answerCallbackQuery', { callback_query_id: queryId }).catch(() => { });
+            const pressedOn = record(query?.message);
+            if (pressedOn?.message_id !== undefined) {
+                await call('editMessageReplyMarkup', {
+                    chat_id: message.conversation,
+                    message_id: pressedOn.message_id,
+                    reply_markup: { inline_keyboard: [] },
+                }).catch(() => { });
+            }
+        },
+        async download(media, { maxBytes }) {
+            if (media.sizeBytes !== undefined && media.sizeBytes > maxBytes) {
+                throw new ChannelMediaTooLargeError(maxBytes);
+            }
+            const answer = record(await call('getFile', { file_id: media.ref }));
+            const path = str(record(answer?.result)?.file_path);
+            if (path === undefined) {
+                // The Bot API serves files up to 20 MB; a larger one has no path.
+                throw new ChannelDeliveryError(name, null, `${name}: the file could not be downloaded`);
+            }
+            const file = await fetchBytes(name, fetcher, `${origin}/file/bot${options.botToken}/${path}`, {}, timeoutMs, maxBytes);
+            return {
+                data: file.data,
+                contentType: media.contentType ?? file.contentType ?? 'application/octet-stream',
+                ...(media.filename !== undefined ? { filename: media.filename } : {}),
+            };
+        },
+        async send(conversation, message) {
+            const body = {
+                chat_id: conversation,
+                text: message.text,
+                link_preview_options: { is_disabled: true },
+                ...(message.buttons !== undefined && message.buttons.length > 0
+                    ? {
+                        reply_markup: {
+                            inline_keyboard: [
+                                message.buttons
+                                    .slice(0, MAX_BUTTONS)
+                                    .map((button) => ({ text: button.label, callback_data: button.id })),
+                            ],
+                        },
+                    }
+                    : {}),
+            };
+            if (!markdown) {
+                await call('sendMessage', body);
+                return;
+            }
+            try {
+                await call('sendMessage', { ...body, parse_mode: 'MarkdownV2' });
+            }
+            catch (error) {
+                // "can't parse entities": the same words, unformatted, beat no answer.
+                if (!(error instanceof ChannelDeliveryError) || error.status !== 400)
+                    throw error;
+                await call('sendMessage', { ...body, text: unescapeTelegramMarkdown(message.text) });
+            }
+        },
+    };
+}
+//# sourceMappingURL=telegram.js.map

package/dist/src/channels/adapters/telegram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.js","sourceRoot":"","sources":["../../../../src/channels/adapters/telegram.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/adapters/whatsapp_cloud.d.ts

@@ -0,0 +1,31 @@
+import { type ChannelFetch } from '../http.js';
+import type { ChannelAdapter } from '../types.js';
+export interface WhatsappCloudOptions {
+    /** The business phone number's id (WhatsApp Manager → API setup) — not the number itself. */
+    phoneNumberId: string;
+    /** A system-user (or temporary) access token with `whatsapp_business_messaging`. */
+    accessToken: string;
+    /** The Meta app's secret: `X-Hub-Signature-256` is an HMAC of the raw body under it. */
+    appSecret: string;
+    /** The "Verify token" typed into the app's webhook settings, echoed by the subscription check. */
+    verifyToken: string;
+    /** Graph API version. Default `'v23.0'`. */
+    graphVersion?: string;
+    /** The adapter's name — the dedupe prefix and the decision's `via`. Default `'whatsapp'`. */
+    name?: string;
+    /** Per-request timeout. Default 20 s. */
+    timeoutMs?: number;
+    fetch?: ChannelFetch;
+}
+/**
+ * WhatsApp through Meta's [Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api).
+ * Route both `GET` (the subscription check) and `POST` (messages) to the same handler, and subscribe
+ * the app to the `messages` field.
+ *
+ * Verifies `X-Hub-Signature-256` over the raw body; reads text, interactive button/list replies,
+ * template quick replies and media (image, audio, video, document, sticker — downloaded through the
+ * Graph API media endpoint) addressed to `phoneNumberId` (status updates are ignored); sends text and
+ * interactive reply buttons (at most 3, 20-character titles).
+ */
+export declare function whatsappCloud(options: WhatsappCloudOptions): ChannelAdapter;
+//# sourceMappingURL=whatsapp_cloud.d.ts.map

package/dist/src/channels/adapters/whatsapp_cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp_cloud.d.ts","sourceRoot":"","sources":["../../../../src/channels/adapters/whatsapp_cloud.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,YAAY,EASlB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB,kGAAkG;IAClG,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAwDD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAmI3E"}

package/dist/src/channels/adapters/whatsapp_cloud.js

@@ -0,0 +1,177 @@
+import { createHmac } from 'node:crypto';
+import { ChannelDeliveryError, ChannelMediaTooLargeError, fetchBytes, postJson, queryParam, record, safeEqual, sizeOf, str, } from '../http.js';
+/** Cloud API limits: text body, interactive body, button title. */
+const MAX_TEXT = 4096;
+const MAX_INTERACTIVE_BODY = 1024;
+const MAX_BUTTON_TITLE = 20;
+const MAX_BUTTONS = 3;
+const MEDIA_TYPES = ['image', 'audio', 'video', 'document', 'sticker'];
+/** The file a Cloud API message carries (`{ id, mime_type, caption?, filename? }`), and its caption. */
+function mediaOf(message) {
+    const kind = MEDIA_TYPES.find((type) => type === message.type);
+    const body = kind === undefined ? undefined : record(message[kind]);
+    const mediaId = str(body?.id);
+    if (kind === undefined || !body || mediaId === undefined)
+        return undefined;
+    const contentType = str(body.mime_type);
+    const filename = str(body.filename);
+    return {
+        media: {
+            kind,
+            ref: mediaId,
+            ...(contentType !== undefined ? { contentType } : {}),
+            ...(filename !== undefined ? { filename } : {}),
+        },
+        caption: str(body.caption),
+    };
+}
+function parseMessage(message) {
+    const id = str(message.id);
+    const from = str(message.from);
+    if (!id || !from)
+        return null;
+    const interactive = record(message.interactive);
+    const reply = record(interactive?.button_reply) ?? record(interactive?.list_reply);
+    // A template's quick-reply button.
+    const button = record(message.button);
+    const buttonId = str(reply?.id) ?? str(button?.payload);
+    const file = mediaOf(message);
+    const text = file
+        ? (file.caption ?? '')
+        : (str(record(message.text)?.body) ?? str(reply?.title) ?? str(button?.text) ?? buttonId);
+    if (text === undefined || (text.trim() === '' && !file))
+        return null;
+    return {
+        id,
+        from,
+        conversation: from,
+        text: text.trim(),
+        ...(buttonId !== undefined ? { buttonId } : {}),
+        ...(file ? { media: [file.media] } : {}),
+        raw: message,
+    };
+}
+/**
+ * WhatsApp through Meta's [Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api).
+ * Route both `GET` (the subscription check) and `POST` (messages) to the same handler, and subscribe
+ * the app to the `messages` field.
+ *
+ * Verifies `X-Hub-Signature-256` over the raw body; reads text, interactive button/list replies,
+ * template quick replies and media (image, audio, video, document, sticker — downloaded through the
+ * Graph API media endpoint) addressed to `phoneNumberId` (status updates are ignored); sends text and
+ * interactive reply buttons (at most 3, 20-character titles).
+ */
+export function whatsappCloud(options) {
+    const name = options.name ?? 'whatsapp';
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const graphVersion = options.graphVersion ?? 'v23.0';
+    const endpoint = `https://graph.facebook.com/${graphVersion}/${encodeURIComponent(options.phoneNumberId)}/messages`;
+    const post = (body) => postJson(name, fetcher, endpoint, { authorization: `Bearer ${options.accessToken}` }, { messaging_product: 'whatsapp', recipient_type: 'individual', ...body }, timeoutMs);
+    const sendText = (to, body) => post({ to, type: 'text', text: { body, preview_url: false } });
+    return {
+        name,
+        capabilities: { buttons: MAX_BUTTONS, markdown: 'whatsapp', maxLength: MAX_TEXT },
+        challenge(request) {
+            if (request.method !== 'GET')
+                return null;
+            const mode = queryParam(request.url, 'hub.mode');
+            const token = queryParam(request.url, 'hub.verify_token');
+            const challenge = queryParam(request.url, 'hub.challenge');
+            if (mode === 'subscribe' && challenge !== undefined && safeEqual(token, options.verifyToken))
+                return { status: 200, body: challenge, contentType: 'text/plain' };
+            return { status: 403, body: 'Forbidden', contentType: 'text/plain' };
+        },
+        verify(request) {
+            const signature = request.header('x-hub-signature-256');
+            if (request.rawBody === null || signature === undefined)
+                return false;
+            const expected = `sha256=${createHmac('sha256', options.appSecret).update(request.rawBody, 'utf8').digest('hex')}`;
+            return safeEqual(signature, expected);
+        },
+        parse(body) {
+            const envelope = record(body);
+            if (envelope?.object !== 'whatsapp_business_account' || !Array.isArray(envelope.entry))
+                return null;
+            const messages = [];
+            for (const entry of envelope.entry) {
+                const changes = record(entry)?.changes;
+                if (!Array.isArray(changes))
+                    continue;
+                for (const change of changes) {
+                    const value = record(record(change)?.value);
+                    if (record(change)?.field !== 'messages' || !value)
+                        continue;
+                    if (str(record(value.metadata)?.phone_number_id) !== options.phoneNumberId)
+                        continue;
+                    if (!Array.isArray(value.messages))
+                        continue;
+                    for (const message of value.messages) {
+                        const parsed = record(message) ? parseMessage(record(message)) : null;
+                        if (parsed)
+                            messages.push(parsed);
+                    }
+                }
+            }
+            return messages;
+        },
+        async download(media, { maxBytes }) {
+            const auth = { authorization: `Bearer ${options.accessToken}` };
+            // The media id resolves to a short-lived url, which wants the same token.
+            const lookup = await fetchBytes(name, fetcher, `https://graph.facebook.com/${graphVersion}/${encodeURIComponent(String(media.ref))}`, auth, timeoutMs, 64 * 1024);
+            let info;
+            try {
+                info = record(JSON.parse(lookup.data.toString('utf8')));
+            }
+            catch {
+                info = undefined;
+            }
+            const url = str(info?.url);
+            if (url === undefined) {
+                throw new ChannelDeliveryError(name, null, `${name}: the media could not be resolved`);
+            }
+            const declared = sizeOf(info?.file_size);
+            if (declared !== undefined && declared > maxBytes)
+                throw new ChannelMediaTooLargeError(maxBytes);
+            const file = await fetchBytes(name, fetcher, url, auth, timeoutMs, maxBytes);
+            return {
+                data: file.data,
+                contentType: media.contentType ??
+                    str(info?.mime_type) ??
+                    file.contentType ??
+                    'application/octet-stream',
+                ...(media.filename !== undefined ? { filename: media.filename } : {}),
+            };
+        },
+        async send(conversation, message) {
+            if (message.buttons === undefined || message.buttons.length === 0) {
+                await sendText(conversation, message.buttons === undefined ? message.text : message.fallbackText);
+                return;
+            }
+            let body = message.text;
+            if (body.length > MAX_INTERACTIVE_BODY) {
+                // The interactive body is short: the text goes first, the buttons under its last paragraph.
+                const cut = body.lastIndexOf('\n\n', body.length - 1);
+                const tail = cut > 0 ? body.slice(cut + 2) : '';
+                const head = tail.length > 0 && tail.length <= MAX_INTERACTIVE_BODY ? body.slice(0, cut) : body;
+                await sendText(conversation, head);
+                body = head === body ? '…' : tail;
+            }
+            await post({
+                to: conversation,
+                type: 'interactive',
+                interactive: {
+                    type: 'button',
+                    body: { text: body },
+                    action: {
+                        buttons: message.buttons.slice(0, MAX_BUTTONS).map((button) => ({
+                            type: 'reply',
+                            reply: { id: button.id, title: button.label.slice(0, MAX_BUTTON_TITLE) },
+                        })),
+                    },
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=whatsapp_cloud.js.map

package/dist/src/channels/adapters/whatsapp_cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsapp_cloud.js","sourceRoot":"","sources":["../../../../src/channels/adapters/whatsapp_cloud.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,oBAAoB,EAEpB,yBAAyB,EACzB,UAAU,EACV,QAAQ,EACR,UAAU,EACV,MAAM,EACN,SAAS,EACT,MAAM,EACN,GAAG,GACJ,MAAM,YAAY,CAAC;AA2BpB,mEAAmE;AACnE,MAAM,QAAQ,GAAG,IAAI,CAAC;AACtB,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,CAAU,CAAC;AAEhF,wGAAwG;AACxG,SAAS,OAAO,CACd,OAAgC;IAEhC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3E,MAAM,WAAW,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO;QACL,KAAK,EAAE;YACL,IAAI;YACJ,GAAG,EAAE,OAAO;YACZ,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD;QACD,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,OAAgC;IACpD,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IACnF,mCAAmC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI;QACf,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QACtB,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,QAAQ,CAAC,CAAC;IAC5F,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO;QACL,EAAE;QACF,IAAI;QACJ,YAAY,EAAE,IAAI;QAClB,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;QACjB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,GAAG,EAAE,OAAO;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,CAAC;IACxC,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC;IACrD,MAAM,QAAQ,GAAG,8BAA8B,YAAY,IAAI,kBAAkB,CAAC,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC;IACpH,MAAM,IAAI,GAAG,CAAC,IAA6B,EAAE,EAAE,CAC7C,QAAQ,CACN,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,WAAW,EAAE,EAAE,EAClD,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,EACxE,SAAS,CACV,CAAC;IACJ,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAE,IAAY,EAAE,EAAE,CAC5C,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAEjE,OAAO;QACL,IAAI;QACJ,YAAY,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE;QAEjF,SAAS,CAAC,OAAuB;YAC/B,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;gBAAE,OAAO,IAAI,CAAC;YAC1C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YACjD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;YAC1D,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;YAC3D,IAAI,IAAI,KAAK,WAAW,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC;gBAC1F,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;YACrE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC;QACvE,CAAC;QAED,MAAM,CAAC,OAAuB;YAC5B,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;YACxD,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YACtE,MAAM,QAAQ,GAAG,UAAU,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACnH,OAAO,SAAS,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACxC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,QAAQ,EAAE,MAAM,KAAK,2BAA2B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBACpF,OAAO,IAAI,CAAC;YACd,MAAM,QAAQ,GAAqB,EAAE,CAAC;YACtC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;gBACnC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;gBACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;oBAAE,SAAS;gBACtC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC;oBAC5C,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,KAAK,UAAU,IAAI,CAAC,KAAK;wBAAE,SAAS;oBAC7D,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,KAAK,OAAO,CAAC,aAAa;wBAAE,SAAS;oBACrF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;wBAAE,SAAS;oBAC7C,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;wBACrC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;wBACvE,IAAI,MAAM;4BAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACpC,CAAC;gBACH,CAAC;YACH,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,KAAmB,EAAE,EAAE,QAAQ,EAAE;YAC9C,MAAM,IAAI,GAAG,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;YAChE,0EAA0E;YAC1E,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,IAAI,EACJ,OAAO,EACP,8BAA8B,YAAY,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EACrF,IAAI,EACJ,SAAS,EACT,EAAE,GAAG,IAAI,CACV,CAAC;YACF,IAAI,IAAyC,CAAC;YAC9C,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC1D,CAAC;YAAC,MAAM,CAAC;gBACP,IAAI,GAAG,SAAS,CAAC;YACnB,CAAC;YACD,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC3B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAI,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,mCAAmC,CAAC,CAAC;YACzF,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACzC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,GAAG,QAAQ;gBAC/C,MAAM,IAAI,yBAAyB,CAAC,QAAQ,CAAC,CAAC;YAChD,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC7E,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EACT,KAAK,CAAC,WAAW;oBACjB,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC;oBACpB,IAAI,CAAC,WAAW;oBAChB,0BAA0B;gBAC5B,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtE,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,YAAoB,EAAE,OAAwB;YACvD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAClE,MAAM,QAAQ,CACZ,YAAY,EACZ,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CACpE,CAAC;gBACF,OAAO;YACT,CAAC;YACD,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;YACxB,IAAI,IAAI,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;gBACvC,4FAA4F;gBAC5F,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACtD,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBACrF,MAAM,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;gBACnC,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YACpC,CAAC;YACD,MAAM,IAAI,CAAC;gBACT,EAAE,EAAE,YAAY;gBAChB,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;oBACpB,MAAM,EAAE;wBACN,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;4BAC9D,IAAI,EAAE,OAAO;4BACb,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,EAAE;yBACzE,CAAC,CAAC;qBACJ;iBACF;aACF,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/channels/handler.d.ts

@@ -0,0 +1,167 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import { AgentService } from '../agent-service.js';
+import type { AttachmentLimits } from '../attachment-limits.js';
+import type { ActionProposal } from '../spi/action-proposal-store.js';
+import type { ToolConfirmation } from '../tool-presentation.js';
+import type { Actor, PageContext } from '../types.js';
+import { type ChannelQuestionTexts } from './questions.js';
+import { type ChannelStore } from './store.js';
+import type { ChannelAdapter, InboundMedia, InboundMessage } from './types.js';
+/**
+ * What a channel turn needs from the agent — `AgentService` is one. The optional methods turn
+ * features on: proposals (buttons, outcomes), questions (`answer`), media (`stageAttachment`), and
+ * the Lucid default store (`lucidDatabase`).
+ */
+export interface ChannelTurnService extends Pick<AgentService, 'send' | 'subscribe' | 'skip' | 'cancel' | 'actionProposalReply'>, Partial<Pick<AgentService, 'decideActionProposal' | 'listActionProposals' | 'actionProposalVocabulary' | 'actionApprovalMode' | 'answer' | 'attachmentLimits' | 'stageAttachment' | 'lucidDatabase'>> {
+}
+/** A proposal the turn left pending, as the channel puts it to the person. */
+export interface ChannelProposal {
+    id: string;
+    toolName: string;
+    confirmation?: ToolConfirmation;
+}
+/** Why a media message could not be attached. */
+export type ChannelMediaRefusal = 'disabled' | 'type' | 'size' | 'failed';
+/** Everything the channel says on its own (not the model). English defaults; override any. */
+export interface ChannelTexts {
+    /** The Confirm button's label. */
+    approve: string;
+    /** The Cancel button's label. */
+    reject: string;
+    /** What a proposal says above its buttons — default: its confirmation's bold title and detail. */
+    proposal(proposal: ChannelProposal): string;
+    /**
+     * How to answer a proposal by text, when there are no buttons. `approve`/`reject` are the reply
+     * commands, built from the configured `actionProposalText.vocabulary` — `#ID` included when more
+     * than one proposal is waiting.
+     */
+    instruction(commands: {
+        approve: string;
+        reject: string;
+    }): string;
+    /** An approval in blocking mode, which a text channel cannot settle. */
+    blockingApproval: string;
+    /** The turn failed. */
+    failed: string;
+    /** An approved action ran, and presented nothing the channel could show. */
+    actionSucceeded: string;
+    /** An approved action's execution failed. */
+    actionFailed: string;
+    /** A file that could not be attached — no attachment store, a type or size it refuses, a failed download. */
+    mediaRefused(reason: ChannelMediaRefusal, media: InboundMedia, limits: AttachmentLimits | null): string;
+    /** How questions (the `ask` tool, intakes) are worded. */
+    questions: ChannelQuestionTexts;
+    /** Answer a sender `actor()` maps to nobody. Omitted → say nothing. */
+    unknownSender?: string;
+}
+export declare const DEFAULT_CHANNEL_TEXTS: ChannelTexts;
+/** `texts` as `channels.handle` takes it: any part, `questions` too. */
+export type ChannelTextsOverrides = Partial<Omit<ChannelTexts, 'questions'>> & {
+    questions?: Partial<ChannelQuestionTexts>;
+};
+export interface ChannelHandleOptions {
+    /**
+     * The account the sender is — from `message.from` (a phone number, a Telegram id). `null` → the
+     * message is not answered (or answered with `texts.unknownSender`). This IS the authentication of
+     * every message, so map only senders the channel itself vouches for.
+     */
+    actor(message: InboundMessage): Actor | null | Promise<Actor | null>;
+    /**
+     * The thread this conversation continues; `null`/`undefined` → a new one, reported to
+     * {@link onThreadCreated} so you can store it.
+     */
+    thread(actor: Actor, message: InboundMessage): string | null | undefined | Promise<string | null | undefined>;
+    /** A new thread was created for the conversation — remember it for {@link thread}. */
+    onThreadCreated?(threadId: string, actor: Actor, message: InboundMessage): void | Promise<void>;
+    /**
+     * The turn's page context. Default `{ kind: adapter.name }`. The handler adds `channel: { name,
+     * conversation }` to it — what a proposal's outcome is routed back by.
+     */
+    pageContext?: PageContext | ((message: InboundMessage) => PageContext);
+    /** The agent that answers. Default: the thread's, else the configured default. */
+    agentName?: string;
+    /** The agent service. Default: `AgentService` from the container. */
+    service?: ChannelTurnService;
+    /**
+     * Where the channel's short-lived state lives: message ids already taken, questions waiting for an
+     * answer, outcomes already relayed. Default: `lucidChannelStore()` over the agent store's database
+     * when the agent store is Lucid, else this process's memory.
+     */
+    store?: ChannelStore;
+    /** How long a message id is remembered. Default 24 h. */
+    dedupeTtlMs?: number;
+    /** Stop waiting for a turn after this long (and cancel it). Default 5 minutes. */
+    timeoutMs?: number;
+    /**
+     * After a proposal is approved, wait this long for it to execute and relay its outcome. `0` → do
+     * not wait (the decision reply is all the person gets; `channels.onSettled` can still relay it).
+     * Default 60 s.
+     */
+    outcomeTimeoutMs?: number;
+    /** How long a question waits for its answer before the agent proceeds without it. Default 30 min. */
+    questionTimeoutMs?: number;
+    texts?: ChannelTextsOverrides;
+    /** A message whose handling failed. Default: `console.error`. */
+    onError?(error: unknown, message: InboundMessage): void;
+}
+/** The route handler `channels.handle()` returns. */
+export interface ChannelRouteHandler {
+    (ctx: HttpContext): Promise<void>;
+    /** Resolves once every turn this handler started has been answered — for tests and shutdown. */
+    drain(): Promise<void>;
+}
+/** The button ids for a proposal: what {@link ChannelRouteHandler} maps back to its decision. */
+export declare function proposalButtonIds(proposalId: string): {
+    approve: string;
+    reject: string;
+};
+/** Where a turn's output goes back to — `pageContext.channel`, recorded with every proposal. */
+export interface ChannelAddress {
+    name: string;
+    conversation: string;
+}
+/**
+ * The webhook route for one channel. Each request is verified (`401` when it is not the provider's),
+ * parsed, deduplicated by the provider's message id, and acknowledged with `200` at once; the turn
+ * runs after the response, so a slow model never makes the provider retry. Then:
+ *
+ * - media are downloaded and attached (held to the attachment store's limits), or refused with a text;
+ * - the message is sent with text-only capabilities (components arrive as their `fallbackText`);
+ *   a text decision ("yes", "confirm #ID") is answered with its reply instead of starting a turn;
+ * - a press on a proposal's button decides that proposal (`via` = the adapter's name);
+ * - a question the turn asks is sent as text, one at a time, and the next messages answer it;
+ * - the reply is converted to the channel's markdown, split at its length limit, and sent;
+ * - a proposal the turn left pending is sent with Confirm/Cancel buttons — or, on a channel without
+ *   them, with a text instruction in the configured `actionProposalText` vocabulary;
+ * - an approved proposal's outcome is relayed once it executed (see `outcomeTimeoutMs`, and
+ *   `channels.onSettled` for one that runs later).
+ *
+ * Wants `actionApprovalMode: 'independent'`: a blocking approval holds the turn open until someone
+ * decides it in the app, so the channel sends what it has and `texts.blockingApproval`.
+ *
+ * Registers the adapter under its `name` for `channels.onSettled` — names must be unique.
+ */
+export declare function handleChannel(adapter: ChannelAdapter, options: ChannelHandleOptions): ChannelRouteHandler;
+/**
+ * `actionProposalWorker.onSettled` for text channels: relays an executed proposal's outcome to the
+ * conversation it was proposed in, through the adapter registered under the recorded channel name.
+ * Proposals from other surfaces are ignored. Safe next to the handler's own wait: an outcome is
+ * relayed once.
+ *
+ * ```ts
+ * // config/agent.ts
+ * actionProposalWorker: { onSettled: channels.onSettled }
+ * ```
+ */
+export declare function relayChannelOutcome(proposal: ActionProposal): Promise<void>;
+export declare const channels: {
+    /** See {@link handleChannel}. */
+    handle: typeof handleChannel;
+    /** See {@link relayChannelOutcome}. */
+    onSettled: typeof relayChannelOutcome;
+    /** Relay one proposal's outcome now; `true` when it was sent. */
+    deliverOutcome: (proposal: ActionProposal, service?: ChannelTurnService) => Promise<boolean>;
+    /** The adapter registered under `name` (by `channels.handle`), if any. */
+    adapter: (name: string) => ChannelAdapter | undefined;
+};
+//# sourceMappingURL=handler.d.ts.map

package/dist/src/channels/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/channels/handler.ts"],"names":[],"mappings":"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"}