modularize docs

2026-06-22 13:04:33 -05:00
parent 7aaf115e2f
commit 5f75f5ca6f
9 changed files with 981 additions and 1535 deletions
@@ -0,0 +1,76 @@
+# 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 |