experimental-ash 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # experimental-ash
 
+## 0.36.0
+
+### Minor Changes
+
+- 34722b0: Unify runtime data access: `ctx` is available as the last argument to all ALS-scoped authored callbacks. Omit it when you don't need it.
+
+  **Breaking changes:**
+
+  - Tool `execute(input)` → `execute(input, ctx)` — access session, sandbox, and skills via `ctx`
+  - Hook lifecycle `(input, ctx)` → `(ctx)` — session identity, auth, and turn info are on `ctx.session`
+  - Hook/channel events `(event, ctx)` → same shape, but `ctx` now carries `session`, `getSandbox()`, `getSkill()`
+  - `SessionHandle.id` (unchanged), `.auth` is now `{ current, initiator }` (was flat)
+  - `getSession()`, `getSandbox()`, `getSkill()` removed — use `ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`
+  - `HookContext.ash` removed — use `defineState` for durable state
+  - `CompactionHookInput` → `onCompact({ history, signal }, ctx)`
+  - `LifecycleHookInput` removed (absorbed into `HookContext`)
+
+  Non-ALS callbacks unchanged: schedule `run`, sandbox `bootstrap`/`onSession`, instrumentation `setup`.
+
+### Patch Changes
+
+- 4e50396: Fixed parked subagent/remote-agent turns persisting a stale (default) emission state. The runtime-action park now stamps the live turn's emission identity onto the parked session, so the resume turn is classified as a continuation instead of a fresh turn — preventing duplicate `session.started`/`turn.started` events and empty `turnId`s on resume.
+
+## 0.35.0
+
+### Minor Changes
+
+- 24aa0cd: `localDev()` now also grants the local-dev session when running under `vercel dev` (`VERCEL=1` and `VERCEL_ENV=development`), not just loopback requests, so the local Vercel dev server can reach the agent without an OIDC token. `ASH_LOG_LEVEL` now defaults to `info` in every environment (previously `debug` outside production), making `debug` opt-in so dev output is no longer flooded with best-effort lines.
+- a59d91c: Remove deprecated `SandboxSession.runCommand` alias and `SandboxRunCommandOptions` type. Use `sandbox.run({ command })` and `SandboxRunOptions` instead.
+- 083c20a: `vercelOidc()` now accepts Vercel OIDC tokens with `external_sub` as user principals when the token matches the configured Vercel project and deployment environment. The resulting session auth uses `external_sub` as the subject, prefers `external_iss` / `connector_id` as the issuer, and exposes string OIDC profile claims such as `name`, `picture`, and `email` as attributes.
+
+### Patch Changes
+
+- 321bae2: Upgrade `@vercel/sandbox` from 2.0.0 to 2.0.1. Sessions are now persistent by default and auto-resume on `Sandbox.get()`. Vendored types updated with `resume`, `onResume`, and `readFile`.
+
 ## 0.34.0
 
 ### Minor Changes

package/dist/docs/internals/context.md

@@ -17,7 +17,7 @@ interface AshContext {
 }
 ```
 
-`loadContext()` returns the active context or throws. Public accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it.
+`loadContext()` returns the active context or throws. Internal accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it — these are implementation details, not public exports. Authored code uses `ctx.session`, `ctx.getSandbox()`, and `ctx.getSkill()` instead.
 
 ## Type Hierarchy
 
@@ -78,9 +78,10 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 5. Call framework provider `commit` hooks for provider-owned session state
 
 Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
-runs inside step (4)'s ALS scope, before the harness step. See
-[Hooks](./hooks.md) for the full pipeline and the
-`SessionPreparedKey` flag's failure semantics.
+runs inside step (4)'s ALS scope, before the harness step. Lifecycle
+hooks receive `(ctx)`, and event hooks receive `(event, ctx)`. See
+[Hooks](./hooks.md) for the full pipeline and the `SessionPreparedKey`
+flag's failure semantics.
 
 `StepInput.modelContext` has two producers. Channels can provide
 ephemeral messages through `SendPayload.modelContext`, and lifecycle
@@ -91,7 +92,7 @@ call only and are never persisted to durable session history.
 
 ## Channel Context
 
-Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a `ContextAccessor` and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
+Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a context accessor and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
 
 Auth lives on the run and deliver inputs:
 

package/dist/docs/internals/core-beliefs.md

@@ -15,8 +15,8 @@ source of truth; a repeated `name` field is a second source that can drift.
 
 The hooks surface (`agent/hooks/`) deliberately reuses the unified
 `AshContext` rather than introducing a parallel state-patch channel:
-hooks read and write through `ctx.ash` like every other authored
-function. One context, one set of keys, one place to look when debugging.
+hooks read and write through `ctx` like every other authored function.
+One context, one set of keys, one place to look when debugging.
 
 ## Durable Work Belongs In The Runtime
 

package/dist/docs/internals/hooks.md

@@ -18,15 +18,20 @@ through one runtime registry, one `HookContext`, one set of ordering
 rules.
 
 The hooks surface deliberately reuses the unified `AshContext`:
-`HookContext.ash` is the same `ContextAccessor` tools, providers, and
-channels get. There is no parallel state-patch channel — one
-`AshContext`, one set of keys, one place to look when debugging.
+`HookContext` extends `AshCallbackContext`, giving hooks the same
+context surface tools, providers, and channels get. There is no
+parallel state-patch channel — one `AshContext`, one set of keys, one
+place to look when debugging.
 
-`HookContext` itself is intentionally tiny: `agent`, `channel`, `session`
-identity plus the `ash` accessor. Per-turn `turnId` and `sequence` come
-from `LifecycleHookInput.turn` for lifecycle hooks, and from
-`event.data.{turnId, sequence}` for stream-event hooks — never duplicated
-on the context.
+`HookContext` carries `agent`, `channel`, and `session` (which includes
+`id`, `auth`, `turn`, and `parent`). `session.auth` is a nested
+`SessionAuth` with `{ current, initiator }`.
+
+Lifecycle hooks receive `(ctx)` — a single `HookContext` argument.
+Event hooks receive `(event, ctx)` — event first, context last (omit `ctx` when unused).
+Per-turn `turnId` and `sequence` come from `ctx.session.turn` for
+lifecycle hooks, and from `event.data.{turnId, sequence}` for
+stream-event hooks — never duplicated on the context.
 
 ## Authoring shape
 
@@ -87,7 +92,7 @@ the workflow path.
 Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. The
 workflow runtime entry point (`execution/workflow-steps.ts`) calls
 `runHookLifecycleStep` once per turn, **inside** the active ALS scope
-so hook code can read and write `ctx.ash` like every other authored
+so hook code can read and write context like every other authored
 function. `runHookLifecycleStep` wraps `dispatchHookLifecycle`, lowers
 a `turn-failed` outcome into a parking `StepResult` (`{ next: null }`
 for conversation mode, `{ next: { done: true, output } }` for task
@@ -142,7 +147,7 @@ Subagent hooks are fully isolated by structural construction:
   established by the existing subagent invocation pipeline. Hooks
   resolve from the subagent node's `hookRegistry`, not the parent
   agent's.
-- `ctx.ash` reads hit the subagent's container, not the parent's.
+- `ctx` reads hit the subagent's container, not the parent's.
 - Lexicographic ordering applies within a subagent's hook set only.
   Parent and child registries do not interleave.
 
@@ -188,7 +193,7 @@ documented expectations:
 - Hook modules never import workflow primitives (`start`, `resumeHook`,
   `createHook`, `getWritable`).
 - Hook return shapes have no `state` field — durable state goes through
-  `ctx.ash`.
+  `ctx`.
 - Subagent hooks never read parent ALS context.
 
 ## Related Pages

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

@@ -68,10 +68,10 @@ flags new `@workflow/*` imports from channel, harness, and hook code.
 ### Hooks Use The Single State Channel
 
 Authored hook modules (`agent/hooks/**`) must read and write durable state
-through `ctx.ash` (the unified `ContextAccessor`). The hooks surface
-introduces no parallel state-patch channel — lifecycle return shapes
-expose only `modelContext` (a one-shot per-call ephemeral message list),
-and subagent hooks never read parent ALS context.
+through `ctx` (the unified context). The hooks surface introduces no
+parallel state-patch channel — lifecycle return shapes expose only
+`modelContext` (a one-shot per-call ephemeral message list), and subagent
+hooks never read parent ALS context.
 
 Enforcement: rule 27 in `scripts/guard-agents-rules.mjs` fails if a
 `state:` (or `readonly state:`, `state?:`) field is declared on any

package/dist/docs/internals/testing.md

@@ -62,7 +62,7 @@ Ad-hoc tmp directories with `package.json` + `agent/` scaffolding.
 
 - Unit tier: `unit-guard.ts` throws on disk writes, subprocesses, `process.chdir`, real fetch. If you hit a guard throw, move the test to a higher tier.
 - Never mutate the process-default `RuntimeSession` — let `createTestRuntime().run(fn)` scope it. Do not call `installBundledCompiledArtifacts` / `resetBundledCompiledArtifacts` / `clearProcessDefaultRuntimeSession` directly.
-- Use `runAsSession({}, ...)` when the test needs `getSession()` / `getSandbox()` / `getSkill()` to resolve. Use `run(...)` when only compiled artifacts + bundle cache need scoping.
+- Use `runAsSession({}, ...)` when the test needs `ctx.session` / `ctx.getSandbox()` / `ctx.getSkill()` to resolve (the internal `getSession()`, `getSandbox()`, `getSkill()` free functions still work but are not public API). Use `run(...)` when only compiled artifacts + bundle cache need scoping.
 - Cleanup is automatic for `mockSkill`, `useScenarioApp`, and `useTemporaryAppRoots`.
 - Do not commit new fixtures under `test/fixtures/` — CI guard will fail. Use descriptors in `src/internal/testing/scenario-apps/`.
 - Prefer `vi.stubEnv` over direct `process.env` mutation.

package/dist/docs/public/README.md

@@ -60,7 +60,7 @@ Ash then gives you:
 - a reconnectable session stream
 - durable session state across turns
 - a per-agent sandbox with a shared runtime workspace
-- typed runtime helpers such as `getSession()`, `getSandbox()`, and `getSkill()`
+- typed runtime helpers accessed through `ctx` (`ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`)
 
 ## The Runtime Shape
 

package/dist/docs/public/auth-and-route-protection.md

@@ -156,6 +156,15 @@ Use this for the common Vercel deployment path. Verifies a bearer JWT against th
 issuer; tokens minted for the current `VERCEL_PROJECT_ID` are always accepted (so internal
 subagent / runtime callers authenticate without configuration).
 
+It accepts Vercel OIDC bearer tokens after signature, issuer, audience, and time-claim verification.
+Tokens for the current `VERCEL_PROJECT_ID` authenticate as runtime/service callers. Tokens with
+`external_sub` authenticate as user callers when their `project_id` matches `VERCEL_PROJECT_ID` if
+configured, and their `environment` matches `VERCEL_TARGET_ENV` or `VERCEL_ENV` if configured. For
+those user tokens, `external_sub` becomes the session subject, `external_iss` becomes the session
+issuer when present, and `connector_id` is used as the issuer fallback before the Vercel OIDC issuer.
+String OIDC profile claims such as `name`, `picture`, and `email` are exposed in
+`ctx.session.auth.current.attributes`.
+
 ### `none`
 
 Returns a synthetic anonymous `SessionAuthContext`. Use as the final entry in `auth` to accept
@@ -186,7 +195,7 @@ re-materializes them from the authored channel definition when it needs the live
 
 ## What Auth Reaches Authored Code
 
-Inside runtime code, `getSession().auth` gives you the caller snapshot.
+Inside runtime code, `ctx.session.auth` gives you the caller snapshot.
 
 Important behavior:
 
@@ -198,8 +207,8 @@ Important behavior:
   accepts with a `SessionAuthContext` or returns `401`
 
 Auth on follow-up messages (`deliver()`) is honored by the workflow runtime. When a different
-user sends a follow-up to the same session, `session.auth.current` reflects the new caller on
-that turn while `session.auth.initiator` stays the same.
+user sends a follow-up to the same session, `ctx.session.auth.current` reflects the new caller on
+that turn while `ctx.session.auth.initiator` stays the same.
 
 ## What Ash Does Not Do
 

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

@@ -179,7 +179,7 @@ export default slackChannel({
       if (event.finishReason === "tool-calls") return;
       if (event.message) ctx.thread.post(event.message);
     },
-    "session.failed"(event, ctx) {
+    "session.failed"(_event, ctx) {
       ctx.thread.post("Something went wrong.");
     },
   },
@@ -372,7 +372,7 @@ Semantics:
 
 - The target channel's authored `receive(input, { send })` hook owns the continuation-token
   format and the initial state. Callers supply only `{ message, args, auth }`.
-- `auth` flows through to `session.initiatorAuth` so the target's event handlers and the
+- `auth` flows through to `session.auth.initiator` so the target's event handlers and the
   agent's tools can read who started the session.
 - Calling `args.receive(...)` does **not** also start a session on the current channel. The
   inbound channel's response is whatever the route handler returns explicitly (e.g.

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

@@ -163,7 +163,7 @@ export default slackChannel({
       if (event.finishReason === "tool-calls") return;
       if (event.message) ctx.thread.post(event.message);
     },
-    "session.failed"(event, ctx) {
+    "session.failed"(_event, ctx) {
       ctx.thread.post("Something went wrong.");
     },
   },
@@ -194,8 +194,8 @@ export default slackChannel({
   webhook side via `waitUntil`, so the channel returns `200 OK` to Slack immediately.
 
 `events: { ... }` handlers receive runtime events emitted by the harness after the turn dispatches
-(`turn.started`, `message.completed`, `session.failed`, etc.). They run inside the workflow context,
-not on the inbound webhook side.
+(`turn.started`, `message.completed`, `session.failed`, etc.). They receive `(eventData, ctx)` and
+run inside the workflow context, not on the inbound webhook side.
 
 ### Thread Context
 

package/dist/docs/public/cli-build-and-debugging.md

@@ -77,7 +77,7 @@ When something is wrong:
 
 - `schedules/` are root-only today
 - `agent.ts` no longer owns inbound auth or network policy; those live on the HTTP channel layer
-- runtime helpers such as `getSession()` do not work at module top level
+- runtime helpers on `ctx` (like `ctx.session`) do not work at module top level
 - skill guidance belongs in `skills/`, not in tool descriptions
 
 ## What To Read Next

package/dist/docs/public/faqs.md

@@ -56,12 +56,11 @@ the framework's mechanical invariants.
 
 If you want session data from your own code, there are two supported surfaces:
 
-- **Tools** can read the current session's metadata (sessionId, turn, auth,
-  parent lineage) via `getSession()` from `experimental-ash/context`. This is
+- **Tools** can read the current session's metadata (id, turn, auth,
+  parent lineage) via `ctx.session` from the optional `ctx` parameter on `execute`. This is
   read-only.
-- **Durable context keys + `ContextProvider`** are the supported pattern for
-  reading or writing session-scoped durable state from authored code — see
-  [Session Context](./session-context.md).
+- **`defineState`** is the supported pattern for reading or writing session-scoped durable state
+  from authored code — see [Session Context](./session-context.md).
 
 For the wire-level session lifecycle (creating sessions, streaming events,
 reconnecting by event index) see [Sessions And Streaming](./runs-and-streaming.md).

package/dist/docs/public/hooks.md

@@ -20,7 +20,7 @@ import { defineHook } from "experimental-ash/hooks";
 export default defineHook({
   events: {
     async "session.started"(_event, ctx) {
-      console.info("session started", { sessionId: ctx.session.sessionId });
+      console.info("session started", { sessionId: ctx.session.id });
     },
     async "message.completed"(event) {
       console.info("model finished", { length: event.data.message?.length ?? 0 });
@@ -33,8 +33,7 @@ The slug is the path-relative basename: `agent/hooks/audit.ts` → `"audit"`,
 `agent/hooks/auth/load-profile.ts` → `"auth/load-profile"`.
 
 `defineHook`, `HookDefinition`, and `HookContext` live on
-`experimental-ash/hooks`. Runtime context helpers (`getSession`,
-`getContext`, …) live on `experimental-ash/context`.
+`experimental-ash/hooks`. The `defineState` helper lives on `experimental-ash/context`.
 
 ## Shape
 
@@ -55,16 +54,10 @@ Every handler receives the same `HookContext`:
 interface HookContext {
   readonly agent: { readonly name: string; readonly nodeId?: string };
   readonly channel: { readonly kind?: string; readonly continuationToken?: string };
-  readonly session: { readonly sessionId: string };
-  readonly ash: ContextAccessor;
+  readonly session: { readonly id: string };
 }
 ```
 
-`ctx.ash` is the same `ContextAccessor` tools, providers, and channels use.
-Hooks read and write durable state through `ctx.ash.set(...)` /
-`ctx.ash.get(...)`. The hooks surface deliberately introduces no parallel
-state-patch channel — one `AshContext`, one set of keys.
-
 ### Narrowing tool results
 
 `toolResultFrom` narrows an `action.result` event to a specific authored
@@ -108,11 +101,13 @@ Lifecycle hooks share one signature:
 
 ```ts
 type LifecycleHook = (
-  input: { session: { sessionId: string }; turn: { sequence: number; turnId: string } },
   ctx: HookContext,
 ) => void | { modelContext?: readonly ModelMessage[]; skills?: readonly NamedSkillDefinition[] } | Promise<…>;
 ```
 
+Session and turn metadata are available on `ctx.session`. For example,
+`ctx.session.turn.sequence` gives the current turn sequence number.
+
 `lifecycle.session` runs **once per durable session**, before the first
 model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
 continuations and HITL resumes do not re-fire it.
@@ -130,24 +125,24 @@ lifecycle hook messages.
 
 ```ts
 // agent/hooks/load-profile.ts
-import { ContextKey } from "experimental-ash/context";
+import { defineState } from "experimental-ash/context";
 import { defineHook } from "experimental-ash/hooks";
 import { fetchGithubProfile, type GithubProfile } from "../lib/github";
 
-const GithubProfileKey = new ContextKey<GithubProfile>("myapp.githubProfile");
+const githubProfile = defineState<GithubProfile | null>("myapp.githubProfile", () => null);
 
 export default defineHook({
   lifecycle: {
-    async session(_input, ctx) {
-      const profile = await fetchGithubProfile(ctx.session.sessionId);
-      ctx.ash.set(GithubProfileKey, profile);
+    async session(ctx) {
+      const profile = await fetchGithubProfile(ctx.session.id);
+      githubProfile.update(() => profile);
     },
   },
 });
 ```
 
 The profile is now visible to every tool, provider, and subsequent hook
-through `ctx.ash.get(GithubProfileKey)`.
+through `githubProfile.get()`.
 
 ### Inject ephemeral system text
 
@@ -158,7 +153,7 @@ import { fetchActiveIncident } from "../lib/linear";
 
 export default defineHook({
   lifecycle: {
-    async turn() {
+    async turn(ctx) {
       const incident = await fetchActiveIncident();
       if (incident === null) return;
 
@@ -186,7 +181,7 @@ import { defineHook } from "experimental-ash/hooks";
 
 export default defineHook({
   lifecycle: {
-    async session() {
+    async session(ctx) {
       return {
         skills: [
           {
@@ -216,12 +211,12 @@ import { defineHook } from "experimental-ash/hooks";
 
 export default defineHook({
   lifecycle: {
-    async session(_input, ctx) {
+    async session(ctx) {
       return {
         modelContext: [
           {
             role: "system",
-            content: `Greet the user by name (${await lookupName(ctx.session.sessionId)}).`,
+            content: `Greet the user by name (${await lookupName(ctx.session.id)}).`,
           },
         ],
       };
@@ -247,7 +242,7 @@ import { postToHoneycomb } from "../lib/honeycomb";
 export default defineHook({
   events: {
     async "session.started"(_event, ctx) {
-      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.sessionId });
+      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.id });
     },
     async "message.completed"(event) {
       await postToHoneycomb({ event: "message.completed", payload: event.data });
@@ -282,7 +277,7 @@ in `try`/`catch` — Ash treats a thrown hook as a real failure.
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks
 fire only inside the subagent scope; parent-agent hooks do not fire for
 subagent turns, and subagent hooks see only the subagent's own
-`ctx.ash`.
+context.
 
 ## When to use a hook vs a tool vs a provider
 

package/dist/docs/public/meta.json

@@ -2,20 +2,20 @@
   "pages": [
     "getting-started",
     "---",
-    "project-layout",
     "agent-ts",
-    "context-control",
     "skills",
     "tools",
-    "hooks",
     "human-in-the-loop",
     "sandbox",
     "channels",
-    "auth-and-route-protection",
     "subagents",
     "schedules",
     "connections",
     "---",
+    "project-layout",
+    "context-control",
+    "hooks",
+    "auth-and-route-protection",
     "vercel-deployment",
     "runs-and-streaming",
     "session-context",

package/dist/docs/public/sandbox.md

@@ -31,7 +31,7 @@ import { defineSandbox } from "experimental-ash/sandbox";
 export default defineSandbox({
   async bootstrap({ use }) {
     const sandbox = await use();
-    await sandbox.runCommand("apt-get install -y jq");
+    await sandbox.run({ command: "apt-get install -y jq" });
   },
 });
 ```
@@ -58,7 +58,7 @@ The public lifecycle surface is intentionally small:
   sandbox — creation happens at prewarm time and at first-time session-create, both driven by the
   backend factory's options.
 - `sandbox.resolvePath(path)` — translate a logical `/workspace/...` path into the live filesystem
-- `sandbox.runCommand(command)` — run a shell command inside the sandbox
+- `sandbox.run({ command })` — run a shell command inside the sandbox
 
 `defineSandbox` lives on `experimental-ash/sandbox`.
 
@@ -114,21 +114,20 @@ and `write_file` tools. The runtime name comes from the file stem (here, `repo_s
 ## Using The Sandbox From Authored Code
 
 Any authored runtime function (tool, step, or model callback) can bind a live sandbox handle via
-`getSandbox()`:
+`ctx.getSandbox()`:
 
 ```ts
-import { getSandbox } from "experimental-ash/sandbox";
 import { defineTool } from "experimental-ash/tools";
 import { z } from "zod";
 
 export default defineTool({
   description: "Append an analytics event to the running session log.",
   inputSchema: z.object({ kind: z.string(), payload: z.string() }),
-  async execute({ kind, payload }) {
-    const sandbox = await getSandbox();
-    await sandbox.runCommand(
-      `echo ${JSON.stringify(JSON.stringify({ kind, payload }))} >> /var/lib/analytics/events.log`,
-    );
+  async execute({ kind, payload }, ctx) {
+    const sandbox = await ctx.getSandbox();
+    await sandbox.run({
+      command: `echo ${JSON.stringify(JSON.stringify({ kind, payload }))} >> /var/lib/analytics/events.log`,
+    });
     return { ok: true };
   },
 });
@@ -136,7 +135,7 @@ export default defineTool({
 
 Important rules:
 
-- `getSandbox()` takes no arguments and is async.
+- `ctx.getSandbox()` takes no arguments and is async.
 - It only works inside authored runtime execution.
 - Visibility is node-local: the root agent sees the root agent's sandbox; a local subagent sees its
   own sandbox, not the parent's.
@@ -144,7 +143,7 @@ Important rules:
 ### Workspace Paths
 
 Every backend runs `bash` with `/workspace` as the working directory. `readFile(...)`,
-`writeFile(...)`, and `runCommand(...)` all share that single namespace — `/workspace/foo` refers
+`writeFile(...)`, and `run(...)` all share that single namespace — `/workspace/foo` refers
 to the same file whether the backend is local or Vercel.
 
 `sandbox.resolvePath(...)` anchors a sandbox-relative path to `/workspace` and returns the
@@ -154,15 +153,15 @@ Use it when you need an absolute path to interpolate into a generated command or
 hardcoding `/workspace/` yourself:
 
 ```ts
-const sandbox = await getSandbox();
+const sandbox = await ctx.getSandbox();
 const analysisRoot = sandbox.resolvePath("python-analysis");
 
 await sandbox.writeFile("python-analysis/run.py", "print('ok')\n");
-await sandbox.runCommand(`python ${JSON.stringify(`${analysisRoot}/run.py`)}`);
+await sandbox.run({ command: `python ${JSON.stringify(`${analysisRoot}/run.py`)}` });
 ```
 
 `readFile(...)` and `writeFile(...)` apply the same anchoring internally, so you only need to
-call `resolvePath(...)` explicitly when building paths for `runCommand(...)` or returning them
+call `resolvePath(...)` explicitly when building paths for `run(...)` or returning them
 from authored helpers.
 
 ## Subagents Get Their Own Sandbox
@@ -176,7 +175,7 @@ different skills, so they should not inherit the parent's filesystem.
   with that workspace seeded in.
 - If a subagent authors neither, the framework default is used as-is.
 
-Inside a subagent's authored code, `getSandbox()` binds to the subagent's own sandbox.
+Inside a subagent's authored code, `ctx.getSandbox()` binds to the subagent's own sandbox.
 
 ## Lifecycle Semantics
 
@@ -210,18 +209,17 @@ returned. The accepted option shape is whatever the backend's update call accept
 factory; `onSession`'s `use()` overrides any overlapping fields post-create.
 
 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
+read `ctx.session` and derive the current principal without baking credentials into the reusable
 template:
 
 ```ts
-import { getSession } from "experimental-ash/context";
 import { defineSandbox, vercelBackend } from "experimental-ash/sandbox";
 
 export default defineSandbox({
   backend: vercelBackend(),
-  async onSession({ use }) {
+  async onSession({ use, ctx }) {
     const sandbox = await use({ networkPolicy: "deny-all" });
-    const user = getSession().auth.current;
+    const user = ctx.session.auth.current;
     if (user === null) return;
 
     await sandbox.writeFile(
@@ -236,7 +234,8 @@ export default defineSandbox({
 
 Ash ships two built-in backends, exposed as factory functions from `experimental-ash/sandbox`:
 
-- `vercelBackend(opts?)` — runs the sandbox on Vercel Sandbox via `@vercel/sandbox`.
+- `vercelBackend(opts?)` — runs the sandbox on [Vercel Sandbox](https://vercel.com/docs/sandbox) via
+  [`@vercel/sandbox`](https://vercel.com/docs/sandbox/sdk-reference).
 - `localBackend(opts?)` — runs the sandbox locally via `just-bash`. Default for `pnpm ash dev`.
 
 Attach a backend via `defineSandbox({ backend })`:
@@ -249,7 +248,7 @@ export default defineSandbox({
   backend: vercelBackend({ runtime: "node24", resources: { vcpus: 2 } }),
   async bootstrap({ use }) {
     const sandbox = await use();
-    await sandbox.runCommand("git clone https://example.com/repo.git repo");
+    await sandbox.run({ command: "git clone https://example.com/repo.git repo" });
   },
   async onSession({ use }) {
     await use({ networkPolicy: "deny-all" });
@@ -282,9 +281,10 @@ The factory `opts` parameter is forwarded to the underlying SDK's `Sandbox.creat
 every fresh sandbox the framework creates — both the template at prewarm time and the session at
 first-time session-create.
 
-On resume (when the framework reattaches to an existing persistent session via `Sandbox.get`), no
-`Sandbox.create` call happens, so the factory opts are not re-applied. The existing sandbox keeps
-whatever configuration it had from its prior creation.
+On resume (when the framework reattaches to an existing
+[persistent](#session-persistence-and-resume) session via `Sandbox.get`), no `Sandbox.create` call
+happens, so the factory opts are not re-applied. The existing sandbox keeps whatever configuration
+it had from its prior creation.
 
 Lifecycle hooks remain update-time and override post-create:
 
@@ -361,9 +361,8 @@ lock down via `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 the sandbox survives across workflow step boundaries. Set
-a different default on the factory, or override per-session in `onSession`:
+Sandbox VMs shut down after a configurable timeout. Ash defaults to **30 minutes**. Set a different
+value on the factory, or override per-session in `onSession`:
 
 ```ts
 // factory default — applies to every fresh sandbox
@@ -376,7 +375,28 @@ async onSession({ use }) {
 ```
 
 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.
+Hobby. When the timeout fires, the VM shuts down — but because sessions are
+[persistent](#session-persistence-and-resume), the filesystem state is preserved and the sandbox
+resumes automatically on the next request.
+
+### Session Persistence and Resume
+
+Sandbox sessions are **persistent by default**: when the VM shuts down (timeout or inactivity), the
+filesystem state is preserved. The next time a message arrives — even days or weeks later — the
+sandbox automatically resumes from that state.
+
+This means:
+
+- A user can send a message days after the last interaction and pick up where they left off.
+  Files created during earlier turns, installed dependencies, and workspace state are all preserved.
+- The resume is transparent to your code — no configuration is required.
+- If a sandbox has been deleted (by cleanup policies or manual deletion), Ash creates a fresh
+  session from the prewarmed template snapshot. The user gets a clean sandbox seeded with framework
+  defaults, bootstrap output, and workspace files — but any session-specific state from prior turns
+  is lost.
+
+See the [Vercel Sandbox documentation](https://vercel.com/docs/sandbox) for details on persistence
+behavior and plan-specific retention limits.
 
 ### Tags
 
@@ -386,8 +406,7 @@ Ash attaches Vercel Sandbox tags for runtime attribution:
 - `channel` — the active channel adapter kind
 - `sessionId` — the Ash session id
 
-Custom tags can be set on the factory (applied at every fresh `Sandbox.create`) or via
-`onSession`'s `use()` (applied via `sandbox.update`):
+Custom tags can be set on the factory or via `onSession`'s `use()`:
 
 ```ts
 backend: vercelBackend({ tags: { team: "infra" } });
@@ -425,3 +444,5 @@ Important behavior:
 - [Tools](./tools.md)
 - [Workspace](./workspace.md)
 - [Session Context](./session-context.md)
+- [Vercel Sandbox](https://vercel.com/docs/sandbox) — platform documentation for Vercel Sandbox
+- [Vercel Sandbox SDK Reference](https://vercel.com/docs/sandbox/sdk-reference) — `@vercel/sandbox` API reference