@anvia/sandbox 1.1.5 → 1.1.7

package/README.md

@@ -32,6 +32,13 @@ Networking is explicit. Use `{ mode: "none" }` or `{ mode: "bridge", 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

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";
@@ -1209,15 +1209,19 @@ var DockerSandboxRuntimeImpl = class {
             "1",
             "-maxdepth",
             "1",
-            "-printf",
-            "%p	%y	%s\n"
+            "-exec",
+            "stat",
+            "-c",
+            "%n	%f	%s",
+            "{}",
+            "+"
           ]
         },
         abortSignal
       );
       if (result.status !== "exited" || result.exitCode !== 0) {
         throw new DockerSandboxError(
-          "Unable to list sandbox files.",
+          dockerExecFailureMessage("Unable to list sandbox files", result),
           "docker_command_failed",
           result
         );
@@ -1820,8 +1824,11 @@ async function assertCopiedRegularFile(temporaryDirectory, target, sandboxPath)
       "invalid_path"
     );
   }
-  const resolvedTarget = await realpath(target);
-  const relativeTarget = path2.relative(temporaryDirectory, resolvedTarget);
+  const [resolvedDirectory, resolvedTarget] = await Promise.all([
+    realpath(temporaryDirectory),
+    realpath(target)
+  ]);
+  const relativeTarget = path2.relative(resolvedDirectory, resolvedTarget);
   if (relativeTarget === "" || relativeTarget === ".." || relativeTarget.startsWith(`..${path2.sep}`) || path2.isAbsolute(relativeTarget)) {
     throw new DockerSandboxError(
       `Sandbox file escaped its temporary read boundary: ${sandboxPath}`,
@@ -1844,13 +1851,14 @@ async function removeVolume(dockerPath, volumeName) {
   );
 }
 function parseFindEntry(line, workdir) {
-  const [absolutePath, rawType, rawSize] = line.split("	");
-  if (absolutePath === void 0 || rawType === void 0 || rawSize === void 0) {
+  const [absolutePath, rawMode, rawSize] = line.split("	");
+  const mode = rawMode === void 0 ? Number.NaN : Number.parseInt(rawMode, 16);
+  if (absolutePath === void 0 || rawSize === void 0 || !Number.isSafeInteger(mode)) {
     throw new DockerSandboxError("Docker returned invalid file metadata.", "docker_command_failed");
   }
   const relativePath = path2.posix.relative(workdir, absolutePath);
   const size = Number(rawSize);
-  const type = mapFindType(rawType);
+  const type = mapFileMode(mode);
   let entry = {
     path: normalizeSandboxPath(relativePath),
     type
@@ -1860,12 +1868,21 @@ function parseFindEntry(line, workdir) {
   }
   return entry;
 }
-function mapFindType(value) {
-  if (value === "f") return "file";
-  if (value === "d") return "directory";
-  if (value === "l") return "symlink";
+function mapFileMode(mode) {
+  const type = mode & 61440;
+  if (type === 32768) return "file";
+  if (type === 16384) return "directory";
+  if (type === 40960) return "symlink";
   return "other";
 }
+function dockerExecFailureMessage(prefix, result) {
+  const detail = (safeDecode(result.stderr).trim() || safeDecode(result.stdout).trim()).slice(
+    0,
+    500
+  );
+  if (detail.length > 0) return `${prefix}: ${detail}`;
+  return result.status === "exited" ? `${prefix}: command exited with code ${result.exitCode}.` : `${prefix}: command timed out.`;
+}
 function toExecResult(result) {
   const common = {
     stdout: result.stdout.slice(),
@@ -2018,8 +2035,10 @@ var allToolNames = [
   "wait_for_port"
 ];
 var execCommandInput = z.object({
-  command: z.string().min(1),
-  args: z.array(z.string()).optional(),
+  command: z.string().min(1).describe(
+    "Command to run. Complete shell command lines are supported; 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(),
   env: z.record(z.string(), z.string()).optional(),
   timeoutMs: z.number().int().positive().max(3e5).optional(),
@@ -2149,17 +2168,17 @@ function createDockerSandboxTools(options) {
 function createExecCommandTool(options) {
   return createTool({
     name: "exec_command",
-    description: "Run one executable inside the sandbox with structured arguments.",
+    description: "Run a command inside the sandbox, including natural shell command lines.",
     inputSchema: execCommandInput,
     outputSchema: execResultOutput,
     execute: async ({ command, args, cwd, env, timeoutMs, input }, context) => {
-      assertCommandAllowed(command, options.exec?.commands);
+      const invocation = resolveExecInvocation(command, args, options.exec?.commands);
       const effectiveTimeoutMs = timeoutMs ?? options.exec?.defaultTimeoutMs;
       assertTimeoutAllowed(effectiveTimeoutMs, options.exec?.maxTimeoutMs);
       let execOptions = {
-        command
+        command: invocation.command
       };
-      if (args !== void 0) execOptions = { ...execOptions, args };
+      if (invocation.args !== void 0) execOptions = { ...execOptions, args: invocation.args };
       if (cwd !== void 0) {
         execOptions = { ...execOptions, cwd: normalizeToolPath(options.sandbox, cwd, true) };
       }
@@ -2519,6 +2538,22 @@ function assertCommandAllowed(command, policy) {
     }
   }
 }
+function resolveExecInvocation(command, args, policy) {
+  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] };
+  }
+  assertCommandAllowed(command, policy);
+  return args === void 0 ? { command } : { command, args };
+}
+function requiresShell(command) {
+  return /[\s|&;<>()$`'"*?[\]{}!#~=]/u.test(command);
+}
 function assertTimeoutAllowed(timeoutMs, maxTimeoutMs) {
   if (timeoutMs !== void 0 && maxTimeoutMs !== void 0 && timeoutMs > maxTimeoutMs) {
     throw toolPolicyError(`Command timeout exceeds policy (${timeoutMs} > ${maxTimeoutMs}).`);