feishu-user-plugin 1.3.8 → 1.3.9

package/src/test-read-doc-markdown.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const assert = require('node:assert/strict');
+
+const { handlers } = require('./tools/docs');
+
+async function run() {
+  const fixturePath = path.join(__dirname, 'test-fixtures', 'doc-blocks', 'sample-1.json');
+  if (!fs.existsSync(fixturePath)) {
+    console.log('read-doc-markdown: no fixture, skipping');
+    return;
+  }
+  const blocks = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+
+  // feishu-docx is a hard dep in v1.3.9, but the handler has a graceful skip;
+  // honour the same pattern so the test passes in lean test envs.
+  try { require.resolve('feishu-docx'); } catch (_) {
+    console.log('read-doc-markdown: feishu-docx not installed, skipping');
+    return;
+  }
+
+  // Mock ctx: passthrough resolveDocId, return fixture from getDocBlocks.
+  const ctx = {
+    resolveDocId: async (id) => id,
+    getOfficialClient: () => ({
+      getDocBlocks: async (_id) => ({ items: blocks }),
+    }),
+  };
+
+  const result = await handlers.read_doc_markdown({ document_id: 'fixture' }, ctx);
+  // handler returns MCP text shape: { content: [{ type: 'text', text: string }] }
+  assert.ok(result, 'handler should return a result');
+  const md = result.content?.[0]?.text;
+  assert.ok(typeof md === 'string', 'handler output should be a markdown string');
+  assert.ok(md.length > 0, 'output should be non-empty');
+
+  // Token saving check
+  const jsonSize = JSON.stringify(blocks).length;
+  const ratio = md.length / jsonSize;
+  if (ratio > 0.6) {
+    console.warn(`read-doc-markdown: ratio ${(ratio * 100).toFixed(1)}% > 60% — consider tightening post-processor`);
+  }
+
+  // Spot-check: post-processor MUST have converted inline HTML tags
+  // (these are the bugs the post-processor exists to handle — without them,
+  // user-facing output is contaminated with <b>, <em>, <del> raw HTML).
+  assert.ok(!md.includes('<b>'), 'output should not contain raw <b> tags');
+  assert.ok(!md.includes('<em>'), 'output should not contain raw <em> tags');
+  assert.ok(!md.includes('<del>'), 'output should not contain raw <del> tags');
+  // External links preserved (the file regex must not over-match)
+  assert.ok(md.includes('[Anthropic](https://anthropic.com)'), 'external link [Anthropic] should be preserved');
+
+  console.log(`read-doc-markdown: PASS (ratio ${(ratio * 100).toFixed(1)}%)`);
+}
+
+if (require.main === module) {
+  run().catch(e => { console.error('read-doc-markdown: FAIL', e); process.exit(1); });
+}
+module.exports = { run };

package/src/test-switch-profile.js

@@ -0,0 +1,171 @@
+// src/test-switch-profile.js
+// e2e test: validate switch_profile invalidates cached clients + persists active.
+//
+// CAUTION: this test temporarily modifies ~/.feishu-user-plugin/credentials.json.
+// Backup is taken at start and restored at end (try/finally). If the test
+// crashes mid-run, the backup file is named cred-backup-<ts>.json — restore
+// manually if you see one in /tmp/.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const assert = require('node:assert/strict');
+
+const credPath = path.join(os.homedir(), '.feishu-user-plugin', 'credentials.json');
+
+function _readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+function _writeJson(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
+}
+
+async function run() {
+  // Warn user before doing anything
+  console.error('[test-switch-profile] WARNING: temporarily modifying ~/.feishu-user-plugin/credentials.json. Stop running MCP processes (pkill -f feishu-user-plugin) to avoid interference.');
+
+  const ts = Date.now();
+  const backupPath = path.join(os.tmpdir(), `cred-backup-${ts}.json`);
+  const originalCanonical = _readJson(credPath);
+
+  // Backup existing file (or note absence)
+  if (originalCanonical) {
+    fs.copyFileSync(credPath, backupPath);
+  } else {
+    _writeJson(backupPath, { absent: true });
+  }
+  console.error(`[test-switch-profile] backup → ${backupPath}`);
+
+  try {
+    // Write fixture with active=default + two profiles (default + alt)
+    // Use user's real default profile if available (so the APP_ID check works),
+    // otherwise fall back to dummy. The test only needs a recognisable prefix.
+    const baseDefault = (originalCanonical?.profiles?.default) || {
+      LARK_APP_ID: 'cli_test_def_xxxxxxxx',
+      LARK_APP_SECRET: 'test_secret_def',
+    };
+
+    const dummyAlt = {
+      LARK_APP_ID: 'cli_test_alt_xxxxxxxx',
+      LARK_APP_SECRET: 'test_secret_alt',
+      LARK_COOKIE: 'session=fake_alt_cookie',
+      LARK_USER_ACCESS_TOKEN: 'u-fake-alt-uat',
+      LARK_USER_REFRESH_TOKEN: 'fake-alt-refresh',
+    };
+
+    const fixture = {
+      version: 1,
+      active: 'default',
+      profiles: { default: baseDefault, alt: dummyAlt },
+      profileHints: {},
+    };
+    _writeJson(credPath, fixture);
+
+    // Bust require cache so credentials.js re-reads the fresh fixture on next require.
+    // Also bust resolver / server in case they cache credential-derived state.
+    for (const mod of ['./auth/credentials', './resolver', './tools/profile']) {
+      try {
+        delete require.cache[require.resolve(mod)];
+      } catch (_) { /* module may not be in cache yet — harmless */ }
+    }
+    // server.js import chain is large; skip busting it to avoid side-effects.
+    // We replicate the minimal ctx surface below instead.
+
+    // ── Minimal ctx (mirrors what src/server.js builds, minus MCP transport) ──
+    const credentials = require('./auth/credentials');
+    const { LarkUserClient } = require('./clients/user');
+    const { LarkOfficialClient } = require('./clients/official');
+
+    let userClient = null;
+    let officialClient = null;
+    let currentProfile = credentials.getActiveProfileName();
+
+    async function getUserClient() {
+      if (userClient) return userClient;
+      const env = credentials.getActiveProfileEnv(currentProfile);
+      // Do NOT call await userClient.init() — that hits the network.
+      userClient = new LarkUserClient(env.LARK_COOKIE || 'dummy');
+      return userClient;
+    }
+
+    function getOfficialClient() {
+      if (officialClient) return officialClient;
+      const env = credentials.getActiveProfileEnv(currentProfile);
+      officialClient = new LarkOfficialClient(env.LARK_APP_ID, env.LARK_APP_SECRET);
+      return officialClient;
+    }
+
+    const ctx = {
+      getUserClient,
+      getOfficialClient,
+      listProfiles: () => credentials.listProfileNames(),
+      getActiveProfile: () => currentProfile,
+      setActiveProfile: (n) => {
+        // Validate profile exists (throws if not)
+        credentials.getActiveProfileEnv(n);
+        currentProfile = n;
+        userClient = null;
+        officialClient = null;
+        // Persist to credentials.json (already validated above)
+        credentials.setActiveProfile(n);
+      },
+    };
+
+    const profile = require('./tools/profile');
+
+    // ── Assertion 1: initial state ──
+    assert.equal(currentProfile, 'default', 'initial profile should be "default"');
+    const c1 = getOfficialClient();
+    // Use baseDefault's actual APP_ID if present, otherwise the dummy prefix
+    const expectedDefaultPrefix = baseDefault.LARK_APP_ID || 'cli_test_def_';
+    assert.equal(c1.appId, expectedDefaultPrefix, 'first client uses default profile APP_ID');
+
+    // ── Assertion 2: switch to alt ──
+    await profile.handlers.switch_profile({ name: 'alt' }, ctx);
+    assert.equal(currentProfile, 'alt', 'currentProfile should be "alt" after switch');
+
+    // ── Assertion 3: credentials.json::active updated ──
+    const fresh = _readJson(credPath);
+    assert.equal(fresh.active, 'alt', 'credentials.json::active should be "alt"');
+
+    // ── Assertion 4: cached client invalidated; next getOfficialClient rebuilds ──
+    const c2 = getOfficialClient();
+    assert.notEqual(c2, c1, 'client instance should differ after profile switch');
+    assert.ok(c2.appId.startsWith('cli_test_alt_'), `alt client APP_ID should start with "cli_test_alt_" (got "${c2.appId}")`);
+
+    // ── Assertion 5: switch back to default ──
+    await profile.handlers.switch_profile({ name: 'default' }, ctx);
+    assert.equal(currentProfile, 'default', 'currentProfile should be "default" after switch back');
+    const afterSwitch = _readJson(credPath);
+    assert.equal(afterSwitch.active, 'default', 'credentials.json::active should be "default" after switch back');
+
+    const c3 = getOfficialClient();
+    assert.notEqual(c3, c2, 'client instance should differ again after switch back');
+    assert.equal(c3.appId, expectedDefaultPrefix, 'client after switch-back uses default profile APP_ID');
+
+    console.log('switch-profile-e2e: PASS');
+  } finally {
+    // Restore original credentials.json (or remove if it didn't exist)
+    if (originalCanonical) {
+      _writeJson(credPath, originalCanonical);
+    } else {
+      try { fs.unlinkSync(credPath); } catch (_) {}
+    }
+    console.error(`[test-switch-profile] restored credentials.json from ${backupPath}`);
+    // Clean up backup on success (it's in /tmp/, so not critical, but tidy)
+    try { fs.unlinkSync(backupPath); } catch (_) {}
+  }
+}
+
+if (require.main === module) {
+  run().catch((e) => {
+    console.error('switch-profile-e2e: FAIL', e);
+    process.exit(1);
+  });
+}
+
+module.exports = { run };

package/src/tools/diagnostics.js

@@ -68,17 +68,23 @@ function maybeSave(savePath, base64) {
 const handlers = {
   async get_login_status(_args, ctx) {
     const parts = [];
+    parts.push(`Active profile: ${ctx.getActiveProfile()}  (available: ${ctx.listProfiles().join(', ')})`);
     try {
       const c = await ctx.getUserClient();
       const status = await c.checkSession();
       parts.push(`Cookie: ${status.valid ? 'Active' : 'Expired'} (${status.userName || status.userId || 'unknown'})`);
       parts.push(`  ${status.message}`);
     } catch (e) { parts.push(`Cookie: ${e.message}`); }
-    const hasApp = !!(process.env.LARK_APP_ID && process.env.LARK_APP_SECRET);
+    // v1.3.9: read APP creds via ctx (profile-aware), not process.env directly,
+    // so SSOT users (env pointer-only) don't see false "Not set" reports.
+    let official, hasApp = false;
+    try {
+      official = ctx.getOfficialClient();
+      hasApp = !!(official.appId && official.appSecret);
+    } catch (_) {}
     if (!hasApp) {
       parts.push(`App credentials: Not set`);
     } else {
-      const official = ctx.getOfficialClient();
       const probe = await official.verifyApp();
       if (probe.valid) {
         const nameBit = probe.appName ? ` "${probe.appName}"` : '';
@@ -87,7 +93,8 @@ const handlers = {
         parts.push(`App credentials: INVALID — app_id=${probe.appId} rejected by Feishu (${probe.error})`);
         parts.push(`  → Likely wrong/stale APP_ID. Re-run the install prompt from team-skills/plugins/feishu-user-plugin/README.md to get the correct credentials.`);
       }
-      if (official.hasUAT) {
+      // official.hasUAT (when available)
+      if (official && official.hasUAT) {
         try {
           await official.listChatsAsUser({ pageSize: 1 });
           parts.push('User access token: Valid (P2P/group UAT reading enabled)');

package/src/tools/docs.js

@@ -1,8 +1,8 @@
 // src/tools/docs.js — Feishu document operations.
 //
-// 5 tools (was 7 in v1.3.6): search_docs, read_doc, get_doc_blocks, create_doc,
-// and the consolidated manage_doc_block (action=create|update|delete) which
-// replaces the v1.3.6 trio create_doc_block / update_doc_block / delete_doc_blocks.
+// 6 tools (was 7 in v1.3.6): search_docs, read_doc, get_doc_blocks, create_doc,
+// manage_doc_block (action=create|update|delete, replaces the v1.3.6 trio
+// create_doc_block / update_doc_block / delete_doc_blocks), and read_doc_markdown.
 
 const { text, json } = require('./_registry');
 
@@ -73,6 +73,17 @@ const schemas = [
       required: ['action', 'document_id'],
     },
   },
+  {
+    name: 'read_doc_markdown',
+    description: '[Plugin v1.3.9] Read a Feishu doc as Markdown (vs get_doc_blocks JSON). Saves ~60% tokens for RAG / digest / summarisation use cases. Accepts native docx token, wiki node token, or full Feishu URL. Embedded images / files appear as feishu://image_token/<TOKEN> placeholders — call download_doc_image for the binary if needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        document_id: { type: 'string', description: 'docx token / wiki node / full URL' },
+      },
+      required: ['document_id'],
+    },
+  },
 ];
 
 function need(arg, name, action) {
@@ -153,6 +164,85 @@ const handlers = {
       }
     }
   },
+  async read_doc_markdown(args, ctx) {
+    const docId = await ctx.resolveDocId(args.document_id);
+    const result = await ctx.getOfficialClient().getDocBlocks(docId);
+
+    // Lazy-load feishu-docx (so environments without the dep don't crash on startup)
+    let MarkdownRenderer;
+    try {
+      ({ MarkdownRenderer } = require('feishu-docx'));
+    } catch (e) {
+      return text('read_doc_markdown: feishu-docx package not installed. Run: npm install feishu-docx@^0.7.0');
+    }
+
+    const blocks = result.items || result;
+    if (!blocks || !blocks.length) {
+      return text('read_doc_markdown: document has no blocks (empty or unpublished draft). Try read_doc for plain text.');
+    }
+    const pageBlock = blocks.find(b => b.block_type === 1);
+    const documentId = pageBlock ? pageBlock.block_id : blocks[0].block_id;
+
+    let md;
+    try {
+      const renderer = new MarkdownRenderer({ document: { document_id: documentId }, blocks });
+      md = renderer.parse();
+    } catch (e) {
+      return text(`read_doc_markdown: feishu-docx render failed — ${e.message}. Try get_doc_blocks for raw JSON fallback. (feishu-docx version may need upgrading)`);
+    }
+
+    return text(_normaliseEmbeds(md));
+  },
 };
 
+// Post-processor applied to feishu-docx output before returning to the caller.
+// Converts inline HTML tags emitted by feishu-docx to Markdown equivalents,
+// converts callout <div> wrappers to > blockquotes, decodes HTML entities, and
+// normalises embedded image/file URLs to feishu:// scheme placeholders.
+function _normaliseEmbeds(md) {
+  // 1. Inline bold: <b>...</b> → **...**
+  md = md.replace(/<b>([\s\S]*?)<\/b>/g, '**$1**');
+  // 2. Inline italic: <em>...</em> → *...*
+  md = md.replace(/<em>([\s\S]*?)<\/em>/g, '*$1*');
+  // 3. Inline strikethrough: <del>...</del> → ~~...~~
+  md = md.replace(/<del>([\s\S]*?)<\/del>/g, '~~$1~~');
+  // 4. Inline underline: <u>...</u> → strip tags, keep inner text (no native Markdown underline)
+  md = md.replace(/<u>([\s\S]*?)<\/u>/g, '$1');
+  // 5. Callout divs → > blockquote. feishu-docx emits:
+  //      <div class="callout callout-bg-N callout-border-N">
+  //      <div class='callout-emoji'>EMOJI</div>
+  //      <p>content...</p>
+  //      </div>
+  //    Strip the outer div + emoji div; prefix each non-empty inner line with "> ".
+  //    Note: nested callouts will partially leak as raw HTML — feishu-docx encloses
+  //    the inner block in its own div, and our non-greedy match may close on the
+  //    first </div>. Acceptable for v1.3.9; revisit if real docs exhibit this.
+  md = md.replace(
+    /<div class="callout[^"]*">\s*<div class=['"]callout-emoji['"][^<]*<\/div>\s*([\s\S]*?)\s*<\/div>/g,
+    (match, inner) => {
+      const stripped = inner.replace(/<\/?[^>]+>/g, '');
+      return stripped.split('\n').map(l => l.trim() ? '> ' + l : '').join('\n');
+    },
+  );
+  // 6. Decode common HTML entities (&lt; &gt; &amp; appear in doc body text).
+  //    &amp; must be decoded first so that double-encoded sequences like &amp;lt;
+  //    are fully resolved (otherwise &amp; → & yields &lt; which stays escaped).
+  md = md.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>');
+  // 7. Image URL normalization.
+  //    feishu-docx parseImage (verified from dist/markdown_renderer.js) emits an HTML <img> tag
+  //    with the image token as src, e.g. <img src="img_v3_02k0XXX"/> or
+  //    <img src="img_v3_02k0XXX" src-width="800" src-height="600" align="center"/>
+  //    Convert to: ![](feishu://image_token/TOKEN)
+  md = md.replace(/<img\s+src="([^"]+)"[^>]*\/?>/g, '![](feishu://image_token/$1)');
+  // 8. File embed normalization.
+  //    feishu-docx parseFile (verified from dist/markdown_renderer.js) emits the
+  //    file token directly as the markdown link URL: [document.pdf](boxcnAbCdEfGhIj)
+  //    Feishu Drive file tokens always start with "box" — anchoring on that
+  //    prefix excludes wiki/docx/bitable/sheet mention links that share the
+  //    [name](token) syntax (wikcn/wikm/wikn/docx/doccn/bascn/sheet prefixes).
+  //    Convert to: [name](feishu://file_token/TOKEN)
+  md = md.replace(/\[([^\]]+)\]\((box[a-zA-Z0-9_-]{8,})\)/g, '[$1](feishu://file_token/$2)');
+  return md;
+}
+
 module.exports = { schemas, handlers };

package/src/tools/events.js

@@ -1,63 +1,173 @@
-// src/tools/events.js — real-time event consumption (v1.3.8).
+// src/tools/events.js — v1.3.9 reads from events.jsonl via cursor.
 //
-// Single tool: get_new_events. Drains the EventBuffer that ws-server.js fills
-// from Feishu's realtime WS push. Default: pulls all events accumulated since
-// the last call (drain semantics — consumers must accept that events vanish
-// after read).
+// Backwards compat: when ctx.getEventBuffer() is the legacy in-memory buffer
+// (no events.jsonl exists), fall back to the old behaviour.
 
+const path = require('path');
+const os = require('os');
 const { text, json } = require('./_registry');
+const { drain, readSnapshot } = require('../events/cursor');
+const { readOwnerInfo } = require('../events/owner');
+const fs = require('fs');
+
+const FEISHU_HOME = path.join(os.homedir(), '.feishu-user-plugin');
+const EVENTS_LOG_PATH = path.join(FEISHU_HOME, 'events.jsonl');
+
+function _hasJsonlMode() {
+  try { fs.statSync(EVENTS_LOG_PATH); return true; } catch (_) { return false; }
+}
+
+function _filter(event, args, currentProfile) {
+  // Profile filter (v1.3.9 default = current active; "*"/"any" = all)
+  const profFilter = args.profile;
+  if (!profFilter || profFilter === 'auto') {
+    if (event.profile && event.profile !== currentProfile && event.profile !== '_system') return false;
+  } else if (profFilter !== '*' && profFilter !== 'any') {
+    if (event.profile !== profFilter) return false;
+  }
+
+  if (args.event_type && event.event_type !== args.event_type) return false;
+  if (args.event_types && !args.event_types.includes(event.event_type)) return false;
+  if (args.chat_id) {
+    const chatId = event?.event?.message?.chat_id || event?.event?.chat_id;
+    if (chatId !== args.chat_id) return false;
+  }
+  if (args.since_seconds) {
+    const cutoff = Date.now() - args.since_seconds * 1000;
+    if ((event.ts || 0) < cutoff) return false;
+  }
+  return true;
+}
 
 const schemas = [
   {
     name: 'get_new_events',
-    description: '[Plugin v1.3.8] Drain real-time events received since the last call. Currently surfaces "im.message.receive_v1" events (replies, group messages). Returns empty when WS isn\'t connected or no events have arrived. Use filter to scope by event_type or chat_id; max_events caps response size.',
+    description: '[Plugin v1.3.9] Drain real-time events from the machine-level shared event log. v1.3.8 used per-process in-memory buffers (with duplicate-event problem); v1.3.9 uses ~/.feishu-user-plugin/events.jsonl with a single global cursor — every event delivered exactly once across all MCP processes on this machine. Default returns events from the current active profile only; pass profile="*" to see all.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        event_type: { type: 'string' },
+        event_types: { type: 'array', items: { type: 'string' } },
+        chat_id: { type: 'string' },
+        since_seconds: { type: 'integer' },
+        profile: { type: 'string', description: 'Profile filter. Default = current active. Pass "*" or "any" for all profiles.' },
+        max_events: { type: 'integer' },
+        peek: { type: 'boolean' },
+      },
+    },
+  },
+  {
+    name: 'manage_ws_status',
+    description: '[Plugin v1.3.9] Inspect or control the machine-level WS owner. Actions: info (status dump), reconnect (owner-only; restart WS), claim (try become owner; force=true to steal active lock), rotate (owner-only; force events.jsonl rotation), reconfig (owner-only; re-read credentials.json + apply event subscriptions).',
     inputSchema: {
       type: 'object',
       properties: {
-        event_type:    { type: 'string',  description: 'Optional: only events of this type (e.g. "im.message.receive_v1").' },
-        event_types:   { type: 'array', items: { type: 'string' }, description: 'Optional: any-of list of event types.' },
-        chat_id:       { type: 'string',  description: 'Optional: only events from this chat (oc_xxx for groups, message events expose chat_id).' },
-        since_seconds: { type: 'integer', description: 'Optional: only events received in the last N seconds.' },
-        max_events:    { type: 'integer', description: 'Cap on returned events (default 50). Drained events beyond the cap are returned in subsequent calls.' },
-        peek:          { type: 'boolean', description: 'When true, leave events in the buffer (default false = drain).' },
+        action: { type: 'string', enum: ['info', 'reconnect', 'claim', 'rotate', 'reconfig'] },
+        force: { type: 'boolean', description: 'For claim only: steal an active owner lock' },
       },
+      required: ['action'],
     },
   },
 ];
 
 const handlers = {
   async get_new_events(args, ctx) {
+    if (_hasJsonlMode()) {
+      const cap = Math.max(1, parseInt(args.max_events, 10) || 50);
+      const peek = !!args.peek;
+      const r = drain(FEISHU_HOME, { peek });
+      const currentProfile = ctx.getActiveProfile();
+      let filtered = r.events.filter((e) => _filter(e, args, currentProfile));
+      let truncated = false;
+      if (filtered.length > cap) {
+        filtered = filtered.slice(0, cap);
+        truncated = true;
+      }
+      const snap = readSnapshot(FEISHU_HOME);
+      return json({
+        events: filtered,
+        cursor: { offset: snap.cursor.offset, file: snap.cursor.file },
+        log: { size_bytes: snap.fileSize, pending_bytes: snap.pending },
+        truncated,
+      });
+    }
+    // Legacy in-memory fallback
     const buffer = ctx.getEventBuffer && ctx.getEventBuffer();
     if (!buffer) {
-      return text('Realtime events are not available. Reasons: APP_ID/SECRET not configured, OR Lark international tenant (Feishu WS only supports feishu.cn), OR the WS handshake failed at startup. Check server stderr for "WS connected" / "WS start failed".');
+      return text('Realtime events are not available. Reasons: APP_ID/SECRET not configured, OR Lark international tenant (Feishu WS only supports feishu.cn), OR the WS handshake failed at startup.');
     }
-
     const filter = {};
-    if (args.event_type)    filter.event_type = args.event_type;
-    if (args.event_types)   filter.event_types = args.event_types;
-    if (args.chat_id)       filter.chat_id = args.chat_id;
+    if (args.event_type) filter.event_type = args.event_type;
+    if (args.event_types) filter.event_types = args.event_types;
+    if (args.chat_id) filter.chat_id = args.chat_id;
     if (args.since_seconds) filter.since_seconds = args.since_seconds;
-
     const cap = Math.max(1, parseInt(args.max_events, 10) || 50);
-
-    let events = args.peek ? buffer.peek(filter) : buffer.drain(filter);
+    let evts = args.peek ? buffer.peek(filter) : buffer.drain(filter);
     let truncated = false;
-    if (events.length > cap) {
-      const kept = events.slice(0, cap);
-      const overflow = events.slice(cap);
-      if (!args.peek) {
-        for (const e of overflow) buffer.push(e);
-      }
-      events = kept;
+    if (evts.length > cap) {
+      evts = evts.slice(0, cap);
       truncated = true;
     }
+    return json({ events: evts, stats: buffer.stats(), truncated });
+  },
+
+  async manage_ws_status(args, ctx) {
+    const ws = ctx.getWsServer && ctx.getWsServer();
+    const ownerInfo = readOwnerInfo(FEISHU_HOME);
+    const isOwner = ws !== null && ws !== undefined;
+
+    if (args.action === 'info') {
+      const snap = readSnapshot(FEISHU_HOME);
+      const cred = require('../auth/credentials').readCanonical();
+      const activeProfile = ctx.getActiveProfile();
+      const configuredEvents = cred?.profiles?.[activeProfile]?.events || ['im.message.receive_v1'];
+      return json({
+        this_process: { is_owner: isOwner, pid: process.pid },
+        owner: ownerInfo.exists
+          ? { pid: ownerInfo.pid, start_time: ownerInfo.start_time, last_heartbeat_age_seconds: ownerInfo.last_heartbeat_age_seconds, alive: ownerInfo.alive }
+          : { exists: false },
+        ws: isOwner && ws ? ws.getStatus() : undefined,
+        log: { size_bytes: snap.fileSize, cursor_offset: snap.cursor.offset, pending_bytes: snap.pending },
+        config: { active_profile: activeProfile, configured_events: configuredEvents },
+      });
+    }
+
+    if (args.action === 'reconnect') {
+      if (!isOwner) return json({ error: 'not_owner', owner_pid: ownerInfo.pid });
+      ws.stop().then(() => ws.start()).catch(() => {});
+      return json({ ok: true, ws_state: 'switching' });
+    }
+
+    if (args.action === 'claim') {
+      if (isOwner) return json({ ok: true, became_owner: false, reason: 'already_owner' });
+      // Trigger _claimAndStart-like flow via ctx.
+      if (ctx.requestClaim) {
+        const r = await ctx.requestClaim({ force: !!args.force });
+        return json(r);
+      }
+      return json({ error: 'claim_not_supported_in_this_ctx' });
+    }
+
+    if (args.action === 'rotate') {
+      if (!isOwner) return json({ error: 'not_owner', owner_pid: ownerInfo.pid });
+      const snap = readSnapshot(FEISHU_HOME);
+      const { forceRotate } = require('../events/event-log');
+      const r = forceRotate(EVENTS_LOG_PATH, snap.fileSize);
+      const { resetCursorTo } = require('../events/cursor');
+      resetCursorTo(FEISHU_HOME, 0);
+      return json({ ok: true, prev_size: snap.fileSize, dropped_file: r.droppedPath });
+    }
+
+    if (args.action === 'reconfig') {
+      if (!isOwner) return json({ error: 'not_owner', owner_pid: ownerInfo.pid });
+      if (ctx.requestReconfigure) {
+        const r = await ctx.requestReconfigure();
+        return json({ ok: true, ...r });
+      }
+      return json({ error: 'reconfig_not_supported_in_this_ctx' });
+    }
 
-    return json({
-      events,
-      stats: buffer.stats(),
-      truncated,
-      hint: events.length === 0 ? 'No new events. Call again later, or check stats.totalSeen / .totalDropped to confirm WS is alive.' : undefined,
-    });
+    return text(`unknown action: ${args.action}`);
   },
 };
 

package/src/tools/messaging-bot.js

@@ -1,7 +1,6 @@
 // src/tools/messaging-bot.js — Bot-identity messaging operations (send, reply,
-// forward, delete, update, pin, reactions). send_card_as_user is intentionally
-// kept inline in src/index.js until v1.3.7's user-identity card path lands; it
-// will move to src/tools/messaging-user.js together with that work.
+// forward, delete, update, pin, reactions). send_card_as_user lives in
+// messaging-user.js (historical naming) but routes through bot — see that file.
 
 const { text, json } = require('./_registry');