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

package/dist/index.cjs

@@ -304,11 +304,14 @@ var toolSchemas = {
     website: v3.z.string().optional()
   },
   haven_list_receipts: {
-    limit: v3.z.number().int().min(1).max(100).optional()
+    limit: v3.z.number().int().min(1).max(100).optional(),
+    /** #3128: the previous page's next_cursor (a receipt id). */
+    cursor: v3.z.string().min(1).optional()
   },
   haven_verify_receipt: {
     receipt: v3.z.unknown()
   }
+  // #3101: keys survive on the type (see the hosted server's contracts.ts).
 };
 var toolDescriptions = {
   haven_send: sdk.composeDescription(sdk.toolDescriptions.send),
@@ -499,12 +502,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 }
+          }
         }));
       });
     },
@@ -524,7 +547,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);
@@ -669,7 +692,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 sdk.HavenPaymentStateError) {
@@ -682,6 +709,7 @@ function normalizeError(err) {
       status: err.status,
       phase: err.phase,
       nextAction: err.nextAction,
+      next_action: err.nextAction,
       resume_state: err.resumeState,
       body: err.body
     };
@@ -703,6 +731,10 @@ function normalizeError(err) {
       paymentId: err.paymentId,
       phase: stringOrUndefined(body?.phase),
       nextAction: stringOrUndefined(body?.nextAction) ?? stringOrUndefined(body?.next_action) ?? sdk.AgentPaymentNextAction.StopAndTellUser,
+      next_action: stringOrUndefined(body?.nextAction) ?? stringOrUndefined(body?.next_action) ?? sdk.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
     };
   }
@@ -719,7 +751,11 @@ function normalizeError(err) {
     success: false,
     code: "UNKNOWN_ERROR",
     message: err instanceof Error ? err.message : String(err),
-    nextAction: sdk.AgentPaymentNextAction.StopAndTellUser
+    nextAction: sdk.AgentPaymentNextAction.StopAndTellUser,
+    next_action: sdk.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) {
@@ -751,7 +787,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("");
@@ -914,7 +950,10 @@ async function resolveHavenClient(options = {}) {
   const client = new sdk.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: sdk.havenClientIdentity(MCP_NAME, MCP_VERSION)
   });
   return { client, credentials };
 }
@@ -923,7 +962,7 @@ async function createHavenMcpServer(options = {}) {
   return buildMcpServer(haven);
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.3.0-alpha.0";
+var MCP_VERSION = "0.5.0-alpha.1";
 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",
@@ -932,7 +971,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",
@@ -959,7 +999,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()))
       )
     );
   }
@@ -1009,6 +1049,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,