@segmentstream/agent 0.6.13 → 0.7.0

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

@@ -0,0 +1,282 @@
+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 { 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 { CONFIRMATION_TTL_MS, inputHash } from "../confirmations.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";
+const PREFIX = "ss-confirm:d:";
+const isDeferredCallback = (data) => data?.startsWith(PREFIX) === true;
+const deferredCallback = (record, choice) => `${PREFIX}${record.key}:${choice}`;
+const copyOf = (record) => record.data.confirmation.description?.chatPost ? chatPostCard(record.data.confirmation.description, record.data.confirmation.copy) : renderConfirmation(record.data.confirmation.description, record.data.confirmation.copy);
+function promptOf(record, state) {
+	const name = humanText(record.data.requesterName);
+	return {
+		mode: "deferred",
+		requestId: record.id,
+		sessionId: record.data.sessionId,
+		address: record.data.address,
+		action: humanText(record.data.confirmation.description?.action) ?? "❓",
+		requestedBy: name ?? null,
+		at: new Date(record.expiresAt - CONFIRMATION_TTL_MS).toISOString(),
+		state,
+		...name === void 0 ? {} : { requester: {
+			id: record.data.requester,
+			author: name
+		} }
+	};
+}
+function remember(record, text, prompt, observed) {
+	if (record.data.messageId === void 0) return;
+	observed?.remember(observedChatKey({
+		chatId: record.data.chatId,
+		...record.data.threadId ? { messageThreadId: Number(record.data.threadId) } : {}
+	}), {
+		...agentMessage({
+			text,
+			at: new Date().toISOString(),
+			messageId: record.data.messageId,
+			...prompt.requester === void 0 ? {} : { inReplyTo: prompt.requester }
+		}),
+		confirmation: prompt
+	});
+}
+async function archiveDeferred(record, phase, archive) {
+	await archive.append(conversationEvent({
+		eventId: `confirmation:${record.id}:${phase}`,
+		provider: "telegram",
+		chatId: record.data.chatId,
+		threadId: record.data.threadId || null,
+		chatType: record.data.chatId.startsWith("-") ? "group" : "private",
+		participantIds: [record.memberId],
+		kind: "tool_result",
+		sessionId: record.data.sessionId,
+		toolCallId: record.id,
+		operationId: record.id,
+		toolName: record.data.action,
+		reason: phase,
+		status: phase === "done" ? "completed" : phase === "failed" ? "failed" : phase === "cancelled" || phase === "expired" ? "cancelled" : "requested"
+	}));
+}
+async function postDeferredCard(id, channel, ctx, options, archive, observed) {
+	const store = deferredConfirmations(options);
+	const record = await store.command({
+		operation: "read",
+		key: deferredKey(id)
+	});
+	if (!record || record.data.sessionId !== ctx.session.id || record.status !== "pending" || record.data.messageId) return;
+	const copy = copyOf(record);
+	const address = channel.continuation?.token ?? formatAddress({
+		chatId: record.data.chatId,
+		messageThreadId: record.data.threadId,
+		conversationId: channel.telegram.conversationId ?? ""
+	});
+	const prompt = {
+		...promptOf(record, "pending"),
+		address
+	};
+	await archiveDeferred(record, "requested", archive);
+	const post = () => channel.telegram.post({
+		text: copy.text,
+		reply_markup: { inline_keyboard: [[
+			{
+				text: copy.confirm,
+				callback_data: deferredCallback(record, "y")
+			},
+			...record.data.confirmation.description?.chatPost ? [{
+				text: copy.edit,
+				callback_data: deferredCallback(record, "e")
+			}] : [],
+			{
+				text: copy.cancel,
+				callback_data: deferredCallback(record, "n")
+			}
+		]] }
+	});
+	const sent = await withConfirmationPrompt(prompt, () => record.data.confirmation.description?.chatPost ? withChatPostCard(copy.text, post, copy.previewLinks) : withConfirmationText(copy.text, post));
+	await store.command({
+		operation: "attach",
+		key: record.key,
+		messageId: sent.id,
+		address
+	});
+	remember({
+		...record,
+		data: {
+			...record.data,
+			messageId: sent.id,
+			address
+		}
+	}, copy.text, prompt, observed);
+}
+async function editCard(record, context, status, state, observed) {
+	if (!record.data.messageId) return;
+	const copy = copyOf(record);
+	const exact = record.data.confirmation.description?.chatPost !== void 0;
+	const text = exact ? chatPostCardStatus(copy.text, status) : `${copy.text}\n\n${status}`;
+	const edit = () => context.telegram.editMessageText({
+		messageId: record.data.messageId,
+		text,
+		replyMarkup: { inline_keyboard: [] }
+	});
+	const prompt = promptOf(record, state);
+	await withConfirmationPrompt(prompt, () => exact ? withChatPostCard(text, edit, [...copy.previewLinks ?? [], ...telegramTextLinks(status)]) : withConfirmationText(text, edit));
+	remember(record, text, prompt, observed);
+}
+async function handleDeferredCallback(input) {
+	const { query, context, options, archive } = input;
+	const notice = async (text) => {
+		try {
+			await context.telegram.answerCallbackQuery({
+				callbackQueryId: query.id,
+				text,
+				showAlert: false
+			});
+		} catch (error) {
+			reportTelegramError("deferred_acknowledgment_failed", error);
+		}
+	};
+	const parts = /^ss-confirm:d:([0-9a-f]{20}):([yne])$/.exec(query.data ?? "");
+	if (!parts || !query.message || query.from.isBot) {
+		await notice("⚠️");
+		return;
+	}
+	const store = deferredConfirmations(options);
+	const record = await store.command({
+		operation: "read",
+		key: parts[1]
+	});
+	const lookup = await input.identities.lookup({
+		provider: "telegram",
+		externalId: query.from.id
+	});
+	if (!record || lookup.status !== "paired" || lookup.member.id !== record.memberId || record.data.requester !== query.from.id || record.data.chatId !== query.message.chat.id || record.data.threadId !== String(query.message.messageThreadId ?? "") || record.data.messageId !== query.message.messageId) {
+		await notice("🔒");
+		return;
+	}
+	if (record.inputHash !== inputHash(record.data.input) || parts[2] === "e" && record.data.confirmation.description?.chatPost === void 0) {
+		await notice("⚠️");
+		return;
+	}
+	const copy = copyOf(record);
+	const decision = parts[2] === "y" ? "approve" : "cancel";
+	const claimed = await store.command({
+		operation: "decide",
+		key: record.key,
+		memberId: record.memberId,
+		inputHash: inputHash(record.data.input),
+		decision
+	});
+	if (!claimed || claimed.status === "pending") {
+		await notice("⌛");
+		return;
+	}
+	await notice(claimed.status === "expired" ? "⌛" : void 0);
+	let status = claimed.status;
+	let cardStatus = status === "expired" ? copy.expired : copy.cancelled;
+	let execution;
+	try {
+		await archiveDeferred(claimed, claimed.status, archive);
+	} catch (error) {
+		const reference = reportTelegramError("deferred_decision_archive_failed", error);
+		if (status === "approved") {
+			status = "failed";
+			execution = "not_started";
+			cardStatus = `${copy.failed} ${reference}`;
+			await store.command({
+				operation: "finish",
+				key: claimed.key,
+				status
+			});
+		}
+	}
+	if (status === "approved") {
+		try {
+			await editCard(claimed, context, copy.executing, "approved", input.observed);
+		} catch (error) {
+			reportTelegramError("deferred_card_update_failed", error);
+		}
+		try {
+			const result = await runDeferredAction(claimed, options);
+			status = "done";
+			cardStatus = claimed.data.confirmation.description?.chatPost ? chatPostReceipt(result.structuredContent, copy.completed) ?? "⚠️ ❓" : copy.completed;
+		} catch (error) {
+			status = "failed";
+			const reference = reportTelegramError("deferred_action_failed", error);
+			cardStatus = `${copy.failed} ${reference}`;
+		}
+		await store.command({
+			operation: "finish",
+			key: claimed.key,
+			status
+		});
+	}
+	if (status === "done" || status === "failed") try {
+		await archiveDeferred(claimed, status, archive);
+	} catch (error) {
+		reportTelegramError("deferred_outcome_archive_failed", error);
+	}
+	try {
+		await editCard(claimed, context, cardStatus, status === "done" ? "completed" : status, input.observed);
+	} catch (error) {
+		reportTelegramError("deferred_card_update_failed", error);
+	}
+	const principal = telegramPrincipal({
+		member: lookup.member,
+		message: {
+			...query.message,
+			from: query.from,
+			text: "",
+			caption: "",
+			raw: {},
+			attachments: []
+		}
+	});
+	await currentInboundRequest()?.confirmationEvent?.(claimed, confirmationOutcome(claimed, status, {
+		...execution === void 0 ? {} : { execution },
+		...parts[2] === "e" && status === "cancelled" ? { editRequested: true } : {}
+	}), principal);
+}
+async function expireDeferredRecord(record, context, options, archive, notify, observed) {
+	const claimed = await deferredConfirmations(options).command({
+		operation: "decide",
+		key: record.key,
+		memberId: record.memberId,
+		inputHash: record.inputHash,
+		decision: "expire"
+	});
+	if (!claimed) return;
+	try {
+		await archiveDeferred(claimed, "expired", archive);
+	} catch (error) {
+		reportTelegramError("deferred_outcome_archive_failed", error);
+	}
+	try {
+		await editCard(claimed, context, copyOf(claimed).expired, "expired", observed);
+	} catch (error) {
+		reportTelegramError("deferred_card_update_failed", error);
+	}
+	await notify(claimed, confirmationOutcome(claimed, "expired"), null);
+}
+async function expireDeferredCards(context, options, archive, observed) {
+	const records = await deferredConfirmations(options).command({
+		operation: "expired",
+		chatId: context.telegram.chatId
+	});
+	for (const record of records) {
+		if (record.data.threadId !== String(context.telegram.messageThreadId ?? "")) continue;
+		await expireDeferredRecord(record, context, options, archive, async (saved, result, auth) => currentInboundRequest()?.confirmationEvent?.(saved, result, auth), observed);
+	}
+}
+export { archiveDeferred, deferredCallback, expireDeferredCards, expireDeferredRecord, handleDeferredCallback, isDeferredCallback, postDeferredCard };

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

@@ -5,9 +5,9 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { conversationLanguage } from "./principal.mjs";
-import { MAXIMUM_ATTACHMENT_BYTES, attachmentUrl } from "../attachments.mjs";
-import { d as failureText, p as reportTelegramError } from "../../../_chunks/inbound-request-CysnjMdw.mjs";
+import { d as failureText, p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { describableImage, describeReceivedImage } from "./images.mjs";
+import { MAXIMUM_ATTACHMENT_BYTES, attachmentUrl } from "../attachments.mjs";
 function telegramConversation(chatId) {
 	return `telegram:${chatId}`;
 }
@@ -80,17 +80,33 @@ async function stageFiles(input) {
 				sourceRef: `${message.chat.id}:${message.messageId}:${index}`
 			});
 			let description;
+			let decoded;
 			let imageInput;
 			if (input.imagePlan !== void 0 && contentType.startsWith("image/")) {
 				imageInput = "text";
 				if (!describableImage(contentType)) description = "[unsupported image format; original remains stored]";
 				else if (input.imagePlan.images === "native" && bytes.byteLength <= 3145728) imageInput = "native";
 				else if (input.imagePlan.images === "describe" && input.imagePlan.descriptionModel && input.describeImage) {
+					decoded = {
+						attachment_kind: file.kind,
+						model: input.imagePlan.descriptionModel,
+						processed: false,
+						status: "not_processed"
+					};
 					description = descriptions >= 1 ? "[image description skipped: per-message limit; original remains stored]" : await describeReceivedImage({
 						bytes,
 						mediaType: contentType,
 						model: input.imagePlan.descriptionModel,
-						describe: input.describeImage
+						describe: input.describeImage,
+						retain: (content) => {
+							decoded = {
+								attachment_kind: file.kind,
+								model: input.imagePlan.descriptionModel,
+								processed: true,
+								status: "processed",
+								content
+							};
+						}
 					});
 					descriptions += 1;
 				} else description = input.imagePlan.images === "native" ? "[image exceeds the native 3 MiB context limit; original remains stored]" : "[image analysis unavailable or disabled; original remains stored]";
@@ -104,6 +120,7 @@ async function stageFiles(input) {
 					conversation
 				}),
 				...description === void 0 ? {} : { description },
+				...decoded === void 0 ? {} : { decoded },
 				...imageInput === void 0 ? {} : { imageInput }
 			});
 		} catch (error) {

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

@@ -16,4 +16,5 @@ export declare function describeReceivedImage(input: {
     readonly mediaType: string;
     readonly model: string;
     readonly describe: ImageDescriber;
+    readonly retain?: (text: string) => void;
 }): Promise<string>;

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-CysnjMdw.mjs";
+import { p as reportTelegramError } from "../../../_chunks/inbound-request-BwBvXk0A.mjs";
 import { gateway, generateText } from "ai";
 const MAXIMUM_IMAGE_DESCRIPTION_BYTES = 5242880;
 const MAXIMUM_NATIVE_IMAGE_BYTES = 3145728;
@@ -39,6 +39,7 @@ async function describeReceivedImage(input) {
 	if (input.bytes.byteLength > 5242880) return "[image description skipped: exceeds 5 MiB; original remains stored]";
 	try {
 		const text = (await input.describe(input)).trim();
+		if (text !== "") input.retain?.(text.slice(0, MAXIMUM_IMAGE_DESCRIPTION_CHARACTERS));
 		return text === "" ? "[image description unavailable: empty result; original remains stored]" : text.length > MAXIMUM_IMAGE_DESCRIPTION_CHARACTERS ? `${text.slice(0, 511)}…` : text;
 	} catch (error) {
 		return `[image description failed; original remains stored; error reference: ${reportTelegramError("image_description_failed", error)}]`;

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

@@ -1,6 +1,8 @@
+import type { DeferredConfirmation } from "../deferred-confirmations.js";
 import type { UserContent } from "ai";
 import type { ChannelSource } from "eve/channels";
 import type { SessionAuthContext } from "eve/context";
+import type { DecodedAttachment } from "./attachment-description.js";
 import type { Attachment } from "../attachments.js";
 import type { SessionOperations } from "./sessions.js";
 /** What became of one Telegram file of the message: stored as an attachment, or why not. */
@@ -9,6 +11,7 @@ export type StagedFile = {
     readonly attachment: Attachment;
     readonly url: URL;
     readonly description?: string;
+    readonly decoded?: DecodedAttachment;
     readonly imageInput?: "native" | "text";
 } | {
     readonly status: "refused";
@@ -25,7 +28,17 @@ export type StagedFile = {
 export declare class InboundRequest {
     /** The agent's description from the compiled manifest, for the routing decision. */
     readonly agentDescription: () => Promise<string>;
+    readonly agentName: () => Promise<string>;
     edited: boolean;
+    previousText: string | undefined;
+    attachmentsChanged: boolean;
+    /** Evidence may be reused only while the provider attachment identities are unchanged. */
+    previousContent: {
+        readonly media?: string;
+        readonly decoded: ReadonlyArray<DecodedAttachment>;
+    } | undefined;
+    /** Claims one edit revision before routing, including revisions the classifier observes. */
+    claimRevision: (() => Promise<boolean>) | undefined;
     deliveryFailed: ((error: unknown) => Promise<void>) | undefined;
     /** Atomic per-message admission in the platform archive, after authentication and routing. */
     claimTurn: (() => Promise<boolean>) | undefined;
@@ -49,10 +62,11 @@ export declare class InboundRequest {
     waitUntil: ((task: Promise<unknown>) => void) | undefined;
     /** Continues the exact pending question's session, including under thread scope. */
     address: string | undefined;
+    confirmationEvent: ((record: DeferredConfirmation, result: Readonly<Record<string, unknown>>, auth: SessionAuthContext | null) => Promise<unknown>) | undefined;
     respond: ((address: string, requestId: string, decision: "approve" | "cancel", principal: SessionAuthContext, text?: string) => Promise<unknown>) | undefined;
     constructor(
     /** The agent's description from the compiled manifest, for the routing decision. */
-    agentDescription: () => Promise<string>);
+    agentDescription: () => Promise<string>, agentName?: () => Promise<string>);
 }
 export declare function runInboundRequest<Result>(request: InboundRequest, run: () => Result): Result;
 /** The current webhook request, or `undefined` outside the wrapped route. */

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

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

@@ -11,6 +11,8 @@ import { type ObservedMessages } from "./observed.js";
 import { type RouteDecider } from "./router.js";
 import { type HistoryReader, type SessionPolicy } from "./sessions.js";
 import { type Transcriber } from "./voice.js";
+import { type AttachmentDescriber } from "./attachment-description.js";
+import type { PdfTextExtractor } from "./pdf-text.js";
 /**
  * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
  *
@@ -21,9 +23,9 @@ import { type Transcriber } from "./voice.js";
  *    and so is the agent's own, which unlinks every member. Neither is the notice, in the old chat
  *    or the new one, that a group became a supergroup: the migration is reported.
  * 2. Voice becomes text, so the router and the agent read what was said.
- * 3. The router answers or observes. Files always start a turn after the identity gates, even
- *    without a caption or when addressed to another person. They are stored after the registry knows the
- *    sender. Observing starts no session or typing indication;
+ * 3. The router answers or observes. Group files follow the same addressing rules as text;
+ *    captionless uploads use smart routing and recent agent requests. Files are stored after the
+ *    registry knows the sender. Observing starts no session or typing indication;
  *    the ring carries the stored files' references (or storage failures) into the next reply.
  * 4. The session policy runs on the session an answered message continues: an idle one is cleared, the
  *    first message after the day's compaction time compacts it.
@@ -39,6 +41,9 @@ export interface InboundDependencies {
     readonly sessions: () => SessionSettings;
     readonly sessionPolicy: SessionPolicy;
     readonly sttModel: string | false;
+    readonly attachmentsModel: string | false;
+    readonly describeAttachment: AttachmentDescriber;
+    readonly extractPdf?: PdfTextExtractor;
     readonly mediaPlan?: (member: PairedMember, sessionId?: string) => Promise<MediaPlan>;
     readonly describeImage?: ImageDescriber;
     readonly identities: AgentIdentities;
@@ -47,7 +52,10 @@ export interface InboundDependencies {
     /** Full session history for open questions, which can survive compaction. */
     readonly history?: HistoryReader;
     readonly transcribe: Transcriber;
-    readonly download: (fileId: string) => Promise<Uint8Array>;
+    readonly download: (fileId: string, options?: {
+        readonly abortSignal?: AbortSignal;
+        readonly maxBytes?: number;
+    }) => Promise<Uint8Array>;
     /** The attachment store; without it, files reach the turn as eve's Telegram file parts. */
     readonly attachments?: AgentAttachments;
     readonly observed: ObservedMessages;