Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: default EXTENSIONS_REF from pinned @openhands/extensions SHA in package.json (#1060)

Tim O'Farrelldda46c10bddb
diff --git a/AGENTS.md b/AGENTS.md
index e0de59880a..9eef3803ef 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,7 @@
- `VITE_ENABLE_BROWSER_TOOLS=false` to omit `BrowserToolSet` from new conversation payloads.
- `VITE_LOAD_PUBLIC_SKILLS=false` to disable loading public skills from the OpenHands extensions marketplace (https://github.com/OpenHands/extensions). Defaults to true (opt-out).
- Default working-dir fallback is now the relative path `workspace/project` (exported as `DEFAULT_WORKING_DIR` from `src/api/agent-server-config.ts`); git-path heuristics and the default PLAN preview path should reuse that constant instead of hardcoding `/workspace/project`.
+- `EXTENSIONS_REF` is derived from the `@openhands/extensions` git URL in `package.json` via `getExtensionsRef()` in `scripts/dev-safe.mjs`, and exported as `DEFAULT_EXTENSIONS_REF`. `buildAgentServerEnv()` injects it as `EXTENSIONS_REF` when not already set in the environment. The Docker path bakes the SHA into `defaults.env` as `CONFIG_EXTENSIONS_REF` (via the `config-gen` stage) and `docker/entrypoint.sh` applies it as `EXTENSIONS_REF="${EXTENSIONS_REF:-${CONFIG_EXTENSIONS_REF:-}}"`. The agent-server SDK skips network polling when it already has the requested SHA in its local cache.
- The UI keeps most OpenHands routes/layout intact, but hosted-only behavior (org, account management, integrations) has been removed via the fabricated OSS config because there is no separate app backend.
- Verification command: `npm run typecheck && npm run build`.
- GitHub automation now includes `.github/workflows/ci.yml` for `npm ci`, `npm test`, and `npm run build`, plus `.github/dependabot.yml` with weekly npm/github-actions updates gated by a 7-day cooldown.
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index c859100f65..9ff3f42e9a 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -428,9 +428,12 @@ describe("buildAgentServerCommand", () => {
expect(cmd.command).toBe("uvx");
expect(cmd.args).toEqual([
+ "--reinstall",
"--from",
"git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-agent-server",
"--with",
+ "git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-sdk",
+ "--with",
"git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-tools",
"--with",
"git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-workspace",
@@ -444,9 +447,12 @@ describe("buildAgentServerCommand", () => {
expect(cmd.command).toBe("uvx");
expect(cmd.args).toEqual([
+ "--reinstall",
"--from",
"git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-agent-server",
"--with",
+ "git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-sdk",
+ "--with",
"git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-tools",
"--with",
"git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-workspace",
diff --git a/docker/Dockerfile b/docker/Dockerfile
index 404e06d18c..3755b3a93a 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -45,10 +45,16 @@ RUN npm run build
# ── Stage 1b: Generate shell-sourceable defaults from config/defaults.json ──
# This avoids needing jq/python at container runtime to parse the JSON.
+# package.json is also read to extract the pinned @openhands/extensions SHA
+# and emit it as CONFIG_EXTENSIONS_REF so the agent-server uses the same
+# extensions commit as the bundled UI (via EXTENSIONS_REF in entrypoint.sh).
FROM node:24-slim AS config-gen
-COPY config/defaults.json /tmp/defaults.json
+COPY config/defaults.json package.json /tmp/
RUN node -e " \
const c = JSON.parse(require('fs').readFileSync('/tmp/defaults.json','utf-8')); \
+ const pkg = JSON.parse(require('fs').readFileSync('/tmp/package.json','utf-8')); \
+ const extUrl = (pkg.dependencies || pkg.devDependencies || {})['@openhands/extensions'] || ''; \
+ const extSha = (extUrl.match(/#([0-9a-f]{40})\$/i) || [])[1] || ''; \
const lines = [ \
'CONFIG_AGENT_SERVER_PORT=' + c.ports.agentServer, \
'CONFIG_AUTOMATION_PORT=' + c.ports.automation, \
@@ -58,6 +64,7 @@ RUN node -e " \
'CONFIG_BASH_EVENTS=' + c.paths.bashEvents, \
'CONFIG_AUTOMATION_DB=' + c.paths.automationDb, \
]; \
+ if (extSha) lines.push('CONFIG_EXTENSIONS_REF=' + extSha); \
require('fs').writeFileSync('/tmp/defaults.env', lines.join('\n') + '\n'); \
"
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index a48f0e2ace..c05935106e 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -128,6 +128,11 @@ export AUTOMATION_AGENT_SERVER_URL="${AUTOMATION_AGENT_SERVER_URL:-http://127.0.
# OH_EXTRA_PYTHON_PATH: config.canvasToolsDir.
export OH_EXTRA_PYTHON_PATH="${OH_EXTRA_PYTHON_PATH:-/opt/agent-canvas/tools}"
+# Pin the public-skills catalog to the same @openhands/extensions commit that
+# the frontend bundle was built with. The agent-server SDK skips network polling
+# when EXTENSIONS_REF is already present in its local cache.
+export EXTENSIONS_REF="${EXTENSIONS_REF:-${CONFIG_EXTENSIONS_REF:-}}"
+
# Track child PIDs so we can clean up on exit.
PIDS=()
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index 70df6c3e3e..e93aaa5e34 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -35,6 +35,32 @@ const SHARED_DEFAULTS = JSON.parse(
),
);
+/**
+ * Extract the pinned commit SHA for @openhands/extensions from package.json.
+ * Returns the 40-char hex SHA when the dependency is a git+https URL with a
+ * commit hash fragment (e.g. "git+https://…#62594156…"), null otherwise.
+ * @returns {string | null}
+ */
+function getExtensionsRef() {
+ try {
+ const pkg = JSON.parse(
+ readFileSync(
+ path.join(__dev_safe_dirname, "..", "package.json"),
+ "utf-8",
+ ),
+ );
+ const url =
+ (pkg.dependencies ?? pkg.devDependencies ?? {})["@openhands/extensions"] ??
+ "";
+ return url.match(/#([0-9a-f]{40})$/i)?.[1] ?? null;
+ } catch {
+ return null;
+ }
+}
+
+/** Pinned extensions commit SHA derived from package.json, or null if not pinned. */
+export const DEFAULT_EXTENSIONS_REF = getExtensionsRef();
+
const DEFAULT_BACKEND_PORT = SHARED_DEFAULTS.ports.agentServer;
const DEFAULT_VITE_PORT = 3001;
const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
@@ -430,14 +456,23 @@ export function buildAgentServerCommand(env = process.env) {
);
source = `local (${localPath})`;
} else if (gitRef) {
- // Use git ref with subdirectory syntax for uv workspace monorepo
+ // Use git ref with subdirectory syntax for uv workspace monorepo.
// The software-agent-sdk repo has packages in subdirectories:
- // openhands-agent-server/, openhands-tools/, openhands-workspace/
+ // openhands-agent-server/, openhands-sdk/, openhands-tools/, openhands-workspace/
+ // All four must come from the same ref so inter-package APIs stay in sync.
+ //
+ // --reinstall is required because the git branch may carry the same version
+ // string as the current PyPI release (e.g. both "1.25.0"). Without it, uv
+ // silently reuses the cached PyPI wheels and the git ref is never actually
+ // used, even though it was explicitly requested.
const baseGitUrl = `git+${AGENT_SERVER_GIT_REPO}@${gitRef}`;
uvxArgs.push(
+ "--reinstall",
"--from",
`${baseGitUrl}#subdirectory=openhands-agent-server`,
"--with",
+ `${baseGitUrl}#subdirectory=openhands-sdk`,
+ "--with",
`${baseGitUrl}#subdirectory=openhands-tools`,
"--with",
`${baseGitUrl}#subdirectory=openhands-workspace`,
@@ -701,6 +736,13 @@ export function buildAgentServerEnv(config) {
// Make the host tools/ directory importable so the agent-server can
// resolve modules listed in tool_module_qualnames (e.g. canvas_ui_tool).
OH_EXTRA_PYTHON_PATH: config.canvasToolsDir,
+ // Tell the agent-server which extensions commit to use for the public
+ // skills catalog. Derived from the @openhands/extensions pin in
+ // package.json; the SDK skips network polling when it already has this
+ // SHA cached. Only injected when the caller has not already set it.
+ ...(DEFAULT_EXTENSIONS_REF && !process.env.EXTENSIONS_REF
+ ? { EXTENSIONS_REF: DEFAULT_EXTENSIONS_REF }
+ : {}),
};
}