@haven_ai/mcp 0.2.1-alpha.0 → 0.4.0-alpha.0

package/dist/index.d.cts

@@ -6,20 +6,8 @@ interface HavenCredentialFile {
     apiKey: string;
     delegateKey: string;
     agentId?: string;
-    /**
-     * The Haven account (smart account) the agent spends from — #2908, the
-     * account-vocabulary name, added EXPLICITLY here (this shape and the
-     * signer's are separate types; the epic's review found they must not be
-     * assumed to match). Same value as `safeAddress`.
-     */
+    /** The Haven account (smart account) the agent spends from. */
     accountAddress?: string;
-    /**
-     * @deprecated #2908 — same value as {@link HavenCredentialFile.accountAddress}.
-     * Removed from this shape in the release after the one carrying #2908
-     * (#2914). The credential-FILE keys are read permanently — see
-     * `readAccountAddressField`.
-     */
-    safeAddress?: string;
     delegateAddress?: string;
     chainId?: number;
     network?: string;
@@ -55,9 +43,9 @@ interface HavenCredentialSource {
  *   1. Explicit `path` argument (typically from `--credentials <path>`).
  *   2. `HAVEN_CREDENTIALS` env var pointing at a credential JSON file.
  *   3. Inline env vars: `HAVEN_API_KEY` + `HAVEN_DELEGATE_KEY` (+ optional
- *      `HAVEN_AGENT_ID`, `HAVEN_ACCOUNT_ADDRESS` — or, until #2914, its
- *      pre-#2908 spellings `HAVEN_WALLET_ADDRESS` / `HAVEN_SAFE_ADDRESS` —
- *      and `HAVEN_API_URL`).
+ *      `HAVEN_AGENT_ID`, `HAVEN_ACCOUNT_ADDRESS` and `HAVEN_API_URL`). The
+ *      pre-#2908 spellings `HAVEN_WALLET_ADDRESS` / `HAVEN_SAFE_ADDRESS` are
+ *      retired as of #2914.
  *
  * The inline-env path exists so that runtime config snippets emitted by the
  * Haven dashboard (Claude Desktop / Cursor / generic MCP configs) can be a
@@ -79,7 +67,79 @@ declare function loadCredentials(source?: string | HavenCredentialSource | undef
  */
 
 type HavenMcpToolName = 'haven_send' | 'haven_pay_mcp_tool' | 'haven_quote_x402' | 'haven_pay_x402_quote' | 'haven_pay_x402' | 'haven_resume_x402_payment' | 'haven_get_payment_status' | 'haven_get_resume_state' | 'haven_get_agent' | 'haven_get_allowances' | 'haven_list_receipts' | 'haven_verify_receipt' | 'haven_sweep_delegate' | 'haven_discover_tools' | 'haven_submit_catalog_entry';
-declare const toolSchemas: Record<HavenMcpToolName, z.ZodRawShape>;
+declare const toolSchemas: {
+    readonly haven_send: {
+        readonly asset: z.ZodEnum<["ETH", "USDC"]>;
+        readonly recipient: z.ZodString;
+        readonly amount: z.ZodString;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_pay_mcp_tool: {
+        readonly merchant_url: z.ZodString;
+        readonly tool_name: z.ZodString;
+        readonly arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_quote_x402: {
+        readonly url: z.ZodString;
+        readonly method: z.ZodOptional<z.ZodString>;
+        readonly headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        readonly body: z.ZodOptional<z.ZodString>;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_pay_x402_quote: {
+        readonly quote: z.ZodUnknown;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_pay_x402: {
+        readonly url: z.ZodString;
+        readonly method: z.ZodOptional<z.ZodString>;
+        readonly headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        readonly body: z.ZodOptional<z.ZodString>;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_resume_x402_payment: {
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly resume_state: z.ZodOptional<z.ZodUnknown>;
+    };
+    readonly haven_get_payment_status: {
+        readonly payment_id: z.ZodString;
+    };
+    readonly haven_get_resume_state: {
+        readonly payment_id: z.ZodString;
+    };
+    readonly haven_get_agent: {};
+    readonly haven_get_allowances: {};
+    readonly haven_sweep_delegate: {};
+    readonly haven_discover_tools: {
+        readonly category: z.ZodOptional<z.ZodString>;
+        readonly search: z.ZodOptional<z.ZodString>;
+        readonly rail: z.ZodOptional<z.ZodEnum<["x402", "mpp"]>>;
+        readonly verified: z.ZodOptional<z.ZodEnum<["any", "verified", "operator"]>>;
+    };
+    readonly haven_submit_catalog_entry: {
+        readonly resource_url: z.ZodString;
+        readonly website: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_list_receipts: {
+        readonly limit: z.ZodOptional<z.ZodNumber>;
+        /** #3128: the previous page's next_cursor (a receipt id). */
+        readonly cursor: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_verify_receipt: {
+        readonly receipt: z.ZodUnknown;
+    };
+};
 /**
  * MCP tool descriptions, composed from the shared semantic source in
  * `@haven_ai/sdk`'s `tool-descriptions.ts`. Keeping both the SDK tool-calling
@@ -110,7 +170,25 @@ interface ToolFailure {
     paymentId?: string;
     status?: string;
     phase?: string;
+    /**
+     * @deprecated since #3103 — read `next_action`. Kept with the same value for
+     * one release (the #2908 pattern) and removed in the release after the one
+     * carrying #3103.
+     */
     nextAction?: string;
+    /**
+     * #3103 (epic #3105, decision 10): the same value as `nextAction`, spelled
+     * the way the hosted server and the signer spell it. Dual-emitted for one
+     * release (the #2908 pattern) before `nextAction` is dropped.
+     */
+    next_action?: string;
+    /** #3101 (epic #3105, decision 7): the typed next-step family, additive; `next_tool` never null. */
+    next_tool?: string;
+    next_tool_server?: string;
+    next_tool_name?: string;
+    next_tool_server_role?: 'hosted' | 'signer';
+    next_arguments?: Record<string, unknown>;
+    next_tool_omitted_reason?: string;
     resume_state?: unknown;
     body?: unknown;
     /**
@@ -162,7 +240,7 @@ interface ConsentInput {
     /** Agent identity from the credential file, when present. */
     agentId?: string;
     /** Haven wallet (Safe) the agent spends from. */
-    safeAddress?: string;
+    accountAddress?: string;
     /** Agent's delegate EOA — the local signer. */
     delegateAddress?: string;
     /** Chain the agent operates on. */
@@ -202,8 +280,8 @@ interface CredentialIdentitySeed {
     apiKey: string;
     apiUrl?: string;
     agentId?: string;
-    /** Safe address from the credential file, used as a fallback. */
-    safeAddress?: string;
+    /** Account address from the credential file, used as a fallback. */
+    accountAddress?: string;
     /** Delegate address from the credential file, used before live allowance metadata is available. */
     delegateAddress?: string;
     /** Chain from the credential file, used as a fallback. */
@@ -267,7 +345,7 @@ declare function createHavenMcpServer(options?: HavenMcpServerOptions): Promise<
  * `agent_tool_invocations` rows are always attributed to the right tool.
  */
 declare const MCP_NAME = "@haven_ai/mcp";
-declare const MCP_VERSION = "0.2.1-alpha.0";
+declare const MCP_VERSION = "0.4.0-alpha.0";
 /**
  * Refuse to start on an unsupported Node (#1161).
  *

package/dist/index.d.ts

@@ -6,20 +6,8 @@ interface HavenCredentialFile {
     apiKey: string;
     delegateKey: string;
     agentId?: string;
-    /**
-     * The Haven account (smart account) the agent spends from — #2908, the
-     * account-vocabulary name, added EXPLICITLY here (this shape and the
-     * signer's are separate types; the epic's review found they must not be
-     * assumed to match). Same value as `safeAddress`.
-     */
+    /** The Haven account (smart account) the agent spends from. */
     accountAddress?: string;
-    /**
-     * @deprecated #2908 — same value as {@link HavenCredentialFile.accountAddress}.
-     * Removed from this shape in the release after the one carrying #2908
-     * (#2914). The credential-FILE keys are read permanently — see
-     * `readAccountAddressField`.
-     */
-    safeAddress?: string;
     delegateAddress?: string;
     chainId?: number;
     network?: string;
@@ -55,9 +43,9 @@ interface HavenCredentialSource {
  *   1. Explicit `path` argument (typically from `--credentials <path>`).
  *   2. `HAVEN_CREDENTIALS` env var pointing at a credential JSON file.
  *   3. Inline env vars: `HAVEN_API_KEY` + `HAVEN_DELEGATE_KEY` (+ optional
- *      `HAVEN_AGENT_ID`, `HAVEN_ACCOUNT_ADDRESS` — or, until #2914, its
- *      pre-#2908 spellings `HAVEN_WALLET_ADDRESS` / `HAVEN_SAFE_ADDRESS` —
- *      and `HAVEN_API_URL`).
+ *      `HAVEN_AGENT_ID`, `HAVEN_ACCOUNT_ADDRESS` and `HAVEN_API_URL`). The
+ *      pre-#2908 spellings `HAVEN_WALLET_ADDRESS` / `HAVEN_SAFE_ADDRESS` are
+ *      retired as of #2914.
  *
  * The inline-env path exists so that runtime config snippets emitted by the
  * Haven dashboard (Claude Desktop / Cursor / generic MCP configs) can be a
@@ -79,7 +67,79 @@ declare function loadCredentials(source?: string | HavenCredentialSource | undef
  */
 
 type HavenMcpToolName = 'haven_send' | 'haven_pay_mcp_tool' | 'haven_quote_x402' | 'haven_pay_x402_quote' | 'haven_pay_x402' | 'haven_resume_x402_payment' | 'haven_get_payment_status' | 'haven_get_resume_state' | 'haven_get_agent' | 'haven_get_allowances' | 'haven_list_receipts' | 'haven_verify_receipt' | 'haven_sweep_delegate' | 'haven_discover_tools' | 'haven_submit_catalog_entry';
-declare const toolSchemas: Record<HavenMcpToolName, z.ZodRawShape>;
+declare const toolSchemas: {
+    readonly haven_send: {
+        readonly asset: z.ZodEnum<["ETH", "USDC"]>;
+        readonly recipient: z.ZodString;
+        readonly amount: z.ZodString;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_pay_mcp_tool: {
+        readonly merchant_url: z.ZodString;
+        readonly tool_name: z.ZodString;
+        readonly arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_quote_x402: {
+        readonly url: z.ZodString;
+        readonly method: z.ZodOptional<z.ZodString>;
+        readonly headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        readonly body: z.ZodOptional<z.ZodString>;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_pay_x402_quote: {
+        readonly quote: z.ZodUnknown;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_pay_x402: {
+        readonly url: z.ZodString;
+        readonly method: z.ZodOptional<z.ZodString>;
+        readonly headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        readonly body: z.ZodOptional<z.ZodString>;
+        readonly idempotency_key: z.ZodOptional<z.ZodString>;
+        /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
+        readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_resume_x402_payment: {
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly resume_state: z.ZodOptional<z.ZodUnknown>;
+    };
+    readonly haven_get_payment_status: {
+        readonly payment_id: z.ZodString;
+    };
+    readonly haven_get_resume_state: {
+        readonly payment_id: z.ZodString;
+    };
+    readonly haven_get_agent: {};
+    readonly haven_get_allowances: {};
+    readonly haven_sweep_delegate: {};
+    readonly haven_discover_tools: {
+        readonly category: z.ZodOptional<z.ZodString>;
+        readonly search: z.ZodOptional<z.ZodString>;
+        readonly rail: z.ZodOptional<z.ZodEnum<["x402", "mpp"]>>;
+        readonly verified: z.ZodOptional<z.ZodEnum<["any", "verified", "operator"]>>;
+    };
+    readonly haven_submit_catalog_entry: {
+        readonly resource_url: z.ZodString;
+        readonly website: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_list_receipts: {
+        readonly limit: z.ZodOptional<z.ZodNumber>;
+        /** #3128: the previous page's next_cursor (a receipt id). */
+        readonly cursor: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_verify_receipt: {
+        readonly receipt: z.ZodUnknown;
+    };
+};
 /**
  * MCP tool descriptions, composed from the shared semantic source in
  * `@haven_ai/sdk`'s `tool-descriptions.ts`. Keeping both the SDK tool-calling
@@ -110,7 +170,25 @@ interface ToolFailure {
     paymentId?: string;
     status?: string;
     phase?: string;
+    /**
+     * @deprecated since #3103 — read `next_action`. Kept with the same value for
+     * one release (the #2908 pattern) and removed in the release after the one
+     * carrying #3103.
+     */
     nextAction?: string;
+    /**
+     * #3103 (epic #3105, decision 10): the same value as `nextAction`, spelled
+     * the way the hosted server and the signer spell it. Dual-emitted for one
+     * release (the #2908 pattern) before `nextAction` is dropped.
+     */
+    next_action?: string;
+    /** #3101 (epic #3105, decision 7): the typed next-step family, additive; `next_tool` never null. */
+    next_tool?: string;
+    next_tool_server?: string;
+    next_tool_name?: string;
+    next_tool_server_role?: 'hosted' | 'signer';
+    next_arguments?: Record<string, unknown>;
+    next_tool_omitted_reason?: string;
     resume_state?: unknown;
     body?: unknown;
     /**
@@ -162,7 +240,7 @@ interface ConsentInput {
     /** Agent identity from the credential file, when present. */
     agentId?: string;
     /** Haven wallet (Safe) the agent spends from. */
-    safeAddress?: string;
+    accountAddress?: string;
     /** Agent's delegate EOA — the local signer. */
     delegateAddress?: string;
     /** Chain the agent operates on. */
@@ -202,8 +280,8 @@ interface CredentialIdentitySeed {
     apiKey: string;
     apiUrl?: string;
     agentId?: string;
-    /** Safe address from the credential file, used as a fallback. */
-    safeAddress?: string;
+    /** Account address from the credential file, used as a fallback. */
+    accountAddress?: string;
     /** Delegate address from the credential file, used before live allowance metadata is available. */
     delegateAddress?: string;
     /** Chain from the credential file, used as a fallback. */
@@ -267,7 +345,7 @@ declare function createHavenMcpServer(options?: HavenMcpServerOptions): Promise<
  * `agent_tool_invocations` rows are always attributed to the right tool.
  */
 declare const MCP_NAME = "@haven_ai/mcp";
-declare const MCP_VERSION = "0.2.1-alpha.0";
+declare const MCP_VERSION = "0.4.0-alpha.0";
 /**
  * Refuse to start on an unsupported Node (#1161).
  *

package/dist/index.js

@@ -54,7 +54,6 @@ async function loadCredentialsFromFile(path) {
     delegateKey,
     agentId: stringField(raw.agent_id ?? raw.agentId),
     accountAddress,
-    safeAddress: accountAddress,
     delegateAddress: stringField(raw.delegate_address ?? raw.delegateAddress),
     chainId: numberField(raw.chain_id ?? raw.chainId),
     network: stringField(raw.network),
@@ -84,13 +83,11 @@ async function loadCredentialsFromSplitFiles(identityPath, signerPath) {
       identity.agent_id ?? identity.agentId,
       signer.agent_id ?? signer.agentId
     ),
-    ...accountAddressTwins(
-      matchingStringField(
-        "account_address",
-        readAccountAddressField(identity),
-        readAccountAddressField(signer),
-        { caseInsensitive: true }
-      )
+    accountAddress: matchingStringField(
+      "account_address",
+      readAccountAddressField(identity),
+      readAccountAddressField(signer),
+      { caseInsensitive: true }
     ),
     delegateAddress: matchingStringField(
       "delegate_address",
@@ -145,7 +142,7 @@ function loadCredentialsFromEnv() {
     apiKey,
     delegateKey,
     agentId: stringField(process.env.HAVEN_AGENT_ID),
-    ...accountAddressTwins(readAccountAddressEnv(process.env)),
+    accountAddress: readAccountAddressEnv(process.env),
     chainId: numberField(process.env.HAVEN_CHAIN_ID),
     network: stringField(process.env.HAVEN_NETWORK),
     apiUrl: stringField(process.env.HAVEN_API_URL)
@@ -155,10 +152,22 @@ function readAccountAddressField(raw) {
   return stringField(raw.account_address ?? raw.safe_address ?? raw.safeAddress);
 }
 function readAccountAddressEnv(env) {
-  return stringField(env.HAVEN_ACCOUNT_ADDRESS ?? env.HAVEN_WALLET_ADDRESS ?? env.HAVEN_SAFE_ADDRESS);
-}
-function accountAddressTwins(address) {
-  return { accountAddress: address, safeAddress: address };
+  const current = stringField(env.HAVEN_ACCOUNT_ADDRESS);
+  for (const name of ["HAVEN_WALLET_ADDRESS", "HAVEN_SAFE_ADDRESS"]) {
+    const retired = stringField(env[name]);
+    if (!retired) continue;
+    if (!current) {
+      throw new Error(
+        `${name} is retired (#2906) \u2014 Haven accounts are addressed as accounts, not Safes. Set HAVEN_ACCOUNT_ADDRESS to the same value. Refusing rather than ignoring it, because an unset account address silently skips the sweep-destination check.`
+      );
+    }
+    if (retired.toLowerCase() !== current.toLowerCase()) {
+      throw new Error(
+        `${name} and HAVEN_ACCOUNT_ADDRESS were both set to different addresses. Remove the retired name, or make them match \u2014 picking one silently would hide the mismatch.`
+      );
+    }
+  }
+  return current;
 }
 function stringField(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
@@ -293,11 +302,14 @@ var toolSchemas = {
     website: z.string().optional()
   },
   haven_list_receipts: {
-    limit: z.number().int().min(1).max(100).optional()
+    limit: z.number().int().min(1).max(100).optional(),
+    /** #3128: the previous page's next_cursor (a receipt id). */
+    cursor: z.string().min(1).optional()
   },
   haven_verify_receipt: {
     receipt: z.unknown()
   }
+  // #3101: keys survive on the type (see the hosted server's contracts.ts).
 };
 var toolDescriptions = {
   haven_send: composeDescription(toolDescriptions$1.send),
@@ -488,12 +500,32 @@ function createToolHandlers(haven) {
           source: entry.source,
           domain_verified: entry.domainVerified,
           verified_payable: entry.verifiedPayable,
-          // Which Haven pay tool reaches this entry from the local MCP surface.
+          // Which Haven pay tool reaches this entry from the local MCP surface,
+          // and — #3100 (epic #3105, decision 4) — the arguments that tool
+          // accepts VERBATIM, spelled in ITS vocabulary (`merchant_url`, not
+          // the entry's `resource_url`). The local surface keeps pointing at
+          // its pay tools: they need no cap, so a verbatim hint exists.
           // #1328: the 'mpp' rail's only-ever catalog row (the Haven MPP demo
           // resource) is delisted with the mpp_demo retirement, so this
           // fallback is unreachable today; it stays x402 rather than naming a
           // deleted tool in case a future non-demo 'mpp' rail entry appears.
-          suggested_tool: entry.protocol === "mcp" ? "haven_pay_mcp_tool" : "haven_pay_x402"
+          // A row without a tool_name cannot get a verbatim hint —
+          // haven_pay_mcp_tool requires tool_name — so it gets the REASON
+          // instead of a hint its own tool refuses (haven-reviewer on #3113;
+          // the epic's "omitted + reason, never null" shape, decision 3).
+          ...entry.protocol === "mcp" ? entry.toolName ? {
+            suggested_tool: "haven_pay_mcp_tool",
+            suggested_arguments: {
+              merchant_url: entry.resourceUrl,
+              tool_name: entry.toolName,
+              ...entry.toolArguments ? { arguments: entry.toolArguments } : {}
+            }
+          } : {
+            suggested_tool_omitted_reason: "this catalog row carries no tool_name, which haven_pay_mcp_tool requires; read the merchant's tool list yourself, then call haven_pay_mcp_tool with merchant_url, tool_name and arguments"
+          } : {
+            suggested_tool: "haven_pay_x402",
+            suggested_arguments: { url: entry.resourceUrl }
+          }
         }));
       });
     },
@@ -513,7 +545,7 @@ function createToolHandlers(haven) {
     },
     haven_list_receipts: async (input) => {
       const args = objectInput("haven_list_receipts", input);
-      return runTool(async () => haven.listReceipts({ limit: args.limit }));
+      return runTool(async () => haven.listReceiptsPage({ limit: args.limit, cursor: args.cursor }));
     },
     haven_verify_receipt: async (input) => {
       const args = objectInput("haven_verify_receipt", input);
@@ -658,7 +690,11 @@ function normalizeError(err) {
       message: err.message,
       statusCode: err.statusCode,
       nextAction: err.nextAction,
-      retry_with_new_quote: err.retryWithNewQuote
+      next_action: err.nextAction,
+      retry_with_new_quote: err.retryWithNewQuote,
+      // #3103: the local runtime's one decision site — no tool can act until
+      // the merchant recovers; the message carries retry_after_s.
+      next_tool_omitted_reason: "the merchant needs to recover first; re-quote after the retry_after_s in the message"
     };
   }
   if (err instanceof HavenPaymentStateError) {
@@ -671,6 +707,7 @@ function normalizeError(err) {
       status: err.status,
       phase: err.phase,
       nextAction: err.nextAction,
+      next_action: err.nextAction,
       resume_state: err.resumeState,
       body: err.body
     };
@@ -692,6 +729,7 @@ function normalizeError(err) {
       paymentId: err.paymentId,
       phase: stringOrUndefined(body?.phase),
       nextAction: stringOrUndefined(body?.nextAction) ?? stringOrUndefined(body?.next_action) ?? AgentPaymentNextAction.StopAndTellUser,
+      next_action: stringOrUndefined(body?.nextAction) ?? stringOrUndefined(body?.next_action) ?? AgentPaymentNextAction.StopAndTellUser,
       body: err.body
     };
   }
@@ -708,7 +746,11 @@ function normalizeError(err) {
     success: false,
     code: "UNKNOWN_ERROR",
     message: err instanceof Error ? err.message : String(err),
-    nextAction: AgentPaymentNextAction.StopAndTellUser
+    nextAction: AgentPaymentNextAction.StopAndTellUser,
+    next_action: AgentPaymentNextAction.StopAndTellUser,
+    // #3103: the second local decision site — nothing structured can follow an
+    // error this runtime did not recognise.
+    next_tool_omitted_reason: "an error this runtime does not recognise; tell the user what the message says"
   };
 }
 function stringOrUndefined(value) {
@@ -721,7 +763,7 @@ function computeConsentHash(input) {
     input.apiKeyPrefix,
     input.apiUrl ?? "",
     input.agentId ?? "",
-    (input.safeAddress ?? "").toLowerCase(),
+    (input.accountAddress ?? "").toLowerCase(),
     (input.delegateAddress ?? "").toLowerCase(),
     input.chainId ?? ""
   ].join("|");
@@ -740,7 +782,7 @@ function renderConsentBlock(input, hash) {
   ];
   if (input.apiUrl) lines.push(`Haven API: ${input.apiUrl}`);
   if (input.agentId) lines.push(`Agent ID:  ${input.agentId}`);
-  if (input.safeAddress) lines.push(`Haven wallet (Safe): ${input.safeAddress}`);
+  if (input.accountAddress) lines.push(`Haven wallet (Safe): ${input.accountAddress}`);
   if (input.delegateAddress) lines.push(`Delegate (local signer): ${input.delegateAddress}`);
   if (typeof input.chainId === "number") lines.push(`Chain ID:  ${input.chainId}`);
   lines.push("");
@@ -847,14 +889,14 @@ async function writeAckFile(path, hash) {
 }
 async function consentInputFromClient(haven, seed, toolNames) {
   let allowanceSummary = seed.allowanceSummary ?? [];
-  let safeAddress = seed.safeAddress;
+  let accountAddress = seed.accountAddress;
   let delegateAddress = seed.delegateAddress;
   let chainId = seed.chainId;
   try {
     const summary = await haven.getAllowances();
     const list = isAllowanceSummary(summary) ? summary.allowances : Array.isArray(summary) ? summary : [];
     if (isAllowanceSummary(summary)) {
-      safeAddress = summary.accountAddress ?? summary.safeAddress ?? safeAddress;
+      accountAddress = summary.accountAddress ?? accountAddress;
       delegateAddress = summary.delegateAddress;
       chainId = typeof summary.chainId === "number" ? summary.chainId : chainId;
     }
@@ -870,7 +912,7 @@ async function consentInputFromClient(haven, seed, toolNames) {
     apiKeyPrefix: derivePrefix(seed.apiKey),
     apiUrl: seed.apiUrl,
     agentId: seed.agentId,
-    safeAddress,
+    accountAddress,
     delegateAddress,
     chainId,
     toolNames,
@@ -912,7 +954,7 @@ async function createHavenMcpServer(options = {}) {
   return buildMcpServer(haven);
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.2.1-alpha.0";
+var MCP_VERSION = "0.4.0-alpha.0";
 var MCP_INSTRUCTIONS = [
   "Haven local MCP server: signs in-process with the delegate key it holds on",
   "this machine \u2014 the key never leaves this process. Call haven_get_agent",
@@ -921,7 +963,8 @@ var MCP_INSTRUCTIONS = [
   "",
   "To pay: haven_discover_tools to find a payable service, then",
   "haven_pay_mcp_tool for MCP merchants or haven_pay_x402 for any x402",
-  "paywall. Tool responses carry nextAction \u2014 follow it; description prose",
+  "paywall. Tool responses carry next_action (nextAction is the same value, kept one more",
+  "release) and, when no tool follows, next_tool_omitted_reason \u2014 follow them; description prose",
   "is fallback, not the source of truth.",
   "",
   "A payment outside the agent budget is declined before any money moves. Haven",
@@ -985,7 +1028,7 @@ async function runConsentGate(haven, credentials, options) {
       apiKey: credentials.apiKey,
       apiUrl: credentials.apiUrl,
       agentId: credentials.agentId,
-      safeAddress: credentials.accountAddress ?? credentials.safeAddress,
+      accountAddress: credentials.accountAddress,
       delegateAddress: credentials.delegateAddress,
       chainId: credentials.chainId,
       allowanceSummary: credentials.allowanceSummary