@poncho-ai/messaging 0.2.0 → 0.2.2

package/src/bridge.ts

@@ -19,11 +19,13 @@ export class AgentBridge {
   private readonly adapter: MessagingAdapter;
   private readonly runner: AgentRunner;
   private readonly waitUntil: (promise: Promise<unknown>) => void;
+  private readonly ownerIdOverride: string | undefined;
 
   constructor(options: AgentBridgeOptions) {
     this.adapter = options.adapter;
     this.runner = options.runner;
     this.waitUntil = options.waitUntil ?? ((_p: Promise<unknown>) => {});
+    this.ownerIdOverride = options.ownerId;
   }
 
   /** Wire the adapter's message handler and initialise. */
@@ -41,6 +43,8 @@ export class AgentBridge {
   private async handleMessage(message: IncomingMessage): Promise<void> {
     let cleanup: (() => Promise<void>) | undefined;
 
+    this.adapter.resetRequestState?.();
+
     try {
       cleanup = await this.adapter.indicateProcessing(message.threadRef);
 
@@ -49,31 +53,57 @@ export class AgentBridge {
         message.threadRef,
       );
 
+      const titleParts = [message.sender.id];
+      if (message.subject) titleParts.push(message.subject);
+      const title = titleParts.join(" — ") || `${message.platform} thread`;
+
       const conversation = await this.runner.getOrCreateConversation(
         conversationId,
         {
           platform: message.platform,
-          ownerId: message.sender.id,
-          title: `${message.platform} thread`,
+          ownerId: this.ownerIdOverride ?? message.sender.id,
+          title,
         },
       );
 
+      const senderLine = message.sender.name
+        ? `From: ${message.sender.name} <${message.sender.id}>`
+        : `From: ${message.sender.id}`;
+      const subjectLine = message.subject ? `Subject: ${message.subject}` : "";
+      const header = [senderLine, subjectLine].filter(Boolean).join("\n");
+      const task = `${header}\n\n${message.text}`;
+
       const result = await this.runner.run(conversationId, {
-        task: message.text,
+        task,
         messages: conversation.messages,
+        files: message.files,
+        metadata: {
+          platform: message.platform,
+          sender: message.sender,
+          threadId: message.threadRef.platformThreadId,
+        },
       });
 
-      await this.adapter.sendReply(message.threadRef, result.response);
+      if (this.adapter.autoReply) {
+        await this.adapter.sendReply(message.threadRef, result.response, {
+          files: result.files,
+        });
+      } else if (!this.adapter.hasSentInCurrentRequest) {
+        console.warn("[agent-bridge] tool mode completed without send_email being called; no reply sent");
+      }
     } 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.
+      console.error("[agent-bridge] handleMessage error:", error instanceof Error ? error.message : error);
+      if (!this.adapter.hasSentInCurrentRequest) {
+        const snippet =
+          error instanceof Error ? error.message : "Unknown error";
+        try {
+          await this.adapter.sendReply(
+            message.threadRef,
+            `Sorry, something went wrong: ${snippet}`,
+          );
+        } catch (replyError) {
+          console.error("[agent-bridge] failed to send error reply:", replyError instanceof Error ? replyError.message : replyError);
+        }
       }
     } finally {
       if (cleanup) {

package/src/index.ts

@@ -1,6 +1,7 @@
 export type {
   AgentBridgeOptions,
   AgentRunner,
+  FileAttachment,
   IncomingMessage,
   IncomingMessageHandler,
   MessagingAdapter,
@@ -12,3 +13,17 @@ export type {
 export { AgentBridge } from "./bridge.js";
 export { SlackAdapter } from "./adapters/slack/index.js";
 export type { SlackAdapterOptions } from "./adapters/slack/index.js";
+export { ResendAdapter } from "./adapters/resend/index.js";
+export type { ResendAdapterOptions } from "./adapters/resend/index.js";
+
+export {
+  buildReplyHeaders,
+  buildReplySubject,
+  deriveRootMessageId,
+  extractDisplayName,
+  extractEmailAddress,
+  markdownToEmailHtml,
+  matchesSenderPattern,
+  parseReferences,
+  stripQuotedReply,
+} from "./adapters/email/utils.js";

package/src/types.ts

@@ -1,5 +1,5 @@
 import type http from "node:http";
-import type { Message } from "@poncho-ai/sdk";
+import type { Message, ToolDefinition } from "@poncho-ai/sdk";
 
 // ---------------------------------------------------------------------------
 // Thread & message primitives
@@ -12,8 +12,17 @@ export interface ThreadRef {
   messageId?: string;
 }
 
+export interface FileAttachment {
+  /** base64-encoded file data */
+  data: string;
+  mediaType: string;
+  filename?: string;
+}
+
 export interface IncomingMessage {
   text: string;
+  subject?: string;
+  files?: FileAttachment[];
   threadRef: ThreadRef;
   sender: { id: string; name?: string };
   platform: string;
@@ -46,6 +55,15 @@ export type RouteRegistrar = (
 export interface MessagingAdapter {
   readonly platform: string;
 
+  /** When true, the bridge auto-sends the agent's response as a reply. */
+  readonly autoReply: boolean;
+
+  /**
+   * Whether the adapter's tool has sent at least one message during the
+   * current request. Used by the bridge to suppress duplicate error replies.
+   */
+  readonly hasSentInCurrentRequest: boolean;
+
   /** Register HTTP routes on the host server for receiving platform events. */
   registerRoutes(router: RouteRegistrar): void;
 
@@ -56,7 +74,11 @@ export interface MessagingAdapter {
   onMessage(handler: IncomingMessageHandler): void;
 
   /** Post a reply back to the originating thread. */
-  sendReply(threadRef: ThreadRef, content: string): Promise<void>;
+  sendReply(
+    threadRef: ThreadRef,
+    content: string,
+    options?: { files?: FileAttachment[] },
+  ): Promise<void>;
 
   /**
    * Show a processing indicator (e.g. reaction, typing).
@@ -65,6 +87,15 @@ export interface MessagingAdapter {
   indicateProcessing(
     threadRef: ThreadRef,
   ): Promise<() => Promise<void>>;
+
+  /**
+   * Optional: return tool definitions the agent can use (e.g. send_email).
+   * Called once after initialization to register tools with the harness.
+   */
+  getToolDefinitions?(): ToolDefinition[];
+
+  /** Reset per-request state (e.g. send counter, hasSentInCurrentRequest). */
+  resetRequestState?(): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -79,8 +110,20 @@ export interface AgentRunner {
 
   run(
     conversationId: string,
-    input: { task: string; messages: Message[] },
-  ): Promise<{ response: string }>;
+    input: {
+      task: string;
+      messages: Message[];
+      files?: FileAttachment[];
+      metadata?: {
+        platform: string;
+        sender: { id: string; name?: string };
+        threadId: string;
+      };
+    },
+  ): Promise<{
+    response: string;
+    files?: FileAttachment[];
+  }>;
 }
 
 // ---------------------------------------------------------------------------
@@ -95,4 +138,10 @@ export interface AgentBridgeOptions {
    * On Vercel, pass the real `waitUntil` from `@vercel/functions`.
    */
   waitUntil?: (promise: Promise<unknown>) => void;
+  /**
+   * Override the ownerId for conversations created by this bridge.
+   * Defaults to the sender's ID. Set to a fixed value (e.g. "local-owner")
+   * so messaging conversations appear in the web UI alongside regular ones.
+   */
+  ownerId?: string;
 }

package/test/adapters/email-utils.test.ts

@@ -0,0 +1,290 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildReplyHeaders,
+  buildReplySubject,
+  deriveRootMessageId,
+  extractDisplayName,
+  extractEmailAddress,
+  markdownToEmailHtml,
+  matchesSenderPattern,
+  parseReferences,
+  stripQuotedReply,
+} from "../../src/adapters/email/utils.js";
+
+// ---------------------------------------------------------------------------
+// extractEmailAddress
+// ---------------------------------------------------------------------------
+
+describe("extractEmailAddress", () => {
+  it("extracts from formatted address", () => {
+    expect(extractEmailAddress("Alice <alice@example.com>")).toBe("alice@example.com");
+  });
+
+  it("handles bare email", () => {
+    expect(extractEmailAddress("bob@test.com")).toBe("bob@test.com");
+  });
+
+  it("lowercases the result", () => {
+    expect(extractEmailAddress("Alice <Alice@Example.COM>")).toBe("alice@example.com");
+  });
+
+  it("handles quoted display name", () => {
+    expect(extractEmailAddress('"Alice B" <alice@example.com>')).toBe("alice@example.com");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractDisplayName
+// ---------------------------------------------------------------------------
+
+describe("extractDisplayName", () => {
+  it("extracts name from formatted address", () => {
+    expect(extractDisplayName("Alice <alice@example.com>")).toBe("Alice");
+  });
+
+  it("returns undefined for bare email", () => {
+    expect(extractDisplayName("bob@test.com")).toBeUndefined();
+  });
+
+  it("strips surrounding quotes", () => {
+    expect(extractDisplayName('"Alice B" <alice@example.com>')).toBe("Alice B");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseReferences
+// ---------------------------------------------------------------------------
+
+describe("parseReferences", () => {
+  it("parses space-separated message IDs", () => {
+    const headers = [
+      { name: "References", value: "<msg1@a.com> <msg2@b.com> <msg3@c.com>" },
+    ];
+    expect(parseReferences(headers)).toEqual([
+      "<msg1@a.com>",
+      "<msg2@b.com>",
+      "<msg3@c.com>",
+    ]);
+  });
+
+  it("returns empty array when no References header", () => {
+    expect(parseReferences([{ name: "Subject", value: "hi" }])).toEqual([]);
+  });
+
+  it("returns empty array for undefined headers", () => {
+    expect(parseReferences(undefined)).toEqual([]);
+  });
+
+  it("is case-insensitive for header name", () => {
+    const headers = [{ name: "references", value: "<msg@a.com>" }];
+    expect(parseReferences(headers)).toEqual(["<msg@a.com>"]);
+  });
+
+  it("handles object-style headers (Record<string, string>)", () => {
+    const headers = { References: "<msg1@a.com> <msg2@b.com>" };
+    expect(parseReferences(headers)).toEqual(["<msg1@a.com>", "<msg2@b.com>"]);
+  });
+
+  it("handles object-style headers case-insensitively", () => {
+    const headers = { references: "<msg@a.com>" };
+    expect(parseReferences(headers)).toEqual(["<msg@a.com>"]);
+  });
+
+  it("returns empty array for object headers without References", () => {
+    const headers = { Subject: "hi", From: "alice@a.com" };
+    expect(parseReferences(headers)).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deriveRootMessageId
+// ---------------------------------------------------------------------------
+
+describe("deriveRootMessageId", () => {
+  it("returns first reference when available", () => {
+    expect(
+      deriveRootMessageId(["<root@a.com>", "<reply@a.com>"], "<current@a.com>"),
+    ).toBe("<root@a.com>");
+  });
+
+  it("falls back to subject+sender hash when no references", () => {
+    const result = deriveRootMessageId([], "<current@a.com>", {
+      subject: "Hello",
+      sender: "alice@example.com",
+    });
+    expect(result).toMatch(/^<fallback:[0-9a-f]+>$/);
+  });
+
+  it("produces stable fallback for same subject+sender", () => {
+    const a = deriveRootMessageId([], "<a@a.com>", { subject: "Hello", sender: "alice@a.com" });
+    const b = deriveRootMessageId([], "<b@b.com>", { subject: "Hello", sender: "alice@a.com" });
+    expect(a).toBe(b);
+  });
+
+  it("normalises Re: prefixes in fallback", () => {
+    const a = deriveRootMessageId([], "<a@a.com>", { subject: "Hello", sender: "alice@a.com" });
+    const b = deriveRootMessageId([], "<b@b.com>", { subject: "Re: Hello", sender: "alice@a.com" });
+    expect(a).toBe(b);
+  });
+
+  it("falls back to current message ID as last resort", () => {
+    expect(deriveRootMessageId([], "<current@a.com>")).toBe("<current@a.com>");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildReplySubject
+// ---------------------------------------------------------------------------
+
+describe("buildReplySubject", () => {
+  it("prepends Re: to a plain subject", () => {
+    expect(buildReplySubject("Q4 Revenue")).toBe("Re: Q4 Revenue");
+  });
+
+  it("does not double-prefix", () => {
+    expect(buildReplySubject("Re: Q4 Revenue")).toBe("Re: Q4 Revenue");
+  });
+
+  it("handles case-insensitive Re:", () => {
+    expect(buildReplySubject("RE: Q4 Revenue")).toBe("RE: Q4 Revenue");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildReplyHeaders
+// ---------------------------------------------------------------------------
+
+describe("buildReplyHeaders", () => {
+  it("builds In-Reply-To and References headers", () => {
+    const headers = buildReplyHeaders("<msg2@a.com>", ["<msg1@a.com>"]);
+    expect(headers["In-Reply-To"]).toBe("<msg2@a.com>");
+    expect(headers["References"]).toBe("<msg1@a.com> <msg2@a.com>");
+  });
+
+  it("does not duplicate inReplyTo in references", () => {
+    const headers = buildReplyHeaders("<msg1@a.com>", ["<msg1@a.com>"]);
+    expect(headers["References"]).toBe("<msg1@a.com>");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// stripQuotedReply
+// ---------------------------------------------------------------------------
+
+describe("stripQuotedReply", () => {
+  it("strips Gmail-style quoted replies", () => {
+    const text = "Thanks for the info.\n\nOn Mon, Jan 1, 2024, Alice wrote:\n> Previous message";
+    expect(stripQuotedReply(text)).toBe("Thanks for the info.");
+  });
+
+  it("strips Outlook-style original message markers", () => {
+    const text = "Got it.\n\n-----Original Message-----\nFrom: Bob\nSent: Monday";
+    expect(stripQuotedReply(text)).toBe("Got it.");
+  });
+
+  it("strips Outlook From:/Sent: header blocks", () => {
+    const text = "Sure thing.\n\nFrom: Alice <alice@example.com>\nSent: Monday, January 1\nTo: Bob";
+    expect(stripQuotedReply(text)).toBe("Sure thing.");
+  });
+
+  it("strips > quoting after a blank line", () => {
+    const text = "My reply.\n\n> Previous line 1\n> Previous line 2";
+    expect(stripQuotedReply(text)).toBe("My reply.");
+  });
+
+  it("preserves text with no quoted content", () => {
+    const text = "Just a plain message.";
+    expect(stripQuotedReply(text)).toBe("Just a plain message.");
+  });
+
+  it("preserves > that is not a quote (no blank line before)", () => {
+    const text = "The value should be > 5\nand also > 10";
+    expect(stripQuotedReply(text)).toBe("The value should be > 5\nand also > 10");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// markdownToEmailHtml
+// ---------------------------------------------------------------------------
+
+describe("markdownToEmailHtml", () => {
+  it("wraps output in a styled div", () => {
+    const html = markdownToEmailHtml("Hello");
+    expect(html).toContain("<div");
+    expect(html).toContain("font-family:");
+  });
+
+  it("converts bold text", () => {
+    const html = markdownToEmailHtml("This is **bold** text.");
+    expect(html).toContain("<strong>bold</strong>");
+  });
+
+  it("converts inline code", () => {
+    const html = markdownToEmailHtml("Use `npm install`.");
+    expect(html).toContain("<code");
+    expect(html).toContain("npm install");
+  });
+
+  it("converts fenced code blocks", () => {
+    const html = markdownToEmailHtml("```js\nconsole.log('hi');\n```");
+    expect(html).toContain("<pre");
+    expect(html).toContain("console.log");
+  });
+
+  it("converts unordered lists", () => {
+    const html = markdownToEmailHtml("- Item A\n- Item B");
+    expect(html).toContain("<ul");
+    expect(html).toContain("<li>Item A</li>");
+  });
+
+  it("converts ordered lists", () => {
+    const html = markdownToEmailHtml("1. First\n2. Second");
+    expect(html).toContain("<ol");
+    expect(html).toContain("<li>First</li>");
+  });
+
+  it("escapes HTML entities", () => {
+    const html = markdownToEmailHtml("Use <script> & stuff");
+    expect(html).toContain("&lt;script&gt;");
+    expect(html).toContain("&amp;");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// matchesSenderPattern
+// ---------------------------------------------------------------------------
+
+describe("matchesSenderPattern", () => {
+  it("returns true when no patterns (open inbox)", () => {
+    expect(matchesSenderPattern("anyone@anywhere.com", undefined)).toBe(true);
+    expect(matchesSenderPattern("anyone@anywhere.com", [])).toBe(true);
+  });
+
+  it("matches exact email", () => {
+    expect(matchesSenderPattern("alice@example.com", ["alice@example.com"])).toBe(true);
+  });
+
+  it("rejects non-matching email", () => {
+    expect(matchesSenderPattern("bob@other.com", ["alice@example.com"])).toBe(false);
+  });
+
+  it("matches domain wildcard", () => {
+    expect(matchesSenderPattern("anyone@myco.com", ["*@myco.com"])).toBe(true);
+  });
+
+  it("rejects non-matching domain", () => {
+    expect(matchesSenderPattern("anyone@other.com", ["*@myco.com"])).toBe(false);
+  });
+
+  it("is case-insensitive", () => {
+    expect(matchesSenderPattern("Alice@EXAMPLE.com", ["alice@example.com"])).toBe(true);
+    expect(matchesSenderPattern("Alice@MYCO.COM", ["*@myco.com"])).toBe(true);
+  });
+
+  it("matches against multiple patterns", () => {
+    const patterns = ["alice@a.com", "*@b.com"];
+    expect(matchesSenderPattern("alice@a.com", patterns)).toBe(true);
+    expect(matchesSenderPattern("bob@b.com", patterns)).toBe(true);
+    expect(matchesSenderPattern("carol@c.com", patterns)).toBe(false);
+  });
+});

package/test/adapters/resend.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from "vitest";
+import { ResendAdapter } from "../../src/adapters/resend/index.js";
+import type { RouteRegistrar } from "../../src/types.js";
+
+/**
+ * Since the ResendAdapter dynamically imports `resend`, we test the parts that
+ * don't require a live Resend client: route registration, construction, and
+ * the allowlist/dedup logic via the exported class shape.
+ *
+ * Full integration tests require mocking the Resend SDK which is covered
+ * separately if needed.
+ */
+
+describe("ResendAdapter", () => {
+  it("registers a POST route at /api/messaging/resend", () => {
+    const adapter = new ResendAdapter();
+    const routes: Array<{ method: string; path: string }> = [];
+    const registrar: RouteRegistrar = (method, path) => {
+      routes.push({ method, path });
+    };
+    adapter.registerRoutes(registrar);
+    expect(routes).toEqual([{ method: "POST", path: "/api/messaging/resend" }]);
+  });
+
+  it("has platform set to 'resend'", () => {
+    const adapter = new ResendAdapter();
+    expect(adapter.platform).toBe("resend");
+  });
+
+  it("indicateProcessing returns a no-op cleanup function", async () => {
+    const adapter = new ResendAdapter();
+    const cleanup = await adapter.indicateProcessing({
+      platformThreadId: "t1",
+      channelId: "c1",
+    });
+    await expect(cleanup()).resolves.toBeUndefined();
+  });
+
+  it("accepts custom env var names", () => {
+    const adapter = new ResendAdapter({
+      apiKeyEnv: "MY_RESEND_KEY",
+      webhookSecretEnv: "MY_WEBHOOK_SECRET",
+      fromEnv: "MY_FROM",
+    });
+    // If env vars are not set, initialize should throw with the custom name
+    expect(
+      adapter.initialize(),
+    ).rejects.toThrow("MY_RESEND_KEY");
+  });
+
+  it("throws on initialize when RESEND_API_KEY is missing", async () => {
+    const adapter = new ResendAdapter();
+    await expect(adapter.initialize()).rejects.toThrow("RESEND_API_KEY");
+  });
+
+  it("stores allowed senders from options", () => {
+    const adapter = new ResendAdapter({
+      allowedSenders: ["*@myco.com"],
+    });
+    expect(adapter.platform).toBe("resend");
+  });
+
+  describe("mode configuration", () => {
+    it("defaults to auto-reply mode", () => {
+      const adapter = new ResendAdapter();
+      expect(adapter.autoReply).toBe(true);
+    });
+
+    it("sets autoReply to false in tool mode", () => {
+      const adapter = new ResendAdapter({ mode: "tool" });
+      expect(adapter.autoReply).toBe(false);
+    });
+
+    it("sets autoReply to true in auto-reply mode", () => {
+      const adapter = new ResendAdapter({ mode: "auto-reply" });
+      expect(adapter.autoReply).toBe(true);
+    });
+
+    it("returns send_email tool definitions in tool mode", () => {
+      const adapter = new ResendAdapter({ mode: "tool" });
+      const tools = adapter.getToolDefinitions();
+      expect(tools).toHaveLength(1);
+      expect(tools[0]!.name).toBe("send_email");
+      expect(tools[0]!.inputSchema.required).toEqual(["to", "subject", "body"]);
+    });
+
+    it("returns empty tool definitions in auto-reply mode", () => {
+      const adapter = new ResendAdapter({ mode: "auto-reply" });
+      const tools = adapter.getToolDefinitions();
+      expect(tools).toHaveLength(0);
+    });
+
+    it("returns empty tool definitions in default mode", () => {
+      const adapter = new ResendAdapter();
+      const tools = adapter.getToolDefinitions();
+      expect(tools).toHaveLength(0);
+    });
+  });
+
+  describe("resetRequestState", () => {
+    it("resets hasSentInCurrentRequest flag", () => {
+      const adapter = new ResendAdapter({ mode: "tool" });
+      (adapter as unknown as { hasSentInCurrentRequest: boolean }).hasSentInCurrentRequest = true;
+      adapter.resetRequestState!();
+      expect(adapter.hasSentInCurrentRequest).toBe(false);
+    });
+  });
+});