@zhin.js/adapter-telegram 1.1.20 → 1.1.21

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 1.1.21
+
+### Patch Changes
+
+- af8f803: Use the current Endpoint's platform profile for Agent account identity, with per-field configured fallbacks and scoped, identity-approved profile tools. Keep SOUL first-person and independent of account names. Profile ports preserve the source Client, cancellation, truthful update outcomes and private image authority.
+
+  Adapter Feature API 2.1 and Tool Feature API 1.1 describe the additive profile requirements; new Core, official adapters and generated plugins declare the corresponding floors. Existing compatible API-2.0/API-1.0 plugins remain accepted by the newer providers. npm releases remain patch.
+
+  Private IM assets now bind to the full canonical conversation and principal. Existing IM asset records that contain only the earlier lossy hash remain on disk until their original expiry, but cannot be safely rebound; recapture them. No automatic file deletion, platform profile mutation or workspace SOUL rewrite occurs during upgrade.
+
+- 26fda97: Deliver validated final answers progressively through configured QQ C2C, Telegram drafts, Slack streams, Lark cards and Sandbox updates. Keep complete-message delivery for unsupported scenes, disabled adapters and outbound middleware that does not explicitly support revisions. Discord retains complete-message delivery.
+
+  Preserve source-account leases, media order and confirmed delivery facts across cancellation, capacity rollover and follow-up answer phases. Preview drafts and uncertain outcomes do not become sent history. Bound each reply's semantic snapshot to 1 MiB, retain confirmed prefixes on failure and avoid replaying published answers.
+
+  Project the latest confirmed message revision into paginated conversation history and synchronize Sandbox message updates across connections. Existing adapter implementations and complete-send callers remain compatible.
+
+- 976886c: Preserve confirmed progressive reply content, routing and delivery evidence across cancellation, rollover and closing failures without replaying published text. Keep error dispositions and actual message references, and abort the owning provider request when its functional text consumer fails.
+
+  Enable native Sandbox Markdown through the real Core projection so Console updates retain formatting in one message. Preserve instance-level streaming opt-outs, recall tombstones and multi-page synchronization. The first safe content is immediate; later updates retain the configured pacing, including large valid intervals.
+
+  Keep Slack and Lark Markdown streaming within the current physical message. When continuation formatting cannot be verified, stop and retain confirmed content instead of replaying or silently changing it to plain text. Plain-text continuations retain their original reply route.
+
+  Use rebuildable revision metadata and indexes in the existing conversation event table for bounded SQL history reads. Original event JSON and retention remain unchanged; older writers and models keep their compatible read path. Supported adapter streaming remains enabled by default, with complete-message fallback for disabled settings or outbound middleware without incremental: true.
+
+- Updated dependencies [b88e988]
+- Updated dependencies [f78eb84]
+- Updated dependencies [c15cef9]
+- Updated dependencies [b0c02a2]
+- Updated dependencies [af8f803]
+- Updated dependencies [26fda97]
+- Updated dependencies [976886c]
+- Updated dependencies [032dc96]
+  - @zhin.js/adapter@1.1.27
+  - @zhin.js/client@1.1.23
+  - @zhin.js/im-contract@1.1.10
+  - @zhin.js/core@1.1.55
+  - @zhin.js/tool@1.1.14
+  - @zhin.js/page@1.1.13
+  - @zhin.js/host-http@1.1.13
+  - @zhin.js/agent-feature@1.1.12
+  - @zhin.js/feature-kit@1.1.11
+  - @zhin.js/skill@1.1.12
+
 ## 1.1.20
 
 ### Patch Changes

package/README.md

@@ -57,6 +57,26 @@ pnpm add @zhin.js/adapter-telegram
 
 必填字段（`endpoints[i]`）：`id`、`token`。
 
+## 渐进式回复
+
+私聊默认通过 Telegram 草稿展示生成中的文本或 Markdown，完成后正式发送。草稿是临时预览，不代表消息已保存；取消只停止更新，不会自动把部分草稿正式发送。群聊和不支持的目标继续使用完整消息发送。
+
+首段立即展示，后续更新默认至少间隔 500 毫秒。可在实例配置或单个 endpoint 中设置：
+
+```yaml
+telegram:
+  streaming: true
+  streamingIntervalMs: 500
+  endpoints:
+    - id: my-telegram-bot
+      token: ${TELEGRAM_TOKEN}
+    - id: complete-replies
+      token: ${OTHER_TELEGRAM_TOKEN}
+      streaming: false
+```
+
+`streaming: false` 关闭生成中的公开更新。草稿与正式回复保持同一话题，最终消息保留引用与交互内容。超过平台单条容量时按内容顺序接续消息，Markdown 代码块和链接保留格式与原文；图片、语音和文件仍使用现有上传发送链路。结果未知时不会自动重复正式发送。
+
 ## 最小配置
 
 ```yaml
@@ -172,3 +192,11 @@ MIT
 ### 禁用按钮
 
 canonical keyboard 的 `disabled: true` 按钮映射为 Telegram Bot API 10.3 的 `disabled: {}`，不携带 `callback_data`；启用按钮仍使用原回调数据，并保留 1–64 UTF-8 字节校验。自建 Bot API Server 需支持该版本，见 [DisabledButton](https://core.telegram.org/bots/api#disabledbutton)。
+
+## 当前账号资料
+
+资料端口使用 Bot API 的账号方法，与聊天管理方法分开：`getMyName` / `setMyName` 读取及修改昵称，`getMyShortDescription` / `setMyShortDescription` 处理简短签名（`signature`），`getMyDescription` / `setMyDescription` 处理个人简介（`bio`）。这些操作针对默认语言版本；修改沿用 Agent 现有的身份类审批。
+
+`setMyProfilePhoto` 通过 multipart 附件上传已解析的 JPEG 字节，不把 URL 冒充上传文件，也不向模型暴露含 Bot Token 的 Telegram 下载地址。资料端口不返回需凭据访问的文件接口 URL，亦不声明 Bot 的年龄、性别、生日及兴趣可写。
+
+`nickname` / `profile` 配置只补足缺失字段；Endpoint 字段优先于适配器默认值，不会修改 Telegram 账号。接口依据 [Bot API 官方文档](https://core.telegram.org/bots/api#getmyname)及[头像设置方法](https://core.telegram.org/bots/api#setmyprofilephoto)。

package/lib/adapter.js

@@ -14,7 +14,7 @@ export class TelegramAdapter extends Adapter {
     get configurationIdentityFields() { return ['id']; }
     get configurationIdentityProbeFields() { return ['token', 'apiBaseUrl']; }
     get configurationUpdateFields() {
-        return ['token', 'polling', 'webhook',
+        return ['token', 'polling', 'streaming', 'streamingIntervalMs', 'webhook',
             'webhook.domain', 'webhook.path', 'webhook.secretToken', 'allowedUpdates', 'apiBaseUrl'];
     }
     validateConfiguration(config) { resolveTelegramConfig(config); }

package/lib/console-spec.js

@@ -5,6 +5,8 @@ export const telegramConsoleSpec = {
         { key: 'token', required: true, env: true, description: 'Telegram bot token' },
         { key: 'apiBaseUrl', description: 'Telegram Bot API URL' },
         { key: 'polling', type: 'boolean', description: 'Use long polling; false selects webhook mode' },
+        { key: 'streaming', type: 'boolean', description: 'Show private-chat drafts while generating (default true)' },
+        { key: 'streamingIntervalMs', type: 'number', description: 'Delay between draft updates in milliseconds (default 500)' },
         { key: 'webhook.domain', description: 'Public webhook origin' },
         { key: 'webhook.path', description: 'Local webhook route' },
         { key: 'webhook.secretToken', env: true, description: 'Webhook secret token' },

package/lib/endpoint.js

@@ -1,4 +1,5 @@
 import { TelegramClient } from './telegram-client.js';
+import { createTelegramStreaming } from './streaming.js';
 import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, } from 'zhin.js/adapter';
 /**
  * TelegramEndpoint — lifecycle, outbound, admit, Bot API helpers for agent tools.
@@ -11,6 +12,7 @@ export { TelegramApiError } from './api-error.js';
 import { normalizeTelegramChatMember } from './platform-permit.js';
 import { buildWebhookUrl, formatCallbackContent, formatCallbackSegments, formatInboundContent, formatInboundSegments, formatOutboundPlan, resolveTelegramChannelType, senderDisplayName, telegramInboundConversation, } from './protocol.js';
 import { registerTelegramWebhookRoutes } from './webhook.js';
+import { createTelegramSelfProfile } from './self-profile.js';
 const CHAT_MEMBER_CACHE_TTL_MS = 60_000;
 const CHAT_MEMBER_CACHE_MAX = 2_000;
 const ADMITTED_UPDATE_LIMIT = 2_048;
@@ -37,6 +39,7 @@ export class TelegramEndpoint extends TelegramClient {
     #inflightUpdates = new Map();
     #botUserId;
     #botUsername;
+    #botName;
     #chatMemberCache = new Map();
     #control = Object.freeze({
         recall: ({ message, signal }) => this.recallMessage(message, signal),
@@ -55,6 +58,11 @@ export class TelegramEndpoint extends TelegramClient {
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
             get name() { return options.config.id; }, get transportState() { return endpoint.#transportState; },
             control: this.#control, content: this.#content,
+            streaming: options.config.streaming !== false ? createTelegramStreaming(() => this, options.config.streamingIntervalMs) : undefined,
+            profile: createTelegramSelfProfile({ client: this,
+                current: () => this.#botName === undefined ? {} : { nickname: this.#botName },
+                nicknameChanged: nickname => { this.#botName = nickname; },
+            }),
         });
     }
     /** Used by webhook handler. */
@@ -105,6 +113,9 @@ export class TelegramEndpoint extends TelegramClient {
                     return;
                 this.#botUserId = me.id;
                 this.#botUsername = me.username;
+                this.#botName = me.first_name;
+                if (me.id)
+                    this[endpointSpec].reportSelfUserId(String(me.id));
                 if (this.#options.config.mode === 'webhook') {
                     if (!this.#options.http) {
                         throw new TypeError('Telegram webhook mode requires httpHostToken');

package/lib/markdown-to-html.d.ts

@@ -1,9 +1,7 @@
-/**
- * Canonical Markdown → Telegram Bot API HTML.
- *
- * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
- * punctuation. HTML gives the adapter a safer dialect seam: user text is
- * escaped first and only the subset supported by Bot API is emitted as tags.
- */
 export declare function markdownToTelegramHtml(markdown: string): string;
+/** Shares exactly the complete-message codec; generated tags never consume source text. */
+export declare function projectTelegramMarkdown(markdown: string): {
+    readonly html: string;
+    readonly source: readonly number[];
+};
 export declare function escapeTelegramHtml(value: string): string;

package/lib/markdown-to-html.js

@@ -1,75 +1,114 @@
-/**
- * Canonical Markdown → Telegram Bot API HTML.
- *
- * Telegram's MarkdownV2 is not CommonMark-compatible and rejects unescaped
- * punctuation. HTML gives the adapter a safer dialect seam: user text is
- * escaped first and only the subset supported by Bot API is emitted as tags.
- */
 export function markdownToTelegramHtml(markdown) {
-    const protectedFragments = [];
-    const protect = (html) => {
-        const token = `\uE000${protectedFragments.length}\uE001`;
-        protectedFragments.push(html);
+    return projectMarkdown({ text: markdown }).text;
+}
+/** Shares exactly the complete-message codec; generated tags never consume source text. */
+export function projectTelegramMarkdown(markdown) {
+    const value = projectMarkdown({ text: markdown, source: Array.from({ length: markdown.length }, (_, index) => index) });
+    return { html: value.text, source: value.source };
+}
+function projectMarkdown(markdown) {
+    const fragments = [];
+    const literal = (text, origin = -1) => ({ text,
+        ...(markdown.source ? { source: Array(text.length).fill(origin) } : {}) });
+    const protect = (value) => {
+        const token = literal(`\uE000${fragments.length}\uE001`);
+        fragments.push(value);
         return token;
     };
-    let value = protectTelegramFencedCode(markdown, protect);
-    value = value.replace(/`([^`\n]+)`/g, (_match, code) => (protect(`<code>${escapeTelegramHtml(String(code))}</code>`)));
-    value = escapeTelegramHtml(value);
-    value = value
-        .replace(/!\[([^\[\]]*)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, '$1')
-        .replace(/\[([^\[\]]+)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_match, label, href) => isSafeTelegramHref(href)
-        ? `<a href="${href}">${label}</a>`
-        : label)
-        .replace(/^#{1,6}\s+(.+)$/gm, '<b>$1</b>')
-        .replace(/^&gt;\s?(.*)$/gm, '<blockquote>$1</blockquote>')
-        .replace(/^\s*[-+*]\s+(.+)$/gm, '• $1')
-        .replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
-        .replace(/__([^_\n]+)__/g, '<b>$1</b>')
-        .replace(/~~([^~\n]+)~~/g, '<s>$1</s>')
-        .replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<i>$2</i>')
-        .replace(/(^|[^_])_([^_\n]+)_/g, '$1<i>$2</i>');
-    for (let index = 0; index < protectedFragments.length; index += 1) {
-        value = value.replace(`\uE000${index}\uE001`, protectedFragments[index]);
+    const wrapped = (tag, value) => join([
+        literal(`<${tag}>`), value, literal(`</${tag.split(' ')[0]}>`),
+    ]);
+    let value = fencedCode(markdown, code => protect(code), literal);
+    value = replace(value, /`([^`\n]+)`/g, (_match, group) => protect(wrapped('code', escape(group(1)))));
+    value = escape(value);
+    value = replace(value, /!\[([^\[\]]*)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_match, group) => group(1));
+    value = replace(value, /\[([^\[\]]+)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, (_match, group) => {
+        const label = group(1), href = group(2);
+        return isSafeTelegramHref(href.text) ? join([literal('<a href="'), href, literal('">'), label, literal('</a>')]) : label;
+    });
+    value = replace(value, /^#{1,6}\s+(.+)$/gm, (_match, group) => wrapped('b', group(1)));
+    value = replace(value, /^&gt;\s?(.*)$/gm, (_match, group) => wrapped('blockquote', group(1)));
+    value = replace(value, /^\s*[-+*]\s+(.+)$/gm, (_match, group) => join([
+        literal('• ', group(0).source?.find(position => position >= 0)), group(1),
+    ]));
+    for (const [pattern, tag] of [[/\*\*([^*\n]+)\*\*/g, 'b'], [/__([^_\n]+)__/g, 'b'], [/~~([^~\n]+)~~/g, 's']]) {
+        value = replace(value, pattern, (_match, group) => wrapped(tag, group(1)));
+    }
+    for (const pattern of [/(^|[^*])\*([^*\n]+)\*/g, /(^|[^_])_([^_\n]+)_/g]) {
+        value = replace(value, pattern, (_match, group) => join([group(1), wrapped('i', group(2))]));
+    }
+    for (let index = 0; index < fragments.length; index++) {
+        value = replace(value, new RegExp(`\uE000${index}\uE001`), () => fragments[index]);
     }
     return value;
 }
-function protectTelegramFencedCode(markdown, protect) {
+function slice(value, start, end) {
+    return { text: value.text.slice(start, end), ...(value.source ? { source: value.source.slice(start, end) } : {}) };
+}
+function join(values) {
+    const mapped = values.some(value => value.source);
+    return { text: values.map(value => value.text).join(''),
+        ...(mapped ? { source: values.flatMap(value => value.source ? [...value.source] : Array(value.text.length).fill(-1)) } : {}) };
+}
+function replace(value, pattern, project) {
+    const matcher = new RegExp(pattern.source, `${pattern.flags}d`);
+    const chunks = [];
+    let cursor = 0;
+    for (let match = matcher.exec(value.text); match; match = matcher.global ? matcher.exec(value.text) : null) {
+        chunks.push(slice(value, cursor, match.index));
+        const matched = match;
+        chunks.push(project(match, index => {
+            const [start, end] = matched.indices[index];
+            return slice(value, start, end);
+        }));
+        cursor = match.index + match[0].length;
+        if (!matcher.global)
+            break;
+    }
+    chunks.push(slice(value, cursor));
+    return join(chunks);
+}
+function escape(value) {
+    const entities = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
+    return replace(value, /[&<>"]/g, (match, group) => {
+        const origin = group(0).source?.[0];
+        const text = entities[match[0]];
+        return { text, ...(origin !== undefined ? { source: Array(text.length).fill(origin) } : {}) };
+    });
+}
+function fencedCode(value, protect, literal) {
     const chunks = [];
     let cursor = 0;
-    while (cursor < markdown.length) {
-        const opening = markdown.indexOf('```', cursor);
+    while (cursor < value.text.length) {
+        const opening = value.text.indexOf('```', cursor);
         if (opening < 0) {
-            chunks.push(markdown.slice(cursor));
+            chunks.push(slice(value, cursor));
             break;
         }
-        chunks.push(markdown.slice(cursor, opening));
+        chunks.push(slice(value, cursor, opening));
         const contentStart = opening + 3;
-        const closing = markdown.indexOf('```', contentStart);
+        const closing = value.text.indexOf('```', contentStart);
         if (closing < 0) {
-            chunks.push(markdown.slice(opening));
+            chunks.push(slice(value, opening));
             break;
         }
-        const newline = markdown.indexOf('\n', contentStart);
+        const newline = value.text.indexOf('\n', contentStart);
         const hasHeader = newline >= 0 && newline < closing;
-        const language = markdown.slice(contentStart, hasHeader ? newline : closing).trim();
-        let code = hasHeader ? markdown.slice(newline + 1, closing) : '';
-        if (code.endsWith('\n'))
-            code = code.slice(0, -1);
-        const escapedCode = escapeTelegramHtml(code);
-        chunks.push(/^[A-Za-z0-9_+-]+$/.test(language)
-            ? protect(`<pre><code class="language-${language}">${escapedCode}</code></pre>`)
-            : protect(`<pre>${escapedCode}</pre>`));
+        const language = value.text.slice(contentStart, hasHeader ? newline : closing).trim();
+        let code = hasHeader ? slice(value, newline + 1, closing) : literal('');
+        if (code.text.endsWith('\n'))
+            code = slice(code, 0, -1);
+        const escaped = escape(code);
+        chunks.push(protect(/^[A-Za-z0-9_+-]+$/.test(language)
+            ? join([literal(`<pre><code class="language-${language}">`), escaped, literal('</code></pre>')])
+            : join([literal('<pre>'), escaped, literal('</pre>')])));
         cursor = closing + 3;
     }
-    return chunks.join('');
+    return join(chunks);
 }
 function isSafeTelegramHref(value) {
     return /^(?:https?:\/\/|tg:\/\/|mailto:)[^\s<>]+$/iu.test(value);
 }
 export function escapeTelegramHtml(value) {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }

package/lib/protocol.d.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 /**
  * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
@@ -6,11 +7,14 @@ import type { IncomingMessage } from 'node:http';
 import { type ConversationKind, type ConversationRef } from '@zhin.js/im-contract';
 import type { Segment } from '@zhin.js/core/runtime';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface TelegramEndpointConfig {
+export interface TelegramEndpointConfig extends EndpointProfileConfiguration {
     readonly id: string;
     readonly token: string;
     /** Default true. `false` selects webhook mode (requires httpHostToken). */
     readonly polling?: boolean;
+    /** Show private-chat drafts while generating; false keeps complete delivery. */
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     readonly webhook?: {
         readonly domain?: string;
         readonly path?: string;
@@ -26,6 +30,8 @@ export interface ResolvedTelegramConfig {
     readonly mode: 'polling' | 'webhook';
     readonly allowedUpdates: readonly string[];
     readonly apiBaseUrl: string;
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     readonly webhook?: {
         readonly domain: string;
         readonly path: string;

package/lib/protocol.js

@@ -1,7 +1,3 @@
-/**
- * Telegram Bot API protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
- * Canonicalization is owned by gateway/core before endpoint.send.
- */
 import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.js';
@@ -9,6 +5,9 @@ const logger = getLogger('telegram');
 export function resolveTelegramConfig(config) {
     const id = requiredEndpointField(config.id, 'id');
     const token = requiredEndpointField(config.token, 'token');
+    const streamingIntervalMs = config.streamingIntervalMs ?? 500;
+    if (!Number.isFinite(streamingIntervalMs) || streamingIntervalMs < 0)
+        throw new TypeError('streamingIntervalMs must be a non-negative finite number');
     const polling = config.polling;
     const webhookSource = config.webhook;
     const mode = polling === false ? 'webhook' : 'polling';
@@ -28,6 +27,8 @@ export function resolveTelegramConfig(config) {
         mode,
         allowedUpdates: [...allowedUpdates],
         apiBaseUrl,
+        streaming: config.streaming !== false,
+        streamingIntervalMs,
         webhook,
     };
 }
@@ -239,6 +240,19 @@ function buildOutboundActions(target, payload, uploads) {
     let keyboard;
     const actions = [];
     const replyParams = () => (replyTo != null ? { reply_parameters: { message_id: replyTo } } : {});
+    const flushText = () => {
+        if (!textContent.trim() && !keyboard)
+            return;
+        actions.push({ method: 'sendMessage', params: {
+                chat_id: chatId,
+                text: textContent.trim() || ' ',
+                ...htmlMode,
+                ...replyParams(),
+                ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
+            } });
+        textContent = '';
+        keyboard = undefined;
+    };
     /**
      * 媒体来源归一：唯一来源是 canonical `data.media` MediaRef。
      * kind=url/file → 字符串直发（file 即 Telegram file_id 不透明引用）；
@@ -352,6 +366,8 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'image': {
+                if (keyboard)
+                    flushText();
                 const photo = mediaSource('image', data, 'image.png');
                 if (photo) {
                     actions.push({
@@ -369,6 +385,8 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'video': {
+                if (keyboard)
+                    flushText();
                 const video = mediaSource('video', data, 'video.mp4');
                 if (video) {
                     actions.push({
@@ -386,6 +404,8 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'audio': {
+                if (keyboard)
+                    flushText();
                 const audio = mediaSource('audio', data, 'audio.mp3');
                 if (audio) {
                     actions.push({
@@ -403,6 +423,8 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'voice': {
+                if (keyboard)
+                    flushText();
                 const voice = mediaSource('voice', data, 'voice.ogg');
                 if (voice) {
                     actions.push({
@@ -420,6 +442,8 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'file': {
+                if (keyboard)
+                    flushText();
                 const document = mediaSource('file', data, 'file');
                 if (document) {
                     actions.push({
@@ -439,6 +463,7 @@ function buildOutboundActions(target, payload, uploads) {
             case 'sticker': {
                 const sticker = mediaSource('sticker', data, 'sticker.webp');
                 if (sticker) {
+                    flushText();
                     actions.push({
                         method: 'sendSticker',
                         params: { chat_id: chatId, sticker, ...replyParams() },
@@ -447,6 +472,7 @@ function buildOutboundActions(target, payload, uploads) {
                 break;
             }
             case 'location': {
+                flushText();
                 actions.push({
                     method: 'sendLocation',
                     params: {
@@ -462,32 +488,8 @@ function buildOutboundActions(target, payload, uploads) {
                 textContent += appendPlain(data.text ?? `[${item.type}]`);
         }
     }
-    if (actions.length === 0) {
-        const text = textContent.trim() || (keyboard ? ' ' : '');
-        if (!text && !keyboard)
-            throw new Error('No Telegram content to send');
-        return [{
-                method: 'sendMessage',
-                params: {
-                    chat_id: chatId,
-                    text: text || ' ',
-                    ...htmlMode,
-                    ...replyParams(),
-                    ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
-                },
-            }];
-    }
-    if (textContent.trim() || keyboard) {
-        actions.unshift({
-            method: 'sendMessage',
-            params: {
-                chat_id: chatId,
-                text: textContent.trim() || ' ',
-                ...htmlMode,
-                ...replyParams(),
-                ...(keyboard ? { reply_markup: { inline_keyboard: keyboard } } : {}),
-            },
-        });
-    }
+    flushText();
+    if (actions.length === 0)
+        throw new Error('No Telegram content to send');
     return actions;
 }

package/lib/self-profile.d.ts

@@ -0,0 +1,11 @@
+import type { EndpointProfile } from 'zhin.js/adapter';
+import type { SelfProfile } from '@zhin.js/im-contract';
+import type { TelegramClientApi } from './telegram-client.js';
+interface TelegramSelfProfileOptions {
+    readonly client: Pick<TelegramClientApi, 'callApi' | 'callApiForm'>;
+    readonly current: () => Readonly<SelfProfile>;
+    readonly nicknameChanged: (nickname: string) => void;
+}
+/** Bot API names/descriptions are account fields, not the title/description of a chat. */
+export declare function createTelegramSelfProfile({ client, current, nicknameChanged }: TelegramSelfProfileOptions): EndpointProfile;
+export {};

package/lib/self-profile.js

@@ -0,0 +1,61 @@
+import { TelegramApiError } from './api-error.js';
+/** Bot API names/descriptions are account fields, not the title/description of a chat. */
+export function createTelegramSelfProfile({ client, current, nicknameChanged }) {
+    return Object.freeze({
+        writableFields: Object.freeze(['nickname', 'signature', 'bio', 'avatar']),
+        get current() { return current(); },
+        async read({ signal }) {
+            const [name, description, shortDescription] = await Promise.all([
+                client.callApi('getMyName', {}, signal),
+                client.callApi('getMyDescription', {}, signal),
+                client.callApi('getMyShortDescription', {}, signal),
+            ]);
+            if (typeof name.name !== 'string' || typeof description.description !== 'string' || typeof shortDescription.short_description !== 'string') {
+                throw new Error('Telegram returned an incomplete bot profile');
+            }
+            return { nickname: name.name, signature: shortDescription.short_description, bio: description.description };
+        },
+        async write({ change, signal }) {
+            try {
+                if (change.field === 'avatar') {
+                    if (change.value.kind !== 'base64' || change.value.mime_type !== 'image/jpeg') {
+                        return { status: 'rejected', message: 'Telegram profile photos require resolved JPEG image bytes' };
+                    }
+                    const form = new FormData();
+                    form.set('photo', JSON.stringify({ type: 'static', photo: 'attach://avatar' }));
+                    form.set('avatar', new Blob([Uint8Array.from(Buffer.from(change.value.value, 'base64'))], { type: 'image/jpeg' }), 'avatar.jpg');
+                    const accepted = await client.callApiForm('setMyProfilePhoto', form, signal);
+                    return accepted === true ? { status: 'updated' } : { status: 'rejected', message: 'Telegram rejected the avatar change' };
+                }
+                let method;
+                let params;
+                switch (change.field) {
+                    case 'nickname':
+                        method = 'setMyName';
+                        params = { name: change.value };
+                        break;
+                    case 'signature':
+                        method = 'setMyShortDescription';
+                        params = { short_description: change.value };
+                        break;
+                    case 'bio':
+                        method = 'setMyDescription';
+                        params = { description: change.value };
+                        break;
+                    default: return { status: 'rejected', message: `Telegram bot profile does not expose ${change.field} through this port` };
+                }
+                const accepted = await client.callApi(method, params, signal);
+                if (accepted !== true)
+                    return { status: 'rejected', message: `Telegram rejected the ${change.field} change` };
+                if (change.field === 'nickname')
+                    nicknameChanged(change.value);
+                return { status: 'updated', profile: { [change.field]: change.value } };
+            }
+            catch (error) {
+                if (!(error instanceof TelegramApiError) || error.disposition === 'not_sent')
+                    throw error;
+                return { status: error.disposition === 'rejected' ? 'rejected' : 'unknown', message: error.message };
+            }
+        },
+    });
+}

package/lib/stream-markdown.d.ts

@@ -0,0 +1,6 @@
+/** Render a physical slice while retaining the original Markdown's source coordinates. */
+export declare function sliceTelegramMarkdown(text: string, precedingText: string, capacity: number): {
+    readonly html: string;
+    readonly acceptedText: string;
+    readonly exhausted: boolean;
+};