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

package/dist/cli.js

@@ -5,11 +5,12 @@ import { randomUUID, createHash } from 'crypto';
 import { readFile, mkdir, writeFile, stat, appendFile } from 'fs/promises';
 import { homedir } from 'os';
 import { resolve, dirname, join } from 'path';
-import { isSupportedNodeVersion, unsupportedNodeVersionMessage, addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, connectorRerunCommand, buildSweepAuthorizationMessage, verifySignature, HavenError, AgentPaymentFailureCode, x402AuthorizationAmount, buildX402ExpectedMessage, signHash, SignerRefusalCode, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, AgentPaymentNextAction } from '@haven_ai/sdk';
+import { createNextStepBuilder, isSupportedNodeVersion, unsupportedNodeVersionMessage, addressFromKey, HavenSigningError, buildSweepTypedData, selectStandardPaymentOption, HavenApiError, toStandardPaymentRequirements, decodeBase64Json, encodeBase64Json, x402V2PaymentEnvelope, connectorRerunCommand, buildSweepAuthorizationMessage, verifySignature, HavenError, AgentPaymentFailureCode, x402AuthorizationAmount, buildX402ExpectedMessage, signHash, SignerRefusalCode, SIGNER_UPDATE_FALLBACK, HavenUnsupportedSignerVersionError, AgentPaymentNextAction } from '@haven_ai/sdk';
 import { recoverTypedDataAddress, hashTypedData, hashMessage } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 import { exact } from 'x402/schemes';
-import { z } from 'zod/v3';
+import { z as z$1 } from 'zod/v3';
+import { z } from 'zod';
 
 function defaultSigningAuditPath(credentialsPath) {
   if (credentialsPath) return resolve(`${credentialsPath}.signer-audit.jsonl`);
@@ -529,9 +530,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: 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
@@ -551,28 +587,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) {
@@ -604,7 +675,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;
@@ -614,7 +687,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 = {};
@@ -624,7 +699,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;
@@ -632,7 +708,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;
@@ -646,54 +724,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
@@ -708,17 +786,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
@@ -727,35 +805,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",
@@ -853,7 +932,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"}`
@@ -1005,7 +1084,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;
@@ -1044,7 +1123,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",
@@ -1060,7 +1139,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) {
@@ -1072,7 +1157,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) {
@@ -1091,7 +1183,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)"
+        }))
       } : {}
     };
   }
@@ -1333,7 +1431,7 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.3.0-alpha.0";
+var SIGNER_VERSION = "0.4.0-alpha.0";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {