@fastagent-sh/fastagent 0.14.0 → 0.16.0

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

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

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

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

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

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

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

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

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

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

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;