Install and update Agent Plugin packages from Git

[Aaronontheweb]

Add an end-to-end path to install and update agent plugin packages from public GitHub repositories.

The active PR stack is:

• Adopt plugin-neutral source and state contracts #2160: managed source and durable state
• Add Agent Plugins and Codex package adapters #2161: bounded GitHub acquisition
• Publish managed plugins during external sync #2162: external sync publication
• Add the managed plugin daemon API #2157: daemon API
• Add the managed plugin CLI #2158: operator CLI

Website documentation: netclaw-dev/netclaw-website#119.

Product contract

Agent Plugins 1.0.0 is the primary package contract.
The first release also supports the Codex compatibility manifest at .codex-plugin/plugin.json.

The default auto format selects root plugin.json whenever that file exists.
It selects the Codex compatibility manifest only when no portable root manifest exists.
After format selection, an invalid manifest fails without another format fallback.
Netclaw never merges declarations from separate manifests.

A managed source ID controls configuration, durable paths, receipts, and CLI mutations.
The package manifest name remains separate installed metadata.

CLI and daemon API

Expose this command family:

• netclaw plugin install <owner/repository> [options]
• netclaw plugin list [--json]
• netclaw plugin update <source-id>|--all [--retry-rejected]
• netclaw plugin enable <source-id>
• netclaw plugin disable <source-id>
• netclaw plugin remove <source-id>

A named plugin command syncs only its selected source.
netclaw plugin update --all syncs all plugins without a skill-server fetch.
Keep netclaw skill sync [--retry-rejected] as the complete external skill sync command.
Expose authenticated plugin lifecycle routes under /api/plugins.
Safe RFC 9457 problem details must remain visible in CLI failures.

Package behavior

The portable adapter must:

• require the recognized Agent Plugins 1.0.0 root manifest
• discover skills through immediate children of skills/
• accept portable names with periods
• accept any string version without a SemVer requirement
• skip an invalid skill and continue with valid sibling skills
• report unsupported components without activation

The Codex adapter must preserve its declared skill-root behavior.
Its package rules must not change portable package behavior.

Update and failure rules

• An equal declared version suppresses a new commit.
• A package without a version uses commit identity.
• Explicit tag and commit pins remain fixed.
• A failed candidate keeps the prior complete package active.
• A deterministic rejection persists across restart.
• An explicit retry runs all checks again.
• A scanner security rejection blocks the complete candidate.
• Download failures remain retryable and produce no security alert.
• Each logical resource call uses one complete package revision.

Security and ownership

• The daemon owns validation, reference resolution, acquisition, config writes, and publication.
• The CLI remains a thin presentation client.
• Reuse one actor, scheduler, registry, and inventory refresh path.
• Reject escaped paths, links, special files, unsafe transport syntax, and resource-limit violations.
• Do not execute hooks, filters, submodules, installers, scripts, or package files during import.
• Manifest fields cannot grant Netclaw tool, subagent, shell, MCP, or filesystem authority.
• Managed package files remain protected from agent writes.

Acceptance

• A real CLI process installs a valid portable package and reads one bundled resource through logical skill tools.
• A Codex package fixture proves explicit compatibility support.
• Multi-manifest fixtures prove fixed selection and no fallback after an invalid selected manifest.
• Portable fixtures prove dotted names, non-SemVer versions, invalid-skill isolation, and unsupported-component diagnostics.
• Invalid source values fail before config persistence.
• Update tests prove version suppression, commit updates, fixed pins, durable rejection, explicit retry, and prior-package recovery.
• Interleaving tests prove one actor pass and one complete inventory refresh.
• CLI tests prove JSON output, safe problem details, confirmation, and stable exit codes.
• Run all affected tests, repository quality checks, native smoke checks, and required skill evals.

This scope excludes marketplaces, private Git credentials, plugin subagents, MCP activation, hooks, LSP configuration, and host execution.

Format extensions remain in #2135.

[Aaronontheweb]

Agent Plugins verification added two contract details:

• Netclaw ignores data for extension namespaces that it does not implement.
• A valid portable package can contain zero supported components.
• The sync result reports excluded components and zero supported skills.

These rules follow the authoritative Agent Plugins 1.0.0 text.

[Aaronontheweb]

Marketplace and catalog work now has a separate scope in #2185. The direct Git package stack keeps its current scope. A named plugin update must use a source-scoped pass before the CLI PR can close.