@zhihand/mcp 0.29.0 → 0.32.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,11 @@
-import { getStaticContext, isDeviceProfileLoaded } from "./device.js";
-import { dbg } from "../daemon/logger.js";
+import { log } from "./logger.js";
+const dbg = (msg) => log.debug(msg);
 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 +57,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 +94,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.`);
@@ -160,7 +158,7 @@ export async function enqueueCommand(config, command) {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
-            "x-zhihand-controller-token": config.controllerToken,
+            "Authorization": `Bearer ${config.controllerToken}`,
         },
         body: JSON.stringify(body),
     });
@@ -176,7 +174,7 @@ export async function getCommand(config, commandId) {
     const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/commands/${encodeURIComponent(commandId)}`;
     dbg(`[cmd] GET ${url}`);
     const response = await fetch(url, {
-        headers: { "x-zhihand-controller-token": config.controllerToken },
+        headers: { "Authorization": `Bearer ${config.controllerToken}` },
     });
     if (!response.ok) {
         dbg(`[cmd] Get failed: ${response.status}`);

package/dist/core/config.d.ts

@@ -1,15 +1,27 @@
-export interface DeviceCredential {
-    credentialId: string;
-    controllerToken: string;
-    endpoint: string;
-    deviceName?: string;
-    pairedAt?: string;
+export type DevicePlatform = "ios" | "android" | "unknown";
+export interface DeviceRecord {
+    credential_id: string;
+    label: string;
+    platform: DevicePlatform;
+    paired_at: string;
+    last_seen_at: string;
+}
+export interface UserRecord {
+    user_id: string;
+    controller_token: string;
+    label: string;
+    created_at: string;
+    devices: DeviceRecord[];
 }
-export interface CredentialStore {
-    default: string;
-    devices: Record<string, DeviceCredential>;
+export interface ZhihandConfigV3 {
+    schema_version: 3;
+    users: Record<string, UserRecord>;
 }
-export interface ZhiHandConfig {
+/**
+ * Runtime config passed to HTTP callers (command/sse/device endpoints).
+ * Derived from a UserRecord + DeviceRecord pair.
+ */
+export interface ZhiHandRuntimeConfig {
     controlPlaneEndpoint: string;
     credentialId: string;
     controllerToken: string;
@@ -21,20 +33,35 @@ 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 getConfigPath(): string;
+export declare function loadConfig(): ZhihandConfigV3;
+/**
+ * Atomically write config: write to .tmp, then rename. Prevents corruption
+ * when the daemon and CLI write concurrently (Gemini code review v0.31).
+ */
+export declare function saveConfig(cfg: ZhihandConfigV3): void;
+export declare function addUser(user: UserRecord): void;
+export declare function removeUser(userId: string): void;
+export declare function addDeviceToUser(userId: string, device: DeviceRecord): void;
+export declare function removeDeviceFromUser(userId: string, credentialId: string): void;
+export declare function updateDeviceLabel(userId: string, credentialId: string, label: string): void;
+export declare function updateControllerToken(userId: string, newToken: string): void;
+export declare function updateDeviceLastSeen(userId: string, credentialId: string, iso: string): void;
+export declare function getUserRecord(userId: string): UserRecord | null;
+export declare function findDeviceOwner(credentialId: string): {
+    user: UserRecord;
+    device: DeviceRecord;
+} | null;
+export declare function listUsers(): UserRecord[];
+export declare function resolveDefaultEndpoint(): string;
+/**
+ * Resolve a runtime config for HTTP calls. Find which user owns the
+ * credential and use the user's controller_token.
+ */
+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,14 @@
 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 STATE_PATH = path.join(ZHIHAND_DIR, "state.json");
 const BACKEND_PATH = path.join(ZHIHAND_DIR, "backend.json");
 export function resolveZhiHandDir() {
@@ -23,47 +17,189 @@ export function resolveZhiHandDir() {
 export function ensureZhiHandDir() {
     fs.mkdirSync(ZHIHAND_DIR, { recursive: true, mode: 0o700 });
 }
-export function loadCredentialStore() {
-    if (!fs.existsSync(CREDENTIALS_PATH))
-        return null;
+export function getConfigPath() {
+    return CONFIG_PATH;
+}
+// ── v3 config I/O ──────────────────────────────────────────
+let legacyWarningPrinted = false;
+function emptyConfig() {
+    return { schema_version: 3, users: {} };
+}
+export function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH)) {
+        // Check for v2 or legacy credentials
+        const legacyCredentials = path.join(ZHIHAND_DIR, "credentials.json");
+        if (!legacyWarningPrinted && (fs.existsSync(legacyCredentials) || checkForV2Config())) {
+            legacyWarningPrinted = true;
+            process.stderr.write("[zhihand] old config detected (v2 or legacy) — run 'zhihand pair' to re-pair on v0.31 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 === 3) {
+            return {
+                schema_version: 3,
+                users: raw.users ?? {},
+            };
+        }
+        // Old schema version detected
+        if (!legacyWarningPrinted) {
+            legacyWarningPrinted = true;
+            process.stderr.write("[zhihand] old config detected (schema v" + (raw.schema_version ?? "?") + ") — run 'zhihand pair' to re-pair on v0.31 schema\n");
+        }
     }
     catch {
-        return null;
+        // fall through
     }
+    return emptyConfig();
 }
-export function loadDefaultCredential() {
-    const store = loadCredentialStore();
-    if (!store)
-        return null;
-    return store.devices[store.default] ?? null;
+function checkForV2Config() {
+    if (!fs.existsSync(CONFIG_PATH))
+        return false;
+    try {
+        const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+        return raw && raw.schema_version === 2;
+    }
+    catch {
+        return false;
+    }
 }
-export function saveCredential(name, cred, setDefault = true) {
+/**
+ * Atomically write config: write to .tmp, then rename. Prevents corruption
+ * when the daemon and CLI write concurrently (Gemini code review v0.31).
+ */
+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.");
+    const tmpPath = CONFIG_PATH + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    fs.renameSync(tmpPath, CONFIG_PATH);
+}
+// ── User helpers ──────────────────────────────────────────
+export function addUser(user) {
+    const cfg = loadConfig();
+    cfg.users[user.user_id] = user;
+    saveConfig(cfg);
+}
+export function removeUser(userId) {
+    const cfg = loadConfig();
+    delete cfg.users[userId];
+    saveConfig(cfg);
+}
+export function addDeviceToUser(userId, device) {
+    const cfg = loadConfig();
+    const user = cfg.users[userId];
+    if (!user)
+        throw new Error(`User '${userId}' not found in config`);
+    // Replace if exists, else append
+    const idx = user.devices.findIndex((d) => d.credential_id === device.credential_id);
+    if (idx >= 0) {
+        user.devices[idx] = device;
+    }
+    else {
+        user.devices.push(device);
+    }
+    saveConfig(cfg);
+}
+export function removeDeviceFromUser(userId, credentialId) {
+    const cfg = loadConfig();
+    const user = cfg.users[userId];
+    if (!user)
+        return;
+    user.devices = user.devices.filter((d) => d.credential_id !== credentialId);
+    saveConfig(cfg);
+}
+export function updateDeviceLabel(userId, credentialId, label) {
+    const cfg = loadConfig();
+    const user = cfg.users[userId];
+    if (!user)
+        throw new Error(`User '${userId}' not found`);
+    const dev = user.devices.find((d) => d.credential_id === credentialId);
+    if (!dev)
+        throw new Error(`Device '${credentialId}' not found under user '${userId}'`);
+    dev.label = label;
+    saveConfig(cfg);
+}
+export function updateControllerToken(userId, newToken) {
+    const cfg = loadConfig();
+    const user = cfg.users[userId];
+    if (!user)
+        throw new Error(`User '${userId}' not found`);
+    user.controller_token = newToken;
+    saveConfig(cfg);
+}
+export function updateDeviceLastSeen(userId, credentialId, iso) {
+    const cfg = loadConfig();
+    const user = cfg.users[userId];
+    if (!user)
+        return;
+    const dev = user.devices.find((d) => d.credential_id === credentialId);
+    if (!dev)
+        return;
+    dev.last_seen_at = iso;
+    saveConfig(cfg);
+}
+export function getUserRecord(userId) {
+    const cfg = loadConfig();
+    return cfg.users[userId] ?? null;
+}
+export function findDeviceOwner(credentialId) {
+    const cfg = loadConfig();
+    for (const user of Object.values(cfg.users)) {
+        const device = user.devices.find((d) => d.credential_id === credentialId);
+        if (device)
+            return { user, device };
+    }
+    return null;
+}
+export function listUsers() {
+    const cfg = loadConfig();
+    return Object.values(cfg.users);
+}
+// ── Runtime config resolution ─────────────────────────────
+export function resolveDefaultEndpoint() {
+    return process.env.ZHIHAND_ENDPOINT ?? "https://api.zhihand.com";
+}
+/**
+ * Resolve a runtime config for HTTP calls. Find which user owns the
+ * credential and use the user's controller_token.
+ */
+export function resolveConfig(credentialId) {
+    const cfg = loadConfig();
+    const endpoint = resolveDefaultEndpoint();
+    if (credentialId) {
+        const owner = findDeviceOwner(credentialId);
+        if (!owner) {
+            const known = Object.values(cfg.users)
+                .flatMap((u) => u.devices.map((d) => d.credential_id))
+                .join(", ") || "(none)";
+            throw new Error(`Device '${credentialId}' not found. Known: ${known}`);
+        }
+        return {
+            controlPlaneEndpoint: endpoint,
+            credentialId,
+            controllerToken: owner.user.controller_token,
+            timeoutMs: 10_000,
+        };
+    }
+    // No explicit credential — pick first device of first user
+    const users = Object.values(cfg.users);
+    if (users.length === 0) {
+        throw new Error("No users configured — run zhihand pair");
     }
-    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(", ")}`);
+    for (const user of users) {
+        if (user.devices.length > 0) {
+            return {
+                controlPlaneEndpoint: endpoint,
+                credentialId: user.devices[0].credential_id,
+                controllerToken: user.controller_token,
+                timeoutMs: 10_000,
+            };
+        }
     }
-    return {
-        controlPlaneEndpoint: cred.endpoint,
-        credentialId: cred.credentialId,
-        controllerToken: cred.controllerToken,
-        timeoutMs: 10_000,
-    };
+    throw new Error("No devices configured — run zhihand pair");
 }
+// ── 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,11 +34,8 @@ export interface DynamicContext {
     thermalState?: string;
     fontScale: number;
 }
-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;
+declare const DEFAULT_STATIC: StaticContext;
+declare const DEFAULT_DYNAMIC: DynamicContext;
 export interface Capability {
     ready: boolean;
     reason: string;
@@ -53,12 +49,25 @@ export interface Capabilities {
         stale: boolean;
     };
 }
-export declare function getCapabilities(): Capabilities;
+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[], multiUser?: boolean): string;
+export declare function buildSystemToolDescription(state: DeviceState | null, onlineStates?: DeviceState[], multiUser?: boolean): string;
+export declare function buildScreenshotToolDescription(state: DeviceState | null, onlineStates?: DeviceState[], multiUser?: boolean): string;
+export declare function formatDeviceStatus(state: DeviceState): Record<string, unknown>;