@zhihand/mcp 0.30.0 → 0.32.1

package/dist/core/pair.js

@@ -1,62 +1,78 @@
 import QRCode from "qrcode";
-import { addDevice, ensureZhiHandDir, saveState } from "./config.js";
+import { addUser, addDeviceToUser, ensureZhiHandDir, saveState, resolveDefaultEndpoint, getUserRecord, } from "./config.js";
 import { fetchDeviceProfileOnce, extractStatic } from "./device.js";
-const DEFAULT_SCOPES = [
-    "observe",
-    "session.control",
-    "screen.read",
-    "screen.capture",
-    "ble.control",
-];
-export async function registerPlugin(endpoint, options) {
-    const response = await fetch(`${endpoint}/v1/plugins`, {
+import { fetchUserCredentials } from "./ws.js";
+// ── Server API helpers ─────────────────────────────────────
+/**
+ * Create a new user on the server.
+ * POST /v1/users { label } → { user_id, controller_token, label, created_at }
+ */
+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.");
@@ -68,49 +84,60 @@ export async function waitForPairingClaim(endpoint, sessionId, timeoutMs = 600_0
 export async function renderPairingQRCode(url) {
     return QRCode.toString(url, { type: "utf8", margin: 2 });
 }
+// ── Pairing flows ──────────────────────────────────────────
 /**
- * Drive the full interactive pairing flow. Saves a new device record into the
- * v2 config on success. Label defaults to the device model (fetched post-claim)
- * and falls back to the supplied preferredLabel or timestamp.
+ * New user pairing: create user → create pairing session → wait → fetch credentials → save config.
  */
-export async function executePairing(endpoint, edgeId, preferredLabel) {
-    const plugin = await registerPlugin(endpoint, {
-        stableIdentity: edgeId,
-        displayName: preferredLabel ? `ZhiHand MCP — ${preferredLabel}` : "ZhiHand MCP Server",
-    });
-    const registeredEdgeId = plugin.edge_id;
-    const session = await createPairingSession(endpoint, { edgeId: registeredEdgeId });
+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,
     });
+    // 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");
-    const claimed = await waitForPairingClaim(endpoint, session.id);
-    const credentialId = claimed.credential_id;
-    const controllerToken = claimed.controller_token ?? session.controller_token;
-    const runtimeCfg = {
-        controlPlaneEndpoint: endpoint,
-        credentialId,
-        controllerToken,
-        timeoutMs: 10_000,
-    };
-    // Try to fetch profile to infer label/platform
-    let label = preferredLabel ?? "";
-    let platform = "unknown";
+    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 (!label)
-                label = st.model && st.model !== "unknown" ? st.model : "";
+            if (!deviceLabel || deviceLabel === cred.credential_id) {
+                deviceLabel = st.model && st.model !== "unknown" ? st.model : "";
+            }
             if (st.platform === "ios" || st.platform === "android")
                 platform = st.platform;
         }
@@ -118,37 +145,114 @@ export async function executePairing(endpoint, edgeId, preferredLabel) {
     catch {
         // fall through
     }
-    if (!label)
-        label = `device-${Date.now().toString(36)}`;
+    if (!deviceLabel)
+        deviceLabel = `device-${Date.now().toString(36)}`;
     const now = new Date().toISOString();
-    const record = {
-        credential_id: credentialId,
-        controller_token: controllerToken,
-        endpoint,
-        label,
+    const deviceRecord = {
+        credential_id: cred.credential_id,
+        label: deviceLabel,
         platform,
-        paired_at: now,
+        paired_at: cred.paired_at ?? now,
         last_seen_at: now,
     };
-    addDevice(record, true);
+    const userRecord = {
+        user_id: userId,
+        controller_token: controllerToken,
+        label,
+        created_at: userResp.created_at ?? now,
+        devices: [deviceRecord],
+    };
+    addUser(userRecord);
     ensureZhiHandDir();
     saveState({
-        sessionId: session.id,
+        sessionId: session.session_id,
+        userId,
         controllerToken,
-        edgeId: session.edge_id,
-        credentialId,
+        edgeId,
+        credentialId: cred.credential_id,
         pairUrl: session.pair_url,
         status: "claimed",
     });
-    return { session: claimed, record };
+    return { userRecord, deviceRecord };
 }
-export function formatPairingStatus(record) {
-    if (!record)
+/**
+ * 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: ${record.label} (${record.platform})`,
-        `Credential: ${record.credential_id}`,
-        `Endpoint: ${record.endpoint}`,
-        `Paired at: ${record.paired_at}`,
-    ].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

@@ -1,67 +1,60 @@
 /**
  * Device registry — the single source of truth for all paired devices,
- * their live state (profile, online flag, SSE connection), and multi-
- * device routing.
+ * their live state, and multi-user WebSocket streams.
  *
- * Holds a per-credential AbortController for SSE, a per-device heartbeat
- * timer, and a single debounced notifier for list_changed.
+ * 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 ZhiHandRuntimeConfig } from "./config.ts";
+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: "ios" | "android" | "unknown";
+    platform: DevicePlatform;
     online: boolean;
     lastSeenAtMs: number;
     profile: StaticContext | null;
     capabilities: Capabilities | null;
     profileReceivedAtMs: number;
     rawAttributes: Record<string, unknown>;
-    sseController: AbortController | null;
-    sseConnected: boolean;
-    heartbeatTimer: ReturnType<typeof setInterval> | null;
     record: DeviceRecord;
 }
 type ListChangedCb = () => void;
 declare class Registry {
-    private devices;
+    private userStates;
     private listChangedSubs;
     private debounceTimer;
     private lastOnlineSet;
     private initialized;
+    private configWatchActive;
+    private reconcileTimer;
     get(credentialId: string): DeviceState | null;
     list(): DeviceState[];
     listOnline(): DeviceState[];
     /**
-     * Priority:
-     *   1. If the user has explicitly set a default via `zhihand default <id>`
-     *      AND that device is online → return it. Honoring an explicit user
-     *      preference is the least-surprising UX.
-     *   2. Otherwise → most-recently-active online device (online[0] is sorted
-     *      desc by lastSeenAtMs).
-     *   3. No online devices → null.
+     * 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 updateOnlineFlag;
+    private createUserState;
+    private makeDeviceState;
+    private populateDevicesFromConfig;
+    private fetchAndPopulateDevices;
+    private startUserStream;
     private touchLastSeen;
-    private refreshProfile;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private startSSE;
-    private stopSSE;
-    private makeState;
-    init(): Promise<void>;
-    addDevice(record: DeviceRecord): Promise<void>;
-    removeDevice(credentialId: string): void;
-    renameDevice(credentialId: string, label: string): void;
-    setDefault(credentialId: string): void;
-    shutdown(): void;
+    private startConfigWatch;
+    private stopConfigWatch;
+    private reconcileConfig;
 }
 export declare const registry: Registry;
 export {};