dashclaw 4.1.1 → 4.2.0

package/README.md

@@ -1075,6 +1075,74 @@ 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);
+
+// Or self-report a SETTLED payment in ONE call — when you pay OUTSIDE a
+// governance hook (e.g. a native-shell agentcash wrapper) and just need the
+// spend on Spend → x402. The server resolves/auto-registers the provider from
+// `provider`, so you don't register one first.
+const settled = await claw.recordX402Purchase({
+  agent_id: 'research-agent',
+  provider: 'stableenrich.dev',   // name/origin
+  spend: 0.007,                   // settled USD
+  transaction_hash: '0xabc…',
+  request_id: 'req_123',
+});
+```
+
+- `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`)
+- `claw.recordX402Purchase({ agent_id, provider, spend, transaction_hash?, request_id?, ... })` -- one call: govern + record the purchase, mark it succeeded, and attach the receipt. Use for the **pay-outside-a-hook** self-report pattern. Python parity: `record_x402_purchase(...)`.
+
+> **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`. (`recordX402Purchase` / `record_x402_purchase` exist in both SDKs and handle the receipt internally.)
+
+> **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

@@ -1420,6 +1420,120 @@ 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,
+    });
+  }
+  /**
+   * Convenience: record a SETTLED x402 payment end-to-end in one call — govern +
+   * record the purchase, mark it succeeded, and (when given) attach the on-chain
+   * receipt. Use this when your agent pays OUTSIDE an OpenClaw governance hook
+   * (e.g. a Codex/native-shell agentcash wrapper) and must self-report so the
+   * spend lands on Spend → x402. The server resolves/auto-registers the provider
+   * from `provider`, so you do NOT register one first. Only call this for a
+   * settled payment — a free quote or a failed call has nothing to record.
+   *
+   * @param {Object} p
+   * @param {string} p.agent_id
+   * @param {string} p.provider - provider name/origin, e.g. "stableenrich.dev"
+   * @param {number} p.spend - settled USD amount (> 0)
+   * @param {string} [p.declared_goal]
+   * @param {string} [p.purchase_reason]
+   * @param {string} [p.context_gap]
+   * @param {string} [p.expected_value]
+   * @param {string} [p.transaction_hash] - on-chain tx hash (receipt evidence)
+   * @param {string} [p.request_id]
+   * @param {string} [p.currency='USDC']
+   * @param {string} [p.payment_method='x402']
+   * @returns {Promise<{ action, purchase, decision, outcome }>}
+   */
+  async recordX402Purchase({
+    agent_id, provider, spend,
+    declared_goal, purchase_reason, context_gap, expected_value,
+    transaction_hash, request_id, currency = 'USDC', payment_method = 'x402',
+  } = {}) {
+    const origin = provider;
+    const res = await this.recordPurchase({
+      agent_id,
+      provider: origin,
+      declared_goal: declared_goal || `x402 capability call to ${origin}`,
+      purchase_reason: purchase_reason || `Paid x402 capability call to ${origin}`,
+      context_gap: context_gap || `Capability gated behind payment at ${origin}`,
+      expected_value: expected_value || `Paid result from ${origin}`,
+      spend_amount: spend,
+      cost_estimate: spend,
+      currency,
+      payment_method,
+    });
+    const actionId = res?.action?.action_id ?? res?.action?.id;
+    let outcome = null;
+    if (actionId) {
+      outcome = await this.reportActionSuccess(actionId, `x402 settled: $${spend} ${currency} at ${origin}`);
+      if (transaction_hash || request_id) {
+        await this.recordPurchaseResult(actionId, {
+          summary: `x402 settled: $${spend} ${currency} at ${origin}`,
+          data: { origin, transactionHash: transaction_hash, requestId: request_id },
+        });
+      }
+    }
+    return { action: res?.action, purchase: res?.purchase, decision: res?.decision, outcome };
+  }
 }
 
 export { DashClaw, ApprovalDeniedError, GuardBlockedError };

package/package.json

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