feat(build): emit one composite plugin root; targets select host projections; remove the plugin target (#555 W1)

[ScriptedAlchemy]

Wave 1 (S1 + S2) of the composite-plugin plan for #555 — the DECISION + SPEC and the implementation plan comment. Decisions D1, D5, D7 taken as final. This PR lands for W1 by the owner's decision on #555 (04:52 UTC); #569 stays closed and its consumer/docs/test work is ported here (table below).

What W1 delivers

S1 — remove plugin from the public target model (AB4100)

• config/normalize.ts no longer synthesizes the plugin lowering target; adapters/registry.ts no longer registers pluginAdapter; adapters/plugin.ts is deleted with everything only it used (the Universal hook-wrapper codec, intersectCapabilityStates / unionCapabilityStates / mergeCapabilityEvidence / capabilityBooleanView).
• targets: ['plugin'] and --target plugin fail as an unknown target (AB4100); create-agent-bundle --target accepts only claude|codex|cursor|portable; nothing emits AGENTS.md.
• Removed public API: TargetAdapter.lowersConfigExtensions, TargetRegistry.lowersConfigExtension(), NormalizationTargetRegistry.lowersConfigExtension() (only the composite adapter used them). Removed environment variable: AGENT_BUNDLE_HOOK_HOST (generated hook wrappers bake their host; see below).

S2 — one composite root; targets select host projections (AB4103, AB4105, AB4106)

• build/build.ts stages one root at the artifact output; only the selected hosts' planners run. New build/compose.ts merges byte-identical entries once, fails same-path/different-bytes with AB4103 (projections compared in host-name order, paths in path order), and refuses a host-scoped command or rule another selected host would discover conventionally with AB4105 (D5). config/validate.ts refuses a selection mixing an advanced-TargetRegistry adapter with any other target with AB4106. adapters/composite-layout.ts owns the composite identity (claude+codex), sorted projections, hook-wrapper naming, and the folder-discovery shadow rule.
• Codex and Cursor hook/MCP documents move beside their manifests (.codex-plugin/hooks.json, .codex-plugin/mcp.json, .cursor-plugin/hooks.json, .cursor-plugin/mcp.json; AB6027, AB6032, AB7320 name those paths); when another selected host claims their conventional path they emit an empty shield document so folder discovery cannot leak the other host's file. Claude keeps hooks/hooks.json + .mcp.json; portable keeps plugin.json + mcp.json.
• A hook shared by several selected hosts compiles to hooks/<name>.<host>.mjs per host, each wrapper baking its own host; a single-host hook keeps hooks/<name>.mjs. Native hooks are preserved for every selected host.
• Compiled MCP entries, scripts, routed CLI bins, and MCP Apps compile once and are attributed to the composite identity in build reports and inspect --bundler (BundlerInspectionEntry.target; distPath.root is <output>). INSTALL.md / install.mjs are composed once over the selection. agent-bundle.manifest.json records the selected projections and provenance; agent-bundle.hooks.json indexes the selected hosts. Reordering targets yields byte-identical output.
• The generated MCP entry accepts events from the selected hosts its server targets (allowedTargets = server.targets ∩ selected); inspect describes that set. The warm event runtime's endpoint is identified by the artifact alone — epoch and root directory — and the invoking host rides each hook request (see the Meta-framework architecture: one application graph, capability-driven projections, one execution kernel #592 audit).

validate / inspect / packed pool judge the composite root

• Composition diagnostics (AB4103, AB4105, AB4106) are computed once in prepare and reported identically by validate, inspect, and build (tests/composite-rules.test.ts pins the parity, pooled in the integration list). validate --artifact --host-validation and build --host-validation run each host's validator lane over the root itself.
• Consumers moved to the root: install/doctor (resolveBundleRoot reads the host manifest directly under --from, AB7001 otherwise — no <from>/<host> lookup), mcp run, serve-app, dev proxy --target, the dev epoch store, artifact/skill/script/hook-playground/MCP-session services, the Workbench artifact inspector (one tree per selected host, root .), eval harnesses (Claude/Codex plugin dir = root), rstest/browser.ts, the agent-bundle/test installed harness, examples, and the tests. The packed pool reads the composite root's bin/ and single mcp/ entry.

Composite root layout (examples/host-test, targets: ['claude','codex','cursor','portable'])

artifact/
├── .agents/plugins/marketplace.json          # Codex marketplace
├── .claude-plugin/{plugin.json,marketplace.json}
├── .codex-plugin/{plugin.json,hooks.json,mcp.json}
├── .cursor-plugin/{plugin.json,marketplace.json,hooks.json,mcp.json}
├── .mcp.json                                 # Claude Code MCP document
├── plugin.json, mcp.json                     # portable (Agent Plugins) documents
├── hooks/hooks.json                          # Claude Code hook document
├── hooks/<hook>.mjs                          # hook selected for exactly one host
├── hooks/<hook>.{claude,codex,cursor}.mjs    # hook shared by several selected hosts
├── hooks/hooks-flight.mjs
├── mcp/mcp-<server>-<hash>.mjs (+ -flight)   # compiled once
├── bin/<plugin>.mjs, bin/<plugin>-flight.mjs # routed CLI
├── skills/, commands/, rules/, scripts/, assets/, mcp-apps/   # shared, emitted once when authored
├── INSTALL.md, install.mjs                   # install surface (install.mjs: cursor|portable)
├── agent-bundle.manifest.json                # selected projections + provenance
└── agent-bundle.hooks.json                   # hook index over the selected hosts

Pinned by tests/build-compose.test.ts (exhaustive sorted top-level listing and of each dotfolder, hooks/, scripts/, skills/, commands/; Codex-only / portable-only / Cursor-only cases; byte-identical roots however the targets are ordered; AB4103, AB4105, AB4106).

Diagnostics

Code	Change
AB4100	plugin is an unknown target (prose names the retirement).
AB4103	new, build error — same path, different bytes across selected projections.
AB4105	new, build error — a host-scoped command or rule leaks into a conventionally discovered directory of another selected host. Skills are never host-scoped (normalization gives every skill every selected target; a per-host frontmatter extension that changes bytes is AB4103), so the skill branch that could never fire is gone from compose.ts and the docs say so.
AB4106	new, validate/inspect/build error — an advanced-registry adapter selected beside any other target.

Changeset

One changeset, .changeset/555-composite-plugin-root.md: agent-bundle: minor, create-agent-bundle: minor (breaking pre-1.0); summary names the commands, config keys, exports, env variable, and diagnostic codes above and ends (#578). Private packages (agent-bundle-workbench, examples, website) are not named.

Port from #569 → where it landed in #578

Design differences that drive most "different form" rows: #578 relocates Codex/Cursor documents to static paths (no selection-dependent root contract), emits per-host hooks/<name>.<host>.mjs wrappers instead of one host-detecting wrapper (AGENT_BUNDLE_HOOK_HOST), puts Cursor documents under .cursor-plugin/ rather than hooks/hooks-cursor.json, and projects portable at the root (no portable/ view) with AB4103 arbitrating byte conflicts.

#569 item	Status	Where in #578 / why not
TargetRegistry.root(targets): ArtifactRootContracts, compositeRoot, compositeHostRoot, compositeMcpRuntime, compositeHookContract	different form	planComposite / composeProjections (build/compose.ts), projectionIdentity / sortedProjections / hookWrapperPath / folderDiscoveryShadowed (adapters/composite-layout.ts); per-host document paths are the adapters' constants (codexArtifactPaths, cursorArtifactPaths). Not public exports.
build/artifact-root.ts (readArtifactTargets, readArtifactRootContracts, hostRootDirectory, hostMcpRuntime) + its test	not adopted	Selection is read from parseArtifactManifest(...).targets; host paths are constants; hostRoot is always the root.
Composite TargetAdapter replacing adapters/plugin.ts	not adopted	adapters/plugin.ts deleted; each built-in planner runs and composeProjections merges.
Host-detecting hook wrapper (AGENT_BUNDLE_HOOK_HOST)	not adopted	Per-host wrappers + shield documents; the variable is removed from the runtime-environment reference (en/zh).
AGENTS.md emitted at the root	not adopted	Nothing emits it after S1.
AB4104 (subset-selected shared file; Cursor command beside Claude)	different form	AB4105 for commands/rules with frontmatter targets; Cursor-beside-Claude commands are refused only when the lowered bytes differ (AB4103).
AB4105 (same path, different bytes)	landed, renumbered	AB4103.
AB4106 (advanced-registry adapter mixed into a selection)	landed	config/validate.ts compositeRootTargetDiagnostics, reported by validate/inspect/build.
AB4100 special-cased hint for plugin	different form	Generic Unknown target message; retirement documented in docs/diagnostics.md.
Codex validator follows manifest hooks/mcpServers pointers	different form	Pins codexArtifactPaths.* (the build always writes them). Shared-root test ported: codex-plugin-validation.test.ts "judges only the Codex documents under .codex-plugin/ in a root shared with Claude (#555)". Pointer-following asymmetry with the Cursor lane is a follow-up.
Cursor validator reads hooks/hooks-cursor.json	not adopted	Cursor documents under .cursor-plugin/; the Cursor lane resolves both hooks and mcpServers pointers.
--host-validation over the composite root	landed	api.ts validate --artifact and build --host-validation pass the root as the plugin directory.
install.ts / doctor.ts resolveBundleRoot without <from>/<host> probing	landed	Manifest directly under --from, AB7001 otherwise. Negative tests ported: install.test.ts "refuses --from that names a directory above the %s plugin root instead of probing into it (#555)" for all three hosts (no host CLI runs), doctor.test.ts "lists Claude plugins from the plugin root --from names, never from a directory nested under it (#555)". AB7001 rewording stays with S3.
Dev epoch store, artifact/inspection/script-catalog/hook-playground/skill-document services, host-install manager, MCP session/run services	landed / different form	Root = epoch; projectionDigests (dev/artifacts/projection-digest.ts) one digest per selected host; MCP document paths from the adapters' constants.
Eval harnesses (options.artifact.root), test/installed.ts, Workbench e2e	landed	Codex/Claude plugin dir = root; installed harness reads the composite root as every host's bundle root; Workbench changes are test-only.
Packed pool, host-install fixture (claude+codex+cursor in one root), examples, examples-contract, create-agent-bundle template README and e2e, mcp-conformance pluginRoot, measure-hook-cold-start.mjs	landed	Commits 27625cb61, e10164a20, c7612b5e5.
#569 composite-root rule tests	landed, different form	tests/composite-rules.test.ts + tests/build-compose.test.ts.
Extra Codex proof "installed SKILL.md byte-identical to the built root"	not ported (minor)	Sidecar/skill presence assertions cover discovery.
Docs (diagnostics section, entry-conventions, framework-mode, READMEs, 19 en/zh website pages)	landed	Every website file #569 touched is touched here, following #578's layout and codes.
Changeset	landed	Same file name, (#578).

Residual <output>/<target> consumer audit

rg over packages/**/src, examples/**, scripts/**, docs/**, website/docs/**, README.md, .github/workflows: no join(<root>, target.name), artifact/<host>, artifact/plugin, <root>/<host> probing, or 'plugin' target literal in production code. The remaining 'plugin' literals are host CLI subcommands (claude plugin …, codex plugin …), manifest document names, config.plugin, the install receipt field, and the Claude marketplace key. Two stale doc comments (src/test/packed.ts, src/routes/graph.ts) were corrected in this PR; dated plans/audits under docs/superpowers/** and docs/audits/** keep their historical per-host paths. #588's new prepack test (merged from main) asserted the pre-composite host-packs/cursor/runtime/mcp/server.js; it now asserts host-packs/runtime/mcp/server.js.

#592 boundary audit

Audited against the architecture note: every place a target or projection name reaches runtime or application identity, session/state namespaces, the manifest, or generated code that branches on host name.

Fixed in this PR (cheap: rename, scope, or separate context):

#	Site	Was	Now
F1	mcp-server-runtime.ts (createGeneratedRouteMcpServer)	lineageHostFor(options.events.target) read the composite identity as a LineageHost for tool-call lineage when the MCP client did not name itself.	The entry bakes hosts — the selected hosts whose MCP documents list that server, i.e. the hosts that can have launched it — beside allowedTargets; the fallback assumes the one host when exactly one can, else undefined. GeneratedEventRuntimeBinding.target removed. Three cases in tests/mcp-server-runtime.test.ts.
F2	build/entry-shell.ts, adapters/hook-contract.ts, src/test/installed.ts	Event endpoint id was <epoch>:<selection identity>:<root> in the generated entry (EVENT_TARGET) and every hook wrapper (artifactTarget); the selection had become runtime identity.	<epoch>:<root> on both sides; GeneratedRouteMcpEntryOptions.target removed; the invoking host still travels on each request and is checked against allowedTargets.
F3	build/entries.ts (planCompiledMcpEntries, planMcpEntriesSurface)	targets ?? [options.target] used the composite identity as the host list when the selection was omitted.	targets required.
F6	website/docs/{en,zh}/reference/runtime-environment.mdx, tests/generated-route-server.test.ts	AGENT_BUNDLE_HOOK_HOST documented as read by generated wrappers; dead env keys in fixtures.	Row and keys removed.
F9	rstest/browser.ts, rstest/browser-setup-module.ts, test/browser-registry.ts	The browser-app pool registered each compiled MCP App with the selection identity (claude+codex+portable) as its target, which mountBrowserApp used as the preview profile and the McpAppBinding.target the page sees (CI's examples/mcp-app suite caught it).	Apps compile once for the whole selection; the registry's target is the host the app mounts as (the target override, or its first declared target the project selects). tests/test-browser-rstest.test.ts covers a two-host selection.
F10	build/compose.ts, build/validate-artifact.ts, install/surface.ts, config/validate.ts, api.ts, build/pack-inventory.ts, adapters/registry.ts	The composite install surface (INSTALL.md, install.mjs) and its AB6023/AB6024 requirement, the AB4106 refusal, and validate/build --host-validation decided "built-in host" by name, so an advanced registry's own adapter named portable shipped instructions it never asked for (Codex review P2), could share a root, and was held to the shipped host's validator; the pack inventory re-derived the surface from manifest names.	TargetRegistry.builtInHost()/builtInHosts() (and the optional NormalizationTargetRegistry.builtInHost?) judge the shipped adapters by identity; compose, artifact validation, AB4106, and host validation use them; the pack inventory expects exactly the manifested files (every emitted file is manifested and AB6023/AB6024 already judged the surface). tests/build-compose.test.ts builds a custom portable beside the shipped hosts: no surface, no AB6023/AB6024, AB4106 beside Claude, no host-validation report alone.

Not a leak (checked): application identity in agent-bundle.manifest.json is project.packageName/packageVersion with targets[] per host (no composite string); the composite identity on compiled apps/bins/scripts is report metadata (build --json, inspect --bundler), not module contents or env; AB4102 keys per host for bookkeeping only; hooks/index.json target is the host name; install receipts iterate host names; dev services key targetDigests by host name; runtime/plugin-root.ts and state/* take no target input.

Listed, not changed in W1 (each would widen the PR):

#	Site	What	Why it stays
F4	adapters/claude.ts:3097, codex.ts:1118, cursor.ts:578 (selected = model.targets.map(…) → hookWrapperPath, folderDiscoveryShadowed)	A host projection's output (wrapper file names, empty shield documents) depends on which other hosts were selected — the Projection IR is a function of the selection.	The note allows "host planners composing directly into filesystem entries" as the migration step. Removing it means passing composite context into TargetAdapter.plan explicitly or moving wrapper naming and the shadow rule into assembly — S3/S10.
F5	dev/artifacts/projection-digest.ts:10-19, eval/artifact.ts:45	Per-host digests salt the content hash with the host name, so identical bytes yield N distinct digests.	Values are persisted (EpochRecord.targetDigests, eval external-binding cache key, trial gates in eval/harness.ts, claude-harness.ts, codex-harness.ts, playground services); changing the hash changes stored formats — S9/S10.
F7	adapters/hook-contract.ts:758,782; mcp-server-runtime.ts:876,894	Host-name gates (target !== 'claude' && …, lineageHostFor, host === 'cursor' && is_background_agent) where lineage.subagent-events capability rows exist in every capability table.	Pre-existing on main, not added here; replacing name checks with capability state needs that state baked into wrapper/binding at build time — #592 (3), S9.
F8a	build/compose.ts:208 compositeNoticeDelivery	Capability resolution (intersection of host advertisements) performed during assembly; every host's wrappers get the intersection.	Forced by the single shared MCP entry and hook worker; belongs between Application IR and projection — S9.
F8b	build/compose.ts:255 installSurfaceEntries	Distribution metadata composed in assembly.	Acceptable per #592 §12; S5.

Follow-ups

• S3 — AB7001 rewording per D2; uninstall; dev services' relocation-awareness beyond "root = epoch"; eval Codex home layout; F4 (pass composite context into TargetAdapter.plan or move wrapper naming / the shadow rule into assembly).
• S4 — npm root = plugin root untouched here; feat(build): hold the package build's dist bundles to AB6005 #588's AB6005 package-build scan is merged in and AB6005: also refuse bare createRequire/require/import.meta.resolve loads in compiled modules #591 extends it. The artifact manifest records target names, not adapter identity; consumers that only have the manifest (install, doctor, the packed harness) still key on names — record the built-in projection identity in the manifest (S6).
• S5 — per-host source-type rendering and distribution forms; F8b.
• S9/S10 — F5 (content-only digests), F7 (capability state over host-name gates), F8a (capability resolution before assembly); union-wired runtime with per-host wrapper advertisements; per-host views (AB4104 / acceptance 9).
• Codex host-validation lane does not follow manifest hooks/mcpServers pointers while the Cursor lane does; fine while the build writes the constants, flag for the wave that opens hand-authored Codex roots.
• compose.ts sameBytes compares copy entries by source path, not content (conservative AB4103 false positive needs two hosts emitting one path from different sources with identical bytes).
• Hygiene: one reachesSelection helper for the four "targets reach the selection" predicates (build.ts, entries.ts, mcp-apps.ts, inspect-bundler.ts); selectedTargetNames could reuse sortedProjections; isSkillHost ≡ isBuiltInHost.

Gate

On 511464dcb (merged with origin/main cfdaecafd — #599's docsite gates included): pnpm install --frozen-lockfile && pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit (3912 passed), pnpm check:release, pnpm docs:site:build (locale drift 0 failures, diagnostics coverage, 0 broken links / 28079 anchors, language parity), plus the integration files the review commits touch (build-compose, composite-rules, generated-route-server, prepack, test-browser-rstest) and examples/mcp-app's test:browser-app suite locally. The full pnpm test:integration:run (1116 passed) ran on df35c1349; CI runs it again on the tip. After gh pr update-branch brought in #603 (323dc9bff): pnpm install --frozen-lockfile && pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit (3945 passed). On the pass-4 fix (064a74c2d, 1b770a4f4 — the first push missed ValidateOptions.root, caught by CI's typecheck): pnpm typecheck && pnpm lint, build-compose.test.ts in the integration pool, and check-diagnostics-coverage. CI's integration-1 shard then caught artifact-validator.test.ts's pre-existing expectation that a custom adapter named portable owes AB6023/AB6024 (the name-keyed rule F10 replaced); ac2e92c1f asserts no diagnostics, and the full pnpm test:integration:run (1122 passed) ran locally on that tip.

Self-review

Reviewer: generalPurpose subagent on GPT-5.6 Sol (the change-risk-reviewer needs the TraceDecay daemon, which is intentionally stopped), asked for concrete merge risks only against the diff vs origin/main. Four passes.

Pass 1 (tip f9f61afd5):

1. Medium — mcp-server-runtime.ts: the lineage fallback infers the root's cardinality from events.allowedTargets, which is server-scoped, so a Claude-only server in a Claude+Codex root falls back to Claude. Dismissed as correct behaviour, comment and test names made precise (df35c1349). allowedTargets = server.targets ∩ selected is exactly the set of hosts whose MCP documents list that server — each adapter writes only servers whose targets include its host (isSelected(server.targets) in claude.ts, codex.ts, cursor.ts, portable.ts) — so those are the hosts that can have spawned the process; a Claude-only server is launched only by Claude, and assuming Claude when the MCP client does not name itself is right. "Composite root ⇒ no fallback" would drop correct lineage for that case. The reviewer verified the adapter gates and agreed in pass 2.
2. Low — AB7001 changed its trigger (no <from>/<host> lookup) but has no entry in docs/diagnostics.md. Fixed (df35c1349): the AB700x family row names AB7001 and the composite-root trigger (there is no per-code AB700x table on main either; the family row is the documented form for that range).

Reviewer noted as checked with no issue: endpoint-id derivation parity across the generated entry, hook wrappers, and the installed harness; planCompiledMcpEntries callers; the dead skill branch in AB4105; changeset package/API coverage; en/zh parity; added-module reachability.

Pass 2 (tip df35c1349): no concrete merge risks; lineage disposition confirmed against the adapter code; AB7001 row confirmed.

Codex review bot (two threads on df35c1349, both answered in-thread):

1. P1 — entries.ts: every event route was attached to the first generated-route server, so a root whose hosts launch different servers (Claude→a, Codex→b) refused Codex's wrappers at a while b hosted nothing. Fixed (2d49a9bef): eventRuntimeHosting hosts the runtime in the first generated-route server each selected host's own MCP document lists — the pre-composite per-host rule — so both a and b host it, each accepting every host that reaches the runtime through a hosting server; the endpoint is the artifact's alone, so whichever hosting process owns the socket answers every host's wrappers. hosts is carried separately for the lineage fallback (F1).
2. P2 — install/surface.ts: built-in hosts identified by name, not adapter identity. Fixed (2d49a9bef, F10). The pack inventory stays name-based (manifest names only) — listed under S4/S6.

Pass 3 (on 68a154e23, GPT-5.6 Sol, read-only, tests not run): four findings, all fixed in 6558432bd/511464dcb:

1. Medium — config/validate.ts: AB4106 identified built-ins by name, so custom adapters named portable/cursor bypassed the advanced-registry refusal. Fixed: NormalizationTargetRegistry.builtInHost? (implemented by TargetRegistry by adapter identity) drives the check; registries that cannot tell still judge by name.
2. Medium — api.ts: validate --host-validation and build --host-validation selected the shipped host validators by target name. Fixed: registry.builtInHosts(...) selects them.
3. Medium — build/pack-inventory.ts: prepack re-derived the install surface from manifest names, so a custom portable adapter's pack would report AB7010. Fixed: the pack expects exactly manifest.files (every emitted file is manifested; AB6023/AB6024 already judged the surface by identity); the existing AB7010 test still fires from the manifest.
4. Low — changeset omitted the agentBundleBrowserRstest() target semantic (mount host; compile over the whole selection). Fixed in the changeset summary.

Checked clean by the reviewer: hosting rule matches AB4817's per-host predicate; two hosting entries use the runtime's owner/standby takeover (events/ipc.ts); no remaining eventHostId; every GeneratedEventRuntimeBinding construction carries hosts; browser overrides validated against project and app targets; added modules have production importers; en/zh event-runtime docs match.

Pass 4 (on 511464dcb, GPT-5.6 Sol, read-only, tests not run; verifying the pass-3 fixes): two findings, both fixed in 064a74c2d (+ 1b770a4f4):

1. Warning — tests/build-compose.test.ts: the identity test called validate() on the project root, which never enters host validation, so the "no report for a custom adapter" assertion was vacuous. Fixed: it validates the built custom root with artifact set (no hostValidation report, no errors), and a custom adapter registered as claude is built with hostValidation: true and a runner spy — no spawn, hostValidation: [].
2. Low — docs/diagnostics.md AB6024 said any cursor/portable selection requires install.mjs, while the validator identity-filters first. Fixed: the row names the shipped cursor/portable adapters by identity.

Checked clean by the reviewer: TargetRegistry is the only production NormalizationTargetRegistry implementer and its identity map covers the four shipped adapters; prepared.registry is the registry the build used; manifest.files carries the install surface (the AB7010 test still fires from it); installSurfaceRequirements keeps its production importer (validate-artifact.ts); the #599 conflict resolution keeps composite paths and passes locale drift and diagnostics coverage; the changeset matches the code.

Earlier self-review of the S1/S2 commits (pre-#569 port) is preserved in the PR history; its findings (per-server allowedTargets, notice-delivery intersection kept, sameBytes by source path, create-agent-bundle bump minor, shield-document docs) are folded into the sections above and the follow-ups.

[changeset-bot]

🦋 Changeset detected

Latest commit: ac2e92c

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

This PR includes changesets to release 2 packages

Name	Type
agent-bundle	Minor
create-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

[pkg-pr-new]

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

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

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/rsc-markdown-stream@578

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

commit: ac2e92c

[ScriptedAlchemy]

Closing as superseded by #569, by the owner's decision (asked directly, 2026-09-05 02:1x UTC): #569 implements the same #555 scope, is CI-green and self-reviewed, and now also carries the plan's "delete rather than shim" directive (no <root>/<host> / <root>/plugin probing). The design points where this PR differs — per-host hooks/<name>.<host>.mjs wrappers plus shield documents instead of one host-detecting Claude+Codex wrapper, Cursor documents under .cursor-plugin/ instead of hooks/hooks-cursor.json, the AB4103 numbering — were not adopted; if any of them should be revisited, open a focused issue against the merged layout.

For the later waves of the plan (npm-source marketplace entries, package-root packaging, local-registry proofs): please rebase them on main once #569 lands. What #569 already provides that those waves can build on: TargetRegistry.root(targets) / ArtifactRootContracts (per-host hookContractFor, mcpRuntimeFor, hostRoot), build/artifact-root.ts (readArtifactTargets, readArtifactRootContracts, hostRootDirectory, hostMcpRuntime), the composition diagnostics AB4104/AB4105/AB4106, the Codex host-validation lane following the manifest's hooks/mcpServers pointers, and the migrated packed/host-install/example test suites.

[ScriptedAlchemy]

Reopened 2026-09-05 04:2x UTC: this PR lands for #555 Wave 1 — see the decision comment on #555. The 02:23 "superseded by #569" comment above no longer applies. Before leaving draft it absorbs #569's AB4106 and consumer/doc changes, adds composite-rules.test.ts, and merges current main.

[ScriptedAlchemy]

Architecture note from #592. The composite-root direction is correct, but two implementation choices in this PR should not become long-term architecture:

• artifactTarget/composite target identity should not become application/runtime identity. targets are host projections; shared compiled routes should retain application identity and carry host/projection context separately.
• Host planners composing directly into filesystem entries is an acceptable migration step, but the intended end state is Application IR -> per-host Projection IR -> common Artifact IR/assembly. Avoid adding new semantics to compose.ts that belong in application normalization or host projection.

Also preserve the #592 constraint that capability requirements, not host-name branching, should become the primary compatibility contract over time.

This does not block the mechanical composite-root work by itself; it flags the boundary to preserve while #555 lands.

[ScriptedAlchemy]

Heads-up from a trial merge of this branch with main now that #588 (d30d9acb6) has landed — three things a textually clean merge will not surface until CI:

1. packages/agent-bundle/tests/prepack.test.ts, test accepts a dependency that only a prebuilt payload module imports: it asserts the packed path host-packs/cursor/runtime/mcp/server.js. Under the composite root that path is host-packs/runtime/mcp/server.js (same change this branch makes for host-packs/INSTALL.md in the shared fixture).
2. packages/agent-bundle/src/build/build.ts: this branch's import line drops deduplicateDiagnostics, but fix(mcp-apps): React plugin on every view, AB4770–AB4772 compile diagnostics, size report, html defaults, reserved-specifier precedence, readable dev output; rsc-agent-runtime AB8206 detail (#572) #585 (on main) still calls it at diagnostics: deepFreeze(deduplicateDiagnostics(compileDiagnostics)).
3. packages/agent-bundle/tests/mcp-apps-compile.test.ts (from fix(mcp-apps): React plugin on every view, AB4770–AB4772 compile diagnostics, size report, html defaults, reserved-specifier precedence, readable dev output; rsc-agent-runtime AB8206 detail (#572) #585) calls compileMcpApps(apps, { cwd, meta, outDir, target: 'portable', ...options }); with this branch's McpAppSelection, selected is required (selected: ['portable']).

The real conflicts (build.ts compile loop, mcp-apps.ts selection types, examples/rsc-agent-runtime/tests/host-artifacts.test.ts) are all this branch vs #585; #588's own hunks merge cleanly.

[ScriptedAlchemy]

Addendum to the audit above, on tip 511464dcb (the PR body's "#592 boundary audit" table is current):

Fixed since f9f61afd5:

• The tool-call lineage fallback now reads a hosts set the entry bakes — the selected hosts whose MCP documents list that server, i.e. the hosts that can have launched it — kept separate from allowedTargets (the hosts whose hook wrappers the runtime it hosts accepts). A Claude-only server hosting a Claude+Codex root's runtime accepts both hosts' wrappers yet assumes Claude for an MCP client that does not name itself; a server two hosts list assumes nothing (mcp-server-runtime.ts, build/entry-shell.ts, build/entries.ts).
• The shared event runtime is hosted per selected host in the first generated-route server that host's own document lists (the per-host rule from before the roots merged), not in "the first generated server of the root"; every hosting process derives the same artifact-only endpoint id and accepts the same allowed set (build/entries.ts eventRuntimeHosting, Codex review P1).
• The browser-app Rstest pool had registered each compiled MCP App with the selection identity (claude+codex+portable) as its target, which mountBrowserApp used as the preview profile and the McpAppBinding.target the page sees. Apps compile once for the whole selection; the registry's target is the host the app mounts as (rstest/browser.ts, rstest/browser-setup-module.ts).
• "Built-in host" is judged by adapter identity, not name, wherever a registry is at hand: the composite install surface and its AB6023/AB6024 requirement, the AB4106 refusal, and validate/build --host-validation (TargetRegistry.builtInHost()/builtInHosts(), optional NormalizationTargetRegistry.builtInHost?). The pack inventory expects exactly the manifested files instead of re-deriving the surface from manifest names.

Listed (unchanged from the table above): the artifact manifest records target names, so consumers that only have the manifest — install, doctor, the packed and installed test harnesses — still key on names; recording the built-in projection identity in the manifest is S6 work.