Files
openidea/docs/en/plugins/api/index.mdx
T
Lucas 43b5c69ecd feat(plugins): add bounded background WebSockets (API 1.6) (#2544)
Plugins get a host-owned WebSocket resource (net.websocket-connect → websocket with id/send/drain/close; dropping it closes the transport). The connection is bound to the project it was opened for, needs the endpoint's net:<host> grant, uses WSS outside loopback with the shared rustls config, and is capped at eight per plugin. Request headers (secret placeholders expanded) go with the handshake, except the ones the handshake owns; an empty subprotocol requests none; the handshake is bounded by the call's I/O budget. Incoming frames queue in a bounded FIFO, signalled by the websocket-ready event. Checked-in components are rebuilt for API 1.6.

Co-authored-by: SorPuti <56741582+SorPuti@users.noreply.github.com>
2026-11-12 10:09:15 +08:00

86 lines
16 KiB
Plaintext

---
title: "API reference"
description: "Every interface of the openidea:plugin WIT package, with a one-line summary and a link to its source."
---
The plugin API is the WIT package `openidea:plugin@1.6.0` in [`wit/`](https://github.com/l0ng-ai/openidea/tree/main/wit). The WIT files are the reference: each interface, type and function is documented in comments there. 1.6.0 is the version on `main`; the latest released version is 1.4.0, whose WIT is kept in [`sdk/rust/openidea-plugin/tests/api/released/`](https://github.com/l0ng-ai/openidea/tree/main/sdk/rust/openidea-plugin/tests/api/released).
<Info>
A generated API reference is planned. Until then, use the WIT files below, `cargo doc` for the Rust SDK
([`sdk/rust/openidea-plugin`](https://github.com/l0ng-ai/openidea/tree/main/sdk/rust/openidea-plugin)), and the table
mapping every SDK function to its WIT function and capability in
[`plugins/README.md`](https://github.com/l0ng-ai/openidea/blob/main/plugins/README.md#the-api).
</Info>
## Worlds
[`plugin.wit`](https://github.com/l0ng-ai/openidea/blob/main/wit/plugin.wit) defines the worlds: the base `plugin` world (every import, plus the `lifecycle`, `commands` and `event-handler` exports) and one optional world per extra export (`plugin-providers`, `plugin-views`, `plugin-hover`, …). See [Architecture and sandbox](/en/plugins/architecture#worlds-imports-and-exports).
## Host interfaces (imports)
The plugin calls these. Most are gated by a [capability](/en/plugins/capabilities).
| Interface | File | Summary |
| ---------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `types` | [types.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/types.wit) | Shared types: positions (0-based lines, UTF-16 columns), ranges, errors, the `extension` carrier for later additions |
| `log` | [host.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/host.wit) | Writes to the IDE log, tagged with the plugin id |
| `ui` | [host.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/host.wit) | Notifications (also for one project, API 1.5), status bar items, context keys, pickers, input boxes, confirmations, folder chooser, clipboard, opening URLs, the UI language |
| `storage` | [host.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/host.wit) | The plugin's persistent key-value storage (64 MiB) |
| `command-runner` | [host.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/host.wit) | Runs IDE actions and other plugins' commands (API 1.4, `ide.commands`) |
| `output` | [host.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/host.wit) | Named, read-only Output tabs per plugin (API 1.4) |
| `workspace` | [workspace.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/workspace.wit) | Open projects: reading, writing, finding and searching files, symbols, the project of a path, opening a project |
| `editor` | [workspace.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/workspace.wit) | Text editors: document, selections, versioned edits, reveal; open editors and opening files |
| `invocation` | [workspace.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/workspace.wit) | Where a command or event came from: its project, editor and selected paths |
| `vcs` | [workspace.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/workspace.wit) | Git for a project's repository: status, remotes, fetch, log, blame, diff |
| `fs` | [fs.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/fs.wit) | Files outside the open projects (`fs.read:` / `fs.write:`) and the plugin's private directory |
| `decorations` | [decorations.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/decorations.wit) | Editor annotations and project-tree badges (API 1.4) |
| `commit` | [commit.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/commit.wit) | The commit being prepared and its message |
| `events` | [events.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/events.wit) | Subscribing to workbench events, optionally filtered by path |
| `tasks` | [events.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/events.wit) | Long-running work with a progress indicator and a longer time budget |
| `diagnostics` | [io.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/io.wit) | Publishing problems for files and reading the Problems view |
| `net` | [io.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/io.wit) | HTTP(S) requests (`net:` / `net.http:` / `net:ask`) |
| `secrets` | [io.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/io.wit) | Secrets in the OS keychain, used only through `{{secret:<name>}}` in requests |
| `process` | [io.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/io.wit) | Running approved programs once, with an environment, or behind a handle |
| `ipc` | [io.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/io.wit) | Local sockets and named pipes on the project machine (API 1.4) |
| `auth` | [io.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/io.wit) | OAuth loopback redirects received on the desktop (API 1.4) |
| `views` | [views.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/views.wit) | Refreshing and revealing views, messages to web views, terminals, content tabs, opening locations |
| `view-types` | [views.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/views.wit) | The declarative view model: trees, lists, forms, tables, messages, `html` bodies, view events |
| `settings` | [views.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/views.wit) | The plugin's own settings, project over global, or the schema default |
| `run` | [run.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/run.wit) | Starting the plugin's run configurations in the Run tool window (API 1.4) |
| `run-targets` | [run-targets.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/run-targets.wit) | Project run targets that wrap commands, owned by the plugin (API 1.4) |
| `database` | [database.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/database.wit) | The plugin's own project data sources and their credentials (API 1.4) |
| `mcp` | [mcp.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/mcp.wit) | The command line of the built-in MCP server's stdio bridge, never its URL or token (API 1.4) |
| `detail-types` | [details.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/details.wit) | What the pane beside the Services tree shows for a plugin's node |
## Plugin interfaces (exports)
The IDE calls these. The first three are in every code plugin; the rest are optional and each comes with its own world.
| Interface | File | Summary |
| -------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `lifecycle` | [exports.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/exports.wit) | `activate` and `deactivate` of an instance |
| `commands` | [exports.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/exports.wit) | Runs one of the plugin's declared commands |
| `event-handler` | [exports.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/exports.wit) | Receives batches of subscribed events |
| `syntax-provider` | [exports.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/exports.wit) | Highlighting, outline and folding for plugin languages without a grammar |
| `run-target-validation` | [exports.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/exports.wit) | Checks a launch through one of the plugin's run targets before it starts (API 1.5) |
| `providers` | [providers.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/providers.wit) | Completion, inline completion, code actions, navigation and line markers for declared languages |
| `language-features` | [language-features.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/language-features.wit) | Formatting, signature help, highlights, links, code lenses, folds, colours, symbols, gutter actions and more (API 1.4) |
| `injections` | [injections.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/injections.wit) | Ranges of embedded languages inside a document (API 1.4) |
| `hover-provider` | [hover.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/hover.wit) | Markdown added to the hover of any language |
| `inlay-hints-provider` | [inlay.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/inlay.wit) | Inline hints in any language |
| `semantic-tokens-provider` | [semantic.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/semantic.wit) | Semantic colouring in any language |
| `diagnostics-provider` | [diagnostics.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/diagnostics.wit) | Problems in the current, possibly unsaved document |
| `file-actions` | [file-actions.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/file-actions.wit) | Quick fixes and refactorings that create, rename or delete files |
| `document-indexer` | [indexing.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/indexing.wit) | Cross-file definitions, references and gutter markers, indexed in the background |
| `endpoints-provider` | [endpoints.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/endpoints.wit) | A project's HTTP endpoints for Search Everywhere and the HTTP client |
| `view-provider` | [views.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/views.wit) | Content and events of declared views and custom editors |
| `detail-provider` | [details.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/details.wit) | The detail pane of the plugin's nodes in the Services tool window |
| `commit-checker` | [commit.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/commit.wit) | Before-commit checks |
| `run-configurations` | [run.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/run.wit) | Dynamic run configurations for a project (API 1.4) |
| `test-results` | [run.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/run.wit) | Parsing test output and selecting tests to rerun (API 1.4) |
| `mcp-provider` | [mcp.wit](https://github.com/l0ng-ai/openidea/blob/main/wit/mcp.wit) | Tools the plugin contributes to the built-in MCP server (API 1.4) |
## Other languages
The SDK carries an identical copy of the WIT files in [`sdk/rust/openidea-plugin/wit`](https://github.com/l0ng-ai/openidea/tree/main/sdk/rust/openidea-plugin/wit). To write a plugin in another language, generate bindings for the `plugin` world (or an optional world) with your language's component-model tooling, build the component, and validate it with `openidea-plugin check`.