@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/channels/slack/preview.js

@@ -0,0 +1,359 @@
+import { log } from "../../log.js";
+import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createTurnView, defaultErrorMessage, humanizeToolName, revealedAnswer, toolLines, } from "../preview-kit.js";
+import { chunkSlackMarkdown, chunkSlackText, isSlackNativeUnavailable, } from "./slack-api.js";
+export { defaultErrorMessage };
+const CLASSIC_UPDATE_INTERVAL_MS = 3_000;
+const NATIVE_APPEND_INTERVAL_MS = 750;
+const WORKING_STATUS = "is working on your request…";
+const GENERIC_FAILURE = "⚠️ The response stream stopped unexpectedly. Please try again.";
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** LLM output uses standard Markdown, never Slack's notification control syntax. Keep explicit sends in
+ * the slack-send tool, where the Agent has to choose a side-effecting delivery action deliberately.
+ * The inner class excludes BOTH `<` and `>` on purpose: bounding each run by the next delimiter keeps
+ * the scan linear even on adversarial input like `(<!)^n` (a `>`-only bound would still be polynomial
+ * across the many `<` start positions), while still neutralizing every `<@…>` / `<!…>` control sequence
+ * (real Slack controls never contain a `<`). */
+export function sanitizeSlackMarkdown(markdown) {
+    return markdown.replace(/<[@!][^<>]*>/g, (control) => `&lt;${control.slice(1)}`);
+}
+function withDisclaimer(markdown, disclaimer) {
+    const body = markdown.trim() || "(no reply)";
+    return disclaimer === false || !disclaimer?.trim() ? body : `${body}\n\n_${disclaimer.trim()}_`;
+}
+async function settleClassic(api, target, previewTs, markdown, update = (ts, value) => api.updateMarkdown(target.channelId, ts, value)) {
+    if (markdown.trim() === "") {
+        if (previewTs)
+            await api.deleteMessage(target.channelId, previewTs).catch(() => { });
+        return;
+    }
+    const [head, ...rest] = chunkSlackMarkdown(markdown);
+    if (previewTs && head !== undefined) {
+        try {
+            await update(previewTs, head);
+        }
+        catch {
+            await api.deleteMessage(target.channelId, previewTs).catch(() => { });
+            await api.sendMarkdown(target, markdown);
+            return;
+        }
+        // The updated preview is authoritative. Never resend it if a continuation fails: that would
+        // duplicate any continuation that Slack already accepted.
+        for (const chunk of rest)
+            await api.postMarkdown(target, chunk);
+        return;
+    }
+    await api.sendMarkdown(target, markdown);
+}
+/** Settle a queue/drop/defer notice. These are authored plain strings, so the basic text API is enough. */
+export async function settleSlackPreview(api, target, previewTs, text) {
+    if (previewTs) {
+        await api.updateMessage(target.channelId, previewTs, text);
+        return;
+    }
+    await api.postMessage(target, text);
+}
+async function streamClassicSlackReply(events, api, target, formatError, initialPreviewTs, disclaimer, label) {
+    // Event → view-state reduction is the shared machine (preview-kit); this renderer owns mrkdwn
+    // sanitizing and delivery. Reasoning stays a static "Thinking…" here: raw chain-of-thought is not
+    // customer-facing on Slack, so the reducer accumulates it but this view never reads it.
+    const turn = createTurnView();
+    let previewTs = initialPreviewTs;
+    let previewAttempted = previewTs !== undefined;
+    let finalized = false;
+    let lastMutationAt = previewTs ? Date.now() : 0;
+    let lastSent = "";
+    let dirty = false;
+    let pumping = false;
+    let stopped = false;
+    let pumpDone;
+    let previewErrorLogged = false;
+    const view = () => composeTurnBody([
+        THINKING_PLACEHOLDER,
+        toolLines(turn),
+        turn.retrying ? RETRY_NOTICE : "",
+        sanitizeSlackMarkdown(revealedAnswer(turn, CLASSIC_UPDATE_INTERVAL_MS)),
+    ]);
+    const waitForMutationSlot = async () => {
+        const remaining = lastMutationAt + CLASSIC_UPDATE_INTERVAL_MS - Date.now();
+        if (remaining > 0)
+            await wait(remaining);
+    };
+    const updateRateSafe = async (ts, markdown) => {
+        await waitForMutationSlot();
+        await api.updateMarkdown(target.channelId, ts, markdown);
+        lastMutationAt = Date.now();
+    };
+    const flushPreview = async () => {
+        const markdown = chunkSlackText(view())[0] ?? THINKING_PLACEHOLDER;
+        if (markdown === lastSent)
+            return;
+        if (previewTs) {
+            await updateRateSafe(previewTs, markdown);
+        }
+        else {
+            if (previewAttempted)
+                return;
+            previewAttempted = true;
+            previewTs = await api.postMarkdown(target, markdown);
+            lastMutationAt = Date.now();
+        }
+        lastSent = markdown;
+    };
+    const runPump = async () => {
+        pumping = true;
+        try {
+            while (dirty && !stopped) {
+                dirty = false;
+                try {
+                    await flushPreview();
+                }
+                catch (error) {
+                    if (!previewErrorLogged) {
+                        previewErrorLogged = true;
+                        log.warn(`${label} live preview failed (final reply still sends): ${String(error)}`);
+                    }
+                }
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    };
+    const touch = () => {
+        dirty = true;
+        if (!pumping)
+            pumpDone = runPump();
+    };
+    const finishPump = async () => {
+        stopped = true;
+        await pumpDone?.catch(() => { });
+    };
+    const finalize = async (markdown) => {
+        await settleClassic(api, target, previewTs, sanitizeSlackMarkdown(markdown), updateRateSafe);
+    };
+    try {
+        for await (const event of events) {
+            if (event.type === "completed") {
+                await finishPump();
+                finalized = true;
+                await finalize(withDisclaimer(turn.answer, disclaimer));
+                return;
+            }
+            if (event.type === "failed") {
+                await finishPump();
+                finalized = true;
+                const notice = formatError({ details: event.details, retryable: event.retryable }) ?? "";
+                await finalize(notice).catch((error) => log.error(`${label} failed to deliver the agent-failure notice: ${String(error)}`));
+                throw new Error(`agent failed: ${event.details} (retryable=${event.retryable})`);
+            }
+            const changed = applyTurnEvent(turn, event);
+            // A young (hidden) answer must not trigger the first frame: unlike telegram/feishu, classic
+            // rendering never posts an upfront placeholder, so a text-only fast turn delivers ONE final
+            // post instead of placeholder → 3s-rate-limited edit. Thinking/tool activity still paints.
+            if (changed && (event.type !== "text" || revealedAnswer(turn, CLASSIC_UPDATE_INTERVAL_MS) !== ""))
+                touch();
+        }
+        throw new Error("stream ended without a terminal event");
+    }
+    finally {
+        await finishPump();
+        if (!finalized) {
+            const notice = formatError({ details: "the turn ended without completing", retryable: false }) ?? "";
+            await finalize(notice).catch((error) => log.error(`${label} failed to deliver the abnormal-turn notice: ${String(error)}`));
+        }
+    }
+}
+async function streamNativeSlackReply(events, api, target, formatError, initialPreviewTs, threadTitle, disclaimer, label, taskDisplayMode) {
+    if (initialPreviewTs) {
+        await api
+            .deleteMessage(target.channelId, initialPreviewTs)
+            .catch((error) => log.warn(`${label} could not remove the compatibility queue notice before native streaming: ${String(error)}`));
+    }
+    if (target.channelId.startsWith("D")) {
+        await Promise.all([
+            api
+                .setThreadStatus(target, WORKING_STATUS)
+                .catch((error) => log.warn(`${label} could not set Slack Agent status: ${String(error)}`)),
+            threadTitle
+                ? api
+                    .setThreadTitle(target, threadTitle)
+                    .catch((error) => log.warn(`${label} could not set Slack Agent thread title: ${String(error)}`))
+                : Promise.resolve(),
+        ]);
+    }
+    let streamTs;
+    let retryStatusShown = false;
+    // DM Agent-status writes are fire-and-forget for the render loop, but must reach Slack in order:
+    // an out-of-order pair would leave a stale "retrying" line after progress (or after the final
+    // clear). One promise chain serializes them; each link swallows its own delivery error.
+    let statusChain = Promise.resolve();
+    const setStatus = (status) => {
+        statusChain = statusChain.then(() => api
+            .setThreadStatus(target, status)
+            .catch((error) => log.warn(`${label} could not set Slack Agent status: ${String(error)}`)));
+    };
+    const toolNames = new Map();
+    let pendingText = "";
+    let fullAnswer = "";
+    let textTimer;
+    let lastTextFlushAt = 0;
+    let operation = Promise.resolve();
+    let renderError;
+    let finalized = false;
+    const enqueue = (work) => {
+        operation = operation.then(async () => {
+            if (renderError !== undefined)
+                return;
+            try {
+                await work();
+            }
+            catch (error) {
+                renderError = error;
+            }
+        });
+    };
+    const sendContent = async (content) => {
+        if (streamTs) {
+            await api.appendStream(target.channelId, streamTs, content);
+        }
+        else {
+            streamTs = await api.startStream(target, content, taskDisplayMode);
+        }
+    };
+    const flushText = (final = false) => {
+        if (textTimer) {
+            clearTimeout(textTimer);
+            textTimer = undefined;
+        }
+        let value = pendingText;
+        pendingText = "";
+        if (!final) {
+            // Hold a possible Slack control token split across Agent deltas/flush windows until its closing
+            // `>` arrives. This prevents `<` + `!channel>` from bypassing the sanitizer.
+            const open = value.lastIndexOf("<");
+            if (open >= 0 && !value.slice(open).includes(">") && value.length - open <= 256) {
+                pendingText = value.slice(open);
+                value = value.slice(0, open);
+            }
+        }
+        if (!value)
+            return;
+        lastTextFlushAt = Date.now();
+        for (const chunk of chunkSlackText(sanitizeSlackMarkdown(value))) {
+            enqueue(() => sendContent({ markdownText: chunk }));
+        }
+    };
+    const scheduleText = () => {
+        if (textTimer)
+            return;
+        const delay = Math.max(0, lastTextFlushAt + NATIVE_APPEND_INTERVAL_MS - Date.now());
+        textTimer = setTimeout(() => {
+            textTimer = undefined;
+            flushText();
+        }, delay);
+    };
+    const sendTask = (chunk) => {
+        flushText();
+        enqueue(() => sendContent({ chunks: [chunk] }));
+    };
+    const settleNative = async (terminalMarkdown) => {
+        flushText(true);
+        await operation;
+        const safeTerminal = sanitizeSlackMarkdown(terminalMarkdown);
+        if (renderError !== undefined) {
+            if (!streamTs && isSlackNativeUnavailable(renderError)) {
+                log.warn(`${label} native Slack stream was unavailable; delivering one compatibility Markdown reply`);
+                await api.sendMarkdown(target, safeTerminal);
+                return;
+            }
+            if (streamTs) {
+                await api.stopStream(target.channelId, streamTs, { markdownText: `\n\n${GENERIC_FAILURE}` }).catch(() => { });
+            }
+            throw renderError;
+        }
+        if (!streamTs)
+            streamTs = await api.startStream(target, { markdownText: safeTerminal }, taskDisplayMode);
+        await api.stopStream(target.channelId, streamTs);
+    };
+    try {
+        for await (const event of events) {
+            if (event.type !== "retrying" && retryStatusShown) {
+                // Progress after a retry notice: restore the normal working status so the stale line doesn't
+                // contradict a visibly streaming answer.
+                retryStatusShown = false;
+                setStatus(WORKING_STATUS);
+            }
+            if (event.type === "text") {
+                pendingText += event.delta;
+                fullAnswer += event.delta;
+                scheduleText();
+            }
+            else if (event.type === "thinking") {
+                // Slack's native loading status represents private reasoning without exposing it.
+            }
+            else if (event.type === "retrying") {
+                // A summarization retry backoff pauses the stream (~14s worst case). Channels have no per-run
+                // status surface in native mode; DMs get the explicit Agent status line, restored on progress.
+                if (target.channelId.startsWith("D")) {
+                    retryStatusShown = true;
+                    setStatus("hit a temporary problem — retrying…");
+                }
+            }
+            else if (event.type === "tool_started") {
+                const title = humanizeToolName(event.name);
+                toolNames.set(event.id, title);
+                sendTask({ type: "task_update", id: event.id, title, status: "in_progress" });
+            }
+            else if (event.type === "tool_ended") {
+                sendTask({
+                    type: "task_update",
+                    id: event.id,
+                    title: toolNames.get(event.id) ?? "Tool",
+                    status: event.isError ? "error" : "complete",
+                });
+            }
+            else if (event.type === "completed") {
+                finalized = true;
+                const finalAnswer = withDisclaimer(fullAnswer, disclaimer);
+                const footer = finalAnswer.slice(fullAnswer.trim().length);
+                if (footer)
+                    pendingText += footer;
+                await settleNative(finalAnswer);
+                return;
+            }
+            else if (event.type === "failed") {
+                finalized = true;
+                const notice = formatError({ details: event.details, retryable: event.retryable }) ?? "";
+                if (notice) {
+                    pendingText += `${fullAnswer.trim() ? "\n\n" : ""}${notice}`;
+                    fullAnswer += `${fullAnswer.trim() ? "\n\n" : ""}${notice}`;
+                }
+                await settleNative(fullAnswer.trim() || GENERIC_FAILURE).catch((error) => log.error(`${label} failed to deliver the agent-failure stream: ${String(error)}`));
+                throw new Error(`agent failed: ${event.details} (retryable=${event.retryable})`);
+            }
+        }
+        throw new Error("stream ended without a terminal event");
+    }
+    finally {
+        if (textTimer)
+            clearTimeout(textTimer);
+        if (!finalized) {
+            pendingText += `${fullAnswer.trim() ? "\n\n" : ""}${GENERIC_FAILURE}`;
+            await settleNative(fullAnswer.trim() || GENERIC_FAILURE).catch((error) => log.error(`${label} failed to stop an abnormal Slack stream: ${String(error)}`));
+        }
+        if (target.channelId.startsWith("D")) {
+            setStatus("");
+            await statusChain;
+        }
+    }
+}
+export async function streamSlackReply(events, api, target, formatError, options = {}) {
+    const { rendering = "native", initialPreviewTs, threadTitle, disclaimer, taskDisplay = "plan", label = "[slack]", } = options;
+    if (rendering === "native" && target.threadTs) {
+        return streamNativeSlackReply(events, api, target, formatError, initialPreviewTs, threadTitle, disclaimer, label, taskDisplay);
+    }
+    if (rendering === "native") {
+        log.info(`${label} native streaming needs a thread target — using the classic renderer for this turn`);
+    }
+    return streamClassicSlackReply(events, api, target, formatError, initialPreviewTs, disclaimer, label);
+}

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

@@ -0,0 +1,24 @@
+import type { SlackApi } from "./slack-api.ts";
+/** Normalize a Slack emoji name (strip surrounding colons, lowercase); return null if invalid. */
+export declare function normalizeSlackEmojiName(value: string): string | null;
+export interface SlackReactionEmojis {
+    processing: string;
+    completed: string;
+}
+/** Resolve the configured reaction emojis; `false` disables the ack, invalid names throw at construction. */
+export declare function resolveReactionEmojis(reactionAck: false | {
+    processing?: string;
+    completed?: string;
+}): SlackReactionEmojis | undefined;
+export interface SlackReactionSession {
+    complete(): Promise<void>;
+    remove(): Promise<void>;
+}
+/** Add the processing emoji now; return a session to swap it for the completed emoji or remove it. */
+export declare function startSlackReaction(args: {
+    api: Pick<SlackApi, "addReaction" | "removeReaction">;
+    channelId: string;
+    ts: string;
+    emojis: SlackReactionEmojis;
+    label: string;
+}): Promise<SlackReactionSession>;

package/dist/channels/slack/reaction.js

@@ -0,0 +1,62 @@
+/** Lightweight Slack emoji ack on the user's triggering message: 👀 while working, ✅ when done.
+ *  Every failure is non-fatal — the turn's threaded reply is the real deliverable. */
+import { log } from "../../log.js";
+const EMOJI_RE = /^(?:[a-z0-9_+-]+)(?:::skin-tone-[2-6])?$/;
+/** Normalize a Slack emoji name (strip surrounding colons, lowercase); return null if invalid. */
+export function normalizeSlackEmojiName(value) {
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const name = trimmed.startsWith(":") && trimmed.endsWith(":") ? trimmed.slice(1, -1) : trimmed;
+    return EMOJI_RE.test(name) ? name : null;
+}
+/** Resolve the configured reaction emojis; `false` disables the ack, invalid names throw at construction. */
+export function resolveReactionEmojis(reactionAck) {
+    if (reactionAck === false)
+        return undefined;
+    const pick = (value, fallback, field) => {
+        if (value === undefined)
+            return fallback;
+        const name = normalizeSlackEmojiName(value);
+        if (!name)
+            throw new Error(`slackChannel reactionAck.${field} is not a valid Slack emoji name: "${value}"`);
+        return name;
+    };
+    return {
+        processing: pick(reactionAck.processing, "eyes", "processing"),
+        completed: pick(reactionAck.completed, "white_check_mark", "completed"),
+    };
+}
+const NO_REACTION = {
+    complete: async () => undefined,
+    remove: async () => undefined,
+};
+/** Add the processing emoji now; return a session to swap it for the completed emoji or remove it. */
+export async function startSlackReaction(args) {
+    const { api, channelId, ts, emojis, label } = args;
+    try {
+        await api.addReaction(channelId, ts, emojis.processing);
+    }
+    catch (error) {
+        log.warn(`${label} could not add the processing reaction (skipping ack): ${String(error)}`);
+        return NO_REACTION;
+    }
+    let active = true;
+    const removeProcessing = async () => {
+        if (!active)
+            return;
+        active = false;
+        await api
+            .removeReaction(channelId, ts, emojis.processing)
+            .catch((error) => log.warn(`${label} could not remove the processing reaction: ${String(error)}`));
+    };
+    return {
+        complete: async () => {
+            await removeProcessing();
+            await api
+                .addReaction(channelId, ts, emojis.completed)
+                .catch((error) => log.warn(`${label} could not add the completed reaction: ${String(error)}`));
+        },
+        remove: removeProcessing,
+    };
+}

package/dist/channels/slack/register-webhook.d.ts

@@ -0,0 +1,10 @@
+import type { RegistrationOutcome } from "../registration.ts";
+export interface RegisterSlackWebhookOptions {
+    stateRoot: string;
+    log?: (message: string) => void;
+    healthTimeoutMs?: number;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Update one onboarded internal Slack app without sending its configuration credential to the host. */
+export declare function registerSlackWebhook(baseUrl: string, options: RegisterSlackWebhookOptions): Promise<RegistrationOutcome>;

package/dist/channels/slack/register-webhook.js

@@ -0,0 +1,49 @@
+import { waitForHealth } from "../wait-health.js";
+import { updateSlackAppManifest } from "./config-api.js";
+import { buildSlackManifest } from "./manifest.js";
+import { currentSlackConfigToken, readSlackOnboardingState } from "./onboarding-state.js";
+/** Update one onboarded internal Slack app without sending its configuration credential to the host. */
+export async function registerSlackWebhook(baseUrl, options) {
+    const note = options.log ?? ((message) => console.error(message));
+    const publicBaseUrl = baseUrl.replace(/\/$/, "");
+    let state;
+    try {
+        state = await readSlackOnboardingState(options.stateRoot);
+    }
+    catch (error) {
+        note(`[fastagent] slack: cannot read local onboarding state: ${String(error)}`);
+        return "failed";
+    }
+    if (!state?.appId || !state.installedAt) {
+        note(`[fastagent] slack: no completed local onboarding state on this machine — the config credential lives only where \`fastagent add slack\` ran. ` +
+            `Set Event Subscriptions → Request URL = ${publicBaseUrl}/slack manually in the Slack console, or re-run this command from the onboarding machine ` +
+            `(repair its expired/revoked tokens with \`fastagent add slack --replace-config\`)`);
+        return "manual";
+    }
+    const healthy = await waitForHealth(`${publicBaseUrl}/health`, options.healthTimeoutMs ?? 45_000, 500);
+    if (!healthy) {
+        note(`[fastagent] slack: ${publicBaseUrl}/health did not become reachable; Request URL was not changed`);
+        return "failed";
+    }
+    try {
+        const current = await currentSlackConfigToken(options.stateRoot, state, {
+            apiBaseUrl: options.apiBaseUrl,
+            fetch: options.fetch,
+        });
+        await updateSlackAppManifest(current.token, current.state.appId, buildSlackManifest({
+            name: current.state.appName,
+            groupBehavior: current.state.groupBehavior,
+            requestUrl: `${publicBaseUrl}/slack`,
+            // Token-rotation manifests require at least one OAuth redirect URL even after installation.
+            // Actual reinstall flows replace this placeholder with their one-shot local setup callback.
+            redirectUrl: `${publicBaseUrl}/slack/oauth/callback`,
+        }), { apiBaseUrl: options.apiBaseUrl, fetch: options.fetch });
+        note(`[fastagent] slack: Event Subscriptions Request URL registered → ${publicBaseUrl}/slack`);
+        return "registered";
+    }
+    catch (error) {
+        note(`[fastagent] slack: automatic Request URL registration failed: ${String(error)} — ` +
+            `re-run \`fastagent add slack --replace-config\` to repair the configuration tokens, or set ${publicBaseUrl}/slack in the Slack console`);
+        return "failed";
+    }
+}

package/dist/channels/slack/scaffold/channel.ts

@@ -0,0 +1,33 @@
+import { slackChannel } from "@fastagent-sh/fastagent/slack";
+
+// Slack HTTP Events API channel. Setup:
+//   1. Create a Slack app at https://api.slack.com/apps and add a bot user.
+//   2. Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history,
+//      files:read, files:write, channels:history, groups:history, and mpim:history. The explicit
+//      mention-only mode may omit the three group-history scopes.
+//   3. Event Subscriptions: app_home_opened, app_context_changed, app_mention, message.im,
+//      message.channels, message.groups, and message.mpim. Mention-only may omit the last three.
+//      Set Request URL to https://<host>/slack.
+//   4. Enable token rotation and install/reinstall the app after changing scopes. Rotating credentials
+//      are written by `fastagent add slack`; manual long-lived tokens may omit the four rotation fields.
+export default slackChannel({
+  botToken: process.env.SLACK_BOT_TOKEN ?? "", // Bot User OAuth Token (xoxb-… or rotating xoxe.xoxb-…)
+  signingSecret: process.env.SLACK_SIGNING_SECRET ?? "", // Basic Information → App Credentials
+  botRefreshToken: process.env.SLACK_BOT_REFRESH_TOKEN || undefined,
+  clientId: process.env.SLACK_CLIENT_ID || undefined,
+  clientSecret: process.env.SLACK_CLIENT_SECRET || undefined,
+  botTokenExpiresAt: process.env.SLACK_BOT_TOKEN_EXPIRES_AT
+    ? Number(process.env.SLACK_BOT_TOKEN_EXPIRES_AT)
+    : undefined,
+  groupBehavior: "context", // default; use "mentions" only for an explicit least-privilege setup
+  rendering: "native", // Slack Agent streams + task timeline; use "classic" only for compatibility
+  // taskDisplay: "plan", // native task-card layout: "plan" (default) | "timeline" | "dense"
+  // Optional per-reply footer, if your policy requires one: aiDisclaimer: "AI-generated; verify important information.",
+  // welcome: "Custom first-run DM greeting", // sent once on first DM open; false disables (default: a generic greeting)
+  // reactionAck: false, // disable the 👀→✅ ack on the user's message (default on; needs reactions:write)
+  // Direct and group asks default to independent sessions + Slack threads; opt out independently:
+  // directMessageSession: "continuous",
+  // groupMessageSession: "continuous",
+  // Dev/personal bot: surface raw errors. Remove this for a customer-facing bot; details remain in logs.
+  onError: (failed) => `⚠️ ${failed.details}`,
+});