experimental-ash 0.3.0-alpha.36 → 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/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)

package/{docs → dist/docs}/public/typescript-api.md

@@ -11,7 +11,7 @@ Source of truth:
 - context subpath: [`../../packages/ash/src/public/context/index.ts`](../../packages/ash/src/public/context/index.ts)
 - skills subpath: [`../../packages/ash/src/public/skills/index.ts`](../../packages/ash/src/public/skills/index.ts)
 - tools subpath: [`../../packages/ash/src/public/tools/index.ts`](../../packages/ash/src/public/tools/index.ts)
-- sandboxes subpath: [`../../packages/ash/src/public/sandboxes/index.ts`](../../packages/ash/src/public/sandboxes/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)
 - evals subpath: [`../../packages/ash/src/evals/index.ts`](../../packages/ash/src/evals/index.ts)
 
@@ -19,14 +19,14 @@ Source of truth:
 
 Use these to author the filesystem-backed surface. Each concern has its own subpath:
 `experimental-ash/tools` for tools, `experimental-ash/hooks` for hooks,
-`experimental-ash/sandboxes` for sandboxes, `experimental-ash/skills` for skills,
+`experimental-ash/sandbox` for the sandbox, `experimental-ash/skills` for skills,
 `experimental-ash/context` for context helpers, and the main `experimental-ash`
 barrel for agent config, routes, schedules, and systems.
 
 - `defineAgent(...)` - additive runtime config for `agent.ts`
 - `defineHook(...)` - lifecycle and stream-event subscriber in `hooks/<slug>.ts` (`experimental-ash/hooks`)
 - `defineRoute(...)` - messaging-platform or HTTP route entrypoints in `channels/`
-- `defineSandbox(...)` - override the agent's single sandbox in `sandbox/sandbox.ts` (`experimental-ash/sandboxes`)
+- `defineSandbox(...)` - override the agent's single sandbox in `sandbox.ts` (or `sandbox/sandbox.ts` when paired with a `workspace/` folder) (`experimental-ash/sandbox`)
 - `defineSchedule(...)` - recurring jobs in `schedules/<name>/schedule.ts`; requires `cron` and `channel`
 - `defineSkill(...)` - module-authored skills (`experimental-ash/skills`)
 - `defineSubagent(...)` - local subagent entrypoint in `subagents/<id>/subagent.ts`
@@ -42,7 +42,6 @@ barrel for agent config, routes, schedules, and systems.
 Framework defaults reachable for spread/wrap composition:
 
 - `bash`, `readFile`, `writeFile`, `webFetch`, `todo`, `loadSkill` (`experimental-ash/tools/defaults`)
-- `defaultSandbox` (`experimental-ash/sandboxes/defaults`)
 
 Most apps use `defineAgent`, `defineTool`, and `defineSandbox` the most.
 
@@ -51,7 +50,7 @@ Most apps use `defineAgent`, `defineTool`, and `defineSandbox` the most.
 Each runtime accessor lives on the subpath that owns its concern:
 
 - `getSession()` - current session, turn, auth, and optional parent lineage (`experimental-ash/context`)
-- `getSandbox()` - live sandbox handle for the current agent (`experimental-ash/sandboxes`)
+- `getSandbox()` - live sandbox handle for the current agent (`experimental-ash/sandbox`)
 - `getSkill(identifier)` - handle for a named skill visible to the current agent (`experimental-ash/skills`)
 - `getContext(key)` / `requireContext(key)` / `hasContext(key)` / `setContext(key)` / `ensureContext(key, factory)` - unified context helpers (`experimental-ash/context`)
 
@@ -136,7 +135,7 @@ import { defineTool } from "experimental-ash/tools";
 ### Sandbox Access
 
 ```ts
-import { getSandbox } from "experimental-ash/sandboxes";
+import { getSandbox } from "experimental-ash/sandbox";
 import { defineTool } from "experimental-ash/tools";
 import { defineBashTool } from "experimental-ash/tools";
 ```
@@ -184,7 +183,7 @@ import { Braintrust } from "experimental-ash/evals/reporters";
 - `defineRoute` and route/channel factories -> [`channels/README.md`](./channels/README.md)
 - `defineTool`, `disableTool`, `defineBashTool`, `defineReadFileTool`, `defineWriteFileTool`, and `experimental-ash/tools/defaults` -> [`tools.md`](./tools.md)
 - `defineHook`, `HookContext`, and lifecycle/event types -> [`hooks.md`](./hooks.md)
-- `defineSandbox` and `getSandbox` -> [`sandboxes.md`](./sandboxes.md)
+- `defineSandbox` and `getSandbox` -> [`sandbox.md`](./sandbox.md)
 - `defineSkill` and `getSkill` -> [`skills.md`](./skills.md)
 - `getSession` -> [`session-context.md`](./session-context.md)
 - `defineSubagent` -> [`subagents.md`](./subagents.md)

package/{docs → dist/docs}/public/vercel-deployment.md

@@ -42,7 +42,7 @@ Attach the backend on the sandbox definition:
 
 ```ts
 // agent/sandbox/sandbox.ts
-import { defineSandbox, vercelBackend } from "experimental-ash/sandboxes";
+import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: vercelBackend(),
@@ -104,5 +104,5 @@ This is useful for smoke tests against preview or production environments.
 ## What To Read Next
 
 - [`workspace.md`](./workspace.md)
-- [`sandboxes.md`](./sandboxes.md)
+- [`sandbox.md`](./sandbox.md)
 - [`auth-and-route-protection.md`](./auth-and-route-protection.md)

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

@@ -30,7 +30,7 @@ workspace today:
   bring their skill package directory with them.
 - **Sandbox workspace files** under `agent/sandbox/workspace/` are mirrored into the workspace
   cwd, preserving subdirectory structure. See
-  [`sandboxes.md`](./sandboxes.md#seeding-workspace-files) for the convention.
+  [`sandbox.md`](./sandbox.md#seeding-workspace-files) for the convention.
 
 That means:
 
@@ -48,7 +48,7 @@ The backend (`localBackend()` or `vercelBackend()`) is configured on the sandbox
 
 ```ts
 // agent/sandbox/sandbox.ts — pin the agent to the local just-bash backend
-import { defineSandbox, localBackend } from "experimental-ash/sandboxes";
+import { defineSandbox, localBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: localBackend(),
@@ -98,5 +98,5 @@ Prefer tools when you need typed business logic or external API access.
 
 ## What To Read Next
 
-- [`sandboxes.md`](./sandboxes.md)
+- [`sandbox.md`](./sandbox.md)
 - [`runs-and-streaming.md`](./runs-and-streaming.md)

package/dist/src/chunks/chunk-2BCVGULU.js

@@ -0,0 +1,37 @@
+import { createRequire as __ashCreateRequire } from "node:module"; const require = __ashCreateRequire(import.meta.url);
+import {
+  isObject
+} from "./chunk-APDYQG3O.js";
+
+// src/shared/errors.ts
+function toErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error === null || error === void 0) {
+    return String(error);
+  }
+  if (isObject(error)) {
+    if (typeof error.message === "string" && error.message.length > 0) {
+      return error.message;
+    }
+    return safeJsonStringify(error);
+  }
+  return String(error);
+}
+function safeJsonStringify(value) {
+  try {
+    const stringified = JSON.stringify(value);
+    return stringified ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export {
+  toErrorMessage
+};
+//# sourceMappingURL=chunk-2BCVGULU.js.map