@haven_ai/sdk 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -447,6 +447,14 @@ declare const AgentPaymentPhase: {
447
447
  readonly Expired: "expired";
448
448
  /** Haven could not complete the payment; the agent should stop and surface the failure. */
449
449
  readonly Failed: "failed";
450
+ /**
451
+ * Pre-flight check determined the delegate's existing balance plus the
452
+ * remaining on-chain allowance cannot cover the requested amount, so no
453
+ * payment intent was created. Distinct from `UserApprovalRequired`: there
454
+ * is no approval that would fix this — the originating Safe needs more
455
+ * funds or the agent's per-token allowance needs to be raised first.
456
+ */
457
+ readonly InsufficientFunds: "insufficient_funds";
450
458
  };
451
459
  type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
452
460
  declare const AgentPaymentNextAction: {
@@ -466,6 +474,12 @@ declare const AgentPaymentNextAction: {
466
474
  readonly StopAndTellUser: "stop_and_tell_user";
467
475
  /** Ask again only if the user still wants the payment after expiry. */
468
476
  readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
477
+ /**
478
+ * Stop and tell the user that the originating Safe needs to be funded or
479
+ * the agent's per-token allowance needs to be raised before the payment
480
+ * can succeed. A user approval will not fix this state on its own.
481
+ */
482
+ readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
469
483
  };
470
484
  type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
471
485
  /**
@@ -505,8 +519,8 @@ declare const AgentPaymentRail: {
505
519
  type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail];
506
520
  type PaymentPhase = AgentPaymentPhase;
507
521
  type PaymentNextAction = AgentPaymentNextAction;
508
- declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent")[];
509
- declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it")[];
522
+ declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent" | "insufficient_funds")[];
523
+ declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "fund_safe_or_raise_allowance")[];
510
524
  declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
511
525
  declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
512
526
  declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
@@ -929,13 +943,19 @@ declare const toolDescriptions: {
929
943
  readonly quoteX402: {
930
944
  readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
931
945
  readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
932
- readonly nextActionGuidance: "";
946
+ readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again — Haven re-uses the captured request when paying.";
933
947
  };
934
948
  readonly payX402: {
935
949
  readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
936
950
  readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
937
951
  readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
938
- readonly nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming.";
952
+ readonly nextActionGuidance: string;
953
+ };
954
+ readonly payX402OneShot: {
955
+ readonly summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.";
956
+ readonly selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
957
+ readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.";
958
+ readonly nextActionGuidance: string;
939
959
  };
940
960
  readonly resumeX402: {
941
961
  readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
@@ -945,7 +965,7 @@ declare const toolDescriptions: {
945
965
  readonly quoteMpp: {
946
966
  readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
947
967
  readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
948
- readonly nextActionGuidance: "";
968
+ readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again — Haven re-uses the captured request when paying.";
949
969
  };
950
970
  readonly payMpp: {
951
971
  readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
package/dist/index.d.ts CHANGED
@@ -447,6 +447,14 @@ declare const AgentPaymentPhase: {
447
447
  readonly Expired: "expired";
448
448
  /** Haven could not complete the payment; the agent should stop and surface the failure. */
449
449
  readonly Failed: "failed";
450
+ /**
451
+ * Pre-flight check determined the delegate's existing balance plus the
452
+ * remaining on-chain allowance cannot cover the requested amount, so no
453
+ * payment intent was created. Distinct from `UserApprovalRequired`: there
454
+ * is no approval that would fix this — the originating Safe needs more
455
+ * funds or the agent's per-token allowance needs to be raised first.
456
+ */
457
+ readonly InsufficientFunds: "insufficient_funds";
450
458
  };
451
459
  type AgentPaymentPhase = (typeof AgentPaymentPhase)[keyof typeof AgentPaymentPhase];
452
460
  declare const AgentPaymentNextAction: {
@@ -466,6 +474,12 @@ declare const AgentPaymentNextAction: {
466
474
  readonly StopAndTellUser: "stop_and_tell_user";
467
475
  /** Ask again only if the user still wants the payment after expiry. */
468
476
  readonly RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it";
477
+ /**
478
+ * Stop and tell the user that the originating Safe needs to be funded or
479
+ * the agent's per-token allowance needs to be raised before the payment
480
+ * can succeed. A user approval will not fix this state on its own.
481
+ */
482
+ readonly FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance";
469
483
  };
470
484
  type AgentPaymentNextAction = (typeof AgentPaymentNextAction)[keyof typeof AgentPaymentNextAction];
471
485
  /**
@@ -505,8 +519,8 @@ declare const AgentPaymentRail: {
505
519
  type AgentPaymentRail = (typeof AgentPaymentRail)[keyof typeof AgentPaymentRail];
506
520
  type PaymentPhase = AgentPaymentPhase;
507
521
  type PaymentNextAction = AgentPaymentNextAction;
508
- declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent")[];
509
- declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it")[];
522
+ declare const AGENT_PAYMENT_PHASE_VALUES: ("rejected" | "expired" | "failed" | "agent_signature_required" | "payment_submitted" | "payment_confirmed" | "user_approval_required" | "user_execution_required" | "waiting_for_additional_approvals" | "funding_sent" | "insufficient_funds")[];
523
+ declare const AGENT_PAYMENT_NEXT_ACTION_VALUES: ("sign_and_submit_payment" | "check_status_later" | "none" | "wait_for_user_approval" | "wait_for_user_to_complete_payment" | "retry_original_x402_request" | "stop_and_tell_user" | "request_again_if_user_still_wants_it" | "fund_safe_or_raise_allowance")[];
510
524
  declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
511
525
  declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
512
526
  declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
@@ -929,13 +943,19 @@ declare const toolDescriptions: {
929
943
  readonly quoteX402: {
930
944
  readonly summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.";
931
945
  readonly behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior — Haven is not contacted.";
932
- readonly nextActionGuidance: "";
946
+ readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again — Haven re-uses the captured request when paying.";
933
947
  };
934
948
  readonly payX402: {
935
949
  readonly summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
936
950
  readonly selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
937
951
  readonly behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.";
938
- readonly nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming.";
952
+ readonly nextActionGuidance: string;
953
+ };
954
+ readonly payX402OneShot: {
955
+ readonly summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.";
956
+ readonly selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.";
957
+ readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.";
958
+ readonly nextActionGuidance: string;
939
959
  };
940
960
  readonly resumeX402: {
941
961
  readonly summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.";
@@ -945,7 +965,7 @@ declare const toolDescriptions: {
945
965
  readonly quoteMpp: {
946
966
  readonly summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.";
947
967
  readonly behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only — Haven is not contacted.";
948
- readonly nextActionGuidance: "";
968
+ readonly nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again — Haven re-uses the captured request when paying.";
949
969
  };
950
970
  readonly payMpp: {
951
971
  readonly summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.";
package/dist/index.js CHANGED
@@ -27,7 +27,15 @@ var AgentPaymentPhase = {
27
27
  /** The payment or approval request expired before completion. */
28
28
  Expired: "expired",
29
29
  /** Haven could not complete the payment; the agent should stop and surface the failure. */
30
- Failed: "failed"
30
+ Failed: "failed",
31
+ /**
32
+ * Pre-flight check determined the delegate's existing balance plus the
33
+ * remaining on-chain allowance cannot cover the requested amount, so no
34
+ * payment intent was created. Distinct from `UserApprovalRequired`: there
35
+ * is no approval that would fix this — the originating Safe needs more
36
+ * funds or the agent's per-token allowance needs to be raised first.
37
+ */
38
+ InsufficientFunds: "insufficient_funds"
31
39
  };
32
40
  var AgentPaymentNextAction = {
33
41
  /** Sign with the delegate key and submit the payment to Haven. */
@@ -45,7 +53,13 @@ var AgentPaymentNextAction = {
45
53
  /** Stop retrying this payment and tell the user what happened. */
46
54
  StopAndTellUser: "stop_and_tell_user",
47
55
  /** Ask again only if the user still wants the payment after expiry. */
48
- RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it"
56
+ RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it",
57
+ /**
58
+ * Stop and tell the user that the originating Safe needs to be funded or
59
+ * the agent's per-token allowance needs to be raised before the payment
60
+ * can succeed. A user approval will not fix this state on its own.
61
+ */
62
+ FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance"
49
63
  };
50
64
  var AgentPaymentRail = {
51
65
  /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -76,7 +90,8 @@ var AgentPaymentPhaseDescriptions = {
76
90
  [AgentPaymentPhase.FundingSent]: "The Haven funding leg was sent; the agent can continue the merchant/protocol leg.",
77
91
  [AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
78
92
  [AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
79
- [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure."
93
+ [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure.",
94
+ [AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain allowance cannot cover the requested amount, so no payment was created. The originating Safe must be funded or the agent allowance raised before retrying."
80
95
  };
81
96
  var AgentPaymentNextActionDescriptions = {
82
97
  [AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
@@ -86,7 +101,8 @@ var AgentPaymentNextActionDescriptions = {
86
101
  [AgentPaymentNextAction.WaitForUserToCompletePayment]: "Wait for the wallet owner to finish sending the approved funding payment.",
87
102
  [AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
88
103
  [AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
89
- [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry."
104
+ [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry.",
105
+ [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed."
90
106
  };
91
107
  var AgentPaymentRailDescriptions = {
92
108
  [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
@@ -202,6 +218,7 @@ function verifySignature(hash, signature, expectedAddress) {
202
218
  }
203
219
  var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
204
220
  var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
221
+ var DECIMAL_ATOMIC_AMOUNT_RE = /^[0-9]+$/;
205
222
  function decodeBase64Json(value, label) {
206
223
  try {
207
224
  return JSON.parse(atob(value));
@@ -209,6 +226,12 @@ function decodeBase64Json(value, label) {
209
226
  throw new Error(`Failed to decode ${label}`);
210
227
  }
211
228
  }
229
+ function isPositiveDecimalAtomicAmount(value) {
230
+ return DECIMAL_ATOMIC_AMOUNT_RE.test(value) && BigInt(value) > 0n;
231
+ }
232
+ function optionAuthorizationAmount(option) {
233
+ return option.maxAmountRequired ?? option.amount;
234
+ }
212
235
  function normalizePaymentOption(value) {
213
236
  const candidate = value;
214
237
  if (!candidate || typeof candidate !== "object" || typeof candidate.scheme !== "string" || typeof candidate.network !== "string" || typeof candidate.asset !== "string" || typeof candidate.payTo !== "string") {
@@ -216,6 +239,10 @@ function normalizePaymentOption(value) {
216
239
  }
217
240
  const amount = typeof candidate.amount === "string" ? candidate.amount : typeof candidate.maxAmountRequired === "string" ? candidate.maxAmountRequired : null;
218
241
  if (!amount) return null;
242
+ if (!isPositiveDecimalAtomicAmount(amount)) return null;
243
+ if (candidate.maxAmountRequired !== void 0 && (typeof candidate.maxAmountRequired !== "string" || !isPositiveDecimalAtomicAmount(candidate.maxAmountRequired))) {
244
+ return null;
245
+ }
219
246
  return {
220
247
  scheme: candidate.scheme,
221
248
  network: candidate.network,
@@ -316,11 +343,13 @@ function selectPaymentOption(accepts) {
316
343
  for (const opt of accepts) {
317
344
  if (opt.network in SUPPORTED_X402_NETWORKS) {
318
345
  const networkTokens = NETWORK_TOKENS[opt.network];
319
- if (networkTokens?.[opt.asset.toLowerCase()]) return opt;
346
+ if (networkTokens?.[opt.asset.toLowerCase()] && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
347
+ return opt;
348
+ }
320
349
  }
321
350
  }
322
351
  for (const opt of accepts) {
323
- if (opt.network in SUPPORTED_X402_NETWORKS) {
352
+ if (opt.network in SUPPORTED_X402_NETWORKS && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
324
353
  return opt;
325
354
  }
326
355
  }
@@ -329,14 +358,18 @@ function selectPaymentOption(accepts) {
329
358
  function selectStandardPaymentOption(accepts) {
330
359
  if (!accepts || accepts.length === 0) return null;
331
360
  for (const opt of accepts) {
332
- if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && opt.asset.toLowerCase() === BASE_USDC_ADDRESS) {
361
+ if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && opt.asset.toLowerCase() === BASE_USDC_ADDRESS && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
333
362
  return opt;
334
363
  }
335
364
  }
336
365
  return null;
337
366
  }
338
367
  function x402AuthorizationAmount(option) {
339
- return option.maxAmountRequired ?? option.amount;
368
+ const amount = optionAuthorizationAmount(option);
369
+ if (!isPositiveDecimalAtomicAmount(amount)) {
370
+ throw new Error("Invalid x402 amount: must be a positive decimal atomic amount");
371
+ }
372
+ return amount;
340
373
  }
341
374
  function buildX402ExpectedMessage(context) {
342
375
  return `Haven x402 expected context v1
@@ -1583,13 +1616,7 @@ var HavenClient = class {
1583
1616
  paymentRequired.x402Version,
1584
1617
  requirements
1585
1618
  );
1586
- if (paymentRequired.x402Version < 2) return header;
1587
- const payment = decodeBase64Json3(header);
1588
- return btoa(JSON.stringify({
1589
- x402Version: paymentRequired.x402Version,
1590
- accepted: option,
1591
- payload: payment.payload
1592
- }));
1619
+ return header;
1593
1620
  }
1594
1621
  cacheX402Receipt(idempotencyKey, paymentHeader, receipt) {
1595
1622
  const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
@@ -2307,13 +2334,19 @@ var toolDescriptions = {
2307
2334
  quoteX402: {
2308
2335
  summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.",
2309
2336
  behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior \u2014 Haven is not contacted.",
2310
- nextActionGuidance: ""
2337
+ nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again \u2014 Haven re-uses the captured request when paying."
2311
2338
  },
2312
2339
  payX402: {
2313
2340
  summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
2314
2341
  selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
2315
2342
  behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
2316
- nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming."
2343
+ nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
2344
+ },
2345
+ payX402OneShot: {
2346
+ summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
2347
+ selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
2348
+ behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
2349
+ nextActionGuidance: "If approval is needed, preserve the returned resume_state or paymentId and call the resume tool once nextAction=retry_original_x402_request. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
2317
2350
  },
2318
2351
  resumeX402: {
2319
2352
  summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.",
@@ -2323,7 +2356,7 @@ var toolDescriptions = {
2323
2356
  quoteMpp: {
2324
2357
  summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.",
2325
2358
  behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only \u2014 Haven is not contacted.",
2326
- nextActionGuidance: ""
2359
+ nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again \u2014 Haven re-uses the captured request when paying."
2327
2360
  },
2328
2361
  payMpp: {
2329
2362
  summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",