## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - Paperclip is distributed as npm packages, including plugins like
`plugin-e2b`
> - The release process publishes canary and stable builds via npm
dist-tags
> - But there was no automated verification that published packages
actually landed with the correct dist-tags, and broken canary publishes
could silently ship to users
> - This PR adds a registry verification script that checks published
packages match their expected dist-tags, and wires it into PR CI so
regressions are caught before merge
> - The benefit is release integrity is verified automatically, and
broken dist-tag states are caught early
## What Changed
- Added `scripts/verify-release-registry-state.mjs` — verifies that
published npm packages have correct dist-tag assignments and detects
orphaned or mispointed tags
- Added `scripts/verify-release-registry-state.test.mjs` — test coverage
for the verification logic
- Updated `scripts/release.sh` to include canary dist-tag safety checks
before publishing
- Updated `.github/workflows/pr.yml` to run registry verification as a
CI step
- Updated `doc/PUBLISHING.md` and `doc/RELEASING.md` with the new
verification workflow
## Verification
- `pnpm test` — all tests pass including new verification script tests
- `node scripts/verify-release-registry-state.mjs` — runs against the
live npm registry and reports current state
- CI: the new PR workflow step runs on every PR push
## Risks
- Low risk. This is additive CI and tooling — no runtime code changes.
The registry verification is read-only (queries npm, does not publish).
The release script changes add safety checks that abort before
publishing if state is unexpected.
## Model Used
Codex GPT 5.4 high via Paperclip.
## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - Sandbox environments are part of that execution layer, and the
recent core refactor moved provider-specific behavior to a generic
plugin seam
> - This pull request adds a dedicated `@paperclipai/plugin-e2b` package
so E2B can live entirely outside core host code
> - Because the feature is still unreleased, the plugin should model
third-party packaging directly instead of carrying extra
backward-compatibility complexity in core or the workspace lockfile
> - This branch therefore makes the E2B provider a standalone
publishable package, documents the package-local dev flow, and keeps the
publish manifest/runtime dependency story correct
> - The benefit is that E2B becomes a true plugin reference
implementation that can be installed by package name without reopening
core Paperclip code
## What Changed
- Added `packages/plugins/paperclip-plugin-e2b` as the E2B sandbox
provider plugin package
- Implemented config validation, lease acquire/resume/release/destroy
handlers, workspace realization, and command execution for E2B sandboxes
- Excluded the E2B plugin package from the root workspace so the repo no
longer needs `pnpm-lock.yaml` churn for its third-party dependency graph
- Added package-local development/install support plus a prepack
manifest generator so the published tarball still declares
`@paperclipai/plugin-sdk` and `e2b` runtime dependencies
- Addressed review feedback by fixing sandbox cleanup on acquire
failures, rejecting blank templates, normalizing fractional `timeoutMs`,
and always passing the configured template name to the E2B SDK
- Updated focused Vitest coverage for config normalization, validation,
acquire cleanup, command execution, and lease release behavior
- Updated the Dockerfile deps stage to copy the E2B package manifest so
the policy check stays in sync
## Verification
- `cd packages/plugins/paperclip-plugin-e2b && pnpm install
--ignore-workspace --no-lockfile`
- `cd packages/plugins/paperclip-plugin-e2b && pnpm build`
- `cd packages/plugins/paperclip-plugin-e2b && pnpm --ignore-workspace
test`
- `cd packages/plugins/paperclip-plugin-e2b && pnpm --ignore-workspace
typecheck`
- `cd packages/plugins/paperclip-plugin-e2b && npm pack --dry-run`
## Risks
- The package now relies on a prepack manifest rewrite so the
publish-time dependency list stays correct while the repo-local dev
manifest stays workspace-light
- The current repo snapshot is still unreleased, so the generated
publish manifest points at the repo SDK version until the normal release
flow rewrites versions before publish
- Real-world E2B environments may still expose edge cases around
lifecycle timing or sandbox metadata beyond the mocked unit coverage
> 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 via `codex_local`
- Model ID: `gpt-5.4`
- Reasoning effort: `high`
- Context window observed in runtime session metadata: `258400` tokens
- Capabilities used: terminal tool execution, git, GitHub CLI, and local
build/test inspection
## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - As the project grows, more contributors want to build features —
which is great
> - Without a public roadmap or clear contribution guidance,
contributors spend time on PRs that overlap with planned core work
> - This creates frustration on both sides when those PRs can't be
merged
> - This PR publishes a roadmap, updates the contribution guide with a
clear path for feature proposals, and reinforces the workflow in the PR
template
> - The benefit is that contributors know exactly how to propose
features and where to focus for the highest-impact contributions
## What Changed
- Added `ROADMAP.md` with expanded descriptions of all shipped and
planned milestones, plus guidance on coordinating feature contributions
- Added "Feature Contributions" section to `CONTRIBUTING.md` explaining
how to propose features (check roadmap → discuss in #dev → consider the
plugin system)
- Updated `.github/PULL_REQUEST_TEMPLATE.md` with a callout linking to
the roadmap and a new checklist item to check for overlap with planned
work, while preserving the newer required `Model Used` section from
`master`
- Added `Memory / Knowledge` to the README roadmap preview and linked
the preview to the full `ROADMAP.md`
## Verification
- Open `ROADMAP.md` on GitHub and confirm it renders correctly with all
milestone sections
- Read the new "Feature Contributions" section in `CONTRIBUTING.md` and
verify all links resolve
- Open a new PR and confirm the template shows the roadmap callout and
the new checklist item
- Verify README links to `ROADMAP.md` and the roadmap preview includes
"Memory / Knowledge"
## Risks
- Docs-only change — no runtime or behavioral impact
- Contribution policy changes were written to be constructive and to
offer clear alternative paths (plugins, coordination via #dev, reference
implementations as feedback)
## Model Used
- OpenAI Codex local agent (GPT-5-based coding model; exact runtime
model ID is not exposed in this environment)
- Tool use enabled for shell, git, GitHub CLI, and patch application
- Used to rebase the branch, resolve merge conflicts, update the PR
metadata, and verify the repo state
## 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
- [ ] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable (N/A — docs only)
- [ ] If this change affects the UI, I have included before/after
screenshots (N/A — no UI changes)
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Add a required "Model Used" section to the PR template so contributors
document which AI model (with version, context window, reasoning mode,
and other capability details) was used for each change. Also adds a
corresponding checklist item.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - The GitHub repository uses CODEOWNERS to enforce review requirements on critical files
> - Currently only release scripts and CI config are protected — package manifests are not
> - Dependency changes (package.json, lockfile) can introduce supply-chain risk if merged without review
> - This PR adds all package files to CODEOWNERS
> - The benefit is that any dependency change now requires explicit approval from maintainers
## What Changed
- Added root package manifest files (`package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.npmrc`) to CODEOWNERS
- Added all 19 workspace `package.json` files (`cli/`, `server/`, `ui/`, `packages/*`) to CODEOWNERS
- All entries owned by `@cryppadotta` and `@devinfoley`, consistent with existing release infrastructure ownership
## Verification
- `gh api repos/paperclipai/paperclip/contents/.github/CODEOWNERS?ref=PAPA-41-add-package-files-to-codeowners` to inspect the file
- Open a test PR touching any `package.json` and confirm GitHub requests review from the listed owners
## Risks
- Low risk. CODEOWNERS only adds review requirements — does not block merges unless branch protection enforces it. New packages added in the future will need a corresponding CODEOWNERS entry.
## Checklist
- [x] I have included a thinking path that traces from project context to this change
- [x] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
* ci: add Dockerfile deps stage validation to PR policy
Checks that all workspace package.json files and the patches/
directory are copied into the Dockerfile deps stage. Prevents the
Docker build from breaking when new packages or patches are added
without updating the Dockerfile.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* ci: scope Dockerfile check to deps stage and derive workspace roots
Address Greptile review feedback:
- Use awk to extract only the deps stage before grepping, preventing
false positives from COPY lines in other stages
- Derive workspace search roots from pnpm-workspace.yaml instead of
hardcoding them, so new top-level workspaces are automatically covered
* ci: guard against empty workspace roots in Dockerfile check
Fail early if pnpm-workspace.yaml parsing yields no search roots,
preventing a silent false-pass from find defaulting to cwd.
* ci: guard against empty deps stage extraction
Fail early with a clear error if awk cannot find the deps stage in the
Dockerfile, instead of producing misleading "missing COPY" errors.
* ci: deduplicate find results from overlapping workspace roots
Use sort -u instead of sort to prevent duplicate error messages when
nested workspace globs (e.g. packages/* and packages/adapters/*) cause
the same package.json to be found twice.
* ci: anchor grep to ^COPY to ignore commented-out Dockerfile lines
Prevents false negatives when a COPY directive is commented out
(e.g. # COPY packages/foo/package.json).
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Address Greptile feedback — the sparse 3-line placeholder could
lead to shallow thinking paths. Expanded to 6 lines with guiding
brackets and added "Aim for 5–8 steps" hint in the comment.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Merge pr-verify.yml, pr-policy.yml, and pr-e2e.yml into a single
pr.yml with three parallel jobs (policy, verify, e2e). Benefits:
- Single concurrency group cancels all jobs on new push
- Consistent Node 24 across all jobs
- One file to maintain instead of three
The jobs still run independently (no artifact sharing) since pnpm
cache makes install fast and the upload/download overhead for
node_modules would negate the savings.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Align with e2e.yml and ensure CI tests exactly the committed
dependency tree. The pr-policy job already blocks lockfile changes
in PRs, so frozen-lockfile is safe here.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The playwright.config.ts had `reuseExistingServer: !!process.env.CI`
which meant CI would reuse (expect) an existing server while local
dev would start one. This is backwards — in CI Playwright should
manage the server, and in local dev you likely already have one
running.
Flip to `!process.env.CI` and remove the `CI: ""` env override
from the workflow.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add a PR E2E workflow that runs the Playwright onboarding test on
every PR targeting master. Generates a minimal config file and lets
Playwright manage the server lifecycle. Runs in skip_llm mode so
no secrets are required.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The "Enable auto-merge" step runs unconditionally, even when the
lockfile didn't change and no PR exists. This causes the workflow
to fail with "lockfile PR was not found."
Use a step output to gate the auto-merge step so it only runs
when a PR was actually created or updated.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Scaffolds end-to-end testing with Playwright for the onboarding wizard.
Runs in skip_llm mode by default (UI-only, no LLM costs). Set
PAPERCLIP_E2E_SKIP_LLM=false for full heartbeat verification.
- tests/e2e/playwright.config.ts: Playwright config with webServer
- tests/e2e/onboarding.spec.ts: 4-step wizard flow test
- .github/workflows/e2e.yml: manual workflow_dispatch CI workflow
- package.json: test:e2e and test:e2e:headed scripts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Simplify the PR-based flow: force push to update the branch if it
already exists, and only create a new PR when one doesn't exist yet.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Use lockfile-bot name/email instead of github-actions[bot]
- Remove force push: close any stale PR and delete branch first,
then create a fresh branch and PR each time
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace peter-evans/create-pull-request with plain gh CLI commands to
avoid third-party supply chain risk. Uses only GitHub's own tooling
(GITHUB_TOKEN + gh CLI) to create the lockfile refresh PR.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The refresh-lockfile workflow was pushing directly to master, which fails
with branch protection rules. Convert to use peter-evans/create-pull-request
to create a PR instead. Exempt the bot's branch from the lockfile policy check.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Devin Foley