@haven_ai/sdk 0.0.0-dev.202609291912.efd0772 → 0.0.0-dev.202609291949.4e52d4b
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/{base64-DyOPH887.d.cts → base64-VVxgYQAD.d.cts} +1 -1
- package/dist/{base64-DyOPH887.d.ts → base64-VVxgYQAD.d.ts} +1 -1
- package/dist/{chunk-MJ2IMB5H.cjs → chunk-J6SS36ZD.cjs} +189 -3
- package/dist/chunk-J6SS36ZD.cjs.map +1 -0
- package/dist/{chunk-6JQT7HNR.js → chunk-S35ZUPXQ.js} +179 -6
- package/dist/chunk-S35ZUPXQ.js.map +1 -0
- package/dist/edge.cjs +88 -88
- package/dist/edge.cjs.map +1 -1
- package/dist/edge.d.cts +172 -3
- package/dist/edge.d.ts +172 -3
- package/dist/edge.js +4 -53
- package/dist/edge.js.map +1 -1
- package/dist/index.cjs +220 -130
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +97 -7
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/dist/chunk-6JQT7HNR.js.map +0 -1
- package/dist/chunk-MJ2IMB5H.cjs.map +0 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { R as RawPaymentParties, H as HavenClientConfig, a as HavenClientUpdate, P as PaymentRequest, b as PaymentResult, c as PaymentIntent, X as X402PaymentRequired, d as X402AuthorizationOptions, e as X402Intent, f as PaymentStatusResult, g as HavenAgent, h as HavenAgentSummary, S as SweepResult, i as SweepPrepareResponse, j as SweepAuthorization, k as SweepSubmitResponse, l as HavenAllowanceSummary, m as HavenBalanceCoverage, n as PostPurchaseAllowanceSummary, A as AgentPaymentWarning, o as HavenCatalogEntry, p as HavenCatalogSubmission, q as HavenPaymentReceipt, r as HavenPaymentReceiptsPage, O as OpenTaskBudgetResult, s as HavenTaskBudget, T as TaskBudgetSignContext, t as SubmitTaskBudgetResult, C as CloseTaskBudgetResult, u as PaymentResumeState, v as X402Receipt, w as X402Quote, x as X402Erc7710Settlement, y as X402McpCallContext, z as SignData, B as ResumeAuthorizedX402Input, D as ResumeX402PaymentInput, E as X402ResumeState, F as X402McpTransport, G as X402MerchantCallContext, I as HavenError } from './base64-
|
|
2
|
-
export { J as AGENT_PAYMENT_FAILURE_CODE_VALUES, K as AGENT_PAYMENT_NEXT_ACTION_VALUES, L as AGENT_PAYMENT_PHASE_VALUES, M as AGENT_PAYMENT_RAIL_VALUES, N as AgentNextStep, Q as AgentPaymentEnumSchema, U as AgentPaymentFailureCode, V as AgentPaymentFailureCodeDescriptions, W as AgentPaymentFailureCodeSchema, Y as AgentPaymentNextAction, Z as AgentPaymentNextActionDescriptions, _ as AgentPaymentNextActionSchema, $ as AgentPaymentPhase, a0 as AgentPaymentPhaseDescriptions, a1 as AgentPaymentPhaseSchema, a2 as AgentPaymentRail, a3 as AgentPaymentRailDescriptions, a4 as AgentPaymentRailSchema, a5 as AgentPaymentSummary, a6 as AgentPaymentWarningCode, a7 as AgentPurchaseSummary, a8 as CONNECTOR_PACKAGE_NAME, a9 as CatalogSubmissionAccepted, aa as DEFAULT_CONFIRMATION_TIMEOUT_MS, ab as DEFAULT_NEXT_TOOL_BY_ACTION, ac as DIRECT_SIGN_CONTEXT_VERSION, ad as ENTRY_POINT_V07, ae as ERC7710_ASSET_TRANSFER_METHOD, af as HAVEN_CLIENT_HEADER, ag as HAVEN_CONNECTOR_CHANNEL, ah as HAVEN_MINIMUM_NODE_VERSION, ai as HYBRID_DELEGATOR_DOMAIN_NAME, aj as HYBRID_DELEGATOR_DOMAIN_VERSION, ak as HavenAgentAllowanceSummary, al as HavenAgentReadiness, am as HavenAllowance, an as HavenApiError, ao as HavenCatalogMerchant, ap as HavenListScope, aq as HavenPaymentStateError, ar as HavenSigningError, as as HavenTimeoutError, at as HavenTypedDataRefusedError, au as HavenUnsupportedSignerVersionError, av as HavenUserOpBindingError, aw as HavenZeroSettlementHashError, ax as MAX_TASK_BUDGET_TTL_SECONDS, ay as MachinePaymentRail, az as MerchantTimeoutError, aA as NEXT_TOOL_SERVER_NAMES, aB as NEXT_TOOL_SERVER_ROLES, aC as NextStep, aD as NextStepArguments, aE as NextStepHandoff, aF as NextStepInput, aG as NextStepTarget, aH as NextStepTargets, aI as NextToolServerRole, aJ as PACKED_USER_OPERATION_FIELDS, aK as PaymentFee, aL as PaymentNextAction, aM as PaymentPhase, aN as PaymentStatus, aO as ROOT_AUTHORITY, aP as SDK_CLIENT_IDENTITY, aQ as SDK_VERSION, aR as SIGNER_UPDATE_FALLBACK, aS as SWEEP_BASE_CHAIN_ID, aT as SWEEP_BASE_SEPOLIA_CHAIN_ID, aU as SWEEP_BASE_SEPOLIA_USDC_ADDRESS, aV as SWEEP_BASE_USDC_ADDRESS, aW as SettlementChildExpectation, aX as SignerRefusalCode, aY as SweepConfirmation, aZ as SweepEip712Domain, a_ as SweepEntry, a$ as SweepExpectedAuth, b0 as SweepPreparation, b1 as SweepSubmitResult, b2 as SweepTypedData, b3 as TASK_SIGN_CONTEXT_VERSION, b4 as TRANSFER_WITH_AUTHORIZATION_TYPES, b5 as TYPED_DATA_NOT_ALLOWED, b6 as TaskBudgetCloseExpectation, b7 as TaskChildExpectation, b8 as TaskChildTypedData, b9 as UnsupportedNodeVersionMessageOptions, ba as X402AlreadySettledError, bb as X402Erc7710AlreadySettledError, bc as X402ExpectedAuth, bd as X402ExpectedContext, be as X402PaymentHeaderContext, bf as X402PaymentHeaderValidationError, bg as X402PaymentOption, bh as X402RequestSnapshot, bi as X402SchemeSelection, bj as X402TaskBudgetMismatchError, bk as X402UnexpectedStatusError, bl as X402_LEGACY_PAYMENT_HEADER_NAME, bm as X402_MAX_AUTHORIZATION_WINDOW_SECONDS, bn as X402_PAYMENT_HEADER_NAME, bo as X402_PAYMENT_HEADER_NAMES_SENT, bp as X402_PAYMENT_REQUIRED_HEADER_NAME, bq as X402_PAYMENT_RESPONSE_HEADER_NAME, br as X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, bs as assertBoundDirectPaymentUserOp, bt as assertOwnTaskBudgetCloseUserOp, bu as assertOwnTaskChild, bv as assertUserOpTypedDataBinding, bw as buildSweepAuthorizationMessage, bx as buildSweepTypedData, by as buildX402ExpectedMessage, bz as compareNodeVersions, bA as connectorRerunCommand, bB as connectorSpec, bC as connectorUpgradeCommand, bD as createNextStepBuilder, bE as decodeBase64Json, bF as decodeBase64Utf8, bG as defaultNextToolFor, bH as deriveDelegateAccountAddress, bI as encodeBase64Json, bJ as encodeBase64Utf8, bK as encodePaymentProof, bL as hashDelegation, bM as havenClientIdentity, bN as isConnectorChannel, bO as isErc7710Option, bP as isPackedUserOperationTypedData, bQ as isSupportedNodeVersion, bR as isSweepableChain, bS as isTaskChildTypedData, bT as normalizePaymentRequired, bU as packedUserOperationHash, bV as parseNextTool, bW as parsePaymentRequired, bX as parsePaymentRequiredResponse, bY as readClientUpdate, bZ as renderNextTool, b_ as resolveConnectorChannel, b$ as resolveTokenBySymbol, c0 as resolveTokenFromAddress, c1 as selectErc7710PaymentOption, c2 as selectPaymentOption, c3 as selectStandardPaymentOption, c4 as selectX402SettlementScheme, c5 as signerUpdateFallback, c6 as sweepUsdcAddress, c7 as sweepUsdcDomain, c8 as toStandardPaymentRequirements, c9 as unsupportedNodeVersionMessage, ca as validateStandardX402PaymentHeader, cb as verifySettlementChild, cc as x402AssetTransferMethod, cd as x402AuthorizationAmount, ce as x402FacilitatorAddresses, cf as x402V2PaymentEnvelope } from './base64-
|
|
1
|
+
import { R as RawPaymentParties, H as HavenClientConfig, a as HavenClientUpdate, P as PaymentRequest, b as PaymentResult, c as PaymentIntent, X as X402PaymentRequired, d as X402AuthorizationOptions, e as X402Intent, f as PaymentStatusResult, g as HavenAgent, h as HavenAgentSummary, S as SweepResult, i as SweepPrepareResponse, j as SweepAuthorization, k as SweepSubmitResponse, l as HavenAllowanceSummary, m as HavenBalanceCoverage, n as PostPurchaseAllowanceSummary, A as AgentPaymentWarning, o as HavenCatalogEntry, p as HavenCatalogSubmission, q as HavenPaymentReceipt, r as HavenPaymentReceiptsPage, O as OpenTaskBudgetResult, s as HavenTaskBudget, T as TaskBudgetSignContext, t as SubmitTaskBudgetResult, C as CloseTaskBudgetResult, u as PaymentResumeState, v as X402Receipt, w as X402Quote, x as X402Erc7710Settlement, y as X402McpCallContext, z as SignData, B as ResumeAuthorizedX402Input, D as ResumeX402PaymentInput, E as X402ResumeState, F as X402McpTransport, G as X402MerchantCallContext, I as HavenError } from './base64-VVxgYQAD.cjs';
|
|
2
|
+
export { J as AGENT_PAYMENT_FAILURE_CODE_VALUES, K as AGENT_PAYMENT_NEXT_ACTION_VALUES, L as AGENT_PAYMENT_PHASE_VALUES, M as AGENT_PAYMENT_RAIL_VALUES, N as AgentNextStep, Q as AgentPaymentEnumSchema, U as AgentPaymentFailureCode, V as AgentPaymentFailureCodeDescriptions, W as AgentPaymentFailureCodeSchema, Y as AgentPaymentNextAction, Z as AgentPaymentNextActionDescriptions, _ as AgentPaymentNextActionSchema, $ as AgentPaymentPhase, a0 as AgentPaymentPhaseDescriptions, a1 as AgentPaymentPhaseSchema, a2 as AgentPaymentRail, a3 as AgentPaymentRailDescriptions, a4 as AgentPaymentRailSchema, a5 as AgentPaymentSummary, a6 as AgentPaymentWarningCode, a7 as AgentPurchaseSummary, a8 as CONNECTOR_PACKAGE_NAME, a9 as CatalogSubmissionAccepted, aa as DEFAULT_CONFIRMATION_TIMEOUT_MS, ab as DEFAULT_NEXT_TOOL_BY_ACTION, ac as DIRECT_SIGN_CONTEXT_VERSION, ad as ENTRY_POINT_V07, ae as ERC7710_ASSET_TRANSFER_METHOD, af as HAVEN_CLIENT_HEADER, ag as HAVEN_CONNECTOR_CHANNEL, ah as HAVEN_MINIMUM_NODE_VERSION, ai as HYBRID_DELEGATOR_DOMAIN_NAME, aj as HYBRID_DELEGATOR_DOMAIN_VERSION, ak as HavenAgentAllowanceSummary, al as HavenAgentReadiness, am as HavenAllowance, an as HavenApiError, ao as HavenCatalogMerchant, ap as HavenListScope, aq as HavenPaymentStateError, ar as HavenSigningError, as as HavenTimeoutError, at as HavenTypedDataRefusedError, au as HavenUnsupportedSignerVersionError, av as HavenUserOpBindingError, aw as HavenZeroSettlementHashError, ax as MAX_TASK_BUDGET_TTL_SECONDS, ay as MachinePaymentRail, az as MerchantTimeoutError, aA as NEXT_TOOL_SERVER_NAMES, aB as NEXT_TOOL_SERVER_ROLES, aC as NextStep, aD as NextStepArguments, aE as NextStepHandoff, aF as NextStepInput, aG as NextStepTarget, aH as NextStepTargets, aI as NextToolServerRole, aJ as PACKED_USER_OPERATION_FIELDS, aK as PaymentFee, aL as PaymentNextAction, aM as PaymentPhase, aN as PaymentStatus, aO as ROOT_AUTHORITY, aP as SDK_CLIENT_IDENTITY, aQ as SDK_VERSION, aR as SIGNER_UPDATE_FALLBACK, aS as SWEEP_BASE_CHAIN_ID, aT as SWEEP_BASE_SEPOLIA_CHAIN_ID, aU as SWEEP_BASE_SEPOLIA_USDC_ADDRESS, aV as SWEEP_BASE_USDC_ADDRESS, aW as SettlementChildExpectation, aX as SignerRefusalCode, aY as SweepConfirmation, aZ as SweepEip712Domain, a_ as SweepEntry, a$ as SweepExpectedAuth, b0 as SweepPreparation, b1 as SweepSubmitResult, b2 as SweepTypedData, b3 as TASK_SIGN_CONTEXT_VERSION, b4 as TRANSFER_WITH_AUTHORIZATION_TYPES, b5 as TYPED_DATA_NOT_ALLOWED, b6 as TaskBudgetCloseExpectation, b7 as TaskChildExpectation, b8 as TaskChildTypedData, b9 as UnsupportedNodeVersionMessageOptions, ba as X402AlreadySettledError, bb as X402Erc7710AlreadySettledError, bc as X402ExpectedAuth, bd as X402ExpectedContext, be as X402PaymentHeaderContext, bf as X402PaymentHeaderValidationError, bg as X402PaymentOption, bh as X402RequestSnapshot, bi as X402SchemeSelection, bj as X402TaskBudgetMismatchError, bk as X402UnexpectedStatusError, bl as X402_LEGACY_PAYMENT_HEADER_NAME, bm as X402_MAX_AUTHORIZATION_WINDOW_SECONDS, bn as X402_PAYMENT_HEADER_NAME, bo as X402_PAYMENT_HEADER_NAMES_SENT, bp as X402_PAYMENT_REQUIRED_HEADER_NAME, bq as X402_PAYMENT_RESPONSE_HEADER_NAME, br as X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, bs as assertBoundDirectPaymentUserOp, bt as assertOwnTaskBudgetCloseUserOp, bu as assertOwnTaskChild, bv as assertUserOpTypedDataBinding, bw as buildSweepAuthorizationMessage, bx as buildSweepTypedData, by as buildX402ExpectedMessage, bz as compareNodeVersions, bA as connectorRerunCommand, bB as connectorSpec, bC as connectorUpgradeCommand, bD as createNextStepBuilder, bE as decodeBase64Json, bF as decodeBase64Utf8, bG as defaultNextToolFor, bH as deriveDelegateAccountAddress, bI as encodeBase64Json, bJ as encodeBase64Utf8, bK as encodePaymentProof, bL as hashDelegation, bM as havenClientIdentity, bN as isConnectorChannel, bO as isErc7710Option, bP as isPackedUserOperationTypedData, bQ as isSupportedNodeVersion, bR as isSweepableChain, bS as isTaskChildTypedData, bT as normalizePaymentRequired, bU as packedUserOperationHash, bV as parseNextTool, bW as parsePaymentRequired, bX as parsePaymentRequiredResponse, bY as readClientUpdate, bZ as renderNextTool, b_ as resolveConnectorChannel, b$ as resolveTokenBySymbol, c0 as resolveTokenFromAddress, c1 as selectErc7710PaymentOption, c2 as selectPaymentOption, c3 as selectStandardPaymentOption, c4 as selectX402SettlementScheme, c5 as signerUpdateFallback, c6 as sweepUsdcAddress, c7 as sweepUsdcDomain, c8 as toStandardPaymentRequirements, c9 as unsupportedNodeVersionMessage, ca as validateStandardX402PaymentHeader, cb as verifySettlementChild, cc as x402AssetTransferMethod, cd as x402AuthorizationAmount, ce as x402FacilitatorAddresses, cf as x402V2PaymentEnvelope } from './base64-VVxgYQAD.cjs';
|
|
3
3
|
import 'x402/types';
|
|
4
4
|
import 'viem';
|
|
5
5
|
|
|
@@ -1004,12 +1004,12 @@ declare const toolDescriptions: {
|
|
|
1004
1004
|
readonly payX402OneShot: {
|
|
1005
1005
|
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.";
|
|
1006
1006
|
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.";
|
|
1007
|
-
readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.";
|
|
1007
|
+
readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. On the EIP-3009 path, when the owner opted this agent in, the same retry also carries the agent-signed buyer tax declaration in X-Tax-Declaration — signed by the same local delegate key, sent to the seller only, and omitted when the declaration is not available or on the direct-settlement (erc7710) scheme. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.";
|
|
1008
1008
|
readonly nextActionGuidance: string;
|
|
1009
1009
|
};
|
|
1010
1010
|
readonly resumeX402: {
|
|
1011
1011
|
readonly summary: "Resume an x402 payment whose Haven-side authorization already succeeded but whose merchant retry did not complete.";
|
|
1012
|
-
readonly behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). No new Haven payment is created.";
|
|
1012
|
+
readonly behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). On the EIP-3009 scheme the retry also carries the agent-signed buyer tax declaration in X-Tax-Declaration when the owner opted this agent in and the declaration is available — signed locally by the same delegate key, sent to the seller only. No new Haven payment is created.";
|
|
1013
1013
|
readonly nextActionGuidance: string;
|
|
1014
1014
|
};
|
|
1015
1015
|
readonly getPaymentStatus: {
|
|
@@ -1132,7 +1132,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
|
|
|
1132
1132
|
* live sibling constant not pulled in here; if it ever is, this applies to it
|
|
1133
1133
|
* too (design review, #2537).
|
|
1134
1134
|
*/
|
|
1135
|
-
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules, and set Haven up when it is not yet connected. Use when the user asks to send, pay, tip, or transfer crypto; when a request hits an HTTP 402 (x402) paywall; or when they ask to create a Haven account, create an agent, or connect one.\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; a payment above the remaining budget is declined \u2014\nnothing is paid past the rules the user set.\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.\nThat namespacing is Claude-family; other runtimes name the servers by their\nown config keys (Codex: `haven`, `haven_signer`). Tool results carry the\nexact next step (`next_action`, `next_tool`, `next_arguments`, plus the\nruntime-neutral `next_tool_server` + `next_tool_name` + `next_tool_server_role`\n\u2014 the bare tool name on that logical server, whatever your runtime calls it).\nWhen no tool follows, `next_tool` is absent and `next_tool_omitted_reason`\nsays why; that is a complete answer.\nFollow those fields first; the prose below is fallback and orientation, not\nthe 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## Onboarding and setup\n\nYou are in this mode when there is no Haven agent credential on this machine,\nor when your user asks you to create a Haven account, create an agent, or\nconnect one \u2014 for themselves or for someone else.\n\n**None of the tools below creates authority.** They spend a budget a human\nalready signed. There is no tool here that opens an account, mints a\ncredential, or approves a budget, so reaching for one of them to \"set Haven\nup\" cannot work; the steps are the ones in this section instead.\n\nStart by reading `/for-agents.md` on the Haven host \u2014 the origin of the\n`api_url` in your `agent.json` if you have one, otherwise the host your user\nnames. It is the full runbook: six steps, which four are your user's, and what\nto say at each hand-off.\n\nTwo of those steps you can do yourself, from the shell with `@haven_ai/cli`\n(installs the `haven` command):\n\n- `haven login` \u2014 a device-code browser flow. It prints a code and a link\n for your user to approve, so you never see or ask for their password. What\n the session can reach is an allow-list, not your user's full authority: it\n creates and manages agents and reads the account, and it cannot approve a\n budget, rotate a key, change a signer or move money \u2014 those are your user's.\n- `haven agents connect` with `--name`, `--budget`, `--token` and\n `--period` \u2014 creates a connection setup and prints two things: the\n connector command the backend built, and the approval link to give your user.\n Add `--run` to execute that command here as a child process.\n- `haven wallets funding` \u2014 prints the paste-ready funding instruction: what\n to send, to which address, on which chain. Read the chain from there rather\n than assuming one. `--wait` polls until the account counts as funded.\n\n**Four steps are your user's, and each one needs a human:** create the account\nand its passkey, fund the wallet, approve every agent's budget, and rotate a\ncredential. You can compose the funding message for them with\n`haven wallets funding`, but you cannot send the money \u2014 that transfer is\ntheirs, from a wallet you have no access to.\n\nRunning the connector command is the step that wires this machine to the new\nagent \u2014 the command `haven agents connect` printed, or the one your user\npasted you from the dashboard. Three rules bind you while you do it, quoted\nunchanged from the setup prompt your user is also holding so the two copies\ncannot drift into contradicting each other. They are written in your user's\nvoice, so read them accordingly: \"me\" and \"I\" below are your user, never\nHaven, and \"the command above\" is that connector command, not anything printed\nin this file. The first rule outranks anything else you were about to do next:\n\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- If the connector refuses with wiring_collision, this machine is already wired to a different agent: relay that refusal to me with the superseded_agent_ids and suggested_name it carries, and let me choose whether to replace the existing wiring or add this agent alongside it. Never pick for me by adding --replace or --name yourself.\n\nDo not print private keys, API keys, credential file contents, or config secrets in chat or logs.\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 `spend_authority_readiness` (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot. That signal\n covers hosted identity and on-chain spend authority only \u2014 it cannot see the\n local signer; the signer is verified by calling any signer tool.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n- `mcp__haven__haven_check_funds` \u2014 whether the account actually HOLDS at\n least a given amount of a token. Allowance answers above say what you are\n permitted to spend; this one says whether the money is really there,\n answered as `covered` true/false/null \u2014 never as a balance. On\n `covered: false`, stop and tell the user the account is short; on\n `covered: null` (the chain read failed), treat it as unverifiable rather\n than as absence.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is declined before any money moves \u2014 tell the user; they can raise\nthe budget in the Haven dashboard, or wait for the period reset.\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. If the user needs the live price before authorizing a cap, call\n `mcp__haven__haven_quote_catalog_purchase` with `catalog_id`. It is\n read-only and informational only: it never reserves a price or creates a\n payment. Tell the user its `amount` / `amount_atomic`, then choose a cap.\n3. `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.)\n4. 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 row is a plain-HTTP x402 paywall (no MCP tool metadata), the response\n instead names `mcp__haven__haven_quote_x402` with the entry's resource\n URL as `url`. If an MCP row is degraded or has no tool name, the response\n instead names `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name,\n arguments) as the manual fallback.\n\n**Signing:** which signer tool to call depends on the settlement scheme the\nprepare/pay response already named as `next_tool` \u2014 follow that field, never\nhard-code a choice. **erc7710** (direct settlement \u2014 chosen per merchant when\nits 402 advertises `assetTransferMethod: \"erc7710\"` AND your account is on\nthe delegation rail; never a blanket default): `mcp__haven-signer__haven_sign`\nwith `payment_id` ONLY; the signer fetches the settlement child itself.\n**EIP-3009** (the bridge \u2014 used otherwise, whenever the merchant offers a\nstandard entry): `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. A merchant\nthat advertises ONLY erc7710 against an account that is NOT on the\ndelegation rail is refused outright \u2014 it does not fall back to EIP-3009. If\nthe signer reports its fetched context carried no `payment_required` (older\nbackend), re-call with `payment_required` added verbatim. Fallback for an\nolder signer or backend: re-run the quote/prepare tool with the SAME\n`idempotency_key` plus `include_signing_payload=true`, then pass\n`payload_hash`, `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` and\n`signature` always. On **erc7710**, pass no `payment_header` \u2014 Haven\nassembles it at settle, so there is nothing to build locally and no funding\ntransaction to wait for. On **EIP-3009**, also pass `payment_header` (from\n`haven_sign_x402`) ONLY. Either way 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. On **EIP-3009**, `settled: false` means\nfunding has not confirmed; on **erc7710** it means the merchant delivered but\nsettlement is not yet verified. Either way, follow the result's guidance\nfields and do 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`): if the user needs the live price before choosing a cap, first\ncall `mcp__haven__haven_quote_mcp_tool` with that merchant URL, tool name,\nand arguments. It is informational only; then call\n`mcp__haven__haven_pay_mcp_tool` with the same inputs and the explicit cap.\nThe paid call always obtains a fresh quote before it creates any intent. Then\ncontinue `mcp__haven__haven_pay_mcp_tool` \u2192\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`. Call that last step with\n`payment_id` and the signer's `payment_header` ONLY. It does not take\n`payment_required`: Haven rehydrates the merchant call context\n(`merchant_url`, `tool_name`, `arguments`, `mcp_transport`) and the\n402 server-side from `payment_id`, exactly as at settle. Pass that context\nexplicitly only as a version-skew fallback when Haven has no stored context\nfor the id \u2014 `merchant_url` and `tool_name` both or none together, never\njust one.\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\n`to`, `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 and sign in the local Haven signer. On THIS path Haven does not talk to\nthe merchant: `mcp__haven-signer__haven_sign_x402` returns both\n`signature` and `payment_header`; relay `signature` with\n`mcp__haven__haven_submit`, then retry the paywalled URL yourself with\n`payment_header`. Do not pass that call's `x402_binding` to\n`mcp__haven-signer__haven_x402_sign_header` \u2014 the one-shot already spent it\nbuilding the header, so the call can only refuse. Then tell Haven what the\nmerchant answered: `mcp__haven__haven_report_x402_outcome` with the\n`payment_id`, `outcome` (`\"accepted\"` for a 2xx, else `\"rejected\"`)\nand the `merchant_status` you got. Because Haven never contacted that\nmerchant, this is the only way it can learn the purchase failed \u2014 without it a\nfailed purchase reads as complete for fifteen minutes. If the merchant's\n`PAYMENT-RESPONSE` header names a `transaction`, also pass it to\n`mcp__haven__haven_report_settlement_evidence` (`payment_id`,\n`settlement_tx_hash`): Haven verifies it on-chain, and the receipt then shows\nthe merchant's settlement, not only the funding transaction. (The SDK's own\n`haven_pay_x402` tool does perform the merchant retry itself; that tool is\nnot part of the hosted MCP surface.) If the process\ncrashes after payment, a later `mcp__haven__haven_get_payment_status` call\nmay report `nextAction: 'retry_original_x402_request'` \u2014 only then call\n`mcp__haven__haven_resume_x402_payment` with the preserved resume state or\npayment id, instead of paying again.\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 a read-only quote or the pay-tool\nresult, never a catalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. A read-only quote is informational\nonly and does not reserve a price; the later paid call re-quotes and enforces\nthe cap. The pay-tool result's `amount` / `amount_atomic` is the merchant's\nown quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay. It is a price, not an approval:\nthe payment goes through only if it also fits the cap you set and the on-chain\nbudget the user signed, which is enforced on-chain rather than by Haven.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on in-flight payments. Do not poll in a tight loop.\n\n## Declines and stop signals\n\n- A payment outside the agent's rules \u2014 above the remaining budget, wrong\n recipient, or expired budget \u2014 is declined before any money moves. Nothing\n is queued; tell the user, who can raise the budget in Haven.\n- `safe_to_continue: false` on a guidance block is a stop 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 connector command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. A failure carries the same\n`next_action` / `next_tool` / `next_arguments` / `next_tool_omitted_reason`\nfields a success does; follow them first, then branch on `code` and surface\n`message` or `error` verbatim. Common cases:\n\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_NOT_READY`: the merchant refused the quote with its own\n \"cannot settle right now\" signal (a 503 `merchant_not_ready` with a\n `reason_code`) instead of a 402. No payment was created. Tell the user;\n retry later (the message carries `retry_after_s` when the merchant gave\n one) \u2014 this is not a wrong or broken endpoint.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n On eip3009 (`rail` not `erc7710`): Stop-and-sweep \u2014 stop retrying the\n merchant and use `mcp__haven__haven_sweep_delegate` to recover stranded\n delegate funds. On erc7710 there is no funding leg and nothing to sweep:\n follow the message \u2014 it says whether the merchant declined to settle\n (re-quote later) or whether to check `haven_get_payment_status` after\n the payment window first.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: the merchant never answered the paid\n retry. This is NOT proof of rejection \u2014 the merchant may still settle late.\n On eip3009 (`rail` not `erc7710`), funding confirmed on-chain: Verify-then-sweep,\n never a blind sweep \u2014 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. On erc7710\n there is no funding leg and nothing to sweep, and\n `mcp__haven__haven_complete_mcp_tool` has no erc7710 branch (it refuses a\n submitted intent) \u2014 do not retry it: the merchant may still redeem the\n settlement authorization within the payment window, so check\n `mcp__haven__haven_get_payment_status` after that window and re-quote only\n if it shows no settlement.\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";
|
|
1135
|
+
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules, and set Haven up when it is not yet connected. Use when the user asks to send, pay, tip, or transfer crypto; when a request hits an HTTP 402 (x402) paywall; or when they ask to create a Haven account, create an agent, or connect one.\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; a payment above the remaining budget is declined \u2014\nnothing is paid past the rules the user set.\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.\nThat namespacing is Claude-family; other runtimes name the servers by their\nown config keys (Codex: `haven`, `haven_signer`). Tool results carry the\nexact next step (`next_action`, `next_tool`, `next_arguments`, plus the\nruntime-neutral `next_tool_server` + `next_tool_name` + `next_tool_server_role`\n\u2014 the bare tool name on that logical server, whatever your runtime calls it).\nWhen no tool follows, `next_tool` is absent and `next_tool_omitted_reason`\nsays why; that is a complete answer.\nFollow those fields first; the prose below is fallback and orientation, not\nthe 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## Onboarding and setup\n\nYou are in this mode when there is no Haven agent credential on this machine,\nor when your user asks you to create a Haven account, create an agent, or\nconnect one \u2014 for themselves or for someone else.\n\n**None of the tools below creates authority.** They spend a budget a human\nalready signed. There is no tool here that opens an account, mints a\ncredential, or approves a budget, so reaching for one of them to \"set Haven\nup\" cannot work; the steps are the ones in this section instead.\n\nStart by reading `/for-agents.md` on the Haven host \u2014 the origin of the\n`api_url` in your `agent.json` if you have one, otherwise the host your user\nnames. It is the full runbook: six steps, which four are your user's, and what\nto say at each hand-off.\n\nTwo of those steps you can do yourself, from the shell with `@haven_ai/cli`\n(installs the `haven` command):\n\n- `haven login` \u2014 a device-code browser flow. It prints a code and a link\n for your user to approve, so you never see or ask for their password. What\n the session can reach is an allow-list, not your user's full authority: it\n creates and manages agents and reads the account, and it cannot approve a\n budget, rotate a key, change a signer or move money \u2014 those are your user's.\n- `haven agents connect` with `--name`, `--budget`, `--token` and\n `--period` \u2014 creates a connection setup and prints two things: the\n connector command the backend built, and the approval link to give your user.\n Add `--run` to execute that command here as a child process.\n- `haven wallets funding` \u2014 prints the paste-ready funding instruction: what\n to send, to which address, on which chain. Read the chain from there rather\n than assuming one. `--wait` polls until the account counts as funded.\n\n**Four steps are your user's, and each one needs a human:** create the account\nand its passkey, fund the wallet, approve every agent's budget, and rotate a\ncredential. You can compose the funding message for them with\n`haven wallets funding`, but you cannot send the money \u2014 that transfer is\ntheirs, from a wallet you have no access to.\n\nRunning the connector command is the step that wires this machine to the new\nagent \u2014 the command `haven agents connect` printed, or the one your user\npasted you from the dashboard. Three rules bind you while you do it, quoted\nunchanged from the setup prompt your user is also holding so the two copies\ncannot drift into contradicting each other. They are written in your user's\nvoice, so read them accordingly: \"me\" and \"I\" below are your user, never\nHaven, and \"the command above\" is that connector command, not anything printed\nin this file. The first rule outranks anything else you were about to do next:\n\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- If the connector refuses with wiring_collision, this machine is already wired to a different agent: relay that refusal to me with the superseded_agent_ids and suggested_name it carries, and let me choose whether to replace the existing wiring or add this agent alongside it. Never pick for me by adding --replace or --name yourself.\n\nDo not print private keys, API keys, credential file contents, or config secrets in chat or logs.\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 `spend_authority_readiness` (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot. That signal\n covers hosted identity and on-chain spend authority only \u2014 it cannot see the\n local signer; the signer is verified by calling any signer tool.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n- `mcp__haven__haven_check_funds` \u2014 whether the account actually HOLDS at\n least a given amount of a token. Allowance answers above say what you are\n permitted to spend; this one says whether the money is really there,\n answered as `covered` true/false/null \u2014 never as a balance. On\n `covered: false`, stop and tell the user the account is short; on\n `covered: null` (the chain read failed), treat it as unverifiable rather\n than as absence.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is declined before any money moves \u2014 tell the user; they can raise\nthe budget in the Haven dashboard, or wait for the period reset.\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. If the user needs the live price before authorizing a cap, call\n `mcp__haven__haven_quote_catalog_purchase` with `catalog_id`. It is\n read-only and informational only: it never reserves a price or creates a\n payment. Tell the user its `amount` / `amount_atomic`, then choose a cap.\n3. `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.)\n4. 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 row is a plain-HTTP x402 paywall (no MCP tool metadata), the response\n instead names `mcp__haven__haven_quote_x402` with the entry's resource\n URL as `url`. If an MCP row is degraded or has no tool name, the response\n instead names `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name,\n arguments) as the manual fallback.\n\n**Signing:** which signer tool to call depends on the settlement scheme the\nprepare/pay response already named as `next_tool` \u2014 follow that field, never\nhard-code a choice. **erc7710** (direct settlement \u2014 chosen per merchant when\nits 402 advertises `assetTransferMethod: \"erc7710\"` AND your account is on\nthe delegation rail; never a blanket default): `mcp__haven-signer__haven_sign`\nwith `payment_id` ONLY; the signer fetches the settlement child itself.\n**EIP-3009** (the bridge \u2014 used otherwise, whenever the merchant offers a\nstandard entry): `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. A merchant\nthat advertises ONLY erc7710 against an account that is NOT on the\ndelegation rail is refused outright \u2014 it does not fall back to EIP-3009. If\nthe signer reports its fetched context carried no `payment_required` (older\nbackend), re-call with `payment_required` added verbatim. Fallback for an\nolder signer or backend: re-run the quote/prepare tool with the SAME\n`idempotency_key` plus `include_signing_payload=true`, then pass\n`payload_hash`, `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` and\n`signature` always. On **erc7710**, pass no `payment_header` \u2014 Haven\nassembles it at settle, so there is nothing to build locally and no funding\ntransaction to wait for. On **EIP-3009**, also pass `payment_header` (from\n`haven_sign_x402`) ONLY. Either way 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. On **EIP-3009**, `settled: false` means\nfunding has not confirmed; on **erc7710** it means the merchant delivered but\nsettlement is not yet verified. Either way, follow the result's guidance\nfields and do 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`): if the user needs the live price before choosing a cap, first\ncall `mcp__haven__haven_quote_mcp_tool` with that merchant URL, tool name,\nand arguments. It is informational only; then call\n`mcp__haven__haven_pay_mcp_tool` with the same inputs and the explicit cap.\nThe paid call always obtains a fresh quote before it creates any intent. Then\ncontinue `mcp__haven__haven_pay_mcp_tool` \u2192\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`. Call that last step with\n`payment_id` and the signer's `payment_header` ONLY. It does not take\n`payment_required`: Haven rehydrates the merchant call context\n(`merchant_url`, `tool_name`, `arguments`, `mcp_transport`) and the\n402 server-side from `payment_id`, exactly as at settle. Pass that context\nexplicitly only as a version-skew fallback when Haven has no stored context\nfor the id \u2014 `merchant_url` and `tool_name` both or none together, never\njust one.\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\n`to`, `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 and sign in the local Haven signer. On THIS path Haven does not talk to\nthe merchant: `mcp__haven-signer__haven_sign_x402` returns both\n`signature` and `payment_header`; relay `signature` with\n`mcp__haven__haven_submit`, then retry the paywalled URL yourself with\n`payment_header`. Do not pass that call's `x402_binding` to\n`mcp__haven-signer__haven_x402_sign_header` \u2014 the one-shot already spent it\nbuilding the header, so the call can only refuse. Then tell Haven what the\nmerchant answered: `mcp__haven__haven_report_x402_outcome` with the\n`payment_id`, `outcome` (`\"accepted\"` for a 2xx, else `\"rejected\"`)\nand the `merchant_status` you got. Because Haven never contacted that\nmerchant, this is the only way it can learn the purchase failed \u2014 without it a\nfailed purchase reads as complete for fifteen minutes. If the merchant's\n`PAYMENT-RESPONSE` header names a `transaction`, also pass it to\n`mcp__haven__haven_report_settlement_evidence` (`payment_id`,\n`settlement_tx_hash`): Haven verifies it on-chain, and the receipt then shows\nthe merchant's settlement, not only the funding transaction. (The SDK's own\n`haven_pay_x402` tool does perform the merchant retry itself; that tool is\nnot part of the hosted MCP surface.) On this SDK path, when the owner opted the\nagent in, the paid EIP-3009 retry also carries the agent-signed buyer tax\ndeclaration to the seller (`X-Tax-Declaration`, #3427) \u2014 signed locally by the\nsame delegate key, omitted when unavailable or on the erc7710 scheme; nothing\nfor you to sign or send. If the process\ncrashes after payment, a later `mcp__haven__haven_get_payment_status` call\nmay report `nextAction: 'retry_original_x402_request'` \u2014 only then call\n`mcp__haven__haven_resume_x402_payment` with the preserved resume state or\npayment id, instead of paying again.\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 a read-only quote or the pay-tool\nresult, never a catalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. A read-only quote is informational\nonly and does not reserve a price; the later paid call re-quotes and enforces\nthe cap. The pay-tool result's `amount` / `amount_atomic` is the merchant's\nown quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay. It is a price, not an approval:\nthe payment goes through only if it also fits the cap you set and the on-chain\nbudget the user signed, which is enforced on-chain rather than by Haven.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on in-flight payments. Do not poll in a tight loop.\n\n## Declines and stop signals\n\n- A payment outside the agent's rules \u2014 above the remaining budget, wrong\n recipient, or expired budget \u2014 is declined before any money moves. Nothing\n is queued; tell the user, who can raise the budget in Haven.\n- `safe_to_continue: false` on a guidance block is a stop 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 connector command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. A failure carries the same\n`next_action` / `next_tool` / `next_arguments` / `next_tool_omitted_reason`\nfields a success does; follow them first, then branch on `code` and surface\n`message` or `error` verbatim. Common cases:\n\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_NOT_READY`: the merchant refused the quote with its own\n \"cannot settle right now\" signal (a 503 `merchant_not_ready` with a\n `reason_code`) instead of a 402. No payment was created. Tell the user;\n retry later (the message carries `retry_after_s` when the merchant gave\n one) \u2014 this is not a wrong or broken endpoint.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n On eip3009 (`rail` not `erc7710`): Stop-and-sweep \u2014 stop retrying the\n merchant and use `mcp__haven__haven_sweep_delegate` to recover stranded\n delegate funds. On erc7710 there is no funding leg and nothing to sweep:\n follow the message \u2014 it says whether the merchant declined to settle\n (re-quote later) or whether to check `haven_get_payment_status` after\n the payment window first.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: the merchant never answered the paid\n retry. This is NOT proof of rejection \u2014 the merchant may still settle late.\n On eip3009 (`rail` not `erc7710`), funding confirmed on-chain: Verify-then-sweep,\n never a blind sweep \u2014 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. On erc7710\n there is no funding leg and nothing to sweep, and\n `mcp__haven__haven_complete_mcp_tool` has no erc7710 branch (it refuses a\n submitted intent) \u2014 do not retry it: the merchant may still redeem the\n settlement authorization within the payment window, so check\n `mcp__haven__haven_get_payment_status` after that window and re-quote only\n if it shows no settlement.\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";
|
|
1136
1136
|
/** Directory name for the installed skill folder. */
|
|
1137
1137
|
declare const SKILL_FOLDER_NAME = "haven-pay";
|
|
1138
1138
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { R as RawPaymentParties, H as HavenClientConfig, a as HavenClientUpdate, P as PaymentRequest, b as PaymentResult, c as PaymentIntent, X as X402PaymentRequired, d as X402AuthorizationOptions, e as X402Intent, f as PaymentStatusResult, g as HavenAgent, h as HavenAgentSummary, S as SweepResult, i as SweepPrepareResponse, j as SweepAuthorization, k as SweepSubmitResponse, l as HavenAllowanceSummary, m as HavenBalanceCoverage, n as PostPurchaseAllowanceSummary, A as AgentPaymentWarning, o as HavenCatalogEntry, p as HavenCatalogSubmission, q as HavenPaymentReceipt, r as HavenPaymentReceiptsPage, O as OpenTaskBudgetResult, s as HavenTaskBudget, T as TaskBudgetSignContext, t as SubmitTaskBudgetResult, C as CloseTaskBudgetResult, u as PaymentResumeState, v as X402Receipt, w as X402Quote, x as X402Erc7710Settlement, y as X402McpCallContext, z as SignData, B as ResumeAuthorizedX402Input, D as ResumeX402PaymentInput, E as X402ResumeState, F as X402McpTransport, G as X402MerchantCallContext, I as HavenError } from './base64-
|
|
2
|
-
export { J as AGENT_PAYMENT_FAILURE_CODE_VALUES, K as AGENT_PAYMENT_NEXT_ACTION_VALUES, L as AGENT_PAYMENT_PHASE_VALUES, M as AGENT_PAYMENT_RAIL_VALUES, N as AgentNextStep, Q as AgentPaymentEnumSchema, U as AgentPaymentFailureCode, V as AgentPaymentFailureCodeDescriptions, W as AgentPaymentFailureCodeSchema, Y as AgentPaymentNextAction, Z as AgentPaymentNextActionDescriptions, _ as AgentPaymentNextActionSchema, $ as AgentPaymentPhase, a0 as AgentPaymentPhaseDescriptions, a1 as AgentPaymentPhaseSchema, a2 as AgentPaymentRail, a3 as AgentPaymentRailDescriptions, a4 as AgentPaymentRailSchema, a5 as AgentPaymentSummary, a6 as AgentPaymentWarningCode, a7 as AgentPurchaseSummary, a8 as CONNECTOR_PACKAGE_NAME, a9 as CatalogSubmissionAccepted, aa as DEFAULT_CONFIRMATION_TIMEOUT_MS, ab as DEFAULT_NEXT_TOOL_BY_ACTION, ac as DIRECT_SIGN_CONTEXT_VERSION, ad as ENTRY_POINT_V07, ae as ERC7710_ASSET_TRANSFER_METHOD, af as HAVEN_CLIENT_HEADER, ag as HAVEN_CONNECTOR_CHANNEL, ah as HAVEN_MINIMUM_NODE_VERSION, ai as HYBRID_DELEGATOR_DOMAIN_NAME, aj as HYBRID_DELEGATOR_DOMAIN_VERSION, ak as HavenAgentAllowanceSummary, al as HavenAgentReadiness, am as HavenAllowance, an as HavenApiError, ao as HavenCatalogMerchant, ap as HavenListScope, aq as HavenPaymentStateError, ar as HavenSigningError, as as HavenTimeoutError, at as HavenTypedDataRefusedError, au as HavenUnsupportedSignerVersionError, av as HavenUserOpBindingError, aw as HavenZeroSettlementHashError, ax as MAX_TASK_BUDGET_TTL_SECONDS, ay as MachinePaymentRail, az as MerchantTimeoutError, aA as NEXT_TOOL_SERVER_NAMES, aB as NEXT_TOOL_SERVER_ROLES, aC as NextStep, aD as NextStepArguments, aE as NextStepHandoff, aF as NextStepInput, aG as NextStepTarget, aH as NextStepTargets, aI as NextToolServerRole, aJ as PACKED_USER_OPERATION_FIELDS, aK as PaymentFee, aL as PaymentNextAction, aM as PaymentPhase, aN as PaymentStatus, aO as ROOT_AUTHORITY, aP as SDK_CLIENT_IDENTITY, aQ as SDK_VERSION, aR as SIGNER_UPDATE_FALLBACK, aS as SWEEP_BASE_CHAIN_ID, aT as SWEEP_BASE_SEPOLIA_CHAIN_ID, aU as SWEEP_BASE_SEPOLIA_USDC_ADDRESS, aV as SWEEP_BASE_USDC_ADDRESS, aW as SettlementChildExpectation, aX as SignerRefusalCode, aY as SweepConfirmation, aZ as SweepEip712Domain, a_ as SweepEntry, a$ as SweepExpectedAuth, b0 as SweepPreparation, b1 as SweepSubmitResult, b2 as SweepTypedData, b3 as TASK_SIGN_CONTEXT_VERSION, b4 as TRANSFER_WITH_AUTHORIZATION_TYPES, b5 as TYPED_DATA_NOT_ALLOWED, b6 as TaskBudgetCloseExpectation, b7 as TaskChildExpectation, b8 as TaskChildTypedData, b9 as UnsupportedNodeVersionMessageOptions, ba as X402AlreadySettledError, bb as X402Erc7710AlreadySettledError, bc as X402ExpectedAuth, bd as X402ExpectedContext, be as X402PaymentHeaderContext, bf as X402PaymentHeaderValidationError, bg as X402PaymentOption, bh as X402RequestSnapshot, bi as X402SchemeSelection, bj as X402TaskBudgetMismatchError, bk as X402UnexpectedStatusError, bl as X402_LEGACY_PAYMENT_HEADER_NAME, bm as X402_MAX_AUTHORIZATION_WINDOW_SECONDS, bn as X402_PAYMENT_HEADER_NAME, bo as X402_PAYMENT_HEADER_NAMES_SENT, bp as X402_PAYMENT_REQUIRED_HEADER_NAME, bq as X402_PAYMENT_RESPONSE_HEADER_NAME, br as X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, bs as assertBoundDirectPaymentUserOp, bt as assertOwnTaskBudgetCloseUserOp, bu as assertOwnTaskChild, bv as assertUserOpTypedDataBinding, bw as buildSweepAuthorizationMessage, bx as buildSweepTypedData, by as buildX402ExpectedMessage, bz as compareNodeVersions, bA as connectorRerunCommand, bB as connectorSpec, bC as connectorUpgradeCommand, bD as createNextStepBuilder, bE as decodeBase64Json, bF as decodeBase64Utf8, bG as defaultNextToolFor, bH as deriveDelegateAccountAddress, bI as encodeBase64Json, bJ as encodeBase64Utf8, bK as encodePaymentProof, bL as hashDelegation, bM as havenClientIdentity, bN as isConnectorChannel, bO as isErc7710Option, bP as isPackedUserOperationTypedData, bQ as isSupportedNodeVersion, bR as isSweepableChain, bS as isTaskChildTypedData, bT as normalizePaymentRequired, bU as packedUserOperationHash, bV as parseNextTool, bW as parsePaymentRequired, bX as parsePaymentRequiredResponse, bY as readClientUpdate, bZ as renderNextTool, b_ as resolveConnectorChannel, b$ as resolveTokenBySymbol, c0 as resolveTokenFromAddress, c1 as selectErc7710PaymentOption, c2 as selectPaymentOption, c3 as selectStandardPaymentOption, c4 as selectX402SettlementScheme, c5 as signerUpdateFallback, c6 as sweepUsdcAddress, c7 as sweepUsdcDomain, c8 as toStandardPaymentRequirements, c9 as unsupportedNodeVersionMessage, ca as validateStandardX402PaymentHeader, cb as verifySettlementChild, cc as x402AssetTransferMethod, cd as x402AuthorizationAmount, ce as x402FacilitatorAddresses, cf as x402V2PaymentEnvelope } from './base64-
|
|
1
|
+
import { R as RawPaymentParties, H as HavenClientConfig, a as HavenClientUpdate, P as PaymentRequest, b as PaymentResult, c as PaymentIntent, X as X402PaymentRequired, d as X402AuthorizationOptions, e as X402Intent, f as PaymentStatusResult, g as HavenAgent, h as HavenAgentSummary, S as SweepResult, i as SweepPrepareResponse, j as SweepAuthorization, k as SweepSubmitResponse, l as HavenAllowanceSummary, m as HavenBalanceCoverage, n as PostPurchaseAllowanceSummary, A as AgentPaymentWarning, o as HavenCatalogEntry, p as HavenCatalogSubmission, q as HavenPaymentReceipt, r as HavenPaymentReceiptsPage, O as OpenTaskBudgetResult, s as HavenTaskBudget, T as TaskBudgetSignContext, t as SubmitTaskBudgetResult, C as CloseTaskBudgetResult, u as PaymentResumeState, v as X402Receipt, w as X402Quote, x as X402Erc7710Settlement, y as X402McpCallContext, z as SignData, B as ResumeAuthorizedX402Input, D as ResumeX402PaymentInput, E as X402ResumeState, F as X402McpTransport, G as X402MerchantCallContext, I as HavenError } from './base64-VVxgYQAD.js';
|
|
2
|
+
export { J as AGENT_PAYMENT_FAILURE_CODE_VALUES, K as AGENT_PAYMENT_NEXT_ACTION_VALUES, L as AGENT_PAYMENT_PHASE_VALUES, M as AGENT_PAYMENT_RAIL_VALUES, N as AgentNextStep, Q as AgentPaymentEnumSchema, U as AgentPaymentFailureCode, V as AgentPaymentFailureCodeDescriptions, W as AgentPaymentFailureCodeSchema, Y as AgentPaymentNextAction, Z as AgentPaymentNextActionDescriptions, _ as AgentPaymentNextActionSchema, $ as AgentPaymentPhase, a0 as AgentPaymentPhaseDescriptions, a1 as AgentPaymentPhaseSchema, a2 as AgentPaymentRail, a3 as AgentPaymentRailDescriptions, a4 as AgentPaymentRailSchema, a5 as AgentPaymentSummary, a6 as AgentPaymentWarningCode, a7 as AgentPurchaseSummary, a8 as CONNECTOR_PACKAGE_NAME, a9 as CatalogSubmissionAccepted, aa as DEFAULT_CONFIRMATION_TIMEOUT_MS, ab as DEFAULT_NEXT_TOOL_BY_ACTION, ac as DIRECT_SIGN_CONTEXT_VERSION, ad as ENTRY_POINT_V07, ae as ERC7710_ASSET_TRANSFER_METHOD, af as HAVEN_CLIENT_HEADER, ag as HAVEN_CONNECTOR_CHANNEL, ah as HAVEN_MINIMUM_NODE_VERSION, ai as HYBRID_DELEGATOR_DOMAIN_NAME, aj as HYBRID_DELEGATOR_DOMAIN_VERSION, ak as HavenAgentAllowanceSummary, al as HavenAgentReadiness, am as HavenAllowance, an as HavenApiError, ao as HavenCatalogMerchant, ap as HavenListScope, aq as HavenPaymentStateError, ar as HavenSigningError, as as HavenTimeoutError, at as HavenTypedDataRefusedError, au as HavenUnsupportedSignerVersionError, av as HavenUserOpBindingError, aw as HavenZeroSettlementHashError, ax as MAX_TASK_BUDGET_TTL_SECONDS, ay as MachinePaymentRail, az as MerchantTimeoutError, aA as NEXT_TOOL_SERVER_NAMES, aB as NEXT_TOOL_SERVER_ROLES, aC as NextStep, aD as NextStepArguments, aE as NextStepHandoff, aF as NextStepInput, aG as NextStepTarget, aH as NextStepTargets, aI as NextToolServerRole, aJ as PACKED_USER_OPERATION_FIELDS, aK as PaymentFee, aL as PaymentNextAction, aM as PaymentPhase, aN as PaymentStatus, aO as ROOT_AUTHORITY, aP as SDK_CLIENT_IDENTITY, aQ as SDK_VERSION, aR as SIGNER_UPDATE_FALLBACK, aS as SWEEP_BASE_CHAIN_ID, aT as SWEEP_BASE_SEPOLIA_CHAIN_ID, aU as SWEEP_BASE_SEPOLIA_USDC_ADDRESS, aV as SWEEP_BASE_USDC_ADDRESS, aW as SettlementChildExpectation, aX as SignerRefusalCode, aY as SweepConfirmation, aZ as SweepEip712Domain, a_ as SweepEntry, a$ as SweepExpectedAuth, b0 as SweepPreparation, b1 as SweepSubmitResult, b2 as SweepTypedData, b3 as TASK_SIGN_CONTEXT_VERSION, b4 as TRANSFER_WITH_AUTHORIZATION_TYPES, b5 as TYPED_DATA_NOT_ALLOWED, b6 as TaskBudgetCloseExpectation, b7 as TaskChildExpectation, b8 as TaskChildTypedData, b9 as UnsupportedNodeVersionMessageOptions, ba as X402AlreadySettledError, bb as X402Erc7710AlreadySettledError, bc as X402ExpectedAuth, bd as X402ExpectedContext, be as X402PaymentHeaderContext, bf as X402PaymentHeaderValidationError, bg as X402PaymentOption, bh as X402RequestSnapshot, bi as X402SchemeSelection, bj as X402TaskBudgetMismatchError, bk as X402UnexpectedStatusError, bl as X402_LEGACY_PAYMENT_HEADER_NAME, bm as X402_MAX_AUTHORIZATION_WINDOW_SECONDS, bn as X402_PAYMENT_HEADER_NAME, bo as X402_PAYMENT_HEADER_NAMES_SENT, bp as X402_PAYMENT_REQUIRED_HEADER_NAME, bq as X402_PAYMENT_RESPONSE_HEADER_NAME, br as X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, bs as assertBoundDirectPaymentUserOp, bt as assertOwnTaskBudgetCloseUserOp, bu as assertOwnTaskChild, bv as assertUserOpTypedDataBinding, bw as buildSweepAuthorizationMessage, bx as buildSweepTypedData, by as buildX402ExpectedMessage, bz as compareNodeVersions, bA as connectorRerunCommand, bB as connectorSpec, bC as connectorUpgradeCommand, bD as createNextStepBuilder, bE as decodeBase64Json, bF as decodeBase64Utf8, bG as defaultNextToolFor, bH as deriveDelegateAccountAddress, bI as encodeBase64Json, bJ as encodeBase64Utf8, bK as encodePaymentProof, bL as hashDelegation, bM as havenClientIdentity, bN as isConnectorChannel, bO as isErc7710Option, bP as isPackedUserOperationTypedData, bQ as isSupportedNodeVersion, bR as isSweepableChain, bS as isTaskChildTypedData, bT as normalizePaymentRequired, bU as packedUserOperationHash, bV as parseNextTool, bW as parsePaymentRequired, bX as parsePaymentRequiredResponse, bY as readClientUpdate, bZ as renderNextTool, b_ as resolveConnectorChannel, b$ as resolveTokenBySymbol, c0 as resolveTokenFromAddress, c1 as selectErc7710PaymentOption, c2 as selectPaymentOption, c3 as selectStandardPaymentOption, c4 as selectX402SettlementScheme, c5 as signerUpdateFallback, c6 as sweepUsdcAddress, c7 as sweepUsdcDomain, c8 as toStandardPaymentRequirements, c9 as unsupportedNodeVersionMessage, ca as validateStandardX402PaymentHeader, cb as verifySettlementChild, cc as x402AssetTransferMethod, cd as x402AuthorizationAmount, ce as x402FacilitatorAddresses, cf as x402V2PaymentEnvelope } from './base64-VVxgYQAD.js';
|
|
3
3
|
import 'x402/types';
|
|
4
4
|
import 'viem';
|
|
5
5
|
|
|
@@ -1004,12 +1004,12 @@ declare const toolDescriptions: {
|
|
|
1004
1004
|
readonly payX402OneShot: {
|
|
1005
1005
|
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.";
|
|
1006
1006
|
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.";
|
|
1007
|
-
readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.";
|
|
1007
|
+
readonly behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. On the EIP-3009 path, when the owner opted this agent in, the same retry also carries the agent-signed buyer tax declaration in X-Tax-Declaration — signed by the same local delegate key, sent to the seller only, and omitted when the declaration is not available or on the direct-settlement (erc7710) scheme. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.";
|
|
1008
1008
|
readonly nextActionGuidance: string;
|
|
1009
1009
|
};
|
|
1010
1010
|
readonly resumeX402: {
|
|
1011
1011
|
readonly summary: "Resume an x402 payment whose Haven-side authorization already succeeded but whose merchant retry did not complete.";
|
|
1012
|
-
readonly behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). No new Haven payment is created.";
|
|
1012
|
+
readonly behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). On the EIP-3009 scheme the retry also carries the agent-signed buyer tax declaration in X-Tax-Declaration when the owner opted this agent in and the declaration is available — signed locally by the same delegate key, sent to the seller only. No new Haven payment is created.";
|
|
1013
1013
|
readonly nextActionGuidance: string;
|
|
1014
1014
|
};
|
|
1015
1015
|
readonly getPaymentStatus: {
|
|
@@ -1132,7 +1132,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
|
|
|
1132
1132
|
* live sibling constant not pulled in here; if it ever is, this applies to it
|
|
1133
1133
|
* too (design review, #2537).
|
|
1134
1134
|
*/
|
|
1135
|
-
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules, and set Haven up when it is not yet connected. Use when the user asks to send, pay, tip, or transfer crypto; when a request hits an HTTP 402 (x402) paywall; or when they ask to create a Haven account, create an agent, or connect one.\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; a payment above the remaining budget is declined \u2014\nnothing is paid past the rules the user set.\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.\nThat namespacing is Claude-family; other runtimes name the servers by their\nown config keys (Codex: `haven`, `haven_signer`). Tool results carry the\nexact next step (`next_action`, `next_tool`, `next_arguments`, plus the\nruntime-neutral `next_tool_server` + `next_tool_name` + `next_tool_server_role`\n\u2014 the bare tool name on that logical server, whatever your runtime calls it).\nWhen no tool follows, `next_tool` is absent and `next_tool_omitted_reason`\nsays why; that is a complete answer.\nFollow those fields first; the prose below is fallback and orientation, not\nthe 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## Onboarding and setup\n\nYou are in this mode when there is no Haven agent credential on this machine,\nor when your user asks you to create a Haven account, create an agent, or\nconnect one \u2014 for themselves or for someone else.\n\n**None of the tools below creates authority.** They spend a budget a human\nalready signed. There is no tool here that opens an account, mints a\ncredential, or approves a budget, so reaching for one of them to \"set Haven\nup\" cannot work; the steps are the ones in this section instead.\n\nStart by reading `/for-agents.md` on the Haven host \u2014 the origin of the\n`api_url` in your `agent.json` if you have one, otherwise the host your user\nnames. It is the full runbook: six steps, which four are your user's, and what\nto say at each hand-off.\n\nTwo of those steps you can do yourself, from the shell with `@haven_ai/cli`\n(installs the `haven` command):\n\n- `haven login` \u2014 a device-code browser flow. It prints a code and a link\n for your user to approve, so you never see or ask for their password. What\n the session can reach is an allow-list, not your user's full authority: it\n creates and manages agents and reads the account, and it cannot approve a\n budget, rotate a key, change a signer or move money \u2014 those are your user's.\n- `haven agents connect` with `--name`, `--budget`, `--token` and\n `--period` \u2014 creates a connection setup and prints two things: the\n connector command the backend built, and the approval link to give your user.\n Add `--run` to execute that command here as a child process.\n- `haven wallets funding` \u2014 prints the paste-ready funding instruction: what\n to send, to which address, on which chain. Read the chain from there rather\n than assuming one. `--wait` polls until the account counts as funded.\n\n**Four steps are your user's, and each one needs a human:** create the account\nand its passkey, fund the wallet, approve every agent's budget, and rotate a\ncredential. You can compose the funding message for them with\n`haven wallets funding`, but you cannot send the money \u2014 that transfer is\ntheirs, from a wallet you have no access to.\n\nRunning the connector command is the step that wires this machine to the new\nagent \u2014 the command `haven agents connect` printed, or the one your user\npasted you from the dashboard. Three rules bind you while you do it, quoted\nunchanged from the setup prompt your user is also holding so the two copies\ncannot drift into contradicting each other. They are written in your user's\nvoice, so read them accordingly: \"me\" and \"I\" below are your user, never\nHaven, and \"the command above\" is that connector command, not anything printed\nin this file. The first rule outranks anything else you were about to do next:\n\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- If the connector refuses with wiring_collision, this machine is already wired to a different agent: relay that refusal to me with the superseded_agent_ids and suggested_name it carries, and let me choose whether to replace the existing wiring or add this agent alongside it. Never pick for me by adding --replace or --name yourself.\n\nDo not print private keys, API keys, credential file contents, or config secrets in chat or logs.\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 `spend_authority_readiness` (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot. That signal\n covers hosted identity and on-chain spend authority only \u2014 it cannot see the\n local signer; the signer is verified by calling any signer tool.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n- `mcp__haven__haven_check_funds` \u2014 whether the account actually HOLDS at\n least a given amount of a token. Allowance answers above say what you are\n permitted to spend; this one says whether the money is really there,\n answered as `covered` true/false/null \u2014 never as a balance. On\n `covered: false`, stop and tell the user the account is short; on\n `covered: null` (the chain read failed), treat it as unverifiable rather\n than as absence.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is declined before any money moves \u2014 tell the user; they can raise\nthe budget in the Haven dashboard, or wait for the period reset.\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. If the user needs the live price before authorizing a cap, call\n `mcp__haven__haven_quote_catalog_purchase` with `catalog_id`. It is\n read-only and informational only: it never reserves a price or creates a\n payment. Tell the user its `amount` / `amount_atomic`, then choose a cap.\n3. `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.)\n4. 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 row is a plain-HTTP x402 paywall (no MCP tool metadata), the response\n instead names `mcp__haven__haven_quote_x402` with the entry's resource\n URL as `url`. If an MCP row is degraded or has no tool name, the response\n instead names `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name,\n arguments) as the manual fallback.\n\n**Signing:** which signer tool to call depends on the settlement scheme the\nprepare/pay response already named as `next_tool` \u2014 follow that field, never\nhard-code a choice. **erc7710** (direct settlement \u2014 chosen per merchant when\nits 402 advertises `assetTransferMethod: \"erc7710\"` AND your account is on\nthe delegation rail; never a blanket default): `mcp__haven-signer__haven_sign`\nwith `payment_id` ONLY; the signer fetches the settlement child itself.\n**EIP-3009** (the bridge \u2014 used otherwise, whenever the merchant offers a\nstandard entry): `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. A merchant\nthat advertises ONLY erc7710 against an account that is NOT on the\ndelegation rail is refused outright \u2014 it does not fall back to EIP-3009. If\nthe signer reports its fetched context carried no `payment_required` (older\nbackend), re-call with `payment_required` added verbatim. Fallback for an\nolder signer or backend: re-run the quote/prepare tool with the SAME\n`idempotency_key` plus `include_signing_payload=true`, then pass\n`payload_hash`, `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` and\n`signature` always. On **erc7710**, pass no `payment_header` \u2014 Haven\nassembles it at settle, so there is nothing to build locally and no funding\ntransaction to wait for. On **EIP-3009**, also pass `payment_header` (from\n`haven_sign_x402`) ONLY. Either way 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. On **EIP-3009**, `settled: false` means\nfunding has not confirmed; on **erc7710** it means the merchant delivered but\nsettlement is not yet verified. Either way, follow the result's guidance\nfields and do 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`): if the user needs the live price before choosing a cap, first\ncall `mcp__haven__haven_quote_mcp_tool` with that merchant URL, tool name,\nand arguments. It is informational only; then call\n`mcp__haven__haven_pay_mcp_tool` with the same inputs and the explicit cap.\nThe paid call always obtains a fresh quote before it creates any intent. Then\ncontinue `mcp__haven__haven_pay_mcp_tool` \u2192\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`. Call that last step with\n`payment_id` and the signer's `payment_header` ONLY. It does not take\n`payment_required`: Haven rehydrates the merchant call context\n(`merchant_url`, `tool_name`, `arguments`, `mcp_transport`) and the\n402 server-side from `payment_id`, exactly as at settle. Pass that context\nexplicitly only as a version-skew fallback when Haven has no stored context\nfor the id \u2014 `merchant_url` and `tool_name` both or none together, never\njust one.\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\n`to`, `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 and sign in the local Haven signer. On THIS path Haven does not talk to\nthe merchant: `mcp__haven-signer__haven_sign_x402` returns both\n`signature` and `payment_header`; relay `signature` with\n`mcp__haven__haven_submit`, then retry the paywalled URL yourself with\n`payment_header`. Do not pass that call's `x402_binding` to\n`mcp__haven-signer__haven_x402_sign_header` \u2014 the one-shot already spent it\nbuilding the header, so the call can only refuse. Then tell Haven what the\nmerchant answered: `mcp__haven__haven_report_x402_outcome` with the\n`payment_id`, `outcome` (`\"accepted\"` for a 2xx, else `\"rejected\"`)\nand the `merchant_status` you got. Because Haven never contacted that\nmerchant, this is the only way it can learn the purchase failed \u2014 without it a\nfailed purchase reads as complete for fifteen minutes. If the merchant's\n`PAYMENT-RESPONSE` header names a `transaction`, also pass it to\n`mcp__haven__haven_report_settlement_evidence` (`payment_id`,\n`settlement_tx_hash`): Haven verifies it on-chain, and the receipt then shows\nthe merchant's settlement, not only the funding transaction. (The SDK's own\n`haven_pay_x402` tool does perform the merchant retry itself; that tool is\nnot part of the hosted MCP surface.) If the process\ncrashes after payment, a later `mcp__haven__haven_get_payment_status` call\nmay report `nextAction: 'retry_original_x402_request'` \u2014 only then call\n`mcp__haven__haven_resume_x402_payment` with the preserved resume state or\npayment id, instead of paying again.\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 a read-only quote or the pay-tool\nresult, never a catalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. A read-only quote is informational\nonly and does not reserve a price; the later paid call re-quotes and enforces\nthe cap. The pay-tool result's `amount` / `amount_atomic` is the merchant's\nown quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay. It is a price, not an approval:\nthe payment goes through only if it also fits the cap you set and the on-chain\nbudget the user signed, which is enforced on-chain rather than by Haven.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on in-flight payments. Do not poll in a tight loop.\n\n## Declines and stop signals\n\n- A payment outside the agent's rules \u2014 above the remaining budget, wrong\n recipient, or expired budget \u2014 is declined before any money moves. Nothing\n is queued; tell the user, who can raise the budget in Haven.\n- `safe_to_continue: false` on a guidance block is a stop 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 connector command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. A failure carries the same\n`next_action` / `next_tool` / `next_arguments` / `next_tool_omitted_reason`\nfields a success does; follow them first, then branch on `code` and surface\n`message` or `error` verbatim. Common cases:\n\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_NOT_READY`: the merchant refused the quote with its own\n \"cannot settle right now\" signal (a 503 `merchant_not_ready` with a\n `reason_code`) instead of a 402. No payment was created. Tell the user;\n retry later (the message carries `retry_after_s` when the merchant gave\n one) \u2014 this is not a wrong or broken endpoint.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n On eip3009 (`rail` not `erc7710`): Stop-and-sweep \u2014 stop retrying the\n merchant and use `mcp__haven__haven_sweep_delegate` to recover stranded\n delegate funds. On erc7710 there is no funding leg and nothing to sweep:\n follow the message \u2014 it says whether the merchant declined to settle\n (re-quote later) or whether to check `haven_get_payment_status` after\n the payment window first.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: the merchant never answered the paid\n retry. This is NOT proof of rejection \u2014 the merchant may still settle late.\n On eip3009 (`rail` not `erc7710`), funding confirmed on-chain: Verify-then-sweep,\n never a blind sweep \u2014 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. On erc7710\n there is no funding leg and nothing to sweep, and\n `mcp__haven__haven_complete_mcp_tool` has no erc7710 branch (it refuses a\n submitted intent) \u2014 do not retry it: the merchant may still redeem the\n settlement authorization within the payment window, so check\n `mcp__haven__haven_get_payment_status` after that window and re-quote only\n if it shows no settlement.\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";
|
|
1135
|
+
declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules, and set Haven up when it is not yet connected. Use when the user asks to send, pay, tip, or transfer crypto; when a request hits an HTTP 402 (x402) paywall; or when they ask to create a Haven account, create an agent, or connect one.\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; a payment above the remaining budget is declined \u2014\nnothing is paid past the rules the user set.\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.\nThat namespacing is Claude-family; other runtimes name the servers by their\nown config keys (Codex: `haven`, `haven_signer`). Tool results carry the\nexact next step (`next_action`, `next_tool`, `next_arguments`, plus the\nruntime-neutral `next_tool_server` + `next_tool_name` + `next_tool_server_role`\n\u2014 the bare tool name on that logical server, whatever your runtime calls it).\nWhen no tool follows, `next_tool` is absent and `next_tool_omitted_reason`\nsays why; that is a complete answer.\nFollow those fields first; the prose below is fallback and orientation, not\nthe 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## Onboarding and setup\n\nYou are in this mode when there is no Haven agent credential on this machine,\nor when your user asks you to create a Haven account, create an agent, or\nconnect one \u2014 for themselves or for someone else.\n\n**None of the tools below creates authority.** They spend a budget a human\nalready signed. There is no tool here that opens an account, mints a\ncredential, or approves a budget, so reaching for one of them to \"set Haven\nup\" cannot work; the steps are the ones in this section instead.\n\nStart by reading `/for-agents.md` on the Haven host \u2014 the origin of the\n`api_url` in your `agent.json` if you have one, otherwise the host your user\nnames. It is the full runbook: six steps, which four are your user's, and what\nto say at each hand-off.\n\nTwo of those steps you can do yourself, from the shell with `@haven_ai/cli`\n(installs the `haven` command):\n\n- `haven login` \u2014 a device-code browser flow. It prints a code and a link\n for your user to approve, so you never see or ask for their password. What\n the session can reach is an allow-list, not your user's full authority: it\n creates and manages agents and reads the account, and it cannot approve a\n budget, rotate a key, change a signer or move money \u2014 those are your user's.\n- `haven agents connect` with `--name`, `--budget`, `--token` and\n `--period` \u2014 creates a connection setup and prints two things: the\n connector command the backend built, and the approval link to give your user.\n Add `--run` to execute that command here as a child process.\n- `haven wallets funding` \u2014 prints the paste-ready funding instruction: what\n to send, to which address, on which chain. Read the chain from there rather\n than assuming one. `--wait` polls until the account counts as funded.\n\n**Four steps are your user's, and each one needs a human:** create the account\nand its passkey, fund the wallet, approve every agent's budget, and rotate a\ncredential. You can compose the funding message for them with\n`haven wallets funding`, but you cannot send the money \u2014 that transfer is\ntheirs, from a wallet you have no access to.\n\nRunning the connector command is the step that wires this machine to the new\nagent \u2014 the command `haven agents connect` printed, or the one your user\npasted you from the dashboard. Three rules bind you while you do it, quoted\nunchanged from the setup prompt your user is also holding so the two copies\ncannot drift into contradicting each other. They are written in your user's\nvoice, so read them accordingly: \"me\" and \"I\" below are your user, never\nHaven, and \"the command above\" is that connector command, not anything printed\nin this file. The first rule outranks anything else you were about to do next:\n\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- If the connector refuses with wiring_collision, this machine is already wired to a different agent: relay that refusal to me with the superseded_agent_ids and suggested_name it carries, and let me choose whether to replace the existing wiring or add this agent alongside it. Never pick for me by adding --replace or --name yourself.\n\nDo not print private keys, API keys, credential file contents, or config secrets in chat or logs.\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 `spend_authority_readiness` (`ready` / `needs_approval` /\n `revoked`) and live remaining per-token allowance, in one shot. That signal\n covers hosted identity and on-chain spend authority only \u2014 it cannot see the\n local signer; the signer is verified by calling any signer tool.\n- `mcp__haven__haven_get_allowances` \u2014 detailed per-token breakdown\n (configured, spent, reset window) when you need more than the summary.\n- `mcp__haven__haven_check_funds` \u2014 whether the account actually HOLDS at\n least a given amount of a token. Allowance answers above say what you are\n permitted to spend; this one says whether the money is really there,\n answered as `covered` true/false/null \u2014 never as a balance. On\n `covered: false`, stop and tell the user the account is short; on\n `covered: null` (the chain read failed), treat it as unverifiable rather\n than as absence.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is declined before any money moves \u2014 tell the user; they can raise\nthe budget in the Haven dashboard, or wait for the period reset.\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. If the user needs the live price before authorizing a cap, call\n `mcp__haven__haven_quote_catalog_purchase` with `catalog_id`. It is\n read-only and informational only: it never reserves a price or creates a\n payment. Tell the user its `amount` / `amount_atomic`, then choose a cap.\n3. `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.)\n4. 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 row is a plain-HTTP x402 paywall (no MCP tool metadata), the response\n instead names `mcp__haven__haven_quote_x402` with the entry's resource\n URL as `url`. If an MCP row is degraded or has no tool name, the response\n instead names `mcp__haven__haven_pay_mcp_tool` (merchant URL, tool name,\n arguments) as the manual fallback.\n\n**Signing:** which signer tool to call depends on the settlement scheme the\nprepare/pay response already named as `next_tool` \u2014 follow that field, never\nhard-code a choice. **erc7710** (direct settlement \u2014 chosen per merchant when\nits 402 advertises `assetTransferMethod: \"erc7710\"` AND your account is on\nthe delegation rail; never a blanket default): `mcp__haven-signer__haven_sign`\nwith `payment_id` ONLY; the signer fetches the settlement child itself.\n**EIP-3009** (the bridge \u2014 used otherwise, whenever the merchant offers a\nstandard entry): `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. A merchant\nthat advertises ONLY erc7710 against an account that is NOT on the\ndelegation rail is refused outright \u2014 it does not fall back to EIP-3009. If\nthe signer reports its fetched context carried no `payment_required` (older\nbackend), re-call with `payment_required` added verbatim. Fallback for an\nolder signer or backend: re-run the quote/prepare tool with the SAME\n`idempotency_key` plus `include_signing_payload=true`, then pass\n`payload_hash`, `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` and\n`signature` always. On **erc7710**, pass no `payment_header` \u2014 Haven\nassembles it at settle, so there is nothing to build locally and no funding\ntransaction to wait for. On **EIP-3009**, also pass `payment_header` (from\n`haven_sign_x402`) ONLY. Either way 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. On **EIP-3009**, `settled: false` means\nfunding has not confirmed; on **erc7710** it means the merchant delivered but\nsettlement is not yet verified. Either way, follow the result's guidance\nfields and do 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`): if the user needs the live price before choosing a cap, first\ncall `mcp__haven__haven_quote_mcp_tool` with that merchant URL, tool name,\nand arguments. It is informational only; then call\n`mcp__haven__haven_pay_mcp_tool` with the same inputs and the explicit cap.\nThe paid call always obtains a fresh quote before it creates any intent. Then\ncontinue `mcp__haven__haven_pay_mcp_tool` \u2192\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`. Call that last step with\n`payment_id` and the signer's `payment_header` ONLY. It does not take\n`payment_required`: Haven rehydrates the merchant call context\n(`merchant_url`, `tool_name`, `arguments`, `mcp_transport`) and the\n402 server-side from `payment_id`, exactly as at settle. Pass that context\nexplicitly only as a version-skew fallback when Haven has no stored context\nfor the id \u2014 `merchant_url` and `tool_name` both or none together, never\njust one.\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\n`to`, `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 and sign in the local Haven signer. On THIS path Haven does not talk to\nthe merchant: `mcp__haven-signer__haven_sign_x402` returns both\n`signature` and `payment_header`; relay `signature` with\n`mcp__haven__haven_submit`, then retry the paywalled URL yourself with\n`payment_header`. Do not pass that call's `x402_binding` to\n`mcp__haven-signer__haven_x402_sign_header` \u2014 the one-shot already spent it\nbuilding the header, so the call can only refuse. Then tell Haven what the\nmerchant answered: `mcp__haven__haven_report_x402_outcome` with the\n`payment_id`, `outcome` (`\"accepted\"` for a 2xx, else `\"rejected\"`)\nand the `merchant_status` you got. Because Haven never contacted that\nmerchant, this is the only way it can learn the purchase failed \u2014 without it a\nfailed purchase reads as complete for fifteen minutes. If the merchant's\n`PAYMENT-RESPONSE` header names a `transaction`, also pass it to\n`mcp__haven__haven_report_settlement_evidence` (`payment_id`,\n`settlement_tx_hash`): Haven verifies it on-chain, and the receipt then shows\nthe merchant's settlement, not only the funding transaction. (The SDK's own\n`haven_pay_x402` tool does perform the merchant retry itself; that tool is\nnot part of the hosted MCP surface.) On this SDK path, when the owner opted the\nagent in, the paid EIP-3009 retry also carries the agent-signed buyer tax\ndeclaration to the seller (`X-Tax-Declaration`, #3427) \u2014 signed locally by the\nsame delegate key, omitted when unavailable or on the erc7710 scheme; nothing\nfor you to sign or send. If the process\ncrashes after payment, a later `mcp__haven__haven_get_payment_status` call\nmay report `nextAction: 'retry_original_x402_request'` \u2014 only then call\n`mcp__haven__haven_resume_x402_payment` with the preserved resume state or\npayment id, instead of paying again.\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 a read-only quote or the pay-tool\nresult, never a catalog price. `haven_discover_tools` prices are indicative\n(`price_is_indicative`) and can be stale. A read-only quote is informational\nonly and does not reserve a price; the later paid call re-quotes and enforces\nthe cap. The pay-tool result's `amount` / `amount_atomic` is the merchant's\nown quoted price for that call \u2014 a ceiling the merchant settles at or below \u2014\nso present it as the most the user will pay. It is a price, not an approval:\nthe payment goes through only if it also fits the cap you set and the on-chain\nbudget the user signed, which is enforced on-chain rather than by Haven.\n\n**Status:** `mcp__haven__haven_get_payment_status` with a `payment_id` to\ncheck on in-flight payments. Do not poll in a tight loop.\n\n## Declines and stop signals\n\n- A payment outside the agent's rules \u2014 above the remaining budget, wrong\n recipient, or expired budget \u2014 is declined before any money moves. Nothing\n is queued; tell the user, who can raise the budget in Haven.\n- `safe_to_continue: false` on a guidance block is a stop 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 connector command.\n\n## Failure handling\n\nHaven tool failures are shaped like `{ success: false, code, message, ... }`\nor older `{ error, status, details? }` responses. A failure carries the same\n`next_action` / `next_tool` / `next_arguments` / `next_tool_omitted_reason`\nfields a success does; follow them first, then branch on `code` and surface\n`message` or `error` verbatim. Common cases:\n\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_NOT_READY`: the merchant refused the quote with its own\n \"cannot settle right now\" signal (a 503 `merchant_not_ready` with a\n `reason_code`) instead of a 402. No payment was created. Tell the user;\n retry later (the message carries `retry_after_s` when the merchant gave\n one) \u2014 this is not a wrong or broken endpoint.\n- `MERCHANT_REJECTED_AFTER_FUNDING`: the merchant refused the paid retry.\n On eip3009 (`rail` not `erc7710`): Stop-and-sweep \u2014 stop retrying the\n merchant and use `mcp__haven__haven_sweep_delegate` to recover stranded\n delegate funds. On erc7710 there is no funding leg and nothing to sweep:\n follow the message \u2014 it says whether the merchant declined to settle\n (re-quote later) or whether to check `haven_get_payment_status` after\n the payment window first.\n- `MERCHANT_UNRESPONSIVE_AFTER_FUNDING`: the merchant never answered the paid\n retry. This is NOT proof of rejection \u2014 the merchant may still settle late.\n On eip3009 (`rail` not `erc7710`), funding confirmed on-chain: Verify-then-sweep,\n never a blind sweep \u2014 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. On erc7710\n there is no funding leg and nothing to sweep, and\n `mcp__haven__haven_complete_mcp_tool` has no erc7710 branch (it refuses a\n submitted intent) \u2014 do not retry it: the merchant may still redeem the\n settlement authorization within the payment window, so check\n `mcp__haven__haven_get_payment_status` after that window and re-quote only\n if it shows no settlement.\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";
|
|
1136
1136
|
/** Directory name for the installed skill folder. */
|
|
1137
1137
|
declare const SKILL_FOLDER_NAME = "haven-pay";
|
|
1138
1138
|
/**
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, selectX402SettlementScheme, selectErc7710PaymentOption,
|
|
2
|
-
export { DEFAULT_NEXT_TOOL_BY_ACTION, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_CLIENT_HEADER, HAVEN_MINIMUM_NODE_VERSION, HavenTypedDataRefusedError, MAX_TASK_BUDGET_TTL_SECONDS, NEXT_TOOL_SERVER_NAMES, NEXT_TOOL_SERVER_ROLES, SDK_CLIENT_IDENTITY, SDK_VERSION, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, TYPED_DATA_NOT_ALLOWED, X402PaymentHeaderValidationError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, assertBoundDirectPaymentUserOp, assertOwnTaskBudgetCloseUserOp, assertOwnTaskChild, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, createNextStepBuilder, decodeBase64Json, decodeBase64Utf8, defaultNextToolFor, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, hashDelegation, havenClientIdentity, isErc7710Option, isSupportedNodeVersion, isSweepableChain, isTaskChildTypedData, normalizePaymentRequired, parseNextTool, parsePaymentRequired, parsePaymentRequiredResponse, readClientUpdate, renderNextTool, resolveTokenBySymbol, resolveTokenFromAddress, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope } from './chunk-
|
|
1
|
+
import { selectStandardPaymentOption, buildX402IdempotencyKey, x402AuthorizationAmount, assertBoundDirectPaymentUserOp, assertFundingLegPaysDelegate, HavenTypedDataRefusedError, assertOwnSettlementChild, parsePaymentRequiredResponse, x402PaymentHeaderNamesSent, SDK_CLIENT_IDENTITY, readClientUpdate, HAVEN_CLIENT_HEADER, isSweepableChain, sweepUsdcAddress, x402PaymentHeaderNamesFor, X402_PAYMENT_HEADER_NAMES, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, isErc7710Option, buildSignedTaxDeclaration, encodeTaxDeclarationHeader, selectX402SettlementScheme, selectErc7710PaymentOption, x402AssetTransferMethod, resolveTokenFromAddress, normalizePaymentRequired, X_TAX_DECLARATION_HEADER } from './chunk-S35ZUPXQ.js';
|
|
2
|
+
export { DEFAULT_NEXT_TOOL_BY_ACTION, ERC7710_ASSET_TRANSFER_METHOD, HAVEN_CLIENT_HEADER, HAVEN_MINIMUM_NODE_VERSION, HavenTypedDataRefusedError, MAX_TASK_BUDGET_TTL_SECONDS, NEXT_TOOL_SERVER_NAMES, NEXT_TOOL_SERVER_ROLES, SDK_CLIENT_IDENTITY, SDK_VERSION, SWEEP_BASE_CHAIN_ID, SWEEP_BASE_SEPOLIA_CHAIN_ID, SWEEP_BASE_SEPOLIA_USDC_ADDRESS, SWEEP_BASE_USDC_ADDRESS, TRANSFER_WITH_AUTHORIZATION_TYPES, TYPED_DATA_NOT_ALLOWED, X402PaymentHeaderValidationError, X402_LEGACY_PAYMENT_HEADER_NAME, X402_MAX_AUTHORIZATION_WINDOW_SECONDS, X402_PAYMENT_HEADER_NAME, X402_PAYMENT_HEADER_NAMES_SENT, X402_PAYMENT_REQUIRED_HEADER_NAME, X402_PAYMENT_RESPONSE_HEADER_NAME, X402_SETTLEMENT_FORWARD_MARGIN_SECONDS, assertBoundDirectPaymentUserOp, assertOwnTaskBudgetCloseUserOp, assertOwnTaskChild, buildSweepAuthorizationMessage, buildSweepTypedData, buildX402ExpectedMessage, compareNodeVersions, createNextStepBuilder, decodeBase64Json, decodeBase64Utf8, defaultNextToolFor, encodeBase64Json, encodeBase64Utf8, encodePaymentProof, hashDelegation, havenClientIdentity, isErc7710Option, isSupportedNodeVersion, isSweepableChain, isTaskChildTypedData, normalizePaymentRequired, parseNextTool, parsePaymentRequired, parsePaymentRequiredResponse, readClientUpdate, renderNextTool, resolveTokenBySymbol, resolveTokenFromAddress, selectErc7710PaymentOption, selectPaymentOption, selectStandardPaymentOption, selectX402SettlementScheme, sweepUsdcAddress, sweepUsdcDomain, toStandardPaymentRequirements, unsupportedNodeVersionMessage, validateStandardX402PaymentHeader, x402AssetTransferMethod, x402AuthorizationAmount, x402FacilitatorAddresses, x402V2PaymentEnvelope } from './chunk-S35ZUPXQ.js';
|
|
3
3
|
import { HavenSigningError, HavenError, DEFAULT_CONFIRMATION_TIMEOUT_MS, HavenApiError, assertUserOpTypedDataBinding, AgentPaymentRail, AgentPaymentPhase, HavenTimeoutError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, X402AlreadySettledError, AgentPaymentWarningCode, MerchantTimeoutError, AgentPaymentNextAction, HavenPaymentStateError, HavenZeroSettlementHashError, X402Erc7710AlreadySettledError, DELEGATION_MANAGER, chainIdForNetwork } from './chunk-5I6LGPWZ.js';
|
|
4
4
|
export { AGENT_PAYMENT_FAILURE_CODE_VALUES, AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentFailureCode, AgentPaymentFailureCodeDescriptions, AgentPaymentFailureCodeSchema, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, AgentPaymentWarningCode, CONNECTOR_PACKAGE_NAME, DEFAULT_CONFIRMATION_TIMEOUT_MS, DIRECT_SIGN_CONTEXT_VERSION, ENTRY_POINT_V07, HAVEN_CONNECTOR_CHANNEL, HYBRID_DELEGATOR_DOMAIN_NAME, HYBRID_DELEGATOR_DOMAIN_VERSION, HavenApiError, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, HavenUnsupportedSignerVersionError, HavenUserOpBindingError, HavenZeroSettlementHashError, MerchantTimeoutError, PACKED_USER_OPERATION_FIELDS, ROOT_AUTHORITY, SIGNER_UPDATE_FALLBACK, SignerRefusalCode, TASK_SIGN_CONTEXT_VERSION, X402AlreadySettledError, X402Erc7710AlreadySettledError, X402TaskBudgetMismatchError, X402UnexpectedStatusError, assertUserOpTypedDataBinding, connectorRerunCommand, connectorSpec, connectorUpgradeCommand, deriveDelegateAccountAddress, isConnectorChannel, isPackedUserOperationTypedData, packedUserOperationHash, resolveConnectorChannel, signerUpdateFallback, verifySettlementChild } from './chunk-5I6LGPWZ.js';
|
|
5
5
|
import { keccak256, toBytes, concatHex, hashTypedData, encodeAbiParameters } from 'viem';
|
|
@@ -154,6 +154,62 @@ var HavenApiTransport = class {
|
|
|
154
154
|
}
|
|
155
155
|
};
|
|
156
156
|
|
|
157
|
+
// src/client-tax-declaration.ts
|
|
158
|
+
async function fetchUnsignedTaxDeclaration(client) {
|
|
159
|
+
const agent = await client.getAgent();
|
|
160
|
+
const body = await client.get(
|
|
161
|
+
`/agents/${agent.id}/tax-declaration`
|
|
162
|
+
);
|
|
163
|
+
if (body && body.available === true && body.declaration && typeof body.declaration === "object") {
|
|
164
|
+
return { available: true, declaration: body.declaration };
|
|
165
|
+
}
|
|
166
|
+
const reason = body && typeof body.reason === "string" ? body.reason : void 0;
|
|
167
|
+
if (reason === "feature_disabled" || reason === "disabled" || reason === "no_company_details" || reason === "vies_not_valid") {
|
|
168
|
+
return { available: false, reason };
|
|
169
|
+
}
|
|
170
|
+
throw new HavenApiError(
|
|
171
|
+
"The tax-declaration endpoint answered a body that is neither the \xA72.1 content nor a named unavailability reason.",
|
|
172
|
+
502
|
|
173
|
+
);
|
|
174
|
+
}
|
|
175
|
+
async function resolveTaxDeclarationHeader(client, input) {
|
|
176
|
+
if (isErc7710Option(input.accepted)) {
|
|
177
|
+
return { header: void 0 };
|
|
178
|
+
}
|
|
179
|
+
let content;
|
|
180
|
+
try {
|
|
181
|
+
content = await fetchUnsignedTaxDeclaration(client);
|
|
182
|
+
} catch {
|
|
183
|
+
return { header: void 0 };
|
|
184
|
+
}
|
|
185
|
+
if (!content.available) {
|
|
186
|
+
return { header: void 0 };
|
|
187
|
+
}
|
|
188
|
+
const signed = buildSignedTaxDeclaration({
|
|
189
|
+
content: content.declaration,
|
|
190
|
+
network: input.accepted.network,
|
|
191
|
+
delegateKey: input.delegateKey
|
|
192
|
+
});
|
|
193
|
+
process.stderr.write(
|
|
194
|
+
`[haven-sdk] signing x402 tax declaration taxId=${JSON.stringify(content.declaration.taxId)} jurisdiction=${JSON.stringify(content.declaration.jurisdiction)} principalId=${signed.declaration.principalId}
|
|
195
|
+
`
|
|
196
|
+
);
|
|
197
|
+
return { header: encodeTaxDeclarationHeader(signed) };
|
|
198
|
+
}
|
|
199
|
+
function withTaxDeclarationHeader(init, header) {
|
|
200
|
+
if (!header) {
|
|
201
|
+
if (init?.headers && new Headers(init.headers).has(X_TAX_DECLARATION_HEADER)) {
|
|
202
|
+
const headers2 = new Headers(init.headers);
|
|
203
|
+
headers2.delete(X_TAX_DECLARATION_HEADER);
|
|
204
|
+
return { ...init, headers: headers2 };
|
|
205
|
+
}
|
|
206
|
+
return init ?? {};
|
|
207
|
+
}
|
|
208
|
+
const headers = new Headers(init?.headers);
|
|
209
|
+
headers.set(X_TAX_DECLARATION_HEADER, header);
|
|
210
|
+
return { ...init, headers };
|
|
211
|
+
}
|
|
212
|
+
|
|
157
213
|
// src/payment-mappers.ts
|
|
158
214
|
function mapParties(raw) {
|
|
159
215
|
if (!raw) return void 0;
|
|
@@ -2173,6 +2229,8 @@ var MerchantCompletion = class {
|
|
|
2173
2229
|
getAgent;
|
|
2174
2230
|
delegateAddress;
|
|
2175
2231
|
x402Wallet;
|
|
2232
|
+
getTaxDeclarationHeader;
|
|
2233
|
+
delegateKey;
|
|
2176
2234
|
sleep;
|
|
2177
2235
|
constructor(options) {
|
|
2178
2236
|
this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
|
|
@@ -2182,6 +2240,8 @@ var MerchantCompletion = class {
|
|
|
2182
2240
|
this.getAgent = options.getAgent;
|
|
2183
2241
|
this.delegateAddress = options.delegateAddress;
|
|
2184
2242
|
this.x402Wallet = options.x402Wallet;
|
|
2243
|
+
this.getTaxDeclarationHeader = options.getTaxDeclarationHeader;
|
|
2244
|
+
this.delegateKey = options.delegateKey;
|
|
2185
2245
|
}
|
|
2186
2246
|
async retryRequest(url, initialInit, paymentRequired, receipt) {
|
|
2187
2247
|
if (!receipt.accepted) {
|
|
@@ -2190,9 +2250,23 @@ var MerchantCompletion = class {
|
|
|
2190
2250
|
if (!receipt.paymentHeader) {
|
|
2191
2251
|
throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
|
|
2192
2252
|
}
|
|
2253
|
+
let retryInit = initialInit;
|
|
2254
|
+
if (this.getTaxDeclarationHeader && this.delegateKey) {
|
|
2255
|
+
const scheme = x402PaymentHeaderNamesFor(receipt.paymentHeader);
|
|
2256
|
+
const isEip3009 = scheme.length > 1;
|
|
2257
|
+
if (isEip3009) {
|
|
2258
|
+
const resolved = await this.getTaxDeclarationHeader({
|
|
2259
|
+
accepted: receipt.accepted,
|
|
2260
|
+
delegateKey: this.delegateKey
|
|
2261
|
+
});
|
|
2262
|
+
retryInit = withTaxDeclarationHeader(initialInit, resolved.header);
|
|
2263
|
+
} else {
|
|
2264
|
+
retryInit = withTaxDeclarationHeader(initialInit, void 0);
|
|
2265
|
+
}
|
|
2266
|
+
}
|
|
2193
2267
|
const retryResponse = await this.merchantTransport.deliverPaymentRecoveringSession(
|
|
2194
2268
|
url,
|
|
2195
|
-
|
|
2269
|
+
retryInit,
|
|
2196
2270
|
receipt.paymentHeader,
|
|
2197
2271
|
() => this.merchantTransport.initialize(url, initialInit)
|
|
2198
2272
|
);
|
|
@@ -2674,7 +2748,19 @@ var HavenClient = class {
|
|
|
2674
2748
|
getPaymentStatus: (paymentId) => this.getPaymentStatus(paymentId),
|
|
2675
2749
|
getAgent: () => this.getAgent(),
|
|
2676
2750
|
delegateAddress: this.delegateAddress,
|
|
2677
|
-
x402Wallet: this.x402Wallet
|
|
2751
|
+
x402Wallet: this.x402Wallet,
|
|
2752
|
+
// #3427: the buyer-side tax declaration is resolved (and signed) only
|
|
2753
|
+
// by the local, key-holding client. The resolver is bound ONLY when a
|
|
2754
|
+
// delegate key exists, so the hosted, keyless construction of this
|
|
2755
|
+
// class — `completeX402MerchantCall`'s `MerchantCompletion` — cannot
|
|
2756
|
+
// resolve a declaration at all, let alone sign one.
|
|
2757
|
+
...config.delegateKey ? {
|
|
2758
|
+
getTaxDeclarationHeader: (input) => resolveTaxDeclarationHeader(
|
|
2759
|
+
{ getAgent: () => this.getAgent(), get: (path) => this.get(path) },
|
|
2760
|
+
input
|
|
2761
|
+
),
|
|
2762
|
+
delegateKey: config.delegateKey
|
|
2763
|
+
} : {}
|
|
2678
2764
|
});
|
|
2679
2765
|
this.erc7710 = new X402Erc7710({
|
|
2680
2766
|
delegateKey: this.delegateKey,
|
|
@@ -3959,12 +4045,12 @@ var toolDescriptions = {
|
|
|
3959
4045
|
payX402OneShot: {
|
|
3960
4046
|
summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
|
|
3961
4047
|
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.",
|
|
3962
|
-
behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.",
|
|
4048
|
+
behavior: "Calls the URL, parses any HTTP 402 x402 challenge (or, since #3118, a native-MCP payment-required tool result under HTTP 200), signs the payment locally, then retries the original request with the signed payment header (sent under PAYMENT-SIGNATURE, plus the legacy X-PAYMENT on the EIP-3009 path only) and returns the merchant response. On the EIP-3009 path, when the owner opted this agent in, the same retry also carries the agent-signed buyer tax declaration in X-Tax-Declaration \u2014 signed by the same local delegate key, sent to the seller only, and omitted when the declaration is not available or on the direct-settlement (erc7710) scheme. Settlement is either direct account-to-merchant with no funding leg, or a bridge that first redeems the agent's budget delegation to fund the delegate wallet for an EIP-3009 authorization. A payment outside the on-chain budget is declined before any money moves; nothing is queued for a human to approve later. If the resource returns a non-402 status with no payment-required tool result, returns it unchanged without contacting Haven.",
|
|
3963
4049
|
nextActionGuidance: "Preserve the returned resume_state or paymentId \u2014 either identifies this payment if you need to ask about it later. This tool performs the merchant retry itself, so do not wait on a signal while the call is in flight. If the process crashes after this call and a later haven_get_payment_status reports nextAction=retry_original_x402_request, Haven's funding leg confirmed but no merchant response was ever recorded \u2014 call the resume tool with the preserved resume_state or payment_id instead of paying again. If the response carries phase=insufficient_funds and nextAction=fund_account_or_raise_allowance, the payment cannot be retried until the account is funded or the agent budget raised \u2014 stop and tell the user the shortfall reported on the response."
|
|
3964
4050
|
},
|
|
3965
4051
|
resumeX402: {
|
|
3966
4052
|
summary: "Resume an x402 payment whose Haven-side authorization already succeeded but whose merchant retry did not complete.",
|
|
3967
|
-
behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). No new Haven payment is created.",
|
|
4053
|
+
behavior: "Accepts either resume_state or payment_id, validates the x402 details against the authorized funding, and retries the merchant request with the signed payment header (PAYMENT-SIGNATURE, plus legacy X-PAYMENT on EIP-3009 only; also params._meta on an MCP tools/call body). On the EIP-3009 scheme the retry also carries the agent-signed buyer tax declaration in X-Tax-Declaration when the owner opted this agent in and the declaration is available \u2014 signed locally by the same delegate key, sent to the seller only. No new Haven payment is created.",
|
|
3968
4054
|
nextActionGuidance: "Only call this after haven_get_payment_status reports nextAction=retry_original_x402_request \u2014 that means Haven's funding leg confirmed but no merchant response was ever recorded, most often because the process crashed between funding and the merchant retry. Any other nextAction reports a conflict instead of retrying, so do not call this speculatively. Do not start a new merchant session and do not pay again \u2014 that would pay twice for one resource."
|
|
3969
4055
|
},
|
|
3970
4056
|
// #1328: quoteMpp / payMpp / resumeMpp (the mpp_demo challenge/quote/resume
|
|
@@ -4626,7 +4712,11 @@ failed purchase reads as complete for fifteen minutes. If the merchant's
|
|
|
4626
4712
|
\`settlement_tx_hash\`): Haven verifies it on-chain, and the receipt then shows
|
|
4627
4713
|
the merchant's settlement, not only the funding transaction. (The SDK's own
|
|
4628
4714
|
\`haven_pay_x402\` tool does perform the merchant retry itself; that tool is
|
|
4629
|
-
not part of the hosted MCP surface.)
|
|
4715
|
+
not part of the hosted MCP surface.) On this SDK path, when the owner opted the
|
|
4716
|
+
agent in, the paid EIP-3009 retry also carries the agent-signed buyer tax
|
|
4717
|
+
declaration to the seller (\`X-Tax-Declaration\`, #3427) \u2014 signed locally by the
|
|
4718
|
+
same delegate key, omitted when unavailable or on the erc7710 scheme; nothing
|
|
4719
|
+
for you to sign or send. If the process
|
|
4630
4720
|
crashes after payment, a later \`mcp__haven__haven_get_payment_status\` call
|
|
4631
4721
|
may report \`nextAction: 'retry_original_x402_request'\` \u2014 only then call
|
|
4632
4722
|
\`mcp__haven__haven_resume_x402_payment\` with the preserved resume state or
|