For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/guide/distribution/preview-packages.md.
Skip to main content
agent-bundle
  • English

      • Preview packages

      pkg.pr.new is the package distribution channel. Every CI package-preview run publishes real, installable tarballs of all four publishable workspace packages to a free continuous-release registry keyed by commit SHA and pull request. Consumers pin the commit-addressed URLs; no npm registry credential is needed or expected.

      The install commands and the runtime pairing rule are in Installation. This page is the channel itself: where previews come from, how far you can trust them, and what pinning actually guarantees.

      Where previews come from

      .github/workflows/package-preview.yml runs pnpm preview:publish after a full build. Pull requests invoke it directly; .github/workflows/release.yml reuses it for every push to main. It publishes packages/agent-bundle, packages/rsc-runtime, packages/rsc-markdown-stream (the Markdown renderer @agent-bundle/runtime depends on), and packages/create-agent-bundle with --previewVersion --peerDeps --no-compact --no-template.

      Pull request runs are grouped by PR with cancel-in-progress, so a newer push cancels the superseded PR build. On main, the serialized Release packages workflow waits for the reusable preview job and does not cancel an earlier release run.

      The "Publish pkg.pr.new preview" check on a PR or commit links to the exact URLs for that build. Previews are built from the same pnpm build output the release gates verify, but they are not npm releases, and they carry preview version strings.

      Pinning, and one historical caveat

      The pairing rule and the install commands live in Installation; two details belong to the channel itself.

      A PR reference resolves to the last preview published for that PR, so @1 means "PR #1's most recent build" rather than a fixed commit. Short SHAs never move, which is why a lockfile should carry one.

      Previews published before the peer rewrite landed (PR #46) still carry the original agent-bundle@^0.1.0 peer range, so pair-installing those older SHAs with npm still requires --legacy-peer-deps. Anything newer installs with stock npm.

      Stock pnpm 11 is the exception. The preview of @agent-bundle/runtime points its rsc-markdown-stream dependency at the renderer's same-sha preview tarball, and pnpm 11's blockExoticSubdeps (default true) rejects a transitive dependency resolved from a tarball URL with ERR_PNPM_EXOTIC_SUBDEP. Set blockExoticSubdeps: false in the consuming project's pnpm-workspace.yaml, or install previews with npm.

      The scaffolder ships on the same channel and is meant to be run rather than installed:

      npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-pr> \
  my-plugin

      A scaffolded project pins agent-bundle to the preview of the same commit the scaffolder came from, so both sides of the pairing rule hold automatically.

      Version Packages merges

      The Release packages workflow records one of version-maintenance-only, preview-release, or failed, with executed and skipped stages. A successful Version Packages refresh is version-maintenance-only. When that PR merges, Release packages first calls the reusable Package preview workflow, which publishes and resolves all four https://pkg.pr.new/ScriptedAlchemy/agent-bundle/<package>@<sha> URLs. The release job depends on that proof and qualifies the exact same merge SHA, so green means the packed gates passed and every commit-addressed package is installable.

      pnpm check:release runs pnpm pack:dry-run, pnpm lint:release, and pnpm test:packed:release. lint:release runs attw with the esm-only profile on the packed agent-bundle, @agent-bundle/runtime, rsc-markdown-stream, and create-agent-bundle tarballs, then scripts/check-declaration-imports.mjs over the same inventories: every .d.ts a consumer can reach from exports may only import packed files, the package's own exported subpaths, # imports its imports map resolves, Node built-ins, and packages declared in dependencies, peerDependencies, or optionalDependencies, absolute paths and URLs never resolve in a consumer install, and a devDependency such as zod in any packed declaration fails the gate, lint:release runs the check with --strict, so an internal declaration no entry point reaches fails like a reachable one (without the flag it is only reported as a warning). Reachability starts from every types target under exports plus the legacy types field, /// <reference types> is checked like a bare import, and a relative import, /// <reference path>, or exports target that names a file missing from the tarball fails too. publint is not a separate gate: every publishable package's rslib build runs it through rsbuild-plugin-publint and fails the build on a warning. That gate is release-only and does not replace the ordinary pnpm check delivery gate.

      Next