@workclaw/openclaw-workchat 1.0.0 → 1.0.4

package/src/auth/login-qr.ts

@@ -1,475 +1,477 @@
-import fs from "node:fs";
-import os from "node:os";
-
-import type { WorkChatApiOptions } from "../api/api.js";
-import { logger } from "../util/logger.js";
-
-/**
- * bind-hardware QR payload — the plugin builds it locally (no platform call):
- * the user scans it with the WorkChat app, which registers this device and
- * pushes an INIT_AGENT event down the WebSocket to bind the agent.
- *
- * Fixed fields: cmd / type / name. Everything else is read live from the host.
- */
-export type BindHardwarePayload = {
-  cmd: "bind-hardware";
-  data: {
-    type: string;
-    name: string;
-    serial_number: string;
-    product_model: string;
-    main_processor: string;
-    memory: string;
-    /** Storage capacity. The field name is protocol-fixed (eMMC on embedded
-     *  devices); on desktops it carries the system disk size. */
-    emmc: string;
-    system: string;
-    app_key: string;
-  };
-};
-
-/** Fixed values for this product line. */
-const BIND_CMD = "bind-hardware" as const;
-const BIND_TYPE = "99";
-const BIND_NAME = "WorkClaw 桌面端";
-
-function readCpuModel(): string {
-  try {
-    const cpus = os.cpus();
-    if (cpus.length > 0 && cpus[0]?.model?.trim()) {
-      return cpus[0].model.trim();
-    }
-  } catch {
-    // ignore
-  }
-  return "unknown";
-}
-
-function readTotalMemory(): string {
-  try {
-    const gb = os.totalmem() / 1024 / 1024 / 1024;
-    return `${Math.max(1, Math.round(gb))}GB`;
-  } catch {
-    return "unknown";
-  }
-}
-
-/**
- * Read the storage capacity of the volume backing the current working
- * directory (the system disk on typical installs) via fs.statfs.
- * Returns the total capacity, not free space.
- */
-function readStorageSize(): string {
-  try {
-    const st = fs.statfsSync(process.cwd());
-    const totalBytes = Number(st.blocks) * Number(st.bsize);
-    if (!Number.isFinite(totalBytes) || totalBytes <= 0) return "unknown";
-    const gb = totalBytes / 1024 / 1024 / 1024;
-    return `${Math.max(1, Math.round(gb))}GB`;
-  } catch {
-    return "unknown";
-  }
-}
-
-function readPlatform(): string {
-  return `${os.type()} ${os.release()} ${os.arch()}`.trim() || "unknown";
-}
-
-/**
- * Build the bind-hardware QR content from live host info.
- * `appKey` comes from the channel config (already injected via
- * ${WORKCHAT_API_KEY}); the renderer encodes this JSON string into the QR.
- */
-export function buildBindHardwarePayload(params: {
-  appKey: string;
-  serialNumber: string;
-  productModel?: string;
-  storageSize?: string;
-}): BindHardwarePayload {
-  return {
-    cmd: BIND_CMD,
-    data: {
-      type: BIND_TYPE,
-      name: BIND_NAME,
-      serial_number: params.serialNumber,
-      product_model: params.productModel || "WorkClaw Desktop",
-      main_processor: readCpuModel(),
-      memory: readTotalMemory(),
-      // 协议字段名固定为 emmc（协议来自嵌入式设备的 eMMC 存储），
-      // 桌面端语义上是系统磁盘总容量；调用方可覆盖，默认自动探测。
-      emmc: params.storageSize || readStorageSize(),
-      system: readPlatform(),
-      app_key: params.appKey,
-    },
-  };
-}
-
-/**
- * Serialize the payload for QR encoding.
- * Per the platform contract the JSON is base64-encoded (UTF-8) before it is
- * painted into the QR — the WorkChat app decodes base64, then parses the JSON.
- */
-export function buildBindHardwareQrContent(params: {
-  appKey: string;
-  serialNumber: string;
-  productModel?: string;
-  storageSize?: string;
-}): string {
-  const json = JSON.stringify(buildBindHardwarePayload(params));
-  return Buffer.from(json, "utf8").toString("base64");
-}
-
-type ActiveBinding = {
-  sessionKey: string;
-  qrContent: string;
-  opts: WorkChatApiOptions;
-  startedAt: number;
-};
-
-const ACTIVE_BINDING_TTL_MS = 10 * 60_000;
-
-const activeBindings = new Map<string, ActiveBinding>();
-
-function isBindingFresh(binding: ActiveBinding): boolean {
-  return Date.now() - binding.startedAt < ACTIVE_BINDING_TTL_MS;
-}
-
-/** Remove expired entries from activeBindings to prevent memory leaks. */
-function purgeExpiredBindings(): void {
-  for (const [id, binding] of activeBindings) {
-    if (!isBindingFresh(binding)) {
-      activeBindings.delete(id);
-    }
-  }
-}
-
-export type WorkChatQrStartResult = {
-  qrcodeUrl?: string;
-  sessionKey?: string;
-  message: string;
-};
-
-export type WorkChatQrWaitResult = {
-  connected: boolean;
-  message: string;
-  accountId?: string;
-  agentId?: string;
-};
-
-/**
- * Build the binding QR locally.
- *
- * Unlike Weixin, no platform call is needed to fetch a QR: the plugin
- * assembles the bind-hardware JSON (device info + this user's app_key), the
- * renderer paints it as a QR, and the WorkChat app scanning it pushes an
- * INIT_AGENT event down the WebSocket which completes the binding.
- */
-export async function startWorkChatLoginWithQr(opts: WorkChatApiOptions): Promise<WorkChatQrStartResult> {
-  purgeExpiredBindings();
-
-  if (!opts.appKey) {
-    return { message: "workchat: missing appKey (WORKCHAT_API_KEY 未注入，请先在桌面端登录)" };
-  }
-
-  try {
-    const qrContent = buildBindHardwareQrContent({
-      appKey: opts.appKey,
-      // Machine identity: hostname + MAC makes a stable per-device serial.
-      serialNumber: buildDeviceSerial(),
-    });
-    const sessionKey = `bind-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-    activeBindings.set(sessionKey, { sessionKey, qrContent, opts, startedAt: Date.now() });
-    logger.info(
-      `binding QR built locally appKey=${opts.appKey.slice(0, 8)}… serialLen=${buildDeviceSerial().length}`,
-    );
-    return {
-      qrcodeUrl: qrContent,
-      sessionKey,
-      message: "请使用 WorkChat 扫描二维码完成智能体绑定",
-    };
-  } catch (err) {
-    logger.error(`startWorkChatLoginWithQr failed: ${String(err)}`);
-    return { message: String(err) };
-  }
-}
-
-function buildDeviceSerial(): string {
-  const nets = os.networkInterfaces();
-  let mac = "";
-  for (const list of Object.values(nets)) {
-    const hit = list?.find(n => n && !n.internal && n.mac && n.mac !== "00:00:00:00:00:00");
-    if (hit?.mac) {
-      mac = hit.mac;
-      break;
-    }
-  }
-  const raw = `${os.hostname()}|${mac}`;
-  // Simple non-crypto hash to a fixed-width hex serial (stable per device,
-  // avoids leaking the hostname/MAC into the QR payload).
-  let h1 = 0x811c9dc5;
-  let h2 = 0x01000193;
-  for (let i = 0; i < raw.length; i++) {
-    h1 = (h1 ^ raw.charCodeAt(i)) * 0x01000193 >>> 0;
-    h2 = (h2 + raw.charCodeAt(i) * (i + 1)) >>> 0;
-  }
-  return `WC-${h1.toString(16).padStart(8, "0")}${h2.toString(16).padStart(8, "0")}`.toUpperCase();
-}
-
-// ---------------------------------------------------------------------------
-// Binding completion — signaled by the WebSocket INIT_AGENT event
-// ---------------------------------------------------------------------------
-
-export type BindingCompletion = {
-  accountId: string;
-  agentId: string;
-  userId?: string;
-};
-
-const pendingWaiters = new Map<string, (completion: BindingCompletion) => void>();
-
-/**
- * Wait for the binding scan completion.
- *
- * There is no HTTP polling: after the user scans, the WorkChat platform
- * pushes an INIT_AGENT event down a WebSocket. The gateway's web.login flow
- * stops the channel before login starts (force), so the plugin's regular
- * monitor cannot be the listener — instead this wait opens its own
- * short-lived binding-listener WebSocket (same credentials), handles the
- * INIT_AGENT frame (persist account + bind agent), resolves, and closes.
- * The monitor's own INIT_AGENT handling remains as a second path.
- */
-export async function waitForWorkChatLogin(params: {
-  sessionKey?: string;
-  opts?: WorkChatApiOptions;
-  timeoutMs?: number;
-}): Promise<WorkChatQrWaitResult> {
-  const sessionKey = params.sessionKey?.trim();
-  if (!sessionKey) {
-    return { connected: false, message: "workchat: no pending binding session" };
-  }
-
-  const binding = activeBindings.get(sessionKey);
-  if (!binding || !isBindingFresh(binding)) {
-    activeBindings.delete(sessionKey);
-    return { connected: false, message: "绑定二维码已过期，请重新获取" };
-  }
-
-  const opts = params.opts ?? binding.opts;
-  const timeoutMs = params.timeoutMs && params.timeoutMs > 0 ? params.timeoutMs : 8 * 60_000;
-
-  // Own the completion: register the waiter and run the binding listener.
-  const completionPromise = waitForCompletion(sessionKey);
-  startBindingListener(sessionKey, opts, timeoutMs);
-  const timeoutPromise = new Promise<BindingCompletion | null>(resolve =>
-    setTimeout(() => resolve(null), timeoutMs).unref?.());
-
-  const completion = await Promise.race([completionPromise, timeoutPromise]);
-
-  stopBindingListener(sessionKey);
-  pendingWaiters.delete(sessionKey);
-
-  if (!completion) {
-    activeBindings.delete(sessionKey);
-    return { connected: false, message: "绑定二维码已过期，请重新获取" };
-  }
-
-  activeBindings.delete(sessionKey);
-  return {
-    connected: true,
-    message: "WorkChat 绑定成功",
-    accountId: completion.accountId,
-    agentId: completion.agentId,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Binding listener — a dedicated WebSocket for the wait window
-// ---------------------------------------------------------------------------
-
-import { Agent, WebSocket } from "undici";
-import { openConnection, clearWorkChatTokenCache } from "../api/api.js";
-import { parseWorkChatFrame } from "../messaging/inbound.js";
-import { buildPongFrame } from "../messaging/inbound.js";
-import {
-  saveWorkChatAccount,
-  registerWorkChatAccountId,
-  listIndexedWorkChatAccountIds,
-} from "./accounts.js";
-
-const bindingListeners = new Map<string, { ws: WebSocket; done: boolean }>();
-
-/**
- * Open a dedicated WebSocket for the binding wait window. Reconnects until
- * the wait resolves or times out; the INIT_AGENT frame completes the binding
- * (account persisted + agent bound into openclaw.json) and wakes the waiter.
- */
-function startBindingListener(
-  sessionKey: string,
-  opts: WorkChatApiOptions,
-  timeoutMs: number,
-): void {
-  const deadline = Date.now() + timeoutMs;
-  let backoffMs = 2_000;
-
-  const attempt = (): void => {
-    if (Date.now() > deadline) return;
-    const entry = bindingListeners.get(sessionKey);
-    if (!entry || entry.done) return;
-
-    void (async () => {
-      let ws: WebSocket | null = null;
-      try {
-        clearWorkChatTokenCache(opts.appKey || "default");
-        const { endpoint, ticket } = await openConnection(opts);
-        const url = `${endpoint}?ticket=${encodeURIComponent(ticket)}`;
-        const dispatcher = opts.allowInsecureTls
-          ? new Agent({ connect: { rejectUnauthorized: false } })
-          : undefined;
-        ws = new WebSocket(url, dispatcher ? { dispatcher } : undefined);
-        const entryNow = bindingListeners.get(sessionKey);
-        if (!entryNow || entryNow.done) {
-          try { ws.close(); } catch { /* ignore */ }
-          return;
-        }
-        entryNow.ws = ws;
-
-        await new Promise<void>((resolve, reject) => {
-          const timer = setTimeout(() => reject(new Error("binding listener ws timeout")), 30_000);
-          ws!.onopen = () => { clearTimeout(timer); resolve(); };
-          ws!.onerror = (e: unknown) => { clearTimeout(timer); reject(new Error(String((e as any)?.message ?? e))); };
-          ws!.onclose = (e: unknown) => { clearTimeout(timer); reject(new Error(`binding listener closed code=${String((e as any)?.code ?? "")}`)); };
-        });
-
-        logger.info("binding listener WebSocket connected");
-        backoffMs = 2_000;
-
-        ws.onmessage = (event: unknown) => {
-          const data = typeof (event as any).data === "string"
-            ? (event as any).data
-            : String((event as any).data ?? "");
-          void handleListenerFrame(sessionKey, data, ws);
-        };
-        ws.onclose = () => {
-          // Reconnect while the wait window is open.
-          const e = bindingListeners.get(sessionKey);
-          if (e && !e.done) setTimeout(attempt, backoffMs);
-        };
-        ws.onerror = (e: unknown) => {
-          logger.warn(`binding listener ws error: ${String((e as any)?.message ?? e)}`);
-        };
-      } catch (err) {
-        const errorStr = String(err);
-        logger.warn(`binding listener connect failed: ${errorStr}`);
-        const e = bindingListeners.get(sessionKey);
-        if (!e || e.done) return;
-        if (errorStr.includes("鉴权失败") || errorStr.includes("missing appKey/appSecret")) {
-          // Credentials wrong — retrying cannot help.
-          return;
-        }
-        backoffMs = Math.min(backoffMs * 2, 60_000);
-        setTimeout(attempt, backoffMs);
-      }
-    })();
-  };
-
-  bindingListeners.set(sessionKey, { ws: null as unknown as WebSocket, done: false });
-  attempt();
-}
-
-async function handleListenerFrame(sessionKey: string, data: string, ws: WebSocket | null): Promise<void> {
-  const result = parseWorkChatFrame(data);
-  if (!result) return;
-
-  if (result.type === "ping") {
-    try { ws?.send(buildPongFrame(result.pongData)); } catch { /* ignore */ }
-    return;
-  }
-  if (result.type !== "init_agent") return;
-
-  const eventData = result.eventData;
-  if (!eventData) return;
-  const agentId = String(eventData.id ?? eventData.agentId ?? "");
-  if (!agentId) return;
-  const userId = String(eventData.futureId ?? eventData.userId ?? "");
-
-  const entry = bindingListeners.get(sessionKey);
-  if (entry) entry.done = true;
-
-  // Rebind detection must happen BEFORE pruning empties the index: if any
-  // account existed, this scan replaces it. The QR login flow force-stops the
-  // channel (marked manually-stopped in the gateway), and a reused account id
-  // would stay stopped after reload — so a rebind always registers under a
-  // FRESH agent-scoped key instead of reusing `default`.
-  const isRebind = listIndexedWorkChatAccountIds().length > 0;
-
-  // Rebind semantics (mirrors handleAgentLifecycleEvent): a re-scan replaces
-  // the previously bound agent, so drop accounts bound to other agentIds
-  // before registering this one.
-  try {
-    const { pruneStaleWorkChatAccounts } = await import("./accounts.js");
-    const removed = await pruneStaleWorkChatAccounts(agentId);
-    if (removed.length > 0) {
-      logger.info(`binding listener: pruned stale account(s): ${removed.join(", ")}`);
-    }
-  } catch (err) {
-    logger.error(`binding listener: rebind cleanup failed: ${String(err)}`);
-  }
-
-  // First bound agent becomes the `default` account; a rebind gets a fresh
-  // agent-scoped key (see isRebind note above).
-  const accountId = isRebind
-    ? `agent-${agentId}`
-    : "default";
-
-  try {
-    saveWorkChatAccount(accountId, {
-      agentId,
-      ...(userId ? { userId } : {}),
-    });
-    registerWorkChatAccountId(accountId);
-    // Bind agent into openclaw.json accounts (routing) — no apiKey ever written.
-    const { bindAgentToAccountFromBinding } = await import("./bind-agent.js");
-    await bindAgentToAccountFromBinding(accountId, agentId, userId);
-    logger.info(`binding listener: account=${accountId} agent=${agentId} persisted`);
-  } catch (err) {
-    logger.error(`binding listener: failed to persist binding err=${String(err)}`);
-  }
-
-  completeWorkChatBinding({
-    accountId,
-    agentId,
-    ...(userId ? { userId } : {}),
-  });
-}
-
-function stopBindingListener(sessionKey: string): void {
-  const entry = bindingListeners.get(sessionKey);
-  if (!entry) return;
-  entry.done = true;
-  try { entry.ws?.close(); } catch { /* ignore */ }
-  bindingListeners.delete(sessionKey);
-}
-
-function waitForCompletion(sessionKey: string): Promise<BindingCompletion> {
-  return new Promise(resolve => {
-    pendingWaiters.set(sessionKey, resolve);
-  });
-}
-
-/**
- * Called by the binding listener / monitor loop when the WebSocket INIT_AGENT
- * frame arrives for a pending binding: resolves the waiting web.login.wait.
- */
-export function completeWorkChatBinding(completion: BindingCompletion): boolean {
-  const sessionKey = pendingWaiters.size > 0
-    ? [...pendingWaiters.keys()][0]
-    : undefined;
-  if (!sessionKey) return false;
-  const resolve = pendingWaiters.get(sessionKey);
-  pendingWaiters.delete(sessionKey);
-  resolve?.(completion);
-  logger.info(
-    `binding completed via INIT_AGENT sessionKey=${sessionKey.slice(0, 12)}… agentId=${completion.agentId}`,
-  );
-  return true;
-}
+import fs from "node:fs";
+import os from "node:os";
+
+import type { WorkChatApiOptions } from "../api/api.js";
+import { logger } from "../util/logger.js";
+
+/**
+ * bind-hardware QR payload — the plugin builds it locally (no platform call):
+ * the user scans it with the WorkChat app, which registers this device and
+ * pushes an INIT_AGENT event down the WebSocket to bind the agent.
+ *
+ * Fixed fields: cmd / type / name. Everything else is read live from the host.
+ */
+export type BindHardwarePayload = {
+  cmd: "bind-hardware";
+  data: {
+    type: string;
+    name: string;
+    serial_number: string;
+    product_model: string;
+    main_processor: string;
+    memory: string;
+    /** Storage capacity. The field name is protocol-fixed (eMMC on embedded
+     *  devices); on desktops it carries the system disk size. */
+    emmc: string;
+    system: string;
+    app_key: string;
+  };
+};
+
+/** Fixed values for this product line. */
+const BIND_CMD = "bind-hardware" as const;
+const BIND_TYPE = "99";
+const BIND_NAME = "WorkClaw 桌面端";
+
+function readCpuModel(): string {
+  try {
+    const cpus = os.cpus();
+    if (cpus.length > 0 && cpus[0]?.model?.trim()) {
+      return cpus[0].model.trim();
+    }
+  } catch {
+    // ignore
+  }
+  return "unknown";
+}
+
+function readTotalMemory(): string {
+  try {
+    const gb = os.totalmem() / 1024 / 1024 / 1024;
+    return `${Math.max(1, Math.round(gb))}GB`;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Read the storage capacity of the volume backing the current working
+ * directory (the system disk on typical installs) via fs.statfs.
+ * Returns the total capacity, not free space.
+ */
+function readStorageSize(): string {
+  try {
+    const st = fs.statfsSync(process.cwd());
+    const totalBytes = Number(st.blocks) * Number(st.bsize);
+    if (!Number.isFinite(totalBytes) || totalBytes <= 0) return "unknown";
+    const gb = totalBytes / 1024 / 1024 / 1024;
+    return `${Math.max(1, Math.round(gb))}GB`;
+  } catch {
+    return "unknown";
+  }
+}
+
+function readPlatform(): string {
+  return `${os.type()} ${os.release()} ${os.arch()}`.trim() || "unknown";
+}
+
+/**
+ * Build the bind-hardware QR content from live host info.
+ * `appKey` comes from the channel config (already injected via
+ * ${WORKCHAT_API_KEY}); the renderer encodes this JSON string into the QR.
+ */
+export function buildBindHardwarePayload(params: {
+  appKey: string;
+  serialNumber: string;
+  productModel?: string;
+  storageSize?: string;
+}): BindHardwarePayload {
+  return {
+    cmd: BIND_CMD,
+    data: {
+      type: BIND_TYPE,
+      name: BIND_NAME,
+      serial_number: params.serialNumber,
+      product_model: params.productModel || "WorkClaw Desktop",
+      main_processor: readCpuModel(),
+      memory: readTotalMemory(),
+      // 协议字段名固定为 emmc（协议来自嵌入式设备的 eMMC 存储），
+      // 桌面端语义上是系统磁盘总容量；调用方可覆盖，默认自动探测。
+      emmc: params.storageSize || readStorageSize(),
+      system: readPlatform(),
+      app_key: params.appKey,
+    },
+  };
+}
+
+/**
+ * Serialize the payload for QR encoding.
+ * Per the platform contract the JSON is base64-encoded (UTF-8) before it is
+ * painted into the QR — the WorkChat app decodes base64, then parses the JSON.
+ */
+export function buildBindHardwareQrContent(params: {
+  appKey: string;
+  serialNumber: string;
+  productModel?: string;
+  storageSize?: string;
+}): string {
+  const json = JSON.stringify(buildBindHardwarePayload(params));
+  return Buffer.from(json, "utf8").toString("base64");
+}
+
+type ActiveBinding = {
+  sessionKey: string;
+  qrContent: string;
+  opts: WorkChatApiOptions;
+  startedAt: number;
+};
+
+const ACTIVE_BINDING_TTL_MS = 10 * 60_000;
+
+const activeBindings = new Map<string, ActiveBinding>();
+
+function isBindingFresh(binding: ActiveBinding): boolean {
+  return Date.now() - binding.startedAt < ACTIVE_BINDING_TTL_MS;
+}
+
+/** Remove expired entries from activeBindings to prevent memory leaks. */
+function purgeExpiredBindings(): void {
+  for (const [id, binding] of activeBindings) {
+    if (!isBindingFresh(binding)) {
+      activeBindings.delete(id);
+    }
+  }
+}
+
+export type WorkChatQrStartResult = {
+  qrcodeUrl?: string;
+  sessionKey?: string;
+  message: string;
+};
+
+export type WorkChatQrWaitResult = {
+  connected: boolean;
+  message: string;
+  accountId?: string;
+  agentId?: string;
+};
+
+/**
+ * Build the binding QR locally.
+ *
+ * Unlike Weixin, no platform call is needed to fetch a QR: the plugin
+ * assembles the bind-hardware JSON (device info + this user's app_key), the
+ * renderer paints it as a QR, and the WorkChat app scanning it pushes an
+ * INIT_AGENT event down the WebSocket which completes the binding.
+ */
+export async function startWorkChatLoginWithQr(opts: WorkChatApiOptions): Promise<WorkChatQrStartResult> {
+  purgeExpiredBindings();
+
+  if (!opts.appKey) {
+    return { message: "workchat: missing appKey (WORKCHAT_API_KEY 未注入，请先在桌面端登录)" };
+  }
+
+  try {
+    const qrContent = buildBindHardwareQrContent({
+      appKey: opts.appKey,
+      // Machine identity: hostname + MAC makes a stable per-device serial.
+      serialNumber: buildDeviceSerial(),
+    });
+    const sessionKey = `bind-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    activeBindings.set(sessionKey, { sessionKey, qrContent, opts, startedAt: Date.now() });
+    logger.info(
+      `binding QR built locally appKey=${opts.appKey.slice(0, 8)}… serialLen=${buildDeviceSerial().length}`,
+    );
+    return {
+      qrcodeUrl: qrContent,
+      sessionKey,
+      message: "请使用 WorkChat 扫描二维码完成智能体绑定",
+    };
+  } catch (err) {
+    logger.error(`startWorkChatLoginWithQr failed: ${String(err)}`);
+    return { message: String(err) };
+  }
+}
+
+function buildDeviceSerial(): string {
+  const nets = os.networkInterfaces();
+  let mac = "";
+  for (const list of Object.values(nets)) {
+    const hit = list?.find(n => n && !n.internal && n.mac && n.mac !== "00:00:00:00:00:00");
+    if (hit?.mac) {
+      mac = hit.mac;
+      break;
+    }
+  }
+  const raw = `${os.hostname()}|${mac}`;
+  // Simple non-crypto hash to a fixed-width hex serial (stable per device,
+  // avoids leaking the hostname/MAC into the QR payload).
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  for (let i = 0; i < raw.length; i++) {
+    h1 = (h1 ^ raw.charCodeAt(i)) * 0x01000193 >>> 0;
+    h2 = (h2 + raw.charCodeAt(i) * (i + 1)) >>> 0;
+  }
+  return `WC-${h1.toString(16).padStart(8, "0")}${h2.toString(16).padStart(8, "0")}`.toUpperCase();
+}
+
+// ---------------------------------------------------------------------------
+// Binding completion — signaled by the WebSocket INIT_AGENT event
+// ---------------------------------------------------------------------------
+
+export type BindingCompletion = {
+  accountId: string;
+  agentId: string;
+  userId?: string;
+};
+
+const pendingWaiters = new Map<string, (completion: BindingCompletion) => void>();
+
+/**
+ * Wait for the binding scan completion.
+ *
+ * There is no HTTP polling: after the user scans, the WorkChat platform
+ * pushes an INIT_AGENT event down a WebSocket. The gateway's web.login flow
+ * stops the channel before login starts (force), so the plugin's regular
+ * monitor cannot be the listener — instead this wait opens its own
+ * short-lived binding-listener WebSocket (same credentials), handles the
+ * INIT_AGENT frame (persist account + bind agent), resolves, and closes.
+ * The monitor's own INIT_AGENT handling remains as a second path.
+ */
+export async function waitForWorkChatLogin(params: {
+  sessionKey?: string;
+  opts?: WorkChatApiOptions;
+  timeoutMs?: number;
+}): Promise<WorkChatQrWaitResult> {
+  const sessionKey = params.sessionKey?.trim();
+  if (!sessionKey) {
+    return { connected: false, message: "workchat: no pending binding session" };
+  }
+
+  const binding = activeBindings.get(sessionKey);
+  if (!binding || !isBindingFresh(binding)) {
+    activeBindings.delete(sessionKey);
+    return { connected: false, message: "绑定二维码已过期，请重新获取" };
+  }
+
+  const opts = params.opts ?? binding.opts;
+  const timeoutMs = params.timeoutMs && params.timeoutMs > 0 ? params.timeoutMs : 8 * 60_000;
+
+  // Own the completion: register the waiter and run the binding listener.
+  const completionPromise = waitForCompletion(sessionKey);
+  startBindingListener(sessionKey, opts, timeoutMs);
+  const timeoutPromise = new Promise<BindingCompletion | null>(resolve =>
+    setTimeout(() => resolve(null), timeoutMs).unref?.());
+
+  const completion = await Promise.race([completionPromise, timeoutPromise]);
+
+  stopBindingListener(sessionKey);
+  pendingWaiters.delete(sessionKey);
+
+  if (!completion) {
+    activeBindings.delete(sessionKey);
+    return { connected: false, message: "绑定二维码已过期，请重新获取" };
+  }
+
+  activeBindings.delete(sessionKey);
+  return {
+    connected: true,
+    message: "WorkChat 绑定成功",
+    accountId: completion.accountId,
+    agentId: completion.agentId,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Binding listener — a dedicated WebSocket for the wait window
+// ---------------------------------------------------------------------------
+
+import { Agent, WebSocket } from "undici";
+import { openConnection, clearWorkChatTokenCache } from "../api/api.js";
+import { parseWorkChatFrame } from "../messaging/inbound.js";
+import { buildPongFrame } from "../messaging/inbound.js";
+import {
+  saveWorkChatAccount,
+  registerWorkChatAccountId,
+  listIndexedWorkChatAccountIds,
+} from "./accounts.js";
+
+const bindingListeners = new Map<string, { ws: WebSocket; done: boolean }>();
+
+/**
+ * Open a dedicated WebSocket for the binding wait window. Reconnects until
+ * the wait resolves or times out; the INIT_AGENT frame completes the binding
+ * (account persisted + agent bound into openclaw.json) and wakes the waiter.
+ */
+function startBindingListener(
+  sessionKey: string,
+  opts: WorkChatApiOptions,
+  timeoutMs: number,
+): void {
+  const deadline = Date.now() + timeoutMs;
+  let backoffMs = 2_000;
+
+  const attempt = (): void => {
+    if (Date.now() > deadline) return;
+    const entry = bindingListeners.get(sessionKey);
+    if (!entry || entry.done) return;
+
+    void (async () => {
+      let ws: WebSocket | null = null;
+      try {
+        clearWorkChatTokenCache(opts.appKey || "default");
+        const { endpoint, ticket } = await openConnection(opts);
+        const url = `${endpoint}?ticket=${encodeURIComponent(ticket)}`;
+        const dispatcher = opts.allowInsecureTls
+          ? new Agent({ connect: { rejectUnauthorized: false } })
+          : undefined;
+        ws = new WebSocket(url, dispatcher ? { dispatcher } : undefined);
+        const entryNow = bindingListeners.get(sessionKey);
+        if (!entryNow || entryNow.done) {
+          try { ws.close(); } catch { /* ignore */ }
+          return;
+        }
+        entryNow.ws = ws;
+
+        await new Promise<void>((resolve, reject) => {
+          const timer = setTimeout(() => reject(new Error("binding listener ws timeout")), 30_000);
+          ws!.onopen = () => { clearTimeout(timer); resolve(); };
+          ws!.onerror = (e: unknown) => { clearTimeout(timer); reject(new Error(String((e as any)?.message ?? e))); };
+          ws!.onclose = (e: unknown) => { clearTimeout(timer); reject(new Error(`binding listener closed code=${String((e as any)?.code ?? "")}`)); };
+        });
+
+        logger.info("binding listener WebSocket connected");
+        backoffMs = 2_000;
+
+        ws.onmessage = (event: unknown) => {
+          const data = typeof (event as any).data === "string"
+            ? (event as any).data
+            : String((event as any).data ?? "");
+          void handleListenerFrame(sessionKey, data, ws);
+        };
+        ws.onclose = () => {
+          // Reconnect while the wait window is open.
+          const e = bindingListeners.get(sessionKey);
+          if (e && !e.done) setTimeout(attempt, backoffMs);
+        };
+        ws.onerror = (e: unknown) => {
+          logger.warn(`binding listener ws error: ${String((e as any)?.message ?? e)}`);
+        };
+      } catch (err) {
+        const errorStr = String(err);
+        logger.warn(`binding listener connect failed: ${errorStr}`);
+        const e = bindingListeners.get(sessionKey);
+        if (!e || e.done) return;
+        if (errorStr.includes("鉴权失败") || errorStr.includes("missing appKey/appSecret")) {
+          // Credentials wrong — retrying cannot help.
+          return;
+        }
+        backoffMs = Math.min(backoffMs * 2, 60_000);
+        setTimeout(attempt, backoffMs);
+      }
+    })();
+  };
+
+  bindingListeners.set(sessionKey, { ws: null as unknown as WebSocket, done: false });
+  attempt();
+}
+
+async function handleListenerFrame(sessionKey: string, data: string, ws: WebSocket | null): Promise<void> {
+  const result = parseWorkChatFrame(data);
+  if (!result) return;
+
+  if (result.type === "ping") {
+    try { ws?.send(buildPongFrame(result.pongData)); } catch { /* ignore */ }
+    return;
+  }
+  if (result.type !== "init_agent") return;
+
+  const eventData = result.eventData;
+  if (!eventData) return;
+  const agentId = String(eventData.id ?? eventData.agentId ?? "");
+  if (!agentId) return;
+  const userId = String(eventData.futureId ?? eventData.userId ?? "");
+
+  const entry = bindingListeners.get(sessionKey);
+  if (entry) entry.done = true;
+
+  // Rebind detection must happen BEFORE pruning empties the index: if any
+  // account existed, this scan replaces it. The QR login flow force-stops the
+  // channel (marked manually-stopped in the gateway), and a reused account id
+  // would stay stopped after reload — so a rebind always registers under a
+  // FRESH agent-scoped key instead of reusing `default`.
+  const isRebind = listIndexedWorkChatAccountIds().length > 0;
+
+  // Rebind semantics (mirrors handleAgentLifecycleEvent): a re-scan replaces
+  // the previously bound agent, so drop accounts bound to other agentIds
+  // before registering this one.
+  try {
+    const { pruneStaleWorkChatAccounts } = await import("./accounts.js");
+    const removed = await pruneStaleWorkChatAccounts(agentId);
+    if (removed.length > 0) {
+      logger.info(`binding listener: pruned stale account(s): ${removed.join(", ")}`);
+    }
+  } catch (err) {
+    logger.error(`binding listener: rebind cleanup failed: ${String(err)}`);
+  }
+
+  // First bound agent becomes the `default` account; a rebind gets a fresh
+  // agent-scoped key (see isRebind note above).
+  const accountId = isRebind
+    ? `agent-${agentId}`
+    : "default";
+
+  try {
+    saveWorkChatAccount(accountId, {
+      agentId,
+      ...(userId ? { userId } : {}),
+    });
+    registerWorkChatAccountId(accountId);
+    // Complete the binding: account data is already in the private state
+    // dir; this call registers the allowFrom user and triggers the channel
+    // hot reload.
+    const { bindAgentToAccountFromBinding } = await import("./bind-agent.js");
+    await bindAgentToAccountFromBinding(accountId, agentId, userId);
+    logger.info(`binding listener: account=${accountId} agent=${agentId} persisted`);
+  } catch (err) {
+    logger.error(`binding listener: failed to persist binding err=${String(err)}`);
+  }
+
+  completeWorkChatBinding({
+    accountId,
+    agentId,
+    ...(userId ? { userId } : {}),
+  });
+}
+
+function stopBindingListener(sessionKey: string): void {
+  const entry = bindingListeners.get(sessionKey);
+  if (!entry) return;
+  entry.done = true;
+  try { entry.ws?.close(); } catch { /* ignore */ }
+  bindingListeners.delete(sessionKey);
+}
+
+function waitForCompletion(sessionKey: string): Promise<BindingCompletion> {
+  return new Promise(resolve => {
+    pendingWaiters.set(sessionKey, resolve);
+  });
+}
+
+/**
+ * Called by the binding listener / monitor loop when the WebSocket INIT_AGENT
+ * frame arrives for a pending binding: resolves the waiting web.login.wait.
+ */
+export function completeWorkChatBinding(completion: BindingCompletion): boolean {
+  const sessionKey = pendingWaiters.size > 0
+    ? [...pendingWaiters.keys()][0]
+    : undefined;
+  if (!sessionKey) return false;
+  const resolve = pendingWaiters.get(sessionKey);
+  pendingWaiters.delete(sessionKey);
+  resolve?.(completion);
+  logger.info(
+    `binding completed via INIT_AGENT sessionKey=${sessionKey.slice(0, 12)}… agentId=${completion.agentId}`,
+  );
+  return true;
+}