@haven_ai/mcp 0.2.0-alpha.0 → 0.3.0-alpha.0

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
@@ -113,6 +101,13 @@ interface ToolFailure {
     nextAction?: string;
     resume_state?: unknown;
     body?: unknown;
+    /**
+     * #2983: carried on `MERCHANT_NOT_READY` — mirrors the hosted MCP's
+     * `retry_with_new_quote` (`mcp-context.ts`'s `merchantNotReadyErrorFor`).
+     * Genuinely retryable: nothing about the CALL was wrong, the merchant's
+     * own wallet needs to recover first.
+     */
+    retry_with_new_quote?: boolean;
 }
 type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
 declare function createToolHandlers(haven: HavenClient): Record<HavenMcpToolName, (input: unknown) => Promise<ToolPayload>>;
@@ -155,7 +150,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. */
@@ -195,8 +190,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. */
@@ -260,7 +255,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.0-alpha.0";
+declare const MCP_VERSION = "0.3.0-alpha.0";
 /**
  * Refuse to start on an unsupported Node (#1161).
  *

package/dist/index.js

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { composeDescription, toolDescriptions as toolDescriptions$1, HavenPaymentStateError, HavenSigningError, HavenApiError, AgentPaymentNextAction, HavenError, HavenClient, isSupportedNodeVersion, unsupportedNodeVersionMessage, verifyPaymentReceipt, discoverMerchantMcpUrl, sameUrl } from '@haven_ai/sdk';
+import { composeDescription, toolDescriptions as toolDescriptions$1, HavenPaymentStateError, HavenSigningError, HavenApiError, AgentPaymentNextAction, HavenError, HavenClient, isSupportedNodeVersion, unsupportedNodeVersionMessage, verifyPaymentReceipt, discoverMerchantMcpUrl, sameUrl, AgentPaymentFailureCode } from '@haven_ai/sdk';
 import { readFile, stat, mkdir, writeFile } from 'fs/promises';
 import { z } from 'zod/v3';
 import { createHash } from 'crypto';
@@ -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;
@@ -372,6 +381,8 @@ function createToolHandlers(haven) {
         const attempt = () => haven.fetch(merchantUrl, init, { idempotencyKey });
         let response = await attempt();
         if (!response.ok) {
+          const notReady = await merchantNotReadyErrorFor(response);
+          if (notReady) throw notReady;
           const discovered = await discoverMerchantMcpUrl(merchantUrl);
           if (!discovered || sameUrl(discovered, merchantUrl)) {
             throw discoveryMissError(response, merchantUrl, discovered);
@@ -380,6 +391,8 @@ function createToolHandlers(haven) {
           merchantUrl = discovered;
           const retryResponse = await attempt();
           if (!retryResponse.ok) {
+            const notReadyAtDiscovered = await merchantNotReadyErrorFor(retryResponse);
+            if (notReadyAtDiscovered) throw notReadyAtDiscovered;
             throw discoveryMissError(retryResponse, merchantUrl, discovered, inputUrl);
           }
           response = retryResponse;
@@ -613,12 +626,50 @@ function parseMaybeJson(text) {
     return text;
   }
 }
+var MerchantNotReadyError = class extends Error {
+  code = AgentPaymentFailureCode.MerchantNotReady;
+  statusCode = 503;
+  nextAction = AgentPaymentNextAction.StopAndTellUser;
+  // Genuinely retryable — unlike a rejection, nothing about THIS call was
+  // wrong; the merchant's own wallet needs to recover first.
+  retryWithNewQuote = true;
+  constructor(message) {
+    super(message);
+    this.name = "MerchantNotReadyError";
+  }
+};
+async function merchantNotReadyErrorFor(response) {
+  if (response.status !== 503) return null;
+  let body;
+  try {
+    body = await response.clone().json();
+  } catch {
+    return null;
+  }
+  if (!body || typeof body !== "object" || body.error !== "merchant_not_ready") {
+    return null;
+  }
+  const { reason_code, settlements_remaining, retry_after_s } = body;
+  return new MerchantNotReadyError(
+    "The merchant refused this call: it cannot settle a payment right now" + (typeof reason_code === "string" ? ` (reason_code: ${reason_code})` : "") + (typeof settlements_remaining === "number" ? `, settlements_remaining: ${settlements_remaining}` : "") + ". No payment was created." + (typeof retry_after_s === "number" ? ` Retry after approximately ${retry_after_s}s.` : " This is often transient; retry later.")
+  );
+}
 function discoveryMissError(response, merchantUrl, discovered, discoveredFromUrl) {
   const base = discoveredFromUrl ? `Merchant call to ${merchantUrl} failed with HTTP ${response.status} (at the DISCOVERED endpoint ${merchantUrl}, resolved from ${discoveredFromUrl} via the merchant discovery document).` : `Merchant call to ${merchantUrl} failed with HTTP ${response.status}.`;
   const guidance = discoveredFromUrl ? "" : discovered ? ` Same-origin discovery resolved the same URL (${discovered}), which still did not answer successfully.` : ` No same-origin discovery document was found at /.well-known/haven-demo-merchant or /. If ${merchantUrl} is a base merchant URL, pass the exact MCP endpoint instead (often <origin>/mcp).`;
   return new HavenApiError(`${base}${guidance}`, response.status || 400);
 }
 function normalizeError(err) {
+  if (err instanceof MerchantNotReadyError) {
+    return {
+      success: false,
+      code: err.code,
+      message: err.message,
+      statusCode: err.statusCode,
+      nextAction: err.nextAction,
+      retry_with_new_quote: err.retryWithNewQuote
+    };
+  }
   if (err instanceof HavenPaymentStateError) {
     return {
       success: false,
@@ -679,7 +730,7 @@ function computeConsentHash(input) {
     input.apiKeyPrefix,
     input.apiUrl ?? "",
     input.agentId ?? "",
-    (input.safeAddress ?? "").toLowerCase(),
+    (input.accountAddress ?? "").toLowerCase(),
     (input.delegateAddress ?? "").toLowerCase(),
     input.chainId ?? ""
   ].join("|");
@@ -698,7 +749,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("");
@@ -805,14 +856,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;
     }
@@ -828,7 +879,7 @@ async function consentInputFromClient(haven, seed, toolNames) {
     apiKeyPrefix: derivePrefix(seed.apiKey),
     apiUrl: seed.apiUrl,
     agentId: seed.agentId,
-    safeAddress,
+    accountAddress,
     delegateAddress,
     chainId,
     toolNames,
@@ -870,7 +921,7 @@ async function createHavenMcpServer(options = {}) {
   return buildMcpServer(haven);
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.2.0-alpha.0";
+var MCP_VERSION = "0.3.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",
@@ -943,7 +994,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