feat(plugins): plugin composability P1 — composition API, compose engine, controller - #616
Draft
ilackarms wants to merge 9 commits into
Draft
feat(plugins): plugin composability P1 — composition API, compose engine, controller#616ilackarms wants to merge 9 commits into
ilackarms wants to merge 9 commits into
Conversation
…ce, ResolvedComponents pin set
…th provenance report
Aligns with the BYO composition contract (enterprise #1265) and the Agent Skills spec, which requires skills/<name>/ to match the frontmatter name. Missing/invalid declared names and cross-ref declared-name collisions are terminal ComponentInvalid; the status pin keeps the registry ref identity.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
P1 of plugin composability — makes
Plugina composable bundle, per the design in #615 (design-docs/PLUGIN_COMPOSABILITY_SPIKE.md).Motivation: today a Plugin is a pointer at a single git repo, materialized 1:1. Product wants plugins declaratively composed from registry artifacts (Skills, MCP servers, Prompts) overlaid on an optional base source, compiled deterministically into one flattened bundle — while the API represents the plugin as a collection of reusable objects.
What changed:
ComponentRef{Namespace,Name,Tag}(the holding field determines the kind — no kind defaulting/mismatch surface);PluginSpec.Sourcebecomes optional; newSkills/MCPServers/Commands/Instructionscomposition refs;PluginStatus.ResolvedComponentsrecords the controller's pin of every ref (Skill → commit; inline kinds → spec content hash). Validation requires source and/or composition, rejects duplicate names per field;Plugin.ResolveRefsexistence-checks refs at admission.internal/registry/plugins/compose): pure, byte-deterministic flatten. Skills →skills/<name>/**(whole-directory overlay-wins), commands →commands/<name>.md, MCP servers → keyed.mcp.jsonmerge (overlay replaces same-named entry; unrelated base content preserved), instructions →AGENTS.mdappend. Baseplugin.jsonpasses through untouched; a minimal manifest is generated only for pure compositions. Every replacement is recorded in a provenanceReport. Bundle ceilings apply to the composed result.MCPEntryFromSpecmaps registry MCPServer specs to.mcp.jsonentries (Remote → remote entry; npm/pypi package → stdio entry; OCI package → terminal invalid).ComponentsPending, retryable) vs missing (ComponentMissing, terminal) vs unrepresentable (ComponentInvalid, terminal) — then composes in memory and computes Manifest/Inventory over the composed bundle, so governance sees the true surface. Pin set freezes at spec change (ObservedGeneration gating unchanged).ResolvedComponents, so deployments redeploy exactly when a composed pin set changes (byte-identical material for existing source-only plugins — no hash churn).ErrComposed) — serving just the base URL would silently drop overlays. Serving composed plugins is gated on the git-backed marketplace (tracked in agentregistry-enterprise#1195).Tests: table-driven compose suite (overlay-wins, .mcp.json merge/replace, traversal guard, ceilings, 10× determinism), hermetic controller reconcile tests (pure composition, pending/missing/invalid components, base+overlay inventory), fingerprint material tests, admission/ResolveRefs tests, marketplace skip test.
make verifygreen;make lint0 issues; full unit suite (1388 tests) green.Change Type
/kind feature
Changelog
Additional Notes
Design of record: #615. P2 (consumption:
arctl plugin pull, harness runner compose-at-start) follows separately.