@haven_ai/mcp 0.5.0-alpha.1 → 0.7.0-alpha.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { composeDescription, toolDescriptions as toolDescriptions$1, HavenClient, havenClientIdentity, isSupportedNodeVersion, unsupportedNodeVersionMessage, HavenPaymentStateError, HavenSigningError, HavenApiError, AgentPaymentNextAction, HavenError, AgentPaymentFailureCode, verifyPaymentReceipt, discoverMerchantMcpUrl, sameUrl } from '@haven_ai/sdk';
+import { composeDescription, toolDescriptions as toolDescriptions$1, HavenClient, havenClientIdentity, isSupportedNodeVersion, unsupportedNodeVersionMessage, resolveTokenBySymbol, formatTokenAmount, HavenPaymentStateError, HavenSigningError, HavenApiError, AgentPaymentNextAction, HavenError, AgentPaymentFailureCode, verifyPaymentReceipt, discoverMerchantMcpUrl, sameUrl, resolveTokenFromAddress, TASK_SIGN_CONTEXT_VERSION, connectorUpgradeCommand } from '@haven_ai/sdk';
 import { readFile, mkdir, writeFile, stat } from 'fs/promises';
 import { z } from 'zod/v3';
 import { createHash } from 'crypto';
@@ -236,6 +236,17 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
     );
   }
 }
+var TASK_BUDGET_MIN_SIGNER_VERSION = "0.6.0-alpha.0";
+var SIGNER_CAPABILITY_KEY = "haven/signer-compatibility";
+function taskSignerCompatibilityNotice() {
+  return {
+    task_sign_context_version: TASK_SIGN_CONTEXT_VERSION,
+    min_signer_version: TASK_BUDGET_MIN_SIGNER_VERSION,
+    signer_capability: SIGNER_CAPABILITY_KEY,
+    check: `Call next_tool with next_arguments EXACTLY as given \u2014 the signer fetches the exact bytes by task_budget_id. If haven_sign answers SIGNING_ERROR with a message starting "Pass payment_id (preferred for delegation-rail x402", the signer predates task budgets and signed nothing: first close this budget with haven_close_task_budget { task_budget_id } to release it, then update the connector by running \`${connectorUpgradeCommand()}\` and the repair line it prints, then open the budget again.`,
+    fallback: `haven_sign answered SIGNING_ERROR with a message starting "Pass payment_id (preferred for delegation-rail x402" \u2014 the signer predates task budgets and signed nothing: call haven_close_task_budget { task_budget_id } to release the pending budget, then update the connector by running \`${connectorUpgradeCommand()}\` and the repair line it prints, then open the budget again. There is no relay fallback for this signing context.`
+  };
+}
 var headersSchema = z.record(z.string(), z.string()).optional();
 var toolSchemas = {
   haven_send: {
@@ -243,16 +254,24 @@ var toolSchemas = {
     recipient: z.string().min(1),
     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()
+    /** REMOVED (#3411): declared only so the resolver can refuse it by name, never accepted. */
+    idempotencyKey: z.string().optional().describe("REMOVED (#3411): refused \u2014 send idempotency_key"),
+    /** #3329: spend against an open task budget instead of the agent's period budget. */
+    task_budget_id: z.string().min(1).optional(),
+    /**
+     * #3330: spend against an open sub-budget this agent HOLDS (it is the
+     * sub-agent B) instead of the agent's own budget. Mutually exclusive
+     * with task_budget_id — the backend refuses a body naming both.
+     */
+    sub_budget_id: z.string().min(1).optional()
   },
   haven_pay_mcp_tool: {
     merchant_url: z.string().url(),
     tool_name: z.string().min(1),
     arguments: z.record(z.string(), z.unknown()).optional(),
     idempotency_key: z.string().optional(),
-    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    /** REMOVED (#3411): declared only so the resolver can refuse it by name, never accepted. */
+    idempotencyKey: z.string().optional().describe("REMOVED (#3411): refused \u2014 send idempotency_key")
   },
   haven_quote_x402: {
     url: z.string().url(),
@@ -260,14 +279,18 @@ var toolSchemas = {
     headers: headersSchema,
     body: z.string().optional(),
     idempotency_key: z.string().optional(),
-    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    /** REMOVED (#3411): declared only so the resolver can refuse it by name, never accepted. */
+    idempotencyKey: z.string().optional().describe("REMOVED (#3411): refused \u2014 send idempotency_key")
   },
   haven_pay_x402_quote: {
     quote: z.unknown(),
     idempotency_key: z.string().optional(),
-    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    /** REMOVED (#3411): declared only so the resolver can refuse it by name, never accepted. */
+    idempotencyKey: z.string().optional().describe("REMOVED (#3411): refused \u2014 send idempotency_key"),
+    /** #3329: spend against an open task budget instead of the agent's period budget. */
+    task_budget_id: z.string().min(1).optional(),
+    /** #3330: spend against an open sub-budget this agent holds (it is sub-agent B). Mutually exclusive with task_budget_id. */
+    sub_budget_id: z.string().min(1).optional()
   },
   haven_pay_x402: {
     url: z.string().url(),
@@ -275,8 +298,12 @@ var toolSchemas = {
     headers: headersSchema,
     body: z.string().optional(),
     idempotency_key: z.string().optional(),
-    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
-    idempotencyKey: z.string().optional()
+    /** REMOVED (#3411): declared only so the resolver can refuse it by name, never accepted. */
+    idempotencyKey: z.string().optional().describe("REMOVED (#3411): refused \u2014 send idempotency_key"),
+    /** #3329: spend against an open task budget instead of the agent's period budget. */
+    task_budget_id: z.string().min(1).optional(),
+    /** #3330: spend against an open sub-budget this agent holds (it is sub-agent B). Mutually exclusive with task_budget_id. */
+    sub_budget_id: z.string().min(1).optional()
   },
   haven_resume_x402_payment: {
     payment_id: z.string().optional(),
@@ -304,13 +331,65 @@ var toolSchemas = {
   haven_list_receipts: {
     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()
+    cursor: z.string().min(1).optional(),
+    /** #3423: drop each row's payload echoes; the default shape is unchanged. */
+    compact: z.boolean().optional().describe("true drops challengePayload, selectedPayment and protocolReceiptPayload from each row; omit for the full row.")
   },
   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 +405,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 {
@@ -340,9 +422,15 @@ function createToolHandlers(haven) {
             token: args.asset,
             amount: args.amount,
             to: args.recipient,
-            // #1207: was accepted by the schema but silently dropped — now
-            // carried to the backend's replay contract.
-            idempotencyKey: args.idempotencyKey
+            // #1207/#3411: was accepted by the schema but silently dropped — now
+            // carried to the backend's replay contract via the resolved carrier.
+            idempotencyKey: args.resolvedIdempotencyKey,
+            // #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 } : {},
+            // #3330: spend through a sub-budget this agent holds (it is
+            // sub-agent B). Exactly one of the two ids, never both.
+            ...typeof args.sub_budget_id === "string" ? { subBudgetId: args.sub_budget_id } : {}
           });
           return {
             payment_id: result.paymentId,
@@ -380,7 +468,7 @@ function createToolHandlers(haven) {
           body: JSON.stringify(envelope)
         };
         let merchantUrl = args.merchant_url;
-        const idempotencyKey = args.idempotencyKey;
+        const idempotencyKey = args.resolvedIdempotencyKey;
         const attempt = () => haven.fetch(merchantUrl, init, { idempotencyKey });
         let response = await attempt();
         if (!response.ok) {
@@ -414,7 +502,7 @@ function createToolHandlers(haven) {
       if ("success" in pf) return pf;
       const { args, warnings } = pf;
       try {
-        const data = await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey });
+        const data = await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.resolvedIdempotencyKey });
         return warnings.length > 0 ? { success: true, data, warnings } : { success: true, data };
       } catch (err) {
         return normalizeError(err);
@@ -440,7 +528,11 @@ 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.resolvedIdempotencyKey,
+          ...typeof args.task_budget_id === "string" ? { taskBudgetId: args.task_budget_id } : {},
+          ...typeof args.sub_budget_id === "string" ? { subBudgetId: args.sub_budget_id } : {}
+        });
         return responsePayload(response);
       }, warnings);
     },
@@ -449,7 +541,11 @@ 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.resolvedIdempotencyKey,
+          ...typeof args.task_budget_id === "string" ? { taskBudgetId: args.task_budget_id } : {},
+          ...typeof args.sub_budget_id === "string" ? { subBudgetId: args.sub_budget_id } : {}
+        });
         return responsePayload(response);
       }, warnings);
     },
@@ -545,11 +641,82 @@ function createToolHandlers(haven) {
     },
     haven_list_receipts: async (input) => {
       const args = objectInput("haven_list_receipts", input);
-      return runTool(async () => haven.listReceiptsPage({ limit: args.limit, cursor: args.cursor }));
+      return runTool(
+        async () => haven.listReceiptsPage({ limit: args.limit, cursor: args.cursor, compact: args.compact === true })
+      );
     },
     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 },
+          signer_compatibility: taskSignerCompatibilityNotice()
+        };
+      });
+    },
+    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 },
+          signer_compatibility: taskSignerCompatibilityNotice()
+        };
+      });
+    },
+    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) {
@@ -578,28 +745,20 @@ function preflight(name, input) {
   }
   const idem = resolveIdempotencyKey(args);
   if ("success" in idem) return idem;
-  if (idem.key !== void 0) args = { ...args, idempotencyKey: idem.key };
+  if (idem.key !== void 0) args = { ...args, resolvedIdempotencyKey: idem.key };
   return { args, warnings: idem.warnings };
 }
 function resolveIdempotencyKey(args) {
   const modern = typeof args.idempotency_key === "string" ? args.idempotency_key : void 0;
   const legacy = typeof args.idempotencyKey === "string" ? args.idempotencyKey : void 0;
-  if (modern !== void 0 && legacy !== void 0 && modern !== legacy) {
+  if (legacy !== void 0) {
     return {
       success: false,
-      code: "AMBIGUOUS_IDEMPOTENCY_KEY",
-      message: "Both idempotency_key and idempotencyKey were sent with different values. Nothing was contacted or spent. Send exactly one \u2014 idempotency_key is the current spelling; idempotencyKey is deprecated and will be removed."
+      code: "IDEMPOTENCY_KEY_RENAMED",
+      message: "idempotencyKey has been renamed to idempotency_key and is no longer accepted. Send idempotency_key instead. Nothing was contacted or spent."
     };
   }
   if (modern !== void 0) return { key: modern, warnings: [] };
-  if (legacy !== void 0) {
-    return {
-      key: legacy,
-      warnings: [
-        "idempotencyKey is deprecated and will be removed in a future release of @haven_ai/mcp. Send idempotency_key instead \u2014 it is the spelling the hosted Haven MCP surface and every other Haven wire contract use."
-      ]
-    };
-  }
   return { warnings: [] };
 }
 function buildMcpToolsCallEnvelope(toolName, args) {
@@ -641,6 +800,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 {
@@ -808,7 +989,7 @@ function renderConsentBlock(input, hash) {
     lines.push("signed delegation, not by Haven):");
     for (const a of input.allowanceSummary) {
       const reset = a.resetMinutes ? ` per ${a.resetMinutes} min` : " (no reset)";
-      lines.push(`  \u2022 up to ${a.amount} ${a.token}${reset}`);
+      lines.push(`  \u2022 up to ${describeBudgetAmount(a, input.chainId)}${reset}`);
     }
   }
   lines.push("");
@@ -905,7 +1086,14 @@ async function consentInputFromClient(haven, seed, toolNames) {
     }
     const liveAllowanceSummary = list.map((a) => ({
       token: a.tokenSymbol ?? "UNKNOWN",
-      amount: a.onchain?.amount ?? a.configuredAmount ?? "0",
+      // #3410: `onchain.amount` is the atomic budget (`budget_atomic` on the
+      // backend). The old `a.configuredAmount` fallback here was unreachable
+      // — `onchain` is required in the SDK types and dereferenced
+      // unconditionally, so a response without it throws into the seed path —
+      // and it was the one HUMAN-decimal value in this chain; a human number
+      // must never reach an atomic field. '0' keeps the (defensive) shape for
+      // a malformed onchain object without inventing a unit.
+      amount: a.onchain?.amount ?? "0",
       resetMinutes: typeof a.onchain?.resetTimeMin === "number" ? a.onchain.resetTimeMin : typeof a.resetPeriodMin === "number" ? a.resetPeriodMin : null
     }));
     allowanceSummary = liveAllowanceSummary;
@@ -928,6 +1116,11 @@ function isAllowanceSummary(value) {
 function derivePrefix(apiKey) {
   return apiKey.slice(0, 12);
 }
+function describeBudgetAmount(a, chainId) {
+  const token = chainId === void 0 ? null : resolveTokenBySymbol(chainId, a.token);
+  if (!token) return `${a.amount} ${a.token} (atomic units)`;
+  return `${formatTokenAmount(a.amount, token.decimals)} ${a.token}`;
+}
 function registeredToolNames() {
   return Object.keys(toolSchemas);
 }
@@ -952,7 +1145,7 @@ async function resolveHavenClient(options = {}) {
   return { client, credentials };
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.5.0-alpha.1";
+var MCP_VERSION = "0.7.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",