Platform architecture

Plugin Platform v3 is the contract between the lla host and plugin code. A plugin is a package holding a manifest, a compiled entrypoint and checksums. The host speaks one protobuf protocol to it, through either of two runtimes.

Read this page when you need to know what the host guarantees, for example when you debug a load failure or write a binding for another language. To write a plugin, use Developing plugins.

Crates

The directories in the repository are short, and the published crate names are longer. All four crates share the lla version.

Plugin authors depend on lla_plugin_sdk. The host's implementation lives in lla/src/plugin/.

How a listing calls a plugin

1. The host reads enabled_plugins, adds any --enable-plugin names, and discovers those packages.
2. It walks and filters the entries, then maps the current view to a format name.
3. It sends each enabled plugin that declares the format a BatchDecorateRequest, in chunks of at most 512 entries.
4. It fills in typed values for declared fields that have only a display string.
5. If the view prints plugin text, it sends a BatchFormatRequest and places the returned strings on each row.

A single-file target and archive members go through Decorate and FormatField instead of the batch messages. The fuzzy view decorates and never formats. Machine output decorates and reads typed_fields, and CSV has fixed columns without plugin fields.

Manifest reference lists the format name for each view.

Discovery and loading

The host searches these directories in order. The first package with a given name wins, and later ones are reported as shadowed.

An ordinary listing only loads enabled plugins and those named on the command line. lla list-plugins and lla use load everything. lla plugin run and lla plugin info load the named plugin, and accept names from [plugin_aliases].

Each package goes through these checks before the host uses it:

1. Parse and validate plugin.toml.
2. Check that the API range includes 3.
3. Verify checksums.toml, which must exist and cover the entrypoint and manifest.
4. Load the entrypoint. A component also needs its permissions approved.
5. Compare the embedded manifest with the packaged file.
6. Compare the runtime's registered actions with the declared ones. No action may have a blank name, usage or description.

A package that fails prints a ⚠️ line on stderr and stays unavailable. The listing carries on.

Native ABI

A native plugin exports one symbol, _plugin_create_v3, which returns a pointer to a PluginApiV3 struct:

#[repr(C)]
pub struct PluginApiV3 {
    pub abi_version: u32,
    pub min_host_api: u32,
    pub max_host_api: u32,
    pub manifest_ptr: *const u8,
    pub manifest_len: usize,
    pub handle_request: extern "C" fn(*mut std::ffi::c_void, *const u8, usize) -> PluginBufferV3,
    pub free_response: extern "C" fn(PluginBufferV3),
    pub destroy: extern "C" fn(*mut PluginApiV3),
    pub context: *mut std::ffi::c_void,
}

Requests and responses are protobuf byte buffers, so no Rust layout crosses the library boundary. The plugin owns each response buffer until the host hands it back through free_response. export_plugin! generates all of this, holds the plugin in a Mutex, and catches panics so they return an error to the host.

The loader inspects a library's symbols without calling them. A library with _plugin_create_v2 or _plugin_create is reported as uses API vN and is disabled; migrate it to API v3, and none of its code runs. See Migrating to v3.

Wire protocol

Every request and response is a PluginMessage from interface/src/plugin.proto.

StructuredErrorResponse carries a code and a message. ErrorResponse carries a plain string.

Typed values have these variants: null, string, integer, float, boolean, bytes, timestamp, path, list and object. The SDK's dispatch function decodes requests, so plugin code using the Plugin trait never touches the protocol.

WebAssembly runtime

A build with the wasm-plugins feature embeds Wasmtime and runs components against WASI Preview 2 and the lla:[email protected] world:

package lla:[email protected];
 
interface host {
    clipboard-write: func(text: string) -> result<_, string>;
    open-url: func(url: string) -> result<_, string>;
}
 
world plugin {
    import host;
    export manifest: func() -> string;
    export handle: func(request: list<u8>) -> result<list<u8>, string>;
}

manifest returns the embedded plugin.toml. handle takes and returns the same protobuf bytes as the native ABI.

The runtime only exists on x86_64 and ARM64. Official Linux, macOS and Windows binaries for those architectures include it. The i686 Linux binaries report components as unsupported, and the NetBSD binary leaves Wasmtime out.

Each request builds a new store and instantiates the component, so values in self or in statics don't survive between calls. Keep state in /data. Compiled code is cached in <cache dir>/lla/wasmtime, or in LLA_WASMTIME_CACHE_DIR when set.

A component gets these resources:

The scope table shows what each filesystem scope opens.

Limits

Native plugins have no timeout, so a slow native plugin slows the listing it runs in.

A component that hits a limit or fails produces an error with a tag instead of crashing lla:

Permission model

Native and WebAssembly plugins have different trust models. Read the runtime line in lla plugin info before you trust the permission list.

lla plugin permissions NAME prints the declared permissions alone. For native plugins, it ends with native permissions are declarations; native code is fully trusted.

The grant flow for a component works like this:

1. lla install compares the manifest with any stored grant for the same id, and lists the new permissions.
2. It asks Approve these WASM sandbox permissions? [y/N]. Without a terminal it fails closed.
3. On approval it records the plugin's version and full permission set.
4. At load the host checks that the stored grant covers the manifest. If it doesn't, loading fails with is missing approved permissions in.

A manifest with no permissions needs no grant. An update that adds a permission prompts again, while one that removes a permission doesn't.

Contract checks by stage

Each stage checks different things, which is why a source install can succeed for a plugin the doctor rejects.

The doctor's functional checks use a temporary text file and a temporary directory, and they point LLA_PLUGIN_DATA_DIR at a temporary location. lla clean moves packages that fail to <plugins_dir>/.quarantine/<timestamp>.

Output type and table schema are checked each time an action runs.

Package layout

~/.config/lla/plugins/
├── metadata.toml             Source of each plugin, used by lla update
├── plugin-grants.toml        Approved component permissions
├── file_score/
│   ├── checksums.toml
│   ├── libfile_score.dylib   or .so, .dll, .wasm
│   └── plugin.toml
└── .quarantine/              Packages removed by lla clean

A plugin's private data shares the <name> directory by default, for example config.toml from ConfigManager. Only the files in checksums.toml are verified, so private data doesn't affect the package check.

Builds without plugins

Cargo features decide what the host can load.

Without dynamic-plugins, a static stub replaces the plugin manager and reports Dynamic plugins are unavailable in this build; install a full-featured lla binary.