@segmentstream/agent 0.5.0 → 0.5.2

package/dist/extension/lib/telegram/customer-text.d.ts

@@ -0,0 +1,20 @@
+export declare function withDeliveryLocale<T>(locale: string, run: () => T, threadId?: string): T;
+export declare function currentLocale(): string;
+export declare function currentThreadId(): string | undefined;
+export declare function customerCopy(locale?: string): {
+    failed: string;
+    recovery: string;
+    attachment: string;
+    authorization: string;
+    response: string;
+    reference: string;
+    connected: string;
+    disconnected: string;
+};
+export declare function isTechnicalText(text: string): boolean;
+/** Original failures stay in operator diagnostics, joined to the public notice by a short reference. */
+export declare function reportTelegramError(operation: string, error: unknown, metadata?: Record<string, unknown>, secrets?: ReadonlySet<string>): string;
+export declare function failureText(errorId: string, kind?: "failed" | "recovery" | "attachment" | "authorization" | "response", locale?: string): string;
+export declare function customerText(text: string, locale?: string): string;
+/** Covers framework defaults, edits and callback notices as well as ordinary agent replies. */
+export declare function safeTelegramFetch(fetchImpl: typeof fetch): typeof fetch;

package/dist/extension/lib/telegram/customer-text.mjs

@@ -0,0 +1,120 @@
+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 { redactDiagnostic } from "../diagnostics.mjs";
+import { currentInboundRequest } from "./inbound-request.mjs";
+import { randomBytes } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+const deliveryLocale = new AsyncLocalStorage();
+function withDeliveryLocale(locale, run, threadId) {
+	return deliveryLocale.run({
+		locale,
+		threadId
+	}, run);
+}
+function currentLocale() {
+	return deliveryLocale.getStore()?.locale ?? currentInboundRequest()?.locale ?? "en";
+}
+function currentThreadId() {
+	return deliveryLocale.getStore()?.threadId ?? currentInboundRequest()?.threadId;
+}
+function customerCopy(locale = currentLocale()) {
+	return locale.toLowerCase().split(/[-_]/)[0] === "ru" ? {
+		failed: "Не удалось выполнить запрос. Попробуйте ещё раз.",
+		recovery: "Не удалось продолжить разговор. Отправьте новое сообщение.",
+		attachment: "Не удалось обработать файл. Попробуйте ещё раз.",
+		authorization: "Не удалось подключиться. Попробуйте ещё раз.",
+		response: "Не удалось показать ответ. Попробуйте ещё раз.",
+		reference: "Код ошибки",
+		connected: "Доступ подключён.",
+		disconnected: "Подключение отменено."
+	} : {
+		failed: "I couldn't complete the request. Please try again.",
+		recovery: "I couldn't continue the conversation. Please send a new message.",
+		attachment: "I couldn't process the file. Please try again.",
+		authorization: "I couldn't connect. Please try again.",
+		response: "I couldn't display the response. Please try again.",
+		reference: "Error reference",
+		connected: "Access connected.",
+		disconnected: "Connection cancelled."
+	};
+}
+const TECHNICAL_PATTERNS = [
+	/[{}]|```/u,
+	/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/iu,
+	/\b[0-9a-hjkmnp-tv-z]{26}\b/iu,
+	/\b\w+__\w+/u,
+	/\b[a-z][a-z0-9]*_[a-z][a-z0-9_]*\b(?!\.[a-z0-9])/iu,
+	/\b(?:Serialization|Type|Reference|Syntax|Tool|Provider|API|Workflow|InternalServer)Error\b/u,
+	/\bError:\s|(?:^|\n)\s*at\s+\S+|\b(?:stack trace|traceback|SQLSTATE|node_modules)\b/imu,
+	/\b(?:duplicate key|ECONN\w+|HTTP [45]\d\d)\b/iu,
+	/\[\s*(?:"[^"]*"|\d+|true|false|null)\s*[,\]]/u
+];
+function isTechnicalText(text) {
+	if (/https?:\/\/[^\s/@]+:[^\s/@]+@|[?&](?:token|access_token|api_key|secret|password)=/iu.test(text)) return true;
+	const visible = text.replace(/https?:\/\/[^\s)<>]+/giu, "link");
+	return TECHNICAL_PATTERNS.some((pattern) => pattern.test(visible));
+}
+function redactCredentials(value) {
+	if (typeof value === "string") return value.replace(/\bBearer [A-Za-z0-9_.~+/-]+=*/giu, "Bearer [redacted]").replace(/(https?:\/\/)[^/@\s]+:[^/@\s]+@/gu, "$1[redacted]@").replace(/([?&](?:token|access_token|api_key|secret|password)=)[^&#\s]*/giu, "$1[redacted]").replace(/("(?:token|api_key|password|secret)"\s*:\s*)"(?:\\.|[^"\\])*"/giu, "$1\"[redacted]\"");
+	if (Array.isArray(value)) return value.map(redactCredentials);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, /^(?:token|password|secret|authorization|cookie|api_?key|access_?token|refresh_?token)$/iu.test(key) && typeof item === "string" ? "[redacted]" : redactCredentials(item)]));
+	return value;
+}
+function reportTelegramError(operation, error, metadata = {}, secrets = new Set()) {
+	const errorId = randomBytes(4).toString("hex").toUpperCase();
+	const credentials = new Set([...secrets, ...[process.env.AI_GATEWAY_API_KEY, process.env.VERCEL_OIDC_TOKEN].filter((value) => value !== void 0)]);
+	console.error("[segmentstream] Telegram delivery diagnostic", {
+		...metadata,
+		errorId,
+		operation,
+		error: redactCredentials(redactDiagnostic(error, credentials))
+	});
+	return errorId;
+}
+function failureText(errorId, kind = "failed", locale = currentLocale()) {
+	const copy = customerCopy(locale);
+	return `${copy[kind]} ${copy.reference}: ${errorId}.`;
+}
+function customerText(text, locale = currentLocale()) {
+	if (!isTechnicalText(text)) return text;
+	return failureText(reportTelegramError("technical_text_blocked", { text }), "response", locale);
+}
+function safeTelegramFetch(fetchImpl) {
+	const methods = new Set([
+		"sendMessage",
+		"editMessageText",
+		"editMessageCaption",
+		"answerCallbackQuery",
+		"sendPhoto",
+		"sendDocument",
+		"sendMediaGroup"
+	]);
+	return async (input, init) => {
+		const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+		if (!methods.has(url.split("/").at(-1) ?? "") || typeof init?.body !== "string") return fetchImpl(input, init);
+		const body = JSON.parse(init.body);
+		for (const field of ["text", "caption"]) if (typeof body[field] === "string") body[field] = customerText(body[field]);
+		if (Array.isArray(body.media)) body.media = body.media.map((item) => ({
+			...item,
+			...typeof item.caption === "string" ? { caption: customerText(item.caption) } : {}
+		}));
+		const markup = body.reply_markup;
+		if (Array.isArray(markup?.inline_keyboard)) markup.inline_keyboard = markup.inline_keyboard.map((row) => row.map((button) => {
+			if (typeof button.text !== "string" || !isTechnicalText(button.text)) return button;
+			reportTelegramError("technical_button_label_blocked", { text: button.text });
+			return {
+				...button,
+				text: currentLocale().startsWith("ru") ? "Продолжить" : "Continue"
+			};
+		}));
+		return fetchImpl(input, {
+			...init,
+			body: JSON.stringify(body)
+		});
+	};
+}
+export { currentLocale, currentThreadId, customerCopy, customerText, failureText, isTechnicalText, reportTelegramError, safeTelegramFetch, withDeliveryLocale };

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

@@ -4,7 +4,9 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { conversationLanguage } from "./principal.mjs";
 import { MAXIMUM_ATTACHMENT_BYTES, attachmentUrl } from "../attachments.mjs";
+import { failureText, reportTelegramError } from "./customer-text.mjs";
 function telegramConversation(chatId) {
 	return `telegram:${chatId}`;
 }
@@ -52,15 +54,14 @@ async function stageFiles(input) {
 				})
 			});
 		} catch (error) {
-			console.error("[segmentstream] attachment could not be stored", {
+			const errorId = reportTelegramError("attachment_storage_failed", error, {
 				kind: file.kind,
-				size: file.size,
-				error
+				size: file.size
 			});
 			staged.set(file.fileId, {
 				status: "refused",
 				filename,
-				reason: error instanceof Error ? error.message : "it could not be stored"
+				reason: failureText(errorId, "attachment", conversationLanguage([message.text || message.caption]) ?? message.from?.languageCode ?? "en")
 			});
 		}
 	}
@@ -68,7 +69,7 @@ async function stageFiles(input) {
 }
 function attachmentsContext(input) {
 	if (input.files.size === 0) return [];
-	const lines = ["<attachments>", `The member's files from this message, kept for 24 hours for this member in this chat only. Read, discard or promote them with the segmentstream__attachments_* tools and these ids; promote only what should be kept.`];
+	const lines = ["<attachments>", `Files from this message, kept for 24 hours ` + (input.group ? "for authorized members of this group only. " : "for this member in this private chat only. ") + "Read, discard or promote them with the segmentstream__attachments_* tools and these ids; promote only what should be kept."];
 	for (const staged of input.files.values()) lines.push(staged.status === "stored" ? `- id: ${staged.attachment.id}, filename: ${JSON.stringify(staged.attachment.filename)}, type: ${staged.attachment.contentType}, size: ${staged.attachment.size} bytes, expires_at: ${staged.attachment.expiresAt}` : `- ${JSON.stringify(staged.filename)}: not received, ${staged.reason}`);
 	if (input.group) lines.push("This is a group chat: everyone in it shares this conversation's history, so do not repeat a private file's contents here. Suggest sending private files in a direct message.");
 	lines.push("</attachments>");

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

@@ -22,6 +22,8 @@ export type StagedFile = {
 export declare class InboundRequest {
     /** The agent's description from the compiled manifest, for the routing decision. */
     readonly agentDescription: () => Promise<string>;
+    locale: string | undefined;
+    threadId: string | undefined;
     /** The text the turn should carry instead of the parsed message, once a transcript exists. */
     text: string | undefined;
     /**

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

@@ -7,6 +7,8 @@ __eveCreateRequire(import.meta.url);
 import { AsyncLocalStorage } from "node:async_hooks";
 var InboundRequest = class {
 	agentDescription;
+	locale;
+	threadId;
 	text;
 	files;
 	sessions;

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

@@ -4,7 +4,7 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { telegramPrincipal } from "./principal.mjs";
+import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
 import { observedChatKey, observedContext } from "./observed.mjs";
 import { recordGateDecision, recordRouteDecision } from "./conversations.mjs";
 import { answerMarker } from "../questions.mjs";
@@ -284,6 +284,7 @@ async function handleInboundMessage(input) {
 		dependencies.sessionPolicy.delivered(address);
 	}
 	await context.telegram.startTyping();
+	await report;
 	const files = sent.attachments.length === 0 || dependencies.attachments === void 0 || input.request === void 0 ? new Map() : await stageFiles({
 		message: sent,
 		memberId: lookup.member.id,
@@ -291,11 +292,15 @@ async function handleInboundMessage(input) {
 		download: dependencies.download
 	});
 	if (input.request !== void 0 && files.size > 0) input.request.files = files;
-	await report;
+	const language = conversationLanguage([text, ...dependencies.observed.recent(chat).map((message) => message.text).reverse()]);
 	dependencies.observed.remember(chat, observedMessage(sent, text, lookup.member));
 	const principal = telegramPrincipal({
-		message: sent,
-		member: lookup.member
+		message: {
+			...sent,
+			text
+		},
+		member: lookup.member,
+		conversationLanguage: language
 	});
 	return {
 		auth: answering && pending !== void 0 ? {
@@ -313,6 +318,7 @@ async function handleInboundMessage(input) {
 				member: lookup.member,
 				bot
 			}),
+			"Reply in the member's conversation language. After an action, use at most one short human sentence saying what changed and where, with a link to the record in the app. Confirmations already show their status. Never quote tool output, tool names, record ids, JSON, stack traces or internal errors; explain failures briefly with an error reference when available.",
 			...attachmentsContext({
 				files,
 				group

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

@@ -13,7 +13,10 @@ export declare function telegramPrincipal(input: {
         readonly from: NonNullable<TelegramMessage["from"]>;
     };
     readonly member: PairedMember;
+    readonly conversationLanguage?: string;
 }): SessionAuthContext;
+/** Short answers and attachment-only turns retain the recent chat language when known. */
+export declare function conversationLanguage(texts: readonly string[]): "ru" | "en" | undefined;
 /** The member a session principal acts for: `memberId` stamped by a SegmentStream channel. */
 export declare function memberIdOf(principal: SessionAuthContext | null | undefined): string | undefined;
 /** The member's roles on a session principal; empty when it carries none. */

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

@@ -20,6 +20,10 @@ function telegramPrincipal(input) {
 	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;
+	const locale = member.locale ?? message.from.languageCode;
+	if (locale !== void 0) attributes.locale = locale;
+	const language = input.conversationLanguage ?? conversationLanguage([message.text || message.caption]);
+	if (language !== void 0) attributes.conversationLanguage = language;
 	return {
 		authenticator: TELEGRAM_AUTHENTICATOR,
 		issuer: "telegram",
@@ -29,6 +33,12 @@ function telegramPrincipal(input) {
 		attributes
 	};
 }
+function conversationLanguage(texts) {
+	for (const text of texts) {
+		if (/[а-яё]/iu.test(text)) return "ru";
+		if ((text.match(/\b[a-z]+\b/gi)?.length ?? 0) >= 3) return "en";
+	}
+}
 function memberIdOf(principal) {
 	const memberId = principal?.attributes.memberId;
 	return typeof memberId === "string" && memberId !== "" ? memberId : void 0;
@@ -38,4 +48,4 @@ function rolesOf(principal) {
 	if (typeof roles === "string") return [roles];
 	return roles ?? [];
 }
-export { TELEGRAM_AUTHENTICATOR, memberIdOf, rolesOf, telegramPrincipal };
+export { TELEGRAM_AUTHENTICATOR, conversationLanguage, memberIdOf, rolesOf, telegramPrincipal };

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

@@ -76,6 +76,7 @@ function requestPrincipal(request) {
 		subject: requester.id,
 		attributes: {
 			requesterId: requester.id,
+			requesterKind: requester.kind,
 			requesterName: requester.name,
 			roles: requester.roles,
 			chatId: target.chatId,
@@ -94,7 +95,10 @@ function requestContext(request) {
 		"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 (request.documentIds !== void 0 && request.documentIds.length > 0) lines.push(`documentIds: ${JSON.stringify(request.documentIds)}`, "Send these documents with the question using segmentstream__attachments_send in this chat. Use the question as the caption (at most 1024 characters), one question per message. In groups send documents only when the chat's purpose allows; never send restricted documents there.");
-	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.`);
+	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.`);
+		if (requester.kind === "member" && request.target.kind === "group") lines.push("Temporary attachments in this group are available through segmentstream__attachments_* when the requester is a current chat participant or chat administrator. Promotion still requires the requester's permission for the target ontology action.");
+	}
 	lines.push("</agent_request>");
 	return lines.join("\n");
 }

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

@@ -6,6 +6,8 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import "./principal.mjs";
 import { agentMessage, observedChatKey } from "./observed.mjs";
+import { currentLocale, customerText } from "./customer-text.mjs";
+import { confirmationLocale } from "./confirmation-text.mjs";
 const SILENT_MARKERS = new Set(["[silent]", "no_reply"]);
 function isSilentReply(text) {
 	return SILENT_MARKERS.has(text.trim().toLowerCase());
@@ -13,7 +15,8 @@ function isSilentReply(text) {
 function replyDelivery(observed) {
 	return async (event, channel, context) => {
 		if (event.finishReason === "tool-calls" || !event.message || isSilentReply(event.message)) return;
-		await channel.telegram.post(event.message);
+		const text = customerText(event.message, confirmationLocale(context.session?.auth.current ?? null, currentLocale()));
+		await channel.telegram.post(text);
 		if (observed === void 0 || channel.telegram.chatType === "private") return;
 		const principal = context.session.auth.current;
 		const sender = principal?.authenticator === "segmentstream-telegram" ? principal.subject : void 0;
@@ -30,7 +33,7 @@ function replyDelivery(observed) {
 			...channel.telegram.messageThreadId === void 0 ? {} : { messageThreadId: channel.telegram.messageThreadId }
 		});
 		observed.remember(chat, agentMessage({
-			text: event.message,
+			text,
 			at: new Date().toISOString(),
 			...inReplyTo === void 0 ? {} : { inReplyTo }
 		}));

package/dist/extension/lib/telegram/turn-errors.d.ts

@@ -1,9 +1,2 @@
-import type { TelegramChannelEvents, TelegramChannelState } from "eve/channels/telegram";
-import type { SessionContext } from "eve/context";
-/** The adapter callback shape; Eve's public channel handler is wrapped inside this callback. */
-export type TurnFailedHandler = (event: Parameters<NonNullable<TelegramChannelEvents["turn.failed"]>>[0], context: {
-    readonly state: TelegramChannelState;
-    readonly session: Pick<SessionContext["session"], "id" | "auth">;
-}) => void | Promise<void>;
-/** Log the original failure before Eve delivers its existing customer-visible error notice. */
-export declare function withTurnErrorLogging(deliver: TurnFailedHandler): TurnFailedHandler;
+import type { TelegramChannelEvents } from "eve/channels/telegram";
+export declare const telegramFailureEvents: Pick<TelegramChannelEvents, "turn.failed" | "session.failed" | "authorization.completed">;

package/dist/extension/lib/telegram/turn-errors.mjs

@@ -5,16 +5,42 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { memberIdOf } from "./principal.mjs";
-function withTurnErrorLogging(deliver) {
-	return async (event, context) => {
-		console.error("[segmentstream] telegram turn failed", {
-			chatId: context.state.chatId,
+import { currentLocale, customerCopy, failureText, reportTelegramError } from "./customer-text.mjs";
+import { confirmationLocale } from "./confirmation-text.mjs";
+const telegramFailureEvents = {
+	async "turn.failed"(event, channel, context) {
+		const errorId = reportTelegramError("turn_failed", event, {
+			chatId: channel.state.chatId,
 			memberId: memberIdOf(context.session.auth.current) ?? null,
 			sessionId: context.session.id,
-			turnId: event.turnId,
-			error: event
+			turnId: event.turnId
 		});
-		await deliver(event, context);
-	};
-}
-export { withTurnErrorLogging };
+		await channel.telegram.post(failureText(errorId, "failed", confirmationLocale(context.session.auth.current, currentLocale())));
+	},
+	async "session.failed"(event, channel) {
+		const errorId = reportTelegramError("session_recovery_failed", event, {
+			chatId: channel.state.chatId,
+			sessionId: event.sessionId
+		});
+		const locale = channel.state.customerLocale ?? "en";
+		await channel.telegram.post(failureText(errorId, "recovery", locale));
+	},
+	async "authorization.completed"(event, channel, context) {
+		const messageId = channel.state.pendingAuthMessageIds?.[event.name];
+		if (event.candidateId !== void 0 || messageId === void 0) return;
+		const locale = confirmationLocale(context.session.auth.current);
+		const copy = customerCopy(locale);
+		let text = event.outcome === "authorized" ? copy.connected : copy.disconnected;
+		if (event.reason !== void 0) {
+			const errorId = reportTelegramError("authorization_not_completed", event, { chatId: channel.state.chatId });
+			text = failureText(errorId, "authorization", locale);
+		}
+		await channel.telegram.editMessageText({
+			messageId,
+			text,
+			replyMarkup: { inline_keyboard: [] }
+		});
+		delete channel.state.pendingAuthMessageIds?.[event.name];
+	}
+};
+export { telegramFailureEvents };

package/dist/extension/tools/attachments_promote.mjs

@@ -5,11 +5,20 @@ 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 { actionToolName, ontologyTools } 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"))) }),
+	approval: actionApproval({
+		labels: (memberId, _tool, input) => ontologyTools().labels(memberId, actionToolName(stringArgument(input, "entity"), stringArgument(input, "action"))),
+		describe: (memberId, _tool, input) => {
+			const recordId = optionalString(input, "record_id");
+			return ontologyTools().describe(memberId, actionToolName(stringArgument(input, "entity"), stringArgument(input, "action")), {
+				...optionalObject(input, "input"),
+				...recordId === void 0 ? {} : { id: recordId }
+			});
+		}
+	}),
 	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/attachments_send.d.ts

@@ -3,5 +3,6 @@ declare const _default: import("eve/tools").ToolDefinition<Record<string, unknow
 } | {
     readonly error: string;
     readonly detail: string;
+    readonly reference: string;
 }>;
 export default _default;

package/package.json

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