@agenttrust-sdk/mcp 0.3.1 → 0.3.3

package/README.md

@@ -24,7 +24,7 @@ deployed AgentTrust programs through natural language.
 | `agenttrust_list_facilitators` | Active facilitator adapters (Pay.sh / Dexter / atxp / MCPay) + ship status. |
 | `agenttrust_demo_state` | Three pre-warmed devnet counterparties used by `examples/pay-sh-demo`. |
 
-### Write (require `KEYPAIR_B58` env)
+### Write (require a signer: `KEYPAIR_B58` / `KEYPAIR_PATH` / Solana CLI default)
 
 | Tool | Effect |
 |--|--|
@@ -105,7 +105,17 @@ The script edits the Claude Desktop config in place. It backs up the
 prior config to `claude_desktop_config.json.bak.<timestamp>` so you can
 revert if needed.
 
-For write tools, add `KEYPAIR_B58` to the `env` block:
+For write tools, supply a signer via any one of the four steps in the
+resolution chain (first match wins):
+
+1. `KEYPAIR_B58` — base58-encoded 64-byte secret key
+2. `KEYPAIR_PATH` — absolute path to a JSON-array secret-key file (Solana CLI native format)
+3. `~/.config/solana/id.json` — Solana CLI's default keypair location, picked up automatically
+4. `SOLANA_KEYPAIR_PATH` — alt path env some tooling sets
+
+If you already use `solana-keygen` locally, no env is needed — the
+default `~/.config/solana/id.json` is detected automatically. To set an
+explicit signer in the Claude Desktop config block:
 
 ```json
 "env": {
@@ -115,6 +125,16 @@ For write tools, add `KEYPAIR_B58` to the `env` block:
 }
 ```
 
+Or point at a file instead of inlining the secret:
+
+```json
+"env": {
+  "RPC_URL":      "https://api.devnet.solana.com",
+  "NETWORK":      "solana-devnet",
+  "KEYPAIR_PATH": "/Users/you/.config/solana/id.json"
+}
+```
+
 ### Cursor
 
 Cursor's MCP config lives at `~/.cursor/mcp.json` (or per-workspace
@@ -176,7 +196,9 @@ The server listens on `http://0.0.0.0:8765`. Behind any reverse proxy
 |--|--|--|
 | `RPC_URL` | devnet RPC | Solana RPC endpoint. |
 | `NETWORK` | `solana-devnet` | `solana-devnet` or `solana-mainnet`. Drives Quantu program IDs. |
-| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. Required for write tools. |
+| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. First step in the signer-resolution chain. |
+| `KEYPAIR_PATH` | unset | Path to a JSON-array secret-key file (Solana CLI native format). Second step in the signer-resolution chain. |
+| `SOLANA_KEYPAIR_PATH` | unset | Alt path env some tooling sets. Fourth step in the signer-resolution chain. |
 | `MCP_TRANSPORT` | `stdio` | `stdio` or `http`. |
 | `MCP_HTTP_PORT` | `8765` | Port for HTTP transport. |
 | `POLICY_VAULT_PROGRAM_ID` | devnet ID | Override the policy_vault program ID. |

package/dist/chain.js

@@ -109,8 +109,10 @@ class ChainClient {
     }
     requireSigner() {
         if (!this.cfg.signer) {
-            throw new Error("This tool requires KEYPAIR_B58 in the environment. " +
-                "Set it to a base58-encoded 64-byte secret key, then restart the MCP server.");
+            throw new Error("This tool requires a signer. Set one of: KEYPAIR_B58 (base58 of a " +
+                "64-byte secret key), KEYPAIR_PATH (absolute path to a Solana CLI " +
+                "keypair JSON), or run `solana-keygen new` so ~/.config/solana/id.json " +
+                "exists. Then restart the MCP server.");
         }
         return this.cfg.signer;
     }

package/dist/chain.js.map

@@ -1 +1 @@
-{"version":3,"file":"chain.js","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmGH,oCAIC;AArGD,0DAA4C;AA0MN,wBAAM;AAzM5C,8CAAwE;AAyM/D,+FAzMA,uBAAc,OAyMA;AAAE,mFAzMA,WAAE,OAyMA;AAAE,wFAzMA,gBAAO,OAyMA;AAxMpC,6CAAiE;AAEjE,yDAiCmC;AAUjC,gGAxCA,2BAAe,OAwCA;AACf,kGAxCA,6BAAiB,OAwCA;AACjB,oGAxCA,+BAAmB,OAwCA;AACnB,qGAxCA,gCAAoB,OAwCA;AACpB,4GAxCA,uCAA2B,OAwCA;AAC3B,sGAxCA,iCAAqB,OAwCA;AACrB,oGAxCA,+BAAmB,OAwCA;AACnB,mGAxCA,8BAAkB,OAwCA;AAClB,+GAxCA,0CAA8B,OAwCA;AAC9B,6GAxCA,wCAA4B,OAwCA;AAwB5B,oGA5DA,+BAAmB,OA4DA;AAbnB,2GA9CA,sCAA0B,OA8CA;AAC1B,uGA9CA,kCAAsB,OA8CA;AACtB,qGA9CA,gCAAoB,OA8CA;AACpB,yGA9CA,oCAAwB,OA8CA;AAPxB,sGAtCA,iCAAqB,OAsCA;AACrB,qGAtCA,gCAAoB,OAsCA;AAPpB,yGA9BA,oCAAwB,OA8BA;AACxB,6GA9BA,wCAA4B,OA8BA;AAC5B,+GA9BA,0CAA8B,OA8BA;AAC9B,2GA9BA,sCAA0B,OA8BA;AAa1B,wGA1CA,mCAAuB,OA0CA;AACvB,yGA1CA,oCAAwB,OA0CA;AACxB,yGA1CA,oCAAwB,OA0CA;AACxB,2GA1CA,sCAA0B,OA0CA;AAC1B,wGA1CA,mCAAuB,OA0CA;AAWzB,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;GAIG;AACH,SAAgB,YAAY,CAAC,GAAqB;IAChD,MAAM,IAAI,GAAK,IAAI,oBAAU,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,IAAI,eAAM,CAAC,GAAG,CAAC,MAAM,IAAI,iBAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5D,OAAO,IAAI,uBAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAa,WAAW;IAQtB,YAAY,GAAqB;QAC/B,IAAI,CAAC,GAAG,GAAQ,GAAG,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;IAClC,CAAC;IAED,wEAAwE;IACxE,YAAY;QACV,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,CAAC;IAED,aAAa;QACX,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,oEAAoE;gBACpE,mEAAmE;gBACnE,wEAAwE;gBACxE,sCAAsC,CACvC,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,YAAY,GAAG,MAAM,IAAA,2BAAe,EACvC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC,WAAW,CACvE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,IAAI,CAAC,UAAU,GAAG,MAAM,IAAA,yBAAa,EACnC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC,SAAS,CACnE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,kBAAkB;QACtB,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,IAAI,CAAC,mBAAmB,GAAG,MAAM,IAAA,kCAAsB,EACrD,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC,kBAAkB,CACrF,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,mBAAmB,CAAC;IAClC,CAAC;CACF;AA5DD,kCA4DC;AAED,8EAA8E;AAC9E,qEAAqE;AACrE,wEAAwE;AACxE,qEAAqE;AACrE,2CAA2C;AAC3C,kDAAkD;AAClD,sEAAsE;AACtE,uEAAuE;AACvE,mCAAmC;AACnC,yEAAyE;AACzE,oEAAoE;AACpE,4DAA4D;AAC5D,8EAA8E;AAE9E,qGAAqG;AACrG,MAAM,cAAc,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;AAC1D,qGAAqG;AACrG,MAAM,YAAY,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AACrD,qGAAqG;AACrG,MAAM,qBAAqB,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAC;AAExE,MAAM,YAAY,GAAG;IACnB,8DAA8D;IAC9D,WAAW,EAAS,cAAqB;IACzC,8DAA8D;IAC9D,SAAS,EAAW,YAAmB;IACvC,8DAA8D;IAC9D,kBAAkB,EAAE,qBAA4B;CACjD,CAAC"}

package/dist/config.d.ts

@@ -1,7 +1,13 @@
 /**
  * Env parsing for the AgentTrust MCP server.
  *
- * Read tools work without any env. Write tools require `KEYPAIR_B58`.
+ * Read tools work without any env. Write tools require a signer
+ * keypair, resolved through a four-step fallback chain (see `readSigner`):
+ *   1. `KEYPAIR_B58`            — base58 of the 64-byte secret key
+ *   2. `KEYPAIR_PATH`           — JSON-array secret-key file (Solana CLI native)
+ *   3. `~/.config/solana/id.json` — Solana CLI's default keypair location
+ *   4. `SOLANA_KEYPAIR_PATH`    — alt name some tooling sets
+ *
  * The HTTP transport requires `MCP_HTTP_PORT` (else stdio is the default).
  *
  * Defaults are biased toward the local-developer / Claude Desktop case:
@@ -19,15 +25,29 @@ export interface AgentTrustConfig {
      *  shape rather than a sibling field on AgentTrustConfig. */
     readonly programs: ProgramIds;
     readonly quantu: QuantuProgramIds;
-    /** Optional signer keypair. Loaded from KEYPAIR_B58. Write tools require this. */
+    /** Optional signer keypair. Resolved via the layered fallback chain
+     *  documented on `readSigner`. Write tools require this. */
     readonly signer?: Keypair;
     /** Transport selection. */
     readonly transport: "stdio" | "http";
     /** HTTP transport port (only used when transport === "http"). */
     readonly httpPort: number;
+    /** HTTP transport bind host (only used when transport === "http").
+     *  Defaults to 127.0.0.1 so a laptop developer doesn't expose the
+     *  server on the LAN. Production-style deploys (Fly, Vercel) set
+     *  `MCP_HTTP_HOST=0.0.0.0` explicitly. */
+    readonly httpHost: string;
     /** Optional default facilitator name to surface in tool replies. */
     readonly defaultFacilitator?: string;
 }
+/**
+ * Decode a JSON-array secret-key file (Solana CLI's native format) into
+ * a Keypair. Exported for direct testing.
+ *
+ * Throws with a clear, source-named error when the file is unreadable,
+ * not valid JSON, not an array of numbers, or the wrong byte length.
+ */
+export declare function readKeypairFile(filePath: string): Keypair;
 export declare function loadConfig(): AgentTrustConfig;
 /**
  * Build a Solana Explorer URL for a tx signature or account, scoped to

package/dist/config.js

@@ -2,18 +2,61 @@
 /**
  * Env parsing for the AgentTrust MCP server.
  *
- * Read tools work without any env. Write tools require `KEYPAIR_B58`.
+ * Read tools work without any env. Write tools require a signer
+ * keypair, resolved through a four-step fallback chain (see `readSigner`):
+ *   1. `KEYPAIR_B58`            — base58 of the 64-byte secret key
+ *   2. `KEYPAIR_PATH`           — JSON-array secret-key file (Solana CLI native)
+ *   3. `~/.config/solana/id.json` — Solana CLI's default keypair location
+ *   4. `SOLANA_KEYPAIR_PATH`    — alt name some tooling sets
+ *
  * The HTTP transport requires `MCP_HTTP_PORT` (else stdio is the default).
  *
  * Defaults are biased toward the local-developer / Claude Desktop case:
  * devnet RPC, devnet program IDs, no signer required.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readKeypairFile = readKeypairFile;
 exports.loadConfig = loadConfig;
 exports.explorerUrl = explorerUrl;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
 const web3_js_1 = require("@solana/web3.js");
 const bs58_1 = __importDefault(require("bs58"));
 const trustgate_1 = require("@agenttrust-sdk/trustgate");
@@ -26,34 +69,140 @@ function readNetwork() {
     }
     return "solana-devnet";
 }
-function readSigner() {
-    const raw = process.env.KEYPAIR_B58?.trim();
-    if (!raw)
-        return undefined;
+/**
+ * Decode a JSON-array secret-key file (Solana CLI's native format) into
+ * a Keypair. Exported for direct testing.
+ *
+ * Throws with a clear, source-named error when the file is unreadable,
+ * not valid JSON, not an array of numbers, or the wrong byte length.
+ */
+function readKeypairFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new Error(`keypair file at ${filePath} is unreadable: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`keypair file at ${filePath} is not valid JSON: ${err.message}`);
+    }
+    if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === "number")) {
+        throw new Error(`keypair file at ${filePath} must be a JSON array of numbers (Solana CLI format)`);
+    }
+    const bytes = Uint8Array.from(parsed);
+    if (bytes.length !== 64) {
+        throw new Error(`keypair file at ${filePath}: expected 64-byte secret key, got ${bytes.length} bytes`);
+    }
     try {
-        const bytes = bs58_1.default.decode(raw);
         return web3_js_1.Keypair.fromSecretKey(bytes);
     }
     catch (err) {
-        throw new Error(`KEYPAIR_B58 is set but failed to decode: ${err.message}. ` +
-            `Expected base58-encoded 64-byte secret key.`);
+        throw new Error(`keypair file at ${filePath} could not be loaded as a Solana keypair: ${err.message}`);
+    }
+}
+/**
+ * Layered signer detection. Tries, in order:
+ *   1. `KEYPAIR_B58`           (base58 of 64-byte secret key)
+ *   2. `KEYPAIR_PATH`          (JSON-array secret-key file)
+ *   3. `~/.config/solana/id.json` (Solana CLI's default keypair location)
+ *   4. `SOLANA_KEYPAIR_PATH`   (alt name some tooling sets)
+ *
+ * Explicit env vars win over the well-known default. If an env var is
+ * SET but unparseable, we throw a clear error naming the source. If
+ * unset, we fall through silently. If none of the four is usable we
+ * return undefined — the read-only mode for no-auth read tools.
+ */
+function readSigner() {
+    const b58 = process.env.KEYPAIR_B58?.trim();
+    if (b58) {
+        let bytes;
+        try {
+            bytes = bs58_1.default.decode(b58);
+        }
+        catch (err) {
+            throw new Error(`KEYPAIR_B58 is set but failed to decode as base58: ${err.message}. ` +
+                `Expected base58-encoded 64-byte secret key.`);
+        }
+        if (bytes.length !== 64) {
+            throw new Error(`KEYPAIR_B58 decoded to ${bytes.length} bytes; expected 64-byte secret key. ` +
+                `A 32-byte value is the public-key half only — Solana keypair files contain both halves.`);
+        }
+        try {
+            return web3_js_1.Keypair.fromSecretKey(bytes);
+        }
+        catch (err) {
+            throw new Error(`KEYPAIR_B58 decoded to 64 bytes but Solana rejected it: ${err.message}`);
+        }
     }
+    const explicitPath = process.env.KEYPAIR_PATH?.trim();
+    if (explicitPath) {
+        try {
+            return readKeypairFile(explicitPath);
+        }
+        catch (err) {
+            throw new Error(`KEYPAIR_PATH points at ${explicitPath} but the file is unreadable: ${err.message}`);
+        }
+    }
+    const altPath = process.env.SOLANA_KEYPAIR_PATH?.trim();
+    if (altPath) {
+        try {
+            return readKeypairFile(altPath);
+        }
+        catch (err) {
+            throw new Error(`SOLANA_KEYPAIR_PATH points at ${altPath} but the file is unreadable: ${err.message}`);
+        }
+    }
+    const defaultPath = path.join(os.homedir(), ".config", "solana", "id.json");
+    if (fs.existsSync(defaultPath)) {
+        try {
+            return readKeypairFile(defaultPath);
+        }
+        catch (err) {
+            throw new Error(`Solana CLI default keypair at ${defaultPath} is unusable: ${err.message}`);
+        }
+    }
+    return undefined;
 }
 function readTransport() {
     const raw = (process.env.MCP_TRANSPORT ?? "stdio").trim().toLowerCase();
     const port = Number.parseInt(process.env.MCP_HTTP_PORT ?? "8765", 10);
+    // Default bind 127.0.0.1 — a local-laptop user starting `MCP_TRANSPORT=http`
+    // should NOT expose the server on the LAN by accident. Hosted deploys
+    // (Fly, Vercel) explicitly set MCP_HTTP_HOST=0.0.0.0.
+    const host = (process.env.MCP_HTTP_HOST ?? "127.0.0.1").trim();
     if (raw === "http" || raw === "sse")
-        return { transport: "http", httpPort: port };
-    return { transport: "stdio", httpPort: port };
+        return { transport: "http", httpPort: port, httpHost: host };
+    return { transport: "stdio", httpPort: port, httpHost: host };
 }
 function loadConfig() {
     const network = readNetwork();
     const rpcUrl = (process.env.RPC_URL ?? (network === "solana-mainnet" ? MAINNET_RPC : DEVNET_RPC)).trim();
-    const { transport, httpPort } = readTransport();
-    // Devnet ships fully-deployed AgentTrust + Quantu. Mainnet ships
-    // Quantu only (per CLAUDE.md). When mainnet is selected the AgentTrust
-    // program IDs default to devnet placeholders — overridable via env once
-    // mainnet deployment lands.
+    try {
+        // eslint-disable-next-line no-new
+        new URL(rpcUrl);
+    }
+    catch (err) {
+        throw new Error(`RPC_URL is not a valid URL: ${err.message}. Got: ${rpcUrl}`);
+    }
+    const { transport, httpPort, httpHost } = readTransport();
+    // AgentTrust programs ship on devnet. Quantu ships on both devnet and
+    // mainnet. When mainnet is selected the AgentTrust program IDs must be
+    // overridden via env — otherwise we'd silently point at devnet pubkeys
+    // on a mainnet RPC (every read returns `exists: false`, every write
+    // throws cryptic Anchor errors).
+    const policyVaultEnv = process.env.POLICY_VAULT_PROGRAM_ID?.trim();
+    const trustGateEnv = process.env.TRUSTGATE_PROGRAM_ID?.trim();
+    const validationRegistryEnv = process.env.VALIDATION_REGISTRY_PROGRAM_ID?.trim();
+    if (network === "solana-mainnet" && !policyVaultEnv && !trustGateEnv && !validationRegistryEnv) {
+        throw new Error("AgentTrust programs are not yet deployed on mainnet. " +
+            "Set explicit POLICY_VAULT_PROGRAM_ID, TRUSTGATE_PROGRAM_ID, and " +
+            "VALIDATION_REGISTRY_PROGRAM_ID env vars, or use NETWORK=solana-devnet (default).");
+    }
     const programs = {
         policyVault: parsePubkeyEnv("POLICY_VAULT_PROGRAM_ID", trustgate_1.DEFAULT_DEVNET_PROGRAM_IDS.policyVault),
         trustGate: parsePubkeyEnv("TRUSTGATE_PROGRAM_ID", trustgate_1.DEFAULT_DEVNET_PROGRAM_IDS.trustGate),
@@ -71,6 +220,7 @@ function loadConfig() {
         signer: readSigner(),
         transport,
         httpPort,
+        httpHost,
         defaultFacilitator: process.env.MCP_DEFAULT_FACILITATOR?.trim() || undefined,
     };
 }

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DH,0CAuCC;AAwFD,gCAkDC;AAiBD,kCAQC;AAvQD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAE7B,6CAAqD;AACrD,gDAAwB;AAExB,yDAOmC;AA6BnC,MAAM,UAAU,GAAI,+BAA+B,CAAC;AACpD,MAAM,WAAW,GAAG,qCAAqC,CAAC;AAE1D,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC1E,IAAI,GAAG,KAAK,gBAAgB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,cAAc,EAAE,CAAC;QAC5E,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe,CAAC,QAAgB;IAC9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,mBAAoB,GAAa,CAAC,OAAO,EAAE,CACvE,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,uBAAwB,GAAa,CAAC,OAAO,EAAE,CAC3E,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,sDAAsD,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAkB,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,sCAAsC,KAAK,CAAC,MAAM,QAAQ,CACtF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,iBAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,6CAA8C,GAAa,CAAC,OAAO,EAAE,CACjG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,UAAU;IACjB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC5C,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,KAAiB,CAAC;QACtB,IAAI,CAAC;YACH,KAAK,GAAG,cAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,sDAAuD,GAAa,CAAC,OAAO,IAAI;gBAChF,6CAA6C,CAC9C,CAAC;QACJ,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,0BAA0B,KAAK,CAAC,MAAM,uCAAuC;gBAC7E,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,OAAO,iBAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,2DAA4D,GAAa,CAAC,OAAO,EAAE,CACpF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IACtD,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,CAAC;YACH,OAAO,eAAe,CAAC,YAAY,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,0BAA0B,YAAY,gCAAiC,GAAa,CAAC,OAAO,EAAE,CAC/F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,CAAC;IACxD,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,iCAAiC,OAAO,gCAAiC,GAAa,CAAC,OAAO,EAAE,CACjG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC5E,IAAI,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,eAAe,CAAC,WAAW,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,iCAAiC,WAAW,iBAAkB,GAAa,CAAC,OAAO,EAAE,CACtF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxE,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;IACtE,6EAA6E;IAC7E,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/D,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,KAAK;QAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAClG,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAChE,CAAC;AAED,SAAgB,UAAU;IACxB,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1G,IAAI,CAAC;QACH,kCAAkC;QAClC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,+BAAgC,GAAa,CAAC,OAAO,UAAU,MAAM,EAAE,CACxE,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,aAAa,EAAE,CAAC;IAE1D,sEAAsE;IACtE,uEAAuE;IACvE,uEAAuE;IACvE,oEAAoE;IACpE,iCAAiC;IACjC,MAAM,cAAc,GAAU,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,CAAC;IAC1E,MAAM,YAAY,GAAY,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC;IACvE,MAAM,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,EAAE,IAAI,EAAE,CAAC;IACjF,IAAI,OAAO,KAAK,gBAAgB,IAAI,CAAC,cAAc,IAAI,CAAC,YAAY,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC/F,MAAM,IAAI,KAAK,CACb,uDAAuD;YACvD,kEAAkE;YAClE,kFAAkF,CACnF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAe;QAC3B,WAAW,EAAS,cAAc,CAAC,yBAAyB,EAAU,sCAA0B,CAAC,WAAW,CAAC;QAC7G,SAAS,EAAW,cAAc,CAAC,sBAAsB,EAAa,sCAA0B,CAAC,SAAS,CAAC;QAC3G,kBAAkB,EAAE,cAAc,CAAC,gCAAgC,EAAG,yCAA6B,CAAC;KACrG,CAAC;IACF,MAAM,MAAM,GAAqB,OAAO,KAAK,gBAAgB;QAC3D,CAAC,CAAC,8BAAkB;QACpB,CAAC,CAAC,qCAAyB,CAAC;IAE9B,OAAO;QACL,OAAO;QACP,MAAM;QACN,eAAe,EAAO,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;QACzE,QAAQ;QACR,MAAM;QACN,MAAM,EAAgB,UAAU,EAAE;QAClC,SAAS;QACT,QAAQ;QACR,QAAQ;QACR,kBAAkB,EAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,SAAS;KAC/E,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,QAAmB;IACvD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,IAAI,CAAC;QACH,OAAO,IAAI,mBAAS,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,kCAAmC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CACzB,GAAqB,EACrB,IAAsB,EACtB,KAAa;IAEb,MAAM,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,EAAE,CAAC;IAChE,MAAM,MAAM,GAAG,GAAG,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,OAAO,+BAA+B,IAAI,GAAG,MAAM,EAAE,CAAC;AACxD,CAAC"}

package/dist/embedded-docs/mcp/hosted-endpoint.mdx

@@ -134,7 +134,7 @@ Phase M flagged this as Bug #4. Fixing it requires restructuring the transport i
 
 ## Auth
 
-The hosted endpoint has no authentication for read tools. Write tools require a `KEYPAIR_B58` environment variable on the *server*; the hosted instance doesn't have one set, so write tools surface the standard `signer required` error.
+The hosted endpoint has no authentication for read tools. Write tools require a signer on the *server* (resolved via `KEYPAIR_B58` / `KEYPAIR_PATH` / Solana CLI default); the hosted instance has none of these set, so write tools surface the standard `signer required` error.
 
 For write-tool access from a hosted MCP context, run your own instance with your own keypair:
 

package/dist/embedded-docs/mcp/install.mdx

@@ -96,7 +96,14 @@ Behind any reverse proxy (Caddy, nginx, Vercel, Fly.io) this surfaces as a publi
 
 ## Write tools — adding a keypair
 
-The five write tools (`agenttrust_init_policy`, `agenttrust_set_killswitch`, `agenttrust_request_validation`, `agenttrust_respond_to_validation`, `agenttrust_emit_feedback`) require a signing keypair. Add `KEYPAIR_B58` to the `env` block:
+The five write tools (`agenttrust_init_policy`, `agenttrust_set_killswitch`, `agenttrust_request_validation`, `agenttrust_respond_to_validation`, `agenttrust_emit_feedback`) require a signing keypair. The MCP server resolves a signer through a four-step chain (first match wins):
+
+1. `KEYPAIR_B58` — base58-encoded 64-byte secret key
+2. `KEYPAIR_PATH` — absolute path to a JSON-array secret-key file (Solana CLI native format)
+3. `~/.config/solana/id.json` — Solana CLI's default keypair location, picked up automatically
+4. `SOLANA_KEYPAIR_PATH` — alt path env some tooling sets
+
+If you already use `solana-keygen` locally, no env is needed. To set an explicit signer in the Claude Desktop config, add `KEYPAIR_B58` to the `env` block:
 
 ```json
 {
@@ -114,7 +121,7 @@ The five write tools (`agenttrust_init_policy`, `agenttrust_set_killswitch`, `ag
 }
 ```
 
-Without `KEYPAIR_B58`, write tools surface a clear `signer required` error. Read and discovery tools never need it.
+Without any usable signer, write tools surface a clear `signer required` error. Read and discovery tools never need one.
 
 Convert a Solana CLI keypair to base58:
 
@@ -135,7 +142,9 @@ cat ~/.config/solana/id.json | jq -r '.[0:64]' | npx bs58 encode
 |---|---|---|
 | `RPC_URL` | devnet RPC | Solana RPC endpoint |
 | `NETWORK` | `solana-devnet` | `solana-devnet` or `solana-mainnet`. Drives Quantu program IDs. |
-| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. Required for write tools. |
+| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. First step in the signer-resolution chain. |
+| `KEYPAIR_PATH` | unset | Path to a JSON-array secret-key file (Solana CLI native format). Second step in the signer-resolution chain. |
+| `SOLANA_KEYPAIR_PATH` | unset | Alt path env some tooling sets. Fourth step in the signer-resolution chain. |
 | `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
 | `MCP_HTTP_PORT` | `8765` | Port for HTTP transport |
 | `POLICY_VAULT_PROGRAM_ID` | devnet ID | Override `policy_vault` program ID |

package/dist/embedded-docs/mcp/tools.mdx

@@ -90,7 +90,7 @@ Returns the three pre-warmed devnet counterparties used by `examples/pay-sh-demo
 
 The demo state is bundled in the tarball as of 0.2.3 — the published package doesn't need a separate state file.
 
-## Write (5 tools — require `KEYPAIR_B58`)
+## Write (5 tools — require a signer: `KEYPAIR_B58` / `KEYPAIR_PATH` / Solana CLI default)
 
 | Tool | Effect |
 |---|---|
@@ -114,7 +114,7 @@ Required args: `subject_asset`, `claim_uri_hash_hex`, `deadline_slot`. The capab
 
 ### `agenttrust_respond_to_validation`
 
-Required args: `subject_asset`, `claim_payload_hash_hex`, `claim_uri_hash_hex`, `expires_at_slot`. The signer (the keypair behind `KEYPAIR_B58`) is the attestor. v1 trust model: tx signature authenticates; v1.1+ adds Ed25519 sysvar verify.
+Required args: `subject_asset`, `claim_payload_hash_hex`, `claim_uri_hash_hex`, `expires_at_slot`. The signer (resolved via the chain `KEYPAIR_B58` / `KEYPAIR_PATH` / Solana CLI default) is the attestor. v1 trust model: tx signature authenticates; v1.1+ adds Ed25519 sysvar verify.
 
 ### `agenttrust_emit_feedback`
 

package/dist/embedded-docs/quickstart.mdx

@@ -0,0 +1,83 @@
+---
+title: Quickstart
+description: AgentTrust in 60 seconds. Install the MCP server into Claude Desktop, create a policy, run a gate-decision simulation. No clone, no Anchor build.
+---
+
+Sixty seconds, three steps, one MCP server. By the end you have a real `PolicyAccount` PDA on devnet and a decoded `gate_payment` decision in your chat client. No clone, no Anchor build, no local validator.
+
+## 1. Install the MCP server into Claude Desktop
+
+Drop this block into `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "npx",
+      "args": ["-y", "@agenttrust-sdk/mcp"],
+      "env": {
+        "RPC_URL": "https://api.devnet.solana.com",
+        "NETWORK": "solana-devnet"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Eighteen tools are now wired in. Ten read-only tools work immediately on devnet with zero credentials. The five write tools resolve a signer through the chain `KEYPAIR_B58` then `KEYPAIR_PATH` then `~/.config/solana/id.json` then `SOLANA_KEYPAIR_PATH` and use the first one that parses. If you already use `solana-keygen`, the default `id.json` is picked up automatically and no env var is needed.
+
+## 2. Create a policy
+
+Ask Claude Desktop, in plain English:
+
+> Use agenttrust_init_policy to create policy 1 for my agent. Enable Spending (bitmask 2) with a per-transaction max of 1 USDC.
+
+The `agenttrust_init_policy` tool is self-healing. If your agent's `PolicyAuthority` PDA does not yet exist on devnet, the tool prepends an `init_authority` instruction (single member = your signer, threshold = 1) and submits both in one atomic transaction. You never see Anchor error 3012. Spending caps also default sanely: when at least one cap is set, unspecified peer caps default to the max of the specified caps rather than zero, so v1 policies (immutable post-init) cannot accidentally hard-deny every payment.
+
+```text
+Output:
+  txSignature:       4n8…ZxR
+  explorerTxUrl:     https://explorer.solana.com/tx/4n8…ZxR?cluster=devnet
+  policyPda:         9aF…tNm
+  effectiveSpending: { perTxMax: "1000000", dailyMax: "1000000", weeklyMax: "1000000" }
+  selfHealed:        true
+  healedSteps:       ["init_authority"]
+```
+
+Open the `explorerTxUrl` to see the on-chain transaction. The `policyPda` is the `PolicyAccount` PDA the gate evaluates against on every payment.
+
+## 3. Run a gate-decision simulation
+
+Now ask:
+
+> Use agenttrust_simulate_payment to gate a 5-USDC payment from the tier-3 demo agent to the tier-0 demo agent against policy 1. What does the gate decide?
+
+`agenttrust_simulate_payment` is read-only. It calls the on-chain `gate_payment` instruction in simulate mode and decodes the `GateDecision` return value — `Allow`, `Deny` with a stable reason code (1 through 15), or `RequireValidation` with the 32-byte capability hash. The same call path the Express service's `POST /verify` route uses for the real x402 v2 challenge.
+
+```text
+Output:
+  kind:       "Deny"
+  reasonCode: 5
+  reasonName: "SpendingPerTxExceeded"
+```
+
+The gate denied the payment because 5 USDC exceeds the 1 USDC per-tx cap you set in step 2. Drop the amount to 0.5 USDC and ask again. The decision flips to `Allow`. You have just exercised the full PolicyVault decision path on devnet from a chat prompt.
+
+## Where to next
+
+Sixty seconds is enough to feel the shape. The deeper paths:
+
+<Cards>
+  <Card title="The three live paths" href="/getting-started/quickstart">
+    Hit the live x402 demo, mount the SDK middleware on Express, wire the MCP server, all against the hosted devnet build.
+  </Card>
+  <Card title="MCP server" href="/mcp">
+    Eighteen tools, four resources, three guided prompts. Full install reference at /mcp/install.
+  </Card>
+  <Card title="@agenttrust-sdk/trustgate" href="/sdk">
+    The TypeScript SDK every facilitator pulls in. Express middleware, client helpers, the atomicity guard, the full ValidationRegistry instruction builder set.
+  </Card>
+  <Card title="Architecture" href="/architecture">
+    How the three Anchor programs compose into one settlement path. The atomic-tx invariant. The FacilitatorAdapter pattern.
+  </Card>
+</Cards>

package/dist/errors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Structured error envelopes for MCP `tools/call` responses (F-013).
+ *
+ * Before this module, every thrown handler error was flattened to
+ * `{ isError: true, content: [{type:"text",text:"tool error: <msg>"}] }`
+ * — opaque to LLM agents and useless for automated recovery.
+ *
+ * Now `classifyError()` inspects the thrown value and produces a
+ * `ToolError` with:
+ *   - `errorCode`: one of a fixed enum so callers can branch on it.
+ *   - `message`:   short human description (truncated original).
+ *   - `hint`:      single sentence of remediation guidance.
+ *   - `cause`:     truncated original message (<=500 chars) for debugging.
+ *
+ * `renderToolError()` serialises that envelope into the MCP
+ * `CallToolResult` shape. The envelope is JSON-encoded into
+ * `content[0].text` (so transports that only surface text still get a
+ * parseable payload), AND mirrored into `structuredContent` (the MCP
+ * spec field for machine-readable tool output, supported by the
+ * `@modelcontextprotocol/sdk` schema we already depend on).
+ *
+ * Tool handlers do NOT need to change. They still:
+ *   - `throw new Error("...")` for ad-hoc failures
+ *   - `throw new ZodError(...)` (implicitly, via `schema.parse()`)
+ *   - throw `AnchorError` / `SendTransactionError` (via `.rpc()` calls)
+ * The classifier sniffs the thrown value (name, message prefix,
+ * `instanceof` where the constructor is in scope) and maps it.
+ *
+ * Note for future contributors: callers reading `content[0].text` as a
+ * string will see a JSON object now, not a plain sentence. This is
+ * intentional — `isError: true` is preserved so existing transports
+ * still treat it as a failure. If you add a new tool that throws a
+ * specific subclass, extend `classifyError()` here rather than
+ * pattern-matching in `server.ts`.
+ */
+/** Stable enum of error categories surfaced to MCP clients. */
+export type ToolErrorCode = "auth_required" | "input_invalid" | "rpc_failure" | "chain_error" | "not_found" | "internal";
+export interface ToolError {
+    errorCode: ToolErrorCode;
+    message: string;
+    hint?: string;
+    cause?: string;
+}
+/**
+ * Classify an unknown thrown value into a structured `ToolError`.
+ *
+ * @param err      The thrown value from a tool handler (or Zod parse).
+ * @param toolName Optional — the MCP tool that was being invoked. When
+ *                 supplied, surfaces in the `auth_required` hint so the
+ *                 LLM agent knows which call to retry.
+ */
+export declare function classifyError(err: unknown, toolName?: string): ToolError;
+/**
+ * Build the MCP `CallToolResult` envelope for a classified error.
+ *
+ * Returns the canonical shape:
+ *   {
+ *     isError: true,
+ *     content: [{ type: "text", text: "<json string>" }],
+ *     structuredContent: <ToolError as object>
+ *   }
+ *
+ * The JSON-in-text duplication is intentional: MCP clients that only
+ * surface text content (current Claude Desktop fallback path) still get
+ * a parseable payload, while spec-compliant clients pick up the
+ * structured field directly.
+ *
+ * The return type is `unknown` so callers don't need to import the SDK's
+ * private `CallToolResult` zod type — the server handler returns
+ * `Promise<{ ... }>` and TS infers the shape at the call site.
+ */
+export declare function renderToolError(toolError: ToolError): {
+    isError: true;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: Record<string, unknown>;
+};