@segmentstream/agent 0.8.0 → 0.8.2

package/README.md

@@ -540,3 +540,55 @@ Rollback
 disables posting while preserving archive claims and deduplication tombstones;
 it never restores relay or retries uncertain deliveries.
 See [migration and verification](../../docs/agent-chat-delivery-migration.md).
+
+### Opt-in attachment lifecycle
+
+`channels.telegram.attachmentLifecycle: { entity, action }` selects a permitted,
+routine ontology action. There is no hook or collection delay by default. The
+workspace action owns grouping, collection deadlines, language, retention and
+completion; the SDK supplies no business policy or acknowledgement copy.
+
+The action receives `phase` (`admitted`, `stored`, `retained`, `ready`, `completed`), a `source`
+object (`chat`, `topic`, `message`, `sender`, `locale`) from the authenticated
+Telegram request, and JSON `data`. Admission precedes downloads and history.
+`data.attachments` records every expected Telegram file ID and filename; stored
+and retained events record every permanent result or actionable error separately.
+Writes execute as the current member; original source provenance grants no access.
+
+Return JSON `{key, reply_to, acknowledgement, ready_at, retain, context}` as
+needed: key identifies durable workspace state, reply_to fixes its source anchor,
+ready_at is an epoch-millisecond collection deadline, and context is the current
+durable inventory for the turn. Acknowledgement copy is workspace supplied;
+claim it durably before returning it so webhook retries do not repeat it.
+`retain: {entity, action, input}` requests immediate permanent storage of the
+current file. Both the hook and retention target must resolve to permitted routine
+actions. Record incomplete sources at admission and require all expected files
+before business completion. Persist bill/result receipts and resume by business
+identity after later uploads; a collection timer alone is insufficient.
+
+The adapter retains the queued-turn policy, checks durable inbox acknowledgement,
+and anchors delivery to the immutable source message/topic. An intake webhook
+uses its host `waitUntil` lifetime to follow the durable session stream and refresh
+Telegram typing every four seconds; completion, human input, cancellation,
+failure, abort and the ten-minute observation bound close the reader and timer.
+Safe phase telemetry distinguishes admission, storage, queue acceptance and the
+owning turn without recording file contents or grants.
+
+Before a final reply, an active lifecycle receives `completed`. Return
+`{complete, message}` after checking durable results. The adapter uses this
+workspace-owned message for both complete and incomplete outcomes; a failed
+completion check cannot send an unchecked model success claim. Questions retain
+the owning task and reply anchor across continuation turns.
+
+Use `attachments_read` with `entity`, record `id`, and optional blob `property`
+to resume from a permanent file after temporary attachment expiry. The SDK
+obtains a fresh current-member `files_download` grant, streams only that grant's
+headers, bounds the transfer and verifies immutable size/SHA before parsing.
+The app bearer token and download grant never reach model output or diagnostics.
+
+Returning a lifecycle key explicitly admits that source as a task, bypassing the
+ordinary routing classifier. Omit the key to retain ordinary routing. Collection
+honours the returned deadline within a 120-second processing budget; expiry fails
+closed without queueing an incomplete turn. Authenticated runtime health includes
+the built SDK version and deployment identity. Phase telemetry records webhook
+receipt, lifecycle/queue admission, model/tool events and typing API acceptance.

package/dist/_chunks/build-metadata-DMTUHsRx.mjs

@@ -0,0 +1,16 @@
+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);
+var version = "0.8.2";
+function agentBuild(environment = process.env) {
+	return {
+		agent: version,
+		deploymentId: environment.VERCEL_DEPLOYMENT_ID ?? null,
+		sourceRevision: environment.VERCEL_GIT_COMMIT_SHA ?? null,
+		workspaceId: environment.SEGMENTSTREAM_WORKSPACE_ID ?? null
+	};
+}
+export { agentBuild as t };

package/dist/_chunks/{inbound-request-BwBvXk0A.mjs → inbound-request-CYSoY6pu.mjs}

@@ -5,19 +5,21 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { isTechnicalText } from "../extension/lib/customer-text-safety.mjs";
+import { redactDiagnostic } from "../extension/lib/diagnostics.mjs";
 import { isConfirmationText } from "../extension/lib/telegram/confirmation-text.mjs";
 import { chatPostCardLinks, isExactChatPostCard } from "../extension/lib/telegram/chat-post-card.mjs";
-import { redactDiagnostic } from "../extension/lib/diagnostics.mjs";
 import { plainTelegramText, splitTelegramText, telegramMarkdown } from "../extension/lib/telegram/format.mjs";
 import { inTelegramSendQueue } from "../extension/lib/telegram/send-queue.mjs";
 import { telegramPreviewOptions, telegramTextLinks } from "@segmentstream-cloud/ontology/telegram";
+import { randomBytes, randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { randomBytes } from "node:crypto";
 const deliveryLocale = new AsyncLocalStorage();
-function withDeliveryLocale(locale, run, threadId) {
+function withDeliveryLocale(locale, run, threadId, replyTo, chatId) {
 	return deliveryLocale.run({
 		locale,
-		threadId
+		threadId,
+		replyTo,
+		chatId
 	}, run);
 }
 function currentLocale() {
@@ -149,6 +151,12 @@ function safeTelegramFetch(fetchImpl, scope = "telegram", previews = {}) {
 			...item,
 			...typeof item.caption === "string" ? { caption: customerText(item.caption) } : {}
 		}));
+		const replyTo = deliveryLocale.getStore()?.replyTo ?? currentInboundRequest()?.replyTo;
+		const replyChat = deliveryLocale.getStore()?.chatId ?? currentInboundRequest()?.chatId;
+		if (replyTo !== void 0 && replyChat === String(body.chat_id) && /\/send(?:Message|Photo|Document|Video|Audio|Voice|MediaGroup)$/.test(url) && body.reply_parameters === void 0 && body.reply_to_message_id === void 0) body.reply_parameters = {
+			message_id: Number(replyTo),
+			allow_sending_without_reply: true
+		};
 		const markup = body.reply_markup;
 		if (Array.isArray(markup?.inline_keyboard)) {
 			if ((textBlocked || typeof body.text === "string" && body.text.length > 4096) && markup.inline_keyboard.some((row) => row.some((button) => typeof button.callback_data === "string" && button.callback_data.startsWith("ss-confirm:")))) throw new Error("Approval buttons require the complete, safe confirmation text.");
@@ -224,7 +232,16 @@ function safeTelegramFetch(fetchImpl, scope = "telegram", previews = {}) {
 var InboundRequest = class {
 	agentDescription;
 	agentName;
+	traceId = randomUUID();
 	edited = false;
+	triggeringMessageId;
+	chatId;
+	replyTo;
+	stopTyping;
+	lifecycle;
+	lifecycleKey;
+	lifecycleContext;
+	monitor;
 	previousText;
 	attachmentsChanged = false;
 	previousContent;
@@ -239,6 +256,7 @@ var InboundRequest = class {
 	files;
 	extraFiles;
 	sessions;
+	backgroundUntil;
 	waitUntil;
 	address;
 	confirmationEvent;
@@ -296,7 +314,9 @@ function withReplacedText(source, request) {
 	return {
 		...source,
 		async send(message, options) {
-			const text = request.text === void 0 ? message : replaceText(message, request.text);
+			const marker = request.lifecycleKey === void 0 || request.replyTo === void 0 ? void 0 : `[source-message:${request.replyTo};trigger:${request.triggeringMessageId ?? request.replyTo}]`;
+			const replacement = marker === void 0 ? request.text : `${marker}\n${request.text ?? (typeof message === "string" ? message : "")}`;
+			const text = replacement === void 0 ? message : replaceText(message, replacement);
 			const files = request.files === void 0 ? text : replaceFiles(text, request.files);
 			const content = request.extraFiles === void 0 || request.extraFiles.length === 0 ? files : [...typeof files === "string" ? [{
 				type: "text",
@@ -325,6 +345,16 @@ function withReplacedText(source, request) {
 			} catch (error) {
 				reportTelegramError("turn_admission_recording_failed", error);
 			}
+			if (request.lifecycleKey !== void 0) console.info("[segmentstream] telegram.phase", {
+				phase: "queue_accepted",
+				traceId: request.traceId,
+				at: new Date().toISOString(),
+				chatId: request.chatId,
+				messageId: request.replyTo,
+				intakeId: request.lifecycleKey,
+				sessionId: result.id
+			});
+			if (marker !== void 0) request.monitor?.(result, marker);
 			return result;
 		}
 	};

package/dist/extension/config.d.ts

@@ -1,3 +1,4 @@
+import type { AttachmentLifecycle } from "./lib/telegram/lifecycle.js";
 import { type TelegramLinkPreviews } from "@segmentstream-cloud/ontology/telegram";
 export declare const TELEGRAM_POLICIES: readonly ["mention", "smart"];
 /**
@@ -62,6 +63,7 @@ export interface SegmentStreamAgentConfigInput {
             readonly linkPreviews?: string;
             /** Additional exact HTTP(S) origins belonging to this workspace. */
             readonly additionalOwnOrigins?: readonly string[];
+            readonly attachmentLifecycle?: AttachmentLifecycle;
         };
     };
     readonly models?: {
@@ -114,6 +116,7 @@ export interface TelegramSettings {
     readonly policy: TelegramPolicy;
     readonly linkPreviews?: TelegramLinkPreviews;
     readonly additionalOwnOrigins?: readonly string[];
+    readonly attachmentLifecycle?: AttachmentLifecycle;
 }
 /** The chat models `segmentstream.model()` chooses between, as AI Gateway model ids. */
 export interface ChatModelChoice {

package/dist/extension/config.mjs

@@ -66,7 +66,8 @@ function telegramSettings(value, issues) {
 			"connection",
 			"policy",
 			"linkPreviews",
-			"additionalOwnOrigins"
+			"additionalOwnOrigins",
+			"attachmentLifecycle"
 		],
 		issues
 	});
@@ -91,11 +92,25 @@ function telegramSettings(value, issues) {
 		message: "must be an array of HTTP(S) origins without paths, credentials, queries or fragments",
 		path: [...path, "additionalOwnOrigins"]
 	});
+	const lifecycle = section({
+		value: telegram.attachmentLifecycle,
+		path: [...path, "attachmentLifecycle"],
+		allowed: ["entity", "action"],
+		issues
+	});
+	if (lifecycle !== void 0 && ["entity", "action"].some((key) => typeof lifecycle[key] !== "string" || !/^(?:[a-z][a-zA-Z0-9]*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/.test(String(lifecycle[key])))) issues.push({
+		message: "must name a valid ontology entity and action",
+		path: [...path, "attachmentLifecycle"]
+	});
 	return typeof connection === "string" && isTelegramPolicy(policy) ? {
 		connection,
 		policy,
 		linkPreviews,
-		additionalOwnOrigins
+		additionalOwnOrigins,
+		...lifecycle === void 0 ? {} : { attachmentLifecycle: {
+			entity: String(lifecycle.entity),
+			action: String(lifecycle.action)
+		} }
 	} : null;
 }
 function modelId(input) {

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

@@ -25,15 +25,16 @@ export declare function attachmentOwner(input: {
 /** The process's attachment client, on the deployment's own origin and OIDC token. */
 export declare function toolAttachments(environment?: Environment, token?: RuntimeToken): AgentAttachments;
 /** An attachment as the tools answer it. */
-export declare function attachmentForModel(attachment: Attachment): {
+export type ReadableFile = Pick<Attachment, "id" | "filename" | "contentType" | "size" | "sha256"> & Partial<Pick<Attachment, "state" | "expiresAt" | "promotion">>;
+export declare function attachmentForModel(attachment: ReadableFile): {
     promotion?: {} | undefined;
+    expires_at?: string | undefined;
+    state?: string | undefined;
     id: string;
     filename: string;
     content_type: string;
     size: number;
     sha256: string;
-    state: string;
-    expires_at: string;
 };
 export interface ReadOptions {
     readonly sheet?: string;
@@ -80,7 +81,7 @@ export declare function headerArgument(value: unknown): number | undefined;
 /** Keep envelopes and structured query results inside the same response budget as file text. */
 export declare function boundedResultPage<T>(items: readonly T[], offset: number, limit: number, envelope: unknown): T[];
 /** Reads never discard the remainder. Parsers process the entire file before selecting a page. */
-export declare function readOutput(attachment: Attachment, bytes: Uint8Array, options?: ReadOptions): Promise<ReadOutput>;
+export declare function readOutput(attachment: ReadableFile, bytes: Uint8Array, options?: ReadOptions): Promise<ReadOutput>;
 /** A required string argument. */
 export declare function stringArgument(input: Readonly<Record<string, unknown>>, name: string): string;
 /** An optional string argument. */

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

@@ -41,9 +41,9 @@ function attachmentForModel(attachment) {
 		content_type: attachment.contentType,
 		size: attachment.size,
 		sha256: attachment.sha256,
-		state: attachment.state,
-		expires_at: attachment.expiresAt,
-		...attachment.promotion === null ? {} : { promotion: attachment.promotion }
+		...attachment.state === void 0 ? {} : { state: attachment.state },
+		...attachment.expiresAt === void 0 ? {} : { expires_at: attachment.expiresAt },
+		...attachment.promotion == null ? {} : { promotion: attachment.promotion }
 	};
 }
 function pageInteger(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {

package/dist/extension/lib/build-metadata.d.ts

@@ -0,0 +1,8 @@
+import type { Environment } from "./environment.js";
+/** Build identity only; credentials and provider payloads never enter runtime provenance. */
+export declare function agentBuild(environment?: Environment): {
+    agent: string;
+    deploymentId: string | null;
+    sourceRevision: string | null;
+    workspaceId: string | null;
+};

package/dist/extension/lib/build-metadata.mjs

@@ -0,0 +1,8 @@
+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-DMTUHsRx.mjs";
+export { agentBuild };

package/dist/extension/lib/confirmations.mjs

@@ -6,8 +6,8 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { memberIdOf } from "./telegram/principal.mjs";
 import { confirmationCopy, renderConfirmation } from "./telegram/confirmation-text.mjs";
-import { chatPostDigest, isChatPost } from "./chat-post-confirmation.mjs";
 import { chatPostCard } from "./telegram/chat-post-card.mjs";
+import { chatPostDigest, isChatPost } from "./chat-post-confirmation.mjs";
 import { createHash } from "node:crypto";
 import { defineState } from "eve/context";
 const CONFIRMATION_TTL_MS = 6e5;

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

@@ -6,10 +6,10 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
 import { memberIdOf } from "./telegram/principal.mjs";
+import { redactDiagnostic } from "./diagnostics.mjs";
 import { humanText, object } from "./confirmation-description.mjs";
 import { chatPostDigest, chatPostOperationId, isChatPost } from "./chat-post-confirmation.mjs";
 import { actionApproval, inputHash } from "./confirmations.mjs";
-import { redactDiagnostic } from "./diagnostics.mjs";
 import { runtimeToken } from "./runtime-token.mjs";
 import { ontologyTools } from "./ontology-tools.mjs";
 import { createHash } from "node:crypto";
@@ -111,7 +111,7 @@ async function executeDeferredTool(memberId, action, input, ctx, options = {}) {
 async function runDeferredAction(record, options) {
 	if (record.inputHash !== inputHash(record.data.input)) throw new Error("The confirmed input changed.");
 	const tools = ontologyTools(options);
-	await tools.labels(record.memberId, record.data.action);
+	await tools.labels(record.memberId, record.data.action, record.data.input);
 	const preview = record.data.confirmation.description?.chatPost;
 	if (isChatPost(record.data.action)) {
 		const input = Object.fromEntries(Object.entries(record.data.input).filter(([key]) => key !== "_confirmation"));

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

@@ -12,9 +12,16 @@ export declare function ontologyTools(options?: {
     rpc: (memberId: string, method: string, params: Record<string, unknown>, signal?: AbortSignal) => Promise<Record<string, unknown>>;
     list(memberId: string): Promise<Record<string, unknown>[]>;
     supportsChatPosting(memberId: string): Promise<boolean>;
-    labels(memberId: string, action: string): Promise<ActionAnnotations>;
+    labels(memberId: string, action: string, input?: Readonly<Record<string, unknown>>): 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>;
+export declare function ontologyToolLabels(options?: Parameters<typeof ontologyTools>[0]): (memberId: string, action: string, input?: Readonly<Record<string, unknown>>) => Promise<ActionAnnotations>;
 /** MCP normalizes an authored camelCase action to snake_case. */
 export declare function actionToolName(entity: string, action: string): string;
+/** One target contract for native and MCP attachment promotion; never trust supplied safety hints. */
+export declare function promotionTarget(input: Readonly<Record<string, unknown>>): {
+    action: string;
+    input: {
+        id?: string | undefined;
+    };
+};

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

@@ -6,9 +6,9 @@ __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin } from "./environment.mjs";
 import { identityProviderOf, memberIdOf } from "./telegram/principal.mjs";
+import { redactDiagnostic } from "./diagnostics.mjs";
 import { describeConfirmation, object } from "./confirmation-description.mjs";
 import { describeChatPost, isChatPost, supportsChatPost } from "./chat-post-confirmation.mjs";
-import { redactDiagnostic } from "./diagnostics.mjs";
 import { runtimeToken } from "./runtime-token.mjs";
 function ontologyTools(options = {}) {
 	async function rpc(memberId, method, params, signal) {
@@ -49,13 +49,38 @@ function ontologyTools(options = {}) {
 		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 = tools.find((candidate) => candidate.name === bareName);
+		let tool = tools.find((candidate) => candidate.name === bareName);
+		if (tool === void 0 && tools.some((item) => item.name === "ontology_describe_tool")) {
+			const inspected = await rpc(memberId, "tools/call", {
+				name: "ontology_describe_tool",
+				arguments: { name: bareName }
+			}, signal);
+			const candidate = object(object(inspected.structuredContent).tool);
+			if (candidate.name === bareName) tool = candidate;
+		}
 		if (tool === void 0) throw new Error("Action not permitted.");
 		return {
 			tool,
 			tools
 		};
 	}
+	async function resolve(memberId, action, input, signal, depth = 0) {
+		if (depth > 3) throw new Error("Too many nested ontology tools.");
+		const found = await toolFor(memberId, action, signal);
+		if (depth > 0 && isChatPost(String(found.tool.name))) throw new Error("Exact chat posting must use the direct chat_post_message tool.");
+		if (found.tool.name === "ontology_call_tool") {
+			if (typeof input.name !== "string") throw new Error("A target tool is required.");
+			return resolve(memberId, input.name, object(input.arguments), signal, depth + 1);
+		}
+		if (found.tool.name === "attachments_promote") {
+			const target = promotionTarget(input);
+			return resolve(memberId, target.action, target.input, signal, depth + 1);
+		}
+		return {
+			...found,
+			input
+		};
+	}
 	return {
 		rpc,
 		async list(memberId) {
@@ -66,8 +91,8 @@ function ontologyTools(options = {}) {
 			const result = await rpc(memberId, "tools/list", {});
 			return Array.isArray(result.tools) && result.tools.map(object).some(supportsChatPost);
 		},
-		async labels(memberId, action) {
-			const { tool } = await toolFor(memberId, action);
+		async labels(memberId, action, input = {}) {
+			const { tool } = await resolve(memberId, action, input);
 			return {
 				...object(tool.annotations),
 				confirmation: object(object(tool.inputSchema).properties)._confirmation !== void 0
@@ -75,7 +100,10 @@ function ontologyTools(options = {}) {
 		},
 		async describe(memberId, action, input) {
 			const signal = AbortSignal.timeout(15e3);
-			const { tool, tools } = await toolFor(memberId, action, signal);
+			const resolved = await resolve(memberId, action, input, signal);
+			const { tool, tools } = resolved;
+			input = resolved.input;
+			action = String(tool.name);
 			if (isChatPost(action)) {
 				if (!supportsChatPost(tool)) throw new Error("The ontology does not support exact chat confirmations.");
 				const read = async (name, args) => {
@@ -125,8 +153,9 @@ function ontologyTools(options = {}) {
 				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 permitted = (await toolFor(memberId, name, signal)).tool;
+						if (object(permitted.annotations).readOnlyHint !== true) return;
 						const result = await rpc(memberId, "tools/call", {
 							name,
 							arguments: { id }
@@ -148,4 +177,16 @@ 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, ontologyTools };
+function promotionTarget(input) {
+	const entity = input.entity;
+	const action = input.action;
+	if (typeof entity !== "string" || typeof action !== "string" || !/^[a-z][a-zA-Z0-9_]*$/.test(entity) || !/^[a-z][a-zA-Z0-9_]*$/.test(action)) throw new Error("A valid attachment target entity and action are required.");
+	return {
+		action: actionToolName(entity, action),
+		input: {
+			...object(input.input),
+			...typeof input.record_id === "string" ? { id: input.record_id } : {}
+		}
+	};
+}
+export { actionToolName, ontologyToolLabels, ontologyTools, promotionTarget };

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

@@ -6,6 +6,8 @@ export interface PendingQuestion {
     readonly chatId: string;
     readonly messageThreadId: string;
     readonly address: string;
+    readonly replyToMessageId?: string;
+    readonly taskId?: string;
 }
 /** Intent survives turns and compaction in the session, independently of model history. */
 export declare const pendingQuestions: import("eve/context").StateHandle<Record<string, PendingQuestion>>;

package/dist/extension/lib/stored-files.d.ts

@@ -0,0 +1,17 @@
+import type { SessionAuthContext } from "eve/context";
+import { ontologyTools } from "./ontology-tools.js";
+/** A permanent blob is read through the same current-member grant used by the ontology UI. */
+export declare function readStoredFile(input: {
+    readonly entity: string;
+    readonly id: string;
+    readonly property?: string;
+}, principal: SessionAuthContext | null, options?: Parameters<typeof ontologyTools>[0]): Promise<{
+    attachment: {
+        id: string;
+        filename: string;
+        contentType: string;
+        size: number;
+        sha256: string;
+    };
+    bytes: Buffer<ArrayBuffer>;
+}>;

package/dist/extension/lib/stored-files.mjs

@@ -0,0 +1,70 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { memberIdOf } from "./telegram/principal.mjs";
+import { redactDiagnostic } from "./diagnostics.mjs";
+import { object } from "./confirmation-description.mjs";
+import { ontologyTools } from "./ontology-tools.mjs";
+import { createHash } from "node:crypto";
+async function readStoredFile(input, principal, options = {}) {
+	const memberId = memberIdOf(principal);
+	if (memberId === void 0) throw new Error("A current member is required to read a stored file.");
+	const raw = await ontologyTools({
+		...options,
+		principal
+	}).rpc(memberId, "tools/call", {
+		name: "files_download",
+		arguments: input
+	});
+	const result = object(raw.structuredContent), file = object(result.file), grant = object(result.download);
+	const headers = object(grant.headers);
+	const size = file.size;
+	const secrets = new Set([...typeof grant.url === "string" ? [grant.url] : [], ...Object.values(headers).filter((value) => typeof value === "string")]);
+	try {
+		if (file.id !== input.id || file.entity !== input.entity || file.property !== (input.property ?? "content") || grant.method !== "GET" || typeof file.filename !== "string" || typeof file.content_type !== "string" || typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(file.sha256) || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || size > 26214400 || typeof grant.url !== "string" || new URL(grant.url).protocol !== "https:" || Object.values(headers).some((value) => typeof value !== "string")) throw new Error("The stored file grant or bounded metadata is invalid.", { cause: {
+			file,
+			download: grant
+		} });
+		const response = await (options.fetch ?? fetch)(grant.url, {
+			method: "GET",
+			headers: Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, String(value)])),
+			redirect: "error",
+			signal: AbortSignal.timeout(12e4)
+		});
+		if (!response.ok || response.body === null) throw new Error(`Stored file transfer refused (HTTP ${response.status}).`);
+		const reader = response.body.getReader(), chunks = [];
+		let received = 0;
+		try {
+			for (;;) {
+				const chunk = await reader.read();
+				if (chunk.done) break;
+				received += chunk.value.byteLength;
+				if (received > size) throw new Error("Stored file transfer exceeded its declared size.");
+				chunks.push(chunk.value);
+			}
+		} finally {
+			await reader.cancel().catch((error) => {
+				console.warn("Stored file reader cleanup failed.", redactDiagnostic(error, secrets));
+			});
+			reader.releaseLock();
+		}
+		const bytes = Buffer.concat(chunks);
+		if (bytes.byteLength !== size || createHash("sha256").update(bytes).digest("hex") !== file.sha256) throw new Error("Stored file bytes differ from their immutable revision metadata.");
+		return {
+			attachment: {
+				id: input.id,
+				filename: file.filename,
+				contentType: file.content_type,
+				size,
+				sha256: file.sha256
+			},
+			bytes
+		};
+	} catch (error) {
+		throw new Error("The permanent file could not be read.", { cause: redactDiagnostic(error, secrets) });
+	}
+}
+export { readStoredFile };

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

@@ -8,11 +8,13 @@ import { manifestOf } from "../../config.mjs";
 import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
 import { conversationLanguage, telegramPrincipal } from "./principal.mjs";
 import { chooseModel } from "../../model.mjs";
+import { t as agentBuild } from "../../../_chunks/build-metadata-DMTUHsRx.mjs";
 import { confirmationLocale } from "./confirmation-text.mjs";
+import { telegramSendScope } from "./send-queue.mjs";
+import { d as failureText, h as withDeliveryLocale, i as withReplacedText, m as safeTelegramFetch, n as currentInboundRequest, p as reportTelegramError, r as runInboundRequest, t as InboundRequest } from "../../../_chunks/inbound-request-CYSoY6pu.mjs";
 import { runtimeToken } from "../runtime-token.mjs";
+import { attachmentLifecycle } from "./lifecycle.mjs";
 import { conversations } from "../conversations.mjs";
-import { telegramSendScope } from "./send-queue.mjs";
-import { d as failureText, h as withDeliveryLocale, i as withReplacedText, m as safeTelegramFetch, n as currentInboundRequest, p as reportTelegramError, r as runInboundRequest, t as InboundRequest } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
 import { observedMessages } from "./observed.mjs";
 import { expireDeferredCards, handleDeferredCallback, isDeferredCallback } from "./deferred-confirmations.mjs";
@@ -164,6 +166,15 @@ function segmentstreamTelegram(options) {
 					request: currentInboundRequest(),
 					dependencies: {
 						policy: settings().policy,
+						...settings().attachmentLifecycle === void 0 ? {} : { lifecycle: (principal, memberId, message) => attachmentLifecycle({
+							configuration: settings().attachmentLifecycle,
+							principal,
+							memberId,
+							message,
+							environment,
+							token,
+							...options.fetch ? { fetch: options.fetch } : {}
+						}) },
 						sessions: options.sessions,
 						admission: options.admission ?? (() => manifestOf({})),
 						sessionPolicy: policy,
@@ -243,6 +254,8 @@ function segmentstreamTelegram(options) {
 				const errorId = reportTelegramError("inbound_message_failed", error, { chatId: message.chat.id });
 				await context.telegram.post(failureText(errorId));
 				return null;
+			} finally {
+				inbound?.stopTyping?.();
 			}
 		},
 		onCallbackQuery: async (context, query) => {
@@ -284,7 +297,41 @@ function segmentstreamTelegram(options) {
 				token,
 				...options.fetch ? { fetch: options.fetch } : {}
 			}),
-			"message.completed": replyDelivery(observed, () => telegramSendScope(environment, settings().connection))
+			async "message.completed"(event, channel, context) {
+				const principal = context.session.auth.current;
+				const taskId = principal?.attributes.taskId;
+				const configuration = settings().attachmentLifecycle;
+				if (event.finishReason !== "tool-calls" && event.message && configuration && principal && typeof taskId === "string") try {
+					const memberId = principal.attributes.memberId;
+					if (typeof memberId !== "string") throw new Error("A current member is required for completion.");
+					const result = await attachmentLifecycle({
+						configuration,
+						principal,
+						memberId,
+						environment,
+						token,
+						...options.fetch ? { fetch: options.fetch } : {},
+						message: {
+							chat: { id: channel.telegram.chatId },
+							messageId: String(principal.attributes.triggeringMessageId ?? principal.attributes.replyToMessageId),
+							messageThreadId: channel.telegram.messageThreadId,
+							from: { id: principal.subject ?? "" }
+						}
+					})("completed", { key: taskId });
+					if (result.message !== void 0 || result.complete === false) event = {
+						...event,
+						message: result.message ?? ""
+					};
+				} catch (error) {
+					const reference = reportTelegramError("intake_completion_failed", error, {
+						sessionId: context.session.id,
+						taskId
+					});
+					await channel.telegram.post(failureText(reference));
+					return;
+				}
+				await replyDelivery(observed, () => telegramSendScope(environment, settings().connection))(event, channel, context);
+			}
 		}
 	});
 	const adapter = channel.adapter;
@@ -334,7 +381,7 @@ function segmentstreamTelegram(options) {
 				context.state.customerLocale = locale;
 				await withDeliveryLocale(locale, async () => {
 					await handler(event, context);
-				}, context.state.messageThreadId === null ? void 0 : String(context.state.messageThreadId));
+				}, context.state.messageThreadId === null ? void 0 : String(context.state.messageThreadId), typeof principal?.attributes.replyToMessageId === "string" ? principal.attributes.replyToMessageId : void 0, typeof principal?.attributes.chatId === "string" ? principal.attributes.chatId : void 0);
 			}]))
 		} },
 		routes: [...channel.routes.map((route) => gatedRoute({
@@ -365,6 +412,12 @@ function gatedRoute(input) {
 			let description;
 			const describe = () => description ??= args.describe();
 			const inbound = new InboundRequest(async () => (await describe()).description ?? "", async () => (await describe()).name);
+			if (options.settings()?.attachmentLifecycle !== void 0 && telegramWebhookVerifier(() => webhookSecret(environment))(request)) console.info("[segmentstream] telegram.phase", {
+				phase: "webhook_received",
+				traceId: inbound.traceId,
+				at: new Date().toISOString(),
+				runtime: agentBuild(environment)
+			});
 			const scoped = (address) => scopedAddress(address, options.sessions().scope);
 			inbound.sessions = {
 				resolveSession: args.resolveSession,
@@ -399,6 +452,7 @@ function gatedRoute(input) {
 				args.waitUntil(task);
 			};
 			inbound.waitUntil = waitUntil;
+			inbound.backgroundUntil = (task) => args.waitUntil(task);
 			return runInboundRequest(inbound, () => input.capture(request, async (routedRequest = request) => {
 				const response = await route.handler(routedRequest, {
 					...args,