dashclaw 1.8.1 → 1.8.2

package/README.md

@@ -1026,6 +1026,7 @@ Send a message to another agent or broadcast.
 | threadId | string | No | Thread ID to attach to |
 | urgent | boolean | No | Mark as urgent |
 | docRef | string | No | Reference to a shared doc ID |
+| attachments | Array<{filename, mime_type, data}> | No | File attachments (base64, max 3, max 5MB each) |
 
 **Returns:** `Promise<{message: Object, message_id: string}>`
 
@@ -1119,6 +1120,38 @@ Create or update a shared workspace document. Upserts by name.
 
 **Returns:** `Promise<{doc: Object, doc_id: string}>`
 
+### claw.getAttachmentUrl(attachmentId)
+
+Get a URL to download an attachment.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `attachmentId` | `string` | Attachment ID (`att_*`) |
+
+**Returns:** `string` — URL to fetch the attachment binary
+
+---
+
+### claw.getAttachment(attachmentId)
+
+Download an attachment as a Buffer.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `attachmentId` | `string` | Attachment ID (`att_*`) |
+
+**Returns:** `Promise<{ data: Buffer, filename: string, mimeType: string }>`
+
+```js
+const inbox = await claw.getInbox();
+for (const msg of inbox.messages) {
+  for (const att of msg.attachments || []) {
+    const { data, filename } = await claw.getAttachment(att.id);
+    fs.writeFileSync(filename, data);
+  }
+}
+```
+
 ---
 
 ## Agent Pairing

package/dashclaw.js

@@ -542,6 +542,10 @@ class DashClaw {
    * Subscribe to real-time SSE events from the DashClaw server.
    * Uses fetch-based SSE parsing for Node 18+ compatibility (no native EventSource required).
    *
+   * @param {Object} [options]
+   * @param {boolean} [options.reconnect=true] - Auto-reconnect on disconnect (resumes from last event ID)
+   * @param {number} [options.maxRetries=Infinity] - Max reconnection attempts before giving up
+   * @param {number} [options.retryInterval=3000] - Milliseconds between reconnection attempts
    * @returns {{ on(eventType: string, callback: Function): this, close(): void, _promise: Promise<void> }}
    *
    * @example
@@ -552,23 +556,36 @@ class DashClaw {
    *   .on('policy.updated', (data) => console.log('Policy changed:', data))
    *   .on('task.assigned', (data) => console.log('Task assigned:', data))
    *   .on('task.completed', (data) => console.log('Task done:', data))
+   *   .on('reconnecting', ({ attempt }) => console.log(`Reconnecting #${attempt}...`))
    *   .on('error', (err) => console.error('Stream error:', err));
    *
    * // Later:
    * stream.close();
    */
-  events() {
+  events({ reconnect = true, maxRetries = Infinity, retryInterval = 3000 } = {}) {
     const url = `${this.baseUrl}/api/stream`;
     const apiKey = this.apiKey;
 
     const handlers = new Map();
     let closed = false;
     let controller = null;
+    let lastEventId = null;
+    let retryCount = 0;
+
+    const emit = (eventType, data) => {
+      const cbs = handlers.get(eventType) || [];
+      for (const cb of cbs) {
+        try { cb(data); } catch { /* ignore handler errors */ }
+      }
+    };
 
     const connect = async () => {
       controller = new AbortController();
+      const headers = { 'x-api-key': apiKey };
+      if (lastEventId) headers['last-event-id'] = lastEventId;
+
       const res = await fetch(url, {
-        headers: { 'x-api-key': apiKey },
+        headers,
         signal: controller.signal,
       });
 
@@ -576,9 +593,14 @@ class DashClaw {
         throw new Error(`SSE connection failed: ${res.status} ${res.statusText}`);
       }
 
+      retryCount = 0; // Reset on successful connection
+
       const reader = res.body.getReader();
       const decoder = new TextDecoder();
       let buffer = '';
+      // Persist across reads so frames split across chunks are handled correctly
+      let currentEvent = null;
+      let currentData = '';
 
       while (!closed) {
         const { done, value } = await reader.read();
@@ -589,39 +611,55 @@ class DashClaw {
         const lines = buffer.split('\n');
         buffer = lines.pop(); // Keep incomplete line in buffer
 
-        let currentEvent = null;
-        let currentData = '';
-
         for (const line of lines) {
-          if (line.startsWith('event: ')) {
+          if (line.startsWith('id: ')) {
+            lastEventId = line.slice(4).trim();
+          } else if (line.startsWith('event: ')) {
             currentEvent = line.slice(7).trim();
           } else if (line.startsWith('data: ')) {
             currentData += line.slice(6);
+          } else if (line.startsWith(':')) {
+            // SSE comment (keepalive heartbeat) — ignore
           } else if (line === '' && currentEvent) {
             // End of SSE frame — dispatch
-            const eventHandlers = handlers.get(currentEvent) || [];
-            if (eventHandlers.length > 0 && currentData) {
+            if (currentData) {
               try {
                 const parsed = JSON.parse(currentData);
-                for (const cb of eventHandlers) {
-                  try { cb(parsed); } catch { /* ignore handler errors */ }
-                }
+                emit(currentEvent, parsed);
               } catch { /* ignore parse errors */ }
             }
             currentEvent = null;
             currentData = '';
+          } else if (line === '') {
+            // Blank line without a pending event — reset partial state
+            currentEvent = null;
+            currentData = '';
           }
         }
       }
     };
 
-    const connectionPromise = connect().catch((err) => {
-      if (closed) return; // Abort is expected on close
-      const errorHandlers = handlers.get('error') || [];
-      for (const cb of errorHandlers) {
-        try { cb(err); } catch { /* ignore */ }
+    const connectLoop = async () => {
+      while (!closed) {
+        try {
+          await connect();
+        } catch (err) {
+          if (closed) return;
+          emit('error', err);
+        }
+        // Stream ended (server closed, network drop, etc.)
+        if (closed) return;
+        if (!reconnect || retryCount >= maxRetries) {
+          emit('error', new Error('SSE stream ended'));
+          return;
+        }
+        retryCount++;
+        emit('reconnecting', { attempt: retryCount, maxRetries });
+        await new Promise((r) => setTimeout(r, retryInterval));
       }
-    });
+    };
+
+    const connectionPromise = connectLoop();
 
     const handle = {
       on(eventType, callback) {
@@ -1495,7 +1533,7 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 11: Agent Messaging (9 methods)
+  // Category 11: Agent Messaging (11 methods)
   // ══════════════════════════════════════════════
 
   /**
@@ -1508,10 +1546,11 @@ class DashClaw {
    * @param {string} [params.threadId] - Thread ID to attach message to
    * @param {boolean} [params.urgent=false] - Mark as urgent
    * @param {string} [params.docRef] - Reference to a shared doc ID
+   * @param {Array<{filename: string, mime_type: string, data: string}>} [params.attachments] - File attachments (base64 data, max 3, max 5MB each)
    * @returns {Promise<{message: Object, message_id: string}>}
    */
-  async sendMessage({ to, type, subject, body, threadId, urgent, docRef }) {
-    return this._request('/api/messages', 'POST', {
+  async sendMessage({ to, type, subject, body, threadId, urgent, docRef, attachments }) {
+    const payload = {
       from_agent_id: this.agentId,
       to_agent_id: to || null,
       message_type: type || 'info',
@@ -1520,7 +1559,9 @@ class DashClaw {
       thread_id: threadId,
       urgent,
       doc_ref: docRef,
-    });
+    };
+    if (attachments?.length) payload.attachments = attachments;
+    return this._request('/api/messages', 'POST', payload);
   }
 
   /**
@@ -1642,6 +1683,39 @@ class DashClaw {
     });
   }
 
+  /**
+   * Get an attachment's download URL or fetch its binary data.
+   * @param {string} attachmentId - Attachment ID (att_*)
+   * @returns {string} URL to fetch the attachment
+   */
+  getAttachmentUrl(attachmentId) {
+    return `${this.baseUrl}/api/messages/attachments?id=${encodeURIComponent(attachmentId)}`;
+  }
+
+  /**
+   * Download an attachment as a Buffer.
+   * @param {string} attachmentId - Attachment ID (att_*)
+   * @returns {Promise<{data: Buffer, filename: string, mimeType: string}>}
+   */
+  async getAttachment(attachmentId) {
+    const url = this.getAttachmentUrl(attachmentId);
+    const res = await fetch(url, {
+      headers: { 'x-api-key': this.apiKey },
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(err.error || `Attachment fetch failed: ${res.status}`);
+    }
+    const data = Buffer.from(await res.arrayBuffer());
+    const cd = res.headers.get('content-disposition') || '';
+    const match = cd.match(/filename="(.+?)"/);
+    return {
+      data,
+      filename: match ? match[1] : attachmentId,
+      mimeType: res.headers.get('content-type') || 'application/octet-stream',
+    };
+  }
+
   // ══════════════════════════════════════════════
   // Category 13: Behavior Guard (2 methods)
   // ══════════════════════════════════════════════

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dashclaw",
-  "version": "1.8.1",
-  "description": "Full-featured agent toolkit for the DashClaw platform. 95+ methods across 21+ categories for action recording, context management, session handoffs, security scanning, behavior guard, compliance, task routing, identity binding, organization management, webhooks, bulk sync, and more.",
+  "version": "1.8.2",
+  "description": "Full-featured agent toolkit for the DashClaw platform. 96+ methods across 22+ categories for action recording, context management, session handoffs, security scanning, behavior guard, compliance, task routing, identity binding, organization management, webhooks, bulk sync, and more.",
   "type": "module",
   "publishConfig": {
     "access": "public"