@zhihand/mcp 0.28.0 → 0.30.0

package/dist/core/command.d.ts

@@ -1,4 +1,4 @@
-import type { ZhiHandConfig } from "./config.ts";
+import type { ZhiHandRuntimeConfig } from "./config.ts";
 export type ScrollDirection = "up" | "down" | "left" | "right";
 export interface ControlParams {
     action: string;
@@ -36,12 +36,12 @@ export interface WaitForCommandAckResult {
     acked: boolean;
     command?: QueuedCommandRecord;
 }
-export declare function createControlCommand(params: ControlParams): QueuedControlCommand;
+export declare function createControlCommand(params: ControlParams, platform?: string): 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 createSystemCommand(params: SystemParams, platform?: string): QueuedControlCommand;
+export declare function enqueueCommand(config: ZhiHandRuntimeConfig, command: QueuedControlCommand): Promise<QueuedCommandRecord>;
+export declare function getCommand(config: ZhiHandRuntimeConfig, commandId: string): Promise<QueuedCommandRecord>;
 export declare function formatAckSummary(action: string, result: WaitForCommandAckResult): string;

package/dist/core/command.js

@@ -1,11 +1,10 @@
-import { getStaticContext, isDeviceProfileLoaded } from "./device.js";
 import { dbg } from "../daemon/logger.js";
 let messageCounter = 0;
 function nextMessageId() {
     messageCounter = (messageCounter + 1) % 1000;
     return (Date.now() * 1000) + messageCounter;
 }
-export function createControlCommand(params) {
+export function createControlCommand(params, platform = "unknown") {
     switch (params.action) {
         case "click":
             return { type: "receive_click", payload: { x: params.xRatio, y: params.yRatio } };
@@ -57,7 +56,6 @@ export function createControlCommand(params) {
             };
         case "open_app": {
             const appPayload = {};
-            const platform = isDeviceProfileLoaded() ? getStaticContext().platform : "unknown";
             // Only send platform-appropriate fields — Android strict JSON rejects unknown keys
             if (platform === "android") {
                 // Android: only app_package
@@ -95,8 +93,7 @@ export function createControlCommand(params) {
 }
 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";
+export function createSystemCommand(params, 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.`);

package/dist/core/config.d.ts

@@ -1,15 +1,23 @@
-export interface DeviceCredential {
-    credentialId: string;
-    controllerToken: string;
+export type DevicePlatform = "ios" | "android" | "unknown";
+export interface DeviceRecord {
+    credential_id: string;
+    controller_token: string;
     endpoint: string;
-    deviceName?: string;
-    pairedAt?: string;
+    label: string;
+    platform: DevicePlatform;
+    paired_at: string;
+    last_seen_at: string;
 }
-export interface CredentialStore {
-    default: string;
-    devices: Record<string, DeviceCredential>;
+export interface ZhihandConfig {
+    schema_version: 2;
+    default_credential_id: string | null;
+    devices: Record<string, DeviceRecord>;
 }
-export interface ZhiHandConfig {
+/**
+ * Legacy-shaped config passed to HTTP callers (command/sse/device endpoints).
+ * Corresponds to what the old single-device code called ZhiHandConfig.
+ */
+export interface ZhiHandRuntimeConfig {
     controlPlaneEndpoint: string;
     credentialId: string;
     controllerToken: string;
@@ -21,20 +29,24 @@ export interface BackendConfig {
     activeBackend: BackendName | null;
     model?: string | null;
 }
-/**
- * Default model aliases per backend.
- * These are generic aliases that the respective CLIs resolve to the latest version:
- *   - Gemini CLI: "flash" → latest flash model (e.g. gemini-2.5-flash)
- *   - Claude Code: "sonnet" → latest sonnet (e.g. claude-sonnet-4-20250514)
- *   - Codex CLI: requires full model name, no alias support
- */
 export declare const DEFAULT_MODELS: Record<Exclude<BackendName, "openclaw">, string>;
 export declare function resolveZhiHandDir(): string;
 export declare function ensureZhiHandDir(): void;
-export declare function loadCredentialStore(): CredentialStore | null;
-export declare function loadDefaultCredential(): DeviceCredential | null;
-export declare function saveCredential(name: string, cred: DeviceCredential, setDefault?: boolean): void;
-export declare function resolveConfig(deviceName?: string): ZhiHandConfig;
+export declare function loadConfig(): ZhihandConfig;
+export declare function saveConfig(cfg: ZhihandConfig): void;
+export declare function addDevice(record: DeviceRecord, makeDefault?: boolean): void;
+export declare function removeDevice(credentialId: string): void;
+export declare function renameDevice(credentialId: string, label: string): void;
+export declare function setDefaultDevice(credentialId: string): void;
+export declare function updateLastSeen(credentialId: string, iso: string): void;
+export declare function getDeviceRecord(credentialId: string): DeviceRecord | null;
+export declare function listDeviceRecords(): DeviceRecord[];
+export declare function recordToRuntimeConfig(r: DeviceRecord): ZhiHandRuntimeConfig;
+/**
+ * Resolve a runtime config for HTTP calls. If credentialId provided, look it up;
+ * else use default_credential_id; else throw.
+ */
+export declare function resolveConfig(credentialId?: string): ZhiHandRuntimeConfig;
 export declare function loadState<T = unknown>(): T | null;
 export declare function saveState(state: unknown): void;
 export declare function loadBackendConfig(): BackendConfig;

package/dist/core/config.js

@@ -1,20 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-/**
- * Default model aliases per backend.
- * These are generic aliases that the respective CLIs resolve to the latest version:
- *   - Gemini CLI: "flash" → latest flash model (e.g. gemini-2.5-flash)
- *   - Claude Code: "sonnet" → latest sonnet (e.g. claude-sonnet-4-20250514)
- *   - Codex CLI: requires full model name, no alias support
- */
 export const DEFAULT_MODELS = {
-    gemini: "flash", // Gemini CLI resolves to latest flash
-    claudecode: "sonnet", // Claude Code resolves to latest sonnet
-    codex: "gpt-5.4-mini", // Codex default: latest GPT mini model
+    gemini: "flash",
+    claudecode: "sonnet",
+    codex: "gpt-5.4-mini",
 };
+// ── Paths ──────────────────────────────────────────────────
 const ZHIHAND_DIR = path.join(os.homedir(), ".zhihand");
-const CREDENTIALS_PATH = path.join(ZHIHAND_DIR, "credentials.json");
+const CONFIG_PATH = path.join(ZHIHAND_DIR, "config.json");
+const LEGACY_CREDENTIALS_PATH = path.join(ZHIHAND_DIR, "credentials.json");
 const STATE_PATH = path.join(ZHIHAND_DIR, "state.json");
 const BACKEND_PATH = path.join(ZHIHAND_DIR, "backend.json");
 export function resolveZhiHandDir() {
@@ -23,47 +18,114 @@ export function resolveZhiHandDir() {
 export function ensureZhiHandDir() {
     fs.mkdirSync(ZHIHAND_DIR, { recursive: true, mode: 0o700 });
 }
-export function loadCredentialStore() {
-    if (!fs.existsSync(CREDENTIALS_PATH))
-        return null;
+// ── v2 config I/O ──────────────────────────────────────────
+let legacyWarningPrinted = false;
+function emptyConfig() {
+    return { schema_version: 2, default_credential_id: null, devices: {} };
+}
+export function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) {
+        if (!legacyWarningPrinted && fs.existsSync(LEGACY_CREDENTIALS_PATH)) {
+            legacyWarningPrinted = true;
+            process.stderr.write("[zhihand] legacy credentials.json detected — run 'zhihand pair' to re-pair on v0.30 schema\n");
+        }
+        return emptyConfig();
+    }
     try {
-        return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf8"));
+        const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+        if (raw && raw.schema_version === 2) {
+            return {
+                schema_version: 2,
+                default_credential_id: raw.default_credential_id ?? null,
+                devices: raw.devices ?? {},
+            };
+        }
     }
     catch {
-        return null;
+        // fall through
     }
+    return emptyConfig();
 }
-export function loadDefaultCredential() {
-    const store = loadCredentialStore();
-    if (!store)
-        return null;
-    return store.devices[store.default] ?? null;
-}
-export function saveCredential(name, cred, setDefault = true) {
+export function saveConfig(cfg) {
     ensureZhiHandDir();
-    let store = loadCredentialStore() ?? { default: name, devices: {} };
-    store.devices[name] = cred;
-    if (setDefault)
-        store.default = name;
-    fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(store, null, 2), { mode: 0o600 });
-}
-export function resolveConfig(deviceName) {
-    const store = loadCredentialStore();
-    if (!store) {
-        throw new Error("No ZhiHand credentials found. Run 'zhihand pair' first.");
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+export function addDevice(record, makeDefault) {
+    const cfg = loadConfig();
+    cfg.devices[record.credential_id] = record;
+    if (makeDefault || cfg.default_credential_id === null) {
+        cfg.default_credential_id = record.credential_id;
+    }
+    saveConfig(cfg);
+}
+export function removeDevice(credentialId) {
+    const cfg = loadConfig();
+    delete cfg.devices[credentialId];
+    if (cfg.default_credential_id === credentialId) {
+        const remaining = Object.keys(cfg.devices);
+        cfg.default_credential_id = remaining[0] ?? null;
     }
-    const name = deviceName ?? store.default;
-    const cred = store.devices[name];
-    if (!cred) {
-        throw new Error(`Device '${name}' not found. Available: ${Object.keys(store.devices).join(", ")}`);
+    saveConfig(cfg);
+}
+export function renameDevice(credentialId, label) {
+    const cfg = loadConfig();
+    const r = cfg.devices[credentialId];
+    if (!r)
+        throw new Error(`Device '${credentialId}' not found`);
+    r.label = label;
+    saveConfig(cfg);
+}
+export function setDefaultDevice(credentialId) {
+    const cfg = loadConfig();
+    if (!cfg.devices[credentialId]) {
+        throw new Error(`Device '${credentialId}' not found`);
     }
+    cfg.default_credential_id = credentialId;
+    saveConfig(cfg);
+}
+export function updateLastSeen(credentialId, iso) {
+    const cfg = loadConfig();
+    const r = cfg.devices[credentialId];
+    if (!r)
+        return;
+    r.last_seen_at = iso;
+    saveConfig(cfg);
+}
+export function getDeviceRecord(credentialId) {
+    const cfg = loadConfig();
+    return cfg.devices[credentialId] ?? null;
+}
+export function listDeviceRecords() {
+    const cfg = loadConfig();
+    return Object.values(cfg.devices);
+}
+// ── Runtime config resolution ─────────────────────────────
+export function recordToRuntimeConfig(r) {
     return {
-        controlPlaneEndpoint: cred.endpoint,
-        credentialId: cred.credentialId,
-        controllerToken: cred.controllerToken,
+        controlPlaneEndpoint: r.endpoint,
+        credentialId: r.credential_id,
+        controllerToken: r.controller_token,
         timeoutMs: 10_000,
     };
 }
+/**
+ * Resolve a runtime config for HTTP calls. If credentialId provided, look it up;
+ * else use default_credential_id; else throw.
+ */
+export function resolveConfig(credentialId) {
+    const cfg = loadConfig();
+    const id = credentialId ?? cfg.default_credential_id;
+    if (!id) {
+        throw new Error("No default device — run zhihand pair");
+    }
+    const r = cfg.devices[id];
+    if (!r) {
+        const known = Object.keys(cfg.devices).join(", ") || "(none)";
+        throw new Error(`Device '${id}' not found. Known: ${known}`);
+    }
+    return recordToRuntimeConfig(r);
+}
+// ── State / backend ───────────────────────────────────────
 export function loadState() {
     if (!fs.existsSync(STATE_PATH))
         return null;

package/dist/core/device.d.ts

@@ -1,13 +1,12 @@
 /**
- * Device Context — static + dynamic device info fetched from control plane.
+ * Device profile extraction & formatting — stateless.
  *
- * Static info (platform, model, screen size) is set once after pairing and
- * injected into MCP tool descriptions so the LLM always knows the device.
- *
- * Dynamic info (battery, network, BLE) is updated via SSE push and exposed
- * through the zhihand_status tool and device://profile resource.
+ * Per-device state (profile, raw attributes, timestamps) lives in the
+ * device registry (see ./registry.ts). This module exposes pure helpers
+ * to extract, classify, and format device data so the same logic can be
+ * applied to any number of devices.
  */
-import type { ZhiHandConfig } from "./config.ts";
+import type { ZhiHandRuntimeConfig } from "./config.ts";
 export interface StaticContext {
     platform: string;
     model: string;
@@ -35,14 +34,40 @@ export interface DynamicContext {
     thermalState?: string;
     fontScale: number;
 }
-export declare function getStaticContext(): StaticContext;
-export declare function getDynamicContext(): DynamicContext;
-export declare function isDeviceProfileLoaded(): boolean;
+declare const DEFAULT_STATIC: StaticContext;
+declare const DEFAULT_DYNAMIC: DynamicContext;
+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 computeCapabilities(rawAttributes: Record<string, unknown>, profileReceivedAtMs: number): 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>;
+/**
+ * Fetch and normalize the device profile from the control plane once.
+ * Returns null on failure (HTTP or network).
+ */
+export declare function fetchDeviceProfileOnce(config: ZhiHandRuntimeConfig): Promise<{
+    rawAttrs: Record<string, unknown>;
+    receivedAtMs: number;
+} | null>;
+/**
+ * Normalize an SSE device_profile.updated payload into rawAttrs shape.
+ */
+export declare function normalizeProfilePayload(raw: Record<string, unknown>): Record<string, unknown>;
+export declare function pickAllowlistedRawAttributes(rawAttributes: Record<string, unknown>): Record<string, unknown>;
+export { DEFAULT_STATIC, DEFAULT_DYNAMIC };
+import type { DeviceState } from "./registry.ts";
+export declare function buildControlToolDescription(state: DeviceState | null, onlineStates?: DeviceState[]): string;
+export declare function buildSystemToolDescription(state: DeviceState | null, onlineStates?: DeviceState[]): string;
+export declare function buildScreenshotToolDescription(state: DeviceState | null, onlineStates?: DeviceState[]): string;
+export declare function formatDeviceStatus(state: DeviceState): Record<string, unknown>;