deployment release pipeline

Release pipeline

Every package shares one version (lockstep versioning), and every release moves all of them together. There are no major releases: release:patch covers bug fixes and new features, and release:minor covers API breaking changes. This page describes the release mechanics, the packaging and publishing flow, and the current state of the CI release workflows.

Lockstep versioning

The root package.json defines the shared version and the release scripts. All of packages/ai, packages/agent, packages/tui, and packages/coding-agent publish at the same version, and their inter-package dependencies are kept in sync by scripts/sync-versions.js, which verifies all package versions are identical (it exits non-zero if not) and rewrites every inter-package dependencies and devDependencies range to match.

The version-bump scripts are:

• npm run version:patch, npm version patch -ws --no-git-tag-version, then node scripts/sync-versions.js, then a clean reinstall (shx rm -rf node_modules packages/*/node_modules package-lock.json && npm install).
• npm run version:minor, same flow for a minor bump.
• npm run version:major, defined but not used (there are no major releases).

The release script

scripts/release.mjs (npm run release:patch / npm run release:minor) runs the whole release:

1. Fail if the working tree has uncommitted changes.
2. Bump the version via npm run version:patch/version:minor, or set an explicit x.y.z that must be strictly greater than the current version.
3. Finalize each package CHANGELOG.md, replacing the ## [Unreleased] heading with ## [<version>] - <date>.
4. Stage and commit (Release v<version>), then create a v<version> git tag.
5. Publish with npm run publish.
6. Add a fresh ## [Unreleased] section to each changelog and commit it (Add [Unreleased] section for next cycle).
7. Push main and the new tag to the remote.

Packaging

Two packaging paths exist.

scripts/pack-prime-agent-release.mjs (npm run release:pack) creates the Qredence-branded public artifact and its private workspace dependency tarballs for R2 distribution:

• It reads the four source packages and requires each to be built (it fails if any dist is missing).
• It also requires the packaged web runtime: packages/coding-agent/dist/web/launcher.mjs and dist/web/client, which come from npm run build:web:release.
• It rewrites each release package.json: keeps dependency keys on the source package names so compiled imports keep resolving, deletes devDependencies/overrides/private, rewrites internal dependency ranges to absolute tarball URLs under the given --base-url, and brands the public coding-agent package with a bin (prime-agent -> dist/bundle/cli.js), a piConfig, and Qredence repository metadata.
• It npm packs each package into <out-dir>/artifacts/ as prime-agent-<version>.tgz, prime-agent-ai-<version>.tgz, prime-agent-core-<version>.tgz, and prime-agent-tui-<version>.tgz, writes a SHA256SUMS manifest, a channel pointer file, and a latest.json (stable) or beta.json (beta) manifest. --channel is stable or beta; --base-url or PRIME_AGENT_DOWNLOAD_BASE_URL is required.

scripts/build-binaries.sh builds self-contained pi binaries for several platforms with bun build --compile against packages/coding-agent/dist/bun/cli.js (targets darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64). It externalizes koffi to avoid embedding all platform .node files (koffi is used only on Windows for VT input and has a try/catch fallback; the Windows build copies the matching .node alongside the binary), installs cross-platform native bindings for clipboard and sharp, copies shared assets (theme, assets, export-html, docs, examples, skills, the photon wasm), and emits .tar.gz archives for Unix and a .zip for Windows under packages/coding-agent/binaries/.

Publishing

npm run publish runs npm run prepublishOnly followed by npm publish -ws --access public. The root prepublishOnly runs npm run clean, npm run build, and npm run check. packages/coding-agent additionally defines its own prepublishOnly (npm run clean && npm run build) and a postinstall (node postinstall.cjs).

Web release build

scripts/build-web-release.mjs (npm run build:web:release) assembles the production web runtime inside the coding-agent artifact. It requires pnpm --dir web --filter @prime-agent/web build output (web/app/dist/server/server.js and web/app/dist/client), copies the client into packages/coding-agent/dist/web/client, and uses esbuild to bundle the server entry into dist/web/server with platform: node, target: node22, splitting: true, and a large external set (all coding-agent dependencies, @earendil-works/*, react, react-dom, debug, undici, zeromq, and others). It then copies scripts/prime-agent-web-launcher.mjs to dist/web/launcher.mjs.

CI workflows

Current state as of HEAD 57e3d5445. .github/workflows/ contains three tracked workflows:

• ci.yml, on push to main and pull requests: a build-check job (pnpm 11.15.1, Node 22, npm ci, pnpm install --dir web --frozen-lockfile, npm run build, npm run check), a matrixed test job (agent, ai, tui, coding-agent sharded 1/3, 2/3, 3/3, plus coding-agent process-smoke and kernel suites), a test-web job, and a build-check-test guard that fails if any of the three finished with anything other than success.
• release-prime-agent.yml, the current release workflow. It triggers on a v* tag push or workflow_dispatch, resolves the release context (version and stable/beta channel), checks out the build ref, installs and builds packages plus the packaged web runtime, runs npm run check, runs npm run release:pack with --base-url from R2_PUBLIC_BASE_URL, smoke-tests the installed release with scripts/check-web-release.mjs, uploads the artifacts, then publishes to Qredence R2 (tarballs, SHA256SUMS, latest.json/beta.json, the channel pointer, and a rendered install.sh/install-beta.sh with the __PRIME_AGENT_DOWNLOAD_BASE_URL__ and __PRIME_AGENT_DEFAULT_RELEASE_CHANNEL__ placeholders filled in) and creates a GitHub release for stable builds.
• nightly-process-stress.yml, scheduled daily (cron 0 9 * * *) plus workflow_dispatch; installs, builds, and runs the process-stress suite in packages/coding-agent (npm run test:process-stress) with PRIME_AGENT_STRESS_WORKERS=10.

The removal commit 859871ada (implementation/remove-release-ci, merged as PR #12) did not remove release-prime-agent.yml. It removed the older .github/workflows/build-binaries.yml (412 lines) and deleted one line from scripts/build-binaries.sh; scripts/build-binaries.sh itself remains in the tree. release-prime-agent.yml is present and tracked, and is the workflow that publishes the installer artifacts to R2.

Related pages

• Deployment, the shipping model
• Development workflow, release process summary and changelog discipline
• History, the timeline of the release-CI removal and the installer
• CLI, prime-agent update and the self-update flow