experimental-ash 0.42.0 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # experimental-ash
 
+## 0.43.0
+
+### Minor Changes
+
+- 52146a5: Migrate `connection_search` from a framework tool singleton to a dynamic tool resolver. Discovered connection tools are now derived from conversation history via `ctx.messages` — no `DiscoveredConnectionToolsKey` durable state or `onCompact` hook needed. Deletes `connection-tools.ts` and the old `connection-search.ts` implementation.
+- 2469218: Unified dynamic tool API: `defineTools` and `defineTool({ events })` are replaced by `defineDynamic`, and the `tool()` entry wrapper is replaced by `defineTool`. Handlers return either a single `defineTool(...)` (named after the file slug) or a `Record<string, defineTool(...)>` (named `slug__key`). The `identity` field is removed from compiled manifests — single vs map detection is now runtime-based.
+- 192a1eb: Add dynamic instrumentation metadata via `metadata["step.started"]`, with per-attempt session, turn, step, channel, and model-input access. The channel projection exposes `kind` (`channel:<filename>` for authored channels, or `http`/`schedule`/`subagent`), also emitted as the `ash.channel.kind` span attribute. Authored metadata is parsed defensively: resolver failures, thenables, reserved `ash.*` keys, and non-string values are dropped without interrupting the model call.
+- d7de8e0: Clean up `DynamicToolResolveContext`: remove `__cache`, add `messages` for history access, add `toModelOutput` to `DynamicToolEntry`, and run the dynamic tool bundler transform on framework tools during the ash build.
+- dc0db8e: Dynamic skills can now be authored with `defineDynamic` + `defineSkill` in `agent/skills/`, matching the `defineDynamic` + `defineTool` pattern for dynamic tools. Resolvers subscribe to lifecycle events (`session.started`, `turn.started`, `step.started`) and return branded `defineSkill(...)` entries that are materialized to the sandbox. Single returns use the file slug as the skill name; map returns use `slug__key`. Hook-contributed skills via `LifecycleHookResult.skills` continue to work but are deprecated in favor of this approach.
+- 80b4c1d: Remove `LifecycleHookResult.skills` — lifecycle hooks can no longer contribute skills. Use `defineDynamic` + `defineSkill` in `agent/skills/` instead.
+
+### Patch Changes
+
+- 3df1814: Emit `$ash.*` workflow run attributes for agent run observability. Every
+  session, turn, and subagent run now tags itself with a small set of
+  reserved-namespace attributes (`$ash.type`, `$ash.parent`,
+  `$ash.root`, `$ash.subagent`, `$ash.trigger`, `$ash.title`,
+  `$ash.model`, `$ash.input_tokens`, `$ash.output_tokens`,
+  `$ash.cache_read_tokens`, `$ash.tool_count`) so the Vercel dashboard can
+  hydrate the Agent Runs view via the workflow runtime's
+  `workflow_run_attributes` table without scraping events.
+
+  Tag writes are best-effort — runtime failures are logged once per process
+  and swallowed so a broken attribute write can never break a session. No
+  public API changes; authored agent code never sees the `$ash.*` namespace.
+  See `research/active/workflow-run-attributes.md` for the full design.
+
+- 70a2d17: Authenticate Slack Enterprise Grid file downloads so agents can read private attachments served from workspace `enterprise.slack.com` hosts.
+- 08e2696: Deploy scaffolded Web Chat routes to Vercel when channel setup adds a deployable route.
+
 ## 0.42.0
 
 ### Minor Changes

package/dist/docs/public/README.md

@@ -15,24 +15,24 @@ Important naming note:
 
 Read in this order:
 
-1. [Getting Started](./getting-started.md)
+1. [Getting Started](./getting-started.mdx)
 2. [Project Layout](./advanced/project-layout.md)
 3. [`agent.ts`](./agent-ts.md)
 4. [TypeScript API](./advanced/typescript-api.md)
 5. [Context Control](./advanced/context-control.md)
 6. [Skills](./skills.md)
-7. [Tools](./tools.md)
-8. [Connections](./connections.md)
+7. [Tools](./tools.mdx)
+8. [Connections](./connections.mdx)
 9. [Workspace](./advanced/workspace.md)
 10. [Sandboxes](./sandbox.md)
 11. [Channels](./channels/README.md)
-12. [Human In The Loop](./human-in-the-loop.md)
+12. [Human In The Loop](./human-in-the-loop.mdx)
 13. [Session Context](./advanced/session-context.md)
 14. [Sessions And Streaming](./advanced/runs-and-streaming.md)
-15. [Subagents](./subagents.md)
-16. [Schedules](./schedules.md)
-17. [Evals](./advanced/evals.md)
-18. [Auth And Route Protection](./advanced/auth-and-route-protection.md)
+15. [Subagents](./subagents.mdx)
+16. [Schedules](./schedules.mdx)
+17. [Evals](./advanced/evals.mdx)
+18. [Auth And Route Protection](./advanced/auth-and-route-protection.mdx)
 19. [Vercel Deployment](./advanced/vercel-deployment.md)
 20. [CLI, Build, And Debugging](./advanced/cli-build-and-debugging.md)
 

package/dist/docs/public/advanced/{auth-and-route-protection.md → auth-and-route-protection.mdx}

@@ -16,6 +16,17 @@ These settings apply to:
 - `POST /ash/v1/session/:sessionId`
 - `GET /ash/v1/session/:sessionId/stream`
 
+<CopyPrompt text="Protect the user's Ash HTTP routes through the channel layer. In Ash, route auth and IP policy live on channel factories, usually agent/channels/ash.ts with ashChannel auth config, not in agent.ts. Inspect the existing channel file and app auth code, replace any generated exampleProductionAuth placeholder with the smallest AuthFn or helper composition, use helpers such as localDev, vercelOidc, none, httpBasic, jwtHmac, jwtEcdsa, or oidc as appropriate, keep secrets in environment variables, preserve localDev and vercelOidc behavior where useful, verify unauthenticated production browser requests are rejected with 401, and do not commit unless the user asks.">
+  Protect the user's Ash HTTP routes through the channel layer. In Ash, route auth and IP policy
+  live on channel factories, usually agent/channels/ash.ts with ashChannel auth config, not in
+  agent.ts. Inspect the existing channel file and app auth code, replace any generated
+  exampleProductionAuth placeholder with the smallest AuthFn or helper composition, use helpers such
+  as localDev, vercelOidc, none, httpBasic, jwtHmac, jwtEcdsa, or oidc as appropriate, keep secrets
+  in environment variables, preserve localDev and vercelOidc behavior where useful, verify
+  unauthenticated production browser requests are rejected with 401, and do not commit unless the
+  user asks.
+</CopyPrompt>
+
 ## Generated Web Chat Auth
 
 `pnpm create experimental-ash-agent` scaffolds `agent/channels/ash.ts` from the Web Chat example.

package/dist/docs/public/advanced/context-control.md

@@ -116,7 +116,7 @@ Subagents are a context-control tool too:
 - they can have their own tools and their own sandbox
 - they run inside their own delegated subagent context instead of extending the root agent inline
 
-See [Subagents](./subagents.md).
+See [Subagents](./subagents.mdx).
 
 ## Choosing The Right Lever
 
@@ -140,8 +140,8 @@ For most agents:
 
 ## What To Read Next
 
-- [Tools](./tools.md)
-- [Hooks](./hooks.md)
+- [Tools](./tools.mdx)
+- [Hooks](./hooks.mdx)
 - [Skills](./skills.md)
 - [Workspace](./workspace.md)
-- [Subagents](./subagents.md)
+- [Subagents](./subagents.mdx)

package/dist/docs/public/advanced/{evals.md → evals.mdx}

@@ -13,6 +13,16 @@ Use evals when you want to:
 - compare output against expected text, JSON, SQL, or session behavior
 - export results to Braintrust for review and comparison
 
+<CopyPrompt text="Add repeatable Ash evals to the user's project. Ash eval suites live under the app root evals directory, use .eval.ts files, and export defineEvalSuite from experimental-ash/evals; suite identity is derived from the file path, not an authored id or name. Inspect existing evals and agent behavior, create a focused smoke suite with model, cases or load, and scores, prefer cheap scorers such as Run.didNotFail, Run.usedTool, Text.includes, Json.deepEqual, or Sql.exactNormalized before LLM judges, add fixture loading only if it helps, run ash eval with the relevant suite flags, and do not commit unless the user asks.">
+  Add repeatable Ash evals to the user's project. Ash eval suites live under the app root evals
+  directory, use .eval.ts files, and export defineEvalSuite from experimental-ash/evals; suite
+  identity is derived from the file path, not an authored id or name. Inspect existing evals and
+  agent behavior, create a focused smoke suite with model, cases or load, and scores, prefer cheap
+  scorers such as Run.didNotFail, Run.usedTool, Text.includes, Json.deepEqual, or
+  Sql.exactNormalized before LLM judges, add fixture loading only if it helps, run ash eval with the
+  relevant suite flags, and do not commit unless the user asks.
+</CopyPrompt>
+
 ## Where Evals Live
 
 Ash discovers eval suites under the app root `evals/` directory.
@@ -276,5 +286,5 @@ For most apps:
 ## What To Read Next
 
 - [TypeScript API](./typescript-api.md)
-- [Tools](./tools.md)
+- [Tools](./tools.mdx)
 - [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/advanced/{hooks.md → hooks.mdx}

@@ -7,10 +7,24 @@ url: /hooks
 Hooks are Ash's authored extension points for the per-turn lifecycle and
 the runtime event stream.
 
+This page is about `agent/hooks/*.ts` runtime hooks. For the React client hook,
+see [`useAshAgent`](../frontend/use-ash-agent.md).
+
 Use a hook when you want to run code **around** a turn (before the model
 runs, around stream events) without writing a tool, a context provider,
 or a channel adapter handler.
 
+<CopyPrompt text="Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from experimental-ash/hooks, and can subscribe to lifecycle.session, lifecycle.turn, or stream events. Use lifecycle hooks when the model needs ephemeral modelContext before the next model call; use events handlers for observe-only side effects after events are durably recorded. Inspect existing hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only when durable shared state is needed, wrap best-effort side effects so they do not fail sessions accidentally, verify the relevant lifecycle or stream event behavior, and do not commit unless the user asks.">
+  Add an Ash hook to the user's project. Ash hooks live under agent/hooks, use defineHook from
+  experimental-ash/hooks, and can subscribe to lifecycle.session, lifecycle.turn, or stream events.
+  Use lifecycle hooks when the model needs ephemeral modelContext before the next model call; use
+  events handlers for observe-only side effects after events are durably recorded. Inspect existing
+  hooks and agent/lib, choose the smallest hook file and path-derived slug, use defineState only
+  when durable shared state is needed, wrap best-effort side effects so they do not fail sessions
+  accidentally, verify the relevant lifecycle or stream event behavior, and do not commit unless the
+  user asks.
+</CopyPrompt>
+
 ## The Main API
 
 `agent/hooks/audit.ts`
@@ -103,7 +117,7 @@ Lifecycle hooks share one signature:
 ```ts
 type LifecycleHook = (
   ctx: HookContext,
-) => void | { modelContext?: readonly ModelMessage[]; skills?: readonly NamedSkillDefinition[] } | Promise<…>;
+) => void | { modelContext?: readonly ModelMessage[] } | Promise<…>;
 ```
 
 Session and turn metadata are available on `ctx.session`. For example,
@@ -113,14 +127,16 @@ Session and turn metadata are available on `ctx.session`. For example,
 model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
 continuations and HITL resumes do not re-fire it.
 
-Both keys may return `{ modelContext, skills }`. `modelContext`
-contributions are concatenated session-then-turn before the harness's
-next model call, and are never written to durable history. Dynamic
-`skills` are written into `/workspace/skills/<name>/` and announced
-through durable system history so the next model call can activate them
-with `load_skill`. Channels may also contribute the same `modelContext`
-shape through `SendPayload`; channel-provided messages appear before
-lifecycle hook messages.
+Both keys may return `{ modelContext }`. `modelContext` contributions
+are concatenated session-then-turn before the harness's next model
+call, and are never written to durable history. Channels may also
+contribute the same `modelContext` shape through `SendPayload`;
+channel-provided messages appear before lifecycle hook messages.
+
+Browser UIs can contribute one-turn page state through `useAshAgent()`
+`prepareSend` and `clientContext`. That client context is merged before
+runtime lifecycle hook context, so use it for page state and use runtime hooks
+for server-side policy and durable context.
 
 ### Seed durable context
 
@@ -174,36 +190,6 @@ export default defineHook({
 `modelContext` messages are appended in registry order and visible to
 the next model call only — never persisted.
 
-### Contribute dynamic skills
-
-```ts
-// agent/hooks/tenant-skills.ts
-import { defineHook } from "experimental-ash/hooks";
-
-export default defineHook({
-  lifecycle: {
-    async session(ctx) {
-      return {
-        skills: [
-          {
-            name: "tenant-policy",
-            description: "Apply tenant-specific policy before answering.",
-            markdown: "Read the policy reference before making a recommendation.",
-            files: {
-              "references/policy.md": "Policy body\n",
-            },
-          },
-        ],
-      };
-    },
-  },
-});
-```
-
-Dynamic skills may be returned from `lifecycle.session` or
-`lifecycle.turn`. They can update earlier dynamic skills with the same
-name, but cannot replace authored skills discovered under `agent/skills/`.
-
 ### Once-per-session text
 
 ```ts
@@ -301,7 +287,9 @@ when both are registered.
 
 ## What to read next
 
-- [Tools](./tools.md)
+- [`useAshAgent`](../frontend/use-ash-agent.md)
+- [Next.js](../frontend/nextjs.md)
+- [Tools](./tools.mdx)
 - [Context Control](./context-control.md)
 - [Sessions And Streaming](./runs-and-streaming.md)
 - [Session Context](./session-context.md)

package/dist/docs/public/advanced/instrumentation.md

@@ -52,7 +52,95 @@ These fields control what the AI SDK records inside OTel spans:
 - `recordOutputs` -- record model outputs on spans (defaults to `true`). Set to `false` to disable
   output recording.
 - `functionId` -- override the function name on spans (defaults to the agent name)
-- `metadata` -- additional key-value pairs added to every span
+- `metadata["step.started"]` -- a synchronous callback that returns key-value pairs for one
+  model-call attempt
+
+## Metadata
+
+Use `metadata["step.started"]` when the metadata depends on the current session, turn, step,
+channel, or model input:
+
+```ts
+import type { SlackInstrumentationMetadata } from "experimental-ash/channels/slack";
+
+// A Slack-backed channel authored at `agent/channels/support.ts` has kind
+// `channel:support` (its filename).
+declare module "experimental-ash/instrumentation" {
+  interface ChannelMetadataMap {
+    readonly "channel:support": SlackInstrumentationMetadata;
+  }
+}
+
+export default defineInstrumentation({
+  metadata: {
+    "step.started"(input) {
+      if (input.channel.kind !== "channel:support") {
+        return {};
+      }
+
+      return {
+        "slack.channel_id": input.channel.metadata.channelId ?? "",
+        "slack.user_id": input.channel.metadata.triggeringUserId ?? "",
+      };
+    },
+  },
+});
+```
+
+The callback runs after Ash has assembled the model input for the attempt and before constructing
+the AI SDK call. That timing lets the returned values attach to the AI SDK model-call span and its
+child spans. It runs for each model-call attempt, including a retry of the same logical step when
+Ash changes provider settings or instructions.
+
+The callback receives:
+
+- `session` -- the session id, current/initiator auth, and parent session lineage when this is a
+  child run
+- `turn` -- the stream turn id and sequence, e.g. `turn_0`
+- `step` -- the zero-based step index inside the turn
+- `channel` -- the channel's `kind` and the metadata projected by the active channel
+- `modelInput` -- the final instructions and messages passed to the model call
+
+A channel exposes its identity through `kind`: the discriminant you narrow on. For authored
+channels it is `channel:<name>`, where `<name>` is the channel's filename under
+`agent/channels/` — `agent/channels/support.ts` is `channel:support`. Framework channels use
+`http`, `schedule`, or `subagent`. It is also emitted as the `ash.channel.kind` span attribute.
+
+Channel metadata is channel-owned. Built-in channels expose only the fields they choose to make
+observable; for example, Slack projects `channelId`, `teamId`, `threadTs`, and `triggeringUserId`
+from its durable channel state. User-authored channels expose their own projection by returning
+`metadata(state)` from `defineChannel`. To make TypeScript narrow `input.channel.metadata`,
+declaration-merge the same `channel:<name>` kind into `ChannelMetadataMap`:
+
+`metadata(state)` must return an object composed of JSON primitives, arrays, and plain objects.
+Ash omits `undefined` object properties and drops projections containing values such as `Date` or
+`Map` with a warning.
+
+```ts
+import { defineChannel } from "experimental-ash/channels";
+
+declare module "experimental-ash/instrumentation" {
+  interface ChannelMetadataMap {
+    readonly "channel:support": {
+      readonly triggeringUserId: string | null;
+    };
+  }
+}
+
+export default defineChannel({
+  state: { triggeringUserId: null as string | null },
+  metadata(state) {
+    return { triggeringUserId: state.triggeringUserId };
+  },
+  routes: [],
+});
+```
+
+Metadata failures are non-destructive. If the callback throws, returns a non-record, or returns
+non-string values, Ash logs a warning, drops the invalid metadata, and continues the model call.
+Thenables are rejected; the callback is intentionally synchronous. Keys beginning with `ash.` are
+reserved, so authored metadata cannot override framework metadata. Instrumentation projections
+containing values outside the JSON shape, such as `Date` or `Map`, are dropped with a warning.
 
 ## Trace Hierarchy
 
@@ -70,8 +158,9 @@ ash.turn  {ash.session.id, ash.turn.id}
 ```
 
 Ash creates the `ash.turn` parent span per turn and passes enriched telemetry to the AI SDK so model
-calls and tool executions are traced automatically. Session context (`ash.version`, `ash.session.id`,
-`ash.continuation_token`, `ash.environment`) is injected into span metadata.
+calls and tool executions are traced automatically. Session, turn, step, and channel context
+(`ash.version`, `ash.session.id`, `ash.environment`, `ash.turn.id`, `ash.turn.sequence`,
+`ash.step.index`, `ash.channel.kind`) is injected into span metadata.
 
 ## What To Read Next
 

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

@@ -39,7 +39,7 @@ my-agent/
 | `instrumentation.ts`                   | Telemetry config                                                                                                                                                                                                                       | OTel exporter setup and AI SDK span settings; auto-discovered and run before agent code                                                                                                                                                         |
 | `channels/`                            | HTTP or messaging entrypoints                                                                                                                                                                                                          | Root-only today                                                                                                                                                                                                                                 |
 | `connections/`                         | External service connections (MCP)                                                                                                                                                                                                     | Each file defines one connection; name derived from filename                                                                                                                                                                                    |
-| `hooks/`                               | Lifecycle and stream-event subscribers                                                                                                                                                                                                 | Module-backed only. Recursive directories supported. See [Hooks](./hooks.md).                                                                                                                                                                   |
+| `hooks/`                               | Lifecycle and stream-event subscribers                                                                                                                                                                                                 | Module-backed only. Recursive directories supported. See [Hooks](./hooks.mdx).                                                                                                                                                                  |
 | `skills/`                              | On-demand procedures and capability packs                                                                                                                                                                                              | Flat markdown, module-backed skills, or packaged skills                                                                                                                                                                                         |
 | `lib/`                                 | Shared authored helper code                                                                                                                                                                                                            | Import-only source, not mounted into the workspace                                                                                                                                                                                              |
 | `sandbox/` or `sandbox.ts`             | The agent's single sandbox. Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + optional `sandbox/workspace/**` when you also want seeded files. Framework default applies when neither is authored. | Supported on the root agent and local subagents                                                                                                                                                                                                 |
@@ -156,15 +156,15 @@ Use:
 - `channels/` for HTTP or messaging ingress and delivery
 - `lib/` for shared helper modules imported by the slots above
 
-See [Connections](./connections.md) for the connection authorization shape, including the
+See [Connections](./connections.mdx) for the connection authorization shape, including the
 `@vercel/connect/ash` helper for OAuth-backed connections.
 
 ## What To Read Next
 
 - [`agent.ts`](./agent-ts.md)
 - [Context Control](./context-control.md)
-- [Connections](./connections.md)
-- [Hooks](./hooks.md)
+- [Connections](./connections.mdx)
+- [Hooks](./hooks.mdx)
 - [Skills](./skills.md)
-- [Tools](./tools.md)
+- [Tools](./tools.mdx)
 - [Channels](./channels/README.md)

package/dist/docs/public/advanced/runs-and-streaming.md

@@ -13,6 +13,10 @@ The key client model is:
 - `POST /ash/v1/session/:sessionId` sends a follow-up message
 - `GET /ash/v1/session/:sessionId/stream` lets you watch the session in real time
 
+React apps can use [`useAshAgent()`](../frontend/use-ash-agent.md) instead of calling these
+routes directly. Next.js apps can use [`withAsh()`](../frontend/nextjs.md) to proxy these
+routes to the Ash runtime from the same origin.
+
 Ash keeps those separate on purpose:
 
 - channels own `continuationToken` as the resume handle
@@ -109,6 +113,8 @@ Important behavior:
 
 ## What To Read Next
 
+- [`useAshAgent`](../frontend/use-ash-agent.md)
+- [Next.js](../frontend/nextjs.md)
 - [Session Context](./session-context.md)
-- [Subagents](./subagents.md)
-- [Schedules](./schedules.md)
+- [Subagents](./subagents.mdx)
+- [Schedules](./schedules.mdx)

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

@@ -205,5 +205,5 @@ the public accessors.
 ## What To Read Next
 
 - [Sessions And Streaming](./runs-and-streaming.md)
-- [Subagents](./subagents.md)
+- [Subagents](./subagents.mdx)
 - [Skills](./skills.md)

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

@@ -14,6 +14,9 @@ Source of truth:
 - tools subpath: [`../../packages/ash/src/public/tools/index.ts`](../../packages/ash/src/public/tools/index.ts)
 - sandbox subpath: [`../../packages/ash/src/public/sandbox/index.ts`](../../packages/ash/src/public/sandbox/index.ts)
 - channel subpaths: [`../../packages/ash/src/public/channels/index.ts`](../../packages/ash/src/public/channels/index.ts)
+- Next.js subpath: [`../../packages/ash/src/public/next/index.ts`](../../packages/ash/src/public/next/index.ts)
+- React subpath: [`../../packages/ash/src/react/index.ts`](../../packages/ash/src/react/index.ts)
+- client subpath: [`../../packages/ash/src/client/index.ts`](../../packages/ash/src/client/index.ts)
 - evals subpath: [`../../packages/ash/src/evals/index.ts`](../../packages/ash/src/evals/index.ts)
 
 ## Definition Helpers
@@ -69,6 +72,26 @@ Related exported types by subpath:
 Ash also exports lower-level runtime primitives such as `createToolLoopHarness(...)`
 and `createWorkflowRuntime(...)`.
 
+Next.js helpers exported from `experimental-ash/next`:
+
+- `withAsh(config, options?)` - wraps a Next.js config so same-origin Ash protocol routes proxy to an Ash service
+- `ASH_NEXT_SERVICE_PREFIX` - default private Vercel service prefix for the Ash service
+- `WithAshOptions` - options for `ashRoot`, `ashBuildCommand`, `configureVercelJson`, and `servicePrefix`
+
+React helpers exported from `experimental-ash/react`:
+
+- `useAshAgent(options?)` - React hook for sending turns, streaming events, projecting UI state, and tracking a session cursor
+- `defaultMessageReducer()` - default chat-style event projection used by `useAshAgent()`
+- `UseAshAgentOptions`, `UseAshAgentHelpers`, `UseAshAgentSnapshot`, `UseAshAgentStatus` - hook configuration and state types
+- `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - default message projection types
+
+Client helpers exported from `experimental-ash/client`:
+
+- `Client` - HTTP client for an Ash server
+- `ClientSession` - one durable session cursor with `send(...)`, `sendMessage(...)`, and stream helpers
+- `defaultMessageReducer()` - reducer shared with the React package
+- `SessionState`, `SendTurnInput`, `SendMessageOptions`, `ClientOptions` - client request and session types
+
 Channel and Slack types exported from `experimental-ash/channels/slack`:
 
 - `slackChannel` - Slack channel factory; zero-config by default, accepts a `SlackChannelConfig`
@@ -231,7 +254,7 @@ import {
 } from "experimental-ash/tools/defaults";
 ```
 
-See [Tools](./tools.md) for the full override patterns.
+See [Tools](./tools.mdx) for the full override patterns.
 
 ### Runtime Mode
 
@@ -239,6 +262,24 @@ See [Tools](./tools.md) for the full override patterns.
 import type { RunMode } from "experimental-ash";
 ```
 
+### Next.js Integration
+
+```ts
+import { withAsh } from "experimental-ash/next";
+```
+
+### React Client
+
+```ts
+import { useAshAgent } from "experimental-ash/react";
+```
+
+### HTTP Client
+
+```ts
+import { Client } from "experimental-ash/client";
+```
+
 ### Eval Suite
 
 ```ts
@@ -252,14 +293,16 @@ import { Braintrust } from "experimental-ash/evals/reporters";
 
 - `defineAgent` -> [`agent.ts`](./agent-ts.md)
 - `defineChannel` and channel factories -> [Channels](./channels/README.md)
-- `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, `defineWriteFileTool`, and `experimental-ash/tools/defaults` -> [Tools](./tools.md)
-- `defineHook`, `HookContext`, and lifecycle/event types -> [Hooks](./hooks.md)
+- `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, `defineWriteFileTool`, and `experimental-ash/tools/defaults` -> [Tools](./tools.mdx)
+- `defineHook`, `HookContext`, and lifecycle/event types -> [Hooks](./hooks.mdx)
 - `defineSandbox` and `ctx.getSandbox()` -> [Sandboxes](./sandbox.md)
 - `defineSkill` and `ctx.getSkill()` -> [Skills](./skills.md)
 - `ctx.session` -> [Session Context](./session-context.md)
-- subagents (authored with `defineAgent` under `subagents/<id>/agent.ts`) -> [Subagents](./subagents.md)
-- `defineSchedule` -> [Schedules](./schedules.md)
-- `defineEvalSuite`, loaders, reporters, and scorers -> [Evals](./evals.md)
+- `withAsh` -> [Next.js](../frontend/nextjs.md)
+- `useAshAgent` -> [`useAshAgent`](../frontend/use-ash-agent.md)
+- subagents (authored with `defineAgent` under `subagents/<id>/agent.ts`) -> [Subagents](./subagents.mdx)
+- `defineSchedule` -> [Schedules](./schedules.mdx)
+- `defineEvalSuite`, loaders, reporters, and scorers -> [Evals](./evals.mdx)
 
 ## Practical Advice
 

package/dist/docs/public/advanced/vercel-deployment.md

@@ -106,4 +106,4 @@ This is useful for smoke tests against preview or production environments.
 
 - [Workspace](./workspace.md)
 - [Sandboxes](./sandbox.md)
-- [Auth And Route Protection](./auth-and-route-protection.md)
+- [Auth And Route Protection](./auth-and-route-protection.mdx)

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`: