@segmentstream/agent 0.5.0 → 0.5.2

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

@@ -5,14 +5,15 @@ import { type Environment } from "./environment.js";
 import { type RuntimeToken } from "./runtime-token.js";
 /**
  * What the `segmentstream__attachments_*` tools share. The owner of every call comes from the turn:
- * the member and chat on the session's principal, which the channel set from the pairing, and the
- * session's own id. A tool's arguments name only the attachment and what to do with it.
+ * the member and chat on the session's principal, which the channel set from the pairing or a
+ * verified member request, and the session's own id. A tool's arguments name only the attachment
+ * and what to do with it.
  */
 /** Maximum characters in a read/query response; remaining data is available by continuation. */
 export declare const MAXIMUM_TEXT_CHARACTERS = 50000;
 /** The largest file `attachments_read` hands the model inline. */
 export declare const MAXIMUM_INLINE_BYTES: number;
-/** The turn has no member and chat to own attachments, such as a caller who never paired. */
+/** The turn has no member and chat to authorize attachments. */
 export declare class AttachmentOwnerError extends Error {
     readonly name = "AttachmentOwnerError";
 }

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

@@ -17,9 +17,11 @@ var AttachmentOwnerError = class extends Error {
 	name = "AttachmentOwnerError";
 };
 function attachmentOwner(input) {
-	const memberId = memberIdOf(input.principal);
+	const attributes = input.principal?.attributes;
+	const requesterId = attributes?.requesterKind === "member" && attributes.chatType === "group" ? attributes.requesterId : void 0;
+	const memberId = memberIdOf(input.principal) ?? (typeof requesterId === "string" ? requesterId : void 0);
 	const chatId = input.principal?.attributes.chatId;
-	if (memberId === void 0 || typeof chatId !== "string" || chatId === "") throw new AttachmentOwnerError("Attachments are available only to a paired member in a chat with the agent.");
+	if (memberId === void 0 || memberId === "" || typeof chatId !== "string" || chatId === "") throw new AttachmentOwnerError("Attachments require a workspace member in a chat with the agent.");
 	return {
 		memberId,
 		conversation: telegramConversation(chatId),

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

@@ -2,7 +2,7 @@ import type { RuntimeToken } from "./runtime-token.js";
 /**
  * The ontology service's attachment routes (`docs/agent.md`, "Attachments"). A file a member sends
  * the agent is stored once in the workspace's private file storage, for 24 hours, and belongs to
- * that member, the chat it arrived in and the agent session that first reads it. The agent calls
+ * the chat's authorized members in groups, or its sender and session in private chats. The agent calls
  * these routes as the deployment, with its OIDC token, naming the member, the chat and the session
  * from the turn's own context; nothing a model writes reaches these headers.
  */
@@ -14,7 +14,7 @@ export declare const CONVERSATION_HEADER = "X-SegmentStream-Agent-Conversation";
 export declare const SESSION_HEADER = "X-SegmentStream-Agent-Session";
 /** The URL protocol of a file part that names a stored attachment instead of a Telegram file. */
 export declare const ATTACHMENT_URL_PROTOCOL = "segmentstream-attachment:";
-/** Whose attachment it is, from the turn: the member, the chat and the agent session. */
+/** Who asks for attachment access, from the turn: the member, chat and agent session. */
 export interface AttachmentOwner {
     readonly memberId: string;
     /** The chat, such as `telegram:12345`. */

package/dist/extension/lib/confirmation-description.d.ts

@@ -0,0 +1,25 @@
+/** Only human-facing facts cross into the confirmation renderer; identifiers stay in the gate. */
+export interface ConfirmationDescription {
+    readonly action: string;
+    readonly entity?: string;
+    readonly description?: string;
+    readonly fields: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+export declare function object(value: unknown): Record<string, unknown>;
+export declare function humanize(value: string): string;
+/** Reject machine identifiers and structured data even in authored labels or resolved titles. */
+export declare function humanText(value: unknown, maximum?: number): string | undefined;
+/** Resolve local schema references and wrappers without following remote references. */
+export declare function fieldSchema(value: unknown, root: Record<string, unknown>, depth?: number): Record<string, unknown>;
+export declare function describeConfirmation(input: {
+    readonly title?: string;
+    readonly description?: string;
+    readonly schema: Record<string, unknown>;
+    readonly entity?: Record<string, unknown>;
+    readonly entities: readonly Record<string, unknown>[];
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly read: (entity: string, id: string) => Promise<Record<string, unknown> | undefined>;
+}): Promise<ConfirmationDescription>;

package/dist/extension/lib/confirmation-description.mjs

@@ -0,0 +1,81 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+function object(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function humanize(value) {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
+}
+function humanText(value, maximum = 180) {
+	if (typeof value !== "string") return;
+	const text = value.replace(/\s+/g, " ").trim();
+	if (text === "" || /[{}\[\]]|__|\b[0-9a-f]{8}-[0-9a-f-]{27,}\b|\b[0-9A-HJKMNP-TV-Z]{26}\b|\b[a-z0-9]{24,}\b/iu.test(text)) return;
+	return text.slice(0, maximum);
+}
+function fieldSchema(value, root, depth = 0) {
+	const schema = object(value);
+	if (depth > 12) return {};
+	const ref = schema.$ref;
+	const referenced = typeof ref === "string" && ref.startsWith("#/") ? ref.slice(2).split("/").reduce((at, key) => object(at)[key.replace(/~1/g, "/").replace(/~0/g, "~")], root) : {};
+	const branches = [
+		schema.allOf,
+		schema.anyOf,
+		schema.oneOf
+	].flatMap((items) => Array.isArray(items) ? items.filter((item) => object(item).type !== "null") : []);
+	return Object.assign({}, ...ref === void 0 ? [] : [fieldSchema(referenced, root, depth + 1)], ...branches.map((branch) => fieldSchema(branch, root, depth + 1)), schema);
+}
+async function describeConfirmation(input) {
+	const entity = input.entity ?? {};
+	const properties = Array.isArray(entity.properties) ? entity.properties.map(object) : [];
+	const fields = [];
+	const read = new Map();
+	for (const [key, value] of Object.entries(input.values).slice(0, 20)) {
+		const declared = object(input.schema.properties)[key];
+		if (declared === void 0 || /password|secret|token|credential|authorization/i.test(key)) continue;
+		const schema = fieldSchema(declared, input.schema);
+		const itemSchema = schema.type === "array" ? fieldSchema(schema.items, input.schema) : schema;
+		const property = properties.find((candidate) => candidate.name === key);
+		const reference = itemSchema["x-ontology-ref"];
+		const target = input.entities.find((candidate) => candidate.name === reference);
+		const label = humanText(schema.title) ?? humanText(property?.label) ?? humanText(humanize(key));
+		if (label === void 0 || schema.writeOnly === true || schema.format === "password") continue;
+		const options = Array.isArray(property?.options) ? property.options.map(object) : [];
+		const choices = [itemSchema.oneOf, itemSchema.anyOf].flatMap((items) => Array.isArray(items) ? items.map(object) : []);
+		const values = [];
+		for (const item of (Array.isArray(value) ? value : [value]).slice(0, 5)) {
+			if (typeof reference === "string") {
+				let title;
+				if (target !== void 0 && typeof item === "string" && typeof target.title === "string") {
+					const cacheKey = `${reference}:${item}`;
+					if (!read.has(cacheKey)) read.set(cacheKey, input.read(reference, item));
+					const value = (await read.get(cacheKey))?.[target.title];
+					title = value === item ? void 0 : humanText(value);
+				}
+				values.push(title ?? humanText(target?.label) ?? label);
+				continue;
+			}
+			if (/^(id|.*_id)$/i.test(key) || itemSchema.format === "uuid" || typeof item === "object") continue;
+			const option = options.find((candidate) => candidate.value === item);
+			const choice = choices.find((candidate) => candidate.const === item);
+			const enumeration = Array.isArray(itemSchema.enum) || choices.length > 0 || options.length > 0;
+			const text = humanText(option?.label) ?? humanText(choice?.title) ?? (enumeration ? void 0 : typeof item === "string" ? humanText(humanize(item)) : typeof item === "number" || typeof item === "boolean" ? String(item) : void 0);
+			if (text !== void 0) values.push(text);
+		}
+		if (values.length > 0) fields.push({
+			label,
+			value: values.join(", ")
+		});
+		if (fields.length === 6) break;
+	}
+	return {
+		action: humanText(input.title) ?? "the requested action",
+		...humanText(entity.label) === void 0 ? {} : { entity: humanText(entity.label) },
+		...humanText(input.description?.split("\n\n")[0]) === void 0 ? {} : { description: humanText(input.description?.split("\n\n")[0]) },
+		fields
+	};
+}
+export { describeConfirmation, fieldSchema, humanText, humanize, object };

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

@@ -1,11 +1,13 @@
 import { type StateHandle } from "eve/context";
 import type { ApprovalConfiguration } from "eve/tools/approval";
+import type { ConfirmationDescription } from "./confirmation-description.js";
 export declare const CONFIRMATION_TTL_MS: number;
 export interface ActionAnnotations {
     readonly readOnlyHint?: boolean;
     readonly destructiveHint?: boolean;
     readonly irreversibleHint?: boolean;
     readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
 }
 /** Safety comes from the authenticated ontology, never from the name or model prose. */
 export declare function needsConfirmation(labels: ActionAnnotations): boolean;
@@ -16,11 +18,13 @@ export interface Confirmation {
     readonly inputHash: string;
     readonly expiresAt: number;
     readonly status: "pending" | "approved" | "consumed" | "cancelled";
+    readonly description?: ConfirmationDescription;
 }
 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 describe?: (memberId: string, action: string, input: Readonly<Record<string, unknown>>) => Promise<ConfirmationDescription>;
     readonly state?: StateHandle<Record<string, Confirmation>>;
     readonly now?: () => number;
 }): ApprovalConfiguration;

package/dist/extension/lib/confirmations.mjs

@@ -9,7 +9,7 @@ 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);
+	return labels.readOnlyHint !== true && (labels.destructiveHint === true || labels.irreversibleHint === true || labels.openWorldHint === true || labels.destructiveHint === void 0 && labels.irreversibleHint === void 0);
 }
 function canonical(value) {
 	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
@@ -59,6 +59,12 @@ function actionApproval(options) {
 			}
 			if (saved !== void 0) return denied("The original call is waiting for its Confirm / Cancel buttons.");
 			if (!needsConfirmation(labels)) return "approved";
+			let description;
+			try {
+				description = await options.describe?.(memberId, ctx.toolName, ctx.toolInput ?? {});
+			} catch (error) {
+				console.warn("The confirmation description could not be read.", error);
+			}
 			state.update((all) => ({
 				...all,
 				[ctx.callId]: {
@@ -66,7 +72,8 @@ function actionApproval(options) {
 					action: ctx.toolName,
 					inputHash: hash,
 					expiresAt: now() + CONFIRMATION_TTL_MS,
-					status: "pending"
+					status: "pending",
+					...description === void 0 ? {} : { description }
 				}
 			}));
 			return "user-approval";

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

@@ -49,6 +49,8 @@ export interface Conversations {
         readonly limit?: number;
     }): Promise<ConversationPage>;
 }
+/** Collapse delivery snapshots from older archives before building a user/model transcript. */
+export declare function collapseConversationEvents(events: ConversationPage["events"]): ConversationPage["events"];
 export declare function conversationEvent(input: Pick<ConversationEvent, "eventId" | "provider" | "chatId" | "chatType" | "kind"> & Partial<ConversationEvent>): ConversationEvent;
 export declare function conversations(input?: {
     readonly environment?: Environment;

package/dist/extension/lib/conversations.mjs

@@ -6,6 +6,18 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { proxyEnvironment } from "./environment.mjs";
 import { runtimeToken } from "./runtime-token.mjs";
+function collapseConversationEvents(events) {
+	const latest = new Map();
+	for (const event of events) {
+		const key = event.kind === "outbound" && /^telegram:(send|edit):/u.test(event.eventId) ? event.eventId.replace(/:result$/u, "") : event.eventId;
+		const previous = latest.get(key);
+		if (previous === void 0 || (/^\d+$/u.test(event.sequence) && /^\d+$/u.test(previous.sequence) ? BigInt(event.sequence) > BigInt(previous.sequence) : event.storedAt > previous.storedAt)) latest.set(key, {
+			...event,
+			eventId: key
+		});
+	}
+	return [...latest.values()];
+}
 function conversationEvent(input) {
 	return {
 		threadId: null,
@@ -78,12 +90,12 @@ function summarizeArguments(value) {
 	return (JSON.stringify(visit(value, 0)) ?? "{}").slice(0, 4e3);
 }
 async function storedConversationContext(archive, coordinates) {
-	const messages = (await archive.context({
+	const messages = collapseConversationEvents((await archive.context({
 		provider: coordinates.provider,
 		chatId: coordinates.chatId,
 		...coordinates.threadId === null ? {} : { threadId: coordinates.threadId },
 		limit: 100
-	})).events.filter((event) => event.kind === "inbound" || event.kind === "outbound" && event.status === "completed");
+	})).events).filter((event) => event.kind === "inbound" || event.kind === "outbound" && event.status === "completed");
 	const selected = [];
 	let characters = 0;
 	for (const event of messages) {
@@ -104,4 +116,4 @@ async function storedConversationContext(archive, coordinates) {
 		JSON.stringify(selected.reverse())
 	].join("\n");
 }
-export { conversationEvent, conversations, storedConversationContext, summarizeArguments };
+export { collapseConversationEvents, conversationEvent, conversations, storedConversationContext, summarizeArguments };

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

@@ -11,6 +11,7 @@ export interface PairedMember {
     readonly id: string;
     readonly name: string | null;
     readonly roles: ReadonlyArray<string>;
+    readonly locale?: string;
 }
 export type IdentityLookup = {
     readonly status: "paired";

package/dist/extension/lib/identities.mjs

@@ -44,7 +44,8 @@ function pairedMember(value) {
 	return {
 		id: user.id,
 		name: typeof user.name === "string" ? user.name : null,
-		roles
+		roles,
+		...typeof user.locale === "string" ? { locale: user.locale } : {}
 	};
 }
 function pairing(value) {

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

@@ -8,7 +8,7 @@ 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 { ontologyTools } 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.";
@@ -30,7 +30,7 @@ function ontologyConnection(input) {
 		url: `${origin}/mcp`,
 		description: DESCRIPTION,
 		instanceKey: `${origin}/mcp#member:${memberId}`,
-		approval: actionApproval({ labels: ontologyToolLabels(input) }),
+		approval: actionApproval(ontologyTools(input)),
 		auth: {
 			credentialOwner: "app",
 			getToken: async () => {

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

@@ -2,10 +2,14 @@ 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?: {
+export declare function ontologyTools(options?: {
     readonly environment?: Environment;
     readonly token?: RuntimeToken;
     readonly fetch?: typeof fetch;
-}): (memberId: string, action: string) => Promise<ActionAnnotations>;
+}): {
+    labels(memberId: string, action: string): Promise<ActionAnnotations>;
+    describe(memberId: string, action: string, input: Readonly<Record<string, unknown>>): Promise<import("./confirmation-description.js").ConfirmationDescription>;
+};
+export declare function ontologyToolLabels(options?: Parameters<typeof ontologyTools>[0]): (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

@@ -5,37 +5,107 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
+import { describeConfirmation, object } from "./confirmation-description.mjs";
+import { redactDiagnostic } from "./diagnostics.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();
+function ontologyTools(options = {}) {
+	async function rpc(memberId, method, params, signal) {
+		const credential = await (options.token ?? runtimeToken)();
+		const secrets = new Set([credential]);
+		try {
+			const response = await (options.fetch ?? fetch)(`${appOrigin(options.environment ?? process.env)}/mcp`, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${credential}`,
+					"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,
+					params
+				}),
+				signal: signal ?? AbortSignal.timeout(15e3),
+				redirect: "error"
+			});
+			if (!response.ok) throw new Error(`Cannot check action permission (HTTP ${response.status}).`);
+			const body = object(await response.json());
+			if (body.error !== void 0) throw new Error("Ontology metadata unavailable.", { cause: body.error });
+			return object(body.result);
+		} catch (error) {
+			throw new Error("The ontology metadata request failed.", { cause: redactDiagnostic(error, secrets) });
+		}
+	}
+	async function toolFor(memberId, action, signal) {
+		const result = await rpc(memberId, "tools/list", {}, signal);
+		const tools = Array.isArray(result.tools) ? result.tools.map(object) : [];
 		const bareName = action.split("__").at(-1);
-		const tool = body.result?.tools?.find((candidate) => candidate.name === bareName);
+		const tool = tools.find((candidate) => candidate.name === bareName);
 		if (tool === void 0) throw new Error("Action not permitted.");
-		return tool.annotations ?? {};
+		return {
+			tool,
+			tools
+		};
+	}
+	return {
+		async labels(memberId, action) {
+			return object((await toolFor(memberId, action)).tool.annotations);
+		},
+		async describe(memberId, action, input) {
+			const signal = AbortSignal.timeout(15e3);
+			const { tool, tools } = await toolFor(memberId, action, signal);
+			let entities = [];
+			try {
+				const catalog = await rpc(memberId, "resources/read", { uri: "ontology://catalog" }, signal);
+				const text = object(Array.isArray(catalog.contents) ? catalog.contents[0] : void 0).text;
+				const manifest = object(typeof text === "string" ? JSON.parse(text) : void 0);
+				entities = Array.isArray(manifest.entities) ? manifest.entities.map(object) : [];
+			} catch (error) {
+				console.warn("The confirmation catalog could not be read.", error);
+			}
+			const entity = entities.find((candidate) => {
+				return [
+					"create",
+					"update",
+					"delete",
+					"link",
+					"unlink",
+					...Array.isArray(candidate.actions) ? candidate.actions.map((item) => object(item).name) : []
+				].some((name) => typeof name === "string" && actionToolName(String(candidate.name), name) === tool.name);
+			});
+			return describeConfirmation({
+				title: typeof tool.title === "string" ? tool.title : void 0,
+				description: typeof tool.description === "string" ? tool.description : void 0,
+				schema: object(tool.inputSchema),
+				entity,
+				entities,
+				values: input,
+				async read(entityName, id) {
+					const name = actionToolName(entityName, "get");
+					if (!tools.some((candidate) => candidate.name === name && object(candidate.annotations).readOnlyHint === true)) return;
+					try {
+						const result = await rpc(memberId, "tools/call", {
+							name,
+							arguments: { id }
+						}, signal);
+						return result.isError === true ? void 0 : object(result.structuredContent);
+					} catch (error) {
+						console.warn("A confirmation record title could not be read.", error);
+						return;
+					}
+				}
+			});
+		}
 	};
 }
+function ontologyToolLabels(options = {}) {
+	return ontologyTools(options).labels;
+}
 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 };
+export { actionToolName, ontologyToolLabels, ontologyTools };

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

@@ -5,6 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
+import { conversationLanguage } from "./principal.mjs";
 import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
 import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
@@ -12,11 +13,13 @@ 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 { failureText, reportTelegramError, safeTelegramFetch, withDeliveryLocale } from "./customer-text.mjs";
 import { captureRouteDecider, captureTelegramFetch, conversationIdentities, telegramConversationCapture } from "./conversations.mjs";
 import { runtimeTokenVerifier } from "../runtime-identity.mjs";
 import { botIdentityCache } from "./bot.mjs";
+import { confirmationLocale, confirmationRenderer } from "./confirmation-text.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
-import { confirmationEvents, handleConfirmationCallback } from "./confirmations.mjs";
+import { handleConfirmationCallback, telegramConfirmationEvents } from "./confirmations.mjs";
 import { agentChats } from "./chats.mjs";
 import { decisionRouter } from "./router.mjs";
 import { replyDelivery } from "./silent.mjs";
@@ -25,7 +28,7 @@ import { handleInboundMessage } from "./inbound.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
 import { messagesRoute } from "./requests.mjs";
 import { healthRoute } from "./health.mjs";
-import { withTurnErrorLogging } from "./turn-errors.mjs";
+import { telegramFailureEvents } from "./turn-errors.mjs";
 import { telegramWebhookVerifier } from "./webhook.mjs";
 import { telegramChannel } from "eve/channels/telegram";
 const eveHistory = async (sessionId) => {
@@ -121,56 +124,81 @@ function segmentstreamTelegram(options) {
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
 			fileBaseUrl: TELEGRAM_PROXY_ORIGIN,
-			fetch: (input, init) => captureTelegramFetch(telegramProxyFetch(proxy()), archive, pairing)(input, init)
+			fetch: (input, init) => safeTelegramFetch(captureTelegramFetch(telegramProxyFetch(proxy()), archive, pairing))(input, init)
 		},
 		credentials: {
 			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
 			webhookVerifier: telegramWebhookVerifier(() => webhookSecret(environment))
 		},
 		uploadPolicy: { maxBytes: MAXIMUM_DOWNLOAD_BYTES },
-		onMessage: (context, message) => handleInboundMessage({
-			context,
-			message,
-			request: currentInboundRequest(),
-			dependencies: {
-				policy: settings().policy,
-				sessions: options.sessions,
-				sessionPolicy: policy,
-				sttModel: options.models().stt,
-				identities: conversationIdentities(pairing()),
-				bot,
-				decide: captureRouteDecider(decisionRouter({
-					decide: options.decide,
-					model: options.models().decision
-				})),
-				transcribe: options.transcribe ?? gatewayTranscriber,
-				download: (fileId) => downloadTelegramFile({
-					proxy: proxy(),
-					fileId
-				}),
-				attachments: attachments(),
-				observed,
-				readHistory,
-				history: readInteractions,
-				chats,
-				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
+		onMessage: async (context, message) => {
+			const inbound = currentInboundRequest();
+			if (inbound !== void 0) {
+				inbound.locale = conversationLanguage([message.text || message.caption]) ?? message.from?.languageCode ?? "en";
+				inbound.threadId = message.messageThreadId === void 0 ? void 0 : String(message.messageThreadId);
 			}
-		}),
-		onCallbackQuery: (context, query) => handleConfirmationCallback({
-			context,
-			query,
-			identities: pairing(),
-			read: readInteractions,
-			scope: options.sessions().scope
-		}),
+			try {
+				const result = await handleInboundMessage({
+					context,
+					message,
+					request: currentInboundRequest(),
+					dependencies: {
+						policy: settings().policy,
+						sessions: options.sessions,
+						sessionPolicy: policy,
+						sttModel: options.models().stt,
+						identities: conversationIdentities(pairing()),
+						bot,
+						decide: captureRouteDecider(decisionRouter({
+							decide: options.decide,
+							model: options.models().decision
+						})),
+						transcribe: options.transcribe ?? gatewayTranscriber,
+						download: (fileId) => downloadTelegramFile({
+							proxy: proxy(),
+							fileId
+						}),
+						attachments: attachments(),
+						observed,
+						readHistory,
+						history: readInteractions,
+						chats,
+						connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
+					}
+				});
+				if (inbound !== void 0 && result !== null) inbound.locale = confirmationLocale(result.auth);
+				return result;
+			} catch (error) {
+				const errorId = reportTelegramError("inbound_message_failed", error, { chatId: message.chat.id });
+				await context.telegram.post(failureText(errorId));
+				return null;
+			}
+		},
+		onCallbackQuery: async (context, query) => {
+			try {
+				await handleConfirmationCallback({
+					context,
+					query,
+					identities: pairing(),
+					read: readInteractions,
+					scope: options.sessions().scope
+				});
+			} catch (error) {
+				const errorId = reportTelegramError("confirmation_callback_failed", error);
+				await context.telegram.answerCallbackQuery({
+					callbackQueryId: query.id,
+					text: failureText(errorId)
+				});
+			}
+		},
 		events: {
-			...confirmationEvents,
+			...telegramFailureEvents,
+			...telegramConfirmationEvents(confirmationRenderer({ model: () => options.models().decision })),
 			"message.completed": replyDelivery(observed)
 		}
 	});
 	const adapter = channel.adapter;
 	const fetchTelegramFile = adapter?.fetchFile;
-	const turnFailed = adapter?.["turn.failed"];
 	async function fetchFile(url, context) {
 		const reference = parseAttachmentUrl(url);
 		if (reference === void 0) return fetchTelegramFile === void 0 ? null : fetchTelegramFile(url, context);
@@ -191,7 +219,14 @@ function segmentstreamTelegram(options) {
 		...adapter === void 0 ? {} : { adapter: {
 			...adapter,
 			fetchFile,
-			...turnFailed === void 0 ? {} : { "turn.failed": withTurnErrorLogging(turnFailed) }
+			...Object.fromEntries(Object.entries(adapter).filter(([name, handler]) => name.includes(".") && typeof handler === "function").map(([name, handler]) => [name, async (event, context) => {
+				const principal = context.session?.auth.current;
+				const locale = confirmationLocale(principal ?? null, context.state.customerLocale ?? "en");
+				context.state.customerLocale = locale;
+				await withDeliveryLocale(locale, async () => {
+					await handler(event, context);
+				}, context.state.messageThreadId === null ? void 0 : String(context.state.messageThreadId));
+			}]))
 		} },
 		routes: [
 			...channel.routes.map((route) => gatedRoute({

package/dist/extension/lib/telegram/attachments-send.d.ts

@@ -37,4 +37,5 @@ export declare function sendAttachments(options: {
 } | {
     readonly error: string;
     readonly detail: string;
+    readonly reference: string;
 }>;