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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { HavenClient } from '@haven_ai/sdk';
+import { HavenClientUpdate, HavenClient } from '@haven_ai/sdk';
 import { z } from 'zod/v3';
 
 interface HavenCredentialFile {
@@ -66,7 +66,7 @@ declare function loadCredentials(source?: string | HavenCredentialSource | undef
  * which is where URL-hardening would matter.)
  */
 
-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';
+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' | 'haven_open_task_budget' | 'haven_close_task_budget' | 'haven_submit';
 declare const toolSchemas: {
     readonly haven_send: {
         readonly asset: z.ZodEnum<["ETH", "USDC"]>;
@@ -75,6 +75,8 @@ declare const toolSchemas: {
         readonly idempotency_key: z.ZodOptional<z.ZodString>;
         /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
         readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+        /** #3329: spend against an open task budget instead of the agent's period budget. */
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
     };
     readonly haven_pay_mcp_tool: {
         readonly merchant_url: z.ZodString;
@@ -98,6 +100,8 @@ declare const toolSchemas: {
         readonly idempotency_key: z.ZodOptional<z.ZodString>;
         /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
         readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+        /** #3329: spend against an open task budget instead of the agent's period budget. */
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
     };
     readonly haven_pay_x402: {
         readonly url: z.ZodString;
@@ -107,6 +111,8 @@ declare const toolSchemas: {
         readonly idempotency_key: z.ZodOptional<z.ZodString>;
         /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
         readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+        /** #3329: spend against an open task budget instead of the agent's period budget. */
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
     };
     readonly haven_resume_x402_payment: {
         readonly payment_id: z.ZodOptional<z.ZodString>;
@@ -139,6 +145,21 @@ declare const toolSchemas: {
     readonly haven_verify_receipt: {
         readonly receipt: z.ZodUnknown;
     };
+    readonly haven_open_task_budget: {
+        readonly max_amount_human: z.ZodString;
+        readonly ttl_minutes: z.ZodNumber;
+        readonly recipient: z.ZodOptional<z.ZodString>;
+        readonly label: z.ZodOptional<z.ZodString>;
+        readonly token: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_close_task_budget: {
+        readonly task_budget_id: z.ZodString;
+    };
+    readonly haven_submit: {
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly signature: z.ZodString;
+    };
 };
 /**
  * MCP tool descriptions, composed from the shared semantic source in
@@ -159,6 +180,12 @@ interface ToolSuccess<T> {
      * leave, which is how `idempotencyKey` survived #2312 and #2348.
      */
     warnings?: string[];
+    /**
+     * #3303: the backend's `client_update` hint when this package is behind the
+     * version the deployment recommends (`required: false`) or below its
+     * minimum (`required: true`). Carries the exact command that updates it.
+     */
+    client_update?: HavenClientUpdate;
 }
 interface ToolFailure {
     success: false;
@@ -198,6 +225,8 @@ interface ToolFailure {
      * own wallet needs to recover first.
      */
     retry_with_new_quote?: boolean;
+    /** #3303: as on {@link ToolSuccess}; on a 426 `client_outdated` refusal it is always `required: true`. */
+    client_update?: HavenClientUpdate;
 }
 type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
 declare function createToolHandlers(haven: HavenClient): Record<HavenMcpToolName, (input: unknown) => Promise<ToolPayload>>;
@@ -239,7 +268,7 @@ interface ConsentInput {
     apiUrl?: string;
     /** Agent identity from the credential file, when present. */
     agentId?: string;
-    /** Haven wallet (Safe) the agent spends from. */
+    /** Haven wallet the agent spends from. */
     accountAddress?: string;
     /** Agent's delegate EOA — the local signer. */
     delegateAddress?: string;
@@ -345,7 +374,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.4.0-alpha.0";
+declare const MCP_VERSION = "0.6.0-alpha.0";
 /**
  * Refuse to start on an unsupported Node (#1161).
  *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { HavenClient } from '@haven_ai/sdk';
+import { HavenClientUpdate, HavenClient } from '@haven_ai/sdk';
 import { z } from 'zod/v3';
 
 interface HavenCredentialFile {
@@ -66,7 +66,7 @@ declare function loadCredentials(source?: string | HavenCredentialSource | undef
  * which is where URL-hardening would matter.)
  */
 
-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';
+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' | 'haven_open_task_budget' | 'haven_close_task_budget' | 'haven_submit';
 declare const toolSchemas: {
     readonly haven_send: {
         readonly asset: z.ZodEnum<["ETH", "USDC"]>;
@@ -75,6 +75,8 @@ declare const toolSchemas: {
         readonly idempotency_key: z.ZodOptional<z.ZodString>;
         /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
         readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+        /** #3329: spend against an open task budget instead of the agent's period budget. */
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
     };
     readonly haven_pay_mcp_tool: {
         readonly merchant_url: z.ZodString;
@@ -98,6 +100,8 @@ declare const toolSchemas: {
         readonly idempotency_key: z.ZodOptional<z.ZodString>;
         /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
         readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+        /** #3329: spend against an open task budget instead of the agent's period budget. */
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
     };
     readonly haven_pay_x402: {
         readonly url: z.ZodString;
@@ -107,6 +111,8 @@ declare const toolSchemas: {
         readonly idempotency_key: z.ZodOptional<z.ZodString>;
         /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
         readonly idempotencyKey: z.ZodOptional<z.ZodString>;
+        /** #3329: spend against an open task budget instead of the agent's period budget. */
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
     };
     readonly haven_resume_x402_payment: {
         readonly payment_id: z.ZodOptional<z.ZodString>;
@@ -139,6 +145,21 @@ declare const toolSchemas: {
     readonly haven_verify_receipt: {
         readonly receipt: z.ZodUnknown;
     };
+    readonly haven_open_task_budget: {
+        readonly max_amount_human: z.ZodString;
+        readonly ttl_minutes: z.ZodNumber;
+        readonly recipient: z.ZodOptional<z.ZodString>;
+        readonly label: z.ZodOptional<z.ZodString>;
+        readonly token: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_close_task_budget: {
+        readonly task_budget_id: z.ZodString;
+    };
+    readonly haven_submit: {
+        readonly task_budget_id: z.ZodOptional<z.ZodString>;
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly signature: z.ZodString;
+    };
 };
 /**
  * MCP tool descriptions, composed from the shared semantic source in
@@ -159,6 +180,12 @@ interface ToolSuccess<T> {
      * leave, which is how `idempotencyKey` survived #2312 and #2348.
      */
     warnings?: string[];
+    /**
+     * #3303: the backend's `client_update` hint when this package is behind the
+     * version the deployment recommends (`required: false`) or below its
+     * minimum (`required: true`). Carries the exact command that updates it.
+     */
+    client_update?: HavenClientUpdate;
 }
 interface ToolFailure {
     success: false;
@@ -198,6 +225,8 @@ interface ToolFailure {
      * own wallet needs to recover first.
      */
     retry_with_new_quote?: boolean;
+    /** #3303: as on {@link ToolSuccess}; on a 426 `client_outdated` refusal it is always `required: true`. */
+    client_update?: HavenClientUpdate;
 }
 type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
 declare function createToolHandlers(haven: HavenClient): Record<HavenMcpToolName, (input: unknown) => Promise<ToolPayload>>;
@@ -239,7 +268,7 @@ interface ConsentInput {
     apiUrl?: string;
     /** Agent identity from the credential file, when present. */
     agentId?: string;
-    /** Haven wallet (Safe) the agent spends from. */
+    /** Haven wallet the agent spends from. */
     accountAddress?: string;
     /** Agent's delegate EOA — the local signer. */
     delegateAddress?: string;
@@ -345,7 +374,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.4.0-alpha.0";
+declare const MCP_VERSION = "0.6.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, AgentPaymentFailureCode } from '@haven_ai/sdk';
+import { composeDescription, toolDescriptions as toolDescriptions$1, HavenPaymentStateError, HavenSigningError, HavenApiError, AgentPaymentNextAction, HavenError, HavenClient, havenClientIdentity, isSupportedNodeVersion, unsupportedNodeVersionMessage, verifyPaymentReceipt, discoverMerchantMcpUrl, sameUrl, AgentPaymentFailureCode, resolveTokenFromAddress } from '@haven_ai/sdk';
 import { readFile, stat, mkdir, writeFile } from 'fs/promises';
 import { z } from 'zod/v3';
 import { createHash } from 'crypto';
@@ -244,7 +244,9 @@ var toolSchemas = {
     amount: z.string().min(1),
     idempotency_key: z.string().optional(),
     /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    idempotencyKey: z.string().optional(),
+    /** #3329: spend against an open task budget instead of the agent's period budget. */
+    task_budget_id: z.string().min(1).optional()
   },
   haven_pay_mcp_tool: {
     merchant_url: z.string().url(),
@@ -267,7 +269,9 @@ var toolSchemas = {
     quote: z.unknown(),
     idempotency_key: z.string().optional(),
     /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    idempotencyKey: z.string().optional(),
+    /** #3329: spend against an open task budget instead of the agent's period budget. */
+    task_budget_id: z.string().min(1).optional()
   },
   haven_pay_x402: {
     url: z.string().url(),
@@ -276,7 +280,9 @@ var toolSchemas = {
     body: z.string().optional(),
     idempotency_key: z.string().optional(),
     /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    idempotencyKey: z.string().optional(),
+    /** #3329: spend against an open task budget instead of the agent's period budget. */
+    task_budget_id: z.string().min(1).optional()
   },
   haven_resume_x402_payment: {
     payment_id: z.string().optional(),
@@ -308,9 +314,59 @@ var toolSchemas = {
   },
   haven_verify_receipt: {
     receipt: z.unknown()
+  },
+  // #3329: a budget for one task that ends by itself — a short-lived child of
+  // the agent's own budget, capped and time-boxed independently of the period
+  // reset.
+  haven_open_task_budget: {
+    max_amount_human: z.string().min(1),
+    ttl_minutes: z.number().int().min(1).max(1440),
+    recipient: z.string().optional(),
+    label: z.string().max(120).optional(),
+    token: z.string().optional()
+  },
+  haven_close_task_budget: {
+    task_budget_id: z.string().min(1)
+  },
+  // #3329: relays a signature from the local signer — either the open/close
+  // signature for a task budget, or (schema parity with the hosted surface)
+  // a direct-payment signature by payment_id. Exactly one of task_budget_id /
+  // payment_id, never both or neither.
+  haven_submit: {
+    task_budget_id: z.string().min(1).optional(),
+    payment_id: z.string().min(1).optional(),
+    signature: z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string")
   }
   // #3101: keys survive on the type (see the hosted server's contracts.ts).
 };
+var OPEN_TASK_BUDGET_DESCRIPTION = [
+  "Open a budget for one task that ends by itself: a spending cap, good for at most ttl_minutes,",
+  "reserved out of the agent's own budget and separate from its period reset.",
+  'Pass max_amount_human (whole tokens, e.g. "5" for 5 USDC), ttl_minutes (1-1440), and optionally',
+  "recipient (pins every payment against this task budget to one address), label, and token",
+  '(defaults to USDC). Returns { task_budget, next_action: "sign", next_tool, next_arguments } \u2014',
+  "call next_tool with next_arguments EXACTLY as given to get a signature, then relay it with",
+  "haven_submit. Spending anything above the reserved amount, past the deadline, or to a",
+  "different recipient than the one pinned here is declined on the spot \u2014 nothing is queued.",
+  "A recipient pin is checked against where each payment first goes: haven_pay_x402 and",
+  "haven_pay_x402_quote first move funds into the agent's own wallet, so a budget pinned to a",
+  "merchant is declined there \u2014 pin only budgets meant for haven_send."
+].join(" ");
+var CLOSE_TASK_BUDGET_DESCRIPTION = [
+  "End a task budget early, before its deadline, releasing whatever of its cap was unspent back",
+  "to the agent's own budget. Pass task_budget_id. If the budget was never signed (still pending),",
+  'this ends it immediately with { task_budget, status: "closed" } and nothing was ever reserved',
+  'on-chain. Otherwise it returns a signature request: { task_budget, next_action: "sign",',
+  "next_tool, next_arguments } \u2014 call next_tool with next_arguments EXACTLY as given, then relay",
+  "the signature with haven_submit. A task budget past its own deadline closes immediately, the",
+  "same as the pending case."
+].join(" ");
+var SUBMIT_DESCRIPTION = [
+  "Relay a signature from the local signer. Pass exactly one of task_budget_id (from",
+  "haven_open_task_budget or haven_close_task_budget) or payment_id \u2014 never both, never neither \u2014",
+  "plus signature. For a task budget this opens or closes it on-chain and returns { task_budget,",
+  'status }; a close in progress may return { task_budget, status: "closed", close_tx_hash }.'
+].join(" ");
 var toolDescriptions = {
   haven_send: composeDescription(toolDescriptions$1.send),
   haven_pay_mcp_tool: composeDescription(toolDescriptions$1.payMcpTool),
@@ -326,7 +382,10 @@ var toolDescriptions = {
   haven_discover_tools: composeDescription(toolDescriptions$1.discoverTools),
   haven_submit_catalog_entry: composeDescription(toolDescriptions$1.submitCatalogEntry),
   haven_list_receipts: composeDescription(toolDescriptions$1.listReceipts),
-  haven_verify_receipt: composeDescription(toolDescriptions$1.verifyReceipt)
+  haven_verify_receipt: composeDescription(toolDescriptions$1.verifyReceipt),
+  haven_open_task_budget: OPEN_TASK_BUDGET_DESCRIPTION,
+  haven_close_task_budget: CLOSE_TASK_BUDGET_DESCRIPTION,
+  haven_submit: SUBMIT_DESCRIPTION
 };
 function createToolHandlers(haven) {
   return {
@@ -342,7 +401,10 @@ function createToolHandlers(haven) {
             to: args.recipient,
             // #1207: was accepted by the schema but silently dropped — now
             // carried to the backend's replay contract.
-            idempotencyKey: args.idempotencyKey
+            idempotencyKey: args.idempotencyKey,
+            // #3329: spend against an open task budget instead of the
+            // agent's period budget, when the caller names one.
+            ...typeof args.task_budget_id === "string" ? { taskBudgetId: args.task_budget_id } : {}
           });
           return {
             payment_id: result.paymentId,
@@ -440,7 +502,10 @@ function createToolHandlers(haven) {
         );
       }
       return runTool(async () => {
-        const response = await haven.payX402Quote(args.quote, { idempotencyKey: args.idempotencyKey });
+        const response = await haven.payX402Quote(args.quote, {
+          idempotencyKey: args.idempotencyKey,
+          ...typeof args.task_budget_id === "string" ? { taskBudgetId: args.task_budget_id } : {}
+        });
         return responsePayload(response);
       }, warnings);
     },
@@ -449,7 +514,10 @@ function createToolHandlers(haven) {
       if ("success" in pf) return pf;
       const { args, warnings } = pf;
       return runTool(async () => {
-        const response = await haven.fetch(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey });
+        const response = await haven.fetch(args.url, requestInit(args), {
+          idempotencyKey: args.idempotencyKey,
+          ...typeof args.task_budget_id === "string" ? { taskBudgetId: args.task_budget_id } : {}
+        });
         return responsePayload(response);
       }, warnings);
     },
@@ -550,6 +618,73 @@ function createToolHandlers(haven) {
     haven_verify_receipt: async (input) => {
       const args = objectInput("haven_verify_receipt", input);
       return runTool(async () => verifyPaymentReceipt(args.receipt));
+    },
+    haven_open_task_budget: async (input) => {
+      const args = objectInput("haven_open_task_budget", input);
+      return runTool(async () => {
+        const token = await resolveTaskBudgetToken(haven, typeof args.token === "string" ? args.token : void 0);
+        const maxAmountAtomic = humanToAtomicOrNull(args.max_amount_human, token.decimals);
+        if (maxAmountAtomic === null) {
+          throw new HavenApiError(
+            `max_amount_human ("${args.max_amount_human}") is not a valid decimal amount for ${token.symbol} (${token.decimals} decimal places). Nothing was reserved.`,
+            400
+          );
+        }
+        const result = await haven.openTaskBudget({
+          tokenAddress: token.address,
+          maxAmountAtomic,
+          ttlSeconds: Number(args.ttl_minutes) * 60,
+          recipientAddress: typeof args.recipient === "string" ? args.recipient : void 0,
+          label: typeof args.label === "string" ? args.label : void 0
+        });
+        return {
+          task_budget: result.taskBudget,
+          next_action: "sign",
+          next_tool: "mcp__haven-signer__haven_sign",
+          next_arguments: { task_budget_id: result.taskBudget.id }
+        };
+      });
+    },
+    haven_close_task_budget: async (input) => {
+      const args = objectInput("haven_close_task_budget", input);
+      return runTool(async () => {
+        const result = await haven.closeTaskBudget(args.task_budget_id);
+        if (result.status === "closed") {
+          return { task_budget: result.taskBudget, status: "closed" };
+        }
+        return {
+          task_budget: result.taskBudget,
+          next_action: "sign",
+          next_tool: "mcp__haven-signer__haven_sign",
+          next_arguments: { task_budget_id: args.task_budget_id }
+        };
+      });
+    },
+    haven_submit: async (input) => {
+      const args = objectInput("haven_submit", input);
+      const hasTaskBudget = typeof args.task_budget_id === "string" && args.task_budget_id.length > 0;
+      const hasPayment = typeof args.payment_id === "string" && args.payment_id.length > 0;
+      if (hasTaskBudget === hasPayment) {
+        return {
+          success: false,
+          code: "INVALID_INPUT",
+          message: "haven_submit takes exactly one of task_budget_id or payment_id, never both or neither. Nothing was relayed."
+        };
+      }
+      return runTool(async () => {
+        if (hasTaskBudget) {
+          const result = await haven.submitTaskBudget(args.task_budget_id, args.signature);
+          return {
+            task_budget: result.taskBudget,
+            status: result.status,
+            ...result.closeTxHash !== void 0 ? { close_tx_hash: result.closeTxHash } : {}
+          };
+        }
+        throw new HavenApiError(
+          "haven_submit with payment_id is not supported on the local MCP surface: haven_send signs and submits a direct payment in one call, so there is no separate relay step. Use haven_submit with task_budget_id to relay a task-budget open/close signature.",
+          400
+        );
+      });
     }
   };
   async function resumeState(args, rail) {
@@ -641,6 +776,28 @@ async function responsePayload(response) {
     body: parseMaybeJson(text)
   };
 }
+async function resolveTaskBudgetToken(haven, symbolOrAddress) {
+  const wanted = (symbolOrAddress ?? "USDC").toLowerCase();
+  const { allowances } = await haven.getAllowances();
+  const isAddress = /^0x[0-9a-fA-F]{40}$/.test(wanted);
+  const match = isAddress ? allowances.find((a) => a.tokenAddress.toLowerCase() === wanted) : allowances.find((a) => (a.tokenSymbol ?? "").toLowerCase() === wanted);
+  if (!match) {
+    const known = allowances.map((a) => `${a.tokenSymbol} (${a.tokenAddress})`);
+    throw new HavenApiError(
+      `token "${symbolOrAddress ?? "USDC"}" is not the symbol or address of any allowance this agent holds${known.length > 0 ? ` (it holds: ${known.join(", ")})` : " (it holds none)"}. Nothing was reserved.`,
+      400
+    );
+  }
+  const resolved = resolveTokenFromAddress(match.tokenAddress);
+  return { address: match.tokenAddress, symbol: match.tokenSymbol, decimals: resolved?.decimals ?? 6 };
+}
+function humanToAtomicOrNull(human, decimals) {
+  if (!/^[0-9]+(\.[0-9]+)?$/.test(human)) return null;
+  const [whole, frac = ""] = human.split(".");
+  if (frac.length > decimals) return null;
+  const atomic = BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(frac.padEnd(decimals, "0") || "0");
+  return atomic.toString();
+}
 function parseMaybeJson(text) {
   if (!text) return null;
   try {
@@ -730,6 +887,9 @@ function normalizeError(err) {
       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,
+      // #3303: a backend refusal that already names why no tool follows (the
+      // 426 `client_outdated` does) keeps that reason at the top level.
+      ...typeof body?.next_tool_omitted_reason === "string" ? { next_tool_omitted_reason: body.next_tool_omitted_reason } : {},
       body: err.body
     };
   }
@@ -782,7 +942,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.accountAddress) lines.push(`Haven wallet (Safe): ${input.accountAddress}`);
+  if (input.accountAddress) lines.push(`Haven wallet: ${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("");
@@ -945,7 +1105,10 @@ async function resolveHavenClient(options = {}) {
   const client = new HavenClient({
     apiKey: credentials.apiKey,
     delegateKey: credentials.delegateKey,
-    baseUrl: credentials.apiUrl
+    baseUrl: credentials.apiUrl,
+    // #3303: name this package, not the SDK inside it, so the backend's
+    // update hint and refusal speak about what the user actually installed.
+    clientIdentity: havenClientIdentity(MCP_NAME, MCP_VERSION)
   });
   return { client, credentials };
 }
@@ -954,7 +1117,7 @@ async function createHavenMcpServer(options = {}) {
   return buildMcpServer(haven);
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.4.0-alpha.0";
+var MCP_VERSION = "0.6.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",
@@ -991,7 +1154,7 @@ function buildMcpServer(haven) {
       toolSchemas[name],
       async (args) => haven.withRequestContext(
         { "X-Haven-MCP-Tool": name },
-        async () => toMcpResult(await handlers[name](args))
+        async () => toMcpResult(withClientUpdate(await handlers[name](args), haven.clientUpdate()))
       )
     );
   }
@@ -1041,6 +1204,10 @@ async function runConsentGate(haven, credentials, options) {
     writeAck: options.writeAck
   });
 }
+function withClientUpdate(payload, hint) {
+  if (!hint || payload.client_update) return payload;
+  return { ...payload, client_update: hint };
+}
 function toMcpResult(payload) {
   return {
     isError: !payload.success,