Accept prerelease Paseo versions in plugin requirements and prepare plugin docs for the 0.8 beta by boudra · Pull Request #4452 · getpaseo/paseo

boudra · 2026-09-07T22:29:07Z

Linked issue

Refs #4206, #4347, #4430, #4265, #4314, #4357, #4435, #4392, #4431, #4358, #4203, #4446, #3983, #3985.

Type of change

Bug fix
Docs

Reasoning

Plugins declaring requirements.paseo: ">=0.8.0" were rejected by Paseo 0.8.0-beta.1, so the release examples could not install on the beta. Match the running version or its stable core against the range in the shared compatibility function. Both the daemon and app use this function; legacy <0.8.0 plugins remain rejected by beta.1, and 0.7.2 remains rejected by >=0.8.0. Explicit prerelease ranges still work.

The ACP example also had unsupported name, version, and description manifest fields. Remove them and validate every checked-in example through the production manifest reader in a parameterized test.

Prepare the plugin guides for the beta: label v0.8 Beta while retaining stable v0.7 navigation; use >=0.8.0 in copyable manifests and explain stable-core matching; correct the slash-command RPC schema and stale runtime-boundary/config-edit guidance; clarify ACP and lifecycle-helper prerequisites; add README plugin discovery and trust guidance. The documentation-navigation assertion follows the Beta label and existing Providers page. The scaffold still generates the current CLI version as its minimum.

Compatibility and scope

No wire schema or RPC shape changes. Old messages still parse unchanged; this changes only local plugin version eligibility in the shared app/daemon helper. An older app still checks its own version and does not become compatible merely because its daemon is compatible. Stable-core matching intentionally treats a prerelease as eligible wherever its stable release is eligible.

Two commits on the branch: the existing docs commit 1766217a8, followed by the code fix 5de2122a7. No evidence files are committed. No release version bump, SDK publish, or provider implementation change.

Test-first evidence

Before the fix, the new compatibility case failed with:

FAIL plugin requirements on daemon > accepts >=0.8.0 on 0.8.0-beta.1
Plugin "test" requires Paseo >=0.8.0. Your daemon is 0.8.0-beta.1.

Before removing the ACP metadata, the new example-validation case failed with:

FAIL plugin manifest > validates the provider-acp-transformer example manifest
Unrecognized keys: "name", "version", "description"

After the fixes:

npx vitest run packages/protocol/src/plugin-requirements.test.ts --bail=1
44 passed — both app and daemon, stable-core acceptance, legacy rejection,
0.7.2 rejection, explicit beta range acceptance, invalid/unknown versions

npx vitest run packages/server/src/server/plugins/manifest.test.ts --bail=1
14 passed — all 12 example manifests plus existing validation tests

npm run build:client   exit 0
npm run typecheck      exit 0
npm run lint           0 warnings, 0 errors
npm run format         exit 0
git diff --check       exit 0

Checked all 12 example manifests and seven manifest JSON snippets across public/internal/example docs: no unsupported top-level metadata fields found. packages/app/src/plugins/registry.ts imports and calls the same assertPluginCompatibility before evaluating client bundles. No app-specific fallback was added.

CLI integration verification

Used this checkout's built CLI against two isolated in-process daemons, each with its own temporary PASEO_HOME and OS-assigned port. The daemon code is the built release source with the rebuilt protocol package; the harness sets only the reported version to beta.1 or 0.7.2. Installed directly from checked-in example directories, with no temporary requirement rewrites or ACP command substitution. All 12 plugins reached running on beta.1, and all 12 were rejected on 0.7.2. Both daemons stopped in finally; existing daemons were untouched.

ACP's example-acp command remains a documented placeholder; installation/running does not establish that command can complete a prompt. Prior UI/provider QA used an installed OpenCode ACP command explicitly, as recorded below.

Example	beta.1 add	0.7.2 add
agent-configuration	exit 0, running	exit 1, incompatible
catppuccin	exit 0, running	exit 1, incompatible
inline-thinking	exit 0, running	exit 1, incompatible
lifecycle-actions	exit 0, running	exit 1, incompatible
lifecycle-logger	exit 0, running	exit 1, incompatible
linear	exit 0, running	exit 1, incompatible
local-plugin	exit 0, running	exit 1, incompatible
modal-ui	exit 0, running	exit 1, incompatible
provider-acp-transformer	exit 0, running	exit 1, incompatible
provider-direct	exit 0, running	exit 1, incompatible
settings	exit 0, running	exit 1, incompatible
timeline-items	exit 0, running	exit 1, incompatible

Exact CLI commands and output (trust notice / Node warning omitted)