@fastagent-sh/fastagent 0.24.4 → 0.26.0

package/dist/channels/telegram/invoke-turn.js

@@ -1,11 +1,11 @@
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, loadBackground, missingAttachmentsNote, turnStream, } from "../kit/invoke-turn-kit.js";
+import { attachedFilesManifest, attributedFileName, loadBackground, missingAttachmentsNote, turnStream, promptContent, } from "../kit/invoke-turn-kit.js";
 import { resolveFiles, resolveImages } from "./telegram-api.js";
 /** Appended to the prompt (not the system prompt): the channel owns Telegram-HTML formatting. */
 const HTML_INSTRUCTION = "\n\n(Format your reply in Telegram-supported HTML — <b> <i> <u> <s> <code> <pre> <a href> — not Markdown.)";
 /**
  * Resolve a turn's attachments: images (vision) inline, files downloaded to disk with their absolute
  * paths listed in a manifest the agent reads with its tools. Two tiers, different failure policies.
- * PRIMARY (this turn's own message) THROWS on any load failure — the caller turns it into a `failed`
+ * PRIMARY (this turn's own message) THROWS on any load failure — the caller turns it into a `rejected`
  * event, so the agent never runs on inputs the user sent but we failed to load. BACKGROUND (`buffered`,
  * from the un-summoned discussion) degrades PER ATTACHMENT — a warn + a prompt note — rather than
  * failing the ask it merely accompanies: one expired earlier file must neither block the answer nor drag
@@ -43,17 +43,17 @@ async function resolveTurnAttachments(t, attachments) {
 }
 /**
  * Run one turn: resolve its attachments, then ask the agent (invoke-turn-kit — a primary-attachment
- * failure surfaces as a `failed` event, never a silent drop).
+ * failure surfaces as a `rejected` event, never a silent drop). `key` is the turn's: the update it answers.
  */
-export function telegramTurnStream(agent, session, text, transport, attachments, busyRetry = DEFAULT_BUSY_RETRY) {
+export function telegramTurnStream(agent, turn, transport, attachments) {
     return turnStream({
         agent,
         label: "[telegram]",
-        busyRetry,
+        session: turn.session,
         resolve: () => resolveTurnAttachments(transport, attachments),
         turn: (resolved) => ({
-            scope: { session },
-            prompt: { text: `${text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, images: resolved.images },
+            idempotencyKey: turn.key,
+            content: promptContent(`${turn.text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, resolved.images),
         }),
         // A Bot API download that failed may simply succeed on the redelivery.
         retryableLoadFailure: () => true,

package/dist/channels/telegram/parse.d.ts

@@ -98,8 +98,8 @@ export interface TelegramUpdate {
  * ignore.
  */
 export interface TelegramRoute {
-    /** Conversation identity (default: `chat` or `chat:thread`). */
-    session?: string;
+    /** Which conversation it belongs to, the one its session is kept by (default: `chat` or `chat:thread`). */
+    conversation?: string;
     /** Reply target chat (default: the message's chat). */
     chatId?: number | string;
     /** Reply thread (default: the message's thread). */
@@ -117,6 +117,11 @@ export declare function ownImages(m: TelegramMessage): string[];
 export declare function extractFiles(m: TelegramMessage): string[];
 /** The message's OWN files, without the replied-to message's. */
 export declare function ownFiles(m: TelegramMessage): string[];
+/**
+ * The place a message lives in: a chat, or a forum topic within it. The context buffer's bucket and the default
+ * conversation, for an update and for a message the agent sends itself alike.
+ */
+export declare function telegramPlaceKey(chatId: number | string, threadId?: number): string;
 /** A stable sender label for attribution. */
 export declare function fromLabel(from: TelegramMessage["from"]): string | undefined;
 /**

package/dist/channels/telegram/parse.js

@@ -21,6 +21,13 @@ export function extractFiles(m) {
 export function ownFiles(m) {
     return [m.document?.file_id, m.voice?.file_id, m.video?.file_id, m.audio?.file_id].filter((id) => Boolean(id));
 }
+/**
+ * The place a message lives in: a chat, or a forum topic within it. The context buffer's bucket and the default
+ * conversation, for an update and for a message the agent sends itself alike.
+ */
+export function telegramPlaceKey(chatId, threadId) {
+    return threadId ? `${chatId}:${threadId}` : `${chatId}`;
+}
 /** A stable sender label for attribution. */
 export function fromLabel(from) {
     if (!from)

package/dist/channels/telegram/preview.d.ts

@@ -5,7 +5,7 @@
  * carry unbalanced HTML); on completion the same message is edited into the final answer as HTML. One
  * message, works in groups and private (unlike sendMessageDraft, which is private/forum-topic only).
  */
-import type { AgentEvent } from "../../agent.ts";
+import type { TurnEvent } from "../kit/invoke-turn-kit.ts";
 import * as Effect from "effect/Effect";
 import type * as Stream from "effect/Stream";
 import { type PortFailure } from "../../effect-port.ts";
@@ -25,4 +25,4 @@ export declare function deliverTelegramAnswer(api: string, botToken: string, tar
  * model). Preview edits are best-effort (logged once if they fail); the final write is authoritative
  * and surfaces a real failure (bad token, etc.).
  */
-export declare function telegramReply(events: Stream.Stream<AgentEvent, PortFailure>, api: string, botToken: string, target: Target, formatError: (failed: TelegramFailure) => string | undefined, previewId?: number, onAnswered?: (answer: string) => void): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;
+export declare function telegramReply(events: Stream.Stream<TurnEvent, PortFailure>, api: string, botToken: string, target: Target, formatError: (failed: TelegramFailure) => string | undefined, previewId?: number, onAnswered?: (answer: string) => void): Effect.Effect<void, PortFailure, import("effect/Scope").Scope>;

package/dist/channels/telegram/register-webhook.d.ts

@@ -8,6 +8,7 @@ import { type RegistrationOutcome } from "../registration.ts";
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
 export declare function registerTelegramWebhook(baseUrl: string, opts?: {
+    env?: NodeJS.ProcessEnv;
     attempts?: number;
     retryMs?: number;
 }): Promise<RegistrationOutcome>;

package/dist/channels/telegram/register-webhook.js

@@ -18,8 +18,9 @@ function isTransientRegistrationError(error) {
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
 export async function registerTelegramWebhook(baseUrl, opts = {}) {
-    const botToken = process.env.TELEGRAM_BOT_TOKEN;
-    const secret = process.env.TELEGRAM_SECRET_TOKEN;
+    const env = opts.env ?? process.env;
+    const botToken = env.TELEGRAM_BOT_TOKEN;
+    const secret = env.TELEGRAM_SECRET_TOKEN;
     const webhookUrl = `${baseUrl}/telegram`;
     if (!botToken || !secret) {
         log.info(`[fastagent] telegram: set TELEGRAM_BOT_TOKEN + TELEGRAM_SECRET_TOKEN in .env, then re-run to auto-register. Webhook URL: ${webhookUrl}`);

package/dist/channels/telegram/scaffold/channel.ts

@@ -1,36 +1,35 @@
+import { needs } from "@fastagent-sh/fastagent";
 import { telegramChannel } from "@fastagent-sh/fastagent/telegram";
-import { defineChannel } from "@fastagent-sh/fastagent";
 
 // A channel = a third-party ADAPTER (telegramChannel: verify + run + reply) configured with YOUR policy.
-// fastagent discovers this file under channels/, mounts POST /telegram, and pipes the agent + state
-// home to the adapter — this file holds only policy. Setup:
+// fastagent registers this file from src/channels/, mounts POST /telegram, and hands the adapter the
+// agent, its sessions and a directory of its own; this file holds only policy. Setup:
 //   1. @BotFather → /newbot → put the bot token in TELEGRAM_BOT_TOKEN
 //   2. pick a random TELEGRAM_SECRET_TOKEN (verifies that inbound updates really come from Telegram)
 //   3. register the webhook once, pointing Telegram at POST /telegram with that secret:
 //        curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
 //          -d url=https://your.host/telegram -d secret_token=$TELEGRAM_SECRET_TOKEN
-export default defineChannel({
-  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
-  // while one is unset — a bare process.env read gets neither guarantee.
-  secrets: ["TELEGRAM_BOT_TOKEN", "TELEGRAM_SECRET_TOKEN"],
-  channel: (secrets) =>
-    telegramChannel({
-      secretToken: secrets.TELEGRAM_SECRET_TOKEN, // verifies inbound updates really come from Telegram
-      botToken: secrets.TELEGRAM_BOT_TOKEN, // used to send the agent's reply back to the chat
-      // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
-      // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
-      // full details always go to the server log regardless.
-      onError: (failed) => `⚠️ ${failed.details}`,
-      // Your bot's @username. Optional — resolved via getMe when omitted — but set it if you pass a `route`
-      // below: the channel needs its own copy to recognise a `/stop` addressed to it.
-      // botUsername: "your_bot",
-      // The channel owns transport + format (HTML) + attachments (photo→vision, file→disk) + streaming.
-      // `route` (POLICY) is OPTIONAL — omitted, it uses defaultTelegramRoute: private chats always answer,
-      // groups only on a reply to THIS bot, an @mention of it, or a `/stop` addressed to it. Override to
-      // customise, reusing the export — but pass your bot's identity BOTH here and as `botUsername` above
-      // (the omitted default gets it from the channel; a bare `defaultTelegramRoute(u)` answers only
-      // private chats):
-      //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { session: `user:${u.message?.from?.id}` },
-      //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { text: `${telegramEnvelope(u.message!)}\n[extra]` },
-    }),
-});
+//
+// `needs` declares the env vars this channel reads: fastagent carries them to a deployed box and
+// refuses to serve while one is unset.
+export default needs(["TELEGRAM_BOT_TOKEN", "TELEGRAM_SECRET_TOKEN"], (secrets) =>
+  telegramChannel({
+    secretToken: secrets.TELEGRAM_SECRET_TOKEN, // verifies inbound updates really come from Telegram
+    botToken: secrets.TELEGRAM_BOT_TOKEN, // used to send the agent's reply back to the chat
+    // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
+    // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
+    // full details always go to the server log regardless.
+    onError: (failed) => `⚠️ ${failed.details}`,
+    // Your bot's @username. Optional — resolved via getMe when omitted — but set it if you pass a `route`
+    // below: the channel needs its own copy to recognise a `/stop` addressed to it.
+    // botUsername: "your_bot",
+    // The channel owns transport + format (HTML) + attachments (photo→vision, file→disk) + streaming.
+    // `route` (POLICY) is OPTIONAL — omitted, it uses defaultTelegramRoute: private chats always answer,
+    // groups only on a reply to THIS bot, an @mention of it, or a `/stop` addressed to it. Override to
+    // customise, reusing the export — but pass your bot's identity BOTH here and as `botUsername` above
+    // (the omitted default gets it from the channel; a bare `defaultTelegramRoute(u)` answers only
+    // private chats):
+    //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { conversation: `user:${u.message?.from?.id}` },
+    //   route: (u) => defaultTelegramRoute(u, { botUsername: "my_bot" }) && { text: `${telegramEnvelope(u.message!)}\n[extra]` },
+  }),
+);

package/dist/channels/telegram/scaffold/telegram-send.ts

@@ -1,112 +1,65 @@
-import { defineTool, z } from "@fastagent-sh/fastagent";
-import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { needs } from "@fastagent-sh/fastagent";
+import { telegramTransport } from "@fastagent-sh/fastagent/telegram";
 
-// Send a message or a local file back to a Telegram chat. In a CHAT turn the channel delivers the
-// reply itself — this tool is for files, and for turns NO channel is carrying: a scheduled turn
-// (routines/<name>.ts) or a self-scheduled wake-up, whose plain reply is not delivered anywhere.
-// The chatId comes from the [telegram: chat …] context line in a chat turn; a scheduled turn has no
-// such line, so the schedule's prompt must name the target chat id. tools/ is auto-discovered.
-
-// Telegram caps a message at 4096 chars. Splitting is the TOOL's job, not the model's (counting chars
-// is exactly what an LLM can't do — the channel encodes the same constraint in telegram-api.ts): chunk
-// at the last newline under the cap, hard-cut a single overlong line. Plain-text mirror of the channel
-// policy (this template cannot import core internals).
-const MAX_TEXT = 4096;
-function splitPlain(text: string): string[] {
-  const parts: string[] = [];
-  let rest = text;
-  while (rest.length > MAX_TEXT) {
-    let cut = rest.lastIndexOf("\n", MAX_TEXT);
-    if (cut <= 0) cut = MAX_TEXT;
-    parts.push(rest.slice(0, cut));
-    rest = rest.slice(cut).replace(/^\n/, "");
-  }
-  if (rest.length > 0 || parts.length === 0) parts.push(rest);
-  return parts;
-}
-
-// Embedded copy of the channel transport's discipline: an upload timeout so a wedged connection
-// can't hang the tool call (and the turn), named errors, and success gated on the body's own ok.
-// Deliberately NO 429 retry — a tool error goes back to the agent, which can decide to retry;
-// fail-fast beats a silently sleeping tool.
-async function callBotApi(token: string, method: string, form: FormData): Promise<void> {
-  let res: Response;
-  let raw: string;
-  try {
-    res = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
-      method: "POST",
-      body: form,
-      signal: AbortSignal.timeout(120_000),
-    });
-    raw = await res.text();
-  } catch (e) {
-    throw new Error(`telegram ${method}: ${String(e)}`, { cause: e });
-  }
-  let data: { ok?: boolean; description?: string };
-  try {
-    data = JSON.parse(raw) as { ok?: boolean; description?: string };
-  } catch {
-    data = {};
-  }
-  if (!res.ok || !data.ok) {
-    throw new Error(
-      `telegram ${method} failed: ${res.status} ${data.description ?? "Bot API response was not the expected JSON"}`,
-    );
-  }
-}
-
-export default defineTool({
-  description:
-    "Send to a Telegram chat: a text message (`text` — long text is split into multiple messages " +
-    "automatically), or a local file (`path` — a document, or a photo if it is an image). Exactly one " +
-    "of text/path. Use it for a turn NO channel is carrying — a scheduled or self-scheduled (wake) " +
-    "turn — or to reach a chat OTHER than the one you are answering. In a normal chat turn the channel " +
-    "already delivers your reply, so do NOT call this to answer (it would send it twice). chatId comes " +
-    "from the [telegram: chat …] context line in a chat turn; a scheduled/woken turn has no context " +
-    "line, so name the destination in your instruction.",
-  input: z.object({
-    chatId: z.union([z.string(), z.number()]).describe("target chat id"),
-    text: z.string().optional().describe("message text to send"),
-    path: z.string().optional().describe("absolute path of the local file to send"),
-    caption: z.string().optional().describe("file caption (file mode only)"),
-    asPhoto: z.boolean().optional().describe("send the file as a photo (inline) instead of a document"),
-    messageThreadId: z.number().optional().describe("thread to reply into (from the context line), if any"),
-  }),
-  // The bot token, declared: fastagent carries it to a deployed box and refuses to start while it is
-  // unset, so `execute` gets a value rather than checking for one.
-  secrets: ["TELEGRAM_BOT_TOKEN"],
-  async execute({ chatId, text, path, caption, asPhoto, messageThreadId }, ctx) {
-    const token = ctx.secrets.TELEGRAM_BOT_TOKEN;
-    if ((text === undefined) === (path === undefined)) {
-      throw new Error("pass exactly one of `text` (a message) or `path` (a file)");
-    }
-    const base = (): FormData => {
-      const form = new FormData();
-      form.set("chat_id", String(chatId));
-      if (messageThreadId !== undefined) form.set("message_thread_id", String(messageThreadId));
-      return form;
-    };
-    if (text !== undefined) {
-      // A file-only param alongside text would be silently dropped — same parameter-responsibility
-      // class as the XOR above, so it gets the same corrective error, not a silent ignore.
-      if (caption !== undefined || asPhoto !== undefined) {
-        throw new Error("`caption`/`asPhoto` are file-mode only — with `text`, put everything in the text");
+// Send a message or a local file to a Telegram chat. In a CHAT turn the channel delivers the
+// reply itself: this tool is for files, and for messages NO channel is carrying: a schedule's
+// (src/schedules/) or a self-scheduled wake-up's, whose plain reply is not delivered anywhere.
+// The chatId comes from the [telegram: chat …] context line in a chat turn; a scheduled message has
+// no such line, so the schedule's prompt must name the target chat id.
+//
+// Delivery rides the channel's own transport (telegramTransport): its token, Telegram's length cap,
+// its rate-limit handling. What it sends becomes part of that chat's discussion, so the chat's next
+// turn knows the agent said it (Telegram never echoes a bot its own messages). With no channel
+// mounted, it sends with TELEGRAM_BOT_TOKEN and says the message was not recorded.
+export default needs(["TELEGRAM_BOT_TOKEN"], ({ TELEGRAM_BOT_TOKEN }) =>
+  defineTool({
+    name: "telegram_send",
+    description:
+      "Send to a Telegram chat: a text message (`text`: long text is split into multiple messages " +
+      "automatically), or a local file (`path`: a document, or a photo if it is an image). Exactly one " +
+      "of text/path. Use it for a message NO channel is carrying (a scheduled or self-scheduled one) " +
+      "or to reach a chat OTHER than the one you are answering. In a normal chat turn the channel " +
+      "already delivers your reply, so do NOT call this to answer (it would send it twice). chatId comes " +
+      "from the [telegram: chat …] context line in a chat turn; a scheduled or woken message has no context " +
+      "line, so name the destination in your instruction. What you send is shown to you in that chat's " +
+      "next turn.",
+    parameters: Type.Object({
+      chatId: Type.Union([Type.String(), Type.Number()], { description: "target chat id" }),
+      text: Type.Optional(Type.String({ description: "message text to send" })),
+      path: Type.Optional(Type.String({ description: "absolute path of the local file to send" })),
+      caption: Type.Optional(Type.String({ description: "file caption (file mode only)" })),
+      asPhoto: Type.Optional(Type.Boolean({ description: "send the file as a photo (inline) instead of a document" })),
+      messageThreadId: Type.Optional(
+        Type.Number({ description: "thread to reply into (from the context line), if any" }),
+      ),
+    }),
+    execute: async ({ chatId, text, path, caption, asPhoto, messageThreadId }) => {
+      if ((text === undefined) === (path === undefined)) {
+        throw new Error("pass exactly one of `text` (a message) or `path` (a file)");
       }
-      const chunks = splitPlain(text);
-      for (const chunk of chunks) {
-        const form = base();
-        form.set("text", chunk);
-        await callBotApi(token, "sendMessage", form);
+      const telegram = telegramTransport(TELEGRAM_BOT_TOKEN);
+      const target = { chatId, threadId: messageThreadId };
+      let said: string;
+      if (text !== undefined) {
+        // A file-only param alongside text would be silently dropped: the same corrective error as above.
+        if (caption !== undefined || asPhoto !== undefined) {
+          throw new Error("`caption`/`asPhoto` are file-mode only: with `text`, put everything in the text");
+        }
+        const sent = await telegram.sendText(target, text);
+        const what =
+          sent.messageIds.length === 1
+            ? `sent message to chat ${chatId}`
+            : `sent ${sent.messageIds.length} messages to chat ${chatId} (split at Telegram's length cap)`;
+        said = sent.notRecorded ? `${what}; not recorded: ${sent.notRecorded}` : what;
+      } else {
+        const sent = await telegram.sendFile(target, { path: path as string, caption, asPhoto });
+        const what = `sent ${basename(path as string)} to chat ${chatId}`;
+        said = sent.notRecorded ? `${what}; not recorded: ${sent.notRecorded}` : what;
       }
-      return chunks.length === 1
-        ? `sent message to chat ${chatId}`
-        : `sent ${chunks.length} messages to chat ${chatId} (split at Telegram's length cap)`;
-    }
-    const form = base();
-    if (caption) form.set("caption", caption);
-    form.set(asPhoto ? "photo" : "document", new Blob([await readFile(path as string)]), basename(path as string));
-    await callBotApi(token, asPhoto ? "sendPhoto" : "sendDocument", form);
-    return `sent ${basename(path as string)} to chat ${chatId}`;
-  },
-});
+      return { output: [{ type: "text", text: said }] };
+    },
+  }),
+);

package/dist/channels/telegram/shared-api.d.ts

@@ -0,0 +1,34 @@
+import { type BufferEntry } from "./context-buffer.ts";
+/** Where a proactive message goes: a chat, optionally a forum topic. */
+export interface TelegramSendTarget {
+    chatId: number | string;
+    threadId?: number;
+}
+/** What a send did. */
+export interface TelegramSent {
+    /** One per message, in order (long text is split at Telegram's length cap). */
+    messageIds: number[];
+    /** Why the chat's next turn will NOT see this message, when it will not; undefined when it was recorded. */
+    notRecorded?: string;
+}
+export interface TelegramTransport {
+    /** Send plain text, split at Telegram's length cap. */
+    sendText(target: TelegramSendTarget, text: string): Promise<TelegramSent>;
+    /** Send a local file as a document, or inline as a photo. */
+    sendFile(target: TelegramSendTarget, file: {
+        path: string;
+        caption?: string;
+        asPhoto?: boolean;
+    }): Promise<TelegramSent>;
+}
+interface Mounted {
+    apiBaseUrl: string;
+    botToken: string;
+    /** The mounted channel's buffer write; absent when no channel is mounted in this process. */
+    record?: (placeKey: string, entry: BufferEntry) => void;
+}
+/** The channel's transport is the authoritative one for its bot; a re-mount replaces it. */
+export declare function registerTelegramTransport(mounted: Required<Mounted>): void;
+/** The transport of the bot `botToken` signs in as: its mounted channel's, or the token's own when none is mounted. */
+export declare function telegramTransport(botToken: string): TelegramTransport;
+export {};

package/dist/channels/telegram/shared-api.js

@@ -0,0 +1,79 @@
+/**
+ * The ONE Telegram transport per bot a process holds: the mounted channel's, shared with the scaffolded send tool,
+ * found by the bot token both hold, and the reason it is shared. A message the agent sends itself (a schedule's digest, a post into another chat)
+ * never comes back as an update, so it is recorded into the target place's discussion here, where the channel's
+ * context buffer lives, and the chat's next turn knows it was said.
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { log } from "../../log.js";
+import { ownPostEntry } from "./context-buffer.js";
+import { telegramPlaceKey } from "./parse.js";
+import { callApi, chunkText } from "./telegram-api.js";
+const byToken = new Map();
+/** The channel's transport is the authoritative one for its bot; a re-mount replaces it. */
+export function registerTelegramTransport(mounted) {
+    byToken.set(mounted.botToken, mounted);
+}
+const NOT_MOUNTED = "no telegram channel is mounted in this process, so the chat's next turn will not see it";
+/**
+ * The place a sent message landed in, keyed by the same fields an update is keyed by (`chat.id`,
+ * `message_thread_id`): the platform's echo names the chat by number where the target named it `@channel`, and
+ * omits the thread id exactly where an update in that place would. The target stands in only for a reply that names
+ * no chat.
+ */
+function landedPlace(sent, target) {
+    return sent.chat?.id !== undefined
+        ? telegramPlaceKey(sent.chat.id, sent.message_thread_id)
+        : telegramPlaceKey(target.chatId, target.threadId);
+}
+/** The transport of the bot `botToken` signs in as: its mounted channel's, or the token's own when none is mounted. */
+export function telegramTransport(botToken) {
+    const { apiBaseUrl, record } = byToken.get(botToken) ?? { apiBaseUrl: "https://api.telegram.org" };
+    /** Record what was delivered. It is already in the chat, so a failure here is reported, never thrown: a thrown send
+     *  would read as "not sent" and invite a duplicate. */
+    const remember = (placeKey, entry) => {
+        if (!record)
+            return NOT_MOUNTED;
+        try {
+            record(placeKey, entry);
+            return undefined;
+        }
+        catch (error) {
+            log.warn(`[telegram] a sent message was not recorded into place ${placeKey}: ${String(error)}`);
+            return `recording it failed: ${String(error)}`;
+        }
+    };
+    const params = (target) => ({
+        chat_id: target.chatId,
+        ...(target.threadId !== undefined ? { message_thread_id: target.threadId } : {}),
+    });
+    return {
+        async sendText(target, text) {
+            const messageIds = [];
+            let place = telegramPlaceKey(target.chatId, target.threadId);
+            for (const chunk of chunkText(text, { html: false })) {
+                const sent = await callApi(apiBaseUrl, botToken, "sendMessage", { ...params(target), text: chunk });
+                if (sent.message_id !== undefined)
+                    messageIds.push(sent.message_id);
+                place = landedPlace(sent, target);
+            }
+            return { messageIds, notRecorded: remember(place, ownPostEntry(text, messageIds[0])) };
+        },
+        async sendFile(target, file) {
+            const form = new FormData();
+            for (const [key, value] of Object.entries(params(target)))
+                form.set(key, String(value));
+            if (file.caption)
+                form.set("caption", file.caption);
+            const name = basename(file.path);
+            form.set(file.asPhoto ? "photo" : "document", new Blob([await readFile(file.path)]), name);
+            const sent = await callApi(apiBaseUrl, botToken, file.asPhoto ? "sendPhoto" : "sendDocument", form);
+            const label = file.asPhoto ? "[photo]" : `[document: ${name}]`;
+            return {
+                messageIds: sent.message_id !== undefined ? [sent.message_id] : [],
+                notRecorded: remember(landedPlace(sent, target), ownPostEntry(file.caption ? `${label} ${file.caption}` : label, sent.message_id)),
+            };
+        },
+    };
+}

package/dist/channels/telegram/telegram-api.d.ts

@@ -1,4 +1,4 @@
-import type { ImageRef } from "../../agent.ts";
+import type { ImageAttachment as ImageRef } from "../kit/invoke-turn-kit.ts";
 import type { CallOptions } from "../kit/transport.ts";
 /** Telegram's hard text limit per message. */
 export declare const TELEGRAM_MAX_TEXT = 4096;
@@ -15,13 +15,21 @@ export interface DownloadedFile {
     name: string;
     size: number;
 }
+/** The part of a sent Message this channel reads: where it landed. */
+interface SentMessage {
+    message_id?: number;
+    chat?: {
+        id?: number;
+    };
+    message_thread_id?: number;
+}
 /** The methods this channel speaks and their result shapes — a hand-written slice of the Bot API
  *  schema. Adding a method = adding a row here, not writing a function. (If this table ever needs to
  *  grow past roughly ten rows, or entity-based formatting, adopt gramIO instead of growing it.) */
 interface Api {
-    sendMessage: {
-        message_id?: number;
-    };
+    sendMessage: SentMessage;
+    sendDocument: SentMessage;
+    sendPhoto: SentMessage;
     editMessageText: unknown;
     deleteMessage: unknown;
     getMe: {
@@ -38,7 +46,9 @@ interface Api {
  * The pipeline: one Bot API call, carrying every transport invariant (see the module header). Returns
  * the method's `result` payload; throws {@link TelegramApiError} on any failure.
  */
-export declare function callApi<M extends keyof Api>(api: string, botToken: string, method: M, params: Record<string, unknown>, opts?: CallOptions): Promise<Api[M]>;
+export declare function callApi<M extends keyof Api>(api: string, botToken: string, method: M, 
+/** JSON params, or a multipart form for an upload (a file's bytes; its own, longer timeout). */
+params: Record<string, unknown> | FormData, opts?: CallOptions): Promise<Api[M]>;
 /**
  * Split text into ≤4096-char chunks (Telegram's limit), preferring a newline boundary. When `html`, it is
  * tag-aware: a tag that would SPAN a boundary is CLOSED at the chunk's end and REOPENED (attributes and

package/dist/channels/telegram/telegram-api.js

@@ -24,7 +24,7 @@ export const TELEGRAM_MAX_TEXT = 4096;
 const PARSE_ERROR = /can't parse|entit|unsupported|unclosed|tag/i;
 /** Per-attempt timeout for a JSON Bot API call — small JSON round-trips, so 30s is generous. */
 const API_TIMEOUT_MS = 30_000;
-/** Timeout for downloading file bytes (up to the 20 MB cap) — sized for a slow link, not a JSON call. */
+/** Timeout for moving file bytes, down or up (up to the 20 MB cap) — sized for a slow link, not a JSON call. */
 const DOWNLOAD_TIMEOUT_MS = 120_000;
 /** Longest flood wait (seconds) honoured PER ATTEMPT before failing visibly instead. Telegram's
  *  `retry_after` can reach minutes–hours on a flood ban; sleeping that long would silently park the
@@ -33,7 +33,7 @@ const FLOOD_WAIT_MAX_S = 30;
 /** How many 429s one call absorbs before giving up. */
 const RETRIES = 3;
 /** Download sanity cap (Telegram's own getFile limit); a larger file/image is rejected visibly. The
- *  engine resizes images to the model's needs, so this is a transport guard, not the model size limit. */
+ *  harness resizes images to the model's needs, so this is a transport guard, not the model size limit. */
 const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
 /** A named Bot API failure. `status` 0 = the transport itself failed (network error / timeout) before
  *  any HTTP status existed; otherwise the HTTP status with Telegram's own description (or a note that
@@ -63,17 +63,21 @@ const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * The pipeline: one Bot API call, carrying every transport invariant (see the module header). Returns
  * the method's `result` payload; throws {@link TelegramApiError} on any failure.
  */
-export async function callApi(api, botToken, method, params, opts = {}) {
+export async function callApi(api, botToken, method, 
+/** JSON params, or a multipart form for an upload (a file's bytes; its own, longer timeout). */
+params, opts = {}) {
     const retries = opts.retries ?? RETRIES;
+    const upload = params instanceof FormData;
     for (let attempt = 0;; attempt++) {
         let res;
         let raw;
         try {
             res = await fetch(`${api}/bot${botToken}/${method}`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify(params),
-                signal: AbortSignal.timeout(API_TIMEOUT_MS),
+                ...(upload
+                    ? { body: params }
+                    : { headers: { "content-type": "application/json" }, body: JSON.stringify(params) }),
+                signal: AbortSignal.timeout(upload ? DOWNLOAD_TIMEOUT_MS : API_TIMEOUT_MS),
             });
             raw = await res.text(); // the body read shares the timeout — a mid-body stall is a transport failure too
         }