experimental-ash 0.59.0 → 0.61.0

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

@@ -1,661 +0,0 @@
----
-title: "Channels"
-description: "Deliver your agent over HTTP, Slack, GitHub, Discord, Twilio, Telegram, Microsoft Teams, and custom transports."
-url: /channels
----
-
-Channels let Ash receive messages from external systems and deliver responses back to the same
-conversation surface.
-
-A channel is defined with `defineChannel()`. It declares routes, optional state, an optional
-`context()` factory, and typed event handlers under `events`. Route handlers receive the inbound
-request and a helpers object with `send()` and `getSession()`. The `send()` function is the unified
-entry point for starting a new turn or resuming a session -- it replaces the old `ctx.agent.run()` and
-`ctx.agent.deliver()` split.
-
-The runtime and harness still own the model turn, tool execution, compaction, and session
-persistence.
-
-## Where Channels Fit
-
-Ash ships the public HTTP protocol as channels:
-
-- `ashChannel({ auth })` for the built-in Ash protocol channel
-
-Ash also supports authored channels under `agent/channels/` for platform-specific integrations such
-as Slack, GitHub, Discord, Twilio, Telegram, Microsoft Teams, or custom webhooks.
-
-## Filesystem Shape
-
-```text
-agent/
-  agent.ts
-  instructions.md
-  channels/
-    slack.ts
-```
-
-Rules that matter:
-
-- `channels/` is root-only today.
-- local subagents do not declare channels.
-- channel files are module-backed only.
-- the file stem becomes the channel id.
-
-## The Main API
-
-```ts
-import { defineChannel, POST, GET } from "experimental-ash/channels";
-
-export default defineChannel({
-  routes: [
-    POST("/message", async (req, { send, getSession, waitUntil }) => {
-      const body = await req.json();
-      const session = await send(body.message, {
-        auth: null,
-        continuationToken: body.token,
-      });
-      return Response.json({ sessionId: session.id });
-    }),
-    GET("/sessions/:sessionId/stream", async (req, { getSession, params }) => {
-      const session = getSession(params.sessionId);
-      const stream = await session.getEventStream();
-      return new Response(stream, {
-        headers: { "content-type": "text/event-stream" },
-      });
-    }),
-  ],
-  events: {
-    "message.completed"(event, ctx) {
-      // handle completed messages
-    },
-  },
-});
-```
-
-`defineChannel({ routes, ... })` defines a channel. Routes are declared with `POST()` and `GET()`
-helpers. Each route handler receives the raw `Request` and a helpers object:
-
-- `send(message, { auth, continuationToken, state? })` -- start or resume a session. Returns a
-  `Session`.
-- `getSession(sessionId)` -- look up an existing session. The returned `Session` exposes
-  `getEventStream({ startIndex? })` for streaming.
-- `params` -- route parameters extracted from the path pattern.
-- `waitUntil(promise)` -- extend the request lifetime for background work.
-
-Event handlers like `"message.completed"` are declared under the `events` key on the config object.
-They receive `(eventData, channel, ctx)` where `channel` carries platform handles and session
-continuation operations, and `ctx` is the Ash `SessionContext`. Use
-`toolResultFrom` from `experimental-ash/tools` to narrow tool results (see
-[Hooks — Narrowing tool results](../hooks.mdx#narrowing-tool-results)).
-
-## The Ash Channel
-
-The framework ships its canonical session protocol on `experimental-ash/channels/ash`:
-
-- `ashChannel({ auth, onMessage?, events? })`
-
-This is the channel the Ash dev client and any deployed-agent SDK talk to — it mounts the routes
-under `/ash/v1/session*` documented in [Ash External Agent Protocol](../../external-agent-protocol.md).
-
-`auth` accepts either a single `AuthFn` or an ordered array walked in order: the first entry
-returning a `SessionAuthContext` wins, `null` / `undefined` skips, exhaustion (including `[]`)
-returns `401`. Use `experimental-ash/channels/auth` for the common helpers such as `localDev()`,
-`vercelOidc()`, `httpBasic()`, and `none()`.
-
-```ts
-import { ashChannel } from "experimental-ash/channels/ash";
-import { localDev, vercelOidc } from "experimental-ash/channels/auth";
-
-export default ashChannel({
-  auth: [localDev(), vercelOidc()],
-});
-```
-
-Pass `onMessage` to add authenticated context before the Ash HTTP channel dispatches a user
-message. The hook runs after `auth` succeeds and body parsing completes, so `ctx.ash.caller` is
-available for caller-specific lookups. Return `{ auth, context }` to choose the runtime session
-auth and append context strings as user messages before the inbound message, or `null` to accept
-the request without dispatching a turn. When `onMessage` is omitted, Ash dispatches with
-`defaultAshAuth(ctx)`.
-
-```ts
-import { ashChannel, defaultAshAuth } from "experimental-ash/channels/ash";
-
-export default ashChannel({
-  auth: [localDev(), vercelOidc()],
-  async onMessage(ctx, message) {
-    const auth = defaultAshAuth(ctx);
-    const profile = auth ? await loadCallerProfile(auth.principalId) : null;
-
-    return {
-      auth,
-      context: profile ? [`Caller profile:\n${JSON.stringify(profile)}`] : [],
-    };
-  },
-});
-```
-
-Pass `events` to observe runtime stream events on the default HTTP channel. The Ash channel has no
-platform-specific context, so `channel` exposes session continuation operations and `ctx` exposes
-the current session context:
-
-```ts
-export default ashChannel({
-  auth: [localDev(), vercelOidc()],
-  events: {
-    "turn.started"(_event, _channel, ctx) {
-      auditTurn(ctx.session.id);
-    },
-  },
-});
-```
-
-`pnpm create experimental-ash-agent` scaffolds the Web Chat example channel at
-`agent/channels/ash.ts`. It permits Vercel OIDC and localhost requests and includes an
-`exampleProductionAuth()` placeholder that throws in production until you replace it
-with end-user auth. If you delete the authored file, Ash falls back to
-`[localDev(), vercelOidc()]`; that default does not admit browser users in production.
-See [Auth and Route Protection](../auth-and-route-protection.mdx) for the full walking
-semantics and helper reference.
-
-## Slack Channels
-
-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.
-
-### Zero-config
-
-```ts
-import { slackChannel } from "experimental-ash/channels/slack";
-
-export default slackChannel();
-```
-
-Handles app mentions, direct messages, typing indicators, message delivery, and HITL interactions
-out of the box. The default `onAppMention` and `onDirectMessage` derive auth from the inbound Slack
-actor and post a `"Thinking…"` typing indicator before the workflow runtime starts.
-
-### Custom config
-
-When you need custom rendering or event handling, pass a config object. `onAppMention` decides
-whether to dispatch a channel mention; `onDirectMessage` does the same for 1:1 DMs (`message`
-events with `channel_type: "im"`); `events` lets you replace individual event handlers;
-`onInteraction` handles non-HITL button clicks.
-
-```ts
-import { slackChannel } from "experimental-ash/channels/slack";
-
-export default slackChannel({
-  onAppMention(ctx, message) {
-    if (!message.author) return null;
-    return {
-      auth: {
-        principalId: message.author.userId,
-        principalType: "user",
-        authenticator: "slack",
-        attributes: {},
-      },
-    };
-  },
-  onDirectMessage(ctx, message) {
-    if (!message.author) return null;
-    return {
-      auth: {
-        principalId: message.author.userId,
-        principalType: "user",
-        authenticator: "slack",
-        attributes: { surface: "im" },
-      },
-    };
-  },
-  events: {
-    "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);
-    },
-    "session.failed"(_event, ctx) {
-      ctx.thread.post("Something went wrong.");
-    },
-  },
-});
-```
-
-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. Direct messages require the Slack app to subscribe to `message.im` with the `im:history`
-scope.
-
-### Interactions
-
-Interactions (button clicks, modals) are platform events, not agent events. They do not appear in the
-event handlers.
-
-`slackChannel()` handles interactions in two paths:
-
-- **HITL interactions** (approval buttons matching pending input requests) are delivered to the agent
-  automatically. The agent resumes.
-- **Custom interactions** (feedback buttons, SQL toggles) are passed to `onInteraction`:
-
-```ts
-import { slackChannel } from "experimental-ash/channels/slack";
-
-export default slackChannel({
-  onAppMention(ctx, message) {
-    if (!message.author) return null;
-    return {
-      auth: {
-        principalId: message.author.userId,
-        principalType: "user",
-        authenticator: "slack",
-        attributes: {},
-      },
-    };
-  },
-  events: {
-    "message.completed"(event, ctx) {
-      if (event.finishReason === "tool-calls") return;
-      if (event.message) ctx.thread.post(event.message);
-    },
-  },
-  onInteraction(action, ctx) {
-    // handle custom button clicks
-  },
-});
-```
-
-### The two shapes
-
-```text
-defineChannel({ routes: [...], events: {...} })                                     -- raw: you handle HTTP
-ashChannel({ auth, onMessage?, events? })                                           -- ash: default HTTP protocol
-slackChannel({ onAppMention?, onDirectMessage?, events?, onInteraction? })          -- slack: everything wired, override as needed
-```
-
-`slackChannel(config)` compiles down to `defineChannel` plus typed inbound parsing and event
-dispatch for app mentions, direct messages, and interactions.
-
-For a Slack app backed by Vercel Connect, see [Slack channel setup](./slack.mdx) to create the Connect client
-and channel file.
-
-## GitHub Channels
-
-GitHub channels are authored with `githubChannel()`:
-
-```ts
-import { githubChannel } from "experimental-ash/channels/github";
-
-export default githubChannel({
-  botName: "my-agent",
-});
-```
-
-The channel verifies GitHub App webhooks at `/ash/v1/github`, dispatches bot-directed issue/PR
-comments and pull-request review comments, can opt into issue and pull-request hooks, exposes
-GitHub-native issue, PR, reaction, and checkout helpers, and injects bounded PR metadata,
-file lists, and patch text as turn `context`.
-
-See [GitHub channel setup](./github.md) for GitHub App permissions, PR context, checkout, and
-custom inbound hooks.
-
-## Discord Channels
-
-Discord channels are authored with `discordChannel()`:
-
-```ts
-import { discordChannel } from "experimental-ash/channels/discord";
-
-export default discordChannel();
-```
-
-The channel verifies Discord's Ed25519 interaction signature headers, accepts HTTP Interactions at
-`/ash/v1/discord`, responds to `PING`, dispatches application commands, and resolves HITL button,
-select, and modal submissions back into Ash input responses. The default command parser uses a
-string option named `message` as the agent prompt and derives auth from the invoking Discord user.
-
-Default delivery edits the original deferred interaction response for the first agent reply, sends
-followups after that, and falls back to bot-token channel messages when the interaction token can no
-longer be used. Proactive `receive(discord, { channelId })` sessions also use bot-token channel
-messages. Default progress handlers trigger Discord's short-lived typing indicator when bot auth is
-available.
-
-See [Discord channel setup](./discord.mdx) for endpoint setup, environment variables, command
-registration, and overrides.
-
-## Twilio Channels
-
-Twilio channels are authored with `twilioChannel()`:
-
-```ts
-import { twilioChannel } from "experimental-ash/channels/twilio";
-
-export default twilioChannel({
-  allowFrom: "+15551234567",
-});
-```
-
-The channel verifies `X-Twilio-Signature` itself, accepts inbound SMS at
-`/ash/v1/twilio/messages`, answers phone calls at `/ash/v1/twilio/voice`, and dispatches speech
-transcripts posted to `/ash/v1/twilio/voice/transcription`. The raw continuation token is the
-caller/sender phone number plus the Twilio receiver (`From:To`), so texts and call transcripts for
-the same phone-number pair resume the same Ash session without collapsing conversations that use
-different Twilio numbers. `allowFrom` accepts a single phone number, a list, or a zero-argument
-resolver when the allowed phone numbers come from dynamic state. Use `allowFrom: "*"` only when the
-`onText` and `onVoice` hooks perform their own incoming-number checks.
-
-See [Twilio channel setup](./twilio.mdx) for webhook URLs, environment variables, and overrides.
-
-## Telegram Channels
-
-Telegram channels are authored with `telegramChannel()`:
-
-```ts
-import { telegramChannel } from "experimental-ash/channels/telegram";
-
-export default telegramChannel({
-  botUsername: "my_bot",
-});
-```
-
-The channel verifies Telegram's `X-Telegram-Bot-Api-Secret-Token` webhook header, accepts updates at
-`/ash/v1/telegram`, dispatches private messages and addressed group messages, and resolves HITL
-inline-keyboard callbacks and ForceReply answers back into Ash input responses. Private chats use
-chat-wide continuation tokens. Group, supergroup, and forum-topic sessions include the chat id,
-optional `message_thread_id`, and a conversation anchor so multiple bot conversations in the same
-chat do not collapse.
-
-Default delivery sends plain text through Telegram `sendMessage` with no `parse_mode`, splits text
-at Telegram's 4096-character limit, and uses best-effort `sendChatAction("typing")` progress
-indicators. Photos and documents are exposed as file parts and fetched through Telegram `getFile`
-when the model needs the bytes.
-
-See [Telegram channel setup](./telegram.mdx) for webhook registration, environment variables, group
-privacy notes, HITL behavior, attachments, and proactive sessions.
-
-## Microsoft Teams Channels
-
-Teams channels are authored with `teamsChannel()`:
-
-```ts
-import { teamsChannel } from "experimental-ash/channels/teams";
-
-export default teamsChannel();
-```
-
-The channel verifies Bot Connector bearer JWTs, accepts Teams Bot Framework Activity POSTs at
-`/ash/v1/teams`, dispatches personal messages and direct bot mentions, renders HITL prompts as
-Adaptive Cards, and sends agent replies through the Bot Framework Connector REST API. Personal chats
-resume by conversation id; channel and group-chat threads resume by conversation id plus root
-activity id.
-
-Proactive `receive(teams, { target })` sessions require an existing conversation reference
-(`serviceUrl` and `conversationId`). See [Microsoft Teams channel setup](./teams.mdx) for Azure Bot
-setup, environment variables, proactive handoff, HITL, and file options.
-
-## Cross-Channel Hand-off
-
-Route handlers can start a session on a different channel via `args.receive(channel, ...)`.
-Use this when an inbound request on one channel should pivot the conversation onto another
--- for example, an incident webhook hits an HTTP route and the operator interacts in Slack.
-
-```ts
-import { defineChannel, POST } from "experimental-ash/channels";
-import slack from "./slack.js";
-
-export default defineChannel({
-  routes: [
-    POST("/incident", async (req, args) => {
-      const incident = await req.json();
-      args.waitUntil(
-        args.receive(slack, {
-          message: `Investigate ${incident.reference}: ${incident.title}`,
-          target: { channelId: "C0123ABC" },
-          auth: {
-            authenticator: "incidentio",
-            principalType: "service",
-            principalId: incident.actor.id,
-            attributes: { reference: incident.reference, severity: incident.severity },
-          },
-        }),
-      );
-      return new Response("ok");
-    }),
-  ],
-});
-```
-
-Semantics:
-
-- The target channel's authored `receive(input, { send })` hook owns the continuation-token
-  format and the initial state. Callers supply only `{ message, target, auth }`.
-- `auth` flows through to `session.auth.initiator` so the target's event handlers and the
-  agent's tools can read who started the session.
-- Calling `args.receive(...)` does **not** also start a session on the current channel. The
-  inbound channel's response is whatever the route handler returns explicitly (e.g.
-  `200 OK` to acknowledge the webhook).
-- The first argument is the target channel module's default export -- import it directly
-  from `agent/channels/<name>.ts`. Identity is matched by reference.
-
-### Slack thread anchoring
-
-When a Slack session starts without a `threadTs` (programmatic `args.receive(slack, ...)`,
-schedule fires, etc.), the channel **auto-anchors on the first agent post**: the message
-becomes the thread root, and every subsequent post, typing indicator, and inbound
-`@mention` reply in that thread resumes the same Ash session. Schedule digests, webhook
-hand-offs, and other session-from-nothing flows produce clean Slack threads with no extra
-wiring — the channel passes the new channel-local token to
-`ctx.session.setContinuationToken(...)`, and the runtime re-keys the parked session to
-`slack:<channelId>:<anchored-ts>` so follow-up mentions land back in the same workflow.
-
-Pass `initialMessage` when you want a structured anchor card to land _before_ the agent
-runs — useful for "Investigation Thread for INC-42"-style banners that should precede
-the model's first reply:
-
-```ts
-import { Card, CardText } from "experimental-ash/channels/slack";
-
-await args.receive(slack, {
-  message: "Begin investigation",
-  target: {
-    channelId: "C0123ABC",
-    initialMessage: {
-      card: Card({ children: [CardText("Investigation Thread for INC-42")] }),
-      fallbackText: "Investigation Thread for INC-42",
-    },
-  },
-  auth,
-});
-```
-
-For inbound mentions in an existing Slack thread, `onAppMention` and
-`onDirectMessage` may return `context` to inject thread history as
-user messages in session history. See
-[Slack thread context](/docs/channels/slack#thread-context).
-
-`threadTs` and `initialMessage` are mutually exclusive: pass `threadTs` to join an existing
-thread, or `initialMessage` to anchor a new one. With neither, the first agent post anchors
-the thread automatically.
-
-## Channel Metadata
-
-Channels can project a subset of their adapter state as **metadata** available to
-instrumentation resolvers, dynamic tool resolvers, and dynamic skill/instruction resolvers.
-Define a `metadata(state)` function on the channel config:
-
-```ts
-import { defineChannel, POST } from "experimental-ash/channels";
-
-export default defineChannel({
-  state: {
-    topic: null as string | null,
-    contextMessages: [] as string[],
-    internalCounter: 0,
-  },
-
-  metadata(state) {
-    // Curated projection — internalCounter is withheld.
-    return {
-      topic: state.topic,
-      contextMessages: state.contextMessages,
-    };
-  },
-
-  routes: [
-    POST("/start", async (req, { send }) => {
-      const body = await req.json();
-      await send(body.message, {
-        auth: null,
-        continuationToken: body.token,
-        state: { topic: body.topic, contextMessages: body.context, internalCounter: 0 },
-      });
-      return new Response("ok");
-    }),
-  ],
-  events: {
-    "turn.started"(_event, ctx) {
-      ctx.state.internalCounter += 1;
-    },
-  },
-});
-```
-
-The projection is re-evaluated whenever adapter state changes (after channel event handlers
-run). Dynamic tool resolvers read it via `ctx.channel.metadata` and narrow it with
-`isChannel`. See [Dynamic Tools — Channel Metadata](../tools.mdx#channel-metadata) for the
-full consumption pattern.
-
-### Subagent propagation
-
-When a parent agent dispatches a subagent, the framework forwards the parent's channel
-metadata projection to the child. The subagent's dynamic tool resolvers see the originating
-channel's `kind` and `metadata` — not `kind: "subagent"` with empty metadata. This lets
-subagents conditionally resolve tools based on which channel is driving the conversation.
-
-### Shared with instrumentation
-
-The same `metadata(state)` projector serves both dynamic resolvers and the instrumentation
-`metadata["step.started"]` resolver. Each consumer picks what it needs: instrumentation
-flattens to `Record<string, string>` for OTel span attributes; tool resolvers use the full
-structured object.
-
-## Continuation Tokens
-
-Each call to `send(message, { auth, continuationToken, state? })` from a channel route
-addresses a session by its **channel-local raw token**. The framework prepends the
-channel name (the file stem under `agent/channels/`) before handing the token to the
-runtime, so a Slack route that passes `"C0123ABC:1800000000.001234"` ends up addressing
-session `"slack:C0123ABC:1800000000.001234"`.
-
-Authored channels typically ship a small helper for building the token:
-
-```ts
-import { slackContinuationToken } from "experimental-ash/channels/slack";
-import { twilioContinuationToken } from "experimental-ash/channels/twilio";
-
-slackContinuationToken("C0123ABC", "1800000000.001234"); // "C0123ABC:1800000000.001234"
-twilioContinuationToken("+15551234567", "+15557654321"); // "+15551234567:+15557654321"
-```
-
-Custom channels just write a function that joins their identity fields. The framework
-does not derive anything for you — the channel owns its token format.
-
-### Re-keying mid-session
-
-When the identity that should address a session isn't known until the first agent post
-(Slack's auto-anchor: the post's `ts` becomes the thread root), the channel re-keys the
-parked session by calling `ctx.session.setContinuationToken(...)` from a handler. Pass
-the **channel-local raw token**; the runtime preserves the current channel namespace:
-
-```ts
-import { defineChannel } from "experimental-ash/channels";
-
-defineChannel<{ ref: string | null }>({
-  state: { ref: null },
-  context(state, session) {
-    return {
-      state,
-      registerAnchor(ref: string) {
-        state.ref = ref;
-        session.setContinuationToken(ref);
-      },
-    };
-  },
-  events: {
-    "message.completed"(_event, ctx) {
-      if (!ctx.state.ref) ctx.registerAnchor(mintRef());
-    },
-  },
-  routes: [
-    /* ... */
-  ],
-});
-```
-
-The workflow runtime disposes the current park hook at the next step boundary and
-registers a new one at the new token. Inbound deliveries already addressed to the old
-token are dropped — coordinate with your senders so follow-up traffic uses the new
-token.
-
-## File Uploads
-
-`send()` accepts `string | UserContent`. To include file attachments,
-pass a `UserContent` array mixing text and file parts:
-
-```ts
-await send(
-  [
-    { type: "text", text: body.message },
-    { type: "file", data: imageBytes, mediaType: "image/png" },
-  ],
-  { auth: null, continuationToken: token },
-);
-```
-
-For platforms like Slack where files are behind authenticated URLs,
-put `URL` objects in `FilePart.data` and declare `fetchFile` on the
-channel config:
-
-```ts
-defineChannel({
-  fetchFile(url) {
-    if (!url.startsWith("https://files.slack.com/")) return null;
-    return fetch(url, { headers: { authorization: `Bearer ${token}` } })
-      .then((r) => r.arrayBuffer())
-      .then((b) => ({ bytes: Buffer.from(b) }));
-  },
-
-  routes: [
-    POST("/webhook", async (req, { send }) => {
-      await send(
-        [
-          { type: "text", text: message.text },
-          ...message.attachments.map((a) => ({
-            type: "file" as const,
-            data: new URL(a.url),
-            mediaType: a.mediaType,
-          })),
-        ],
-        { auth, continuationToken, state },
-      );
-    }),
-  ],
-});
-```
-
-See [Channel file uploads](./attachments.md) for the full guide.
-
-## What To Read Next
-
-- [Slack channel setup](./slack.mdx)
-- [GitHub channel setup](./github.md)
-- [Telegram channel setup](./telegram.mdx)
-- [Channel file uploads](./attachments.md)
-- [Project Layout](../project-layout.md)
-- [TypeScript API](../typescript-api.md)
-- [Auth And Route Protection](../auth-and-route-protection.mdx)
-- [Ash External Agent Protocol](../../external-agent-protocol.md)