experimental-ash 0.3.0-alpha.35 → 0.3.0-alpha.37

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/evals.md

@@ -40,6 +40,7 @@ import { Run } from "experimental-ash/evals/scores";
 
 export default defineEvalSuite({
   id: "weather-smoke",
+  model: "openai/gpt-5.4-mini",
   name: "Weather Smoke",
   description: "Basic message and tool-usage coverage for the weather agent.",
   cases: [
@@ -59,6 +60,7 @@ can discover and run.
 Every suite must provide:
 
 - `id`
+- `model`
 - `name`
 - `scores`
 - either `cases` or `load`
@@ -68,6 +70,7 @@ Common optional suite fields:
 - `description`
 - `task`
 - `thresholds`
+- `modelOptions`
 - `tags`
 - `metadata`
 - `maxConcurrency`
@@ -86,6 +89,7 @@ You can provide cases directly:
 ```ts
 export default defineEvalSuite({
   id: "smoke",
+  model: "openai/gpt-5.4-mini",
   name: "Smoke",
   cases: [
     {
@@ -107,6 +111,7 @@ import { Text } from "experimental-ash/evals/scores";
 
 export default defineEvalSuite({
   id: "marketing-sql",
+  model: "openai/gpt-5.4-mini",
   name: "Marketing SQL",
   async load() {
     const doc = await loadYaml("evals/data/cases.yaml");
@@ -127,6 +132,7 @@ message.
 ```ts
 defineEvalSuite({
   id: "weather-task",
+  model: "openai/gpt-5.4-mini",
   name: "Weather Task",
   task: {
     prompt: (testCase) => `Answer the user: ${String(testCase.input)}`,
@@ -144,6 +150,7 @@ Suite thresholds let you relax a scorer from the default exact-match requirement
 ```ts
 defineEvalSuite({
   id: "weather",
+  model: "openai/gpt-5.4-mini",
   name: "Weather",
   cases: [{ id: "hello", input: "Hello", expected: "Hello" }],
   scores: [Run.didNotFail(), Text.includes()],
@@ -157,6 +164,34 @@ defineEvalSuite({
 Use `maxConcurrency` to limit how many cases the runner executes in parallel and `timeoutMs` to
 bound each case. When omitted, `ash eval` runs up to 8 cases in parallel per suite.
 
+## Model-Backed Scorers
+
+Some scorers call a judge or embedding model. For those scorers, Ash uses the same model contract
+as `agent.ts`:
+
+- a string model id, such as `"openai/gpt-5.4-mini"`, routes through the Vercel AI Gateway
+- an AI SDK model instance is used directly
+
+Set a suite-level scorer model with `model`. Every eval suite requires one. This model is only
+used for scoring; it does not change the Ash agent being evaluated.
+
+```ts
+import { defineEvalSuite } from "experimental-ash/evals";
+import { Autoevals, Run } from "experimental-ash/evals/scores";
+
+export default defineEvalSuite({
+  id: "support-quality",
+  name: "Support Quality",
+  model: "openai/gpt-5.4-mini",
+  cases: [{ id: "refund", input: "How do I get a refund?", expected: "refund policy" }],
+  scores: [Run.didNotFail(), Autoevals.factuality()],
+});
+```
+
+Use `modelOptions.providerOptions` when the scorer model needs provider-specific AI SDK options.
+Individual Autoevals scorers also accept `model` and `modelOptions`; scorer-level values override
+the suite default.
+
 ## Loaders
 
 Ash ships small loader helpers for eval data files:
@@ -170,20 +205,42 @@ These loaders are meant for eval fixtures and other authoring-time data, not for
 
 ## Scores
 
-Ash exports scorer namespaces from `experimental-ash/evals/scores`:
+Ash exports scorer namespaces from `experimental-ash/evals/scores`. Scorers receive flattened
+`input`, `output`, and `expected` strings plus the full case and task result. They may return
+`null` to skip scoring a case.
+
+### Picking a Scorer
+
+Pick the cheapest scorer that can express what "correct" means. Free scorers run instantly with no
+API cost; an LLM judge runs once per case and costs tokens, so reach for it last.
+
+| Need                                                         | Use                                                        |
+| ------------------------------------------------------------ | ---------------------------------------------------------- |
+| Assert agent behavior (run succeeded, used the right tools)  | `Run.didNotFail()`, `Run.usedTool()`, `Run.maxToolCalls()` |
+| Exact string match                                           | `Text.exact()` or `Text.includes()`                        |
+| Exact JSON match                                             | `Json.deepEqual()`                                         |
+| Exact SQL match (after normalization)                        | `Sql.exactNormalized()`                                    |
+| Fuzzy text match (typos, whitespace differences)             | `Text.levenshtein()`                                       |
+| LLM-judged factual correctness vs an expected answer         | `Autoevals.factuality()`                                   |
+| LLM-judged summary quality                                   | `Autoevals.summary()`                                      |
+| LLM-judged SQL semantic equivalence                          | `Autoevals.sql()`                                          |
+| LLM-judged free-form criteria (no `expected` value to match) | `Autoevals.closedQA({ criteria: "..." })`                  |
+
+### Reference
 
-- `Text.exact()` and `Text.includes()`
-- `Json.deepEqual()`
-- `Sql.exactNormalized()`
 - `Run.didNotFail()`
 - `Run.usedTool(name)`
 - `Run.usedNoTools()`
 - `Run.maxToolCalls(max)`
-
-Scorers receive flattened `input`, `output`, and `expected` strings plus the full case and task
-result. They may return `null` to skip scoring a case.
-
-Use `Run.*` scores when you want to assert execution behavior, not just final text.
+- `Text.exact()`
+- `Text.includes()`
+- `Text.levenshtein()`
+- `Json.deepEqual()`
+- `Sql.exactNormalized()`
+- `Autoevals.factuality()`
+- `Autoevals.summary()`
+- `Autoevals.sql()`
+- `Autoevals.closedQA({ criteria })`
 
 ## Reporters
 

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}

@@ -22,21 +22,31 @@ 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`:
+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 }) {
     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)
@@ -44,13 +54,12 @@ The public lifecycle surface is intentionally small:
 - `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 +76,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 +103,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 +111,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 +164,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.
@@ -189,7 +200,7 @@ template:
 
 ```ts
 import { getSession } from "experimental-ash/context";
-import { defineSandbox } from "experimental-ash/sandboxes";
+import { defineSandbox } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   async onSession({ sandbox }) {
@@ -206,7 +217,7 @@ 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`.
 - `localBackend()` — runs the sandbox locally via `just-bash`. Default for `pnpm ash dev`.
@@ -215,7 +226,7 @@ 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" }),
@@ -233,7 +244,7 @@ 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(),
@@ -270,7 +281,7 @@ share an Ash-owned key.
 ### 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
+raises this default to **30 minutes** so the sandbox survives across workflow step boundaries. You can
 override it via `vercelBackend()`:
 
 ```ts
@@ -308,7 +319,7 @@ needs (e.g. `["registry.npmjs.org"]`) instead of using `deny-all`.
 
 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
 

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

@@ -40,7 +40,7 @@ exposed to the model as `get_weather`; a file at `agent/tools/get-weather.ts` is
 
 `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, and `defineWriteFileTool` live on the `experimental-ash/tools` subpath.
 Runtime context helpers (`getSession`, `getContext`, `requireContext`, `hasContext`, `setContext`, `ensureContext`) live on `experimental-ash/context`.
-`getSandbox` lives on `experimental-ash/sandboxes` and `getSkill` lives on `experimental-ash/skills`.
+`getSandbox` lives on `experimental-ash/sandbox` and `getSkill` lives on `experimental-ash/skills`.
 
 ## What A Tool Definition Needs
 
@@ -170,7 +170,7 @@ filenames fail at resolve time instead of silently doing nothing.
 
 `defineBashTool`, `defineReadFileTool`, and `defineWriteFileTool` build additional model-visible
 tools that share the executor core of the framework `bash`, `read_file`, and `write_file` tools. All
-of them run in the agent's single sandbox — there is no `sandboxes` option to pass.
+of them run in the agent's single sandbox — there is no `sandbox` option to pass.
 
 Use them whenever you want extra `bash`-shaped or file-shaped tools with narrower model-facing
 descriptions:
@@ -263,7 +263,7 @@ unbounded text, cap it in the executor before returning:
 
 ```ts
 import { defineTool } from "experimental-ash/tools";
-import { truncateHead } from "experimental-ash/sandboxes/truncate-output";
+import { truncateHead } from "experimental-ash/sandbox/truncate-output";
 import { z } from "zod";
 
 export default defineTool({
@@ -321,4 +321,4 @@ export default defineTool({
 ## What To Read Next
 
 - [`session-context.md`](./session-context.md)
-- [`sandboxes.md`](./sandboxes.md)
+- [`sandbox.md`](./sandbox.md)