dashclaw 1.8.2 → 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.
@@ -1128,7 +1212,7 @@ Get a URL to download an attachment.
 |---|---|---|
 | `attachmentId` | `string` | Attachment ID (`att_*`) |
 
-**Returns:** `string` — URL to fetch the attachment binary
+**Returns:** `string`: URL to fetch the attachment binary
 
 ---
 
@@ -1379,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}`);
 }
 ```
 
@@ -1425,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
@@ -619,9 +619,9 @@ class DashClaw {
           } else if (line.startsWith('data: ')) {
             currentData += line.slice(6);
           } else if (line.startsWith(':')) {
-            // SSE comment (keepalive heartbeat) — ignore
+            // SSE comment (keepalive heartbeat). Ignore.
           } else if (line === '' && currentEvent) {
-            // End of SSE frame — dispatch
+            // End of SSE frame. Dispatch.
             if (currentData) {
               try {
                 const parsed = JSON.parse(currentData);
@@ -631,7 +631,7 @@ class DashClaw {
             currentEvent = null;
             currentData = '';
           } else if (line === '') {
-            // Blank line without a pending event — reset partial state
+            // Blank line without a pending event. Reset partial state.
             currentEvent = null;
             currentData = '';
           }
@@ -766,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
@@ -817,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
@@ -873,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() {
@@ -1669,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
@@ -1717,12 +1717,11 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // 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
@@ -2133,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,6 +1,6 @@
 {
   "name": "dashclaw",
-  "version": "1.8.2",
+  "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": {
@@ -22,7 +22,7 @@
   ],
   "keywords": [
     "ai-agent",
-    "observability",
+    "decision-infrastructure",
     "agent-toolkit",
     "dashclaw",
     "dashclaw",