@zhin.js/adapter-telegram 1.1.3 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: Fix adapter connection races, transport health reporting, candidate rollback and delivery acknowledgement boundaries. Separate generation admission from locally observed connectivity, reject unconfirmed message receipts, and mark uncertain delivery results without recommending automatic replay.
+
+  Class and compact endpoints should expose a `transportState` getter to report physical connection or local listener health. Unobserved endpoints now report an unknown transport and remain offline in diagnostics. Platform stability tiers remain unchanged until real account acceptance evidence is available.
+
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
+## 1.1.4
+
+### Patch Changes
+
+- Updated dependencies [43eda99]
+- Updated dependencies [0de4836]
+  - @zhin.js/core@1.1.39
+  - @zhin.js/adapter@1.1.15
+
 ## 1.1.3
 
 ### Patch Changes

package/README.md

@@ -11,6 +11,18 @@ Zhin.js Telegram Bot API 适配器（Plugin Runtime），默认通过 **长轮
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Webhook 模式通过 `httpHostToken` 注册回调路由，支持 secretToken 校验
 
+### 更新确认与重投
+
+- Polling 在 `handleUpdate()` 的框架接纳 Promise 成功后推进本地 offset；同批次接纳失败会停止处理后续 update，保留失败 update 供下一次重投。Telegram 在下一次携带更高 offset 的 `getUpdates` 请求时才确认旧 update。
+- Webhook 等待框架接纳后返回 200；请求到达时端点已关闭、尚未进入 Core 的处理被取消或接纳失败返回 503，非法 JSON/update_id 返回 400，secret 不匹配返回 403。仅 native `platform.receive` 成功不等于消息接纳成功，还需等待 canonical `message.receive`。已经进入 Core 的业务由 generation lease 完成，随后成功仍返回 200，即使端点期间关闭，避免把完成的副作用错误地触发重投。
+- 每个 Endpoint 最多保存 2,048 个已接纳 update_id，并合并相同 ID 的并发请求；最多允许 256 个不同 ID 的并发接纳，超过容量返回失败供重投。失败不计入已接纳集合。
+- 去重状态和 polling offset 属于当前 Endpoint generation，**不是耐久 checkpoint**。HMR/进程重启会清空；已接纳但尚未由下一轮 offset 请求确认的尾部 update，或 webhook 200 尚未到达 Telegram 的 update，可能再次投递。当前提供至少一次重投路径，不保证跨重启恰好一次；有外部副作用的插件应使用 update/message ID 做持久幂等。
+- JSON API 和 multipart/form-data 默认 30 秒 deadline；长轮询允许服务端 timeout 外加 15 秒。客户端 `callApi` / `callApiForm` 第三个参数可传 AbortSignal，端点停止也会取消当前 API 请求。`TelegramApiError.kind` 区分 timeout、cancelled、network、http、authentication、rate_limit、api、invalid_response；429 可读取 `retryAfterSeconds`。发送失败不会自动重试，超时/网络中断的送达结果可能未知。
+- `TelegramApiError` 同时遵循 `EndpointDeliveryError` 合同：明确 Bot API 拒绝为 rejected，网络/超时或异常响应为 unknown，发出请求前取消为 not_sent。一个 payload 拆成多个发送动作时，已有动作成功而后续失败会报告 `partial_delivery` / unknown，并在 cause 保留后续错误；不能把整条消息视为全部拒绝或安全重发。
+- Polling 请求失败时 transport 状态为 reconnecting，成功拉取后恢复 open；Webhook 的 open 代表本地路由与注册成功，不能证明公网代理实时可达。
+
+确认与重试规则依据 [Telegram Bot API getUpdates / setWebhook](https://core.telegram.org/bots/api#getupdates)。
+
 ## 安装
 
 ```bash

package/lib/api-error.d.ts

@@ -0,0 +1,13 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Machine-readable failures. Sending is never automatically retried. */
+export type TelegramApiErrorKind = 'timeout' | 'cancelled' | 'network' | 'http' | 'authentication' | 'rate_limit' | 'api' | 'invalid_response';
+export declare class TelegramApiError extends EndpointDeliveryError {
+    readonly kind: TelegramApiErrorKind;
+    readonly status?: number;
+    readonly retryAfterSeconds?: number;
+    constructor(kind: TelegramApiErrorKind, message: string, details?: {
+        readonly status?: number;
+        readonly retryAfterSeconds?: number;
+        readonly disposition?: EndpointDeliveryError['disposition'];
+    });
+}

package/lib/api-error.js

@@ -0,0 +1,16 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+export class TelegramApiError extends EndpointDeliveryError {
+    kind;
+    status;
+    retryAfterSeconds;
+    constructor(kind, message, details = {}) {
+        const disposition = details.disposition ?? (kind === 'authentication' || kind === 'rate_limit' || kind === 'api' ? 'rejected' : 'unknown');
+        super(disposition === 'rejected' ? 'platform_rejected'
+            : kind === 'timeout' ? 'endpoint_timeout'
+                : kind === 'cancelled' ? 'endpoint_cancelled' : 'delivery_unconfirmed', message, disposition);
+        this.name = 'TelegramApiError';
+        this.kind = kind;
+        this.status = details.status;
+        this.retryAfterSeconds = details.retryAfterSeconds;
+    }
+}

package/lib/endpoint.d.ts

@@ -1,7 +1,8 @@
-import { Endpoint, type EndpointContentPort, type EndpointControl, type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointContentPort, type EndpointControl, type EndpointSendRequest, type EndpointTransportState } 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';
+export { TelegramApiError } from './api-error.js';
 import { type ResolvedTelegramConfig, type TelegramCallbackQuery, type TelegramChatMember, type TelegramMessage, type TelegramUpdate } from './protocol.js';
 export type TelegramFetch = (url: string, init?: {
     readonly method?: string;
@@ -23,10 +24,12 @@ export interface TelegramEndpointOptions {
     readonly config: ResolvedTelegramConfig;
     readonly http?: HttpHost;
     readonly fetch?: TelegramFetch;
+    /** Internal transport deadline override; long polling always allows its server timeout. */
+    readonly requestTimeoutMs?: number;
 }
 export interface TelegramClientApi {
-    callApi<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
-    callApiForm<T = unknown>(method: string, form: FormData): Promise<T>;
+    callApi<T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    callApiForm<T = unknown>(method: string, form: FormData, signal?: AbortSignal): Promise<T>;
     pinMessage(chatId: number, messageId: number): Promise<boolean>;
     unpinMessage(chatId: number, messageId?: number): Promise<boolean>;
     setChatDescription(chatId: number, description: string): Promise<boolean>;
@@ -46,8 +49,8 @@ export interface TelegramClientApi {
 export declare class TelegramClient implements TelegramClientApi {
     readonly api: TelegramClientApi;
     constructor(api: TelegramClientApi);
-    callApi: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>;
-    callApiForm: <T = unknown>(method: string, form: FormData) => Promise<T>;
+    callApi: <T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal) => Promise<T>;
+    callApiForm: <T = unknown>(method: string, form: FormData, signal?: AbortSignal) => Promise<T>;
     pinMessage: (chatId: number, messageId: number) => Promise<boolean>;
     unpinMessage: (chatId: number, messageId?: number) => Promise<boolean>;
     setChatDescription: (chatId: number, description: string) => Promise<boolean>;
@@ -76,6 +79,8 @@ export declare class TelegramEndpoint extends Endpoint<TelegramClient> {
     constructor(options: TelegramEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
+    get transportState(): EndpointTransportState;
+    setPollingHealthy(healthy: boolean): void;
     get config(): ResolvedTelegramConfig;
     get allowedUpdates(): readonly string[];
     getUpdateOffset(): number;
@@ -91,7 +96,7 @@ export declare class TelegramEndpoint extends Endpoint<TelegramClient> {
     /** Test / internal: admit a callback query when open. */
     admitCallback(query: TelegramCallbackQuery): void;
     /** Used by webhook / polling handlers. */
-    handleUpdate(update: TelegramUpdate): void;
+    handleUpdate(update: TelegramUpdate): Promise<void>;
     callApi<T = unknown>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
     /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
     callApiForm<T = unknown>(method: string, form: FormData, signal?: AbortSignal): Promise<T>;

package/lib/endpoint.js

@@ -3,21 +3,27 @@ import { Endpoint, createEndpointLifecycle, } from 'zhin.js/adapter';
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
 import { readFile } from 'node:fs/promises';
+import { EndpointDeliveryError, } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { runTelegramPollLoop } from './polling.js';
+import { TelegramApiError } from './api-error.js';
+export { TelegramApiError } from './api-error.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
 import { botApiUrl, buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
+const ADMITTED_UPDATE_LIMIT = 2_048;
+const INFLIGHT_UPDATE_LIMIT = 256;
+const DEFAULT_API_TIMEOUT_MS = 30_000;
 /** Telegram Bot API client carried by message, update and lifecycle events. */
 export class TelegramClient {
     api;
     constructor(api) {
         this.api = api;
     }
-    callApi = (method, params = {}) => this.api.callApi(method, params);
-    callApiForm = (method, form) => this.api.callApiForm(method, form);
+    callApi = (method, params = {}, signal) => this.api.callApi(method, params, signal);
+    callApiForm = (method, form, signal) => this.api.callApiForm(method, form, signal);
     pinMessage = (chatId, messageId) => this.api.pinMessage(chatId, messageId);
     unpinMessage = (chatId, messageId) => this.api.unpinMessage(chatId, messageId);
     setChatDescription = (chatId, description) => this.api.setChatDescription(chatId, description);
@@ -36,8 +42,8 @@ export class TelegramClient {
  */
 export class TelegramEndpoint extends Endpoint {
     client = new TelegramClient({
-        callApi: (method, params) => this.callApi(method, params),
-        callApiForm: (method, form) => this.callApiForm(method, form),
+        callApi: (method, params, signal) => this.callApi(method, params, signal),
+        callApiForm: (method, form, signal) => this.callApiForm(method, form, signal),
         pinMessage: (chatId, messageId) => this.pinMessage(chatId, messageId),
         unpinMessage: (chatId, messageId) => this.unpinMessage(chatId, messageId),
         setChatDescription: (chatId, description) => this.setChatDescription(chatId, description),
@@ -52,12 +58,16 @@ export class TelegramEndpoint extends Endpoint {
     #logger;
     #options;
     #fetch;
+    #apiAbort = new AbortController();
     #pollAbort;
     #pollPromise;
     #lifecycle;
     #open = false;
     #admission;
     #updateOffset = 0;
+    #pollingHealthy = true;
+    #admittedUpdates = new Set();
+    #inflightUpdates = new Map();
     #botUserId;
     #botUsername;
     #chatMemberCache = new Map();
@@ -69,6 +79,9 @@ export class TelegramEndpoint extends Endpoint {
     });
     constructor(options) {
         super();
+        if (options.requestTimeoutMs !== undefined && (!Number.isFinite(options.requestTimeoutMs) || options.requestTimeoutMs <= 0)) {
+            throw new TypeError('Telegram requestTimeoutMs must be a positive finite number');
+        }
         this.#logger = getAdapterLogger('telegram', options.config.id);
         this.#lifecycle = createEndpointLifecycle({ name: options.config.id, reconnect: false });
         this.#options = options;
@@ -78,6 +91,14 @@ export class TelegramEndpoint extends Endpoint {
     get isOpen() {
         return this.#open;
     }
+    get transportState() {
+        const state = this.#lifecycle.state;
+        return state === 'open' && this.#options.config.mode === 'polling' && !this.#pollingHealthy
+            ? 'reconnecting' : state;
+    }
+    setPollingHealthy(healthy) {
+        this.#pollingHealthy = healthy;
+    }
     get config() {
         return this.#options.config;
     }
@@ -91,6 +112,8 @@ export class TelegramEndpoint extends Endpoint {
         this.#updateOffset = offset;
     }
     async start() {
+        if (this.#apiAbort.signal.aborted)
+            this.#apiAbort = new AbortController();
         await this.#lifecycle.start(async (handle) => {
             const abort = new AbortController();
             const routes = [];
@@ -177,6 +200,7 @@ export class TelegramEndpoint extends Endpoint {
     }
     async stop() {
         this.close();
+        this.#apiAbort.abort();
         const polling = this.#pollPromise;
         this.#pollPromise = undefined;
         await this.#lifecycle.stop();
@@ -189,21 +213,33 @@ export class TelegramEndpoint extends Endpoint {
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const plan = formatOutboundPlan(conversation.id, payload);
         let lastId = '';
-        for (const action of plan.actions) {
-            const form = await this.#buildUploadForm(action.params, plan.uploads);
-            const result = form
-                ? await this.callApiForm(action.method, form)
-                : await this.callApi(action.method, action.params);
-            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`);
+        let completedActions = 0;
+        try {
+            const plan = formatOutboundPlan(conversation.id, payload);
+            for (const action of plan.actions) {
+                const form = await this.#buildUploadForm(action.params, plan.uploads);
+                const result = form
+                    ? await this.callApiForm(action.method, form)
+                    : await this.callApi(action.method, action.params);
+                if (!result || !Number.isSafeInteger(result.message_id) || result.message_id <= 0) {
+                    throw new EndpointDeliveryError('delivery_unconfirmed', `Telegram API ${action.method} returned no valid message_id; delivery is unconfirmed`, 'unknown');
+                }
+                lastId = String(result.message_id);
+                completedActions += 1;
+            }
+            if (!lastId)
+                throw new EndpointDeliveryError('empty_message', 'Telegram message contains no sendable actions', 'not_sent');
+            return lastId;
+        }
+        catch (error) {
+            if (completedActions > 0) {
+                throw new EndpointDeliveryError('partial_delivery', `Telegram message failed after ${completedActions} confirmed action(s); complete delivery is unconfirmed`, 'unknown', { cause: error });
             }
-            lastId = String(result.message_id);
+            if (error instanceof EndpointDeliveryError)
+                throw error;
+            throw new EndpointDeliveryError('invalid_payload', 'Telegram message could not be prepared', 'not_sent', { cause: error });
         }
-        if (!lastId)
-            throw new Error('Telegram message contains no sendable actions');
-        return lastId;
     }
     async recallMessage(message) {
         if (!message.id || message.id.startsWith('telegram-'))
@@ -224,37 +260,39 @@ export class TelegramEndpoint extends Endpoint {
             signal.throwIfAborted();
             const file = await this.callApi('getFile', {
                 file_id: reference.media.value,
-            });
+            }, signal);
             if (!file.file_path)
                 return Object.freeze({ status: 'not_found', code: 'telegram_file_not_found' });
             if ((file.file_size ?? 0) > 26_214_400)
                 return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
-            const response = await this.#fetch(`${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`, { signal });
-            if (!response.ok)
-                return Object.freeze({ status: 'failed', code: 'telegram_file_download_failed' });
-            if (!response.arrayBuffer)
-                return Object.freeze({ status: 'failed', code: 'telegram_binary_transport_unavailable' });
-            const bytes = Buffer.from(await response.arrayBuffer());
-            if (bytes.byteLength > 26_214_400)
-                return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
-            return Object.freeze({
-                status: 'resolved',
-                reference,
-                value: Object.freeze({
-                    kind: 'base64',
-                    value: bytes.toString('base64'),
-                    ...(response.headers?.get('content-type')?.split(';')[0] || reference.media.mime_type
-                        ? { mime_type: response.headers?.get('content-type')?.split(';')[0] ?? reference.media.mime_type }
-                        : {}),
-                    ...(reference.media.file_name ? { file_name: reference.media.file_name } : {}),
-                    size: bytes.byteLength,
-                }),
-            });
+            return await this.#withRequestDeadline('downloadFile', async (downloadSignal) => {
+                const response = await this.#fetch(`${this.#options.config.apiBaseUrl}/file/bot${this.#options.config.token}/${file.file_path}`, { signal: downloadSignal });
+                if (!response.ok)
+                    return Object.freeze({ status: 'failed', code: 'telegram_file_download_failed' });
+                if (!response.arrayBuffer)
+                    return Object.freeze({ status: 'failed', code: 'telegram_binary_transport_unavailable' });
+                const bytes = Buffer.from(await response.arrayBuffer());
+                if (bytes.byteLength > 26_214_400)
+                    return Object.freeze({ status: 'forbidden', code: 'media_size_limit' });
+                return Object.freeze({
+                    status: 'resolved',
+                    reference,
+                    value: Object.freeze({
+                        kind: 'base64',
+                        value: bytes.toString('base64'),
+                        ...(response.headers?.get('content-type')?.split(';')[0] || reference.media.mime_type
+                            ? { mime_type: response.headers?.get('content-type')?.split(';')[0] ?? reference.media.mime_type }
+                            : {}),
+                        ...(reference.media.file_name ? { file_name: reference.media.file_name } : {}),
+                        size: bytes.byteLength,
+                    }),
+                });
+            }, signal);
         }
-        catch (error) {
+        catch {
             if (signal.aborted)
                 return Object.freeze({ status: 'expired', code: 'turn_aborted' });
-            return Object.freeze({ status: 'failed', code: 'telegram_file_resolution_failed', message: error instanceof Error ? error.message : String(error) });
+            return Object.freeze({ status: 'failed', code: 'telegram_file_resolution_failed', message: 'Telegram file resolution failed' });
         }
     }
     /**
@@ -299,11 +337,10 @@ export class TelegramEndpoint extends Endpoint {
     }
     async #admitWithSenderRole(msg, conversation, signal) {
         const permit = await this.#resolveGroupSenderPermit(msg, signal);
-        if (signal.aborted)
-            return;
+        signal.throwIfAborted();
         // 新 Runtime Message.content 为纯文本：@ 本机只能经 metadata 传递
         const mentioned = this.#isBotMentioned(msg);
-        await this.emit('message.receive', {
+        await this.emitAccepted('message.receive', {
             conversation,
             message: { conversation, id: String(msg.message_id) },
             content: formatInboundContent(msg),
@@ -392,13 +429,21 @@ export class TelegramEndpoint extends Endpoint {
     admitCallback(query) {
         if (!this.#open)
             return;
+        void this.#admitCallback(query).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'telegram_gateway_receive_failed',
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #admitCallback(query) {
         const endpointKey = String(this.#options.id);
         const msg = query.message;
         // 无挂载消息的 callback（如 inline 模式）退化为 sender 私聊会话
         const conversation = msg
             ? telegramInboundConversation(endpointKey, msg.chat)
             : telegramInboundConversation(endpointKey, { id: query.from.id, type: 'private' });
-        void this.emit('message.receive', {
+        await this.emitAccepted('message.receive', {
             conversation,
             message: { conversation, id: query.id },
             content: formatCallbackContent(query),
@@ -410,30 +455,58 @@ export class TelegramEndpoint extends Endpoint {
                 payload: query.data,
                 sourceMessageId: msg ? String(msg.message_id) : undefined,
             }),
-        }).catch((err) => {
-            this.#logger.warn(formatCompact({
-                op: 'telegram_gateway_receive_failed',
-                target: `${conversation.kind}:${conversation.id}`,
-                error: err instanceof Error ? err.message : String(err),
-            }));
         });
     }
     /** Used by webhook / polling handlers. */
-    handleUpdate(update) {
+    async handleUpdate(update) {
+        if (!this.#open || !this.#admission)
+            throw new Error('Telegram endpoint is not accepting updates');
+        if (!Number.isSafeInteger(update.update_id) || update.update_id < 0) {
+            throw new TypeError('Telegram update_id must be a non-negative safe integer');
+        }
+        if (this.#admittedUpdates.has(update.update_id))
+            return;
+        const pending = this.#inflightUpdates.get(update.update_id);
+        if (pending)
+            return pending;
+        if (this.#inflightUpdates.size >= INFLIGHT_UPDATE_LIMIT) {
+            throw new Error('Telegram update admission capacity exhausted');
+        }
+        const admission = this.#admission;
+        const receiving = (async () => {
+            // Once canonical dispatch enters Core, its generation lease drains the work.
+            // Closing the transport cannot turn successful business processing into a retry.
+            await this.#receiveUpdate(update, admission.signal);
+            this.#admittedUpdates.add(update.update_id);
+            if (this.#admittedUpdates.size > ADMITTED_UPDATE_LIMIT) {
+                this.#admittedUpdates.delete(this.#admittedUpdates.values().next().value);
+            }
+        })();
+        this.#inflightUpdates.set(update.update_id, receiving);
+        try {
+            await receiving;
+        }
+        finally {
+            this.#inflightUpdates.delete(update.update_id);
+        }
+    }
+    async #receiveUpdate(update, signal) {
         const eventName = update.message
             ? 'message'
             : update.callback_query
                 ? 'callback_query'
                 : 'update';
-        void this.emitPlatform(eventName, update).catch((error) => {
-            this.#logger.warn(formatCompact({
-                op: 'telegram_platform_event_failed',
-                event: eventName,
-                error: error instanceof Error ? error.message : String(error),
-            }));
-        });
+        if (update.message || update.callback_query) {
+            await this.emitPlatform(eventName, update);
+        }
+        else {
+            await this.emitAccepted('platform.receive', Object.freeze({ name: eventName, event: update }));
+            return;
+        }
+        signal.throwIfAborted();
         if (update.message) {
-            this.admit(update.message);
+            const conversation = telegramInboundConversation(String(this.#options.id), update.message.chat);
+            await this.#admitWithSenderRole(update.message, conversation, signal);
             return;
         }
         if (update.callback_query) {
@@ -443,28 +516,76 @@ export class TelegramEndpoint extends Endpoint {
                     /* already answered */
                 });
             }
-            this.admitCallback(query);
+            await this.#admitCallback(query);
         }
     }
     async callApi(method, params = {}, signal) {
-        const url = botApiUrl(this.#options.config, method);
-        const response = await this.#fetch(url, {
+        return this.#requestApi(method, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(params),
-            signal,
-        });
-        return this.#parseApiResponse(method, response);
+        }, signal, method === 'getUpdates'
+            ? Math.max(this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS, (Number(params.timeout) || 0) * 1_000 + 15_000)
+            : undefined);
     }
     /** multipart/form-data 变体（attach:// 媒体上传；Content-Type 边界由 FormData 自带）。 */
     async callApiForm(method, form, signal) {
-        const url = botApiUrl(this.#options.config, method);
-        const response = await this.#fetch(url, {
+        return this.#requestApi(method, {
             method: 'POST',
             body: form,
-            signal,
-        });
-        return this.#parseApiResponse(method, response);
+        }, signal);
+    }
+    async #requestApi(method, init, signal, timeoutMs = this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS) {
+        return this.#withRequestDeadline(method, async (requestSignal) => {
+            const response = await this.#fetch(botApiUrl(this.#options.config, method), { ...init, signal: requestSignal });
+            return this.#parseApiResponse(method, response);
+        }, signal, timeoutMs);
+    }
+    async #withRequestDeadline(method, requestOperation, signal, timeoutMs = this.#options.requestTimeoutMs ?? DEFAULT_API_TIMEOUT_MS) {
+        const abort = new AbortController();
+        let issued = false;
+        const sources = [...new Set([signal, this.#pollAbort?.signal, this.#apiAbort.signal].filter((item) => !!item))];
+        let rejectAbort;
+        const cancelled = new Promise((_resolve, reject) => { rejectAbort = reject; });
+        const onCancel = () => {
+            const error = new TelegramApiError('cancelled', `Telegram API ${method} cancelled`, {
+                disposition: issued ? 'unknown' : 'not_sent',
+            });
+            abort.abort(error);
+            rejectAbort(error);
+        };
+        const timer = setTimeout(() => {
+            const error = new TelegramApiError('timeout', `Telegram API ${method} timed out`);
+            abort.abort(error);
+            rejectAbort(error);
+        }, timeoutMs);
+        for (const source of sources)
+            source.addEventListener('abort', onCancel, { once: true });
+        try {
+            if (sources.some((source) => source.aborted))
+                onCancel();
+            const request = Promise.resolve().then(async () => {
+                abort.signal.throwIfAborted();
+                issued = true;
+                return requestOperation(abort.signal);
+            });
+            return await Promise.race([request, cancelled]);
+        }
+        catch (error) {
+            if (abort.signal.aborted)
+                throw abort.signal.reason;
+            if (error instanceof TelegramApiError)
+                throw error;
+            // Network exceptions can contain credential-bearing URLs. Keep those out of errors/logs.
+            const detail = error instanceof Error
+                ? error.message.replaceAll(this.#options.config.token, '[redacted]') : 'transport failure';
+            throw new TelegramApiError('network', `Telegram API ${method} network request failed: ${detail}`);
+        }
+        finally {
+            clearTimeout(timer);
+            for (const source of sources)
+                source.removeEventListener('abort', onCancel);
+        }
     }
     async #parseApiResponse(method, response) {
         const text = await response.text();
@@ -473,11 +594,21 @@ export class TelegramEndpoint extends Endpoint {
             body = JSON.parse(text);
         }
         catch {
-            throw new Error(`Telegram API ${method} invalid JSON (${response.status}): ${text.slice(0, 200)}`);
+            throw new TelegramApiError('invalid_response', `Telegram API ${method} invalid JSON (${response.status})`, { status: response.status });
+        }
+        if (!body || typeof body !== 'object' || typeof body.ok !== 'boolean') {
+            throw new TelegramApiError('invalid_response', `Telegram API ${method} invalid response envelope`, { status: response.status });
         }
-        if (!body.ok) {
-            throw new Error(`Telegram API ${method} failed (${body.error_code ?? response.status}): ${body.description ?? text}`);
+        if (!body.ok || response.status < 200 || response.status >= 300) {
+            const status = !body.ok ? body.error_code ?? response.status : response.status;
+            const kind = status === 401 || status === 403 ? 'authentication'
+                : status === 429 ? 'rate_limit' : response.status >= 400 ? 'http' : 'api';
+            const description = !body.ok ? body.description?.replaceAll(this.#options.config.token, '[redacted]') : undefined;
+            throw new TelegramApiError(kind, `Telegram API ${method} failed (${status}): ${description ?? 'request rejected'}`, { status, disposition: !body.ok ? 'rejected' : 'unknown', ...(!body.ok && body.parameters?.retry_after != null
+                    ? { retryAfterSeconds: body.parameters.retry_after } : {}) });
         }
+        if (!('result' in body))
+            throw new TelegramApiError('invalid_response', `Telegram API ${method} missing result`);
         return body.result;
     }
     // ── Agent tool surface ──────────────────────────────────────────────

package/lib/polling.d.ts

@@ -4,6 +4,7 @@ export interface TelegramPollingHost {
     callApi<T>(method: string, params?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
     getUpdateOffset(): number;
     setUpdateOffset(offset: number): void;
-    handleUpdate(update: TelegramUpdate): void;
+    handleUpdate(update: TelegramUpdate): void | Promise<void>;
+    setPollingHealthy?(healthy: boolean): void;
 }
 export declare function runTelegramPollLoop(host: TelegramPollingHost, abortSignal: AbortSignal): Promise<void>;

package/lib/polling.js

@@ -16,18 +16,23 @@ export async function runTelegramPollLoop(host, abortSignal) {
                 timeout: DEFAULT_POLL_TIMEOUT_SEC,
                 allowed_updates: host.allowedUpdates,
             }, abortSignal);
-            consecutiveFailures = 0;
+            host.setPollingHealthy?.(true);
             for (const update of updates) {
                 // A transport may resolve after cancellation; never admit that late batch.
                 if (abortSignal.aborted)
                     return;
+                if (update.update_id < host.getUpdateOffset())
+                    continue;
+                await host.handleUpdate(update);
+                // Acknowledgement follows successful framework admission, never receipt.
                 host.setUpdateOffset(update.update_id + 1);
-                host.handleUpdate(update);
             }
+            consecutiveFailures = 0;
         }
         catch (err) {
             if (abortSignal.aborted)
                 return;
+            host.setPollingHealthy?.(false);
             consecutiveFailures += 1;
             logger.error(formatCompact({
                 op: 'poll',