@segmentstream/agent 0.13.0 → 0.15.0

package/dist/extension/lib/telegram/health.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 { t as agentBuild } from "../../../_chunks/build-metadata-BLeBanNg.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-CJlaXNhc.mjs";
 import { runtimeRequestFailure } from "./runtime-request.mjs";
 import { GET } from "eve/channels";
 const HEALTH_ROUTE = "/eve/v1/telegram/health";

package/dist/extension/lib/telegram/images.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 { p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 import { gateway, generateText } from "ai";
 const MAXIMUM_IMAGE_DESCRIPTION_BYTES = 5242880;
 const MAXIMUM_NATIVE_IMAGE_BYTES = 3145728;

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

@@ -60,6 +60,13 @@ export declare class InboundRequest {
     /** Finalize the reservation only after the durable inbox acknowledges delivery. */
     beginDispatch: (() => Promise<boolean>) | undefined;
     finishClaim: ((accepted: boolean) => Promise<void>) | undefined;
+    /** A known successful hook's continuation, bound to its admitted member. */
+    structuredContext: {
+        readonly text: string;
+        readonly memberId: string;
+    } | undefined;
+    recordStructuredContext: ((text: string, memberId: string) => Promise<void>) | undefined;
+    beginStructuredContinuation: (() => Promise<boolean>) | undefined;
     locale: string | undefined;
     threadId: string | undefined;
     /** The text the turn should carry instead of the parsed message, once a transcript exists. */

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

@@ -4,5 +4,5 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { i as withReplacedText, n as currentInboundRequest, r as runInboundRequest, t as InboundRequest } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { i as withReplacedText, n as currentInboundRequest, r as runInboundRequest, t as InboundRequest } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 export { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText };

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

@@ -1,3 +1,4 @@
+import { type StructuredInbound, type StructuredMessage, type StructuredResult } from "./structured.js";
 import type { RecentMessage } from "../group-routing/observed.js";
 import { type GroupPolicy } from "../group-routing/policy.js";
 import type { TelegramSettings } from "../../config.js";
@@ -41,6 +42,10 @@ import type { PdfTextExtractor } from "./pdf-text.js";
  *    its `<chat>` block.
  */
 export interface InboundDependencies {
+    readonly structured?: {
+        readonly configuration: StructuredInbound;
+        readonly run: (principal: import("eve/context").SessionAuthContext, memberId: string, message: TelegramMessage, event: StructuredMessage, beforeDispatch?: () => Promise<void>) => Promise<StructuredResult>;
+    };
     readonly policy: TelegramPolicy;
     readonly decisionModel?: string;
     readonly groups?: GroupPolicy;

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

@@ -6,16 +6,18 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { effectiveGroupPolicy, groupPolicy } from "../group-routing/policy.mjs";
 import { admitMessage, localizedText } from "../admission.mjs";
-import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
+import { d as telegramRuntimeSource, n as conversationLanguage, o as telegramPrincipal, u as runtimeEnvelope } from "../../../_chunks/principal-MEMlG3EG.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 import { addressingReason, conversationKey, otherRecipient } from "../group-routing/signals.mjs";
 import { conversationAddressing, conversationState } from "../group-routing/conversation.mjs";
 import { questionInvitation } from "../group-routing/engagement.mjs";
 import { conversationContext, routeMessage } from "../group-routing/router.mjs";
 import { observedContext } from "../group-routing/observed.mjs";
 import { debounceBurst, routingBurst } from "../group-routing/burst.mjs";
-import { p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
-import { AttachmentLifecycleNotPermitted, startTypingHeartbeat, typingUntilComplete } from "./lifecycle.mjs";
+import { WorkspaceActionAlreadyDispatched } from "./workspace-action.mjs";
+import { structuredMessage } from "./structured.mjs";
 import { formatAddress, messageAddress, scopedAddress } from "./sessions.mjs";
+import { AttachmentLifecycleNotPermitted, startTypingHeartbeat, typingUntilComplete } from "./lifecycle.mjs";
 import { contentShape, messageContent } from "./content.mjs";
 import { messageAudience } from "./audience.mjs";
 import { attachmentKind, messageMetadata } from "./observed.mjs";
@@ -225,13 +227,14 @@ async function handleInboundMessage(input) {
 		from: message.from,
 		attachments: inboundAttachments(message)
 	};
+	const structured = dependencies.structured === void 0 ? void 0 : structuredMessage(sent.raw, dependencies.structured.configuration.kinds);
 	const bot = await dependencies.bot(context.telegram);
 	const audience = messageAudience(sent, bot);
 	const signals = telegramSignals(sent, bot, dependencies.signalSettings);
 	const addressed = addressingReason(signals);
 	const elsewhere = otherRecipient(audience);
 	if (input.request?.edited) {
-		if (addressed === void 0 && !input.request.attachmentsChanged && (input.request.previousText ?? "").trim().replace(/\s+/gu, " ") === audience.originalText.trim().replace(/\s+/gu, " ")) {
+		if (structured === void 0 && addressed === void 0 && !input.request.attachmentsChanged && (input.request.previousText ?? "").trim().replace(/\s+/gu, " ") === audience.originalText.trim().replace(/\s+/gu, " ")) {
 			recordGateDecision("message_edit");
 			return null;
 		}
@@ -262,7 +265,7 @@ async function handleInboundMessage(input) {
 			reportTelegramError("identity_notice_failed", error, { provider: "telegram" });
 		}
 	});
-	const turn = addressed !== void 0 && hasContent && (addressed !== "reply-to-bot" || elsewhere === void 0);
+	const turn = structured === void 0 && input.request?.structuredContext === void 0 && addressed !== void 0 && hasContent && (addressed !== "reply-to-bot" || elsewhere === void 0);
 	const lookup = await resolve(turn);
 	const group = isGroupChat(sent);
 	const chat = conversationKey(signals);
@@ -334,7 +337,7 @@ async function handleInboundMessage(input) {
 		}
 	};
 	async function reject(refused, reply) {
-		const replied = hasContent && reply && (refused.status !== "limited" || refused.notify) ? await answerUnpaired({
+		const replied = (hasContent || structured !== void 0) && reply && (refused.status !== "limited" || refused.notify) ? await answerUnpaired({
 			context,
 			message: sent,
 			lookup: refused,
@@ -357,13 +360,28 @@ async function handleInboundMessage(input) {
 		return null;
 	}
 	let member = lookup.member;
-	let turnAdmitted = turn || !lookup.provisioned || member.roles.length !== 1 || member.roles[0] !== "member";
+	if (input.request?.structuredContext !== void 0 && input.request.structuredContext.memberId !== member.id) {
+		recordGateDecision("structured_context_actor_changed");
+		return null;
+	}
+	let turnAdmitted = turn || input.request?.structuredContext !== void 0 || !lookup.provisioned || member.roles.length !== 1 || member.roles[0] !== "member";
 	let admissionRefused = false;
+	let structuredClaimed = input.request?.structuredContext !== void 0;
 	async function admitTurn(reply) {
+		if (admissionRefused) return false;
+		if (structured !== void 0 && !structuredClaimed) {
+			if (input.request?.claimTurn !== void 0 && !await input.request.claimTurn()) {
+				admissionRefused = true;
+				recordGateDecision("message_already_handled");
+				return false;
+			}
+			structuredClaimed = true;
+		}
 		if (turnAdmitted) return true;
 		const admitted = await resolve(true);
 		if (admitted.status !== "existing" && admitted.status !== "created") {
 			admissionRefused = true;
+			if (structuredClaimed) await input.request?.finishClaim?.(false);
 			await reject(admitted, reply);
 			return false;
 		}
@@ -474,7 +492,7 @@ async function handleInboundMessage(input) {
 	].filter((n) => !!n)];
 	const freshConversation = async () => dependencies.recentConversation ? dependencies.recentConversation(sent.chat.id, sent.messageThreadId === void 0 ? void 0 : String(sent.messageThreadId)) : dependencies.observed.recent(chat);
 	let conversationRecent = conversationPolicy ? await freshConversation() : dependencies.observed.recent(chat);
-	if (conversationPolicy && input.request && input.request.lifecycleKey === void 0) {
+	if (conversationPolicy && input.request && input.request.lifecycleKey === void 0 && input.request.structuredContext === void 0) {
 		address = topicAddress;
 		input.request.address = topicAddress;
 		input.request.turnPolicy = "steer";
@@ -503,12 +521,12 @@ async function handleInboundMessage(input) {
 		address = pending.address || (questionSession === void 0 ? topicAddress : memberQuestionAddress);
 		input.request.address = address;
 	}
-	if (input.request?.lifecycleKey === void 0 && group && (addressed === void 0 && !answering && groups.mode === "mention" || !conversationPolicy && elsewhere !== void 0 && (addressed === void 0 || addressed === "reply-to-bot" && !recipientAnswer))) {
+	if (input.request?.lifecycleKey === void 0 && input.request?.structuredContext === void 0 && group && (addressed === void 0 && !answering && groups.mode === "mention" || !conversationPolicy && elsewhere !== void 0 && (addressed === void 0 || addressed === "reply-to-bot" && !recipientAnswer))) {
 		await recordInboundContent({
 			text,
 			decoded
 		});
-		dependencies.observed.add(chat, observedMessage(sent, text || "[attachment]", member, void 0, bot));
+		dependencies.observed.add(chat, observedMessage(sent, text || (structured === void 0 ? "[attachment]" : `[${structured.kind}]`), member, void 0, bot));
 		recordRouteDecision("observe", addressed, groups.mode, {
 			reason: elsewhere === void 0 ? "mention_policy" : "other_recipient",
 			note: elsewhere ?? "Mention policy observes unaddressed messages."
@@ -526,6 +544,9 @@ async function handleInboundMessage(input) {
 	const mediaPlan = voice !== void 0 || sent.attachments.length > 0 || dependencies.observed.list(chat).some((message) => (message.images?.length ?? 0) > 0) ? await dependencies.mediaPlan?.(member, owner?.id) : void 0;
 	if (voice !== void 0 && !group) await transcribeVoice(false);
 	if (voice !== void 0 && mediaPlan?.audio) notes.push("[The chat model supports audio, but this host cannot deliver native audio. The configured speech-to-text fallback was used if enabled.]");
+	if (structured !== void 0) {
+		if (text.trim() === "") text = `[${structured.kind}]`;
+	}
 	if (text.trim() === "" && sent.attachments.length === 0) {
 		console.info("[segmentstream] Telegram message has no readable content", {
 			chatId: sent.chat.id,
@@ -603,7 +624,7 @@ async function handleInboundMessage(input) {
 		return question;
 	};
 	let burstId;
-	if (conversationPolicy && input.request?.lifecycleKey === void 0) {
+	if (conversationPolicy && input.request?.lifecycleKey === void 0 && input.request?.structuredContext === void 0) {
 		if (voice !== void 0) await transcribeVoice(true);
 		const routingSignals = {
 			...policySignals,
@@ -644,7 +665,7 @@ async function handleInboundMessage(input) {
 			messagesToClassify: burst.messages
 		};
 	}
-	const route = input.request?.lifecycleKey !== void 0 ? "reply" : await routeMessage({
+	const route = input.request?.lifecycleKey !== void 0 || input.request?.structuredContext !== void 0 ? "reply" : await routeMessage({
 		chatId: sent.chat.id,
 		memberId: member.id,
 		policy: groups.mode,
@@ -728,6 +749,74 @@ async function handleInboundMessage(input) {
 			return conversation();
 		}
 	});
+	let structuredDispatched = false;
+	if (structured !== void 0 && dependencies.structured !== void 0) {
+		if (route === "observe" || admissionRefused) {
+			await recordInboundContent({
+				text,
+				decoded
+			});
+			if (group) dependencies.observed.add(chat, observedMessage(sent, text, member, media, bot));
+			return null;
+		}
+		if (!await admitTurn(true)) return null;
+		const retained = input.request?.structuredContext;
+		let result;
+		if (retained !== void 0) {
+			structuredDispatched = true;
+			result = { context: retained.text };
+		} else {
+			const principal = telegramPrincipal({
+				message: sent,
+				member
+			});
+			try {
+				result = await dependencies.structured.run(principal, member.id, sent, structured, async () => {
+					if (input.request?.beginDispatch !== void 0 && !await input.request.beginDispatch()) throw new WorkspaceActionAlreadyDispatched("structured_action_already_dispatched");
+					structuredDispatched = true;
+				});
+			} catch (error) {
+				try {
+					await input.request?.finishClaim?.(false);
+				} catch (cleanupError) {
+					reportTelegramError("workspace_structured_claim_release_failed", new AggregateError([error, cleanupError], "Structured action and claim cleanup failed"));
+				}
+				if (error instanceof WorkspaceActionAlreadyDispatched) {
+					recordGateDecision("message_already_handled");
+					return null;
+				}
+				throw error;
+			}
+			if (result.complete !== true && result.context?.trim()) {
+				if (input.request !== void 0) input.request.structuredContext = {
+					text: result.context,
+					memberId: member.id
+				};
+				try {
+					if (input.request?.recordStructuredContext === void 0) throw new Error("A structured continuation requires durable conversation capture.");
+					await input.request.recordStructuredContext(result.context, member.id);
+				} catch (error) {
+					reportTelegramError("workspace_structured_context_recording_failed", error);
+				}
+			} else try {
+				await input.request?.finishClaim?.(true);
+			} catch (error) {
+				reportTelegramError("workspace_structured_admission_recording_failed", error);
+			}
+			if (result.acknowledgement?.trim()) try {
+				await context.telegram.post(result.acknowledgement);
+			} catch (error) {
+				reportTelegramError("workspace_structured_ack_failed", error, {
+					chatId: sent.chat.id,
+					messageId: sent.messageId
+				});
+			}
+		}
+		recordGateDecision("workspace_structured_inbound", result.context ? "reply" : "silent");
+		if (result.complete === true || !result.context?.trim()) return null;
+		text = result.context;
+		if (input.request !== void 0) input.request.text = text;
+	}
 	if (input.request?.lifecycleKey !== void 0) recordRouteDecision("reply", addressed, groups.mode, {
 		reason: "workspace_attachment_lifecycle",
 		note: "The configured workspace action admitted this attachment task."
@@ -757,6 +846,7 @@ async function handleInboundMessage(input) {
 		} : mediaPlan },
 		...dependencies.describeImage === void 0 ? {} : { describeImage: dependencies.describeImage }
 	});
+	if (input.request !== void 0) input.request.files = files;
 	if (input.request?.lifecycle !== void 0) {
 		const lifecycle = input.request.lifecycle;
 		const key = input.request.lifecycleKey;
@@ -787,7 +877,10 @@ async function handleInboundMessage(input) {
 					outcome = { result: (await dependencies.attachments.promote({
 						memberId: member.id,
 						conversation: `telegram:${sent.chat.id}`
-					}, file.attachment.id, stored.retain)).result };
+					}, file.attachment.id, {
+						...stored.retain,
+						runtime: runtimeEnvelope({ source: telegramRuntimeSource(sent, files) })
+					})).result };
 				} catch (error) {
 					outcome = { error: reportTelegramError("attachment_retention_failed", error, { attachmentId: file.attachment.id }) };
 				}
@@ -866,7 +959,7 @@ async function handleInboundMessage(input) {
 		});
 		return null;
 	}
-	if (input.request?.claimTurn !== void 0 && !await input.request.claimTurn()) {
+	if (!structuredDispatched && input.request?.claimTurn !== void 0 && !await input.request.claimTurn()) {
 		recordGateDecision("message_already_handled");
 		return null;
 	}
@@ -957,7 +1050,8 @@ async function handleInboundMessage(input) {
 	}
 	const language = conversationLanguage([text, ...dependencies.observed.recent(chat).map((message) => message.text).reverse()]);
 	const sharedContext = group ? conversationContext(await conversation()) : void 0;
-	if (input.request?.beginDispatch !== void 0 && !await input.request.beginDispatch()) {
+	const beginTurnDispatch = structuredDispatched ? input.request?.beginStructuredContinuation : input.request?.beginDispatch;
+	if (beginTurnDispatch !== void 0 && !await beginTurnDispatch()) {
 		recordGateDecision("message_already_handled");
 		return null;
 	}
@@ -970,7 +1064,7 @@ async function handleInboundMessage(input) {
 		member,
 		conversationLanguage: language
 	});
-	if (conversationPolicy && input.request?.lifecycleKey === void 0) principal = {
+	if (conversationPolicy && input.request?.lifecycleKey === void 0 && input.request?.structuredContext === void 0) principal = {
 		...principal,
 		attributes: {
 			...principal.attributes,

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

@@ -4,16 +4,21 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import { t as agentBuild } from "../../../_chunks/build-metadata-BLeBanNg.mjs";
+import { d as telegramRuntimeSource, l as principalRuntimeSource, u as runtimeEnvelope } from "../../../_chunks/principal-MEMlG3EG.mjs";
 import { object } from "../confirmation-description.mjs";
-import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 import { needsConfirmation } from "../confirmations.mjs";
 import { OntologyActionNotPermitted, actionToolName, ontologyTools } from "../ontology-tools.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-CJlaXNhc.mjs";
 var AttachmentLifecycleNotPermitted = class extends Error {
 	code = "attachment_lifecycle_not_permitted";
 };
 function attachmentLifecycle(options) {
-	const tools = ontologyTools(options);
+	const source = () => options.message.raw === void 0 ? principalRuntimeSource(options.principal) : telegramRuntimeSource({
+		...options.message,
+		attachments: options.message.attachments ?? [],
+		raw: options.message.raw
+	}, currentInboundRequest()?.files);
 	const action = actionToolName(options.configuration.entity, options.configuration.action);
 	return async (phase, data = {}) => {
 		console.info("[segmentstream] telegram.phase", {
@@ -40,6 +45,13 @@ function attachmentLifecycle(options) {
 				...options.configuration.contextVersion === 2 && typeof options.message.raw?.date === "number" && Number.isSafeInteger(options.message.raw.date) && options.message.raw.date > 0 ? { source_at: options.message.raw.date * 1e3 } : {}
 			}
 		};
+		const tools = ontologyTools({
+			...options,
+			envelope: runtimeEnvelope({
+				principal: options.principal,
+				source: source()
+			})
+		});
 		const labels = await tools.labels(options.memberId, action, input).catch((error) => {
 			throw error instanceof OntologyActionNotPermitted ? new AttachmentLifecycleNotPermitted("The sender may not run the lifecycle action.", { cause: error }) : error;
 		});

package/dist/extension/lib/telegram/media-policy.mjs

@@ -5,7 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { DEFAULT_IMAGE_DESCRIPTION_MODEL } from "../../config.mjs";
-import { p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 function planMedia(capabilities, descriptionModel = null) {
 	if (typeof descriptionModel === "string") return {
 		images: "describe",

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

@@ -14,6 +14,7 @@ export declare function telegramPrincipal(input: {
     };
     readonly member: PairedMember;
     readonly conversationLanguage?: string;
+    readonly callbackQueryId?: 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;

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

@@ -4,53 +4,5 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-const TELEGRAM_AUTHENTICATOR = "segmentstream-telegram";
-function isGroup(message) {
-	return message.chat.type === "group" || message.chat.type === "supergroup";
-}
-function telegramPrincipal(input) {
-	const { message, member } = input;
-	const sender = message.from.id;
-	const attributes = {
-		memberId: member.id,
-		identityProvider: "telegram",
-		roles: member.roles,
-		chatId: message.chat.id,
-		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;
-	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",
-		principalId: isGroup(message) ? `telegram:${message.chat.id}:${sender}` : `telegram:${sender}`,
-		principalType: "user",
-		subject: sender,
-		attributes
-	};
-}
-function conversationLanguage(texts) {
-	for (const text of texts) {
-		if (/[\u0430-\u044f\u0451]/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;
-}
-function rolesOf(principal) {
-	const roles = principal?.attributes.roles;
-	if (typeof roles === "string") return [roles];
-	return roles ?? [];
-}
-function identityProviderOf(principal) {
-	const provider = principal?.attributes.identityProvider;
-	return typeof provider === "string" && provider !== "" ? provider : void 0;
-}
+import { a as rolesOf, i as memberIdOf, n as conversationLanguage, o as telegramPrincipal, r as identityProviderOf, t as TELEGRAM_AUTHENTICATOR } from "../../../_chunks/principal-MEMlG3EG.mjs";
 export { TELEGRAM_AUTHENTICATOR, conversationLanguage, identityProviderOf, memberIdOf, rolesOf, telegramPrincipal };

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

@@ -1,5 +1,6 @@
 import type { TelegramMessage } from "eve/channels/telegram";
-import type { CancelTurnResult } from "eve/channels";
+import type { CancelTurnResult, ChannelSource } from "eve/channels";
+import type { TelegramChannelState } from "eve/channels/telegram";
 import type { SessionSettings } from "../../config.js";
 /**
  * Session policy for the Telegram channel (`agent-design.md`, section 4, and docs/agent.md,
@@ -62,6 +63,7 @@ export interface SessionOperations {
         }) => Promise<CancelTurnResult>;
     } | undefined>;
     readonly from: (address: string) => {
+        readonly send?: ChannelSource<TelegramChannelState>["send"];
         compact(): Promise<unknown>;
         clear(): Promise<unknown>;
     };

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

@@ -4,12 +4,12 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
-import "./principal.mjs";
-import { agentMessage, observedChatKey } from "../group-routing/observed.mjs";
+import "../../../_chunks/principal-MEMlG3EG.mjs";
 import { confirmationLocale } from "./confirmation-text.mjs";
 import { splitTelegramText } from "./format.mjs";
 import { inTelegramSendQueue } from "./send-queue.mjs";
-import { a as TelegramDeliveryError, l as customerMessage, o as currentLocale, p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { a as TelegramDeliveryError, l as customerMessage, o as currentLocale, p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
+import { agentMessage, observedChatKey } from "../group-routing/observed.mjs";
 const SILENT_MARKERS = new Set(["[silent]", "no_reply"]);
 function isSilentReply(text) {
 	return SILENT_MARKERS.has(text.trim().toLowerCase());

package/dist/extension/lib/telegram/structured-settings.d.ts

@@ -0,0 +1,6 @@
+import type { WorkspaceActionHook } from "./workspace-action.js";
+export declare const STRUCTURED_KINDS: readonly ["location", "venue", "contact"];
+export type StructuredKind = (typeof STRUCTURED_KINDS)[number];
+export interface StructuredInbound extends WorkspaceActionHook {
+    readonly kinds: ReadonlyArray<StructuredKind>;
+}

package/dist/extension/lib/telegram/structured-settings.mjs

@@ -0,0 +1,12 @@
+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);
+const STRUCTURED_KINDS = [
+	"location",
+	"venue",
+	"contact"
+];
+export { STRUCTURED_KINDS };

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

@@ -0,0 +1,28 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import type { SessionAuthContext } from "eve/context";
+import type { Environment } from "../environment.js";
+import type { RuntimeToken } from "../runtime-token.js";
+import type { StructuredInbound, StructuredKind } from "./structured-settings.js";
+export { STRUCTURED_KINDS, type StructuredInbound, type StructuredKind, } from "./structured-settings.js";
+export interface StructuredMessage {
+    readonly kind: StructuredKind;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+export interface StructuredResult {
+    readonly acknowledgement?: string;
+    readonly context?: string;
+    readonly complete?: boolean;
+}
+/** Just declared provider fields, bounded to 16 KiB; unknown kinds and malformed payloads stay undispatched. */
+export declare function structuredMessage(raw: Readonly<Record<string, unknown>>, kinds: ReadonlyArray<StructuredKind>): StructuredMessage | undefined;
+export declare function dispatchStructuredMessage(input: {
+    readonly configuration: StructuredInbound;
+    readonly event: StructuredMessage;
+    readonly principal: SessionAuthContext;
+    readonly memberId: string;
+    readonly message: TelegramMessage;
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+    readonly beforeDispatch?: () => Promise<void>;
+}): Promise<StructuredResult>;

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

@@ -0,0 +1,114 @@
+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 { STRUCTURED_KINDS } from "./structured-settings.mjs";
+import { d as telegramRuntimeSource, u as runtimeEnvelope } from "../../../_chunks/principal-MEMlG3EG.mjs";
+import { workspaceAction } from "./workspace-action.mjs";
+const record = (value) => {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid structured Telegram object.");
+	return value;
+};
+function text(value, maximum) {
+	if (typeof value !== "string" || value.length > maximum) throw new Error("Invalid structured Telegram text field.");
+	return value;
+}
+function numeric(value, minimum, maximum, integer = false) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum || integer && !Number.isSafeInteger(value)) throw new Error("Invalid structured Telegram number field.");
+	return value;
+}
+function location(value) {
+	const data = record(value);
+	const result = {
+		latitude: numeric(data.latitude, -90, 90),
+		longitude: numeric(data.longitude, -180, 180)
+	};
+	for (const [key, minimum, maximum, integer] of [
+		[
+			"horizontal_accuracy",
+			0,
+			1500,
+			false
+		],
+		[
+			"live_period",
+			0,
+			2 ** 31 - 1,
+			true
+		],
+		[
+			"heading",
+			1,
+			360,
+			true
+		],
+		[
+			"proximity_alert_radius",
+			0,
+			1e5,
+			true
+		]
+	]) if (data[key] !== void 0) result[key] = numeric(data[key], minimum, maximum, integer);
+	return result;
+}
+function structuredMessage(raw, kinds) {
+	for (const kind of [
+		"venue",
+		"contact",
+		"location"
+	]) {
+		if (raw[kind] === void 0) continue;
+		if (!kinds.includes(kind)) return;
+		try {
+			const input = record(raw[kind]);
+			const data = kind === "location" ? location(input) : kind === "venue" ? {
+				location: location(input.location),
+				title: text(input.title, 1024),
+				address: text(input.address, 1024)
+			} : {
+				phone_number: text(input.phone_number, 256),
+				first_name: text(input.first_name, 256)
+			};
+			if (kind === "venue") {
+				for (const key of [
+					"foursquare_id",
+					"foursquare_type",
+					"google_place_id",
+					"google_place_type"
+				]) if (input[key] !== void 0) data[key] = text(input[key], 1024);
+			}
+			if (kind === "contact") {
+				for (const [key, maximum] of [["last_name", 256], ["vcard", 16384]]) if (input[key] !== void 0) data[key] = text(input[key], maximum);
+				if (input.user_id !== void 0) data.user_id = numeric(input.user_id, 0, Number.MAX_SAFE_INTEGER, true);
+			}
+			if (new TextEncoder().encode(JSON.stringify(data)).byteLength <= 16384) return {
+				kind,
+				data
+			};
+		} catch {
+			return;
+		}
+	}
+}
+async function dispatchStructuredMessage(input) {
+	const source = telegramRuntimeSource(input.message);
+	const result = await workspaceAction({
+		...input,
+		input: {
+			...input.event,
+			source
+		},
+		envelope: runtimeEnvelope({
+			principal: input.principal,
+			source
+		})
+	});
+	return {
+		...typeof result.acknowledgement === "string" && result.acknowledgement.trim() !== "" && result.acknowledgement.length <= 4096 ? { acknowledgement: result.acknowledgement } : {},
+		...typeof result.context === "string" && result.context.length <= 16384 ? { context: result.context } : {},
+		...typeof result.complete === "boolean" ? { complete: result.complete } : {}
+	};
+}
+export { STRUCTURED_KINDS, dispatchStructuredMessage, structuredMessage };

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

@@ -5,9 +5,9 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { telegramText } from "./texts.mjs";
-import { memberIdOf } from "./principal.mjs";
+import { i as memberIdOf } from "../../../_chunks/principal-MEMlG3EG.mjs";
 import { confirmationLocale } from "./confirmation-text.mjs";
-import { c as customerCopy, d as failureText, o as currentLocale, p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { c as customerCopy, d as failureText, o as currentLocale, p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 const telegramFailureEvents = {
 	async "authorization.required"(event, channel, context) {
 		if (event.candidateId !== void 0) return;

package/dist/extension/lib/telegram/voice.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 { p as reportTelegramError } from "../../../_chunks/inbound-request-BXhiIph-.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-RIRNBxUC.mjs";
 import "../connection-proxy.mjs";
 import { gateway, transcribe } from "ai";
 const LABELS = {