@opencoredev/sandbox-sdk 0.1.1 → 1.0.0-beta.0

package/dist/types.d.ts

@@ -0,0 +1,189 @@
+import type { Capability, CreateInput, FileInfo, Labels, OutputChunk, Provider, SandboxInfo, Terminal, Preview } from "./provider.js";
+import type { Files } from "./files.js";
+import type { Git } from "./git.js";
+import type { ProcessHandle, ProcessInfo, StartOptions } from "./processes.js";
+/** Your own key-to-ID store (Redis, a database row) so `createSandbox({ key })` finds the same sandbox from any server. */
+export interface Locator {
+    /** Return the sandbox ID stored for `key`, or `undefined`/`null` when there is none. */
+    get(key: string): Promise<string | undefined | null>;
+    /** Store the sandbox ID for `key`. Called after every create or lookup. */
+    set(key: string, id: string): Promise<void>;
+    /** Forget `key`. Called by `destroy()`. */
+    delete?(key: string): Promise<void>;
+    /** Run `action` while holding a distributed lock on `key`. Required for cross-host exactness with a best-effort provider. */
+    withLock?<T>(key: string, action: () => Promise<T>): Promise<T>;
+}
+/** Options for `createSandbox`. Every field is optional. */
+export interface CreateOptions extends Omit<CreateInput, "labels"> {
+    /** Your own tags. `listSandboxes` and `reapSandboxes` filter on them. The `sandbox-sdk` label is reserved. */
+    labels?: Record<string, string>;
+    /** Environment variables that are redacted from output, errors, and agent tool results. Names must be valid shell identifiers. */
+    secrets?: Record<string, string>;
+    /** Advanced. External key store used with `key`. Most apps only need `key`. */
+    locator?: Locator;
+    /** Advanced. `"exact"` refuses to run unless one sandbox per key is guaranteed (a provider with unique names, or `locator.withLock`). Default: best effort. */
+    keyMode?: "exact" | "best-effort";
+    /** Record a "start" checkpoint at create so `files.changes()` works without `since`. Costs one exec. */
+    trackChanges?: boolean;
+}
+/** Options for `connectSandbox`. */
+export type ConnectOptions = Pick<CreateOptions, "secrets">;
+/** Options for `listSandboxes`. */
+export interface ListOptions {
+    /** Only return sandboxes that carry every one of these labels. */
+    labels?: Labels;
+}
+/** Options for `reapSandboxes`. */
+export interface ReapOptions extends ListOptions {
+    /** Only destroy sandboxes at least this old, in milliseconds. Default: 0. */
+    olderThanMs?: number;
+    /** Skip sandboxes with an active SDK command or a running background process. */
+    idleOnly?: boolean;
+}
+/** Per-command options for `box.run`. */
+export interface RunOptions {
+    /** Working directory. Relative paths resolve against `/workspace`. Default: `/workspace`. */
+    cwd?: string;
+    /** Extra environment variables for this command only. */
+    env?: Record<string, string>;
+    /** Kill the command after this many milliseconds and resolve with `timedOut: true`. Default: 120000. */
+    timeoutMs?: number;
+    /** Keep at most this many bytes per stream; older output is dropped and `truncated` is set. Default: 1048576 (1 MB). */
+    maxOutputBytes?: number;
+    /** Text written to the command's stdin, which is then closed. */
+    stdin?: string;
+    /** Abort the command. It resolves with a result rather than throwing. */
+    signal?: AbortSignal;
+}
+/** The outcome of a finished command. A non-zero exit, a timeout, or an abort is a result, not an error. */
+export interface RunResult {
+    /** `true` when the command exited with code 0. */
+    ok: boolean;
+    /** Exit code, or `null` when the command was killed (timeout or abort). */
+    exitCode: number | null;
+    /** Standard output, with secrets redacted. */
+    stdout: string;
+    /** Standard error, with secrets redacted. */
+    stderr: string;
+    /** stdout and stderr interleaved in arrival order. */
+    output: string;
+    /** Wall-clock time of the command, in milliseconds. */
+    durationMs: number;
+    /** `true` when output exceeded `maxOutputBytes` and the oldest bytes were dropped. */
+    truncated: boolean;
+    /** `true` when `timeoutMs` ran out and the command was killed. */
+    timedOut: boolean;
+    /** Absolute working directory the command ran in. */
+    cwd: string;
+    /** The command as it was sent to the shell. */
+    command: string;
+}
+/**
+ * A lazy command. Nothing runs until you `await` it (for the {@link RunResult})
+ * or iterate it with `for await` (for live {@link OutputChunk}s).
+ * Chain `cwd`, `env`, or `timeout` before starting it.
+ */
+export interface RunHandle extends PromiseLike<RunResult>, AsyncIterable<OutputChunk> {
+    /** Run in this directory. */
+    cwd(path: string): RunHandle;
+    /** Add environment variables for this command. */
+    env(env: Record<string, string>): RunHandle;
+    /** Set the timeout in milliseconds. */
+    timeout(timeoutMs: number): RunHandle;
+}
+/** Options for `box.preview`. */
+export interface PreviewOptions {
+    /** Path appended to the preview URL. */
+    path?: string;
+    /** Wait up to this many milliseconds for the URL to answer with a 2xx. Fails with `port_not_ready` when it runs out. */
+    waitMs?: number;
+}
+/** Counters from `box.usage()`. Providers may add their own numeric fields. */
+export type Usage = {
+    /** When the sandbox was created, in epoch milliseconds. */
+    createdAt: number;
+    /** Milliseconds since `createdAt`. */
+    runningMs: number;
+    /** Commands run through this handle. */
+    commands: number;
+    /** Output bytes received through this handle. */
+    bytesOut: number;
+} & Record<string, number>;
+/** The methods every sandbox has, whatever the provider. `N` is the provider's native client type. */
+export interface SandboxBase<N> {
+    /** The provider's sandbox ID. Pass it to `connectSandbox` to reattach. */
+    readonly id: string;
+    /** The key passed to `createSandbox`, when there was one. */
+    readonly key?: string;
+    /** Provider name, such as `"e2b"`. */
+    readonly provider: string;
+    /** `true` when this call created the sandbox, `false` when it reattached to an existing one. */
+    readonly created: boolean;
+    /** Labels on the sandbox. */
+    readonly labels: Record<string, string>;
+    /** What this provider supports. The optional methods on {@link Sandbox} follow it. */
+    readonly capabilities: ReadonlySet<Capability>;
+    /** The provider's own SDK object, fully typed, for anything this SDK does not cover. */
+    readonly native: N;
+    /** Run a shell command. Await the handle for the result, or iterate it to stream output. */
+    run(command: string, options?: RunOptions): RunHandle;
+    /** Run a command from a template literal. Every interpolated value is shell-quoted. */
+    $(strings: TemplateStringsArray, ...values: unknown[]): RunHandle;
+    /** Read, write, edit, search, and sync files. Relative paths resolve against `/workspace`. */
+    readonly files: Files;
+    /** Git helpers that run inside the sandbox. Tokens never reach argv, env, or shell history. */
+    readonly git: Git;
+    /** Start a named background process and optionally wait until it is ready. The name lets any client find it again with {@link process}; without one, the name is derived from the command and returned on the handle. */
+    start(command: string, options?: StartOptions): Promise<ProcessHandle>;
+    /** Get a handle to a background process by name, including one started by another client. */
+    process(name: string): ProcessHandle;
+    /** List the background processes started through the SDK. */
+    processes(): Promise<ProcessInfo[]>;
+    /** Get a URL for a port in the sandbox. Send the returned `headers` with every request. */
+    preview(port: number, options?: PreviewOptions): Promise<Preview>;
+    /** Counters for this handle, plus provider metrics when available. */
+    usage(): Promise<Usage>;
+    /** Detach this handle and leave the sandbox running. Reattach later with the key or ID. */
+    close(): Promise<void>;
+    /** Delete the sandbox. */
+    destroy(): Promise<void>;
+    /** For `await using`: calls `close()` when the sandbox has a key, otherwise `destroy()`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** The methods each optional capability adds to a sandbox. */
+export interface CapabilityMethods {
+    pause: {
+        /** Pause the sandbox. Billing and the hard lifetime depend on the provider. */
+        pause(): Promise<void>;
+        /** Resume a paused sandbox. */
+        resume(): Promise<void>;
+    };
+    snapshot: {
+        /** Save the sandbox state. Pass the returned `id` as `createSandbox(provider, { from: id })`. */
+        snapshot(): Promise<{
+            id: string;
+        }>;
+    };
+    terminal: {
+        /** Open an interactive PTY. */
+        terminal(options: {
+            cols: number;
+            rows: number;
+        }): Promise<Terminal>;
+    };
+}
+type MethodCapability = keyof CapabilityMethods;
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
+/** The methods added by the capabilities in `C`. */
+export type MethodsFor<C extends Capability> = [Extract<C, MethodCapability>] extends [never] ? {} : UnionToIntersection<CapabilityMethods[Extract<C, MethodCapability>]>;
+/**
+ * A sandbox handle. `N` is the native client type; `C` is the provider's capability union.
+ * With a concrete provider, `pause`/`resume`, `snapshot`, and `terminal` exist only when
+ * `C` includes them, so calling one on a provider that lacks it is a type error. With a
+ * provider typed as plain `Provider` (any capability), the methods are optional: check
+ * them with {@link hasCapability} first. `createSandbox(e2b())` infers the precise type.
+ */
+export type Sandbox<N = unknown, C extends Capability = never> = SandboxBase<N> & (Capability extends C ? Partial<MethodsFor<MethodCapability>> : MethodsFor<C>);
+/** The sandbox type a provider produces: `ProviderSandbox<ReturnType<typeof e2b>>`. */
+export type ProviderSandbox<P extends Provider> = P extends Provider<infer N, infer C> ? Sandbox<N, C> : never;
+export type { OutputChunk, Capability, SandboxInfo, FileInfo, Labels, Preview, Terminal };

package/package.json

@@ -1,151 +1,229 @@
 {
   "name": "@opencoredev/sandbox-sdk",
-  "version": "0.1.1",
-  "description": "One TypeScript SDK for every sandbox provider.",
+  "version": "1.0.0-beta.0",
+  "description": "One TypeScript API for cloud and local sandboxes: E2B, Daytona, Vercel, Upstash, Docker, and more. Run commands, edit files, start servers, and give AI agents a sandbox.",
+  "keywords": [
+    "sandbox",
+    "code-execution",
+    "ai-agents",
+    "agent-tools",
+    "e2b",
+    "daytona",
+    "vercel-sandbox",
+    "upstash",
+    "docker",
+    "microvm",
+    "ai-sdk",
+    "mastra",
+    "openai-agents",
+    "typescript"
+  ],
   "homepage": "https://sandbox-sdk.app",
-  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/opencoredev/sandbox-sdk/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/opencoredev/sandbox-sdk.git",
     "directory": "packages/sdk"
   },
+  "license": "MIT",
+  "author": "OpenCore",
+  "type": "module",
+  "sideEffects": false,
   "files": [
     "dist",
     "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
-  "type": "module",
-  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.mts",
-      "import": "./dist/index.mjs"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "./local": {
-      "types": "./dist/providers/local/index.d.mts",
-      "import": "./dist/providers/local/index.mjs"
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "default": "./dist/provider.js"
     },
-    "./agentos": {
-      "types": "./dist/providers/agentos/index.d.mts",
-      "import": "./dist/providers/agentos/index.mjs"
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "default": "./dist/memory.js"
     },
-    "./e2b": {
-      "types": "./dist/providers/e2b/index.d.mts",
-      "import": "./dist/providers/e2b/index.mjs"
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     },
-    "./daytona": {
-      "types": "./dist/providers/daytona/index.d.mts",
-      "import": "./dist/providers/daytona/index.mjs"
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "default": "./dist/tools.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "default": "./dist/ai.js"
+    },
+    "./mastra": {
+      "types": "./dist/mastra.d.ts",
+      "default": "./dist/mastra.js"
+    },
+    "./openai": {
+      "types": "./dist/openai.d.ts",
+      "default": "./dist/openai.js"
+    },
+    "./local": {
+      "types": "./dist/providers/local/index.d.ts",
+      "default": "./dist/providers/local/index.js"
+    },
+    "./e2b": {
+      "types": "./dist/providers/e2b/index.d.ts",
+      "default": "./dist/providers/e2b/index.js"
     },
     "./vercel": {
-      "types": "./dist/providers/vercel/index.d.mts",
-      "import": "./dist/providers/vercel/index.mjs"
+      "types": "./dist/providers/vercel/index.d.ts",
+      "default": "./dist/providers/vercel/index.js"
+    },
+    "./daytona": {
+      "types": "./dist/providers/daytona/index.d.ts",
+      "default": "./dist/providers/daytona/index.js"
     },
     "./upstash": {
-      "types": "./dist/providers/upstash/index.d.mts",
-      "import": "./dist/providers/upstash/index.mjs"
+      "types": "./dist/providers/upstash/index.d.ts",
+      "default": "./dist/providers/upstash/index.js"
     },
-    "./metadata": {
-      "types": "./dist/metadata.d.mts",
-      "import": "./dist/metadata.mjs"
+    "./railway": {
+      "types": "./dist/providers/railway/index.d.ts",
+      "default": "./dist/providers/railway/index.js"
     },
-    "./testing": {
-      "types": "./dist/testing/index.d.mts",
-      "import": "./dist/testing/index.mjs"
+    "./boat": {
+      "types": "./dist/providers/boat/index.d.ts",
+      "default": "./dist/providers/boat/index.js"
     },
-    "./ai": {
-      "types": "./dist/ai/index.d.mts",
-      "import": "./dist/ai/index.mjs"
+    "./sandboxer": {
+      "types": "./dist/providers/sandboxer/index.d.ts",
+      "default": "./dist/providers/sandboxer/index.js"
     },
-    "./ai/harness": {
-      "types": "./dist/ai/harness.d.mts",
-      "import": "./dist/ai/harness.mjs"
+    "./tenki": {
+      "types": "./dist/providers/tenki/index.d.ts",
+      "default": "./dist/providers/tenki/index.js"
     },
-    "./eve": {
-      "types": "./dist/eve/index.d.mts",
-      "import": "./dist/eve/index.mjs"
+    "./agentos": {
+      "types": "./dist/providers/agentos/index.d.ts",
+      "default": "./dist/providers/agentos/index.js"
     },
-    "./mastra": {
-      "types": "./dist/mastra/index.d.mts",
-      "import": "./dist/mastra/index.mjs"
-    }
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
+    "./boxd": {
+      "types": "./dist/providers/boxd/index.d.ts",
+      "default": "./dist/providers/boxd/index.js"
+    },
+    "./freestyle": {
+      "types": "./dist/providers/freestyle/index.d.ts",
+      "default": "./dist/providers/freestyle/index.js"
+    },
+    "./superserve": {
+      "types": "./dist/providers/superserve/index.d.ts",
+      "default": "./dist/providers/superserve/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsdown",
-    "prepack": "bun run build",
-    "dev": "tsdown --watch src",
-    "lint": "oxlint src tests examples",
+    "build": "bun scripts/build.ts && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "bun test tests --parallel=1 --timeout=15000",
-    "test:live": "bun test tests/live",
-    "test:live:ai-gateway": "bun scripts/run-ai-gateway-live.ts local",
-    "test:live:ai-gateway:vercel": "bun scripts/run-ai-gateway-live.ts vercel",
-    "test:live:e2b": "bun test tests/live/e2b.test.ts",
-    "test:live:daytona": "bun test tests/live/daytona.test.ts",
-    "test:live:integrations": "bun test tests/live/integrations.test.ts",
-    "test:live:mastra": "bun test tests/live/mastra.test.ts",
-    "test:live:vercel": "bun test tests/live/vercel.test.ts",
-    "test:live:upstash": "bun test tests/live/upstash.test.ts"
-  },
-  "dependencies": {
-    "@rivet-dev/agentos-core": "^0.2.7"
+    "lint": "oxlint src tests scripts",
+    "test": "timeout 120s vitest run --maxWorkers=4 && bun scripts/size.ts",
+    "check:size": "bun scripts/size.ts",
+    "smoke:consumer": "timeout 900s bun scripts/consumer-smoke.ts"
   },
   "devDependencies": {
-    "@ai-sdk/harness": "^1",
-    "@daytona/sdk": "^0.196.0",
-    "@mastra/core": "1.51.0",
-    "@types/bun": "^1.3.14",
-    "@types/node": "^22.13.14",
-    "@upstash/box": "0.5.3",
-    "@vercel/sandbox": "^2.5.0",
-    "ai": "^7",
-    "e2b": "^2.32.0",
-    "eve": "^0.22",
-    "tsdown": "^0.16.6",
-    "typescript": "^6.0.3"
+    "@boatdev/sdk": "1.9.9",
+    "@boxd-sh/sdk": "0.2.17",
+    "@daytonaio/sdk": "^0.225.0",
+    "@mastra/core": "^1.78.0",
+    "@openai/agents": "^0.20.0",
+    "@rivet-dev/agentos-core": "0.4.1",
+    "@tenkicloud/sandbox": "^1.4.1",
+    "@upstash/box": "^0.7.9",
+    "@vercel/sandbox": "3.8.0",
+    "ai": "^7.0.143",
+    "e2b": "2.56.0",
+    "freestyle": "0.2.20",
+    "railway": "3.16.0",
+    "vitest": "^3.2.4",
+    "zod": "^4.6.7",
+    "@superserve/sdk": "0.11.4"
   },
   "peerDependencies": {
-    "@ai-sdk/harness": "^1.0.0",
-    "@daytona/sdk": "^0.196.0",
-    "@mastra/core": ">=1.12.0-0 <2.0.0-0",
-    "@upstash/box": "^0.5.3",
-    "@vercel/sandbox": "^2.5.0",
-    "ai": "^7.0.0",
-    "e2b": "^2.32.0",
-    "eve": "^0.22.0"
+    "@daytonaio/sdk": "^0.225.0",
+    "@mastra/core": "^1.78.0",
+    "@openai/agents": "^0.20.0",
+    "@upstash/box": "^0.7.9",
+    "@vercel/sandbox": "^3.8.0",
+    "ai": "^7.0.143",
+    "e2b": "^2.56.0",
+    "vitest": ">=3",
+    "zod": "^4.6.7",
+    "railway": "^3.16.0",
+    "@boatdev/sdk": "^1.9.9",
+    "@tenkicloud/sandbox": "^1.4.1",
+    "@rivet-dev/agentos-core": "0.4.1",
+    "@boxd-sh/sdk": "^0.2.17",
+    "freestyle": "^0.2.20",
+    "@superserve/sdk": "^0.11.4"
   },
   "peerDependenciesMeta": {
-    "e2b": {
+    "vitest": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "@mastra/core": {
       "optional": true
     },
-    "@daytona/sdk": {
+    "@openai/agents": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "e2b": {
       "optional": true
     },
     "@vercel/sandbox": {
       "optional": true
     },
+    "@daytonaio/sdk": {
+      "optional": true
+    },
     "@upstash/box": {
       "optional": true
     },
-    "ai": {
+    "railway": {
       "optional": true
     },
-    "@ai-sdk/harness": {
+    "@boatdev/sdk": {
       "optional": true
     },
-    "@mastra/core": {
+    "@tenkicloud/sandbox": {
+      "optional": true
+    },
+    "@rivet-dev/agentos-core": {
+      "optional": true
+    },
+    "@boxd-sh/sdk": {
+      "optional": true
+    },
+    "freestyle": {
       "optional": true
     },
-    "eve": {
+    "@superserve/sdk": {
       "optional": true
     }
   },
   "engines": {
-    "node": ">=22 <26"
+    "bun": ">=1.3",
+    "node": ">=22"
   }
 }