agentcash 0.14.3 → 0.14.4

package/dist/cjs/run-server.cjs

@@ -125393,6 +125393,13 @@ var PatchedExactSvmScheme = class {
   }
 };
 
+// src/shared/protocols/x402/policies.ts
+init_cjs_shims();
+var MAX_UPTO_DEADLINE_SECONDS = 7 * 24 * 60 * 60;
+var capUptoDeadline = (_x402Version, requirements) => requirements.map(
+  (r) => r.scheme === "upto" && r.maxTimeoutSeconds > MAX_UPTO_DEADLINE_SECONDS ? { ...r, maxTimeoutSeconds: MAX_UPTO_DEADLINE_SECONDS } : r
+);
+
 // ../../internal/networks/src/index.ts
 init_cjs_shims();
 
@@ -137674,6 +137681,7 @@ var safeCreatePaymentPayload = (surface, wallets, paymentRequired, paymentRequir
           client: new PatchedExactSvmScheme(toClientSvmSigner(wallets.svm))
         }
       ],
+      policies: [capUptoDeadline],
       paymentRequirementsSelector
     })
   );
@@ -146285,6 +146293,9 @@ init_cjs_shims();
 
 // src/shared/protocols/x402/choose-payment-requirement.ts
 init_cjs_shims();
+var preferUpto = (requirements) => {
+  return requirements.find((pr) => pr.scheme === "upto") ?? requirements[0];
+};
 var choosePaymentRequirement = async ({
   paymentRequirements,
   options
@@ -146293,7 +146304,7 @@ var choosePaymentRequirement = async ({
   const { paymentNetwork } = options.params;
   if (paymentNetwork) {
     const caip2 = networkToCaip2(paymentNetwork);
-    return paymentRequirements.find((pr) => pr.network === caip2);
+    return preferUpto(paymentRequirements.filter((pr) => pr.network === caip2));
   }
   const requirementsWithBalance = await Promise.all(
     paymentRequirements.map(async (pr) => {
@@ -146333,10 +146344,26 @@ var choosePaymentRequirement = async ({
       }
     })
   );
-  return requirementsWithBalance.sort((a, b) => b.balance - a.balance)[0].requirement;
+  const bestNetwork = requirementsWithBalance.sort(
+    (a, b) => b.balance - a.balance
+  )[0].requirement.network;
+  return preferUpto(
+    paymentRequirements.filter((pr) => pr.network === bestNetwork)
+  );
 };
 
 // src/shared/protocols/x402/handle-payment.ts
+var isPermit2AllowanceFailureBody = (body) => body.includes("permit2") && body.includes("allowance_required");
+var buildPermit2AllowanceErrorMessage = (params) => {
+  const { walletAddress, scheme } = params;
+  return [
+    `Payment failed: this endpoint's \`${scheme}\` scheme settles via the Permit2 contract, but your agentcash wallet (${walletAddress}) has not approved Permit2 to spend USDC.`,
+    "",
+    "The clean fix is server-side. The merchant should adopt the EIP-2612 gas-sponsoring extension \u2014 agentcash will then auto-sign an off-chain permit on each call and the facilitator pays the approval gas, with no setup required from the user. See https://docs.x402.org/extensions/eip2612-gas-sponsoring",
+    "",
+    `Until the merchant adopts that extension, you can do a one-time \`USDC.approve(0x000000000022D473030F116dDEE9F6B43aC78BA3, MAX_UINT256)\` on Base from this wallet (requires a small amount of ETH for gas, ~$0.01\u20130.10). After that, all future Permit2-based payments from this wallet work without further on-chain transactions.`
+  ].join("\n");
+};
 async function handleX402Payment({
   response,
   request: request2,
@@ -146414,27 +146441,50 @@ async function handleX402Payment({
     "Access-Control-Expose-Headers",
     "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
   );
-  return await safeFetch(surface, request2, timeout).andThen((paidResponse) => {
-    const settlementResult = safeGetPaymentSettlement(surface, paidResponse);
-    const settlement = settlementResult.isOk() ? settlementResult.value : null;
-    const maxAmount = tokenStringToNumber(paymentPayload.accepted.amount);
-    const settledAmount = settlement?.amount ? tokenStringToNumber(settlement.amount) : null;
-    const isUpTo = paymentPayload.accepted.scheme === "upto";
-    const price = settledAmount != null ? formatUsd(settledAmount) : isUpTo ? `up to ${formatUsd(maxAmount)}` : formatUsd(maxAmount);
-    return x402Ok({
-      response: paidResponse,
-      paymentInfo: {
-        protocol: "x402" /* X402 */,
-        network: caip2ToNetwork(paymentPayload.accepted.network),
-        price,
-        payment: settlement ? {
-          success: settlement.success,
-          transactionHash: settlement.transaction
-        } : null
-      }
-    });
+  const paidResult = await safeFetch(surface, request2, timeout);
+  if (paidResult.isErr()) {
+    return paidResult;
+  }
+  const paidResponse = paidResult.value;
+  const permit2Error = await detectPermit2AllowanceError(paidResponse, {
+    walletAddress: wallets.evm.address,
+    scheme: paymentPayload.accepted.scheme
+  });
+  if (permit2Error) {
+    return x402Err(surface, permit2Error);
+  }
+  const settlementResult = safeGetPaymentSettlement(surface, paidResponse);
+  const settlement = settlementResult.isOk() ? settlementResult.value : null;
+  const maxAmount = tokenStringToNumber(paymentPayload.accepted.amount);
+  const settledAmount = settlement?.amount ? tokenStringToNumber(settlement.amount) : null;
+  const isUpTo = paymentPayload.accepted.scheme === "upto";
+  const price = settledAmount != null ? formatUsd(settledAmount) : isUpTo ? `up to ${formatUsd(maxAmount)}` : formatUsd(maxAmount);
+  return x402Ok({
+    response: paidResponse,
+    paymentInfo: {
+      protocol: "x402" /* X402 */,
+      network: caip2ToNetwork(paymentPayload.accepted.network),
+      price,
+      payment: settlement ? {
+        success: settlement.success,
+        transactionHash: settlement.transaction
+      } : null
+    }
   });
 }
+async function detectPermit2AllowanceError(response, context2) {
+  if (response.ok) {
+    return null;
+  }
+  const body = await response.clone().text().catch(() => "");
+  if (!isPermit2AllowanceFailureBody(body)) {
+    return null;
+  }
+  return {
+    cause: "permit2_allowance_required",
+    message: buildPermit2AllowanceErrorMessage(context2)
+  };
+}
 
 // src/operations/fetch/payment.ts
 async function executePayment(response, request2, options) {
@@ -146717,7 +146767,7 @@ var ORIGIN_METADATA = {
   },
   ["https://stablesocial.dev" /* StableSocial */]: {
     title: "StableSocial",
-    description: "Social media data for Twitter, Instagram, TikTok, YouTube, Facebook, Reddit"
+    description: "Social media data for TikTok, Instagram, Facebook, Reddit"
   },
   ["https://stablestudio.dev" /* StableStudio */]: {
     title: "StableStudio",
@@ -162358,7 +162408,7 @@ var import_path2 = require("path");
 var import_url2 = require("url");
 function getVersion3() {
   if (true) {
-    return "0.14.3";
+    return "0.14.4";
   }
   const __dirname2 = (0, import_path2.dirname)((0, import_url2.fileURLToPath)(importMetaUrl));
   const pkg2 = JSON.parse(
@@ -169887,7 +169937,7 @@ var import_path3 = require("path");
 var import_url5 = require("url");
 function getVersion4() {
   if (true) {
-    return "0.14.3";
+    return "0.14.4";
   }
   const __dirname2 = (0, import_path3.dirname)((0, import_url5.fileURLToPath)(importMetaUrl));
   const pkg2 = JSON.parse(

package/dist/esm/{add-skill-CDIK57A3.js → add-skill-MO4YPAYM.js}

@@ -1,14 +1,14 @@
 import {
   resolveOrigin
-} from "./chunk-K627XZI4.js";
+} from "./chunk-2SZ6MZS3.js";
 import {
   installSkills
 } from "./chunk-FVVSNDQR.js";
 import {
   addUserOrigin
 } from "./chunk-YIU364NZ.js";
-import "./chunk-CFSSHSBN.js";
-import "./chunk-SFESERJN.js";
+import "./chunk-L4U6AJW3.js";
+import "./chunk-3PYQIEMA.js";
 import "./chunk-KVSTJRSJ.js";
 import "./chunk-FB5CMO3J.js";
 import "./chunk-U6FRXL3X.js";
@@ -97,4 +97,4 @@ var addSkillCommand = async (input) => {
 export {
   addSkillCommand
 };
-//# sourceMappingURL=add-skill-CDIK57A3.js.map
+//# sourceMappingURL=add-skill-MO4YPAYM.js.map

package/dist/esm/{bridge-6WMUV3ML.js → bridge-Q4YWH4WW.js}

@@ -1,10 +1,10 @@
 import {
   bridge,
   bridgeSchema
-} from "./chunk-FV6DADHO.js";
+} from "./chunk-2OKYUR7B.js";
 import {
   DESCRIPTIONS
-} from "./chunk-SFESERJN.js";
+} from "./chunk-3PYQIEMA.js";
 import "./chunk-BFOYXXLG.js";
 import {
   getWalletOrExit
@@ -54,4 +54,4 @@ var bridgeCommand = async (args) => {
 export {
   bridgeCommand
 };
-//# sourceMappingURL=bridge-6WMUV3ML.js.map
+//# sourceMappingURL=bridge-Q4YWH4WW.js.map

package/dist/esm/{check-D5DZ6Y3T.js → check-3GPSLBNI.js}

@@ -3,9 +3,9 @@ import {
 } from "./chunk-5CMVFNXO.js";
 import {
   cliRequestSchema
-} from "./chunk-SCBLFGL2.js";
-import "./chunk-KMS4TVJY.js";
-import "./chunk-SFESERJN.js";
+} from "./chunk-JKK2XT7N.js";
+import "./chunk-7KT6UCTT.js";
+import "./chunk-3PYQIEMA.js";
 import "./chunk-IKPLMFAK.js";
 import {
   RequestMethod
@@ -69,4 +69,4 @@ var checkCommand = async (args) => {
 export {
   checkCommand
 };
-//# sourceMappingURL=check-D5DZ6Y3T.js.map
+//# sourceMappingURL=check-3GPSLBNI.js.map

package/dist/esm/{chunk-FV6DADHO.js → chunk-2OKYUR7B.js}

@@ -1,6 +1,6 @@
 import {
   TOOL_PARAMS
-} from "./chunk-SFESERJN.js";
+} from "./chunk-3PYQIEMA.js";
 import {
   safeFetchJson
 } from "./chunk-BFOYXXLG.js";
@@ -541,4 +541,4 @@ export {
   bridgeSchema,
   bridge
 };
-//# sourceMappingURL=chunk-FV6DADHO.js.map
+//# sourceMappingURL=chunk-2OKYUR7B.js.map

package/dist/esm/{chunk-K627XZI4.js → chunk-2SZ6MZS3.js}

@@ -1,6 +1,6 @@
 import {
   discoverResources
-} from "./chunk-CFSSHSBN.js";
+} from "./chunk-L4U6AJW3.js";
 import {
   errorResponse
 } from "./chunk-7EBJ4BCH.js";
@@ -52,4 +52,4 @@ function resolveDescription(result) {
 export {
   resolveOrigin
 };
-//# sourceMappingURL=chunk-K627XZI4.js.map
+//# sourceMappingURL=chunk-2SZ6MZS3.js.map

package/dist/esm/{chunk-SFESERJN.js → chunk-3PYQIEMA.js}

@@ -6,7 +6,7 @@ var ORIGIN_METADATA = {
   },
   ["https://stablesocial.dev" /* StableSocial */]: {
     title: "StableSocial",
-    description: "Social media data for Twitter, Instagram, TikTok, YouTube, Facebook, Reddit"
+    description: "Social media data for TikTok, Instagram, Facebook, Reddit"
   },
   ["https://stablestudio.dev" /* StableStudio */]: {
     title: "StableStudio",
@@ -248,4 +248,4 @@ export {
   REQUEST_FETCH_PARAMS,
   TOOL_PARAMS
 };
-//# sourceMappingURL=chunk-SFESERJN.js.map
+//# sourceMappingURL=chunk-3PYQIEMA.js.map

package/dist/esm/chunk-3PYQIEMA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/descriptions.ts"],"sourcesContent":["/**\n * Single source of truth for all LLM-facing text in the MCP package.\n *\n * `DESCRIPTIONS` covers every tool with both an `mcp` variant (detailed,\n * AI-audience) and a `cli` variant (concise, human-readable for --help).\n * `serverInstructions` is shared across both surfaces.\n *\n * Additional exports cover parameter/output schema descriptions, origin\n * metadata, and prompt content — all LLM-facing text in one place.\n */\n\nimport type { UserOrigin } from './user-origins';\nimport { Origin } from './origins';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Origin metadata (used for MCP resource registration descriptions)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport const ORIGIN_METADATA: Record<\n  string,\n  { title: string; description: string }\n> = {\n  [Origin.StableEnrich]: {\n    title: 'StableEnrich',\n    description:\n      'People/org search, Google Maps, Exa web search, LinkedIn data, Firecrawl scrape, WhitePages, email enrichment',\n  },\n  [Origin.StableSocial]: {\n    title: 'StableSocial',\n    description: 'Social media data for TikTok, Instagram, Facebook, Reddit',\n  },\n  [Origin.StableStudio]: {\n    title: 'StableStudio',\n    description: 'Generate and edit images and videos',\n  },\n  [Origin.StableUpload]: {\n    title: 'StableUpload',\n    description: 'Pay to upload files, get a permanent download URL.',\n  },\n  [Origin.StableEmail]: {\n    title: 'StableEmail',\n    description: 'Send emails',\n  },\n  [Origin.X402Scan]: {\n    title: 'X402 Scan',\n    description: 'x402 protocol explorer',\n  },\n  [Origin.Shirt]: {\n    title: 'Shirt',\n    description: 'Shirt.sh',\n  },\n  [Origin.X402Puppet]: {\n    title: 'X402 Puppet',\n    description: 'Browser automation',\n  },\n  [Origin.X402Facilitator]: {\n    title: 'X402 Facilitator',\n    description: 'Payment facilitation',\n  },\n  [Origin.StableMerch]: {\n    title: 'StableMerch',\n    description:\n      'Create shirts and mugs with custom images and have them shipped to your address.',\n  },\n};\n\nexport const PRIMARY_ORIGINS = [\n  Origin.StableEnrich,\n  Origin.StableSocial,\n  Origin.StableStudio,\n  Origin.StableUpload,\n  Origin.StableEmail,\n  Origin.StableMerch,\n] as const;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tool descriptions — { mcp, cli } per tool + shared serverInstructions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport const DESCRIPTIONS = {\n  bridge: {\n    toolNames: {\n      cli: 'bridge',\n      mcp: 'bridge',\n    },\n    title: 'Bridge Between Networks',\n    mcp: `Bridge USDC between supported networks using the current wallet. Requires a source network, destination network, and amount. Use this when funds are on one supported network and the user needs them moved to another. Bridging is subject to fees.`,\n    cli: `Bridge USDC between supported networks using the current wallet. Requires --from, --to, and --amount. Bridging is subject to fees.`,\n  },\n\n  getBalance: {\n    mcp: `Get your total USDC balance across all supported networks. Auto-creates the wallet on first use (~/.agentcash/wallet.json). Use this before paid API calls to confirm you have funds available.`,\n    cli: `Get your total USDC balance across all supported networks. Creates the wallet on first use (~/.agentcash/wallet.json). Use this before paid API calls to confirm you have funds available.`,\n  },\n\n  fetch: {\n    mcp: `HTTP fetch with automatic authentication and payment handling. Makes the request, retries with SIGN-IN-WITH-X when the route exposes a SIWX challenge, and only pays if the route still returns 402. Returns response data along with payment details (price, tx hash) if a payment was made.\\n\\nFor endpoints you haven't called before in this session, you MUST call check_endpoint_schema first to confirm the request body schema. Skipping this causes 400 errors from wrong field names.`,\n    cli: `HTTP fetch with automatic authentication and payment handling. If the endpoint returns 402, agentcash attempts authentication first and only falls back to payment if the route still requires it. Run 'check <url>' first to confirm the request body schema; skipping this causes 400 errors from wrong field names.`,\n    epilogue: `Workflow: check <url> → fetch <url> -m POST -b '{\"field\":\"value\"}'\\nAuth mode is advisory only; fetch handles both SIWX and paid routes.`,\n  },\n\n  fetchWithAuth: {\n    mcp: `Deprecated alias for fetch. Uses the same unified flow: probe the route, attempt SIWX when available, and only pay if the route still returns 402.\\n\\nFor new integrations, prefer fetch.`,\n    cli: `Deprecated alias for fetch. Uses the same unified auth-and-payment flow, but new integrations should call 'fetch' directly.`,\n    epilogue: `Deprecated: use agentcash fetch <url>. This alias is kept for compatibility.`,\n  },\n\n  listAccounts: {\n    mcp: `List wallet accounts for each supported network. Returns the network, address, balance, and deposit link for every supported network so you can see where to fund the wallet. Auto-creates the wallet on first use (~/.agentcash/wallet.json). If onboardingCta is present, show its message to the user — it means they haven't onboarded yet and need to either visit the onboard link or deposit directly.`,\n    cli: `List wallet accounts for each supported network, including network, address, balance, and deposit link. Creates the wallet on first use (~/.agentcash/wallet.json). Use this when you need the per-network funding addresses and deposit links.`,\n  },\n\n  getWalletInfo: {\n    mcp: `Legacy combined wallet view. Returns both the total balance and the per-network account list. Prefer calling get_balance for available funds and list_accounts when you need network-specific addresses or deposit links.`,\n    cli: `Legacy combined wallet view. Returns both the total balance and the per-network account list. Prefer 'balance' for available funds and 'accounts' for network-specific addresses or deposit links.`,\n  },\n\n  checkEndpointSchema: {\n    mcp: [\n      `Get the input/output schema and auth mode (paid or SIWX) for a single endpoint.`,\n      `Call this to see exactly what fields the request body expects and what the response contains.`,\n      `Returns the schema from the origin's OpenAPI spec. Optionally pass sample_input_body to probe the endpoint live (without payment) for an exact price quote — do this when pricing is dynamic (range-based or variable), or when you're unsure about the input schema. Treat auth mode as advisory: fetch handles both SIWX and paid routes.`,\n    ].join('\\n\\n'),\n    cli: `Get the input/output schema and auth mode (paid or SIWX) for an endpoint. Returns exact field names from the OpenAPI spec — call this before 'fetch' to avoid 400 errors. Pass --body to probe the endpoint live for an exact price quote when pricing is dynamic or unclear.`,\n    epilogue: `Auth mode is advisory:\\n  paid  → agentcash fetch <url>\\n  SIWX  → agentcash fetch <url>`,\n  },\n\n  discoverApiEndpoints: {\n    mcp: [\n      `List available endpoints at an API origin. Returns endpoint URLs with descriptions of what each does and the auth mode for each (paid or SIWX). Works with any origin, not just the registered ones.`,\n      `Call this when you need to see what routes are available at an origin — whether it's one of the registered origins or any other origin you've identified as useful. Treat the auth mode as guidance for what the route may require; fetch handles both SIWX and payment.`,\n      `The response always indicates whether guidance is available. Guidance is documentation published by the API provider explaining how endpoints work together, edge cases, and usage tips. compact guidance is included automatically; set include_guidance=true to force-include full usage documentation when you need to compose two or more endpoints or need clarification on how the origin works.`,\n    ].join('\\n\\n'),\n    cli: `List available endpoints at an API origin with descriptions and auth modes (paid or SIWX). Works with any origin, not just registered ones. Add --include-guidance for full provider docs when composing multiple endpoints or when usage is unclear. Fetch handles both auth modes.`,\n    epilogue: `Registered origins:\\n${PRIMARY_ORIGINS.flatMap(o => (ORIGIN_METADATA[o] ? [`  ${o} — ${ORIGIN_METADATA[o].description}`] : [])).join('\\n')}`,\n  },\n\n  redeemInvite: {\n    mcp: `Redeem an invite code for free USDC on Base. One-time use per code. Returns amount received and transaction hash. Use get_balance after to verify funds, or list_accounts if you need the per-network deposit links as well.`,\n    cli: `Redeem an invite code for free USDC on Base. One-time use per code. Run 'balance' after to verify the balance landed.`,\n  },\n\n  try: {\n    cli: `Fetch a new origin for its resources and return a prompt guiding the user through the process of calling the first endpoint.`,\n  },\n\n  search: {\n    mcp: `Search for relevant paid API services by describing what you need in natural language. Returns the best matching origins with endpoint details and pricing. The top result includes the full input/output schema so you can call it immediately via fetch.\n\nOnly use this when you DON'T already know which registered origin to use. If the task clearly maps to a registered origin (e.g. people search → StableEnrich, image generation → StableStudio), skip search and go straight to discover_api_endpoints on that origin. Search is for discovering NEW or UNKNOWN capabilities outside the registered origins.\n\nSet broad=true to widen the search to include newer, unvetted tools that may not have established trust. Use this if the default results don't cover what you need.`,\n    cli: `Search for paid API services by natural language query. Returns matching origins with endpoints and pricing. Use --broad to include newer, unvetted tools that may not have established trust.`,\n  },\n\n  reportError: {\n    mcp: `EMERGENCY ONLY. Report critical MCP tool bugs. Do NOT use for normal errors (balance, network, 4xx) — those are recoverable.`,\n    cli: `Report a critical bug to the agentcash team (emergency only). Do NOT use for normal errors like low balance, network timeouts, or 4xx responses — those are recoverable without filing a report.`,\n  },\n\n  updateSettings: {\n    mcp: `Update user settings (persisted to ~/.agentcash/settings.json). Currently supports maxAmount — the maximum USD amount allowed per fetch request. If a fetch response requests more than this, the payment is rejected. Returns the current settings after applying changes.`,\n    cli: `Update user settings (persisted to ~/.agentcash/settings.json). Currently supports maxAmount, which caps how much a single fetch request can spend.`,\n  },\n\n  getSettings: {\n    mcp: `Get current user settings. Returns persisted values from ~/.agentcash/settings.json with defaults applied.`,\n    cli: `Get current user settings from ~/.agentcash/settings.json, with defaults applied.`,\n  },\n} as const;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Dynamic server instructions (includes user-added origins at runtime)\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst WORKFLOW = [\n  `Workflow:`,\n  `1. If you don't already know your balance, call get_balance. You need a balance for paid endpoints. SIWX endpoints don't require one. You don't need to call this every turn, just before your first paid call or whenever you're unsure.`,\n  `2. If the balance is zero, or if the user needs a funding link or wallet addresses, call list_accounts and share the relevant deposit link. If onboardingCta is present, show it to the user.`,\n  `3. If the task doesn't clearly map to any registered origin above, call search() to find relevant APIs. Skip this step when you already know the right origin — go straight to step 4.`,\n  `4. Call discover_api_endpoints() to get the endpoint index — a list of available routes with descriptions and auth modes. The auth mode is advisory and tells you what the route may require.`,\n  `5. Call check_endpoint_schema() to get the exact input/output schema and auth mode for the endpoint you want to call, so you know what fields to pass and what the response contains. Both discover_api_endpoints and check_endpoint_schema return the auth mode.`,\n  `6. Call fetch with the correct input schema. It will attempt SIWX first when available and only pay if the route still returns 402.`,\n].join('\\n');\n\nexport function buildServerInstructions(\n  userOrigins: UserOrigin[] = []\n): string {\n  const allOrigins = [\n    ...userOrigins.map(o => `  - ${o.url} — ${o.description}`),\n    ...PRIMARY_ORIGINS.flatMap(o =>\n      ORIGIN_METADATA[o] ? [`  - ${o} — ${ORIGIN_METADATA[o].description}`] : []\n    ),\n  ].join('\\n');\n\n  return [\n    `AgentCash lets you call protected APIs — handling both x402 micropayments and SIWX authentication seamlessly. It manages a USDC wallet for paid endpoints and signs wallet proofs for identity-gated endpoints through fetch.`,\n    `The user has installed agentcash because they want to use paid and SIWX-protected APIs as their preferred way to accomplish related tasks.`,\n    `Paid endpoints require a wallet balance. SIWX endpoints are free — they only require a wallet identity.`,\n    `If a task could be accomplished by one of these registered origins, run the workflow below. If you're unsure which origin to use, or the task doesn't match a registered origin, call search() to find relevant APIs.\\n${allOrigins}`,\n    `discover_api_endpoints also works with any origin beyond this list. If you identify another origin that would be useful for a task, you can use it.`,\n    WORKFLOW,\n    `If you need to compose multiple endpoints in sequence, or anything about the origin's capabilities is unclear, call discover_api_endpoints with include_guidance=true to retrieve the origin's full usage documentation.`,\n  ].join('\\n\\n');\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Shared request schema parameter descriptions\n// (used by fetch, fetch_with_auth tools)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport const REQUEST_PARAMS = {\n  url: 'The endpoint URL',\n  method: 'HTTP method. Defaults to GET for fetch operations.',\n  body: 'Raw request body string. Passed through to the underlying fetch call as-is.',\n  headers:\n    'Additional headers to include. Each entry must be a string in \"Name: value\" format.',\n  timeout: 'Request timeout in milliseconds',\n} as const;\n\nexport const REQUEST_FETCH_PARAMS = {\n  ...REQUEST_PARAMS,\n  paymentProtocol:\n    'Payment protocol to use when payment is required. If not specified, the payment protocol will be auto-detected.',\n  paymentNetwork:\n    'Chain to use for SIWX and payment when applicable. If not specified, the network will be auto-detected.',\n  maxAmount:\n    'Maximum amount (in USD) to pay per request. Aborts if the endpoint requests more. Defaults to $5. Pass a higher value for known-expensive endpoints.',\n} as const;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Per-tool parameter and output schema descriptions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport const TOOL_PARAMS = {\n  bridge: {\n    from: 'The network to bridge from',\n    to: 'The network to bridge to',\n    amount: 'The amount of USDC to bridge',\n  },\n  fetch: REQUEST_FETCH_PARAMS,\n  fetchWithAuth: REQUEST_FETCH_PARAMS,\n  checkEndpointSchema: {\n    ...REQUEST_PARAMS,\n    method:\n      'HTTP method to check. If omitted, all methods declared in the spec are returned.',\n    body: 'Optional. A sample request body to probe the endpoint live (without payment) for exact pricing. Use when pricing is range-based or quote-based, or when you need to verify the input schema. Omit to get the static schema and advisory pricing from the spec.',\n  },\n  try: {\n    url: 'The origin URL to explore',\n  },\n  add: {\n    url: 'The origin URL to add',\n  },\n\n  listAccounts: {\n    output: {\n      accounts: 'Wallet accounts for each supported network',\n      address: 'Wallet address for this network',\n      balance: 'USDC balance on this network',\n      network: 'Supported payment network name',\n      isNewWallet: 'Whether the wallet is new and needs to be funded',\n      depositLink:\n        'Link to deposit USDC directly into the wallet for this network',\n      onboardingCta:\n        'Present when the user has not yet redeemed an invite code. Show the message to the user — it directs them to onboard or deposit.',\n      onboardingCtaOnboardLink: 'Link to the onboarding page',\n      onboardingCtaDepositLink: 'Link to deposit USDC directly',\n      onboardingCtaMessage: 'Human-readable CTA to show the user',\n    },\n  },\n\n  redeemInvite: {\n    code: 'The invite code',\n    output: {\n      amount: 'Amount with unit (e.g., \"5 USDC\")',\n      txHash: 'Transaction hash on Base',\n    },\n  },\n\n  search: {\n    query:\n      'Natural language description of what you need (e.g. \"send physical mail\", \"generate music\", \"flight prices\")',\n    broad:\n      'Include broader results that may contain newer, unvetted tools. Default is false.',\n    limit: 'Maximum number of results to return (1-50). Default is 10.',\n    page: 'Page number for pagination. Default is 1.',\n  },\n\n  discoverApiEndpoints: {\n    url: 'The origin URL to discover endpoints on (e.g. https://stableenrich.dev)',\n    includeGuidance:\n      \"Request the origin's usage guidance. true=always include, false=never include, omit=auto (included when compact). Guidance explains how to compose multiple endpoints and covers edge cases.\",\n  },\n\n  reportError: {\n    tool: 'MCP tool name',\n    resource: 'Resource URL',\n    summary: '1-2 sentence summary',\n    errorMessage: 'Error message',\n    stack: 'Stack trace',\n    fullReport: 'Detailed report with context, logs, repro steps',\n    output: {\n      reportId: 'Unique report ID for tracking',\n      message: 'Confirmation message',\n    },\n  },\n} as const;\n"],"mappings":"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","names":[]}

package/dist/esm/{chunk-KMS4TVJY.js → chunk-7KT6UCTT.js}

@@ -1,7 +1,7 @@
 import {
   REQUEST_FETCH_PARAMS,
   REQUEST_PARAMS
-} from "./chunk-SFESERJN.js";
+} from "./chunk-3PYQIEMA.js";
 import {
   RequestMethod
 } from "./chunk-LNJIXYCU.js";
@@ -40,4 +40,4 @@ export {
   paymentProtocols,
   fetchShape
 };
-//# sourceMappingURL=chunk-KMS4TVJY.js.map
+//# sourceMappingURL=chunk-7KT6UCTT.js.map

package/dist/esm/{chunk-IL2CNAJY.js → chunk-CUZFVI2X.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-27DZCYDB.js";
 import {
   INSTALL_PACKAGE_SPECIFIER
-} from "./chunk-NP7CKLI4.js";
+} from "./chunk-QOMU3YLK.js";
 import {
   log,
   safeReadFile,
@@ -628,4 +628,4 @@ export {
   tryAddServer,
   addServer
 };
-//# sourceMappingURL=chunk-IL2CNAJY.js.map
+//# sourceMappingURL=chunk-CUZFVI2X.js.map

package/dist/esm/{chunk-SCBLFGL2.js → chunk-JKK2XT7N.js}

@@ -1,10 +1,10 @@
 import {
   coreRequestSchema,
   fetchShape
-} from "./chunk-KMS4TVJY.js";
+} from "./chunk-7KT6UCTT.js";
 import {
   REQUEST_PARAMS
-} from "./chunk-SFESERJN.js";
+} from "./chunk-3PYQIEMA.js";
 
 // src/shared/request/schemas/cli.ts
 import z from "zod";
@@ -46,4 +46,4 @@ export {
   cliRequestSchema,
   cliFetchRequestSchema
 };
-//# sourceMappingURL=chunk-SCBLFGL2.js.map
+//# sourceMappingURL=chunk-JKK2XT7N.js.map

package/dist/esm/{chunk-G5FHPXQL.js → chunk-JVMJVMWB.js}

@@ -197,6 +197,12 @@ var PatchedExactSvmScheme = class {
   }
 };
 
+// src/shared/protocols/x402/policies.ts
+var MAX_UPTO_DEADLINE_SECONDS = 7 * 24 * 60 * 60;
+var capUptoDeadline = (_x402Version, requirements) => requirements.map(
+  (r) => r.scheme === "upto" && r.maxTimeoutSeconds > MAX_UPTO_DEADLINE_SECONDS ? { ...r, maxTimeoutSeconds: MAX_UPTO_DEADLINE_SECONDS } : r
+);
+
 // src/shared/protocols/x402/index.ts
 import { createSIWxPayload } from "@x402/extensions/sign-in-with-x";
 import { createPublicClient, http } from "viem";
@@ -273,6 +279,7 @@ var safeCreatePaymentPayload = (surface, wallets, paymentRequired, paymentRequir
           client: new PatchedExactSvmScheme(toClientSvmSigner(wallets.svm))
         }
       ],
+      policies: [capUptoDeadline],
       paymentRequirementsSelector
     })
   );
@@ -593,6 +600,9 @@ async function pickByBalance(response, options) {
 }
 
 // src/shared/protocols/x402/choose-payment-requirement.ts
+var preferUpto = (requirements) => {
+  return requirements.find((pr) => pr.scheme === "upto") ?? requirements[0];
+};
 var choosePaymentRequirement = async ({
   paymentRequirements,
   options
@@ -601,7 +611,7 @@ var choosePaymentRequirement = async ({
   const { paymentNetwork } = options.params;
   if (paymentNetwork) {
     const caip2 = networkToCaip2(paymentNetwork);
-    return paymentRequirements.find((pr) => pr.network === caip2);
+    return preferUpto(paymentRequirements.filter((pr) => pr.network === caip2));
   }
   const requirementsWithBalance = await Promise.all(
     paymentRequirements.map(async (pr) => {
@@ -641,10 +651,26 @@ var choosePaymentRequirement = async ({
       }
     })
   );
-  return requirementsWithBalance.sort((a, b) => b.balance - a.balance)[0].requirement;
+  const bestNetwork = requirementsWithBalance.sort(
+    (a, b) => b.balance - a.balance
+  )[0].requirement.network;
+  return preferUpto(
+    paymentRequirements.filter((pr) => pr.network === bestNetwork)
+  );
 };
 
 // src/shared/protocols/x402/handle-payment.ts
+var isPermit2AllowanceFailureBody = (body) => body.includes("permit2") && body.includes("allowance_required");
+var buildPermit2AllowanceErrorMessage = (params) => {
+  const { walletAddress, scheme } = params;
+  return [
+    `Payment failed: this endpoint's \`${scheme}\` scheme settles via the Permit2 contract, but your agentcash wallet (${walletAddress}) has not approved Permit2 to spend USDC.`,
+    "",
+    "The clean fix is server-side. The merchant should adopt the EIP-2612 gas-sponsoring extension \u2014 agentcash will then auto-sign an off-chain permit on each call and the facilitator pays the approval gas, with no setup required from the user. See https://docs.x402.org/extensions/eip2612-gas-sponsoring",
+    "",
+    `Until the merchant adopts that extension, you can do a one-time \`USDC.approve(0x000000000022D473030F116dDEE9F6B43aC78BA3, MAX_UINT256)\` on Base from this wallet (requires a small amount of ETH for gas, ~$0.01\u20130.10). After that, all future Permit2-based payments from this wallet work without further on-chain transactions.`
+  ].join("\n");
+};
 async function handleX402Payment({
   response,
   request,
@@ -722,27 +748,50 @@ async function handleX402Payment({
     "Access-Control-Expose-Headers",
     "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
   );
-  return await safeFetch(surface, request, timeout).andThen((paidResponse) => {
-    const settlementResult = safeGetPaymentSettlement(surface, paidResponse);
-    const settlement = settlementResult.isOk() ? settlementResult.value : null;
-    const maxAmount = tokenStringToNumber(paymentPayload.accepted.amount);
-    const settledAmount = settlement?.amount ? tokenStringToNumber(settlement.amount) : null;
-    const isUpTo = paymentPayload.accepted.scheme === "upto";
-    const price = settledAmount != null ? formatUsd(settledAmount) : isUpTo ? `up to ${formatUsd(maxAmount)}` : formatUsd(maxAmount);
-    return x402Ok({
-      response: paidResponse,
-      paymentInfo: {
-        protocol: "x402" /* X402 */,
-        network: caip2ToNetwork(paymentPayload.accepted.network),
-        price,
-        payment: settlement ? {
-          success: settlement.success,
-          transactionHash: settlement.transaction
-        } : null
-      }
-    });
+  const paidResult = await safeFetch(surface, request, timeout);
+  if (paidResult.isErr()) {
+    return paidResult;
+  }
+  const paidResponse = paidResult.value;
+  const permit2Error = await detectPermit2AllowanceError(paidResponse, {
+    walletAddress: wallets.evm.address,
+    scheme: paymentPayload.accepted.scheme
+  });
+  if (permit2Error) {
+    return x402Err(surface, permit2Error);
+  }
+  const settlementResult = safeGetPaymentSettlement(surface, paidResponse);
+  const settlement = settlementResult.isOk() ? settlementResult.value : null;
+  const maxAmount = tokenStringToNumber(paymentPayload.accepted.amount);
+  const settledAmount = settlement?.amount ? tokenStringToNumber(settlement.amount) : null;
+  const isUpTo = paymentPayload.accepted.scheme === "upto";
+  const price = settledAmount != null ? formatUsd(settledAmount) : isUpTo ? `up to ${formatUsd(maxAmount)}` : formatUsd(maxAmount);
+  return x402Ok({
+    response: paidResponse,
+    paymentInfo: {
+      protocol: "x402" /* X402 */,
+      network: caip2ToNetwork(paymentPayload.accepted.network),
+      price,
+      payment: settlement ? {
+        success: settlement.success,
+        transactionHash: settlement.transaction
+      } : null
+    }
   });
 }
+async function detectPermit2AllowanceError(response, context) {
+  if (response.ok) {
+    return null;
+  }
+  const body = await response.clone().text().catch(() => "");
+  if (!isPermit2AllowanceFailureBody(body)) {
+    return null;
+  }
+  return {
+    cause: "permit2_allowance_required",
+    message: buildPermit2AllowanceErrorMessage(context)
+  };
+}
 
 // src/operations/fetch/payment.ts
 async function executePayment(response, request, options) {
@@ -826,4 +875,4 @@ async function executeFetch(input, options) {
 export {
   executeFetch
 };
-//# sourceMappingURL=chunk-G5FHPXQL.js.map
+//# sourceMappingURL=chunk-JVMJVMWB.js.map