@zhihand/mcp 0.29.0 → 0.32.0

package/dist/core/pair.js

@@ -1,66 +1,78 @@
 import QRCode from "qrcode";
-import { saveCredential, saveState } from "./config.js";
-const DEFAULT_SCOPES = [
-    "observe",
-    "session.control",
-    "screen.read",
-    "screen.capture",
-    "ble.control",
-];
+import { addUser, addDeviceToUser, ensureZhiHandDir, saveState, resolveDefaultEndpoint, getUserRecord, } from "./config.js";
+import { fetchDeviceProfileOnce, extractStatic } from "./device.js";
+import { fetchUserCredentials } from "./ws.js";
+// ── Server API helpers ─────────────────────────────────────
 /**
- * Register this MCP instance as a plugin with the server.
- * Server requires a registered plugin (edge_id) before pairing can begin.
- * Idempotent — re-registering with the same stable_identity returns the existing plugin.
+ * Create a new user on the server.
+ * POST /v1/users { label } → { user_id, controller_token, label, created_at }
  */
-export async function registerPlugin(endpoint, options) {
-    const response = await fetch(`${endpoint}/v1/plugins`, {
+export async function createUser(endpoint, label) {
+    const response = await fetch(`${endpoint}/v1/users`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            adapter_kind: options.adapterKind ?? "mcp",
-            display_name: options.displayName ?? "ZhiHand MCP Server",
-            stable_identity: options.stableIdentity,
-        }),
+        body: JSON.stringify({ label }),
     });
     if (!response.ok) {
-        throw new Error(`Register plugin failed: ${response.status} ${await response.text()}`);
+        throw new Error(`Create user failed: ${response.status} ${await response.text()}`);
     }
-    const payload = (await response.json());
-    return payload.plugin;
+    return (await response.json());
 }
-export async function createPairingSession(endpoint, options) {
-    const response = await fetch(`${endpoint}/v1/pairing/sessions`, {
+/**
+ * Create a pairing session for a user.
+ * POST /v1/users/{id}/pairing/sessions { edge_id, ttl_seconds } → PairingSession
+ */
+export async function createPairingSession(endpoint, userId, controllerToken, edgeId, ttlSeconds = 300) {
+    const response = await fetch(`${endpoint}/v1/users/${encodeURIComponent(userId)}/pairing/sessions`, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${controllerToken}`,
+        },
         body: JSON.stringify({
-            edge_id: options.edgeId,
-            ttl_seconds: options.ttlSeconds ?? 600,
-            requested_scopes: options.requestedScopes ?? DEFAULT_SCOPES,
+            edge_id: edgeId,
+            ttl_seconds: ttlSeconds,
+            requested_scopes: ["observe", "session.control", "screen.read", "screen.capture", "ble.control"],
         }),
     });
     if (!response.ok) {
         throw new Error(`Create pairing session failed: ${response.status}`);
     }
     const payload = (await response.json());
-    return {
-        ...payload.session,
-        controller_token: payload.controller_token ?? payload.session.controller_token,
-    };
+    return payload;
 }
-export async function getPairingSession(endpoint, sessionId) {
-    const response = await fetch(`${endpoint}/v1/pairing/sessions/${encodeURIComponent(sessionId)}`);
+/**
+ * Register a plugin (edge). Kept for backward compat with edge registration.
+ */
+export async function registerPlugin(endpoint, options) {
+    const response = await fetch(`${endpoint}/v1/plugins`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            adapter_kind: options.adapterKind ?? "mcp",
+            display_name: options.displayName ?? "ZhiHand MCP Server",
+            stable_identity: options.stableIdentity,
+        }),
+    });
     if (!response.ok) {
-        throw new Error(`Get pairing session failed: ${response.status}`);
+        throw new Error(`Register plugin failed: ${response.status} ${await response.text()}`);
     }
     const payload = (await response.json());
-    return payload.session;
+    return { edge_id: payload.plugin.edge_id };
 }
-export async function waitForPairingClaim(endpoint, sessionId, timeoutMs = 600_000) {
+/**
+ * Poll pairing session until claimed or expired.
+ */
+export async function waitForPairingClaim(endpoint, userId, controllerToken, sessionId, timeoutMs = 600_000) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        const session = await getPairingSession(endpoint, sessionId);
-        if (session.status === "claimed" && session.credential_id) {
-            return session;
+        const response = await fetch(`${endpoint}/v1/users/${encodeURIComponent(userId)}/pairing/sessions/${encodeURIComponent(sessionId)}`, { headers: { "Authorization": `Bearer ${controllerToken}` } });
+        if (!response.ok) {
+            throw new Error(`Get pairing session failed: ${response.status}`);
+        }
+        const session = (await response.json());
+        if (session.status === "claimed") {
+            return;
         }
         if (session.status === "expired") {
             throw new Error("Pairing session expired.");
@@ -72,59 +84,175 @@ export async function waitForPairingClaim(endpoint, sessionId, timeoutMs = 600_0
 export async function renderPairingQRCode(url) {
     return QRCode.toString(url, { type: "utf8", margin: 2 });
 }
-export async function executePairing(endpoint, edgeId, deviceName) {
-    // Step 0: Register plugin first — server requires a known edge_id before pairing.
-    // Uses edgeId as stable_identity so re-runs are idempotent.
-    const plugin = await registerPlugin(endpoint, {
-        stableIdentity: edgeId,
-        displayName: deviceName ? `ZhiHand MCP — ${deviceName}` : "ZhiHand MCP Server",
-    });
-    const registeredEdgeId = plugin.edge_id;
-    const session = await createPairingSession(endpoint, { edgeId: registeredEdgeId });
-    // Save pending state
+// ── Pairing flows ──────────────────────────────────────────
+/**
+ * New user pairing: create user → create pairing session → wait → fetch credentials → save config.
+ */
+export async function executePairingNewUser(preferredLabel) {
+    const endpoint = resolveDefaultEndpoint();
+    const label = preferredLabel ?? `User-${Date.now().toString(36)}`;
+    // 1. Create user
+    const userResp = await createUser(endpoint, label);
+    const userId = userResp.user_id;
+    const controllerToken = userResp.controller_token;
+    // 2. Register plugin (get edge_id)
+    const stableIdentity = `mcp-${Date.now().toString(36)}`;
+    const plugin = await registerPlugin(endpoint, { stableIdentity });
+    const edgeId = plugin.edge_id;
+    // 3. Create pairing session
+    const session = await createPairingSession(endpoint, userId, controllerToken, edgeId, 300);
     saveState({
-        sessionId: session.id,
-        controllerToken: session.controller_token,
-        edgeId: session.edge_id,
+        sessionId: session.session_id,
+        userId,
+        controllerToken,
+        edgeId,
         pairUrl: session.pair_url,
         status: "pending",
         expiresAt: session.expires_at,
     });
-    // Display QR code and pairing URL
+    // 4. Show QR + wait
     const qr = await renderPairingQRCode(session.pair_url);
     console.log(qr);
     console.log(`Open this URL on your phone to pair:\n  ${session.pair_url}\n`);
     console.log(`Expires at: ${session.expires_at}`);
     console.log("Waiting for phone to scan...\n");
-    // Wait for phone to scan
-    const claimed = await waitForPairingClaim(endpoint, session.id);
-    const credential = {
-        credentialId: claimed.credential_id,
-        controllerToken: claimed.controller_token ?? session.controller_token,
-        endpoint,
-        deviceName: deviceName ?? `device_${Date.now()}`,
-        pairedAt: new Date().toISOString(),
+    await waitForPairingClaim(endpoint, userId, controllerToken, session.session_id);
+    // 5. Fetch credentials to get device info
+    const creds = await fetchUserCredentials(endpoint, userId, controllerToken);
+    const cred = creds[0]; // Just-paired device should be the first/only
+    if (!cred)
+        throw new Error("Pairing claimed but no credentials found");
+    // 6. Try to get label/platform from profile
+    let deviceLabel = cred.label ?? "";
+    let platform = cred.platform ?? "unknown";
+    try {
+        const runtimeCfg = {
+            controlPlaneEndpoint: endpoint,
+            credentialId: cred.credential_id,
+            controllerToken,
+            timeoutMs: 10_000,
+        };
+        const fetched = await fetchDeviceProfileOnce(runtimeCfg);
+        if (fetched) {
+            const st = extractStatic(fetched.rawAttrs);
+            if (!deviceLabel || deviceLabel === cred.credential_id) {
+                deviceLabel = st.model && st.model !== "unknown" ? st.model : "";
+            }
+            if (st.platform === "ios" || st.platform === "android")
+                platform = st.platform;
+        }
+    }
+    catch {
+        // fall through
+    }
+    if (!deviceLabel)
+        deviceLabel = `device-${Date.now().toString(36)}`;
+    const now = new Date().toISOString();
+    const deviceRecord = {
+        credential_id: cred.credential_id,
+        label: deviceLabel,
+        platform,
+        paired_at: cred.paired_at ?? now,
+        last_seen_at: now,
+    };
+    const userRecord = {
+        user_id: userId,
+        controller_token: controllerToken,
+        label,
+        created_at: userResp.created_at ?? now,
+        devices: [deviceRecord],
     };
-    const name = deviceName ?? credential.deviceName;
-    saveCredential(name, credential, true);
-    // Update state
+    addUser(userRecord);
+    ensureZhiHandDir();
     saveState({
-        sessionId: session.id,
-        controllerToken: credential.controllerToken,
-        edgeId: session.edge_id,
-        credentialId: credential.credentialId,
+        sessionId: session.session_id,
+        userId,
+        controllerToken,
+        edgeId,
+        credentialId: cred.credential_id,
         pairUrl: session.pair_url,
         status: "claimed",
     });
-    return { session: claimed, credential };
+    return { userRecord, deviceRecord };
 }
-export function formatPairingStatus(cred) {
-    if (!cred)
+/**
+ * Add device to existing user: create pairing session → wait → fetch new credential → save.
+ */
+export async function executePairingAddDevice(userId, preferredLabel) {
+    const endpoint = resolveDefaultEndpoint();
+    const user = getUserRecord(userId);
+    if (!user)
+        throw new Error(`User '${userId}' not found in config`);
+    const controllerToken = user.controller_token;
+    // Register plugin (get edge_id)
+    const stableIdentity = `mcp-${Date.now().toString(36)}`;
+    const plugin = await registerPlugin(endpoint, { stableIdentity });
+    const edgeId = plugin.edge_id;
+    // Get existing credential IDs before pairing
+    const existingCreds = await fetchUserCredentials(endpoint, userId, controllerToken);
+    const existingIds = new Set(existingCreds.map((c) => c.credential_id));
+    // Create pairing session
+    const session = await createPairingSession(endpoint, userId, controllerToken, edgeId, 300);
+    const qr = await renderPairingQRCode(session.pair_url);
+    console.log(qr);
+    console.log(`Open this URL on your phone to pair:\n  ${session.pair_url}\n`);
+    console.log(`Expires at: ${session.expires_at}`);
+    console.log("Waiting for phone to scan...\n");
+    await waitForPairingClaim(endpoint, userId, controllerToken, session.session_id);
+    // Fetch credentials and find the new one
+    const updatedCreds = await fetchUserCredentials(endpoint, userId, controllerToken);
+    const newCred = updatedCreds.find((c) => !existingIds.has(c.credential_id));
+    if (!newCred)
+        throw new Error("Pairing claimed but no new credential found");
+    // Try to get label/platform
+    let deviceLabel = preferredLabel ?? newCred.label ?? "";
+    let platform = newCred.platform ?? "unknown";
+    try {
+        const runtimeCfg = {
+            controlPlaneEndpoint: endpoint,
+            credentialId: newCred.credential_id,
+            controllerToken,
+            timeoutMs: 10_000,
+        };
+        const fetched = await fetchDeviceProfileOnce(runtimeCfg);
+        if (fetched) {
+            const st = extractStatic(fetched.rawAttrs);
+            if (!deviceLabel || deviceLabel === newCred.credential_id) {
+                deviceLabel = st.model && st.model !== "unknown" ? st.model : "";
+            }
+            if (st.platform === "ios" || st.platform === "android")
+                platform = st.platform;
+        }
+    }
+    catch {
+        // fall through
+    }
+    if (!deviceLabel)
+        deviceLabel = `device-${Date.now().toString(36)}`;
+    const now = new Date().toISOString();
+    const deviceRecord = {
+        credential_id: newCred.credential_id,
+        label: deviceLabel,
+        platform,
+        paired_at: newCred.paired_at ?? now,
+        last_seen_at: now,
+    };
+    addDeviceToUser(userId, deviceRecord);
+    return deviceRecord;
+}
+/**
+ * Legacy: format pairing status (kept for backward compat).
+ */
+export function formatPairingStatus(userId) {
+    if (!userId)
+        return "Not paired. Run 'zhihand pair' to connect a device.";
+    const user = getUserRecord(userId);
+    if (!user)
         return "Not paired. Run 'zhihand pair' to connect a device.";
-    return [
-        `Paired to: ${cred.deviceName ?? "unknown device"}`,
-        `Endpoint: ${cred.endpoint}`,
-        `Credential: ${cred.credentialId}`,
-        `Paired at: ${cred.pairedAt ?? "unknown"}`,
-    ].join("\n");
+    const lines = [
+        `User: ${user.label} (${user.user_id})`,
+        `Devices: ${user.devices.length}`,
+        ...user.devices.map((d) => `  - ${d.credential_id} (${d.label}, ${d.platform})`),
+    ];
+    return lines.join("\n");
 }

package/dist/core/registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Device registry — the single source of truth for all paired devices,
+ * their live state, and multi-user WebSocket streams.
+ *
+ * Groups devices under users. Each user has one UserEventWebSocket.
+ * Online detection is server-authoritative (no local heartbeat polling).
+ * Config hot-reload via fs.watchFile.
+ */
+import { type DeviceRecord, type DevicePlatform, type ZhiHandRuntimeConfig } from "./config.ts";
+import { type StaticContext, type Capabilities } from "./device.ts";
+export interface DeviceState {
+    credentialId: string;
+    userId: string;
+    userLabel: string;
+    label: string;
+    platform: DevicePlatform;
+    online: boolean;
+    lastSeenAtMs: number;
+    profile: StaticContext | null;
+    capabilities: Capabilities | null;
+    profileReceivedAtMs: number;
+    rawAttributes: Record<string, unknown>;
+    record: DeviceRecord;
+}
+type ListChangedCb = () => void;
+declare class Registry {
+    private userStates;
+    private listChangedSubs;
+    private debounceTimer;
+    private lastOnlineSet;
+    private initialized;
+    private configWatchActive;
+    private reconcileTimer;
+    get(credentialId: string): DeviceState | null;
+    list(): DeviceState[];
+    listOnline(): DeviceState[];
+    /**
+     * Most-recently-active online device across all users.
+     */
+    resolveDefault(): DeviceState | null;
+    isMultiUser(): boolean;
+    toRuntimeConfig(state: DeviceState): ZhiHandRuntimeConfig;
+    subscribe(cb: ListChangedCb): () => void;
+    init(): Promise<void>;
+    shutdown(): void;
+    private computeOnlineSet;
+    private setsEqual;
+    private scheduleListChanged;
+    private createUserState;
+    private makeDeviceState;
+    private populateDevicesFromConfig;
+    private fetchAndPopulateDevices;
+    private startUserStream;
+    private touchLastSeen;
+    private startConfigWatch;
+    private stopConfigWatch;
+    private reconcileConfig;
+}
+export declare const registry: Registry;
+export {};