experimental-ash 0.3.0-alpha.36 → 0.3.0-alpha.38

package/{docs → dist/docs}/internals/compiler-and-artifacts.md

@@ -31,7 +31,7 @@ Discovery avoids executing authored code. The module map is the handoff — it s
 
 ## Key Artifacts
 
-**`compiled-agent-manifest.json`** — the normalized runtime-facing manifest. Preserves config, prompt, skill, sandbox, schedule, and tool metadata; flattened subagent nodes with explicit `subagentEdges`; manifest kind and version. `sandboxes` and `sandboxWorkspaces` arrays are always size 0 or 1 (single-sandbox model).
+**`compiled-agent-manifest.json`** — the normalized runtime-facing manifest. Preserves config, prompt, skill, sandbox, schedule, and tool metadata; flattened subagent nodes with explicit `subagentEdges`; manifest kind and version. `sandbox` is `null` or one entry, and `sandboxWorkspaces` is an array of size 0 or 1 (single-sandbox model).
 
 **`compile-metadata.json`** — artifact paths, SHA-256 digests, diagnostics summary, compile status, generator version, and `sourceGraphHash`. The `sourceGraphHash` drives sandbox template cache invalidation — runtime and Vercel build-time prewarm both derive template keys from it.
 

package/{docs → dist/docs}/internals/message-runtime.md

@@ -35,7 +35,6 @@ session.started → turn.started → step.started →
   message.appended / reasoning.appended →
   actions.requested → action.result →
   subagent.called / subagent.completed →
-  sandbox.initialized / sandbox.restored / sandbox.command →
 step.completed → turn.completed → session.waiting / session.completed
 ```
 

package/{docs → dist/docs}/public/README.md

@@ -24,7 +24,7 @@ Read in this order:
 7. [tools.md](./tools.md)
 8. [connections.md](./connections.md)
 9. [workspace.md](./workspace.md)
-10. [sandboxes.md](./sandboxes.md)
+10. [sandbox.md](./sandbox.md)
 11. [channels/README.md](./channels/README.md)
 12. [human-in-the-loop.md](./human-in-the-loop.md)
 13. [session-context.md](./session-context.md)

package/{docs → dist/docs}/public/agent-ts.md

@@ -123,7 +123,7 @@ server output instead of being bundled.
 - `model` optionally overrides the model used for compaction summaries
 
 The shared per-run workspace is configured on the sandbox, not on `agent.ts`. See
-[`workspace.md`](./workspace.md) and [`sandboxes.md`](./sandboxes.md).
+[`workspace.md`](./workspace.md) and [`sandbox.md`](./sandbox.md).
 
 ## `humanInTheLoop`
 

package/{docs → dist/docs}/public/channels/README.md

@@ -84,6 +84,8 @@ export default httpRoute({
 ## Slack And Other Authored Channels
 
 Authored channels can wrap those helpers or build custom transport flows with `defineRoute(...)`.
+For a Slack app backed by Vercel Connex, start with
+[`./slack.md`](./slack.md) to create the Connex client and channel file.
 
 Use a custom adapter when you want:
 
@@ -200,6 +202,7 @@ See [`./attachments.md`](./attachments.md) for the authoring guide.
 
 ## What To Read Next
 
+- [`./slack.md`](./slack.md)
 - [`./attachments.md`](./attachments.md)
 - [`../project-layout.md`](../project-layout.md)
 - [`../typescript-api.md`](../typescript-api.md)

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

@@ -0,0 +1,142 @@
+---
+title: "Slack channel setup"
+description: "Create a Slack-backed Ash channel with Vercel Connex."
+type: integration
+related:
+  - /channels
+  - /connections
+---
+
+Ash Slack channels can use Vercel Connex for both outbound Slack bot tokens and inbound webhook
+verification. With Connex, you do not need to manage `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET`
+environment variables yourself.
+
+## Prerequisites
+
+- A Vercel project for the agent.
+- A Slack workspace where you can install the app.
+- Access to Vercel Connex for your team.
+
+For local development, link the project and pull Vercel OIDC env vars so Connex can authenticate to
+the Vercel API:
+
+```bash
+vercel link
+vercel env pull
+```
+
+## Create The Connex Client
+
+Create a Slack Connex client, then copy its UID. The UID is the value you pass to Ash, for example
+`slack/my-agent`.
+
+### Dashboard Path
+
+Open [Connex in the Vercel dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connex&title=Go+to+Connex),
+then:
+
+1. Choose **Create Client**.
+2. Choose **Slack**.
+3. Choose **Install and Configure Client**.
+4. Complete the Slack installation flow.
+5. Choose **Continue**.
+6. Copy the UID, for example `slack/test`.
+
+### CLI Or Agent-Assisted Path
+
+The `vercel connex` command is currently gated for allow-listed teams. If the command is missing,
+update the Vercel CLI and enable the Connex flag in the terminal session where you will run the
+commands:
+
+```bash
+pnpm i -g vercel@latest
+export FF_CONNEX_ENABLED=1
+vercel connex --help
+```
+
+The flag only applies to the current shell session. Export it again in new terminals, or add it to
+your shell config while you are working with Connex.
+
+Make sure the CLI is authenticated and scoped to the Vercel team that has Connex access:
+
+```bash
+vercel login
+vercel switch
+vercel link
+```
+
+If you are using an AI coding agent, install the Connex skill first:
+
+```bash
+npx skills add https://github.com/vercel/connex --skill vercel-connex
+```
+
+Then create the Slack client from the project or agent folder that will use it:
+
+```bash
+vercel connex create slack
+```
+
+Run Connex commands from the directory containing the agent's `package.json` or `vercel.json`.
+Connex uses that project context to configure project access, webhooks, and triggers. The command may
+open a browser for Slack installation or OAuth consent; finish that flow before continuing.
+
+You can list existing clients with:
+
+```bash
+vercel connex list
+```
+
+## Install Connex
+
+Add the Connex SDK to the Ash project:
+
+```bash
+pnpm add @vercel/connex
+```
+
+## Add The Slack Channel File
+
+Create `agent/channels/slack.ts`:
+
+```ts
+import { slackChannelCredentials } from "@vercel/connex/ash";
+import { slackRoute } from "experimental-ash/channels/slack";
+
+export default slackRoute({
+  credentials: slackChannelCredentials("slack/my-agent"),
+});
+```
+
+Replace `slack/my-agent` with the UID from the Connex client.
+
+The helper returns a complete Slack credentials object:
+
+- `botToken` resolves an app-scoped Slack token through Connex for outbound posts.
+- `webhookVerifier` verifies Connex-forwarded Slack webhooks with Vercel OIDC.
+
+That means token rotation, refresh, multi-workspace tenancy, and inbound request verification stay in
+Connex instead of in your app environment.
+
+## Customize Delivery
+
+If you need custom Slack rendering or interaction handling, keep the same credentials and add an
+adapter:
+
+```ts
+import { slackChannelCredentials } from "@vercel/connex/ash";
+import { defineSlackAdapter, slackRoute } from "experimental-ash/channels/slack";
+
+const adapter = defineSlackAdapter({
+  "turn.started": async (_data, ctx) => {
+    await ctx.thread.post({ markdown: "Working on it..." });
+  },
+});
+
+export default slackRoute({
+  credentials: slackChannelCredentials("slack/my-agent"),
+  adapter,
+});
+```
+
+See [Channels](/docs/channels) for the full Slack adapter surface.

package/{docs → dist/docs}/public/context-control.md

@@ -97,7 +97,7 @@ Today that mainly means:
 - skill files are available under the active runtime workspace root
 - the model can inspect them with the shared `bash` tool
 
-See [`workspace.md`](./workspace.md) and [`sandboxes.md`](./sandboxes.md).
+See [`workspace.md`](./workspace.md) and [`sandbox.md`](./sandbox.md).
 
 ## 5. Delegate To A Specialist With A Subagent
 

package/{docs → dist/docs}/public/meta.json

@@ -9,7 +9,7 @@
     "tools",
     "hooks",
     "human-in-the-loop",
-    "sandboxes",
+    "sandbox",
     "channels",
     "auth-and-route-protection",
     "subagents",

package/{docs → dist/docs}/public/project-layout.md

@@ -32,21 +32,21 @@ my-agent/
 
 ## Slot Guide
 
-| Path                       | Purpose                                                                                                                                                                                     | Notes                                                                                                                              |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `system.md` or `system.ts` | Base system prompt                                                                                                                                                                          | Exactly one system prompt is expected                                                                                              |
-| `system/`                  | Additive always-on prompt layers                                                                                                                                                            | Loaded in deterministic path order. Module-backed layers are evaluated when a new session starts and then frozen for that session. |
-| `agent.ts`                 | Runtime config                                                                                                                                                                              | Model, name, metadata, workspace, build, compaction                                                                                |
-| `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.md`](./hooks.md).                                                 |
-| `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/`                 | The agent's single sandbox. Optional `sandbox/sandbox.ts` for lifecycle overrides and optional `sandbox/workspace/**` for seeded files. Framework default applies when neither is authored. | Supported on the root agent and local subagents                                                                                    |
-| `tools/`                   | Typed executable integrations                                                                                                                                                               | Module-backed only                                                                                                                 |
-| `schedules/`               | Recurring jobs; each schedule is a directory with `schedule.ts` + `prompt.md`                                                                                                               | Root-only today                                                                                                                    |
-| `subagents/`               | Specialist child agents                                                                                                                                                                     | Each child is its own local package                                                                                                |
+| Path                       | Purpose                                                                                                                                                                                                                                | Notes                                                                                                                              |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `system.md` or `system.ts` | Base system prompt                                                                                                                                                                                                                     | Exactly one system prompt is expected                                                                                              |
+| `system/`                  | Additive always-on prompt layers                                                                                                                                                                                                       | Loaded in deterministic path order. Module-backed layers are evaluated when a new session starts and then frozen for that session. |
+| `agent.ts`                 | Runtime config                                                                                                                                                                                                                         | Model, name, metadata, workspace, build, compaction                                                                                |
+| `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.md`](./hooks.md).                                                 |
+| `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                                                                                    |
+| `tools/`                   | Typed executable integrations                                                                                                                                                                                                          | Module-backed only                                                                                                                 |
+| `schedules/`               | Recurring jobs; each schedule is a directory with `schedule.ts` + `prompt.md`                                                                                                                                                          | Root-only today                                                                                                                    |
+| `subagents/`               | Specialist child agents                                                                                                                                                                                                                | Each child is its own local package                                                                                                |
 
 ## Root Agent Example
 
@@ -137,7 +137,7 @@ the sandbox workspace today:
 - skill files under `skills/` are seeded into `/workspace/skills/...`
 - files under `agent/sandbox/workspace/` are mirrored into `/workspace/...` at session bootstrap
 
-See [`sandboxes.md`](./sandboxes.md#seeding-workspace-files) for the convention.
+See [`sandbox.md`](./sandbox.md#seeding-workspace-files) for the convention.
 
 Important boundary:
 

package/{docs → dist/docs}/public/runs-and-streaming.md

@@ -40,9 +40,6 @@ Common stream events:
 - `turn.started`
 - `message.received`
 - `step.started`
-- `sandbox.initialized`
-- `sandbox.restored`
-- `sandbox.command`
 - `actions.requested`
 - `action.result`
 - `subagent.called`
@@ -98,7 +95,7 @@ Ash uses three nested concepts:
 - `turn`: one user-visible roundtrip inside that session
 - `step`: one model call inside that turn
 
-That is why tools, sandboxes, and subagents feel synchronous from authored code even though the
+That is why tools, the sandbox, and subagents feel synchronous from authored code even though the
 overall session remains durable.
 
 Important behavior:

package/{docs/public/sandboxes.md → dist/docs/public/sandbox.md}

@@ -21,36 +21,48 @@ If you never author a sandbox override, the framework default is what you get.
 
 ## Overriding The Sandbox
 
-To customize the sandbox — to add backend options, bootstrap commands, or per-session setup —
-create `agent/sandbox/sandbox.ts` and spread `defaultSandbox`:
+To customize the sandbox — to add bootstrap commands or per-session setup —
+author a sandbox definition module:
 
 ```ts
-// agent/sandbox/sandbox.ts
-import { defineSandbox } from "experimental-ash/sandboxes";
-import { defaultSandbox } from "experimental-ash/sandboxes/defaults";
+// agent/sandbox.ts
+import { defineSandbox } from "experimental-ash/sandbox";
 
 export default defineSandbox({
-  ...defaultSandbox,
-  async bootstrap({ sandbox }) {
+  async bootstrap({ use }) {
+    const sandbox = await use();
     await sandbox.runCommand("apt-get install -y jq");
   },
 });
 ```
 
+You don't need to spread anything: when `backend` is omitted, the runtime substitutes
+`defaultBackend()` automatically (see [Backend Selection](#backend-selection) below).
+
+Two layouts are supported. Pick whichever matches what you need:
+
+- `agent/sandbox.ts` — top-level shorthand. Use this when you only need a definition module and
+  no seeded workspace files. The shorthand cannot carry a `workspace/` folder.
+- `agent/sandbox/sandbox.ts` — folder layout. Use this when you also want to seed
+  `agent/sandbox/workspace/**` into the live sandbox cwd at session bootstrap.
+
+When both are present, the folder layout wins and the top-level shorthand is ignored.
+
 The public lifecycle surface is intentionally small:
 
-- `bootstrap` — template-scoped setup (runs once when the template is built)
-- `onSession` — durable-session-scoped setup (runs once per session)
+- `bootstrap({ use })` — template-scoped setup (runs once when the template is built). Call `use()`
+  to get a `SandboxSession` for filesystem setup. Only filesystem state survives snapshotting.
+- `onSession({ use })` — durable-session-scoped setup (runs once per session). Call `use(opts?)` to
+  get the backend-specific sandbox (e.g. `VercelSandbox`) with session-level configuration applied.
 - `sandbox.resolvePath(path)` — translate a logical `/workspace/...` path into the live filesystem
 - `sandbox.runCommand(command)` — run a shell command inside the sandbox
 
-`defineSandbox` and `defaultSandbox` live on `experimental-ash/sandboxes` and
-`experimental-ash/sandboxes/defaults`.
+`defineSandbox` lives on `experimental-ash/sandbox`.
 
 ## Seeding Workspace Files
 
-You can mount a folder of authored files into the sandbox filesystem at session bootstrap by
-putting them under `agent/sandbox/workspace/`:
+Seeding workspace files requires the folder layout. You can mount a folder of authored files into
+the sandbox filesystem at session bootstrap by putting them under `agent/sandbox/workspace/`:
 
 ```text
 agent/sandbox/
@@ -67,7 +79,8 @@ Rules:
 - The workspace folder is optional. An empty or missing `workspace/` is identical to today — no
   mounts.
 - `sandbox.ts` is also optional. You can author _just_ a `workspace/` folder and the framework
-  default definition still applies.
+  default definition still applies. (To author only a definition without seeded files, prefer the
+  top-level `agent/sandbox.ts` shorthand instead.)
 - The workspace prompt section advertises the top-level entries to the model automatically.
 
 ### Reserved `skills/` Subtree
@@ -93,7 +106,7 @@ export default defineBashTool({
 
 These share the executor core, input schema, and result shape of the framework `bash`, `read_file`,
 and `write_file` tools. The runtime name comes from the file stem (here, `repo_shell`). There is no
-`sandboxes` option on these factories — every tool runs in the single sandbox.
+`sandbox` option on these factories — every tool runs in the single sandbox.
 
 ## Using The Sandbox From Authored Code
 
@@ -101,7 +114,7 @@ Any authored runtime function (tool, step, or model callback) can bind a live sa
 `getSandbox()`:
 
 ```ts
-import { getSandbox } from "experimental-ash/sandboxes";
+import { getSandbox } from "experimental-ash/sandbox";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
@@ -154,7 +167,8 @@ from authored helpers.
 Each subagent has its own sandbox, independent of its parent. This is intentional: subagents carry
 different skills, so they should not inherit the parent's filesystem.
 
-- If a subagent authors `subagents/<name>/sandbox/sandbox.ts`, that definition is used.
+- If a subagent authors `subagents/<name>/sandbox.ts` (or `subagents/<name>/sandbox/sandbox.ts`),
+  that definition is used. The same shorthand-vs-folder rules apply as for the root agent.
 - If a subagent authors only `subagents/<name>/sandbox/workspace/`, the framework default applies
   with that workspace seeded in.
 - If a subagent authors neither, the framework default is used as-is.
@@ -171,6 +185,9 @@ Inside a subagent's authored code, `getSandbox()` binds to the subagent's own sa
 - installing dependencies
 - seeding files or directories every later session should start with
 
+Call `use()` to get a `SandboxSession`. Only filesystem state survives — configuration changes
+like network policy or resource allocation do not persist into the snapshot.
+
 Framework-managed seed files (compiled skills, authored `workspace/` entries) are written into the
 template before the authored `bootstrap` runs, so your bootstrap can read them.
 
@@ -178,10 +195,14 @@ template before the authored `bootstrap` runs, so your bootstrap can read them.
 
 `onSession` is durable-session-scoped. Use it for one-time setup for the current Ash session:
 
+- configuring network policy, resources, or timeout
 - creating a session-specific working copy
 - configuring per-user credentials for CLI tools
 - writing one-time markers
-- lightweight setup that should not be baked into the template
+
+Call `use(opts?)` to get the backend-specific sandbox. When using `vercelBackend()`, this returns
+a `VercelSandbox` with `update()` for session-level configuration. Options passed to `use()` are
+applied immediately; you can call `sandbox.update()` again later if needed.
 
 Unlike `bootstrap`, `onSession` runs inside the active Ash runtime context, so user-scoped setup can
 call `getSession()` and derive the current principal without baking credentials into the reusable
@@ -189,10 +210,12 @@ template:
 
 ```ts
 import { getSession } from "experimental-ash/context";
-import { defineSandbox } from "experimental-ash/sandboxes";
+import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
-  async onSession({ sandbox }) {
+  backend: vercelBackend(),
+  async onSession({ use }) {
+    const sandbox = await use({ networkPolicy: "deny-all" });
     const user = getSession().auth.current;
     if (user === null) return;
 
@@ -206,22 +229,27 @@ export default defineSandbox({
 
 ## Backend Selection
 
-Ash ships two built-in backends, exposed as factory functions from `experimental-ash/sandboxes`:
+Ash ships two built-in backends, exposed as factory functions from `experimental-ash/sandbox`:
 
-- `vercelBackend(options?)` — runs the sandbox on Vercel Sandbox via `@vercel/sandbox`.
+- `vercelBackend()` — runs the sandbox on Vercel Sandbox via `@vercel/sandbox`. Returns a
+  `VercelSandbox` from `onSession`'s `use()` with full SDK capabilities.
 - `localBackend()` — runs the sandbox locally via `just-bash`. Default for `pnpm ash dev`.
 
 Attach a backend via `defineSandbox({ backend })`:
 
 ```ts
 // agent/sandbox/sandbox.ts
-import { defineSandbox, vercelBackend } from "experimental-ash/sandboxes";
+import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
-  backend: vercelBackend({ runtime: "node24" }),
-  async bootstrap({ sandbox }) {
+  backend: vercelBackend(),
+  async bootstrap({ use }) {
+    const sandbox = await use();
     await sandbox.runCommand("git clone https://example.com/repo.git repo");
   },
+  async onSession({ use }) {
+    await use({ networkPolicy: "deny-all" });
+  },
 });
 ```
 
@@ -233,82 +261,103 @@ default; production builds on Vercel use the Vercel backend by default.
 If you want the env-aware default explicitly, use `defaultBackend()`:
 
 ```ts
-import { defaultBackend, defineSandbox } from "experimental-ash/sandboxes";
+import { defaultBackend, defineSandbox } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: defaultBackend(),
 });
 ```
 
-### Vercel Backend Options
+### Vercel Backend: Session Configuration
 
-`vercelBackend(options)` accepts the same parameters as `@vercel/sandbox`'s `Sandbox.create`, minus
-the four fields Ash owns internally (`name`, `persistent`, `source`, `signal`). The option type is
-**inferred** from the SDK so new SDK fields flow through automatically without any ash-side change.
-Hover the `options` argument in your editor to see the live set of fields.
+`vercelBackend()` takes no options. All configuration is done through lifecycle hooks:
+
+- **Immutable creation config** (runtime, ports, env) — passed via `bootstrap`'s `use()`:
 
 ```ts
-vercelBackend({
-  networkPolicy: "deny-all",
-  runtime: "node24",
-  resources: { vcpus: 4 },
-  ports: [3000],
-  env: { NODE_ENV: "production" },
-});
+async bootstrap({ use }) {
+  const sandbox = await use({ runtime: "node24", ports: [3000] });
+  await sandbox.runCommand("npm install");
+}
 ```
 
-Ash also attaches Vercel Sandbox tags for runtime attribution:
+- **Session-level config** (networkPolicy, resources, timeout, tags) — passed via `onSession`'s
+  `use()` or `sandbox.update()`:
 
-- `agent` — the active agent or subagent name
-- `channel` — the active channel adapter kind
-- `sessionId` — the Ash session id
+```ts
+async onSession({ use }) {
+  const sandbox = await use({
+    networkPolicy: "deny-all",
+    resources: { vcpus: 4 },
+    timeout: 60 * 60 * 1_000,
+  });
+  // Can also update later:
+  await sandbox.update({ tags: { user: "casey" } });
+}
+```
+
+This split ensures that `bootstrap` only does filesystem setup (which survives snapshotting), while
+`onSession` configures the live session (network policy, resources, etc. do not survive snapshots).
+
+### Network Policies
+
+Network policies are set per-session via `onSession`. Three forms are supported:
+
+```ts
+await use({ networkPolicy: "allow-all" }); // default
+await use({ networkPolicy: "deny-all" }); // block all egress, including DNS
+
+await use({
+  networkPolicy: {
+    allow: ["ai-gateway.vercel.sh", "*.github.com"],
+    subnets: { deny: ["10.0.0.0/8"] },
+  },
+});
+```
 
-Custom `tags` passed to `vercelBackend(options)` are merged with those Ash-owned tags. Vercel
-Sandbox supports at most five tags, so custom tags have two free slots unless they intentionally
-share an Ash-owned key.
+Since network policy is applied in `onSession` (after the template snapshot), it does not constrain
+`bootstrap`. You can freely `git clone` and `npm install` in bootstrap, then lock down the network
+in `onSession`.
 
 ### Timeout
 
 The `@vercel/sandbox` SDK shuts down idle VMs after a configurable timeout (default 5 minutes). Ash
-raises this default to **30 minutes** so sandboxes survive across workflow step boundaries. You can
-override it via `vercelBackend()`:
+raises this default to **30 minutes** so the sandbox survives across workflow step boundaries. You can
+override it in `onSession`:
 
 ```ts
-vercelBackend({ timeout: 60 * 60 * 1_000 }); // 1 hour
+async onSession({ use }) {
+  await use({ timeout: 60 * 60 * 1_000 }); // 1 hour
+}
 ```
 
 The maximum timeout depends on your Vercel plan: **5 hours** for Pro/Enterprise, **45 minutes** for
 Hobby. If a sandbox expires between steps, the next step will fail with a `410 Gone` error.
 
-### Network Policies
+### Tags
 
-The Vercel backend exposes the underlying SDK's `networkPolicy` field unchanged. Three forms are
-supported:
+Ash attaches Vercel Sandbox tags for runtime attribution:
 
-```ts
-vercelBackend({ networkPolicy: "allow-all" }); // default
-vercelBackend({ networkPolicy: "deny-all" }); // block all egress, including DNS
+- `agent` — the active agent or subagent name
+- `channel` — the active channel adapter kind
+- `sessionId` — the Ash session id
 
-vercelBackend({
-  networkPolicy: {
-    allow: ["ai-gateway.vercel.sh", "*.github.com"],
-    subnets: { deny: ["10.0.0.0/8"] },
-  },
-});
+Custom tags can be set via `onSession`:
+
+```ts
+async onSession({ use }) {
+  await use({ tags: { team: "infra" } });
+}
 ```
 
-Important caveat: any options you pass to `vercelBackend()` are applied to **both** the build-time
-template snapshot (when `bootstrap()` runs) and per-session sandbox creation. A restrictive
-`networkPolicy` will therefore also constrain `bootstrap()`. Make sure your bootstrap works within
-whatever constraints you set — for example, a `deny-all` policy will block `git clone` and
-`npm install`. If you need a less restrictive bootstrap, allowlist only the hosts your bootstrap
-needs (e.g. `["registry.npmjs.org"]`) instead of using `deny-all`.
+Vercel Sandbox supports at most five tags. Ash-owned tags take three slots, leaving two for custom
+tags.
 
 ### Custom Backends
 
 A `SandboxBackend` is just an object with a `name` and a `create` function (and optionally
 `prewarm`). You can write your own and pass it to `defineSandbox({ backend })`. See
-`experimental-ash/sandboxes` for the `SandboxBackend`, `SandboxBackendCreateInput`, and
+`experimental-ash/sandbox` for the `SandboxBackend`, `SandboxBackendCreateInput`, and
 `SandboxBackendPrewarmInput` interface types.
 
 ## Vercel Behavior

package/{docs → dist/docs}/public/session-context.md

@@ -83,7 +83,7 @@ Important behavior:
 backend-native path for a logical `/workspace/...` location before passing it to shell code or a
 child process.
 
-See [`sandboxes.md`](./sandboxes.md) for lifecycle details.
+See [`sandbox.md`](./sandbox.md) for lifecycle details.
 
 ## `getSkill(identifier)`
 

package/{docs → dist/docs}/public/subagents.md

@@ -1,6 +1,6 @@
 ---
 title: "Subagents"
-description: "Delegate specialized work to child agents with their own prompts, tools, and sandboxes."
+description: "Delegate specialized work to child agents with their own prompts, tools, and sandbox."
 ---
 
 Subagents let the root agent delegate specialized work to local child agents.
@@ -61,9 +61,9 @@ Subagent execution gets:
 
 The subagent's sandbox does not inherit from the parent. Different agents generally have different
 skills, so sharing a filesystem would be confusing. Each subagent gets the framework default
-sandbox unless it authors its own override at `subagents/<name>/sandbox/sandbox.ts`. A subagent can
-also author only `subagents/<name>/sandbox/workspace/` to seed files without overriding the
-definition.
+sandbox unless it authors its own override at `subagents/<name>/sandbox.ts` (or
+`subagents/<name>/sandbox/sandbox.ts` when paired with a `workspace/` folder). A subagent can also
+author only `subagents/<name>/sandbox/workspace/` to seed files without overriding the definition.
 
 ## Stream Behavior