@fastagent-sh/fastagent 0.19.0 → 0.21.0

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

@@ -12,6 +12,16 @@ export interface DownloadedSlackFile {
     name: string;
     size: number;
 }
+export interface UploadedSlackFile {
+    id: string;
+    name: string;
+}
+export interface SentSlackMessage {
+    /** The first message's ts (a long Markdown body continues in further messages). */
+    ts: string;
+    /** Where it landed: a user-id target (`U…`) resolves to that user's DM channel (`D…`). */
+    channelId: string;
+}
 export declare class SlackApiError extends Error {
     readonly method: string;
     readonly status: number;
@@ -24,7 +34,7 @@ export declare class SlackApiError extends Error {
  * internal, and timeout failures are ambiguous: Slack may already have created the stream. */
 export declare function isSlackNativeUnavailable(error: unknown): boolean;
 export interface SlackApiOptions {
-    botToken: string | (() => Promise<string>);
+    botToken: string;
     baseUrl?: string;
 }
 export interface SlackApi {
@@ -38,7 +48,9 @@ export interface SlackApi {
     updateMessage(channelId: string, ts: string, text: string): Promise<void>;
     updateMarkdown(channelId: string, ts: string, markdown: string): Promise<void>;
     deleteMessage(channelId: string, ts: string): Promise<void>;
-    sendMarkdown(target: SlackTarget, markdown: string): Promise<string | undefined>;
+    /** Post standard Markdown, split under Slack's limit. `target.channelId` may be a user id: Slack
+     *  then opens (or reuses) the app's DM with that user, and the result names it. */
+    sendMarkdown(target: SlackTarget, markdown: string): Promise<SentSlackMessage>;
     startStream(target: SlackTarget, markdown?: string): Promise<string>;
     appendStream(channelId: string, ts: string, markdown: string): Promise<void>;
     stopStream(channelId: string, ts: string, markdown?: string): Promise<void>;
@@ -49,6 +61,12 @@ export interface SlackApi {
     fileInfo(fileId: string): Promise<SlackFile>;
     fetchImage(file: SlackFile): Promise<ImageRef>;
     fetchFile(file: SlackFile, channelId: string, filesDir: string): Promise<DownloadedSlackFile>;
+    /** Upload one local file into a channel/thread through Slack's external-upload protocol
+     *  (getUploadURLExternal → bytes → completeUploadExternal). */
+    uploadFile(target: SlackTarget, path: string, options?: {
+        title?: string;
+        initialComment?: string;
+    }): Promise<UploadedSlackFile>;
 }
 /** Split a Slack text/Markdown field at a code-point-safe boundary, preferring a newline. */
 export declare function chunkSlackText(text: string, maxPoints?: number): string[];

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

@@ -1,13 +1,14 @@
-/** Slack Web API transport: one JSON pipeline plus authenticated, capped private-file downloads. */
-import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+/** Slack Web API transport: one JSON pipeline, authenticated capped private-file downloads, and the
+ * external-upload protocol. */
+import { mkdir, open, stat, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { attachmentPath } from "../kit/attachment-path.js";
 import { codePointPrefix } from "../kit/text.js";
 const API_TIMEOUT_MS = 30_000;
-const DOWNLOAD_TIMEOUT_MS = 120_000;
+const FILE_TRANSFER_TIMEOUT_MS = 120_000;
 const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
 const RETRIES = 3;
 const MAX_RETRY_AFTER_S = 30;
-const MAX_REDIRECTS = 3;
 /** Slack's standard-Markdown fields cap each call at 12,000 characters. Keep headroom for
  * code-fence balancing and future server-side transformations. */
 const SLACK_MAX_MARKDOWN = 10_000;
@@ -95,11 +96,6 @@ export function chunkSlackMarkdown(markdown, maxPoints = SLACK_MAX_MARKDOWN) {
     }
     return output;
 }
-function safeFileName(file) {
-    const raw = file.name ?? file.title ?? file.id ?? "file";
-    const safe = raw.replace(/[/\\]/g, "_").replace(/^\.+/, "_") || "file";
-    return `${file.id ?? "slack"}-${safe}`;
-}
 function fileDownloadUrl(file) {
     if (file.file_access === "check_file_info")
         throw new Error(`Slack file ${file.id ?? "(unknown)"} is not ready`);
@@ -138,25 +134,17 @@ async function readBytesCapped(response) {
     }
     return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
 }
+/** A rotating token (an app created by a release up to 0.20) would work for up to 12 hours and then
+ *  fail as `token_expired`, far from the cause — refuse it where the token enters, on both paths. */
+function assertLongLivedBotToken(botToken) {
+    if (botToken.startsWith("xoxe.")) {
+        throw new Error("got a rotating Slack bot token (xoxe.…); this release uses a long-lived xoxb- token — " +
+            'create a new app (docs/slack.md → "Upgrading from a rotating-token app")');
+    }
+}
 export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" }) {
+    assertLongLivedBotToken(botToken);
     const apiBase = baseUrl.replace(/\/$/, "");
-    const configuredOrigin = new URL(apiBase).origin;
-    const currentToken = typeof botToken === "string" ? async () => botToken : botToken;
-    const trustedDownloadUrl = (value) => {
-        const url = new URL(value);
-        const host = url.hostname.toLowerCase();
-        const slackHost = host === "slack-files.com" ||
-            host.endsWith(".slack-files.com") ||
-            host === "slack.com" ||
-            host.endsWith(".slack.com") ||
-            host === "slack-edge.com" ||
-            host.endsWith(".slack-edge.com");
-        if (!slackHost && url.origin !== configuredOrigin)
-            throw new Error(`refusing non-Slack file URL host ${host}`);
-        if (url.protocol !== "https:" && url.origin !== configuredOrigin)
-            throw new Error("refusing non-HTTPS Slack file URL");
-        return url;
-    };
     const call = async (method, body, httpMethod = "POST") => {
         const url = new URL(`${apiBase}/${method}`);
         if (httpMethod === "GET") {
@@ -169,11 +157,10 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             let response;
             let raw;
             try {
-                const token = await currentToken();
                 response = await fetch(url, {
                     method: httpMethod,
                     headers: {
-                        authorization: `Bearer ${token}`,
+                        authorization: `Bearer ${botToken}`,
                         ...(httpMethod === "POST" ? { "content-type": "application/json; charset=utf-8" } : {}),
                     },
                     ...(httpMethod === "POST" ? { body: JSON.stringify(body) } : {}),
@@ -211,36 +198,38 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             throw new SlackApiError(method, response.status, detail, data.error);
         }
     };
+    // Slack owns both halves of this download: the URL comes from its own files.info response, and it
+    // documents url_private as taking our bearer token. Where that URL leads is Slack's call; whether a
+    // redirect hop still carries the token is fetch's, which drops the header cross-origin.
     const download = async (file) => {
-        let url = trustedDownloadUrl(fileDownloadUrl(file));
-        for (let redirect = 0;; redirect++) {
-            let response;
-            try {
-                const token = await currentToken();
-                response = await fetch(url, {
-                    headers: { authorization: `Bearer ${token}` },
-                    redirect: "manual",
-                    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-                });
-            }
-            catch (error) {
-                throw new SlackApiError("file download", 0, String(error), undefined, { cause: error });
-            }
-            if (response.status >= 300 && response.status < 400) {
-                const location = response.headers.get("location");
-                if (!location || redirect >= MAX_REDIRECTS) {
-                    throw new SlackApiError("file download", response.status, "invalid or excessive redirect");
-                }
-                await response.body?.cancel().catch(() => { });
-                url = trustedDownloadUrl(new URL(location, url).toString());
-                continue;
-            }
-            if (!response.ok) {
-                const detail = codePointPrefix(await response.text().catch(() => ""), 300) || "file bytes were rejected";
-                throw new SlackApiError("file download", response.status, detail);
-            }
-            return { bytes: await readBytesCapped(response), contentType: response.headers.get("content-type") ?? undefined };
+        let response;
+        try {
+            response = await fetch(fileDownloadUrl(file), {
+                headers: { authorization: `Bearer ${botToken}` },
+                signal: AbortSignal.timeout(FILE_TRANSFER_TIMEOUT_MS),
+            });
         }
+        catch (error) {
+            throw new SlackApiError("file download", 0, String(error), undefined, { cause: error });
+        }
+        if (!response.ok) {
+            const detail = codePointPrefix(await response.text().catch(() => ""), 300) || "file bytes were rejected";
+            throw new SlackApiError("file download", response.status, detail);
+        }
+        return { bytes: await readBytesCapped(response), contentType: response.headers.get("content-type") ?? undefined };
+    };
+    const postMarkdown = async (target, markdown) => {
+        const data = await call("chat.postMessage", {
+            channel: target.channelId,
+            markdown_text: markdown,
+            ...(target.threadTs ? { thread_ts: target.threadTs } : {}),
+            unfurl_links: false,
+            unfurl_media: false,
+        });
+        if (!data.ts)
+            throw new SlackApiError("chat.postMessage", 200, "response carried no ts");
+        // The response's `channel` is what resolves a user-id target to its DM; a channel target echoes itself.
+        return { ts: data.ts, channelId: data.channel ?? target.channelId };
     };
     const api = {
         async authTest() {
@@ -260,16 +249,7 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             return data.ts;
         },
         async postMarkdown(target, markdown) {
-            const data = await call("chat.postMessage", {
-                channel: target.channelId,
-                markdown_text: markdown,
-                ...(target.threadTs ? { thread_ts: target.threadTs } : {}),
-                unfurl_links: false,
-                unfurl_media: false,
-            });
-            if (!data.ts)
-                throw new SlackApiError("chat.postMessage", 200, "response carried no ts");
-            return data.ts;
+            return (await postMarkdown(target, markdown)).ts;
         },
         async updateMessage(channelId, ts, text) {
             try {
@@ -297,10 +277,11 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
         async sendMarkdown(target, markdown) {
             let first;
             for (const chunk of chunkSlackMarkdown(markdown)) {
-                const ts = await api.postMarkdown(target, chunk);
-                first ??= ts;
+                // Continuations go to the resolved channel: a user-id target must not reopen the DM per chunk.
+                const sent = await postMarkdown(first ? { ...target, channelId: first.channelId } : target, chunk);
+                first ??= sent;
             }
-            return first;
+            return first; // chunkSlackMarkdown never yields zero chunks
         },
         async startStream(target, markdown) {
             if (!target.threadTs)
@@ -387,13 +368,59 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
         },
         async fetchFile(file, channelId, filesDir) {
             const { bytes } = await download(file);
-            const dir = join(filesDir, channelId);
+            // The id prefix keeps two same-named uploads in one channel apart.
+            const suggested = `${file.id ?? "slack"}-${file.name ?? file.title ?? file.id ?? "file"}`;
+            const { dir, name, path } = attachmentPath(filesDir, channelId, suggested);
             await mkdir(dir, { recursive: true });
-            const name = safeFileName(file);
-            const path = join(dir, name);
             await writeFile(path, bytes);
             return { path, name, size: bytes.byteLength };
         },
+        async uploadFile(target, path, options = {}) {
+            const info = await stat(path);
+            if (!info.isFile())
+                throw new Error(`${path} is not a regular file`);
+            const name = basename(path);
+            const upload = await call("files.getUploadURLExternal", {
+                filename: name,
+                length: info.size,
+            });
+            if (!upload.upload_url || !upload.file_id) {
+                throw new SlackApiError("files.getUploadURLExternal", 200, "response carried no upload_url/file_id");
+            }
+            // Where upload_url points is Slack's call, as with url_private above; the bytes carry no token.
+            const handle = await open(path, "r");
+            let response;
+            try {
+                response = await fetch(upload.upload_url, {
+                    method: "POST",
+                    headers: { "content-type": "application/octet-stream" },
+                    body: handle.readableWebStream(),
+                    signal: AbortSignal.timeout(FILE_TRANSFER_TIMEOUT_MS),
+                    // Required by Node fetch for a streaming request body; not part of the browser RequestInit type.
+                    duplex: "half",
+                });
+            }
+            catch (error) {
+                throw new SlackApiError("file upload", 0, String(error), undefined, { cause: error });
+            }
+            finally {
+                await handle.close().catch(() => { });
+            }
+            if (!response.ok) {
+                const detail = codePointPrefix(await response.text().catch(() => ""), 300) || "file bytes were rejected";
+                throw new SlackApiError("file upload", response.status, detail);
+            }
+            // At-least-once: if Slack commits this call but the response is lost, a retry may post a
+            // duplicate. Retrying here would hide that ambiguity, so only an explicit agent/user retry
+            // crosses this final side-effect boundary.
+            await call("files.completeUploadExternal", {
+                files: [{ id: upload.file_id, title: options.title ?? name }],
+                channel_id: target.channelId,
+                ...(options.initialComment ? { initial_comment: options.initialComment } : {}),
+                ...(target.threadTs ? { thread_ts: target.threadTs } : {}),
+            });
+            return { id: upload.file_id, name };
+        },
     };
     return api;
 }

package/dist/channels/slack/slack.d.ts

@@ -8,16 +8,6 @@ export interface SlackChannelOptions {
     botToken: string;
     /** App signing secret used to verify the raw Events API request body. */
     signingSecret: string;
-    /** Rotating OAuth credentials. Omit all four only for a manually managed long-lived bot token. */
-    botRefreshToken?: string;
-    clientId?: string;
-    clientSecret?: string;
-    botTokenExpiresAt?: number;
-    /** `context` (default) subscribes to group message streams, which is what lets the channel HEAR a
-     * thread: bare replies are then admitted by the participation rule (design/participant-model.md §3),
-     * and other discussion is buffered. `mentions` answers only app_mention plus DMs for an explicit
-     * least-privilege setup. */
-    groupBehavior?: "context" | "mentions";
     /** `native` (default) uses Slack Agent streams for threaded replies. Its inline tool traces carry a
      * bounded summary of each call's first argument and cannot be retracted, so they stay in the
      * delivered message beside the answer. `classic` retains the compatibility renderer based on one

package/dist/channels/slack/slack.js

@@ -1,28 +1,32 @@
 /** First-party Slack HTTP Events API channel: signed ingress, durable turns/context, files, and edited previews. */
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createHmac } 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 { secretEquals } from "../secret.js";
 import { createSeenRing } from "../kit/seen.js";
+import { signatureIsFresh } from "../kit/signature.js";
 import { createThreadParticipants } from "../kit/thread-participants.js";
 import { createTaskTracker } from "../kit/tasks.js";
 import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop, isStopText } from "../kit/stop-command.js";
 import { codePointPrefix } from "../kit/text.js";
-import { createTurnQueue } from "../kit/turn-queue.js";
+import { createTurnRunner } from "../kit/turn-runner.js";
 import { createTurnStore } from "../kit/turn-store.js";
-import { createSlackBotTokenProvider } from "./bot-auth.js";
+import { discussionBlock } from "../kit/context-buffer.js";
 import { collectSlackBufferedFiles, createSlackContextBuffer } from "./context-buffer.js";
 import { invokeSlackTurn } 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 { 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;
-const MAX_TURN_ATTEMPTS = 3;
+/** 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. */
 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.";
@@ -45,15 +49,12 @@ function isStoredSlackTurn(value) {
 }
 /** Verify Slack's v0 HMAC over the exact raw body and reject timestamps outside the replay window. */
 export function verifySlackSignature(signingSecret, timestamp, signature, rawBody, nowMs = Date.now()) {
-    if (!/^\d+$/.test(timestamp) || !/^v0=[a-f0-9]{64}$/i.test(signature))
+    if (!/^v0=[a-f0-9]{64}$/i.test(signature))
         return false;
-    const seconds = Number(timestamp);
-    if (!Number.isSafeInteger(seconds) || Math.abs(Math.floor(nowMs / 1000) - seconds) > MAX_SIGNATURE_AGE_S)
+    if (!signatureIsFresh(timestamp, MAX_SIGNATURE_AGE_S, nowMs))
         return false;
     const expected = `v0=${createHmac("sha256", signingSecret).update(`v0:${timestamp}:${rawBody}`).digest("hex")}`;
-    const actualBytes = Buffer.from(signature);
-    const expectedBytes = Buffer.from(expected);
-    return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+    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. */
@@ -62,19 +63,7 @@ function messageRefOf(turnId) {
     return parts.length === 3 && parts[1] && parts[2] ? { channelId: parts[1], ts: parts[2] } : undefined;
 }
 export function slackChannel(options) {
-    const { botToken, signingSecret, botRefreshToken, clientId, clientSecret, botTokenExpiresAt, groupBehavior = "context", rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
-    // The participant model derives placement instead of selecting it: Slack has no quote primitive, so
-    // answering in place means answering in a thread on the ask, whichever renderer draws it. An
-    // upgraded workspace still passing one of the removed modes would otherwise start fine and silently
-    // get a different placement AND a different memory boundary.
-    const removedModes = ["directMessageSession", "groupMessageSession"].filter((name) => options[name] !== undefined);
-    if (removedModes.length > 0) {
-        throw new Error(`slackChannel no longer accepts ${removedModes.join(" / ")}: an answer goes in a thread on the ask, and ` +
-            "that thread is the session — see docs/design/participant-model.md");
-    }
-    if (!["context", "mentions"].includes(groupBehavior)) {
-        throw new Error('slackChannel groupBehavior must be "context" or "mentions"');
-    }
+    const { botToken, signingSecret, rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
     if (!["native", "classic"].includes(rendering)) {
         throw new Error('slackChannel rendering must be "native" or "classic"');
     }
@@ -93,16 +82,8 @@ export function slackChannel(options) {
         const formatError = onError ?? defaultErrorMessage;
         const stateHome = join(stateRoot, "channels", "slack");
         ensureStateHome(stateHome);
-        const currentBotToken = createSlackBotTokenProvider({
-            statePath: join(stateHome, "bot-auth.json"),
-            botToken,
-            botRefreshToken,
-            clientId,
-            clientSecret,
-            botTokenExpiresAt,
-            apiBaseUrl,
-        });
-        const api = createSlackApi({ botToken: currentBotToken, baseUrl: apiBaseUrl });
+        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";
@@ -134,6 +115,9 @@ export function slackChannel(options) {
                 });
             });
         };
+        // 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 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
@@ -149,64 +133,66 @@ export function slackChannel(options) {
             order: (a, b) => a.seq - b.seq,
         });
         const decide = route ?? defaultSlackRoute;
-        const toStored = (turn) => {
-            const { previewTs: _preview, nativeQueueStatus: _status, ...intent } = turn;
-            return { ...intent, attempts: 0 };
-        };
         const targetOf = (turn) => ({
             channelId: turn.channelId,
             threadTs: turn.threadTs,
             recipientUserId: turn.requesterUserId,
             recipientTeamId: turn.teamId,
         });
-        const notices = new Map();
-        const queue = createTurnQueue({
+        const notifyDropped = (turn) => {
+            const target = targetOf(turn);
+            if (turn.nativeQueueStatus)
+                void api.setThreadStatus(target, "").catch(() => { });
+            void settleSlackPreview(api, target, turn.previewTs, "⚠️ I couldn’t complete an earlier request — please ask again.").catch((error) => log.warn(`${label} could not notify a dropped turn: ${String(error)}`));
+        };
+        const runner = createTurnRunner({
             label,
+            store,
+            buffer,
+            seen,
+            toStored: ({ previewTs: _preview, nativeQueueStatus: _status, ...intent }) => ({ ...intent, attempts: 0 }),
+            fromStored: ({ attempts: _attempts, ...intent }) => ({ ...intent }),
+            bufferKey: (turn) => turn.bufferKey,
+            where: (turn) => `channel=${turn.channelId}`,
             onQueuedBehind(turn) {
                 const nativeDmStatus = rendering === "native" && turn.threadTs && turn.channelId.startsWith("D");
                 if (nativeDmStatus)
                     turn.nativeQueueStatus = true;
-                notices.set(turn.id, authentication
-                    .then(() => nativeDmStatus
-                    ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
-                    : api.postMessage(targetOf(turn), QUEUED_PLACEHOLDER).then((ts) => {
-                        turn.previewTs = ts;
-                    }))
-                    .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)));
+                return {
+                    done: authentication
+                        .then(() => nativeDmStatus
+                        ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
+                        : api.postMessage(targetOf(turn), QUEUED_PLACEHOLDER).then((ts) => {
+                            turn.previewTs = ts;
+                        }))
+                        .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)),
+                };
             },
-            run: async (turn) => {
-                await notices.get(turn.id);
-                notices.delete(turn.id);
+            // 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.
+            beforeRun: async (turn) => {
                 try {
                     await authentication;
+                    return true;
                 }
                 catch (error) {
-                    // Leave the intent untouched. A fixed token + restart replays it; running now would execute an
-                    // Agent turn whose only customer-facing transport is known to be unavailable.
                     log.error(`${label} deferring durable turn ${turn.id} because Slack authentication failed: ${String(error)}`);
-                    return;
+                    return false;
                 }
-                const attempt = store.startAttempt(turn.id, MAX_TURN_ATTEMPTS);
-                if (attempt === "exceeded") {
-                    notifyDropped(turn);
-                    return;
+            },
+            onDeferred: (turn) => {
+                if (turn.nativeQueueStatus) {
+                    void api
+                        .setThreadStatus(targetOf(turn), "is delayed by a temporary system issue and will retry after restart…")
+                        .catch((error) => log.warn(`${label} could not update a deferred Agent status: ${String(error)}`));
                 }
-                if (attempt === "defer") {
-                    if (turn.nativeQueueStatus) {
-                        void api
-                            .setThreadStatus(targetOf(turn), "is delayed by a temporary system issue and will retry after restart…")
-                            .catch((error) => log.warn(`${label} could not update a deferred Agent status: ${String(error)}`));
-                    }
-                    else if (turn.previewTs) {
-                        void settleSlackPreview(api, targetOf(turn), turn.previewTs, DEFERRED_PLACEHOLDER).catch((error) => log.warn(`${label} could not update a deferred queue preview: ${String(error)}`));
-                    }
-                    return;
+                else if (turn.previewTs) {
+                    void settleSlackPreview(api, targetOf(turn), turn.previewTs, DEFERRED_PLACEHOLDER).catch((error) => log.warn(`${label} could not update a deferred queue preview: ${String(error)}`));
                 }
-                const startedAt = Date.now();
-                log.info(`${label} turn start: turn=${turn.id} session=${turn.session} channel=${turn.channelId}`);
-                const { text: recent, consumed } = buffer.peek(turn.bufferKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${turn.baseText}` : turn.baseText;
-                const buffered = collectSlackBufferedFiles(consumed, new Set(turn.fileIds));
+            },
+            notifyDropped,
+            execute: async (turn, discussion, onCompleted) => {
                 const messageRef = messageRefOf(turn.id);
                 const reaction = reactionEmojis && messageRef
                     ? await startSlackReaction({
@@ -218,47 +204,25 @@ export function slackChannel(options) {
                     })
                     : undefined;
                 try {
-                    await streamSlackReply(invokeSlackTurn(agent, turn.session, prompt, { api, channelId: turn.channelId, filesDir: join(stateHome, "files"), label }, { primaryFileIds: turn.fileIds, buffered }, () => {
-                        store.remove(turn.id);
-                        buffer.commit(turn.bufferKey, consumed);
-                    }), api, targetOf(turn), formatError, {
+                    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,
                     });
-                    log.info(`${label} turn done: turn=${turn.id} session=${turn.session} (${Date.now() - startedAt}ms)`);
-                    await reaction?.complete();
                 }
                 catch (error) {
-                    log.error(`${label} turn failed: turn=${turn.id} session=${turn.session}: ${String(error)}`);
                     await reaction?.remove();
+                    throw error;
                 }
-                finally {
-                    store.remove(turn.id);
-                }
+                await reaction?.complete();
             },
         });
-        const notifyDropped = (turn) => {
-            const target = targetOf(turn);
-            if (turn.nativeQueueStatus)
-                void api.setThreadStatus(target, "").catch(() => { });
-            void settleSlackPreview(api, target, turn.previewTs, "⚠️ I couldn’t complete an earlier request — please ask again.").catch((error) => log.warn(`${label} could not notify a dropped turn: ${String(error)}`));
-        };
-        const submit = (turn, persist) => {
-            if (persist) {
-                store.add(toStored(turn));
-                seen.add(turn.id);
-            }
-            queue.accept(turn);
-        };
-        const recovered = store.recover();
-        if (recovered.length)
-            log.info(`${label} recovering ${recovered.length} unfinished turn(s) from a prior run`);
-        let seq = recovered.reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
-        for (const { attempts: _attempts, ...intent } of recovered)
-            submit({ ...intent }, false);
+        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.
@@ -285,7 +249,7 @@ export function slackChannel(options) {
             // 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 `groupBehavior` or `route` — see thread-participants.ts. Slack
+            // Structural facts only, never `route` — see thread-participants.ts. Slack
             // adds no delta of its own here; its summon rule is the only consumer.
             if (group && event.thread_ts !== undefined) {
                 threadParticipants.merge(threadKey(teamId, event.channel, event.thread_ts), { humans: [event.user] });
@@ -307,7 +271,6 @@ export function slackChannel(options) {
             // structural: it reads who THIS message addresses, which is the one thing an observation-only
             // store cannot know about someone it has never heard.
             if (!routed &&
-                groupBehavior === "context" &&
                 route === undefined &&
                 group &&
                 event.thread_ts !== undefined &&
@@ -321,7 +284,7 @@ export function slackChannel(options) {
             if (!routed) {
                 if (route === undefined && group && botUserId === undefined && mightBeTheBot)
                     return;
-                if (groupBehavior === "context" && route === undefined && group) {
+                if (route === undefined && group) {
                     const body = slackBufferText(slackMessageText(event));
                     if (body) {
                         const fileIds = slackFileIds(event);
@@ -365,7 +328,7 @@ export function slackChannel(options) {
             const threadTitle = direct && event.thread_ts === undefined
                 ? codePointPrefix(stripSlackMentions(slackMessageText(event), "").replace(/\s+/g, " ").trim(), 80)
                 : undefined;
-            submit({
+            runner.submit({
                 id: logicalId,
                 seq: ++seq,
                 session: routed.session ?? defaultSession,
@@ -410,8 +373,6 @@ export function slackChannel(options) {
                 });
             }
         };
-        // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle.
-        const sideTasks = createTaskTracker();
         // First-run DM welcome: app_home_opened(tab="messages") signals a DM open. Post once per user.
         const welcomeInFlight = new Set();
         const maybeWelcome = (envelope) => {
@@ -486,7 +447,7 @@ export function slackChannel(options) {
             acceptEvent(envelope);
             return new Response(null, { status: 200 });
         };
-        handler.turnsIdle = () => Promise.all([queue.idle(), sideTasks.drain()]).then(() => undefined);
+        handler.turnsIdle = () => Promise.all([runner.idle(), sideTasks.drain()]).then(() => undefined);
         return { "POST /slack": handler };
     };
 }

package/dist/channels/sse.d.ts

@@ -0,0 +1,4 @@
+/** Shared SSE response lifecycle for invoke and session observation. Fetch-only, with no Node dependencies. */
+/** 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;