@fastagent-sh/fastagent 0.12.0

package/dist/channels/http.js

@@ -0,0 +1,161 @@
+/**
+ * HTTP/SSE channel: fan one invoke stream out to Server-Sent Events.
+ *
+ * The handler is Fetch-shaped (`(Request) => Promise<Response>`) — the cross-runtime form every
+ * embedding host speaks, so it mounts inside an existing app's own route. It is path-agnostic. The
+ * web stream primitives give cancellation (consumer disconnect → cancel() → iterator.return() →
+ * invoke cancellation, SPEC MUST 3), backpressure (pull-based), and the body cap natively.
+ *
+ * `nodeListener` is the thin node:http adapter for the standalone `fastagent dev/start` server.
+ */
+import { Readable } from "node:stream";
+import { log } from "../log.js";
+import { readBodyCapped } from "./body.js";
+import { text, textHeaders } from "./respond.js";
+/** Request body cap (1 MiB). */
+const MAX_BODY_BYTES = 1 << 20;
+const encoder = new TextEncoder();
+/**
+ * Fetch-shaped invoke handler. Mount it at any route in the host app; it accepts POST only.
+ * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.
+ */
+export function createInvokeHandler(agent) {
+    return async (req) => {
+        if (req.method !== "POST")
+            return text("POST only\n", 405);
+        const body = await readBodyCapped(req, MAX_BODY_BYTES);
+        if ("tooLarge" in body)
+            return text("body too large\n", 413);
+        let payload;
+        try {
+            payload = JSON.parse(body.text);
+        }
+        catch {
+            return text("invalid json\n", 400);
+        }
+        const { session, text: promptText } = (payload ?? {});
+        if (typeof session !== "string" || typeof promptText !== "string") {
+            return text('need { "session": string, "text": string }\n', 400);
+        }
+        // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
+        // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
+        const iterator = agent.invoke({ session }, { text: promptText })[Symbol.asyncIterator]();
+        const stream = new ReadableStream({
+            async pull(controller) {
+                const { value, done } = await iterator.next();
+                if (done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
+            },
+            async cancel() {
+                await iterator.return?.();
+            },
+        });
+        return new Response(stream, {
+            status: 200,
+            headers: {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            },
+        });
+    };
+}
+/**
+ * node:http adapter for a Fetch handler. Bridges IncomingMessage → Request and pumps the
+ * Response body back to ServerResponse with backpressure; a client disconnect (`res` close)
+ * cancels both the request signal and the response stream (→ invoke cancellation).
+ */
+export function nodeListener(handler) {
+    return (req, res) => {
+        void pump(handler, req, res); // safe: pump is TOTAL (never rejects) — see its contract below
+    };
+}
+/**
+ * Consume ONE request and drive its response to a terminal state. pump is TOTAL: a SINGLE try/catch wraps
+ * the whole request→response→stream path, so EVERY failure — a handler throw, a non-Response return
+ * (`response.headers` undefined), a header Node rejects, `getReader`, or a body stream that errors
+ * mid-flight — ends the response and the returned promise NEVER rejects, which is what lets the
+ * `void pump(...)` above be safe. Before any byte goes out (headers not sent) it is a clean 500; once the
+ * response is streaming, the only honest signal left is to destroy the socket (truncated stream, not a
+ * hang). The process installs no `unhandledRejection` handler by design: robustness against a background
+ * throw is each fire-and-forget's OWN contract (fail into a terminal HTTP response here), not a global net
+ * that would blanket-swallow.
+ */
+async function pump(handler, req, res) {
+    const controller = new AbortController();
+    res.on("close", () => controller.abort());
+    try {
+        const method = req.method ?? "GET";
+        const hasBody = method !== "GET" && method !== "HEAD";
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(req.headers)) {
+            if (Array.isArray(v))
+                for (const vv of v)
+                    headers.append(k, vv);
+            else if (v != null)
+                headers.set(k, v);
+        }
+        const request = new Request(`http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`, {
+            method,
+            headers,
+            body: hasBody ? Readable.toWeb(req) : undefined,
+            duplex: "half",
+            signal: controller.signal,
+        });
+        const response = await handler(request);
+        const outHeaders = {};
+        response.headers.forEach((value, key) => {
+            outHeaders[key] = value;
+        });
+        res.writeHead(response.status, outHeaders);
+        if (!response.body) {
+            res.end();
+            return;
+        }
+        const reader = response.body.getReader();
+        res.on("close", () => void reader.cancel());
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done || res.destroyed)
+                break;
+            // Backpressure: wait for drain, but ALSO resolve on close. A client disconnect after write()
+            // returned false never emits 'drain' on the closed socket, so waiting on 'drain' alone would
+            // suspend pump() forever (leaking the request/stream).
+            if (!res.write(value)) {
+                await new Promise((resolve) => {
+                    const settle = () => {
+                        res.off("drain", settle);
+                        res.off("close", settle);
+                        resolve();
+                    };
+                    res.once("drain", settle);
+                    res.once("close", settle);
+                });
+            }
+        }
+        if (!res.destroyed)
+            res.end(); // normal completion
+    }
+    catch (error) {
+        // The ONE totality boundary: every failure above lands here, so pump never rejects (see the header
+        // doc) — which REQUIRES the catch itself not to throw. Don't leak the internal message to the client.
+        log.error(`[host] request failed: ${String(error)}`);
+        // Never touch an already-terminal res: a client that disconnects during the handler await destroys res
+        // (headers not yet sent), and writeHead/end on a dead socket can throw ERR_STREAM_DESTROYED here — which
+        // WOULD be the unhandled rejection this boundary exists to kill. One named gate states the invariant;
+        // with it the catch is provably non-throwing (writeHead only when !headersSent && !destroyed, destroy is
+        // idempotent).
+        if (res.destroyed)
+            return;
+        if (res.headersSent) {
+            res.destroy(error instanceof Error ? error : undefined); // streaming → truncate (not a hang)
+        }
+        else {
+            res.writeHead(500, textHeaders); // pre-header → a clean 500
+            res.end("internal error\n");
+        }
+    }
+}

package/dist/channels/respond.d.ts

@@ -0,0 +1,5 @@
+/** Shared `text/plain` reply for channels + the host (error/status responses). */
+export declare const textHeaders: {
+    readonly "content-type": "text/plain";
+};
+export declare const text: (body: string, status: number) => Response;

package/dist/channels/respond.js

@@ -0,0 +1,3 @@
+/** Shared `text/plain` reply for channels + the host (error/status responses). */
+export const textHeaders = { "content-type": "text/plain" };
+export const text = (body, status) => new Response(body, { status, headers: textHeaders });

package/dist/channels/telegram/context-buffer.d.ts

@@ -0,0 +1,59 @@
+/** One buffered un-summoned message (object identity is the commit key). Besides the sender label and
+ *  one-line body, it carries what a LATER summon needs to resolve references into the discussion:
+ *  message ids ("reply to the one Alex answered"), and attachment file_ids so "summarize the file from
+ *  earlier" can actually open it — an un-summoned attachment otherwise surfaces only as its caption or
+ *  a `[document: …]` label, never the bytes. */
+export interface BufferEntry {
+    sender: string;
+    body: string;
+    /** The message's id — rendered into the fold so the model can correlate replies. */
+    messageId?: number;
+    /** The message_id this one replied to, when it was a reply. */
+    replyTo?: number;
+    /** file_ids of document/voice/video/audio attachments (downloadable on a later summon). */
+    fileIds?: string[];
+    /** file_ids of photos (usable as vision inputs on a later summon). */
+    imageIds?: string[];
+}
+/** A buffered attachment reference: its file_id plus WHO posted it in WHICH message, so the manifest
+ *  can attribute it ("the file Bob sent") the way the fold attributes text. */
+export interface BufferedRef {
+    id: string;
+    from: string;
+    msg?: number;
+}
+/**
+ * The buffered attachment references a summoned turn pulls in with the fold — most recent
+ * BUFFER_ATTACH_MAX of each kind, MINUS the summoning message's own ids: replying to a still-buffered
+ * attachment puts its file_id in both sets, and without the filter the same file would download twice
+ * and appear in the manifest twice (primary wins — it is what the user pointed at this turn).
+ * Cap-skipped ones are COUNTED, not silently dropped: a fold line may show a [document: …] label, but
+ * a captioned attachment renders as its caption text alone — without a note, the model holds
+ * references it silently cannot open and may pretend it read them.
+ */
+export declare function collectAttachments(consumed: BufferEntry[], primary: {
+    files: Set<string>;
+    images: Set<string>;
+}): {
+    files: BufferedRef[];
+    images: BufferedRef[];
+    skipped: number;
+};
+export interface ContextBuffer {
+    /** Record an un-summoned message. Persists BEFORE returning (pre-ACK: a throw becomes the webhook's
+     *  500, and Telegram redelivers once the disk recovers) — staged on a copy and rolled back on a
+     *  failed write, so the redelivery does not double-append the entry already in memory. */
+    push(placeKey: string, entry: BufferEntry): void;
+    /** Render the fold text and snapshot the consumed entries (see the module header's consume protocol). */
+    peek(placeKey: string): {
+        text: string;
+        consumed: BufferEntry[];
+    };
+    /** Remove exactly `consumed` (by identity) — call on the turn's `completed` event, when the folded
+     *  discussion provably lives in the durable session. Consumes entries WHOLE, including ones whose
+     *  attachments failed to load or were cap-skipped: their text is in the session (keeping them would
+     *  re-fold duplicate text), and the prompt note said what is missing; re-post an attachment to use
+     *  it. Post-ACK: a failed write is logged, never thrown (it must not abort the turn's delivery). */
+    commit(placeKey: string, consumed: BufferEntry[]): void;
+}
+export declare function createContextBuffer(path: string): ContextBuffer;

package/dist/channels/telegram/context-buffer.js

@@ -0,0 +1,139 @@
+/**
+ * Group-context buffer: recent UN-summoned messages per Telegram "place" (chat[:thread]), kept under a
+ * char budget and folded into the next answered turn's prompt, so a summoned agent has the discussion
+ * it didn't see turn-by-turn. Bucketed by place (not session): an un-summoned message has no route
+ * session, and the flush feeds whatever turn answers that place.
+ *
+ * DURABLE: persisted synchronously before the webhook 200 (Telegram never redelivers an ACKed update,
+ * so ACK-then-persist would be a silent-loss window) and reloaded on start. The consume protocol is
+ * peek → (turn completes) → commit: peek renders WITHOUT clearing and snapshots exactly which entries
+ * it consumed; commit removes only those, by object identity — so a failure or crash before the turn's
+ * `completed` leaves them intact for the next summon, and a message that arrives while the turn runs
+ * survives for the next answered turn (a whole-bucket delete would lose it).
+ */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+/** Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded
+ *  the OLDEST un-summoned messages are dropped (not a time window: a quiet group keeps its
+ *  sparse-but-relevant lines, a busy burst is capped). */
+const BUFFER_MAX_CHARS = 4000;
+/** How many buffered files and images (each, most recent first) a summon pulls in with the folded
+ *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
+ *  group posting many attachments between summons. Skipped ones are counted into the prompt note, so
+ *  the model never sees an attachment reference it silently cannot open. */
+const BUFFER_ATTACH_MAX = 3;
+/** One fold line. ALSO the eviction cost basis: the budget must price what the fold actually renders
+ *  (sender + body + the msg/reply meta), or the fold would systematically overrun BUFFER_MAX_CHARS. */
+function bufferLine(e) {
+    const meta = [
+        e.messageId !== undefined ? `msg ${e.messageId}` : undefined,
+        e.replyTo !== undefined ? `reply to msg ${e.replyTo}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    return `${e.sender}${meta ? ` (${meta})` : ""}: ${e.body}`;
+}
+/**
+ * The buffered attachment references a summoned turn pulls in with the fold — most recent
+ * BUFFER_ATTACH_MAX of each kind, MINUS the summoning message's own ids: replying to a still-buffered
+ * attachment puts its file_id in both sets, and without the filter the same file would download twice
+ * and appear in the manifest twice (primary wins — it is what the user pointed at this turn).
+ * Cap-skipped ones are COUNTED, not silently dropped: a fold line may show a [document: …] label, but
+ * a captioned attachment renders as its caption text alone — without a note, the model holds
+ * references it silently cannot open and may pretend it read them.
+ */
+export function collectAttachments(consumed, primary) {
+    const refs = (pick, exclude) => {
+        const seen = new Set();
+        const out = [];
+        for (const e of consumed) {
+            for (const id of pick(e) ?? []) {
+                if (exclude.has(id) || seen.has(id))
+                    continue;
+                seen.add(id);
+                out.push({ id, from: e.sender, msg: e.messageId });
+            }
+        }
+        return out;
+    };
+    const files = refs((e) => e.fileIds, primary.files);
+    const images = refs((e) => e.imageIds, primary.images);
+    return {
+        files: files.slice(-BUFFER_ATTACH_MAX),
+        images: images.slice(-BUFFER_ATTACH_MAX),
+        skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) + Math.max(0, images.length - BUFFER_ATTACH_MAX),
+    };
+}
+/** State files are an IO boundary: valid JSON of the WRONG SHAPE (hand-edited, version drift) must
+ *  degrade exactly like a corrupt file — warn + empty — not flow in as trusted data. */
+function isBufferEntry(e) {
+    const t = e;
+    const strings = (v) => v === undefined || (Array.isArray(v) && v.every((x) => typeof x === "string"));
+    return (typeof t?.sender === "string" &&
+        typeof t.body === "string" &&
+        (t.messageId === undefined || typeof t.messageId === "number") &&
+        (t.replyTo === undefined || typeof t.replyTo === "number") &&
+        strings(t.fileIds) &&
+        strings(t.imageIds));
+}
+export function createContextBuffer(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((v) => Array.isArray(v) && v.every(isBufferEntry))) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`[telegram] unexpected shape in ${path} — starting with an empty buffer`);
+        return new Map();
+    };
+    const buffers = load();
+    const persist = () => saveStateFile(path, Object.fromEntries(buffers));
+    return {
+        push(placeKey, entry) {
+            const prev = buffers.get(placeKey);
+            const buf = prev ? [...prev] : [];
+            buf.push(entry);
+            let total = buf.reduce((n, e) => n + bufferLine(e).length + 1, 0);
+            while (buf.length > 1 && total > BUFFER_MAX_CHARS) {
+                const dropped = buf.shift();
+                if (dropped)
+                    total -= bufferLine(dropped).length + 1;
+            }
+            buffers.set(placeKey, buf);
+            try {
+                persist();
+            }
+            catch (e) {
+                if (prev)
+                    buffers.set(placeKey, prev);
+                else
+                    buffers.delete(placeKey);
+                throw e;
+            }
+        },
+        peek(placeKey) {
+            const buf = buffers.get(placeKey) ?? [];
+            return { text: buf.map(bufferLine).join("\n"), consumed: [...buf] };
+        },
+        commit(placeKey, consumed) {
+            const buf = buffers.get(placeKey);
+            if (!buf)
+                return;
+            const remaining = buf.filter((e) => !consumed.includes(e));
+            if (remaining.length === 0)
+                buffers.delete(placeKey);
+            else
+                buffers.set(placeKey, remaining);
+            try {
+                persist();
+            }
+            catch (e) {
+                log.error(`[telegram] buffer write failed post-ACK (a restart may re-fold answered discussion): ${String(e)}`);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Run one turn (the IO half of Telegram→Agent translation): assemble its inputs — resolve attachments
+ * (download files to disk, load vision images) — and stream `agent.invoke` with the assembled prompt.
+ * `invokeTurn` is the export; attachment resolution is an internal step. Split from parse.ts (which is
+ * pure) because this half touches the Bot API + disk; split from telegram.ts so the factory keeps only
+ * wiring and the per-turn lifecycle.
+ */
+import { type Agent, type AgentEvent } from "../../agent.ts";
+import type { BufferedRef } from "./context-buffer.ts";
+/** Everything the transport needs to fetch a turn's attachments. */
+export interface TurnTransport {
+    api: string;
+    botToken: string;
+    chatId: number | string;
+    filesDir: string;
+}
+/** A turn's attachment inputs: the summoning message's own file_ids (primary) and the ones folded in
+ *  from the un-summoned discussion (buffered). */
+export interface TurnAttachments {
+    primary: {
+        imageFileIds?: string[];
+        fileIds?: string[];
+    };
+    buffered: {
+        files: BufferedRef[];
+        images: BufferedRef[];
+        skipped: number;
+    };
+}
+/** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
+ *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
+ *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
+ *  always an outside holder — wait for it like a queued turn, instead of erroring at the user. */
+export interface BusyRetry {
+    delayMs: number;
+    maxWaitMs: number;
+}
+/**
+ * Run one turn: resolve its attachments, then stream agent.invoke. A primary-attachment failure surfaces
+ * as a `failed` event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed`
+ * event — the durable-commit point: only then does the folded discussion provably live in the session,
+ * so a failure or crash at ANY earlier point leaves the buffer intact for the next summon (a re-folded
+ * block beats lost context). The caller uses it to remove the turn intent AND commit the context buffer,
+ * in that order (see the call site) so a crash between the two clears cannot replay a context-stripped turn.
+ *
+ * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn (e.g. a self-scheduled
+ * wake) holds this session's lease and OUR turn never started — replay-safe. Retry (bounded) instead of
+ * yielding it: the user sees the "Thinking…" placeholder while waiting (the mirror of the scheduler
+ * deferring a wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a
+ * FIRST-event busy retries — attachments are already resolved, and a fail-fast reject is the only shape
+ * the engine emits it in, so nothing that started is ever re-run.
+ */
+export declare function invokeTurn(agent: Agent, session: string, text: string, transport: TurnTransport, attachments: TurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;

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

@@ -0,0 +1,127 @@
+/**
+ * Run one turn (the IO half of Telegram→Agent translation): assemble its inputs — resolve attachments
+ * (download files to disk, load vision images) — and stream `agent.invoke` with the assembled prompt.
+ * `invokeTurn` is the export; attachment resolution is an internal step. Split from parse.ts (which is
+ * pure) because this half touches the Bot API + disk; split from telegram.ts so the factory keeps only
+ * wiring and the per-turn lifecycle.
+ */
+import { SESSION_BUSY_CODE } from "../../agent.js";
+import { log } from "../../log.js";
+import { resolveFiles, resolveImages } from "./telegram-api.js";
+/** Appended to the prompt (not the system prompt): the channel owns Telegram-HTML formatting. */
+const HTML_INSTRUCTION = "\n\n(Format your reply in Telegram-supported HTML — <b> <i> <u> <s> <code> <pre> <a href> — not Markdown.)";
+/**
+ * Resolve a turn's attachments: images (vision) inline, files downloaded to disk with their absolute
+ * paths listed in a manifest the agent reads with its tools. Two tiers, different failure policies.
+ * PRIMARY (this turn's own message) THROWS on any load failure — the caller turns it into a `failed`
+ * event, so the agent never runs on inputs the user sent but we failed to load. BACKGROUND (`buffered`,
+ * from the un-summoned discussion) degrades PER ATTACHMENT — a warn + a prompt note — rather than
+ * failing the ask it merely accompanies: one expired earlier file must neither block the answer nor drag
+ * down its still-valid siblings. Parallel (allSettled keeps input order + per-attachment isolation); the
+ * note counts EVERY missing one (load failures + cap-skipped) so the model never holds a reference it
+ * silently cannot open.
+ */
+async function resolveTurnAttachments(t, attachments) {
+    const { api, botToken, chatId, filesDir } = t;
+    const { primary, buffered } = attachments;
+    const images = await resolveImages(api, botToken, primary.imageFileIds);
+    const files = await resolveFiles(api, botToken, primary.fileIds, chatId, filesDir);
+    const bufferedImages = [];
+    const bufferedFiles = [];
+    let lost = 0;
+    const imageResults = await Promise.allSettled(buffered.images.map((ref) => resolveImages(api, botToken, [ref.id])));
+    for (const r of imageResults) {
+        if (r.status === "fulfilled")
+            bufferedImages.push(...(r.value ?? []));
+        else {
+            lost++;
+            log.warn(`[telegram] could not load an earlier (buffered) photo: ${String(r.reason)}`);
+        }
+    }
+    const fileResults = await Promise.allSettled(buffered.files.map(async (ref) => ({
+        ref,
+        files: (await resolveFiles(api, botToken, [ref.id], chatId, filesDir)) ?? [],
+    })));
+    for (const r of fileResults) {
+        if (r.status === "fulfilled") {
+            for (const file of r.value.files)
+                bufferedFiles.push({ file, ref: r.value.ref });
+        }
+        else {
+            lost++;
+            log.warn(`[telegram] could not load an earlier (buffered) attachment: ${String(r.reason)}`);
+        }
+    }
+    const missing = lost + buffered.skipped;
+    const bufferedNote = missing > 0
+        ? `\n[note: ${missing} attachment(s) from the earlier discussion are not loaded (expired, or older than the most recent few)]`
+        : "";
+    // PRIMARY first, background after — consistent with "primary wins": what the user pointed at this
+    // turn leads. Buffered file entries are attributed like the fold's text lines ("the file Bob sent"
+    // resolves); buffered PHOTOS cannot be (ImageRef carries no label), so their attribution stops at
+    // the fold's attachment markers (the buffer appends `[photo]` even to captioned lines) — a
+    // documented limit.
+    const allFiles = [
+        ...(files ?? []),
+        ...bufferedFiles.map(({ file, ref }) => ({
+            ...file,
+            name: `${file.name} (from ${ref.from}${ref.msg !== undefined ? `, msg ${ref.msg}` : ""}, earlier discussion)`,
+        })),
+    ];
+    const manifest = allFiles.length
+        ? `\n\n[attached files — read them with your tools:\n${allFiles.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+        : "";
+    const allImages = [...(images ?? []), ...bufferedImages];
+    return { images: allImages.length ? allImages : undefined, promptSuffix: `${bufferedNote}${manifest}` };
+}
+// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
+// free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
+// real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
+// this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
+// turn forever.
+const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
+/**
+ * Run one turn: resolve its attachments, then stream agent.invoke. A primary-attachment failure surfaces
+ * as a `failed` event (never a silent drop). `onCompleted` (if given) fires on the turn's `completed`
+ * event — the durable-commit point: only then does the folded discussion provably live in the session,
+ * so a failure or crash at ANY earlier point leaves the buffer intact for the next summon (a re-folded
+ * block beats lost context). The caller uses it to remove the turn intent AND commit the context buffer,
+ * in that order (see the call site) so a crash between the two clears cannot replay a context-stripped turn.
+ *
+ * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn (e.g. a self-scheduled
+ * wake) holds this session's lease and OUR turn never started — replay-safe. Retry (bounded) instead of
+ * yielding it: the user sees the "Thinking…" placeholder while waiting (the mirror of the scheduler
+ * deferring a wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a
+ * FIRST-event busy retries — attachments are already resolved, and a fail-fast reject is the only shape
+ * the engine emits it in, so nothing that started is ever re-run.
+ */
+export async function* invokeTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
+    let resolved;
+    try {
+        resolved = await resolveTurnAttachments(transport, attachments);
+    }
+    catch (e) {
+        yield { type: "failed", details: `could not load attachment: ${String(e)}`, retryable: true };
+        return;
+    }
+    const prompt = { text: `${text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, images: resolved.images };
+    const deadline = Date.now() + busyRetry.maxWaitMs;
+    for (;;) {
+        let retryBusy = false;
+        let first = true;
+        for await (const e of agent.invoke({ session }, prompt)) {
+            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
+                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
+                break;
+            }
+            first = false;
+            if (e.type === "completed")
+                onCompleted?.(); // the turn is durably in the session — commit point
+            yield e;
+        }
+        if (!retryBusy)
+            return;
+        log.info(`[telegram] session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
+        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
+    }
+}