@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/channels/slack/preview.js

@@ -1,7 +1,8 @@
+import { answerText } from "../../answer-text.js";
 import * as Effect from "effect/Effect";
 import * as Clock from "effect/Clock";
 import * as Stream from "effect/Stream";
-import { previewPump, renderReply, serialWriter } from "../kit/delivery.js";
+import { previewPump, renderReply, serialWriter, turnEnd, unfinishedTurn } from "../kit/delivery.js";
 import { PortFailure, portJoin } from "../../effect-port.js";
 import { log } from "../../log.js";
 import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createTurnView, defaultErrorMessage, humanizeToolName, revealedAnswer, summarizeToolArgs, toolLines, } from "../kit/preview-kit.js";
@@ -45,7 +46,7 @@ function boldText(value) {
 /**
  * One trace line: the tool, what it was called on, and — on the failure line — that it failed.
  *
- * Tool OUTPUT never leaves the process, failed or not: the channel would have to guess the engine's
+ * Tool OUTPUT never leaves the process, failed or not: the channel would have to guess the harness's
  * result shape to read it, and the agent already explains a failure it recovered from in its answer.
  * The failure line therefore repeats the operation instead of adding one: it states WHICH call failed
  * (six `Bash` calls in a turn are otherwise indistinguishable) without exposing anything the start
@@ -105,6 +106,8 @@ export async function settleSlackPreview(api, target, previewTs, text) {
     }
     await api.postMessage(target, text);
 }
+/** Whether an event carries answer text: a text delta, or the settled message it adds up to. */
+const isAnswerText = (event) => (event.type === "delta" && event.channel === "text") || (event.type === "entry" && event.entry.kind === "assistant");
 function streamClassicSlackReply(events, api, target, formatError, initialPreviewTs, disclaimer, label, onAnswered) {
     return Effect.gen(function* () {
         const clock = yield* Clock.Clock;
@@ -176,7 +179,7 @@ function streamClassicSlackReply(events, api, target, formatError, initialPrevie
             onEvent: (event) => {
                 const changed = applyTurnEvent(turn, event, now());
                 // A hidden answer must not open a placeholder followed by a rate-limited edit on a fast turn.
-                if (changed && (event.type !== "text" || revealedAnswer(turn, CLASSIC_UPDATE_INTERVAL_MS, now()) !== ""))
+                if (changed && (!isAnswerText(event) || revealedAnswer(turn, CLASSIC_UPDATE_INTERVAL_MS, now()) !== ""))
                     touch();
             },
         });
@@ -206,7 +209,9 @@ function streamNativeSlackReply(events, api, target, formatError, initialPreview
         yield* Effect.addFinalizer(() => Effect.gen(function* () {
             if (target.channelId.startsWith("D"))
                 setStatus("");
-            yield* statuses.finish.pipe(Effect.orDie);
+            // A finalizer does not fail: its defect would make the turn's typed failure one too. Unreachable while
+            // `setStatus` catches its own failures, which no test can make it stop doing.
+            yield* statuses.finish.pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.warn(`${label} could not finish the Slack Agent status: ${String(error.cause)}`))));
         }));
         let stopAttempted = false;
         const stop = (ts, markdown) => {
@@ -350,6 +355,32 @@ function streamNativeSlackReply(events, api, target, formatError, initialPreview
                 ]);
             }
         });
+        let messageId;
+        let streamError;
+        const textOf = answerText();
+        /** An ending that is a failure: its notice woven into the stream, then the turn fails with it. */
+        const failWith = (failure) => Effect.gen(function* () {
+            finalized = true;
+            yield* Effect.gen(function* () {
+                const notice = yield* Effect.try({
+                    try: () => formatError(failure) ?? "",
+                    catch: (cause) => new PortFailure(cause),
+                });
+                if (notice) {
+                    pendingText += `${fullAnswer.trim() ? "\n\n" : ""}${notice}`;
+                    fullAnswer += `${fullAnswer.trim() ? "\n\n" : ""}${notice}`;
+                }
+                yield* settleNative(fullAnswer.trim() || GENERIC_FAILURE);
+            }).pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.error(`${label} failed to deliver the agent-failure stream: ${String(error.cause)}`))));
+            return yield* Effect.fail(new PortFailure(new Error(`agent failed: ${failure.details} (retryable=${failure.retryable})`)));
+        });
+        const appendAnswer = (text) => {
+            if (!text)
+                return;
+            pendingText += text;
+            fullAnswer += text;
+            scheduleText();
+        };
         yield* Stream.runForEachWhile(events, (event) => Effect.gen(function* () {
             if (event.type !== "retrying" && retryStatusShown) {
                 // Progress after a retry notice: restore the normal working status so the stale line doesn't
@@ -357,34 +388,43 @@ function streamNativeSlackReply(events, api, target, formatError, initialPreview
                 retryStatusShown = false;
                 setStatus(WORKING_STATUS);
             }
-            if (event.type === "text") {
-                pendingText += event.delta;
-                fullAnswer += event.delta;
-                scheduleText();
-            }
-            else if (event.type === "thinking") {
-                // Slack's native loading status represents private reasoning without exposing it.
-            }
-            else if (event.type === "retrying") {
-                // A summarization retry backoff pauses the stream (~14s worst case). Channels have no per-run
-                // status surface in native mode; DMs get the explicit Agent status line, restored on progress.
-                if (target.channelId.startsWith("D")) {
-                    retryStatusShown = true;
-                    setStatus("hit a temporary problem — retrying…");
+            if (event.type === "message")
+                messageId = event.message.id;
+            if (event.type === "stream_error")
+                streamError = event.error.message;
+            const end = turnEnd(event, messageId);
+            if (end === undefined) {
+                // Slack's native loading status represents private reasoning (`thinking` deltas) without exposing it.
+                if (event.type === "delta" && event.channel === "text")
+                    appendAnswer(textOf(event));
+                else if (event.type === "retrying") {
+                    // A summarization retry backoff pauses the stream (~14s worst case). Channels have no per-message
+                    // status surface in native mode; DMs get the explicit Agent status line, restored on progress.
+                    if (target.channelId.startsWith("D")) {
+                        retryStatusShown = true;
+                        setStatus("hit a temporary problem — retrying…");
+                    }
                 }
+                else if (event.type === "tool_started") {
+                    const trace = nativeToolTrace(event.name, event.args);
+                    toolTraces.set(event.toolCallId, trace);
+                    sendToolTrace(nativeToolLine(trace));
+                }
+                else if (event.type === "entry") {
+                    if (event.entry.kind === "assistant")
+                        appendAnswer(textOf(event));
+                    if (event.entry.kind === "tool_result") {
+                        const data = event.entry.data;
+                        const trace = (data.toolCallId && toolTraces.get(data.toolCallId)) || { label: "Tool" };
+                        if (data.toolCallId)
+                            toolTraces.delete(data.toolCallId);
+                        if (data.isError === true)
+                            sendToolTrace(nativeToolLine(trace, " failed"));
+                    }
+                }
+                return true;
             }
-            else if (event.type === "tool_started") {
-                const trace = nativeToolTrace(event.name, event.args);
-                toolTraces.set(event.id, trace);
-                sendToolTrace(nativeToolLine(trace));
-            }
-            else if (event.type === "tool_ended") {
-                const trace = toolTraces.get(event.id) ?? { label: "Tool" };
-                toolTraces.delete(event.id);
-                if (event.isError)
-                    sendToolTrace(nativeToolLine(trace, " failed"));
-            }
-            else if (event.type === "completed") {
+            if ("answered" in end) {
                 finalized = true;
                 const finalAnswer = withDisclaimer(fullAnswer, disclaimer);
                 const footer = finalAnswer.slice(fullAnswer.trim().length);
@@ -396,29 +436,15 @@ function streamNativeSlackReply(events, api, target, formatError, initialPreview
                 yield* settleNative(finalAnswer);
                 return false;
             }
-            else if (event.type === "failed") {
-                finalized = true;
-                yield* Effect.gen(function* () {
-                    const notice = yield* Effect.try({
-                        try: () => formatError({
-                            details: event.details,
-                            retryable: event.retryable,
-                            ...(event.code !== undefined ? { code: event.code } : {}),
-                        }) ?? "",
-                        catch: (cause) => new PortFailure(cause),
-                    });
-                    if (notice) {
-                        pendingText += `${fullAnswer.trim() ? "\n\n" : ""}${notice}`;
-                        fullAnswer += `${fullAnswer.trim() ? "\n\n" : ""}${notice}`;
-                    }
-                    yield* settleNative(fullAnswer.trim() || GENERIC_FAILURE);
-                }).pipe(Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.error(`${label} failed to deliver the agent-failure stream: ${String(error.cause)}`))));
-                return yield* Effect.fail(new PortFailure(new Error(`agent failed: ${event.details} (retryable=${event.retryable})`)));
-            }
-            return true;
+            return yield* failWith(end.failure);
         }).pipe(Effect.uninterruptible));
-        if (!finalized)
-            yield* Effect.fail(new PortFailure(new Error("stream ended without a terminal event")));
+        if (finalized)
+            return;
+        const unfinished = unfinishedTurn(streamError);
+        if (unfinished === undefined) {
+            return yield* Effect.fail(new PortFailure(new Error("stream ended without a terminal event")));
+        }
+        yield* failWith(unfinished).pipe(Effect.uninterruptible);
     });
 }
 export function slackReply(events, api, target, formatError, options = {}) {

package/dist/channels/slack/register-webhook.d.ts

@@ -1,6 +1,7 @@
 import { type RegistrationOutcome } from "../registration.ts";
 export interface RegisterSlackWebhookOptions {
     stateRoot: string;
+    environment?: "dev" | "production";
     log?: (message: string) => void;
     attempts?: number;
     retryMs?: number;

package/dist/channels/slack/register-webhook.js

@@ -6,6 +6,8 @@ import { currentSlackConfigToken, readSlackOnboardingState } from "./onboarding-
 export async function registerSlackWebhook(baseUrl, options) {
     const note = options.log ?? ((message) => console.error(message));
     const publicBaseUrl = baseUrl.replace(/\/$/, "");
+    const add = `fastagent add slack${options.environment === "production" ? " --env production" : ""}`;
+    const repair = `${add} --replace-config`;
     let state;
     try {
         state = readSlackOnboardingState(options.stateRoot);
@@ -15,9 +17,9 @@ export async function registerSlackWebhook(baseUrl, options) {
         return "failed";
     }
     if (!state?.appId || !state.installedAt) {
-        note(`[fastagent] slack: no completed local onboarding state on this machine — the config credential lives only where \`fastagent add slack\` ran. ` +
+        note(`[fastagent] slack: no completed local onboarding state on this machine — the config credential lives only where \`${add}\` ran. ` +
             `Set Event Subscriptions → Request URL = ${publicBaseUrl}/slack manually in the Slack console, or re-run this command from the onboarding machine ` +
-            `(repair its expired/revoked tokens with \`fastagent add slack --replace-config\`)`);
+            `(repair its expired/revoked tokens with \`${repair}\`)`);
         return "manual";
     }
     const consoleFallback = `set ${publicBaseUrl}/slack as the Event Subscriptions Request URL in the Slack console`;
@@ -31,14 +33,13 @@ export async function registerSlackWebhook(baseUrl, options) {
     }
     catch (error) {
         note(`[fastagent] slack: could not refresh the App Configuration token: ${String(error)} — ` +
-            `re-run \`fastagent add slack --replace-config\` to repair it, or ${consoleFallback}`);
+            `re-run \`${repair}\` to repair it, or ${consoleFallback}`);
         return "failed";
     }
     // Slack verifies the new request_url with a challenge DURING apps.manifest.update, from Slack's own network.
     try {
         await retryWhile(() => updateSlackAppManifest(current.token, current.state.appId, buildSlackManifest({
             name: current.state.appName,
-            groupBehavior: current.state.groupBehavior,
             requestUrl: `${publicBaseUrl}/slack`,
             // A manifest update replaces the whole manifest and redirect_urls may not be empty, so a placeholder is
             // declared.
@@ -60,7 +61,7 @@ export async function registerSlackWebhook(baseUrl, options) {
             ? `[fastagent] slack: Slack could not verify ${publicBaseUrl}/slack after retries (last error: ${String(error)}) — ` +
                 `once the app is up, ${consoleFallback}`
             : `[fastagent] slack: automatic Request URL registration failed: ${String(error)} — ` +
-                `re-run \`fastagent add slack --replace-config\` to repair the configuration tokens, or ${consoleFallback}`);
+                `re-run \`${repair}\` to repair the configuration tokens, or ${consoleFallback}`);
         return "failed";
     }
 }

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

@@ -1,33 +1,32 @@
+import { needs } from "@fastagent-sh/fastagent";
 import { slackChannel } from "@fastagent-sh/fastagent/slack";
-import { defineChannel } from "@fastagent-sh/fastagent";
 
 // 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, channels:history, groups:history, and mpim:history. The explicit
-//      mention-only mode may omit the three group-history scopes.
+//      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. Mention-only may omit the last three.
+//      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.
-export default defineChannel({
-  // The env vars this channel needs. fastagent carries them to a deployed box and refuses to serve
-  // while one is unset — a bare process.env read gets neither guarantee.
-  secrets: ["SLACK_BOT_TOKEN", "SLACK_SIGNING_SECRET"],
-  channel: (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)
-      // No session modes: an answer attaches to its question with a thread (Slack has no quote primitive),
-      // and that thread is the session — 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}`,
-    }),
-});
+//
+// `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}`,
+  }),
+);

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

@@ -1,48 +1,55 @@
-import { defineTool, z } from "@fastagent-sh/fastagent";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { needs } from "@fastagent-sh/fastagent";
 import { slackTransport } from "@fastagent-sh/fastagent/slack";
 
 // Send a message or upload a local file to Slack. In a CHAT turn the channel delivers the reply
-// itself — do NOT call this to answer a normal chat turn (that posts the message twice). This tool is
-// for file uploads, and for turns NO channel is carrying: a scheduled turn (routines/<name>.ts) or a
-// self-scheduled wake-up, whose plain reply is not delivered anywhere. The channelId/threadTs come
-// from the [slack: …] context line in a chat turn; a scheduled/woken turn has no such line, so its
-// prompt must name the target channel id. tools/ is auto-discovered.
+// itself: do NOT call this to answer a normal chat turn (that posts the message twice). This tool is
+// for file uploads, and for messages NO channel is carrying: a schedule's (src/schedules/) or a
+// self-scheduled wake-up's, whose plain reply is not delivered anywhere. The channelId/threadTs come
+// from the [slack: …] context line in a chat turn; a scheduled or woken message has no such line, so
+// its prompt must name the target channel id.
 //
-// Delivery rides the channel's own transport (slackTransport): its token, API base, Markdown splitting
-// and rate-limit handling. With no channel mounted (`fastagent routine run` / `invoke`) it is built from
-// SLACK_BOT_TOKEN in .env.
-
-export default defineTool({
-  description:
-    "Upload one local file to Slack (`path`), or send a message (`text`) for a turn NO channel is " +
-    "carrying — a scheduled or self-scheduled (wake) turn. In a normal chat turn the channel already " +
-    "delivers your reply, so do NOT call this to answer (it would post the message twice). Pass exactly " +
-    "one of `text`/`path`. channelId/threadTs come from the [slack: …] context line in a chat turn; a " +
-    "scheduled/woken turn 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.",
-  input: z.object({
-    channelId: z.string().describe("target Slack channel ID, or a user ID (U…) to message that user's DM"),
-    text: z.string().optional().describe("standard Markdown message text"),
-    path: z.string().optional().describe("absolute path of a local file to upload"),
-    title: z.string().optional().describe("file title (file mode only)"),
-    initialComment: z.string().optional().describe("message posted with the file (file mode only)"),
-    threadTs: z.string().optional().describe("thread parent timestamp, if replying in a thread"),
-  }),
-  async execute({ channelId, text, path, title, initialComment, threadTs }, ctx) {
-    if ((text === undefined) === (path === undefined)) throw new Error("pass exactly one of `text` or `path`");
-    const slack = slackTransport(ctx.cwd);
-    const target = { channelId, threadTs };
-    if (text !== undefined) {
-      if (title !== undefined || initialComment !== undefined) {
-        throw new Error("`title`/`initialComment` are file-mode only");
+// Delivery rides the channel's own transport (slackTransport): its token, API base, Markdown
+// splitting and rate-limit handling. With no channel mounted, it is built from SLACK_BOT_TOKEN.
+export default needs(["SLACK_BOT_TOKEN"], ({ SLACK_BOT_TOKEN }) =>
+  defineTool({
+    name: "slack_send",
+    description:
+      "Upload one local file to Slack (`path`), or send a message (`text`) for a message NO channel is " +
+      "carrying: a scheduled or self-scheduled one. In a normal chat turn the channel already " +
+      "delivers your reply, so do NOT call this to answer (it would post the message twice). Pass exactly " +
+      "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" })),
+    }),
+    execute: async ({ channelId, text, path, title, initialComment, threadTs }) => {
+      if ((text === undefined) === (path === undefined)) throw new Error("pass exactly one of `text` or `path`");
+      const slack = slackTransport(SLACK_BOT_TOKEN);
+      const target = { channelId, threadTs };
+      let said: string;
+      if (text !== undefined) {
+        if (title !== undefined || initialComment !== undefined) {
+          throw new Error("`title`/`initialComment` are file-mode only");
+        }
+        const sent = await slack.sendMarkdown(target, text);
+        // A user-id target reports the DM channel Slack resolved it to: the id a file upload needs.
+        said =
+          sent.channelId === channelId
+            ? `sent message to Slack channel ${channelId} (ts ${sent.ts})`
+            : `sent message to Slack user ${channelId} in DM channel ${sent.channelId} (ts ${sent.ts})`;
+      } else {
+        const file = await slack.uploadFile(target, path as string, { title, initialComment });
+        said = `uploaded ${file.name} to Slack channel ${channelId} (file ${file.id})`;
       }
-      const sent = await slack.sendMarkdown(target, text);
-      // A user-id target reports the DM channel Slack resolved it to — the id a file upload needs.
-      return sent.channelId === channelId
-        ? `sent message to Slack channel ${channelId} (ts ${sent.ts})`
-        : `sent message to Slack user ${channelId} in DM channel ${sent.channelId} (ts ${sent.ts})`;
-    }
-    const file = await slack.uploadFile(target, path as string, { title, initialComment });
-    return `uploaded ${file.name} to Slack channel ${channelId} (file ${file.id})`;
-  },
-});
+      return { output: [{ type: "text", text: said }] };
+    },
+  }),
+);

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

@@ -0,0 +1,29 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { sessionIdOf } from "@fastagent-sh/fastagent";
+import { slackThreads } from "@fastagent-sh/fastagent/slack";
+
+// Reads the threads of the Slack channel this message was asked in, and no other channel's: the
+// channel names where the message runs, so the tool takes no channel id. It works in a channel turn
+// served by `fastagent dev`/`start`.
+export default defineTool({
+  name: "slack_threads",
+  description:
+    "Read the threads of the Slack channel you are answering in. Without `threadId`, list its recent threads, most " +
+    "recently active first, each with its id; with a `threadId` from that list, read that thread. Use it when a " +
+    "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({
+        description: "a thread id from the list (its first message's ts, like 1712345678.123456); omit it to list",
+      }),
+    ),
+  }),
+  execute: async ({ threadId }, api, context) => {
+    const threads = slackThreads(await sessionIdOf(api, context));
+    const text = threadId === undefined ? await threads.list() : await threads.read(threadId);
+    return { output: [{ type: "text", text }] };
+  },
+});

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

@@ -2,6 +2,25 @@ export interface SlackSetupServer {
     port: number;
     requestPath: string;
     redirectPath: string;
+    /**
+     * The page a person pastes an App Configuration token pair on, for a setup a coding agent runs: the pair never
+     * passes through the agent's conversation or any file. Its path is the server's secret, like the OAuth redirect's.
+     */
+    tokensPath: string;
+    /** The pair, once one `check` accepts is pasted; what `check` throws is shown on the page, which stays up. */
+    waitForTokens<T>(check: (pair: {
+        access: string;
+        refresh: string;
+    }) => T): Promise<T>;
+    /** Where the browser that pasted the pair goes next: Slack's install page. */
+    next(url: string): void;
+    /**
+     * Why the setup stopped, for a browser waiting on the page after the pair: resolves once it has been shown, at once
+     * when no browser waits there, or after one refresh window, so a setup can stop without leaving it on a dead page.
+     */
+    failed(message: string): Promise<void>;
+    /** What the setup did, for a browser waiting on that page when the setup ends there (a saved pair replaced), as `failed`. */
+    done(message: string): Promise<void>;
     waitForOAuth(timeoutMs?: number): Promise<{
         code?: string;
         state?: string;

package/dist/channels/slack/setup-server.js

@@ -1,10 +1,45 @@
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
+const escapeHtml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+const page = (body, head = "") => `<!doctype html><meta charset=utf-8><meta name=viewport content="width=device-width">${head}` +
+    `<title>FastAgent Slack setup</title><body style="font:16px system-ui;max-width:40em;margin:3em auto;padding:0 1em">${body}`;
+function tokensForm(error) {
+    return page(`<h1>Slack App Configuration token</h1>` +
+        `<ol><li>Open <a href="https://api.slack.com/apps" target=_blank rel=noopener>api.slack.com/apps</a>, then ` +
+        `<b>Your App Configuration Tokens</b> → <b>Generate Token</b> for the workspace the agent joins.</li>` +
+        `<li>Paste both tokens here.</li></ol>` +
+        `<p>FastAgent keeps them on this machine only (owner-readable), uses them to create the app and update its ` +
+        `Request URL, and never deploys them.</p>` +
+        (error ? `<p style="color:#b00"><b>${escapeHtml(error)}</b></p>` : "") +
+        `<form method=post><p><label>Access token<br><input name=access type=password required ` +
+        `placeholder="xoxe.xoxp-…" style="width:100%"></label></p><p><label>Refresh token<br><input name=refresh ` +
+        `type=password required placeholder="xoxe-…" style="width:100%"></label></p>` +
+        `<p><button>Create the Slack app</button></p></form>`);
+}
 /** Temporary onboarding-only responder. */
 export async function startSlackSetupServer() {
     const nonce = randomBytes(24).toString("hex");
     const requestPath = `/slack/setup/${nonce}`;
     const redirectPath = `/slack/oauth/${nonce}`;
+    const tokensPath = `/slack/tokens/${nonce}`;
+    const nextPath = `/slack/next/${nonce}`;
+    let takeTokens;
+    let pasted = false;
+    let after;
+    let lastShown;
+    /** The last page a browser waiting after the pair sees, and when it has seen it (bounded by one refresh window). */
+    const lastPage = (said, failed) => {
+        if (!pasted || after !== undefined)
+            return Promise.resolve();
+        after = { said, failed };
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, 5_000);
+            lastShown = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        });
+    };
     let settleOAuth;
     const oauth = new Promise((resolve) => {
         settleOAuth = resolve;
@@ -24,21 +59,61 @@ export async function startSlackSetupServer() {
             settleOAuth = undefined;
             response.statusCode = 200;
             response.setHeader("content-type", "text/html; charset=utf-8");
-            response.end("<!doctype html><title>FastAgent Slack setup</title><p>Slack authorization received. Return to your terminal.</p>");
+            response.end(page("<p>Slack authorization received: FastAgent is finishing the install. You can close this page.</p>"));
             return;
         }
-        if (request.method === "POST" && url.pathname === requestPath) {
-            let body = "";
-            let tooLarge = false;
-            request.on("data", (chunk) => {
-                if (tooLarge)
+        if (url.pathname === tokensPath && (request.method === "GET" || request.method === "POST")) {
+            response.setHeader("content-type", "text/html; charset=utf-8");
+            if (takeTokens === undefined) {
+                // Taken already, or not asked for: the page is one-time.
+                response.statusCode = 404;
+                response.end(page("<p>This page is no longer in use.</p>"));
+                return;
+            }
+            if (request.method === "GET") {
+                response.end(tokensForm());
+                return;
+            }
+            readBody(request, (body) => {
+                if (body === undefined) {
+                    response.statusCode = 413;
+                    response.end(page("<p>Too large.</p>"));
                     return;
-                body += String(chunk);
-                if (Buffer.byteLength(body) > 64 * 1024)
-                    tooLarge = true;
+                }
+                const form = new URLSearchParams(body);
+                try {
+                    takeTokens?.({ access: (form.get("access") ?? "").trim(), refresh: (form.get("refresh") ?? "").trim() });
+                }
+                catch (error) {
+                    response.end(tokensForm(error.message));
+                    return;
+                }
+                response.statusCode = 303;
+                response.setHeader("location", nextPath);
+                response.end();
             });
-            request.on("end", () => {
-                if (tooLarge) {
+            return;
+        }
+        if (request.method === "GET" && url.pathname === nextPath) {
+            response.setHeader("content-type", "text/html; charset=utf-8");
+            if (after === undefined) {
+                response.end(page("<p>Creating the Slack app…</p>", '<meta http-equiv="refresh" content="2">'));
+            }
+            else if ("url" in after) {
+                response.statusCode = 303;
+                response.setHeader("location", after.url);
+                response.end();
+            }
+            else {
+                const style = after.failed ? ' style="color:#b00"' : "";
+                response.end(page(`<p${style}><b>${escapeHtml(after.said)}</b></p><p>Return to your agent.</p>`));
+                lastShown?.();
+            }
+            return;
+        }
+        if (request.method === "POST" && url.pathname === requestPath) {
+            readBody(request, (body) => {
+                if (body === undefined) {
                     response.statusCode = 413;
                     response.end("payload too large\n");
                     return;
@@ -78,6 +153,20 @@ export async function startSlackSetupServer() {
         port: address.port,
         requestPath,
         redirectPath,
+        tokensPath,
+        waitForTokens: (check) => new Promise((resolve) => {
+            takeTokens = (pair) => {
+                const taken = check(pair);
+                takeTokens = undefined;
+                pasted = true;
+                resolve(taken);
+            };
+        }),
+        next(url) {
+            after = { url };
+        },
+        failed: (message) => lastPage(message, true),
+        done: (message) => lastPage(message, false),
         async waitForOAuth(timeoutMs = 10 * 60_000) {
             let timer;
             const timeout = new Promise((_, reject) => {
@@ -97,3 +186,16 @@ export async function startSlackSetupServer() {
         }),
     };
 }
+/** A request's body, or `undefined` past 64 KB: setup traffic is small, and anything larger is not ours. */
+function readBody(request, then) {
+    let body = "";
+    let tooLarge = false;
+    request.on("data", (chunk) => {
+        if (tooLarge)
+            return;
+        body += String(chunk);
+        if (Buffer.byteLength(body) > 64 * 1024)
+            tooLarge = true;
+    });
+    request.on("end", () => then(tooLarge ? undefined : body));
+}