@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/channels/preview-kit.js

@@ -0,0 +1,183 @@
+import { truncateCodePointPrefix, truncateCodePointSuffix } from "./text.js";
+/** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
+ *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").
+ *  The non-retryable branch keeps the "something went wrong" phrase deliberately — it is neutral (we only
+ *  know a boolean, never the specific limitation) and shared verbatim across channels. */
+export function defaultErrorMessage(failed) {
+    return failed.retryable
+        ? "⚠️ Temporary problem — please try again in a moment."
+        : "⚠️ Sorry, something went wrong. Try rephrasing, or check I have access to what you need.";
+}
+/** Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying`
+ *  event): neutral, no leaked internals — the reason stays in operator logs. */
+export const RETRY_NOTICE = "⏳ Temporary problem — retrying…";
+/** The placeholder shown before any reasoning/tool/text arrives. */
+export const THINKING_PLACEHOLDER = "💭 Thinking…";
+export function createTurnView() {
+    return { thinking: "", tools: [], toolById: new Map(), answer: "", retrying: false };
+}
+/**
+ * Apply one event to the view state. Returns true when the view changed (the caller repaints).
+ * This is the ONE place the shared view rules live: tool labels are humanized with a compact arg
+ * summary, and any progress event closes an open retry notice (a stale "retrying" line must never
+ * outlive actual progress). Terminal events only close the notice — they are the caller's business.
+ */
+export function applyTurnEvent(view, e) {
+    const closedRetry = view.retrying && e.type !== "retrying";
+    if (closedRetry)
+        view.retrying = false;
+    switch (e.type) {
+        case "text":
+            view.answer += e.delta;
+            if (view.answerSince === undefined && view.answer.trim() !== "")
+                view.answerSince = Date.now();
+            return true;
+        case "thinking":
+            view.thinking += e.delta;
+            return true;
+        case "tool_started": {
+            const arg = summarizeToolArgs(e.args);
+            const name = humanizeToolName(e.name);
+            const line = { label: arg ? `${name} ${arg}` : name, status: "running" };
+            view.tools.push(line);
+            view.toolById.set(e.id, line);
+            return true;
+        }
+        case "tool_ended": {
+            const line = view.toolById.get(e.id);
+            if (line)
+                line.status = e.isError ? "error" : "ok";
+            return true;
+        }
+        case "retrying":
+            view.retrying = true;
+            return true;
+        default:
+            return closedRetry;
+    }
+}
+const TOOL_MARK = { running: "…", ok: "✓", error: "✗" };
+/** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
+export function toolLines(view) {
+    return view.tools.map((t) => `🔧 ${t.label} ${TOOL_MARK[t.status]}`).join("\n");
+}
+/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe.
+ *  Process, not the answer — renderers show it live only, never in the persisted final message. */
+export function thinkingLine(view, maxTail) {
+    const t = view.thinking.replace(/\s+/g, " ").trim();
+    return t === "" ? "" : `💭 ${truncateCodePointSuffix(t, maxTail)}`;
+}
+/**
+ * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one
+ * throttle window (`ageMs` — each platform passes its own pacing constant). The pump's leading-edge
+ * flush would otherwise turn the very first content delta (often a lone character or unbalanced
+ * markup) into its own frame — the short-reply flicker (placeholder → "O" → "OK."). Aging is
+ * anchored at delta ARRIVAL (`answerSince`, set by the reducer) so an in-flight write can't skew the
+ * clock, and there is deliberately NO timer at the boundary: a young answer surfaces on the next
+ * content-driven pass, so a turn completing within the window delivers the final answer only.
+ */
+export function revealedAnswer(view, ageMs) {
+    if (view.answer.trim() === "" || view.answerSince === undefined)
+        return "";
+    return Date.now() - view.answerSince >= ageMs ? view.answer : "";
+}
+/** Compose body parts (thinking/tools/retry/answer) into one frame: skip empties, blank-line joins. */
+export function composeTurnBody(parts) {
+    return parts
+        .filter((s) => s.trim() !== "")
+        .join("\n\n")
+        .trim();
+}
+export function createPreviewPump(opts) {
+    let dirty = false;
+    let pumping = false;
+    let stopped = false;
+    let errored = false;
+    let pumpDone;
+    let wakeThrottle; // set while mid-throttle; finish() cuts it short
+    const runPump = async () => {
+        pumping = true;
+        try {
+            while (dirty && !stopped) {
+                dirty = false;
+                try {
+                    await opts.flush();
+                }
+                catch (error) {
+                    if (!errored) {
+                        errored = true;
+                        opts.onError(error);
+                    }
+                }
+                if (dirty && !stopped) {
+                    await new Promise((resolve) => {
+                        const t = setTimeout(resolve, opts.throttleMs);
+                        wakeThrottle = () => {
+                            clearTimeout(t);
+                            resolve();
+                        };
+                    });
+                    wakeThrottle = undefined;
+                }
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    };
+    return {
+        touch() {
+            dirty = true;
+            if (!pumping)
+                pumpDone = runPump();
+        },
+        async finish() {
+            stopped = true;
+            wakeThrottle?.();
+            await pumpDone?.catch(() => { });
+        },
+    };
+}
+/** Max length (code points) of a tool's arg preview in the live view. */
+const TOOL_ARG_MAX = 48;
+/** Max length (code points) of a humanized tool label. */
+const TOOL_NAME_MAX = 80;
+/** One-line, truncated at code-point boundaries: collapse whitespace so a multi-line command/arg
+ *  stays on one line, and never tear a surrogate pair mid-emoji. */
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    return truncateCodePointPrefix(one, TOOL_ARG_MAX);
+}
+/**
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
+ * rather than just `🔧 read`. Generic (a channel knows no tool schemas): show the salient value — the
+ * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ */
+function summarizeToolArgs(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return clip(String(args));
+    const values = Object.values(args);
+    const primary = values.find((v) => typeof v === "string" || typeof v === "number");
+    if (primary !== undefined)
+        return clip(String(primary));
+    return values.length > 0 ? clip(JSON.stringify(args)) : "";
+}
+/**
+ * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool
+ * does rather than expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue",
+ * not "mcp__github__create_issue"). Deliberately generic and engine-neutral: it only reshapes the
+ * identifier string — it never invents semantics and never exposes arguments. An `mcp__server__tool`
+ * identifier becomes `server: tool`; any other identifier has its separators normalized to spaces and
+ * its first letter capitalized.
+ */
+export function humanizeToolName(name) {
+    const normalize = (s) => s
+        .replace(/[_\-.]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const mcp = /^mcp__(.+?)__(.+)$/.exec(name);
+    const base = mcp ? `${normalize(mcp[1] ?? "")}: ${normalize(mcp[2] ?? "")}` : normalize(name);
+    const label = base.trim() || name.trim() || "Tool";
+    const capitalized = label.charAt(0).toUpperCase() + label.slice(1);
+    return truncateCodePointPrefix(capitalized, TOOL_NAME_MAX);
+}

package/dist/channels/seen.d.ts

@@ -0,0 +1,5 @@
+export interface SeenRing {
+    has(id: string): boolean;
+    add(id: string): void;
+}
+export declare function createSeenRing(path: string, label: string, cap?: number): SeenRing;

package/dist/channels/seen.js

@@ -0,0 +1,35 @@
+/** Best-effort bounded durable dedup ring, recorded only after the caller's pre-ACK side effect is durable. */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+export function createSeenRing(path, label, cap = 2000) {
+    const raw = loadStateFile(path);
+    const order = raw === undefined
+        ? []
+        : Array.isArray(raw) && raw.every((id) => typeof id === "string")
+            ? raw.slice(-cap)
+            : undefined;
+    if (order === undefined)
+        log.warn(`${label} unexpected shape in ${path} — starting with no seen ids`);
+    const values = order ?? [];
+    const ids = new Set(values);
+    return {
+        has: (id) => ids.has(id),
+        add(id) {
+            if (ids.has(id))
+                return;
+            ids.add(id);
+            values.push(id);
+            while (values.length > cap) {
+                const evicted = values.shift();
+                if (evicted !== undefined)
+                    ids.delete(evicted);
+            }
+            try {
+                saveStateFile(path, values);
+            }
+            catch (error) {
+                log.warn(`${label} seen-ring write failed (delivery dedup is in-memory until restart): ${String(error)}`);
+            }
+        },
+    };
+}

package/dist/channels/slack/bot-auth.d.ts

@@ -0,0 +1,15 @@
+export interface SlackBotTokenProviderOptions {
+    statePath: string;
+    botToken: string;
+    botRefreshToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+    botTokenExpiresAt?: number;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Latest local rotating credentials for `deploy --run`. The remote runtime still prefers its own
+ * durable volume; this overlay prevents a locally consumed refresh token from being redeployed. */
+export declare function readSlackBotAuthEnv(statePath: string): Record<string, string>;
+/** Resolve the current bot token, refreshing once per process when it approaches expiry. */
+export declare function createSlackBotTokenProvider(options: SlackBotTokenProviderOptions): () => Promise<string>;

package/dist/channels/slack/bot-auth.js

@@ -0,0 +1,146 @@
+/** Rotating Slack bot-token provider backed by owner-only channel state. */
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const REFRESH_EARLY_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+function isState(value) {
+    const state = value;
+    return (typeof state === "object" &&
+        state !== null &&
+        state.version === 1 &&
+        typeof state.accessToken === "string" &&
+        typeof state.refreshToken === "string" &&
+        typeof state.expiresAt === "number");
+}
+function load(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Slack bot auth state ${path} is unreadable: ${String(error)}`, { cause: error });
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (!isState(value))
+            throw new Error("unexpected shape/version");
+        return value;
+    }
+    catch (error) {
+        // A stale env refresh token may already have been consumed. Never hide corrupt rotating state by
+        // falling back to it: recovery requires restoring the durable file or reinstalling the app.
+        throw new Error(`Slack bot auth state ${path} is invalid: ${String(error)}`, { cause: error });
+    }
+}
+function save(path, state) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify(state), { mode: 0o600 });
+        chmodSync(temp, 0o600);
+        renameSync(temp, path);
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+}
+async function refreshSlackBotToken(input) {
+    const authorization = Buffer.from(`${input.clientId}:${input.clientSecret}`, "utf8").toString("base64");
+    let lastError;
+    // Slack keeps a short grace window for a just-consumed refresh token. One retry recovers the
+    // committed-but-response-lost boundary without creating an unbounded refresh loop.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const response = await input.fetch(`${input.apiBaseUrl}/oauth.v2.access`, {
+                method: "POST",
+                headers: {
+                    authorization: `Basic ${authorization}`,
+                    "content-type": "application/x-www-form-urlencoded",
+                },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: input.refreshToken,
+                }).toString(),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = (await response.json().catch(() => ({})));
+            if (!response.ok ||
+                data.ok !== true ||
+                !data.access_token ||
+                !data.refresh_token ||
+                typeof data.expires_in !== "number") {
+                throw new Error(`Slack rejected bot-token refresh (HTTP ${response.status})`);
+            }
+            return {
+                version: 1,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                expiresAt: Date.now() + data.expires_in * 1_000,
+            };
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error("Slack bot-token rotation failed; restore credentials or reinstall the app", { cause: lastError });
+}
+/** Latest local rotating credentials for `deploy --run`. The remote runtime still prefers its own
+ * durable volume; this overlay prevents a locally consumed refresh token from being redeployed. */
+export function readSlackBotAuthEnv(statePath) {
+    const state = load(statePath);
+    return state
+        ? {
+            SLACK_BOT_TOKEN: state.accessToken,
+            SLACK_BOT_REFRESH_TOKEN: state.refreshToken,
+            SLACK_BOT_TOKEN_EXPIRES_AT: String(state.expiresAt),
+        }
+        : {};
+}
+/** Resolve the current bot token, refreshing once per process when it approaches expiry. */
+export function createSlackBotTokenProvider(options) {
+    const rotatingFields = [options.botRefreshToken, options.clientId, options.clientSecret, options.botTokenExpiresAt];
+    const rotating = rotatingFields.some((value) => value !== undefined);
+    if (rotating && rotatingFields.some((value) => value === undefined || value === "")) {
+        throw new Error("Slack token rotation requires botRefreshToken, clientId, clientSecret, and botTokenExpiresAt together");
+    }
+    if (rotating && (!Number.isFinite(options.botTokenExpiresAt) || options.botTokenExpiresAt <= 0)) {
+        throw new Error("Slack botTokenExpiresAt must be a positive epoch-millisecond value");
+    }
+    if (!rotating)
+        return async () => options.botToken;
+    const configured = {
+        version: 1,
+        accessToken: options.botToken,
+        refreshToken: options.botRefreshToken,
+        expiresAt: options.botTokenExpiresAt,
+    };
+    const persisted = load(options.statePath);
+    // Deploy may carry a newer pair from the owner machine onto an existing remote volume; ordinary
+    // restarts carry the original stale env and therefore keep the newer persisted pair.
+    let state = persisted && persisted.expiresAt >= configured.expiresAt ? persisted : configured;
+    let refreshing;
+    return async () => {
+        if (state.expiresAt > Date.now() + REFRESH_EARLY_MS)
+            return state.accessToken;
+        refreshing ??= refreshSlackBotToken({
+            refreshToken: state.refreshToken,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            apiBaseUrl: (options.apiBaseUrl ?? "https://slack.com/api").replace(/\/$/, ""),
+            fetch: options.fetch ?? globalThis.fetch,
+        })
+            .then((next) => {
+            save(options.statePath, next);
+            state = next;
+        })
+            .finally(() => {
+            refreshing = undefined;
+        });
+        await refreshing;
+        return state.accessToken;
+    };
+}

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

@@ -0,0 +1,60 @@
+import type { SlackAppManifest } from "./manifest.ts";
+interface SlackErrorShape {
+    ok?: boolean;
+    error?: string;
+    errors?: {
+        message?: string;
+        pointer?: string;
+    }[];
+}
+export declare class SlackConfigApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(method: string, status: number, data: SlackErrorShape, fallback: string);
+}
+export interface SlackAppCredentials {
+    appId: string;
+    clientId: string;
+    clientSecret: string;
+    signingSecret: string;
+    oauthAuthorizeUrl?: string;
+}
+/** Create is intentionally single-attempt: an ambiguous response may already have created the app. */
+export declare function createSlackApp(configToken: string, manifest: SlackAppManifest, options?: {
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<SlackAppCredentials>;
+export declare function updateSlackAppManifest(configToken: string, appId: string, manifest: SlackAppManifest, options?: {
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<void>;
+export interface RotatedSlackConfigToken {
+    token: string;
+    refreshToken: string;
+    expiresAt: number;
+    teamId?: string;
+}
+export declare function rotateSlackConfigToken(refreshToken: string, options?: {
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<RotatedSlackConfigToken>;
+export interface SlackOAuthResult {
+    botToken: string;
+    botRefreshToken: string;
+    botTokenExpiresAt: number;
+    appId: string;
+    teamId: string;
+    teamName?: string;
+    botUserId?: string;
+    scopes: string[];
+}
+export declare function exchangeSlackOAuthCode(input: {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUrl: string;
+}, options?: {
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<SlackOAuthResult>;
+export {};

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

@@ -0,0 +1,149 @@
+const SLACK_API = "https://slack.com/api";
+const REQUEST_TIMEOUT_MS = 30_000;
+export class SlackConfigApiError extends Error {
+    code;
+    status;
+    constructor(method, status, data, fallback) {
+        const code = data.error ?? fallback;
+        const fields = data.errors
+            ?.map((error) => `${error.pointer ?? "manifest"}: ${error.message ?? "invalid"}`)
+            .join("; ");
+        super(`Slack ${method} failed: ${code}${fields ? ` — ${fields}` : ""}`);
+        this.name = "SlackConfigApiError";
+        this.code = code;
+        this.status = status;
+    }
+}
+async function slackJson(method, body, options = {}) {
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    let response;
+    let raw;
+    try {
+        response = await fetchFn(`${options.apiBaseUrl ?? SLACK_API}/${method}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json; charset=utf-8",
+                ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        raw = await response.text();
+    }
+    catch (error) {
+        throw new Error(`Slack ${method} request failed before receiving a response`, { cause: error });
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Slack ${method} failed: HTTP ${response.status} returned non-JSON`);
+    }
+    if (!response.ok || data.ok !== true) {
+        throw new SlackConfigApiError(method, response.status, data, raw.trim().slice(0, 200) || "unknown_error");
+    }
+    return data;
+}
+/** Create is intentionally single-attempt: an ambiguous response may already have created the app. */
+export async function createSlackApp(configToken, manifest, options = {}) {
+    const data = await slackJson("apps.manifest.create", { manifest: JSON.stringify(manifest) }, { ...options, token: configToken });
+    const credentials = data.credentials;
+    if (!data.app_id || !credentials?.client_id || !credentials.client_secret || !credentials.signing_secret) {
+        throw new Error("Slack apps.manifest.create succeeded but returned incomplete app credentials");
+    }
+    return {
+        appId: data.app_id,
+        clientId: credentials.client_id,
+        clientSecret: credentials.client_secret,
+        signingSecret: credentials.signing_secret,
+        oauthAuthorizeUrl: data.oauth_authorize_url,
+    };
+}
+export async function updateSlackAppManifest(configToken, appId, manifest, options = {}) {
+    await slackJson("apps.manifest.update", { app_id: appId, manifest: JSON.stringify(manifest) }, { ...options, token: configToken });
+}
+export async function rotateSlackConfigToken(refreshToken, options = {}) {
+    const data = await slackJson("tooling.tokens.rotate", { refresh_token: refreshToken }, options);
+    if (!data.token || !data.refresh_token || typeof data.exp !== "number") {
+        throw new Error("Slack tooling.tokens.rotate succeeded but returned incomplete token credentials");
+    }
+    return {
+        token: data.token,
+        refreshToken: data.refresh_token,
+        expiresAt: data.exp * 1000,
+        teamId: data.team_id,
+    };
+}
+function slackOAuthFailure(status, code) {
+    const reason = (() => {
+        switch (code) {
+            case "bad_client_secret":
+                return "Slack rejected the app client secret";
+            case "invalid_client_id":
+                return "Slack rejected the app client ID";
+            case "bad_redirect_uri":
+            case "invalid_redirect_uri":
+                return "Slack rejected the temporary OAuth redirect URL";
+            case "invalid_code":
+                return "Slack rejected the authorization code";
+            case "code_already_used":
+                return "the Slack authorization code was already used";
+            case "access_denied":
+                return "the Slack installation was not approved";
+            default:
+                return "Slack rejected the OAuth exchange";
+        }
+    })();
+    return new Error(`${reason} (HTTP ${status}); re-run fastagent add slack to resume installation`);
+}
+export async function exchangeSlackOAuthCode(input, options = {}) {
+    const authorization = Buffer.from(`${input.clientId}:${input.clientSecret}`, "utf8").toString("base64");
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    let response;
+    let raw;
+    try {
+        response = await fetchFn(`${options.apiBaseUrl ?? SLACK_API}/oauth.v2.access`, {
+            method: "POST",
+            headers: {
+                authorization: `Basic ${authorization}`,
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body: new URLSearchParams({ code: input.code, redirect_uri: input.redirectUrl }).toString(),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        raw = await response.text();
+    }
+    catch (error) {
+        throw new Error("Slack oauth.v2.access request failed before receiving a response", { cause: error });
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Slack oauth.v2.access failed: HTTP ${response.status} returned non-JSON`);
+    }
+    if (!response.ok || data.ok !== true)
+        throw slackOAuthFailure(response.status, data.error);
+    if (!data.access_token ||
+        !data.refresh_token ||
+        typeof data.expires_in !== "number" ||
+        !data.app_id ||
+        !data.team?.id) {
+        throw new Error("Slack oauth.v2.access succeeded but returned incomplete rotating bot credentials/app identity");
+    }
+    return {
+        botToken: data.access_token,
+        botRefreshToken: data.refresh_token,
+        botTokenExpiresAt: Date.now() + data.expires_in * 1_000,
+        appId: data.app_id,
+        teamId: data.team.id,
+        teamName: data.team.name,
+        botUserId: data.bot_user_id,
+        scopes: (data.scope ?? "")
+            .split(",")
+            .map((scope) => scope.trim())
+            .filter(Boolean),
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Slack's half of the shared context buffer (mechanics + consume protocol: ../context-buffer.ts):
+ * the entry shape, its fold-line rendering, and buffered-file selection. Durable, bounded
+ * unsummoned Slack discussion folded into the next answered turn in the same place.
+ */
+import { type ContextBuffer } from "../context-buffer.ts";
+export interface SlackBufferEntry {
+    sender: string;
+    body: string;
+    messageId: string;
+    replyTo?: string;
+    fileIds?: string[];
+}
+export interface SlackBufferedFileRef {
+    id: string;
+    from: string;
+    messageId: string;
+}
+export declare function collectSlackBufferedFiles(consumed: SlackBufferEntry[], primaryIds: Set<string>): {
+    files: SlackBufferedFileRef[];
+    skipped: number;
+};
+export type SlackContextBuffer = ContextBuffer<SlackBufferEntry>;
+export declare function createSlackContextBuffer(path: string, label: string): SlackContextBuffer;

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

@@ -0,0 +1,37 @@
+/**
+ * Slack's half of the shared context buffer (mechanics + consume protocol: ../context-buffer.ts):
+ * the entry shape, its fold-line rendering, and buffered-file selection. Durable, bounded
+ * unsummoned Slack discussion folded into the next answered turn in the same place.
+ */
+import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
+function bufferLine(entry) {
+    const meta = [`msg ${entry.messageId}`, entry.replyTo ? `thread root ${entry.replyTo}` : undefined]
+        .filter(Boolean)
+        .join(", ");
+    return `${entry.sender} (${meta}): ${entry.body}`;
+}
+export function collectSlackBufferedFiles(consumed, primaryIds) {
+    const seen = new Set();
+    const files = [];
+    for (const entry of consumed) {
+        for (const id of entry.fileIds ?? []) {
+            if (primaryIds.has(id) || seen.has(id))
+                continue;
+            seen.add(id);
+            files.push({ id, from: entry.sender, messageId: entry.messageId });
+        }
+    }
+    return { files: files.slice(-BUFFER_ATTACH_MAX), skipped: Math.max(0, files.length - BUFFER_ATTACH_MAX) };
+}
+function isEntry(value) {
+    const entry = value;
+    return (typeof entry?.sender === "string" &&
+        typeof entry.body === "string" &&
+        typeof entry.messageId === "string" &&
+        (entry.replyTo === undefined || typeof entry.replyTo === "string") &&
+        (entry.fileIds === undefined ||
+            (Array.isArray(entry.fileIds) && entry.fileIds.every((id) => typeof id === "string"))));
+}
+export function createSlackContextBuffer(path, label) {
+    return createGenericContextBuffer({ path, label, isEntry, line: bufferLine });
+}

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

@@ -0,0 +1,19 @@
+/** Resolve Slack file IDs at dequeue, then stream one engine-neutral Agent turn. */
+import type { Agent, AgentEvent } from "../../agent.ts";
+import { type BusyRetry } from "../invoke-turn-kit.ts";
+import type { SlackBufferedFileRef } from "./context-buffer.ts";
+import type { SlackApi } from "./slack-api.ts";
+export interface SlackTurnTransport {
+    api: SlackApi;
+    channelId: string;
+    filesDir: string;
+    label: string;
+}
+export interface SlackTurnAttachments {
+    primaryFileIds: string[];
+    buffered: {
+        files: SlackBufferedFileRef[];
+        skipped: number;
+    };
+}
+export declare function invokeSlackTurn(agent: Agent, session: string, text: string, transport: SlackTurnTransport, attachments: SlackTurnAttachments, onCompleted?: () => void, busyRetry?: BusyRetry): AsyncIterable<AgentEvent>;