feishu-user-plugin 1.3.7 → 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/_registry.js

@@ -7,6 +7,7 @@
 // the v1.3.7 phase A migration, temporarily in src/index.js) and provides:
 //   - getUserClient():   Promise<LarkUserClient>
 //   - getOfficialClient(): LarkOfficialClient
+//   - getEventBuffer():  EventBuffer | null  — null when WS isn't running
 //   - resolveDocId(x):   Promise<string>  — wiki-node / URL → native token
 //   - listProfiles():    string[]         — names from LARK_PROFILES_JSON + 'default'
 //   - getActiveProfile():string

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

@@ -0,0 +1,174 @@
+// src/tools/events.js — v1.3.9 reads from events.jsonl via cursor.
+//
+// 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.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: {
+        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.');
+    }
+    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.since_seconds) filter.since_seconds = args.since_seconds;
+    const cap = Math.max(1, parseInt(args.max_events, 10) || 50);
+    let evts = args.peek ? buffer.peek(filter) : buffer.drain(filter);
+    let truncated = false;
+    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 text(`unknown action: ${args.action}`);
+  },
+};
+
+module.exports = { schemas, handlers };

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');
 

package/src/tools/messaging-user.js

@@ -1,10 +1,12 @@
 // src/tools/messaging-user.js — User-identity (cookie-based) messaging plus
-// batch_send fan-out and the v1.3.6 bot-default send_card_as_user.
+// batch_send fan-out. send_card_as_user lives here (historical naming) but
+// always routes through bot — user-identity card sending is server-side
+// disabled in Feishu at the cookie auth tier.
 //
-// All send_*_as_user handlers route through ctx.getUserClient() (cookie identity).
-// batch_send mixes user + bot identities per target. send_card_as_user currently
-// delegates to bot via ctx.getOfficialClient() — the "as_user" suffix is reserved
-// for v1.3.7's reverse-engineered cookie path; default flips when that lands.
+// All send_*_as_user handlers route through ctx.getUserClient() (cookie identity)
+// EXCEPT send_card_as_user which delegates to bot via ctx.getOfficialClient().
+// The "as_user" suffix on the card tool is historical — v1.3.9 confirmed the
+// cookie protobuf path for CARD is server-side disabled, brute-force exhausted.
 
 const { text, sendResult, json } = require('./_registry');
 
@@ -115,12 +117,17 @@ const schemas = [
   },
   {
     name: 'send_image_as_user',
-    description: '[User Identity] Send an image as the logged-in user. Requires image_key (upload via Official API first).',
+    description: '[User Identity, v1.3.9] Send an image as the logged-in user (NOT bot). Requires image_key from a prior upload_image call. Cookie-protobuf wire format requires both imageKey + thumbnailKey — when no separate thumbnail is provided, plugin defaults thumbnailKey to imageKey (Feishu accepts this for messenger-uploaded images). Width/height/mime/size are optional metadata; Feishu auto-derives display sizing on its side.',
     inputSchema: {
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Target chat ID. Numeric preferred; oc_xxx is auto-resolved (v1.3.7 C1.4).' },
         image_key: { type: 'string', description: 'Image key from upload (img_v2_xxx or img_v3_xxx)' },
+        thumbnail_key: { type: 'string', description: 'Optional separate thumbnail image key. Defaults to image_key when omitted.' },
+        width: { type: 'number', description: 'Optional image width in pixels.' },
+        height: { type: 'number', description: 'Optional image height in pixels.' },
+        mime: { type: 'string', description: 'Optional MIME type (e.g. "image/png").' },
+        size: { type: 'number', description: 'Optional file size in bytes.' },
         root_id: { type: 'string', description: 'Thread root message ID (optional)' },
       },
       required: ['chat_id', 'image_key'],
@@ -160,13 +167,12 @@ const schemas = [
   },
   {
     name: 'send_card_as_user',
-    description: '[v1.3.6: bot-routed default] Send an interactive card to a chat. **As of v1.3.6, identity defaults to BOT** because user-identity card sending requires reverse-engineering the Feishu web protobuf and is deferred to v1.3.7. The tool name keeps the "as_user" suffix so callers don\'t have to migrate when v1.3.7 lands; once user-identity is implemented the default flips. Pass `card` as a JSON object (Feishu card schema). To force bot explicitly set via="bot".',
+    description: '[v1.3.9+: bot-only] Send an interactive Feishu card to a chat via bot identity (Official API). User-identity cookie protobuf path is server-side disabled at the auth tier — confirmed by exhaustive brute-force in v1.3.9, see scripts/explore-card-protobuf.js. The "as_user" suffix is historical naming kept for backward compat; the tool always routes through bot. Pass `card` as a JSON object (Feishu card schema, see https://open.feishu.cn/cardkit).',
     inputSchema: {
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Target chat_id (oc_xxx) or open_id' },
         card: { description: 'Feishu card JSON. See https://open.feishu.cn/cardkit for the schema; build cards visually then paste the resulting JSON here.' },
-        via: { type: 'string', enum: ['bot', 'user'], description: 'Identity to send as. Default "bot". "user" returns an explicit not-yet-implemented error in v1.3.6.' },
       },
       required: ['chat_id', 'card'],
     },
@@ -264,7 +270,14 @@ const handlers = {
   async send_image_as_user(args, ctx) {
     const c = await ctx.getUserClient();
     const chatId = await _resolveCookieChatId(args.chat_id, ctx);
-    const r = await c.sendImage(chatId, args.image_key, { rootId: args.root_id });
+    const r = await c.sendImage(chatId, args.image_key, {
+      rootId: args.root_id,
+      thumbnailKey: args.thumbnail_key,
+      width: args.width,
+      height: args.height,
+      mime: args.mime,
+      size: args.size,
+    });
     return sendResult(r, `Image sent to ${args.chat_id}`);
   },
   async send_file_as_user(args, ctx) {
@@ -280,12 +293,8 @@ const handlers = {
     return sendResult(r, `Post sent to ${args.chat_id}`);
   },
   async send_card_as_user(args, ctx) {
-    const via = args.via || 'bot';
-    if (via === 'user') {
-      return text('send_card_as_user via="user" is not implemented in v1.3.6 — user-identity card sending requires reverse-engineering the Feishu web protobuf and is scheduled for v1.3.7. Use via="bot" (default) for now.');
-    }
     const r = await ctx.getOfficialClient().sendMessageAsBot(args.chat_id, 'interactive', args.card);
-    return text(`Card sent (${via}): ${r.messageId}`);
+    return text(`Card sent (bot): ${r.messageId}`);
   },
 };