dashclaw 2.1.1 → 2.1.3

package/README.md

@@ -1,4 +1,4 @@
-# DashClaw SDK (v2)
+# DashClaw SDK (v2.1.2)
 
 **Minimal governance runtime for AI agents.**
 
@@ -6,70 +6,102 @@ The DashClaw SDK provides the infrastructure to intercept, govern, and verify ag
 
 ## Installation
 
+### Node.js
 ```bash
 npm install dashclaw
 ```
 
+### Python
+```bash
+pip install dashclaw
+```
+
 ## The Governance Loop
 
 DashClaw v2 is designed around a single 4-step loop.
 
+### Node.js
 ```javascript
-import { DashClaw, GuardBlockedError } from 'dashclaw';
+import { DashClaw } from 'dashclaw';
 
 const claw = new DashClaw({
-  baseUrl: process.env.DASHCLAW_BASE_URL,
+  baseUrl: 'https://dashclaw.io',
   apiKey: process.env.DASHCLAW_API_KEY,
   agentId: 'my-agent'
 });
 
-async function runAgentTask() {
-  // 1. GUARD: Ask for permission
-  // Intercepts intent and evaluates vs. organization policies.
-  const decision = await claw.guard({ 
-    action_type: 'deploy', 
-    risk_score: 85 
-  });
-
-  // 2. RECORD: Log the attempt
-  // Promotes guarded intent into a recorded action record.
-  const action = await claw.createAction({
-    action_type: 'deploy',
-    declared_goal: 'Deploying latest build'
-  });
-
-  try {
-    // 3. VERIFY: Record assumptions
-    // Tracks beliefs to detect reasoning drift later.
-    await claw.recordAssumption({
-      action_id: action.action_id,
-      assumption: 'The staging tests passed.'
-    });
-
-    // Execute the real-world action here...
-    // await deploy();
-
-    // 4. OUTCOME: Log the evidence
-    await claw.updateOutcome(action.action_id, { status: 'completed' });
-
-  } catch (err) {
-    await claw.updateOutcome(action.action_id, { status: 'failed', error: err.message });
-  }
-}
+// 1. Ask permission
+const res = await claw.guard({ action_type: 'deploy' });
+
+// 2. Log intent
+const { action_id } = await claw.createAction({ action_type: 'deploy' });
+
+// 3. Log evidence
+await claw.recordAssumption({ action_id, assumption: 'Tests passed' });
+
+// 4. Update result
+await claw.updateOutcome(action_id, { status: 'completed' });
+```
+
+### Python
+```python
+from dashclaw import DashClaw
+
+claw = DashClaw(
+    base_url="https://dashclaw.io",
+    api_key="your_api_key",
+    agent_id="my-agent"
+)
+
+# 1. Ask permission
+res = claw.guard({"action_type": "deploy"})
+
+# 2. Log intent
+action = claw.create_action(action_type="deploy")
+action_id = action["action_id"]
+
+# 3. Log evidence
+claw.record_assumption({"action_id": action_id, "assumption": "Tests passed"})
+
+# 4. Update result
+claw.update_outcome(action_id, status="completed")
 ```
 
 ---
 
-## SDK Surface Area (v2)
+## SDK Surface Area (v2.1.2)
 
-The v2 SDK is optimized for stability and zero-overhead governance:
+The v2.1.2 SDK is optimized for stability and zero-overhead governance:
 
+### Core Runtime
 - `guard(context)` — Policy evaluation ("Can I do X?")
 - `createAction(action)` — Lifecycle tracking ("I am doing X")
 - `updateOutcome(id, outcome)` — Result recording ("X finished with Y")
 - `recordAssumption(assumption)` — Integrity tracking ("I believe Z while doing X")
 - `waitForApproval(id)` — Polling helper for human-in-the-loop approvals
 
+### Decision Integrity
+- `registerOpenLoop(actionId, type, desc)` — Register unresolved dependencies.
+- `resolveOpenLoop(loopId, status, res)` — Resolve pending loops.
+- `getSignals()` — Get current risk signals across all agents.
+
+### Swarm & Connectivity
+- `heartbeat(status, metadata)` — Report agent presence and health.
+- `reportConnections(connections)` — Report active provider connections.
+
+### Learning & Optimization
+- `getLearningVelocity()` — Track agent improvement rate.
+- `getLearningCurves()` — Measure efficiency gains per action type.
+- `renderPrompt(context)` — Fetch rendered prompt templates from DashClaw.
+
+### Compliance & Audit
+- `createScorer(name, type, config)` — Define automated evaluations.
+- `createScoringProfile(profile)` — Weighted quality scoring.
+- `mapCompliance(framework)` — Map behavior to regulatory controls.
+- `getProofReport(format)` — Generate audit-ready evidence exports.
+- `getActivityLogs(filters)` — Query the immutable audit trail.
+- `createWebhook(url, events)` — Real-time event exfiltration.
+
 ---
 
 ## Error Handling
@@ -83,17 +115,7 @@ DashClaw uses standard HTTP status codes and custom error classes:
 
 ## Legacy SDK (v1)
 
-If you require legacy features (Calendar, Messages, Workflows, etc.), the v1 SDK is available via the `legacy` sub-path:
-
-```javascript
-// ESM
-import { DashClaw } from 'dashclaw/legacy';
-
-// CommonJS
-const { DashClaw } = require('dashclaw/legacy');
-```
-
-*Note: Legacy features are now considered "Extensions" and require these routes to be enabled on your DashClaw server.*
+If you require legacy features (Calendar, Messages, Workflows, etc.), the v1 SDK is available via the `legacy` sub-path in Node.js or via the full client in Python.
 
 ---
 

package/dashclaw.js

@@ -72,9 +72,6 @@ class DashClaw {
   /**
    * POST /api/guard — "Can I do X?"
    * @param {Object} context
-   * @param {string} context.action - Action type (e.g. "deploy")
-   * @param {string} [context.intent] - What the action aims to do
-   * @param {number} [context.risk_score] - Risk score 0-100
    * @returns {Promise<{decision: 'allow'|'block'|'require_approval', action_id: string, reason: string, signals: string[]}>}
    */
   async guard(context) {
@@ -86,23 +83,16 @@ class DashClaw {
 
   /**
    * POST /api/actions — "I am attempting X."
-   * @param {Object} action
-   * @param {string} action.action_type - e.g. "deploy"
-   * @param {string} action.declared_goal - e.g. "deploy to production"
-   * @returns {Promise<{action: Object, action_id: string}>}
    */
   async createAction(action) {
-    const res = await this._request('/api/actions', 'POST', {
+    return this._request('/api/actions', 'POST', {
       ...action,
       agent_id: this.agentId,
     });
-    return res;
   }
 
   /**
    * PATCH /api/actions/:id — "X finished with result Y."
-   * @param {string} actionId
-   * @param {Object} outcome
    */
   async updateOutcome(actionId, outcome) {
     return this._request(`/api/actions/${actionId}`, 'PATCH', {
@@ -113,7 +103,6 @@ class DashClaw {
 
   /**
    * POST /api/assumptions — "I believe Z is true while doing X."
-   * @param {Object} assumption
    */
   async recordAssumption(assumption) {
     return this._request('/api/assumptions', 'POST', assumption);
@@ -126,14 +115,158 @@ class DashClaw {
     const startTime = Date.now();
     while (Date.now() - startTime < timeout) {
       const { action } = await this._request(`/api/actions/${actionId}`, 'GET');
-      if (action.status === 'running' || action.status === 'completed') return action;
+      
+      // Explicitly unblocked by approval metadata
+      if (action.approved_by) return action;
+
+      // Denial cases
       if (action.status === 'failed' || action.status === 'cancelled') {
         throw new ApprovalDeniedError(action.error_message || 'Operator denied the action.', action.status);
       }
+
+      // Requirement 4: If an action leaves pending_approval without approval metadata, throw an error.
+      // This prevents "auto-approval" bugs where status is changed by non-approval paths.
+      if (action.status !== 'pending_approval') {
+        throw new Error(`Action ${actionId} left pending_approval state without explicit approval metadata (Status: ${action.status})`);
+      }
+
       await new Promise(r => setTimeout(r, interval));
     }
     throw new Error(`Timed out waiting for approval of action ${actionId}`);
   }
+
+  /**
+   * POST /api/agents/heartbeat
+   */
+  async heartbeat(status = 'online', metadata = null) {
+    return this._request('/api/agents/heartbeat', 'POST', {
+      agent_id: this.agentId,
+      status,
+      metadata
+    });
+  }
+
+  /**
+   * POST /api/agents/connections
+   */
+  async reportConnections(connections) {
+    return this._request('/api/agents/connections', 'POST', {
+      agent_id: this.agentId,
+      connections
+    });
+  }
+
+  /**
+   * POST /api/actions/loops
+   */
+  async registerOpenLoop(actionId, loopType, description, metadata = null) {
+    return this._request('/api/actions/loops', 'POST', {
+      action_id: actionId,
+      loop_type: loopType,
+      description,
+      metadata
+    });
+  }
+
+  /**
+   * PATCH /api/actions/loops/:id
+   */
+  async resolveOpenLoop(loopId, status, resolution = null) {
+    return this._request(`/api/actions/loops/${loopId}`, 'PATCH', {
+      status,
+      resolution
+    });
+  }
+
+  /**
+   * GET /api/actions/signals
+   */
+  async getSignals() {
+    return this._request('/api/actions/signals');
+  }
+
+  /**
+   * GET /api/learning/analytics/velocity
+   */
+  async getLearningVelocity(lookbackDays = 30) {
+    return this._request('/api/learning/analytics/velocity', 'GET', null, {
+      agent_id: this.agentId,
+      lookback_days: lookbackDays
+    });
+  }
+
+  /**
+   * GET /api/learning/analytics/curves
+   */
+  async getLearningCurves(lookbackDays = 60) {
+    return this._request('/api/learning/analytics/curves', 'GET', null, {
+      agent_id: this.agentId,
+      lookback_days: lookbackDays
+    });
+  }
+
+  /**
+   * POST /api/prompts/render
+   */
+  async renderPrompt({ template_id, version_id, variables, record = false }) {
+    return this._request('/api/prompts/render', 'POST', {
+      template_id,
+      version_id,
+      variables,
+      agent_id: this.agentId,
+      record
+    });
+  }
+
+  /**
+   * POST /api/evaluations/scorers
+   */
+  async createScorer(name, scorer_type, config = null, description = null) {
+    return this._request('/api/evaluations/scorers', 'POST', {
+      name,
+      scorer_type,
+      config,
+      description
+    });
+  }
+
+  /**
+   * POST /api/scoring/profiles
+   */
+  async createScoringProfile(profile) {
+    return this._request('/api/scoring/profiles', 'POST', profile);
+  }
+
+  /**
+   * GET /api/compliance/map
+   */
+  async mapCompliance(framework) {
+    return this._request(`/api/compliance/map`, 'GET', null, { framework });
+  }
+
+  /**
+   * GET /api/policies/proof
+   */
+  async getProofReport(format = 'json') {
+    return this._request('/api/policies/proof', 'GET', null, { format });
+  }
+
+  /**
+   * GET /api/activity
+   */
+  async getActivityLogs(filters = {}) {
+    return this._request('/api/activity', 'GET', null, filters);
+  }
+
+  /**
+   * POST /api/webhooks
+   */
+  async createWebhook(url, events = null) {
+    return this._request('/api/webhooks', 'POST', {
+      url,
+      events
+    });
+  }
 }
 
 export { DashClaw, ApprovalDeniedError, GuardBlockedError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashclaw",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Minimal governance runtime for AI agents. Intercept, govern, and verify agent actions.",
   "type": "module",
   "publishConfig": {