fix(adapters): anchor emitted stdio MCP entries with AGENT_BUNDLE_PLUGIN_ROOT and restore claude cwd

[ScriptedAlchemy]

Closes #47

What

Every adapter now injects a well-known AGENT_BUNDLE_PLUGIN_ROOT environment variable into emitted stdio MCP server entries, holding the plugin install root in the target's native spelling, and the claude adapter stops dropping cwd for source-built servers. This hoists the consumer workaround from the movie-library port into the framework: plugin runtimes get a working-directory-independent install-root anchor on every host, including Claude Code, which silently ignores stdio cwd at runtime (anthropics/claude-code#17565, #42883, #54786).

Per-adapter before/after (source-built entry: server demo)

claude (.mcp.json) — before dropped cwd and emitted no env; after:

{"args":["${CLAUDE_PLUGIN_ROOT}/mcp/demo.mjs"],"command":"node","cwd":"${CLAUDE_PLUGIN_ROOT}","env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CLAUDE_PLUGIN_ROOT}"},"type":"stdio"}

The absolute args[0] stays as the hedge against the upstream cwd-ignoring bugs; cwd is documented and schema-valid, so it is emitted as future-proofing and the env anchor carries the guarantee today.

portable (mcp.json) — before: cwd: "${PLUGIN_ROOT}", no env; after adds:

{"env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${PLUGIN_ROOT}"}}

codex (.mcp.json) — before: cwd: "./" with ./-relative args, no env; after adds:

{"env":{"AGENT_BUNDLE_PLUGIN_ROOT":"./"}}

Codex has no path-token interpolation, so ./ is only meaningful resolved against the entry's plugin-root cwd. A codex stdio entry without a plugin-root cwd omits the anchor rather than emitting a misleading value (consistent with the existing hard diagnostics for plugin-root tokens on such entries). Source-built servers always have a plugin-root cwd, so they always carry the anchor.

cursor (mcp.json) — before: no env; after adds:

{"env":{"AGENT_BUNDLE_PLUGIN_ROOT":"${CURSOR_PLUGIN_ROOT}"}}

plugin (unified bundle) — reuses the three planners, so .mcp.json, .codex-plugin/mcp.json, and .cursor-plugin/mcp.json each carry their host's native anchor (pinned by a new bundle regression test).

Merge semantics

withPluginRootEnvAnchor spreads declared env entries after the injected anchor, so a user-declared AGENT_BUNDLE_PLUGIN_ROOT key always wins. Documented on the config env field, in the package README, and in the root README's artifact contract. The anchor name ships as the public pluginRootEnvAnchor export.

Staleness

All adapter revisions advance 1.0.0 → 1.1.0, so artifacts built before this change revalidate as stale (AB6010, "Rebuild the artifact with the current target registry") instead of silently passing with the old emission shape. Capability tables and pinned schemas are untouched, so all pinned hashes in adapter-metadata.test.ts hold; only the revision pins moved.

Tests

• host-adapters.test.ts: updated exact-content pins; claude source-built entries now assert cwd + anchor (replacing the old not.toHaveProperty('cwd')); new regressions for user-declared-anchor-wins (codex + claude) and codex anchor omission without a plugin-root cwd.
• portable-adapter.test.ts, cursor-adapter.test.ts: anchor pins with native tokens.
• plugin-bundle.test.ts: per-host anchors pinned on all three bundle MCP documents.
• adapter-metadata.test.ts: revision pins 1.1.0; hashes unchanged.

Gates

• pnpm build ✓, pnpm typecheck ✓, pnpm lint ✓ (0 errors/warnings, 620 files)
• pnpm test:unit ✓ (117 files, 1654 passed / 4 skipped)
• pnpm test:packed ✓ (release-audit, packed-consumer, dev-workbench-packaging, public-api-packed, rsc-runtime-optional-packaging, packed-native-smoke, workbench packed-release e2e)

Consumer note

The movie-library port (agent-plugins/movie-library, commit af0ab2a) works around this per-server today with env: { MOVIE_LIBRARY_ROOT: pathTokens.pluginRoot }. That splice keeps working (user-declared keys win) but is unnecessary for new consumers: runtime code can read process.env.AGENT_BUNDLE_PLUGIN_ROOT (resolving it against process.cwd() to absorb Codex's relative form) on every target.

[changeset-bot]

🦋 Changeset detected

Latest commit: a24dcf8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-30T18:11:46.150463Z	fc0cf26	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@49

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/rsc-runtime@49

commit: a24dcf8