GGitHubfix(build): enforce Node 24 across Paperclip (#11792)

38d8f371创建于 8月22日历史提交

文件	最后提交记录	最后更新时间
Dockerfile.base	fix(build): enforce Node 24 across Paperclip (#11792) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip runs across the CLI, server, adapters, plugins, CI, and container images. > - These surfaces declared different Node.js versions from 20 through 24. > - A newer `@types/node` major can expose APIs that the supported runtime does not provide. > - Node.js 20 is no longer a suitable project baseline, and Node.js 24 is the current LTS line. > - This pull request sets Node.js 24.11.0 as one repository-wide baseline, adds a drift check, and gives users actionable startup guidance when their runtime is too old. > - The benefit is one clear runtime contract for development, release, installation, and published packages. ## Linked Issues or Issue Description Refs #2734 Refs #11727 Refs #739 ## What Changed - Require Node.js 24.11.0 or newer in all 42 package manifests and runtime checks. - Use Node.js 24 in GitHub Actions, Docker images, smoke images, sandbox setup, portable installs, and esbuild targets. - Align every direct `@types/node` declaration on `^24.0.0`. - Prevent Dependabot from opening major `@types/node` upgrades without a matching runtime decision. - Add `.nvmrc` and a CI policy check for Node version drift. - Update ACP version gates, tests, and user documentation for the new minimum. - Print a non-blocking warning on CLI and server startup when Node is unsupported, with remediation through a version manager or the documented downloaded `install.sh` workflow. - Deduplicate that warning when `paperclipai run` boots the CLI and server in the same process. ## Verification - `node scripts/check-node-version-policy.mjs` - `node --check scripts/check-node-version-policy.mjs` - `node --check cli/esbuild.config.mjs` - `node --check scripts/generate-npm-package-json.mjs` - `bash -n scripts/install.sh scripts/test-install-sh-docker.sh scripts/e2e-install-lifecycle.sh` - Parsed all 42 package manifests and confirmed `engines.node` is `>=24.11.0`. - `git diff --check` - `vitest run packages/adapter-utils/src/sandbox-install-command.test.ts` passed with 3 tests. - `vitest run cli/src/node-version.test.ts` passed with 4 tests. - Directly exercised the shared warning helper for unsupported-version messaging and same-process deduplication. - The focused exe.dev suite could not resolve the locally unbuilt plugin SDK from this isolated worktree. A full offline workspace install was also blocked because the package-manager signature verifier requires registry access. The full suite was not run locally; draft CI performs a clean install and evaluates the wider impact. ## Risks - This is a breaking runtime change for users, plugins, and deployments that still use Node.js 20 or 22. - Published workspace packages will now produce an engine warning or failure in strict package managers on older Node.js releases. - Node.js 24 can reveal dependency, native module, Playwright, or agent CLI compatibility issues in CI. - The bootstrap installer now installs Node.js 24 when the current runtime is older than 24.11.0. - The portable sandbox fallback is pinned to Node.js 24.11.0 and depends on that upstream tarball remaining available. - Unsupported runtimes continue booting after a warning, so a later incompatibility can still fail at its point of use. - The CLI and server share the warning policy through the published `@paperclipai/shared` package; packaging checks must keep that subpath export available. - This PR does not commit `pnpm-lock.yaml` because repository policy assigns lockfile generation to CI. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex based on GPT-5. The exact deployment ID and context window are not exposed in this session. Reasoning, repository tools, shell execution, and GitHub tools were enabled. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	1 个月前
Dockerfile.claude	build(agent-runtime): harness runtime images for sandboxed execution (stage 3/3) (#7934) > [!NOTE] > This is stage 3 of 3 of the staged Kubernetes contribution: stage 1 is the kubernetes sandbox-provider plugin (#5790), stage 2 is the provider backend/hardening refresh filed separately, and this stage ships the runtime images those sandboxes run. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Sandboxed agent execution (Refs #248) runs each agent turn in an isolated environment; the kubernetes sandbox provider (stage 1, #5790) schedules those runs as hardened pods > - A sandbox pod needs a runtime image with the harness CLI preinstalled: installing CLIs at run start is slow, flaky, and needs network egress the sandbox should not have > - There is no first-party image family for this, so every deployer would have to hand-roll Ubuntu + Node + CLI images per harness and solve signal handling, non-root, and image chaining themselves > - This PR ships the agent-runtime image family: a hardened base (non-root uid 1000, tini, git, the agent shim) plus one derived image per harness, a buildx bake file that chains them, and a publish workflow with cosign keyless signing > - The benefit is that any sandbox infrastructure, the kubernetes provider or otherwise, gets ready-made, signed, security-hardened per-harness runtime images that are verified in production across five harnesses ## Linked Issues or Issue Description Refs #248 (sandboxed agent execution proposal) and #5790 (the kubernetes sandbox provider, stage 1 of this contribution, which consumes these images as per-run runtime images via its adapter defaults). No issue covers the image gap itself, described in-PR: sandbox providers reference `ghcr.io/paperclipai/agent-runtime-` images, but the repository contains neither the Dockerfiles nor the workflow that builds and publishes them. Without this, self-deployers cannot reproduce or audit the images their agent runs execute in. ## What Changed - `docker/agent-runtime/Dockerfile.base`: foundation image. Ubuntu 22.04 + Node 22 + git + tini (PID 1, signal propagation) + non-root `paperclip` user (uid/gid 1000) + the agent shim compiled in a Go build stage. `WORKDIR /workspace`, entrypoint `tini -- paperclip-agent-shim`. - One derived Dockerfile per harness: `opencode` (opencode-ai), `pi` (@mariozechner/pi-coding-agent), `codex` (@openai/codex), `gemini` (@google/gemini-cli, plus headless auth-mode settings), `claude` (@anthropic-ai/claude-code, symlinked as `claude-code`). Each installs the CLI as root, returns to uid 1000, and asserts the binary is on PATH at build time. - `acpx` and `hermes` Dockerfiles are included in the bake group but are not in the default publish scope (hermes is a stub until a CLI package exists). - `docker/agent-runtime/buildx-bake.hcl`: builds the whole family in one pass. Derived targets chain off the `base` target through bake `contexts` (the literal registry in each `FROM` is overridden to `target:base` at build time, so no intermediate push is needed). `REGISTRY` (default `ghcr.io/paperclipai`) and `VERSION` are overridable variables. - `tools/agent-shim/`: a small Go shim that runs as the container command. It reads `/run/paperclip/runtime-command.json` (`{ "command", "args" }`), resolves the harness CLI on PATH, and `syscall.Exec`s it so SIGTERM from the kubelet reaches the harness directly. Harness-agnostic, with unit tests. - `.github/workflows/agent-runtime-images.yml`: builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) for linux/amd64 on `workflow_dispatch` (explicit version tag) or pushes to `master` touching these paths, then signs every digest with cosign keyless OIDC. Uses only `GITHUB_TOKEN`; no extra secrets. - `docker/agent-runtime/README.md`: image lineup, base contents, local build instructions, the runtime-command contract, and the security model. Additive only: nothing in the product loads these images. Deployments opt in via their sandbox provider configuration (for example the kubernetes plugin's image settings). ## Verification - `cd tools/agent-shim && go build ./... && go test ./... && go vet ./...`: all passing. - `docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --print base opencode pi codex gemini claude`: resolves cleanly; every tag and build context lands on `ghcr.io/paperclipai/agent-runtime-` and derived targets map the base ref to `target:base`. - Workflow YAML validated (parses, single job, no org-specific secrets). - This exact image family (built from these Dockerfiles, bake file, and workflow) is what runs agent execution in production on paperclip.inc, verified end-to-end across five harnesses (opencode, pi, codex, gemini, claude): each as a full loop from assigned issue to per-run runtime image in a sandboxed pod to completed run. ## Risks - Low risk: purely additive, nothing in paperclip-server or the UI references these files. The workflow only triggers on its own paths. - Derived images install harness CLIs `@latest` at build time; a broken upstream CLI release would surface at image build, not at run time, and the PATH assertion fails the build rather than shipping a broken image. - The hermes image is an explicit stub (documented in its Dockerfile) until a hermes CLI package exists; it is outside the default publish scope. - cosign signing is keyless OIDC with the workflow identity; no long-lived signing keys are introduced. ## Model Used Claude Opus 4.8 (claude-opus-4-8, 1M context, extended thinking, tool use via Claude Code). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	3 个月前
Dockerfile.codex	build(agent-runtime): harness runtime images for sandboxed execution (stage 3/3) (#7934) > [!NOTE] > This is stage 3 of 3 of the staged Kubernetes contribution: stage 1 is the kubernetes sandbox-provider plugin (#5790), stage 2 is the provider backend/hardening refresh filed separately, and this stage ships the runtime images those sandboxes run. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Sandboxed agent execution (Refs #248) runs each agent turn in an isolated environment; the kubernetes sandbox provider (stage 1, #5790) schedules those runs as hardened pods > - A sandbox pod needs a runtime image with the harness CLI preinstalled: installing CLIs at run start is slow, flaky, and needs network egress the sandbox should not have > - There is no first-party image family for this, so every deployer would have to hand-roll Ubuntu + Node + CLI images per harness and solve signal handling, non-root, and image chaining themselves > - This PR ships the agent-runtime image family: a hardened base (non-root uid 1000, tini, git, the agent shim) plus one derived image per harness, a buildx bake file that chains them, and a publish workflow with cosign keyless signing > - The benefit is that any sandbox infrastructure, the kubernetes provider or otherwise, gets ready-made, signed, security-hardened per-harness runtime images that are verified in production across five harnesses ## Linked Issues or Issue Description Refs #248 (sandboxed agent execution proposal) and #5790 (the kubernetes sandbox provider, stage 1 of this contribution, which consumes these images as per-run runtime images via its adapter defaults). No issue covers the image gap itself, described in-PR: sandbox providers reference `ghcr.io/paperclipai/agent-runtime-` images, but the repository contains neither the Dockerfiles nor the workflow that builds and publishes them. Without this, self-deployers cannot reproduce or audit the images their agent runs execute in. ## What Changed - `docker/agent-runtime/Dockerfile.base`: foundation image. Ubuntu 22.04 + Node 22 + git + tini (PID 1, signal propagation) + non-root `paperclip` user (uid/gid 1000) + the agent shim compiled in a Go build stage. `WORKDIR /workspace`, entrypoint `tini -- paperclip-agent-shim`. - One derived Dockerfile per harness: `opencode` (opencode-ai), `pi` (@mariozechner/pi-coding-agent), `codex` (@openai/codex), `gemini` (@google/gemini-cli, plus headless auth-mode settings), `claude` (@anthropic-ai/claude-code, symlinked as `claude-code`). Each installs the CLI as root, returns to uid 1000, and asserts the binary is on PATH at build time. - `acpx` and `hermes` Dockerfiles are included in the bake group but are not in the default publish scope (hermes is a stub until a CLI package exists). - `docker/agent-runtime/buildx-bake.hcl`: builds the whole family in one pass. Derived targets chain off the `base` target through bake `contexts` (the literal registry in each `FROM` is overridden to `target:base` at build time, so no intermediate push is needed). `REGISTRY` (default `ghcr.io/paperclipai`) and `VERSION` are overridable variables. - `tools/agent-shim/`: a small Go shim that runs as the container command. It reads `/run/paperclip/runtime-command.json` (`{ "command", "args" }`), resolves the harness CLI on PATH, and `syscall.Exec`s it so SIGTERM from the kubelet reaches the harness directly. Harness-agnostic, with unit tests. - `.github/workflows/agent-runtime-images.yml`: builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) for linux/amd64 on `workflow_dispatch` (explicit version tag) or pushes to `master` touching these paths, then signs every digest with cosign keyless OIDC. Uses only `GITHUB_TOKEN`; no extra secrets. - `docker/agent-runtime/README.md`: image lineup, base contents, local build instructions, the runtime-command contract, and the security model. Additive only: nothing in the product loads these images. Deployments opt in via their sandbox provider configuration (for example the kubernetes plugin's image settings). ## Verification - `cd tools/agent-shim && go build ./... && go test ./... && go vet ./...`: all passing. - `docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --print base opencode pi codex gemini claude`: resolves cleanly; every tag and build context lands on `ghcr.io/paperclipai/agent-runtime-` and derived targets map the base ref to `target:base`. - Workflow YAML validated (parses, single job, no org-specific secrets). - This exact image family (built from these Dockerfiles, bake file, and workflow) is what runs agent execution in production on paperclip.inc, verified end-to-end across five harnesses (opencode, pi, codex, gemini, claude): each as a full loop from assigned issue to per-run runtime image in a sandboxed pod to completed run. ## Risks - Low risk: purely additive, nothing in paperclip-server or the UI references these files. The workflow only triggers on its own paths. - Derived images install harness CLIs `@latest` at build time; a broken upstream CLI release would surface at image build, not at run time, and the PATH assertion fails the build rather than shipping a broken image. - The hermes image is an explicit stub (documented in its Dockerfile) until a hermes CLI package exists; it is outside the default publish scope. - cosign signing is keyless OIDC with the workflow identity; no long-lived signing keys are introduced. ## Model Used Claude Opus 4.8 (claude-opus-4-8, 1M context, extended thinking, tool use via Claude Code). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	3 个月前
Dockerfile.gemini	build(agent-runtime): harness runtime images for sandboxed execution (stage 3/3) (#7934) > [!NOTE] > This is stage 3 of 3 of the staged Kubernetes contribution: stage 1 is the kubernetes sandbox-provider plugin (#5790), stage 2 is the provider backend/hardening refresh filed separately, and this stage ships the runtime images those sandboxes run. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Sandboxed agent execution (Refs #248) runs each agent turn in an isolated environment; the kubernetes sandbox provider (stage 1, #5790) schedules those runs as hardened pods > - A sandbox pod needs a runtime image with the harness CLI preinstalled: installing CLIs at run start is slow, flaky, and needs network egress the sandbox should not have > - There is no first-party image family for this, so every deployer would have to hand-roll Ubuntu + Node + CLI images per harness and solve signal handling, non-root, and image chaining themselves > - This PR ships the agent-runtime image family: a hardened base (non-root uid 1000, tini, git, the agent shim) plus one derived image per harness, a buildx bake file that chains them, and a publish workflow with cosign keyless signing > - The benefit is that any sandbox infrastructure, the kubernetes provider or otherwise, gets ready-made, signed, security-hardened per-harness runtime images that are verified in production across five harnesses ## Linked Issues or Issue Description Refs #248 (sandboxed agent execution proposal) and #5790 (the kubernetes sandbox provider, stage 1 of this contribution, which consumes these images as per-run runtime images via its adapter defaults). No issue covers the image gap itself, described in-PR: sandbox providers reference `ghcr.io/paperclipai/agent-runtime-` images, but the repository contains neither the Dockerfiles nor the workflow that builds and publishes them. Without this, self-deployers cannot reproduce or audit the images their agent runs execute in. ## What Changed - `docker/agent-runtime/Dockerfile.base`: foundation image. Ubuntu 22.04 + Node 22 + git + tini (PID 1, signal propagation) + non-root `paperclip` user (uid/gid 1000) + the agent shim compiled in a Go build stage. `WORKDIR /workspace`, entrypoint `tini -- paperclip-agent-shim`. - One derived Dockerfile per harness: `opencode` (opencode-ai), `pi` (@mariozechner/pi-coding-agent), `codex` (@openai/codex), `gemini` (@google/gemini-cli, plus headless auth-mode settings), `claude` (@anthropic-ai/claude-code, symlinked as `claude-code`). Each installs the CLI as root, returns to uid 1000, and asserts the binary is on PATH at build time. - `acpx` and `hermes` Dockerfiles are included in the bake group but are not in the default publish scope (hermes is a stub until a CLI package exists). - `docker/agent-runtime/buildx-bake.hcl`: builds the whole family in one pass. Derived targets chain off the `base` target through bake `contexts` (the literal registry in each `FROM` is overridden to `target:base` at build time, so no intermediate push is needed). `REGISTRY` (default `ghcr.io/paperclipai`) and `VERSION` are overridable variables. - `tools/agent-shim/`: a small Go shim that runs as the container command. It reads `/run/paperclip/runtime-command.json` (`{ "command", "args" }`), resolves the harness CLI on PATH, and `syscall.Exec`s it so SIGTERM from the kubelet reaches the harness directly. Harness-agnostic, with unit tests. - `.github/workflows/agent-runtime-images.yml`: builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) for linux/amd64 on `workflow_dispatch` (explicit version tag) or pushes to `master` touching these paths, then signs every digest with cosign keyless OIDC. Uses only `GITHUB_TOKEN`; no extra secrets. - `docker/agent-runtime/README.md`: image lineup, base contents, local build instructions, the runtime-command contract, and the security model. Additive only: nothing in the product loads these images. Deployments opt in via their sandbox provider configuration (for example the kubernetes plugin's image settings). ## Verification - `cd tools/agent-shim && go build ./... && go test ./... && go vet ./...`: all passing. - `docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --print base opencode pi codex gemini claude`: resolves cleanly; every tag and build context lands on `ghcr.io/paperclipai/agent-runtime-` and derived targets map the base ref to `target:base`. - Workflow YAML validated (parses, single job, no org-specific secrets). - This exact image family (built from these Dockerfiles, bake file, and workflow) is what runs agent execution in production on paperclip.inc, verified end-to-end across five harnesses (opencode, pi, codex, gemini, claude): each as a full loop from assigned issue to per-run runtime image in a sandboxed pod to completed run. ## Risks - Low risk: purely additive, nothing in paperclip-server or the UI references these files. The workflow only triggers on its own paths. - Derived images install harness CLIs `@latest` at build time; a broken upstream CLI release would surface at image build, not at run time, and the PATH assertion fails the build rather than shipping a broken image. - The hermes image is an explicit stub (documented in its Dockerfile) until a hermes CLI package exists; it is outside the default publish scope. - cosign signing is keyless OIDC with the workflow identity; no long-lived signing keys are introduced. ## Model Used Claude Opus 4.8 (claude-opus-4-8, 1M context, extended thinking, tool use via Claude Code). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	3 个月前
Dockerfile.hermes	build(agent-runtime): harness runtime images for sandboxed execution (stage 3/3) (#7934) > [!NOTE] > This is stage 3 of 3 of the staged Kubernetes contribution: stage 1 is the kubernetes sandbox-provider plugin (#5790), stage 2 is the provider backend/hardening refresh filed separately, and this stage ships the runtime images those sandboxes run. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Sandboxed agent execution (Refs #248) runs each agent turn in an isolated environment; the kubernetes sandbox provider (stage 1, #5790) schedules those runs as hardened pods > - A sandbox pod needs a runtime image with the harness CLI preinstalled: installing CLIs at run start is slow, flaky, and needs network egress the sandbox should not have > - There is no first-party image family for this, so every deployer would have to hand-roll Ubuntu + Node + CLI images per harness and solve signal handling, non-root, and image chaining themselves > - This PR ships the agent-runtime image family: a hardened base (non-root uid 1000, tini, git, the agent shim) plus one derived image per harness, a buildx bake file that chains them, and a publish workflow with cosign keyless signing > - The benefit is that any sandbox infrastructure, the kubernetes provider or otherwise, gets ready-made, signed, security-hardened per-harness runtime images that are verified in production across five harnesses ## Linked Issues or Issue Description Refs #248 (sandboxed agent execution proposal) and #5790 (the kubernetes sandbox provider, stage 1 of this contribution, which consumes these images as per-run runtime images via its adapter defaults). No issue covers the image gap itself, described in-PR: sandbox providers reference `ghcr.io/paperclipai/agent-runtime-` images, but the repository contains neither the Dockerfiles nor the workflow that builds and publishes them. Without this, self-deployers cannot reproduce or audit the images their agent runs execute in. ## What Changed - `docker/agent-runtime/Dockerfile.base`: foundation image. Ubuntu 22.04 + Node 22 + git + tini (PID 1, signal propagation) + non-root `paperclip` user (uid/gid 1000) + the agent shim compiled in a Go build stage. `WORKDIR /workspace`, entrypoint `tini -- paperclip-agent-shim`. - One derived Dockerfile per harness: `opencode` (opencode-ai), `pi` (@mariozechner/pi-coding-agent), `codex` (@openai/codex), `gemini` (@google/gemini-cli, plus headless auth-mode settings), `claude` (@anthropic-ai/claude-code, symlinked as `claude-code`). Each installs the CLI as root, returns to uid 1000, and asserts the binary is on PATH at build time. - `acpx` and `hermes` Dockerfiles are included in the bake group but are not in the default publish scope (hermes is a stub until a CLI package exists). - `docker/agent-runtime/buildx-bake.hcl`: builds the whole family in one pass. Derived targets chain off the `base` target through bake `contexts` (the literal registry in each `FROM` is overridden to `target:base` at build time, so no intermediate push is needed). `REGISTRY` (default `ghcr.io/paperclipai`) and `VERSION` are overridable variables. - `tools/agent-shim/`: a small Go shim that runs as the container command. It reads `/run/paperclip/runtime-command.json` (`{ "command", "args" }`), resolves the harness CLI on PATH, and `syscall.Exec`s it so SIGTERM from the kubelet reaches the harness directly. Harness-agnostic, with unit tests. - `.github/workflows/agent-runtime-images.yml`: builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) for linux/amd64 on `workflow_dispatch` (explicit version tag) or pushes to `master` touching these paths, then signs every digest with cosign keyless OIDC. Uses only `GITHUB_TOKEN`; no extra secrets. - `docker/agent-runtime/README.md`: image lineup, base contents, local build instructions, the runtime-command contract, and the security model. Additive only: nothing in the product loads these images. Deployments opt in via their sandbox provider configuration (for example the kubernetes plugin's image settings). ## Verification - `cd tools/agent-shim && go build ./... && go test ./... && go vet ./...`: all passing. - `docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --print base opencode pi codex gemini claude`: resolves cleanly; every tag and build context lands on `ghcr.io/paperclipai/agent-runtime-` and derived targets map the base ref to `target:base`. - Workflow YAML validated (parses, single job, no org-specific secrets). - This exact image family (built from these Dockerfiles, bake file, and workflow) is what runs agent execution in production on paperclip.inc, verified end-to-end across five harnesses (opencode, pi, codex, gemini, claude): each as a full loop from assigned issue to per-run runtime image in a sandboxed pod to completed run. ## Risks - Low risk: purely additive, nothing in paperclip-server or the UI references these files. The workflow only triggers on its own paths. - Derived images install harness CLIs `@latest` at build time; a broken upstream CLI release would surface at image build, not at run time, and the PATH assertion fails the build rather than shipping a broken image. - The hermes image is an explicit stub (documented in its Dockerfile) until a hermes CLI package exists; it is outside the default publish scope. - cosign signing is keyless OIDC with the workflow identity; no long-lived signing keys are introduced. ## Model Used Claude Opus 4.8 (claude-opus-4-8, 1M context, extended thinking, tool use via Claude Code). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	3 个月前
Dockerfile.opencode	build(agent-runtime): harness runtime images for sandboxed execution (stage 3/3) (#7934) > [!NOTE] > This is stage 3 of 3 of the staged Kubernetes contribution: stage 1 is the kubernetes sandbox-provider plugin (#5790), stage 2 is the provider backend/hardening refresh filed separately, and this stage ships the runtime images those sandboxes run. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Sandboxed agent execution (Refs #248) runs each agent turn in an isolated environment; the kubernetes sandbox provider (stage 1, #5790) schedules those runs as hardened pods > - A sandbox pod needs a runtime image with the harness CLI preinstalled: installing CLIs at run start is slow, flaky, and needs network egress the sandbox should not have > - There is no first-party image family for this, so every deployer would have to hand-roll Ubuntu + Node + CLI images per harness and solve signal handling, non-root, and image chaining themselves > - This PR ships the agent-runtime image family: a hardened base (non-root uid 1000, tini, git, the agent shim) plus one derived image per harness, a buildx bake file that chains them, and a publish workflow with cosign keyless signing > - The benefit is that any sandbox infrastructure, the kubernetes provider or otherwise, gets ready-made, signed, security-hardened per-harness runtime images that are verified in production across five harnesses ## Linked Issues or Issue Description Refs #248 (sandboxed agent execution proposal) and #5790 (the kubernetes sandbox provider, stage 1 of this contribution, which consumes these images as per-run runtime images via its adapter defaults). No issue covers the image gap itself, described in-PR: sandbox providers reference `ghcr.io/paperclipai/agent-runtime-` images, but the repository contains neither the Dockerfiles nor the workflow that builds and publishes them. Without this, self-deployers cannot reproduce or audit the images their agent runs execute in. ## What Changed - `docker/agent-runtime/Dockerfile.base`: foundation image. Ubuntu 22.04 + Node 22 + git + tini (PID 1, signal propagation) + non-root `paperclip` user (uid/gid 1000) + the agent shim compiled in a Go build stage. `WORKDIR /workspace`, entrypoint `tini -- paperclip-agent-shim`. - One derived Dockerfile per harness: `opencode` (opencode-ai), `pi` (@mariozechner/pi-coding-agent), `codex` (@openai/codex), `gemini` (@google/gemini-cli, plus headless auth-mode settings), `claude` (@anthropic-ai/claude-code, symlinked as `claude-code`). Each installs the CLI as root, returns to uid 1000, and asserts the binary is on PATH at build time. - `acpx` and `hermes` Dockerfiles are included in the bake group but are not in the default publish scope (hermes is a stub until a CLI package exists). - `docker/agent-runtime/buildx-bake.hcl`: builds the whole family in one pass. Derived targets chain off the `base` target through bake `contexts` (the literal registry in each `FROM` is overridden to `target:base` at build time, so no intermediate push is needed). `REGISTRY` (default `ghcr.io/paperclipai`) and `VERSION` are overridable variables. - `tools/agent-shim/`: a small Go shim that runs as the container command. It reads `/run/paperclip/runtime-command.json` (`{ "command", "args" }`), resolves the harness CLI on PATH, and `syscall.Exec`s it so SIGTERM from the kubelet reaches the harness directly. Harness-agnostic, with unit tests. - `.github/workflows/agent-runtime-images.yml`: builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) for linux/amd64 on `workflow_dispatch` (explicit version tag) or pushes to `master` touching these paths, then signs every digest with cosign keyless OIDC. Uses only `GITHUB_TOKEN`; no extra secrets. - `docker/agent-runtime/README.md`: image lineup, base contents, local build instructions, the runtime-command contract, and the security model. Additive only: nothing in the product loads these images. Deployments opt in via their sandbox provider configuration (for example the kubernetes plugin's image settings). ## Verification - `cd tools/agent-shim && go build ./... && go test ./... && go vet ./...`: all passing. - `docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --print base opencode pi codex gemini claude`: resolves cleanly; every tag and build context lands on `ghcr.io/paperclipai/agent-runtime-` and derived targets map the base ref to `target:base`. - Workflow YAML validated (parses, single job, no org-specific secrets). - This exact image family (built from these Dockerfiles, bake file, and workflow) is what runs agent execution in production on paperclip.inc, verified end-to-end across five harnesses (opencode, pi, codex, gemini, claude): each as a full loop from assigned issue to per-run runtime image in a sandboxed pod to completed run. ## Risks - Low risk: purely additive, nothing in paperclip-server or the UI references these files. The workflow only triggers on its own paths. - Derived images install harness CLIs `@latest` at build time; a broken upstream CLI release would surface at image build, not at run time, and the PATH assertion fails the build rather than shipping a broken image. - The hermes image is an explicit stub (documented in its Dockerfile) until a hermes CLI package exists; it is outside the default publish scope. - cosign signing is keyless OIDC with the workflow identity; no long-lived signing keys are introduced. ## Model Used Claude Opus 4.8 (claude-opus-4-8, 1M context, extended thinking, tool use via Claude Code). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	3 个月前
Dockerfile.pi	build(agent-runtime): harness runtime images for sandboxed execution (stage 3/3) (#7934) > [!NOTE] > This is stage 3 of 3 of the staged Kubernetes contribution: stage 1 is the kubernetes sandbox-provider plugin (#5790), stage 2 is the provider backend/hardening refresh filed separately, and this stage ships the runtime images those sandboxes run. ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Sandboxed agent execution (Refs #248) runs each agent turn in an isolated environment; the kubernetes sandbox provider (stage 1, #5790) schedules those runs as hardened pods > - A sandbox pod needs a runtime image with the harness CLI preinstalled: installing CLIs at run start is slow, flaky, and needs network egress the sandbox should not have > - There is no first-party image family for this, so every deployer would have to hand-roll Ubuntu + Node + CLI images per harness and solve signal handling, non-root, and image chaining themselves > - This PR ships the agent-runtime image family: a hardened base (non-root uid 1000, tini, git, the agent shim) plus one derived image per harness, a buildx bake file that chains them, and a publish workflow with cosign keyless signing > - The benefit is that any sandbox infrastructure, the kubernetes provider or otherwise, gets ready-made, signed, security-hardened per-harness runtime images that are verified in production across five harnesses ## Linked Issues or Issue Description Refs #248 (sandboxed agent execution proposal) and #5790 (the kubernetes sandbox provider, stage 1 of this contribution, which consumes these images as per-run runtime images via its adapter defaults). No issue covers the image gap itself, described in-PR: sandbox providers reference `ghcr.io/paperclipai/agent-runtime-` images, but the repository contains neither the Dockerfiles nor the workflow that builds and publishes them. Without this, self-deployers cannot reproduce or audit the images their agent runs execute in. ## What Changed - `docker/agent-runtime/Dockerfile.base`: foundation image. Ubuntu 22.04 + Node 22 + git + tini (PID 1, signal propagation) + non-root `paperclip` user (uid/gid 1000) + the agent shim compiled in a Go build stage. `WORKDIR /workspace`, entrypoint `tini -- paperclip-agent-shim`. - One derived Dockerfile per harness: `opencode` (opencode-ai), `pi` (@mariozechner/pi-coding-agent), `codex` (@openai/codex), `gemini` (@google/gemini-cli, plus headless auth-mode settings), `claude` (@anthropic-ai/claude-code, symlinked as `claude-code`). Each installs the CLI as root, returns to uid 1000, and asserts the binary is on PATH at build time. - `acpx` and `hermes` Dockerfiles are included in the bake group but are not in the default publish scope (hermes is a stub until a CLI package exists). - `docker/agent-runtime/buildx-bake.hcl`: builds the whole family in one pass. Derived targets chain off the `base` target through bake `contexts` (the literal registry in each `FROM` is overridden to `target:base` at build time, so no intermediate push is needed). `REGISTRY` (default `ghcr.io/paperclipai`) and `VERSION` are overridable variables. - `tools/agent-shim/`: a small Go shim that runs as the container command. It reads `/run/paperclip/runtime-command.json` (`{ "command", "args" }`), resolves the harness CLI on PATH, and `syscall.Exec`s it so SIGTERM from the kubelet reaches the harness directly. Harness-agnostic, with unit tests. - `.github/workflows/agent-runtime-images.yml`: builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) for linux/amd64 on `workflow_dispatch` (explicit version tag) or pushes to `master` touching these paths, then signs every digest with cosign keyless OIDC. Uses only `GITHUB_TOKEN`; no extra secrets. - `docker/agent-runtime/README.md`: image lineup, base contents, local build instructions, the runtime-command contract, and the security model. Additive only: nothing in the product loads these images. Deployments opt in via their sandbox provider configuration (for example the kubernetes plugin's image settings). ## Verification - `cd tools/agent-shim && go build ./... && go test ./... && go vet ./...`: all passing. - `docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --print base opencode pi codex gemini claude`: resolves cleanly; every tag and build context lands on `ghcr.io/paperclipai/agent-runtime-` and derived targets map the base ref to `target:base`. - Workflow YAML validated (parses, single job, no org-specific secrets). - This exact image family (built from these Dockerfiles, bake file, and workflow) is what runs agent execution in production on paperclip.inc, verified end-to-end across five harnesses (opencode, pi, codex, gemini, claude): each as a full loop from assigned issue to per-run runtime image in a sandboxed pod to completed run. ## Risks - Low risk: purely additive, nothing in paperclip-server or the UI references these files. The workflow only triggers on its own paths. - Derived images install harness CLIs `@latest` at build time; a broken upstream CLI release would surface at image build, not at run time, and the PATH assertion fails the build rather than shipping a broken image. - The hermes image is an explicit stub (documented in its Dockerfile) until a hermes CLI package exists; it is outside the default publish scope. - cosign signing is keyless OIDC with the workflow identity; no long-lived signing keys are introduced. ## Model Used Claude Opus 4.8 (claude-opus-4-8, 1M context, extended thinking, tool use via Claude Code). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots (no UI changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	3 个月前
README.md	fix(build): enforce Node 24 across Paperclip (#11792) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip runs across the CLI, server, adapters, plugins, CI, and container images. > - These surfaces declared different Node.js versions from 20 through 24. > - A newer `@types/node` major can expose APIs that the supported runtime does not provide. > - Node.js 20 is no longer a suitable project baseline, and Node.js 24 is the current LTS line. > - This pull request sets Node.js 24.11.0 as one repository-wide baseline, adds a drift check, and gives users actionable startup guidance when their runtime is too old. > - The benefit is one clear runtime contract for development, release, installation, and published packages. ## Linked Issues or Issue Description Refs #2734 Refs #11727 Refs #739 ## What Changed - Require Node.js 24.11.0 or newer in all 42 package manifests and runtime checks. - Use Node.js 24 in GitHub Actions, Docker images, smoke images, sandbox setup, portable installs, and esbuild targets. - Align every direct `@types/node` declaration on `^24.0.0`. - Prevent Dependabot from opening major `@types/node` upgrades without a matching runtime decision. - Add `.nvmrc` and a CI policy check for Node version drift. - Update ACP version gates, tests, and user documentation for the new minimum. - Print a non-blocking warning on CLI and server startup when Node is unsupported, with remediation through a version manager or the documented downloaded `install.sh` workflow. - Deduplicate that warning when `paperclipai run` boots the CLI and server in the same process. ## Verification - `node scripts/check-node-version-policy.mjs` - `node --check scripts/check-node-version-policy.mjs` - `node --check cli/esbuild.config.mjs` - `node --check scripts/generate-npm-package-json.mjs` - `bash -n scripts/install.sh scripts/test-install-sh-docker.sh scripts/e2e-install-lifecycle.sh` - Parsed all 42 package manifests and confirmed `engines.node` is `>=24.11.0`. - `git diff --check` - `vitest run packages/adapter-utils/src/sandbox-install-command.test.ts` passed with 3 tests. - `vitest run cli/src/node-version.test.ts` passed with 4 tests. - Directly exercised the shared warning helper for unsupported-version messaging and same-process deduplication. - The focused exe.dev suite could not resolve the locally unbuilt plugin SDK from this isolated worktree. A full offline workspace install was also blocked because the package-manager signature verifier requires registry access. The full suite was not run locally; draft CI performs a clean install and evaluates the wider impact. ## Risks - This is a breaking runtime change for users, plugins, and deployments that still use Node.js 20 or 22. - Published workspace packages will now produce an engine warning or failure in strict package managers on older Node.js releases. - Node.js 24 can reveal dependency, native module, Playwright, or agent CLI compatibility issues in CI. - The bootstrap installer now installs Node.js 24 when the current runtime is older than 24.11.0. - The portable sandbox fallback is pinned to Node.js 24.11.0 and depends on that upstream tarball remaining available. - Unsupported runtimes continue booting after a warning, so a later incompatibility can still fail at its point of use. - The CLI and server share the warning policy through the published `@paperclipai/shared` package; packaging checks must keep that subpath export available. - This PR does not commit `pnpm-lock.yaml` because repository policy assigns lockfile generation to CI. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex based on GPT-5. The exact deployment ID and context window are not exposed in this session. Reasoning, repository tools, shell execution, and GitHub tools were enabled. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	1 个月前
buildx-bake.hcl	Make ACP the default engine for local adapters (#9238) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Adapter packages are the bridge between the control plane and local agent harnesses such as Claude Code, Codex, and Gemini CLI. > - ACP support was concentrated in a separate `acpx_local` adapter, which made ACP feel like a separate agent choice instead of an execution capability of the harness adapters. > - Claude, Codex, and Gemini now have ACP-capable harnesses, so the native adapter should own ACP selection, fallback, config, transcript parsing, and environment diagnostics. > - The standalone ACPX adapter still needs a compatibility path for existing rows, but it should not be offered as an active adapter for new agents. > - This pull request moves the shared ACP runtime into `@paperclipai/acpx-engine`, wires Claude/Codex/Gemini local adapters to prefer ACP when prerequisites are available, and retires `acpx_local` to a tombstone. > - The benefit is one adapter per harness, richer ACP transcripts by default where possible, and a migration path for existing Claude/Codex ACPX agents. ## Linked Issues or Issue Description Closes #5932 — the broken default `acpx_local` Claude path is replaced by native `claude_local` ACP support, existing Claude/Codex ACPX rows migrate to native adapters, and new agents no longer choose the standalone ACPX adapter. Refs #4893 — original merged ACPX local adapter runtime that this PR replaces with native per-harness ACP engines. Refs #6590 — prior ACPX-Claude seamlessness work folded into the new native Claude ACP path. Refs #197 — related open generic ACP/Kiro adapter work; this PR does not close it because Kiro/custom generic ACP remains a separate adapter decision. Refs #7018 — related Kimi-specific `acpx_local` shell failure; this PR retires the built-in standalone adapter but does not add a native Kimi adapter. Refs #8864 — related ACPX prompt/API guidance PR; this PR moves runtime guidance into the shared/native ACP engine path instead of the old standalone adapter. Refs #8881 — related `acpx_local` POSIX shell failure from the old `acpx` pin; this PR updates ACP dependencies but does not claim custom/OMP ACP support as a first-class native adapter. Refs #8964 — related open `acpx_local` stderr cleanup PR; this PR makes the old runtime path obsolete for new agents but keeps it as a non-closing reference. Problem description: - The standalone `acpx_local` adapter duplicates Claude/Codex agent choices that already have first-class local adapters. - ACP should be an execution engine capability of each harness adapter when the underlying harness supports ACP. - Existing `acpx_local` agents should either migrate to native harness adapters or fail with an explicit retirement message instead of silently falling back to the process adapter. ## What Changed - Added `@paperclipai/acpx-engine` as the shared ACP execution, session-codec, CLI formatter, and UI parser package. - Wired `claude_local`, `codex_local`, and `gemini_local` to auto-select ACP by default when prerequisites pass, with `engine=cli` opt-out and `engine=acp` strict mode. - Added ACP config schema/UI fields, environment checks, session-codec preservation, transcript parsing, and adapter capability metadata for the native adapters. - Retired `acpx_local` to a server tombstone, removed its UI/package/runtime image surface, and added a migration for existing Claude/Codex ACPX agents. - Updated package manifests, lockfile, release tooling, docs, Kubernetes sandbox defaults, and tests. ## Verification - `corepack pnpm --filter @paperclipai/acpx-engine typecheck` - `corepack pnpm --filter @paperclipai/adapter-claude-local typecheck` - `corepack pnpm --filter @paperclipai/adapter-codex-local typecheck` - `corepack pnpm --filter @paperclipai/adapter-gemini-local typecheck` - `corepack pnpm --filter @paperclipai/acpx-engine exec vitest run` - `corepack pnpm --filter @paperclipai/adapter-claude-local exec vitest run src/server/acp.test.ts src/server/execute.acp-fallback.test.ts src/ui/build-config.test.ts` - `corepack pnpm --filter @paperclipai/adapter-codex-local exec vitest run src/server/acp.test.ts src/ui/build-config.test.ts` - `corepack pnpm --filter @paperclipai/adapter-gemini-local exec vitest run src/server/acp.test.ts src/ui/build-config.test.ts src/ui/parse-stdout.test.ts` - `corepack pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && corepack pnpm --filter @paperclipai/server exec tsc --noEmit` - `corepack pnpm --filter @paperclipai/server exec vitest run src/__tests__/adapter-routes.test.ts src/__tests__/adapter-session-codecs.test.ts src/__tests__/adapter-models.test.ts` - `corepack pnpm --filter @paperclipai/ui typecheck` - `corepack pnpm --filter @paperclipai/ui exec vitest run src/adapters/metadata.test.ts src/adapters/adapter-display-registry.test.ts src/components/AgentConfigForm.test.ts src/components/AgentConfigForm.render.test.tsx src/components/transcript/RunTranscriptView.test.tsx` - `node --test scripts/bootstrap-npm-package.test.mjs scripts/release-package-map.test.mjs scripts/verify-release-registry-state.test.mjs` Note: the server typecheck script calls `pnpm` internally; this dev shell exposes pnpm through Corepack only, so I ran the two script steps manually with `corepack pnpm`. ## Risks - Migration changes existing `acpx_local` Claude/Codex agents to native adapter types and clears old ACPX task sessions/runtime state. - Custom ACP commands remain on the retired tombstone and will need a separate future adapter/plugin path. - ACP auto-selection depends on local Node and ACP server command prerequisites; remote and unsupported environments fall back to CLI unless `engine=acp` is explicit. - `@paperclipai/acpx-engine` is a new public package and needs npm trusted-publishing bootstrap before release automation can publish it. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI GPT-5 via Codex coding agent. Exact hosted model build and context-window size are not exposed in this runtime. Tool use included shell execution, repository editing, GitHub CLI operations, and local test/typecheck execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>	2 个月前

Agent Runtime Image Family

Container images for running coding-agent harnesses in sandboxed environments (for example the kubernetes sandbox provider, stage 1 of the k8s contribution). Images are named agent-runtime-{harness}:{version} and published to ghcr.io/paperclipai/ by the agent-runtime-images workflow. The registry is overridable: every reference flows through the REGISTRY bake variable.

Image Lineup

agent-runtime-base: Foundation. Ubuntu 22.04 + Node 24 + git + tini + non-root user (uid 1000) + the agent shim.
agent-runtime-opencode: Extends base with opencode-ai globally installed.
agent-runtime-pi: Extends base with @mariozechner/pi-coding-agent.
agent-runtime-codex: Extends base with @openai/codex.
agent-runtime-gemini: Extends base with @google/gemini-cli plus headless auth-mode settings.
agent-runtime-claude: Extends base with @anthropic-ai/claude-code (symlinked as claude-code).
agent-runtime-hermes: Dockerfile included in the bake group, not in the default publish scope (stub until a CLI package exists).

Base Image Contents

OS & Runtime:

Ubuntu 22.04
Node.js 24 (via NodeSource APT repo)
git
tini (PID-1 init, ensures signal propagation)
Non-root user paperclip (uid/gid 1000)

The NodeSource install puts node on the default PATH. The agent shim in this image runs the harness directly with that PATH. The shim does not source a login profile, and the runtime never writes a profile or an rc file. Some sandbox providers instead wrap each command in a login shell. That shell sources /etc/profile and the user profile files to read an owner-supplied PATH. No exec path sources nvm. For the full exec-path contract, see packages/plugins/sandbox-providers/SANDBOX-REQUIREMENTS.md.

Paperclip Binaries:

/usr/local/bin/paperclip-agent-shim: Go binary compiled from tools/agent-shim/. Reads /run/paperclip/runtime-command.json and syscall.Execs the harness CLI.

Defaults:

USER: 1000:1000 (paperclip, non-root)
WORKDIR: /workspace (mount workspace volumes here)
ENTRYPOINT: /usr/bin/tini -- (PID-1 reaper, forwards signals)
CMD: /usr/local/bin/paperclip-agent-shim

Building Locally

All targets build linux/amd64 by default (see buildx-bake.hcl). Derived images chain off the base target through bake contexts, so the literal registry in each FROM line is overridden at build time and the whole family builds in one pass without pushing intermediates.

docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load

Custom tag or registry

REGISTRY=myregistry VERSION=mytag \
  docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --load

Quickstart Smoke Test

Build and verify the agent-runtime-claude image runs locally:

docker buildx bake -f docker/agent-runtime/buildx-bake.hcl base claude --load
docker run --rm ghcr.io/paperclipai/agent-runtime-claude:dev claude-code --version

Agent Container (paperclip-agent-shim)

The main agent process runs as the shim (PID 1 under tini). The shim:

Reads /run/paperclip/runtime-command.json (path overridable via -spec), a JSON file mounted by whatever schedules the run
Parses { "command", "args" }: the harness CLI and arguments
Resolves the command on PATH and syscall.Execs it, replacing itself
SIGTERM from the kubelet propagates directly to the harness (no zombie processes)

runtime-command.json Contract:

{
  "command": "claude-code",
  "args": ["--token", "xyz", "--workspace", "/workspace"]
}

The shim makes no assumptions about command structure; it is harness-agnostic. New harnesses swap the command/args; the base image stays the same.

Security Model

Non-root execution: user 1000:1000, no capability grants
PSS Restricted compatible: no privileged containers, no host mounts; works with a read-only root filesystem (writable /workspace + /tmp mounts)
No secrets baked in: API tokens and credentials come from per-run ephemeral Secrets mounted as env vars or files
Image signing: cosign keyless OIDC in the publish workflow

Publishing

.github/workflows/agent-runtime-images.yml builds and pushes the default scope (base, opencode, pi, codex, gemini, claude) on workflow_dispatch (with an explicit version tag) or on pushes to master touching these paths, then signs each digest with cosign keyless OIDC.