@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/channels/slack/slack.js

@@ -0,0 +1,451 @@
+/** First-party Slack HTTP Events API channel: signed ingress, durable turns/context, files, and edited previews. */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { log } from "../../log.js";
+import { readBodyCapped } from "../body.js";
+import { text } from "../respond.js";
+import { createSeenRing } from "../seen.js";
+import { createTaskTracker } from "../tasks.js";
+import { ensureStateHome } from "../state.js";
+import { dispatchStop, isStopText } from "../stop-command.js";
+import { codePointPrefix } from "../text.js";
+import { createTurnQueue } from "../turn-queue.js";
+import { createTurnStore } from "../turn-store.js";
+import { createSlackBotTokenProvider } from "./bot-auth.js";
+import { collectSlackBufferedFiles, createSlackContextBuffer } from "./context-buffer.js";
+import { invokeSlackTurn } from "./invoke-turn.js";
+import { createOwnedSlackThreads } from "./owned-threads.js";
+import { defaultSlackRoute, isSlackDirectMessage, isSlackGroupMessage, isSlackHumanMessage, slackBufferText, slackEnvelope, slackFileIds, slackMessageText, slackPlaceKey, slackSenderLabel, slackTeamId, } from "./parse.js";
+import { defaultErrorMessage, settleSlackPreview, streamSlackReply, } from "./preview.js";
+import { resolveReactionEmojis, startSlackReaction } from "./reaction.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;
+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.";
+const DEFAULT_WELCOME = "👋 Hi! I'm an AI agent here to help. Ask a question or describe a task and I'll get to work.";
+function isStoredSlackTurn(value) {
+    const turn = value;
+    return (typeof turn?.id === "string" &&
+        typeof turn.seq === "number" &&
+        typeof turn.session === "string" &&
+        typeof turn.baseText === "string" &&
+        typeof turn.bufferKey === "string" &&
+        typeof turn.teamId === "string" &&
+        typeof turn.channelId === "string" &&
+        (turn.threadTs === undefined || typeof turn.threadTs === "string") &&
+        (turn.requesterUserId === undefined || typeof turn.requesterUserId === "string") &&
+        (turn.threadTitle === undefined || typeof turn.threadTitle === "string") &&
+        Array.isArray(turn.fileIds) &&
+        turn.fileIds.every((id) => typeof id === "string") &&
+        typeof turn.attempts === "number");
+}
+/** 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))
+        return false;
+    const seconds = Number(timestamp);
+    if (!Number.isSafeInteger(seconds) || Math.abs(Math.floor(nowMs / 1000) - seconds) > MAX_SIGNATURE_AGE_S)
+        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);
+}
+/** 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. */
+function messageRefOf(turnId) {
+    const parts = turnId.split(":");
+    return parts.length === 3 && parts[1] && parts[2] ? { channelId: parts[1], ts: parts[2] } : undefined;
+}
+export function slackChannel({ botToken, signingSecret, botRefreshToken, clientId, clientSecret, botTokenExpiresAt, directMessageSession = "threaded", groupMessageSession = "threaded", groupBehavior = "context", rendering = "native", taskDisplay = "plan", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", }) {
+    if (!["continuous", "threaded"].includes(directMessageSession)) {
+        throw new Error('slackChannel directMessageSession must be "continuous" or "threaded"');
+    }
+    if (!["continuous", "threaded"].includes(groupMessageSession)) {
+        throw new Error('slackChannel groupMessageSession must be "continuous" or "threaded"');
+    }
+    if (!["context", "mentions"].includes(groupBehavior)) {
+        throw new Error('slackChannel groupBehavior must be "context" or "mentions"');
+    }
+    if (!["native", "classic"].includes(rendering)) {
+        throw new Error('slackChannel rendering must be "native" or "classic"');
+    }
+    if (!["timeline", "plan", "dense"].includes(taskDisplay)) {
+        throw new Error('slackChannel taskDisplay must be "timeline", "plan", or "dense"');
+    }
+    if (welcome !== false && typeof welcome !== "string") {
+        throw new Error("slackChannel welcome must be a string or false");
+    }
+    const reactionEmojis = resolveReactionEmojis(reactionAck);
+    return ({ agent, stateRoot, control }) => {
+        if (!botToken)
+            throw new Error("slackChannel requires a non-empty botToken (Bot User OAuth Token)");
+        if (!signingSecret)
+            throw new Error("slackChannel requires a non-empty signingSecret (Basic Information → App Credentials)");
+        if (!isAbsolute(stateRoot))
+            throw new Error(`slackChannel requires an absolute ctx.stateRoot, got "${stateRoot}"`);
+        const label = "[slack]";
+        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 });
+        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);
+                });
+            });
+        };
+        const seen = createSeenRing(join(stateHome, "seen.json"), label);
+        const ownedThreads = createOwnedSlackThreads(join(stateHome, "owned-threads.json"), label);
+        const welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
+        const buffer = createSlackContextBuffer(join(stateHome, "buffers.json"), label);
+        const store = createTurnStore(join(stateHome, "turns.json"), {
+            label,
+            isRecord: isStoredSlackTurn,
+            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({
+            label,
+            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)}`)));
+            },
+            run: async (turn) => {
+                await notices.get(turn.id);
+                notices.delete(turn.id);
+                try {
+                    await authentication;
+                }
+                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;
+                }
+                const attempt = store.startAttempt(turn.id, MAX_TURN_ATTEMPTS);
+                if (attempt === "exceeded") {
+                    notifyDropped(turn);
+                    return;
+                }
+                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;
+                }
+                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));
+                const messageRef = messageRefOf(turn.id);
+                const reaction = reactionEmojis && messageRef
+                    ? await startSlackReaction({
+                        api,
+                        channelId: messageRef.channelId,
+                        ts: messageRef.ts,
+                        emojis: reactionEmojis,
+                        label,
+                    })
+                    : 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, {
+                        rendering,
+                        initialPreviewTs: turn.previewTs,
+                        threadTitle: turn.threadTitle,
+                        disclaimer: aiDisclaimer,
+                        taskDisplay,
+                        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();
+                }
+                finally {
+                    store.remove(turn.id);
+                }
+            },
+        });
+        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);
+        const acceptEvent = (envelope) => {
+            const event = envelope.event;
+            if (!isSlackHumanMessage(event))
+                return;
+            if (botUserId && event.user === botUserId)
+                return;
+            const teamId = slackTeamId(envelope) ?? authenticatedTeamId;
+            if (!teamId) {
+                log.warn(`${label} ignored message ${event.ts}: event carried no workspace/enterprise identity`);
+                return;
+            }
+            const logicalId = `${teamId}:${event.channel}:${event.ts}`;
+            if (seen.has(logicalId)) {
+                log.debug(`${label} duplicate logical message ${logicalId} — skipping`);
+                return;
+            }
+            const group = isSlackGroupMessage(event);
+            const direct = isSlackDirectMessage(event);
+            const rootTs = event.thread_ts ?? event.ts;
+            const bufferKey = slackPlaceKey(teamId, event);
+            const threadedGroup = group && groupMessageSession === "threaded";
+            const managedContinuation = groupBehavior === "context" &&
+                route === undefined &&
+                threadedGroup &&
+                event.thread_ts !== undefined &&
+                ownedThreads.has(teamId, event.channel, event.thread_ts);
+            let routed = decide(envelope);
+            const hasUserMention = /<@[A-Z0-9]+>/i.test(event.text ?? "");
+            const structurallyMentionsBot = botUserId !== undefined && (event.text ?? "").includes(`<@${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.
+            if (!routed && route === undefined && group && event.type === "message" && structurallyMentionsBot)
+                routed = {};
+            if (!routed && managedContinuation && event.type !== "app_mention")
+                routed = {};
+            if (!routed) {
+                if (route === undefined && group && botUserId === undefined && hasUserMention)
+                    return;
+                if (groupBehavior === "context" && route === undefined && group) {
+                    const body = slackBufferText(slackMessageText(event));
+                    if (body) {
+                        const fileIds = slackFileIds(event);
+                        buffer.push(bufferKey, {
+                            sender: slackSenderLabel(event),
+                            body,
+                            messageId: event.ts,
+                            replyTo: event.thread_ts,
+                            fileIds: fileIds.length ? fileIds : undefined,
+                        });
+                        seen.add(logicalId);
+                        log.debug(`${label} buffered unsummoned group message ${logicalId} (place ${bufferKey})`);
+                    }
+                }
+                return;
+            }
+            const targetChannel = routed.channelId ?? event.channel;
+            const sameChannel = targetChannel === event.channel;
+            const defaultThread = group
+                ? (event.thread_ts ?? (groupMessageSession === "threaded" ? event.ts : undefined))
+                : (event.thread_ts ?? (directMessageSession === "threaded" ? event.ts : undefined));
+            const threadTs = routed.threadTs === null ? undefined : (routed.threadTs ?? (sameChannel ? defaultThread : undefined));
+            const continuousTopLevel = event.thread_ts === undefined;
+            const defaultSession = direct
+                ? directMessageSession === "continuous" && continuousTopLevel
+                    ? `slack:${teamId}:${event.channel}`
+                    : `slack:${teamId}:${event.channel}:${rootTs}`
+                : groupMessageSession === "continuous" && continuousTopLevel
+                    ? `slack:${teamId}:${event.channel}`
+                    : `slack:${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.
+            if (isStopText((event.text ?? "").replace(/<@[A-Z0-9]+>/gi, " "))) {
+                seen.add(logicalId);
+                const target = { channelId: event.channel, threadTs: event.thread_ts };
+                sideTasks.track(dispatchStop(control, routed.session ?? defaultSession, label)
+                    .then((feedback) => api.postMessage(target, feedback).then(() => undefined))
+                    .catch((error) => log.warn(`${label} stop feedback failed: ${String(error)}`)));
+                return;
+            }
+            const fileIds = slackFileIds(event);
+            const baseText = routed.text ?? slackEnvelope(envelope);
+            if (!baseText.trim() && fileIds.length === 0)
+                return;
+            const threadTitle = direct && event.thread_ts === undefined
+                ? codePointPrefix(slackMessageText(event)
+                    .replace(/<@[A-Z0-9]+>/gi, "")
+                    .replace(/\s+/g, " ")
+                    .trim(), 80)
+                : undefined;
+            // Match Feishu/Lark ownership in context mode: only a top-level summon that creates an
+            // Agent-managed thread owns the root. Mentioning the Agent inside an existing human thread
+            // answers once without adopting it; mention-only mode never consumes ownership state.
+            if (groupBehavior === "context" &&
+                route === undefined &&
+                threadedGroup &&
+                event.thread_ts === undefined &&
+                sameChannel) {
+                ownedThreads.add(teamId, event.channel, rootTs);
+            }
+            submit({
+                id: logicalId,
+                seq: ++seq,
+                session: routed.session ?? defaultSession,
+                baseText,
+                bufferKey,
+                teamId,
+                channelId: targetChannel,
+                threadTs,
+                requesterUserId: event.user,
+                threadTitle: threadTitle || undefined,
+                fileIds,
+            }, true);
+        };
+        // 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) => {
+            if (welcome === false)
+                return;
+            const body = welcome.trim();
+            if (!body)
+                return;
+            const event = envelope.event;
+            if (!event)
+                return;
+            if (event.type !== "app_home_opened" || event.tab !== "messages")
+                return;
+            const userId = event.user;
+            const channelId = event.channel;
+            if (!userId || !channelId)
+                return;
+            const teamId = slackTeamId(envelope) ?? authenticatedTeamId;
+            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.
+            welcomeInFlight.add(id);
+            sideTasks.track(api
+                .postMarkdown({ channelId }, body)
+                .then(() => {
+                welcomed.add(teamId, userId);
+                log.info(`${label} sent first-run welcome to ${id}`);
+            })
+                .catch((error) => log.warn(`${label} could not send first-run welcome (retries on next open): ${String(error)}`))
+                .finally(() => {
+                welcomeInFlight.delete(id);
+            }));
+        };
+        const handler = async (request) => {
+            if (request.method !== "POST")
+                return text("POST only\n", 405);
+            const body = await readBodyCapped(request, MAX_EVENT_BYTES);
+            if ("tooLarge" in body)
+                return text("payload too large\n", 413);
+            const timestamp = request.headers.get("x-slack-request-timestamp") ?? "";
+            const signature = request.headers.get("x-slack-signature") ?? "";
+            if (!verifySlackSignature(signingSecret, timestamp, signature, body.text)) {
+                log.warn(`${label} rejected an event with an invalid/stale X-Slack-Signature`);
+                return text("invalid signature\n", 401);
+            }
+            let envelope;
+            try {
+                envelope = JSON.parse(body.text);
+                if (typeof envelope !== "object" || envelope === null)
+                    throw new Error("not an object");
+            }
+            catch {
+                return text("invalid json\n", 400);
+            }
+            if (envelope.type === "url_verification" && typeof envelope.challenge === "string") {
+                return Response.json({ challenge: envelope.challenge });
+            }
+            if (envelope.type !== "event_callback")
+                return new Response(null, { status: 200 });
+            try {
+                await waitForAuthentication();
+            }
+            catch (error) {
+                log.error(`${label} refusing to ACK an event because Slack authentication is unavailable: ${String(error)}`);
+                return text("slack authentication unavailable\n", 503);
+            }
+            maybeWelcome(envelope);
+            acceptEvent(envelope);
+            return new Response(null, { status: 200 });
+        };
+        handler.turnsIdle = () => Promise.all([queue.idle(), sideTasks.drain()]).then(() => undefined);
+        return { "POST /slack": handler };
+    };
+}

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

@@ -0,0 +1,5 @@
+export interface WelcomedUsers {
+    has(teamId: string, userId: string): boolean;
+    add(teamId: string, userId: string): void;
+}
+export declare function createWelcomedUsers(path: string, label?: string): WelcomedUsers;

package/dist/channels/slack/welcomed.js

@@ -0,0 +1,32 @@
+/** Durable set of users who have already received the first-run DM welcome, so it is sent at most once. */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "../state.js";
+function key(teamId, userId) {
+    return `${teamId}:${userId}`;
+}
+export function createWelcomedUsers(path, label = "[slack]") {
+    const raw = loadStateFile(path);
+    let ids = new Set();
+    if (raw !== undefined) {
+        if (Array.isArray(raw) && raw.every((id) => typeof id === "string")) {
+            ids = new Set(raw);
+        }
+        else {
+            log.warn(`${label} unexpected shape in ${path} — starting with no welcomed users`);
+        }
+    }
+    return {
+        has(teamId, userId) {
+            return ids.has(key(teamId, userId));
+        },
+        add(teamId, userId) {
+            const id = key(teamId, userId);
+            if (ids.has(id))
+                return;
+            const next = new Set(ids);
+            next.add(id);
+            saveStateFile(path, [...next]);
+            ids = next;
+        },
+    };
+}

package/dist/channels/state.js

@@ -2,9 +2,9 @@
  * Durable channel state for a SINGLE-PROCESS deployment (the supported production shape — no
  * cross-instance locking; two processes must not share a state dir). Small JSON files, written
  * atomically (tmp + rename), so a crash leaves the previous version on disk, never a torn file.
- * Writes are synchronous: the files are KB-sized and a write that completes BEFORE the webhook 200
- * is what makes the state actually durable (an ACKed webhook delivery is not redelivered).
- * Channel-neutral: every stateful channel (telegram, Feishu; Lark compatibility) derives its home from the ctx state root
+ * Writes are synchronous: the files are KB-sized and a write that completes BEFORE the transport ACK
+ * is what makes the state actually durable (an ACKed delivery is not redelivered).
+ * Channel-neutral: every stateful channel (Telegram, Feishu/Lark, Slack) derives its home from the ctx state root
  * and persists through these three primitives.
  *
  * Failure split: a CORRUPT file (bad JSON) degrades visibly — log.warn + start empty — because channel

package/dist/channels/stop-command.d.ts

@@ -0,0 +1,6 @@
+import { type SessionControl } from "../session.ts";
+/** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
+export declare function isStopText(text: string): boolean;
+/** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;
+ *  full details go to the operator log. */
+export declare function dispatchStop(control: SessionControl | undefined, session: string, label: string): Promise<string>;

package/dist/channels/stop-command.js

@@ -0,0 +1,36 @@
+/**
+ * SHARED user-facing stop command: the chat channels (telegram, feishu/lark, slack) map an explicit
+ * "stop" ask onto the session control plane's `abort`. Policy decisions (design session-control.md
+ * §15): the stop message is a CONTROL ACTION, never a turn (it must not queue behind the run it
+ * stops); only the ACTIVE run is aborted — queued durable turns are independent asks and keep their
+ * at-least-once floor; and the hub stays gated by `config.sessionControl`, so without it the command
+ * degrades to a visible "not enabled" notice, never a silent ignore.
+ */
+import { log } from "../log.js";
+import { NO_ACTIVE_RUN_CODE } from "../session.js";
+/** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
+export function isStopText(text) {
+    return /^(stop|cancel)[.!]?$/i.test(text.trim());
+}
+const STOPPED_NOTICE = "⏹ Stopped.";
+const NOTHING_RUNNING_NOTICE = "Nothing is running.";
+const STOP_UNAVAILABLE_NOTICE = "⚠️ Stop isn't enabled on this deployment (set sessionControl: true in fastagent.config).";
+/** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;
+ *  full details go to the operator log. */
+export async function dispatchStop(control, session, label) {
+    if (!control)
+        return STOP_UNAVAILABLE_NOTICE;
+    try {
+        const result = await control.dispatch(session, { type: "abort" });
+        if (result.ok)
+            return STOPPED_NOTICE;
+        if (result.error.code === NO_ACTIVE_RUN_CODE)
+            return NOTHING_RUNNING_NOTICE;
+        log.warn(`${label} stop dispatch rejected for ${session}: ${result.error.code} — ${result.error.message}`);
+        return `⚠️ Could not stop (${result.error.code}).`;
+    }
+    catch (error) {
+        log.warn(`${label} stop dispatch failed for ${session}: ${String(error)}`);
+        return "⚠️ Could not stop — see the server logs.";
+    }
+}

package/dist/channels/tasks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SHARED fire-and-forget side-task tracking. Channels launch work off the request path (stop
+ * feedback, DM welcomes) that must not block the transport ACK but MUST be drained on shutdown
+ * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
+ * handling stays with the caller: track() only guarantees the drain sees the task settle.
+ */
+export interface TaskTracker {
+    /** Track one task. The caller keeps its own `.catch` — rejections must already be handled. */
+    track(task: Promise<unknown>): void;
+    /** Resolves when every currently-tracked task has settled. */
+    drain(): Promise<void>;
+}
+export declare function createTaskTracker(): TaskTracker;

package/dist/channels/tasks.js

@@ -0,0 +1,10 @@
+export function createTaskTracker() {
+    const tasks = new Set();
+    return {
+        track(task) {
+            tasks.add(task);
+            void task.finally(() => tasks.delete(task)).catch(() => { }); // the caller's chain owns the error
+        },
+        drain: () => Promise.all(tasks).then(() => undefined),
+    };
+}

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

@@ -1,3 +1,10 @@
+/**
+ * Telegram's half of the shared context buffer (mechanics + consume protocol: ../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 { type ContextBuffer as GenericContextBuffer } from "../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
@@ -39,21 +46,5 @@ export declare function collectAttachments(consumed: BufferEntry[], primary: {
     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 type ContextBuffer = GenericContextBuffer<BufferEntry>;
 export declare function createContextBuffer(path: string): ContextBuffer;