@zhin.js/adapter-telegram 1.1.26 → 1.1.27

package/agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.js

@@ -1,21 +1,20 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '置顶 Telegram 群组消息',
+    description: '置顶当前 Telegram 群组中的消息',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
         message_id: z.string().describe('消息 ID'),
     }),
     adapter: 'telegram',
     scopes: ["group", "channel"],
     tags: ['telegram'],
-    permissions: [platformPermission('telegram', 'pin_messages')],
-    async execute({ chat_id, message_id }, context) {
+    permissions: ['platform-permission:pin_messages', 'bot-permission:pin_messages'],
+    async execute({ message_id }, context) {
         const endpoint = context.$client;
-        const success = await endpoint.pinMessage(Number(chat_id), Number(message_id));
+        const success = await endpoint.pinMessage(currentChat(context), Number(message_id));
         return { success, message: success ? t(context.locale, 'pinDone') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-chat-admin/tools/pin_message/index.ts

@@ -1,21 +1,20 @@
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ chat_id: string; message_id: string }>({
-  description: '置顶 Telegram 群组消息',
+export default defineAgentTool<{ message_id: string }>({
+  description: '置顶当前 Telegram 群组中的消息',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
     message_id: z.string().describe('消息 ID'),
   }),
   adapter: 'telegram',
   scopes: ["group","channel"],
   tags: ['telegram'],
-  permissions: [platformPermission('telegram', 'pin_messages')],
-  async execute({ chat_id, message_id  }: { chat_id: string; message_id: string }, context) {
+  permissions: ['platform-permission:pin_messages', 'bot-permission:pin_messages'],
+  async execute({ message_id }, context) {
     const endpoint = context.$client;
-    const success = await endpoint.pinMessage(Number(chat_id), Number(message_id));
+    const success = await endpoint.pinMessage(currentChat(context), Number(message_id));
     return { success, message: success ? t(context.locale, 'pinDone') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/telegram/skills/telegram-chat-admin/tools/set_description/index.js

@@ -1,19 +1,20 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '设置 Telegram 群组描述',
+    description: '设置当前 Telegram 群组描述',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
         description: z.string().describe('群描述文字'),
     }),
     adapter: 'telegram',
     scopes: ["group", "channel"],
+    permissions: ['platform-permission:change_info', 'bot-permission:change_info'],
     tags: ['telegram'],
-    async execute({ chat_id, description }, context) {
+    async execute({ description }, context) {
         const endpoint = context.$client;
-        const success = await endpoint.setChatDescription(Number(chat_id), description);
+        const success = await endpoint.setChatDescription(currentChat(context), description);
         return { success, message: success ? t(context.locale, 'descriptionUpdated') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-chat-admin/tools/set_description/index.ts

@@ -1,19 +1,20 @@
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ chat_id: string; description: string }>({
-  description: '设置 Telegram 群组描述',
+export default defineAgentTool<{ description: string }>({
+  description: '设置当前 Telegram 群组描述',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
     description: z.string().describe('群描述文字'),
   }),
   adapter: 'telegram',
   scopes: ["group","channel"],
+  permissions: ['platform-permission:change_info', 'bot-permission:change_info'],
   tags: ['telegram'],
-  async execute({ chat_id, description  }: { chat_id: string; description: string }, context) {
+  async execute({ description }, context) {
     const endpoint = context.$client;
-    const success = await endpoint.setChatDescription(Number(chat_id), description);
+    const success = await endpoint.setChatDescription(currentChat(context), description);
     return { success, message: success ? t(context.locale, 'descriptionUpdated') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.js

@@ -1,21 +1,20 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '取消置顶 Telegram 群组消息',
+    description: '取消置顶当前 Telegram 群组中的消息',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
         message_id: z.string().optional().describe('消息 ID（可选，不提供则取消所有置顶）'),
     }),
     adapter: 'telegram',
     scopes: ["group", "channel"],
     tags: ['telegram'],
-    permissions: [platformPermission('telegram', 'pin_messages')],
-    async execute({ chat_id, message_id }, context) {
+    permissions: ['platform-permission:pin_messages', 'bot-permission:pin_messages'],
+    async execute({ message_id }, context) {
         const endpoint = context.$client;
-        const success = await endpoint.unpinMessage(Number(chat_id), message_id ? Number(message_id) : undefined);
+        const success = await endpoint.unpinMessage(currentChat(context), message_id ? Number(message_id) : undefined);
         return { success, message: success ? t(context.locale, 'messageUnpinned') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-chat-admin/tools/unpin_message/index.ts

@@ -1,21 +1,20 @@
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ chat_id: string; message_id?: string }>({
-  description: '取消置顶 Telegram 群组消息',
+export default defineAgentTool<{ message_id?: string }>({
+  description: '取消置顶当前 Telegram 群组中的消息',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
     message_id: z.string().optional().describe('消息 ID（可选，不提供则取消所有置顶）'),
   }),
   adapter: 'telegram',
   scopes: ["group","channel"],
   tags: ['telegram'],
-  permissions: [platformPermission('telegram', 'pin_messages')],
-  async execute({ chat_id, message_id  }: { chat_id: string; message_id?: string }, context) {
+  permissions: ['platform-permission:pin_messages', 'bot-permission:pin_messages'],
+  async execute({ message_id }, context) {
     const endpoint = context.$client;
-    const success = await endpoint.unpinMessage(Number(chat_id), message_id ? Number(message_id) : undefined);
+    const success = await endpoint.unpinMessage(currentChat(context), message_id ? Number(message_id) : undefined);
     return { success, message: success ? t(context.locale, 'messageUnpinned') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/telegram/skills/telegram-group-permissions/tools/set_permissions/index.js

@@ -1,12 +1,11 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '设置 Telegram 群组的默认成员权限',
+    description: '设置当前 Telegram 群组的默认成员权限',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
         can_send_messages: z.boolean().optional().describe('是否可以发消息'),
         can_send_photos: z.boolean().optional().describe('是否可以发图片'),
         can_send_videos: z.boolean().optional().describe('是否可以发视频'),
@@ -20,15 +19,15 @@ export default defineAgentTool({
     adapter: 'telegram',
     scopes: ["group"],
     tags: ['telegram'],
-    permissions: [platformPermission('telegram', 'manage_chat')],
-    async execute({ chat_id, ...perms }, context) {
+    permissions: ['platform-permission:restrict_members', 'bot-permission:restrict_members'],
+    async execute(perms, context) {
         const endpoint = context.$client;
         const permissions = {};
         for (const [k, v] of Object.entries(perms)) {
             if (typeof v === 'boolean')
                 permissions[k] = v;
         }
-        const success = await endpoint.setChatPermissionsAll(Number(chat_id), permissions);
+        const success = await endpoint.setChatPermissionsAll(currentChat(context), permissions);
         return { success, message: success ? t(context.locale, 'permissionsUpdated') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-group-permissions/tools/set_permissions/index.ts

@@ -1,12 +1,11 @@
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ chat_id: string; can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }>({
-  description: '设置 Telegram 群组的默认成员权限',
+export default defineAgentTool<{ can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }>({
+  description: '设置当前 Telegram 群组的默认成员权限',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
     can_send_messages: z.boolean().optional().describe('是否可以发消息'),
     can_send_photos: z.boolean().optional().describe('是否可以发图片'),
     can_send_videos: z.boolean().optional().describe('是否可以发视频'),
@@ -20,14 +19,14 @@ export default defineAgentTool<{ chat_id: string; can_send_messages?: boolean; c
   adapter: 'telegram',
   scopes: ["group"],
   tags: ['telegram'],
-  permissions: [platformPermission('telegram', 'manage_chat')],
-  async execute({ chat_id, ...perms  }: { chat_id: string; can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }, context) {
+  permissions: ['platform-permission:restrict_members', 'bot-permission:restrict_members'],
+  async execute(perms: { can_send_messages?: boolean; can_send_photos?: boolean; can_send_videos?: boolean; can_send_polls?: boolean; can_send_other_messages?: boolean; can_add_web_page_previews?: boolean; can_change_info?: boolean; can_invite_users?: boolean; can_pin_messages?: boolean }, context) {
     const endpoint = context.$client;
     const permissions: Record<string, boolean> = {};
     for (const [k, v] of Object.entries(perms)) {
       if (typeof v === 'boolean') permissions[k] = v;
     }
-    const success = await endpoint.setChatPermissionsAll(Number(chat_id), permissions);
+    const success = await endpoint.setChatPermissionsAll(currentChat(context), permissions);
     return { success, message: success ? t(context.locale, 'permissionsUpdated') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/telegram/skills/telegram-messages/tools/react/index.js

@@ -1,19 +1,18 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '对 Telegram 消息添加表情反应',
+    description: '对当前 Telegram 会话中的消息添加表情反应',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
-        message_id: z.string().describe('消息 ID'),
+        message_id: z.string().describe('当前会话中的消息 ID'),
         reaction: z.string().describe('反应表情（如 👍、❤️、🔥）'),
     }),
     adapter: 'telegram',
     tags: ['telegram'],
-    async execute({ chat_id, message_id, reaction }, context) {
-        const endpoint = context.$client;
-        const success = await endpoint.setMessageReaction(Number(chat_id), Number(message_id), reaction);
+    async execute({ message_id, reaction }, context) {
+        const success = await context.$client.setMessageReaction(currentChat(context, { allowPrivate: true }), Number(message_id), reaction);
         return { success, message: success ? t(context.locale, 'reactionAdded', { p0: reaction }) : t(context.locale, 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-messages/tools/react/index.ts

@@ -1,19 +1,18 @@
 import { messages as t } from "../../../../messages.js";
+import { currentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ chat_id: string; message_id: string; reaction: string }>({
-  description: '对 Telegram 消息添加表情反应',
+export default defineAgentTool<{ message_id: string; reaction: string }>({
+  description: '对当前 Telegram 会话中的消息添加表情反应',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
-    message_id: z.string().describe('消息 ID'),
+    message_id: z.string().describe('当前会话中的消息 ID'),
     reaction: z.string().describe('反应表情（如 👍、❤️、🔥）'),
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  async execute({ chat_id, message_id, reaction  }: { chat_id: string; message_id: string; reaction: string }, context) {
-    const endpoint = context.$client;
-    const success = await endpoint.setMessageReaction(Number(chat_id), Number(message_id), reaction);
+  async execute({ message_id, reaction }, context) {
+    const success = await context.$client.setMessageReaction(currentChat(context, { allowPrivate: true }), Number(message_id), reaction);
     return { success, message: success ? t(context.locale, 'reactionAdded', { p0: reaction }) : t(context.locale, 'operationFailed') };
   },
 });

package/agents/telegram/skills/telegram-messages/tools/send_poll/index.js

@@ -1,11 +1,11 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { sendToCurrentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '在 Telegram 群组中发起投票',
+    description: '在当前 Telegram 会话中发起投票',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
         question: z.string().describe('投票问题'),
         options: z.string().describe('选项 JSON 数组，如 ["A","B","C"]'),
         is_anonymous: z.boolean().optional().describe('是否匿名投票，默认 true'),
@@ -13,8 +13,7 @@ export default defineAgentTool({
     }),
     adapter: 'telegram',
     tags: ['telegram'],
-    async execute({ chat_id, question, options, is_anonymous, allows_multiple }, context) {
-        const endpoint = context.$client;
+    async execute({ question, options, is_anonymous, allows_multiple }, context) {
         let optList;
         try {
             optList = JSON.parse(options);
@@ -25,8 +24,10 @@ export default defineAgentTool({
         if (!Array.isArray(optList) || optList.length < 2) {
             return { success: false, message: t(context.locale, 'pollOptionCount') };
         }
-        const result = await endpoint.sendPoll({ chatId: Number(chat_id), question, options: optList,
-            isAnonymous: is_anonymous ?? true, allowsMultipleAnswers: allows_multiple ?? false });
-        return { success: true, message_id: result.message_id, message: t(context.locale, 'pollSent') };
+        // `telegram:poll` is the Telegram adapter's namespaced outbound segment.
+        const result = await sendToCurrentChat(context, { type: 'telegram:poll', data: {
+                question, options: optList, is_anonymous: is_anonymous ?? true, allows_multiple_answers: allows_multiple ?? false,
+            } });
+        return { ...result, message: t(context.locale, result.success ? 'pollSent' : 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-messages/tools/send_poll/index.ts

@@ -1,11 +1,11 @@
 import { messages as t } from "../../../../messages.js";
+import { sendToCurrentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }>({
-  description: '在 Telegram 群组中发起投票',
+export default defineAgentTool<{ question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }>({
+  description: '在当前 Telegram 会话中发起投票',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
     question: z.string().describe('投票问题'),
     options: z.string().describe('选项 JSON 数组，如 ["A","B","C"]'),
     is_anonymous: z.boolean().optional().describe('是否匿名投票，默认 true'),
@@ -13,8 +13,7 @@ export default defineAgentTool<{ chat_id: string; question: string; options: str
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  async execute({ chat_id, question, options, is_anonymous, allows_multiple  }: { chat_id: string; question: string; options: string; is_anonymous?: boolean; allows_multiple?: boolean }, context) {
-    const endpoint = context.$client;
+  async execute({ question, options, is_anonymous, allows_multiple }, context) {
     let optList: string[];
     try {
       optList = JSON.parse(options);
@@ -24,8 +23,10 @@ export default defineAgentTool<{ chat_id: string; question: string; options: str
     if (!Array.isArray(optList) || optList.length < 2) {
       return { success: false, message: t(context.locale, 'pollOptionCount') };
     }
-    const result = await endpoint.sendPoll({ chatId: Number(chat_id), question, options: optList,
-      isAnonymous: is_anonymous ?? true, allowsMultipleAnswers: allows_multiple ?? false });
-    return { success: true, message_id: result.message_id, message: t(context.locale, 'pollSent') };
+    // `telegram:poll` is the Telegram adapter's namespaced outbound segment.
+    const result = await sendToCurrentChat(context, { type: 'telegram:poll', data: {
+      question, options: optList, is_anonymous: is_anonymous ?? true, allows_multiple_answers: allows_multiple ?? false,
+    } });
+    return { ...result, message: t(context.locale, result.success ? 'pollSent' : 'operationFailed') };
   },
 });

package/agents/telegram/skills/telegram-messages/tools/send_sticker/index.js

@@ -1,18 +1,18 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { sendToCurrentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '发送 Telegram 贴纸',
+    description: '在当前 Telegram 会话发送贴纸',
     inputSchema: z.object({
-        chat_id: z.string().describe('聊天 ID'),
-        sticker: z.string().describe('贴纸 file_id 或 URL'),
+        sticker: z.string().describe('贴纸 file_id 或 http(s) URL'),
     }),
     adapter: 'telegram',
     tags: ['telegram'],
-    async execute({ chat_id, sticker }, context) {
-        const endpoint = context.$client;
-        const result = await endpoint.sendStickerMessage(Number(chat_id), sticker);
-        return { success: true, message_id: result.message_id, message: t(context.locale, 'stickerSent') };
+    async execute({ sticker }, context) {
+        // `telegram:sticker` is the Telegram adapter's namespaced outbound segment.
+        const result = await sendToCurrentChat(context, { type: 'telegram:sticker', data: { sticker } });
+        return { ...result, message: t(context.locale, result.success ? 'stickerSent' : 'operationFailed') };
     },
 });

package/agents/telegram/skills/telegram-messages/tools/send_sticker/index.ts

@@ -1,18 +1,18 @@
 import { messages as t } from "../../../../messages.js";
+import { sendToCurrentChat } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ chat_id: string; sticker: string }>({
-  description: '发送 Telegram 贴纸',
+export default defineAgentTool<{ sticker: string }>({
+  description: '在当前 Telegram 会话发送贴纸',
   inputSchema: z.object({
-    chat_id: z.string().describe('聊天 ID'),
-    sticker: z.string().describe('贴纸 file_id 或 URL'),
+    sticker: z.string().describe('贴纸 file_id 或 http(s) URL'),
   }),
   adapter: 'telegram',
   tags: ['telegram'],
-  async execute({ chat_id, sticker  }: { chat_id: string; sticker: string }, context) {
-    const endpoint = context.$client;
-    const result = await endpoint.sendStickerMessage(Number(chat_id), sticker);
-    return { success: true, message_id: result.message_id, message: t(context.locale, 'stickerSent') };
+  async execute({ sticker }, context) {
+    // `telegram:sticker` is the Telegram adapter's namespaced outbound segment.
+    const result = await sendToCurrentChat(context, { type: 'telegram:sticker', data: { sticker } });
+    return { ...result, message: t(context.locale, result.success ? 'stickerSent' : 'operationFailed') };
   },
 });

package/lib/endpoint.d.ts

@@ -17,7 +17,8 @@ export { TelegramClient, type TelegramClientApi, type TelegramFetch } from './te
 /**
  * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
  * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
- * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ * 因此本 endpoint 的 EndpointManagement 只有 `inspectSelfStanding`（ADR 0056 §1：getChatMember bot），
+ * Console 社交面 RPC 对该平台保持未接线。
  */
 export declare class TelegramEndpoint extends TelegramClient implements Endpoint {
     #private;

package/lib/endpoint.js

@@ -9,19 +9,22 @@ import { EndpointDeliveryError, } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
 export { TelegramApiError } from './api-error.js';
-import { normalizeTelegramChatMember } from './platform-permit.js';
+import { telegramChatMemberStanding } from './platform-permit.js';
 import { buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
 import { createTelegramSelfProfile } from './self-profile.js';
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
+/** A failed `getChatMember` is not retried for every message of a busy chat (unknown standing meanwhile). */
+const CHAT_MEMBER_FAILURE_TTL_MS = 10_000;
 const ADMITTED_UPDATE_LIMIT = 2_048;
 const INFLIGHT_UPDATE_LIMIT = 256;
 export { TelegramClient } from './telegram-client.js';
 /**
  * Telegram Bot API 无列表类接口（无 getMyChats/getChatMembers），
  * 仅 getChat/getChatMember 按已知 id 单查，不构成列表能力；
- * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ * 因此本 endpoint 的 EndpointManagement 只有 `inspectSelfStanding`（ADR 0056 §1：getChatMember bot），
+ * Console 社交面 RPC 对该平台保持未接线。
  */
 export class TelegramEndpoint extends TelegramClient {
     [endpointSpec];
@@ -44,6 +47,24 @@ export class TelegramEndpoint extends TelegramClient {
         ttlMs: CHAT_MEMBER_CACHE_TTL_MS,
         maxEntries: CHAT_MEMBER_CACHE_MAX,
     });
+    /** Recently failed lookups (negative cache): the standing stays unknown until it expires. */
+    #chatMemberFailures = new TtlLookupCache({
+        ttlMs: CHAT_MEMBER_FAILURE_TTL_MS,
+        maxEntries: CHAT_MEMBER_CACHE_MAX,
+    });
+    /** Concurrent messages from one sender share one `getChatMember` call. */
+    #chatMemberInflight = new Map();
+    #management = Object.freeze({
+        // ADR 0056 §1: the Bot's own standing (`bot:*` permits); the framework caches per conversation.
+        inspectSelfStanding: async ({ conversation, signal }) => {
+            if (conversation.kind === 'private' || !this.#botUserId)
+                return undefined;
+            const member = await this.callApi('getChatMember', {
+                chat_id: Number(conversation.id), user_id: this.#botUserId,
+            }, signal);
+            return telegramChatMemberStanding(member);
+        },
+    });
     #control = Object.freeze({
         recall: ({ message, signal }) => this.recallMessage(message, signal),
     });
@@ -60,7 +81,7 @@ export class TelegramEndpoint extends TelegramClient {
             start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
             get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
-            control: this.#control, content: this.#content,
+            control: this.#control, content: this.#content, management: this.#management,
             streaming: options.config.streaming !== false ? createTelegramStreaming(() => this, options.config.streamingIntervalMs) : undefined,
             profile: createTelegramSelfProfile({ client: this,
                 current: () => this.#botName === undefined ? {} : { nickname: this.#botName },
@@ -340,7 +361,7 @@ export class TelegramEndpoint extends TelegramClient {
             sender: {
                 id: String(msg.from?.id ?? ''),
                 name: senderDisplayName(msg.from) || undefined,
-                ...(permit?.role ? { roles: [permit.role] } : {}),
+                ...(permit ? { platform: permit } : {}),
             },
             endpointId: this.#options.config.id,
             ...(mentioned ? { mentioned: true } : {}),
@@ -350,8 +371,6 @@ export class TelegramEndpoint extends TelegramClient {
                 chatType: msg.chat.type,
                 userId: msg.from?.id,
                 date: msg.date,
-                ...(permit?.role ? { senderRole: permit.role } : {}),
-                ...(permit?.permissions.length ? { senderPermissions: [...permit.permissions] } : {}),
             }),
         });
     }
@@ -379,7 +398,10 @@ export class TelegramEndpoint extends TelegramClient {
         }
         return false;
     }
-    /** 群消息 sender role 解析：getChatMember + 60s 缓存（对齐旧 enrichGroupSender）。 */
+    /**
+     * 群消息 sender role 解析：getChatMember + 60s 缓存；并发查询合并为一次调用，失败负缓存 10s，
+     * `chat_member` / `my_chat_member` 更新时以新状态覆盖缓存。
+     */
     async #resolveGroupSenderPermit(msg, signal) {
         if (msg.chat.type === 'private' || !msg.from?.id)
             return undefined;
@@ -389,22 +411,52 @@ export class TelegramEndpoint extends TelegramClient {
         const cached = this.#chatMemberCache.get(key);
         if (cached)
             return cached;
-        try {
-            const member = await this.callApi('getChatMember', {
-                chat_id: chatId,
-                user_id: userId,
-            }, signal);
-            if (signal.aborted)
-                return undefined;
-            const normalized = normalizeTelegramChatMember(member);
-            const entry = { ...normalized };
-            this.#chatMemberCache.set(key, entry);
-            return entry;
-        }
-        catch {
-            // 保守拒绝：无角色快照
+        if (this.#chatMemberFailures.get(key))
             return undefined;
+        let task = this.#chatMemberInflight.get(key)?.promise;
+        if (!task) {
+            const lookup = {};
+            task = (async () => {
+                await undefined; // registered in #chatMemberInflight before the body runs
+                try {
+                    const member = await this.callApi('getChatMember', {
+                        chat_id: chatId,
+                        user_id: userId,
+                    }, signal);
+                    if (signal.aborted)
+                        return undefined;
+                    const entry = telegramChatMemberStanding(member);
+                    // Invalidated (chat_member update) while in flight: do not store the older answer.
+                    if (this.#chatMemberInflight.get(key) === lookup)
+                        this.#chatMemberCache.set(key, entry);
+                    return entry;
+                }
+                catch {
+                    // 保守拒绝：无角色快照；取消不算失败
+                    if (!signal.aborted && this.#chatMemberInflight.get(key) === lookup)
+                        this.#chatMemberFailures.set(key, true);
+                    return undefined;
+                }
+                finally {
+                    if (this.#chatMemberInflight.get(key) === lookup)
+                        this.#chatMemberInflight.delete(key);
+                }
+            })();
+            lookup.promise = task;
+            this.#chatMemberInflight.set(key, lookup);
         }
+        const entry = await task;
+        return signal.aborted ? undefined : entry;
+    }
+    /** `chat_member` / `my_chat_member`: the update carries the new status, so it replaces the cached one. */
+    #applyChatMemberUpdate(update) {
+        const userId = update?.new_chat_member?.user?.id;
+        if (!update?.chat || userId == null)
+            return;
+        const key = `${Number(update.chat.id)}:${userId}`;
+        this.#chatMemberInflight.delete(key);
+        this.#chatMemberFailures.delete(key);
+        this.#chatMemberCache.set(key, telegramChatMemberStanding(update.new_chat_member));
     }
     /** Test / internal: admit a callback query when open. */
     admitCallback(query) {
@@ -482,6 +534,8 @@ export class TelegramEndpoint extends TelegramClient {
             await this[endpointSpec].events.platform(eventName, update);
         }
         else {
+            this.#applyChatMemberUpdate(update.chat_member);
+            this.#applyChatMemberUpdate(update.my_chat_member);
             await this[endpointSpec].events.emitAccepted('platform.receive', Object.freeze({ name: eventName, event: update }));
             return;
         }

package/lib/index.d.ts

@@ -2,5 +2,5 @@ export { TelegramClient, TelegramEndpoint, type TelegramClientApi, type Telegram
 export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, type ResolvedTelegramConfig, type TelegramEndpointConfig, type TelegramCallbackQuery, type TelegramChat, type TelegramChatMember, type TelegramMessage, type TelegramOutboundAction, type TelegramOutboundPlan, type TelegramOutboundUpload, type TelegramUpdate, type TelegramUser, type TelegramWireSegment, } from './protocol.js';
 export { type TelegramClientEventMap } from './client.js';
 export { TelegramAdapter } from './adapter.js';
-export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';
+export { telegramChatMemberStanding, platformPermit, } from './platform-permit.js';
 export type { TelegramPollRequest } from './telegram-client.js';

package/lib/index.js

@@ -1,4 +1,4 @@
 export { TelegramClient, TelegramEndpoint, } from './endpoint.js';
 export { botApiUrl, formatCallbackContent, formatInboundContent, formatOutboundActions, formatOutboundPlan, normalizeWebhookPath, resolveTelegramConfig, senderDisplayName, } from './protocol.js';
 export { TelegramAdapter } from './adapter.js';
-export { checkTelegramPlatformPermit, normalizeTelegramChatMember, platformPermit, telegramGroupPermitResolver, } from './platform-permit.js';
+export { telegramChatMemberStanding, platformPermit, } from './platform-permit.js';