π OpenHands: AI-Driven Development
fix(launcher): pin uvx to Python 3.12-3.14 until deps ship 3.15 wheels (#18731)
Vasco Schiavo4b147dcff291
diff --git a/.agents/skills/local-stack-runtime/references/guide.md b/.agents/skills/local-stack-runtime/references/guide.mdindex c1e813fffc..38b3b687b5 100644--- a/.agents/skills/local-stack-runtime/references/guide.md+++ b/.agents/skills/local-stack-runtime/references/guide.md@@ -93,6 +93,7 @@ you are running inside of β NOT the automation backend.- `OH_AGENT_SERVER_LOCAL_PATH` β absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.- `OH_AGENT_SERVER_GIT_REF` β git commit SHA or branch name (takes precedence over version)- `OH_AGENT_SERVER_VERSION` β specific PyPI version (e.g., "1.56.0")+ - `UV_PYTHON` β Python version or range uvx may use for agent-server and automation. Defaults to `python.uvxRequest` in `config/defaults.json` (`>=3.12,<3.15`), so a machine with no supported Python downloads the newest 3.14 instead of the newest CPython, whose wheels the SDK's compiled dependencies lag behind (#18654).- `OH_SECRET_KEY` β secret key for settings encryption; auto-generated and persisted to `~/.openhands/agent-canvas/secret-key.txt` on first run (same file Docker uses), ensuring dev mode and Docker share the same key when both mount the same `~/.openhands` directory. Override with the env var to pin a specific key.- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` β session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)- Default: released PyPI version `1.56.0` for agent-server SDK librariesdiff --git a/.pr/uvx-python-pin-after-canvas.png b/.pr/uvx-python-pin-after-canvas.pngnew file mode 100644index 0000000000..74cb675b1cBinary files /dev/null and b/.pr/uvx-python-pin-after-canvas.png differdiff --git a/.pr/uvx-python-pin-before-after.png b/.pr/uvx-python-pin-before-after.pngnew file mode 100644index 0000000000..2dd779bfe5Binary files /dev/null and b/.pr/uvx-python-pin-before-after.png differdiff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.tsindex b351fce91e..a3e3fdf823 100644--- a/__tests__/scripts/dev-safe.test.ts+++ b/__tests__/scripts/dev-safe.test.ts@@ -23,6 +23,7 @@ import {buildAgentServerEnv,buildAgentServerTelemetryEnv,buildRuntimeServicesInfo,+ buildUvxPythonArgs,formatMissingUvxGuidance,formatMissingFrontendDependenciesGuidance,getMissingFrontendDependencyBins,@@ -540,6 +541,8 @@ describe("buildAgentServerCommand", () => {expect(cmd.command).toBe("uvx");// Defaults to the released PyPI version with all SDK packages pinned to same versionexpect(cmd.args).toEqual([+ "--python",+ ">=3.12,<3.15","--from","openhands-agent-server==1.56.0","--with",@@ -564,6 +567,8 @@ describe("buildAgentServerCommand", () => {// Uses --from syntax because executable name (agent-server) differs from package name (openhands-agent-server)// All SDK packages are pinned to the same versionexpect(cmd.args).toEqual([+ "--python",+ ">=3.12,<3.15","--from","openhands-agent-server==1.18.0","--with",@@ -588,6 +593,8 @@ describe("buildAgentServerCommand", () => {expect(cmd.command).toBe("uvx");expect(cmd.args).toEqual([+ "--python",+ ">=3.12,<3.15","--reinstall","--from","git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-agent-server",@@ -611,6 +618,8 @@ describe("buildAgentServerCommand", () => {expect(cmd.command).toBe("uvx");expect(cmd.args).toEqual([+ "--python",+ ">=3.12,<3.15","--reinstall","--from","git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-agent-server",@@ -649,6 +658,8 @@ describe("buildAgentServerCommand", () => {expect(cmd.command).toBe("uvx");expect(cmd.args).toEqual([+ "--python",+ ">=3.12,<3.15","--reinstall","--from",path.join(sdk, "openhands-agent-server"),@@ -713,6 +724,37 @@ describe("buildAgentServerCommand", () => {});});+describe("buildUvxPythonArgs", () => {+ const defaults = JSON.parse(+ readFileSync(+ path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ "../../config/defaults.json",+ ),+ "utf-8",+ ),+ ) as { python: { uvxRequest: string } };++ it("requests the Python range from config/defaults.json by default", () => {+ // Without it uvx downloads the newest CPython on a machine that has none,+ // which fails until the SDK's compiled dependencies ship wheels for it+ // (#18654).+ expect(defaults.python.uvxRequest).toBe(">=3.12,<3.15");+ expect(buildUvxPythonArgs({})).toEqual([+ "--python",+ defaults.python.uvxRequest,+ ]);+ });++ it("leaves the interpreter choice to uv when UV_PYTHON is set", () => {+ // An explicit --python would outrank uv's own variable.+ expect(buildUvxPythonArgs({ UV_PYTHON: "3.13" })).toEqual([]);+ const { args } = buildAgentServerCommand({ UV_PYTHON: "3.13" });+ expect(args).not.toContain("--python");+ expect(args[0]).toBe("--from");+ });+});+describe("validateLocalAgentServerPath", () => {it("passes when all four workspace packages exist", () => {const tmp = mkdtempSync(path.join(tmpdir(), "sdk-"));diff --git a/__tests__/scripts/dev-with-automation.test.ts b/__tests__/scripts/dev-with-automation.test.tsindex 2262db0300..7d96573ab9 100644--- a/__tests__/scripts/dev-with-automation.test.ts+++ b/__tests__/scripts/dev-with-automation.test.ts@@ -109,6 +109,25 @@ describe("buildAutomationCommand", () => {expect(cmd.source).toBe(`PyPI (${DEFAULT_AUTOMATION_VERSION}, default)`);});+ it("requests the shared Python range for uvx in every source mode", () => {+ // See buildUvxPythonArgs in dev-safe.mjs and #18654.+ const variants = [+ {},+ { OH_AUTOMATION_VERSION: "1.0.0" },+ { OH_AUTOMATION_GIT_REF: "main" },+ ];+ for (const env of variants) {+ const { command, args } = buildAutomationCommand(env);+ expect(command).toBe("uvx");+ expect(args.slice(0, 2)).toEqual(["--python", ">=3.12,<3.15"]);+ }+ });++ it("leaves the interpreter choice to uv when UV_PYTHON is set", () => {+ const { args } = buildAutomationCommand({ UV_PYTHON: "3.13" });+ expect(args).not.toContain("--python");+ });+it("uses custom git ref from OH_AUTOMATION_GIT_REF", () => {const cmd = buildAutomationCommand({OH_AUTOMATION_GIT_REF: "feat/my-feature",diff --git a/bin/agent-canvas.mjs b/bin/agent-canvas.mjsindex f399534872..2f96f7fc0a 100755--- a/bin/agent-canvas.mjs+++ b/bin/agent-canvas.mjs@@ -94,6 +94,7 @@ ENVIRONMENT VARIABLES:OH_AGENT_SERVER_GIT_REF Git ref for agent-serverOH_AGENT_SERVER_LOCAL_PATH Path to local SDK checkout (for development)OH_AGENT_SERVER_VERSION Specific PyPI version for agent-server+ UV_PYTHON Python version/range for uvx-run servicesNote: LLM settings are configured through the web UI settings page,not environment variables.diff --git a/config/defaults.json b/config/defaults.jsonindex 86bab4889d..f58ce19a4e 100644--- a/config/defaults.json+++ b/config/defaults.json@@ -8,6 +8,10 @@"compatibility": {"minimumAgentServer": "1.55.0"},+ "python": {+ "_comment": "Interpreter request the npm and desktop launchers pass to uvx as --python for agent-server and automation. Without it uvx downloads the newest CPython when it finds no suitable interpreter, which breaks every autumn until the SDK's compiled dependencies (lmnr-claude-code-proxy, fastuuid) publish wheels for the new release (OpenHands/OpenHands#18654). Raise the upper bound once they do. UV_PYTHON in the environment replaces it.",+ "uvxRequest": ">=3.12,<3.15"+ },"images": {"agentServer": "ghcr.io/openhands/agent-server","agentCanvas": "ghcr.io/openhands/agent-canvas"diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.mdindex 1d8b8065a4..f8e31146ec 100644--- a/docs/DEVELOPMENT.md+++ b/docs/DEVELOPMENT.md@@ -77,6 +77,7 @@ directory before starting the Agent Server and preserve an explicit override.| `OH_AUTOMATION_LOCAL_PATH` | Absolute `automation` checkout | unset || `OH_AUTOMATION_GIT_REF` | Git ref for automation backend | unset (`config/defaults.json`) || `OH_AUTOMATION_VERSION` | PyPI version for automation | unset (`config/defaults.json`) |+| `UV_PYTHON` | Python version/range for uvx services | unset (`config/defaults.json`) |### Alternative: Minimal Mode (without Automation)diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjsindex da14006a4a..3438155981 100644--- a/scripts/dev-safe.mjs+++ b/scripts/dev-safe.mjs@@ -60,6 +60,9 @@ const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_API_KEY =const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_HOST =SHARED_DEFAULTS.telemetry.posthogHost;const AGENT_SERVER_POSTHOG_CONSTRAINT = "posthog>=6,<7";+// Interpreter request passed to uvx for agent-server and automation; see+// buildUvxPythonArgs.+const DEFAULT_UVX_PYTHON_REQUEST = SHARED_DEFAULTS.python.uvxRequest;const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];/**@@ -408,6 +411,27 @@ export function validateFrontendDependencies(*/export const AGENT_SERVER_IMPORT_MODULES = "canvas_ui_tool";+/**+ * Build the `--python` arguments for a uvx-launched service.+ *+ * When no suitable interpreter is installed, uvx downloads the newest+ * CPython it knows, and the SDK's compiled dependencies lag each new+ * Python release by weeks. A fresh machine therefore failed to start as+ * soon as Python 3.15 shipped (#18654). Requesting a range makes uvx reuse+ * any installed interpreter inside it and otherwise download the newest+ * matching one. An explicit `--python` would outrank uv's own UV_PYTHON+ * variable, so it is omitted when UV_PYTHON is set.+ *+ * @param {Record<string, string | undefined>} env+ * @returns {string[]}+ */+export function buildUvxPythonArgs(env = process.env) {+ if (env.UV_PYTHON) {+ return [];+ }+ return ["--python", DEFAULT_UVX_PYTHON_REQUEST];+}+/*** Build the uvx command and arguments for running agent-server.*@@ -424,6 +448,9 @@ export const AGENT_SERVER_IMPORT_MODULES = "canvas_ui_tool";* DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a* git branch or commit instead.*+ * UV_PYTHON, when set, replaces the default interpreter request (the+ * python.uvxRequest range in config/defaults.json) given to uvx.+ ** @param {Record<string, string | undefined>} env* @returns {{ command: string, args: string[], source: string }}*/@@ -432,7 +459,7 @@ export function buildAgentServerCommand(env = process.env) {const gitRef = env.OH_AGENT_SERVER_GIT_REF;const version = env.OH_AGENT_SERVER_VERSION;- const uvxArgs = [];+ const uvxArgs = buildUvxPythonArgs(env);let source = "";if (localPath) {diff --git a/scripts/dev-with-automation.mjs b/scripts/dev-with-automation.mjsindex 30d804aa8c..d0ff0fab7e 100644--- a/scripts/dev-with-automation.mjs+++ b/scripts/dev-with-automation.mjs@@ -59,6 +59,7 @@ import {buildAgentServerEnv,buildNpmScriptCommand,buildRuntimeServicesInfo,+ buildUvxPythonArgs,formatMissingUvxGuidance,validateFrontendDependencies,validateLocalAgentServerPath,@@ -320,6 +321,9 @@ function validateLocalAutomationPath(localPath) {* If none are set, defaults to the released version specified by* DEFAULT_AUTOMATION_VERSION. Set OH_AUTOMATION_GIT_REF to use a* git branch or commit instead.+ *+ * UV_PYTHON, when set, replaces the default interpreter request (the+ * python.uvxRequest range in config/defaults.json) given to uvx.*/function buildAutomationCommand(env = process.env) {const localPath = env.OH_AUTOMATION_LOCAL_PATH;@@ -327,7 +331,7 @@ function buildAutomationCommand(env = process.env) {const version = env.OH_AUTOMATION_VERSION;const repoUrl = env.OH_AUTOMATION_REPO || DEFAULT_AUTOMATION_REPO;- const uvxArgs = [];+ const uvxArgs = buildUvxPythonArgs(env);let source = "";if (localPath) {