vxaboveground/overlord
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Remove WASM plugin support

Browse Source
This commit is contained in:
KingKDot
2026-08-18 21:41:28 -05:00
parent 4b8de29d32
commit 7800c24c65
42 changed files with 125 additions and 1773 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/docs/README.md
+1 -2
View File
@@ -6,8 +6,7 @@ These docs are split from `plugins/PLUGINS.md` so each plugin area has a smaller
|------|--------|
| [bundle-format.md](bundle-format.md) | Bundle layout, manifest fields, nav entries, TypeScript entrypoints. |
| [server-side-plugins.md](server-side-plugins.md) | Server-only plugin runtime, RPC/SSE, persistent data, build hooks, build UI settings/actions. |
| [wasm-plugins.md](wasm-plugins.md) | Plugin 2.0 WASM runtime and agent-side host bridges. |
| [install-and-manage.md](install-and-manage.md) | Uploading, opening, enabling, auto-load, Plugin Manager behavior. |
| [samples.md](samples.md) | Included sample plugins and what each demonstrates. |
| [legacy-native-plugins.md](legacy-native-plugins.md) | Legacy native plugins, direct OS/API use, native ABI, build scripts, static Linux shim. |
| [legacy-native-plugins.md](legacy-native-plugins.md) | Native plugins, direct OS/API use, native ABI, build scripts, static Linux shim. |
| [signing.md](signing.md) | Ed25519 plugin signing and trusted key management. |
plugins/docs/bundle-format.md
+3 -5
View File
@@ -10,7 +10,7 @@ Plugin bundles are zip files named after the plugin ID. `config.json` must be at
<pluginId>.html
<pluginId>.css
<pluginId>.js optional when src/ui.ts exists
<pluginId>.wasm optional agent-side WASM module
<pluginId>-<os>-<arch>.* optional native agent library
server.js optional server runtime
src/
ui.ts compiled to assets/<pluginId>.js
@@ -25,8 +25,7 @@ After extraction the server stores assets under `Overlord-Server/plugins/<plugin
```json
{
"apiVersion": 2,
"runtime": "wasm",
"wasm": "sample-wasm.wasm"
"runtime": "server"
}
```
@@ -35,8 +34,7 @@ Use:
| Runtime | Use case |
|---------|----------|
| `server` | Server-only extension, build plugin, dashboard plugin, RPC-backed plugin. |
| `wasm` | Sandboxed agent-side Plugin 2.0 module. |
| `native` or omitted v1 fields | Legacy shared-library agent plugin. |
| `native` or omitted v1 fields | Shared-library agent plugin. |
Server-only plugins are not sent to clients and do not use auto-load.
plugins/docs/install-and-manage.md
+3 -5
View File
@@ -36,8 +36,7 @@ Navbar plugins appear in the Plugin Apps group when enabled and configured with:
| Plugin kind | Manager behavior |
|-------------|------------------|
| Server-only (`runtime: "server"`) | Shown as a server extension. Auto-load controls are hidden. It is not sent to clients. |
| WASM (`runtime: "wasm"`) | Shows declared needs and approval state. Can be loaded on compatible clients after needs approval. |
| Legacy native | Shows native binary/runtime compatibility. Requires matching OS/architecture binary. |
| Native (`runtime: "native"`) | Shows native binary/runtime compatibility. Requires a matching OS/architecture binary. |
## Auto-Load
@@ -50,16 +49,15 @@ Auto-load notes:
| Rule | Detail |
|------|--------|
| Enabled flag | Disabled plugins are never auto-loaded. |
| WASM needs | WASM plugins with unapproved needs are blocked. |
| Persistence | Auto-load state is saved in `.plugin-state.json`. |
| Platform matching | WASM is universal; legacy native requires a matching binary. |
| Platform matching | Native plugins require a matching binary. |
| Bundle default | `autoLoadByDefault: true` enables auto-load only after the plugin passes trusted enablement or an administrator explicitly confirms enablement. |
## Useful APIs
| Endpoint | Purpose |
|----------|---------|
| `GET /api/plugins` | List installed plugins, runtime, needs, enabled state, server state, and auto-load state. |
| `GET /api/plugins` | List installed plugins, runtime, enabled state, server state, and auto-load state. |
| `POST /api/plugins/<id>/autoload` | Configure auto-load for client-side plugins. Server-only plugins reject this. |
| `POST /api/plugins/<id>/rpc` | Call a server-side plugin RPC method. |
| `GET /api/plugins/<id>/stream` | Subscribe to server-side plugin broadcasts. |
plugins/docs/legacy-native-plugins.md
+7 -9
View File
@@ -1,12 +1,12 @@
# Legacy Native Plugins
# Native Plugins
Legacy native v1 plugins run as shared libraries inside the agent. They are still supported and still useful when you need capabilities that the WASM runtime intentionally does not expose.
Native plugins run as shared libraries inside the agent.
Use legacy native plugins when you need direct OS APIs, native libraries, custom process/thread behavior, platform-specific integrations, or code that cannot reasonably be compiled to the Plugin 2.0 WASM ABI.
Use native plugins when you need direct OS APIs, native libraries, custom process/thread behavior, or platform-specific integrations.
Native plugins run with the same privileges as the agent. They are not sandboxed.
## What Legacy Plugins Can Do
## What Native Plugins Can Do
| Capability | Notes |
|------------|-------|
@@ -16,11 +16,9 @@ Native plugins run with the same privileges as the agent. They are not sandboxed
| Emit plugin events | Send events back to the UI/server through the host callback. |
| Receive UI/server commands | Handle `PluginOnEvent` calls from plugin UI actions or server-side routing. |
WASM Plugin 2.0 is preferred for sandboxed, portable agent modules. Legacy native plugins are the escape hatch for privileged native behavior.
## Bundle Layout
A legacy bundle is a zip with web assets plus one or more platform binaries:
A native bundle is a zip with web assets plus one or more platform binaries:
```text
<pluginId>.zip
@@ -253,7 +251,7 @@ Most plugin authors can ignore this, but it is useful when debugging Linux nativ
## Build Scripts
Legacy samples include `build.bat` and `build.sh`. They compile native binaries and zip them with web assets.
Native samples include `build.bat` and `build.sh`. They compile native binaries and zip them with web assets.
Default usage:
@@ -316,4 +314,4 @@ The native plugin can reply by invoking the host callback. Those callback events
## Security Notes
Legacy native plugins are trusted executable code. They can call OS APIs, read/write files available to the agent process, spawn subprocesses, open sockets, and interact with native libraries. Use plugin signing, per-user plugin access, and code review before deploying third-party native plugins.
Native plugins are trusted executable code. They can call OS APIs, read/write files available to the agent process, spawn subprocesses, open sockets, and interact with native libraries. Use plugin signing, per-user plugin access, and code review before deploying third-party native plugins.
plugins/docs/samples.md
+4 -7
View File
@@ -6,12 +6,9 @@ The `plugins/` directory includes small examples that exercise each plugin style
|-----------|--------------|
| `sample-build-hooks` | Server-only build plugin, custom Build page action, build settings, and replacing the produced artifact with a `.txt` file. |
| `sample-ts-fullstack` | TypeScript UI and TypeScript server runtime with shared local modules. |
| `sample-wasm` | Plugin 2.0 WASM module built from C/WASI. |
| `sample-wasm-hostinfo` | TinyGo WASM plugin that queries HostInfo. |
| `sample-wasm-platform-note` | Rust WASM plugin that branches by HostInfo/platform. |
| `sample-c` | Legacy native C plugin for the smallest unloadable ABI surface. |
| `sample-cpp` | Legacy native C++ plugin using exported C ABI functions. |
| `sample-go` | Legacy native Go plugin. Go plugins are intentionally not unloaded because the Go runtime cannot be safely unloaded from shared libraries. |
| `sample-rust` | Legacy native Rust plugin with C ABI exports and unload-friendly runtime handling. |
| `sample-c` | Native C plugin for the smallest unloadable ABI surface. |
| `sample-cpp` | Native C++ plugin using exported C ABI functions. |
| `sample-go` | Native Go plugin. Go plugins are intentionally not unloaded because the Go runtime cannot be safely unloaded from shared libraries. |
| `sample-rust` | Native Rust plugin with C ABI exports and unload-friendly runtime handling. |
Use `sample-build-hooks` as the starting point for uploaders, artifact publishers, or custom release buttons.
plugins/docs/wasm-plugins.md
-76
View File
@@ -1,76 +0,0 @@
# WASM Plugins
Plugin 2.0 WASM plugins run inside the agent through a sandboxed runtime. They cannot access files or OS APIs directly; they declare needs in `config.json`, and the agent exposes approved host bridge operations.
## Config
```json
{
"name": "My WASM Plugin",
"version": "1.0.0",
"apiVersion": 2,
"runtime": "wasm",
"wasm": "my-plugin.wasm",
"needs": {
"files": [
{
"bucket": "pluginData",
"access": ["read", "write", "list", "mkdir"],
"reason": "Store plugin state"
}
]
}
}
```
Supported file buckets are `home`, `desktop`, `documents`, `downloads`, `temp`, `appData`, `pluginData`, and `fullDisk`.
Supported operations are `read`, `write`, `list`, `delete`, and `mkdir`. Approval is tracked by a stable hash of normalized needs; changing needs requires approval again.
## Required Exports
| Export | Signature |
|--------|-----------|
| `overlord_alloc` | `ptr(uint32 size)` |
| `overlord_free` | `void(ptr, uint32 size)` |
| `overlord_on_load` | `int32(ptr hostInfo, uint32 hostInfoLen)` |
| `overlord_on_event` | `int32(ptr event, uint32 eventLen, ptr payload, uint32 payloadLen)` |
| `overlord_on_unload` | `void()` |
## Host Imports
Imports are available from both `env` and `overlord`.
| Import | Behavior |
|--------|----------|
| `overlord_emit(event, eventLen, payload, payloadLen)` | Sends an event through the plugin event channel. |
| `overlord_host_info(out, outLen)` | Writes HostInfo JSON into `out`. |
| `overlord_fs_stat(bucket, bucketLen, path, pathLen, out, outLen)` | Writes JSON file metadata into `out`. |
| `overlord_fs_list(bucket, bucketLen, path, pathLen, out, outLen)` | Writes a JSON directory listing into `out`. |
| `overlord_fs_read(bucket, bucketLen, path, pathLen, out, outLen)` | Writes file bytes into `out`, max 32 MB. |
| `overlord_fs_write(bucket, bucketLen, path, pathLen, data, dataLen)` | Writes bytes to a bucket-relative path. |
| `overlord_fs_delete(bucket, bucketLen, path, pathLen)` | Deletes a bucket-relative file or directory. |
| `overlord_fs_mkdir(bucket, bucketLen, path, pathLen)` | Creates a bucket-relative directory. |
Bridge functions return non-negative byte counts or `0` on success. Negative return codes mean denied, invalid path/memory, not found, output buffer too small, file too large, or I/O failure.
## HostInfo
WASM plugins are universal across OS/architecture. To branch by platform, read HostInfo from `overlord_on_load(hostInfo, hostInfoLen)` or `overlord_host_info(out, outLen)`.
```json
{
"clientId": "abc123",
"os": "windows",
"arch": "amd64",
"version": "1.0.0"
}
```
## Samples
| Directory | Toolchain |
|-----------|-----------|
| `plugins/sample-wasm` | C/WASI |
| `plugins/sample-wasm-hostinfo` | TinyGo |
| `plugins/sample-wasm-platform-note` | Rust |