@agent-native/core 0.92.12 → 0.94.0

package/corpus/core/src/integrations/adapters/telegram.ts

@@ -38,14 +38,20 @@ function shouldRefuseWhenSecretMissing(): boolean {
  *
  * Required env vars:
  * - TELEGRAM_BOT_TOKEN — Bot token from @BotFather
- *
- * Optional env vars:
  * - TELEGRAM_WEBHOOK_SECRET — Secret token for webhook verification
  */
 export function telegramAdapter(): PlatformAdapter {
   return {
     platform: "telegram",
     label: "Telegram",
+    capabilities: {
+      replyText: true,
+      proactiveMessages: true,
+      nativeThreads: true,
+      contextualReplies: true,
+      deferredWebhookResponse: false,
+      interactionOnly: false,
+    },
 
     getRequiredEnvKeys(): EnvKeyConfig[] {
       return [
@@ -59,9 +65,9 @@ export function telegramAdapter(): PlatformAdapter {
         {
           key: "TELEGRAM_WEBHOOK_SECRET",
           label: "Telegram Webhook Secret",
-          required: false,
+          required: true,
           helpText:
-            "Optional. Any random string — Telegram will echo it on every webhook so dispatch can verify the request came from Telegram.",
+            "A random secret token. Telegram echoes it on every webhook so the adapter can verify the request came from Telegram.",
         },
       ];
     },
@@ -149,18 +155,27 @@ export function telegramAdapter(): PlatformAdapter {
 
       const chat = message.chat;
       const from = message.from;
+      const messageThreadId = message.message_thread_id;
+      const externalThreadId =
+        messageThreadId === undefined
+          ? `chat:${String(chat.id)}`
+          : `chat:${String(chat.id)}:thread:${String(messageThreadId)}`;
 
       return {
         platform: "telegram",
-        externalThreadId: String(chat.id),
+        externalThreadId,
         text: cleanText,
         senderName:
           from?.first_name + (from?.last_name ? ` ${from.last_name}` : ""),
         senderId: String(from?.id),
+        threadRef:
+          messageThreadId === undefined ? undefined : String(messageThreadId),
+        replyRef: String(message.message_id),
         platformContext: {
           chatId: chat.id,
           chatType: chat.type,
           messageId: message.message_id,
+          messageThreadId,
           rawText: text,
           fromId: from?.id,
           fromUsername: from?.username,
@@ -169,6 +184,13 @@ export function telegramAdapter(): PlatformAdapter {
       };
     },
 
+    getLegacyExternalThreadIds(incoming: IncomingMessage): string[] {
+      const chatId = incoming.platformContext.chatId;
+      return typeof chatId === "string" || typeof chatId === "number"
+        ? [String(chatId)]
+        : [];
+    },
+
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
@@ -182,18 +204,28 @@ export function telegramAdapter(): PlatformAdapter {
       const chatId = context.platformContext.chatId;
       const chunks = splitMessage(message.text, TELEGRAM_MAX_LENGTH);
 
-      for (const chunk of chunks) {
+      for (const [index, chunk] of chunks.entries()) {
         try {
+          const body: Record<string, unknown> = {
+            chat_id: chatId,
+            text: chunk,
+            parse_mode: "Markdown",
+          };
+          if (context.threadRef) {
+            body.message_thread_id = Number(context.threadRef);
+          }
+          if (index === 0 && context.replyRef) {
+            body.reply_parameters = {
+              message_id: Number(context.replyRef),
+              allow_sending_without_reply: true,
+            };
+          }
           const res = await fetch(
             `https://api.telegram.org/bot${token}/sendMessage`,
             {
               method: "POST",
               headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({
-                chat_id: chatId,
-                text: chunk,
-                parse_mode: "Markdown",
-              }),
+              body: JSON.stringify(body),
             },
           );
           const data = (await res.json()) as {
@@ -207,8 +239,8 @@ export function telegramAdapter(): PlatformAdapter {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
-                  chat_id: chatId,
-                  text: chunk,
+                  ...body,
+                  parse_mode: undefined,
                 }),
               });
             } else {
@@ -275,6 +307,10 @@ export function telegramAdapter(): PlatformAdapter {
     async getStatus(_baseUrl?: string): Promise<IntegrationStatus> {
       const token = await resolveSecret("TELEGRAM_BOT_TOKEN");
       const hasToken = !!token;
+      const hasWebhookSecret = !!(await resolveSecret(
+        "TELEGRAM_WEBHOOK_SECRET",
+      ));
+      const configured = hasToken && hasWebhookSecret;
 
       let botName: string | undefined;
       if (hasToken) {
@@ -294,12 +330,15 @@ export function telegramAdapter(): PlatformAdapter {
         platform: "telegram",
         label: "Telegram",
         enabled: false, // overridden by plugin
-        configured: hasToken,
+        configured,
         details: {
           hasToken,
+          hasWebhookSecret,
           botUsername: botName,
         },
-        error: !hasToken ? "Save TELEGRAM_BOT_TOKEN in settings" : undefined,
+        error: !configured
+          ? "Save TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET in settings"
+          : undefined,
       };
     },
   };

package/corpus/core/src/integrations/adapters/whatsapp.ts

@@ -12,6 +12,7 @@ import type {
 
 /** WhatsApp's max message length */
 const WHATSAPP_MAX_LENGTH = 4096;
+const WHATSAPP_GRAPH_API_VERSION = "v25.0";
 
 /**
  * One-shot warning flag — log once per process when accepting unverified
@@ -37,14 +38,20 @@ function shouldRefuseWhenSecretMissing(): boolean {
  * - WHATSAPP_ACCESS_TOKEN — Permanent access token from Meta
  * - WHATSAPP_VERIFY_TOKEN — Custom token for webhook verification
  * - WHATSAPP_PHONE_NUMBER_ID — Phone number ID from Meta dashboard
- *
- * Optional env vars:
  * - WHATSAPP_APP_SECRET — App secret for signature verification
  */
 export function whatsappAdapter(): PlatformAdapter {
   return {
     platform: "whatsapp",
     label: "WhatsApp",
+    capabilities: {
+      replyText: true,
+      proactiveMessages: false,
+      nativeThreads: false,
+      contextualReplies: true,
+      deferredWebhookResponse: false,
+      interactionOnly: false,
+    },
 
     getRequiredEnvKeys(): EnvKeyConfig[] {
       return [
@@ -72,9 +79,9 @@ export function whatsappAdapter(): PlatformAdapter {
         {
           key: "WHATSAPP_APP_SECRET",
           label: "WhatsApp App Secret",
-          required: false,
+          required: true,
           helpText:
-            "Optional. From Meta App Dashboard → Basic Settings → App Secret. Enables HMAC signature verification on inbound webhooks.",
+            "From Meta App Dashboard → Basic Settings → App Secret. Used for HMAC verification on every inbound webhook.",
         },
       ];
     },
@@ -202,15 +209,18 @@ export function whatsappAdapter(): PlatformAdapter {
 
       const contact = value.contacts?.[0];
       const from = message.from; // Phone number
+      const phoneNumberId = value.metadata?.phone_number_id;
+      if (!from || !phoneNumberId || !message.id) return null;
 
       return {
         platform: "whatsapp",
-        externalThreadId: from,
+        externalThreadId: `phone:${String(phoneNumberId)}:user:${String(from)}`,
         text,
         senderName: contact?.profile?.name,
         senderId: from,
+        replyRef: String(message.id),
         platformContext: {
-          phoneNumberId: value.metadata?.phone_number_id,
+          phoneNumberId,
           displayPhoneNumber: value.metadata?.display_phone_number,
           messageId: message.id,
           from,
@@ -220,6 +230,13 @@ export function whatsappAdapter(): PlatformAdapter {
       };
     },
 
+    getLegacyExternalThreadIds(incoming: IncomingMessage): string[] {
+      const from = incoming.platformContext.from ?? incoming.senderId;
+      return typeof from === "string" || typeof from === "number"
+        ? [String(from)]
+        : [];
+    },
+
     async sendResponse(
       message: OutgoingMessage,
       context: IncomingMessage,
@@ -236,23 +253,27 @@ export function whatsappAdapter(): PlatformAdapter {
       const to = context.senderId;
       const chunks = splitMessage(message.text, WHATSAPP_MAX_LENGTH);
 
-      for (const chunk of chunks) {
+      for (const [index, chunk] of chunks.entries()) {
         try {
+          const body: Record<string, unknown> = {
+            messaging_product: "whatsapp",
+            recipient_type: "individual",
+            to,
+            type: "text",
+            text: { body: chunk },
+          };
+          if (index === 0 && context.replyRef) {
+            body.context = { message_id: context.replyRef };
+          }
           const res = await fetch(
-            `https://graph.facebook.com/v21.0/${phoneNumberId}/messages`,
+            `https://graph.facebook.com/${WHATSAPP_GRAPH_API_VERSION}/${phoneNumberId}/messages`,
             {
               method: "POST",
               headers: {
                 Authorization: `Bearer ${accessToken}`,
                 "Content-Type": "application/json",
               },
-              body: JSON.stringify({
-                messaging_product: "whatsapp",
-                recipient_type: "individual",
-                to,
-                type: "text",
-                text: { body: chunk },
-              }),
+              body: JSON.stringify(body),
             },
           );
           if (!res.ok) {
@@ -275,7 +296,9 @@ export function whatsappAdapter(): PlatformAdapter {
       const hasPhoneNumberId = !!(await resolveSecret(
         "WHATSAPP_PHONE_NUMBER_ID",
       ));
-      const configured = hasAccessToken && hasVerifyToken && hasPhoneNumberId;
+      const hasAppSecret = !!(await resolveSecret("WHATSAPP_APP_SECRET"));
+      const configured =
+        hasAccessToken && hasVerifyToken && hasPhoneNumberId && hasAppSecret;
 
       return {
         platform: "whatsapp",
@@ -286,9 +309,10 @@ export function whatsappAdapter(): PlatformAdapter {
           hasAccessToken,
           hasVerifyToken,
           hasPhoneNumberId,
+          hasAppSecret,
         },
         error: !configured
-          ? "Save WHATSAPP_ACCESS_TOKEN, WHATSAPP_VERIFY_TOKEN, and WHATSAPP_PHONE_NUMBER_ID in settings"
+          ? "Save WHATSAPP_ACCESS_TOKEN, WHATSAPP_VERIFY_TOKEN, WHATSAPP_PHONE_NUMBER_ID, and WHATSAPP_APP_SECRET in settings"
           : undefined,
       };
     },

package/corpus/core/src/integrations/awaiting-input-store.ts

@@ -0,0 +1,130 @@
+import { getDbExec, intType, isPostgres } from "../db/client.js";
+import { ensureTableExists } from "../db/ddl-guard.js";
+
+let initPromise: Promise<void> | undefined;
+
+/** Channel-thread clarification windows are deliberately short-lived. */
+export const INTEGRATION_AWAITING_INPUT_TTL_MS = 24 * 60 * 60 * 1000;
+
+async function ensureTable(): Promise<void> {
+  if (!initPromise) {
+    initPromise = (async () => {
+      const client = getDbExec();
+      const createSql = `
+        CREATE TABLE IF NOT EXISTS integration_awaiting_inputs (
+          platform TEXT NOT NULL,
+          external_thread_id TEXT NOT NULL,
+          requester_id TEXT NOT NULL,
+          expires_at ${intType()} NOT NULL,
+          created_at ${intType()} NOT NULL,
+          updated_at ${intType()} NOT NULL,
+          PRIMARY KEY (platform, external_thread_id)
+        )
+      `;
+      if (isPostgres()) {
+        await ensureTableExists("integration_awaiting_inputs", createSql);
+        return;
+      }
+      await client.execute(createSql);
+    })().catch((error) => {
+      initPromise = undefined;
+      throw error;
+    });
+  }
+  return initPromise;
+}
+
+/**
+ * Open (or refresh) the bounded reply window after an integration explicitly
+ * asks the originating Slack user a question. The workspace-qualified external
+ * thread id and requester id prevent unrelated channel messages from opting in.
+ */
+export async function setIntegrationAwaitingInput(input: {
+  platform: string;
+  externalThreadId: string;
+  requesterId: string;
+  expiresAt?: number;
+}): Promise<void> {
+  await ensureTable();
+  const requesterId = input.requesterId.trim();
+  if (!requesterId) throw new Error("requesterId is required");
+  const now = Date.now();
+  const expiresAt = input.expiresAt ?? now + INTEGRATION_AWAITING_INPUT_TTL_MS;
+  const client = getDbExec();
+  await client.execute({
+    sql: isPostgres()
+      ? `INSERT INTO integration_awaiting_inputs (platform, external_thread_id, requester_id, expires_at, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT (platform, external_thread_id) DO UPDATE SET
+             requester_id = EXCLUDED.requester_id,
+             expires_at = EXCLUDED.expires_at,
+             updated_at = EXCLUDED.updated_at`
+      : `INSERT OR REPLACE INTO integration_awaiting_inputs (platform, external_thread_id, requester_id, expires_at, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?)`,
+    args: [
+      input.platform,
+      input.externalThreadId,
+      requesterId,
+      expiresAt,
+      now,
+      now,
+    ],
+  });
+}
+
+/**
+ * Atomically consume the one reply window for this exact requester. Competing
+ * Slack deliveries cannot both claim it, and expired rows never authorize a
+ * later unmentioned reply.
+ */
+export async function consumeIntegrationAwaitingInput(input: {
+  platform: string;
+  externalThreadId: string;
+  requesterId: string;
+}): Promise<boolean> {
+  await ensureTable();
+  const client = getDbExec();
+  const result = await client.execute({
+    sql: isPostgres()
+      ? `DELETE FROM integration_awaiting_inputs
+           WHERE platform = ?
+             AND external_thread_id = ?
+             AND requester_id = ?
+             AND expires_at > ?
+           RETURNING platform`
+      : `DELETE FROM integration_awaiting_inputs
+           WHERE platform = ?
+             AND external_thread_id = ?
+             AND requester_id = ?
+             AND expires_at > ?`,
+    args: [
+      input.platform,
+      input.externalThreadId,
+      input.requesterId,
+      Date.now(),
+    ],
+  });
+
+  if (isPostgres()) return (result.rows ?? []).length > 0;
+  const affected =
+    (result as { rowsAffected?: number; rowCount?: number }).rowsAffected ??
+    (result as { rowsAffected?: number; rowCount?: number }).rowCount ??
+    0;
+  return affected > 0;
+}
+
+/** Clear any outstanding clarification window once the thread resolves. */
+export async function clearIntegrationAwaitingInput(
+  platform: string,
+  externalThreadId: string,
+): Promise<void> {
+  await ensureTable();
+  await getDbExec().execute({
+    sql: `DELETE FROM integration_awaiting_inputs WHERE platform = ? AND external_thread_id = ?`,
+    args: [platform, externalThreadId],
+  });
+}
+
+export function _resetIntegrationAwaitingInputStoreForTests(): void {
+  initPromise = undefined;
+}