@haven_ai/sdk 0.1.22-alpha.0 → 0.1.23-alpha.0
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/README.md +3 -1
- package/dist/index.cjs +107 -31
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +95 -5
- package/dist/index.d.ts +95 -5
- package/dist/index.js +107 -32
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/index.d.cts
CHANGED
|
@@ -270,6 +270,21 @@ interface X402AuthorizationOptions {
|
|
|
270
270
|
* omit for a non-MCP-tool x402 merchant (plain HTTP resource).
|
|
271
271
|
*/
|
|
272
272
|
mcpCallContext?: X402McpCallContext;
|
|
273
|
+
/**
|
|
274
|
+
* #1348: the agent's delegate address, when the caller already resolved it
|
|
275
|
+
* from `getAgent()` in this same flow — skips `createX402Intent`'s internal
|
|
276
|
+
* agent fetch (one full round trip on every guided purchase). Staleness
|
|
277
|
+
* caveat (#1358 review): the backend derives the funding shape by comparing
|
|
278
|
+
* `payTo` to the CURRENT delegate address, so a value made stale by a
|
|
279
|
+
* delegate rotation mid-flow is not always a clean failure — a pinned-budget
|
|
280
|
+
* agent gets a 403, but an open-budget delegation agent would route to the
|
|
281
|
+
* settlement shape with the stale address. The window is one tool call
|
|
282
|
+
* (previously sub-millisecond, now the merchant-quote duration), never
|
|
283
|
+
* externally suppliable; server-truth hardening is tracked in #1360. Only
|
|
284
|
+
* pass an address fetched in THIS flow; omit to keep the self-contained
|
|
285
|
+
* fetch.
|
|
286
|
+
*/
|
|
287
|
+
delegateAddress?: string;
|
|
273
288
|
}
|
|
274
289
|
/**
|
|
275
290
|
* Keyless x402 construct result.
|
|
@@ -403,6 +418,16 @@ interface X402Quote {
|
|
|
403
418
|
amountAtomic: string;
|
|
404
419
|
amount: string;
|
|
405
420
|
token: string;
|
|
421
|
+
/**
|
|
422
|
+
* #1351: decimals for `asset` on `network`, resolved from the SAME
|
|
423
|
+
* address→token binding that produced `token` — the quote's own authority on
|
|
424
|
+
* how many atomic units one human unit is. `null` when the merchant's asset
|
|
425
|
+
* is not a token Haven recognises on that network, in which case `token` is
|
|
426
|
+
* an unverified fallback label and NO human→atomic conversion is safe.
|
|
427
|
+
* Consumers converting a human-denominated figure (a user-intent spending
|
|
428
|
+
* cap) MUST fail closed on `null` rather than assume 6.
|
|
429
|
+
*/
|
|
430
|
+
decimals: number | null;
|
|
406
431
|
asset: string;
|
|
407
432
|
network: string;
|
|
408
433
|
chainId: number | null;
|
|
@@ -825,6 +850,22 @@ declare const AgentPaymentFailureCode: {
|
|
|
825
850
|
* mcp_transport explicitly (the version-skew path).
|
|
826
851
|
*/
|
|
827
852
|
readonly MerchantCallContextUnavailable: "MERCHANT_CALL_CONTEXT_UNAVAILABLE";
|
|
853
|
+
/**
|
|
854
|
+
* #1351: the caller supplied BOTH the atomic `max_amount` and the
|
|
855
|
+
* human-denominated `max_amount_human` cap for one purchase. Haven refuses
|
|
856
|
+
* to guess which the user meant — the two differ by a factor of 10^decimals,
|
|
857
|
+
* so picking wrong is exactly the silent-overspend this cap exists to
|
|
858
|
+
* prevent. Rejected before any merchant probe, funding intent, or signature.
|
|
859
|
+
*/
|
|
860
|
+
readonly AmbiguousMaxAmount: "AMBIGUOUS_MAX_AMOUNT";
|
|
861
|
+
/**
|
|
862
|
+
* #1351: a human-denominated cap was supplied, but it cannot be converted to
|
|
863
|
+
* atomic units against THIS quote — either the quote's asset has no known
|
|
864
|
+
* decimals on its network, or the cap carries more fraction digits than the
|
|
865
|
+
* asset can represent (truncating it would silently change the user's cap).
|
|
866
|
+
* The fallback is the exact atomic `max_amount`.
|
|
867
|
+
*/
|
|
868
|
+
readonly MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE";
|
|
828
869
|
};
|
|
829
870
|
type AgentPaymentFailureCode = (typeof AgentPaymentFailureCode)[keyof typeof AgentPaymentFailureCode];
|
|
830
871
|
/**
|
|
@@ -866,7 +907,7 @@ type PaymentPhase = AgentPaymentPhase;
|
|
|
866
907
|
type PaymentNextAction = AgentPaymentNextAction;
|
|
867
908
|
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" | "funded_but_unsettled")[];
|
|
868
909
|
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" | "retry_with_explicit_context" | "payment_window_expired" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds")[];
|
|
869
|
-
declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE")[];
|
|
910
|
+
declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE" | "AMBIGUOUS_MAX_AMOUNT" | "MAX_AMOUNT_UNCONVERTIBLE")[];
|
|
870
911
|
declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
|
|
871
912
|
declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
|
|
872
913
|
declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
|
|
@@ -931,6 +972,34 @@ interface AgentNextStep {
|
|
|
931
972
|
safe_to_continue: boolean;
|
|
932
973
|
reason: string;
|
|
933
974
|
}
|
|
975
|
+
/**
|
|
976
|
+
* #1349: compact, Haven-generated reporting evidence for a completed x402
|
|
977
|
+
* merchant purchase. `status`, money fields, merchant endpoint/address, and
|
|
978
|
+
* funding transaction come from Haven payment state; `product` and
|
|
979
|
+
* `invoice_id` are optional merchant-supplied display metadata. The raw
|
|
980
|
+
* merchant result remains separate evidence and MUST NOT be used to infer
|
|
981
|
+
* settlement status.
|
|
982
|
+
*/
|
|
983
|
+
interface AgentPurchaseSummary {
|
|
984
|
+
/** Set only after Haven has completed the funding and merchant-settlement flow. */
|
|
985
|
+
status: 'settled';
|
|
986
|
+
product: string | null;
|
|
987
|
+
amount: string | null;
|
|
988
|
+
amount_atomic: string | null;
|
|
989
|
+
asset: string | null;
|
|
990
|
+
network: string | null;
|
|
991
|
+
merchant: {
|
|
992
|
+
address: string | null;
|
|
993
|
+
resource_url: string | null;
|
|
994
|
+
};
|
|
995
|
+
/** Merchant-supplied identifier, or null when the merchant did not supply one. */
|
|
996
|
+
invoice_id: string | null;
|
|
997
|
+
funding_tx_hash: string | null;
|
|
998
|
+
/** Optional merchant receipt reference parsed from PAYMENT-RESPONSE; not Haven settlement proof. */
|
|
999
|
+
settlement_tx_hash: string | null;
|
|
1000
|
+
/** Same read-only allowance block returned at the top level, or null when unavailable. */
|
|
1001
|
+
allowance: PostPurchaseAllowanceSummary | null;
|
|
1002
|
+
}
|
|
934
1003
|
/** #1308: compact reporting summary — what the agent tells the user. */
|
|
935
1004
|
interface AgentPaymentSummary {
|
|
936
1005
|
payment_id: string;
|
|
@@ -941,6 +1010,12 @@ interface AgentPaymentSummary {
|
|
|
941
1010
|
network?: string;
|
|
942
1011
|
expires_at?: string;
|
|
943
1012
|
product?: string;
|
|
1013
|
+
/**
|
|
1014
|
+
* Default reporting contract for a successful `haven_settle_mcp_tool` call.
|
|
1015
|
+
* The merchant's raw `result` remains available separately as advanced
|
|
1016
|
+
* evidence; do not parse it to determine whether a payment settled.
|
|
1017
|
+
*/
|
|
1018
|
+
purchase_summary?: AgentPurchaseSummary;
|
|
944
1019
|
}
|
|
945
1020
|
declare const AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
|
|
946
1021
|
declare const AgentPaymentPhaseSchema: AgentPaymentEnumSchema;
|
|
@@ -1408,6 +1483,8 @@ declare class HavenClient {
|
|
|
1408
1483
|
* Get the agent identity tied to this API key.
|
|
1409
1484
|
*/
|
|
1410
1485
|
getAgent(): Promise<HavenAgent>;
|
|
1486
|
+
private agentInFlight;
|
|
1487
|
+
private fetchAgent;
|
|
1411
1488
|
/**
|
|
1412
1489
|
* One-shot "am I ready?" bootstrap: identity + live spend authority + a
|
|
1413
1490
|
* readiness signal, in a single call. Folds {@link getAgent} and
|
|
@@ -1478,6 +1555,8 @@ declare class HavenClient {
|
|
|
1478
1555
|
getPostPurchaseAllowanceSummary(paymentId: string): Promise<{
|
|
1479
1556
|
allowance: PostPurchaseAllowanceSummary | null;
|
|
1480
1557
|
warnings: AgentPaymentWarning[];
|
|
1558
|
+
/** Same authenticated payment-state read used to resolve the settled token. */
|
|
1559
|
+
payment: PaymentStatusResult | null;
|
|
1481
1560
|
}>;
|
|
1482
1561
|
/**
|
|
1483
1562
|
* `haven_get_payment_status` convenience: fetch status and, for a
|
|
@@ -1506,6 +1585,7 @@ declare class HavenClient {
|
|
|
1506
1585
|
*/
|
|
1507
1586
|
discoverTools(options?: {
|
|
1508
1587
|
category?: string;
|
|
1588
|
+
search?: string;
|
|
1509
1589
|
rail?: 'x402' | 'mpp';
|
|
1510
1590
|
}): Promise<HavenCatalogEntry[]>;
|
|
1511
1591
|
/**
|
|
@@ -1987,7 +2067,7 @@ declare const toolDescriptions: {
|
|
|
1987
2067
|
readonly summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog — names, prices, and which pay tool to use next.";
|
|
1988
2068
|
readonly selectionGuidance: string;
|
|
1989
2069
|
readonly behavior: string;
|
|
1990
|
-
readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass
|
|
2070
|
+
readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens (\"no more than 1 USDC\" → max_amount_human: \"1\") — never convert it to atomic units by hand (#1351).";
|
|
1991
2071
|
};
|
|
1992
2072
|
readonly sweep_delegate: {
|
|
1993
2073
|
readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
|
|
@@ -2023,7 +2103,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
|
|
|
2023
2103
|
* this canonical string and asserts byte-for-byte equality, so the two copies
|
|
2024
2104
|
* cannot drift.
|
|
2025
2105
|
*/
|
|
2026
|
-
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the source of truth.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n (wallet, network) plus a readiness signal (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n `catalog_id`.\n2. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and\n
|
|
2106
|
+
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the source of truth.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n (wallet, network) plus a readiness signal (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n `catalog_id`.\n2. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and a\n spending cap. A cap is REQUIRED on this tool and is best practice on every\n paid call below too \u2014 it caps what the LIVE merchant quote may charge,\n checked before any funding intent is created. Write it the way the user\n said it: `max_amount_human` is whole tokens, so \"no more than 1 USDC\" is\n `max_amount_human: \"1\"`. (`max_amount` is the atomic-unit form, where\n \"1\" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)\n3. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: `next_action`, `next_tool`,\n and `next_arguments` name the exact next call \u2014 act on those first; the\n prose in this section is fallback and debugging detail. If the catalog\n entry is missing or degraded, the response instead names\n `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name, arguments) as\n the manual fallback.\n\n**Signing:** `mcp__haven-signer__haven_sign_x402` with `payment_id` ONLY \u2014\nthe local signer fetches the exact signing bytes AND `payment_required`\nitself, so never relay `typed_data` or the 402 blob yourself. If the signer\nreports its fetched context carried no `payment_required` (older backend),\nre-call with `payment_required` added verbatim. Fallback for an older signer\nor backend: re-run the quote/prepare tool with the SAME `idempotency_key`\nplus `include_signing_payload=true`, then pass `payload_hash`,\n`x402_expected` (the nested `x402.expected` object), and\n`typed_data`/`typed_data_b64` through unchanged.\n\n**Settle:** `mcp__haven__haven_settle_mcp_tool` with `payment_id`,\n`signature`, and `payment_header` ONLY \u2014 Haven rehydrates the merchant call\ncontext (`merchant_url`, `tool_name`, `arguments`, `mcp_transport`)\nserver-side from `payment_id`. Pass those four fields explicitly only as a\nversion-skew fallback when Haven has no stored context for the id \u2014 both or\nnone together, never just one. If the settle result carries `settled: false`,\nfunding is queued for the user's approval \u2014 tell them and check status later,\ndo not re-pay.\n\nStep-by-step alternative (also key-safe; for an older signer or backend, or\nwhen you already have a merchant URL and tool name instead of a\n`catalog_id`): `mcp__haven__haven_pay_mcp_tool` then\n`mcp__haven-signer__haven_sign` \u2192 `mcp__haven__haven_submit` \u2192\n`mcp__haven-signer__haven_x402_sign_header` \u2192\n`mcp__haven__haven_complete_mcp_tool`. Pass `payment_required`,\n`arguments`, and `mcp_transport` verbatim from the quote/prepare result.\nThe returned `expires_at` is the signing window; if a tool returns\n`PAYMENT_WINDOW_EXPIRED`, re-run the same quote/prepare tool with the same\n`idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\nmerchant leg for you.\n\n**Direct transfer / non-MCP paywall:** `mcp__haven__haven_pay` with\nrecipient, amount, and token for a plain transfer. For an arbitrary,\nnon-MCP x402 paywall: `mcp__haven__haven_quote_x402` to get a quote, then\n`mcp__haven__haven_pay_x402_quote` \u2014 follow the result's guidance fields\nfirst, sign in the local Haven signer, and retry the original request only\nwhen the result says `retry_original_x402_request`.\n\n**Catalog tool arguments:** when `haven_discover_tools` returns\n`tool_arguments`, pass that object unchanged as the pay tool's\n`arguments` field (for example\n`tool_arguments: { \"tier\": \"50gb\" }` -> `arguments: { \"tier\": \"50gb\" }`).\n\n**Prices:** show the user the live price from the pay-tool result, never a\ncatalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. The pay-tool result's `amount` /\n`amount_atomic` is the amount Haven authorizes for the call \u2014 a ceiling the\nmerchant settles at or below \u2014 so present it as the most the user will pay.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n budget and is waiting for the user in Haven. Tell the user, then check\n status later.\n- `safe_to_continue: false` on a guidance block is the same signal in\n machine-readable form: stop and involve the user before calling anything\n else for this payment.\n- Never ask the user for private keys. Signing happens only in the local Haven\n signer; the hosted Haven tools never receive the signing key. If a tool\n reports a missing or invalid credential, tell the user to re-run the Haven\n setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your cap. No funds\n moved; ask the user before retrying with a higher one.\n- `AMBIGUOUS_MAX_AMOUNT`: you sent both `max_amount` and\n `max_amount_human`. Nothing was contacted or spent \u2014 re-send with exactly\n one (`max_amount_human` for a cap the user stated in tokens).\n- `MAX_AMOUNT_UNCONVERTIBLE`: `max_amount_human` does not fit this quote's\n asset \u2014 unknown decimals, or more decimal places than the asset supports.\n Round the cap, or send an exact atomic `max_amount`.\n- `PAYMENT_WINDOW_EXPIRED`: re-run the quote/prepare tool with the same\n `idempotency_key`, then sign the fresh payload.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n Stop-and-sweep \u2014 stop retrying the merchant and use\n `mcp__haven__haven_sweep_delegate` to recover stranded delegate funds.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: funding confirmed on-chain, but the\n merchant never answered the paid retry. This is NOT proof of rejection \u2014 the\n merchant may still settle late. Verify-then-sweep, never a blind sweep:\n check `mcp__haven__haven_get_payment_status`, retry\n `mcp__haven__haven_complete_mcp_tool` ONCE, and only sweep with\n `mcp__haven__haven_sweep_delegate` if no settlement appears.\n- Budget exceeded: tell the user how much remains (from\n `mcp__haven__haven_get_allowances`) and that they can raise the budget in\n Haven.\n\n## Reporting after a purchase\n\nA settled `mcp__haven__haven_settle_mcp_tool` response carries\n`agent_summary.purchase_summary` and the remaining post-purchase allowance\nin `allowance` \u2014 report the product, Haven-derived payment/transaction\nfields, and what is left from those fields directly. `result` is optional\nraw merchant evidence; never use it to decide whether the purchase was paid.\nDo not call `haven_get_agent` or `haven_get_allowances` again just to\nreport a purchase you already made.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
|
|
2027
2107
|
/** Directory name for the installed skill folder. */
|
|
2028
2108
|
declare const SKILL_FOLDER_NAME = "haven-pay";
|
|
2029
2109
|
|
|
@@ -2061,7 +2141,7 @@ declare const SKILL_FOLDER_NAME = "haven-pay";
|
|
|
2061
2141
|
* package. A guard test in each package asserts exactly that against its own
|
|
2062
2142
|
* `package.json`, so the two cannot drift again silently.
|
|
2063
2143
|
*/
|
|
2064
|
-
declare const HAVEN_MINIMUM_NODE_VERSION = "
|
|
2144
|
+
declare const HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
|
|
2065
2145
|
/**
|
|
2066
2146
|
* Compare two Node versions. Negative when `left` is older.
|
|
2067
2147
|
*
|
|
@@ -2206,6 +2286,16 @@ declare function encodePaymentProof(receipt: {
|
|
|
2206
2286
|
payer?: string;
|
|
2207
2287
|
chainId?: number;
|
|
2208
2288
|
}): string;
|
|
2289
|
+
/**
|
|
2290
|
+
* Resolve a token symbol from a contract address.
|
|
2291
|
+
*
|
|
2292
|
+
* Checks all supported chains. For chain-specific resolution,
|
|
2293
|
+
* pass the optional `network` CAIP-2 string (e.g. "eip155:100").
|
|
2294
|
+
*/
|
|
2295
|
+
declare function resolveTokenFromAddress(address: string, network?: string): {
|
|
2296
|
+
symbol: string;
|
|
2297
|
+
decimals: number;
|
|
2298
|
+
} | null;
|
|
2209
2299
|
|
|
2210
2300
|
declare function parseMachinePaymentChallenge(response: Response): MachinePaymentChallenge;
|
|
2211
2301
|
declare function parseMachinePaymentChallengeResponse(response: Response): Promise<MachinePaymentChallenge>;
|
|
@@ -2278,4 +2368,4 @@ declare function discoverMerchantMcpUrl(inputUrl: string): Promise<string | null
|
|
|
2278
2368
|
/** Trailing-slash/percent-case echoes compare equal; unparseable never does. */
|
|
2279
2369
|
declare function sameUrl(a: string, b: string): boolean;
|
|
2280
2370
|
|
|
2281
|
-
export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type ClaudeTool, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, MerchantTimeoutError, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
|
|
2371
|
+
export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, type ClaudeTool, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, MerchantTimeoutError, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
|
package/dist/index.d.ts
CHANGED
|
@@ -270,6 +270,21 @@ interface X402AuthorizationOptions {
|
|
|
270
270
|
* omit for a non-MCP-tool x402 merchant (plain HTTP resource).
|
|
271
271
|
*/
|
|
272
272
|
mcpCallContext?: X402McpCallContext;
|
|
273
|
+
/**
|
|
274
|
+
* #1348: the agent's delegate address, when the caller already resolved it
|
|
275
|
+
* from `getAgent()` in this same flow — skips `createX402Intent`'s internal
|
|
276
|
+
* agent fetch (one full round trip on every guided purchase). Staleness
|
|
277
|
+
* caveat (#1358 review): the backend derives the funding shape by comparing
|
|
278
|
+
* `payTo` to the CURRENT delegate address, so a value made stale by a
|
|
279
|
+
* delegate rotation mid-flow is not always a clean failure — a pinned-budget
|
|
280
|
+
* agent gets a 403, but an open-budget delegation agent would route to the
|
|
281
|
+
* settlement shape with the stale address. The window is one tool call
|
|
282
|
+
* (previously sub-millisecond, now the merchant-quote duration), never
|
|
283
|
+
* externally suppliable; server-truth hardening is tracked in #1360. Only
|
|
284
|
+
* pass an address fetched in THIS flow; omit to keep the self-contained
|
|
285
|
+
* fetch.
|
|
286
|
+
*/
|
|
287
|
+
delegateAddress?: string;
|
|
273
288
|
}
|
|
274
289
|
/**
|
|
275
290
|
* Keyless x402 construct result.
|
|
@@ -403,6 +418,16 @@ interface X402Quote {
|
|
|
403
418
|
amountAtomic: string;
|
|
404
419
|
amount: string;
|
|
405
420
|
token: string;
|
|
421
|
+
/**
|
|
422
|
+
* #1351: decimals for `asset` on `network`, resolved from the SAME
|
|
423
|
+
* address→token binding that produced `token` — the quote's own authority on
|
|
424
|
+
* how many atomic units one human unit is. `null` when the merchant's asset
|
|
425
|
+
* is not a token Haven recognises on that network, in which case `token` is
|
|
426
|
+
* an unverified fallback label and NO human→atomic conversion is safe.
|
|
427
|
+
* Consumers converting a human-denominated figure (a user-intent spending
|
|
428
|
+
* cap) MUST fail closed on `null` rather than assume 6.
|
|
429
|
+
*/
|
|
430
|
+
decimals: number | null;
|
|
406
431
|
asset: string;
|
|
407
432
|
network: string;
|
|
408
433
|
chainId: number | null;
|
|
@@ -825,6 +850,22 @@ declare const AgentPaymentFailureCode: {
|
|
|
825
850
|
* mcp_transport explicitly (the version-skew path).
|
|
826
851
|
*/
|
|
827
852
|
readonly MerchantCallContextUnavailable: "MERCHANT_CALL_CONTEXT_UNAVAILABLE";
|
|
853
|
+
/**
|
|
854
|
+
* #1351: the caller supplied BOTH the atomic `max_amount` and the
|
|
855
|
+
* human-denominated `max_amount_human` cap for one purchase. Haven refuses
|
|
856
|
+
* to guess which the user meant — the two differ by a factor of 10^decimals,
|
|
857
|
+
* so picking wrong is exactly the silent-overspend this cap exists to
|
|
858
|
+
* prevent. Rejected before any merchant probe, funding intent, or signature.
|
|
859
|
+
*/
|
|
860
|
+
readonly AmbiguousMaxAmount: "AMBIGUOUS_MAX_AMOUNT";
|
|
861
|
+
/**
|
|
862
|
+
* #1351: a human-denominated cap was supplied, but it cannot be converted to
|
|
863
|
+
* atomic units against THIS quote — either the quote's asset has no known
|
|
864
|
+
* decimals on its network, or the cap carries more fraction digits than the
|
|
865
|
+
* asset can represent (truncating it would silently change the user's cap).
|
|
866
|
+
* The fallback is the exact atomic `max_amount`.
|
|
867
|
+
*/
|
|
868
|
+
readonly MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE";
|
|
828
869
|
};
|
|
829
870
|
type AgentPaymentFailureCode = (typeof AgentPaymentFailureCode)[keyof typeof AgentPaymentFailureCode];
|
|
830
871
|
/**
|
|
@@ -866,7 +907,7 @@ type PaymentPhase = AgentPaymentPhase;
|
|
|
866
907
|
type PaymentNextAction = AgentPaymentNextAction;
|
|
867
908
|
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" | "funded_but_unsettled")[];
|
|
868
909
|
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" | "retry_with_explicit_context" | "payment_window_expired" | "fund_safe_or_raise_allowance" | "sweep_stranded_funds")[];
|
|
869
|
-
declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE")[];
|
|
910
|
+
declare const AGENT_PAYMENT_FAILURE_CODE_VALUES: ("PRICE_EXCEEDS_MAX" | "PAYMENT_WINDOW_EXPIRED" | "MERCHANT_REJECTED_AFTER_FUNDING" | "MERCHANT_UNRESPONSIVE_AFTER_FUNDING" | "MERCHANT_CALL_CONTEXT_UNAVAILABLE" | "AMBIGUOUS_MAX_AMOUNT" | "MAX_AMOUNT_UNCONVERTIBLE")[];
|
|
870
911
|
declare const AGENT_PAYMENT_RAIL_VALUES: ("x402" | "mpp" | "mpp_demo" | "mpp_crypto" | "stripe_deposit" | "spt" | "direct")[];
|
|
871
912
|
declare const AgentPaymentPhaseDescriptions: Record<AgentPaymentPhase, string>;
|
|
872
913
|
declare const AgentPaymentNextActionDescriptions: Record<AgentPaymentNextAction, string>;
|
|
@@ -931,6 +972,34 @@ interface AgentNextStep {
|
|
|
931
972
|
safe_to_continue: boolean;
|
|
932
973
|
reason: string;
|
|
933
974
|
}
|
|
975
|
+
/**
|
|
976
|
+
* #1349: compact, Haven-generated reporting evidence for a completed x402
|
|
977
|
+
* merchant purchase. `status`, money fields, merchant endpoint/address, and
|
|
978
|
+
* funding transaction come from Haven payment state; `product` and
|
|
979
|
+
* `invoice_id` are optional merchant-supplied display metadata. The raw
|
|
980
|
+
* merchant result remains separate evidence and MUST NOT be used to infer
|
|
981
|
+
* settlement status.
|
|
982
|
+
*/
|
|
983
|
+
interface AgentPurchaseSummary {
|
|
984
|
+
/** Set only after Haven has completed the funding and merchant-settlement flow. */
|
|
985
|
+
status: 'settled';
|
|
986
|
+
product: string | null;
|
|
987
|
+
amount: string | null;
|
|
988
|
+
amount_atomic: string | null;
|
|
989
|
+
asset: string | null;
|
|
990
|
+
network: string | null;
|
|
991
|
+
merchant: {
|
|
992
|
+
address: string | null;
|
|
993
|
+
resource_url: string | null;
|
|
994
|
+
};
|
|
995
|
+
/** Merchant-supplied identifier, or null when the merchant did not supply one. */
|
|
996
|
+
invoice_id: string | null;
|
|
997
|
+
funding_tx_hash: string | null;
|
|
998
|
+
/** Optional merchant receipt reference parsed from PAYMENT-RESPONSE; not Haven settlement proof. */
|
|
999
|
+
settlement_tx_hash: string | null;
|
|
1000
|
+
/** Same read-only allowance block returned at the top level, or null when unavailable. */
|
|
1001
|
+
allowance: PostPurchaseAllowanceSummary | null;
|
|
1002
|
+
}
|
|
934
1003
|
/** #1308: compact reporting summary — what the agent tells the user. */
|
|
935
1004
|
interface AgentPaymentSummary {
|
|
936
1005
|
payment_id: string;
|
|
@@ -941,6 +1010,12 @@ interface AgentPaymentSummary {
|
|
|
941
1010
|
network?: string;
|
|
942
1011
|
expires_at?: string;
|
|
943
1012
|
product?: string;
|
|
1013
|
+
/**
|
|
1014
|
+
* Default reporting contract for a successful `haven_settle_mcp_tool` call.
|
|
1015
|
+
* The merchant's raw `result` remains available separately as advanced
|
|
1016
|
+
* evidence; do not parse it to determine whether a payment settled.
|
|
1017
|
+
*/
|
|
1018
|
+
purchase_summary?: AgentPurchaseSummary;
|
|
944
1019
|
}
|
|
945
1020
|
declare const AgentPaymentRailDescriptions: Record<AgentPaymentRail, string>;
|
|
946
1021
|
declare const AgentPaymentPhaseSchema: AgentPaymentEnumSchema;
|
|
@@ -1408,6 +1483,8 @@ declare class HavenClient {
|
|
|
1408
1483
|
* Get the agent identity tied to this API key.
|
|
1409
1484
|
*/
|
|
1410
1485
|
getAgent(): Promise<HavenAgent>;
|
|
1486
|
+
private agentInFlight;
|
|
1487
|
+
private fetchAgent;
|
|
1411
1488
|
/**
|
|
1412
1489
|
* One-shot "am I ready?" bootstrap: identity + live spend authority + a
|
|
1413
1490
|
* readiness signal, in a single call. Folds {@link getAgent} and
|
|
@@ -1478,6 +1555,8 @@ declare class HavenClient {
|
|
|
1478
1555
|
getPostPurchaseAllowanceSummary(paymentId: string): Promise<{
|
|
1479
1556
|
allowance: PostPurchaseAllowanceSummary | null;
|
|
1480
1557
|
warnings: AgentPaymentWarning[];
|
|
1558
|
+
/** Same authenticated payment-state read used to resolve the settled token. */
|
|
1559
|
+
payment: PaymentStatusResult | null;
|
|
1481
1560
|
}>;
|
|
1482
1561
|
/**
|
|
1483
1562
|
* `haven_get_payment_status` convenience: fetch status and, for a
|
|
@@ -1506,6 +1585,7 @@ declare class HavenClient {
|
|
|
1506
1585
|
*/
|
|
1507
1586
|
discoverTools(options?: {
|
|
1508
1587
|
category?: string;
|
|
1588
|
+
search?: string;
|
|
1509
1589
|
rail?: 'x402' | 'mpp';
|
|
1510
1590
|
}): Promise<HavenCatalogEntry[]>;
|
|
1511
1591
|
/**
|
|
@@ -1987,7 +2067,7 @@ declare const toolDescriptions: {
|
|
|
1987
2067
|
readonly summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog — names, prices, and which pay tool to use next.";
|
|
1988
2068
|
readonly selectionGuidance: string;
|
|
1989
2069
|
readonly behavior: string;
|
|
1990
|
-
readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass
|
|
2070
|
+
readonly nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens (\"no more than 1 USDC\" → max_amount_human: \"1\") — never convert it to atomic units by hand (#1351).";
|
|
1991
2071
|
};
|
|
1992
2072
|
readonly sweep_delegate: {
|
|
1993
2073
|
readonly summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.";
|
|
@@ -2023,7 +2103,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
|
|
|
2023
2103
|
* this canonical string and asserts byte-for-byte equality, so the two copies
|
|
2024
2104
|
* cannot drift.
|
|
2025
2105
|
*/
|
|
2026
|
-
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the source of truth.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n (wallet, network) plus a readiness signal (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n `catalog_id`.\n2. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and\n
|
|
2106
|
+
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\nHosted tools run in the `mcp__haven__` namespace. Local signing tools run in\nthe `mcp__haven-signer__` namespace and keep the delegate key on this machine.\nTool results carry the exact next step (`next_action`, `next_tool`,\n`next_arguments`) \u2014 follow those fields first; the prose below is fallback\nand orientation, not the source of truth.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n then retry the original request.\n\n## Identity and budget\n\nDo not guess the wallet address, network, or budget.\n\nFor instant orientation at the start of a session, read the non-secret\n`agent.json` the connector wrote to your Haven credential directory (typically\n`~/.haven/agents/<agent-id>/agent.json` \u2014 if you don't know the agent id, list\n`~/.haven/agents/` to find the folder). It\nholds your agent id, Haven wallet address, network, and *configured* per-token\nbudget, and contains no keys \u2014 the fastest way to answer \"who am I and what may\nI spend\" with no round trip. If that file is absent (some setups don't write\nit), use the tools below instead.\n\nBefore any payment, confirm the *live remaining* budget with the tools \u2014\n`agent.json` shows the configured budget, not what is left after recent\nspending:\n\n- `mcp__haven__haven_get_agent` \u2014 the recommended first call: identity\n (wallet, network) plus a readiness signal (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n**Catalog purchases \u2014 the primary path for MCP merchants:**\n\n1. `mcp__haven__haven_discover_tools` to find a payable service and its\n `catalog_id`.\n2. `mcp__haven__haven_prepare_catalog_purchase` with `catalog_id` and a\n spending cap. A cap is REQUIRED on this tool and is best practice on every\n paid call below too \u2014 it caps what the LIVE merchant quote may charge,\n checked before any funding intent is created. Write it the way the user\n said it: `max_amount_human` is whole tokens, so \"no more than 1 USDC\" is\n `max_amount_human: \"1\"`. (`max_amount` is the atomic-unit form, where\n \"1\" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)\n3. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: `next_action`, `next_tool`,\n and `next_arguments` name the exact next call \u2014 act on those first; the\n prose in this section is fallback and debugging detail. If the catalog\n entry is missing or degraded, the response instead names\n `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name, arguments) as\n the manual fallback.\n\n**Signing:** `mcp__haven-signer__haven_sign_x402` with `payment_id` ONLY \u2014\nthe local signer fetches the exact signing bytes AND `payment_required`\nitself, so never relay `typed_data` or the 402 blob yourself. If the signer\nreports its fetched context carried no `payment_required` (older backend),\nre-call with `payment_required` added verbatim. Fallback for an older signer\nor backend: re-run the quote/prepare tool with the SAME `idempotency_key`\nplus `include_signing_payload=true`, then pass `payload_hash`,\n`x402_expected` (the nested `x402.expected` object), and\n`typed_data`/`typed_data_b64` through unchanged.\n\n**Settle:** `mcp__haven__haven_settle_mcp_tool` with `payment_id`,\n`signature`, and `payment_header` ONLY \u2014 Haven rehydrates the merchant call\ncontext (`merchant_url`, `tool_name`, `arguments`, `mcp_transport`)\nserver-side from `payment_id`. Pass those four fields explicitly only as a\nversion-skew fallback when Haven has no stored context for the id \u2014 both or\nnone together, never just one. If the settle result carries `settled: false`,\nfunding is queued for the user's approval \u2014 tell them and check status later,\ndo not re-pay.\n\nStep-by-step alternative (also key-safe; for an older signer or backend, or\nwhen you already have a merchant URL and tool name instead of a\n`catalog_id`): `mcp__haven__haven_pay_mcp_tool` then\n`mcp__haven-signer__haven_sign` \u2192 `mcp__haven__haven_submit` \u2192\n`mcp__haven-signer__haven_x402_sign_header` \u2192\n`mcp__haven__haven_complete_mcp_tool`. Pass `payment_required`,\n`arguments`, and `mcp_transport` verbatim from the quote/prepare result.\nThe returned `expires_at` is the signing window; if a tool returns\n`PAYMENT_WINDOW_EXPIRED`, re-run the same quote/prepare tool with the same\n`idempotency_key`. Do not call the merchant yourself \u2014 Haven completes the\nmerchant leg for you.\n\n**Direct transfer / non-MCP paywall:** `mcp__haven__haven_pay` with\nrecipient, amount, and token for a plain transfer. For an arbitrary,\nnon-MCP x402 paywall: `mcp__haven__haven_quote_x402` to get a quote, then\n`mcp__haven__haven_pay_x402_quote` \u2014 follow the result's guidance fields\nfirst, sign in the local Haven signer, and retry the original request only\nwhen the result says `retry_original_x402_request`.\n\n**Catalog tool arguments:** when `haven_discover_tools` returns\n`tool_arguments`, pass that object unchanged as the pay tool's\n`arguments` field (for example\n`tool_arguments: { \"tier\": \"50gb\" }` -> `arguments: { \"tier\": \"50gb\" }`).\n\n**Prices:** show the user the live price from the pay-tool result, never a\ncatalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. The pay-tool result's `amount` /\n`amount_atomic` is the amount Haven authorizes for the call \u2014 a ceiling the\nmerchant settles at or below \u2014 so present it as the most the user will pay.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n budget and is waiting for the user in Haven. Tell the user, then check\n status later.\n- `safe_to_continue: false` on a guidance block is the same signal in\n machine-readable form: stop and involve the user before calling anything\n else for this payment.\n- Never ask the user for private keys. Signing happens only in the local Haven\n signer; the hosted Haven tools never receive the signing key. If a tool\n reports a missing or invalid credential, tell the user to re-run the Haven\n setup command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. Branch on `code` when\npresent and surface `message` or `error` verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n Suggest the user add funds in the Haven dashboard.\n- `PRICE_EXCEEDS_MAX`: the live merchant price exceeded your cap. No funds\n moved; ask the user before retrying with a higher one.\n- `AMBIGUOUS_MAX_AMOUNT`: you sent both `max_amount` and\n `max_amount_human`. Nothing was contacted or spent \u2014 re-send with exactly\n one (`max_amount_human` for a cap the user stated in tokens).\n- `MAX_AMOUNT_UNCONVERTIBLE`: `max_amount_human` does not fit this quote's\n asset \u2014 unknown decimals, or more decimal places than the asset supports.\n Round the cap, or send an exact atomic `max_amount`.\n- `PAYMENT_WINDOW_EXPIRED`: re-run the quote/prepare tool with the same\n `idempotency_key`, then sign the fresh payload.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n Stop-and-sweep \u2014 stop retrying the merchant and use\n `mcp__haven__haven_sweep_delegate` to recover stranded delegate funds.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: funding confirmed on-chain, but the\n merchant never answered the paid retry. This is NOT proof of rejection \u2014 the\n merchant may still settle late. Verify-then-sweep, never a blind sweep:\n check `mcp__haven__haven_get_payment_status`, retry\n `mcp__haven__haven_complete_mcp_tool` ONCE, and only sweep with\n `mcp__haven__haven_sweep_delegate` if no settlement appears.\n- Budget exceeded: tell the user how much remains (from\n `mcp__haven__haven_get_allowances`) and that they can raise the budget in\n Haven.\n\n## Reporting after a purchase\n\nA settled `mcp__haven__haven_settle_mcp_tool` response carries\n`agent_summary.purchase_summary` and the remaining post-purchase allowance\nin `allowance` \u2014 report the product, Haven-derived payment/transaction\nfields, and what is left from those fields directly. `result` is optional\nraw merchant evidence; never use it to decide whether the purchase was paid.\nDo not call `haven_get_agent` or `haven_get_allowances` again just to\nreport a purchase you already made.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
|
|
2027
2107
|
/** Directory name for the installed skill folder. */
|
|
2028
2108
|
declare const SKILL_FOLDER_NAME = "haven-pay";
|
|
2029
2109
|
|
|
@@ -2061,7 +2141,7 @@ declare const SKILL_FOLDER_NAME = "haven-pay";
|
|
|
2061
2141
|
* package. A guard test in each package asserts exactly that against its own
|
|
2062
2142
|
* `package.json`, so the two cannot drift again silently.
|
|
2063
2143
|
*/
|
|
2064
|
-
declare const HAVEN_MINIMUM_NODE_VERSION = "
|
|
2144
|
+
declare const HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
|
|
2065
2145
|
/**
|
|
2066
2146
|
* Compare two Node versions. Negative when `left` is older.
|
|
2067
2147
|
*
|
|
@@ -2206,6 +2286,16 @@ declare function encodePaymentProof(receipt: {
|
|
|
2206
2286
|
payer?: string;
|
|
2207
2287
|
chainId?: number;
|
|
2208
2288
|
}): string;
|
|
2289
|
+
/**
|
|
2290
|
+
* Resolve a token symbol from a contract address.
|
|
2291
|
+
*
|
|
2292
|
+
* Checks all supported chains. For chain-specific resolution,
|
|
2293
|
+
* pass the optional `network` CAIP-2 string (e.g. "eip155:100").
|
|
2294
|
+
*/
|
|
2295
|
+
declare function resolveTokenFromAddress(address: string, network?: string): {
|
|
2296
|
+
symbol: string;
|
|
2297
|
+
decimals: number;
|
|
2298
|
+
} | null;
|
|
2209
2299
|
|
|
2210
2300
|
declare function parseMachinePaymentChallenge(response: Response): MachinePaymentChallenge;
|
|
2211
2301
|
declare function parseMachinePaymentChallengeResponse(response: Response): Promise<MachinePaymentChallenge>;
|
|
@@ -2278,4 +2368,4 @@ declare function discoverMerchantMcpUrl(inputUrl: string): Promise<string | null
|
|
|
2278
2368
|
/** Trailing-slash/percent-case echoes compare equal; unparseable never does. */
|
|
2279
2369
|
declare function sameUrl(a: string, b: string): boolean;
|
|
2280
2370
|
|
|
2281
|
-
export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type ClaudeTool, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, MerchantTimeoutError, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
|
|
2371
|
+
export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, type AgentNextStep, type AgentPaymentEnumSchema, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, type AgentPaymentSummary, type AgentPaymentWarning, AgentPaymentWarningCode, type AgentPurchaseSummary, type ClaudeTool, DISCOVERY_MAX_BYTES, HAVEN_MINIMUM_NODE_VERSION, HAVEN_SKILL_MD, type HavenAgent, type HavenAgentAllowanceSummary, type HavenAgentReadiness, type HavenAgentSummary, type HavenAllowance, type HavenAllowanceSummary, HavenApiError, type HavenCatalogEntry, HavenClient, type HavenClientConfig, HavenError, type HavenPaymentReceipt, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, MERCHANT_DISCOVERY_PATHS, type MachinePaymentChallenge, type MachinePaymentRail, type MachinePaymentReceipt, MerchantTimeoutError, type MppAuthorizationOptions, type MppQuote, type MppResumeState, type OpenAITool, type PaymentFee, type PaymentIntent, type PaymentNextAction, type PaymentPhase, type PaymentReceipt, type PaymentRequest, type PaymentResult, type PaymentResumeState, type PaymentStatus, type PaymentStatusResult, type PendingApproval, type PostPurchaseAllowanceSummary, RECEIPT_VERSION, type ReceiptVerification, type ResumeAuthorizedMppInput, type ResumeAuthorizedX402Input, type ResumeMppPaymentInput, type ResumeX402PaymentInput, SIGNER_UPDATE_FALLBACK, SKILL_FOLDER_NAME, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, type SharedToolKey, type SignData, SignerRefusalCode, type SweepAuthorization, type SweepEip712Domain, type SweepEntry, type SweepExpectedAuth, type SweepPreparation, type SweepPrepareResponse, type SweepResult, type SweepSubmitResponse, type SweepSubmitResult, type SweepTypedData, TRANSFER_WITH_AUTHORIZATION_TYPES, type ToolDescription, type UnsupportedNodeVersionMessageOptions, type X402AuthorizationOptions, type X402ExpectedAuth, type X402ExpectedContext, type X402Intent, type X402McpCallContext, type X402McpTransport, type X402MerchantCallContext, type X402PaymentOption, type X402PaymentRequired, type X402Quote, type X402Receipt, type X402RequestSnapshot, type X402ResumeState, X402UnexpectedStatusError, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, addressFromKey, buildMachinePaymentIdempotencyKey, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, composeDescription, decodeBase64Json, decodeBase64Utf8, discoverMerchantMcpUrl, encodeBase64Json, encodeBase64Utf8, encodeMachinePaymentProof, encodePaymentProof, havenTools, isSupportedNodeVersion, isSweepableChain, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, resolveTokenFromAddress, sameUrl, selectPaymentOption, selectStandardPaymentOption, signHash, signUserOpTypedDataForDelegation, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, toolDescriptions, unsupportedNodeVersionMessage, verifyPaymentReceipt, verifySignature, x402AuthorizationAmount };
|