dashclaw 2.12.0 → 2.13.0

package/README.md

@@ -1,4 +1,4 @@
-# DashClaw SDK (v2.11.1)
+# DashClaw SDK (v2.12.0)
 
 **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
@@ -247,12 +251,12 @@ See:
 
 ---
 
-## SDK Surface Area (v2.11.1)
+## SDK Surface Area (v2.12.0)
 
 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")
@@ -590,10 +594,30 @@ 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.
 
 **4 resources:** `dashclaw://policies`, `dashclaw://capabilities`, `dashclaw://agent/{agent_id}/history`, `dashclaw://status`.
 
+### 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 |
+
+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`)
 
 For teams using the OpenClaw agent framework, the governance plugin intercepts `PreToolUse` / `PostToolUse` lifecycle hooks and runs guard → record → wait-for-approval automatically. Tool classification vocabulary aligns with DashClaw's guard action types. Install via the openclaw CLI which picks up the bundled `HOOK.md` pack.

package/dashclaw.js

@@ -1,5 +1,5 @@
 /**
- * DashClaw SDK v2.11.0 (Stable Runtime API)
+ * DashClaw SDK v2.12.0 (Stable Runtime API)
  * Focused governance runtime client for AI agents.
  */
 
@@ -28,8 +28,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 +42,7 @@ class DashClaw {
     this.apiKey = apiKey;
     this.agentId = agentId;
     this.agentName = agentName || null;
+    this.authToken = authToken || null;
 
     this.execution = {
       capabilities: {
@@ -63,7 +68,8 @@ class DashClaw {
 
     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, {
@@ -94,7 +100,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', {

package/package.json

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