Skip to content

πŸ™Œ 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.md
index 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.md
index 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.png
new file mode 100644
index 0000000000..10a4e5c5db
Binary files /dev/null and b/.pr/launchers-running-canvas.png differ
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index 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.ts
index 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.ts
index 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/Dockerfile
index 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_modul
COPY --from=frontend-build /build/node_modules/@polka /opt/agent-canvas/node_modules/@polka
COPY --from=frontend-build /build/node_modules/mrmime /opt/agent-canvas/node_modules/mrmime
COPY --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.sh
index 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.mjs
index 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 are
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index 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 }
+ : {}),
};
}