@segmentstream/agent 0.3.1 → 0.5.0

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

@@ -9,19 +9,22 @@ import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs
 import { runtimeToken } from "../runtime-token.mjs";
 import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
 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 { captureRouteDecider, captureTelegramFetch, conversationIdentities, telegramConversationCapture } from "./conversations.mjs";
 import { runtimeTokenVerifier } from "../runtime-identity.mjs";
 import { botIdentityCache } from "./bot.mjs";
-import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
 import { confirmationEvents, handleConfirmationCallback } from "./confirmations.mjs";
 import { agentChats } from "./chats.mjs";
-import { observedMessages } from "./observed.mjs";
 import { decisionRouter } from "./router.mjs";
 import { replyDelivery } from "./silent.mjs";
 import { downloadTelegramFile, gatewayTranscriber } from "./voice.mjs";
 import { handleInboundMessage } from "./inbound.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
 import { messagesRoute } from "./requests.mjs";
+import { healthRoute } from "./health.mjs";
 import { withTurnErrorLogging } from "./turn-errors.mjs";
 import { telegramWebhookVerifier } from "./webhook.mjs";
 import { telegramChannel } from "eve/channels/telegram";
@@ -57,6 +60,11 @@ function segmentstreamTelegram(options) {
 	const observed = options.observed ?? observedMessages();
 	const readHistory = options.history ?? eveHistory;
 	const readInteractions = options.history ?? eveInteractions;
+	const archive = options.conversations ?? conversations({
+		environment,
+		token,
+		fetch: options.fetch
+	});
 	const policy = sessionPolicy({
 		settings: options.sessions,
 		read: readHistory
@@ -93,6 +101,13 @@ function segmentstreamTelegram(options) {
 		return identities;
 	}
 	const chats = agentChats({ identities: pairing });
+	const capture = telegramConversationCapture({
+		archive,
+		identities: pairing,
+		observed,
+		chats,
+		verify: telegramWebhookVerifier(() => webhookSecret(environment))
+	});
 	let store = options.attachments;
 	function attachments() {
 		store ??= agentAttachments({
@@ -106,7 +121,7 @@ function segmentstreamTelegram(options) {
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
 			fileBaseUrl: TELEGRAM_PROXY_ORIGIN,
-			fetch: (input, init) => telegramProxyFetch(proxy())(input, init)
+			fetch: (input, init) => captureTelegramFetch(telegramProxyFetch(proxy()), archive, pairing)(input, init)
 		},
 		credentials: {
 			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
@@ -122,12 +137,12 @@ function segmentstreamTelegram(options) {
 				sessions: options.sessions,
 				sessionPolicy: policy,
 				sttModel: options.models().stt,
-				identities: pairing(),
+				identities: conversationIdentities(pairing()),
 				bot,
-				decide: decisionRouter({
+				decide: captureRouteDecider(decisionRouter({
 					decide: options.decide,
 					model: options.models().decision
-				}),
+				})),
 				transcribe: options.transcribe ?? gatewayTranscriber,
 				download: (fileId) => downloadTelegramFile({
 					proxy: proxy(),
@@ -178,18 +193,28 @@ function segmentstreamTelegram(options) {
 			fetchFile,
 			...turnFailed === void 0 ? {} : { "turn.failed": withTurnErrorLogging(turnFailed) }
 		} },
-		routes: [...channel.routes.map((route) => gatedRoute({
-			route,
-			options,
-			environment
-		})), messagesRoute({
-			channel,
-			enabled: () => channelsEnabled(environment),
-			configured: () => options.settings() !== null,
-			verify: () => verify ??= runtimeTokenVerifier(runtimeIdentityEnvironment(environment)),
-			sessionPolicy: policy,
-			scope: () => options.sessions().scope
-		})]
+		routes: [
+			...channel.routes.map((route) => gatedRoute({
+				route,
+				options,
+				environment,
+				capture
+			})),
+			messagesRoute({
+				channel,
+				enabled: () => channelsEnabled(environment),
+				configured: () => options.settings() !== null,
+				verify: () => verify ??= runtimeTokenVerifier(runtimeIdentityEnvironment(environment)),
+				sessionPolicy: policy,
+				scope: () => options.sessions().scope
+			}),
+			healthRoute({
+				chats,
+				enabled: () => channelsEnabled(environment),
+				configured: () => options.settings() !== null,
+				verify: () => verify ??= runtimeTokenVerifier(runtimeIdentityEnvironment(environment))
+			})
+		]
 	};
 }
 function sessionIdOf(context) {
@@ -210,14 +235,28 @@ function gatedRoute(input) {
 				resolveSession: args.resolveSession,
 				from: args.from
 			};
-			inbound.waitUntil = args.waitUntil;
 			inbound.respond = (address, requestId, decision, auth) => args.from(scoped(address)).respond([{
 				requestId,
 				optionId: decision
 			}], { auth });
-			return runInboundRequest(inbound, () => route.handler(request, {
-				...args,
-				from: (address) => withReplacedText(args.from(inbound.address ?? scoped(address)), inbound)
+			const tasks = [];
+			const waitUntil = (task) => {
+				tasks.push(task);
+				args.waitUntil(task);
+			};
+			inbound.waitUntil = waitUntil;
+			return runInboundRequest(inbound, () => input.capture(request, async () => {
+				const response = await route.handler(request, {
+					...args,
+					waitUntil,
+					from: (address) => withReplacedText(args.from(inbound.address ?? scoped(address)), inbound)
+				});
+				for (let completed = 0; completed < tasks.length;) {
+					const pending = tasks.slice(completed);
+					completed = tasks.length;
+					await Promise.all(pending);
+				}
+				return response;
 			}));
 		}
 	};

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

@@ -0,0 +1,40 @@
+import type { SessionAuthContext } from "eve/context";
+import { type Environment } from "../environment.js";
+import { type RuntimeToken } from "../runtime-token.js";
+export declare const MAXIMUM_PHOTO_BYTES: number;
+export declare const MAXIMUM_DOCUMENT_BYTES: number;
+export interface DocumentReference {
+    readonly entity: string;
+    readonly id: string;
+    readonly property?: string;
+}
+export interface SendAttachmentsInput {
+    readonly documentIds: ReadonlyArray<DocumentReference>;
+    readonly caption?: string;
+    readonly replyToMessageId?: number;
+}
+export interface SentFile {
+    readonly id: string;
+    readonly filename: string;
+    readonly telegramMessageId?: number;
+    readonly error?: string;
+    readonly detail?: string;
+    readonly reference?: string;
+}
+/** 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: {
+    readonly input: SendAttachmentsInput;
+    readonly principal: SessionAuthContext | null;
+    readonly sessionId: string;
+    readonly connection: string | undefined;
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+}): Promise<{
+    readonly files: ReadonlyArray<SentFile>;
+} | {
+    readonly error: string;
+    readonly detail: string;
+}>;

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

@@ -0,0 +1,269 @@
+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 { appOrigin, channelsEnabled, proxyEnvironment } from "../environment.mjs";
+import "./principal.mjs";
+import { MAXIMUM_PROXY_BODY_BYTES, connectionProxy } from "../connection-proxy.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 { redactDiagnostic } from "../diagnostics.mjs";
+import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
+import { attachmentOwner } from "../attachment-tools.mjs";
+const MAXIMUM_PHOTO_BYTES = 10485760;
+const MAXIMUM_DOCUMENT_BYTES = 52428800;
+const PHOTOS = new Set([
+	"image/jpeg",
+	"image/png",
+	"image/webp"
+]);
+const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NAME = /^[a-z][a-z0-9_]{0,63}$/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sendAttachmentsInput(value) {
+	if (!Array.isArray(value.documentIds) || value.documentIds.length < 1 || value.documentIds.length > 10) throw new TypeError("documentIds must contain 1 to 10 file record ids or references.");
+	const documentIds = value.documentIds.map((item) => {
+		const reference = typeof item === "string" ? {
+			entity: "document",
+			id: item
+		} : item;
+		if (!isRecord(reference) || typeof reference.id !== "string" || !RECORD_ID.test(reference.id) || typeof reference.entity !== "string" || !NAME.test(reference.entity) || reference.property !== void 0 && (typeof reference.property !== "string" || !NAME.test(reference.property))) throw new TypeError("Each file reference needs an entity, a record UUID and optionally a property.");
+		return {
+			entity: reference.entity,
+			id: reference.id,
+			...reference.property === void 0 ? {} : { property: reference.property }
+		};
+	});
+	if (value.caption !== void 0 && (typeof value.caption !== "string" || value.caption.length > 1024)) throw new TypeError("caption must be a string of at most 1024 characters.");
+	if (value.replyToMessageId !== void 0 && (typeof value.replyToMessageId !== "number" || !Number.isSafeInteger(value.replyToMessageId) || value.replyToMessageId < 1)) throw new TypeError("replyToMessageId must be a positive integer.");
+	return {
+		documentIds,
+		...value.caption === void 0 ? {} : { caption: value.caption },
+		...value.replyToMessageId === void 0 ? {} : { replyToMessageId: value.replyToMessageId }
+	};
+}
+function refused(code, message) {
+	return new AttachmentError({
+		code,
+		message
+	});
+}
+const PROXY_LIMIT = "The multipart upload exceeds the connection proxy's 2 MiB request limit (including overhead).";
+async function boundedDownload(response, maximum) {
+	if (response.body === null) throw refused("unsupported", "The stored file is empty.");
+	const reader = response.body.getReader();
+	const chunks = [];
+	let size = 0;
+	try {
+		while (true) {
+			const next = await reader.read();
+			if (next.done) break;
+			size += next.value.byteLength;
+			if (size > maximum) throw refused("too_large", PROXY_LIMIT);
+			chunks.push(next.value);
+		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+	return new Uint8Array(Buffer.concat(chunks));
+}
+async function sendAttachments(options) {
+	const environment = options.environment ?? process.env;
+	const principal = options.principal;
+	if (!channelsEnabled(environment)) return {
+		error: "channels_disabled",
+		detail: "Attachments can be sent only in production."
+	};
+	if (options.connection === void 0) return {
+		error: "unsupported",
+		detail: "The Telegram channel is not configured."
+	};
+	if (principal?.authenticator !== "segmentstream-telegram" || typeof principal.attributes.chatId !== "string" || !/^-?\d{1,20}$/.test(principal.attributes.chatId)) return {
+		error: "no_telegram_chat",
+		detail: "This turn has no Telegram chat."
+	};
+	let owner;
+	try {
+		owner = attachmentOwner({
+			principal,
+			sessionId: options.sessionId
+		});
+	} catch {
+		return {
+			error: "forbidden",
+			detail: "A paired member is required to send stored files."
+		};
+	}
+	const runtimeToken$1 = options.token ?? runtimeToken;
+	const secrets = new Set();
+	const token = async () => {
+		const value = await runtimeToken$1();
+		secrets.add(value);
+		return value;
+	};
+	const fetchImpl = options.fetch ?? fetch;
+	const origin = appOrigin(environment);
+	const telegram = telegramProxyFetch(connectionProxy({
+		environment: proxyEnvironment(environment),
+		connection: options.connection,
+		token,
+		fetch: fetchImpl
+	}));
+	const results = options.input.documentIds.map(({ id }) => ({
+		id,
+		filename: ""
+	}));
+	const uploads = [];
+	for (const [index, reference] of options.input.documentIds.entries()) {
+		let filename = "";
+		try {
+			const response = await fetchImpl(`${origin}/api/ontology/agent/files/${[
+				reference.entity,
+				reference.id,
+				...reference.property === void 0 ? [] : [reference.property]
+			].map(encodeURIComponent).join("/")}`, {
+				headers: {
+					authorization: `Bearer ${await token()}`,
+					[ACT_AS_HEADER]: owner.memberId,
+					[CONVERSATION_HEADER]: owner.conversation,
+					...owner.sessionId === void 0 ? {} : { [SESSION_HEADER]: owner.sessionId }
+				},
+				redirect: "error",
+				signal: AbortSignal.timeout(3e4)
+			});
+			if (!response.ok) {
+				const code = response.status === 404 ? "not_found" : response.status === 403 ? "forbidden" : response.status === 422 ? "unsupported" : "unavailable";
+				throw refused(code, `The ontology refused the file (${code}).`);
+			}
+			const answer = await response.json();
+			const file = isRecord(answer) ? answer.file : void 0;
+			const grant = isRecord(answer) ? answer.download : void 0;
+			if (!isRecord(file) || typeof file.filename !== "string" || typeof file.content_type !== "string" || typeof file.size !== "number" || !Number.isSafeInteger(file.size) || file.size < 0 || !isRecord(grant) || typeof grant.url !== "string" || !/^https?:\/\//.test(grant.url) || grant.method !== "GET" || !isRecord(grant.headers) || !Object.values(grant.headers).every((header) => typeof header === "string")) throw refused("invalid_response", "The ontology returned invalid file metadata.");
+			filename = file.filename;
+			secrets.add(grant.url);
+			Object.values(grant.headers).forEach((header) => secrets.add(header));
+			new URL(grant.url).searchParams.forEach((value, name) => {
+				if (/signature|credential|token|key/i.test(name)) secrets.add(value);
+			});
+			const contentType = file.content_type.toLowerCase();
+			const type = PHOTOS.has(contentType) ? "photo" : "document";
+			const maximum = type === "photo" ? MAXIMUM_PHOTO_BYTES : MAXIMUM_DOCUMENT_BYTES;
+			if (file.size > maximum) throw refused("too_large", `Telegram's ${type} limit is ${maximum / 1024 / 1024} MiB.`);
+			if (file.size > 2097152) throw refused("too_large", PROXY_LIMIT);
+			if (file.size === 0) throw refused("unsupported", "Telegram cannot send an empty file.");
+			const download = await fetchImpl(grant.url, {
+				method: "GET",
+				headers: grant.headers,
+				redirect: "error",
+				signal: AbortSignal.timeout(12e4)
+			});
+			if (!download.ok) throw refused(download.status === 404 ? "not_found" : "unavailable", "The stored file could not be downloaded.");
+			const bytes = await boundedDownload(download, Math.min(maximum, MAXIMUM_PROXY_BODY_BYTES));
+			if (bytes.byteLength !== file.size) throw refused("invalid_response", "The downloaded size differs from the stored file metadata.");
+			uploads.push({
+				index,
+				id: reference.id,
+				filename,
+				type,
+				blob: new Blob([Buffer.from(bytes)], { type: contentType })
+			});
+		} catch (error) {
+			const errorId = crypto.randomUUID();
+			console.error("[segmentstream] stored attachment fetch failed", {
+				errorId,
+				id: reference.id,
+				error: redactDiagnostic(error, secrets)
+			});
+			results[index] = {
+				id: reference.id,
+				filename,
+				error: error instanceof AttachmentError ? error.code : "unavailable",
+				detail: error instanceof AttachmentError ? error.message : "The file could not be fetched.",
+				reference: errorId
+			};
+		}
+	}
+	function multipart(files, caption) {
+		const form = new FormData();
+		form.set("chat_id", principal.attributes.chatId);
+		const thread = principal.attributes.messageThreadId;
+		if (typeof thread === "string" && /^\d+$/.test(thread)) form.set("message_thread_id", thread);
+		if (options.input.replyToMessageId !== void 0) form.set("reply_parameters", JSON.stringify({ message_id: options.input.replyToMessageId }));
+		if (files.length === 1) {
+			const file = files[0];
+			form.set(file.type, file.blob, file.filename);
+			if (caption !== void 0) form.set("caption", caption);
+		} else {
+			form.set("media", JSON.stringify(files.map((file, index) => ({
+				type: file.type,
+				media: `attach://file${index}`,
+				...index === 0 && caption !== void 0 ? { caption } : {}
+			}))));
+			files.forEach((file, index) => form.set(`file${index}`, file.blob, file.filename));
+		}
+		const method = files.length > 1 ? "sendMediaGroup" : files[0].type === "photo" ? "sendPhoto" : "sendDocument";
+		return new Request(`${TELEGRAM_PROXY_ORIGIN}/bot${TELEGRAM_PLACEHOLDER_TOKEN}/${method}`, {
+			method: "POST",
+			body: form
+		});
+	}
+	let caption = options.input.caption;
+	let cursor = 0;
+	while (cursor < uploads.length) {
+		const batch = [uploads[cursor++]];
+		let request = multipart(batch, caption);
+		let size = (await request.clone().arrayBuffer()).byteLength;
+		while (cursor < uploads.length && batch.length < 10 && uploads[cursor].type === batch[0].type) {
+			const candidate = multipart([...batch, uploads[cursor]], caption);
+			const candidateSize = (await candidate.clone().arrayBuffer()).byteLength;
+			if (candidateSize > 2097152) break;
+			batch.push(uploads[cursor++]);
+			request = candidate;
+			size = candidateSize;
+		}
+		try {
+			if (size > 2097152) throw refused("too_large", PROXY_LIMIT);
+			const response = await telegram(request);
+			const answer = await response.json();
+			if (!response.ok || !isRecord(answer) || answer.ok !== true) {
+				console.error("[segmentstream] Telegram attachment upload refused", {
+					status: response.status,
+					answer: redactDiagnostic(answer, secrets)
+				});
+				throw refused(response.status === 413 ? "too_large" : response.status === 403 ? "forbidden" : "send_failed", "Telegram refused the attachment upload.");
+			}
+			const messages = batch.length === 1 ? [answer.result] : answer.result;
+			if (!Array.isArray(messages) || messages.length !== batch.length || !messages.every((message) => isRecord(message) && Number.isSafeInteger(message.message_id))) throw refused("invalid_response", "Telegram did not return the uploaded files' message ids.");
+			batch.forEach((file, index) => {
+				results[file.index] = {
+					id: file.id,
+					filename: file.filename,
+					telegramMessageId: messages[index].message_id
+				};
+			});
+			caption = void 0;
+		} catch (error) {
+			const errorId = crypto.randomUUID();
+			console.error("[segmentstream] attachment upload failed", {
+				errorId,
+				error: redactDiagnostic(error, secrets)
+			});
+			batch.forEach((file) => {
+				results[file.index] = {
+					id: file.id,
+					filename: file.filename,
+					error: error instanceof AttachmentError ? error.code : "send_failed",
+					detail: error instanceof AttachmentError ? error.message : "The attachment upload failed.",
+					reference: errorId
+				};
+			});
+		}
+	}
+	return { files: results };
+}
+export { MAXIMUM_DOCUMENT_BYTES, MAXIMUM_PHOTO_BYTES, sendAttachments, sendAttachmentsInput };

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

@@ -1,12 +1,22 @@
-import type { AgentChat, AgentIdentities } from "../identities.js";
+import { type AgentChat, type AgentIdentities } from "../identities.js";
 /** How long a chat's report stands before the next message reports it again. */
 export declare const REPORT_INTERVAL_MS: number;
+export declare const REPORT_FAILURE_THRESHOLD = 3;
 export interface ChatReport {
     readonly chatId: string;
     readonly title: string;
     readonly memberId?: string;
 }
 export interface AgentChats {
+    /** The bot joined/rejoined: report immediately even if this chat was recently remembered. */
+    joined(report: ChatReport): Promise<void>;
+    /** Process-local report diagnostics for the authenticated channel health route. */
+    health(): {
+        readonly failureThreshold: number;
+        readonly totalFailures: number;
+        readonly degraded: boolean;
+        readonly chats: ReadonlyArray<ChatReportFailure>;
+    };
     /** Reports the chat when due. Resolves when done; never rejects. */
     seen(report: ChatReport): Promise<void>;
     /**
@@ -37,10 +47,20 @@ export interface AgentChats {
     /** The registry's latest answer for the chat, if this process has one. */
     chat(chatId: string): AgentChat | undefined;
 }
+export interface ChatReportFailure {
+    readonly chatId: string;
+    readonly consecutiveFailures: number;
+    readonly lastFailedAt: string;
+    readonly status: number | null;
+    readonly code: string;
+    readonly requestId: string | null;
+}
 export declare function agentChats(input: {
     readonly identities: () => AgentIdentities;
     readonly now?: () => number;
     readonly log?: (message: string, error: unknown) => void;
+    readonly logError?: (message: string, error: unknown) => void;
+    readonly logRecovery?: (message: string, detail: unknown) => void;
 }): AgentChats;
 /** The registry's facts as turn context: only the fields it holds. */
 export declare function chatContext(chat: AgentChat | undefined): ReadonlyArray<string>;

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

@@ -4,13 +4,21 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { redactDiagnostic } from "../diagnostics.mjs";
+import { AgentIdentityError } from "../identities.mjs";
 const MAXIMUM_WHEN_TO_USE_LENGTH = 1e3;
 const REPORT_INTERVAL_MS = 6e5;
+const REPORT_FAILURE_THRESHOLD = 3;
 const MAXIMUM_CHATS = 500;
 function agentChats(input) {
 	const chats = new Map();
+	const inFlight = new Map();
+	const failures = new Map();
+	let totalFailures = 0;
 	const now = input.now ?? Date.now;
 	const log = input.log ?? ((message, error) => console.warn(message, error));
+	const logError = input.logError ?? ((message, error) => console.error(message, error));
+	const logRecovery = input.logRecovery ?? ((message, detail) => console.info(message, detail));
 	function remember(chatId, value) {
 		chats.delete(chatId);
 		chats.set(chatId, value);
@@ -35,17 +43,65 @@ function agentChats(input) {
 				...chats.get(chatId) ?? fallback,
 				chat
 			});
+			const previousFailure = failures.get(chatId);
+			failures.delete(chatId);
+			if ((previousFailure?.consecutiveFailures ?? 0) >= 3) logRecovery("The agent's chat registry report recovered.", {
+				event: "segmentstream.telegram.registry_recovered",
+				chatId,
+				consecutiveFailures: previousFailure.consecutiveFailures
+			});
 			return true;
 		} catch (error) {
-			log("The agent could not report the chat to the ontology's registry.", error);
+			totalFailures += 1;
+			const failure = {
+				chatId,
+				consecutiveFailures: (failures.get(chatId)?.consecutiveFailures ?? 0) + 1,
+				lastFailedAt: new Date(now()).toISOString(),
+				status: error instanceof AgentIdentityError ? error.status ?? null : null,
+				code: error instanceof AgentIdentityError ? error.code : "unavailable",
+				requestId: error instanceof AgentIdentityError ? error.requestId ?? null : null
+			};
+			failures.delete(chatId);
+			failures.set(chatId, failure);
+			if (failures.size > MAXIMUM_CHATS) failures.delete(failures.keys().next().value);
+			const detail = {
+				event: "segmentstream.telegram.registry_report_failed",
+				...failure,
+				totalFailures,
+				error: redactDiagnostic(error, new Set())
+			};
+			if (failure.consecutiveFailures < 3) log("The agent could not report the chat to the ontology's registry.", detail);
+			else if (failure.consecutiveFailures === 3) logError("The agent's chat registry reports repeatedly failed.", detail);
 			return false;
 		}
 	}
 	return {
+		async joined({ chatId, title }) {
+			const known = chats.get(chatId);
+			const remembered = {
+				reportedAt: now(),
+				members: known?.members ?? new Set(),
+				chat: known?.chat
+			};
+			remember(chatId, remembered);
+			if (!await report(chatId, remembered, { title })) restore(chatId, remembered, known);
+		},
+		health() {
+			const failedChats = [...failures.values()];
+			return {
+				failureThreshold: 3,
+				totalFailures,
+				degraded: failedChats.some((failure) => failure.consecutiveFailures >= 3),
+				chats: failedChats
+			};
+		},
 		async seen({ chatId, title, memberId }) {
 			const known = chats.get(chatId);
 			const at = now();
-			if (!(known === void 0 || at - known.reportedAt >= 6e5 || memberId !== void 0 && !known.members.has(memberId))) return;
+			if (!(known === void 0 || at - known.reportedAt >= 6e5 || memberId !== void 0 && !known.members.has(memberId))) {
+				await inFlight.get(chatId);
+				return;
+			}
 			const members = new Set(known?.members);
 			if (memberId !== void 0) members.add(memberId);
 			const written = {
@@ -54,14 +110,22 @@ function agentChats(input) {
 				chat: known?.chat
 			};
 			remember(chatId, written);
-			if (!await report(chatId, {
-				reportedAt: at,
-				members,
-				chat: void 0
-			}, {
-				title,
-				...memberId === void 0 ? {} : { memberId }
-			})) restore(chatId, written, known);
+			const task = (async () => {
+				if (!await report(chatId, {
+					reportedAt: at,
+					members,
+					chat: void 0
+				}, {
+					title,
+					...memberId === void 0 ? {} : { memberId }
+				})) restore(chatId, written, known);
+			})();
+			inFlight.set(chatId, task);
+			try {
+				await task;
+			} finally {
+				if (inFlight.get(chatId) === task) inFlight.delete(chatId);
+			}
 		},
 		async left({ chatId, title, memberId }) {
 			const known = chats.get(chatId);
@@ -120,4 +184,4 @@ function chatContext(chat) {
 	lines.push("</chat>");
 	return [lines.join("\n")];
 }
-export { REPORT_INTERVAL_MS, agentChats, chatContext };
+export { REPORT_FAILURE_THRESHOLD, REPORT_INTERVAL_MS, agentChats, chatContext };

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

@@ -6,8 +6,8 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { memberIdOf, telegramPrincipal } from "./principal.mjs";
 import { confirmations } from "../confirmations.mjs";
-import { answerMarker, isPendingQuestion, pendingQuestions, questionKey } from "../questions.mjs";
 import { currentInboundRequest } from "./inbound-request.mjs";
+import { answerMarker, isPendingQuestion, pendingQuestions, questionKey } from "../questions.mjs";
 import { formatAddress, scopedAddress } from "./sessions.mjs";
 import { registerTelegramFreeformPrompt, renderTelegramInputRequest } from "eve/channels/telegram";
 import { createHash } from "node:crypto";

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

@@ -0,0 +1,30 @@
+import type { AgentIdentities } from "../identities.js";
+import { type Conversations } from "../conversations.js";
+import type { AgentChats } from "./chats.js";
+import type { ObservedMessages } from "./observed.js";
+import type { AddressingReason, RouteDecider } from "./router.js";
+/** Runs after webhook verification, before eve drops bot/channel/service updates. */
+export declare function captureTelegramWebhook(input: {
+    readonly request: Request;
+    readonly archive: Conversations;
+    readonly identities: AgentIdentities;
+    readonly observed: ObservedMessages;
+    readonly chats?: AgentChats;
+    readonly next: () => Promise<Response>;
+}): Promise<Response>;
+/** Additive inbound hook: the router keeps ownership of the reply policy. */
+export declare function recordGateDecision(reason: string, decision?: "reply" | "silent"): void;
+export declare function recordRouteDecision(route: "reply" | "observe", addressed: boolean | AddressingReason | undefined, policy: string): void;
+export declare function captureRouteDecider(decide: RouteDecider): RouteDecider;
+/** Captures every Telegram sendMessage chunk, including pairing/HITL/proactive replies. */
+export declare function captureTelegramFetch(fetchImpl: typeof fetch, archive: Conversations, identities: () => AgentIdentities): typeof fetch;
+/** Reuses the request's verified lookup; it never survives into another inbound request. */
+export declare function conversationIdentities(identities: AgentIdentities): AgentIdentities;
+/** Verification and failure acknowledgement stay outside eve's swallowed onMessage failures. */
+export declare function telegramConversationCapture(input: {
+    readonly archive: Conversations;
+    readonly identities: () => AgentIdentities;
+    readonly observed: ObservedMessages;
+    readonly chats: AgentChats;
+    readonly verify: (request: Request) => boolean;
+}): (request: Request, next: () => Promise<Response>) => Promise<Response>;