@fastagent-sh/fastagent 0.21.1 → 0.22.1

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

@@ -1,29 +1,11 @@
 /**
- * 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.
- *
- * READINESS IS setWebhook'S OWN VERDICT, not a local probe. Telegram VERIFIES the URL during the call,
- * from Telegram's network — which is the only network that has to reach it. This used to poll
- * `<baseUrl>/health` from here first, and that probe answered a different question badly: a freshly
- * minted hostname (a quick tunnel, a fresh deploy) is routinely unreachable from the machine running
- * the CLI for a minute or more — behind a proxy, or while its own resolver still says ENOTFOUND — long
- * after Telegram can reach it (#421). So the retry loop below IS the wait: Telegram's reachability
- * verdicts ("Failed to resolve host", "Wrong response from the webhook") are retried, and only a
- * configuration error the operator must fix is reported once.
+ * Telegram webhook registration — the TELEGRAM-domain step both `--tunnel` (dev, tunnel.ts) and `deploy … --run` (the
+ * host runners' post-deploy step) invoke.
  */
 import { log } from "../../log.js";
 import { retryWhile } from "../registration.js";
 import { callApi } from "./telegram-api.js";
-/**
- * Whether a setWebhook failure is the URL still warming up rather than a configuration error. Two
- * families: transport failures reaching Telegram at all, and Telegram's own verdict after it fails to
- * reach the webhook — which carries its connection layer's words verbatim (`Bad Request: bad webhook:
- * Connection timed out` / `Connection refused` for a host whose DNS answers before anything listens,
- * `Wrong response from the webhook: 530` for a tunnel edge without its origin). This is the ONLY gate
- * between "spend the caller's retry budget" and "fail now", so it is wide on the reachability side.
- * A permanent "bad webhook" — an http:// URL, an unsupported port — matches nothing here and is reported.
- */
+/** Whether a setWebhook failure is the URL still warming up rather than a configuration error. */
 function isTransientRegistrationError(error) {
     return /resolve host|getaddrinfo|ENOTFOUND|fetch failed|ECONNRESET|timeout|timed out|connection refused|can't connect|connection to the host|wrong response from the webhook/i.test(error);
 }
@@ -54,8 +36,8 @@ export async function registerTelegramWebhook(baseUrl, opts = {}) {
         return "registered";
     }
     catch (e) {
-        // Both endings leave the webhook unregistered and the operator with work to do, so both are ERROR;
-        // they differ only in what to do about it.
+        // Both endings leave the webhook unregistered and the operator with work to do, so both are ERROR; they differ
+        // only in what to do about it.
         const error = String(e);
         log.error(isTransientRegistrationError(error)
             ? `[fastagent] telegram: Telegram could not reach ${webhookUrl} after retries (last error: ${error}). ` +

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

@@ -1,4 +1,5 @@
 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
@@ -8,22 +9,28 @@ import { telegramChannel } from "@fastagent-sh/fastagent/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}`,
-  // 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]` },
+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]` },
+    }),
 });

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

@@ -4,7 +4,7 @@ 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.
+// (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.
 
@@ -73,9 +73,11 @@ export default defineTool({
     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");
+  // 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)");
     }

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

@@ -1,4 +1,5 @@
 import type { ImageRef } from "../../agent.ts";
+import type { CallOptions } from "../kit/transport.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. */
@@ -37,7 +38,7 @@ 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>): Promise<Api[M]>;
+export declare function callApi<M extends keyof Api>(api: string, botToken: string, method: M, params: Record<string, unknown>, 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
@@ -59,7 +60,7 @@ export declare function chunkText(text: string, opts?: {
  */
 export declare function sendMessage(api: string, botToken: string, t: Target, body: string, opts?: {
     html?: boolean;
-}): Promise<number | undefined>;
+} & CallOptions): 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
@@ -68,7 +69,7 @@ export declare function sendMessage(api: string, botToken: string, t: Target, bo
  */
 export declare function editMessageText(api: string, botToken: string, t: Target, messageId: number, body: string, opts?: {
     html?: boolean;
-}): Promise<void>;
+} & CallOptions): 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/`).

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

@@ -7,7 +7,8 @@
  *     connection cannot hang a turn, its session queue, or webhook registration.
  *  2. Only a 429 is retried (bounded attempts, honouring `retry_after` up to FLOOD_WAIT_MAX_S per
  *     wait); a longer flood ban or exhausted retries fail visibly. No other failure class is retried:
- *     the request may have been processed, and a retried sendMessage would double-deliver.
+ *     the request may have been processed, and a retried sendMessage would double-deliver. A caller whose
+ *     write is DROPPABLE spends no budget on it — see kit/transport.ts.
  *  3. Success requires the body's own `ok:true` — an intermediary's HTTP 200 is not a sent message.
  *  4. Every failure is a {@link TelegramApiError} naming the method: self-description is a property of
  *     the error type, not per-call-site string assembly.
@@ -62,7 +63,8 @@ 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) {
+export async function callApi(api, botToken, method, params, opts = {}) {
+    const retries = opts.retries ?? RETRIES;
     for (let attempt = 0;; attempt++) {
         let res;
         let raw;
@@ -87,7 +89,7 @@ export async function callApi(api, botToken, method, params) {
         }
         if (res.ok && data.ok === true)
             return data.result;
-        if (res.status === 429 && attempt < RETRIES) {
+        if (res.status === 429 && attempt < retries) {
             const floodWait = data.parameters?.retry_after ?? attempt + 1; // no retry_after → short linear backoff
             if (floodWait <= FLOOD_WAIT_MAX_S) {
                 await wait((floodWait + 1) * 1000);
@@ -216,7 +218,7 @@ export async function sendMessage(api, botToken, t, body, opts = {}) {
         }
         let result;
         try {
-            result = await callApi(api, botToken, "sendMessage", mode ? { ...base, parse_mode: "HTML" } : base);
+            result = await callApi(api, botToken, "sendMessage", mode ? { ...base, parse_mode: "HTML" } : base, opts);
         }
         catch (e) {
             if (!(mode && e instanceof TelegramApiError && PARSE_ERROR.test(e.description)))
@@ -229,7 +231,7 @@ export async function sendMessage(api, botToken, t, body, opts = {}) {
                 continue;
             }
             // A later chunk failed after the first parsed cleanly (rare) — best-effort plain resend of this chunk.
-            result = await callApi(api, botToken, "sendMessage", base);
+            result = await callApi(api, botToken, "sendMessage", base, opts);
         }
         if (first)
             firstId = result.message_id;
@@ -251,7 +253,7 @@ export async function editMessageText(api, botToken, t, messageId, body, opts =
     };
     const notModified = (e) => e instanceof TelegramApiError && /message is not modified/i.test(e.description);
     try {
-        await callApi(api, botToken, "editMessageText", opts.html ? { ...base, parse_mode: "HTML" } : base);
+        await callApi(api, botToken, "editMessageText", opts.html ? { ...base, parse_mode: "HTML" } : base, opts);
     }
     catch (e) {
         if (notModified(e))
@@ -259,7 +261,7 @@ export async function editMessageText(api, botToken, t, messageId, body, opts =
         if (!(opts.html && e instanceof TelegramApiError && PARSE_ERROR.test(e.description)))
             throw e;
         try {
-            await callApi(api, botToken, "editMessageText", base); // plain fallback for rejected markup
+            await callApi(api, botToken, "editMessageText", base, opts); // plain fallback for rejected markup
         }
         catch (e2) {
             if (!notModified(e2))

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

@@ -8,28 +8,14 @@ export interface TelegramChannelOptions {
     secretToken: string;
     /** Bot token — used to send the agent's reply via the Bot API. */
     botToken: string;
-    /** Policy: whether/where to answer an update (return null to ignore). Defaults to {@link defaultTelegramRoute}. */
+    /** Policy: whether/where to answer an update (return null to ignore). */
     route?: (update: TelegramUpdate) => TelegramRoute | null;
-    /**
-     * Customer-facing failure text for the chat (the dev-facing full `details` always go to the operator
-     * log). Return a string to send it, or undefined/"" to stay silent. Default: a neutral message keyed
-     * on `retryable`. A developer's own bot can surface the raw details, e.g. `(f) => `⚠️ ${f.details}``.
-     */
+    /** Customer-facing failure text for the chat (the dev-facing full `details` always go to the operator log). */
     onError?: (failed: TelegramFailure) => string | undefined;
     /** Bot @username for group @mention summon by the default route (else resolved via getMe). */
     botUsername?: string;
-    /** Bot API base, for tests. Defaults to the public Telegram endpoint. */
+    /** Bot API base, for tests. */
     apiBaseUrl?: string;
 }
-/**
- * Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. The framework (or an
- * embedder) mounts it with the context — `telegramChannel(opts)` in `channels/telegram.ts` is the whole
- * glue; `agent` and the state root arrive via ctx, never through user code. Mounts `POST /telegram`
- * (the path `--tunnel` webhook registration expects). The adapter owns that route key; to serve the
- * SAME instance at a different path (e.g. behind a rewriting proxy), re-key the returned module:
- *   `(ctx) => ({ "POST /bot": telegramChannel(opts)(ctx)["POST /telegram"]! })`.
- * This re-routes ONE instance — it is not a way to run two telegram bots in one workspace: the state
- * home is derived from the channel kind (`<stateRoot>/channels/telegram`), so a second instance would
- * share the first's turn-store/context-buffer. One telegram instance per workspace (single-process).
- */
+/** Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. */
 export declare function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl, }: TelegramChannelOptions): ChannelModule;

package/dist/channels/telegram/telegram.js

@@ -1,57 +1,29 @@
 /**
- * Telegram bot channel: verify the webhook secret token → decide via `route(update)` → run the turn →
- * stream the agent's reply back to the chat, ACK 200. Reply model A: the channel holds the bot token
- * and posts the reply itself (chat UX), unlike the github channel's fire-and-forget. No SDK — inbound
- * is a JSON POST, outbound is a `fetch` to the Bot API. The developer writes only `route` (policy); the
- * channel owns transport + format + attachments.
- *
- * This file is the Telegram WIRING: ingress (secret/body cap/JSON) + the per-turn lifecycle + composition.
- * Every other concern lives in its own module, each owning its invariants:
- *   - parse.ts          pure message parsing: field extraction, prompt envelope, summon/route policy
- *   - invoke-turn.ts    run one turn: assemble inputs (resolve attachments) + stream `agent.invoke`
- *   - kit/turn-runner.ts the durable-turn lifecycle (accept → dequeue → execute → end) over the queue + store
- *   - turn-store.ts     durable turn intent (L1): pre-ACK persist, replay a crash-surviving turn
- *   - context-buffer.ts un-summoned group discussion, folded into the next answered turn
- *   - preview.ts        the live-preview pump ("💭 Thinking…" → edits → final answer) + terminal writes
- *   - telegram-api.ts   the single Bot API pipeline (timeouts, 429, ok-gating, HTML-aware split)
- *   - state.ts          atomic state files under the channel-state home
- *
- * Threaded Mode (topics in private chats, a @BotFather toggle) is auto-adapted: an update carrying
- * message_thread_id replies into that thread; without one the chat is linear. Same code, both modes.
- *
- * Authored against the public `@fastagent-sh/fastagent` surface only (the contract + the channel-authoring
- * kit: readBodyCapped / text), so it is exactly what a third-party `fastagent-channel-*` package would write.
+ * Telegram bot channel: verify the webhook secret token → decide via `route(update)` → run the turn → stream the
+ * agent's reply back to the chat, ACK 200.
  */
 import { isAbsolute, join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { secretEquals } from "../secret.js";
-import { invokeTurn } from "./invoke-turn.js";
+import { telegramTurnStream } from "./invoke-turn.js";
 import { collectAttachments, createContextBuffer } from "./context-buffer.js";
 import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, telegramStop, } from "./parse.js";
-import { defaultErrorMessage, streamReply } from "./preview.js";
+import { defaultErrorMessage, deliverTelegramAnswer, telegramReply } from "./preview.js";
+import { attachmentsDir } from "../kit/attachment-path.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop } from "../kit/stop-command.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
 import { createTurnRunner } from "../kit/turn-runner.js";
 import { discussionBlock } from "../kit/context-buffer.js";
+import { portJoin } from "../../effect-port.js";
 import { createTurnStore } from "./turn-store.js";
 // Re-export the public surface authored elsewhere, so `@fastagent-sh/fastagent/telegram` keeps one entry point.
 export { defaultTelegramRoute, telegramEnvelope, telegramStop };
 /** Update body cap — Telegram updates are small JSON; 1 MiB is generous and guards a public endpoint. */
 const MAX_UPDATE_BYTES = 1 << 20;
-/**
- * Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. The framework (or an
- * embedder) mounts it with the context — `telegramChannel(opts)` in `channels/telegram.ts` is the whole
- * glue; `agent` and the state root arrive via ctx, never through user code. Mounts `POST /telegram`
- * (the path `--tunnel` webhook registration expects). The adapter owns that route key; to serve the
- * SAME instance at a different path (e.g. behind a rewriting proxy), re-key the returned module:
- *   `(ctx) => ({ "POST /bot": telegramChannel(opts)(ctx)["POST /telegram"]! })`.
- * This re-routes ONE instance — it is not a way to run two telegram bots in one workspace: the state
- * home is derived from the channel kind (`<stateRoot>/channels/telegram`), so a second instance would
- * share the first's turn-store/context-buffer. One telegram instance per workspace (single-process).
- */
+/** Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. */
 export function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl = "https://api.telegram.org", }) {
     return ({ agent, stateRoot, control }) => {
         // Validate at activation so deploy may inspect the module shape before secrets are provisioned.
@@ -62,10 +34,9 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
         }
         const formatError = onError ?? defaultErrorMessage;
-        // One getMe at startup: the bot's @username (for the default route's group @mention summon and for
-        // recognising an addressed `/stop`, only when not supplied) and the group-privacy flag — privacy
-        // mode off is required to receive the un-summoned group messages that feed the context buffer, so
-        // warn if it is on.
+        // One getMe at startup: the bot's @username (for the default route's group @mention summon and for recognising an
+        // addressed `/stop`, only when not supplied) and the group-privacy flag — privacy mode off is required to receive
+        // the un-summoned group messages that feed the context buffer, so warn if it is on.
         let mentionName = botUsername;
         void callApi(apiBaseUrl, botToken, "getMe", {}).then((me) => {
             if (mentionName === undefined)
@@ -75,40 +46,31 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                     "context (un-summoned messages) won't be captured. Disable it via @BotFather → /setprivacy.");
             }
         }, 
-        // Name every capability the missing username costs, so "the bot ignores /stop@name" is
-        // diagnosable from this ONE line — the alternative, a warn per undecidable message, repeats a
-        // single startup fact on every update.
+        // Name every capability the missing username costs, so "the bot ignores /stop@name" is diagnosable from this
+        // ONE line.
         (e) => log.warn(`[telegram] getMe failed; @mention summon, addressed /stop, and the privacy check are skipped: ${String(e)}`));
-        // A bot token is "<bot_id>:<secret>" — the bot's own id is knowable synchronously, so reply-to-bot
-        // targeting is precise from the first update (no getMe race; getMe only resolves the @username).
-        // Every real token parses; one that doesn't (a mock/test token) degrades visibly: reply summon stays
-        // off (fail-closed in repliesToBot) until getMe supplies the username tier.
+        // A bot token is "<bot_id>:<secret>" — the bot's own id is knowable synchronously, so reply-to-bot targeting is
+        // precise from the first update (no getMe race; getMe only resolves the @username).
         const tokenId = Number(botToken.split(":")[0]);
         const botId = Number.isSafeInteger(tokenId) && tokenId > 0 ? tokenId : undefined;
         if (botId === undefined) {
             log.warn("[telegram] bot token has no parseable bot id — reply-to-bot summon disabled until getMe resolves");
         }
         const decide = route ?? ((update) => defaultTelegramRoute(update, { botUsername: mentionName, botId }));
-        // The channel-state convention: this channel's durable home is `<stateRoot>/channels/telegram`
-        // (engine state at the root, channel state under `channels/<kind>/`) — derived, not an option, so
-        // the operator's ONE state knob (FASTAGENT_STATE_DIR) can never be silently bypassed by glue.
-        // The ctx contract says stateRoot is absolute (loadChannels enforces it); re-assert for embedders
-        // that mount without the loader — a silent cwd re-anchor is the bug this contract exists to kill,
-        // and every derived path (incl. attachment paths) relies on DownloadedFile's absolute-path contract.
+        // The channel-state convention: this channel's durable home is `<stateRoot>/channels/telegram` (engine state at
+        // the root, channel state under `channels/<kind>/`).
         if (!isAbsolute(stateRoot)) {
             throw new Error(`telegramChannel requires an absolute ctx.stateRoot, got "${stateRoot}"`);
         }
         const stateHome = join(stateRoot, "channels", "telegram");
         ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
         const buffer = createContextBuffer(join(stateHome, "buffers.json"));
-        // Durable turn intent (L1): persist an accepted turn pre-ACK, remove it when the turn ends; a crash
-        // leaves it for replay on the next start. See turn-store.ts for the at-least-once semantics.
+        // Durable turn intent (L1): persist an accepted turn pre-ACK, remove it when the turn ends; a crash leaves it for
+        // replay on the next start.
         const store = createTurnStore(join(stateHome, "turns.json"));
         const targetOf = (r) => ({ chatId: r.chatId, threadId: r.threadId, replyTo: r.replyTo });
-        // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal, not
-        // just an operator log line. Take over the ⏳ "Queued" notice in place if the turn had one (else send
-        // fresh) — leaving it pinned at "Queued" while sending a separate failure would double-post. Best-
-        // effort, like the queue notices.
+        // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal, not just an
+        // operator log line.
         const notifyDropped = (r) => {
             const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
             const sent = r.previewId !== undefined
@@ -124,11 +86,8 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, previewId: undefined }),
             bufferKey: (rec) => rec.placeKey,
             where: (rec) => `chat=${rec.chatId}${rec.threadId !== undefined ? ` thread=${rec.threadId}` : ""}`,
-            // Queue feedback: when this session already has a turn running/queued, a silent wait reads as "the
-            // bot ignored me" once the current turn runs long — tell the asker NOW (reply-quoted, so it is
-            // clear whose ask is queued). Best-effort and post-ACK: a failed notice is a log line, never a
-            // failed update. The turn's live preview then edits this same message in place. The runner holds
-            // this same `rec` object, so mutating it here (awaited at dequeue) hands the turn its preview id.
+            // Queue feedback: when this session already has a turn running/queued, a silent wait reads as "the bot ignored
+            // me" once the current turn runs long.
             onQueuedBehind: (rec) => ({
                 done: sendMessage(apiBaseUrl, botToken, targetOf(rec), "⏳ Queued — I’ll start once the current task finishes.", {
                     html: false,
@@ -137,8 +96,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                         rec.previewId = id;
                 }, (e) => log.warn(`[telegram] queue notice failed (the turn still runs): ${String(e)}`)),
             }),
-            // Its ⏳ notice (if any) now falsely reads "Queued": delete it best-effort — the eventual replay
-            // sends a fresh preview, and leaving it would orphan a stale message above that.
+            // Its ⏳ notice (if any) now falsely reads "Queued": delete it best-effort.
             onDeferred: (rec) => {
                 if (rec.previewId !== undefined) {
                     void callApi(apiBaseUrl, botToken, "deleteMessage", {
@@ -148,13 +106,15 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 }
             },
             notifyDropped,
-            execute: (rec, discussion, onCompleted) => streamReply(invokeTurn(agent, rec.session, `${discussionBlock(discussion.text)}${rec.baseText}`, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: join(stateHome, "files") }, {
+            // `rec.previewId`: the ⏳ notice THIS process put up if the record waited behind another turn.
+            deliverAnswer: (rec, answer) => portJoin(() => deliverTelegramAnswer(apiBaseUrl, botToken, targetOf(rec), answer, rec.previewId)),
+            execute: (rec, discussion, onAnswered) => telegramReply(telegramTurnStream(agent, rec.session, `${discussionBlock(discussion.text)}${rec.baseText}`, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: attachmentsDir(stateHome) }, {
                 primary: { imageFileIds: rec.imageFileIds, fileIds: rec.fileIds },
                 buffered: collectAttachments(discussion.consumed, {
                     files: new Set(rec.fileIds),
                     images: new Set(rec.imageFileIds),
                 }),
-            }, onCompleted), apiBaseUrl, botToken, targetOf(rec), formatError, rec.previewId),
+            }), apiBaseUrl, botToken, targetOf(rec), formatError, rec.previewId, onAnswered),
         });
         runner.recover();
         const handler = async (req) => {
@@ -174,27 +134,23 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             catch {
                 return text("invalid json\n", 400);
             }
-            // Decide whether/where to answer, then run the turn. ACK 200 immediately (the turn may outlast the
-            // webhook timeout); lifecycle goes to stderr — after the 200 there is no response body, so those
-            // lines are the operator's only signal.
+            // Decide whether/where to answer, then run the turn.
             const m = pickMessage(update);
             if (!m)
                 return new Response(null, { status: 200 });
             const placeKey = m.message_thread_id ? `${m.chat.id}:${m.message_thread_id}` : `${m.chat.id}`;
             const r = decide(update);
             if (!r) {
-                // Not summoned: in a group, record the message so a later summon has the discussion (needs privacy
-                // off to be delivered here at all). Empty/service messages and non-group chats keep no buffer.
+                // Not summoned: in a group, record the message so a later summon has the discussion (needs privacy off to be
+                // delivered here at all).
                 const isGroup = m.chat.type === "group" || m.chat.type === "supergroup";
                 const content = messageText(m);
                 if (isGroup && content) {
-                    // OWN attachments only: each message is its own buffer entry, so a reply's referenced
-                    // attachment is already (or will be) the other entry's — recounting it here would duplicate
-                    // downloads and squeeze the attachment cap.
+                    // OWN attachments only: each message is its own buffer entry, so a reply's referenced attachment is already
+                    // (or will be) the other entry's.
                     const fileIds = ownFiles(m);
                     const imageIds = ownImages(m);
-                    // A captioned attachment renders as its caption — append the attachment marker so the fold
-                    // ALWAYS labels attachments (that label + sender is all the attribution a photo gets).
+                    // A captioned attachment renders as its caption.
                     const summary = attachmentSummary(m);
                     const bodyLine = summary && content !== summary ? `${content} ${summary}` : content;
                     buffer.push(placeKey, {
@@ -208,24 +164,14 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 }
                 return new Response(null, { status: 200 });
             }
-            const session = r.session ?? placeKey;
+            // Branded with the channel kind: session ids share one namespace across every channel of a deployment.
+            const session = r.session ?? `telegram:${placeKey}`;
             const chatId = r.chatId ?? m.chat.id;
-            // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no
-            // reply-quote. Only when the RESOLVED target is the message's own chat+thread: a route that
-            // redirects elsewhere must not carry a reply_parameters that resolves in the wrong place (fail, or
-            // quote a same-id message there). Compare VALUES, not whether the route touched the field — a route
-            // that explicitly returns the same chat/thread still quotes.
+            // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no reply-quote.
             const threadId = r.threadId ?? m.message_thread_id;
             const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
             const replyTo = m.chat.type !== "private" && sameTarget ? m.message_id : undefined;
-            // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
-            // run it stops. Awaited before the ACK: dispatch + one sendMessage is fast, and a delivery failure
-            // logs instead of failing the webhook. Read AFTER the route, on the route's own session: the route
-            // is both the gate (a route that ignores this chat must not have the bot abort or answer in it) and
-            // the session authority (a route that remaps `session` would otherwise have its stop abort a
-            // session nobody runs). The default route summons an ADDRESSED `/stop` in a group for this reason:
-            // the general slash-command refusal would leave it buffered as discussion while the run kept going.
-            // An unaddressed one is not a command at all (see telegramStop) and never reaches here.
+            // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the run it stops.
             if (telegramStop(update, { botUsername: mentionName, botId })) {
                 const feedback = await dispatchStop(control, session, "[telegram]");
                 await sendMessage(apiBaseUrl, botToken, { chatId, threadId, replyTo }, feedback, { html: false }).catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`));
@@ -250,9 +196,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             }
             return new Response(null, { status: 200 });
         };
-        // Test/observability seam: await the fire-and-forget turns this handler enqueues. Inert in production
-        // (nothing reads it; the runtime never drains — see turn-queue), it lets a test await a turn
-        // deterministically instead of polling for side effects to settle.
+        // Test/observability seam: await the fire-and-forget turns this handler enqueues.
         handler.turnsIdle = () => runner.idle();
         return { "POST /telegram": handler };
     };

package/dist/channels/telegram/turn-store.d.ts

@@ -1,18 +1,16 @@
 /**
- * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
- * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
- * (../kit/turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
- * turn execution ceiling, the fail-closed attempt bump).
+ * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a turn), its
+ * IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store (../kit/turn-store.ts — the
+ * semantics live there: pre-ACK persist, replay on the next start, the poison-turn execution ceiling, the fail-closed
+ * attempt bump).
  */
-import { type TurnStore } from "../kit/turn-store.ts";
-/** An accepted turn's persisted intent — the SOURCE for the fields a runner needs to re-execute it
- *  (telegram.ts's PendingTurn derives from this, so a new execution field added here propagates and
- *  cannot silently drop from the persisted record). Minus the live `previewId` (a restart's queue
- *  notice is gone; a replayed turn sends a fresh preview). `attempts` counts how many times this turn
- *  has STARTED executing without finishing (0 until its first run; bumped at each `startAttempt`). */
-export interface StoredTurn {
-    id: string;
-    session: string;
+import { type TurnRecordBase, type TurnStore } from "../kit/turn-store.ts";
+/**
+ * An accepted turn's persisted intent — the SOURCE for the fields a runner needs to re-execute it (telegram.ts's
+ * PendingTurn derives from this, so a new execution field added here propagates and cannot silently drop from the
+ * persisted record).
+ */
+export interface StoredTurn extends TurnRecordBase {
     placeKey: string;
     baseText: string;
     chatId: number | string;
@@ -20,6 +18,5 @@ export interface StoredTurn {
     replyTo?: number;
     imageFileIds: string[];
     fileIds: string[];
-    attempts: number;
 }
 export declare function createTurnStore(path: string): TurnStore<StoredTurn>;

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

@@ -1,12 +1,14 @@
 /**
- * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
- * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
- * (../kit/turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
- * turn execution ceiling, the fail-closed attempt bump).
+ * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a turn), its
+ * IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store (../kit/turn-store.ts — the
+ * semantics live there: pre-ACK persist, replay on the next start, the poison-turn execution ceiling, the fail-closed
+ * attempt bump).
  */
 import { createTurnStore as createGenericTurnStore } from "../kit/turn-store.js";
-/** State files are an IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file
- *  (warn + empty), not flow in as trusted data (mirrors context-buffer's isBufferEntry). */
+/**
+ * State files are an IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file (warn + empty), not
+ * flow in as trusted data (mirrors context-buffer's isBufferEntry).
+ */
 function isStoredTurn(t) {
     const r = t;
     const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");

package/dist/channels/wait-health.d.ts

@@ -1,6 +1,4 @@
-/**
- * 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.
- */
-export declare function waitForHealth(healthUrl: string, timeoutMs: number, intervalMs: number): Promise<boolean>;
+/** Poll `healthUrl` until it responds 200, or the timeout elapses. */
+export declare function waitForHealth(healthUrl: string, timeoutMs: number, intervalMs: number, 
+/** Optional liveness answer from whoever runs the server. */
+stillStarting?: () => Promise<boolean>): Promise<boolean>;