@zooid/runtime-docker 0.11.2 → 0.12.0

package/docker/agent-claude-code/Dockerfile

@@ -1,6 +1,9 @@
 FROM ghcr.io/zooid-ai/agent-base:latest
 
-RUN npm install -g @agentclientprotocol/claude-agent-acp
+# ZOD074: the ARG default is the pin. docker/versions.json maps this ARG to its
+# npm package; image-versions.manifest.test.ts fails if the two disagree.
+ARG CLAUDE_AGENT_ACP_VERSION=0.74.0
+RUN npm install -g @agentclientprotocol/claude-agent-acp@${CLAUDE_AGENT_ACP_VERSION}
 
 # No CMD — DockerAcpRuntime sets the entrypoint to the resolved ACP shim
 # command (e.g. `npx @agentclientprotocol/claude-agent-acp`). The npm install

package/docker/agent-codex/Dockerfile

@@ -1,3 +1,6 @@
 FROM ghcr.io/zooid-ai/agent-base:latest
 
-RUN npm install -g @zed-industries/codex-acp
+# ZOD074: the ARG default is the pin. docker/versions.json maps this ARG to its
+# npm package; image-versions.manifest.test.ts fails if the two disagree.
+ARG CODEX_ACP_VERSION=0.16.0
+RUN npm install -g @zed-industries/codex-acp@${CODEX_ACP_VERSION}

package/docker/agent-opencode/Dockerfile

@@ -1,3 +1,6 @@
 FROM ghcr.io/zooid-ai/agent-base:latest
 
-RUN npm install -g opencode-ai
+# ZOD074: the ARG default is the pin. docker/versions.json maps this ARG to its
+# npm package; image-versions.manifest.test.ts fails if the two disagree.
+ARG OPENCODE_VERSION=1.18.27
+RUN npm install -g opencode-ai@${OPENCODE_VERSION}

package/docker/agent-pi/Dockerfile

@@ -0,0 +1,17 @@
+FROM ghcr.io/zooid-ai/agent-base:latest
+
+# pi-acp is an adapter: it spawns `pi --mode rpc` as a child process, so BOTH
+# packages must be on PATH. Installing only pi-acp yields an image that starts,
+# completes the ACP handshake, and then fails on the first turn.
+#
+# ZOD073 pins these inline, unlike the three older agent images, which install
+# unpinned and therefore freeze at whatever was current when someone last ran
+# the publish workflow by hand. [[ZOD074]] hoists all four into
+# docker/versions.json and automates the refresh.
+ARG PI_VERSION=0.85.0
+ARG PI_ACP_VERSION=0.0.33
+RUN npm install -g \
+      @earendil-works/pi-coding-agent@${PI_VERSION} \
+      pi-acp@${PI_ACP_VERSION}
+
+# No CMD — DockerAcpRuntime sets the entrypoint to the resolved ACP shim command.

package/docker/versions.json

@@ -0,0 +1,15 @@
+{
+  "agent-claude-code": {
+    "CLAUDE_AGENT_ACP_VERSION": "@agentclientprotocol/claude-agent-acp"
+  },
+  "agent-codex": {
+    "CODEX_ACP_VERSION": "@zed-industries/codex-acp"
+  },
+  "agent-opencode": {
+    "OPENCODE_VERSION": "opencode-ai"
+  },
+  "agent-pi": {
+    "PI_VERSION": "@earendil-works/pi-coding-agent",
+    "PI_ACP_VERSION": "pi-acp"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zooid/runtime-docker",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Docker runtime for zooid. Spawns the agent CLI inside a container with a workspace mount and an env allowlist.",
   "type": "module",
   "license": "MIT",
@@ -25,11 +25,12 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@zooid/core": "^0.11.2"
+    "@zooid/core": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.5.0",
     "vitest": "^3.2.0"
   },

package/src/image-versions-cli.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// ZOD074. `pnpm agent-images:check [--write]`
+//
+// Reads docker/versions.json + the Dockerfiles, asks the npm registry what is
+// current, and reports (or rewrites) stale pins. Exits 1 when anything is out
+// of date so the workflow can branch on it.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  collectPins,
+  findOutdated,
+  applyPin,
+  npmLatestUrl,
+  type ImageManifest,
+} from './image-versions.js'
+
+const DOCKER_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'docker')
+const dockerfilePath = (dir: string) => join(DOCKER_DIR, dir, 'Dockerfile')
+
+async function fetchLatest(packageName: string): Promise<string | undefined> {
+  const res = await fetch(npmLatestUrl(packageName), {
+    headers: { accept: 'application/json' },
+  })
+  if (!res.ok) {
+    console.error(`  ! ${packageName}: registry returned ${res.status}`)
+    return undefined
+  }
+  return ((await res.json()) as { version?: string }).version
+}
+
+async function main(): Promise<number> {
+  const write = process.argv.includes('--write')
+
+  const manifest: ImageManifest = JSON.parse(
+    readFileSync(join(DOCKER_DIR, 'versions.json'), 'utf8'),
+  )
+  const dockerfiles = Object.fromEntries(
+    Object.keys(manifest).map((dir) => [dir, readFileSync(dockerfilePath(dir), 'utf8')]),
+  )
+
+  // Throws on drift — a bad manifest is a hard stop, not a warning.
+  const pins = collectPins(manifest, dockerfiles)
+
+  const names = [...new Set(pins.map((p) => p.packageName))]
+  const resolved = await Promise.all(names.map(fetchLatest))
+  const latest: Record<string, string> = {}
+  names.forEach((n, i) => {
+    const v = resolved[i]
+    if (v) latest[n] = v
+  })
+
+  const outdated = findOutdated(pins, latest)
+  if (outdated.length === 0) {
+    console.log(`All ${pins.length} agent-image pins are current.`)
+    return 0
+  }
+
+  for (const p of outdated) {
+    console.log(`${p.imageDir}: ${p.packageName} ${p.version} -> ${p.latest}`)
+  }
+
+  if (write) {
+    // Group by file so an image with two pins is written once.
+    const byDir = new Map<string, typeof outdated>()
+    for (const p of outdated) {
+      byDir.set(p.imageDir, [...(byDir.get(p.imageDir) ?? []), p])
+    }
+    for (const [dir, ps] of byDir) {
+      let text = dockerfiles[dir]
+      for (const p of ps) text = applyPin(text, p.argName, p.latest)
+      writeFileSync(dockerfilePath(dir), text)
+      console.log(`  wrote ${dir}/Dockerfile`)
+    }
+  }
+
+  return 1
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error(err instanceof Error ? err.message : err)
+    process.exit(2)
+  },
+)

package/src/image-versions.manifest.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { collectPins, type ImageManifest } from './image-versions.js'
+
+const DOCKER_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'docker')
+
+function loadManifest(): ImageManifest {
+  return JSON.parse(readFileSync(join(DOCKER_DIR, 'versions.json'), 'utf8'))
+}
+
+function loadDockerfiles(manifest: ImageManifest): Record<string, string> {
+  return Object.fromEntries(
+    Object.keys(manifest).map((dir) => [
+      dir,
+      readFileSync(join(DOCKER_DIR, dir, 'Dockerfile'), 'utf8'),
+    ]),
+  )
+}
+
+describe('docker/versions.json ⇄ Dockerfiles (ZOD074)', () => {
+  it('collectPins accepts the committed tree — no drift in either direction', () => {
+    const manifest = loadManifest()
+    expect(() => collectPins(manifest, loadDockerfiles(manifest))).not.toThrow()
+  })
+
+  it('every pin resolves to a non-empty version', () => {
+    const manifest = loadManifest()
+    for (const pin of collectPins(manifest, loadDockerfiles(manifest))) {
+      expect(pin.version, `${pin.imageDir}/${pin.argName}`).toMatch(/^\d+\.\d+\.\d+/)
+    }
+  })
+
+  // Catches the other forgetting: a new agent-* image dir that pins packages
+  // but never gets a manifest entry, so the bumper never sees it.
+  it('every agent-* image dir with a *_VERSION ARG is in the manifest', () => {
+    const manifest = loadManifest()
+    const dirs = readdirSync(DOCKER_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('agent-'))
+      .map((e) => e.name)
+      .filter((d) => existsSync(join(DOCKER_DIR, d, 'Dockerfile')))
+
+    for (const dir of dirs) {
+      const text = readFileSync(join(DOCKER_DIR, dir, 'Dockerfile'), 'utf8')
+      if (/^ARG\s+\w*_VERSION=/m.test(text)) {
+        expect(Object.keys(manifest), `${dir} pins versions but is not in versions.json`)
+          .toContain(dir)
+      }
+    }
+  })
+
+  // agent-base installs from apt, not npm — it must stay out (see Non-goals).
+  it('does not claim agent-base', () => {
+    expect(Object.keys(loadManifest())).not.toContain('agent-base')
+  })
+})

package/src/image-versions.test.ts

@@ -0,0 +1,212 @@
+import { describe, it, expect } from 'vitest'
+import {
+  parseDockerfileArgs,
+  collectPins,
+  findOutdated,
+  applyPin,
+  npmLatestUrl,
+  type ImageManifest,
+} from './image-versions.js'
+
+const OPENCODE_DOCKERFILE = `FROM ghcr.io/zooid-ai/agent-base:latest
+
+ARG OPENCODE_VERSION=1.18.27
+RUN npm install -g opencode-ai@\${OPENCODE_VERSION}
+`
+
+const PI_DOCKERFILE = `FROM ghcr.io/zooid-ai/agent-base:latest
+
+ARG PI_VERSION=0.85.0
+ARG PI_ACP_VERSION=0.0.33
+RUN npm install -g \\
+      @earendil-works/pi-coding-agent@\${PI_VERSION} \\
+      pi-acp@\${PI_ACP_VERSION}
+`
+
+describe('parseDockerfileArgs', () => {
+  it('reads ARG NAME=value pairs', () => {
+    expect(parseDockerfileArgs(OPENCODE_DOCKERFILE)).toEqual({
+      OPENCODE_VERSION: '1.18.27',
+    })
+  })
+
+  it('reads several ARGs from one file', () => {
+    expect(parseDockerfileArgs(PI_DOCKERFILE)).toEqual({
+      PI_VERSION: '0.85.0',
+      PI_ACP_VERSION: '0.0.33',
+    })
+  })
+
+  it('tolerates extra whitespace', () => {
+    expect(parseDockerfileArgs('ARG   FOO_VERSION=1.2.3   \n')).toEqual({
+      FOO_VERSION: '1.2.3',
+    })
+  })
+
+  it('records a defaultless ARG as an empty string (collectPins rejects it)', () => {
+    expect(parseDockerfileArgs('ARG BARE_ARG\n')).toEqual({ BARE_ARG: '' })
+  })
+
+  it('ignores ARG-like text inside a comment', () => {
+    expect(parseDockerfileArgs('# ARG COMMENTED_VERSION=9.9.9\n')).toEqual({})
+  })
+
+  it('returns an empty object for a Dockerfile with no ARGs', () => {
+    expect(parseDockerfileArgs('FROM node:22-slim\nRUN echo hi\n')).toEqual({})
+  })
+})
+
+describe('collectPins', () => {
+  const manifest: ImageManifest = {
+    'agent-opencode': { OPENCODE_VERSION: 'opencode-ai' },
+  }
+
+  it('joins manifest ARG names to Dockerfile ARG defaults', () => {
+    expect(collectPins(manifest, { 'agent-opencode': OPENCODE_DOCKERFILE })).toEqual([
+      {
+        imageDir: 'agent-opencode',
+        argName: 'OPENCODE_VERSION',
+        packageName: 'opencode-ai',
+        version: '1.18.27',
+      },
+    ])
+  })
+
+  it('flattens several images into one list', () => {
+    const pins = collectPins(
+      {
+        'agent-opencode': { OPENCODE_VERSION: 'opencode-ai' },
+        'agent-pi': {
+          PI_VERSION: '@earendil-works/pi-coding-agent',
+          PI_ACP_VERSION: 'pi-acp',
+        },
+      },
+      { 'agent-opencode': OPENCODE_DOCKERFILE, 'agent-pi': PI_DOCKERFILE },
+    )
+    expect(pins).toHaveLength(3)
+    expect(pins.map((p) => p.packageName).sort()).toEqual([
+      '@earendil-works/pi-coding-agent',
+      'opencode-ai',
+      'pi-acp',
+    ])
+  })
+
+  // Drift, direction 1: the manifest claims an ARG the Dockerfile does not have.
+  it('throws when the manifest names an ARG the Dockerfile lacks', () => {
+    expect(() =>
+      collectPins(
+        { 'agent-opencode': { MISSING_VERSION: 'opencode-ai' } },
+        { 'agent-opencode': OPENCODE_DOCKERFILE },
+      ),
+    ).toThrow(/MISSING_VERSION/)
+  })
+
+  // Drift, direction 2: a version-bearing ARG nobody claims. This is the one
+  // that matters — it catches adding a pin and forgetting versions.json, which
+  // would leave the bumper silently ignoring it forever.
+  it('throws when a *_VERSION ARG is absent from the manifest', () => {
+    expect(() =>
+      collectPins({ 'agent-pi': { PI_VERSION: '@earendil-works/pi-coding-agent' } }, {
+        'agent-pi': PI_DOCKERFILE,
+      }),
+    ).toThrow(/PI_ACP_VERSION/)
+  })
+
+  it('throws when the manifest names an image with no Dockerfile', () => {
+    expect(() => collectPins({ 'agent-ghost': { X_VERSION: 'x' } }, {})).toThrow(
+      /agent-ghost/,
+    )
+  })
+
+  it('throws when a manifest ARG has no default value', () => {
+    expect(() =>
+      collectPins({ 'agent-x': { BARE_ARG: 'x' } }, { 'agent-x': 'ARG BARE_ARG\n' }),
+    ).toThrow(/BARE_ARG/)
+  })
+})
+
+describe('findOutdated', () => {
+  const pins = [
+    {
+      imageDir: 'agent-opencode',
+      argName: 'OPENCODE_VERSION',
+      packageName: 'opencode-ai',
+      version: '1.15.7',
+    },
+    {
+      imageDir: 'agent-pi',
+      argName: 'PI_ACP_VERSION',
+      packageName: 'pi-acp',
+      version: '0.0.33',
+    },
+  ]
+
+  it('reports pins whose version differs from latest', () => {
+    const out = findOutdated(pins, { 'opencode-ai': '1.18.27', 'pi-acp': '0.0.33' })
+    expect(out).toEqual([{ ...pins[0], latest: '1.18.27' }])
+  })
+
+  it('reports nothing when every pin matches', () => {
+    expect(findOutdated(pins, { 'opencode-ai': '1.15.7', 'pi-acp': '0.0.33' })).toEqual(
+      [],
+    )
+  })
+
+  // Inequality, not semver ordering: the registry's `latest` dist-tag is
+  // authoritative, including when upstream yanks and goes backwards.
+  it('treats a lower latest as outdated too', () => {
+    const out = findOutdated([pins[0]], { 'opencode-ai': '1.15.6' })
+    expect(out).toHaveLength(1)
+    expect(out[0].latest).toBe('1.15.6')
+  })
+
+  it('skips packages with no lookup result rather than guessing', () => {
+    expect(findOutdated(pins, {})).toEqual([])
+  })
+})
+
+describe('applyPin', () => {
+  it('rewrites the ARG default in place', () => {
+    const next = applyPin(OPENCODE_DOCKERFILE, 'OPENCODE_VERSION', '1.18.27')
+    expect(next).toContain('ARG OPENCODE_VERSION=1.18.27')
+    expect(next).not.toContain('1.15.7')
+  })
+
+  it('leaves the rest of the file byte-identical', () => {
+    const next = applyPin(OPENCODE_DOCKERFILE, 'OPENCODE_VERSION', '2.0.0')
+    expect(next.split('\n').length).toBe(OPENCODE_DOCKERFILE.split('\n').length)
+    expect(next).toContain('RUN npm install -g opencode-ai@${OPENCODE_VERSION}')
+  })
+
+  it('rewrites only the named ARG', () => {
+    const next = applyPin(PI_DOCKERFILE, 'PI_ACP_VERSION', '0.1.0')
+    expect(next).toContain('ARG PI_VERSION=0.85.0')
+    expect(next).toContain('ARG PI_ACP_VERSION=0.1.0')
+  })
+
+  it('throws when the ARG is not present', () => {
+    expect(() => applyPin(OPENCODE_DOCKERFILE, 'NOPE_VERSION', '1.0.0')).toThrow(
+      /NOPE_VERSION/,
+    )
+  })
+})
+
+describe('npmLatestUrl', () => {
+  it('builds the latest-dist-tag URL for an unscoped package', () => {
+    expect(npmLatestUrl('opencode-ai')).toBe(
+      'https://registry.npmjs.org/opencode-ai/latest',
+    )
+  })
+
+  // The slash in a scoped name must be percent-encoded or the registry 404s
+  // silently — the single easiest thing to get wrong here.
+  it('percent-encodes the slash in a scoped package', () => {
+    expect(npmLatestUrl('@zed-industries/codex-acp')).toBe(
+      'https://registry.npmjs.org/@zed-industries%2Fcodex-acp/latest',
+    )
+  })
+
+  it('does not encode the leading @', () => {
+    expect(npmLatestUrl('@scope/pkg')).toContain('/@scope%2Fpkg/')
+  })
+})

package/src/image-versions.ts

@@ -0,0 +1,90 @@
+// ZOD074. The Dockerfile ARG default IS the pin; docker/versions.json maps each
+// ARG name to the npm package it pins (which the Dockerfile only expresses in a
+// shell line). collectPins joins the two and refuses to proceed if they disagree.
+
+export interface ImageManifest {
+  /** image dir (e.g. "agent-opencode") -> ARG name -> npm package name */
+  [imageDir: string]: { [argName: string]: string }
+}
+
+export interface Pin {
+  imageDir: string
+  argName: string
+  packageName: string
+  version: string
+}
+
+export interface OutdatedPin extends Pin {
+  latest: string
+}
+
+const ARG_LINE = /^[ \t]*ARG[ \t]+([A-Za-z_][A-Za-z0-9_]*)(?:[ \t]*=[ \t]*(.*?))?[ \t]*$/
+
+export function parseDockerfileArgs(text: string): Record<string, string> {
+  const args: Record<string, string> = {}
+  for (const line of text.split('\n')) {
+    const m = ARG_LINE.exec(line)
+    if (m) args[m[1]] = m[2] ?? ''
+  }
+  return args
+}
+
+export function collectPins(
+  manifest: ImageManifest,
+  dockerfiles: Record<string, string>,
+): Pin[] {
+  const pins: Pin[] = []
+  for (const [imageDir, argMap] of Object.entries(manifest)) {
+    const text = dockerfiles[imageDir]
+    if (text === undefined) {
+      throw new Error(`versions.json names "${imageDir}", which has no Dockerfile`)
+    }
+    const args = parseDockerfileArgs(text)
+
+    for (const [argName, packageName] of Object.entries(argMap)) {
+      const version = args[argName]
+      if (version === undefined) {
+        throw new Error(`${imageDir}: versions.json names ARG ${argName}, absent from its Dockerfile`)
+      }
+      if (version === '') {
+        throw new Error(`${imageDir}: ARG ${argName} has no default value, so there is no pin`)
+      }
+      pins.push({ imageDir, argName, packageName, version })
+    }
+
+    // The direction that actually bites: a pin nobody indexed is a pin the
+    // bumper will never refresh.
+    for (const argName of Object.keys(args)) {
+      if (argName.endsWith('_VERSION') && !(argName in argMap)) {
+        throw new Error(`${imageDir}: ARG ${argName} is not in versions.json`)
+      }
+    }
+  }
+  return pins
+}
+
+export function findOutdated(pins: Pin[], latest: Record<string, string>): OutdatedPin[] {
+  const out: OutdatedPin[] = []
+  for (const pin of pins) {
+    const current = latest[pin.packageName]
+    // No lookup result means the fetch failed or the name is wrong. Staying
+    // silent beats reporting a bump we cannot substantiate.
+    if (current === undefined) continue
+    // Inequality, not ordering: the registry's `latest` dist-tag is definitional.
+    if (current !== pin.version) out.push({ ...pin, latest: current })
+  }
+  return out
+}
+
+export function applyPin(text: string, argName: string, version: string): string {
+  const pattern = new RegExp(`^([ \\t]*ARG[ \\t]+${argName}[ \\t]*=[ \\t]*).*$`, 'm')
+  if (!pattern.test(text)) {
+    throw new Error(`ARG ${argName} not found`)
+  }
+  return text.replace(pattern, `$1${version}`)
+}
+
+export function npmLatestUrl(packageName: string): string {
+  // A scoped name's slash must be percent-encoded; the @ must not be.
+  return `https://registry.npmjs.org/${packageName.replace('/', '%2F')}/latest`
+}