@mono-agent/telegram-adapter 0.3.0 → 0.4.0

package/README.md

@@ -10,6 +10,10 @@ Telegram communication adapter for agent hosts. It provides a Bot API client, lo
 
 The adapter is opt-in: `telegram.enabled` / `MONO_AGENT_TELEGRAM_ENABLED` defaults to `false`. While disabled the loader skips credential validation and the channel reports `disabled` rather than `waiting_for_config`. Set `enabled: true` to turn it on; a missing bot token or allowlist then surfaces as a real `waiting_for_config` reason.
 
+Inbound Telegram document, photo, audio, video, and voice messages are downloaded (subject to the MIME allowlist and ~20 MB cap) and delivered to the responder as transport-agnostic `AgentAttachment` bytes on the shared `AgentRequestBase.attachments` contract (decoded `mimeType` + base64 `data` + `name`). Captions remain the request text; media-only messages still get a concise text summary so existing text-only responder paths can reason about what arrived. The original Telegram file metadata (file id, sizes, kind) is preserved under `metadata.telegram.attachments`.
+
+Downloads are gated by the configured allowlist and size cap, and a download failure skips the attachment without failing the run. Whether the model actually consumes the images/documents depends on the host runtime's vision/document support — the adapter forwards bytes but does not itself guarantee model-level understanding.
+
 ## Install / Usage
 
 ```bash
@@ -18,10 +22,10 @@ pnpm --filter @mono-agent/telegram-adapter run build
 
 ```ts
 import {
-  TelegramAdapter,
-  TelegramBotApiClient,
-  TelegramLongPoller,
+  createTelegramBot,
+  createGrammyTelegramApi,
   loadTelegramAdapterConfig,
+  startTelegramAdapter,
   telegramFieldGroup,
 } from "@mono-agent/telegram-adapter";
 ```
@@ -30,16 +34,17 @@ Load adapter settings separately from core config, then pass a structural `Agent
 
 ## Public API
 
-- `TelegramAdapter`, `TelegramAdapterOptions`
-- `TelegramBotApiClient`, `TelegramApiError`
-- `TelegramLongPoller`
-- `TelegramMessageStream`, `splitTelegramText`
+- `createTelegramBot`, `startTelegramAdapter`
+- `createGrammyTelegramApi`, `TelegramApiError`
+- `TelegramMessageStream`, `classifyTelegramError`
 - `loadTelegramAdapterConfig`, `redactTelegramAdapterConfig`, `telegramFieldGroup`
+- `downloadTelegramAttachments` (+ `DownloadTelegramAttachmentsOptions`, `TelegramFileDownloader`): the inbound-bytes flow that maps `TelegramAttachment` metadata to `AgentAttachment` bytes on `request.attachments`
+- `TelegramAttachment` and related Telegram-owned inbound attachment metadata types (preserved under `metadata.telegram.attachments`)
 - Telegram Bot API, request/response, and config types
 
 ## Dependency Boundary
 
-This adapter depends only on shared contracts and settings primitives inside the workspace. It does not depend on the harness, operator console, core config, memory, runtime package, or other adapters. Hosts compose those pieces outside the adapter.
+This adapter depends only on shared contracts and settings primitives inside the workspace. It does not depend on the harness, core config, memory, runtime package, or other adapters. Hosts compose those pieces outside the adapter.
 
 ## What This Package Does Not Own
 

package/dist/adapter.d.ts

@@ -1,6 +1,55 @@
-import type { AgentRequestBase, AgentResponder as SharedAgentResponder, AgentResponse } from "@mono-agent/agent-contracts";
+import type { AgentAttachment, AgentRequestBase, AgentResponder as SharedAgentResponder, AgentResponse } from "@mono-agent/agent-contracts";
 import { TelegramMessageStream, type AgentMessageStream, type TelegramMessageStreamLogger } from "./message-stream.js";
 import type { TelegramChatId, TelegramMessage, TelegramUpdate } from "./types.js";
+export type TelegramAttachmentKind = "document" | "photo" | "audio" | "video" | "voice";
+export interface TelegramAttachmentBase {
+    kind: TelegramAttachmentKind;
+    fileId: string;
+    fileUniqueId: string;
+    fileSize?: number;
+}
+export interface TelegramDocumentAttachment extends TelegramAttachmentBase {
+    kind: "document";
+    fileName?: string;
+    mimeType?: string;
+}
+export interface TelegramPhotoAttachmentSize {
+    fileId: string;
+    fileUniqueId: string;
+    width: number;
+    height: number;
+    fileSize?: number;
+}
+export interface TelegramPhotoAttachment extends TelegramAttachmentBase {
+    kind: "photo";
+    width: number;
+    height: number;
+    sizes: readonly TelegramPhotoAttachmentSize[];
+}
+export interface TelegramAudioAttachment extends TelegramAttachmentBase {
+    kind: "audio";
+    duration: number;
+    fileName?: string;
+    mimeType?: string;
+}
+export interface TelegramVideoAttachment extends TelegramAttachmentBase {
+    kind: "video";
+    duration: number;
+    width: number;
+    height: number;
+    fileName?: string;
+    mimeType?: string;
+}
+export interface TelegramVoiceAttachment extends TelegramAttachmentBase {
+    kind: "voice";
+    duration: number;
+    mimeType?: string;
+}
+export type TelegramAttachment = TelegramDocumentAttachment | TelegramPhotoAttachment | TelegramAudioAttachment | TelegramVideoAttachment | TelegramVoiceAttachment;
+export interface TelegramAgentMessageInput {
+    text: string;
+    attachments: readonly TelegramAttachment[];
+}
 export interface AgentRequest extends AgentRequestBase {
     conversationId: string;
     chatId: TelegramChatId;
@@ -9,6 +58,19 @@ export interface AgentRequest extends AgentRequestBase {
     userId?: number;
     username?: string;
     text: string;
+    /**
+     * Downloaded attachment bytes, ready for a vision/document-aware runtime, in
+     * the transport-agnostic {@link AgentAttachment} shape (base64 data + mime +
+     * name).
+     *
+     * BREAKING (intentional, unified contract): on earlier versions this field
+     * held Telegram-specific `TelegramAttachment[]` metadata. It is now
+     * `AgentAttachment[]` (matching Slack and the OpenAI-compatible channel). The
+     * original Telegram file metadata (fileId, sizes, kind, …) is preserved under
+     * `metadata.telegram.attachments` — custom responders that filtered by
+     * `fileId`/`sizes`/`kind` should read it from there.
+     */
+    attachments?: readonly AgentAttachment[];
     abortSignal: AbortSignal;
     metadata: {
         telegram: TelegramRequestMetadata;
@@ -27,6 +89,7 @@ export interface TelegramRequestMetadata {
         id: number;
         date?: number;
     };
+    attachments?: readonly TelegramAttachment[];
     from?: {
         id: number;
         isBot?: boolean;
@@ -60,7 +123,13 @@ export interface TelegramAdapterStreamOptions {
     retryCapMs?: number;
     retryBaseDelayMs?: number;
     showThoughts?: boolean;
+    showHints?: boolean;
     formatMarkdown?: boolean;
+    /**
+     * Deliver only the final answer with a "typing…" indicator while working,
+     * instead of streaming interim edits. Defaults to true for the Telegram bot.
+     */
+    finalOnly?: boolean;
 }
 export interface TelegramAdapterLogger extends TelegramMessageStreamLogger {
     info?(message: string, metadata?: Record<string, unknown>): void;
@@ -71,8 +140,65 @@ export declare const DEFAULT_MESSAGES: Required<TelegramAdapterMessages>;
  * Build the responder-facing {@link AgentRequest} from a Telegram update. The
  * grammY message handler passes `ctx.update` and `ctx.message`, which are
  * structurally compatible with the wire types this reads.
+ *
+ * `resolvedAttachments` are the downloaded {@link AgentAttachment} bytes (when
+ * available) that populate `request.attachments`; the original Telegram file
+ * metadata is always preserved under `metadata.telegram.attachments`.
+ */
+export declare function buildAgentRequest(update: TelegramUpdate, message: TelegramMessage, input: TelegramAgentMessageInput, abortSignal: AbortSignal, resolvedAttachments?: readonly AgentAttachment[]): AgentRequest;
+export declare function normalizeTelegramMessageInput(message: TelegramMessage): TelegramAgentMessageInput | undefined;
+/**
+ * Merge a Telegram media-group (album) into a single input: Telegram delivers an
+ * album of N photos/videos as N separate messages sharing one `media_group_id`,
+ * with the caption on only one of them. We concatenate every message's
+ * attachments and take the single caption (first non-empty), so the agent sees
+ * all photos as one request instead of N single-attachment turns.
+ */
+export declare function mergeTelegramMessageInputs(messages: readonly TelegramMessage[]): TelegramAgentMessageInput | undefined;
+/** Telegram's hard cap for bot file downloads is 20 MB. */
+export declare const DEFAULT_ATTACHMENT_MAX_BYTES: number;
+/**
+ * MIME types the adapter will download and inline. Images flow to vision-capable
+ * runtimes; documents/text are saved to disk (and decoded inline for text/*).
+ */
+export declare const DEFAULT_ATTACHMENT_MIME_ALLOWLIST: readonly string[];
+/**
+ * Minimal seam over the Telegram Bot API needed to fetch attachment bytes:
+ * resolve a `file_id` to a `file_path` (getFile) then download it from the file
+ * URL. Both calls honor the request `abortSignal`.
+ */
+export interface TelegramFileDownloader {
+    /** Resolve a `file_id` to a downloadable `file_path` (Bot API `getFile`). */
+    resolveFilePath(fileId: string, signal: AbortSignal): Promise<string | undefined>;
+    /**
+     * Download the file at `file_path` (GET on the file URL). `maxBytes`, when
+     * provided, lets the downloader abort an oversized transfer mid-stream instead
+     * of buffering the whole body first; the caller still re-checks the cap as a
+     * backstop, so a custom downloader that ignores `maxBytes` stays bounded.
+     */
+    download(filePath: string, signal: AbortSignal, maxBytes?: number): Promise<Uint8Array>;
+}
+export interface DownloadTelegramAttachmentsOptions {
+    /** Skip files larger than this many decoded bytes. Default ~20 MB. */
+    readonly maxBytes?: number;
+    /** Only download files whose MIME type is allowed. Defaults to images + common docs/text. */
+    readonly mimeAllowlist?: readonly string[];
+    /**
+     * Per-file download timeout (ms) for the default downloader, composed with the
+     * run abort signal. Defaults to 30000. Only consulted by the built-in
+     * downloader; custom downloaders manage their own timeouts.
+     */
+    readonly downloadTimeoutMs?: number;
+    readonly logger?: TelegramAdapterLogger;
+}
+/**
+ * Download the bytes for each inbound {@link TelegramAttachment} and map them to
+ * the transport-agnostic {@link AgentAttachment} shape. Enforces a byte cap and a
+ * MIME allowlist, ties every request to `abortSignal`, and skips (never throws on)
+ * an attachment whose download fails so the run still proceeds. Photos and audio
+ * without a declared MIME type fall back to sensible defaults.
  */
-export declare function buildAgentRequest(update: TelegramUpdate, message: TelegramMessage, text: string, abortSignal: AbortSignal): AgentRequest;
+export declare function downloadTelegramAttachments(attachments: readonly TelegramAttachment[], downloader: TelegramFileDownloader, abortSignal: AbortSignal, options?: DownloadTelegramAttachmentsOptions): Promise<AgentAttachment[]>;
 /**
  * Deliver a terminal/system message (cancelled, error, …) in place. Such copy is
  * fixed text we author, not model output, so it is delivered as plain text

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -1,36 +1,47 @@
 import { TelegramMessageStream, } from "./message-stream.js";
 export const DEFAULT_ERROR_TEXT = "The agent failed while processing your message.";
 export const DEFAULT_MESSAGES = {
-    welcomeText: "Hello! Send me a text message and I will pass it to the configured agent.",
-    helpText: "Send a text message to talk to the agent. Use /cancel to stop the current response.",
+    welcomeText: "Hello! Send text or Telegram media. I pass your caption and download allowed attachments to share with the configured agent.",
+    helpText: "Send text, documents, photos, audio, video, or voice messages. I forward your caption and download supported attachments (within size/type limits) for the agent. Use /cancel to stop the current response.",
     busyText: "I am still working on your previous message. Use /cancel to stop it.",
     unauthorizedText: "This Telegram chat is not authorized to use this bot.",
     cancelledText: "Cancelled.",
     errorText: DEFAULT_ERROR_TEXT,
-    unsupportedText: "I can only handle text messages in this adapter for now.",
+    unsupportedText: "I can handle text and Telegram document, photo, audio, video, or voice metadata in this adapter.",
 };
 /**
  * Build the responder-facing {@link AgentRequest} from a Telegram update. The
  * grammY message handler passes `ctx.update` and `ctx.message`, which are
  * structurally compatible with the wire types this reads.
+ *
+ * `resolvedAttachments` are the downloaded {@link AgentAttachment} bytes (when
+ * available) that populate `request.attachments`; the original Telegram file
+ * metadata is always preserved under `metadata.telegram.attachments`.
  */
-export function buildAgentRequest(update, message, text, abortSignal) {
+export function buildAgentRequest(update, message, input, abortSignal, resolvedAttachments) {
     const from = metadataFromUser(message.from);
+    const telegramMetadata = {
+        updateId: update.update_id,
+        chat: metadataFromChat(message.chat),
+        message: metadataFromMessage(message),
+    };
+    if (input.attachments.length > 0) {
+        telegramMetadata.attachments = input.attachments;
+    }
     const request = {
         conversationId: `telegram:${String(message.chat.id)}`,
         chatId: message.chat.id,
         messageId: message.message_id,
         updateId: update.update_id,
-        text,
+        text: input.text,
         abortSignal,
         metadata: {
-            telegram: {
-                updateId: update.update_id,
-                chat: metadataFromChat(message.chat),
-                message: metadataFromMessage(message),
-            },
+            telegram: telegramMetadata,
         },
     };
+    if (resolvedAttachments !== undefined && resolvedAttachments.length > 0) {
+        request.attachments = resolvedAttachments;
+    }
     if (message.from?.id !== undefined) {
         request.userId = message.from.id;
     }
@@ -42,6 +53,50 @@ export function buildAgentRequest(update, message, text, abortSignal) {
     }
     return request;
 }
+export function normalizeTelegramMessageInput(message) {
+    if (message.animation !== undefined) {
+        return undefined;
+    }
+    const text = normalizeMessageText(message);
+    const attachments = extractTelegramAttachments(message);
+    if (text.length === 0 && attachments.length === 0) {
+        return undefined;
+    }
+    return {
+        text: text.length > 0 ? text : summarizeTelegramAttachments(attachments),
+        attachments,
+    };
+}
+/**
+ * Merge a Telegram media-group (album) into a single input: Telegram delivers an
+ * album of N photos/videos as N separate messages sharing one `media_group_id`,
+ * with the caption on only one of them. We concatenate every message's
+ * attachments and take the single caption (first non-empty), so the agent sees
+ * all photos as one request instead of N single-attachment turns.
+ */
+export function mergeTelegramMessageInputs(messages) {
+    const attachments = [];
+    let text = "";
+    for (const message of messages) {
+        if (message.animation !== undefined) {
+            continue;
+        }
+        if (text.length === 0) {
+            const messageText = normalizeMessageText(message);
+            if (messageText.length > 0) {
+                text = messageText;
+            }
+        }
+        attachments.push(...extractTelegramAttachments(message));
+    }
+    if (text.length === 0 && attachments.length === 0) {
+        return undefined;
+    }
+    return {
+        text: text.length > 0 ? text : summarizeTelegramAttachments(attachments),
+        attachments,
+    };
+}
 function metadataFromChat(messageChat) {
     const chat = { id: messageChat.id };
     if (messageChat.type !== undefined) {
@@ -62,6 +117,323 @@ function metadataFromMessage(message) {
     }
     return metadata;
 }
+function normalizeMessageText(message) {
+    return (message.text ?? message.caption ?? "").trim();
+}
+function extractTelegramAttachments(message) {
+    const attachments = [];
+    const document = attachmentFromDocument(message.document);
+    if (document !== undefined) {
+        attachments.push(document);
+    }
+    const photo = attachmentFromPhoto(message.photo);
+    if (photo !== undefined) {
+        attachments.push(photo);
+    }
+    const audio = attachmentFromAudio(message.audio);
+    if (audio !== undefined) {
+        attachments.push(audio);
+    }
+    const video = attachmentFromVideo(message.video);
+    if (video !== undefined) {
+        attachments.push(video);
+    }
+    const voice = attachmentFromVoice(message.voice);
+    if (voice !== undefined) {
+        attachments.push(voice);
+    }
+    return attachments;
+}
+function attachmentFromDocument(document) {
+    if (document === undefined) {
+        return undefined;
+    }
+    const attachment = {
+        kind: "document",
+        fileId: document.file_id,
+        fileUniqueId: document.file_unique_id,
+    };
+    addFileSize(attachment, document.file_size);
+    if (document.file_name !== undefined) {
+        attachment.fileName = document.file_name;
+    }
+    if (document.mime_type !== undefined) {
+        attachment.mimeType = document.mime_type;
+    }
+    return attachment;
+}
+function attachmentFromPhoto(photos) {
+    const sizes = photos?.map(photoSizeFromTelegram).filter(isDefined) ?? [];
+    if (sizes.length === 0) {
+        return undefined;
+    }
+    const largest = sizes.reduce((best, candidate) => candidate.width * candidate.height > best.width * best.height ? candidate : best);
+    const attachment = {
+        kind: "photo",
+        fileId: largest.fileId,
+        fileUniqueId: largest.fileUniqueId,
+        width: largest.width,
+        height: largest.height,
+        sizes,
+    };
+    addFileSize(attachment, largest.fileSize);
+    return attachment;
+}
+function attachmentFromAudio(audio) {
+    if (audio === undefined) {
+        return undefined;
+    }
+    const attachment = {
+        kind: "audio",
+        fileId: audio.file_id,
+        fileUniqueId: audio.file_unique_id,
+        duration: audio.duration,
+    };
+    addFileSize(attachment, audio.file_size);
+    if (audio.file_name !== undefined) {
+        attachment.fileName = audio.file_name;
+    }
+    if (audio.mime_type !== undefined) {
+        attachment.mimeType = audio.mime_type;
+    }
+    return attachment;
+}
+function attachmentFromVideo(video) {
+    if (video === undefined) {
+        return undefined;
+    }
+    const attachment = {
+        kind: "video",
+        fileId: video.file_id,
+        fileUniqueId: video.file_unique_id,
+        duration: video.duration,
+        width: video.width,
+        height: video.height,
+    };
+    addFileSize(attachment, video.file_size);
+    if (video.file_name !== undefined) {
+        attachment.fileName = video.file_name;
+    }
+    if (video.mime_type !== undefined) {
+        attachment.mimeType = video.mime_type;
+    }
+    return attachment;
+}
+function attachmentFromVoice(voice) {
+    if (voice === undefined) {
+        return undefined;
+    }
+    const attachment = {
+        kind: "voice",
+        fileId: voice.file_id,
+        fileUniqueId: voice.file_unique_id,
+        duration: voice.duration,
+    };
+    addFileSize(attachment, voice.file_size);
+    if (voice.mime_type !== undefined) {
+        attachment.mimeType = voice.mime_type;
+    }
+    return attachment;
+}
+function photoSizeFromTelegram(size) {
+    const attachmentSize = {
+        fileId: size.file_id,
+        fileUniqueId: size.file_unique_id,
+        width: size.width,
+        height: size.height,
+    };
+    addFileSize(attachmentSize, size.file_size);
+    return attachmentSize;
+}
+function addFileSize(target, fileSize) {
+    if (typeof fileSize === "number" && Number.isFinite(fileSize)) {
+        target.fileSize = fileSize;
+    }
+}
+function isDefined(value) {
+    return value !== undefined;
+}
+function summarizeTelegramAttachments(attachments) {
+    return attachments.map(describeTelegramAttachment).join("\n");
+}
+function describeTelegramAttachment(attachment) {
+    const details = attachmentDetails(attachment);
+    return details.length === 0
+        ? `Telegram ${attachment.kind}`
+        : `Telegram ${attachment.kind}: ${details.join(", ")}`;
+}
+function attachmentDetails(attachment) {
+    const details = [];
+    if ("fileName" in attachment && attachment.fileName !== undefined) {
+        details.push(attachment.fileName);
+    }
+    if ("mimeType" in attachment && attachment.mimeType !== undefined) {
+        details.push(attachment.mimeType);
+    }
+    if ("width" in attachment && "height" in attachment) {
+        details.push(`${attachment.width}x${attachment.height}`);
+    }
+    if ("duration" in attachment) {
+        details.push(`${attachment.duration}s`);
+    }
+    if (attachment.fileSize !== undefined) {
+        details.push(formatBytes(attachment.fileSize));
+    }
+    return details;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${Math.round(bytes / 1024)} KB`;
+    }
+    return `${Math.round(bytes / (1024 * 1024))} MB`;
+}
+/** Telegram's hard cap for bot file downloads is 20 MB. */
+export const DEFAULT_ATTACHMENT_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * MIME types the adapter will download and inline. Images flow to vision-capable
+ * runtimes; documents/text are saved to disk (and decoded inline for text/*).
+ */
+export const DEFAULT_ATTACHMENT_MIME_ALLOWLIST = [
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "application/pdf",
+    "application/json",
+    "application/zip",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+    "text/plain",
+    "text/markdown",
+    "text/csv",
+    "text/html",
+    // Audio (Telegram voice messages normalize to audio/ogg; see attachmentMimeType).
+    "audio/ogg",
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/aac",
+    "audio/wav",
+    "audio/webm",
+    // Video.
+    "video/mp4",
+    "video/mpeg",
+    "video/quicktime",
+    "video/webm",
+];
+/**
+ * Download the bytes for each inbound {@link TelegramAttachment} and map them to
+ * the transport-agnostic {@link AgentAttachment} shape. Enforces a byte cap and a
+ * MIME allowlist, ties every request to `abortSignal`, and skips (never throws on)
+ * an attachment whose download fails so the run still proceeds. Photos and audio
+ * without a declared MIME type fall back to sensible defaults.
+ */
+export async function downloadTelegramAttachments(attachments, downloader, abortSignal, options) {
+    const maxBytes = options?.maxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES;
+    const allowlist = new Set((options?.mimeAllowlist ?? DEFAULT_ATTACHMENT_MIME_ALLOWLIST).map((mime) => mime.toLowerCase()));
+    const logger = options?.logger;
+    const resolved = [];
+    for (const attachment of attachments) {
+        if (abortSignal.aborted) {
+            break;
+        }
+        const source = attachmentSource(attachment);
+        const mimeType = source.mimeType.toLowerCase();
+        if (!allowlist.has(mimeType)) {
+            logger?.debug?.("Skipping Telegram attachment with disallowed MIME type.", {
+                mimeType: source.mimeType,
+                name: source.name,
+            });
+            continue;
+        }
+        if (source.declaredSize !== undefined && source.declaredSize > maxBytes) {
+            logger?.debug?.("Skipping oversized Telegram attachment.", {
+                sizeBytes: source.declaredSize,
+                maxBytes,
+                name: source.name,
+            });
+            continue;
+        }
+        try {
+            const filePath = await downloader.resolveFilePath(source.fileId, abortSignal);
+            if (filePath === undefined) {
+                logger?.warn?.("Telegram getFile returned no file_path; skipping attachment.", {
+                    fileId: source.fileId,
+                    name: source.name,
+                });
+                continue;
+            }
+            const bytes = await downloader.download(filePath, abortSignal, maxBytes);
+            if (bytes.byteLength > maxBytes) {
+                logger?.warn?.("Telegram attachment exceeded the size cap after download; skipping.", {
+                    sizeBytes: bytes.byteLength,
+                    maxBytes,
+                    name: source.name,
+                });
+                continue;
+            }
+            resolved.push(buildAgentAttachment(source, mimeType, bytes));
+        }
+        catch (error) {
+            // Download failures never fail the run — skip the attachment and continue.
+            logger?.warn?.("Failed to download Telegram attachment; skipping it.", {
+                fileId: source.fileId,
+                name: source.name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return resolved;
+}
+function buildAgentAttachment(source, mimeType, bytes) {
+    const kind = mimeType.startsWith("image/") ? "image" : "document";
+    const attachment = {
+        kind,
+        mimeType: source.mimeType,
+        data: Buffer.from(bytes).toString("base64"),
+        sizeBytes: bytes.byteLength,
+    };
+    if (source.name !== undefined) {
+        attachment.name = source.name;
+    }
+    if (mimeType.startsWith("text/")) {
+        attachment.text = Buffer.from(bytes).toString("utf8");
+    }
+    return attachment;
+}
+function attachmentSource(attachment) {
+    const name = "fileName" in attachment ? attachment.fileName : undefined;
+    return {
+        fileId: attachment.fileId,
+        mimeType: attachmentMimeType(attachment),
+        name,
+        declaredSize: attachment.fileSize,
+    };
+}
+function attachmentMimeType(attachment) {
+    if ("mimeType" in attachment && attachment.mimeType !== undefined) {
+        return attachment.mimeType;
+    }
+    if (attachment.kind === "photo") {
+        return "image/jpeg";
+    }
+    if (attachment.kind === "voice") {
+        return "audio/ogg";
+    }
+    // Telegram may omit mime_type on audio/video; fall back to a sensible default
+    // on the allowlist so the attachment is not skipped as application/octet-stream.
+    if (attachment.kind === "audio") {
+        return "audio/mpeg";
+    }
+    if (attachment.kind === "video") {
+        return "video/mp4";
+    }
+    return "application/octet-stream";
+}
 function metadataFromUser(user) {
     if (user === undefined) {
         return undefined;