@adonis-agora/agent 0.61.0 → 0.63.0

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":"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"}

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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"}