dashclaw 2.13.0 → 2.13.1

package/README.md

@@ -1,4 +1,4 @@
-# DashClaw SDK (v2.12.0)
+# DashClaw SDK
 
 **Minimal governance runtime for AI agents.**
 
@@ -141,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
@@ -251,7 +253,7 @@ See:
 
 ---
 
-## SDK Surface Area (v2.12.0)
+## SDK Surface Area
 
 The v2 SDK exposes the stable governance runtime plus promoted execution domains in the canonical Node client:
 
@@ -336,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
@@ -604,7 +611,7 @@ If your agent supports Model Context Protocol (Claude Code, Claude Desktop, Mana
 - **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.
 
-**4 resources:** `dashclaw://policies`, `dashclaw://capabilities`, `dashclaw://agent/{agent_id}/history`, `dashclaw://status`.
+**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)
 

package/dashclaw.js

@@ -1,6 +1,10 @@
 /**
- * DashClaw SDK v2.12.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';
@@ -62,8 +66,16 @@ 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 = {
@@ -78,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') {
@@ -289,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;
@@ -319,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));
     }
@@ -611,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.13.0",
+  "version": "2.13.1",
   "description": "Minimal governance runtime for AI agents. Intercept, govern, and verify agent actions.",
   "type": "module",
   "publishConfig": {