@segmentstream/agent 0.3.0 → 0.4.0

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

@@ -2,6 +2,7 @@ import { type TelegramChannel } from "eve/channels/telegram";
 import type { SessionSettings, TelegramSettings } from "../../config.js";
 import { type AgentAttachments } from "../attachments.js";
 import { type Environment } from "../environment.js";
+import { type Conversations } from "../conversations.js";
 import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 import { type RuntimeToken } from "../runtime-token.js";
 import { type ObservedMessages } from "./observed.js";
@@ -31,10 +32,11 @@ 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;
+    readonly conversations?: Conversations;
 }
 /** The Telegram channel of the extension. */
 export declare function segmentstreamTelegram(options: TelegramAdapterOptions): TelegramChannel;

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

@@ -9,16 +9,19 @@ import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs
 import { runtimeToken } from "../runtime-token.mjs";
 import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
 import { agentIdentities } from "../identities.mjs";
+import { conversations } from "../conversations.mjs";
+import { observedMessages } from "./observed.mjs";
+import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
+import { captureRouteDecider, captureTelegramFetch, conversationIdentities, telegramConversationCapture } from "./conversations.mjs";
 import { runtimeTokenVerifier } from "../runtime-identity.mjs";
 import { botIdentityCache } from "./bot.mjs";
+import { 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 +43,27 @@ 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 archive = options.conversations ?? conversations({
+		environment,
+		token,
+		fetch: options.fetch
+	});
 	const policy = sessionPolicy({
 		settings: options.sessions,
 		read: readHistory
@@ -81,6 +100,13 @@ function segmentstreamTelegram(options) {
 		return identities;
 	}
 	const chats = agentChats({ identities: pairing });
+	const capture = telegramConversationCapture({
+		archive,
+		identities: pairing,
+		observed,
+		chats,
+		verify: telegramWebhookVerifier(() => webhookSecret(environment))
+	});
 	let store = options.attachments;
 	function attachments() {
 		store ??= agentAttachments({
@@ -94,7 +120,7 @@ function segmentstreamTelegram(options) {
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
 			fileBaseUrl: TELEGRAM_PROXY_ORIGIN,
-			fetch: (input, init) => telegramProxyFetch(proxy())(input, init)
+			fetch: (input, init) => captureTelegramFetch(telegramProxyFetch(proxy()), archive, pairing)(input, init)
 		},
 		credentials: {
 			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
@@ -110,12 +136,12 @@ function segmentstreamTelegram(options) {
 				sessions: options.sessions,
 				sessionPolicy: policy,
 				sttModel: options.models().stt,
-				identities: pairing(),
+				identities: conversationIdentities(pairing()),
 				bot,
-				decide: decisionRouter({
+				decide: captureRouteDecider(decisionRouter({
 					decide: options.decide,
 					model: options.models().decision
-				}),
+				})),
 				transcribe: options.transcribe ?? gatewayTranscriber,
 				download: (fileId) => downloadTelegramFile({
 					proxy: proxy(),
@@ -124,11 +150,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;
@@ -158,7 +195,8 @@ function segmentstreamTelegram(options) {
 		routes: [...channel.routes.map((route) => gatedRoute({
 			route,
 			options,
-			environment
+			environment,
+			capture
 		})), messagesRoute({
 			channel,
 			enabled: () => channelsEnabled(environment),
@@ -188,9 +226,22 @@ function gatedRoute(input) {
 				from: args.from
 			};
 			inbound.waitUntil = args.waitUntil;
-			return runInboundRequest(inbound, () => route.handler(request, {
-				...args,
-				from: (address) => withReplacedText(args.from(scoped(address)), inbound)
+			inbound.respond = (address, requestId, decision, auth) => args.from(scoped(address)).respond([{
+				requestId,
+				optionId: decision
+			}], { auth });
+			return runInboundRequest(inbound, () => input.capture(request, async () => {
+				const tasks = [];
+				const response = await route.handler(request, {
+					...args,
+					waitUntil: (task) => {
+						tasks.push(task);
+						args.waitUntil(task);
+					},
+					from: (address) => withReplacedText(args.from(inbound.address ?? scoped(address)), inbound)
+				});
+				await Promise.all(tasks);
+				return response;
 			}));
 		}
 	};

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 { currentInboundRequest } from "./inbound-request.mjs";
+import { answerMarker, isPendingQuestion, pendingQuestions, questionKey } from "../questions.mjs";
+import { formatAddress, scopedAddress } from "./sessions.mjs";
+import { registerTelegramFreeformPrompt, renderTelegramInputRequest } from "eve/channels/telegram";
+import { createHash } from "node:crypto";
+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/conversations.d.ts

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