dashclaw 4.1.2 → 4.2.0

package/README.md

@@ -1112,6 +1112,18 @@ if (action.status === 'pending_approval') {
 // 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
@@ -1123,8 +1135,9 @@ await claw.recordPurchaseResult(action.id, x402Result);
 - `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`.
+> **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.
 

package/dashclaw.js

@@ -1480,6 +1480,60 @@ class DashClaw {
       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.2",
+  "version": "4.2.0",
   "description": "Minimal governance runtime for AI agents. Intercept, govern, and verify agent actions.",
   "type": "module",
   "publishConfig": {