@zhin.js/adapter-telegram 8.0.8 → 9.0.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 9.0.1
+
+### Patch Changes
+
+- f7ee28d: Reject sends without a valid platform message ID. Use the shared Endpoint lifecycle to cancel setup requests and polling, isolate late results from replacement connections, and release Webhook routes on failed startup. Release retry listeners and cancel permission lookups when admission closes, preventing stale messages and permissions from entering reopened endpoints. Correct endpoint ID and Webhook setup documentation.
+- Updated dependencies [f7ee28d]
+  - @zhin.js/adapter@1.2.2
+  - @zhin.js/core@1.5.16
+  - zhin.js@7.0.1
+  - @zhin.js/agent@1.2.1
+
+## 9.0.0
+
+### Patch Changes
+
+- Updated dependencies [12325e1]
+- Updated dependencies [d19e976]
+  - @zhin.js/agent@1.2.0
+  - zhin.js@7.0.0
+
 ## 8.0.8
 
 ### Patch Changes

package/README.md

@@ -9,7 +9,7 @@ Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮
 - 支持私聊与群组
 - 出站 `send({ conversation, payload })` → Bot API（Markdown→安全 HTML / media / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
-- Webhook 模式延期（需 `httpHostToken`）；配置 `polling: false` 会明确报错
+- Webhook 模式通过 `httpHostToken` 注册回调路由，支持 secretToken 校验
 
 ## 安装
 
@@ -40,9 +40,9 @@ pnpm add @zhin.js/adapter-telegram
 | **Bot Token** | 通过 [@BotFather](https://t.me/botfather) 创建并获取 Token |
 | **Polling（默认）** | 本地/生产均可；主动拉取更新，无需公网 HTTPS |
 | **网络** | 出站可访问 `api.telegram.org` |
-| **host-http** | Polling **不需要**；Webhook 延期至下一棒 |
+| **host-http** | Polling **不需要**；Webhook **需要** CLI HTTP Host |
 
-必填字段（`endpoints[i]`）：`name`、`token`。
+必填字段（`endpoints[i]`）：`id`、`token`。
 
 ## 最小配置
 
@@ -52,7 +52,7 @@ plugins:
   telegram:
     # polling: true   # 默认
     endpoints:
-      - name: my-telegram-bot
+      - id: my-telegram-bot
         token: ${TELEGRAM_TOKEN}
 ```
 
@@ -65,13 +65,37 @@ plugins:
 | `TELEGRAM_TOKEN` / `TELEGRAM_BOT_TOKEN` | Bot Token |
 | `TELEGRAM_BOT_NAME` | 可选，默认 endpoint 名 |
 
-## Webhook（延期）
+## Webhook
 
-`polling: false` + `webhook` 目前会抛出明确错误：
+配置 `polling: false`，启用 CLI HTTP Host，并提供公网 HTTPS 回调地址。
+`webhook.path` 必须与反向代理转发路径一致，多账号使用不同路径。
 
-> Telegram webhook mode is deferred until httpHostToken wiring; use polling: true (default) for now
+```yaml
+http:
+  host: 127.0.0.1
+  port: 8086
+plugins:
+  telegram:
+    polling: false
+    endpoints:
+      - id: my-telegram-bot
+        token: ${TELEGRAM_TOKEN}
+    webhook:
+      domain: https://bot.example.com
+      path: /telegram/webhook
+      secretToken: ${TELEGRAM_WEBHOOK_SECRET}
+```
+
+启动时注册 Host 路由并调用 `setWebhook`；停止时释放路由。
+配置 `secretToken` 后，回调须携带匹配的 `X-Telegram-Bot-Api-Secret-Token`，否则返回 403。
+
+## 稳定化范围
 
-下一棒将用 `httpHostToken` 注册 POST 路由，不再使用 Telegraf 自建监听或 legacy host-router。
+当前为 **Advanced / 首批升档候选**，完整适配器测试已纳入 `pnpm check:stable`。
+长轮询停止会中止请求与退避；即使传输层在中止后返回更新，也不会派发或推进 offset。
+轮询 offset 仅保存在当前 Endpoint 内存中，不承诺跨重启去重或业务处理恰好一次。
+Webhook 接收确认不等于业务处理完成；需要幂等性的业务应自行持久化去重。
+详见[平台稳定验收](https://github.com/zhinjs/zhin/blob/main/docs/contributing/platform-acceptance.md)。
 
 ## 消息类型映射
 
@@ -100,7 +124,7 @@ plugins:
 |------|------|
 | 收不到消息 | Token 是否正确；进程已 `open()`；同一 Token 勿多进程同时 polling |
 | Polling 报错 | 检查能否访问 `api.telegram.org`；查看日志 `op: poll` |
-| Webhook 配置报错 | 当前仅支持 polling；去掉 `polling: false` |
+| Webhook 配置报错 | 检查 HTTP Host、公网 HTTPS、反向代理路径与 secretToken |
 | 发送失败 | Token 是否被撤销；查看 Bot API 错误描述 |
 
 ## Documentation

package/lib/endpoint.d.ts

@@ -1,5 +1,4 @@
-import { Endpoint } from 'zhin.js/adapter';
-import type { EndpointContentPort, EndpointControl, EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointContentPort, type EndpointControl, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import { type MessageRef } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';

package/lib/endpoint.js

@@ -1,4 +1,4 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
@@ -54,9 +54,9 @@ export class TelegramEndpoint extends Endpoint {
     #fetch;
     #pollAbort;
     #pollPromise;
-    #routeReleases = [];
+    #lifecycle;
     #open = false;
-    #started = false;
+    #admission;
     #updateOffset = 0;
     #botUserId;
     #botUsername;
@@ -70,6 +70,7 @@ export class TelegramEndpoint extends Endpoint {
     constructor(options) {
         super();
         this.#logger = getAdapterLogger('telegram', options.config.id);
+        this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
     }
@@ -90,78 +91,101 @@ export class TelegramEndpoint extends Endpoint {
         this.#updateOffset = offset;
     }
     async start() {
-        if (this.#started)
-            return;
-        this.#started = true;
-        try {
-            const me = await this.callApi('getMe');
-            this.#botUserId = me.id;
-            this.#botUsername = me.username;
-            if (this.#options.config.mode === 'webhook') {
-                if (!this.#options.http) {
-                    throw new TypeError('Telegram webhook mode requires httpHostToken');
+        await this.#lifecycle.start(async (handle) => {
+            const abort = new AbortController();
+            const routes = [];
+            this.#pollAbort = abort;
+            const cleanup = () => {
+                abort.abort();
+                for (const release of routes.splice(0))
+                    release();
+                if (this.#pollAbort === abort) {
+                    this.#botUserId = undefined;
+                    this.#botUsername = undefined;
                 }
-                this.#routeReleases.push(...registerTelegramWebhookRoutes(this.#options.http, this));
-                const webhook = this.#options.config.webhook;
-                if (!webhook.secretToken) {
-                    // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
-                    this.#logger.warn(formatCompact({
-                        op: 'webhook_no_secret',
+            };
+            handle.onForceClose(cleanup);
+            try {
+                const me = await this.callApi('getMe', {}, abort.signal);
+                if (abort.signal.aborted)
+                    return;
+                this.#botUserId = me.id;
+                this.#botUsername = me.username;
+                if (this.#options.config.mode === 'webhook') {
+                    if (!this.#options.http) {
+                        throw new TypeError('Telegram webhook mode requires httpHostToken');
+                    }
+                    routes.push(...registerTelegramWebhookRoutes(this.#options.http, this));
+                    const webhook = this.#options.config.webhook;
+                    if (!webhook.secretToken) {
+                        // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
+                        this.#logger.warn(formatCompact({
+                            op: 'webhook_no_secret',
+                            endpoint: this.#options.config.id,
+                            path: webhook.path,
+                            hint: 'set webhook.secretToken to authenticate Telegram callbacks',
+                        }));
+                    }
+                    const url = buildWebhookUrl(webhook);
+                    await this.callApi('setWebhook', {
+                        url,
+                        allowed_updates: this.#options.config.allowedUpdates,
+                        ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
+                    }, abort.signal);
+                    if (abort.signal.aborted)
+                        return;
+                    this.#logger.info(formatCompact({
+                        op: 'connect',
                         endpoint: this.#options.config.id,
+                        mode: 'webhook',
                         path: webhook.path,
-                        hint: 'set webhook.secretToken to authenticate Telegram callbacks',
+                        username: me.username,
                     }));
+                    return;
                 }
-                const url = buildWebhookUrl(webhook);
-                await this.callApi('setWebhook', {
-                    url,
-                    allowed_updates: this.#options.config.allowedUpdates,
-                    ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
-                });
+                await this.callApi('deleteWebhook', { drop_pending_updates: false }, abort.signal);
+                if (abort.signal.aborted)
+                    return;
+                this.#pollPromise = runTelegramPollLoop(this, abort.signal);
                 this.#logger.info(formatCompact({
                     op: 'connect',
                     endpoint: this.#options.config.id,
-                    mode: 'webhook',
-                    path: webhook.path,
+                    mode: 'polling',
                     username: me.username,
                 }));
-                return;
             }
-            await this.callApi('deleteWebhook', { drop_pending_updates: false });
-            this.#pollAbort = new AbortController();
-            this.#pollPromise = runTelegramPollLoop(this, this.#pollAbort.signal);
-            this.#logger.info(formatCompact({
-                op: 'connect',
-                endpoint: this.#options.config.id,
-                mode: 'polling',
-                username: me.username,
-            }));
-        }
-        catch (error) {
-            await this.stop();
-            this.#logger.error('Failed to connect Telegram bot:', error);
-            throw error;
-        }
+            catch (error) {
+                const cancelled = abort.signal.aborted;
+                cleanup();
+                if (cancelled)
+                    return;
+                this.#logger.error('Failed to connect Telegram bot:', error);
+                throw error;
+            }
+        });
     }
     open() {
+        if (this.#open)
+            return;
+        this.#admission = new AbortController();
         this.#open = true;
     }
     close() {
         this.#open = false;
+        this.#admission?.abort();
+        this.#chatMemberCache.clear();
     }
     async stop() {
-        this.#open = false;
-        this.#pollAbort?.abort();
+        this.close();
+        const polling = this.#pollPromise;
+        this.#pollPromise = undefined;
+        await this.#lifecycle.stop();
         try {
-            await this.#pollPromise;
+            await polling;
         }
         catch {
             /* poll loop exit */
         }
-        for (const release of this.#routeReleases.splice(0))
-            release();
-        this.#chatMemberCache.clear();
-        this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
@@ -172,10 +196,14 @@ export class TelegramEndpoint extends Endpoint {
             const result = form
                 ? await this.callApiForm(action.method, form)
                 : await this.callApi(action.method, action.params);
-            if (result.message_id != null)
-                lastId = String(result.message_id);
+            if (!result || !Number.isSafeInteger(result.message_id) || result.message_id <= 0) {
+                throw new Error(`Telegram API ${action.method} returned no valid message_id; delivery is unconfirmed`);
+            }
+            lastId = String(result.message_id);
         }
-        return lastId || `telegram-${Date.now()}`;
+        if (!lastId)
+            throw new Error('Telegram message contains no sendable actions');
+        return lastId;
     }
     async recallMessage(message) {
         if (!message.id || message.id.startsWith('telegram-'))
@@ -258,10 +286,10 @@ export class TelegramEndpoint extends Endpoint {
     }
     /** Test / internal: admit a message when open. */
     admit(msg) {
-        if (!this.#open)
+        if (!this.#open || !this.#admission)
             return;
         const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
-        void this.#admitWithSenderRole(msg, conversation).catch((err) => {
+        void this.#admitWithSenderRole(msg, conversation, this.#admission.signal).catch((err) => {
             this.#logger.warn(formatCompact({
                 op: 'telegram_gateway_receive_failed',
                 target: `${conversation.kind}:${conversation.id}`,
@@ -269,8 +297,10 @@ export class TelegramEndpoint extends Endpoint {
             }));
         });
     }
-    async #admitWithSenderRole(msg, conversation) {
-        const permit = await this.#resolveGroupSenderPermit(msg);
+    async #admitWithSenderRole(msg, conversation, signal) {
+        const permit = await this.#resolveGroupSenderPermit(msg, signal);
+        if (signal.aborted)
+            return;
         // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
         const mentioned = this.#isBotMentioned(msg);
         await this.emit('message.receive', {
@@ -314,7 +344,7 @@ export class TelegramEndpoint extends Endpoint {
         return false;
     }
     /** 群消息 sender role 解析：getChatMember + 60s 缓存（对齐旧 enrichGroupSender）。 */
-    async #resolveGroupSenderPermit(msg) {
+    async #resolveGroupSenderPermit(msg, signal) {
         if (msg.chat.type === 'private' || !msg.from?.id)
             return undefined;
         const chatId = Number(msg.chat.id);
@@ -329,7 +359,9 @@ export class TelegramEndpoint extends Endpoint {
             const member = await this.callApi('getChatMember', {
                 chat_id: chatId,
                 user_id: userId,
-            });
+            }, signal);
+            if (signal.aborted)
+                return undefined;
             const normalized = normalizeTelegramChatMember(member);
             const entry = { at: now, ...normalized };
             this.#chatMemberCache.set(key, entry);

package/lib/polling.js

@@ -18,6 +18,9 @@ export async function runTelegramPollLoop(host, abortSignal) {
             }, abortSignal);
             consecutiveFailures = 0;
             for (const update of updates) {
+                // A transport may resolve after cancellation; never admit that late batch.
+                if (abortSignal.aborted)
+                    return;
                 host.setUpdateOffset(update.update_id + 1);
                 host.handleUpdate(update);
             }
@@ -43,10 +46,12 @@ function sleep(ms, signal) {
             resolve();
             return;
         }
-        const timer = setTimeout(resolve, ms);
-        signal?.addEventListener('abort', () => {
+        const finish = () => {
             clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
             resolve();
-        }, { once: true });
+        };
+        const timer = setTimeout(finish, ms);
+        signal?.addEventListener('abort', finish, { once: true });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "8.0.8",
+  "version": "9.0.1",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,8 +32,8 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.2.1",
-    "@zhin.js/core": "1.5.15",
+    "@zhin.js/adapter": "1.2.2",
+    "@zhin.js/core": "1.5.16",
     "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/host-http": "1.0.17",
     "@zhin.js/im-contract": "1.0.4",
@@ -41,12 +41,12 @@
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.2.1",
-    "@zhin.js/agent": "1.1.22",
+    "@zhin.js/adapter": "1.2.2",
+    "@zhin.js/agent": "1.2.1",
     "@zhin.js/command": "1.0.16",
-    "@zhin.js/core": "1.5.15",
+    "@zhin.js/core": "1.5.16",
     "@zhin.js/permission": "1.0.4",
-    "zhin.js": "6.0.15"
+    "zhin.js": "7.0.1"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -67,9 +67,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.22",
+    "@zhin.js/agent": "1.2.1",
     "@zhin.js/host-http": "1.0.17",
-    "zhin.js": "6.0.15"
+    "zhin.js": "7.0.1"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -1,9 +1,12 @@
-import { Endpoint } from 'zhin.js/adapter';
+import {
+  Endpoint, createEndpointLifecycle,
+  type EndpointLifecycle, type EndpointContentPort, type EndpointContentResolveContext,
+  type EndpointControl, type EndpointSendRequest,
+} from 'zhin.js/adapter';
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
-import type { EndpointContentPort, EndpointContentResolveContext, EndpointControl, EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
   type ConversationRef,
@@ -158,9 +161,9 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
   readonly #fetch: TelegramFetch;
   #pollAbort?: AbortController;
   #pollPromise?: Promise<void>;
-  #routeReleases: HttpRouteRegistration[] = [];
+  readonly #lifecycle: EndpointLifecycle;
   #open = false;
-  #started = false;
+  #admission?: AbortController;
   #updateOffset = 0;
   #botUserId?: number;
   #botUsername?: string;
@@ -175,6 +178,7 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
   constructor(options: TelegramEndpointOptions) {
     super();
     this.#logger = getAdapterLogger('telegram', options.config.id);
+    this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
     this.#options = options;
     this.#fetch = options.fetch ?? globalThis.fetch;
   }
@@ -201,79 +205,98 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
   }
 
   async start(): Promise<void> {
-    if (this.#started) return;
-    this.#started = true;
-    try {
-      const me = await this.callApi<{ id?: number; username?: string; first_name?: string }>('getMe');
-      this.#botUserId = me.id;
-      this.#botUsername = me.username;
-
-      if (this.#options.config.mode === 'webhook') {
-        if (!this.#options.http) {
-          throw new TypeError('Telegram webhook mode requires httpHostToken');
+    await this.#lifecycle.start(async (handle) => {
+      const abort = new AbortController();
+      const routes: HttpRouteRegistration[] = [];
+      this.#pollAbort = abort;
+      const cleanup = () => {
+        abort.abort();
+        for (const release of routes.splice(0)) release();
+        if (this.#pollAbort === abort) {
+          this.#botUserId = undefined;
+          this.#botUsername = undefined;
         }
-        this.#routeReleases.push(...registerTelegramWebhookRoutes(this.#options.http, this));
-        const webhook = this.#options.config.webhook!;
-        if (!webhook.secretToken) {
-          // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
-          this.#logger.warn(formatCompact({
-            op: 'webhook_no_secret',
+      };
+      handle.onForceClose(cleanup);
+      try {
+        const me = await this.callApi<{ id?: number; username?: string; first_name?: string }>('getMe', {}, abort.signal);
+        if (abort.signal.aborted) return;
+        this.#botUserId = me.id;
+        this.#botUsername = me.username;
+
+        if (this.#options.config.mode === 'webhook') {
+          if (!this.#options.http) {
+            throw new TypeError('Telegram webhook mode requires httpHostToken');
+          }
+          routes.push(...registerTelegramWebhookRoutes(this.#options.http, this));
+          const webhook = this.#options.config.webhook!;
+          if (!webhook.secretToken) {
+            // 未配 secretToken 时 webhook 无鉴权：任何人知道 path 即可注入假 update。
+            this.#logger.warn(formatCompact({
+              op: 'webhook_no_secret',
+              endpoint: this.#options.config.id,
+              path: webhook.path,
+              hint: 'set webhook.secretToken to authenticate Telegram callbacks',
+            }));
+          }
+          const url = buildWebhookUrl(webhook);
+          await this.callApi('setWebhook', {
+            url,
+            allowed_updates: this.#options.config.allowedUpdates,
+            ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
+          }, abort.signal);
+          if (abort.signal.aborted) return;
+          this.#logger.info(formatCompact({
+            op: 'connect',
             endpoint: this.#options.config.id,
+            mode: 'webhook',
             path: webhook.path,
-            hint: 'set webhook.secretToken to authenticate Telegram callbacks',
+            username: me.username,
           }));
+          return;
         }
-        const url = buildWebhookUrl(webhook);
-        await this.callApi('setWebhook', {
-          url,
-          allowed_updates: this.#options.config.allowedUpdates,
-          ...(webhook.secretToken ? { secret_token: webhook.secretToken } : {}),
-        });
+
+        await this.callApi('deleteWebhook', { drop_pending_updates: false }, abort.signal);
+        if (abort.signal.aborted) return;
+        this.#pollPromise = runTelegramPollLoop(this, abort.signal);
         this.#logger.info(formatCompact({
           op: 'connect',
           endpoint: this.#options.config.id,
-          mode: 'webhook',
-          path: webhook.path,
+          mode: 'polling',
           username: me.username,
         }));
-        return;
+      } catch (error) {
+        const cancelled = abort.signal.aborted;
+        cleanup();
+        if (cancelled) return;
+        this.#logger.error('Failed to connect Telegram bot:', error);
+        throw error;
       }
-
-      await this.callApi('deleteWebhook', { drop_pending_updates: false });
-      this.#pollAbort = new AbortController();
-      this.#pollPromise = runTelegramPollLoop(this, this.#pollAbort.signal);
-      this.#logger.info(formatCompact({
-        op: 'connect',
-        endpoint: this.#options.config.id,
-        mode: 'polling',
-        username: me.username,
-      }));
-    } catch (error) {
-      await this.stop();
-      this.#logger.error('Failed to connect Telegram bot:', error);
-      throw error;
-    }
+    });
   }
 
   open(): void {
+    if (this.#open) return;
+    this.#admission = new AbortController();
     this.#open = true;
   }
 
   close(): void {
     this.#open = false;
+    this.#admission?.abort();
+    this.#chatMemberCache.clear();
   }
 
   async stop(): Promise<void> {
-    this.#open = false;
-    this.#pollAbort?.abort();
+    this.close();
+    const polling = this.#pollPromise;
+    this.#pollPromise = undefined;
+    await this.#lifecycle.stop();
     try {
-      await this.#pollPromise;
+      await polling;
     } catch {
       /* poll loop exit */
     }
-    for (const release of this.#routeReleases.splice(0)) release();
-    this.#chatMemberCache.clear();
-    this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
@@ -285,9 +308,13 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
       const result = form
         ? await this.callApiForm<{ message_id?: number }>(action.method, form)
         : await this.callApi<{ message_id?: number }>(action.method, action.params);
-      if (result.message_id != null) lastId = String(result.message_id);
+      if (!result || !Number.isSafeInteger(result.message_id) || result.message_id! <= 0) {
+        throw new Error(`Telegram API ${action.method} returned no valid message_id; delivery is unconfirmed`);
+      }
+      lastId = String(result.message_id);
     }
-    return lastId || `telegram-${Date.now()}`;
+    if (!lastId) throw new Error('Telegram message contains no sendable actions');
+    return lastId;
   }
 
   async recallMessage(message: MessageRef): Promise<void> {
@@ -376,9 +403,9 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
 
   /** Test / internal: admit a message when open. */
   admit(msg: TelegramMessage): void {
-    if (!this.#open) return;
+    if (!this.#open || !this.#admission) return;
     const conversation = telegramInboundConversation(String(this.#options.id), msg.chat);
-    void this.#admitWithSenderRole(msg, conversation).catch((err) => {
+    void this.#admitWithSenderRole(msg, conversation, this.#admission.signal).catch((err) => {
       this.#logger.warn(formatCompact({
         op: 'telegram_gateway_receive_failed',
         target: `${conversation.kind}:${conversation.id}`,
@@ -387,8 +414,9 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
     });
   }
 
-  async #admitWithSenderRole(msg: TelegramMessage, conversation: ConversationRef): Promise<void> {
-    const permit = await this.#resolveGroupSenderPermit(msg);
+  async #admitWithSenderRole(msg: TelegramMessage, conversation: ConversationRef, signal: AbortSignal): Promise<void> {
+    const permit = await this.#resolveGroupSenderPermit(msg, signal);
+    if (signal.aborted) return;
     // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
     const mentioned = this.#isBotMentioned(msg);
     await this.emit('message.receive', {
@@ -430,7 +458,7 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
   }
 
   /** 群消息 sender role 解析：getChatMember + 60s 缓存（对齐旧 enrichGroupSender）。 */
-  async #resolveGroupSenderPermit(msg: TelegramMessage): Promise<ChatMemberPermit | undefined> {
+  async #resolveGroupSenderPermit(msg: TelegramMessage, signal: AbortSignal): Promise<ChatMemberPermit | undefined> {
     if (msg.chat.type === 'private' || !msg.from?.id) return undefined;
     const chatId = Number(msg.chat.id);
     const userId = msg.from.id;
@@ -443,7 +471,8 @@ export class TelegramEndpoint extends Endpoint<TelegramClient> {
       const member = await this.callApi<TelegramChatMember>('getChatMember', {
         chat_id: chatId,
         user_id: userId,
-      });
+      }, signal);
+      if (signal.aborted) return undefined;
       const normalized = normalizeTelegramChatMember(member);
       const entry: ChatMemberPermit = { at: now, ...normalized };
       this.#chatMemberCache.set(key, entry);

package/src/polling.ts

@@ -36,6 +36,8 @@ export async function runTelegramPollLoop(
       }, abortSignal);
       consecutiveFailures = 0;
       for (const update of updates) {
+        // A transport may resolve after cancellation; never admit that late batch.
+        if (abortSignal.aborted) return;
         host.setUpdateOffset(update.update_id + 1);
         host.handleUpdate(update);
       }
@@ -63,10 +65,12 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
       resolve();
       return;
     }
-    const timer = setTimeout(resolve, ms);
-    signal?.addEventListener('abort', () => {
+    const finish = () => {
       clearTimeout(timer);
+      signal?.removeEventListener('abort', finish);
       resolve();
-    }, { once: true });
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener('abort', finish, { once: true });
   });
 }