@zhin.js/adapter-telegram 1.1.22 → 1.1.24

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 1.1.24
+
+### Patch Changes
+
+- cbf1fb1: Unify Console page blueprints (`definePageBlueprint`, `defineAdapterPage`, `defineCommentReviewPage`, `projectBlueprintToImCard`, `projectBlueprintToCliPanel`) into `@zhin.js/console-contract` and `@zhin.js/page`, add zero-esbuild pure Blueprint synthesis + static client bundle mounting to `@zhin.js/pagemanager`, remove `@zhin.js/client` (React 19) and `.tsx` from all 30 server-side plugins and adapters (including `bilibili` and `juejin`), and remove legacy Era-1 Koa `PageManager` code.
+- Updated dependencies [cbf1fb1]
+- Updated dependencies [008ccad]
+- Updated dependencies [a1f1028]
+  - @zhin.js/console-contract@1.1.4
+  - @zhin.js/page@1.1.16
+  - @zhin.js/core@1.1.58
+  - @zhin.js/im-contract@1.1.13
+  - @zhin.js/host-http@1.1.16
+  - @zhin.js/adapter@1.1.30
+  - @zhin.js/tool@1.1.17
+  - @zhin.js/agent-feature@1.1.15
+  - @zhin.js/feature-kit@1.1.14
+  - @zhin.js/skill@1.1.15
+
+## 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

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.22",
+  "version": "1.1.24",
   "description": "Zhin.js Telegram Bot API adapter for Plugin Runtime (long-poll getUpdates)",
   "type": "module",
   "main": "./lib/index.js",
@@ -31,26 +31,25 @@
     "directory": "plugins/adapters/telegram"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.28",
-    "@zhin.js/agent-feature": "1.1.13",
-    "@zhin.js/client": "1.1.24",
-    "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.56",
-    "@zhin.js/feature-kit": "1.1.12",
-    "@zhin.js/host-http": "1.1.14",
-    "@zhin.js/im-contract": "1.1.11",
+    "@zhin.js/adapter": "1.1.30",
+    "@zhin.js/agent-feature": "1.1.15",
+    "@zhin.js/console-contract": "1.1.4",
+    "@zhin.js/core": "1.1.58",
+    "@zhin.js/feature-kit": "1.1.14",
+    "@zhin.js/host-http": "1.1.16",
+    "@zhin.js/im-contract": "1.1.13",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.14",
-    "@zhin.js/skill": "1.1.13",
-    "@zhin.js/tool": "1.1.15"
+    "@zhin.js/page": "1.1.16",
+    "@zhin.js/skill": "1.1.15",
+    "@zhin.js/tool": "1.1.17"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.28",
-    "@zhin.js/command": "^1.1.14",
-    "@zhin.js/core": "^1.1.56",
-    "@zhin.js/permission": "^1.1.12",
-    "zhin.js": "^1.1.21"
+    "@zhin.js/adapter": "^1.1.30",
+    "@zhin.js/command": "^1.1.16",
+    "@zhin.js/core": "^1.1.58",
+    "@zhin.js/permission": "^1.1.14",
+    "zhin.js": "^1.1.23"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -69,9 +68,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.14",
-    "@zhin.js/pagemanager": "1.1.21",
-    "zhin.js": "1.1.21"
+    "@zhin.js/host-http": "1.1.16",
+    "@zhin.js/pagemanager": "1.1.23",
+    "zhin.js": "1.1.23"
   },
   "files": [
     "adapters",

package/pages/index/index.js

@@ -1,6 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { definePage } from '@zhin.js/console-contract';
-import { createAdapterConsolePage } from '@zhin.js/client';
+import { definePage, createAdapterConsolePage } from '@zhin.js/console-contract';
 export const meta = definePage({
     title: 'Telegram',
     titleI18n: { en: 'Telegram' },

package/pages/index/index.ts

@@ -1,5 +1,4 @@
-import { definePage } from '@zhin.js/console-contract';
-import { createAdapterConsolePage } from '@zhin.js/client';
+import { definePage, createAdapterConsolePage } from '@zhin.js/console-contract';
 
 export const meta = definePage({
   title: 'Telegram',

package/plugin.js

@@ -1,5 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { definePlugin, pluginConsoleRpcToken } from 'zhin.js';
+import { definePlugin } from 'zhin.js';
 import { permissionHostToken } from '@zhin.js/permission';
 import { checkTelegramPlatformPermit } from "./lib/platform-permit.js";
 import { createTelegramConsoleRpc } from "./lib/console.js";
@@ -10,10 +10,12 @@ export default definePlugin({
         displayName: 'Telegram Bot API Adapter',
     },
     setup(context) {
-        context.resources.provide(pluginConsoleRpcToken, createTelegramConsoleRpc(() => context.config.get()));
-        if (context.resources.has(permissionHostToken)) {
-            const host = context.resources.use(permissionHostToken);
-            return host.registerPlatform('telegram', checkTelegramPlatformPermit);
-        }
+        const dispose = context.resources.has(permissionHostToken)
+            ? context.resources.use(permissionHostToken).registerPlatform('telegram', checkTelegramPlatformPermit)
+            : undefined;
+        return {
+            consoleRpc: createTelegramConsoleRpc(() => context.config.get()),
+            ...(dispose ? { dispose } : {}),
+        };
     },
 });

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,