build: agent-runtime images (base/opencode/pi) -> paperclipinc (#105)

* build(agent-runtime): resurrect agent-runtime image build, publish to paperclipinc

Brings docker/agent-runtime (Dockerfile.base + per-harness Dockerfiles + buildx-bake.hcl),
tools/agent-shim, tools/workspace-init, and .github/workflows/agent-runtime-images.yml
from feat/k8s-cloud-adapter-m4a-bugfixes. Repoints all REGISTRY references from
ghcr.io/paperclipai to ghcr.io/paperclipinc. Extends cosign signing to cover
opencode and pi in addition to base and claude.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* build(agent-runtime): scope publish to base+opencode+pi, trigger on main

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: stubbi

.github/workflows/agent-runtime-images.yml

@@ -0,0 +1,83 @@
+name: Agent runtime images
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docker/agent-runtime/**"
+      - "tools/agent-shim/**"
+      - "tools/workspace-init/**"
+      - "packages/workspace-strategy/**"
+      - ".github/workflows/agent-runtime-images.yml"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version tag (e.g., v1.0.0 or dev-test)"
+        required: true
+        default: "dev"
+
+permissions:
+  contents: read
+  packages: write
+  id-token: write   # cosign keyless OIDC
+
+env:
+  REGISTRY: ghcr.io/paperclipinc
+  VERSION: ${{ github.event.inputs.version || format('git-{0}', github.sha) }}
+
+jobs:
+  build-and-sign:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU (multi-arch builds)
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install cosign
+        uses: sigstore/cosign-installer@v3
+
+      - name: Build + push base + opencode + pi (multi-arch)
+        id: bake
+        run: |
+          # Scope: cloud agent execution currently ships opencode + pi only. We
+          # build just those two harness images (+ their base) to keep the
+          # publish fast and avoid failing on harnesses we do not deploy yet.
+          docker buildx bake \
+            -f docker/agent-runtime/buildx-bake.hcl \
+            base opencode pi \
+            --set "*.platforms=linux/amd64,linux/arm64" \
+            --set "*.push=true" \
+            --metadata-file=bake-metadata.json
+          # Extract digests for cosign signing
+          BASE_DIGEST=$(jq -r '."base"."containerimage.digest"' bake-metadata.json)
+          OPENCODE_DIGEST=$(jq -r '."opencode"."containerimage.digest"' bake-metadata.json)
+          PI_DIGEST=$(jq -r '."pi"."containerimage.digest"' bake-metadata.json)
+          echo "base_digest=$BASE_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "opencode_digest=$OPENCODE_DIGEST" >> "$GITHUB_OUTPUT"
+          echo "pi_digest=$PI_DIGEST" >> "$GITHUB_OUTPUT"
+        env:
+          VERSION: ${{ env.VERSION }}
+          REGISTRY: ${{ env.REGISTRY }}
+
+      - name: Cosign sign base
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-base@${{ steps.bake.outputs.base_digest }}"
+
+      - name: Cosign sign opencode
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-opencode@${{ steps.bake.outputs.opencode_digest }}"
+
+      - name: Cosign sign pi
+        run: |
+          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-pi@${{ steps.bake.outputs.pi_digest }}"

docker/agent-runtime/Dockerfile.acpx

@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+USER root
+# acpx is the ACPX wrapper that bridges to claude / codex backends.
+# Verified npm package name: "acpx" (bin 'acpx' → dist/cli.js).
+RUN npm install -g acpx@latest \
+    && chown -R 1000:1000 /usr/lib/node_modules \
+    || true
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v acpx >/dev/null 2>&1 || (echo "acpx not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.base

@@ -0,0 +1,67 @@
+# syntax=docker/dockerfile:1.6
+ARG NODE_VERSION=22
+ARG TARGETARCH
+
+# ---------- Stage 1: build agent-shim ----------
+FROM golang:1.25-bookworm AS shim-build
+ARG TARGETARCH
+WORKDIR /src
+COPY tools/agent-shim/ ./
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH:-amd64} \
+    go build -ldflags='-s -w' -o /out/paperclip-agent-shim .
+
+# ---------- Stage 2: build workspace-init (Node) ----------
+FROM node:${NODE_VERSION}-bookworm-slim AS wsinit-build
+WORKDIR /src
+COPY pnpm-lock.yaml package.json pnpm-workspace.yaml tsconfig.base.json ./
+# Repo root pnpm config has patchedDependencies referencing ./patches/* — copy
+# the patch files so `pnpm install --frozen-lockfile` does not ENOENT on them
+# even though we install zero workspaces that consume embedded-postgres.
+COPY patches/ ./patches/
+COPY packages/workspace-strategy/ ./packages/workspace-strategy/
+COPY tools/workspace-init/ ./tools/workspace-init/
+RUN corepack enable && pnpm install --frozen-lockfile \
+    && pnpm --filter @paperclipai/workspace-strategy build \
+    && pnpm --filter @paperclipai/workspace-init build \
+    # Materialize publishConfig into the live package.json so that Node's
+    # production module resolution targets dist/ instead of src/*.ts. This
+    # mirrors what `pnpm publish` does, but for our local consumption inside
+    # the runtime image where TypeScript loaders are not present.
+    && node -e "const f='packages/workspace-strategy/package.json';const p=JSON.parse(require('fs').readFileSync(f,'utf8'));if(p.publishConfig&&p.publishConfig.exports){p.exports=p.publishConfig.exports;}require('fs').writeFileSync(f,JSON.stringify(p,null,2)+'\n');"
+
+# ---------- Stage 3: runtime base image ----------
+FROM ubuntu:22.04 AS base
+ARG NODE_VERSION
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      ca-certificates curl git tini gnupg \
+    && rm -rf /var/lib/apt/lists/* \
+    && curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd -g 1000 paperclip \
+    && useradd -u 1000 -g 1000 -d /home/paperclip -m -s /bin/bash paperclip
+
+COPY --from=shim-build   /out/paperclip-agent-shim                          /usr/local/bin/paperclip-agent-shim
+
+# workspace-init resolves @paperclipai/workspace-strategy via a pnpm workspace
+# symlink (tools/workspace-init/node_modules/@paperclipai/workspace-strategy ->
+# ../../../../packages/workspace-strategy). Mirror the /src layout under
+# /opt/paperclip/app so Node's module resolution and that relative symlink
+# both keep working at runtime.
+COPY --from=wsinit-build /src/tools/workspace-init/package.json              /opt/paperclip/app/tools/workspace-init/package.json
+COPY --from=wsinit-build /src/tools/workspace-init/dist                      /opt/paperclip/app/tools/workspace-init/dist
+COPY --from=wsinit-build /src/tools/workspace-init/node_modules              /opt/paperclip/app/tools/workspace-init/node_modules
+COPY --from=wsinit-build /src/packages/workspace-strategy/package.json       /opt/paperclip/app/packages/workspace-strategy/package.json
+COPY --from=wsinit-build /src/packages/workspace-strategy/dist               /opt/paperclip/app/packages/workspace-strategy/dist
+COPY --from=wsinit-build /src/node_modules                                   /opt/paperclip/app/node_modules
+
+# Convenience launcher so the init container can just run `paperclip-workspace-init`
+RUN printf '#!/bin/sh\nexec node --enable-source-maps /opt/paperclip/app/tools/workspace-init/dist/index.js "$@"\n' \
+      > /usr/local/bin/paperclip-workspace-init \
+    && chmod +x /usr/local/bin/paperclip-workspace-init
+
+USER 1000:1000
+WORKDIR /workspace
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/usr/local/bin/paperclip-agent-shim"]

docker/agent-runtime/Dockerfile.claude

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+USER root
+RUN npm install -g @anthropic-ai/claude-code@latest \
+    && chown -R 1000:1000 /usr/lib/node_modules \
+    || true
+
+# @anthropic-ai/claude-code installs as 'claude', but the shim expects 'claude-code'
+RUN command -v claude >/dev/null 2>&1 && ln -s /usr/bin/claude /usr/bin/claude-code || true
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v claude-code >/dev/null 2>&1 || (echo "claude-code not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.codex

@@ -0,0 +1,13 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+USER root
+RUN npm install -g @openai/codex@latest \
+    && chown -R 1000:1000 /usr/lib/node_modules \
+    || true
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v codex >/dev/null 2>&1 || (echo "codex not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.gemini

@@ -0,0 +1,13 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+USER root
+RUN npm install -g @google/gemini-cli@latest \
+    && chown -R 1000:1000 /usr/lib/node_modules \
+    || true
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v gemini >/dev/null 2>&1 || (echo "gemini not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.hermes

@@ -0,0 +1,17 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+# hermes_local is in the legacy sessioned-adapter set but has no upstream
+# npm package wired into Paperclip locally yet (see
+# packages/adapter-utils/src/session-compaction.ts vs the absent
+# packages/adapters/hermes-local/). This stub image preserves a cloud
+# runtime slot for hermes_local; whoever ports the hermes binary to
+# Paperclip locally adds the `npm install -g <pkg>` and the PATH check
+# to this Dockerfile.
+#
+# Until then, runs targeting hermes_local on the cloud adapter will boot
+# the container but `agent-shim` will fail with "hermes not on PATH" when
+# it tries to invoke the CLI.
+
+USER 1000:1000

docker/agent-runtime/Dockerfile.opencode

@@ -0,0 +1,14 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+USER root
+# opencode-ai npm package; binary on PATH is `opencode`.
+RUN npm install -g opencode-ai@latest \
+    && chown -R 1000:1000 /usr/lib/node_modules \
+    || true
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v opencode >/dev/null 2>&1 || (echo "opencode not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.pi

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1.6
+ARG BASE_TAG=dev
+FROM paperclipinc/agent-runtime-base:${BASE_TAG}
+
+USER root
+# pi is the multi-provider Pi coding-agent router. Verified npm package:
+# @mariozechner/pi-coding-agent (binary 'pi' → dist/cli.js). Same package
+# is used by SANDBOX_INSTALL_COMMAND in pi-local/src/index.ts.
+RUN npm install -g @mariozechner/pi-coding-agent@latest \
+    && chown -R 1000:1000 /usr/lib/node_modules \
+    || true
+
+USER 1000:1000
+
+# Verify the CLI is on PATH for the shim's exec.LookPath
+RUN command -v pi >/dev/null 2>&1 || (echo "pi not on PATH"; exit 1)

docker/agent-runtime/README.md

@@ -0,0 +1,121 @@
+# Agent Runtime Image Family
+
+Paperclip.inc publishes container images for remote agents. Images are named `agent-runtime-{adapterType}:{paperclipVersion}` and distributed via `ghcr.io/paperclipinc/`.
+
+## Image Lineup
+
+- **`agent-runtime-base`**: Foundation. Ubuntu 22.04 + Node 22 + git + tini + non-root user + shim + workspace-init.
+- **`agent-runtime-claude`**: Extends base with `@anthropic-ai/claude-code` CLI globally installed.
+- Future: Additional adapter-specific images follow the same pattern (e.g., `agent-runtime-go`, `agent-runtime-rust`).
+
+## Base Image Contents
+
+**OS & Runtime:**
+- Ubuntu 22.04
+- Node.js 22 (via NodeSource APT repo)
+- git
+- tini (PID-1 init, ensures signal propagation)
+- Non-root user `paperclip` (uid/gid 1000)
+
+**Paperclip Binaries:**
+- `/usr/local/bin/paperclip-agent-shim` — Go binary compiled from `tools/agent-shim/`. Reads `/run/paperclip/runtime-command.json` and `syscall.Exec`s the adapter CLI.
+- `/usr/local/bin/paperclip-workspace-init` — Node script entry point. Used by init container to bootstrap the workspace.
+
+**Defaults:**
+- `USER`: 1000:1000 (paperclip, non-root)
+- `WORKDIR`: `/workspace` — PVCs are mounted here
+- `ENTRYPOINT`: `/usr/bin/tini --` (PID-1 reaper, forwards signals)
+- `CMD`: `/usr/local/bin/paperclip-agent-shim`
+
+## Building Locally
+
+### Multi-architecture (amd64 + arm64)
+
+```bash
+docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --push
+```
+
+### Host-only (faster iteration)
+
+Replace the architecture with your machine's native platform:
+
+```bash
+docker buildx bake -f docker/agent-runtime/buildx-bake.hcl \
+  --set "*.platforms=linux/$(uname -m | sed s/x86_64/amd64/)" \
+  --load
+```
+
+### Custom tag or registry
+
+```bash
+docker buildx bake -f docker/agent-runtime/buildx-bake.hcl \
+  --set "*.tags=myregistry/agent-runtime-base:mytag" \
+  --load
+```
+
+## Quickstart Smoke Test
+
+Build and verify the `agent-runtime-claude` image runs locally:
+
+```bash
+docker buildx bake -f docker/agent-runtime/buildx-bake.hcl \
+  --set "*.platforms=linux/$(uname -m | sed s/x86_64/amd64/)" \
+  --load
+docker run --rm ghcr.io/paperclipinc/agent-runtime-claude:dev claude-code --version
+```
+
+## Init Container (workspace-init)
+
+The init container prepares the workspace before the agent starts. It reads environment variables, bootstraps the workspace directory tree, and exits.
+
+**Environment Variables:**
+- `PAPERCLIP_WORKSPACE_REQUEST` — JSON serialized workspace request (required)
+- `PAPERCLIP_WORKSPACE_ROOT` — Where to write workspace state (default: `/workspace`)
+- `BOOTSTRAP_TOKEN` — Authentication token for workspace API (required)
+- `PAPERCLIP_PUBLIC_URL` — Public endpoint for workspace callbacks (required)
+
+**Failure Modes:**
+Missing or invalid env vars → exit code 1. Pod init never repeats; failure blocks agent startup.
+
+## Agent Container (paperclip-agent-shim)
+
+The main agent runs as the shim process (PID 1 under tini). The shim:
+
+1. Reads `/run/paperclip/runtime-command.json` — a JSON file mounted by the Job controller
+2. Parses `{ command, args, ... }` — the adapter CLI and arguments
+3. `syscall.Exec`s the adapter process, replacing itself
+4. SIGTERM from kubelet propagates directly to the adapter (no process zombie)
+
+**runtime-command.json Contract:**
+```json
+{
+  "command": "claude-code",
+  "args": ["--token", "xyz", "--workspace", "/workspace"]
+}
+```
+
+The shim makes no assumptions about command structure; it is adapter-agnostic. Future adapters swap the command/args; the image remains the same.
+
+## Security Model
+
+- **Non-root execution** — user 1000:1000, no capability grant
+- **PSS Restricted compatible** — no privileged containers, no host mounts, read-only filesystem (except `/workspace` + `/tmp`)
+- **No secrets baked in** — API tokens, credentials come from per-Job ephemeral Secrets mounted as env vars or files
+- **Image signing** — cosign keyless OIDC in CI (see Task 29)
+
+## Versioning Policy
+
+**agent-runtime-base:**
+- Version tag `vX.Y.Z` published when the shim or workspace-init source changes
+- Includes all base layer content (OS, Node, git, tini, non-root user)
+
+**agent-runtime-claude:**
+- Builds on top of base at the same version tag
+- Version tag bumps independently when a new `@anthropic-ai/claude-code` release is pinned
+- Currently uses `npm install @anthropic-ai/claude-code@latest` for the `dev` tag; CI workflow (Task 29) will pin exact semver versions per release
+
+## Multi-arch Caveats
+
+- Both amd64 and arm64 images are built in CI; local builds require `--load` on single-arch or `--push` for multi-arch
+- Go shim cross-compilation is automatic via `GOARCH` (see Dockerfile.base Stage 1)
+- Node modules are platform-agnostic; workspace-init rebuilds without issues across architectures