dashclaw 1.7.1 → 1.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 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 60+ methods across action recording, behavior guard, context management, session handoffs, security scanning, and more.
+Install, configure, and instrument your AI agents with 78+ methods across action recording, behavior guard, context management, session handoffs, security scanning, policy testing, compliance, task routing, and more.
 
 ---
 
@@ -608,6 +608,100 @@ Add an entry to an existing thread.
 
 ---
 
+## Automation Snippets
+
+Save, search, and reuse code snippets across agent sessions.
+
+### claw.saveSnippet(snippet)
+Save or update a reusable code snippet. Upserts on name.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| name | string | Yes | Snippet name (unique per org) |
+| code | string | Yes | The snippet code |
+| description | string | No | What this snippet does |
+| language | string | No | Programming language |
+| tags | string[] | No | Tags for categorization |
+
+**Returns:** `Promise<{snippet: Object, snippet_id: string}>`
+
+**Example:**
+```javascript
+await claw.saveSnippet({
+  name: 'fetch-with-retry',
+  code: 'async function fetchRetry(url, n = 3) { ... }',
+  language: 'javascript',
+  tags: ['fetch', 'retry'],
+});
+```
+
+### claw.getSnippet(snippetId)
+Fetch a single snippet by ID.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| snippetId | string | Yes | The snippet ID |
+
+**Returns:** `Promise<{snippet: Object}>`
+
+**Example:**
+```javascript
+const { snippet } = await claw.getSnippet('sn_abc123');
+console.log(snippet.name, snippet.language);
+```
+
+### claw.getSnippets(filters?)
+Search and list snippets.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| search | string | No | Search name/description |
+| tag | string | No | Filter by tag |
+| language | string | No | Filter by language |
+| limit | number | No | Max results |
+
+**Returns:** `Promise<{snippets: Object[], total: number}>`
+
+**Example:**
+```javascript
+const { snippets } = await claw.getSnippets({ language: 'javascript' });
+```
+
+### claw.useSnippet(snippetId)
+Mark a snippet as used (increments use_count).
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| snippetId | string | Yes | Snippet ID |
+
+**Returns:** `Promise<{snippet: Object}>`
+
+**Example:**
+```javascript
+await claw.useSnippet('sn_abc123');
+```
+
+### claw.deleteSnippet(snippetId)
+Delete a snippet.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| snippetId | string | Yes | Snippet ID |
+
+**Returns:** `Promise<{deleted: boolean, id: string}>`
+
+**Example:**
+```javascript
+await claw.deleteSnippet('sn_abc123');
+```
+
+---
+
 ## Agent Messaging
 
 ### claw.sendMessage(params)
@@ -640,6 +734,231 @@ Push multiple data categories in a single request. Accepts connections, memory,
 
 ---
 
+## Policy Testing
+
+Run guardrails tests, generate compliance proof reports, and import policy packs.
+
+### claw.testPolicies()
+Run guardrails tests against all active policies. Returns pass/fail results per policy.
+
+**Returns:** `Promise<{ results: Object[], total: number, passed: number, failed: number }>`
+
+**Example:**
+```javascript
+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}`);
+}
+```
+
+### claw.getProofReport(options?)
+Generate a compliance proof report summarizing guard decisions, policy evaluations, and audit evidence.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| format | string | No | Output format: "json" (default) or "md" |
+
+**Returns:** `Promise<{ report: Object|string }>`
+
+### claw.importPolicies({ pack?, yaml? })
+Import a policy pack or raw YAML. Admin only. Replaces or merges into active policies.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| pack | string | No | Named policy pack: enterprise-strict, smb-safe, startup-growth, development |
+| yaml | string | No | Raw YAML policy definition |
+
+**Returns:** `Promise<{ imported: number, policies: Object[] }>`
+
+---
+
+## Compliance Engine
+
+Map policies to regulatory frameworks, run gap analysis, and generate compliance reports.
+
+### claw.mapCompliance(framework)
+Map active policies to framework controls. Returns a control-by-control coverage matrix.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| framework | string | Yes | Target framework: soc2, iso27001, gdpr, nist-ai-rmf, imda-agentic |
+
+**Returns:** `Promise<{ framework: string, controls: Object[], coverage_pct: number }>`
+
+**Example:**
+```javascript
+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}`);
+}
+```
+
+### claw.analyzeGaps(framework)
+Run gap analysis with remediation plan. Identifies missing controls and suggests policy changes.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| framework | string | Yes | Target framework: soc2, iso27001, gdpr, nist-ai-rmf, imda-agentic |
+
+**Returns:** `Promise<{ framework: string, gaps: Object[], remediation_plan: Object[] }>`
+
+### claw.getComplianceReport(framework, options?)
+Generate a full compliance report and save a point-in-time snapshot.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| framework | string | Yes | Target framework |
+| options.format | string | No | Output format: "json" (default) or "md" |
+
+**Returns:** `Promise<{ report: Object|string, snapshot_id: string }>`
+
+### claw.listFrameworks()
+List all available compliance frameworks with metadata.
+
+**Returns:** `Promise<{ frameworks: Object[] }>`
+
+### claw.getComplianceEvidence(options?)
+Get live guard decision evidence for compliance audits. Returns timestamped decision records.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| options.window | string | No | Time window: "7d" (default), "30d", "90d" |
+
+**Returns:** `Promise<{ evidence: Object[], window: string, total: number }>`
+
+---
+
+## Task Routing
+
+Route tasks to agents based on capabilities, availability, and workload. Manage the agent pool and monitor routing health.
+
+### claw.listRoutingAgents(filters?)
+List registered routing agents with optional status filter.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| filters.status | string | No | Filter by status: available, busy, offline |
+
+**Returns:** `Promise<{ agents: Object[], total: number }>`
+
+### claw.registerRoutingAgent(agent)
+Register a new agent in the routing pool.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| name | string | Yes | Agent display name |
+| capabilities | string[] | No | List of skills/capabilities |
+| maxConcurrent | number | No | Max concurrent tasks (default: 1) |
+| endpoint | string | No | Agent callback endpoint URL |
+
+**Returns:** `Promise<{ agent: Object, agent_id: string }>`
+
+### claw.getRoutingAgent(agentId)
+Get a single routing agent with current metrics.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agentId | string | Yes | The routing agent ID |
+
+**Returns:** `Promise<{ agent: Object, metrics: Object }>`
+
+### claw.updateRoutingAgentStatus(agentId, status)
+Update a routing agent's availability status.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agentId | string | Yes | The routing agent ID |
+| status | string | Yes | New status: available, busy, offline |
+
+**Returns:** `Promise<{ agent: Object }>`
+
+### claw.deleteRoutingAgent(agentId)
+Remove an agent from the routing pool.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| agentId | string | Yes | The routing agent ID |
+
+**Returns:** `Promise<{ deleted: boolean, id: string }>`
+
+### claw.listRoutingTasks(filters?)
+List routing tasks with optional filters.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| filters.status | string | No | Filter by status: pending, assigned, completed, failed |
+| filters.agent_id | string | No | Filter by assigned agent |
+| filters.limit | number | No | Max results (default: 50) |
+| filters.offset | number | No | Pagination offset |
+
+**Returns:** `Promise<{ tasks: Object[], total: number }>`
+
+### claw.submitRoutingTask(task)
+Submit a task for automatic routing to the best available agent.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| title | string | Yes | Task title |
+| description | string | No | Detailed description |
+| requiredSkills | string[] | No | Skills needed to handle this task |
+| urgency | string | No | low, medium, high, critical (default: medium) |
+| timeoutSeconds | number | No | Task timeout in seconds |
+| maxRetries | number | No | Max retry attempts on failure |
+| callbackUrl | string | No | URL to notify on completion |
+
+**Returns:** `Promise<{ task: Object, task_id: string, assigned_agent: Object|null }>`
+
+**Example:**
+```javascript
+const { task_id, assigned_agent } = await claw.submitRoutingTask({
+  title: 'Analyze quarterly metrics',
+  description: 'Pull Q4 data and generate summary report',
+  requiredSkills: ['data-analysis', 'reporting'],
+  urgency: 'high',
+  timeoutSeconds: 600,
+  callbackUrl: 'https://hooks.example.com/task-done',
+});
+console.log(`Task ${task_id} assigned to ${assigned_agent?.name ?? 'queue'}`);
+```
+
+### claw.completeRoutingTask(taskId, result?)
+Mark a routing task as completed with optional result payload.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| taskId | string | Yes | The task ID |
+| result | Object | No | Task result data |
+
+**Returns:** `Promise<{ task: Object }>`
+
+### claw.getRoutingStats()
+Get aggregate routing statistics (throughput, latency, agent utilization).
+
+**Returns:** `Promise<{ stats: Object }>`
+
+### claw.getRoutingHealth()
+Get routing system health status and diagnostics.
+
+**Returns:** `Promise<{ healthy: boolean, agents: Object, tasks: Object, latency: Object }>`
+
+---
+
 ## Error Handling
 
 All SDK methods throw on non-2xx responses. Errors include `status` (HTTP code) and `details` (when available).

package/dashclaw.js

@@ -3,20 +3,23 @@
  * Full-featured agent toolkit for the DashClaw platform.
  * Zero-dependency ESM SDK — requires Node 18+ (native fetch).
  *
- * 60+ methods across 13+ categories:
+ * 78+ methods across 16+ categories:
  * - Action Recording (7)
  * - Loops & Assumptions (7)
  * - Signals (1)
  * - Dashboard Data (9)
  * - Session Handoffs (3)
  * - Context Manager (7)
- * - Automation Snippets (4)
+ * - Automation Snippets (5)
  * - User Preferences (6)
  * - Daily Digest (1)
  * - Security Scanning (2)
  * - Agent Messaging (9)
  * - Behavior Guard (2)
  * - Bulk Sync (1)
+ * - Policy Testing (3)
+ * - Compliance Engine (5)
+ * - Task Routing (10)
  */
 
 class DashClaw {
@@ -1138,7 +1141,7 @@ class DashClaw {
   }
 
   // ══════════════════════════════════════════════
-  // Category 7: Automation Snippets (4 methods)
+  // Category 7: Automation Snippets (5 methods)
   // ══════════════════════════════════════════════
 
   /**
@@ -1176,6 +1179,15 @@ class DashClaw {
     return this._request(`/api/snippets?${params}`, 'GET');
   }
 
+  /**
+   * Fetch a single snippet by ID.
+   * @param {string} snippetId - The snippet ID
+   * @returns {Promise<{snippet: Object}>}
+   */
+  async getSnippet(snippetId) {
+    return this._request(`/api/snippets/${snippetId}`, 'GET');
+  }
+
   /**
    * Mark a snippet as used (increments use_count).
    * @param {string} snippetId - The snippet ID
@@ -1524,6 +1536,217 @@ class DashClaw {
     return this._request(`/api/guard?${params}`, 'GET');
   }
 
+  // ══════════════════════════════════════════════════════════
+  // Category 14: Policy Testing (3 methods)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * Run guardrails tests against all active policies for this org.
+   * @returns {Promise<{success: boolean, total_policies: number, total_tests: number, passed: number, failed: number, details: Object[]}>}
+   */
+  async testPolicies() {
+    return this._request('/api/policies/test', 'POST', {
+      agent_id: this.agentId,
+    });
+  }
+
+  /**
+   * Generate a compliance proof report from active policies.
+   * @param {Object} [options]
+   * @param {string} [options.format='json'] - 'json' or 'md'
+   * @returns {Promise<Object|string>}
+   */
+  async getProofReport(options = {}) {
+    const params = new URLSearchParams();
+    if (options.format) params.set('format', options.format);
+    return this._request(`/api/policies/proof?${params}`, 'GET');
+  }
+
+  /**
+   * Import a policy pack or raw YAML into the org's guard policies.
+   * Requires admin role.
+   * @param {Object} options
+   * @param {string} [options.pack] - Pack name: enterprise-strict, smb-safe, startup-growth, development
+   * @param {string} [options.yaml] - Raw YAML string of policies to import
+   * @returns {Promise<{imported: number, skipped: number, errors: string[], policies: Object[]}>}
+   */
+  async importPolicies({ pack, yaml } = {}) {
+    return this._request('/api/policies/import', 'POST', { pack, yaml });
+  }
+
+  // ══════════════════════════════════════════════════════════
+  // Category 15: Compliance Engine (5 methods)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * Map active policies to a compliance framework's controls.
+   * @param {string} framework - Framework ID: soc2, iso27001, gdpr, nist-ai-rmf, imda-agentic
+   * @returns {Promise<Object>} Compliance map with controls, coverage, and gaps
+   */
+  async mapCompliance(framework) {
+    return this._request(`/api/compliance/map?framework=${encodeURIComponent(framework)}`, 'GET');
+  }
+
+  /**
+   * Run gap analysis on a compliance framework mapping.
+   * @param {string} framework - Framework ID
+   * @returns {Promise<Object>} Gap analysis with remediation plan and risk assessment
+   */
+  async analyzeGaps(framework) {
+    return this._request(`/api/compliance/gaps?framework=${encodeURIComponent(framework)}`, 'GET');
+  }
+
+  /**
+   * Generate a full compliance report (markdown or JSON) and save a snapshot.
+   * @param {string} framework - Framework ID
+   * @param {Object} [options]
+   * @param {string} [options.format='json'] - 'json' or 'md'
+   * @returns {Promise<Object>}
+   */
+  async getComplianceReport(framework, options = {}) {
+    const params = new URLSearchParams({ framework });
+    if (options.format) params.set('format', options.format);
+    return this._request(`/api/compliance/report?${params}`, 'GET');
+  }
+
+  /**
+   * List available compliance frameworks.
+   * @returns {Promise<{frameworks: Object[]}>}
+   */
+  async listFrameworks() {
+    return this._request('/api/compliance/frameworks', 'GET');
+  }
+
+  /**
+   * Get live compliance evidence from guard decisions and action records.
+   * @param {Object} [options]
+   * @param {string} [options.window='30d'] - Time window (e.g., '7d', '30d', '90d')
+   * @returns {Promise<{evidence: Object}>}
+   */
+  async getComplianceEvidence(options = {}) {
+    const params = new URLSearchParams();
+    if (options.window) params.set('window', options.window);
+    return this._request(`/api/compliance/evidence?${params}`, 'GET');
+  }
+
+  // ══════════════════════════════════════════════════════════
+  // Category 16: Task Routing (10 methods)
+  // ══════════════════════════════════════════════════════════
+
+  /**
+   * List routing agents registered in this org.
+   * @param {Object} [filters]
+   * @param {string} [filters.status] - Filter by status: available, busy, offline
+   * @returns {Promise<{agents: Object[]}>}
+   */
+  async listRoutingAgents(filters = {}) {
+    const params = new URLSearchParams();
+    if (filters.status) params.set('status', filters.status);
+    return this._request(`/api/routing/agents?${params}`, 'GET');
+  }
+
+  /**
+   * Register an agent for task routing.
+   * @param {Object} agent
+   * @param {string} agent.name - Agent name
+   * @param {Array} [agent.capabilities] - Skills/capabilities (strings or {skill, priority} objects)
+   * @param {number} [agent.maxConcurrent=3] - Max concurrent tasks
+   * @param {string} [agent.endpoint] - Webhook endpoint for task dispatch
+   * @returns {Promise<{agent: Object}>}
+   */
+  async registerRoutingAgent(agent) {
+    return this._request('/api/routing/agents', 'POST', agent);
+  }
+
+  /**
+   * Get a single routing agent by ID.
+   * @param {string} agentId - Routing agent ID
+   * @returns {Promise<{agent: Object, metrics: Object[]}>}
+   */
+  async getRoutingAgent(agentId) {
+    return this._request(`/api/routing/agents/${encodeURIComponent(agentId)}`, 'GET');
+  }
+
+  /**
+   * Update routing agent status.
+   * @param {string} agentId - Routing agent ID
+   * @param {string} status - New status: available, busy, offline
+   * @returns {Promise<{agent: Object}>}
+   */
+  async updateRoutingAgentStatus(agentId, status) {
+    return this._request(`/api/routing/agents/${encodeURIComponent(agentId)}`, 'PATCH', { status });
+  }
+
+  /**
+   * Unregister (delete) a routing agent.
+   * @param {string} agentId - Routing agent ID
+   * @returns {Promise<{deleted: Object}>}
+   */
+  async deleteRoutingAgent(agentId) {
+    return this._request(`/api/routing/agents/${encodeURIComponent(agentId)}`, 'DELETE');
+  }
+
+  /**
+   * List routing tasks with optional filters.
+   * @param {Object} [filters]
+   * @param {string} [filters.status] - Filter by status
+   * @param {string} [filters.assignedTo] - Filter by assigned agent
+   * @param {number} [filters.limit=50] - Max results
+   * @returns {Promise<{tasks: Object[]}>}
+   */
+  async listRoutingTasks(filters = {}) {
+    const params = new URLSearchParams();
+    if (filters.status) params.set('status', filters.status);
+    if (filters.assignedTo) params.set('assigned_to', filters.assignedTo);
+    if (filters.limit) params.set('limit', String(filters.limit));
+    return this._request(`/api/routing/tasks?${params}`, 'GET');
+  }
+
+  /**
+   * Submit a task for auto-routing to the best available agent.
+   * @param {Object} task
+   * @param {string} task.title - Task title
+   * @param {string} [task.description] - Task description
+   * @param {string[]} [task.requiredSkills] - Skills needed to complete this task
+   * @param {string} [task.urgency='normal'] - Urgency: low, normal, high, critical
+   * @param {number} [task.timeoutSeconds=3600] - Timeout in seconds
+   * @param {number} [task.maxRetries=2] - Max retry attempts
+   * @param {string} [task.callbackUrl] - Webhook URL for task completion callback
+   * @returns {Promise<{task: Object, routing: Object}>}
+   */
+  async submitRoutingTask(task) {
+    return this._request('/api/routing/tasks', 'POST', task);
+  }
+
+  /**
+   * Complete a routing task.
+   * @param {string} taskId - Task ID
+   * @param {Object} [result]
+   * @param {boolean} [result.success=true] - Whether task succeeded
+   * @param {Object} [result.result] - Task result data
+   * @param {string} [result.error] - Error message if failed
+   * @returns {Promise<{task: Object, routing: Object}>}
+   */
+  async completeRoutingTask(taskId, result = {}) {
+    return this._request(`/api/routing/tasks/${encodeURIComponent(taskId)}/complete`, 'POST', result);
+  }
+
+  /**
+   * Get routing statistics for the org.
+   * @returns {Promise<{agents: Object, tasks: Object, routing: Object}>}
+   */
+  async getRoutingStats() {
+    return this._request('/api/routing/stats', 'GET');
+  }
+
+  /**
+   * Get routing system health status.
+   * @returns {Promise<{status: string, agents: Object, tasks: Object}>}
+   */
+  async getRoutingHealth() {
+    return this._request('/api/routing/health', 'GET');
+  }
+
   // ─── Bulk Sync ────────────────────────────────────────────
 
   /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dashclaw",
-  "version": "1.7.1",
-  "description": "Full-featured agent toolkit for the DashClaw platform. 60+ methods for action recording, context management, session handoffs, security scanning, behavior guard, bulk sync, and more.",
+  "version": "1.8.0",
+  "description": "Full-featured agent toolkit for the DashClaw platform. 78+ methods for action recording, context management, session handoffs, security scanning, behavior guard, compliance, task routing, bulk sync, and more.",
   "type": "module",
   "publishConfig": {
     "access": "public"