@fastagent-sh/fastagent 0.12.0

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

@@ -0,0 +1,73 @@
+/**
+ * Telegram webhook registration — the TELEGRAM-domain step both `--tunnel` (dev, tunnel.ts) and
+ * `deploy … --run` (the host runners' post-deploy step) invoke. What "registering telegram" means lives
+ * here, beside the channel it serves; it reads the same .env tokens the channel uses.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { log } from "../../log.js";
+import { callApi } from "./telegram-api.js";
+/**
+ * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Waits for the server to be
+ * REACHABLE first — polling `<baseUrl>/health` — because Telegram VERIFIES the URL when you set it, and a
+ * fresh deploy's container (healthcheck + routing) or a fresh tunnel's DNS is not routable for some
+ * seconds after the deploy/tunnel command returns. Tracking real readiness (not a fixed timer) is what
+ * fixes the race that made the first real deploy need a manual `setWebhook`. Missing tokens print the
+ * manual instruction instead of failing. `opts` (timeouts) exist for tests; production uses the defaults.
+ */
+export async function registerTelegramWebhook(baseUrl, opts = {}) {
+    const botToken = process.env.TELEGRAM_BOT_TOKEN;
+    const secret = process.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}`);
+        return;
+    }
+    // Align registration with the server actually serving. Don't setWebhook against a URL Telegram can't
+    // yet reach — it would fail, and a fixed retry window guesses the readiness delay (the deploy race).
+    log.info(`[fastagent] telegram: waiting for ${baseUrl} to be reachable before registering the webhook…`);
+    const ready = await waitForHealth(`${baseUrl}/health`, opts.readyTimeoutMs ?? 120_000, opts.readyIntervalMs ?? 3_000);
+    if (!ready) {
+        log.warn(`[fastagent] telegram: ${baseUrl}/health did not come up in time — the app may still be starting. ` +
+            `Register the webhook manually once it's up: curl "https://api.telegram.org/bot<token>/setWebhook" -d url=${webhookUrl} -d secret_token=<secret>`);
+        return;
+    }
+    // Reachable → register. A short retry backstops Telegram's resolver lagging /health by a moment; only
+    // network-transient errors retry (a permanent "bad webhook" config error is reported, not retried).
+    for (let attempt = 0; attempt < 3; attempt++) {
+        if (attempt > 0)
+            await sleep(opts.retryMs ?? 2000);
+        try {
+            await callApi("https://api.telegram.org", botToken, "setWebhook", { url: webhookUrl, secret_token: secret });
+            log.info(`[fastagent] telegram: webhook registered → ${webhookUrl}`);
+            return;
+        }
+        catch (e) {
+            const error = String(e);
+            if (!/resolve host|getaddrinfo|ENOTFOUND|fetch failed|ECONNRESET|timeout/i.test(error)) {
+                log.error(`[fastagent] telegram: setWebhook failed (${error}). Register manually with url=${webhookUrl}`);
+                return;
+            }
+        }
+    }
+    log.warn(`[fastagent] telegram: setWebhook still failing after retries. Register manually with url=${webhookUrl}`);
+}
+/**
+ * Poll `healthUrl` until it responds 200, or the timeout elapses. Any error (not routable yet, DNS not
+ * settled, connection refused) is a "keep waiting", not a failure — that IS the readiness signal. Each
+ * probe has its own short timeout so one slow attempt can't eat the whole budget.
+ */
+async function waitForHealth(healthUrl, timeoutMs, intervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            if ((await fetch(healthUrl, { signal: AbortSignal.timeout(5000) })).ok)
+                return true;
+        }
+        catch {
+            /* not routable yet — keep polling until the deadline */
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(intervalMs);
+    }
+}

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

@@ -0,0 +1,25 @@
+import { telegramChannel } from "@fastagent-sh/fastagent/telegram";
+
+// 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:
+//   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 telegramChannel({
+  secretToken: process.env.TELEGRAM_SECRET_TOKEN ?? "", // missing → fails at startup (would accept forged updates)
+  botToken: process.env.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}`,
+  // 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 or an @mention of it. Override to customise, reusing the
+  // export — but pass your bot's identity: group summon needs it (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]` },
+});

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

@@ -0,0 +1,107 @@
+import { defineTool, z } from "@fastagent-sh/fastagent";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+// 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
+// (schedules/<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;
+}
+
+// Standalone 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. In a chat turn take chatId from the [telegram: chat …] context line; in a " +
+    "scheduled/woken turn (no context line) the chat id must come from 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"),
+  }),
+  async execute({ chatId, text, path, caption, asPhoto, messageThreadId }) {
+    const token = process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) throw new Error("TELEGRAM_BOT_TOKEN is not set");
+    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");
+      }
+      const chunks = splitPlain(text);
+      for (const chunk of chunks) {
+        const form = base();
+        form.set("text", chunk);
+        await callBotApi(token, "sendMessage", form);
+      }
+      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}`;
+  },
+});

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

@@ -0,0 +1,9 @@
+/** Create the state home and self-ignore it (`.gitignore="*"`): its contents (buffers, downloaded
+ *  files) can carry chat content and must never be committable. The workspace opener already protects
+ *  an in-tree state root; this local guard also covers direct embedders. `wx` never clobbers an
+ *  operator's own file. */
+export declare function ensureStateHome(dir: string): void;
+/** Returns `unknown` on purpose — no generic pretending otherwise: the file is an IO boundary, and the
+ *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
+export declare function loadStateFile(path: string): unknown;
+export declare function saveStateFile(path: string, value: unknown): void;

package/dist/channels/telegram/state.js

@@ -0,0 +1,58 @@
+/**
+ * Durable channel state for a SINGLE-PROCESS deployment (the supported production shape — no
+ * cross-instance locking; two processes must not share a state dir). Small JSON files, written
+ * atomically (tmp + rename), so a crash leaves the previous version on disk, never a torn file.
+ * Writes are synchronous: the files are KB-sized and a write that completes BEFORE the webhook 200
+ * is what makes the state actually durable (an ACKed update is never redelivered by Telegram).
+ *
+ * Failure split: a CORRUPT file (bad JSON) degrades visibly — log.warn + start empty — because channel
+ * state is recoverable context, not worth refusing to boot over. An unreadable file (permissions, IO)
+ * is an ENVIRONMENT error the operator must fix: it throws, and construction fails loudly — booting
+ * with silently-empty state would hide real data behind a config mistake.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { log } from "../../log.js";
+/** Create the state home and self-ignore it (`.gitignore="*"`): its contents (buffers, downloaded
+ *  files) can carry chat content and must never be committable. The workspace opener already protects
+ *  an in-tree state root; this local guard also covers direct embedders. `wx` never clobbers an
+ *  operator's own file. */
+export function ensureStateHome(dir) {
+    mkdirSync(dir, { recursive: true });
+    try {
+        writeFileSync(join(dir, ".gitignore"), "*\n", { flag: "wx" });
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+    }
+}
+/** Returns `unknown` on purpose — no generic pretending otherwise: the file is an IO boundary, and the
+ *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
+export function loadStateFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined; // first run — normal
+        // Permissions/IO: an environment error — fail the boot loudly rather than run on invisible state.
+        throw new Error(`telegram state file ${path} is unreadable — fix permissions/disk and restart: ${String(e)}`, {
+            cause: e,
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        log.warn(`[telegram] corrupt state file ${path} — starting empty: ${String(e)}`);
+        return undefined;
+    }
+}
+export function saveStateFile(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value));
+    renameSync(tmp, path);
+}

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

@@ -0,0 +1,77 @@
+import type { ImageRef } from "../../agent.ts";
+/** Telegram's hard text limit per message. */
+export declare const TELEGRAM_MAX_TEXT = 4096;
+/** Where a reply goes: a chat, optionally a thread (Threaded Mode), optionally replying to a message. */
+export interface Target {
+    chatId: number | string;
+    threadId?: number;
+    /** Message to reply to (the summoning message). Set in groups so the answer threads under the asker. */
+    replyTo?: number;
+}
+/** A downloaded inbound file: an absolute local path the agent's tools (read/bash) can open. */
+export interface DownloadedFile {
+    path: string;
+    name: string;
+    size: 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;
+    };
+    editMessageText: unknown;
+    deleteMessage: unknown;
+    getMe: {
+        username?: string;
+        can_read_all_group_messages?: boolean;
+    };
+    getFile: {
+        file_path?: string;
+        file_size?: number;
+    };
+    setWebhook: unknown;
+}
+/**
+ * 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>): 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
+ * all) at the next chunk's start, so every chunk is self-contained valid HTML — a long `<pre>` code block
+ * stays formatted instead of the first chunk degrading to plain text. It also never cuts THROUGH a tag
+ * token (backs the cut up before a `<` it would land inside). For plain text a `<` is literal content, so
+ * both behaviours are skipped.
+ */
+export declare function chunkText(text: string, opts?: {
+    html?: boolean;
+}): string[];
+/**
+ * Send a message: split to Telegram's 4096-char limit, each chunk as HTML by default (`html:false` for a
+ * plain live-preview). If Telegram rejects the markup on the FIRST chunk (a model formatting slip), the
+ * whole body is re-chunked and resent as PLAIN — re-chunked, not the same bytes, so the tag-balancer's
+ * injected boundary tags don't leak as literal text. (A later chunk failing after the first parsed
+ * cleanly is rare; it falls back per-chunk, best-effort.) Returns the FIRST chunk's message_id (so the
+ * caller can edit it as a live preview). `message_thread_id` is dropped from the JSON when undefined.
+ */
+export declare function sendMessage(api: string, botToken: string, t: Target, body: string, opts?: {
+    html?: boolean;
+}): Promise<number | undefined>;
+/**
+ * Edit a message in place — the live-preview mechanism (one message, repeatedly updated). Plain by
+ * default (a partial preview may contain unbalanced HTML); `html:true` for the final answer, falling
+ * back to plain if Telegram rejects the markup. "message is not modified" is NOT an error: the pump may
+ * re-render an unchanged view. The message is identified by (chat_id, message_id) — no thread needed.
+ */
+export declare function editMessageText(api: string, botToken: string, t: Target, messageId: number, body: string, opts?: {
+    html?: boolean;
+}): Promise<void>;
+/** Fetch the message's images. Throws if any cannot be loaded — the caller surfaces it (no silent drop). */
+export declare function resolveImages(api: string, botToken: string, fileIds: string[] | undefined): Promise<ImageRef[] | undefined>;
+/** Download the message's files into `filesDir` (the channel passes its state home's `files/`).
+ *  Throws if any cannot be loaded — the caller surfaces it (no silent drop). */
+export declare function resolveFiles(api: string, botToken: string, fileIds: string[] | undefined, chatId: number | string, filesDir: string): Promise<DownloadedFile[] | undefined>;
+export {};