mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-13 13:38:01 +02:00
7df517d18f
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Its CI runs a `Build` job on every pull request. That job runs `pnpm build` and then verifies the public npm install. Since the server test shards got faster, `Build` is the slowest check in most runs (419-497s on the six fully green `master` runs created 2026-10-11 19:46Z to 20:17Z). > - Inside `pnpm build`, the server package is the last package to build. Its first step, `prepare:runner-vendor`, runs the full build of `@paperclipai/paperclip-runner` so the server can vendor `packages/paperclip-runner/dist`. In `pnpm -r build` that package was built seconds earlier by the same command. The second build took 12-16s on those six runs and sits on the critical path of the job. > - The step cannot just be removed. A standalone `pnpm --filter @paperclipai/server build` (the Dockerfile's path) must produce a current vendored Runner on its own. > - This pull request keeps that guarantee and skips only the build that is provably redundant. The Runner's `build` records a digest of its inputs, captured before its first step and confirmed after its last, together with a manifest of every file it left under `dist`. The server's `prepare:runner-vendor` reuses the build when the digest matches, the stamp is for this platform, and every recorded output is still there at its recorded size. Any other state runs the same full Runner build as before. > - The benefit is 12-16s off the `Build` job and off every other `pnpm build` (the Canary Dry Run's `release.sh` build, local builds), with no change to what a standalone server build produces. The PR's own first run measured it: the server step reused the build in 56ms where `master` runs rebuilt for 11-15s. ## Linked Issues or Issue Description No GitHub issue exists for this. The description below follows the enhancement template. **What existing behavior does this improve?** The server build's `prepare:runner-vendor` step, which builds `@paperclipai/paperclip-runner` so the server can vendor its `dist`. **Subsystem affected** Build and CI (`server/package.json`, `packages/paperclip-runner/package.json`, the `Build` job). **Current behavior** `prepare:runner-vendor` runs the Runner's full `build` every time. Inside `pnpm -r build`, the Runner was already built by the same command 20 to 25 seconds earlier, with every check passing. On six fully green `master` runs (2026-10-11, 19:46Z to 20:17Z) the repeated build took 11.8s to 15.9s, measured from the `server build$ pnpm run prepare:runner-vendor` log line to the Runner's `Finished release profile` line. The server package builds last, so that time is on the critical path of `Build`, which is the slowest check in most pull request runs. **Proposed behavior** - The Runner's `build` starts with `node scripts/record-build-inputs.mjs --begin` and ends with `node scripts/record-build-inputs.mjs --finish`. `--begin` removes the previous stamp and records a digest of every build input before the first step reads anything. `--finish`, after every step and check has passed, recomputes the digest and writes `packages/paperclip-runner/node_modules/.cache/paperclip-runner-build-inputs.json` only if the inputs are still the ones the build began with, together with the path and size of every file under `dist`. A stamp therefore exists only for a build that completed every step on inputs that did not move while it ran. - The server's `prepare:runner-vendor` becomes `node scripts/prepare-runner-vendor.mjs`. It reuses the build if the stamp is for this platform and architecture, every recorded output is still there at its recorded size, and the recomputed digest matches. In every other case it removes the stamp and runs `pnpm --filter @paperclipai/paperclip-runner build`, the exact command the step ran before. - `PAPERCLIP_RUNNER_VENDOR_REBUILD=1` forces the rebuild. **Reason and benefit** 12-16s off the `Build` job and off every other `pnpm build` (the Canary Dry Run's `release.sh` build, local builds), with no change to what a standalone `pnpm --filter @paperclipai/server build` produces. **Breaking changes** None. The rebuild path runs the same command as before. A fresh checkout, a changed input, a missing or truncated output, an edit that landed during the build, or a stamp from another platform always rebuilds. ## What Changed - `packages/paperclip-runner/scripts/build-inputs.mjs` (new): defines the input set, the digest, the output manifest and the reuse decision. Inputs are every file under `packages/paperclip-runner` except `dist`, `dist-browser`, `runner/target`, `node_modules` and dot-directories; every file under `packages/paperclip-eval-kernel` except `dist` and `node_modules` (the Runner's `build:typescript` builds it first); every file under the root `patches` directory (`check:acpx-profiles` hashes `acpx@0.13.1.patch`, and `build-verified-provider-entrypoints.mjs` copies the `pi-acp` and `brace-expansion` patches into `dist/cli/pi-provision-inputs`); and the root `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml` and `tsconfig.base.json`. The toolchain pins are inside the package (`rust-toolchain.toml`, `runner/Cargo.lock`) and the TypeScript version is in the lockfile, so both are covered. A symlink is hashed as its target path and is not followed. Outputs are every file under `dist`, the tree the server copies wholesale, recorded with their sizes. Exports `beginRunnerBuild`, `recordRunnerBuild` and `assessRunnerBuild` (returns `current` plus a stable reason code: `no_stamp`, `schema_mismatch`, `platform_mismatch`, `missing_output`, `outputs_changed`, `inputs_changed`, `inputs_unchanged`). - `packages/paperclip-runner/scripts/record-build-inputs.mjs` (new): the two phases, `--begin` and `--finish`, added as the first and last step of the Runner's `build` in `packages/paperclip-runner/package.json`. Each build chain has its own pending record under `node_modules/.cache/paperclip-runner-build-inputs.pending/`, named after the shell pnpm runs the chain in (the parent of both phases; `--finish` also accepts a record named after its own pid, for a shell that execs the last command of the chain), so two Runner builds running at once in one checkout do not consume each other's record. `--finish` without a pending record for its chain is an error, so the chain cannot silently lose its first step; `--finish` after an edit that landed mid-build prints `not recorded: inputs changed while the build ran` and leaves no stamp. Records of builds that never finished are pruned by the next `--begin` after a day. - `server/scripts/prepare-runner-vendor.mjs` (new): the reuse-or-rebuild step. It resolves the pnpm that is running it through `npm_execpath` with the same rule as the CLI's `resolvePnpmInstallInvocation` (a JavaScript entry runs through this Node, a native executable runs directly, otherwise `pnpm` on PATH). It prints one `paperclip.runner-vendor.timing.v1` line with `action`, `reason`, `check_ms` and `build_ms`, so the saving is measured on this PR's own `Build` job. - `server/package.json`: `prepare:runner-vendor` now runs that script. The `build` and `typecheck` scripts are unchanged. - `server/src/__tests__/server-package-build-script.test.ts`: pins the new indirection and the command behind it (imported from the script, so the Dockerfile's standalone path stays pinned), and a new test asserts the Runner's `build` starts with `--begin`, ends with `--finish`, and has exactly those two record steps. - Tests: `packages/paperclip-runner/scripts/build-inputs.test.mjs` (node:test, added to `test:typescript:prep`) and `server/scripts/prepare-runner-vendor.test.mjs` (vitest, in the server lane). - `doc/DEVELOPING.md`: a "Reused Runner build in the server build" section under Test Commands. ## Review findings on the first head, all fixed in [2d57542](https://github.com/paperclipai/paperclip/pull/15926/commits/2d575425977f87b4612222d0a1961bc9cc5ba569) Greptile scored the first head 2/5 with three P1 findings. All three were valid. | Finding | Fix | | --- | --- | | **Patch edits leave stale output.** The root patch files the build reads were not in the digest. | Every file under the root `patches` directory is an input. Tests assert the patches are in the input list and that editing the pi-acp patch, the acpx patch, or adding a patch changes the digest. | | **Missing helpers pass the build.** Only four outputs were checked, so a `dist` that lost `dist/cli/acpx-runtime-sidecar.cjs` still counted as current. | `--finish` records the path and size of every file under `dist`; reuse requires all of them intact and reports `outputs_changed` naming the first missing or resized file. Schema bumped to `paperclip.runner-build-inputs.v2` so an older stamp is rejected. Tests cover a deleted helper, a truncated helper, and the server step rebuilding on `outputs_changed`. | | **New edits count as compiled.** The digest was hashed after the build, so a source edited while `build:binary` ran was recorded as compiled. | The build is bracketed: `--begin` captures the digest before the first step, `--finish` compares after the last and writes nothing if it moved. Tests cover the mid-build edit, the undisturbed build, and the CLI in both orders. | ## Review finding on the second head, fixed in the third commit Greptile scored the second head 4/5 with one P1, valid: two Runner builds running at once in one checkout (server `build` beside `typecheck`) shared one pending record, so the second `--begin` overwrote it, the first `--finish` consumed it, and the second `--finish` threw `no pending build inputs` after every step of its build had passed. Reproduced on the second head's module: two `beginRunnerBuild`, then the first `recordRunnerBuild` records and the second throws. | Finding | Fix | | --- | --- | | **Overlapping builds fail each other.** One pending file for every build chain. | One record per chain, named after the shell pnpm runs the chain in: `--begin` sees it as its parent, and so does `--finish`, unless the shell execs the last command of the chain (bash can), in which case `--finish` is that shell and finds the record under its own pid. Pending records of builds that never finished are pruned after a day. An edit between two overlapping starts leaves no stamp whichever build finishes last: the build that began before the edit reports `inputs_changed_during_build` and removes the stamp the other wrote, so a stamp always means every build that wrote `dist` read the inputs it names. Tests: both finishing orders with and without an edit, the pruning, a `--finish` that cannot use another chain's record, and two real `sh -c` chains (plus one under `bash`) held open at the same time, both recording. On the real repo, two `pnpm --filter @paperclipai/paperclip-runner build` chains started 8s apart with a cargo stand-in both recorded (`files=1223 outputs=1434`) and left the pending directory empty. | ## Measured on this PR's runs The `Build` job ran `pnpm build` from the branch, so both builds of the Runner in that job used the new chain. First head (c23faab, run 38175281058), against the four fully green `master` runs created 20:41Z to 21:37Z the same evening: | | PR run 38175281058 | `master`, four runs | | --- | --- | --- | | Runner build inside `pnpm -r build` | 55.3s | 47.3-62.0s | | Server step `prepare:runner-vendor` | `action:reuse,reason:inputs_unchanged,check_ms:56,build_ms:0` | full Runner rebuild, 11.0-14.8s | | Server package build | 29.7s | 32.3-43.5s | | `pnpm build` step | 114s | 102-135s | | `Build` job | 411s | 409-474s | Second head (2d57542, run 38178686999), against the two fully green `master` runs created in the same half hour (38178951607 and 38180574768): | | PR run 38178686999 | `master`, two runs | | --- | --- | --- | | Runner build inside `pnpm -r build` | 53.9s (`begin:` 22:03:04, `recorded:` 22:03:57, digest 460e02616081 over 1231 files and 1434 outputs) | 62.2s, 64.6s | | Server step `prepare:runner-vendor` | `action:reuse,reason:inputs_unchanged,check_ms:109,build_ms:0` | full Runner rebuild, 14.5s, 15.2s | | Server package build | 27.4s | 43.5s, 44.8s | | `pnpm build` step | 106s | 91s, 95s to the Runner's end plus the rest; 127s, 135s in all | | `Build` job | 405s | 461s, 479s | The rebuild is gone from the server build on both heads, and the check costs 56-109ms where `master` rebuilds for 11-15s; the rest of the spread between runs is runner speed on the `runs-on` fleet. The third commit changes nothing on the reuse path: it only changes where the pending record lives between `--begin` and `--finish`. ## Verification - `node --test packages/paperclip-runner/scripts/build-inputs.test.mjs`: 11 tests, three consecutive runs clean. Two builds at once in one checkout each keep their own pending record and both record, in either finishing order; with an edit between their starts the build that began before it leaves no stamp whichever finishes last. A build's start prunes records older than a day and no others. A `--finish` cannot use another chain's record. Two chains run by separate `sh -c` shells at the same time (and one under `bash`) both record and leave the pending directory empty. The input set is exactly the sources, the eval kernel, the root patches and the root config, and skips outputs and caches. The output manifest lists every file under `dist` with its size and nothing outside it. The digest is stable across reads, does not change when `dist`, `dist-browser`, `node_modules`, `.vite` or `runner/target` change, and does change for a Runner source, a Rust source, an eval-kernel source, the pi-acp patch, the acpx patch, a new patch, the lockfile, the base tsconfig, a new file and a rename. A symlink changes the digest but its target's files are not read. A build is current only with a matching v2 stamp, the same platform and architecture, the four named outputs present, and every recorded output intact (a deleted or truncated helper is `outputs_changed`; a file the build did not produce may appear). An input edited between `--begin` and `--finish` leaves no stamp and removes the pending record; the next build records normally. `--finish` without `--begin`, or after a build that left a required output missing, throws and leaves no stamp. The CLI brackets the build for the package it is pointed at, reports a mid-build edit, and rejects `--finish` first, both flags, neither flag, and unknown arguments. - `vitest run scripts/prepare-runner-vendor.test.mjs src/__tests__/server-package-build-script.test.ts` in `server/`: 21 tests. The decision reuses a current build, rebuilds a stale one, and rebuilds a current one only when `PAPERCLIP_RUNNER_VENDOR_REBUILD=1`. The pnpm resolver covers a JavaScript entry, a native executable, a Windows executable, no `npm_execpath`, and npm's `npm_execpath`. With an injected build command: a current stamp runs nothing and prints `action:reuse`; changed inputs run the exact command from `server/` with the stale stamp already removed; a lost `dist/cli/acpx-runtime-sidecar.cjs` rebuilds with `reason:outputs_changed`; a failing build returns its status and leaves no stamp. End to end, the CLI with a stand-in `pnpm` on PATH that brackets its build the way the real one does rebuilds on the first call, reuses on the second, rebuilds after a source change, rebuilds after a lost output, and reuses again. The guard test asserts `prepare:runner-vendor` is the new script, the rebuild command is still `pnpm --filter @paperclipai/paperclip-runner build`, the server build still starts with the step, and the Runner's `build` starts with `--begin` and ends with `--finish` with exactly two record steps; it fails against the previous build script on its first assertion. - Real repo, this checkout, with `cargo` and `pnpm` stand-ins on PATH (no Rust toolchain here; the stand-in writes the one file `stage-runner-binary.mjs` copies): `pnpm --filter @paperclipai/paperclip-runner build` ran the complete chain through the real nested pnpm (every TypeScript step and check, the stand-in cargo, the binary staging, the two binary-reading checks) and recorded `files=1223 bytes=18735059 outputs=1434`; the stamp is 128 KB. `pnpm run prepare:runner-vendor` in `server/` then printed `action:reuse,reason:inputs_unchanged,check_ms:222,build_ms:0`. Appending a newline to `patches/pi-acp@0.0.33.patch` made the assessment `inputs_changed`; truncating or deleting `dist/cli/acpx-runtime-sidecar.cjs` or `dist/cli/opencode-app-server-proxy.cjs` made it `outputs_changed` in 1-5ms; restoring each made it current again. `--begin`, an edit to `src/index.ts`, then `--finish` printed `not recorded: inputs changed while the build ran` and left no stamp. - The whole check on the real set (1223 inputs, 18 MB; 1434 outputs) takes 165-227ms on this host and took 56ms on the CI runner; the output manifest part is 1-5ms. - Not run here: the real `cargo build`, and `pnpm build` end to end. This PR's `Build` job runs `pnpm build` from the branch, so its log carries the Runner's `begin:` and `recorded:` lines and the server build's `paperclip.runner-vendor.timing.v1` line with the measured result. ## Risks - A build input outside the digest would let a stale Runner be vendored. The digest covers the whole Runner package except its outputs, the eval kernel the Runner builds first, the root patches, and the root files the Runner's tsconfig and dependency graph read. The lockfile covers dependency versions, and the pins inside the package cover the Rust toolchain. An input missed here is a bug to fix by adding it to the set; the fallback direction is always a rebuild, never a skip. - The whole `patches` directory is an input, although the Runner build reads three of its fourteen files. An edit to an unrelated patch therefore costs one extra Runner rebuild, which is the safe direction and avoids a hand-kept list of file names that could drift from the scripts that read them. - The stamp lives in `node_modules/.cache`, which pnpm does not manage and `.gitignore` and `.dockerignore` already exclude. It is about 128 KB with the output manifest. The Docker build has no stamp and no prior Runner build, so it rebuilds exactly as before. - A stamp is written only after the Runner's `build` passed every step on inputs that did not change while it ran. The Runner's first step and the prepare step both remove any existing stamp before a rebuild starts, so a build that stops partway, or a build command that fails before its first step, leaves no stamp. - `node scripts/record-build-inputs.mjs --finish` on its own is an error; the script is only meant to run as the two ends of the `build` chain, and the guard test pins that. - The pending record is keyed by the pid of the shell that runs the chain. pnpm runs every script through a shell (`sh -c` on POSIX, `cmd` on Windows), and both phases are children of that shell; a shell that execs the last command of the chain is covered by matching the finishing process's own pid too. A chain run some other way, with the two phases under different parents, fails loudly at `--finish` rather than recording. Two builds running at once still write the same `dist`, which no stamp can make safe; what the record guarantees is that a stamp is written only by a build whose own inputs did not move. - The platform and architecture are part of the comparison, so a stamp from another machine is never trusted; an older v1 stamp is rejected by schema. - The Typecheck job builds the Runner once, through this step, with no prior `pnpm -r build`, so it gains nothing and loses nothing: there is no stamp and it rebuilds as before. - The step now spawns pnpm through `npm_execpath` instead of relying on `pnpm` being on PATH, because under corepack the script shell has no `pnpm`. Outside a pnpm script it still falls back to `pnpm` on PATH. ## Model Used - Claude (Anthropic), model id `claude-fable-5-1` (Claude Fable 5.1), extended thinking, with tool use (shell, file editing, GitHub CLI) in a Paperclip agent session. ## 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 - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>