@zhihand/mcp 0.30.0 → 0.32.1

package/dist/core/command.js

@@ -1,4 +1,5 @@
-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;
@@ -157,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),
     });
@@ -173,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,21 +1,25 @@
 export type DevicePlatform = "ios" | "android" | "unknown";
 export interface DeviceRecord {
     credential_id: string;
-    controller_token: string;
-    endpoint: string;
     label: string;
     platform: DevicePlatform;
     paired_at: string;
     last_seen_at: string;
 }
-export interface ZhihandConfig {
-    schema_version: 2;
-    default_credential_id: string | null;
-    devices: Record<string, DeviceRecord>;
+export interface UserRecord {
+    user_id: string;
+    controller_token: string;
+    label: string;
+    created_at: string;
+    devices: DeviceRecord[];
+}
+export interface ZhihandConfigV3 {
+    schema_version: 3;
+    users: Record<string, UserRecord>;
 }
 /**
- * Legacy-shaped config passed to HTTP callers (command/sse/device endpoints).
- * Corresponds to what the old single-device code called ZhiHandConfig.
+ * Runtime config passed to HTTP callers (command/sse/device endpoints).
+ * Derived from a UserRecord + DeviceRecord pair.
  */
 export interface ZhiHandRuntimeConfig {
     controlPlaneEndpoint: string;
@@ -32,19 +36,30 @@ export interface BackendConfig {
 export declare const DEFAULT_MODELS: Record<Exclude<BackendName, "openclaw">, string>;
 export declare function resolveZhiHandDir(): string;
 export declare function ensureZhiHandDir(): void;
-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;
+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. If credentialId provided, look it up;
- * else use default_credential_id; else throw.
+ * 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;

package/dist/core/config.js

@@ -9,7 +9,6 @@ export const DEFAULT_MODELS = {
 // ── Paths ──────────────────────────────────────────────────
 const ZHIHAND_DIR = path.join(os.homedir(), ".zhihand");
 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() {
@@ -18,112 +17,187 @@ export function resolveZhiHandDir() {
 export function ensureZhiHandDir() {
     fs.mkdirSync(ZHIHAND_DIR, { recursive: true, mode: 0o700 });
 }
-// ── v2 config I/O ──────────────────────────────────────────
+export function getConfigPath() {
+    return CONFIG_PATH;
+}
+// ── v3 config I/O ──────────────────────────────────────────
 let legacyWarningPrinted = false;
 function emptyConfig() {
-    return { schema_version: 2, default_credential_id: null, devices: {} };
+    return { schema_version: 3, users: {} };
 }
 export function loadConfig() {
     if (!fs.existsSync(CONFIG_PATH)) {
-        if (!legacyWarningPrinted && fs.existsSync(LEGACY_CREDENTIALS_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] legacy credentials.json detected — run 'zhihand pair' to re-pair on v0.30 schema\n");
+            process.stderr.write("[zhihand] old config detected (v2 or legacy) — run 'zhihand pair' to re-pair on v0.31 schema\n");
         }
         return emptyConfig();
     }
     try {
         const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
-        if (raw && raw.schema_version === 2) {
+        if (raw && raw.schema_version === 3) {
             return {
-                schema_version: 2,
-                default_credential_id: raw.default_credential_id ?? null,
-                devices: raw.devices ?? {},
+                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 {
         // fall through
     }
     return emptyConfig();
 }
+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;
+    }
+}
+/**
+ * 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();
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    const tmpPath = CONFIG_PATH + ".tmp";
+    fs.writeFileSync(tmpPath, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    fs.renameSync(tmpPath, CONFIG_PATH);
 }
-export function addDevice(record, makeDefault) {
+// ── User helpers ──────────────────────────────────────────
+export function addUser(user) {
     const cfg = loadConfig();
-    cfg.devices[record.credential_id] = record;
-    if (makeDefault || cfg.default_credential_id === null) {
-        cfg.default_credential_id = record.credential_id;
-    }
+    cfg.users[user.user_id] = user;
+    saveConfig(cfg);
+}
+export function removeUser(userId) {
+    const cfg = loadConfig();
+    delete cfg.users[userId];
     saveConfig(cfg);
 }
-export function removeDevice(credentialId) {
+export function addDeviceToUser(userId, device) {
     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 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 renameDevice(credentialId, label) {
+export function removeDeviceFromUser(userId, credentialId) {
     const cfg = loadConfig();
-    const r = cfg.devices[credentialId];
-    if (!r)
-        throw new Error(`Device '${credentialId}' not found`);
-    r.label = label;
+    const user = cfg.users[userId];
+    if (!user)
+        return;
+    user.devices = user.devices.filter((d) => d.credential_id !== credentialId);
     saveConfig(cfg);
 }
-export function setDefaultDevice(credentialId) {
+export function updateDeviceLabel(userId, credentialId, label) {
     const cfg = loadConfig();
-    if (!cfg.devices[credentialId]) {
-        throw new Error(`Device '${credentialId}' not found`);
-    }
-    cfg.default_credential_id = credentialId;
+    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 updateLastSeen(credentialId, iso) {
+export function updateDeviceLastSeen(userId, credentialId, iso) {
     const cfg = loadConfig();
-    const r = cfg.devices[credentialId];
-    if (!r)
+    const user = cfg.users[userId];
+    if (!user)
         return;
-    r.last_seen_at = iso;
+    const dev = user.devices.find((d) => d.credential_id === credentialId);
+    if (!dev)
+        return;
+    dev.last_seen_at = iso;
     saveConfig(cfg);
 }
-export function getDeviceRecord(credentialId) {
+export function getUserRecord(userId) {
     const cfg = loadConfig();
-    return cfg.devices[credentialId] ?? null;
+    return cfg.users[userId] ?? null;
 }
-export function listDeviceRecords() {
+export function findDeviceOwner(credentialId) {
     const cfg = loadConfig();
-    return Object.values(cfg.devices);
+    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 recordToRuntimeConfig(r) {
-    return {
-        controlPlaneEndpoint: r.endpoint,
-        credentialId: r.credential_id,
-        controllerToken: r.controller_token,
-        timeoutMs: 10_000,
-    };
+export function resolveDefaultEndpoint() {
+    return process.env.ZHIHAND_ENDPOINT ?? "https://api.zhihand.com";
 }
 /**
- * Resolve a runtime config for HTTP calls. If credentialId provided, look it up;
- * else use default_credential_id; else throw.
+ * 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 id = credentialId ?? cfg.default_credential_id;
-    if (!id) {
-        throw new Error("No default device — run zhihand pair");
+    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 r = cfg.devices[id];
-    if (!r) {
-        const known = Object.keys(cfg.devices).join(", ") || "(none)";
-        throw new Error(`Device '${id}' not found. Known: ${known}`);
+    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 recordToRuntimeConfig(r);
+    throw new Error("No devices configured — run zhihand pair");
 }
 // ── State / backend ───────────────────────────────────────
 export function loadState() {

package/dist/core/device.d.ts

@@ -67,7 +67,7 @@ export declare function normalizeProfilePayload(raw: Record<string, unknown>): R
 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 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>;

package/dist/core/device.js

@@ -6,7 +6,7 @@
  * to extract, classify, and format device data so the same logic can be
  * applied to any number of devices.
  */
-import { dbg } from "../daemon/logger.js";
+import { log } from "./logger.js";
 const DEFAULT_STATIC = {
     platform: "unknown",
     model: "unknown",
@@ -136,14 +136,14 @@ export function extractDynamic(profile) {
  */
 export async function fetchDeviceProfileOnce(config) {
     const url = `${config.controlPlaneEndpoint}/v1/credentials/${encodeURIComponent(config.credentialId)}/device-profile`;
-    dbg(`[device] Fetching profile: GET ${url}`);
+    log.debug(`[device] Fetching profile: GET ${url}`);
     try {
         const response = await fetch(url, {
-            headers: { "x-zhihand-controller-token": config.controllerToken },
+            headers: { "Authorization": `Bearer ${config.controllerToken}` },
             signal: AbortSignal.timeout(10_000),
         });
         if (!response.ok) {
-            dbg(`[device] Profile fetch failed: ${response.status} ${response.statusText}`);
+            log.debug(`[device] Profile fetch failed: ${response.status} ${response.statusText}`);
             return null;
         }
         const data = (await response.json());
@@ -157,7 +157,7 @@ export async function fetchDeviceProfileOnce(config) {
         return { rawAttrs, receivedAtMs: Date.now() };
     }
     catch (err) {
-        dbg(`[device] Profile fetch error: ${err.message}`);
+        log.debug(`[device] Profile fetch error: ${err.message}`);
         return null;
     }
 }
@@ -200,6 +200,9 @@ export function pickAllowlistedRawAttributes(rawAttributes) {
 }
 // ── Default static/dynamic export for empty-state rendering ──
 export { DEFAULT_STATIC, DEFAULT_DYNAMIC };
+function formatDeviceLabel(d, multiUser) {
+    return multiUser ? `[${d.userLabel}] ${d.label}` : d.label;
+}
 function singleDeviceOpenAppGuidance(platform) {
     if (platform === "android") {
         return " For open_app, use appPackage (e.g. 'com.tencent.mm'). Do NOT send bundleId or urlScheme.";
@@ -209,7 +212,7 @@ function singleDeviceOpenAppGuidance(platform) {
     }
     return "";
 }
-export function buildControlToolDescription(state, onlineStates) {
+export function buildControlToolDescription(state, onlineStates, multiUser) {
     const baseGeneric = "Control the connected mobile device. Supports click, swipe, type, scroll, open_app, back, home, and more. All coordinates use normalized ratios [0,1]. Call zhihand_list_devices to see online devices, then pass device_id.";
     if (onlineStates) {
         if (onlineStates.length === 0) {
@@ -218,8 +221,9 @@ export function buildControlToolDescription(state, onlineStates) {
         if (onlineStates.length === 1) {
             const s = onlineStates[0];
             const ctx = s.profile;
+            const label = formatDeviceLabel(s, multiUser ?? false);
             if (!ctx || ctx.platform === "unknown") {
-                return `Control the connected mobile device (${s.label}). device_id is optional (single device online). All coordinates use normalized ratios [0,1].`;
+                return `Control the connected mobile device (${label}). device_id is optional (single device online). All coordinates use normalized ratios [0,1].`;
             }
             const parts = [
                 `Control a ${ctx.platform} device`,
@@ -233,7 +237,7 @@ export function buildControlToolDescription(state, onlineStates) {
             return desc;
         }
         // 2+ devices
-        const ids = onlineStates.map((d) => `${d.credentialId} (${d.label}, ${d.platform})`).join("; ");
+        const ids = onlineStates.map((d) => `${d.credentialId} (${formatDeviceLabel(d, multiUser ?? false)}, ${d.platform})`).join("; ");
         return `Control a mobile device. device_id is REQUIRED (multiple online). Online devices: ${ids}. Call zhihand_list_devices first. All coordinates use normalized ratios [0,1].`;
     }
     // No explicit onlineStates: describe single state or generic
@@ -252,7 +256,7 @@ export function buildControlToolDescription(state, onlineStates) {
     desc += singleDeviceOpenAppGuidance(ctx.platform);
     return desc;
 }
-export function buildSystemToolDescription(state, onlineStates) {
+export function buildSystemToolDescription(state, onlineStates, multiUser) {
     const genericBase = "System navigation and media controls. Actions: notification, recent, search, switch_input, siri (iOS), control_center (iOS), open_browser (Android), shortcut_help (Android), volume_up/down, mute, play_pause, stop, next/prev_track, fast_forward, rewind, brightness_up/down, power.";
     if (onlineStates) {
         if (onlineStates.length === 0) {
@@ -261,8 +265,9 @@ export function buildSystemToolDescription(state, onlineStates) {
         if (onlineStates.length === 1) {
             const s = onlineStates[0];
             const platform = s.profile?.platform ?? s.platform;
+            const label = formatDeviceLabel(s, multiUser ?? false);
             const parts = [
-                `System navigation and media controls for ${platform} device (${s.profile?.model ?? s.label}). device_id is optional (single device online).`,
+                `System navigation and media controls for ${platform} device (${s.profile?.model ?? label}). device_id is optional (single device online).`,
             ];
             parts.push("Navigation: notification, recent, search (optional text query), switch_input.");
             if (platform === "ios")
@@ -273,7 +278,7 @@ export function buildSystemToolDescription(state, onlineStates) {
             parts.push("Hardware: brightness_up, brightness_down, power.");
             return parts.join(" ");
         }
-        const ids = onlineStates.map((d) => `${d.credentialId} (${d.label}, ${d.platform})`).join("; ");
+        const ids = onlineStates.map((d) => `${d.credentialId} (${formatDeviceLabel(d, multiUser ?? false)}, ${d.platform})`).join("; ");
         return `System navigation and media controls for mobile device. device_id is REQUIRED (multiple online). Online: ${ids}. ` + genericBase;
     }
     if (!state || !state.profile || state.profile.platform === "unknown") {
@@ -292,7 +297,7 @@ export function buildSystemToolDescription(state, onlineStates) {
     parts.push("Hardware: brightness_up, brightness_down, power.");
     return parts.join(" ");
 }
-export function buildScreenshotToolDescription(state, onlineStates) {
+export function buildScreenshotToolDescription(state, onlineStates, multiUser) {
     if (onlineStates) {
         if (onlineStates.length === 0) {
             return "Take a screenshot of the phone screen. No devices online — ask user to open the ZhiHand app.";
@@ -300,12 +305,13 @@ export function buildScreenshotToolDescription(state, onlineStates) {
         if (onlineStates.length === 1) {
             const s = onlineStates[0];
             const ctx = s.profile;
+            const label = formatDeviceLabel(s, multiUser ?? false);
             if (!ctx || ctx.platform === "unknown") {
-                return `Take a screenshot of the phone screen (${s.label}). device_id is optional (single device online).`;
+                return `Take a screenshot of the phone screen (${label}). device_id is optional (single device online).`;
             }
             return `Take a screenshot of the ${ctx.platform} device (${ctx.model}, ${ctx.screenWidthPx}x${ctx.screenHeightPx}). device_id is optional (single device online).`;
         }
-        const ids = onlineStates.map((d) => `${d.credentialId} (${d.label})`).join("; ");
+        const ids = onlineStates.map((d) => `${d.credentialId} (${formatDeviceLabel(d, multiUser ?? false)})`).join("; ");
         return `Take a screenshot of a mobile device. device_id is REQUIRED (multiple online). Online: ${ids}.`;
     }
     if (!state || !state.profile || state.profile.platform === "unknown") {
@@ -324,6 +330,8 @@ export function formatDeviceStatus(state) {
     return {
         credential_id: state.credentialId,
         label: state.label,
+        user_id: state.userId,
+        user_label: state.userLabel,
         online: state.online,
         platform: staticCtx.platform,
         model: staticCtx.model,

package/dist/core/logger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unified logger — all log output goes to stderr so stdout stays clean
+ * for MCP JSON-RPC. Replaces ad-hoc process.stderr.write and dbg() calls
+ * in core/ and tools/ code.
+ *
+ * The daemon has its own stdout-based log() in daemon/index.ts — that is
+ * intentional (it writes to daemon.log). The daemon's debug logger
+ * (daemon/logger.ts) remains for daemon-specific verbose output.
+ */
+export declare const log: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+};
+export declare function setDebugEnabled(v: boolean): void;
+export declare function isDebugEnabled(): boolean;

package/dist/core/logger.js

@@ -0,0 +1,32 @@
+/**
+ * Unified logger — all log output goes to stderr so stdout stays clean
+ * for MCP JSON-RPC. Replaces ad-hoc process.stderr.write and dbg() calls
+ * in core/ and tools/ code.
+ *
+ * The daemon has its own stdout-based log() in daemon/index.ts — that is
+ * intentional (it writes to daemon.log). The daemon's debug logger
+ * (daemon/logger.ts) remains for daemon-specific verbose output.
+ */
+let debugEnabled = false;
+export const log = {
+    info: (...args) => {
+        process.stderr.write(`[info]  ${args.map(String).join(" ")}\n`);
+    },
+    warn: (...args) => {
+        process.stderr.write(`[warn]  ${args.map(String).join(" ")}\n`);
+    },
+    error: (...args) => {
+        process.stderr.write(`[error] ${args.map(String).join(" ")}\n`);
+    },
+    debug: (...args) => {
+        if (debugEnabled) {
+            process.stderr.write(`[debug] ${args.map(String).join(" ")}\n`);
+        }
+    },
+};
+export function setDebugEnabled(v) {
+    debugEnabled = v;
+}
+export function isDebugEnabled() {
+    return debugEnabled;
+}

package/dist/core/pair.d.ts

@@ -1,45 +1,53 @@
-import type { DeviceRecord } from "./config.ts";
-export interface PluginRecord {
-    id: string;
-    edge_id: string;
-    adapter_kind: string;
-    display_name?: string;
-    stable_identity?: string;
-    status: string;
-    created_at: string;
-}
+import type { DeviceRecord, UserRecord } from "./config.ts";
 export interface PairingSession {
-    id: string;
+    session_id: string;
     pair_url: string;
     qr_payload: string;
-    controller_token?: string;
-    edge_id: string;
-    status: "pending" | "claimed" | "expired" | string;
-    credential_id?: string;
     expires_at: string;
-    requested_scopes?: string[];
 }
-export interface CreatePairingOptions {
-    edgeId: string;
-    ttlSeconds?: number;
-    requestedScopes?: string[];
+export interface CreateUserResponse {
+    user_id: string;
+    controller_token: string;
+    label: string;
+    created_at: string;
 }
+/**
+ * Create a new user on the server.
+ * POST /v1/users { label } → { user_id, controller_token, label, created_at }
+ */
+export declare function createUser(endpoint: string, label: string): Promise<CreateUserResponse>;
+/**
+ * Create a pairing session for a user.
+ * POST /v1/users/{id}/pairing/sessions { edge_id, ttl_seconds } → PairingSession
+ */
+export declare function createPairingSession(endpoint: string, userId: string, controllerToken: string, edgeId: string, ttlSeconds?: number): Promise<PairingSession>;
+/**
+ * Register a plugin (edge). Kept for backward compat with edge registration.
+ */
 export declare function registerPlugin(endpoint: string, options: {
     stableIdentity: string;
     displayName?: string;
     adapterKind?: string;
-}): Promise<PluginRecord>;
-export declare function createPairingSession(endpoint: string, options: CreatePairingOptions): Promise<PairingSession>;
-export declare function getPairingSession(endpoint: string, sessionId: string): Promise<PairingSession>;
-export declare function waitForPairingClaim(endpoint: string, sessionId: string, timeoutMs?: number): Promise<PairingSession>;
+}): Promise<{
+    edge_id: string;
+}>;
+/**
+ * Poll pairing session until claimed or expired.
+ */
+export declare function waitForPairingClaim(endpoint: string, userId: string, controllerToken: string, sessionId: string, timeoutMs?: number): Promise<void>;
 export declare function renderPairingQRCode(url: string): Promise<string>;
 /**
- * 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 declare function executePairing(endpoint: string, edgeId: string, preferredLabel?: string): Promise<{
-    session: PairingSession;
-    record: DeviceRecord;
+export declare function executePairingNewUser(preferredLabel?: string): Promise<{
+    userRecord: UserRecord;
+    deviceRecord: DeviceRecord;
 }>;
-export declare function formatPairingStatus(record: DeviceRecord | null): string;
+/**
+ * Add device to existing user: create pairing session → wait → fetch new credential → save.
+ */
+export declare function executePairingAddDevice(userId: string, preferredLabel?: string): Promise<DeviceRecord>;
+/**
+ * Legacy: format pairing status (kept for backward compat).
+ */
+export declare function formatPairingStatus(userId: string | null): string;