@poncho-ai/messaging 0.2.0

package/.turbo/turbo-build.log

@@ -0,0 +1,14 @@
+
+> @poncho-ai/messaging@0.2.0 build /home/runner/work/poncho-ai/poncho-ai/packages/messaging
+> tsup src/index.ts --format esm --dts
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2022
+ESM Build start
+ESM dist/index.js 8.45 KB
+ESM ⚡️ Build success in 29ms
+DTS Build start
+DTS ⚡️ Build success in 2735ms
+DTS dist/index.d.ts 3.23 KB

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @poncho-ai/messaging
+
+## 0.2.0
+
+### Minor Changes
+
+- [#10](https://github.com/cesr/poncho-ai/pull/10) [`d5bce7b`](https://github.com/cesr/poncho-ai/commit/d5bce7be5890c657bea915eb0926feb6de66b218) Thanks [@cesr](https://github.com/cesr)! - Add generic messaging layer with Slack as the first adapter. Agents can now respond to @mentions in Slack by adding `messaging: [{ platform: 'slack' }]` to `poncho.config.js`. Includes signature verification, threaded conversations, processing indicators, and Vercel `waitUntil` support.
+
+### Patch Changes
+
+- Updated dependencies [[`d5bce7b`](https://github.com/cesr/poncho-ai/commit/d5bce7be5890c657bea915eb0926feb6de66b218)]:
+  - @poncho-ai/sdk@1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Latitude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import http from 'node:http';
+import { Message } from '@poncho-ai/sdk';
+
+interface ThreadRef {
+    platformThreadId: string;
+    channelId: string;
+    /** The specific message ID that triggered this interaction (for reactions). */
+    messageId?: string;
+}
+interface IncomingMessage {
+    text: string;
+    threadRef: ThreadRef;
+    sender: {
+        id: string;
+        name?: string;
+    };
+    platform: string;
+    raw: unknown;
+}
+type IncomingMessageHandler = (message: IncomingMessage) => Promise<void>;
+type RouteHandler = (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+type RouteRegistrar = (method: "GET" | "POST", path: string, handler: RouteHandler) => void;
+interface MessagingAdapter {
+    readonly platform: string;
+    /** Register HTTP routes on the host server for receiving platform events. */
+    registerRoutes(router: RouteRegistrar): void;
+    /** One-time startup (e.g. validate credentials). */
+    initialize(): Promise<void>;
+    /** Set the handler that processes incoming messages. */
+    onMessage(handler: IncomingMessageHandler): void;
+    /** Post a reply back to the originating thread. */
+    sendReply(threadRef: ThreadRef, content: string): Promise<void>;
+    /**
+     * Show a processing indicator (e.g. reaction, typing).
+     * Returns a cleanup function that removes the indicator.
+     */
+    indicateProcessing(threadRef: ThreadRef): Promise<() => Promise<void>>;
+}
+interface AgentRunner {
+    getOrCreateConversation(conversationId: string, meta: {
+        platform: string;
+        ownerId: string;
+        title?: string;
+    }): Promise<{
+        messages: Message[];
+    }>;
+    run(conversationId: string, input: {
+        task: string;
+        messages: Message[];
+    }): Promise<{
+        response: string;
+    }>;
+}
+interface AgentBridgeOptions {
+    adapter: MessagingAdapter;
+    runner: AgentRunner;
+    /**
+     * Optional hook to keep serverless functions alive after the HTTP response.
+     * On Vercel, pass the real `waitUntil` from `@vercel/functions`.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+
+declare class AgentBridge {
+    private readonly adapter;
+    private readonly runner;
+    private readonly waitUntil;
+    constructor(options: AgentBridgeOptions);
+    /** Wire the adapter's message handler and initialise. */
+    start(): Promise<void>;
+    private handleMessage;
+}
+
+interface SlackAdapterOptions {
+    botTokenEnv?: string;
+    signingSecretEnv?: string;
+}
+declare class SlackAdapter implements MessagingAdapter {
+    readonly platform: "slack";
+    private botToken;
+    private signingSecret;
+    private readonly botTokenEnv;
+    private readonly signingSecretEnv;
+    private handler;
+    constructor(options?: SlackAdapterOptions);
+    initialize(): Promise<void>;
+    onMessage(handler: IncomingMessageHandler): void;
+    registerRoutes(router: RouteRegistrar): void;
+    sendReply(threadRef: ThreadRef, content: string): Promise<void>;
+    indicateProcessing(threadRef: ThreadRef): Promise<() => Promise<void>>;
+    private handleRequest;
+}
+
+export { AgentBridge, type AgentBridgeOptions, type AgentRunner, type IncomingMessage, type IncomingMessageHandler, type MessagingAdapter, type RouteHandler, type RouteRegistrar, SlackAdapter, type SlackAdapterOptions, type ThreadRef };

package/dist/index.js

@@ -0,0 +1,290 @@
+// src/bridge.ts
+var conversationIdFromThread = (platform, ref) => `${platform}:${ref.channelId}:${ref.platformThreadId}`;
+var AgentBridge = class {
+  adapter;
+  runner;
+  waitUntil;
+  constructor(options) {
+    this.adapter = options.adapter;
+    this.runner = options.runner;
+    this.waitUntil = options.waitUntil ?? ((_p) => {
+    });
+  }
+  /** Wire the adapter's message handler and initialise. */
+  async start() {
+    this.adapter.onMessage((msg) => {
+      const processing = this.handleMessage(msg);
+      this.waitUntil(processing);
+      return processing;
+    });
+    await this.adapter.initialize();
+  }
+  async handleMessage(message) {
+    let cleanup;
+    try {
+      cleanup = await this.adapter.indicateProcessing(message.threadRef);
+      const conversationId = conversationIdFromThread(
+        message.platform,
+        message.threadRef
+      );
+      const conversation = await this.runner.getOrCreateConversation(
+        conversationId,
+        {
+          platform: message.platform,
+          ownerId: message.sender.id,
+          title: `${message.platform} thread`
+        }
+      );
+      const result = await this.runner.run(conversationId, {
+        task: message.text,
+        messages: conversation.messages
+      });
+      await this.adapter.sendReply(message.threadRef, result.response);
+    } catch (error) {
+      const snippet = error instanceof Error ? error.message : "Unknown error";
+      try {
+        await this.adapter.sendReply(
+          message.threadRef,
+          `Sorry, something went wrong: ${snippet}`
+        );
+      } catch {
+      }
+    } finally {
+      if (cleanup) {
+        try {
+          await cleanup();
+        } catch {
+        }
+      }
+    }
+  }
+};
+
+// src/adapters/slack/verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var MAX_TIMESTAMP_DRIFT_SECONDS = 300;
+var verifySlackSignature = (signingSecret, headers, rawBody) => {
+  const { signature, timestamp } = headers;
+  if (!signature || !timestamp) return false;
+  const ts = Number(timestamp);
+  if (Number.isNaN(ts)) return false;
+  const drift = Math.abs(Math.floor(Date.now() / 1e3) - ts);
+  if (drift > MAX_TIMESTAMP_DRIFT_SECONDS) return false;
+  const basestring = `v0:${timestamp}:${rawBody}`;
+  const computed = `v0=${createHmac("sha256", signingSecret).update(basestring).digest("hex")}`;
+  if (computed.length !== signature.length) return false;
+  return timingSafeEqual(Buffer.from(computed), Buffer.from(signature));
+};
+
+// src/adapters/slack/utils.ts
+var SLACK_MAX_MESSAGE_LENGTH = 4e3;
+var MENTION_PATTERN = /^\s*<@[A-Z0-9]+>\s*/i;
+var stripMention = (text) => text.replace(MENTION_PATTERN, "").trim();
+var splitMessage = (text) => {
+  if (text.length <= SLACK_MAX_MESSAGE_LENGTH) return [text];
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= SLACK_MAX_MESSAGE_LENGTH) {
+      chunks.push(remaining);
+      break;
+    }
+    let cutPoint = remaining.lastIndexOf(
+      "\n",
+      SLACK_MAX_MESSAGE_LENGTH
+    );
+    if (cutPoint <= 0) {
+      cutPoint = SLACK_MAX_MESSAGE_LENGTH;
+    }
+    chunks.push(remaining.slice(0, cutPoint));
+    remaining = remaining.slice(cutPoint).replace(/^\n/, "");
+  }
+  return chunks;
+};
+var SLACK_API = "https://slack.com/api";
+var slackFetch = async (method, token, body) => {
+  const res = await fetch(`${SLACK_API}/${method}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json; charset=utf-8"
+    },
+    body: JSON.stringify(body)
+  });
+  return await res.json();
+};
+var postMessage = async (token, channel, text, threadTs) => {
+  const result = await slackFetch("chat.postMessage", token, {
+    channel,
+    text,
+    thread_ts: threadTs
+  });
+  if (!result.ok) {
+    throw new Error(`Slack chat.postMessage failed: ${result.error}`);
+  }
+};
+var addReaction = async (token, channel, timestamp, reaction) => {
+  const result = await slackFetch("reactions.add", token, {
+    channel,
+    timestamp,
+    name: reaction
+  });
+  if (!result.ok && result.error !== "already_reacted") {
+    throw new Error(`Slack reactions.add failed: ${result.error}`);
+  }
+};
+var removeReaction = async (token, channel, timestamp, reaction) => {
+  const result = await slackFetch("reactions.remove", token, {
+    channel,
+    timestamp,
+    name: reaction
+  });
+  if (!result.ok && result.error !== "no_reaction") {
+    throw new Error(`Slack reactions.remove failed: ${result.error}`);
+  }
+};
+
+// src/adapters/slack/index.ts
+var PROCESSING_REACTION = "eyes";
+var collectBody = (req) => new Promise((resolve, reject) => {
+  const chunks = [];
+  req.on("data", (chunk) => chunks.push(chunk));
+  req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+  req.on("error", reject);
+});
+var SlackAdapter = class {
+  platform = "slack";
+  botToken = "";
+  signingSecret = "";
+  botTokenEnv;
+  signingSecretEnv;
+  handler;
+  constructor(options = {}) {
+    this.botTokenEnv = options.botTokenEnv ?? "SLACK_BOT_TOKEN";
+    this.signingSecretEnv = options.signingSecretEnv ?? "SLACK_SIGNING_SECRET";
+  }
+  // -----------------------------------------------------------------------
+  // MessagingAdapter implementation
+  // -----------------------------------------------------------------------
+  async initialize() {
+    this.botToken = process.env[this.botTokenEnv] ?? "";
+    this.signingSecret = process.env[this.signingSecretEnv] ?? "";
+    if (!this.botToken) {
+      throw new Error(
+        `Slack messaging: ${this.botTokenEnv} environment variable is not set`
+      );
+    }
+    if (!this.signingSecret) {
+      throw new Error(
+        `Slack messaging: ${this.signingSecretEnv} environment variable is not set`
+      );
+    }
+  }
+  onMessage(handler) {
+    this.handler = handler;
+  }
+  registerRoutes(router) {
+    router(
+      "POST",
+      "/api/messaging/slack",
+      (req, res) => this.handleRequest(req, res)
+    );
+  }
+  async sendReply(threadRef, content) {
+    const chunks = splitMessage(content);
+    for (const chunk of chunks) {
+      await postMessage(
+        this.botToken,
+        threadRef.channelId,
+        chunk,
+        threadRef.platformThreadId
+      );
+    }
+  }
+  async indicateProcessing(threadRef) {
+    const reactionTarget = threadRef.messageId ?? threadRef.platformThreadId;
+    await addReaction(
+      this.botToken,
+      threadRef.channelId,
+      reactionTarget,
+      PROCESSING_REACTION
+    );
+    return () => removeReaction(
+      this.botToken,
+      threadRef.channelId,
+      reactionTarget,
+      PROCESSING_REACTION
+    );
+  }
+  // -----------------------------------------------------------------------
+  // HTTP request handling
+  // -----------------------------------------------------------------------
+  async handleRequest(req, res) {
+    const rawBody = await collectBody(req);
+    const isValid = verifySlackSignature(
+      this.signingSecret,
+      {
+        signature: req.headers["x-slack-signature"],
+        timestamp: req.headers["x-slack-request-timestamp"]
+      },
+      rawBody
+    );
+    if (!isValid) {
+      res.writeHead(401);
+      res.end("Invalid signature");
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      res.writeHead(400);
+      res.end("Invalid JSON");
+      return;
+    }
+    if (payload.type === "url_verification") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ challenge: payload.challenge }));
+      return;
+    }
+    if (req.headers["x-slack-retry-num"]) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    if (payload.type === "event_callback") {
+      res.writeHead(200);
+      res.end();
+      const event = payload.event;
+      if (event?.type === "app_mention" && this.handler) {
+        const text = stripMention(String(event.text ?? ""));
+        if (!text) return;
+        const threadTs = String(event.thread_ts ?? event.ts ?? "");
+        const messageTs = String(event.ts ?? "");
+        const channel = String(event.channel ?? "");
+        const userId = String(event.user ?? "");
+        const message = {
+          text,
+          threadRef: {
+            platformThreadId: threadTs,
+            channelId: channel,
+            messageId: messageTs
+          },
+          sender: { id: userId },
+          platform: "slack",
+          raw: event
+        };
+        void this.handler(message).catch((err) => {
+          console.error("[slack-adapter] unhandled message handler error", err);
+        });
+      }
+      return;
+    }
+    res.writeHead(200);
+    res.end();
+  }
+};
+export {
+  AgentBridge,
+  SlackAdapter
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@poncho-ai/messaging",
+  "version": "0.2.0",
+  "description": "Messaging platform adapters for Poncho agents (Slack, Telegram, etc.)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cesr/poncho-ai.git",
+    "directory": "packages/messaging"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@poncho-ai/sdk": "1.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "vitest": "^1.4.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "messaging",
+    "slack"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest",
+    "lint": "eslint src/"
+  }
+}

package/src/adapters/slack/index.ts

@@ -0,0 +1,214 @@
+import type http from "node:http";
+import type {
+  IncomingMessage as PonchoIncomingMessage,
+  IncomingMessageHandler,
+  MessagingAdapter,
+  RouteRegistrar,
+  ThreadRef,
+} from "../../types.js";
+import { verifySlackSignature } from "./verify.js";
+import {
+  addReaction,
+  postMessage,
+  removeReaction,
+  splitMessage,
+  stripMention,
+} from "./utils.js";
+
+const PROCESSING_REACTION = "eyes";
+
+export interface SlackAdapterOptions {
+  botTokenEnv?: string;
+  signingSecretEnv?: string;
+}
+
+/**
+ * Collect the raw request body from a Node `http.IncomingMessage`.
+ */
+const collectBody = (req: http.IncomingMessage): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+
+export class SlackAdapter implements MessagingAdapter {
+  readonly platform = "slack" as const;
+
+  private botToken = "";
+  private signingSecret = "";
+  private readonly botTokenEnv: string;
+  private readonly signingSecretEnv: string;
+  private handler: IncomingMessageHandler | undefined;
+
+  constructor(options: SlackAdapterOptions = {}) {
+    this.botTokenEnv = options.botTokenEnv ?? "SLACK_BOT_TOKEN";
+    this.signingSecretEnv =
+      options.signingSecretEnv ?? "SLACK_SIGNING_SECRET";
+  }
+
+  // -----------------------------------------------------------------------
+  // MessagingAdapter implementation
+  // -----------------------------------------------------------------------
+
+  async initialize(): Promise<void> {
+    this.botToken = process.env[this.botTokenEnv] ?? "";
+    this.signingSecret = process.env[this.signingSecretEnv] ?? "";
+
+    if (!this.botToken) {
+      throw new Error(
+        `Slack messaging: ${this.botTokenEnv} environment variable is not set`,
+      );
+    }
+    if (!this.signingSecret) {
+      throw new Error(
+        `Slack messaging: ${this.signingSecretEnv} environment variable is not set`,
+      );
+    }
+  }
+
+  onMessage(handler: IncomingMessageHandler): void {
+    this.handler = handler;
+  }
+
+  registerRoutes(router: RouteRegistrar): void {
+    router("POST", "/api/messaging/slack", (req, res) =>
+      this.handleRequest(req, res),
+    );
+  }
+
+  async sendReply(threadRef: ThreadRef, content: string): Promise<void> {
+    const chunks = splitMessage(content);
+    for (const chunk of chunks) {
+      await postMessage(
+        this.botToken,
+        threadRef.channelId,
+        chunk,
+        threadRef.platformThreadId,
+      );
+    }
+  }
+
+  async indicateProcessing(
+    threadRef: ThreadRef,
+  ): Promise<() => Promise<void>> {
+    // React to the specific message that triggered the event, not the
+    // thread parent. Falls back to platformThreadId for non-threaded msgs.
+    const reactionTarget =
+      threadRef.messageId ?? threadRef.platformThreadId;
+
+    await addReaction(
+      this.botToken,
+      threadRef.channelId,
+      reactionTarget,
+      PROCESSING_REACTION,
+    );
+
+    return () =>
+      removeReaction(
+        this.botToken,
+        threadRef.channelId,
+        reactionTarget,
+        PROCESSING_REACTION,
+      );
+  }
+
+  // -----------------------------------------------------------------------
+  // HTTP request handling
+  // -----------------------------------------------------------------------
+
+  private async handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ): Promise<void> {
+    const rawBody = await collectBody(req);
+
+    // -- Signature verification ------------------------------------------
+    const isValid = verifySlackSignature(
+      this.signingSecret,
+      {
+        signature: req.headers["x-slack-signature"] as string | undefined,
+        timestamp: req.headers["x-slack-request-timestamp"] as
+          | string
+          | undefined,
+      },
+      rawBody,
+    );
+
+    if (!isValid) {
+      res.writeHead(401);
+      res.end("Invalid signature");
+      return;
+    }
+
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(rawBody) as Record<string, unknown>;
+    } catch {
+      res.writeHead(400);
+      res.end("Invalid JSON");
+      return;
+    }
+
+    // -- URL verification challenge --------------------------------------
+    if (payload.type === "url_verification") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ challenge: payload.challenge }));
+      return;
+    }
+
+    // -- Retry deduplication ---------------------------------------------
+    if (req.headers["x-slack-retry-num"]) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // -- Event dispatch --------------------------------------------------
+    if (payload.type === "event_callback") {
+      // Acknowledge immediately so Slack doesn't retry.
+      res.writeHead(200);
+      res.end();
+
+      const event = payload.event as Record<string, unknown> | undefined;
+      if (event?.type === "app_mention" && this.handler) {
+        const text = stripMention(String(event.text ?? ""));
+        if (!text) return;
+
+        // thread_ts = parent message (for threading replies).
+        // ts = this specific message (for reactions).
+        const threadTs = String(event.thread_ts ?? event.ts ?? "");
+        const messageTs = String(event.ts ?? "");
+        const channel = String(event.channel ?? "");
+        const userId = String(event.user ?? "");
+
+        const message: PonchoIncomingMessage = {
+          text,
+          threadRef: {
+            platformThreadId: threadTs,
+            channelId: channel,
+            messageId: messageTs,
+          },
+          sender: { id: userId },
+          platform: "slack",
+          raw: event,
+        };
+
+        // Processing is fire-and-forget; the bridge's waitUntil keeps
+        // serverless functions alive.  If the handler was wired via
+        // AgentBridge.scheduleProcessing, it already uses waitUntil.
+        // If wired via onMessage, we await here (long-running server).
+        void this.handler(message).catch((err) => {
+          console.error("[slack-adapter] unhandled message handler error", err);
+        });
+      }
+
+      return;
+    }
+
+    // Unknown payload type
+    res.writeHead(200);
+    res.end();
+  }
+}