π OpenHands: AI-Driven Development
feat(launchers): read public skills from the bundled extensions package (#18683)
simonrosenberg56d05f37a06f
diff --git a/.agents/skills/desktop-electron/references/guide.md b/.agents/skills/desktop-electron/references/guide.mdindex 43cdc841fb..17a95e4941 100644--- a/.agents/skills/desktop-electron/references/guide.md+++ b/.agents/skills/desktop-electron/references/guide.md@@ -4,7 +4,7 @@2. **First-run feedback loop**: `dev-with-automation.mjs::setServiceLogListener(cb)` exposes a workspace-wide hook that fires `cb(name, line, level)` for every line of every child-process stdout/stderr/exit. `electron/main.mjs::handleServiceLog` filters for uvx install lines (`Downloading...`, `Resolved N packages...`, etc.) plus agent-server boot markers and forwards them to `loading.html` via `setLoadingStatus()` β `window.__setLoadingStatus()`. The hook is best-effort and swallows listener errors β a buggy embedder must not be able to take down the dev stack.-- Electron desktop packaging β `electron-builder.config.mjs` uses `directories.app: "electron"` so electron/package.json is the app manifest. Even though electron/package.json has zero `dependencies`, app-builder-lib's `collectNodeModulesWithLogging` walks UP from the app dir looking for the first npm workspace that resolves modules. The next dir in line is the project root, where `npm list --json` reports the full hoisted tree (~342 dirs, ~600 MB of Vite/React/Monaco/HeroUI), and electron-builder copies all of it into `Resources/app/node_modules/`. The walk is hardcoded in `app-builder-lib/out/util/appFileCopier.js::collectNodeModulesWithLogging` β there is no config knob to disable it. Creating an empty `electron/node_modules/` does NOT help because the collector falls through to project root when it sees zero deps. **The fix is the `afterPack` hook** (`stripBundledNodeModules` in `electron-builder.config.mjs`): after electron-builder copies everything, the hook `rm -rf`s `Resources/app/node_modules/` (handling macOS `.app` bundle layout and Linux/Windows flat resources/ layout), then copies back the dependency closure of `RUNTIME_PACKAGES` (`sirv` for static-server.mjs, `httpxy` for proxy-utils.mjs/ingress.mjs β ~200 KB total). Effect: `resources/app/` drops from ~598 MB to ~7 MB; total `linux-unpacked/` from ~1 GB to ~365 MB (the rest is Electron + Chromium + the bundled `uv` binary). If a spawned backend script gains a new bare npm import, add the package to `RUNTIME_PACKAGES` β otherwise that service crashes with `ERR_MODULE_NOT_FOUND` only in the installed app. **Testing trap:** an app launched from `dist-electron/` inside the repo resolves bare specifiers against the repo's own `node_modules` (Node ESM resolution walks up from the script file), so a missing runtime package is invisible there β verify packaged builds from a copy outside the repo tree (e.g. `/Applications`). Don't add real deps to electron/package.json β any real dep would survive the strip and would also have to be hand-installed inside electron/ since the project root is npm-hoisted. `build:desktop:universal` and `--linux/--win/--mac` variants all run the same hook.+- Electron desktop packaging β `electron-builder.config.mjs` uses `directories.app: "electron"` so electron/package.json is the app manifest. Even though electron/package.json has zero `dependencies`, app-builder-lib's `collectNodeModulesWithLogging` walks UP from the app dir looking for the first npm workspace that resolves modules. The next dir in line is the project root, where `npm list --json` reports the full hoisted tree (~342 dirs, ~600 MB of Vite/React/Monaco/HeroUI), and electron-builder copies all of it into `Resources/app/node_modules/`. The walk is hardcoded in `app-builder-lib/out/util/appFileCopier.js::collectNodeModulesWithLogging` β there is no config knob to disable it. Creating an empty `electron/node_modules/` does NOT help because the collector falls through to project root when it sees zero deps. **The fix is the `afterPack` hook** (`stripBundledNodeModules` in `electron-builder.config.mjs`): after electron-builder copies everything, the hook `rm -rf`s `Resources/app/node_modules/` (handling macOS `.app` bundle layout and Linux/Windows flat resources/ layout), then copies back the dependency closure of `RUNTIME_PACKAGES`: `sirv` for static-server.mjs, `httpxy` for proxy-utils.mjs/ingress.mjs, `ws` for tunnel-client.mjs (~250 KB together), and `@openhands/extensions` (~6 MB), which no script imports: the launcher points the agent-server's `EXTENSIONS_PATH` at it so public skills load from disk. Effect: `resources/app/` drops from ~598 MB to ~7 MB before the extensions package; total `linux-unpacked/` from ~1 GB to ~365 MB (the rest is Electron + Chromium + the bundled `uv` binary). If a spawned backend script gains a new bare npm import, add the package to `RUNTIME_PACKAGES` β otherwise that service crashes with `ERR_MODULE_NOT_FOUND` only in the installed app. A package a backend only reads from disk fails quietly instead: without `@openhands/extensions` the launcher sets no `EXTENSIONS_PATH` and the agent-server falls back to cloning the extensions repo. **Testing trap:** an app launched from `dist-electron/` inside the repo resolves bare specifiers against the repo's own `node_modules` (Node ESM resolution walks up from the script file), so a missing runtime package is invisible there β verify packaged builds from a copy outside the repo tree (e.g. `/Applications`). Don't add real deps to electron/package.json β any real dep would survive the strip and would also have to be hand-installed inside electron/ since the project root is npm-hoisted. `build:desktop:universal` and `--linux/--win/--mac` variants all run the same hook.- Electron desktop universal (multi-arch) builds β `ELECTRON_ARCH=universal npm run build:desktop:universal` produces one fat arm64+x64 DMG. The bundled uv/node runtimes are per-arch: the download scripts (arch resolution in `scripts/download-arch-utils.mjs::resolveDownloadArches()`; any `ELECTRON_ARCH` value other than unset or `universal` fails fast) populate `resources/{bin,node}-{arm64,x64}/` in universal mode (legacy flat `resources/{bin,node}/` otherwise), `mac.extraResources` ships all four dirs into BOTH packaging passes, and `mac.x64ArchFiles` whitelists them through the `@electron/universal` merge β the merger requires both pass trees to carry the same Mach-O file list and rejects byte-identical thin Mach-O files unless whitelisted, so bundling only the pass's own arch (e.g. via the `${arch}` macro) fails the merge. `electron/lib/bundled-runtime-dir.mjs::resolveBundledRuntimeDir()` (used by `injectBundledUv`/`injectBundledNode`) prefers `<Resources>/{bin,node}-<process.arch>` β under a universal Electron binary `process.arch` reports the executing slice (arm64 native, x64 under Rosetta) β and falls back to the flat dirs. Release CI (`desktop-macos.yml`) builds universal; PR/manual smoke builds run a two-leg matrix β native arm64 on `macos-latest` and native Intel x64 on `macos-15-intel` (GitHub's last Intel macOS runner, available until Aug 2027) β so the per-arch download + packaging path is exercised on the runner's own CPU. On `macos-15-intel` (which reports `process.arch === "x64"`), `npm run build:desktop` resolves the Intel runtimes into the legacy flat dirs, so that leg also guards the single-arch x64 fallback path.diff --git a/.agents/skills/local-stack-runtime/references/guide.md b/.agents/skills/local-stack-runtime/references/guide.mdindex badf0ed477..c1e813fffc 100644--- a/.agents/skills/local-stack-runtime/references/guide.md+++ b/.agents/skills/local-stack-runtime/references/guide.md@@ -100,6 +100,7 @@ you are running inside of β NOT the automation backend.- Security: launchers generate and persist a 64-character session API key at `~/.openhands/agent-canvas/session-api-key.txt` unless overridden. The agent-server and automation backend share that session key. `OH_SECRET_KEY` protects settings encryption and is persisted separately at `~/.openhands/agent-canvas/secret-key.txt`.- `scripts/dev-safe.mjs` should fail fast if `uvx` cannot be spawned (for example missing PATH entries).- `tools/` holds Python modules the agent-server can import: `buildAgentServerEnv` exposes the directory through `OH_EXTRA_PYTHON_PATH` (Docker: `/opt/agent-canvas/tools`, see `docker/entrypoint.sh`). `tools/canvas_ui_tool.py` is imported at startup via `--import-modules canvas_ui_tool` (appended by `buildAgentServerCommand` and by both launch lines in `docker/entrypoint.sh`), not only lazily from persisted conversation metadata: besides the legacy `canvas_ui` registration it registers the SDK's builtin `FinishTool`, so `openhands-automation` β₯ 1.9.0 presets β which dispatch remote conversations with `finish_tool_response_schema=TaskOutcome` and advertise the tool as the non-self-registering `openhands.sdk.tool.builtins.finish` β do not fail every run with `ToolDefinition 'FinishTool' is not registered`. Remove that registration once the SDK registers builtins for remote conversations.+- Every launcher points the agent-server at the installed `@openhands/extensions` package through `EXTENSIONS_PATH`, so the public skills Agent Profiles select (`public_skills`) are the files Canvas bundles and nothing is cloned. `buildAgentServerEnv` sets it from `resolveExtensionsDir()` unless the environment already sets one; Docker copies the package to `/opt/agent-canvas/node_modules/@openhands/extensions` and exports it in `docker/entrypoint.sh`; the desktop app ships it through `RUNTIME_PACKAGES` in `electron-builder.config.mjs`.- `npm run dev` runs the full local stack via `uvx` (agent-server + automation backend + Vite dev server + ingress proxy) with no Docker dependency. `npm run dev:static` does the same but serves a production build of the frontend instead of the Vite dev server.- `scripts/dev-with-automation.mjs` runs the full stack: agent-server, automation backend (both via uvx), frontend server, and ingress proxy. It defaults to Vite when run directly, supports `--static` for an existing build, and supports `--dynamic` so wrappers that default static can opt back into Vite. Uses a standalone ingress proxy (`scripts/ingress.mjs`) to route traffic:- Keep `SIGINT`, `SIGTERM`, and `SIGHUP` wired through the coordinated shutdown handler. Services run in detached process groups on POSIX, so cleanup must use `signalProcessTree()` rather than signaling only the direct child; regression coverage lives in `__tests__/scripts/dev-with-automation.test.ts`.diff --git a/.pr/launchers-running-canvas.png b/.pr/launchers-running-canvas.pngnew file mode 100644index 0000000000..10a4e5c5dbBinary files /dev/null and b/.pr/launchers-running-canvas.png differdiff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.tsindex c5fccd8049..b351fce91e 100644--- a/__tests__/scripts/dev-safe.test.ts+++ b/__tests__/scripts/dev-safe.test.ts@@ -33,9 +33,11 @@ import {findFreePorts,getOrCreatePersistedSessionApiKey,resetPersistedSessionApiKeyCache,+ resolveExtensionsDir,} from "../../scripts/dev-safe.mjs";import {chmodSync,+ existsSync,mkdtempSync,mkdirSync,readFileSync,@@ -402,6 +404,7 @@ describe("buildAgentServerTelemetryEnv", () => {backendHost: "127.0.0.1:18000",workingDir: "/tmp/workspaces",canvasToolsDir: "/tmp/tools",+ extensionsDir: "/tmp/node_modules/@openhands/extensions",};it("configures PostHog telemetry by default without seeding consent", () => {@@ -497,6 +500,30 @@ describe("buildAgentServerTelemetryEnv", () => {).not.toHaveProperty("OH_ENABLE_BROWSER");});+ it("points the agent-server at the installed extensions package", () => {+ expect(+ buildAgentServerEnv(agentServerConfig, { env: {} }).EXTENSIONS_PATH,+ ).toBe("/tmp/node_modules/@openhands/extensions");+ expect(+ buildAgentServerEnv(agentServerConfig, {+ env: { EXTENSIONS_PATH: "/custom/extensions" },+ }).EXTENSIONS_PATH,+ ).toBe("/custom/extensions");+ expect(+ buildAgentServerEnv(+ { ...agentServerConfig, extensionsDir: null },+ { env: {} },+ ),+ ).not.toHaveProperty("EXTENSIONS_PATH");+ });++ it("resolves the extensions package that ships the public skills", () => {+ const dir = resolveExtensionsDir();++ expect(dir).not.toBeNull();+ expect(existsSync(path.join(dir as string, "skills"))).toBe(true);+ });+it("keeps an explicit OH_ENABLE_BROWSER when browser tools are disabled", () => {expect(buildAgentServerEnv(agentServerConfig, {diff --git a/__tests__/scripts/docker-script-imports.test.ts b/__tests__/scripts/docker-script-imports.test.tsindex 5b780e33f3..e64811b2a4 100644--- a/__tests__/scripts/docker-script-imports.test.ts+++ b/__tests__/scripts/docker-script-imports.test.ts@@ -17,6 +17,23 @@ const entrypoint = readFileSync("utf-8",);+// The agent-server reads this package from disk, so no import points at it and+// a missing copy only shows up as an agent with no public skills.+describe("Docker image extensions package", () => {+ it("copies the package to the path the entrypoint exports as EXTENSIONS_PATH", () => {+ const exported = entrypoint.match(+ /^export EXTENSIONS_PATH="\$\{EXTENSIONS_PATH:-([^}]+)\}"$/m,+ )?.[1];++ expect(exported).toBe(+ "/opt/agent-canvas/node_modules/@openhands/extensions",+ );+ expect(dockerfile).toContain(+ `COPY --from=frontend-build /build/node_modules/@openhands/extensions ${exported}`,+ );+ });+});+// The image copies scripts/ one file at a time, so a new import in a script// the entrypoint runs must come with a COPY line, or the container crashes on// start with ERR_MODULE_NOT_FOUND (#18342).diff --git a/__tests__/scripts/electron-builder-config.test.ts b/__tests__/scripts/electron-builder-config.test.tsindex 27999e592f..9112dc370a 100644--- a/__tests__/scripts/electron-builder-config.test.ts+++ b/__tests__/scripts/electron-builder-config.test.ts@@ -7,7 +7,14 @@// These tests therefore build a fake bundle under os.tmpdir() and verify// resolution with a real `node --eval` from that location.import { spawnSync } from "node:child_process";-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from "node:fs";import { tmpdir } from "node:os";import { dirname, join } from "node:path";import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";@@ -45,7 +52,11 @@ function appDirFor(platform: string, appOutDir: string) {function resolveRuntimeImports(appDir: string) {return spawnSync(process.execPath,- ["--input-type=module", "-e", 'await import("sirv"); await import("httpxy");'],+ [+ "--input-type=module",+ "-e",+ 'await import("sirv"); await import("httpxy");',+ ],{ cwd: appDir, stdio: "pipe" },);}@@ -55,7 +66,15 @@ function resolveRuntimeImports(appDir: string) {* its npm-cli.js marker, as download-node.mjs produces on macOS/Linux.*/function writeFakeNpmCli(resourcesDir: string, nodeDirName: string) {- const npmCli = join(resourcesDir, nodeDirName, "lib", "node_modules", "npm", "bin", "npm-cli.js");+ const npmCli = join(+ resourcesDir,+ nodeDirName,+ "lib",+ "node_modules",+ "npm",+ "bin",+ "npm-cli.js",+ );mkdirSync(dirname(npmCli), { recursive: true });writeFileSync(npmCli, "// fake npm-cli.js\n");}@@ -107,8 +126,18 @@ describe("electron-builder afterPack hook", () => {await afterPack(makeContext("linux", tmp));expect(existsSync(junkPkg)).toBe(false);- expect(existsSync(join(appDir, "node_modules", "sirv", "package.json"))).toBe(true);- expect(existsSync(join(appDir, "node_modules", "httpxy", "package.json"))).toBe(true);+ expect(+ existsSync(join(appDir, "node_modules", "sirv", "package.json")),+ ).toBe(true);+ expect(+ existsSync(join(appDir, "node_modules", "httpxy", "package.json")),+ ).toBe(true);+ // The agent-server reads the public skills from it (EXTENSIONS_PATH).+ expect(+ existsSync(+ join(appDir, "node_modules", "@openhands", "extensions", "skills"),+ ),+ ).toBe(true);});it("verifies npm in every per-arch node dir of a universal bundle", async () => {@@ -118,7 +147,9 @@ describe("electron-builder afterPack hook", () => {writeFakeNpmCli(resourcesDir, "node-arm64");writeFakeNpmCli(resourcesDir, "node-x64");- await expect(afterPack(makeContext("darwin", tmp))).resolves.toBeUndefined();+ await expect(+ afterPack(makeContext("darwin", tmp)),+ ).resolves.toBeUndefined();});it("fails the build when one per-arch node dir of a universal bundle is missing npm", async () => {@@ -141,7 +172,9 @@ describe("electron-builder afterPack hook", () => {mkdirSync(join(resourcesDir, "app"), { recursive: true });writeFakeNpmCli(resourcesDir, "node");- await expect(afterPack(makeContext("darwin", tmp))).resolves.toBeUndefined();+ await expect(+ afterPack(makeContext("darwin", tmp)),+ ).resolves.toBeUndefined();});});@@ -210,7 +243,10 @@ describe("extraResources mode switch", () => {describe("desktop app name", () => {it("keeps electron/package.json productName in sync with the builder config", () => {const appManifest = JSON.parse(- readFileSync(join(import.meta.dirname, "../../electron/package.json"), "utf8"),+ readFileSync(+ join(import.meta.dirname, "../../electron/package.json"),+ "utf8",+ ),);expect(appManifest.productName).toBe(config.productName);diff --git a/docker/Dockerfile b/docker/Dockerfileindex f4e4e86a7e..0cbbf72502 100644--- a/docker/Dockerfile+++ b/docker/Dockerfile@@ -158,6 +158,9 @@ COPY --from=frontend-build /build/node_modules/sirv /opt/agent-canvas/node_modulCOPY --from=frontend-build /build/node_modules/@polka /opt/agent-canvas/node_modules/@polkaCOPY --from=frontend-build /build/node_modules/mrmime /opt/agent-canvas/node_modules/mrmimeCOPY --from=frontend-build /build/node_modules/totalist /opt/agent-canvas/node_modules/totalist+# The agent-server reads public skills from the package the frontend bundles+# (EXTENSIONS_PATH in entrypoint.sh) instead of cloning the extensions repo.+COPY --from=frontend-build /build/node_modules/@openhands/extensions /opt/agent-canvas/node_modules/@openhands/extensions# Copy the runtime-services-info builder (entrypoint.sh runs it as a CLI to# emit the agent's <RUNTIME_SERVICES> block; same builder the dev stack uses).diff --git a/docker/entrypoint.sh b/docker/entrypoint.shindex 82f349b437..f2eb72c8df 100644--- a/docker/entrypoint.sh+++ b/docker/entrypoint.sh@@ -283,6 +283,10 @@ export AUTOMATION_AGENT_SERVER_URL="${AUTOMATION_AGENT_SERVER_URL:-http://127.0.# FinishTool registration lets automation runs resolve the tool on their# remote conversations (see the note at the bottom of tools/canvas_ui_tool.py).export OH_EXTRA_PYTHON_PATH="${OH_EXTRA_PYTHON_PATH:-/opt/agent-canvas/tools}"++# Read public skills from the extensions package the frontend was built with,+# so Canvas and the agent-server see the same catalog and nothing is cloned.+export EXTENSIONS_PATH="${EXTENSIONS_PATH:-/opt/agent-canvas/node_modules/@openhands/extensions}"AGENT_SERVER_IMPORT_MODULES="canvas_ui_tool"# Track child PIDs so we can clean up on exit.diff --git a/electron-builder.config.mjs b/electron-builder.config.mjsindex 7b06e259ce..e823d79cab 100644--- a/electron-builder.config.mjs+++ b/electron-builder.config.mjs@@ -30,8 +30,9 @@* The fix is the `afterPack` hook below: after electron-builder has* finished copying files, we rm -rf the bundled Resources/app/node_modules/* directory, then copy back the dependency closure of RUNTIME_PACKAGES- * (~200 KB). The build wastes a few seconds copying files we immediately- * delete, but the final artifact is correctly tiny (~10 MB vs ~600 MB).+ * (~6 MB, nearly all @openhands/extensions). The build wastes a few seconds+ * copying files we immediately delete, but the final artifact stays small+ * (~16 MB vs ~600 MB).** Packaged app layout (Resources/app/ = electron/ contents):* main.mjs β Electron entry point@@ -79,13 +80,15 @@ const isUniversal = ELECTRON_ARCH === "universal";// scripts/tunnel-client.mjs β ws (imported directly by main.mjs,// not spawned β the MARS// port-forward tunnel client)+// scripts/dev-safe.mjs β @openhands/extensions (read from disk by+// the agent-server as EXTENSIONS_PATH)// Their dependency closure is copied back into Resources/app/node_modules// after the strip below. If a spawned script (or main.mjs itself) gains a// new bare import, add the package here β a missing one crashes that// service in the installed app with ERR_MODULE_NOT_FOUND (invisible under// Finder, where stdout goes to /dev/null) and the splash times out waiting// for port 8000.-const RUNTIME_PACKAGES = ["sirv", "httpxy", "ws"];+const RUNTIME_PACKAGES = ["sirv", "httpxy", "ws", "@openhands/extensions"];const repoRoot = dirname(fileURLToPath(import.meta.url));@@ -432,9 +435,7 @@ const config = {target: [{target: "dmg",- arch: [- ELECTRON_ARCH ?? (process.arch === "arm64" ? "arm64" : "x64"),- ],+ arch: [ELECTRON_ARCH ?? (process.arch === "arm64" ? "arm64" : "x64")],},],// Universal merge whitelist: the per-arch uv/node runtime binaries arediff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjsindex f6c19b3958..da14006a4a 100644--- a/scripts/dev-safe.mjs+++ b/scripts/dev-safe.mjs@@ -10,6 +10,7 @@ import {writeFileSync,} from "node:fs";import net from "node:net";+import { createRequire } from "node:module";import { homedir } from "node:os";import path from "node:path";import process from "node:process";@@ -629,8 +630,26 @@ export async function buildSafeDevConfigAsync(* @property {string} secretKey* @property {string} sessionApiKey* @property {string} canvasToolsDir+ * @property {string | null} extensionsDir*/+/**+ * The installed `@openhands/extensions` package, so the agent-server reads the+ * same public skills Canvas bundles instead of cloning the repository.+ * @returns {string | null}+ */+export function resolveExtensionsDir() {+ try {+ return path.dirname(+ createRequire(import.meta.url).resolve(+ "@openhands/extensions/package.json",+ ),+ );+ } catch {+ return null;+ }+}+/*** Internal helper to build config from already-resolved ports.* @param {{backendPort: number, vscodePort: number}} ports@@ -704,6 +723,7 @@ function buildConfigFromPorts(ports, cwd, env) {secretKey,sessionApiKey,canvasToolsDir,+ extensionsDir: resolveExtensionsDir(),};}@@ -849,6 +869,9 @@ export function buildAgentServerEnv(config, options = {}) {// Let the agent-server resolve canvas_ui_tool when old persisted metadata// requests that compatibility module during startup.OH_EXTRA_PYTHON_PATH: config.canvasToolsDir,+ ...(env.EXTENSIONS_PATH || config.extensionsDir+ ? { EXTENSIONS_PATH: env.EXTENSIONS_PATH || config.extensionsDir }+ : {}),};}