@agentick/sandbox 0.2.1

package/dist/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Sandbox Contract Types
+ *
+ * All types for the sandbox abstraction layer.
+ * Provider adapters (@agentick/sandbox-local, @agentick/sandbox-docker, etc.)
+ * implement SandboxProvider.
+ */
+import type { Edit, EditResult } from "./edit";
+export interface Sandbox {
+    /** Unique sandbox instance ID. */
+    readonly id: string;
+    /** Absolute path to the workspace root inside the sandbox. */
+    readonly workspacePath: string;
+    /** Execute a shell command. */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    /** Read a file from the sandbox filesystem. */
+    readFile(path: string): Promise<string>;
+    /** Write a file to the sandbox filesystem. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Apply surgical edits to a file. */
+    editFile(path: string, edits: Edit[]): Promise<EditResult>;
+    /** Tear down the sandbox and release resources. */
+    destroy(): Promise<void>;
+}
+export interface SandboxProvider {
+    /** Provider name (e.g. "local", "docker", "e2b"). */
+    readonly name: string;
+    /** Create a new sandbox instance. */
+    create(options: SandboxCreateOptions): Promise<Sandbox>;
+    /** Restore a sandbox from a snapshot. */
+    restore?(snapshot: SandboxSnapshot): Promise<Sandbox>;
+    /** Destroy a sandbox (provider-level cleanup). */
+    destroy?(sandbox: Sandbox): Promise<void>;
+}
+export interface SandboxCreateOptions {
+    /** Session ID for associating the sandbox with a session. */
+    sessionId?: string;
+    /** Workspace directory path, or true to auto-create a temp directory. */
+    workspace?: string | true;
+    /** Host↔sandbox path mappings. */
+    mounts?: Mount[];
+    /** Advisory permissions. */
+    permissions?: Permissions;
+    /** Environment variables. */
+    env?: Record<string, string>;
+    /** Resource constraints. */
+    limits?: ResourceLimits;
+}
+export interface SandboxConfig {
+    provider: SandboxProvider;
+    workspace?: string | true;
+    mounts?: Mount[];
+    permissions?: Permissions;
+    env?: Record<string, string | (() => string)>;
+    limits?: ResourceLimits;
+    setup?: (sandbox: Sandbox) => Promise<void>;
+    persist?: boolean;
+}
+export interface SandboxSnapshot {
+    /** Provider name that created this sandbox. */
+    provider: string;
+    /** Sandbox ID. */
+    id: string;
+    /** Workspace path. */
+    workspacePath: string;
+    /** Provider-specific state for restoration. */
+    state?: Record<string, unknown>;
+}
+export interface ExecOptions {
+    /** Working directory for the command. */
+    cwd?: string;
+    /** Additional environment variables. */
+    env?: Record<string, string>;
+    /** Timeout in milliseconds. */
+    timeout?: number;
+    /** Streaming output callback. Called for each chunk of stdout/stderr. */
+    onOutput?: (chunk: OutputChunk) => void;
+}
+export interface ExecResult {
+    /** Standard output. */
+    stdout: string;
+    /** Standard error. */
+    stderr: string;
+    /** Process exit code. */
+    exitCode: number;
+}
+export interface OutputChunk {
+    /** Which output stream this chunk came from. */
+    stream: "stdout" | "stderr";
+    /** The data content. */
+    data: string;
+}
+export interface Mount {
+    /** Host filesystem path. */
+    host: string;
+    /** Sandbox filesystem path. */
+    sandbox: string;
+    /** Mount mode. Default: "rw". */
+    mode?: "ro" | "rw";
+}
+export interface Permissions {
+    /** Filesystem access. Default: true. */
+    fs?: boolean;
+    /**
+     * Network access. Default: false.
+     * - `false` — deny all (default)
+     * - `true` — allow all
+     * - `NetworkRule[]` — apply rules in order, first match wins, default deny
+     */
+    net?: boolean | NetworkRule[];
+    /** Child process spawning. Default: true. */
+    childProcess?: boolean;
+    /** Inherit host environment variables. Default: false. */
+    inheritEnv?: boolean;
+}
+export interface ResourceLimits {
+    /** Memory limit in bytes. */
+    memory?: number;
+    /** CPU limit (fractional cores, e.g. 0.5). */
+    cpu?: number;
+    /** Global timeout in milliseconds. */
+    timeout?: number;
+    /** Disk limit in bytes. */
+    disk?: number;
+    /** Maximum concurrent processes. */
+    maxProcesses?: number;
+}
+export interface NetworkRule {
+    /** "allow" or "deny". Rules evaluated in order; first match wins. */
+    action: "allow" | "deny";
+    /** Domain pattern. Supports wildcards: "*.example.com", "api.github.com". */
+    domain?: string;
+    /** URL regex pattern. Matched against full URL. */
+    urlPattern?: string;
+    /** HTTP methods to match. Default: all. */
+    methods?: string[];
+    /** Port to match. */
+    port?: number;
+}
+export interface ProxiedRequest {
+    /** Full URL of the request. */
+    url: string;
+    /** HTTP method. */
+    method: string;
+    /** Target host. */
+    host: string;
+    /** Target port. */
+    port: number;
+    /** Unix timestamp (ms) when the request was made. */
+    timestamp: number;
+    /** Whether the request was blocked. */
+    blocked: boolean;
+    /** The rule that matched, if any. */
+    matchedRule?: NetworkRule;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Sandbox Contract Types
+ *
+ * All types for the sandbox abstraction layer.
+ * Provider adapters (@agentick/sandbox-local, @agentick/sandbox-docker, etc.)
+ * implement SandboxProvider.
+ */
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@agentick/sandbox",
+  "version": "0.2.1",
+  "description": "Sandbox primitive layer for Agentick — types, context, component, and pre-built tools",
+  "keywords": [
+    "agent",
+    "ai",
+    "sandbox"
+  ],
+  "license": "MIT",
+  "author": "Ryan Lindgren",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agenticklabs/agentick.git",
+    "directory": "packages/sandbox"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./src/testing.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./testing": {
+        "types": "./dist/testing.d.ts",
+        "import": "./dist/testing.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "lint": "oxlint src/",
+    "format:check": "oxfmt --check src/",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@agentick/core": "workspace:*",
+    "react": "^19.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.13",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @agentick/sandbox - Sandbox primitive layer
+ *
+ * Types, context, component, and pre-built tools for sandboxed execution.
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type {
+  Sandbox as SandboxHandle,
+  SandboxProvider,
+  SandboxCreateOptions,
+  SandboxConfig,
+  SandboxSnapshot,
+  ExecOptions,
+  ExecResult,
+  OutputChunk,
+  Mount,
+  Permissions,
+  ResourceLimits,
+  NetworkRule,
+  ProxiedRequest,
+} from "./types";
+
+// ── Edit Types & Utilities ───────────────────────────────────────────────────
+export { applyEdits, editFile, EditError } from "./edit";
+export type { Edit, EditResult, EditChange } from "./edit";
+
+// ── Context & Hook ───────────────────────────────────────────────────────────
+export { SandboxContext, useSandbox } from "./context";
+
+// ── Component ────────────────────────────────────────────────────────────────
+export { Sandbox } from "./component";
+export type { SandboxProps } from "./component";
+
+// ── Tools ────────────────────────────────────────────────────────────────────
+export { Shell, ReadFile, WriteFile, EditFile } from "./tools";
+
+// ── Testing ──────────────────────────────────────────────────────────────────
+// Import from "@agentick/sandbox/testing" — not re-exported here to avoid
+// pulling vitest into production bundles.