experimental-ash 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # experimental-ash
 
+## 0.9.0
+
+### Minor Changes
+
+- 6a3f538: feat(slack): async `run`, new `onMention` pre-dispatch hook, and `onInteraction` docs
+
+  The previous `slackChannel` shape had a single Nitro-side callback — `run(ctx, message)` — that was synchronous and could only return `{ auth } | null`. That made it impossible to do any awaited pre-dispatch work (DB lookups, OAuth refresh, etc.) or to fire awaited side effects on the inbound webhook side before the workflow runtime cold-starts.
+
+  Three additive changes:
+
+  - **`run` is now sync-or-async.** Return type is `SlackRunResult | Promise<SlackRunResult>`. The framework `await`s the result before dispatching. Existing sync `run()` callers continue to work unchanged.
+  - **New `onMention(ctx, message)` hook.** Fires after `run()` accepts and before `send()` enqueues the turn. The framework awaits it; thrown errors are caught and logged so a misbehaving handler cannot block dispatch. Use this for free-form pre-dispatch side effects — starting a typing indicator, logging, etc. The framework still owns dispatch; to skip a turn, return `null` from `run()`.
+  - **`onInteraction` JSDoc.** Documented the existing handler's semantics: HITL `action_id` routing (`ash_input:*` is consumed by the framework before reaching this handler), `waitUntil` execution, error swallowing, and the limitations of the rebuilt `SlackContext`.
+
+  The higher-level `slack()` wrapper moves its `Thinking...` typing indicator into `onMention` so it fires on the inbound webhook side, not after the workflow runtime materializes. The existing `events["turn.started"]` handler still fires the indicator for subsequent in-session turns (HITL follow-ups, multi-turn tool loops).
+
+  Docs updated:
+
+  - `docs/public/channels/slack.md` now has a `Hooks` section explaining `run` vs `onMention` vs `onInteraction` vs `events`, and the `Typing Indicators` section uses `onMention` instead of an un-awaited `startTyping()` inside `run()` (which was a dangling-promise footgun).
+  - The `Customize Delivery` example now correctly nests event handlers under `events: { ... }` (the previous example showed them flat on the config object, which never worked).
+
+  No breaking changes.
+
+### Patch Changes
+
+- 41947c0: fix(slack): forward `webhookVerifier` to the adapter rebuilt for event-handler context
+
+  Follow-up to the previous webhook-verifier fix. `slackChannel` instantiates Slack adapters in two places: `getChat()` for inbound webhook routing and `rebuildSlackContext()` for outbound event-handler dispatch (e.g. delivering `session.failed` at the end of a turn). The previous fix only plumbed `webhookVerifier` and `signingSecret` through the first site, so a Connect-credentialed channel that successfully accepted the inbound webhook would later crash when the runtime tried to materialize the channel context for terminal events:
+
+  ```
+  ValidationError: signingSecret or webhookVerifier is required.
+    at rebuildSlackContext (..., adapter: 'slack', code: 'VALIDATION_ERROR')
+  ```
+
+  Concretely:
+
+  - Extracted a single `resolveSlackAdapterCredentials(credentials)` helper that returns `{ botToken, signingSecret, webhookVerifier }` with the env-var fallback rules (skipping `SLACK_SIGNING_SECRET` when a verifier is supplied).
+  - Both `getChat()` and `rebuildSlackContext()` now resolve credentials through that helper and pass the full triple into `createSlackAdapter`, keeping the two adapter instantiation sites in lockstep so a future credential field cannot drift again.
+  - `rebuildSlackContext`'s signature now takes the full `SlackChannelCredentials | undefined` instead of just `botToken`.
+
+  No public API change.
+
+- 06cd322: chore(vendor): vendor the `chat` package's real `.d.ts` instead of a hand-written stub so `ctx.thread` and friends expose the actual chat surface (`refresh()`, `startTyping()`, `post()`, `postEphemeral()`, …) instead of `any`.
+
+  Previously, `#compiled/chat/index.js` shipped an Ash-owned hand-written declaration that declared `Thread = any`, `Message = any`, `Author = any`, etc. The runtime value of `ctx.thread` was always a real `ThreadImpl` from the bundled chat package, so methods like `thread.refresh()` worked at runtime — they just typechecked as `any` regardless of whether the method existed. Hand-written stubs also silently drifted from upstream on every `chat` version bump.
+
+  What changed:
+
+  - The vendor step now copies `chat`'s real `dist/index.d.ts` verbatim into `.generated/compiled/chat/index.d.ts`, with three transforms applied at copy time:
+    - The sibling `jsx-runtime-<hash>.d.ts` chunk is co-copied so chat's relative import resolves locally. The chunk filename has a content hash, so it's discovered dynamically.
+    - `from '@workflow/serde'` is rewritten to a locally-emitted stub that declares just the `unique symbol`s chat references.
+    - `from 'mdast'` is rewritten to a locally-emitted stub that aliases the names chat references to `unknown` — consumers don't need to install `@types/mdast`.
+    - Any external the upstream `.d.ts` reaches for that has no rewrite rule is a hard error at vendor time so a future chat version can't sneak a new dependency past us.
+  - The same copy-from-package treatment is applied to `@chat-adapter/slack` and `@chat-adapter/state-memory`, whose types extend chat's `Adapter` / `StateAdapter` interfaces and have to satisfy them after the chat copy.
+  - `chat`, `@chat-adapter/slack`, and `@chat-adapter/state-memory` are bumped from `^4.27.0` to `4.28.1`. Every other direct dependency in `packages/ash/package.json` is also locked (no `^` ranges) so the vendored output is reproducible. Peer deps still use ranges so consumers control compatibility.
+  - `slackChannel.rebuildSlackContext` was assigning to `thread._adapter` directly; that field is `private` in the real chat types. Switched to `Reflect.set(thread, "_adapter", adapter)` which preserves runtime behavior without an unsafe cast.
+
+  What this means for agent code:
+
+  ```ts
+  // Before — typechecked as `any`, no autocomplete:
+  await ctx.thread.refresh();
+  await ctx.thread.startTyping("Working on it…");
+  const participants = await ctx.thread.getParticipants();
+
+  // After — typechecked against the actual chat@4.28.1 Thread interface
+  // with full autocomplete, JSDoc, and error reporting:
+  await ctx.thread.refresh();
+  await ctx.thread.startTyping("Working on it…");
+  const participants = await ctx.thread.getParticipants();
+  ```
+
+  If your handlers were calling methods that don't exist on `Thread` and were passing typecheck through `any`, you'll see real type errors now. The runtime behavior is unchanged.
+
+  Vendor-script refactor (internal, no public-API impact):
+
+  - `scripts/vendor-compiled.mjs` shrank from ~1500 lines to ~36 lines. Per-package configs moved to one file each under `scripts/vendor-compiled/`, mirroring npm package names (`@chat-adapter/slack.mjs`, `@workflow/core.mjs`, etc.).
+  - Inline `.d.ts` template-literal strings moved to real `.d.ts` files under `scripts/vendor-compiled/declarations/` with editor syntax highlighting.
+  - Reusable bundling primitives (`runVendor`, `createDeclarationCopier`, `buildUniqueSymbolStub`, `buildOpaqueTypesStub`, `createOptionalNativeStubPlugin`, `collectFilesRecursively`) live in `scripts/vendor-compiled/_shared.mjs` so other packages in the monorepo can adopt the same vendoring pipeline without duplication.
+
 ## 0.8.3
 
 ### Patch Changes

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

@@ -127,6 +127,7 @@ import { slackChannelCredentials } from "@vercel/connex/ash";
 import { slackChannel } from "experimental-ash/channels/slack";
 
 export default slackChannel({
+  credentials: slackChannelCredentials("slack/my-agent"),
   run(ctx, message) {
     return {
       auth: {
@@ -137,37 +138,57 @@ export default slackChannel({
       },
     };
   },
-  "message.completed"(event, ctx) {
-    if (event.finishReason === "tool-calls") return;
-    if (event.message) ctx.thread.post(event.message);
-  },
-  "session.failed"(event, ctx) {
-    ctx.thread.post("Something went wrong.");
+  events: {
+    "message.completed"(event, ctx) {
+      if (event.finishReason === "tool-calls") return;
+      if (event.message) ctx.thread.post(event.message);
+    },
+    "session.failed"(event, ctx) {
+      ctx.thread.post("Something went wrong.");
+    },
   },
-  credentials: slackChannelCredentials("slack/my-agent"),
 });
 ```
 
+## Hooks
+
+`slackChannel` exposes three places to plug in custom behavior:
+
+- **`run(ctx, message)`** -- decides whether to dispatch a turn for an inbound `app_mention` and
+  with what `auth` context. Returns `{ auth }` to dispatch or `null` to silently drop the mention.
+  May be sync or async; the framework awaits the result before dispatching.
+- **`onMention(ctx, message)`** -- free-form pre-dispatch side effects, invoked on the inbound
+  webhook side after `run()` accepts and before the turn is enqueued. Use it for work that should
+  fire immediately, before the workflow runtime cold-starts -- starting a typing indicator,
+  logging, etc. Errors are caught and logged; the turn still dispatches.
+- **`onInteraction(action, ctx)`** -- handler for Slack `block_actions` callbacks (button clicks,
+  selects, etc.) that are not consumed by the framework's HITL pipeline. Runs on the inbound
+  webhook side via `waitUntil`, so the channel returns `200 OK` to Slack immediately.
+
+`events: { ... }` handlers receive runtime events emitted by the harness after the turn dispatches
+(`turn.started`, `message.completed`, `session.failed`, etc.). They run inside the workflow context,
+not on the inbound webhook side.
+
 ## Typing Indicators
 
 Out of the box, `slack()` posts typing statuses so the user sees feedback before the agent starts
 thinking:
 
-- **`Thinking...`** -- posted by the default handler the moment a mention arrives, before the agent
-  run starts.
+- **`Thinking...`** -- posted by the default `onMention` hook the moment a mention arrives, on the
+  inbound webhook side, before the workflow runtime starts.
+- **`Working...`** -- posted by the default `turn.started` event handler at the start of each turn
+  within the session, refreshing the typing indicator after the workflow runtime materializes.
 - **Tool status** -- when an `actions.requested` event fires, the default handler updates the typing
   indicator to show which tools are running.
 
-To customize typing indicators, use `slackChannel` and write your own event handlers:
+To customize typing indicators, use `slackChannel` and supply your own `onMention` plus event
+handlers:
 
 ```ts
 import { slackChannel } from "experimental-ash/channels/slack";
 
 export default slackChannel({
-  run(ctx, message) {
-    ctx.thread.startTyping(
-      message.text.includes("weather") ? "Checking the weather..." : "Thinking...",
-    );
+  run(_ctx, message) {
     return {
       auth: {
         principalId: message.author.userId,
@@ -177,21 +198,28 @@ export default slackChannel({
       },
     };
   },
-  "actions.requested"(event, ctx) {
-    const labels = event.actions.map((a) => (a.kind === "tool-call" ? a.toolName : a.kind));
-    ctx.thread.startTyping(`Running ${labels.join(", ")}...`);
-  },
-  "message.completed"(event, ctx) {
-    if (event.finishReason === "tool-calls") return;
-    if (event.message) ctx.thread.post(event.message);
+  async onMention(ctx, message) {
+    await ctx.thread.startTyping(
+      message.text.includes("weather") ? "Checking the weather..." : "Thinking...",
+    );
   },
-  "session.failed"(event, ctx) {
-    ctx.thread.post("Something went wrong.");
+  events: {
+    async "actions.requested"(event, ctx) {
+      const labels = event.actions.map((a) => (a.kind === "tool-call" ? a.toolName : a.kind));
+      await ctx.thread.startTyping(`Running ${labels.join(", ")}...`);
+    },
+    async "message.completed"(event, ctx) {
+      if (event.finishReason === "tool-calls") return;
+      if (event.message) await ctx.thread.post(event.message);
+    },
+    async "session.failed"(_event, ctx) {
+      await ctx.thread.post("Something went wrong.");
+    },
   },
 });
 ```
 
-Event handlers are declared as named properties on the config object. They receive `(eventData, ctx)`
-where `ctx` carries platform handles like `ctx.thread` and `ctx.session`.
+Event handlers are nested under `events: { ... }` and receive `(eventData, ctx)` where `ctx`
+carries platform handles like `ctx.thread` and `ctx.slack`.
 
 See [Channels](/docs/channels) for the full channel surface.

package/dist/src/compiled/.vendor-stamp.json

@@ -1,24 +1,24 @@
 {
   "moduleVersions": {
-    "turndown": "7.2.4",
-    "zod-validation-error": "5.0.0",
-    "zod": "4.4.3",
-    "chat": "4.27.0",
-    "@vercel/sandbox": "2.0.0-beta.14",
-    "@ai-sdk/provider": "4.0.0-canary.16",
     "@ai-sdk/anthropic": "4.0.0-canary.46",
+    "chat": "4.28.1",
+    "@chat-adapter/slack": "4.28.1",
+    "@chat-adapter/state-memory": "4.28.1",
     "@ai-sdk/google": "4.0.0-canary.53",
-    "@ai-sdk/openai": "4.0.0-canary.49",
+    "jose": "6.2.3",
+    "just-bash": "2.14.5",
     "@ai-sdk/mcp": "2.0.0-canary.41",
+    "@ai-sdk/openai": "4.0.0-canary.49",
     "@opentelemetry/api": "1.9.1",
+    "@ai-sdk/otel": "1.0.0-canary.77",
+    "@ai-sdk/provider": "4.0.0-canary.16",
+    "@standard-schema/spec": "1.1.0",
+    "turndown": "7.2.4",
+    "@vercel/sandbox": "2.0.0-beta.14",
     "@workflow/core": "5.0.0-beta.5",
     "@workflow/errors": "5.0.0-beta.2",
-    "@ai-sdk/otel": "1.0.0-canary.77",
-    "@chat-adapter/slack": "4.27.0",
-    "@chat-adapter/state-memory": "4.27.0",
-    "jose": "6.2.3",
-    "just-bash": "2.14.5",
-    "@standard-schema/spec": "1.1.0"
+    "zod": "4.4.3",
+    "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "520ce458abd555329457db163ebe68cdefda54855571c6d96b4f2a0fb76aa0c9"
+  "scriptHash": "ae1e079196d6cbf9f9fec8b3083fba06192d71d35e09f8980a9b99415c0d463a"
 }