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

package/README.md

@@ -180,15 +180,17 @@ what a payload means; they re-derive it.
   allowed — top-level caveats are AND-ed during redemption, so an unrecognised
   one can only add a constraint.
 - **A binding version it does not understand.** The refusal is machine-readable
-  — `code`, `supported_versions`, `received_version`, `fallback` — and names
-  updating the signer as the fix.
+  — `code`, `supported_versions`, `received_version`, `fallback`, and (#3103)
+  `next_tool_omitted_reason` — and names updating the signer as the fix.
 - **A sweep that does not move funds out of this delegate's own key** — the
   `from` check is unconditional. The **destination** check is not, and this is
   the one asymmetry in this list: the signer compares the sweep's `to` against
   the account address **only when the local credential records one**
   (`account_address`, or the pre-#2908 `safe_address` / `safeAddress`, which
-  are read permanently; from the environment, `HAVEN_ACCOUNT_ADDRESS`, or the
-  older `HAVEN_WALLET_ADDRESS` / `HAVEN_SAFE_ADDRESS` until #2914). Run with
+  are read permanently; from the environment, `HAVEN_ACCOUNT_ADDRESS` only —
+  `HAVEN_WALLET_ADDRESS` and `HAVEN_SAFE_ADDRESS` were removed by #2914, so a
+  machine still configured through either records no account address and lands
+  in exactly the degraded case this paragraph describes). Run with
   `HAVEN_DELEGATE_KEY` alone — or with a credential
   whose account address is absent — and there is no local value to compare
   against, so the destination is authenticated by Haven's binding signature and
@@ -204,7 +206,12 @@ signing payload from Haven (`GET /x402/:id/sign-context`, see
 still holds everywhere it did before, but structured like the version-mismatch
 refusal below rather than prose alone: `code`, `next_action`, and — per
 refusal class — `fallback`, `retry_with_new_quote`, `http_status`,
-`backend_error_code`. `message` is unchanged.
+`backend_error_code`. Since #3103 each also carries a typed next step: the
+`SIGN_CONTEXT_REFUSED` (other) row names the hosted status read
+(`next_tool_server_role: hosted`, `next_tool_name: haven_get_payment_status`,
+`next_arguments: { payment_id }` — resolve the role against your own server
+names); every other row carries `next_tool_omitted_reason` with the exact
+remedy. `message` is unchanged.
 
 | `code` | When | `next_action` | `fallback` | extra |
 |---|---|---|---|---|

package/dist/cli.cjs

@@ -12,6 +12,7 @@ var viem = require('viem');
 var accounts = require('viem/accounts');
 var schemes = require('x402/schemes');
 var v3 = require('zod/v3');
+var zod = require('zod');
 
 function defaultSigningAuditPath(credentialsPath) {
   if (credentialsPath) return path.resolve(`${credentialsPath}.signer-audit.jsonl`);
@@ -30,7 +31,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;
 }
@@ -531,9 +532,44 @@ 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");
 }
+var SIGNER_HOSTED_HANDOFF_SHAPES = {
+  haven_get_payment_status: { payment_id: zod.z.string().min(1) }
+};
+function target(shape) {
+  const schema = zod.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 = sdk.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 sdk.HavenSigningError {
   /**
    * #3001 / #3010 review: the recovery path, when signing OTHER bytes is
@@ -553,28 +589,63 @@ var HavenSignContextError = class extends sdk.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 = sdk.AgentPaymentNextAction.PaymentWindowExpired;
         this.retry_with_new_quote = true;
+        step = signerRefusalStep({
+          nextAction: sdk.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 = sdk.AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: sdk.AgentPaymentNextAction.StopAndTellUser,
+          nextTool: "haven_get_payment_status",
+          nextArguments: { payment_id: paymentId }
+        });
       }
     } else {
       this.fallback = "typed_data_b64";
       this.next_action = sdk.AgentPaymentNextAction.StopAndTellUser;
+      step = signerRefusalStep({
+        nextAction: sdk.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) {
@@ -606,7 +677,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;
@@ -616,7 +689,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 = {};
@@ -626,7 +701,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;
@@ -634,7 +710,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;
@@ -758,6 +836,7 @@ var toolSchemas = {
     // #1255: see haven_sign.typed_data_b64 — the copy-through-safe form.
     typed_data_b64: v3.z.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",
@@ -985,7 +1064,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",
@@ -1062,7 +1141,13 @@ function normalizeError(err) {
       supported_versions: [...err.supportedVersions],
       received_version: err.receivedVersion,
       fallback: err.fallback,
-      next_action: sdk.AgentPaymentNextAction.StopAndTellUser
+      next_action: sdk.AgentPaymentNextAction.StopAndTellUser,
+      // #3103: no tool can fix a version skew from inside the call.
+      ...nextStepWireFields(signerRefusalStep({
+        nextAction: sdk.AgentPaymentNextAction.StopAndTellUser,
+        nextTool: null,
+        nextToolOmittedReason: "update @haven_ai/signer by re-running the connector, then repeat the same call"
+      }))
     };
   }
   if (err instanceof HavenSignContextError) {
@@ -1074,7 +1159,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 sdk.HavenSigningError) {
@@ -1093,7 +1185,13 @@ function normalizeError(err) {
       ...err.code === sdk.AgentPaymentFailureCode.PaymentWindowExpired ? {
         next_action: sdk.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: sdk.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)"
+        }))
       } : {}
     };
   }
@@ -1110,7 +1208,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 ?? ""
@@ -1129,7 +1227,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}`);
@@ -1231,7 +1329,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)
@@ -1266,7 +1363,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(
@@ -1279,7 +1375,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;
@@ -1322,7 +1433,7 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.2.1-alpha.0";
+var SIGNER_VERSION = "0.4.0-alpha.0";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {
@@ -1357,7 +1468,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
@@ -1407,7 +1518,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,