experimental-ash 0.41.0 → 0.43.0

package/dist/docs/public/agent-ts.md

@@ -38,7 +38,7 @@ Use `agent.ts` for:
 - provider-specific model options
 
 Per-tool approval (formerly "human-in-the-loop policy") lives on each tool via `needsApproval`,
-not in `agent.ts`. See [Human In The Loop](./human-in-the-loop.md).
+not in `agent.ts`. See [Human In The Loop](./human-in-the-loop.mdx).
 
 For OpenTelemetry configuration, use `instrumentation.ts` instead. See
 [`instrumentation.ts`](./instrumentation.md).
@@ -135,7 +135,7 @@ The shared per-run workspace is configured on the sandbox, not on `agent.ts`. Se
 ## Human In The Loop
 
 Approval policy lives on individual tools via `needsApproval` in `defineTool({...})`, not on
-`agent.ts`. See [Human In The Loop](./human-in-the-loop.md) for the runtime flow, `input.requested`
+`agent.ts`. See [Human In The Loop](./human-in-the-loop.mdx) for the runtime flow, `input.requested`
 events, and HTTP response payloads.
 
 ## Telemetry
@@ -149,7 +149,7 @@ OpenTelemetry tracing is configured in `agent/instrumentation.ts`, not in `agent
 
 Those concerns live on the HTTP channel layer instead. See:
 
-- [Auth And Route Protection](./auth-and-route-protection.md)
+- [Auth And Route Protection](./auth-and-route-protection.mdx)
 - [Channels](./channels/README.md)
 
 ## A Good Default
@@ -169,6 +169,6 @@ That is enough to start. Add build and compaction settings only when you need th
 ## What To Read Next
 
 - [Context Control](./context-control.md)
-- [Human In The Loop](./human-in-the-loop.md)
+- [Human In The Loop](./human-in-the-loop.mdx)
 - [Workspace](./workspace.md)
-- [Auth And Route Protection](./auth-and-route-protection.md)
+- [Auth And Route Protection](./auth-and-route-protection.mdx)

package/dist/docs/public/channels/{discord.md → discord.mdx}

@@ -9,6 +9,17 @@ The Discord channel accepts HTTP Interactions: slash/application commands, messa
 modal submissions. It verifies Discord's Ed25519 signature headers before parsing the request,
 acknowledges commands immediately, and continues Ash work in the background.
 
+<CopyPrompt text="Add Discord support to the user's Ash project. Ash Discord channels are authored in agent/channels/discord.ts with discordChannel, verify Discord Ed25519 interaction signatures, mount POST /ash/v1/discord by default, defer command responses, deliver replies and HITL components, and can use proactive bot-token messages. Inspect existing channels and env conventions, add the channel file, configure DISCORD_PUBLIC_KEY, DISCORD_APPLICATION_ID, and DISCORD_BOT_TOKEN or equivalent config, set the Discord Interactions Endpoint URL, register or update an application command with a string message option, verify command delivery and HITL behavior, and do not commit unless the user asks.">
+  Add Discord support to the user's Ash project. Ash Discord channels are authored in
+  agent/channels/discord.ts with discordChannel, verify Discord Ed25519 interaction signatures,
+  mount POST /ash/v1/discord by default, defer command responses, deliver replies and HITL
+  components, and can use proactive bot-token messages. Inspect existing channels and env
+  conventions, add the channel file, configure DISCORD_PUBLIC_KEY, DISCORD_APPLICATION_ID, and
+  DISCORD_BOT_TOKEN or equivalent config, set the Discord Interactions Endpoint URL, register or
+  update an application command with a string message option, verify command delivery and HITL
+  behavior, and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Add The Channel
 
 Create `agent/channels/discord.ts`:

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

@@ -86,7 +86,7 @@ helpers. Each route handler receives the raw `Request` and a helpers object:
 Event handlers like `"message.completed"` are declared under the `events` key on the config object.
 They receive `(eventData, ctx)` where `ctx` carries platform handles and `ctx.session`. Use
 `toolResultFrom` from `experimental-ash/tools` to narrow tool results (see
-[Hooks — Narrowing tool results](../hooks.md#narrowing-tool-results)).
+[Hooks — Narrowing tool results](../hooks.mdx#narrowing-tool-results)).
 
 ## The Ash Channel
 
@@ -116,7 +116,7 @@ export default ashChannel({
 `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.md) for the full walking
+See [Auth and Route Protection](../auth-and-route-protection.mdx) for the full walking
 semantics and helper reference.
 
 ## Slack Channels
@@ -239,7 +239,7 @@ slackChannel({ onAppMention?, onDirectMessage?, events?, onInteraction? })
 `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.md) to create the Connect client
+For a Slack app backed by Vercel Connect, see [Slack channel setup](./slack.mdx) to create the Connect client
 and channel file.
 
 ## Discord Channels
@@ -263,7 +263,7 @@ longer be used. Proactive `receive(discord, { channelId })` sessions also use bo
 messages. Default progress handlers trigger Discord's short-lived typing indicator when bot auth is
 available.
 
-See [Discord channel setup](./discord.md) for endpoint setup, environment variables, command
+See [Discord channel setup](./discord.mdx) for endpoint setup, environment variables, command
 registration, and overrides.
 
 ## Twilio Channels
@@ -287,7 +287,7 @@ different Twilio numbers. `allowFrom` accepts a single phone number, a list, or
 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.md) for webhook URLs, environment variables, and overrides.
+See [Twilio channel setup](./twilio.mdx) for webhook URLs, environment variables, and overrides.
 
 ## Telegram Channels
 
@@ -313,7 +313,7 @@ at Telegram's 4096-character limit, and uses best-effort `sendChatAction("typing
 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.md) for webhook registration, environment variables, group
+See [Telegram channel setup](./telegram.mdx) for webhook registration, environment variables, group
 privacy notes, HITL behavior, attachments, and proactive sessions.
 
 ## Microsoft Teams Channels
@@ -333,7 +333,7 @@ resume by conversation id; channel and group-chat threads resume by conversation
 activity id.
 
 Proactive `receive(teams, args)` sessions require an existing conversation reference
-(`serviceUrl` and `conversationId`). See [Microsoft Teams channel setup](./teams.md) for Azure Bot
+(`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
@@ -528,10 +528,10 @@ See [Channel file uploads](./attachments.md) for the full guide.
 
 ## What To Read Next
 
-- [Slack channel setup](./slack.md)
-- [Telegram channel setup](./telegram.md)
+- [Slack channel setup](./slack.mdx)
+- [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.md)
+- [Auth And Route Protection](../auth-and-route-protection.mdx)
 - [Ash External Agent Protocol](../../external-agent-protocol.md)

package/dist/docs/public/channels/{slack.md → slack.mdx}

@@ -11,6 +11,17 @@ Ash Slack channels can use Vercel Connect for both outbound Slack bot tokens and
 verification. With Connect, you do not need to manage `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET`
 environment variables yourself.
 
+<CopyPrompt text="Add a Slack channel to the user's Ash project using Vercel Connect. Ash Slack channels are authored in agent/channels/slack.ts with slackChannel, and Connect can provide both outbound bot credentials and inbound webhook verification without SLACK_BOT_TOKEN or SLACK_SIGNING_SECRET env vars. Inspect existing channel files and Vercel project context, install @vercel/connect if needed, create or verify the Slack Connect client UID, attach triggers to /ash/v1/slack, add connectSlackCredentials to the Slack channel file, preserve or customize default mention, DM, delivery, typing, and HITL behavior as needed, verify the webhook route and deployment checklist, and do not commit unless the user asks.">
+  Add a Slack channel to the user's Ash project using Vercel Connect. Ash Slack channels are
+  authored in agent/channels/slack.ts with slackChannel, and Connect can provide both outbound bot
+  credentials and inbound webhook verification without SLACK_BOT_TOKEN or SLACK_SIGNING_SECRET env
+  vars. Inspect existing channel files and Vercel project context, install @vercel/connect if
+  needed, create or verify the Slack Connect client UID, attach triggers to /ash/v1/slack, add
+  connectSlackCredentials to the Slack channel file, preserve or customize default mention, DM,
+  delivery, typing, and HITL behavior as needed, verify the webhook route and deployment checklist,
+  and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Prerequisites
 
 - A Vercel project for the agent.

package/dist/docs/public/channels/{teams.md → teams.mdx}

@@ -9,6 +9,18 @@ The Teams channel accepts Bot Framework Activity POSTs from Microsoft Teams, ver
 Connector bearer JWTs, dispatches message activities to Ash, renders HITL prompts as Adaptive
 Cards, and delivers agent responses through the Bot Framework Connector REST API.
 
+<CopyPrompt text="Add Microsoft Teams support to the user's Ash project. Ash Teams channels are authored in agent/channels/teams.ts with teamsChannel, verify Bot Connector bearer JWTs, mount POST /ash/v1/teams by default, dispatch personal messages and direct bot mentions, render HITL as Adaptive Cards, and deliver replies through the Bot Framework Connector REST API. Inspect existing channels and env conventions, add the channel file, configure MICROSOFT_APP_ID, MICROSOFT_APP_PASSWORD, and optional MICROSOFT_TENANT_ID, set the Azure Bot or Teams messaging endpoint, customize onMessage or route only if needed, verify message dispatch and HITL cards, note proactive sessions require an existing conversation reference, and do not commit unless the user asks.">
+  Add Microsoft Teams support to the user's Ash project. Ash Teams channels are authored in
+  agent/channels/teams.ts with teamsChannel, verify Bot Connector bearer JWTs, mount POST
+  /ash/v1/teams by default, dispatch personal messages and direct bot mentions, render HITL as
+  Adaptive Cards, and deliver replies through the Bot Framework Connector REST API. Inspect existing
+  channels and env conventions, add the channel file, configure MICROSOFT_APP_ID,
+  MICROSOFT_APP_PASSWORD, and optional MICROSOFT_TENANT_ID, set the Azure Bot or Teams messaging
+  endpoint, customize onMessage or route only if needed, verify message dispatch and HITL cards,
+  note proactive sessions require an existing conversation reference, and do not commit unless the
+  user asks.
+</CopyPrompt>
+
 ## Add The Channel
 
 Create `agent/channels/teams.ts`:

package/dist/docs/public/channels/{telegram.md → telegram.mdx}

@@ -9,6 +9,17 @@ The Telegram channel accepts Telegram Bot API webhooks. It verifies Telegram's
 `X-Telegram-Bot-Api-Secret-Token` header before parsing the update, dispatches private messages and
 addressed group messages, and sends default replies through `sendMessage`.
 
+<CopyPrompt text="Add Telegram support to the user's Ash project. Ash Telegram channels are authored in agent/channels/telegram.ts with telegramChannel, verify the X-Telegram-Bot-Api-Secret-Token webhook header, mount POST /ash/v1/telegram by default, dispatch private messages plus addressed group messages, render HITL with inline keyboards or ForceReply, and can expose photos and documents as file parts. Inspect existing channels and env conventions, add the channel file, configure TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET_TOKEN, and botUsername, register the deployed webhook with allowed_updates, add an upload policy if attachments are needed, verify private and group dispatch, and do not commit unless the user asks.">
+  Add Telegram support to the user's Ash project. Ash Telegram channels are authored in
+  agent/channels/telegram.ts with telegramChannel, verify the X-Telegram-Bot-Api-Secret-Token
+  webhook header, mount POST /ash/v1/telegram by default, dispatch private messages plus addressed
+  group messages, render HITL with inline keyboards or ForceReply, and can expose photos and
+  documents as file parts. Inspect existing channels and env conventions, add the channel file,
+  configure TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET_TOKEN, and botUsername, register the
+  deployed webhook with allowed_updates, add an upload policy if attachments are needed, verify
+  private and group dispatch, and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Add The Channel
 
 Create `agent/channels/telegram.ts`:

package/dist/docs/public/channels/{twilio.md → twilio.mdx}

@@ -10,6 +10,17 @@ with TwiML `<Gather input="speech">`; the Twilio speech transcript is then deliv
 Ash session model as SMS. The raw continuation token is the caller/sender phone number plus the
 Twilio receiver: `From:To`.
 
+<CopyPrompt text="Add Twilio SMS and voice support to the user's Ash project. Ash Twilio channels are authored in agent/channels/twilio.ts with twilioChannel, verify X-Twilio-Signature, accept inbound SMS at /ash/v1/twilio/messages, answer voice calls at /ash/v1/twilio/voice, and deliver speech transcripts to the same session through /ash/v1/twilio/voice/transcription. Inspect existing channels and env conventions, add the channel file, configure allowFrom, TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, outbound messaging.from or messagingServiceSid, webhookUrl or publicBaseUrl when proxies are involved, customize onText or onVoice only if needed, verify SMS and voice webhooks, and do not commit unless the user asks.">
+  Add Twilio SMS and voice support to the user's Ash project. Ash Twilio channels are authored in
+  agent/channels/twilio.ts with twilioChannel, verify X-Twilio-Signature, accept inbound SMS at
+  /ash/v1/twilio/messages, answer voice calls at /ash/v1/twilio/voice, and deliver speech
+  transcripts to the same session through /ash/v1/twilio/voice/transcription. Inspect existing
+  channels and env conventions, add the channel file, configure allowFrom, TWILIO_ACCOUNT_SID,
+  TWILIO_AUTH_TOKEN, outbound messaging.from or messagingServiceSid, webhookUrl or publicBaseUrl
+  when proxies are involved, customize onText or onVoice only if needed, verify SMS and voice
+  webhooks, and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Add The Channel
 
 Create `agent/channels/twilio.ts`:

package/dist/docs/public/{connections.md → connections.mdx}

@@ -7,8 +7,20 @@ Ash exposes external MCP servers to the model through files in `connections/`. E
 connection; the connection's runtime name is derived from the filename (`agent/connections/linear.ts`
 is registered as `"linear"`).
 
-The model sees each connection through `connection_search` and picks tools based on its
-`description`, so write the description for the model.
+The model sees each connection through `connection__search` and picks tools based on its
+`description`, so write the description for the model. Discovered tools are registered as
+`connection__<connectionName>__<toolName>` (e.g. `connection__linear__list_issues`).
+
+<CopyPrompt text="Add an external MCP connection to the user's Ash project. Ash connections live under agent/connections, and the runtime connection name comes from the filename. Inspect existing connections and environment variable conventions, then add or update the right connection file with defineMcpClientConnection from experimental-ash/connections. Choose static token auth with getToken, Vercel Connect-managed OAuth, or no auth based on the service; keep credentials in environment variables or Connect, set principalType when app-vs-user auth matters, add headers, approval, or tools allow/block filters when needed, verify discovery, and do not commit unless the user asks.">
+  Add an external MCP connection to the user's Ash project. Ash connections live under
+  agent/connections, and the runtime connection name comes from the filename. Inspect existing
+  connections and environment variable conventions, then add or update the right connection file
+  with defineMcpClientConnection from experimental-ash/connections. Choose static token auth with
+  getToken, Vercel Connect-managed OAuth, or no auth based on the service; keep credentials in
+  environment variables or Connect, set principalType when app-vs-user auth matters, add headers,
+  approval, or tools allow/block filters when needed, verify discovery, and do not commit unless the
+  user asks.
+</CopyPrompt>
 
 ## Pick An Auth Strategy
 
@@ -158,7 +170,7 @@ export default defineMcpClientConnection({
 ```
 
 `never()` allows all calls, `once()` requires approval the first time per session, `always()`
-requires approval every time. See [Human In The Loop](./human-in-the-loop.md) for the approval
+requires approval every time. See [Human In The Loop](./human-in-the-loop.mdx) for the approval
 runtime.
 
 ## Tool Filters
@@ -174,10 +186,10 @@ export default defineMcpClientConnection({
 });
 ```
 
-Tools that don't pass the filter are silently excluded from `connection_search`.
+Tools that don't pass the filter are silently excluded from `connection__search`.
 
 ## What To Read Next
 
-- [Tools](./tools.md) — authored tools live alongside connection-provided tools.
-- [Human In The Loop](./human-in-the-loop.md) — interactive consent and approval runtime.
+- [Tools](./tools.mdx) — authored tools live alongside connection-provided tools.
+- [Human In The Loop](./human-in-the-loop.mdx) — interactive consent and approval runtime.
 - [Session Context](./session-context.md) — how the active principal flows through the runtime.

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

@@ -0,0 +1,16 @@
+---
+title: "Overview"
+description: "Wire your web app to an Ash agent."
+url: /frontend
+---
+
+Ash ships first-class helpers for the two most common ways to put an agent
+behind a web UI:
+
+- [Next.js](./nextjs.md) — `withAsh()` runs the Ash agent alongside your
+  Next.js app.
+- [`useAshAgent`](./use-ash-agent.md) — React hook for chat and agent UIs in any
+  React app.
+
+For other stacks, call Ash directly over its HTTP routes —
+see [Sessions And Streaming](../runs-and-streaming.md).

package/dist/docs/public/frontend/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["README", "nextjs", "use-ash-agent"]
+}

package/dist/docs/public/frontend/nextjs.md

@@ -0,0 +1,192 @@
+---
+title: "Next.js"
+description: "Add an Ash agent to a Next.js app and call it from the browser."
+---
+
+`experimental-ash/next` lets you ship a Next.js frontend and an Ash agent as
+one project. Come in from either side: drop it into an existing Next.js app
+to add an agent, or start with an agent and point a Next.js project at it.
+
+- **One dev server.** `next dev` runs the app and the agent together.
+- **One deploy.** Vercel ships them as a single project; no extra service to operate.
+- **Zero URL plumbing.** `useAshAgent()` finds the mounted routes automatically; no CORS, no env vars.
+
+## Add Ash To Next.js
+
+Wrap your Next.js config with `withAsh()`:
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+import { withAsh } from "experimental-ash/next";
+
+const nextConfig: NextConfig = {};
+
+export default withAsh(nextConfig);
+```
+
+By default, `withAsh()` looks for an `agent/` folder inside your Next.js
+project root. Pass `ashRoot` when the agent lives somewhere else:
+
+```ts
+export default withAsh(nextConfig, {
+  ashRoot: "../my-agent",
+});
+```
+
+## Add The Ash Channel
+
+Skip this section if the framework default channel works for you. `withAsh()`
+already wires Ash up without it.
+
+Create `agent/channels/ash.ts` when you want to choose the route auth policy
+explicitly:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { none } from "experimental-ash/channels/auth";
+
+export default ashChannel({
+  auth: none(),
+});
+```
+
+For protected apps, replace `none()` with a channel auth helper such as
+`vercelOidc()`, `oidc(...)`, or `httpBasic(...)`.
+
+## Use The React Hook
+
+Once `withAsh()` is in `next.config.ts`, browser code can use
+[`useAshAgent()`](./use-ash-agent.md) without a custom host:
+
+```tsx
+"use client";
+
+import { useAshAgent } from "experimental-ash/react";
+
+export function Chat() {
+  const agent = useAshAgent();
+  const isBusy = agent.status === "submitted" || agent.status === "streaming";
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const data = new FormData(event.currentTarget);
+        const message = String(data.get("message") ?? "").trim();
+        if (message.length > 0) {
+          void agent.sendMessage(message);
+        }
+      }}
+    >
+      <input name="message" disabled={isBusy} />
+      <button type="submit" disabled={isBusy}>
+        Send
+      </button>
+    </form>
+  );
+}
+```
+
+The hook handles conversation state, streaming updates, errors, and
+messages for you. See [`useAshAgent`](./use-ash-agent.md) for the full API.
+
+## Local Development
+
+`pnpm dev` is enough. `withAsh()` boots the Ash dev server alongside Next.js
+and rewrites the Ash routes to it, so your browser keeps talking to the
+Next.js origin.
+
+## Vercel Deployments
+
+On Vercel, `withAsh()` keeps the web app public and the Ash runtime tucked
+behind it. Users visit the Next.js app, and the browser talks to the agent
+through the same site origin.
+
+Use `ashBuildCommand` when the agent needs a project-specific build command:
+
+```ts
+export default withAsh(nextConfig, {
+  ashBuildCommand: "pnpm build:ash",
+});
+```
+
+## Local Production Builds
+
+When you run `next build && next start` on your own machine, `withAsh()` proxies
+Ash routes to `http://127.0.0.1:4274` and serves a built `.output/server/index.mjs`
+on that port. Set `ASH_NEXT_PRODUCTION_PORT` to use a different port:
+
+```bash
+ASH_NEXT_PRODUCTION_PORT=5000 pnpm build && pnpm start
+```
+
+## Non-Vercel Production Hosts
+
+If you deploy somewhere other than Vercel and the Ash service runs on a
+separate origin, point Next.js at it with `ASH_NEXT_PRODUCTION_ORIGIN`:
+
+```bash
+ASH_NEXT_PRODUCTION_ORIGIN=https://agent.example.com pnpm build
+```
+
+## Authenticated Requests
+
+Because the agent runs on the same origin as your Next.js app, the auth you
+already use for the rest of the app applies to it for free. Auth.js or any
+cookie-based session works without extra wiring: the browser already sends
+those cookies on every Ash request. The channel just reads them:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { getAuthJsSession } from "@/lib/auth";
+
+export default ashChannel({
+  auth: async (request) => {
+    const session = await getAuthJsSession(request);
+    if (!session) return null;
+    return {
+      attributes: {},
+      principalType: "user",
+      principalId: session.profile.sub,
+      authenticator: "authjs",
+      issuer: session.issuer,
+    };
+  },
+});
+```
+
+The `apps/nextjs-ash` example app has a full Auth.js setup.
+
+For non-cookie schemes (bearer tokens, custom headers), attach them from the
+client instead:
+
+```tsx
+const agent = useAshAgent({
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+```
+
+Prefer function values for short-lived credentials. Ash re-resolves them
+before each HTTP request, including reconnects.
+
+## Add Per-Turn Page Context
+
+`useAshAgent()` accepts a `prepareSend` callback for attaching one-turn page
+state (pathname, selected ids, anything else the model should see for the
+next call only). See [`useAshAgent`](./use-ash-agent.md#add-per-turn-client-context)
+for the full pattern.
+
+For server-side enrichment (policy, durable context, dynamic skills), use
+runtime lifecycle hooks instead. See [Hooks](../hooks.md).
+
+## What To Read Next
+
+- [`useAshAgent`](./use-ash-agent.md)
+- [Auth And Route Protection](../auth-and-route-protection.md)
+- [Hooks](../hooks.md)
+- [Sessions And Streaming](../runs-and-streaming.md)