Skip to content

The open-source app everyone uses to manage agents at work

fix: support Windows command wrappers for local adapters

online5880d7b98a72b4aa
diff --git a/package.json b/package.json
index 45c02b8b5e..8b35d0baa4 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
"type": "module",
"scripts": {
"dev": "node scripts/dev-runner.mjs watch",
- "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
+ "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
"dev:once": "node scripts/dev-runner.mjs dev",
"dev:server": "pnpm --filter @paperclipai/server dev",
"dev:ui": "pnpm --filter @paperclipai/ui dev",
@@ -29,6 +29,7 @@
},
"devDependencies": {
"@changesets/cli": "^2.30.0",
+ "cross-env": "^10.1.0",
"esbuild": "^0.27.3",
"typescript": "^5.7.3",
"vitest": "^3.0.5"
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index 76efba86a2..8a2961913e 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -15,6 +15,11 @@ interface RunningProcess {
graceSec: number;
}
+interface SpawnTarget {
+ command: string;
+ args: string[];
+}
+
type ChildProcessWithEvents = ChildProcess & {
on(event: "error", listener: (err: Error) => void): ChildProcess;
on(
@@ -125,6 +130,78 @@ export function defaultPathForPlatform() {
return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
}
+function windowsPathExts(env: NodeJS.ProcessEnv): string[] {
+ return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+}
+
+async function pathExists(candidate: string) {
+ try {
+ await fs.access(candidate, fsConstants.X_OK);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function resolveCommandPath(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string | null> {
+ const hasPathSeparator = command.includes("/") || command.includes("\\");
+ if (hasPathSeparator) {
+ const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+ return (await pathExists(absolute)) ? absolute : null;
+ }
+
+ const pathValue = env.PATH ?? env.Path ?? "";
+ const delimiter = process.platform === "win32" ? ";" : ":";
+ const dirs = pathValue.split(delimiter).filter(Boolean);
+ const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
+ const hasExtension = process.platform === "win32" && path.extname(command).length > 0;
+
+ for (const dir of dirs) {
+ const candidates =
+ process.platform === "win32"
+ ? hasExtension
+ ? [path.join(dir, command)]
+ : exts.map((ext) => path.join(dir, `${command}${ext}`))
+ : [path.join(dir, command)];
+ for (const candidate of candidates) {
+ if (await pathExists(candidate)) return candidate;
+ }
+ }
+
+ return null;
+}
+
+function quoteForCmd(arg: string) {
+ if (!arg.length) return '""';
+ const escaped = arg.replace(/"/g, '""').replace(/%/g, "%%");
+ return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
+}
+
+async function resolveSpawnTarget(
+ command: string,
+ args: string[],
+ cwd: string,
+ env: NodeJS.ProcessEnv,
+): Promise<SpawnTarget> {
+ const resolved = await resolveCommandPath(command, cwd, env);
+ const executable = resolved ?? command;
+
+ if (process.platform !== "win32") {
+ return { command: executable, args };
+ }
+
+ if (/\.(cmd|bat)$/i.test(executable)) {
+ const shell = env.ComSpec || process.env.ComSpec || "cmd.exe";
+ const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
+ return {
+ command: shell,
+ args: ["/d", "/s", "/c", commandLine],
+ };
+ }
+
+ return { command: executable, args };
+}
+
export function ensurePathInEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
if (typeof env.PATH === "string" && env.PATH.length > 0) return env;
if (typeof env.Path === "string" && env.Path.length > 0) return env;
@@ -169,36 +246,12 @@ export async function ensureAbsoluteDirectory(
}
export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
- const hasPathSeparator = command.includes("/") || command.includes("\\");
- if (hasPathSeparator) {
+ const resolved = await resolveCommandPath(command, cwd, env);
+ if (resolved) return;
+ if (command.includes("/") || command.includes("\\")) {
const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
- try {
- await fs.access(absolute, fsConstants.X_OK);
- } catch {
- throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
- }
- return;
- }
-
- const pathValue = env.PATH ?? env.Path ?? "";
- const delimiter = process.platform === "win32" ? ";" : ":";
- const dirs = pathValue.split(delimiter).filter(Boolean);
- const windowsExt = process.platform === "win32"
- ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
- : [""];
-
- for (const dir of dirs) {
- for (const ext of windowsExt) {
- const candidate = path.join(dir, process.platform === "win32" ? `${command}${ext}` : command);
- try {
- await fs.access(candidate, fsConstants.X_OK);
- return;
- } catch {
- // continue scanning PATH
- }
- }
+ throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
}
-
throw new Error(`Command not found in PATH: "${command}"`);
}
@@ -220,78 +273,82 @@ export async function runChildProcess(
return new Promise<RunProcessResult>((resolve, reject) => {
const mergedEnv = ensurePathInEnv({ ...process.env, ...opts.env });
- const child = spawn(command, args, {
- cwd: opts.cwd,
- env: mergedEnv,
- shell: false,
- stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
- }) as ChildProcessWithEvents;
-
- if (opts.stdin != null && child.stdin) {
- child.stdin.write(opts.stdin);
- child.stdin.end();
- }
+ void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
+ .then((target) => {
+ const child = spawn(target.command, target.args, {
+ cwd: opts.cwd,
+ env: mergedEnv,
+ shell: false,
+ stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+ }) as ChildProcessWithEvents;
+
+ if (opts.stdin != null && child.stdin) {
+ child.stdin.write(opts.stdin);
+ child.stdin.end();
+ }
+
+ runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+
+ let timedOut = false;
+ let stdout = "";
+ let stderr = "";
+ let logChain: Promise<void> = Promise.resolve();
+
+ const timeout =
+ opts.timeoutSec > 0
+ ? setTimeout(() => {
+ timedOut = true;
+ child.kill("SIGTERM");
+ setTimeout(() => {
+ if (!child.killed) {
+ child.kill("SIGKILL");
+ }
+ }, Math.max(1, opts.graceSec) * 1000);
+ }, opts.timeoutSec * 1000)
+ : null;
+
+ child.stdout?.on("data", (chunk: unknown) => {
+ const text = String(chunk);
+ stdout = appendWithCap(stdout, text);
+ logChain = logChain
+ .then(() => opts.onLog("stdout", text))
+ .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+ });
+
+ child.stderr?.on("data", (chunk: unknown) => {
+ const text = String(chunk);
+ stderr = appendWithCap(stderr, text);
+ logChain = logChain
+ .then(() => opts.onLog("stderr", text))
+ .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
+ });
+
+ child.on("error", (err: Error) => {
+ if (timeout) clearTimeout(timeout);
+ runningProcesses.delete(runId);
+ const errno = (err as NodeJS.ErrnoException).code;
+ const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+ const msg =
+ errno === "ENOENT"
+ ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
+ : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+ reject(new Error(msg));
+ });
- runningProcesses.set(runId, { child, graceSec: opts.graceSec });
-
- let timedOut = false;
- let stdout = "";
- let stderr = "";
- let logChain: Promise<void> = Promise.resolve();
-
- const timeout =
- opts.timeoutSec > 0
- ? setTimeout(() => {
- timedOut = true;
- child.kill("SIGTERM");
- setTimeout(() => {
- if (!child.killed) {
- child.kill("SIGKILL");
- }
- }, Math.max(1, opts.graceSec) * 1000);
- }, opts.timeoutSec * 1000)
- : null;
-
- child.stdout?.on("data", (chunk: unknown) => {
- const text = String(chunk);
- stdout = appendWithCap(stdout, text);
- logChain = logChain
- .then(() => opts.onLog("stdout", text))
- .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
- });
-
- child.stderr?.on("data", (chunk: unknown) => {
- const text = String(chunk);
- stderr = appendWithCap(stderr, text);
- logChain = logChain
- .then(() => opts.onLog("stderr", text))
- .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
- });
-
- child.on("error", (err: Error) => {
- if (timeout) clearTimeout(timeout);
- runningProcesses.delete(runId);
- const errno = (err as NodeJS.ErrnoException).code;
- const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
- const msg =
- errno === "ENOENT"
- ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
- : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
- reject(new Error(msg));
- });
-
- child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
- if (timeout) clearTimeout(timeout);
- runningProcesses.delete(runId);
- void logChain.finally(() => {
- resolve({
- exitCode: code,
- signal,
- timedOut,
- stdout,
- stderr,
+ child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+ if (timeout) clearTimeout(timeout);
+ runningProcesses.delete(runId);
+ void logChain.finally(() => {
+ resolve({
+ exitCode: code,
+ signal,
+ timedOut,
+ stdout,
+ stderr,
+ });
+ });
});
- });
- });
+ })
+ .catch(reject);
});
}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ff4f3e35ef..8027020738 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,6 +11,9 @@ importers:
'@changesets/cli':
specifier: ^2.30.0
version: 2.30.0(@types/[email protected])
+ cross-env:
+ specifier: ^10.1.0
+ version: 10.1.0
esbuild:
specifier: ^0.27.3
version: 0.27.3
@@ -35,9 +38,6 @@ importers:
'@paperclipai/adapter-cursor-local':
specifier: workspace:*
version: link:../packages/adapters/cursor-local
- '@paperclipai/adapter-openclaw':
- specifier: workspace:*
- version: link:../packages/adapters/openclaw
'@paperclipai/adapter-openclaw-gateway':
specifier: workspace:*
version: link:../packages/adapters/openclaw-gateway
@@ -139,22 +139,6 @@ importers:
specifier: ^5.7.3
version: 5.9.3
- packages/adapters/openclaw:
- dependencies:
- '@paperclipai/adapter-utils':
- specifier: workspace:*
- version: link:../../adapter-utils
- picocolors:
- specifier: ^1.1.1
- version: 1.1.1
- devDependencies:
- '@types/node':
- specifier: ^24.6.0
- version: 24.12.0
- typescript:
- specifier: ^5.7.3
- version: 5.9.3
-
packages/adapters/openclaw-gateway:
dependencies:
'@paperclipai/adapter-utils':
@@ -261,9 +245,6 @@ importers:
'@paperclipai/adapter-cursor-local':
specifier: workspace:*
version: link:../packages/adapters/cursor-local
- '@paperclipai/adapter-openclaw':
- specifier: workspace:*
- version: link:../packages/adapters/openclaw
'@paperclipai/adapter-openclaw-gateway':
specifier: workspace:*
version: link:../packages/adapters/openclaw-gateway
@@ -379,9 +360,6 @@ importers:
'@paperclipai/adapter-cursor-local':
specifier: workspace:*
version: link:../packages/adapters/cursor-local
- '@paperclipai/adapter-openclaw':
- specifier: workspace:*
- version: link:../packages/adapters/openclaw
'@paperclipai/adapter-openclaw-gateway':
specifier: workspace:*
version: link:../packages/adapters/openclaw-gateway
@@ -1011,6 +989,9 @@ packages:
cpu: [x64]
os: [win32]
+ '@epic-web/[email protected]':
+ resolution: {integrity: sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==}
+
'@esbuild-kit/[email protected]':
resolution: {integrity: sha512-sPRAnw9CdSsRmEtnsl2WXWdyquogVpB3yZ3dgwJfe8zrOzTsV7cJvmwrKVa+0ma5BoiGJ+BoqkMvawbayKUsqQ==}
deprecated: 'Merged into tsx: https://tsx.is'
@@ -3441,6 +3422,11 @@ packages:
resolution: {integrity: sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==}
+ resolution: {integrity: sha512-GsYosgnACZTADcmEyJctkJIoqAhHjttw7RsFrVoJNXbsWWqaq6Ym+7kZjq6mS45O0jij6vtiReppKQEtqWy6Dw==}
+ engines: {node: '>=20'}
+ hasBin: true
+
resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
engines: {node: '>= 8'}
@@ -6743,6 +6729,8 @@ snapshots:
'@embedded-postgres/[email protected]':
optional: true
+ '@epic-web/[email protected]': {}
+
'@esbuild-kit/[email protected]':
dependencies:
esbuild: 0.18.20
@@ -8942,14 +8930,6 @@ snapshots:
chai: 5.3.3
tinyrainbow: 2.0.0
- dependencies:
- '@vitest/spy': 3.2.4
- estree-walker: 3.0.3
- magic-string: 0.30.21
- optionalDependencies:
-
dependencies:
'@vitest/spy': 3.2.4
@@ -9253,6 +9233,11 @@ snapshots:
+ dependencies:
+ '@epic-web/invariant': 1.0.0
+ cross-spawn: 7.0.6
+
dependencies:
path-key: 3.1.1
@@ -11722,7 +11707,7 @@ snapshots:
dependencies:
'@types/chai': 5.2.3
'@vitest/expect': 3.2.4
'@vitest/pretty-format': 3.2.4
'@vitest/runner': 3.2.4
'@vitest/snapshot': 3.2.4
diff --git a/server/package.json b/server/package.json
index 3e74286b8f..2b3e1ed071 100644
--- a/server/package.json
+++ b/server/package.json
@@ -23,7 +23,7 @@
],
"scripts": {
"dev": "tsx src/index.ts",
- "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
+ "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
"build": "tsc",
"clean": "rm -rf dist",
"start": "node dist/index.js",
diff --git a/server/src/__tests__/codex-local-adapter-environment.test.ts b/server/src/__tests__/codex-local-adapter-environment.test.ts
index 9814334d6d..bf42e47d66 100644
--- a/server/src/__tests__/codex-local-adapter-environment.test.ts
+++ b/server/src/__tests__/codex-local-adapter-environment.test.ts
@@ -29,4 +29,47 @@ describe("codex_local environment diagnostics", () => {
expect(stats.isDirectory()).toBe(true);
await fs.rm(path.dirname(cwd), { recursive: true, force: true });
});
+
+ it("runs the hello probe when Codex is available via a Windows .cmd wrapper", async () => {
+ if (process.platform !== "win32") return;
+
+ const root = path.join(
+ os.tmpdir(),
+ `paperclip-codex-local-probe-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+ );
+ const binDir = path.join(root, "bin");
+ const cwd = path.join(root, "workspace");
+ const fakeCodex = path.join(binDir, "codex.cmd");
+ const script = [
+ "@echo off",
+ "echo {\"type\":\"thread.started\",\"thread_id\":\"test-thread\"}",
+ "echo {\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"hello\"}}",
+ "echo {\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":1,\"cached_input_tokens\":0,\"output_tokens\":1}}",
+ "exit /b 0",
+ "",
+ ].join("\r\n");
+
+ try {
+ await fs.mkdir(binDir, { recursive: true });
+ await fs.writeFile(fakeCodex, script, "utf8");
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "codex_local",
+ config: {
+ command: "codex",
+ cwd,
+ env: {
+ OPENAI_API_KEY: "test-key",
+ PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
+ },
+ },
+ });
+
+ expect(result.status).toBe("pass");
+ expect(result.checks.some((check) => check.code === "codex_hello_probe_passed")).toBe(true);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+ });
});