Plugin Nester

Plugin Nester bundles, installs, and manages community or custom Agent Zero plugins as nested children. It keeps the nester's management state separate from each child plugin so a child remains an ordinary Agent Zero plugin.

Sibling link layout

The nester itself lives at usr/plugins/plugin_nester/. Managed children are installed as sibling directories under usr/plugins/, for example:

usr/plugins/
├── plugin_nester/
│   └── nested/
│       └── <child>/
├── fixture_child/
└── another_plugin/

usr/plugins/plugin_nester/nested/<child>/
usr/plugins/<child> -> usr/plugins/plugin_nester/nested/<child>/

Do not place a child directly at usr/plugins/plugin_nester/<child>/, because that discovery-root path is reserved for the nester itself. The vendor path usr/plugins/plugin_nester/nested/<child>/ is the permitted managed storage location. The public usr/plugins/<child> entry is always a managed sibling symlink owned by the nester (or a Windows directory junction) pointing to that vendor path, never an independent checkout. This layout lets Agent Zero discover each child by its own plugin.yaml and makes uninstall cleanup bounded to nester-owned links, vendor directories, and metadata.

Supported sources

When adding a child, provide one of these sources:

1. A Plugin Hub key from the configured Plugin Index (hub_index_url).
2. A direct Git URL over HTTPS or SSH for a repository containing the plugin at its root.
3. A remote HTTPS ZIP URL (a remote ZIP URL over HTTPS) that points to a downloadable plugin archive.

Plugin Nester does not accept a local ZIP upload. Local archives should be published to a reachable, reviewable source first. The nester checks the source's root plugin.yaml and keeps the child's manifest as the source of truth for its name and version.

Scanning and updates

Scanning is opt-in. When requested, the bundled scanner can inspect a Git source; its current limitation is Git-only scanning, so a remote ZIP URL can be installed without that scanner review. A requested scan is an install gate: if the scan fails, installation or update is blocked and the child is not linked. If scanning is turned off, installation records an explicit unscanned warning instead of treating the child as scan-approved. Treat every third-party plugin as untrusted code and review it before enabling it.

The update policy is set per nester installation:

• never keeps the installed revision until a user starts an update.
• notify reports an available update and waits for approval (the default).
• auto applies an available update after the configured checks pass.

Prefer immutable refs, such as a full Git commit SHA or a content-addressed archive, when reproducibility matters. A moving branch or tag can change after it was first installed and is not an immutable ref.

The manager runs selected children independently and shows the active child, completed count, and per-child result. While an install is in progress, the primary action changes to Stop nesting. Stopping is cooperative: the active Git/ZIP transaction is cancelled at a safe boundary, staged material is rolled back, and children that have not started remain selected for retry. A Git clone also has a bounded timeout, so a stalled remote cannot leave the manager waiting forever.

Main Plugins view and scoped availability

Nested children appear in a dedicated Nested children shelf inside the main Agent Zero Plugins modal. The shelf keeps each child's published thumbnail, title, key, and health together instead of duplicating children among unrelated custom plugins. Manage is the single shelf entry point to this manager. If the optional nester runtime is unavailable, the normal Plugins list continues to work without the shelf.

Before nesting a selection, the manager asks for a destination: Nested globally, an existing or new Project bundle, or an existing or new Agent profile bundle. A child is still checked out once under nested/; the destination is a manifest assignment, so the same child can appear in several bundles without scattered copies or duplicate links. The manager's Bundles index groups children by destination, and each child's Manage panel shows its bundle memberships alongside its ordinary availability switches.

Removing a child from one bundle removes that assignment only when another bundle still owns it. Removing its last assignment removes the managed child and deletes its manifest entry. This keeps project/profile bundles independent while ensuring a removed child is fully absent from the nester inventory. The global, Agent profile, and Project switches remain the same activation rules used by Agent Zero's standard plugin Switch panel; bundle membership is the durable organization layer and activation is the runtime availability layer.

Older removed records are ignored by the inventory and do not render as children or bundle members. New removals delete the child from the inventory.

Uninstall and cleanup

Uninstalling through the nester removes the managed sibling symlink (or Windows directory junction), its vendor directory, nester-owned metadata, and its child-specific temporary files. It does not delete unrelated files, alter Agent Zero core files, or remove user data outside the managed child. Review a child README for any external resources that need manual cleanup before uninstalling.

Publishing Plugin Nester

The runtime plugin.yaml belongs at the root of a standalone publication repository, alongside README.md, LICENSE, and the plugin's helpers/ and other runtime directories. Publishing means copying the contents of usr/plugins/plugin_nester/ into that standalone publication repository root; do not copy the enclosing usr/plugins/ tree or the whole Agent Zero repository. Keep the runtime manifest and publication metadata separate: a Plugin Index entry is an index.yaml file in the index repository, not a replacement for plugin.yaml.

Before sharing, remove local state, secrets, generated caches, and machine paths. Verify the final repository URL and the copied root layout before submitting an index pull request; publication is a later, external action and is not performed by this local plugin.