@poncho-ai/messaging 0.2.0 → 0.2.2

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/messaging@0.2.0 build /home/runner/work/poncho-ai/poncho-ai/packages/messaging
+> @poncho-ai/messaging@0.2.2 build /Users/cesar/Dev/latitude/poncho-ai/packages/messaging
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -7,8 +7,8 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js 8.45 KB
-ESM ⚡️ Build success in 29ms
+ESM dist/index.js 29.35 KB
+ESM ⚡️ Build success in 39ms
 DTS Build start
-DTS ⚡️ Build success in 2735ms
-DTS dist/index.d.ts 3.23 KB
+DTS ⚡️ Build success in 1509ms
+DTS dist/index.d.ts 8.89 KB

package/.turbo/turbo-test.log

@@ -0,0 +1,29 @@
+
+> @poncho-ai/messaging@0.2.0 test /Users/cesar/Dev/latitude/poncho-ai/packages/messaging
+> vitest
+
+
+ RUN  v1.6.1 /Users/cesar/Dev/latitude/poncho-ai/packages/messaging
+
+stderr | test/bridge.test.ts > AgentBridge > posts an error message and cleans up on runner failure
+[agent-bridge] handleMessage error: Model overloaded
+
+stderr | test/bridge.test.ts > AgentBridge > skips sendReply when autoReply is false
+[agent-bridge] tool mode completed without send_email being called; no reply sent
+
+stderr | test/bridge.test.ts > AgentBridge > suppresses error reply when hasSentInCurrentRequest is true
+[agent-bridge] handleMessage error: Oops
+
+stderr | test/bridge.test.ts > AgentBridge > calls resetRequestState before handling each message
+[agent-bridge] tool mode completed without send_email being called; no reply sent
+
+ ✓ test/bridge.test.ts  (15 tests) 12ms
+ ✓ test/adapters/email-utils.test.ts  (44 tests) 79ms
+ ✓ test/adapters/resend.test.ts  (13 tests) 11ms
+ ✓ test/adapters/slack.test.ts  (17 tests) 62ms
+
+ Test Files  4 passed (4)
+      Tests  89 passed (89)
+   Start at  09:39:50
+   Duration  1.33s (transform 355ms, setup 0ms, collect 774ms, tests 164ms, environment 1ms, prepare 1.04s)
+

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @poncho-ai/messaging
 
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies [[`1f47bb4`](https://github.com/cesr/poncho-ai/commit/1f47bb49e5d48dc17644172012b057190b316469)]:
+  - @poncho-ai/sdk@1.0.3
+
+## 0.2.1
+
+### Patch Changes
+
+- [`e000b96`](https://github.com/cesr/poncho-ai/commit/e000b96837cbbb8d95c868c91a614f458868c444) Thanks [@cesr](https://github.com/cesr)! - Durable approval checkpoints, email conversation improvements, and web UI fixes
+  - Simplify approval system to checkpoint-only (remove legacy blocking approvalHandler)
+  - Optimize checkpoint storage with delta messages instead of full history
+  - Add sidebar sections for conversations awaiting approval with status indicator
+  - Fix nested checkpoint missing baseMessageCount in resumeRunFromCheckpoint
+  - Improve email conversation titles (sender email + subject)
+  - Remove email threading — each incoming email creates its own conversation
+  - Fix streaming after approval to preserve existing messages (liveOnly mode)
+  - Preserve newlines in user messages in web UI
+
+- Updated dependencies [[`e000b96`](https://github.com/cesr/poncho-ai/commit/e000b96837cbbb8d95c868c91a614f458868c444)]:
+  - @poncho-ai/sdk@1.0.2
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import http from 'node:http';
-import { Message } from '@poncho-ai/sdk';
+import { ToolDefinition, Message } from '@poncho-ai/sdk';
 
 interface ThreadRef {
     platformThreadId: string;
@@ -7,8 +7,16 @@ interface ThreadRef {
     /** The specific message ID that triggered this interaction (for reactions). */
     messageId?: string;
 }
+interface FileAttachment {
+    /** base64-encoded file data */
+    data: string;
+    mediaType: string;
+    filename?: string;
+}
 interface IncomingMessage {
     text: string;
+    subject?: string;
+    files?: FileAttachment[];
     threadRef: ThreadRef;
     sender: {
         id: string;
@@ -22,6 +30,13 @@ type RouteHandler = (req: http.IncomingMessage, res: http.ServerResponse) => Pro
 type RouteRegistrar = (method: "GET" | "POST", path: string, handler: RouteHandler) => void;
 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;
     /** One-time startup (e.g. validate credentials). */
@@ -29,12 +44,21 @@ interface MessagingAdapter {
     /** 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>;
+    sendReply(threadRef: ThreadRef, content: string, options?: {
+        files?: FileAttachment[];
+    }): Promise<void>;
     /**
      * Show a processing indicator (e.g. reaction, typing).
      * Returns a cleanup function that removes the indicator.
      */
     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;
 }
 interface AgentRunner {
     getOrCreateConversation(conversationId: string, meta: {
@@ -47,8 +71,18 @@ interface AgentRunner {
     run(conversationId: string, input: {
         task: string;
         messages: Message[];
+        files?: FileAttachment[];
+        metadata?: {
+            platform: string;
+            sender: {
+                id: string;
+                name?: string;
+            };
+            threadId: string;
+        };
     }): Promise<{
         response: string;
+        files?: FileAttachment[];
     }>;
 }
 interface AgentBridgeOptions {
@@ -59,12 +93,19 @@ 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;
 }
 
 declare class AgentBridge {
     private readonly adapter;
     private readonly runner;
     private readonly waitUntil;
+    private readonly ownerIdOverride;
     constructor(options: AgentBridgeOptions);
     /** Wire the adapter's message handler and initialise. */
     start(): Promise<void>;
@@ -77,6 +118,8 @@ interface SlackAdapterOptions {
 }
 declare class SlackAdapter implements MessagingAdapter {
     readonly platform: "slack";
+    readonly autoReply = true;
+    readonly hasSentInCurrentRequest = false;
     private botToken;
     private signingSecret;
     private readonly botTokenEnv;
@@ -86,9 +129,113 @@ declare class SlackAdapter implements MessagingAdapter {
     initialize(): Promise<void>;
     onMessage(handler: IncomingMessageHandler): void;
     registerRoutes(router: RouteRegistrar): void;
-    sendReply(threadRef: ThreadRef, content: string): Promise<void>;
+    sendReply(threadRef: ThreadRef, content: string, _options?: {
+        files?: Array<{
+            data: string;
+            mediaType: string;
+            filename?: 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 };
+interface ResendAdapterOptions {
+    apiKeyEnv?: string;
+    webhookSecretEnv?: string;
+    fromEnv?: string;
+    allowedSenders?: string[];
+    mode?: "auto-reply" | "tool";
+    allowedRecipients?: string[];
+    maxSendsPerRun?: number;
+}
+declare class ResendAdapter implements MessagingAdapter {
+    readonly platform: "resend";
+    readonly autoReply: boolean;
+    hasSentInCurrentRequest: boolean;
+    private resend;
+    private apiKey;
+    private webhookSecret;
+    private fromAddress;
+    private readonly apiKeyEnv;
+    private readonly webhookSecretEnv;
+    private readonly fromEnv;
+    private readonly allowedSenders;
+    private readonly allowedRecipients;
+    private readonly maxSendsPerRun;
+    private readonly mode;
+    private handler;
+    private sendCount;
+    /** Request-scoped thread metadata for sendReply. */
+    private readonly threadMeta;
+    /** Deduplication set for svix-id headers. */
+    private readonly processed;
+    constructor(options?: ResendAdapterOptions);
+    resetRequestState(): void;
+    initialize(): Promise<void>;
+    onMessage(handler: IncomingMessageHandler): void;
+    registerRoutes(router: RouteRegistrar): void;
+    sendReply(threadRef: ThreadRef, content: string, options?: {
+        files?: FileAttachment[];
+    }): Promise<void>;
+    indicateProcessing(_threadRef: ThreadRef): Promise<() => Promise<void>>;
+    getToolDefinitions(): ToolDefinition[];
+    private handleSendEmailTool;
+    private handleRequest;
+    private processInboundEmail;
+    private fetchAndDownloadAttachments;
+}
+
+/** Extract the bare email address from a formatted string like `"Name <addr>"`. */
+declare function extractEmailAddress(formatted: string): string;
+/** Extract the display name from `"Name <addr>"`, or return `undefined`. */
+declare function extractDisplayName(formatted: string): string | undefined;
+/**
+ * Parse a `References` header value into an ordered array of message IDs.
+ * Handles both space-separated and newline-folded formats.
+ */
+declare function parseReferences(headers: Array<{
+    name: string;
+    value: string;
+}> | Record<string, string> | undefined): string[];
+/**
+ * Derive a stable root message ID for a conversation.
+ *
+ * 1. First entry in the `References` chain (the original message).
+ * 2. Fallback: hash of normalised subject + sender (for clients that strip References).
+ * 3. Last resort: the current message's own ID.
+ */
+declare function deriveRootMessageId(references: string[], currentMessageId: string, fallback?: {
+    subject: string;
+    sender: string;
+}): string;
+/** Prepend `Re:` if the subject doesn't already have it. */
+declare function buildReplySubject(subject: string): string;
+/**
+ * Build `In-Reply-To` and `References` headers for an outbound reply.
+ */
+declare function buildReplyHeaders(inReplyTo: string, existingReferences: string[]): Record<string, string>;
+/**
+ * Strip quoted reply content from an email body (plain text).
+ *
+ * Handles common patterns from Gmail, Apple Mail, Outlook, and Thunderbird.
+ * Best-effort heuristic — the full original text should be preserved elsewhere
+ * (e.g. `IncomingMessage.raw`) for debugging.
+ */
+declare function stripQuotedReply(text: string): string;
+/**
+ * Convert a markdown-ish agent response to simple email-safe HTML.
+ *
+ * This is intentionally lightweight — no external dependency. It handles the
+ * most common patterns agents produce: paragraphs, bold, italic, inline code,
+ * code blocks, unordered/ordered lists, and headings.
+ */
+declare function markdownToEmailHtml(text: string): string;
+/**
+ * Check whether a sender email matches any pattern in an allowlist.
+ * Patterns can be exact addresses or domain wildcards like `*@example.com`.
+ * Returns `true` if the list is empty/undefined (no restriction).
+ */
+declare function matchesSenderPattern(sender: string, patterns: string[] | undefined): boolean;
+
+export { AgentBridge, type AgentBridgeOptions, type AgentRunner, type FileAttachment, type IncomingMessage, type IncomingMessageHandler, type MessagingAdapter, ResendAdapter, type ResendAdapterOptions, type RouteHandler, type RouteRegistrar, SlackAdapter, type SlackAdapterOptions, type ThreadRef, buildReplyHeaders, buildReplySubject, deriveRootMessageId, extractDisplayName, extractEmailAddress, markdownToEmailHtml, matchesSenderPattern, parseReferences, stripQuotedReply };