From 8610e7934e50a0d7e2a8d0cc55692687427b2d48 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Mon, 31 Aug 2026 08:08:27 -0500 Subject: [PATCH] fix(release): bundle vendored runner ACPX runtime (#12582) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app that people use to manage AI agents for work. > - The npm release includes the Paperclip server and a vendored runner. > - The vendored runner imports ACPX when it starts a Codex agent. > - The server package did not include the ACPX version that the runner needs. > - A fresh canary install therefore stopped with `ERR_MODULE_NOT_FOUND` after onboarding. > - This pull request bundles the patched ACPX runtime with the server package. > - The benefit is that a fresh npm install can load the vendored runner. ## Linked Issues or Issue Description No public issue exists for this bug. A GitHub search found no duplicate or related pull request. **What happened?** A fresh `npx paperclipai@canary onboard` command completed onboarding. The server then failed to start. Node could not resolve `acpx` from the vendored Paperclip runner. **Expected behavior** The server should start after onboarding from a fresh npm cache and a temporary data directory. **Steps to reproduce** 1. Run `npx paperclipai@canary onboard --data-dir "$(mktemp -d /tmp/paperclip-canary.XXXXXX)"`. 2. Select Quickstart. 3. Start Paperclip. 4. Observe `ERR_MODULE_NOT_FOUND` for `acpx`. **Paperclip version or commit** `paperclipai@2026.831.0-canary.6` **Deployment mode** Other: local trusted Quickstart through `npx`. **Installation method** npm through `npx`. **Agent adapter(s) involved** Codex. **Database mode** Embedded PGlite. **Access context** Board operator during onboarding. **Node.js version** Node.js 26.4.0. **Operating system** macOS. **Relevant logs or output** ```shell Cannot find package 'acpx' imported from .../node_modules/@paperclipai/server/dist/vendor/paperclip-runner/drivers/acpx/codex-runtime-adapter.js ``` **Relevant config (if applicable)** No custom configuration was required. **Additional context** The published adapter utilities contain a nested `acpx@0.12.0`. Node cannot resolve that nested package from the sibling vendored runner. Installing `acpx@0.13.1` at the clean package root makes the failing runner import succeed. **Privacy checklist** The log excerpt contains no user path, token, company name, or other private value. ## What Changed - Added `acpx@0.13.1` as a bundled server runtime dependency. - Added a version-specific patch check for the ACPX versions used by the server and adapter utilities. - Added release-package coverage for the server ACPX bundle. ## Verification - `pnpm test:release-registry` passed 98 tests. - `node --test scripts/acpx-patch-packaging.test.mjs` passed 12 tests. - `pnpm exec vitest run server/src/__tests__/server-package-build-script.test.ts` passed 4 tests. - `node --test scripts/release-package-map.test.mjs` passed 12 tests. - `pnpm -r typecheck` passed. - A clean extracted server tarball contained the patched `acpx@0.13.1` runtime. - The previously failing vendored runner module imported from that clean tarball. - The repository-wide test suite was stopped before completion at the maintainer's request because it takes too long for this urgent packaging fix. ## Risks - Risk is low. - The server tarball grows because it now contains ACPX and its production dependencies. - The release stager now uses a version-specific marker to verify the ACPX patch. > 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 with `gpt-5.6-sol`. - The model used reasoning mode, tool use, and code execution. - The context window size was not disclosed. ## 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 Co-authored-by: Paperclip --- scripts/acpx-patch-packaging.test.mjs | 29 ++++++++++++++++++++------- scripts/prepare-bundled-package.mjs | 24 +++++++++++++++------- server/package.json | 4 ++++ 3 files changed, 43 insertions(+), 14 deletions(-) diff --git a/scripts/acpx-patch-packaging.test.mjs b/scripts/acpx-patch-packaging.test.mjs index beea369944..b37155b9ef 100644 --- a/scripts/acpx-patch-packaging.test.mjs +++ b/scripts/acpx-patch-packaging.test.mjs @@ -26,6 +26,9 @@ const rootPackage = JSON.parse(await readFile(new URL("../package.json", import. const adapterUtilsPackage = JSON.parse( await readFile(new URL("../packages/adapter-utils/package.json", import.meta.url), "utf8"), ); +const serverPackage = JSON.parse( + await readFile(new URL("../server/package.json", import.meta.url), "utf8"), +); const dbPackage = JSON.parse( await readFile(new URL("../packages/db/package.json", import.meta.url), "utf8"), ); @@ -38,8 +41,14 @@ test("published packages preserve the patched ACPX runtime", () => { rootPackage.pnpm.patchedDependencies["acpx@0.12.0"], "patches/acpx@0.12.0.patch", ); + assert.equal( + rootPackage.pnpm.patchedDependencies["acpx@0.13.1"], + "patches/acpx@0.13.1.patch", + ); assert.equal(adapterUtilsPackage.dependencies.acpx, "0.12.0"); assert.deepEqual(adapterUtilsPackage.bundleDependencies, ["acpx"]); + assert.equal(serverPackage.dependencies.acpx, "0.13.1"); + assert.deepEqual(serverPackage.bundleDependencies, ["acpx"]); assert.equal(bundledCliNpmDependencies.has("acpx"), true); assert.equal(cliEsbuildConfig.external.includes("acpx"), false); }); @@ -181,7 +190,7 @@ test("bundled package patch selection rejects an unpatched installed version", ( ); }); -test("bundled package staging rebuilds npm dependencies and applies the acpx patch", (t) => { +test("server package staging bundles and patches the vendored runner's acpx runtime", (t) => { const fixtureDir = mkdtempSync(join(tmpdir(), "paperclip-bundled-stage-")); const sourceDir = join(fixtureDir, "source"); const destinationDir = join(fixtureDir, "destination"); @@ -192,7 +201,10 @@ test("bundled package staging rebuilds npm dependencies and applies the acpx pat writeFileSync(join(sourceDir, "dist", "index.js"), "export {};\n"); mkdirSync(destinationDir); mkdirSync(binDir); - writeFileSync(join(sourceDir, "package.json"), JSON.stringify(adapterUtilsPackage)); + writeFileSync( + join(sourceDir, "package.json"), + JSON.stringify({ ...serverPackage, files: ["dist"] }), + ); writeFileSync(callLog, ""); t.after(() => rmSync(fixtureDir, { recursive: true, force: true })); @@ -217,7 +229,7 @@ printf 'npm %s\\n' "$*" >> "$FAKE_CALL_LOG" [ "$*" = "install --omit=dev --ignore-scripts --no-audit --no-fund" ] mkdir -p node_modules/acpx/dist printf 'unpatched runtime\\n' > node_modules/acpx/dist/runtime.js -printf '{"name":"acpx","version":"0.12.0"}\\n' > node_modules/acpx/package.json +printf '{"name":"acpx","version":"0.13.1"}\\n' > node_modules/acpx/package.json `, ); writeExecutable( @@ -235,9 +247,9 @@ while [ "$#" -gt 0 ]; do fi done patch_input="$(cat)" -grep -q onAgentStderr <<< "$patch_input" -! grep -q spawnEnvironment <<< "$patch_input" -printf 'patched onAgentStderr runtime\\n' > "$target/dist/runtime.js" +grep -q spawnEnvironment <<< "$patch_input" +! grep -q onAgentStderr <<< "$patch_input" +printf 'patched spawnEnvironment runtime\\n' > "$target/dist/runtime.js" `, ); @@ -259,7 +271,10 @@ printf 'patched onAgentStderr runtime\\n' > "$target/dist/runtime.js" assert.equal(lstatSync(stagedAcpxDir).isDirectory(), true); assert.equal(lstatSync(stagedAcpxDir).isSymbolicLink(), false); assert.equal(existsSync(join(destinationDir, "node_modules/.pnpm")), false); - assert.match(readFileSync(join(stagedAcpxDir, "dist/runtime.js"), "utf8"), /onAgentStderr/); + assert.match( + readFileSync(join(stagedAcpxDir, "dist/runtime.js"), "utf8"), + /spawnEnvironment/, + ); assert.match( readFileSync(callLog, "utf8"), /patch -p1 --forward -d .*node_modules\/acpx/, diff --git a/scripts/prepare-bundled-package.mjs b/scripts/prepare-bundled-package.mjs index 84cef8d001..db5ad596ca 100644 --- a/scripts/prepare-bundled-package.mjs +++ b/scripts/prepare-bundled-package.mjs @@ -166,13 +166,23 @@ export function prepareBundledPackage(sourceDir, destinationDir) { writeFileSync(deployedPackagePath, `${JSON.stringify(publishManifest, null, 2)}\n`); applyBundledDependencyPatches(destinationDir, bundledDependencies); - if ( - bundledDependencies.includes("acpx") && - !readFileSync(resolve(destinationDir, "node_modules/acpx/dist/runtime.js"), "utf8").includes( - "onAgentStderr", - ) - ) { - throw new Error("staged acpx runtime is missing the repository patch"); + if (bundledDependencies.includes("acpx")) { + const acpxPackage = JSON.parse( + readFileSync(resolve(destinationDir, "node_modules/acpx/package.json"), "utf8"), + ); + const expectedPatchMarker = { + "0.12.0": "onAgentStderr", + "0.13.1": "spawnEnvironment", + }[acpxPackage.version]; + const acpxRuntime = readFileSync( + resolve(destinationDir, "node_modules/acpx/dist/runtime.js"), + "utf8", + ); + if (!expectedPatchMarker || !acpxRuntime.includes(expectedPatchMarker)) { + throw new Error( + `staged acpx@${acpxPackage.version} runtime is missing the repository patch`, + ); + } } if (bundledDependencies.includes("embedded-postgres")) { diff --git a/server/package.json b/server/package.json index 9d8300cfb1..baecc3805a 100644 --- a/server/package.json +++ b/server/package.json @@ -63,6 +63,7 @@ "@paperclipai/shared": "workspace:*", "@paperclipai/skills-catalog": "workspace:*", "@vercel/connect": "0.6.1", + "acpx": "0.13.1", "ajv": "^8.20.0", "ajv-formats": "^3.0.1", "better-auth": "1.7.0", @@ -84,6 +85,9 @@ "ws": "^8.21.3", "zod": "^4.4.3" }, + "bundleDependencies": [ + "acpx" + ], "devDependencies": { "@paperclipai/paperclip-runner": "workspace:*", "@types/express": "^5.0.0",