@zhin.js/adapter-telegram 1.1.20 → 1.1.21

package/src/markdown-to-html.ts

@@ -1,76 +1,120 @@
-/**
- * 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.
- */
+/** Canonical Markdown → Telegram Bot API HTML, with optional source positions for streaming. */
+interface ProjectedText {
+  readonly text: string;
+  /** UTF-16 source position for every HTML code unit; -1 denotes generated markup. */
+  readonly source?: readonly number[];
+}
+
 export function markdownToTelegramHtml(markdown: string): string {
-  const protectedFragments: string[] = [];
-  const protect = (html: string): string => {
-    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: string): { readonly html: string; readonly source: readonly number[] } {
+  const value = projectMarkdown({ text: markdown, source: Array.from({ length: markdown.length }, (_, index) => index) });
+  return { html: value.text, source: value.source! };
+}
+
+function projectMarkdown(markdown: ProjectedText): ProjectedText {
+  const fragments: ProjectedText[] = [];
+  const literal = (text: string, origin = -1): ProjectedText => ({ text,
+    ...(markdown.source ? { source: Array<number>(text.length).fill(origin) } : {}) });
+  const protect = (value: ProjectedText): ProjectedText => {
+    const token = literal(`\uE000${fragments.length}\uE001`);
+    fragments.push(value);
     return token;
   };
+  const wrapped = (tag: string, value: ProjectedText): ProjectedText => 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']] as const) {
+    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;
+}
 
-  let value = protectTelegramFencedCode(markdown, protect);
-  value = value.replace(/`([^`\n]+)`/g, (_match, code) => (
-    protect(`<code>${escapeTelegramHtml(String(code))}</code>`)
-  ));
-  value = escapeTelegramHtml(value);
+function slice(value: ProjectedText, start: number, end?: number): ProjectedText {
+  return { text: value.text.slice(start, end), ...(value.source ? { source: value.source.slice(start, end) } : {}) };
+}
 
-  value = value
-    .replace(/!\[([^\[\]]*)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g, '$1')
-    .replace(/\[([^\[\]]+)\]\(([^()\s]+)(?:\s+&quot;[^&]*&quot;)?\)/g,
-      (_match, label: string, href: string) => 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>');
+function join(values: readonly ProjectedText[]): ProjectedText {
+  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<number>(value.text.length).fill(-1)) } : {}) };
+}
 
-  for (let index = 0; index < protectedFragments.length; index += 1) {
-    value = value.replace(`\uE000${index}\uE001`, protectedFragments[index]!);
+function replace(value: ProjectedText, pattern: RegExp,
+  project: (match: RegExpExecArray, group: (index: number) => ProjectedText) => ProjectedText,
+): ProjectedText {
+  const matcher = new RegExp(pattern.source, `${pattern.flags}d`);
+  const chunks: ProjectedText[] = [];
+  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;
   }
-  return value;
+  chunks.push(slice(value, cursor));
+  return join(chunks);
+}
+
+function escape(value: ProjectedText): ProjectedText {
+  const entities: Record<string, string> = { '&': '&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<number>(text.length).fill(origin) } : {}) };
+  });
 }
 
-function protectTelegramFencedCode(
-  markdown: string,
-  protect: (html: string) => string,
-): string {
-  const chunks: string[] = [];
+function fencedCode(value: ProjectedText, protect: (value: ProjectedText) => ProjectedText,
+  literal: (text: string) => ProjectedText,
+): ProjectedText {
+  const chunks: ProjectedText[] = [];
   let cursor = 0;
-  while (cursor < markdown.length) {
-    const opening = markdown.indexOf('```', cursor);
-    if (opening < 0) {
-      chunks.push(markdown.slice(cursor));
-      break;
-    }
-    chunks.push(markdown.slice(cursor, opening));
+  while (cursor < value.text.length) {
+    const opening = value.text.indexOf('```', cursor);
+    if (opening < 0) { chunks.push(slice(value, cursor)); break; }
+    chunks.push(slice(value, cursor, opening));
     const contentStart = opening + 3;
-    const closing = markdown.indexOf('```', contentStart);
-    if (closing < 0) {
-      chunks.push(markdown.slice(opening));
-      break;
-    }
-    const newline = markdown.indexOf('\n', contentStart);
+    const closing = value.text.indexOf('```', contentStart);
+    if (closing < 0) { chunks.push(slice(value, opening)); break; }
+    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: string): boolean {
@@ -78,9 +122,5 @@ function isSafeTelegramHref(value: string): boolean {
 }
 
 export function escapeTelegramHtml(value: string): string {
-  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/src/protocol.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.
@@ -12,11 +13,14 @@ import { escapeTelegramHtml, markdownToTelegramHtml } from './markdown-to-html.j
 const logger = getLogger('telegram');
 
 /** 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;
@@ -33,6 +37,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;
@@ -242,6 +248,8 @@ export type TelegramOutboundAction =
 export function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedTelegramConfig {
   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' | 'webhook' = polling === false ? 'webhook' : 'polling';
@@ -261,6 +269,8 @@ export function resolveTelegramConfig(config: TelegramEndpointConfig): ResolvedT
     mode,
     allowedUpdates: [...allowedUpdates],
     apiBaseUrl,
+    streaming: config.streaming !== false,
+    streamingIntervalMs,
     webhook,
   };
 }
@@ -522,6 +532,19 @@ function buildOutboundActions(
     replyTo != null ? { reply_parameters: { message_id: replyTo } } : {}
   );
 
+  const flushText = (): void => {
+    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 不透明引用）；
@@ -619,6 +642,7 @@ function buildOutboundActions(
         break;
       }
       case 'image': {
+        if (keyboard) flushText();
         const photo = mediaSource('image', data, 'image.png');
         if (photo) {
           actions.push({
@@ -636,6 +660,7 @@ function buildOutboundActions(
         break;
       }
       case 'video': {
+        if (keyboard) flushText();
         const video = mediaSource('video', data, 'video.mp4');
         if (video) {
           actions.push({
@@ -653,6 +678,7 @@ function buildOutboundActions(
         break;
       }
       case 'audio': {
+        if (keyboard) flushText();
         const audio = mediaSource('audio', data, 'audio.mp3');
         if (audio) {
           actions.push({
@@ -670,6 +696,7 @@ function buildOutboundActions(
         break;
       }
       case 'voice': {
+        if (keyboard) flushText();
         const voice = mediaSource('voice', data, 'voice.ogg');
         if (voice) {
           actions.push({
@@ -687,6 +714,7 @@ function buildOutboundActions(
         break;
       }
       case 'file': {
+        if (keyboard) flushText();
         const document = mediaSource('file', data, 'file');
         if (document) {
           actions.push({
@@ -706,6 +734,7 @@ function buildOutboundActions(
       case 'sticker': {
         const sticker = mediaSource('sticker', data, 'sticker.webp');
         if (sticker) {
+          flushText();
           actions.push({
             method: 'sendSticker',
             params: { chat_id: chatId, sticker, ...replyParams() },
@@ -714,6 +743,7 @@ function buildOutboundActions(
         break;
       }
       case 'location': {
+        flushText();
         actions.push({
           method: 'sendLocation',
           params: {
@@ -730,33 +760,8 @@ function buildOutboundActions(
     }
   }
 
-  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/src/self-profile.ts

@@ -0,0 +1,58 @@
+import type { EndpointProfile } from 'zhin.js/adapter';
+import type { SelfProfile } from '@zhin.js/im-contract';
+import type { TelegramClientApi } from './telegram-client.js';
+import { TelegramApiError } from './api-error.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 function createTelegramSelfProfile({ client, current, nicknameChanged }: TelegramSelfProfileOptions): EndpointProfile {
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze(['nickname', 'signature', 'bio', 'avatar']),
+    get current() { return current(); },
+    async read({ signal }) {
+      const [name, description, shortDescription] = await Promise.all([
+        client.callApi<{ name: string }>('getMyName', {}, signal),
+        client.callApi<{ description: string }>('getMyDescription', {}, signal),
+        client.callApi<{ short_description: string }>('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<boolean>('setMyProfilePhoto', form, signal);
+          return accepted === true ? { status: 'updated' } : { status: 'rejected', message: 'Telegram rejected the avatar change' };
+        }
+        let method: string;
+        let params: Record<string, unknown>;
+        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<boolean>(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/src/stream-markdown.ts

@@ -0,0 +1,67 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { projectTelegramMarkdown } from './markdown-to-html.js';
+
+interface HtmlTag { readonly name: string; readonly html: string; }
+interface VisibleUnit {
+  readonly html: string;
+  readonly sourceStart: number;
+  readonly sourceEnd: number;
+  readonly tags: readonly HtmlTag[];
+}
+
+/** Render a physical slice while retaining the original Markdown's source coordinates. */
+export function sliceTelegramMarkdown(text: string, precedingText: string, capacity: number): {
+  readonly html: string;
+  readonly acceptedText: string;
+  readonly exhausted: boolean;
+} {
+  const full = precedingText + text;
+  const projection = projectTelegramMarkdown(full);
+  const units: VisibleUnit[] = [];
+  const tags: HtmlTag[] = [];
+  const trimStart = projection.html.length - projection.html.trimStart().length;
+  const trimEnd = projection.html.trimEnd().length;
+  const html = projection.html.slice(trimStart, trimEnd);
+  const matcher = /<\/?[a-z][^>]*>|&(?:amp|lt|gt|quot);|[\s\S]/gu;
+  for (const match of html.matchAll(matcher)) {
+    const raw = match[0];
+    if (raw.startsWith('<')) {
+      const tag = /^<(\/?)([a-z]+)/.exec(raw)!;
+      if (tag[1]) {
+        if (tags.at(-1)?.name !== tag[2]) throw unsupportedProjection();
+        tags.pop();
+      } else tags.push({ name: tag[2], html: raw });
+      continue;
+    }
+    const origins = projection.source.slice(trimStart + match.index, trimStart + match.index + raw.length).filter(position => position >= 0);
+    if (!origins.length) throw unsupportedProjection();
+    const sourceStart = Math.min(...origins), sourceEnd = Math.max(...origins) + 1;
+    if (sourceEnd > precedingText.length) units.push({ html: raw, sourceStart, sourceEnd, tags: [...tags] });
+  }
+  if (tags.length) throw unsupportedProjection();
+  if (!units.length) return { html: '', acceptedText: text, exhausted: false };
+
+  // One decoded code point is one unit. Keep replacement expansions together
+  // when their source positions coincide (for example a Markdown bullet).
+  let take = Math.min(capacity, units.length);
+  while (take > 0 && take < units.length && units[take].sourceStart < units[take - 1].sourceEnd) take--;
+  if (take <= 0) throw new EndpointDeliveryError('stream_capacity', 'Telegram prefix leaves no room for a Markdown unit', 'not_sent');
+  const end = take < units.length ? units[take].sourceStart : full.length;
+  if (end <= precedingText.length) throw unsupportedProjection();
+  let rendered = '';
+  let active: readonly HtmlTag[] = [];
+  for (const unit of units.slice(0, take)) {
+    let common = 0;
+    while (common < active.length && common < unit.tags.length && active[common].html === unit.tags[common].html) common++;
+    for (let index = active.length - 1; index >= common; index--) rendered += `</${active[index].name}>`;
+    for (const tag of unit.tags.slice(common)) rendered += tag.html;
+    rendered += unit.html;
+    active = unit.tags;
+  }
+  for (let index = active.length - 1; index >= 0; index--) rendered += `</${active[index].name}>`;
+  return { html: rendered, acceptedText: text.slice(0, end - precedingText.length), exhausted: take < units.length || take === capacity };
+}
+
+function unsupportedProjection(): EndpointDeliveryError {
+  return new EndpointDeliveryError('unsupported_operation', 'Telegram Markdown projection has no safe source mapping', 'not_sent');
+}

package/src/streaming.ts

@@ -0,0 +1,110 @@
+import { randomInt } from 'node:crypto';
+import type { EndpointMessageStream, EndpointStreamAcknowledgement, EndpointStreaming, EndpointStreamRequest } from 'zhin.js/adapter';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { formatOutboundPlan, type TelegramWireSegment } from './protocol.js';
+import { escapeTelegramHtml } from './markdown-to-html.js';
+import { sliceTelegramMarkdown } from './stream-markdown.js';
+import type { TelegramClientApi } from './telegram-client.js';
+
+function supportsTelegramStream(request: Pick<EndpointStreamRequest, 'conversation' | 'source'>): boolean {
+  return request.conversation.kind === 'private' && !request.conversation.parent;
+}
+
+/** Drafts are previews; only finish performs a persistent send. */
+export function createTelegramStreaming(getClient: () => Pick<TelegramClientApi, 'callApi'>, minIntervalMs = 500): EndpointStreaming {
+  return {
+    mode: 'draft',
+    minIntervalMs,
+    supports: supportsTelegramStream,
+    open(request): EndpointMessageStream | undefined {
+      if (!supportsTelegramStream(request)) return undefined;
+      if (request.prefix?.some(segment => segment.type !== 'reply' && segment.type !== 'mention')) return undefined;
+      const prefix: TelegramWireSegment[] = (request.prefix ?? []).map(segment => segment.type === 'mention'
+        ? { type: 'at', data: { id: 'target' in segment.data ? segment.data.target : undefined,
+          name: 'name' in segment.data ? segment.data.name : undefined } }
+        : { type: segment.type, data: { ...segment.data } });
+      const draftId = randomInt(1, 2_147_483_647);
+      const cancellation = new AbortController();
+      const signal = request.signal ? AbortSignal.any([request.signal, cancellation.signal]) : cancellation.signal;
+      const threadId = request.conversation.threadId === undefined ? undefined : Number(request.conversation.threadId);
+      if (threadId !== undefined && (!Number.isSafeInteger(threadId) || threadId <= 0)) {
+        throw new EndpointDeliveryError('invalid_payload', 'Telegram topic id must be a positive integer', 'not_sent');
+      }
+      let acceptedText = '';
+      let messageId: string | undefined;
+      let exhausted = false;
+      let contentUnavailable = false;
+      let confirmed: { readonly source: string; readonly params: Record<string, unknown> & { readonly text: string }; readonly exhausted: boolean } | undefined;
+      let failure: unknown;
+      let completion: Promise<EndpointStreamAcknowledgement> | undefined;
+      const acknowledgement = (): EndpointStreamAcknowledgement => ({
+        status: messageId ? 'sent' : acceptedText ? 'preview' : 'buffered', acceptedText,
+        ...(messageId ? { messageId } : {}),
+        ...(exhausted ? { exhausted: true as const } : {}),
+        ...(contentUnavailable ? { contentUnavailable: true as const } : {}),
+      });
+      const prepare = (text: string) => {
+        const mentionText = prefix.map(segment => segment.type === 'at' && segment.data?.id
+          ? `@${segment.data.name || segment.data.id}` : '').join('');
+        const mentionLength = Array.from(mentionText).length;
+        const capacity = 4096 - mentionLength;
+        if (capacity <= 0) throw new EndpointDeliveryError('stream_capacity', 'Telegram prefix exceeds its text container', 'not_sent');
+        const markdown = request.format === 'markdown'
+          ? sliceTelegramMarkdown(text, request.continuation?.precedingText ?? '', capacity) : undefined;
+        const source = markdown?.acceptedText ?? Array.from(text).slice(0, capacity).join('');
+        const plan = formatOutboundPlan(request.conversation.id, [...prefix, request.format === 'markdown'
+          ? { type: 'markdown', data: { content: source } }
+          : { type: 'text', data: { text: source } }]);
+        const action = plan.actions[0];
+        if (plan.actions.length !== 1 || action?.method !== 'sendMessage') {
+          throw new EndpointDeliveryError('unsupported_operation', 'Telegram draft requires one text container', 'not_sent');
+        }
+        const params = { ...action.params,
+          ...(markdown ? { text: escapeTelegramHtml(mentionText) + markdown.html } : {}),
+          ...(threadId !== undefined ? { message_thread_id: threadId } : {}) };
+        return { source, params, exhausted: markdown?.exhausted ?? (source.length < text.length || Array.from(params.text).length === 4096) };
+      };
+      const send = async (text: string, final: boolean): Promise<EndpointStreamAcknowledgement> => {
+        if (failure) throw failure;
+        if (signal.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'Telegram draft cancelled', 'not_sent');
+        if (!text.startsWith(acceptedText)) throw new EndpointDeliveryError('invalid_payload', 'Telegram draft cannot replace its accepted source prefix', 'not_sent');
+        if (!text.trim() || (!final && text === acceptedText)) return acknowledgement();
+        const next = final && text === acceptedText && confirmed ? confirmed : prepare(text);
+        const { source, params } = next;
+        if (!final && source === acceptedText) return acknowledgement();
+        if (!params.text) return acknowledgement();
+        try {
+          if (final) {
+            const result = await getClient().callApi<{ message_id?: number }>('sendMessage', params, signal);
+            if (!Number.isSafeInteger(result?.message_id) || result.message_id! <= 0) {
+              throw new EndpointDeliveryError('delivery_unconfirmed', 'Telegram final send returned no valid message_id', 'unknown');
+            }
+            messageId = String(result.message_id);
+          } else {
+            const { reply_parameters: _reply, ...draftParams } = params;
+            const result = await getClient().callApi<unknown>('sendMessageDraft', { ...draftParams, draft_id: draftId }, signal);
+            if (result !== true) throw new EndpointDeliveryError('delivery_unconfirmed', 'Telegram draft response is unconfirmed', 'unknown');
+          }
+          acceptedText = source;
+          // A temporary Markdown preview can still reinterpret an unfinished fence/link.
+          // Rollover persists this container, so only the final source may trigger it.
+          exhausted = next.exhausted && (final || request.format !== 'markdown');
+          contentUnavailable = request.format === 'markdown'
+            && (Boolean(request.continuation?.precedingText) || exhausted || source.length < text.length);
+          confirmed = next;
+          return acknowledgement();
+        } catch (error) {
+          failure = error;
+          throw error;
+        }
+      };
+      return {
+        write: text => completion
+          ? Promise.reject(new EndpointDeliveryError('stream_closed', 'Telegram draft is finishing', 'not_sent'))
+          : send(text, false),
+        finish: text => completion ??= send(text, true),
+        cancel: () => { cancellation.abort(); },
+      };
+    },
+  };
+}