dashclaw 1.8.2 → 1.9.0

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.
@@ -474,6 +558,46 @@ Report a token usage snapshot for this agent.
 
 **Returns:** `Promise<{snapshot: Object}>`
 
+### claw.wrapClient(llmClient, options?)
+Wrap an Anthropic or OpenAI client to auto-report token usage after every call. Returns the same client instance for fluent usage. Streaming calls (where response lacks `.usage`) are safely ignored.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| llmClient | Object | Yes | An Anthropic or OpenAI SDK client instance |
+| options.provider | string | No | Force `'anthropic'` or `'openai'` if auto-detect fails |
+
+**Returns:** The wrapped client (same instance)
+
+**Example (Anthropic):**
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+import { DashClaw } from 'dashclaw';
+
+const claw = new DashClaw({ baseUrl: 'http://localhost:3000', agentId: 'my-agent', apiKey: '...' });
+const anthropic = claw.wrapClient(new Anthropic());
+
+const msg = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+// Token usage auto-reported to DashClaw
+```
+
+**Example (OpenAI):**
+```javascript
+import OpenAI from 'openai';
+
+const openai = claw.wrapClient(new OpenAI());
+
+const chat = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+// Token usage auto-reported to DashClaw
+```
+
 ### claw.recordDecision(entry)
 Record a decision for the learning database. Track what your agent decides and why.
 
@@ -1009,6 +1133,27 @@ Scan text and store finding metadata for audit trails. The original content is n
 
 **Returns:** `Promise<{clean: boolean, findings_count: number, findings: Object[], redacted_text: string}>`
 
+### claw.scanPromptInjection(text, options?)
+Scan text for prompt injection attacks — role overrides, delimiter injection, instruction smuggling, data exfiltration attempts, and encoding evasion. Returns risk level and actionable recommendation.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| text | string | Yes | Text to scan for injection attacks |
+| options.source | string | No | Where this text came from (e.g. user_input, tool_output, retrieval) |
+
+**Returns:** `Promise<{clean: boolean, risk_level: string, recommendation: string, findings_count: number, critical_count: number, categories: string[], findings: Object[]}>`
+
+**Example:**
+```javascript
+const result = await claw.scanPromptInjection(userMessage, { source: 'user_input' });
+if (result.recommendation === 'block') {
+  console.error(`Blocked: ${result.findings_count} injection patterns detected`);
+} else if (result.recommendation === 'warn') {
+  console.warn(`Warning: ${result.categories.join(', ')} detected`);
+}
+```
+
 ---
 
 ## Agent Messaging
@@ -1128,7 +1273,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 +1524,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 +1570,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)
@@ -13,7 +13,7 @@
  * - Automation Snippets (5)
  * - User Preferences (6)
  * - Daily Digest (1)
- * - Security Scanning (2)
+ * - Security Scanning (3)
  * - Agent Messaging (9)
  * - Behavior Guard (2)
  * - Agent Pairing (3)
@@ -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() {
@@ -885,7 +885,7 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 4: Dashboard Data (8 methods)
+  // Category 4: Dashboard Data (9 methods)
   // ══════════════════════════════════════════════
 
   /**
@@ -905,6 +905,79 @@ class DashClaw {
     });
   }
 
+  /**
+   * Internal: fire-and-forget token report extracted from an LLM response.
+   * @private
+   */
+  async _reportTokenUsageFromLLM({ tokens_in, tokens_out, model }) {
+    if (tokens_in == null && tokens_out == null) return;
+    try {
+      await this._request('/api/tokens', 'POST', {
+        tokens_in: tokens_in || 0,
+        tokens_out: tokens_out || 0,
+        model: model || undefined,
+        agent_id: this.agentId,
+      });
+    } catch (_) {
+      // fire-and-forget: never let telemetry break the caller
+    }
+  }
+
+  /**
+   * Wrap an Anthropic or OpenAI client to auto-report token usage after each call.
+   * Returns the same client instance (mutated) for fluent usage.
+   *
+   * @param {Object} llmClient - An Anthropic or OpenAI SDK client instance
+   * @param {Object} [options]
+   * @param {'anthropic'|'openai'} [options.provider] - Force provider detection
+   * @returns {Object} The wrapped client
+   *
+   * @example
+   * const anthropic = claw.wrapClient(new Anthropic());
+   * const msg = await anthropic.messages.create({ model: 'claude-sonnet-4-20250514', max_tokens: 1024, messages: [...] });
+   * // Token usage is auto-reported to DashClaw
+   */
+  wrapClient(llmClient, { provider } = {}) {
+    if (llmClient._dashclawWrapped) return llmClient;
+
+    const detected = provider
+      || (llmClient.messages?.create ? 'anthropic' : null)
+      || (llmClient.chat?.completions?.create ? 'openai' : null);
+
+    if (!detected) {
+      throw new Error(
+        'DashClaw.wrapClient: unable to detect provider. Pass { provider: "anthropic" } or { provider: "openai" }.'
+      );
+    }
+
+    if (detected === 'anthropic') {
+      const original = llmClient.messages.create.bind(llmClient.messages);
+      llmClient.messages.create = async (...args) => {
+        const response = await original(...args);
+        this._reportTokenUsageFromLLM({
+          tokens_in: response?.usage?.input_tokens ?? null,
+          tokens_out: response?.usage?.output_tokens ?? null,
+          model: response?.model ?? null,
+        });
+        return response;
+      };
+    } else if (detected === 'openai') {
+      const original = llmClient.chat.completions.create.bind(llmClient.chat.completions);
+      llmClient.chat.completions.create = async (...args) => {
+        const response = await original(...args);
+        this._reportTokenUsageFromLLM({
+          tokens_in: response?.usage?.prompt_tokens ?? null,
+          tokens_out: response?.usage?.completion_tokens ?? null,
+          model: response?.model ?? null,
+        });
+        return response;
+      };
+    }
+
+    llmClient._dashclawWrapped = true;
+    return llmClient;
+  }
+
   /**
    * Record a decision for the learning database.
    * @param {Object} entry
@@ -1497,7 +1570,7 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 10: Security Scanning (2 methods)
+  // Category 10: Security Scanning (3 methods)
   // ══════════════════════════════════════════════
 
   /**
@@ -1532,6 +1605,22 @@ class DashClaw {
     });
   }
 
+  /**
+   * Scan text for prompt injection attacks (role overrides, delimiter injection,
+   * instruction smuggling, data exfiltration attempts, etc.).
+   * @param {string} text - Text to scan
+   * @param {Object} [options]
+   * @param {string} [options.source] - Where this text came from (for context)
+   * @returns {Promise<{clean: boolean, risk_level: string, recommendation: string, findings_count: number, critical_count: number, categories: string[], findings: Object[]}>}
+   */
+  async scanPromptInjection(text, options = {}) {
+    return this._request('/api/security/prompt-injection', 'POST', {
+      text,
+      source: options.source,
+      agent_id: this.agentId,
+    });
+  }
+
   // ══════════════════════════════════════════════
   // Category 11: Agent Messaging (11 methods)
   // ══════════════════════════════════════════════
@@ -1669,7 +1758,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 +1806,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 +2221,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.9.0",
   "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",