@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/channels/slack/reaction.js

@@ -1,5 +1,4 @@
-/** Lightweight Slack emoji ack on the user's triggering message: 👀 while working, ✅ when done.
- *  Every failure is non-fatal — the turn's threaded reply is the real deliverable. */
+/** Lightweight Slack emoji ack on the user's triggering message: 👀 while working, ✅ when done. */
 import { log } from "../../log.js";
 const EMOJI_RE = /^(?:[a-z0-9_+-]+)(?:::skin-tone-[2-6])?$/;
 /** Normalize a Slack emoji name (strip surrounding colons, lowercase); return null if invalid. */
@@ -27,6 +26,22 @@ export function resolveReactionEmojis(reactionAck) {
         completed: pick(reactionAck.completed, "white_check_mark", "completed"),
     };
 }
+// Every step is best effort: an ack is decoration, and must never fail the turn carrying it.
+const dropProcessing = ({ api, channelId, ts, emojis, label }) => api
+    .removeReaction(channelId, ts, emojis.processing)
+    .catch((error) => log.warn(`${label} could not remove the processing reaction: ${String(error)}`));
+const addCompleted = ({ api, channelId, ts, emojis, label }) => api
+    .addReaction(channelId, ts, emojis.completed)
+    .catch((error) => log.warn(`${label} could not add the completed reaction: ${String(error)}`));
+/**
+ * Finish an ack this process did not start: 👀 on the asker's message was added by the run that produced the answer,
+ * and a re-delivery is the only thing left that can turn it into ✅. Without it the ack says "still working" under a
+ * delivered answer, forever.
+ */
+export async function completeSlackReaction(target) {
+    await dropProcessing(target);
+    await addCompleted(target);
+}
 const NO_REACTION = {
     complete: async () => undefined,
     remove: async () => undefined,
@@ -46,16 +61,12 @@ export async function startSlackReaction(args) {
         if (!active)
             return;
         active = false;
-        await api
-            .removeReaction(channelId, ts, emojis.processing)
-            .catch((error) => log.warn(`${label} could not remove the processing reaction: ${String(error)}`));
+        await dropProcessing(args);
     };
     return {
         complete: async () => {
             await removeProcessing();
-            await api
-                .addReaction(channelId, ts, emojis.completed)
-                .catch((error) => log.warn(`${label} could not add the completed reaction: ${String(error)}`));
+            await addCompleted(args);
         },
         remove: removeProcessing,
     };

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

@@ -23,8 +23,7 @@ export async function registerSlackWebhook(baseUrl, options) {
     const consoleFallback = `set ${publicBaseUrl}/slack as the Event Subscriptions Request URL in the Slack console`;
     let current;
     try {
-        // 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.
+        // Rotation is not retried with the manifest below.
         current = await currentSlackConfigToken(options.stateRoot, state, {
             apiBaseUrl: options.apiBaseUrl,
             fetch: options.fetch,
@@ -35,16 +34,14 @@ export async function registerSlackWebhook(baseUrl, options) {
             `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).
+    // 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; a reinstall replaces it with its one-shot local setup callback.
+            // A manifest update replaces the whole manifest and redirect_urls may not be empty, so a placeholder is
+            // declared.
             redirectUrl: `${publicBaseUrl}/slack/oauth/callback`,
         }), { apiBaseUrl: options.apiBaseUrl, fetch: options.fetch }), isSlackRequestUrlUnverified, {
             attempts: options.attempts,

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

@@ -1,4 +1,5 @@
 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.
@@ -10,17 +11,23 @@ import { slackChannel } from "@fastagent-sh/fastagent/slack";
 //      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 slackChannel({
-  botToken: process.env.SLACK_BOT_TOKEN ?? "", // OAuth & Permissions → Bot User OAuth Token (xoxb-…)
-  signingSecret: process.env.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}`,
+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}`,
+    }),
 });

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

@@ -3,13 +3,13 @@ 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 (schedules/<name>.ts) or a
+// 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.
 //
 // 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
+// and rate-limit handling. With no channel mounted (`fastagent routine run` / `invoke`) it is built from
 // SLACK_BOT_TOKEN in .env.
 
 export default defineTool({

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

@@ -9,9 +9,5 @@ export interface SlackSetupServer {
     }>;
     close(): Promise<void>;
 }
-/**
- * Temporary onboarding-only responder. Its unguessable paths live for one command: one path echoes only
- * Slack's URL-verification challenge, while the other captures one OAuth redirect. It never accepts
- * event callbacks or runs Agent work.
- */
+/** Temporary onboarding-only responder. */
 export declare function startSlackSetupServer(): Promise<SlackSetupServer>;

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

@@ -1,10 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
-/**
- * Temporary onboarding-only responder. Its unguessable paths live for one command: one path echoes only
- * Slack's URL-verification challenge, while the other captures one OAuth redirect. It never accepts
- * event callbacks or runs Agent work.
- */
+/** Temporary onboarding-only responder. */
 export async function startSlackSetupServer() {
     const nonce = randomBytes(24).toString("hex");
     const requestPath = `/slack/setup/${nonce}`;

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

@@ -3,8 +3,5 @@ import { type SlackApi } from "./slack-api.ts";
 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.
- */
+/** The transport of the agent whose workspace is `cwd` (a tool's `ctx.cwd`). */
 export declare function slackTransport(cwd: string): SlackTransport;

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

@@ -1,13 +1,5 @@
 /**
- * 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.
+ * The ONE Slack transport per state root a process holds: the mounted channel's, shared with the scaffolded send tool.
  */
 import { resolvePlacement, resolveStateRoot } from "../../paths.js";
 import { createSlackApi } from "./slack-api.js";
@@ -16,10 +8,7 @@ const byStateRoot = new Map();
 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.
- */
+/** The transport of the agent whose workspace is `cwd` (a tool's `ctx.cwd`). */
 export function slackTransport(cwd) {
     const stateRoot = resolveStateRoot(resolvePlacement(cwd).agentDir);
     let api = byStateRoot.get(stateRoot);

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

@@ -1,4 +1,5 @@
 import type { ImageRef } from "../../agent.ts";
+import type { CallOptions } from "../kit/transport.ts";
 import type { SlackFile } from "./model.ts";
 export interface SlackTarget {
     channelId: string;
@@ -46,7 +47,7 @@ export interface SlackApi {
     postMessage(target: SlackTarget, text: string): Promise<string>;
     postMarkdown(target: SlackTarget, markdown: string): Promise<string>;
     updateMessage(channelId: string, ts: string, text: string): Promise<void>;
-    updateMarkdown(channelId: string, ts: string, markdown: string): Promise<void>;
+    updateMarkdown(channelId: string, ts: string, markdown: string, opts?: CallOptions): Promise<void>;
     deleteMessage(channelId: string, ts: string): Promise<void>;
     /** 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. */

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

@@ -37,6 +37,7 @@ const NATIVE_UNAVAILABLE_ERRORS = new Set([
 export function isSlackNativeUnavailable(error) {
     return error instanceof SlackApiError && !!error.slackError && NATIVE_UNAVAILABLE_ERRORS.has(error.slackError);
 }
+/** Sleep on the GLOBAL timer (not `node:timers/promises`) so tests can drive it with fake timers. */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Split a Slack text/Markdown field at a code-point-safe boundary, preferring a newline. */
 export function chunkSlackText(text, maxPoints = SLACK_MAX_MARKDOWN) {
@@ -145,7 +146,8 @@ function assertLongLivedBotToken(botToken) {
 export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" }) {
     assertLongLivedBotToken(botToken);
     const apiBase = baseUrl.replace(/\/$/, "");
-    const call = async (method, body, httpMethod = "POST") => {
+    const call = async (method, body, httpMethod = "POST", opts = {}) => {
+        const retries = opts.retries ?? RETRIES;
         const url = new URL(`${apiBase}/${method}`);
         if (httpMethod === "GET") {
             for (const [name, value] of Object.entries(body)) {
@@ -181,7 +183,7 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
             if (response.ok && data.ok === true)
                 return data;
             const rateLimited = response.status === 429 || data.error === "ratelimited";
-            if (rateLimited && attempt < RETRIES) {
+            if (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);
@@ -261,9 +263,9 @@ export function createSlackApi({ botToken, baseUrl = "https://slack.com/api" })
                 throw error;
             }
         },
-        async updateMarkdown(channelId, ts, markdown) {
+        async updateMarkdown(channelId, ts, markdown, opts) {
             try {
-                await call("chat.update", { channel: channelId, ts, markdown_text: markdown });
+                await call("chat.update", { channel: channelId, ts, markdown_text: markdown }, "POST", opts);
             }
             catch (error) {
                 if (error instanceof SlackApiError && error.slackError === "message_not_modified")

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

@@ -8,23 +8,20 @@ export interface SlackChannelOptions {
     botToken: string;
     /** App signing secret used to verify the raw Events API request body. */
     signingSecret: string;
-    /** `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
-     * rate-limited edited message, which settles into the answer alone. A top-level target necessarily
-     * uses the classic renderer, because Slack streams require a parent user message; a custom route
-     * reaches one either by returning `threadTs: null` or by redirecting to another channel without
-     * naming a thread. */
+    /**
+     * `native` (default) uses Slack Agent streams for threaded replies; `classic` retains the compatibility renderer
+     * based on one rate-limited edited message. A top-level target necessarily uses `classic`, because Slack streams
+     * require a parent user message — a custom route reaches one either by returning `threadTs: null` or by redirecting
+     * to another channel without naming a thread.
+     */
     rendering?: SlackRendering;
-    /** Optional footer for successful Agent replies. Omitted or `false` sends no repetitive disclaimer. */
+    /** Optional footer for successful Agent replies. */
     aiDisclaimer?: string | false;
-    /** First-run direct-message welcome, sent once when a user first opens the DM (`app_home_opened`,
-     * `tab: "messages"`). A string customizes it; `false` disables it. Plain Markdown only — no interactive
-     * buttons until an interactivity endpoint exists. Defaults to a generic greeting. */
+    /**
+     * First-run direct-message welcome, sent once when a user first opens the DM (`app_home_opened`, `tab: "messages"`).
+     */
     welcome?: string | false;
-    /** Lightweight emoji ack on the user's triggering message: 👀 while working, ✅ when done. `false`
-     * disables it; an object overrides either emoji name. Requires the `reactions:write` scope; a missing
-     * scope degrades to no ack. */
+    /** Lightweight emoji ack on the user's triggering message: 👀 while working, ✅ when done. */
     reactionAck?: false | {
         processing?: string;
         completed?: string;