@segmentstream/agent 0.8.1 → 0.8.3

package/dist/extension/lib/telegram/attachment-description.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-BwBvXk0A.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 import { describableImage } from "./images.mjs";
 import { MAXIMUM_ROUTING_PDF_CHARACTERS, extractRoutingPdf } from "./pdf-text.mjs";
 import { gateway, generateText } from "ai";

package/dist/extension/lib/telegram/attachments-send.mjs

@@ -6,11 +6,11 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin, channelsEnabled, proxyEnvironment } from "../environment.mjs";
 import "./principal.mjs";
-import { confirmationLocale } from "./confirmation-text.mjs";
 import { redactDiagnostic } from "../diagnostics.mjs";
-import { runtimeToken } from "../runtime-token.mjs";
+import { confirmationLocale } from "./confirmation-text.mjs";
 import { inTelegramSendQueue, telegramSendScope } from "./send-queue.mjs";
-import { c as customerCopy, f as formattingRefused, l as customerMessage, p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
+import { c as customerCopy, f as formattingRefused, l as customerMessage, p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
+import { runtimeToken } from "../runtime-token.mjs";
 import { MAXIMUM_PROXY_BODY_BYTES, connectionProxy } from "../connection-proxy.mjs";
 import { ACT_AS_HEADER } from "../ontology-connection.mjs";
 import { AttachmentError, CONVERSATION_HEADER, SESSION_HEADER } from "../attachments.mjs";

package/dist/extension/lib/telegram/confirmation-expiry.mjs

@@ -5,11 +5,11 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { proxyEnvironment } from "../environment.mjs";
+import { telegramSendScope } from "./send-queue.mjs";
+import { m as safeTelegramFetch, p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
 import { deferredConfirmations } from "../deferred-confirmations.mjs";
 import { conversations } from "../conversations.mjs";
-import { telegramSendScope } from "./send-queue.mjs";
-import { m as safeTelegramFetch, p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { expireDeferredRecord } from "./deferred-confirmations.mjs";
 import { connectionProxy } from "../connection-proxy.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";

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

@@ -52,7 +52,7 @@ function confirmationCopy(value) {
 function renderConfirmation(description, copy) {
 	copy = confirmationCopy(copy);
 	const action = humanText(description?.action);
-	if (description !== void 0 && (action === void 0 || action === "❓")) throw new Error("A confirmation requires a safe declared action title.");
+	if (description === void 0 || action === void 0 || action === "❓") throw new Error("A confirmation requires a safe declared action title.");
 	const facts = [[description?.warning ? "⚠️" : "", action].filter(Boolean).join(" "), ...(description?.fields ?? []).map(({ label, value }) => {
 		if (value.length > 3584) throw new Error("The complete confirmation facts cannot fit in one Telegram message.");
 		const safeLabel = humanText(label);

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

@@ -7,11 +7,11 @@ __eveCreateRequire(import.meta.url);
 import { memberIdOf, telegramPrincipal } from "./principal.mjs";
 import { humanText } from "../confirmation-description.mjs";
 import { renderConfirmation, withConfirmationText } from "./confirmation-text.mjs";
-import { chatPostOperationId, isChatPost } from "../chat-post-confirmation.mjs";
 import { chatPostCard, chatPostCardStatus, chatPostReceipt, withChatPostCard } from "./chat-post-card.mjs";
+import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
+import { chatPostOperationId, isChatPost } from "../chat-post-confirmation.mjs";
 import { confirmations } from "../confirmations.mjs";
 import { conversationEvent } from "../conversations.mjs";
-import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { formatAddress, scopedAddress } from "./sessions.mjs";
 import { agentMessage, observedChatKey, withConfirmationPrompt } from "./observed.mjs";
 import { postDeferredCard } from "./deferred-confirmations.mjs";

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

@@ -17,7 +17,7 @@ export declare function telegramRecord(value: unknown): Readonly<Record<string,
 export declare function messageContent(raw: Readonly<Record<string, unknown>>): MessageContent;
 /** Only shape/size diagnostics: do not retain/log raw webhook bodies, URLs or credential values. */
 export declare function contentShape(raw: Readonly<Record<string, unknown>>, content?: MessageContent): {
-    contentSource: "none" | "text" | "caption" | "rich_message";
+    contentSource: "text" | "caption" | "none" | "rich_message";
     textType: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
     captionType: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
     hasRichMessage: boolean;

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

@@ -4,8 +4,8 @@ import { createRequire as __eveCreateRequire } from "node:module";
 const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
+import { n as currentInboundRequest, s as currentThreadId } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 import { conversationEvent } from "../conversations.mjs";
-import { n as currentInboundRequest, s as currentThreadId } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { contentShape, messageContent } from "./content.mjs";
 import { currentConfirmationPrompt, messageMetadata, observedChatKey } from "./observed.mjs";
 import { archivedRoutingMessages } from "./routing-context.mjs";

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

@@ -1,7 +1,7 @@
 import { type TelegramPreviewContext } from "@segmentstream-cloud/ontology/telegram";
 import { type TelegramText } from "./format.js";
 export { isTechnicalText } from "../customer-text-safety.js";
-export declare function withDeliveryLocale<T>(locale: string, run: () => T, threadId?: string): T;
+export declare function withDeliveryLocale<T>(locale: string, run: () => T, threadId?: string, replyTo?: string, chatId?: string): T;
 export declare function currentLocale(): string;
 export declare function currentThreadId(): string | undefined;
 export declare function customerCopy(): {

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

@@ -5,5 +5,5 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { isTechnicalText } from "../customer-text-safety.mjs";
-import { a as TelegramDeliveryError, c as customerCopy, d as failureText, f as formattingRefused, h as withDeliveryLocale, l as customerMessage, m as safeTelegramFetch, o as currentLocale, p as reportTelegramError, s as currentThreadId, u as customerText } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
+import { a as TelegramDeliveryError, c as customerCopy, d as failureText, f as formattingRefused, h as withDeliveryLocale, l as customerMessage, m as safeTelegramFetch, o as currentLocale, p as reportTelegramError, s as currentThreadId, u as customerText } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 export { TelegramDeliveryError, currentLocale, currentThreadId, customerCopy, customerMessage, customerText, failureText, formattingRefused, isTechnicalText, reportTelegramError, safeTelegramFetch, withDeliveryLocale };

package/dist/extension/lib/telegram/deferred-confirmations.mjs

@@ -7,12 +7,12 @@ __eveCreateRequire(import.meta.url);
 import { telegramPrincipal } from "./principal.mjs";
 import { humanText } from "../confirmation-description.mjs";
 import { renderConfirmation, withConfirmationText } from "./confirmation-text.mjs";
-import { confirmationOutcome } from "../confirmation-outcome.mjs";
 import { chatPostCard, chatPostCardStatus, chatPostReceipt, withChatPostCard } from "./chat-post-card.mjs";
+import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 import { CONFIRMATION_TTL_MS, inputHash } from "../confirmations.mjs";
+import { confirmationOutcome } from "../confirmation-outcome.mjs";
 import { deferredConfirmations, deferredKey, runDeferredAction } from "../deferred-confirmations.mjs";
 import { conversationEvent } from "../conversations.mjs";
-import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { formatAddress } from "./sessions.mjs";
 import { agentMessage, observedChatKey, withConfirmationPrompt } from "./observed.mjs";
 import { telegramTextLinks } from "@segmentstream-cloud/ontology/telegram";

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

@@ -5,7 +5,7 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { conversationLanguage } from "./principal.mjs";
-import { d as failureText, p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
+import { d as failureText, p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 import { describableImage, describeReceivedImage } from "./images.mjs";
 import { MAXIMUM_ATTACHMENT_BYTES, attachmentUrl } from "../attachments.mjs";
 function telegramConversation(chatId) {

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

@@ -4,6 +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-BLyaHLJW.mjs";
 import { runtimeRequestFailure } from "./runtime-request.mjs";
 import { GET } from "eve/channels";
 const HEALTH_ROUTE = "/eve/v1/telegram/health";
@@ -14,7 +15,8 @@ function healthRoute(input) {
 		const registry = input.chats.health();
 		return Response.json({
 			status: registry.degraded ? "degraded" : "ok",
-			registry
+			registry,
+			runtime: agentBuild()
 		}, {
 			status: registry.degraded ? 503 : 200,
 			headers: { "cache-control": "no-store" }

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-BwBvXk0A.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.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

@@ -29,7 +29,16 @@ export declare class InboundRequest {
     /** The agent's description from the compiled manifest, for the routing decision. */
     readonly agentDescription: () => Promise<string>;
     readonly agentName: () => Promise<string>;
+    readonly traceId: `${string}-${string}-${string}-${string}-${string}`;
     edited: boolean;
+    triggeringMessageId: string | undefined;
+    chatId: string | undefined;
+    replyTo: string | undefined;
+    stopTyping: (() => void) | undefined;
+    lifecycle: ReturnType<typeof import("./lifecycle.js").attachmentLifecycle> | undefined;
+    lifecycleKey: string | undefined;
+    lifecycleContext: string | undefined;
+    monitor: ((session: Awaited<ReturnType<ChannelSource<unknown>["send"]>>, marker: string) => void) | undefined;
     previousText: string | undefined;
     attachmentsChanged: boolean;
     /** Evidence may be reused only while the provider attachment identities are unchanged. */
@@ -58,6 +67,8 @@ export declare class InboundRequest {
     extraFiles: Exclude<UserContent, string> | undefined;
     /** The route's session operations, on addresses already mapped to the configured scope. */
     sessions: SessionOperations | undefined;
+    /** Host background lifetime; long-running observers must never enter the routing drain. */
+    backgroundUntil: ((task: Promise<unknown>) => void) | 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. */

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-BwBvXk0A.mjs";
+import { i as withReplacedText, n as currentInboundRequest, r as runInboundRequest, t as InboundRequest } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 export { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText };

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

@@ -1,3 +1,4 @@
+import { attachmentLifecycle } from "./lifecycle.js";
 import type { TelegramContext, TelegramInboundResult, TelegramMessage } from "eve/channels/telegram";
 import type { AdmissionSettings, SessionSettings, TelegramPolicy } from "../../config.js";
 import type { AgentAttachments } from "../attachments.js";
@@ -38,6 +39,7 @@ import type { PdfTextExtractor } from "./pdf-text.js";
  */
 export interface InboundDependencies {
     readonly policy: TelegramPolicy;
+    readonly lifecycle?: (principal: import("eve/context").SessionAuthContext, memberId: string, message: TelegramMessage) => ReturnType<typeof attachmentLifecycle>;
     readonly admission: () => AdmissionSettings;
     readonly sessions: () => SessionSettings;
     readonly sessionPolicy: SessionPolicy;

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

@@ -5,7 +5,8 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
-import { p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
+import { startTypingHeartbeat, typingUntilComplete } from "./lifecycle.mjs";
 import { formatAddress, messageAddress, scopedAddress } from "./sessions.mjs";
 import { contentShape, messageContent } from "./content.mjs";
 import { messageAudience, otherRecipient } from "./audience.mjs";
@@ -363,6 +364,65 @@ async function handleInboundMessage(input) {
 		turnAdmitted = true;
 		return true;
 	}
+	if (input.request !== void 0 && sent.attachments.length > 0 && dependencies.lifecycle !== void 0 && await admitTurn(true)) {
+		const principal = telegramPrincipal({
+			message: sent,
+			member
+		});
+		input.request.lifecycle = dependencies.lifecycle(principal, member.id, sent);
+		input.request.stopTyping = startTypingHeartbeat(context.telegram);
+		try {
+			const admitted = await input.request.lifecycle("admitted", { attachments: sent.attachments.map((file) => ({
+				id: file.fileId,
+				filename: file.fileName ?? file.kind,
+				mediaType: file.mediaType,
+				kind: file.kind
+			})) });
+			input.request.lifecycleKey = admitted.key;
+			input.request.replyTo = admitted.replyTo ?? sent.messageId;
+			if (admitted.key === void 0) input.request.lifecycle = void 0;
+			if (admitted.acknowledgement) try {
+				await context.telegram.post({
+					text: admitted.acknowledgement,
+					reply_parameters: { message_id: Number(input.request.replyTo) }
+				});
+				console.info("[segmentstream] telegram.phase", {
+					phase: "acknowledged",
+					at: new Date().toISOString(),
+					traceId: input.request.traceId,
+					intakeId: admitted.key,
+					chatId: sent.chat.id,
+					messageId: sent.messageId
+				});
+			} catch (error) {
+				reportTelegramError("intake_acknowledgement_failed", error, {
+					chatId: sent.chat.id,
+					messageId: sent.messageId
+				});
+			}
+		} catch (error) {
+			reportTelegramError("intake_admission_failed", error, {
+				chatId: sent.chat.id,
+				messageId: sent.messageId
+			});
+			input.request.lifecycle = void 0;
+		}
+	}
+	if (input.request !== void 0) {
+		input.request.triggeringMessageId = sent.messageId;
+		input.request.chatId = sent.chat.id;
+		input.request.replyTo ??= sent.messageId;
+		input.request.monitor = (session, marker) => {
+			input.request?.backgroundUntil?.(typingUntilComplete(session, marker, context.telegram, AbortSignal.timeout(6e5), {
+				traceId: input.request?.traceId,
+				intakeId: input.request?.lifecycleKey,
+				chatId: sent.chat.id,
+				messageId: sent.messageId
+			}).catch((error) => {
+				reportTelegramError("typing_monitor_failed", error, { sessionId: session.id });
+			}));
+		};
+	}
 	let address = scopedAddress(messageAddress(sent), dependencies.sessions().scope);
 	const operations = input.request?.sessions;
 	const topicAddress = formatAddress({
@@ -380,7 +440,7 @@ async function handleInboundMessage(input) {
 	const owner = questionSession ?? await operations?.resolveSession(address) ?? await operations?.resolveSession(topicAddress);
 	const questionHistory = owner === void 0 || dependencies.history === void 0 ? [] : await dependencies.history(owner.id);
 	const pending = questionFromHistory(questionHistory, questionOwner);
-	let answering = pending !== void 0 && pending.memberId === member.id && pending.chatId === sent.chat.id && pending.messageThreadId === String(sent.messageThreadId ?? "");
+	let answering = pending !== void 0 && (input.request?.lifecycleKey === void 0 || pending.taskId === input.request.lifecycleKey) && pending.memberId === member.id && pending.chatId === sent.chat.id && pending.messageThreadId === String(sent.messageThreadId ?? "");
 	const asked = questionHistory.findLast((event) => {
 		const data = isRecord(event.data) ? event.data : {};
 		const result = isRecord(data.result) ? data.result : {};
@@ -393,7 +453,7 @@ async function handleInboundMessage(input) {
 		address = pending.address || (questionSession === void 0 ? topicAddress : memberQuestionAddress);
 		input.request.address = address;
 	}
-	if (group && (addressed === void 0 && !answering && dependencies.policy === "mention" || elsewhere !== void 0 && (addressed === void 0 || addressed === "reply-to-bot" && !recipientAnswer))) {
+	if (input.request?.lifecycleKey === void 0 && group && (addressed === void 0 && !answering && dependencies.policy === "mention" || elsewhere !== void 0 && (addressed === void 0 || addressed === "reply-to-bot" && !recipientAnswer))) {
 		await recordInboundContent({
 			text,
 			decoded
@@ -481,7 +541,7 @@ async function handleInboundMessage(input) {
 		};
 		return question;
 	};
-	const route = await routeMessage({
+	const route = input.request?.lifecycleKey !== void 0 ? "reply" : await routeMessage({
 		chatId: sent.chat.id,
 		memberId: member.id,
 		policy: dependencies.policy,
@@ -539,6 +599,10 @@ async function handleInboundMessage(input) {
 			return conversation();
 		}
 	});
+	if (input.request?.lifecycleKey !== void 0) recordRouteDecision("reply", addressed, dependencies.policy, {
+		reason: "workspace_attachment_lifecycle",
+		note: "The configured workspace action admitted this attachment task."
+	});
 	if (admissionRefused) {
 		await recordInboundContent({
 			text,
@@ -564,6 +628,66 @@ async function handleInboundMessage(input) {
 		} : mediaPlan },
 		...dependencies.describeImage === void 0 ? {} : { describeImage: dependencies.describeImage }
 	});
+	if (input.request?.lifecycle !== void 0) {
+		const lifecycle = input.request.lifecycle;
+		const key = input.request.lifecycleKey;
+		for (const [sourceFile, file] of files.entries()) {
+			if (file.status === "refused") {
+				await lifecycle("stored", {
+					key,
+					sourceFile,
+					error: {
+						filename: file.filename,
+						reason: file.reason
+					}
+				});
+				continue;
+			}
+			const stored = await lifecycle("stored", {
+				key,
+				sourceFile,
+				attachment: {
+					id: file.attachment.id,
+					filename: file.attachment.filename,
+					sha256: file.attachment.sha256
+				}
+			});
+			if (stored.retain !== void 0 && dependencies.attachments !== void 0) {
+				let outcome;
+				try {
+					outcome = { result: (await dependencies.attachments.promote({
+						memberId: member.id,
+						conversation: `telegram:${sent.chat.id}`
+					}, file.attachment.id, stored.retain)).result };
+				} catch (error) {
+					outcome = { error: reportTelegramError("attachment_retention_failed", error, { attachmentId: file.attachment.id }) };
+				}
+				try {
+					await lifecycle("retained", {
+						key,
+						attachment: file.attachment.id,
+						...outcome
+					});
+				} catch (error) {
+					reportTelegramError("attachment_receipt_recording_failed", error, { attachmentId: file.attachment.id });
+					await lifecycle("retained", {
+						key,
+						attachment: file.attachment.id,
+						...outcome
+					});
+				}
+			}
+		}
+		let current = await lifecycle("ready", { key });
+		const collectionTimeoutAt = Date.now() + 12e4;
+		while (current.readyAt !== void 0 && current.readyAt > Date.now()) {
+			if (Date.now() >= collectionTimeoutAt) throw new Error("The attachment collection exceeded its processing budget.");
+			await new Promise((resolve) => setTimeout(resolve, Math.min(2e4, current.readyAt - Date.now(), collectionTimeoutAt - Date.now())));
+			current = await lifecycle("ready", { key });
+		}
+		input.request.lifecycleContext = current.context;
+		input.request.replyTo = current.replyTo ?? input.request.replyTo;
+	}
 	if (routingFile !== void 0 && processedMedia !== void 0) {
 		const stored = files.get(routingFile.fileId);
 		if (stored?.status === "stored" && stored.imageInput === "text") files = new Map(files).set(routingFile.fileId, {
@@ -599,6 +723,8 @@ 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.replyTo = pending.replyToMessageId ?? input.request.replyTo;
+		input.request.lifecycleKey = pending.taskId ?? input.request.lifecycleKey;
 		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>`);
@@ -667,10 +793,26 @@ async function handleInboundMessage(input) {
 			...principal,
 			attributes: {
 				...principal.attributes,
+				replyToMessageId: input.request?.replyTo ?? sent.messageId,
+				...input.request?.lifecycleKey === void 0 ? {} : {
+					taskId: input.request.lifecycleKey,
+					triggeringMessageId: sent.messageId
+				},
 				pendingQuestionId: pending.id
 			}
-		} : principal,
+		} : {
+			...principal,
+			attributes: {
+				...principal.attributes,
+				replyToMessageId: input.request?.replyTo ?? sent.messageId,
+				...input.request?.lifecycleKey === void 0 ? {} : {
+					taskId: input.request.lifecycleKey,
+					triggeringMessageId: sent.messageId
+				}
+			}
+		},
 		context: [
+			...input.request?.lifecycleContext === void 0 ? [] : [input.request.lifecycleContext],
 			...observedContext(dependencies.observed.take(chat), sharedContext),
 			...group ? chatContext(dependencies.chats.chat(sent.chat.id)) : [],
 			speakerBlock({

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

@@ -0,0 +1,46 @@
+import type { SessionAuthContext } from "eve/context";
+import type { TelegramContext } from "eve/channels/telegram";
+import type { Session } from "eve/channels";
+import type { Environment } from "../environment.js";
+import type { RuntimeToken } from "../runtime-token.js";
+export interface AttachmentLifecycle {
+    readonly entity: string;
+    readonly action: string;
+}
+export interface LifecycleResult {
+    readonly key?: string;
+    readonly replyTo?: string;
+    readonly acknowledgement?: string;
+    readonly readyAt?: number;
+    readonly context?: string;
+    readonly complete?: boolean;
+    readonly message?: string;
+    readonly retain?: {
+        readonly entity: string;
+        readonly action: string;
+        readonly input: Record<string, unknown>;
+    };
+}
+/** Opt-in workspace action; the workspace owns grouping, copy, retention and completion decisions. */
+export declare function attachmentLifecycle(options: {
+    readonly configuration: AttachmentLifecycle;
+    readonly principal: SessionAuthContext;
+    readonly memberId: string;
+    readonly message: {
+        readonly chat: {
+            readonly id: string;
+        };
+        readonly messageId: string;
+        readonly messageThreadId?: number;
+        readonly from?: {
+            readonly id: string;
+        };
+    };
+    readonly environment?: Environment;
+    readonly token?: RuntimeToken;
+    readonly fetch?: typeof fetch;
+}): (phase: "admitted" | "stored" | "retained" | "ready" | "completed", data?: Record<string, unknown>) => Promise<LifecycleResult>;
+/** Kept inside the webhook's waitUntil lifetime; terminal durable stream events close the reader. */
+export declare function typingUntilComplete(session: Session, marker: string, telegram: TelegramContext["telegram"], signal: AbortSignal, metadata?: Readonly<Record<string, string | undefined>>): Promise<void>;
+/** No global timer survives a request or terminal event; failures retain safe method/status telemetry. */
+export declare function startTypingHeartbeat(telegram: TelegramContext["telegram"]): () => void;

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

@@ -0,0 +1,163 @@
+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 { t as agentBuild } from "../../../_chunks/build-metadata-BLyaHLJW.mjs";
+import { object } from "../confirmation-description.mjs";
+import { n as currentInboundRequest, p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
+import { needsConfirmation } from "../confirmations.mjs";
+import { actionToolName, ontologyTools } from "../ontology-tools.mjs";
+function attachmentLifecycle(options) {
+	const tools = ontologyTools(options);
+	const action = actionToolName(options.configuration.entity, options.configuration.action);
+	return async (phase, data = {}) => {
+		console.info("[segmentstream] telegram.phase", {
+			phase,
+			traceId: currentInboundRequest()?.traceId,
+			at: new Date().toISOString(),
+			chatId: options.message.chat.id,
+			messageId: options.message.messageId,
+			memberId: options.memberId,
+			intakeId: data.key,
+			runtime: agentBuild(options.environment)
+		});
+		const input = {
+			phase,
+			source: {
+				chat: options.message.chat.id,
+				topic: String(options.message.messageThreadId ?? ""),
+				message: options.message.messageId,
+				sender: options.message.from.id,
+				locale: String(options.principal.attributes.conversationLanguage ?? options.principal.attributes.locale ?? "en")
+			},
+			data
+		};
+		if (needsConfirmation(await tools.labels(options.memberId, action, input))) throw new Error("An attachment lifecycle hook must be a permitted routine action.");
+		const raw = await tools.rpc(options.memberId, "tools/call", {
+			name: action,
+			arguments: input
+		});
+		const envelope = object(raw.structuredContent);
+		if (object(envelope.validation).ok === false) throw new Error("The attachment lifecycle action rejected its event.");
+		const result = object(envelope.result ?? envelope);
+		const retention = object(result.retain);
+		if (typeof retention.entity === "string" && typeof retention.action === "string" && needsConfirmation(await tools.labels(options.memberId, actionToolName(retention.entity, retention.action), object(retention.input)))) throw new Error("Automatic retention requires a permitted routine storage action.");
+		return {
+			...typeof result.key === "string" ? { key: result.key } : {},
+			...typeof result.reply_to === "string" && /^[1-9]\d*$/.test(result.reply_to) ? { replyTo: result.reply_to } : {},
+			...typeof result.acknowledgement === "string" ? { acknowledgement: result.acknowledgement } : {},
+			...typeof result.ready_at === "number" && Number.isSafeInteger(result.ready_at) ? { readyAt: result.ready_at } : {},
+			...typeof result.context === "string" ? { context: result.context } : {},
+			...typeof result.complete === "boolean" ? { complete: result.complete } : {},
+			...typeof result.message === "string" ? { message: result.message } : {},
+			...typeof object(result.retain).entity === "string" && typeof object(result.retain).action === "string" ? { retain: {
+				entity: String(object(result.retain).entity),
+				action: String(object(result.retain).action),
+				input: object(object(result.retain).input)
+			} } : {}
+		};
+	};
+}
+async function typingUntilComplete(session, marker, telegram, signal, metadata = {}) {
+	const reader = (await session.getEventStream({ follow: true })).getReader();
+	let turn;
+	let firstResponse = false;
+	const abort = () => {
+		reader.cancel().catch(() => void 0);
+	};
+	signal.addEventListener("abort", abort, { once: true });
+	const stop = startTypingHeartbeat(telegram);
+	try {
+		while (!signal.aborted) {
+			const item = await reader.read();
+			if (item.done) break;
+			const event = item.value;
+			if (event.type === "message.received" && event.data.message.includes(marker)) {
+				turn = event.data.turnId;
+				console.info("[segmentstream] telegram.phase", {
+					...metadata,
+					phase: "turn_received",
+					at: new Date().toISOString(),
+					sessionId: session.id,
+					turnId: turn
+				});
+			}
+			if (turn && event.data !== void 0 && "turnId" in event.data && event.data.turnId === turn && [
+				"step.started",
+				"actions.requested",
+				"action.result",
+				"turn.completed",
+				"turn.failed",
+				"turn.cancelled"
+			].includes(event.type)) console.info("[segmentstream] telegram.phase", {
+				...metadata,
+				phase: event.type,
+				at: new Date().toISOString(),
+				sessionId: session.id,
+				turnId: turn
+			});
+			if (turn && !firstResponse && (event.type === "message.appended" || event.type === "reasoning.appended") && "turnId" in event.data && event.data.turnId === turn) {
+				firstResponse = true;
+				console.info("[segmentstream] telegram.phase", {
+					...metadata,
+					phase: "model_first_response",
+					at: new Date().toISOString(),
+					sessionId: session.id,
+					turnId: turn
+				});
+			}
+			if (event.type === "session.failed" || event.type === "session.completed") break;
+			if (turn && "turnId" in event.data && event.data.turnId === turn && ([
+				"turn.completed",
+				"turn.failed",
+				"turn.cancelled",
+				"input.requested"
+			].includes(event.type) || event.type === "turn.waiting" && event.data.on === "input")) break;
+		}
+	} finally {
+		stop();
+		signal.removeEventListener("abort", abort);
+		await reader.cancel().catch(() => void 0);
+		reader.releaseLock();
+	}
+}
+function startTypingHeartbeat(telegram) {
+	let stopped = false;
+	let timer;
+	const tick = async () => {
+		try {
+			const response = await telegram.request("sendChatAction", {
+				chat_id: telegram.chatId,
+				action: "typing",
+				...telegram.messageThreadId === void 0 ? {} : { message_thread_id: telegram.messageThreadId }
+			});
+			console.info("[segmentstream] telegram.method", {
+				method: "sendChatAction",
+				at: new Date().toISOString(),
+				chatId: telegram.chatId,
+				status: response.status,
+				accepted: response.ok && object(response.body).ok === true
+			});
+			if (!response.ok || object(response.body).ok !== true) throw new Error("Telegram rejected sendChatAction.", { cause: {
+				status: response.status,
+				body: response.body
+			} });
+		} catch (error) {
+			reportTelegramError("typing_failed", error, {
+				method: "sendChatAction",
+				chatId: telegram.chatId
+			});
+		}
+		if (!stopped) timer = setTimeout(() => {
+			tick();
+		}, 4e3);
+	};
+	tick();
+	return () => {
+		stopped = true;
+		if (timer !== void 0) clearTimeout(timer);
+	};
+}
+export { attachmentLifecycle, startTypingHeartbeat, typingUntilComplete };

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-BwBvXk0A.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 function planMedia(capabilities, descriptionModel = null) {
 	if (typeof descriptionModel === "string") return {
 		images: "describe",