@segmentstream/agent 0.1.5 → 0.2.1

package/dist/extension/lib/connection-proxy.mjs

@@ -5,6 +5,8 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 const MAXIMUM_PROXY_BODY_BYTES = 2097152;
+const MAXIMUM_DOWNLOAD_BYTES = 20971520;
+const PROXY_STREAM_MEDIA_TYPE = "application/vnd.segmentstream.proxy-stream.v1+ndjson";
 const CALL_TIMEOUT_MS = 4e4;
 var ConnectionProxyError = class extends Error {
 	name = "ConnectionProxyError";
@@ -55,59 +57,153 @@ function connectionProxy(input) {
 	const { environment, connection } = input;
 	const fetchImpl = input.fetch ?? fetch;
 	const url = `${`${environment.segmentstreamUrl}/api/internal/v1/workspaces/${environment.workspaceId}`}/ontology/connections/${encodeURIComponent(connection)}/request`;
+	async function send(call, accept) {
+		if (call.body.byteLength > 2097152) throw new ConnectionProxyError({
+			connection,
+			code: "invalid_request",
+			message: "The request body exceeds the proxy's 2 MiB limit."
+		});
+		const token = await input.token();
+		try {
+			return await fetchImpl(url, {
+				method: "POST",
+				headers: {
+					"x-segmentstream-runtime-identity": token,
+					"x-segmentstream-organization-id": environment.organizationId,
+					"content-type": "application/json",
+					accept
+				},
+				body: JSON.stringify({
+					...call.api === void 0 ? {} : { api: call.api },
+					method: call.method,
+					path: call.path,
+					headers: call.headers,
+					body: Buffer.from(call.body).toString("base64")
+				}),
+				redirect: "error",
+				signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
+			});
+		} catch (error) {
+			throw new ConnectionProxyError({
+				connection,
+				code: error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unavailable",
+				message: "SegmentStream's connection proxy could not be reached.",
+				cause: error
+			});
+		}
+	}
+	async function buffered(response) {
+		const text = await response.text();
+		let value;
+		try {
+			value = JSON.parse(text);
+		} catch (error) {
+			if (response.ok) throw new ConnectionProxyError({
+				connection,
+				code: "invalid_response",
+				message: "The connection proxy answered with an invalid response.",
+				cause: error
+			});
+			throw refusal(connection, response.status, void 0, error);
+		}
+		if (!response.ok) throw refusal(connection, response.status, value);
+		return decodeReply(connection, value);
+	}
 	return {
 		connection,
 		async request(call) {
-			if (call.body.byteLength > 2097152) throw new ConnectionProxyError({
-				connection,
-				code: "invalid_request",
-				message: "The request body exceeds the proxy's 2 MiB limit."
-			});
-			const token = await input.token();
-			let response;
+			return buffered(await send(call, "application/json"));
+		},
+		async download(call, maxBytes = MAXIMUM_DOWNLOAD_BYTES) {
+			const response = await send(call, PROXY_STREAM_MEDIA_TYPE);
+			const type = response.headers.get("content-type") ?? "";
+			if (!response.ok || !type.startsWith("application/vnd.segmentstream.proxy-stream.v1+ndjson") || response.body === null) return buffered(response);
 			try {
-				response = await fetchImpl(url, {
-					method: "POST",
-					headers: {
-						"x-segmentstream-runtime-identity": token,
-						"x-segmentstream-organization-id": environment.organizationId,
-						"content-type": "application/json",
-						accept: "application/json"
-					},
-					body: JSON.stringify({
-						...call.api === void 0 ? {} : { api: call.api },
-						method: call.method,
-						path: call.path,
-						headers: call.headers,
-						body: Buffer.from(call.body).toString("base64")
-					}),
-					redirect: "error",
-					signal: AbortSignal.timeout(CALL_TIMEOUT_MS)
-				});
+				return await framedReply(connection, response.body, maxBytes);
 			} catch (error) {
+				if (error instanceof ConnectionProxyError) throw error;
 				throw new ConnectionProxyError({
 					connection,
 					code: error instanceof DOMException && error.name === "TimeoutError" ? "timeout" : "unavailable",
-					message: "SegmentStream's connection proxy could not be reached.",
+					message: "SegmentStream's connection proxy stopped relaying the response.",
 					cause: error
 				});
 			}
-			const text = await response.text();
-			let value;
-			try {
-				value = JSON.parse(text);
-			} catch (error) {
-				if (response.ok) throw new ConnectionProxyError({
+		}
+	};
+}
+async function framedReply(connection, body, maxBytes) {
+	const invalid = () => new ConnectionProxyError({
+		connection,
+		code: "invalid_response",
+		message: "The connection proxy answered with an invalid stream."
+	});
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	const chunks = [];
+	let head;
+	let size = 0;
+	let pending = "";
+	let ended = false;
+	try {
+		while (!ended) {
+			const next = await reader.read();
+			if (next.done) break;
+			pending += decoder.decode(next.value, { stream: true });
+			for (let newline = pending.indexOf("\n"); newline >= 0; newline = pending.indexOf("\n")) {
+				const line = pending.slice(0, newline);
+				pending = pending.slice(newline + 1);
+				if (line.trim() === "") continue;
+				let frame;
+				try {
+					frame = JSON.parse(line);
+				} catch (error) {
+					throw new ConnectionProxyError({
+						connection,
+						code: "invalid_response",
+						message: "The connection proxy answered with an invalid stream.",
+						cause: error
+					});
+				}
+				if (!isRecord(frame)) throw invalid();
+				if (head === void 0) {
+					if (typeof frame.statusCode !== "number" || !isHeaderPairs(frame.headers)) throw invalid();
+					head = {
+						status: frame.statusCode,
+						headers: frame.headers
+					};
+				} else if (typeof frame.data === "string") {
+					const chunk = Buffer.from(frame.data, "base64");
+					size += chunk.byteLength;
+					if (size > maxBytes) throw new ConnectionProxyError({
+						connection,
+						code: "too_large",
+						message: `The response exceeds the ${Math.floor(maxBytes / 1024 / 1024)} MiB download limit.`
+					});
+					chunks.push(chunk);
+				} else if (frame.end === true) {
+					ended = true;
+					break;
+				} else if (typeof frame.error === "string") throw new ConnectionProxyError({
 					connection,
-					code: "invalid_response",
-					message: "The connection proxy answered with an invalid response.",
-					cause: error
+					code: frame.error,
+					message: "SegmentStream's connection proxy failed while relaying the response."
 				});
-				throw refusal(connection, response.status, void 0, error);
+				else throw invalid();
 			}
-			if (!response.ok) throw refusal(connection, response.status, value);
-			return decodeReply(connection, value);
 		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+	if (head === void 0 || !ended) throw new ConnectionProxyError({
+		connection,
+		code: "unavailable",
+		message: "The connection proxy's stream ended before the response did."
+	});
+	return {
+		status: head.status,
+		headers: head.headers,
+		body: new Uint8Array(Buffer.concat(chunks))
 	};
 }
-export { ConnectionProxyError, MAXIMUM_PROXY_BODY_BYTES, connectionProxy };
+export { ConnectionProxyError, MAXIMUM_DOWNLOAD_BYTES, MAXIMUM_PROXY_BODY_BYTES, PROXY_STREAM_MEDIA_TYPE, connectionProxy };

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

@@ -1,5 +1,6 @@
 import { type TelegramChannel } from "eve/channels/telegram";
 import type { SessionSettings, TelegramSettings } from "../../config.js";
+import { type AgentAttachments } from "../attachments.js";
 import { type Environment } from "../environment.js";
 import { type RuntimeTokenVerifier } from "../runtime-identity.js";
 import { type RuntimeToken } from "../runtime-token.js";
@@ -32,6 +33,8 @@ export interface TelegramAdapterOptions {
     readonly verify?: RuntimeTokenVerifier;
     /** Reads the tail of a session's durable stream; tests pass a fake. */
     readonly history?: HistoryReader;
+    /** The attachment store; tests pass a fake. */
+    readonly attachments?: AgentAttachments;
 }
 /** The Telegram channel of the extension. */
 export declare function segmentstreamTelegram(options: TelegramAdapterOptions): TelegramChannel;

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

@@ -5,21 +5,23 @@ const __filename = __eveFileURLToPath(import.meta.url);
 __eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { appOrigin, channelsEnabled, proxyEnvironment, runtimeIdentityEnvironment, webhookSecret } from "../environment.mjs";
-import { MAXIMUM_PROXY_BODY_BYTES, connectionProxy } from "../connection-proxy.mjs";
+import { MAXIMUM_DOWNLOAD_BYTES, connectionProxy } from "../connection-proxy.mjs";
+import { runtimeToken } from "../runtime-token.mjs";
+import { agentAttachments, parseAttachmentUrl } from "../attachments.mjs";
 import { agentIdentities } from "../identities.mjs";
 import { runtimeTokenVerifier } from "../runtime-identity.mjs";
-import { runtimeToken } from "../runtime-token.mjs";
 import { botIdentityCache } from "./bot.mjs";
 import { agentChats } from "./chats.mjs";
 import { observedMessages } from "./observed.mjs";
 import { decisionRouter } from "./router.mjs";
+import { replyDelivery } from "./silent.mjs";
 import { scopedAddress, sessionPolicy } from "./sessions.mjs";
 import { downloadTelegramFile, gatewayTranscriber } from "./voice.mjs";
 import { handleInboundMessage } from "./inbound.mjs";
 import { InboundRequest, currentInboundRequest, runInboundRequest, withReplacedText } from "./inbound-request.mjs";
 import { TELEGRAM_PLACEHOLDER_TOKEN, TELEGRAM_PROXY_ORIGIN, telegramProxyFetch } from "./proxy-fetch.mjs";
 import { messagesRoute } from "./requests.mjs";
-import { deliverUnlessSilent } from "./silent.mjs";
+import { withTurnErrorLogging } from "./turn-errors.mjs";
 import { telegramWebhookVerifier } from "./webhook.mjs";
 import { telegramChannel } from "eve/channels/telegram";
 const eveHistory = async (sessionId) => {
@@ -30,7 +32,11 @@ const eveHistory = async (sessionId) => {
 		follow: false
 	})) events.push({
 		type: event.type,
-		meta: { at: event.meta.at }
+		meta: { at: event.meta.at },
+		...event.type === "message.completed" ? { data: {
+			message: event.data.message,
+			finishReason: event.data.finishReason
+		} } : {}
 	});
 	return events;
 };
@@ -38,9 +44,10 @@ function segmentstreamTelegram(options) {
 	const environment = options.environment ?? process.env;
 	const token = options.token ?? runtimeToken;
 	const observed = options.observed ?? observedMessages();
+	const readHistory = options.history ?? eveHistory;
 	const policy = sessionPolicy({
 		settings: options.sessions,
-		read: options.history ?? eveHistory
+		read: readHistory
 	});
 	const bot = botIdentityCache();
 	const proxies = new Map();
@@ -74,6 +81,15 @@ function segmentstreamTelegram(options) {
 		return identities;
 	}
 	const chats = agentChats({ identities: pairing });
+	let store = options.attachments;
+	function attachments() {
+		store ??= agentAttachments({
+			origin: appOrigin(environment),
+			token,
+			...options.fetch === void 0 ? {} : { fetch: options.fetch }
+		});
+		return store;
+	}
 	const channel = telegramChannel({
 		api: {
 			apiBaseUrl: TELEGRAM_PROXY_ORIGIN,
@@ -84,7 +100,7 @@ function segmentstreamTelegram(options) {
 			botToken: TELEGRAM_PLACEHOLDER_TOKEN,
 			webhookVerifier: telegramWebhookVerifier(() => webhookSecret(environment))
 		},
-		uploadPolicy: { maxBytes: MAXIMUM_PROXY_BODY_BYTES },
+		uploadPolicy: { maxBytes: MAXIMUM_DOWNLOAD_BYTES },
 		onMessage: (context, message) => handleInboundMessage({
 			context,
 			message,
@@ -105,15 +121,40 @@ function segmentstreamTelegram(options) {
 					proxy: proxy(),
 					fileId
 				}),
+				attachments: attachments(),
 				observed,
+				readHistory,
 				chats,
 				connectUrl: (code) => `${appOrigin(environment)}/agent/connect?code=${encodeURIComponent(code)}`
 			}
 		}),
-		events: { "message.completed": deliverUnlessSilent }
+		events: { "message.completed": replyDelivery(observed) }
 	});
+	const adapter = channel.adapter;
+	const fetchTelegramFile = adapter?.fetchFile;
+	const turnFailed = adapter?.["turn.failed"];
+	async function fetchFile(url, context) {
+		const reference = parseAttachmentUrl(url);
+		if (reference === void 0) return fetchTelegramFile === void 0 ? null : fetchTelegramFile(url, context);
+		const sessionId = sessionIdOf(context);
+		const { attachment, bytes } = await attachments().read({
+			memberId: reference.memberId,
+			conversation: reference.conversation,
+			...sessionId === void 0 ? {} : { sessionId }
+		}, reference.id);
+		return {
+			bytes: Buffer.from(bytes),
+			mediaType: attachment.contentType,
+			filename: attachment.filename
+		};
+	}
 	return {
 		...channel,
+		...adapter === void 0 ? {} : { adapter: {
+			...adapter,
+			fetchFile,
+			...turnFailed === void 0 ? {} : { "turn.failed": withTurnErrorLogging(turnFailed) }
+		} },
 		routes: [...channel.routes.map((route) => gatedRoute({
 			route,
 			options,
@@ -128,6 +169,10 @@ function segmentstreamTelegram(options) {
 		})]
 	};
 }
+function sessionIdOf(context) {
+	const session = typeof context === "object" && context !== null ? context.session : void 0;
+	return typeof session?.id === "string" && session.id !== "" ? session.id : void 0;
+}
 function gatedRoute(input) {
 	const { route, options, environment } = input;
 	if (route.transport === "websocket") return route;

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

@@ -0,0 +1,25 @@
+import type { TelegramMessage } from "eve/channels/telegram";
+import { type AgentAttachments } from "../attachments.js";
+import type { StagedFile } from "./inbound-request.js";
+/**
+ * Photos and documents a member sends the agent (`docs/agent.md`, "Attachments"). Before the turn
+ * starts, each file is downloaded through the connection and stored once as a temporary attachment
+ * of the member, in this chat, for 24 hours. The turn reads the stored copy, and the model learns
+ * each attachment's id from an `<attachments>` block, so that it can read, discard or promote it
+ * with the attachment tools. A file that cannot be stored is never passed on silently: the turn
+ * gets a note saying why.
+ */
+/** The chat an attachment belongs to: `telegram:<chat id>`. */
+export declare function telegramConversation(chatId: string): string;
+/** Stores the message's files one after another, so that a large album holds one file at a time. */
+export declare function stageFiles(input: {
+    readonly message: TelegramMessage;
+    readonly memberId: string;
+    readonly attachments: AgentAttachments;
+    readonly download: (fileId: string) => Promise<Uint8Array>;
+}): Promise<ReadonlyMap<string, StagedFile>>;
+/** The `<attachments>` block that tells the model which attachments the message carries. */
+export declare function attachmentsContext(input: {
+    readonly files: ReadonlyMap<string, StagedFile>;
+    readonly group: boolean;
+}): ReadonlyArray<string>;

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

@@ -0,0 +1,77 @@
+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 { MAXIMUM_ATTACHMENT_BYTES, attachmentUrl } from "../attachments.mjs";
+function telegramConversation(chatId) {
+	return `telegram:${chatId}`;
+}
+function described(file, index) {
+	return {
+		filename: file.fileName ?? (file.kind === "photo" ? `photo-${index}.jpg` : `file-${index}`),
+		contentType: file.mediaType ?? (file.kind === "photo" ? "image/jpeg" : "application/octet-stream")
+	};
+}
+function megabytes(bytes) {
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+async function stageFiles(input) {
+	const { message } = input;
+	const conversation = telegramConversation(message.chat.id);
+	const staged = new Map();
+	for (const [index, file] of message.attachments.entries()) {
+		const { filename, contentType } = described(file, index);
+		if (file.size !== void 0 && file.size > MAXIMUM_ATTACHMENT_BYTES) {
+			staged.set(file.fileId, {
+				status: "refused",
+				filename,
+				reason: `it is ${megabytes(file.size)}, over the ${megabytes(MAXIMUM_ATTACHMENT_BYTES)} a bot may download`
+			});
+			continue;
+		}
+		try {
+			const bytes = await input.download(file.fileId);
+			const attachment = await input.attachments.receive({
+				memberId: input.memberId,
+				conversation
+			}, {
+				bytes,
+				filename,
+				contentType,
+				sourceRef: `${message.chat.id}:${message.messageId}:${index}`
+			});
+			staged.set(file.fileId, {
+				status: "stored",
+				attachment,
+				url: attachmentUrl({
+					id: attachment.id,
+					memberId: input.memberId,
+					conversation
+				})
+			});
+		} catch (error) {
+			console.error("[segmentstream] attachment could not be stored", {
+				kind: file.kind,
+				size: file.size,
+				error
+			});
+			staged.set(file.fileId, {
+				status: "refused",
+				filename,
+				reason: error instanceof Error ? error.message : "it could not be stored"
+			});
+		}
+	}
+	return staged;
+}
+function attachmentsContext(input) {
+	if (input.files.size === 0) return [];
+	const lines = ["<attachments>", `The member's files from this message, kept for 24 hours for this member in this chat only. Read, discard or promote them with the segmentstream__attachments_* tools and these ids; promote only what should be kept.`];
+	for (const staged of input.files.values()) lines.push(staged.status === "stored" ? `- id: ${staged.attachment.id}, filename: ${JSON.stringify(staged.attachment.filename)}, type: ${staged.attachment.contentType}, size: ${staged.attachment.size} bytes, expires_at: ${staged.attachment.expiresAt}` : `- ${JSON.stringify(staged.filename)}: not received, ${staged.reason}`);
+	if (input.group) lines.push("This is a group chat: everyone in it shares this conversation's history, so do not repeat a private file's contents here. Suggest sending private files in a direct message.");
+	lines.push("</attachments>");
+	return [lines.join("\n")];
+}
+export { attachmentsContext, stageFiles, telegramConversation };

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

@@ -1,5 +1,16 @@
 import type { ChannelSource } from "eve/channels";
+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. */
+export type StagedFile = {
+    readonly status: "stored";
+    readonly attachment: Attachment;
+    readonly url: URL;
+} | {
+    readonly status: "refused";
+    readonly filename: string;
+    readonly reason: string;
+};
 /**
  * What one webhook request shares between eve's `onMessage` hook and the route wrapper around it.
  * `onMessage` may only return `{ auth, context, title }`; it cannot change the message eve sends.
@@ -12,6 +23,11 @@ export declare class InboundRequest {
     readonly agentDescription: () => Promise<string>;
     /** The text the turn should carry instead of the parsed message, once a transcript exists. */
     text: string | undefined;
+    /**
+     * The message's Telegram files by file id, once stored as attachments: the turn reads each from
+     * the attachment store instead of Telegram, and one that could not be stored becomes a note.
+     */
+    files: ReadonlyMap<string, StagedFile> | undefined;
     /** The route's session operations, on addresses already mapped to the configured scope. */
     sessions: SessionOperations | undefined;
     /** Keeps work the request started, such as a chat report, alive after it answers. */
@@ -23,5 +39,8 @@ export declare class InboundRequest {
 export declare function runInboundRequest<Result>(request: InboundRequest, run: () => Result): Result;
 /** The current webhook request, or `undefined` outside the wrapped route. */
 export declare function currentInboundRequest(): InboundRequest | undefined;
-/** A channel source whose `send` delivers the request's replacement text, when one was recorded. */
+/**
+ * A channel source whose `send` delivers the request's replacement text, when one was recorded,
+ * and its stored attachments in place of the Telegram files.
+ */
 export declare function withReplacedText<State>(source: ChannelSource<State>, request: InboundRequest): ChannelSource<State>;

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

@@ -8,6 +8,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 var InboundRequest = class {
 	agentDescription;
 	text;
+	files;
 	sessions;
 	waitUntil;
 	constructor(agentDescription) {
@@ -28,11 +29,38 @@ function replaceText(message, text) {
 		text
 	}, ...message.filter((part) => part.type !== "text")];
 }
+function telegramFileId(data) {
+	const href = data instanceof URL ? data.href : typeof data === "string" ? data : void 0;
+	if (href === void 0 || !href.startsWith("telegram-file:")) return;
+	try {
+		return decodeURIComponent(new URL(href).pathname);
+	} catch {
+		return;
+	}
+}
+function replaceFiles(message, files) {
+	if (typeof message === "string") return message;
+	return message.map((part) => {
+		if (part.type !== "file") return part;
+		const fileId = telegramFileId(part.data);
+		const staged = fileId === void 0 ? void 0 : files.get(fileId);
+		if (staged === void 0) return part;
+		if (staged.status === "refused") return {
+			type: "text",
+			text: `[file ${staged.filename} was not received: ${staged.reason}]`
+		};
+		return {
+			...part,
+			data: staged.url
+		};
+	});
+}
 function withReplacedText(source, request) {
 	return {
 		...source,
 		send(message, options) {
-			return source.send(request.text === void 0 ? message : replaceText(message, request.text), options);
+			const text = request.text === void 0 ? message : replaceText(message, request.text);
+			return source.send(request.files === void 0 ? text : replaceFiles(text, request.files), options);
 		}
 	};
 }

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

@@ -1,12 +1,13 @@
 import type { TelegramContext, TelegramInboundResult, TelegramMessage } from "eve/channels/telegram";
 import type { SessionSettings, TelegramPolicy } from "../../config.js";
+import type { AgentAttachments } from "../attachments.js";
 import type { AgentIdentities } from "../identities.js";
 import type { BotIdentityLookup } from "./bot.js";
 import { type AgentChats } from "./chats.js";
 import type { InboundRequest } from "./inbound-request.js";
 import { type ObservedMessages } from "./observed.js";
 import { type RouteDecider } from "./router.js";
-import { type SessionPolicy } from "./sessions.js";
+import { type HistoryReader, type SessionPolicy } from "./sessions.js";
 import { type Transcriber } from "./voice.js";
 /**
  * eve's Telegram `onMessage` hook, in the order `agent-design.md` gives:
@@ -21,10 +22,13 @@ import { type Transcriber } from "./voice.js";
  * 3. The router answers or observes. An observed message goes to the chat's ring and stops here.
  * 4. The session policy runs on the session the message continues: an idle one is cleared, the
  *    first message after the day's compaction time compacts it.
- * 5. An answered message dispatches as the paired member, with the ring, the registry's `<chat>`
- *    block and a `<speaker>` block naming the member, their roles and the message they replied to
- *    ahead of it as context. An answered group message waits for its chat's report first, so that
- *    a chat new to the process already carries its `<chat>` block.
+ * 5. An answered message's photos and documents are stored as the member's temporary attachments,
+ *    which the turn reads in place of the Telegram files.
+ * 6. An answered message dispatches as the paired member, with the ring, the registry's `<chat>`
+ *    block, a `<speaker>` block naming the member, their roles and the message they replied to and
+ *    an `<attachments>` block naming its stored files ahead of it as context. An answered group
+ *    message waits for its chat's report first, so that a chat new to the process already carries
+ *    its `<chat>` block.
  */
 export interface InboundDependencies {
     readonly policy: TelegramPolicy;
@@ -36,7 +40,10 @@ export interface InboundDependencies {
     readonly decide: RouteDecider;
     readonly transcribe: Transcriber;
     readonly download: (fileId: string) => Promise<Uint8Array>;
+    /** The attachment store; without it, files reach the turn as eve's Telegram file parts. */
+    readonly attachments?: AgentAttachments;
     readonly observed: ObservedMessages;
+    readonly readHistory: HistoryReader;
     readonly chats: AgentChats;
     /** The app's `/agent/connect` link for a pairing code. */
     readonly connectUrl: (code: string) => string;