xytara 3.1.7 → 3.1.9

package/RELEASE_NOTES.md

@@ -1,11 +1,9 @@
-`xytara` 3.1.7 completes the Coinbase CDP facilitator path, proven with a real Base mainnet settlement.
-
-A facilitator can signal a verification or settlement result either with a 200 and the result in the body, or with a non-2xx status and the same body. Coinbase CDP returns HTTP 400 for an invalid payment (with `{isValid:false, invalidReason, invalidMessage}`). The client previously treated any non-2xx as an unreachable transport error and never read the body, so a CDP verdict was misclassified. This release reads the result from the body regardless of HTTP status, which was the last blocker for Base mainnet settlement through CDP.
+`xytara` 3.1.9 adds the open execution-provider network: the runtime can now route paid agent calls to independently-registered providers, split the settlement, and reconcile payouts.
 
 Highlights:
 
-- the facilitator client treats any `/verify` or `/settle` response that carries an `isValid` or `success` flag as the facilitator's result, regardless of HTTP status; only a missing or unparseable body is a transport failure
-- failure details now surface the facilitator's `invalidReason` / `invalidMessage` / `errorReason` and a truncated response-body excerpt, so operators can see exactly why a facilitator rejected a payment
-- adds regression checks for facilitators that return a non-2xx status with a result body
-- no change for facilitators that return 200 with the result; the default Base Sepolia path is unaffected
-- verified end to end: a real Base mainnet USDC payment settled on-chain through the CDP facilitator and minted self-serve credits
+- **Open provider network** — self-registration (`POST /v1/provider-network/register`, operator-activated or permissionless + rate-limited), capability matching, public discovery, and a machine-readable integration contract (`GET /v1/provider-network/contract`).
+- **Routing resilience** — per-provider health with cooldown/half-open, in-request failover on provably-not-processed failures only (no double-execution), and reputation-weighted ordering (smoothed success rate).
+- **Economics** — floored revenue-share split (platform keeps the remainder), a reconciled, non-custodial payout ledger (create → on-chain send → confirm), and optional payout auto-execution via an external signer (the runtime stays key-less).
+- **Agent identity** — spend-auth proofs can bind to the exact account/amount/task (request binding), with an optional strict mode.
+- Back-compatible: an empty registry is a byte-for-byte no-op, and env-pinned execution targets still resolve first.

package/examples/generated.carried-handoff.json

@@ -6,9 +6,9 @@
     "source_ref": "spine.job.commitment",
     "committed_ref": "transaction.job.commitment",
     "precommit_pack_ref": "precommit.job.commitment.readiness",
-    "transaction_id": "txn_2b8e48010d89",
-    "receipt_id": "rcpt_5b59fa10c38d",
-    "proof_ref": "proof_rcpt_5b59fa10c38d",
+    "transaction_id": "txn_9ee101eb66d3",
+    "receipt_id": "rcpt_b89c5a8c80f0",
+    "proof_ref": "proof_rcpt_b89c5a8c80f0",
     "payment_protocol": "x402",
     "settlement_mode": "evm_payment",
     "treasury_destination_id": "treasury_acct_demo",

package/lib/a2a_rpc.js

@@ -0,0 +1,280 @@
+"use strict";
+
+// A2A JSON-RPC endpoint with the x402 payment extension (in-band).
+//
+// Spec shape (A2A + x402 extension): payment travels inside the A2A message
+// metadata, not an HTTP header. An unpaid `message/send` returns a Task in
+// state `input-required` whose status message metadata carries
+// `x402.payment.status: "payment-required"` and `x402.payment.required` (the
+// advertised x402 accepts). The caller re-sends `message/send` with the signed
+// x402 authorization in `x402.payment.payload`; we verify + settle it through
+// the same proven facilitator path used by the HTTP x402 routes, run the
+// requested task, and return a `completed` Task carrying the settlement in
+// `x402.payment.receipts` (plus a PAYMENT-RESPONSE header for header-aware
+// clients).
+//
+// This module is dependency-injected so it can be unit-tested without a live
+// facilitator or network: see verify.js.
+
+const crypto = require("crypto");
+
+// x402 A2A extension URI (declared in the agent card capabilities.extensions).
+const X402_EXTENSION_URI = "https://github.com/google-a2a/a2a-x402/tree/main/spec/v0.1";
+
+// Metadata keys defined by the x402 A2A extension.
+const META_STATUS = "x402.payment.status";
+const META_REQUIRED = "x402.payment.required";
+const META_PAYLOAD = "x402.payment.payload";
+const META_RECEIPTS = "x402.payment.receipts";
+const META_ERROR = "x402.payment.error";
+
+function uuid() {
+  return crypto.randomUUID();
+}
+
+function jsonrpcResult(id, result) {
+  return { jsonrpc: "2.0", id: typeof id === "undefined" ? null : id, result };
+}
+
+function jsonrpcError(id, code, message, data) {
+  return {
+    jsonrpc: "2.0",
+    id: typeof id === "undefined" ? null : id,
+    error: { code, message, ...(typeof data === "undefined" ? {} : { data }) }
+  };
+}
+
+function agentMessage(text, metadata) {
+  return {
+    role: "agent",
+    kind: "message",
+    messageId: uuid(),
+    parts: [{ kind: "text", text }],
+    ...(metadata ? { metadata } : {})
+  };
+}
+
+function paymentRequiredTask({ taskId, contextId, accepts, skillTaskRef }) {
+  return {
+    id: taskId,
+    contextId,
+    kind: "task",
+    status: {
+      state: "input-required",
+      message: agentMessage(
+        `Payment required to run "${skillTaskRef}". Re-send message/send with the signed x402 authorization in metadata["${META_PAYLOAD}"].`,
+        {
+          [META_STATUS]: "payment-required",
+          [META_REQUIRED]: { x402Version: 2, scheme: "exact", accepts }
+        }
+      ),
+      timestamp: new Date().toISOString()
+    },
+    artifacts: [],
+    history: []
+  };
+}
+
+function failedTask({ taskId, contextId, paymentStatus, error }) {
+  return {
+    id: taskId,
+    contextId,
+    kind: "task",
+    status: {
+      state: "failed",
+      message: agentMessage(`Payment ${paymentStatus}: ${error || "error"}`, {
+        [META_STATUS]: paymentStatus,
+        [META_ERROR]: error || null
+      }),
+      timestamp: new Date().toISOString()
+    },
+    artifacts: [],
+    history: []
+  };
+}
+
+function completedTask({ taskId, contextId, resultPayload, settlement }) {
+  return {
+    id: taskId,
+    contextId,
+    kind: "task",
+    status: {
+      state: "completed",
+      message: agentMessage("Completed and settled.", {
+        [META_STATUS]: "payment-completed",
+        [META_RECEIPTS]: [settlement]
+      }),
+      timestamp: new Date().toISOString()
+    },
+    artifacts: [
+      {
+        artifactId: uuid(),
+        name: "result",
+        parts: [{ kind: "data", data: resultPayload }]
+      }
+    ],
+    history: []
+  };
+}
+
+// Pull the task reference + body an agent wants to run out of the A2A message.
+// Accepts an explicit `task_ref`/`skill_id`/`skill` in message.metadata, plus a
+// params/body object (metadata.params | metadata.body | a DataPart's data).
+function resolveSkill(message) {
+  const meta = (message && message.metadata) || {};
+  const skillTaskRef = String(meta.task_ref || meta.skill_id || meta.skill || "a2a.negotiate");
+  let body = meta.params || meta.body || null;
+  if (!body && message && Array.isArray(message.parts)) {
+    const dataPart = message.parts.find((p) => p && p.kind === "data" && p.data && typeof p.data === "object");
+    if (dataPart) body = dataPart.data;
+  }
+  return { skillTaskRef, body: body && typeof body === "object" ? body : {} };
+}
+
+// Handle a single `message/send` call. Returns { http, headers, body }.
+// `ctx` = { config, resourceUrl, deps } where deps has the injected runtime
+// functions (facilitator factory, verify/settle, receipt encoder, authorized
+// executor, task-payload builder, and `state`).
+async function handleMessageSend(rpc, ctx) {
+  const id = rpc.id;
+  const params = rpc.params || {};
+  const message = params.message || {};
+  const meta = message.metadata || {};
+
+  const config = ctx.config || {};
+  const x402 = config.x402 || {};
+  const accepts = Array.isArray(x402.accepts) ? x402.accepts : [];
+
+  if (config.verification_mode !== "x402_facilitator") {
+    return { http: 200, body: jsonrpcError(id, -32010, "x402 settlement is not enabled on this runtime") };
+  }
+  if (!accepts.length) {
+    return { http: 200, body: jsonrpcError(id, -32011, "x402 accepts are not configured") };
+  }
+
+  const taskId = uuid();
+  const contextId = message.contextId || message.taskId || uuid();
+  const { skillTaskRef, body } = resolveSkill(message);
+
+  const payload = meta[META_PAYLOAD];
+  if (!payload) {
+    // In-band 402: Task(input-required) carrying the x402 requirements.
+    return {
+      http: 200,
+      body: jsonrpcResult(id, paymentRequiredTask({ taskId, contextId, accepts, skillTaskRef }))
+    };
+  }
+
+  // Payment present: verify + settle via the same facilitator path as the HTTP routes.
+  const facilitator = ctx.deps.createFacilitator({
+    url: x402.facilitator_url,
+    headers: x402.facilitator_headers,
+    timeoutMs: x402.facilitator_timeout_ms,
+    cdp: x402.cdp
+  });
+  const paymentHeader =
+    typeof payload === "string" ? payload : Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+
+  const auth = await ctx.deps.verifyX402Payment({
+    paymentHeader,
+    accepts,
+    resourceUrl: ctx.resourceUrl || null,
+    facilitator
+  });
+  if (!auth.ok) {
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "payment-rejected", error: auth.detail || auth.reason }))
+    };
+  }
+
+  const settled = await ctx.deps.settleX402Payment({ authorization: auth.authorization, facilitator, settle: x402.settle });
+  if (!settled.ok) {
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "payment-failed", error: settled.detail || settled.reason }))
+    };
+  }
+
+  const requirements = (auth.authorization && auth.authorization.paymentRequirements) || {};
+  const requestPayload = {
+    ...ctx.deps.buildNamedTaskPayload(skillTaskRef, body, skillTaskRef),
+    payment_protocol: "x402"
+  };
+  const authorizationContext = {
+    verification_mode: "x402_facilitator",
+    wallet_id: (auth.authorization && auth.authorization.payer) || "x402_payer",
+    payment_payload: {
+      x402_payer: (auth.authorization && auth.authorization.payer) || null,
+      x402_network: requirements.network || null,
+      x402_asset: requirements.asset || null,
+      x402_amount: requirements.amount || null
+    }
+  };
+
+  const exec = await ctx.deps.executeAuthorized(ctx.deps.state, requestPayload, authorizationContext);
+  const receipt = ctx.deps.encodeReceipt(settled.settlement);
+  const execOk = Boolean(exec) && exec.status === 200 && (!exec.payload || exec.payload.ok !== false);
+  if (!execOk) {
+    // The payment settled (money moved) but the skill did not execute. Report
+    // that honestly as a failed task while still carrying the settlement receipt,
+    // so the paying agent knows it paid and can pursue a refund/retry.
+    const failed = {
+      id: taskId,
+      contextId,
+      kind: "task",
+      status: {
+        state: "failed",
+        message: agentMessage("Payment settled, but the requested skill failed to execute.", {
+          [META_STATUS]: "payment-completed",
+          [META_RECEIPTS]: [settled.settlement],
+          execution_error: (exec && exec.payload) || "execution_failed",
+          execution_status: exec && exec.status
+        }),
+        timestamp: new Date().toISOString()
+      },
+      artifacts: [],
+      history: []
+    };
+    return {
+      http: 200,
+      headers: { "PAYMENT-RESPONSE": receipt, "Cache-Control": "no-store" },
+      body: jsonrpcResult(id, failed)
+    };
+  }
+  const task = completedTask({ taskId, contextId, resultPayload: exec.payload, settlement: settled.settlement });
+  return {
+    http: 200,
+    headers: { "PAYMENT-RESPONSE": receipt, "Cache-Control": "no-store" },
+    body: jsonrpcResult(id, task)
+  };
+}
+
+// Top-level JSON-RPC dispatcher for POST /v1/a2a.
+async function handleA2ARpc(rpc, ctx) {
+  if (!rpc || typeof rpc !== "object" || Array.isArray(rpc)) {
+    return { http: 200, body: jsonrpcError(null, -32600, "Invalid Request: expected a single JSON-RPC 2.0 object") };
+  }
+  if (rpc.jsonrpc !== "2.0") {
+    return { http: 200, body: jsonrpcError(rpc.id, -32600, "Invalid Request: jsonrpc must be \"2.0\"") };
+  }
+  if (rpc.method === "message/send") {
+    return handleMessageSend(rpc, ctx);
+  }
+  if (rpc.method === "message/stream") {
+    return { http: 200, body: jsonrpcError(rpc.id, -32004, "Streaming is not supported by this agent (capabilities.streaming=false)") };
+  }
+  return { http: 200, body: jsonrpcError(rpc.id, -32601, `Method not found: ${rpc.method}`) };
+}
+
+module.exports = {
+  handleA2ARpc,
+  handleMessageSend,
+  resolveSkill,
+  X402_EXTENSION_URI,
+  META_STATUS,
+  META_REQUIRED,
+  META_PAYLOAD,
+  META_RECEIPTS,
+  META_ERROR
+};