@fastagent-sh/fastagent 0.13.0 → 0.15.0

package/dist/channels/slack/invoke-turn.js

@@ -0,0 +1,63 @@
+import { log } from "../../log.js";
+import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
+const MARKDOWN_INSTRUCTION = "\n\n(Format your reply as standard Markdown. Slack renders it natively. Do not use HTML or Slack control-mention syntax such as <!here>, <!channel>, or <!everyone>.)";
+async function resolveFile(transport, fileId) {
+    const info = await transport.api.fileInfo(fileId);
+    return info.mimetype?.toLowerCase().startsWith("image/")
+        ? { image: await transport.api.fetchImage(info) }
+        : { file: await transport.api.fetchFile(info, transport.channelId, transport.filesDir) };
+}
+async function resolveInputs(transport, attachments) {
+    const images = [];
+    const files = [];
+    for (const id of attachments.primaryFileIds) {
+        const resolved = await resolveFile(transport, id);
+        if (resolved.image)
+            images.push(resolved.image);
+        if (resolved.file)
+            files.push(resolved.file);
+    }
+    const backgroundImages = [];
+    const backgroundFiles = [];
+    let lost = 0;
+    const results = await Promise.allSettled(attachments.buffered.files.map(async (ref) => ({ ref, resolved: await resolveFile(transport, ref.id) })));
+    for (const result of results) {
+        if (result.status === "fulfilled") {
+            const { ref, resolved } = result.value;
+            if (resolved.image)
+                backgroundImages.push({ image: resolved.image, ref });
+            if (resolved.file)
+                backgroundFiles.push({ file: resolved.file, ref });
+        }
+        else {
+            lost++;
+            log.warn(`${transport.label} could not load an earlier (buffered) Slack file: ${String(result.reason)}`);
+        }
+    }
+    const missingNote = missingAttachmentsNote(lost + attachments.buffered.skipped);
+    const imageManifest = backgroundImagesManifest(images.length, backgroundImages.map(({ ref }) => ref));
+    const allFiles = [
+        ...files,
+        ...backgroundFiles.map(({ file, ref }) => ({
+            ...file,
+            name: attributedFileName(file.name, ref.from, ref.messageId),
+        })),
+    ];
+    const allImages = [...images, ...backgroundImages.map(({ image }) => image)];
+    return {
+        images: allImages.length ? allImages : undefined,
+        promptSuffix: `${missingNote}${imageManifest}${attachedFilesManifest(allFiles)}`,
+    };
+}
+export async function* invokeSlackTurn(agent, session, text, transport, attachments, onCompleted, busyRetry = DEFAULT_BUSY_RETRY) {
+    let resolved;
+    try {
+        resolved = await resolveInputs(transport, attachments);
+    }
+    catch (error) {
+        yield { type: "failed", details: `could not load Slack attachment: ${String(error)}`, retryable: true };
+        return;
+    }
+    const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
+    yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
+}

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

@@ -0,0 +1,49 @@
+export type SlackGroupBehavior = "context" | "mentions";
+export interface SlackAppManifest {
+    display_information: {
+        name: string;
+        description: string;
+        background_color: string;
+    };
+    features: {
+        app_home: {
+            home_tab_enabled: boolean;
+            messages_tab_enabled: boolean;
+            messages_tab_read_only_enabled: boolean;
+        };
+        agent_view: {
+            agent_description: string;
+            suggested_prompts: Array<{
+                title: string;
+                message: string;
+            }>;
+        };
+        bot_user: {
+            display_name: string;
+            always_online: boolean;
+        };
+    };
+    oauth_config: {
+        scopes: {
+            bot: string[];
+        };
+        redirect_urls?: string[];
+    };
+    settings: {
+        event_subscriptions?: {
+            request_url: string;
+            bot_events: string[];
+        };
+        org_deploy_enabled: boolean;
+        socket_mode_enabled: boolean;
+        token_rotation_enabled: boolean;
+    };
+}
+export declare function slackBotScopes(groupBehavior: SlackGroupBehavior): string[];
+export declare function slackBotEvents(groupBehavior: SlackGroupBehavior): string[];
+export declare function buildSlackManifest(input: {
+    name: string;
+    groupBehavior: SlackGroupBehavior;
+    requestUrl?: string;
+    redirectUrl?: string;
+}): SlackAppManifest;

package/dist/channels/slack/manifest.js

@@ -0,0 +1,69 @@
+const SLACK_BASE_BOT_SCOPES = [
+    "app_mentions:read",
+    "assistant:write",
+    "chat:write",
+    "files:read",
+    "files:write",
+    "im:history",
+    "reactions:write",
+];
+const SLACK_CONTEXT_BOT_SCOPES = ["channels:history", "groups:history", "mpim:history"];
+const SLACK_BASE_BOT_EVENTS = ["app_context_changed", "app_home_opened", "app_mention", "message.im"];
+const SLACK_CONTEXT_BOT_EVENTS = ["message.channels", "message.groups", "message.mpim"];
+export function slackBotScopes(groupBehavior) {
+    return [...SLACK_BASE_BOT_SCOPES, ...(groupBehavior === "context" ? SLACK_CONTEXT_BOT_SCOPES : [])].sort();
+}
+export function slackBotEvents(groupBehavior) {
+    return [...SLACK_BASE_BOT_EVENTS, ...(groupBehavior === "context" ? SLACK_CONTEXT_BOT_EVENTS : [])].sort();
+}
+/** Slack's bot display name is more restrictive than the app name. */
+function slackBotDisplayName(name) {
+    const normalized = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "")
+        .slice(0, 80);
+    return normalized || "fastagent";
+}
+export function buildSlackManifest(input) {
+    const name = input.name.trim().slice(0, 35) || "FastAgent";
+    return {
+        display_information: {
+            name,
+            description: "A FastAgent-powered internal workspace agent.",
+            background_color: "#111827",
+        },
+        features: {
+            app_home: {
+                home_tab_enabled: false,
+                messages_tab_enabled: true,
+                messages_tab_read_only_enabled: false,
+            },
+            agent_view: {
+                agent_description: "A workspace agent powered by the files, skills, and tools in its FastAgent definition.",
+                suggested_prompts: [
+                    { title: "What can you do?", message: "What can you help me with?" },
+                    { title: "Summarize context", message: "Summarize the relevant context and propose next steps." },
+                ],
+            },
+            bot_user: { display_name: slackBotDisplayName(name), always_online: false },
+        },
+        oauth_config: {
+            scopes: { bot: slackBotScopes(input.groupBehavior) },
+            ...(input.redirectUrl ? { redirect_urls: [input.redirectUrl] } : {}),
+        },
+        settings: {
+            ...(input.requestUrl
+                ? {
+                    event_subscriptions: {
+                        request_url: input.requestUrl,
+                        bot_events: slackBotEvents(input.groupBehavior),
+                    },
+                }
+                : {}),
+            org_deploy_enabled: false,
+            socket_mode_enabled: false,
+            token_rotation_enabled: true,
+        },
+    };
+}

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;
+}