overlord/PLUGINS.md

# Overlord Plugins

This document explains how to build Overlord plugins, how the runtime works, and what you can do from a plugin UI and a WASM module.

> TL;DR: A plugin is a zip file with 4 files at the root: `<id>.wasm`, `<id>.html`, `<id>.css`, `<id>.js`. Upload it in the Plugins page or drop it in Overlord-Server/plugins.

## 1) How plugins are structured

### Required bundle format

A plugin bundle is a zip file named after the plugin ID:

```
<pluginId>.zip
```

Inside the zip (root level), these four files are required:

```
<pluginId>.wasm
<pluginId>.html
<pluginId>.css
<pluginId>.js
```

Example for plugin ID `sample`:

```
sample.zip
  ├─ sample.wasm
  ├─ sample.html
  ├─ sample.css
  └─ sample.js
```

When the server sees `<pluginId>.zip`, it extracts to:

```
Overlord-Server/plugins/<pluginId>/
  ├─ <pluginId>.wasm
  ├─ manifest.json
  └─ assets/
     ├─ <pluginId>.html
     ├─ <pluginId>.css
     └─ <pluginId>.js
```

The server **generates manifest.json** automatically. You do not need to include a manifest inside the zip.

### Manifest fields

The auto-generated manifest looks like:

```
{
  "id": "sample",
  "name": "sample",
  "version": "1.0.0",
  "binary": "sample.wasm",
  "entry": "sample.html",
  "assets": {
    "html": "sample.html",
    "css": "sample.css",
    "js": "sample.js"
  }
}
```

## 2) Build a WASM plugin (Go WASI)

The plugin runtime expects a WASI-compatible WebAssembly binary. Go 1.21+ builds work well with the current wazero runtime.

Build steps (from the plugin folder):

```
GOOS=wasip1 GOARCH=wasm go build -o <pluginId>.wasm ./wasm
```

There is a working example in:

- plugin-sample-go/wasm/main.go

## 3) Install & open a plugin

### Install / upload

- Use the UI at /plugins to upload the zip
- Or drop `<pluginId>.zip` into Overlord-Server/plugins and restart the server

### Open the UI

The plugin UI is served from:

```
/plugins/<pluginId>?clientId=<CLIENT_ID>
```

Your HTML should load its JS/CSS from `/plugins/<pluginId>/assets/`.

## 4) Runtime: how events flow

Overlord plugins have **two parts**:

1. **UI (HTML/CSS/JS)** — Runs in the browser and can call server APIs or open WebSockets.
2. **WASM module** — Runs in the agent (client) process via wazero.

### UI → agent (plugin event)

From your UI JS, you can send an event to a plugin on a client:

```
POST /api/clients/<clientId>/plugins/<pluginId>/event
{
  "event": "ui_message",
  "payload": { "message": "hello" }
}
```

If the plugin is not loaded yet, the server will:

- load it on the client
- queue your event
- deliver it when the plugin reports `loaded`

### Agent → plugin (WASM stdin)

The agent forwards that event into the WASM plugin over msgpack via stdin.

The message envelope looks like:

```
{
  "type": "event",
  "event": "ui_message",
  "payload": { ... }
}
```

### Plugin → agent (WASM stdout)

Your WASM can reply by writing msgpack messages to stdout. Two supported types:

- `type: "event"` → forwarded back to the server as `plugin_event`
- `type: "log"` → logged by the agent

Examples:

```
{ "type": "event", "event": "ready", "payload": "plugin ready" }
{ "type": "log", "payload": "starting capture" }
```

### Plugin lifecycle events

The agent sends lifecycle events to the server:

- `loaded` on successful load
- `unloaded` when unloaded
- `error` if load or runtime fails

These update the server-side plugin status and error display.

> Note: plugin events are **not** pushed back to the plugin UI automatically. If you need UI feedback, call a server API that returns a response to the UI or implement your own polling/WS endpoint.

## 5) What can plugins do?

Plugins can do anything **the server already exposes** to authenticated users, such as:

- start/stop remote desktop
- open a console session
- file browser actions (list, upload, download, edit)
- process listing and kill
- run scripts
- send commands to clients

This is intentional: plugins **do not modify server code** and are sandboxed by the plugin CSP.

### Security constraints

Plugin pages are served with a tight CSP:

- scripts must be same-origin
- no third‑party JS/CDN
- WebSocket and fetch are allowed to same origin

That means your plugin JS must be bundled into `<pluginId>.js` and loaded from `/plugins/<pluginId>/assets/`.

### Sandboxed iframe isolation

Plugin UIs are rendered inside a **sandboxed iframe** to isolate them from the main dashboard. This provides:

- No access to main app DOM
- No access to main app cookies/localStorage
- No direct access to privileged APIs

Because of the sandbox, **direct network calls from the plugin are blocked** by CSP. The system injects a small bridge that replaces `window.fetch` and forwards requests to the parent page.

Practical implications:

- Use `fetch()` as usual in your plugin JS
- Only the allowed plugin API routes are permitted
- Direct WebSocket usage from the plugin frame is blocked

If your plugin needs WebSockets (e.g., remote desktop), you must build a parent‑page bridge that opens the WS in the parent and forwards frames into the plugin UI. See the remote desktop section below for the architecture.

## 6) API surface (what you can call)

### Plugin management

- `GET /api/plugins` — list installed plugins
- `POST /api/plugins/upload` — upload zip
- `POST /api/plugins/<id>/enable` — enable/disable
- `DELETE /api/plugins/<id>` — remove

### Per-client plugin runtime

- `POST /api/clients/<clientId>/plugins/<pluginId>/load`
- `POST /api/clients/<clientId>/plugins/<pluginId>/event`
- `POST /api/clients/<clientId>/plugins/<pluginId>/unload`

### Useful built-in endpoints

- `POST /api/clients/<clientId>/command` (input, ping, scripts, etc.)
- `WS /api/clients/<clientId>/rd/ws` (remote desktop)
- `WS /api/clients/<clientId>/console/ws`
- `WS /api/clients/<clientId>/files/ws`
- `WS /api/clients/<clientId>/processes/ws`

## 7) Building a “pinnacle” plugin (remote desktop class)

A remote‑desktop‑class plugin typically has:

1. **A UI page** with a `<canvas>` and quality controls
2. **A WebSocket** connection to `/api/clients/<id>/rd/ws`
3. **Command messages** (`desktop_start`, `desktop_stop`, `desktop_select_display`, etc.)
4. **Binary frame decoding** (JPEG/raw) and drawing into the canvas

### How it would work (high level)

1. UI page reads `clientId` from query string
2. JS opens a WebSocket to `/api/clients/<clientId>/rd/ws`
3. UI sends JSON messages:

```
{ "type": "desktop_start" }
{ "type": "desktop_select_display", "display": 0 }
{ "type": "desktop_set_quality", "quality": 90, "codec": "jpeg" }
```

4. Incoming WS messages contain encoded frames (see `public/assets/remotedesktop.js` for the parsing logic)
5. Draw frames into the canvas and expose controls to the user

You do **not** need to re-implement the agent capture pipeline. The agent already supports it; your plugin just drives the existing WS endpoint.

### What you’d write (outline)

- **HTML**: Canvas + controls
- **JS**:
  - parse `clientId`
  - open WS
  - send desktop commands
  - decode frames and draw
- **WASM module** (optional):
  - background tasks or message validation
  - optional telemetry / state management

If you want a starting point, the existing remote desktop UI is in:

- Overlord-Server/public/remotedesktop.html
- Overlord-Server/public/assets/remotedesktop.js

You can reuse that logic inside your plugin UI with minimal changes.

## 8) Example: minimal plugin code shape

### WASM side (Go, message loop)

- listen on stdin using msgpack
- on `type=init`, send `event=ready`
- on `type=event`, process payload and emit response events

See:

- plugin-sample-go/wasm/main.go

### UI side (JS)

- call `/api/clients/<id>/plugins/<pluginId>/event`
- show responses via your own UI (or poll your own endpoints)

See:

- plugin-sample-go/sample.js

---

If you want a deeper walkthrough of a specific plugin type (file explorer, custom telemetry, or a remote-desktop clone), say which one and I’ll expand that section.