@anvia/sandbox 1.1.6 → 1.1.8

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,21 @@ 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.
+## What you get
 
-`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.
+- 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.
 
-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.
+`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.
 
-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:
-
-```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),
-    },
-  ],
-});
-```
+## 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/{chunk-D5XZQ2ES.js → chunk-ZMZH4DBC.js}

@@ -87,12 +87,31 @@ async function assertDockerCli(args, options) {
   const result = await runDockerCli(args, options);
   if (result.exitCode !== 0) {
     throw new DockerSandboxError(
-      `Docker command failed: docker ${args.join(" ")}`,
+      `Docker command failed: docker ${redactCliArgs(args).join(" ")}`,
       "docker_command_failed",
       result
     );
   }
 }
+var envValueFlags = /* @__PURE__ */ new Set(["--env", "-e"]);
+function redactCliArgs(args) {
+  return args.map((arg, index) => {
+    const flag = args[index - 1];
+    if (flag !== void 0 && envValueFlags.has(flag)) return redactEnvAssignment(arg);
+    for (const envFlag of envValueFlags) {
+      const prefix = `${envFlag}=`;
+      if (arg.startsWith(prefix))
+        return `${prefix}${redactEnvAssignment(arg.slice(prefix.length))}`;
+    }
+    if (arg.startsWith("-e") && !arg.startsWith("-e=") && arg.length > 2)
+      return `-e${redactEnvAssignment(arg.slice(2))}`;
+    return arg;
+  });
+}
+function redactEnvAssignment(value) {
+  const separator = value.indexOf("=");
+  return separator === -1 ? value : `${value.slice(0, separator + 1)}<redacted>`;
+}
 function createOutputCollector(maxBytes, onChunk) {
   const chunks = [];
   let length = 0;
@@ -131,4 +150,4 @@ export {
   assertDockerCli,
   decodeUtf8
 };
-//# sourceMappingURL=chunk-D5XZQ2ES.js.map
+//# sourceMappingURL=chunk-ZMZH4DBC.js.map

package/dist/chunk-ZMZH4DBC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/docker-cli.ts"],"sourcesContent":["export type DockerSandboxErrorCode =\n  | \"docker_unavailable\"\n  | \"docker_command_failed\"\n  | \"image_not_found\"\n  | \"runtime_not_found\"\n  | \"volume_not_found\"\n  | \"sandbox_not_found\"\n  | \"invalid_state\"\n  | \"invalid_path\"\n  | \"timeout\"\n  | \"file_too_large\"\n  | \"tool_policy\"\n  | \"port\"\n  | \"process\";\n\nexport class DockerSandboxError extends Error {\n  constructor(\n    message: string,\n    readonly code: DockerSandboxErrorCode,\n    readonly details?: unknown,\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n    this.name = \"DockerSandboxError\";\n  }\n}\n\nexport function dockerSandboxError(\n  message: string,\n  code: DockerSandboxErrorCode,\n  cause?: unknown,\n  details?: unknown,\n): DockerSandboxError {\n  return new DockerSandboxError(\n    message,\n    code,\n    details,\n    cause === undefined ? undefined : { cause },\n  );\n}\n","import { spawn } from \"node:child_process\";\nimport { DockerSandboxError } from \"./errors\";\n\nexport interface DockerCliResult {\n  stdout: Uint8Array;\n  stderr: Uint8Array;\n  exitCode: number;\n  durationMs: number;\n  timedOut: boolean;\n  stdoutTruncated: boolean;\n  stderrTruncated: boolean;\n}\n\nexport interface DockerCliOptions {\n  dockerPath: string;\n  timeoutMs?: number | undefined;\n  maxOutputBytes?: number | undefined;\n  input?: string | Uint8Array | undefined;\n  signal?: AbortSignal | undefined;\n  onStdout?: (chunk: Uint8Array) => void;\n  onStderr?: (chunk: Uint8Array) => void;\n}\n\nconst defaultMaxOutputBytes = 1024 * 1024;\n\nexport async function runDockerCli(\n  args: string[],\n  options: DockerCliOptions,\n): Promise<DockerCliResult> {\n  const startedAt = Date.now();\n  const maxOutputBytes = options.maxOutputBytes ?? defaultMaxOutputBytes;\n  const stdout = createOutputCollector(maxOutputBytes, options.onStdout);\n  const stderr = createOutputCollector(maxOutputBytes, options.onStderr);\n\n  return new Promise((resolve, reject) => {\n    const child = spawn(options.dockerPath, args, {\n      stdio: [\"pipe\", \"pipe\", \"pipe\"],\n    });\n\n    let timedOut = false;\n    let settled = false;\n\n    const timeout =\n      options.timeoutMs === undefined\n        ? undefined\n        : setTimeout(() => {\n            timedOut = true;\n            child.kill(\"SIGKILL\");\n          }, options.timeoutMs);\n\n    const abort = () => {\n      child.kill(\"SIGKILL\");\n    };\n\n    if (options.signal?.aborted === true) {\n      abort();\n    } else {\n      options.signal?.addEventListener(\"abort\", abort, { once: true });\n    }\n\n    child.stdout.on(\"data\", (chunk: Buffer) => stdout.accept(chunk));\n    child.stderr.on(\"data\", (chunk: Buffer) => stderr.accept(chunk));\n\n    child.on(\"error\", (error) => {\n      if (settled) {\n        return;\n      }\n      settled = true;\n      clearTimeout(timeout);\n      options.signal?.removeEventListener(\"abort\", abort);\n\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n        reject(\n          new DockerSandboxError(\"Docker CLI was not found.\", \"docker_unavailable\", undefined, {\n            cause: error,\n          }),\n        );\n        return;\n      }\n\n      reject(error);\n    });\n\n    child.on(\"close\", (code) => {\n      if (settled) {\n        return;\n      }\n      settled = true;\n      clearTimeout(timeout);\n      options.signal?.removeEventListener(\"abort\", abort);\n\n      if (options.signal?.aborted === true) {\n        reject(options.signal.reason ?? new DOMException(\"Aborted\", \"AbortError\"));\n        return;\n      }\n\n      resolve({\n        stdout: stdout.bytes(),\n        stderr: stderr.bytes(),\n        exitCode: code ?? 1,\n        durationMs: Date.now() - startedAt,\n        timedOut,\n        stdoutTruncated: stdout.truncated,\n        stderrTruncated: stderr.truncated,\n      });\n    });\n\n    if (options.input !== undefined) {\n      child.stdin.end(options.input);\n    } else {\n      child.stdin.end();\n    }\n  });\n}\n\nexport async function assertDockerCli(args: string[], options: DockerCliOptions): Promise<void> {\n  const result = await runDockerCli(args, options);\n\n  if (result.exitCode !== 0) {\n    throw new DockerSandboxError(\n      `Docker command failed: docker ${redactCliArgs(args).join(\" \")}`,\n      \"docker_command_failed\",\n      result,\n    );\n  }\n}\n\n/** Flags whose following value is a `KEY=VALUE` assignment that may carry a secret. */\nconst envValueFlags = new Set([\"--env\", \"-e\"]);\n\n/**\n * Replace secret values in a Docker argv before it is embedded in an error message, so\n * environment values passed with `--env`/`-e` never reach logs or traces. The variable\n * name is kept visible to keep the failure diagnosable. Both the separated\n * (`--env KEY=VALUE`) and equals-delimited (`--env=KEY=VALUE`) spellings are covered, as\n * well as the attached short-flag spelling (`-eKEY=VALUE`) that Docker's flag parser\n * accepts for the `-e` shorthand.\n */\nfunction redactCliArgs(args: string[]): string[] {\n  return args.map((arg, index) => {\n    const flag = args[index - 1];\n    if (flag !== undefined && envValueFlags.has(flag)) return redactEnvAssignment(arg);\n    for (const envFlag of envValueFlags) {\n      const prefix = `${envFlag}=`;\n      if (arg.startsWith(prefix))\n        return `${prefix}${redactEnvAssignment(arg.slice(prefix.length))}`;\n    }\n    if (arg.startsWith(\"-e\") && !arg.startsWith(\"-e=\") && arg.length > 2)\n      return `-e${redactEnvAssignment(arg.slice(2))}`;\n    return arg;\n  });\n}\n\nfunction redactEnvAssignment(value: string): string {\n  const separator = value.indexOf(\"=\");\n  return separator === -1 ? value : `${value.slice(0, separator + 1)}<redacted>`;\n}\n\nfunction createOutputCollector(maxBytes: number, onChunk?: (chunk: Uint8Array) => void) {\n  const chunks: Buffer[] = [];\n  let length = 0;\n  let truncated = false;\n\n  return {\n    get truncated() {\n      return truncated;\n    },\n    accept(chunk: Buffer) {\n      onChunk?.(chunk);\n\n      if (length >= maxBytes) {\n        truncated = true;\n        return;\n      }\n\n      const remaining = maxBytes - length;\n      const next = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;\n      chunks.push(next);\n      length += next.length;\n\n      if (next.length < chunk.length) {\n        truncated = true;\n      }\n    },\n    bytes() {\n      const bytes = Buffer.concat(chunks, length);\n      return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength).slice();\n    },\n  };\n}\n\nexport function decodeUtf8(bytes: Uint8Array): string {\n  return new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes);\n}\n"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   assertDockerCli
-} from "./chunk-D5XZQ2ES.js";
+} from "./chunk-ZMZH4DBC.js";
 
 // src/cli.ts
 import { realpathSync } from "fs";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   assertDockerCli,
   decodeUtf8,
   runDockerCli
-} from "./chunk-D5XZQ2ES.js";
+} from "./chunk-ZMZH4DBC.js";
 
 // src/docker-sandbox.ts
 import { randomUUID as randomUUID2 } from "crypto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvia/sandbox",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Sandboxed workspace tools for Anvia agents.",
   "author": "anvia",
   "license": "MIT",
@@ -36,10 +36,10 @@
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@anvia/core": "1.5.0"
+    "@anvia/core": "1.6.1"
   },
   "peerDependencies": {
-    "@anvia/core": "^1.5.0"
+    "@anvia/core": "^1.6.1"
   },
   "engines": {
     "node": ">=20.12.0"

package/dist/chunk-D5XZQ2ES.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/errors.ts","../src/docker-cli.ts"],"sourcesContent":["export type DockerSandboxErrorCode =\n  | \"docker_unavailable\"\n  | \"docker_command_failed\"\n  | \"image_not_found\"\n  | \"runtime_not_found\"\n  | \"volume_not_found\"\n  | \"sandbox_not_found\"\n  | \"invalid_state\"\n  | \"invalid_path\"\n  | \"timeout\"\n  | \"file_too_large\"\n  | \"tool_policy\"\n  | \"port\"\n  | \"process\";\n\nexport class DockerSandboxError extends Error {\n  constructor(\n    message: string,\n    readonly code: DockerSandboxErrorCode,\n    readonly details?: unknown,\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n    this.name = \"DockerSandboxError\";\n  }\n}\n\nexport function dockerSandboxError(\n  message: string,\n  code: DockerSandboxErrorCode,\n  cause?: unknown,\n  details?: unknown,\n): DockerSandboxError {\n  return new DockerSandboxError(\n    message,\n    code,\n    details,\n    cause === undefined ? undefined : { cause },\n  );\n}\n","import { spawn } from \"node:child_process\";\nimport { DockerSandboxError } from \"./errors\";\n\nexport interface DockerCliResult {\n  stdout: Uint8Array;\n  stderr: Uint8Array;\n  exitCode: number;\n  durationMs: number;\n  timedOut: boolean;\n  stdoutTruncated: boolean;\n  stderrTruncated: boolean;\n}\n\nexport interface DockerCliOptions {\n  dockerPath: string;\n  timeoutMs?: number | undefined;\n  maxOutputBytes?: number | undefined;\n  input?: string | Uint8Array | undefined;\n  signal?: AbortSignal | undefined;\n  onStdout?: (chunk: Uint8Array) => void;\n  onStderr?: (chunk: Uint8Array) => void;\n}\n\nconst defaultMaxOutputBytes = 1024 * 1024;\n\nexport async function runDockerCli(\n  args: string[],\n  options: DockerCliOptions,\n): Promise<DockerCliResult> {\n  const startedAt = Date.now();\n  const maxOutputBytes = options.maxOutputBytes ?? defaultMaxOutputBytes;\n  const stdout = createOutputCollector(maxOutputBytes, options.onStdout);\n  const stderr = createOutputCollector(maxOutputBytes, options.onStderr);\n\n  return new Promise((resolve, reject) => {\n    const child = spawn(options.dockerPath, args, {\n      stdio: [\"pipe\", \"pipe\", \"pipe\"],\n    });\n\n    let timedOut = false;\n    let settled = false;\n\n    const timeout =\n      options.timeoutMs === undefined\n        ? undefined\n        : setTimeout(() => {\n            timedOut = true;\n            child.kill(\"SIGKILL\");\n          }, options.timeoutMs);\n\n    const abort = () => {\n      child.kill(\"SIGKILL\");\n    };\n\n    if (options.signal?.aborted === true) {\n      abort();\n    } else {\n      options.signal?.addEventListener(\"abort\", abort, { once: true });\n    }\n\n    child.stdout.on(\"data\", (chunk: Buffer) => stdout.accept(chunk));\n    child.stderr.on(\"data\", (chunk: Buffer) => stderr.accept(chunk));\n\n    child.on(\"error\", (error) => {\n      if (settled) {\n        return;\n      }\n      settled = true;\n      clearTimeout(timeout);\n      options.signal?.removeEventListener(\"abort\", abort);\n\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n        reject(\n          new DockerSandboxError(\"Docker CLI was not found.\", \"docker_unavailable\", undefined, {\n            cause: error,\n          }),\n        );\n        return;\n      }\n\n      reject(error);\n    });\n\n    child.on(\"close\", (code) => {\n      if (settled) {\n        return;\n      }\n      settled = true;\n      clearTimeout(timeout);\n      options.signal?.removeEventListener(\"abort\", abort);\n\n      if (options.signal?.aborted === true) {\n        reject(options.signal.reason ?? new DOMException(\"Aborted\", \"AbortError\"));\n        return;\n      }\n\n      resolve({\n        stdout: stdout.bytes(),\n        stderr: stderr.bytes(),\n        exitCode: code ?? 1,\n        durationMs: Date.now() - startedAt,\n        timedOut,\n        stdoutTruncated: stdout.truncated,\n        stderrTruncated: stderr.truncated,\n      });\n    });\n\n    if (options.input !== undefined) {\n      child.stdin.end(options.input);\n    } else {\n      child.stdin.end();\n    }\n  });\n}\n\nexport async function assertDockerCli(args: string[], options: DockerCliOptions): Promise<void> {\n  const result = await runDockerCli(args, options);\n\n  if (result.exitCode !== 0) {\n    throw new DockerSandboxError(\n      `Docker command failed: docker ${args.join(\" \")}`,\n      \"docker_command_failed\",\n      result,\n    );\n  }\n}\n\nfunction createOutputCollector(maxBytes: number, onChunk?: (chunk: Uint8Array) => void) {\n  const chunks: Buffer[] = [];\n  let length = 0;\n  let truncated = false;\n\n  return {\n    get truncated() {\n      return truncated;\n    },\n    accept(chunk: Buffer) {\n      onChunk?.(chunk);\n\n      if (length >= maxBytes) {\n        truncated = true;\n        return;\n      }\n\n      const remaining = maxBytes - length;\n      const next = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;\n      chunks.push(next);\n      length += next.length;\n\n      if (next.length < chunk.length) {\n        truncated = true;\n      }\n    },\n    bytes() {\n      const bytes = Buffer.concat(chunks, length);\n      return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength).slice();\n    },\n  };\n}\n\nexport function decodeUtf8(bytes: Uint8Array): string {\n  return new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes);\n}\n"],"mappings":"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","names":[]}