Files
PaperClipAI/packages/paperclip-runner/scripts/provider-pack-runtime-tree.test.mjs
T
Nicky LeachandClaude Fable 5.2 5d3fa712aa feat(docker): build and check the Runner alone as the runner-artifacts target (#21204)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Runner is the part that executes agent work: a daemon
(`paperclip-runnerd`) and a provider pack of agent tools
> - Today the application image build compiles the Runner. Other images
that need the Runner build it again, or pull the whole application image
to copy it out
> - Each of those builds can produce a slightly different Runner, and
each one costs time
> - The Runner should be built one time for each change to its inputs,
and every image should copy the same bytes
> - This pull request adds the build target `runner-artifacts`, a
contract for its layout, and a workflow that builds and checks it. It
publishes nothing
> - Nothing consumes the target in this pull request. The application
image build does not change
> - The benefit is one checked Runner build that later changes can
publish and copy by digest

## Linked Issues or Issue Description

Refs #21096 (the merge-queue image build) and #21167 (provider pack
layers). Those are earlier work on the same build. No issue exists for
this change.

**Problem or motivation**

The Runner is compiled inside the application image build. The daemon
comes from the `runner-build` stage. The provider pack is built on top
of the full server and UI build. Downstream sandbox and VM images need
the same Runner. They rebuild it from source, or they pull the
application image and copy paths out of it. There is no contract for
those paths and no single identity for a Runner build.

**Proposed solution**

Build the Runner alone, from its own inputs, as a plain file tree. Give
each build an identity: a digest of its inputs. Document the layout as a
contract, and check every built tree against it. Keep every check that
proves the Runner is good in this one build.

**Alternatives considered**

- Keep the current builds and only document the paths in the application
image. This does not remove the duplicate builds, and consumers still
need the full application image.
- Build the Runner in `docker.yml`. That workflow has no pull-request
trigger, so a change to the Runner build would have no check before it
merges.

**Roadmap alignment**

This is build infrastructure. It adds no product feature and does not
overlap an item in `ROADMAP.md`.

This is part 2 of 4. Each part is on top of the one before it:

1. `runner/pack-inputs-digest`: an optional field in the provider pack
manifest
2. `runner/runner-image-build` (#21204): build and check the Runner
image, with no publication (this pull request)
3. `runner/runner-image-layers`: layers by change rate, and the slim
variant
4. `runner/runner-image-publish`: publish both variants from `master`

This pull request had one larger form before. Publication, the image
layers and the second variant are now parts 3 and 4.

## What Changed

- `Dockerfile`: eight new stages that end in the target
`runner-artifacts` (`FROM scratch`). They install with a filtered,
frozen lockfile from a context that holds only the Runner's inputs. The
base is a Node image on Debian bookworm, pinned by digest. No existing
stage changed. `cloud` is still the default target.
- The tree holds: the stripped daemon, the Runner package's complete
`dist` with the build stamp that its own build records, the provider
pack with its transport archives, the Grok provisioning inputs, the
transport contract source and a bundled transport module, the lockfile,
and `runner-image.json`.
- `scripts/runner-image-identity.mjs`: computes the image identity. It
hashes every file under the paths that the build copies from the build
context (path, executable bit, content; symbolic links by target), the
whole `Dockerfile`, and the two platforms. The build runs it on the
files that the build context supplies after `.dockerignore`.
- `scripts/runner-image-layout.mjs`: the layout contract. `write`
assembles the tree in the build. `check` verifies a built tree: every
documented path, the build stamp, every pack artifact and tree digest in
`provider-pack.json`, and every transport archive. It also extracts the
transport archives the way a sandbox does and compares the result with
the pack. No checked path may resolve outside the tree.
- Publication form. The build argument
`PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1` is off by default. Only with it
does the pack manifest carry `payload.runnerInputsDigest` (part 1), and
`runner-image.json` records `publication: true`. Another image build
that runs the stage inline builds the same Runner, but its pack names no
image. `check` requires the field in a publication build and refuses it
in any other. `--expect-inputs-digest` passes only for a publication
build.
- `docker/runner-image/Dockerfile.smoke`: runs `paperclip-runnerd
--build-metadata` on each base image that a consumer uses. Each base is
pinned by digest.
- `.github/workflows/runner-image.yml`: two jobs, on pull requests that
touch an input and on manual dispatch. `identity` resolves the lockfile
and computes the digest in the build context. `build` builds each
architecture on a native runner, checks the layout, and runs the smoke
matrix. The workflow has `contents: read` only. It holds no credential,
reads no registry, and publishes nothing. It builds the publication
form, so the check can bind the tree to the digest that the identity job
resolved. The tree stays on the runner.
- `packages/paperclip-runner/scripts/provider-pack-runtime-tree.mjs`:
the tree digest function moves here from `build-provider-pack.mjs`
without a change in behavior, so the layout check can use it. A test
pins its value.
- `.github/workflows/pr-merge-review.yml`: lists the new workflow, as
`doc/PR-MERGE-REVIEW-WEBHOOK.md` requires.
- `doc/runner-image-contract.md` (127 lines): the contract for
consumers. `doc/DOCKER.md` links to it.

Changes from the earlier form of this pull request:

- The identity hashes the whole `Dockerfile`. The script no longer
parses stages, and it no longer refuses recipes.
`scripts/runner-image-identity.mjs` went from 397 lines to 166. A short
test keeps the three rules that make the hash enough: the Runner stages
start only from pinned images, only `runner-artifacts-context` reads the
build context, and it copies only the paths that the identity hashes.
- The contract document went from 384 lines to 127.
- The workflow tests keep only the security properties: job permissions,
no credential and no registry access, triggers, actions pinned by
commit, and no expression inside a shell script. They no longer pin step
names, order, or wording.

## Verification

Verified on `linux/arm64` only, on a local Docker host:

- `docker buildx build --target runner-artifacts --platform linux/arm64
--build-arg PAPERCLIP_RUNNER_SOURCE_REVISION=<sha> --build-arg
PAPERCLIP_RUNNER_IMAGE_PUBLICATION=1 --output type=local,dest=<tree> .`
builds in 166 seconds without a cache. The image is one layer of
850,121,093 bytes. The tree is 1,755,345,443 bytes in 9,969 files.
- `node scripts/runner-image-layout.mjs check <tree>
--expect-inputs-digest <digest> --expect-source-revision <sha>
--expect-architecture arm64` passes on the exported tree.
- `docker buildx build --file docker/runner-image/Dockerfile.smoke
--build-context runner-artifacts=<tree> docker/runner-image` passes on
all five base images.
- The digest from `--target runner-artifacts-identity` equals the digest
in the built `runner-image.json`:
`d05f51f075cb8fec687a1d27f574ba7cb41cd8ebbe9927c5cbb2cfc13b147880`.
- The same target with `PAPERCLIP_BUILD_COMMIT=<sha>` and no publication
argument builds. Its pack has `runnerSourceRevision` and no
`runnerInputsDigest`. `check` passes on it, and `check
--expect-inputs-digest` fails with "this is not a publication build".
- An edit to `ui/package.json` and to `server/src` leaves the digest
unchanged. A comment added to an application stage of the `Dockerfile`
changes it.
- The two points above ran one commit state earlier. The only difference
to this commit is one type annotation in a comment of
`scripts/runner-image-layout.mjs`.
- A named build context replaces the `runner-artifacts` stage, and no
Runner stage runs. A build with the application build's view of the
context accepts the tree's `dist` and build stamp as current
(`assessRunnerBuild`).
- The daemon has the same bytes in the five cold builds of this stack
that were compared.
- Tests: `cd server && node node_modules/vitest/vitest.mjs run` on
`runner-image-identity.test.ts`, `runner-image-layout.test.ts` and
`runner-image-workflow.test.ts` (132 tests), with
`remote-provider-pack-verification.test.ts` and the existing Dockerfile
tests: 186 tests pass. `tests/runner-e2e` workflow tests: 39 pass. `node
--test .github/scripts/tests/*.test.mjs`: 799 pass. `node --test` on the
image contract scripts and `provider-pack-runtime-tree.test.mjs`: 33
pass. `check-docker-deps-stage.mjs`, `check-node-version-policy.mjs` and
`docker buildx build --check` report nothing.

Never run:

- The `linux/amd64` build. It is the leg that downloads the Cursor and
Copilot assets for the pack.
- The workflow. No job has run on GitHub.
- The transport archive round trip with GNU tar outside the build. The
build runs it with GNU tar. The local host ran it with bsdtar.
- `actionlint` and `hadolint`. They are not installed on the local host.
- The full test suite and the full typecheck. CI must supply them.

## Risks

- Low risk to the application image. The change adds stages and files.
No existing target reaches the new stages.
- The first run of the workflow is the first test of the amd64 build.
This pull request triggers it.
- The `Dockerfile` is one file for all images. Any edit to it, also to
an application stage, changes the Runner image identity. That is the
price of not parsing it.
- The Dockerfile frontend (`# syntax=docker/dockerfile:1.20`) is a tag,
not a digest. A new frontend release under that tag does not change the
identity.
- The image does not run the drift checks of the Runner's `build`
script. They need files outside the Runner's inputs, and repository CI
runs them. A test fails when the `build` script gains a step.

> 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

- Claude Fable 5.2 (`claude-fable-5-2`), Anthropic, used through Claude
Code with tool use (shell, file edits, local Docker builds).

## 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 17:30:51 -08:00

146 lines
7.7 KiB
JavaScript

import assert from "node:assert/strict";
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, relative } from "node:path";
import test from "node:test";
import {
providerPackLibc,
removeControllerArtifactsFromProviderPack,
removeForeignLibcPackagesFromProviderPack,
removePnpmStoreEntries,
sha256Tree,
} from "./provider-pack-runtime-tree.mjs";
test("the tree digest of a pack directory keeps its recorded format", () => {
// Packs already in images carry digests computed this way, and the server
// recomputes them with its own copy of the walk. A change here must be a
// deliberate pack contract change.
const root = mkdtempSync(join(tmpdir(), "provider-pack-tree-digest-"));
try {
mkdirSync(join(root, "cli"), { recursive: true });
writeFileSync(join(root, "index.js"), "export {};\n");
writeFileSync(join(root, "cli", "proxy.cjs"), "module.exports = {};\n");
symlinkSync("index.js", join(root, "main.js"));
assert.equal(sha256Tree(root), "sha256:01f41c32adc4fae6f04481df39bb22ef6facf49424b8fb77a31d555fd7ff8878");
writeFileSync(join(root, "cli", "proxy.cjs"), "module.exports = { changed: true };\n");
assert.notEqual(sha256Tree(root), "sha256:01f41c32adc4fae6f04481df39bb22ef6facf49424b8fb77a31d555fd7ff8878");
} finally {
rmSync(root, { recursive: true, force: true });
}
});
test("image and native producer packs retain identical provider outputs despite different controller artifacts", () => {
const root = mkdtempSync(join(tmpdir(), "provider-pack-producers-"));
try {
const packs = [join(root, "image"), join(root, "native")];
for (const pack of packs) {
mkdirSync(join(pack, "dist", "cli"), { recursive: true });
writeFileSync(join(pack, "dist", "cli", "acpx-runtime-sidecar.cjs"), "identical provider bridge\n");
}
mkdirSync(join(packs[1], "dist", "bin"));
writeFileSync(join(packs[1], "dist", "bin", "paperclip-runnerd"), "host-specific daemon");
mkdirSync(join(packs[1], "dist", "remote-provider-packs"));
writeFileSync(join(packs[1], "dist", "remote-provider-packs", "prior-pack.json"), "earlier release identity");
for (const pack of packs) {
removeControllerArtifactsFromProviderPack(pack);
assert.deepEqual(readdirSync(join(pack, "dist")), ["cli"]);
assert.equal(readFileSync(join(pack, "dist", "cli", "acpx-runtime-sidecar.cjs"), "utf8"), "identical provider bridge\n");
}
} finally { rmSync(root, { recursive: true, force: true }); }
});
test("removing an owned controller-artifact link preserves its external target", () => {
const root = mkdtempSync(join(tmpdir(), "provider-pack-controller-link-"));
try {
const pack = join(root, "pack"), outside = join(root, "outside");
mkdirSync(join(pack, "dist"), { recursive: true }); mkdirSync(outside);
writeFileSync(join(outside, "preserved"), "original");
symlinkSync(outside, join(pack, "dist", "bin"));
removeControllerArtifactsFromProviderPack(pack);
assert.equal(existsSync(join(pack, "dist", "bin")), false);
assert.equal(readFileSync(join(outside, "preserved"), "utf8"), "original");
} finally { rmSync(root, { recursive: true, force: true }); }
});
function pnpmPackage(pack, entry, name, manifest = {}) {
const path = join(pack, "node_modules", ".pnpm", entry, "node_modules", name);
mkdirSync(path, { recursive: true });
writeFileSync(join(path, "package.json"), JSON.stringify({ name, version: "1.0.0", ...manifest }));
writeFileSync(join(path, "binary"), `${name}\n`);
return path;
}
function link(pack, from, entry, name) {
const path = join(pack, "node_modules", from, name);
mkdirSync(dirname(path), { recursive: true });
symlinkSync(relative(dirname(path), join(pack, "node_modules", ".pnpm", entry, "node_modules", name)), path);
return path;
}
test("detects the libc of the Node copied into Linux packs only", () => {
assert.equal(providerPackLibc("linux", () => ({ header: { glibcVersionRuntime: "2.39" } })), "glibc");
assert.equal(providerPackLibc("linux", () => ({ header: {} })), "musl");
assert.equal(providerPackLibc("darwin", () => { throw new Error("unused"); }), undefined);
});
test("removes packages built only for another libc and every link into them", () => {
const root = mkdtempSync(join(tmpdir(), "provider-pack-libc-"));
try {
const pack = join(root, "pack");
pnpmPackage(pack, "@scope+native-linux-x64@1.0.0", "@scope/native-linux-x64", { libc: ["glibc"] });
pnpmPackage(pack, "@scope+native-linux-x64-musl@1.0.0", "@scope/native-linux-x64-musl", { libc: ["musl"] });
pnpmPackage(pack, "tool-linux-x64-musl@1.0.0", "tool-linux-x64-musl", { libc: ["musl"] });
pnpmPackage(pack, "tool-linux-x64@1.0.0", "tool-linux-x64");
pnpmPackage(pack, "consumer@1.0.0", "consumer", { optionalDependencies: { "tool-linux-x64": "1.0.0", "tool-linux-x64-musl": "1.0.0" } });
const kept = [
link(pack, ".pnpm/consumer@1.0.0/node_modules", "tool-linux-x64@1.0.0", "tool-linux-x64"),
link(pack, ".pnpm/node_modules", "@scope+native-linux-x64@1.0.0", "@scope/native-linux-x64"),
];
const pruned = [
link(pack, ".pnpm/consumer@1.0.0/node_modules", "tool-linux-x64-musl@1.0.0", "tool-linux-x64-musl"),
link(pack, ".pnpm/node_modules", "@scope+native-linux-x64-musl@1.0.0", "@scope/native-linux-x64-musl"),
link(pack, "", "@scope+native-linux-x64-musl@1.0.0", "@scope/native-linux-x64-musl"),
];
assert.deepEqual(removeForeignLibcPackagesFromProviderPack(pack, "glibc"), [
"@scope+native-linux-x64-musl@1.0.0", "tool-linux-x64-musl@1.0.0",
]);
assert.deepEqual(readdirSync(join(pack, "node_modules", ".pnpm")).sort(), [
"@scope+native-linux-x64@1.0.0", "consumer@1.0.0", "node_modules", "tool-linux-x64@1.0.0",
]);
for (const path of kept) assert.equal(existsSync(join(path, "package.json")), true);
for (const path of pruned) assert.equal(lstatExists(path), false);
// The emptied top-level scope goes too; the shared hoisted scope keeps its glibc link.
assert.equal(existsSync(join(pack, "node_modules", "@scope")), false);
assert.deepEqual(readdirSync(join(pack, "node_modules", ".pnpm", "node_modules", "@scope")), ["native-linux-x64"]);
} finally { rmSync(root, { recursive: true, force: true }); }
});
test("keeps every package when the pack has no libc or the libc matches", () => {
const root = mkdtempSync(join(tmpdir(), "provider-pack-libc-noop-"));
try {
const pack = join(root, "pack");
pnpmPackage(pack, "tool-linux-x64-musl@1.0.0", "tool-linux-x64-musl", { libc: ["musl"] });
assert.deepEqual(removeForeignLibcPackagesFromProviderPack(pack, undefined), []);
assert.deepEqual(removeForeignLibcPackagesFromProviderPack(pack, "musl"), []);
assert.equal(existsSync(join(pack, "node_modules", ".pnpm", "tool-linux-x64-musl@1.0.0")), true);
} finally { rmSync(root, { recursive: true, force: true }); }
});
test("refuses store entry names that escape the pnpm virtual store", () => {
const root = mkdtempSync(join(tmpdir(), "provider-pack-store-escape-"));
try {
const pack = join(root, "pack");
mkdirSync(join(pack, "node_modules", ".pnpm", "node_modules"), { recursive: true });
writeFileSync(join(pack, "node_modules", "outside"), "kept");
for (const name of ["../outside", "node_modules", "a/b"]) {
assert.throws(() => removePnpmStoreEntries(pack, [name]), /Refusing to remove/);
}
assert.equal(readFileSync(join(pack, "node_modules", "outside"), "utf8"), "kept");
} finally { rmSync(root, { recursive: true, force: true }); }
});
function lstatExists(path) {
try { lstatSync(path); return true; } catch { return false; }
}