@segmentstream/agent 0.5.4 → 0.6.3

package/dist/extension/lib/telegram/chat-post-card.mjs

@@ -0,0 +1,65 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { AsyncLocalStorage } from "node:async_hooks";
+const MAX_PREVIEW_LENGTH = 3584;
+const exactText = new AsyncLocalStorage();
+function withChatPostCard(text, run) {
+	if (text.length > 4096) throw new Error("The complete chat confirmation cannot fit in one Telegram message.");
+	return exactText.run(text, run);
+}
+function isExactChatPostCard(text) {
+	return exactText.getStore() === text;
+}
+function chatPostCopy(locale) {
+	return locale.startsWith("ru") ? {
+		edit: "Изменить",
+		changes: "Что изменить в сообщении?",
+		uncertain: "Неизвестно, отправлено ли сообщение. Не отправляйте его повторно автоматически.",
+		sent: "Отправлено.",
+		history: "Не удалось записать квитанцию в историю.",
+		expired: "Срок подтверждения истёк. Ничего не отправлено."
+	} : {
+		edit: "Edit",
+		changes: "What would you like to change in the message?",
+		uncertain: "Delivery is uncertain. Do not resend automatically.",
+		sent: "Sent.",
+		history: "The receipt could not be recorded in history.",
+		expired: "This confirmation expired. Nothing was sent."
+	};
+}
+function chatPostCard(preview, locale) {
+	const russian = locale.startsWith("ru");
+	const text = [
+		russian ? "Отправить сообщение?" : "Send message?",
+		`${russian ? "Чат" : "Chat"}: ${preview.title} (${preview.provider})`,
+		...preview.replyTo === null ? [] : [`${russian ? "В ответ на" : "Reply to"}: ${preview.replyTo}`],
+		"",
+		preview.finalText
+	].join("\n");
+	if (text.length > MAX_PREVIEW_LENGTH) throw new Error("The full message and receipt cannot fit in one Telegram confirmation. Make a shorter draft.");
+	return {
+		text,
+		confirm: russian ? "Отправить" : "Confirm",
+		cancel: russian ? "Отмена" : "Cancel",
+		executing: russian ? "Подтверждено." : "Confirmed.",
+		cancelled: russian ? "Отменено." : "Cancelled.",
+		completed: chatPostCopy(locale).sent,
+		failed: russian ? "Ошибка отправки сообщения." : "Chat posting failed."
+	};
+}
+function chatPostReceipt(output, locale) {
+	const value = typeof output === "object" && output !== null ? output : {};
+	if (value.status !== "sent" && value.status !== "uncertain" || typeof value.history_recorded !== "boolean" || typeof value.duplicate !== "boolean" || value.message_id !== null && typeof value.message_id !== "string" || value.url !== null && typeof value.url !== "string") return;
+	const copy = chatPostCopy(locale);
+	const url = typeof value.url === "string" && value.url.length <= 256 && /^https:\/\/t\.me\/[A-Za-z0-9_/-]+$/u.test(value.url) ? value.url : null;
+	return [
+		value.status === "sent" ? copy.sent : copy.uncertain,
+		...url === null ? [] : [url],
+		...value.history_recorded ? [] : [copy.history]
+	].join("\n");
+}
+export { chatPostCard, chatPostCopy, chatPostReceipt, isExactChatPostCard, withChatPostCard };

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

@@ -1,10 +1,11 @@
 import type { ChannelEvents } from "eve/channels";
 import type { TelegramCallbackQuery, TelegramChannelEvents, TelegramContext, TelegramEventContext } from "eve/channels/telegram";
+import { type Conversations } from "../conversations.js";
 import type { AgentIdentities } from "../identities.js";
 import { type PendingQuestion } from "../questions.js";
 import { type ConfirmationRenderer } from "./confirmation-text.js";
 import { type HistoryReader, type RecordedEvent } from "./sessions.js";
-export declare function confirmationCallback(requestId: string, memberId: string, decision: "approve" | "cancel"): string;
+export declare function confirmationCallback(requestId: string, memberId: string, decision: "approve" | "cancel" | "edit"): string;
 export declare function questionFromHistory(events: readonly RecordedEvent[], owner?: Pick<PendingQuestion, "memberId" | "chatId" | "messageThreadId">): PendingQuestion | undefined;
 export declare function questionAddress(owner: Pick<PendingQuestion, "memberId" | "chatId" | "messageThreadId">): string;
 /** Custom callback data avoids Eve's default, unpaired Telegram callback principal. */
@@ -16,5 +17,5 @@ export declare function handleConfirmationCallback(input: {
     readonly scope: "chat" | "thread";
     readonly now?: number;
 }): Promise<void>;
-export declare function telegramConfirmationEvents(render?: ConfirmationRenderer): TelegramChannelEvents & Pick<ChannelEvents<TelegramEventContext>, "context.cleared">;
+export declare function telegramConfirmationEvents(render?: ConfirmationRenderer, archive?: Conversations): TelegramChannelEvents & Pick<ChannelEvents<TelegramEventContext>, "context.cleared">;
 export declare const confirmationEvents: TelegramChannelEvents & Pick<ChannelEvents<TelegramEventContext>, "context.cleared">;

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

@@ -5,7 +5,10 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { conversationLanguage, memberIdOf, telegramPrincipal } from "./principal.mjs";
+import { chatPostOperationId, isChatPost } from "../chat-post-confirmation.mjs";
+import { chatPostCard, chatPostCopy, chatPostReceipt, withChatPostCard } from "./chat-post-card.mjs";
 import { confirmations } from "../confirmations.mjs";
+import { conversationEvent } from "../conversations.mjs";
 import { currentInboundRequest } from "./inbound-request.mjs";
 import { currentLocale, failureText, reportTelegramError } from "./customer-text.mjs";
 import { answerMarker, isPendingQuestion, pendingQuestions, questionKey } from "../questions.mjs";
@@ -18,7 +21,8 @@ function shortHash(value) {
 	return createHash("sha256").update(value).digest("hex").slice(0, 20);
 }
 function confirmationCallback(requestId, memberId, decision) {
-	return `${PREFIX}${shortHash(requestId)}:${shortHash(memberId)}:${decision === "approve" ? "y" : "n"}`;
+	const choice = decision === "approve" ? "y" : decision === "edit" ? "e" : "n";
+	return `${PREFIX}${shortHash(requestId)}:${shortHash(memberId)}:${choice}`;
 }
 function object(value) {
 	return typeof value === "object" && value !== null ? value : {};
@@ -34,7 +38,9 @@ function openConfirmations(events) {
 			if (request.kind === "tool-approval" && typeof request.requestId === "string" && typeof action.callId === "string") open.set(request.requestId, {
 				requestId: request.requestId,
 				callId: action.callId,
-				at: Date.parse(event.meta.at)
+				at: Date.parse(event.meta.at),
+				toolName: String(action.toolName ?? ""),
+				input: object(action.input)
 			});
 		}
 		if (event.type === "input.resolved" && Array.isArray(data.resolutions)) for (const item of data.resolutions) {
@@ -49,6 +55,10 @@ function questionFromHistory(events, owner) {
 	for (const event of events) {
 		const data = object(event.data);
 		if (event.type === "context.cleared") pending.clear();
+		if (event.type === "input.resolved" && Array.isArray(data.resolutions)) for (const resolution of data.resolutions) {
+			const question = chatPostEditQuestion(object(resolution));
+			if (question !== void 0) pending.set(questionKey(question), question);
+		}
 		if (event.type === "action.result") {
 			const result = object(data.result);
 			const candidate = object(result.output).pendingQuestion;
@@ -60,6 +70,16 @@ function questionFromHistory(events, owner) {
 	}
 	return owner === void 0 ? [...pending.values()].at(-1) : pending.get(questionKey(owner));
 }
+function chatPostEditQuestion(resolution) {
+	const text = object(resolution.response).text;
+	if (resolution.outcome !== "cancelled" || typeof text !== "string") return;
+	try {
+		const question = object(JSON.parse(text)).pendingChatPostEdit;
+		return isPendingQuestion(question) ? question : void 0;
+	} catch {
+		return;
+	}
+}
 function questionAddress(owner) {
 	return formatAddress({
 		...owner,
@@ -111,12 +131,17 @@ async function handleConfirmationCallback(input) {
 	}), input.scope);
 	const session = await (currentInboundRequest()?.sessions)?.resolveSession(address);
 	const prompt = session === void 0 ? void 0 : openConfirmations(await input.read(session.id)).find((candidate) => shortHash(candidate.requestId) === requestHash);
-	if (prompt === void 0 || choice !== "y" && choice !== "n") {
+	if (prompt === void 0 || ![
+		"y",
+		"n",
+		"e"
+	].includes(choice ?? "") || choice === "e" && !isChatPost(prompt.toolName)) {
 		await notice("This confirmation is no longer pending.");
 		return;
 	}
 	const expired = !Number.isFinite(prompt.at) || prompt.at + 6e5 <= (input.now ?? Date.now());
-	const decision = expired || choice === "n" ? "cancel" : "approve";
+	const decision = expired || choice !== "y" ? "cancel" : "approve";
+	const edit = !expired && choice === "e";
 	const principal = telegramPrincipal({
 		member: lookup.member,
 		message: {
@@ -130,17 +155,58 @@ async function handleConfirmationCallback(input) {
 	});
 	const source = currentInboundRequest()?.respond;
 	if (source === void 0) throw new Error("Confirmation callback has no session continuation.");
+	const editQuestion = edit ? {
+		id: `edit-${prompt.callId}`,
+		memberId: lookup.member.id,
+		chatId: query.message.chat.id,
+		messageThreadId: String(query.message.messageThreadId ?? ""),
+		address,
+		question: chatPostCopy(language).changes,
+		task: `The previous chat post was cancelled for editing. Apply the member's changes to this draft, then make a NEW chat_post_message call and confirmation. Never reuse the cancelled call. Previous input: ${JSON.stringify(prompt.input)}`
+	} : void 0;
 	await source(address, prompt.requestId, decision, {
 		...principal,
 		attributes: {
 			...principal.attributes,
 			confirmationRequestId: prompt.requestId,
-			confirmationDecision: decision
+			confirmationDecision: decision,
+			...expired ? { confirmationReason: "expired" } : edit ? { confirmationReason: "edit" } : {}
 		}
-	});
+	}, editQuestion === void 0 ? void 0 : JSON.stringify({ pendingChatPostEdit: editQuestion }));
 	await notice(expired ? "This confirmation expired; nothing executed." : decision === "cancel" ? "Cancellation received." : "Confirmation received.");
 }
-function telegramConfirmationEvents(render = async (description, locale) => fallbackConfirmation(description, locale)) {
+function telegramConfirmationEvents(render = async (description, locale) => fallbackConfirmation(description, locale), archive) {
+	const record = async (callId, phase, text, status, ctx) => {
+		const saved = confirmations.get()[callId];
+		if (archive === void 0 || saved?.description?.chatPost === void 0 || saved.source === void 0) return;
+		const operationId = chatPostOperationId(ctx.session.id, callId);
+		const source = saved.source;
+		const append = () => archive.append(conversationEvent({
+			eventId: `chat-post:${operationId}:${phase}`,
+			provider: "telegram",
+			chatId: source.chatId,
+			chatType: source.chatId.startsWith("-") ? "group" : "private",
+			threadId: source.threadId || null,
+			participantIds: [saved.memberId],
+			kind: "tool_result",
+			operationId,
+			toolCallId: operationId,
+			toolName: saved.action,
+			sessionId: ctx.session.id,
+			text,
+			status,
+			reason: phase
+		}));
+		if (phase === "preview") await append();
+		else try {
+			await append();
+		} catch (error) {
+			reportTelegramError("chat_post_source_archive_failed", error, {
+				operationId,
+				phase
+			});
+		}
+	};
 	return {
 		"context.cleared"(_data, channel) {
 			confirmations.update(() => ({}));
@@ -176,18 +242,30 @@ function telegramConfirmationEvents(render = async (description, locale) => fall
 				}
 				const memberId = confirmations.get()[request.action.callId]?.memberId ?? memberIdOf(ctx.session.auth.current);
 				if (memberId === void 0) throw new Error("Confirmation requires a member.");
-				const copy = await render(confirmations.get()[request.action.callId]?.description, confirmationLocale(ctx.session.auth.current));
+				const description = confirmations.get()[request.action.callId]?.description;
+				const exactPost = isChatPost(request.action.toolName);
+				if (exactPost && description?.chatPost === void 0) throw new Error("An exact chat post cannot show a generic confirmation.");
+				const copy = description?.chatPost === void 0 ? await render(description, confirmationLocale(ctx.session.auth.current)) : chatPostCard(description.chatPost, confirmationLocale(ctx.session.auth.current));
 				const text = copy.text;
-				const sent = await channel.telegram.post({
+				await record(request.action.callId, "preview", text, "requested", ctx);
+				const send = () => channel.telegram.post({
 					text,
-					reply_markup: { inline_keyboard: [[{
-						text: copy.confirm,
-						callback_data: confirmationCallback(request.requestId, memberId, "approve")
-					}, {
-						text: copy.cancel,
-						callback_data: confirmationCallback(request.requestId, memberId, "cancel")
-					}]] }
+					reply_markup: { inline_keyboard: [[
+						{
+							text: copy.confirm,
+							callback_data: confirmationCallback(request.requestId, memberId, "approve")
+						},
+						...exactPost ? [{
+							text: chatPostCopy(confirmationLocale(ctx.session.auth.current)).edit,
+							callback_data: confirmationCallback(request.requestId, memberId, "edit")
+						}] : [],
+						{
+							text: copy.cancel,
+							callback_data: confirmationCallback(request.requestId, memberId, "cancel")
+						}
+					]] }
 				});
+				const sent = await (exactPost ? withChatPostCard(text, send) : send());
 				const state = channel.state;
 				state.confirmationMessages = {
 					...state.confirmationMessages,
@@ -196,7 +274,8 @@ function telegramConfirmationEvents(render = async (description, locale) => fall
 						messageId: sent.id,
 						text,
 						copy,
-						locale: confirmationLocale(ctx.session.auth.current)
+						locale: confirmationLocale(ctx.session.auth.current),
+						exactPost
 					}
 				};
 			}
@@ -221,12 +300,39 @@ function telegramConfirmationEvents(render = async (description, locale) => fall
 				}
 				const [callId, message] = entry;
 				const copy = message.copy ?? confirmationCopy(message.locale ?? confirmationLocale(ctx.session.auth.current, currentLocale()));
-				const text = resolution.outcome === "approved" ? copy.executing : copy.cancelled;
-				await channel.telegram.editMessageText({
+				const reason = confirmations.get()[callId]?.cancellationReason;
+				const status = resolution.outcome === "approved" ? copy.executing : reason === "expired" ? chatPostCopy(message.locale ?? "en").expired : copy.cancelled;
+				const text = message.exactPost ? `${message.text}\n\n${status}` : status;
+				const edit = () => channel.telegram.editMessageText({
 					messageId: message.messageId,
 					replyMarkup: { inline_keyboard: [] },
 					text
 				});
+				await (message.exactPost ? withChatPostCard(text, edit) : edit());
+				await record(callId, reason ?? resolution.outcome, text, resolution.outcome === "approved" ? "completed" : "cancelled", ctx);
+				const question = chatPostEditQuestion(resolution);
+				if (message.exactPost && reason === "edit" && question !== void 0) {
+					pendingQuestions.update((all) => ({
+						...all,
+						[questionKey(question)]: question
+					}));
+					state.pendingQuestions = {
+						...state.pendingQuestions,
+						[questionKey(question)]: question
+					};
+					channel.continuation?.alias(questionAddress(question));
+					channel.continuation?.alias(formatAddress({
+						...question,
+						conversationId: ""
+					}));
+					await channel.telegram.post({
+						text: question.question,
+						reply_markup: {
+							force_reply: true,
+							selective: true
+						}
+					});
+				}
 				if (resolution.outcome !== "approved") {
 					delete state.confirmationMessages?.[callId];
 					confirmations.update((all) => ({
@@ -239,7 +345,7 @@ function telegramConfirmationEvents(render = async (description, locale) => fall
 				}
 			}
 		},
-		async "action.result"(data, channel) {
+		async "action.result"(data, channel, ctx) {
 			const state = channel.state;
 			if (data.result.kind === "tool-result") {
 				const question = object(data.result.output).pendingQuestion;
@@ -278,7 +384,20 @@ function telegramConfirmationEvents(render = async (description, locale) => fall
 			}
 			const message = state.confirmationMessages?.[data.result.callId];
 			if (message === void 0) return;
-			if (data.status !== "completed" || data.result.kind === "tool-result" && (data.result.isError === true || object(data.result.output).isError === true || object(object(data.result.output).validation).ok === false)) {
+			const failed = data.status !== "completed" || data.result.kind === "tool-result" && (data.result.isError === true || object(data.result.output).isError === true || object(object(data.result.output).validation).ok === false);
+			if (message.exactPost) {
+				const locale = message.locale ?? currentLocale();
+				const receipt = !failed && data.result.kind === "tool-result" ? chatPostReceipt(data.result.output, locale) : void 0;
+				const errorId = failed ? reportTelegramError("confirmed_chat_post_failed", data, { callId: data.result.callId }) : void 0;
+				const status = receipt ?? (failed ? `${message.copy?.failed ?? "Chat posting failed."} ${errorId}\n${chatPostCopy(locale).uncertain}` : chatPostCopy(locale).uncertain);
+				const text = `${message.text}\n\n${status}`;
+				await withChatPostCard(text, () => channel.telegram.editMessageText({
+					messageId: message.messageId,
+					replyMarkup: { inline_keyboard: [] },
+					text
+				}));
+				await record(data.result.callId, "receipt", text, failed ? "failed" : object(data.result.kind === "tool-result" ? data.result.output : void 0).status === "sent" ? "completed" : "unknown", ctx);
+			} else if (failed) {
 				const errorId = reportTelegramError("confirmed_action_failed", data, { callId: data.result.callId });
 				await channel.telegram.editMessageText({
 					messageId: message.messageId,

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

@@ -4,6 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { isExactChatPostCard } from "./chat-post-card.mjs";
 import { redactDiagnostic } from "../diagnostics.mjs";
 import { currentInboundRequest } from "./inbound-request.mjs";
 import { randomBytes } from "node:crypto";
@@ -97,7 +98,7 @@ function safeTelegramFetch(fetchImpl) {
 		const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
 		if (!methods.has(url.split("/").at(-1) ?? "") || typeof init?.body !== "string") return fetchImpl(input, init);
 		const body = JSON.parse(init.body);
-		for (const field of ["text", "caption"]) if (typeof body[field] === "string") body[field] = customerText(body[field]);
+		for (const field of ["text", "caption"]) if (typeof body[field] === "string" && !isExactChatPostCard(body[field])) body[field] = customerText(body[field]);
 		if (Array.isArray(body.media)) body.media = body.media.map((item) => ({
 			...item,
 			...typeof item.caption === "string" ? { caption: customerText(item.caption) } : {}

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

@@ -4,7 +4,7 @@ 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 { runtimeRequestFailure } from "./runtime-request.mjs";
 import { GET } from "eve/channels";
 const HEALTH_ROUTE = "/eve/v1/telegram/health";
 function healthRoute(input) {

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

@@ -42,7 +42,7 @@ export declare class InboundRequest {
     waitUntil: ((task: Promise<unknown>) => void) | undefined;
     /** Continues the exact pending question's session, including under thread scope. */
     address: string | undefined;
-    respond: ((address: string, requestId: string, decision: "approve" | "cancel", principal: SessionAuthContext) => Promise<unknown>) | undefined;
+    respond: ((address: string, requestId: string, decision: "approve" | "cancel", principal: SessionAuthContext, text?: string) => Promise<unknown>) | undefined;
     constructor(
     /** The agent's description from the compiled manifest, for the routing decision. */
     agentDescription: () => Promise<string>);

package/dist/extension/lib/telegram/runtime-request.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeTokenVerifier } from "../runtime-identity.js";
+/** 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>;

package/dist/extension/lib/telegram/runtime-request.mjs

@@ -0,0 +1,36 @@
+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 bearer(header) {
+	return (header === null ? null : /^Bearer\s+(\S+)$/i.exec(header.trim()))?.[1];
+}
+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);
+	}
+}
+export { runtimeRequestFailure };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.5.4",
+  "version": "0.6.3",
   "description": "Mount a SegmentStream workspace's agent on eve: the ontology as tools, acting as the member who writes, and Telegram through the workspace's connection.",
   "license": "Apache-2.0",
   "author": "SegmentStream",

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

@@ -1,80 +0,0 @@
-import { type RouteDefinition } from "eve/channels";
-import type { TelegramChannel, TelegramChannelState } from "eve/channels/telegram";
-import type { SessionAuthContext } from "eve/context";
-import type { SessionSettings } from "../../config.js";
-import type { RuntimeTokenVerifier } from "../runtime-identity.js";
-import { type SessionPolicy } from "./sessions.js";
-/**
- * Requests from the ontology's `agent_chat.send_message` action: an external agent or a member asks
- * the workspace agent to contact someone in a group or a private chat. The ontology service resolves
- * the chat and posts here with its own Vercel OIDC token; the request is delivered into the chat's
- * session through eve's proactive `receive`, without a seed message, so it continues the session
- * the chat's own messages reach (`chatId::`, the chat-scope address) and the replies land there too.
- * The session policy runs on that session first, as it does for an inbound message.
- */
-export declare const MESSAGES_ROUTE = "/eve/v1/telegram/messages";
-export interface AgentRequest {
-    readonly target: {
-        readonly kind: "group" | "private";
-        readonly provider: "telegram";
-        /** The group's chat id, or the Telegram user id of a private chat. */
-        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;
-        readonly name: string;
-    } | null;
-    readonly requester: {
-        readonly id: string;
-        readonly name: string;
-        readonly kind: "member" | "service";
-        /** The roles the requester holds; empty from an ontology that does not send them. */
-        readonly roles: ReadonlyArray<string>;
-        /**
-         * Whether the turn can act as the requester: a member with a live paired identity. An ontology
-         * that does not send it means a member can.
-         */
-        readonly actAs: boolean;
-    };
-}
-/** The request body, or `undefined` when it does not match the contract. */
-export declare function agentRequest(value: unknown): AgentRequest | undefined;
-/**
- * Whom the request's turn runs as. A member requester the ontology says can be acted as is the
- * turn's member, so the ontology connection acts as them and the ontology service checks, as for any
- * turn, that they are active and paired. Their roles, as the action's principal held them, choose the
- * model of a session the request starts; the service resolves them afresh on every call. A service
- * user, or a member who has not paired, cannot be acted as, so the request runs without a member and
- * the turn has no ontology; their roles still choose the model, and grant nothing, since the
- * ontology connection acts only for a `memberId`.
- */
-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
- * project, verified from its Vercel OIDC token.
- */
-export declare function messagesRoute(input: {
-    readonly channel: TelegramChannel;
-    readonly enabled: () => boolean;
-    readonly configured: () => boolean;
-    readonly verify: () => RuntimeTokenVerifier;
-    /** The adapter's session policy, which the webhook route applies too. */
-    readonly sessionPolicy: SessionPolicy;
-    /** The mounted `sessions.scope`. */
-    readonly scope: () => SessionSettings["scope"];
-    readonly log?: (message: string, detail: unknown) => void;
-}): RouteDefinition<TelegramChannelState>;