@cmdoss/suipay-mcp 0.2.2-dev.3 → 0.2.2-dev.30

package/dist/{http-B4YTVw0k.d.ts → http-DvnvTrb3.d.ts}

@@ -3,8 +3,12 @@ import { McpAccessContext } from '@cmdoss/suipay-sdk/mcp/access-context';
 import { SettlementDTO } from '@cmdoss/suipay-sdk/buyer/settlement-dto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { GetObjectJson } from '@cmdoss/suipay-sdk/agent-sdk/reads';
-import { DelegatedKeySigner, DelegatedPayerDeps } from '@cmdoss/suipay-sdk/delegated-signer/payer';
+import { DelegatedKeySigner, DelegatedPayerDeps, GuardedSettleFields } from '@cmdoss/suipay-sdk/delegated-signer/payer';
 import { TraceRunResolver, TraceSink } from '@cmdoss/suipay-core/trace/types';
+import { PaidHttpRequest } from '@cmdoss/suipay-sdk/protocol/paid-http-request';
+import { Dialect } from '@cmdoss/suipay-sdk/protocol/types';
+import { PayOperationDeps } from '@cmdoss/suipay-sdk/pay-operation';
+import { PaymentState, NextAction } from '@cmdoss/suipay-core/errors';
 
 /**
  * Authenticated MCP request context (remote Streamable HTTP).
@@ -16,7 +20,7 @@ import { TraceRunResolver, TraceSink } from '@cmdoss/suipay-core/trace/types';
  *
  * Non-custodial: the gateway holds NO key that can spend. There is deliberately
  * no `decryptDelegateSeed` and no forwarded `sponsorAuthorization` here — the
- * `pay` tool only PREPARES an unsigned `spend_account::settle_policy_payment` transaction from the
+ * `pay` tool only PREPARES an unsigned `spend_account::settle_policy` / `settle_any_recipient` transaction from the
  * immutable grant snapshot (`prepareSpendAccountPayment`), and the client that
  * holds the delegate key signs locally and submits. Only signatures ever reach
  * the gateway. See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
@@ -40,7 +44,7 @@ interface McpAuthContext {
     /** Public, descriptive policy context. Never used as payment authority. */
     access?: McpAccessContext;
     /**
-     * When present, `pay` prepares unsigned spend_account::settle_policy_payment bytes for the
+     * When present, `pay` prepares unsigned spend_account::settle_policy / settle_any_recipient bytes for the
      * client-held delegate key to sign locally — no server-side decrypt or
      * signing. Stdio local V1 profile path remains when absent.
      */
@@ -79,6 +83,13 @@ interface McpConfig {
     minFunded: bigint;
     minMaxPerPayment: bigint;
     label: string;
+    /**
+     * Optional override of the gateway's published `ExclusionDirectory` id.
+     * When null, pay reads `GET /v1/delegate/deployment` and turns the resolver
+     * on only if that response names one. The id here does not choose the
+     * directory a settle uses — the offer's `registryIdentity` does.
+     */
+    exclusionDirectoryObjectId: string | null;
 }
 /**
  * CLI flags: `--local` / `-local`, `--dev` / `-dev`. Unknown args are ignored
@@ -249,6 +260,244 @@ interface TraceMcpHttpRequestInput {
  */
 declare function traceMcpHttpRequest(input: TraceMcpHttpRequestInput): Promise<Response>;
 
+/**
+ * Shared pay-request helpers.
+ *
+ * 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. `paidRequestInit` is the SDK helper
+ * that builds the one RequestInit replayed byte for byte on both calls.
+ */
+
+type PayResult = {
+    status: 'ok' | 'failed' | 'ambiguous';
+    /**
+     * `true` — settlement confirmed. `false` — money did not leave the
+     * account. `'unknown'` — execute/finality did not resolve; a retry can
+     * pay twice.
+     */
+    paid: boolean | 'unknown';
+    /** Whether money moved; always agrees with `paid`. */
+    paymentState?: PaymentState;
+    body?: unknown;
+    receipt?: unknown;
+    /** Registry code on a failed or ambiguous result. */
+    code?: string;
+    retryable?: boolean;
+    nextAction?: NextAction;
+    supportCode?: string;
+    detail?: string;
+    txDigest?: string;
+    paymentId?: string;
+    challengeId?: string;
+    httpStatus?: number;
+    responseClass?: 'unpaid_ok' | 'rejected' | 'unavailable';
+};
+
+/**
+ * SpendAccount PREPARE-only client (non-custodial MCP).
+ *
+ * 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` / `settle_any_recipient` 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.
+ *
+ * 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.
+ *
+ * See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
+ */
+
+type SharedObjectReader = (objectId: string) => Promise<{
+    owner?: unknown;
+} | null | undefined>;
+/**
+ * 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`.
+ */
+interface SpendAccountPrepareSession {
+    snapshot: GrantSnapshot;
+    /** SpendAccount package id (V2). */
+    packageId: 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` remains the final backstop for any
+     * spend the client later submits).
+     */
+    assertLive?: () => Promise<void>;
+}
+interface SpendAccountPayDeps {
+    fetchImpl?: typeof fetch;
+    /**
+     * Build only-transaction-kind bytes for the canonical guarded debit
+     * (`spend_account::settle_policy` / `settle_any_recipient`).
+     *
+     * The guarded-settle fields ({@link GuardedSettleFields}) are required on the
+     * fresh lineage: every delegate settle consumes the shared exclusion marker.
+     * Dropping them fails closed rather than building an unguarded call that no
+     * longer exists on chain.
+     */
+    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';
+    } & GuardedSettleFields) => Promise<{
+        kindBytes: string;
+    }>;
+    /**
+     * Resolve the per-recipient `RecipientRegistry` bound in the offer's exclusion
+     * directory (guarded offers only). Injected seam for tests; production
+     * leaves it unset and the prepare wires a live gRPC-backed resolver from the
+     * configured `ExclusionDirectory` id when present, else fails closed.
+     */
+    resolveExclusionRegistry?: PayOperationDeps['resolveExclusionRegistry'];
+    /**
+     * Read a shared object's owner so prepare binds the real initial version.
+     * Missing owner fails the prepare; version 1 is not a substitute.
+     */
+    readSharedObject?: SharedObjectReader;
+    /**
+     * 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 {
+    /**
+     * Unsigned `spend_account::settle_policy` / `settle_any_recipient` 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.
+     */
+    unsignedKindBytes: string;
+    delegateAddress: string;
+    packageId: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    /** On-chain policy id the pay is bound to. */
+    policyId: number | string;
+    coinType: string;
+    targetHash: string;
+    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: string;
+    /** Where the client (holding the key) sponsors and submits. */
+    submit: {
+        sponsorUrl: string;
+        executeUrl: string;
+        moveCallTarget: string;
+    };
+    /**
+     * ISO-8601 timestamp when this prepared operation expires. After this time the
+     * unsigned bytes are no longer valid and the client must re-call pay() for a
+     * fresh prepare. Derived from the offer TTL.
+     */
+    expiresAt: string;
+    /** Restated hard rule for the agent host. */
+    note: string;
+}
+interface PreparedPayment {
+    status: 'prepared';
+    paid: false;
+    signingRequest: SpendAccountSigningRequest;
+}
+/** 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;
+    coinType: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    policyId: number | string;
+    targetHash: string;
+    amount: string;
+    paymentIdHash: Uint8Array;
+    termsHash: Uint8Array;
+    poolInitialSharedVersion?: string;
+    grantInitialSharedVersion?: string;
+    clockInitialSharedVersion?: string;
+} & GuardedSettleFields): Promise<{
+    kindBytes: string;
+}>;
+/**
+ * Refuse blind signing: a client validating a sponsored transaction must be able
+ * to prove the sponsored bytes reconstruct the intended spend_account::settle_policy. Kept
+ * here (and exported) so both the client signer and its tests share one check.
+ */
+declare function verifySpendAccountPayReconstructs(bytes: string, expected: {
+    kindBytes: string;
+    packageId: string;
+    delegate: string;
+    poolObjectId: string;
+    grantObjectId: string;
+    amount: string;
+}): void;
+/**
+ * Prepare a delegate 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.
+ *
+ * Uses `resolvePayment` from the SDK pay-operation module for the
+ * shared offer-acquisition + authority-resolution pipeline (steps 1–5 + assertLive
+ * + hash derivation + buildPayKind). This module wraps that with MCP-specific
+ * concerns: trace events, dialect-mode ceiling check, and signing-request
+ * construction.
+ */
+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>;
+
 /**
  * Transport-neutral SuiPay MCP server + tool registry.
  * Used by stdio (index.ts) and Streamable HTTP (http.ts).
@@ -282,6 +531,14 @@ declare const TOOLS: readonly [{
                 readonly type: "object";
                 readonly description: "JSON request body for a POST. Sent as application/json and bound to the payment.";
             };
+            readonly file: {
+                readonly type: "string";
+                readonly description: "Absolute path under SUIPAY_MCP_FILE_ROOT (unset disables attach). Stdio POST only; requires fileField. Regular non-empty file whose decoded size fits the paid-body ceiling. Not a URL, FIFO, device, or path under ~/.suipay. Bytes fill json[fileField] as canonical base64.";
+            };
+            readonly fileField: {
+                readonly type: "string";
+                readonly description: "JSON key to set from file (e.g. contentBase64). Required with file. Pattern [A-Za-z][A-Za-z0-9_]{0,63}. Must not already be present on json.";
+            };
             readonly recipient: {
                 readonly type: "string";
                 readonly description: "Sui address you expect to be paid. The payment is refused, unsigned, if the prepared transaction pays anyone else.";
@@ -370,6 +627,13 @@ interface McpServerOptions {
      * does not already authorize.
      */
     resolveAgentHeld?: AgentHeldResolver;
+    /** Override the exclusion-registry resolver (tests / offline). */
+    resolveExclusionRegistry?: SpendAccountPayDeps['resolveExclusionRegistry'];
+    /**
+     * Wire that created this server. Hosted HTTP never forwards `file` into `pay`.
+     * Stdio is the default so existing tests stay local.
+     */
+    transport?: 'stdio' | 'http';
 }
 declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceHooks, options?: McpServerOptions): Server;
 
@@ -389,4 +653,4 @@ declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: Mcp
  */
 declare function handleSuipayMcpHttpRequest(req: Request, cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceRuntime | null, options?: McpServerOptions): Promise<Response>;
 
-export { type AgentHeldResolver as A, type McpConfig as M, PACKAGE_NAME as P, TOOLS as T, type McpAuthContext as a, type McpTraceHooks as b, type AgentHeldSettlement as c, MCP_TARGET_PRESETS as d, type McpEnvelope as e, type McpEnvelopeEntry as f, type McpServerOptions as g, type McpTarget as h, type McpTraceContext as i, type McpTraceRuntime as j, canonicalMcpRequestId as k, createServer as l, handleSuipayMcpHttpRequest as m, inspectMcpEnvelope as n, loadMcpConfig as o, parseMcpTargetFlag as p, resolveAgentHeldSettlement as q, resetAgentHeldProcessLedger as r, resolveMcpTarget as s, sameMcpGateway as t, traceMcpHttpRequest as u };
+export { type AgentHeldResolver as A, traceMcpHttpRequest as B, verifySpendAccountPayReconstructs as C, type McpConfig as M, PACKAGE_NAME as P, type SpendAccountSigningRequest as S, TOOLS as T, type McpAuthContext as a, type McpTraceHooks as b, type SpendAccountPayDeps as c, type AgentHeldSettlement as d, MCP_TARGET_PRESETS as e, type McpEnvelope as f, type McpEnvelopeEntry as g, type McpServerOptions as h, type McpTarget as i, type McpTraceContext as j, type McpTraceRuntime as k, type PreparedPayment as l, type SpendAccountPrepareResult as m, type SpendAccountPrepareSession as n, buildSpendAccountPayKind as o, canonicalMcpRequestId as p, createServer as q, handleSuipayMcpHttpRequest as r, inspectMcpEnvelope as s, loadMcpConfig as t, parseMcpTargetFlag as u, prepareSpendAccountPayment as v, resetAgentHeldProcessLedger as w, resolveAgentHeldSettlement as x, resolveMcpTarget as y, sameMcpGateway as z };

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-export { m as handleSuipayMcpHttpRequest } from './http-B4YTVw0k.js';
+export { r as handleSuipayMcpHttpRequest } from './http-DvnvTrb3.js';
 import '@cmdoss/suipay-core/policy/grant-target';
 import '@cmdoss/suipay-sdk/mcp/access-context';
 import '@cmdoss/suipay-sdk/buyer/settlement-dto';
@@ -6,3 +6,7 @@ import '@modelcontextprotocol/sdk/server/index.js';
 import '@cmdoss/suipay-sdk/agent-sdk/reads';
 import '@cmdoss/suipay-sdk/delegated-signer/payer';
 import '@cmdoss/suipay-core/trace/types';
+import '@cmdoss/suipay-sdk/protocol/paid-http-request';
+import '@cmdoss/suipay-sdk/protocol/types';
+import '@cmdoss/suipay-sdk/pay-operation';
+import '@cmdoss/suipay-core/errors';

package/dist/http.js

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

package/dist/index.d.ts

@@ -1,18 +1,19 @@
 import { Wallet } from '@cmdoss/suipay-core/chain/types';
-import { M as McpConfig, a as McpAuthContext, b as McpTraceHooks } from './http-B4YTVw0k.js';
-export { A as AgentHeldResolver, c as AgentHeldSettlement, d as MCP_TARGET_PRESETS, e as McpEnvelope, f as McpEnvelopeEntry, g as McpServerOptions, h as McpTarget, i as McpTraceContext, j as McpTraceRuntime, P as PACKAGE_NAME, T as TOOLS, k as canonicalMcpRequestId, l as createServer, m as handleSuipayMcpHttpRequest, n as inspectMcpEnvelope, o as loadMcpConfig, p as parseMcpTargetFlag, r as resetAgentHeldProcessLedger, q as resolveAgentHeldSettlement, s as resolveMcpTarget, t as sameMcpGateway, u as traceMcpHttpRequest } from './http-B4YTVw0k.js';
-import { GrantSnapshot } from '@cmdoss/suipay-core/policy/grant-target';
-export { resolveGrantTarget } from '@cmdoss/suipay-core/policy/grant-target';
-import { PaidHttpRequest } from '@cmdoss/suipay-sdk/protocol/paid-http-request';
-import { TraceSink } from '@cmdoss/suipay-core/trace/types';
-import { Dialect } from '@cmdoss/suipay-sdk/protocol/types';
+import { S as SpendAccountSigningRequest, M as McpConfig, a as McpAuthContext, b as McpTraceHooks, c as SpendAccountPayDeps } from './http-DvnvTrb3.js';
+export { A as AgentHeldResolver, d as AgentHeldSettlement, e as MCP_TARGET_PRESETS, f as McpEnvelope, g as McpEnvelopeEntry, h as McpServerOptions, i as McpTarget, j as McpTraceContext, k as McpTraceRuntime, P as PACKAGE_NAME, l as PreparedPayment, m as SpendAccountPrepareResult, n as SpendAccountPrepareSession, T as TOOLS, o as buildSpendAccountPayKind, p as canonicalMcpRequestId, q as createServer, r as handleSuipayMcpHttpRequest, s as inspectMcpEnvelope, t as loadMcpConfig, u as parseMcpTargetFlag, v as prepareSpendAccountPayment, w as resetAgentHeldProcessLedger, x as resolveAgentHeldSettlement, y as resolveMcpTarget, z as sameMcpGateway, B as traceMcpHttpRequest, C as verifySpendAccountPayReconstructs } from './http-DvnvTrb3.js';
 import { GetObjectJson, createReader } from '@cmdoss/suipay-sdk/agent-sdk/reads';
 import { DelegatedKeySigner, DelegatedPayerSession, DelegatedPayerConfig, DelegatedPayerDeps, SpendIntent, DelegatedPayResult } from '@cmdoss/suipay-sdk/delegated-signer/payer';
+import { PaidHttpRequest } from '@cmdoss/suipay-sdk/protocol/paid-http-request';
 import { createPayer } from '@cmdoss/suipay-sdk/agent-sdk/delegate-agent';
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export { resolveGrantTarget } from '@cmdoss/suipay-core/policy/grant-target';
 import '@cmdoss/suipay-sdk/mcp/access-context';
 import '@cmdoss/suipay-sdk/buyer/settlement-dto';
 import '@modelcontextprotocol/sdk/server/index.js';
+import '@cmdoss/suipay-core/trace/types';
+import '@cmdoss/suipay-sdk/protocol/types';
+import '@cmdoss/suipay-sdk/pay-operation';
+import '@cmdoss/suipay-core/errors';
 
 interface SuiPayCredentials {
     /** 64-hex Ed25519 seed. NEVER logged. */
@@ -68,208 +69,6 @@ declare function loadLocalSigner(): {
     signPersonalMessage: (message: Uint8Array) => Promise<string>;
 } | null;
 
-/**
- * Shared pay-request helpers.
- *
- * 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. `paidRequestInit` is the SDK helper
- * that builds the one RequestInit replayed byte for byte on both calls.
- */
-
-type PayResult = {
-    status: 'ok' | 'failed' | 'ambiguous';
-    /**
-     * `true` — settlement confirmed. `false` — money did not leave the
-     * account. `'unknown'` — execute/finality did not resolve; a retry can
-     * pay twice.
-     */
-    paid: boolean | 'unknown';
-    body?: unknown;
-    receipt?: unknown;
-    code?: string;
-    detail?: string;
-    txDigest?: string;
-};
-
-/**
- * SpendAccount PREPARE-only client (non-custodial MCP).
- *
- * 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.
- *
- * 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.
- *
- * See docs/design/mcp-non-custodial-signing.md and ADR-0013 §3.
- */
-
-/**
- * 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`.
- */
-interface SpendAccountPrepareSession {
-    snapshot: GrantSnapshot;
-    /** SpendAccount package id (V2). */
-    packageId: 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).
-     */
-    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 {
-    /**
-     * 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.
-     */
-    unsignedKindBytes: string;
-    delegateAddress: string;
-    packageId: string;
-    poolObjectId: string;
-    grantObjectId: string;
-    /** On-chain policy id the pay is bound to. */
-    policyId: number | string;
-    coinType: string;
-    targetHash: string;
-    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: string;
-    /** Where the client (holding the key) sponsors and submits. */
-    submit: {
-        sponsorUrl: string;
-        executeUrl: string;
-        moveCallTarget: string;
-    };
-    /**
-     * ISO-8601 timestamp when this prepared operation expires. After this time the
-     * unsigned bytes are no longer valid and the client must re-call pay() for a
-     * fresh prepare. Derived from the offer TTL.
-     */
-    expiresAt: string;
-    /** Restated hard rule for the agent host. */
-    note: string;
-}
-interface PreparedPayment {
-    status: 'prepared';
-    paid: false;
-    signingRequest: SpendAccountSigningRequest;
-}
-/** 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;
-    coinType: string;
-    poolObjectId: string;
-    grantObjectId: string;
-    policyId: number | string;
-    targetHash: string;
-    amount: string;
-    paymentIdHash: Uint8Array;
-    termsHash: Uint8Array;
-}): Promise<{
-    kindBytes: string;
-}>;
-/**
- * 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.
- */
-declare function verifySpendAccountPayReconstructs(bytes: string, expected: {
-    kindBytes: string;
-    packageId: string;
-    delegate: string;
-    poolObjectId: string;
-    grantObjectId: string;
-    amount: string;
-}): void;
-/**
- * Prepare a delegate 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.
- *
- * Uses `resolvePayment` from the SDK pay-operation module (SAIP-170) for the
- * shared offer-acquisition + authority-resolution pipeline (steps 1–5 + assertLive
- * + hash derivation + buildPayKind). This module wraps that with MCP-specific
- * concerns: trace events, dialect-mode ceiling check, and signing-request
- * construction.
- */
-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>;
-
 /**
  * Client-side completion of an MCP prepared payment.
  *
@@ -347,6 +146,8 @@ interface ToolDeps {
     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.
@@ -364,6 +165,8 @@ interface ToolDeps {
     };
     /** 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.
@@ -377,6 +180,8 @@ declare function pay(args: {
     url: string;
     method?: unknown;
     json?: unknown;
+    file?: unknown;
+    fileField?: unknown;
     recipient?: unknown;
     maxAmount?: unknown;
 }, cfg: McpConfig, deps?: ToolDeps): Promise<ToolResult>;
@@ -390,4 +195,4 @@ declare function loadBootProfile(load?: typeof loadPaymentProfile): {
 };
 declare function main(): Promise<void>;
 
-export { McpAuthContext, McpConfig, McpTraceHooks, type PreparedPayment, type SpendAccountPrepareResult, type SpendAccountPrepareSession, type SpendAccountSigningRequest, buildSpendAccountPayKind, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, pay, prepareSpendAccountPayment, receipts, settlePreparedMcpPayment, verifySpendAccountPayReconstructs };
+export { McpAuthContext, McpConfig, McpTraceHooks, SpendAccountSigningRequest, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, pay, receipts, settlePreparedMcpPayment };

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   loadBootProfile,
   main
-} from "./chunk-C2IYSV43.js";
+} from "./chunk-IH6HQD2V.js";
 import {
   MCP_TARGET_PRESETS,
   PACKAGE_NAME,
@@ -26,7 +26,7 @@ import {
   settlePreparedMcpPayment,
   traceMcpHttpRequest,
   verifySpendAccountPayReconstructs
-} from "./chunk-SRMAH6MK.js";
+} from "./chunk-YMOMYFKL.js";
 export {
   MCP_TARGET_PRESETS,
   PACKAGE_NAME,