DOCUMENTATION / PROJECT

Documentation for AgentRun 0.1.0-beta.27. Use the matching setup instructions → GitHub’s main branch may include unreleased changes.

Release a beta

The packages are @parcha/agentrun-dsl, @parcha/agentrun-jev, @parcha/agentrun-pi, @parcha/pi-durable-disk, @parcha/pi-browser, @parcha/pi-vision, @parcha/pi-transport, @parcha/pi-durable-agent, @parcha/pi-git-remote and @parcha/pi-agent-learn. They share a version and are published in that order (pi-durable-disk, pi-browser, pi-vision, pi-transport, pi-durable-agent and pi-git-remote depend on none of the others; pi-agent-learn depends on dsl, pi and pi-git-remote). @parcha/agentrun-harness and @parcha/agentrun-serve are in the repository but held; see Held packages. Publication is manual; pushes, pull requests and tags do not publish packages.

Held packages

The packages a release may publish are named, in publication order, in releasePackageNames in scripts/release-preflight.mjs: dependencies first (dsl, then jev and pi), then the packages that depend on none of them, serve (@parcha/agentrun-serve), which uses dsl, pi, pi-durable-disk and pi-durable-agent, pi-agent-learn, which uses dsl, pi and pi-git-remote, and the reference host (@parcha/agentrun-harness), which uses dsl, pi, pi-browser, pi-durable-disk and pi-vision, last. That list is the gate for a new package: release-preflight fails when a workspace package is neither private nor named there, so a package is never published by accident. A package whose manifest says "private": true is held. It is built, tested, typechecked and checked by verify-packages and verify:tarball, and it is bumped with the workspace version in every release PR like the rest (release-preflight fails if its version differs from the workspace's), but it is skipped at publication: the publish set (releasePackages, which verify-published and the workflow's publish loop read) is the named packages that are not held. @parcha/agentrun-harness and @parcha/agentrun-serve are held while publishing them is on hold. Lifting a hold is one commit that removes "private": true from the package's manifest, after its npm bootstrap and trusted publisher exist (see "Prepare publication").

Verify the source and packages

Use Node 22.23.2, npm 11.21.0 and GNU tar for release verification. From a clean checkout:

npm install --global npm@11.21.0 --ignore-scripts
npm ci --ignore-scripts
npm run check
npm run export:source
node scripts/check-generated.mjs
npm run verify:packages
npm run verify:source

Inspect .release/verification.json and .release/source-consumer.json. Package verification installs the exact tarballs into an empty consumer. Source verification checks the archive against its export receipt, then extracts, installs, builds and exercises its offline examples. Dependency installation requires network access.

Regenerate schemas, packaged demo data and the dependency inventory when their sources change. Verify that LICENSE, NOTICE and applicable asset notices accompany the source and package archives. Offline checks establish execution behavior; live adapter compatibility needs a separate configured check.

Prepare publication

Confirm publishing access to the @parcha npm organization. New packages need an initial authenticated publication before a trusted publisher can be associated with them. Arrange that bootstrap with the package owner; the release workflow does not create accounts, grant ownership or complete this first-publication setup. The existing @parcha/agentrun package is separate.

Once each package exists, configure its trusted publisher for this repository's release.yml workflow. This workflow publishes directly, so the association must allow direct publishing. Configure the npm-release GitHub environment with maintainer review and allowed tags. Subsequent workflow releases use OIDC and provenance. See npm trust for publisher configuration.

Before creating the release tag:

  1. Confirm who will start the workflow. A GitHub App needs Actions: write to dispatch or rerun it; repository contents access alone is insufficient. If the App lacks this permission, arrange a maintainer dispatch before starting the release.
  2. Confirm who can approve npm-release. If Prevent self-review is enabled, the person starting the workflow must have a different eligible reviewer. A sole reviewer who also dispatches needs self-review allowed; keep the required review and allowed-tag restrictions.
  3. Include any release-script or workflow fixes in the reviewed commit before tagging. A rerun uses the tagged source, not newer fixes on main. Release tags cannot be moved or deleted, so a tag on the wrong commit costs that version number: run the preflight at a local tag in a clean checkout before pushing the tag.

Complete the public launch checklist before announcing the release. Review source, repository refs and retained GitHub records before changing visibility. Source export checks do not review issues, pull requests or Actions artifacts.

Before the tag, fold the changelogs with one command: node scripts/changes.mjs --fold 0.1.0-beta.1 --date 2026-10-20 (the date defaults to today, UTC). In the root CHANGELOG.md, and in each package changelog that has fragments, it renames the Unreleased section ## 0.1.0-beta.1 (2026-10-20), keeping its bullets and adding the fragments' bullets after them, and opens a new empty Unreleased section above it. A fragment goes to its package's own changelog, else the root; a package changelog with no fragment is untouched. It deletes the fragments. Commit the result with the version bump. The preflight refuses a tag while a fragment remains or the root CHANGELOG.md has no section for the version.

The fold and the version bump are one commit, the release pull request, and CI guards it. A release commit is one where any workspace package.json version differs from the merge base's (the pull request's base, or the merge queue's base for a queued one). On it, changes/ must hold only README.md; otherwise the required verify jobs fail with release commit carries unfolded fragments: <names>; refold on current main. That happens when another pull request adds a fragment after the fold was made. Refold on current main (node scripts/changes.mjs --fold <version>) and push; the queue then takes the release pull request again. A release that folded, merged main and folds a late fragment in a second commit gets the same changelogs as one fold of all of them, for held and for published packages: the fold takes the first fold's output (a held package's run in its Unreleased section, a published package's dated section, which one fold groups by kind and orders by fragment name) back to the merge base's text (--base, default origin/main) and rebuilds it with the late fragments in the fold's order. A section that was edited by hand since the first fold is not rebuilt; the late bullets go after it. --check refuses a hand edit of a held package's Unreleased section, but it reads only Unreleased sections, so it does not see an edit of a published package's dated section. Every other commit is untouched, a fold that changes no version included.

So the tag always goes on the release pull request's own merge commit, and there are no separate fold pull requests: a fold changes no version, so the guard would not fire on one, and a late fragment would reach the tag unfolded.

Create a reviewed beta tag whose version matches every package, such as v0.1.0-beta.1. At that exact tag:

node scripts/release-preflight.mjs --tag v0.1.0-beta.1

The preflight checks tag identity, clean source, package versions, licenses and verified archive bytes. A passing check does not authorize publication.

Publish and verify

Dispatch Publish verified beta with the workflow ref and tag input set to the same reviewed tag, after ci.yml has finished on the tagged commit's push to main. The workflow does not run the suites again: it first requires that run's verify (<node>) jobs to have passed (scripts/release-ci-gate.mjs), with verify (22.19.0) and verify (22.23.2) present, and stops if the run is missing, still running or red. Other jobs of that run do not stop a release. It then builds and runs the checks that make the archives, requires a public repository, publishes the verified archives with the latest tag in dependency layers (each layer published, then all of its packages verified against the registry at once, a failure stopping the release before the next layer), and verifies registry integrity and a fresh installed consumer. A version is published as latest because npm's package page shows the README of the publish that carried the latest tag; moving latest later with npm dist-tag leaves the page without one. After the run, a maintainer moves the beta dist-tag to the same version of each package (npm dist-tag add <name>@<version> beta), since the install commands name @beta.

An npm publish success can mean the package is still processing. The verifier waits up to 20 minutes in each of three phases: for a version's registry document to appear, for its tarball to download, and for npm to list every release version in both the full and the abbreviated (install) metadata. It polls every 5 seconds at first and backs off to every 30. npm took about 5 minutes to show beta.10 and 16 for beta.11's first package; the job's own limit is 45 minutes, so several slow packages in a row can still end the run, and a rerun on the same tag resumes. Only then does it run its one clean installation. It still fails immediately on authentication errors or mismatched integrity. Do not treat npm's acceptance message as a completed release.

If publication stops partway, resume from the same tag and archive bytes. The workflow verifies an existing version before skipping it. A byte mismatch stops publication; never replace a published version with different bytes.

If the visibility wait expires, check the exact version in the registry before retrying; it may already be published. Resume only after confirming its bytes match the verified archive. Do not change the version or start a separate publication to work around the delay.

Once publication passes, the workflow's image job builds AgentRun Server's container from the same tag (packages/serve/docker/Dockerfile, for linux/amd64 and linux/arm64) and pushes ghcr.io/parcha-ai/agentrun-server:<tag> and :beta, with an SBOM and max provenance, which buildx stores with the image. GitHub's registry creates a new package private: after the first push, a maintainer makes it public once, in the package's settings.

The release is complete only when every published archive matches the release plan and the fresh registry installation passes. Confirm the beta-release-<run ID> artifact contains the release plan, archives, and published-all.json with status: passed and cleanRegistryInstall: true.

After publication, test the README from an empty clone and exact-version npm installation outside the workspace. Remove private or unpublished notices only when those public paths work. Website deployment belongs to the separate website repository.

See npm's trusted publishing, provenance and scoped package documentation for account setup.

Public launch

  1. Review the release source and make only the DSL repository public. Keep the website repository and any prelaunch history archive private. Verify that an unauthenticated user can clone the source and follow the README.
  2. A repository admin must enable Settings → Advanced Security → Private vulnerability reporting. GitHub provides this feature only for public repositories. Open the reporting form from a signed-in account without repository write access to confirm it works. A maintainer must subscribe to security-alert notifications. See GitHub's setup instructions.
  3. Publish the verified packages in dependency order, then verify a clean registry installation. Until that succeeds, keep the source installation as the default and retain the unpublished-package notices. Previously prepared tarballs are invalid after source changes; rebuild and verify them.
  4. Once the registry checks pass, update the package READMEs and changelog with the published version, beta install commands and release date. Test those exact commands outside the workspace before announcing them.