feishu-user-plugin 1.3.7 → 1.3.8

package/src/server.js

@@ -26,6 +26,7 @@ const { LarkOfficialClient } = require('./clients/official');
 const { resolveToken } = require('./resolver');
 const { listPrompts, getPrompt } = require('./prompts');
 const credentials = require('./auth/credentials');
+const profileRouter = require('./auth/profile-router');
 
 // --- Tool modules ---
 // Adding a new domain: create src/tools/<x>.js exporting { schemas, handlers }
@@ -38,6 +39,7 @@ const TOOL_MODULES = [
   require('./tools/diagnostics'),
   require('./tools/docs'),
   require('./tools/drive'),
+  require('./tools/events'),
   require('./tools/groups'),
   require('./tools/im-read'),
   require('./tools/messaging-bot'),
@@ -65,10 +67,20 @@ const HANDLERS = Object.fromEntries(TOOL_MODULES.flatMap((m) => Object.entries(m
 
 let userClient = null;
 let officialClient = null;
+let wsServer = null;
+function getEventBuffer() {
+  return wsServer ? wsServer.buffer : null;
+}
 // The "current" profile this in-memory MCP server is pinned to. Initialised
 // from the persisted active profile (credentials.json) at boot, but in-process
 // switches may diverge from the persisted active until the next server restart.
-let currentProfile = credentials.getActiveProfileName();
+//
+// Profile selection precedence (v1.3.8 E.1):
+//   1. process.env.FEISHU_PLUGIN_PROFILE — harness pointer
+//   2. credentials.json::active — single-file persisted active
+//   3. 'default' — legacy zero-config path
+let currentProfile = process.env.FEISHU_PLUGIN_PROFILE
+  || credentials.getActiveProfileName();
 
 function profileEnv(name) {
   return credentials.getActiveProfileEnv(name);
@@ -137,6 +149,7 @@ function buildCtx() {
   return {
     getUserClient,
     getOfficialClient,
+    getEventBuffer,
     listProfiles: () => credentials.listProfileNames(),
     getActiveProfile: () => currentProfile,
     setActiveProfile: (n) => {
@@ -168,8 +181,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (!handler) {
     return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
   }
+  // Strip via_profile from args before passing to the handler — it's a
+  // routing-layer concern, not a tool argument. Keep a copy for routing.
+  const cleanArgs = (args && typeof args === 'object') ? { ...args } : {};
+  delete cleanArgs.via_profile;
+
   try {
-    return await handler(args || {}, buildCtx());
+    return await profileRouter.withProfileRouting(buildCtx(), name, args || {}, async () => {
+      return handler(cleanArgs, buildCtx());
+    });
   } catch (err) {
     return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
   }
@@ -191,6 +211,8 @@ process.on('uncaughtException', (err) => {
 process.on('unhandledRejection', (reason) => {
   console.error('[feishu-user-plugin] Unhandled rejection:', reason);
 });
+process.on('SIGTERM', () => { try { wsServer?.stop(); } catch {} process.exit(0); });
+process.on('SIGINT',  () => { try { wsServer?.stop(); } catch {} process.exit(0); });
 
 // --- main ---
 
@@ -200,6 +222,16 @@ async function main() {
 
   // Startup diagnostics — use the resolved active-profile env so users on
   // credentials.json (where process.env may not have LARK_*) get accurate flags.
+  // If FEISHU_PLUGIN_PROFILE was set, validate the name exists. If not, fail
+  // loud — silently falling back to "default" would mask a typo'd harness env.
+  if (process.env.FEISHU_PLUGIN_PROFILE) {
+    const known = credentials.listProfileNames();
+    if (!known.includes(currentProfile)) {
+      console.error(`[feishu-user-plugin] FATAL: FEISHU_PLUGIN_PROFILE="${currentProfile}" not found. Known: ${known.join(', ')}.`);
+      console.error('[feishu-user-plugin] Fix: edit harness env block, or add the profile to ~/.feishu-user-plugin/credentials.json.');
+      process.exit(2);
+    }
+  }
   let activeEnv = {};
   try { activeEnv = profileEnv(currentProfile); } catch (_) { /* unknown profile is reported below */ }
   const hasCanonical = !!credentials.readCanonical();
@@ -212,6 +244,15 @@ async function main() {
   if (!hasCookie) console.error('[feishu-user-plugin] WARNING: LARK_COOKIE not set — user identity tools (send_to_user, etc.) will fail');
   if (!hasApp) console.error('[feishu-user-plugin] WARNING: LARK_APP_ID/SECRET not set — official API tools (read_messages, docs, etc.) will fail');
   if (!hasUAT) console.error('[feishu-user-plugin] WARNING: LARK_USER_ACCESS_TOKEN not set — P2P chat reading (read_p2p_messages) will fail');
+  // Warn when both credentials.json AND legacy env vars exist — they may
+  // diverge silently after a UAT refresh (we always write credentials.json).
+  if (hasCanonical && (process.env.LARK_COOKIE || process.env.LARK_APP_ID || process.env.LARK_USER_ACCESS_TOKEN)) {
+    console.error('[feishu-user-plugin] NOTE: credentials.json AND legacy LARK_* env vars are both set. Plugin reads credentials.json; the env vars are ignored. To clean up: remove the LARK_* keys from your harness config, leaving FEISHU_PLUGIN_PROFILE only.');
+  }
+  // Nudge legacy env-only users to migrate.
+  if (!hasCanonical && (hasCookie || hasApp || hasUAT)) {
+    console.error('[feishu-user-plugin] TIP: run `npx feishu-user-plugin migrate --confirm` to consolidate credentials into ~/.feishu-user-plugin/credentials.json (single source of truth, removes UAT-refresh drift across harnesses).');
+  }
 
   // Validate APP_ID/SECRET against Feishu before serving any tool calls.
   // Catches the "Claude filled in a wrong/stale APP_ID during install" failure
@@ -233,6 +274,28 @@ async function main() {
       console.error(`[feishu-user-plugin] WARNING: Could not verify APP_ID (${e.message}); network issue or cold start. Proceeding anyway.`);
     }
   }
+
+  // --- Real-time events (v1.3.8 C.3) ---
+  // Boot WS only when APP_ID/SECRET are valid. WS uses app credentials
+  // (not UAT), so cookie-only setups don't get realtime.
+  if (hasApp) {
+    try {
+      const { createWSServer } = require('./events');
+      wsServer = createWSServer({
+        appId: activeEnv.LARK_APP_ID,
+        appSecret: activeEnv.LARK_APP_SECRET,
+        registrations: ['im.message.receive_v1'],
+      });
+      // Start asynchronously — don't block MCP serving on WS handshake.
+      wsServer.start().catch((e) => {
+        console.error(`[feishu-user-plugin] WS deferred start error: ${e.message}`);
+      });
+    } catch (e) {
+      console.error(`[feishu-user-plugin] WS init failed: ${e.message}. Continuing without realtime.`);
+    }
+  } else {
+    console.error('[feishu-user-plugin] WS not started — APP_ID/SECRET missing. Realtime events (get_new_events) will return empty.');
+  }
 }
 
 module.exports = { main, TOOLS, HANDLERS };

package/src/setup.js

@@ -21,6 +21,7 @@ function parseArgs() {
     else if (argv[i] === '--app-secret' && argv[i + 1]) args.appSecret = argv[++i];
     else if (argv[i] === '--cookie' && argv[i + 1]) args.cookie = argv[++i];
     else if (argv[i] === '--client' && argv[i + 1]) args.client = argv[++i];
+    else if (argv[i] === '--pointer-only') args.pointerOnly = true;
   }
   return args;
 }
@@ -150,6 +151,19 @@ async function main() {
   }
   if (!client) client = 'claude';
 
+  // If credentials.json exists, recommend pointer-only — the env block in
+  // harness configs becomes redundant (and divergent on UAT refresh).
+  const { readCanonical } = require('./auth/credentials');
+  const hasCanonical = !!readCanonical();
+  let pointerOnly = !!cliArgs.pointerOnly;
+  if (hasCanonical && !pointerOnly && !nonInteractive) {
+    console.log('\n--- Pointer-only mode ---');
+    console.log('Detected ~/.feishu-user-plugin/credentials.json. You can write only');
+    console.log('FEISHU_PLUGIN_PROFILE=default to the harness env (recommended for clean configs).');
+    const ans = (await ask('Use pointer-only mode? (y/N): ')).trim().toLowerCase();
+    pointerOnly = (ans === 'y' || ans === 'yes');
+  }
+
   // Write config
   console.log('\n--- Writing Config ---');
 
@@ -161,9 +175,10 @@ async function main() {
     LARK_USER_REFRESH_TOKEN: hasUAT ? (existingRT || '') : '',
   };
 
-  const result = writeNewConfig(env, undefined, undefined, client);
+  const result = writeNewConfig(env, undefined, undefined, client, { pointerOnly });
   if (result.configPath) console.log(`Written to ${result.configPath} (Claude Code)`);
   if (result.codexConfigPath) console.log(`Written to ${result.codexConfigPath} (Codex)`);
+  if (pointerOnly) console.log('Mode: pointer-only (env block contains only FEISHU_PLUGIN_PROFILE)');
 
   // Summary
   console.log('\n' + '='.repeat(60));

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/events.js

@@ -0,0 +1,64 @@
+// src/tools/events.js — real-time event consumption (v1.3.8).
+//
+// 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).
+
+const { text, json } = require('./_registry');
+
+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.',
+    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).' },
+      },
+    },
+  },
+];
+
+const handlers = {
+  async get_new_events(args, ctx) {
+    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".');
+    }
+
+    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 events = 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;
+      truncated = true;
+    }
+
+    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,
+    });
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/messaging-user.js

@@ -160,7 +160,7 @@ 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.6+: bot-routed default] Send an interactive card to a chat. **Identity defaults to BOT** because user-identity card sending requires reverse-engineering the Feishu web protobuf (deferred to v1.3.9; v1.3.8 shipped the capture/decode tooling). The tool name keeps the "as_user" suffix so callers don\'t have to migrate when v1.3.9 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".',
     inputSchema: {
       type: 'object',
       properties: {

package/src/tools/profile.js

@@ -23,6 +23,19 @@ const schemas = [
       required: ['name'],
     },
   },
+  {
+    name: 'manage_profile_hints',
+    description: '[Plugin v1.3.8] Inspect / set / clear profileHints — the resourceKey → profileName cache the auto-switch middleware uses to remember which profile owns each Feishu resource. Useful when a hint goes stale (e.g., a profile lost access to a doc).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['list', 'set', 'clear'], description: 'list = show all hints; set = upsert one; clear = remove one or all.' },
+        resource_key: { type: 'string', description: 'For set/clear: the resourceKey, e.g. "doc:doccnXXX" or "chat:oc_zzz". Omit on clear to wipe all hints.' },
+        profile: { type: 'string', description: 'For set: the profile name to associate with the resource_key.' },
+      },
+      required: ['action'],
+    },
+  },
 ];
 
 const handlers = {
@@ -38,6 +51,24 @@ const handlers = {
     ctx.setActiveProfile(target);
     return text(`Switched to profile: ${target}`);
   },
+  async manage_profile_hints(args, _ctx) {
+    const credentials = require('../auth/credentials');
+    if (args.action === 'list') {
+      return json({ hints: credentials.getProfileHints() });
+    }
+    if (args.action === 'set') {
+      if (!args.resource_key) return text('manage_profile_hints(set): resource_key is required');
+      if (!args.profile) return text('manage_profile_hints(set): profile is required');
+      const ok = credentials.setProfileHint(args.resource_key, args.profile);
+      return text(ok ? `Hint set: ${args.resource_key} → ${args.profile}` : 'Hint not set (no credentials.json — run `npx feishu-user-plugin migrate --confirm`)');
+    }
+    if (args.action === 'clear') {
+      const ok = credentials.clearProfileHint(args.resource_key);
+      const target = args.resource_key || '<all>';
+      return text(ok ? `Hint cleared: ${target}` : `No hint to clear for: ${target}`);
+    }
+    return text(`manage_profile_hints: unknown action "${args.action}". Use list / set / clear.`);
+  },
 };
 
 module.exports = { schemas, handlers };