@zhihand/mcp 0.28.0 → 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" },
   },
 });
@@ -54,9 +55,10 @@ Usage:
   zhihand detect             Detect available CLI tools
 
   zhihand list               List all available tests with IDs
-  zhihand test               Run all safe device tests
+  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:
@@ -65,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);
@@ -294,13 +297,31 @@ switch (command) {
     const { resolveConfig: resolveTestConfig } = await import("../dist/core/config.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" },
@@ -391,6 +412,7 @@ switch (command) {
 
     // 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) {
@@ -427,6 +449,24 @@ switch (command) {
     } 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;
@@ -489,6 +529,22 @@ switch (command) {
         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++;
@@ -516,14 +572,19 @@ switch (command) {
           process.stdout.write(`   ${String(t.id).padStart(2)}. ${t.label}... `);
           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(", ")})`);
+            // 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}`);
@@ -539,13 +600,24 @@ switch (command) {
             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);
-              console.log(`✅ ${(buf.length / 1024).toFixed(0)}KB (${Date.now() - t0}ms)`);
-              passed++;
-            } else {
+            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)`);

package/dist/core/device.d.ts

@@ -37,7 +37,23 @@ 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;

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}`);
 }
@@ -205,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,
@@ -225,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/index.d.ts

@@ -1,4 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare const PACKAGE_VERSION = "0.28.0";
+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

@@ -7,7 +7,7 @@ import { executeSystem } from "./tools/system.js";
 import { handleScreenshot } from "./tools/screenshot.js";
 import { handlePair } from "./tools/pair.js";
 import { getStaticContext, getDynamicContext, fetchDeviceProfile, buildControlToolDescription, buildSystemToolDescription, buildScreenshotToolDescription, formatDeviceStatus, } from "./core/device.js";
-export const PACKAGE_VERSION = "0.28.0";
+export const PACKAGE_VERSION = "0.29.0";
 export function createServer(deviceName) {
     const server = new McpServer({
         name: "zhihand",
@@ -30,7 +30,7 @@ export function createServer(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/package.json

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