feishu-user-plugin 1.3.8 → 1.3.10

package/src/events/cursor.js

@@ -0,0 +1,103 @@
+// src/events/cursor.js — events.cursor.json + drain protocol.
+//
+// cursor.json schema: { version: 1, file: "events.jsonl", offset: <int> }
+// Atomic write: tmp + rename.
+// Drain: take per-operation mutex, read cursor, read events.jsonl[offset:], advance.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { withMutex } = require('./lockfile');
+const { readFrom } = require('./event-log');
+
+const CURSOR_FILENAME = 'events.cursor.json';
+const CURSOR_LOCK_FILENAME = 'events.cursor.lock';
+
+function _cursorPath(dir) { return path.join(dir, CURSOR_FILENAME); }
+function _lockPath(dir) { return path.join(dir, CURSOR_LOCK_FILENAME); }
+
+function _readCursor(cursorPath, defaultFileSize) {
+  try {
+    const raw = fs.readFileSync(cursorPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.version !== 1) throw new Error('bad version');
+    if (typeof parsed.file !== 'string' || typeof parsed.offset !== 'number') throw new Error('bad shape');
+    return parsed;
+  } catch (e) {
+    // Conservative reset: skip history (offset = current size), don't replay.
+    if (e.code !== 'ENOENT') {
+      console.error(`[feishu-user-plugin] cursor.json read failed: ${e.message}; resetting to current EOF.`);
+    }
+    return { version: 1, file: 'events.jsonl', offset: defaultFileSize };
+  }
+}
+
+function _writeCursorAtomic(cursorPath, cursor) {
+  const tmpPath = cursorPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(cursor) + '\n', { mode: 0o600 });
+  fs.renameSync(tmpPath, cursorPath);
+}
+
+// Sanity check: offset in [0, fileSize]. Returns clamped cursor.
+function _sanitize(cursor, fileSize) {
+  if (cursor.offset < 0 || cursor.offset > fileSize) {
+    console.error(`[feishu-user-plugin] cursor offset ${cursor.offset} out of range [0, ${fileSize}]; resetting to EOF.`);
+    return { ...cursor, offset: fileSize };
+  }
+  return cursor;
+}
+
+// Drain: read events from current offset; advance cursor (unless peek).
+//
+// Returns { events, nextOffset, advanced }.
+// `events` is the raw event objects from events.jsonl (filter applied by caller).
+function drain(dir, { peek = false } = {}) {
+  const logPath = path.join(dir, 'events.jsonl');
+  const curPath = _cursorPath(dir);
+  const lockPath = _lockPath(dir);
+
+  return withMutex(lockPath, () => {
+    let stat;
+    try { stat = fs.statSync(logPath); } catch (e) {
+      if (e.code === 'ENOENT') return { events: [], nextOffset: 0, advanced: false };
+      throw e;
+    }
+    let cursor = _readCursor(curPath, stat.size);
+    cursor = _sanitize(cursor, stat.size);
+
+    const { events, nextOffset } = readFrom(logPath, cursor.offset);
+    if (!peek && nextOffset !== cursor.offset) {
+      _writeCursorAtomic(curPath, { version: 1, file: 'events.jsonl', offset: nextOffset });
+      return { events, nextOffset, advanced: true };
+    }
+    // Always persist cursor.json on first drain (ENOENT) so subsequent calls
+    // don't trigger the conservative-reset-to-EOF path.
+    if (!peek) {
+      const exists = (() => { try { fs.statSync(curPath); return true; } catch (_) { return false; } })();
+      if (!exists) _writeCursorAtomic(curPath, { version: 1, file: 'events.jsonl', offset: nextOffset });
+    }
+    return { events, nextOffset, advanced: false };
+  }, { staleMs: 30_000 });
+}
+
+// Read cursor without advancing or locking — for diagnostics.
+function readSnapshot(dir) {
+  const logPath = path.join(dir, 'events.jsonl');
+  const curPath = _cursorPath(dir);
+  let fileSize = 0;
+  try { fileSize = fs.statSync(logPath).size; } catch (_) {}
+  const cursor = _readCursor(curPath, fileSize);
+  return { cursor, fileSize, pending: Math.max(0, fileSize - cursor.offset) };
+}
+
+// Manual reset (used by force-rotate path).
+function resetCursorTo(dir, offset) {
+  const curPath = _cursorPath(dir);
+  const lockPath = _lockPath(dir);
+  withMutex(lockPath, () => {
+    _writeCursorAtomic(curPath, { version: 1, file: 'events.jsonl', offset });
+  }, { staleMs: 30_000 });
+}
+
+module.exports = { drain, readSnapshot, resetCursorTo, CURSOR_FILENAME };

package/src/events/event-buffer.js

@@ -1,9 +1,12 @@
-// src/events/event-buffer.js — in-memory FIFO buffer for WS events.
+// src/events/event-buffer.js — in-memory FIFO buffer.
 //
-// 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.
+// v1.3.9: This is now the **disk-full fallback** only. Normal flow writes
+// to events.jsonl via src/events/event-log.js. The owner falls back to this
+// buffer when fs.appendFileSync fails (ENOSPC etc); get_new_events does NOT
+// read from this buffer in the owner-arbitrated path. Pre-v1.3.8 behaviour
+// is preserved when no logPath is configured.
+//
+// (rest of file unchanged)
 //
 // What this owns:
 //   - _events: ordered list of events (oldest first)

package/src/events/event-log.js

@@ -0,0 +1,151 @@
+// src/events/event-log.js — events.jsonl management.
+//
+// Single-writer (owner) appends with `\n`-terminated lines.
+// Multi-reader (any process) seeks from cursor offset to EOF, parses lines,
+// tolerates a trailing partial line.
+//
+// On owner takeover, callers should run repairTail() once before appending
+// to ensure append-only invariant is intact.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function ensureLog(logPath) {
+  try { fs.mkdirSync(path.dirname(logPath), { recursive: true, mode: 0o700 }); } catch (_) {}
+  try { fs.openSync(logPath, 'a'); } catch (_) {}
+}
+
+function appendEvent(logPath, eventObj) {
+  const line = JSON.stringify(eventObj) + '\n';
+  fs.appendFileSync(logPath, line, { encoding: 'utf8' });
+}
+
+// Read from `offset` to EOF; return { events: [...], nextOffset }.
+// Tolerates a trailing partial line (no \n) — partial line not consumed,
+// nextOffset stops at the last full \n.
+function readFrom(logPath, offset) {
+  let stat;
+  try { stat = fs.statSync(logPath); } catch (e) {
+    if (e.code === 'ENOENT') return { events: [], nextOffset: 0, fileSize: 0 };
+    throw e;
+  }
+  const fileSize = stat.size;
+  if (offset >= fileSize) return { events: [], nextOffset: offset, fileSize };
+  if (offset < 0) offset = 0;
+
+  const fd = fs.openSync(logPath, 'r');
+  try {
+    const length = fileSize - offset;
+    const buf = Buffer.allocUnsafe(length);
+    fs.readSync(fd, buf, 0, length, offset);
+    const text = buf.toString('utf8');
+    // Find last \n; everything after it is partial.
+    const lastNl = text.lastIndexOf('\n');
+    if (lastNl < 0) {
+      // Entire chunk is partial; no events consumed.
+      return { events: [], nextOffset: offset, fileSize };
+    }
+    const fullText = text.slice(0, lastNl + 1);  // include the \n
+    const events = [];
+    for (const line of fullText.split('\n')) {
+      if (!line) continue;
+      try { events.push(JSON.parse(line)); } catch (_) { /* skip malformed */ }
+    }
+    return { events, nextOffset: offset + Buffer.byteLength(fullText, 'utf8'), fileSize };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Repair: scan the tail for last \n; truncate file there if file ends with
+// non-\n bytes (partial line from a crash).
+function repairTail(logPath, scanBytes = 8192) {
+  let stat;
+  try { stat = fs.statSync(logPath); } catch (e) {
+    if (e.code === 'ENOENT') return { repaired: false, sizeBefore: 0, sizeAfter: 0 };
+    throw e;
+  }
+  if (stat.size === 0) return { repaired: false, sizeBefore: 0, sizeAfter: 0 };
+
+  const fd = fs.openSync(logPath, 'r+');
+  try {
+    const readLen = Math.min(scanBytes, stat.size);
+    const buf = Buffer.allocUnsafe(readLen);
+    fs.readSync(fd, buf, 0, readLen, stat.size - readLen);
+    // If the file already ends in \n, no repair needed.
+    if (buf[buf.length - 1] === 0x0A) return { repaired: false, sizeBefore: stat.size, sizeAfter: stat.size };
+    // Find last \n in the scanned tail.
+    let i = buf.length - 1;
+    while (i >= 0 && buf[i] !== 0x0A) i--;
+    if (i < 0) {
+      // No \n in last 8 KB — pathological. Don't truncate (might lose data); leave as is.
+      return { repaired: false, sizeBefore: stat.size, sizeAfter: stat.size, warning: 'no \\n in scan window' };
+    }
+    const truncateAt = stat.size - readLen + i + 1;  // +1 to keep the \n
+    fs.ftruncateSync(fd, truncateAt);
+    return { repaired: true, sizeBefore: stat.size, sizeAfter: truncateAt };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Defer-rotate. Returns true if rotation happened.
+//
+// Conditions: size > sizeThresholdBytes AND (cursorOffset >= size - 4096) — i.e.,
+// consumer is within 4 KB of EOF.
+function maybeRotate(logPath, cursorOffset, sizeThresholdBytes) {
+  let stat;
+  try { stat = fs.statSync(logPath); } catch (e) {
+    if (e.code === 'ENOENT') return { rotated: false };
+    throw e;
+  }
+  if (stat.size <= sizeThresholdBytes) return { rotated: false, sizeBytes: stat.size };
+  if (cursorOffset < stat.size - 4096) {
+    return { rotated: false, deferred: true, sizeBytes: stat.size, cursorOffset };
+  }
+  const ts = Math.floor(Date.now() / 1000);
+  const droppedPath = logPath + '.dropped-' + ts;
+  fs.renameSync(logPath, droppedPath);
+  // Recreate empty events.jsonl.
+  fs.openSync(logPath, 'a');
+  return { rotated: true, droppedPath, sizeBytes: stat.size };
+}
+
+// Force rotate (called when log > hardCap and consumer is too far behind).
+// Drops the current log to .dropped-<ts>, writes a synthetic _rotated event
+// to the new log so consumers see the warning.
+function forceRotate(logPath, prevSize) {
+  const ts = Math.floor(Date.now() / 1000);
+  const droppedPath = logPath + '.dropped-' + ts;
+  try { fs.renameSync(logPath, droppedPath); } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  appendEvent(logPath, {
+    event_id: '_rotated',
+    ts: ts * 1000,
+    profile: '_system',
+    payload: { warning: 'force_rotated_log', prev_size: prevSize, dropped_file: path.basename(droppedPath) },
+  });
+  return { droppedPath };
+}
+
+// Cleanup of old .dropped-<ts> files. Keep last `keepDays` worth.
+function cleanupDropped(logPath, keepDays = 7) {
+  const dir = path.dirname(logPath);
+  const base = path.basename(logPath);
+  const cutoffMs = Date.now() - keepDays * 86400_000;
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch (_) { return; }
+  for (const name of entries) {
+    if (!name.startsWith(base + '.dropped-')) continue;
+    const fp = path.join(dir, name);
+    try {
+      const stat = fs.statSync(fp);
+      if (stat.mtimeMs < cutoffMs) fs.unlinkSync(fp);
+    } catch (_) {}
+  }
+}
+
+module.exports = { ensureLog, appendEvent, readFrom, repairTail, maybeRotate, forceRotate, cleanupDropped };

package/src/events/index.js

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

package/src/events/lockfile.js

@@ -0,0 +1,126 @@
+// src/events/lockfile.js — generic O_CREAT|O_EXCL advisory lock.
+//
+// Two flavors:
+//   - acquireLongLived(path, info) → { release(), heartbeat() } for owner-style
+//     locks (one process holds for the duration of its lifetime, mtime = liveness).
+//     Steal: rename old → .stale-<pid>, then EXCL create. Returns null if active.
+//   - withMutex(path, fn, { staleMs }) → runs fn() while holding a per-operation
+//     mutex. Stale lock files (mtime older than staleMs) are reaped.
+//
+// Both reuse the same `fs.openSync(p, 'wx')` pattern v1.3.5 UAT lock established.
+// No new dep.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function _ensureDir(p) {
+  try { fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 }); } catch (_) {}
+}
+
+function _writeLockBody(fd, info) {
+  const body = JSON.stringify({ version: 1, pid: process.pid, start_time: Math.floor(Date.now() / 1000), ...info });
+  fs.writeSync(fd, body);
+}
+
+// Long-lived (owner) acquisition.
+//
+// Returns { release(), heartbeat() } on success.
+// Returns null if lock active (mtime within staleMs).
+function acquireLongLived(lockPath, { info = {}, staleMs = 60_000 } = {}) {
+  _ensureDir(lockPath);
+
+  // If lock exists, check staleness.
+  let stat;
+  try { stat = fs.statSync(lockPath); } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  if (stat) {
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < staleMs) return null;
+    // Stale — try to steal. Rename out of the way to make room for EXCL create.
+    const stolenPath = lockPath + '.stale-' + process.pid + '-' + Date.now();
+    try { fs.renameSync(lockPath, stolenPath); } catch (e) {
+      // Race: someone else got there first; try again from scratch.
+      if (e.code === 'ENOENT') return acquireLongLived(lockPath, { info, staleMs });
+      throw e;
+    }
+    // Schedule cleanup of the stolen file after a moment to avoid disk litter.
+    setTimeout(() => { try { fs.unlinkSync(stolenPath); } catch (_) {} }, 5000).unref();
+  }
+
+  // Atomic EXCL create — only one process wins this race.
+  let fd;
+  try {
+    fd = fs.openSync(lockPath, 'wx');
+  } catch (e) {
+    if (e.code === 'EEXIST') return null;  // someone else won
+    throw e;
+  }
+  try {
+    _writeLockBody(fd, info);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return {
+    release() {
+      try { fs.unlinkSync(lockPath); } catch (_) {}
+    },
+    heartbeat() {
+      try {
+        const now = new Date();
+        fs.utimesSync(lockPath, now, now);
+      } catch (e) {
+        // If the lock file was stolen, our heartbeat will fail. Caller must
+        // detect this via separate check (e.g., re-stat + compare pid in body).
+        return false;
+      }
+      return true;
+    },
+  };
+}
+
+// Per-operation mutex. Synchronous wrapper for short critical sections.
+function withMutex(lockPath, fn, { staleMs = 30_000, retries = 30, retryDelayMs = 100 } = {}) {
+  _ensureDir(lockPath);
+
+  const start = Date.now();
+  while (true) {
+    // Stale reap.
+    try {
+      const stat = fs.statSync(lockPath);
+      if (Date.now() - stat.mtimeMs > staleMs) {
+        try { fs.unlinkSync(lockPath); } catch (_) {}
+      }
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, 'wx');
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // Wait + retry.
+      if (Date.now() - start > staleMs) {
+        throw new Error(`withMutex: lock ${lockPath} held longer than ${staleMs}ms`);
+      }
+      const sleepUntil = Date.now() + retryDelayMs;
+      while (Date.now() < sleepUntil) { /* busy wait — short delay */ }
+      continue;
+    }
+
+    try {
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      fs.closeSync(fd);
+      const result = fn();
+      return result;
+    } finally {
+      try { fs.unlinkSync(lockPath); } catch (_) {}
+    }
+  }
+}
+
+module.exports = { acquireLongLived, withMutex };

package/src/events/owner.js

@@ -0,0 +1,73 @@
+// src/events/owner.js — ws-owner.lock acquire / heartbeat / takeover.
+//
+// Wraps lockfile.acquireLongLived for the WS-ownership use case.
+// Exposes an EventEmitter-style interface: 'become_owner', 'lose_owner', 'state_change'.
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { acquireLongLived } = require('./lockfile');
+
+const OWNER_LOCK_FILENAME = 'ws-owner.lock';
+const HEARTBEAT_INTERVAL_MS = 15_000;
+const STALE_MS = 60_000;
+const TAKEOVER_POLL_INTERVAL_MS = 30_000;
+
+function _ownerLockPath(dir) { return path.join(dir, OWNER_LOCK_FILENAME); }
+
+// Try to claim ownership (or steal if stale + force, or just steal if stale).
+// Returns:
+//   { isOwner: true, release(), heartbeat() } if successful
+//   { isOwner: false, ownerInfo } otherwise
+function tryClaim(dir, { info = {}, force = false } = {}) {
+  const lockPath = _ownerLockPath(dir);
+
+  if (force) {
+    // Force takeover: rename existing out of the way.
+    try { fs.renameSync(lockPath, lockPath + '.forced-' + Date.now()); } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  const handle = acquireLongLived(lockPath, { info, staleMs: STALE_MS });
+  if (!handle) {
+    // Read existing lock body for diagnostics.
+    let body = null;
+    try { body = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch (_) {}
+    let mtimeMs = null;
+    try { mtimeMs = fs.statSync(lockPath).mtimeMs; } catch (_) {}
+    return { isOwner: false, ownerInfo: { ...body, mtimeMs, last_heartbeat_age_seconds: mtimeMs ? Math.floor((Date.now() - mtimeMs) / 1000) : null } };
+  }
+  return { isOwner: true, ...handle };
+}
+
+// Read current owner info without modifying anything.
+function readOwnerInfo(dir) {
+  const lockPath = _ownerLockPath(dir);
+  let body = null;
+  let mtimeMs = null;
+  try {
+    body = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    mtimeMs = fs.statSync(lockPath).mtimeMs;
+  } catch (_) {}
+  if (!body) return { exists: false };
+  const ageSec = mtimeMs ? Math.floor((Date.now() - mtimeMs) / 1000) : null;
+  return {
+    exists: true,
+    pid: body.pid,
+    start_time: body.start_time,
+    mtimeMs,
+    last_heartbeat_age_seconds: ageSec,
+    alive: ageSec !== null && ageSec * 1000 < STALE_MS,
+  };
+}
+
+module.exports = {
+  tryClaim,
+  readOwnerInfo,
+  OWNER_LOCK_FILENAME,
+  HEARTBEAT_INTERVAL_MS,
+  STALE_MS,
+  TAKEOVER_POLL_INTERVAL_MS,
+};

package/src/events/ws-server.js

@@ -1,61 +1,103 @@
-// 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).
+// src/events/ws-server.js — rewritten for v1.3.9 owner-arbitrated mode.
 //
 // 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)
+//   - createWSServer(opts) — factory for WS client + event dispatcher.
+//   - v1.3.9: In owner mode (logPath provided), events go to events.jsonl
+//     directly instead of the in-memory buffer.
+//   - Tracks wsState / wsProfile so downstream can filter dropped events.
 //
 // 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.
+//   - Owner-lock acquisition (src/events/owner.js).
+//   - Cursor protocol (src/events/cursor.js).
+
+'use strict';
 
 const lark = require('@larksuiteoapi/node-sdk');
 const { EventBuffer, DEFAULT_CAP } = require('./event-buffer');
 const { stderrLogger } = require('../logger');
+const { appendEvent } = require('./event-log');
 
-// 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) {
+// Build the handler that writes a normalised event row.
+// In v1.3.9 owner mode, we write to events.jsonl directly with a profile tag.
+// In legacy mode (no logPath given) we fall back to the in-memory buffer.
+function _eventRowHandler({ buffer, eventType, getProfile, getWsState, logPath }) {
   return async (data) => {
+    const wsState = getWsState();
+    if (wsState !== 'connected') {
+      // Drop events received during 'switching' / 'disconnected' — we don't
+      // know which profile they belong to.
+      return;
+    }
     const event = {
+      event_id: data?.event_id || data?.header?.event_id || 'evt_' + Math.random().toString(36).slice(2),
+      ts: Date.now(),
+      profile: getProfile(),
       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);
+    if (logPath) {
+      try {
+        appendEvent(logPath, event);
+      } catch (e) {
+        // Disk-full or similar — fall back to in-memory buffer.
+        console.error(`[feishu-user-plugin] events.jsonl append failed: ${e.message}; falling back to in-memory buffer`);
+        buffer.push(event);
+      }
+    } else {
+      buffer.push(event);
+    }
   };
 }
 
-function createWSServer({ appId, appSecret, bufferCap = DEFAULT_CAP, registrations = ['im.message.receive_v1'] } = {}) {
+function createWSServer({
+  appId, appSecret,
+  bufferCap = DEFAULT_CAP,
+  registrations = ['im.message.receive_v1'],
+  logPath = null,                 // NEW: when set, events go to events.jsonl
+  initialProfile = 'default',     // NEW: profile name to tag events with
+} = {}) {
   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;
+  let wsProfile = initialProfile;
+  let wsState = 'disconnected';   // disconnected | connected | switching
+  let lastReconnectAt = null;
+  let reconnectAttempts = 0;
 
   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);
+    handlers[t] = _eventRowHandler({
+      buffer, eventType: t,
+      getProfile: () => wsProfile,
+      getWsState: () => wsState,
+      logPath,
+    });
+  }
+  try {
+    dispatcher.register(handlers);
+  } catch (e) {
+    console.error(`[feishu-user-plugin] WS event registration failed: ${e.message}; falling back to im.message.receive_v1 only`);
+    dispatcher.register({
+      'im.message.receive_v1': _eventRowHandler({
+        buffer, eventType: 'im.message.receive_v1',
+        getProfile: () => wsProfile, getWsState: () => wsState, logPath,
+      }),
+    });
   }
-  dispatcher.register(handlers);
 
   async function start() {
     if (started) return;
     started = true;
+    wsState = 'switching';
     wsClient = new lark.WSClient({
       appId, appSecret,
       logger: stderrLogger,
@@ -63,24 +105,52 @@ function createWSServer({ appId, appSecret, bufferCap = DEFAULT_CAP, registratio
     });
     try {
       await wsClient.start({ eventDispatcher: dispatcher });
-      console.error(`[feishu-user-plugin] WS connected — listening for: ${registrations.join(', ')}`);
+      wsState = 'connected';
+      lastReconnectAt = Date.now();
+      console.error(`[feishu-user-plugin] WS connected (profile=${wsProfile}) — listening for: ${registrations.join(', ')}`);
     } catch (e) {
+      wsState = 'disconnected';
+      reconnectAttempts++;
       console.error(`[feishu-user-plugin] WS start failed: ${e.message}. Continuing without realtime events.`);
       started = false;
       wsClient = null;
     }
   }
 
-  function stop() {
+  async function stop() {
     if (stopped) return;
     stopped = true;
+    wsState = 'disconnected';
     if (wsClient) {
-      try { wsClient.close(); } catch (e) { console.error(`[feishu-user-plugin] WS close error: ${e.message}`); }
+      try { wsClient.close(); } catch (_) {}
       wsClient = null;
     }
   }
 
-  return { buffer, start, stop, get isRunning() { return started && !stopped; } };
+  // For switching: stop, then start with a new profile/registrations.
+  // The registrations list is currently fixed at construction; full switching
+  // requires re-creating the WSClient. This helper just stops + nulls so the
+  // caller can construct a new server.
+  async function reconfigureProfile(newProfile) {
+    wsState = 'switching';
+    wsProfile = 'switching';   // tag-irrelevant during transition
+    await stop();
+    started = false; stopped = false;
+    wsProfile = newProfile;
+    await start();
+  }
+
+  function getStatus() {
+    return {
+      state: wsState,
+      wsProfile,
+      subscribed_events: registrations.slice(),
+      lastReconnectAt,
+      reconnectAttempts,
+    };
+  }
+
+  return { buffer, start, stop, reconfigureProfile, getStatus, get isRunning() { return started && !stopped; } };
 }
 
 module.exports = { createWSServer };