experimental-ash 0.6.1 → 0.7.0

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

@@ -0,0 +1,124 @@
+import type { SandboxBootstrapContext, SandboxSessionUseFn } from "#shared/sandbox-definition.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+/**
+ * Live sandbox handle returned by a {@link SandboxBackend}.
+ *
+ * Wraps the public {@link SandboxSession} with lifecycle methods so the
+ * runtime orchestrator can persist reconnect metadata and release
+ * resources.
+ */
+export interface SandboxBackendHandle<S extends SandboxSession = SandboxSession> {
+    readonly session: SandboxSession;
+    readonly useSessionFn: SandboxSessionUseFn<S>;
+    captureState(): Promise<SandboxBackendSessionState>;
+    dispose(): Promise<void>;
+}
+/**
+ * Serializable per-sandbox reconnect record stored on the harness session.
+ *
+ * `backendName` matches the {@link SandboxBackend.name} of the backend
+ * that produced this state, and is used by the runtime to decide whether
+ * a previously persisted handle is still compatible with the current
+ * backend.
+ */
+export interface SandboxBackendSessionState {
+    readonly backendName: string;
+    readonly metadata: Record<string, unknown>;
+    readonly sessionKey: string;
+}
+/**
+ * One file written into a sandbox template before snapshot capture.
+ */
+export interface SandboxSeedFile {
+    readonly path: string;
+    readonly content: string | Buffer;
+}
+/**
+ * Diagnostic tags attached to provider-owned sandbox resources.
+ *
+ * Built-in backends may forward these into their hosting platform's
+ * native tagging system. Ash supplies stable tags such as the active
+ * agent, channel, and session id so sandboxes can be found and
+ * attributed in provider dashboards.
+ */
+export type SandboxBackendTags = Readonly<Record<string, string>>;
+/**
+ * Framework-owned runtime context handed to a backend on every
+ * {@link SandboxBackend.create} call.
+ *
+ * Backends use this to derive any per-call state that depends on the
+ * surrounding application — for example, the local backend computes its
+ * cache directory from `appRoot`. Backends that don't need anything
+ * here may ignore the field entirely.
+ */
+export interface SandboxBackendRuntimeContext {
+    readonly appRoot: string;
+}
+/**
+ * Input passed to {@link SandboxBackend.create} when the runtime needs a
+ * live sandbox session.
+ */
+export interface SandboxBackendCreateInput {
+    readonly templateKey: string;
+    readonly sessionKey: string;
+    readonly existingMetadata?: Record<string, unknown>;
+    /**
+     * Runtime tags the backend should attach to sandbox resources when
+     * the underlying provider supports tags.
+     */
+    readonly tags?: SandboxBackendTags;
+    readonly runtimeContext: SandboxBackendRuntimeContext;
+}
+/**
+ * Input passed to {@link SandboxBackend.prewarm} when the build pipeline
+ * is preparing reusable templates.
+ *
+ * Every authored sandbox in the compiled graph receives exactly one
+ * `prewarm(...)` call before runtime opens its first session. The
+ * backend captures a reusable template snapshot from the supplied
+ * `bootstrap` hook and `seedFiles`, then `backend.create(...)` opens
+ * durable sessions from that snapshot.
+ */
+export interface SandboxBackendPrewarmInput {
+    readonly templateKey: string;
+    readonly bootstrap?: (input: SandboxBootstrapContext) => void | Promise<void>;
+    readonly runtimeContext: SandboxBackendRuntimeContext;
+    readonly seedFiles: ReadonlyArray<SandboxSeedFile>;
+}
+/**
+ * Pluggable sandbox backend.
+ *
+ * A `SandboxBackend` is a value an author attaches to a
+ * {@link SandboxDefinition} to choose which underlying runtime hosts the
+ * sandbox. Ash ships two built-in backends — `vercelBackend()` and
+ * `localBackend()` — but the interface is public so authors can write
+ * their own.
+ *
+ * Each backend owns the full template-then-session lifecycle internally;
+ * callers only need a single `create` call.
+ */
+export interface SandboxBackend<S extends SandboxSession = SandboxSession> {
+    /**
+     * Stable identifier for this backend implementation.
+     *
+     * Participates in cache-key derivation and the persisted reconnect
+     * state, so two backends that should not share template snapshots
+     * must use distinct names. Built-in backends use `"vercel"` and
+     * `"local"`. Custom backends pick a unique string.
+     */
+    readonly name: string;
+    /**
+     * Creates or reattaches one live sandbox session from a template
+     * previously captured by {@link SandboxBackend.prewarm}. Throws
+     * {@link SandboxTemplateNotProvisionedError} when the requested
+     * template is missing.
+     */
+    create(input: SandboxBackendCreateInput): Promise<SandboxBackendHandle<S>>;
+    /**
+     * Build-time prewarm hook. Ash invokes this for every authored
+     * sandbox in the compiled graph before serving traffic so the backend
+     * can capture a reusable template snapshot. Idempotent against an
+     * existing snapshot keyed by `templateKey`.
+     */
+    prewarm(input: SandboxBackendPrewarmInput): Promise<void>;
+}

package/dist/src/shared/sandbox-backend.js

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

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

@@ -0,0 +1,72 @@
+import type { SandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxBackend } from "#shared/sandbox-backend.js";
+/**
+ * A transform applied to network requests matching a domain rule.
+ */
+export interface SandboxNetworkTransformer {
+    readonly headers?: Record<string, string>;
+}
+/**
+ * A rule applied to requests matching a domain in the network policy.
+ */
+export interface SandboxNetworkPolicyRule {
+    readonly transform?: SandboxNetworkTransformer[];
+}
+/**
+ * Network policy to define network restrictions for the sandbox.
+ *
+ * - `"allow-all"`: Full internet access (default). All traffic is allowed.
+ * - `"deny-all"`: No internet access. All traffic is denied.
+ * - Object: Custom access with explicit allow/deny lists.
+ */
+export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
+    readonly allow?: string[] | Readonly<Record<string, SandboxNetworkPolicyRule[]>>;
+};
+export interface SandboxBootstrapUseOptions {
+    readonly runtime?: string;
+    readonly ports?: number[];
+    readonly env?: Record<string, string>;
+}
+export interface SandboxSessionUseOptions {
+    readonly networkPolicy?: SandboxNetworkPolicy;
+    readonly resources?: {
+        vcpus?: number;
+    };
+    readonly timeout?: number;
+    readonly tags?: Record<string, string>;
+}
+export type SandboxBootstrapUseFn = (options?: SandboxBootstrapUseOptions) => Promise<SandboxSession>;
+export type SandboxSessionUseFn<S extends SandboxSession = SandboxSession> = (options?: SandboxSessionUseOptions) => Promise<S>;
+export interface SandboxBootstrapContext {
+    readonly use: SandboxBootstrapUseFn;
+}
+export interface SandboxSessionContext<S extends SandboxSession = SandboxSession> {
+    readonly use: SandboxSessionUseFn<S>;
+}
+/**
+ * Public sandbox definition authored in `agent/sandbox.ts` (shorthand)
+ * or `agent/sandbox/sandbox.ts` (folder layout, when paired with an
+ * authored `sandbox/workspace/` subtree).
+ *
+ * Each agent (and each subagent) owns exactly one sandbox. When the
+ * module file is absent the framework auto-provides a default sandbox
+ * via `defaultBackend()`. Authors override lifecycle and backend by
+ * creating `agent/sandbox.ts` (or `agent/sandbox/sandbox.ts` when they
+ * also want a workspace folder); subagents override independently via
+ * `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
+ * their parent's sandbox (skill seeds differ per agent).
+ */
+export interface SandboxDefinition<S extends SandboxSession = SandboxSession> {
+    /**
+     * Backend that runs this sandbox.
+     *
+     * 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<S>;
+    bootstrap?(input: SandboxBootstrapContext): Promise<void> | void;
+    onSession?(input: SandboxSessionContext<S>): Promise<void> | void;
+}

package/dist/src/shared/sandbox-definition.js

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

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

@@ -0,0 +1,95 @@
+import type { Sandbox as AiSdkSandbox } from "ai";
+/**
+ * Options for running a sandbox command.
+ */
+export type SandboxCommandOptions = Readonly<Omit<Parameters<AiSdkSandbox["executeCommand"]>[0], "command">>;
+/**
+ * Serializable result returned after running one sandbox command.
+ */
+export type SandboxCommandResult = Readonly<Awaited<ReturnType<AiSdkSandbox["executeCommand"]>>>;
+/**
+ * Options for reading a text file from a sandbox with optional line ranges.
+ */
+export interface SandboxReadFileOptions {
+    /**
+     * 1-based inclusive end line. When past the file's line count, the read
+     * returns through EOF without error.
+     */
+    readonly endLine?: number;
+    /**
+     * 1-based inclusive start line. Defaults to 1.
+     */
+    readonly startLine?: number;
+}
+/**
+ * Minimal Ash-owned sandbox session exposed to authored lifecycle hooks.
+ */
+export interface SandboxSession {
+    /**
+     * Stable identifier for the backend session this handle wraps.
+     *
+     * Persists across reconnects to the same logical session: two calls
+     * that resume the same underlying backend sandbox observe the same
+     * `id`. Template sessions constructed during bootstrap expose the
+     * template key; live sessions expose the session key assigned by the
+     * runtime. Useful as a cache key for per-session state that must
+     * outlive individual step executions.
+     */
+    readonly id: string;
+    /**
+     * Reads one text file from the sandbox as UTF-8.
+     *
+     * Returns `null` when the file does not exist. Throws when the file
+     * contains invalid UTF-8.
+     *
+     * Relative paths resolve from `/workspace`, the live working directory
+     * for every backend. Absolute paths pass through unchanged.
+     *
+     * Line ranges are 1-based and inclusive. When `endLine` is past EOF the
+     * read returns through EOF without error.
+     */
+    readFile(path: string, options?: SandboxReadFileOptions): Promise<string | null>;
+    /**
+     * Reads one file from the sandbox as raw bytes.
+     *
+     * Returns `null` when the file does not exist. Unlike
+     * {@link SandboxSession.readFile}, this variant performs no UTF-8
+     * decoding and is safe for binary payloads (images, PDFs, archives,
+     * attachment bytes written by the framework at
+     * `/workspace/attachments/...`).
+     *
+     * Relative paths resolve from `/workspace`, the live working
+     * directory for every backend. Absolute paths pass through unchanged.
+     */
+    readFileBytes(path: string): Promise<Buffer | null>;
+    /**
+     * Anchors a sandbox-relative path to `/workspace` and returns the
+     * resulting absolute path.
+     *
+     * Relative paths resolve from `/workspace`; absolute paths pass through.
+     * `readFile(...)` and `writeFile(...)` already apply this internally.
+     */
+    resolvePath(path: string): string;
+    /**
+     * Runs one shell command inside the current sandbox session and returns the
+     * captured stdout, stderr, and exit code.
+     *
+     * Commands execute with `/workspace` as the working directory on every
+     * backend.
+     */
+    runCommand(command: string, options?: SandboxCommandOptions): Promise<SandboxCommandResult>;
+    /**
+     * Writes one file to the sandbox, creating parent directories
+     * recursively and overwriting any existing file.
+     *
+     * `content` accepts a UTF-8 `string` for text files or a `Buffer` for
+     * arbitrary bytes. The framework uses the `Buffer` overload to mount
+     * binary workspace assets (images under skill `assets/` directories,
+     * fixture payloads, and so on) through the same public surface authors
+     * use.
+     *
+     * Relative paths resolve from `/workspace`. Absolute paths pass through
+     * unchanged.
+     */
+    writeFile(path: string, content: string | Buffer): Promise<void>;
+}

package/dist/src/shared/sandbox-session.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -90,10 +90,15 @@
       "import": "./dist/src/public/skills/index.js",
       "default": "./dist/src/public/skills/index.js"
     },
+    "./instructions": {
+      "types": "./dist/src/public/instructions/index.d.ts",
+      "import": "./dist/src/public/instructions/index.js",
+      "default": "./dist/src/public/instructions/index.js"
+    },
     "./system": {
-      "types": "./dist/src/public/system/index.d.ts",
-      "import": "./dist/src/public/system/index.js",
-      "default": "./dist/src/public/system/index.js"
+      "types": "./dist/src/public/instructions/index.d.ts",
+      "import": "./dist/src/public/instructions/index.js",
+      "default": "./dist/src/public/instructions/index.js"
     },
     "./context": {
       "types": "./dist/src/public/context/index.d.ts",
@@ -143,7 +148,7 @@
     "@ai-sdk/google": "4.0.0-canary.53",
     "@ai-sdk/mcp": "2.0.0-canary.41",
     "@ai-sdk/openai": "4.0.0-canary.49",
-    "@ai-sdk/otel": "1.0.0-canary.67",
+    "@ai-sdk/otel": "1.0.0-canary.77",
     "@ai-sdk/provider": "4.0.0-canary.16",
     "@chat-adapter/slack": "^4.27.0",
     "@chat-adapter/state-memory": "^4.27.0",
@@ -154,7 +159,7 @@
     "@workflow/core": "5.0.0-beta.5",
     "@workflow/errors": "5.0.0-beta.2",
     "@workflow/world-local": "5.0.0-beta.4",
-    "ai": "7.0.0-canary.121",
+    "ai": "7.0.0-canary.131",
     "autoevals": "^0.0.132",
     "chat": "^4.27.0",
     "chokidar": "^5.0.0",
@@ -170,7 +175,7 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "ai": "7.0.0-canary.121",
+    "ai": "7.0.0-canary.131",
     "braintrust": ">=3.0.0"
   },
   "peerDependenciesMeta": {