Skip to main content

Module native_plugin

vtcode_core::skills

Module native_plugin 

Source
Expand description

Native Plugin System for VT Code Skills

This module provides support for loading native code plugins as skills using libloading. Native plugins offer high-performance, pre-compiled skill logic that can be discovered and loaded dynamically at runtime.

§Safety

Loading native code plugins requires careful security considerations:

  • Plugins are loaded from canonicalized, explicitly trusted locations only
  • Callers must obtain user approval before loading an untrusted plugin
  • Plugin signatures can be verified (future enhancement)
  • This module does not sandbox plugin execution; native code runs with process privileges
  • VT Code serializes plugin FFI calls for ABI v1
  • All plugin operations go through VT Code’s tool system

The unsafe blocks in this module are necessary for FFI:

  • Loading dynamic libraries (Library::new)
  • Calling plugin functions (version_fn, metadata_fn, execute_fn, free_string_fn)
  • Converting C strings (CStr::from_ptr)

Symbol resolution is centralized in the safe get_plugin_symbol wrapper; the remaining raw calls cannot be made safe without losing the ability to load arbitrary plugin code. Each call site carries its own // SAFETY: comment documenting the specific invariant that justifies the unsafe operation.

§Plugin Structure

A native plugin skill consists of:

  • plugin.json - Metadata (name, description, version, author)
  • lib<name>.dylib (macOS) or lib<name>.so (Linux) or <name>.dll (Windows)
  • Optional: README.md, scripts/, templates/

§Plugin ABI

Plugins must export the following C-compatible symbols:

  • vtcode_plugin_version() - Returns ABI version
  • vtcode_plugin_metadata() - Returns plugin metadata JSON
  • vtcode_plugin_execute() - Main execution entry point

§Example

ⓘ
use vtcode_core::skills::native_plugin::{NativePlugin, PluginLoader};

let mut loader = PluginLoader::new();
let plugin = loader.load_plugin("/path/to/plugin").unwrap();
let result = plugin.execute(&input).unwrap();

Structs§

NativePlugin
A loaded native plugin
PluginContext
Plugin execution context passed to plugin functions
PluginLoader
Plugin loader responsible for discovering and loading native plugins.
PluginMetadata
Plugin metadata structure
PluginResult
Plugin execution result

Constants§

PLUGIN_ABI_VERSION
Current plugin ABI version Increment this when breaking changes are made to the plugin interface

Traits§

NativePluginTrait
Native plugin trait for type-erased plugin operations

Functions§

validate_plugin_structure
Validate a plugin directory structure