@anvia/sandbox 1.1.7 → 1.2.0

package/README.md

@@ -1,6 +1,16 @@
-# `@anvia/sandbox`
+# @anvia/sandbox
 
-Docker-backed sandbox ownership and tools for Anvia applications.
+Give agents a workspace where they can run commands and work with files. Docker-backed sandboxes keep execution infrastructure explicit and under your application’s control.
+
+## Installation
+
+```sh
+pnpm add @anvia/sandbox @anvia/core
+```
+
+## Quick start
+
+Requires Node.js 20.12 or later and an accessible Docker daemon. Pull an image before creating a sandbox.
 
 ```ts
 import { createDockerSandboxTools, DockerSandboxClient } from "@anvia/sandbox";
@@ -18,67 +28,32 @@ const tools = createDockerSandboxTools({
   sandbox: sandbox.runtime,
   tools: ["exec_command", "read_file", "write_file", "list_files"],
 });
+// Pass tools to new Agent({ id, model, tools }).
 ```
 
-`DockerSandboxClient` performs explicit infrastructure operations. Its constructor performs no I/O,
-and `createSandbox()` and `resumeSandbox()` never pull images. `DockerSandbox` owns the container and,
-for an ephemeral workspace, its Docker volume. Dispose it asynchronously or call `destroy()`.
-
-`stop()` preserves the container and workspace. `resumeSandbox({ id })` creates a fresh live handle for
-that container; workspace files persist, while the in-memory managed-process registry starts empty. A
-caller-owned `{ type: "docker-volume", name }` workspace is never deleted by the sandbox.
-
-Networking is explicit. Use `{ mode: "none" }` or `{ mode: "bridge", ports: [...] }`; published ports
-bind only to `127.0.0.1`. Runtime methods use object arguments, propagate abort signals, and expose
-command and process output as bytes. Tool wrappers decode UTF-8 strictly and return structured values.
-
-`exec_command` accepts a complete shell command line in `command`, including pipes, redirects, and
-multiline scripts. For exact argv execution without shell parsing, provide the executable in
-`command` and its arguments in `args`. Command policies apply to the implicit `sh` executable when a
-shell command line is used. Natural command lines are rejected with block-mode command policies
-because arbitrary shell syntax cannot be checked safely against an executable block list; use exact
-`command` and `args` input in that configuration.
-
-File paths and command working directories passed to agent tools may be workspace-relative (for
-example `notes/result.txt`) or absolute paths inside the sandbox workdir (for example
-`/workspace/notes/result.txt` with the default workdir). Paths outside the sandbox workdir are
-rejected.
-
-With `exec.commands.mode: "allow"`, both `exec_command` and `start_process` reject known shell
-executables by default, including path-qualified names such as `/bin/sh`. To permit an allowlisted
-shell, set `exec.commands.allowShellInterpreters` to the boolean `true`. Omitted or `false` keeps the
-guard enabled; non-boolean values such as `"false"` are rejected when creating tools. This guard
-checks executable names only: allowlisted runtimes such as Node.js or Python can still launch other
-commands, so the command policy does not restrict what those programs can execute.
-
-`resources.sharedMemoryMb` maps to a private Docker `/dev/shm` size. A security configuration may use
-explicit `dropCapabilities` and `addCapabilities` arrays, plus
-`seccompProfile: { type: "path", path }` with an absolute host path. These options are used by
-`@anvia/browser` to keep Chromium's own process sandbox enabled.
-
-`createSandbox()` accepts `containerRuntime` — the runtime name registered in the Docker daemon (for
-example `runsc` for gVisor). The runtime must already be registered (`runsc install` followed by a
-daemon restart); creation fails with a `runtime_not_found` error otherwise. `resumeSandbox()` keeps
-the container's original runtime. Under gVisor, workspace files persist through
-`stop()`/`resumeSandbox()` because they live on a Docker volume, but changes to the container's
-writable rootfs outside the workspace do not survive a resume, and `security.seccompProfile` is not
-enforced the way it is on the default runtime because the gVisor sentry mediates application
-syscalls itself.
-
-Studio does not discover sandboxes through tool metadata. Register a read-only inspector explicitly:
+## What you get
 
-```ts
-const studio = new Studio([agent], {
-  sandboxes: [
-    {
-      inspector: sandbox.inspector({ files: true, ports: true, processes: true }),
-      agentIds: [agent.id],
-      toolNames: tools.map((tool) => tool.name),
-    },
-  ],
-});
-```
+- Command execution, file access, and managed processes.
+- Ephemeral workspaces or caller-owned Docker volumes.
+- Explicit networking, resource limits, and command policies.
+- Stop/resume lifecycle and automatic disposal.
+- Read-only sandbox inspection in Anvia Studio.
+
+`await using` destroys the owned container and ephemeral volume at scope exit. Keep the scope open while agents use its tools. Command policies filter executable names; they do not restrict what an allowed interpreter can execute.
+
+## Shell command lines
+
+`exec_command` and `start_process` use `/bin/bash -c` for natural command lines when `/bin/bash`
+is executable, falling back to `sh -c` when it is absent. Availability is cached per live sandbox
+runtime handle. Explicit `command` plus `args` remains exact argv; use
+`{ command: "sh", args: ["-c", script] }` to retain the previous POSIX shell behavior.
+
+Allow policies must permit the selected executable (`/bin/bash` or `sh`) and set
+`allowShellInterpreters: true`. Allowing only `sh` does not implicitly authorize Bash.
+Block-mode policies continue to reject natural command lines. See the usage guide for details.
+
+## Learn more
 
-The `anvia-sandbox create-image` CLI only builds images. It does not create, resume, stop, or destroy
-sandboxes. Its `playwright` feature remains a general code-sandbox image; the visible Chromium/CDP/
-noVNC appliance is source-controlled and owned by `@anvia/browser`.
+- [Usage guide](https://github.com/anvia-hq/anvia/blob/main/docs/packages/tool-sandbox.md)
+- [Anvia](https://github.com/anvia-hq/anvia/blob/main/README.md)
+- [Contributing](https://github.com/anvia-hq/anvia/blob/main/CONTRIBUTING.md)

package/dist/index.js

@@ -2007,6 +2007,47 @@ function isRecord(value) {
 import { createTool } from "@anvia/core/tool";
 import { z } from "zod";
 
+// src/shell.ts
+var shells = /* @__PURE__ */ new WeakMap();
+async function sandboxShell(sandbox, abortSignal) {
+  abortSignal?.throwIfAborted();
+  let pending = shells.get(sandbox);
+  if (pending === void 0) {
+    pending = detectShell(sandbox).catch((error) => {
+      shells.delete(sandbox);
+      throw error;
+    });
+    shells.set(sandbox, pending);
+  }
+  if (abortSignal === void 0) return pending;
+  let abort;
+  try {
+    return await Promise.race([
+      pending,
+      new Promise((_, reject) => {
+        abort = () => reject(abortSignal.reason);
+        if (abortSignal.aborted) abort();
+        else abortSignal.addEventListener("abort", abort, { once: true });
+      })
+    ]);
+  } finally {
+    if (abort !== void 0) abortSignal.removeEventListener("abort", abort);
+  }
+}
+async function detectShell(sandbox) {
+  const result = await sandbox.exec({
+    command: "sh",
+    args: ["-c", "test -x /bin/bash"],
+    timeoutMs: 5e3
+  });
+  if (result.status === "timed_out") {
+    throw new DockerSandboxError("Sandbox shell detection timed out.", "timeout");
+  }
+  if (result.exitCode === 0) return "/bin/bash";
+  if (result.exitCode === 1) return "sh";
+  throw new DockerSandboxError("Could not detect the sandbox shell.", "docker_command_failed");
+}
+
 // src/types.ts
 var shellInterpreters = [
   "sh",
@@ -2036,7 +2077,7 @@ var allToolNames = [
 ];
 var execCommandInput = z.object({
   command: z.string().min(1).describe(
-    "Command to run. Complete shell command lines are supported; use args for exact argv execution."
+    "Command to run. Natural command lines use /bin/bash -c when available, otherwise sh -c. Use args for exact argv execution."
   ),
   args: z.array(z.string()).describe("Optional exact arguments. Omit when command contains the complete command line.").optional(),
   cwd: z.string().describe("Workspace-relative directory or an absolute directory inside the sandbox workdir.").optional(),
@@ -2105,8 +2146,8 @@ var publishedPortOutput = z.object({
 });
 var listPortsOutput = z.object({ ports: z.array(publishedPortOutput) });
 var startProcessInput = z.object({
-  command: z.string().min(1),
-  args: z.array(z.string()).optional(),
+  command: execCommandInput.shape.command,
+  args: execCommandInput.shape.args,
   cwd: z.string().describe("Workspace-relative directory or an absolute directory inside the sandbox workdir.").optional(),
   env: z.record(z.string(), z.string()).optional()
 });
@@ -2168,19 +2209,20 @@ function createDockerSandboxTools(options) {
 function createExecCommandTool(options) {
   return createTool({
     name: "exec_command",
-    description: "Run a command inside the sandbox, including natural shell command lines.",
+    description: "Run a command inside the sandbox. Natural command lines use /bin/bash -c when available, otherwise sh -c; supply args for exact argv execution.",
     inputSchema: execCommandInput,
     outputSchema: execResultOutput,
     execute: async ({ command, args, cwd, env, timeoutMs, input }, context) => {
-      const invocation = resolveExecInvocation(command, args, options.exec?.commands);
       const effectiveTimeoutMs = timeoutMs ?? options.exec?.defaultTimeoutMs;
       assertTimeoutAllowed(effectiveTimeoutMs, options.exec?.maxTimeoutMs);
+      const normalizedCwd = cwd === void 0 ? void 0 : normalizeToolPath(options.sandbox, cwd, true);
+      const invocation = await resolveExecInvocation(options, command, args, context.abortSignal);
       let execOptions = {
         command: invocation.command
       };
       if (invocation.args !== void 0) execOptions = { ...execOptions, args: invocation.args };
-      if (cwd !== void 0) {
-        execOptions = { ...execOptions, cwd: normalizeToolPath(options.sandbox, cwd, true) };
+      if (normalizedCwd !== void 0) {
+        execOptions = { ...execOptions, cwd: normalizedCwd };
       }
       if (env !== void 0) execOptions = { ...execOptions, env };
       if (effectiveTimeoutMs !== void 0) {
@@ -2275,15 +2317,15 @@ function createListPortsTool(sandbox) {
 function createStartProcessTool(options) {
   return createTool({
     name: "start_process",
-    description: "Start a managed long-running process inside the sandbox.",
+    description: "Start a managed long-running process inside the sandbox. Natural command lines use /bin/bash -c when available, otherwise sh -c; supply args for exact argv execution.",
     inputSchema: startProcessInput,
     outputSchema: processInfoOutput,
     execute: async ({ command, args, cwd, env }, context) => {
-      assertCommandAllowed(command, options.exec?.commands);
-      let startOptions = { command };
-      if (args !== void 0) startOptions = { ...startOptions, args };
-      if (cwd !== void 0) {
-        startOptions = { ...startOptions, cwd: normalizeToolPath(options.sandbox, cwd, true) };
+      const normalizedCwd = cwd === void 0 ? void 0 : normalizeToolPath(options.sandbox, cwd, true);
+      const invocation = await resolveExecInvocation(options, command, args, context.abortSignal);
+      let startOptions = { ...invocation };
+      if (normalizedCwd !== void 0) {
+        startOptions = { ...startOptions, cwd: normalizedCwd };
       }
       if (env !== void 0) startOptions = { ...startOptions, env };
       if (context.abortSignal !== void 0) {
@@ -2538,15 +2580,22 @@ function assertCommandAllowed(command, policy) {
     }
   }
 }
-function resolveExecInvocation(command, args, policy) {
+async function resolveExecInvocation(options, command, args, abortSignal) {
+  abortSignal?.throwIfAborted();
+  const policy = options.exec?.commands;
   if (args === void 0 && requiresShell(command)) {
     if (policy?.mode === "block") {
       throw toolPolicyError(
         "Natural command lines cannot be used with block-mode command policies. Use command and args instead."
       );
     }
-    assertCommandAllowed("sh", policy);
-    return { command: "sh", args: ["-c", command] };
+    if (policy?.mode === "allow" && policy.allowShellInterpreters !== true) {
+      throw toolPolicyError("Natural command lines require allowShellInterpreters: true.");
+    }
+    const shell = await sandboxShell(options.sandbox, abortSignal);
+    abortSignal?.throwIfAborted();
+    assertCommandAllowed(shell, policy);
+    return { command: shell, args: ["-c", command] };
   }
   assertCommandAllowed(command, policy);
   return args === void 0 ? { command } : { command, args };