@muhaven/mcp 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.9] — 2026-05-23
+
+### Added
+
+- **`pathDDecodedCall` in the position.buy echo on Path D fallback.**
+  When the bundler trace contains a `zd_sponsorUserOperation` event,
+  the handler now decodes the userOp.callData inline and surfaces:
+
+      pathDDecodedCall: {
+        sender: '0x<kernel>',
+        kernelExecuteMode: '0x<32 bytes>',
+        kernelExecuteTarget: '0x<addr>',          // should == MuHavenSubscription
+        kernelExecuteValue: '0',
+        innerSelector: '0xd29b624b',              // purchase(...)
+        innerPurchaseTokenArg: '0x<addr>',        // the RWA token (MuHavenToken)
+        innerPurchaseMaxSharesHint: '14',
+        innerPurchaseEphemeralEOA: '0x<addr>',
+        expectedSubscriptionAddress: '0x<addr>',  // MCP env wiring
+        kernelExecuteTargetMatchesSubscription: true|false,
+        interpretation: 'kernel.execute target matches MuHavenSubscription. ...',
+      }
+
+  Lets the LLM read at-a-glance which contract the kernel was about
+  to call (kernel.execute target) vs which RWA token the inner
+  purchase() carries — the two are commonly confused (the inner
+  purchase's first arg IS the token address, but the kernel.execute
+  target should be the subscription).
+
+  The `interpretation` field branches on three cases:
+    1. target == expected subscription → "shape is correct; AA23 is
+       downstream of validator signature decode; check
+       muhaven.policy.session_key_status."
+    2. target == inner purchase.token → "kernel is dispatching to
+       the token instead of the subscription — code bug."
+    3. Anything else → "unexpected third-address dispatch."
+
+- **`decodeKernelExecuteSingleCall` exported from
+  `clients/kernel-encoder.ts`.** Sibling to the existing encoder;
+  reuses the same KERNEL_EXECUTE_ABI + single-call default mode.
+  Returns `null` on unsupported modes (batch / delegate / try) so
+  the diagnostic emits a clear gap instead of garbage.
+
+- **`scripts/decode-userop-trace.ts`** — standalone CLI that takes
+  the raw `pathDBundlerTrace` JSON via stdin and prints the same
+  decode + cross-check. Useful when triaging against an older MCP
+  version that doesn't ship `pathDDecodedCall`, or for offline
+  analysis from a saved trace.
+
+## [0.2.8] — 2026-05-23
+
+### Added
+
+- **`pathDBundlerTrace` inline in the `muhaven.position.buy` echo on
+  fallback.** Every Path D attempt now buffers its bundler RPC
+  round-trips in a 20-event ring on the `BundlerClient`; on any
+  fallback return the handler drains the ring and inlines it into
+  the echo:
+
+      pathDBundlerTrace: [
+        {
+          method: 'eth_call',
+          id: 12,
+          requestBody: '{"jsonrpc":"2.0","id":12,"method":"eth_call",...}',
+          responseStatus: 200,
+          responseBody: '{"jsonrpc":"2.0","id":12,"result":"0x..."}',
+          elapsedMs: 87,
+        },
+        {
+          method: 'zd_sponsorUserOperation',
+          id: 14,
+          requestBody: '{"jsonrpc":"2.0","method":"zd_sponsorUserOperation","params":[...]}',
+          responseStatus: 400,
+          responseBody: '{"error":"AA23 reverted ..."}',
+          error: { code: 'http_error', message: '...' },
+          elapsedMs: 412,
+        },
+      ]
+
+  Bodies truncated at 2KB. The LLM (and the operator reading the
+  tool result) sees the EXACT wire payload that the bundler /
+  paymaster rejected — no need for curl repro or Claude Code
+  subprocess log digging. Confirmed 2026-05-23 that Claude Code's
+  MCP client only captures subprocess stderr at handshake (not
+  during tool calls), so the 0.2.7 stderr-verbose path never reached
+  the LLM context during the smoke iterations.
+
+  Ring buffer is always-on (no env-gate, ~80KB worst-case per
+  BundlerClient instance) so the next gate is self-diagnosing
+  immediately without a second `npm i -g` cycle.
+
+  `BundlerClient.drainTrace()` returns + clears the ring; called at
+  the start of `attemptPathD` (clear stale) and again right before
+  the fallback echo (collect + inline).
+
+### Tests
+
+- bundler-client.test.ts: new ring-buffer behaviour cases (drain
+  returns a copy; drain clears; ring is bounded at 20; populates on
+  success + http_error + timeout + rpc_error).
+
 ## [0.2.7] — 2026-05-23
 
 ### Added

package/dist/broker.cjs

@@ -2783,7 +2783,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.7";
+    return "0.2.9";
   }
 }
 function printVersion() {

package/dist/broker.js

@@ -2785,7 +2785,7 @@ function printUsage() {
 }
 function getBrokerPackageVersion() {
   {
-    return "0.2.7";
+    return "0.2.9";
   }
 }
 function printVersion() {

package/dist/index.cjs

@@ -999,7 +999,7 @@ var BundlerClientError = class extends Error {
   code;
   detail;
 };
-var BundlerClient = class {
+var BundlerClient = class _BundlerClient {
   constructor(options) {
     this.options = options;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
@@ -1007,6 +1007,35 @@ var BundlerClient = class {
   options;
   fetchImpl;
   nextRpcId = 1;
+  /**
+   * Ring buffer of the most recent RPC round-trips. Surfaced via
+   * `drainTrace()` to the caller (attemptPathD) for inline diagnostic
+   * in the position.buy echo. Always populated (no env-gate) — bounded
+   * at 20 events × ~4KB each ≈ 80KB worst-case per client instance.
+   * Cheap enough to keep on for all installs so the next paymaster
+   * gate is self-diagnosing without a second binary spin.
+   */
+  static TRACE_BUFFER_SIZE = 20;
+  recentTrace = [];
+  /**
+   * Return AND CLEAR the in-memory trace ring. attemptPathD calls this
+   * right before constructing a fallback echo so the trace inlined
+   * into the echo corresponds to THAT smoke iteration (subsequent
+   * tool calls start with an empty buffer). Returns a copy so the
+   * caller can safely serialize without races against in-flight
+   * concurrent RPCs.
+   */
+  drainTrace() {
+    const snapshot = this.recentTrace.slice();
+    this.recentTrace = [];
+    return snapshot;
+  }
+  pushTrace(event) {
+    this.recentTrace.push(event);
+    if (this.recentTrace.length > _BundlerClient.TRACE_BUFFER_SIZE) {
+      this.recentTrace.shift();
+    }
+  }
   /**
    * Submit a signed UserOperation. Returns the userOpHash the bundler
    * computed (which must match the hash the broker signed — caller is
@@ -1212,10 +1241,12 @@ var BundlerClient = class {
     const id = this.nextRpcId++;
     const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
     const verbose = process.env.MUHAVEN_MCP_VERBOSE === "1";
+    const truncate = (s) => s.length > 2048 ? s.slice(0, 2048) + "\u2026(truncated)" : s;
+    const requestBody = truncate(body);
+    const startMs = Date.now();
     if (verbose) {
-      const bodyDump = body.length > 2048 ? body.slice(0, 2048) + "\u2026(truncated)" : body;
       process.stderr.write(
-        `[muhaven-mcp] [bundler\u2192] ${method} id=${id} body=${bodyDump}
+        `[muhaven-mcp] [bundler\u2192] ${method} id=${id} body=${requestBody}
 `
       );
     }
@@ -1238,22 +1269,38 @@ var BundlerClient = class {
       });
     } catch (err2) {
       clearTimeout(timer);
+      const elapsedMs2 = Date.now() - startMs;
       if (err2.name === "AbortError") {
         if (verbose) {
           process.stderr.write(`[muhaven-mcp] [bundler\u2717] ${method} id=${id} timeout
 `);
         }
+        this.pushTrace({
+          method,
+          id,
+          requestBody,
+          error: { code: "timeout", message: `bundler ${method} timed out` },
+          elapsedMs: elapsedMs2
+        });
         throw new BundlerClientError("timeout", `bundler ${method} timed out`);
       }
+      const netMsg = err2 instanceof Error ? err2.message : String(err2);
       if (verbose) {
         process.stderr.write(
-          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} network err=${err2 instanceof Error ? err2.message : String(err2)}
+          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} network err=${netMsg}
 `
         );
       }
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        error: { code: "network", message: `bundler ${method} network error: ${netMsg}` },
+        elapsedMs: elapsedMs2
+      });
       throw new BundlerClientError(
         "network",
-        `bundler ${method} network error: ${err2 instanceof Error ? err2.message : String(err2)}`,
+        `bundler ${method} network error: ${netMsg}`,
         err2
       );
     } finally {
@@ -1271,6 +1318,18 @@ var BundlerClient = class {
 `
         );
       }
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        responseBody: text,
+        error: {
+          code: "http_error",
+          message: `bundler ${method} \u2192 HTTP ${res.status}: ${text}`
+        },
+        elapsedMs: Date.now() - startMs
+      });
       throw new BundlerClientError(
         "http_error",
         `bundler ${method} \u2192 HTTP ${res.status}: ${text}`
@@ -1280,24 +1339,43 @@ var BundlerClient = class {
     try {
       parsed = await res.json();
     } catch (err2) {
+      const jsonErr = err2 instanceof Error ? err2.message : String(err2);
       if (verbose) {
         process.stderr.write(
-          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} non-JSON err=${err2 instanceof Error ? err2.message : String(err2)}
+          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} non-JSON err=${jsonErr}
 `
         );
       }
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        error: { code: "invalid_response", message: `bundler ${method} returned non-JSON: ${jsonErr}` },
+        elapsedMs: Date.now() - startMs
+      });
       throw new BundlerClientError(
         "invalid_response",
-        `bundler ${method} returned non-JSON: ${err2 instanceof Error ? err2.message : String(err2)}`
+        `bundler ${method} returned non-JSON: ${jsonErr}`
       );
     }
+    const respDump = JSON.stringify(parsed);
+    const respBody = truncate(respDump);
     if (verbose) {
-      const respDump = JSON.stringify(parsed);
-      const trunc = respDump.length > 2048 ? respDump.slice(0, 2048) + "\u2026(truncated)" : respDump;
-      process.stderr.write(`[muhaven-mcp] [bundler\u2190] ${method} id=${id} resp=${trunc}
+      process.stderr.write(`[muhaven-mcp] [bundler\u2190] ${method} id=${id} resp=${respBody}
 `);
     }
+    const elapsedMs = Date.now() - startMs;
     if (typeof parsed !== "object" || parsed === null) {
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        responseBody: respBody,
+        error: { code: "invalid_response", message: `bundler ${method} returned non-object` },
+        elapsedMs
+      });
       throw new BundlerClientError(
         "invalid_response",
         `bundler ${method} returned non-object`
@@ -1306,12 +1384,30 @@ var BundlerClient = class {
     const obj = parsed;
     if (obj.error !== void 0 && obj.error !== null) {
       const err2 = obj.error;
+      const errMsg = typeof err2.message === "string" ? err2.message : "<no message>";
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        responseBody: respBody,
+        error: { code: "rpc_error", message: `bundler ${method} rpc error: ${errMsg}` },
+        elapsedMs
+      });
       throw new BundlerClientError(
         "rpc_error",
-        `bundler ${method} rpc error: ${typeof err2.message === "string" ? err2.message : "<no message>"}`,
+        `bundler ${method} rpc error: ${errMsg}`,
         { code: err2.code, message: err2.message, data: err2.data }
       );
     }
+    this.pushTrace({
+      method,
+      id,
+      requestBody,
+      responseStatus: res.status,
+      responseBody: respBody,
+      elapsedMs
+    });
     return obj.result;
   }
 };
@@ -1872,6 +1968,26 @@ function encodeKernelExecuteSingleCall(input) {
     args: [KERNEL_V3_SINGLE_CALL_MODE_DEFAULT, executionCalldata]
   });
 }
+function decodeKernelExecuteSingleCall(data) {
+  let decoded;
+  try {
+    decoded = viem.decodeFunctionData({ abi: KERNEL_EXECUTE_ABI, data });
+  } catch {
+    return null;
+  }
+  const [mode, executionCalldata] = decoded.args;
+  if (mode !== KERNEL_V3_SINGLE_CALL_MODE_DEFAULT) {
+    return null;
+  }
+  const ec = executionCalldata.slice(2);
+  if (ec.length < 20 * 2 + 32 * 2) {
+    return null;
+  }
+  const target = `0x${ec.slice(0, 40)}`;
+  const value = BigInt(`0x${ec.slice(40, 40 + 64)}`);
+  const innerCallData = `0x${ec.slice(40 + 64)}`;
+  return { mode, target, value, innerCallData };
+}
 var ECDSA_SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
 var PERMISSION_USE_PREFIX = "0xff";
 function buildKernelSessionKeySignature(input) {
@@ -2261,11 +2377,85 @@ async function syncSnapshotFromMirror(deps, brokerSignerAddress) {
   }
   return { kind: "ok", sessionId: activeId };
 }
+var PURCHASE_SELECTOR_LOWER = SUBSCRIPTION_PURCHASE_SELECTOR.toLowerCase();
+function buildPathDDecodedCall(trace, deps) {
+  const sponsorEvent = trace.find((e) => e.method === "zd_sponsorUserOperation");
+  if (!sponsorEvent) return void 0;
+  let req;
+  try {
+    req = JSON.parse(sponsorEvent.requestBody);
+  } catch {
+    return void 0;
+  }
+  const userOp = req.params?.[0]?.userOp;
+  if (!userOp || typeof userOp.callData !== "string" || !userOp.callData.startsWith("0x")) {
+    return void 0;
+  }
+  const sender = userOp.sender ?? "<missing>";
+  const decoded = decodeKernelExecuteSingleCall(userOp.callData);
+  if (!decoded) {
+    return {
+      sender,
+      kernelExecuteMode: "<undecodable>",
+      kernelExecuteTarget: "<undecodable>",
+      kernelExecuteValue: "<undecodable>",
+      innerSelector: "<undecodable>",
+      interpretation: "kernel.execute callData could not be decoded as single-call default mode. The mode word is non-zero or the executionCalldata layout is unexpected. Manual decode required."
+    };
+  }
+  const innerSelector = decoded.innerCallData.slice(0, 10).toLowerCase();
+  let innerPurchaseTokenArg;
+  let innerPurchaseMaxSharesHint;
+  let innerPurchaseEphemeralEOA;
+  if (innerSelector === PURCHASE_SELECTOR_LOWER) {
+    try {
+      const inner = viem.decodeFunctionData({
+        abi: SUBSCRIPTION_PURCHASE_ABI,
+        data: decoded.innerCallData
+      });
+      const [tokenArg, , maxSharesHint, ephemeralEOA] = inner.args;
+      innerPurchaseTokenArg = tokenArg;
+      innerPurchaseMaxSharesHint = maxSharesHint.toString();
+      innerPurchaseEphemeralEOA = ephemeralEOA;
+    } catch {
+    }
+  }
+  const expectedSubscriptionAddress = deps.subscriptionAddress?.toLowerCase();
+  const kernelTargetLower = decoded.target.toLowerCase();
+  let kernelExecuteTargetMatchesSubscription;
+  let interpretation;
+  if (expectedSubscriptionAddress === void 0) {
+    interpretation = `kernel.execute target=${decoded.target}; inner purchase token=${innerPurchaseTokenArg ?? "<unknown>"}; MUHAVEN_SUBSCRIPTION_ADDRESS not wired on this MCP server \u2014 cannot cross-check.`;
+  } else if (kernelTargetLower === expectedSubscriptionAddress) {
+    kernelExecuteTargetMatchesSubscription = true;
+    interpretation = `kernel.execute target matches MuHavenSubscription (${decoded.target}). Inner purchase token = ${innerPurchaseTokenArg ?? "<unknown>"}. The shape is correct; the AA23 revert is downstream of the validator's signature decode \u2014 likely either an on-chain signer-vs-installed-permission mismatch, a target/selector not in the on-chain policy, or a cap-arg breach. Check muhaven.policy.session_key_status for the installed permission state.`;
+  } else if (innerPurchaseTokenArg !== void 0 && kernelTargetLower === innerPurchaseTokenArg.toLowerCase()) {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} = the RWA MuHavenToken (purchase.token arg0). Expected MuHavenSubscription (${deps.subscriptionAddress}). The kernel is dispatching purchase() to the token contract instead of the subscription \u2014 token doesn't have a purchase() selector, so fallback returns empty revert data (= AA23 reverted 0x). This is a code-side bug in the kernel.execute target wiring.`;
+  } else {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} \u2014 NEITHER the expected MuHavenSubscription (${deps.subscriptionAddress}) NOR the inner purchase.token arg (${innerPurchaseTokenArg ?? "<none>"}). This is an unexpected third-address dispatch; inspect deps.subscriptionAddress env wiring.`;
+  }
+  return {
+    sender,
+    kernelExecuteMode: decoded.mode,
+    kernelExecuteTarget: decoded.target,
+    kernelExecuteValue: decoded.value.toString(),
+    innerSelector,
+    innerPurchaseTokenArg,
+    innerPurchaseMaxSharesHint,
+    innerPurchaseEphemeralEOA,
+    expectedSubscriptionAddress: deps.subscriptionAddress,
+    kernelExecuteTargetMatchesSubscription,
+    interpretation
+  };
+}
 async function attemptPathD(args, deps) {
   const { shares, tokenAddress, tokenSymbol } = args;
   if (!deps.broker || !deps.bundler) {
     return { kind: "unconfigured" };
   }
+  deps.bundler.drainTrace();
   if (!deps.subscriptionAddress) {
     return {
       kind: "fallback",
@@ -2706,6 +2896,8 @@ async function positionBuy(input, deps) {
   let pathDFallbackReason;
   let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
+  let pathDBundlerTrace;
+  let pathDDecodedCall;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
     deps
@@ -2719,6 +2911,13 @@ async function positionBuy(input, deps) {
     if (pathD.submittedUserOpHash) {
       pathDSubmittedUserOpHash = pathD.submittedUserOpHash;
     }
+    if (deps.bundler) {
+      const trace = deps.bundler.drainTrace();
+      if (trace.length > 0) {
+        pathDBundlerTrace = trace;
+        pathDDecodedCall = buildPathDDecodedCall(trace, deps);
+      }
+    }
   }
   const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "buy", {
     token: token.symbol,
@@ -2742,7 +2941,9 @@ ${dashboardUrl}`,
       navUsd6: navUsd6.toString(),
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
       ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
-      ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {}
+      ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {},
+      ...pathDBundlerTrace ? { pathDBundlerTrace } : {},
+      ...pathDDecodedCall ? { pathDDecodedCall } : {}
     }
   });
 }
@@ -3093,7 +3294,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.7";
+    return "0.2.9";
   }
 }
 function toJsonInputSchema(schema) {

package/dist/index.d.cts

@@ -755,6 +755,43 @@ interface UserOperationReceipt {
         readonly blockHash: `0x${string}`;
     };
 }
+/**
+ * Wave 5 Path D 0.2.8 — single bundler RPC round-trip captured for
+ * downstream diagnostic. Stored in a ring buffer on the client; the
+ * caller (attemptPathD) drains the buffer at each fallback return and
+ * inlines it into the `position.buy` echo's `pathDFallbackDetail`
+ * field. Claude Code's MCP client only captures subprocess stderr at
+ * connection handshake (NOT during tool calls — verified 2026-05-23
+ * via Claude Code's `mcp-logs-muhaven` JSONL files), so the previous
+ * stderr-only verbose path was invisible to operators. Returning the
+ * trace IN the tool response is the diagnostic surface that actually
+ * reaches the LLM context.
+ *
+ * Bodies truncated at 2KB each to keep the echo small + bounded.
+ * Sensitive fields (signatures) are kept since the LLM already sees
+ * the unsigned UserOp shape elsewhere — there's no incremental
+ * disclosure beyond what `pathDFallbackDetail`'s sanitized message
+ * already carries.
+ */
+interface BundlerTraceEvent {
+    /** RPC method (e.g. `eth_call`, `eth_gasPrice`, `zd_sponsorUserOperation`). */
+    readonly method: string;
+    /** Monotonically-incrementing per-client RPC id. */
+    readonly id: number;
+    /** Request body (JSON), truncated. */
+    readonly requestBody: string;
+    /** HTTP status of the response. Undefined for transport-layer failures. */
+    readonly responseStatus?: number;
+    /** Response body (text), truncated. Undefined on transport-layer failures. */
+    readonly responseBody?: string;
+    /** Set when the rpc threw — captures the BundlerClientError code+message. */
+    readonly error?: {
+        code: string;
+        message: string;
+    };
+    /** Wall-clock ms elapsed (request start → response received / failure). */
+    readonly elapsedMs: number;
+}
 interface BundlerClientOptions {
     /** Bundler RPC endpoint — MUHAVEN_BUNDLER_URL. https-or-loopback validated
      *  at config-load time (see `config.ts::validatePublicUrlEnv`). */
@@ -789,7 +826,27 @@ declare class BundlerClient {
     private readonly options;
     private readonly fetchImpl;
     private nextRpcId;
+    /**
+     * Ring buffer of the most recent RPC round-trips. Surfaced via
+     * `drainTrace()` to the caller (attemptPathD) for inline diagnostic
+     * in the position.buy echo. Always populated (no env-gate) — bounded
+     * at 20 events × ~4KB each ≈ 80KB worst-case per client instance.
+     * Cheap enough to keep on for all installs so the next paymaster
+     * gate is self-diagnosing without a second binary spin.
+     */
+    private static readonly TRACE_BUFFER_SIZE;
+    private recentTrace;
     constructor(options: BundlerClientOptions);
+    /**
+     * Return AND CLEAR the in-memory trace ring. attemptPathD calls this
+     * right before constructing a fallback echo so the trace inlined
+     * into the echo corresponds to THAT smoke iteration (subsequent
+     * tool calls start with an empty buffer). Returns a copy so the
+     * caller can safely serialize without races against in-flight
+     * concurrent RPCs.
+     */
+    drainTrace(): readonly BundlerTraceEvent[];
+    private pushTrace;
     /**
      * Submit a signed UserOperation. Returns the userOpHash the bundler
      * computed (which must match the hash the broker signed — caller is

package/dist/index.d.ts

@@ -755,6 +755,43 @@ interface UserOperationReceipt {
         readonly blockHash: `0x${string}`;
     };
 }
+/**
+ * Wave 5 Path D 0.2.8 — single bundler RPC round-trip captured for
+ * downstream diagnostic. Stored in a ring buffer on the client; the
+ * caller (attemptPathD) drains the buffer at each fallback return and
+ * inlines it into the `position.buy` echo's `pathDFallbackDetail`
+ * field. Claude Code's MCP client only captures subprocess stderr at
+ * connection handshake (NOT during tool calls — verified 2026-05-23
+ * via Claude Code's `mcp-logs-muhaven` JSONL files), so the previous
+ * stderr-only verbose path was invisible to operators. Returning the
+ * trace IN the tool response is the diagnostic surface that actually
+ * reaches the LLM context.
+ *
+ * Bodies truncated at 2KB each to keep the echo small + bounded.
+ * Sensitive fields (signatures) are kept since the LLM already sees
+ * the unsigned UserOp shape elsewhere — there's no incremental
+ * disclosure beyond what `pathDFallbackDetail`'s sanitized message
+ * already carries.
+ */
+interface BundlerTraceEvent {
+    /** RPC method (e.g. `eth_call`, `eth_gasPrice`, `zd_sponsorUserOperation`). */
+    readonly method: string;
+    /** Monotonically-incrementing per-client RPC id. */
+    readonly id: number;
+    /** Request body (JSON), truncated. */
+    readonly requestBody: string;
+    /** HTTP status of the response. Undefined for transport-layer failures. */
+    readonly responseStatus?: number;
+    /** Response body (text), truncated. Undefined on transport-layer failures. */
+    readonly responseBody?: string;
+    /** Set when the rpc threw — captures the BundlerClientError code+message. */
+    readonly error?: {
+        code: string;
+        message: string;
+    };
+    /** Wall-clock ms elapsed (request start → response received / failure). */
+    readonly elapsedMs: number;
+}
 interface BundlerClientOptions {
     /** Bundler RPC endpoint — MUHAVEN_BUNDLER_URL. https-or-loopback validated
      *  at config-load time (see `config.ts::validatePublicUrlEnv`). */
@@ -789,7 +826,27 @@ declare class BundlerClient {
     private readonly options;
     private readonly fetchImpl;
     private nextRpcId;
+    /**
+     * Ring buffer of the most recent RPC round-trips. Surfaced via
+     * `drainTrace()` to the caller (attemptPathD) for inline diagnostic
+     * in the position.buy echo. Always populated (no env-gate) — bounded
+     * at 20 events × ~4KB each ≈ 80KB worst-case per client instance.
+     * Cheap enough to keep on for all installs so the next paymaster
+     * gate is self-diagnosing without a second binary spin.
+     */
+    private static readonly TRACE_BUFFER_SIZE;
+    private recentTrace;
     constructor(options: BundlerClientOptions);
+    /**
+     * Return AND CLEAR the in-memory trace ring. attemptPathD calls this
+     * right before constructing a fallback echo so the trace inlined
+     * into the echo corresponds to THAT smoke iteration (subsequent
+     * tool calls start with an empty buffer). Returns a copy so the
+     * caller can safely serialize without races against in-flight
+     * concurrent RPCs.
+     */
+    drainTrace(): readonly BundlerTraceEvent[];
+    private pushTrace;
     /**
      * Submit a signed UserOperation. Returns the userOpHash the bundler
      * computed (which must match the hash the broker signed — caller is

package/dist/index.js

@@ -10,7 +10,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { platform, homedir } from 'os';
 import { connect, createServer } from 'net';
 import { setTimeout as setTimeout$1 } from 'timers/promises';
-import { parseAbi, toFunctionSelector, encodeFunctionData, encodePacked, pad, concatHex, decodeAbiParameters } from 'viem';
+import { parseAbi, toFunctionSelector, encodeFunctionData, decodeFunctionData, encodePacked, pad, concatHex, decodeAbiParameters } from 'viem';
 import { createHash, randomBytes } from 'crypto';
 import { getUserOperationHash } from 'viem/account-abstraction';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -995,7 +995,7 @@ var BundlerClientError = class extends Error {
   code;
   detail;
 };
-var BundlerClient = class {
+var BundlerClient = class _BundlerClient {
   constructor(options) {
     this.options = options;
     this.fetchImpl = options.fetchImpl ?? globalThis.fetch.bind(globalThis);
@@ -1003,6 +1003,35 @@ var BundlerClient = class {
   options;
   fetchImpl;
   nextRpcId = 1;
+  /**
+   * Ring buffer of the most recent RPC round-trips. Surfaced via
+   * `drainTrace()` to the caller (attemptPathD) for inline diagnostic
+   * in the position.buy echo. Always populated (no env-gate) — bounded
+   * at 20 events × ~4KB each ≈ 80KB worst-case per client instance.
+   * Cheap enough to keep on for all installs so the next paymaster
+   * gate is self-diagnosing without a second binary spin.
+   */
+  static TRACE_BUFFER_SIZE = 20;
+  recentTrace = [];
+  /**
+   * Return AND CLEAR the in-memory trace ring. attemptPathD calls this
+   * right before constructing a fallback echo so the trace inlined
+   * into the echo corresponds to THAT smoke iteration (subsequent
+   * tool calls start with an empty buffer). Returns a copy so the
+   * caller can safely serialize without races against in-flight
+   * concurrent RPCs.
+   */
+  drainTrace() {
+    const snapshot = this.recentTrace.slice();
+    this.recentTrace = [];
+    return snapshot;
+  }
+  pushTrace(event) {
+    this.recentTrace.push(event);
+    if (this.recentTrace.length > _BundlerClient.TRACE_BUFFER_SIZE) {
+      this.recentTrace.shift();
+    }
+  }
   /**
    * Submit a signed UserOperation. Returns the userOpHash the bundler
    * computed (which must match the hash the broker signed — caller is
@@ -1208,10 +1237,12 @@ var BundlerClient = class {
     const id = this.nextRpcId++;
     const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
     const verbose = process.env.MUHAVEN_MCP_VERBOSE === "1";
+    const truncate = (s) => s.length > 2048 ? s.slice(0, 2048) + "\u2026(truncated)" : s;
+    const requestBody = truncate(body);
+    const startMs = Date.now();
     if (verbose) {
-      const bodyDump = body.length > 2048 ? body.slice(0, 2048) + "\u2026(truncated)" : body;
       process.stderr.write(
-        `[muhaven-mcp] [bundler\u2192] ${method} id=${id} body=${bodyDump}
+        `[muhaven-mcp] [bundler\u2192] ${method} id=${id} body=${requestBody}
 `
       );
     }
@@ -1234,22 +1265,38 @@ var BundlerClient = class {
       });
     } catch (err2) {
       clearTimeout(timer);
+      const elapsedMs2 = Date.now() - startMs;
       if (err2.name === "AbortError") {
         if (verbose) {
           process.stderr.write(`[muhaven-mcp] [bundler\u2717] ${method} id=${id} timeout
 `);
         }
+        this.pushTrace({
+          method,
+          id,
+          requestBody,
+          error: { code: "timeout", message: `bundler ${method} timed out` },
+          elapsedMs: elapsedMs2
+        });
         throw new BundlerClientError("timeout", `bundler ${method} timed out`);
       }
+      const netMsg = err2 instanceof Error ? err2.message : String(err2);
       if (verbose) {
         process.stderr.write(
-          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} network err=${err2 instanceof Error ? err2.message : String(err2)}
+          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} network err=${netMsg}
 `
         );
       }
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        error: { code: "network", message: `bundler ${method} network error: ${netMsg}` },
+        elapsedMs: elapsedMs2
+      });
       throw new BundlerClientError(
         "network",
-        `bundler ${method} network error: ${err2 instanceof Error ? err2.message : String(err2)}`,
+        `bundler ${method} network error: ${netMsg}`,
         err2
       );
     } finally {
@@ -1267,6 +1314,18 @@ var BundlerClient = class {
 `
         );
       }
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        responseBody: text,
+        error: {
+          code: "http_error",
+          message: `bundler ${method} \u2192 HTTP ${res.status}: ${text}`
+        },
+        elapsedMs: Date.now() - startMs
+      });
       throw new BundlerClientError(
         "http_error",
         `bundler ${method} \u2192 HTTP ${res.status}: ${text}`
@@ -1276,24 +1335,43 @@ var BundlerClient = class {
     try {
       parsed = await res.json();
     } catch (err2) {
+      const jsonErr = err2 instanceof Error ? err2.message : String(err2);
       if (verbose) {
         process.stderr.write(
-          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} non-JSON err=${err2 instanceof Error ? err2.message : String(err2)}
+          `[muhaven-mcp] [bundler\u2717] ${method} id=${id} non-JSON err=${jsonErr}
 `
         );
       }
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        error: { code: "invalid_response", message: `bundler ${method} returned non-JSON: ${jsonErr}` },
+        elapsedMs: Date.now() - startMs
+      });
       throw new BundlerClientError(
         "invalid_response",
-        `bundler ${method} returned non-JSON: ${err2 instanceof Error ? err2.message : String(err2)}`
+        `bundler ${method} returned non-JSON: ${jsonErr}`
       );
     }
+    const respDump = JSON.stringify(parsed);
+    const respBody = truncate(respDump);
     if (verbose) {
-      const respDump = JSON.stringify(parsed);
-      const trunc = respDump.length > 2048 ? respDump.slice(0, 2048) + "\u2026(truncated)" : respDump;
-      process.stderr.write(`[muhaven-mcp] [bundler\u2190] ${method} id=${id} resp=${trunc}
+      process.stderr.write(`[muhaven-mcp] [bundler\u2190] ${method} id=${id} resp=${respBody}
 `);
     }
+    const elapsedMs = Date.now() - startMs;
     if (typeof parsed !== "object" || parsed === null) {
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        responseBody: respBody,
+        error: { code: "invalid_response", message: `bundler ${method} returned non-object` },
+        elapsedMs
+      });
       throw new BundlerClientError(
         "invalid_response",
         `bundler ${method} returned non-object`
@@ -1302,12 +1380,30 @@ var BundlerClient = class {
     const obj = parsed;
     if (obj.error !== void 0 && obj.error !== null) {
       const err2 = obj.error;
+      const errMsg = typeof err2.message === "string" ? err2.message : "<no message>";
+      this.pushTrace({
+        method,
+        id,
+        requestBody,
+        responseStatus: res.status,
+        responseBody: respBody,
+        error: { code: "rpc_error", message: `bundler ${method} rpc error: ${errMsg}` },
+        elapsedMs
+      });
       throw new BundlerClientError(
         "rpc_error",
-        `bundler ${method} rpc error: ${typeof err2.message === "string" ? err2.message : "<no message>"}`,
+        `bundler ${method} rpc error: ${errMsg}`,
         { code: err2.code, message: err2.message, data: err2.data }
       );
     }
+    this.pushTrace({
+      method,
+      id,
+      requestBody,
+      responseStatus: res.status,
+      responseBody: respBody,
+      elapsedMs
+    });
     return obj.result;
   }
 };
@@ -1868,6 +1964,26 @@ function encodeKernelExecuteSingleCall(input) {
     args: [KERNEL_V3_SINGLE_CALL_MODE_DEFAULT, executionCalldata]
   });
 }
+function decodeKernelExecuteSingleCall(data) {
+  let decoded;
+  try {
+    decoded = decodeFunctionData({ abi: KERNEL_EXECUTE_ABI, data });
+  } catch {
+    return null;
+  }
+  const [mode, executionCalldata] = decoded.args;
+  if (mode !== KERNEL_V3_SINGLE_CALL_MODE_DEFAULT) {
+    return null;
+  }
+  const ec = executionCalldata.slice(2);
+  if (ec.length < 20 * 2 + 32 * 2) {
+    return null;
+  }
+  const target = `0x${ec.slice(0, 40)}`;
+  const value = BigInt(`0x${ec.slice(40, 40 + 64)}`);
+  const innerCallData = `0x${ec.slice(40 + 64)}`;
+  return { mode, target, value, innerCallData };
+}
 var ECDSA_SIG_HEX_RE = /^0x[0-9a-fA-F]{130}$/;
 var PERMISSION_USE_PREFIX = "0xff";
 function buildKernelSessionKeySignature(input) {
@@ -2257,11 +2373,85 @@ async function syncSnapshotFromMirror(deps, brokerSignerAddress) {
   }
   return { kind: "ok", sessionId: activeId };
 }
+var PURCHASE_SELECTOR_LOWER = SUBSCRIPTION_PURCHASE_SELECTOR.toLowerCase();
+function buildPathDDecodedCall(trace, deps) {
+  const sponsorEvent = trace.find((e) => e.method === "zd_sponsorUserOperation");
+  if (!sponsorEvent) return void 0;
+  let req;
+  try {
+    req = JSON.parse(sponsorEvent.requestBody);
+  } catch {
+    return void 0;
+  }
+  const userOp = req.params?.[0]?.userOp;
+  if (!userOp || typeof userOp.callData !== "string" || !userOp.callData.startsWith("0x")) {
+    return void 0;
+  }
+  const sender = userOp.sender ?? "<missing>";
+  const decoded = decodeKernelExecuteSingleCall(userOp.callData);
+  if (!decoded) {
+    return {
+      sender,
+      kernelExecuteMode: "<undecodable>",
+      kernelExecuteTarget: "<undecodable>",
+      kernelExecuteValue: "<undecodable>",
+      innerSelector: "<undecodable>",
+      interpretation: "kernel.execute callData could not be decoded as single-call default mode. The mode word is non-zero or the executionCalldata layout is unexpected. Manual decode required."
+    };
+  }
+  const innerSelector = decoded.innerCallData.slice(0, 10).toLowerCase();
+  let innerPurchaseTokenArg;
+  let innerPurchaseMaxSharesHint;
+  let innerPurchaseEphemeralEOA;
+  if (innerSelector === PURCHASE_SELECTOR_LOWER) {
+    try {
+      const inner = decodeFunctionData({
+        abi: SUBSCRIPTION_PURCHASE_ABI,
+        data: decoded.innerCallData
+      });
+      const [tokenArg, , maxSharesHint, ephemeralEOA] = inner.args;
+      innerPurchaseTokenArg = tokenArg;
+      innerPurchaseMaxSharesHint = maxSharesHint.toString();
+      innerPurchaseEphemeralEOA = ephemeralEOA;
+    } catch {
+    }
+  }
+  const expectedSubscriptionAddress = deps.subscriptionAddress?.toLowerCase();
+  const kernelTargetLower = decoded.target.toLowerCase();
+  let kernelExecuteTargetMatchesSubscription;
+  let interpretation;
+  if (expectedSubscriptionAddress === void 0) {
+    interpretation = `kernel.execute target=${decoded.target}; inner purchase token=${innerPurchaseTokenArg ?? "<unknown>"}; MUHAVEN_SUBSCRIPTION_ADDRESS not wired on this MCP server \u2014 cannot cross-check.`;
+  } else if (kernelTargetLower === expectedSubscriptionAddress) {
+    kernelExecuteTargetMatchesSubscription = true;
+    interpretation = `kernel.execute target matches MuHavenSubscription (${decoded.target}). Inner purchase token = ${innerPurchaseTokenArg ?? "<unknown>"}. The shape is correct; the AA23 revert is downstream of the validator's signature decode \u2014 likely either an on-chain signer-vs-installed-permission mismatch, a target/selector not in the on-chain policy, or a cap-arg breach. Check muhaven.policy.session_key_status for the installed permission state.`;
+  } else if (innerPurchaseTokenArg !== void 0 && kernelTargetLower === innerPurchaseTokenArg.toLowerCase()) {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} = the RWA MuHavenToken (purchase.token arg0). Expected MuHavenSubscription (${deps.subscriptionAddress}). The kernel is dispatching purchase() to the token contract instead of the subscription \u2014 token doesn't have a purchase() selector, so fallback returns empty revert data (= AA23 reverted 0x). This is a code-side bug in the kernel.execute target wiring.`;
+  } else {
+    kernelExecuteTargetMatchesSubscription = false;
+    interpretation = `kernel.execute target = ${decoded.target} \u2014 NEITHER the expected MuHavenSubscription (${deps.subscriptionAddress}) NOR the inner purchase.token arg (${innerPurchaseTokenArg ?? "<none>"}). This is an unexpected third-address dispatch; inspect deps.subscriptionAddress env wiring.`;
+  }
+  return {
+    sender,
+    kernelExecuteMode: decoded.mode,
+    kernelExecuteTarget: decoded.target,
+    kernelExecuteValue: decoded.value.toString(),
+    innerSelector,
+    innerPurchaseTokenArg,
+    innerPurchaseMaxSharesHint,
+    innerPurchaseEphemeralEOA,
+    expectedSubscriptionAddress: deps.subscriptionAddress,
+    kernelExecuteTargetMatchesSubscription,
+    interpretation
+  };
+}
 async function attemptPathD(args, deps) {
   const { shares, tokenAddress, tokenSymbol } = args;
   if (!deps.broker || !deps.bundler) {
     return { kind: "unconfigured" };
   }
+  deps.bundler.drainTrace();
   if (!deps.subscriptionAddress) {
     return {
       kind: "fallback",
@@ -2702,6 +2892,8 @@ async function positionBuy(input, deps) {
   let pathDFallbackReason;
   let pathDFallbackDetail;
   let pathDSubmittedUserOpHash;
+  let pathDBundlerTrace;
+  let pathDDecodedCall;
   const pathD = await attemptPathD(
     { shares, tokenAddress: token.address, tokenSymbol: token.symbol },
     deps
@@ -2715,6 +2907,13 @@ async function positionBuy(input, deps) {
     if (pathD.submittedUserOpHash) {
       pathDSubmittedUserOpHash = pathD.submittedUserOpHash;
     }
+    if (deps.bundler) {
+      const trace = deps.bundler.drainTrace();
+      if (trace.length > 0) {
+        pathDBundlerTrace = trace;
+        pathDDecodedCall = buildPathDDecodedCall(trace, deps);
+      }
+    }
   }
   const dashboardUrl = buildPositionDeeplink(resolveDashboardBaseUrl(deps), "buy", {
     token: token.symbol,
@@ -2738,7 +2937,9 @@ ${dashboardUrl}`,
       navUsd6: navUsd6.toString(),
       ...pathDFallbackReason ? { pathDFallbackReason } : {},
       ...pathDFallbackDetail ? { pathDFallbackDetail } : {},
-      ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {}
+      ...pathDSubmittedUserOpHash ? { pathDSubmittedUserOpHash } : {},
+      ...pathDBundlerTrace ? { pathDBundlerTrace } : {},
+      ...pathDDecodedCall ? { pathDDecodedCall } : {}
     }
   });
 }
@@ -3089,7 +3290,7 @@ var SERVER_NAME = "@muhaven/mcp";
 var SERVER_VERSION = resolveServerVersion();
 function resolveServerVersion() {
   {
-    return "0.2.7";
+    return "0.2.9";
   }
 }
 function toJsonInputSchema(schema) {

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.2",
   "name": "muhaven-mcp",
   "display_name": "MuHaven (RWA portfolio)",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Confidential RWA portfolio management on Fhenix CoFHE. Read your encrypted balances, propose yield claims and policy changes — all signing happens in a sibling broker daemon, the LLM never sees your private key.",
   "long_description": "MuHaven MCP exposes 24 tools across read.* / position.* / policy.* / issuer.* / governance.* groups for managing real-world asset (RWA) tokens with FHE-encrypted balances. Authentication uses a one-time device-code ceremony (run `muhaven-broker login`); subsequent tool calls fetch the JWT from the broker over a Unix socket. Position / governance tools deep-link to the dashboard for passkey signing — they NEVER auto-submit to a bundler. The companion `muhaven-broker` daemon must be running before tools can be invoked. See README for setup.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhaven/mcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "MuHaven MCP server — read/position/policy toolsets bridging Claude Desktop / Cursor / Claude Code to the MuHaven backend, with a sibling muhaven-broker daemon holding the session-key private half over a local IPC socket",
   "type": "module",
   "repository": {