@segmentstream/agent 0.2.0 → 0.3.0

package/dist/extension/lib/attachment-tools.d.ts

@@ -1,5 +1,6 @@
 import type { SessionAuthContext } from "eve/context";
 import { type AgentAttachments, type Attachment, type AttachmentOwner } from "./attachments.js";
+import { type DateOrder } from "./attachment-tables.js";
 import { type Environment } from "./environment.js";
 import { type RuntimeToken } from "./runtime-token.js";
 /**
@@ -7,7 +8,7 @@ import { type RuntimeToken } from "./runtime-token.js";
  * the member and chat on the session's principal, which the channel set from the pairing, and the
  * session's own id. A tool's arguments name only the attachment and what to do with it.
  */
-/** The longest text `attachments_read` returns; the rest is cut and marked as truncated. */
+/** Maximum characters in a read/query response; remaining data is available by continuation. */
 export declare const MAXIMUM_TEXT_CHARACTERS = 50000;
 /** The largest file `attachments_read` hands the model inline. */
 export declare const MAXIMUM_INLINE_BYTES: number;
@@ -33,22 +34,52 @@ export declare function attachmentForModel(attachment: Attachment): {
     state: string;
     expires_at: string;
 };
+export interface ReadOptions {
+    readonly sheet?: string;
+    readonly offset?: number;
+    readonly limit?: number;
+    readonly character_offset?: number;
+    readonly header_row?: number;
+    readonly date_order?: DateOrder;
+}
 export type ReadOutput = {
     readonly attachment: ReturnType<typeof attachmentForModel>;
     readonly kind: "text";
+    readonly format: string;
     readonly text: string;
     readonly truncated: boolean;
+    readonly pagination: {
+        readonly unit: "characters" | "rows";
+        readonly offset: number;
+        readonly limit: number;
+        readonly total: number;
+        readonly total_pages: number;
+        readonly next_offset: number | null;
+        readonly next_character_offset?: number;
+    };
+    readonly sheet?: string;
+    readonly sheets?: ReadonlyArray<{
+        readonly name: string;
+        readonly total_rows: number;
+    }>;
+    readonly columns?: unknown;
+    readonly warnings?: ReadonlyArray<string>;
 } | {
     readonly attachment: ReturnType<typeof attachmentForModel>;
     readonly kind: "file";
+    readonly media_type: string;
     readonly data: string;
 } | {
     readonly attachment: ReturnType<typeof attachmentForModel>;
     readonly kind: "unreadable";
     readonly note: string;
 };
-/** What `attachments_read` answers for a file: its text, the file itself, or why neither. */
-export declare function readOutput(attachment: Attachment, bytes: Uint8Array): ReadOutput;
+export declare function pageInteger(value: unknown, fallback: number, maximum?: number): number;
+export declare function headerArgument(value: unknown): number | undefined;
+/** Keep envelopes and structured query results inside the same response budget as file text. */
+export declare function boundedResultPage<T>(items: readonly T[], offset: number, limit: number, envelope: unknown): T[];
+/** Reads never discard the remainder. Parsers process the entire file before selecting a page. */
+export declare function readOutput(attachment: Attachment, bytes: Uint8Array, options?: ReadOptions): Promise<ReadOutput>;
 /** A required string argument. */
 export declare function stringArgument(input: Readonly<Record<string, unknown>>, name: string): string;
 /** An optional string argument. */

package/dist/extension/lib/attachment-tools.mjs

@@ -9,22 +9,10 @@ import { memberIdOf } from "./telegram/principal.mjs";
 import { runtimeToken } from "./runtime-token.mjs";
 import { agentAttachments } from "./attachments.mjs";
 import { telegramConversation } from "./telegram/files.mjs";
+import { detectFile, documentText } from "./attachment-formats.mjs";
+import { readSheets, typedTable } from "./attachment-tables.mjs";
 const MAXIMUM_TEXT_CHARACTERS = 5e4;
 const MAXIMUM_INLINE_BYTES = 5242880;
-const INLINE_TYPES = new Set([
-	"application/pdf",
-	"image/png",
-	"image/jpeg",
-	"image/webp",
-	"image/gif"
-]);
-function isText(contentType) {
-	return contentType.startsWith("text/") || [
-		"application/json",
-		"application/xml",
-		"application/csv"
-	].includes(contentType);
-}
 var AttachmentOwnerError = class extends Error {
 	name = "AttachmentOwnerError";
 };
@@ -58,27 +46,148 @@ function attachmentForModel(attachment) {
 		...attachment.promotion === null ? {} : { promotion: attachment.promotion }
 	};
 }
-function readOutput(attachment, bytes) {
+function pageInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximum) throw new TypeError(`Pagination values must be integers from 0 to ${maximum}.`);
+	return value;
+}
+function headerArgument(value) {
+	if (value === void 0) return;
+	if (value === -1) return -1;
+	return pageInteger(value, 0);
+}
+function boundedResultPage(items, offset, limit, envelope) {
+	const budget = MAXIMUM_TEXT_CHARACTERS - JSON.stringify(envelope).length - 2e3;
+	const page = [];
+	let size = 2;
+	for (const item of items.slice(offset, offset + limit)) {
+		const length = JSON.stringify(item).length + 1;
+		if (size + length > budget) {
+			if (page.length === 0) throw new Error("One result exceeds the response budget. Use attachments_read and its character continuation.");
+			break;
+		}
+		page.push(item);
+		size += length;
+	}
+	return page;
+}
+async function readOutput(attachment, bytes, options = {}) {
 	const described = attachmentForModel(attachment);
-	if (isText(attachment.contentType)) {
-		const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+	const offset = pageInteger(options.offset, 0);
+	const requestedLimit = pageInteger(options.limit, MAXIMUM_TEXT_CHARACTERS, MAXIMUM_TEXT_CHARACTERS);
+	if (requestedLimit === 0) throw new TypeError("limit must be greater than zero.");
+	try {
+		const file = await detectFile(attachment, bytes);
+		if (file.format === "inline" && bytes.byteLength <= 5242880) return {
+			attachment: described,
+			kind: "file",
+			media_type: file.mediaType,
+			data: Buffer.from(bytes).toString("base64")
+		};
+		if (file.format === "inline" || file.format === "opaque" || file.format === "doc") return {
+			attachment: described,
+			kind: "unreadable",
+			note: file.format === "inline" ? "The file exceeds the inline display limit; it can still be promoted by id." : file.format === "doc" ? "Legacy binary Word document: text extraction is unavailable. Metadata is shown; the original can be promoted." : "No text extractor for this format. Metadata is shown; the original can be promoted by id."
+		};
+		if (file.format === "table") {
+			const table = typedTable(await readSheets(attachment, bytes), options);
+			const limit = pageInteger(options.limit, 100, MAXIMUM_TEXT_CHARACTERS);
+			const characterOffset = pageInteger(options.character_offset, 0);
+			const envelope = {
+				attachment: described,
+				columns: table.columns,
+				warnings: table.warnings,
+				sheets: table.sheets
+			};
+			const budget = Math.floor((MAXIMUM_TEXT_CHARACTERS - JSON.stringify(envelope).length - 2e3) / 6);
+			const csv = (values) => values.map((value) => `"${(value ?? "").replace(/"/g, "\"\"")}"`).join(",");
+			const heading = `Sheet: ${table.sheet}\n${csv(table.columns.map((column) => column.name))}\n`;
+			const lines = table.rows.map((row) => csv(table.columns.map((column) => row[column.name])) + "\n");
+			if (heading.length >= budget) throw new Error("Table headers exceed the response budget.");
+			const pageAt = (rowOffset, charOffset) => {
+				let text = heading;
+				let cursor = Math.min(rowOffset, lines.length);
+				let nextCharacter = 0;
+				for (; cursor < Math.min(lines.length, rowOffset + limit); cursor++) {
+					const line = lines[cursor];
+					const start = cursor === rowOffset ? charOffset : 0;
+					const remaining = line.slice(start);
+					if (start >= line.length) throw new TypeError("character_offset exceeds this row's text length.");
+					if (text.length + remaining.length > budget) {
+						if (cursor === rowOffset) {
+							const available = budget - text.length;
+							text += remaining.slice(0, available);
+							nextCharacter = start + available;
+						}
+						break;
+					}
+					text += remaining;
+				}
+				return {
+					text,
+					next: cursor < lines.length ? cursor : null,
+					nextCharacter
+				};
+			};
+			const { text, next, nextCharacter } = pageAt(offset, characterOffset);
+			let totalPages = 0;
+			let nextRow = 0;
+			let nextChar = 0;
+			while (nextRow !== null && lines.length > 0) {
+				const page = pageAt(nextRow, nextChar);
+				totalPages++;
+				nextRow = page.next;
+				nextChar = page.nextCharacter;
+			}
+			return {
+				...envelope,
+				kind: "text",
+				format: "table",
+				sheet: table.sheet,
+				text,
+				truncated: next !== null,
+				pagination: {
+					unit: "rows",
+					offset,
+					limit,
+					total: table.rows.length,
+					total_pages: totalPages,
+					next_offset: next,
+					...nextCharacter === 0 ? {} : { next_character_offset: nextCharacter }
+				}
+			};
+		}
+		const fullText = await documentText(file, bytes);
+		const budget = Math.floor((MAXIMUM_TEXT_CHARACTERS - JSON.stringify(described).length - 2e3) / 6);
+		const limit = Math.min(requestedLimit, budget);
+		const text = fullText.slice(offset, offset + limit);
+		const next = offset + text.length < fullText.length ? offset + text.length : null;
 		return {
 			attachment: described,
 			kind: "text",
-			text: text.slice(0, MAXIMUM_TEXT_CHARACTERS),
-			truncated: text.length > MAXIMUM_TEXT_CHARACTERS
+			format: file.format,
+			text,
+			truncated: next !== null,
+			pagination: {
+				unit: "characters",
+				offset,
+				limit,
+				total: fullText.length,
+				total_pages: Math.ceil(fullText.length / limit),
+				next_offset: next
+			}
+		};
+	} catch (error) {
+		console.error("[segmentstream] attachment parsing failed", {
+			id: attachment.id,
+			error
+		});
+		return {
+			attachment: described,
+			kind: "unreadable",
+			note: "The file could not be parsed (invalid, encrypted, or over the expanded parsing limit). The original can still be promoted."
 		};
 	}
-	if (INLINE_TYPES.has(attachment.contentType) && bytes.byteLength <= 5242880) return {
-		attachment: described,
-		kind: "file",
-		data: Buffer.from(bytes).toString("base64")
-	};
-	return {
-		attachment: described,
-		kind: "unreadable",
-		note: INLINE_TYPES.has(attachment.contentType) ? "The file is too large to show again; it was attached to the message it came with." : `A ${attachment.contentType} file cannot be shown; promote or discard it by its id.`
-	};
 }
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -107,4 +216,4 @@ const ID_INPUT = {
 	required: ["id"],
 	additionalProperties: false
 };
-export { AttachmentOwnerError, ID_INPUT, MAXIMUM_INLINE_BYTES, MAXIMUM_TEXT_CHARACTERS, attachmentForModel, attachmentOwner, optionalObject, optionalString, readOutput, stringArgument, toolAttachments };
+export { AttachmentOwnerError, ID_INPUT, MAXIMUM_INLINE_BYTES, MAXIMUM_TEXT_CHARACTERS, attachmentForModel, attachmentOwner, boundedResultPage, headerArgument, optionalObject, optionalString, pageInteger, readOutput, stringArgument, toolAttachments };

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

@@ -14,13 +14,14 @@ import { botIdentityCache } from "./bot.mjs";
 import { agentChats } from "./chats.mjs";
 import { observedMessages } from "./observed.mjs";
 import { decisionRouter } from "./router.mjs";
+import { replyDelivery } from "./silent.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
 import { downloadTelegramFile, gatewayTranscriber } from "./voice.mjs";
 import { handleInboundMessage } from "./inbound.mjs";
 import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
 import { messagesRoute } from "./requests.mjs";
-import { deliverUnlessSilent } from "./silent.mjs";
+import { withTurnErrorLogging } from "./turn-errors.mjs";
 import { telegramWebhookVerifier } from "./webhook.mjs";
 import { telegramChannel } from "eve/channels/telegram";
 const eveHistory = async (sessionId) => {
@@ -31,7 +32,11 @@ const eveHistory = async (sessionId) => {
 		follow: false
 	})) events.push({
 		type: event.type,
-		meta: { at: event.meta.at }
+		meta: { at: event.meta.at },
+		...event.type === "message.completed" ? { data: {
+			message: event.data.message,
+			finishReason: event.data.finishReason
+		} } : {}
 	});
 	return events;
 };
@@ -39,9 +44,10 @@ function segmentstreamTelegram(options) {
 	const environment = options.environment ?? process.env;
 	const token = options.token ?? runtimeToken;
 	const observed = options.observed ?? observedMessages();
+	const readHistory = options.history ?? eveHistory;
 	const policy = sessionPolicy({
 		settings: options.sessions,
-		read: options.history ?? eveHistory
+		read: readHistory
 	});
 	const bot = botIdentityCache();
 	const proxies = new Map();
@@ -117,14 +123,16 @@ function segmentstreamTelegram(options) {
 				}),
 				attachments: attachments(),
 				observed,
+				readHistory,
 				chats,
 				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
 			}
 		}),
-		events: { "message.completed": deliverUnlessSilent }
+		events: { "message.completed": replyDelivery(observed) }
 	});
 	const adapter = channel.adapter;
 	const fetchTelegramFile = adapter?.fetchFile;
+	const turnFailed = adapter?.["turn.failed"];
 	async function fetchFile(url, context) {
 		const reference = parseAttachmentUrl(url);
 		if (reference === void 0) return fetchTelegramFile === void 0 ? null : fetchTelegramFile(url, context);
@@ -144,7 +152,8 @@ function segmentstreamTelegram(options) {
 		...channel,
 		...adapter === void 0 ? {} : { adapter: {
 			...adapter,
-			fetchFile
+			fetchFile,
+			...turnFailed === void 0 ? {} : { "turn.failed": withTurnErrorLogging(turnFailed) }
 		} },
 		routes: [...channel.routes.map((route) => gatedRoute({
 			route,

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

@@ -7,7 +7,7 @@ import { type AgentChats } from "./chats.js";
 import type { InboundRequest } from "./inbound-request.js";
 import { type ObservedMessages } from "./observed.js";
 import { type RouteDecider } from "./router.js";
-import { type SessionPolicy } from "./sessions.js";
+import { type HistoryReader, type SessionPolicy } from "./sessions.js";
 import { type Transcriber } from "./voice.js";
 /**
  * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
@@ -43,6 +43,7 @@ export interface InboundDependencies {
     /** The attachment store; without it, files reach the turn as eve's Telegram file parts. */
     readonly attachments?: AgentAttachments;
     readonly observed: ObservedMessages;
+    readonly readHistory: HistoryReader;
     readonly chats: AgentChats;
     /** The app's `/agent/connect` link for a pairing code. */
     readonly connectUrl: (code: string) => string;

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

@@ -8,7 +8,8 @@ import { telegramPrincipal } from "./principal.mjs";
 import { chatContext } from "./chats.mjs";
 import { attachmentsContext, stageFiles } from "./files.mjs";
 import { observedChatKey, observedContext } from "./observed.mjs";
-import { isAddressed, routeMessage } from "./router.mjs";
+import { addressingReason, routeMessage } from "./router.mjs";
+import { routingContext } from "./routing-context.mjs";
 import { messageAddress, scopedAddress } from "./sessions.mjs";
 import { voiceNote, voiceOf, voiceText } from "./voice.mjs";
 const UNKNOWN_PRIVATE = "Hi, I don't know you yet. Connect your Telegram account to the workspace and I'll act as you. The button works for ten minutes.";
@@ -39,6 +40,8 @@ function authorOf(user, member) {
 function observedMessage(message, text, member) {
 	return {
 		author: authorOf(message.from, member),
+		authorId: message.from.id,
+		...message.from.username === void 0 ? {} : { username: message.from.username },
 		text,
 		at: sentAt(message)
 	};
@@ -159,7 +162,7 @@ async function handleInboundMessage(input) {
 		from: message.from
 	};
 	const bot = await dependencies.bot(context.telegram);
-	const addressed = isAddressed(sent, bot);
+	const addressed = addressingReason(sent, bot);
 	const lookup = await dependencies.identities.lookup({
 		provider: "telegram",
 		externalId: sent.from.id
@@ -172,7 +175,7 @@ async function handleInboundMessage(input) {
 	}) : void 0;
 	if (report !== void 0) input.request?.waitUntil?.(report);
 	if (lookup.status !== "paired") {
-		if (addressed) await answerUnpaired({
+		if (addressed !== void 0) await answerUnpaired({
 			context,
 			message: sent,
 			lookup,
@@ -187,7 +190,7 @@ async function handleInboundMessage(input) {
 	const caption = sent.text || sent.caption;
 	const notes = [];
 	let text = caption;
-	if (voice !== void 0 && (addressed || dependencies.policy === "smart")) {
+	if (voice !== void 0 && (addressed !== void 0 || dependencies.policy === "smart")) {
 		const spoken = await voiceText({
 			voice,
 			model: dependencies.sttModel,
@@ -203,14 +206,25 @@ async function handleInboundMessage(input) {
 		...sent.messageThreadId === void 0 ? {} : { messageThreadId: sent.messageThreadId }
 	});
 	if (await routeMessage({
+		chatId: sent.chat.id,
+		memberId: lookup.member.id,
 		policy: dependencies.policy,
 		addressed,
 		decide: dependencies.decide,
-		question: async () => ({
-			agent: await input.request?.agentDescription() ?? "",
-			observed: dependencies.observed.list(chat),
-			message: observedMessage(sent, text, lookup.member)
-		})
+		question: async () => {
+			const recent = await routingContext({
+				address,
+				operations,
+				read: dependencies.readHistory,
+				remembered: dependencies.observed.recent(chat),
+				at: sentAt(sent)
+			});
+			return {
+				agent: await input.request?.agentDescription() ?? "",
+				recent,
+				message: observedMessage(sent, text, lookup.member)
+			};
+		}
 	}) === "observe") {
 		dependencies.observed.add(chat, observedMessage(sent, text === "" ? "[attachment]" : text, lookup.member));
 		return null;
@@ -223,7 +237,7 @@ async function handleInboundMessage(input) {
 			address,
 			operations,
 			...newest === void 0 ? {} : { activeAt: Date.parse(newest.at) || 0 }
-		}) === "cleared") dependencies.observed.take(chat);
+		}) === "cleared") dependencies.observed.clear(chat);
 		dependencies.sessionPolicy.delivered(address);
 	}
 	await context.telegram.startTyping();
@@ -235,6 +249,7 @@ async function handleInboundMessage(input) {
 	});
 	if (input.request !== void 0 && files.size > 0) input.request.files = files;
 	await report;
+	dependencies.observed.remember(chat, observedMessage(sent, text, lookup.member));
 	return {
 		auth: telegramPrincipal({
 			message: sent,

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

@@ -1,7 +1,7 @@
 /**
- * The bounded ring of group messages the router observed without answering. The router shows it to
- * the decision model, and a reply carries it into the turn as context, so the agent knows what the
- * chat was talking about.
+ * Bounded group conversation context for routing, and the backlog observed without answering.
+ * A reply drains only the backlog: recent member messages and the agent's own replies remain
+ * available to decide whether a later unaddressed message answers one of the agent's questions.
  *
  * eve's `defineState` would be the durable home, but it is session state and needs an active eve
  * context; an observed message has neither, because observing must not start a session. The ring
@@ -15,14 +15,40 @@ export interface ObservedMessage {
     readonly text: string;
     /** ISO time the message was sent. */
     readonly at: string;
+    /** Stable Telegram identity, independent of changes to the member's display name or roles. */
+    readonly authorId?: string;
+    readonly username?: string;
 }
+export interface MessageRecipient {
+    readonly author: string;
+    readonly id?: string;
+    readonly username?: string;
+}
+export interface AgentMessage extends ObservedMessage {
+    readonly role: "agent";
+    /** Explicit @mentions take precedence over the member whose turn produced the reply. */
+    readonly addressedTo: ReadonlyArray<MessageRecipient>;
+    readonly inReplyTo?: MessageRecipient;
+}
+export type RecentMessage = ObservedMessage | AgentMessage;
 export interface ObservedMessages {
     add(chat: string, message: ObservedMessage): void;
+    /** Records a received message that starts a turn, or a successfully delivered agent reply. */
+    remember(chat: string, message: RecentMessage): void;
     list(chat: string): ReadonlyArray<ObservedMessage>;
+    recent(chat: string): ReadonlyArray<RecentMessage>;
     /** Returns and forgets the chat's ring, once a reply has carried it into a turn. */
     take(chat: string): ReadonlyArray<ObservedMessage>;
+    /** An idle reset forgets both the backlog and the earlier conversation. */
+    clear(chat: string): void;
 }
 export declare function observedMessages(capacity?: number): ObservedMessages;
+/** Recipient metadata for an agent reply; explicit mentions are visible even in proactive turns. */
+export declare function agentMessage(input: {
+    readonly text: string;
+    readonly at: string;
+    readonly inReplyTo?: MessageRecipient;
+}): AgentMessage;
 /** The key of a chat's ring: the chat and, in a forum, the topic. */
 export declare function observedChatKey(input: {
     readonly chatId: string;

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

@@ -9,29 +9,63 @@ const MAXIMUM_CHATS = 500;
 const MAXIMUM_TEXT_LENGTH = 1e3;
 function observedMessages(capacity = 30) {
 	const chats = new Map();
+	function remember(chat, message, observe) {
+		const previous = chats.get(chat);
+		const bounded = {
+			...message,
+			text: message.text.slice(0, MAXIMUM_TEXT_LENGTH)
+		};
+		const backlog = previous?.observed ?? [];
+		chats.delete(chat);
+		chats.set(chat, {
+			observed: observe ? [...backlog, bounded].slice(-capacity) : backlog,
+			recent: [...previous?.recent ?? [], bounded].slice(-capacity)
+		});
+		if (chats.size > MAXIMUM_CHATS) {
+			const oldest = chats.keys().next();
+			if (oldest.done !== true) chats.delete(oldest.value);
+		}
+	}
 	return {
 		add(chat, message) {
-			const ring = [...chats.get(chat) ?? [], {
-				...message,
-				text: message.text.slice(0, MAXIMUM_TEXT_LENGTH)
-			}];
-			chats.delete(chat);
-			chats.set(chat, ring.slice(-capacity));
-			if (chats.size > MAXIMUM_CHATS) {
-				const oldest = chats.keys().next();
-				if (oldest.done !== true) chats.delete(oldest.value);
-			}
+			remember(chat, message, true);
+		},
+		remember(chat, message) {
+			remember(chat, message, false);
 		},
 		list(chat) {
-			return chats.get(chat) ?? [];
+			return chats.get(chat)?.observed ?? [];
+		},
+		recent(chat) {
+			return chats.get(chat)?.recent ?? [];
 		},
 		take(chat) {
-			const ring = chats.get(chat) ?? [];
+			const previous = chats.get(chat);
+			if (previous !== void 0) chats.set(chat, {
+				...previous,
+				observed: []
+			});
+			return previous?.observed ?? [];
+		},
+		clear(chat) {
 			chats.delete(chat);
-			return ring;
 		}
 	};
 }
+function agentMessage(input) {
+	const usernames = Array.from(input.text.matchAll(/(?:^|[^A-Za-z0-9_])@([A-Za-z0-9_]+)/gu), (match) => match[1] ?? "");
+	const addressedTo = usernames.length > 0 ? [...new Set(usernames)].map((username) => ({
+		author: `@${username}`,
+		username
+	})) : input.inReplyTo === void 0 ? [] : [input.inReplyTo];
+	return {
+		...input,
+		text: input.text.slice(0, MAXIMUM_TEXT_LENGTH),
+		author: "the agent",
+		role: "agent",
+		addressedTo
+	};
+}
 function observedChatKey(input) {
 	return input.messageThreadId === void 0 ? input.chatId : `${input.chatId}:${input.messageThreadId}`;
 }
@@ -44,4 +78,4 @@ function observedContext(messages) {
 		"</observed_messages>"
 	].join("\n")];
 }
-export { OBSERVED_MESSAGES, observedChatKey, observedContext, observedMessages };
+export { OBSERVED_MESSAGES, agentMessage, observedChatKey, observedContext, observedMessages };

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

@@ -1,6 +1,6 @@
 import type { TelegramMessage } from "eve/channels/telegram";
 import type { TelegramPolicy } from "../../config.js";
-import type { ObservedMessage } from "./observed.js";
+import type { ObservedMessage, RecentMessage } from "./observed.js";
 /**
  * The inbound router (`agent-design.md`, section 4): every message from a paired member is either
  * answered or observed before eve starts a turn. A private chat, a mention, a reply to the bot and
@@ -8,18 +8,22 @@ import type { ObservedMessage } from "./observed.js";
  * policy, put to one decision on the decision model.
  */
 export type Route = "observe" | "reply";
+export type AddressingReason = "private" | "mention" | "reply-to-bot" | "command";
 /** The bot, as Telegram's `getMe` describes it. Unknown when `getMe` failed. */
 export interface BotIdentity {
     readonly id: string;
     readonly username: string | undefined;
 }
+/** Why the message is for the bot without asking any model. */
+export declare function addressingReason(message: TelegramMessage, bot: BotIdentity | undefined): AddressingReason | undefined;
 /** Whether the message is for the bot without asking any model. */
 export declare function isAddressed(message: TelegramMessage, bot: BotIdentity | undefined): boolean;
 /** What the decision model sees. */
 export interface RouteQuestion {
     /** The agent's own description, so the model knows what it can be asked for. */
     readonly agent: string;
-    readonly observed: ReadonlyArray<ObservedMessage>;
+    /** Recent received messages and delivered agent replies, oldest first. */
+    readonly recent: ReadonlyArray<RecentMessage>;
     readonly message: ObservedMessage;
 }
 /** Decides whether a group message not addressed to the bot is still for it. */
@@ -51,6 +55,8 @@ export type DecideFunction = (options: {
         };
     };
 }>;
+/** An unthreaded answer minutes later may continue a question, but old questions are not hints. */
+export declare const FOLLOW_UP_WINDOW_MS: number;
 /** A {@link RouteDecider} that asks one `decide` question on the configured decision model. */
 export declare function decisionRouter(input: {
     readonly decide: DecideFunction;
@@ -61,8 +67,10 @@ export declare function decisionRouter(input: {
  * mistake in a group chat.
  */
 export declare function routeMessage(input: {
+    readonly chatId: string;
+    readonly memberId: string;
     readonly policy: TelegramPolicy;
-    readonly addressed: boolean;
+    readonly addressed: AddressingReason | undefined;
     /** Builds the question only when a decision is needed: it reads the agent's description. */
     readonly question: () => Promise<RouteQuestion>;
     readonly decide: RouteDecider;