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

package/dist/index.js

@@ -2,13 +2,14 @@ import { randomUUID, createHash } from 'crypto';
 import { recoverTypedDataAddress, hashTypedData, hashMessage } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { exact } from 'x402/schemes';
-import { addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, buildSweepAuthorizationMessage, verifySignature, x402AuthorizationAmount, SignerRefusalCode, connectorRerunCommand, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, buildX402ExpectedMessage, HavenError, AgentPaymentFailureCode, AgentPaymentNextAction, isSupportedNodeVersion, unsupportedNodeVersionMessage, signHash } from '@haven_ai/sdk';
+import { createNextStepBuilder, addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, buildSweepAuthorizationMessage, verifySignature, x402AuthorizationAmount, SignerRefusalCode, connectorRerunCommand, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, buildX402ExpectedMessage, HavenError, AgentPaymentFailureCode, AgentPaymentNextAction, isSupportedNodeVersion, unsupportedNodeVersionMessage, signHash } from '@haven_ai/sdk';
 import { readFile, stat, mkdir, appendFile, writeFile } from 'fs/promises';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { homedir } from 'os';
 import { resolve, dirname, join } from 'path';
-import { z } from 'zod/v3';
+import { z as z$1 } from 'zod/v3';
+import { z } from 'zod';
 
 // src/core.ts
 var DELEGATION_MANAGER = "0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3";
@@ -494,7 +495,10 @@ function signerInstructions() {
     "",
     "A version-mismatch refusal from haven_sign / haven_sign_x402 / haven_sign_sweep_delegate is",
     "machine-readable, not just prose: it carries code, supported_versions, received_version, and",
-    "fallback fields alongside the message, so you can branch on it directly."
+    "fallback fields alongside the message, so you can branch on it directly. Every signer",
+    "refusal also carries the next-step family: next_tool_name + next_tool_server_role when a",
+    "hosted tool follows (resolve the role against your own server names), else",
+    "next_tool_omitted_reason saying why not."
   ].join("\n");
 }
 async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
@@ -506,7 +510,6 @@ async function loadSignerCredentials(path = process.env.HAVEN_CREDENTIALS) {
       delegateKey: envKey,
       agentId: stringField(process.env.HAVEN_AGENT_ID),
       accountAddress,
-      safeAddress: accountAddress,
       chainId: chainIdField(process.env.HAVEN_CHAIN_ID, "HAVEN_CHAIN_ID"),
       network: stringField(process.env.HAVEN_NETWORK),
       x402BindingSigner: stringField(process.env.HAVEN_X402_BINDING_SIGNER)
@@ -541,7 +544,6 @@ async function loadFromFile(path) {
     delegateKey,
     agentId: stringField(raw.agent_id ?? raw.agentId),
     accountAddress,
-    safeAddress: accountAddress,
     chainId: chainIdField(raw.chain_id ?? raw.chainId, "chain_id"),
     network: stringField(raw.network),
     x402BindingSigner: stringField(
@@ -554,7 +556,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);
+  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;
@@ -611,7 +628,7 @@ function createSigningAuditEntry(tool, payloadHash, context, now = /* @__PURE__
     payload_hash: payloadHash,
     delegate_address: context.delegateAddress
   };
-  if (context.safeAddress) entry.safe_address = context.safeAddress;
+  if (context.accountAddress) entry.safe_address = context.accountAddress;
   if (typeof context.chainId === "number") entry.chain_id = context.chainId;
   return entry;
 }
@@ -627,6 +644,38 @@ function stableStringify(value) {
   const object = value;
   return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
 }
+var SIGNER_HOSTED_HANDOFF_SHAPES = {
+  haven_get_payment_status: { payment_id: z.string().min(1) }
+};
+function target(shape) {
+  const schema = z.object(shape).strict();
+  return {
+    role: "hosted",
+    validate: (input) => {
+      const r = schema.safeParse(input ?? {});
+      return r.success ? null : r.error.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join("; ");
+    }
+  };
+}
+var SIGNER_NEXT_STEP_TARGETS = {
+  haven_get_payment_status: target(SIGNER_HOSTED_HANDOFF_SHAPES.haven_get_payment_status)
+};
+var nextStep = createNextStepBuilder(SIGNER_NEXT_STEP_TARGETS);
+function signerRefusalStep(input) {
+  return nextStep({ ...input, safeToContinue: false, reason: "" });
+}
+function nextStepWireFields(step) {
+  return {
+    ...step.next_tool ? { next_tool: step.next_tool } : {},
+    ...step.next_tool_server ? { next_tool_server: step.next_tool_server } : {},
+    ...step.next_tool_name ? { next_tool_name: step.next_tool_name } : {},
+    ...step.next_tool_server_role ? { next_tool_server_role: step.next_tool_server_role } : {},
+    ...step.next_arguments ? { next_arguments: step.next_arguments } : {},
+    ...step.next_tool_omitted_reason ? { next_tool_omitted_reason: step.next_tool_omitted_reason } : {}
+  };
+}
+
+// src/sign-context.ts
 var HavenSignContextError = class extends HavenSigningError {
   /**
    * #3001 / #3010 review: the recovery path, when signing OTHER bytes is
@@ -646,28 +695,63 @@ var HavenSignContextError = class extends HavenSigningError {
    * plain `HavenError` branch already does for that code.
    */
   next_action;
+  /**
+   * #3103 (epic #3105, decisions 1 and 3): the typed next step beside the
+   * action. A refusal Haven made (`SIGN_CONTEXT_REFUSED`, not expired) names
+   * the hosted status read with the payment id; a transport failure or a
+   * malformed body names no tool — the remedy is re-running the SAME quote
+   * tool with `include_signing_payload: true` — and an expired window names
+   * none either (which quote tool depends on the flow). Never null: a step
+   * with no tool carries `next_tool_omitted_reason`. Additive: the class is
+   * not exported from the package index — the published surface is the
+   * `ToolFailure` envelope `tools.ts` builds from these fields — and every
+   * constructor call site is in this file.
+   */
+  next_tool;
+  next_tool_server;
+  next_tool_name;
+  next_tool_server_role;
+  next_arguments;
+  next_tool_omitted_reason;
   retry_with_new_quote;
   /** Present only for `SIGN_CONTEXT_REFUSED` (the backend's HTTP status). */
   http_status;
   /** Present only for `SIGN_CONTEXT_REFUSED`: the backend's own `error_code`. */
   backend_error_code;
-  constructor(message, code, refusal) {
+  constructor(message, code, refusal, paymentId) {
     super(message);
     this.code = code;
     this.name = "HavenSignContextError";
+    let step;
     if (code === "SIGN_CONTEXT_REFUSED") {
       this.http_status = refusal?.httpStatus;
       this.backend_error_code = refusal?.errorCode;
       if (refusal?.httpStatus === 410 || refusal?.errorCode === "expired") {
         this.next_action = AgentPaymentNextAction.PaymentWindowExpired;
         this.retry_with_new_quote = true;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.PaymentWindowExpired,
+          nextTool: null,
+          nextToolOmittedReason: "re-run the hosted quote tool you called with the same idempotency_key; which one depends on the flow"
+        });
       } else {
         this.next_action = AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: AgentPaymentNextAction.StopAndTellUser,
+          nextTool: "haven_get_payment_status",
+          nextArguments: { payment_id: paymentId }
+        });
       }
     } else {
       this.fallback = "typed_data_b64";
       this.next_action = AgentPaymentNextAction.StopAndTellUser;
+      step = signerRefusalStep({
+        nextAction: AgentPaymentNextAction.StopAndTellUser,
+        nextTool: null,
+        nextToolOmittedReason: "re-run the SAME hosted quote tool with the same idempotency_key and include_signing_payload: true, then pass its typed_data_b64 to this signer"
+      });
     }
+    Object.assign(this, nextStepWireFields(step));
   }
 };
 async function loadHavenIdentity(credentialsPath) {
@@ -699,7 +783,9 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
     const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
     throw new HavenSignContextError(
       timedOut ? `Haven did not answer the signing-context fetch for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.` : `Could not reach Haven to fetch the signing context for ${paymentId}: ${err instanceof Error ? err.message : String(err)}. Retry, or pass typed_data_b64 from the quote result instead.`,
-      timedOut ? "SIGN_CONTEXT_TIMEOUT" : "SIGN_CONTEXT_UNREACHABLE"
+      timedOut ? "SIGN_CONTEXT_TIMEOUT" : "SIGN_CONTEXT_UNREACHABLE",
+      void 0,
+      paymentId
     );
   }
   let body;
@@ -709,7 +795,9 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
     if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
       throw new HavenSignContextError(
         `Haven did not finish sending the signing context for ${paymentId} within ${timeoutMs} ms. Retry, or pass typed_data_b64 from the quote result instead.`,
-        "SIGN_CONTEXT_TIMEOUT"
+        "SIGN_CONTEXT_TIMEOUT",
+        void 0,
+        paymentId
       );
     }
     body = {};
@@ -719,7 +807,8 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
     throw new HavenSignContextError(
       `Haven refused the signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 check the payment_id came from this agent\u2019s own quote." : response.status === 410 ? " Re-run the quote with the same idempotency key, then sign the fresh payment_id." : ""),
       "SIGN_CONTEXT_REFUSED",
-      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 }
+      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 },
+      paymentId
     );
   }
   const signData = body.sign_data;
@@ -727,7 +816,9 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
   if (!signData || typeof signData.hash !== "string" || !signData.typed_data || typeof signData.typed_data !== "object" || !x402Expected) {
     throw new HavenSignContextError(
       "The Haven sign-context response is missing sign_data.typed_data or x402_expected \u2014 the backend may predate #1263. Pass typed_data_b64 from the quote result instead.",
-      "SIGN_CONTEXT_MALFORMED"
+      "SIGN_CONTEXT_MALFORMED",
+      void 0,
+      paymentId
     );
   }
   const paymentRequired = body.payment_required;
@@ -741,54 +832,54 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
 }
 
 // src/tools.ts
-var sweepAuthorizationSchema = z.object({
-  from: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
-  to: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
-  value: z.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
-  validAfter: z.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
-  validBefore: z.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
-  nonce: z.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
-  token: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
-  chainId: z.number().int().positive()
+var sweepAuthorizationSchema = z$1.object({
+  from: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "from must be a 0x address"),
+  to: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "to must be a 0x address"),
+  value: z$1.string().regex(/^[0-9]+$/, "value must be a decimal atomic amount"),
+  validAfter: z$1.string().regex(/^[0-9]+$/, "validAfter must be a decimal unix time"),
+  validBefore: z$1.string().regex(/^[0-9]+$/, "validBefore must be a decimal unix time"),
+  nonce: z$1.string().regex(/^0x[0-9a-fA-F]{64}$/, "nonce must be a 0x-prefixed 32-byte hex string"),
+  token: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "token must be a 0x address"),
+  chainId: z$1.number().int().positive()
 });
-var bindingVersionSchema = z.number().int().positive();
-var sweepExpectedAuthSchema = z.object({
+var bindingVersionSchema = z$1.number().int().positive();
+var sweepExpectedAuthSchema = z$1.object({
   version: bindingVersionSchema,
-  message: z.string().min(1),
-  signature: z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-  signer: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
+  message: z$1.string().min(1),
+  signature: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+  signer: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "signer must be a 0x address")
 });
 var x402ExpectedShape = {
-  payment_id: z.string().min(1),
-  payload_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
-  resource_url: z.string().url(),
-  merchant_to: z.string().min(1),
-  amount: z.string().min(1),
-  asset: z.string().min(1),
-  network: z.string().min(1),
+  payment_id: z$1.string().min(1),
+  payload_hash: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string"),
+  resource_url: z$1.string().url(),
+  merchant_to: z$1.string().min(1),
+  amount: z$1.string().min(1),
+  asset: z$1.string().min(1),
+  network: z$1.string().min(1),
   // Required: expires_at is folded into the Haven-signed binding message, so the
   // signer must receive the exact same value to reconstruct a matching message.
   // Omitting it used to fail downstream with a cryptic "authentication message is
   // invalid" — making it required surfaces a clear INVALID_INPUT at the boundary.
-  expires_at: z.string().min(1),
+  expires_at: z$1.string().min(1),
   // #1138: present on a delegation-rail (v2) context. It commits to the EIP-712
   // typed data the account validates; the signer refuses to raw-sign the bare
   // hash when it is present, and refuses to sign typed data when it is absent.
-  typed_data_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "typed_data_hash must be a 0x-prefixed hex string").optional(),
+  typed_data_hash: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "typed_data_hash must be a 0x-prefixed hex string").optional(),
   // #1690: present on a v3 context. The delegate this quote was created FOR —
   // the signer refuses to sign when it is not its own. Inside the Haven-signed
   // message, so stripping it here would only break the binding signature.
-  payer_delegate: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "payer_delegate must be a 0x-prefixed address").optional(),
-  payer_agent_id: z.string().min(1).optional(),
-  auth: z.object({
+  payer_delegate: z$1.string().regex(/^0x[0-9a-fA-F]{40}$/, "payer_delegate must be a 0x-prefixed address").optional(),
+  payer_agent_id: z$1.string().min(1).optional(),
+  auth: z$1.object({
     // Open at the boundary, enforced in the signer — see bindingVersionSchema.
     version: bindingVersionSchema,
-    message: z.string().min(1),
-    signature: z.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
-    signer: z.string().min(1)
+    message: z$1.string().min(1),
+    signature: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "signature must be a 0x-prefixed hex string"),
+    signer: z$1.string().min(1)
   })
 };
-var x402ExpectedSchema = z.object(x402ExpectedShape);
+var x402ExpectedSchema = z$1.object(x402ExpectedShape);
 var toolSchemas = {
   haven_sign_sweep_delegate: {
     // The authorization fields prepared by Haven's POST /sweep/prepare. Passed
@@ -803,17 +894,17 @@ var toolSchemas = {
     // payload + expected context from Haven itself (authenticated with the
     // locally-stored agent credential), so no bulky bytes ever cross the
     // model. Pass payment_id ALONE for a delegation-rail x402 funding intent.
-    payment_id: z.string().min(1).optional(),
+    payment_id: z$1.string().min(1).optional(),
     // The unsigned hash from haven_pay / haven_pay_x402_quote (payload_hash).
     // Optional when payment_id is supplied (the fetch carries it).
-    payload_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
+    payload_hash: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
     // Pass x402.expected from hosted haven_pay_x402_quote when this hash funds
     // a standard x402 merchant retry. The signer records it locally and returns
     // an opaque x402_binding for the later header-signing step.
     x402_expected: x402ExpectedSchema.optional(),
     // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
     // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
-    typed_data: z.record(z.string(), z.unknown()).optional(),
+    typed_data: z$1.record(z$1.string(), z$1.unknown()).optional(),
     // #1255: the same payload as ONE opaque base64 string, exactly as returned
     // by the hosted tools. Preferred over typed_data when both are present —
     // an agent re-emitting multi-KB nested JSON between tool calls is the
@@ -822,35 +913,36 @@ var toolSchemas = {
     // Bounded: a realistic redemption payload is ~10KB encoded; 256KB is
     // generous headroom while keeping the offline signer from materializing
     // arbitrarily large caller input.
-    typed_data_b64: z.string().min(1).max(262144).optional()
+    typed_data_b64: z$1.string().min(1).max(262144).optional()
   },
   haven_x402_sign_header: {
     // The parsed HTTP 402 PaymentRequired from the merchant. Typed as an object
     // (not z.unknown(), which becomes empty JSON Schema `{}`) so MCP clients
     // embed it as JSON rather than serialising the object to a string.
-    payment_required: z.record(z.string(), z.unknown()),
+    payment_required: z$1.record(z$1.string(), z$1.unknown()),
     // Opaque binding returned by haven_sign when x402_expected was supplied.
-    x402_binding: z.string().min(1)
+    x402_binding: z$1.string().min(1)
   },
   haven_sign_x402: {
     // #1263: preferred — pass payment_id (plus payment_required) and the
     // signer fetches the exact signing payload + expected context itself.
-    payment_id: z.string().min(1).optional(),
+    payment_id: z$1.string().min(1).optional(),
     // One-shot x402 signing: funding hash + merchant header in one local call.
     // Both optional when payment_id is supplied (the fetch carries them).
-    payload_hash: z.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
+    payload_hash: z$1.string().regex(/^0x[0-9a-fA-F]+$/, "payload_hash must be a 0x-prefixed hex string").optional(),
     x402_expected: x402ExpectedSchema.optional(),
     // #1355: optional when payment_id is supplied — the signer's context fetch
     // carries the stored 402 PaymentRequired, so `{ payment_id }` alone is the
     // preferred call. Still required (via the runtime check in the handler)
     // for the quote-based fallback path without a payment_id.
-    payment_required: z.record(z.string(), z.unknown()).optional(),
+    payment_required: z$1.record(z$1.string(), z$1.unknown()).optional(),
     // #1138: delegation-rail intents sign THIS, not payload_hash. Object-typed
     // (not z.unknown()) so MCP clients embed it as JSON rather than a string.
-    typed_data: z.record(z.string(), z.unknown()).optional(),
+    typed_data: z$1.record(z$1.string(), z$1.unknown()).optional(),
     // #1255: see haven_sign.typed_data_b64 — the copy-through-safe form.
-    typed_data_b64: z.string().min(1).max(262144).optional()
+    typed_data_b64: z$1.string().min(1).max(262144).optional()
   }
+  // #3101: keys survive on the type (see the hosted server's contracts.ts).
 };
 var SIGN_DESCRIPTION = [
   "Sign an unsigned Haven payment hash with the local delegate key. The delegate key never leaves",
@@ -948,7 +1040,7 @@ function toExpectedX402(raw) {
   };
 }
 function parseFetchedExpected(fetched) {
-  const parsed = z.object(x402ExpectedShape).safeParse(fetched.x402Expected);
+  const parsed = z$1.object(x402ExpectedShape).safeParse(fetched.x402Expected);
   if (!parsed.success) {
     throw new HavenSigningError(
       `The Haven sign-context response carried a malformed x402_expected \u2014 the backend may predate #1263. Pass payload_hash + x402_expected from the quote result instead. Underlying: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`
@@ -1078,7 +1170,7 @@ function createToolHandlers(signer, options = {}) {
         authorization: args.authorization,
         expectedAuth: args.expected_auth,
         // Cross-check `to` against the Safe in the local credential when present.
-        expectedSafe: options.audit?.safeAddress
+        expectedSafe: options.audit?.accountAddress
       });
       await auditSigning(
         "haven_sign_sweep_delegate",
@@ -1100,7 +1192,7 @@ function createToolHandlers(signer, options = {}) {
   }
 }
 function parse(name, input) {
-  return z.object(toolSchemas[name]).parse(input ?? {});
+  return z$1.object(toolSchemas[name]).parse(input ?? {});
 }
 function coerceX402Expected(input) {
   if (!input || typeof input !== "object") return input;
@@ -1139,7 +1231,7 @@ async function runTool(fn) {
   }
 }
 function normalizeError(err) {
-  if (err instanceof z.ZodError) {
+  if (err instanceof z$1.ZodError) {
     return {
       success: false,
       code: "INVALID_INPUT",
@@ -1155,7 +1247,13 @@ function normalizeError(err) {
       supported_versions: [...err.supportedVersions],
       received_version: err.receivedVersion,
       fallback: err.fallback,
-      next_action: AgentPaymentNextAction.StopAndTellUser
+      next_action: AgentPaymentNextAction.StopAndTellUser,
+      // #3103: no tool can fix a version skew from inside the call.
+      ...nextStepWireFields(signerRefusalStep({
+        nextAction: AgentPaymentNextAction.StopAndTellUser,
+        nextTool: null,
+        nextToolOmittedReason: "update @haven_ai/signer by re-running the connector, then repeat the same call"
+      }))
     };
   }
   if (err instanceof HavenSignContextError) {
@@ -1167,7 +1265,14 @@ function normalizeError(err) {
       ...err.fallback !== void 0 ? { fallback: err.fallback } : {},
       ...err.retry_with_new_quote ? { retry_with_new_quote: true } : {},
       ...err.http_status !== void 0 ? { http_status: err.http_status } : {},
-      ...err.backend_error_code !== void 0 ? { backend_error_code: err.backend_error_code } : {}
+      ...err.backend_error_code !== void 0 ? { backend_error_code: err.backend_error_code } : {},
+      // #3103: the typed step the error decided beside its action.
+      ...err.next_tool ? { next_tool: err.next_tool } : {},
+      ...err.next_tool_server ? { next_tool_server: err.next_tool_server } : {},
+      ...err.next_tool_name ? { next_tool_name: err.next_tool_name } : {},
+      ...err.next_tool_server_role ? { next_tool_server_role: err.next_tool_server_role } : {},
+      ...err.next_arguments ? { next_arguments: err.next_arguments } : {},
+      ...err.next_tool_omitted_reason ? { next_tool_omitted_reason: err.next_tool_omitted_reason } : {}
     };
   }
   if (err instanceof HavenSigningError) {
@@ -1186,7 +1291,13 @@ function normalizeError(err) {
       ...err.code === AgentPaymentFailureCode.PaymentWindowExpired ? {
         next_action: AgentPaymentNextAction.PaymentWindowExpired,
         retry_with_new_quote: true,
-        suggested_tool: "haven_pay_mcp_tool"
+        suggested_tool: "haven_pay_mcp_tool",
+        // #3103: same omission as the hosted window-expired helper.
+        ...nextStepWireFields(signerRefusalStep({
+          nextAction: AgentPaymentNextAction.PaymentWindowExpired,
+          nextTool: null,
+          nextToolOmittedReason: "re-run the hosted quote tool you called with the same idempotency_key; which one depends on the flow (suggested_tool names the MCP one)"
+        }))
       } : {}
     };
   }
@@ -1203,7 +1314,7 @@ var SIGNER_CONSENT_SURFACE_VERSION = 2;
 function computeSignerConsentHash(input) {
   const identity = [
     input.delegateAddress.toLowerCase(),
-    (input.safeAddress ?? "").toLowerCase(),
+    (input.accountAddress ?? "").toLowerCase(),
     input.agentId ?? "",
     input.chainId ?? "",
     input.network ?? ""
@@ -1222,7 +1333,7 @@ function renderSignerConsentBlock(input, hash) {
     "",
     `Delegate address: ${input.delegateAddress}`
   ];
-  lines.push(`Haven wallet:     ${input.safeAddress ?? "not provided to this signer"}`);
+  lines.push(`Haven wallet:     ${input.accountAddress ?? "not provided to this signer"}`);
   if (input.agentId) lines.push(`Agent ID:         ${input.agentId}`);
   if (typeof input.chainId === "number") lines.push(`Chain ID:         ${input.chainId}`);
   if (input.network) lines.push(`Network:          ${input.network}`);
@@ -1316,7 +1427,7 @@ async function writeAckFile(path, hash) {
   );
 }
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.2.1-alpha.0";
+var SIGNER_VERSION = "0.4.0-alpha.0";
 async function resolveEdgeSigner(options = {}) {
   const { signer } = await resolveSignerRuntime(options);
   return signer;
@@ -1355,7 +1466,7 @@ function buildSignerMcpServer(signer, options = {}) {
     audit: {
       auditPath: options.auditPath ?? defaultSigningAuditPath(credentialsPath),
       delegateAddress: signer.delegateAddress,
-      safeAddress: options.credentials?.accountAddress ?? options.credentials?.safeAddress,
+      accountAddress: options.credentials?.accountAddress,
       chainId: options.credentials?.chainId
     },
     // #1263: the payment_id signing path — the ONLY network call this server
@@ -1405,7 +1516,7 @@ async function runSignerConsentGate(signer, credentials, options) {
   return ensureSignerConsent(
     {
       delegateAddress: signer.delegateAddress,
-      safeAddress: credentials?.accountAddress ?? credentials?.safeAddress,
+      accountAddress: credentials?.accountAddress,
       agentId: credentials?.agentId,
       chainId: credentials?.chainId,
       network: credentials?.network,
@@ -1426,6 +1537,6 @@ function toMcpResult(payload) {
   };
 }
 
-export { SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, appendSigningAuditEntry, assertSupportedBindingVersion, assertSupportedNodeVersion, assertX402MatchesExpected, buildSignerMcpServer, computeSignerConsentHash, createEdgeSigner, createSigningAuditEntry, createToolHandlers, defaultSigningAuditPath, ensureSignerConsent, hashPayloadForAudit, loadSignerCredentials, readAccountAddressEnv, readAccountAddressField, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive };
+export { SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_HOSTED_HANDOFF_SHAPES, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, appendSigningAuditEntry, assertSupportedBindingVersion, assertSupportedNodeVersion, assertX402MatchesExpected, buildSignerMcpServer, computeSignerConsentHash, createEdgeSigner, createSigningAuditEntry, createToolHandlers, defaultSigningAuditPath, ensureSignerConsent, hashPayloadForAudit, loadSignerCredentials, readAccountAddressEnv, readAccountAddressField, renderSignerConsentBlock, resolveEdgeSigner, resolveSignerRuntime, runSignerConsentGate, runSignerStdioServer, signerCapabilityAdvertisement, signerCompatibility, signerInstructions, toolDescriptions, toolSchemas, warnIfCredentialFilePermissive };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map