---
title: Plugin Runtime
description: Plugin Runtime protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# 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

<Callout type="info">
**Source:** `packages/spec/src/kernel/plugin-runtime.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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-...") |


---

