@poncho-ai/messaging 0.2.0

package/src/adapters/slack/utils.ts

@@ -0,0 +1,107 @@
+const SLACK_MAX_MESSAGE_LENGTH = 4000;
+const MENTION_PATTERN = /^\s*<@[A-Z0-9]+>\s*/i;
+
+/** Strip the leading `<@BOT_ID>` mention from a Slack message. */
+export const stripMention = (text: string): string =>
+  text.replace(MENTION_PATTERN, "").trim();
+
+/**
+ * Split a long message into chunks that fit within Slack's character limit.
+ * Attempts to split on newlines, falling back to hard cuts.
+ */
+export const splitMessage = (text: string): string[] => {
+  if (text.length <= SLACK_MAX_MESSAGE_LENGTH) return [text];
+
+  const chunks: string[] = [];
+  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;
+};
+
+// ---------------------------------------------------------------------------
+// Minimal Slack Web API helpers (avoids @slack/web-api dependency)
+// ---------------------------------------------------------------------------
+
+const SLACK_API = "https://slack.com/api";
+
+const slackFetch = async (
+  method: string,
+  token: string,
+  body: Record<string, unknown>,
+): Promise<{ ok: boolean; error?: string }> => {
+  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()) as { ok: boolean; error?: string };
+};
+
+export const postMessage = async (
+  token: string,
+  channel: string,
+  text: string,
+  threadTs: string,
+): Promise<void> => {
+  const result = await slackFetch("chat.postMessage", token, {
+    channel,
+    text,
+    thread_ts: threadTs,
+  });
+  if (!result.ok) {
+    throw new Error(`Slack chat.postMessage failed: ${result.error}`);
+  }
+};
+
+export const addReaction = async (
+  token: string,
+  channel: string,
+  timestamp: string,
+  reaction: string,
+): Promise<void> => {
+  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}`);
+  }
+};
+
+export const removeReaction = async (
+  token: string,
+  channel: string,
+  timestamp: string,
+  reaction: string,
+): Promise<void> => {
+  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}`);
+  }
+};

package/src/adapters/slack/verify.ts

@@ -0,0 +1,32 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const MAX_TIMESTAMP_DRIFT_SECONDS = 300; // 5 minutes
+
+/**
+ * Verify a Slack request signature per
+ * https://api.slack.com/authentication/verifying-requests-from-slack
+ */
+export const verifySlackSignature = (
+  signingSecret: string,
+  headers: {
+    signature: string | undefined;
+    timestamp: string | undefined;
+  },
+  rawBody: string,
+): boolean => {
+  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() / 1000) - 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));
+};

package/src/bridge.ts

@@ -0,0 +1,88 @@
+import type {
+  AgentBridgeOptions,
+  IncomingMessage,
+  MessagingAdapter,
+  AgentRunner,
+  ThreadRef,
+} from "./types.js";
+
+/**
+ * Derive a stable conversation ID from a platform thread reference.
+ * Format: `<platform>:<channelId>:<threadId>`
+ */
+const conversationIdFromThread = (
+  platform: string,
+  ref: ThreadRef,
+): string => `${platform}:${ref.channelId}:${ref.platformThreadId}`;
+
+export class AgentBridge {
+  private readonly adapter: MessagingAdapter;
+  private readonly runner: AgentRunner;
+  private readonly waitUntil: (promise: Promise<unknown>) => void;
+
+  constructor(options: AgentBridgeOptions) {
+    this.adapter = options.adapter;
+    this.runner = options.runner;
+    this.waitUntil = options.waitUntil ?? ((_p: Promise<unknown>) => {});
+  }
+
+  /** Wire the adapter's message handler and initialise. */
+  async start(): Promise<void> {
+    this.adapter.onMessage((msg) => {
+      const processing = this.handleMessage(msg);
+      // On serverless (Vercel), waitUntil keeps the function alive after
+      // the HTTP 200 response so the agent run completes.
+      this.waitUntil(processing);
+      return processing;
+    });
+    await this.adapter.initialize();
+  }
+
+  private async handleMessage(message: IncomingMessage): Promise<void> {
+    let cleanup: (() => Promise<void>) | undefined;
+
+    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 {
+        // Best-effort error reporting — nothing more we can do.
+      }
+    } finally {
+      if (cleanup) {
+        try {
+          await cleanup();
+        } catch {
+          // Indicator removal is best-effort.
+        }
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export type {
+  AgentBridgeOptions,
+  AgentRunner,
+  IncomingMessage,
+  IncomingMessageHandler,
+  MessagingAdapter,
+  RouteHandler,
+  RouteRegistrar,
+  ThreadRef,
+} from "./types.js";
+
+export { AgentBridge } from "./bridge.js";
+export { SlackAdapter } from "./adapters/slack/index.js";
+export type { SlackAdapterOptions } from "./adapters/slack/index.js";

package/src/types.ts

@@ -0,0 +1,98 @@
+import type http from "node:http";
+import type { Message } from "@poncho-ai/sdk";
+
+// ---------------------------------------------------------------------------
+// Thread & message primitives
+// ---------------------------------------------------------------------------
+
+export interface ThreadRef {
+  platformThreadId: string;
+  channelId: string;
+  /** The specific message ID that triggered this interaction (for reactions). */
+  messageId?: string;
+}
+
+export interface IncomingMessage {
+  text: string;
+  threadRef: ThreadRef;
+  sender: { id: string; name?: string };
+  platform: string;
+  raw: unknown;
+}
+
+export type IncomingMessageHandler = (
+  message: IncomingMessage,
+) => Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Route registration (adapter ↔ HTTP server contract)
+// ---------------------------------------------------------------------------
+
+export type RouteHandler = (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+) => Promise<void>;
+
+export type RouteRegistrar = (
+  method: "GET" | "POST",
+  path: string,
+  handler: RouteHandler,
+) => void;
+
+// ---------------------------------------------------------------------------
+// Messaging adapter interface (one per platform)
+// ---------------------------------------------------------------------------
+
+export 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>>;
+}
+
+// ---------------------------------------------------------------------------
+// Agent runner interface (bridge ↔ agent contract)
+// ---------------------------------------------------------------------------
+
+export 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 }>;
+}
+
+// ---------------------------------------------------------------------------
+// Bridge options
+// ---------------------------------------------------------------------------
+
+export 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;
+}

package/test/adapters/slack.test.ts

@@ -0,0 +1,241 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+import { verifySlackSignature } from "../../src/adapters/slack/verify.js";
+import { splitMessage, stripMention } from "../../src/adapters/slack/utils.js";
+import { SlackAdapter } from "../../src/adapters/slack/index.js";
+import type { IncomingMessage as PonchoIncomingMessage } from "../../src/types.js";
+
+// ---------------------------------------------------------------------------
+// Signature verification
+// ---------------------------------------------------------------------------
+
+describe("verifySlackSignature", () => {
+  const secret = "test-signing-secret";
+
+  const sign = (body: string, timestamp: number): string => {
+    const basestring = `v0:${timestamp}:${body}`;
+    return `v0=${createHmac("sha256", secret).update(basestring).digest("hex")}`;
+  };
+
+  it("accepts a valid signature", () => {
+    const ts = Math.floor(Date.now() / 1000);
+    const body = '{"type":"event_callback"}';
+    const sig = sign(body, ts);
+
+    expect(
+      verifySlackSignature(secret, { signature: sig, timestamp: String(ts) }, body),
+    ).toBe(true);
+  });
+
+  it("rejects a tampered body", () => {
+    const ts = Math.floor(Date.now() / 1000);
+    const sig = sign("original", ts);
+
+    expect(
+      verifySlackSignature(secret, { signature: sig, timestamp: String(ts) }, "tampered"),
+    ).toBe(false);
+  });
+
+  it("rejects when timestamp is too old", () => {
+    const ts = Math.floor(Date.now() / 1000) - 600;
+    const body = "body";
+    const sig = sign(body, ts);
+
+    expect(
+      verifySlackSignature(secret, { signature: sig, timestamp: String(ts) }, body),
+    ).toBe(false);
+  });
+
+  it("rejects missing headers", () => {
+    expect(
+      verifySlackSignature(secret, { signature: undefined, timestamp: undefined }, "body"),
+    ).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Utility functions
+// ---------------------------------------------------------------------------
+
+describe("stripMention", () => {
+  it("removes a leading bot mention", () => {
+    expect(stripMention("<@U12345> what is the weather?")).toBe("what is the weather?");
+  });
+
+  it("handles multiple mentions (only strips leading)", () => {
+    expect(stripMention("<@U12345> ping <@U99999>")).toBe("ping <@U99999>");
+  });
+
+  it("returns the text unchanged when no mention", () => {
+    expect(stripMention("hello world")).toBe("hello world");
+  });
+
+  it("handles whitespace around the mention", () => {
+    expect(stripMention("  <@UABC>  hello  ")).toBe("hello");
+  });
+});
+
+describe("splitMessage", () => {
+  it("returns a single chunk for short messages", () => {
+    expect(splitMessage("short")).toEqual(["short"]);
+  });
+
+  it("splits long messages at newlines", () => {
+    const line = "x".repeat(3000);
+    const text = `${line}\n${"y".repeat(2000)}`;
+    const chunks = splitMessage(text);
+    expect(chunks.length).toBe(2);
+    expect(chunks[0]).toBe(line);
+    expect(chunks[1]).toBe("y".repeat(2000));
+  });
+
+  it("hard-cuts when there are no newlines", () => {
+    const text = "a".repeat(5000);
+    const chunks = splitMessage(text);
+    expect(chunks.length).toBe(2);
+    expect(chunks[0]!.length).toBe(4000);
+    expect(chunks[1]!.length).toBe(1000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SlackAdapter
+// ---------------------------------------------------------------------------
+
+describe("SlackAdapter", () => {
+  const secret = "test-secret";
+  const token = "xoxb-test-token";
+
+  beforeEach(() => {
+    process.env.SLACK_BOT_TOKEN = token;
+    process.env.SLACK_SIGNING_SECRET = secret;
+  });
+
+  afterEach(() => {
+    delete process.env.SLACK_BOT_TOKEN;
+    delete process.env.SLACK_SIGNING_SECRET;
+    vi.restoreAllMocks();
+  });
+
+  const makeReqRes = (
+    body: string,
+    headers: Record<string, string> = {},
+  ): { req: any; res: any; resBody: () => string; resStatus: () => number } => {
+    const ts = String(Math.floor(Date.now() / 1000));
+    const sig = `v0=${createHmac("sha256", secret).update(`v0:${ts}:${body}`).digest("hex")}`;
+
+    let _resBody = "";
+    let _resStatus = 0;
+    const dataListeners: Array<(chunk: Buffer) => void> = [];
+    const endListeners: Array<() => void> = [];
+    const errorListeners: Array<(err: Error) => void> = [];
+
+    const req = {
+      method: "POST",
+      url: "/api/messaging/slack",
+      headers: {
+        "x-slack-signature": sig,
+        "x-slack-request-timestamp": ts,
+        ...headers,
+      },
+      on(event: string, cb: (...args: any[]) => void) {
+        if (event === "data") {
+          dataListeners.push(cb as any);
+        } else if (event === "end") {
+          endListeners.push(cb as any);
+        } else if (event === "error") {
+          errorListeners.push(cb as any);
+        }
+        // Fire body data on next tick after both data+end listeners are registered
+        if (dataListeners.length > 0 && endListeners.length > 0) {
+          queueMicrotask(() => {
+            for (const fn of dataListeners) fn(Buffer.from(body));
+            for (const fn of endListeners) fn();
+          });
+        }
+        return req;
+      },
+    };
+
+    const res = {
+      writeHead(status: number, _headers?: Record<string, string>) {
+        _resStatus = status;
+      },
+      end(data?: string) {
+        _resBody = data ?? "";
+      },
+    };
+
+    return {
+      req,
+      res,
+      resBody: () => _resBody,
+      resStatus: () => _resStatus,
+    };
+  };
+
+  it("initializes successfully with valid env vars", async () => {
+    const adapter = new SlackAdapter();
+    await expect(adapter.initialize()).resolves.not.toThrow();
+  });
+
+  it("throws on missing SLACK_BOT_TOKEN", async () => {
+    delete process.env.SLACK_BOT_TOKEN;
+    const adapter = new SlackAdapter();
+    await expect(adapter.initialize()).rejects.toThrow("SLACK_BOT_TOKEN");
+  });
+
+  it("throws on missing SLACK_SIGNING_SECRET", async () => {
+    delete process.env.SLACK_SIGNING_SECRET;
+    const adapter = new SlackAdapter();
+    await expect(adapter.initialize()).rejects.toThrow("SLACK_SIGNING_SECRET");
+  });
+
+  it("registers a POST route at /api/messaging/slack", () => {
+    const adapter = new SlackAdapter();
+    const routes: Array<{ method: string; path: string }> = [];
+    adapter.registerRoutes((method, path) => {
+      routes.push({ method, path });
+    });
+    expect(routes).toEqual([{ method: "POST", path: "/api/messaging/slack" }]);
+  });
+
+  it("handles url_verification challenge", async () => {
+    const adapter = new SlackAdapter();
+    await adapter.initialize();
+
+    let handler: any;
+    adapter.registerRoutes((_m, _p, h) => { handler = h; });
+
+    const body = JSON.stringify({ type: "url_verification", challenge: "abc123" });
+    const { req, res, resBody } = makeReqRes(body);
+
+    await handler(req, res);
+
+    const parsed = JSON.parse(resBody());
+    expect(parsed.challenge).toBe("abc123");
+  });
+
+  it("skips retry requests", async () => {
+    const adapter = new SlackAdapter();
+    await adapter.initialize();
+    const received: PonchoIncomingMessage[] = [];
+    adapter.onMessage(async (msg) => { received.push(msg); });
+
+    let handler: any;
+    adapter.registerRoutes((_m, _p, h) => { handler = h; });
+
+    const body = JSON.stringify({
+      type: "event_callback",
+      event: { type: "app_mention", text: "<@U1> hi", ts: "1", channel: "C1", user: "U2" },
+    });
+    const { req, res, resStatus } = makeReqRes(body, { "x-slack-retry-num": "1" });
+
+    await handler(req, res);
+
+    // Give time for any async handler to fire
+    await new Promise((r) => setTimeout(r, 50));
+    expect(received).toHaveLength(0);
+    expect(resStatus()).toBe(200);
+  });
+});