@segmentstream/agent 0.3.1 → 0.5.0

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

@@ -0,0 +1,298 @@
+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 { conversationEvent } from "../conversations.mjs";
+import { observedChatKey } from "./observed.mjs";
+import { currentInboundRequest } from "./inbound-request.mjs";
+import { reportMembership } from "./membership.mjs";
+import { parseTelegramUpdate } from "eve/channels/telegram";
+import { randomUUID } from "node:crypto";
+const captures = new WeakMap();
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+const id = (value) => typeof value === "number" || typeof value === "string" ? String(value) : null;
+function attachmentRefs(message) {
+	const files = message.attachments.map((file) => ({
+		id: file.fileId,
+		kind: file.kind,
+		...file.fileName === void 0 ? {} : { filename: file.fileName },
+		...file.mediaType === void 0 ? {} : { contentType: file.mediaType },
+		...file.size === void 0 ? {} : { size: file.size },
+		...file.fileUniqueId === void 0 ? {} : { uniqueId: file.fileUniqueId }
+	}));
+	for (const kind of [
+		"voice",
+		"audio",
+		"video",
+		"video_note",
+		"sticker",
+		"animation"
+	]) {
+		const file = record(message.raw[kind]);
+		const fileId = id(file.file_id);
+		if (fileId !== null) files.push({
+			id: fileId,
+			kind,
+			...id(file.file_unique_id) ? { uniqueId: id(file.file_unique_id) } : {},
+			...typeof file.file_size === "number" ? { size: file.file_size } : {},
+			...typeof file.mime_type === "string" ? { contentType: file.mime_type } : {},
+			...typeof file.file_name === "string" ? { filename: file.file_name } : {}
+		});
+	}
+	return files;
+}
+async function participants(message, identities, resolved) {
+	if (message.chat.type !== "private" || message.from === void 0 || message.from.isBot) return [];
+	try {
+		const lookup = await identities.lookup({
+			provider: "telegram",
+			externalId: message.from.id
+		});
+		resolved(lookup);
+		return lookup.status === "paired" ? [lookup.member.id] : [];
+	} catch (error) {
+		console.error("[segmentstream] conversation participant lookup failed", { error });
+		return [];
+	}
+}
+async function captureTelegramWebhook(input) {
+	let raw;
+	try {
+		raw = await input.request.clone().json();
+	} catch {
+		return input.next();
+	}
+	const update = record(raw);
+	if (input.chats !== void 0 && (update.my_chat_member !== void 0 || update.chat_member !== void 0)) {
+		const task = reportMembership({
+			update,
+			chats: input.chats,
+			identities: input.identities
+		});
+		currentInboundRequest()?.waitUntil?.(task);
+		await task;
+		return input.next();
+	}
+	const edited = update.edited_message ?? update.edited_channel_post;
+	const messagePayload = edited ?? update.channel_post ?? update.message;
+	const parsed = parseTelegramUpdate({ message: messagePayload });
+	if (parsed?.kind !== "message") return input.next();
+	const message = parsed.message;
+	const sentAt = typeof message.raw.date === "number" ? message.raw.date * 1e3 : Date.now();
+	const senderChat = record(message.raw.sender_chat);
+	let lookup;
+	const event = conversationEvent({
+		eventId: [
+			"telegram",
+			message.chat.id,
+			message.messageId,
+			edited === void 0 ? "message" : `edit:${id(update.update_id) ?? id(message.raw.edit_date)}`
+		].join(":"),
+		provider: "telegram",
+		chatId: message.chat.id,
+		chatType: message.chat.type === "supergroup" ? "group" : message.chat.type,
+		threadId: message.messageThreadId === void 0 ? null : String(message.messageThreadId),
+		kind: "inbound",
+		text: message.text || message.caption || null,
+		messageId: message.messageId,
+		replyToMessageId: message.replyToMessage?.messageId ?? null,
+		senderId: id(senderChat.id) ?? message.from?.id ?? null,
+		senderName: typeof senderChat.title === "string" ? senderChat.title : message.from?.username ?? message.from?.firstName ?? null,
+		senderIsBot: message.from?.isBot ?? false,
+		participantIds: await participants(message, input.identities, (result) => {
+			lookup = result;
+		}),
+		attachments: attachmentRefs(message),
+		at: new Date(sentAt).toISOString()
+	});
+	await input.archive.append(event);
+	const capture = {
+		event,
+		message,
+		...lookup === void 0 ? {} : { lookup }
+	};
+	const inbound = currentInboundRequest();
+	if (inbound !== void 0) captures.set(inbound, capture);
+	const chat = observedChatKey({
+		chatId: message.chat.id,
+		...message.messageThreadId === void 0 ? {} : { messageThreadId: message.messageThreadId }
+	});
+	if (!(message.from === void 0 || message.from.isBot || message.chat.type === "channel") && edited === void 0) {
+		const history = await input.archive.context({
+			provider: "telegram",
+			chatId: message.chat.id,
+			...event.threadId === null ? {} : { threadId: event.threadId },
+			limit: 100
+		});
+		for (const earlier of (input.observed.recent(chat).length === 0 ? history.events : []).filter((item) => item.kind === "inbound" && item.eventId !== event.eventId).slice(0, 30).reverse()) input.observed.add(chat, {
+			author: earlier.senderName ?? earlier.senderId ?? "automated post",
+			text: earlier.text ?? "[attachment or service message]",
+			at: earlier.at,
+			...earlier.senderId === null ? {} : { authorId: earlier.senderId }
+		});
+	} else {
+		if (message.chat.type === "group" || message.chat.type === "supergroup") await input.chats?.seen({
+			chatId: message.chat.id,
+			title: message.chat.title ?? ""
+		});
+		input.observed.add(chat, {
+			author: event.senderName ?? event.senderId ?? "automated post",
+			text: event.text ?? "[attachment or service message]",
+			at: event.at
+		});
+		capture.decision = "silent";
+		capture.reason = edited !== void 0 ? "message_edit" : "automated_or_channel_message";
+	}
+	let response;
+	try {
+		response = await input.next();
+	} catch (error) {
+		try {
+			await input.archive.append({
+				...event,
+				eventId: `${event.eventId}:decision`,
+				kind: "decision",
+				text: null,
+				decision: "silent",
+				reason: "inbound_handler_failed",
+				attachments: []
+			});
+		} catch (storageError) {
+			console.error("[segmentstream] recording inbound failure failed", {
+				storageError,
+				cause: error
+			});
+		}
+		throw error;
+	}
+	await input.archive.append({
+		...event,
+		eventId: `${event.eventId}:decision`,
+		kind: "decision",
+		text: null,
+		decision: capture.decision ?? "silent",
+		reason: capture.reason ?? (message.raw.left_chat_member ? "member_departure" : message.raw.migrate_to_chat_id || message.raw.migrate_from_chat_id ? "chat_migration" : "unpaired_refused_or_empty_message"),
+		attachments: []
+	});
+	return response;
+}
+function recordGateDecision(reason, decision = "silent") {
+	const inbound = currentInboundRequest();
+	const capture = inbound === void 0 ? void 0 : captures.get(inbound);
+	if (capture !== void 0) {
+		capture.reason = reason;
+		capture.decision = decision;
+	}
+}
+function recordRouteDecision(route, addressed, policy) {
+	const inbound = currentInboundRequest();
+	const capture = inbound === void 0 ? void 0 : captures.get(inbound);
+	if (capture !== void 0) {
+		capture.decision = route === "reply" ? "reply" : "silent";
+		capture.reason ??= typeof addressed === "string" ? addressed : addressed ? "addressed_message" : policy === "mention" ? "mention_policy" : `decision_model_${route}`;
+	}
+}
+function captureRouteDecider(decide) {
+	return async (question) => {
+		try {
+			return await decide(question);
+		} catch (error) {
+			const inbound = currentInboundRequest();
+			const capture = inbound === void 0 ? void 0 : captures.get(inbound);
+			if (capture !== void 0) capture.reason = error instanceof Error && error.name === "TimeoutError" ? "decision_model_timeout" : "decision_model_failed";
+			throw error;
+		}
+	};
+}
+function captureTelegramFetch(fetchImpl, archive, identities) {
+	return async (input, init) => {
+		if (!(typeof input === "string" ? input : input instanceof URL ? input.href : input.url).endsWith("/sendMessage") || typeof init?.body !== "string") return fetchImpl(input, init);
+		const body = record(JSON.parse(init.body));
+		const chatId = id(body.chat_id);
+		if (chatId === null) return fetchImpl(input, init);
+		const inbound = currentInboundRequest();
+		const capture = inbound === void 0 ? void 0 : captures.get(inbound);
+		let participantIds = capture?.event.participantIds ?? [];
+		const chatType = capture?.event.chatType ?? (chatId.startsWith("-") ? "group" : "private");
+		if (chatType === "private" && participantIds.length === 0 && capture === void 0) try {
+			const lookup = await identities().lookup({
+				provider: "telegram",
+				externalId: chatId
+			});
+			if (lookup.status === "paired") participantIds = [lookup.member.id];
+		} catch (error) {
+			console.error("[segmentstream] outbound participant lookup failed", { error });
+		}
+		const event = conversationEvent({
+			eventId: `telegram:send:${randomUUID()}`,
+			provider: "telegram",
+			chatId,
+			chatType,
+			kind: "outbound",
+			text: typeof body.text === "string" ? body.text : null,
+			senderIsBot: true,
+			senderId: "agent",
+			senderName: "agent",
+			participantIds,
+			threadId: id(body.message_thread_id),
+			replyToMessageId: id(body.reply_to_message_id) ?? id(record(body.reply_parameters).message_id),
+			status: "requested"
+		});
+		await archive.append(event);
+		let response;
+		try {
+			response = await fetchImpl(input, init);
+		} catch (error) {
+			try {
+				await archive.append({
+					...event,
+					eventId: `${event.eventId}:result`,
+					status: "unknown"
+				});
+			} catch (storageError) {
+				console.error("[segmentstream] recording uncertain delivery failed", {
+					storageError,
+					cause: error
+				});
+			}
+			throw error;
+		}
+		const result = record(await response.clone().json());
+		await archive.append({
+			...event,
+			eventId: `${event.eventId}:result`,
+			status: response.ok && result.ok === true ? "completed" : "failed",
+			messageId: id(record(result.result).message_id)
+		});
+		return response;
+	};
+}
+function conversationIdentities(identities) {
+	return {
+		...identities,
+		lookup: async (account) => {
+			const inbound = currentInboundRequest();
+			const capture = inbound === void 0 ? void 0 : captures.get(inbound);
+			return account.provider === "telegram" && capture?.message.from?.id === account.externalId && capture.lookup !== void 0 ? capture.lookup : identities.lookup(account);
+		}
+	};
+}
+function telegramConversationCapture(input) {
+	return async (request, next) => {
+		if (!input.verify(request)) return next();
+		try {
+			return await captureTelegramWebhook({
+				...input,
+				request,
+				identities: input.identities(),
+				next
+			});
+		} catch (error) {
+			console.error("[segmentstream] conversation capture failed", { error });
+			return new Response("conversation storage unavailable", { status: 503 });
+		}
+	};
+}
+export { captureRouteDecider, captureTelegramFetch, captureTelegramWebhook, conversationIdentities, recordGateDecision, recordRouteDecision, telegramConversationCapture };

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

@@ -0,0 +1,12 @@
+import { type RouteDefinition } from "eve/channels";
+import type { TelegramChannelState } from "eve/channels/telegram";
+import type { RuntimeTokenVerifier } from "../runtime-identity.js";
+import type { AgentChats } from "./chats.js";
+export declare const HEALTH_ROUTE = "/eve/v1/telegram/health";
+/** Runtime-only, per-instance health. It never exposes credentials or private provider bodies. */
+export declare function healthRoute(input: {
+    readonly chats: AgentChats;
+    readonly enabled: () => boolean;
+    readonly configured: () => boolean;
+    readonly verify: () => RuntimeTokenVerifier;
+}): RouteDefinition<TelegramChannelState>;

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

@@ -0,0 +1,24 @@
+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 { runtimeRequestFailure } from "./requests.mjs";
+import { GET } from "eve/channels";
+const HEALTH_ROUTE = "/eve/v1/telegram/health";
+function healthRoute(input) {
+	return GET(HEALTH_ROUTE, async (request) => {
+		const failure = await runtimeRequestFailure(request, input);
+		if (failure !== void 0) return failure;
+		const registry = input.chats.health();
+		return Response.json({
+			status: registry.degraded ? "degraded" : "ok",
+			registry
+		}, {
+			status: registry.degraded ? 503 : 200,
+			headers: { "cache-control": "no-store" }
+		});
+	});
+}
+export { HEALTH_ROUTE, healthRoute };

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

@@ -5,12 +5,13 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { telegramPrincipal } from "./principal.mjs";
+import { observedChatKey, observedContext } from "./observed.mjs";
+import { recordGateDecision, recordRouteDecision } from "./conversations.mjs";
 import { answerMarker } from "../questions.mjs";
 import { formatAddress, messageAddress, scopedAddress } from "./sessions.mjs";
 import { questionAddress, questionFromHistory } from "./confirmations.mjs";
 import { chatContext } from "./chats.mjs";
 import { attachmentsContext, stageFiles } from "./files.mjs";
-import { observedChatKey, observedContext } from "./observed.mjs";
 import { addressingReason, routeMessage } from "./router.mjs";
 import { routingContext } from "./routing-context.mjs";
 import { voiceNote, voiceOf, voiceText } from "./voice.mjs";
@@ -143,6 +144,7 @@ async function handleInboundMessage(input) {
 	const left = message.raw.left_chat_member;
 	const migration = isGroupChat(message) ? migrationOf(message) : void 0;
 	if (isGroupChat(message) && isRecord(left)) {
+		recordGateDecision("member_departure");
 		await reportDeparture({
 			context,
 			message,
@@ -152,6 +154,7 @@ async function handleInboundMessage(input) {
 		return null;
 	}
 	if (migration !== void 0) {
+		recordGateDecision("chat_migration");
 		await dependencies.chats.migrated({
 			...migration,
 			title: message.chat.title ?? ""
@@ -177,6 +180,7 @@ async function handleInboundMessage(input) {
 	}) : void 0;
 	if (report !== void 0) input.request?.waitUntil?.(report);
 	if (lookup.status !== "paired") {
+		recordGateDecision(`identity_${lookup.status}`, addressed !== void 0 ? "reply" : "silent");
 		if (addressed !== void 0) await answerUnpaired({
 			context,
 			message: sent,
@@ -221,12 +225,15 @@ async function handleInboundMessage(input) {
 		text = [caption, spoken.text].filter((part) => part.trim() !== "").join("\n\n");
 		notes.push(spoken.note);
 	} else if (voice !== void 0) text = caption || voiceNote(voice);
-	if (text.trim() === "" && sent.attachments.length === 0) return null;
+	if (text.trim() === "" && sent.attachments.length === 0) {
+		recordGateDecision("empty_message");
+		return null;
+	}
 	const chat = observedChatKey({
 		chatId: sent.chat.id,
 		...sent.messageThreadId === void 0 ? {} : { messageThreadId: sent.messageThreadId }
 	});
-	if (await routeMessage({
+	const route = await routeMessage({
 		chatId: sent.chat.id,
 		memberId: lookup.member.id,
 		policy: dependencies.policy,
@@ -246,7 +253,9 @@ async function handleInboundMessage(input) {
 				message: observedMessage(sent, text, lookup.member)
 			};
 		}
-	}) === "observe") {
+	});
+	recordRouteDecision(route, addressed ?? (answering ? "pending-question" : void 0), dependencies.policy);
+	if (route === "observe") {
 		dependencies.observed.add(chat, observedMessage(sent, text === "" ? "[attachment]" : text, lookup.member));
 		return null;
 	}

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

@@ -0,0 +1,8 @@
+import type { AgentIdentities } from "../identities.js";
+import type { AgentChats } from "./chats.js";
+/** Membership updates have no message for Eve to route. Report them at the verified webhook boundary. */
+export declare function reportMembership(input: {
+    readonly update: Record<string, unknown>;
+    readonly chats: AgentChats;
+    readonly identities: AgentIdentities;
+}): Promise<void>;

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

@@ -0,0 +1,48 @@
+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);
+function record(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function isMember(value) {
+	return value.status === "member" || value.status === "administrator" || value.status === "creator" || value.status === "restricted" && value.is_member === true;
+}
+async function reportMembership(input) {
+	const mine = input.update.my_chat_member !== void 0;
+	const update = record(input.update.my_chat_member ?? input.update.chat_member);
+	const chat = record(update.chat);
+	const next = record(update.new_chat_member);
+	const previous = record(update.old_chat_member);
+	if (chat.type !== "group" && chat.type !== "supergroup" || typeof chat.id !== "number" && typeof chat.id !== "string" || !/^-?\d{1,20}$/.test(String(chat.id))) return;
+	const report = {
+		chatId: String(chat.id),
+		title: typeof chat.title === "string" ? chat.title : ""
+	};
+	if (mine) {
+		if (isMember(next)) await input.chats.joined(report);
+		else if (isMember(previous) && (next.status === "left" || next.status === "kicked" || next.status === "restricted")) await input.chats.agentLeft(report);
+		return;
+	}
+	const user = record(next.user);
+	if (user.is_bot === true || typeof user.id !== "number" && typeof user.id !== "string") return;
+	const lookup = await input.identities.lookup({
+		provider: "telegram",
+		externalId: String(user.id)
+	});
+	if (lookup.status !== "paired") {
+		await input.chats.seen(report);
+		return;
+	}
+	if (isMember(next)) await input.chats.seen({
+		...report,
+		memberId: lookup.member.id
+	});
+	else if (isMember(previous)) await input.chats.left({
+		...report,
+		memberId: lookup.member.id
+	});
+}
+export { reportMembership };

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

@@ -38,10 +38,6 @@ function telegramProxyRoute(url) {
 function headerPairs(headers) {
 	return [...new Headers(headers).entries()];
 }
-async function bodyBytes(body) {
-	if (body === void 0 || body === null) return new Uint8Array();
-	return new Uint8Array(await new Response(body).arrayBuffer());
-}
 function proxyMethod(method) {
 	const upper = (method ?? "GET").toUpperCase();
 	for (const candidate of METHODS) if (candidate === upper) return candidate;
@@ -53,12 +49,13 @@ function hasNullBody(status) {
 function telegramProxyFetch(proxy) {
 	return async (input, init) => {
 		const route = telegramProxyRoute(requestUrl(input));
+		const request = new Request(input, init);
 		const call = {
 			api: route.api,
-			method: proxyMethod(init?.method),
+			method: proxyMethod(request.method),
 			path: route.path,
-			headers: headerPairs(init?.headers),
-			body: await bodyBytes(init?.body)
+			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), {

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

@@ -21,6 +21,8 @@ export interface AgentRequest {
         readonly chatId: string;
     };
     readonly message: string;
+    /** Document record ids from newer ontologies; omitted by older deployments. */
+    readonly documentIds?: ReadonlyArray<string>;
     /** Whom to contact, when the requester named someone. */
     readonly person: {
         readonly id: string;
@@ -53,6 +55,13 @@ export declare function agentRequest(value: unknown): AgentRequest | undefined;
 export declare function requestPrincipal(request: AgentRequest): SessionAuthContext;
 /** What the turn is about, for the model, ahead of the request itself. */
 export declare function requestContext(request: AgentRequest): string;
+/** Authenticate internal channel routes with the production deployment's runtime identity. */
+export declare function runtimeRequestFailure(request: Request, options: {
+    readonly enabled: () => boolean;
+    readonly configured: () => boolean;
+    readonly verify: () => RuntimeTokenVerifier;
+    readonly log?: (message: string, detail: unknown) => void;
+}): Promise<Response | undefined>;
 /**
  * `POST /eve/v1/telegram/messages`. Gated like the webhook: outside production it answers 503 and a
  * workspace without a Telegram channel 404. The caller must be a function of this deployment's

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

@@ -33,7 +33,8 @@ function agentRequest(value) {
 	const from = user(requester);
 	const held = isRecord(requester) ? roles(requester.roles) : void 0;
 	const actAs = isRecord(requester) ? requester.actAs : void 0;
-	if (!isRecord(target) || target.kind !== "group" && target.kind !== "private" || target.provider !== "telegram" || typeof target.chatId !== "string" || !CHAT_ID.test(target.chatId) || !isText(message) || message.length > MAX_REQUEST_MESSAGE_LENGTH || person === void 0 || from === void 0 || !isRecord(requester) || requester.kind !== "member" && requester.kind !== "service" || held === void 0 || actAs !== void 0 && typeof actAs !== "boolean") return;
+	const documentIds = value.documentIds;
+	if (!isRecord(target) || target.kind !== "group" && target.kind !== "private" || target.provider !== "telegram" || typeof target.chatId !== "string" || !CHAT_ID.test(target.chatId) || !isText(message) || message.length > MAX_REQUEST_MESSAGE_LENGTH || person === void 0 || from === void 0 || !isRecord(requester) || requester.kind !== "member" && requester.kind !== "service" || held === void 0 || actAs !== void 0 && typeof actAs !== "boolean" || documentIds !== void 0 && (!Array.isArray(documentIds) || documentIds.length > 10 || !documentIds.every((id) => typeof id === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)))) return;
 	return {
 		target: {
 			kind: target.kind,
@@ -41,6 +42,7 @@ function agentRequest(value) {
 			chatId: target.chatId
 		},
 		message,
+		...documentIds === void 0 ? {} : { documentIds },
 		person,
 		requester: {
 			...from,
@@ -91,6 +93,7 @@ function requestContext(request) {
 		`Write in this chat${to}, carry out the clear request, ask only for missing or ambiguous information, and handle the replies here.`,
 		"If the addressed person has a linked Telegram username, mention them with @username; otherwise address them by name without a tag. Never invent a username."
 	];
+	if (request.documentIds !== void 0 && request.documentIds.length > 0) lines.push(`documentIds: ${JSON.stringify(request.documentIds)}`, "Send these documents with the question using segmentstream__attachments_send in this chat. Use the question as the caption (at most 1024 characters), one question per message. In groups send documents only when the chat's purpose allows; never send restricted documents there.");
 	if (requester.kind === "service" || !requester.actAs) lines.push(`${requester.kind === "service" ? "The requester is a service, not a member" : "The requester has not paired a Telegram account with the agent"}, so this turn runs without a member and the ontology is not available in it. Each member who replies acts with their own permissions.`);
 	lines.push("</agent_request>");
 	return lines.join("\n");
@@ -112,29 +115,33 @@ function bearer(header) {
 function error(code, status) {
 	return Response.json({ error: code }, { status });
 }
+async function runtimeRequestFailure(request, options) {
+	const log = options.log ?? ((message, detail) => console.warn(message, detail));
+	if (!options.enabled()) return error("channels_disabled", 503);
+	if (!options.configured()) return error("not_found", 404);
+	const token = bearer(request.headers.get("authorization"));
+	if (token === void 0) return error("unauthorized", 401);
+	let verifier;
+	try {
+		verifier = options.verify();
+	} catch (cause) {
+		log("The agent cannot verify requests: the runtime identity is not configured.", cause);
+		return error("unavailable", 503);
+	}
+	const verification = await verifier(token);
+	if (verification.status === "unavailable") {
+		log("The agent cannot verify requests: the runtime key set is unavailable.", verification.reason);
+		return error("unavailable", 503);
+	}
+	if (verification.status !== "valid") {
+		log("The agent refused a request with an invalid runtime token.", verification.reason);
+		return error("unauthorized", 401);
+	}
+}
 function messagesRoute(input) {
-	const log = input.log ?? ((message, detail) => console.warn(message, detail));
 	return POST(MESSAGES_ROUTE, async (request, args) => {
-		if (!input.enabled()) return error("channels_disabled", 503);
-		if (!input.configured()) return error("not_found", 404);
-		const token = bearer(request.headers.get("authorization"));
-		if (token === void 0) return error("unauthorized", 401);
-		let verifier;
-		try {
-			verifier = input.verify();
-		} catch (cause) {
-			log("The agent cannot verify requests: the runtime identity is not configured.", cause);
-			return error("unavailable", 503);
-		}
-		const verification = await verifier(token);
-		if (verification.status === "unavailable") {
-			log("The agent cannot verify requests: the runtime key set is unavailable.", verification.reason);
-			return error("unavailable", 503);
-		}
-		if (verification.status !== "valid") {
-			log("The agent refused a request with an invalid runtime token.", verification.reason);
-			return error("unauthorized", 401);
-		}
+		const failure = await runtimeRequestFailure(request, input);
+		if (failure !== void 0) return failure;
 		let body;
 		try {
 			body = await request.json();
@@ -172,4 +179,4 @@ function messagesRoute(input) {
 		}, { status: 202 });
 	});
 }
-export { MESSAGES_ROUTE, agentRequest, messagesRoute, requestContext, requestPrincipal };
+export { MESSAGES_ROUTE, agentRequest, messagesRoute, requestContext, requestPrincipal, runtimeRequestFailure };

package/dist/extension/tools/attachments_send.d.ts

@@ -0,0 +1,7 @@
+declare const _default: import("eve/tools").ToolDefinition<Record<string, unknown>, {
+    readonly files: ReadonlyArray<import("../lib/telegram/attachments-send.js").SentFile>;
+} | {
+    readonly error: string;
+    readonly detail: string;
+}>;
+export default _default;

package/dist/extension/tools/attachments_send.mjs

@@ -0,0 +1,59 @@
+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 segmentstream from "../extension.mjs";
+import { sendAttachments, sendAttachmentsInput } from "../lib/telegram/attachments-send.mjs";
+import { defineTool } from "eve/tools";
+var attachments_send_default = defineTool({
+	availableInSubagents: false,
+	description: "Send 1 to 10 stored ontology files to this turn's Telegram chat, as the paired member. Bare ids are document record ids; use entity/id/property references for other file records. Images use sendPhoto, other files sendDocument, with compatible albums when possible. Uploads are limited to 2 MiB including multipart overhead by the connection proxy. Use the question as caption when sending documents with a question; one question per message. In groups follow the chat's purpose and never send restricted documents.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			documentIds: {
+				type: "array",
+				minItems: 1,
+				maxItems: 10,
+				items: { anyOf: [{
+					type: "string",
+					description: "A document record id (UUID)."
+				}, {
+					type: "object",
+					properties: {
+						entity: { type: "string" },
+						id: { type: "string" },
+						property: {
+							type: "string",
+							description: "Required when there are multiple file properties."
+						}
+					},
+					required: ["entity", "id"],
+					additionalProperties: false
+				}] }
+			},
+			caption: {
+				type: "string",
+				maxLength: 1024
+			},
+			replyToMessageId: {
+				type: "integer",
+				minimum: 1
+			}
+		},
+		required: ["documentIds"],
+		additionalProperties: false
+	},
+	label: { start: () => "Send stored attachments to Telegram" },
+	execute(input, ctx) {
+		return sendAttachments({
+			input: sendAttachmentsInput(input),
+			principal: ctx.session.auth.current,
+			sessionId: ctx.session.id,
+			connection: segmentstream.config.channels.telegram?.connection
+		});
+	}
+});
+export { attachments_send_default as default };