dashclaw 2.12.0 → 2.13.1

package/README.md

@@ -1,4 +1,4 @@
-# DashClaw SDK (v2.11.1)
+# DashClaw SDK
 
 **Minimal governance runtime for AI agents.**
 
@@ -34,6 +34,10 @@ const claw = new DashClaw({
   apiKey: process.env.DASHCLAW_API_KEY,
   agentId: 'my-agent',
   agentName: 'My Agent',  // optional — stored in audit trail for attribution
+  // Phase 2 (optional): attach a JWT from your OIDC provider for cryptographic
+  // attribution. When set, the server verifies the signature via JWKS and the
+  // JWT sub claim overrides agentId in the audit record.
+  // authToken: process.env.MY_AGENT_JWT,
 });
 
 // 1. Ask permission
@@ -137,14 +141,16 @@ Telegram button.
 ### The rule every agent author needs to know
 
 **`waitForApproval()` must be called with the `action_id` returned by
-`createAction()`, NOT with the `action_id` returned by `guard()`.**
+`createAction()`, NOT with the guard decision's id.**
 
 These are two different records in two different tables:
 
-| Call | Returns `action_id` that refers to… | Prefix |
-|---|---|---|
-| `guard()` | A row in `guard_decisions` (the decision log) | `act_gd_…` |
-| `createAction()` | A row in `action_records` (the thing you're actually doing) | `act_…` |
+| Call | Returns an id that refers to… | Prefix | Field on the result |
+|---|---|---|---|
+| `guard()` | A row in `guard_decisions` (the decision log) | `act_gd_…` | `decision_id` (canonical); `action_id` is a **deprecated alias** of the same value |
+| `createAction()` | A row in `action_records` (the thing you're actually doing) | `act_…` | `action_id` |
+
+> The guard result's `action_id` field is a legacy alias of `decision_id` and will be removed in a future major — read `decision_id` from `guard()`, and `action_id` from `createAction()`.
 
 `waitForApproval()` polls `GET /api/actions/:id`, which is the
 `action_records` table. Passing it a `guard_decisions` ID (`act_gd_…`) will
@@ -247,12 +253,12 @@ See:
 
 ---
 
-## SDK Surface Area (v2.11.1)
+## SDK Surface Area
 
 The v2 SDK exposes the stable governance runtime plus promoted execution domains in the canonical Node client:
 
 ### Core Runtime
-- `guard(context)` -- Policy evaluation ("Can I do X?"). Returns `risk_score` (server-computed) and `agent_risk_score` (raw agent value). Automatically includes `agent_name` from the constructor if not overridden in the call context.
+- `guard(context)` -- Policy evaluation ("Can I do X?"). Returns `risk_score` (server-computed), `agent_risk_score` (raw agent value), and `verification_status` (`verified` | `unverified` | `expired` | `failed` | `unknown_issuer`). Automatically includes `agent_name` from the constructor if not overridden in the call context. Pass `authToken` in the constructor to enable JWKS-backed cryptographic attribution (Phase 2 — see `docs/agent-identity.md`).
 - `createAction(action)` -- Lifecycle tracking ("I am doing X"). Accepts optional `idempotency_key`; on collision returns the existing row with `{ idempotent_replay: true }` instead of inserting a duplicate.
 - `updateOutcome(id, outcome)` -- Result recording ("X finished with Y"). `outcome` accepts `status`, `output_summary`, `side_effects`, `artifacts_created`, `error_message`, `duration_ms`, `tokens_in`, `tokens_out`, `model`, `cost_estimate`. When `tokens_in` / `tokens_out` are reported without an explicit `cost_estimate`, the server derives cost from `model` using the configured pricing table.
 - `recordAssumption(assumption)` -- Integrity tracking ("I believe Z while doing X")
@@ -332,6 +338,11 @@ lessons.forEach(l => console.log(l.guidance));
 ### Messaging
 - `sendMessage({ to, type, subject, body, threadId, urgent })` -- Send a message to another agent or broadcast.
 - `getInbox({ type, unread, limit })` -- Retrieve inbox messages with optional filters.
+- `getSentMessages({ type, threadId, limit })` -- Retrieve messages this agent has sent.
+- `getMessages({ direction, type, unread, threadId, limit })` -- Retrieve messages with flexible filters.
+- `getMessage(messageId)` -- Fetch a single message by id.
+- `markRead(messageIds)` -- Mark messages as read for this agent (`PATCH /api/messages`, `action: 'read'`).
+- `archiveMessages(messageIds)` -- Archive messages for this agent (`PATCH /api/messages`, `action: 'archive'`).
 
 ```javascript
 // Send a message to another agent
@@ -590,9 +601,29 @@ If your agent supports Model Context Protocol (Claude Code, Claude Desktop, Mana
 
 **Streamable HTTP transport** (same surface, served by your DashClaw instance at `POST /api/mcp`).
 
-**8 tools:** `dashclaw_guard`, `dashclaw_record`, `dashclaw_invoke`, `dashclaw_capabilities_list`, `dashclaw_policies_list`, `dashclaw_wait_for_approval`, `dashclaw_session_start`, `dashclaw_session_end`.
+**23 tools** in 7 groups:
+
+- **Core governance (8):** `dashclaw_guard`, `dashclaw_record`, `dashclaw_invoke`, `dashclaw_capabilities_list`, `dashclaw_policies_list`, `dashclaw_wait_for_approval`, `dashclaw_session_start`, `dashclaw_session_end`.
+- **Optimal files (2):** `dashclaw_optimal_files_preview`, `dashclaw_optimal_files_manifest` — Code Sessions optimizer output (root CLAUDE.md, path-scoped rules, hooks, skill packs).
+- **Session continuity (3):** `dashclaw_handoff_create`, `dashclaw_handoff_latest`, `dashclaw_handoff_consume` — agent-runtime handoff bundle for the next session.
+- **Credential hygiene (3):** `dashclaw_secret_list`, `dashclaw_secret_due`, `dashclaw_secret_mark_rotated` — check rotation due-dates before acting on tracked credentials.
+- **Skill safety (1):** `dashclaw_skill_scan` — static safety scan of untrusted skill files; results cached by content hash.
+- **Open loops (3):** `dashclaw_loop_add`, `dashclaw_loop_list`, `dashclaw_loop_close` — action-scoped commitments (the "I will X later" tracker).
+- **Learning + retrospection (3):** `dashclaw_learning_log`, `dashclaw_learning_query`, `dashclaw_decisions_recent` — log + query non-obvious decisions; recent governed-action ledger.
+
+**6 resources:** `dashclaw://policies`, `dashclaw://capabilities`, `dashclaw://agent/{agent_id}/history`, `dashclaw://status`, `dashclaw://code-sessions/projects`, `dashclaw://code-sessions/sessions/{session_id}`.
+
+### Agent runtime endpoints (server-side, no SDK wrapper)
+
+DashClaw 2.17 (platform) added three route families that are **agent-runtime infrastructure, not developer SDK methods**. They are called by the MCP server (the tools listed above), by Hermes Agent hooks, and by other governance plumbing — never directly from agent code. By design, they are not exposed on `claw.*`:
+
+| Family | Endpoints | Where called from |
+|---|---|---|
+| Session handoffs | `POST/GET /api/handoffs`, `GET /api/handoffs/latest`, `GET /api/handoffs/{id}`, `POST /api/handoffs/{id}/consume` | Hermes `on_session_end` / `on_session_start` / `pre_llm_call` hooks; MCP `dashclaw_handoff_*` tools |
+| Operator-tracked secrets | `GET/POST /api/secrets`, `PATCH/DELETE /api/secrets/{id}`, `GET /api/secrets/rotation-due` | MCP `dashclaw_secret_*` tools; operator UI |
+| Skill safety scan | `POST /api/skills/scan`, `GET /api/skills/scans/{id}` | MCP `dashclaw_skill_scan` tool; agents before loading an untrusted skill |
 
-**4 resources:** `dashclaw://policies`, `dashclaw://capabilities`, `dashclaw://agent/{agent_id}/history`, `dashclaw://status`.
+If you're building a custom integration that needs these without MCP, call them as plain HTTP — see `docs/api-inventory.md` and the OpenAPI spec at `docs/openapi/critical-stable.openapi.json`.
 
 ## OpenClaw Plugin (`@dashclaw/openclaw-plugin`)
 

package/dashclaw.js

@@ -1,6 +1,10 @@
 /**
- * DashClaw SDK v2.11.0 (Stable Runtime API)
+ * DashClaw SDK (Stable Runtime API)
  * Focused governance runtime client for AI agents.
+ *
+ * Version is the single source of truth in sdk/package.json — never
+ * hardcoded here, in the README header, or in app/ pages. Consumers
+ * read it at runtime via `import pkg from 'dashclaw/package.json'`.
  */
 
 import { createHash } from 'crypto';
@@ -28,8 +32,12 @@ class DashClaw {
    * @param {string} options.apiKey - API key for authentication
    * @param {string} options.agentId - Unique identifier for this agent
    * @param {string} [options.agentName] - Human-readable label for this agent (stored in audit trail)
+   * @param {string} [options.authToken] - Phase 2: JWT bearer token from your OIDC provider.
+   *   When set, DashClaw server verifies the token via JWKS and returns `verification_status`
+   *   in every guard response. The JWT `sub` claim overrides agentId in the audit record
+   *   when verification succeeds — cryptographic proof beats self-assertion.
    */
-  constructor({ baseUrl, apiKey, agentId, agentName }) {
+  constructor({ baseUrl, apiKey, agentId, agentName, authToken }) {
     if (!baseUrl) throw new Error('baseUrl is required');
     if (!apiKey) throw new Error('apiKey is required');
     if (!agentId) throw new Error('agentId is required');
@@ -38,6 +46,7 @@ class DashClaw {
     this.apiKey = apiKey;
     this.agentId = agentId;
     this.agentName = agentName || null;
+    this.authToken = authToken || null;
 
     this.execution = {
       capabilities: {
@@ -57,13 +66,22 @@ class DashClaw {
   async _request(path, method = 'GET', body = null, params = null) {
     let url = `${this.baseUrl}${path}`;
     if (params) {
-      const qs = new URLSearchParams(params).toString();
-      if (qs) url += `?${qs}`;
+      // Skip undefined/null values. Passing them straight into URLSearchParams
+      // serializes the literal strings "undefined"/"null", which the receiving
+      // routes treat as real filter values and match zero rows. Falsy-but-valid
+      // values (0, false, '') are preserved. Mirrors the v1 SDK behavior.
+      const qs = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) qs.append(key, String(value));
+      }
+      const s = qs.toString();
+      if (s) url += `?${s}`;
     }
 
     const headers = {
       'Content-Type': 'application/json',
-      'x-api-key': this.apiKey
+      'x-api-key': this.apiKey,
+      ...(this.authToken ? { 'Authorization': `Bearer ${this.authToken}` } : {}),
     };
 
     const res = await fetch(url, {
@@ -72,7 +90,16 @@ class DashClaw {
       body: body ? JSON.stringify(body) : undefined
     });
 
-    const data = await res.json();
+    // Parse the body defensively. A non-JSON error body (a Vercel 502/504/413
+    // gateway page, a 429 rate-limit page) makes res.json() reject with a
+    // SyntaxError, which would propagate instead of the status-bearing error
+    // below and lose res.status. Fall back to {} so the real status is thrown.
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      data = {};
+    }
 
     if (!res.ok) {
       if (res.status === 403 && data.decision && data.decision.decision === 'block') {
@@ -94,7 +121,23 @@ class DashClaw {
   /**
    * POST /api/guard — "Can I do X?"
    * @param {Object} context
-   * @returns {Promise<{decision: 'allow'|'block'|'require_approval', action_id: string, reason: string, signals: string[]}>}
+   * @returns {Promise<{
+   *   decision: 'allow'|'block'|'require_approval'|'warn',
+   *   action_id: string,
+   *   reason: string,
+   *   signals: string[],
+   *   verification_status: 'verified'|'unverified'|'expired'|'failed'|'unknown_issuer',
+   *   agent_id: string|null,
+   *   agent_name: string|null,
+   * }>}
+   *
+   * `verification_status` reflects whether the JWT bearer token (if provided
+   * via the `authToken` constructor option) was cryptographically verified:
+   *   verified       — signature valid; audit entry anchored to JWT sub
+   *   unverified     — no token, or issuer temporarily unreachable (fail-soft)
+   *   expired        — token expired; consider refreshing before next call
+   *   failed         — bad signature, malformed token, or audience mismatch
+   *   unknown_issuer — issuer not in DASHCLAW_ALLOWED_ISSUER (server config)
    */
   async guard(context) {
     return this._request('/api/guard', 'POST', {
@@ -267,7 +310,12 @@ class DashClaw {
     let printedBlock = false;
 
     while (Date.now() - startTime < timeout) {
-      const { action } = await this._request(`/api/actions/${actionId}`, 'GET');
+      // Return the full GET response (action + open_loops + assumptions +
+      // message_summary) so the polling fallback resolves to the same shape as
+      // the SSE fast-path above and the Python SDK. Returning only { action }
+      // dropped the related collections whenever SSE was unavailable.
+      const result = await this._request(`/api/actions/${actionId}`, 'GET');
+      const action = result.action;
 
       if (!printedBlock) {
         printedBlock = true;
@@ -297,14 +345,14 @@ class DashClaw {
       }
 
       if (action.status === 'pending_approval') wasPending = true;
-      if (action.approved_by) return { action };
+      if (action.approved_by) return result;
       if (action.status === 'failed' || action.status === 'cancelled') {
         throw new ApprovalDeniedError(action.error_message || 'Operator denied the action.', action.status);
       }
       if (wasPending && action.status !== 'pending_approval') {
         throw new Error(`Action ${actionId} left pending_approval state without explicit approval metadata (Status: ${action.status})`);
       }
-      if (!wasPending && action.status === 'running') return { action };
+      if (!wasPending && action.status === 'running') return result;
 
       await new Promise(r => setTimeout(r, interval));
     }
@@ -589,6 +637,68 @@ class DashClaw {
     });
   }
 
+  /**
+   * GET /api/messages — Fetch messages this agent has sent.
+   */
+  async getSentMessages({ type, threadId, limit } = {}) {
+    return this._request('/api/messages', 'GET', null, {
+      agent_id: this.agentId,
+      direction: 'sent',
+      ...(type && { type }),
+      ...(threadId && { thread_id: threadId }),
+      ...(limit && { limit }),
+    });
+  }
+
+  /**
+   * GET /api/messages — Fetch this agent's messages with flexible filters.
+   */
+  async getMessages({ direction, type, unread, threadId, limit } = {}) {
+    return this._request('/api/messages', 'GET', null, {
+      agent_id: this.agentId,
+      ...(direction && { direction }),
+      ...(type && { type }),
+      ...(unread != null && { unread }),
+      ...(threadId && { thread_id: threadId }),
+      ...(limit && { limit }),
+    });
+  }
+
+  /**
+   * GET /api/messages/:messageId — Fetch a single message by id.
+   */
+  async getMessage(messageId) {
+    return this._request(`/api/messages/${encodeURIComponent(messageId)}`, 'GET');
+  }
+
+  /**
+   * PATCH /api/messages — Mark messages as read for this agent. Direct messages
+   * are marked read only for the target agent (or dashboard); broadcasts update
+   * read_by for this agent.
+   * @param {string[]} messageIds - Message IDs (msg_*) to mark read.
+   * @returns {Promise<{ updated: number }>}
+   */
+  async markRead(messageIds) {
+    return this._request('/api/messages', 'PATCH', {
+      message_ids: messageIds,
+      action: 'read',
+      agent_id: this.agentId,
+    });
+  }
+
+  /**
+   * PATCH /api/messages — Archive messages for this agent.
+   * @param {string[]} messageIds - Message IDs (msg_*) to archive.
+   * @returns {Promise<{ updated: number }>}
+   */
+  async archiveMessages(messageIds) {
+    return this._request('/api/messages', 'PATCH', {
+      message_ids: messageIds,
+      action: 'archive',
+      agent_id: this.agentId,
+    });
+  }
+
   // ---------------------------------------------------------------------------
   // Session Handoffs
   // ---------------------------------------------------------------------------

package/package.json

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