Support agent plugins (Agent Plugins spec v1.0.0)

[hsm207]

This implements the Agent Plugins spec v1.0.0 and closes #1349. An agent plugin bundles a manifest (plugin.json), skills, and MCP server config, and this PR adds a one-command install for such bundles. After a restart the plugin's skills and MCP servers join the session.

fb plugin install https://github.com/google/skills/plugins/cloud/google-cloud-developer

I verified the feature end to end against that plugin: its five skills are served, its MCP server is discovered and routed through the project's existing MCP client, and nothing collides with the user's own skills or servers.

How it works

• Domain model (common/src/plugins/): a Plugin value object, whose manifest is validated per §5, and an InstalledPlugin entity rooted at a client-managed plugins root. The entity shape leaves room for a plugin update flow later.
• Validation: the specification text is authoritative if it conflicts with the official JSON schema (§5.2), so section 5's rules are implemented as a direct rule engine rather than zod transforms. MCP entries reuse the existing MCP config types, and streamable-http maps onto the CLI's http transport.
• Install: fetch the GitHub archive (no git clone), extract to a staging dir, validate before installing, abort on any name conflict with the user's existing skills or servers, then move into the plugins root atomically. Only https://github.com URLs are accepted; anything else is refused before any network or filesystem work.
• Session wiring: plugin skills and MCP servers load after the user's own. Install aborts on conflicts, so nothing is shadowed.

The four spec gaps

• §5.2 never defines "object". I validate the three checks that match the spec's examples (non-null, non-array, plain) and note the assumption at the enforcement site.
• Skill files are read by the existing SDK loader without re-validation. A present-but-invalid skill can currently load as absent, which §7.1 wants reported; flagged inline.
• Env provisioning and ${PLUGIN_ROOT}/${PLUGIN_DATA} expansion (§9.1, §9.2) are not implemented; flagged inline where the spec expects them.
• Remote MCP servers wanting user credentials (OAuth, ADC) cannot connect, exactly as on main today: the existing MCP client has no credential path for remote servers. §7.2.2 rule 5 maps this to a connection failure, never invalid config.

Testing

62 unit tests cover the manifest, skills and MCP policy in common; command, registry and child-process suites cover the cli side. The live verification above also confirmed gitlab URLs are refused cleanly. Automated end-to-end tests through the real binary are a small follow-up: the e2e scaffolding is unusable from a public checkout.

[codebuff-team]

There's clearly a lot of care here — the domain model in common/src/plugins/, the containment/reparse-point tests, the conflict-checking on install, the child-process discovery tests. This is not sloppy work.

But this PR adopts a third-party specification (github.com/agentplugins/agent-plugins-spec) as a first-class Codebuff/Freebuff feature, adds a new CLI verb (fb plugin install), and — most importantly — teaches the CLI to download an arbitrary GitHub tarball and wire its declared MCP servers and skills into a live session. That's a new trust boundary and a new product surface ("we now support an external plugin ecosystem"), not a bug fix or a docs correction. Whether Codebuff should support this spec at all, whether MCP servers from a plugin should be trusted the way ~/.agents/mcp.json is, and how name-conflict/precedence semantics should work (you flag several of these as open questions yourself, e.g. plugin-vs-user precedence in plugin-discovery.ts) are calls for the maintainers to make before any implementation, not decisions a PR should make unilaterally.

Separately, at +4276/-5 across 49 files touching CLI argument parsing, session wiring, MCP config mapping, and a new domain layer, this is far larger than what could be reviewed or hand-ported in one pass even if the direction were agreed on.

If you want this considered, I'd suggest opening an issue/discussion first proposing agent-plugin support as a feature, and if there's interest, land it in much smaller, independently reviewable slices (e.g. manifest parsing and validation alone, with no install/execution path, would be a reasonable first PR).

[hsm207]

Thanks for the review. The trust-boundary point is fair, and the open questions deserve real discussion.

On the process point: the proposal already exists. #1349 has been open since Sep 13, four days before this PR, and the description links it in the first line. I built this PR as a first MVP to make the discussion concrete. Working end to end is what surfaced the open questions: plugin-vs-user precedence, what install-time consent looks like, and the spec gaps listed in the description.

Happy to keep going when a human review picks this up. I can amend here, work through the open questions on #1349, or split manifest parsing into a standalone first PR.