@cmdoss/suipay-mcp 0.2.2 → 0.3.0-dev.1

package/dist/index.d.ts

@@ -1,19 +1,9 @@
-import { D as Dialect, G as GrantSnapshot, M as McpConfig, T as TraceSink, a as DelegatedKeySigner, b as GetObjectJson, c as DelegatedPayerSession, d as DelegatedPayerConfig, e as DelegatedPayerDeps, S as SpendIntent, f as DelegatedPayResult } from './http-BnIjiwcR.js';
-export { A as AgentHeldResolver, g as AgentHeldSettlement, h as McpEnvelope, i as McpEnvelopeEntry, j as McpServerOptions, k as McpTraceContext, l as McpTraceHooks, m as McpTraceRuntime, P as PACKAGE_NAME, n as TOOLS, o as canonicalMcpRequestId, p as createServer, q as handleSuipayMcpHttpRequest, r as inspectMcpEnvelope, s as loadMcpConfig, t as resetAgentHeldProcessLedger, u as resolveAgentHeldSettlement, v as resolveGrantTarget, w as traceMcpHttpRequest } from './http-BnIjiwcR.js';
+import { S as SpendAccountSigningRequest, P as PaidHttpRequest, D as DelegatedKeySigner, G as GetObjectJson, a as DelegatedPayerSession, b as DelegatedPayerConfig, c as DelegatedPayerDeps, d as SpendIntent, e as DelegatedPayResult, f as DelegationScope, C as CodeFor, N as NextAction, g as GrantPolicyBinding, h as PaymentAttemptLedger, i as DelegatedPayerLog, j as PreparedSettlementTerms, X as X402PayProgress, O as Offer, M as McpConfig, k as McpAuthContext, l as McpTraceHooks, m as SpendAccountPayDeps, n as createReader } from './http-BCFfQFIg.js';
+export { A as AgentHeldResolver, o as AgentHeldSettlement, p as MCP_TARGET_PRESETS, q as McpEnvelope, r as McpEnvelopeEntry, s as McpServerOptions, t as McpTarget, u as McpTraceContext, v as McpTraceRuntime, w as PACKAGE_NAME, x as PreparedPayment, y as SpendAccountPrepareResult, z as SpendAccountPrepareSession, T as TOOLS, B as buildSpendAccountPayKind, E as canonicalMcpRequestId, F as createServer, H as handleSuipayMcpHttpRequest, I as inspectMcpEnvelope, J as loadMcpConfig, K as parseMcpTargetFlag, L as prepareSpendAccountPayment, Q as resetAgentHeldProcessLedger, R as resolveAgentHeldSettlement, U as resolveGrantTarget, V as resolveMcpTarget, W as sameMcpGateway, Y as traceMcpHttpRequest, Z as verifySpendAccountPayReconstructs } from './http-BCFfQFIg.js';
+import { SuiGrpcClient } from '@mysten/sui/grpc';
+import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import '@modelcontextprotocol/sdk/server/index.js';
-import '@mysten/sui/keypairs/ed25519';
-
-type PaidHttpMethod = 'GET' | 'POST';
-interface PaidHttpRequest {
-    url: string;
-    method: PaidHttpMethod;
-    /** Exact wire bytes. Empty for GET. */
-    body: Uint8Array;
-    /** Normalized media type, or null when no body is sent. */
-    contentType: string | null;
-    /** `hashRequestBody(body)` — the single canonical body hash. */
-    bodyHash: string;
-}
 
 /** Holds a key and signs transaction bytes. Never leaves the payer. */
 interface Wallet {
@@ -53,14 +43,9 @@ interface PaymentProfile {
 /**
  * Load a historical V1 allowance payment profile, if present.
  * ADR-0010: not for new settlement. Callers that pay must refuse this profile
- * and point operators at shared_pool OAuth / delegated-signer flows.
+ * and point operators at delegate OAuth / delegated-signer flows.
  */
 declare function loadPaymentProfile(): PaymentProfile | null;
-/**
- * First authorization generates a local keypair and persists it at 0600.
- * Re-authorization reuses the stored key so a second key cannot orphan the grant.
- * Returns only the public identity.
- */
 declare function ensureLocalSigningKey(opts?: {
     label?: string;
 }): Promise<LocalSigningKeyIdentity>;
@@ -81,239 +66,519 @@ declare function loadLocalSigner(): {
 } | null;
 
 /**
- * Shared pay-request helpers.
+ * Client-side completion of an MCP prepared payment.
  *
- * The V1 allowance sponsored payer (ADR-0010) is retired; only the
- * rail-neutral request surface the SpendAccount payer depends on survives here:
- * the `PayResult` shape every payer returns and `paidRequestInit`, which builds
- * the one RequestInit replayed byte for byte on the unpaid and the paid call.
+ * Verifies the server-prepared kind (ADR-0016 §3) then settles through
+ * `payDelegatedSpendAccount` — the same path as direct signer mode. This module
+ * does not implement a second submitter.
+ *
+ * Two hops read a 402, and only one of them was verified. The prepare hop's kind
+ * is checked here; the payer then reads its own offer and builds the bytes it
+ * signs from that. So the verified terms are carried down as `preparedTerms` and
+ * re-asserted against the payer's offer before it signs. Without that carry, the
+ * two hops can price different recipients and nothing would notice.
  */
 
-type PayResult = {
-    status: 'ok' | 'failed' | 'ambiguous';
+declare function settlePreparedMcpPayment(args: {
+    signingRequest: SpendAccountSigningRequest;
     /**
-     * `true` — settlement confirmed. `false` — money did not leave the
-     * account. `'unknown'` — execute/finality did not resolve; a retry can
-     * pay twice.
+     * The same paid request that minted the prepare hop. Reconstructing from
+     * url+method alone drops a POST body and the settlement hop then prices
+     * (or 400s) a different request than the one the tool was called with.
      */
-    paid: boolean | 'unknown';
-    body?: unknown;
-    receipt?: unknown;
-    code?: string;
-    detail?: string;
-    txDigest?: string;
-};
+    request: PaidHttpRequest;
+    /**
+     * What this payment is supposed to move, sourced from the caller's intent —
+     * never re-read from the object being verified. Comparing a prepared kind
+     * against fields copied out of the same prepare response proves only that the
+     * response agrees with itself.
+     */
+    expected: {
+        amount: string;
+        recipient: string;
+        delegateAddress: string;
+    };
+    signer: DelegatedKeySigner;
+    getObjectJson: GetObjectJson;
+    session: DelegatedPayerSession;
+    cfg: DelegatedPayerConfig;
+    deps: DelegatedPayerDeps;
+    /**
+     * Agent-declared spend bound. Required when `deps.offerSecret` is absent
+     * (stdio local key): the HMAC is a gateway secret the agent must not need.
+     */
+    intent?: SpendIntent;
+}): Promise<DelegatedPayResult>;
 
 /**
- * SpendAccount PREPARE-only client (non-custodial MCP).
+ * The executable settlement a 402 carries so the agent needs no chain access.
  *
- * The remote MCP `pay` tool runs inside the gateway, which holds NO key that can
- * spend. So this module does not sign or submit: it PREPARES a payment and hands
- * back an unsigned `spend_account::settle_policy_payment` transaction plus everything the client
- * needs. The client — which holds the delegate key — sponsors, signs locally,
- * and submits through the same personal-message challenge → local-sign → submit flow the
- * REST/SDK delegate path uses. Only signatures ever reach the gateway; the
- * private key is never placed in an HTTP body, a bearer, or any header.
+ * ADR-0016 §2 says "the server prepares, the agent verifies, the agent signs".
+ * ADR-0015 shipped only the first half: the prepare path emitted a placeholder
+ * `poolInitialSharedVersion: '1'`, so its bytes described a payment instead of
+ * executing one, and an agent still had to make two full-node reads to build
+ * something submittable. These bytes are executable — the gateway resolves the
+ * real shared-object initial versions before it builds them.
  *
- * Flow: 402 Offer → request-binding → package/network SSOT →
- * resolveGrantTarget(snapshot, offer.targetHash) (pause/revoke gate) → cap/coin
- * checks → assertLive (fresh authority) → build unsigned kind bytes → return the
- * signing request. There is deliberately no sponsor call, no decrypt, no
- * signature, and no forwarded bearer here.
+ * This travels ALONGSIDE the offer on the 402 body, never inside it, exactly as
+ * `requestSchema` does (`src/gateway/app.ts`). The offer digest is a
+ * consensus-relevant wire shape whose fields go on chain via `terms_hash`;
+ * adding to it is a protocol change. A prepared settlement authorizes nothing
+ * on its own — it is unsigned bytes, worthless until the delegate's key signs
+ * them — so it has no business inside a signed digest.
  *
- * See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
+ * Every field here exists to let the agent REBUILD the same transaction kind
+ * offline and compare it byte for byte. Nothing here is trusted: see
+ * `verifyPreparedPayment` in `src/agent-sdk/verify-prepared-settlement.ts`
+ * for what an agent must check before it signs, and why what it can check from
+ * the 402 alone is sufficient.
  */
 
+/** Current prepared-settlement wire version. Bumped on any shape change. */
+declare const PREPARED_SETTLEMENT_VERSION: 1;
 /**
- * Read/prepare-only session for the non-custodial MCP pay tool. It carries the
- * immutable grant snapshot and an optional prepare-time live gate — and no key,
- * by construction. There is no `decryptDelegateSeed` and no `sponsorAuthorization`.
+ * An unsigned, executable settlement transaction plus everything needed to
+ * reconstruct it offline.
+ *
+ * `transactionBytes` is the full sponsored `TransactionData` — gas is already
+ * attached by the gateway's sponsor, so this is the ONE thing the agent signs.
+ * `transactionKindBytes` is the pre-sponsor programmable-transaction kind: the
+ * Move call and nothing else, which is what the agent rebuilds and compares.
  */
-interface SpendAccountPrepareSession {
-    snapshot: GrantSnapshot;
-    /** SpendAccount package id (V2). */
-    packageId: string;
+interface PreparedSettlement {
+    version: typeof PREPARED_SETTLEMENT_VERSION;
+    /** Base64 sponsored `TransactionData`. The agent signs exactly these bytes. */
+    transactionBytes: string;
+    /** Base64 pre-sponsor transaction kind (the Move call baseline). */
+    transactionKindBytes: string;
     /**
-     * Re-assert the grant is still live (not paused/revoked/expired) against fresh
-     * canonical state, invoked immediately before a signing request is handed back.
-     * Throw to abort. Optional; when absent, only the request-time snapshot gates
-     * the prepare (on-chain `spend_account::settle_policy_payment` remains the final backstop for any
-     * spend the client later submits).
+     * The address that must sign. Move asserts `ctx.sender() == grant.delegate`,
+     * so an agent that checks this equals its own address has the chain enforce
+     * that the named grant is one it may draw on — no `getObject` required.
      */
-    assertLive?: () => Promise<void>;
-}
-interface SpendAccountPayDeps {
-    fetchImpl?: typeof fetch;
-    /** Build only-transaction-kind bytes for spend_account::settle_policy_payment. */
-    buildPayKind?: (input: {
-        delegate: string;
-        coinType: string;
-        poolObjectId: string;
-        grantObjectId: string;
-        policyId: number | string;
-        targetHash: string;
-        amount: string;
-        paymentIdHash: Uint8Array;
-        termsHash: Uint8Array;
-        recipient?: string;
-        accessMode?: 'scoped' | 'open';
-    }) => Promise<{
-        kindBytes: string;
-    }>;
-    /**
-     * Live trace for this prepare. Purely observational: emission records what the
-     * canonical read decisions already returned — an event is written after a check
-     * passes and can never be the thing that lets the next step run.
-     */
-    trace?: SpendAccountPayTrace;
-}
-interface SpendAccountPayTrace {
-    sink: TraceSink;
-    traceId: string;
-    requestId: string | null;
-    buyerAccountId: string;
-    connectionId: string;
-    /** HMAC secret for signed cross-request context. Absent disables signing. */
-    secret?: string | null;
-    /** Injected clock, for tests. */
-    now?: () => number;
-}
-/** The unsigned payment the client signs locally and submits. */
-interface SpendAccountSigningRequest {
+    sender: string;
+    /** Deployed `suipay` package the call targets (normalized). */
+    packageId: string;
+    /** Fully-qualified `package::module::function` the call invokes. */
+    moveTarget: string;
     /**
-     * Unsigned `spend_account::settle_policy_payment` transaction-kind bytes (base64), sender set to
-     * `delegateAddress`. The client sponsors these for gas, signs with the delegate
-     * key, and submits — the gateway never receives the key.
+     * Delegation scope: `open` pays an arbitrary recipient, `scoped` an
+     * allowlist. This is the SCOPE discriminator (which pay function) — distinct
+     * from the x402 eligibility (`SpendAccountGrantKind`) and the budget cap. The
+     * `'open'`/`'scoped'` value strings are a frozen wire shape (parsed by
+     * `asPreparedSettlement`); the type only names the concept.
      */
-    unsignedKindBytes: string;
-    delegateAddress: string;
-    packageId: string;
+    accessMode: DelegationScope;
+    /** Shared `Account` the payment debits. */
     poolObjectId: string;
+    /** Shared `Grant` naming the delegate. */
     grantObjectId: string;
-    /** On-chain policy id the pay is bound to. */
-    policyId: number | string;
+    /** Real initial shared versions — the gap ADR-0015's placeholder `'1'` left. */
+    poolInitialSharedVersion: string;
+    grantInitialSharedVersion: string;
+    clockInitialSharedVersion: string;
+    /** On-chain policy id; `'0'` for an open grant. Decimal string (u64). */
+    policyId: string;
+    /** Coin type the call spends. Must equal the offer's asset. */
     coinType: string;
-    targetHash: string;
+    /** Atomic amount the call moves. Must equal the offer's amount. */
     amount: string;
-    /** Hex (no 0x) of the payment-id hash bound into the transaction. */
-    paymentIdHashHex: string;
-    /** Hex (no 0x) of the terms hash bound into the transaction. */
-    termsHashHex: string;
-    challengeId: string;
-    /** The exact paid request to replay after the client submits. */
-    resource: {
-        url: string;
-        method: string;
-    };
-    dialect: Dialect;
-    /** Recipient the agent requested (offer.payTo). */
+    /** Recipient the call pays. Must equal the offer's payTo. */
     recipient: string;
-    /** Where the client (holding the key) sponsors and submits. */
-    submit: {
-        sponsorUrl: string;
-        executeUrl: string;
-        moveCallTarget: string;
-    };
     /**
-     * Non-secret wallet/console handoff for hosts that cannot run a local signer:
-     * the delegate key signs and submits out of band there. Parameterized only by
-     * public Connection-manifest fields — never any secret.
+     * Fresh lineage (ADR-0043 Option B): settlement is MANDATORY-guarded, so the
+     * prepared call always consumes the offer's single-use exclusion marker before
+     * funds move. These four let the agent rebuild the SAME guarded kind offline
+     * and compare it byte for byte. The `ExclusionDirectory` the offer committed
+     * to (from its `registryIdentity`), read-only.
      */
-    handoffUrl: string;
-    /** Restated hard rule for the agent host. */
-    note: string;
+    exclusionDirectoryId: string;
+    /** The per-recipient `RecipientRegistry` the marker is claimed in (mutable). */
+    recipientRegistryId: string;
+    /** Real initial shared version of the exclusion directory. */
+    exclusionDirectoryInitialSharedVersion: string;
+    /** Real initial shared version of the recipient registry. */
+    recipientRegistryInitialSharedVersion: string;
+    /** Signed expiry (epoch-ms, decimal string) bound into the guarded settle. */
+    expiresAtMs: string;
+    /** Absolute URL to POST `{challengeId, signature, body}` to. */
+    payUrl: string;
 }
-interface PreparedPayment {
-    status: 'prepared';
-    paid: false;
-    signingRequest: SpendAccountSigningRequest;
+
+/**
+ * Connection-manifest → SDK session bridge.
+ *
+ * The dashboard hands an agent a non-secret "Connection manifest" after it
+ * authorizes a delegate key. Historically that manifest could NOT be passed to
+ * the SDK: it named the signer `agentAddress` (not `delegateAddress`), the asset
+ * by symbol (`"USDC"`, not the full `coinType`), and its policies by off-chain
+ * UUID — while the payer needs the full coin type and each policy's NUMERIC
+ * on-chain id + target hashes (`GrantPolicyBinding`). This module closes that
+ * mismatch two ways:
+ *
+ *   1. {@link AgentConnectionManifest} — the SDK-consumable shape a corrected
+ *      console emits directly (delegate address, full coin type, numeric policy
+ *      ids + target hashes). {@link manifestToSession} turns it, plus an agent
+ *      key, into a ready `DelegatedPayerSession` — no protocol reverse-engineering
+ *      and no on-chain lookups.
+ *
+ *   2. {@link dashboardManifestToAgentManifest} — a bridge from the legacy
+ *      console shape, resolving asset→coinType and (for scoped grants) UUID→
+ *      numeric policy binding through injected resolvers.
+ *
+ * Every failure is a typed, caller-safe error (never a thrown internal): a
+ * malformed or legacy manifest that cannot be resolved fails loudly, not
+ * silently.
+ */
+
+/**
+ * A manifest or session that cannot be paid from. Nothing was signed, so the
+ * money state is always `not_charged`. Branch on `code`; `reason` names the
+ * internal check for logs.
+ */
+interface ManifestError {
+    code: CodeFor<'sdk'>;
+    detail: string;
+    paymentState: 'not_charged';
+    retryable: boolean;
+    nextAction: NextAction;
 }
-/** Prepared signing request, or a canonical failure (never a spend). */
-type SpendAccountPrepareResult = PreparedPayment | PayResult;
-/** Default kind builder (no chain client — pure PTB). */
-declare function buildSpendAccountPayKind(input: {
-    packageId: string;
-    delegate: string;
+type ManifestResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: ManifestError;
+};
+/**
+ * A manifest policy binding. `onChainPolicyId` is always a validated u64 DECIMAL
+ * STRING — never a JS number — so `BigInt(onChainPolicyId)` on the money path
+ * (`spend_account::settle_policy`) is exact. A `u64` policy id can exceed `2^53`, past which
+ * a JS number loses precision and would bind the WRONG on-chain policy; carrying
+ * the string preserves every id exactly.
+ */
+type AgentPolicyBinding = Omit<GrantPolicyBinding, 'onChainPolicyId'> & {
+    onChainPolicyId: string;
+};
+/** One grant's SDK-consumable binding: everything the payer needs to settle. */
+interface AgentSessionBinding {
+    /** Display asset symbol (informational; `coinType` is authoritative). */
+    asset: string;
+    /** Full coin struct type, e.g. `0x..::usdc::USDC`. Required for pay. */
     coinType: string;
     poolObjectId: string;
     grantObjectId: string;
-    policyId: number | string;
-    targetHash: string;
-    amount: string;
-    paymentIdHash: Uint8Array;
-    termsHash: Uint8Array;
-}): Promise<{
-    kindBytes: string;
-}>;
+    /** `open` = capped, no allowlist; `scoped` = policy-bound. */
+    accessMode: 'scoped' | 'open';
+    /** Grant-level session cap (atomic); null/undefined = unlimited. */
+    sessionCap?: string | null;
+    /** Grant-level per-payment ceiling (atomic); null/undefined = unlimited. */
+    maxPerPayment?: string | null;
+    /** On-chain policy ids (u64 strings) + target hashes. Empty for open grants. */
+    policies: AgentPolicyBinding[];
+}
+/** Which grant to drive when a manifest carries several. */
+interface SessionSelector {
+    grantObjectId?: string;
+    asset?: string;
+    coinType?: string;
+}
+/** @deprecated Renamed to {@link AgentSessionBinding}. */
+type AgentGrantBinding = AgentSessionBinding;
+/** @deprecated Renamed to {@link SessionSelector}. */
+type GrantSelector = SessionSelector;
+
 /**
- * Refuse blind signing: a client validating a sponsored transaction must be able
- * to prove the sponsored bytes reconstruct the intended spend_account::settle_policy_payment. Kept
- * here (and exported) so both the client signer and its tests share one check.
+ * Key + gateway URL → a ready delegated-pay session.
+ *
+ * This module is the point of `docs/decisions/ADR-0016-delegate-key-sole-agent-input.md`
+ * §1. Before it, an agent needed a connection manifest — network, package id,
+ * pool id, grant id, caps, expiry — copied out of the console at authorize time
+ * and liable to go stale the moment the owner tightened a cap or the operator
+ * rotated a package. After it, the agent is handed one secret and one URL, and
+ * everything else is resolved from the chain's own projection at startup.
+ *
+ * The order is forced by the protocol. A bootstrap signature binds `network` and
+ * `packageId`, which the gateway reconstructs from its own config, so the agent
+ * must know them before it can sign anything that will verify. It learns them
+ * from the gateway's public deployment constants — the same two values every 402
+ * offer already carries in the clear — and only then signs.
+ *
+ * Nothing here spends. It resolves authority and hands back a session; the
+ * payment is still built and signed later, on this machine, by
+ * `payDelegatedSpendAccount` with a key that never leaves the process.
  */
-declare function verifySpendAccountPayReconstructs(bytes: string, expected: {
-    kindBytes: string;
+
+/** The gateway's public deployment constants. */
+interface GatewayDeployment {
+    network: string;
     packageId: string;
-    delegate: string;
-    poolObjectId: string;
-    grantObjectId: string;
-    amount: string;
-}): void;
+    /**
+     * The canonical `ExclusionDirectory` object id, present only while the gateway
+     * mints guarded offers. Absent means every offer is unguarded and no registry
+     * ever needs resolving.
+     *
+     * It enables the resolver; it is never resolved against. A guarded settle
+     * resolves the directory the OFFER committed to under the HMAC, so a gateway
+     * cannot point a payer at a directory of its choosing by answering here.
+     */
+    exclusionDirectoryObjectId?: string;
+}
+
 /**
- * Prepare a shared_pool payment WITHOUT signing. Reads the 402 offer, binds it,
- * gates on the immutable grant snapshot + a fresh authority check, builds the
- * unsigned transaction, and returns a signing request. The client holding the
- * delegate key signs locally and submits. This function never decrypts, signs,
- * sponsors, or submits.
+ * A delegate key and a gateway URL, and the agent can pay.
+ *
+ * `resolvePayerSession` already turned a key into a pay *session*
+ * (ADR-0016 §1). What it did not do was assemble the rest of what
+ * `payDelegatedSpendAccount` demands, so a real agent still had to supply four
+ * things its key does not carry: the gateway's own HMAC secret, a fullnode
+ * connection to confirm settlement, a second fullnode read for live
+ * shared-object versions, and a personal-message signer for the sponsor's
+ * personal-message challenge, separate from the transaction signer. This module is
+ * where those four go.
+ *
+ * Where each one went, and why that is safe:
+ *
+ *  - **The gateway's HMAC secret is gone, not relocated.** It authenticated the
+ *    offer's issuer to the agent — but the issuer is the same gateway the agent
+ *    is paying, reached over TLS at an origin the payer pins, so a gateway that
+ *    wanted to overcharge never needed to forge its own offer. What replaces it
+ *    is a bound the gateway cannot see: the agent's own {@link SpendIntent}.
+ *  - **Both fullnode reads stay with the AGENT**, against a public Sui fullnode
+ *    derived from the network the gateway reports. They are not proxied through
+ *    the gateway, because their whole value is that they are independent of it:
+ *    an agent that asked the gateway whether the gateway's transaction settled
+ *    would be verifying nothing. The gateway supplies no input here it could
+ *    not already supply; what it never gains is the ability to answer for the
+ *    chain.
+ *  - **The personal-message challenge signer is the same key**, taken from the one
+ *    keypair the agent already holds. It was never a second credential, only a
+ *    second callback the caller had to wire.
+ *
+ * The key never leaves this process, and the gateway never gains the ability to
+ * spend: every payment is still built here, checked here against the chain's
+ * own view of the grant, and signed here.
  */
-declare function prepareSpendAccountPayment(args: {
-    url: string;
-    /** The one normalized paid request, replayed byte for byte after signing. */
-    request?: PaidHttpRequest;
-    session: SpendAccountPrepareSession;
-    cfg: McpConfig;
-    deps?: SpendAccountPayDeps;
-    /** Preferred dialect when the 402 advertises both (default mpp). */
-    preferredDialect?: Dialect;
-}): Promise<SpendAccountPrepareResult>;
 
+interface PayerOptions {
+    /** Gateway origin, e.g. `https://gateway.suipay.dev`. */
+    gatewayUrl: string;
+    /**
+     * The delegate key. Used for the bootstrap signature, the sponsor
+     * personal-message challenge, and the payment signature — one key, three uses, none
+     * of which leave this process.
+     */
+    keypair: Ed25519Keypair;
+    /** Which grant to drive when the delegate holds several. */
+    select?: GrantSelector;
+    /** Injectable fetch (tests / custom transports). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Sui fullnode for the agent's own on-chain reads. Defaults to the public
+     * fullnode for the network the gateway reports. An operator running a private
+     * network sets it; an agent does not need to.
+     */
+    fullnodeUrl?: string;
+    /**
+     * A chain transport to read through, for a caller that already has one (or a
+     * test). The seam is the CLIENT, not the individual reads: an option to
+     * supply `getSettledTx` directly would let a caller point settlement
+     * confirmation at something that is not the chain.
+     */
+    client?: SuiGrpcClient;
+    /**
+     * Skip deployment discovery by supplying the constants directly. Same escape
+     * hatch `resolvePayerSession` offers.
+     */
+    deployment?: GatewayDeployment;
+    /**
+     * Durable payment-attempt ledger. Defaults to an in-process one, which is
+     * exactly-once for the lifetime of THIS process. An agent that must survive a
+     * restart mid-payment supplies a durable one.
+     */
+    paymentLedger?: PaymentAttemptLedger;
+    /**
+     * The gateway's HMAC secret, when the caller legitimately holds one (an
+     * operator running its own gateway). An external agent leaves it unset and
+     * relies on its spend intent; see {@link SpendIntent}.
+     */
+    offerSecret?: string;
+    /**
+     * The canonical `ExclusionDirectory` object id, so this payer can build a
+     * GUARDED delegate settle for a guarded offer out of the box.
+     *
+     * Optional: `createPayer` otherwise takes it from `GET /v1/delegate/deployment`,
+     * which discovery already calls, so an agent holding only a key and a gateway
+     * URL needs no out-of-band value to pay a guarded offer. Pass it to pin the
+     * behaviour against a gateway that does not publish one.
+     *
+     * When present from either source, `createPayer` constructs the
+     * `resolveExclusionRegistry` dependency bound to this payer's own gRPC reader
+     * (the same client that reads the grant and confirms settlement), which
+     * resolves the per-recipient `RecipientRegistry` from the directory's
+     * dynamic-field binding at settle-build time. When absent from BOTH, a guarded
+     * offer FAILS CLOSED (BUILD_FAILED) — the payer never builds an unguarded
+     * settle, which would reopen the cross-rail double-settle hole and be rejected
+     * by the gateway's self-settled verifier anyway. An unguarded offer never
+     * resolves a registry, so it is unaffected either way.
+     */
+    exclusionDirectoryObjectId?: string;
+    /** Server-side log port for internal failure detail. Never reaches a result. */
+    log?: DelegatedPayerLog;
+}
+/** Result of `payer.pay`. Same shape as the internal settlement result. */
+type PayResult = DelegatedPayResult;
+
+/** One paid request. `intent` is what this agent says it is buying. */
+interface PayInput {
+    method?: string;
+    body?: string | Uint8Array;
+    contentType?: string;
+    /**
+     * Required. Without it nothing bounds what the offer may charge, and the
+     * payer refuses — the whole point of the key-only path is that the ceiling
+     * comes from the agent, not from a secret it should not hold.
+     */
+    intent: SpendIntent;
+    /**
+     * Terms the caller has ALREADY verified, which the offer this payer reads
+     * must price exactly or nothing is signed.
+     *
+     * Distinct from {@link SpendIntent}, and not a replacement for it: `intent`
+     * is a ceiling — it refuses an offer that charges MORE — while this is an
+     * equality. A caller that showed a person a specific price, or checked a
+     * server-prepared kind, is not agreeing to "that or less from anyone in the
+     * catalogue"; it is agreeing to one exact payment. The payer fetches its own
+     * offer immediately before signing, so without this that final offer is only
+     * ceiling-bounded and could legitimately differ from the one the caller
+     * verified.
+     *
+     * Optional, so every existing caller keeps ceiling semantics unchanged.
+     */
+    preparedTerms?: PreparedSettlementTerms;
+    /**
+     * Which dialect to pay in. Default `'mpp'`, unchanged: the sponsor executes
+     * the pay and the payer presents a finalized proof. `'x402'` signs the pay
+     * with the offer's pinned sponsor gas and presents it as `PAYMENT-SIGNATURE`;
+     * the gateway co-signs and submits (ADR-0045). Before reserving anything,
+     * x402 refuses an open-recipient grant and an offer without the pins.
+     */
+    dialect?: 'mpp' | 'x402';
+    /**
+     * x402 only: each step as it happens (built, signed, then presented and
+     * answered per presentation). Called synchronously; a throw is logged and
+     * never affects the payment.
+     */
+    onX402Progress?: (event: X402PayProgress) => void;
+}
+interface Payer {
+    /** The delegate's own address, derived from the key it holds. */
+    address: string;
+    /** Deployment constants the gateway published and the bootstrap bound. */
+    deployment: GatewayDeployment;
+    /** The grant this agent will pay from, as resolved and then verified on chain. */
+    grant: AgentGrantBinding;
+    /** The assembled session; exposed so a caller can inspect what it will sign with. */
+    session: DelegatedPayerSession;
+    /** Pay for one resource and return its response. */
+    pay(url: string, input: PayInput): Promise<PayResult>;
+    /**
+     * Verify a 402 prepared settlement against the grant this agent resolved.
+     * Always pins {@link Payer.grant} — a settlement drawn on another
+     * buyer's grant is refused. Callers with no resolved grant still use
+     * {@link verifyPreparedPayment} unpinned.
+     */
+    verifySettlement(prepared: unknown, offer: Offer): Promise<PreparedSettlement>;
+}
 /**
- * Client-side completion of an MCP prepared payment.
+ * Create a payer from its key and a gateway URL.
  *
- * Verifies the server-prepared kind (ADR-0016 §3) then settles through
- * `payDelegatedSpendAccount` — the same path as direct signer mode. This module
- * does not implement a second submitter.
+ * The call sequence, all of it derivable from those two inputs:
+ *   1. `GET /v1/delegate/deployment` — network, package id, and the exclusion
+ *      directory id when guarded minting is on. All in the clear.
+ *   2. `GET /v1/delegate/grants`, signed by the key — the grants naming it.
+ *   3. an unsigned `getObject` on the resolved grant, against a public
+ *      fullnode — the agent's own check that the grant is its own.
  *
- * Two hops read a 402, and only one of them was verified. The prepare hop's kind
- * is checked here; the payer then reads its own offer and builds the bytes it
- * signs from that. So the verified terms are carried down as `preparedTerms` and
- * re-asserted against the payer's offer before it signs. Without that carry, the
- * two hops can price different recipients and nothing would notice.
+ * Typed failure, never a throw: an agent that cannot verify its own authority
+ * must refuse to sign, not proceed on the gateway's word.
  */
+declare function createPayer(options: PayerOptions): Promise<ManifestResult<Payer>>;
 
-declare function settlePreparedMcpPayment(args: {
-    signingRequest: SpendAccountSigningRequest;
+interface StdioLoginOptions {
+    consoleUrl: string;
+    gatewayUrl: string;
+    identity: {
+        delegateAddress: string;
+        publicKeyHex: string;
+    };
+    label?: string;
+    timeoutMs?: number;
+    openBrowser?: boolean;
+    onUrl?: (connectUrl: string) => void;
+}
+interface StartedStdioLogin {
+    connectUrl: string;
+    port: number;
+    connectState: string;
+    done: Promise<void>;
+    close: () => void;
+}
+/**
+ * Bind the loopback listener and return the console URL immediately.
+ * The wallet callback is awaited on `done`, not on the MCP tool call.
+ */
+declare function startStdioLogin(opts: StdioLoginOptions): Promise<StartedStdioLogin>;
+
+type ToolResult = CallToolResult;
+
+interface ToolDeps {
+    fetchImpl?: typeof fetch;
+    profileLoader?: () => PaymentProfile | null;
+    /** Remote HTTP auth (grant + scope + optional shared-pool pay session). */
+    auth?: McpAuthContext;
+    /** Wire transport. Hosted HTTP never reads a buyer path. */
+    transport?: 'stdio' | 'http';
     /**
-     * What this payment is supposed to move, sourced from the caller's intent —
-     * never re-read from the object being verified. Comparing a prepared kind
-     * against fields copied out of the same prepare response proves only that the
-     * response agrees with itself.
+     * Proxy-resolved live trace for this MCP request. Observation only: it never
+     * changes which rail runs, what is paid, or whether a payment is allowed.
      */
-    expected: {
-        amount: string;
-        recipient: string;
-        delegateAddress: string;
+    trace?: McpTraceHooks;
+    /**
+     * Agent-held delegate key. Present only in the process that stores the
+     * key — never on the gateway. When set after a server-side prepare, `pay`
+     * verifies the prepared kind and settles through `payDelegatedSpendAccount`.
+     */
+    agentHeld?: {
+        signer: DelegatedKeySigner;
+        getObjectJson: GetObjectJson;
+        payerDeps: DelegatedPayerDeps;
     };
-    signer: DelegatedKeySigner;
-    getObjectJson: GetObjectJson;
-    session: DelegatedPayerSession;
-    cfg: DelegatedPayerConfig;
-    deps: DelegatedPayerDeps;
+    /** Override the prepare-time kind builder (tests / offline). */
+    buildPayKind?: SpendAccountPayDeps['buildPayKind'];
+    /** Override the exclusion-registry resolver (tests / offline). */
+    resolveExclusionRegistry?: SpendAccountPayDeps['resolveExclusionRegistry'];
     /**
-     * Agent-declared spend bound. Required when `deps.offerSecret` is absent
-     * (stdio local key): the HMAC is a gateway secret the agent must not need.
+     * Stdio login surfaces the console URL (MCP progress notification). The URL
+     * carries the delegate address only — never the seed.
      */
-    intent?: SpendIntent;
-}): Promise<DelegatedPayResult>;
+    onUrl?: (url: string) => void;
+    createPayer?: typeof createPayer;
+    createReader?: typeof createReader;
+    startStdioLogin?: typeof startStdioLogin;
+}
+declare function pay(args: {
+    url: string;
+    method?: unknown;
+    json?: unknown;
+    file?: unknown;
+    fileField?: unknown;
+    recipient?: unknown;
+    maxAmount?: unknown;
+}, cfg: McpConfig, deps?: ToolDeps): Promise<ToolResult>;
+declare function receipts(args: {
+    challengeId?: string;
+}, cfg: McpConfig, deps?: ToolDeps): Promise<ToolResult>;
 
 declare function loadBootProfile(load?: typeof loadPaymentProfile): {
     profile: ReturnType<typeof loadPaymentProfile>;
@@ -321,4 +586,4 @@ declare function loadBootProfile(load?: typeof loadPaymentProfile): {
 };
 declare function main(): Promise<void>;
 
-export { type PreparedPayment, type SpendAccountPrepareResult, type SpendAccountPrepareSession, type SpendAccountSigningRequest, buildSpendAccountPayKind, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, prepareSpendAccountPayment, settlePreparedMcpPayment, verifySpendAccountPayReconstructs };
+export { McpAuthContext, McpConfig, McpTraceHooks, SpendAccountSigningRequest, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, pay, receipts, settlePreparedMcpPayment };