Native Plugin Development
This guide describes the OxideTerm Native plugin model. It is intentionally different from the Tauri/Web plugin model: native plugins do not run React components, do not inject CSS, and do not execute main.js through a WebView. A native plugin is discovered through plugin.json, then either contributes manifest-only metadata or runs through a host-owned process/WASM runtime bridge.
Specialized packages also use language, acp, remote-desktop, terminal-transport, and helper runtimes. RDP and VNC engines are marketplace plugins; the host retains saved profiles and the viewer. Process connection providers can supply independent connection instances and live workbenches.
Contents
Section titled “Contents”- Build A Running Plugin
- Runtime Conversation
- Host Calls In Plugin Code
- UI And Event Recipes
- Common Failure Checks
- Native Plugin Model
- Native Versus Tauri Plugins
- Plugin Directory
- Minimal Manifest-Only Plugin
- Background Material Packs
- Editor Language Plugins
- Process Runtime Plugin
- Protocol Frames
- Runtime Registrations
- Connection providers
- Declarative Native UI
- Host API Calls
- Permissions And Capabilities
- Settings, Storage, And Secrets
- Terminal, SFTP, Forwarding, IDE, And AI
- Packaging And Installation
- Interface Reference
- Host API Reference
- Events Reference
- Debugging
- Migration Notes
Build A Running Plugin
Section titled “Build A Running Plugin”Start with a process plugin. It is the easiest runtime to debug because every message is visible as JSON Lines over stdio.
Create this directory inside the user plugin directory:
hello-native/ plugin.json bin/ hello.jsThe process entry must be a real executable inside the plugin directory. On macOS/Linux, give the script an executable bit:
chmod +x hello-native/bin/hello.jsUse this manifest:
{ "id": "com.example.hello-native", "name": "Hello Native", "version": "0.1.0", "description": "Minimal native process plugin.", "runtime": { "kind": "process", "entry": "bin/hello.js" }, "permissions": { "capabilities": [ "legacy.invoke", "ui.write" ] }, "contributes": { "sidebarPanels": [ { "id": "hello-panel", "title": "Hello", "icon": "panel-left", "position": "top" } ], "settings": [ { "id": "message", "type": "string", "default": "Hello from a native plugin", "title": "Message" } ], "apiCommands": [ "get_app_version" ] }}Use this process runner:
#!/usr/bin/env node
const readline = require("node:readline");
const pluginId = "com.example.hello-native";let nextHostRequest = 1;const pendingHostCalls = new Map();
// Keep stdout reserved for protocol frames.function writeFrame(payload, requestId = null) { process.stdout.write(JSON.stringify({ protocolVersion: 1, requestId, payload }) + "\n");}
function respondOk(requestId, value) { writeFrame({ requestId, result: { status: "ok", value } }, requestId);}
function respondError(requestId, code, message) { writeFrame({ requestId, result: { status: "error", error: { code, message, recoverable: false } } }, requestId);}
function registerPanel() { writeFrame({ type: "registerContribution", registration: { registrationId: "hello-panel-view", pluginId, kind: "sidebar-panel", metadata: { panelId: "hello-panel", schema: { kind: "form", title: "Hello Native", sections: [ { id: "main", controls: [ { kind: "markdown", text: "This panel was registered by a native process plugin." }, { kind: "button", id: "refresh", label: "Refresh" } ] } ] } } } });}
// Returnable host calls are matched by requestId.function callHost(namespace, method, args = {}) { const requestId = `host-${nextHostRequest++}`; writeFrame({ type: "callHostApi", requestId, namespace, method, args }); return new Promise((resolve, reject) => { pendingHostCalls.set(requestId, { resolve, reject }); });}
// Host-call responses arrive on stdin like normal host requests.function handleHostResponse(payload) { const pending = pendingHostCalls.get(payload.requestId); if (!pending) { return false; } pendingHostCalls.delete(payload.requestId); if (payload.result.status === "ok") { pending.resolve(payload.result.value); } else { pending.reject(new Error(payload.result.error.message)); } return true;}
// Host requests and host-call responses share the same input stream.async function handleRequest(envelope) { const request = envelope.payload; if (handleHostResponse(request)) { return; }
const requestId = request.requestId; switch (request.kind.type) { case "activate": registerPanel(); writeFrame({ type: "runtimeReady" }); respondOk(requestId, { activated: true }); break; case "sendEvent": respondOk(requestId, { received: request.kind.event.name }); break; case "health": respondOk(requestId, { ok: true }); break; case "deactivate": case "kill": respondOk(requestId, { stopped: true }); process.exit(0); break; case "dispatchCommand": try { const version = await callHost("api", "invoke", { command: "get_app_version", args: {} }); respondOk(requestId, { version }); } catch (error) { respondError(requestId, "command_failed", error.message); } break; default: respondError(requestId, "unsupported_request", `Unsupported request ${request.kind.type}`); }}
readline.createInterface({ input: process.stdin, crlfDelay: Infinity}).on("line", (line) => { if (!line.trim()) { return; } handleRequest(JSON.parse(line)).catch((error) => { process.stderr.write(`Plugin error: ${error.stack || error.message}\n`); });});This example demonstrates the important contract:
stdoutis reserved for protocol frames, one JSON object per line.stderris for human diagnostics.- The plugin must answer the activation request with the same
requestId. - Runtime UI is not React. It is a declarative schema registered through a
sidebar-panelortabcontribution. - A returnable host call is sent as an outbound
callHostApiframe; the host writes the response back on stdin.
For a complete repository example that registers both a tab and a left activity-bar panel, discovers an active node, and runs a manifest-declared custom Host Tools monitor, see Host Tools Dashboard.
Runtime Conversation
Section titled “Runtime Conversation”The process runtime has one line-oriented conversation.
sequenceDiagram
participant Host as OxideTerm Host
participant Plugin as Plugin Process
Host->>Plugin: activate request on stdin
Plugin-->>Host: registerContribution sidebar-panel on stdout
Plugin-->>Host: runtimeReady on stdout
Plugin-->>Host: activate ok response on stdout
Host->>Plugin: sendEvent / dispatchCommand / health on stdin
Plugin-->>Host: response with the same requestId on stdout
Activation request from host to plugin. The manifest and allowedHostApis values are shortened here; the real request carries the parsed plugin.json and the complete effective allowlist:
{ "protocolVersion": 1, "requestId": "activate:com.example.hello-native", "payload": { "requestId": "activate:com.example.hello-native", "kind": { "type": "activate", "manifest": { "id": "com.example.hello-native", "name": "Hello Native", "version": "0.1.0" }, "permissions": { "capabilities": [ "legacy.invoke", "runtime.process.trusted", "ui.write" ], "allowedHostApis": [ "api.invoke", "app.getVersion", "connections.getSummaries", "settings.get", "ui.registerSidebarPanel", "ui.registerActivityBarItem" ] } }, "timeoutMs": 5000 }}Activation response from plugin to host:
{ "protocolVersion": 1, "requestId": "activate:com.example.hello-native", "payload": { "requestId": "activate:com.example.hello-native", "result": { "status": "ok", "value": { "activated": true } } }}Error response:
{ "protocolVersion": 1, "requestId": "activate:com.example.hello-native", "payload": { "requestId": "activate:com.example.hello-native", "result": { "status": "error", "error": { "code": "invalid_config", "message": "Missing required plugin setting", "recoverable": false } } }}Host-call request from plugin to host:
{ "protocolVersion": 1, "requestId": null, "payload": { "type": "callHostApi", "requestId": "host-1", "namespace": "app", "method": "getVersion", "args": {} }}Host-call response from host to plugin:
{ "protocolVersion": 1, "requestId": "host-1", "payload": { "requestId": "host-1", "result": { "status": "ok", "value": "0.1.0" } }}The process bridge rejects malformed frames before they reach the workspace. Common rejection causes are unsupported protocolVersion, missing requestId on responses, mismatched response ids, invalid registration ownership, and stdout text that is not JSON.
Host Calls In Plugin Code
Section titled “Host Calls In Plugin Code”Host calls are not global JavaScript functions. They are protocol messages. A call is accepted only when its name appears in the effective allowedHostApis. Baseline, redacted reads are included automatically; sensitive reads and side effects are included after the matching manifest capabilities are approved.
api.invoke has one additional check: args.command must also be listed in contributes.apiCommands.
Read a plugin setting:
{ "type": "callHostApi", "requestId": "host-2", "namespace": "settings", "method": "get", "args": { "key": "message" }}Read redacted terminal metadata without requesting a capability:
{ "type": "callHostApi", "requestId": "host-3", "namespace": "terminal", "method": "getMetadata", "args": {}}Write text to the active terminal:
{ "type": "callHostApi", "requestId": "host-4", "namespace": "terminal", "method": "writeToActive", "args": { "text": "pwd\n" }}That write requires terminal.write. Reading terminal text or the active target requires terminal.content.read.
Read a remote file through SFTP:
{ "type": "callHostApi", "requestId": "host-5", "namespace": "sftp", "method": "readFile", "args": { "nodeId": "node-1", "path": "/etc/hostname" }}That SFTP call also requires the filesystem.read capability. Write operations require filesystem.write. Legacy SCP transfers use the same capability pair and must target an online node. Port forwarding mutations require network.forward.
Import an .oxide bundle:
{ "type": "callHostApi", "requestId": "host-6", "namespace": "sync", "method": "importOxide", "args": { "fileData": [1, 2, 3], "password": "user-entered-password", "conflictStrategy": "rename", "importAppSettings": true, "importPluginSettings": true }}Do not log or echo passwords, secret values, terminal buffers, connection config, or raw import/export payloads.
UI And Event Recipes
Section titled “UI And Event Recipes”Register a tab view:
{ "type": "registerContribution", "registration": { "registrationId": "hello-tab-view", "pluginId": "com.example.hello-native", "kind": "tab", "metadata": { "tabId": "hello-tab", "schema": { "componentVersion": 1, "kind": "form", "title": "Hello", "controls": [ { "kind": "markdown", "text": "This tab is rendered by OxideTerm, not by plugin HTML." } ] } } }}Subscribe to terminal/session events by registering event-subscription:
{ "type": "registerContribution", "registration": { "registrationId": "watch-active-node", "pluginId": "com.example.hello-native", "kind": "event-subscription", "metadata": { "namespace": "sessions", "method": "onNodeStateChange", "nodeId": "node-1" } }}When the event fires, the host sends a normal sendEvent request to the process:
{ "protocolVersion": 1, "requestId": "event:sessions.nodeStateChanged", "payload": { "requestId": "event:sessions.nodeStateChanged", "kind": { "type": "sendEvent", "event": { "name": "sessions.nodeStateChanged", "payload": { "nodeId": "node-1" } } } }}The plugin must still respond:
{ "protocolVersion": 1, "requestId": "event:sessions.nodeStateChanged", "payload": { "requestId": "event:sessions.nodeStateChanged", "result": { "status": "ok", "value": { "handled": true } } }}Custom plugin events use events.emit and events.on. They are scoped by plugin id, so one plugin cannot take ownership of arbitrary global event names.
Common Failure Checks
Section titled “Common Failure Checks”If the plugin never activates:
- Check that
runtime.entrypoints to an existing executable file inside the plugin directory. - Check that the process prints only JSON Lines to stdout.
- Check that the activation response has both envelope
requestIdand payloadrequestId. - Check that
protocolVersionis1. - Check stderr for plugin diagnostics.
If UI does not appear:
contributes.tabsorcontributes.sidebarPanelsmust declare the surface id.- Runtime registration must use the same
tabIdorpanelId. registration.pluginIdmust match the manifestid.metadata.schema.kindshould beform.- Interactive controls such as
button,text,password,number,checkbox, andselectneed stableidvalues.
If a standalone activity-bar action does not appear or run:
contributes.activityBarItemsmust declare the item id, title, icon, command, and placement.- Runtime registration must use
kind: "activity-bar-item"with the sameitemId. - The plugin must request
ui.writeand handle the declareddispatchCommandvalue. - Runtime metadata cannot override the manifest-declared icon or command.
If a Host API call fails:
- Confirm the call is in
allowedHostApis. - Confirm the method name and argument names match the reference tables below.
- For
api.invoke, confirm the command is listed incontributes.apiCommands. - For SFTP or forwarding, confirm the required capability is present.
- For secrets and passwords, confirm the plugin is not trying to send secret values through logs or UI text.
Native Plugin Model
Section titled “Native Plugin Model”flowchart TB
Manifest["plugin.json"] --> Discovery["Native Plugin Discovery"]
Discovery --> Registry["Plugin Registry"]
Registry --> Contributions["Manifest Contributions"]
Registry --> RuntimePlan["Runtime Plan"]
RuntimePlan --> ManifestOnly["manifest-only"]
RuntimePlan --> Process["process runtime"]
RuntimePlan --> Wasm["wasm runtime"]
RuntimePlan --> Legacy["legacy-js visible but not executable"]
Process --> Protocol["JSON Lines Protocol"]
Wasm --> Protocol
Protocol --> HostApi["Host API Resolver"]
Protocol --> RuntimeRegs["Runtime Registrations"]
RuntimeRegs --> UI["Native GPUI Surfaces"]
HostApi --> Domains["SSH · SFTP · Terminal · IDE · AI · Sync · Settings"]
The host owns every durable and security-sensitive boundary:
- Manifest parsing and validation.
- Runtime startup and timeout handling.
- Contribution registration and cleanup.
- Host API permission checks.
- Plugin settings, storage, and secrets.
- UI rendering through native GPUI controls.
The host API does not expose raw GPUI elements, DOM nodes, React instances, or SSH transport handles. Native process plugins run with their user’s operating-system permissions; host API checks do not sandbox the executable’s own filesystem or network access.
Native Versus Tauri Plugins
Section titled “Native Versus Tauri Plugins”| Area | Tauri/Web Plugin | Native Plugin |
|---|---|---|
| Runtime | ESM main.js loaded through dynamic import | General extensions use process, wasm, or manifest-only; specialized runtimes are listed above |
| UI | React components and CSS | Declarative native UI schema rendered by GPUI |
| Shared modules | window.__OXIDE__ | Not available |
| Styling | CSS and theme variables | Host-owned native controls only |
| Host API | Frozen PluginContext object | JSON protocol calls with namespace/method/args |
| Legacy JS | Executable in Tauri | Shown as legacy-js, not executed |
| Security boundary | Browser membrane plus Tauri commands | Runtime bridge, permission gates, scoped storage/secrets |
If a plugin has main but no native runtime block, Native classifies it as legacy JS. It can appear in Plugin Manager for migration, but it is not executed.
Plugin Directory
Section titled “Plugin Directory”Plugins live under the app configuration directory:
<config-dir>/plugins/<plugin-id>/ plugin.json bin/ plugin-runtime assets/ locales/Use oxideterm paths --json to find the active configuration directory. The CLI can enable, disable, and inspect plugin state for headless workflows, but interactive install/update/uninstall work is owned by the desktop Plugin Manager.
Minimal Manifest-Only Plugin
Section titled “Minimal Manifest-Only Plugin”Manifest-only plugins are useful for static metadata, declared settings, AI tool metadata, and future package migration. They do not execute code.
{ "id": "com.example.audit", "name": "Audit Helper", "version": "0.1.0", "description": "Adds audit-related settings and tool metadata.", "author": "Example", "contributes": { "settings": [ { "id": "scanDepth", "type": "number", "default": 3, "title": "Scan depth", "description": "Maximum audit depth." } ], "aiTools": [ { "name": "audit_summarize", "description": "Summarize visible connection and terminal state.", "capabilities": ["state.list", "terminal.observe"], "risk": "read", "targetKinds": ["ssh-node", "terminal-session"] } ] }}Supported setting types are string, number, boolean, and select. A select setting must provide options, and option values must be strings or numbers.
Background Material Packs
Section titled “Background Material Packs”Background packs use the same installer and declare only
contributes.backgrounds, an array of package-relative media paths. For example:
{ "id": "com.example.backgrounds", "name": "Backgrounds", "version": "1.0.0", "engines": { "oxideterm": ">2.2.2" }, "tags": ["backgrounds"], "contributes": { "backgrounds": ["assets/day.mp4", "assets/night.mp4"] }}Omit runtime, main, capabilities, and other contributions. Background packs
require a subsequent host release containing this feature; 2.2.2 does not support
them. Installation copies media into backgrounds beside the active settings
file, including portable profiles, without changing either appearance’s selection.
Reinstalling a version reuses its copies. New versions add separate media; uninstalling
keeps imported files for the user to manage in the appearance library.
Editor Language Plugins
Section titled “Editor Language Plugins”The host keeps 15 grammar entries built in: Bash, Zsh, Fish, PowerShell, JSON,
YAML, TOML, Markdown, Dockerfile, Make, CMake, Diff, Python, Lua, and SQL.
Another 24 grammar entries use language plugins: C, C++, C#, CSS, Common Lisp, Elixir, Go,
HTML, Java, JavaScript, Objective-C, Perl, PHP, R, Ruby, Rust, Scala, Swift,
TypeScript, TSX, Zig, Nginx, Terraform/HCL, and Protobuf. TypeScript and TSX are separate plugin packages.
Nginx uses dedicated filenames such as nginx.conf or .nginx extensions, not
generic .conf files. HCL handles .tf, .tfvars, and .hcl; JSON variants
remain JSON. Protobuf uses .proto.
File type
recognition stays in the host. When support is missing or disabled, the editor keeps
the document editable and offers a link to Plugin Manager. Installing or enabling
support loads the parser on demand; updates and disabling refresh open documents
without discarding their text or undo history. Header files ending in .h
continue to select C++ support.
A language package declares runtime.kind: "language" and contributes.language.
It contains a Tree-sitter WebAssembly parser, highlight queries, their SHA-256
checksums, a host version range, and the upstream licenses. It does not receive the
general-purpose WASI plugin host API. The marketplace repository maintains the
pinned build recipes and release workflow.
Each language has its own directory under plugins/, version, and release asset.
Language plugin files use Apache-2.0, with upstream licenses retained separately.
Packages require a host strictly newer than 2.2.0 with the language loader.
Process Runtime Plugin
Section titled “Process Runtime Plugin”A process plugin is an executable inside the plugin directory. The host starts it with stdin/stdout pipes and exchanges newline-delimited JSON protocol frames.
{ "id": "com.example.native-dashboard", "name": "Native Dashboard", "version": "0.1.0", "runtime": { "kind": "process", "entry": "./bin/native-dashboard" }, "permissions": { "capabilities": [ "connections.read", "legacy.invoke", "ui.write" ] }, "contributes": { "tabs": [ { "id": "dashboard", "title": "Dashboard", "icon": "LayoutDashboard" } ], "sidebarPanels": [ { "id": "dashboard-panel", "title": "Dashboard", "icon": "Activity", "position": "bottom" } ], "activityBarItems": [ { "id": "refresh", "title": "Refresh Dashboard", "icon": "RefreshCw", "command": "dashboard.refresh", "position": "top" } ], "terminalHooks": { "shortcuts": [ { "key": "Ctrl+Shift+D", "command": "dashboard.refresh" } ] }, "apiCommands": [ "get_app_version" ] }}Rules:
runtime.entrymust be a relative path inside the plugin directory.- The entry must exist for
processandwasmruntimes. - A process plugin implicitly requests
runtime.process.trusted. The Plugin Manager includes that trust decision in the enable-time approval because the process runs without an OS sandbox. - The process must not write arbitrary human logs to stdout. Stdout is the protocol channel.
- Use stderr for diagnostic text.
- Every protocol frame is a single JSON object followed by
\n.
Protocol Frames
Section titled “Protocol Frames”The host wraps every request and response in an envelope. This example shortens the baseline allowlist:
{ "protocolVersion": 1, "requestId": "activate-1", "payload": { "requestId": "activate-1", "kind": { "type": "activate", "manifest": { "id": "com.example.runtime", "name": "Example Runtime", "version": "0.1.0" }, "permissions": { "capabilities": [], "allowedHostApis": [ "app.getVersion", "connections.getSummaries", "sessions.getSummary", "terminal.getMetadata" ] } }, "timeoutMs": 3000 }}The plugin responds with a matching requestId:
{ "protocolVersion": 1, "requestId": "activate-1", "payload": { "requestId": "activate-1", "result": { "status": "ok", "value": { "activated": true } } }}The host may send request kinds such as activate, deactivate, dispatchCommand, sendEvent, callHostApi, health, and kill. A plugin may emit outbound frames such as runtimeReady, registerContribution, disposeContribution, callHostApi, emitEvent, reportProgress, log, and runtimeError.
Runtime Registrations
Section titled “Runtime Registrations”Runtime registrations let a running process/WASM plugin add host-owned contributions:
{ "protocolVersion": 1, "requestId": null, "payload": { "type": "registerContribution", "registration": { "registrationId": "cmd-refresh", "pluginId": "com.example.native-dashboard", "kind": "command", "metadata": { "id": "dashboard.refresh", "label": "Refresh Dashboard", "icon": "RefreshCw", "section": "Dashboard" } } }}Common registration kinds:
| Kind | Purpose |
|---|---|
command | Add a command-palette action dispatched back to the plugin |
keybinding | Add a keybinding after built-in shortcuts miss |
context-menu | Add context menu items for declared targets |
status-bar | Add a host-owned status item |
tab | Register declarative UI for a declared tab |
sidebar-panel | Register declarative UI for a declared panel |
activity-bar-item | Register a standalone left activity-bar action declared by the manifest |
event-subscription | Subscribe to host events |
terminal-input-interceptor | Transform or suppress terminal input |
terminal-output-processor | Process terminal output before parser input |
terminal-shortcut | Attach terminal shortcut handling to a command |
progress | Create a host-owned progress reporter |
A registration must use the same plugin id as the plugin that emitted it. Disposal is idempotent and host-owned.
Connection providers
Section titled “Connection providers”Process plugins can declare connection types in contributes.connections. They appear in
the existing New Connection dialog and Session Manager, including search, editing,
deletion, batch selection and groups. Each opening creates an independent instance even
when it uses the same saved profile. This API requires OxideTerm 2.2.5 or later; exclude
older hosts in engines.oxideterm and request ui.write.
{ "connections": [{ "id": "device", "title": "Device", "icon": "plug", "terminalEntry": "bin/terminal", "form": { "controls": [ {"kind": "text", "id": "address", "label": "@address"}, {"kind": "password", "id": "token", "label": "@token"} ], "translations": {"en": {"address": "Address", "token": "Token"}} } }]}Supply the usual eleven-locale dictionary in production. Forms reuse the native controls:
text, password, number, checkbox, select, textarea, stack, row, columns
and markdown. The host adds name and group fields. Section and field IDs cannot contain
/; __profile is a reserved host section. Values use sectionId/controlId keys,
with root for top-level controls. Numeric text fields submit their text representation.
Password fields require approved credentials.raw.read. The host saves their values in
its secret store, with references in the connection profile. Blank password edits preserve
saved values; “Clear saved credentials” removes them before applying newly entered ones.
Drafts are not sent to the plugin. Saved profiles remain available when a provider is
disabled or removed; their metadata can still be edited and deleted. Profiles are stored
in the connection manager and included in the connections scope of cloud sync and in
.oxide selection, previews and conflict handling. Sync identifies a provider by
plugin_id and type_id; importing metadata does not require the provider to be installed.
Unknown configuration fields remain in storage and subsequent exports, but connection.open
receives only fields declared by the installed provider’s form. Editing on an older provider
therefore does not erase newer settings. Password slots are also matched to the current form.
Credentials travel only when sensitive-credential sync is enabled or passwords are included
in an encrypted .oxide export. Archive import additionally requires opting into stored
credentials. Local secret-store references never travel; restored values receive new local
references. Missing providers keep the connection unavailable until a compatible provider is
installed and enabled. Both devices need a host version supporting plugin connections.
After activation the host dispatches connection.open with:
{ "instanceId": "host-generated-uuid", "profileId": "saved-profile-uuid", "typeId": "device", "config": {"root/address": "device.local"}, "credentials": {"root/token": "user-provided-secret"}}Key all live resources by instanceId, not profileId. Reply with one of these values:
{"kind":"workbench","schema":{...}}: a validated declarative UI, displayed in a normal plugin page that can share a split with terminals. Itsui.event.surfaceIdis the instance ID. Update it with atabregistration whose metadata containsconnectionId: instanceIdandschema; use a distinct registration ID per instance.{"kind":"terminal","args":[...]}: launch the declaredterminalEntrydirectly in the host’s native PTY. The executable must resolve inside the plugin package. Arguments retain their boundaries; the host does not fall back to a shell. Keep credentials out of arguments and environment variables; the provider should retain them for its helper.{"kind":"sshTerminal","shell":"posix","nodeId":"...","argv":["program","arg"]}: with approvedterminal.write, open a terminal consumer on an already connected node. The host quotes each argument for the explicitly selected POSIX shell and rejects control characters that could edit or submit its command line. No second unmanaged SSH connection is created.
Disconnecting or closing the connection’s page or terminal sends connection.close with
{"instanceId":"..."}. Make this command idempotent, including for unknown IDs and
cancelled opens. Stop the instance’s sockets, subscriptions and workers before replying.
Switching pages does not disconnect. Moving or splitting a terminal preserves its owner.
The provider must answer lifecycle commands within five seconds. A transport timeout or
failed cleanup retires the provider process and its terminal consumers. Disabling or
updating a provider also stops its instances while retaining saved profiles. Late results
and view updates cannot reopen closed instances.
Declarative Native UI
Section titled “Declarative Native UI”Live updates and message workbenches
Section titled “Live updates and message workbenches”After activation, process plugins can write protocol frames to stdout without waiting for
a user action. Re-register a tab or sidebar-panel with the same registrationId to
update its view. The host continuously reads output and delivers bounded batches through
the same permission checks as initial registration. Coalesce incoming messages and submit
only a bounded visible dataset instead of replacing the entire view for every message.
Keep stdout exclusively for JSON Lines protocol frames.
Switching or closing an ordinary contributed tab does not stop the plugin process. The plugin owns its network
connections and should provide an explicit disconnect action. Disabling, uninstalling or
closing the workspace stops its runtime and output readers; updates from a retired instance
are discarded. These capabilities require OxideTerm 2.2.5 or later. Exclude older hosts in
engines.oxideterm when using them.
A table with id, selectable: true and rowKey supports mouse selection and, when focused,
arrow keys, Home and End. rowKey names a field containing a unique, nonempty string in
every row. value can set the selected row identity. Selection emits ui.event with
type: "change" and the row identity as value. Existing tables remain read-only by default.
{ "kind": "table", "id": "messages", "selectable": true, "rowKey": "id", "columns": ["topic", "preview"], "rows": [{"id": "message-1", "topic": "devices/status", "preview": "ready"}]}Tables and lists with stable IDs preserve their scroll position across updates. With
rowKey, insertion, deletion and reordering preserve the first visible row’s identity;
if that row disappears, the host uses a nearby valid position. Removing the selected row
clears selection. Keep the plugin, surface, section and control IDs stable to retain state.
Use textarea for multiline message bodies:
{"kind": "textarea", "id": "body", "label": "@payload", "value": "first line\nsecond line"}This uses the native editor’s IME, selection, undo, clipboard and scrolling behavior.
Edits emit ui.event with type: "input" and the complete text as value. Unrelated view
updates preserve the draft; explicitly changing value replaces it. disabled prevents
editing. Closing the owning surface releases editor state. Labels and placeholders use
the plugin’s existing eleven-language translation dictionary.
Native plugins select OxideTerm components through a versioned schema. The plugin supplies data and receives events; the host supplies the real shared components, theme tokens, density, typography, focus, IME behavior, accessibility semantics, and responsive layout. Plugin runtimes never receive raw GPUI objects and cannot inject HTML, CSS, closures, or drawing code.
{ "protocolVersion": 1, "requestId": null, "payload": { "type": "registerContribution", "registration": { "registrationId": "tab-dashboard", "pluginId": "com.example.native-dashboard", "kind": "tab", "metadata": { "tabId": "dashboard", "schema": { "componentVersion": 1, "kind": "form", "title": "Dashboard", "sections": [ { "id": "overview", "title": "Overview", "controls": [ { "kind": "markdown", "text": "Native plugin UI is host-rendered." }, { "kind": "keyValue", "label": "Status", "value": "Ready" }, { "kind": "progress", "label": "Sync", "value": 42 }, { "kind": "button", "id": "refresh", "label": "Refresh" } ] } ] } } } }}Supported control kinds:
| Kind | Notes |
|---|---|
stack, row, card, toolbar | Layout components; render nested children using bounded host layouts |
columns | Equal-width columns that wrap in narrow containers |
actionRow | Flexible first child with trailing actions aligned to the right; a leading button fills its slot |
text, password, number, checkbox, select | Shared field controls; require stable id values |
radioGroup, radio-group, segmentedControl, segmented-control, slider | Shared choice/range controls; require stable id values |
button, iconButton, icon-button | Shared actions; actionable only with id and while enabled/not loading; icon buttons also require icon and label |
alert | Semantic host notice with tone, optional icon, title, and description |
markdown | Parsed using OxideTerm’s Markdown renderer; background images and local-file links are disabled |
code, codeBlock, code-block | Code block |
statusBadge, status-badge, badge | Shared status pill with semantic tone/strength |
progress | Shared progress display; values may be 0..1 or 0..100 |
table, list | Bounded, virtualized shared data components |
emptyState, empty-state | Shared empty state with optional icon/description |
divider | Shared separator |
keyValue, key-value, keyValueRow, key-value-row | Key/value row |
Component events are delivered only to the plugin that owns the surface:
{ "name": "ui.event", "payload": { "type": "change", "componentKind": "select", "surfaceKind": "tab", "surfaceId": "dashboard", "sectionId": "overview", "controlId": "environment", "value": "production" }}Buttons emit click, text fields emit input, and choice/range controls emit
change. Password drafts are zeroized by the host. Without an explicitly
approved credentials.raw.read capability, password events contain only
{ "present": boolean, "redacted": true }; raw text is sent only to the
owning plugin after that sensitive-content approval. Password controls cannot
declare an initial value, so a credential is never retained in a registered
schema.
For safety and predictable performance, component version 1 accepts at most 8
nested levels, 256 controls, 64 children per container, 128 options per choice,
2,000 rows per data control, and 64 table columns. Control IDs must be unique
within their root or section, and root is reserved as a section ID. Unknown
versions, variants, tones, sizes, gaps, or child placements are rejected during
registration. The complete encoded schema is limited to 2 MiB.
Host API Calls
Section titled “Host API Calls”Native text workbench
Section titled “Native text workbench”WASM plugins may register a textWorkbench control with a stable id. Its options
are tools: { label, value: { command, group?, description?, parameterLabel?, parameterDefault? } }. Tools sharing a group appear under one sidebar entry; their operations appear above the editors. The optional parameter
uses another native input. Selecting an unrelated parameter applies its declared default; switching operations with the same parameter label retains the current value. The control’s value supplies translated labels for
input, output, execute, working, copy, useInput, clear, limit, failed,
line, column and its supported error codes. A schema can bundle
translations: { "en": { key: text }, "zh-CN": { key: text }, ... }; strings prefixed
with @ resolve against that catalog, including the page header and tool options.
Ship all 11 host locales with matching keys. This capability requires a host newer than 2.2.0.
The host owns input and read-only result editors, selection, clipboard writes and
draft lifetime. Run snapshots the input and starts a fresh WASM instance, invoking
the selected command with { input, parameter }. The response value is either
{ output: string } or { error: { code, line?, column? } }. Error codes resolve
through the control’s labels; unknown codes use the generic failed label.
Input is limited to 256 KiB, parameter to 4 KiB, output to
2 MiB, and execution to five seconds. Failed executions keep both drafts. Input is
not sent in UI registration/events, saved in settings, or dispatched to a terminal.
Closing the tab drops editors and cancels result delivery; an executing WASM call
is bounded by its timeout. This isolated instance has no host-call resolver,
preopened directories or network permissions.
A runtime contextMenu contribution with target: "terminal" may declare an item
with { label, tabId, controlId }. The host captures the selected text when clicked
and opens that plugin’s declared text workbench. Later pane focus or output changes
cannot change the captured input. @ menu labels use the target tab’s translations.
File preview providers
Section titled “File preview providers”Process plugins can provide paginated document previews through the existing file-browser preview window. They do not need a tab or sidebar contribution:
{ "contributes": { "filePreviews": [{"mimeTypes": ["application/pdf"], "command": "preview.render"}] }}The host selects an enabled, compatible and approved provider by exact MIME type.
Local files and SFTP PDF, SQLite, certificate and binary downloads use the document asset path; the initial size
limit is 10 MiB. Other built-in preview types retain their existing renderers.
Each render uses a dedicated process instance and the ordinary activate and
dispatchCommand protocol. The command receives { path, page, width }, where
page is zero-based and width is a requested bitmap width from 256 to 2048 pixels.
PDF providers return { pageCount, page, png } with a base64 PNG. The host bounds the decoded
image to 8 million pixels and displays it through GPUI. Do not emit UI registrations
or host calls from a preview renderer; this instance only returns a rendered page.
SQLite providers register application/vnd.sqlite3 (and optionally application/x-sqlite3).
Requests also include table: string | null and snapshot: boolean. The latter is
true only for host-owned temporary downloads; SQLite opens these immutable copies
without creating WAL/SHM sidecars. Local files use ordinary read-only SQLite access.
Responses use { kind: "table", tables: string[], selectedTable: string | null, columns: string[], rows: (string | null)[][], rowCount, page, pageCount }.
Pages contain 50 rows except the last; empty tables/databases have one empty page.
The host validates table selection, row shape and bounds before rendering its
native table. Limits are 256 table names, 64 columns and 4 MiB of cell text per page.
Remote SQLite files with nonempty WAL/rollback journals or detected changes during
download are rejected; use a complete backup made after writes stopped.
Certificate providers register application/pkix-cert; binary inspectors register
application/x-oxideterm-binary. Extensions and file headers select these routes
before text preview. Inspection responses contain { kind, index, objects, fields },
where index echoes the requested page, objects lists up to 64 certificates or
architecture slices, and fields contains { key, value } pairs using the host’s
localized field keys. Certificate responses use kind: "certificate", add details,
and require Unix-second notBefore and notAfter. Return only public certificate
fields; mixed PEM private-key blocks must never appear in the response. The host
labels validity dates separately from trust, chain, signature and revocation checks.
Binary responses use kind: "binary", add whole-file size and up to 1024 sections
with { name, address, offset, size }. File offsets are relative to the whole source,
including universal Mach-O files; null denotes sections without file-backed bytes.
The host rejects out-of-file ranges and uses its existing hex formatter and read-only
editor for 512-byte pages and offset jumps. Plugins only interpret the file and do
not edit it, disassemble it or register additional views.
The preview owns cancellation and the source-file lease. Closing it aborts the render process and pending SFTP preview download; dropping the final lease removes remote temporary files. It does not disconnect the shared SSH node. Process trust is still required: this is crash isolation, not a filesystem sandbox. Disable or uninstall removes the provider from selection and cancels its open preview.
This capability is new after 2.2.0. Release manifests must exclude older hosts; local development variants must not weaken the published compatibility range.
Runtime plugins call host APIs by namespace, method, and JSON args:
{ "protocolVersion": 1, "requestId": null, "payload": { "type": "callHostApi", "requestId": "host-1", "namespace": "connections", "method": "getAll", "args": {} }}The host rejects calls that are not in the effective plugin permission set. Direct host APIs are derived from approved capabilities and do not need to be repeated in contributes.apiCommands. That list is only the second allowlist for commands sent through the legacy api.invoke adapter.
Common namespaces include:
| Namespace | Typical use |
|---|---|
connections | Read and control saved/live connection lifecycle |
sessions | Read node tree and active node state |
terminal | Observe buffers or send approved input |
sftp | List/read/write remote files through node-owned SFTP |
scp | Transfer files through node-owned legacy SCP when SFTP is unavailable |
forward | List/create/stop forwards |
transfers | Observe transfer state |
profiler | Read node metrics |
hostTools | Read cached host state, capture typed datasets, and run validated actions |
eventLog | Read app event log |
notifications | Read or manage notification-center entries |
quickCommands | Read, manage, or execute saved quick commands |
cloudSync | Read safe sync status/history and control sync operations |
theme | Read full effective tokens and select an installed theme |
ide | Observe and edit the active IDE project |
ai | Read sanitized AI data and control conversations/generation |
app | Theme, platform, version, settings snapshots |
settings | Plugin and syncable settings |
storage | Plugin-scoped JSON KV |
sync | .oxide, saved connections, plugin settings, sync metadata |
secrets | Plugin-scoped secret storage |
ui | Toasts, confirm dialogs, layout, progress |
This table describes implemented namespaces. Call baseline app.getApiCatalog to discover the exact direct APIs supported by the running host, including each API’s access tier, required capability, and introduction version. The catalog is authoritative for version and capability negotiation.
Permissions And Capabilities
Section titled “Permissions And Capabilities”Declare sensitive reads and side effects in the top-level manifest field:
{ "permissions": { "capabilities": ["terminal.content.read", "terminal.write"] }}An empty or omitted permissions.capabilities does not produce an empty plugin. Every runtime plugin receives useful baseline, redacted calls, including connections.getSummaries, sessions.getSummary, terminal.getMetadata, ai.getCatalog, ide.getSummary, and app.getApiCatalog. Baseline metadata excludes raw terminal text, file contents, AI conversation text, credentials, and mutating operations.
Current capability names are:
| Capability | Meaning |
|---|---|
filesystem.read | Read file metadata/content through approved host APIs |
filesystem.write | Mutate files through approved host APIs |
filesystem.delete | Delete files or directory trees through approved host APIs |
network.forward.read | Read saved and active forwarding rules |
network.forward | Create or manage forwarding/network bridge behavior |
app.settings.read | Read host settings categories |
app.sync.refresh | Refresh host state after external synchronization |
connections.read | Read full saved-connection and endpoint projections |
connections.control | Connect, reconnect, or explicitly disconnect existing product-owned nodes |
sessions.read | Read full session trees, active-node projections, and event logs |
terminal.content.read | Read terminal targets, selection, scrollback, or search results |
terminal.write | Write terminal input, clear a buffer, or open a Telnet transport |
credentials.raw.read | Return raw plugin-scoped secret values |
credentials.manage | Store, test, or delete plugin-scoped secrets through the host broker |
network.http | Permit HTTP/HTTPS through the legacy request adapter |
sync.read | Read/export synchronization data |
sync.write | Refresh, apply, or import synchronization data |
transfers.read | Read and subscribe to transfer state |
ide.read | Read full IDE project and open-file projections |
ide.write | Open, edit, save, close, or refresh files in an existing IDE project |
ai.content.read | Read AI conversations and message content |
ai.write | Create/select/delete conversations, send text, or cancel generation |
host_tools.read | Read cached host state or capture typed Host Tools datasets |
host_tools.write | Run validated non-destructive process/container/service/tmux/task actions |
host_tools.destructive | Terminate processes or kill tmux resources |
host_tools.custom.execute | Run a static custom monitor command declared by this plugin |
notifications.read | Read notification title/body/scope projections |
notifications.manage | Mark, remove, clear, or change do-not-disturb state |
quick_commands.read | Read complete saved quick-command definitions |
quick_commands.manage | Create, update, or remove quick commands |
quick_commands.execute | Execute a saved quick command through normal risk confirmation |
theme.write | Select an installed built-in or custom theme |
cloud_sync.read | Read sanitized Cloud Sync history |
cloud_sync.control | Check, upload, preview pull, or configure automatic upload |
cloud_sync.apply | Apply the currently reviewed remote preview |
legacy.invoke | Call the compatibility api.invoke adapter |
events.emit | Emit a plugin-scoped custom event |
plugin.settings.write | Change plugin settings or plugin-scoped storage |
ui.write | Register/open plugin UI and show host UI effects |
runtime.process.trusted | Trust an unsandboxed process runtime; added implicitly for process plugins |
The Plugin Manager presents all requested sensitive capabilities together when a plugin is enabled. Activation waits for approval, then the runtime receives the effective permission set in the activate request. Treat that request as the source of truth. A version-only update does not prompt again and does not expand access. Adding a capability or changing the runtime boundary requires a new review; removing capabilities narrows access without another prompt.
Process plugins deserve special care: runtime.process.trusted is implicit and cannot be removed from their approval. The process is not confined by an OxideTerm OS sandbox, so its executable can exercise the operating-system access of the current user independently of Host API gates. Install and approve process plugins only from trusted publishers. WASM and process plugins must not be described as having the same security boundary.
HTTP requests currently use the compatibility adapter. A plugin must request both legacy.invoke and network.http, and must list plugin_http_request in contributes.apiCommands before calling api.invoke with that command.
AI tool metadata can also declare semantic capabilities such as terminal.observe, terminal.send, state.list, settings.read, settings.write, and plugin.invoke. Those declarations describe tool behavior for the host and model-facing surfaces; they do not bypass runtime permission checks.
Settings, Storage, And Secrets
Section titled “Settings, Storage, And Secrets”Use the smallest storage boundary that fits the data:
| Data | Boundary | Notes |
|---|---|---|
| User-visible plugin option | contributes.settings and settings.* | Typed values; safe for export/import when not secret |
| Plugin internal cache | storage.* | Plugin-scoped JSON KV with size limits |
| Token/password/key | secrets.* | OS keychain-backed plugin-scoped storage; raw reads require credentials.raw.read, while set/has/delete require credentials.manage |
| Cross-machine plugin preferences | plugin settings import/export or .oxide | Do not include raw secrets unless the encrypted portable flow explicitly supports them |
Never put credentials in plugin ids, names, labels, logs, AI prompts, event payloads, or support bundles.
Terminal, SFTP, Forwarding, IDE, And AI
Section titled “Terminal, SFTP, Forwarding, IDE, And AI”Native plugins should target stable node ids where possible:
- Use node/session snapshots rather than terminal tab assumptions.
- Terminal input hooks must fail open on error or timeout.
- SFTP mutating calls require file-write capability and an online node.
- SCP calls share the node-owned SSH connection. They support live pause/cancel, but a failed or disconnected SCP transfer restarts from byte zero.
- Forward calls require network-forward capability and should handle suspended nodes.
- IDE APIs expose project/open-file metadata, not arbitrary editor internals.
- AI APIs expose sanitized metadata and avoid tool message content.
Destructive actions should be represented as host-visible commands or AI tools with clear risk metadata.
Packaging And Installation
Section titled “Packaging And Installation”Use this package shape:
com.example.native-dashboard/ plugin.json bin/ native-dashboard README.md LICENSEPackage rules:
- The plugin root or a single nested plugin directory must contain
plugin.json. - Archive entries must not escape the plugin directory.
- Keep packages below the host package size and entry-count limits.
- Prefer one plugin id per package.
- Use semantic versions so update checks can compare releases.
- Declare the supported host range in
engines.oxideterm, for example>=2.3.0, <3.0.0, based on actual compatibility testing. - Keep runtime binaries platform-specific unless the entry is portable.
The marketplace retains each release’s host range and platform packages, and selects the highest compatible version. Newer incompatible releases display their requirements without replacing the installed plugin. Installation and startup both check the manifest range, including after app upgrades and downgrades. Incompatible plugins keep their files and settings but do not load. The official catalog is refreshed before startup activation and cached for offline use. Recorded compatibility corrections take precedence without changing package files. Unlisted older packages without a declared range remain permitted; older app builds do not gain these checks retroactively. See the publishing guide for the catalog format and release workflow.
During development:
- Copy the plugin directory into
<config-dir>/plugins/. - Open the desktop Plugin Manager.
- Enable or reload the plugin.
- Inspect state, errors, and permissions.
- Use CLI only for headless state/settings checks:
oxideterm plugins list --jsonoxideterm plugins enable com.example.native-dashboard --dry-run --jsonoxideterm plugins settings export --jsonInterface Reference
Section titled “Interface Reference”Manifest Interfaces
Section titled “Manifest Interfaces”interface NativePluginManifest { id: string; name: string; version: string; description?: string; author?: string; main?: string; // Tauri legacy JS entry; visible but not executed by Native. engines?: { oxideterm?: string }; manifestVersion?: number; format?: string; assets?: string; styles?: string[]; sharedDependencies?: Record<string, string>; repository?: string; checksum?: string; contributes?: NativePluginContributes; locales?: string; runtime?: NativePluginRuntime; permissions?: NativePluginPermissions;}
interface NativePluginPermissions { capabilities?: string[];}
interface NativePluginRuntime { kind: 'wasm' | 'process' | 'manifest-only' | 'language' | 'acp' | 'remote-desktop' | 'terminal-transport' | 'helper'; entry: string;}
interface NativePluginContributes { backgrounds?: string[]; language?: { id: string; displayName?: string; grammarName?: string; extensions?: string[]; fileNames?: string[]; highlights: string; parserSha256: string; highlightsSha256: string; }; tabs?: NativePluginTabDef[]; sidebarPanels?: NativePluginSidebarDef[]; activityBarItems?: NativePluginActivityBarItemDef[]; settings?: NativePluginSettingDef[]; terminalHooks?: NativePluginTerminalHooksDef; terminalTransports?: string[]; connectionHooks?: Array<'onConnect' | 'onDisconnect' | 'onReconnect' | 'onLinkDown'>; aiTools?: NativePluginAiToolDef[]; apiCommands?: string[]; hostMonitors?: NativePluginHostMonitorDef[];}
interface NativePluginHostMonitorDef { id: string; title: string; description?: string; commands: Partial<Record<'linux' | 'macos' | 'bsd' | 'windows' | 'default', string>>; output?: { format?: 'json' | 'jsonLines' | 'tsv' | 'textLines'; columns?: string[]; // Required only for tsv. maxRows?: number; // Default 1,000; maximum 2,000. }; timeoutSeconds?: number; // Default 10; range 1-30. maxOutputBytes?: number; // Default 262,144; range 1 KiB-1 MiB.}
interface NativePluginTabDef { id: string; title: string; icon: string;}
interface NativePluginSidebarDef { id: string; title: string; icon: string; position?: 'top' | 'bottom';}
interface NativePluginActivityBarItemDef { id: string; title: string; icon: string; command: string; position?: 'top' | 'bottom';}
interface NativePluginSettingDef { id: string; type: 'string' | 'number' | 'boolean' | 'select'; default: unknown; title: string; description?: string; options?: Array<{ label: string; value: string | number }>;}
interface NativePluginTerminalHooksDef { inputInterceptor?: boolean; outputProcessor?: boolean; shortcuts?: Array<{ key: string; command: string }>;}
interface NativePluginAiToolDef { name: string; description: string; parameters?: unknown; capabilities?: string[]; risk?: 'read' | 'write-file' | 'execute-command' | 'interactive-input' | 'destructive' | 'network-expose' | 'settings-change' | 'credential-sensitive'; targetKinds?: Array<'local-shell' | 'ssh-node' | 'terminal-session' | 'sftp-session' | 'ide-workspace' | 'app-tab' | 'mcp-server' | 'rag-index'>; resultSchema?: unknown;}Validation rules:
id,name,version, contribution ids, titles, and icons must be non-empty text.- Activity-bar item commands must be non-empty, item ids must be unique within the plugin, and
positionaccepts onlytoporbottom. - Tab, sidebar-panel, and activity-bar-item icons resolve against OxideTerm’s bundled Lucide icons. Matching ignores ASCII case, hyphens, and underscores; unsupported names fall back to
Puzzle. - Relative paths must stay inside the plugin directory.
terminalTransportscurrently acceptstelnet.apiCommandsentries are compatibility-adapter commands such asget_app_versionorplugin_http_request; direct host APIs are not listed there.- Omit
runtimefor a manifest-only plugin; an empty runtime entry is invalid. - Legacy
mainwithoutruntimeproduceslegacy-jsstate and is not executed.
Protocol Interfaces
Section titled “Protocol Interfaces”interface PluginProtocolEnvelope<T> { protocolVersion: 1; requestId?: string | null; payload: T;}
interface PluginRequest { requestId: string; kind: | { type: 'activate'; manifest: NativePluginManifest; permissions: PluginPermissionSet } | { type: 'deactivate' } | { type: 'callHostApi'; namespace: string; method: string; args?: unknown } | { type: 'dispatchCommand'; command: string; args?: unknown } | { type: 'sendEvent'; event: PluginEvent } | { type: 'cancelRequest'; requestId: string } | { type: 'health' } | { type: 'kill' }; timeoutMs?: number;}
interface PluginResponse { requestId: string; result: | { status: 'ok'; value: unknown } | { status: 'error'; error: PluginError };}
interface PluginError { kind: string; code: string; message: string;}
interface PluginPermissionSet { capabilities: string[]; allowedHostApis: string[];}
interface PluginEvent { name: string; payload?: unknown;}Outbound Message Interfaces
Section titled “Outbound Message Interfaces”type PluginOutboundMessage = | { type: 'registerContribution'; registration: PluginRegistration } | { type: 'disposeContribution'; registrationId: string } | { type: 'log'; level: 'debug' | 'info' | 'warn' | 'error'; message: string } | { type: 'reportProgress'; registrationId: string; value: unknown } | { type: 'runtimeReady' } | { type: 'runtimeError'; error: PluginError } | { type: 'emitEvent'; event: PluginEvent } | { type: 'callHostApi'; requestId: string; namespace: string; method: string; args?: unknown };
interface PluginRegistration { registrationId: string; pluginId: string; kind: | 'command' | 'keybinding' | 'context-menu' | 'status-bar' | 'tab' | 'sidebar-panel' | 'activity-bar-item' | 'terminal-input-interceptor' | 'terminal-output-processor' | 'terminal-shortcut' | 'event-subscription' | 'progress'; metadata?: unknown;}Registration Metadata
Section titled “Registration Metadata”| Registration kind | Required metadata | Optional metadata |
|---|---|---|
command | id or command, label | icon, shortcut, section |
keybinding | keybinding or key, command, label | when |
context-menu | target, items | target-specific item metadata |
status-bar | text | alignment, icon, tooltip |
tab | tabId, schema | title in schema |
sidebar-panel | panelId, schema | position, title in schema |
activity-bar-item | itemId | none; title, icon, position, and command come from the manifest |
event-subscription | event or namespace + method | nodeId filter for some event families |
terminal-input-interceptor | command or id | none |
terminal-output-processor | command or id | none |
terminal-shortcut | command or id | uses declared shortcut key from manifest |
progress | id or generated id | title, message |
Declarative UI Interfaces
Section titled “Declarative UI Interfaces”interface NativePluginDeclarativeUiSchema { translations?: Record<string, Record<string, string>>; componentVersion?: 1; kind?: 'form'; title?: string; description?: string; sections?: NativePluginDeclarativeUiSection[]; controls?: NativePluginDeclarativeUiControl[];}
interface NativePluginDeclarativeUiSection { id: string; title?: string; description?: string; controls?: NativePluginDeclarativeUiControl[];}
interface NativePluginDeclarativeUiControl { kind: | 'text' | 'textWorkbench' | 'password' | 'number' | 'checkbox' | 'select' | 'radioGroup' | 'radio-group' | 'slider' | 'segmentedControl' | 'segmented-control' | 'button' | 'iconButton' | 'icon-button' | 'stack' | 'row' | 'columns' | 'actionRow' | 'card' | 'toolbar' | 'alert' | 'markdown' | 'code' | 'codeBlock' | 'code-block' | 'statusBadge' | 'status-badge' | 'badge' | 'progress' | 'table' | 'list' | 'emptyState' | 'empty-state' | 'divider' | 'keyValue' | 'key-value' | 'keyValueRow' | 'key-value-row'; id?: string; label?: string; description?: string; placeholder?: string; icon?: string; variant?: 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link' | 'panel' | 'inset' | 'inspector'; tone?: 'neutral' | 'accent' | 'success' | 'warning' | 'error' | 'info'; size?: 'small' | 'default' | 'large' | 'icon'; gap?: 'none' | 'compact' | 'normal' | 'spacious'; value?: unknown; text?: string; language?: string; options?: Array<{ label: string; value: unknown }>; rows?: unknown[]; columns?: string[]; columnDefs?: Array<{ key: string; label: string; style?: 'primary' | 'meta' | 'mono' }>; children?: NativePluginDeclarativeUiControl[]; min?: number; max?: number; step?: number; indeterminate?: boolean; strong?: boolean; disabled?: boolean; loading?: boolean;}Interactive controls require a stable id: text, password, number,
checkbox, select, radio groups, segmented controls, sliders, buttons, and
icon buttons. Buttons are actionable only while disabled and loading are
both false. componentVersion defaults to 1 for compatibility, but plugins
should declare it explicitly so future component changes can be negotiated.
Host API Reference
Section titled “Host API Reference”All host APIs use:
interface HostCall { requestId: string; namespace: string; method: string; args?: unknown;}Calls must be allowed by allowedHostApis. Exact names and namespace wildcards are supported, for example connections.getAll and connections.*.
api.invoke requires legacy.invoke and has an additional allowlist: args.command must also appear in contributes.apiCommands. The plugin_http_request command additionally requires network.http.
api.invoke command | Native adapter |
|---|---|
ssh_get_pool_stats | SSH pool statistics |
list_connections | Saved/known connection snapshots |
get_app_version | Application version |
get_system_info | Platform, architecture, OS, and family |
sftp_cancel_transfer | Cancel transfer by transferId |
sftp_pause_transfer | Pause transfer by transferId |
sftp_resume_transfer | Resume transfer by transferId |
sftp_transfer_stats | Transfer queue statistics |
node_sftp_init | sftp.init adapter |
node_sftp_list_dir | sftp.listDir adapter |
node_sftp_stat | sftp.stat adapter |
node_sftp_preview | sftp.preview adapter |
node_sftp_write | sftp.write adapter |
node_sftp_download | sftp.download adapter |
node_sftp_upload | sftp.upload adapter |
node_sftp_mkdir | sftp.mkdir adapter |
node_sftp_delete | sftp.delete adapter |
node_sftp_delete_recursive | sftp.deleteRecursive adapter |
node_sftp_rename | sftp.rename adapter |
node_sftp_download_dir | sftp.downloadDir adapter |
node_sftp_upload_dir | sftp.uploadDir adapter |
node_sftp_tar_probe | sftp.tarProbe adapter |
node_sftp_tar_upload | sftp.tarUpload adapter |
node_sftp_tar_download | sftp.tarDownload adapter |
node_scp_probe | scp.capabilities adapter |
node_scp_download | scp.download adapter |
node_scp_upload | scp.upload adapter |
node_scp_download_dir | scp.downloadDirectory adapter |
node_scp_upload_dir | scp.uploadDirectory adapter |
list_port_forwards | forward.list adapter |
create_port_forward | forward.create adapter |
stop_port_forward | forward.stop adapter |
delete_port_forward | forward.delete adapter |
restart_port_forward | forward.restart adapter |
update_port_forward | forward.update adapter |
get_port_forward_stats | forward.getStats adapter |
stop_all_forwards | forward.stopAll adapter |
plugin_http_request | HTTP/HTTPS request adapter with a 10 MiB body limit |
App, Layout, Settings, I18n
Section titled “App, Layout, Settings, I18n”| Host API | Args | Result |
|---|---|---|
api.invoke | { command: string, args?: object } | Adapter-specific result for a command declared in contributes.apiCommands |
app.getTheme | {} | { name, isDark } |
app.getSettings | { category: string } | Settings section JSON |
app.getVersion | {} | Version string |
app.getPlatform | {} | Platform string |
app.getLocale | {} | Locale string |
app.getApiCatalog | {} | Implemented direct APIs with access tier, capability, and introduction version |
app.getPoolStats | {} | { activeConnections, totalSessions }-style stats |
app.getWorkspaceSummary | {} | Requires sessions.read; open tab IDs/titles/kinds/recording states, node IDs/titles/states/active-forward counts, and plugin issue IDs/names. No terminal content, paths or diagnostic text. Introduced after 2.2.0. |
app.refreshAfterExternalSync | {} | One-way workspace refresh effect |
ui.getLayout | {} | Layout snapshot |
ui.registerTabView | { tabId: string, schema: NativePluginDeclarativeUiSchema } | Declarative tab registration result |
ui.registerSidebarPanel | { panelId: string, schema: NativePluginDeclarativeUiSchema } | Declarative sidebar registration result |
ui.registerActivityBarItem | { itemId: string } | Standalone activity-bar action registration result |
ui.openTab | { tabId: string } | Opens/focuses declared plugin tab |
ui.openWorkspace | Tagged destination below | Requires ui.write; validates the destination and returns { queued: true }. Introduced after 2.2.0. |
ui.showToast | { title?: string, description?: string, variant?: string } | One-way toast effect |
ui.showNotification | { title?: string, body?: string, severity?: string } | One-way notification effect |
ui.showConfirm | { title: string, description: string } | boolean |
ui.showProgress | { title?: string, message?: string, registrationId?: string, id?: string } | { id, registrationId } |
events.emit | { name: string, payload?: unknown } | { emitted: true, event } |
settings.get | { key: string } | Plugin setting value or null |
settings.set | { key: string, value: unknown } | One-way setting write |
settings.exportSyncableSettings | {} | { revision, exportedAt, payload, warnings } |
settings.applySyncableSettings | { payload: object } | { revision, appliedPayload, warnings } |
i18n.getLanguage | {} | Language string |
i18n.t | { key: string } | Translated string or fallback key |
Connections And Sessions
Section titled “Connections And Sessions”Workspace destinations are { kind: "tab", id }, { kind: "sftp", nodeId },
{ kind: "forwards", nodeId }, or { kind: "page", page }. Page names are
sessions, files, plugins, cloudSync, notifications, and
localTerminal. Existing tabs retain their main/detached-window ownership.
Closed tab/node targets and unknown pages are rejected. Navigation does not expose
arbitrary command execution; saved connections use connections.connect and its
separate capability. The workspace summary is current state, not persisted project
or workspace history.
| Host API | Args | Result |
|---|---|---|
connections.getSummaries | {} | Redacted connection summaries; baseline |
connections.getSavedSummaries | {} | Redacted saved-connection IDs/names/groups for discovery; baseline |
connections.getAll | {} | Connection snapshots |
connections.getSaved | {} | Saved-connection projections without secrets, key paths, certificate paths, post-connect commands, or proxy credential references |
connections.get | { connectionId: string } | Connection snapshot or null |
connections.getState | { connectionId: string } | Connection state or null |
connections.getByNode | { nodeId: string } | Connection snapshot or null |
connections.connect | { connectionId: string } | { queued: true }; uses the existing saved-connection and prompt flow |
connections.openForm | { name: string, host: string, port: number, username?: string, group?: string } | { queued: true }; opens the native SSH form for review, without saving or connecting; requires connections.control |
connections.reconnect | { nodeId: string } | { queued: true }; reuses the existing node runtime |
connections.disconnect | { nodeId: string } | { queued: true }; opens the normal cascade confirmation before disconnecting the NodeRouter-owned subtree |
sessions.getTree | {} | Node tree snapshot |
sessions.getSummary | {} | Redacted session summary; baseline |
sessions.getActiveNodes | {} | Active/connected node snapshots |
sessions.getNodeState | { nodeId: string } | Node state or null |
eventLog.getEntries | { severity?: string, category?: string, limit?: number } | Event-log entries |
Product Data And Controls
Section titled “Product Data And Controls”connections.openForm requires a host newer than 2.2.0. Host-source plugins should
also check app.getApiCatalog before activation. Only plain connection metadata is
accepted: credentials, key paths, commands, and other fields are rejected. The user
sets authentication and any jump hosts in the existing form. A queued request will
not replace a form already being edited; its failure appears in the plugin manager.
Discovery owns no SSH transport and makes no persistent connection-store changes.
Workspace mutations return { queued: true } after schema and permission preflight. They execute on the product owner and appear in subsequent snapshots/events. Host Tools calls are synchronous because they return typed remote results.
| Host API | Capability | Args | Result |
|---|---|---|---|
notifications.getSummary | baseline | {} | Counts and DND state without content |
notifications.getAll | notifications.read | {} | Notification title/body/status/scope projections |
notifications.markRead | notifications.manage | { id: number } | { queued: true } |
notifications.markAllRead | notifications.manage | {} | { queued: true } |
notifications.setDnd | notifications.manage | { enabled: boolean } | { queued: true } |
notifications.remove / notifications.clear | notifications.manage | { id: number } / {} | { queued: true } |
quickCommands.getMetadata | baseline | {} | Discovery metadata without command bodies |
quickCommands.getAll | quick_commands.read | {} | Complete categories and command definitions |
quickCommands.execute | quick_commands.execute | { id: string } | { queued: true }; normal command-risk confirmation still applies |
quickCommands.upsert | quick_commands.manage | { id?, name, command, category?, description?, hostPattern?, hostPatterns?, parameters?, protocols?, confirmation? } | { queued: true } |
quickCommands.remove | quick_commands.manage | { id: string } | { queued: true } |
theme.getTokens | baseline | {} | Complete effective terminal/UI/metric/radius/spacing/motion tokens |
theme.getAvailable | baseline | {} | Active, built-in, and custom theme identifiers |
theme.setActive | theme.write | { themeId: string } | { queued: true } |
hostTools.getSnapshot | host_tools.read | { nodeId: string } | Cached system identity, metrics, processes, Docker, and service state; no full process arguments |
hostTools.getExtensions | baseline | {} | This plugin’s monitor metadata, with command strings omitted |
hostTools.capture | host_tools.read | { nodeId, osType, resource, preset?, limit? } | Typed snapshot for docker, services, logs, tmux, ports, filesystems, packages, or scheduledTasks |
hostTools.execute | host_tools.write | { nodeId, osType, resource, action, target, ...actionArgs } | { success, exitCode, truncated } |
| hostTools.terminate | host_tools.destructive | { nodeId, osType, resource: 'process' \| 'tmux', action, target } | { success, exitCode, truncated } |
| hostTools.runExtension | host_tools.custom.execute | { nodeId, osType, monitorId } | { monitorId, success, data, rowCount, exitCode, truncated } |
| cloudSync.getSummary | baseline | {} | Safe status/progress/dirty/conflict metadata |
| cloudSync.getHistory | cloud_sync.read | {} | History without errors, remote revisions, destinations, credentials, or payloads |
| cloudSync.check | cloud_sync.control | {} | { queued: true } |
| cloudSync.upload | cloud_sync.control | { force?: boolean } | { queued: true } |
| cloudSync.pullPreview | cloud_sync.control | {} | { queued: true }; does not apply data or persist unsaved panel drafts |
| cloudSync.applyPreview | cloud_sync.apply | {} | { queued: true }; applies only the currently reviewed preview |
| cloudSync.setAutoUpload | cloud_sync.control | { enabled: boolean, intervalMinutes?: number } | { queued: true }; interval is clamped to at least five minutes |
Quick Command parameters use { name, label, kind?, defaultValue?, choices?, required? }; kind is text or choice. protocols accepts local, ssh, mosh, telnet, serial, and tmux, while confirmation is inherit or always. Templates insert {{param.name}} verbatim; use {{param.name|sh}} when the value must be quoted as one POSIX shell word.
Host Tools never creates a second SSH transport. It resolves the current nodeId through NodeRouter, uses the existing connection, validates every command argument with product command builders, and omits raw standard error. Capture errors are redacted before serialization.
Plugins can extend Host Tools beyond the built-in monitor set by declaring static monitor commands in contributes.hostMonitors:
{ "permissions": { "capabilities": ["host_tools.custom.execute"] }, "contributes": { "hostMonitors": [{ "id": "nginx-workers", "title": "Nginx workers", "description": "Reports worker PIDs and states", "commands": { "linux": "ps -C nginx -o pid=,stat= | awk '{printf \"{\\\"pid\\\":%s,\\\"state\\\":\\\"%s\\\"}\\n\", $1, $2}'" }, "output": { "format": "jsonLines", "maxRows": 200 }, "timeoutSeconds": 10, "maxOutputBytes": 262144 }] }}The command is selected from linux, macos, bsd, or windows, then falls back to default. Commands are static: runtime parameters and template substitution are intentionally unsupported, so a plugin cannot turn runExtension into an arbitrary-command endpoint. Manifest commands are plaintext package metadata and must never contain passwords, tokens, private keys, or other secrets. Because a shell command cannot be proven read-only, execution uses the separate high-risk host_tools.custom.execute capability even when the monitor is observational. The host limits execution time, captured bytes, and parsed rows; it never returns standard error or failed-command stdout. Successful output is parsed as json, jsonLines, tsv, or textLines before crossing the plugin boundary.
A declaration does not automatically add a built-in Host Tools page. The plugin owns presentation and polling through its declarative tab or sidebar, calling getExtensions for discovery and runExtension when it needs a fresh sample.
Host Tools action names are closed enums: process supports stop, continue, and renice (nice) through execute, plus terminate and kill through terminate; docker supports start, stop, and restart; service supports start, stop, restart, reload, enable, and disable; tmux supports renameSession, renameWindow (name), and sendPaneCommand (command), while killSession, killWindow, and killPane require terminate; scheduledTask supports runNow (unit), enable, and disable (source). osType selects the product’s validated Linux, macOS/Darwin, BSD, or Windows command builder; it is not interpolated into a shell command.
Terminal
Section titled “Terminal”| Host API | Args | Result |
|---|---|---|
terminal.getMetadata | {} | Redacted terminal metadata; baseline |
terminal.getActiveTarget | {} | Active terminal target snapshot |
terminal.getNodeBuffer | { nodeId: string } | Terminal buffer text or null |
terminal.getNodeSelection | { nodeId: string } | Selected text or null |
terminal.search | { nodeId: string, query: string, regex?: boolean, caseSensitive?: boolean, wholeWord?: boolean, maxResults?: number } | Search matches |
terminal.getScrollBuffer | { nodeId: string, start?: number, limit?: number } | Bounded scrollback rows |
terminal.getBufferSize | { nodeId: string } | Buffer size summary |
terminal.writeToActive | { text: string } | boolean |
terminal.writeToNode | { nodeId: string, text: string } | boolean |
terminal.clearBuffer | { nodeId: string } | Clear result |
terminal.openTelnet | { host: string, port?: number } | { sessionId, info } |
SFTP And Transfers
Section titled “SFTP And Transfers”| Host API | Capability | Args | Result |
|---|---|---|---|
sftp.init | filesystem.read | { nodeId: string } | Session status |
sftp.listDir | filesystem.read | { nodeId: string, path: string } | Directory entries |
sftp.stat | filesystem.read | { nodeId: string, path: string } | File metadata |
sftp.readFile | filesystem.read | { nodeId: string, path: string } | File content payload |
sftp.preview | filesystem.read | { nodeId: string, path: string } | Preview payload |
sftp.download | filesystem.read | { nodeId: string, remotePath: string, localPath: string } | Transfer result |
sftp.downloadDir | filesystem.read | { nodeId: string, remotePath: string, localPath: string } | Transfer result |
sftp.tarProbe | filesystem.read | { nodeId: string, path: string } | Tar capability/probe result |
sftp.tarDownload | filesystem.read | { nodeId: string, remotePath: string, localPath: string } | Transfer result |
sftp.writeFile | filesystem.write | { nodeId: string, path: string, content: string } | Write result |
sftp.write | filesystem.write | { nodeId: string, path: string, content: string } | Write result |
sftp.upload | filesystem.write | { nodeId: string, localPath: string, remotePath: string } | Transfer result |
sftp.uploadDir | filesystem.write | { nodeId: string, localPath: string, remotePath: string } | Transfer result |
sftp.tarUpload | filesystem.write | { nodeId: string, localPath: string, remotePath: string } | Transfer result |
sftp.mkdir | filesystem.write | { nodeId: string, path: string } | Directory result |
sftp.delete | filesystem.write | { nodeId: string, path: string } | Delete result |
sftp.deleteRecursive | filesystem.write | { nodeId: string, path: string } | Recursive delete result |
sftp.rename | filesystem.write | { nodeId: string, oldPath: string, newPath: string } | Rename result |
scp.capabilities | filesystem.read | { nodeId: string } | { supported, recursive, restartResume: false } |
scp.download | filesystem.read | { nodeId: string, remotePath: string, localPath: string, transferId?: string } | SCP transfer result |
scp.downloadDirectory | filesystem.read | { nodeId: string, remotePath: string, localPath: string, transferId?: string } | SCP transfer result |
scp.upload | filesystem.write | { nodeId: string, localPath: string, remotePath: string, transferId?: string } | SCP transfer result |
scp.uploadDirectory | filesystem.write | { nodeId: string, localPath: string, remotePath: string, transferId?: string } | SCP transfer result |
transfers.getAll | read | {} | Transfer snapshots |
transfers.getByNode | read | { nodeId: string } | Transfer snapshots for node |
SCP is a POSIX compatibility transport, not a browsing API. Use sftp.listDir, sftp.stat, and previews when SFTP is available. A result reports protocol: "scp" and restartResume: false; a retry after channel or node loss starts the object again instead of continuing from a byte offset.
Forwarding
Section titled “Forwarding”| Host API | Capability | Args | Result |
|---|---|---|---|
forward.list | read | { nodeId?: string } | Active forward rules |
forward.listSavedForwards | read | {} | Saved forward rules |
forward.exportSavedForwardsSnapshot | read | {} | Saved-forward sync snapshot |
forward.applySavedForwardsSnapshot | network.forward | { snapshot: object, strategy?: string } | Apply result |
forward.create | network.forward | { nodeId: string, type: 'local' | 'remote' | 'dynamic', localPort?: number, remoteHost?: string, remotePort?: number } | Created rule |
forward.stop | network.forward | { id: string } | Stop result |
forward.delete | network.forward | { id: string } | Delete result |
forward.restart | network.forward | { id: string } | Restart result |
forward.update | network.forward | { id: string, ...changes } | Update result |
forward.stopAll | network.forward | { nodeId?: string } | Stop-all result |
forward.getStats | read | {} | Forwarding stats |
Sync, Storage, Secrets
Section titled “Sync, Storage, Secrets”| Host API | Args | Result |
|---|---|---|
storage.get | { key: string } | JSON value or null |
storage.set | { key: string, value: unknown } | One-way write |
storage.remove | { key: string } | One-way delete |
secrets.get | { key: string } | Secret string or null; requires credentials.raw.read |
secrets.getMany | { keys: string[] } | Map of key to secret/null; requires credentials.raw.read |
secrets.set | { key: string, value: string } | Empty value deletes; requires credentials.manage |
secrets.has | { key: string } | boolean; requires credentials.manage |
secrets.delete | { key: string } | Delete result; requires credentials.manage |
sync.listSavedConnections | {} | Saved connection snapshots |
sync.refreshSavedConnections | {} | Saved connection snapshots after refresh |
sync.exportSavedConnectionsSnapshot | {} | Saved connection sync snapshot |
sync.applySavedConnectionsSnapshot | { snapshot: object, conflictStrategy?: 'rename' | 'skip' | 'replace' | 'merge' } | Apply result |
sync.getLocalSyncMetadata | {} | Revision metadata |
sync.preflightExport | { connectionIds?: string[], embedKeys?: boolean, includeManagedKeys?: boolean } | Export preflight result. Managed keys are excluded by default for plugin-driven sync. |
sync.exportOxide | { connectionIds?: string[], password: string, embedKeys?: boolean, includeManagedKeys?: boolean, includeManagedKeyPassphrases?: boolean, includeAppSettings?: boolean, selectedAppSettingsSections?: string[], includePluginSettings?: boolean, selectedPluginIds?: string[], progressRegistrationId?: string } | .oxide bytes/metadata result. Managed keys are excluded by default for plugin-driven sync. |
sync.validateOxide | { fileData: number[] } | .oxide metadata |
sync.previewImport | { fileData: number[], password: string, conflictStrategy?: string, progressRegistrationId?: string } | Import preview |
sync.importOxide | { fileData: number[], password: string, conflictStrategy?: string, progressRegistrationId?: string, selectedNames?: string[], selectedForwardIds?: string[], importForwards?: boolean, importPortableSecrets?: boolean, importAppSettings?: boolean, selectedAppSettingsSections?: string[], importPluginSettings?: boolean, selectedPluginIds?: string[], importQuickCommands?: boolean } | Import result |
IDE, AI, Profiler
Section titled “IDE, AI, Profiler”| Host API | Args | Result |
|---|---|---|
ide.isOpen | {} | boolean |
ide.getSummary | {} | Redacted IDE state summary; baseline |
ide.getProject | {} | Project snapshot or null |
ide.getOpenFiles | {} | Open-file snapshots |
ide.getActiveFile | {} | Active file snapshot or null |
ide.openFile | { path: string, nodeId?: string } | { queued: true } |
ide.replaceActiveText | { text: string, nodeId?: string } | { queued: true } |
ide.insertActiveText | { text: string, nodeId?: string } | { queued: true } |
ide.saveActive | { nodeId?: string } | { queued: true }; preserves remote conflict checks |
ide.closeFile | { path: string, nodeId?: string } | { queued: true }; preserves dirty-buffer confirmation |
ide.refreshProject | { nodeId?: string } | { queued: true } |
ai.getConversations | {} | Sanitized conversation summaries |
ai.getCatalog | {} | Redacted provider and model catalog; baseline |
ai.getMessages | { conversationId: string } | Sanitized messages |
ai.getActiveProvider | {} | Active provider summary or null |
ai.getAvailableModels | {} | Model names |
ai.createConversation | { title?: string } | { queued: true } |
ai.selectConversation | { conversationId: string } | { queued: true } |
ai.sendMessage | { content: string } | { queued: true }; credential-like text is redacted before model context is built |
ai.cancelGeneration | {} | { queued: true } |
ai.deleteConversation | { conversationId: string } | { queued: true } |
ai.clearConversations | {} | { queued: true } |
profiler.getMetrics | { nodeId: string } | Metrics snapshot or null; systemInfo contains the remote system name, version, architecture, boot-time milliseconds, and uptime seconds when available |
profiler.getHistory | { nodeId: string, limit?: number } | Metrics history |
profiler.isRunning | { nodeId: string } | boolean |
Events Reference
Section titled “Events Reference”Subscribe by registering event-subscription with event, or with namespace + method for Tauri-style names.
| Namespace + method | Event key | Required capability |
|---|---|---|
app.onThemeChange | app.themeChanged | — |
app.onSettingsChange | app.settingsChanged | app.settings.read |
i18n.onLanguageChange | i18n.languageChanged | — |
settings.onChange | settings.changed | — |
ui.onLayoutChange | ui.layoutChanged | — |
sessions.onTreeChange | sessions.treeChanged | sessions.read |
sessions.onNodeStateChange | sessions.nodeStateChanged | — |
eventLog.onEntry | eventLog.entry | sessions.read |
forward.onSavedForwardsChange | forward.savedForwardsChanged | network.forward.read |
transfers.onProgress | transfers.progress | transfers.read |
transfers.onComplete | transfers.complete | transfers.read |
transfers.onError | transfers.error | transfers.read |
profiler.onMetrics | profiler.metrics | — |
ide.onFileOpen | ide.fileOpen | ide.read |
ide.onFileClose | ide.fileClose | ide.read |
ide.onActiveFileChange | ide.activeFileChanged | ide.read |
ai.onMessage | ai.message | — (metadata only; no message content) |
events.onConnect | lifecycle.onConnect | — |
events.onDisconnect | lifecycle.onDisconnect | — |
events.onLinkDown | lifecycle.onLinkDown | — |
events.onReconnect | lifecycle.onReconnect | — |
Terminal input interceptors require both terminal.content.read and terminal.write. Terminal output processors require terminal.content.read.
Custom plugin events use the events.on / events.emit path and are scoped by plugin id so one plugin cannot claim arbitrary global event names.
Debugging
Section titled “Debugging”Start with the Plugin Manager:
- Check whether the plugin is
ready,disabled,legacy-js,error, orauto-disabled. - Check manifest validation errors before debugging runtime code.
- Use stderr for process diagnostics.
- Keep stdout strictly JSON Lines protocol.
- Register one contribution at a time while developing.
- Confirm that
registrationIdvalues are stable and unique per plugin. - Confirm that every host call is declared and allowed.
- Use
oxideterm plugins list --jsonfor headless state. - Use
oxideterm plugins settings export --jsonto inspect plugin settings.
If a process plugin activates but no UI appears, verify both sides:
contributes.tabsorcontributes.sidebarPanelsdeclares the surface id.- The runtime registration uses the same
tabIdorpanelId. - The schema
kindisform. - The schema contains at least one section or top-level control.
- Required controls have
id.
For a standalone activity-bar action, verify contributes.activityBarItems, the runtime itemId, the ui.write capability, and the plugin’s dispatchCommand handler instead of looking for a declarative UI schema.
Migration Notes
Section titled “Migration Notes”Do not port Tauri plugins by copying main.js unchanged.
| Tauri concept | Native replacement |
|---|---|
main.js ESM activate(ctx) | Process/WASM runtime using JSON protocol |
| React tab/sidebar components | Declarative native UI schema |
| CSS files | Host-rendered controls and theme |
window.__OXIDE__ | Host API calls and protocol frames |
| Direct JS event bus | event-subscription registration and sendEvent requests |
| Tauri command imports | Manifest-declared host API calls |
| Browser asset URL | Future host-owned asset handle |
Keep the public plugin intent, manifest ids, settings ids, and tool metadata where possible. Replace browser implementation details with native process/WASM protocol behavior.