Releasing AgentLoop¶
The official PyPI distribution is agentloop-profiler; Python imports and the
CLI remain agentloop. Release versions start at 0.1.0, followed by routine
patch releases such as 0.1.1 and 0.1.2. A version labels the package; native
trace/study/receipt schemas, API routes and database migrations have their own
versions and do not reset with the package.
Versioning policy¶
Default to a patch bump (0.1.0 → 0.1.1 → 0.1.2 → ...). Reserve
minor for a release whose reason to ship is a notable user-facing
feature, and major for a breaking change (before 1.0, any deliberate
breaking change). The maintainer chooses the bump explicitly.
Don't reach for minor just because a release happens to
include a new feature among other changes.
scripts/bump_version.py rejects repeated or lower versions, updates package and
runtime metadata together, moves nonempty Unreleased entries to a dated changelog
section, and refreshes uv.lock. If an update or lock refresh fails, it restores
the original files so preparation can retry. A restoration failure reports the
affected paths for manual recovery. The one-time initial numbering reset does not
weaken that rule for future releases.
Prepare and review¶
The 0.2.0 preparation uses the existing helper's explicit --set 0.2.0 override
for the maintainer-selected guided optimization release. Its focused prerequisite
PRs stay separate from the version/changelog PR. Review
the readiness audit, upgrade notes,
guided validation and remaining gaps.
Preparation does not authorize merging, tagging or publishing. Obtain explicit
maintainer approval and satisfy normal protected-branch reviews/checks before
each authorized integration or publication step. The TypeScript SDK has its own
npm release flow, described below.
Run Prepare release on main, or:
The workflow validates main before creating a preparation branch and PR. Its version input accepts an explicit greater X.Y.Z override. Inputs pass through quoted environment variables, and preparation never force-overwrites a branch. Fresh CI, CodeQL, dependency, replay and application checks run against the exact preparation head, including PRs created with GitHub's bot token.
The repository must allow Actions to create PRs for this automated flow. A manual alternative is to run the existing version helper in a clean branch:
uv run --frozen python scripts/bump_version.py patch
uv run --frozen pre-commit run --all-files
uv run --frozen --all-extras python -m pytest -q
uv build
uv run --isolated --no-project --with twine twine check dist/*
Review the changelog, source/compatibility changes, dependency license inventory, wheel/sdist and four standalone CLI artifacts. Follow UPGRADING.md for existing clients and stores. Required final-head checks must pass, actual review findings must be resolved, and the PR must merge normally. Skipped bot reviews are not approvals.
Merging preparation does not tag or publish. Once the final source is reviewed and its main checks pass, explicitly create the matching annotated tag:
git switch main
git pull --ff-only origin main
git tag -a vX.Y.Z -m "AgentLoop X.Y.Z"
git push origin vX.Y.Z
Validate and publish¶
release.yml checks that the ref is an annotated semantic version tag, exactly
matches package metadata and points to a commit reachable from main. It runs the
reusable full CI against that exact tag: Python 3.11/3.13/3.14/3.15, SQLite/Postgres,
lock/format/security checks, Docker deployment, installed-wheel smoke and four
standalone platform builds. Publication downloads those validated bytes instead
of rebuilding them. Concurrent publishing runs for one ref are serialized.
The PyPI trusted publisher must match owner dipeshbabu, repository agentloop,
workflow release.yml, and environment pypi. Preserve that filename when
editing the automation. PYPI_PUBLISH_ENABLED=true enables the publish job; the
protected pypi environment still requires its configured reviewer approval.
No API token belongs in source or workflow logs.
GitHub publication attaches the validated distributions, platform executables,
complete dependency notices, license files and SHA256SUMS. Notes come from the
exact version's changelog, rather than importing obsolete PR/release titles.
Recover an interrupted tagged release by explicitly dispatching:
Do not reuse a published version or move its tag. Publish a new patch for a fix. PyPI cannot restore deleted releases or accept a previously used filename.
Verify publication¶
Download and verify the release checksum manifest and one available standalone
executable, then run its --help. In an isolated Python environment:
python -m pip install agentloop-profiler==X.Y.Z
python -m pip show agentloop-profiler
agentloop --help
The wheel's adoption smoke also exercises quickstart, qualified JSON/HTML, studies, retained quality failures and interventions:
On Windows use path/to/wheel-env/Scripts/python.exe. A merged PR, tag, or GitHub
release does not prove PyPI publication; verify each destination independently.
For the initial numbering restart, install the exact 0.1.0 version in existing
environments and refresh pinned requirements. Removing earlier PyPI releases
requires the owner's project management page.
Keep the registered project and its trusted publisher; removing the whole project
can release its name. See PyPI's deletion and filename rules.
TypeScript SDK on npm¶
The SDK in sdk/typescript publishes to npm as agentloop-profiler. Its version
is independent of the Python package. Bump version in
sdk/typescript/package.json (and refresh package-lock.json with
npm install --package-lock-only) in a normal PR, then tag the merged commit:
git switch main
git pull --ff-only origin main
git tag -a typescript-vX.Y.Z -m "AgentLoop TypeScript SDK X.Y.Z"
git push origin typescript-vX.Y.Z
release-npm.yml checks that the tag is annotated, matches the package version
and is reachable from main. It builds and tests the SDK on Node.js 22 and 24, then
publishes with npm trusted publishing and provenance. Publishing runs only when
the repository variable NPM_PUBLISH_ENABLED is true, in the npm environment.
One-time setup, after the first publish exists on npm:
- On npmjs.com, open the package's Settings → Trusted publishing and add
GitHub Actions with repository
dipeshbabu/agentloop, workflowrelease-npm.ymland environmentnpm. - In the GitHub repository, create the
npmenvironment and set the repository variableNPM_PUBLISH_ENABLEDtotrue.
The trusted publisher is configured from the package's settings page, so the first version is published by hand from a clean checkout of main:
npm login
cd sdk/typescript
npm ci && npm test && npm run test:types
npm pack --dry-run
npm publish --access public
npm versions are immutable: a published version cannot be re-uploaded, and unpublishing is restricted after 72 hours. Fix mistakes with a new patch version. Verify publication in a fresh directory: