fix(agents): expand leading tilde in exec workdir

bowenluo718 · bowenluo718 · commit 5a21c8c0dd60 · 2026-06-18T14:11:26.000+08:00
Add `expandTilde()` helper to handle `~` and `~/` prefixes in the `workdir` parameter of exec tool calls. The function expands leading tildes to the user's home directory before validating the path. Fixes issue #94434 where models emitting `workdir: "~/path"` would fail because the tilde was not expanded, causing the path validation to fail and fall back to a different directory while still executing the command. Changes: - Add `expandTilde()` function that handles `~`, `~/path`, and leaves other paths unchanged (absolute, relative, `~user` unsupported) - Modify `resolveWorkdir()` to call `expandTilde()` before validation - Add comprehensive unit tests for both functions covering all edge cases The fix is minimal and focused: only paths starting with `~` or `~/` are affected; all other path types continue to work as before. Fixes #94434
diff --git a/src/agents/bash-tools.shared.test.ts b/src/agents/bash-tools.shared.test.ts
@@ -1,13 +1,20 @@
+import { existsSync, statSync as statSyncCb } from "node:fs";
 /**
  * Shared bash-tool helper tests.
  * Covers strict env parsing and sandbox workdir mapping between container and
  * host workspace paths.
  */
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, statSync } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { deriveSessionName, readEnvInt, resolveSandboxWorkdir } from "./bash-tools.shared.js";
+import {
+  deriveSessionName,
+  expandTilde,
+  readEnvInt,
+  resolveSandboxWorkdir,
+  resolveWorkdir,
+} from "./bash-tools.shared.js";
 
 async function withTempDir(run: (dir: string) => Promise<void>) {
   const dir = await mkdtemp(path.join(os.tmpdir(), "openclaw-bash-workdir-"));
@@ -144,3 +151,121 @@ describe("deriveSessionName", () => {
     }
   });
 });
+
+describe("expandTilde", () => {
+  const homeDir = os.homedir();
+
+  it("expands ~ to home directory", () => {
+    expect(expandTilde("~")).toBe(homeDir);
+  });
+
+  it("expands ~/path to homeDir/path", () => {
+    expect(expandTilde("~/test/path")).toBe(`${homeDir}/test/path`);
+    expect(expandTilde("~/Documents/file.txt")).toBe(`${homeDir}/Documents/file.txt`);
+  });
+
+  it("leaves absolute paths unchanged", () => {
+    expect(expandTilde("/usr/local/bin")).toBe("/usr/local/bin");
+    expect(expandTilde("/home/user/test")).toBe("/home/user/test");
+  });
+
+  it("leaves relative paths unchanged", () => {
+    expect(expandTilde("src/index.ts")).toBe("src/index.ts");
+    expect(expandTilde("./local/path")).toBe("./local/path");
+    expect(expandTilde("../parent/path")).toBe("../parent/path");
+  });
+
+  it("handles empty string", () => {
+    expect(expandTilde("")).toBe("");
+  });
+
+  it("does not expand ~user syntax (not supported)", () => {
+    expect(expandTilde("~otheruser")).toBe("~otheruser");
+    expect(expandTilde("~otheruser/path")).toBe("~otheruser/path");
+  });
+
+  it("handles tilde in the middle or end of path", () => {
+    // These should not be expanded as they're not leading tildes
+    expect(expandTilde("/path/to/~cache")).toBe("/path/to/~cache");
+    expect(expandTilde("file~backup.txt")).toBe("file~backup.txt");
+  });
+});
+
+describe("resolveWorkdir", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("returns existing absolute path if valid directory", () => {
+    const tmpDir = path.join(os.tmpdir(), `openclaw-test-${Date.now()}`);
+    try {
+      require("node:fs").mkdirSync(tmpDir, { recursive: true });
+      const warnings: string[] = [];
+      const result = resolveWorkdir(tmpDir, warnings);
+      expect(result).toBe(tmpDir);
+      expect(warnings).toEqual([]);
+    } finally {
+      require("node:fs").rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("falls back for invalid relative path", async () => {
+    const tmpDir = path.join(os.tmpdir(), `openclaw-test-${Date.now()}`);
+    try {
+      await mkdir(tmpDir, { recursive: true });
+      const warnings: string[] = [];
+      // Test with a relative path that doesn't exist from any reasonable cwd
+      const result = resolveWorkdir("nonexistent_subdir_12345", warnings);
+      // Should fall back to cwd or homedir since the path doesn't exist
+      expect([process.cwd(), os.homedir()].includes(result)).toBe(true);
+      expect(warnings.length).toBe(1);
+      expect(warnings[0]).toMatch(/Warning: workdir "nonexistent_subdir_\d+" is unavailable/);
+    } finally {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("expands ~ to home directory and returns it if valid", () => {
+    const warnings: string[] = [];
+    const result = resolveWorkdir("~", warnings);
+    expect(result).toBe(os.homedir());
+    expect(warnings).toEqual([]);
+  });
+
+  it("expands ~/path and returns it if valid directory", async () => {
+    const testSubdir = `openclaw-test-${Date.now()}`;
+    const testPath = path.join(os.homedir(), testSubdir);
+    try {
+      await mkdir(testPath, { recursive: true });
+      const warnings: string[] = [];
+      const result = resolveWorkdir(`~/${testSubdir}`, warnings);
+      expect(result).toBe(testPath);
+      expect(warnings).toEqual([]);
+    } finally {
+      await rm(testPath, { recursive: true, force: true });
+    }
+  });
+
+  it("falls back with warning when expanded ~ path does not exist", () => {
+    const warnings: string[] = [];
+    const result = resolveWorkdir("~/nonexistent_dir_12345", warnings);
+    // Should fall back to cwd or homedir
+    expect(result).toBe(process.cwd() ?? os.homedir());
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toMatch(/Warning: workdir "~\/nonexistent_dir_\d+" is unavailable/);
+  });
+
+  it("falls back with warning for invalid absolute path", () => {
+    const warnings: string[] = [];
+    const result = resolveWorkdir("/nonexistent/path/12345", warnings);
+    expect(result).toBe(process.cwd() ?? os.homedir());
+    expect(warnings.length).toBe(1);
+  });
+
+  it("falls back with warning for invalid relative path", () => {
+    const warnings: string[] = [];
+    const result = resolveWorkdir("nonexistent/relative/path", warnings);
+    expect(result).toBe(process.cwd() ?? os.homedir());
+    expect(warnings.length).toBe(1);
+  });
+});
diff --git a/src/agents/bash-tools.shared.ts b/src/agents/bash-tools.shared.ts
@@ -179,14 +179,32 @@ function normalizeContainerPath(input: string): string {
   return path.posix.normalize(normalized);
 }
 
+/** Expands a leading ~ or ~/ to the user's home directory. */
+export function expandTilde(input: string): string {
+  if (!input) {
+    return input;
+  }
+  if (input === "~") {
+    return homedir();
+  }
+  if (input.startsWith("~/")) {
+    return homedir() + input.slice(1);
+  }
+  return input;
+}
+
 /** Resolves a host workdir, falling back to a safe cwd/home path with a warning. */
 export function resolveWorkdir(workdir: string, warnings: string[]) {
   const current = safeCwd();
   const fallback = current ?? homedir();
+
+  // Expand leading tilde before validating the path
+  const expandedWorkdir = expandTilde(workdir);
+
   try {
-    const stats = statSync(workdir);
+    const stats = statSync(expandedWorkdir);
     if (stats.isDirectory()) {
-      return workdir;
+      return expandedWorkdir;
     }
   } catch {
     // ignore, fallback below
