@zhihand/mcp 0.15.0 → 0.16.0

package/README.md

@@ -2,22 +2,30 @@
 
 ZhiHand MCP Server — let AI agents see and control your phone.
 
-Version: `0.15.0`
+Version: `0.16.0`
 
 ## What is this?
 
-`@zhihand/mcp` is the core integration layer for ZhiHand. It provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes phone control tools to any compatible AI agent, including:
+`@zhihand/mcp` is the core integration layer for ZhiHand. It runs as a **persistent daemon** that exposes phone control tools to any compatible AI agent via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/), including:
 
 - **Claude Code**
 - **Codex CLI**
 - **Gemini CLI**
 - **OpenClaw**
 
-One npm package, two entry points:
+The daemon is a single persistent process that bundles three subsystems:
+
+| Subsystem | Purpose |
+|---|---|
+| **MCP Server** | HTTP Streamable transport on `localhost:18686/mcp` — serves tool calls to AI agents |
+| **Relay** | Brain heartbeat (30s), prompt listener (phone-initiated tasks), CLI dispatch |
+| **Config API** | IPC endpoint for `zhihand gemini/claude/codex` backend switching |
+
+Legacy entry points (backward compatible):
 
 | Entry | Purpose |
 |---|---|
-| `zhihand serve` | MCP Server (stdio) — used by Claude Code, Codex, Gemini CLI |
+| `zhihand serve` | MCP Server (stdio mode) — legacy, still works for direct CLI integration |
 | `zhihand.openclaw` | OpenClaw Plugin entry — thin wrapper calling the same core |
 
 ## Requirements
@@ -53,10 +61,20 @@ This runs the full interactive setup:
 4. Saves credentials to `~/.zhihand/credentials.json`
 5. Detects installed CLI tools (Claude Code, Codex, Gemini CLI, OpenClaw)
 6. Auto-selects the best available tool and configures MCP automatically
+7. Starts the daemon (MCP Server + Relay + Config API)
 
 No manual MCP configuration needed — `zhihand setup` handles everything.
 
-### 2. Start using it
+### 2. Start the daemon
+
+```bash
+zhihand start              # Start daemon in foreground
+zhihand start -d           # Start daemon in background (detached)
+```
+
+The daemon runs the MCP Server on `localhost:18686/mcp` (HTTP Streamable transport), maintains a brain heartbeat every 30 seconds (keeps the phone Brain indicator green), and listens for phone-initiated prompts.
+
+### 3. Start using it
 
 Once configured, your AI agent can use ZhiHand tools directly. For example, in Claude Code:
 
@@ -70,18 +88,36 @@ Once configured, your AI agent can use ZhiHand tools directly. For example, in C
 ## CLI Commands
 
 ```
-zhihand serve              Start MCP Server (stdio mode, called by AI tools)
-zhihand setup              Interactive setup: pair + auto-detect + auto-configure
+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 (detached)
+zhihand stop               Stop the running daemon
+zhihand status             Show daemon status, pairing info, device, and active backend
+
 zhihand pair               Pair with a phone (QR code in terminal)
-zhihand status             Show pairing status, device info, and active backend
 zhihand detect             List detected CLI tools and their login status
+zhihand serve              Start MCP Server (stdio mode, backward compatible)
 zhihand --help             Show help
 
-zhihand claude             Switch backend to Claude Code (auto-configures MCP)
-zhihand codex              Switch backend to Codex CLI (auto-configures MCP)
-zhihand gemini             Switch backend to Gemini CLI (auto-configures MCP)
+zhihand claude             Switch backend to Claude Code (sends IPC to daemon, auto-configures MCP)
+zhihand codex              Switch backend to Codex CLI (sends IPC to daemon, auto-configures MCP)
+zhihand gemini             Switch backend to Gemini CLI (sends IPC to daemon, auto-configures MCP)
 ```
 
+### Daemon Lifecycle
+
+```bash
+zhihand start              # Start daemon in foreground
+zhihand start -d           # Start daemon in background
+zhihand stop               # Stop the daemon
+zhihand status             # Check if daemon is running, show device & backend info
+```
+
+The daemon is a single persistent process that runs:
+- **MCP Server** on `localhost:18686/mcp` (HTTP Streamable transport)
+- **Relay**: brain heartbeat every 30s (keeps phone Brain indicator green), prompt listener (phone-initiated tasks dispatched to CLI), CLI dispatch
+- **Config API**: IPC endpoint for backend switching
+
 ### Switching Backends
 
 Use `zhihand claude`, `zhihand codex`, or `zhihand gemini` to switch the active backend:
@@ -93,6 +129,7 @@ zhihand codex              # Switch to Codex CLI
 ```
 
 When you switch:
+- The command sends an **IPC message to the running daemon**
 - MCP config is **automatically added** to the new backend
 - MCP config is **automatically removed** from the previous backend
 - If the tool is not installed, an error is shown
@@ -154,26 +191,40 @@ Pair with a phone device. Returns a QR code and pairing URL.
 ## How It Works
 
 ```
-AI Agent ←stdio→ zhihand serve (MCP Server)
-                       │
-                       ├── POST /v1/plugins           Register plugin
-                       ├── POST /v1/pairing/sessions   Create pairing
-                       ├── POST /v1/credentials/{id}/commands   Send command
-                       ├── GET  /v1/credentials/{id}/commands/{cid}   Poll ACK
-                       ├── SSE  /v1/credentials/{id}/events?topic=commands   Real-time ACK
-                       └── GET  /v1/credentials/{id}/screen   Fetch screenshot (JPEG)
-                       │
-                  ZhiHand Server
-                       │
-                  ZhiHand Mobile App
+AI Agent ←HTTP Streamable→ Daemon (localhost:18686/mcp)
+                               │
+                               ├── MCP Server ──→ ZhiHand Server ──→ Mobile App
+                               │     (tool calls: control, screenshot, pair)
+                               │
+                               ├── Relay
+                               │     ├── Brain heartbeat (30s) ──→ Server
+                               │     ├── Prompt listener (SSE) ←── Server ←── Phone
+                               │     └── CLI dispatch ──→ spawn claude/codex/gemini
+                               │
+                               └── Config API
+                                     └── IPC from zhihand claude/codex/gemini
 ```
 
+### Agent-initiated flow (tool calls)
+
 1. AI agent calls a tool (e.g. `zhihand_control` with `action: "click"`)
 2. MCP Server translates to a device command and enqueues it via the ZhiHand API
 3. Mobile app picks up the command, executes it, and sends an ACK
 4. MCP Server receives the ACK (via SSE or polling fallback)
 5. MCP Server fetches a fresh screenshot and returns it to the AI agent
 
+### Phone-initiated flow (prompt relay)
+
+1. User speaks or types a prompt on the phone
+2. Phone sends prompt to ZhiHand Server
+3. Daemon receives prompt via SSE
+4. Daemon spawns the active CLI tool (e.g. `claude`, `codex`, `gemini`) with the prompt
+5. CLI tool executes, result is sent back to the phone
+
+### Brain heartbeat
+
+The daemon sends a heartbeat to the ZhiHand Server every 30 seconds. This keeps the **Brain indicator green** on the phone, showing the user that an AI backend is connected and ready.
+
 Screenshots are transferred as raw JPEG binary and only base64-encoded at the LLM API boundary, minimizing bandwidth.
 
 ## Credential Storage
@@ -184,6 +235,7 @@ Pairing credentials are stored at:
 ~/.zhihand/
 ├── credentials.json    # Device credentials (credentialId, controllerToken, endpoint)
 ├── backend.json        # Active backend selection (claudecode/codex/gemini)
+├── daemon.pid          # Daemon PID file (for zhihand stop)
 └── state.json          # Current pairing session state
 ```
 
@@ -209,10 +261,10 @@ You can manage multiple devices. The `credentials.json` file stores a `default`
 ```
 packages/mcp/
 ├── bin/
-│   ├── zhihand              # Main CLI entry (serve/setup/pair/status/detect)
+│   ├── zhihand              # Main CLI entry (start/stop/status/setup/serve/pair/detect)
 │   └── zhihand.openclaw     # OpenClaw plugin entry
 ├── src/
-│   ├── index.ts             # MCP Server (stdio transport)
+│   ├── index.ts             # MCP Server (stdio transport, legacy)
 │   ├── openclaw.adapter.ts  # OpenClaw Plugin adapter (thin wrapper)
 │   ├── core/
 │   │   ├── config.ts        # Credential & config management (~/.zhihand/)
@@ -220,6 +272,11 @@ packages/mcp/
 │   │   ├── 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
+│   │   ├── 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)
 │   ├── tools/
 │   │   ├── schemas.ts       # Zod parameter schemas
 │   │   ├── control.ts       # zhihand_control handler

package/bin/zhihand

@@ -3,6 +3,7 @@
 import os from "node:os";
 import { parseArgs } from "node:util";
 import { startStdioServer } from "../dist/index.js";
+import { startDaemon, stopDaemon, isAlreadyRunning } from "../dist/daemon/index.js";
 import { detectCLITools, formatDetectedTools } from "../dist/cli/detect.js";
 import { detectAndSetupOpenClaw } from "../dist/cli/openclaw.js";
 import { loadDefaultCredential, loadBackendConfig, saveBackendConfig } from "../dist/core/config.js";
@@ -22,9 +23,9 @@ const { positionals, values } = parseArgs({
   strict: false,
   options: {
     device: { type: "string" },
-    model: { type: "string" },
-    http: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false },
+    detach: { type: "boolean", short: "d", default: false },
+    port: { type: "string" },
   },
 });
 
@@ -32,28 +33,35 @@ const command = positionals[0] ?? "serve";
 
 if (values.help) {
   console.log(`
-zhihand — MCP Server for phone control
+zhihand — MCP Server and Relay for phone control
 
 Usage:
-  zhihand serve              Start MCP Server (stdio mode)
-  zhihand serve --http       Start MCP Server (HTTP mode)
-  zhihand pair               Pair with a phone device
-  zhihand status             Show pairing status and device info
-  zhihand detect             Detect available CLI tools
-  zhihand setup              Interactive setup: pair + auto-configure
+  zhihand start              Start daemon (MCP Server + Relay, foreground)
+  zhihand start -d           Start daemon in background (detach)
+  zhihand stop               Stop daemon
+  zhihand status             Show status (pairing, backend, brain)
 
+  zhihand gemini             Switch backend to Gemini CLI
   zhihand claude             Switch backend to Claude Code
   zhihand codex              Switch backend to Codex CLI
-  zhihand gemini             Switch backend to Gemini CLI
+
+  zhihand setup              Interactive setup: pair + configure + start
+  zhihand pair               Pair with a phone device
+  zhihand detect             Detect available CLI tools
+
+  zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
   --device <name>    Use a specific paired device
+  --port <port>      Override daemon port (default: 18686)
+  -d, --detach       Run daemon in background
   -h, --help         Show this help
 `);
   process.exit(0);
 }
 
-// Handle CLI tool subcommands: claude, codex, gemini → switch backend
+// ── Backend switch commands: claude, codex, gemini ─────────
+
 if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
   const backendName = CLI_TOOL_MAP[command];
   const tools = await detectCLITools();
@@ -69,6 +77,8 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
     console.error(`Warning: ${command} is installed but not logged in.`);
   }
 
+  // Check if daemon is running — if so, notify it via HTTP
+  const daemonPid = isAlreadyRunning();
   const config = loadBackendConfig();
   const previous = config.activeBackend;
 
@@ -78,20 +88,82 @@ if (Object.prototype.hasOwnProperty.call(CLI_TOOL_MAP, command)) {
   }
 
   console.log(`Switching backend to ${displayName(backendName)}...`);
+
+  // Configure MCP (HTTP transport)
   const { configured, removed } = configureMCP(backendName, previous);
 
   if (configured) {
-    saveBackendConfig({ activeBackend: backendName });
-    console.log(`\nBackend switched to ${displayName(backendName)}.`);
-    if (previous) {
-      console.log(`Previous backend: ${displayName(previous)} ${removed ? '(MCP config removed)' : '(MCP config removal skipped)'}.`);
+    // Notify daemon if running
+    if (daemonPid) {
+      try {
+        const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+        const res = await fetch(`http://127.0.0.1:${port}/internal/backend`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ backend: backendName }),
+          signal: AbortSignal.timeout(5000),
+        });
+        if (res.ok) {
+          console.log(`\nDaemon notified. Backend switched to ${displayName(backendName)}.`);
+        }
+      } catch {
+        // Daemon not responding, just save config
+        saveBackendConfig({ activeBackend: backendName });
+        console.log(`\nBackend config saved. Daemon not responding — restart with 'zhihand start'.`);
+      }
+    } else {
+      saveBackendConfig({ activeBackend: backendName });
+      console.log(`\nBackend switched to ${displayName(backendName)}.`);
+      console.log(`Start the daemon to receive prompts: zhihand start`);
+    }
+
+    if (previous && removed) {
+      console.log(`Previous backend: ${displayName(previous)} (MCP config removed).`);
     }
   }
   process.exit(0);
 }
 
+// ── Other commands ─────────────────────────────────────────
+
 switch (command) {
+  case "start":
+  case "relay": {
+    if (values.detach) {
+      const { spawn: spawnChild } = await import("node:child_process");
+      const args = [process.argv[1], "start"];
+      if (values.port) args.push("--port", values.port);
+      if (values.device) args.push("--device", values.device);
+
+      const child = spawnChild(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env },
+      });
+      child.unref();
+      console.log(`Daemon starting in background (PID ${child.pid}).`);
+      process.exit(0);
+    }
+    const port = values.port ? parseInt(values.port, 10) : undefined;
+    await startDaemon({
+      port,
+      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+    });
+    break;
+  }
+
+  case "stop": {
+    const stopped = stopDaemon();
+    if (stopped) {
+      console.log("Daemon stopped.");
+    } else {
+      console.log("No daemon is running.");
+    }
+    break;
+  }
+
   case "serve": {
+    // Backward compatible: stdio MCP server (for old configs)
     await startStdioServer(values.device ?? process.env.ZHIHAND_DEVICE);
     break;
   }
@@ -106,18 +178,31 @@ switch (command) {
   case "status": {
     const cred = loadDefaultCredential();
     const backend = loadBackendConfig();
+    const daemonPid = isAlreadyRunning();
+
     if (cred) {
       console.log(`Paired device: ${cred.deviceName}`);
       console.log(`Credential ID: ${cred.credentialId}`);
       console.log(`Endpoint: ${cred.endpoint}`);
-      console.log(`Paired at: ${cred.pairedAt}`);
     } else {
-      console.log("No paired device. Run: zhihand pair");
+      console.log("No paired device. Run: zhihand setup");
     }
-    if (backend.activeBackend) {
-      console.log(`Active backend: ${displayName(backend.activeBackend)}`);
-    } else {
-      console.log("No active backend. Run: zhihand claude / zhihand gemini / zhihand codex");
+    console.log(`Active backend: ${backend.activeBackend ? displayName(backend.activeBackend) : "(none)"}`);
+    console.log(`Daemon: ${daemonPid ? `running (PID ${daemonPid})` : "not running"}`);
+
+    // If daemon running, get live status
+    if (daemonPid) {
+      try {
+        const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || 18686;
+        const res = await fetch(`http://127.0.0.1:${port}/internal/status`, {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+          const status = await res.json();
+          console.log(`Processing: ${status.processing ? "yes" : "idle"}`);
+          console.log(`Queue: ${status.queueLength} prompt(s)`);
+        }
+      } catch { /* daemon not responding */ }
     }
     break;
   }
@@ -129,7 +214,7 @@ switch (command) {
   }
 
   case "setup": {
-    // 1. Check/create pairing
+    // 1. Pair
     let cred = loadDefaultCredential();
     if (!cred) {
       console.log("No paired device found. Starting pairing...\n");
@@ -142,30 +227,34 @@ switch (command) {
       console.log(`\nPaired: ${cred.deviceName} (${cred.credentialId})\n`);
     }
 
-    // 2. Detect CLI tools
+    // 2. Detect tools
     const tools = await detectCLITools();
     console.log(formatDetectedTools(tools));
 
     if (tools.length === 0) {
-      console.log("\nNo CLI tools detected. Install one of: Claude Code, Codex CLI, Gemini CLI, OpenClaw.");
+      console.log("\nNo CLI tools detected. Install one of: Claude Code, Codex CLI, Gemini CLI.");
       break;
     }
 
-    // 3. Auto-select best tool (logged in + highest priority) and configure
+    // 3. Auto-select best tool and configure MCP (HTTP transport)
     const best = tools.find((t) => t.loggedIn) ?? tools[0];
     const config = loadBackendConfig();
 
     console.log(`\nAuto-selecting backend: ${displayName(best.name)}...`);
-
-    if (best.name === "openclaw") {
-      await detectAndSetupOpenClaw();
-    } else {
-      configureMCP(best.name, config.activeBackend);
+    // Ensure MCP URL uses correct port
+    if (values.port) {
+      process.env.ZHIHAND_PORT = values.port;
     }
-
+    configureMCP(best.name, config.activeBackend);
     saveBackendConfig({ activeBackend: best.name });
-    console.log(`\nSetup complete. Backend: ${displayName(best.name)}.`);
-    console.log(`To switch backend later: zhihand claude / zhihand gemini / zhihand codex`);
+
+    // 4. Start daemon
+    console.log(`\nStarting daemon...\n`);
+    const port = values.port ? parseInt(values.port, 10) : undefined;
+    await startDaemon({
+      port,
+      deviceName: values.device ?? process.env.ZHIHAND_DEVICE,
+    });
     break;
   }
 

package/dist/cli/mcp-config.d.ts

@@ -1,6 +1,6 @@
 import type { BackendName } from "../core/config.ts";
 /**
- * Configure MCP for the selected backend and remove from others.
+ * Configure MCP (HTTP transport) for the selected backend and remove from others.
  */
 export declare function configureMCP(backend: BackendName, previousBackend: BackendName | null): {
     configured: boolean;

package/dist/cli/mcp-config.js

@@ -1,15 +1,20 @@
 import { execSync } from "node:child_process";
+const DEFAULT_PORT = 18686;
+function mcpUrl() {
+    const port = parseInt(process.env.ZHIHAND_PORT ?? "", 10) || DEFAULT_PORT;
+    return `http://localhost:${port}/mcp`;
+}
 const MCP_COMMANDS = {
     claudecode: {
-        add: "claude mcp add zhihand -- zhihand serve",
+        add: () => `claude mcp add --transport http zhihand ${mcpUrl()}`,
         remove: "claude mcp remove zhihand",
     },
     codex: {
-        add: "codex mcp add zhihand -- zhihand serve",
+        add: () => `codex mcp add zhihand --url ${mcpUrl()}`,
         remove: "codex mcp remove zhihand",
     },
     gemini: {
-        add: "gemini mcp add --scope user zhihand zhihand -- serve",
+        add: () => `gemini mcp add --transport http --scope user zhihand ${mcpUrl()}`,
         remove: "gemini mcp remove --scope user zhihand",
     },
 };
@@ -29,7 +34,7 @@ function tryRun(cmd) {
     }
 }
 /**
- * Configure MCP for the selected backend and remove from others.
+ * Configure MCP (HTTP transport) for the selected backend and remove from others.
  */
 export function configureMCP(backend, previousBackend) {
     let removed = false;
@@ -49,9 +54,10 @@ export function configureMCP(backend, previousBackend) {
     }
     else {
         const cmds = MCP_COMMANDS[backend];
-        console.log(`  Configuring MCP for ${DISPLAY_NAMES[backend]}...`);
+        const addCmd = cmds.add();
+        console.log(`  Configuring MCP for ${DISPLAY_NAMES[backend]} (HTTP transport)...`);
         try {
-            execSync(cmds.add, { stdio: "inherit", timeout: 10_000 });
+            execSync(addCmd, { stdio: "inherit", timeout: 10_000 });
             configured = true;
         }
         catch (err) {

package/dist/daemon/dispatcher.d.ts

@@ -0,0 +1,13 @@
+import type { ZhiHandConfig, BackendName } from "../core/config.ts";
+export interface DispatchResult {
+    text: string;
+    success: boolean;
+    durationMs: number;
+}
+/**
+ * Kill the active child process. Returns a promise that resolves
+ * when the child has exited (or immediately if no child).
+ */
+export declare function killActiveChild(): Promise<void>;
+export declare function dispatchToCLI(backend: Exclude<BackendName, "openclaw">, prompt: string, model?: string): Promise<DispatchResult>;
+export declare function postReply(config: ZhiHandConfig, promptId: string, text: string): Promise<boolean>;

package/dist/daemon/dispatcher.js

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+const CLI_TIMEOUT = 120_000; // 120s
+const SIGKILL_DELAY = 2_000; // 2s after SIGTERM
+const MAX_OUTPUT_BYTES = 100 * 1024; // 100KB
+const BACKENDS = {
+    gemini: {
+        command: "gemini",
+        buildArgs: (prompt, model) => [
+            "--approval-mode", "yolo",
+            "--model", model ?? process.env.CLAUDE_GEMINI_MODEL ?? "gemini-3.1-pro-preview",
+            "-i", prompt,
+        ],
+        env: {
+            GEMINI_SANDBOX: "false",
+            TERM: "xterm-256color",
+            COLORTERM: "truecolor",
+        },
+    },
+    claudecode: {
+        command: "claude",
+        buildArgs: (prompt) => ["-p", prompt, "--output-format", "json"],
+    },
+    codex: {
+        command: "codex",
+        buildArgs: (prompt) => ["-q", prompt, "--json"],
+    },
+};
+let activeChild = null;
+/**
+ * Kill the active child process. Returns a promise that resolves
+ * when the child has exited (or immediately if no child).
+ */
+export function killActiveChild() {
+    if (!activeChild || activeChild.killed) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const child = activeChild;
+        child.once("close", () => resolve());
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (!child.killed) {
+                child.kill("SIGKILL");
+            }
+        }, SIGKILL_DELAY);
+        // Safety: resolve after SIGKILL_DELAY + 1s even if no close event
+        setTimeout(() => resolve(), SIGKILL_DELAY + 1000);
+    });
+}
+export function dispatchToCLI(backend, prompt, model) {
+    const config = BACKENDS[backend];
+    if (!config) {
+        return Promise.resolve({
+            text: `Unsupported backend: ${backend}`,
+            success: false,
+            durationMs: 0,
+        });
+    }
+    const startTime = Date.now();
+    const args = config.buildArgs(prompt, model);
+    const env = { ...process.env, ...config.env };
+    return new Promise((resolve) => {
+        const chunks = [];
+        let totalBytes = 0;
+        let truncated = false;
+        let settled = false;
+        function settle(result) {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        }
+        const child = spawn(config.command, args, {
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: false,
+        });
+        activeChild = child;
+        // Timeout with two-stage kill
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!child.killed)
+                    child.kill("SIGKILL");
+            }, SIGKILL_DELAY);
+        }, CLI_TIMEOUT);
+        const collectOutput = (data) => {
+            if (truncated)
+                return;
+            totalBytes += data.length;
+            if (totalBytes > MAX_OUTPUT_BYTES) {
+                truncated = true;
+                chunks.push(data.subarray(0, MAX_OUTPUT_BYTES - (totalBytes - data.length)));
+            }
+            else {
+                chunks.push(data);
+            }
+        };
+        child.stdout?.on("data", collectOutput);
+        child.stderr?.on("data", collectOutput);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            activeChild = null;
+            const durationMs = Date.now() - startTime;
+            let text = Buffer.concat(chunks).toString("utf8").trim();
+            if (truncated) {
+                text += "\n\n[Output truncated at 100KB]";
+            }
+            if (!text) {
+                text = code === 0
+                    ? "Task completed (no output)."
+                    : `CLI process exited with code ${code}.`;
+            }
+            settle({ text, success: code === 0, durationMs });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            activeChild = null;
+            settle({
+                text: `CLI launch failed: ${err.message}`,
+                success: false,
+                durationMs: Date.now() - startTime,
+            });
+        });
+    });
+}
+export async function postReply(config, promptId, text) {
+    try {
+        const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/prompts/${encodeURIComponent(promptId)}/reply`;
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-zhihand-controller-token": config.controllerToken,
+            },
+            body: JSON.stringify({ role: "assistant", text }),
+            signal: AbortSignal.timeout(30_000),
+        });
+        // 4xx = prompt cancelled, that's OK
+        return response.ok || (response.status >= 400 && response.status < 500);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/daemon/heartbeat.d.ts

@@ -0,0 +1,5 @@
+import type { ZhiHandConfig } from "../core/config.ts";
+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 stopHeartbeatLoop(): void;

package/dist/daemon/heartbeat.js

@@ -0,0 +1,65 @@
+const HEARTBEAT_INTERVAL = 30_000; // 30s
+const HEARTBEAT_RETRY_INTERVAL = 5_000; // 5s on failure
+let heartbeatTimer;
+let retryTimer;
+function buildUrl(config) {
+    return `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/brain-status`;
+}
+async function sendHeartbeat(config, online) {
+    try {
+        const response = await fetch(buildUrl(config), {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-zhihand-controller-token": config.controllerToken,
+            },
+            body: JSON.stringify({ plugin_online: online }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function sendBrainOnline(config) {
+    return sendHeartbeat(config, true);
+}
+export async function sendBrainOffline(config) {
+    return sendHeartbeat(config, false);
+}
+export function startHeartbeatLoop(config, log) {
+    let retrying = false;
+    async function beat() {
+        const ok = await sendBrainOnline(config);
+        if (!ok && !retrying) {
+            retrying = true;
+            log("[heartbeat] Failed, retrying every 5s...");
+            // Fast retry to recover before 40s TTL
+            retryTimer = setInterval(async () => {
+                const recovered = await sendBrainOnline(config);
+                if (recovered) {
+                    retrying = false;
+                    if (retryTimer) {
+                        clearInterval(retryTimer);
+                        retryTimer = undefined;
+                    }
+                    log("[heartbeat] Recovered.");
+                }
+            }, HEARTBEAT_RETRY_INTERVAL);
+        }
+    }
+    // Immediate first heartbeat
+    beat();
+    heartbeatTimer = setInterval(beat, HEARTBEAT_INTERVAL);
+}
+export function stopHeartbeatLoop() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = undefined;
+    }
+    if (retryTimer) {
+        clearInterval(retryTimer);
+        retryTimer = undefined;
+    }
+}

package/dist/daemon/index.d.ts

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

package/dist/daemon/index.js

@@ -0,0 +1,283 @@
+import { createServer as createHTTPServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+// Transport type used only for cleanup interface
+import { createServer as createMcpServer } from "../index.js";
+import { resolveConfig, loadBackendConfig, saveBackendConfig, resolveZhiHandDir, ensureZhiHandDir, } from "../core/config.js";
+import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline } from "./heartbeat.js";
+import { PromptListener } from "./prompt-listener.js";
+import { dispatchToCLI, postReply, killActiveChild } from "./dispatcher.js";
+const DEFAULT_PORT = 18686;
+const PID_FILE = "daemon.pid";
+// ── State ──────────────────────────────────────────────────
+let activeBackend = null;
+let isProcessing = false;
+const promptQueue = [];
+function log(msg) {
+    const ts = new Date().toLocaleTimeString();
+    process.stdout.write(`[${ts}] ${msg}\n`);
+}
+// ── Prompt Processing ──────────────────────────────────────
+async function processPrompt(config, prompt) {
+    if (!activeBackend) {
+        log(`[relay] No backend configured. Replying with error.`);
+        await postReply(config, prompt.id, "No AI backend configured. Run: zhihand gemini / zhihand claude / zhihand codex");
+        return;
+    }
+    const preview = prompt.text.length > 40 ? prompt.text.slice(0, 40) + "..." : prompt.text;
+    log(`[relay] Prompt: "${preview}" → dispatching to ${activeBackend}...`);
+    const result = await dispatchToCLI(activeBackend, prompt.text);
+    const ok = await postReply(config, prompt.id, result.text);
+    const dur = (result.durationMs / 1000).toFixed(1);
+    if (ok) {
+        log(`[relay] Reply posted (${dur}s, ${result.success ? "ok" : "error"}).`);
+    }
+    else {
+        log(`[relay] Failed to post reply for prompt ${prompt.id}.`);
+    }
+}
+async function processQueue(config) {
+    while (promptQueue.length > 0) {
+        isProcessing = true;
+        const next = promptQueue.shift();
+        await processPrompt(config, next);
+    }
+    isProcessing = false;
+}
+function onPromptReceived(config, prompt) {
+    promptQueue.push(prompt);
+    if (!isProcessing) {
+        processQueue(config);
+    }
+}
+// ── Internal API ───────────────────────────────────────────
+function handleInternalAPI(req, res) {
+    const url = req.url ?? "";
+    if (url === "/internal/backend" && req.method === "POST") {
+        let body = "";
+        const MAX_BODY = 10 * 1024; // 10KB
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+            if (body.length > MAX_BODY) {
+                res.writeHead(413, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Payload too large" }));
+                req.destroy();
+                return;
+            }
+        });
+        req.on("end", () => {
+            try {
+                const { backend } = JSON.parse(body);
+                const allowed = ["claudecode", "codex", "gemini"];
+                if (!allowed.includes(backend)) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: `Invalid backend. Allowed: ${allowed.join(", ")}` }));
+                    return;
+                }
+                activeBackend = backend;
+                saveBackendConfig({ activeBackend });
+                log(`[config] Backend switched to ${activeBackend}.`);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ ok: true, backend: activeBackend }));
+            }
+            catch {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Invalid JSON" }));
+            }
+        });
+        return true;
+    }
+    if (url === "/internal/status" && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            backend: activeBackend,
+            processing: isProcessing,
+            queueLength: promptQueue.length,
+            pid: process.pid,
+        }));
+        return true;
+    }
+    return false;
+}
+// ── PID Management ─────────────────────────────────────────
+function getPidPath() {
+    return path.join(resolveZhiHandDir(), PID_FILE);
+}
+function writePid() {
+    ensureZhiHandDir();
+    fs.writeFileSync(getPidPath(), String(process.pid), { mode: 0o600 });
+}
+function removePid() {
+    try {
+        fs.unlinkSync(getPidPath());
+    }
+    catch { /* ignore */ }
+}
+function readPid() {
+    try {
+        const pid = parseInt(fs.readFileSync(getPidPath(), "utf8").trim(), 10);
+        if (isNaN(pid))
+            return null;
+        // Check if process is still alive
+        try {
+            process.kill(pid, 0);
+            return pid;
+        }
+        catch {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+export function isAlreadyRunning() {
+    return readPid();
+}
+// ── Main Daemon Entry ──────────────────────────────────────
+export async function startDaemon(options) {
+    const port = options?.port ?? (parseInt(process.env.ZHIHAND_PORT ?? "", 10) || DEFAULT_PORT);
+    // Check if already running
+    const existingPid = readPid();
+    if (existingPid) {
+        log(`Daemon already running (PID ${existingPid}). Use 'zhihand stop' first.`);
+        process.exit(1);
+    }
+    // Load config
+    let config;
+    try {
+        config = resolveConfig(options?.deviceName);
+    }
+    catch (err) {
+        log(`Error: ${err.message}`);
+        log("Run 'zhihand setup' to pair a device first.");
+        process.exit(1);
+    }
+    // Load backend
+    const backendConfig = loadBackendConfig();
+    activeBackend = backendConfig.activeBackend ?? null;
+    // Create MCP server
+    const mcpServer = createMcpServer(options?.deviceName);
+    // Track active transports for cleanup
+    const activeTransports = new Map();
+    // Create HTTP server
+    const httpServer = createHTTPServer(async (req, res) => {
+        // Internal API
+        if (req.url?.startsWith("/internal/")) {
+            if (handleInternalAPI(req, res))
+                return;
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        // MCP endpoint
+        if (req.url === "/mcp" || req.url?.startsWith("/mcp")) {
+            try {
+                // Check for existing session
+                const sessionId = req.headers["mcp-session-id"];
+                if (sessionId && activeTransports.has(sessionId)) {
+                    // Route to existing transport
+                    const transport = activeTransports.get(sessionId);
+                    await transport.handleRequest(req, res);
+                }
+                else if (req.method === "POST" || !sessionId) {
+                    // New session: create transport, connect to MCP server
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: (sid) => {
+                            activeTransports.set(sid, transport);
+                            log(`[mcp] Session started: ${sid.slice(0, 8)}...`);
+                        },
+                        onsessionclosed: (sid) => {
+                            activeTransports.delete(sid);
+                            log(`[mcp] Session closed: ${sid.slice(0, 8)}...`);
+                        },
+                    });
+                    await mcpServer.connect(transport);
+                    await transport.handleRequest(req, res);
+                }
+                else {
+                    // Unknown session ID
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Invalid or expired session" }));
+                }
+            }
+            catch (err) {
+                if (!res.headersSent) {
+                    res.writeHead(500);
+                    res.end(`MCP error: ${err.message}`);
+                }
+            }
+            return;
+        }
+        // Health check
+        if (req.url === "/health") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "ok", pid: process.pid }));
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    // Start HTTP server on 127.0.0.1 ONLY (security: no 0.0.0.0)
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                log(`Error: Port ${port} is already in use. Set ZHIHAND_PORT to use a different port.`);
+                process.exit(1);
+            }
+            reject(err);
+        });
+        httpServer.listen(port, "127.0.0.1", () => resolve());
+    });
+    writePid();
+    // Start heartbeat
+    startHeartbeatLoop(config, log);
+    // Start prompt listener
+    const promptListener = new PromptListener(config, (prompt) => onPromptReceived(config, prompt), log);
+    promptListener.start();
+    log(`ZhiHand daemon started.`);
+    log(`  PID: ${process.pid}`);
+    log(`  MCP: http://127.0.0.1:${port}/mcp`);
+    log(`  Backend: ${activeBackend ?? "(none)"}`);
+    log(`  Device: ${config.credentialId}`);
+    log(`Listening for prompts...`);
+    // Graceful shutdown
+    const shutdown = async () => {
+        log("\nShutting down...");
+        promptListener.stop();
+        stopHeartbeatLoop();
+        await killActiveChild();
+        await sendBrainOffline(config);
+        // Close all active MCP transports
+        for (const transport of activeTransports.values()) {
+            try {
+                await transport.close();
+            }
+            catch { /* ignore */ }
+        }
+        httpServer.close();
+        removePid();
+        log("Daemon stopped.");
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+export function stopDaemon() {
+    const pid = readPid();
+    if (!pid) {
+        return false;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+        return true;
+    }
+    catch {
+        // Process already dead, clean up PID file
+        removePid();
+        return false;
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { ZhiHandConfig } from "../core/config.ts";
+export interface MobilePrompt {
+    id: string;
+    credential_id: string;
+    edge_id: string;
+    text: string;
+    status: string;
+    client_message_id?: string;
+    created_at: string;
+    attachments?: unknown[];
+}
+export type PromptHandler = (prompt: MobilePrompt) => void;
+export declare class PromptListener {
+    private config;
+    private handler;
+    private log;
+    private processedIds;
+    private sseAbort;
+    private pollTimer;
+    private sseConnected;
+    private stopped;
+    constructor(config: ZhiHandConfig, handler: PromptHandler, log: (msg: string) => void);
+    start(): void;
+    stop(): void;
+    private dispatchPrompt;
+    private connectSSE;
+    private resetWatchdog;
+    private handleSSEEvent;
+    private startPolling;
+    private stopPolling;
+    private poll;
+}

package/dist/daemon/prompt-listener.js

@@ -0,0 +1,152 @@
+const SSE_WATCHDOG_TIMEOUT = 45_000; // 45s no data → reconnect
+const SSE_RECONNECT_DELAY = 3_000;
+const POLL_INTERVAL = 2_000;
+export class PromptListener {
+    config;
+    handler;
+    log;
+    processedIds = new Set();
+    sseAbort = null;
+    pollTimer = null;
+    sseConnected = false;
+    stopped = false;
+    constructor(config, handler, log) {
+        this.config = config;
+        this.handler = handler;
+        this.log = log;
+    }
+    start() {
+        this.stopped = false;
+        this.connectSSE();
+    }
+    stop() {
+        this.stopped = true;
+        this.sseAbort?.abort();
+        this.sseAbort = null;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    dispatchPrompt(prompt) {
+        if (this.processedIds.has(prompt.id))
+            return;
+        this.processedIds.add(prompt.id);
+        // Prevent unbounded growth
+        if (this.processedIds.size > 500) {
+            const arr = [...this.processedIds];
+            this.processedIds = new Set(arr.slice(-250));
+        }
+        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`;
+                const response = await fetch(url, {
+                    headers: {
+                        "Accept": "text/event-stream",
+                        "x-zhihand-controller-token": this.config.controllerToken,
+                    },
+                    signal: this.sseAbort.signal,
+                });
+                if (!response.ok) {
+                    throw new Error(`SSE connect failed: ${response.status}`);
+                }
+                this.sseConnected = 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();
+                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 = "";
+                        }
+                    }
+                }
+                clearTimeout(watchdog);
+            }
+            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));
+            }
+        }
+    }
+    resetWatchdog() {
+        return setTimeout(() => {
+            this.log("[sse] Watchdog timeout (45s no data). Reconnecting...");
+            this.sseAbort?.abort();
+        }, SSE_WATCHDOG_TIMEOUT);
+    }
+    handleSSEEvent(event) {
+        if (event.kind === "prompt.queued" && event.prompt) {
+            this.dispatchPrompt(event.prompt);
+        }
+        else if (event.kind === "prompt.snapshot" && event.prompts) {
+            for (const p of event.prompts) {
+                if (p.status === "pending" || p.status === "processing") {
+                    this.dispatchPrompt(p);
+                }
+            }
+        }
+    }
+    startPolling() {
+        if (this.pollTimer)
+            return;
+        this.pollTimer = setInterval(() => this.poll(), POLL_INTERVAL);
+    }
+    stopPolling() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    async poll() {
+        try {
+            const url = `${this.config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/prompts?limit=5`;
+            const response = await fetch(url, {
+                headers: { "x-zhihand-controller-token": this.config.controllerToken },
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!response.ok)
+                return;
+            const data = (await response.json());
+            for (const prompt of data.items ?? []) {
+                this.dispatchPrompt(prompt);
+            }
+        }
+        catch {
+            // Polling failure is non-fatal
+        }
+    }
+}

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

package/package.json

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