dashclaw 1.8.1 → 1.8.3

package/README.md

@@ -1,8 +1,10 @@
-# DashClaw SDK Reference (Full)
+# DashClaw SDK: Agent Decision Infrastructure
 
 Full reference for the DashClaw SDK (Node.js). For Python, see the [Python SDK docs](../sdk-python/README.md).
 
-Install, configure, and instrument your AI agents with 95+ methods across 21+ categories including action recording, behavior guard, context management, session handoffs, security scanning, agent messaging, agent pairing, identity binding, organization management, webhooks, policy testing, compliance, task routing, and more.
+DashClaw treats every agent action as a governed decision. The SDK provides decision recording, policy enforcement, assumption tracking, and compliance mapping. It proves what your agents decided and why.
+
+Install, configure, and govern your AI agents with 95+ methods across 21+ categories including action recording, behavior guard, context management, session handoffs, security scanning, agent messaging, agent pairing, identity binding, organization management, webhooks, policy testing, compliance, task routing, and more.
 
 ---
 
@@ -111,11 +113,93 @@ try {
 }
 ```
 
+### Compliance & Governance Patterns
+
+DashClaw's guard + action recording pipeline maps directly to compliance controls.
+
+**SOC 2 CC6.1: Logical Access Controls**
+```javascript
+// Before any high-risk operation, enforce policy
+const guardResult = await claw.guard({
+  action_type: 'database_write',
+  risk_score: 85,
+  systems_touched: ['production_db'],
+  reversible: false,
+  declared_goal: 'Drop legacy user table'
+});
+
+if (guardResult.decision === 'block') {
+  // SOC 2 control satisfied: unauthorized action prevented
+  console.log('Policy blocked:', guardResult.reasons);
+  return;
+}
+
+// Decision is governed. Record with full lineage
+const { action_id } = await claw.createAction({
+  action_type: 'database_write',
+  declared_goal: 'Drop legacy user table',
+  risk_score: 85,
+  reversible: false,
+  authorization_scope: 'admin-approved'
+});
+
+// Register the assumption this decision relies on
+await claw.registerAssumption({
+  action_id,
+  assumption: 'Legacy table has zero active references',
+  basis: 'Schema dependency scan completed 2h ago'
+});
+```
+
+**EU AI Act Article 14: Human Oversight**
+```javascript
+// require_approval forces human-in-the-loop
+const result = await claw.guard({
+  action_type: 'customer_communication',
+  risk_score: 60,
+  declared_goal: 'Send pricing update to 500 customers'
+});
+
+if (result.decision === 'require_approval') {
+  // Create action in pending state, wait for human approval
+  const { action_id } = await claw.createAction({
+    action_type: 'customer_communication',
+    declared_goal: 'Send pricing update to 500 customers',
+    status: 'pending'
+  });
+  // Approval queue at /approvals shows this to operators
+}
+```
+
+**ISO 42001: AI Decision Accountability**
+```javascript
+// Full decision lineage: guard → action → assumptions → outcome
+const { action_id } = await claw.createAction({
+  action_type: 'data_processing',
+  declared_goal: 'Rebuild customer segmentation model',
+  risk_score: 45,
+  systems_touched: ['ml-pipeline', 'customer-db']
+});
+
+await claw.registerAssumption({
+  action_id,
+  assumption: 'Customer data is current as of today',
+  basis: 'CRM sync completed at 09:00 UTC'
+});
+
+// Later: validate or invalidate assumptions
+await claw.validateAssumption(assumptionId, true);
+
+// Decision integrity signals auto-detect when assumptions drift
+const signals = await claw.getSignals();
+// → Returns 'assumption_drift' if too many invalidated
+```
+
 ---
 
 ## Action Recording
 
-Create, update, and query action records. Every agent action gets a full audit trail.
+Create, update, and query action records. Every agent action is a governed decision with a full audit trail capturing intent, reasoning, and outcome for compliance and review.
 
 ### claw.createAction(action)
 Create a new action record. The agent's agentId, agentName, and swarmId are automatically attached.
@@ -268,7 +352,7 @@ stream.close();
 
 ### claw.waitForApproval(actionId, { useEvents: true })
 
-SSE-powered approval waiting — resolves instantly when the operator approves/denies instead of polling every 5 seconds.
+SSE-powered approval waiting. Resolves instantly when the operator approves/denies instead of polling every 5 seconds.
 
 ```javascript
 // SSE mode (instant, recommended)
@@ -280,7 +364,7 @@ const { action } = await claw.waitForApproval('act_abc');
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| actionId | string | — | Action ID to watch |
+| actionId | string | Yes | Action ID to watch |
 | options.timeout | number | 300000 | Max wait time (ms) |
 | options.interval | number | 5000 | Poll interval (polling mode only) |
 | options.useEvents | boolean | false | Use SSE instead of polling |
@@ -425,7 +509,7 @@ Get current risk signals across all agents. Returns 7 signal types: autonomy_spi
 
 ## Behavior Guard
 
-Check org-level policies before executing risky actions. Returns allow, warn, block, or require_approval based on configured guard policies.
+Guard is the heart of DashClaw. Every action can be checked against policies before execution. Returns allow, warn, block, or require_approval based on configured guard policies.
 
 ### claw.guard(context, options?)
 Evaluate guard policies for a proposed action. Call this before risky operations to get a go/no-go decision. The agent_id is auto-attached from the SDK constructor.
@@ -1026,6 +1110,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 +1204,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
@@ -1346,7 +1463,7 @@ Run guardrails tests against all active policies. Returns pass/fail results per
 const report = await claw.testPolicies();
 console.log(`${report.passed}/${report.total} policies passed`);
 for (const r of report.results.filter(r => !r.passed)) {
-  console.log(`FAIL: ${r.policy} — ${r.reason}`);
+  console.log(`FAIL: ${r.policy}: ${r.reason}`);
 }
 ```
 
@@ -1392,7 +1509,7 @@ Map active policies to framework controls. Returns a control-by-control coverage
 const { controls, coverage_pct } = await claw.mapCompliance('soc2');
 console.log(`SOC 2 coverage: ${coverage_pct}%`);
 for (const ctrl of controls.filter(c => !c.covered)) {
-  console.log(`Gap: ${ctrl.id} — ${ctrl.name}`);
+  console.log(`Gap: ${ctrl.id}: ${ctrl.name}`);
 }
 ```
 

package/dashclaw.js

@@ -1,7 +1,7 @@
 /**
  * DashClaw SDK
  * Full-featured agent toolkit for the DashClaw platform.
- * Zero-dependency ESM SDK — requires Node 18+ (native fetch).
+ * Zero-dependency ESM SDK. Requires Node 18+ (native fetch).
  *
  * 96+ methods across 22+ categories:
  * - Action Recording (7)
@@ -217,7 +217,7 @@ class DashClaw {
     try {
       decision = await this.guard(context);
     } catch (err) {
-      // Guard API failure is fail-open — log and proceed
+      // Guard API failure is fail-open: log and proceed
       console.warn(`[DashClaw] Guard check failed (proceeding): ${err.message}`);
       return;
     }
@@ -403,11 +403,11 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 1: Action Recording (6 methods)
+  // Category 1: Decision Recording (6 methods)
   // ══════════════════════════════════════════════
 
   /**
-   * Create a new action record.
+   * Record a governed decision. Every action is a decision with a full audit trail: goal, reasoning, assumptions, and policy compliance.
    * @param {Object} action
    * @param {string} action.action_type - One of: build, deploy, post, apply, security, message, api, calendar, research, review, fix, refactor, test, config, monitor, alert, cleanup, sync, migrate, other
    * @param {string} action.declared_goal - What this action aims to accomplish
@@ -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) {
+            // End of SSE frame. Dispatch.
+            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) {
@@ -728,11 +766,11 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 2: Loops & Assumptions (7 methods)
+  // Category 2: Decision Integrity (Loops & Assumptions) (7 methods)
   // ══════════════════════════════════════════════
 
   /**
-   * Register an open loop for an action.
+   * Register an unresolved dependency for a decision. Open loops track work that must be completed before the decision can be considered fully resolved.
    * @param {Object} loop
    * @param {string} loop.action_id - Parent action ID
    * @param {string} loop.loop_type - One of: followup, question, dependency, approval, review, handoff, other
@@ -779,7 +817,7 @@ class DashClaw {
   }
 
   /**
-   * Register assumptions made during an action.
+   * Register assumptions underlying a decision. Assumptions are the decision basis. They must be validated or invalidated to maintain decision integrity.
    * @param {Object} assumption
    * @param {string} assumption.action_id - Parent action ID
    * @param {string} assumption.assumption - The assumption being made
@@ -835,11 +873,11 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 3: Signals (1 method)
+  // Category 3: Decision Integrity Signals (1 method)
   // ══════════════════════════════════════════════
 
   /**
-   * Get current risk signals.
+   * Get current decision integrity signals. Returns autonomy breaches, logic drift, and governance violations.
    * @returns {Promise<{signals: Object[], counts: {red: number, amber: number, total: number}}>}
    */
   async getSignals() {
@@ -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);
   }
 
   /**
@@ -1628,7 +1669,7 @@ class DashClaw {
 
   /**
    * Create or update a shared workspace document.
-   * Upserts by (org_id, name) — updates increment the version.
+   * Upserts by (org_id, name). Updates increment the version.
    * @param {Object} params
    * @param {string} params.name - Document name (unique per org)
    * @param {string} params.content - Document content
@@ -1642,13 +1683,45 @@ 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)
+  // Category 13: Policy Enforcement (Guard) (2 methods)
   // ══════════════════════════════════════════════
 
   /**
-   * Check guard policies before executing a risky action.
-   * Returns allow/warn/block/require_approval.
+   * Enforce policies before a decision executes. Guard is the heart of DashClaw. It intercepts intent and returns allow/warn/block/require_approval.
    * @param {Object} context
    * @param {string} context.action_type - Action type (required)
    * @param {number} [context.risk_score] - Risk score 0-100
@@ -2059,7 +2132,7 @@ class DashClaw {
 
   /**
    * Sync multiple data categories in a single request.
-   * Every key is optional — only provided categories are processed.
+   * Every key is optional. Only provided categories are processed.
    * @param {Object} state - Data to sync (connections, memory, goals, learning, content, inspiration, context_points, context_threads, handoffs, preferences, snippets)
    * @returns {Promise<{results: Object, total_synced: number, total_errors: number, duration_ms: number}>}
    */

package/index.cjs

@@ -1,5 +1,5 @@
 /**
- * DashClaw SDK — CommonJS compatibility wrapper.
+ * DashClaw SDK: CommonJS compatibility wrapper.
  * For ESM: import { DashClaw } from 'dashclaw'
  * For CJS: const { DashClaw } = require('dashclaw')
  */

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.3",
+  "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"
@@ -22,7 +22,7 @@
   ],
   "keywords": [
     "ai-agent",
-    "observability",
+    "decision-infrastructure",
     "agent-toolkit",
     "dashclaw",
     "dashclaw",