@onekeyfe/hardware-cli 1.2.0-alpha.19 → 1.2.0-alpha.20

package/dist/cli.js

@@ -3,11 +3,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.program = exports.buildWallpaperUploadMetrics = exports.getLegacyFirmwareConnectTimeout = void 0;
 const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const commander_1 = require("commander");
 const hd_core_1 = require("@onekeyfe/hd-core");
 const hd_shared_1 = require("@onekeyfe/hd-shared");
 const chains_1 = require("./chains");
 const deviceSelection_1 = require("./deviceSelection");
+const deviceStateCommands_1 = require("./deviceStateCommands");
 const sdk_1 = require("./sdk");
 const session_1 = require("./session");
 function extractPassphraseSession(payload) {
@@ -36,10 +38,11 @@ function extractPassphraseSession(payload) {
 }
 const program = new commander_1.Command();
 exports.program = program;
+const { version: cliVersion } = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.resolve)(__dirname, '../package.json'), 'utf8'));
 program
     .name('onekey-hw')
     .description('OneKey hardware wallet CLI for AI agent integration')
-    .version('1.1.26-alpha.1');
+    .version(cliVersion);
 // ============================================================
 // Global Options
 // ============================================================
@@ -57,49 +60,27 @@ program
     .description('Search for connected OneKey hardware wallet devices')
     .action(() => runCommand({}, async ({ sdk, globalOpts }) => {
     const result = await sdk.searchDevices();
-    // USB 下自动读取 features 成本低；BLE 搜索阶段只做枚举，避免批量连接导致超时。
-    if (globalOpts.transport !== 'ble' && result?.success && Array.isArray(result.payload)) {
-        for (const device of result.payload) {
-            if (device.connectId) {
-                try {
-                    const features = await sdk.getFeatures(device.connectId);
-                    if (features?.success && features.payload) {
-                        device.features = features.payload;
-                        device.name = features.payload.label || features.payload.bleName || device.name;
-                        const devType = features.payload.deviceType?.toLowerCase();
-                        if (devType) {
-                            device.deviceType = devType;
-                        }
-                    }
-                }
-                catch {
-                    // Features fetch failed — device may need PIN, continue with basic info
-                }
-            }
-        }
-    }
     outputResult(globalOpts, result);
 }));
 program
     .command('get-features')
     .description('Get device features (firmware, unlock state, passphrase protection, etc.)')
     .action(() => runCommand({}, async ({ sdk, globalOpts }) => {
-    // Resolve connectId: explicit flag wins, else pick the first attached device
-    let { connectId } = globalOpts;
-    if (!connectId) {
-        const searchResult = await sdk.searchDevices();
-        if (!searchResult?.success ||
-            !Array.isArray(searchResult.payload) ||
-            searchResult.payload.length === 0) {
-            outputResult(globalOpts, {
-                success: false,
-                payload: { error: 'No device found', code: 'NO_DEVICE' },
-            });
-            return;
-        }
-        connectId = searchResult.payload[0].connectId ?? undefined;
+    const result = await (0, deviceStateCommands_1.getCompatibleFeatures)(sdk, globalOpts.connectId);
+    outputResult(globalOpts, result);
+}));
+program
+    .command('get-state')
+    .description('Get canonical device state for Protocol V1 and Protocol V2 devices')
+    .option('--scope <scope>', 'State refresh scope: runtime, settings, or firmware', 'runtime')
+    .action((opts) => runCommand({}, async ({ sdk, globalOpts }) => {
+    const supportedScopes = ['runtime', 'settings', 'firmware'];
+    if (!supportedScopes.includes(opts.scope)) {
+        const error = new Error(`Unsupported device state scope: ${opts.scope}`);
+        error.code = 'INVALID_DEVICE_STATE_SCOPE';
+        throw error;
     }
-    const result = await sdk.getFeatures(connectId || '');
+    const result = await (0, deviceStateCommands_1.getCanonicalDeviceState)(sdk, globalOpts.connectId, opts.scope);
     outputResult(globalOpts, result);
 }));
 program
@@ -859,7 +840,7 @@ globalOpts) {
     // getFeatures failures here are non-fatal — we fall through to Step 3
     // which will fail with a clearer error if the device is truly unreachable.
     let deviceId = selectedDevice.features?.deviceId || selectedDevice.deviceId || '';
-    let deviceType = (0, hd_core_1.getDeviceType)(selectedDevice.features);
+    let deviceType = selectedDevice.features?.deviceType ?? selectedDevice.deviceType ?? hd_shared_1.EDeviceType.Unknown;
     let unlocked = selectedDevice.features?.unlocked;
     let passphraseProtection = selectedDevice.features?.passphraseProtection;
     if (!deviceId || unlocked == null || passphraseProtection == null) {
@@ -947,8 +928,8 @@ function outputResult(_globalOpts, result) {
         !result.success) {
         process.exitCode = 1;
     }
-    // No process.exit here — runCommand() below handles dispose + exit so SDK
-    // async cleanup (USB release, event listener teardown) finishes first.
+    // No process.exit here — runCommand() waits for SDK cleanup, then lets Node
+    // exit naturally so leaked USB handles remain observable.
 }
 async function runCommand(options, handler) {
     const globalOpts = program.opts();
@@ -981,9 +962,7 @@ async function runCommand(options, handler) {
         // promise reference. Idempotent, safe to call even if init failed.
         await (0, sdk_1.disposeSDK)();
     }
-    // SDK event listeners can keep the event loop alive after dispose.
-    // setImmediate lets any trailing stdout/stderr writes flush first.
-    setImmediate(() => process.exit(process.exitCode ?? 0));
+    // disposeSDK awaits transport cleanup; let Node exit naturally so leaks remain visible.
 }
 /** For commands that don't touch the SDK at all (e.g. firmware-update stubs). */
 function respondAndExit(result) {
@@ -1021,16 +1000,18 @@ async function resolveLegacyFirmwareConnectId(sdk, explicitConnectId, deviceName
         ? devices.filter(device => device.name?.trim().toLowerCase() === normalizedName)
         : devices.filter(device => device.deviceType?.toLowerCase() === 'classic');
     if (matches.length === 0) {
-        throw new Error(normalizedName ? `BLE device not found by name: ${deviceName}` : 'No Classic/Pure BLE device found');
+        throw new Error(normalizedName
+            ? `BLE device not found by name: ${deviceName}`
+            : 'No Classic/Pure BLE device found');
     }
     if (matches.length > 1) {
         throw new Error(normalizedName
             ? `Multiple BLE devices found by name: ${deviceName}`
             : 'Multiple Classic/Pure BLE devices found; specify --device-name');
     }
-    const connectId = matches[0].connectId;
+    const [{ connectId, name }] = matches;
     if (!connectId)
-        throw new Error(`BLE device has no connect ID: ${matches[0].name}`);
+        throw new Error(`BLE device has no connect ID: ${name}`);
     return connectId;
 }
 function parseResourceBundleParam(spec) {
@@ -1100,9 +1081,7 @@ function buildWallpaperUploadMetrics({ totalBytes, transferredBytes, startedAt,
         totalBytes,
         transferredBytes,
         totalSeconds: Number((elapsedMs / 1000).toFixed(2)),
-        transferKiBPerSecond: elapsedMs > 0
-            ? Number((transferredBytes / 1024 / (elapsedMs / 1000)).toFixed(2))
-            : null,
+        transferKiBPerSecond: elapsedMs > 0 ? Number((transferredBytes / 1024 / (elapsedMs / 1000)).toFixed(2)) : null,
         lastProgress,
     };
 }

package/dist/deviceStateCommands.d.ts

@@ -0,0 +1,19 @@
+import type { CoreApi, DeviceStateScope } from '@onekeyfe/hd-core';
+type DeviceStateSdk = Pick<CoreApi, 'searchDevices' | 'getDeviceState' | 'getFeatures'>;
+/**
+ * Unified state entry for the new CLI. Resolve the user-facing connectId through
+ * discovery so V1 serial IDs map to the process-local USB path.
+ */
+export declare const getCanonicalDeviceState: (sdk: DeviceStateSdk, connectId: string | undefined, scope: DeviceStateScope) => Promise<import("@onekeyfe/hd-core").Unsuccessful | {
+    success: true;
+    payload: import("@onekeyfe/hd-core").DeviceState;
+}>;
+/**
+ * Legacy CLI only: retain getFeatures for V1 and reuse the discovery projection for V2.
+ * Public SDK.getFeatures remains V1-only.
+ */
+export declare const getCompatibleFeatures: (sdk: DeviceStateSdk, connectId?: string) => Promise<import("@onekeyfe/hd-core").Unsuccessful | {
+    success: true;
+    payload: import("@onekeyfe/hd-core").Features;
+}>;
+export {};

package/dist/deviceStateCommands.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCompatibleFeatures = exports.getCanonicalDeviceState = void 0;
+const createDeviceNotFoundResult = (connectId) => ({
+    success: false,
+    payload: {
+        code: 'DEVICE_NOT_FOUND',
+        error: connectId ? `Device not found: ${connectId}` : 'No device found',
+    },
+});
+const resolveSearchDevice = async (sdk, connectId) => {
+    const searchResult = await sdk.searchDevices();
+    if (!searchResult.success)
+        return searchResult;
+    const devices = searchResult.payload;
+    const device = connectId ? devices.find(item => item.connectId === connectId) : devices[0];
+    if (!device?.connectId)
+        return createDeviceNotFoundResult(connectId);
+    return { success: true, payload: device };
+};
+/**
+ * Unified state entry for the new CLI. Resolve the user-facing connectId through
+ * discovery so V1 serial IDs map to the process-local USB path.
+ */
+const getCanonicalDeviceState = async (sdk, connectId, scope) => {
+    const deviceResult = await resolveSearchDevice(sdk, connectId);
+    if (!deviceResult.success)
+        return deviceResult;
+    if (scope === 'runtime' && deviceResult.payload.state) {
+        return { success: true, payload: deviceResult.payload.state };
+    }
+    const resolvedConnectId = deviceResult.payload.connectId ?? undefined;
+    if (!resolvedConnectId)
+        return createDeviceNotFoundResult();
+    return sdk.getDeviceState(resolvedConnectId, { scope });
+};
+exports.getCanonicalDeviceState = getCanonicalDeviceState;
+/**
+ * Legacy CLI only: retain getFeatures for V1 and reuse the discovery projection for V2.
+ * Public SDK.getFeatures remains V1-only.
+ */
+const getCompatibleFeatures = async (sdk, connectId) => {
+    const deviceResult = await resolveSearchDevice(sdk, connectId);
+    if (!deviceResult.success)
+        return deviceResult;
+    const device = deviceResult.payload;
+    const protocol = device.state?.protocol ?? device.features?.protocol;
+    if (protocol === 'V2') {
+        if (!device.features) {
+            return {
+                success: false,
+                payload: {
+                    code: 'DEVICE_FEATURES_UNAVAILABLE',
+                    error: 'Protocol V2 compatibility features are unavailable',
+                },
+            };
+        }
+        return { success: true, payload: device.features };
+    }
+    return sdk.getFeatures(device.connectId ?? '');
+};
+exports.getCompatibleFeatures = getCompatibleFeatures;

package/dist/sdk.js

@@ -168,12 +168,12 @@ function registerEventHandlers(sdk) {
             process.stderr.write('[onekey-hw] Please confirm the action on your device...\n');
         }
     });
-    sdk.on(hd_core_1.DEVICE.CONNECT, (device) => {
+    sdk.on(hd_core_1.DEVICE.CONNECT, ({ device }) => {
         const name = device?.label || device?.name;
         if (name)
             process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
     });
-    sdk.on(hd_core_1.DEVICE.DISCONNECT, (device) => {
+    sdk.on(hd_core_1.DEVICE.DISCONNECT, ({ device }) => {
         const name = device?.label || device?.name;
         if (name)
             process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
@@ -222,7 +222,7 @@ async function disposeSDK() {
         return;
     try {
         const sdk = await sdkReadyPromise;
-        sdk.dispose();
+        await Promise.resolve(sdk.dispose());
     }
     catch {
         // ignore errors during cleanup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hardware-cli",
-  "version": "1.2.0-alpha.19",
+  "version": "1.2.0-alpha.20",
   "description": "OneKey hardware wallet CLI for testing device communication",
   "author": "OneKey",
   "license": "Apache-2.0",
@@ -23,6 +23,7 @@
     "start": "node dist/cli.js",
     "search": "node dist/cli.js search",
     "get-features": "node dist/cli.js get-features",
+    "get-state": "node dist/cli.js get-state",
     "get-address": "node dist/cli.js get-address",
     "ping": "node dist/cli.js ping",
     "lint": "eslint .",
@@ -30,12 +31,12 @@
     "test": "jest"
   },
   "dependencies": {
-    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.19",
-    "@onekeyfe/hd-core": "1.2.0-alpha.19",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.19",
-    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.19",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.20",
+    "@onekeyfe/hd-core": "1.2.0-alpha.20",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.20",
+    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.20",
     "@stoprocent/noble": "2.3.16",
     "commander": "^12.0.0"
   },
-  "gitHead": "4e79f6a400463f342285b9a761b6b84523f1d6b9"
+  "gitHead": "5fbc1ada90fd3cfda7e5ef08be368cb452018733"
 }

package/src/__tests__/cli-version.test.ts

@@ -0,0 +1,8 @@
+import packageJson from '../../package.json';
+import { program } from '../cli';
+
+describe('CLI 版本', () => {
+  test('与发布包 package.json 使用同一个版本来源', () => {
+    expect(program.version()).toBe(packageJson.version);
+  });
+});

package/src/__tests__/device-state-commands.test.ts

@@ -0,0 +1,118 @@
+import { getCanonicalDeviceState, getCompatibleFeatures } from '../deviceStateCommands';
+
+const createSdkMock = () => ({
+  searchDevices: jest.fn(),
+  getDeviceState: jest.fn(),
+  getFeatures: jest.fn(),
+});
+
+describe('设备状态 CLI 兼容层', () => {
+  test('Protocol V2 直接返回 SDK 搜索结果中的兼容 features', async () => {
+    const sdk = createSdkMock();
+    const features = {
+      protocol: 'V2',
+      deviceType: 'pro2',
+      deviceId: 'device-id',
+    };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [
+        {
+          connectId: 'pro2-connect-id',
+          state: { protocol: 'V2' },
+          features,
+        },
+      ],
+    });
+
+    await expect(getCompatibleFeatures(sdk as never, 'pro2-connect-id')).resolves.toEqual({
+      success: true,
+      payload: features,
+    });
+    expect(sdk.getFeatures).not.toHaveBeenCalled();
+  });
+
+  test('Protocol V1 继续调用公共 getFeatures 保持旧行为', async () => {
+    const sdk = createSdkMock();
+    const response = {
+      success: true,
+      payload: { protocol: 'V1', label: 'Classic' },
+    };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [
+        {
+          connectId: 'classic-connect-id',
+          state: { protocol: 'V1' },
+        },
+      ],
+    });
+    sdk.getFeatures.mockResolvedValue(response);
+
+    await expect(getCompatibleFeatures(sdk as never, 'classic-connect-id')).resolves.toBe(response);
+    expect(sdk.getFeatures).toHaveBeenCalledWith('classic-connect-id');
+  });
+
+  test('未显式指定设备时选择搜索结果中的第一台设备', async () => {
+    const sdk = createSdkMock();
+    const response = { success: true, payload: { protocol: 'V1' } };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'first-device', state: { protocol: 'V1' } }],
+    });
+    sdk.getFeatures.mockResolvedValue(response);
+
+    await expect(getCompatibleFeatures(sdk as never)).resolves.toBe(response);
+    expect(sdk.getFeatures).toHaveBeenCalledWith('first-device');
+  });
+
+  test('显式 connectId 不在搜索结果时返回结构化错误', async () => {
+    const sdk = createSdkMock();
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'another-device', state: { protocol: 'V1' } }],
+    });
+
+    await expect(getCompatibleFeatures(sdk as never, 'missing-device')).resolves.toEqual({
+      success: false,
+      payload: {
+        code: 'DEVICE_NOT_FOUND',
+        error: 'Device not found: missing-device',
+      },
+    });
+    expect(sdk.getFeatures).not.toHaveBeenCalled();
+  });
+
+  test('get-state 将 firmware scope 传给 SDK', async () => {
+    const sdk = createSdkMock();
+    const response = { success: true, payload: { protocol: 'V2' } };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'pro2-connect-id', state: { protocol: 'V2' } }],
+    });
+    sdk.getDeviceState.mockResolvedValue(response);
+
+    await expect(
+      getCanonicalDeviceState(sdk as never, 'pro2-connect-id', 'firmware')
+    ).resolves.toBe(response);
+    expect(sdk.getDeviceState).toHaveBeenCalledWith('pro2-connect-id', {
+      scope: 'firmware',
+    });
+    expect(sdk.searchDevices).toHaveBeenCalledTimes(1);
+  });
+
+  test('get-state 未指定 connectId 时搜索并选择第一台设备', async () => {
+    const sdk = createSdkMock();
+    const state = { protocol: 'V2', revision: 2 };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'pro2-connect-id', state }],
+    });
+
+    await expect(getCanonicalDeviceState(sdk as never, undefined, 'runtime')).resolves.toEqual({
+      success: true,
+      payload: state,
+    });
+    expect(sdk.getDeviceState).not.toHaveBeenCalled();
+  });
+});

package/src/cli.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { Command } from 'commander';
 import { UI_EVENT, UI_REQUEST, getDeviceType } from '@onekeyfe/hd-core';
 import { EDeviceType } from '@onekeyfe/hd-shared';
@@ -11,6 +12,7 @@ import {
   resolveSignTransaction,
 } from './chains';
 import { selectSearchDevice } from './deviceSelection';
+import { getCanonicalDeviceState, getCompatibleFeatures } from './deviceStateCommands';
 import { createSDK, disposeSDK } from './sdk';
 import {
   clearSessionFromKeychain,
@@ -19,10 +21,10 @@ import {
 } from './session';
 
 import type {
+  DeviceStateScope,
   EthereumSignTypedDataMessage,
   EthereumSignTypedDataTypes,
   Features,
-  IDeviceType,
   SearchDevice,
 } from '@onekeyfe/hd-core';
 
@@ -65,11 +67,14 @@ function extractPassphraseSession(payload: unknown): {
 }
 
 const program = new Command();
+const { version: cliVersion } = JSON.parse(
+  readFileSync(resolve(__dirname, '../package.json'), 'utf8')
+) as { version: string };
 
 program
   .name('onekey-hw')
   .description('OneKey hardware wallet CLI for AI agent integration')
-  .version('1.1.26-alpha.1');
+  .version(cliVersion);
 
 // ============================================================
 // Global Options
@@ -95,28 +100,6 @@ program
   .action(() =>
     runCommand({}, async ({ sdk, globalOpts }) => {
       const result = await sdk.searchDevices();
-
-      // USB 下自动读取 features 成本低；BLE 搜索阶段只做枚举，避免批量连接导致超时。
-      if (globalOpts.transport !== 'ble' && result?.success && Array.isArray(result.payload)) {
-        for (const device of result.payload as EnrichedSearchDevice[]) {
-          if (device.connectId) {
-            try {
-              const features = await sdk.getFeatures(device.connectId);
-              if (features?.success && features.payload) {
-                device.features = features.payload;
-                device.name = features.payload.label || features.payload.bleName || device.name;
-                const devType = features.payload.deviceType?.toLowerCase();
-                if (devType) {
-                  device.deviceType = devType as IDeviceType;
-                }
-              }
-            } catch {
-              // Features fetch failed — device may need PIN, continue with basic info
-            }
-          }
-        }
-      }
-
       outputResult(globalOpts, result);
     })
   );
@@ -126,24 +109,28 @@ program
   .description('Get device features (firmware, unlock state, passphrase protection, etc.)')
   .action(() =>
     runCommand({}, async ({ sdk, globalOpts }) => {
-      // Resolve connectId: explicit flag wins, else pick the first attached device
-      let { connectId } = globalOpts as { connectId?: string };
-      if (!connectId) {
-        const searchResult = await sdk.searchDevices();
-        if (
-          !searchResult?.success ||
-          !Array.isArray(searchResult.payload) ||
-          searchResult.payload.length === 0
-        ) {
-          outputResult(globalOpts, {
-            success: false,
-            payload: { error: 'No device found', code: 'NO_DEVICE' },
-          });
-          return;
-        }
-        connectId = (searchResult.payload[0] as EnrichedSearchDevice).connectId ?? undefined;
+      const result = await getCompatibleFeatures(sdk, globalOpts.connectId);
+      outputResult(globalOpts, result);
+    })
+  );
+
+program
+  .command('get-state')
+  .description('Get canonical device state for Protocol V1 and Protocol V2 devices')
+  .option('--scope <scope>', 'State refresh scope: runtime, settings, or firmware', 'runtime')
+  .action((opts: { scope: string }) =>
+    runCommand({}, async ({ sdk, globalOpts }) => {
+      const supportedScopes: DeviceStateScope[] = ['runtime', 'settings', 'firmware'];
+      if (!supportedScopes.includes(opts.scope as DeviceStateScope)) {
+        const error = new Error(`Unsupported device state scope: ${opts.scope}`);
+        (error as Error & { code?: string }).code = 'INVALID_DEVICE_STATE_SCOPE';
+        throw error;
       }
-      const result = await sdk.getFeatures(connectId || '');
+      const result = await getCanonicalDeviceState(
+        sdk,
+        globalOpts.connectId,
+        opts.scope as DeviceStateScope
+      );
       outputResult(globalOpts, result);
     })
   );
@@ -860,7 +847,7 @@ sessionCmd
         });
         return;
       }
-      const device = searchResult.payload[0] as EnrichedSearchDevice;
+      const device: EnrichedSearchDevice = searchResult.payload[0];
       const connectId = device.connectId || globalOpts.connectId;
 
       // 2. Unlock if locked — getPassphraseState below talks to a live
@@ -1070,6 +1057,7 @@ async function prepareSession(
     searchResult.payload as Array<{
       connectId?: string;
       deviceId?: string;
+      deviceType?: string;
       features?: {
         deviceId?: string | null;
         deviceType?: string;
@@ -1088,6 +1076,7 @@ async function prepareSession(
   const selectedDevice = device as {
     connectId?: string;
     deviceId?: string;
+    deviceType?: string;
     features?: {
       deviceId?: string | null;
       deviceType?: string;
@@ -1105,7 +1094,8 @@ async function prepareSession(
   // getFeatures failures here are non-fatal — we fall through to Step 3
   // which will fail with a clearer error if the device is truly unreachable.
   let deviceId = selectedDevice.features?.deviceId || selectedDevice.deviceId || '';
-  let deviceType = getDeviceType(selectedDevice.features as Features | undefined);
+  let deviceType =
+    selectedDevice.features?.deviceType ?? selectedDevice.deviceType ?? EDeviceType.Unknown;
   let unlocked = selectedDevice.features?.unlocked;
   let passphraseProtection = selectedDevice.features?.passphraseProtection;
 
@@ -1207,8 +1197,8 @@ function outputResult(_globalOpts: Record<string, any>, result: unknown): void {
   ) {
     process.exitCode = 1;
   }
-  // No process.exit here — runCommand() below handles dispose + exit so SDK
-  // async cleanup (USB release, event listener teardown) finishes first.
+  // No process.exit here — runCommand() waits for SDK cleanup, then lets Node
+  // exit naturally so leaked USB handles remain observable.
 }
 
 /**
@@ -1220,7 +1210,7 @@ function outputResult(_globalOpts: Record<string, any>, result: unknown): void {
  *   3. run the handler (which calls outputResult on success)
  *   4. report uncaught errors as a structured failure result
  *   5. dispose SDK
- *   6. drain event loop and process.exit with the right code
+ *   6. let Node exit naturally after all SDK resources are released
  *
  * This fixes three previous bugs:
  *   - Most signing commands skipped prepareSession, so keychain sessions
@@ -1272,9 +1262,7 @@ async function runCommand(
     // promise reference. Idempotent, safe to call even if init failed.
     await disposeSDK();
   }
-  // SDK event listeners can keep the event loop alive after dispose.
-  // setImmediate lets any trailing stdout/stderr writes flush first.
-  setImmediate(() => process.exit(process.exitCode ?? 0));
+  // disposeSDK awaits transport cleanup; let Node exit naturally so leaks remain visible.
 }
 
 /** For commands that don't touch the SDK at all (e.g. firmware-update stubs). */
@@ -1322,7 +1310,9 @@ async function resolveLegacyFirmwareConnectId(
 
   if (matches.length === 0) {
     throw new Error(
-      normalizedName ? `BLE device not found by name: ${deviceName}` : 'No Classic/Pure BLE device found'
+      normalizedName
+        ? `BLE device not found by name: ${deviceName}`
+        : 'No Classic/Pure BLE device found'
     );
   }
   if (matches.length > 1) {
@@ -1333,8 +1323,8 @@ async function resolveLegacyFirmwareConnectId(
     );
   }
 
-  const connectId = matches[0].connectId;
-  if (!connectId) throw new Error(`BLE device has no connect ID: ${matches[0].name}`);
+  const [{ connectId, name }] = matches;
+  if (!connectId) throw new Error(`BLE device has no connect ID: ${name}`);
   return connectId;
 }
 
@@ -1429,9 +1419,7 @@ export function buildWallpaperUploadMetrics({
     transferredBytes,
     totalSeconds: Number((elapsedMs / 1000).toFixed(2)),
     transferKiBPerSecond:
-      elapsedMs > 0
-        ? Number((transferredBytes / 1024 / (elapsedMs / 1000)).toFixed(2))
-        : null,
+      elapsedMs > 0 ? Number((transferredBytes / 1024 / (elapsedMs / 1000)).toFixed(2)) : null,
     lastProgress,
   };
 }

package/src/deviceStateCommands.ts

@@ -0,0 +1,71 @@
+import type { CoreApi, DeviceStateScope, KnownDevice, SearchDevice } from '@onekeyfe/hd-core';
+
+type DeviceStateSdk = Pick<CoreApi, 'searchDevices' | 'getDeviceState' | 'getFeatures'>;
+
+type DiscoveredDevice = SearchDevice & Partial<Pick<KnownDevice, 'features' | 'state'>>;
+
+const createDeviceNotFoundResult = (connectId?: string) => ({
+  success: false as const,
+  payload: {
+    code: 'DEVICE_NOT_FOUND',
+    error: connectId ? `Device not found: ${connectId}` : 'No device found',
+  },
+});
+
+const resolveSearchDevice = async (sdk: DeviceStateSdk, connectId?: string) => {
+  const searchResult = await sdk.searchDevices();
+  if (!searchResult.success) return searchResult;
+
+  const devices = searchResult.payload as DiscoveredDevice[];
+  const device = connectId ? devices.find(item => item.connectId === connectId) : devices[0];
+
+  if (!device?.connectId) return createDeviceNotFoundResult(connectId);
+  return { success: true as const, payload: device };
+};
+
+/**
+ * Unified state entry for the new CLI. Resolve the user-facing connectId through
+ * discovery so V1 serial IDs map to the process-local USB path.
+ */
+export const getCanonicalDeviceState = async (
+  sdk: DeviceStateSdk,
+  connectId: string | undefined,
+  scope: DeviceStateScope
+) => {
+  const deviceResult = await resolveSearchDevice(sdk, connectId);
+  if (!deviceResult.success) return deviceResult;
+
+  if (scope === 'runtime' && deviceResult.payload.state) {
+    return { success: true as const, payload: deviceResult.payload.state };
+  }
+
+  const resolvedConnectId = deviceResult.payload.connectId ?? undefined;
+  if (!resolvedConnectId) return createDeviceNotFoundResult();
+  return sdk.getDeviceState(resolvedConnectId, { scope });
+};
+
+/**
+ * Legacy CLI only: retain getFeatures for V1 and reuse the discovery projection for V2.
+ * Public SDK.getFeatures remains V1-only.
+ */
+export const getCompatibleFeatures = async (sdk: DeviceStateSdk, connectId?: string) => {
+  const deviceResult = await resolveSearchDevice(sdk, connectId);
+  if (!deviceResult.success) return deviceResult;
+
+  const device = deviceResult.payload;
+  const protocol = device.state?.protocol ?? device.features?.protocol;
+  if (protocol === 'V2') {
+    if (!device.features) {
+      return {
+        success: false as const,
+        payload: {
+          code: 'DEVICE_FEATURES_UNAVAILABLE',
+          error: 'Protocol V2 compatibility features are unavailable',
+        },
+      };
+    }
+    return { success: true as const, payload: device.features };
+  }
+
+  return sdk.getFeatures(device.connectId ?? '');
+};

package/src/sdk.ts

@@ -16,7 +16,7 @@ import { DEVICE, UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core';
 import { promptPassphraseViaPinentry } from './pinentry';
 import { createNobleBlePlugin } from './transports/nobleBlePlugin';
 
-import type { ConnectSettings } from '@onekeyfe/hd-core';
+import type { ConnectSettings, KnownDevice } from '@onekeyfe/hd-core';
 import type { PinentryResult } from './pinentry';
 
 export interface SDKOptions {
@@ -169,12 +169,12 @@ function registerEventHandlers(sdk: typeof HardwareSDK): void {
     }
   });
 
-  sdk.on(DEVICE.CONNECT, (device: any) => {
+  sdk.on(DEVICE.CONNECT, ({ device }: { device: KnownDevice }) => {
     const name = device?.label || device?.name;
     if (name) process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
   });
 
-  sdk.on(DEVICE.DISCONNECT, (device: any) => {
+  sdk.on(DEVICE.DISCONNECT, ({ device }: { device: KnownDevice }) => {
     const name = device?.label || device?.name;
     if (name) process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
   });
@@ -231,7 +231,7 @@ export async function disposeSDK(): Promise<void> {
   if (!sdkReadyPromise) return;
   try {
     const sdk = await sdkReadyPromise;
-    sdk.dispose();
+    await Promise.resolve(sdk.dispose());
   } catch {
     // ignore errors during cleanup
   } finally {