77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
|
# 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 |
|