@nevermined-io/payments 1.4.1 → 1.6.0

package/dist/x402/langchain/agent.d.ts

@@ -0,0 +1,96 @@
+/**
+ * LangGraph ReAct agent helper that surfaces `PaymentRequiredError` intact.
+ *
+ * By default `createReactAgent` from `@langchain/langgraph/prebuilt` constructs a
+ * `ToolNode` with `handleToolErrors: true` — tool exceptions are caught and
+ * rendered into a `ToolMessage` for the LLM. That is convenient for
+ * prompt-engineered recovery, but it stringifies the exception and loses the
+ * `X402PaymentRequired` payload attached to {@link PaymentRequiredError}.
+ * Without that payload the caller cannot run the x402 discovery flow (probe →
+ * read scheme/network/plan id → acquire token → retry).
+ *
+ * {@link createPaidReactAgent} builds the same agent but with a `ToolNode`
+ * configured to **re-raise** exceptions (`handleToolErrors: false`), so
+ * `PaymentRequiredError` propagates all the way back to `agent.invoke()`'s
+ * caller with `.paymentRequired` populated.
+ *
+ * `@langchain/langgraph` is imported **lazily** inside the function so the
+ * existing `peerDependencies` story is unchanged — users who only use the
+ * `requiresPayment` wrapper do not need LangGraph installed. Install it
+ * yourself (`pnpm add @langchain/langgraph`) to use this helper.
+ *
+ * Unlike Python's synchronous `create_paid_react_agent`, this helper is
+ * **`async`** — that is a deliberate consequence of the lazy `import()` that
+ * keeps `@langchain/langgraph` an optional peer, not a parity break. `await` it.
+ *
+ * @example
+ * ```typescript
+ * import { tool } from '@langchain/core/tools'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { z } from 'zod'
+ * import {
+ *   PaymentRequiredError,
+ *   createPaidReactAgent,
+ *   requiresPayment,
+ *   lastSettlement,
+ * } from '@nevermined-io/payments/langchain'
+ *
+ * const getMarketInsight = tool(
+ *   requiresPayment(
+ *     (args) => `Market insight for ${args.topic} ...`,
+ *     { payments, planId: PLAN_ID, credits: 1 },
+ *   ),
+ *   { name: 'get_market_insight', description: 'Paid market insight', schema: z.object({ topic: z.string() }) },
+ * )
+ *
+ * const agent = await createPaidReactAgent(
+ *   new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }),
+ *   [getMarketInsight],
+ *   { prompt: '...' },
+ * )
+ *
+ * // Discovery: invoke without a token to learn what to pay for.
+ * try {
+ *   await agent.invoke({ messages: [...] }, { configurable: {} })
+ * } catch (err) {
+ *   if (err instanceof PaymentRequiredError) {
+ *     const accept = err.paymentRequired?.accepts[0]
+ *     // ... acquire token using accept.planId / accept.scheme / accept.network ...
+ *   }
+ * }
+ *
+ * const result = await agent.invoke(
+ *   { messages: [...] },
+ *   { configurable: { payment_token: token } },
+ * )
+ * const receipt = lastSettlement()
+ * ```
+ */
+/**
+ * Options forwarded to the underlying `createReactAgent` call.
+ *
+ * Everything except `tools` (which this helper builds from the `tools`
+ * argument as a `ToolNode` with `handleToolErrors: false`) and `llm` (which
+ * this helper maps from the `model` argument) is passed through verbatim —
+ * `prompt`, `stateSchema`, `checkpointer`, `responseFormat`, etc.
+ */
+export type CreatePaidReactAgentOptions = Record<string, unknown>;
+/**
+ * Build a LangGraph ReAct agent that lets `PaymentRequiredError` propagate.
+ *
+ * Wraps `createReactAgent` from `@langchain/langgraph/prebuilt` with a
+ * `ToolNode(tools, { handleToolErrors: false })`. The signature mirrors the
+ * Python `create_paid_react_agent(model, tools, **kwargs)` helper: `model` is
+ * mapped to the JS `llm` parameter and any extra `options` are forwarded.
+ *
+ * @param model - The chat model (mapped to `createReactAgent`'s `llm` argument).
+ * @param tools - The LangChain tools, typically functions wrapped with
+ *   `requiresPayment` and registered via `tool(...)`.
+ * @param options - Forwarded verbatim to `createReactAgent` (`prompt`,
+ *   `stateSchema`, `checkpointer`, …).
+ * @returns The compiled ReAct agent graph, ready to be invoked with
+ *   `agent.invoke(...)`.
+ * @throws If `@langchain/langgraph` is not installed.
+ */
+export declare function createPaidReactAgent(model: unknown, tools: readonly unknown[], options?: CreatePaidReactAgentOptions): Promise<unknown>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/x402/langchain/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/x402/langchain/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,OAAO,CAAC,CAyClB"}

package/dist/x402/langchain/agent.js

@@ -0,0 +1,121 @@
+/**
+ * LangGraph ReAct agent helper that surfaces `PaymentRequiredError` intact.
+ *
+ * By default `createReactAgent` from `@langchain/langgraph/prebuilt` constructs a
+ * `ToolNode` with `handleToolErrors: true` — tool exceptions are caught and
+ * rendered into a `ToolMessage` for the LLM. That is convenient for
+ * prompt-engineered recovery, but it stringifies the exception and loses the
+ * `X402PaymentRequired` payload attached to {@link PaymentRequiredError}.
+ * Without that payload the caller cannot run the x402 discovery flow (probe →
+ * read scheme/network/plan id → acquire token → retry).
+ *
+ * {@link createPaidReactAgent} builds the same agent but with a `ToolNode`
+ * configured to **re-raise** exceptions (`handleToolErrors: false`), so
+ * `PaymentRequiredError` propagates all the way back to `agent.invoke()`'s
+ * caller with `.paymentRequired` populated.
+ *
+ * `@langchain/langgraph` is imported **lazily** inside the function so the
+ * existing `peerDependencies` story is unchanged — users who only use the
+ * `requiresPayment` wrapper do not need LangGraph installed. Install it
+ * yourself (`pnpm add @langchain/langgraph`) to use this helper.
+ *
+ * Unlike Python's synchronous `create_paid_react_agent`, this helper is
+ * **`async`** — that is a deliberate consequence of the lazy `import()` that
+ * keeps `@langchain/langgraph` an optional peer, not a parity break. `await` it.
+ *
+ * @example
+ * ```typescript
+ * import { tool } from '@langchain/core/tools'
+ * import { ChatOpenAI } from '@langchain/openai'
+ * import { z } from 'zod'
+ * import {
+ *   PaymentRequiredError,
+ *   createPaidReactAgent,
+ *   requiresPayment,
+ *   lastSettlement,
+ * } from '@nevermined-io/payments/langchain'
+ *
+ * const getMarketInsight = tool(
+ *   requiresPayment(
+ *     (args) => `Market insight for ${args.topic} ...`,
+ *     { payments, planId: PLAN_ID, credits: 1 },
+ *   ),
+ *   { name: 'get_market_insight', description: 'Paid market insight', schema: z.object({ topic: z.string() }) },
+ * )
+ *
+ * const agent = await createPaidReactAgent(
+ *   new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }),
+ *   [getMarketInsight],
+ *   { prompt: '...' },
+ * )
+ *
+ * // Discovery: invoke without a token to learn what to pay for.
+ * try {
+ *   await agent.invoke({ messages: [...] }, { configurable: {} })
+ * } catch (err) {
+ *   if (err instanceof PaymentRequiredError) {
+ *     const accept = err.paymentRequired?.accepts[0]
+ *     // ... acquire token using accept.planId / accept.scheme / accept.network ...
+ *   }
+ * }
+ *
+ * const result = await agent.invoke(
+ *   { messages: [...] },
+ *   { configurable: { payment_token: token } },
+ * )
+ * const receipt = lastSettlement()
+ * ```
+ */
+/**
+ * Build a LangGraph ReAct agent that lets `PaymentRequiredError` propagate.
+ *
+ * Wraps `createReactAgent` from `@langchain/langgraph/prebuilt` with a
+ * `ToolNode(tools, { handleToolErrors: false })`. The signature mirrors the
+ * Python `create_paid_react_agent(model, tools, **kwargs)` helper: `model` is
+ * mapped to the JS `llm` parameter and any extra `options` are forwarded.
+ *
+ * @param model - The chat model (mapped to `createReactAgent`'s `llm` argument).
+ * @param tools - The LangChain tools, typically functions wrapped with
+ *   `requiresPayment` and registered via `tool(...)`.
+ * @param options - Forwarded verbatim to `createReactAgent` (`prompt`,
+ *   `stateSchema`, `checkpointer`, …).
+ * @returns The compiled ReAct agent graph, ready to be invoked with
+ *   `agent.invoke(...)`.
+ * @throws If `@langchain/langgraph` is not installed.
+ */
+export async function createPaidReactAgent(model, tools, options = {}) {
+    // `llm` and `tools` are owned by this helper — `tools` carries the
+    // handleToolErrors:false ToolNode that makes PaymentRequiredError propagate,
+    // and overriding either would silently defeat the whole point of the helper
+    // (a caller-supplied `tools` re-enables the default handleToolErrors:true and
+    // the X402 payload is stringified away). Reject them up front, mirroring how
+    // Python's positional `create_paid_react_agent(model, tools, **kwargs)` raises
+    // a TypeError if `llm`/`tools` are passed again via kwargs.
+    if ('llm' in options || 'tools' in options) {
+        throw new Error('createPaidReactAgent: `llm` and `tools` are set from the `model` and ' +
+            '`tools` arguments and must not be passed in `options` (they would ' +
+            'override the handleToolErrors:false ToolNode and break x402 discovery).');
+    }
+    let prebuilt;
+    try {
+        prebuilt = await import('@langchain/langgraph/prebuilt');
+    }
+    catch (err) {
+        throw new Error('createPaidReactAgent requires @langchain/langgraph. ' +
+            `Install it with \`pnpm add @langchain/langgraph\`. (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const { ToolNode, createReactAgent } = prebuilt;
+    // handleToolErrors: false re-raises tool exceptions instead of stringifying
+    // them into a ToolMessage, so PaymentRequiredError reaches agent.invoke()'s
+    // caller with its X402PaymentRequired payload intact.
+    const toolNode = new ToolNode(tools, { handleToolErrors: false });
+    // `createReactAgent` is the current prebuilt entry point in
+    // @langchain/langgraph@1.2.0. It is marked @deprecated in favour of
+    // `createAgent`, but that replacement lives in the separate `langchain`
+    // package (out of scope for this SDK's optional langgraph peer), so the
+    // prebuilt `createReactAgent` is the deliberate, only in-package choice here.
+    // Spread `...options` FIRST so the protected `llm`/`tools` keys (set last)
+    // always win, even though the guard above already forbids them in `options`.
+    return createReactAgent({ ...options, llm: model, tools: toolNode });
+}
+//# sourceMappingURL=agent.js.map

package/dist/x402/langchain/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/x402/langchain/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAYH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAc,EACd,KAAyB,EACzB,UAAuC,EAAE;IAEzC,mEAAmE;IACnE,6EAA6E;IAC7E,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,4DAA4D;IAC5D,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,uEAAuE;YACrE,oEAAoE;YACpE,yEAAyE,CAC5E,CAAA;IACH,CAAC;IAED,IAAI,QAAwD,CAAA;IAC5D,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,MAAM,CAAC,+BAA+B,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,sDAAsD;YACpD,uDACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,GAAG,CACN,CAAA;IACH,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,QAAQ,CAAA;IAE/C,4EAA4E;IAC5E,4EAA4E;IAC5E,sDAAsD;IACtD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,KAAc,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1E,4DAA4D;IAC5D,oEAAoE;IACpE,wEAAwE;IACxE,wEAAwE;IACxE,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,OAAO,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,KAAc,EAAE,KAAK,EAAE,QAAQ,EAAW,CAAC,CAAA;AACxF,CAAC","sourcesContent":["/**\n * LangGraph ReAct agent helper that surfaces `PaymentRequiredError` intact.\n *\n * By default `createReactAgent` from `@langchain/langgraph/prebuilt` constructs a\n * `ToolNode` with `handleToolErrors: true` — tool exceptions are caught and\n * rendered into a `ToolMessage` for the LLM. That is convenient for\n * prompt-engineered recovery, but it stringifies the exception and loses the\n * `X402PaymentRequired` payload attached to {@link PaymentRequiredError}.\n * Without that payload the caller cannot run the x402 discovery flow (probe →\n * read scheme/network/plan id → acquire token → retry).\n *\n * {@link createPaidReactAgent} builds the same agent but with a `ToolNode`\n * configured to **re-raise** exceptions (`handleToolErrors: false`), so\n * `PaymentRequiredError` propagates all the way back to `agent.invoke()`'s\n * caller with `.paymentRequired` populated.\n *\n * `@langchain/langgraph` is imported **lazily** inside the function so the\n * existing `peerDependencies` story is unchanged — users who only use the\n * `requiresPayment` wrapper do not need LangGraph installed. Install it\n * yourself (`pnpm add @langchain/langgraph`) to use this helper.\n *\n * Unlike Python's synchronous `create_paid_react_agent`, this helper is\n * **`async`** — that is a deliberate consequence of the lazy `import()` that\n * keeps `@langchain/langgraph` an optional peer, not a parity break. `await` it.\n *\n * @example\n * ```typescript\n * import { tool } from '@langchain/core/tools'\n * import { ChatOpenAI } from '@langchain/openai'\n * import { z } from 'zod'\n * import {\n *   PaymentRequiredError,\n *   createPaidReactAgent,\n *   requiresPayment,\n *   lastSettlement,\n * } from '@nevermined-io/payments/langchain'\n *\n * const getMarketInsight = tool(\n *   requiresPayment(\n *     (args) => `Market insight for ${args.topic} ...`,\n *     { payments, planId: PLAN_ID, credits: 1 },\n *   ),\n *   { name: 'get_market_insight', description: 'Paid market insight', schema: z.object({ topic: z.string() }) },\n * )\n *\n * const agent = await createPaidReactAgent(\n *   new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 }),\n *   [getMarketInsight],\n *   { prompt: '...' },\n * )\n *\n * // Discovery: invoke without a token to learn what to pay for.\n * try {\n *   await agent.invoke({ messages: [...] }, { configurable: {} })\n * } catch (err) {\n *   if (err instanceof PaymentRequiredError) {\n *     const accept = err.paymentRequired?.accepts[0]\n *     // ... acquire token using accept.planId / accept.scheme / accept.network ...\n *   }\n * }\n *\n * const result = await agent.invoke(\n *   { messages: [...] },\n *   { configurable: { payment_token: token } },\n * )\n * const receipt = lastSettlement()\n * ```\n */\n\n/**\n * Options forwarded to the underlying `createReactAgent` call.\n *\n * Everything except `tools` (which this helper builds from the `tools`\n * argument as a `ToolNode` with `handleToolErrors: false`) and `llm` (which\n * this helper maps from the `model` argument) is passed through verbatim —\n * `prompt`, `stateSchema`, `checkpointer`, `responseFormat`, etc.\n */\nexport type CreatePaidReactAgentOptions = Record<string, unknown>\n\n/**\n * Build a LangGraph ReAct agent that lets `PaymentRequiredError` propagate.\n *\n * Wraps `createReactAgent` from `@langchain/langgraph/prebuilt` with a\n * `ToolNode(tools, { handleToolErrors: false })`. The signature mirrors the\n * Python `create_paid_react_agent(model, tools, **kwargs)` helper: `model` is\n * mapped to the JS `llm` parameter and any extra `options` are forwarded.\n *\n * @param model - The chat model (mapped to `createReactAgent`'s `llm` argument).\n * @param tools - The LangChain tools, typically functions wrapped with\n *   `requiresPayment` and registered via `tool(...)`.\n * @param options - Forwarded verbatim to `createReactAgent` (`prompt`,\n *   `stateSchema`, `checkpointer`, …).\n * @returns The compiled ReAct agent graph, ready to be invoked with\n *   `agent.invoke(...)`.\n * @throws If `@langchain/langgraph` is not installed.\n */\nexport async function createPaidReactAgent(\n  model: unknown,\n  tools: readonly unknown[],\n  options: CreatePaidReactAgentOptions = {},\n): Promise<unknown> {\n  // `llm` and `tools` are owned by this helper — `tools` carries the\n  // handleToolErrors:false ToolNode that makes PaymentRequiredError propagate,\n  // and overriding either would silently defeat the whole point of the helper\n  // (a caller-supplied `tools` re-enables the default handleToolErrors:true and\n  // the X402 payload is stringified away). Reject them up front, mirroring how\n  // Python's positional `create_paid_react_agent(model, tools, **kwargs)` raises\n  // a TypeError if `llm`/`tools` are passed again via kwargs.\n  if ('llm' in options || 'tools' in options) {\n    throw new Error(\n      'createPaidReactAgent: `llm` and `tools` are set from the `model` and ' +\n        '`tools` arguments and must not be passed in `options` (they would ' +\n        'override the handleToolErrors:false ToolNode and break x402 discovery).',\n    )\n  }\n\n  let prebuilt: typeof import('@langchain/langgraph/prebuilt')\n  try {\n    prebuilt = await import('@langchain/langgraph/prebuilt')\n  } catch (err) {\n    throw new Error(\n      'createPaidReactAgent requires @langchain/langgraph. ' +\n        `Install it with \\`pnpm add @langchain/langgraph\\`. (${\n          err instanceof Error ? err.message : String(err)\n        })`,\n    )\n  }\n  const { ToolNode, createReactAgent } = prebuilt\n\n  // handleToolErrors: false re-raises tool exceptions instead of stringifying\n  // them into a ToolMessage, so PaymentRequiredError reaches agent.invoke()'s\n  // caller with its X402PaymentRequired payload intact.\n  const toolNode = new ToolNode(tools as never, { handleToolErrors: false })\n  // `createReactAgent` is the current prebuilt entry point in\n  // @langchain/langgraph@1.2.0. It is marked @deprecated in favour of\n  // `createAgent`, but that replacement lives in the separate `langchain`\n  // package (out of scope for this SDK's optional langgraph peer), so the\n  // prebuilt `createReactAgent` is the deliberate, only in-package choice here.\n  // Spread `...options` FIRST so the protected `llm`/`tools` keys (set last)\n  // always win, even though the guard above already forbids them in `options`.\n  return createReactAgent({ ...options, llm: model as never, tools: toolNode } as never)\n}\n"]}

package/dist/x402/langchain/decorator.d.ts

@@ -14,7 +14,7 @@
  *
  * The `credits` option accepts two forms:
  *   - **Static number**: `credits: 1` — always charges 1 credit
- *   - **Function**: `credits: (ctx) => Math.max(1, ctx.result.length / 100)` — dynamic
+ *   - **Function**: `credits: (ctx) => Math.max(1, Math.floor(ctx.result.length / 100))` — dynamic
  *
  * When `credits` is a function, it receives `{ args, result }` after tool execution.
  *
@@ -43,7 +43,7 @@
  * ```
  */
 import type { Payments } from '../../payments.js';
-import { type X402PaymentRequired } from '../facilitator-api.js';
+import { type X402PaymentRequired, type SettlePermissionsResult } from '../facilitator-api.js';
 /**
  * Context passed to a dynamic credits function after tool execution.
  */
@@ -66,7 +66,18 @@ export interface RequiresPaymentOptions {
     payments: Payments;
     /** Single plan ID to accept */
     planId: string;
-    /** Number of credits to charge, or a function for dynamic pricing (default: 1) */
+    /**
+     * Number of credits to charge, or a function for dynamic pricing (default: 1).
+     *
+     * This value is sent as `maxAmount` to the facilitator. The amount actually
+     * redeemed depends on the plan's server-side credit configuration:
+     *
+     * - **Fixed plans** (`plan.credits.minAmount === plan.credits.maxAmount`)
+     *   always burn `plan.credits.maxAmount` — this value is then effectively a
+     *   no-op (see nevermined-io/nvm-monorepo#1568).
+     * - **Range plans** clamp this value into
+     *   `[plan.credits.minAmount, plan.credits.maxAmount]`.
+     */
     credits?: number | CreditsCallable;
     /** Optional agent identifier */
     agentId?: string;
@@ -88,7 +99,17 @@ export declare class PaymentRequiredError extends Error {
  * Payment context stored in `config.configurable.payment_context` after verification.
  */
 export interface PaymentContext {
-    /** The x402 access token */
+    /**
+     * Abbreviated, non-functional reference to the x402 access token — the SAME
+     * redacted form surfaced as `nvm.payment_token` (`<first 16>…<last 4>`, or a
+     * `…(short)` marker for a too-short token). The **full token is deliberately
+     * not persisted here**: this object is written into
+     * `config.configurable.payment_context`, and tracing frameworks (e.g.
+     * LangChain) can capture `config.configurable` into span metadata, so storing
+     * the raw credential would let it ride into any traced run opened during or
+     * after the tool body. Settlement uses the token read from
+     * `config.configurable.payment_token`, never this field.
+     */
     token: string;
     /** The payment required object */
     paymentRequired: X402PaymentRequired;
@@ -101,6 +122,24 @@ export interface PaymentContext {
     /** Agent request context for observability */
     agentRequest?: unknown;
 }
+/**
+ * Return the most recent settlement receipt produced by {@link requiresPayment}.
+ *
+ * Use this after invoking a LangChain/LangGraph runnable whose tool is wrapped
+ * with {@link requiresPayment} to recover the settlement receipt
+ * (`creditsRedeemed`, `remainingBalance`, `transaction`, `network`, `payer`)
+ * without threading it back through the runnable config (which LangGraph copies
+ * per node, so the in-place write is invisible to the outer scope).
+ *
+ * Returns `undefined` if no settlement has happened yet in this process, or if
+ * the most recent invocation raised before reaching the settle phase.
+ *
+ * @remarks
+ * This accessor reads from a module-level slot. In multi-tenant processes (e.g.
+ * a server handling concurrent settlements), the value reflects whichever
+ * invocation settled most recently — there is no per-call isolation.
+ */
+export declare function lastSettlement(): SettlePermissionsResult | undefined;
 /**
  * Wraps a LangChain.js tool implementation with x402 payment verification and settlement.
  *

package/dist/x402/langchain/decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../src/x402/langchain/decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,uBAAuB,CAAA;AAE9B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAA;AAE7D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,QAAQ,EAAE,QAAQ,CAAA;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAA;IAClC,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,yEAAyE;IACzE,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAA;gBAEpC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB;CAKnE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,eAAe,EAAE,mBAAmB,CAAA;IACpC,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAA;IACjB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAC5E,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACjE,OAAO,EAAE,sBAAsB,GAC9B,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAiFrD"}
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../src/x402/langchain/decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAEL,KAAK,mBAAmB,EAExB,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAA;AAY9B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAA;AAE7D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,QAAQ,EAAE,QAAQ,CAAA;IAClB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAA;IAClC,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,yEAAyE;IACzE,eAAe,EAAE,mBAAmB,GAAG,SAAS,CAAA;gBAEpC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB;CAKnE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,eAAe,EAAE,mBAAmB,CAAA;IACpC,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,EAAE,OAAO,CAAA;IACjB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,IAAI,uBAAuB,GAAG,SAAS,CAEpE;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAC5E,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EACjE,OAAO,EAAE,sBAAsB,GAC9B,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAoNrD"}

package/dist/x402/langchain/decorator.js

@@ -14,7 +14,7 @@
  *
  * The `credits` option accepts two forms:
  *   - **Static number**: `credits: 1` — always charges 1 credit
- *   - **Function**: `credits: (ctx) => Math.max(1, ctx.result.length / 100)` — dynamic
+ *   - **Function**: `credits: (ctx) => Math.max(1, Math.floor(ctx.result.length / 100))` — dynamic
  *
  * When `credits` is a function, it receives `{ args, result }` after tool execution.
  *
@@ -43,6 +43,7 @@
  * ```
  */
 import { buildPaymentRequired, } from '../facilitator-api.js';
+import { abbreviateToken, activeRunTree, addMetadata, buildSettleMetadata, buildVerifyMetadata, redactMetadataKeys, settlementSpan, verifySpan, } from '../langsmith/spans.js';
 /**
  * Thrown when payment verification fails or no token is provided.
  *
@@ -56,6 +57,38 @@ export class PaymentRequiredError extends Error {
         this.paymentRequired = paymentRequired;
     }
 }
+// Module-level holder for the most recent settlement receipt. LangGraph copies
+// `RunnableConfig.configurable` per node, so the in-place write to
+// `config.configurable.payment_settlement` is not visible to the buyer's outer
+// scope. A module-level slot is the simplest reliable signal. It is
+// intentionally single-tenant — if the same process runs multiple concurrent
+// settlements, the last writer wins. This race is not limited to multi-tenant
+// servers: a single `createPaidReactAgent` run can also hit it, because a ReAct
+// agent may execute several paid tools in parallel within one LLM turn via
+// `ToolNode`, and this single slot only retains the last writer. For
+// multi-tenant or parallel-tool use cases, surface the receipt via a callback
+// or via observability (see Sprint 1 of the LangChain epic).
+let lastSettlementReceipt;
+/**
+ * Return the most recent settlement receipt produced by {@link requiresPayment}.
+ *
+ * Use this after invoking a LangChain/LangGraph runnable whose tool is wrapped
+ * with {@link requiresPayment} to recover the settlement receipt
+ * (`creditsRedeemed`, `remainingBalance`, `transaction`, `network`, `payer`)
+ * without threading it back through the runnable config (which LangGraph copies
+ * per node, so the in-place write is invisible to the outer scope).
+ *
+ * Returns `undefined` if no settlement has happened yet in this process, or if
+ * the most recent invocation raised before reaching the settle phase.
+ *
+ * @remarks
+ * This accessor reads from a module-level slot. In multi-tenant processes (e.g.
+ * a server handling concurrent settlements), the value reflects whichever
+ * invocation settled most recently — there is no per-call isolation.
+ */
+export function lastSettlement() {
+    return lastSettlementReceipt;
+}
 /**
  * Extract the payment token from a LangChain RunnableConfig.
  *
@@ -82,6 +115,17 @@ function storeInConfigurable(config, key, value) {
         return;
     configurable[key] = value;
 }
+/**
+ * Remove a key from config.configurable if present (no-op otherwise).
+ */
+function removeFromConfigurable(config, key) {
+    if (config == null || typeof config !== 'object')
+        return;
+    const configurable = config.configurable;
+    if (configurable == null || typeof configurable !== 'object')
+        return;
+    delete configurable[key];
+}
 /**
  * Wraps a LangChain.js tool implementation with x402 payment verification and settlement.
  *
@@ -126,17 +170,82 @@ function storeInConfigurable(config, key, value) {
 export function requiresPayment(fn, options) {
     const { payments, planId, credits = 1, agentId, network } = options;
     return async (args, config) => {
+        // Reset the module-level slot at the START of every invocation, before
+        // verify. Any failure that does not reach the settle-success write (a
+        // verify failure / PaymentRequiredError, or a swallowed settle failure)
+        // then leaves lastSettlement() returning `undefined` rather than a stale
+        // receipt from a previous invocation — matching the JSDoc contract on
+        // lastSettlement().
+        lastSettlementReceipt = undefined;
         // Build payment required object
         const paymentRequired = buildPaymentRequired(planId, {
             endpoint: fn.name || 'tool',
             agentId,
             network,
         });
+        // The scheme/network the verify span advertises come from the resolved
+        // X402 scheme so the span metadata matches what the buyer paid against.
+        const accepted = paymentRequired.accepts[0];
+        const planIds = paymentRequired.accepts
+            .map((a) => a.planId)
+            .filter((p) => Boolean(p));
+        const resolvedScheme = accepted?.scheme;
+        const resolvedNetwork = network ?? accepted?.network;
+        // LangChain auto-captures every key in config.configurable into the parent
+        // tool span's metadata, and child spans inherit it at construction time.
+        // Strip the full x402 access token from the parent BEFORE opening the verify
+        // span so neither the parent nor the child carries the raw credential — only
+        // the abbreviated nvm.payment_token remains for correlation.
+        const parentRunTree = await activeRunTree();
+        redactMetadataKeys(parentRunTree, 'payment_token');
+        const verifyStarted = Date.now();
+        // Open the verify span BEFORE the token-presence check so failed probes
+        // (no payment_token in config) still produce a clearly-named span with the
+        // static nvm.* attrs attached to both the span and the parent tool span.
+        const vspan = await verifySpan({
+            planIds,
+            scheme: resolvedScheme,
+            network: resolvedNetwork,
+            agentId,
+        });
+        // Pre-verify metadata is best-effort and static-only.
+        const preVerifyMd = buildVerifyMetadata({
+            planIds,
+            scheme: resolvedScheme,
+            network: resolvedNetwork,
+            agentId,
+        });
+        vspan.addMetadata(preVerifyMd);
+        addMetadata(parentRunTree, preVerifyMd);
         // Extract token from config.configurable.payment_token
         const token = extractPaymentToken(config);
         if (!token) {
-            throw new PaymentRequiredError("Payment required: missing payment_token in config.configurable", paymentRequired);
+            await vspan.end(new Error('missing payment_token in config.configurable'));
+            throw new PaymentRequiredError('Payment required: missing payment_token in config.configurable', paymentRequired);
         }
+        // Drop the raw token from configurable now that we hold it in `token`.
+        // LangChain's `ensureConfig` re-promotes every configurable scalar into a
+        // runnable's `metadata` on EACH invocation, so any traced runnable the tool
+        // body spawns (an LLM call, a sub-chain) sharing this config would otherwise
+        // re-leak the full credential into its own span metadata — and a child run
+        // opened *during* `fn()` would capture it before the settle-side
+        // `redactMetadataKeys` below could run. Removing the key here is the
+        // proactive complement to that reactive redaction. This MUST run after
+        // extraction (deleting earlier would make `extractPaymentToken` return null)
+        // and before `fn()` — guaranteed, since `fn()` is called further down.
+        // Settlement uses the local `token`, never configurable, so removal is
+        // non-functional. On the `tool()`/LangGraph path LangChain hands the wrapper
+        // a per-invocation config copy, so this does not mutate a config the caller
+        // reuses across sibling tools.
+        removeFromConfigurable(config, 'payment_token');
+        // Abbreviate/redact the token ONCE here (mirrors Python's
+        // attach_metadata_safely pre-abbreviation) and pass the result into the
+        // metadata builders. abbreviateToken is idempotent, so the builders leave
+        // it unchanged — this means the short-token warning fires at most once per
+        // call (not once per verify AND once per settle), and the raw token never
+        // reaches the builders' frame locals (defense against exception enrichers
+        // that capture locals).
+        const abbreviatedToken = abbreviateToken(token);
         // Resolve pre-execution credits (static only; callable deferred to post-execution)
         const creditsToVerify = typeof credits === 'number' ? credits : 1;
         // Verify permissions
@@ -149,14 +258,38 @@ export function requiresPayment(fn, options) {
             });
         }
         catch (error) {
+            await vspan.end(error);
             throw new PaymentRequiredError(`Payment verification failed: ${error instanceof Error ? error.message : String(error)}`, paymentRequired);
         }
+        // Augment span metadata with verification results + timing (both span and
+        // parent), then close the verify span. Best-effort: a metadata failure must
+        // not mask the PaymentRequiredError that may follow.
+        const verifyMd = buildVerifyMetadata({
+            planIds,
+            scheme: resolvedScheme,
+            network: resolvedNetwork,
+            agentId,
+            verification,
+            durationMs: Date.now() - verifyStarted,
+            token: abbreviatedToken,
+        });
+        vspan.addMetadata(verifyMd);
+        addMetadata(parentRunTree, verifyMd);
         if (!verification.isValid) {
+            await vspan.end(new Error(verification.invalidReason || 'verification failed'));
             throw new PaymentRequiredError(`Payment verification failed: ${verification.invalidReason || 'Insufficient credits or invalid token'}`, paymentRequired);
         }
-        // Store payment context
+        await vspan.end();
+        // Store payment context. The `token` field carries the ABBREVIATED
+        // reference, never the raw credential: `payment_context` is written into
+        // `config.configurable`, which LangChain can capture into span metadata, so
+        // persisting the full token here would reopen the very leak the parent-tree
+        // `redactMetadataKeys('payment_token')` calls close — and a child run opened
+        // *during* the tool body would capture it before any post-hoc redaction
+        // could run. `abbreviatedToken` is always defined past the `!token` guard
+        // above; `?? ''` is a belt-and-suspenders that can never fall back to raw.
         const paymentContext = {
-            token,
+            token: abbreviatedToken ?? '',
             paymentRequired,
             creditsToSettle: creditsToVerify,
             verified: true,
@@ -170,18 +303,52 @@ export function requiresPayment(fn, options) {
         const finalCredits = typeof credits === 'function'
             ? credits({ args: args, result })
             : credits;
-        // Settle credits
+        // Settle credits, wrapped in an nvm:settlement span (mirrors Python's
+        // settlement_span around settle_permissions).
+        //
+        // Re-fetch the active run tree: `fn()` may have opened nested traced runs, so
+        // `activeRunTree()` can now return a different RunTree than the verify-side
+        // redaction at the top of this function scrubbed. We already removed
+        // `payment_token` from `config.configurable` before `fn()` ran, so newly
+        // opened child runs can no longer re-promote the raw credential — this
+        // re-redaction is now defense-in-depth, covering any RunTree whose metadata
+        // was populated before that removal took effect. Redact BEFORE opening the
+        // settlement span so the credential never rides into the settle child span or
+        // the (possibly new) parent tree.
+        const settleParentRunTree = await activeRunTree();
+        redactMetadataKeys(settleParentRunTree, 'payment_token');
+        const settleStarted = Date.now();
+        const sspan = await settlementSpan({ planIds, agentId });
         try {
             const settlement = await payments.facilitator.settlePermissions({
                 paymentRequired,
                 x402AccessToken: token,
-                maxAmount: BigInt(finalCredits),
+                // A dynamic `credits` callable can return a float (e.g. length/100).
+                // `BigInt(1.5)` throws RangeError, which the surrounding try/catch
+                // swallows — credits are never burned and the caller is never told.
+                // Floor to keep the settle on the money path.
+                maxAmount: BigInt(Math.floor(finalCredits)),
                 agentRequestId: paymentContext.agentRequestId,
             });
             storeInConfigurable(config, 'payment_settlement', settlement);
+            // Also publish to the module-level slot so lastSettlement() can recover
+            // the receipt — LangGraph copies config.configurable per node, hiding the
+            // line above from the buyer's outer scope.
+            lastSettlementReceipt = settlement;
+            const settleMd = buildSettleMetadata({
+                settlement,
+                planIds,
+                agentId,
+                durationMs: Date.now() - settleStarted,
+                token: abbreviatedToken,
+            });
+            sspan.addMetadata(settleMd);
+            addMetadata(settleParentRunTree, settleMd);
+            await sspan.end();
         }
         catch (settleError) {
             console.error('Payment settlement failed:', settleError);
+            await sspan.end(settleError);
             // Still return result even if settlement fails
         }
         return result;