@agentick/sandbox 0.2.1

package/README.md

@@ -0,0 +1,251 @@
+# @agentick/sandbox
+
+Sandbox primitive layer for Agentick. Provides types, React context, a `<Sandbox>` JSX component, and pre-built tools (Shell, ReadFile, WriteFile, EditFile) for sandboxed code execution.
+
+Provider adapters (`@agentick/sandbox-local`, `@agentick/sandbox-docker`, etc.) implement `SandboxProvider` and plug in via the `provider` prop.
+
+## Installation
+
+```bash
+pnpm add @agentick/sandbox
+```
+
+## Quick Start
+
+```tsx
+import { Sandbox, Shell, ReadFile, WriteFile, EditFile } from "@agentick/sandbox";
+import { localProvider } from "@agentick/sandbox-local";
+
+function CodingAgent() {
+  return (
+    <Sandbox provider={localProvider()} workspace="/tmp/project">
+      <Shell />
+      <ReadFile />
+      <WriteFile />
+      <EditFile />
+      <System>You are a coding assistant with sandbox access.</System>
+    </Sandbox>
+  );
+}
+```
+
+## Component
+
+### `<Sandbox>`
+
+Creates a sandbox instance and provides it to children via React context.
+
+```tsx
+<Sandbox
+  provider={localProvider()} // Required — SandboxProvider implementation
+  workspace="/tmp/project" // Path or true for auto temp dir (default: true)
+  mounts={[{ host: "./src", sandbox: "/app/src", mode: "rw" }]}
+  allow={{ fs: true, net: false }} // Advisory permissions
+  env={{ NODE_ENV: "development" }} // Env vars (string or () => string)
+  limits={{ memory: 512_000_000 }} // Resource constraints
+  setup={async (sb) => {
+    // Post-creation setup
+    await sb.exec("npm install");
+  }}
+>
+  {children}
+</Sandbox>
+```
+
+Uses `useData` for async initialization and `useOnUnmount` for cleanup.
+
+## Hook
+
+### `useSandbox()`
+
+Access the nearest `Sandbox` from the component tree. Throws if no provider is found.
+
+```tsx
+import { useSandbox } from "@agentick/sandbox";
+
+const sandbox = useSandbox();
+const result = await sandbox.exec("ls -la");
+```
+
+Primary use: the `use()` hook on `createTool` for tree-scoped sandbox access.
+
+```tsx
+const MyTool = createTool({
+  name: "my_tool",
+  description: "Custom sandbox tool",
+  input: z.object({ query: z.string() }),
+  use: () => ({ sandbox: useSandbox() }),
+  handler: async ({ query }, deps) => {
+    const result = await deps!.sandbox.exec(`grep -r "${query}" .`);
+    return [{ type: "text", text: result.stdout }];
+  },
+});
+```
+
+## Tools
+
+Four pre-built tools, all using `use()` + `useSandbox()` for tree-scoped access:
+
+| Tool        | Name         | Description                    |
+| ----------- | ------------ | ------------------------------ |
+| `Shell`     | `shell`      | Execute a shell command        |
+| `ReadFile`  | `read_file`  | Read file contents             |
+| `WriteFile` | `write_file` | Write content to a file        |
+| `EditFile`  | `edit_file`  | Apply surgical edits to a file |
+
+```tsx
+import { Shell, ReadFile, WriteFile, EditFile } from "@agentick/sandbox";
+
+// Include all tools
+<Sandbox provider={provider}>
+  <Shell />
+  <ReadFile />
+  <WriteFile />
+  <EditFile />
+  <MyAgent />
+</Sandbox>
+
+// Or pick specific tools
+<Sandbox provider={provider}>
+  <Shell />
+  <ReadFile />
+  <MyAgent />
+</Sandbox>
+```
+
+### Tree Scoping
+
+Multiple sandboxes in the same tree work naturally. Each tool accesses its nearest `<Sandbox>` provider:
+
+```tsx
+<Sandbox provider={localProvider()}>
+  <Shell />          {/* Uses local sandbox */}
+  <ReadFile />
+</Sandbox>
+<Sandbox provider={dockerProvider()}>
+  <Shell />          {/* Uses Docker sandbox */}
+  <WriteFile />
+</Sandbox>
+```
+
+## Edit Utilities
+
+Surgical code editing with 3-level matching that recovers from trailing whitespace, indentation mismatch, and CRLF/LF differences.
+
+### `applyEdits(source, edits)`
+
+Pure transform, no I/O. Matching strategy per edit (in order):
+
+1. Exact byte match
+2. Line-normalized (trailing whitespace stripped)
+3. Indent-adjusted (leading whitespace baseline stripped)
+
+```typescript
+import { applyEdits } from "@agentick/sandbox";
+
+const result = applyEdits(source, [
+  { old: "return 1;", new: "return 2;" },
+  { old: "oldName", new: "newName", all: true },
+]);
+// result.content, result.applied, result.changes
+```
+
+### `editFile(path, edits)`
+
+File wrapper. Reads, applies edits, writes atomically (temp + rename).
+
+```typescript
+import { editFile } from "@agentick/sandbox";
+
+await editFile("/path/to/file.ts", [{ old: "const x = 1;", new: "const x = 42;" }]);
+```
+
+## Types
+
+```typescript
+import type {
+  // Core types
+  SandboxHandle, // Runtime handle: exec, readFile, writeFile, editFile, destroy
+  SandboxProvider, // Factory: name, create, restore?, destroy?
+  SandboxCreateOptions, // Passed to provider.create()
+  SandboxConfig, // Component-level config
+  SandboxSnapshot, // Serializable state for persistence
+
+  // Execution
+  ExecOptions, // Per-command: cwd, env, timeout
+  ExecResult, // Output: stdout, stderr, exitCode
+  OutputChunk, // Streaming: stream, data
+
+  // Configuration
+  Mount, // Host<->sandbox path mapping
+  Permissions, // Advisory: fs, net, childProcess, inheritEnv
+  ResourceLimits, // Constraints: memory, cpu, timeout, disk, maxProcesses
+
+  // Edit
+  Edit, // { old, new, all? }
+  EditResult, // { content, applied, changes }
+  EditChange, // { line, removed, added }
+} from "@agentick/sandbox";
+```
+
+## Implementing a Provider
+
+Provider adapters implement `SandboxProvider`:
+
+```typescript
+import type { SandboxProvider, SandboxHandle, SandboxCreateOptions } from "@agentick/sandbox";
+import { applyEdits } from "@agentick/sandbox";
+
+export function myProvider(): SandboxProvider {
+  return {
+    name: "my-provider",
+    async create(options: SandboxCreateOptions): Promise<SandboxHandle> {
+      // Set up sandbox environment...
+      return {
+        id: crypto.randomUUID(),
+        workspacePath: "/sandbox/workspace",
+        async exec(command, opts) {
+          /* ... */
+        },
+        async readFile(path) {
+          /* ... */
+        },
+        async writeFile(path, content) {
+          /* ... */
+        },
+        async editFile(path, edits) {
+          const source = await this.readFile(path);
+          const result = applyEdits(source, edits);
+          if (result.applied > 0) await this.writeFile(path, result.content);
+          return result;
+        },
+        async destroy() {
+          /* ... */
+        },
+      };
+    },
+  };
+}
+```
+
+## Testing
+
+Import test utilities from `@agentick/sandbox/testing`:
+
+```typescript
+import { createMockSandbox, createMockProvider } from "@agentick/sandbox/testing";
+
+const sandbox = createMockSandbox({
+  exec: vi.fn().mockResolvedValue({ stdout: "hello", stderr: "", exitCode: 0 }),
+});
+
+const provider = createMockProvider({
+  create: vi.fn().mockResolvedValue(sandbox),
+});
+```
+
+Both return objects with `vi.fn()` stubs and sensible defaults. Override any method via the options parameter.
+
+## License
+
+MIT

package/dist/component.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Sandbox Component
+ *
+ * JSX component that creates and provides a Sandbox instance to its children.
+ * Uses useData for async initialization and useOnUnmount for cleanup.
+ */
+import type React from "react";
+import type { SandboxProvider, Mount, Permissions, ResourceLimits, Sandbox as SandboxHandle } from "./types";
+export interface SandboxProps {
+    /** The sandbox provider to use (e.g. localProvider()). */
+    provider: SandboxProvider;
+    /** Workspace path, or true for auto temp directory. Default: true. */
+    workspace?: string | true;
+    /** Host↔sandbox path mappings. */
+    mounts?: Mount[];
+    /** Advisory permissions. */
+    allow?: Permissions;
+    /** Environment variables. Functions are resolved at creation time. */
+    env?: Record<string, string | (() => string)>;
+    /** Post-creation setup callback. */
+    setup?: (sandbox: SandboxHandle) => Promise<void>;
+    /** Resource constraints. */
+    limits?: ResourceLimits;
+    /** Whether to persist sandbox state in snapshots. Default: false. */
+    persist?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Creates a sandbox instance and provides it to children via context.
+ *
+ * @example
+ * ```tsx
+ * <Sandbox provider={localProvider()}>
+ *   <Shell />
+ *   <ReadFile />
+ *   <WriteFile />
+ *   <EditFile />
+ *   <MyAgent />
+ * </Sandbox>
+ * ```
+ */
+export declare function Sandbox({ provider, workspace, mounts, allow, env, setup, limits, children, }: SandboxProps): React.ReactElement;
+//# sourceMappingURL=component.d.ts.map

package/dist/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EACV,eAAe,EAEf,KAAK,EACL,WAAW,EACX,cAAc,EACd,OAAO,IAAI,aAAa,EACzB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,QAAQ,EAAE,eAAe,CAAC;IAE1B,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,kCAAkC;IAClC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IAEjB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC;IAE9C,oCAAoC;IACpC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD,4BAA4B;IAC5B,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,SAAgB,EAChB,MAAM,EACN,KAAK,EACL,GAAG,EACH,KAAK,EACL,MAAM,EACN,QAAQ,GACT,EAAE,YAAY,GAAG,KAAK,CAAC,YAAY,CA2BnC"}

package/dist/component.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useData, useOnUnmount } from "@agentick/core";
+import { SandboxContext } from "./context";
+/**
+ * Creates a sandbox instance and provides it to children via context.
+ *
+ * @example
+ * ```tsx
+ * <Sandbox provider={localProvider()}>
+ *   <Shell />
+ *   <ReadFile />
+ *   <WriteFile />
+ *   <EditFile />
+ *   <MyAgent />
+ * </Sandbox>
+ * ```
+ */
+export function Sandbox({ provider, workspace = true, mounts, allow, env, setup, limits, children, }) {
+    // Resolve env functions to plain strings
+    const resolvedEnv = env
+        ? Object.fromEntries(Object.entries(env).map(([k, v]) => [k, typeof v === "function" ? v() : v]))
+        : undefined;
+    const options = {
+        workspace,
+        mounts,
+        permissions: allow,
+        env: resolvedEnv,
+        limits,
+    };
+    const sandbox = useData("sandbox", async () => {
+        const sb = await provider.create(options);
+        if (setup)
+            await setup(sb);
+        return sb;
+    });
+    useOnUnmount(() => {
+        sandbox.destroy();
+    });
+    return _jsx(SandboxContext.Provider, { value: sandbox, children: children });
+}
+//# sourceMappingURL=component.js.map

package/dist/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.tsx"],"names":[],"mappings":";AAQA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAsC3C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CAAC,EACtB,QAAQ,EACR,SAAS,GAAG,IAAI,EAChB,MAAM,EACN,KAAK,EACL,GAAG,EACH,KAAK,EACL,MAAM,EACN,QAAQ,GACK;IACb,yCAAyC;IACzC,MAAM,WAAW,GAAG,GAAG;QACrB,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC5E;QACH,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,OAAO,GAAyB;QACpC,SAAS;QACT,MAAM;QACN,WAAW,EAAE,KAAK;QAClB,GAAG,EAAE,WAAW;QAChB,MAAM;KACP,CAAC;IAEF,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC5C,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,KAAK;YAAE,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC,CAAC;IAEH,YAAY,CAAC,GAAG,EAAE;QAChB,OAAO,CAAC,OAAO,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,OAAO,KAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YAAG,QAAQ,GAA2B,CAAC;AACvF,CAAC"}

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sandbox Context
+ *
+ * React context and hook for accessing the nearest Sandbox in the component tree.
+ */
+import type { Sandbox } from "./types";
+export declare const SandboxContext: import("react").Context<Sandbox | null>;
+/**
+ * Access the nearest Sandbox from the component tree.
+ *
+ * @throws Error if no `<Sandbox>` provider is found in the tree.
+ *
+ * @example
+ * ```tsx
+ * const Shell = createTool({
+ *   name: 'shell',
+ *   use: () => ({ sandbox: useSandbox() }),
+ *   handler: async ({ command }, deps) => {
+ *     const result = await deps!.sandbox.exec(command);
+ *     return [{ type: 'text', text: result.stdout }];
+ *   },
+ * });
+ * ```
+ */
+export declare function useSandbox(): Sandbox;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,eAAO,MAAM,cAAc,yCAAsC,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAQpC"}

package/dist/context.js

@@ -0,0 +1,32 @@
+/**
+ * Sandbox Context
+ *
+ * React context and hook for accessing the nearest Sandbox in the component tree.
+ */
+import { createContext, useContext } from "react";
+export const SandboxContext = createContext(null);
+/**
+ * Access the nearest Sandbox from the component tree.
+ *
+ * @throws Error if no `<Sandbox>` provider is found in the tree.
+ *
+ * @example
+ * ```tsx
+ * const Shell = createTool({
+ *   name: 'shell',
+ *   use: () => ({ sandbox: useSandbox() }),
+ *   handler: async ({ command }, deps) => {
+ *     const result = await deps!.sandbox.exec(command);
+ *     return [{ type: 'text', text: result.stdout }];
+ *   },
+ * });
+ * ```
+ */
+export function useSandbox() {
+    const sandbox = useContext(SandboxContext);
+    if (!sandbox) {
+        throw new Error("useSandbox(): No sandbox found. Wrap your component tree with <Sandbox provider={...}>.");
+    }
+    return sandbox;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAiB,IAAI,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/edit.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Surgical Code Editing
+ *
+ * LLM-driven code editing with layered matching that recovers from
+ * trailing whitespace, indentation mismatch, and CRLF/LF differences.
+ *
+ * Pure transform (`applyEdits`) + file wrapper (`editFile`) with atomic writes.
+ */
+export interface Edit {
+    /** Exact string to find in the source. */
+    old: string;
+    /** Replacement string. Empty string deletes the match. */
+    new: string;
+    /** Replace ALL occurrences. Default false — requires unique match. */
+    all?: boolean;
+}
+export interface EditChange {
+    /** 1-based line where the change starts. */
+    line: number;
+    /** Lines removed. */
+    removed: number;
+    /** Lines added. */
+    added: number;
+}
+export interface EditResult {
+    /** Resulting content after edits. */
+    content: string;
+    /** Total number of replacements applied. */
+    applied: number;
+    /** Per-replacement details in document order. */
+    changes: EditChange[];
+}
+export declare class EditError extends Error {
+    readonly editIndex: number;
+    readonly detail?: {
+        closest?: string;
+        line?: number;
+    } | undefined;
+    constructor(message: string, editIndex: number, detail?: {
+        closest?: string;
+        line?: number;
+    } | undefined);
+}
+/**
+ * Apply edits to a source string. Pure function, no I/O.
+ *
+ * Matching strategy per edit (in order):
+ * 1. Exact byte match
+ * 2. Line-normalized (trailing whitespace stripped)
+ * 3. Indent-adjusted (leading whitespace baseline stripped, new indentation adjusted)
+ *
+ * Multi-edit: all matches resolved against original source,
+ * validated for overlap, applied bottom-to-top.
+ *
+ * @throws EditError on match failure or overlapping edits
+ */
+export declare function applyEdits(source: string, edits: Edit[]): EditResult;
+/**
+ * Edit a file on disk. Reads, applies edits, writes atomically (temp + rename).
+ */
+export declare function editFile(path: string, edits: Edit[]): Promise<EditResult>;
+//# sourceMappingURL=edit.d.ts.map

package/dist/edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../src/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,IAAI;IACnB,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,qBAAa,SAAU,SAAQ,KAAK;aAGhB,SAAS,EAAE,MAAM;aACjB,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;gBAF5D,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,YAAA;CAK/D;AAyHD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAsJpE;AAID;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAmB/E"}