dashclaw 1.3.0 → 1.6.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 57 methods across action recording, behavior guard, context management, session handoffs, security scanning, and more.
+Install, configure, and instrument your AI agents with 59 methods across action recording, behavior guard, context management, session handoffs, security scanning, and more.
 
 ---
 
@@ -23,6 +23,7 @@ const claw = new DashClaw({
   apiKey: process.env.DASHCLAW_API_KEY,
   agentId: 'my-agent',
   agentName: 'My Agent',
+  hitlMode: 'wait', // Optional: automatically wait for human approval
 });
 ```
 
@@ -51,7 +52,7 @@ await claw.updateOutcome(action_id, {
 Create a DashClaw instance. Requires Node 18+ (native fetch).
 
 ```javascript
-const claw = new DashClaw({ baseUrl, apiKey, agentId, agentName, swarmId, guardMode, guardCallback });
+const claw = new DashClaw({ baseUrl, apiKey, agentId, agentName, swarmId, guardMode, guardCallback, hitlMode });
 ```
 
 ### Parameters
@@ -64,27 +65,30 @@ const claw = new DashClaw({ baseUrl, apiKey, agentId, agentName, swarmId, guardM
 | swarmId | string | No | Swarm/group identifier if part of a multi-agent system |
 | guardMode | string | No | Auto guard check before createAction/track: "off" (default), "warn" (log + proceed), "enforce" (throw on block) |
 | guardCallback | Function | No | Called with guard decision object when guardMode is active |
+| hitlMode | string | No | HITL behavior: "off" (default - return 202 immediately), "wait" (automatically block and poll until approved/denied) |
 
-### Guard Mode
+### Guard Mode & HITL
 When `guardMode` is set, every call to `createAction()` and `track()` automatically checks guard policies before proceeding.
 
 ```javascript
-import { DashClaw, GuardBlockedError } from 'dashclaw';
+import { DashClaw, GuardBlockedError, ApprovalDeniedError } from 'dashclaw';
 
 const claw = new DashClaw({
   baseUrl: 'https://your-app.vercel.app',
   apiKey: process.env.DASHCLAW_API_KEY,
   agentId: 'my-agent',
-  guardMode: 'enforce', // throws GuardBlockedError on block/require_approval
-  guardCallback: (decision) => console.log('Guard:', decision.decision),
+  guardMode: 'enforce', // throws GuardBlockedError on block
+  hitlMode: 'wait',     // poll until approved or throw ApprovalDeniedError
 });
 
 try {
   await claw.createAction({ action_type: 'deploy', declared_goal: 'Ship v2' });
+  // If a policy triggers 'require_approval', the SDK will pause here until an admin clicks 'Allow'
 } catch (err) {
   if (err instanceof GuardBlockedError) {
-    console.log(err.decision);  // 'block' or 'require_approval'
-    console.log(err.reasons);   // ['Risk score 90 >= threshold 80']
+    console.log('Blocked by policy:', err.reasons);
+  } else if (err instanceof ApprovalDeniedError) {
+    console.log('Denied by human operator');
   }
 }
 ```
@@ -98,6 +102,8 @@ Create, update, and query action records. Every agent action gets a full audit t
 ### claw.createAction(action)
 Create a new action record. The agent's agentId, agentName, and swarmId are automatically attached.
 
+If `hitlMode` is set to `'wait'` and the action requires approval, this method will not return until the action is approved or denied (or it times out).
+
 **Parameters:**
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -127,6 +133,19 @@ const { action_id } = await claw.createAction({
 });
 ```
 
+### claw.waitForApproval(actionId, options?)
+Manual poll for human approval. Only needed if `hitlMode` is `'off'`.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| actionId | string | Yes | The action_id to poll |
+| options.timeout | number | No | Max wait time in ms (default: 300000 / 5 min) |
+| options.interval | number | No | Poll interval in ms (default: 5000) |
+
+**Returns:** `Promise<{ action: Object, action_id: string }>`
+**Throws:** `ApprovalDeniedError` if denied.
+
 ### claw.updateOutcome(actionId, outcome)
 Update the outcome of an existing action. Automatically sets timestamp_end if not provided.
 

package/dashclaw.js

@@ -3,8 +3,8 @@
  * Full-featured agent toolkit for the DashClaw platform.
  * Zero-dependency ESM SDK — requires Node 18+ (native fetch).
  *
- * 58 methods across 13 categories:
- * - Action Recording (6)
+ * 59 methods across 13 categories:
+ * - Action Recording (7)
  * - Loops & Assumptions (7)
  * - Signals (1)
  * - Dashboard Data (9)
@@ -29,9 +29,10 @@ class DashClaw {
    * @param {string} [options.swarmId] - Swarm/group identifier if part of a multi-agent system
    * @param {string} [options.guardMode='off'] - Auto guard check before createAction: 'off' | 'warn' | 'enforce'
    * @param {Function} [options.guardCallback] - Called with guard decision object when guardMode is active
+   * @param {string} [options.hitlMode='off'] - How to handle pending approvals: 'off' (return immediately) | 'wait' (block and poll)
    * @param {CryptoKey} [options.privateKey] - Web Crypto API Private Key for signing actions
    */
-  constructor({ baseUrl, apiKey, agentId, agentName, swarmId, guardMode, guardCallback, privateKey }) {
+  constructor({ baseUrl, apiKey, agentId, agentName, swarmId, guardMode, guardCallback, hitlMode, privateKey }) {
     if (!baseUrl) throw new Error('baseUrl is required');
     if (!apiKey) throw new Error('apiKey is required');
     if (!agentId) throw new Error('agentId is required');
@@ -48,6 +49,7 @@ class DashClaw {
     this.swarmId = swarmId || null;
     this.guardMode = guardMode || 'off';
     this.guardCallback = guardCallback || null;
+    this.hitlMode = hitlMode || 'off';
     this.privateKey = privateKey || null;
     
     // Auto-import JWK if passed as plain object
@@ -193,10 +195,46 @@ class DashClaw {
       }
     }
 
-    return this._request('/api/actions', 'POST', {
+    const res = await this._request('/api/actions', 'POST', {
       ...payload,
       _signature: signature
     });
+
+    // Handle HITL Approval
+    if (res.action?.status === 'pending_approval' && this.hitlMode === 'wait') {
+      console.log(`[DashClaw] Action ${res.action_id} requires human approval. Waiting...`);
+      return this.waitForApproval(res.action_id);
+    }
+
+    return res;
+  }
+
+  /**
+   * Poll for human approval of a pending action.
+   * @param {string} actionId 
+   * @param {Object} [options]
+   * @param {number} [options.timeout=300000] - Max wait time (5 min)
+   * @param {number} [options.interval=5000] - Poll interval
+   */
+  async waitForApproval(actionId, { timeout = 300000, interval = 5000 } = {}) {
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < timeout) {
+      const { action } = await this.getAction(actionId);
+      
+      if (action.status === 'running') {
+        console.log(`[DashClaw] Action ${actionId} approved by operator.`);
+        return { action, action_id: actionId };
+      }
+      
+      if (action.status === 'failed' || action.status === 'cancelled') {
+        throw new ApprovalDeniedError(action.error_message || 'Operator denied the action.');
+      }
+      
+      await new Promise(r => setTimeout(r, interval));
+    }
+    
+    throw new Error(`[DashClaw] Timed out waiting for approval of action ${actionId}`);
   }
 
   /**
@@ -1133,8 +1171,18 @@ class GuardBlockedError extends Error {
   }
 }
 
+/**
+ * Error thrown when a human operator denies an action.
+ */
+class ApprovalDeniedError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ApprovalDeniedError';
+  }
+}
+
 // Backward compatibility alias (Legacy)
 const OpenClawAgent = DashClaw;
 
 export default DashClaw;
-export { DashClaw, OpenClawAgent, GuardBlockedError };
+export { DashClaw, OpenClawAgent, GuardBlockedError, ApprovalDeniedError };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dashclaw",
-  "version": "1.3.0",
-  "description": "Full-featured agent toolkit for the DashClaw platform. 58 methods for action recording, context management, session handoffs, security scanning, behavior guard, bulk sync, and more.",
+  "version": "1.6.0",
+  "description": "Full-featured agent toolkit for the DashClaw platform. 59 methods for action recording, context management, session handoffs, security scanning, behavior guard, bulk sync, and more.",
   "type": "module",
   "publishConfig": {
     "access": "public"