@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/channels/slack/manifest.js

@@ -1,3 +1,4 @@
+import { stripEdges } from "../../strip-edges.js";
 // One posture, as on Feishu: the agent hears the channels it is in (participant-model.md §2), so the history scopes
 // and their message events are part of every app. `users:read` names the people in the history a turn reads.
 const SLACK_BOT_SCOPES = [
@@ -22,7 +23,7 @@ const SLACK_BOT_EVENTS = [
     "message.groups",
     "message.mpim",
 ];
-export function slackBotScopes() {
+function slackBotScopes() {
     return [...SLACK_BOT_SCOPES].sort();
 }
 function slackBotEvents() {
@@ -30,11 +31,7 @@ function slackBotEvents() {
 }
 /** 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);
+    const normalized = stripEdges(name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-"), (char) => !/[a-z0-9]/.test(char)).slice(0, 80);
     return normalized || "fastagent";
 }
 export function buildSlackManifest(input) {
@@ -62,22 +59,21 @@ export function buildSlackManifest(input) {
         },
         oauth_config: {
             scopes: { bot: slackBotScopes() },
-            ...(input.redirectUrl ? { redirect_urls: [input.redirectUrl] } : {}),
         },
         settings: {
-            ...(input.requestUrl
-                ? {
-                    event_subscriptions: {
-                        request_url: input.requestUrl,
-                        bot_events: slackBotEvents(),
-                    },
-                }
-                : {}),
+            event_subscriptions: {
+                ...(input.ingress === "webhook" ? { request_url: input.requestUrl } : {}),
+                bot_events: slackBotEvents(),
+            },
             org_deploy_enabled: false,
-            socket_mode_enabled: false,
+            socket_mode_enabled: input.ingress === "connection",
             // Off, and Slack makes the alternative permanent: an app with rotation on can never turn it off
             // (`cannot_disable_once_enabled`, verified against the API).
             token_rotation_enabled: false,
         },
     };
 }
+/** The page that creates an app from `manifest`, filled in: the person picks a workspace and clicks Create. */
+export function slackManifestLink(manifest) {
+    return `https://api.slack.com/apps?new_app=1&manifest_json=${encodeURIComponent(JSON.stringify(manifest))}`;
+}

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

@@ -1,32 +1,46 @@
-import { needs } from "@fastagent-sh/fastagent";
-import { slackChannel } from "@fastagent-sh/fastagent/slack";
+import { byIngress, needs } from "@fastagent-sh/fastagent";
+import { type SlackChannelOptions, slackChannel, slackSocketChannel } from "@fastagent-sh/fastagent/slack";
 
-// Slack HTTP Events API channel. Setup:
-//   1. Create a Slack app at https://api.slack.com/apps and add a bot user.
-//   2. Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history,
-//      files:read, files:write, reactions:write, channels:history, groups:history, mpim:history,
-//      and users:read.
-//   3. Event Subscriptions: app_home_opened, app_context_changed, app_mention, message.im,
-//      message.channels, message.groups, and message.mpim.
-//      Set Request URL to https://<host>/slack.
-//   4. Install the app (reinstall after changing scopes) and leave token rotation OFF: it cannot be
-//      turned off again, and this channel takes one long-lived Bot User OAuth Token.
+// Slack channel. `fastagent channels setup slack` creates the app (from a manifest link that sets the scopes, the
+// events and the Socket Mode switch this file needs) and keeps its credentials.
 //
-// `needs` declares the env vars this channel reads: fastagent carries them to a deployed box and
-// refuses to serve while one is unset.
-export default needs(["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"], (secrets) =>
-  slackChannel({
-    botToken: secrets.SLACK_BOT_TOKEN, // OAuth & Permissions → Bot User OAuth Token (xoxb-…)
-    signingSecret: secrets.SLACK_SIGNING_SECRET, // Basic Information → App Credentials
-    // Slack Agent stream; its inline tool traces show each call's first argument and stay in the
-    // delivered message. "classic" settles into the answer alone (and gives up native streaming).
-    rendering: "native",
-    // Optional per-reply footer, if your policy requires one: aiDisclaimer: "AI-generated; verify important information.",
-    // welcome: "Custom first-run DM greeting", // sent once on first DM open; false disables (default: a generic greeting)
-    // reactionAck: false, // disable the 👀→✅ ack on the user's message (default on; needs reactions:write)
-    // An answer attaches to its question with a thread (Slack has no quote primitive), and that thread is
-    // one conversation, with a session of its own: see docs/design/participant-model.md.
-    // Dev/personal bot: surface raw errors. Remove this for a customer-facing bot; details remain in logs.
-    onError: (failed) => `⚠️ ${failed.details}`,
-  }),
-);
+// How it receives is the instance's choice, `channels.slack.ingress` in its fastagent.json (webhook | connection).
+// Unset, `fastagent dev` opens a Socket Mode connection OUT (no public URL, no tunnel), and everything else —
+// `fastagent start`, every deployment — receives by webhook at POST /slack, the way a host that wakes on a request is
+// reached. An app in Socket Mode receives over the socket ALONE, so an app serves one instance, and a deployment that
+// receives by webhook has an app of its own.
+//
+// Leave token rotation OFF: it cannot be turned off again, and this channel takes one long-lived Bot User OAuth Token.
+
+// Your policy, the same whichever way the channel receives.
+const policy: Pick<SlackChannelOptions, "rendering" | "onError"> = {
+  // Slack Agent stream; its inline tool traces show each call's first argument and stay in the delivered message.
+  // "classic" settles into the answer alone (and gives up native streaming).
+  rendering: "native",
+  // Optional per-reply footer, if your policy requires one: aiDisclaimer: "AI-generated; verify important information.",
+  // welcome: "Custom first-run DM greeting", // sent once on first DM open; false disables (default: a generic greeting)
+  // reactionAck: false, // disable the 👀→✅ ack on the user's message (default on; needs reactions:write)
+  // An answer attaches to its question with a thread (Slack has no quote primitive), and that thread is
+  // one conversation, with a session of its own: see docs/design/participant-model.md.
+  // Dev/personal bot: surface raw errors. Remove this for a customer-facing bot; details remain in logs.
+  onError: (failed) => `⚠️ ${failed.details}`,
+};
+
+// Each way's `needs` declares the env vars it reads: an instance is asked only for its way's, and refused to serve
+// while a required one is unset.
+export default byIngress({
+  webhook: needs(["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"], (secrets) =>
+    slackChannel({
+      botToken: secrets.SLACK_BOT_TOKEN, // Install App → Bot User OAuth Token (xoxb-…)
+      signingSecret: secrets.SLACK_SIGNING_SECRET, // Basic Information → Signing Secret
+      ...policy,
+    }),
+  ),
+  connection: needs(["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"], (secrets) =>
+    slackSocketChannel({
+      botToken: secrets.SLACK_BOT_TOKEN,
+      appToken: secrets.SLACK_APP_TOKEN, // Basic Information → App-Level Tokens (xapp-…, connections:write)
+      ...policy,
+    }),
+  ),
+});

package/dist/channels/slack/scaffold/slack-send.ts

@@ -1,4 +1,4 @@
-import { Type } from "@earendil-works/pi-ai";
+import { obj, opt, str } from "@earendil-works/pi-schema";
 import { defineTool } from "@earendil-works/pi-durable";
 import { needs } from "@fastagent-sh/fastagent";
 import { slackTransport } from "@fastagent-sh/fastagent/slack";
@@ -22,13 +22,13 @@ export default needs(["SLACK_BOT_TOKEN"], ({ SLACK_BOT_TOKEN }) =>
       "one of `text`/`path`. channelId/threadTs come from the [slack: …] context line in a chat turn; a " +
       "scheduled or woken message has no context line, so name the destination in your instruction. A user ID " +
       "(U…) as channelId messages that user's DM; a file upload needs the DM channel ID (D…) the text send reports.",
-    parameters: Type.Object({
-      channelId: Type.String({ description: "target Slack channel ID, or a user ID (U…) to message that user's DM" }),
-      text: Type.Optional(Type.String({ description: "standard Markdown message text" })),
-      path: Type.Optional(Type.String({ description: "absolute path of a local file to upload" })),
-      title: Type.Optional(Type.String({ description: "file title (file mode only)" })),
-      initialComment: Type.Optional(Type.String({ description: "message posted with the file (file mode only)" })),
-      threadTs: Type.Optional(Type.String({ description: "thread parent timestamp, if replying in a thread" })),
+    parameters: obj({
+      channelId: str({ description: "target Slack channel ID, or a user ID (U…) to message that user's DM" }),
+      text: opt(str({ description: "standard Markdown message text" })),
+      path: opt(str({ description: "absolute path of a local file to upload" })),
+      title: opt(str({ description: "file title (file mode only)" })),
+      initialComment: opt(str({ description: "message posted with the file (file mode only)" })),
+      threadTs: opt(str({ description: "thread parent timestamp, if replying in a thread" })),
     }),
     execute: async ({ channelId, text, path, title, initialComment, threadTs }) => {
       if ((text === undefined) === (path === undefined)) throw new Error("pass exactly one of `text` or `path`");

package/dist/channels/slack/scaffold/slack-threads.ts

@@ -1,4 +1,4 @@
-import { Type } from "@earendil-works/pi-ai";
+import { obj, opt, str } from "@earendil-works/pi-schema";
 import { defineTool } from "@earendil-works/pi-durable";
 import { sessionIdOf } from "@fastagent-sh/fastagent";
 import { slackThreads } from "@fastagent-sh/fastagent/slack";
@@ -14,9 +14,9 @@ export default defineTool({
     "question here concerns something discussed in another thread, such as whether a problem raised there was " +
     "resolved: the answer is often what a person wrote in the thread. Only this channel's threads can be read, and " +
     "only in a channel turn.",
-  parameters: Type.Object({
-    threadId: Type.Optional(
-      Type.String({
+  parameters: obj({
+    threadId: opt(
+      str({
         description: "a thread id from the list (its first message's ts, like 1712345678.123456); omit it to list",
       }),
     ),

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

@@ -0,0 +1,7 @@
+/**
+ * What a Slack app's setup asks for (channels/setup.ts). The app is created from a manifest link the person opens, so
+ * its scopes, events and Socket Mode switch are what FastAgent needs; the values only they can read off its pages are
+ * pasted: the bot token, and for the way the app receives, its app-level token (Socket Mode) or its signing secret.
+ */
+import { type ChannelSetup } from "../setup.ts";
+export declare const slackSetup: ChannelSetup;

package/dist/channels/slack/setup.js

@@ -0,0 +1,119 @@
+/**
+ * What a Slack app's setup asks for (channels/setup.ts). The app is created from a manifest link the person opens, so
+ * its scopes, events and Socket Mode switch are what FastAgent needs; the values only they can read off its pages are
+ * pasted: the bot token, and for the way the app receives, its app-level token (Socket Mode) or its signing secret.
+ */
+import { SetupRefused, pasteOne } from "../setup.js";
+import { buildSlackManifest, slackManifestLink } from "./manifest.js";
+import { SlackApiError, createSlackApi } from "./slack-api.js";
+import { TerminalSocketError, openSlackConnection } from "./socket.js";
+const SLACK_API = "https://slack.com/api";
+/** Stands in for the Request URL of an app that receives by webhook, until the person sets the real one. */
+const PLACEHOLDER_REQUEST_URL = "https://example.invalid/slack";
+export const slackSetup = ({ way, appName, publicUrl }) => {
+    const manifest = way === "connection"
+        ? buildSlackManifest({ name: `FastAgent ${appName}`, ingress: "connection" })
+        : buildSlackManifest({
+            name: `FastAgent ${appName}`,
+            ingress: "webhook",
+            requestUrl: publicUrl === undefined ? PLACEHOLDER_REQUEST_URL : `${publicUrl}/slack`,
+        });
+    const values = [
+        pasteOne({
+            name: "SLACK_BOT_TOKEN",
+            label: "Bot User OAuth Token",
+            guide: {
+                instructions: "Create the app from this link (pick a workspace, then Create), then open Install App → Install to " +
+                    "Workspace → Allow, and copy the Bot User OAuth Token.",
+                url: slackManifestLink(manifest),
+            },
+            async check(value) {
+                if (value.startsWith("xoxe.")) {
+                    throw new SetupRefused("That is a rotating token, which FastAgent does not support.", {
+                        fix: "Token rotation cannot be turned off once it is on: create the app again from the link, which leaves it off.",
+                    });
+                }
+                if (!value.startsWith("xoxb-")) {
+                    throw new SetupRefused("That is not a bot token.", {
+                        fix: "The Bot User OAuth Token is under Install App, and starts with xoxb-.",
+                    });
+                }
+                try {
+                    const api = createSlackApi({ botToken: value, baseUrl: SLACK_API });
+                    const identity = await api.authTest();
+                    return `bot in workspace ${identity.teamId ?? "(unknown)"}`;
+                }
+                catch (error) {
+                    if (error instanceof SlackApiError && error.status === 200) {
+                        throw new SetupRefused("Slack does not accept this token.", {
+                            fix: "Copy the Bot User OAuth Token again from Install App.",
+                            why: error.message,
+                        });
+                    }
+                    throw error;
+                }
+            },
+        }),
+        ...(way === "connection"
+            ? [
+                pasteOne({
+                    name: "SLACK_APP_TOKEN",
+                    label: "App-Level Token",
+                    guide: {
+                        instructions: "Open Basic Information → App-Level Tokens → Generate Token and Scopes, add the scope " +
+                            "connections:write, and copy the token.",
+                    },
+                    async check(value) {
+                        if (!value.startsWith("xapp-")) {
+                            throw new SetupRefused("That is not an app-level token.", {
+                                fix: "It starts with xapp-, and is made under Basic Information → App-Level Tokens (not the bot token).",
+                            });
+                        }
+                        try {
+                            await openSlackConnection(SLACK_API, value);
+                            return undefined;
+                        }
+                        catch (error) {
+                            if (error instanceof TerminalSocketError) {
+                                throw new SetupRefused("Slack does not accept this token.", {
+                                    fix: "Make sure it has the connections:write scope, and copy it again.",
+                                    why: error.message,
+                                });
+                            }
+                            throw error;
+                        }
+                    },
+                }),
+            ]
+            : [
+                pasteOne({
+                    name: "SLACK_SIGNING_SECRET",
+                    label: "Signing Secret",
+                    guide: {
+                        instructions: "Open Basic Information → App Credentials, show the Signing Secret, and copy it.",
+                    },
+                    // Slack gives no way to ask whether it is right: the first signed request will say.
+                    async check(value) {
+                        if (!/^[a-f0-9]{32}$/i.test(value)) {
+                            throw new SetupRefused("That is not a signing secret.", {
+                                fix: "It is 32 letters and digits, under Basic Information → App Credentials (not the Client Secret).",
+                            });
+                        }
+                        return undefined;
+                    },
+                }),
+            ]),
+    ];
+    return {
+        values,
+        finish: () => [
+            "invite the app to each channel it should read (/invite @<its name> in the channel)",
+            ...(way === "webhook"
+                ? [
+                    `Event Subscriptions → set the Request URL to ${publicUrl ?? "https://<where it is served>"}/slack once it ` +
+                        "is served (Slack verifies it as you save; click Retry if it was set before)",
+                ]
+                : []),
+        ],
+    };
+};

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

@@ -102,6 +102,8 @@ export interface SlackApi {
         userId?: string;
         botId?: string;
     }>;
+    /** The id of the Slack app a bot belongs to (`bots.info`, which a bot token holding `users:read` may call). */
+    botAppId(botId: string): Promise<string | undefined>;
     postMessage(target: SlackTarget, text: string): Promise<string>;
     postMarkdown(target: SlackTarget, markdown: string): Promise<string>;
     updateMessage(channelId: string, ts: string, text: string): Promise<void>;

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

@@ -261,6 +261,10 @@ function slackClient({ botToken, baseUrl = "https://slack.com/api" }, onSent) {
             const data = await call("auth.test", {});
             return { teamId: data.team_id, userId: data.user_id, botId: data.bot_id };
         },
+        async botAppId(botId) {
+            const data = await call("bots.info", { bot: botId }, "GET");
+            return data.bot?.app_id;
+        },
         async postMessage(target, text) {
             const data = await call("chat.postMessage", {
                 channel: target.channelId,

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

@@ -1,8 +1,14 @@
-import type { ChannelModule } from "../../channel.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../channel.ts";
+import { type OpenSlackSocket } from "./socket.ts";
 import { type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRoute, defaultSlackRoute, slackEnvelope } from "./parse.ts";
 import { type SlackFailure, type SlackRendering } from "./preview.ts";
 export { defaultSlackRoute, slackEnvelope };
-export type { SlackEventEnvelope, SlackFailure, SlackFile, SlackMessageEvent, SlackRendering, SlackRoute };
+export type { SlackEventEnvelope, SlackFailure, SlackFile, SlackMessageEvent, SlackRendering, SlackRoute, SlackSocketChannelOptions, };
+/** What `slackSocketChannel` is given: the policy of `slackChannel`, and the app-level token in place of its secret. */
+interface SlackSocketChannelOptions extends SlackPolicyOptions {
+    /** The app-level token (`xapp-…`, scope `connections:write`): opens the socket. */
+    appToken: string;
+}
 export interface SlackChannelOptions {
     /** Bot User OAuth Token (`xoxb-…`) used for replies and files. */
     botToken: string;
@@ -35,4 +41,17 @@ export interface SlackChannelOptions {
 }
 /** Verify Slack's v0 HMAC over the exact raw body and reject timestamps outside the replay window. */
 export declare function verifySlackSignature(signingSecret: string, timestamp: string, signature: string, rawBody: string, nowMs?: number): boolean;
+/** What a Slack channel is told besides how its events arrive: the policy both ways share. */
+type SlackPolicyOptions = Omit<SlackChannelOptions, "signingSecret">;
+/** Build a Slack channel that receives by the Events API's HTTP Request URL: signed requests in, durable turns out. */
 export declare function slackChannel(options: SlackChannelOptions): ChannelModule;
+/**
+ * Build a Slack channel that receives by Socket Mode: the process opens a WebSocket to Slack with the app-level token
+ * and takes its events there, so no public URL and no signing secret are involved. An app in Socket Mode receives over
+ * the socket alone: it has no Request URL to point anywhere else.
+ */
+export declare function slackSocketChannel(options: SlackSocketChannelOptions, 
+/** Internal seam for deterministic tests: the socket the connection opens. */
+deps?: {
+    openSocket?: OpenSlackSocket;
+}): LongConnectionChannelModule;