Plugin System Overview

Document ID: PLG-001
File Path: docs/08-plugin-sdk/overview.md
Version: 1.0.0
Status: Draft
Owner: AI Platform Team
Last Updated: 2026-06-27

1. Purpose

This document specifies the plugin system of the Wovyr AI Platform — the Plugin SDK developers use to build extensions and the Plugin Engine service that installs, governs, and loads them.

The plugin system is what makes the platform extensible without forking or recompiling it: tools, providers, memory backends, policies, and workflow activities all arrive as plugins.

2. Scope

The plugin system is responsible for:

An SDK + manifest format for authoring capabilities
Packaging, signing, and publishing plugins
Installing plugins: signature verification, dependency resolution, compatibility checks
Registering capabilities with their host subsystems
Lifecycle: enable, disable, upgrade, rollback, uninstall
Permission grants and consent
Isolated loading/execution of plugin code
Marketplace distribution and discovery

It is not responsible for:

Executing tool logic — that is the Tool Runtime
Defining the tool model — see Tool Framework
Provider inference — see LLM Gateway

3. Plugin Engine in the Platform

 Marketplace / Registry
        │  publish / pull
        ▼
   Plugin Engine ──► verify + resolve + register
        │
        ├──► Tool Runtime      (tool capabilities)
        ├──► LLM Gateway       (provider capabilities)
        ├──► Memory Engine     (memory_backend capabilities)
        ├──► Policy Engine      (policy capabilities)
        └──► Workflow Engine    (workflow_activity capabilities)
        │
        └── plugin.* events ──► Event Bus

The Plugin Engine is the control plane for extensions: it owns the catalog of installed plugins and routes each capability to the subsystem that hosts it. See C4 Container §4.7.

4. Anatomy of a Plugin

my-plugin/
├── plugin.yaml          # manifest: identity, capabilities, permissions, compat
├── capabilities/        # one or more capability implementations
│   ├── tools/
│   ├── providers/
│   └── activities/
├── artifacts/           # compiled wasm / binaries / images
├── LICENSE
├── README.md
└── SIGNATURE            # detached signature + provenance

The manifest is the contract; the Plugin API defines it in full. Tool capabilities follow the Tool Framework package structure.

5. Core Responsibilities

5.1 Authoring (SDK)

The Plugin SDK provides traits, a manifest schema, codegen, and a CLI (wovyr plugin new|build|sign|publish) so a developer can scaffold, implement, and package a capability.

5.2 Installation

The Plugin Engine verifies the package signature, resolves dependencies, checks platform-API compatibility, and stages the plugin (see Versioning).

5.3 Registration

Each capability is registered with its host (a tool into the Tool Registry, a provider into the Provider SDK registry, etc.).

5.4 Governance

Plugins request permissions; operators/tenants grant them. The Policy Engine enforces grants at runtime. See Permissions.

5.5 Isolation

Untrusted plugin code runs sandboxed — tool plugins via the Tool Runtime, others via the loading model in Sandbox.

6. Installation Lifecycle

1. Pull package (Marketplace / registry / file)
2. Verify signature + provenance
3. Parse manifest; validate schema
4. Check platform-API compatibility (semver range)
5. Resolve plugin dependencies
6. Present requested permissions for grant/consent
7. Stage artifacts (content-addressed)
8. Register capabilities (disabled)
9. Enable → capabilities become live
10. Emit plugin.installed / plugin.enabled

Failure at any step aborts cleanly with no partially-registered capabilities.

7. Trust Model

Trust class	Source	Default isolation
First-party	Platform team	In-process / native
Verified	Reviewed + signed third-party	Sandboxed (WASM/container)
Community	Marketplace, unreviewed	Sandboxed (gVisor/microVM), restricted permissions

Trust class composes with tenant policy floors, exactly as in Tool Runtime §3 Trust Classification.

8. Deployment Modes

Mode	Description
Embedded	Plugin Engine in the all-in-one dev binary; local plugin dir
Standalone	Dedicated Plugin Engine service (enterprise default)
Air-gapped	Private registry mirror; no public marketplace access

9. Module Organization

service-plugin-engine/
├── api/             # install / enable / disable / upgrade / list
├── registry/        # installed-plugin catalog + capability index
├── verifier/        # signature + provenance verification
├── resolver/        # dependency + compatibility resolution
├── loader/          # capability loading + routing to hosts
├── permissions/     # grant + consent management
├── marketplace/     # registry/marketplace client
├── telemetry/       # plugin.* events, metrics, audit
└── main.rs

sdk-plugin/          # the authoring SDK (separate crate)
├── manifest/
├── traits/
├── codegen/
└── cli/

This corresponds to the engine-plugin crate in the DDD module map.

10. Non-Functional Requirements

Requirement	Target
Install (verify + resolve + register)	< 3 s typical
Enable/disable	< 200 ms (no restart)
Capability load (cold)	host-dependent (see Tool Runtime)
Compatibility check	< 50 ms
Availability (Plugin Engine)	99.99%

11. Security

All packages are signature- and provenance-verified before install.
Plugins run with least privilege; unrequested access is impossible.
Untrusted plugins are sandboxed and may be quarantined instantly.
Install/enable/disable are audited and emit plugin.* events.

See Permissions, Sandbox, and the planned 13-security/ section.

12. Observability

The Plugin Engine emits plugin.installed, plugin.enabled, plugin.disabled, plugin.upgraded, and plugin.published events to the Event Bus, plus metrics (install success rate, active plugins, capability load latency) and audit records.

13. Dependencies

15. Future Enhancements

Cross-language plugins via the WASM component model
Capability hot-reload with zero in-flight disruption
Plugin dependency lockfiles and reproducible installs
AI-assisted plugin scaffolding and review
Revenue-share monetization in the marketplace

16. Revision History

Version	Date	Description
1.0.0	2026-06-27	Initial Plugin System Overview