@haven_ai/signer 0.0.0-dev.202609250737.3bd5a51 → 0.0.0-dev.202609251409.98ed67a

package/README.md

@@ -335,6 +335,7 @@ carries no x402 context to fund a merchant retry with, so it surfaces the
 | `SIGN_CONTEXT_MALFORMED` | The response body was missing `sign_data.typed_data` / `x402_expected` (a pre-#1263 backend), or — on the direct-payment fetch — an unsupported `direct_sign_context_version` or a `signature_scheme` other than `eip712_userop` | `stop_and_tell_user` | `typed_data_b64` | — |
 | `SIGN_CONTEXT_REFUSED` (x402: 410 or `expired`; direct: `expired` only) | x402: the quote's window closed. Direct: the payment's window closed — call `haven_send` / `haven_pay` again with the same `idempotency_key` | `payment_window_expired` | — | x402 only: `retry_with_new_quote: true`; both: `http_status`, and `backend_error_code: 'expired'` when the backend sent one |
 | `SIGN_CONTEXT_REFUSED` (404, direct fetch) | The `payment_id` is not this agent's, or the backend predates #3271 and has no direct route | `stop_and_tell_user` | `typed_data_b64` | `http_status`, `backend_error_code` |
+| `SIGN_CONTEXT_REFUSED` (426 `client_outdated`, #3303) | This signer is below the minimum version the Haven deployment has set (only when one is set). Nothing is signed; the prepared payment is left unsigned. Update with `client_update.upgrade_command`, restart the agent runtime, then retry the same call | `stop_and_tell_user` | — | `http_status: 426`, `backend_error_code: 'client_outdated'`, `client_update` (the update command as data); carries `next_tool_omitted_reason`, not the status read |
 | `SIGN_CONTEXT_REFUSED` (other) | Unknown `payment_id` (404, x402 fetch), `already_executed` / `not_signable` (409), a bare 410 retired-rail tombstone (direct fetch) — or `sign_context_unavailable` (409): always on `haven_sign_x402`; on `haven_sign` only when neither route can serve the row | `stop_and_tell_user` | — | `http_status`, `backend_error_code` |
 | `USEROP_BINDING_MISMATCH` | A direct payment's `PackedUserOperation` typed data (from the direct fetch, or a tool argument) does not recompute to its own `payload_hash`, or a fetched direct context is not a `PackedUserOperation` — see [Two ways to use it](#two-ways-to-use-it) above | `stop_and_tell_user` | — | no `http_status` — this is a local recomputation, not a backend refusal |
 | `TYPED_DATA_NOT_ALLOWED` | Typed data without an x402 context that is not a bound direct-payment `PackedUserOperation` (#3272): wrong chain, not this signer's own account, a call other than `execute` → DelegationManager → `redeemDelegations`, or a redemption whose delegations are empty, not made to this account, or in a non-default mode — see the allowlist paragraph above. Reachable by `payment_id` when Haven serves such a payload | `stop_and_tell_user` | — | no `http_status` — a local shape check, not a backend refusal |

package/dist/cli.cjs

@@ -211,6 +211,12 @@ var HavenSignContextError = class extends edge.HavenSigningError {
   http_status;
   /** Present only for `SIGN_CONTEXT_REFUSED`: the backend's own `error_code`. */
   backend_error_code;
+  /**
+   * #3303: on a 426 `client_outdated` refusal, the backend's update hint —
+   * this signer is below the minimum the deployment set, and
+   * `client_update.upgrade_command` is what updates it.
+   */
+  client_update;
   constructor(message, code, refusal, paymentId, flow = "x402") {
     super(message);
     this.code = code;
@@ -219,7 +225,15 @@ var HavenSignContextError = class extends edge.HavenSigningError {
     if (code === "SIGN_CONTEXT_REFUSED") {
       this.http_status = refusal?.httpStatus;
       this.backend_error_code = refusal?.errorCode;
-      if (flow === "direct" && refusal?.httpStatus === 404) {
+      if (refusal?.errorCode === "client_outdated") {
+        this.client_update = refusal.clientUpdate;
+        this.next_action = edge.AgentPaymentNextAction.StopAndTellUser;
+        step = signerRefusalStep({
+          nextAction: edge.AgentPaymentNextAction.StopAndTellUser,
+          nextTool: null,
+          nextToolOmittedReason: `this signer is below the minimum version Haven accepts \u2014 tell the user to run ${refusal.clientUpdate?.upgrade_command ?? "the connector again"}, restart the agent runtime, then retry the same haven_sign / haven_sign_x402 call`
+        });
+      } else if (flow === "direct" && refusal?.httpStatus === 404) {
         this.fallback = "typed_data_b64";
         this.next_action = edge.AgentPaymentNextAction.StopAndTellUser;
         step = signerRefusalStep({
@@ -277,13 +291,26 @@ async function loadHavenIdentity(credentialsPath) {
   }
 }
 var SIGN_CONTEXT_TIMEOUT_MS = 15e3;
-async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS) {
+function signContextHeaders(identity, clientIdentity) {
+  return {
+    Authorization: `Bearer ${identity.apiKey}`,
+    ...clientIdentity ? { [edge.HAVEN_CLIENT_HEADER]: clientIdentity } : {}
+  };
+}
+function refusalOf(status, body) {
+  return {
+    httpStatus: status,
+    errorCode: typeof body.error_code === "string" ? body.error_code : void 0,
+    clientUpdate: edge.readClientUpdate(body.client_update)
+  };
+}
+async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS, clientIdentity) {
   let response;
   try {
     response = await fetchImpl(
       `${identity.apiUrl}/x402/${encodeURIComponent(paymentId)}/sign-context`,
       {
-        headers: { Authorization: `Bearer ${identity.apiKey}` },
+        headers: signContextHeaders(identity, clientIdentity),
         signal: AbortSignal.timeout(timeoutMs)
       }
     );
@@ -315,7 +342,7 @@ 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 },
+      refusalOf(response.status, body),
       paymentId
     );
   }
@@ -335,17 +362,18 @@ async function fetchX402SignContext(identity, paymentId, fetchImpl = fetch, time
     payloadHash: signData.hash,
     typedData: signData.typed_data,
     x402Expected,
-    paymentRequired: paymentRequired && typeof paymentRequired === "object" && !Array.isArray(paymentRequired) ? paymentRequired : null
+    paymentRequired: paymentRequired && typeof paymentRequired === "object" && !Array.isArray(paymentRequired) ? paymentRequired : null,
+    clientUpdate: edge.readClientUpdate(body.client_update)
   };
 }
 var SUPPORTED_DIRECT_SIGN_CONTEXT_VERSIONS = [edge.DIRECT_SIGN_CONTEXT_VERSION];
-async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS) {
+async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, timeoutMs = SIGN_CONTEXT_TIMEOUT_MS, clientIdentity) {
   let response;
   try {
     response = await fetchImpl(
       `${identity.apiUrl}/payments/${encodeURIComponent(paymentId)}/sign-context`,
       {
-        headers: { Authorization: `Bearer ${identity.apiKey}` },
+        headers: signContextHeaders(identity, clientIdentity),
         signal: AbortSignal.timeout(timeoutMs)
       }
     );
@@ -379,7 +407,7 @@ async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, ti
     throw new HavenSignContextError(
       `Haven refused the direct-payment signing-context fetch for ${paymentId}: ${detail}` + (response.status === 404 ? " \u2014 either the payment_id is not from this agent\u2019s own POST /payments call, or this Haven backend predates #3271. Pass payload_hash and typed_data_b64 from the haven_send / haven_pay result, unchanged, instead." : body.error_code === "expired" ? " The payment window has expired; call haven_send / haven_pay again with the same idempotency_key." : ""),
       "SIGN_CONTEXT_REFUSED",
-      { httpStatus: response.status, errorCode: typeof body.error_code === "string" ? body.error_code : void 0 },
+      refusalOf(response.status, body),
       paymentId,
       "direct"
     );
@@ -400,7 +428,8 @@ async function fetchDirectSignContext(identity, paymentId, fetchImpl = fetch, ti
     payloadHash: signData.hash,
     typedData: signData.typed_data,
     status: typeof body.status === "string" ? body.status : "pending_signature",
-    expiresAt: typeof body.expires_at === "string" ? body.expires_at : void 0
+    expiresAt: typeof body.expires_at === "string" ? body.expires_at : void 0,
+    clientUpdate: edge.readClientUpdate(body.client_update)
   };
 }
 
@@ -671,6 +700,9 @@ function parseFetchedExpected(fetched) {
   }
   return parsed.data;
 }
+function clientUpdateField(resolved) {
+  return resolved?.ctx.clientUpdate ? { client_update: resolved.ctx.clientUpdate } : {};
+}
 function resolveTypedData(args) {
   if (!args.typed_data_b64) return args.typed_data;
   try {
@@ -704,14 +736,26 @@ function createToolHandlers(signer, options = {}) {
       );
     }
     try {
-      const ctx = await fetchX402SignContext(identity, args.payment_id, options.signContext?.fetchImpl);
+      const ctx = await fetchX402SignContext(
+        identity,
+        args.payment_id,
+        options.signContext?.fetchImpl,
+        void 0,
+        options.signContext?.clientIdentity
+      );
       checkPayloadHashMatch(args.payload_hash, ctx.payloadHash, args.payment_id);
       return { kind: "x402", ctx };
     } catch (err) {
       if (opts.allowDirectFallback && err instanceof HavenSignContextError && err.http_status === 409 && err.backend_error_code === "sign_context_unavailable") {
         let ctx;
         try {
-          ctx = await fetchDirectSignContext(identity, args.payment_id, options.signContext?.fetchImpl);
+          ctx = await fetchDirectSignContext(
+            identity,
+            args.payment_id,
+            options.signContext?.fetchImpl,
+            void 0,
+            options.signContext?.clientIdentity
+          );
         } catch (directErr) {
           if (directErr instanceof HavenSignContextError && directErr.http_status === 409 && directErr.backend_error_code === "sign_context_unavailable") {
             throw err;
@@ -761,12 +805,12 @@ function createToolHandlers(signer, options = {}) {
           assertBoundDirectPaymentUserOp(typedData, signer.delegateAddress);
           const signature = await signer.signDelegationTypedData(typedData);
           await auditSigning("haven_sign", viem.hashTypedData(typedData));
-          return { signature };
+          return { signature, ...clientUpdateField(resolved) };
         }
         throw new HavenBareHashRefusedError();
       }
       await auditSigning("haven_sign", viem.hashTypedData(typedData));
-      return { signature: result.signature, x402_binding: result.x402Binding };
+      return { signature: result.signature, x402_binding: result.x402Binding, ...clientUpdateField(resolved) };
     }),
     haven_x402_sign_header: async (input) => runTool(async () => {
       const args = parse("haven_x402_sign_header", coercePaymentRequired(input));
@@ -812,7 +856,8 @@ function createToolHandlers(signer, options = {}) {
         signature: funding.signature,
         x402_binding: funding.x402Binding,
         payment_header: header.paymentHeader,
-        accepted: header.accepted
+        accepted: header.accepted,
+        ...clientUpdateField(resolved)
       };
     }),
     haven_sign_sweep_delegate: async (input) => runTool(async () => {
@@ -951,6 +996,7 @@ function normalizeError(err) {
       ...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.client_update ? { client_update: err.client_update } : {},
       // #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 } : {},
@@ -1663,7 +1709,7 @@ async function warnIfCredentialFilePermissive(path, log = (message) => process.s
 
 // src/server.ts
 var SIGNER_NAME = "@haven_ai/signer";
-var SIGNER_VERSION = "0.0.0-dev.202609250737.3bd5a51";
+var SIGNER_VERSION = "0.0.0-dev.202609251409.98ed67a";
 async function resolveSignerRuntime(options = {}) {
   assertSupportedNodeVersion(options.nodeVersion);
   if (options.delegateKey) {
@@ -1708,7 +1754,10 @@ function buildSignerMcpServer(signer, options = {}) {
     // The signer CORE stays network-free; fetched bytes still pass the same
     // binding verification + digest re-derivation as tool-argument bytes.
     signContext: {
-      loadIdentity: () => loadHavenIdentity(credentialsPath)
+      loadIdentity: () => loadHavenIdentity(credentialsPath),
+      // #3303: the backend refuses a signer below a minimum it has set, at
+      // sign-context — the one place this signer meets it.
+      clientIdentity: edge.havenClientIdentity(SIGNER_NAME, SIGNER_VERSION)
     }
   });
   const registerTool = server.tool.bind(server);