@zhihand/mcp 0.23.1 → 0.25.0

package/README.md

@@ -2,7 +2,7 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.23.0`
+Version: `0.25.0`
 
 ## What is this?
 
@@ -93,9 +93,11 @@ 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
 
+zhihand test               Test device connectivity (screenshot, click, swipe, home, back)
 zhihand pair               Pair with a phone (QR code in terminal)
 zhihand detect             List detected CLI tools and their login status
 zhihand serve              Start MCP Server (stdio mode, backward compatible)
@@ -112,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
 ```
@@ -158,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

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)
 
@@ -51,6 +53,7 @@ Usage:
   zhihand pair               Pair with a phone device
   zhihand detect             Detect available CLI tools
 
+  zhihand test               Test device connectivity (sends click + type commands)
   zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
@@ -58,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);
@@ -144,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");
@@ -166,6 +171,7 @@ switch (command) {
     await startDaemon({
       port,
       deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+      debug: values.debug,
     });
     break;
   }
@@ -280,6 +286,87 @@ switch (command) {
     break;
   }
 
+  case "test": {
+    const { resolveConfig: resolveTestConfig } = await import("../dist/core/config.js");
+    const { createControlCommand, enqueueCommand } = await import("../dist/core/command.js");
+    const { waitForCommandAck } = await import("../dist/core/sse.js");
+    const { fetchScreenshotBinary } = await import("../dist/core/screenshot.js");
+
+    let testConfig;
+    try {
+      testConfig = resolveTestConfig(values.device ?? process.env.ZHIHAND_DEVICE);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      console.error("Run 'zhihand setup' to pair a device first.");
+      process.exit(1);
+    }
+
+    console.log("🧪 ZhiHand Device Test");
+    console.log(`   Device: ${testConfig.credentialId}`);
+    console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}\n`);
+
+    const steps = [
+      { label: "1. Screenshot", type: "screenshot" },
+      { label: "2. Click center", type: "hid", params: { action: "click", xRatio: 0.5, yRatio: 0.5 } },
+      { 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" },
+    ];
+
+    let passed = 0;
+    let failed = 0;
+
+    for (const step of steps) {
+      process.stdout.write(`   ${step.label}... `);
+      const t0 = Date.now();
+      try {
+        if (step.type === "screenshot") {
+          // Screenshot: send receive_screenshot command, then fetch binary
+          const cmd = createControlCommand({ action: "screenshot" });
+          const queued = await enqueueCommand(testConfig, cmd);
+          const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
+          if (ack.acked) {
+            const buf = await fetchScreenshotBinary(testConfig);
+            const ms = Date.now() - t0;
+            console.log(`✅ ${(buf.length / 1024).toFixed(0)}KB (${ms}ms)`);
+            passed++;
+          } else {
+            console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
+            failed++;
+          }
+        } else {
+          const cmd = createControlCommand(step.params);
+          const queued = await enqueueCommand(testConfig, cmd);
+          const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
+          const ms = Date.now() - t0;
+          if (ack.acked) {
+            console.log(`✅ (${ms}ms)`);
+            passed++;
+          } else {
+            console.log(`⏱️  Timeout (${ms}ms)`);
+            failed++;
+          }
+        }
+      } catch (err) {
+        const ms = Date.now() - t0;
+        console.log(`❌ ${err.message} (${ms}ms)`);
+        failed++;
+      }
+      // Pause between commands: let phone process + user can observe
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+
+    console.log(`\n   Result: ${passed}/${steps.length} passed`);
+    if (failed === 0) {
+      console.log("   ✅ Device is responding to all commands!");
+    } else {
+      console.log("   ⚠️  Some commands failed. Check phone connectivity.");
+    }
+    process.exit(failed > 0 ? 1 : 0);
+  }
+
   default:
     console.error(`Unknown command: ${command}. Run 'zhihand --help' for usage.`);
     process.exit(1);

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,37 @@ 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());
+    dbg(`[cmd] Got: id=${payload.command.id}, status=${payload.command.status}, acked=${!!payload.command.acked_at}`);
     return payload.command;
 }
 export function formatAckSummary(action, result) {

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}`);
             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,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 { 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 +264,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",
@@ -419,6 +421,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 +464,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 +487,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 +530,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 +542,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 +556,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,
@@ -558,11 +574,31 @@ async function dispatchClaudeWithHistory(prompt, startTime, log, model) {
     // Write prompt to stdin, then close to signal EOF
     child.stdin?.write(fullPrompt);
     child.stdin?.end();
-    const result = await collectChildOutput(child, startTime);
+    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;
 }
+/** Parse Claude JSON output and extract the result text. */
+function extractClaudeResult(raw) {
+    try {
+        const parsed = JSON.parse(raw.text);
+        if (!parsed || typeof parsed !== "object")
+            return raw;
+        const resultText = typeof parsed.result === "string" ? parsed.result : raw.text;
+        const isError = parsed.is_error === true || parsed.subtype === "error";
+        // Preserve process exit failure: only succeed if both JSON and process agree
+        return { text: resultText, success: raw.success && !isError, durationMs: raw.durationMs };
+    }
+    catch {
+        // Not JSON — return as-is
+        return raw;
+    }
+}
 // ── Codex JSONL Output Collector ──────────────────────────────
 function collectCodexOutput(child, startTime) {
     return new Promise((resolve) => {
@@ -673,8 +709,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: {
@@ -684,9 +722,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,7 @@ 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";
 const DEFAULT_PORT = 18686;
 const PID_FILE = "daemon.pid";
 // ── State ──────────────────────────────────────────────────
@@ -30,7 +31,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 +55,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 +64,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 +102,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 +154,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 +179,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}`);
@@ -207,6 +219,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,4 @@
+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 +30,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 +48,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 +57,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 +120,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);
         }
@@ -152,19 +159,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.23.1";
+export declare const PACKAGE_VERSION = "0.25.0";
 export declare function createServer(deviceName?: string): McpServer;
 export declare function startStdioServer(deviceName?: string): Promise<void>;

package/dist/index.js

@@ -5,7 +5,7 @@ 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.23.1";
+export const PACKAGE_VERSION = "0.25.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",

package/package.json

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