feishu-user-plugin 1.3.6 → 1.3.8

package/src/tools/diagnostics.js

@@ -0,0 +1,172 @@
+// src/tools/diagnostics.js — health checks + media downloads.
+//
+// v1.3.7 (C2.4) consolidates download_image / download_file into:
+//   download_message_resource(message_id, key, kind=image|file, save_path?)
+//   download_doc_image(image_token, doc_token?, save_path?)
+// Inline-base64 responses are capped at MAX_INLINE_BYTES (2 MiB) to leave
+// headroom under Anthropic's 5 MB API limit; over the cap, save_path is
+// required and the response only includes a short summary.
+
+const fs = require('fs');
+const { text } = require('./_registry');
+
+const MAX_INLINE_BYTES = 2 * 1024 * 1024; // 2 MiB; Anthropic API cap is 5 MB
+
+function inlineTooBig(bytes) {
+  return bytes > MAX_INLINE_BYTES;
+}
+
+function fmtMB(bytes) {
+  return (bytes / (1024 * 1024)).toFixed(2) + ' MB';
+}
+
+const schemas = [
+  {
+    name: 'get_login_status',
+    description: 'Check cookie session validity and app credentials status. Also refreshes session.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'download_message_resource',
+    description: '[User Identity / Official API] Download an image or file attached to a message so the model can see / store it. v1.3.7 (C2.4) consolidates the v1.3.6 download_image (mode 1) + download_file. UAT-first, falls back to app.\n\nFor images, the response includes an inline `image` content block so the model sees pixels. For files, the response includes the bytes as base64 (truncated for display) plus an optional save_path write.\n\n**Size cap:** payloads > 2 MiB MUST pass `save_path`. The Anthropic API rejects responses > 5 MB; we cap at 2 MiB so multipart wrapping has headroom.\n\n**merge_forward children:** Feishu keys media by the parent merge_forward id, not the child id. Use the child\'s `parentMessageId` field (returned by read_messages with expand_merge_forward) — not the child id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'Message ID (om_xxx). For merge_forward children, use the child\'s `parentMessageId`.' },
+        key: { type: 'string', description: 'image_key (img_xxx) for kind=image, file_key for kind=file. From read_messages content.' },
+        kind: { type: 'string', enum: ['image', 'file'], description: 'image or file' },
+        save_path: { type: 'string', description: 'Absolute local path. Required when downloaded bytes > 2 MiB (else the response would exceed the Anthropic API 5 MB inline limit).' },
+      },
+      required: ['message_id', 'key', 'kind'],
+    },
+  },
+  {
+    name: 'download_doc_image',
+    description: '[User Identity / Official API] Download an image embedded in a docx document so the model can see it. Pass the `image_token` from `get_doc_blocks` (block.image.token), and optionally the doc/wiki/URL token to scope the lookup. UAT-first.\n\n**Size cap:** payloads > 2 MiB MUST pass `save_path`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image_token: { type: 'string', description: 'Image token (from get_doc_blocks image block)' },
+        doc_token: { type: 'string', description: 'Document ID, wiki node token, or Feishu URL (optional but recommended for permission scoping).' },
+        save_path: { type: 'string', description: 'Absolute local path. Required when image bytes > 2 MiB.' },
+      },
+      required: ['image_token'],
+    },
+  },
+];
+
+function maybeSave(savePath, base64) {
+  if (!savePath) return null;
+  try {
+    fs.writeFileSync(savePath, Buffer.from(base64, 'base64'));
+    return { ok: true, path: savePath };
+  } catch (e) {
+    return { ok: false, path: savePath, error: e.message };
+  }
+}
+
+const handlers = {
+  async get_login_status(_args, ctx) {
+    const parts = [];
+    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);
+    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}"` : '';
+        parts.push(`App credentials: Valid — app_id=${probe.appId}${nameBit}`);
+      } else {
+        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) {
+        try {
+          await official.listChatsAsUser({ pageSize: 1 });
+          parts.push('User access token: Valid (P2P/group UAT reading enabled)');
+        } catch (e) {
+          parts.push(`User access token: INVALID — ${e.message}`);
+          parts.push('  → Re-run OAuth: npx feishu-user-plugin oauth, then restart Claude Code / Codex so running MCP servers load the new token.');
+        }
+      } else {
+        parts.push('User access token: Not set (optional — needed for P2P chat reading. Run OAuth flow to obtain, see README for details)');
+      }
+    }
+    return text(parts.join('\n'));
+  },
+
+  async download_message_resource(args, ctx) {
+    if (!args.message_id || !args.key) {
+      return text('download_message_resource requires message_id and key. For merge_forward children, use the child\'s parentMessageId (not the child id).');
+    }
+    const kind = args.kind;
+    if (kind !== 'image' && kind !== 'file') {
+      return text('download_message_resource: kind must be "image" or "file".');
+    }
+    const r = await ctx.getOfficialClient().downloadMessageResource(args.message_id, args.key, kind);
+    const sizeNote = `${r.bytes} bytes (${fmtMB(r.bytes)}, ${r.mimeType})`;
+    const tooBig = inlineTooBig(r.bytes);
+    if (tooBig && !args.save_path) {
+      return text(`Resource is ${sizeNote} — exceeds the 2 MiB inline cap. Re-run download_message_resource with save_path=<absolute path> so the bytes are written to disk and only a small summary is returned.`);
+    }
+    const saved = maybeSave(args.save_path, r.base64);
+    const saveNote = saved
+      ? (saved.ok ? `\nSaved to: ${saved.path}` : `\nSave to ${saved.path} failed: ${saved.error}`)
+      : '';
+    const ident = r.viaUser ? 'as user' : 'as app';
+    if (kind === 'image' && !tooBig) {
+      return {
+        content: [
+          { type: 'text', text: `Image from message ${args.message_id} (${ident}, ${sizeNote})${saveNote}` },
+          { type: 'image', data: r.base64, mimeType: r.mimeType },
+        ],
+      };
+    }
+    if (tooBig) {
+      return text(`Resource from message ${args.message_id} downloaded (${ident}, ${sizeNote})${saveNote}\nInline content omitted because the payload exceeds the 2 MiB cap.`);
+    }
+    return {
+      content: [
+        { type: 'text', text: `File from message ${args.message_id} (${ident}, ${sizeNote})${saveNote}` },
+        { type: 'text', text: `base64 (${r.bytes} bytes, truncated display):\n${r.base64.slice(0, 400)}${r.base64.length > 400 ? '…' : ''}` },
+      ],
+    };
+  },
+
+  async download_doc_image(args, ctx) {
+    if (!args.image_token) {
+      return text('download_doc_image requires image_token (from get_doc_blocks image block). Optionally pass doc_token (native id / wiki node / Feishu URL).');
+    }
+    const docToken = args.doc_token ? await ctx.resolveDocId(args.doc_token) : undefined;
+    const r = await ctx.getOfficialClient().downloadDocImage(args.image_token, docToken);
+    const sizeNote = `${r.bytes} bytes (${fmtMB(r.bytes)}, ${r.mimeType})`;
+    const tooBig = inlineTooBig(r.bytes);
+    if (tooBig && !args.save_path) {
+      return text(`Image is ${sizeNote} — exceeds the 2 MiB inline cap. Re-run download_doc_image with save_path=<absolute path>.`);
+    }
+    const saved = maybeSave(args.save_path, r.base64);
+    const saveNote = saved
+      ? (saved.ok ? `\nSaved to: ${saved.path}` : `\nSave to ${saved.path} failed: ${saved.error}`)
+      : '';
+    const source = docToken ? `docx ${docToken}` : 'drive media';
+    const ident = r.viaUser ? 'as user' : 'as app';
+    if (tooBig) {
+      return text(`Image from ${source} downloaded (${ident}, ${sizeNote})${saveNote}\nInline content omitted because the payload exceeds the 2 MiB cap.`);
+    }
+    return {
+      content: [
+        { type: 'text', text: `Image from ${source} (${ident}, ${sizeNote})${saveNote}` },
+        { type: 'image', data: r.base64, mimeType: r.mimeType },
+      ],
+    };
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/docs.js

@@ -0,0 +1,158 @@
+// 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.
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'search_docs',
+    description: '[Official API] Search Feishu documents by keyword.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search keyword' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'read_doc',
+    description: '[Official API] Read the raw text content of a Feishu document.',
+    inputSchema: {
+      type: 'object',
+      properties: { document_id: { type: 'string', description: 'Document ID or token' } },
+      required: ['document_id'],
+    },
+  },
+  {
+    name: 'get_doc_blocks',
+    description: '[Official API] Get structured block tree of a document. Returns block types, content, and hierarchy for precise document analysis.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        document_id: { type: 'string', description: 'Document ID (from search_docs or create_doc)' },
+      },
+      required: ['document_id'],
+    },
+  },
+  {
+    name: 'create_doc',
+    description: '[Official API] Create a new Feishu document. Can place directly under a Wiki space by passing wiki_space_id (optionally wiki_parent_node_token for nested placement) — the plugin creates the doc in drive then attaches it as a Wiki node.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Document title' },
+        folder_id: { type: 'string', description: 'Parent folder token (optional; ignored when wiki_space_id is set)' },
+        wiki_space_id: { type: 'string', description: 'Wiki space ID to place the doc under (optional)' },
+        wiki_parent_node_token: { type: 'string', description: 'Parent wiki node token within the space (optional; defaults to space root)' },
+      },
+      required: ['title'],
+    },
+  },
+  {
+    name: 'manage_doc_block',
+    description: '[Official API] Manage content blocks in a document. Single tool replaces v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks.\n  action=create — five modes:\n    (A) Generic — pass `children` array (e.g. [{block_type:2, text:{...}}]).\n    (B) Image from local file — pass `image_path`; plugin uploads and patches.\n    (C) Image from token — pass `image_token` (already uploaded).\n    (D) File attachment from local file — pass `file_path`; plugin handles VIEW-wrap + replace_file.\n    (E) File from token — pass `file_token`.\n  action=update — generic (pass `update_body`), image-replace (pass `image_token`), or file-replace (pass `file_token`).\n  action=delete — pass `parent_block_id` + `start_index` + `end_index` (range delete).\n`document_id` accepts native ID, wiki node token, or Feishu URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['create', 'update', 'delete'], description: 'Operation to perform' },
+        document_id: { type: 'string', description: 'Document ID, wiki node token, or Feishu URL (required for all actions)' },
+        block_id: { type: 'string', description: 'Block ID — required for action=update.' },
+        parent_block_id: { type: 'string', description: 'Parent block ID — required for create/delete (use document_id for the doc root).' },
+        index: { type: 'number', description: 'Insert position for create (optional, appends to end if omitted).' },
+        start_index: { type: 'number', description: 'Range start (inclusive) — required for delete.' },
+        end_index: { type: 'number', description: 'Range end (exclusive) — required for delete.' },
+        children: { type: 'array', description: 'Generic blocks for create mode A. E.g. [{block_type:2, text:{elements:[{text_run:{content:"Hello"}}]}}]', items: { type: 'object' } },
+        image_path: { type: 'string', description: 'Local image path — create mode B (mutually exclusive with other create modes).' },
+        image_token: { type: 'string', description: 'Pre-uploaded docx image token — create mode C, or update image-replace.' },
+        file_path: { type: 'string', description: 'Local file path — create mode D (mutually exclusive with other create modes).' },
+        file_token: { type: 'string', description: 'Pre-uploaded docx file token — create mode E, or update file-replace.' },
+        update_body: { type: 'object', description: 'Generic update payload for action=update. E.g. {update_text_elements:{elements:[{text_run:{content:"new text"}}]}}.' },
+      },
+      required: ['action', 'document_id'],
+    },
+  },
+];
+
+function need(arg, name, action) {
+  if (arg === undefined || arg === null || arg === '') {
+    throw new Error(`manage_doc_block: ${name} required for action=${action}`);
+  }
+}
+
+const handlers = {
+  async search_docs(args, ctx) {
+    return json(await ctx.getOfficialClient().searchDocs(args.query));
+  },
+  async read_doc(args, ctx) {
+    return json(await ctx.getOfficialClient().readDoc(await ctx.resolveDocId(args.document_id)));
+  },
+  async get_doc_blocks(args, ctx) {
+    return json(await ctx.getOfficialClient().getDocBlocks(await ctx.resolveDocId(args.document_id)));
+  },
+  async create_doc(args, ctx) {
+    const r = await ctx.getOfficialClient().createDoc(args.title, args.folder_id, {
+      wikiSpaceId: args.wiki_space_id,
+      wikiParentNodeToken: args.wiki_parent_node_token,
+    });
+    const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; document owned by the app, not you)';
+    const wikiNote = r.wikiNodeToken ? ` [wiki node: ${r.wikiNodeToken}]`
+      : r.wikiAttachTaskId ? ` [wiki attach queued — task_id: ${r.wikiAttachTaskId}]`
+      : r.wikiAttachError ? ` [WARNING: wiki attach failed — ${r.wikiAttachError}. Doc exists in drive root/folder.]`
+      : '';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Document created${ownership}: ${r.documentId}${wikiNote}${warn}`);
+  },
+  async manage_doc_block(args, ctx) {
+    const official = ctx.getOfficialClient();
+    const docId = await ctx.resolveDocId(args.document_id);
+    switch (args.action) {
+      case 'create': {
+        need(args.parent_block_id, 'parent_block_id', 'create');
+        const modes = [args.children, args.image_path, args.image_token, args.file_path, args.file_token].filter(Boolean);
+        if (modes.length > 1) return text('manage_doc_block(create): pass exactly ONE of children / image_path / image_token / file_path / file_token.');
+        if (args.image_path || args.image_token) {
+          const r = await official.createDocBlockWithImage(docId, args.parent_block_id, {
+            imagePath: args.image_path,
+            imageToken: args.image_token,
+            index: args.index,
+          });
+          return json(r);
+        }
+        if (args.file_path || args.file_token) {
+          const r = await official.createDocBlockWithFile(docId, args.parent_block_id, {
+            filePath: args.file_path,
+            fileToken: args.file_token,
+            index: args.index,
+          });
+          return json(r);
+        }
+        if (!args.children) return text('manage_doc_block(create): children, image_path, image_token, file_path, or file_token is required.');
+        return json(await official.createDocBlock(docId, args.parent_block_id, args.children, args.index));
+      }
+      case 'update': {
+        need(args.block_id, 'block_id', 'update');
+        const modes = [args.update_body, args.image_token, args.file_token].filter(Boolean);
+        if (modes.length > 1) return text('manage_doc_block(update): pass exactly ONE of update_body / image_token / file_token.');
+        if (args.image_token) {
+          return json(await official.updateDocBlockImage(docId, args.block_id, args.image_token));
+        }
+        if (args.file_token) {
+          return json(await official.updateDocBlockFile(docId, args.block_id, args.file_token));
+        }
+        if (!args.update_body) return text('manage_doc_block(update): update_body, image_token, or file_token is required.');
+        return json(await official.updateDocBlock(docId, args.block_id, args.update_body));
+      }
+      case 'delete': {
+        need(args.parent_block_id, 'parent_block_id', 'delete');
+        if (typeof args.start_index !== 'number' || typeof args.end_index !== 'number') {
+          throw new Error('manage_doc_block(delete): start_index and end_index (numbers) required.');
+        }
+        return text(`Blocks deleted: ${(await official.deleteDocBlocks(docId, args.parent_block_id, args.start_index, args.end_index)).deleted}`);
+      }
+    }
+  },
+};
+
+module.exports = { schemas, handlers };

package/src/tools/drive.js

@@ -0,0 +1,111 @@
+// src/tools/drive.js — Drive file operations + drive-targeted upload.
+//
+// 4 tools (was 6 in v1.3.6): list_files, create_folder, upload_drive_file,
+// and the consolidated manage_drive_file (action=copy|move|delete) which
+// replaces v1.3.6 copy_file / move_file / delete_file.
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'list_files',
+    description: '[Official API] List files in a Drive folder.',
+    inputSchema: {
+      type: 'object',
+      properties: { folder_token: { type: 'string', description: 'Folder token (empty for root)' } },
+    },
+  },
+  {
+    name: 'create_folder',
+    description: '[Official API] Create a new folder in Drive.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Folder name' },
+        parent_token: { type: 'string', description: 'Parent folder token (optional)' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'upload_drive_file',
+    description: '[Official API] Upload a file from disk to a Feishu Drive folder (drive/v1/files/upload_all, parent_type=explorer). Returns file_token + url. If wiki_space_id is provided, the uploaded file is then attached to that Wiki space via move_docs_to_wiki (obj_type=file). UAT-first with app fallback.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file_path: { type: 'string', description: 'Absolute path to the file on disk' },
+        folder_token: { type: 'string', description: 'Destination folder token. Use list_files to find one, or pass the user "我的空间" root token.' },
+        wiki_space_id: { type: 'string', description: 'Optional. If set, also attach the uploaded file to this Wiki space.' },
+        wiki_parent_node_token: { type: 'string', description: 'Optional. Parent node under which to attach in the Wiki space.' },
+      },
+      required: ['file_path', 'folder_token'],
+    },
+  },
+  {
+    name: 'manage_drive_file',
+    description: '[Official API] Manage a Drive file/doc/folder. action=copy (duplicate to a new name + folder), move (relocate, returns task_id), delete (remove, returns task_id). `type` is always required (Feishu rejects with 1061002 / 1062501 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['copy', 'move', 'delete'], description: 'Operation to perform' },
+        file_token: { type: 'string', description: 'File/folder token to operate on (required for all actions).' },
+        type: { type: 'string', enum: ['file', 'folder', 'doc', 'sheet', 'bitable', 'docx', 'mindnote', 'slides'], description: 'Resource type — Feishu requires this to know which API table to look up.' },
+        name: { type: 'string', description: 'New name — required for action=copy.' },
+        folder_token: { type: 'string', description: 'Destination folder token — required for action=move; optional for action=copy (defaults to root).' },
+      },
+      required: ['action', 'file_token', 'type'],
+    },
+  },
+];
+
+function need(arg, name, action) {
+  if (arg === undefined || arg === null || arg === '') {
+    throw new Error(`manage_drive_file: ${name} required for action=${action}`);
+  }
+}
+
+const handlers = {
+  async list_files(args, ctx) {
+    return json(await ctx.getOfficialClient().listFiles(args.folder_token));
+  },
+  async create_folder(args, ctx) {
+    const r = await ctx.getOfficialClient().createFolder(args.name, args.parent_token);
+    const ownership = r.viaUser ? ' (as user)' : ' (as app — UAT unavailable or failed; folder owned by the app, not you)';
+    const warn = r.fallbackWarning ? `\n\n${r.fallbackWarning}` : '';
+    return text(`Folder created${ownership}: ${r.token}${warn}`);
+  },
+  async upload_drive_file(args, ctx) {
+    const official = ctx.getOfficialClient();
+    const up = await official.uploadDriveFile(args.file_path, args.folder_token);
+    const out = { fileToken: up.fileToken, viaUser: up.viaUser, url: `https://feishu.cn/file/${up.fileToken}` };
+    if (args.wiki_space_id) {
+      try {
+        const node = await official.attachToWiki(args.wiki_space_id, 'file', up.fileToken, args.wiki_parent_node_token);
+        out.wikiNodeToken = node.node_token || null;
+        out.wikiAttachTaskId = node.task_id || null;
+      } catch (e) {
+        out.wikiAttachError = e.message;
+      }
+    }
+    return json(out);
+  },
+  async manage_drive_file(args, ctx) {
+    const c = ctx.getOfficialClient();
+    switch (args.action) {
+      case 'copy': {
+        need(args.name, 'name', 'copy');
+        return json(await c.copyFile(args.file_token, args.name, args.folder_token, args.type));
+      }
+      case 'move': {
+        need(args.folder_token, 'folder_token', 'move');
+        return text(`File moved: task=${(await c.moveFile(args.file_token, args.folder_token, args.type)).taskId}`);
+      }
+      case 'delete': {
+        const r = await c.deleteFile(args.file_token, args.type);
+        return text(r.taskId ? `File deletion queued: task=${r.taskId}` : `File deleted (${args.type})`);
+      }
+    }
+  },
+};
+
+module.exports = { schemas, handlers };

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

@@ -0,0 +1,81 @@
+// src/tools/groups.js — bot-side group chat management.
+
+const { text, json } = require('./_registry');
+
+const schemas = [
+  {
+    name: 'create_group',
+    description: '[Official API] Create a new group chat (as bot). Can add initial members.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Group name' },
+        description: { type: 'string', description: 'Group description (optional)' },
+        user_ids: { type: 'array', items: { type: 'string' }, description: 'Initial member open_ids (optional)' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'update_group',
+    description: '[Official API] Update group chat name or description.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Chat ID (oc_xxx)' },
+        name: { type: 'string', description: 'New group name (optional)' },
+        description: { type: 'string', description: 'New description (optional)' },
+      },
+      required: ['chat_id'],
+    },
+  },
+  {
+    name: 'list_members',
+    description: '[Official API] List all members in a group chat.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Chat ID (oc_xxx)' },
+        page_size: { type: 'number', description: 'Items per page (default 50)' },
+        page_token: { type: 'string', description: 'Pagination token' },
+      },
+      required: ['chat_id'],
+    },
+  },
+  {
+    name: 'manage_members',
+    description: '[Official API] Add or remove members from a group chat. The Feishu API rejects with code 9499 when the IDs in `member_ids` do not match `member_id_type` — pass `member_id_type` explicitly when using union_id or user_id (default: open_id).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Group chat ID (oc_xxx)' },
+        member_ids: { type: 'array', items: { type: 'string' }, description: 'Array of member identifiers — IDs must match member_id_type.' },
+        action: { type: 'string', enum: ['add', 'remove'], description: 'Action to perform' },
+        member_id_type: { type: 'string', enum: ['open_id', 'union_id', 'user_id'], description: 'Format of member_ids (default: open_id).', default: 'open_id' },
+      },
+      required: ['chat_id', 'member_ids', 'action'],
+    },
+  },
+];
+
+const handlers = {
+  async create_group(args, ctx) {
+    return text(`Group created: ${(await ctx.getOfficialClient().createChat({ name: args.name, description: args.description, userIds: args.user_ids })).chatId}`);
+  },
+  async update_group(args, ctx) {
+    return text(`Group updated: ${(await ctx.getOfficialClient().updateChat(args.chat_id, { name: args.name, description: args.description })).updated}`);
+  },
+  async list_members(args, ctx) {
+    return json(await ctx.getOfficialClient().listChatMembers(args.chat_id, { pageSize: args.page_size, pageToken: args.page_token }));
+  },
+  async manage_members(args, ctx) {
+    const official = ctx.getOfficialClient();
+    const memberIdType = args.member_id_type || 'open_id';
+    if (args.action === 'remove') {
+      return json(await official.removeChatMembers(args.chat_id, args.member_ids, memberIdType));
+    }
+    return json(await official.addChatMembers(args.chat_id, args.member_ids, memberIdType));
+  },
+};
+
+module.exports = { schemas, handlers };