Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(examples): inherit acp-docker image from config/defaults.json (#1434)

george larsonb2ba5889d3be
diff --git a/__tests__/scripts/acp-docker-env-sync.test.ts b/__tests__/scripts/acp-docker-env-sync.test.ts
new file mode 100644
index 0000000000..a372212906
--- /dev/null
+++ b/__tests__/scripts/acp-docker-env-sync.test.ts
@@ -0,0 +1,140 @@
+// @vitest-environment node
+//
+// Drift-detection for the examples/acp-docker quickstart. Invariants enforced:
+// the generated pin must equal versions.agentServer from the single source of
+// truth (config/defaults.json); the no-config compose fallback must stay on
+// `latest-python`; and the pinned tag must never fall below the Canvas
+// compatibility floor (compatibility.minimumAgentServer). Any of those drifting
+// fails this test.
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import {
+ computeAgentServerImage,
+ renderEnvLine,
+ upsertEnvLine,
+} from "../../scripts/gen-acp-docker-env.mjs";
+
+const repoRoot = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ "../..",
+);
+
+function read(rel: string): string {
+ return readFileSync(path.join(repoRoot, rel), "utf-8");
+}
+
+const config = JSON.parse(read("config/defaults.json")) as {
+ images: { agentServer: string };
+ versions: { agentServer: string };
+ compatibility: { minimumAgentServer: string };
+};
+
+const pinnedImage = `${config.images.agentServer}:${config.versions.agentServer}-python`;
+
+// Numeric-semver comparison. Throws (rather than silently comparing NaN) if a
+// pin carries a non-numeric segment β€” these defaults.json fields are dotted
+// numeric version pins, so a sha or pre-release tag landing here is a config
+// error the floor check should surface loudly.
+function parseSemver(v: string): number[] {
+ if (!/^\d+(\.\d+)*$/.test(v)) {
+ throw new Error(`expected a dotted numeric version, got "${v}"`);
+ }
+ return v.split(".").map(Number);
+}
+
+function gte(a: string, b: string): boolean {
+ const pa = parseSemver(a);
+ const pb = parseSemver(b);
+ for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+ const da = pa[i] ?? 0;
+ const db = pb[i] ?? 0;
+ if (da !== db) return da > db;
+ }
+ return true;
+}
+
+describe("examples/acp-docker stays in sync with config/defaults.json", () => {
+ it("computeAgentServerImage derives the pinned SoT tag", () => {
+ expect(computeAgentServerImage(config)).toBe(pinnedImage);
+ });
+
+ it("renders the AGENT_SERVER_IMAGE line with the pinned tag", () => {
+ expect(renderEnvLine(config)).toBe(`AGENT_SERVER_IMAGE=${pinnedImage}`);
+ });
+
+ it("the pinned SoT version satisfies the Canvas compatibility floor", () => {
+ expect(
+ gte(config.versions.agentServer, config.compatibility.minimumAgentServer),
+ ).toBe(true);
+ });
+
+ it("the no-config compose fallback uses the SoT registry with the latest-python tag", () => {
+ const compose = read("examples/acp-docker/docker-compose.yml");
+ const match = compose.match(/AGENT_SERVER_IMAGE:-([^}]+)\}/);
+ expect(match?.[1]).toBe(`${config.images.agentServer}:latest-python`);
+ });
+});
+
+describe("gen-acp-docker-env.mjs is safe to import", () => {
+ // The module exports helpers (imported above, and by future consumers), so
+ // importing it must not run main(). The entrypoint guard compares
+ // import.meta.url against process.argv[1] β€” but argv[1] is undefined in some
+ // ESM contexts (e.g. `node --input-type=module -e "import(...)"`), and an
+ // unguarded pathToFileURL(argv[1]) throws ERR_INVALID_ARG_TYPE at import,
+ // before any export is reachable. Reproduces that exact context.
+ const scriptPath = path.join(repoRoot, "scripts", "gen-acp-docker-env.mjs");
+
+ it("imports without throwing when process.argv[1] is undefined", () => {
+ const url = pathToFileURL(scriptPath).href;
+ const res = spawnSync(
+ process.execPath,
+ ["--input-type=module", "-e", `import(${JSON.stringify(url)})`],
+ { encoding: "utf-8" },
+ );
+ expect(res.stderr).not.toMatch(/ERR_INVALID_ARG_TYPE/);
+ expect(res.status).toBe(0);
+ });
+});
+
+describe("upsertEnvLine", () => {
+ const line =
+ "AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:1.28.1-python";
+
+ it("appends the line to an empty file", () => {
+ expect(upsertEnvLine("", line)).toBe(`${line}\n`);
+ });
+
+ it("replaces an existing assignment in place, preserving other lines", () => {
+ const existing =
+ "SESSION_API_KEY=abc\n" +
+ "AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:1.25.0-python\n" +
+ "CLAUDE_CODE_OAUTH_TOKEN=zzz\n";
+ expect(upsertEnvLine(existing, line)).toBe(
+ `SESSION_API_KEY=abc\n${line}\nCLAUDE_CODE_OAUTH_TOKEN=zzz\n`,
+ );
+ });
+
+ it("is idempotent β€” re-running yields one assignment, unchanged content", () => {
+ const once = upsertEnvLine("", line);
+ expect(upsertEnvLine(once, line)).toBe(once);
+ expect(once.match(/^AGENT_SERVER_IMAGE=/gm)?.length).toBe(1);
+ });
+
+ it("treats a commented template line as documentation and appends the real value", () => {
+ // .env.example ships `# AGENT_SERVER_IMAGE=...` as a documented knob; after
+ // `cp .env.example .env` the comment stays and the generator adds the value.
+ const existing =
+ "# AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:latest-python\n";
+ expect(upsertEnvLine(existing, line)).toBe(
+ `${existing.trimEnd()}\n${line}\n`,
+ );
+ });
+
+ it("throws rather than rewrite every line when given a keyless line", () => {
+ expect(() => upsertEnvLine("FOO=bar\n", "novalue")).toThrow();
+ });
+});
diff --git a/examples/acp-docker/.env.example b/examples/acp-docker/.env.example
index e129a73beb..30f326e542 100644
--- a/examples/acp-docker/.env.example
+++ b/examples/acp-docker/.env.example
@@ -4,12 +4,9 @@
# credentials" step (they ride the conversation start request as secrets).
# Set values here only if you want them baked into the container instead.
-# Pin the agent-server image. Default in docker-compose.yml is 1.25.0-python,
-# the first release that includes software-agent-sdk#3510 (required β€” Canvas
-# delivers ACP creds as loopback LookupSecrets that only #3510 resolves without
-# deadlocking). Bump to a newer release, or a post-#3510 main commit:
-# gh api repos/OpenHands/software-agent-sdk/commits/main --jq '.sha[0:7]'
-# AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:1.25.0-python
+# Pin the agent-server image. The compose default is `latest-python`.
+# For a reproducible pin (driven by config/defaults.json): npm run example:acp-docker:env
+# AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:latest-python
# --- Claude Code ---
# A Pro/Max OAuth token, OR an API key. Do NOT set ANTHROPIC_BASE_URL with the
diff --git a/examples/acp-docker/README.md b/examples/acp-docker/README.md
index 538f619e4b..c463561c86 100644
--- a/examples/acp-docker/README.md
+++ b/examples/acp-docker/README.md
@@ -12,27 +12,40 @@ for the full walkthrough; this is the quick start.
```bash
cd examples/acp-docker
-cp .env.example .env # optional β€” only if baking creds into the container
docker compose up
```
-This starts `ghcr.io/openhands/agent-server:1.25.0-python` on
+This starts `ghcr.io/openhands/agent-server:latest-python` on
`http://localhost:8010` with a persistent `acp-data` volume. The image
pre-installs the ACP CLI wrappers and the SDK rewrites `npx -y <pkg>` to those
pinned binaries in-pod, so Canvas can keep sending the default `npx` command
unchanged.
-> **Minimum version:** `1.25.0-python`. Canvas delivers every ACP credential as
-> a loopback `LookupSecret`; only software-agent-sdk#3510 (first released in
-> v1.25.0) resolves it off the event loop. An older image deadlocks the first
-> ACP turn with `Failed to start ACP server: timed out`.
+For a **reproducible, pinned** image, generate `.env` from the repo's single
+source of truth (`config/defaults.json`) first β€” it pins `AGENT_SERVER_IMAGE`
+to the exact `versions.agentServer` release, so two people get the same build:
-To pin a newer release or a post-#3510 main build:
+```bash
+npm run example:acp-docker:env # from the repo root; writes examples/acp-docker/.env
+cd examples/acp-docker && docker compose up
+```
+
+> **Version compatibility.** The common paths keep Canvas and agent-server in
+> sync: zero-config Compose uses `latest-python`, while the pinned path reads
+> `versions.agentServer` from the same `config/defaults.json` used by the Canvas
+> launchers. If you carry an old hand-written `.env` with `AGENT_SERVER_IMAGE`,
+> rerun `npm run example:acp-docker:env` or remove that override so the example
+> does not stay pinned below `compatibility.minimumAgentServer`.
+
+To pin a newer release or a current main build by hand instead:
```bash
AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:$(gh api repos/OpenHands/software-agent-sdk/commits/main --jq '.sha[0:7]')-python docker compose up
```
+To bake credentials into the container instead of entering them in Canvas, copy
+the env template first: `cp .env.example .env` (optional β€” see [Β§3](#3-onboard-with-credentials)).
+
## 2. Point Canvas at it
```bash
diff --git a/examples/acp-docker/docker-compose.yml b/examples/acp-docker/docker-compose.yml
index aa6ac30601..8e14a7d2b6 100644
--- a/examples/acp-docker/docker-compose.yml
+++ b/examples/acp-docker/docker-compose.yml
@@ -19,17 +19,12 @@
services:
agent-server:
- # Pin to a software-agent-sdk release that includes the containerized ACP
- # merges (#1020 file-secret materialisation, #3490 npx→pinned-binary, #3492
- # per-conversation data-dir) AND #3510 (ACP cold-start off the event loop),
- # which is REQUIRED: Canvas now delivers every ACP credential as a loopback
- # LookupSecret, and only #3510 resolves it without self-deadlocking the
- # conversation ("Failed to start ACP server: timed out"). #3510 first ships
- # in v1.25.0, so 1.25.0-python is the minimum. Override with a newer release
- # or a post-#3510 main sha:
- # AGENT_SERVER_IMAGE=ghcr.io/openhands/agent-server:<sha>-python docker compose up
- # gh api repos/OpenHands/software-agent-sdk/commits/main --jq '.sha[0:7]'
- image: ${AGENT_SERVER_IMAGE:-ghcr.io/openhands/agent-server:1.25.0-python}
+ # Default `latest-python` is always >= the version Canvas requires. To pin a
+ # reproducible image (driven by config/defaults.json) or override per-run:
+ # npm run example:acp-docker:env # writes AGENT_SERVER_IMAGE to .env
+ # (Rationale β€” the compatibility floor and the #3510 LookupSecret fix β€” is in
+ # README.md Β§1 and the env-sync test.)
+ image: ${AGENT_SERVER_IMAGE:-ghcr.io/openhands/agent-server:latest-python}
container_name: oh-acp
ports:
# host:container β€” Canvas points VITE_BACKEND_BASE_URL at http://localhost:8010.
diff --git a/package.json b/package.json
index 9665e9f644..a54d945d00 100644
--- a/package.json
+++ b/package.json
@@ -97,7 +97,8 @@
"check-translation-completeness": "node scripts/check-translation-completeness.cjs",
"build:app": "npm run make-i18n && react-router build",
"build:lib": "npm run make-i18n && react-router typegen && cross-env BUILD_LIB=true VITE_APP_ENV=production vite build && tsc -p tsconfig.lib.json",
- "build:docker": "node scripts/docker-build.mjs"
+ "build:docker": "node scripts/docker-build.mjs",
+ "example:acp-docker:env": "node scripts/gen-acp-docker-env.mjs"
},
"lint-staged": {
"src/**/*.{ts,tsx,js}": [
diff --git a/scripts/gen-acp-docker-env.mjs b/scripts/gen-acp-docker-env.mjs
new file mode 100644
index 0000000000..de1ecb0c85
--- /dev/null
+++ b/scripts/gen-acp-docker-env.mjs
@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Generate examples/acp-docker/.env from the single source of truth.
+ *
+ * Reads the version pins in config/defaults.json and writes the
+ * `AGENT_SERVER_IMAGE=` line into examples/acp-docker/.env, pinning the
+ * example to the exact `versions.agentServer` release. This keeps the
+ * reproducible quickstart path on the SoT version instead of a hardcoded
+ * tag that silently drifts below the Canvas compatibility floor
+ * (compatibility.minimumAgentServer) and renders "Disconnected".
+ *
+ * The no-config `docker compose up` path uses the compose fallback
+ * (`latest-python`, always >= the floor); running this script first pins the
+ * example to the reproducible SoT version instead.
+ *
+ * Idempotent: re-running upserts the AGENT_SERVER_IMAGE line and leaves any
+ * other lines in an existing .env untouched.
+ *
+ * Usage:
+ * node scripts/gen-acp-docker-env.mjs # or: npm run example:acp-docker:env
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..");
+
+/**
+ * @param {{ images: { agentServer: string }, versions: { agentServer: string } }} config
+ * @returns {string} e.g. "ghcr.io/openhands/agent-server:1.28.1-python"
+ */
+export function computeAgentServerImage(config) {
+ return `${config.images.agentServer}:${config.versions.agentServer}-python`;
+}
+
+/**
+ * @param {{ images: { agentServer: string }, versions: { agentServer: string } }} config
+ * @returns {string} the `AGENT_SERVER_IMAGE=<image>` line
+ */
+export function renderEnvLine(config) {
+ return `AGENT_SERVER_IMAGE=${computeAgentServerImage(config)}`;
+}
+
+/**
+ * Upsert the AGENT_SERVER_IMAGE line into an existing .env body, preserving
+ * every other line. Appends the line if absent.
+ * @param {string} existing prior .env contents ("" if the file is absent)
+ * @param {string} line the `AGENT_SERVER_IMAGE=...` line to set
+ * @returns {string} the updated .env contents
+ */
+export function upsertEnvLine(existing, line) {
+ const eq = line.indexOf("=");
+ if (eq <= 0) {
+ // A keyless line ("", "novalue", "=value") would make `key` empty and
+ // match every line β€” refuse rather than silently rewrite the whole file.
+ throw new Error(
+ `upsertEnvLine: expected a "KEY=value" line, got "${line}"`,
+ );
+ }
+ const key = line.slice(0, eq + 1); // "AGENT_SERVER_IMAGE="
+ const lines = existing.length ? existing.replace(/\n+$/, "").split("\n") : [];
+ let replaced = false;
+ const next = lines.map((l) => {
+ if (l.startsWith(key)) {
+ replaced = true;
+ return line;
+ }
+ return l;
+ });
+ if (!replaced) next.push(line);
+ return next.join("\n") + "\n";
+}
+
+function loadConfig() {
+ return JSON.parse(
+ readFileSync(join(projectRoot, "config", "defaults.json"), "utf-8"),
+ );
+}
+
+function main() {
+ const config = loadConfig();
+ const line = renderEnvLine(config);
+ const envPath = join(projectRoot, "examples", "acp-docker", ".env");
+
+ let existing = "";
+ try {
+ existing = readFileSync(envPath, "utf-8");
+ } catch {
+ // no .env yet β€” create it
+ }
+
+ const updated = upsertEnvLine(existing, line);
+ writeFileSync(envPath, updated);
+ console.log(`Wrote ${line} to examples/acp-docker/.env`);
+}
+
+// Run main() only when invoked as a CLI. process.argv[1] is undefined in some
+// ESM contexts (e.g. `node --input-type=module -e "import(...)"`), so guard it
+// before pathToFileURL β€” otherwise importing this module for its exports throws
+// ERR_INVALID_ARG_TYPE.
+if (
+ process.argv[1] &&
+ import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+ main();
+}