@zhihand/mcp 0.26.4 → 0.29.0

package/bin/zhihand

@@ -27,6 +27,7 @@ const { positionals, values } = parseArgs({
     help: { type: "boolean", short: "h", default: false },
     detach: { type: "boolean", short: "d", default: false },
     debug: { type: "boolean", default: false },
+    force: { type: "boolean", default: false },
     port: { type: "string" },
   },
 });
@@ -53,7 +54,11 @@ Usage:
   zhihand pair               Pair with a phone device
   zhihand detect             Detect available CLI tools
 
-  zhihand test               Test device connectivity (sends click + type commands)
+  zhihand list               List all available tests with IDs
+  zhihand test               Run all safe device tests (skips capability-gated)
+  zhihand test <ids>         Run specific test(s), e.g. 'zhihand test 4' or '4,9,20'
+  zhihand test all           Run ALL tests (including unsafe, e.g. power button)
+  zhihand test --force       Bypass capability gates (run anyway even if NOT ready)
   zhihand serve              Start MCP Server (stdio mode, backward compat)
 
 Options:
@@ -62,6 +67,7 @@ Options:
   --port <port>      Override daemon port (default: 18686)
   -d, --detach       Run daemon in background
   --debug            Enable verbose debug logging
+  --force            (test only) Run tests even if capability not ready
   -h, --help         Show this help
 `);
   process.exit(0);
@@ -286,13 +292,115 @@ switch (command) {
     break;
   }
 
+  case "list":
   case "test": {
     const { resolveConfig: resolveTestConfig } = await import("../dist/core/config.js");
-    const { createControlCommand, enqueueCommand } = await import("../dist/core/command.js");
+    const { createControlCommand, createSystemCommand, enqueueCommand } = await import("../dist/core/command.js");
     const { waitForCommandAck } = await import("../dist/core/sse.js");
-    const { fetchScreenshotBinary } = await import("../dist/core/screenshot.js");
-    const { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded, formatDeviceStatus } = await import("../dist/core/device.js");
+    const { fetchScreenshot, getSnapshotStaleThresholdMs } = await import("../dist/core/screenshot.js");
+    const { fetchDeviceProfile, getStaticContext, isDeviceProfileLoaded, formatDeviceStatus, getCapabilities } = await import("../dist/core/device.js");
+
+    // ── Test Registry ────────────────────────────────────────
+    // Kind: "profile" | "status" | "screenshot" | "hid" | "system"
+    //   - Each kind maps to a required capability (see KIND_CAPABILITY).
+    // Platform: undefined | "android" | "ios" (skipped on non-matching)
+    // Unsafe: won't run in full-suite unless explicitly requested
+
+    // Required capability per test kind. Tests whose required capability
+    // is not ready are SKIPPED (not failed), unless --force is passed.
+    //
+    // NOTE: `system` commands (volume, brightness, notification, media,
+    // etc.) are executed by the phone app via native OS APIs
+    // (AccessibilityService on Android, Shortcuts/system hooks on iOS)
+    // and do NOT depend on the BLE HID channel. Only the `hid` kind
+    // (click, swipe, type, keycombo — which inject into the paired
+    // target via the ZhiHand peripheral) needs the HID capability.
+    const KIND_CAPABILITY = {
+      profile: "none",
+      status: "none",
+      screenshot: "screen",
+      hid: "hid",
+      system: "none",
+    };
+    const REGISTRY = [
+      // Phase A — Device Info API
+      { id: 1, phase: "Device Info", label: "Fetch device profile", kind: "profile" },
+      { id: 2, phase: "Device Info", label: "Device status fields", kind: "status" },
+      // Phase B — Screenshot
+      { id: 3, phase: "Screenshot", label: "Screenshot", kind: "screenshot" },
+      // Phase C — Tap / Touch
+      { id: 4, phase: "Tap/Touch", label: "Click center", kind: "hid", params: { action: "click", xRatio: 0.5, yRatio: 0.5 } },
+      { id: 5, phase: "Tap/Touch", label: "Double click", kind: "hid", params: { action: "doubleclick", xRatio: 0.5, yRatio: 0.5 } },
+      { id: 6, phase: "Tap/Touch", label: "Long click (800ms)", kind: "hid", params: { action: "longclick", xRatio: 0.5, yRatio: 0.5, durationMs: 800 } },
+      { id: 7, phase: "Tap/Touch", label: "Right click", kind: "hid", params: { action: "rightclick", xRatio: 0.5, yRatio: 0.5 } },
+      { id: 8, phase: "Tap/Touch", label: "Middle click", kind: "hid", params: { action: "middleclick", xRatio: 0.5, yRatio: 0.5 } },
+      // Phase D — Swipe / Scroll
+      { id: 9, phase: "Swipe/Scroll", label: "Swipe up", kind: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 } },
+      { id: 10, phase: "Swipe/Scroll", label: "Swipe down", kind: "hid", params: { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 } },
+      { id: 11, phase: "Swipe/Scroll", label: "Swipe left", kind: "hid", params: { action: "swipe", startXRatio: 0.7, startYRatio: 0.5, endXRatio: 0.3, endYRatio: 0.5, durationMs: 300 } },
+      { id: 12, phase: "Swipe/Scroll", label: "Swipe right", kind: "hid", params: { action: "swipe", startXRatio: 0.3, startYRatio: 0.5, endXRatio: 0.7, endYRatio: 0.5, durationMs: 300 } },
+      { id: 13, phase: "Swipe/Scroll", label: "Scroll down", kind: "hid", params: { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "down", amount: 3 } },
+      { id: 14, phase: "Swipe/Scroll", label: "Scroll up", kind: "hid", params: { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "up", amount: 3 } },
+      // Phase E — Text + Keys
+      { id: 15, phase: "Text+Keys", label: "Type text", kind: "hid", params: { action: "type", text: "zhihand" } },
+      { id: 16, phase: "Text+Keys", label: "Enter key", kind: "hid", params: { action: "enter" } },
+      { id: 17, phase: "Text+Keys", label: "Key combo (select all)", kind: "hid", platformAware: "select_all" },
+      // Phase F — App Navigation
+      { id: 18, phase: "Navigation", label: "Press Home", kind: "hid", params: { action: "home" } },
+      { id: 19, phase: "Navigation", label: "Press Back", kind: "hid", params: { action: "back" } },
+      { id: 20, phase: "Navigation", label: "Open WeChat", kind: "hid", platformAware: "open_wechat" },
+      // Phase G — Clipboard
+      { id: 21, phase: "Clipboard", label: "Clipboard set", kind: "hid", platformAware: "clipboard_set" },
+      // Phase H — System Navigation
+      { id: 22, phase: "System Nav", label: "Notification shade", kind: "system", params: { action: "notification" } },
+      { id: 23, phase: "System Nav", label: "Recent apps", kind: "system", params: { action: "recent" } },
+      { id: 24, phase: "System Nav", label: "Search (query='zhihand')", kind: "system", params: { action: "search", text: "zhihand" } },
+      { id: 25, phase: "System Nav", label: "Switch input", kind: "system", params: { action: "switch_input" } },
+      { id: 26, phase: "System Nav", label: "Siri", kind: "system", params: { action: "siri" }, platform: "ios" },
+      { id: 27, phase: "System Nav", label: "Control Center", kind: "system", params: { action: "control_center" }, platform: "ios" },
+      { id: 28, phase: "System Nav", label: "Open browser", kind: "system", params: { action: "open_browser" }, platform: "android" },
+      { id: 29, phase: "System Nav", label: "Shortcut help", kind: "system", params: { action: "shortcut_help" }, platform: "android" },
+      // Phase I — Media
+      { id: 30, phase: "Media", label: "Volume up", kind: "system", params: { action: "volume_up" } },
+      { id: 31, phase: "Media", label: "Volume down", kind: "system", params: { action: "volume_down" } },
+      { id: 32, phase: "Media", label: "Mute toggle", kind: "system", params: { action: "mute" } },
+      { id: 33, phase: "Media", label: "Play/Pause", kind: "system", params: { action: "play_pause" } },
+      { id: 34, phase: "Media", label: "Next track", kind: "system", params: { action: "next_track" } },
+      { id: 35, phase: "Media", label: "Prev track", kind: "system", params: { action: "prev_track" } },
+      { id: 36, phase: "Media", label: "Fast forward", kind: "system", params: { action: "fast_forward" } },
+      { id: 37, phase: "Media", label: "Rewind", kind: "system", params: { action: "rewind" } },
+      { id: 38, phase: "Media", label: "Stop", kind: "system", params: { action: "stop" } },
+      // Phase J — Hardware
+      { id: 39, phase: "Hardware", label: "Brightness up", kind: "system", params: { action: "brightness_up" } },
+      { id: 40, phase: "Hardware", label: "Brightness down", kind: "system", params: { action: "brightness_down" } },
+      { id: 41, phase: "Hardware", label: "Power button (⚠️ may lock screen)", kind: "system", params: { action: "power" }, unsafe: true },
+    ];
+
+    // ── "list" sub-command ───────────────────────────────────
+    if (command === "list") {
+      console.log("📋 ZhiHand Test Registry\n");
+      let currentPhase = "";
+      for (const t of REGISTRY) {
+        if (t.phase !== currentPhase) {
+          console.log(`\n   ── ${t.phase} ──`);
+          currentPhase = t.phase;
+        }
+        const tags = [];
+        if (t.platform) tags.push(`${t.platform}-only`);
+        if (t.unsafe) tags.push("unsafe");
+        const tagStr = tags.length ? ` [${tags.join(", ")}]` : "";
+        console.log(`   ${String(t.id).padStart(2)}. ${t.label}${tagStr}`);
+      }
+      console.log(`\n   Total: ${REGISTRY.length} tests`);
+      console.log("\nUsage:");
+      console.log("   zhihand test            # run all safe tests");
+      console.log("   zhihand test 4          # run test #4 only");
+      console.log("   zhihand test 4,9,20     # run tests #4, #9, #20");
+      console.log("   zhihand test all        # run ALL tests (including unsafe)");
+      process.exit(0);
+    }
 
+    // ── "test" sub-command ───────────────────────────────────
     let testConfig;
     try {
       testConfig = resolveTestConfig(values.device ?? process.env.ZHIHAND_DEVICE);
@@ -302,152 +410,270 @@ switch (command) {
       process.exit(1);
     }
 
+    // Parse which tests to run from positional args
+    const filterArg = positionals[1];  // e.g. "4" or "4,9,20" or "all"
+    const forceRun = values.force === true;
+    let selectedIds = null;   // null = default (all safe)
+    let includeUnsafe = false;
+    if (filterArg) {
+      if (filterArg === "all") {
+        includeUnsafe = true;
+      } else {
+        selectedIds = new Set(
+          filterArg.split(",").map((s) => {
+            const trimmed = s.trim();
+            const n = Number(trimmed);
+            // Strict: reject ranges like "4-10" (Number returns NaN), floats, empty
+            return Number.isInteger(n) && n > 0 ? n : NaN;
+          }).filter((n) => !isNaN(n))
+        );
+        if (selectedIds.size === 0) {
+          console.error(`Invalid test IDs: ${filterArg}`);
+          console.error("Run 'zhihand list' to see available tests.");
+          process.exit(1);
+        }
+        // Explicit selection implies user knows what they're doing
+        includeUnsafe = true;
+      }
+    }
+
     console.log("🧪 ZhiHand Device Test");
     console.log(`   Device: ${testConfig.credentialId}`);
     console.log(`   Endpoint: ${testConfig.controlPlaneEndpoint}\n`);
 
+    // Pre-fetch device profile so platform-aware tests work.
+    // Note: platform is read dynamically via getDevicePlatform() so Test 1
+    // (Fetch device profile) can populate it before later tests consume it.
+    try {
+      await fetchDeviceProfile(testConfig);
+    } catch { /* non-fatal — Test 1 will retry and platform will update */ }
+    const getDevicePlatform = () => isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
+
+    // ── Capability readiness pre-flight ──
+    console.log("   ── Capability readiness ──");
+    const preCaps = isDeviceProfileLoaded() ? getCapabilities() : null;
+    if (!preCaps) {
+      console.log("   ⚠️  Device profile not loaded — all capability gates will allow tests through.");
+    } else {
+      const fmt = (name, cap) => `   ${cap.ready ? "✅" : "⚠️"} ${name.padEnd(14)} ${cap.ready ? "ready" : "NOT ready"}  — ${cap.reason}`;
+      console.log(fmt("screen_sharing", preCaps.screen_sharing));
+      console.log(fmt("hid",            preCaps.hid));
+      console.log(fmt("live_session",   preCaps.live_session));
+      const ageStr = preCaps.profile.age_ms >= 0 ? `${(preCaps.profile.age_ms / 1000).toFixed(1)}s` : "unknown";
+      console.log(`   ${preCaps.profile.stale ? "⚠️" : "✅"} profile        age=${ageStr}${preCaps.profile.stale ? " (STALE)" : ""}`);
+      if (forceRun) {
+        console.log("   --force passed: capability gates disabled.");
+      }
+    }
+    console.log("");
+
     let passed = 0;
     let failed = 0;
+    let skipped = 0;
     let totalSteps = 0;
 
-    // ── Helper: run a single HID step ──
-    async function runHidStep(label, params) {
+    // ── Resolve platform-aware params (evaluated at test time) ──
+    function resolvePlatformAwareParams(variant) {
+      const platform = getDevicePlatform();
+      if (variant === "open_wechat") {
+        return platform === "ios"
+          ? { action: "open_app", bundleId: "com.tencent.xin" }
+          : { action: "open_app", appPackage: "com.tencent.mm" };
+      }
+      if (variant === "clipboard_set") {
+        return { action: "clipboard", text: `zhihand_test_${Date.now()}` };
+      }
+      if (variant === "select_all") {
+        const keys = platform === "ios" ? "cmd+a" : "ctrl+a";
+        return { action: "keycombo", keys };
+      }
+      return null;
+    }
+
+    // ── Test runners (shared ACK logic) ──
+    async function runCommandTest(t, command) {
       totalSteps++;
-      process.stdout.write(`   ${label}... `);
+      process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
       const t0 = Date.now();
       try {
-        const cmd = createControlCommand(params);
-        const queued = await enqueueCommand(testConfig, cmd);
+        const queued = await enqueueCommand(testConfig, command);
         const ack = await waitForCommandAck(testConfig, { commandId: queued.id, timeoutMs: 10_000 });
         const ms = Date.now() - t0;
         if (ack.acked) {
           const ackStatus = ack.command?.ack_status ?? "ok";
-          const detail = ackStatus !== "ok" ? ` [${ackStatus}]` : "";
           const resultInfo = ack.command?.ack_result ? ` ${JSON.stringify(ack.command.ack_result)}` : "";
-          console.log(`✅ (${ms}ms)${detail}${resultInfo}`);
-          passed++;
-          return ack;
+          if (ackStatus === "ok") {
+            console.log(`✅ (${ms}ms)${resultInfo}`);
+            passed++;
+          } else {
+            console.log(`❌ [${ackStatus}] (${ms}ms)${resultInfo}`);
+            failed++;
+          }
         } else {
           console.log(`⏱️  Timeout (${ms}ms)`);
           failed++;
-          return null;
         }
       } catch (err) {
         console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
         failed++;
-        return null;
       }
     }
 
-    // ── Helper: run a screenshot step ──
-    async function runScreenshotStep(label) {
-      totalSteps++;
-      process.stdout.write(`   ${label}... `);
-      const t0 = Date.now();
-      try {
-        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++;
+    async function runSingleTest(t) {
+      // Platform skip (evaluated at test time — Test 1 may have just populated the profile)
+      const currentPlatform = getDevicePlatform();
+      if (t.platform && t.platform !== currentPlatform) {
+        totalSteps++;
+        skipped++;
+        console.log(`   ${String(t.id).padStart(2)}. ${t.label}... ⏭️  Skipped (${t.platform}-only, device is ${currentPlatform})`);
+        return;
+      }
+
+      // Capability gate (unless --force) — evaluated per-test so later
+      // tests see fresh readiness flags pushed after Test 1's profile fetch.
+      if (!forceRun && isDeviceProfileLoaded()) {
+        const requiredCap = KIND_CAPABILITY[t.kind] ?? "none";
+        if (requiredCap !== "none") {
+          const caps = getCapabilities();
+          const gate = requiredCap === "screen" ? caps.screen_sharing : caps.hid;
+          if (!gate.ready) {
+            totalSteps++;
+            skipped++;
+            console.log(`   ${String(t.id).padStart(2)}. ${t.label}... ⏭️  Skipped (${requiredCap} not ready: ${gate.reason})`);
+            return;
+          }
+        }
+      }
+
+      switch (t.kind) {
+        case "profile": {
+          totalSteps++;
+          process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
+          const t0 = Date.now();
+          try {
+            await fetchDeviceProfile(testConfig);
+            const ms = Date.now() - t0;
+            if (isDeviceProfileLoaded()) {
+              const s = getStaticContext();
+              console.log(`✅ ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
+              passed++;
+            } else {
+              console.log(`⚠️  Loaded but empty (${ms}ms)`);
+              failed++;
+            }
+          } catch (err) {
+            console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+            failed++;
+          }
+          break;
+        }
+        case "status": {
+          totalSteps++;
+          process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
+          try {
+            const status = formatDeviceStatus();
+            // Count curated top-level fields (excluding the nested 'raw'
+            // and 'capabilities' containers) plus every allowlisted raw
+            // attribute — this is what the LLM actually sees via
+            // zhihand_status.
+            const topLevel = Object.keys(status).filter((k) => k !== "raw" && k !== "capabilities");
+            const rawKeys = Object.keys(status.raw ?? {});
+            const caps = status.capabilities ?? {};
+            const capReadySummary = ["screen_sharing", "hid", "live_session"]
+              .map((k) => `${k}=${caps[k]?.ready ? "ready" : "not-ready"}`)
+              .join(", ");
+            console.log(`✅ ${topLevel.length} curated + ${rawKeys.length} raw attributes; ${capReadySummary}`);
+            console.log(`      curated: ${topLevel.join(", ")}`);
+            console.log(`      raw:     ${rawKeys.join(", ")}`);
+            passed++;
+          } catch (err) {
+            console.log(`❌ ${err.message}`);
+            failed++;
+          }
+          break;
+        }
+        case "screenshot": {
+          totalSteps++;
+          process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
+          const t0 = Date.now();
+          try {
+            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) {
+              console.log(`⏱️  Timeout (${Date.now() - t0}ms)`);
+              failed++;
+              break;
+            }
+            const shot = await fetchScreenshot(testConfig);
+            const kb = (shot.buffer.length / 1024).toFixed(0);
+            const ms = Date.now() - t0;
+            // The screenshot endpoint returns the last cached frame even
+            // when the phone isn't actively sharing — the age header is
+            // the only way to tell. Treat stale as failure.
+            if (shot.stale) {
+              const threshold = getSnapshotStaleThresholdMs();
+              console.log(`❌ Stale (${kb}KB, age=${(shot.ageMs / 1000).toFixed(1)}s > ${(threshold / 1000).toFixed(1)}s) ${shot.width}x${shot.height} seq=${shot.sequence} — phone may not be screen-sharing (${ms}ms)`);
+              failed++;
+            } else {
+              console.log(`✅ ${kb}KB, ${shot.width}x${shot.height}, age=${shot.ageMs >= 0 ? `${shot.ageMs}ms` : "?"}, seq=${shot.sequence} (${ms}ms)`);
+              passed++;
+            }
+          } catch (err) {
+            console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
+            failed++;
+          }
+          break;
+        }
+        case "hid": {
+          const params = t.platformAware ? resolvePlatformAwareParams(t.platformAware) : t.params;
+          await runCommandTest(t, createControlCommand(params));
+          break;
+        }
+        case "system": {
+          await runCommandTest(t, createSystemCommand(t.params));
+          break;
         }
-      } catch (err) {
-        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
-        failed++;
       }
     }
 
     const pause = () => new Promise((r) => setTimeout(r, 1500));
 
-    // ── Phase 1: Device Profile ──────────────────────────────
-    console.log("   ── Phase 1: Device Info ──");
-    totalSteps++;
-    process.stdout.write("   1. Fetch device profile... ");
-    {
-      const t0 = Date.now();
-      try {
-        await fetchDeviceProfile(testConfig);
-        const ms = Date.now() - t0;
-        if (isDeviceProfileLoaded()) {
-          const s = getStaticContext();
-          console.log(`✅ ${s.platform} ${s.model}, ${s.osVersion}, ${s.screenWidthPx}x${s.screenHeightPx} (${ms}ms)`);
-          passed++;
-        } else {
-          console.log(`⚠️  Loaded but empty (${ms}ms)`);
-          failed++;
-        }
-      } catch (err) {
-        console.log(`❌ ${err.message} (${Date.now() - t0}ms)`);
-        failed++;
-      }
+    // Select tests to run
+    const toRun = REGISTRY.filter((t) => {
+      if (selectedIds) return selectedIds.has(t.id);
+      if (t.unsafe && !includeUnsafe) return false;
+      return true;
+    });
+
+    if (toRun.length === 0) {
+      console.error("No matching tests.");
+      console.error("Run 'zhihand list' to see available tests.");
+      process.exit(1);
     }
 
-    totalSteps++;
-    process.stdout.write("   2. Device status fields... ");
-    {
-      try {
-        const status = formatDeviceStatus();
-        const ignoredDefaults = new Set(["unknown", "0x0", "-1% (unknown)", "0"]);
-        const fields = Object.keys(status).filter((k) => {
-          const v = status[k];
-          if (v === null || v === undefined) return false;
-          if (ignoredDefaults.has(String(v))) return false;
-          return true;
-        });
-        console.log(`✅ ${fields.length} fields (${fields.join(", ")})`);
-        passed++;
-      } catch (err) {
-        console.log(`❌ ${err.message}`);
-        failed++;
+    // Warn about missing IDs
+    if (selectedIds) {
+      const foundIds = new Set(toRun.map((t) => t.id));
+      const missing = [...selectedIds].filter((id) => !foundIds.has(id));
+      if (missing.length) {
+        console.warn(`⚠️  Unknown test IDs: ${missing.join(", ")}`);
       }
     }
 
-    await pause();
-
-    // ── Phase 2: Screenshot + Basic HID ──────────────────────
-    console.log("   ── Phase 2: Screenshot + HID ──");
-    await runScreenshotStep("3. Screenshot");
-    await pause();
-    await runHidStep("4. Click center", { action: "click", xRatio: 0.5, yRatio: 0.5 });
-    await pause();
-    await runHidStep("5. Swipe up", { action: "swipe", startXRatio: 0.5, startYRatio: 0.7, endXRatio: 0.5, endYRatio: 0.3, durationMs: 300 });
-    await pause();
-    await runHidStep("6. Swipe down", { action: "swipe", startXRatio: 0.5, startYRatio: 0.3, endXRatio: 0.5, endYRatio: 0.7, durationMs: 300 });
-    await pause();
-    await runHidStep("7. Scroll down", { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "down", amount: 3 });
-    await pause();
-    await runHidStep("8. Scroll up", { action: "scroll", xRatio: 0.5, yRatio: 0.5, direction: "up", amount: 3 });
-    await pause();
-
-    // ── Phase 3: App + Navigation ────────────────────────────
-    console.log("   ── Phase 3: App + Navigation ──");
-    await runHidStep("9. Press Home", { action: "home" });
-    await pause();
-    {
-      const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "android";
-      const openParams = platform === "ios"
-        ? { action: "open_app", bundleId: "com.tencent.xin" }
-        : { action: "open_app", appPackage: "com.tencent.mm" };
-      await runHidStep(`10. Open WeChat (${platform})`, openParams);
+    let currentPhase = "";
+    for (let i = 0; i < toRun.length; i++) {
+      const t = toRun[i];
+      if (t.phase !== currentPhase) {
+        console.log(`   ── ${t.phase} ──`);
+        currentPhase = t.phase;
+      }
+      await runSingleTest(t);
+      if (i < toRun.length - 1) await pause();
     }
-    await pause();
-    await runHidStep("11. Press Back", { action: "back" });
-    await pause();
-
-    // ── Phase 4: Clipboard Set ─────────────────────────────
-    // Note: App only supports clipboard set, not get
-    console.log("   ── Phase 4: Clipboard ──");
-    const clipboardTestText = `zhihand_test_${Date.now()}`;
-    await runHidStep("12. Clipboard set", { action: "clipboard", text: clipboardTestText });
 
     // ── Summary ──────────────────────────────────────────────
-    console.log(`\n   Result: ${passed}/${totalSteps} passed`);
+    console.log(`\n   Result: ${passed}/${totalSteps} passed, ${failed} failed, ${skipped} skipped`);
     if (failed === 0) {
       console.log("   ✅ All tests passed! Device is fully responsive.");
     } else {

package/dist/core/command.d.ts

@@ -37,6 +37,11 @@ export interface WaitForCommandAckResult {
     command?: QueuedCommandRecord;
 }
 export declare function createControlCommand(params: ControlParams): QueuedControlCommand;
+export interface SystemParams {
+    action: string;
+    text?: string;
+}
+export declare function createSystemCommand(params: SystemParams): QueuedControlCommand;
 export declare function enqueueCommand(config: ZhiHandConfig, command: QueuedControlCommand): Promise<QueuedCommandRecord>;
 export declare function getCommand(config: ZhiHandConfig, commandId: string): Promise<QueuedCommandRecord>;
 export declare function formatAckSummary(action: string, result: WaitForCommandAckResult): string;

package/dist/core/command.js

@@ -93,6 +93,65 @@ export function createControlCommand(params) {
             throw new Error(`Unsupported action: ${params.action}`);
     }
 }
+const IOS_ONLY_ACTIONS = new Set(["siri", "control_center"]);
+const ANDROID_ONLY_ACTIONS = new Set(["open_browser", "shortcut_help"]);
+export function createSystemCommand(params) {
+    const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
+    // Platform validation — block mismatched platform-specific actions
+    if (platform === "android" && IOS_ONLY_ACTIONS.has(params.action)) {
+        throw new Error(`Action '${params.action}' is not supported on Android.`);
+    }
+    if (platform === "ios" && ANDROID_ONLY_ACTIONS.has(params.action)) {
+        throw new Error(`Action '${params.action}' is not supported on iOS.`);
+    }
+    switch (params.action) {
+        // System navigation
+        case "notification":
+            return { type: "receive_notification", payload: {} };
+        case "recent":
+            return { type: "receive_recent", payload: {} };
+        case "search":
+            return { type: "receive_search", payload: { query: params.text ?? "" } };
+        case "switch_input":
+            return { type: "receive_switch_input", payload: {} };
+        case "siri":
+            return { type: "receive_siri", payload: {} };
+        case "control_center":
+            return { type: "receive_control_center", payload: {} };
+        case "open_browser":
+            return { type: "receive_open_browser", payload: {} };
+        case "shortcut_help":
+            return { type: "receive_shortcut_help", payload: {} };
+        // Media controls
+        case "volume_up":
+            return { type: "receive_volume_up", payload: {} };
+        case "volume_down":
+            return { type: "receive_volume_down", payload: {} };
+        case "mute":
+            return { type: "receive_mute", payload: {} };
+        case "play_pause":
+            return { type: "receive_play_pause", payload: {} };
+        case "stop":
+            return { type: "receive_stop", payload: {} };
+        case "next_track":
+            return { type: "receive_next_track", payload: {} };
+        case "prev_track":
+            return { type: "receive_prev_track", payload: {} };
+        case "fast_forward":
+            return { type: "receive_fast_forward", payload: {} };
+        case "rewind":
+            return { type: "receive_rewind", payload: {} };
+        // Hardware
+        case "brightness_up":
+            return { type: "receive_brightness_up", payload: {} };
+        case "brightness_down":
+            return { type: "receive_brightness_down", payload: {} };
+        case "power":
+            return { type: "receive_power", payload: {} };
+        default:
+            throw new Error(`Unsupported system action: ${params.action}`);
+    }
+}
 export async function enqueueCommand(config, command) {
     const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands`;
     const body = { command: { ...command, message_id: command.messageId ?? nextMessageId() } };

package/dist/core/device.d.ts

@@ -37,11 +37,28 @@ export interface DynamicContext {
 }
 export declare function getStaticContext(): StaticContext;
 export declare function getDynamicContext(): DynamicContext;
+export declare function getRawAttributes(): Record<string, unknown>;
+export declare function getProfileAgeMs(): number;
 export declare function isDeviceProfileLoaded(): boolean;
+export interface Capability {
+    ready: boolean;
+    reason: string;
+}
+export interface Capabilities {
+    screen_sharing: Capability;
+    hid: Capability;
+    live_session: Capability;
+    profile: {
+        age_ms: number;
+        stale: boolean;
+    };
+}
+export declare function getCapabilities(): Capabilities;
 export declare function extractStatic(profile: Record<string, unknown>): StaticContext;
 export declare function extractDynamic(profile: Record<string, unknown>): DynamicContext;
 export declare function updateDeviceProfile(raw: Record<string, unknown>): void;
 export declare function fetchDeviceProfile(config: ZhiHandConfig): Promise<void>;
 export declare function buildControlToolDescription(): string;
+export declare function buildSystemToolDescription(): string;
 export declare function buildScreenshotToolDescription(): string;
 export declare function formatDeviceStatus(): Record<string, unknown>;

package/dist/core/device.js

@@ -36,6 +36,11 @@ const DEFAULT_DYNAMIC = {
 // ── Module state ──────────────────────────────────────────
 let staticCtx = { ...DEFAULT_STATIC };
 let dynamicCtx = { ...DEFAULT_DYNAMIC };
+let rawAttributes = {};
+// Local monotonic timestamp (Date.now()) captured when the profile was last
+// updated. Used for age calculations — avoids distributed clock skew vs.
+// reading server-side `updated_at`.
+let profileReceivedAtMs = 0;
 let loaded = false;
 export function getStaticContext() {
     return staticCtx;
@@ -43,9 +48,66 @@ export function getStaticContext() {
 export function getDynamicContext() {
     return dynamicCtx;
 }
+export function getRawAttributes() {
+    return rawAttributes;
+}
+export function getProfileAgeMs() {
+    if (!loaded || profileReceivedAtMs === 0)
+        return Number.POSITIVE_INFINITY;
+    return Date.now() - profileReceivedAtMs;
+}
 export function isDeviceProfileLoaded() {
     return loaded;
 }
+// Max age (ms) before the device profile is considered stale. Bounds to
+// 60s: profile updates are pushed ~every 10–30s by the phone app.
+const PROFILE_STALE_THRESHOLD_MS = 60_000;
+export function getCapabilities() {
+    const a = rawAttributes;
+    const b = (k) => typeof a[k] === "boolean" ? a[k] : undefined;
+    const recordingActive = b("recording_active");
+    const hidConnected = b("hid_connected");
+    const hidBonded = b("hid_bonded");
+    const hidPairing = b("hid_pairing");
+    const hidSessionReady = b("hid_session_ready");
+    const liveSessionActive = b("live_session_active");
+    const pairedHostReady = b("paired_host_ready");
+    const screenSharingReady = recordingActive === true;
+    // HID is "ready" when we have a connected bonded peripheral and aren't
+    // mid-pairing. `hid_session_ready` is advisory — some devices keep it
+    // false while HID still works, so we don't require it.
+    const hidReady = hidConnected === true && hidBonded === true && hidPairing !== true;
+    // Strict AND: a "ready" live session requires both an active socket
+    // and a paired host. Using OR here would mask a dead session when a
+    // host is still paired from a previous run.
+    const liveReady = liveSessionActive === true && pairedHostReady === true;
+    const ageMs = getProfileAgeMs();
+    const stale = ageMs > PROFILE_STALE_THRESHOLD_MS;
+    return {
+        screen_sharing: {
+            ready: screenSharingReady,
+            reason: screenSharingReady
+                ? "recording_active=true"
+                : `recording_active=${recordingActive ?? "unknown"} — phone is not screen-sharing; start sharing in the app to enable screenshots`,
+        },
+        hid: {
+            ready: hidReady,
+            reason: hidReady
+                ? `connected=true, bonded=true, session_ready=${hidSessionReady ?? "unknown"}`
+                : `connected=${hidConnected ?? "unknown"}, bonded=${hidBonded ?? "unknown"}, pairing=${hidPairing ?? "unknown"}, session_ready=${hidSessionReady ?? "unknown"} — connect the ZhiHand (BLE HID) to enable input`,
+        },
+        live_session: {
+            ready: liveReady,
+            reason: liveReady
+                ? `live_session_active=${liveSessionActive ?? "-"}, paired_host_ready=${pairedHostReady ?? "-"}`
+                : `live_session_active=${liveSessionActive ?? "unknown"}, paired_host_ready=${pairedHostReady ?? "unknown"}`,
+        },
+        profile: {
+            age_ms: Number.isFinite(ageMs) ? ageMs : -1,
+            stale,
+        },
+    };
+}
 // ── Extract helpers ───────────────────────────────────────
 function str(v, fallback) {
     return typeof v === "string" && v ? v : fallback;
@@ -121,6 +183,8 @@ export function updateDeviceProfile(raw) {
     }
     staticCtx = extractStatic(profile);
     dynamicCtx = extractDynamic(profile);
+    rawAttributes = profile;
+    profileReceivedAtMs = Date.now();
     loaded = true;
     dbg(`[device] Profile updated: platform=${staticCtx.platform}, model=${staticCtx.model}, screen=${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}`);
 }
@@ -176,6 +240,28 @@ export function buildControlToolDescription() {
     }
     return desc;
 }
+export function buildSystemToolDescription() {
+    if (!loaded || staticCtx.platform === "unknown") {
+        return "System navigation and media controls. Actions: notification, recent, search, switch_input, siri (iOS), control_center (iOS), open_browser (Android), shortcut_help (Android), volume_up/down, mute, play_pause, stop, next/prev_track, fast_forward, rewind, brightness_up/down, power.";
+    }
+    const platform = staticCtx.platform;
+    const parts = [
+        `System navigation and media controls for ${platform} device (${staticCtx.model}).`,
+    ];
+    // Navigation
+    parts.push("Navigation: notification, recent, search (optional text query), switch_input.");
+    if (platform === "ios") {
+        parts.push("iOS: siri, control_center.");
+    }
+    else if (platform === "android") {
+        parts.push("Android: open_browser, shortcut_help.");
+    }
+    // Media
+    parts.push("Media: volume_up, volume_down, mute, play_pause, stop, next_track, prev_track, fast_forward, rewind.");
+    // Hardware
+    parts.push("Hardware: brightness_up, brightness_down, power.");
+    return parts.join(" ");
+}
 export function buildScreenshotToolDescription() {
     if (!loaded || staticCtx.platform === "unknown") {
         return "Take a screenshot of the phone screen.";
@@ -183,8 +269,45 @@ export function buildScreenshotToolDescription() {
     return `Take a screenshot of the ${staticCtx.platform} device (${staticCtx.model}, ${staticCtx.screenWidthPx}x${staticCtx.screenHeightPx}).`;
 }
 // ── Format status for zhihand_status tool ─────────────────
+// Allowlist of raw attribute keys exposed via zhihand_status.
+// Keeps context window manageable and blocks sensitive/internal fields
+// (e.g. credential_status, full_access_*). Wire-format names are kept
+// verbatim so the LLM can cite them consistently with the server logs.
+const RAW_ATTRIBUTE_ALLOWLIST = [
+    // Device identity
+    "brand", "manufacturer", "model", "rom_family", "rom_version",
+    "system_release", "api_level", "app_version", "app_build",
+    // Display / form factor
+    "display_width_px", "display_height_px", "density", "density_dpi",
+    "screen_width_dp", "screen_height_dp", "smallest_width_dp",
+    "form_factor", "orientation", "touchscreen", "navigation_mode",
+    // Locale / UI
+    "locale", "language", "timezone", "rtl", "dark_mode", "font_scale",
+    // Power / thermal / storage
+    "battery_level", "battery_state", "available_storage_mb",
+    "thermal_state", "low_ram_device",
+    // Network
+    "network_type",
+    // Capability / readiness signals (most important for LLM diagnosis)
+    "hid_connected", "hid_bonded", "hid_pairing", "hid_session_ready",
+    "live_session_active", "paired_host_ready", "recording_active",
+    "recording_archive_enabled", "app_in_foreground", "task_running",
+    "emergency_stop_armed", "firmware_update_in_progress",
+    "hardware_keyboard_present", "hard_keyboard_hidden",
+    "supports_keyboard_prompt_navigation",
+];
+function pickAllowlistedRawAttributes() {
+    const out = {};
+    for (const k of RAW_ATTRIBUTE_ALLOWLIST) {
+        if (k in rawAttributes && rawAttributes[k] !== undefined) {
+            out[k] = rawAttributes[k];
+        }
+    }
+    return out;
+}
 export function formatDeviceStatus() {
     return {
+        // Curated summary (human-readable, stable schema)
         platform: staticCtx.platform,
         model: staticCtx.model,
         os_version: staticCtx.osVersion,
@@ -203,5 +326,9 @@ export function formatDeviceStatus() {
         storage_available_mb: dynamicCtx.availableStorageMb,
         thermal: dynamicCtx.thermalState ?? "normal",
         font_scale: dynamicCtx.fontScale,
+        // Readiness — always present so LLM knows what works right now
+        capabilities: getCapabilities(),
+        // Full (allowlisted) attributes from the device — wire-format names
+        raw: pickAllowlistedRawAttributes(),
     };
 }

package/dist/core/screenshot.d.ts

@@ -1,2 +1,13 @@
 import type { ZhiHandConfig } from "./config.ts";
+export declare function getSnapshotStaleThresholdMs(): number;
+export interface ScreenshotResult {
+    buffer: Buffer;
+    ageMs: number;
+    width: number;
+    height: number;
+    capturedAt: string | null;
+    sequence: number;
+    stale: boolean;
+}
+export declare function fetchScreenshot(config: ZhiHandConfig): Promise<ScreenshotResult>;
 export declare function fetchScreenshotBinary(config: ZhiHandConfig): Promise<Buffer>;

package/dist/core/screenshot.js

@@ -1,5 +1,24 @@
 import { dbg } from "../daemon/logger.js";
-export async function fetchScreenshotBinary(config) {
+// Snapshot is considered stale if the server-reported age exceeds this
+// threshold. Configurable via env ZHIHAND_SNAPSHOT_MAX_AGE_MS.
+// Default 5s: typical HID command + capture + upload is well under 2s;
+// anything beyond 5s suggests the phone is no longer actively sharing.
+export function getSnapshotStaleThresholdMs() {
+    const raw = process.env.ZHIHAND_SNAPSHOT_MAX_AGE_MS;
+    if (raw) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 5000;
+}
+function parseIntHeader(h) {
+    if (!h)
+        return -1;
+    const n = Number(h);
+    return Number.isFinite(n) ? n : -1;
+}
+export async function fetchScreenshot(config) {
     const controller = new AbortController();
     const timeoutMs = config.timeoutMs ?? 10_000;
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -20,10 +39,31 @@ export async function fetchScreenshotBinary(config) {
             throw new Error(`Screenshot fetch failed: ${response.status}`);
         }
         const buf = Buffer.from(await response.arrayBuffer());
-        dbg(`[screenshot] OK: ${(buf.length / 1024).toFixed(0)}KB in ${Date.now() - t0}ms`);
-        return buf;
+        const ageMs = parseIntHeader(response.headers.get("x-snapshot-age"));
+        const width = parseIntHeader(response.headers.get("x-snapshot-width"));
+        const height = parseIntHeader(response.headers.get("x-snapshot-height"));
+        const sequence = parseIntHeader(response.headers.get("x-snapshot-sequence"));
+        const capturedAt = response.headers.get("x-snapshot-captured-at");
+        const threshold = getSnapshotStaleThresholdMs();
+        const stale = ageMs >= 0 && ageMs > threshold;
+        dbg(`[screenshot] OK: ${(buf.length / 1024).toFixed(0)}KB in ${Date.now() - t0}ms, age=${ageMs}ms, stale=${stale}`);
+        return {
+            buffer: buf,
+            ageMs,
+            width: Math.max(width, 0),
+            height: Math.max(height, 0),
+            capturedAt,
+            sequence,
+            stale,
+        };
     }
     finally {
         clearTimeout(timeout);
     }
 }
+// Backward-compatible wrapper — returns only the Buffer.
+// New code should prefer fetchScreenshot() for staleness info.
+export async function fetchScreenshotBinary(config) {
+    const res = await fetchScreenshot(config);
+    return res.buffer;
+}

package/dist/daemon/dispatcher.js

@@ -372,6 +372,17 @@ function buildSystemContext() {
     else {
         openAppDoc = "- open_app: Open an app. Params: appPackage (Android, e.g. 'com.tencent.mm'), bundleId (iOS), urlScheme (e.g. 'weixin://')";
     }
+    // Platform-specific system actions
+    let platformSystemDoc;
+    if (static_?.platform === "ios") {
+        platformSystemDoc = "- siri: Activate Siri\n- control_center: Open Control Center";
+    }
+    else if (static_?.platform === "android") {
+        platformSystemDoc = "- open_browser: Launch default browser\n- shortcut_help: Show keyboard shortcuts overlay";
+    }
+    else {
+        platformSystemDoc = "- siri: Activate Siri (iOS only)\n- control_center: Open Control Center (iOS only)\n- open_browser: Launch default browser (Android only)\n- shortcut_help: Show keyboard shortcuts overlay (Android only)";
+    }
     return `You are ZhiHand, an AI assistant connected to the user's mobile phone via MCP tools.
 
 ## Device
@@ -401,13 +412,35 @@ ${openAppDoc}
 - screenshot: Capture screen via control (same as zhihand_screenshot)
 - wait: Wait before next action. Params: durationMs (default 1000)
 
+### zhihand_system
+System navigation and media controls. Requires "action" parameter.
+
+**System navigation:**
+- notification: Open notification shade/center
+- recent: Show app switcher / recent apps
+- search: Open system search. Optional "text" param to type query after opening
+- switch_input: Switch input method (only works in text input fields)
+${platformSystemDoc}
+
+**Media controls:**
+- volume_up / volume_down: Adjust volume
+- mute: Toggle mute
+- play_pause / stop: Playback control
+- next_track / prev_track: Skip track
+- fast_forward / rewind: Seek
+
+**Hardware:**
+- brightness_up / brightness_down: Adjust brightness
+- power: Press power button
+
 ### zhihand_status
 Get device status: platform, battery, network, BLE connection, dark mode, storage, etc.
 
 ## Rules
 - When the user asks to see their screen, ALWAYS call zhihand_screenshot first.
-- When the user asks to open an app (e.g. WeChat, Settings), use open_app action.
-- When the user asks to go back/home, use back/home actions.
+- When the user asks to open an app (e.g. WeChat, Settings), use open_app action with zhihand_control.
+- When the user asks to go back/home, use back/home actions with zhihand_control.
+- For system functions (notifications, volume, brightness, media), use zhihand_system.
 - For all tap/click operations, use xRatio and yRatio (0-1 normalized coordinates based on the screenshot).`;
 }
 /**

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,12 +1,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { resolveConfig } from "./core/config.js";
-import { controlSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
+import { controlSchema, systemSchema, screenshotSchema, pairSchema } from "./tools/schemas.js";
 import { executeControl } from "./tools/control.js";
+import { executeSystem } from "./tools/system.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
-import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
-export const PACKAGE_VERSION = "0.26.4";
+import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
+export const PACKAGE_VERSION = "0.29.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",
@@ -18,13 +19,18 @@ export function createServer(deviceName) {
         const config = resolveConfig(deviceName);
         return await executeControl(config, params);
     });
+    // zhihand_system — system navigation + media controls (separate tool per Gemini design review)
+    server.tool("zhihand_system", buildSystemToolDescription(), systemSchema, async (params) => {
+        const config = resolveConfig(deviceName);
+        return await executeSystem(config, params);
+    });
     // zhihand_screenshot — capture current screen without any action
     server.tool("zhihand_screenshot", buildScreenshotToolDescription(), screenshotSchema, async () => {
         const config = resolveConfig(deviceName);
         return await handleScreenshot(config);
     });
     // zhihand_status — return device context for LLM to query on demand
-    server.tool("zhihand_status", "Get device status: platform, model, OS version, screen size, battery, network, BLE, dark mode, storage, and more.", {}, async () => {
+    server.tool("zhihand_status", "Get device status and capability readiness. Returns curated fields (platform, model, OS, screen, battery, network, BLE, ...), a `capabilities` object with `ready`/`reason` for screen_sharing, hid, live_session, profile.age, AND a `raw` map of allowlisted device attributes (wire-format names). Call this BEFORE issuing commands if you are unsure whether the phone is screen-sharing or the ZhiHand (BLE HID) is connected.", {}, async () => {
         return {
             content: [{
                     type: "text",

package/dist/tools/control.js

@@ -1,20 +1,46 @@
 import { createControlCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
-import { fetchScreenshotBinary } from "../core/screenshot.js";
+import { fetchScreenshot } from "../core/screenshot.js";
 import { waitForCommandAck } from "../core/sse.js";
+import { getCapabilities, isDeviceProfileLoaded } from "../core/device.js";
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
+/**
+ * Build a short human-readable warning for the LLM if the underlying
+ * capability isn't ready, or if the last screenshot is stale. Returns
+ * empty string when everything is nominal.
+ */
+function buildReadinessWarning(requiredCapability, screenshot) {
+    if (!isDeviceProfileLoaded())
+        return "";
+    const caps = getCapabilities();
+    const warnings = [];
+    if (requiredCapability === "hid" && !caps.hid.ready) {
+        warnings.push(`⚠️ HID not ready: ${caps.hid.reason}`);
+    }
+    if (requiredCapability === "screen" && !caps.screen_sharing.ready) {
+        warnings.push(`⚠️ Screen sharing not active: ${caps.screen_sharing.reason}`);
+    }
+    if (screenshot && screenshot.stale) {
+        warnings.push(`⚠️ Stale screenshot: age=${(screenshot.ageMs / 1000).toFixed(1)}s (phone may not be actively sharing the screen).`);
+    }
+    if (caps.profile.stale) {
+        warnings.push(`⚠️ Stale device profile: ${(caps.profile.age_ms / 1000).toFixed(1)}s old — readiness flags may be out of date.`);
+    }
+    return warnings.join("\n");
+}
 export async function executeControl(config, params) {
     // wait: Plugin-local implementation, no server round-trip
     if (params.action === "wait") {
         await sleep(params.durationMs ?? 1000);
-        const screenshot = await fetchScreenshotBinary(config);
-        return {
-            content: [
-                { type: "text", text: `Waited ${params.durationMs ?? 1000}ms` },
-                { type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" },
-            ],
-        };
+        const shot = await fetchScreenshot(config);
+        const warning = buildReadinessWarning("screen", shot);
+        const content = [];
+        if (warning)
+            content.push({ type: "text", text: warning });
+        content.push({ type: "text", text: `Waited ${params.durationMs ?? 1000}ms` });
+        content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
+        return { content };
     }
     // screenshot: send receive_screenshot, App captures immediately (no 2s delay)
     if (params.action === "screenshot") {
@@ -24,29 +50,38 @@ export async function executeControl(config, params) {
     const command = createControlCommand(params);
     const queued = await enqueueCommand(config, command);
     const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 15_000 });
-    const content = [
-        { type: "text", text: formatAckSummary(params.action, ack) },
-    ];
+    const content = [];
+    let shot = null;
     if (ack.acked) {
         try {
-            const screenshot = await fetchScreenshotBinary(config);
-            content.push({ type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" });
+            shot = await fetchScreenshot(config);
         }
         catch {
             // Screenshot is best-effort after ACK
         }
     }
+    const warning = buildReadinessWarning("hid", shot);
+    if (warning)
+        content.push({ type: "text", text: warning });
+    content.push({ type: "text", text: formatAckSummary(params.action, ack) });
+    if (shot) {
+        content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
+    }
     return { content };
 }
 export async function executeScreenshot(config) {
     const command = createControlCommand({ action: "screenshot" });
     const queued = await enqueueCommand(config, command);
     const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 5_000 });
-    const screenshot = await fetchScreenshotBinary(config);
-    return {
-        content: [
-            { type: "text", text: `Screenshot captured (acked: ${ack.acked})` },
-            { type: "image", data: screenshot.toString("base64"), mimeType: "image/jpeg" },
-        ],
-    };
+    const shot = await fetchScreenshot(config);
+    const warning = buildReadinessWarning("screen", shot);
+    const content = [];
+    if (warning)
+        content.push({ type: "text", text: warning });
+    content.push({
+        type: "text",
+        text: `Screenshot captured (acked: ${ack.acked}, age: ${shot.ageMs >= 0 ? `${shot.ageMs}ms` : "unknown"}, size: ${shot.width}x${shot.height}, seq: ${shot.sequence})`,
+    });
+    content.push({ type: "image", data: shot.buffer.toString("base64"), mimeType: "image/jpeg" });
+    return { content };
 }

package/dist/tools/schemas.d.ts

@@ -16,6 +16,10 @@ export declare const controlSchema: {
     bundleId: z.ZodOptional<z.ZodString>;
     urlScheme: z.ZodOptional<z.ZodString>;
 };
+export declare const systemSchema: {
+    action: z.ZodEnum<["notification", "recent", "search", "switch_input", "siri", "control_center", "open_browser", "shortcut_help", "volume_up", "volume_down", "mute", "play_pause", "stop", "next_track", "prev_track", "fast_forward", "rewind", "brightness_up", "brightness_down", "power"]>;
+    text: z.ZodOptional<z.ZodString>;
+};
 export declare const screenshotSchema: {};
 export declare const pairSchema: {
     forceNew: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;

package/dist/tools/schemas.js

@@ -23,6 +23,24 @@ export const controlSchema = {
     bundleId: z.string().optional().describe("iOS bundle ID, e.g. 'com.tencent.xin'"),
     urlScheme: z.string().optional().describe("URL scheme, e.g. 'weixin://'"),
 };
+// zhihand_system — system navigation + media controls (separate from UI control)
+export const systemSchema = {
+    action: z.enum([
+        // System navigation — cross-platform
+        "notification", "recent", "search", "switch_input",
+        // System navigation — iOS only
+        "siri", "control_center",
+        // System navigation — Android only
+        "open_browser", "shortcut_help",
+        // Media controls — cross-platform
+        "volume_up", "volume_down", "mute",
+        "play_pause", "stop", "next_track", "prev_track",
+        "fast_forward", "rewind",
+        // Hardware — cross-platform
+        "brightness_up", "brightness_down", "power",
+    ]).describe("System or media action to perform"),
+    text: z.string().optional().describe("Optional text, e.g. search query for 'search' action"),
+};
 export const screenshotSchema = {};
 export const pairSchema = {
     forceNew: z.boolean().default(false).optional().describe("Force new pairing even if already paired"),

package/dist/tools/system.d.ts

@@ -0,0 +1,17 @@
+/**
+ * zhihand_system tool handler — system navigation + media controls.
+ *
+ * Separated from zhihand_control to keep UI-control schema focused and
+ * reduce LLM parameter hallucination (Gemini design review recommendation).
+ */
+import type { ZhiHandConfig } from "../core/config.ts";
+import type { SystemParams } from "../core/command.ts";
+type TextContent = {
+    type: "text";
+    text: string;
+};
+type ToolResult = {
+    content: TextContent[];
+};
+export declare function executeSystem(config: ZhiHandConfig, params: SystemParams): Promise<ToolResult>;
+export {};

package/dist/tools/system.js

@@ -0,0 +1,11 @@
+import { createSystemCommand, enqueueCommand, formatAckSummary } from "../core/command.js";
+import { waitForCommandAck } from "../core/sse.js";
+export async function executeSystem(config, params) {
+    const command = createSystemCommand(params);
+    const queued = await enqueueCommand(config, command);
+    const ack = await waitForCommandAck(config, { commandId: queued.id, timeoutMs: 15_000 });
+    const summary = formatAckSummary(params.action, ack);
+    return {
+        content: [{ type: "text", text: summary }],
+    };
+}

package/package.json

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