@zhihand/mcp 0.29.0 → 0.32.0

package/dist/daemon/dispatcher.d.ts

@@ -1,4 +1,5 @@
-import type { ZhiHandConfig, BackendName } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig, BackendName } from "../core/config.ts";
+type ZhiHandConfig = ZhiHandRuntimeConfig;
 export interface DispatchResult {
     text: string;
     success: boolean;
@@ -10,3 +11,4 @@ export interface DispatchResult {
 export declare function killActiveChild(): Promise<void>;
 export declare function dispatchToCLI(backend: Exclude<BackendName, "openclaw">, prompt: string, log: (msg: string) => void, model?: string): Promise<DispatchResult>;
 export declare function postReply(config: ZhiHandConfig, promptId: string, text: string): Promise<boolean>;
+export {};

package/dist/daemon/dispatcher.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_MODELS } from "../core/config.js";
 import { resolveGemini, resolveClaude, resolveCodex } from "../core/resolve-path.js";
-import { getStaticContext, isDeviceProfileLoaded } from "../core/device.js";
+import { registry } from "../core/registry.js";
 import { dbg } from "./logger.js";
 const CLI_TIMEOUT = 300_000; // 300s (5min) per prompt — MCP tool chains need multiple turns
 const SIGKILL_DELAY = 2_000; // 2s after SIGTERM
@@ -357,7 +357,8 @@ export async function killActiveChild() {
  * so the AI sends correct platform-specific parameters (e.g. appPackage vs bundleId).
  */
 function buildSystemContext() {
-    const static_ = isDeviceProfileLoaded() ? getStaticContext() : null;
+    const defaultState = registry.resolveDefault();
+    const static_ = defaultState?.profile ?? null;
     const deviceLine = static_
         ? `Connected device: ${static_.platform} ${static_.model} (${static_.osVersion}), ${static_.screenWidthPx}x${static_.screenHeightPx}, ${static_.formFactor}, ${static_.locale}`
         : "Connected device: unknown platform";
@@ -778,7 +779,7 @@ export async function postReply(config, promptId, text) {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "x-zhihand-controller-token": config.controllerToken,
+                "Authorization": `Bearer ${config.controllerToken}`,
             },
             body: JSON.stringify({ role: "assistant", text }),
             signal: AbortSignal.timeout(30_000),

package/dist/daemon/heartbeat.d.ts

@@ -1,4 +1,4 @@
-import type { ZhiHandConfig } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
 /** Brain metadata included in every heartbeat, so the app always knows the current backend/model. */
 export interface BrainMeta {
     backend?: string | null;
@@ -6,7 +6,7 @@ export interface BrainMeta {
 }
 /** Update the backend/model metadata that will be sent with the next heartbeat. */
 export declare function setBrainMeta(meta: BrainMeta): void;
-export declare function sendBrainOnline(config: ZhiHandConfig): Promise<boolean>;
-export declare function sendBrainOffline(config: ZhiHandConfig): Promise<boolean>;
-export declare function startHeartbeatLoop(config: ZhiHandConfig, log: (msg: string) => void): void;
+export declare function sendBrainOnline(config: ZhiHandRuntimeConfig): Promise<boolean>;
+export declare function sendBrainOffline(config: ZhiHandRuntimeConfig): Promise<boolean>;
+export declare function startHeartbeatLoop(config: ZhiHandRuntimeConfig, log: (msg: string) => void): void;
 export declare function stopHeartbeatLoop(): void;

package/dist/daemon/heartbeat.js

@@ -25,7 +25,7 @@ async function sendHeartbeat(config, online) {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "x-zhihand-controller-token": config.controllerToken,
+                "Authorization": `Bearer ${config.controllerToken}`,
             },
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(10_000),

package/dist/daemon/index.js

@@ -11,10 +11,10 @@ import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline, setBrainMeta }
 import { PromptListener } from "./prompt-listener.js";
 import { dispatchToCLI, postReply, killActiveChild } from "./dispatcher.js";
 import { setDebugEnabled, dbg } from "./logger.js";
-import { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded } from "../core/device.js";
+import { registry } from "../core/registry.js";
 const DEFAULT_PORT = 18686;
 const PID_FILE = "daemon.pid";
-// ── State ──────────────────────────────────────────────────
+// ── State ────────���─────────────────────────────────────────
 let activeBackend = null;
 let activeModel = null; // user-selected model alias, null = use default
 let isProcessing = false;
@@ -153,7 +153,7 @@ function readPid() {
 export function isAlreadyRunning() {
     return readPid();
 }
-// ── Main Daemon Entry ──────────────────────────────────────
+// ── Main Daemon Entry ──────���───────────────────────────────
 export async function startDaemon(options) {
     if (options?.debug)
         setDebugEnabled(true);
@@ -190,10 +190,11 @@ export async function startDaemon(options) {
     else {
         log(`[config] No backend configured. Use: zhihand gemini / zhihand claude / zhihand codex`);
     }
-    // Fetch device profile (platform, model, screen size) — non-blocking, best-effort
-    await fetchDeviceProfile(config);
-    if (isDeviceProfileLoaded()) {
-        const s = getStaticContext();
+    // Init the multi-device registry and log profile.
+    await registry.init();
+    const defaultState = registry.resolveDefault();
+    if (defaultState?.profile) {
+        const s = defaultState.profile;
         log(`[device] ${s.platform} ${s.model} (${s.osVersion}), ${s.screenWidthPx}x${s.screenHeightPx}, ${s.locale}`);
     }
     else {
@@ -244,7 +245,7 @@ export async function startDaemon(options) {
                 }
                 else if (!sessionId) {
                     // New session: create dedicated McpServer + Transport
-                    const server = createMcpServer(options?.deviceName);
+                    const server = createMcpServer();
                     const transport = new StreamableHTTPServerTransport({
                         sessionIdGenerator: () => randomUUID(),
                         onsessioninitialized: (sid) => {
@@ -341,6 +342,7 @@ export async function startDaemon(options) {
             catch { /* ignore */ }
         }
         mcpSessions.clear();
+        registry.shutdown();
         httpServer.close();
         removePid();
         log("Daemon stopped.");

package/dist/daemon/prompt-listener.d.ts

@@ -1,4 +1,5 @@
-import type { ZhiHandConfig } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
+type ZhiHandConfig = ZhiHandRuntimeConfig;
 export interface MobilePrompt {
     id: string;
     credential_id: string;
@@ -15,20 +16,20 @@ export declare class PromptListener {
     private handler;
     private log;
     private processedIds;
-    private sseAbort;
+    private rws;
     private pollTimer;
-    private sseConnected;
+    private wsConnected;
     private stopped;
     constructor(config: ZhiHandConfig, handler: PromptHandler, log: (msg: string) => void);
     start(): void;
     stop(): void;
     private dispatchPrompt;
-    private connectSSE;
-    private resetWatchdog;
-    private handleSSEEvent;
+    private connectWS;
+    private handleWSMessage;
+    private handleEvent;
     private startPolling;
-    /** Recursive setTimeout: waits for fetch to complete before scheduling next poll. */
     private schedulePoll;
     private stopPolling;
     private poll;
 }
+export {};

package/dist/daemon/prompt-listener.js

@@ -1,16 +1,14 @@
-import { updateDeviceProfile } from "../core/device.js";
+import { ReconnectingWebSocket } from "../core/ws.js";
 import { dbg } from "./logger.js";
-const SSE_WATCHDOG_TIMEOUT = 120_000; // 120s no data → reconnect (servers may not send keepalive frequently)
-const SSE_RECONNECT_DELAY = 3_000;
 const POLL_INTERVAL = 2_000;
 export class PromptListener {
     config;
     handler;
     log;
     processedIds = new Set();
-    sseAbort = null;
+    rws = null;
     pollTimer = null;
-    sseConnected = false;
+    wsConnected = false;
     stopped = false;
     constructor(config, handler, log) {
         this.config = config;
@@ -19,16 +17,14 @@ export class PromptListener {
     }
     start() {
         this.stopped = false;
-        this.connectSSE();
+        this.connectWS();
     }
     stop() {
         this.stopped = true;
-        this.sseAbort?.abort();
-        this.sseAbort = null;
-        if (this.pollTimer) {
-            clearTimeout(this.pollTimer);
-            this.pollTimer = null;
-        }
+        this.rws?.stop();
+        this.rws = null;
+        this.wsConnected = false;
+        this.stopPolling();
     }
     dispatchPrompt(prompt) {
         if (this.processedIds.has(prompt.id)) {
@@ -44,116 +40,78 @@ export class PromptListener {
         }
         this.handler(prompt);
     }
-    async connectSSE() {
-        while (!this.stopped) {
-            try {
-                this.sseAbort = new AbortController();
-                const url = `${this.config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/events/stream?topic=prompts`;
-                dbg(`[sse] Connecting to ${url}`);
-                const response = await fetch(url, {
-                    headers: {
-                        "Accept": "text/event-stream",
-                        "x-zhihand-controller-token": this.config.controllerToken,
-                    },
-                    signal: this.sseAbort.signal,
-                });
-                if (!response.ok) {
-                    dbg(`[sse] Connect failed: ${response.status} ${response.statusText}`);
-                    throw new Error(`SSE connect failed: ${response.status}`);
-                }
-                this.sseConnected = true;
+    connectWS() {
+        if (this.stopped)
+            return;
+        const wsUrl = `${this.config.controlPlaneEndpoint.replace(/^http/, "ws")}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/ws?topic=prompts`;
+        dbg(`[ws] Connecting to ${wsUrl}`);
+        this.rws = new ReconnectingWebSocket({
+            url: wsUrl,
+            headers: {
+                "Authorization": `Bearer ${this.config.controllerToken}`,
+            },
+            onOpen: () => {
+                this.wsConnected = true;
                 this.stopPolling();
-                this.log("[sse] Connected to prompt stream.");
-                const reader = response.body?.getReader();
-                if (!reader)
-                    throw new Error("No response body for SSE");
-                const decoder = new TextDecoder();
-                let buffer = "";
-                let watchdog = this.resetWatchdog();
-                try {
-                    while (!this.stopped) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        // Reset watchdog on any data (including keepalive comments)
-                        clearTimeout(watchdog);
-                        watchdog = this.resetWatchdog();
-                        buffer += decoder.decode(value, { stream: true });
-                        const lines = buffer.split("\n");
-                        buffer = lines.pop() ?? "";
-                        let eventData = "";
-                        for (const line of lines) {
-                            if (line.startsWith("data: ")) {
-                                eventData += (eventData ? "\n" : "") + line.slice(6);
-                            }
-                            else if (line === "" && eventData) {
-                                try {
-                                    const event = JSON.parse(eventData);
-                                    this.handleSSEEvent(event);
-                                }
-                                catch {
-                                    // Malformed event
-                                }
-                                eventData = "";
-                            }
-                        }
-                    }
-                }
-                finally {
-                    // Always clear watchdog — prevents leaked timer from aborting next connection
-                    clearTimeout(watchdog);
+                this.log("[ws] Connected to prompt stream.");
+            },
+            onClose: (_code, _reason) => {
+                if (this.wsConnected) {
+                    this.wsConnected = false;
+                    this.log("[ws] Disconnected. Falling back to polling.");
+                    this.startPolling();
                 }
-            }
-            catch (err) {
-                if (this.stopped)
-                    break;
-                this.sseConnected = false;
-                this.log(`[sse] Disconnected. Falling back to polling. (${err.message})`);
-                this.startPolling();
-                await new Promise((r) => setTimeout(r, SSE_RECONNECT_DELAY));
-            }
-        }
+            },
+            onMessage: (data) => {
+                this.handleWSMessage(data);
+            },
+            onError: (err) => {
+                dbg(`[ws] Error: ${err.message}`);
+            },
+        });
+        this.rws.start();
     }
-    resetWatchdog() {
-        return setTimeout(() => {
-            this.log("[sse] Watchdog timeout (120s no data). Reconnecting...");
-            this.sseAbort?.abort();
-        }, SSE_WATCHDOG_TIMEOUT);
+    handleWSMessage(data) {
+        const msg = data;
+        // Application-level ping (if server sends these alongside protocol pings)
+        if (msg.type === "ping") {
+            this.rws?.send(JSON.stringify({ type: "pong" }));
+            return;
+        }
+        // Event dispatch
+        if (msg.type === "event" || msg.kind) {
+            this.handleEvent(msg);
+        }
     }
-    handleSSEEvent(event) {
-        dbg(`[sse] Event: kind=${event.kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
-        if (event.kind === "prompt.queued" && event.prompt) {
+    handleEvent(event) {
+        const kind = event.kind;
+        dbg(`[ws] Event: kind=${kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
+        if (kind === "prompt.queued" && event.prompt) {
             this.dispatchPrompt(event.prompt);
         }
-        else if (event.kind === "prompt.snapshot" && event.prompts) {
+        else if (kind === "prompt.snapshot" && event.prompts) {
             for (const p of event.prompts) {
                 if (p.status === "pending" || p.status === "processing") {
                     this.dispatchPrompt(p);
                 }
             }
         }
-        else if (event.kind === "device_profile.updated" && event.device_profile) {
-            // NOTE: This event may only arrive if the server sends cross-topic events on
-            // the prompts stream, or if the API is updated to support multi-topic SSE.
-            // If not received, device profile is still fetched at daemon startup.
-            this.log("[device] Device profile updated via SSE");
-            updateDeviceProfile(event.device_profile);
+        else if (kind === "device_profile.updated") {
+            this.log("[device] device_profile.updated event received on prompts stream (ignored; registry handles it)");
         }
     }
     startPolling() {
-        if (this.pollTimer)
+        if (this.pollTimer || this.stopped)
             return;
         this.schedulePoll();
     }
-    /** Recursive setTimeout: waits for fetch to complete before scheduling next poll. */
     schedulePoll() {
         if (this.pollTimer)
             return;
         this.pollTimer = setTimeout(async () => {
             this.pollTimer = null;
             await this.poll();
-            // Schedule next poll only if SSE is still disconnected
-            if (!this.sseConnected && !this.stopped) {
+            if (!this.wsConnected && !this.stopped) {
                 this.schedulePoll();
             }
         }, POLL_INTERVAL);
@@ -169,7 +127,7 @@ export class PromptListener {
             const url = `${this.config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/prompts?limit=5`;
             dbg(`[poll] GET ${url}`);
             const response = await fetch(url, {
-                headers: { "x-zhihand-controller-token": this.config.controllerToken },
+                headers: { "Authorization": `Bearer ${this.config.controllerToken}` },
                 signal: AbortSignal.timeout(10_000),
             });
             if (!response.ok) {
@@ -178,6 +136,8 @@ export class PromptListener {
             }
             const data = (await response.json());
             dbg(`[poll] Got ${data.items?.length ?? 0} prompt(s)`);
+            if (this.stopped)
+                return; // Guard against late responses after stop()
             for (const prompt of data.items ?? []) {
                 this.dispatchPrompt(prompt);
             }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const PACKAGE_VERSION = "0.29.0";
-export declare function createServer(deviceName?: string): McpServer;
-export declare function startStdioServer(deviceName?: string): Promise<void>;
+export declare const PACKAGE_VERSION = "0.31.0";
+export declare function createServer(): McpServer;
+export declare function startStdioServer(): Promise<void>;

package/dist/index.js

@@ -1,79 +1,143 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { resolveConfig } from "./core/config.js";
-import { controlSchema, systemSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+import { controlSchema, systemSchema, screenshotSchema, pairSchema, listDevicesSchema, statusSchema, } from "./tools/schemas.js";
 import { executeControl } from "./tools/control.js";
 import { executeSystem } from "./tools/system.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
-export const PACKAGE_VERSION = "0.29.0";
-export function createServer(deviceName) {
+import { resolveTargetDevice } from "./tools/resolve.js";
+import { buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, extractDynamic, } from "./core/device.js";
+import { registry } from "./core/registry.js";
+export const PACKAGE_VERSION = "0.31.0";
+function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function createServer() {
     const server = new McpServer({
         name: "zhihand",
         version: PACKAGE_VERSION,
     });
-    // zhihand_control — main phone control tool
-    // Description includes device info (platform, model, screen size) when available
-    server.tool("zhihand_control", buildControlToolDescription(), controlSchema, async (params) => {
-        const config = resolveConfig(deviceName);
-        return await executeControl(config, params);
+    const multiUser = registry.isMultiUser();
+    const controlTool = server.tool("zhihand_control", buildControlToolDescription(null, registry.listOnline(), multiUser), controlSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
+        const { state } = resolved;
+        const cfg = registry.toRuntimeConfig(state);
+        const platform = state.profile?.platform ?? "unknown";
+        return await executeControl(cfg, params, platform, state.capabilities);
     });
-    // zhihand_system — system navigation + media controls (separate tool per Gemini design review)
-    server.tool("zhihand_system", buildSystemToolDescription(), systemSchema, async (params) => {
-        const config = resolveConfig(deviceName);
-        return await executeSystem(config, params);
+    const systemTool = server.tool("zhihand_system", buildSystemToolDescription(null, registry.listOnline(), multiUser), systemSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
+        const { state } = resolved;
+        const cfg = registry.toRuntimeConfig(state);
+        const platform = state.profile?.platform ?? "unknown";
+        return await executeSystem(cfg, params, platform);
     });
-    // zhihand_screenshot — capture current screen without any action
-    server.tool("zhihand_screenshot", buildScreenshotToolDescription(), screenshotSchema, async () => {
-        const config = resolveConfig(deviceName);
-        return await handleScreenshot(config);
+    const screenshotTool = server.tool("zhihand_screenshot", buildScreenshotToolDescription(null, registry.listOnline(), multiUser), screenshotSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
+        const { state } = resolved;
+        const cfg = registry.toRuntimeConfig(state);
+        return await handleScreenshot(cfg, state.capabilities);
     });
-    // zhihand_status — return device context for LLM to query on demand
-    server.tool("zhihand_status", "Get device status and capability readiness. Returns curated fields (platform, model, OS, screen, battery, network, BLE, ...), a `capabilities` object with `ready`/`reason` for screen_sharing, hid, live_session, profile.age, AND a `raw` map of allowlisted device attributes (wire-format names). Call this BEFORE issuing commands if you are unsure whether the phone is screen-sharing or the ZhiHand (BLE HID) is connected.", {}, async () => {
+    server.tool("zhihand_status", "Get device status and capability readiness for a device. Returns curated fields (platform, model, OS, screen, battery, network, BLE, ...), a `capabilities` object with `ready`/`reason` for screen_sharing, hid, live_session, profile.age, AND a `raw` map of allowlisted device attributes. Pass device_id when multiple devices are online.", statusSchema, async (params) => {
+        const resolved = resolveTargetDevice(params.device_id);
+        if ("error" in resolved)
+            return errorResult(resolved.error);
         return {
             content: [{
                     type: "text",
-                    text: JSON.stringify(formatDeviceStatus(), null, 2),
+                    text: JSON.stringify(formatDeviceStatus(resolved.state), null, 2),
+                }],
+        };
+    });
+    server.tool("zhihand_list_devices", "List ALL configured ZhiHand devices with their online status. Returns device_id, label, platform, online, battery, is_default, last_active for each. Call this before zhihand_control/system/screenshot/status when multiple devices may be online.", listDevicesSchema, async () => {
+        const mu = registry.isMultiUser();
+        const defaultDev = registry.resolveDefault();
+        const devices = registry.list().map((d) => ({
+            device_id: d.credentialId,
+            label: mu ? `[${d.userLabel}] ${d.label}` : d.label,
+            platform: d.platform,
+            online: d.online,
+            battery: d.rawAttributes ? extractDynamic(d.rawAttributes).batteryLevel : null,
+            is_default: d === defaultDev,
+            last_active: d.lastSeenAtMs > 0 ? new Date(d.lastSeenAtMs).toISOString() : null,
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ devices }, null, 2),
                 }],
         };
     });
-    // zhihand_pair — device pairing
     server.tool("zhihand_pair", "Pair a new mobile device via QR code.", pairSchema, async (params) => {
         return await handlePair(params);
     });
-    // device://profile — MCP resource for device profile
-    server.resource("device-profile", "device://profile", { description: "Device static and dynamic context (platform, model, screen, battery, network, etc.)" }, async () => {
-        const staticCtx = getStaticContext();
-        const dynamicCtx = getDynamicContext();
+    // Dynamic tool-description updates on online-set change.
+    registry.subscribe(() => {
+        const online = registry.listOnline();
+        const mu = registry.isMultiUser();
+        try {
+            controlTool.update({ description: buildControlToolDescription(null, online, mu) });
+        }
+        catch { /* best-effort */ }
+        try {
+            systemTool.update({ description: buildSystemToolDescription(null, online, mu) });
+        }
+        catch { /* best-effort */ }
+        try {
+            screenshotTool.update({ description: buildScreenshotToolDescription(null, online, mu) });
+        }
+        catch { /* best-effort */ }
+        try {
+            server.server.sendToolListChanged();
+        }
+        catch { /* best-effort */ }
+    });
+    // device://profile — returns default online device
+    server.resource("device-profile", "device://profile", { description: "Device static and dynamic context for the default online device." }, async () => {
+        const state = registry.resolveDefault();
+        if (!state) {
+            return {
+                contents: [{
+                        uri: "device://profile",
+                        mimeType: "application/json",
+                        text: JSON.stringify({ error: "No device online" }, null, 2),
+                    }],
+            };
+        }
         return {
             contents: [{
                     uri: "device://profile",
                     mimeType: "application/json",
-                    text: JSON.stringify({ ...staticCtx, ...dynamicCtx }, null, 2),
+                    text: JSON.stringify(formatDeviceStatus(state), null, 2),
                 }],
         };
     });
     return server;
 }
-export async function startStdioServer(deviceName) {
-    // Fetch device profile before creating server so tool descriptions have platform info
-    try {
-        const config = resolveConfig(deviceName);
-        await fetchDeviceProfile(config);
-    }
-    catch {
-        // Non-fatal — server will use generic descriptions
-    }
-    const server = createServer(deviceName);
+export async function startStdioServer() {
+    await registry.init();
+    const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-// Direct execution: start stdio server
+function setupShutdown() {
+    const shutdown = () => {
+        registry.shutdown();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+setupShutdown();
 const isDirectRun = process.argv[1]?.endsWith("index.ts") || process.argv[1]?.endsWith("index.js");
 if (isDirectRun) {
-    const deviceArg = process.argv.find((a) => a.startsWith("--device="))?.split("=")[1];
-    startStdioServer(deviceArg ?? process.env.ZHIHAND_DEVICE).catch((err) => {
+    startStdioServer().catch((err) => {
         process.stderr.write(`ZhiHand MCP Server failed: ${err.message}\n`);
         process.exit(1);
     });

package/dist/openclaw.adapter.js

@@ -8,6 +8,7 @@ import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
 import { detectCLITools, formatDetectedTools } from "./cli/detect.js";
 import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+import { registry } from "./core/registry.js";
 function zodSchemaToJsonSchema(zodShape) {
     // Simplified conversion — OpenClaw uses JSON Schema-like parameter objects.
     // The actual Zod schemas are used for validation inside tool handlers.
@@ -23,6 +24,8 @@ function zodSchemaToJsonSchema(zodShape) {
 }
 export function registerOpenClawTools(api, deviceName) {
     const log = (msg) => api.logger.info?.(msg);
+    // Kick off registry in the background so runtime config resolution benefits.
+    void registry.init().catch(() => { });
     // zhihand_control
     api.registerTool({
         name: "zhihand_control",
@@ -31,7 +34,10 @@ export function registerOpenClawTools(api, deviceName) {
         parameters: zodSchemaToJsonSchema(controlSchema),
         execute: async (_id, params) => {
             const config = resolveConfig(deviceName);
-            const result = await executeControl(config, params);
+            const state = registry.get(config.credentialId);
+            const platform = state?.profile?.platform ?? "unknown";
+            const caps = state?.capabilities ?? null;
+            const result = await executeControl(config, params, platform, caps);
             return result;
         },
     });
@@ -43,7 +49,9 @@ export function registerOpenClawTools(api, deviceName) {
         parameters: zodSchemaToJsonSchema(screenshotSchema),
         execute: async (_id, _params) => {
             const config = resolveConfig(deviceName);
-            const result = await handleScreenshot(config);
+            const state = registry.get(config.credentialId);
+            const caps = state?.capabilities ?? null;
+            const result = await handleScreenshot(config, caps);
             return result;
         },
     });

package/dist/tools/control.d.ts

@@ -1,5 +1,7 @@
-import type { ZhiHandConfig } from "../core/config.ts";
+import type { ZhiHandRuntimeConfig } from "../core/config.ts";
 import type { ControlParams } from "../core/command.ts";
+import type { ScreenshotResult } from "../core/screenshot.ts";
+import type { Capabilities } from "../core/device.ts";
 type TextContent = {
     type: "text";
     text: string;
@@ -13,6 +15,11 @@ type ToolContent = TextContent | ImageContent;
 type ToolResult = {
     content: ToolContent[];
 };
-export declare function executeControl(config: ZhiHandConfig, params: ControlParams): Promise<ToolResult>;
-export declare function executeScreenshot(config: ZhiHandConfig): Promise<ToolResult>;
+/**
+ * Build a short human-readable warning for the LLM if the underlying
+ * capability isn't ready, or if the last screenshot is stale.
+ */
+export declare function buildReadinessWarning(requiredCapability: "hid" | "screen" | "none", capabilities: Capabilities | null, screenshot: ScreenshotResult | null): string;
+export declare function executeControl(config: ZhiHandRuntimeConfig, params: ControlParams, platform: string, capabilities: Capabilities | null): Promise<ToolResult>;
+export declare function executeScreenshot(config: ZhiHandRuntimeConfig, capabilities: Capabilities | null): Promise<ToolResult>;
 export {};