@segmentstream/agent 0.3.0 → 0.4.0

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

@@ -0,0 +1,287 @@
+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 { 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);
+	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/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,15 @@ 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 { 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.";
@@ -141,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,
@@ -150,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 ?? ""
@@ -175,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,
@@ -184,13 +190,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,
@@ -200,16 +225,19 @@ 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,
-		addressed,
+		addressed: addressed ?? (answering ? "pending-question" : void 0),
 		decide: dependencies.decide,
 		question: async () => {
 			const recent = await routingContext({
@@ -225,19 +253,34 @@ 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;
 	}
 	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 +293,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",

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

@@ -0,0 +1,12 @@
+declare const _default: import("eve/tools").ToolDefinition<Record<string, unknown>, {
+    pendingQuestion: {
+        id: string;
+        question: string;
+        task: string;
+        memberId: string;
+        chatId: string;
+        messageThreadId: string;
+        address: string;
+    };
+}>;
+export default _default;

package/dist/extension/tools/questions_ask.mjs

@@ -0,0 +1,50 @@
+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 } from "../lib/telegram/principal.mjs";
+import { pendingQuestions, questionKey } from "../lib/questions.mjs";
+import { stringArgument } from "../lib/attachment-tools.mjs";
+import { defineTool } from "eve/tools";
+var questions_ask_default = defineTool({
+	availableInSubagents: false,
+	description: "Ask for missing or ambiguous information needed to continue the member's task. Saves the task and question in the session, sends the question, and waits for their answer. Never use this for approval: destructive or irreversible actions have Confirm / Cancel buttons.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			question: {
+				type: "string",
+				description: "The one question to send to the member."
+			},
+			task: {
+				type: "string",
+				description: "The pending task, including known targets and supplied values."
+			}
+		},
+		required: ["question", "task"],
+		additionalProperties: false
+	},
+	endsTurn: true,
+	execute(input, ctx) {
+		const memberId = memberIdOf(ctx.session.auth.current);
+		const chatId = ctx.session.auth.current?.attributes.chatId;
+		if (memberId === void 0 || typeof chatId !== "string") throw new Error("A member in a chat is required.");
+		const question = {
+			id: ctx.callId,
+			question: stringArgument(input, "question"),
+			task: stringArgument(input, "task"),
+			memberId,
+			chatId,
+			messageThreadId: String(ctx.session.auth.current?.attributes.messageThreadId ?? ""),
+			address: ""
+		};
+		pendingQuestions.update((all) => ({
+			...all,
+			[questionKey(question)]: question
+		}));
+		return { pendingQuestion: question };
+	}
+});
+export { questions_ask_default as default };

package/dist/tools/index.d.ts

@@ -5,3 +5,4 @@ export { default as attachments_list } from "../extension/tools/attachments_list
 export { default as attachments_promote } from "../extension/tools/attachments_promote.js";
 export { default as attachments_read } from "../extension/tools/attachments_read.js";
 export { default as attachments_table } from "../extension/tools/attachments_table.js";
+export { default as questions_ask } from "../extension/tools/questions_ask.js";

package/dist/tools/index.mjs

@@ -9,4 +9,5 @@ import attachments_list_default from "../extension/tools/attachments_list.mjs";
 import attachments_promote_default from "../extension/tools/attachments_promote.mjs";
 import attachments_read_default from "../extension/tools/attachments_read.mjs";
 import attachments_table_default from "../extension/tools/attachments_table.mjs";
-export { attachments_discard_default as attachments_discard, attachments_list_default as attachments_list, attachments_promote_default as attachments_promote, attachments_read_default as attachments_read, attachments_table_default as attachments_table };
+import questions_ask_default from "../extension/tools/questions_ask.mjs";
+export { attachments_discard_default as attachments_discard, attachments_list_default as attachments_list, attachments_promote_default as attachments_promote, attachments_read_default as attachments_read, attachments_table_default as attachments_table, questions_ask_default as questions_ask };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream/agent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",