@segmentstream/agent 0.2.1 → 0.3.1

package/dist/extension/lib/questions.mjs

@@ -0,0 +1,30 @@
+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 { defineState } from "eve/context";
+const pendingQuestions = defineState("segmentstream.pending-questions", () => ({}));
+function questionKey(question) {
+	return JSON.stringify([
+		question.memberId,
+		question.chatId,
+		question.messageThreadId
+	]);
+}
+function isPendingQuestion(value) {
+	return typeof value === "object" && value !== null && [
+		"id",
+		"question",
+		"task",
+		"memberId",
+		"chatId",
+		"messageThreadId",
+		"address"
+	].every((key) => typeof value[key] === "string");
+}
+function answerMarker(id) {
+	return `[Answer to pending question ${id}]`;
+}
+export { answerMarker, isPendingQuestion, pendingQuestions, questionKey };

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

@@ -31,7 +31,7 @@ export interface TelegramAdapterOptions {
     readonly observed?: ObservedMessages;
     /** Verifies callers of the messages route; tests pass one on a local key set. */
     readonly verify?: RuntimeTokenVerifier;
-    /** Reads the tail of a session's durable stream; tests pass a fake. */
+    /** Reads session events for routing, policy and interactions; tests pass a fake. */
     readonly history?: HistoryReader;
     /** The attachment store; tests pass a fake. */
     readonly attachments?: AgentAttachments;

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

@@ -11,14 +11,15 @@ import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
 import { agentIdentities } from "../identities.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 { 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 { withTurnErrorLogging } from "./turn-errors.mjs";
@@ -40,11 +41,22 @@ const eveHistory = async (sessionId) => {
 	});
 	return events;
 };
+const eveInteractions = async (sessionId) => {
+	const { sessions } = await import("eve/server");
+	const events = [];
+	for await (const event of sessions.attach(sessionId).stream({ follow: false })) events.push({
+		type: event.type,
+		meta: { at: event.meta.at },
+		data: event.data
+	});
+	return events;
+};
 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 readInteractions = options.history ?? eveInteractions;
 	const policy = sessionPolicy({
 		settings: options.sessions,
 		read: readHistory
@@ -124,11 +136,22 @@ function segmentstreamTelegram(options) {
 				attachments: attachments(),
 				observed,
 				readHistory,
+				history: readInteractions,
 				chats,
 				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
 			}
 		}),
-		events: { "message.completed": replyDelivery(observed) }
+		onCallbackQuery: (context, query) => handleConfirmationCallback({
+			context,
+			query,
+			identities: pairing(),
+			read: readInteractions,
+			scope: options.sessions().scope
+		}),
+		events: {
+			...confirmationEvents,
+			"message.completed": replyDelivery(observed)
+		}
 	});
 	const adapter = channel.adapter;
 	const fetchTelegramFile = adapter?.fetchFile;
@@ -188,9 +211,13 @@ function gatedRoute(input) {
 				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(scoped(address)), inbound)
+				from: (address) => withReplacedText(args.from(inbound.address ?? scoped(address)), inbound)
 			}));
 		}
 	};

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

@@ -0,0 +1,18 @@
+import type { ChannelEvents } from "eve/channels";
+import type { TelegramCallbackQuery, TelegramChannelEvents, TelegramContext, TelegramEventContext } from "eve/channels/telegram";
+import type { AgentIdentities } from "../identities.js";
+import { type PendingQuestion } from "../questions.js";
+import { type HistoryReader, type RecordedEvent } from "./sessions.js";
+export declare function confirmationCallback(requestId: string, memberId: string, decision: "approve" | "cancel"): 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. */
+export declare function handleConfirmationCallback(input: {
+    readonly context: TelegramContext;
+    readonly query: TelegramCallbackQuery;
+    readonly identities: AgentIdentities;
+    readonly read: HistoryReader;
+    readonly scope: "chat" | "thread";
+    readonly now?: number;
+}): Promise<void>;
+export declare const confirmationEvents: TelegramChannelEvents & Pick<ChannelEvents<TelegramEventContext>, "context.cleared">;

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

@@ -0,0 +1,280 @@
+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 { 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 { formatAddress, scopedAddress } from "./sessions.mjs";
+import { registerTelegramFreeformPrompt, renderTelegramInputRequest } from "eve/channels/telegram";
+import { createHash } from "node:crypto";
+const PREFIX = "ss-confirm:";
+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"}`;
+}
+function object(value) {
+	return typeof value === "object" && value !== null ? value : {};
+}
+function openConfirmations(events) {
+	const open = new Map();
+	for (const event of events) {
+		const data = object(event.data);
+		if (event.type === "context.cleared") open.clear();
+		if (event.type === "input.requested" && Array.isArray(data.requests)) for (const item of data.requests) {
+			const request = object(item);
+			const action = object(request.action);
+			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)
+			});
+		}
+		if (event.type === "input.resolved" && Array.isArray(data.resolutions)) for (const item of data.resolutions) {
+			const id = object(item).requestId;
+			if (typeof id === "string") open.delete(id);
+		}
+	}
+	return [...open.values()];
+}
+function questionFromHistory(events, owner) {
+	const pending = new Map();
+	for (const event of events) {
+		const data = object(event.data);
+		if (event.type === "context.cleared") pending.clear();
+		if (event.type === "action.result") {
+			const result = object(data.result);
+			const candidate = object(result.output).pendingQuestion;
+			if (typeof result.toolName === "string" && result.toolName.endsWith("__questions_ask") && isPendingQuestion(candidate)) pending.set(questionKey(candidate), candidate);
+		}
+		if (event.type === "message.received" && typeof data.message === "string" && data.message.startsWith("[Answer to pending question ")) {
+			for (const [key, question] of pending) if (data.message.startsWith(answerMarker(question.id))) pending.delete(key);
+		}
+	}
+	return owner === void 0 ? [...pending.values()].at(-1) : pending.get(questionKey(owner));
+}
+function questionAddress(owner) {
+	return formatAddress({
+		...owner,
+		conversationId: `question-${shortHash(owner.memberId)}`
+	});
+}
+async function handleConfirmationCallback(input) {
+	const { context, query } = input;
+	const notice = (text) => context.telegram.answerCallbackQuery({
+		callbackQueryId: query.id,
+		text
+	});
+	if (!query.data?.startsWith(PREFIX) || query.message === void 0 || query.from.isBot) {
+		await notice("Unsupported action.");
+		return;
+	}
+	const [requestHash, memberHash, choice] = query.data.slice(11).split(":");
+	const lookup = await input.identities.lookup({
+		provider: "telegram",
+		externalId: query.from.id
+	});
+	if (lookup.status !== "paired" || shortHash(lookup.member.id) !== memberHash) {
+		await notice("Only the requesting member can confirm or cancel this action.");
+		return;
+	}
+	const address = scopedAddress(formatAddress({
+		chatId: query.message.chat.id,
+		messageThreadId: String(query.message.messageThreadId ?? ""),
+		conversationId: query.message.chat.type === "private" ? "" : query.message.messageId
+	}), 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") {
+		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 principal = telegramPrincipal({
+		member: lookup.member,
+		message: {
+			...query.message,
+			from: query.from,
+			text: "",
+			caption: "",
+			raw: {},
+			attachments: []
+		}
+	});
+	const source = currentInboundRequest()?.respond;
+	if (source === void 0) throw new Error("Confirmation callback has no session continuation.");
+	await source(address, prompt.requestId, decision, {
+		...principal,
+		attributes: {
+			...principal.attributes,
+			confirmationRequestId: prompt.requestId,
+			confirmationDecision: decision
+		}
+	});
+	await notice(expired ? "This confirmation expired; nothing executed." : decision === "cancel" ? "Cancellation received." : "Confirmation received.");
+}
+const confirmationEvents = {
+	"context.cleared"(_data, channel) {
+		confirmations.update(() => ({}));
+		pendingQuestions.update(() => ({}));
+		const state = channel.state;
+		state.confirmationMessages = {};
+		state.pendingQuestions = {};
+	},
+	async "input.requested"(data, channel, ctx) {
+		for (const request of data.requests) {
+			if (request.kind !== "tool-approval") {
+				const rendered = renderTelegramInputRequest(request, channel.state);
+				const sent = await channel.telegram.post({
+					text: rendered.text,
+					reply_markup: rendered.replyMarkup
+				});
+				if (rendered.freeformRequestId !== void 0) registerTelegramFreeformPrompt(channel.state, {
+					messageId: sent.id,
+					requestId: request.requestId
+				});
+				else channel.state.hitlPrompts = {
+					...channel.state.hitlPrompts,
+					[request.requestId]: {
+						messageId: sent.id,
+						text: rendered.text,
+						options: (request.options ?? []).map(({ id, label }) => ({
+							id,
+							label
+						}))
+					}
+				};
+				continue;
+			}
+			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 text = `Confirm ${request.action.toolName}?\n${JSON.stringify(request.action.input, null, 2)}`.slice(0, 3900);
+			const sent = await channel.telegram.post({
+				text,
+				reply_markup: { inline_keyboard: [[{
+					text: "Confirm",
+					callback_data: confirmationCallback(request.requestId, memberId, "approve")
+				}, {
+					text: "Cancel",
+					callback_data: confirmationCallback(request.requestId, memberId, "cancel")
+				}]] }
+			});
+			const state = channel.state;
+			state.confirmationMessages = {
+				...state.confirmationMessages,
+				[request.action.callId]: {
+					requestId: request.requestId,
+					messageId: sent.id,
+					text
+				}
+			};
+		}
+	},
+	async "input.resolved"(data, channel) {
+		const state = channel.state;
+		for (const resolution of data.resolutions) {
+			const entry = Object.entries(state.confirmationMessages ?? {}).find(([, message]) => message.requestId === resolution.requestId);
+			if (entry === void 0) {
+				const prompt = channel.state.hitlPrompts?.[resolution.requestId];
+				if (prompt !== void 0) {
+					const response = resolution.response;
+					const label = response?.text ?? prompt.options.find((option) => option.id === response?.optionId)?.label;
+					await channel.telegram.editMessageText({
+						messageId: prompt.messageId,
+						replyMarkup: { inline_keyboard: [] },
+						text: `${prompt.text}\n\n${label ?? resolution.outcome}`
+					});
+					delete channel.state.hitlPrompts?.[resolution.requestId];
+				}
+				continue;
+			}
+			const [callId, message] = entry;
+			const text = resolution.outcome === "approved" ? "Confirmed. Executing…" : "Cancelled. Nothing executed.";
+			await channel.telegram.editMessageText({
+				messageId: message.messageId,
+				replyMarkup: { inline_keyboard: [] },
+				text: `${message.text}\n\n${text}`
+			});
+			if (resolution.outcome !== "approved") {
+				delete state.confirmationMessages?.[callId];
+				confirmations.update((all) => ({
+					...all,
+					...all[callId] === void 0 ? {} : { [callId]: {
+						...all[callId],
+						status: "cancelled"
+					} }
+				}));
+			}
+		}
+	},
+	async "action.result"(data, channel) {
+		const state = channel.state;
+		if (data.result.kind === "tool-result") {
+			const question = object(data.result.output).pendingQuestion;
+			if (data.result.toolName.endsWith("__questions_ask") && isPendingQuestion(question)) {
+				const address = channel.continuation?.token ?? formatAddress({
+					chatId: channel.telegram.chatId,
+					messageThreadId: String(channel.telegram.messageThreadId ?? ""),
+					conversationId: channel.telegram.conversationId ?? ""
+				});
+				const saved = {
+					...question,
+					address
+				};
+				pendingQuestions.update((all) => ({
+					...all,
+					[questionKey(saved)]: saved
+				}));
+				state.pendingQuestions = {
+					...state.pendingQuestions,
+					[questionKey(saved)]: saved
+				};
+				channel.continuation?.alias(formatAddress({
+					chatId: question.chatId,
+					messageThreadId: question.messageThreadId,
+					conversationId: ""
+				}));
+				channel.continuation?.alias(questionAddress(saved));
+				await channel.telegram.post({
+					text: question.question,
+					reply_markup: {
+						force_reply: true,
+						selective: true
+					}
+				});
+			}
+		}
+		const message = state.confirmationMessages?.[data.result.callId];
+		if (message === void 0) return;
+		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);
+		const result = data.result.kind === "tool-result" ? JSON.stringify(data.result.output) : "";
+		await channel.telegram.editMessageText({
+			messageId: message.messageId,
+			replyMarkup: { inline_keyboard: [] },
+			text: `${message.text}\n\n${failed ? "Failed" : "Completed"}: ${result}`.slice(0, 4096)
+		});
+		delete state.confirmationMessages?.[data.result.callId];
+	},
+	"turn.started"(_data, channel, ctx) {
+		const memberId = memberIdOf(ctx.session.auth.current);
+		const answeredId = ctx.session.auth.current?.attributes.pendingQuestionId;
+		if (memberId !== void 0 && typeof answeredId === "string") {
+			const key = questionKey({
+				memberId,
+				chatId: channel.telegram.chatId,
+				messageThreadId: String(channel.telegram.messageThreadId ?? "")
+			});
+			if (pendingQuestions.get()[key]?.id === answeredId) {
+				pendingQuestions.update((all) => Object.fromEntries(Object.entries(all).filter(([name]) => name !== key)));
+				delete channel.state.pendingQuestions?.[key];
+			}
+		}
+	}
+};
+export { confirmationCallback, confirmationEvents, handleConfirmationCallback, questionAddress, questionFromHistory };

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

@@ -1,4 +1,5 @@
 import type { ChannelSource } from "eve/channels";
+import type { SessionAuthContext } from "eve/context";
 import type { Attachment } from "../attachments.js";
 import type { SessionOperations } from "./sessions.js";
 /** What became of one Telegram file of the message: stored as an attachment, or why not. */
@@ -32,6 +33,9 @@ export declare class InboundRequest {
     sessions: SessionOperations | undefined;
     /** Keeps work the request started, such as a chat report, alive after it answers. */
     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;
     constructor(
     /** The agent's description from the compiled manifest, for the routing decision. */
     agentDescription: () => Promise<string>);

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

@@ -11,6 +11,8 @@ var InboundRequest = class {
 	files;
 	sessions;
 	waitUntil;
+	address;
+	respond;
 	constructor(agentDescription) {
 		this.agentDescription = agentDescription;
 	}

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

@@ -38,11 +38,14 @@ export interface InboundDependencies {
     readonly identities: AgentIdentities;
     readonly bot: BotIdentityLookup;
     readonly decide: RouteDecider;
+    /** Full session history for open questions, which can survive compaction. */
+    readonly history?: HistoryReader;
     readonly transcribe: Transcriber;
     readonly download: (fileId: string) => Promise<Uint8Array>;
     /** The attachment store; without it, files reach the turn as eve's Telegram file parts. */
     readonly attachments?: AgentAttachments;
     readonly observed: ObservedMessages;
+    /** Recent session events for smart routing. */
     readonly readHistory: HistoryReader;
     readonly chats: AgentChats;
     /** The app's `/agent/connect` link for a pairing code. */

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

@@ -5,12 +5,14 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { telegramPrincipal } from "./principal.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 { 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.";
 const UNKNOWN_IN_GROUP = "I don't know you yet. Message me privately to connect your account.";
@@ -184,13 +186,32 @@ async function handleInboundMessage(input) {
 		});
 		return null;
 	}
-	const address = scopedAddress(messageAddress(sent), dependencies.sessions().scope);
+	let address = scopedAddress(messageAddress(sent), dependencies.sessions().scope);
 	const operations = input.request?.sessions;
+	const topicAddress = formatAddress({
+		chatId: sent.chat.id,
+		messageThreadId: String(sent.messageThreadId ?? ""),
+		conversationId: ""
+	});
+	const questionOwner = {
+		memberId: lookup.member.id,
+		chatId: sent.chat.id,
+		messageThreadId: String(sent.messageThreadId ?? "")
+	};
+	const memberQuestionAddress = questionAddress(questionOwner);
+	const questionSession = await operations?.resolveSession(memberQuestionAddress);
+	const owner = questionSession ?? await operations?.resolveSession(address) ?? await operations?.resolveSession(topicAddress);
+	const pending = owner === void 0 || dependencies.history === void 0 ? void 0 : questionFromHistory(await dependencies.history(owner.id), questionOwner);
+	let answering = pending !== void 0 && pending.memberId === lookup.member.id && pending.chatId === sent.chat.id && pending.messageThreadId === String(sent.messageThreadId ?? "");
+	if (answering && pending !== void 0 && input.request !== void 0) {
+		address = pending.address || (questionSession === void 0 ? topicAddress : memberQuestionAddress);
+		input.request.address = address;
+	}
 	const voice = voiceOf(sent.raw);
 	const caption = sent.text || sent.caption;
 	const notes = [];
 	let text = caption;
-	if (voice !== void 0 && (addressed !== void 0 || dependencies.policy === "smart")) {
+	if (voice !== void 0 && (addressed !== void 0 || answering || dependencies.policy === "smart")) {
 		const spoken = await voiceText({
 			voice,
 			model: dependencies.sttModel,
@@ -209,7 +230,7 @@ async function handleInboundMessage(input) {
 		chatId: sent.chat.id,
 		memberId: lookup.member.id,
 		policy: dependencies.policy,
-		addressed,
+		addressed: addressed ?? (answering ? "pending-question" : void 0),
 		decide: dependencies.decide,
 		question: async () => {
 			const recent = await routingContext({
@@ -231,13 +252,26 @@ async function handleInboundMessage(input) {
 	}
 	if (voice !== void 0 && input.request !== void 0) input.request.text = text;
 	else if (voice !== void 0) notes.push(text);
+	if (answering && pending !== void 0 && input.request !== void 0) {
+		input.request.text = `${answerMarker(pending.id)}\n${text}`;
+		notes.push(`<pending_question>\nTask: ${pending.task}\nQuestion: ${pending.question}\nUse this member's answer to continue the pending task with their current permissions.
+</pending_question>`);
+	}
 	if (operations !== void 0) {
 		const newest = dependencies.observed.list(chat).at(-1);
 		if (await dependencies.sessionPolicy.apply({
 			address,
 			operations,
 			...newest === void 0 ? {} : { activeAt: Date.parse(newest.at) || 0 }
-		}) === "cleared") dependencies.observed.clear(chat);
+		}) === "cleared") {
+			dependencies.observed.clear(chat);
+			if (answering && input.request !== void 0) {
+				answering = false;
+				input.request.text = text;
+				const questionNote = notes.findIndex((note) => note.startsWith("<pending_question>"));
+				if (questionNote !== -1) notes.splice(questionNote, 1);
+			}
+		}
 		dependencies.sessionPolicy.delivered(address);
 	}
 	await context.telegram.startTyping();
@@ -250,11 +284,18 @@ 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));
+	const principal = telegramPrincipal({
+		message: sent,
+		member: lookup.member
+	});
 	return {
-		auth: telegramPrincipal({
-			message: sent,
-			member: lookup.member
-		}),
+		auth: answering && pending !== void 0 ? {
+			...principal,
+			attributes: {
+				...principal.attributes,
+				pendingQuestionId: pending.id
+			}
+		} : principal,
 		context: [
 			...observedContext(dependencies.observed.take(chat)),
 			...group ? chatContext(dependencies.chats.chat(sent.chat.id)) : [],

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

@@ -18,6 +18,7 @@ function telegramPrincipal(input) {
 		chatType: message.chat.type
 	};
 	if (member.name !== null) attributes.memberName = member.name;
+	if (message.messageThreadId !== void 0) attributes.messageThreadId = String(message.messageThreadId);
 	if (message.from.username !== void 0) attributes.username = message.from.username;
 	return {
 		authenticator: TELEGRAM_AUTHENTICATOR,

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

@@ -87,7 +87,9 @@ function requestContext(request) {
 	const lines = [
 		"<agent_request>",
 		`A request from ${requester.name} (${requester.kind}, user_id ${requester.id}) arrived through the ontology action agent_chat.send_message; the message is the request.`,
-		`Write in this chat${to}, ask what the request needs, and handle the replies here.`
+		"This turn already runs in the target chat. Your reply here is the message delivered to this chat. Do not look for or call agent_chat.send_message to deliver it, even if the ontology catalog is empty or that action is unavailable.",
+		`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 (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>");

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

@@ -8,7 +8,7 @@ import type { ObservedMessage, RecentMessage } 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";
+export type AddressingReason = "private" | "mention" | "reply-to-bot" | "command" | "pending-question";
 /** The bot, as Telegram's `getMe` describes it. Unknown when `getMe` failed. */
 export interface BotIdentity {
     readonly id: string;

package/dist/extension/lib/telegram/routing-context.mjs

@@ -23,8 +23,8 @@ async function routingContext(input) {
 				resetAt = Date.parse(event.meta.at);
 			}
 			const age = sentAt - Date.parse(event.meta.at);
-			const data = event.data;
-			if (event.type === "message.completed" && data !== void 0 && data.finishReason !== "tool-calls" && data.message.trim() !== "" && !isSilentReply(data.message) && age >= 0 && age <= 18e5) recovered.push(agentMessage({
+			const data = typeof event.data === "object" && event.data !== null ? event.data : void 0;
+			if (event.type === "message.completed" && data !== void 0 && typeof data.message === "string" && typeof data.finishReason === "string" && data.finishReason !== "tool-calls" && data.message.trim() !== "" && !isSilentReply(data.message) && age >= 0 && age <= 18e5) recovered.push(agentMessage({
 				text: data.message,
 				at: event.meta.at
 			}));

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

@@ -37,19 +37,16 @@ export interface SessionHistory {
     /** Turns completed since `resetAt`; a compaction is worth nothing before the first. */
     readonly turnsSinceReset: number;
 }
-/** One recorded event, as much of eve's envelope as the policy reads. */
+/** One recorded event used by session policy, routing context and interaction projections. */
 export interface RecordedEvent {
     readonly type: string;
     readonly meta: {
         readonly at: string;
     };
-    /** Visible assistant message content, also used to recover smart-routing context. */
-    readonly data?: {
-        readonly message: string;
-        readonly finishReason: string;
-    };
+    /** Consumers validate the payload for the event type they project. */
+    readonly data?: unknown;
 }
-/** The last events of a session, oldest first. Production reads eve's durable stream. */
+/** Session events, oldest first; readers choose a tail or full stream for their consumers. */
 export type HistoryReader = (sessionId: string) => Promise<ReadonlyArray<RecordedEvent>>;
 /** How many events of the tail the reader fetches: enough for a day of a busy group. */
 export declare const HISTORY_TAIL = 400;

package/dist/extension/tools/attachments_promote.mjs

@@ -4,9 +4,12 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { actionApproval } from "../lib/confirmations.mjs";
+import { actionToolName, ontologyToolLabels } from "../lib/ontology-tools.mjs";
 import { attachmentForModel, attachmentOwner, optionalObject, optionalString, stringArgument, toolAttachments } from "../lib/attachment-tools.mjs";
 import { defineTool } from "eve/tools";
 var attachments_promote_default = defineTool({
+	approval: actionApproval({ labels: (memberId, _tool, input) => ontologyToolLabels()(memberId, actionToolName(stringArgument(input, "entity"), stringArgument(input, "action"))) }),
 	description: "Keep a file the member sent by storing it in a record through an ontology action that takes a file, such as document.upload. Give the entity, the action and the action's input without the file field: the platform fills it with the attachment, and fills sha256 when the action takes one. Runs with the member's permissions. The same file promoted again through the same action returns the earlier result instead of a duplicate.",
 	inputSchema: {
 		type: "object",