experimental-ash 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # experimental-ash
 
+## 0.44.0
+
+### Minor Changes
+
+- ed89a1b: Generate channel instrumentation metadata typings from authored `agent/channels/*` files so `input.channel.metadata` narrows after checking `input.channel.kind` or calling `isChannel(input.channel, channel)`.
+- 5faaf2b: Add `sandbox.setNetworkPolicy(policy)` to the live sandbox handle returned by `ctx.getSandbox()`, so any tool, hook, or channel event can apply a firewall network policy at run time — for cases where the policy must change _during_ a turn (e.g. brokering a credential resolved mid-turn). Configuring a policy known at session start in the backend factory or `onSession`'s `use()` remains valid and is often preferable; both accept the same `transform` shape for credential brokering, which injects headers at the firewall so secrets authenticate egress without entering the sandbox process. The local backend rejects `setNetworkPolicy` (just-bash applies its network policy only at creation and runs no binaries to govern). The `@vercel/sandbox` and `just-bash` network-policy types are now copied verbatim from the installed packages at vendor time (instead of hand-written stubs), so the brokering surface (`match`/`transform`/`forwardURL`/matchers, and just-bash's `allowedUrlPrefixes` transforms) never drifts.
+
+## 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/bin/ash.js

@@ -18,6 +18,7 @@ function createBootstrapOptions(overrides = {}) {
       overrides.cliEntrypointPath ?? resolve(packageRoot, "dist", "src", "cli", "run.js"),
     packageRoot,
     postBuildScriptPaths: overrides.postBuildScriptPaths ?? [
+      resolve(packageRoot, "scripts", "copy-compiled-assets.mjs"),
       resolve(packageRoot, "scripts", "copy-docs.mjs"),
       resolve(packageRoot, "scripts", "stamp-version-tokens.mjs"),
     ],

package/dist/docs/internals/mechanical-invariants.md

@@ -49,6 +49,22 @@ This is enforced on three layers:
 Markdown frontmatter is treated the same way: `name:` is no longer a
 recognized field on system or skill markdown.
 
+## Release Metadata
+
+### Changeset Package Keys Match Workspace Names
+
+Changeset frontmatter must name the package exactly as it appears in that
+workspace package's `package.json`. Directory names, binary names, and
+marketing names are not valid substitutes; for example, the package under
+`packages/ash` is named `experimental-ash`.
+
+Enforcement: rule 29 in `scripts/guard-agents-rules.mjs` parses changeset
+YAML frontmatter with `gray-matter`, reads the package patterns from
+`pnpm-workspace.yaml`, resolves workspace package names from their
+`package.json` files, and fails if any `.changeset/*.md` package key does not
+match one of those names. This keeps invalid release metadata from reaching
+the post-merge `changesets/action` workflow.
+
 ## Runtime Boundaries
 
 ### Workflow APIs Stay In Runtime Code

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,145 @@ 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 { defineInstrumentation } from "experimental-ash/instrumentation";
+
+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 ?? "",
+      };
+    },
+  },
+});
+```
+
+For authored channels, TypeScript gets channel metadata types from a compiler-owned declaration
+file. When Ash compiles `agent/channels/support.ts`, it writes
+`.ash/compile/channel-instrumentation-types.d.ts` with a `ChannelMetadataMap` entry for the
+filename-derived kind and a `ChannelReferenceMap` entry for `isChannel`:
+
+```ts
+import type { InferChannelMetadata } from "experimental-ash/channels";
+
+declare module "experimental-ash/instrumentation" {
+  interface ChannelMetadataMap {
+    readonly "channel:support": InferChannelMetadata<
+      typeof import("../../agent/channels/support.js").default
+    >;
+  }
+  interface ChannelReferenceMap {
+    readonly "channel:support": typeof import("../../agent/channels/support.js").default;
+  }
+}
+```
+
+Keep `.ash/**/*.d.ts` in your app's `tsconfig.json` `include` list so TypeScript sees that file.
+Then either `input.channel.kind === "channel:support"` or `isChannel(input.channel, supportChannel)`
+narrows `input.channel.metadata` to the return type of the channel's `metadata(state)` function:
+
+```ts
+// agent/channels/support.ts
+import { defineChannel, POST } from "experimental-ash/channels";
+
+export default defineChannel({
+  state: { ticketId: null as string | null },
+  // Ash uses this function's runtime value for instrumentation metadata and
+  // makes its return type available to instrumentation.ts.
+  metadata(state) {
+    return { ticketId: state.ticketId };
+  },
+  routes: [POST("/support", async () => new Response("ok"))],
+});
+```
+
+```ts
+// agent/instrumentation.ts
+import { defineInstrumentation, isChannel } from "experimental-ash/instrumentation";
+
+import supportChannel from "./channels/support.js";
+
+export default defineInstrumentation({
+  metadata: {
+    "step.started"(input) {
+      if (!isChannel(input.channel, supportChannel)) {
+        return {};
+      }
+
+      return {
+        "support.ticket_id": input.channel.metadata.ticketId ?? "",
+      };
+    },
+  },
+});
+```
+
+Built-in wrapper return types expose their concrete metadata too. For example, a file named
+`agent/channels/support.ts` that default-exports `slackChannel()` still narrows under
+`input.channel.kind === "channel:support"` to Slack's projected metadata shape.
+
+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`. Runtime instrumentation never falls back to raw channel
+state.
+
+`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.
+
+Manual `ChannelMetadataMap` declaration merging is only the escape hatch for unusual setups where
+the generated `.ash/**/*.d.ts` file is not available to the TypeScript program, or where a channel
+is typed outside the normal `agent/channels/<name>` compile path:
+
+```ts
+import type { SlackInstrumentationMetadata } from "experimental-ash/channels/slack";
+
+declare module "experimental-ash/instrumentation" {
+  interface ChannelMetadataMap {
+    readonly "channel:support": SlackInstrumentationMetadata;
+  }
+}
+```
+
+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 +208,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
@@ -55,7 +58,7 @@ Session metadata, sandbox access, and skill access are available through the `ct
 passed to tool `execute`, hook handlers, and channel event handlers:
 
 - `ctx.session` - current session, turn, auth, and optional parent lineage
-- `ctx.getSandbox()` - live sandbox handle for the current agent
+- `ctx.getSandbox()` - live sandbox handle for the current agent; `sandbox.setNetworkPolicy(policy)` applies a firewall network policy at run time (egress control, credential brokering) without an `onSession` hook
 - `ctx.getSkill(identifier)` - handle for a named skill visible to the current agent
 - `defineState(name, initial)` - typed durable state with `get()` and `update()` (`experimental-ash/context`)
 
@@ -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)