Sandbox: improve missing-python3 write/edit error guidance

tonga54 · tonga54 · commit 8219dbccc312 · 2026-03-29T01:05:20.000-03:00
diff --git a/src/agents/sandbox/fs-bridge.shell.test.ts b/src/agents/sandbox/fs-bridge.shell.test.ts
@@ -5,6 +5,7 @@ import {
   createSandbox,
   createSandboxFsBridge,
   createSeededSandboxFsBridge,
+  getDockerScript,
   getScriptsFromCalls,
   installFsBridgeTestHarness,
   mockedExecDockerRaw,
@@ -140,6 +141,35 @@ describe("sandbox fs bridge shell compatibility", () => {
     expect(scripts.some((script) => script.includes("os.replace("))).toBe(true);
   });
 
+  it("surfaces actionable guidance when sandbox python3 is missing", async () => {
+    const bridge = createSandboxFsBridge({ sandbox: createSandbox() });
+    const baseImpl = mockedExecDockerRaw.getMockImplementation();
+    mockedExecDockerRaw.mockImplementation(async (...callArgs) => {
+      const args = callArgs[0] as string[];
+      if (getDockerScript(args).includes("operation = sys.argv[1]")) {
+        const message = "moltbot-sandbox-fs: 2: python3: not found";
+        const err = Object.assign(new Error(message), {
+          code: 127,
+          stdout: Buffer.alloc(0),
+          stderr: Buffer.from(message),
+        });
+        throw err;
+      }
+      if (baseImpl) {
+        return await baseImpl(...callArgs);
+      }
+      return {
+        stdout: Buffer.alloc(0),
+        stderr: Buffer.alloc(0),
+        code: 0,
+      };
+    });
+
+    await expect(bridge.writeFile({ filePath: "b.txt", data: "hello" })).rejects.toThrow(
+      /requires `python3` inside the sandbox container/i,
+    );
+  });
+
   it("routes mkdirp, remove, and rename through the pinned mutation helper", async () => {
     await withTempDir("openclaw-fs-bridge-shell-write-", async (stateDir) => {
       const { bridge } = await createSeededSandboxFsBridge(stateDir, {
diff --git a/src/agents/sandbox/fs-bridge.ts b/src/agents/sandbox/fs-bridge.ts
@@ -14,6 +14,7 @@ import {
   resolveSandboxFsPathWithMounts,
   type SandboxResolvedFsPath,
 } from "./fs-paths.js";
+import { toFriendlySandboxMutationError } from "./mutation-errors.js";
 import type { SandboxContext, SandboxWorkspaceAccess } from "./types.js";
 
 type RunCommandOptions = {
@@ -286,12 +287,19 @@ class SandboxFsBridgeImpl implements SandboxFsBridge {
     if (plan.recheckBeforeCommand) {
       await this.pathGuard.assertPathChecks(plan.checks);
     }
-    return await this.runCommand(plan.script, {
-      args: plan.args,
-      stdin: plan.stdin,
-      allowFailure: plan.allowFailure,
-      signal: plan.signal,
-    });
+    try {
+      return await this.runCommand(plan.script, {
+        args: plan.args,
+        stdin: plan.stdin,
+        allowFailure: plan.allowFailure,
+        signal: plan.signal,
+      });
+    } catch (error) {
+      if (plan.script.includes("python3 /dev/fd/3")) {
+        throw toFriendlySandboxMutationError(error);
+      }
+      throw error;
+    }
   }
 
   private async runPlannedCommand(
diff --git a/src/agents/sandbox/mutation-errors.ts b/src/agents/sandbox/mutation-errors.ts
@@ -0,0 +1,17 @@
+const PYTHON3_MISSING_RE = /\bpython3:\s*not found\b/i;
+
+/**
+ * Provide actionable guidance when mutation helpers fail because the sandbox image
+ * is missing Python. This keeps write/edit errors from surfacing as opaque shell
+ * stderr blobs.
+ */
+export function toFriendlySandboxMutationError(error: unknown): Error {
+  const rawMessage = error instanceof Error ? error.message : String(error);
+  if (!PYTHON3_MISSING_RE.test(rawMessage)) {
+    return error instanceof Error ? error : new Error(rawMessage);
+  }
+  return new Error(
+    "Sandbox write/edit requires `python3` inside the sandbox container, but it is missing in the active image. Rebuild or update the sandbox image (or configure a custom sandbox image that includes `python3`). Original error: " +
+      rawMessage,
+  );
+}
diff --git a/src/agents/sandbox/remote-fs-bridge.ts b/src/agents/sandbox/remote-fs-bridge.ts
@@ -4,6 +4,7 @@ import type { SandboxBackendCommandParams, SandboxBackendCommandResult } from ".
 import { SANDBOX_PINNED_MUTATION_PYTHON } from "./fs-bridge-mutation-helper.js";
 import { createWritableRenameTargetResolver } from "./fs-bridge-rename-targets.js";
 import type { SandboxFsBridge, SandboxFsStat, SandboxResolvedPath } from "./fs-bridge.js";
+import { toFriendlySandboxMutationError } from "./mutation-errors.js";
 import {
   isPathInsideContainerRoot,
   normalizeContainerPath as normalizeSandboxContainerPath,
@@ -472,18 +473,22 @@ class RemoteShellSandboxFsBridge implements SandboxFsBridge {
     signal?: AbortSignal;
     allowFailure?: boolean;
   }) {
-    await this.runRemoteScript({
-      script: [
-        "set -eu",
-        "python3 /dev/fd/3 \"$@\" 3<<'PY'",
-        SANDBOX_PINNED_MUTATION_PYTHON,
-        "PY",
-      ].join("\n"),
-      args: params.args,
-      stdin: params.stdin,
-      signal: params.signal,
-      allowFailure: params.allowFailure,
-    });
+    try {
+      await this.runRemoteScript({
+        script: [
+          "set -eu",
+          "python3 /dev/fd/3 \"$@\" 3<<'PY'",
+          SANDBOX_PINNED_MUTATION_PYTHON,
+          "PY",
+        ].join("\n"),
+        args: params.args,
+        stdin: params.stdin,
+        signal: params.signal,
+        allowFailure: params.allowFailure,
+      });
+    } catch (error) {
+      throw toFriendlySandboxMutationError(error);
+    }
   }
 
   private async runRemoteScript(params: {
