@cmdoss/suipay-mcp 0.2.0 → 0.2.2-dev.0

package/dist/http-B4YTVw0k.d.ts

@@ -0,0 +1,392 @@
+import { GrantSnapshot } from '@cmdoss/suipay-core/policy/grant-target';
+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 { TraceRunResolver, TraceSink } from '@cmdoss/suipay-core/trace/types';
+
+/**
+ * Authenticated MCP request context (remote Streamable HTTP).
+ * Bearer is required on /mcp; tools enforce scope from the resolved grant.
+ */
+
+/**
+ * Read/prepare-only shared-pool context for an authenticated MCP bearer.
+ *
+ * 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
+ * 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.
+ */
+interface McpSpendAccountPayAuth {
+    snapshot: GrantSnapshot;
+    packageId: string;
+    /**
+     * Re-verify the paying authority against a FRESH graph + injected clock at
+     * prepare time. Throws on drift/expiry so the pay tool refuses to hand back a
+     * signing request for a grant that just went paused/revoked/expired. Optional:
+     * absent for legacy/local paths.
+     */
+    assertLive?: () => Promise<void>;
+}
+interface McpAuthContext {
+    grantId: string;
+    buyerAccountId: string;
+    /** Space-separated scopes from the access token. */
+    scope: string;
+    /** Public, descriptive policy context. Never used as payment authority. */
+    access?: McpAccessContext;
+    /**
+     * When present, `pay` prepares unsigned spend_account::settle_policy_payment bytes for the
+     * client-held delegate key to sign locally — no server-side decrypt or
+     * signing. Stdio local V1 profile path remains when absent.
+     */
+    spendAccountPay?: McpSpendAccountPayAuth;
+    /**
+     * Server-scoped receipts reader, built by the /mcp route from the verified
+     * bearer's connection. The `receipts` tool calls this instead of hitting the
+     * global settlement feed with a forwarded credential — the bearer never
+     * enters the tool surface, and scoping is enforced server-side. Absent for
+     * local stdio (no connection, no settlement source).
+     */
+    listReceipts?: (challengeId?: string) => Promise<SettlementDTO[]>;
+}
+
+type McpTarget = 'dev' | 'local';
+/**
+ * Public suipay-dev origins (Railway). `local` is the laptop stack from
+ * `pnpm demo:testnet`. Explicit `SUIPAY_GATEWAY_URL` / `SUIPAY_CONSOLE_URL`
+ * still win over the preset.
+ */
+declare const MCP_TARGET_PRESETS: Record<McpTarget, {
+    consoleUrl: string;
+    gatewayUrl: string;
+}>;
+interface McpConfig {
+    /** Preset used when console/gateway env is unset. Set by `loadMcpConfig`. */
+    target?: McpTarget;
+    consoleUrl: string;
+    gatewayUrl: string;
+    rpcUrl: string;
+    network: 'testnet' | 'mainnet' | 'devnet' | 'localnet';
+    packageId: string;
+    recipient: string;
+    coinType: string;
+    sponsorUrl: string;
+    minFunded: bigint;
+    minMaxPerPayment: bigint;
+    label: string;
+}
+/**
+ * CLI flags: `--local` / `-local`, `--dev` / `-dev`. Unknown args are ignored
+ * so an MCP host can pass extra argv without breaking stdio.
+ */
+declare function parseMcpTargetFlag(argv: readonly string[]): McpTarget | undefined;
+declare function resolveMcpTarget(env?: NodeJS.ProcessEnv, argv?: readonly string[]): McpTarget;
+/** Same public origin, or the same laptop loopback port (`localhost` ≡ `127.0.0.1`). */
+declare function sameMcpGateway(a: string, b: string): boolean;
+declare function loadMcpConfig(env?: NodeJS.ProcessEnv, argv?: readonly string[]): McpConfig;
+
+/**
+ * Agent-held settlement wiring for the `pay` tool.
+ *
+ * The gateway prepares (it holds no key). Settlement needs the delegate key, so
+ * it can only happen in the process that holds one. This module answers a single
+ * question for a given grant: *is this process that grant's agent, and is it
+ * configured to settle?* Any "no" returns null and `pay` falls back to handing
+ * back unsigned bytes — the pre-existing behavior.
+ *
+ * Two conditions gate it, and the first is the security one:
+ *
+ * 1. **The persisted key must be the key the grant names.** A hosted gateway
+ *    running this same tool code either holds no credentials file (null) or
+ *    holds one for some unrelated key (address mismatch → null). It can only
+ *    settle by already possessing the grant's delegate seed — which is exactly
+ *    the custody ADR-0015 removed, not a state a flag protects against.
+ * 2. **The settlement dependencies must all be present.** A half-configured
+ *    settler is worse than none: it would sign and then fail to confirm. Missing
+ *    anything → null, prepare-only.
+ *
+ * The key is read, never minted. See `loadLocalSigner`.
+ */
+
+/** Everything `pay` needs to settle rather than prepare. */
+interface AgentHeldSettlement {
+    signer: DelegatedKeySigner;
+    getObjectJson: GetObjectJson;
+    payerDeps: DelegatedPayerDeps;
+}
+/**
+ * Resolve agent-held settlement for one grant, or null to stay prepare-only.
+ * Injectable so `createServer` can be driven without touching disk,
+ * chain, or environment.
+ */
+type AgentHeldResolver = (cfg: McpConfig, spendAccountPay: McpSpendAccountPayAuth) => AgentHeldSettlement | null;
+/** Test seam: drop the process ledger so suites do not share reservations. */
+declare function resetAgentHeldProcessLedger(): void;
+declare function resolveAgentHeldSettlement(cfg: McpConfig, spendAccountPay: McpSpendAccountPayAuth, env?: NodeJS.ProcessEnv): AgentHeldSettlement | null;
+
+/**
+ * Transparent MCP wire proxy.
+ *
+ * This module is the *only* place in the system that parses MCP methods and
+ * JSON-RPC ids. The gateway authenticates and hands over a run manager and a
+ * sink; it never sniffs an MCP body a second time. Payment code emits domain
+ * facts, never wire facts. That single-owner rule is what stops two subsystems
+ * from disagreeing about which tool call a payment belongs to.
+ *
+ * Transparency is the top invariant, and it is structural rather than
+ * best-effort:
+ *
+ *  - With no runtime, this file is a pass-through and does not touch the
+ *    request or the response at all.
+ *  - With a runtime, observation reads `Request.clone()` and `Response.clone()`
+ *    only. The exact `Response` instance the handler produced is what the caller
+ *    receives, so byte equality is by construction, not by careful copying.
+ *  - Response observation is started and deliberately not awaited. A trace
+ *    store that hangs cannot hold an MCP response open.
+ *  - The request side cannot be fire-and-forget — the proxy must know the run
+ *    and the JSON-RPC ids before the handler runs — so it is bounded instead:
+ *    one deadline over envelope parsing plus run selection, and the same byte
+ *    cap the response observer uses. A hung store or an oversized body costs
+ *    the trace, never the request.
+ *  - Every observation path is wrapped: a hostile body, a failing run manager or
+ *    a throwing sink degrades to "no trace", never to a changed response.
+ *
+ * Volume control lives here too. One `tool_called` per JSON-RPC id and one
+ * terminal `tool_result` / `tool_error` per id — never one row per SSE frame.
+ */
+
+/** Everything the proxy needs to attribute wire facts to one owned run. */
+interface McpTraceRuntime {
+    buyerAccountId: string;
+    connectionId: string;
+    runs: TraceRunResolver;
+    sink: TraceSink;
+    /**
+     * HMAC secret for signed cross-request context. Supplied by the composition
+     * root so a published SDK never reads a gateway-only environment variable.
+     * Absent means internal hops carry no correlation and the gateway simply
+     * emits no linked events.
+     */
+    secret?: string | null;
+    /** Injected clock; tests pin it, production leaves it out. */
+    now?: () => number;
+}
+/** The proxy-resolved context handed down to payment code (Task 5 seams). */
+interface McpTraceContext {
+    traceId: string;
+    requestId: string | null;
+}
+interface McpTraceHooks {
+    runtime: McpTraceRuntime;
+    context: McpTraceContext;
+    sink: TraceSink;
+}
+/** One JSON-RPC message read off the request side. */
+interface McpEnvelopeEntry {
+    method: string | null;
+    jsonRpcId: string | number | null;
+    /** Canonical, header-safe request id. `null` for notifications. */
+    requestId: string | null;
+    toolName: string | null;
+    toolArguments: unknown;
+    clientName: string | null;
+    clientVersion: string | null;
+    protocolVersion: string | null;
+}
+interface McpEnvelope {
+    batch: boolean;
+    entries: McpEnvelopeEntry[];
+    /** First entry's method — what run selection keys on. */
+    method: string | null;
+    requestId: string | null;
+    clientName: string | null;
+}
+/**
+ * Canonical MCP request id.
+ *
+ * JSON-RPC allows both `7` and `"7"` as distinct ids, and they must stay
+ * distinct: correlating a payment to the wrong tool call is worse than not
+ * correlating it. Numbers keep their JSON form under `n:`; strings are
+ * base64url-encoded under `s:` so an id containing newlines, colons or quotes
+ * survives being carried in an HTTP header without escaping games.
+ */
+declare function canonicalMcpRequestId(id: unknown): string | null;
+/**
+ * Read the JSON-RPC envelope from a request **clone**.
+ *
+ * The caller owns cloning; this consumes the body it is given. An unparsable,
+ * bodiless or over-cap request yields an empty envelope rather than an error — a
+ * malformed request is the transport's problem to answer, not tracing's problem
+ * to block.
+ */
+declare function inspectMcpEnvelope(request: Request, maxBytes?: number): Promise<McpEnvelope>;
+interface TraceMcpHttpRequestInput {
+    request: Request;
+    /**
+     * The real MCP handler. Receives the untouched original request, plus the
+     * resolved trace context when tracing is live.
+     */
+    handle: (request: Request, hooks?: McpTraceHooks) => Promise<Response>;
+    runtime?: McpTraceRuntime | null;
+    /** Cap on bytes read for observation, request and response. Never unbounded. */
+    maxObservedBytes?: number;
+    /**
+     * Deadline for envelope parsing plus run selection, the only trace work that
+     * happens before the handler. Past it the exchange proceeds untraced.
+     */
+    runSetupTimeoutMs?: number;
+}
+/**
+ * Wrap one MCP HTTP exchange in observation.
+ *
+ * The response returned here is the exact object `handle` produced. Nothing on
+ * the observation path can change it, delay it, or prevent it.
+ */
+declare function traceMcpHttpRequest(input: TraceMcpHttpRequestInput): Promise<Response>;
+
+/**
+ * Transport-neutral SuiPay MCP server + tool registry.
+ * Used by stdio (index.ts) and Streamable HTTP (http.ts).
+ * Remote HTTP passes McpAuthContext so tools enforce OAuth scope + shared-pool pay.
+ */
+
+declare const PACKAGE_NAME = "@cmdoss/suipay-mcp";
+declare const TOOLS: readonly [{
+    readonly name: "access_context";
+    readonly description: "Inspect profiles, policies, service targets, spend caps, usage, and lifecycle state enforced for this authenticated SuiPay session. Call before choosing a paid service.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}, {
+    readonly name: "pay";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly url: {
+                readonly type: "string";
+                readonly description: "Full gateway resource URL.";
+            };
+            readonly method: {
+                readonly type: "string";
+                readonly enum: readonly ["GET", "POST"];
+                readonly description: "HTTP method of the paid request. Defaults to GET.";
+            };
+            readonly json: {
+                readonly type: "object";
+                readonly description: "JSON request body for a POST. Sent as application/json and bound to the payment.";
+            };
+            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.";
+            };
+            readonly maxAmount: {
+                readonly type: "string";
+                readonly description: "Atomic ceiling you will spend on this call. The payment is refused, unsigned, if the offer costs more.";
+            };
+        };
+        readonly required: readonly ["url"];
+    };
+}, {
+    readonly name: "discover";
+    readonly description: "Search SuiPay gateway resources. After login, each row includes name, path, url, catalog price, and whether the current session can cover one call at that price (descriptive only — pay still enforces the grant).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Optional service search terms.";
+            };
+        };
+    };
+}, {
+    readonly name: "receipts";
+    readonly description: "List SuiPay settlement receipts, optionally filtered by challenge id.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly challengeId: {
+                readonly type: "string";
+                readonly description: "Optional payment challenge id.";
+            };
+        };
+    };
+}, {
+    readonly name: "suipay_login";
+    readonly description: "Mint or reuse the local delegate key (version-2, mode 0600) and return a clickable console URL immediately so the owner can bind a spend-account grant. Does not wait for the wallet. Default target is Railway suipay-dev; pass target=\"local\" (or start the binary with --local) for the laptop stack. Stdio only; hosted /mcp never holds a spendable key.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly label: {
+                readonly type: "string";
+                readonly description: "Label shown in SuiPay console.";
+            };
+            readonly target: {
+                readonly type: "string";
+                readonly enum: readonly ["dev", "local"];
+                readonly description: "Where to bind the grant. Default is Railway suipay-dev. Pass \"local\" for localhost:3000 / 127.0.0.1:4340.";
+            };
+            readonly gatewayResourceUrl: {
+                readonly type: "string";
+                readonly description: "Gateway resource URL whose 402 defines recipient, asset, and package.";
+            };
+        };
+    };
+}, {
+    readonly name: "suipay_logout";
+    readonly description: "Remove the local delegate-key credentials file. Missing file is success. Force clears a corrupt file without printing the seed.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly force: {
+                readonly type: "boolean";
+                readonly description: "Remove local credentials even if the file is unreadable.";
+            };
+        };
+    };
+}];
+/**
+ * Create a Server with the public SuiPay tool surface registered.
+ *
+ * `trace` is the proxy-resolved run for this HTTP exchange. It is threaded into
+ * tool dependencies so payment code can emit *domain* events, and nothing else:
+ * this wrapper deliberately emits no tool lifecycle of its own, because the
+ * proxy observes the actual JSON-RPC wire and a second source would double-count
+ * every call and disagree on ids.
+ */
+interface McpServerOptions {
+    /**
+     * How `pay` finds an agent-held delegate key for the authenticated grant.
+     * Defaults to the persisted local key (`resolveAgentHeldSettlement`), which
+     * returns null on any process that does not hold the key the grant names — so
+     * the default is prepare-only everywhere except the agent's own machine.
+     * Injectable for tests; there is no way to make it hand over a key the grant
+     * does not already authorize.
+     */
+    resolveAgentHeld?: AgentHeldResolver;
+}
+declare function createServer(cfg: McpConfig, auth?: McpAuthContext, trace?: McpTraceHooks, options?: McpServerOptions): Server;
+
+/**
+ * Streamable HTTP transport for SuiPay MCP.
+ * Stateless per-request (sessionIdGenerator undefined) — same public tools as stdio.
+ * Auth context is required for remote gateway /mcp (bearer resolved upstream).
+ *
+ * The optional trace runtime turns on live observation. It is a pure wrapper:
+ * `traceMcpHttpRequest` reads clones and returns the transport's own Response,
+ * so passing a runtime cannot change what an MCP client sees.
+ */
+
+/**
+ * Handle one MCP Streamable HTTP request (initialize, tools/list, tools/call, …).
+ * Creates a fresh transport+server pair per request (stateless mode).
+ */
+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 };

package/dist/http.d.ts

@@ -1,3 +1,8 @@
-export { q as handleSuipayMcpHttpRequest } from './http-BnIjiwcR.js';
+export { m as handleSuipayMcpHttpRequest } from './http-B4YTVw0k.js';
+import '@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 '@mysten/sui/keypairs/ed25519';
+import '@cmdoss/suipay-sdk/agent-sdk/reads';
+import '@cmdoss/suipay-sdk/delegated-signer/payer';
+import '@cmdoss/suipay-core/trace/types';

package/dist/http.js

@@ -1,7 +1,6 @@
 import {
   handleSuipayMcpHttpRequest
-} from "./chunk-XZQOOY66.js";
-import "./chunk-A3JIIDYT.js";
+} from "./chunk-NVTYOOMY.js";
 export {
   handleSuipayMcpHttpRequest
 };

package/dist/index.d.ts

@@ -1,25 +1,18 @@
-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 { 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 { GetObjectJson, createReader } from '@cmdoss/suipay-sdk/agent-sdk/reads';
+import { DelegatedKeySigner, DelegatedPayerSession, DelegatedPayerConfig, DelegatedPayerDeps, SpendIntent, DelegatedPayResult } from '@cmdoss/suipay-sdk/delegated-signer/payer';
+import { createPayer } from '@cmdoss/suipay-sdk/agent-sdk/delegate-agent';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import '@cmdoss/suipay-sdk/mcp/access-context';
+import '@cmdoss/suipay-sdk/buyer/settlement-dto';
 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 {
-    readonly address: string;
-    signTransaction(txBytes: string): Promise<string>;
-}
 
 interface SuiPayCredentials {
     /** 64-hex Ed25519 seed. NEVER logged. */
@@ -53,14 +46,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>;
@@ -85,8 +73,8 @@ declare function loadLocalSigner(): {
  *
  * 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.
+ * 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 = {
@@ -215,11 +203,11 @@ interface SpendAccountSigningRequest {
         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.
+     * 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.
      */
-    handoffUrl: string;
+    expiresAt: string;
     /** Restated hard rule for the agent host. */
     note: string;
 }
@@ -259,11 +247,17 @@ declare function verifySpendAccountPayReconstructs(bytes: string, expected: {
     amount: string;
 }): void;
 /**
- * Prepare a shared_pool payment WITHOUT signing. Reads the 402 offer, binds it,
+ * 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;
@@ -292,6 +286,12 @@ declare function prepareSpendAccountPayment(args: {
 
 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
@@ -315,10 +315,84 @@ declare function settlePreparedMcpPayment(args: {
     intent?: SpendIntent;
 }): Promise<DelegatedPayResult>;
 
+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>;
+
+/**
+ * MCP tool payloads. Settlement honesty matches the playground stamp:
+ * money that moved is never reported as a tool error (that invites a second pay).
+ */
+
+type ToolResult = CallToolResult;
+
+interface ToolDeps {
+    fetchImpl?: typeof fetch;
+    profileLoader?: () => PaymentProfile | null;
+    /** Remote HTTP auth (grant + scope + optional shared-pool pay session). */
+    auth?: McpAuthContext;
+    /**
+     * 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'];
+    /**
+     * 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;
+    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 { type PreparedPayment, type SpendAccountPrepareResult, type SpendAccountPrepareSession, type SpendAccountSigningRequest, buildSpendAccountPayKind, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, prepareSpendAccountPayment, settlePreparedMcpPayment, verifySpendAccountPayReconstructs };
+export { McpAuthContext, McpConfig, McpTraceHooks, type PreparedPayment, type SpendAccountPrepareResult, type SpendAccountPrepareSession, type SpendAccountSigningRequest, buildSpendAccountPayKind, ensureLocalSigningKey, loadBootProfile, loadLocalSigner, main, pay, prepareSpendAccountPayment, receipts, settlePreparedMcpPayment, verifySpendAccountPayReconstructs };

package/dist/index.js

@@ -1,8 +1,9 @@
 import {
   loadBootProfile,
   main
-} from "./chunk-TPW6S2K4.js";
+} from "./chunk-K6WM4Z7H.js";
 import {
+  MCP_TARGET_PRESETS,
   PACKAGE_NAME,
   TOOLS,
   buildSpendAccountPayKind,
@@ -13,16 +14,21 @@ import {
   inspectMcpEnvelope,
   loadLocalSigner,
   loadMcpConfig,
+  parseMcpTargetFlag,
+  pay,
   prepareSpendAccountPayment,
+  receipts,
   resetAgentHeldProcessLedger,
   resolveAgentHeldSettlement,
   resolveGrantTarget,
+  resolveMcpTarget,
+  sameMcpGateway,
   settlePreparedMcpPayment,
   traceMcpHttpRequest,
   verifySpendAccountPayReconstructs
-} from "./chunk-XZQOOY66.js";
-import "./chunk-A3JIIDYT.js";
+} from "./chunk-NVTYOOMY.js";
 export {
+  MCP_TARGET_PRESETS,
   PACKAGE_NAME,
   TOOLS,
   buildSpendAccountPayKind,
@@ -35,10 +41,15 @@ export {
   loadLocalSigner,
   loadMcpConfig,
   main,
+  parseMcpTargetFlag,
+  pay,
   prepareSpendAccountPayment,
+  receipts,
   resetAgentHeldProcessLedger,
   resolveAgentHeldSettlement,
   resolveGrantTarget,
+  resolveMcpTarget,
+  sameMcpGateway,
   settlePreparedMcpPayment,
   traceMcpHttpRequest,
   verifySpendAccountPayReconstructs