@segmentstream/agent 0.3.0 → 0.3.1

package/dist/extension/_manifest.json

@@ -8,6 +8,7 @@
     "channel": 58,
     "connection": 46,
     "instructions": 2,
-    "config": 1
+    "config": 1,
+    "state": 13
   }
 }

package/dist/extension/instructions.md

@@ -7,15 +7,30 @@ talking to you, and you act with exactly their permissions.
   connection. Call `describe` for the catalog of entities and actions, and `me` for whom you act
   for and what they may do. The tools you see are already narrowed to that member's permissions;
   if a tool is missing, the member may not use it, so say so instead of looking for a way around.
-- Every change goes through an action. Never claim a record changed unless an action reported it.
+- When the current member has permission and gives a clear instruction, act, including necessary
+  routine intermediate steps. Their authorization continues across turns. When they answer your
+  question, use the answer and continue the pending task without asking for permission again.
+- Ask only when information is missing or ambiguous. In Telegram, use
+  `segmentstream__questions_ask` with the question and pending task so the session keeps its intent,
+  member and chat/topic. An answer to a pending question is never chatter or `[SILENT]`.
+- Destructive or irreversible actions, and legacy custom actions without safety labels, require
+  the tool boundary's Confirm / Cancel buttons. Call the action to start that flow; never ask for
+  approval in prose or treat a text acknowledgement as approval. Wait for the button outcome.
+  Cancel ends that call; retry it only after a new instruction from the member.
+- Every change goes through an action. Report results after success; never claim a record changed
+  unless an action reported it.
 - Never invent records or values. Say when the ontology does not hold what was asked.
 - When you have been routed a message but a reply would add nothing, answer with exactly
   `[SILENT]` and nothing else. Use it only in that case; it suppresses delivery to the chat.
-- To ask someone something in a group or a private chat, run the ontology action
-  `agent_chat.send_message`; their replies come back into that chat's session, where you handle
-  them. The groups you are in are listed in `agent_chat`, with the `purpose` and `whenToUse` members
-  set; when a member who may change it tells you what a group is for, record it with
-  `agent_chat.update`.
+- Use the ontology action `agent_chat.send_message` only to start a conversation in a different
+  group or private chat; their replies come back into that chat's session, where you handle them.
+  Inside a delivered `<agent_request>`, this turn already runs in the target chat: your reply here
+  is the message delivered to that 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. 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. The groups you are in are listed in `agent_chat`, with the
+  `purpose` and `whenToUse` members set; when a member who may change it tells you what a group is
+  for, record it with `agent_chat.update`.
 - Files the member sends are temporary attachments, listed in an `<attachments>` block with their
   ids and kept for 24 hours. `segmentstream__attachments_read` extracts sheet tables, document text,
   email bodies and archive listings, with images/PDF inline and metadata for other formats. Follow

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

@@ -0,0 +1,26 @@
+import { type StateHandle } from "eve/context";
+import type { ApprovalConfiguration } from "eve/tools/approval";
+export declare const CONFIRMATION_TTL_MS: number;
+export interface ActionAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly irreversibleHint?: boolean;
+    readonly idempotentHint?: boolean;
+}
+/** Safety comes from the authenticated ontology, never from the name or model prose. */
+export declare function needsConfirmation(labels: ActionAnnotations): boolean;
+export declare function inputHash(input: unknown): string;
+export interface Confirmation {
+    readonly memberId: string;
+    readonly action: string;
+    readonly inputHash: string;
+    readonly expiresAt: number;
+    readonly status: "pending" | "approved" | "consumed" | "cancelled";
+}
+export declare const confirmations: StateHandle<Record<string, Confirmation>>;
+/** Eve pauses the original call and rechecks this policy immediately before executing it. */
+export declare function actionApproval(options: {
+    readonly labels: (memberId: string, action: string, input: Readonly<Record<string, unknown>>) => Promise<ActionAnnotations>;
+    readonly state?: StateHandle<Record<string, Confirmation>>;
+    readonly now?: () => number;
+}): ApprovalConfiguration;

package/dist/extension/lib/confirmations.mjs

@@ -0,0 +1,96 @@
+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 "./telegram/principal.mjs";
+import { createHash } from "node:crypto";
+import { defineState } from "eve/context";
+const CONFIRMATION_TTL_MS = 6e5;
+function needsConfirmation(labels) {
+	return labels.readOnlyHint !== true && (labels.destructiveHint === true || labels.irreversibleHint === true || labels.destructiveHint === void 0 && labels.irreversibleHint === void 0);
+}
+function canonical(value) {
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	if (typeof value === "object" && value !== null) return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+	const encoded = JSON.stringify(value);
+	if (encoded === void 0) throw new TypeError("Action input must be JSON.");
+	return encoded;
+}
+function inputHash(input) {
+	return createHash("sha256").update(canonical(input)).digest("hex");
+}
+const confirmations = defineState("segmentstream.confirmations", () => ({}));
+function actionApproval(options) {
+	const state = options.state ?? confirmations;
+	const now = options.now ?? Date.now;
+	const denied = (reason) => ({
+		type: "denied",
+		reason
+	});
+	return {
+		async request(ctx) {
+			const memberId = memberIdOf(ctx.session.auth.current);
+			if (memberId === void 0) return denied("A paired member is required.");
+			const hash = inputHash(ctx.toolInput ?? {});
+			const saved = state.get()[ctx.callId];
+			if (saved !== void 0) {
+				if (saved.memberId !== memberId || saved.action !== ctx.toolName || saved.inputHash !== hash) return denied("The confirmation belongs to another member, action or input.");
+				if (saved.expiresAt <= now()) return denied("The confirmation expired. Make a new call.");
+				if (saved.status === "consumed" || saved.status === "cancelled") return denied("The confirmation has already been used or cancelled.");
+			}
+			let labels;
+			try {
+				labels = await options.labels(memberId, ctx.toolName, ctx.toolInput ?? {});
+			} catch (error) {
+				console.warn("The ontology action permission check failed.", error);
+				return denied("The action is unavailable or the member no longer has permission.");
+			}
+			if (saved?.status === "approved") {
+				state.update((all) => ({
+					...all,
+					[ctx.callId]: {
+						...saved,
+						status: "consumed"
+					}
+				}));
+				return "approved";
+			}
+			if (saved !== void 0) return denied("The original call is waiting for its Confirm / Cancel buttons.");
+			if (!needsConfirmation(labels)) return "approved";
+			state.update((all) => ({
+				...all,
+				[ctx.callId]: {
+					memberId,
+					action: ctx.toolName,
+					inputHash: hash,
+					expiresAt: now() + CONFIRMATION_TTL_MS,
+					status: "pending"
+				}
+			}));
+			return "user-approval";
+		},
+		response(ctx) {
+			const saved = state.get()[ctx.request.callId];
+			const reject = (reason) => ({
+				status: "rejected",
+				reason
+			});
+			if (saved === void 0 || saved.status !== "pending") return reject("This confirmation is no longer pending.");
+			if (ctx.response.principal.attributes.confirmationRequestId !== ctx.request.requestId || ctx.response.principal.attributes.confirmationDecision !== ctx.response.decision) return reject("Use the Confirm or Cancel button on the action's message.");
+			if (memberIdOf(ctx.response.principal) !== saved.memberId || memberIdOf(ctx.request.principal) !== saved.memberId) return reject("Only the requesting member can confirm or cancel this action.");
+			if (saved.action !== ctx.request.toolName || saved.inputHash !== inputHash(ctx.request.toolInput ?? {})) return reject("The action or input changed. Make a new call.");
+			if (ctx.response.decision === "approve" && saved.expiresAt <= now()) return reject("This confirmation expired.");
+			state.update((all) => ({
+				...all,
+				[ctx.request.callId]: {
+					...saved,
+					status: ctx.response.decision === "approve" ? "approved" : "cancelled"
+				}
+			}));
+			return { status: "allowed" };
+		}
+	};
+}
+export { CONFIRMATION_TTL_MS, actionApproval, confirmations, inputHash, needsConfirmation };

package/dist/extension/lib/ontology-connection.d.ts

@@ -33,4 +33,5 @@ export declare function ontologyConnection(input: {
     readonly principal: SessionAuthContext | null;
     readonly environment?: Environment;
     readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
 }): McpClientConnectionDefinition | null;

package/dist/extension/lib/ontology-connection.mjs

@@ -6,7 +6,9 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
 import { memberIdOf } from "./telegram/principal.mjs";
+import { actionApproval } from "./confirmations.mjs";
 import { runtimeToken, tokenExpiry } from "./runtime-token.mjs";
+import { ontologyToolLabels } from "./ontology-tools.mjs";
 import { defineMcpClientConnection } from "eve/connections";
 const ACT_AS_HEADER = "X-SegmentStream-Act-As";
 const DESCRIPTION = "The company's ontology: its records, their history, and the actions that change them, narrowed to what the member you act for may read and do. Call describe for the catalog and me for the member.";
@@ -28,6 +30,7 @@ function ontologyConnection(input) {
 		url: `${origin}/mcp`,
 		description: DESCRIPTION,
 		instanceKey: `${origin}/mcp#member:${memberId}`,
+		approval: actionApproval({ labels: ontologyToolLabels(input) }),
 		auth: {
 			credentialOwner: "app",
 			getToken: async () => {

package/dist/extension/lib/ontology-tools.d.ts

@@ -0,0 +1,11 @@
+import type { ActionAnnotations } from "./confirmations.js";
+import { type Environment } from "./environment.js";
+import { type RuntimeToken } from "./runtime-token.js";
+/** A fresh, permission-filtered catalog. Listing tools cannot run an action's prepare step. */
+export declare function ontologyToolLabels(options?: {
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+}): (memberId: string, action: string) => Promise<ActionAnnotations>;
+/** MCP normalizes an authored camelCase action to snake_case. */
+export declare function actionToolName(entity: string, action: string): string;

package/dist/extension/lib/ontology-tools.mjs

@@ -0,0 +1,41 @@
+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 { appOrigin } from "./environment.mjs";
+import { runtimeToken } from "./runtime-token.mjs";
+function ontologyToolLabels(options = {}) {
+	return async (memberId, action) => {
+		const response = await (options.fetch ?? fetch)(`${appOrigin(options.environment ?? process.env)}/mcp`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${await (options.token ?? runtimeToken)()}`,
+				"X-SegmentStream-Act-As": memberId,
+				"content-type": "application/json",
+				accept: "application/json, text/event-stream",
+				"mcp-protocol-version": "2025-11-25"
+			},
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: "approval-tools",
+				method: "tools/list",
+				params: {}
+			}),
+			signal: AbortSignal.timeout(15e3),
+			redirect: "error"
+		});
+		if (!response.ok) throw new Error("Cannot check action permission.");
+		const body = await response.json();
+		const bareName = action.split("__").at(-1);
+		const tool = body.result?.tools?.find((candidate) => candidate.name === bareName);
+		if (tool === void 0) throw new Error("Action not permitted.");
+		return tool.annotations ?? {};
+	};
+}
+function actionToolName(entity, action) {
+	const snake = (name) => name.replace(/([A-Z])([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+	return `${snake(entity)}_${snake(action)}`;
+}
+export { actionToolName, ontologyToolLabels };

package/dist/extension/lib/questions.d.ts

@@ -0,0 +1,14 @@
+export interface PendingQuestion {
+    readonly id: string;
+    readonly question: string;
+    readonly task: string;
+    readonly memberId: string;
+    readonly chatId: string;
+    readonly messageThreadId: string;
+    readonly address: string;
+}
+/** Intent survives turns and compaction in the session, independently of model history. */
+export declare const pendingQuestions: import("eve/context").StateHandle<Record<string, PendingQuestion>>;
+export declare function questionKey(question: Pick<PendingQuestion, "memberId" | "chatId" | "messageThreadId">): string;
+export declare function isPendingQuestion(value: unknown): value is PendingQuestion;
+export declare function answerMarker(id: string): string;

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",

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.3.1",
   "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",