@fastagent-sh/fastagent 0.20.0 → 0.21.1

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,68 +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"}`);
-  }
-}
+//
+// 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:
@@ -77,80 +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 {
-      // where getUploadURLExternal points is Slack's call: these bytes are on their way to Slack either way
-      byteResponse = await fetch(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;
+}

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

@@ -12,6 +12,16 @@ export interface DownloadedSlackFile {
     name: string;
     size: number;
 }
+export interface UploadedSlackFile {
+    id: string;
+    name: string;
+}
+export interface SentSlackMessage {
+    /** The first message's ts (a long Markdown body continues in further messages). */
+    ts: string;
+    /** Where it landed: a user-id target (`U…`) resolves to that user's DM channel (`D…`). */
+    channelId: string;
+}
 export declare class SlackApiError extends Error {
     readonly method: string;
     readonly status: number;
@@ -24,7 +34,7 @@ export declare class SlackApiError extends Error {
  * internal, and timeout failures are ambiguous: Slack may already have created the stream. */
 export declare function isSlackNativeUnavailable(error: unknown): boolean;
 export interface SlackApiOptions {
-    botToken: string | (() => Promise<string>);
+    botToken: string;
     baseUrl?: string;
 }
 export interface SlackApi {
@@ -38,7 +48,9 @@ export interface SlackApi {
     updateMessage(channelId: string, ts: string, text: string): Promise<void>;
     updateMarkdown(channelId: string, ts: string, markdown: string): Promise<void>;
     deleteMessage(channelId: string, ts: string): Promise<void>;
-    sendMarkdown(target: SlackTarget, markdown: string): Promise<string | undefined>;
+    /** Post standard Markdown, split under Slack's limit. `target.channelId` may be a user id: Slack
+     *  then opens (or reuses) the app's DM with that user, and the result names it. */
+    sendMarkdown(target: SlackTarget, markdown: string): Promise<SentSlackMessage>;
     startStream(target: SlackTarget, markdown?: string): Promise<string>;
     appendStream(channelId: string, ts: string, markdown: string): Promise<void>;
     stopStream(channelId: string, ts: string, markdown?: string): Promise<void>;
@@ -49,6 +61,12 @@ export interface SlackApi {
     fileInfo(fileId: string): Promise<SlackFile>;
     fetchImage(file: SlackFile): Promise<ImageRef>;
     fetchFile(file: SlackFile, channelId: string, filesDir: string): Promise<DownloadedSlackFile>;
+    /** Upload one local file into a channel/thread through Slack's external-upload protocol
+     *  (getUploadURLExternal → bytes → completeUploadExternal). */
+    uploadFile(target: SlackTarget, path: string, options?: {
+        title?: string;
+        initialComment?: string;
+    }): Promise<UploadedSlackFile>;
 }
 /** Split a Slack text/Markdown field at a code-point-safe boundary, preferring a newline. */
 export declare function chunkSlackText(text: string, maxPoints?: number): string[];

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

@@ -1,9 +1,11 @@
-/** Slack Web API transport: one JSON pipeline plus authenticated, capped private-file downloads. */
-import { mkdir, writeFile } from "node:fs/promises";
+/** Slack Web API transport: one JSON pipeline, authenticated capped private-file downloads, and the
+ * external-upload protocol. */
+import { mkdir, open, stat, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
 import { attachmentPath } from "../kit/attachment-path.js";
 import { codePointPrefix } from "../kit/text.js";
 const API_TIMEOUT_MS = 30_000;
-const DOWNLOAD_TIMEOUT_MS = 120_000;
+const FILE_TRANSFER_TIMEOUT_MS = 120_000;
 const MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
 const RETRIES = 3;
 const MAX_RETRY_AFTER_S = 30;
@@ -132,9 +134,17 @@ async function readBytesCapped(response) {
     }
     return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
 }
+/** A rotating token (an app created by a release up to 0.20) would work for up to 12 hours and then
+ *  fail as `token_expired`, far from the cause — refuse it where the token enters, on both paths. */
+function assertLongLivedBotToken(botToken) {
+    if (botToken.startsWith("xoxe.")) {
+        throw new Error("got a rotating Slack bot token (xoxe.…); this release uses a long-lived xoxb- token — " +
+            'create a new app (docs/slack.md → "Upgrading from a rotating-token app")');
+    }
+}
 export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" }) {
+    assertLongLivedBotToken(botToken);
     const apiBase = baseUrl.replace(/\/$/, "");
-    const currentToken = typeof botToken === "string" ? async () => botToken : botToken;
     const call = async (method, body, httpMethod = "POST") => {
         const url = new URL(`${apiBase}/${method}`);
         if (httpMethod === "GET") {
@@ -147,11 +157,10 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             let response;
             let raw;
             try {
-                const token = await currentToken();
                 response = await fetch(url, {
                     method: httpMethod,
                     headers: {
-                        authorization: `Bearer ${token}`,
+                        authorization: `Bearer ${botToken}`,
                         ...(httpMethod === "POST" ? { "content-type": "application/json; charset=utf-8" } : {}),
                     },
                     ...(httpMethod === "POST" ? { body: JSON.stringify(body) } : {}),
@@ -195,10 +204,9 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
     const download = async (file) => {
         let response;
         try {
-            const token = await currentToken();
             response = await fetch(fileDownloadUrl(file), {
-                headers: { authorization: `Bearer ${token}` },
-                signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+                headers: { authorization: `Bearer ${botToken}` },
+                signal: AbortSignal.timeout(FILE_TRANSFER_TIMEOUT_MS),
             });
         }
         catch (error) {
@@ -210,6 +218,19 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
         }
         return { bytes: await readBytesCapped(response), contentType: response.headers.get("content-type") ?? undefined };
     };
+    const postMarkdown = async (target, markdown) => {
+        const data = await call("chat.postMessage", {
+            channel: target.channelId,
+            markdown_text: markdown,
+            ...(target.threadTs ? { thread_ts: target.threadTs } : {}),
+            unfurl_links: false,
+            unfurl_media: false,
+        });
+        if (!data.ts)
+            throw new SlackApiError("chat.postMessage", 200, "response carried no ts");
+        // The response's `channel` is what resolves a user-id target to its DM; a channel target echoes itself.
+        return { ts: data.ts, channelId: data.channel ?? target.channelId };
+    };
     const api = {
         async authTest() {
             const data = await call("auth.test", {});
@@ -228,16 +249,7 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             return data.ts;
         },
         async postMarkdown(target, markdown) {
-            const data = await call("chat.postMessage", {
-                channel: target.channelId,
-                markdown_text: markdown,
-                ...(target.threadTs ? { thread_ts: target.threadTs } : {}),
-                unfurl_links: false,
-                unfurl_media: false,
-            });
-            if (!data.ts)
-                throw new SlackApiError("chat.postMessage", 200, "response carried no ts");
-            return data.ts;
+            return (await postMarkdown(target, markdown)).ts;
         },
         async updateMessage(channelId, ts, text) {
             try {
@@ -265,10 +277,11 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
         async sendMarkdown(target, markdown) {
             let first;
             for (const chunk of chunkSlackMarkdown(markdown)) {
-                const ts = await api.postMarkdown(target, chunk);
-                first ??= ts;
+                // Continuations go to the resolved channel: a user-id target must not reopen the DM per chunk.
+                const sent = await postMarkdown(first ? { ...target, channelId: first.channelId } : target, chunk);
+                first ??= sent;
             }
-            return first;
+            return first; // chunkSlackMarkdown never yields zero chunks
         },
         async startStream(target, markdown) {
             if (!target.threadTs)
@@ -362,6 +375,52 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             await writeFile(path, bytes);
             return { path, name, size: bytes.byteLength };
         },
+        async uploadFile(target, path, options = {}) {
+            const info = await stat(path);
+            if (!info.isFile())
+                throw new Error(`${path} is not a regular file`);
+            const name = basename(path);
+            const upload = await call("files.getUploadURLExternal", {
+                filename: name,
+                length: info.size,
+            });
+            if (!upload.upload_url || !upload.file_id) {
+                throw new SlackApiError("files.getUploadURLExternal", 200, "response carried no upload_url/file_id");
+            }
+            // Where upload_url points is Slack's call, as with url_private above; the bytes carry no token.
+            const handle = await open(path, "r");
+            let response;
+            try {
+                response = await fetch(upload.upload_url, {
+                    method: "POST",
+                    headers: { "content-type": "application/octet-stream" },
+                    body: handle.readableWebStream(),
+                    signal: AbortSignal.timeout(FILE_TRANSFER_TIMEOUT_MS),
+                    // Required by Node fetch for a streaming request body; not part of the browser RequestInit type.
+                    duplex: "half",
+                });
+            }
+            catch (error) {
+                throw new SlackApiError("file upload", 0, String(error), undefined, { cause: error });
+            }
+            finally {
+                await handle.close().catch(() => { });
+            }
+            if (!response.ok) {
+                const detail = codePointPrefix(await response.text().catch(() => ""), 300) || "file bytes were rejected";
+                throw new SlackApiError("file upload", response.status, detail);
+            }
+            // At-least-once: if Slack commits this call but the response is lost, a retry may post a
+            // duplicate. Retrying here would hide that ambiguity, so only an explicit agent/user retry
+            // crosses this final side-effect boundary.
+            await call("files.completeUploadExternal", {
+                files: [{ id: upload.file_id, title: options.title ?? name }],
+                channel_id: target.channelId,
+                ...(options.initialComment ? { initial_comment: options.initialComment } : {}),
+                ...(target.threadTs ? { thread_ts: target.threadTs } : {}),
+            });
+            return { id: upload.file_id, name };
+        },
     };
     return api;
 }

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

@@ -8,16 +8,6 @@ export interface SlackChannelOptions {
     botToken: string;
     /** App signing secret used to verify the raw Events API request body. */
     signingSecret: string;
-    /** Rotating OAuth credentials. Omit all four only for a manually managed long-lived bot token. */
-    botRefreshToken?: string;
-    clientId?: string;
-    clientSecret?: string;
-    botTokenExpiresAt?: number;
-    /** `context` (default) subscribes to group message streams, which is what lets the channel HEAR a
-     * thread: bare replies are then admitted by the participation rule (design/participant-model.md §3),
-     * and other discussion is buffered. `mentions` answers only app_mention plus DMs for an explicit
-     * least-privilege setup. */
-    groupBehavior?: "context" | "mentions";
     /** `native` (default) uses Slack Agent streams for threaded replies. Its inline tool traces carry a
      * bounded summary of each call's first argument and cannot be retracted, so they stay in the
      * delivered message beside the answer. `classic` retains the compatibility renderer based on one