Plugin Runtime Management Protocol

Defines the protocol for dynamic plugin loading, unloading, and discovery

at runtime. Addresses the "Dynamic Loading" gap in the microkernel architecture

by enabling plugins to be loaded and unloaded without restarting the kernel.

Inspired by:

OSGi Dynamic Module System (bundle lifecycle)
Kubernetes Operator pattern (reconciliation loop)
VS Code Extension Host (activation events)

This protocol enables:

Runtime load/unload of plugins without kernel restart
Plugin discovery from registries and local filesystem
Activation events (load plugin only when needed)
Safe unload with dependency awareness

Source: packages/spec/src/kernel/plugin-runtime.zod.ts

TypeScript Usage

import { DynamicLoadRequest, DynamicLoadingConfig, DynamicPluginOperation, DynamicPluginResult, DynamicUnloadRequest, PluginDiscoveryConfig, PluginDiscoverySource, PluginSource } from '@objectstack/spec/kernel';
import type { DynamicLoadRequest, DynamicLoadingConfig, DynamicPluginOperation, DynamicPluginResult, DynamicUnloadRequest, PluginDiscoveryConfig, PluginDiscoverySource, PluginSource } from '@objectstack/spec/kernel';

// Validate data
const result = DynamicLoadRequest.parse(data);

DynamicLoadRequest

Request to dynamically load a plugin at runtime

Properties

Property	Type	Required	Description
pluginId	`string`	✅	Unique plugin identifier
source	`Object`	✅	Plugin source location for dynamic resolution
activationEvents	`Object[]`	optional	Lazy activation triggers; if omitted plugin starts immediately
config	`Record<string, any>`	optional	Runtime configuration overrides
priority	`integer`	✅	Loading priority (lower is higher)
sandbox	`boolean`	✅	Run in an isolated sandbox
timeout	`integer`	✅	Maximum time to complete loading in ms

DynamicLoadingConfig

Dynamic plugin loading subsystem configuration

Properties

Property	Type	Required	Description
enabled	`boolean`	✅	Enable runtime load/unload of plugins
maxDynamicPlugins	`integer`	✅	Upper limit on runtime-loaded plugins
discovery	`Object`	optional	Runtime plugin discovery configuration
defaultSandbox	`boolean`	✅	Sandbox dynamically loaded plugins by default
allowedSources	`Enum<'npm' \| 'local' \| 'url' \| 'registry' \| 'git'>[]`	optional	Restrict which source types are permitted
requireIntegrity	`boolean`	✅	Require integrity hash verification for remote sources
operationTimeout	`integer`	✅	Default timeout for load/unload operations in ms

DynamicPluginOperation

Runtime plugin operation type

Allowed Values

load
unload
reload
enable
disable

DynamicPluginResult

Result of a dynamic plugin operation

Properties

Property	Type	Required	Description
success	`boolean`	✅
operation	`Enum<'load' \| 'unload' \| 'reload' \| 'enable' \| 'disable'>`	✅	Runtime plugin operation type
pluginId	`string`	✅
durationMs	`integer`	optional
version	`string`	optional
error	`Object`	optional
warnings	`string[]`	optional

DynamicUnloadRequest

Request to dynamically unload a plugin at runtime

Properties

Property	Type	Required	Description
pluginId	`string`	✅	Plugin to unload
strategy	`Enum<'graceful' \| 'forceful' \| 'drain'>`	✅	How to handle in-flight work during unload
timeout	`integer`	✅	Maximum time to complete unloading in ms
cleanupCache	`boolean`	✅	Remove cached code and assets after unload
dependentAction	`Enum<'cascade' \| 'warn' \| 'block'>`	✅	How to handle plugins that depend on this one

PluginDiscoveryConfig

Runtime plugin discovery configuration

Properties

Property	Type	Required	Description
enabled	`boolean`	✅
sources	`Object[]`	✅
autoLoad	`boolean`	✅	Automatically load newly discovered plugins
requireApproval	`boolean`	✅	Require admin approval before loading discovered plugins

PluginDiscoverySource

Source for runtime plugin discovery

Properties

Property	Type	Required	Description
type	`Enum<'registry' \| 'npm' \| 'directory' \| 'url'>`	✅	Discovery source type
endpoint	`string`	✅	Registry URL, directory path, or manifest URL
pollInterval	`integer`	✅	How often to re-scan for new plugins (0 = manual)
filter	`Object`	optional

PluginSource

Plugin source location for dynamic resolution

Properties

Property	Type	Required	Description
type	`Enum<'npm' \| 'local' \| 'url' \| 'registry' \| 'git'>`	✅	Plugin source type
location	`string`	✅	Package name, file path, URL, or git repository
version	`string`	optional	Semver version range (e.g., "^1.0.0")
integrity	`string`	optional	Subresource Integrity hash (e.g., "sha384-...")

Plugin Runtime

On this page