experimental-ash 0.18.3 → 0.19.0

package/dist/src/public/sandbox/backends/local.js

@@ -7,10 +7,12 @@ import { createLocalSandboxBackend } from "#execution/sandbox/bindings/local.js"
  * under the application root. It is the default backend on developer
  * machines (`pnpm ash dev`).
  *
- * Takes no arguments today — `just-bash` does not currently expose any
- * configuration that's worth surfacing through ash. New options would
- * be added here as the underlying runtime grows.
+ * Accepts an `opts` parameter for parity with other backends, but
+ * `LocalSandboxCreateOptions` is empty today — `just-bash` does not
+ * currently expose any configuration worth surfacing. New options would
+ * be added by widening `LocalSandboxCreateOptions` and routing them
+ * into the binding without changing this signature.
  */
-export function localBackend() {
-    return createLocalSandboxBackend();
+export function localBackend(opts) {
+    return createLocalSandboxBackend({ createOptions: opts });
 }

package/dist/src/public/sandbox/backends/vercel.d.ts

@@ -1,11 +1,17 @@
 import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
-import type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
+import type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, VercelSandboxSessionUseOptions } from "#public/sandbox/vercel-sandbox.js";
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
+ * The optional `opts` parameter is forwarded to the Vercel SDK's
+ * `Sandbox.create(...)` for every fresh sandbox the framework creates
+ * (template at prewarm, session at first-time create). On resume
+ * (`Sandbox.get`), no create happens, so opts are not re-applied.
+ *
  * `bootstrap({ use })` applies its options to the template via
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the
- * SDK's `update` under the hood.
+ * SDK's `update` under the hood — overriding any overlapping field
+ * from `opts`.
  */
-export declare function vercelBackend(): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;
+export declare function vercelBackend(opts?: VercelSandboxCreateOptions): SandboxBackend<VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions>;

package/dist/src/public/sandbox/backends/vercel.js

@@ -2,11 +2,17 @@ import { createVercelSandboxBackend } from "#execution/sandbox/bindings/vercel.j
 /**
  * Constructs the built-in Vercel sandbox backend.
  *
+ * The optional `opts` parameter is forwarded to the Vercel SDK's
+ * `Sandbox.create(...)` for every fresh sandbox the framework creates
+ * (template at prewarm, session at first-time create). On resume
+ * (`Sandbox.get`), no create happens, so opts are not re-applied.
+ *
  * `bootstrap({ use })` applies its options to the template via
  * `sandbox.update(...)`; those settings persist into the snapshot.
  * `onSession({ use })` applies its options to the live session via the
- * SDK's `update` under the hood.
+ * SDK's `update` under the hood — overriding any overlapping field
+ * from `opts`.
  */
-export function vercelBackend() {
-    return createVercelSandboxBackend();
+export function vercelBackend(opts) {
+    return createVercelSandboxBackend({ createOptions: opts });
 }

package/dist/src/public/sandbox/index.d.ts

@@ -9,4 +9,5 @@ export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-
 export { defaultBackend } from "#public/sandbox/backends/default.js";
 export { localBackend } from "#public/sandbox/backends/local.js";
 export { vercelBackend } from "#public/sandbox/backends/vercel.js";
-export type { VercelSandboxBootstrapUseOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";
+export type { LocalSandboxCreateOptions } from "#public/sandbox/local-sandbox.js";
+export type { VercelSandboxBootstrapUseOptions, VercelSandboxCreateOptions, VercelSandboxSessionUseOptions, } from "#public/sandbox/vercel-sandbox.js";

package/dist/src/public/sandbox/local-sandbox.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Options accepted by `localBackend(opts)`. Reserved for future
+ * widening: today the local backend exposes no consumer-controllable
+ * create options, so this is an empty object. The parameter exists on
+ * the factory so adding real fields here later is purely additive.
+ */
+export type LocalSandboxCreateOptions = Record<string, never>;

package/dist/src/public/sandbox/local-sandbox.js

@@ -0,0 +1 @@
+export {};

package/dist/src/public/sandbox/vercel-sandbox.d.ts

@@ -1,4 +1,16 @@
-import type { SandboxUpdateParams } from "#compiled/@vercel/sandbox/index.js";
+import type { Sandbox as SdkSandbox, SandboxUpdateParams } from "#compiled/@vercel/sandbox/index.js";
+/**
+ * Options accepted by `vercelBackend(opts)`. Forwarded directly to the
+ * Vercel SDK's `Sandbox.create(...)` for every fresh sandbox the
+ * framework creates (template at prewarm time, session at first-time
+ * session-create). Skipped on resume (`Sandbox.get`) since no create
+ * happens there.
+ *
+ * Framework-injected fields (`name`, `persistent`, `source`, `signal`)
+ * are excluded — the framework owns those and overrides any author-
+ * supplied values.
+ */
+export type VercelSandboxCreateOptions = Omit<NonNullable<Parameters<typeof SdkSandbox.create>[0]>, "name" | "persistent" | "source" | "signal">;
 /**
  * Options accepted by the Vercel backend's `bootstrap({ use })` hook.
  * Aliases the Vercel SDK's `SandboxUpdateParams` because bootstrap

package/dist/src/runtime/resolve-sandbox.js

@@ -1,3 +1,4 @@
+import { lazyBackend } from "#execution/sandbox/lazy-backend.js";
 import { expectObjectRecord } from "#internal/authored-module.js";
 import { defaultBackend } from "#public/sandbox/backends/default.js";
 import { toErrorMessage } from "#shared/errors.js";
@@ -47,8 +48,11 @@ function resolveBackend(value, logicalPath) {
     if (value === undefined) {
         return defaultBackend();
     }
+    if (typeof value === "function") {
+        return lazyBackend(value);
+    }
     if (typeof value !== "object" || value === null) {
-        throw new ResolveAgentError(`Sandbox "${logicalPath}" exposed a non-object "backend" field. Use vercelBackend(), localBackend(), or another factory that returns a SandboxBackend value.`, { logicalPath });
+        throw new ResolveAgentError(`Sandbox "${logicalPath}" exposed a non-object "backend" field. Use vercelBackend(), localBackend(), another factory that returns a SandboxBackend value, or a zero-arg callback returning one.`, { logicalPath });
     }
     const record = value;
     if (typeof record.name !== "string" || record.name.length === 0) {

package/dist/src/runtime/types.d.ts

@@ -15,6 +15,7 @@ import type { SourceRef, ModuleSourceRef, SkillPackageSourceRef, MarkdownSourceR
 import type { InternalSkillDefinition } from "#shared/skill-definition.js";
 import type { InternalAgentDefinition } from "#shared/agent-definition.js";
 import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";
+import type { SandboxBackend } from "#shared/sandbox-backend.js";
 import type { SandboxDefinition } from "#shared/sandbox-definition.js";
 /**
  * Runtime-owned source ref describing one additive config module import.
@@ -82,7 +83,15 @@ export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {
  * `vercelBackend()` and `localBackend()` based on the current
  * environment).
  */
-export type ResolvedSandboxDefinition = Readonly<SandboxDefinition> & ResolvedModuleSourceRef & {
+export type ResolvedSandboxDefinition = Readonly<Omit<SandboxDefinition, "backend">> & ResolvedModuleSourceRef & {
+    /**
+     * Resolved backend value. The authored `SandboxDefinition.backend`
+     * accepts either a `SandboxBackend` or a `() => SandboxBackend`; by
+     * the time it reaches the runtime the function form has been
+     * unwrapped via `lazyBackend(...)` so consumers always see a plain
+     * value.
+     */
+    readonly backend: SandboxBackend;
     readonly description?: string;
 };
 /**

package/dist/src/shared/sandbox-definition.d.ts

@@ -25,13 +25,28 @@ export interface SandboxDefinition<BO = Record<string, never>, SO = Record<strin
     /**
      * Backend that runs this sandbox.
      *
+     * Accepts either a {@link SandboxBackend} value or a zero-arg factory
+     * function that returns one. The factory form is invoked lazily on
+     * first framework access and the result is memoized for the lifetime
+     * of the process, so backend-internal state (such as the Vercel
+     * backend's prewarmed-template cache) is preserved across every call.
+     * Use the factory form to defer evaluation — for example, when create
+     * options depend on environment variables that aren't set at module
+     * load time:
+     *
+     * ```ts
+     * defineSandbox({
+     *   backend: () => vercelBackend({ env: { TOKEN: process.env.TOKEN ?? "" } }),
+     * });
+     * ```
+     *
      * When this field is omitted, Ash substitutes `defaultBackend()` at
      * runtime, which delegates to `vercelBackend()` on hosted Vercel
      * (where `process.env.VERCEL` is set) and to `localBackend()`
      * everywhere else. Set `backend` explicitly to pin the sandbox to a
      * specific backend regardless of environment.
      */
-    backend: SandboxBackend<BO, SO>;
+    backend: SandboxBackend<BO, SO> | (() => SandboxBackend<BO, SO>);
     bootstrap?(input: SandboxBootstrapContext<BO>): Promise<void> | void;
     onSession?(input: SandboxSessionContext<SO>): Promise<void> | void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"