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

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth } from '@haven_ai/sdk';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod/v3';
+import { z as z$1 } from 'zod';
 
 /**
  * The edge signer core.
@@ -282,18 +283,8 @@ declare function signerInstructions(): string;
 interface SignerCredentials {
     delegateKey: string;
     agentId?: string;
-    /**
-     * The Haven account (smart account) the agent spends from — #2908, the
-     * account-vocabulary name. Same value as `safeAddress`.
-     */
+    /** The Haven account (smart account) the agent spends from. */
     accountAddress?: string;
-    /**
-     * @deprecated #2908 — same value as {@link SignerCredentials.accountAddress}.
-     * Removed from this shape in the release after the one carrying #2908
-     * (#2914). The credential-FILE keys it was read from are a different
-     * matter — see `readAccountAddressField`.
-     */
-    safeAddress?: string;
     chainId?: number;
     network?: string;
     x402BindingSigner?: string;
@@ -305,11 +296,11 @@ interface RawCredentialFile {
     delegateKey?: unknown;
     agent_id?: unknown;
     agentId?: unknown;
-    /** #2908: what `@haven_ai/connect` writes from this release on. */
+    /** What `@haven_ai/connect` writes. */
     account_address?: unknown;
-    /** Pre-#2908 spelling — read PERMANENTLY, see `readAccountAddressField`. */
+    /** Pre-#2908 spelling — read PERMANENTLY (a credential file never rewrites itself), see `readAccountAddressField`. */
     safe_address?: unknown;
-    /** Pre-#2908 spelling — read PERMANENTLY, see `readAccountAddressField`. */
+    /** Pre-#2908 spelling — read PERMANENTLY (a credential file never rewrites itself), see `readAccountAddressField`. */
     safeAddress?: unknown;
     chain_id?: unknown;
     chainId?: unknown;
@@ -346,11 +337,11 @@ declare function loadSignerCredentials(path?: string | undefined): Promise<Signe
  */
 declare function readAccountAddressField(raw: Pick<RawCredentialFile, 'account_address' | 'safe_address' | 'safeAddress'>): string | undefined;
 /**
- * The account address off the process environment, new name first:
- * `HAVEN_ACCOUNT_ADDRESS` (the survivor, decided on #2906) then the two
- * names the dashboard handoff emitted before #2908 — `HAVEN_WALLET_ADDRESS`
- * and `HAVEN_SAFE_ADDRESS`. Unlike the file fallbacks these two ARE
- * window-scoped: they are dropped at #2914, one release after this one.
+ * The account address off the process environment: `HAVEN_ACCOUNT_ADDRESS`
+ * (the survivor, decided on #2906). The two names the dashboard handoff
+ * emitted before #2908 — `HAVEN_WALLET_ADDRESS` and `HAVEN_SAFE_ADDRESS` —
+ * were window-scoped (unlike the credential-FILE fallbacks) and are retired
+ * as of #2914.
  */
 declare function readAccountAddressEnv(env: NodeJS.ProcessEnv): string | undefined;
 /**
@@ -368,12 +359,20 @@ interface SigningAuditEntry {
     tool: SignerToolName;
     payload_hash: string;
     delegate_address: string;
+    /**
+     * Serialized key kept as `safe_address` deliberately (#2914 review): this
+     * is a persisted JSONL field, and an audit log written by an earlier
+     * release never rewrites itself — renaming the key here would fork the
+     * format mid-file. `SigningAuditContext.accountAddress` (the in-memory
+     * field this is built from) carries the account-vocabulary name; only the
+     * on-disk spelling stays put.
+     */
     safe_address?: string;
     chain_id?: number;
 }
 interface SigningAuditContext {
     delegateAddress: string;
-    safeAddress?: string;
+    accountAddress?: string;
     chainId?: number;
     auditPath?: string;
 }
@@ -393,7 +392,201 @@ interface HavenIdentity {
  * they never call the Haven API and never emit the key.
  */
 type SignerToolName = 'haven_sign' | 'haven_x402_sign_header' | 'haven_sign_x402' | 'haven_sign_sweep_delegate';
-declare const toolSchemas: Record<SignerToolName, z.ZodRawShape>;
+declare const toolSchemas: {
+    readonly haven_sign_sweep_delegate: {
+        readonly authorization: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            value: z.ZodString;
+            validAfter: z.ZodString;
+            validBefore: z.ZodString;
+            nonce: z.ZodString;
+            token: z.ZodString;
+            chainId: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            chainId: number;
+            to: string;
+            from: string;
+            nonce: string;
+            value: string;
+            token: string;
+            validAfter: string;
+            validBefore: string;
+        }, {
+            chainId: number;
+            to: string;
+            from: string;
+            nonce: string;
+            value: string;
+            token: string;
+            validAfter: string;
+            validBefore: string;
+        }>;
+        readonly expected_auth: z.ZodObject<{
+            version: z.ZodNumber;
+            message: z.ZodString;
+            signature: z.ZodString;
+            signer: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            message: string;
+            version: number;
+            signature: string;
+            signer: string;
+        }, {
+            message: string;
+            version: number;
+            signature: string;
+            signer: string;
+        }>;
+    };
+    readonly haven_sign: {
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly payload_hash: z.ZodOptional<z.ZodString>;
+        readonly x402_expected: z.ZodOptional<z.ZodObject<{
+            payment_id: z.ZodString;
+            payload_hash: z.ZodString;
+            resource_url: z.ZodString;
+            merchant_to: z.ZodString;
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodString;
+            expires_at: z.ZodString;
+            typed_data_hash: z.ZodOptional<z.ZodString>;
+            payer_delegate: z.ZodOptional<z.ZodString>;
+            payer_agent_id: z.ZodOptional<z.ZodString>;
+            auth: z.ZodObject<{
+                version: z.ZodNumber;
+                message: z.ZodString;
+                signature: z.ZodString;
+                signer: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }>>;
+        readonly typed_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly typed_data_b64: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_x402_sign_header: {
+        readonly payment_required: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        readonly x402_binding: z.ZodString;
+    };
+    readonly haven_sign_x402: {
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly payload_hash: z.ZodOptional<z.ZodString>;
+        readonly x402_expected: z.ZodOptional<z.ZodObject<{
+            payment_id: z.ZodString;
+            payload_hash: z.ZodString;
+            resource_url: z.ZodString;
+            merchant_to: z.ZodString;
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodString;
+            expires_at: z.ZodString;
+            typed_data_hash: z.ZodOptional<z.ZodString>;
+            payer_delegate: z.ZodOptional<z.ZodString>;
+            payer_agent_id: z.ZodOptional<z.ZodString>;
+            auth: z.ZodObject<{
+                version: z.ZodNumber;
+                message: z.ZodString;
+                signature: z.ZodString;
+                signer: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }>>;
+        readonly payment_required: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly typed_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly typed_data_b64: z.ZodOptional<z.ZodString>;
+    };
+};
 declare const toolDescriptions: Record<SignerToolName, string>;
 interface ToolSuccess<T> {
     success: true;
@@ -408,6 +601,13 @@ interface ToolFailure {
     next_action?: string;
     retry_with_new_quote?: boolean;
     suggested_tool?: string;
+    /** #3101 (epic #3105, decision 7): the typed next-step family, additive; `next_tool` never null. */
+    next_tool?: string;
+    next_tool_server?: string;
+    next_tool_name?: string;
+    next_tool_server_role?: 'hosted' | 'signer';
+    next_arguments?: Record<string, unknown>;
+    next_tool_omitted_reason?: string;
     /**
      * #1309: present on `UNSUPPORTED_EXPECTED_CONTEXT_VERSION` /
      * `UNSUPPORTED_SWEEP_BINDING_VERSION` refusals — the exact version set this
@@ -451,7 +651,7 @@ declare function createToolHandlers(signer: EdgeSigner, options?: ToolHandlerOpt
 
 interface SignerConsentInput {
     delegateAddress: string;
-    safeAddress?: string;
+    accountAddress?: string;
     agentId?: string;
     chainId?: number;
     network?: string;
@@ -476,7 +676,7 @@ declare function renderSignerConsentBlock(input: SignerConsentInput, hash: strin
 declare function ensureSignerConsent(input: SignerConsentInput, options?: SignerConsentOptions): Promise<SignerConsentDecision>;
 
 declare const SIGNER_NAME = "@haven_ai/signer";
-declare const SIGNER_VERSION = "0.2.1-alpha.0";
+declare const SIGNER_VERSION = "0.4.0-alpha.0";
 interface SignerOptions {
     /** Path to a Haven credential JSON file (delegate_key is read from it). */
     credentialsPath?: string;
@@ -541,4 +741,24 @@ declare function assertSupportedNodeVersion(nodeVersion?: string): void;
 declare function runSignerStdioServer(options?: SignerOptions): Promise<void>;
 declare function runSignerConsentGate(signer: EdgeSigner, credentials: SignerCredentials | undefined, options: SignerOptions): Promise<SignerConsentDecision>;
 
-export { type EdgeSigner, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, type SignerCompatibility, type SignerConsentDecision, type SignerConsentInput, type SignerConsentOptions, type SignerCredentials, type SignerOptions, type SignerToolName, type SigningAuditContext, type SigningAuditEntry, type ToolFailure, type ToolPayload, type ToolSuccess, type X402ExpectedPayment, type X402FundingSignatureResult, type X402HeaderResult, 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 };
+/**
+ * #3103 (epic #3105, slice 4/5): the signer's typed next step.
+ *
+ * The signer decides a `next_action` on its refusals and, until this module,
+ * never said which tool to call. It cannot know the client's server names
+ * (#2550), so the handoff is expressed through the role fields the SDK
+ * builder renders — `next_tool_server_role: hosted`, `next_tool_name` — from
+ * a bare tool name. The signer must not import the hosted server (it is an
+ * npm package installed on user machines; the hosted server is a Docker
+ * deployment), so the hosted tools it hands off to are DECLARED here as the
+ * argument shape the signer actually emits, and `next-step-signer-parity`
+ * in the hosted server's own suite pins them to the hosted schemas at test
+ * time — the mirror of how the hosted server declares the signer's shapes.
+ */
+declare const SIGNER_HOSTED_HANDOFF_SHAPES: {
+    readonly haven_get_payment_status: {
+        readonly payment_id: z$1.ZodString;
+    };
+};
+
+export { type EdgeSigner, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_HOSTED_HANDOFF_SHAPES, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, type SignerCompatibility, type SignerConsentDecision, type SignerConsentInput, type SignerConsentOptions, type SignerCredentials, type SignerOptions, type SignerToolName, type SigningAuditContext, type SigningAuditEntry, type ToolFailure, type ToolPayload, type ToolSuccess, type X402ExpectedPayment, type X402FundingSignatureResult, type X402HeaderResult, 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 };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { X402ExpectedAuth, X402PaymentRequired, X402PaymentOption, SweepAuthorization, SweepExpectedAuth } from '@haven_ai/sdk';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod/v3';
+import { z as z$1 } from 'zod';
 
 /**
  * The edge signer core.
@@ -282,18 +283,8 @@ declare function signerInstructions(): string;
 interface SignerCredentials {
     delegateKey: string;
     agentId?: string;
-    /**
-     * The Haven account (smart account) the agent spends from — #2908, the
-     * account-vocabulary name. Same value as `safeAddress`.
-     */
+    /** The Haven account (smart account) the agent spends from. */
     accountAddress?: string;
-    /**
-     * @deprecated #2908 — same value as {@link SignerCredentials.accountAddress}.
-     * Removed from this shape in the release after the one carrying #2908
-     * (#2914). The credential-FILE keys it was read from are a different
-     * matter — see `readAccountAddressField`.
-     */
-    safeAddress?: string;
     chainId?: number;
     network?: string;
     x402BindingSigner?: string;
@@ -305,11 +296,11 @@ interface RawCredentialFile {
     delegateKey?: unknown;
     agent_id?: unknown;
     agentId?: unknown;
-    /** #2908: what `@haven_ai/connect` writes from this release on. */
+    /** What `@haven_ai/connect` writes. */
     account_address?: unknown;
-    /** Pre-#2908 spelling — read PERMANENTLY, see `readAccountAddressField`. */
+    /** Pre-#2908 spelling — read PERMANENTLY (a credential file never rewrites itself), see `readAccountAddressField`. */
     safe_address?: unknown;
-    /** Pre-#2908 spelling — read PERMANENTLY, see `readAccountAddressField`. */
+    /** Pre-#2908 spelling — read PERMANENTLY (a credential file never rewrites itself), see `readAccountAddressField`. */
     safeAddress?: unknown;
     chain_id?: unknown;
     chainId?: unknown;
@@ -346,11 +337,11 @@ declare function loadSignerCredentials(path?: string | undefined): Promise<Signe
  */
 declare function readAccountAddressField(raw: Pick<RawCredentialFile, 'account_address' | 'safe_address' | 'safeAddress'>): string | undefined;
 /**
- * The account address off the process environment, new name first:
- * `HAVEN_ACCOUNT_ADDRESS` (the survivor, decided on #2906) then the two
- * names the dashboard handoff emitted before #2908 — `HAVEN_WALLET_ADDRESS`
- * and `HAVEN_SAFE_ADDRESS`. Unlike the file fallbacks these two ARE
- * window-scoped: they are dropped at #2914, one release after this one.
+ * The account address off the process environment: `HAVEN_ACCOUNT_ADDRESS`
+ * (the survivor, decided on #2906). The two names the dashboard handoff
+ * emitted before #2908 — `HAVEN_WALLET_ADDRESS` and `HAVEN_SAFE_ADDRESS` —
+ * were window-scoped (unlike the credential-FILE fallbacks) and are retired
+ * as of #2914.
  */
 declare function readAccountAddressEnv(env: NodeJS.ProcessEnv): string | undefined;
 /**
@@ -368,12 +359,20 @@ interface SigningAuditEntry {
     tool: SignerToolName;
     payload_hash: string;
     delegate_address: string;
+    /**
+     * Serialized key kept as `safe_address` deliberately (#2914 review): this
+     * is a persisted JSONL field, and an audit log written by an earlier
+     * release never rewrites itself — renaming the key here would fork the
+     * format mid-file. `SigningAuditContext.accountAddress` (the in-memory
+     * field this is built from) carries the account-vocabulary name; only the
+     * on-disk spelling stays put.
+     */
     safe_address?: string;
     chain_id?: number;
 }
 interface SigningAuditContext {
     delegateAddress: string;
-    safeAddress?: string;
+    accountAddress?: string;
     chainId?: number;
     auditPath?: string;
 }
@@ -393,7 +392,201 @@ interface HavenIdentity {
  * they never call the Haven API and never emit the key.
  */
 type SignerToolName = 'haven_sign' | 'haven_x402_sign_header' | 'haven_sign_x402' | 'haven_sign_sweep_delegate';
-declare const toolSchemas: Record<SignerToolName, z.ZodRawShape>;
+declare const toolSchemas: {
+    readonly haven_sign_sweep_delegate: {
+        readonly authorization: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            value: z.ZodString;
+            validAfter: z.ZodString;
+            validBefore: z.ZodString;
+            nonce: z.ZodString;
+            token: z.ZodString;
+            chainId: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            chainId: number;
+            to: string;
+            from: string;
+            nonce: string;
+            value: string;
+            token: string;
+            validAfter: string;
+            validBefore: string;
+        }, {
+            chainId: number;
+            to: string;
+            from: string;
+            nonce: string;
+            value: string;
+            token: string;
+            validAfter: string;
+            validBefore: string;
+        }>;
+        readonly expected_auth: z.ZodObject<{
+            version: z.ZodNumber;
+            message: z.ZodString;
+            signature: z.ZodString;
+            signer: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            message: string;
+            version: number;
+            signature: string;
+            signer: string;
+        }, {
+            message: string;
+            version: number;
+            signature: string;
+            signer: string;
+        }>;
+    };
+    readonly haven_sign: {
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly payload_hash: z.ZodOptional<z.ZodString>;
+        readonly x402_expected: z.ZodOptional<z.ZodObject<{
+            payment_id: z.ZodString;
+            payload_hash: z.ZodString;
+            resource_url: z.ZodString;
+            merchant_to: z.ZodString;
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodString;
+            expires_at: z.ZodString;
+            typed_data_hash: z.ZodOptional<z.ZodString>;
+            payer_delegate: z.ZodOptional<z.ZodString>;
+            payer_agent_id: z.ZodOptional<z.ZodString>;
+            auth: z.ZodObject<{
+                version: z.ZodNumber;
+                message: z.ZodString;
+                signature: z.ZodString;
+                signer: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }>>;
+        readonly typed_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly typed_data_b64: z.ZodOptional<z.ZodString>;
+    };
+    readonly haven_x402_sign_header: {
+        readonly payment_required: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        readonly x402_binding: z.ZodString;
+    };
+    readonly haven_sign_x402: {
+        readonly payment_id: z.ZodOptional<z.ZodString>;
+        readonly payload_hash: z.ZodOptional<z.ZodString>;
+        readonly x402_expected: z.ZodOptional<z.ZodObject<{
+            payment_id: z.ZodString;
+            payload_hash: z.ZodString;
+            resource_url: z.ZodString;
+            merchant_to: z.ZodString;
+            amount: z.ZodString;
+            asset: z.ZodString;
+            network: z.ZodString;
+            expires_at: z.ZodString;
+            typed_data_hash: z.ZodOptional<z.ZodString>;
+            payer_delegate: z.ZodOptional<z.ZodString>;
+            payer_agent_id: z.ZodOptional<z.ZodString>;
+            auth: z.ZodObject<{
+                version: z.ZodNumber;
+                message: z.ZodString;
+                signature: z.ZodString;
+                signer: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }, {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }, {
+            network: string;
+            payment_id: string;
+            payload_hash: string;
+            resource_url: string;
+            merchant_to: string;
+            amount: string;
+            asset: string;
+            expires_at: string;
+            auth: {
+                message: string;
+                version: number;
+                signature: string;
+                signer: string;
+            };
+            typed_data_hash?: string | undefined;
+            payer_delegate?: string | undefined;
+            payer_agent_id?: string | undefined;
+        }>>;
+        readonly payment_required: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly typed_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        readonly typed_data_b64: z.ZodOptional<z.ZodString>;
+    };
+};
 declare const toolDescriptions: Record<SignerToolName, string>;
 interface ToolSuccess<T> {
     success: true;
@@ -408,6 +601,13 @@ interface ToolFailure {
     next_action?: string;
     retry_with_new_quote?: boolean;
     suggested_tool?: string;
+    /** #3101 (epic #3105, decision 7): the typed next-step family, additive; `next_tool` never null. */
+    next_tool?: string;
+    next_tool_server?: string;
+    next_tool_name?: string;
+    next_tool_server_role?: 'hosted' | 'signer';
+    next_arguments?: Record<string, unknown>;
+    next_tool_omitted_reason?: string;
     /**
      * #1309: present on `UNSUPPORTED_EXPECTED_CONTEXT_VERSION` /
      * `UNSUPPORTED_SWEEP_BINDING_VERSION` refusals — the exact version set this
@@ -451,7 +651,7 @@ declare function createToolHandlers(signer: EdgeSigner, options?: ToolHandlerOpt
 
 interface SignerConsentInput {
     delegateAddress: string;
-    safeAddress?: string;
+    accountAddress?: string;
     agentId?: string;
     chainId?: number;
     network?: string;
@@ -476,7 +676,7 @@ declare function renderSignerConsentBlock(input: SignerConsentInput, hash: strin
 declare function ensureSignerConsent(input: SignerConsentInput, options?: SignerConsentOptions): Promise<SignerConsentDecision>;
 
 declare const SIGNER_NAME = "@haven_ai/signer";
-declare const SIGNER_VERSION = "0.2.1-alpha.0";
+declare const SIGNER_VERSION = "0.4.0-alpha.0";
 interface SignerOptions {
     /** Path to a Haven credential JSON file (delegate_key is read from it). */
     credentialsPath?: string;
@@ -541,4 +741,24 @@ declare function assertSupportedNodeVersion(nodeVersion?: string): void;
 declare function runSignerStdioServer(options?: SignerOptions): Promise<void>;
 declare function runSignerConsentGate(signer: EdgeSigner, credentials: SignerCredentials | undefined, options: SignerOptions): Promise<SignerConsentDecision>;
 
-export { type EdgeSigner, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, type SignerCompatibility, type SignerConsentDecision, type SignerConsentInput, type SignerConsentOptions, type SignerCredentials, type SignerOptions, type SignerToolName, type SigningAuditContext, type SigningAuditEntry, type ToolFailure, type ToolPayload, type ToolSuccess, type X402ExpectedPayment, type X402FundingSignatureResult, type X402HeaderResult, 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 };
+/**
+ * #3103 (epic #3105, slice 4/5): the signer's typed next step.
+ *
+ * The signer decides a `next_action` on its refusals and, until this module,
+ * never said which tool to call. It cannot know the client's server names
+ * (#2550), so the handoff is expressed through the role fields the SDK
+ * builder renders — `next_tool_server_role: hosted`, `next_tool_name` — from
+ * a bare tool name. The signer must not import the hosted server (it is an
+ * npm package installed on user machines; the hosted server is a Docker
+ * deployment), so the hosted tools it hands off to are DECLARED here as the
+ * argument shape the signer actually emits, and `next-step-signer-parity`
+ * in the hosted server's own suite pins them to the hosted schemas at test
+ * time — the mirror of how the hosted server declares the signer's shapes.
+ */
+declare const SIGNER_HOSTED_HANDOFF_SHAPES: {
+    readonly haven_get_payment_status: {
+        readonly payment_id: z$1.ZodString;
+    };
+};
+
+export { type EdgeSigner, type ResolvedSignerRuntime, SIGNER_ACK_ENV, SIGNER_CAPABILITY_KEY, SIGNER_HOSTED_HANDOFF_SHAPES, SIGNER_NAME, SIGNER_VERSION, SUPPORTED_SWEEP_BINDING_VERSIONS, SUPPORTED_X402_EXPECTED_VERSIONS, type SignerCompatibility, type SignerConsentDecision, type SignerConsentInput, type SignerConsentOptions, type SignerCredentials, type SignerOptions, type SignerToolName, type SigningAuditContext, type SigningAuditEntry, type ToolFailure, type ToolPayload, type ToolSuccess, type X402ExpectedPayment, type X402FundingSignatureResult, type X402HeaderResult, 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 };