experimental-ash 0.10.4 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # experimental-ash
 
+## 0.11.0
+
+### Minor Changes
+
+- c823956: refactor(slack): collapse `slack` and `slackChannel` into one `slackChannel()`; merge `run` + `onMention` into a single mention hook
+
+  The previous `slack` (defaults wrapper) and `slackChannel` (raw config) factories are unified behind a single `slackChannel(config?)` exported from `experimental-ash/channels/slack`. Defaults always apply; any field you supply replaces the corresponding default. Events you don't override keep their defaults. The default `onMention` derives a workspace-scoped auth from the inbound Slack actor and posts a `"Thinking…"` typing indicator before the workflow runtime cold-starts.
+
+  The separate `run` (gate + auth) and `onMention` (pre-dispatch side effects) hooks are merged into a single `onMention(ctx, message)` callback. Return `{ auth }` to dispatch, `null` to drop, and perform any side effects inline. Errors thrown from `onMention` are caught, logged, and drop the mention — previously side-effect throws were logged but dispatch continued. Wrap best-effort side effects in `try/catch` if you want them to be non-fatal.
+
+  Migration:
+
+  ```ts
+  // before — slackChannel with separate run + onMention
+  import { slackChannel } from "experimental-ash/channels/slack";
+
+  export default slackChannel({
+    run(ctx, message) {
+      if (!ALLOWED.has(ctx.slack.channelId)) return null;
+      return {
+        auth: {
+          /* ... */
+        },
+      };
+    },
+    onMention(ctx) {
+      ctx.thread.startTyping("Thinking…");
+    },
+    events: {
+      /* ... */
+    },
+  });
+
+  // before — slack() with defaults
+  import { slack } from "experimental-ash/channels/slack";
+
+  export default slack({
+    events: {
+      /* ... */
+    },
+  });
+
+  // after — one factory, one onMention hook
+  import { slackChannel } from "experimental-ash/channels/slack";
+
+  export default slackChannel({
+    onMention(ctx, message) {
+      if (!ALLOWED.has(ctx.slack.channelId)) return null;
+      ctx.thread.startTyping("Thinking…");
+      return {
+        auth: {
+          /* ... */
+        },
+      };
+    },
+    events: {
+      /* ... */
+    },
+  });
+  ```
+
+  Drops the `SlackOptions` type and the `run` / `onMention` split on `SlackChannelConfig`. Adds `SlackMentionResult` (`{ auth } | null`) and `SlackMentionResultOrPromise`.
+
 ## 0.10.4
 
 ### Patch Changes

package/README.md

@@ -49,7 +49,7 @@ Every authored directory has a typed helper. Import each from the matching subpa
 | `defineSkill(...)`, `getSkill(...)`                                                                                 | `experimental-ash/skills`                          | `skills/<name>.ts` (or `skills/<name>.md`)       |
 | `defineHook(...)`                                                                                                   | `experimental-ash/hooks`                           | `hooks/<slug>.ts`                                |
 | `defineChannel(...)`, `POST`, `GET`                                                                                 | `experimental-ash/channels`                        | `channels/<name>.ts`                             |
-| `ashChannel(...)`, `slack`, `slackChannel(...)`, `vercelOidc(...)`                                                  | `experimental-ash/channels/ash`, `/slack`, `/auth` | reused from `channels/<name>.ts`                 |
+| `ashChannel(...)`, `slackChannel(...)`, `vercelOidc(...)`                                                           | `experimental-ash/channels/ash`, `/slack`, `/auth` | reused from `channels/<name>.ts`                 |
 | `defineSandbox(...)`                                                                                                | `experimental-ash/sandbox`                         | `sandbox.ts` (or `sandbox/sandbox.ts`)           |
 | `defineSchedule(...)`                                                                                               | `experimental-ash/schedules`                       | `schedules/<name>.ts` (or `schedules/<name>.md`) |
 | `defineEvalSuite(...)`                                                                                              | `experimental-ash/evals`                           | `evals/<name>.eval.ts`                           |

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

@@ -109,29 +109,33 @@ export default ashChannel({
 
 ## Slack Channels
 
-For Slack, Ash provides three levels of abstraction:
+Slack channels are authored with a single `slackChannel()` factory. Pass no config for the
+zero-config defaults, or supply only the fields you want to override -- everything else keeps the
+default.
 
-### `slack()` -- zero-config
+### Zero-config
 
 ```ts
-import { slack } from "experimental-ash/channels/slack";
+import { slackChannel } from "experimental-ash/channels/slack";
 
-export default slack();
+export default slackChannel();
 ```
 
-Handles mentions, typing indicators, message delivery, and HITL interactions out of the box.
+Handles mentions, typing indicators, message delivery, and HITL interactions out of the box. The
+default `onMention` derives auth from the inbound Slack actor and posts a `"Thinking…"` typing
+indicator before the workflow runtime starts.
 
-### `slackChannel({ run, events })` -- custom config
+### Custom config
 
-When you need custom rendering or event handling, use `slackChannel` with a config object. The `run`
-function receives the channel context and the inbound message and returns run options like `auth`.
-Event handlers are declared under the `events` key.
+When you need custom rendering or event handling, pass a config object. `onMention` decides whether
+to dispatch and with what auth; `events` lets you replace individual event handlers; `onInteraction`
+handles non-HITL button clicks.
 
 ```ts
 import { slackChannel } from "experimental-ash/channels/slack";
 
 export default slackChannel({
-  run(ctx, message) {
+  onMention(ctx, message) {
     return {
       auth: {
         principalId: message.author.userId,
@@ -157,12 +161,16 @@ export default slackChannel({
 });
 ```
 
+Fields you supply fully replace the corresponding default -- if you pass your own
+`"message.completed"` handler, the default's behavior for that event is gone. Other defaults stay
+in place.
+
 ### Interactions
 
 Interactions (button clicks, modals) are platform events, not agent events. They do not appear in the
 event handlers.
 
-`slackChannel` handles interactions separately:
+`slackChannel()` handles interactions in two paths:
 
 - **HITL interactions** (approval buttons matching pending input requests) are delivered to the agent
   automatically. The agent resumes.
@@ -172,7 +180,7 @@ event handlers.
 import { slackChannel } from "experimental-ash/channels/slack";
 
 export default slackChannel({
-  run(ctx, message) {
+  onMention(ctx, message) {
     return {
       auth: {
         principalId: message.author.userId,
@@ -194,21 +202,17 @@ export default slackChannel({
 });
 ```
 
-### The three shapes
+### The two shapes
 
 ```
-defineChannel({ routes: [...], events: {...} })    -- raw: you handle HTTP
-slackChannel({ run, events: {...}, onInteraction })-- slack: you handle events
-slack()                                           -- default: everything handled
+defineChannel({ routes: [...], events: {...} })              -- raw: you handle HTTP
+slackChannel({ onMention?, events?, onInteraction? })        -- slack: everything wired, override as needed
 ```
 
-Each compiles down to the one below it:
-
-- `slack()` -> `slackChannel(defaultConfig)`
-- `slackChannel(config)` -> `defineChannel` + Chat SDK setup + typed event dispatch
-- `defineChannel` -> the primitive
+`slackChannel(config)` compiles down to `defineChannel` plus the Chat SDK setup and typed event
+dispatch.
 
-For a Slack app backed by Vercel Connex, see [Slack channel setup](./slack.md) to create the Connex client
+For a Slack app backed by Vercel Connect, see [Slack channel setup](./slack.md) to create the Connect client
 and channel file.
 
 ## File Uploads

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

@@ -1,38 +1,38 @@
 ---
 title: "Slack channel setup"
-description: "Create a Slack-backed Ash channel with Vercel Connex."
+description: "Create a Slack-backed Ash channel with Vercel Connect."
 type: integration
 related:
   - /channels
   - /connections
 ---
 
-Ash Slack channels can use Vercel Connex for both outbound Slack bot tokens and inbound webhook
-verification. With Connex, you do not need to manage `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET`
+Ash Slack channels can use Vercel Connect for both outbound Slack bot tokens and inbound webhook
+verification. With Connect, you do not need to manage `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET`
 environment variables yourself.
 
 ## Prerequisites
 
 - A Vercel project for the agent.
 - A Slack workspace where you can install the app.
-- Access to Vercel Connex for your team.
+- Access to Vercel Connect for your team.
 
-For local development, link the project and pull Vercel OIDC env vars so Connex can authenticate to
-the Vercel API:
+For local development, link the project and pull Vercel OIDC env vars so Connect can authenticate
+to the Vercel API:
 
 ```bash
 vercel link
 vercel env pull
 ```
 
-## Create The Connex Client
+## Create The Connect Client
 
-Create a Slack Connex client, then copy its UID. The UID is the value you pass to Ash, for example
+Create a Slack Connect client, then copy its UID. The UID is the value you pass to Ash, for example
 `slack/my-agent`.
 
 ### Dashboard Path
 
-Open [Connex in the Vercel dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connex&title=Go+to+Connex),
+Open [Connect in the Vercel dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect),
 then:
 
 1. Choose **Create Client**.
@@ -44,20 +44,20 @@ then:
 
 ### CLI Or Agent-Assisted Path
 
-The `vercel connex` command is currently gated for allow-listed teams. If the command is missing,
-update the Vercel CLI and enable the Connex flag in the terminal session where you will run the
+The `vercel connect` command is currently gated for allow-listed teams. If the command is missing,
+update the Vercel CLI and enable the Connect flag in the terminal session where you will run the
 commands:
 
 ```bash
 pnpm i -g vercel@latest
-export FF_CONNEX_ENABLED=1
-vercel connex --help
+export FF_CONNECT_ENABLED=1
+vercel connect --help
 ```
 
 The flag only applies to the current shell session. Export it again in new terminals, or add it to
-your shell config while you are working with Connex.
+your shell config while you are working with Connect.
 
-Make sure the CLI is authenticated and scoped to the Vercel team that has Connex access:
+Make sure the CLI is authenticated and scoped to the Vercel team that has Connect access:
 
 ```bash
 vercel login
@@ -65,34 +65,34 @@ vercel switch
 vercel link
 ```
 
-If you are using an AI coding agent, install the Connex skill first:
+If you are using an AI coding agent, install the Connect skill first:
 
 ```bash
-npx skills add https://github.com/vercel/connex --skill vercel-connex
+npx skills add https://github.com/vercel/connect --skill vercel-connect
 ```
 
 Then create the Slack client from the project or agent folder that will use it:
 
 ```bash
-vercel connex create slack
+vercel connect create slack
 ```
 
-Run Connex commands from the directory containing the agent's `package.json` or `vercel.json`.
-Connex uses that project context to configure project access, webhooks, and triggers. The command may
-open a browser for Slack installation or OAuth consent; finish that flow before continuing.
+Run Connect commands from the directory containing the agent's `package.json` or `vercel.json`.
+Connect uses that project context to configure project access, webhooks, and triggers. The command
+may open a browser for Slack installation or OAuth consent; finish that flow before continuing.
 
 You can list existing clients with:
 
 ```bash
-vercel connex list
+vercel connect list
 ```
 
-## Install Connex
+## Install Connect
 
-Add the Connex SDK to the Ash project:
+Add the Connect SDK to the Ash project:
 
 ```bash
-pnpm add @vercel/connex
+pnpm add @vercel/connect
 ```
 
 ## Add The Slack Channel File
@@ -100,35 +100,36 @@ pnpm add @vercel/connex
 Create `agent/channels/slack.ts`:
 
 ```ts
-import { slackChannelCredentials } from "@vercel/connex/ash";
-import { slack } from "experimental-ash/channels/slack";
+import { connectSlackCredentials } from "@vercel/connect/ash";
+import { slackChannel } from "experimental-ash/channels/slack";
 
-export default slack({
-  credentials: slackChannelCredentials("slack/my-agent"),
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
 });
 ```
 
-Replace `slack/my-agent` with the UID from the Connex client.
+Replace `slack/my-agent` with the UID from the Connect client.
 
 The helper returns a complete Slack credentials object:
 
-- `botToken` resolves an app-scoped Slack token through Connex for outbound posts.
-- `webhookVerifier` verifies Connex-forwarded Slack webhooks with Vercel OIDC.
+- `botToken` resolves an app-scoped Slack token through Connect for outbound posts.
+- `webhookVerifier` verifies Connect-forwarded Slack webhooks with Vercel OIDC.
 
-That means token rotation, refresh, multi-workspace tenancy, and inbound request verification stay in
-Connex instead of in your app environment.
+That means token rotation, refresh, multi-workspace tenancy, and inbound request verification stay
+in Connect instead of in your app environment.
 
 ## Customize Delivery
 
-If you need custom Slack rendering or interaction handling, use `slackChannel` with a config object:
+If you need custom Slack rendering or interaction handling, pass a config object to `slackChannel()`.
+Any field you supply replaces the corresponding default; fields you omit keep the defaults.
 
 ```ts
-import { slackChannelCredentials } from "@vercel/connex/ash";
+import { connectSlackCredentials } from "@vercel/connect/ash";
 import { slackChannel } from "experimental-ash/channels/slack";
 
 export default slackChannel({
-  credentials: slackChannelCredentials("slack/my-agent"),
-  run(ctx, message) {
+  credentials: connectSlackCredentials("slack/my-agent"),
+  onMention(ctx, message) {
     return {
       auth: {
         principalId: message.author.userId,
@@ -152,15 +153,15 @@ export default slackChannel({
 
 ## Hooks
 
-`slackChannel` exposes three places to plug in custom behavior:
+`slackChannel()` exposes two places to plug in custom behavior on the inbound webhook side:
 
-- **`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.
+- **`onMention(ctx, message)`** -- decides whether to dispatch a turn for an inbound `app_mention`,
+  with what `auth` context, and runs any pre-dispatch side effects (typing indicators, logging,
+  feature-flag lookups). Return `{ auth }` to dispatch or `null` to silently drop the mention. May
+  be sync or async; the framework awaits the result before dispatching. Thrown errors are caught,
+  logged, and drop the mention -- wrap best-effort side effects in `try/catch` if you want them to
+  be non-fatal. The default `onMention` derives a workspace-scoped auth from the Slack actor and
+  posts a `"Thinking…"` typing indicator.
 - **`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.
@@ -180,11 +181,11 @@ connection pool:
 
 ```ts
 import { createRedisState } from "@chat-adapter/state-redis";
-import { slack } from "experimental-ash/channels/slack";
+import { slackChannel } from "experimental-ash/channels/slack";
 
 const stateAdapter = createRedisState({ url: process.env.REDIS_URL! });
 
-export default slack({
+export default slackChannel({
   stateAdapter,
 });
 ```
@@ -194,8 +195,8 @@ 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
-thinking:
+Out of the box, `slackChannel()` posts typing statuses so the user sees feedback before the agent
+starts thinking:
 
 - **`Thinking...`** -- posted by the default `onMention` hook the moment a mention arrives, on the
   inbound webhook side, before the workflow runtime starts.
@@ -204,14 +205,17 @@ thinking:
 - **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 supply your own `onMention` plus event
-handlers:
+To customize typing indicators, override `onMention` and/or specific event handlers. Replacing one
+handler does not affect the others -- the rest keep their defaults.
 
 ```ts
 import { slackChannel } from "experimental-ash/channels/slack";
 
 export default slackChannel({
-  run(_ctx, message) {
+  async onMention(ctx, message) {
+    await ctx.thread.startTyping(
+      message.text.includes("weather") ? "Checking the weather..." : "Thinking...",
+    );
     return {
       auth: {
         principalId: message.author.userId,
@@ -221,23 +225,11 @@ export default slackChannel({
       },
     };
   },
-  async onMention(ctx, message) {
-    await ctx.thread.startTyping(
-      message.text.includes("weather") ? "Checking the weather..." : "Thinking...",
-    );
-  },
   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.");
-    },
   },
 });
 ```

package/dist/docs/public/connections.md

@@ -15,11 +15,11 @@ The model sees each connection through `connection_search` and picks tools based
 Every connection needs to decide how Ash obtains a bearer token for the MCP server. Pick one before
 you write the file — the rest of the shape is the same:
 
-| Strategy                                  | Use it when                                                                                                                     |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| [Static token](#static-tokens)            | You already have an API key or pre-provisioned JWT (env var, secrets manager, vault).                                           |
-| [Connex-managed OAuth](#oauth-via-connex) | The server uses OAuth and you want Vercel to own consent, token storage, and refresh.                                           |
-| [No auth](#no-auth)                       | The server doesn't require a token — localhost, public servers, or servers already authenticated through [`headers`](#headers). |
+| Strategy                                    | Use it when                                                                                                                     |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| [Static token](#static-tokens)              | You already have an API key or pre-provisioned JWT (env var, secrets manager, vault).                                           |
+| [Connect-managed OAuth](#oauth-via-connect) | The server uses OAuth and you want Vercel to own consent, token storage, and refresh.                                           |
+| [No auth](#no-auth)                         | The server doesn't require a token — localhost, public servers, or servers already authenticated through [`headers`](#headers). |
 
 If you need something the table doesn't cover (BYO token vault, custom signing flow, on-demand JWT
 exchange), use the static-token shape with whatever async logic you need inside `getToken`.
@@ -51,27 +51,27 @@ Ash defaults static `getToken`-only auth to `principalType: "app"`, which keys t
 cache by `"app"` so all sessions share the same credential. Set `principalType: "user"` when each
 end-user has their own token (see [Principal Type](#principal-type-user-vs-app)).
 
-## OAuth via Connex
+## OAuth via Connect
 
-For OAuth-backed connections, [Vercel Connex](https://vercel.com/docs/connex) can own the OAuth
-flow, encrypt token storage, and handle refresh. The `connex` helper from `@vercel/connex/ash`
-collapses that into a single declaration and wires Connex's typed errors into Ash's
+For OAuth-backed connections, [Vercel Connect](https://vercel.com/docs/connect) can own the OAuth
+flow, encrypt token storage, and handle refresh. The `connect` helper from `@vercel/connect/ash`
+collapses that into a single declaration and wires Connect's typed errors into Ash's
 `ConnectionAuthorizationRequiredError` / `ConnectionAuthorizationFailedError` so the runtime can
 drive consent without any connection-specific glue.
 
-**Prerequisites.** Connex is currently in private beta — your team needs to be enabled for it before
-the helper will work. Once you have access:
+**Prerequisites.** Connect is currently in private beta — your team needs to be enabled for it
+before the helper will work. Once you have access:
 
 1. Install the SDK:
 
    ```bash
-   pnpm add @vercel/connex
+   pnpm add @vercel/connect
    ```
 
-2. Create the Connex client — either in the Vercel dashboard or with
-   `vercel connex create <type> --name <uid>` from the CLI. Pick a `uid` (e.g. `"linear"`); this is
-   the value you'll pass to `connex()`.
-3. Link the Connex client to the Vercel project that runs your agent.
+2. Create the Connect client — either in the Vercel dashboard or with
+   `vercel connect create <type> --name <uid>` from the CLI. Pick a `uid` (e.g. `"linear"`); this is
+   the value you'll pass to `connect()`.
+3. Link the Connect client to the Vercel project that runs your agent.
 4. Run `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally — the SDK
    uses it to authenticate to the Vercel API. On Vercel deployments OIDC is auto-provisioned.
 
@@ -79,24 +79,25 @@ Then declare the connection:
 
 ```ts
 // agent/connections/linear.ts
-import { connex } from "@vercel/connex/ash";
+import { connect } from "@vercel/connect/ash";
 import { defineMcpClientConnection } from "experimental-ash/connections";
 
 export default defineMcpClientConnection({
   url: "https://mcp.linear.app/sse",
   description: "Linear workspace — issues, projects, cycles, and comments.",
-  auth: connex("linear"),
+  auth: connect("linear"),
 });
 ```
 
-`"linear"` is the UID you chose when registering the Connex client (any string that doesn't start
-with a Vercel-reserved prefix). Use the object form when you need to pass additional Connex options:
+`"linear"` is the UID you chose when registering the Connect client (any string that doesn't start
+with a Vercel-reserved prefix). Use the object form when you need to pass additional Connect
+options:
 
 ```ts
-auth: connex({ clientId: "linear" }),
+auth: connect({ clientId: "linear" }),
 ```
 
-Connex-managed OAuth defaults to user-scoped auth — each end-user authorizes through their own
+Connect-managed OAuth defaults to user-scoped auth — each end-user authorizes through their own
 browser, and the runtime resolves the per-user token before each tool call.
 
 ## No Auth
@@ -113,7 +114,7 @@ export default defineMcpClientConnection({
 
 ## Principal Type: `user` vs `app`
 
-Connex-managed OAuth defaults to user-scoped auth. Custom `getToken` auth may set `principalType`
+Connect-managed OAuth defaults to user-scoped auth. Custom `getToken` auth may set `principalType`
 when it needs a different cache and principal model:
 
 - `principalType: "user"` returns an interactive definition. Each end-user authorizes the
@@ -151,7 +152,7 @@ import { once } from "experimental-ash/tools/approval";
 export default defineMcpClientConnection({
   url: "https://mcp.linear.app/sse",
   description: "Linear workspace.",
-  auth: connex("linear"),
+  auth: connect("linear"),
   approval: once(),
 });
 ```
@@ -168,7 +169,7 @@ Constrain which tools the model sees with `tools.allow` or `tools.block`:
 export default defineMcpClientConnection({
   url: "https://mcp.linear.app/sse",
   description: "Linear — read-only.",
-  auth: connex("linear"),
+  auth: connect("linear"),
   tools: { allow: ["search_issues", "get_issue"] },
 });
 ```

package/dist/docs/public/project-layout.md

@@ -156,7 +156,7 @@ Use:
 - `lib/` for shared helper modules imported by the slots above
 
 See [Connections](./connections.md) for the connection authorization shape, including the
-`@vercel/connex/ash` helper for OAuth-backed connections.
+`@vercel/connect/ash` helper for OAuth-backed connections.
 
 ## What To Read Next
 

package/dist/docs/public/session-context.md

@@ -110,9 +110,9 @@ See [Skills](./skills.md) for the full authoring model.
 ## Passing Custom Context From a Channel
 
 Channels can inject custom typed durable context into the agent via the channel's `state` and
-`context()` properties on `defineChannel`, or via `run()` options on `slackChannel`. This is useful
-when a channel needs to pass platform-specific metadata (tenant ID, feature flags, etc.) that
-authored tools can read on the same turn and on later turns.
+`context()` properties on `defineChannel`, or via the auth attributes returned from `onMention` on
+`slackChannel()`. This is useful when a channel needs to pass platform-specific metadata (tenant
+ID, feature flags, etc.) that authored tools can read on the same turn and on later turns.
 
 ### Defining a key
 
@@ -129,7 +129,7 @@ export const TenantKey = new ContextKey<string>("myapp.tenant");
 
 ### Setting context from a channel
 
-Use `slackChannel` and seed context via the `run()` return value or the channel `state`:
+Use `slackChannel()` and seed context via the `onMention` return value's auth attributes:
 
 `agent/channels/slack.ts`
 
@@ -138,7 +138,7 @@ import { slackChannel } from "experimental-ash/channels/slack";
 import { TenantKey } from "./keys.js";
 
 export default slackChannel({
-  run(ctx, message) {
+  onMention(ctx, message) {
     const tenantId = lookupTenant(message);
     return {
       auth: {
@@ -149,17 +149,19 @@ 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.");
+    },
   },
 });
 ```
 
-Auth lives on the return value of `run()`, not on a separate channel object.
+Auth lives on the return value of `onMention`, not on a separate channel object.
 
 ### Reading context from a tool
 

package/dist/docs/public/typescript-api.md

@@ -66,12 +66,13 @@ Ash also exports lower-level runtime primitives such as `createToolLoopHarness(.
 
 Channel and Slack types exported from `experimental-ash/channels/slack`:
 
-- `slack` - zero-config Slack channel
-- `slackChannel` - custom Slack channel with config object (`run`, event handlers, `onInteraction`)
-- `SlackChannelConfig` - config type for `slackChannel`
+- `slackChannel` - Slack channel factory; zero-config by default, accepts a `SlackChannelConfig`
+  to override `onMention`, individual event handlers, `onInteraction`, etc.
+- `SlackChannelConfig` - config type for `slackChannel(...)`
 - `SlackContext` - context type for Slack event handlers (`thread`, `slack`)
 - `SlackApiHandle` - Slack API handle with `channelId`, `threadTs`, `request()`
 - `SlackInteractionAction` - action type for `onInteraction`
+- `SlackMentionResult` - return type of `onMention` (`{ auth } | null`)
 - `Thread`, `Message`, `Card`, `Button`, `Actions`, etc. - Chat SDK types for Slack rendering
 
 Channel types exported from `experimental-ash/channels`:
@@ -114,7 +115,7 @@ import { defineAgent } from "experimental-ash";
 import { defineChannel, POST, GET } from "experimental-ash/channels";
 import { ashChannel } from "experimental-ash/channels/ash";
 import { vercelOidc } from "experimental-ash/channels/auth";
-import { slack, slackChannel } from "experimental-ash/channels/slack";
+import { slackChannel } from "experimental-ash/channels/slack";
 ```
 
 Inside a route handler, the helpers object exposes: