@zhihand/mcp 0.33.1 → 0.34.0

package/bin/zhihand

@@ -21,6 +21,8 @@ import {
   DEFAULT_MODELS,
   resolveConfig,
   resolveDefaultEndpoint,
+  loadPluginIdentity,
+  clearPluginIdentity,
 } from "../dist/core/config.js";
 import {
   executePairingNewUser,
@@ -207,6 +209,24 @@ switch (command) {
     break;
   }
 
+  case "identity": {
+    const subCmd = positionals[1];
+    if (subCmd === "reset") {
+      clearPluginIdentity();
+      console.log("Plugin identity cleared. Next 'zhihand pair' will register a new identity.");
+    } else {
+      const id = loadPluginIdentity();
+      if (id) {
+        console.log(`Edge ID:          ${id.edge_id}`);
+        console.log(`Stable Identity:  ${id.stable_identity}`);
+        console.log(`Plugin Secret:    ${id.plugin_secret.slice(0, 6)}...(redacted)`);
+      } else {
+        console.log("No plugin identity found. Run 'zhihand pair' to create one.");
+      }
+    }
+    break;
+  }
+
   case "mcp":
   case "serve": {
     await startStdioServer();

package/dist/core/config.d.ts

@@ -34,9 +34,20 @@ export interface BackendConfig {
     model?: string | null;
 }
 export declare const DEFAULT_MODELS: Record<Exclude<BackendName, "openclaw">, string>;
+export interface PluginIdentity {
+    stable_identity: string;
+    edge_id: string;
+    plugin_secret: string;
+}
 export declare function resolveZhiHandDir(): string;
 export declare function ensureZhiHandDir(): void;
 export declare function getConfigPath(): string;
+/** Read persisted Plugin identity. Returns null if missing or malformed. */
+export declare function loadPluginIdentity(): PluginIdentity | null;
+/** Atomically persist Plugin identity (write-to-tmp + rename, mode 0o600). */
+export declare function savePluginIdentity(identity: PluginIdentity): void;
+/** Delete identity.json (used by `zhihand identity reset`). */
+export declare function clearPluginIdentity(): void;
 export declare function loadConfig(): ZhihandConfigV3;
 /**
  * Atomically write config: write to .tmp, then rename. Prevents corruption

package/dist/core/config.js

@@ -11,6 +11,7 @@ const ZHIHAND_DIR = path.join(os.homedir(), ".zhihand");
 const CONFIG_PATH = path.join(ZHIHAND_DIR, "config.json");
 const STATE_PATH = path.join(ZHIHAND_DIR, "state.json");
 const BACKEND_PATH = path.join(ZHIHAND_DIR, "backend.json");
+const IDENTITY_PATH = path.join(ZHIHAND_DIR, "identity.json");
 export function resolveZhiHandDir() {
     return ZHIHAND_DIR;
 }
@@ -20,6 +21,36 @@ export function ensureZhiHandDir() {
 export function getConfigPath() {
     return CONFIG_PATH;
 }
+// ── Plugin identity I/O ──────────────────────────────────
+/** Read persisted Plugin identity. Returns null if missing or malformed. */
+export function loadPluginIdentity() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(IDENTITY_PATH, "utf-8"));
+        if (raw.stable_identity && raw.edge_id && raw.plugin_secret) {
+            return raw;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically persist Plugin identity (write-to-tmp + rename, mode 0o600). */
+export function savePluginIdentity(identity) {
+    ensureZhiHandDir();
+    const tmp = IDENTITY_PATH + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(identity, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, IDENTITY_PATH);
+}
+/** Delete identity.json (used by `zhihand identity reset`). */
+export function clearPluginIdentity() {
+    try {
+        fs.unlinkSync(IDENTITY_PATH);
+    }
+    catch {
+        // already gone
+    }
+}
 // ── v3 config I/O ──────────────────────────────────────────
 let legacyWarningPrinted = false;
 function emptyConfig() {

package/dist/core/pair.d.ts

@@ -1,4 +1,4 @@
-import type { DeviceRecord, UserRecord } from "./config.ts";
+import type { DeviceRecord, UserRecord, PluginIdentity } from "./config.ts";
 export interface PairingSession {
     session_id: string;
     pair_url: string;
@@ -30,7 +30,14 @@ export declare function registerPlugin(endpoint: string, options: {
     adapterKind?: string;
 }): Promise<{
     edge_id: string;
+    plugin_secret: string;
 }>;
+/**
+ * Ensure a persistent Plugin identity exists. Reuses existing identity
+ * if present; otherwise registers a new plugin and persists the result.
+ * All pair operations share the same identity → same EdgeID.
+ */
+export declare function ensurePluginIdentity(endpoint: string): Promise<PluginIdentity>;
 /**
  * Poll pairing session until claimed or expired.
  */

package/dist/core/pair.js

@@ -1,5 +1,6 @@
 import QRCode from "qrcode";
-import { addUser, addDeviceToUser, ensureZhiHandDir, saveState, resolveDefaultEndpoint, getUserRecord, cleanupLegacyConfig, } from "./config.js";
+import os from "node:os";
+import { addUser, addDeviceToUser, ensureZhiHandDir, saveState, resolveDefaultEndpoint, getUserRecord, cleanupLegacyConfig, loadPluginIdentity, savePluginIdentity, } from "./config.js";
 import { fetchDeviceProfileOnce, extractStatic } from "./device.js";
 import { fetchUserCredentials } from "./ws.js";
 // ── Server API helpers ─────────────────────────────────────
@@ -58,7 +59,24 @@ export async function registerPlugin(endpoint, options) {
         throw new Error(`Register plugin failed: ${response.status} ${await response.text()}`);
     }
     const payload = (await response.json());
-    return { edge_id: payload.plugin.edge_id };
+    return { edge_id: payload.plugin.edge_id, plugin_secret: payload.plugin.plugin_secret };
+}
+/**
+ * Ensure a persistent Plugin identity exists. Reuses existing identity
+ * if present; otherwise registers a new plugin and persists the result.
+ * All pair operations share the same identity → same EdgeID.
+ */
+export async function ensurePluginIdentity(endpoint) {
+    const existing = loadPluginIdentity();
+    const stableId = existing?.stable_identity ?? `mcp-${os.hostname()}-${Date.now().toString(36)}`;
+    const plugin = await registerPlugin(endpoint, { stableIdentity: stableId });
+    const identity = {
+        stable_identity: stableId,
+        edge_id: plugin.edge_id,
+        plugin_secret: plugin.plugin_secret,
+    };
+    savePluginIdentity(identity);
+    return identity;
 }
 /**
  * Poll pairing session until claimed or expired.
@@ -97,10 +115,9 @@ export async function executePairingNewUser(preferredLabel) {
     cleanupLegacyConfig();
     const userId = userResp.user_id;
     const controllerToken = userResp.controller_token;
-    // 2. Register plugin (get edge_id)
-    const stableIdentity = `mcp-${Date.now().toString(36)}`;
-    const plugin = await registerPlugin(endpoint, { stableIdentity });
-    const edgeId = plugin.edge_id;
+    // 2. Ensure persistent plugin identity (same EdgeID across all pairs)
+    const identity = await ensurePluginIdentity(endpoint);
+    const edgeId = identity.edge_id;
     // 3. Create pairing session
     const session = await createPairingSession(endpoint, userId, controllerToken, edgeId, 300);
     saveState({
@@ -186,10 +203,9 @@ export async function executePairingAddDevice(userId, preferredLabel) {
     if (!user)
         throw new Error(`User '${userId}' not found in config`);
     const controllerToken = user.controller_token;
-    // Register plugin (get edge_id)
-    const stableIdentity = `mcp-${Date.now().toString(36)}`;
-    const plugin = await registerPlugin(endpoint, { stableIdentity });
-    const edgeId = plugin.edge_id;
+    // Ensure persistent plugin identity (same EdgeID across all pairs)
+    const identity = await ensurePluginIdentity(endpoint);
+    const edgeId = identity.edge_id;
     // Get existing credential IDs before pairing
     const existingCreds = await fetchUserCredentials(endpoint, userId, controllerToken);
     const existingIds = new Set(existingCreds.map((c) => c.credential_id));

package/dist/daemon/heartbeat.d.ts

@@ -1,12 +1,17 @@
-import type { ZhiHandRuntimeConfig } from "../core/config.ts";
 /** Brain metadata included in every heartbeat, so the app always knows the current backend/model. */
 export interface BrainMeta {
     backend?: string | null;
     model?: string | null;
 }
+/** Plugin-level heartbeat target. Uses edgeId + pluginSecret instead of per-credential auth. */
+export interface HeartbeatTarget {
+    controlPlaneEndpoint: string;
+    edgeId: string;
+    pluginSecret: string;
+}
 /** Update the backend/model metadata that will be sent with the next heartbeat. */
 export declare function setBrainMeta(meta: BrainMeta): void;
-export declare function sendBrainOnline(config: ZhiHandRuntimeConfig): Promise<boolean>;
-export declare function sendBrainOffline(config: ZhiHandRuntimeConfig): Promise<boolean>;
-export declare function startHeartbeatLoop(config: ZhiHandRuntimeConfig, log: (msg: string) => void): void;
+export declare function sendBrainOnline(target: HeartbeatTarget): Promise<boolean>;
+export declare function sendBrainOffline(target: HeartbeatTarget): Promise<boolean>;
+export declare function startHeartbeatLoop(target: HeartbeatTarget, log: (msg: string) => void): void;
 export declare function stopHeartbeatLoop(): void;

package/dist/daemon/heartbeat.js

@@ -9,23 +9,23 @@ let currentMeta = {};
 export function setBrainMeta(meta) {
     currentMeta = meta;
 }
-function buildUrl(config) {
-    return `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/brain-status`;
+function buildUrl(target) {
+    return `${target.controlPlaneEndpoint}/v1/plugins/${encodeURIComponent(target.edgeId)}/brain-status`;
 }
-async function sendHeartbeat(config, online) {
+async function sendHeartbeat(target, online) {
     try {
         const body = { plugin_online: online };
         if (currentMeta.backend)
             body.backend = currentMeta.backend;
         if (currentMeta.model)
             body.model = currentMeta.model;
-        const url = buildUrl(config);
+        const url = buildUrl(target);
         dbg(`[heartbeat] POST ${url} body=${JSON.stringify(body)}`);
         const response = await fetch(url, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "Authorization": `Bearer ${config.controllerToken}`,
+                "Authorization": `Bearer ${target.pluginSecret}`,
             },
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(10_000),
@@ -38,20 +38,20 @@ async function sendHeartbeat(config, online) {
         return false;
     }
 }
-export async function sendBrainOnline(config) {
-    return sendHeartbeat(config, true);
+export async function sendBrainOnline(target) {
+    return sendHeartbeat(target, true);
 }
-export async function sendBrainOffline(config) {
-    return sendHeartbeat(config, false);
+export async function sendBrainOffline(target) {
+    return sendHeartbeat(target, false);
 }
-export function startHeartbeatLoop(config, log) {
+export function startHeartbeatLoop(target, log) {
     let retrying = false;
     stopped = false;
     async function beat() {
         // Skip main-timer beats while retry loop is active (avoids overlap & flapping)
         if (retrying || stopped)
             return;
-        const ok = await sendBrainOnline(config);
+        const ok = await sendBrainOnline(target);
         if (stopped)
             return; // check after await — stopHeartbeatLoop() may have been called
         if (ok) {
@@ -70,7 +70,7 @@ export function startHeartbeatLoop(config, log) {
         retryTimer = setTimeout(async () => {
             if (!retrying || stopped)
                 return;
-            const recovered = await sendBrainOnline(config);
+            const recovered = await sendBrainOnline(target);
             if (stopped)
                 return; // check after await
             if (recovered) {

package/dist/daemon/index.js

@@ -5,7 +5,7 @@ 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, DEFAULT_MODELS, } from "../core/config.js";
+import { resolveConfig, loadBackendConfig, saveBackendConfig, resolveZhiHandDir, resolveDefaultEndpoint, ensureZhiHandDir, loadPluginIdentity, DEFAULT_MODELS, } from "../core/config.js";
 import { PACKAGE_VERSION } from "../index.js";
 import { startHeartbeatLoop, stopHeartbeatLoop, sendBrainOffline, setBrainMeta } from "./heartbeat.js";
 import { PromptListener } from "./prompt-listener.js";
@@ -359,15 +359,35 @@ export async function startDaemon(options) {
         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);
+    // Load Plugin identity for edge-level heartbeat + prompt WS
+    const identity = loadPluginIdentity();
+    if (!identity) {
+        log("[identity] No plugin identity found. Run 'zhihand pair' first.");
+        process.exit(1);
+    }
+    log(`[identity] Loaded: edge_id=${identity.edge_id}, stable_identity=${identity.stable_identity}`);
+    const heartbeatTarget = {
+        controlPlaneEndpoint: resolveDefaultEndpoint(),
+        edgeId: identity.edge_id,
+        pluginSecret: identity.plugin_secret,
+    };
+    // Start heartbeat (edge-level, pluginSecret auth)
+    startHeartbeatLoop(heartbeatTarget, log);
+    // Start prompt listener (edge-level single WS)
+    const promptListener = new PromptListener({
+        controlPlaneEndpoint: resolveDefaultEndpoint(),
+        edgeId: identity.edge_id,
+        pluginSecret: identity.plugin_secret,
+    }, (prompt) => onPromptReceived(config, prompt), log, (reason) => {
+        log(`[fatal] ${reason}`);
+        process.exit(1);
+    });
     promptListener.start();
     log(`ZhiHand daemon started.`);
     log(`  PID: ${process.pid}`);
     log(`  MCP: http://127.0.0.1:${port}/mcp`);
     log(`  Backend: ${activeBackend ?? "(none)"}`);
+    log(`  Edge: ${identity.edge_id}`);
     log(`  Device: ${config.credentialId}`);
     log(`Listening for prompts...`);
     // Graceful shutdown
@@ -377,7 +397,7 @@ export async function startDaemon(options) {
         stopHeartbeatLoop();
         clearInterval(sessionCleanupTimer);
         await killActiveChild();
-        await sendBrainOffline(config);
+        await sendBrainOffline(heartbeatTarget);
         // Close all MCP sessions
         for (const session of mcpSessions.values()) {
             try {

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

@@ -1,5 +1,3 @@
-import type { ZhiHandRuntimeConfig } from "../core/config.ts";
-type ZhiHandConfig = ZhiHandRuntimeConfig;
 export interface MobilePrompt {
     id: string;
     credential_id: string;
@@ -11,14 +9,21 @@ export interface MobilePrompt {
     attachments?: unknown[];
 }
 export type PromptHandler = (prompt: MobilePrompt) => void;
+/** Edge-level prompt listener config. Uses pluginSecret instead of per-user controllerToken. */
+export interface PromptListenerConfig {
+    controlPlaneEndpoint: string;
+    edgeId: string;
+    pluginSecret: string;
+}
 export declare class PromptListener {
     private config;
     private handler;
     private log;
+    private onFatalError?;
     private processedIds;
     private rws;
     private stopped;
-    constructor(config: ZhiHandConfig, handler: PromptHandler, log: (msg: string) => void);
+    constructor(config: PromptListenerConfig, handler: PromptHandler, log: (msg: string) => void, onFatalError?: (reason: string) => void);
     start(): void;
     stop(): void;
     private dispatchPrompt;
@@ -26,4 +31,3 @@ export declare class PromptListener {
     private handleWSMessage;
     private handleEvent;
 }
-export {};

package/dist/daemon/prompt-listener.js

@@ -4,13 +4,15 @@ export class PromptListener {
     config;
     handler;
     log;
+    onFatalError;
     processedIds = new Set();
     rws = null;
     stopped = false;
-    constructor(config, handler, log) {
+    constructor(config, handler, log, onFatalError) {
         this.config = config;
         this.handler = handler;
         this.log = log;
+        this.onFatalError = onFatalError;
     }
     start() {
         this.stopped = false;
@@ -27,7 +29,7 @@ export class PromptListener {
             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 ? "..." : ""}"`);
+        dbg(`[prompt] Dispatching prompt: id=${prompt.id}, cred=${prompt.credential_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];
@@ -38,21 +40,18 @@ export class PromptListener {
     connectWS() {
         if (this.stopped)
             return;
-        const wsUrl = `${this.config.controlPlaneEndpoint.replace(/^http/, "ws")}/v1/credentials/${encodeURIComponent(this.config.credentialId)}/ws?topic=prompts`;
+        // Edge-level WS: single connection for all credentials under this edge
+        const wsUrl = `${this.config.controlPlaneEndpoint.replace(/^http/, "ws")}/v1/plugins/${encodeURIComponent(this.config.edgeId)}/ws?topic=prompts`;
         dbg(`[ws] Connecting to ${wsUrl}`);
         this.rws = new ReconnectingWebSocket({
             url: wsUrl,
-            headers: {
-                "Authorization": `Bearer ${this.config.controllerToken}`,
-            },
+            headers: {},
             onOpen: () => {
-                // Send auth message as first frame (required by server).
+                // Send auth frame with pluginSecret (server verifies before streaming)
                 this.rws.send(JSON.stringify({
                     type: "auth",
-                    controller_token: this.config.controllerToken,
-                    topics: ["prompts"],
+                    plugin_secret: this.config.pluginSecret,
                 }));
-                // onConnected deferred until auth_ok is received (see handleWSMessage)
             },
             onClose: (_code, _reason) => {
                 dbg("[ws] Disconnected. ReconnectingWebSocket will retry.");
@@ -68,42 +67,38 @@ export class PromptListener {
     }
     handleWSMessage(data) {
         const msg = data;
-        // Auth responses
         if (msg.type === "auth_ok") {
-            this.log("[ws] Connected to prompt stream.");
+            this.log("[ws] Connected to Edge prompt stream.");
             return;
         }
         if (msg.type === "auth_error") {
-            this.log(`[ws] Auth failed: ${msg.error}`);
+            const reason = `Plugin auth failed: ${msg.error}. Run 'zhihand pair' to re-register.`;
+            this.log(`[ws] ${reason}`);
             this.rws?.stop();
             this.rws = null;
+            this.onFatalError?.(reason);
             return;
         }
-        // Application-level ping (if server sends these alongside protocol pings)
         if (msg.type === "ping") {
             this.rws?.send(JSON.stringify({ type: "pong" }));
             return;
         }
-        // Event dispatch
         if (msg.type === "event" || msg.kind) {
             this.handleEvent(msg);
         }
     }
     handleEvent(event) {
         const kind = event.kind;
-        dbg(`[ws] Event: kind=${kind}, prompt=${event.prompt?.id ?? "-"}, prompts=${event.prompts?.length ?? 0}`);
+        dbg(`[ws] Event: kind=${kind}, prompt=${event.prompt?.id ?? "-"}`);
         if (kind === "prompt.queued" && event.prompt) {
             this.dispatchPrompt(event.prompt);
         }
-        else if (kind === "prompt.snapshot" && event.prompts) {
-            for (const p of event.prompts) {
-                if (p.status === "pending" || p.status === "processing") {
-                    this.dispatchPrompt(p);
-                }
+        else if (kind === "prompt.snapshot" && event.prompt) {
+            // Edge WS sends individual snapshot events (one per pending prompt)
+            const p = event.prompt;
+            if (p.status === "pending" || p.status === "processing") {
+                this.dispatchPrompt(p);
             }
         }
-        else if (kind === "device_profile.updated") {
-            this.log("[device] device_profile.updated event received on prompts stream (ignored; registry handles it)");
-        }
     }
 }

package/dist/index.d.ts

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

package/dist/index.js

@@ -8,7 +8,7 @@ import { handlePair } from "./tools/pair.js";
 import { resolveTargetDevice } from "./tools/resolve.js";
 import { buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, extractDynamic, } from "./core/device.js";
 import { registry } from "./core/registry.js";
-export const PACKAGE_VERSION = "0.33.1";
+export const PACKAGE_VERSION = "0.34.0";
 function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }

package/package.json

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