Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(frontend): validate OH_AGENT_SERVER_LOCAL_PATH in dev-with-automation (#650)

Hiep Lef42d684a0391
diff --git a/__tests__/scripts/dev-with-automation.test.ts b/__tests__/scripts/dev-with-automation.test.ts
index 01ab69dd9c..3f396aa3e9 100644
--- a/__tests__/scripts/dev-with-automation.test.ts
+++ b/__tests__/scripts/dev-with-automation.test.ts
@@ -8,7 +8,7 @@
import net from "node:net";
import { spawn } from "node:child_process";
import { once } from "node:events";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import path from "node:path";
import { setTimeout as delay } from "node:timers/promises";
@@ -450,11 +450,77 @@ describe("dev-with-automation CLI", () => {
expect(output).toContain("--static");
expect(output).toContain("--dynamic");
expect(output).toContain("OH_AUTOMATION_GIT_REF");
+ expect(output).toContain("OH_AGENT_SERVER_LOCAL_PATH");
expect(output).toContain("AUTOMATION_LOCAL_API_KEY");
expect(output).toContain("OPENHANDS_AUTOMATION_API_KEY");
expect(output).toContain("SECRETS:");
});
+ it("fails fast with a clear error when OH_AGENT_SERVER_LOCAL_PATH is invalid", async () => {
+ // Arrange: an absolute but empty directory β€” `validateLocalAgentServerPath`
+ // requires the four workspace subdirs (openhands-agent-server, openhands-sdk,
+ // openhands-tools, openhands-workspace) and must reject this.
+ const emptyDir = mkdtempSync(path.join(tmpdir(), "bad-sdk-"));
+
+ // Stub a no-op `uvx` on PATH so `checkPrerequisites` passes even on CI
+ // runners that don't have uv installed. The prerequisite check must
+ // succeed so the LOCAL_PATH validation guard (the actual subject of this
+ // test, which runs immediately after) is exercised.
+ const stubBinDir = mkdtempSync(path.join(tmpdir(), "stub-bin-"));
+ writeFileSync(path.join(stubBinDir, "uvx"), "#!/bin/sh\nexit 0\n", {
+ mode: 0o755,
+ });
+
+ // Act: spawn `dev-with-automation.mjs` with that path set. Stubbed `uvx`
+ // is prepended to PATH so the prerequisite check passes; the validation
+ // guard must trip *after* those checks but *before* port allocation, so
+ // we can assert on both the error message and the absence of side effects.
+ const child = spawn(process.execPath, ["scripts/dev-with-automation.mjs"], {
+ cwd: repoRoot,
+ env: {
+ PATH: `${stubBinDir}:${process.env.PATH ?? ""}`,
+ HOME: process.env.HOME ?? "",
+ OH_AGENT_SERVER_LOCAL_PATH: emptyDir,
+ },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+
+ let output = "";
+ child.stdout.on("data", (chunk) => {
+ output += chunk.toString();
+ });
+ child.stderr.on("data", (chunk) => {
+ output += chunk.toString();
+ });
+
+ const exitResult = await Promise.race([
+ once(child, "exit").then(([code, signal]) => ({
+ code,
+ signal,
+ timedOut: false,
+ })),
+ delay(10_000).then(() => ({ code: null, signal: null, timedOut: true })),
+ ]);
+
+ if (exitResult.timedOut) {
+ child.kill("SIGKILL");
+ }
+
+ try {
+ // Assert: process exits non-zero, surfaces the validator's error, and
+ // never reaches `buildConfig` (no `[ports] Allocating ports...` log).
+ expect(exitResult.timedOut).toBe(false);
+ expect(exitResult.code).toBe(1);
+ expect(output).toContain(
+ "OH_AGENT_SERVER_LOCAL_PATH is missing expected workspace package",
+ );
+ expect(output).not.toContain("Allocating ports");
+ } finally {
+ rmSync(emptyDir, { recursive: true, force: true });
+ rmSync(stubBinDir, { recursive: true, force: true });
+ }
+ });
+
it("exits promptly when uvx is missing", async () => {
const child = spawn(process.execPath, ["scripts/dev-with-automation.mjs"], {
cwd: repoRoot,
diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjs
index 1508e262fb..a8a82b8416 100644
--- a/scripts/dev-with-automation.mjs
+++ b/scripts/dev-with-automation.mjs
@@ -29,6 +29,11 @@
* Environment variables:
* - PORT: Ingress port (default: 8000)
* - OH_AUTOMATION_GIT_REF: Git ref for automation (default: main)
+ * - OH_AGENT_SERVER_LOCAL_PATH: Absolute path to a local software-agent-sdk
+ * checkout. Highest precedence for agent-server source selection: rebuilds
+ * the agent-server from local source and installs openhands-sdk,
+ * openhands-tools and openhands-workspace as editable so source edits are
+ * picked up without manual reinstall.
* - OH_AGENT_SERVER_GIT_REF: Git ref for agent-server
* - AUTOMATION_LOCAL_API_KEY: Custom API key for automation backend auth
* - OH_AUTOMATION_API_KEY_PATH: Override persisted default automation key path
@@ -56,6 +61,7 @@ import {
findFreePorts,
getOrCreatePersistedApiKey,
validateFrontendDependencies,
+ validateLocalAgentServerPath,
} from "./dev-safe.mjs";
import {
createShutdownHookRegistry,
@@ -203,6 +209,7 @@ ENVIRONMENT VARIABLES:
PORT Alternative to --port
OH_AUTOMATION_GIT_REF Git ref for automation (overrides default version)
OH_AUTOMATION_VERSION Specific PyPI version for automation (default: ${DEFAULT_AUTOMATION_VERSION})
+ OH_AGENT_SERVER_LOCAL_PATH Absolute path to a local software-agent-sdk checkout (highest precedence)
OH_AGENT_SERVER_GIT_REF Git ref for agent-server SDK (overrides default version)
OH_AGENT_SERVER_VERSION Specific PyPI version for agent-server
OH_SECRET_KEY Secret key for sessions
@@ -966,6 +973,19 @@ async function main(options = {}) {
!useStaticMode || typeof buildStaticFrontend === "function",
});
+ // Fail fast on an obviously bad OH_AGENT_SERVER_LOCAL_PATH so we don't waste
+ // time allocating ports / generating keys / launching uvx with a path that
+ // would only produce a cryptic build error. Mirrors dev-safe.mjs and
+ // dev-extra-backend.mjs.
+ if (process.env.OH_AGENT_SERVER_LOCAL_PATH) {
+ try {
+ validateLocalAgentServerPath(process.env.OH_AGENT_SERVER_LOCAL_PATH);
+ } catch (error) {
+ logError(error instanceof Error ? error.message : String(error));
+ process.exit(1);
+ }
+ }
+
// Build config with dynamic port allocation
const config = await buildConfig(args);
if (viteWorkingDir) config.viteWorkingDir = viteWorkingDir;