experimental-ash 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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
+
+- edce3c9: Unified event dispatch: single `handleEvent` pipeline for all event-based handlers (channels, hooks, dynamic tools). Dynamic tool entries now require the `tool()` wrapper — the bundler transform only matches `execute` inside `tool()` calls.
+
 ## 0.41.0
 
 ### Minor Changes

package/dist/docs/internals/hooks.md

@@ -124,13 +124,35 @@ itself throws while the dispatcher is emitting the recoverable
 `session.failed` instead. This is the bounded second-order behavior
 when both a `lifecycle.turn` and a `turn.failed` event hook fail.
 
-Stream-event dispatch is `dispatchStreamEventHooks`, called from each
-runtime's `HarnessEmitFn` composer **after** the channel adapter's
-event handler runs. The dispatcher reads the typed bucket
+### Stream event dispatch (`handleEvent`)
+
+Every stream event passes through one `handleEvent` function
+(`execution/workflow-steps.ts`) that coordinates three stages:
+
+```
+handleEvent(event):
+  1. emit(event)             — channel adapter handler + durable stream write
+  2. dispatchStreamEventHooks — typed bucket, then wildcard bucket
+  3. dispatchDynamicToolEvent — resolvers subscribed to event.type
+```
+
+`emit` handles the channel adapter's event handler (can mutate
+adapter state, can transform the event) and writes the (possibly
+transformed) event to the durable stream. The durable record is
+consistent with what was written even if a downstream handler throws.
+
+`dispatchStreamEventHooks` reads the typed bucket
 (`registry.streamEventsByType.get(eventType)`) followed by the flat
-wildcard bucket (`registry.streamEventsWildcard`); thrown errors
-propagate through the emit composer. The existing harness error path
-catches them and emits the recoverable `turn.failed` cascade.
+wildcard bucket (`registry.streamEventsWildcard`). Thrown errors
+propagate through the handler; the existing harness error path catches
+them and emits the recoverable `turn.failed` cascade.
+
+`dispatchDynamicToolEvent` (`context/dynamic-tool-lifecycle.ts`) runs
+dynamic tool resolvers subscribed to the event type and merges
+resolved tools into `DynamicToolsKey`. The tool-loop reads this key
+right before each model call. See the [event dispatch
+doc](../../research/active/unified-event-dispatch.md) for the full
+design.
 
 ## `SessionPreparedKey`
 
@@ -162,11 +184,31 @@ The `discover/discover-subagent.ts` path walks each local subagent's
 | `lifecycle.turn`    | Caught by dispatcher → recoverable `turn.failed` cascade emitted                       |
 | Stream-event hooks  | Propagated through the emit composer → existing harness error path emits `turn.failed` |
 
-The contract with `HarnessEmitFn`: the wrapped emit fn calls the
-channel adapter's event handler first, writes the (possibly
-transformed) event to the durable stream, **then** fans out to authored
-stream-event hook subscribers. The durable record is consistent with
-what was written even if a downstream hook throws.
+### Full per-turn execution order
+
+```
+dispatchHookLifecycle():
+  lifecycle.session hooks        (once per session, produce modelContext)
+  lifecycle.turn hooks           (once per turn, produce modelContext)
+
+emitTurnPreamble() via handleEvent:
+  handleEvent(session.started)   → emit, hooks, dynamic tool resolvers
+  handleEvent(turn.started)      → emit, hooks, dynamic tool resolvers
+  handleEvent(message.received)  → emit, hooks
+
+emitStepStarted() via handleEvent:
+  handleEvent(step.started)      → emit, hooks, dynamic tool resolvers
+
+runOneModelCall():
+  read DynamicToolsKey           (current tools from all prior events)
+  build effective toolset        (static + dynamic + connections)
+  model.stream()
+
+emitStepActions() via handleEvent:
+  handleEvent(actions.requested) → emit, hooks, dynamic tool resolvers
+  handleEvent(action.result) × N → emit, hooks, dynamic tool resolvers
+  handleEvent(step.completed)    → emit, hooks
+```
 
 ## Testing Strategy
 

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
@@ -229,7 +215,7 @@ export default defineHook({
 The session contribution lands in `modelContext` for the **first** model
 call only. Subsequent turns proceed without it.
 
-## Stream events
+## Stream Events
 
 Side-effect-only handlers for accepted runtime events. Subscribe by
 event type, or use `*` for every event:
@@ -255,12 +241,15 @@ export default defineHook({
 });
 ```
 
-Composition:
+### Execution order
+
+When a stream event fires, three things happen in order:
+
+1. **Emit** — the channel adapter handler runs, then the event is written to the durable stream.
+2. **Hooks** — stream event hooks fire (typed handlers first, then `*` wildcard). Return values are ignored.
+3. **Dynamic tool resolvers** — resolvers subscribed to the event type run and update the tool set.
 
-- Stream-event hooks run **after** Ash has accepted the event and
-  written it to the durable stream.
-- Return values are ignored.
-- Typed event hooks run **before** `*` for the same event.
+Hooks always run **after** the event is durably recorded — if a hook throws, the stream is consistent.
 
 ## Errors
 
@@ -298,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)