zk-agent-cli 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/index.js

@@ -74,10 +74,215 @@ function isAgentError(error) {
 }
 
 // ../agent-core/src/storage.ts
-import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes2 } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+
+// ../agent-session-protocol/src/constants.ts
+var PROTOCOL_VERSION = "zk-agent-session-v1";
+
+// ../agent-session-protocol/src/encoding.ts
+function bytesToHex(bytes) {
+  return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function hexToBytes(hex) {
+  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+function b64urlEncode(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
+  const binary = atob(normalized + padding);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+// ../agent-session-protocol/src/crypto.ts
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+import { x25519 } from "@noble/curves/ed25519";
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha2";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { randomBytes } from "@noble/hashes/utils";
+function deriveEthereumAddressFromPrivateKey(privateKeyHex) {
+  const normalized = privateKeyHex.startsWith("0x") ? privateKeyHex.slice(2) : privateKeyHex;
+  if (!/^[0-9a-fA-F]{64}$/.test(normalized)) {
+    throw new Error("sessionPrivateKey must be a 32-byte hex string");
+  }
+  const publicKey = secp256k1.getPublicKey(hexToBytes(normalized), false);
+  const digest = keccak_256(publicKey.slice(1));
+  return `0x${bytesToHex(digest.slice(-20))}`;
+}
+function generateX25519Keypair() {
+  const secretKey = randomBytes(32);
+  const publicKey = x25519.getPublicKey(secretKey);
+  return { secretKey, publicKey };
+}
+function computeCodeHash(requestId, code) {
+  if (!requestId) throw new Error("requestId must not be empty");
+  return sha256(new TextEncoder().encode(requestId + code));
+}
+function deriveEncryptionKey(sharedSecret, code, cliPublicKeyHex, walletPublicKeyHex) {
+  const salt = sha256(new TextEncoder().encode(code));
+  const info = new TextEncoder().encode(cliPublicKeyHex + walletPublicKeyHex + PROTOCOL_VERSION);
+  return hkdf(sha256, sharedSecret, salt, info, 32);
+}
+function decryptSession(encrypted, cliSecretKey, code, requestId) {
+  if (!requestId) throw new Error("requestId must not be empty");
+  const cliPublicKey = x25519.getPublicKey(cliSecretKey);
+  const walletPublicKey = hexToBytes(encrypted.wallet_pk_hex);
+  const sharedSecret = x25519.getSharedSecret(cliSecretKey, walletPublicKey);
+  const cliPublicKeyHex = bytesToHex(cliPublicKey);
+  const encryptionKey = deriveEncryptionKey(
+    sharedSecret,
+    code,
+    cliPublicKeyHex,
+    encrypted.wallet_pk_hex
+  );
+  const expectedHash = bytesToHex(computeCodeHash(requestId, code));
+  if (expectedHash !== encrypted.code_hash_hex) {
+    throw new Error("Invalid code: hash mismatch");
+  }
+  const nonce = hexToBytes(encrypted.nonce_hex);
+  const aad = new Uint8Array([...cliPublicKey, ...walletPublicKey]);
+  const ciphertext = b64urlDecode(encrypted.ciphertext_b64url);
+  const cipher = xchacha20poly1305(encryptionKey, nonce, aad);
+  const plaintext = cipher.decrypt(ciphertext);
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+
+// ../agent-session-protocol/src/connector.ts
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+function isAddress(value) {
+  return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+function encodeSessionApprovalRequest(request) {
+  return b64urlEncode(textEncoder.encode(JSON.stringify(request)));
+}
+function buildApprovedSessionPayload(input) {
+  if (!isAddress(input.walletAddress)) throw new Error("walletAddress must be a valid address");
+  const derivedOwnerAddress = input.sessionPrivateKey ? deriveEthereumAddressFromPrivateKey(input.sessionPrivateKey) : void 0;
+  const ownerAddress = input.ownerAddress || derivedOwnerAddress;
+  if (ownerAddress && !isAddress(ownerAddress)) {
+    throw new Error("ownerAddress must be a valid address");
+  }
+  if (input.sessionAddress && !isAddress(input.sessionAddress)) {
+    throw new Error("sessionAddress must be a valid address");
+  }
+  if (input.sessionPrivateKey && !/^0x[0-9a-fA-F]{64}$/.test(input.sessionPrivateKey)) {
+    throw new Error("sessionPrivateKey must be a 32-byte hex string");
+  }
+  if (input.validatorAddress && !isAddress(input.validatorAddress)) {
+    throw new Error("validatorAddress must be a valid address");
+  }
+  if (input.paymasterAddress && !isAddress(input.paymasterAddress)) {
+    throw new Error("paymasterAddress must be a valid address");
+  }
+  if (input.paymasterToken && !isAddress(input.paymasterToken)) {
+    throw new Error("paymasterToken must be a valid address");
+  }
+  if (input.request.requestedAccountKind === "smart-account" && !ownerAddress) {
+    throw new Error(
+      "Smart-account approval requires ownerAddress or a sessionPrivateKey that can be used to derive it"
+    );
+  }
+  const signerType = input.signerType || (input.sessionPrivateKey ? "local" : "connector");
+  return {
+    version: 1,
+    provider: input.request.provider,
+    chain: input.request.chain,
+    chainId: input.request.chainId,
+    walletAddress: input.walletAddress,
+    account: {
+      kind: input.request.requestedAccountKind,
+      address: input.walletAddress,
+      ownerAddress,
+      sessionAddress: input.sessionAddress,
+      validatorAddress: input.validatorAddress,
+      signerType
+    },
+    sessionScope: input.request.requestedSessionScope,
+    capabilities: input.request.requestedCapabilities,
+    sessionExpiresAt: input.request.expiresAt,
+    paymaster: {
+      mode: input.request.requestedPaymasterMode,
+      address: input.paymasterAddress || null,
+      token: input.paymasterToken
+    },
+    sessionPublicKey: input.request.sessionPublicKey,
+    sessionPrivateKey: input.sessionPrivateKey,
+    sessionAddress: input.sessionAddress,
+    permissions: input.request.policies,
+    connectorUrl: input.connectorUrl || input.request.connectorUrl,
+    connectorOrigin: input.connectorOrigin,
+    paymasterAddress: input.paymasterAddress || null,
+    metadata: input.metadata
+  };
+}
+
+// ../agent-core/src/wallet-session.ts
+function isHexPrivateKey(value) {
+  return /^0x[a-fA-F0-9]{64}$/.test(value);
+}
+function deriveLocalExecutionSignerAddress(privateKey) {
+  if (!privateKey || !isHexPrivateKey(privateKey)) return void 0;
+  try {
+    return deriveEthereumAddressFromPrivateKey(privateKey);
+  } catch {
+    return void 0;
+  }
+}
+function buildLocalExecutionAuthority(input) {
+  if (!input.privateKey) return void 0;
+  return {
+    privateKey: input.privateKey,
+    signerAddress: deriveLocalExecutionSignerAddress(input.privateKey),
+    signerType: input.signerType || "local",
+    source: input.source,
+    attachedAt: input.attachedAt
+  };
+}
+function resolveLocalExecutionPrivateKey(wallet) {
+  return wallet.localExecutionAuthority?.privateKey || wallet.sessionPayload?.sessionPrivateKey;
+}
+function migrateWalletSessionRecord(wallet) {
+  const legacyPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const existingAuthority = wallet.localExecutionAuthority;
+  if (!existingAuthority && !legacyPrivateKey) {
+    return wallet;
+  }
+  const privateKey = existingAuthority?.privateKey || legacyPrivateKey;
+  if (!privateKey) {
+    return wallet;
+  }
+  return {
+    ...wallet,
+    localExecutionAuthority: {
+      privateKey,
+      signerAddress: existingAuthority?.signerAddress || deriveLocalExecutionSignerAddress(privateKey),
+      signerType: existingAuthority?.signerType || wallet.sessionPayload?.account?.signerType || "local",
+      source: existingAuthority?.source || (legacyPrivateKey ? "legacy-session-payload" : void 0),
+      attachedAt: existingAuthority?.attachedAt || wallet.createdAt
+    }
+  };
+}
+
+// ../agent-core/src/storage.ts
 function normalizeOptionalPath(value) {
   const trimmed = value?.trim();
   return trimmed ? path.resolve(trimmed) : null;
@@ -126,13 +331,13 @@ function getEncryptionKey() {
   const storageDirectory = ensureStorageDir();
   const encryptionKeyFile = path.join(storageDirectory, ".encryption-key");
   if (fs.existsSync(encryptionKeyFile)) return fs.readFileSync(encryptionKeyFile);
-  const key = randomBytes(32);
+  const key = randomBytes2(32);
   fs.writeFileSync(encryptionKeyFile, key, { mode: 384 });
   return key;
 }
 function encrypt(plaintext) {
   const key = getEncryptionKey();
-  const iv = randomBytes(16);
+  const iv = randomBytes2(16);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
   let encrypted = cipher.update(plaintext, "utf8", "hex");
   encrypted += cipher.final("hex");
@@ -181,12 +386,15 @@ async function loadProjectConfig() {
 }
 async function saveWalletSession(record) {
   const storageDirectory = ensureStorageDir();
-  writeEncryptedJson(path.join(storageDirectory, "wallets", `${record.walletName}.json`), record);
+  writeEncryptedJson(
+    path.join(storageDirectory, "wallets", `${record.walletName}.json`),
+    migrateWalletSessionRecord(record)
+  );
 }
 async function loadWalletSession(walletName) {
   const filePath = storagePath("wallets", `${walletName}.json`);
   if (!fs.existsSync(filePath)) return null;
-  return readEncryptedJson(filePath);
+  return migrateWalletSessionRecord(readEncryptedJson(filePath));
 }
 async function listWalletNames() {
   const storageDirectory = ensureStorageDir();
@@ -2225,22 +2433,33 @@ function buildWalletPreparationActions(input) {
   const { wallet, inspection, funding } = input;
   const exclude = new Set(input.excludeActionIds || []);
   const actions = [];
-  if (!exclude.has("reapprove") && !inspection.sessionPrivateKeyStored) {
+  const approvalReady = inspection.approvalReady ?? Boolean(wallet.sessionPayload);
+  const localExecutionReady = inspection.localExecutionKeyStored ?? inspection.sessionPrivateKeyStored;
+  if (!exclude.has("reapprove") && !approvalReady) {
     actions.push({
       id: "reapprove",
       priority: "required",
-      title: "Restore a writable local session",
-      reason: "No local session key is stored, so this wallet cannot execute local write actions yet.",
+      title: "Restore approved session metadata",
+      reason: localExecutionReady ? "A local execution signer is already present, but approved session metadata is missing or not usable yet." : "Approved session metadata is missing, so this wallet cannot execute local write actions yet.",
       command: `zk-agent wallet reapprove --name ${wallet.walletName} --await-local`
     });
   }
+  if (!exclude.has("attach-signer") && approvalReady && !localExecutionReady) {
+    actions.push({
+      id: "attach-signer",
+      priority: "required",
+      title: "Attach a local execution signer",
+      reason: "Approved session metadata exists, but no local execution signer is stored for write actions yet.",
+      command: `zk-agent wallet signer attach --name ${wallet.walletName} --private-key <hex>`
+    });
+  }
   if (!exclude.has("signer-mismatch") && inspection.signerMatchesStoredIdentity === false) {
     actions.push({
       id: "signer-mismatch",
       priority: "required",
       title: "Repair the signer/address mismatch",
       reason: "The stored local signer does not match the wallet identity currently recorded for this session.",
-      command: `zk-agent wallet reapprove --name ${wallet.walletName} --await-local`
+      command: `zk-agent wallet signer attach --name ${wallet.walletName} --private-key <hex>`
     });
   }
   if (!exclude.has("deploy") && inspection.accountKind === "smart-account" && inspection.deploymentStatus === "not-deployed") {
@@ -2784,7 +3003,7 @@ async function loadWorkflowRuntimeState(wallet, intent, provider4, protocol, toC
 }
 function manualBlockingActionIds(plan) {
   return plan.steps.filter(
-    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "signer-mismatch" || step.id === "deploy")
+    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "attach-signer" || step.id === "signer-mismatch" || step.id === "deploy")
   ).map((step) => step.id);
 }
 function buildWorkflowGoalCommand(goal, wallet) {
@@ -3120,7 +3339,7 @@ function mergeNotes2(...groups) {
 }
 function manualBlockingActionIds2(plan) {
   return plan.steps.filter(
-    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "signer-mismatch" || step.id === "deploy")
+    (step) => step.kind === "prerequisite" && step.priority === "required" && (step.id === "reapprove" || step.id === "attach-signer" || step.id === "signer-mismatch" || step.id === "deploy")
   ).map((step) => step.id);
 }
 async function inspectWorkflowStatus(input, deps) {
@@ -4159,28 +4378,28 @@ function getL1ExplorerUrl(l1ChainId, txHash) {
       return void 0;
   }
 }
-function isHexPrivateKey(value) {
+function isHexPrivateKey2(value) {
   return /^0x[a-fA-F0-9]{64}$/.test(value);
 }
 function deriveSignerAddress(privateKey) {
-  if (!privateKey || !isHexPrivateKey(privateKey)) return void 0;
+  if (!privateKey || !isHexPrivateKey2(privateKey)) return void 0;
   return new Wallet(privateKey).address;
 }
 function requireWritableSession(wallet) {
-  const privateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const privateKey = resolveLocalExecutionPrivateKey(wallet);
   if (!privateKey) {
     throw new AgentError(
       "WRITABLE_SESSION_REQUIRED",
-      "Writable local execution requires a stored sessionPrivateKey.",
+      "Writable local execution requires a stored local execution key.",
       {
         walletName: wallet.walletName
       }
     );
   }
-  if (!isHexPrivateKey(privateKey)) {
+  if (!isHexPrivateKey2(privateKey)) {
     throw new AgentError(
       "WRITABLE_SESSION_INVALID",
-      "Stored sessionPrivateKey is not a valid 32-byte hex key.",
+      "Stored local execution key is not a valid 32-byte hex key.",
       {
         walletName: wallet.walletName
       }
@@ -4193,7 +4412,7 @@ function resolveWritableSignerAddress(wallet, privateKey) {
   if (!derivedSignerAddress) {
     throw new AgentError(
       "WRITABLE_SESSION_INVALID",
-      "Stored sessionPrivateKey is not a valid 32-byte hex key.",
+      "Stored local execution key is not a valid 32-byte hex key.",
       {
         walletName: wallet.walletName
       }
@@ -4204,7 +4423,7 @@ function resolveWritableSignerAddress(wallet, privateKey) {
     if (derivedSignerAddress.toLowerCase() !== executionAddress.toLowerCase()) {
       throw new AgentError(
         "EOA_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the EOA execution address.",
+        "Stored local execution key does not match the EOA execution address.",
         {
           walletName: wallet.walletName,
           executionAddress,
@@ -4228,7 +4447,7 @@ function resolveWritableSignerAddress(wallet, privateKey) {
     if (derivedSignerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
       throw new AgentError(
         "SMART_ACCOUNT_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+        "Stored local execution key does not match the smart-account ownerAddress.",
         {
           walletName: wallet.walletName,
           ownerAddress,
@@ -4255,7 +4474,7 @@ async function buildSigner(wallet, provider4) {
     if (derivedSignerAddress && derivedSignerAddress.toLowerCase() !== executionAddress.toLowerCase()) {
       throw new AgentError(
         "EOA_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the EOA execution address.",
+        "Stored local execution key does not match the EOA execution address.",
         {
           walletName: wallet.walletName,
           executionAddress,
@@ -4279,7 +4498,7 @@ async function buildSigner(wallet, provider4) {
     if (derivedSignerAddress && derivedSignerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
       throw new AgentError(
         "SMART_ACCOUNT_SIGNER_MISMATCH",
-        "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+        "Stored local execution key does not match the smart-account ownerAddress.",
         {
           walletName: wallet.walletName,
           ownerAddress,
@@ -6064,163 +6283,6 @@ var ZkSyncDefiProvider = class {
 
 // ../provider-zksync-wallet/src/provider.ts
 import { randomBytes as randomBytes3 } from "node:crypto";
-
-// ../agent-session-protocol/src/constants.ts
-var PROTOCOL_VERSION = "zk-agent-session-v1";
-
-// ../agent-session-protocol/src/encoding.ts
-function bytesToHex(bytes) {
-  return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-function hexToBytes(hex) {
-  if (hex.length % 2 !== 0) throw new Error("Invalid hex string");
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let index = 0; index < bytes.length; index += 1) {
-    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
-  }
-  return bytes;
-}
-function b64urlEncode(bytes) {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function b64urlDecode(value) {
-  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
-  const padding = normalized.length % 4 === 0 ? "" : "=".repeat(4 - normalized.length % 4);
-  const binary = atob(normalized + padding);
-  const bytes = new Uint8Array(binary.length);
-  for (let index = 0; index < binary.length; index += 1) {
-    bytes[index] = binary.charCodeAt(index);
-  }
-  return bytes;
-}
-
-// ../agent-session-protocol/src/crypto.ts
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-import { x25519 } from "@noble/curves/ed25519";
-import { secp256k1 } from "@noble/curves/secp256k1";
-import { hkdf } from "@noble/hashes/hkdf";
-import { sha256 } from "@noble/hashes/sha2";
-import { keccak_256 } from "@noble/hashes/sha3";
-import { randomBytes as randomBytes2 } from "@noble/hashes/utils";
-function deriveEthereumAddressFromPrivateKey(privateKeyHex) {
-  const normalized = privateKeyHex.startsWith("0x") ? privateKeyHex.slice(2) : privateKeyHex;
-  if (!/^[0-9a-fA-F]{64}$/.test(normalized)) {
-    throw new Error("sessionPrivateKey must be a 32-byte hex string");
-  }
-  const publicKey = secp256k1.getPublicKey(hexToBytes(normalized), false);
-  const digest = keccak_256(publicKey.slice(1));
-  return `0x${bytesToHex(digest.slice(-20))}`;
-}
-function generateX25519Keypair() {
-  const secretKey = randomBytes2(32);
-  const publicKey = x25519.getPublicKey(secretKey);
-  return { secretKey, publicKey };
-}
-function computeCodeHash(requestId, code) {
-  if (!requestId) throw new Error("requestId must not be empty");
-  return sha256(new TextEncoder().encode(requestId + code));
-}
-function deriveEncryptionKey(sharedSecret, code, cliPublicKeyHex, walletPublicKeyHex) {
-  const salt = sha256(new TextEncoder().encode(code));
-  const info = new TextEncoder().encode(cliPublicKeyHex + walletPublicKeyHex + PROTOCOL_VERSION);
-  return hkdf(sha256, sharedSecret, salt, info, 32);
-}
-function decryptSession(encrypted, cliSecretKey, code, requestId) {
-  if (!requestId) throw new Error("requestId must not be empty");
-  const cliPublicKey = x25519.getPublicKey(cliSecretKey);
-  const walletPublicKey = hexToBytes(encrypted.wallet_pk_hex);
-  const sharedSecret = x25519.getSharedSecret(cliSecretKey, walletPublicKey);
-  const cliPublicKeyHex = bytesToHex(cliPublicKey);
-  const encryptionKey = deriveEncryptionKey(
-    sharedSecret,
-    code,
-    cliPublicKeyHex,
-    encrypted.wallet_pk_hex
-  );
-  const expectedHash = bytesToHex(computeCodeHash(requestId, code));
-  if (expectedHash !== encrypted.code_hash_hex) {
-    throw new Error("Invalid code: hash mismatch");
-  }
-  const nonce = hexToBytes(encrypted.nonce_hex);
-  const aad = new Uint8Array([...cliPublicKey, ...walletPublicKey]);
-  const ciphertext = b64urlDecode(encrypted.ciphertext_b64url);
-  const cipher = xchacha20poly1305(encryptionKey, nonce, aad);
-  const plaintext = cipher.decrypt(ciphertext);
-  return JSON.parse(new TextDecoder().decode(plaintext));
-}
-
-// ../agent-session-protocol/src/connector.ts
-var textEncoder = new TextEncoder();
-var textDecoder = new TextDecoder();
-function isAddress(value) {
-  return /^0x[a-fA-F0-9]{40}$/.test(value);
-}
-function encodeSessionApprovalRequest(request) {
-  return b64urlEncode(textEncoder.encode(JSON.stringify(request)));
-}
-function buildApprovedSessionPayload(input) {
-  if (!isAddress(input.walletAddress)) throw new Error("walletAddress must be a valid address");
-  const derivedOwnerAddress = input.sessionPrivateKey ? deriveEthereumAddressFromPrivateKey(input.sessionPrivateKey) : void 0;
-  const ownerAddress = input.ownerAddress || derivedOwnerAddress;
-  if (ownerAddress && !isAddress(ownerAddress)) {
-    throw new Error("ownerAddress must be a valid address");
-  }
-  if (input.sessionAddress && !isAddress(input.sessionAddress)) {
-    throw new Error("sessionAddress must be a valid address");
-  }
-  if (input.sessionPrivateKey && !/^0x[0-9a-fA-F]{64}$/.test(input.sessionPrivateKey)) {
-    throw new Error("sessionPrivateKey must be a 32-byte hex string");
-  }
-  if (input.validatorAddress && !isAddress(input.validatorAddress)) {
-    throw new Error("validatorAddress must be a valid address");
-  }
-  if (input.paymasterAddress && !isAddress(input.paymasterAddress)) {
-    throw new Error("paymasterAddress must be a valid address");
-  }
-  if (input.paymasterToken && !isAddress(input.paymasterToken)) {
-    throw new Error("paymasterToken must be a valid address");
-  }
-  if (input.request.requestedAccountKind === "smart-account" && !ownerAddress) {
-    throw new Error(
-      "Smart-account approval requires ownerAddress or a sessionPrivateKey that can be used to derive it"
-    );
-  }
-  return {
-    version: 1,
-    provider: input.request.provider,
-    chain: input.request.chain,
-    chainId: input.request.chainId,
-    walletAddress: input.walletAddress,
-    account: {
-      kind: input.request.requestedAccountKind,
-      address: input.walletAddress,
-      ownerAddress,
-      sessionAddress: input.sessionAddress,
-      validatorAddress: input.validatorAddress,
-      signerType: input.signerType || "connector"
-    },
-    sessionScope: input.request.requestedSessionScope,
-    capabilities: input.request.requestedCapabilities,
-    sessionExpiresAt: input.request.expiresAt,
-    paymaster: {
-      mode: input.request.requestedPaymasterMode,
-      address: input.paymasterAddress || null,
-      token: input.paymasterToken
-    },
-    sessionPublicKey: input.request.sessionPublicKey,
-    sessionPrivateKey: input.sessionPrivateKey,
-    sessionAddress: input.sessionAddress,
-    permissions: input.request.policies,
-    connectorUrl: input.connectorUrl || input.request.connectorUrl,
-    connectorOrigin: input.connectorOrigin,
-    paymasterAddress: input.paymasterAddress || null,
-    metadata: input.metadata
-  };
-}
-
-// ../provider-zksync-wallet/src/provider.ts
 import { ethers as ethers2 } from "ethers";
 import { ContractFactory, ECDSASmartAccount as ECDSASmartAccount2, Provider as Provider2, Wallet as Wallet2, utils as utils2 } from "zksync-ethers";
 
@@ -6251,7 +6313,7 @@ function isAddress2(value) {
 function isHexData(value) {
   return /^0x([a-fA-F0-9]{2})*$/.test(value);
 }
-function isHexPrivateKey2(value) {
+function isHexPrivateKey3(value) {
   return /^0x[a-fA-F0-9]{64}$/.test(value);
 }
 function padHex(value, length = 64) {
@@ -6428,6 +6490,8 @@ function buildInspectionResult(wallet, codeLength, derivedSignerAddress, blocker
     paymasterMode: wallet.paymasterMode,
     deploymentStatus,
     codeLength,
+    approvalReady: Boolean(wallet.sessionPayload),
+    localExecutionKeyStored: Boolean(resolveLocalExecutionPrivateKey(wallet)),
     sessionPrivateKeyStored: Boolean(wallet.sessionPayload?.sessionPrivateKey),
     derivedSignerAddress,
     signerMatchesStoredIdentity,
@@ -6837,7 +6901,7 @@ async function preparePaymasterTransaction(wallet, tx, paymaster) {
   }
 }
 function deriveSignerAddress2(privateKey) {
-  if (!privateKey || !isHexPrivateKey2(privateKey)) return void 0;
+  if (!privateKey || !isHexPrivateKey3(privateKey)) return void 0;
   return new Wallet2(privateKey).address;
 }
 function normalizeSalt(value) {
@@ -6897,7 +6961,7 @@ async function resolveSmartAccountDeploymentContext(input) {
   if (deployerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
     throw new AgentError(
       "SMART_ACCOUNT_SIGNER_MISMATCH",
-      "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+      "Stored local execution key does not match the smart-account ownerAddress.",
       {
         walletName: wallet.walletName,
         ownerAddress,
@@ -6994,7 +7058,7 @@ async function resolveSmartAccountDeploymentContext(input) {
 async function inspectWalletRecord(wallet) {
   const executionAddress = resolveExecutionAddress2(wallet);
   const ownerAddress = resolveOwnerAddress2(wallet);
-  const sessionPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const sessionPrivateKey = resolveLocalExecutionPrivateKey(wallet);
   const derivedSignerAddress = deriveSignerAddress2(sessionPrivateKey);
   const provider4 = getProvider(wallet.chain);
   const code = await provider4.getCode(executionAddress);
@@ -7006,14 +7070,14 @@ async function inspectWalletRecord(wallet) {
   }
   if (!sessionPrivateKey) {
     blockers.push(
-      "Writable local execution requires a stored sessionPrivateKey. Re-approve locally with --session-private-key or import a writable session."
+      "Writable local execution requires a stored local execution key. Attach one with wallet signer attach, re-approve locally with --session-private-key, or import a writable session."
     );
-  } else if (!isHexPrivateKey2(sessionPrivateKey)) {
-    blockers.push("Stored sessionPrivateKey is not a valid 32-byte hex key.");
+  } else if (!isHexPrivateKey3(sessionPrivateKey)) {
+    blockers.push("Stored local execution key is not a valid 32-byte hex key.");
   }
   if (wallet.accountKind === "eoa") {
     if (derivedSignerAddress && derivedSignerAddress.toLowerCase() !== executionAddress.toLowerCase()) {
-      blockers.push("Stored sessionPrivateKey does not match the EOA execution address.");
+      blockers.push("Stored local execution key does not match the EOA execution address.");
     }
     if (codeLength > 0) {
       notes.push("EOA wallet record points to an address with deployed bytecode.");
@@ -7024,7 +7088,7 @@ async function inspectWalletRecord(wallet) {
       blockers.push("Smart-account session is missing ownerAddress metadata.");
     }
     if (ownerAddress && derivedSignerAddress && derivedSignerAddress.toLowerCase() !== ownerAddress.toLowerCase()) {
-      blockers.push("Stored sessionPrivateKey does not match the smart-account ownerAddress.");
+      blockers.push("Stored local execution key does not match the smart-account ownerAddress.");
     }
     if (codeLength === 0) {
       blockers.push(
@@ -7050,18 +7114,18 @@ async function assertWalletReadyForWrite(wallet) {
       { inspection }
     );
   }
-  const sessionPrivateKey = wallet.sessionPayload?.sessionPrivateKey;
-  if (!sessionPrivateKey || !isHexPrivateKey2(sessionPrivateKey)) {
+  const sessionPrivateKey = resolveLocalExecutionPrivateKey(wallet);
+  if (!sessionPrivateKey || !isHexPrivateKey3(sessionPrivateKey)) {
     throw new AgentError(
       "WRITABLE_SESSION_REQUIRED",
-      "Writable local execution requires a valid stored sessionPrivateKey.",
+      "Writable local execution requires a valid stored local execution key.",
       { inspection }
     );
   }
   if (wallet.accountKind === "eoa") {
     throw new AgentError(
       "EOA_SIGNER_MISMATCH",
-      "Stored sessionPrivateKey does not match the EOA execution address.",
+      "Stored local execution key does not match the EOA execution address.",
       { inspection }
     );
   }
@@ -7075,7 +7139,7 @@ async function assertWalletReadyForWrite(wallet) {
   if (inspection.signerMatchesStoredIdentity === false) {
     throw new AgentError(
       "SMART_ACCOUNT_SIGNER_MISMATCH",
-      "Stored sessionPrivateKey does not match the smart-account ownerAddress.",
+      "Stored local execution key does not match the smart-account ownerAddress.",
       { inspection }
     );
   }
@@ -7096,14 +7160,14 @@ async function assertWalletReadyForWrite(wallet) {
   );
 }
 function requireWritableSession2(wallet) {
-  const privateKey = wallet.sessionPayload?.sessionPrivateKey;
+  const privateKey = resolveLocalExecutionPrivateKey(wallet);
   if (!privateKey) {
     throw new Error(
-      "Writable session requires sessionPrivateKey. Re-approve locally with --session-private-key or import a writable testnet session."
+      "Writable session requires a stored local execution key. Re-approve locally with --session-private-key or import a writable testnet session."
     );
   }
-  if (!isHexPrivateKey2(privateKey)) {
-    throw new Error("Stored sessionPrivateKey is not a valid 32-byte hex key");
+  if (!isHexPrivateKey3(privateKey)) {
+    throw new Error("Stored local execution key is not a valid 32-byte hex key");
   }
   return privateKey;
 }
@@ -7354,6 +7418,13 @@ var ZkSyncWalletProvider = class {
     }
     const chain = resolveChain(payload.chainId);
     const walletAddress = payload.account?.address || payload.walletAddress;
+    const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+    const localExecutionAuthority = buildLocalExecutionAuthority({
+      privateKey: payload.sessionPrivateKey,
+      signerType: payload.account?.signerType,
+      source: payload.sessionPrivateKey ? payload.account?.signerType === "local" ? "explicit-local-approval" : "approved-payload" : void 0,
+      attachedAt: createdAt
+    });
     return {
       walletName,
       walletAddress,
@@ -7367,7 +7438,8 @@ var ZkSyncWalletProvider = class {
       sessionScope: payload.sessionScope || summarizeScope(chain.key, chain.chainId),
       capabilities: payload.capabilities,
       paymasterMode: resolvePaymasterMode(payload),
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      createdAt,
+      localExecutionAuthority,
       sessionPayload: payload
     };
   }
@@ -7692,6 +7764,9 @@ function buildWalletListRecommendedCommand() {
 function buildWalletStatusRecommendedCommand(walletName) {
   return `zk-agent wallet status --name ${walletName}`;
 }
+function buildWalletSignerAttachRecommendedCommand(walletName, privateKeyRef = "<hex>") {
+  return `zk-agent wallet signer attach --name ${walletName} --private-key ${privateKeyRef}`;
+}
 function buildAssetsRecommendedCommand(walletName) {
   return `zk-agent assets --wallet ${walletName}`;
 }
@@ -7760,6 +7835,10 @@ function buildWorkflowListRecommendedCommand() {
 function buildWorkflowAutoRecommendedCommand(walletName) {
   return `zk-agent workflow auto --wallet ${walletName} --intent <intent> [goal flags] --create-checkpoint --execute-when-ready`;
 }
+function buildWorkflowPayRecommendedCommand(walletName, paymasterMode) {
+  const command = `zk-agent workflow pay --wallet ${walletName} --to <address> --amount <amount>`;
+  return appendPaymasterMode(command, paymasterMode);
+}
 function buildWorkflowShowRecommendedCommand(requestId) {
   return `zk-agent workflow show --request-id ${requestId}`;
 }
@@ -10505,11 +10584,15 @@ function createNextCommand(deps) {
       nativeSymbol: nativeBalance?.symbol,
       funding
     });
+    const workflowPay = buildWorkflowPayRecommendedCommand(
+      wallet.walletName,
+      paymasterMode
+    );
     const workflowAuto = appendPaymasterMode2(
       buildWorkflowAutoRecommendedCommand(wallet.walletName),
       paymasterMode
     );
-    const nextCommand = summary.recommendedCommand || workflowAuto;
+    const nextCommand = summary.recommendedCommand || workflowPay;
     const agentFollowup = buildAgentFollowup(agentProfile, {
       walletName: wallet.walletName,
       walletExists: true
@@ -10521,6 +10604,7 @@ function createNextCommand(deps) {
       discoverOwnedTokens: buildOwnedTokensRecommendedCommand(wallet.walletName),
       discoverTokens: buildTokensRecommendedCommand(wallet.chain),
       inspectToken: buildResolveTokenRecommendedCommand(wallet.chain),
+      workflowPay,
       workflowAuto,
       nextAction: nextCommand,
       inspectDefaults: buildDefaultsRecommendedCommand()
@@ -10530,7 +10614,7 @@ function createNextCommand(deps) {
         ...walletNextLines(summary),
         ...agentProfileLines(agentProfile),
         ...agentFollowupLines(agentFollowup),
-        ...summary.recommendedCommand ? [] : [["next", workflowAuto]],
+        ...summary.recommendedCommand ? [] : [["next", workflowPay]],
         ["discover assets", recommendedCommands.discoverAssets],
         ["discover owned tokens", recommendedCommands.discoverOwnedTokens],
         ["discover tokens", recommendedCommands.discoverTokens],
@@ -11824,16 +11908,19 @@ function readRequestBody(request, limitBytes = RELAY_BODY_LIMIT_BYTES) {
   });
 }
 function writeJson2(response, statusCode, payload) {
-  response.statusCode = statusCode;
-  response.setHeader("Content-Type", "application/json; charset=utf-8");
-  response.setHeader("Access-Control-Allow-Origin", "*");
-  response.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-  response.setHeader("Access-Control-Allow-Headers", "Content-Type");
-  response.end(JSON.stringify(payload, null, 2));
+  writeBody(response, statusCode, "application/json; charset=utf-8", JSON.stringify(payload, null, 2), {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type"
+  });
 }
-function writeText(response, statusCode, contentType, value) {
+function writeBody(response, statusCode, contentType, value, extraHeaders = {}) {
   response.statusCode = statusCode;
   response.setHeader("Content-Type", contentType);
+  response.setHeader("Content-Length", Buffer.isBuffer(value) ? String(value.byteLength) : String(Buffer.byteLength(value)));
+  for (const [key, headerValue] of Object.entries(extraHeaders)) {
+    response.setHeader(key, headerValue);
+  }
   response.end(value);
 }
 function resolveConnectorUiDistRoot() {
@@ -11861,8 +11948,8 @@ function contentTypeFor(filePath) {
 function normalizeRelayBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
-function resolveRelayPublicBaseUrl(actualBaseUrl, publicOrigin) {
-  return publicOrigin?.trim() ? normalizeRelayBaseUrl(new URL(publicOrigin.trim()).toString()) : normalizeRelayBaseUrl(actualBaseUrl);
+function resolveRelayPublicBaseUrl(bindBaseUrl, publicOrigin) {
+  return publicOrigin?.trim() ? normalizeRelayBaseUrl(new URL(publicOrigin.trim()).toString()) : normalizeRelayBaseUrl(bindBaseUrl);
 }
 function relayCapabilities(connectorUiAvailable) {
   return [
@@ -11874,14 +11961,14 @@ function relayCapabilities(connectorUiAvailable) {
     ...connectorUiAvailable ? ["connector-ui"] : []
   ];
 }
-function relayHealthResponse(actualBaseUrl, publicBaseUrl, connectorUiAvailable) {
+function relayHealthResponse(bindBaseUrl, publicBaseUrl, connectorUiAvailable) {
   return {
     ok: true,
     service: RELAY_SERVICE,
     protocol: RELAY_PROTOCOL,
     schema_version: RELAY_SCHEMA_VERSION,
     relay_mode: "local-file",
-    origin: normalizeRelayBaseUrl(actualBaseUrl),
+    origin: normalizeRelayBaseUrl(bindBaseUrl),
     public_origin: normalizeRelayBaseUrl(publicBaseUrl),
     connector_ui_available: connectorUiAvailable,
     capabilities: relayCapabilities(connectorUiAvailable)
@@ -11954,13 +12041,13 @@ async function fetchRelayApproval(baseUrl, requestId) {
 }
 async function startRelayServer(options) {
   const uiDistRoot = resolveConnectorUiDistRoot();
+  let bindBaseUrl = "";
   const server = createServer(async (request, response) => {
     try {
-      const requestUrl = new URL(request.url || "/", `http://${request.headers.host || "localhost"}`);
+      const requestUrl = new URL(request.url || "/", "http://localhost");
       const pathname = requestUrl.pathname;
       const method = request.method || "GET";
-      const actualBaseUrl = `${requestUrl.protocol}//${requestUrl.host}`;
-      const publicBaseUrl = resolveRelayPublicBaseUrl(actualBaseUrl, options.publicOrigin);
+      const publicBaseUrl = resolveRelayPublicBaseUrl(bindBaseUrl, options.publicOrigin);
       if (method === "OPTIONS") {
         writeJson2(response, 204, {});
         return;
@@ -11969,7 +12056,7 @@ async function startRelayServer(options) {
         writeJson2(
           response,
           200,
-          relayHealthResponse(actualBaseUrl, publicBaseUrl, Boolean(uiDistRoot))
+          relayHealthResponse(bindBaseUrl, publicBaseUrl, Boolean(uiDistRoot))
         );
         return;
       }
@@ -12044,12 +12131,12 @@ async function startRelayServer(options) {
           return;
         }
         if (fs7.existsSync(filePath) && fs7.statSync(filePath).isFile()) {
-          writeText(response, 200, contentTypeFor(filePath), fs7.readFileSync(filePath, "utf8"));
+          writeBody(response, 200, contentTypeFor(filePath), fs7.readFileSync(filePath));
           return;
         }
         const indexPath = path6.join(uiDistRoot, "index.html");
         if (fs7.existsSync(indexPath)) {
-          writeText(response, 200, "text/html; charset=utf-8", fs7.readFileSync(indexPath, "utf8"));
+          writeBody(response, 200, "text/html; charset=utf-8", fs7.readFileSync(indexPath));
           return;
         }
       }
@@ -12074,9 +12161,10 @@ async function startRelayServer(options) {
       });
     });
   });
+  bindBaseUrl = `http://${address.address}:${address.port}`;
   return {
     connectorUiAvailable: Boolean(uiDistRoot),
-    origin: `http://${address.address}:${address.port}`,
+    origin: bindBaseUrl,
     port: address.port,
     close: async () => await new Promise((resolve, reject) => {
       server.close((error) => {
@@ -12853,6 +12941,7 @@ var WALLET_HELP_COMMAND_ORDER = [
   "rename",
   "remove",
   "request",
+  "signer",
   "paymaster",
   "smart-account"
 ];
@@ -12872,6 +12961,11 @@ var WALLET_SMART_ACCOUNT_HELP_COMMAND_ORDER = [
   "sed-lite",
   "daily-spend-limit"
 ];
+var WALLET_SIGNER_HELP_COMMAND_ORDER = [
+  "show",
+  "attach",
+  "remove"
+];
 function applyCommandOrder(command, orderedNames) {
   const order = new Map(orderedNames.map((name, index) => [name, index]));
   const sortedCommands = [...command.commands].sort((left, right) => {
@@ -12892,6 +12986,10 @@ function sanitizeSessionPayload(payload) {
 function stripSensitiveWalletRecord(wallet) {
   return {
     ...wallet,
+    localExecutionAuthority: wallet.localExecutionAuthority ? {
+      ...wallet.localExecutionAuthority,
+      privateKey: void 0
+    } : wallet.localExecutionAuthority,
     sessionPayload: wallet.sessionPayload ? {
       ...wallet.sessionPayload,
       sessionPrivateKey: void 0
@@ -12982,6 +13080,7 @@ function isRecord5(value) {
 function cloneWalletSessionRecord(wallet) {
   return {
     ...wallet,
+    localExecutionAuthority: wallet.localExecutionAuthority ? { ...wallet.localExecutionAuthority } : wallet.localExecutionAuthority,
     validationHookAddresses: wallet.validationHookAddresses ? [...wallet.validationHookAddresses] : wallet.validationHookAddresses,
     sessionScope: wallet.sessionScope ? {
       ...wallet.sessionScope,
@@ -13032,6 +13131,12 @@ function parseWalletExportRecord(value) {
   if (wallet.validatorAddress && !isAddress3(wallet.validatorAddress)) {
     throw new Error("Restore payload validatorAddress must be a valid 20-byte hex address.");
   }
+  if (wallet.localExecutionAuthority?.signerAddress && !isAddress3(wallet.localExecutionAuthority.signerAddress)) {
+    throw new Error("Restore payload localExecutionAuthority.signerAddress must be a valid 20-byte hex address.");
+  }
+  if (wallet.localExecutionAuthority?.privateKey && !/^0x[a-fA-F0-9]{64}$/.test(wallet.localExecutionAuthority.privateKey)) {
+    throw new Error("Restore payload localExecutionAuthority.privateKey must be a valid 32-byte hex string.");
+  }
   if (wallet.validationHookAddresses && wallet.validationHookAddresses.some((hookAddress) => !isAddress3(hookAddress))) {
     throw new Error("Restore payload validationHookAddresses must contain valid 20-byte hex addresses.");
   }
@@ -13064,7 +13169,7 @@ function parseWalletExportRecord(value) {
   }
   return {
     ...candidate,
-    wallet: cloneWalletSessionRecord(wallet)
+    wallet: migrateWalletSessionRecord(cloneWalletSessionRecord(wallet))
   };
 }
 function normalizeHexString2(value, label) {
@@ -13075,6 +13180,13 @@ function normalizeHexString2(value, label) {
   }
   return prefixed;
 }
+function normalizePrivateKey(value, label) {
+  const normalized = normalizeHexString2(value, label);
+  if (!/^0x[a-fA-F0-9]{64}$/.test(normalized)) {
+    throw new Error(`${label} must be a valid 32-byte hex string.`);
+  }
+  return normalized;
+}
 function parseArtifactInput(value) {
   const raw = parseJsonInput(value);
   if (!isRecord5(raw)) throw new Error("Artifact must be a JSON object");
@@ -13783,6 +13895,12 @@ function inspectionLines(inspection) {
       inspection.signerMatchesStoredIdentity ? "yes" : "no"
     ]);
   }
+  if (typeof inspection.approvalReady === "boolean") {
+    lines.push(["approval", inspection.approvalReady ? "present" : "missing"]);
+  }
+  if (typeof inspection.localExecutionKeyStored === "boolean") {
+    lines.push(["local signer", inspection.localExecutionKeyStored ? "stored" : "missing"]);
+  }
   lines.push(["session key", inspection.sessionPrivateKeyStored ? "stored" : "missing"]);
   if (inspection.paymasterMode) {
     lines.push(["paymaster", inspection.paymasterMode]);
@@ -13881,6 +13999,7 @@ function walletExportLines(wallet, bundle) {
 }
 function walletRestoreLines(wallet, restoredFrom, syncResult) {
   let nextCommand = buildWalletNextRecommendedCommand(wallet.walletName);
+  let afterNextCommandLabel;
   const lines = [
     ["wallet", wallet.walletName],
     ["address", wallet.walletAddress],
@@ -13891,12 +14010,15 @@ function walletRestoreLines(wallet, restoredFrom, syncResult) {
     ["source export", restoredFrom.exportedAt],
     ["sensitive data", restoredFrom.sensitiveDataIncluded ? "included in backup" : "not included in backup"]
   ];
-  if (!wallet.sessionPayload?.sessionPrivateKey) {
+  if (!resolveLocalExecutionPrivateKey(wallet)) {
+    const attachSignerCommand = buildWalletSignerAttachRecommendedCommand(wallet.walletName);
+    const reapproveCommand = buildWalletReapproveRecommendedCommand(wallet.walletName);
     lines.push([
       "note",
-      `No sessionPrivateKey was present in the backup. The restored wallet can be inspected and synced, but local write execution will stay blocked until you re-import or re-approve a writable session, for example: ${buildWalletReapproveRecommendedCommand(wallet.walletName)}`
+      wallet.sessionPayload ? `No local execution signer was present in the backup. The restored wallet can be inspected and synced, but local write execution will stay blocked until you attach a local signer or re-approve a writable session, for example: ${attachSignerCommand}` : `No local execution signer was present in the backup. The restored wallet can be inspected and synced, but local write execution will stay blocked until you re-import, attach a local signer, or re-approve a writable session, for example: ${reapproveCommand}`
     ]);
-    nextCommand = buildWalletReapproveRecommendedCommand(wallet.walletName);
+    nextCommand = wallet.sessionPayload ? attachSignerCommand : reapproveCommand;
+    afterNextCommandLabel = wallet.sessionPayload ? "after signer attach" : "after reapprove";
   }
   if (syncResult) {
     lines.push(["sync", "completed"]);
@@ -13920,7 +14042,10 @@ function walletRestoreLines(wallet, restoredFrom, syncResult) {
   }
   lines.push(["next", nextCommand]);
   if (nextCommand !== buildWalletNextRecommendedCommand(wallet.walletName)) {
-    lines.push(["after reapprove", buildWalletNextRecommendedCommand(wallet.walletName)]);
+    lines.push([
+      afterNextCommandLabel || "after reapprove",
+      buildWalletNextRecommendedCommand(wallet.walletName)
+    ]);
   }
   lines.push(["status command", buildWalletStatusRecommendedCommand(wallet.walletName)]);
   return lines;
@@ -13932,6 +14057,17 @@ function preserveExistingWalletMetadata(importedWallet, existingWallet) {
   if (existingWallet.chain !== importedWallet.chain || existingWallet.chainId !== importedWallet.chainId || existingWallet.walletAddress.toLowerCase() !== importedWallet.walletAddress.toLowerCase()) {
     return importedWallet;
   }
+  const sameAccountKind = existingWallet.accountKind === importedWallet.accountKind;
+  const sameSmartAccountOwner = existingWallet.accountKind !== "smart-account" || existingWallet.ownerAddress && importedWallet.ownerAddress && existingWallet.ownerAddress.toLowerCase() === importedWallet.ownerAddress.toLowerCase();
+  const existingSessionPrivateKey = resolveLocalExecutionPrivateKey(existingWallet);
+  const existingLocalExecutionAuthority = existingWallet.localExecutionAuthority || buildLocalExecutionAuthority({
+    privateKey: existingSessionPrivateKey,
+    signerType: existingWallet.sessionPayload?.account?.signerType,
+    source: existingSessionPrivateKey ? "legacy-session-payload" : void 0,
+    attachedAt: existingWallet.createdAt
+  });
+  const importedSessionPrivateKey = resolveLocalExecutionPrivateKey(importedWallet);
+  const shouldPreserveWritableSession = sameAccountKind && sameSmartAccountOwner && Boolean(existingSessionPrivateKey) && !importedSessionPrivateKey;
   const metadataUpdates = {};
   if (existingWallet.smartAccountProfileId) {
     const profileId = tryResolveBuiltinProfileId(existingWallet.smartAccountProfileId);
@@ -13948,7 +14084,13 @@ function preserveExistingWalletMetadata(importedWallet, existingWallet) {
   if (existingWallet.validatorAddress) {
     metadataUpdates.validatorAddress = existingWallet.validatorAddress;
   }
-  return applyWalletSyncMetadata(importedWallet, metadataUpdates);
+  const mergedWallet = shouldPreserveWritableSession && existingLocalExecutionAuthority ? {
+    ...importedWallet,
+    localExecutionAuthority: {
+      ...existingLocalExecutionAuthority
+    }
+  } : importedWallet;
+  return migrateWalletSessionRecord(applyWalletSyncMetadata(mergedWallet, metadataUpdates));
 }
 function linesForWriteResult2(result, nextCommand) {
   const lines = [
@@ -14042,23 +14184,85 @@ function buildWalletApprovalLines(status, requestId, walletRecord) {
   ];
 }
 function buildWalletFollowUpRecommendedCommands(walletRecord) {
+  const localExecutionReady = Boolean(resolveLocalExecutionPrivateKey(walletRecord));
+  const approvalReady = Boolean(walletRecord.sessionPayload);
   return {
     next: buildWalletNextRecommendedCommand(walletRecord.walletName),
     status: buildWalletStatusRecommendedCommand(walletRecord.walletName),
-    ...!walletRecord.sessionPayload?.sessionPrivateKey ? { reapprove: buildWalletReapproveRecommendedCommand(walletRecord.walletName) } : {}
+    ...!localExecutionReady && approvalReady ? {
+      attachSigner: buildWalletSignerAttachRecommendedCommand(walletRecord.walletName),
+      reapprove: buildWalletReapproveRecommendedCommand(walletRecord.walletName)
+    } : !localExecutionReady ? { reapprove: buildWalletReapproveRecommendedCommand(walletRecord.walletName) } : {}
+  };
+}
+function walletSignerSummary(walletRecord) {
+  const authority = walletRecord.localExecutionAuthority;
+  const localExecutionPrivateKey = resolveLocalExecutionPrivateKey(walletRecord);
+  return {
+    approvalReady: Boolean(walletRecord.sessionPayload),
+    localExecutionKeyStored: Boolean(localExecutionPrivateKey),
+    legacySessionKeyStored: Boolean(walletRecord.sessionPayload?.sessionPrivateKey),
+    signerAddress: authority?.signerAddress || deriveAddressFromPrivateKey(localExecutionPrivateKey),
+    signerType: authority?.signerType || walletRecord.sessionPayload?.account?.signerType,
+    source: authority?.source || (walletRecord.sessionPayload?.sessionPrivateKey ? "legacy-session-payload" : void 0),
+    attachedAt: authority?.attachedAt
+  };
+}
+function walletSignerLines(walletRecord) {
+  const signer = walletSignerSummary(walletRecord);
+  return [
+    ["wallet", walletRecord.walletName],
+    ["address", walletRecord.walletAddress],
+    ...displayOwnerAddress(walletRecord) ? [["owner", displayOwnerAddress(walletRecord)]] : [],
+    ["account", displayAccountKind(walletRecord)],
+    ["chain", `${walletRecord.chain} (${walletRecord.chainId})`],
+    ["approval", signer.approvalReady ? "present" : "missing"],
+    ["local signer", signer.localExecutionKeyStored ? "stored" : "missing"],
+    ["legacy payload mirror", signer.legacySessionKeyStored ? "present" : "missing"],
+    ...signer.signerType ? [["signer type", signer.signerType]] : [],
+    ...signer.signerAddress ? [["signer address", signer.signerAddress]] : [],
+    ...signer.source ? [["source", signer.source]] : [],
+    ...signer.attachedAt ? [["attached", signer.attachedAt]] : [],
+    ...walletFollowUpLines(walletRecord)
+  ];
+}
+function walletSignerAttachResult(walletRecord, note) {
+  return {
+    ok: true,
+    wallet: sanitizeWalletRecord(walletRecord),
+    signer: walletSignerSummary(walletRecord),
+    ...note ? { note } : {},
+    nextAction: buildWalletFollowUpNextAction(walletRecord),
+    recommendedCommands: buildWalletFollowUpRecommendedCommands(walletRecord)
   };
 }
+function normalizeSignerType(value) {
+  if (value === "local" || value === "connector" || value === "external") {
+    return value;
+  }
+  throw new Error(`Unsupported signer type: ${value}`);
+}
+function clearLegacySessionPrivateKey(payload) {
+  return payload ? {
+    ...payload,
+    sessionPrivateKey: void 0
+  } : payload;
+}
 function walletFollowUpLines(walletRecord) {
   const recommendedCommands = buildWalletFollowUpRecommendedCommands(walletRecord);
+  const nextCommand = recommendedCommands.attachSigner ?? recommendedCommands.reapprove ?? recommendedCommands.next;
   return [
-    ["next", recommendedCommands.reapprove ?? recommendedCommands.next],
-    ...recommendedCommands.reapprove ? [["after reapprove", recommendedCommands.next]] : [],
+    ["next", nextCommand],
+    ...recommendedCommands.attachSigner ? [
+      ["after signer attach", recommendedCommands.next],
+      ["or reapprove", recommendedCommands.reapprove]
+    ] : recommendedCommands.reapprove ? [["after reapprove", recommendedCommands.next]] : [],
     ["status command", recommendedCommands.status]
   ];
 }
 function buildWalletFollowUpNextAction(walletRecord) {
   const recommendedCommands = buildWalletFollowUpRecommendedCommands(walletRecord);
-  return recommendedCommands.reapprove ?? recommendedCommands.next;
+  return recommendedCommands.attachSigner ?? recommendedCommands.reapprove ?? recommendedCommands.next;
 }
 function buildPendingRequestRecommendedCommands(walletName, requestId, relayUrl, paymasterMode) {
   return {
@@ -14136,7 +14340,7 @@ async function createWalletReapprovalRequest(options) {
     chain: options.walletRecord.chain,
     connectorUrl,
     accountKind: displayAccountKind(options.walletRecord),
-    paymasterMode: displayPaymasterMode(options.walletRecord),
+    paymasterMode: options.paymasterMode || displayPaymasterMode(options.walletRecord),
     policies
   });
   await saveWalletRequest(request);
@@ -14604,6 +14808,9 @@ function createWalletCommand(deps) {
   const resolvedDeps = resolveWalletCommandDeps(deps);
   const wallet = new Command9("wallet").description("Manage wallet sessions");
   const request = new Command9("request").description("Inspect and finalize pending wallet requests");
+  const signer = new Command9("signer").description(
+    "Inspect and manage the stored local execution signer for a wallet"
+  );
   const smartAccount = new Command9("smart-account").description(
     "Predict and deploy zkSync smart-account contracts from a supplied artifact or built-in profile"
   );
@@ -14634,8 +14841,11 @@ function createWalletCommand(deps) {
       "    zk-agent wallet create --await-local",
       "    zk-agent next",
       "",
-      "  Restore a writable session for an existing wallet:",
+      "  Restore approval metadata for an existing wallet:",
       "    zk-agent wallet reapprove --name main --await-local",
+      "",
+      "  Attach a local signer when approval is still present:",
+      "    zk-agent wallet signer attach --name main --private-key <hex>",
       "    zk-agent next",
       "",
       "  Wallet-layer inspection:",
@@ -14643,8 +14853,9 @@ function createWalletCommand(deps) {
       "    zk-agent wallet next --name main",
       "",
       "  Remote approval path:",
-      "    zk-agent wallet create --relay-url <url>",
-      "    zk-agent wallet request approve --request-id <id> --relay-url <url> --code <code> --wait"
+      "    zk-agent relay inspect --relay-url <url>",
+      "    zk-agent wallet create --relay-url <url> --wait-relay --prompt-code",
+      "    zk-agent wallet reapprove --name main --relay-url <url> --wait-relay --prompt-code"
     ].join("\n")
   );
   request.addHelpText(
@@ -14661,6 +14872,21 @@ function createWalletCommand(deps) {
       "    zk-agent wallet request approve --request-id <id> --relay-url <url> --code <code> --wait"
     ].join("\n")
   );
+  signer.addHelpText(
+    "after",
+    [
+      "",
+      "Wallet signer path:",
+      "  Inspect the stored local execution signer state:",
+      "    zk-agent wallet signer show --name main",
+      "",
+      "  Attach a local execution signer without rebuilding approval metadata:",
+      "    zk-agent wallet signer attach --name main --private-key <hex>",
+      "",
+      "  Remove the stored local execution signer:",
+      "    zk-agent wallet signer remove --name main"
+    ].join("\n")
+  );
   smartAccount.addHelpText(
     "after",
     [
@@ -15029,7 +15255,56 @@ function createWalletCommand(deps) {
       }
     );
   });
-  wallet.command("export").description("Export one stored wallet as a portable backup bundle for later restore").option("--name <name>", "Wallet name", "main").option("--include-sensitive-data", "Include sessionPrivateKey in the exported bundle", false).action(async (options) => {
+  signer.command("show").description("Show the stored local execution signer state for a wallet").option("--name <name>", "Wallet name", "main").action(async (options) => {
+    const walletRecord = await requireWalletRecord(options.name);
+    printResult(walletSignerLines(walletRecord), {
+      ok: true,
+      wallet: sanitizeWalletRecord(walletRecord),
+      signer: walletSignerSummary(walletRecord),
+      nextAction: buildWalletFollowUpNextAction(walletRecord),
+      recommendedCommands: buildWalletFollowUpRecommendedCommands(walletRecord)
+    });
+  });
+  signer.command("attach").description("Attach a stored local execution signer to an existing wallet record").option("--name <name>", "Wallet name", "main").requiredOption("--private-key <hex>", "Local execution private key to store").action(async (options) => {
+    const walletRecord = await requireWalletRecord(options.name);
+    const privateKey = normalizePrivateKey(options.privateKey, "--private-key");
+    const nextWallet = migrateWalletSessionRecord({
+      ...walletRecord,
+      localExecutionAuthority: buildLocalExecutionAuthority({
+        privateKey,
+        signerType: "local",
+        source: "explicit-local-approval",
+        attachedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }),
+      sessionPayload: clearLegacySessionPrivateKey(walletRecord.sessionPayload)
+    });
+    const note = walletRecord.sessionPayload ? void 0 : "No approved session metadata is stored yet. Attach succeeded, but wallet reapprove is still required before local write execution becomes usable.";
+    await saveWalletSession(nextWallet);
+    printResult(
+      walletSignerLines(nextWallet),
+      walletSignerAttachResult(nextWallet, note)
+    );
+  });
+  signer.command("remove").description("Remove the stored local execution signer from a wallet record").option("--name <name>", "Wallet name", "main").action(async (options) => {
+    const walletRecord = await requireWalletRecord(options.name);
+    const hadLocalExecutionKey = Boolean(resolveLocalExecutionPrivateKey(walletRecord));
+    const nextWallet = migrateWalletSessionRecord({
+      ...walletRecord,
+      localExecutionAuthority: void 0,
+      sessionPayload: clearLegacySessionPrivateKey(walletRecord.sessionPayload)
+    });
+    const note = hadLocalExecutionKey ? "Removed the stored local execution signer. Local write execution now requires signer attach or reapproval." : "No stored local execution signer was present.";
+    await saveWalletSession(nextWallet);
+    printResult(
+      walletSignerLines(nextWallet),
+      walletSignerAttachResult(nextWallet, note)
+    );
+  });
+  wallet.command("export").description("Export one stored wallet as a portable backup bundle for later restore").option("--name <name>", "Wallet name", "main").option(
+    "--include-sensitive-data",
+    "Include the stored local execution key and any legacy sessionPrivateKey mirror in the exported bundle",
+    false
+  ).action(async (options) => {
     const walletRecord = await requireWalletRecord(options.name);
     const bundle = exportWalletRecord(walletRecord, Boolean(options.includeSensitiveData));
     const recommendedCommands = {
@@ -15334,7 +15609,7 @@ function createWalletCommand(deps) {
       }
     );
   });
-  request.command("approve-local").description("Manually construct an approved session payload from CLI inputs and save the resulting wallet").requiredOption("--request-id <id>", "Wallet request id").requiredOption("--wallet-address <address>", "Approved execution address (EOA address or smart-account address)").option("--owner-address <address>", "Owner / signer address for smart-account sessions").option("--name <name>", "Override saved wallet name").option("--session-address <address>", "Optional session address").option("--session-private-key <hex>", "Optional local private key for writable testnet sessions").option("--validator-address <address>", "Optional validator address").option("--paymaster-address <address>", "Optional paymaster address").option("--paymaster-token <address>", "Optional ERC-20 token used by an approval-based paymaster").option("--signer-type <type>", "Signer type", "connector").action(
+  request.command("approve-local").description("Manually construct an approved session payload from CLI inputs and save the resulting wallet").requiredOption("--request-id <id>", "Wallet request id").requiredOption("--wallet-address <address>", "Approved execution address (EOA address or smart-account address)").option("--owner-address <address>", "Owner / signer address for smart-account sessions").option("--name <name>", "Override saved wallet name").option("--session-address <address>", "Optional session address").option("--session-private-key <hex>", "Optional local execution private key for writable sessions").option("--validator-address <address>", "Optional validator address").option("--paymaster-address <address>", "Optional paymaster address").option("--paymaster-token <address>", "Optional ERC-20 token used by an approval-based paymaster").option("--signer-type <type>", "Optional signer type override: local, connector, or external").action(
     async (options) => {
       const walletRequest = await requireActiveWalletRequest(options.requestId);
       assertRequestActive(walletRequest.expiresAt);
@@ -15354,7 +15629,7 @@ function createWalletCommand(deps) {
         validatorAddress: options.validatorAddress,
         paymasterAddress: options.paymasterAddress,
         paymasterToken: options.paymasterToken,
-        signerType: options.signerType,
+        signerType: options.signerType ? normalizeSignerType(options.signerType) : void 0,
         connectorOrigin: connectorOriginFromUrl(walletRequest.connectorUrl),
         connectorUrl: walletRequest.connectorUrl
       });
@@ -16940,10 +17215,12 @@ function createWalletCommand(deps) {
   sedLite.addCommand(selectorAllowlistHook);
   smartAccount.addCommand(sedLite);
   smartAccount.addCommand(dailySpendLimit);
-  wallet.addCommand(smartAccount);
-  wallet.addCommand(paymaster);
   wallet.addCommand(request);
+  wallet.addCommand(signer);
+  wallet.addCommand(paymaster);
+  wallet.addCommand(smartAccount);
   applyCommandOrder(request, WALLET_REQUEST_HELP_COMMAND_ORDER);
+  applyCommandOrder(signer, WALLET_SIGNER_HELP_COMMAND_ORDER);
   applyCommandOrder(smartAccount, WALLET_SMART_ACCOUNT_HELP_COMMAND_ORDER);
   applyCommandOrder(wallet, WALLET_HELP_COMMAND_ORDER);
   return wallet;
@@ -17375,7 +17652,7 @@ function prependWorkflowRequestId(requestId, lines) {
   return [["workflow request", requestId], ...lines];
 }
 function workflowHasSessionApprovalBlocker(status) {
-  return status.blockingActionIds.some((actionId) => actionId === "reapprove" || actionId === "signer-mismatch");
+  return status.blockingActionIds.some((actionId) => actionId === "reapprove");
 }
 function workflowShouldEnsureWalletSession(options) {
   return Boolean(options.ensureWalletSession || options.awaitLocal);
@@ -17449,10 +17726,14 @@ async function ensureWorkflowWalletSession(input, deps) {
     goal: input.goal,
     options: input.options
   });
+  const paymasterInput = resolveWorkflowPaymasterInput(input.options);
   const reusableRequest = await deps.findReusableWalletRequest(input.wallet.walletName);
   const walletRequest = reusableRequest || await deps.createWalletReapprovalRequest({
     walletRecord: input.wallet,
     connectorUrl: input.options.connectorUrl,
+    ...paymasterInput?.mode ? {
+      paymasterMode: paymasterInput.mode
+    } : {},
     sessionPreset: policyRequestOptions.sessionPreset,
     sessionHours: policyRequestOptions.sessionHours,
     allowTransferTo: policyRequestOptions.allowTransferTo,
@@ -17805,6 +18086,17 @@ function buildWorkflowAutoCheckpoint(context, status) {
     status
   });
 }
+function applyWorkflowPayDefaults(options) {
+  return {
+    ...options,
+    intent: "send-native",
+    createCheckpoint: true,
+    executeWhenReady: true,
+    ensureWalletSession: true,
+    sessionPreset: options.sessionPreset?.trim() || "intent",
+    paymasterMode: options.paymasterMode?.trim() || "approval-based"
+  };
+}
 async function executeWorkflowAutoCommand(options, deps = resolveWorkflowCommandDeps(void 0)) {
   const { provider: provider4, defiProvider: defiProvider2 } = deps;
   const context = await resolveWorkflowAutoExecutionContext(options);
@@ -18359,6 +18651,9 @@ function buildWorkflowHelpText() {
     "  Guided default:",
     "    zk-agent workflow auto --wallet main --intent <intent> [goal flags] --create-checkpoint --execute-when-ready",
     "",
+    "  Flagship native pay path:",
+    "    zk-agent workflow pay --wallet main --to <address> --amount <amount>",
+    "",
     "  Checkpointed execution:",
     "    zk-agent workflow start --wallet main --intent <intent> [goal flags]",
     "    zk-agent workflow status --request-id <id>",
@@ -18374,6 +18669,7 @@ function buildWorkflowHelpText() {
 }
 var WORKFLOW_HELP_COMMAND_ORDER = [
   "auto",
+  "pay",
   "start",
   "status",
   "next",
@@ -18597,6 +18893,23 @@ function createWorkflowCommand(deps) {
     const execution = await executeWorkflowAutoCommand(options, resolvedDeps);
     await printWorkflowAutoCommandResult(execution);
   }));
+  const pay = workflow.command("pay").description(
+    "Guided flagship AA native-send path with checkpoint persistence, intent-scoped session recovery, and paymaster-aware defaults"
+  ).option("--wallet <name>", "Wallet name", "main").option(
+    "--request-id <id>",
+    "Load the workflow definition from a stored checkpoint, or reserve this id for the flagship pay path"
+  );
+  addWorkflowGoalOptions(pay, {
+    includeExecutionFlags: true,
+    includeFundingDispatch: true,
+    includeLocalApproval: true
+  }).action(withWorkflowInputErrorHandling(async (options) => {
+    const execution = await executeWorkflowAutoCommand(
+      applyWorkflowPayDefaults(options),
+      resolvedDeps
+    );
+    await printWorkflowAutoCommandResult(execution);
+  }));
   const run = workflow.command("run").description("Run the requested workflow, or stop on the next required prerequisite or funding step first").option(
     "--intent <intent>",
     "send-native, send-token, call-write, swap, bridge, deposit, or withdraw"