Skip to main content

Plugin Packages

Holon plugin packages are the intended packaging abstraction for capability sources. The long-term direction is one Holon-governed install and import surface that can wrap portable skills, capabilities, docs, assets, and adapter hints without forcing users to start from MCP, CLI, or other implementation-lane details.

Today the implemented V1 slice is narrower. It supports runtime-backed registration, import, desktop inventory, discovery, and a small bounded live execution floor for supported lanes. It is not yet a marketplace, remote package feed, uninstall or update system, or broad live plugin or live MCP execution system.

Current-State Summary​

  • /desktop/plugins is a global desktop inventory surface for plugin packages, not a workspace-scoped skill browser.
  • The desktop surface can list existing registered packages, show whether each package is only registered or fully imported, and derive imported skill counts, capability-binding counts, runtime-tool counts, and blocked reasons.
  • The current add or install flow is pasted holon-plugin/v1 JSON only.
  • Search-before-build evidence is now durable: local draft creation requires a valid asset-search-evidence:<uuid> reference, and the runtime records the normalized search decision, candidates, ranking inputs, and justification before drafting.
  • Local trust lifecycle is now enforced for plugin packages: the runtime computes effective trust posture (channel, evidence tier, review state, incident overlay), persists local trust decisions, blocks imports when policy disallows activation, and can hide blocked candidates from default search.
  • Imported package capabilities appear on the normal runtime discovery surfaces beside built-ins, frozen tools, Elegy imports, and other sources.
  • Existing skills remain inspectable through the separate runtime skill and tool discovery surfaces; the plugin page stays package-centric.
  • Desktop observation settings now also expose per-surface readiness diagnostics for the bundled elegy.memory and elegy.planning package executables, including pinned manifest version expectations, receipt-backed published paths when available, launch failures, and operator recovery guidance.
  • Elegy is a premier portable contract source inside packages, especially for embedded skill-definition-v2 entries, but Elegy is not itself the plugin inventory or package registry.

Direction​

  • Keep the primary UX centered on capabilities and tools rather than on implementation lanes such as MCP, CLI, or adapter internals.
  • Use plugin packages as the Holon-managed wrapper around portable contract content.
  • Let one package group skill definitions, capability bindings, docs, assets, and adapter hints under one package identity.
  • Preserve clear authority boundaries: package contracts may travel, but runtime execution, approvals, secrets, and evidence stay local to Holon. Current V1 live execution is narrow: only supported cli and subprocess lanes execute through a runtime-owned subprocess path with validation and approval gates. MCP and generic plugin lanes remain blocked for live execution. Catalog and discovery surfaces are broader than live execution.

Accepted future marketplace boundaries are documented separately in Plugin Marketplace Boundaries so this page can stay focused on current V1 behavior.

Authority Split​

  • Elegy owns portable contract shapes: skills, capabilities, profiles, package metadata, and optional MCP projection metadata.
  • Holon owns local registration, package inventory, workspace policy, approvals, secrets, bridge sessions, runtime execution, evidence, and UI.
  • A plugin package is the Holon-governed wrapper and import surface around those portable contracts.
  • Plugin manifests do not carry Holon workspace ids, approval state, secret values, runtime sessions, adapter handles, or local trust decisions.

Manifest Shape​

Holon accepts package manifests with schemaVersion: holon-plugin/v1.

The manifest is a Holon wrapper around portable component contracts:

  • identity.packageId: stable local package id used to derive plugin-package:<packageId>.
  • metadata: package-level display and description metadata.
  • components.skillDefinitions: embedded Elegy skill-definition-v2 definitions imported into Holon skill state.
  • components.capabilityBindings: optional per-capability lane and projection hints.
  • components.instructionSkills, components.mcp, components.docs, and components.assets: optional package resources that remain non-authoritative in V1.

components.capabilityBindings is the current V1 manifest field and maps to runtime CapabilityBindingRecord state. A bounded runtime-only dual-read translation to a holon-plugin/v2-core-shaped import form now exists for import normalization and diagnostics, but current register/store/protocol truth remains the V1 plugin-package/* surface until a later implementation slice lands.

All component paths must be relative package paths. Rooted paths, parent traversal, empty segments, Windows drive syntax, duplicate component ids, and unresolved capability-binding refs are rejected during registration or import.

Normalization Flow​

The user-facing surface remains capabilities and tools. The runtime source may be MCP, CLI, plugin, API, built-in, or frozen-tool internally, but the primary UX does not require users to choose between those implementation types.

Protocol Surface​

Plugin package state is managed through five runtime methods:

  • plugin-package/register: validates and upserts one inert package manifest.
  • plugin-package/read: reads one registered package record.
  • plugin-package/list: lists registered package records.
  • plugin-package/search: searches installed packages, registered-but-not-imported local drafts, and configured local static registries with normalized candidate status, source provenance, deterministic ranking inputs, and a reduced remote-query shape.
  • plugin-package/search-evidence/create: records durable search evidence for a prior package search, including the normalized query, candidates, selected outcome, rejected summaries, and justification, then persists it for later draft creation.
  • plugin-package/draft-create: creates a local holon-plugin/v2-core draft package from inert asset inputs after validating a matching asset-search-evidence:<uuid> reference. The current draft path does not create executable adapter-binding assets.
  • plugin-package/import: imports registered package skill definitions and capability bindings into normalized runtime state.
  • plugin-package/trust/evaluate: resolves the effective local trust policy for a package.
  • plugin-package/trust-decision/apply: applies and persists one local trust decision for a package.
  • plugin-package/trust-decision/list: lists persisted local trust decisions for a package.

Imports are idempotent by package-derived source id and skill source key. Re-importing an unchanged package reuses the existing normalized records, while re-importing after a package update refreshes the affected skill definitions and capability bindings and removes stale imported records that no longer exist in the manifest.

The current plugin-package/search slice is intentionally local-only. It uses existing registered package state to distinguish imported packages from registered local drafts, and it can also read file-backed static registry metadata from configured local-registry skill sources. Remote fetch and authenticated registry search remain deferred, but asset_search_evidence is now enforced for local draft creation through the durable search-evidence create method.

Local trust policy now feeds both import and search behavior:

  • Import is fail-closed when effective trust policy marks the package blocked or otherwise disallows activation.
  • Search returns blocked candidates only when include_blocked=true; otherwise quarantined or blocklisted packages remain hidden.
  • Overlay precedence is deterministic (retroactive-disable > blocklisted > quarantined > yanked) and supersedes base channel posture.
  • verified-publisher posture is not treated as equivalent to audited or official channels.
  • Tier-3 and Tier-4 assets remain non-activatable in the current V1 runtime slice.

The current desktop route builds on that runtime surface with five bridge commands:

  • desktop_runtime_plugin_package_list
  • desktop_runtime_plugin_package_add
  • desktop_runtime_plugin_package_import
  • desktop_runtime_plugin_registry_source_list
  • desktop_runtime_plugin_registry_source_add

Registry-source configuration remains local-only in this slice. The desktop marketplace can list and upsert local-registry source descriptors that carry file or directory discovery input for static registry-index.json metadata on local filesystems. It does not yet expose source deletion, authenticated remote registry credentials, remote search transport, or artifact download and update flows.

Discovery And Execution​

Plugin package capabilities appear beside built-ins, frozen tools, Elegy imports, adapter tools, and MCP sources in:

  • runtime-tool/list for low-context runtime tool listing.
  • runtime-capability/discover for context-aware discovery and blocking reasons.

V1 lane behavior is intentionally narrow:

LaneCatalogDiscoveryDry-run projectionLive call
api adapterYesYesYesExisting bounded API adapter behavior
mcpYesYesYesFail-closed
pluginYesYesYesFail-closed
cli / subprocessYesYesYesSupported for bounded runtime-owned subprocess execution when the lane has a live executor and passes runtime validation, policy, and approval gates
file_formatYesYesYesSupported for bounded pilot adapter execution when the lane is allowed by fail-closed piloting policy
built-inYesYesN/AExisting built-in behavior
frozen-toolYesYesN/AExisting bounded frozen-tool behavior

runtime-tool/call remains fail-closed for plugin package lanes that do not have a supported live executor. The current live floor is still intentionally small: MCP and generic plugin lanes remain blocked, while supported cli or subprocess lanes can execute only through the runtime-owned subprocess path with validated machine-output contracts, runtime policy and approval checks, and advisory sandbox signaling rather than claimed OS-level confinement. Workflow dry-run can still select and prove capabilities through declared schemas and projection metadata even when live execution is blocked.

Piloting Adapter Surface​

Holon now owns piloting end to end through the native holon.piloting core plugin and the pilot-adapter asset family.

  • The native holon.piloting core plugin is seeded by default at runtime initialization and appears in plugin inventory and capability catalog as a built-in provider source.
  • Eight built-in piloting tools are projected into runtime-tool/list and runtime-capability/discover: search adapters, inspect adapter, discover targets, read target, readiness, simulate, plan, and execute.
  • The pilot-adapter asset kind is accepted in holon-plugin/v2-core manifests for distributing pilot adapter packages.
  • The bundled piloting.blender.reference package is a reference pilot adapter demonstrating file_format lane support with dry-run execute.
  • Fail-closed execute policy: only api and file_format lanes are allowed for live pilot execution in this phase. All other lanes (vision, raw_input, browser, desktop_semantic) are blocked at readiness time.
  • The PilotAdapterRegistry is in-memory only; no new persisted SQLite table is added in this phase.
  • Holon owns all piloting registration, registry, execution, readiness, and evidence. No Elegy contract shapes or fixtures participate in the Holon piloting protocol.

Current Limits And Non-Goals​

  • No remote registry, marketplace, or feed browsing exists yet.
  • No file picker, bundle installer, uninstall, disable, update, or signing workflow exists yet.
  • The desktop plugin page is package-centric; it does not replace the full runtime skill catalog.
  • Package inventory is global desktop state. Workspace or provider-specific readiness still belongs on the normal runtime discovery surfaces.
  • mcp and generic plugin lanes remain catalog, discovery, and dry-run only. They are not claimed as supported live execution lanes in V1.
  • Supported cli and subprocess lanes still depend on a runtime-owned live executor, declared machine-output contracts, external executable availability, and runtime policy or approval checks.
  • Current subprocess sandbox metadata is advisory signaling, not a claimed OS-level filesystem or network sandbox.
  • The current bootstrap receipt flow publishes elegy-memory as a supported wrapper surface, but does not yet publish an elegy-planning wrapper surface. Desktop diagnostics expose that mismatch explicitly instead of treating elegy.planning as launch-ready whenever the package is present in inventory.