@zhihand/mcp 0.24.1 → 0.26.0

package/README.md

@@ -2,7 +2,7 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.24.1`
+Version: `0.26.0`
 
 ## What is this?
 
@@ -93,6 +93,7 @@ Once configured, your AI agent can use ZhiHand tools directly. For example, in C
 zhihand setup              Interactive setup: pair + detect tools + auto-select + configure MCP + start daemon
 zhihand start              Start daemon (MCP Server + Relay + Config API)
 zhihand start -d           Start daemon in background (logs to ~/.zhihand/daemon.log)
+zhihand start --debug      Start daemon with verbose debug logging
 zhihand stop               Stop the running daemon
 zhihand status             Show daemon status, pairing info, device, backend, and model
 
@@ -113,6 +114,7 @@ zhihand gemini --model pro Switch backend with custom model
 ```bash
 zhihand start              # Start daemon in foreground
 zhihand start -d           # Start daemon in background
+zhihand start --debug      # Start with verbose debug logging
 zhihand stop               # Stop the daemon
 zhihand status             # Check if daemon is running, show device & backend info
 ```
@@ -159,6 +161,7 @@ When you switch:
 | `--model, -m <name>` | Set model alias (e.g. `flash`, `pro`, `sonnet`, `opus`, `gpt-5.4-mini`) |
 | `--port <port>` | Override daemon port (default: 18686) |
 | `-d, --detach` | Run daemon in background |
+| `--debug` | Enable verbose debug logging (all API requests, CLI args, SSE events) |
 | `-h, --help` | Show help |
 
 ### Environment Variables
@@ -174,7 +177,7 @@ When you switch:
 
 ## MCP Tools
 
-The server exposes three tools to AI agents:
+The server exposes these tools to AI agents:
 
 ### `zhihand_control`
 
@@ -209,6 +212,12 @@ Capture the current phone screen without performing any action. Returns an image
 
 No parameters required.
 
+### `zhihand_status`
+
+Get device status: platform, model, OS version, screen size, battery, network, BLE connection, dark mode, storage, and more. No parameters.
+
+Tool description and `open_app` guidance are **automatically adapted** based on the connected device platform (Android/iOS), so AI agents always send correct platform-specific parameters.
+
 ### `zhihand_pair`
 
 Pair with a phone device. Returns a QR code and pairing URL.
@@ -217,6 +226,10 @@ Pair with a phone device. Returns a QR code and pairing URL.
 |---|---|---|
 | `forceNew` | `boolean` | Force new pairing even if already paired (default: `false`) |
 
+### MCP Resource: `device://profile`
+
+Provides full device context (static + dynamic) as JSON. Includes platform, model, OS version, screen size, battery, network, BLE, dark mode, storage, thermal state, locale, and more.
+
 ## How It Works
 
 ```
@@ -299,12 +312,14 @@ packages/mcp/
 │   ├── core/
 │   │   ├── config.ts        # Credential & config management (~/.zhihand/), default models
 │   │   ├── resolve-path.ts  # Platform-aware executable path resolution (gemini/claude/codex)
+│   │   ├── device.ts        # Device context: static/dynamic profile, fetch, SSE updates
 │   │   ├── command.ts       # Command creation, enqueue, ACK formatting
 │   │   ├── screenshot.ts    # Binary screenshot fetch (JPEG)
 │   │   ├── sse.ts           # SSE client + hybrid ACK (SSE push + polling fallback)
 │   │   └── pair.ts          # Plugin registration + device pairing flow
 │   ├── daemon/
 │   │   ├── index.ts         # Daemon entry: HTTP server + MCP + Relay + Config API
+│   │   ├── logger.ts        # Debug logger (--debug flag)
 │   │   ├── heartbeat.ts     # Brain heartbeat loop (30s interval, 5s retry)
 │   │   ├── prompt-listener.ts # SSE + polling prompt listener with dedup
 │   │   └── dispatcher.ts    # Async CLI dispatch (spawn + timeout + two-stage kill)

package/bin/zhihand

@@ -26,6 +26,7 @@ const { positionals, values } = parseArgs({
     model: { type: "string", short: "m" },
     help: { type: "boolean", short: "h", default: false },
     detach: { type: "boolean", short: "d", default: false },
+    debug: { type: "boolean", default: false },
     port: { type: "string" },
   },
 });
@@ -39,6 +40,7 @@ zhihand — MCP Server and Relay for phone control
 Usage:
   zhihand start              Start daemon (MCP Server + Relay, foreground)
   zhihand start -d           Start daemon in background (detach)
+  zhihand start --debug      Start daemon with verbose debug logging
   zhihand stop               Stop daemon
   zhihand status             Show status (pairing, backend, brain)
 
@@ -59,6 +61,7 @@ Options:
   --model, -m <name> Set model alias (e.g. flash, pro, sonnet, opus, gpt-5.4-mini)
   --port <port>      Override daemon port (default: 18686)
   -d, --detach       Run daemon in background
+  --debug            Enable verbose debug logging
   -h, --help         Show this help
 `);
   process.exit(0);
@@ -145,6 +148,7 @@ switch (command) {
       const args = [process.argv[1], "start"];
       if (values.port) args.push("--port", values.port);
       if (values.device) args.push("--device", values.device);
+      if (values.debug) args.push("--debug");
 
       // Write daemon logs to ~/.zhihand/daemon.log
       const zhihandDir = pathMod.default.join(osMod.default.homedir(), ".zhihand");
@@ -167,6 +171,7 @@ switch (command) {
     await startDaemon({
       port,
       deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+      debug: values.debug,
     });
     break;
   }
@@ -306,8 +311,9 @@ switch (command) {
       { label: "3. Swipe up", type: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 } },
       { label: "4. Swipe down", type: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 } },
       { label: "5. Press Home", type: "hid", params: { action: "home" } },
-      { label: "6. Press Back", type: "hid", params: { action: "back" } },
-      { label: "7. Screenshot", type: "screenshot" },
+      { label: "6. Open WeChat", type: "hid", params: { action: "open_app", appPackage: "com.tencent.mm" } },
+      { label: "7. Press Back", type: "hid", params: { action: "back" } },
+      { label: "8. Screenshot", type: "screenshot" },
     ];
 
     let passed = 0;
@@ -337,7 +343,10 @@ switch (command) {
           const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
           const ms = Date.now() - t0;
           if (ack.acked) {
-            console.log(`✅ (${ms}ms)`);
+            const ackStatus = ack.command?.ack_status ?? "ok";
+            const detail = ackStatus !== "ok" ? ` [${ackStatus}]` : "";
+            const resultInfo = ack.command?.ack_result ? ` ${JSON.stringify(ack.command.ack_result)}` : "";
+            console.log(`✅ (${ms}ms)${detail}${resultInfo}`);
             passed++;
           } else {
             console.log(`⏱️  Timeout (${ms}ms)`);

package/dist/core/command.js

@@ -1,3 +1,4 @@
+import { dbg } from "../daemon/logger.js";
 let messageCounter = 0;
 function nextMessageId() {
     messageCounter = (messageCounter + 1) % 1000;
@@ -73,30 +74,38 @@ export function createControlCommand(params) {
     }
 }
 export async function enqueueCommand(config, command) {
-    const response = await fetch(`${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands`, {
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands`;
+    const body = { command: { ...command, message_id: command.messageId ?? nextMessageId() } };
+    dbg(`[cmd] POST ${url} type=${command.type} payload=${JSON.stringify(command.payload ?? {})}`);
+    const response = await fetch(url, {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
             "x-zhihand-controller-token": config.controllerToken,
         },
-        body: JSON.stringify({
-            command: { ...command, message_id: command.messageId ?? nextMessageId() },
-        }),
+        body: JSON.stringify(body),
     });
     if (!response.ok) {
+        dbg(`[cmd] Enqueue failed: ${response.status} ${response.statusText}`);
         throw new Error(`Enqueue command failed: ${response.status}`);
     }
     const payload = (await response.json());
+    dbg(`[cmd] Enqueued: id=${payload.command.id}, status=${payload.command.status}`);
     return payload.command;
 }
 export async function getCommand(config, commandId) {
-    const response = await fetch(`${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands/${encodeURIComponent(commandId)}`, {
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands/${encodeURIComponent(commandId)}`;
+    dbg(`[cmd] GET ${url}`);
+    const response = await fetch(url, {
         headers: { "x-zhihand-controller-token": config.controllerToken },
     });
     if (!response.ok) {
+        dbg(`[cmd] Get failed: ${response.status}`);
         throw new Error(`Get command failed: ${response.status}`);
     }
     const payload = (await response.json());
+    const cmd = payload.command;
+    dbg(`[cmd] Got: id=${cmd.id}, status=${cmd.status}, acked=${!!cmd.acked_at}, ack_status=${cmd.ack_status ?? "-"}, ack_result=${JSON.stringify(cmd.ack_result ?? null)}`);
     return payload.command;
 }
 export function formatAckSummary(action, result) {

package/dist/core/device.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Device Context — static + dynamic device info fetched from control plane.
+ *
+ * Static info (platform, model, screen size) is set once after pairing and
+ * injected into MCP tool descriptions so the LLM always knows the device.
+ *
+ * Dynamic info (battery, network, BLE) is updated via SSE push and exposed
+ * through the zhihand_status tool and device://profile resource.
+ */
+import type { ZhiHandConfig } from "./config.ts";
+export interface StaticContext {
+    platform: string;
+    model: string;
+    osVersion: string;
+    screenWidthPx: number;
+    screenHeightPx: number;
+    density: number;
+    formFactor: string;
+    locale: string;
+    textDirection: string;
+    timezone: string;
+    navigationMode?: string;
+    romFamily?: string;
+}
+export interface DynamicContext {
+    batteryLevel: number;
+    batteryState: string;
+    networkType: string;
+    bleRssi: number | null;
+    darkMode: boolean;
+    hidConnected: boolean;
+    recordingActive: boolean;
+    appInForeground: boolean;
+    availableStorageMb: number;
+    thermalState?: string;
+    fontScale: number;
+}
+export declare function getStaticContext(): StaticContext;
+export declare function getDynamicContext(): DynamicContext;
+export declare function isDeviceProfileLoaded(): boolean;
+export declare function extractStatic(profile: Record<string, unknown>): StaticContext;
+export declare function extractDynamic(profile: Record<string, unknown>): DynamicContext;
+export declare function updateDeviceProfile(profile: Record<string, unknown>): void;
+export declare function fetchDeviceProfile(config: ZhiHandConfig): Promise<void>;
+export declare function buildControlToolDescription(): string;
+export declare function buildScreenshotToolDescription(): string;
+export declare function formatDeviceStatus(): Record<string, unknown>;

package/dist/core/device.js

@@ -0,0 +1,171 @@
+/**
+ * Device Context — static + dynamic device info fetched from control plane.
+ *
+ * Static info (platform, model, screen size) is set once after pairing and
+ * injected into MCP tool descriptions so the LLM always knows the device.
+ *
+ * Dynamic info (battery, network, BLE) is updated via SSE push and exposed
+ * through the zhihand_status tool and device://profile resource.
+ */
+import { dbg } from "../daemon/logger.js";
+// ── Default values ────────────────────────────────────────
+const DEFAULT_STATIC = {
+    platform: "unknown",
+    model: "unknown",
+    osVersion: "unknown",
+    screenWidthPx: 0,
+    screenHeightPx: 0,
+    density: 1,
+    formFactor: "phone",
+    locale: "en-US",
+    textDirection: "ltr",
+    timezone: "UTC",
+};
+const DEFAULT_DYNAMIC = {
+    batteryLevel: -1,
+    batteryState: "unknown",
+    networkType: "unknown",
+    bleRssi: null,
+    darkMode: false,
+    hidConnected: false,
+    recordingActive: false,
+    appInForeground: false,
+    availableStorageMb: -1,
+    fontScale: 1,
+};
+// ── Module state ──────────────────────────────────────────
+let staticCtx = { ...DEFAULT_STATIC };
+let dynamicCtx = { ...DEFAULT_DYNAMIC };
+let loaded = false;
+export function getStaticContext() {
+    return staticCtx;
+}
+export function getDynamicContext() {
+    return dynamicCtx;
+}
+export function isDeviceProfileLoaded() {
+    return loaded;
+}
+// ── Extract helpers ───────────────────────────────────────
+function str(v, fallback) {
+    return typeof v === "string" && v ? v : fallback;
+}
+function num(v, fallback) {
+    return typeof v === "number" && !isNaN(v) ? v : fallback;
+}
+function bool(v, fallback) {
+    return typeof v === "boolean" ? v : fallback;
+}
+export function extractStatic(profile) {
+    return {
+        platform: str(profile.platform, DEFAULT_STATIC.platform),
+        model: str(profile.model, DEFAULT_STATIC.model),
+        osVersion: str(profile.os_version, DEFAULT_STATIC.osVersion),
+        screenWidthPx: num(profile.screen_width_px, DEFAULT_STATIC.screenWidthPx),
+        screenHeightPx: num(profile.screen_height_px, DEFAULT_STATIC.screenHeightPx),
+        density: num(profile.density, DEFAULT_STATIC.density),
+        formFactor: str(profile.form_factor, DEFAULT_STATIC.formFactor),
+        locale: str(profile.locale, DEFAULT_STATIC.locale),
+        textDirection: str(profile.text_direction, DEFAULT_STATIC.textDirection),
+        timezone: str(profile.timezone, DEFAULT_STATIC.timezone),
+        navigationMode: typeof profile.navigation_mode === "string" ? profile.navigation_mode : undefined,
+        romFamily: typeof profile.rom_family === "string" ? profile.rom_family : undefined,
+    };
+}
+export function extractDynamic(profile) {
+    return {
+        batteryLevel: num(profile.battery_level, DEFAULT_DYNAMIC.batteryLevel),
+        batteryState: str(profile.battery_state, DEFAULT_DYNAMIC.batteryState),
+        networkType: str(profile.network_type, DEFAULT_DYNAMIC.networkType),
+        bleRssi: typeof profile.ble_rssi === "number" ? profile.ble_rssi : null,
+        darkMode: bool(profile.dark_mode, DEFAULT_DYNAMIC.darkMode),
+        hidConnected: bool(profile.hid_connected, DEFAULT_DYNAMIC.hidConnected),
+        recordingActive: bool(profile.recording_active, DEFAULT_DYNAMIC.recordingActive),
+        appInForeground: bool(profile.app_in_foreground, DEFAULT_DYNAMIC.appInForeground),
+        availableStorageMb: num(profile.available_storage_mb, DEFAULT_DYNAMIC.availableStorageMb),
+        thermalState: typeof profile.thermal_state === "string" ? profile.thermal_state : undefined,
+        fontScale: num(profile.font_scale, DEFAULT_DYNAMIC.fontScale),
+    };
+}
+// ── Update from SSE event ─────────────────────────────────
+export function updateDeviceProfile(profile) {
+    staticCtx = extractStatic(profile);
+    dynamicCtx = extractDynamic(profile);
+    loaded = true;
+    dbg(`[device] Profile updated: platform=${staticCtx.platform}, model=${staticCtx.model}, screen=${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`);
+}
+// ── Fetch initial profile from API ────────────────────────
+export async function fetchDeviceProfile(config) {
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/device-profile`;
+    dbg(`[device] Fetching profile: GET ${url}`);
+    try {
+        const response = await fetch(url, {
+            headers: { "x-zhihand-controller-token": config.controllerToken },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            dbg(`[device] Profile fetch failed: ${response.status} ${response.statusText}`);
+            return;
+        }
+        const data = await response.json();
+        // API may wrap in { device_profile: {...} } or return flat
+        const profile = (typeof data.device_profile === "object" && data.device_profile !== null)
+            ? data.device_profile
+            : data;
+        updateDeviceProfile(profile);
+    }
+    catch (err) {
+        dbg(`[device] Profile fetch error: ${err.message}`);
+    }
+}
+// ── Build tool description with device info ───────────────
+export function buildControlToolDescription() {
+    if (!loaded || staticCtx.platform === "unknown") {
+        return "Control the connected mobile device. Supports click, swipe, type, scroll, open_app, back, home, and more. All coordinates use normalized ratios [0,1].";
+    }
+    const parts = [
+        `Control a ${staticCtx.platform} device`,
+        `(${staticCtx.model}, ${staticCtx.osVersion}`,
+        `${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`,
+        `${staticCtx.formFactor}, ${staticCtx.locale})`,
+    ];
+    let desc = parts.join(", ") + ".";
+    desc += " All coordinates use normalized ratios [0,1].";
+    // Platform-specific open_app guidance
+    if (staticCtx.platform === "android") {
+        desc += " For open_app, use appPackage (e.g. 'com.tencent.mm'). Do NOT send bundleId or urlScheme.";
+    }
+    else if (staticCtx.platform === "ios") {
+        desc += " For open_app, use bundleId (e.g. 'com.tencent.xin') or urlScheme (e.g. 'weixin://'). Do NOT send appPackage.";
+    }
+    return desc;
+}
+export function buildScreenshotToolDescription() {
+    if (!loaded || staticCtx.platform === "unknown") {
+        return "Take a screenshot of the phone screen.";
+    }
+    return `Take a screenshot of the ${staticCtx.platform} device (${staticCtx.model}, ${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}).`;
+}
+// ── Format status for zhihand_status tool ─────────────────
+export function formatDeviceStatus() {
+    return {
+        platform: staticCtx.platform,
+        model: staticCtx.model,
+        os_version: staticCtx.osVersion,
+        screen: `${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`,
+        density: staticCtx.density,
+        form_factor: staticCtx.formFactor,
+        locale: staticCtx.locale,
+        timezone: staticCtx.timezone,
+        navigation_mode: staticCtx.navigationMode ?? null,
+        battery: `${dynamicCtx.batteryLevel}% (${dynamicCtx.batteryState})`,
+        network: dynamicCtx.networkType,
+        ble: dynamicCtx.hidConnected
+            ? `connected${dynamicCtx.bleRssi !== null ? ` (RSSI: ${dynamicCtx.bleRssi})` : ""}`
+            : "disconnected",
+        dark_mode: dynamicCtx.darkMode,
+        storage_available_mb: dynamicCtx.availableStorageMb,
+        thermal: dynamicCtx.thermalState ?? "normal",
+        font_scale: dynamicCtx.fontScale,
+    };
+}

package/dist/core/screenshot.js

@@ -1,8 +1,13 @@
+import { dbg } from "../daemon/logger.js";
 export async function fetchScreenshotBinary(config) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 10_000);
+    const timeoutMs = config.timeoutMs ?? 10_000;
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/screen`;
+    dbg(`[screenshot] GET ${url} timeout=${timeoutMs}ms`);
+    const t0 = Date.now();
     try {
-        const response = await fetch(`${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/screen`, {
+        const response = await fetch(url, {
             method: "GET",
             headers: {
                 "x-zhihand-controller-token": config.controllerToken,
@@ -11,9 +16,12 @@ export async function fetchScreenshotBinary(config) {
             signal: controller.signal,
         });
         if (!response.ok) {
+            dbg(`[screenshot] Failed: ${response.status} ${response.statusText}`);
             throw new Error(`Screenshot fetch failed: ${response.status}`);
         }
-        return Buffer.from(await response.arrayBuffer());
+        const buf = Buffer.from(await response.arrayBuffer());
+        dbg(`[screenshot] OK: ${(buf.length / 1024).toFixed(0)}KB in ${Date.now() - t0}ms`);
+        return buf;
     }
     finally {
         clearTimeout(timeout);

package/dist/core/sse.js

@@ -1,13 +1,16 @@
 import { getCommand } from "./command.js";
+import { dbg } from "../daemon/logger.js";
 // Per-commandId callback registry for SSE-based ACK
 const ackCallbacks = new Map();
 // Active SSE connection state
 let sseAbortController = null;
 let sseConnected = false;
 export function handleSSEEvent(event) {
+    dbg(`[sse-cmd] Event: kind=${event.kind}, command=${event.command?.id ?? "-"}`);
     if (event.kind === "command.acked" && event.command) {
         const callback = ackCallbacks.get(event.command.id);
         if (callback) {
+            dbg(`[sse-cmd] ACK callback for ${event.command.id}, ack_status=${event.command.ack_status}, ack_result=${JSON.stringify(event.command.ack_result ?? null)}`);
             callback(event.command);
             ackCallbacks.delete(event.command.id);
         }
@@ -103,6 +106,7 @@ export function isSSEConnected() {
  */
 export async function waitForCommandAck(config, options) {
     const timeoutMs = options.timeoutMs ?? 15_000;
+    dbg(`[sse-cmd] Waiting for ACK: commandId=${options.commandId}, timeout=${timeoutMs}ms`);
     // Ensure SSE is connected for real-time ACKs
     connectSSE(config);
     return new Promise((resolve, reject) => {

package/dist/daemon/dispatcher.js

@@ -5,6 +5,8 @@ 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 { 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
 const MCP_PORT = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
@@ -263,6 +265,7 @@ function pollGeminiSession(child, startTime, promptText, log, knownSessionFile,
             }
             if (Date.now() - outcomeAt >= SESSION_STABILITY_DELAY) {
                 const [status, text] = finalResult ?? outcome;
+                dbg(`[gemini] Session outcome: status=${status}, text (${text.length} chars): ${text.slice(0, 200)}${text.length > 200 ? "..." : ""}`);
                 settle({
                     text,
                     success: status === "success",
@@ -349,7 +352,30 @@ export async function killActiveChild() {
     conversationHistory.length = 0;
 }
 // ── System Prompt ─────────────────────────────────────────
-const SYSTEM_CONTEXT = `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
+/**
+ * Build system context dynamically — injects device platform info when available
+ * so the AI sends correct platform-specific parameters (e.g. appPackage vs bundleId).
+ */
+function buildSystemContext() {
+    const static_ = isDeviceProfileLoaded() ? getStaticContext() : 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";
+    // Platform-specific open_app guidance
+    let openAppDoc;
+    if (static_?.platform === "android") {
+        openAppDoc = "- open_app: Open an app. Params: appPackage (e.g. 'com.tencent.mm'). Do NOT send bundleId or urlScheme on Android.";
+    }
+    else if (static_?.platform === "ios") {
+        openAppDoc = "- open_app: Open an app. Params: bundleId (e.g. 'com.tencent.xin') or urlScheme (e.g. 'weixin://'). Do NOT send appPackage on iOS.";
+    }
+    else {
+        openAppDoc = "- open_app: Open an app. Params: appPackage (Android, e.g. 'com.tencent.mm'), bundleId (iOS), urlScheme (e.g. 'weixin://')";
+    }
+    return `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
+
+## Device
+${deviceLine}
 
 ## Available MCP Tools
 
@@ -370,22 +396,26 @@ Control the phone. Requires "action" parameter. All coordinates use normalized r
 - back: Press Back button (no params)
 - home: Press Home button (no params)
 - enter: Press Enter key (no params)
-- open_app: Open an app. Params: appPackage (Android, e.g. "com.tencent.mm"), bundleId (iOS), urlScheme (e.g. "weixin://")
+${openAppDoc}
 - clipboard: Read/write clipboard. Params: clipboardAction ("get"/"set"), text
 - screenshot: Capture screen via control (same as zhihand_screenshot)
 - wait: Wait before next action. Params: durationMs (default 1000)
 
+### zhihand_status
+Get device status: platform, battery, network, BLE connection, dark mode, storage, etc.
+
 ## Rules
 - When the user asks to see their screen, ALWAYS call zhihand_screenshot first.
 - When the user asks to open an app (e.g. WeChat, Settings), use open_app action.
 - When the user asks to go back/home, use back/home actions.
 - For all tap/click operations, use xRatio and yRatio (0-1 normalized coordinates based on the screenshot).`;
+}
 /**
  * Build the full system prompt with optional conversation history.
  * Used for first prompt in persistent sessions and all one-shot calls.
  */
 function wrapPrompt(userPrompt, history) {
-    let result = SYSTEM_CONTEXT;
+    let result = buildSystemContext();
     if (history && history.length > 0) {
         result += "\n\n## Recent Conversation\n";
         for (const turn of history) {
@@ -419,6 +449,7 @@ export function dispatchToCLI(backend, prompt, log, model) {
     }
     const sessionLabel = canReuse ? `#${session.promptCount + 1}` : "new";
     log(`[dispatch] Backend: ${backend}, Model: ${resolvedModel}, Session: ${sessionLabel}`);
+    dbg(`[dispatch] Prompt (${prompt.length} chars): ${prompt.slice(0, 200)}${prompt.length > 200 ? "..." : ""}`);
     if (backend === "gemini") {
         return dispatchGeminiPersistent(prompt, startTime, log, resolvedModel);
     }
@@ -461,6 +492,7 @@ async function dispatchGeminiPersistent(prompt, startTime, log, model) {
         session.promptCount++;
         const turnNum = session.promptCount;
         log(`[gemini] Reusing session — sending prompt #${turnNum}`);
+        dbg(`[gemini] Writing to PTY stdin: ${prompt.slice(0, 200)}${prompt.length > 200 ? "..." : ""}`);
         // Write raw prompt to PTY stdin (gemini already has system context from first prompt)
         session.child.stdin?.write(prompt + "\n");
         const result = await pollGeminiSession(session.child, startTime, prompt, log, session.geminiSessionFile, turnNum);
@@ -483,6 +515,10 @@ async function dispatchGeminiPersistent(prompt, startTime, log, model) {
     };
     const geminiPath = resolveGemini();
     log(`[gemini] Starting new persistent session (model: ${model})`);
+    dbg(`[gemini] Executable: ${geminiPath}`);
+    dbg(`[gemini] PTY wrap: python3 ${PTY_WRAP_SCRIPT}`);
+    dbg(`[gemini] Args: ${JSON.stringify(cliArgs)}`);
+    dbg(`[gemini] Wrapped prompt (${wrappedPrompt.length} chars): ${wrappedPrompt.slice(0, 300)}...`);
     const child = spawn("python3", [PTY_WRAP_SCRIPT, geminiPath, ...cliArgs], {
         env,
         stdio: ["pipe", "pipe", "pipe"], // stdin=pipe for subsequent prompts
@@ -522,6 +558,9 @@ async function dispatchCodexWithHistory(prompt, startTime, log, model) {
     args.push("-");
     const codexPath = resolveCodex();
     log(`[codex] One-shot dispatch (history: ${conversationHistory.length} turns)`);
+    dbg(`[codex] Executable: ${codexPath}`);
+    dbg(`[codex] Args: ${JSON.stringify(args)}`);
+    dbg(`[codex] Stdin prompt (${fullPrompt.length} chars): ${fullPrompt.slice(0, 300)}...`);
     const child = spawn(codexPath, args, {
         env: process.env,
         stdio: ["pipe", "pipe", "pipe"],
@@ -531,6 +570,7 @@ async function dispatchCodexWithHistory(prompt, startTime, log, model) {
     child.stdin?.write(fullPrompt);
     child.stdin?.end();
     const result = await collectCodexOutput(child, startTime);
+    dbg(`[codex] Output: success=${result.success}, duration=${result.durationMs}ms, text (${result.text.length} chars): ${result.text.slice(0, 300)}${result.text.length > 300 ? "..." : ""}`);
     recordTurn("user", prompt);
     recordTurn("assistant", result.text);
     return result;
@@ -544,13 +584,17 @@ async function dispatchClaudeWithHistory(prompt, startTime, log, model) {
     // --permission-mode bypassPermissions: auto-approve all tool calls (like gemini's --approval-mode yolo)
     // --mcp-config: explicitly pass MCP server URL so Claude finds it regardless of cwd
     const mcpConfig = JSON.stringify({ mcpServers: { zhihand: { type: "http", url: MCP_URL } } });
-    const child = spawn(claudePath, [
+    const claudeArgs = [
         "-p", "-",
         "--model", model,
         "--output-format", "json",
         "--permission-mode", "bypassPermissions",
         "--mcp-config", mcpConfig,
-    ], {
+    ];
+    dbg(`[claude] Executable: ${claudePath}`);
+    dbg(`[claude] Args: ${JSON.stringify(claudeArgs)}`);
+    dbg(`[claude] Stdin prompt (${fullPrompt.length} chars): ${fullPrompt.slice(0, 300)}...`);
+    const child = spawn(claudePath, claudeArgs, {
         env: process.env,
         stdio: ["pipe", "pipe", "pipe"],
         detached: false,
@@ -559,8 +603,10 @@ async function dispatchClaudeWithHistory(prompt, startTime, log, model) {
     child.stdin?.write(fullPrompt);
     child.stdin?.end();
     const raw = await collectChildOutput(child, startTime);
+    dbg(`[claude] Raw output (${raw.text.length} chars): ${raw.text.slice(0, 500)}${raw.text.length > 500 ? "..." : ""}`);
     // Claude --output-format json wraps the result in a JSON envelope — extract the actual text
     const result = extractClaudeResult(raw);
+    dbg(`[claude] Parsed result: success=${result.success}, text (${result.text.length} chars)`);
     recordTurn("user", prompt);
     recordTurn("assistant", result.text);
     return result;
@@ -691,8 +737,10 @@ function collectChildOutput(child, startTime) {
 }
 // ── Reply ──────────────────────────────────────────────────
 export async function postReply(config, promptId, text) {
+    const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/prompts/${encodeURIComponent(promptId)}/reply`;
+    dbg(`[reply] POST ${url}`);
+    dbg(`[reply] Body (${text.length} chars): ${text.slice(0, 300)}${text.length > 300 ? "..." : ""}`);
     try {
-        const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/prompts/${encodeURIComponent(promptId)}/reply`;
         const response = await fetch(url, {
             method: "POST",
             headers: {
@@ -702,9 +750,11 @@ export async function postReply(config, promptId, text) {
             body: JSON.stringify({ role: "assistant", text }),
             signal: AbortSignal.timeout(30_000),
         });
+        dbg(`[reply] Response: ${response.status} ${response.statusText}`);
         return response.ok || (response.status >= 400 && response.status < 500);
     }
-    catch {
+    catch (err) {
+        dbg(`[reply] Error: ${err.message}`);
         return false;
     }
 }

package/dist/daemon/heartbeat.js

@@ -1,3 +1,4 @@
+import { dbg } from "./logger.js";
 const HEARTBEAT_INTERVAL = 30_000; // 30s
 const HEARTBEAT_RETRY_INTERVAL = 5_000; // 5s on failure
 let heartbeatTimer;
@@ -18,7 +19,9 @@ async function sendHeartbeat(config, online) {
             body.backend = currentMeta.backend;
         if (currentMeta.model)
             body.model = currentMeta.model;
-        const response = await fetch(buildUrl(config), {
+        const url = buildUrl(config);
+        dbg(`[heartbeat] POST ${url} body=${JSON.stringify(body)}`);
+        const response = await fetch(url, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
@@ -27,9 +30,11 @@ async function sendHeartbeat(config, online) {
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(10_000),
         });
+        dbg(`[heartbeat] Response: ${response.status} ${response.statusText}`);
         return response.ok;
     }
-    catch {
+    catch (err) {
+        dbg(`[heartbeat] Error: ${err.message}`);
         return false;
     }
 }

package/dist/daemon/index.d.ts

@@ -2,5 +2,6 @@ export declare function isAlreadyRunning(): number | null;
 export declare function startDaemon(options?: {
     port?: number;
     deviceName?: string;
+    debug?: boolean;
 }): Promise<void>;
 export declare function stopDaemon(): boolean;

package/dist/daemon/index.js

@@ -10,6 +10,8 @@ import { PACKAGE_VERSION } from "../index.js";
 import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline, setBrainMeta } from "./heartbeat.js";
 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";
 const DEFAULT_PORT = 18686;
 const PID_FILE = "daemon.pid";
 // ── State ──────────────────────────────────────────────────
@@ -30,7 +32,11 @@ async function processPrompt(config, prompt) {
     }
     const preview = prompt.text.length > 40 ? prompt.text.slice(0, 40) + "..." : prompt.text;
     log(`[relay] Prompt: "${preview}" → dispatching to ${activeBackend}...`);
+    dbg(`[relay] Prompt ID: ${prompt.id}, full text (${prompt.text.length} chars): ${prompt.text}`);
+    dbg(`[relay] Prompt metadata: status=${prompt.status}, edge_id=${prompt.edge_id}, created_at=${prompt.created_at}`);
     const result = await dispatchToCLI(activeBackend, prompt.text, log, activeModel ?? undefined);
+    dbg(`[relay] Dispatch result: success=${result.success}, duration=${result.durationMs}ms, text length=${result.text.length}`);
+    dbg(`[relay] Reply text: ${result.text.slice(0, 500)}${result.text.length > 500 ? "..." : ""}`);
     const ok = await postReply(config, prompt.id, result.text);
     const dur = (result.durationMs / 1000).toFixed(1);
     if (ok) {
@@ -50,6 +56,7 @@ async function processQueue(config) {
 }
 function onPromptReceived(config, prompt) {
     promptQueue.push(prompt);
+    dbg(`[queue] Enqueued prompt ${prompt.id}, queue length: ${promptQueue.length}, processing: ${isProcessing}`);
     if (!isProcessing) {
         processQueue(config);
     }
@@ -58,6 +65,7 @@ function onPromptReceived(config, prompt) {
 function handleInternalAPI(req, res) {
     const url = req.url ?? "";
     if (url === "/internal/backend" && req.method === "POST") {
+        dbg(`[api] POST /internal/backend from ${req.socket.remoteAddress}`);
         let body = "";
         const MAX_BODY = 10 * 1024; // 10KB
         req.on("data", (chunk) => {
@@ -95,6 +103,7 @@ function handleInternalAPI(req, res) {
         return true;
     }
     if (url === "/internal/status" && req.method === "GET") {
+        dbg(`[api] GET /internal/status`);
         const effectiveModel = activeBackend ? (activeModel ?? DEFAULT_MODELS[activeBackend]) : null;
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(JSON.stringify({
@@ -146,6 +155,8 @@ export function isAlreadyRunning() {
 }
 // ── Main Daemon Entry ──────────────────────────────────────
 export async function startDaemon(options) {
+    if (options?.debug)
+        setDebugEnabled(true);
     const port = options?.port ?? (parseInt(process.env.ZHIHAND_PORT ?? "", 10) || DEFAULT_PORT);
     // Check if already running
     const existingPid = readPid();
@@ -169,6 +180,8 @@ export async function startDaemon(options) {
     activeModel = backendConfig.model ?? null;
     // Log startup info + set brain meta for heartbeat
     log(`ZhiHand v${PACKAGE_VERSION} starting...`);
+    if (options?.debug)
+        log(`[config] Debug mode enabled — verbose logging active`);
     if (activeBackend) {
         const effectiveModel = activeModel ?? DEFAULT_MODELS[activeBackend];
         log(`[config] Backend: ${activeBackend}, Model: ${effectiveModel}`);
@@ -177,6 +190,15 @@ 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();
+        log(`[device] ${s.platform} ${s.model} (${s.osVersion}), ${s.screenWidthPx}x${s.screenHeightPx}, ${s.locale}`);
+    }
+    else {
+        log(`[device] Device profile not available — tool descriptions will use generic defaults`);
+    }
     // MCP sessions: each client gets its own McpServer + Transport pair
     // because McpServer.connect() can only be called once per instance
     const MAX_MCP_SESSIONS = 20;
@@ -207,6 +229,7 @@ export async function startDaemon(options) {
         if (req.url === "/mcp" || req.url?.startsWith("/mcp")) {
             try {
                 const sessionId = req.headers["mcp-session-id"];
+                dbg(`[mcp] ${req.method} /mcp session=${sessionId?.slice(0, 8) ?? "(new)"} sessions=${mcpSessions.size}`);
                 if (sessionId && mcpSessions.has(sessionId)) {
                     // Existing session
                     const session = mcpSessions.get(sessionId);

package/dist/daemon/logger.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Debug logger for ZhiHand daemon.
+ *
+ * Enable with `zhihand start --debug` to see detailed request/response,
+ * CLI spawn args, stdin/stdout data, SSE events, and timing information.
+ */
+export declare function setDebugEnabled(enabled: boolean): void;
+export declare function isDebugEnabled(): boolean;
+/** Debug log — only outputs when --debug is active. */
+export declare function dbg(msg: string): void;

package/dist/daemon/logger.js

@@ -0,0 +1,22 @@
+/**
+ * Debug logger for ZhiHand daemon.
+ *
+ * Enable with `zhihand start --debug` to see detailed request/response,
+ * CLI spawn args, stdin/stdout data, SSE events, and timing information.
+ */
+let debugEnabled = false;
+export function setDebugEnabled(enabled) {
+    debugEnabled = enabled;
+}
+export function isDebugEnabled() {
+    return debugEnabled;
+}
+function ts() {
+    return new Date().toLocaleTimeString();
+}
+/** Debug log — only outputs when --debug is active. */
+export function dbg(msg) {
+    if (!debugEnabled)
+        return;
+    process.stdout.write(`[${ts()}] [DEBUG] ${msg}\n`);
+}

package/dist/daemon/prompt-listener.js

@@ -1,3 +1,5 @@
+import { updateDeviceProfile } from "../core/device.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;
@@ -29,9 +31,12 @@ export class PromptListener {
         }
     }
     dispatchPrompt(prompt) {
-        if (this.processedIds.has(prompt.id))
+        if (this.processedIds.has(prompt.id)) {
+            dbg(`[prompt] Skipping duplicate prompt: ${prompt.id}`);
             return;
+        }
         this.processedIds.add(prompt.id);
+        dbg(`[prompt] Dispatching prompt: id=${prompt.id}, status=${prompt.status}, text="${prompt.text.slice(0, 100)}${prompt.text.length > 100 ? "..." : ""}"`);
         // Prevent unbounded growth
         if (this.processedIds.size > 500) {
             const arr = [...this.processedIds];
@@ -44,6 +49,7 @@ export class PromptListener {
             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",
@@ -52,6 +58,7 @@ export class PromptListener {
                     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;
@@ -114,6 +121,7 @@ export class PromptListener {
         }, SSE_WATCHDOG_TIMEOUT);
     }
     handleSSEEvent(event) {
+        dbg(`[sse] Event: kind=${event.kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
         if (event.kind === "prompt.queued" && event.prompt) {
             this.dispatchPrompt(event.prompt);
         }
@@ -124,6 +132,13 @@ export class PromptListener {
                 }
             }
         }
+        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);
+        }
     }
     startPolling() {
         if (this.pollTimer)
@@ -152,19 +167,23 @@ export class PromptListener {
     async poll() {
         try {
             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 },
                 signal: AbortSignal.timeout(10_000),
             });
-            if (!response.ok)
+            if (!response.ok) {
+                dbg(`[poll] Response: ${response.status}`);
                 return;
+            }
             const data = (await response.json());
+            dbg(`[poll] Got ${data.items?.length ?? 0} prompt(s)`);
             for (const prompt of data.items ?? []) {
                 this.dispatchPrompt(prompt);
             }
         }
-        catch {
-            // Polling failure is non-fatal
+        catch (err) {
+            dbg(`[poll] Error: ${err.message}`);
         }
     }
 }

package/dist/index.d.ts

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

package/dist/index.js

@@ -5,29 +5,60 @@ import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js"
 import { executeControl } from "./tools/control.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-export const PACKAGE_VERSION = "0.24.1";
+import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
+export const PACKAGE_VERSION = "0.26.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",
         version: PACKAGE_VERSION,
     });
     // zhihand_control — main phone control tool
-    server.tool("zhihand_control", controlSchema, async (params) => {
+    // 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);
     });
     // zhihand_screenshot — capture current screen without any action
-    server.tool("zhihand_screenshot", screenshotSchema, async () => {
+    server.tool("zhihand_screenshot", buildScreenshotToolDescription(), screenshotSchema, async () => {
         const config = resolveConfig(deviceName);
         return await handleScreenshot(config);
     });
+    // zhihand_status — return device context for LLM to query on demand
+    server.tool("zhihand_status", "Get device status: platform, model, OS version, screen size, battery, network, BLE, dark mode, storage, and more.", {}, async () => {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(formatDeviceStatus(), null, 2),
+                }],
+        };
+    });
     // zhihand_pair — device pairing
-    server.tool("zhihand_pair", pairSchema, async (params) => {
+    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();
+        return {
+            contents: [{
+                    uri: "device://profile",
+                    mimeType: "application/json",
+                    text: JSON.stringify({ ...staticCtx, ...dynamicCtx }, 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);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhihand/mcp",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "private": false,
   "type": "module",
   "description": "ZhiHand MCP Server — phone control tools for Claude Code, Codex, Gemini CLI, and OpenClaw",