π 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.tsnew file mode 100644index 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.exampleindex 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 thediff --git a/examples/acp-docker/README.md b/examples/acp-docker/README.mdindex 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.```bashcd examples/acp-docker-cp .env.example .env # optional β only if baking creds into the containerdocker 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 imagepre-installs the ACP CLI wrappers and the SDK rewrites `npx -y <pkg>` to thosepinned binaries in-pod, so Canvas can keep sending the default `npx` commandunchanged.-> **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:```bashAGENT_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```bashdiff --git a/examples/acp-docker/docker-compose.yml b/examples/acp-docker/docker-compose.ymlindex 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-acpports:# host:container β Canvas points VITE_BACKEND_BASE_URL at http://localhost:8010.diff --git a/package.json b/package.jsonindex 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.mjsnew file mode 100644index 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();+}