dashclaw 2.6.0 → 2.8.0

package/README.md

@@ -1,4 +1,4 @@
-# DashClaw SDK (v2.6.0)
+# DashClaw SDK (v2.7.0)
 
 **Minimal governance runtime for AI agents.**
 
@@ -235,6 +235,106 @@ await claw.syncState({
 
 ---
 
+## Agent Identity
+
+Enroll agents via public-key pairing and manage approved identities for signature verification. Pairing is available in the v1 legacy SDK; the REST endpoints are callable directly from any HTTP client.
+
+### Create Pairing
+
+```javascript
+// Node SDK (v1 legacy)
+import { DashClaw } from 'dashclaw/legacy';
+const claw = new DashClaw({ baseUrl, apiKey, agentId });
+
+const { pairing } = await claw.createPairing(publicKeyPem, 'RSASSA-PKCS1-v1_5', 'my-agent');
+console.log(pairing.id); // pair_...
+```
+
+### Wait for Pairing Approval
+
+```javascript
+const approved = await claw.waitForPairing(pairing.id, { timeout: 300 });
+```
+
+### Get Pairing
+
+```javascript
+const status = await claw.getPairing(pairingId);
+console.log(status.pairing.status); // pending | approved | expired
+```
+
+### Approve Pairing (Admin)
+
+```javascript
+// Direct HTTP — admin API key required
+const res = await fetch(`${baseUrl}/api/pairings/${pairingId}/approve`, {
+  method: 'POST',
+  headers: { 'x-api-key': adminApiKey }
+});
+```
+
+### List Pairings (Admin)
+
+```javascript
+const res = await fetch(`${baseUrl}/api/pairings`, {
+  headers: { 'x-api-key': adminApiKey }
+});
+const { pairings } = await res.json();
+```
+
+### Register Identity (Admin)
+
+```javascript
+// Node SDK (v1 legacy)
+await claw.registerIdentity('agent-007', publicKeyPem, 'RSASSA-PKCS1-v1_5');
+```
+
+### List Identities (Admin)
+
+```javascript
+const { identities } = await claw.getIdentities();
+```
+
+### Revoke Identity (Admin)
+
+```javascript
+// Direct HTTP — admin API key required
+const res = await fetch(`${baseUrl}/api/identities/${agentId}`, {
+  method: 'DELETE',
+  headers: { 'x-api-key': adminApiKey }
+});
+```
+
+---
+
+## Action Context (Auto-Tagging)
+
+When sending messages or recording assumptions during an action, use `actionContext()` to automatically tag them with the action_id:
+
+### Node.js
+```javascript
+const action = await claw.createAction({ action_type: 'deploy', declared_goal: 'Deploy v2' });
+
+const ctx = claw.actionContext(action.action_id);
+await ctx.sendMessage({ to: 'ops-agent', type: 'status', body: 'Starting deploy' });
+await ctx.recordAssumption({ assumption: 'Staging tests passed' });
+await ctx.updateOutcome({ status: 'completed', output_summary: 'Deployed' });
+```
+
+### Python
+```python
+action = claw.create_action(action_type="deploy", declared_goal="Deploy v2")
+
+with claw.action_context(action["action_id"]) as ctx:
+    ctx.send_message("Starting deploy", to="ops-agent")
+    ctx.record_assumption({"assumption": "Staging tests passed"})
+    ctx.update_outcome(status="completed", output_summary="Deployed")
+```
+
+Messages sent through the context are automatically correlated with the action in the decisions ledger and timeline.
+
+---
+
 ## Error Handling
 
 DashClaw uses standard HTTP status codes and custom error classes:

package/dashclaw.js

@@ -1,5 +1,5 @@
 /**
- * DashClaw SDK v2 (Stable Runtime API)
+ * DashClaw SDK v2.8.0 (Stable Runtime API)
  * Focused governance runtime client for AI agents.
  */
 
@@ -456,6 +456,26 @@ class DashClaw {
     });
   }
 
+  /**
+   * Create a scoped action context that auto-tags messages and assumptions
+   * with the given action_id.
+   * @param {string} actionId - The action_id to attach to all operations
+   * @returns {{ sendMessage, recordAssumption, updateOutcome }}
+   */
+  actionContext(actionId) {
+    return {
+      sendMessage: ({ to, type, subject, body, threadId, urgent }) => {
+        return this.sendMessage({ to, type, subject, body, threadId, urgent, actionId });
+      },
+      recordAssumption: (assumption) => {
+        return this.recordAssumption({ ...assumption, action_id: actionId });
+      },
+      updateOutcome: (outcome) => {
+        return this.updateOutcome(actionId, outcome);
+      },
+    };
+  }
+
   /**
    * GET /api/messages — Fetch this agent's inbox.
    */
@@ -574,6 +594,55 @@ class DashClaw {
       ...state,
     });
   }
+
+  // ---------------------------------------------------------------------------
+  // Session Lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * POST /api/sessions — Create a new agent session.
+   * @param {string} agentId - Agent identifier (defaults to this.agentId)
+   * @param {string} workspace - Workspace path or identifier
+   * @param {string|null} [branch=null] - Optional git branch
+   */
+  async createSession(agentId, workspace, branch = null) {
+    return this._request('/api/sessions', 'POST', {
+      agent_id: agentId || this.agentId,
+      workspace,
+      branch,
+    });
+  }
+
+  /**
+   * GET /api/sessions/:id — Fetch a single session by ID.
+   */
+  async getSession(sessionId) {
+    return this._request(`/api/sessions/${sessionId}`, 'GET');
+  }
+
+  /**
+   * PATCH /api/sessions/:id — Update session state.
+   * @param {string} sessionId
+   * @param {Object} updates - Fields to update (status, green_level, branch_freshness, commits_behind, blocked_reason)
+   */
+  async updateSession(sessionId, updates) {
+    return this._request(`/api/sessions/${sessionId}`, 'PATCH', updates);
+  }
+
+  /**
+   * GET /api/sessions — List sessions with optional filters.
+   * @param {Object} [filters={}] - Query filters (agent_id, status, limit)
+   */
+  async listSessions(filters = {}) {
+    return this._request('/api/sessions', 'GET', null, filters);
+  }
+
+  /**
+   * GET /api/sessions/:id/events — Fetch events for a session.
+   */
+  async getSessionEvents(sessionId) {
+    return this._request(`/api/sessions/${sessionId}/events`, 'GET');
+  }
 }
 
 export { DashClaw, ApprovalDeniedError, GuardBlockedError };

package/package.json

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