dashclaw 4.1.0 → 4.1.2

package/README.md

@@ -56,6 +56,7 @@ const { action, action_id } = await claw.createAction({
   action_type: 'deploy',
   declared_goal: 'Ship v2.4.0 to production',
   risk_score: 90,
+  // session_id: 'sess_…'  // optional: link to a started session for exact attribution (else server correlates by agent + time window)
 });
 
 // 3. If the server flagged this for human review, wait for an operator.
@@ -1074,6 +1075,61 @@ x402 and auth metadata are recorded on the provider (`auth_metadata`); no paymen
 
 ---
 
+## x402 Spend Governance
+
+Register x402 providers, govern individual purchases through the guard loop, and record spend for audit. The agent executes the actual x402 call itself — DashClaw records the provider, governs the purchase intent, and keeps a tamper-evident ledger of agent spend. DashClaw never holds a wallet.
+
+```js
+// Register a paid provider
+const { provider } = await claw.createProvider({
+  name: 'Exa Search',
+  category: 'research',
+  base_url: 'https://api.exa.ai',
+});
+
+// Add an endpoint to the provider
+await claw.createProviderEndpoint(provider.provider_id, {
+  name: 'Search',
+  endpoint_url: 'https://api.exa.ai/search',
+  default_price: 0.01,
+  sensitivity_level: 'low',
+});
+
+// Govern + record a purchase (call guard, then agent executes x402)
+const { action, purchase, decision } = await claw.recordPurchase({
+  agent_id: 'research-agent',
+  provider: provider.provider_id,
+  declared_goal: 'Find recent papers on quantum computing',
+  purchase_reason: 'Context gap: no local data for period 2025-01-01..2026-01-01',
+  context_gap: 'No papers in knowledge base for the requested window',
+  expected_value: 'Retrieve 10+ relevant citations',
+});
+
+if (action.status === 'pending_approval') {
+  await claw.waitForApproval(action.id);
+}
+
+// Agent executes the x402 call, then records the result
+const x402Result = { summary: 'Found 14 papers', data: { count: 14 }, url: 'https://...' };
+await claw.recordPurchaseResult(action.id, x402Result);
+```
+
+- `claw.listProviders(filters?)` -- GET /api/x402/providers
+- `claw.createProvider(data)` -- POST /api/x402/providers
+- `claw.getProvider(id)` -- GET /api/x402/providers/:id
+- `claw.updateProvider(id, patch)` -- PATCH /api/x402/providers/:id
+- `claw.listProviderEndpoints(id)` -- GET /api/x402/providers/:id/endpoints
+- `claw.createProviderEndpoint(id, data)` -- POST /api/x402/providers/:id/endpoints
+- `claw.recordPurchase(data)` -- POST /api/x402/purchases (guard-gated; returns `{ action, purchase, decision }`)
+- `claw.listPurchases(filters?)` -- GET /api/x402/purchases
+- `claw.recordPurchaseResult(actionId, result)` -- POST /api/artifacts (attaches the x402 result snapshot to the purchase action via `source_action_id`)
+
+> **Note:** `recordPurchaseResult` is Node-only. It is a convenience wrapper over `POST /api/artifacts` — Python callers post directly to that endpoint with `artifact_type: 'x402_purchase_result'` and `source_action_id` set to the `act_` id from `record_purchase`.
+
+> **Operator surface (no SDK wrapper):** The platform also exposes `GET /api/finops/spend?lens=fleet|claude-code` — a read-only operator rollup that aggregates agent LLM cost + x402 purchases (Fleet lens) or Code Sessions cost (Claude-Code lens). It is a presentation layer backed by repository functions (`getFleetSpend` / `getClaudeCodeSpend`), **not** an SDK method, so it does not appear in the method count. Query it directly over HTTP.
+
+---
+
 ## Hosted provisioning (operator surface — not an SDK method)
 
 When `DASHCLAW_HOSTED=true` the deployment exposes `/api/hosted/*` routes for one-click trial provisioning. These are operator-facing routes, not SDK methods — they produce the API key the SDK consumes.

package/dashclaw.js

@@ -164,7 +164,12 @@ class DashClaw {
    * to have a `non_fabrication` guard policy verify the content before the
    * action proceeds. A violation blocks the action or routes it to approval and
    * is recorded with a signed receipt in the decision ledger.
+   *
+   * Optional `session_id`: pass the id from `createSession()` to link this
+   * action to a session via the Direct path (exact attribution). When omitted,
+   * the server falls back to time-window correlation by agent_id.
    * @param {Object} action
+   * @param {string} [action.session_id] Session to attribute this action to.
    */
   async createAction(action) {
     return this._request('/api/actions', 'POST', {
@@ -1415,6 +1420,66 @@ class DashClaw {
   async invokeRegisteredAgent({ registered_agent_id, capability_id, agent_id, payload, declared_goal } = {}) {
     return this._request('/api/agents/invoke', 'POST', { registered_agent_id, capability_id, agent_id, payload, declared_goal });
   }
+
+  // ---------------------------------------------------------------------------
+  // x402 spend governance — provider registry + governed paid acquisition.
+  // The agent executes the actual x402 call itself; these methods register
+  // providers and record/govern the spend. DashClaw never holds a wallet.
+  // ---------------------------------------------------------------------------
+
+  /** GET /api/x402/providers — list registered providers. */
+  async listProviders(filters = {}) {
+    return this._request('/api/x402/providers', 'GET', null, filters);
+  }
+  /** POST /api/x402/providers — register a paid provider. */
+  async createProvider(data = {}) {
+    return this._request('/api/x402/providers', 'POST', data);
+  }
+  /** GET /api/x402/providers/:id — provider detail + endpoints. */
+  async getProvider(id) {
+    return this._request(`/api/x402/providers/${id}`, 'GET');
+  }
+  /** PATCH /api/x402/providers/:id — update a provider. */
+  async updateProvider(id, patch = {}) {
+    return this._request(`/api/x402/providers/${id}`, 'PATCH', patch);
+  }
+  /** GET /api/x402/providers/:id/endpoints — list a provider's endpoints. */
+  async listProviderEndpoints(id) {
+    return this._request(`/api/x402/providers/${id}/endpoints`, 'GET');
+  }
+  /** POST /api/x402/providers/:id/endpoints — add an endpoint. */
+  async createProviderEndpoint(id, data = {}) {
+    return this._request(`/api/x402/providers/${id}/endpoints`, 'POST', data);
+  }
+  /**
+   * POST /api/x402/purchases — govern + record a paid acquisition.
+   * Required: agent_id, provider, declared_goal, purchase_reason, context_gap, expected_value.
+   * Returns { action, purchase, decision }; branch on action.status (running | pending_approval).
+   */
+  async recordPurchase(data = {}) {
+    return this._request('/api/x402/purchases', 'POST', data);
+  }
+  /** GET /api/x402/purchases — list governed purchases. */
+  async listPurchases(filters = {}) {
+    return this._request('/api/x402/purchases', 'GET', null, filters);
+  }
+  /**
+   * POST /api/artifacts — attach the x402 result snapshot to its purchase action.
+   * Reuses the existing artifacts endpoint; links by source_action_id so the
+   * snapshot appears in that action's evidence bundle.
+   * @param {string} actionId - the act_ id returned by recordPurchase
+   * @param {Object} result - { summary?, data?, url? }
+   */
+  async recordPurchaseResult(actionId, result = {}) {
+    return this._request('/api/artifacts', 'POST', {
+      artifact_type: 'x402_purchase_result',
+      name: `x402 result ${actionId}`,
+      description: result.summary || null,
+      content_json: result.data ?? {},
+      content_url: result.url || null,
+      source_action_id: actionId,
+    });
+  }
 }
 
 export { DashClaw, ApprovalDeniedError, GuardBlockedError };

package/package.json

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