@fastagent-sh/fastagent 0.19.0 → 0.21.0

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

@@ -2,7 +2,7 @@
 import type { Agent, AgentEvent } from "../../agent.ts";
 import { type BusyRetry } from "../kit/invoke-turn-kit.ts";
 import type { SlackBufferedFileRef } from "./context-buffer.ts";
-import type { SlackApi } from "./slack-api.ts";
+import { type SlackApi } from "./slack-api.ts";
 export interface SlackTurnTransport {
     api: SlackApi;
     channelId: string;

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

@@ -1,5 +1,6 @@
 import { log } from "../../log.js";
 import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../kit/invoke-turn-kit.js";
+import { SlackApiError } from "./slack-api.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);
@@ -58,7 +59,10 @@ export async function* invokeSlackTurn(agent, session, text, transport, attachme
         resolved = await resolveInputs(transport, attachments);
     }
     catch (error) {
-        yield { type: "failed", details: `could not load Slack attachment: ${String(error)}`, retryable: true };
+        // transient (network, exhausted 429 retries, Slack 5xx) is worth re-sending; an access or shape
+        // error reads the same every time, and "try again in a moment" is the wrong thing to tell the user
+        const retryable = error instanceof SlackApiError && (error.status === 0 || error.status === 429 || error.status >= 500);
+        yield { type: "failed", details: `could not load Slack attachment: ${String(error)}`, retryable };
         return;
     }
     const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };

package/dist/channels/slack/manifest.js

@@ -63,7 +63,11 @@ export function buildSlackManifest(input) {
                 : {}),
             org_deploy_enabled: false,
             socket_mode_enabled: false,
-            token_rotation_enabled: true,
+            // 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). Rotation would ship the refresh token
+            // and the client secret to every host beside the access token — the same blast radius as one
+            // long-lived bot token, plus a 12-hour refresh lineage to keep single and durable.
+            token_rotation_enabled: false,
         },
     };
 }

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

@@ -10,13 +10,10 @@ export interface SlackOnboardIO {
         state?: string;
         error?: string;
     }>;
-    /** Stage runtime-only credentials into the gitignored .env. */
+    /** Stage the runtime secrets into the gitignored .env — the bot token and the signing secret, nothing
+     *  else: the client credentials are setup-only (the OAuth code exchange) and stay in onboarding state. */
     writeRuntimeSecrets(values: {
         botToken?: string;
-        botRefreshToken?: string;
-        botTokenExpiresAt?: number;
-        clientId?: string;
-        clientSecret?: string;
         signingSecret?: string;
     }): Promise<void>;
 }
@@ -31,6 +28,9 @@ export declare function onboardSlackApp(input: SlackOnboardInput, io: SlackOnboa
     createApp?: typeof createSlackApp;
     updateManifest?: typeof updateSlackAppManifest;
     exchangeCode?: typeof exchangeSlackOAuthCode;
+    /** Attempts absorbing the setup tunnel's warm-up before Slack can verify its URL. */
+    attempts?: number;
+    retryMs?: number;
 }): Promise<SlackOnboardingState>;
 export declare function newSlackOnboardingState(input: {
     appName: string;

package/dist/channels/slack/onboard.js

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
-import { createSlackApp, exchangeSlackOAuthCode, SlackConfigApiError, updateSlackAppManifest } from "./config-api.js";
+import { retryWhile } from "../registration.js";
+import { createSlackApp, exchangeSlackOAuthCode, isSlackRequestUrlUnverified, isSlackRotationLocked, SLACK_ROTATING_APP_UPGRADE, 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. */
@@ -7,6 +8,16 @@ export async function onboardSlackApp(input, io, deps = {}) {
     let state = input.state;
     const current = await currentSlackConfigToken(input.stateRoot, state);
     state = current.state;
+    /** Slack challenges request_url from ITS network during a manifest call and validates the whole
+     *  manifest before acting, so an unverifiable URL created nothing and the call is safe to repeat. */
+    const whileUnverified = (call, onRetry) => retryWhile(call, isSlackRequestUrlUnverified, {
+        attempts: deps.attempts,
+        retryMs: deps.retryMs,
+        onRetry: ({ attempt, attempts }) => {
+            onRetry?.();
+            io.note(`Slack cannot reach the temporary setup URL yet (attempt ${attempt}/${attempts}); retrying…`);
+        },
+    });
     const manifest = buildSlackManifest({
         name: state.appName,
         groupBehavior: state.groupBehavior,
@@ -19,21 +30,26 @@ export async function onboardSlackApp(input, io, deps = {}) {
                 "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);
+        const setMarker = (value) => {
+            state = { ...state, createAttemptedAt: value };
+            writeSlackOnboardingState(input.stateRoot, state);
+        };
         let created;
         try {
-            created = await (deps.createApp ?? createSlackApp)(current.token, manifest);
+            created = await whileUnverified(() => {
+                // 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. The marker spans
+                // exactly one in-flight call: an unverifiable URL created nothing, so it comes off again before
+                // the wait — a Ctrl-C during that wait must not wedge the next run on an app that never existed.
+                setMarker(new Date().toISOString());
+                return (deps.createApp ?? createSlackApp)(current.token, manifest);
+            }, () => setMarker(undefined));
         }
         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);
-            }
+            if (!ambiguous)
+                setMarker(undefined);
             throw error;
         }
         state = {
@@ -45,7 +61,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
             signingSecret: created.signingSecret,
         };
         // Irreversible boundary first: a cancellation or .env write failure can resume without creating a duplicate.
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
         io.note(`Created Slack app ${created.appId}; credentials captured locally.`);
     }
     else {
@@ -53,13 +69,22 @@ export async function onboardSlackApp(input, io, deps = {}) {
             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);
+        const appId = state.appId;
+        io.note(`Resuming Slack app ${appId}; refreshing its temporary setup URLs…`);
+        try {
+            await whileUnverified(() => (deps.updateManifest ?? updateSlackAppManifest)(current.token, appId, manifest));
+        }
+        catch (error) {
+            // A resume of an app created with rotation on: the manifest is refused for good, so say what fixes it.
+            if (isSlackRotationLocked(error))
+                throw new Error(SLACK_ROTATING_APP_UPGRADE, { cause: error });
+            throw error;
+        }
     }
     if (state.signingSecret) {
         await io.writeRuntimeSecrets({ signingSecret: state.signingSecret });
         state = { ...state, signingSecret: undefined };
-        await writeSlackOnboardingState(input.stateRoot, state);
+        writeSlackOnboardingState(input.stateRoot, state);
     }
     if (!state.appId || !state.clientId || !state.clientSecret) {
         throw new Error("Slack onboarding state lost app OAuth credentials before installation");
@@ -70,7 +95,9 @@ export async function onboardSlackApp(input, io, deps = {}) {
     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}`);
+    // The redirect lands on the tunnel hostname, which THIS machine may not resolve yet (#421) — a broken
+    // page beside a terminal that looks hung, unless the reload is named before it happens.
+    io.note(`Click Allow in Slack to install the app: ${authorize}\nIf the page it returns to does not load, reload it.`);
     io.openUrl(authorize.toString());
     const callback = await io.waitForOAuth();
     if (callback.error)
@@ -90,13 +117,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
     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,
-    });
+    await io.writeRuntimeSecrets({ botToken: oauth.botToken });
     state = {
         ...state,
         clientSecret: undefined,
@@ -104,7 +125,7 @@ export async function onboardSlackApp(input, io, deps = {}) {
         teamName: oauth.teamName,
         installedAt: new Date().toISOString(),
     };
-    await writeSlackOnboardingState(input.stateRoot, state);
+    writeSlackOnboardingState(input.stateRoot, state);
     return state;
 }
 export function newSlackOnboardingState(input) {

package/dist/channels/slack/onboarding-state.d.ts

@@ -18,9 +18,13 @@ export interface SlackOnboardingState {
     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 readSlackOnboardingState(stateRoot: string): SlackOnboardingState | undefined;
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh
+ *  token. Synchronous, through the shared writer, like every other piece of state this repo keeps
+ *  (kit/state.ts): the file is ~1 KB and its writers are `fastagent add slack` and one config-token
+ *  rotation at tunnel startup, so the async spelling bought nothing and cost a fifth set of temp-name
+ *  and permission rules to keep true. */
+export declare function writeSlackOnboardingState(stateRoot: string, state: SlackOnboardingState): void;
 export declare function currentSlackConfigToken(stateRoot: string, state: SlackOnboardingState, options?: {
     now?: number;
     apiBaseUrl?: string;

package/dist/channels/slack/onboarding-state.js

@@ -1,5 +1,6 @@
-import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../../atomic-write.js";
 import { rotateSlackConfigToken } from "./config-api.js";
 function slackOnboardingStatePath(stateRoot) {
     return join(stateRoot, "channels", "slack", "onboarding.json");
@@ -15,11 +16,11 @@ function validState(value) {
         typeof state.configRefreshToken === "string" &&
         typeof state.configTokenExpiresAt === "number");
 }
-export async function readSlackOnboardingState(stateRoot) {
+export function readSlackOnboardingState(stateRoot) {
     const file = slackOnboardingStatePath(stateRoot);
     let raw;
     try {
-        raw = await readFile(file, "utf8");
+        raw = readFileSync(file, "utf8");
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -36,21 +37,13 @@ export async function readSlackOnboardingState(stateRoot) {
         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;
-    }
+/** Atomic replacement with owner-only permissions: this file carries a workspace-wide config refresh
+ *  token. Synchronous, through the shared writer, like every other piece of state this repo keeps
+ *  (kit/state.ts): the file is ~1 KB and its writers are `fastagent add slack` and one config-token
+ *  rotation at tunnel startup, so the async spelling bought nothing and cost a fifth set of temp-name
+ *  and permission rules to keep true. */
+export function writeSlackOnboardingState(stateRoot, state) {
+    writeFileAtomic(slackOnboardingStatePath(stateRoot), `${JSON.stringify(state, null, 2)}\n`, 0o600);
 }
 export async function currentSlackConfigToken(stateRoot, state, options = {}) {
     const now = options.now ?? Date.now();
@@ -64,6 +57,6 @@ export async function currentSlackConfigToken(stateRoot, state, options = {}) {
         configTokenExpiresAt: rotated.expiresAt,
         teamId: state.teamId ?? rotated.teamId,
     };
-    await writeSlackOnboardingState(stateRoot, next);
+    writeSlackOnboardingState(stateRoot, next);
     return { token: next.configToken, state: next };
 }

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

@@ -1,8 +1,9 @@
-import type { RegistrationOutcome } from "../registration.ts";
+import { type RegistrationOutcome } from "../registration.ts";
 export interface RegisterSlackWebhookOptions {
     stateRoot: string;
     log?: (message: string) => void;
-    healthTimeoutMs?: number;
+    attempts?: number;
+    retryMs?: number;
     apiBaseUrl?: string;
     fetch?: typeof fetch;
 }

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

@@ -1,5 +1,5 @@
-import { waitForHealth } from "../wait-health.js";
-import { updateSlackAppManifest } from "./config-api.js";
+import { retryWhile } from "../registration.js";
+import { SLACK_ROTATING_APP_UPGRADE, isSlackRequestUrlUnverified, isSlackRotationLocked, updateSlackAppManifest, } from "./config-api.js";
 import { buildSlackManifest } from "./manifest.js";
 import { currentSlackConfigToken, readSlackOnboardingState } from "./onboarding-state.js";
 /** Update one onboarded internal Slack app without sending its configuration credential to the host. */
@@ -8,7 +8,7 @@ export async function registerSlackWebhook(baseUrl, options) {
     const publicBaseUrl = baseUrl.replace(/\/$/, "");
     let state;
     try {
-        state = await readSlackOnboardingState(options.stateRoot);
+        state = readSlackOnboardingState(options.stateRoot);
     }
     catch (error) {
         note(`[fastagent] slack: cannot read local onboarding state: ${String(error)}`);
@@ -20,30 +20,50 @@ export async function registerSlackWebhook(baseUrl, options) {
             `(repair its expired/revoked tokens with \`fastagent add slack --replace-config\`)`);
         return "manual";
     }
-    const healthy = await waitForHealth(`${publicBaseUrl}/health`, options.healthTimeoutMs ?? 45_000, 500);
-    if (!healthy) {
-        note(`[fastagent] slack: ${publicBaseUrl}/health did not become reachable; Request URL was not changed`);
-        return "failed";
-    }
+    const consoleFallback = `set ${publicBaseUrl}/slack as the Event Subscriptions Request URL in the Slack console`;
+    let current;
     try {
-        const current = await currentSlackConfigToken(options.stateRoot, state, {
+        // Rotation is not retried with the manifest below: each rotate invalidates the previous pair, so a
+        // repeat would spend tokens on a failure that is about the URL, not about the credential.
+        current = await currentSlackConfigToken(options.stateRoot, state, {
             apiBaseUrl: options.apiBaseUrl,
             fetch: options.fetch,
         });
-        await updateSlackAppManifest(current.token, current.state.appId, buildSlackManifest({
+    }
+    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}`);
+        return "failed";
+    }
+    // Slack verifies the new request_url with a challenge DURING apps.manifest.update, from Slack's own
+    // network — that verdict IS the readiness signal, so it is retried while a fresh tunnel/container
+    // warms up. No local `/health` poll precedes it: this machine's reach is the wrong question (#421).
+    try {
+        await retryWhile(() => updateSlackAppManifest(current.token, current.state.appId, buildSlackManifest({
             name: current.state.appName,
             groupBehavior: current.state.groupBehavior,
             requestUrl: `${publicBaseUrl}/slack`,
-            // Token-rotation manifests require at least one OAuth redirect URL even after installation.
-            // Actual reinstall flows replace this placeholder with their one-shot local setup callback.
+            // A manifest update replaces the whole manifest and redirect_urls may not be empty, so a
+            // placeholder is declared; a reinstall replaces it with its one-shot local setup callback.
             redirectUrl: `${publicBaseUrl}/slack/oauth/callback`,
-        }), { apiBaseUrl: options.apiBaseUrl, fetch: options.fetch });
+        }), { apiBaseUrl: options.apiBaseUrl, fetch: options.fetch }), isSlackRequestUrlUnverified, {
+            attempts: options.attempts,
+            retryMs: options.retryMs,
+            onRetry: ({ attempt, attempts }) => note(`[fastagent] slack: Slack cannot verify ${publicBaseUrl}/slack yet (attempt ${attempt}/${attempts}); retrying…`),
+        });
         note(`[fastagent] slack: Event Subscriptions Request URL registered → ${publicBaseUrl}/slack`);
         return "registered";
     }
     catch (error) {
-        note(`[fastagent] slack: automatic Request URL registration failed: ${String(error)} — ` +
-            `re-run \`fastagent add slack --replace-config\` to repair the configuration tokens, or set ${publicBaseUrl}/slack in the Slack console`);
+        if (isSlackRotationLocked(error)) {
+            note(`[fastagent] slack: ${SLACK_ROTATING_APP_UPGRADE}, or ${consoleFallback}`);
+            return "failed";
+        }
+        note(isSlackRequestUrlUnverified(error)
+            ? `[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}`);
         return "failed";
     }
 }

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

@@ -8,18 +8,11 @@ import { slackChannel } from "@fastagent-sh/fastagent/slack";
 //   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.
 //      Set Request URL to https://<host>/slack.
-//   4. Enable token rotation and install/reinstall the app after changing scopes. Rotating credentials
-//      are written by `fastagent add slack`; manual long-lived tokens may omit the four rotation fields.
+//   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 slackChannel({
-  botToken: process.env.SLACK_BOT_TOKEN ?? "", // Bot User OAuth Token (xoxb-… or rotating xoxe.xoxb-…)
+  botToken: process.env.SLACK_BOT_TOKEN ?? "", // OAuth & Permissions → Bot User OAuth Token (xoxb-…)
   signingSecret: process.env.SLACK_SIGNING_SECRET ?? "", // Basic Information → App Credentials
-  botRefreshToken: process.env.SLACK_BOT_REFRESH_TOKEN || undefined,
-  clientId: process.env.SLACK_CLIENT_ID || undefined,
-  clientSecret: process.env.SLACK_CLIENT_SECRET || undefined,
-  botTokenExpiresAt: process.env.SLACK_BOT_TOKEN_EXPIRES_AT
-    ? Number(process.env.SLACK_BOT_TOKEN_EXPIRES_AT)
-    : undefined,
-  groupBehavior: "context", // default; use "mentions" only for an explicit least-privilege setup
   // 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",

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

@@ -1,6 +1,5 @@
 import { defineTool, z } from "@fastagent-sh/fastagent";
-import { open, stat } from "node:fs/promises";
-import { basename } from "node:path";
+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
@@ -8,84 +7,10 @@ import { basename } from "node:path";
 // 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.
-
-const API = "https://slack.com/api";
-const MAX_TEXT = 10_000;
-const RETRIES = 3;
-const MAX_RETRY_AFTER_S = 30;
-
-const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-function splitText(text: string): string[] {
-  const points = Array.from(text);
-  const chunks: string[] = [];
-  let offset = 0;
-  while (offset < points.length) {
-    let end = Math.min(points.length, offset + MAX_TEXT);
-    if (end < points.length) {
-      const block = points.slice(offset, end).join("");
-      const newline = block.lastIndexOf("\n");
-      if (newline > 0) end = offset + Array.from(block.slice(0, newline)).length;
-    }
-    chunks.push(points.slice(offset, end).join(""));
-    offset = end;
-    if (points[offset] === "\n") offset++;
-  }
-  return chunks.length ? chunks : [""];
-}
-
-async function callSlack<T extends { ok?: boolean; error?: string }>(
-  token: string,
-  method: string,
-  body: Record<string, unknown>,
-): Promise<T> {
-  for (let attempt = 0; ; attempt++) {
-    let response: Response;
-    let raw: string;
-    try {
-      response = await fetch(`${API}/${method}`, {
-        method: "POST",
-        headers: { authorization: `Bearer ${token}`, "content-type": "application/json; charset=utf-8" },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(120_000),
-      });
-      raw = await response.text();
-    } catch (error) {
-      throw new Error(`slack ${method}: ${String(error)}`, { cause: error });
-    }
-    let data: T;
-    try {
-      data = JSON.parse(raw) as T;
-    } catch {
-      data = {} as T;
-    }
-    if (response.ok && data.ok === true) return data;
-    if ((response.status === 429 || data.error === "ratelimited") && attempt < RETRIES) {
-      const retryAfter = Number(response.headers.get("retry-after") ?? attempt + 1);
-      if (Number.isFinite(retryAfter) && retryAfter <= MAX_RETRY_AFTER_S) {
-        await wait(Math.max(1, retryAfter) * 1000);
-        continue;
-      }
-    }
-    throw new Error(`slack ${method} failed: ${response.status} ${data.error ?? "unexpected response"}`);
-  }
-}
-
-function trustedUploadUrl(value: string): URL {
-  const url = new URL(value);
-  const host = url.hostname.toLowerCase();
-  const slackHost =
-    host === "slack-files.com" ||
-    host.endsWith(".slack-files.com") ||
-    host === "slack.com" ||
-    host.endsWith(".slack.com") ||
-    host === "slack-edge.com" ||
-    host.endsWith(".slack-edge.com");
-  if (url.protocol !== "https:" || !slackHost) {
-    throw new Error(`Slack returned an untrusted upload URL host: ${host}`);
-  }
-  return url;
-}
+//
+// Delivery rides the channel's own transport (slackTransport): its token, API base, Markdown splitting
+// and rate-limit handling. With no channel mounted (`fastagent fire` / `invoke`) it is built from
+// SLACK_BOT_TOKEN in .env.
 
 export default defineTool({
   description:
@@ -93,79 +18,31 @@ export default defineTool({
     "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.",
+    "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"),
+    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 }) {
-    const token = process.env.SLACK_BOT_TOKEN;
-    if (!token) throw new Error("SLACK_BOT_TOKEN is not set");
+  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");
       }
-      const chunks = splitText(text);
-      for (const chunk of chunks) {
-        await callSlack(token, "chat.postMessage", {
-          channel: channelId,
-          markdown_text: chunk,
-          ...(threadTs ? { thread_ts: threadTs } : {}),
-          unfurl_links: false,
-          unfurl_media: false,
-        });
-      }
-      return chunks.length === 1
-        ? `sent message to Slack channel ${channelId}`
-        : `sent ${chunks.length} messages to Slack channel ${channelId}`;
-    }
-
-    const filePath = path as string;
-    const info = await stat(filePath);
-    if (!info.isFile()) throw new Error(`${filePath} is not a regular file`);
-    const filename = basename(filePath);
-    const upload = await callSlack<{ ok?: boolean; error?: string; upload_url?: string; file_id?: string }>(
-      token,
-      "files.getUploadURLExternal",
-      { filename, length: info.size },
-    );
-    if (!upload.upload_url || !upload.file_id) throw new Error("Slack upload URL response carried no upload_url/file_id");
-
-    let byteResponse: Response;
-    const handle = await open(filePath, "r");
-    try {
-      byteResponse = await fetch(trustedUploadUrl(upload.upload_url), {
-        method: "POST",
-        headers: { "content-type": "application/octet-stream" },
-        body: handle.readableWebStream(),
-        signal: AbortSignal.timeout(120_000),
-        // Required by Node fetch for a streaming request body; not part of the browser RequestInit type.
-        duplex: "half",
-      } as RequestInit & { duplex: "half" });
-    } catch (error) {
-      throw new Error(`Slack file byte upload failed: ${String(error)}`, { cause: error });
-    } finally {
-      await handle.close().catch(() => {});
+      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})`;
     }
-    if (!byteResponse.ok) {
-      throw new Error(`Slack file byte upload failed: ${byteResponse.status} ${await byteResponse.text()}`);
-    }
-
-    // At-least-once: if Slack commits this call but the response is lost, a tool retry may post a
-    // duplicate. Retrying automatically here would hide that ambiguity, so only explicit agent/user
-    // retry crosses this final side-effect boundary.
-    await callSlack(token, "files.completeUploadExternal", {
-      files: [{ id: upload.file_id, title: title ?? filename }],
-      channel_id: channelId,
-      ...(initialComment ? { initial_comment: initialComment } : {}),
-      ...(threadTs ? { thread_ts: threadTs } : {}),
-    });
-    return `uploaded ${filename} to Slack channel ${channelId}`;
+    const file = await slack.uploadFile(target, path as string, { title, initialComment });
+    return `uploaded ${file.name} to Slack channel ${channelId} (file ${file.id})`;
   },
 });

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

@@ -0,0 +1,10 @@
+import { type SlackApi } from "./slack-api.ts";
+/** What a proactive sender needs: Markdown delivery and file upload. */
+export type SlackTransport = Pick<SlackApi, "sendMarkdown" | "uploadFile">;
+/** A re-mount replaces the entry: the channel's transport is the authoritative one for its root. */
+export declare function registerSlackApi(stateRoot: string, api: SlackApi): void;
+/**
+ * The transport of the agent whose workspace is `cwd` (a tool's `ctx.cwd`). The state root is derived
+ * exactly as the opener derives it for the channel, so both name the same mount.
+ */
+export declare function slackTransport(cwd: string): SlackTransport;

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

@@ -0,0 +1,34 @@
+/**
+ * The ONE Slack transport per state root a process holds: the mounted channel's, shared with the
+ * scaffolded send tool.
+ *
+ * The tool used to carry a transport of its own over `SLACK_BOT_TOKEN` (#458). Sharing the channel's
+ * gives it the channel's `apiBaseUrl`, Markdown splitting and rate-limit handling, and one place to
+ * read the credential. The channel registers at mount; the tool resolves at EXECUTE, never at load,
+ * and builds a transport from the env only where no channel is mounted (`fastagent fire` / `invoke`)
+ * — that fallback knows no `apiBaseUrl`, since the option lives in the channel's glue, which is not
+ * loaded on those paths.
+ */
+import { resolvePlacement, resolveStateRoot } from "../../paths.js";
+import { createSlackApi } from "./slack-api.js";
+const byStateRoot = new Map();
+/** A re-mount replaces the entry: the channel's transport is the authoritative one for its root. */
+export function registerSlackApi(stateRoot, api) {
+    byStateRoot.set(stateRoot, api);
+}
+/**
+ * The transport of the agent whose workspace is `cwd` (a tool's `ctx.cwd`). The state root is derived
+ * exactly as the opener derives it for the channel, so both name the same mount.
+ */
+export function slackTransport(cwd) {
+    const stateRoot = resolveStateRoot(resolvePlacement(cwd).agentDir);
+    let api = byStateRoot.get(stateRoot);
+    if (!api) {
+        const botToken = process.env.SLACK_BOT_TOKEN;
+        if (!botToken)
+            throw new Error("SLACK_BOT_TOKEN is not set and no Slack channel is mounted");
+        api = createSlackApi({ botToken });
+        byStateRoot.set(stateRoot, api);
+    }
+    return api;
+}