feishu-user-plugin 1.3.7 → 1.3.8

package/src/clients/official/base.js

@@ -1,6 +1,7 @@
 const lark = require('@larksuiteoapi/node-sdk');
 const { fetchWithTimeout } = require('../../utils');
 const { stderrLogger } = require('../../logger');
+const uatLifecycle = require('../../auth/uat');
 
 class LarkOfficialClient {
   constructor(appId, appSecret) {
@@ -74,254 +75,17 @@ class LarkOfficialClient {
     }
   }
 
-  async _getValidUAT() {
-    if (!this._uat) throw new Error('No user_access_token. Run: npx feishu-user-plugin oauth');
-
-    const now = Math.floor(Date.now() / 1000);
-    if (!this._uatExpires) this._uatExpires = this._decodeTokenExpiry(this._uat);
-    // Proactively refresh if we know it's expiring within 5 min
-    if (this._uatExpires > 0 && this._uatExpires <= now + 300) {
-      return this._refreshUAT();
-    }
-    return this._uat;
-  }
-
-  _decodeTokenExpiry(token) {
-    try {
-      const payload = token?.split('.')?.[1];
-      if (!payload) return 0;
-      const data = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
-      return typeof data.exp === 'number' ? data.exp : 0;
-    } catch (_) {
-      return 0;
-    }
-  }
-
-  _adoptPersistedUATIfNewer() {
-    try {
-      // auth/credentials reads credentials.json first; falls back to legacy
-      // mcpServers. The peer-rotated UAT will land wherever persistUAT wrote,
-      // and we'll see it consistently.
-      const { readCredentials } = require('../../auth/credentials');
-      const creds = readCredentials();
-      const token = creds.LARK_USER_ACCESS_TOKEN;
-      const refresh = creds.LARK_USER_REFRESH_TOKEN;
-      if (!token && !refresh) return false;
-
-      const expires = parseInt(creds.LARK_UAT_EXPIRES || '0') || this._decodeTokenExpiry(token);
-      const changed = (token && token !== this._uat)
-        || (refresh && refresh !== this._uatRefresh)
-        || (expires && expires !== this._uatExpires);
-      if (!changed) return false;
-
-      if (token) this._uat = token;
-      if (refresh) this._uatRefresh = refresh;
-      this._uatExpires = expires || 0;
-      console.error('[feishu-user-plugin] UAT adopted latest persisted token before refresh');
-      return true;
-    } catch (e) {
-      console.error(`[feishu-user-plugin] UAT persisted-token check failed: ${e.message}`);
-      return false;
-    }
-  }
-
-  // Cross-process advisory lock for UAT refresh. Feishu rotates the refresh_token
-  // on every refresh (old one invalidated instantly). When multiple MCP server
-  // processes share the same persisted refresh_token and all wake up near expiry,
-  // they race: the first wins, the rest see `invalid_grant` and can't recover.
-  // This lock serialises refreshes across processes; inside the critical section
-  // we also re-read the persisted config so late arrivals adopt the winner's
-  // token instead of attempting a doomed refresh with the already-rotated one.
-  _uatLockPath() {
-    const path = require('path');
-    const os = require('os');
-    return path.join(os.homedir(), '.claude', 'feishu-uat-refresh.lock');
-  }
-
-  async _acquireRefreshLock(lockPath, { staleMs = 30000, pollMs = 200, timeoutMs = 20000 } = {}) {
-    const fs = require('fs');
-    const path = require('path');
-    try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch (_) {}
-    const start = Date.now();
-    while (Date.now() - start < timeoutMs) {
-      try {
-        const fd = fs.openSync(lockPath, 'wx'); // O_CREAT | O_EXCL
-        fs.writeSync(fd, `${process.pid}\n${Date.now()}\n`);
-        fs.closeSync(fd);
-        return true;
-      } catch (e) {
-        if (e.code !== 'EEXIST') throw e;
-        try {
-          const stat = fs.statSync(lockPath);
-          if (Date.now() - stat.mtimeMs > staleMs) {
-            try { fs.unlinkSync(lockPath); } catch (_) {}
-            continue;
-          }
-        } catch (_) { /* lock vanished under us — retry */ }
-        await new Promise(r => setTimeout(r, pollMs));
-      }
-    }
-    return false;
-  }
-
-  _releaseRefreshLock(lockPath) {
-    try { require('fs').unlinkSync(lockPath); } catch (_) {}
-  }
-
-  async _refreshUAT() {
-    const lockPath = this._uatLockPath();
-    const acquired = await this._acquireRefreshLock(lockPath);
-    if (!acquired) {
-      console.error('[feishu-user-plugin] UAT refresh lock timed out; proceeding without mutual exclusion');
-    }
-    try {
-      // Re-check under lock: another process may have already refreshed and
-      // persisted a new token while we waited. If so, adopt and skip the refresh.
-      const now = Math.floor(Date.now() / 1000);
-      if (this._adoptPersistedUATIfNewer() && this._uatExpires > now + 300) {
-        return this._uat;
-      }
-
-      if (!this._uatRefresh) throw new Error('UAT expired and no refresh token. Run: npx feishu-user-plugin oauth');
-
-      const res = await fetchWithTimeout('https://open.feishu.cn/open-apis/authen/v2/oauth/token', {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          grant_type: 'refresh_token',
-          client_id: this.appId,
-          client_secret: this.appSecret,
-          refresh_token: this._uatRefresh,
-        }),
-      });
-      const data = await res.json();
-      const tokenData = data.access_token ? data : data.data;
-      if (!tokenData?.access_token) throw new Error(`UAT refresh failed: ${JSON.stringify(data)}. Run: npx feishu-user-plugin oauth`);
-
-      this._uat = tokenData.access_token;
-      this._uatRefresh = tokenData.refresh_token || this._uatRefresh;
-      const expiresIn = typeof tokenData.expires_in === 'number' && tokenData.expires_in > 0 ? tokenData.expires_in : 7200;
-      this._uatExpires = Math.floor(Date.now() / 1000) + expiresIn;
-      this._persistUAT();
-      console.error('[feishu-user-plugin] UAT refreshed successfully');
-      return this._uat;
-    } finally {
-      if (acquired) this._releaseRefreshLock(lockPath);
-    }
-  }
-
-  _persistUAT() {
-    // Lazy require to avoid circular dependency at module load time.
-    // auth/credentials writes to credentials.json when it exists, otherwise
-    // falls back to legacy mcpServers persistence — same call site, two
-    // outcomes, same end result for callers.
-    const { persistToConfig } = require('../../auth/credentials');
-    persistToConfig({
-      LARK_USER_ACCESS_TOKEN: this._uat,
-      LARK_USER_REFRESH_TOKEN: this._uatRefresh,
-      LARK_UAT_EXPIRES: String(this._uatExpires),
-    });
-  }
-
-  // --- UAT-based IM operations (for P2P chats) ---
-
-  // Wrapper: call fn with UAT, retry once after refresh if auth fails
-  async _withUAT(fn) {
-    let uat = await this._getValidUAT();
-    const data = await fn(uat);
-    // Known auth error codes: 99991668 (invalid), 99991663 (expired), 99991677 (auth_expired)
-    if (data.code === 99991668 || data.code === 99991663 || data.code === 99991677) {
-      // 99991668 is overloaded: "invalid token" (→ refresh helps) vs
-      // "endpoint doesn't support UAT at all" (→ refresh is pointless, and
-      // worse, it consumes a one-shot refresh_token rotation). The second
-      // case is identifiable by the msg "user access token not support" or
-      // "not support". If so, surface the code to the caller without refresh.
-      if (data.code === 99991668 && typeof data.msg === 'string' && /not support/i.test(data.msg)) {
-        return data;
-      }
-      // Token invalid/expired — try refresh once
-      uat = await this._refreshUAT();
-      return fn(uat);
-    }
-    return data;
-  }
-
-  // Generic UAT REST helper. Returns parsed JSON ({code, msg, data}).
-  // Array query values are expanded to repeated keys (period_ids=a&period_ids=b)
-  // because several Feishu endpoints (OKR, calendar) rely on that convention.
-  async _uatREST(method, path, { body, query } = {}) {
-    let qs = '';
-    if (query) {
-      const sp = new URLSearchParams();
-      for (const [k, v] of Object.entries(query)) {
-        if (v === undefined || v === null) continue;
-        if (Array.isArray(v)) { for (const item of v) sp.append(k, String(item)); }
-        else sp.append(k, String(v));
-      }
-      const str = sp.toString();
-      if (str) qs = '?' + str;
-    }
-    const url = 'https://open.feishu.cn' + path + qs;
-    return this._withUAT(async (uat) => {
-      const headers = { 'Authorization': `Bearer ${uat}` };
-      const init = { method, headers };
-      if (body !== undefined) {
-        headers['content-type'] = 'application/json';
-        init.body = JSON.stringify(body);
-      }
-      const res = await fetchWithTimeout(url, init);
-      return res.json();
-    });
-  }
-
-  // Try UAT first (for resources likely owned by the user), fall back to app SDK on failure.
-  // Returns SDK-shaped {code, msg, data, _viaUser}. _viaUser is true iff the UAT call succeeded;
-  // callers can surface this to distinguish "created by user" vs "created by app" for resources
-  // whose ownership matters (docs, bitables, folders).
-  //
-  // When BOTH paths fail (common for OKR/Calendar if neither UAT nor app has the scope),
-  // the final error includes the UAT-side reason too, so the user can tell whether they
-  // need a new OAuth (UAT missing scope) or a different app (app missing scope).
-  async _asUserOrApp({ uatPath, method = 'GET', body, query, sdkFn, label }) {
-    let uatSummary = null;
-    if (this.hasUAT) {
-      try {
-        const data = await this._uatREST(method, uatPath, { body, query });
-        if (data.code === 0) {
-          data._viaUser = true;
-          return data;
-        }
-        uatSummary = `as user: code=${data.code} msg=${data.msg}`;
-        console.error(`[feishu-user-plugin] ${label} ${uatSummary}, retrying as app`);
-      } catch (err) {
-        uatSummary = `as user: ${err.message}`;
-        console.error(`[feishu-user-plugin] ${label} as user threw (${err.message}), retrying as app`);
-      }
-    }
-    try {
-      const appData = await this._safeSDKCall(sdkFn, label);
-      if (appData && typeof appData === 'object') {
-        appData._viaUser = false;
-        // Attach a warning when we silently fell back to bot identity. This lets
-        // write handlers surface "⚠️ created as BOT, not you" so the user doesn't
-        // discover it days later when a teammate can read the "private" resource.
-        if (uatSummary) {
-          appData._fallbackWarning = `⚠️  UAT 不可用 (${uatSummary}),本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。恢复方法:运行 \`npx feishu-user-plugin oauth\` 后重启 Claude Code / Codex。`;
-        } else if (!this.hasUAT) {
-          appData._fallbackWarning = `⚠️  未配置 UAT,本次操作以 bot 身份执行。资源归属于共享 bot「Claude聊天助手」,不是你。想让资源归你所有,先跑 \`npx feishu-user-plugin oauth\` 然后重启 Claude Code / Codex。`;
-        }
-      }
-      return appData;
-    } catch (appErr) {
-      if (uatSummary) {
-        const err = new Error(`${label} failed on both identities. ${uatSummary}. as app: ${appErr.message}`);
-        err.uatSummary = uatSummary;
-        err.appError = appErr;
-        throw err;
-      }
-      throw appErr;
-    }
-  }
+  // UAT lifecycle methods are extracted to src/auth/uat.js (v1.3.8 D.1).
+  // State (this._uat / this._uatRefresh / this._uatExpires) still lives here;
+  // function bodies live in auth/uat.js. These methods are 1-line delegates.
+  _decodeTokenExpiry(token)            { return uatLifecycle.decodeTokenExpiry(token); }
+  async _getValidUAT()                 { return uatLifecycle.getValidUAT(this); }
+  _adoptPersistedUATIfNewer()          { return uatLifecycle.adoptPersistedUATIfNewer(this); }
+  async _refreshUAT()                  { return uatLifecycle.refreshUAT(this); }
+  _persistUAT()                        { return uatLifecycle.persistUAT(this); }
+  async _withUAT(fn)                   { return uatLifecycle.withUAT(this, fn); }
+  async _uatREST(method, path, opts)   { return uatLifecycle.uatREST(this, method, path, opts); }
+  async _asUserOrApp(opts)             { return uatLifecycle.asUserOrApp(this, opts); }
 
   // --- Safe SDK Call (extracts real Feishu error from AxiosError) ---
 

package/src/clients/user.js

@@ -1,6 +1,7 @@
 const path = require('path');
 const protobuf = require('protobufjs');
 const { generateRequestId, generateCid, parseCookie, formatCookie, fetchWithTimeout } = require('../utils');
+const cookieHeartbeat = require('../auth/cookie');
 
 const GATEWAY_URL = 'https://internal-api-lark-api.feishu.cn/im/gateway/';
 const CSRF_URL = 'https://internal-api-lark-api.feishu.cn/accounts/csrf';
@@ -86,26 +87,9 @@ class LarkUserClient {
   }
 
   // --- Cookie Heartbeat ---
-
-  _startHeartbeat() {
-    // Refresh CSRF token every 4 hours to keep session alive
-    // Feishu sl_session has 12h max-age; CSRF refresh also refreshes sl_session
-    this._heartbeatTimer = setInterval(async () => {
-      try {
-        await this._getCsrfToken();
-        // Lazy require to avoid circular dependency at module load time.
-        // auth/credentials writes to credentials.json (single source of truth)
-        // when it exists; falls back to legacy mcpServers persistence otherwise.
-        const { persistToConfig } = require('../auth/credentials');
-        persistToConfig({ LARK_COOKIE: this.cookieStr });
-        console.error('[feishu-user-plugin] Cookie heartbeat: session refreshed and persisted');
-      } catch (e) {
-        console.error('[feishu-user-plugin] Cookie heartbeat failed:', e.message);
-      }
-    }, 4 * 60 * 60 * 1000); // 4 hours
-    // Don't keep the process alive just for heartbeat
-    if (this._heartbeatTimer.unref) this._heartbeatTimer.unref();
-  }
+  // Body extracted to src/auth/cookie.js (v1.3.8 D.2). Timer state stays on
+  // this instance; auth/cookie.js mutates this._heartbeatTimer.
+  _startHeartbeat() { cookieHeartbeat.startHeartbeat(this); }
 
   async checkSession() {
     try {
@@ -205,11 +189,13 @@ class LarkUserClient {
       // missing required fields. Verified for IMAGE (v1.3.7 testing): the
       // simple {imageKey} content payload is rejected — Feishu Web encodes
       // images with extra metadata (image dimensions, mime type, etc.) that
-      // we don't have in proto/lark.proto. Reverse-engineering requires Chrome
-      // DevTools capture and is deferred to v1.3.8. Surface a clear error
-      // routing the user to send_message_as_bot, which works.
+      // we don't have in proto/lark.proto. v1.3.8 shipped the capture/decode
+      // tooling (scripts/decode-feishu-protobuf.js + capture-feishu-protobuf.js
+      // + docs/COOKIE-PROTOBUF-CAPTURES.md). Actual reverse-engineering moved
+      // to v1.3.9. Surface a clear error routing the user to
+      // send_message_as_bot, which works.
       if (type === MsgType.IMAGE) {
-        throw new Error('send_image_as_user: Feishu cookie protobuf gateway rejected the IMAGE wire format (HTTP 400). User-identity image sends are not yet supported — wire format reverse-engineering is deferred to v1.3.8. Workaround: use send_message_as_bot(chat_id, msg_type="image", payload={image_key:"..."}).');
+        throw new Error('send_image_as_user: Feishu cookie protobuf gateway rejected the IMAGE wire format (HTTP 400). User-identity image sends are not yet supported — wire format reverse-engineering is deferred to v1.3.9 (v1.3.8 shipped the capture/decode tooling at scripts/decode-feishu-protobuf.js). Workaround: use send_message_as_bot(chat_id, msg_type="image", payload={image_key:"..."}).');
       }
       throw new Error(`_sendMsg: cookie protobuf gateway returned non-2xx for type=${type}. The wire format likely doesn't match what Feishu expects.`);
     }

package/src/config.js

@@ -274,23 +274,23 @@ function persistToConfig(updates) {
  *   client: 'claude' (default) | 'codex' | 'both'
  * @returns {{ configPath: string, codexConfigPath?: string }}
  */
-function writeNewConfig(env, configPath, projectPath, client) {
+function writeNewConfig(env, configPath, projectPath, client, options = {}) {
   const results = {};
 
   // --- Claude Code (JSON) ---
   if (client !== 'codex') {
-    results.configPath = _writeClaudeConfig(env, configPath, projectPath);
+    results.configPath = _writeClaudeConfig(env, configPath, projectPath, options);
   }
 
   // --- Codex (TOML) ---
   if (client === 'codex' || client === 'both') {
-    results.codexConfigPath = _writeCodexConfig(env);
+    results.codexConfigPath = _writeCodexConfig(env, options);
   }
 
   return results;
 }
 
-function _writeClaudeConfig(env, configPath, projectPath) {
+function _writeClaudeConfig(env, configPath, projectPath, options = {}) {
   if (!configPath) {
     configPath = path.join(process.env.HOME || '', '.claude.json');
   }
@@ -312,7 +312,9 @@ function _writeClaudeConfig(env, configPath, projectPath) {
   const serverEntry = {
     command: 'npx',
     args: ['-y', 'feishu-user-plugin'],
-    env,
+    env: options.pointerOnly
+      ? { FEISHU_PLUGIN_PROFILE: env.FEISHU_PLUGIN_PROFILE || 'default' }
+      : env,
   };
 
   if (projectPath && config.projects?.[projectPath]) {
@@ -334,7 +336,7 @@ function _writeClaudeConfig(env, configPath, projectPath) {
   return configPath;
 }
 
-function _writeCodexConfig(env) {
+function _writeCodexConfig(env, options = {}) {
   const home = process.env.HOME || '';
   const codexDir = path.join(home, '.codex');
   const configPath = path.join(codexDir, 'config.toml');
@@ -352,8 +354,11 @@ function _writeCodexConfig(env) {
     content = _removeTomlServer(content, name);
   }
 
-  // Append new entry
-  content = content.trimEnd() + '\n\n' + _generateTomlServerEntry('feishu-user-plugin', env);
+  // Append new entry — pointer-only writes only FEISHU_PLUGIN_PROFILE
+  const envToWrite = options.pointerOnly
+    ? { FEISHU_PLUGIN_PROFILE: env.FEISHU_PLUGIN_PROFILE || 'default' }
+    : env;
+  content = content.trimEnd() + '\n\n' + _generateTomlServerEntry('feishu-user-plugin', envToWrite);
 
   _atomicWrite(configPath, content);
   console.error(`[feishu-user-plugin] Codex config written to ${configPath}`);

package/src/events/event-buffer.js

@@ -0,0 +1,100 @@
+// src/events/event-buffer.js — in-memory FIFO buffer for WS events.
+//
+// Single-consumer model: tools/events.js pulls events with `drain()`, which
+// removes them from the buffer. If multiple agents read concurrently they'll
+// see partial sets — explicitly NOT designed to fan out the same event to N
+// consumers, since the MCP server already serializes tool calls.
+//
+// What this owns:
+//   - _events: ordered list of events (oldest first)
+//   - cap: max retained; oldest dropped when full
+//   - push(event): append + trim
+//   - drain(filter?): remove and return matching events
+//   - peek(filter?): return matching events without removing
+//   - size, cap accessors
+
+const DEFAULT_CAP = 1000;
+
+class EventBuffer {
+  constructor({ cap = DEFAULT_CAP } = {}) {
+    this._events = [];
+    this._cap = Math.max(1, cap | 0);
+    this._totalSeen = 0;
+    this._totalDropped = 0;
+  }
+
+  push(event) {
+    if (!event || typeof event !== 'object') return;
+    if (!event._received_at) event._received_at = Math.floor(Date.now() / 1000);
+    this._events.push(event);
+    this._totalSeen++;
+    while (this._events.length > this._cap) {
+      this._events.shift();
+      this._totalDropped++;
+    }
+  }
+
+  drain(filter) {
+    if (!filter) {
+      const out = this._events;
+      this._events = [];
+      return out;
+    }
+    const fn = this._compileFilter(filter);
+    const kept = [];
+    const drained = [];
+    for (const e of this._events) {
+      if (fn(e)) drained.push(e);
+      else kept.push(e);
+    }
+    this._events = kept;
+    return drained;
+  }
+
+  peek(filter) {
+    if (!filter) return [...this._events];
+    const fn = this._compileFilter(filter);
+    return this._events.filter(fn);
+  }
+
+  size() { return this._events.length; }
+  cap() { return this._cap; }
+  stats() {
+    return {
+      size: this._events.length,
+      cap: this._cap,
+      totalSeen: this._totalSeen,
+      totalDropped: this._totalDropped,
+    };
+  }
+
+  // Filter language (intentionally narrow — extend on demand):
+  //   { event_type: "im.message.receive_v1" }       — exact match on type
+  //   { chat_id: "oc_zzz" }                         — extract from event payload
+  //   { since_seconds: 60 }                         — only events received in last N sec
+  //   { event_types: ["a", "b"] }                   — any of these types
+  // Multiple keys = AND.
+  _compileFilter(filter) {
+    return (e) => {
+      if (filter.event_type && e.event_type !== filter.event_type) return false;
+      if (filter.event_types && !filter.event_types.includes(e.event_type)) return false;
+      if (filter.chat_id) {
+        const chatId = this._extractChatId(e);
+        if (chatId !== filter.chat_id) return false;
+      }
+      if (filter.since_seconds) {
+        const cutoff = Math.floor(Date.now() / 1000) - filter.since_seconds;
+        if ((e._received_at || 0) < cutoff) return false;
+      }
+      return true;
+    };
+  }
+
+  _extractChatId(e) {
+    return e?.event?.message?.chat_id
+        || e?.event?.chat_id
+        || null;
+  }
+}
+
+module.exports = { EventBuffer, DEFAULT_CAP };

package/src/events/index.js

@@ -0,0 +1,5 @@
+// src/events/index.js — barrel import for the events subsystem.
+const { EventBuffer, DEFAULT_CAP } = require('./event-buffer');
+const { createWSServer } = require('./ws-server');
+
+module.exports = { EventBuffer, DEFAULT_CAP, createWSServer };

package/src/events/ws-server.js

@@ -0,0 +1,86 @@
+// src/events/ws-server.js — Feishu WebSocket subscription wrapper.
+//
+// Owns the WSClient + EventDispatcher pair. The MCP main() in server.js calls
+// startWS() at boot if APP_ID + APP_SECRET are configured; failures are
+// logged-and-tolerated (MCP keeps serving tool calls without realtime).
+//
+// What this owns:
+//   - createWSServer(opts) → { buffer, start(), stop() } factory
+//   - Default event registrations (im.message.receive_v1)
+//   - Reconnect via SDK's built-in handling (WSClient does this internally)
+//
+// What it does NOT own:
+//   - The buffer's persistence — it's in-memory only.
+//   - Multi-profile fan-out — single WS per process, per active profile.
+
+const lark = require('@larksuiteoapi/node-sdk');
+const { EventBuffer, DEFAULT_CAP } = require('./event-buffer');
+const { stderrLogger } = require('../logger');
+
+// Wrap an SDK event handler so the payload always lands in the buffer with
+// a stable shape. The SDK passes the raw event payload — we add metadata
+// for downstream filtering / display.
+function _bufferEventHandler(buffer, eventType) {
+  return async (data) => {
+    const event = {
+      event_type: eventType,
+      event_id: data?.event_id || data?.header?.event_id || null,
+      _received_at: Math.floor(Date.now() / 1000),
+      header: data?.header || null,
+      event: data?.event || data,
+    };
+    buffer.push(event);
+  };
+}
+
+function createWSServer({ appId, appSecret, bufferCap = DEFAULT_CAP, registrations = ['im.message.receive_v1'] } = {}) {
+  if (!appId || !appSecret) throw new Error('createWSServer: appId + appSecret required');
+
+  const buffer = new EventBuffer({ cap: bufferCap });
+  let wsClient = null;
+  let started = false;
+  let stopped = false;
+
+  const dispatcher = new lark.EventDispatcher({
+    logger: stderrLogger,
+    loggerLevel: lark.LoggerLevel.warn,
+  });
+
+  // Register handlers for each requested event type.
+  const handlers = {};
+  for (const t of registrations) {
+    handlers[t] = _bufferEventHandler(buffer, t);
+  }
+  dispatcher.register(handlers);
+
+  async function start() {
+    if (started) return;
+    started = true;
+    wsClient = new lark.WSClient({
+      appId, appSecret,
+      logger: stderrLogger,
+      loggerLevel: lark.LoggerLevel.warn,
+    });
+    try {
+      await wsClient.start({ eventDispatcher: dispatcher });
+      console.error(`[feishu-user-plugin] WS connected — listening for: ${registrations.join(', ')}`);
+    } catch (e) {
+      console.error(`[feishu-user-plugin] WS start failed: ${e.message}. Continuing without realtime events.`);
+      started = false;
+      wsClient = null;
+    }
+  }
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    if (wsClient) {
+      try { wsClient.close(); } catch (e) { console.error(`[feishu-user-plugin] WS close error: ${e.message}`); }
+      wsClient = null;
+    }
+  }
+
+  return { buffer, start, stop, get isRunning() { return started && !stopped; } };
+}
+
+module.exports = { createWSServer };