Sandbox: add actionable error when docker missing (#28547)

Co-authored-by: AaronWander <siralonne@163.com>

src/agents/sandbox/docker.execDockerRaw.enoent.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { withEnvAsync } from "../../test-utils/env.js";
+import { execDockerRaw } from "./docker.js";
+
+describe("execDockerRaw", () => {
+  it("wraps docker ENOENT with an actionable configuration error", async () => {
+    await withEnvAsync({ PATH: "" }, async () => {
+      let err: unknown;
+      try {
+        await execDockerRaw(["version"]);
+      } catch (caught) {
+        err = caught;
+      }
+
+      expect(err).toBeInstanceOf(Error);
+      expect(err).toMatchObject({ code: "INVALID_CONFIG" });
+      expect((err as Error).message).toContain("Sandbox mode requires Docker");
+      expect((err as Error).message).toContain("agents.defaults.sandbox.mode=off");
+    });
+  });
+});

src/agents/sandbox/docker.ts

@@ -65,6 +65,21 @@ export function execDockerRaw(
       if (signal) {
         signal.removeEventListener("abort", handleAbort);
       }
+      if (
+        error &&
+        typeof error === "object" &&
+        "code" in error &&
+        (error as NodeJS.ErrnoException).code === "ENOENT"
+      ) {
+        const friendly = Object.assign(
+          new Error(
+            'Sandbox mode requires Docker, but the "docker" command was not found in PATH. Install Docker (and ensure "docker" is available), or set `agents.defaults.sandbox.mode=off` to disable sandboxing.',
+          ),
+          { code: "INVALID_CONFIG", cause: error },
+        );
+        reject(friendly);
+        return;
+      }
       reject(error);
     });