@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/channels/slack/onboard.js

@@ -0,0 +1,120 @@
+import { randomBytes } from "node:crypto";
+import { createSlackApp, exchangeSlackOAuthCode, SlackConfigApiError, updateSlackAppManifest } from "./config-api.js";
+import { buildSlackManifest, slackBotScopes } from "./manifest.js";
+import { currentSlackConfigToken, writeSlackOnboardingState } from "./onboarding-state.js";
+/** Create/resume one internal Slack app and complete its workspace OAuth installation. */
+export async function onboardSlackApp(input, io, deps = {}) {
+    let state = input.state;
+    const current = await currentSlackConfigToken(input.stateRoot, state);
+    state = current.state;
+    const manifest = buildSlackManifest({
+        name: state.appName,
+        groupBehavior: state.groupBehavior,
+        requestUrl: input.requestUrl,
+        redirectUrl: input.redirectUrl,
+    });
+    if (!state.appId) {
+        if (state.createAttemptedAt) {
+            throw new Error(`a Slack app creation request started at ${state.createAttemptedAt}, but no app ID was returned. ` +
+                "Inspect https://api.slack.com/apps before retrying; if an app exists, delete that incomplete app first, then remove the local Slack onboarding state and re-run");
+        }
+        io.note("Creating the internal Slack app from its FastAgent manifest…");
+        // Record BEFORE the non-idempotent API call. A transport/internal failure may have created the app;
+        // refusing a blind retry is safer than silently producing duplicates.
+        state = { ...state, createAttemptedAt: new Date().toISOString() };
+        await writeSlackOnboardingState(input.stateRoot, state);
+        let created;
+        try {
+            created = await (deps.createApp ?? createSlackApp)(current.token, manifest);
+        }
+        catch (error) {
+            const ambiguous = !(error instanceof SlackConfigApiError) ||
+                ["fatal_error", "internal_error", "request_timeout", "service_unavailable", "failed_creating_app"].includes(error.code);
+            if (!ambiguous) {
+                state = { ...state, createAttemptedAt: undefined };
+                await writeSlackOnboardingState(input.stateRoot, state);
+            }
+            throw error;
+        }
+        state = {
+            ...state,
+            appId: created.appId,
+            createAttemptedAt: undefined,
+            clientId: created.clientId,
+            clientSecret: created.clientSecret,
+            signingSecret: created.signingSecret,
+        };
+        // Irreversible boundary first: a cancellation or .env write failure can resume without creating a duplicate.
+        await writeSlackOnboardingState(input.stateRoot, state);
+        io.note(`Created Slack app ${created.appId}; credentials captured locally.`);
+    }
+    else {
+        if (!state.clientId || !state.clientSecret) {
+            throw new Error(`Slack app ${state.appId} exists but OAuth client credentials are no longer available — ` +
+                "the app appears already installed; set SLACK_BOT_TOKEN/SLACK_SIGNING_SECRET in .env or remove the app and onboarding state to start over");
+        }
+        io.note(`Resuming Slack app ${state.appId}; refreshing its temporary setup URLs…`);
+        await (deps.updateManifest ?? updateSlackAppManifest)(current.token, state.appId, manifest);
+    }
+    if (state.signingSecret) {
+        await io.writeRuntimeSecrets({ signingSecret: state.signingSecret });
+        state = { ...state, signingSecret: undefined };
+        await writeSlackOnboardingState(input.stateRoot, state);
+    }
+    if (!state.appId || !state.clientId || !state.clientSecret) {
+        throw new Error("Slack onboarding state lost app OAuth credentials before installation");
+    }
+    const oauthState = randomBytes(24).toString("hex");
+    const authorize = new URL("https://slack.com/oauth/v2/authorize");
+    authorize.searchParams.set("client_id", state.clientId);
+    authorize.searchParams.set("scope", slackBotScopes(state.groupBehavior).join(","));
+    authorize.searchParams.set("redirect_uri", input.redirectUrl);
+    authorize.searchParams.set("state", oauthState);
+    io.note(`Approve the internal app installation in Slack: ${authorize}`);
+    io.openUrl(authorize.toString());
+    const callback = await io.waitForOAuth();
+    if (callback.error)
+        throw new Error("Slack OAuth installation was not approved");
+    if (!callback.code)
+        throw new Error("Slack OAuth callback carried no authorization code");
+    if (!callback.state || callback.state !== oauthState)
+        throw new Error("Slack OAuth callback state mismatch");
+    const oauth = await (deps.exchangeCode ?? exchangeSlackOAuthCode)({
+        clientId: state.clientId,
+        clientSecret: state.clientSecret,
+        code: callback.code,
+        redirectUrl: input.redirectUrl,
+    });
+    if (oauth.appId !== state.appId)
+        throw new Error("Slack OAuth installed a different app than the manifest app");
+    if (slackBotScopes(state.groupBehavior).some((scope) => !oauth.scopes.includes(scope))) {
+        throw new Error("Slack OAuth completed without all required bot scopes; re-run fastagent add slack to reinstall");
+    }
+    await io.writeRuntimeSecrets({
+        botToken: oauth.botToken,
+        botRefreshToken: oauth.botRefreshToken,
+        botTokenExpiresAt: oauth.botTokenExpiresAt,
+        clientId: state.clientId,
+        clientSecret: state.clientSecret,
+    });
+    state = {
+        ...state,
+        clientSecret: undefined,
+        teamId: oauth.teamId,
+        teamName: oauth.teamName,
+        installedAt: new Date().toISOString(),
+    };
+    await writeSlackOnboardingState(input.stateRoot, state);
+    return state;
+}
+export function newSlackOnboardingState(input) {
+    return {
+        version: 1,
+        appName: input.appName,
+        groupBehavior: input.groupBehavior,
+        configToken: input.configToken,
+        configRefreshToken: input.configRefreshToken,
+        // Slack config access tokens expire in 12 hours; use 11h so registration rotates before the edge.
+        configTokenExpiresAt: (input.now ?? Date.now()) + 11 * 60 * 60_000,
+    };
+}

package/dist/channels/slack/onboarding-state.d.ts

@@ -0,0 +1,31 @@
+import type { SlackGroupBehavior } from "./manifest.ts";
+export interface SlackOnboardingState {
+    version: 1;
+    appName: string;
+    groupBehavior: SlackGroupBehavior;
+    appId?: string;
+    /** Set before apps.manifest.create; without an appId it blocks blind duplicate-creation retries. */
+    createAttemptedAt?: string;
+    clientId?: string;
+    /** Kept only while OAuth installation is unfinished, then deleted. */
+    clientSecret?: string;
+    /** Kept only until it has been staged into .env, then deleted. */
+    signingSecret?: string;
+    configToken: string;
+    configRefreshToken: string;
+    configTokenExpiresAt: number;
+    teamId?: string;
+    teamName?: string;
+    installedAt?: string;
+}
+export declare function readSlackOnboardingState(stateRoot: string): Promise<SlackOnboardingState | undefined>;
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh token. */
+export declare function writeSlackOnboardingState(stateRoot: string, state: SlackOnboardingState): Promise<void>;
+export declare function currentSlackConfigToken(stateRoot: string, state: SlackOnboardingState, options?: {
+    now?: number;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}): Promise<{
+    token: string;
+    state: SlackOnboardingState;
+}>;

package/dist/channels/slack/onboarding-state.js

@@ -0,0 +1,69 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { rotateSlackConfigToken } from "./config-api.js";
+function slackOnboardingStatePath(stateRoot) {
+    return join(stateRoot, "channels", "slack", "onboarding.json");
+}
+function validState(value) {
+    const state = value;
+    return (typeof state === "object" &&
+        state !== null &&
+        state.version === 1 &&
+        typeof state.appName === "string" &&
+        (state.groupBehavior === "context" || state.groupBehavior === "mentions") &&
+        typeof state.configToken === "string" &&
+        typeof state.configRefreshToken === "string" &&
+        typeof state.configTokenExpiresAt === "number");
+}
+export async function readSlackOnboardingState(stateRoot) {
+    const file = slackOnboardingStatePath(stateRoot);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`cannot read Slack onboarding state ${file}: ${error.message}`);
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (!validState(value))
+            throw new Error("unexpected shape/version");
+        return value;
+    }
+    catch (error) {
+        throw new Error(`invalid Slack onboarding state ${file}: ${error.message}`);
+    }
+}
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh token. */
+export async function writeSlackOnboardingState(stateRoot, state) {
+    const file = slackOnboardingStatePath(stateRoot);
+    await mkdir(dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        await chmod(temp, 0o600);
+        await rename(temp, file);
+        await chmod(file, 0o600);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+export async function currentSlackConfigToken(stateRoot, state, options = {}) {
+    const now = options.now ?? Date.now();
+    if (state.configTokenExpiresAt > now + 5 * 60_000)
+        return { token: state.configToken, state };
+    const rotated = await rotateSlackConfigToken(state.configRefreshToken, options);
+    const next = {
+        ...state,
+        configToken: rotated.token,
+        configRefreshToken: rotated.refreshToken,
+        configTokenExpiresAt: rotated.expiresAt,
+        teamId: state.teamId ?? rotated.teamId,
+    };
+    await writeSlackOnboardingState(stateRoot, next);
+    return { token: next.configToken, state: next };
+}

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

@@ -0,0 +1,38 @@
+import type { SlackEventEnvelope, SlackMessageEvent, SlackRoute } from "./model.ts";
+export type { SlackEventEnvelope, SlackFile, SlackMessageEvent, SlackRoute } from "./model.ts";
+/** Does this text address ANYONE — a user, a broadcast, or a user group? The §3 discussion guard. */
+export declare function hasSlackMention(text: string): boolean;
+/** Does this text mention a USER? Distinct from the above because only a user mention can be the bot:
+ *  a broadcast never is, so it must not make a message look like a possible summon. */
+export declare function hasSlackUserMention(text: string): boolean;
+/** Does this text mention this specific user (either form)? The id is MATCHED, not interpreted. */
+export declare function mentionsSlackUser(text: string, userId: string): boolean;
+/** Strip every mention, e.g. before matching a bare command word or building a title. */
+export declare function stripSlackMentions(text: string, replacement?: string): string;
+/** Slack message events whose content represents a new human message rather than a mutation/service event. */
+export declare function isSlackHumanMessage(event: SlackMessageEvent | undefined): event is SlackMessageEvent & {
+    channel: string;
+    ts: string;
+    user: string;
+};
+export declare function isSlackDirectMessage(event: SlackMessageEvent): boolean;
+export declare function isSlackGroupMessage(event: SlackMessageEvent): boolean;
+/** Stable install identity. Events API normally supplies team_id; the fallbacks cover Grid envelopes. */
+export declare function slackTeamId(envelope: SlackEventEnvelope): string | undefined;
+export declare function slackFileIds(event: SlackMessageEvent): string[];
+/** Text plus a structural marker for file-only or captioned file shares. */
+export declare function slackMessageText(event: SlackMessageEvent): string;
+export declare function slackSenderLabel(event: SlackMessageEvent): string;
+/** Main-channel discussion and each concrete thread are independent context buckets.
+ *
+ *  The `:root:` segment carries `thread_ts`, which in Slack IS the thread's parent message and is
+ *  stable for the life of the thread — unrelated to the `<chat>:root:<root_id>` shape Feishu retired
+ *  (its `root_id` moves with the reply chain, so it could not identify a side conversation at all).
+ *  Same token, different platform meaning; the key is left as-is because renaming it would discard
+ *  live context buckets for no semantic gain. */
+export declare function slackPlaceKey(teamId: string, event: Pick<SlackMessageEvent, "channel" | "thread_ts">): string;
+export declare function slackBufferText(text: string): string;
+/** Canonical prompt envelope. The channel/thread ids also give slack-send an explicit delivery target. */
+export declare function slackEnvelope(envelope: SlackEventEnvelope): string;
+/** Default explicit-summon policy: DMs and app_mention events only. */
+export declare function defaultSlackRoute(envelope: SlackEventEnvelope): SlackRoute | null;

package/dist/channels/slack/parse.js

@@ -0,0 +1,124 @@
+import { BUFFER_LINE_MAX_CHARS } from "../context-buffer.js";
+import { codePointPrefix, truncateCodePointPrefix } from "../text.js";
+const HUMAN_MESSAGE_SUBTYPES = new Set(["file_share", "thread_broadcast"]);
+/**
+ * Both forms Slack writes a mention in: `<@U123>` and the labelled `<@U123|name>`. ONE definition,
+ * because the forms have to agree across every site that reads them — the "@-mentions only other
+ * people is discussion" guard, the structural bot-summon check, the stop-command strip, and the
+ * assistant-thread title. They drifted once: widening the first two while the strip still matched only
+ * the bare form turned `<@bot|name> stop` into an ordinary turn, queued behind the run it meant to stop.
+ */
+const mentionSource = (idPattern) => String.raw `<@${idPattern}(?:\|[^>]*)?>`;
+const USER_MENTION = mentionSource("[A-Z0-9]+");
+/** Broadcasts and user groups address people too: `<!here>`, `<!channel>`, `<!everyone>`,
+ *  `<!subteam^S123|@team>`. Feishu's twin guard counts every mention, and the summon rule is supposed
+ *  to be the same on both — without these, "@here can someone look at this" in a thread the agent takes
+ *  part in reads as a bare message addressed to IT, and gets answered. */
+const ANY_MENTION = String.raw `(?:${USER_MENTION}|<!(?:here|channel|everyone)(?:\|[^>]*)?>|<!subteam\^[^>]*>)`;
+/** Does this text address ANYONE — a user, a broadcast, or a user group? The §3 discussion guard. */
+export function hasSlackMention(text) {
+    return new RegExp(ANY_MENTION, "i").test(text);
+}
+/** Does this text mention a USER? Distinct from the above because only a user mention can be the bot:
+ *  a broadcast never is, so it must not make a message look like a possible summon. */
+export function hasSlackUserMention(text) {
+    return new RegExp(USER_MENTION, "i").test(text);
+}
+/** Escape a platform-supplied id before it becomes part of a pattern. Slack ids are alphanumeric in
+ *  practice, but `auth.test`'s value is not validated here, and this runs on every group message: an
+ *  unescaped metacharacter would either mis-answer the summon question or throw on the acceptance
+ *  path, which Slack answers with an endless redelivery. */
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Does this text mention this specific user (either form)? The id is MATCHED, not interpreted. */
+export function mentionsSlackUser(text, userId) {
+    return new RegExp(mentionSource(escapeRegExp(userId)), "i").test(text);
+}
+/** Strip every mention, e.g. before matching a bare command word or building a title. */
+export function stripSlackMentions(text, replacement = " ") {
+    return text.replace(new RegExp(ANY_MENTION, "gi"), replacement);
+}
+/** Slack message events whose content represents a new human message rather than a mutation/service event. */
+export function isSlackHumanMessage(event) {
+    if (!event || (event.type !== "message" && event.type !== "app_mention"))
+        return false;
+    if (!event.channel || !event.ts || !event.user || event.bot_id || event.hidden)
+        return false;
+    return event.subtype === undefined || HUMAN_MESSAGE_SUBTYPES.has(event.subtype);
+}
+export function isSlackDirectMessage(event) {
+    return event.channel_type === "im";
+}
+export function isSlackGroupMessage(event) {
+    return !isSlackDirectMessage(event) && (event.type === "app_mention" || event.channel_type !== undefined);
+}
+/** Stable install identity. Events API normally supplies team_id; the fallbacks cover Grid envelopes. */
+export function slackTeamId(envelope) {
+    return (envelope.team_id ??
+        envelope.event?.team ??
+        envelope.authorizations?.find((authorization) => authorization.team_id)?.team_id ??
+        envelope.context_team_id ??
+        envelope.enterprise_id ??
+        envelope.authorizations?.find((authorization) => authorization.enterprise_id)?.enterprise_id);
+}
+export function slackFileIds(event) {
+    return [...new Set((event.files ?? []).flatMap((file) => (typeof file.id === "string" ? [file.id] : [])))];
+}
+/** Text plus a structural marker for file-only or captioned file shares. */
+export function slackMessageText(event) {
+    const text = event.text?.trim() ?? "";
+    const files = slackFileIds(event).length;
+    if (files === 0)
+        return text;
+    const marker = `[${files} attached file${files === 1 ? "" : "s"}]`;
+    return text ? `${text}\n${marker}` : marker;
+}
+export function slackSenderLabel(event) {
+    return `user ${event.user ?? "unknown"}`;
+}
+/** Main-channel discussion and each concrete thread are independent context buckets.
+ *
+ *  The `:root:` segment carries `thread_ts`, which in Slack IS the thread's parent message and is
+ *  stable for the life of the thread — unrelated to the `<chat>:root:<root_id>` shape Feishu retired
+ *  (its `root_id` moves with the reply chain, so it could not identify a side conversation at all).
+ *  Same token, different platform meaning; the key is left as-is because renaming it would discard
+ *  live context buckets for no semantic gain. */
+export function slackPlaceKey(teamId, event) {
+    const base = `${teamId}:${event.channel ?? "unknown-channel"}`;
+    return event.thread_ts ? `${base}:root:${event.thread_ts}` : base;
+}
+export function slackBufferText(text) {
+    return truncateCodePointPrefix(text.replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
+}
+/** Canonical prompt envelope. The channel/thread ids also give slack-send an explicit delivery target. */
+export function slackEnvelope(envelope) {
+    const event = envelope.event;
+    if (!event?.channel)
+        return "";
+    const team = slackTeamId(envelope) ?? "unknown-team";
+    const direct = isSlackDirectMessage(event);
+    const meta = [
+        `team ${team}`,
+        `channel ${event.channel} (${direct ? "direct" : "group"})`,
+        event.thread_ts ? `thread ${event.thread_ts}` : undefined,
+        event.ts ? `msg ${event.ts}` : undefined,
+        event.user ? `from user ${event.user}` : undefined,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    const activeContext = (event.app_context?.entities ?? [])
+        .filter((entity) => entity.type && entity.value)
+        .slice(0, 5)
+        .map((entity) => `${codePointPrefix(String(entity.type).replace(/\s+/g, " "), 80)}=` +
+        codePointPrefix(String(entity.value).replace(/\s+/g, " "), 200))
+        .join(", ");
+    const scope = direct ? "" : "\n[group chat — multiple people; recent discussion is sender-prefixed]";
+    const context = activeContext ? `\n[Slack context currently open for the user: ${activeContext}]` : "";
+    return `[slack: ${meta}]${scope}${context}\n${slackMessageText(event)}`;
+}
+/** Default explicit-summon policy: DMs and app_mention events only. */
+export function defaultSlackRoute(envelope) {
+    const event = envelope.event;
+    if (!isSlackHumanMessage(event))
+        return null;
+    return isSlackDirectMessage(event) || event.type === "app_mention" ? {} : null;
+}

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

@@ -0,0 +1,23 @@
+/** Slack reply rendering: native Agent streams first, rate-safe edited-message compatibility second. */
+import type { AgentEvent } from "../../agent.ts";
+import { type ChannelFailure, defaultErrorMessage } from "../preview-kit.ts";
+import { type SlackApi, type SlackTarget } from "./slack-api.ts";
+export type SlackFailure = ChannelFailure;
+export type SlackRendering = "native" | "classic";
+export { defaultErrorMessage };
+/** 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 declare function sanitizeSlackMarkdown(markdown: string): string;
+/** Settle a queue/drop/defer notice. These are authored plain strings, so the basic text API is enough. */
+export declare function settleSlackPreview(api: SlackApi, target: SlackTarget, previewTs: string | undefined, text: string): Promise<void>;
+export declare function streamSlackReply(events: AsyncIterable<AgentEvent>, api: SlackApi, target: SlackTarget, formatError: (failure: SlackFailure) => string | undefined, options?: {
+    rendering?: SlackRendering;
+    initialPreviewTs?: string;
+    threadTitle?: string;
+    disclaimer?: string | false;
+    label?: string;
+}): Promise<void>;