experimental-ash 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # experimental-ash
 
+## 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/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
+`getSession().auth.current.attributes`.
+
 ### `none`
 
 Returns a synthetic anonymous `SessionAuthContext`. Use as the final entry in `auth` to accept

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`.
 
@@ -126,9 +126,9 @@ export default defineTool({
   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`,
-    );
+    await sandbox.run({
+      command: `echo ${JSON.stringify(JSON.stringify({ kind, payload }))} >> /var/lib/analytics/events.log`,
+    });
     return { ok: true };
   },
 });
@@ -144,7 +144,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
@@ -158,11 +158,11 @@ const sandbox = await 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
@@ -236,7 +236,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 +250,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 +283,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 +363,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 +377,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 +408,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 +446,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

package/dist/docs/public/session-context.md

@@ -65,7 +65,7 @@ Important behavior:
 
 ```ts
 const sandbox = await getSandbox();
-const result = await sandbox.runCommand("pnpm test");
+const result = await sandbox.run({ command: "pnpm test" });
 ```
 
 Important behavior:

package/dist/src/compiled/.vendor-stamp.json

@@ -20,11 +20,11 @@
     "@standard-schema/spec": "1.1.0",
     "turndown": "7.2.4",
     "@vercel/oidc": "3.4.1",
-    "@vercel/sandbox": "2.0.0",
+    "@vercel/sandbox": "2.0.1",
     "@workflow/core": "5.0.0-beta.7",
     "@workflow/errors": "5.0.0-beta.4",
     "zod": "4.4.3",
     "zod-validation-error": "5.0.0"
   },
-  "scriptHash": "d4ce5a47e0f6620d682bfcba879a1eabaa5c61cc9c9cfe24e3a54c38aaf1edb0"
+  "scriptHash": "de60e990328c8664beec98bc5e81625ecdc0cdace1ba8bd8aa267bf9bea29af4"
 }

package/dist/src/compiled/@vercel/sandbox/index.d.ts

@@ -41,6 +41,7 @@ export interface SandboxCreateOptions {
   env?: Record<string, string> | undefined;
   name?: string | undefined;
   networkPolicy?: NetworkPolicy | undefined;
+  onResume?: ((sandbox: Sandbox) => Promise<void>) | undefined;
   persistent?: boolean | undefined;
   ports?: number[] | undefined;
   resources?: { vcpus?: number | undefined } | undefined;
@@ -52,6 +53,13 @@ export interface SandboxCreateOptions {
   timeout?: number | undefined;
 }
 
+export interface SandboxGetOptions {
+  name: string;
+  onResume?: ((sandbox: Sandbox) => Promise<void>) | undefined;
+  resume?: boolean | undefined;
+  signal?: AbortSignal | undefined;
+}
+
 export interface SandboxRunCommandParams {
   args?: readonly string[] | undefined;
   cmd: string;
@@ -95,9 +103,10 @@ export declare class Sandbox {
   status: string;
   tags?: Record<string, string> | undefined;
   static create(options?: SandboxCreateOptions): Promise<Sandbox>;
-  static get(options: { name: string } | Record<string, unknown>): Promise<Sandbox>;
+  static get(options: SandboxGetOptions): Promise<Sandbox>;
   domain(port: number): string;
-  readFileToBuffer(input: { path: string }): Promise<Buffer | Uint8Array | null>;
+  readFile(file: { path: string }): Promise<ReadableStream<Uint8Array> | null>;
+  readFileToBuffer(file: { path: string }): Promise<Buffer | null>;
   runCommand(input: SandboxRunCommandParams & { detached: true }): Promise<SandboxCommand>;
   runCommand(input: SandboxRunCommandParams): Promise<SandboxCommandFinished>;
   snapshot(options?: unknown): Promise<{ snapshotId: string }>;