@zhin.js/adapter-telegram 1.1.21 → 1.1.23

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 1.1.23
+
+### Patch Changes
+
+- bc6ccb1: Deep audit bug fixes and 7 architectural improvements:
+  - Sink Agent Turn ingress pipeline from `@zhin.js/cli` into `@zhin.js/agent/runtime` (`plugin-runtime/ingress/`) and decompose `ingress-route.ts` into modular pipeline stages.
+  - Bind Session State Plane (`JsxButtonRegistry`, `InteractionRuntime`, `RuntimeInteractiveRouter`) to `PluginIncarnationRef` so active buttons and interactions survive unrelated-plugin HMR while expiring when the owning plugin reloads, and support per-conversation fallback numbering (`numberingScope: 'conversation'`).
+  - Establish `conversation_events` as the canonical message SSOT and reference `conversation_event_id`, `conversation_key`, `platform_message_id`, and `message_key` in `agent_messages` (`AGENT_MESSAGE_QUERY_VERSION = 2`), threading `conversationSequence` across inbound and outbound delivery receipts.
+  - Push down `DatabaseContextRepository` and `DatabaseScheduleJobStorage` full-session/full-table memory scans to indexed SQL queries.
+  - Add kernel-level inbound `replyTo` and `mentioned` auto-promotion (`promoteInboundMessagePayload`) plus reusable `InboundDeduper` and `TtlLookupCache` primitives in `@zhin.js/adapter`.
+  - Add `MiddlewareContext.dispatch` (`InboundDispatchSummary`) and `onAfterDispatch` hooks for `after-dispatch` middlewares, and support incremental rendering of in-place `envelope.payload` array mutations in `OutboundDeliveryRuntime`.
+  - Unify `HistoryWindowTracker` and `AgentCompactionRuntime` token/message budgets (`resolveUnifiedHistoryAndCompactionBudget`).
+  - Fix schema validation, database transaction connection cleanup and SQLite WAL mode, schedule timer wheel head-of-line blocking, security policy bash read paths and subagent guard propagation, group merge window permission carrier handoff, micro-compact namespaced tool matching, and WebSocket force-close / inbound segment mapping across adapters.
+- Updated dependencies [3a8504b]
+- Updated dependencies [6163abc]
+- Updated dependencies [fed2c27]
+- Updated dependencies [bc6ccb1]
+- Updated dependencies [72b5a12]
+- Updated dependencies [aa41889]
+- Updated dependencies [4427e72]
+- Updated dependencies [22bd14a]
+  - @zhin.js/agent-feature@1.1.14
+  - @zhin.js/core@1.1.57
+  - @zhin.js/client@1.1.25
+  - @zhin.js/page@1.1.15
+  - @zhin.js/im-contract@1.1.12
+  - @zhin.js/adapter@1.1.29
+  - @zhin.js/host-http@1.1.15
+  - @zhin.js/feature-kit@1.1.13
+  - @zhin.js/tool@1.1.16
+  - @zhin.js/skill@1.1.14
+
+## 1.1.22
+
+### Patch Changes
+
+- 41ff1a5: ADR 0044 C5: every official adapter now declares a capability `profile` (its `segments` moved into `profile.default.messaging.segments`). icqq declares the complete profile (per conversation kind: scene, all 14 actions with real limits, events, feedback, delivery) and implements the seven new management ports (`pokeUser`, `unmuteGroupMember`, `muteAllGroupMembers`, `setGroupCard`, `setGroupTitle`, `setGroupEssence`, `inviteGroupMember`) with fresh bot-role reads. qq official declares its passive reply windows; undeclared capabilities stay unsupported.
+- cbd3f14: ADR 0044 integration and C6 guard. `delivery.spool` now reproduces the pre-0044 media rule (icqq `false`, every other official adapter `true`). icqq narrows `actions.recall.others` unless the Bot is admin or owner, and declares recall for groups. Endpoint kind capabilities merge the Endpoint's `operations` (Discord reactions keep working; Discord declares reaction feedback). Adapters in the `@zhin.js/` scope are trusted: their custom prompt text is not labelled `external_content`. Core no longer keeps a telegram/discord interactive-policy table (adapters declare `segments.interactive`). New `pnpm check:no-platform-branches` blocks platform-name branches in runtime code.
+- 4fe49b5: 支持配置按需生效：分离保存与有效版本，独立变更先应用，账号资料更新保留连接，模型按回合使用确定版本；Console 返回结构化应用结果。监听改为仅显式 --watch 启用，开发模板显式选择源码和配置监听。
+
+  自变更消费配置应用回执，避免已处理配置被二次重载；持久化本次写入修订和应用结果，未知结果或修订冲突时停止自动续作并保留现场，恢复不会覆盖未经本次变更确认的配置。
+
+- Updated dependencies [b249e5e]
+- Updated dependencies [57661f6]
+- Updated dependencies [cbd3f14]
+- Updated dependencies [299863a]
+- Updated dependencies [aaa93d7]
+- Updated dependencies [bd524d1]
+- Updated dependencies [126ae99]
+- Updated dependencies [4fe49b5]
+- Updated dependencies [cce07db]
+- Updated dependencies [b652db3]
+- Updated dependencies [0315ba0]
+- Updated dependencies [00be764]
+  - @zhin.js/core@1.1.56
+  - @zhin.js/adapter@1.1.28
+  - @zhin.js/im-contract@1.1.11
+  - @zhin.js/tool@1.1.15
+  - @zhin.js/skill@1.1.13
+  - @zhin.js/host-http@1.1.14
+  - @zhin.js/feature-kit@1.1.12
+  - @zhin.js/client@1.1.24
+  - @zhin.js/page@1.1.14
+  - @zhin.js/agent-feature@1.1.13
+
 ## 1.1.21
 
 ### Patch Changes

package/adapters/telegram/index.js

@@ -8,13 +8,28 @@ import {} from "../../lib/protocol.js";
 export { TelegramEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    operations: ['recall'],
     // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
     // inline keyboard 原生按钮承载交互段。
-    segments: {
-        outboundMedia: ['url', 'upload'],
-        interactive: 'native',
-        markdown: 'native',
+    profile: {
+        default: {
+            messaging: {
+                segments: {
+                    outboundMedia: ['url', 'upload'],
+                    interactive: 'native',
+                    markdown: 'native',
+                },
+                quote: true,
+                recall: { timeLimitSeconds: 172800 },
+            },
+            actions: {
+                recall: {
+                    scopes: ['private', 'group', 'channel'],
+                    params: { timeLimitSeconds: 172800 },
+                },
+                quoteReply: { scopes: ['private', 'group', 'channel'] },
+            },
+            delivery: { send: true, proactive: true, spool: true },
+        },
     },
     createAdapter: context => new TelegramAdapter(context),
 });

package/adapters/telegram/index.ts

@@ -12,13 +12,28 @@ export type { TelegramEndpointOptions, TelegramFetch } from '../../src/endpoint.
 
 export default defineAdapter<TelegramEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
-  operations: ['recall'],
   // 媒体 url / file_id 直发，base64 / 本地路径经 multipart attach:// 上传物化；
   // inline keyboard 原生按钮承载交互段。
-  segments: {
-    outboundMedia: ['url', 'upload'],
-    interactive: 'native',
-    markdown: 'native',
+  profile: {
+    default: {
+      messaging: {
+        segments: {
+          outboundMedia: ['url', 'upload'],
+          interactive: 'native',
+          markdown: 'native',
+        },
+        quote: true,
+        recall: { timeLimitSeconds: 172800 },
+      },
+      actions: {
+        recall: {
+          scopes: ['private', 'group', 'channel'],
+          params: { timeLimitSeconds: 172800 },
+        },
+        quoteReply: { scopes: ['private', 'group', 'channel'] },
+      },
+      delivery: { send: true, proactive: true, spool: true },
+    },
   },
   createAdapter: context => new TelegramAdapter(context),
 });

package/lib/endpoint.js

@@ -1,6 +1,6 @@
 import { TelegramClient } from './telegram-client.js';
 import { createTelegramStreaming } from './streaming.js';
-import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, InboundDeduper, TtlLookupCache, } from 'zhin.js/adapter';
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
  */
@@ -35,12 +35,15 @@ export class TelegramEndpoint extends TelegramClient {
     #executionSignal;
     #updateOffset = 0;
     #pollingHealthy = true;
-    #admittedUpdates = new Set();
+    #admittedUpdates = new InboundDeduper({ maxEntries: ADMITTED_UPDATE_LIMIT });
     #inflightUpdates = new Map();
     #botUserId;
     #botUsername;
     #botName;
-    #chatMemberCache = new Map();
+    #chatMemberCache = new TtlLookupCache({
+        ttlMs: CHAT_MEMBER_CACHE_TTL_MS,
+        maxEntries: CHAT_MEMBER_CACHE_MAX,
+    });
     #control = Object.freeze({
         recall: ({ message, signal }) => this.recallMessage(message, signal),
     });
@@ -341,6 +344,7 @@ export class TelegramEndpoint extends TelegramClient {
             },
             endpointId: this.#options.config.id,
             ...(mentioned ? { mentioned: true } : {}),
+            ...(msg.reply_to_message?.message_id != null ? { replyTo: { id: String(msg.reply_to_message.message_id) } } : {}),
             metadata: Object.freeze({
                 channelType: resolveTelegramChannelType(msg.chat.type),
                 chatType: msg.chat.type,
@@ -351,21 +355,27 @@ export class TelegramEndpoint extends TelegramClient {
             }),
         });
     }
-    /** entities 里 mention 文本命中 bot username（getMe 缓存），或 text_mention 指向 bot 用户。 */
+    /** entities / caption_entities 里 mention 文本命中 bot username（getMe 缓存），或 text_mention 指向 bot 用户。 */
     #isBotMentioned(msg) {
-        if (!msg.entities?.length)
-            return false;
-        for (const entity of msg.entities) {
-            if (entity.type === 'text_mention') {
-                if (this.#botUserId != null && entity.user?.id === this.#botUserId)
-                    return true;
+        const sources = [
+            { text: msg.text ?? '', entities: msg.entities },
+            { text: msg.caption ?? '', entities: msg.caption_entities },
+        ];
+        for (const { text, entities } of sources) {
+            if (!entities?.length)
                 continue;
+            for (const entity of entities) {
+                if (entity.type === 'text_mention') {
+                    if (this.#botUserId != null && entity.user?.id === this.#botUserId)
+                        return true;
+                    continue;
+                }
+                if (entity.type !== 'mention' || !this.#botUsername)
+                    continue;
+                const slice = text.slice(entity.offset, entity.offset + entity.length);
+                if (slice.toLowerCase() === `@${this.#botUsername.toLowerCase()}`)
+                    return true;
             }
-            if (entity.type !== 'mention' || !this.#botUsername)
-                continue;
-            const slice = (msg.text ?? '').slice(entity.offset, entity.offset + entity.length);
-            if (slice.toLowerCase() === `@${this.#botUsername.toLowerCase()}`)
-                return true;
         }
         return false;
     }
@@ -376,10 +386,8 @@ export class TelegramEndpoint extends TelegramClient {
         const chatId = Number(msg.chat.id);
         const userId = msg.from.id;
         const key = `${chatId}:${userId}`;
-        const now = Date.now();
-        this.#sweepChatMemberCache(now);
         const cached = this.#chatMemberCache.get(key);
-        if (cached && now - cached.at < CHAT_MEMBER_CACHE_TTL_MS)
+        if (cached)
             return cached;
         try {
             const member = await this.callApi('getChatMember', {
@@ -389,7 +397,7 @@ export class TelegramEndpoint extends TelegramClient {
             if (signal.aborted)
                 return undefined;
             const normalized = normalizeTelegramChatMember(member);
-            const entry = { at: now, ...normalized };
+            const entry = { ...normalized };
             this.#chatMemberCache.set(key, entry);
             return entry;
         }
@@ -398,22 +406,6 @@ export class TelegramEndpoint extends TelegramClient {
             return undefined;
         }
     }
-    #sweepChatMemberCache(now) {
-        for (const [key, entry] of this.#chatMemberCache) {
-            if (now - entry.at >= CHAT_MEMBER_CACHE_TTL_MS)
-                this.#chatMemberCache.delete(key);
-        }
-        if (this.#chatMemberCache.size > CHAT_MEMBER_CACHE_MAX) {
-            const excess = this.#chatMemberCache.size - CHAT_MEMBER_CACHE_MAX;
-            let removed = 0;
-            for (const [key] of this.#chatMemberCache) {
-                if (removed >= excess)
-                    break;
-                this.#chatMemberCache.delete(key);
-                removed++;
-            }
-        }
-    }
     /** Test / internal: admit a callback query when open. */
     admitCallback(query) {
         void this[endpointSpec].events.run(() => {
@@ -455,7 +447,8 @@ export class TelegramEndpoint extends TelegramClient {
             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))
+            const updateKey = String(update.update_id);
+            if (this.#admittedUpdates.has(updateKey))
                 return;
             const pending = this.#inflightUpdates.get(update.update_id);
             if (pending)
@@ -468,10 +461,7 @@ export class TelegramEndpoint extends TelegramClient {
                 // 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, AbortSignal.any([admission.signal, this.#executionSignal]));
-                this.#admittedUpdates.add(update.update_id);
-                if (this.#admittedUpdates.size > ADMITTED_UPDATE_LIMIT) {
-                    this.#admittedUpdates.delete(this.#admittedUpdates.values().next().value);
-                }
+                this.#admittedUpdates.shouldProcess(updateKey);
             })();
             this.#inflightUpdates.set(update.update_id, receiving);
             try {

package/lib/protocol.d.ts

@@ -73,6 +73,7 @@ export interface TelegramMessage {
     readonly text?: string;
     readonly caption?: string;
     readonly entities?: readonly TelegramMessageEntity[];
+    readonly caption_entities?: readonly TelegramMessageEntity[];
     readonly reply_to_message?: TelegramMessage;
     readonly photo?: readonly TelegramPhotoSize[];
     readonly video?: {
@@ -145,6 +146,7 @@ export interface TelegramWireSegment {
 export interface TelegramInlineButton {
     readonly text: string;
     readonly callback_data?: string;
+    readonly url?: string;
     /** Bot API 10.3+: mutually exclusive with callback_data. */
     readonly disabled?: Record<string, never>;
 }

package/lib/protocol.js

@@ -349,12 +349,15 @@ function buildOutboundActions(target, payload, uploads) {
                             : {};
                         const text = String(record.label ?? record.text ?? '');
                         const callback = String(record.payload ?? record.callback_data ?? '');
+                        const url = typeof record.url === 'string' && record.url.trim() ? record.url.trim() : undefined;
                         if (record.mode === 'command')
                             throw new EndpointDeliveryError('unsupported_operation', 'Telegram command buttons are not implemented', 'not_sent');
                         if (!text.trim())
                             throw new EndpointDeliveryError('invalid_payload', 'Telegram button label must be nonempty', 'not_sent');
                         if (record.disabled)
                             return { text, disabled: {} };
+                        if (url && /^https?:\/\//i.test(url))
+                            return { text, url };
                         if (Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64)
                             throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
                         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-telegram",
-  "version": "1.1.21",
+  "version": "1.1.23",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -31,26 +31,26 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.27",
-    "@zhin.js/agent-feature": "1.1.12",
-    "@zhin.js/client": "1.1.23",
+    "@zhin.js/adapter": "1.1.29",
+    "@zhin.js/agent-feature": "1.1.14",
+    "@zhin.js/client": "1.1.25",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.55",
-    "@zhin.js/feature-kit": "1.1.11",
-    "@zhin.js/host-http": "1.1.13",
-    "@zhin.js/im-contract": "1.1.10",
+    "@zhin.js/core": "1.1.57",
+    "@zhin.js/feature-kit": "1.1.13",
+    "@zhin.js/host-http": "1.1.15",
+    "@zhin.js/im-contract": "1.1.12",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.13",
-    "@zhin.js/skill": "1.1.12",
-    "@zhin.js/tool": "1.1.14"
+    "@zhin.js/page": "1.1.15",
+    "@zhin.js/skill": "1.1.14",
+    "@zhin.js/tool": "1.1.16"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.27",
-    "@zhin.js/command": "^1.1.13",
-    "@zhin.js/core": "^1.1.55",
-    "@zhin.js/permission": "^1.1.11",
-    "zhin.js": "^1.1.20"
+    "@zhin.js/adapter": "^1.1.29",
+    "@zhin.js/command": "^1.1.15",
+    "@zhin.js/core": "^1.1.57",
+    "@zhin.js/permission": "^1.1.13",
+    "zhin.js": "^1.1.22"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -69,9 +69,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.13",
-    "@zhin.js/pagemanager": "1.1.20",
-    "zhin.js": "1.1.20"
+    "@zhin.js/host-http": "1.1.15",
+    "@zhin.js/pagemanager": "1.1.22",
+    "zhin.js": "1.1.22"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -5,6 +5,7 @@ import { checkTelegramPlatformPermit } from "./lib/platform-permit.js";
 import { createTelegramConsoleRpc } from "./lib/console.js";
 export default definePlugin({
     name: 'telegram',
+    configUpdate: { featurePaths: [['nickname'], ['profile'], ['endpoints']] },
     metadata: {
         displayName: 'Telegram Bot API Adapter',
     },

package/src/endpoint.ts

@@ -4,6 +4,7 @@ import {
   createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSpecification, createEndpointLifecycle,
   type EndpointLifecycle, type EndpointContentPort, type EndpointContentResolveContext,
   type EndpointControl, type EndpointSendRequest, type EndpointTransportState,
+  InboundDeduper, TtlLookupCache,
 } from 'zhin.js/adapter';
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
@@ -49,7 +50,6 @@ const ADMITTED_UPDATE_LIMIT = 2_048;
 const INFLIGHT_UPDATE_LIMIT = 256;
 
 interface ChatMemberPermit {
-  readonly at: number;
   readonly role?: string;
   readonly permissions: string[];
 }
@@ -91,12 +91,15 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
   #executionSignal?: AbortSignal;
   #updateOffset = 0;
   #pollingHealthy = true;
-  readonly #admittedUpdates = new Set<number>();
+  readonly #admittedUpdates = new InboundDeduper({ maxEntries: ADMITTED_UPDATE_LIMIT });
   readonly #inflightUpdates = new Map<number, Promise<void>>();
   #botUserId?: number;
   #botUsername?: string;
   #botName?: string;
-  readonly #chatMemberCache = new Map<string, ChatMemberPermit>();
+  readonly #chatMemberCache = new TtlLookupCache<string, ChatMemberPermit>({
+    ttlMs: CHAT_MEMBER_CACHE_TTL_MS,
+    maxEntries: CHAT_MEMBER_CACHE_MAX,
+  });
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({
     recall: ({ message, signal }) => this.recallMessage(message, signal),
   });
@@ -410,6 +413,7 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
       },
       endpointId: this.#options.config.id,
       ...(mentioned ? { mentioned: true } : {}),
+      ...(msg.reply_to_message?.message_id != null ? { replyTo: { id: String(msg.reply_to_message.message_id) } } : {}),
       metadata: Object.freeze({
         channelType: resolveTelegramChannelType(msg.chat.type),
         chatType: msg.chat.type,
@@ -421,17 +425,23 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     });
   }
 
-  /** entities 里 mention 文本命中 bot username（getMe 缓存），或 text_mention 指向 bot 用户。 */
+  /** entities / caption_entities 里 mention 文本命中 bot username（getMe 缓存），或 text_mention 指向 bot 用户。 */
   #isBotMentioned(msg: TelegramMessage): boolean {
-    if (!msg.entities?.length) return false;
-    for (const entity of msg.entities) {
-      if (entity.type === 'text_mention') {
-        if (this.#botUserId != null && entity.user?.id === this.#botUserId) return true;
-        continue;
+    const sources: Array<{ readonly text: string; readonly entities: readonly import('./protocol.js').TelegramMessageEntity[] | undefined }> = [
+      { text: msg.text ?? '', entities: msg.entities },
+      { text: msg.caption ?? '', entities: msg.caption_entities },
+    ];
+    for (const { text, entities } of sources) {
+      if (!entities?.length) continue;
+      for (const entity of entities) {
+        if (entity.type === 'text_mention') {
+          if (this.#botUserId != null && entity.user?.id === this.#botUserId) return true;
+          continue;
+        }
+        if (entity.type !== 'mention' || !this.#botUsername) continue;
+        const slice = text.slice(entity.offset, entity.offset + entity.length);
+        if (slice.toLowerCase() === `@${this.#botUsername.toLowerCase()}`) return true;
       }
-      if (entity.type !== 'mention' || !this.#botUsername) continue;
-      const slice = (msg.text ?? '').slice(entity.offset, entity.offset + entity.length);
-      if (slice.toLowerCase() === `@${this.#botUsername.toLowerCase()}`) return true;
     }
     return false;
   }
@@ -442,10 +452,8 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     const chatId = Number(msg.chat.id);
     const userId = msg.from.id;
     const key = `${chatId}:${userId}`;
-    const now = Date.now();
-    this.#sweepChatMemberCache(now);
     const cached = this.#chatMemberCache.get(key);
-    if (cached && now - cached.at < CHAT_MEMBER_CACHE_TTL_MS) return cached;
+    if (cached) return cached;
     try {
       const member = await this.callApi<TelegramChatMember>('getChatMember', {
         chat_id: chatId,
@@ -453,7 +461,7 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
       }, signal);
       if (signal.aborted) return undefined;
       const normalized = normalizeTelegramChatMember(member);
-      const entry: ChatMemberPermit = { at: now, ...normalized };
+      const entry: ChatMemberPermit = { ...normalized };
       this.#chatMemberCache.set(key, entry);
       return entry;
     } catch {
@@ -462,21 +470,6 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
     }
   }
 
-  #sweepChatMemberCache(now: number): void {
-    for (const [key, entry] of this.#chatMemberCache) {
-      if (now - entry.at >= CHAT_MEMBER_CACHE_TTL_MS) this.#chatMemberCache.delete(key);
-    }
-    if (this.#chatMemberCache.size > CHAT_MEMBER_CACHE_MAX) {
-      const excess = this.#chatMemberCache.size - CHAT_MEMBER_CACHE_MAX;
-      let removed = 0;
-      for (const [key] of this.#chatMemberCache) {
-        if (removed >= excess) break;
-        this.#chatMemberCache.delete(key);
-        removed++;
-      }
-    }
-  }
-
   /** Test / internal: admit a callback query when open. */
   admitCallback(query: TelegramCallbackQuery): void {
     void this[endpointSpec].events.run(() => {
@@ -519,7 +512,8 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
       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 updateKey = String(update.update_id);
+      if (this.#admittedUpdates.has(updateKey)) return;
       const pending = this.#inflightUpdates.get(update.update_id);
       if (pending) return pending;
       if (this.#inflightUpdates.size >= INFLIGHT_UPDATE_LIMIT) {
@@ -530,10 +524,7 @@ export class TelegramEndpoint extends TelegramClient implements Endpoint {
         // 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, AbortSignal.any([admission.signal, this.#executionSignal!]));
-        this.#admittedUpdates.add(update.update_id);
-        if (this.#admittedUpdates.size > ADMITTED_UPDATE_LIMIT) {
-          this.#admittedUpdates.delete(this.#admittedUpdates.values().next().value!);
-        }
+        this.#admittedUpdates.shouldProcess(updateKey);
       })();
       this.#inflightUpdates.set(update.update_id, receiving);
       try {

package/src/protocol.ts

@@ -85,6 +85,7 @@ export interface TelegramMessage {
   readonly text?: string;
   readonly caption?: string;
   readonly entities?: readonly TelegramMessageEntity[];
+  readonly caption_entities?: readonly TelegramMessageEntity[];
   readonly reply_to_message?: TelegramMessage;
   readonly photo?: readonly TelegramPhotoSize[];
   readonly video?: {
@@ -162,6 +163,7 @@ export interface TelegramWireSegment {
 export interface TelegramInlineButton {
   readonly text: string;
   readonly callback_data?: string;
+  readonly url?: string;
   /** Bot API 10.3+: mutually exclusive with callback_data. */
   readonly disabled?: Record<string, never>;
 }
@@ -625,13 +627,15 @@ function buildOutboundActions(
           const buttons = Array.isArray(row) ? row : [];
           return buttons.map((btn) => {
             const record = btn && typeof btn === 'object'
-              ? btn as { label?: string; text?: string; payload?: string; callback_data?: string; disabled?: boolean; mode?: string }
+              ? btn as { label?: string; text?: string; payload?: string; callback_data?: string; url?: string; disabled?: boolean; mode?: string }
               : {};
             const text = String(record.label ?? record.text ?? '');
             const callback = String(record.payload ?? record.callback_data ?? '');
+            const url = typeof record.url === 'string' && record.url.trim() ? record.url.trim() : undefined;
             if (record.mode === 'command') throw new EndpointDeliveryError('unsupported_operation', 'Telegram command buttons are not implemented', 'not_sent');
             if (!text.trim()) throw new EndpointDeliveryError('invalid_payload', 'Telegram button label must be nonempty', 'not_sent');
             if (record.disabled) return { text, disabled: {} };
+            if (url && /^https?:\/\//i.test(url)) return { text, url };
             if (Buffer.byteLength(callback, 'utf8') < 1 || Buffer.byteLength(callback, 'utf8') > 64) throw new EndpointDeliveryError('invalid_payload', 'Telegram callback payload must be 1-64 UTF-8 bytes and label nonempty', 'not_sent');
             return {
               text,