xytara 3.1.13 → 3.1.15

package/lib/a2a_rpc.js

@@ -1,280 +1,287 @@
-"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
-};
+"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);
+
+  // Never ask for (or take) payment for a skill nothing can execute.
+  const taskPayloadDraft = ctx.deps.buildNamedTaskPayload(skillTaskRef, body, skillTaskRef);
+  const executability = typeof ctx.deps.assessExecutability === "function" ? ctx.deps.assessExecutability(taskPayloadDraft) : { ok: true };
+  if (!executability.ok) {
+    const refusal = executability.payload || {};
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({
+        taskId,
+        contextId,
+        paymentStatus: "not-required",
+        error: `${refusal.reason || "capability_not_executable"}: ${refusal.detail || "this skill cannot run here"}${Array.isArray(refusal.executable_task_refs) ? ` Executable: ${refusal.executable_task_refs.join(", ")}.` : ""}`
+      }))
+    };
+  }
+
+  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 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
+    }
+  };
+
+  // Verify -> execute -> settle: the payment is only settled once the skill has produced its
+  // result, so a failed skill never charges the paying agent.
+  const exec = await ctx.deps.executeAuthorized(ctx.deps.state, requestPayload, authorizationContext);
+  const execOk = Boolean(exec) && exec.status === 200 && (!exec.payload || exec.payload.ok !== false);
+  if (!execOk) {
+    const reason = (exec && exec.payload && exec.payload.reason) || "execution_failed";
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "not-charged", error: `${reason}: the skill did not run, so the payment was not settled — retry` }))
+    };
+  }
+
+  let settled = await ctx.deps.settleX402Payment({ authorization: auth.authorization, facilitator, settle: x402.settle });
+  if (!settled.ok && settled.reason === "facilitator_unreachable" && typeof ctx.deps.confirmAuthorizationUsed === "function") {
+    // The facilitator may have broadcast before timing out: if the authorization is used on-chain, it settled.
+    const signed = auth.authorization && auth.authorization.paymentPayload && auth.authorization.paymentPayload.payload
+      && auth.authorization.paymentPayload.payload.authorization;
+    const used = signed ? await ctx.deps.confirmAuthorizationUsed({ network: requirements.network, asset: requirements.asset, authorizer: signed.from, nonce: signed.nonce }) : null;
+    if (used === true) {
+      settled = { ok: true, settlement: { success: true, transaction: null, network: requirements.network, payer: signed.from, recovered_from: "authorization_state" } };
+    }
+  }
+  if (!settled.ok) {
+    return {
+      http: 200,
+      body: jsonrpcResult(id, failedTask({ taskId, contextId, paymentStatus: "payment-failed", error: `${settled.detail || settled.reason} (the result was withheld; if this payment later shows as settled on-chain, contact us with the payment nonce)` }))
+    };
+  }
+  const receipt = ctx.deps.encodeReceipt(settled.settlement);
+  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
+};