@mysten-incubation/suipay-mcp 0.0.0-stage → 0.3.0-dev.0

package/dist/http.d.ts

@@ -0,0 +1,4 @@
+export { I as handleSuipayMcpHttpRequest } from './http-15g02zyM.js';
+import '@modelcontextprotocol/sdk/server/index.js';
+import '@mysten/sui/keypairs/ed25519';
+import 'node:crypto';

package/dist/http.js

@@ -0,0 +1,6 @@
+import {
+  handleSuipayMcpHttpRequest
+} from "./chunk-CXM7PELK.js";
+export {
+  handleSuipayMcpHttpRequest
+};

package/dist/index.d.ts

@@ -0,0 +1,604 @@
+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, O as OfferPublicKeySource, i as DelegatedPayerLog, j as PreparedSettlementTerms, X as X402PayProgress, k as Offer, M as McpConfig, l as McpAuthContext, m as McpTraceHooks, n as SpendAccountPayDeps, o as createReader } from './http-15g02zyM.js';
+export { A as AgentHeldResolver, p as AgentHeldSettlement, q as MCP_TARGET_PRESETS, r as McpEnvelope, s as McpEnvelopeEntry, t as McpServerOptions, u as McpTarget, v as McpTraceContext, w as McpTraceRuntime, x as PACKAGE_NAME, y as PreparedPayment, z as SpendAccountPrepareResult, B as SpendAccountPrepareSession, T as TOOLS, E as buildSpendAccountPayKind, F as canonicalMcpRequestId, H as createServer, I as handleSuipayMcpHttpRequest, J as inspectMcpEnvelope, K as loadMcpConfig, L as parseMcpTargetFlag, Q as prepareSpendAccountPayment, R as resetAgentHeldProcessLedger, U as resolveAgentHeldSettlement, V as resolveGrantTarget, W as resolveMcpTarget, Y as sameMcpGateway, Z as traceMcpHttpRequest, _ as verifySpendAccountPayReconstructs } from './http-15g02zyM.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 'node:crypto';
+
+/** Holds a key and signs transaction bytes. Never leaves the payer. */
+interface Wallet {
+    readonly address: string;
+    signTransaction(txBytes: string): Promise<string>;
+}
+
+interface SuiPayCredentials {
+    /** 64-hex Ed25519 seed. NEVER logged. */
+    delegatePrivateKey: string;
+    delegatePublicKeyHex: string;
+    delegateAddress: string;
+    ownerAddress: string;
+    allowanceId: string;
+    packageId: string;
+    coinType: string;
+    /** Allowance recipient = the resource's payTo. */
+    recipient: string;
+    gatewayUrl: string;
+    network: string;
+    maxPerPayment: string;
+    label?: string;
+    createdAt: string;
+    version: 1;
+}
+/** Public-only view. Never includes the seed. */
+interface LocalSigningKeyIdentity {
+    delegateAddress: string;
+    publicKeyHex: string;
+}
+type SignerSource = 'secret-key' | 'credentials' | 'mnemonic';
+interface PaymentProfile {
+    creds: SuiPayCredentials;
+    wallet: Wallet;
+    source: SignerSource;
+}
+/**
+ * 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 delegate OAuth / delegated-signer flows.
+ */
+declare function loadPaymentProfile(): PaymentProfile | null;
+declare function ensureLocalSigningKey(opts?: {
+    label?: string;
+}): Promise<LocalSigningKeyIdentity>;
+/**
+ * The persisted agent-held delegate signer, or null when this process holds no
+ * key. Reads only — it never mints.
+ *
+ * `ensureLocalSigningKey` is the provisioning entry point and mints on first
+ * authorization, which is right there and wrong here: `pay` runs on hosts that
+ * are not the agent (the gateway runs the same tool code), and minting on a read
+ * path would write key material onto a machine that must hold none, then quietly
+ * fail to match any grant. Absent key → no settlement, by construction.
+ */
+declare function loadLocalSigner(): {
+    address: string;
+    signTransaction: (txBytes: string) => Promise<string>;
+    signPersonalMessage: (message: Uint8Array) => Promise<string>;
+} | null;
+
+/**
+ * Client-side completion of an MCP prepared payment.
+ *
+ * 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.
+ */
+
+declare function settlePreparedMcpPayment(args: {
+    signingRequest: SpendAccountSigningRequest;
+    /**
+     * 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.
+     */
+    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;
+        /**
+         * From the prepare hop's offer. Never from `submit.moveCallTarget`:
+         * that target is the kind this function is checking.
+         */
+        refundable?: boolean;
+        refundConfigId?: string;
+        chainId?: number;
+        decideWindowMs?: number;
+        refundWindowMs?: number;
+        paymentSalt?: string;
+    };
+    signer: DelegatedKeySigner;
+    getObjectJson: GetObjectJson;
+    session: DelegatedPayerSession;
+    cfg: DelegatedPayerConfig;
+    deps: DelegatedPayerDeps;
+    /**
+     * Agent-declared spend bound (optional additional ceiling, ADR-0073 D1).
+     */
+    intent?: SpendIntent;
+}): Promise<DelegatedPayResult>;
+
+/**
+ * The executable settlement a 402 carries so the agent needs no chain access.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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;
+/**
+ * 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 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;
+    /**
+     * 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.
+     */
+    sender: string;
+    /** Deployed `suipay` package the call targets (normalized). */
+    packageId: string;
+    /** Fully-qualified `package::module::function` the call invokes. */
+    moveTarget: string;
+    /**
+     * 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.
+     */
+    accessMode: DelegationScope;
+    /** Shared `Account` the payment debits. */
+    poolObjectId: string;
+    /** Shared `Grant` naming the delegate. */
+    grantObjectId: 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;
+    /** Atomic amount the call moves. Must equal the offer's amount. */
+    amount: string;
+    /** Recipient the call pays. Must equal the offer's payTo. */
+    recipient: string;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * Initial shared version of the RefundConfig, only when the kind opens a
+     * vault. The offer names the object; this version is what the rebuild must
+     * use so the kind bytes match. Absent on an immediate payment.
+     */
+    refundConfigInitialSharedVersion?: string;
+    /** Absolute URL to POST `{challengeId, signature, body}` to. */
+    payUrl: string;
+}
+
+/**
+ * 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;
+}
+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;
+    /** `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;
+
+/**
+ * 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.
+ */
+
+/** The gateway's public deployment constants. */
+interface GatewayDeployment {
+    network: string;
+    packageId: string;
+    /**
+     * 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;
+}
+
+/**
+ * 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.
+ */
+
+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;
+    /**
+     * Gateway offer-signing public key material or resolver (ADR-0073 D1, D3).
+     * Used to verify the offer's asymmetric signature before signing.
+     */
+    offerVerificationKeys?: OfferPublicKeySource;
+    /**
+     * 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>;
+}
+/**
+ * Create a payer from its key and a gateway URL.
+ *
+ * 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.
+ *
+ * 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>>;
+
+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';
+    /**
+     * 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.
+     */
+    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;
+    };
+    /** Override the prepare-time kind builder (tests / offline). */
+    buildPayKind?: SpendAccountPayDeps['buildPayKind'];
+    /** Override the exclusion-registry resolver (tests / offline). */
+    resolveExclusionRegistry?: SpendAccountPayDeps['resolveExclusionRegistry'];
+    /**
+     * Stdio login surfaces the console URL (MCP progress notification). The URL
+     * carries the delegate address only — never the seed.
+     */
+    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>;
+    unreadable: boolean;
+};
+declare function main(): Promise<void>;
+
+export { McpAuthContext, McpConfig, McpTraceHooks, SpendAccountSigningRequest, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, pay, receipts, settlePreparedMcpPayment };

package/dist/index.js

@@ -0,0 +1,56 @@
+import {
+  loadBootProfile,
+  main
+} from "./chunk-47YNZDCC.js";
+import {
+  MCP_TARGET_PRESETS,
+  PACKAGE_NAME,
+  TOOLS,
+  buildSpendAccountPayKind,
+  canonicalMcpRequestId,
+  createServer,
+  ensureLocalSigningKey,
+  handleSuipayMcpHttpRequest,
+  inspectMcpEnvelope,
+  loadLocalSigner,
+  loadMcpConfig,
+  parseMcpTargetFlag,
+  pay,
+  prepareSpendAccountPayment,
+  receipts,
+  resetAgentHeldProcessLedger,
+  resolveAgentHeldSettlement,
+  resolveGrantTarget,
+  resolveMcpTarget,
+  sameMcpGateway,
+  settlePreparedMcpPayment,
+  traceMcpHttpRequest,
+  verifySpendAccountPayReconstructs
+} from "./chunk-CXM7PELK.js";
+export {
+  MCP_TARGET_PRESETS,
+  PACKAGE_NAME,
+  TOOLS,
+  buildSpendAccountPayKind,
+  canonicalMcpRequestId,
+  createServer,
+  ensureLocalSigningKey,
+  handleSuipayMcpHttpRequest,
+  inspectMcpEnvelope,
+  loadBootProfile,
+  loadLocalSigner,
+  loadMcpConfig,
+  main,
+  parseMcpTargetFlag,
+  pay,
+  prepareSpendAccountPayment,
+  receipts,
+  resetAgentHeldProcessLedger,
+  resolveAgentHeldSettlement,
+  resolveGrantTarget,
+  resolveMcpTarget,
+  sameMcpGateway,
+  settlePreparedMcpPayment,
+  traceMcpHttpRequest,
+  verifySpendAccountPayReconstructs
+};