@one-source/mcp 5.3.3 → 5.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 29 tools for blockchain data and live chain queries in a single server.
+Unified MCP server for [OneSource](https://docs.onesource.io) — 30 tools for blockchain data and live chain queries in a single server.
 
 > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
 
 Health check: `GET http://localhost:3000/health`
 
-## Tools (29)
+## Tools (30)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -90,13 +90,14 @@ RPC only.
 | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
 | `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
 
-### Setup & Ops (2 tools)
+### Setup & Ops (3 tools)
 
 No authentication required.
 
 | Tool | Purpose | When to use |
 |------|---------|-------------|
-| `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
+| `1s_setup_check` | Server health, version, auth status, batch-settlement status, and setup instructions | First thing to call — checks if everything is configured |
+| `1s_batch_config` | View or change x402 batch-settlement preferences (autonomy, threshold, deposit multiplier, default mode) and persist them across restarts — no config editing required | Configure batch behaviour from the session |
 | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
 
 ## Networks
@@ -107,7 +108,6 @@ All blockchain API tools accept an optional `network` parameter:
 |---------|-------------|
 | `ethereum` | Ethereum mainnet (default) |
 | `sepolia` | Ethereum Sepolia testnet |
-| `avax` | Avalanche C-Chain |
 
 ## Authentication
 
@@ -198,6 +198,8 @@ X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
 
 By default each paid call signs one USDC payment (`exact`). For a burst of calls, switch to a **batch** payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling `1s_payment_mode` with `{ "mode": "batch" }` (or setting `X402_PAYMENT_MODE=batch`). The first batch call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the `1s_refund` tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.
 
+When paying via x402, the agent is also given batch guidance at startup so it can manage this for you: when it anticipates a burst of calls it offers to switch to batch mode and reminds you to `1s_refund` when done. Tune that behavior with the `1s_batch_config` tool — set whether the agent asks first / switches automatically / only on request (`prompt`), how many calls count as "a burst" (`threshold`), the deposit multiplier, and the default mode, all from your session. Changes are saved to a server-managed config file and persist across restarts, so you never have to edit the MCP config or set env vars by hand. (The matching `X402_BATCH_PROMPT` / `X402_BATCH_THRESHOLD` / `X402_PAYMENT_MODE` / `X402_DEPOSIT_MULTIPLIER` env vars still work as install-time defaults.) Run `1s_setup_check` to see your current mode, whether batch is available, and these settings.
+
 ### Security
 
 Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
@@ -206,14 +208,27 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
 
 ## Environment Variables
 
+### Required
+
+Set one to access the blockchain API tools. Without either, only the no-auth Setup & Ops tools work. API key takes priority when both are set.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
-| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
+| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base. |
+
+### Optional / Advanced
+
+All have sensible defaults — batch mode runs out of the box. Set these only to tune how `batch` mode behaves or how proactively the agent reaches for it. Payment modes can also be switched at runtime with the `1s_payment_mode` tool.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
 | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
 | `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
-| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
+| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode. |
 | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
+| `X402_BATCH_PROMPT` | `ask` | How the agent handles switching to batch mode: `ask` (confirm first), `auto` (switch on its own), or `off` (only when explicitly asked). |
+| `X402_BATCH_THRESHOLD` | `5` | Number of anticipated calls in a session at/above which the agent considers batch mode. Advisory — the agent estimates the count; not a hard runtime counter. |
 
 ## Troubleshooting
 

package/README.npm.md

@@ -1,6 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 29 tools for blockchain data and live chain queries in a single server.
+Unified MCP server for [OneSource](https://docs.onesource.io) — 30 tools for blockchain data and live chain queries in a single server.
 
 > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
 
 Health check: `GET http://localhost:3000/health`
 
-## Tools (29)
+## Tools (30)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -90,13 +90,14 @@ RPC only.
 | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
 | `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
 
-### Setup & Ops (2 tools)
+### Setup & Ops (3 tools)
 
 No authentication required.
 
 | Tool | Purpose | When to use |
 |------|---------|-------------|
-| `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
+| `1s_setup_check` | Server health, version, auth status, batch-settlement status, and setup instructions | First thing to call — checks if everything is configured |
+| `1s_batch_config` | View or change x402 batch-settlement preferences (autonomy, threshold, deposit multiplier, default mode) and persist them across restarts — no config editing required | Configure batch behaviour from the session |
 | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
 
 ## Networks
@@ -107,7 +108,6 @@ All blockchain API tools accept an optional `network` parameter:
 |---------|-------------|
 | `ethereum` | Ethereum mainnet (default) |
 | `sepolia` | Ethereum Sepolia testnet |
-| `avax` | Avalanche C-Chain |
 
 ## Authentication
 
@@ -198,6 +198,8 @@ X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
 
 By default each paid call signs one USDC payment (`exact`). For a burst of calls, switch to a **batch** payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling `1s_payment_mode` with `{ "mode": "batch" }` (or setting `X402_PAYMENT_MODE=batch`). The first batch call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the `1s_refund` tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.
 
+When paying via x402, the agent is also given batch guidance at startup so it can manage this for you: when it anticipates a burst of calls it offers to switch to batch mode and reminds you to `1s_refund` when done. Tune that behavior with the `1s_batch_config` tool — set whether the agent asks first / switches automatically / only on request (`prompt`), how many calls count as "a burst" (`threshold`), the deposit multiplier, and the default mode, all from your session. Changes are saved to a server-managed config file and persist across restarts, so you never have to edit the MCP config or set env vars by hand. (The matching `X402_BATCH_PROMPT` / `X402_BATCH_THRESHOLD` / `X402_PAYMENT_MODE` / `X402_DEPOSIT_MULTIPLIER` env vars still work as install-time defaults.) Run `1s_setup_check` to see your current mode, whether batch is available, and these settings.
+
 ### Security
 
 Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
@@ -206,14 +208,27 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
 
 ## Environment Variables
 
+### Required
+
+Set one to access the blockchain API tools. Without either, only the no-auth Setup & Ops tools work. API key takes priority when both are set.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
-| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
+| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base. |
+
+### Optional / Advanced
+
+All have sensible defaults — batch mode runs out of the box. Set these only to tune how `batch` mode behaves or how proactively the agent reaches for it. Payment modes can also be switched at runtime with the `1s_payment_mode` tool.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
 | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
 | `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
-| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
+| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode. |
 | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
+| `X402_BATCH_PROMPT` | `ask` | How the agent handles switching to batch mode: `ask` (confirm first), `auto` (switch on its own), or `off` (only when explicitly asked). |
+| `X402_BATCH_THRESHOLD` | `5` | Number of anticipated calls in a session at/above which the agent considers batch mode. Advisory — the agent estimates the count; not a hard runtime counter. |
 
 ## Troubleshooting
 

package/README.repo.md

@@ -1,6 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 29 tools for blockchain data and live chain queries in a single server.
+Unified MCP server for [OneSource](https://docs.onesource.io) — 30 tools for blockchain data and live chain queries in a single server.
 
 > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:8080/`.
 
 Health check: `GET http://localhost:8080/health`
 
-## Tools (29)
+## Tools (30)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -96,15 +96,16 @@ RPC only.
 | `1s_refund`       | Refund unused `batch` channel balance back to your wallet on demand                                                                                           |
 
 
-### Setup & Ops (2 tools)
+### Setup & Ops (3 tools)
 
 No authentication required.
 
 
-| Tool             | Purpose                                                 | When to use                                              |
-| ---------------- | ------------------------------------------------------- | -------------------------------------------------------- |
-| `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
-| `1s_report_bug`  | Report bugs to Slack (or GitHub Issues fallback)        | When a tool errors or user wants to report an issue      |
+| Tool              | Purpose                                                 | When to use                                              |
+| ----------------- | ------------------------------------------------------- | -------------------------------------------------------- |
+| `1s_setup_check`  | Server health, version, auth status, batch-settlement status, and setup instructions | First thing to call — checks if everything is configured |
+| `1s_batch_config` | View or change x402 batch-settlement preferences (autonomy, threshold, deposit multiplier, default mode) and persist them across restarts — no config editing required | Configure batch behaviour from the session |
+| `1s_report_bug`   | Report bugs to Slack (or GitHub Issues fallback)        | When a tool errors or user wants to report an issue      |
 
 
 ## Networks
@@ -116,7 +117,6 @@ All blockchain API tools accept an optional `network` parameter:
 | ---------- | -------------------------- |
 | `ethereum` | Ethereum mainnet (default) |
 | `sepolia`  | Ethereum Sepolia testnet   |
-| `avax`     | Avalanche C-Chain          |
 
 
 ## Authentication
@@ -233,6 +233,8 @@ Instead of the `env` config block, you can set either variable as a shell or sys
 
 By default each paid call signs one USDC payment (`exact`). For a burst of calls, switch to a **batch** payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling `1s_payment_mode` with `{ "mode": "batch" }` (or setting `X402_PAYMENT_MODE=batch`). The first batch call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the `1s_refund` tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.
 
+When paying via x402, the agent receives batch guidance in its system prompt at startup, so it can manage this for you rather than leaving batching as a manual step: when it anticipates a burst of calls it offers to switch to batch mode and reminds you to `1s_refund` when finished. Control how proactive it is with `X402_BATCH_PROMPT` (`ask` / `auto` / `off`) and `X402_BATCH_THRESHOLD` (how many anticipated calls count as a burst) — see [Environment Variables](#optional--advanced). `1s_setup_check` reports your current mode, whether batch is available, and both settings.
+
 ### Security
 
 Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
@@ -241,18 +243,33 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
 
 ## Environment Variables
 
+### Required
+
+Set one to access the blockchain API tools. Without either, only the no-auth Setup & Ops tools work. API key takes priority when both are set.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
+| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base. |
 
-| Variable                  | Default                       | Description                                                                                                                        |
-| ------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `ONESOURCE_API_KEY`       | —                             | OneSource API key for Bearer token auth. Takes priority over x402.                                                                 |
-| `X402_PRIVATE_KEY`        | —                             | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base                                       |
-| `X402_PAYMENT_MODE`       | `exact`                       | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`.                    |
-| `X402_DEPOSIT_MULTIPLIER` | `10`                          | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |                                                                |
-| `X402_CHANNEL_DIR`        | —                             | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). 
-| `ONESOURCE_BASE_URL`      | `https://skills.onesource.io` | API base URL                                                                       |
-| `ONESOURCE_ANALYTICS`    | —                             | Set to `false` to disable analytics                                                |
-| `ONESOURCE_ANALYTICS_URL` | —                             | Dashboard endpoint for analytics                                                   |
-| `X402_ANALYTICS_KEY`     | —                             | API key for dashboard analytics                                                    |
+### Optional / Advanced
+
+All have sensible defaults — batch mode runs out of the box. Set these only to override an endpoint, tune how `batch` mode behaves, or adjust analytics. Payment modes can also be switched at runtime with the `1s_payment_mode` tool. The batch knobs below (`X402_PAYMENT_MODE`, `X402_DEPOSIT_MULTIPLIER`, `X402_BATCH_PROMPT`, `X402_BATCH_THRESHOLD`) can be set and persisted from a session with the `1s_batch_config` tool — no config editing or restart required; a saved config takes priority over these env vars.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL. |
+| `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
+| `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode. |
+| `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
+| `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
+| `X402_CHANNEL_SALT` | zero | Batch mode: 32-byte hex salt to derive the starting channel id. The client auto-rotates to the next salt when a channel is exhausted or refunded. |
+| `X402_BATCH_PROMPT` | `ask` | How the agent handles switching to batch mode: `ask` (confirm before switching), `auto` (switch on its own), or `off` (only switch when explicitly asked). |
+| `X402_BATCH_THRESHOLD` | `5` | Number of anticipated calls in a session at/above which the agent considers batch mode. Advisory — the agent estimates the call count; it is not a hard runtime counter. |
+| `ONESOURCE_CONFIG_DIR` | `~/.onesource` | Directory holding the server-managed batch config (`batch-config.json`) written by `1s_batch_config`. |
+| `ONESOURCE_ANALYTICS` | `true` | Set to `false` to disable analytics. |
+| `ONESOURCE_ANALYTICS_URL` | `https://1s-analytics.vercel.app` | Dashboard endpoint for analytics. |
+| `X402_ANALYTICS_KEY` | `onesource-mcp` | API key for dashboard analytics. |
 
 
 ## Troubleshooting
@@ -353,6 +370,14 @@ If you need to regenerate the keypair (this invalidates the current DNS record a
 
 #### Publishing a New Version
 
+> **Use the release script.** Releases are normally run via the coordinated release
+> script in the sre-services repo (`scripts/release-mcp.mjs` — see `sre-services/RELEASING.md`),
+> which performs all of the steps below across both `@one-source/api-mcp` and
+> `@one-source/mcp` in the correct order, including the `server.json` bump and
+> `mcp-publisher publish`. The First-Time Setup above is still the prerequisite for
+> the registry step. The manual steps below are the fallback for registry-only fixes
+> or when the script can't run.
+
 Every time you release a new npm version, update the MCP Registry:
 
 1. **Publish to npm** (the registry validates the package exists, so this must happen first):

package/dist/batch-prefs.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Batch-settlement preferences — server-managed and runtime-configurable.
+ *
+ * The x402 batch knobs (autonomy prompt, "many" threshold, deposit multiplier,
+ * and default payment mode) were previously settable only via env vars, which
+ * meant editing the MCP client config and restarting. This module lets them be
+ * set from within a session (via the `1s_batch_config` tool) and persists them
+ * to a server-owned file so they survive restarts without touching the client
+ * config.
+ *
+ * Resolution priority per field: persisted file > env var > built-in default.
+ *
+ * Resolved values are mirrored back into process.env (X402_PAYMENT_MODE,
+ * X402_DEPOSIT_MULTIPLIER) so the downstream @one-source/api-mcp x402 code —
+ * which reads those env vars directly — transparently honours them. This module
+ * intentionally has no dependency on api-mcp: applying the live payment scheme
+ * (setPaymentMode) is left to the caller.
+ */
+export type BatchPromptPref = 'ask' | 'auto' | 'off';
+export type PaymentMode = 'exact' | 'batch';
+export interface BatchPrefs {
+    /** Agent autonomy when deciding to switch to batch mode. */
+    prompt: BatchPromptPref;
+    /** Anticipated call count at/above which batching is worth considering. */
+    threshold: number;
+    /** Channel deposit = call price × this multiplier. */
+    depositMultiplier: number;
+    /** Payment scheme the session starts in. */
+    mode: PaymentMode;
+}
+export declare const DEFAULT_BATCH_PREFS: BatchPrefs;
+/** Lowest deposit multiplier the batch-settlement SDK accepts. */
+export declare const MIN_DEPOSIT_MULTIPLIER = 3;
+export declare function coercePrompt(v: unknown): BatchPromptPref | undefined;
+export declare function coerceThreshold(v: unknown): number | undefined;
+export declare function coerceMultiplier(v: unknown): number | undefined;
+export declare function coerceMode(v: unknown): PaymentMode | undefined;
+/**
+ * Resolve preferences (file > env > default), cache them, and mirror the
+ * api-mcp-consumed values into process.env. Call once at startup BEFORE
+ * setupX402() so the deposit multiplier and initial mode are in place before
+ * the batch channel is built.
+ */
+export declare function loadBatchPrefs(): BatchPrefs;
+/** Current preferences (lazily resolved on first access). */
+export declare function getBatchPrefs(): BatchPrefs;
+export interface SetBatchResult {
+    prefs: BatchPrefs;
+    /** True when the change was written to the config file. */
+    persisted: boolean;
+    /** Set when persistence failed — the in-memory update still took effect. */
+    persistError?: string;
+}
+/**
+ * Merge a (pre-validated) patch into the current preferences, persist to the
+ * config file, and mirror to process.env. Caller is responsible for validating
+ * raw user input (use the coerce* helpers) and for applying any mode change to
+ * the live payment scheme via setPaymentMode().
+ */
+export declare function setBatchPrefs(patch: Partial<BatchPrefs>): SetBatchResult;
+/** Clear persisted overrides — delete the file and re-resolve from env/defaults. */
+export declare function resetBatchPrefs(): SetBatchResult;
+/** Absolute path to the config file (for display in setup output). */
+export declare function batchConfigPath(): string;
+/** Whether a persisted config file currently exists. */
+export declare function hasPersistedConfig(): boolean;
+//# sourceMappingURL=batch-prefs.d.ts.map

package/dist/batch-prefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-prefs.d.ts","sourceRoot":"","sources":["../src/batch-prefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AACrD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,MAAM,EAAE,eAAe,CAAC;IACxB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,EAAE,UAKjC,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAaxC,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAGpE;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG9D;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAG/D;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAG9D;AA+DD;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAI3C;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,IAAI,UAAU,CAG1C;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,cAAc,CAgBxE;AAED,oFAAoF;AACpF,wBAAgB,eAAe,IAAI,cAAc,CAQhD;AAED,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,OAAO,CAM5C"}

package/dist/batch-prefs.js

@@ -0,0 +1,181 @@
+/**
+ * Batch-settlement preferences — server-managed and runtime-configurable.
+ *
+ * The x402 batch knobs (autonomy prompt, "many" threshold, deposit multiplier,
+ * and default payment mode) were previously settable only via env vars, which
+ * meant editing the MCP client config and restarting. This module lets them be
+ * set from within a session (via the `1s_batch_config` tool) and persists them
+ * to a server-owned file so they survive restarts without touching the client
+ * config.
+ *
+ * Resolution priority per field: persisted file > env var > built-in default.
+ *
+ * Resolved values are mirrored back into process.env (X402_PAYMENT_MODE,
+ * X402_DEPOSIT_MULTIPLIER) so the downstream @one-source/api-mcp x402 code —
+ * which reads those env vars directly — transparently honours them. This module
+ * intentionally has no dependency on api-mcp: applying the live payment scheme
+ * (setPaymentMode) is left to the caller.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
+export const DEFAULT_BATCH_PREFS = {
+    prompt: 'ask',
+    threshold: 5,
+    depositMultiplier: 10,
+    mode: 'exact',
+};
+/** Lowest deposit multiplier the batch-settlement SDK accepts. */
+export const MIN_DEPOSIT_MULTIPLIER = 3;
+function configDir() {
+    const override = process.env.ONESOURCE_CONFIG_DIR?.trim();
+    return override && override.length > 0 ? override : join(homedir(), '.onesource');
+}
+function configFile() {
+    return join(configDir(), 'batch-config.json');
+}
+// --- field coercers: return undefined when the raw value is absent/invalid ---
+export function coercePrompt(v) {
+    const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    return s === 'ask' || s === 'auto' || s === 'off' ? s : undefined;
+}
+export function coerceThreshold(v) {
+    const n = typeof v === 'number' ? v : parseInt(String(v ?? ''), 10);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+export function coerceMultiplier(v) {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) && n >= MIN_DEPOSIT_MULTIPLIER ? n : undefined;
+}
+export function coerceMode(v) {
+    const s = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    return s === 'exact' || s === 'batch' ? s : undefined;
+}
+// Snapshot the launch-time env vars ONCE at module load. We mirror resolved
+// values back into process.env (so api-mcp's x402 layer honours them), which
+// would otherwise corrupt the env baseline — a later reset() would read our own
+// mirror instead of the original env. Reading the snapshot keeps env precedence
+// stable across set/reset cycles.
+const ENV_SNAPSHOT = {
+    prompt: process.env.X402_BATCH_PROMPT,
+    threshold: process.env.X402_BATCH_THRESHOLD,
+    depositMultiplier: process.env.X402_DEPOSIT_MULTIPLIER,
+    mode: process.env.X402_PAYMENT_MODE,
+};
+let _cache;
+/** Read + validate the persisted file, ignoring any invalid/missing fields. */
+function readPersisted() {
+    try {
+        const data = JSON.parse(readFileSync(configFile(), 'utf8'));
+        const out = {};
+        const prompt = coercePrompt(data.prompt);
+        if (prompt)
+            out.prompt = prompt;
+        const threshold = coerceThreshold(data.threshold);
+        if (threshold)
+            out.threshold = threshold;
+        const depositMultiplier = coerceMultiplier(data.depositMultiplier);
+        if (depositMultiplier)
+            out.depositMultiplier = depositMultiplier;
+        const mode = coerceMode(data.mode);
+        if (mode)
+            out.mode = mode;
+        return out;
+    }
+    catch {
+        // No file, unreadable, or malformed JSON — fall back to env/defaults.
+        return {};
+    }
+}
+function fromEnv() {
+    const out = {};
+    const prompt = coercePrompt(ENV_SNAPSHOT.prompt);
+    if (prompt)
+        out.prompt = prompt;
+    const threshold = coerceThreshold(ENV_SNAPSHOT.threshold);
+    if (threshold)
+        out.threshold = threshold;
+    const depositMultiplier = coerceMultiplier(ENV_SNAPSHOT.depositMultiplier);
+    if (depositMultiplier)
+        out.depositMultiplier = depositMultiplier;
+    const mode = coerceMode(ENV_SNAPSHOT.mode);
+    if (mode)
+        out.mode = mode;
+    return out;
+}
+/** Mirror api-mcp-consumed values into process.env so its x402 layer honours them. */
+function mirrorToEnv(prefs) {
+    process.env.X402_PAYMENT_MODE = prefs.mode;
+    process.env.X402_DEPOSIT_MULTIPLIER = String(prefs.depositMultiplier);
+}
+function resolve() {
+    return {
+        ...DEFAULT_BATCH_PREFS,
+        ...fromEnv(), // env over default
+        ...readPersisted(), // file over env
+    };
+}
+/**
+ * Resolve preferences (file > env > default), cache them, and mirror the
+ * api-mcp-consumed values into process.env. Call once at startup BEFORE
+ * setupX402() so the deposit multiplier and initial mode are in place before
+ * the batch channel is built.
+ */
+export function loadBatchPrefs() {
+    _cache = resolve();
+    mirrorToEnv(_cache);
+    return _cache;
+}
+/** Current preferences (lazily resolved on first access). */
+export function getBatchPrefs() {
+    if (!_cache)
+        loadBatchPrefs();
+    return _cache;
+}
+/**
+ * Merge a (pre-validated) patch into the current preferences, persist to the
+ * config file, and mirror to process.env. Caller is responsible for validating
+ * raw user input (use the coerce* helpers) and for applying any mode change to
+ * the live payment scheme via setPaymentMode().
+ */
+export function setBatchPrefs(patch) {
+    const next = { ...getBatchPrefs(), ...patch };
+    let persisted = false;
+    let persistError;
+    try {
+        mkdirSync(configDir(), { recursive: true });
+        writeFileSync(configFile(), JSON.stringify(next, null, 2) + '\n', 'utf8');
+        persisted = true;
+    }
+    catch (err) {
+        persistError = err instanceof Error ? err.message : String(err);
+    }
+    _cache = next;
+    mirrorToEnv(next);
+    return { prefs: next, persisted, persistError };
+}
+/** Clear persisted overrides — delete the file and re-resolve from env/defaults. */
+export function resetBatchPrefs() {
+    let persistError;
+    try {
+        rmSync(configFile(), { force: true });
+    }
+    catch (err) {
+        persistError = err instanceof Error ? err.message : String(err);
+    }
+    return { prefs: loadBatchPrefs(), persisted: persistError === undefined, persistError };
+}
+/** Absolute path to the config file (for display in setup output). */
+export function batchConfigPath() {
+    return configFile();
+}
+/** Whether a persisted config file currently exists. */
+export function hasPersistedConfig() {
+    try {
+        return existsSync(configFile());
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=batch-prefs.js.map

package/dist/batch-prefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-prefs.js","sourceRoot":"","sources":["../src/batch-prefs.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AA2VH,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AAgZH,OAAO,EAAE,CAAC"}