Merge remote-tracking branch 'origin/cc-sandbox' into tool-governor

Author: Kaguya-19

extensions/edgeclaw-sandbox/openclaw.plugin.json

@@ -0,0 +1,78 @@
+{
+  "id": "edgeclaw-sandbox",
+  "name": "EdgeClaw OS Sandbox",
+  "description": "OS-level sandbox backend (bwrap/sandbox-exec) for EdgeClaw agents, powered by @anthropic-ai/sandbox-runtime.",
+  "version": "0.1.0",
+  "kind": "sandbox",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "network": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "allowedDomains": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Domain allowlist for outbound network access."
+          },
+          "deniedDomains": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Domain denylist for outbound network access."
+          },
+          "allowUnixSockets": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Unix socket paths to allow."
+          },
+          "allowAllUnixSockets": {
+            "type": "boolean",
+            "description": "Allow all Unix socket connections."
+          },
+          "allowLocalBinding": {
+            "type": "boolean",
+            "description": "Allow binding to localhost ports."
+          }
+        }
+      },
+      "filesystem": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "allowWrite": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Additional paths to allow writing (workspace is always included)."
+          },
+          "denyWrite": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Paths to deny writing."
+          },
+          "allowRead": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Additional paths to allow reading."
+          },
+          "denyRead": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Paths to deny reading."
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "network.allowedDomains": {
+      "label": "Allowed Domains",
+      "placeholder": "registry.npmjs.org, pypi.org"
+    },
+    "filesystem.denyWrite": {
+      "label": "Deny Write Paths",
+      "placeholder": "~/.ssh, ~/.gnupg"
+    }
+  }
+}

extensions/edgeclaw-sandbox/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@openclaw/edgeclaw-sandbox",
+  "version": "2026.4.1",
+  "private": true,
+  "description": "OS-level sandbox backend (bwrap/sandbox-exec) for EdgeClaw agents.",
+  "type": "module",
+  "dependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.46"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

extensions/edgeclaw-sandbox/src/bwrap-backend.ts

@@ -0,0 +1,130 @@
+import { spawn } from "node:child_process";
+import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import type {
+  CreateSandboxBackendParams,
+  SandboxBackendCommandParams,
+  SandboxBackendCommandResult,
+  SandboxBackendHandle,
+  SandboxBackendManager,
+} from "openclaw/plugin-sdk/sandbox";
+import { mapToSandboxRuntimeConfig, type EdgeClawSandboxPluginConfig } from "./config.js";
+
+let initialized = false;
+
+async function ensureInitialized(config: SandboxRuntimeConfig): Promise<void> {
+  if (initialized) {
+    SandboxManager.updateConfig(config);
+    return;
+  }
+  await SandboxManager.initialize(config);
+  initialized = true;
+}
+
+function runWrappedCommand(
+  wrappedCommand: string,
+  params: {
+    env: Record<string, string>;
+    stdin?: Buffer | string;
+    allowFailure?: boolean;
+    signal?: AbortSignal;
+  },
+): Promise<SandboxBackendCommandResult> {
+  return new Promise<SandboxBackendCommandResult>((resolve, reject) => {
+    const child = spawn("/bin/sh", ["-c", wrappedCommand], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...params.env },
+      signal: params.signal,
+    });
+
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+
+    child.stdout.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const stdout = Buffer.concat(stdoutChunks);
+      const stderr = Buffer.concat(stderrChunks);
+      const exitCode = code ?? 0;
+      if (exitCode !== 0 && !params.allowFailure) {
+        reject(
+          Object.assign(
+            new Error(`Sandbox command failed (exit ${exitCode}): ${stderr.toString("utf8")}`),
+            { code: exitCode, stdout, stderr },
+          ),
+        );
+        return;
+      }
+      resolve({ stdout, stderr, code: exitCode });
+    });
+
+    if (params.stdin !== undefined) {
+      child.stdin.end(params.stdin);
+    } else {
+      child.stdin.end();
+    }
+  });
+}
+
+export function createBwrapSandboxBackendFactory(
+  getPluginConfig: () => EdgeClawSandboxPluginConfig,
+) {
+  const factory = async (params: CreateSandboxBackendParams): Promise<SandboxBackendHandle> => {
+    const pluginConfig = getPluginConfig();
+    const runtimeConfig = mapToSandboxRuntimeConfig(
+      pluginConfig,
+      params.workspaceDir,
+      params.agentWorkspaceDir,
+    );
+    await ensureInitialized(runtimeConfig);
+
+    return {
+      id: "bwrap",
+      runtimeId: `bwrap-${params.scopeKey}`,
+      runtimeLabel: `OS Sandbox (${params.scopeKey})`,
+      workdir: params.workspaceDir,
+      env: params.cfg.docker.env,
+
+      async buildExecSpec({ command, workdir, env, usePty }) {
+        const wrapped = await SandboxManager.wrapWithSandbox(command);
+        return {
+          argv: ["/bin/sh", "-c", wrapped],
+          env: { ...process.env, ...env },
+          stdinMode: usePty ? ("pipe-open" as const) : ("pipe-closed" as const),
+        };
+      },
+
+      async runShellCommand(command: SandboxBackendCommandParams) {
+        const wrapped = await SandboxManager.wrapWithSandbox(command.script);
+        return runWrappedCommand(wrapped, {
+          env: {},
+          stdin: command.stdin,
+          allowFailure: command.allowFailure,
+          signal: command.signal,
+        });
+      },
+    };
+  };
+
+  return factory;
+}
+
+export const bwrapSandboxBackendManager: SandboxBackendManager = {
+  async describeRuntime() {
+    return {
+      running: SandboxManager.isSupportedPlatform(),
+      configLabelMatch: true,
+    };
+  },
+  async removeRuntime() {
+    // bwrap has no persistent runtime to remove
+  },
+};
+
+/**
+ * Reset internal initialization state.
+ * Exposed for testing only.
+ */
+export function resetBwrapState(): void {
+  initialized = false;
+}

extensions/edgeclaw-sandbox/src/config.ts

@@ -0,0 +1,56 @@
+import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+
+export type EdgeClawSandboxNetworkConfig = {
+  allowedDomains?: string[];
+  deniedDomains?: string[];
+  allowUnixSockets?: string[];
+  allowAllUnixSockets?: boolean;
+  allowLocalBinding?: boolean;
+};
+
+export type EdgeClawSandboxFilesystemConfig = {
+  allowWrite?: string[];
+  denyWrite?: string[];
+  allowRead?: string[];
+  denyRead?: string[];
+};
+
+export type EdgeClawSandboxPluginConfig = {
+  network?: EdgeClawSandboxNetworkConfig;
+  filesystem?: EdgeClawSandboxFilesystemConfig;
+};
+
+/**
+ * Convert EdgeClaw plugin config + backend params into the
+ * SandboxRuntimeConfig shape that @anthropic-ai/sandbox-runtime expects.
+ *
+ * The workspace directory is always added to allowWrite so sandboxed
+ * commands can operate on the agent's working tree.
+ */
+export function mapToSandboxRuntimeConfig(
+  pluginConfig: EdgeClawSandboxPluginConfig,
+  workspaceDir: string,
+  agentWorkspaceDir?: string,
+): SandboxRuntimeConfig {
+  const extraWritePaths = pluginConfig.filesystem?.allowWrite ?? [];
+  const allowWrite = [workspaceDir, ...extraWritePaths];
+  if (agentWorkspaceDir && agentWorkspaceDir !== workspaceDir) {
+    allowWrite.push(agentWorkspaceDir);
+  }
+
+  return {
+    network: {
+      allowedDomains: pluginConfig.network?.allowedDomains ?? [],
+      deniedDomains: pluginConfig.network?.deniedDomains ?? [],
+      allowUnixSockets: pluginConfig.network?.allowUnixSockets,
+      allowAllUnixSockets: pluginConfig.network?.allowAllUnixSockets,
+      allowLocalBinding: pluginConfig.network?.allowLocalBinding,
+    },
+    filesystem: {
+      allowWrite,
+      denyWrite: pluginConfig.filesystem?.denyWrite ?? [],
+      allowRead: pluginConfig.filesystem?.allowRead ?? [],
+      denyRead: pluginConfig.filesystem?.denyRead ?? [],
+    },
+  };
+}

extensions/edgeclaw-sandbox/src/fs-bridge.ts

@@ -0,0 +1,108 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type {
+  SandboxFsBridge,
+  SandboxFsStat,
+  SandboxResolvedPath,
+} from "openclaw/plugin-sdk/sandbox";
+
+/**
+ * Pass-through fsBridge for the bwrap backend.
+ *
+ * Since bwrap runs on the host filesystem (unlike Docker which has an
+ * isolated rootfs), all paths map to themselves — no docker-cp or
+ * remote-shell indirection is needed.
+ */
+export function createBwrapFsBridge(params: {
+  workspaceDir: string;
+  containerWorkdir: string;
+}): SandboxFsBridge {
+  const { workspaceDir, containerWorkdir } = params;
+
+  function resolveAbsolute(filePath: string, cwd?: string): string {
+    if (path.isAbsolute(filePath)) {
+      return filePath;
+    }
+    return path.resolve(cwd ?? workspaceDir, filePath);
+  }
+
+  return {
+    resolvePath(p: { filePath: string; cwd?: string }): SandboxResolvedPath {
+      const abs = resolveAbsolute(p.filePath, p.cwd);
+      const rel = path.relative(workspaceDir, abs);
+      return {
+        hostPath: abs,
+        relativePath: rel,
+        containerPath: path.join(containerWorkdir, rel),
+      };
+    },
+
+    async readFile(p: { filePath: string; cwd?: string; signal?: AbortSignal }): Promise<Buffer> {
+      const abs = resolveAbsolute(p.filePath, p.cwd);
+      return fs.readFile(abs, { signal: p.signal });
+    },
+
+    async writeFile(p: {
+      filePath: string;
+      cwd?: string;
+      data: Buffer | string;
+      encoding?: BufferEncoding;
+      mkdir?: boolean;
+      signal?: AbortSignal;
+    }): Promise<void> {
+      const abs = resolveAbsolute(p.filePath, p.cwd);
+      if (p.mkdir) {
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+      }
+      await fs.writeFile(abs, p.data, {
+        encoding: p.encoding,
+        signal: p.signal,
+      });
+    },
+
+    async mkdirp(p: { filePath: string; cwd?: string; signal?: AbortSignal }): Promise<void> {
+      const abs = resolveAbsolute(p.filePath, p.cwd);
+      await fs.mkdir(abs, { recursive: true });
+    },
+
+    async remove(p: {
+      filePath: string;
+      cwd?: string;
+      recursive?: boolean;
+      force?: boolean;
+      signal?: AbortSignal;
+    }): Promise<void> {
+      const abs = resolveAbsolute(p.filePath, p.cwd);
+      await fs.rm(abs, { recursive: p.recursive ?? false, force: p.force ?? false });
+    },
+
+    async rename(p: {
+      from: string;
+      to: string;
+      cwd?: string;
+      signal?: AbortSignal;
+    }): Promise<void> {
+      const absFrom = resolveAbsolute(p.from, p.cwd);
+      const absTo = resolveAbsolute(p.to, p.cwd);
+      await fs.rename(absFrom, absTo);
+    },
+
+    async stat(p: {
+      filePath: string;
+      cwd?: string;
+      signal?: AbortSignal;
+    }): Promise<SandboxFsStat | null> {
+      const abs = resolveAbsolute(p.filePath, p.cwd);
+      try {
+        const s = await fs.stat(abs);
+        return {
+          type: s.isDirectory() ? "directory" : s.isFile() ? "file" : "other",
+          size: s.size,
+          mtimeMs: s.mtimeMs,
+        };
+      } catch {
+        return null;
+      }
+    },
+  };
+}