@fastagent-sh/fastagent 0.14.0 → 0.15.0

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

@@ -0,0 +1,67 @@
+/** Minimal Slack Events/Web API shapes used by the first-party channel. Unknown fields remain ignored. */
+export interface SlackFile {
+    id?: string;
+    name?: string;
+    title?: string;
+    mimetype?: string;
+    filetype?: string;
+    pretty_type?: string;
+    size?: number;
+    mode?: string;
+    is_external?: boolean;
+    external_type?: string;
+    file_access?: string;
+    url_private?: string;
+    url_private_download?: string;
+}
+interface SlackAppContextEntity {
+    type?: string;
+    value?: string;
+    team_id?: string;
+}
+export interface SlackMessageEvent {
+    type?: string;
+    subtype?: string;
+    hidden?: boolean;
+    user?: string;
+    bot_id?: string;
+    text?: string;
+    ts?: string;
+    event_ts?: string;
+    thread_ts?: string;
+    channel?: string;
+    channel_type?: string;
+    /** `app_home_opened` only: which App Home tab was opened (`messages` signals a DM open). */
+    tab?: string;
+    team?: string;
+    files?: SlackFile[];
+    /** Included on message.im when the Agent messaging experience is enabled. */
+    app_context?: {
+        entities?: SlackAppContextEntity[];
+    };
+}
+export interface SlackEventEnvelope {
+    type?: string;
+    challenge?: string;
+    team_id?: string;
+    context_team_id?: string;
+    enterprise_id?: string;
+    api_app_id?: string;
+    event_id?: string;
+    event_time?: number;
+    event?: SlackMessageEvent;
+    authorizations?: Array<{
+        team_id?: string;
+        enterprise_id?: string;
+        user_id?: string;
+        is_bot?: boolean;
+    }>;
+}
+/** A routed Slack turn. `threadTs:null` explicitly sends at channel top level. */
+export interface SlackRoute {
+    session?: string;
+    channelId?: string;
+    threadTs?: string | null;
+    text?: string;
+}
+export {};

package/dist/channels/slack/model.js

@@ -0,0 +1,2 @@
+/** Minimal Slack Events/Web API shapes used by the first-party channel. Unknown fields remain ignored. */
+export {};

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

@@ -0,0 +1,41 @@
+import { createSlackApp, exchangeSlackOAuthCode, updateSlackAppManifest } from "./config-api.ts";
+import { type SlackGroupBehavior } from "./manifest.ts";
+import { type SlackOnboardingState } from "./onboarding-state.ts";
+export interface SlackOnboardIO {
+    note(message: string): void;
+    openUrl(url: string): void;
+    /** Wait for the one OAuth redirect. Implementations must validate only the path; core validates state. */
+    waitForOAuth(): Promise<{
+        code?: string;
+        state?: string;
+        error?: string;
+    }>;
+    /** Stage runtime-only credentials into the gitignored .env. */
+    writeRuntimeSecrets(values: {
+        botToken?: string;
+        botRefreshToken?: string;
+        botTokenExpiresAt?: number;
+        clientId?: string;
+        clientSecret?: string;
+        signingSecret?: string;
+    }): Promise<void>;
+}
+export interface SlackOnboardInput {
+    stateRoot: string;
+    state: SlackOnboardingState;
+    requestUrl: string;
+    redirectUrl: string;
+}
+/** Create/resume one internal Slack app and complete its workspace OAuth installation. */
+export declare function onboardSlackApp(input: SlackOnboardInput, io: SlackOnboardIO, deps?: {
+    createApp?: typeof createSlackApp;
+    updateManifest?: typeof updateSlackAppManifest;
+    exchangeCode?: typeof exchangeSlackOAuthCode;
+}): Promise<SlackOnboardingState>;
+export declare function newSlackOnboardingState(input: {
+    appName: string;
+    groupBehavior: SlackGroupBehavior;
+    configToken: string;
+    configRefreshToken: string;
+    now?: number;
+}): SlackOnboardingState;

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/owned-threads.d.ts

@@ -0,0 +1,6 @@
+interface OwnedSlackThreads {
+    has(teamId: string, channelId: string, rootTs: string): boolean;
+    add(teamId: string, channelId: string, rootTs: string): void;
+}
+export declare function createOwnedSlackThreads(path: string, label?: string, now?: () => number): OwnedSlackThreads;
+export {};

package/dist/channels/slack/owned-threads.js

@@ -0,0 +1,43 @@
+/** Durable roots of Slack group threads entered by an explicit summon. */
+import { log } from "../../log.js";
+import { loadStateFile, saveStateFile } from "../state.js";
+function key(teamId, channelId, rootTs) {
+    return `${teamId}:${channelId}:${rootTs}`;
+}
+function isRecord(value) {
+    const record = value;
+    return (typeof record?.teamId === "string" &&
+        typeof record.channelId === "string" &&
+        typeof record.rootTs === "string" &&
+        typeof record.createdAt === "number" &&
+        Number.isFinite(record.createdAt));
+}
+export function createOwnedSlackThreads(path, label = "[slack]", now = Date.now) {
+    const raw = loadStateFile(path);
+    let records = new Map();
+    if (raw !== undefined) {
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.entries(raw).every(([id, record]) => isRecord(record) && key(record.teamId, record.channelId, record.rootTs) === id)) {
+            records = new Map(Object.entries(raw));
+        }
+        else {
+            log.warn(`${label} unexpected shape in ${path} — starting with no managed Slack threads`);
+        }
+    }
+    return {
+        has(teamId, channelId, rootTs) {
+            return records.has(key(teamId, channelId, rootTs));
+        },
+        add(teamId, channelId, rootTs) {
+            const id = key(teamId, channelId, rootTs);
+            if (records.has(id))
+                return;
+            const next = new Map(records);
+            next.set(id, { teamId, channelId, rootTs, createdAt: now() });
+            saveStateFile(path, Object.fromEntries(next));
+            records = next;
+        },
+    };
+}

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

@@ -0,0 +1,23 @@
+import type { SlackEventEnvelope, SlackMessageEvent, SlackRoute } from "./model.ts";
+export type { SlackEventEnvelope, SlackFile, SlackMessageEvent, SlackRoute } from "./model.ts";
+/** 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. */
+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,81 @@
+import { codePointPrefix } from "../text.js";
+const HUMAN_MESSAGE_SUBTYPES = new Set(["file_share", "thread_broadcast"]);
+/** 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. */
+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 codePointPrefix(text.replace(/\s+/g, " ").trim(), 280);
+}
+/** 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,24 @@
+/** 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, type SlackTaskDisplayMode } 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;
+    taskDisplay?: SlackTaskDisplayMode;
+    label?: string;
+}): Promise<void>;