@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/channels/slack/slack.js

@@ -8,7 +8,11 @@ import { secretEquals } from "../secret.js";
 import { createSeenRing } from "../kit/seen.js";
 import { signatureIsFresh } from "../kit/signature.js";
 import { createThreadParticipants } from "../kit/thread-participants.js";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { portJoin } from "../../effect-port.js";
 import { createTaskTracker } from "../kit/tasks.js";
+import { attachmentsDir } from "../kit/attachment-path.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
 import { codePointPrefix } from "../kit/text.js";
@@ -16,17 +20,18 @@ import { createTurnRunner } from "../kit/turn-runner.js";
 import { createTurnStore } from "../kit/turn-store.js";
 import { discussionBlock } from "../kit/context-buffer.js";
 import { collectSlackBufferedFiles, createSlackContextBuffer } from "./context-buffer.js";
-import { invokeSlackTurn } from "./invoke-turn.js";
+import { slackTurnStream } from "./invoke-turn.js";
 import { defaultSlackRoute, isSlackDirectMessage, isSlackGroupMessage, hasSlackMention, hasSlackUserMention, isSlackHumanMessage, mentionsSlackUser, stripSlackMentions, slackBufferText, slackEnvelope, slackFileIds, slackMessageText, slackPlaceKey, slackSenderLabel, slackTeamId, } from "./parse.js";
-import { defaultErrorMessage, settleSlackPreview, streamSlackReply, } from "./preview.js";
-import { resolveReactionEmojis, startSlackReaction } from "./reaction.js";
+import { defaultErrorMessage, deliverSlackAnswer, settleSlackPreview, slackReply, } from "./preview.js";
+import { completeSlackReaction, resolveReactionEmojis, startSlackReaction } from "./reaction.js";
 import { registerSlackApi } from "./shared-api.js";
 import { createSlackApi } from "./slack-api.js";
 import { createWelcomedUsers } from "./welcomed.js";
 export { defaultSlackRoute, slackEnvelope };
 const MAX_EVENT_BYTES = 1 << 20;
-/** Slack's own documented window — it re-signs every redelivery with a current timestamp, so a tight
- *  one costs nothing. The Feishu ingress reads hours off the same helper for the opposite reason. */
+/**
+ * Slack's own documented window — it re-signs every redelivery with a current timestamp, so a tight one costs nothing.
+ */
 const MAX_SIGNATURE_AGE_S = 5 * 60;
 const QUEUED_PLACEHOLDER = "⏳ Queued — I’ll start once the current task finishes.";
 const DEFERRED_PLACEHOLDER = "⏳ Delayed by a temporary system issue — I’ll retry automatically.";
@@ -56,12 +61,50 @@ export function verifySlackSignature(signingSecret, timestamp, signature, rawBod
     const expected = `v0=${createHmac("sha256", signingSecret).update(`v0:${timestamp}:${rawBody}`).digest("hex")}`;
     return secretEquals(signature, expected);
 }
-/** The (channel, ts) of the user's triggering message, encoded in the logical turn id `team:channel:ts`
- *  (Slack ids never contain a colon, so a 3-part split is exact). Used to place the reaction ack. */
+/**
+ * The (channel, ts) of the user's triggering message, encoded in the logical turn id `team:channel:ts` (Slack ids
+ * never contain a colon, so a 3-part split is exact).
+ */
 function messageRefOf(turnId) {
     const parts = turnId.split(":");
     return parts.length === 3 && parts[1] && parts[2] ? { channelId: parts[1], ts: parts[2] } : undefined;
 }
+/** How long an ingress may wait for `auth.test`: the Events API allows 3s to ACK, so this must fail well inside it. */
+const AUTH_ACK_BUDGET_MS = 2_000;
+function createSlackAuthentication(api, label) {
+    let teamId;
+    let botUserId;
+    let state = "pending";
+    const settled = api.authTest().then((identity) => {
+        teamId = identity.teamId;
+        botUserId = identity.userId;
+        state = "ready";
+        log.info(`${label} authenticated${identity.teamId ? ` for workspace ${identity.teamId}` : ""}`);
+    }, (error) => {
+        state = "failed";
+        throw new Error(`Slack auth.test failed — fix SLACK_BOT_TOKEN before accepting events: ${String(error)}`, {
+            cause: error,
+        });
+    });
+    void settled.catch((error) => log.error(`${label} ${String(error)}`));
+    return {
+        settled,
+        teamId: () => teamId,
+        botUserId: () => botUserId,
+        ready: () => state !== "pending"
+            ? settled
+            : new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => reject(new Error("Slack auth.test did not finish inside the Events API ACK budget")), AUTH_ACK_BUDGET_MS);
+                void settled.then(() => {
+                    clearTimeout(timeout);
+                    resolve();
+                }, (error) => {
+                    clearTimeout(timeout);
+                    reject(error);
+                });
+            }),
+    };
+}
 export function slackChannel(options) {
     const { botToken, signingSecret, rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
     if (!["native", "classic"].includes(rendering)) {
@@ -84,46 +127,15 @@ export function slackChannel(options) {
         ensureStateHome(stateHome);
         const api = createSlackApi({ botToken, baseUrl: apiBaseUrl });
         registerSlackApi(stateRoot, api); // the send tool delivers through this one (shared-api.ts)
-        let authenticatedTeamId;
-        let botUserId;
-        let authenticationState = "pending";
-        const authentication = api.authTest().then((identity) => {
-            authenticatedTeamId = identity.teamId;
-            botUserId = identity.userId;
-            authenticationState = "ready";
-            log.info(`${label} authenticated${identity.teamId ? ` for workspace ${identity.teamId}` : ""}`);
-        }, (error) => {
-            authenticationState = "failed";
-            throw new Error(`Slack auth.test failed — fix SLACK_BOT_TOKEN before accepting events: ${String(error)}`, {
-                cause: error,
-            });
-        });
-        // Construction cannot await Web API IO. Keep the rejection observed; recovered turns and ingress
-        // both gate on the same promise/state below and surface the failure without ACKing new work.
-        void authentication.catch((error) => log.error(`${label} ${String(error)}`));
-        const waitForAuthentication = () => {
-            if (authenticationState !== "pending")
-                return authentication;
-            return new Promise((resolve, reject) => {
-                const timeout = setTimeout(() => reject(new Error("Slack auth.test did not finish inside the Events API ACK budget")), 2_000);
-                void authentication.then(() => {
-                    clearTimeout(timeout);
-                    resolve();
-                }, (error) => {
-                    clearTimeout(timeout);
-                    reject(error);
-                });
-            });
-        };
-        // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle. Declared
-        // ahead of its consumers so no construction-time path can reach it in the temporal dead zone.
+        const auth = createSlackAuthentication(api, label);
+        // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle.
         const sideTasks = createTaskTracker(label);
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
         const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
-        /** A thread's participation is keyed by the SESSION it describes — "the agent answered here" is a
-         *  claim about a memory, so the two must not be re-keyable independently. What keeps the claim true
-         *  under a custom route is the `routed.session === undefined` condition on the write, not the
-         *  absence of a route: a route that supplies its own session records nothing here. */
+        /**
+         * A thread's participation is keyed by the SESSION it describes — "the agent answered here" is a claim about a
+         * memory, so the two must not be re-keyable independently.
+         */
         const threadKey = (teamId, channelId, threadTs) => `slack:${teamId}:${channelId}:${threadTs}`;
         const welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
         const buffer = createSlackContextBuffer(join(stateHome, "buffers.json"), label);
@@ -159,7 +171,7 @@ export function slackChannel(options) {
                 if (nativeDmStatus)
                     turn.nativeQueueStatus = true;
                 return {
-                    done: authentication
+                    done: auth.settled
                         .then(() => nativeDmStatus
                         ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
                         : api.postMessage(targetOf(turn), QUEUED_PLACEHOLDER).then((ts) => {
@@ -168,12 +180,10 @@ export function slackChannel(options) {
                         .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)),
                 };
             },
-            // Leave the intent untouched when Slack auth failed. A fixed token + restart replays it;
-            // running now would execute an Agent turn whose only customer-facing transport is known to be
-            // unavailable.
+            // Leave the intent untouched when Slack auth failed.
             beforeRun: async (turn) => {
                 try {
-                    await authentication;
+                    await auth.settled;
                     return true;
                 }
                 catch (error) {
@@ -192,47 +202,67 @@ export function slackChannel(options) {
                 }
             },
             notifyDropped,
-            execute: async (turn, discussion, onCompleted) => {
+            deliverAnswer: (turn, answer) => portJoin(async () => {
+                // A queue notice THIS process put up outlives the run the answer came from, so it is settled here as it
+                // would be by a turn that ran: the status line cleared, the compatibility message taken over.
+                if (turn.nativeQueueStatus) {
+                    await api
+                        .setThreadStatus(targetOf(turn), "")
+                        .catch((error) => log.warn(`${label} could not clear a queued Agent status: ${String(error)}`));
+                }
+                await deliverSlackAnswer(api, targetOf(turn), answer, turn.previewTs);
+                // The 👀 on the asker's message was added by the run that produced this answer, and `execute`'s
+                // acquire/release — the only thing that turns it into ✅ — is not on this path.
                 const messageRef = messageRefOf(turn.id);
-                const reaction = reactionEmojis && messageRef
-                    ? await startSlackReaction({
+                if (reactionEmojis && messageRef) {
+                    await completeSlackReaction({
                         api,
                         channelId: messageRef.channelId,
                         ts: messageRef.ts,
                         emojis: reactionEmojis,
                         label,
-                    })
-                    : undefined;
-                try {
-                    await streamSlackReply(invokeSlackTurn(agent, turn.session, `${discussionBlock(discussion.text)}${turn.baseText}`, { api, channelId: turn.channelId, filesDir: join(stateHome, "files"), label }, {
-                        primaryFileIds: turn.fileIds,
-                        buffered: collectSlackBufferedFiles(discussion.consumed, new Set(turn.fileIds)),
-                    }, onCompleted), api, targetOf(turn), formatError, {
-                        rendering,
-                        initialPreviewTs: turn.previewTs,
-                        threadTitle: turn.threadTitle,
-                        disclaimer: aiDisclaimer,
-                        label,
                     });
                 }
-                catch (error) {
-                    await reaction?.remove();
-                    throw error;
-                }
-                await reaction?.complete();
+            }),
+            execute: (turn, discussion, onAnswered) => {
+                const messageRef = messageRefOf(turn.id);
+                return Effect.acquireUseRelease(portJoin(async () => reactionEmojis && messageRef
+                    ? startSlackReaction({
+                        api,
+                        channelId: messageRef.channelId,
+                        ts: messageRef.ts,
+                        emojis: reactionEmojis,
+                        label,
+                    })
+                    : undefined), () => Effect.scoped(slackReply(slackTurnStream(agent, turn.session, `${discussionBlock(discussion.text)}${turn.baseText}`, { api, channelId: turn.channelId, filesDir: attachmentsDir(stateHome), label }, {
+                    primaryFileIds: turn.fileIds,
+                    buffered: collectSlackBufferedFiles(discussion.consumed, new Set(turn.fileIds)),
+                }), api, targetOf(turn), formatError, {
+                    rendering,
+                    initialPreviewTs: turn.previewTs,
+                    threadTitle: turn.threadTitle,
+                    disclaimer: aiDisclaimer,
+                    label,
+                    onAnswered,
+                })), (reaction, exit) => portJoin(async () => {
+                    if (Exit.isSuccess(exit))
+                        await reaction?.complete();
+                    else
+                        await reaction?.remove();
+                }).pipe(Effect.orDie));
             },
         });
         let seq = runner.recover().reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
-        // Acceptance touches no network, so it stays synchronous inside Slack's ACK window and the
-        // delivery dedup ring alone is enough — there is no await for a duplicate delivery to race
-        // through. The minutes-long Agent turn remains fire-and-forget.
+        // Acceptance touches no network, so it stays synchronous inside Slack's ACK window and the delivery dedup ring
+        // alone is enough.
         const acceptEvent = (envelope) => {
             const event = envelope.event;
             if (!isSlackHumanMessage(event))
                 return;
+            const botUserId = auth.botUserId();
             if (botUserId && event.user === botUserId)
                 return;
-            const teamId = slackTeamId(envelope) ?? authenticatedTeamId;
+            const teamId = slackTeamId(envelope) ?? auth.teamId();
             if (!teamId) {
                 log.warn(`${label} ignored message ${event.ts}: event carried no workspace/enterprise identity`);
                 return;
@@ -246,37 +276,28 @@ export function slackChannel(options) {
             const direct = isSlackDirectMessage(event);
             const rootTs = event.thread_ts ?? event.ts;
             const bufferKey = slackPlaceKey(teamId, event);
-            // Listening is not speaking: every message the channel can see refines who takes part in its
-            // thread, whether or not it is answered. Humans only — a bot's own posts are recorded where they
-            // are known — this channel answering.
-            // Structural facts only, never `route` — see thread-participants.ts. Slack
-            // adds no delta of its own here; its summon rule is the only consumer.
+            // Listening is not speaking: every message the channel can see refines who takes part in its thread, whether or
+            // not it is answered.
             if (group && event.thread_ts !== undefined) {
                 threadParticipants.merge(threadKey(teamId, event.channel, event.thread_ts), { humans: [event.user] });
             }
             let routed = decide(envelope);
-            // Two different questions (see parse.ts). `addressesSomeone` is the "@-mentions only other people
-            // is discussion, never an ask" guard (§3) and counts broadcasts and user groups too;
-            // `mightBeTheBot` gates the identity-window deferral below, where only a USER mention qualifies.
+            // Two different questions (see parse.ts).
             const addressesSomeone = hasSlackMention(event.text ?? "");
             const mightBeTheBot = hasSlackUserMention(event.text ?? "");
             const structurallyMentionsBot = botUserId !== undefined && mentionsSlackUser(event.text ?? "", botUserId);
-            // app_mention and message.* subscriptions can overlap. If message.* arrives first, structural bot
-            // identity routes it now; while auth.test is still unresolved, defer any mentioned message rather
-            // than buffer+dedup it and accidentally suppress the later app_mention callback.
+            // app_mention and message.* subscriptions can overlap.
             if (!routed && route === undefined && group && event.type === "message" && structurallyMentionsBot)
                 routed = {};
-            // The participant model's thread rule (§3): a bare message reaches the agent while it takes part
-            // and has not heard a second human. Note the ORDER — the mention guard below runs first and is
-            // structural: it reads who THIS message addresses, which is the one thing an observation-only
-            // store cannot know about someone it has never heard.
+            // The participant model's thread rule (§3): a bare message reaches the agent while it takes part and has not
+            // heard a second human.
             if (!routed &&
                 route === undefined &&
                 group &&
                 event.thread_ts !== undefined &&
                 event.type !== "app_mention" &&
-                // Mentioning only other people is targeted discussion, never an ask (§3) — the same guard
-                // Feishu applies with `hasMentions`.
+                // Mentioning only other people is targeted discussion, never an ask (§3) — the same guard Feishu applies with
+                // `hasMentions`.
                 !addressesSomeone &&
                 threadParticipants.admitsBareMessage(threadKey(teamId, event.channel, event.thread_ts))) {
                 routed = {};
@@ -303,16 +324,11 @@ export function slackChannel(options) {
             }
             const targetChannel = routed.channelId ?? event.channel;
             const sameChannel = targetChannel === event.channel;
-            // Answer where asked (participant model §4). Slack has no quote primitive, so the only way to
-            // attach an answer to its question is a thread on it — which then IS the place, and carries the
-            // memory (§5). Native streaming additionally REQUIRES a thread, but the shape does not depend on
-            // the renderer: `classic` attaches its answer the same way.
+            // Answer where asked (participant model §4).
             const defaultThread = event.thread_ts ?? event.ts;
             const threadTs = routed.threadTs === null ? undefined : (routed.threadTs ?? (sameChannel ? defaultThread : undefined));
             const defaultSession = threadKey(teamId, event.channel, rootTs);
-            // Explicit user stop: a control action, never a turn — it must not queue behind the run it
-            // stops. Match the bare word after stripping the bot mention; record the logical id so a Slack
-            // redelivery doesn't double-abort or double-notify.
+            // Explicit user stop: a control action, never a turn — it must not queue behind the run it stops.
             if (isStopText(stripSlackMentions(event.text ?? ""))) {
                 seen.add(logicalId);
                 const target = { channelId: event.channel, threadTs: event.thread_ts };
@@ -341,32 +357,15 @@ export function slackChannel(options) {
                 threadTitle: threadTitle || undefined,
                 fileIds,
             }, true);
-            // Answering inside a GROUP thread makes the agent a participant of it, which is what lets the
-            // NEXT bare message address it without a mention.
-            //
-            // `group` excludes DMs, whose `threadTs` is always defined (the answer opens its assistant
-            // thread) and which no rule could ever read — safe because it is structural: a channel never
-            // becomes a DM.
-            //
-            // The two `routed` conditions keep the record describing what it claims. `session` undefined: the
-            // flag asserts "the agent answered into THIS thread's session", so a route supplying its own
-            // would record participation in a memory that never held the turn. `threadTs` undefined: a route
-            // can send the answer to a DIFFERENT thread, where the asker never spoke — recording them there
-            // would invent a participant. Feishu carries the same two conditions for the same reasons.
-            //
-            // Recorded only once the intent is durable: `submit` can throw, and a redelivery must still see
-            // the thread as the agent has actually left it.
+            // Answering inside a GROUP thread makes the agent a participant of it, which is what lets the NEXT bare message
+            // address it without a mention.
             if (group &&
                 threadTs !== undefined &&
                 sameChannel &&
                 routed.session === undefined &&
                 routed.threadTs === undefined) {
-                // The ASKER counts as heard in this thread too, and both halves are written together so the
-                // record can never say "the agent takes part and nobody has spoken". When the ask is top
-                // level, the answer is what CREATES the thread, so the observation above never ran for it (no
-                // `thread_ts` on the ask) — without this, a thread whose root is a human would not count them,
-                // and a stranger's first bare reply would read as a two-party exchange. `event.user` is
-                // guaranteed here (isSlackHumanMessage). Idempotent when the ask was already in the thread.
+                // The ASKER counts as heard in this thread too, and both halves are written together so the record can never
+                // say "the agent takes part and nobody has spoken".
                 threadParticipants.merge(threadKey(teamId, event.channel, threadTs), {
                     agentSpoke: true,
                     humans: [event.user],
@@ -390,14 +389,14 @@ export function slackChannel(options) {
             const channelId = event.channel;
             if (!userId || !channelId)
                 return;
-            const teamId = slackTeamId(envelope) ?? authenticatedTeamId;
+            const teamId = slackTeamId(envelope) ?? auth.teamId();
             if (!teamId)
                 return;
             const id = `${teamId}:${userId}`;
             if (welcomed.has(teamId, userId) || welcomeInFlight.has(id))
                 return;
-            // Reserve in-memory so rapid re-opens don't double-post; persist to the durable set only on a
-            // successful post, so a failed post simply retries on the next open.
+            // Reserve in-memory so rapid re-opens don't double-post; persist to the durable set only on a successful post,
+            // so a failed post simply retries on the next open.
             welcomeInFlight.add(id);
             sideTasks.track(api
                 .postMarkdown({ channelId }, body)
@@ -437,7 +436,7 @@ export function slackChannel(options) {
             if (envelope.type !== "event_callback")
                 return new Response(null, { status: 200 });
             try {
-                await waitForAuthentication();
+                await auth.ready();
             }
             catch (error) {
                 log.error(`${label} refusing to ACK an event because Slack authentication is unavailable: ${String(error)}`);

package/dist/channels/sse.d.ts

@@ -1,4 +1,4 @@
-/** Shared SSE response lifecycle for invoke and session observation. Fetch-only, with no Node dependencies. */
+/** Shared SSE response lifecycle for invoke and session observation. */
 /** The remote client's idle watchdog allows three missed heartbeats. */
 export declare const SSE_HEARTBEAT_MS = 30000;
 export declare function sseResponse<T>(events: AsyncIterable<T>, project?: (event: T) => unknown): Response;

package/dist/channels/sse.js

@@ -1,4 +1,4 @@
-/** Shared SSE response lifecycle for invoke and session observation. Fetch-only, with no Node dependencies. */
+/** Shared SSE response lifecycle for invoke and session observation. */
 /** The remote client's idle watchdog allows three missed heartbeats. */
 export const SSE_HEARTBEAT_MS = 30_000;
 const encoder = new TextEncoder();

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

@@ -1,15 +1,6 @@
-/**
- * Telegram's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts):
- * the entry shape, its fold-line rendering, and buffered-attachment selection. Bucketed by Telegram
- * "place" (chat[:thread]), not session: an un-summoned message has no route session, and the flush
- * feeds whatever turn answers that place.
- */
+/** Telegram's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts). */
 import { type ContextBuffer as GenericContextBuffer } from "../kit/context-buffer.ts";
-/** 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. */
+/** One buffered un-summoned message (object identity is the commit key). */
 export interface BufferEntry {
     sender: string;
     body: string;
@@ -22,22 +13,16 @@ export interface BufferEntry {
     /** 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. */
+/**
+ * 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.
- */
+/** The buffered attachment references a summoned turn pulls in with the fold. */
 export declare function collectAttachments(consumed: BufferEntry[], primary: {
     files: Set<string>;
     images: Set<string>;

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

@@ -1,10 +1,5 @@
-/**
- * Telegram's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts):
- * the entry shape, its fold-line rendering, and buffered-attachment selection. Bucketed by Telegram
- * "place" (chat[:thread]), not session: an un-summoned message has no route session, and the flush
- * feeds whatever turn answers that place.
- */
-import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
+/** Telegram's half of the shared context buffer (mechanics + consume protocol: ../kit/context-buffer.ts). */
+import { capBufferedRefs, createContextBuffer as createGenericContextBuffer, } from "../kit/context-buffer.js";
 function bufferLine(e) {
     const meta = [
         e.messageId !== undefined ? `msg ${e.messageId}` : undefined,
@@ -14,15 +9,7 @@ function bufferLine(e) {
         .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.
- */
+/** The buffered attachment references a summoned turn pulls in with the fold. */
 export function collectAttachments(consumed, primary) {
     const refs = (pick, exclude) => {
         const seen = new Set();
@@ -37,13 +24,9 @@ export function collectAttachments(consumed, primary) {
         }
         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),
-    };
+    const files = capBufferedRefs(refs((e) => e.fileIds, primary.files));
+    const images = capBufferedRefs(refs((e) => e.imageIds, primary.images));
+    return { files: files.kept, images: images.kept, skipped: files.skipped + images.skipped };
 }
 function isBufferEntry(e) {
     const t = e;

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

@@ -1,11 +1,12 @@
 /**
  * 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.
+ * Split from parse.ts 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, AgentEvent } from "../../agent.ts";
+import type * as Stream from "effect/Stream";
+import type { PortFailure } from "../../effect-port.ts";
 import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { BufferedRef } from "./context-buffer.ts";
 /** Everything the transport needs to fetch a turn's attachments. */
@@ -29,8 +30,7 @@ export interface TurnAttachments {
     };
 }
 /**
- * Run one turn: resolve its attachments, then stream agent.invoke with the shared busy-wait
- * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
- * primary-attachment failure surfaces as a `failed` event (never a silent drop).
+ * Run one turn: resolve its attachments, then ask the agent (invoke-turn-kit — a primary-attachment
+ * failure surfaces as a `failed` event, never a silent drop).
  */
-export declare function invokeTurn(agent: Agent, session: string, text: string, transport: TurnTransport, attachments: TurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;
+export declare function telegramTurnStream(agent: Agent, session: string, text: string, transport: TurnTransport, attachments: TurnAttachments, busyRetry?: BusyRetry): Stream.Stream<AgentEvent, PortFailure>;

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

@@ -1,5 +1,4 @@
-import { log } from "../../log.js";
-import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/invoke-turn-kit.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, loadBackground, missingAttachmentsNote, turnStream, } from "../kit/invoke-turn-kit.js";
 import { resolveFiles, resolveImages } from "./telegram-api.js";
 /** Appended to the prompt (not the system prompt): the channel owns Telegram-HTML formatting. */
 const HTML_INSTRUCTION = "\n\n(Format your reply in Telegram-supported HTML — <b> <i> <u> <s> <code> <pre> <a href> — not Markdown.)";
@@ -19,33 +18,14 @@ async function resolveTurnAttachments(t, attachments) {
     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 missingNote = missingAttachmentsNote(lost + buffered.skipped);
+    const backgroundImages = await loadBackground(buffered.images, (ref) => resolveImages(api, botToken, [ref.id]), {
+        label: "[telegram]",
+        what: "photo",
+    });
+    const backgroundFiles = await loadBackground(buffered.files, (ref) => resolveFiles(api, botToken, [ref.id], chatId, filesDir), { label: "[telegram]", what: "attachment" });
+    const bufferedImages = backgroundImages.loaded.flatMap(({ value }) => value ?? []);
+    const bufferedFiles = backgroundFiles.loaded.flatMap(({ ref, value }) => (value ?? []).map((file) => ({ file, ref })));
+    const missingNote = missingAttachmentsNote(backgroundImages.lost + backgroundFiles.lost + buffered.skipped);
     // 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
@@ -62,19 +42,20 @@ async function resolveTurnAttachments(t, attachments) {
     };
 }
 /**
- * Run one turn: resolve its attachments, then stream agent.invoke with the shared busy-wait
- * (invoke-turn-kit — `onCompleted` is the durable-commit point; see streamTurnWithBusyRetry). A
- * primary-attachment failure surfaces as a `failed` event (never a silent drop).
+ * Run one turn: resolve its attachments, then ask the agent (invoke-turn-kit — a primary-attachment
+ * failure surfaces as a `failed` event, never a silent drop).
  */
-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 };
-    yield* streamTurnWithBusyRetry(agent, { session }, prompt, { label: "[telegram]", onCompleted, busyRetry });
+export function telegramTurnStream(agent, session, text, transport, attachments, busyRetry = DEFAULT_BUSY_RETRY) {
+    return turnStream({
+        agent,
+        label: "[telegram]",
+        busyRetry,
+        resolve: () => resolveTurnAttachments(transport, attachments),
+        turn: (resolved) => ({
+            scope: { session },
+            prompt: { text: `${text}${resolved.promptSuffix}${HTML_INSTRUCTION}`, images: resolved.images },
+        }),
+        // A Bot API download that failed may simply succeed on the redelivery.
+        retryableLoadFailure: () => true,
+    });
 }