Skip to content

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.

  1. Build A Running Plugin
  2. Runtime Conversation
  3. Host Calls In Plugin Code
  4. UI And Event Recipes
  5. Common Failure Checks
  6. Native Plugin Model
  7. Native Versus Tauri Plugins
  8. Plugin Directory
  9. Minimal Manifest-Only Plugin
  10. Background Material Packs
  11. Editor Language Plugins
  12. Process Runtime Plugin
  13. Protocol Frames
  14. Runtime Registrations
  15. Connection providers
  16. Declarative Native UI
  17. Host API Calls
  18. Permissions And Capabilities
  19. Settings, Storage, And Secrets
  20. Terminal, SFTP, Forwarding, IDE, And AI
  21. Packaging And Installation
  22. Interface Reference
  23. Host API Reference
  24. Events Reference
  25. Debugging
  26. Migration Notes

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.js

The process entry must be a real executable inside the plugin directory. On macOS/Linux, give the script an executable bit:

Terminal window
chmod +x hello-native/bin/hello.js

Use 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:

  • stdout is reserved for protocol frames, one JSON object per line.
  • stderr is 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-panel or tab contribution.
  • A returnable host call is sent as an outbound callHostApi frame; 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.

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 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.

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.

If the plugin never activates:

  • Check that runtime.entry points 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 requestId and payload requestId.
  • Check that protocolVersion is 1.
  • Check stderr for plugin diagnostics.

If UI does not appear:

  • contributes.tabs or contributes.sidebarPanels must declare the surface id.
  • Runtime registration must use the same tabId or panelId.
  • registration.pluginId must match the manifest id.
  • metadata.schema.kind should be form.
  • Interactive controls such as button, text, password, number, checkbox, and select need stable id values.

If a standalone activity-bar action does not appear or run:

  • contributes.activityBarItems must declare the item id, title, icon, command, and placement.
  • Runtime registration must use kind: "activity-bar-item" with the same itemId.
  • The plugin must request ui.write and handle the declared dispatchCommand value.
  • 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 in contributes.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.
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.

AreaTauri/Web PluginNative Plugin
RuntimeESM main.js loaded through dynamic importGeneral extensions use process, wasm, or manifest-only; specialized runtimes are listed above
UIReact components and CSSDeclarative native UI schema rendered by GPUI
Shared moduleswindow.__OXIDE__Not available
StylingCSS and theme variablesHost-owned native controls only
Host APIFrozen PluginContext objectJSON protocol calls with namespace/method/args
Legacy JSExecutable in TauriShown as legacy-js, not executed
Security boundaryBrowser membrane plus Tauri commandsRuntime 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.

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.

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 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.

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.

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.entry must be a relative path inside the plugin directory.
  • The entry must exist for process and wasm runtimes.
  • 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.

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 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:

KindPurpose
commandAdd a command-palette action dispatched back to the plugin
keybindingAdd a keybinding after built-in shortcuts miss
context-menuAdd context menu items for declared targets
status-barAdd a host-owned status item
tabRegister declarative UI for a declared tab
sidebar-panelRegister declarative UI for a declared panel
activity-bar-itemRegister a standalone left activity-bar action declared by the manifest
event-subscriptionSubscribe to host events
terminal-input-interceptorTransform or suppress terminal input
terminal-output-processorProcess terminal output before parser input
terminal-shortcutAttach terminal shortcut handling to a command
progressCreate 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.

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. Its ui.event.surfaceId is the instance ID. Update it with a tab registration whose metadata contains connectionId: instanceId and schema; use a distinct registration ID per instance.
  • {"kind":"terminal","args":[...]}: launch the declared terminalEntry directly 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 approved terminal.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.

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:

KindNotes
stack, row, card, toolbarLayout components; render nested children using bounded host layouts
columnsEqual-width columns that wrap in narrow containers
actionRowFlexible first child with trailing actions aligned to the right; a leading button fills its slot
text, password, number, checkbox, selectShared field controls; require stable id values
radioGroup, radio-group, segmentedControl, segmented-control, sliderShared choice/range controls; require stable id values
button, iconButton, icon-buttonShared actions; actionable only with id and while enabled/not loading; icon buttons also require icon and label
alertSemantic host notice with tone, optional icon, title, and description
markdownParsed using OxideTerm’s Markdown renderer; background images and local-file links are disabled
code, codeBlock, code-blockCode block
statusBadge, status-badge, badgeShared status pill with semantic tone/strength
progressShared progress display; values may be 0..1 or 0..100
table, listBounded, virtualized shared data components
emptyState, empty-stateShared empty state with optional icon/description
dividerShared separator
keyValue, key-value, keyValueRow, key-value-rowKey/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.

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.

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:

NamespaceTypical use
connectionsRead and control saved/live connection lifecycle
sessionsRead node tree and active node state
terminalObserve buffers or send approved input
sftpList/read/write remote files through node-owned SFTP
scpTransfer files through node-owned legacy SCP when SFTP is unavailable
forwardList/create/stop forwards
transfersObserve transfer state
profilerRead node metrics
hostToolsRead cached host state, capture typed datasets, and run validated actions
eventLogRead app event log
notificationsRead or manage notification-center entries
quickCommandsRead, manage, or execute saved quick commands
cloudSyncRead safe sync status/history and control sync operations
themeRead full effective tokens and select an installed theme
ideObserve and edit the active IDE project
aiRead sanitized AI data and control conversations/generation
appTheme, platform, version, settings snapshots
settingsPlugin and syncable settings
storagePlugin-scoped JSON KV
sync.oxide, saved connections, plugin settings, sync metadata
secretsPlugin-scoped secret storage
uiToasts, 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.

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:

CapabilityMeaning
filesystem.readRead file metadata/content through approved host APIs
filesystem.writeMutate files through approved host APIs
filesystem.deleteDelete files or directory trees through approved host APIs
network.forward.readRead saved and active forwarding rules
network.forwardCreate or manage forwarding/network bridge behavior
app.settings.readRead host settings categories
app.sync.refreshRefresh host state after external synchronization
connections.readRead full saved-connection and endpoint projections
connections.controlConnect, reconnect, or explicitly disconnect existing product-owned nodes
sessions.readRead full session trees, active-node projections, and event logs
terminal.content.readRead terminal targets, selection, scrollback, or search results
terminal.writeWrite terminal input, clear a buffer, or open a Telnet transport
credentials.raw.readReturn raw plugin-scoped secret values
credentials.manageStore, test, or delete plugin-scoped secrets through the host broker
network.httpPermit HTTP/HTTPS through the legacy request adapter
sync.readRead/export synchronization data
sync.writeRefresh, apply, or import synchronization data
transfers.readRead and subscribe to transfer state
ide.readRead full IDE project and open-file projections
ide.writeOpen, edit, save, close, or refresh files in an existing IDE project
ai.content.readRead AI conversations and message content
ai.writeCreate/select/delete conversations, send text, or cancel generation
host_tools.readRead cached host state or capture typed Host Tools datasets
host_tools.writeRun validated non-destructive process/container/service/tmux/task actions
host_tools.destructiveTerminate processes or kill tmux resources
host_tools.custom.executeRun a static custom monitor command declared by this plugin
notifications.readRead notification title/body/scope projections
notifications.manageMark, remove, clear, or change do-not-disturb state
quick_commands.readRead complete saved quick-command definitions
quick_commands.manageCreate, update, or remove quick commands
quick_commands.executeExecute a saved quick command through normal risk confirmation
theme.writeSelect an installed built-in or custom theme
cloud_sync.readRead sanitized Cloud Sync history
cloud_sync.controlCheck, upload, preview pull, or configure automatic upload
cloud_sync.applyApply the currently reviewed remote preview
legacy.invokeCall the compatibility api.invoke adapter
events.emitEmit a plugin-scoped custom event
plugin.settings.writeChange plugin settings or plugin-scoped storage
ui.writeRegister/open plugin UI and show host UI effects
runtime.process.trustedTrust 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.

Use the smallest storage boundary that fits the data:

DataBoundaryNotes
User-visible plugin optioncontributes.settings and settings.*Typed values; safe for export/import when not secret
Plugin internal cachestorage.*Plugin-scoped JSON KV with size limits
Token/password/keysecrets.*OS keychain-backed plugin-scoped storage; raw reads require credentials.raw.read, while set/has/delete require credentials.manage
Cross-machine plugin preferencesplugin settings import/export or .oxideDo 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.

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.

Use this package shape:

com.example.native-dashboard/
plugin.json
bin/
native-dashboard
README.md
LICENSE

Package 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:

  1. Copy the plugin directory into <config-dir>/plugins/.
  2. Open the desktop Plugin Manager.
  3. Enable or reload the plugin.
  4. Inspect state, errors, and permissions.
  5. Use CLI only for headless state/settings checks:
Terminal window
oxideterm plugins list --json
oxideterm plugins enable com.example.native-dashboard --dry-run --json
oxideterm plugins settings export --json
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 position accepts only top or bottom.
  • 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.
  • terminalTransports currently accepts telnet.
  • apiCommands entries are compatibility-adapter commands such as get_app_version or plugin_http_request; direct host APIs are not listed there.
  • Omit runtime for a manifest-only plugin; an empty runtime entry is invalid.
  • Legacy main without runtime produces legacy-js state and is not executed.
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;
}
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 kindRequired metadataOptional metadata
commandid or command, labelicon, shortcut, section
keybindingkeybinding or key, command, labelwhen
context-menutarget, itemstarget-specific item metadata
status-bartextalignment, icon, tooltip
tabtabId, schematitle in schema
sidebar-panelpanelId, schemaposition, title in schema
activity-bar-itemitemIdnone; title, icon, position, and command come from the manifest
event-subscriptionevent or namespace + methodnodeId filter for some event families
terminal-input-interceptorcommand or idnone
terminal-output-processorcommand or idnone
terminal-shortcutcommand or iduses declared shortcut key from manifest
progressid or generated idtitle, message
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.

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 commandNative adapter
ssh_get_pool_statsSSH pool statistics
list_connectionsSaved/known connection snapshots
get_app_versionApplication version
get_system_infoPlatform, architecture, OS, and family
sftp_cancel_transferCancel transfer by transferId
sftp_pause_transferPause transfer by transferId
sftp_resume_transferResume transfer by transferId
sftp_transfer_statsTransfer queue statistics
node_sftp_initsftp.init adapter
node_sftp_list_dirsftp.listDir adapter
node_sftp_statsftp.stat adapter
node_sftp_previewsftp.preview adapter
node_sftp_writesftp.write adapter
node_sftp_downloadsftp.download adapter
node_sftp_uploadsftp.upload adapter
node_sftp_mkdirsftp.mkdir adapter
node_sftp_deletesftp.delete adapter
node_sftp_delete_recursivesftp.deleteRecursive adapter
node_sftp_renamesftp.rename adapter
node_sftp_download_dirsftp.downloadDir adapter
node_sftp_upload_dirsftp.uploadDir adapter
node_sftp_tar_probesftp.tarProbe adapter
node_sftp_tar_uploadsftp.tarUpload adapter
node_sftp_tar_downloadsftp.tarDownload adapter
node_scp_probescp.capabilities adapter
node_scp_downloadscp.download adapter
node_scp_uploadscp.upload adapter
node_scp_download_dirscp.downloadDirectory adapter
node_scp_upload_dirscp.uploadDirectory adapter
list_port_forwardsforward.list adapter
create_port_forwardforward.create adapter
stop_port_forwardforward.stop adapter
delete_port_forwardforward.delete adapter
restart_port_forwardforward.restart adapter
update_port_forwardforward.update adapter
get_port_forward_statsforward.getStats adapter
stop_all_forwardsforward.stopAll adapter
plugin_http_requestHTTP/HTTPS request adapter with a 10 MiB body limit
Host APIArgsResult
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.openWorkspaceTagged destination belowRequires 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

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 APIArgsResult
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

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 APICapabilityArgsResult
notifications.getSummarybaseline{}Counts and DND state without content
notifications.getAllnotifications.read{}Notification title/body/status/scope projections
notifications.markReadnotifications.manage{ id: number }{ queued: true }
notifications.markAllReadnotifications.manage{}{ queued: true }
notifications.setDndnotifications.manage{ enabled: boolean }{ queued: true }
notifications.remove / notifications.clearnotifications.manage{ id: number } / {}{ queued: true }
quickCommands.getMetadatabaseline{}Discovery metadata without command bodies
quickCommands.getAllquick_commands.read{}Complete categories and command definitions
quickCommands.executequick_commands.execute{ id: string }{ queued: true }; normal command-risk confirmation still applies
quickCommands.upsertquick_commands.manage{ id?, name, command, category?, description?, hostPattern?, hostPatterns?, parameters?, protocols?, confirmation? }{ queued: true }
quickCommands.removequick_commands.manage{ id: string }{ queued: true }
theme.getTokensbaseline{}Complete effective terminal/UI/metric/radius/spacing/motion tokens
theme.getAvailablebaseline{}Active, built-in, and custom theme identifiers
theme.setActivetheme.write{ themeId: string }{ queued: true }
hostTools.getSnapshothost_tools.read{ nodeId: string }Cached system identity, metrics, processes, Docker, and service state; no full process arguments
hostTools.getExtensionsbaseline{}This plugin’s monitor metadata, with command strings omitted
hostTools.capturehost_tools.read{ nodeId, osType, resource, preset?, limit? }Typed snapshot for docker, services, logs, tmux, ports, filesystems, packages, or scheduledTasks
hostTools.executehost_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.

Host APIArgsResult
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 }
Host APICapabilityArgsResult
sftp.initfilesystem.read{ nodeId: string }Session status
sftp.listDirfilesystem.read{ nodeId: string, path: string }Directory entries
sftp.statfilesystem.read{ nodeId: string, path: string }File metadata
sftp.readFilefilesystem.read{ nodeId: string, path: string }File content payload
sftp.previewfilesystem.read{ nodeId: string, path: string }Preview payload
sftp.downloadfilesystem.read{ nodeId: string, remotePath: string, localPath: string }Transfer result
sftp.downloadDirfilesystem.read{ nodeId: string, remotePath: string, localPath: string }Transfer result
sftp.tarProbefilesystem.read{ nodeId: string, path: string }Tar capability/probe result
sftp.tarDownloadfilesystem.read{ nodeId: string, remotePath: string, localPath: string }Transfer result
sftp.writeFilefilesystem.write{ nodeId: string, path: string, content: string }Write result
sftp.writefilesystem.write{ nodeId: string, path: string, content: string }Write result
sftp.uploadfilesystem.write{ nodeId: string, localPath: string, remotePath: string }Transfer result
sftp.uploadDirfilesystem.write{ nodeId: string, localPath: string, remotePath: string }Transfer result
sftp.tarUploadfilesystem.write{ nodeId: string, localPath: string, remotePath: string }Transfer result
sftp.mkdirfilesystem.write{ nodeId: string, path: string }Directory result
sftp.deletefilesystem.write{ nodeId: string, path: string }Delete result
sftp.deleteRecursivefilesystem.write{ nodeId: string, path: string }Recursive delete result
sftp.renamefilesystem.write{ nodeId: string, oldPath: string, newPath: string }Rename result
scp.capabilitiesfilesystem.read{ nodeId: string }{ supported, recursive, restartResume: false }
scp.downloadfilesystem.read{ nodeId: string, remotePath: string, localPath: string, transferId?: string }SCP transfer result
scp.downloadDirectoryfilesystem.read{ nodeId: string, remotePath: string, localPath: string, transferId?: string }SCP transfer result
scp.uploadfilesystem.write{ nodeId: string, localPath: string, remotePath: string, transferId?: string }SCP transfer result
scp.uploadDirectoryfilesystem.write{ nodeId: string, localPath: string, remotePath: string, transferId?: string }SCP transfer result
transfers.getAllread{}Transfer snapshots
transfers.getByNoderead{ 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.

Host APICapabilityArgsResult
forward.listread{ nodeId?: string }Active forward rules
forward.listSavedForwardsread{}Saved forward rules
forward.exportSavedForwardsSnapshotread{}Saved-forward sync snapshot
forward.applySavedForwardsSnapshotnetwork.forward{ snapshot: object, strategy?: string }Apply result
forward.createnetwork.forward{ nodeId: string, type: 'local' | 'remote' | 'dynamic', localPort?: number, remoteHost?: string, remotePort?: number }Created rule
forward.stopnetwork.forward{ id: string }Stop result
forward.deletenetwork.forward{ id: string }Delete result
forward.restartnetwork.forward{ id: string }Restart result
forward.updatenetwork.forward{ id: string, ...changes }Update result
forward.stopAllnetwork.forward{ nodeId?: string }Stop-all result
forward.getStatsread{}Forwarding stats
Host APIArgsResult
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
Host APIArgsResult
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

Subscribe by registering event-subscription with event, or with namespace + method for Tauri-style names.

Namespace + methodEvent keyRequired capability
app.onThemeChangeapp.themeChanged—
app.onSettingsChangeapp.settingsChangedapp.settings.read
i18n.onLanguageChangei18n.languageChanged—
settings.onChangesettings.changed—
ui.onLayoutChangeui.layoutChanged—
sessions.onTreeChangesessions.treeChangedsessions.read
sessions.onNodeStateChangesessions.nodeStateChanged—
eventLog.onEntryeventLog.entrysessions.read
forward.onSavedForwardsChangeforward.savedForwardsChangednetwork.forward.read
transfers.onProgresstransfers.progresstransfers.read
transfers.onCompletetransfers.completetransfers.read
transfers.onErrortransfers.errortransfers.read
profiler.onMetricsprofiler.metrics—
ide.onFileOpenide.fileOpenide.read
ide.onFileCloseide.fileCloseide.read
ide.onActiveFileChangeide.activeFileChangedide.read
ai.onMessageai.message— (metadata only; no message content)
events.onConnectlifecycle.onConnect—
events.onDisconnectlifecycle.onDisconnect—
events.onLinkDownlifecycle.onLinkDown—
events.onReconnectlifecycle.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.

Start with the Plugin Manager:

  • Check whether the plugin is ready, disabled, legacy-js, error, or auto-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 registrationId values are stable and unique per plugin.
  • Confirm that every host call is declared and allowed.
  • Use oxideterm plugins list --json for headless state.
  • Use oxideterm plugins settings export --json to inspect plugin settings.

If a process plugin activates but no UI appears, verify both sides:

  • contributes.tabs or contributes.sidebarPanels declares the surface id.
  • The runtime registration uses the same tabId or panelId.
  • The schema kind is form.
  • 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.

Do not port Tauri plugins by copying main.js unchanged.

Tauri conceptNative replacement
main.js ESM activate(ctx)Process/WASM runtime using JSON protocol
React tab/sidebar componentsDeclarative native UI schema
CSS filesHost-rendered controls and theme
window.__OXIDE__Host API calls and protocol frames
Direct JS event busevent-subscription registration and sendEvent requests
Tauri command importsManifest-declared host API calls
Browser asset URLFuture 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.