From 2dcfdabc7926f4e5b3718d1272b4ed07a1e167c0 Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Thu, 12 Nov 2026 16:58:14 -0800 Subject: [PATCH] feat(runner): let a provider pack record the Runner image it was built in (#21228) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 > - A provider pack has a manifest, `provider-pack.json`. It records the commit the pack was built from as `payload.runnerSourceRevision` > - The next pull requests build the Runner alone as an image that has an identity of its own: a digest of the Runner's inputs > - A pack from that image must be able to say which image it came from. The commit does not say that, because many commits have the same inputs > - This pull request adds one optional field to the pack manifest for that digest > - The benefit is that a reader of a pack can find the exact image that built it. Packs that are built today do not change ## Linked Issues or Issue Description Refs #21204 (the Runner image, part 2 of this stack). No issue exists for this change. **Problem or motivation** The provider pack manifest records a source revision. It has no place for the identity of a Runner image. The Runner image in #21204 is named by a digest of its inputs, and one image serves every commit that has those inputs. Without a field in the manifest, a pack cannot name the image that built it. **Proposed solution** Add the optional field `payload.runnerInputsDigest`. The pack builder writes it only when the environment variable `PAPERCLIP_RUNNER_INPUTS_DIGEST` is set. The value must be 64 lowercase hexadecimal characters. The pack builder fails for another value. Nothing sets the variable in this pull request. **Alternatives considered** - Put the digest in a file beside the pack. Then the pack digest does not cover it, and a copy of the pack loses it. - Reuse `runnerSourceRevision`. That field is a commit, and code compares it with other commits. **Roadmap alignment** This is build infrastructure. It adds no product feature and does not overlap an item in `ROADMAP.md`. This is part 1 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 (this pull request) 2. `runner/runner-image-build` (#21204): build and check the Runner image, with no publication 3. `runner/runner-image-layers`: layers by change rate, and the slim variant 4. `runner/runner-image-publish`: publish both variants from `master` ## What Changed - `packages/paperclip-runner/scripts/build-provider-pack.mjs`: reads `PAPERCLIP_RUNNER_INPUTS_DIGEST`. When it is set, the script checks its form and writes `payload.runnerInputsDigest` after `runnerSourceRevision`. When it is not set, the manifest is the same as before, byte for byte. - `server/src/services/native-runtime/remote-provider-pack-verification.ts`: the manifest type has the optional field `runnerInputsDigest`. No check reads it. - `server/src/services/native-runtime/remote-provider-pack-verification.test.ts`: one test. A sealed manifest with the field passes verification. A manifest whose field was changed after it was sealed fails, because the pack digest covers the field. The change is 20 added lines in 3 files. ## Verification - `cd server && node node_modules/vitest/vitest.mjs run src/services/native-runtime/remote-provider-pack-verification.test.ts`: 19 tests pass. - Part 2 builds a pack with the variable set and a pack without it, on `linux/arm64`. The first has the field and the second does not. Never run: - The full test suite and the full typecheck. CI must supply them. ## Risks - Low risk. The field is optional and additive, and nothing sets the variable yet. - The pack digest covers the payload. A pack that has the field therefore has another digest than the same pack without it. No pack has the field until part 2 builds one. > 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 - [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 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.2 --- .../paperclip-runner/scripts/build-provider-pack.mjs | 8 ++++++++ .../remote-provider-pack-verification.test.ts | 10 ++++++++++ .../remote-provider-pack-verification.ts | 2 ++ 3 files changed, 20 insertions(+) diff --git a/packages/paperclip-runner/scripts/build-provider-pack.mjs b/packages/paperclip-runner/scripts/build-provider-pack.mjs index 54e10b7f173..7d9ed8ae768 100644 --- a/packages/paperclip-runner/scripts/build-provider-pack.mjs +++ b/packages/paperclip-runner/scripts/build-provider-pack.mjs @@ -314,6 +314,13 @@ try { : spawnSync("git", ["diff", "--quiet", "--", "packages/paperclip-runner"], { cwd: workspaceRoot, }).status !== 0; + // Set only by the Runner image build (the `runner-artifacts` Dockerfile + // target): the identity of the inputs the image was built from, which is its + // `inputs-` tag. No check reads it. + const runnerInputsDigest = process.env.PAPERCLIP_RUNNER_INPUTS_DIGEST?.trim(); + if (runnerInputsDigest && !/^[0-9a-f]{64}$/.test(runnerInputsDigest)) { + throw new Error("PAPERCLIP_RUNNER_INPUTS_DIGEST must be 64 hexadecimal characters"); + } const payload = { compatibility, // Semantic digest of the Runner/pack contracts. Image packs are reused only @@ -330,6 +337,7 @@ try { }, target: { platform: process.platform, architecture: process.arch }, runnerSourceRevision: `${revision}${dirty ? "-dirty" : ""}`, + ...(runnerInputsDigest ? { runnerInputsDigest } : {}), distDigest, bridgeDigest: `sha256:${createHash("sha256") .update(opencodeProxySha) diff --git a/server/src/services/native-runtime/remote-provider-pack-verification.test.ts b/server/src/services/native-runtime/remote-provider-pack-verification.test.ts index 6321ebd22c7..3c4255a4dc5 100644 --- a/server/src/services/native-runtime/remote-provider-pack-verification.test.ts +++ b/server/src/services/native-runtime/remote-provider-pack-verification.test.ts @@ -114,6 +114,16 @@ describe("installed provider pack compatibility", () => { pack.payload.acpxProfileDigests = { codex: sha("different-codex") }; await expect(check(reseal(pack))).resolves.toEqual(reseal(pack)); }); + it("treats the Runner image inputs digest as provenance", async () => { + // A pack built in the Runner image records which image it came from. The + // controller's own pack may record another image, or none. + const pack = manifest("a"); + pack.payload.runnerInputsDigest = "c".repeat(64); + await expect(check(reseal(pack))).resolves.toEqual(reseal(pack)); + // The field is part of the sealed payload, so it cannot change unnoticed. + await expect(check({ ...reseal(pack), payload: { ...pack.payload, runnerInputsDigest: "d".repeat(64) } })) + .rejects.toThrow("runner_remote_provider_artifact_incompatible"); + }); it("checks only the selected ACPX profile", async () => { const current = manifest("b"), installed = manifest("a"); current.payload.acpxProfileDigests = { claude: sha("claude"), codex: sha("codex") }; diff --git a/server/src/services/native-runtime/remote-provider-pack-verification.ts b/server/src/services/native-runtime/remote-provider-pack-verification.ts index 9759ca9a52e..5d48ea89146 100644 --- a/server/src/services/native-runtime/remote-provider-pack-verification.ts +++ b/server/src/services/native-runtime/remote-provider-pack-verification.ts @@ -22,6 +22,8 @@ export type ProviderPackIdentity = { pins: { opencode: string; [key: string]: string | null }; target: { platform: string; architecture: string }; runnerSourceRevision: string; + /** Identity of the Runner image the pack was built in, when it was built there. Provenance only. */ + runnerInputsDigest?: string; artifacts: { nodeCommand: { path: string; sha256: string }; opencodeCommand: { path: string; sha256: string }; [key: string]: { path: string; sha256: string } }; }; };