src — plugins

Module: src-plugins Cohesion: 0.80 Members: 0

src — plugins

The src/plugins module is the core of Native Engine's extensibility, enabling the system to integrate with various Large Language Model (LLM) providers, execute custom tools, and offer dynamic capabilities. It encompasses bundled providers, a robust plugin marketplace, secure sandboxing, conflict detection, hot-reloading for development, and integration with code graph analysis tools like GitNexus.

This documentation covers:

Core Concepts

At the heart of the plugin system are several key interfaces and types:

Bundled LLM Providers (src/plugins/bundled/)

This directory contains pre-integrated LLM providers that are shipped with Native Engine. They are automatically discovered and registered if their respective environment variables are set. This provides out-of-the-box support for popular LLM services.

The getBundledProviders() function in src/plugins/bundled/index.ts serves as the central entry point for discovering and instantiating these providers. It checks for the necessary environment variables and returns an array of active PluginProvider instances. 

graph TD
    A[getBundledProviders] --> B{createAzureProvider};
    A --> C{createBedrockProvider};
    A --> D{createCopilotProvider};
    A --> E{createFireworksProvider};
    A --> F{createGroqProvider};
    A --> G{createOllamaProvider};
    A --> H{createOpenRouterProvider};
    A --> I{createTogetherProvider};
    A --> J{createVllmProvider};
    B -- AZURE_OPENAI_ENDPOINT --> AzureProvider;
    C -- AWS_BEDROCK_REGION --> BedrockProvider;
    D -- GITHUB_COPILOT_TOKEN --> CopilotProvider;
    E -- FIREWORKS_API_KEY --> FireworksProvider;
    F -- GROQ_API_KEY --> GroqProvider;
    G -- OLLAMA_HOST --> OllamaProvider;
    H -- OPENROUTER_API_KEY --> OpenRouterProvider;
    I -- TOGETHER_API_KEY --> TogetherProvider;
    J -- VLLM_BASE_URL --> VllmProvider;

Common Provider Structure

Each bundled provider follows a similar pattern:

  1. Environment Variable Check: A function (e.g., getAzureEndpoint(), getBedrockRegion()) checks for the presence of a specific environment variable. If not found, the createXProvider() function returns null, effectively disabling the provider.
  2. Configuration Retrieval: Functions to retrieve API keys, regions, or base URLs from environment variables.
  3. buildOnboardingHooks(): For providers that support it, this function creates the ProviderOnboardingHooks object. These hooks handle:

  1. createXProvider(): The main factory function that returns a PluginProvider object. It defines:

Specific Bundled Providers

Plugin Management System

The plugin management system orchestrates the entire lifecycle of plugins, from discovery to secure execution.

PluginMarketplace (src/plugins/marketplace.ts)

The PluginMarketplace class manages the discovery, installation, updates, and loading of plugins. It acts as the central registry for all plugins, whether installed from a remote registry or loaded locally.

Key Responsibilities:

Core Flow:

  1. initialize(): Ensures plugin directories exist and loads previously installed plugins from manifest.json.
  2. loadInstalledPlugins(): Reads manifest.json and attempts to loadPlugin() for each enabled plugin.
  3. loadPlugin(pluginId):

  1. saveManifest(): Persists the state of installed plugins to disk.

PluginManager (from src/plugins/plugin-system.ts - exported by index.ts)

While the full source for PluginManager is not provided, its exports in src/plugins/index.ts and its interactions implied by other files (like IsolatedPluginRunner and PluginMarketplace) suggest it acts as a higher-level orchestrator.

Inferred Responsibilities:

IsolatedPluginRunner (src/plugins/isolated-plugin-runner.ts)

This class is critical for security and stability, running each plugin in its own Node.js Worker Thread. This isolates plugin code from the main application process, preventing malicious or buggy plugins from affecting the core system.

Key Features:

Security Measures:

PluginConflictDetector (src/plugins/conflict-detection.ts)

This class prevents naming collisions between plugin IDs, tool names, and built-in functionalities. It ensures that plugins can be registered safely without overwriting or conflicting with existing components.

Key Features:

Usage Flow (registerPlugins):

  1. Plugins are sorted by priority (required plugins first).
  2. For each plugin, checkConflicts() is called. If conflicts exist, the plugin is blocked.
  3. Plugin tools are resolved (if dynamic).
  4. checkToolConflicts() is run for the plugin's tools.
  5. Each tool is checked against the allowlist using isToolAllowed().
  6. Allowed tools are registered, and metadata (PluginToolMeta) is attached.

PluginHotReloader (src/plugins/hot-reload.ts)

Designed to enhance developer experience, the PluginHotReloader watches plugin directories for file changes and triggers reloads without requiring a full application restart.

Key Features:

Core Flow:

  1. watch(pluginId, pluginPath, manifest): Sets up a file system watcher for a given plugin.
  2. handleFileChange(): Filters changes based on shouldIgnore() and shouldWatch() patterns.
  3. triggerReload(): Debounces the reload, then calls the reloadCallback and emits events.

GitNexus Integration (src/plugins/gitnexus/)

GitNexus provides code graph analysis capabilities, allowing Native Engine to understand the structure, relationships, and business processes within a codebase. This integration is currently in "stub mode" but lays the groundwork for powerful code intelligence features.

GitNexusManager (src/plugins/gitnexus/GitNexusManager.ts)

This class manages the GitNexus CLI tool, handling its installation, repository analysis, and the lifecycle of its MCP (Model Context Protocol) server.

Key Responsibilities:

GitNexusMCPClient (src/plugins/gitnexus/GitNexusMCPClient.ts)

The GitNexusMCPClient is responsible for communicating with a running GitNexus MCP server to query the code graph.

Key Features (Stubbed):

Note on Stub Mode: Currently, all GitNexusMCPClient methods return empty or default results. The actual MCP transport and integration with the gitnexus CLI will be implemented in a future release.

GitPinnedMarketplace (src/plugins/git-pinned-marketplace.ts)

This marketplace manages plugins that are "pinned" to specific Git commit SHAs. This ensures reproducibility and auditability for plugin installations, especially for internal or highly sensitive plugins.

Key Features:

How it Connects to the Rest of the Codebase

The src/plugins module is a foundational layer for Native Engine's capabilities:

Contribution Guide

Adding a New Bundled LLM Provider

  1. Create a new file: In src/plugins/bundled/, create your-provider-name-provider.ts.
  2. Implement PluginProvider:

  1. Export createYourProvider(): This function should return PluginProvider | null.
  2. Register in index.ts:

  1. Update src/plugins/types.ts: If your provider introduces new capabilities or specific model types, ensure DiscoveredModel and related types can accommodate them.

Understanding Plugin Lifecycle for Custom Plugins

If you are developing a custom plugin for Native Engine, understanding the lifecycle is key:

  1. Manifest (package.json or manifest.json): Your plugin must declare its id, name, version, main entry point, engines.grok compatibility, and permissions.
  2. Installation: When a user installs your plugin via the PluginMarketplace, it's downloaded, extracted, and its metadata is stored.
  3. Loading (PluginMarketplace.loadPlugin):

  1. Activation (IsolatedPluginRunner.activate): Your plugin's activate() method (if defined) is called, allowing it to perform setup tasks.
  2. Execution:

  1. Deactivation (IsolatedPluginRunner.deactivate): Your plugin's deactivate() method is called, allowing it to clean up resources.
  2. Unloading (PluginMarketplace.unloadPlugin): The IsolatedPluginRunner worker thread is terminated, completely removing your plugin's code from memory.

Always design your plugins with security and resource limits in mind, as they will run in a sandboxed environment. Request only the necessary permissions and handle errors gracefully.