@segmentstream/agent 0.6.3 → 0.6.4

package/README.md

@@ -314,6 +314,28 @@ There are no `document_ids` relay arguments, `AgentMessage` transport or
 `<agent_request>` turns. Stored file tools keep their member authorization in the
 current conversation; group purpose and document restrictions still apply.
 
+## Telegram answer delivery
+
+Agent replies render Markdown as visible text and Telegram entities. Headings, emphasis,
+links, lists, quotations and code are supported; decorative separator lines are removed.
+The customer-text guard checks the rendered prose and link destinations. If rendering fails,
+delivery uses clean plain text. Only an explicit Telegram entity-formatting refusal permits
+a plain-text retry; timeouts and other uncertain outcomes must never trigger an automatic resend.
+Attachment captions use the same rendering and fallback rules.
+
+Replies split at paragraph, line, sentence, word or UTF-16 boundaries within Telegram's 4096-unit
+limit. Entities are rebased or clipped on each part, and surrogate pairs stay intact. The whole
+reply or attachment batch occupies one shared FIFO slot per workspace/connection/chat, including
+all forum topics. A failed slot releases the next one. Sends require a positive Telegram message
+id; missing acknowledgements are errors and archive as unknown. Partial-delivery errors retain
+the message ids already acknowledged.
+
+This queue lives in one SDK runtime. It does not coordinate separate serverless instances or
+the ontology service's exact `chat_post_message` provider. Ordering all of those together needs
+a shared provider sequencer. Exact posting retains its approved literal text and durable receipt;
+this formatter does not rewrite approved posts or their confirmation cards. The removed
+`agent_chat.send_message` instruction relay must not be restored as a delivery fallback.
+
 ## Local development
 
 `eve dev` in `agent/` runs the agent locally. The Telegram channel stays silent outside production.
@@ -395,7 +417,7 @@ Eve resolution, so member/topic routing survives a cold start. No second provide
 
 ## Release and migration
 
-The tested release uses agent SDK 0.6.3, Eve 0.76.3 and ontology SDK 0.28.2.
+The tested release uses agent SDK 0.6.4, Eve 0.76.3 and ontology SDK 0.28.3.
 Deploy the agent first, then backend archive migration 0033/API, then the ontology
 with its declared Telegram provider mapping and explicit `agent_chat:post_message`
 grant. Older ontologies keep ordinary tools working without the extra envelope.

package/dist/extension/lib/telegram/adapter.mjs

@@ -14,6 +14,7 @@ import { agentIdentities } from "../identities.mjs";
 import { conversations } from "../conversations.mjs";
 import { observedMessages } from "./observed.mjs";
 import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
+import { telegramSendScope } from "./send-queue.mjs";
 import { failureText, reportTelegramError, safeTelegramFetch, withDeliveryLocale } from "./customer-text.mjs";
 import { captureRouteDecider, captureTelegramFetch, conversationIdentities, telegramConversationCapture } from "./conversations.mjs";
 import { runtimeTokenVerifier } from "../runtime-identity.mjs";
@@ -127,7 +128,7 @@ function segmentstreamTelegram(options) {
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
 			fileBaseUrl: TELEGRAM_PROXY_ORIGIN,
-			fetch: (input, init) => safeTelegramFetch(captureTelegramFetch(telegramProxyFetch(proxy()), archive, pairing))(input, init)
+			fetch: (input, init) => safeTelegramFetch(captureTelegramFetch(telegramProxyFetch(proxy(), telegramSendScope(environment, settings().connection)), archive, pairing), telegramSendScope(environment, settings().connection))(input, init)
 		},
 		credentials: {
 			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
@@ -228,7 +229,7 @@ function segmentstreamTelegram(options) {
 		events: {
 			...telegramFailureEvents,
 			...telegramConfirmationEvents(confirmationRenderer({ model: () => options.models().decision }), archive),
-			"message.completed": replyDelivery(observed)
+			"message.completed": replyDelivery(observed, () => telegramSendScope(environment, settings().connection))
 		}
 	});
 	const adapter = channel.adapter;

package/dist/extension/lib/telegram/attachments-send.d.ts

@@ -24,7 +24,7 @@ export interface SentFile {
 /** Bare ids are document records; explicit references select other entities and file properties. */
 export declare function sendAttachmentsInput(value: Record<string, unknown>): SendAttachmentsInput;
 /** All destinations and credentials come from the channel's turn and mounted configuration. */
-export declare function sendAttachments(options: {
+interface SendOptions {
     readonly input: SendAttachmentsInput;
     readonly principal: SessionAuthContext | null;
     readonly sessionId: string;
@@ -32,10 +32,14 @@ export declare function sendAttachments(options: {
     readonly environment?: Environment;
     readonly token?: RuntimeToken;
     readonly fetch?: typeof fetch;
-}): Promise<{
+}
+type SendResult = {
     readonly files: ReadonlyArray<SentFile>;
 } | {
     readonly error: string;
     readonly detail: string;
     readonly reference: string;
-}>;
+};
+/** Reserve the chat before downloading, and keep every album/batch in the same queue slot. */
+export declare function sendAttachments(options: SendOptions): Promise<SendResult>;
+export {};

package/dist/extension/lib/telegram/attachments-send.mjs

@@ -11,7 +11,8 @@ import { redactDiagnostic } from "../diagnostics.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
 import { ACT_AS_HEADER } from "../ontology-connection.mjs";
 import { AttachmentError, CONVERSATION_HEADER, SESSION_HEADER } from "../attachments.mjs";
-import { customerCopy, customerText, reportTelegramError } from "./customer-text.mjs";
+import { inTelegramSendQueue, telegramSendScope } from "./send-queue.mjs";
+import { customerCopy, customerMessage, formattingRefused, reportTelegramError } from "./customer-text.mjs";
 import { confirmationLocale } from "./confirmation-text.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
 import { attachmentOwner } from "../attachment-tools.mjs";
@@ -74,7 +75,11 @@ async function boundedDownload(response, maximum) {
 	}
 	return new Uint8Array(Buffer.concat(chunks));
 }
-async function sendAttachments(options) {
+function sendAttachments(options) {
+	const chatId = options.principal?.attributes.chatId;
+	return typeof chatId === "string" && options.connection !== void 0 ? inTelegramSendQueue(telegramSendScope(options.environment ?? process.env, options.connection), chatId, () => sendAttachmentsInOrder(options)) : sendAttachmentsInOrder(options);
+}
+async function sendAttachmentsInOrder(options) {
 	const environment = options.environment ?? process.env;
 	const principal = options.principal;
 	const locale = confirmationLocale(principal);
@@ -117,7 +122,7 @@ async function sendAttachments(options) {
 		connection: options.connection,
 		token,
 		fetch: fetchImpl
-	}));
+	}), telegramSendScope(environment, options.connection));
 	const results = options.input.documentIds.map(({ id }) => ({
 		id,
 		filename: ""
@@ -196,12 +201,18 @@ async function sendAttachments(options) {
 		if (files.length === 1) {
 			const file = files[0];
 			form.set(file.type, file.blob, file.filename);
-			if (caption !== void 0) form.set("caption", caption);
+			if (caption !== void 0) {
+				form.set("caption", caption.text);
+				if (caption.entities.length > 0) form.set("caption_entities", JSON.stringify(caption.entities));
+			}
 		} else {
 			form.set("media", JSON.stringify(files.map((file, index) => ({
 				type: file.type,
 				media: `attach://file${index}`,
-				...index === 0 && caption !== void 0 ? { caption } : {}
+				...index === 0 && caption !== void 0 ? {
+					caption: caption.text,
+					...caption.entities.length > 0 ? { caption_entities: caption.entities } : {}
+				} : {}
 			}))));
 			files.forEach((file, index) => form.set(`file${index}`, file.blob, file.filename));
 		}
@@ -211,7 +222,7 @@ async function sendAttachments(options) {
 			body: form
 		});
 	}
-	let caption = options.input.caption === void 0 ? void 0 : customerText(options.input.caption, locale);
+	let caption = options.input.caption === void 0 ? void 0 : customerMessage(options.input.caption, locale);
 	let cursor = 0;
 	while (cursor < uploads.length) {
 		const batch = [uploads[cursor++]];
@@ -227,7 +238,14 @@ async function sendAttachments(options) {
 		}
 		try {
 			if (size > 2097152) throw refused("too_large", PROXY_LIMIT);
-			const response = await telegram(request);
+			let response = await telegram(request);
+			if (caption !== void 0 && caption.entities.length > 0 && await formattingRefused(response)) {
+				caption = {
+					text: caption.text,
+					entities: []
+				};
+				response = await telegram(multipart(batch, caption));
+			}
 			const answer = await response.json();
 			if (!response.ok || !isRecord(answer) || answer.ok !== true) {
 				console.error("[segmentstream] Telegram attachment upload refused", {

package/dist/extension/lib/telegram/conversations.mjs

@@ -272,12 +272,14 @@ function captureTelegramFetch(fetchImpl, archive, identities) {
 			}
 			throw error;
 		}
-		const result = record(await response.clone().json());
+		const result = record(await response.clone().json().catch(() => null));
+		const messageId = id(record(result.result).message_id);
+		const acknowledged = edit || messageId !== null && /^[1-9]\d*$/u.test(messageId);
 		await archive.append({
 			...event,
 			eventId: `${event.eventId}:result`,
-			status: response.ok && result.ok === true ? "completed" : "failed",
-			messageId: id(record(result.result).message_id) ?? event.messageId
+			status: response.ok && result.ok === true && acknowledged ? "completed" : result.ok === false ? "failed" : "unknown",
+			messageId: messageId ?? event.messageId
 		});
 		return response;
 	};

package/dist/extension/lib/telegram/customer-text.d.ts

@@ -1,3 +1,4 @@
+import { type TelegramText } from "./format.js";
 export declare function withDeliveryLocale<T>(locale: string, run: () => T, threadId?: string): T;
 export declare function currentLocale(): string;
 export declare function currentThreadId(): string | undefined;
@@ -16,5 +17,16 @@ export declare function isTechnicalText(text: string): boolean;
 export declare function reportTelegramError(operation: string, error: unknown, metadata?: Record<string, unknown>, secrets?: ReadonlySet<string>): string;
 export declare function failureText(errorId: string, kind?: "failed" | "recovery" | "attachment" | "authorization" | "response", locale?: string): string;
 export declare function customerText(text: string, locale?: string): string;
+/** Check what Telegram will display, including hidden link destinations, after removing markup. */
+export declare function customerMessage(text: string, locale?: string): TelegramText;
+/** Only a definite formatting refusal permits resending; network/unknown failures never do. */
+export declare function formattingRefused(response: Response): Promise<boolean>;
+export declare class TelegramDeliveryError extends Error {
+    readonly reference: string;
+    readonly delivery: "failed" | "unknown";
+    readonly messageIds: readonly number[];
+    readonly name = "TelegramDeliveryError";
+    constructor(reference: string, delivery: "failed" | "unknown", messageIds: readonly number[]);
+}
 /** Covers framework defaults, edits and callback notices as well as ordinary agent replies. */
-export declare function safeTelegramFetch(fetchImpl: typeof fetch): typeof fetch;
+export declare function safeTelegramFetch(fetchImpl: typeof fetch, scope?: string): typeof fetch;

package/dist/extension/lib/telegram/customer-text.mjs

@@ -7,6 +7,8 @@ __eveCreateRequire(import.meta.url);
 import { isExactChatPostCard } from "./chat-post-card.mjs";
 import { redactDiagnostic } from "../diagnostics.mjs";
 import { currentInboundRequest } from "./inbound-request.mjs";
+import { plainTelegramText, splitTelegramText, telegramMarkdown } from "./format.mjs";
+import { inTelegramSendQueue } from "./send-queue.mjs";
 import { randomBytes } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 const deliveryLocale = new AsyncLocalStorage();
@@ -84,7 +86,47 @@ function customerText(text, locale = currentLocale()) {
 	if (!isTechnicalText(text)) return text;
 	return failureText(reportTelegramError("technical_text_blocked", { text }), "response", locale);
 }
-function safeTelegramFetch(fetchImpl) {
+function customerMessage(text, locale = currentLocale()) {
+	let message;
+	try {
+		message = telegramMarkdown(text);
+	} catch (error) {
+		reportTelegramError("markdown_render_failed", error);
+		message = {
+			text: plainTelegramText(text),
+			entities: []
+		};
+	}
+	const links = message.entities.flatMap((entity) => entity.url === void 0 ? [] : [entity.url]);
+	const visible = customerText(message.text, locale);
+	if (visible !== message.text) return {
+		text: visible,
+		entities: []
+	};
+	if (links.some(isTechnicalText)) return {
+		text: failureText(reportTelegramError("unsafe_markdown_link", new Error("Credential-bearing link refused.")), "response", locale),
+		entities: []
+	};
+	return message;
+}
+async function formattingRefused(response) {
+	if (response.status !== 400) return false;
+	const body = await response.clone().json().catch(() => null);
+	return body?.ok === false && typeof body.description === "string" && (/can't parse entities|cannot parse entities|entity (?:bounds|offset|length)|entities (?:are|too)/iu.test(body.description) || /unsupported (?:start tag|parse mode)/iu.test(body.description));
+}
+var TelegramDeliveryError = class extends Error {
+	reference;
+	delivery;
+	messageIds;
+	name = "TelegramDeliveryError";
+	constructor(reference, delivery, messageIds) {
+		super(`Telegram delivery ${delivery}; reference ${reference}. Do not automatically resend.`);
+		this.reference = reference;
+		this.delivery = delivery;
+		this.messageIds = messageIds;
+	}
+};
+function safeTelegramFetch(fetchImpl, scope = "telegram") {
 	const methods = new Set([
 		"sendMessage",
 		"editMessageText",
@@ -98,7 +140,18 @@ function safeTelegramFetch(fetchImpl) {
 		const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
 		if (!methods.has(url.split("/").at(-1) ?? "") || typeof init?.body !== "string") return fetchImpl(input, init);
 		const body = JSON.parse(init.body);
-		for (const field of ["text", "caption"]) if (typeof body[field] === "string" && !isExactChatPostCard(body[field])) body[field] = customerText(body[field]);
+		for (const field of ["text", "caption"]) if (typeof body[field] === "string" && !isExactChatPostCard(body[field])) {
+			const entityField = field === "text" ? "entities" : "caption_entities";
+			const existing = body[entityField];
+			const message = Array.isArray(existing) ? {
+				text: body[field],
+				entities: existing
+			} : customerMessage(body[field]);
+			const guarded = customerText(message.text);
+			body[field] = message.entities.some((entity) => typeof entity.url === "string" && isTechnicalText(entity.url)) ? failureText(reportTelegramError("unsafe_entity_link", new Error("Credential-bearing link refused.")), "response") : guarded;
+			if (!url.endsWith("/answerCallbackQuery")) body[entityField] = body[field] === message.text ? message.entities : [];
+			delete body.parse_mode;
+		}
 		if (Array.isArray(body.media)) body.media = body.media.map((item) => ({
 			...item,
 			...typeof item.caption === "string" ? { caption: customerText(item.caption) } : {}
@@ -112,10 +165,57 @@ function safeTelegramFetch(fetchImpl) {
 				text: currentLocale().startsWith("ru") ? "Продолжить" : "Continue"
 			};
 		}));
-		return fetchImpl(input, {
-			...init,
-			body: JSON.stringify(body)
-		});
+		const send = async () => {
+			const parts = url.endsWith("/sendMessage") && typeof body.text === "string" && !isExactChatPostCard(body.text) ? splitTelegramText({
+				text: body.text,
+				entities: body.entities ?? []
+			}) : [null];
+			let first;
+			const messageIds = [];
+			const attempt = async (outgoing) => {
+				try {
+					return await fetchImpl(input, {
+						...init,
+						body: JSON.stringify(outgoing)
+					});
+				} catch (error) {
+					throw new TelegramDeliveryError(reportTelegramError("telegram_send_unknown", error, { messageIds }), "unknown", messageIds);
+				}
+			};
+			for (const [index, part] of parts.entries()) {
+				const outgoing = part === null ? { ...body } : {
+					...body,
+					text: part.text,
+					entities: part.entities
+				};
+				if (index < parts.length - 1) delete outgoing.reply_markup;
+				let response = await attempt(outgoing);
+				const entityField = typeof outgoing.text === "string" ? "entities" : "caption_entities";
+				if (Array.isArray(outgoing[entityField]) && outgoing[entityField].length > 0 && await formattingRefused(response)) {
+					delete outgoing[entityField];
+					delete outgoing.parse_mode;
+					response = await attempt(outgoing);
+				}
+				const result = await response.clone().json().catch(() => null);
+				if (url.endsWith("/sendMessage")) {
+					const id = result?.result?.message_id;
+					if (!response.ok || result?.ok !== true || typeof id !== "number" || !Number.isSafeInteger(id) || id < 1) {
+						const delivery = result?.ok === false ? "failed" : "unknown";
+						throw new TelegramDeliveryError(reportTelegramError("telegram_send_unacknowledged", {
+							status: response.status,
+							result,
+							messageIds,
+							delivery
+						}), delivery, messageIds);
+					}
+					messageIds.push(id);
+				} else if (!response.ok || result?.ok !== true) return response;
+				first ??= response;
+			}
+			if (first === void 0) throw new Error("Telegram message has no visible text; nothing was sent.");
+			return first;
+		};
+		return typeof body.chat_id === "string" || typeof body.chat_id === "number" ? inTelegramSendQueue(scope, String(body.chat_id), send) : send();
 	};
 }
-export { currentLocale, currentThreadId, customerCopy, customerText, failureText, isTechnicalText, reportTelegramError, safeTelegramFetch, withDeliveryLocale };
+export { TelegramDeliveryError, currentLocale, currentThreadId, customerCopy, customerMessage, customerText, failureText, formattingRefused, isTechnicalText, reportTelegramError, safeTelegramFetch, withDeliveryLocale };

package/dist/extension/lib/telegram/format.d.ts

@@ -0,0 +1,17 @@
+export interface TelegramEntity {
+    readonly type: string;
+    readonly offset: number;
+    readonly length: number;
+    readonly url?: string;
+    readonly language?: string;
+}
+export interface TelegramText {
+    readonly text: string;
+    readonly entities: readonly TelegramEntity[];
+}
+/** Render Markdown as visible text plus UTF-16 entities; no HTML/Markdown parse mode is needed. */
+export declare function telegramMarkdown(markdown: string): TelegramText;
+/** A failed renderer still produces customer prose, without obvious Markdown/decorative markers. */
+export declare function plainTelegramText(text: string): string;
+/** Paragraph, line, sentence, word, then hard boundaries. All lengths/offsets are UTF-16. */
+export declare function splitTelegramText(message: TelegramText, maximum?: number): readonly TelegramText[];

package/dist/extension/lib/telegram/format.mjs

@@ -0,0 +1,171 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { Lexer } from "marked";
+function telegramMarkdown(markdown) {
+	const source = markdown.replace(/^[ \t]*[━─═]{3,}[ \t]*$/gmu, "");
+	const entities = [];
+	let text = "";
+	let nodes = 0;
+	const append = (value) => {
+		text += value;
+	};
+	function span(type, run, extra = {}) {
+		const offset = text.length;
+		run();
+		if (text.length > offset) entities.push({
+			type,
+			offset,
+			length: text.length - offset,
+			...extra
+		});
+	}
+	function render(tokens = [], depth = 0) {
+		if (depth > 32) throw new Error("Markdown nesting exceeds the Telegram rendering limit.");
+		for (const token of tokens) {
+			if (++nodes > 2e4) throw new Error("Markdown exceeds the Telegram rendering limit.");
+			switch (token.type) {
+				case "strong":
+				case "em":
+				case "del":
+					span(token.type === "strong" ? "bold" : token.type === "em" ? "italic" : "strikethrough", () => render(token.tokens, depth + 1));
+					break;
+				case "heading":
+					span("bold", () => render(token.tokens, depth + 1));
+					append("\n\n");
+					break;
+				case "paragraph":
+					render(token.tokens, depth + 1);
+					append("\n\n");
+					break;
+				case "blockquote":
+					span("blockquote", () => render(token.tokens, depth + 1));
+					break;
+				case "codespan":
+					span("code", () => append(token.text));
+					break;
+				case "code":
+					span("pre", () => append(token.text), token.lang ? { language: token.lang.split(/\s/u)[0] } : {});
+					append("\n\n");
+					break;
+				case "link": {
+					let url;
+					try {
+						url = new URL(token.href);
+					} catch {
+						render(token.tokens, depth + 1);
+						break;
+					}
+					if (![
+						"https:",
+						"http:",
+						"mailto:",
+						"tel:"
+					].includes(url.protocol) || url.username || url.password) throw new Error("Markdown link has an unsupported or credential-bearing destination.");
+					span("text_link", () => render(token.tokens, depth + 1), { url: token.href });
+					break;
+				}
+				case "list":
+					for (const [index, item] of token.items.entries()) {
+						append(token.ordered ? `${Number(token.start) + index}. ` : "• ");
+						if (item.task) append(item.checked ? "☑ " : "☐ ");
+						render(item.tokens, depth + 1);
+						if (!text.endsWith("\n")) append("\n");
+					}
+					append("\n");
+					break;
+				case "table":
+					for (const [index, row] of [token.header, ...token.rows].entries()) {
+						for (const [cellIndex, cell] of row.entries()) {
+							if (cellIndex > 0) append(" | ");
+							if (index === 0) span("bold", () => render(cell.tokens, depth + 1));
+							else render(cell.tokens, depth + 1);
+						}
+						append("\n");
+					}
+					append("\n");
+					break;
+				case "image":
+					append(token.text);
+					break;
+				case "hr":
+					append("\n\n");
+					break;
+				case "br":
+					append("\n");
+					break;
+				case "space": break;
+				case "def": break;
+				case "text":
+					if (token.tokens) render(token.tokens, depth + 1);
+					else append(token.text);
+					break;
+				default: append("text" in token && typeof token.text === "string" ? token.text : token.raw);
+			}
+		}
+	}
+	render(Lexer.lex(source, { gfm: true }));
+	text = text.trimEnd();
+	for (const match of text.matchAll(/(?<![\w@])@[a-z][a-z0-9_]{4,31}(?!\w)/giu)) {
+		const offset = match.index;
+		const end = offset + match[0].length;
+		if (!entities.some((entity) => [
+			"code",
+			"pre",
+			"text_link"
+		].includes(entity.type) && entity.offset < end && entity.offset + entity.length > offset)) entities.push({
+			type: "mention",
+			offset,
+			length: match[0].length
+		});
+	}
+	return {
+		text,
+		entities: entities.map((entity) => ({
+			...entity,
+			length: Math.min(entity.length, text.length - entity.offset)
+		})).filter((entity) => entity.length > 0).sort((a, b) => a.offset - b.offset || b.length - a.length)
+	};
+}
+function plainTelegramText(text) {
+	return text.replace(/^[ \t]*[━─═]{3,}[ \t]*$/gmu, "").replace(/^\s*```[^\n]*\n?|```\s*$/gmu, "").replace(/!?\[([^\]]+)\]\([^\n)]+\)/gu, "$1").replace(/(?:\*\*|__|~~|`)/gu, "").replace(/(?<![\w@])([*_])([^\n*_]+)\1(?!\w)/gu, "$2").replace(/^ {0,3}(?:>\s*)+/gmu, "").replace(/^ {0,3}#{1,6}\s+/gmu, "").replace(/^ {0,3}[-*+]\s+/gmu, "• ").trim();
+}
+function splitTelegramText(message, maximum = 4096) {
+	if (!Number.isSafeInteger(maximum) || maximum < 2) throw new RangeError("Telegram split size must be at least 2 UTF-16 units.");
+	const parts = [];
+	let start = 0;
+	while (start < message.text.length) {
+		let end = Math.min(start + maximum, message.text.length);
+		if (end < message.text.length) {
+			const window = message.text.slice(start, end);
+			const paragraph = window.lastIndexOf("\n\n");
+			const line = window.lastIndexOf("\n");
+			const sentence = [...window.matchAll(/[.!?。！？][ \t]+/gu)].at(-1);
+			const word = window.lastIndexOf(" ");
+			const boundary = paragraph > 0 ? paragraph + 2 : line > 0 ? line + 1 : sentence?.index !== void 0 ? sentence.index + sentence[0].length : word > 0 ? word + 1 : maximum;
+			end = window.slice(0, boundary).trim() === "" ? Math.min(start + maximum, message.text.length) : start + boundary;
+			for (const entity of message.entities) if (entity.offset > start && entity.offset < end && entity.offset + entity.length > end) end = entity.offset;
+			if (/^[\uDC00-\uDFFF]$/u.test(message.text[end] ?? "") && /^[\uD800-\uDBFF]$/u.test(message.text[end - 1] ?? "")) end -= 1;
+		}
+		if (end <= start) end = Math.min(start + maximum, message.text.length);
+		const entities = message.entities.flatMap((entity) => {
+			const left = Math.max(start, entity.offset);
+			const right = Math.min(end, entity.offset + entity.length);
+			return right > left ? [{
+				...entity,
+				offset: left - start,
+				length: right - left
+			}] : [];
+		});
+		parts.push({
+			text: message.text.slice(start, end),
+			entities
+		});
+		start = end;
+	}
+	return parts;
+}
+export { plainTelegramText, splitTelegramText, telegramMarkdown };

package/dist/extension/lib/telegram/proxy-fetch.d.ts

@@ -25,4 +25,4 @@ export declare function telegramProxyRoute(url: string): {
     readonly path: string;
 };
 /** The `fetch` eve's Telegram channel calls; see the module comment. */
-export declare function telegramProxyFetch(proxy: ConnectionProxy): typeof fetch;
+export declare function telegramProxyFetch(proxy: ConnectionProxy, scope?: string): typeof fetch;

package/dist/extension/lib/telegram/proxy-fetch.mjs

@@ -4,6 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { inTelegramSendQueue } from "./send-queue.mjs";
 const TELEGRAM_PROXY_ORIGIN = "https://telegram.segmentstream.invalid";
 const TELEGRAM_PLACEHOLDER_TOKEN = "segmentstream-connection";
 const METHOD_PREFIX = `${TELEGRAM_PROXY_ORIGIN}/bot${TELEGRAM_PLACEHOLDER_TOKEN}/`;
@@ -46,7 +47,7 @@ function proxyMethod(method) {
 function hasNullBody(status) {
 	return status === 101 || status === 204 || status === 205 || status === 304;
 }
-function telegramProxyFetch(proxy) {
+function telegramProxyFetch(proxy, scope = "telegram") {
 	return async (input, init) => {
 		const route = telegramProxyRoute(requestUrl(input));
 		const request = new Request(input, init);
@@ -57,11 +58,18 @@ function telegramProxyFetch(proxy) {
 			headers: headerPairs(request.headers),
 			body: new Uint8Array(await request.arrayBuffer())
 		};
-		const reply = route.api === "file" ? await proxy.download(call) : await proxy.request(call);
-		return new Response(hasNullBody(reply.status) ? null : Buffer.from(reply.body), {
-			status: reply.status,
-			headers: reply.headers.map(([name, value]) => [name, value])
-		});
+		const send = async () => {
+			const reply = route.api === "file" ? await proxy.download(call) : await proxy.request(call);
+			return new Response(hasNullBody(reply.status) ? null : Buffer.from(reply.body), {
+				status: reply.status,
+				headers: reply.headers.map(([name, value]) => [name, value])
+			});
+		};
+		if (route.api !== "bot" || !/^\/(?:send|editMessage|deleteMessage)/u.test(route.path)) return send();
+		const type = request.headers.get("content-type") ?? "";
+		const body = type.startsWith("multipart/form-data") ? await new Response(Buffer.from(call.body), { headers: request.headers }).formData() : type.includes("application/json") ? JSON.parse(new TextDecoder().decode(call.body)) : {};
+		const chatId = body instanceof FormData ? body.get("chat_id") : body.chat_id;
+		return typeof chatId === "string" || typeof chatId === "number" ? inTelegramSendQueue(scope, String(chatId), send) : send();
 	};
 }
 export { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, TelegramProxyRouteError, telegramProxyFetch, telegramProxyRoute };

package/dist/extension/lib/telegram/send-queue.d.ts

@@ -0,0 +1,4 @@
+import type { Environment } from "../environment.js";
+export declare function telegramSendScope(environment: Environment, connection: string): string;
+/** One FIFO per bot/chat in this runtime, shared by all adapters, topics and attachment tools. */
+export declare function inTelegramSendQueue<T>(scope: string, chatId: string, run: () => Promise<T>): Promise<T>;

package/dist/extension/lib/telegram/send-queue.mjs

@@ -0,0 +1,35 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { AsyncLocalStorage } from "node:async_hooks";
+const pending = new Map();
+const held = new AsyncLocalStorage();
+function telegramSendScope(environment, connection) {
+	return JSON.stringify([environment.SEGMENTSTREAM_WORKSPACE_ID ?? "", connection]);
+}
+function inTelegramSendQueue(scope, chatId, run) {
+	const key = JSON.stringify([scope, chatId]);
+	if (held.getStore()?.get(key)?.active) return run();
+	const task = (pending.get(key) ?? Promise.resolve()).catch(() => void 0).then(() => {
+		const lease = { active: true };
+		const context = new Map(held.getStore());
+		context.set(key, lease);
+		return held.run(context, async () => {
+			try {
+				return await run();
+			} finally {
+				lease.active = false;
+			}
+		});
+	});
+	pending.set(key, task);
+	const cleanup = () => {
+		if (pending.get(key) === task) pending.delete(key);
+	};
+	task.then(cleanup, cleanup);
+	return task;
+}
+export { inTelegramSendQueue, telegramSendScope };

package/dist/extension/lib/telegram/silent.d.ts

@@ -5,9 +5,9 @@ export declare function isSilentReply(text: string): boolean;
 export declare function completionKind(message: string | null | undefined, finishReason?: string): "reply" | "tool_calls" | "empty" | "whitespace" | "silent_marker";
 type MessageCompleted = NonNullable<TelegramChannelEvents["message.completed"]>;
 /**
- * The channel's `message.completed` handler: eve's default delivery (plain text through
- * `sendMessage`, nothing for a tool-call step) unless the reply is a silence marker.
+ * The channel's final reply: formatted and split before Eve's plain-text splitter, with one
+ * queue slot for the whole reply. Tool-call steps and explicit silence markers have no delivery.
  */
-export declare function replyDelivery(observed?: ObservedMessages): MessageCompleted;
+export declare function replyDelivery(observed?: ObservedMessages, scope?: () => string): MessageCompleted;
 export declare const deliverUnlessSilent: MessageCompleted;
 export {};

package/dist/extension/lib/telegram/silent.mjs

@@ -6,7 +6,9 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import "./principal.mjs";
 import { agentMessage, observedChatKey } from "./observed.mjs";
-import { currentLocale, customerText } from "./customer-text.mjs";
+import { splitTelegramText } from "./format.mjs";
+import { inTelegramSendQueue } from "./send-queue.mjs";
+import { TelegramDeliveryError, currentLocale, customerMessage, reportTelegramError } from "./customer-text.mjs";
 import { confirmationLocale } from "./confirmation-text.mjs";
 const SILENT_MARKERS = new Set(["[silent]", "no_reply"]);
 function isSilentReply(text) {
@@ -18,11 +20,24 @@ function completionKind(message, finishReason) {
 	if (message.trim() === "") return "whitespace";
 	return isSilentReply(message) ? "silent_marker" : "reply";
 }
-function replyDelivery(observed) {
+function replyDelivery(observed, scope = () => "telegram") {
 	return async (event, channel, context) => {
 		if (completionKind(event.message, event.finishReason) !== "reply") return;
-		const text = customerText(event.message, confirmationLocale(context.session?.auth.current ?? null, currentLocale()));
-		await channel.telegram.post(text);
+		const message = customerMessage(event.message, confirmationLocale(context.session?.auth.current ?? null, currentLocale()));
+		await inTelegramSendQueue(scope(), channel.telegram.chatId, async () => {
+			const messageIds = [];
+			try {
+				for (const part of splitTelegramText(message)) {
+					const result = await channel.telegram.post(part);
+					if (!/^[1-9]\d*$/u.test(result.id)) throw new Error("Telegram did not acknowledge the reply with a message id.");
+					messageIds.push(Number(result.id));
+				}
+			} catch (error) {
+				const reference = reportTelegramError("telegram_reply_delivery_failed", error, { messageIds });
+				throw new TelegramDeliveryError(reference, error instanceof TelegramDeliveryError ? error.delivery : "unknown", messageIds);
+			}
+		});
+		const text = message.text;
 		if (observed === void 0 || channel.telegram.chatType === "private") return;
 		const principal = context.session.auth.current;
 		const sender = principal?.authenticator === "segmentstream-telegram" ? principal.subject : void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Mount a SegmentStream workspace's agent on eve: the ontology as tools, acting as the member who writes, and Telegram through the workspace's connection.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -68,6 +68,7 @@
     "jose": "^6.2.12",
     "jszip": "^3.10.2",
     "mammoth": "^1.13.0",
+    "marked": "15.0.12",
     "postal-mime": "^4.0.5",
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
   },