experimental-ash 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # experimental-ash
 
+## 0.10.1
+
+### Patch Changes
+
+- 05ab89c: fix(slack): eliminate duplicate replies on follow-up mentions in a thread
+
+  `slackChannel` registered its `chat.onNewMention` listener inside the route handler, but the chat SDK's `onNewMention` _pushes_ handlers to an internal list (it does not replace). On warm serverless workers the cached `chat` instance accumulated one listener per inbound webhook, so the N-th `app_mention` dispatched N independent agent turns. Symptom: the first mention in a thread replied once, the next replied twice, the next three times, etc. — reset only by a cold start.
+
+  Registration is now done once per `chat` instance inside `getChat()`. The route handler threads its per-request `send` / `waitUntil` to the listener through a per-`slackChannel` `AsyncLocalStorage` — `requestContext.run({ send, waitUntil }, () => chat.webhooks.slack(req, ...))`. A naive shared module slot would race under concurrent webhook deliveries (the chat SDK yields the event loop on `await req.text()` inside `webhooks.slack`, so a second request can overwrite the slot before the first listener fires, causing request A's mention to dispatch with request B's `send`). ALS binds the store to the async call tree, so each concurrent route invocation gets its own isolated context.
+
+  The mention dispatch also now runs under `waitUntil(send(...).catch(log))` instead of `await send(...)`, mirroring the interaction path. This lets the webhook return `200 OK` within Slack's ~3s ACK window even on cold starts, avoiding the secondary duplication mode where Slack retries the same `app_mention` payload after a slow ACK.
+
+## 0.10.0
+
+### Minor Changes
+
+- 5bc39de: feat(slack): pluggable `stateAdapter` for production persistence
+
+  `slackChannel` and `slack()` now accept a `stateAdapter` option implementing the chat SDK `StateAdapter` contract. Used for callback URLs on posted cards, `thread.state` / `thread.setState`, `thread.subscribe`, message queues, and locks. Defaults to an in-memory adapter (development only — loses state on restart, not shared across processes). Pass a Redis/Postgres-backed adapter for production.
+
+  The supplied instance is shared across the inbound webhook path (`Chat` constructor) and every event-handler context rebuild, so state stays coherent within a single agent run. The default in-memory adapter is now constructed once at channel-construction time and shared the same way, replacing the previous behavior where the inbound path and each rebuild call each got their own isolated memory adapter.
+
+  A new exported type alias `SlackStateAdapter` aliases the chat SDK's `StateAdapter` interface.
+
 ## 0.9.0
 
 ### Minor Changes

package/dist/docs/public/channels/slack.md

@@ -169,6 +169,29 @@ export default slackChannel({
 (`turn.started`, `message.completed`, `session.failed`, etc.). They run inside the workflow context,
 not on the inbound webhook side.
 
+## State Persistence
+
+The Slack channel uses a state backend for callback URLs on posted cards, `thread.state` /
+`thread.setState`, `thread.subscribe`, message queues, and locks. By default this is an in-memory
+adapter scoped to the current process, which loses state on restart and is not coherent across
+processes. For deployed agents, pass a production adapter (Redis, Postgres, etc.) implementing the
+chat SDK `StateAdapter` contract. Construct it once at module top-level so all requests share one
+connection pool:
+
+```ts
+import { createRedisState } from "@chat-adapter/state-redis";
+import { slack } from "experimental-ash/channels/slack";
+
+const stateAdapter = createRedisState({ url: process.env.REDIS_URL! });
+
+export default slack({
+  stateAdapter,
+});
+```
+
+The same instance is reused across the inbound webhook path and every event-handler context rebuild,
+so state stays coherent within a single agent run.
+
 ## Typing Indicators
 
 Out of the box, `slack()` posts typing statuses so the user sees feedback before the agent starts

package/dist/src/internal/application/package.js

@@ -6,7 +6,7 @@ import { ASH_PACKAGE_NAME } from "#package-name.js";
 let cachedPackageInfo;
 // The package build stamps the published version into `dist` so bundled
 // deployments can still report package metadata without resolving package.json.
-const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.9.0";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.10.1";
 const BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER = "__ASH_PACKAGE_VERSION_PLACEHOLDER__";
 const WORKFLOW_MODULE_ALIASES = {
     "workflow/api": "src/compiled/@workflow/core/runtime.js",

package/dist/src/public/channels/slack/index.d.ts

@@ -1,4 +1,4 @@
 export { slack, type SlackOptions } from "#public/channels/slack/slack.js";
-export { slackChannel, type SlackApiHandle, type SlackApiResponse, type SlackChannel, type SlackChannelConfig, type SlackChannelEvents, type SlackChannelCredentials, type SlackChannelState, type SlackContext, type SlackInteractionAction, type SlackReceiveArgs, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
+export { slackChannel, type SlackApiHandle, type SlackApiResponse, type SlackChannel, type SlackChannelConfig, type SlackChannelEvents, type SlackChannelCredentials, type SlackChannelState, type SlackContext, type SlackInteractionAction, type SlackReceiveArgs, type SlackStateAdapter, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
 export { Actions, Button, Card, CardText, Divider, Fields, Image, LinkButton, Modal, RadioSelect, Section, Select, SelectOption, Table, TextInput, } from "#compiled/chat/index.js";
 export type { AdapterPostableMessage, Attachment, Author, CardElement, FileUpload, Message, PostableMessage, SentMessage, Thread, } from "#compiled/chat/index.js";

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

@@ -1,9 +1,10 @@
 import type { SessionAuthContext } from "#channel/types.js";
 import type { Channel } from "#public/definitions/defineChannel.js";
-import { type SlackChannelCredentials, type SlackChannelState } from "#public/channels/slack/slackChannel.js";
+import { type SlackChannelCredentials, type SlackChannelState, type SlackStateAdapter } from "#public/channels/slack/slackChannel.js";
 export interface SlackOptions {
     readonly auth?: (message: import("#compiled/chat/index.js").Message) => SessionAuthContext | null;
     readonly credentials?: SlackChannelCredentials;
     readonly botName?: string;
+    readonly stateAdapter?: SlackStateAdapter;
 }
 export declare function slack(options?: SlackOptions): Channel<SlackChannelState>;

package/dist/src/public/channels/slack/slack.js

@@ -15,6 +15,7 @@ export function slack(options = {}) {
     return slackChannel({
         credentials: options.credentials,
         botName: options.botName,
+        stateAdapter: options.stateAdapter,
         run(_ctx, message) {
             return { auth: resolveAuth(message) };
         },

package/dist/src/public/channels/slack/slackChannel.d.ts

@@ -1,5 +1,5 @@
 import { type SlackBotToken } from "#compiled/@chat-adapter/slack/index.js";
-import { type Message, type SerializedThread, type Thread } from "#compiled/chat/index.js";
+import { type Message, type SerializedThread, type StateAdapter, type Thread } from "#compiled/chat/index.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
 import { type UploadPolicy } from "#public/channels/upload-policy.js";
 import { type Channel } from "#public/definitions/defineChannel.js";
@@ -36,6 +36,14 @@ export interface SlackChannelState {
  * with Vercel OIDC instead of Slack's signing secret.
  */
 export type SlackWebhookVerifier = (request: Request, body: string) => unknown | Promise<unknown>;
+/**
+ * State backend used by the chat SDK for callback URL persistence on
+ * posted cards, `thread.state`/`setState`, `thread.subscribe`, message
+ * queues, and locks. Any value implementing the chat SDK
+ * `StateAdapter` contract works — `@chat-adapter/state-memory` for
+ * local development, a Redis/Postgres-backed adapter for production.
+ */
+export type SlackStateAdapter = StateAdapter;
 export interface SlackChannelCredentials {
     readonly botToken?: SlackBotToken;
     /**
@@ -93,6 +101,17 @@ export interface SlackChannelEvents {
 export interface SlackChannelConfig {
     readonly credentials?: SlackChannelCredentials;
     readonly botName?: string;
+    /**
+     * State backend for chat SDK persistence — callback URLs on posted
+     * cards, `thread.state` / `thread.setState`, `thread.subscribe`,
+     * message queues, locks. Defaults to an in-memory adapter scoped to
+     * the current process, which loses state on restart and is not
+     * shared across processes. Pass a production adapter (Redis,
+     * Postgres, etc.) for deployed agents. The same instance is reused
+     * across the inbound webhook path and every event-handler context
+     * rebuild, keeping state coherent within a single agent run.
+     */
+    readonly stateAdapter?: SlackStateAdapter;
     /**
      * Override the default webhook route path (`/ash/v1/slack`).
      */

package/dist/src/public/channels/slack/slackChannel.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createSlackAdapter } from "#compiled/@chat-adapter/slack/index.js";
 import { createMemoryState } from "#compiled/@chat-adapter/state-memory/index.js";
 import { ThreadImpl, } from "#compiled/chat/index.js";
@@ -5,7 +6,7 @@ import { createLogger } from "#internal/logging.js";
 import { buildSlackTurnMessage, collectSlackFileParts, createSlackFetchFile, } from "#public/channels/slack/attachments.js";
 import { deriveHitlResponse, isHitlAction, renderInputRequestBlocks, } from "#public/channels/slack/hitl.js";
 import { mergeUploadPolicy } from "#public/channels/upload-policy.js";
-import { defineChannel, POST } from "#public/definitions/defineChannel.js";
+import { defineChannel, POST, } from "#public/definitions/defineChannel.js";
 const log = createLogger("slack.channel");
 function decodeThreadId(id) {
     const parts = id.replace(/^slack:/u, "").split(":");
@@ -94,7 +95,7 @@ function resolveSlackAdapterCredentials(credentials) {
     const signingSecret = credentials?.signingSecret ?? (webhookVerifier ? undefined : process.env.SLACK_SIGNING_SECRET);
     return { botToken, signingSecret, webhookVerifier };
 }
-function rebuildSlackContext(state, credentials) {
+function rebuildSlackContext(state, credentials, stateAdapter) {
     const { botToken, signingSecret, webhookVerifier } = resolveSlackAdapterCredentials(credentials);
     const adapter = createSlackAdapter({
         botToken,
@@ -109,20 +110,8 @@ function rebuildSlackContext(state, credentials) {
             id: "slack::",
             isDM: false,
         });
-    // Pin both private adapter slots so the thread is fully self-
-    // contained — no `Chat.getSingleton()` lookup needed when handlers
-    // call `thread.post()`, `thread.startTyping()`, `thread.setState()`,
-    // `thread.subscribe()`, etc. The `_adapter` line matches the runtime
-    // behavior chat itself relies on for `ThreadImpl.fromJSON(json,
-    // adapter)`. `ThreadImpl.fromJSON` does NOT pin a state adapter, so
-    // without `_stateAdapterInstance` set, state-touching paths (cards,
-    // callback URLs, `state`/`setState`, `subscribe()`/`isSubscribed()`)
-    // would fall through to the singleton and throw — we use an in-
-    // memory state adapter scoped to this rebuild so the asymmetry with
-    // the fallback branch goes away and both branches converge to a
-    // fully-pinned thread.
     Reflect.set(thread, "_adapter", adapter);
-    Reflect.set(thread, "_stateAdapterInstance", createMemoryState());
+    Reflect.set(thread, "_stateAdapterInstance", stateAdapter);
     return {
         thread,
         slack: buildSlackApiHandle(thread, botToken, state.teamId ?? undefined),
@@ -152,6 +141,15 @@ export function slackChannel(config = {}) {
     const slackFetchFile = createSlackFetchFile({
         botToken: config.credentials?.botToken,
     });
+    const stateAdapter = config.stateAdapter ?? createMemoryState();
+    // Threads per-request `send`/`waitUntil` to the once-registered
+    // `onNewMention` listener. A shared mutable slot would race under
+    // concurrent webhook deliveries — `webhooks.slack` yields on
+    // `await req.text()`, so request B could overwrite A's slot before A's
+    // listener fires. ALS scopes the store to each route's async call tree.
+    // Allowlisted in `scripts/guard-agents-rules-baseline.json` (rule 19);
+    // this is channel-local request state, not Ash runtime state.
+    const requestContext = new AsyncLocalStorage();
     let chatPromise = null;
     async function getChat() {
         if (chatPromise)
@@ -161,9 +159,8 @@ export function slackChannel(config = {}) {
             if (!botToken) {
                 throw new Error("slackChannel requires a bot token. Pass credentials.botToken or set SLACK_BOT_TOKEN.");
             }
-            const [slackModule, stateModule, chatModule] = await Promise.all([
+            const [slackModule, chatModule] = await Promise.all([
                 import("#compiled/@chat-adapter/slack/index.js"),
-                import("#compiled/@chat-adapter/state-memory/index.js"),
                 import("#compiled/chat/index.js"),
             ]);
             const slackAdapter = slackModule.createSlackAdapter({
@@ -174,10 +171,69 @@ export function slackChannel(config = {}) {
             });
             const chat = new chatModule.Chat({
                 adapters: { slack: slackAdapter },
-                state: stateModule.createMemoryState(),
+                state: stateAdapter,
                 userName: config.botName ?? "ash-agent",
             });
             await chat.initialize();
+            // Register exactly once per chat instance — the chat SDK's
+            // `onNewMention` pushes handlers (does not replace), so registering
+            // on every webhook accumulates listeners on warm workers and the
+            // N-th `app_mention` dispatches N times.
+            chat.onNewMention(async (thread, message) => {
+                const rawEvent = message.raw;
+                // Slack sends both `app_mention` and `message.channels` for the same
+                // utterance. The Chat SDK dedup relies on in-memory state that doesn't
+                // survive serverless invocations, so both events reach this handler.
+                // Only process `app_mention` to prevent duplicate runs.
+                if (rawEvent?.type !== "app_mention")
+                    return;
+                const ctx = requestContext.getStore();
+                if (!ctx) {
+                    // Defensive: the chat SDK invokes handlers inside the
+                    // `requestContext.run(...)` tree below, so this should never
+                    // miss. Log and drop in case a future SDK ever defers
+                    // invocation (e.g. via a queue or `setImmediate`).
+                    log.warn("slack mention received but no request context is active");
+                    return;
+                }
+                const teamId = rawEvent.team_id ?? rawEvent.team;
+                const slackCtx = {
+                    thread,
+                    slack: buildSlackApiHandle(thread, config.credentials?.botToken, teamId),
+                };
+                const runOpts = config.run ? await config.run(slackCtx, message) : { auth: null };
+                if (runOpts === null)
+                    return;
+                if (config.onMention) {
+                    try {
+                        await config.onMention(slackCtx, message);
+                    }
+                    catch (error) {
+                        log.error("onMention handler failed", { error });
+                    }
+                }
+                const decoded = decodeThreadId(thread.id ?? "");
+                const continuationToken = `slack:${decoded.channelId}:${decoded.threadTs}`;
+                const fileParts = collectSlackFileParts(message, uploadPolicy);
+                const turnMessage = buildSlackTurnMessage(message.text, fileParts);
+                // Dispatch via `waitUntil` so the webhook ACKs within Slack's ~3s
+                // window even on cold starts. Awaiting `send` here would let a
+                // slow dispatch push the response past 3s and trigger Slack
+                // retries of the same `app_mention` (which the type filter
+                // cannot dedupe). Errors are logged; Slack already got its 200.
+                ctx.waitUntil(ctx
+                    .send(turnMessage, {
+                    auth: runOpts.auth,
+                    continuationToken,
+                    state: {
+                        serializedThread: thread.toJSON(),
+                        teamId: teamId ?? null,
+                    },
+                })
+                    .catch((error) => {
+                    log.error("mention delivery failed", { error });
+                }));
+            });
             return { chat };
         })();
         chatPromise = promise;
@@ -191,7 +247,7 @@ export function slackChannel(config = {}) {
         state: { serializedThread: null, teamId: null },
         fetchFile: slackFetchFile,
         context(state) {
-            return rebuildSlackContext(state, config.credentials);
+            return rebuildSlackContext(state, config.credentials, stateAdapter);
         },
         routes: [
             POST(config.route ?? "/ash/v1/slack", async (req, { send, waitUntil }) => {
@@ -255,44 +311,9 @@ export function slackChannel(config = {}) {
                     }
                     return new Response("ok", { status: 200 });
                 }
-                chat.onNewMention(async (thread, message) => {
-                    const rawEvent = message.raw;
-                    // Slack sends both `app_mention` and `message.channels` for the same
-                    // utterance. The Chat SDK dedup relies on in-memory state that doesn't
-                    // survive serverless invocations, so both events reach this handler.
-                    // Only process `app_mention` to prevent duplicate runs.
-                    if (rawEvent?.type !== "app_mention")
-                        return;
-                    const teamId = rawEvent.team_id ?? rawEvent.team;
-                    const slackCtx = {
-                        thread,
-                        slack: buildSlackApiHandle(thread, config.credentials?.botToken, teamId),
-                    };
-                    const runOpts = config.run ? await config.run(slackCtx, message) : { auth: null };
-                    if (runOpts === null)
-                        return;
-                    if (config.onMention) {
-                        try {
-                            await config.onMention(slackCtx, message);
-                        }
-                        catch (error) {
-                            log.error("onMention handler failed", { error });
-                        }
-                    }
-                    const decoded = decodeThreadId(thread.id ?? "");
-                    const continuationToken = `slack:${decoded.channelId}:${decoded.threadTs}`;
-                    const fileParts = collectSlackFileParts(message, uploadPolicy);
-                    const turnMessage = buildSlackTurnMessage(message.text, fileParts);
-                    await send(turnMessage, {
-                        auth: runOpts.auth,
-                        continuationToken,
-                        state: {
-                            serializedThread: thread.toJSON(),
-                            teamId: teamId ?? null,
-                        },
-                    });
-                });
-                return await chat.webhooks.slack(req, { waitUntil });
+                // Scope `send` / `waitUntil` to this request's async call tree so
+                // the `onNewMention` listener picks them up via `getStore()`.
+                return await requestContext.run({ send, waitUntil }, () => chat.webhooks.slack(req, { waitUntil }));
             }),
         ],
         async receive(input, { send }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"