@segmentstream/agent 0.5.3 → 0.5.4

package/README.md

@@ -79,13 +79,14 @@ Both entry points export the same handle: `@segmentstream/agent` and
 }
 ```
 
-| Field                          | Default               | Meaning                                                                                         |
-| ------------------------------ | --------------------- | ----------------------------------------------------------------------------------------------- |
-| `channels.telegram.connection` | none                  | The Connect key whose credential is the bot token. Without `channels.telegram`, no Telegram.    |
-| `channels.telegram.policy`     | `"smart"`             | Group messages that do not address the bot: `smart` asks the decision model, `mention` observes |
-| `models.stt`                   | `"spacexai/grok-stt"` | The AI Gateway transcription model for voice messages; `false` leaves them untranscribed        |
-| `models.decision`              | `"typesafe-ai/jev"`   | The AI Gateway decision model of the inbound router                                             |
-| `ontology.connection`          | `true`                | Whether the agent reaches the ontology over MCP                                                 |
+| Field                          | Default               | Meaning                                                                                                                  |
+| ------------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `channels.telegram.connection` | none                  | The Connect key whose credential is the bot token. Without `channels.telegram`, no Telegram.                             |
+| `channels.telegram.policy`     | `"smart"`             | Group messages that do not address the bot: `smart` asks the decision model, `mention` observes                          |
+| `models.stt`                   | `"spacexai/grok-stt"` | The AI Gateway transcription model for voice messages; `false` leaves them untranscribed                                 |
+| `models.imageDescription`      | automatic             | A separate vision model for ingestion descriptions; omitted prefers native images, `false` disables description fallback |
+| `models.decision`              | `"typesafe-ai/jev"`   | The AI Gateway decision model of the inbound router                                                                      |
+| `ontology.connection`          | `true`                | Whether the agent reaches the ontology over MCP                                                                          |
 
 An unknown field or an invalid value fails the mount with `SegmentStreamAgentConfigError`, naming
 each path. `manifestOf(config)` returns the normalized configuration, defaults applied, for the
@@ -145,14 +146,28 @@ share a group chat's session never share a client.
   model, with the agent's description and the chat's recent observed messages. A message that is not
   answered joins a ring of the chat's last 30 observed messages. The next answered message carries
   the ring into its turn as context. A failed decision observes.
+  Replies to a known human or another bot, and explicit mentions of another recipient, are
+  observed before smart inference unless this bot is addressed. This also takes precedence over
+  a pending-question follow-up. Both mention entities and user-ID `text_mention` entities count;
+  quoted/code mentions do not. Smart routing receives the original body, reply author/text,
+  tagged users and whether this bot was tagged. Decision events retain a short routing audit note
+  alongside the reason code; this is an observable summary, not model chain-of-thought.
 - **Voice.** Voice messages, audio files and video notes are downloaded through the connection and
-  transcribed with `models.stt` through AI Gateway. The transcript becomes the message, with a note
-  such as `[voice message, 12 s]` in context. A file over Telegram's 20 MB download limit, or a
-  failed transcription, reaches the agent as a note saying so.
+  transcribed with `models.stt` through AI Gateway before routing, including observations under
+  `mention`. The transcript becomes the message, with a note such as `[voice message, 12 s]` in
+  context. `stt: false` skips download and transcription. Transcription accepts at most 20 MiB
+  and ten minutes of declared duration, with a 60-second inference timeout. A skipped or failed
+  transcription reaches the agent as a note. Originals are not stored as ontology attachments.
+  Eve 0.76.3 only hydrates inbound images and PDFs; it does **not** deliver native audio bytes to
+  the chat model. Even an audio-capable chat model therefore uses the configured STT fallback,
+  with an explicit host limitation note. Native audio requires a compatible Eve host change.
 - **Attachments.** Photos and documents up to 20 MB stream through the connection proxy (its
   framed responses are not bound by the 2 MiB buffered limit) and are stored, before the turn,
   as the member's temporary attachments in the ontology's file storage
-  (`POST /api/ontology/agent/attachments`), for this chat, for 24 hours. The turn's file parts
+  (`POST /api/ontology/agent/attachments`), for this chat, for 24 hours.
+  Observed group uploads are stored too, after participant registration, without starting a turn
+  or sending a typing indication. The next reply receives their references; attachment tools can
+  also list the stored files after a cold start. The turn's file parts
   point at the stored copies, which eve reads through the channel's `fetchFile` as the turn's
   session, which then owns them, and an `<attachments>` block names each attachment's id. A file
   that is too large or could not be stored becomes a note. The `segmentstream__attachments_*`
@@ -195,12 +210,69 @@ share a group chat's session never share a client.
   production, 404 without `channels.telegram`, 401 for a missing or invalid token and 400 for a
   body that does not match, including a request over 4000 characters.
 - **Silence.** When the model answers a routed message with exactly `[SILENT]` (or `NO_REPLY`), in
-  any case, nothing is sent to the chat. The turn stays in the session.
+  any case, nothing is sent to the chat. Empty and whitespace-only final text also send nothing.
+  The turn stays in the session. Archive decisions distinguish silence markers, empty text and
+  whitespace, retaining finish reason and character count without logging raw output. Model reply
+  decisions do not prove transport delivery; completed outbound events carry that evidence.
 
 The observed ring and chat-report caches live in process memory. On a cold start, the adapter
 restores recent conversation context from the platform archive and reports its chats afresh.
 The archive survives independently of eve session state and these caches.
 
+Text and captions retain their Telegram entity annotations for addressing. Rich-message blocks
+are projected to plain text before capture and dispatch, bounded to 16,384 UTF-16 code units,
+2048 traversal steps and 24 nested levels. The archive records content shape and truncation without retaining
+raw webhook payloads. Edits remain separate audit events, but replace the earlier message in
+observed/restored model context. An edit alone never starts an agent turn. Entity offsets cannot
+reconstruct a missing body; unsupported empty content is recorded with shape diagnostics.
+
+### Image context and capabilities
+
+Before handling media, the adapter reads the selected model's declared input modalities from
+AI Gateway's public model metadata. Existing sessions use the model recorded in their latest
+available `step.started` event, rather than reselecting by the current speaker's roles. A new
+session uses `models.chat` with the normal role and preview rules. An inline model choice in
+`agent.ts` cannot be inspected before its first session step; capabilities then stay unknown.
+
+| Main chat input    | `models.imageDescription` | Ingestion and later context                                               |
+| ------------------ | ------------------------- | ------------------------------------------------------------------------- |
+| Images supported   | omitted or `false`        | Store the original and retain native file references; no description call |
+| Any capability     | a model id                | Store the original and describe with that separate model before routing   |
+| Images unsupported | omitted                   | Describe with `google/gemini-2.5-flash-lite` before routing               |
+| Images unsupported | `false`                   | Store the original and record that analysis is disabled                   |
+| Unknown            | omitted or `false`        | Store the original and record that analysis is unavailable                |
+
+Descriptions cover JPEG, PNG, WebP and GIF, at most one per Telegram message, 5 MiB of input,
+256 output tokens, 512 retained characters, and a 15-second inference timeout. Albums are
+multiple Telegram messages and can incur multiple calls. These ingestion calls are separate
+from the chat model's session spending limit. The descriptor treats image text as untrusted
+evidence. Failure, unsupported format and limit notes retain the original attachment reference.
+Metadata lookups have a five-second timeout, a five-minute success cache and a 30-second failure
+cache, with at most 128 model entries. A lookup failure never asserts that the model saw pixels.
+
+Eve's native image input limit is 3 MiB per image. On the next reply, the adapter also appends
+eligible observed images as file parts, up to five images and 3 MiB total after accounting for
+current images. It creates attachment URLs for the **current** requester, and storage checks that
+member's access again. Expired or omitted images get notes. A text-only reply receives generated
+descriptions and references, never hidden image bytes. Other formats remain attachment-tool inputs.
+
+The process-local ring retains 30 observations per chat/topic, with separate budgets of 1000
+UTF-16 code units of text and 2000 of media notes per observation, plus at most five image
+references. The recent routing window also retains 30 entries. A process retains at most 500
+chats, evicting the chat least recently written. Reading does not refresh its position. A reply
+drains the observation backlog; an idle reset clears both windows; daily compaction leaves the
+ring intact. Image bytes are not kept in this cache.
+
+Archive restoration can recover raw text/captions after restarts and compaction: the webhook
+warms an empty ring from up to 30 inbound events, and each turn refreshes a separate bounded
+archive transcript. The latter reads at most 100 events, 4000 text characters and ten raw
+attachment references per event, within 30,000 serialized characters overall. Generated
+transcripts/descriptions and native-image ring references are currently **not** archived.
+They can be lost on restart or eviction before the next reply; the originals of stored images
+remain discoverable with attachment tools until expiry. Already dispatched native images follow
+Eve's sandbox/session history and may be omitted by compaction. Durable enriched media context
+and native audio are follow-up work, not guarantees of this adapter.
+
 The webhook subscribes to `message`, `edited_message`, `callback_query`, `my_chat_member`
 and `chat_member`. A bot join reports the group immediately, including when the inviter is
 unpaired; membership updates do not start turns. Report tasks participate in the wrapper's

package/dist/extension/config.d.ts

@@ -14,6 +14,7 @@ export declare const TELEGRAM_POLICIES: readonly ["mention", "smart"];
 export type TelegramPolicy = (typeof TELEGRAM_POLICIES)[number];
 /** The speech-to-text model voice messages are transcribed with, in the AI Gateway catalog. */
 export declare const DEFAULT_STT_MODEL = "spacexai/grok-stt";
+export declare const DEFAULT_IMAGE_DESCRIPTION_MODEL = "google/gemini-2.5-flash-lite";
 /** The decision model the inbound router asks; eve's `decide` default. */
 export declare const DEFAULT_DECISION_MODEL = "typesafe-ai/jev";
 /**
@@ -42,6 +43,8 @@ export interface SegmentStreamAgentConfigInput {
         };
         /** A Gateway transcription model, or `false` to leave voice messages untranscribed. */
         readonly stt?: string | boolean;
+        /** Separate vision model, or false to disable fallback descriptions; omitted prefers native input. */
+        readonly imageDescription?: string | boolean;
         /** The Gateway decision model of the inbound router. */
         readonly decision?: string;
     };
@@ -102,6 +105,7 @@ export interface SegmentStreamAgentConfig {
         /** `null` when `agent.ts` passes the choice to `segmentstream.model()` itself. */
         readonly chat: ChatModelChoice | null;
         readonly stt: string | false;
+        readonly imageDescription: string | false | null;
         readonly decision: string;
     };
     readonly ontology: {

package/dist/extension/config.mjs

@@ -7,6 +7,7 @@ __eveCreateRequire(import.meta.url);
 const CONNECTION_KEY = /^[a-z][a-z0-9_]{0,63}$/;
 const TELEGRAM_POLICIES = ["mention", "smart"];
 const DEFAULT_STT_MODEL = "spacexai/grok-stt";
+const DEFAULT_IMAGE_DESCRIPTION_MODEL = "google/gemini-2.5-flash-lite";
 const DEFAULT_DECISION_MODEL = "typesafe-ai/jev";
 const SESSION_SCOPES = ["chat", "thread"];
 var SegmentStreamAgentConfigError = class extends Error {
@@ -202,7 +203,8 @@ function validateConfig(input) {
 		allowed: [
 			"chat",
 			"stt",
-			"decision"
+			"decision",
+			"imageDescription"
 		],
 		issues
 	});
@@ -226,6 +228,12 @@ function validateConfig(input) {
 		path: ["models", "decision"],
 		issues
 	});
+	const imageDescription = models?.imageDescription === void 0 ? null : models.imageDescription === false ? false : modelId({
+		value: models.imageDescription,
+		fallback: DEFAULT_IMAGE_DESCRIPTION_MODEL,
+		path: ["models", "imageDescription"],
+		issues
+	});
 	const connection = ontology?.connection ?? true;
 	const sessions = sessionSettings(root?.sessions, issues);
 	if (typeof connection !== "boolean") issues.push({
@@ -238,7 +246,8 @@ function validateConfig(input) {
 		models: {
 			chat,
 			stt,
-			decision
+			decision,
+			imageDescription
 		},
 		ontology: { connection: connection === true },
 		sessions
@@ -255,4 +264,4 @@ function manifestOf(config) {
 	if (validation.issues !== void 0) throw new SegmentStreamAgentConfigError(validation.issues);
 	return validation.value;
 }
-export { DEFAULT_DECISION_MODEL, DEFAULT_STT_MODEL, SESSION_SCOPES, SegmentStreamAgentConfigError, TELEGRAM_POLICIES, configSchema, manifestOf, validateConfig };
+export { DEFAULT_DECISION_MODEL, DEFAULT_IMAGE_DESCRIPTION_MODEL, DEFAULT_STT_MODEL, SESSION_SCOPES, SegmentStreamAgentConfigError, TELEGRAM_POLICIES, configSchema, manifestOf, validateConfig };

package/dist/extension/lib/conversation-runtime.mjs

@@ -7,21 +7,25 @@ __eveCreateRequire(import.meta.url);
 import { memberIdOf } from "./telegram/principal.mjs";
 import { conversationEvent, conversations, summarizeArguments } from "./conversations.mjs";
 import { parseAddress } from "./telegram/sessions.mjs";
-import { isSilentReply } from "./telegram/silent.mjs";
+import { completionKind } from "./telegram/silent.mjs";
 function conversationCoordinates(context) {
 	const principal = context.session.auth.current;
 	const telegram = principal?.authenticator === "segmentstream-telegram" || context.channel.kind?.includes("telegram");
 	const address = context.channel.continuationToken;
 	const attributes = principal?.attributes;
-	const chatId = telegram && address ? parseAddress(address).chatId : typeof attributes?.chatId === "string" ? attributes.chatId : address;
+	const fields = address?.split(":");
+	const localAddress = telegram && fields?.length === 4 ? fields.slice(1).join(":") : address;
+	const parsed = telegram && localAddress !== void 0 && /^-?\d+:\d*:\d*$/u.test(localAddress) ? parseAddress(localAddress) : void 0;
+	const attributeChatId = typeof attributes?.chatId === "string" && (!telegram || /^-?\d+$/u.test(attributes.chatId)) ? attributes.chatId : void 0;
+	const chatId = telegram ? parsed?.chatId ?? attributeChatId : attributeChatId !== void 0 ? attributeChatId : address;
 	if (!chatId) return;
 	const memberId = memberIdOf(principal);
 	const chatType = attributes?.chatType;
 	return {
 		provider: telegram ? "telegram" : context.channel.kind ?? "eve",
 		chatId,
-		chatType: chatType === "group" || chatType === "supergroup" ? "group" : chatType === "channel" ? "channel" : "private",
-		threadId: telegram && address ? parseAddress(address).messageThreadId || null : null,
+		chatType: chatType === "group" || chatType === "supergroup" || chatType === void 0 && telegram && chatId.startsWith("-") ? "group" : chatType === "channel" ? "channel" : "private",
+		threadId: !telegram ? null : parsed !== void 0 ? parsed.messageThreadId || null : typeof attributes?.messageThreadId === "string" ? attributes.messageThreadId : null,
 		participantIds: memberId === void 0 ? [] : [memberId],
 		senderId: principal?.subject ?? null
 	};
@@ -70,13 +74,21 @@ function conversationRecorder(archive = conversations()) {
 			status: event.type === "task.started" ? "requested" : event.data.status === "cancelled" ? "cancelled" : event.data.status === "failed" ? "failed" : "completed"
 		}));
 		else if (event.type === "message.completed" && event.data.finishReason !== "tool-calls") {
-			const silent = !event.data.message || isSilentReply(event.data.message);
+			const kind = completionKind(event.data.message, event.data.finishReason);
+			const silent = kind !== "reply";
+			const note = kind === "silent_marker" ? "Model returned an explicit silence marker; no message delivery." : kind === "empty" ? "Model completed without final text; no message delivery." : kind === "whitespace" ? "Model returned only whitespace; no message delivery." : "Model produced a reply; transport delivery is recorded separately.";
 			await archive.append(conversationEvent({
 				...base,
 				eventId,
 				kind: "decision",
 				decision: silent ? "silent" : "reply",
-				reason: silent ? "model_silent_or_empty_output" : "model_reply"
+				reason: kind === "reply" ? "model_reply" : `model_${kind}_output`,
+				text: note,
+				argsSummary: JSON.stringify({
+					outputKind: kind,
+					outputCharacters: event.data.message?.length ?? 0,
+					finishReason: event.data.finishReason
+				})
 			}));
 			if (coordinates.provider !== "telegram" && !silent) await archive.append(conversationEvent({
 				...base,

package/dist/extension/lib/conversations.mjs

@@ -9,7 +9,7 @@ import { runtimeToken } from "./runtime-token.mjs";
 function collapseConversationEvents(events) {
 	const latest = new Map();
 	for (const event of events) {
-		const key = event.kind === "outbound" && /^telegram:(send|edit):/u.test(event.eventId) ? event.eventId.replace(/:result$/u, "") : event.eventId;
+		const key = event.kind === "inbound" && event.provider === "telegram" && event.messageId !== null ? `telegram:${event.chatId}:${event.messageId}:message` : event.kind === "outbound" && /^telegram:(send|edit):/u.test(event.eventId) ? event.eventId.replace(/:result$/u, "") : event.eventId;
 		const previous = latest.get(key);
 		if (previous === void 0 || (/^\d+$/u.test(event.sequence) && /^\d+$/u.test(previous.sequence) ? BigInt(event.sequence) > BigInt(previous.sequence) : event.storedAt > previous.storedAt)) latest.set(key, {
 			...event,

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

@@ -1,10 +1,12 @@
 import { type TelegramChannel } from "eve/channels/telegram";
-import type { SessionSettings, TelegramSettings } from "../../config.js";
+import type { ChatModelChoice, SessionSettings, TelegramSettings } from "../../config.js";
 import { type AgentAttachments } from "../attachments.js";
 import { type Environment } from "../environment.js";
 import { type Conversations } from "../conversations.js";
 import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 import { type RuntimeToken } from "../runtime-token.js";
+import { type ImageDescriber } from "./images.js";
+import { type CapabilityLookup } from "./media-policy.js";
 import { type ObservedMessages } from "./observed.js";
 import { type DecideFunction } from "./router.js";
 import { type HistoryReader } from "./sessions.js";
@@ -20,6 +22,8 @@ export interface TelegramAdapterOptions {
     readonly models: () => {
         readonly stt: string | false;
         readonly decision: string;
+        readonly chat?: ChatModelChoice | null;
+        readonly imageDescription?: string | false | null;
     };
     /** The mounted `sessions`. */
     readonly sessions: () => SessionSettings;
@@ -29,6 +33,8 @@ export interface TelegramAdapterOptions {
     /** For the proxy and the ontology service; tests pass a fake. */
     readonly fetch?: typeof fetch;
     readonly transcribe?: Transcriber;
+    readonly describeImage?: ImageDescriber;
+    readonly modelCapabilities?: CapabilityLookup;
     readonly observed?: ObservedMessages;
     /** Verifies callers of the messages route; tests pass one on a local key set. */
     readonly verify?: RuntimeTokenVerifier;

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

@@ -5,7 +5,8 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
-import { conversationLanguage } from "./principal.mjs";
+import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
+import { chooseModel } from "../../model.mjs";
 import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
 import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
@@ -20,6 +21,8 @@ import { botIdentityCache } from "./bot.mjs";
 import { confirmationLocale, confirmationRenderer } from "./confirmation-text.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
 import { handleConfirmationCallback, telegramConfirmationEvents } from "./confirmations.mjs";
+import { gatewayImageDescriber } from "./images.mjs";
+import { gatewayMediaCapabilities, planMedia } from "./media-policy.mjs";
 import { agentChats } from "./chats.mjs";
 import { decisionRouter } from "./router.mjs";
 import { replyDelivery } from "./silent.mjs";
@@ -40,7 +43,7 @@ const eveHistory = async (sessionId) => {
 	})) events.push({
 		type: event.type,
 		meta: { at: event.meta.at },
-		...event.type === "message.completed" ? { data: {
+		...event.type === "step.started" ? { data: { modelId: event.data.modelId } } : event.type === "message.completed" ? { data: {
 			message: event.data.message,
 			finishReason: event.data.finishReason
 		} } : {}
@@ -63,6 +66,7 @@ function segmentstreamTelegram(options) {
 	const observed = options.observed ?? observedMessages();
 	const readHistory = options.history ?? eveHistory;
 	const readInteractions = options.history ?? eveInteractions;
+	const capabilities = options.modelCapabilities ?? gatewayMediaCapabilities(options.fetch);
 	const archive = options.conversations ?? conversations({
 		environment,
 		token,
@@ -147,6 +151,37 @@ function segmentstreamTelegram(options) {
 						sessions: options.sessions,
 						sessionPolicy: policy,
 						sttModel: options.models().stt,
+						describeImage: options.describeImage ?? gatewayImageDescriber,
+						mediaPlan: async (member, sessionId) => {
+							let selected;
+							if (sessionId !== void 0) try {
+								for (const event of await readHistory(sessionId)) {
+									const data = event.data;
+									if (event.type === "step.started" && typeof data?.modelId === "string") selected = data.modelId;
+								}
+							} catch (error) {
+								reportTelegramError("media_session_model_lookup_failed", error, { sessionId });
+							}
+							else {
+								const choice = options.models().chat;
+								if (choice) selected = chooseModel({
+									choice,
+									principal: telegramPrincipal({
+										message: {
+											...message,
+											from: message.from
+										},
+										member
+									}),
+									environment
+								});
+							}
+							return planMedia(selected === void 0 ? {
+								known: false,
+								images: false,
+								audio: false
+							} : await capabilities(selected), options.models().imageDescription ?? null);
+						},
 						identities: conversationIdentities(pairing()),
 						bot,
 						decide: captureRouteDecider(decisionRouter({

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

@@ -0,0 +1,26 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import type { BotIdentity } from "./router.js";
+type TargetKind = "bot" | "human" | "other_bot" | "unknown";
+interface Recipient {
+    readonly kind: TargetKind;
+    readonly id?: string;
+    readonly username?: string;
+    readonly name?: string;
+}
+export interface MessageAudience {
+    readonly originalText: string;
+    readonly botTagged: boolean;
+    readonly mentions: ReadonlyArray<Recipient & {
+        readonly type: "mention" | "text_mention";
+        readonly text: string;
+    }>;
+    readonly replyTo: (Recipient & {
+        readonly messageId: string;
+        readonly text: string;
+    }) | null;
+}
+/** Current-message entities only; mentions inside a quoted/code range are not addressees. */
+export declare function messageAudience(message: TelegramMessage, bot: BotIdentity | undefined): MessageAudience;
+/** A known human reply or an explicit other recipient takes precedence over smart follow-ups. */
+export declare function otherRecipient(audience: MessageAudience | undefined): string | undefined;
+export {};

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

@@ -0,0 +1,80 @@
+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 { messageContent, telegramRecord } from "./content.mjs";
+function recipient(user, bot) {
+	const id = typeof user.id === "string" || typeof user.id === "number" ? String(user.id) : void 0;
+	const username = typeof user.username === "string" ? user.username : void 0;
+	return {
+		kind: bot !== void 0 && (id === bot.id || username !== void 0 && bot.username !== void 0 && username.toLowerCase() === bot.username.toLowerCase()) ? "bot" : user.is_bot === false ? "human" : user.is_bot === true && bot !== void 0 ? "other_bot" : "unknown",
+		...id === void 0 ? {} : { id },
+		...username === void 0 ? {} : { username },
+		...typeof user.first_name === "string" ? { name: user.first_name } : {}
+	};
+}
+function messageAudience(message, bot) {
+	const content = messageContent(message.raw);
+	const text = content.source === "none" ? message.text || message.caption : content.text;
+	const mentions = [];
+	const quoted = (offset) => content.entities.some((entity) => [
+		"code",
+		"pre",
+		"blockquote",
+		"expandable_blockquote"
+	].includes(entity.type) && offset >= entity.offset && offset < entity.offset + entity.length);
+	for (const entity of content.entities) {
+		if (entity.type !== "mention" && entity.type !== "text_mention" || quoted(entity.offset)) continue;
+		const label = text.slice(entity.offset, entity.offset + entity.length);
+		if (entity.type === "text_mention") mentions.push({
+			...recipient(entity.user ?? {}, bot),
+			type: "text_mention",
+			text: label
+		});
+		else {
+			const username = entity.username ?? /^@([A-Za-z0-9_]+)$/u.exec(label)?.[1];
+			if (username !== void 0) mentions.push({
+				...recipient({ username }, bot),
+				type: "mention",
+				text: label
+			});
+		}
+	}
+	for (const match of text.matchAll(/(?<![A-Za-z0-9_@])@([A-Za-z0-9_]{1,32})(?![A-Za-z0-9_])/gu)) {
+		if (quoted(match.index)) continue;
+		const username = match[1];
+		if (mentions.some((item) => item.username?.toLowerCase() === username.toLowerCase())) continue;
+		mentions.push({
+			...recipient({ username }, bot),
+			type: "mention",
+			text: match[0]
+		});
+	}
+	const rawReply = telegramRecord(message.raw.reply_to_message);
+	const author = message.replyToMessage?.from;
+	const replyId = message.replyToMessage?.messageId ?? rawReply.message_id;
+	const replyTo = replyId === void 0 ? null : {
+		...recipient(Object.keys(telegramRecord(rawReply.from)).length > 0 ? telegramRecord(rawReply.from) : {
+			id: author?.id,
+			username: author?.username,
+			is_bot: author?.isBot,
+			first_name: author?.firstName
+		}, bot),
+		messageId: String(replyId),
+		text: messageContent(rawReply).text.slice(0, 1e3)
+	};
+	return {
+		originalText: text,
+		mentions: mentions.slice(0, 50),
+		botTagged: mentions.some((item) => item.kind === "bot"),
+		replyTo
+	};
+}
+function otherRecipient(audience) {
+	if (audience === void 0 || audience.botTagged || audience.replyTo?.kind === "bot") return;
+	if (audience.replyTo?.kind === "human" || audience.replyTo?.kind === "other_bot") return "Reply targets another person or bot; this bot was not addressed.";
+	if (audience.mentions.some((item) => item.kind !== "bot")) return "Message tags another recipient; this bot was not addressed.";
+}
+export { messageAudience, otherRecipient };

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

@@ -0,0 +1,29 @@
+/** Telegram entities annotate UTF-16 text ranges; they never contain the missing message body. */
+export interface ContentEntity {
+    readonly type: string;
+    readonly offset: number;
+    readonly length: number;
+    readonly user?: Readonly<Record<string, unknown>>;
+    readonly username?: string;
+}
+export interface MessageContent {
+    readonly text: string;
+    readonly entities: ReadonlyArray<ContentEntity>;
+    readonly source: "text" | "caption" | "rich_message" | "none";
+    readonly truncated: boolean;
+}
+export declare function telegramRecord(value: unknown): Readonly<Record<string, unknown>>;
+/** Text/caption stay verbatim, including forwarded messages; rich bodies need flattening. */
+export declare function messageContent(raw: Readonly<Record<string, unknown>>): MessageContent;
+/** Only shape/size diagnostics: do not retain/log raw webhook bodies, URLs or credential values. */
+export declare function contentShape(raw: Readonly<Record<string, unknown>>, content?: MessageContent): {
+    contentSource: "text" | "caption" | "rich_message" | "none";
+    textType: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+    captionType: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+    hasRichMessage: boolean;
+    entityCount: number;
+    captionEntityCount: number;
+    textLength: number;
+    truncated: boolean;
+    forwarded: boolean;
+};