@fastagent-sh/fastagent 0.12.0

package/dist/channels/telegram/telegram.js

@@ -0,0 +1,352 @@
+/**
+ * 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`
+ *   - turn-queue.ts     in-memory per-session serial execution (FIFO; one turn at a time per session)
+ *   - 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.
+ */
+import { timingSafeEqual } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { log } from "../../log.js";
+import { readBodyCapped } from "../body.js";
+import { text } from "../respond.js";
+import { invokeTurn } from "./invoke-turn.js";
+import { collectAttachments, createContextBuffer } from "./context-buffer.js";
+import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
+import { defaultErrorMessage, streamReply } from "./preview.js";
+import { ensureStateHome } from "./state.js";
+import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
+import { createTurnQueue } from "./turn-queue.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 };
+/** Execution ceiling: a turn that has STARTED running this many times without finishing is dropped
+ *  rather than run again (a poison turn must not loop forever under a restart policy). Counted per turn
+ *  at dequeue, so a never-run turn queued behind a poison one keeps its full budget.
+ *
+ *  Known limitation: `startAttempt` cannot tell a self-inflicted process crash from an external SIGTERM
+ *  (no graceful drain), so a legitimately LONG turn interrupted by this many successive deploys is
+ *  dropped ("please ask again") as if it were poison. Accepted: catching SIGTERM to spare it would
+ *  reintroduce the drain the design refuses, and a turn outliving this many deploy cycles is an outlier
+ *  — raise this constant if such turns are expected. */
+const MAX_TURN_ATTEMPTS = 3;
+/** Update body cap — Telegram updates are small JSON; 1 MiB is generous and guards a public endpoint. */
+const MAX_UPDATE_BYTES = 1 << 20;
+/** Constant-time compare so the secret-token check leaks no timing signal. */
+function tokenMatches(header, secret) {
+    const a = Buffer.from(header);
+    const b = Buffer.from(secret);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * 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).
+ */
+export function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl = "https://api.telegram.org", }) {
+    // Both are mandatory: an unset secret_token would accept forged updates (the endpoint is public);
+    // the bot token is required to send the reply. Fail at construction (startup), not silently.
+    if (!secretToken) {
+        throw new Error("telegramChannel requires a non-empty secretToken (the webhook secret_token; an unset one accepts forged updates)");
+    }
+    if (!botToken) {
+        throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
+    }
+    return ({ agent, stateRoot }) => {
+        const formatError = onError ?? defaultErrorMessage;
+        // One getMe at startup: the bot's @username (for the default route's group @mention summon, 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)
+                mentionName = me.username;
+            if (me.can_read_all_group_messages === false) {
+                log.warn("[telegram] privacy mode is on: the bot only sees @mentions / replies / commands, so group " +
+                    "context (un-summoned messages) won't be captured. Disable it via @BotFather → /setprivacy.");
+            }
+        }, (e) => log.warn(`[telegram] getMe failed; @mention summon + privacy check 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.
+        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.
+        if (!isAbsolute(stateRoot)) {
+            throw new Error(`telegramChannel requires an absolute ctx.stateRoot, got "${stateRoot}"`);
+        }
+        const stateHome = join(stateRoot, "channels", "telegram");
+        ensureStateHome(stateHome); // create + self-ignore — buffers/files may carry chat content
+        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.
+        const store = createTurnStore(join(stateHome, "turns.json"));
+        const toStored = (r) => {
+            const { previewId: _live, ...intent } = r; // drop the live-only field; TS enforces the rest is complete
+            return { ...intent, attempts: 0 };
+        };
+        // In-memory: the in-flight "⏳ queued" notice per turn, awaited at dequeue so the turn reliably takes
+        // the notice message over (rec.previewId) instead of racing it and orphaning a late-arriving notice.
+        const notices = new Map();
+        const queue = createTurnQueue({
+            label: "[telegram]",
+            // 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.
+            onQueuedBehind: (rec) => {
+                const target = {
+                    chatId: rec.chatId,
+                    threadId: rec.threadId,
+                    replyTo: rec.replyTo,
+                };
+                notices.set(rec.id, sendMessage(apiBaseUrl, botToken, target, "⏳ Queued — I’ll start once the current task finishes.", {
+                    html: false,
+                }).then(
+                // The runner holds this same `rec` object, so mutating it here (gated by the notices await at
+                // dequeue below) is what hands the turn its preview message id.
+                (id) => {
+                    if (id !== undefined)
+                        rec.previewId = id;
+                }, (e) => log.warn(`[telegram] queue notice failed (the turn still runs): ${String(e)}`)));
+            },
+            run: async (rec) => {
+                // Runs at DEQUEUE time (serialized), so the lifecycle log and engine turn reflect the actual
+                // execution order rather than arrival.
+                // Settle the queue notice (if any) so rec.previewId is final. NOT free: a slow (not failed)
+                // notice delays this turn's start by up to the API timeout — accepted, because racing it would
+                // orphan the ⏳ message and double-post a placeholder; in the common path the notice resolved
+                // while the previous turn was still running, so this await is instant. BEFORE the ceiling check
+                // so a dropped turn's notice is settled/cleared too (rec.previewId lets notifyDropped take it over).
+                await notices.get(rec.id);
+                notices.delete(rec.id);
+                // Count this execution against the durable record (poison-turn ceiling) before running it again.
+                const decision = store.startAttempt(rec.id, MAX_TURN_ATTEMPTS);
+                if (decision === "exceeded") {
+                    // Started MAX_TURN_ATTEMPTS times without finishing — tell the asker (reusing its ⏳ notice if
+                    // any), drop it.
+                    notifyDropped(rec);
+                    return;
+                }
+                if (decision === "defer") {
+                    // Couldn't record the attempt (disk failure): skip this cycle. A restart replays it, so no notify
+                    // (telling the asker to re-ask would double-answer once the deferred turn runs). Two accepted
+                    // edges of this rare disk-failure corner: (1) the session chain proceeds to the next queued turn,
+                    // so a deferred turn can replay AFTER its successors — a per-session FIFO reorder; (2) its ⏳ notice
+                    // (if it was queued behind another turn) now falsely reads "Queued", so delete it best-effort — the
+                    // eventual replay sends a fresh preview, and leaving it would orphan a stale message above that.
+                    if (rec.previewId !== undefined) {
+                        void callApi(apiBaseUrl, botToken, "deleteMessage", {
+                            chat_id: rec.chatId,
+                            message_id: rec.previewId,
+                        }).catch(() => { });
+                    }
+                    return;
+                }
+                const startedAt = Date.now();
+                const where = `chat=${rec.chatId}${rec.threadId !== undefined ? ` thread=${rec.threadId}` : ""}`;
+                log.info(`[telegram] turn start: turn=${rec.id} session=${rec.session} ${where}`);
+                // Fold the un-summoned discussion since the last answered turn into the prompt; it is cleared
+                // only when the turn COMPLETES (then it lives in the session).
+                const { text: recent, consumed } = buffer.peek(rec.placeKey);
+                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
+                const buffered = collectAttachments(consumed, {
+                    files: new Set(rec.fileIds),
+                    images: new Set(rec.imageFileIds),
+                });
+                const target = {
+                    chatId: rec.chatId,
+                    threadId: rec.threadId,
+                    replyTo: rec.replyTo,
+                };
+                try {
+                    await streamReply(invokeTurn(agent, rec.session, prompt, {
+                        api: apiBaseUrl,
+                        botToken,
+                        chatId: rec.chatId,
+                        filesDir: join(stateHome, "files"),
+                    }, {
+                        primary: {
+                            imageFileIds: rec.imageFileIds,
+                            fileIds: rec.fileIds,
+                        },
+                        buffered,
+                    }, () => {
+                        // On completed, ORDER the two durable clears so a crash between them can't replay a
+                        // context-stripped turn: drop the intent FIRST (a crash after this won't replay it), THEN
+                        // commit the context buffer (a crash before this just re-folds the same context into the
+                        // next summon — harmless and additive). The reverse order would leave intent+no-context.
+                        store.remove(rec.id);
+                        buffer.commit(rec.placeKey, consumed);
+                    }), apiBaseUrl, botToken, target, formatError, rec.previewId);
+                    log.info(`[telegram] turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
+                }
+                catch (error) {
+                    log.error(`[telegram] turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
+                }
+                finally {
+                    // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
+                    // never reach the completed hook above, which is where a completed turn removes its intent in
+                    // order. Idempotent — a second remove after the completed hook is a no-op. Only an INTERRUPTED run
+                    // (this finally never runs — a crash or a SIGTERM deploy, no graceful drain) leaves the record for
+                    // replay; a transport throw is dropped, not retried (safe retry needs an L2 delivery key).
+                    store.remove(rec.id);
+                }
+            },
+        });
+        // Accept a turn: persist its intent before the ACK (durable), then enqueue it. Recovery re-enqueues a
+        // crash-surviving turn WITHOUT re-persisting (it is already on disk with a bumped attempt count).
+        const submit = (rec, persist) => {
+            if (persist)
+                store.add(toStored(rec)); // pre-ACK: a failed write throws → webhook 500 → redeliver
+            queue.accept(rec);
+        };
+        // 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.
+        const notifyDropped = (r) => {
+            const body = "⚠️ I couldn’t complete an earlier request — please ask again.";
+            const target = {
+                chatId: r.chatId,
+                threadId: r.threadId,
+                replyTo: r.replyTo,
+            };
+            const sent = r.previewId !== undefined
+                ? editMessageText(apiBaseUrl, botToken, target, r.previewId, body, {
+                    html: false,
+                })
+                : sendMessage(apiBaseUrl, botToken, target, body, {
+                    html: false,
+                }).then(() => { });
+            void sent.catch((e) => log.warn(`[telegram] could not notify a dropped turn (session=${r.session}): ${String(e)}`));
+        };
+        // Re-enqueue turns a prior crash left mid-flight (ACKed but unfinished). Synchronous at construction:
+        // the queue runs them on the next tick, once this factory returns and the event loop turns. The
+        // execution ceiling is enforced per turn at dequeue (run), not here — a never-run turn keeps its budget.
+        const recovered = store.recover();
+        if (recovered.length > 0)
+            log.info(`[telegram] recovering ${recovered.length} unfinished turn(s) from a prior run`);
+        for (const { attempts: _a, ...intent } of recovered)
+            submit({ ...intent, previewId: undefined }, false);
+        const handler = async (req) => {
+            if (req.method !== "POST")
+                return text("POST only\n", 405);
+            // Fail closed: a missing/wrong secret token is 401, never routed.
+            if (!tokenMatches(req.headers.get("x-telegram-bot-api-secret-token") ?? "", secretToken)) {
+                return text("invalid secret token\n", 401);
+            }
+            const body = await readBodyCapped(req, MAX_UPDATE_BYTES);
+            if ("tooLarge" in body)
+                return text("payload too large\n", 413);
+            let update;
+            try {
+                update = JSON.parse(body.text);
+            }
+            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.
+            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.
+                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.
+                    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).
+                    const summary = attachmentSummary(m);
+                    const bodyLine = summary && content !== summary ? `${content} ${summary}` : content;
+                    buffer.push(placeKey, {
+                        sender: fromLabel(m.from) ?? "someone",
+                        body: bodyLine,
+                        messageId: m.message_id,
+                        replyTo: m.reply_to_message?.message_id,
+                        fileIds: fileIds.length ? fileIds : undefined,
+                        imageIds: imageIds.length ? imageIds : undefined,
+                    });
+                }
+                return new Response(null, { status: 200 });
+            }
+            {
+                const session = r.session ?? 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.
+                const threadId = r.threadId ?? m.message_thread_id;
+                const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
+                const baseText = r.text ?? telegramEnvelope(m);
+                const imageFileIds = extractImages(m);
+                const fileIds = extractFiles(m);
+                if (baseText.trim() !== "" || imageFileIds.length > 0 || fileIds.length > 0) {
+                    // Everything the turn needs, as a plain record; persisted pre-ACK then run serially per session.
+                    submit({
+                        id: `${update.update_id}`,
+                        session,
+                        placeKey,
+                        baseText,
+                        chatId,
+                        threadId,
+                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
+                        imageFileIds,
+                        fileIds,
+                    }, true);
+                }
+            }
+            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.
+        handler.turnsIdle = () => queue.idle();
+        return { "POST /telegram": handler };
+    };
+}

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

@@ -0,0 +1,21 @@
+export interface TurnQueue<T> {
+    /** Schedule onto the session's serial chain (runs after that session's previous turn). */
+    accept(rec: T): void;
+    /** Resolve once no turn is in flight (every per-session chain has drained). A test/observability seam
+     *  — the production runtime does NOT drain on shutdown (SIGTERM exits mid-turn by design; see the module
+     *  header), so this is not a graceful-drain hook; it just lets a caller await the fire-and-forget turns. */
+    idle(): Promise<void>;
+}
+export declare function createTurnQueue<T extends {
+    session: string;
+}>(opts: {
+    /** Log prefix naming the consumer (e.g. "[telegram]") — the queue itself is channel-neutral. */
+    label: string;
+    /** Executes ONE turn. The queue wraps it: dequeue in FIFO order per session. The runner owns its
+     *  own error surface; a rejection that escapes anyway is caught and logged here (never a silent
+     *  unhandled rejection), but the runner's own catch is where diagnosis belongs. */
+    run: (rec: T) => Promise<void>;
+    /** Fired synchronously when a record is scheduled BEHIND an active turn — the caller's hook for
+     *  queue feedback to the user (e.g. an "⏳ queued" notice). */
+    onQueuedBehind?: (rec: T) => void;
+}): TurnQueue<T>;

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

@@ -0,0 +1,47 @@
+/**
+ * Per-session serial turn execution: one turn at a time per session (FIFO chains), different
+ * sessions concurrent. IN-MEMORY — the runtime queue holds no durability of its own. The engine lease
+ * is the corruption floor beneath this; this adds the group-UX queue (a second summon waits its turn
+ * instead of colliding on the lease and being dropped as "busy").
+ *
+ * Channel-neutral (records are opaque beyond a `session` key); it lives in the telegram directory
+ * because that is its only consumer today. Durability is layered ON TOP by the caller: turn-store.ts
+ * persists an accepted turn's intent pre-ACK and replays a crash-surviving one on the next start (L1,
+ * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
+ * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
+ */
+import { log } from "../../log.js";
+export function createTurnQueue(opts) {
+    const { label, run, onQueuedBehind } = opts;
+    // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of
+    // colliding on the engine lease and being dropped as "busy". Different sessions run concurrently.
+    const chains = new Map();
+    return {
+        accept(rec) {
+            if (chains.has(rec.session))
+                onQueuedBehind?.(rec);
+            const prev = chains.get(rec.session) ?? Promise.resolve();
+            const task = async () => {
+                try {
+                    await run(rec);
+                }
+                catch (e) {
+                    log.error(`${label} turn runner rejected (session=${rec.session}; own your error surface in run()): ${String(e)}`);
+                }
+            };
+            const next = prev.then(task, task); // run after this session's previous turn, in arrival order
+            chains.set(rec.session, next);
+            void next.finally(() => {
+                if (chains.get(rec.session) === next)
+                    chains.delete(rec.session); // drop the entry when drained
+            });
+        },
+        async idle() {
+            // Await outstanding chains until none remain — a chain may schedule a follow-up turn, and each
+            // deletes its own map entry on settle, so an emptied map means every turn ran to completion. The
+            // tasks catch their own rejections, but allSettled keeps idle() itself total regardless.
+            while (chains.size > 0)
+                await Promise.allSettled([...chains.values()]);
+        },
+    };
+}

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

@@ -0,0 +1,38 @@
+/** 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;
+    placeKey: string;
+    baseText: string;
+    chatId: number | string;
+    threadId?: number;
+    replyTo?: number;
+    imageFileIds: string[];
+    fileIds: string[];
+    attempts: number;
+}
+export interface TurnStore {
+    /** Persist an accepted turn before the ACK. A failed write throws (→ webhook 500, Telegram redelivers). */
+    add(rec: StoredTurn): void;
+    /** Remove a finished turn. Post-ACK: a failed write is logged, never thrown (must not abort delivery). */
+    remove(id: string): void;
+    /** Every persisted turn a crash left behind, in ARRIVAL order, to re-enqueue on the next start. Read-
+     *  only — the ceiling is enforced per turn at `startAttempt`, so a never-run turn's budget is untouched
+     *  by a restart. Order matters: the queue rebuilds each session's FIFO chain from re-enqueue order. */
+    recover(): StoredTurn[];
+    /** Called when a turn is about to RUN (dequeued). Returns:
+     *   - "run": bumped its persisted execution count; go ahead.
+     *   - "exceeded": over `maxAttempts` starts without finishing (killed mid-run every time, whatever the
+     *     cause); the record is dropped and the runner notifies the asker.
+     *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
+     *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
+     *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
+     *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
+     *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
+    startAttempt(id: string, maxAttempts: number): "run" | "exceeded" | "defer";
+}
+export declare function createTurnStore(path: string): TurnStore;

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

@@ -0,0 +1,150 @@
+/**
+ * Durable turn intent: the L1 half of durable execution (the L2 exactly-once / deterministic
+ * step-replay layer is the K-axis backend — docs/design/core.md §11). Persists an accepted turn BEFORE
+ * the webhook 200 (pre-ACK, like context-buffer) and removes it when the turn ENDS — the runner's
+ * `finally`: a completed turn OR any caught error both remove it. Precisely, a completed turn's removal
+ * fires at the `completed` event (the session is committed), which is BEFORE streamReply delivers the
+ * answer to Telegram: so L1 recovers the ACKed-but-un-COMPLETED window, not un-DELIVERED. A crash in
+ * that narrow tail (completed, session-committed, but the message not yet sent) leaves the answer in the
+ * session history undelivered and is deliberately NOT replayed — replaying a session-committed turn
+ * would double-append it; the asker re-asks (and sees the prior answer in history). L1's scope is the
+ * INTERRUPTED-run window (the `finally` never runs); a caught error is NOT retried here — a `failed`
+ * event already told the user, and a transport throw is dropped exactly like the pre-L1 in-memory queue
+ * did (replaying it could double-send). Only an interrupted run leaves the record on disk — and
+ * "interrupted" is not just a rare crash: `runStart` has no graceful drain (cli.ts), so a SIGTERM exits
+ * mid-turn too, i.e. EVERY rolling deploy that catches an in-flight turn. Recovery re-enqueues it next start.
+ *
+ * This recovers the ACKed-but-unfinished window the in-memory turn-queue drops (turn-queue.ts). Weigh
+ * the trade before trusting it: the alternative (dropping the turn) fails VISIBLY and self-corrects
+ * (the turn vanished, the asker re-asks); replay's sharpest cost is the opposite — invisible. It is
+ * at-least-once, not exactly-once:
+ *   - PRIMARY cost: replay re-runs the WHOLE turn, so every external side effect happens AGAIN — re-sent
+ *     messages, re-fired tool actions — and nobody may notice (unlike the visible loss it replaces).
+ *     And the trigger is not rare (above): it fires on every deploy that interrupts an in-flight turn,
+ *     not just on crashes. So "safe only if the turn's tools are idempotent" is a bar to judge against
+ *     DEPLOY frequency: it holds for a Q&A bot, and is the gate for adding side-effecting tools. (A
+ *     mid-stream interruption also leaves an orphan "💭 Thinking…" preview — cosmetic.)
+ *   - The pre-ACK window overlaps Telegram redelivery: a crash AFTER the persist but BEFORE the 200
+ *     means recovery replays the turn AND Telegram (never-ACKed) redelivers the same update — same
+ *     update_id, but the queue does not dedup, so the turn can run twice. Exactly-once (a persisted
+ *     delivery key) is L2.
+ *
+ * ponytail: at-least-once with a per-turn EXECUTION ceiling. A poison turn that deterministically
+ * crashes the process would replay forever under a container restart policy. The counter is bumped at
+ * `startAttempt` — when a turn is about to RUN, not per restart cycle — so it counts a turn's OWN
+ * execution attempts: `recover()` re-enqueues every surviving turn without touching its count, and a
+ * poison turn at a session's head is dropped on its own N+1th run WITHOUT penalizing the never-run turns
+ * queued behind it (they keep their full budget and get their turn once the poison one is gone). On drop,
+ * the runner notifies the asker (the chain's end must get a signal — a log line the user can't see isn't).
+ * The bump is the ONE post-ACK write that fails CLOSED (not best-effort): if it can't be persisted the
+ * turn is DEFERRED — skipped this cycle and left on disk to replay on the next start — rather than run
+ * untracked, because an unpersisted count lets recover() re-run a poison turn every restart (the ceiling
+ * would never advance on disk). It replays on the next START — a restart is required; disk recovery alone
+ * does not re-run a deferred turn — and the asker is NOT told (a transient system degrade, not a user-
+ * actionable failure — telling them "ask again" would double-answer on that replay).
+ * Single-process, single-writer: same durability model as state.ts (crash-safe via atomic rename;
+ * power-loss is best-effort — no fsync, consistent with the rest of the channel's state).
+ */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "./state.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). */
+function isStoredTurn(t) {
+    const r = t;
+    const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+    return (typeof r?.id === "string" &&
+        typeof r.session === "string" &&
+        typeof r.placeKey === "string" &&
+        typeof r.baseText === "string" &&
+        (typeof r.chatId === "string" || typeof r.chatId === "number") &&
+        (r.threadId === undefined || typeof r.threadId === "number") &&
+        (r.replyTo === undefined || typeof r.replyTo === "number") &&
+        strings(r.imageFileIds) &&
+        strings(r.fileIds) &&
+        typeof r.attempts === "number");
+}
+export function createTurnStore(path) {
+    const load = () => {
+        const raw = loadStateFile(path);
+        if (raw === undefined)
+            return new Map();
+        if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.values(raw).every(isStoredTurn)) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`[telegram] unexpected shape in ${path} — starting with no pending turns`);
+        return new Map();
+    };
+    const turns = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(turns));
+    // Post-ACK writes (remove, startAttempt) must not abort a turn: log a failed write, never throw.
+    const persistBestEffort = (what) => {
+        try {
+            persist();
+        }
+        catch (e) {
+            log.error(`[telegram] turn-store ${what} write failed post-ACK: ${String(e)}`);
+        }
+    };
+    return {
+        add(rec) {
+            // Idempotent on re-add: a redelivery (pre-ACK crash → never-ACKed update replayed) re-submits an id
+            // already in the store. Skip it — the intent is already durable, and overwriting would RESET this
+            // turn's execution count, handing a poison turn a fresh ceiling budget.
+            if (turns.has(rec.id))
+                return;
+            turns.set(rec.id, rec);
+            try {
+                persist(); // pre-ACK: a throw becomes the webhook's 500 and Telegram redelivers
+            }
+            catch (e) {
+                // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom
+                // entry makes the redelivery's `add` short-circuit on `turns.has` — running the turn with its
+                // intent never persisted, defeating this module — and gets flushed later by an unrelated persist.
+                turns.delete(rec.id);
+                throw e;
+            }
+        },
+        remove(id) {
+            if (turns.delete(id))
+                persistBestEffort("remove (a restart may replay an answered turn)");
+        },
+        recover() {
+            // Arrival order, so the queue rebuilds each session's FIFO chain correctly. Ids are Telegram
+            // update_ids — monotonic — so numeric id order IS arrival order; sort on it explicitly rather than
+            // lean on JS object-key enumeration happening to survive the load's JSON round-trip.
+            return [...turns.values()].sort((a, b) => Number(a.id) - Number(b.id));
+        },
+        startAttempt(id, maxAttempts) {
+            const rec = turns.get(id);
+            if (!rec)
+                return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
+            const attempts = rec.attempts + 1;
+            if (attempts > maxAttempts) {
+                // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps
+                // this whether IT poisoned the process or a deploy/OOM took it down each time.
+                log.error(`[telegram] dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +
+                    `(session=${rec.session}) — it may be crashing the process, or was killed mid-run each time; notifying the asker`);
+                turns.delete(id);
+                persistBestEffort("drop");
+                return "exceeded";
+            }
+            turns.set(id, { ...rec, attempts });
+            try {
+                persist();
+            }
+            catch (e) {
+                // The bump MUST be durable, unlike remove/drop: if it isn't, a restart's recover() reads the old
+                // count and RE-RUNS this turn — a poison turn would re-execute forever (the ceiling never advances
+                // on disk). Fail closed: roll the memory bump back (match disk) and DEFER — the record stays on
+                // disk with its old count and replays on the next start (a restart is required; disk recovery
+                // alone won't re-run it). Not a drop: under disk failure the removal couldn't persist anyway.
+                // The runner skips silently (no notify).
+                turns.set(id, rec);
+                log.error(`[telegram] cannot persist turn ${id}'s attempt count — deferring it to the next start rather ` +
+                    `than run it untracked (session=${rec.session}): ${String(e)}`);
+                return "defer";
+            }
+            return "run";
+        },
+    };
+}

package/dist/cli-auth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI presenter for the auth-status line `reportAuth` prints (invoke/dev/start). Kept out of cli.ts —
+ * which self-executes on import — so the expired-vs-missing DECISION is unit-testable without a real
+ * credential round-trip, mirroring cli-models.ts.
+ */
+/** A stored credential as `reportAuth` needs it: just its kind, for the status line. */
+export interface StoredCredentialInfo {
+    type: string;
+}
+/**
+ * Format the auth status for `spec`'s provider. `source` is {@link probeAuthSource}'s label (an env-var
+ * name, "OAuth", a stored-key label) or undefined when nothing currently SATISFIES auth. Undefined has
+ * TWO causes probeAuthSource can't distinguish (it swallows the throw): nothing stored, OR a credential
+ * that IS stored but couldn't be made usable (an expired/revoked OAuth whose refresh failed). `stored`
+ * — a refresh-FREE store read the caller does only in that case — tells them apart, so an expired login
+ * reports "expired/unusable → `fastagent login`" instead of a misleading "(none found)" (which would then
+ * be contradicted by the actual "OAuth refresh failed"). A malformed/unreadable store also reads as
+ * undefined `stored` and lands in "(none found)" — but the store's own read warns about the corrupt file,
+ * so the real signal is surfaced there; this line stays about credential PRESENCE.
+ */
+export declare function formatAuthReport(provider: string, authPath: string, source: string | undefined, stored: StoredCredentialInfo | undefined): {
+    line: string;
+    warn?: string;
+};