LibreChat/packages/api/src/plugins/deployment.ts
Danny Avila 5c939d129b
🔌 feat: Add Agent Plugins (Experimental) (#14704)
* 🔌 feat: Add Agent Plugins v1.0.0 Support

Implements the Agent Plugins 1.0.0 specification so LibreChat can load
portable plugin packages: a `plugin.json` manifest, `skills/` holding Agent
Skills, `mcp.json` describing MCP servers, and reverse-domain extension
directories.

- Validate the closed `plugin.json` schema, selecting rules from `$schema`
  without retrieving it. Unknown top-level fields and a non-object
  `extensions` field are reported and ignored; every other violation rejects
  the plugin.
- Enforce plugin-root containment through realpath, including for paths whose
  leaf does not exist, and apply the narrowest failure boundary per component.
- Map `mcp.json` onto LibreChat MCP options across stdio, Streamable HTTP, and
  legacy HTTP+SSE, bypassing the config loader's `${VAR}` process-env
  expansion so plugin values never resolve against the server environment.
- Expand only `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`, once and non-recursively,
  in `args`, `env` values, and `cwd`; supply both variables to the subprocess
  after configured `env`, and reject entries that declare them.
- Discover skills from the immediate children of `skills/` only, reusing the
  deployment skill loader so plugin skills are ordinary deployment skills with
  a distinct id namespace.
- Read LibreChat's `ai.librechat` extension directory and hand
  `hooks/hooks.json` to the Claude hook compatibility layer.
- Load operator-installed plugins from `DEPLOYMENT_PLUGINS_DIR` at startup,
  merging their skills into the deployment skill registry and their MCP
  servers into the app config. Plugins never displace a configured server or
  deployment skill.
- Add `cwd` to the stdio MCP transport, which the specification requires and
  LibreChat did not previously support.

Component failures stay isolated: a malformed `mcp.json`, an invalid skill, or
a bad hooks document never prevents the rest of a plugin from loading.

* 🔒 fix: Contain Agent Plugins config at the runtime boundary

Review of #14704 surfaced that every real finding sat where the loader's
output crosses into LibreChat's existing runtime, not in the specification
logic. The loader deliberately left plugin placeholders literal, but
downstream layers re-processed the same fields and undid it.

- Mark plugin MCP configuration with `source: 'plugin'` and return it verbatim
  from `processMCPEnv`. Without this a remote plugin could declare
  `Authorization: Bearer ${OPENAI_API_KEY}` and receive host credentials at its
  own origin. The gate reads the configuration rather than a caller-supplied
  flag, so no future call site can reintroduce the leak by omitting it.
- Skip `preProcessGraphTokens` for plugin configuration as well; it resolves
  placeholders into headers, url, and args on the same path.
- Reject plugin server names that change under `normalizeServerName`. Tool keys
  embed the normalized name while request-time resolution uses the raw name, so
  an unstable name published tools that nothing could resolve.
- Reject `__proto__`, `constructor`, and `prototype` as server names, and merge
  plugin servers with `Object.defineProperty` and an own-property conflict
  check, so a package cannot reach a prototype setter or collide with an
  inherited member.
- Enforce manifest-name uniqueness before components are accepted; two packages
  sharing a name would share one `PLUGIN_DATA` directory.
- Isolate a failed data-directory creation to the single plugin instead of
  rejecting the whole scan.
- Prefix rejected-plugin diagnostics with the directory, which is the only
  identifier a package without a valid manifest has.
- Type extension namespace contents as JSON rather than `unknown`, and correct
  the header field-value comment to name obs-text.

Verified end to end from the built package: a plugin declaring an environment
placeholder in a header reaches the transport with the placeholder intact while
operator-authored configuration still resolves normally.

* 🔇 fix: Report Agent Plugin hooks that will not run

The loader reads `ai.librechat/hooks/hooks.json`, but nothing registers the
resulting plan, and startup supplies no hook capabilities. A package declaring
hooks was therefore accepted in silence, leaving an operator to believe the
hooks ran.

Detect the document when no capabilities are registered and report it as
unsupported, so the limitation is visible in startup diagnostics rather than
inferred from behavior that never happens.

* 🧯 test: Restore MCP startup test mocks

Carries the two mock additions from #14711 so this branch can prove itself
green. `initializeMCPs` now calls `syncStaticTools`, which the server startup
specs do not stub, so they fail on every branch that has not picked this up.
Drops out of the rebase once #14711 lands.

Co-authored-by: Danny Avila <danny@librechat.ai>
2026-08-09 08:10:22 -04:00

266 lines
8.3 KiB
TypeScript

import fs from 'fs';
import path from 'path';
import { logger } from '@librechat/data-schemas';
import type { MCPOptions } from 'librechat-data-provider';
import type { LoadedPlugin, PluginDiagnostic } from './types';
import type { PluginHookCapabilities } from '~/agents/hooks';
import type { DeploymentSkill } from '~/skills';
import {
DEPLOYMENT_PLUGINS_DIR_ENV,
DEFAULT_DEPLOYMENT_PLUGINS_DIR,
DEPLOYMENT_PLUGIN_DATA_DIR_ENV,
DEFAULT_DEPLOYMENT_PLUGIN_DATA_DIR,
} from './constants';
import { loadPlugin } from './load';
export interface DeploymentPluginOptions {
projectRoot?: string;
env?: NodeJS.ProcessEnv;
hookCapabilities?: PluginHookCapabilities;
}
interface DirectoryResolution {
directory: string;
explicitlyConfigured: boolean;
}
function resolveDirectory(
envKey: string,
fallback: string,
options: DeploymentPluginOptions,
): DirectoryResolution {
const env = options.env ?? process.env;
const projectRoot = options.projectRoot ?? process.cwd();
const configured = env[envKey]?.trim();
const raw = configured && configured.length > 0 ? configured : fallback;
return {
directory: path.isAbsolute(raw) ? raw : path.resolve(projectRoot, raw),
explicitlyConfigured: configured != null && configured.length > 0,
};
}
export function resolveDeploymentPluginDirectory(
options: DeploymentPluginOptions = {},
): DirectoryResolution {
return resolveDirectory(DEPLOYMENT_PLUGINS_DIR_ENV, DEFAULT_DEPLOYMENT_PLUGINS_DIR, options);
}
export function resolveDeploymentPluginDataDirectory(
options: DeploymentPluginOptions = {},
): string {
return resolveDirectory(
DEPLOYMENT_PLUGIN_DATA_DIR_ENV,
DEFAULT_DEPLOYMENT_PLUGIN_DATA_DIR,
options,
).directory;
}
/**
* Holds the plugins installed by the operator. Names are unique across the
* registry: a later plugin declaring an already-claimed plugin name, skill
* name, or MCP server name loses and the conflict is reported.
*/
export class DeploymentPluginRegistry {
private readonly plugins: LoadedPlugin[] = [];
private readonly pluginsByName = new Map<string, LoadedPlugin>();
private readonly skillsByName = new Map<string, DeploymentSkill>();
private readonly serversByName = new Map<string, MCPOptions>();
private readonly rejections: PluginDiagnostic[] = [];
constructor(
private readonly directory: string | null,
loaded: LoadedPlugin[] = [],
) {
for (const plugin of loaded) {
this.add(plugin);
}
}
private add(plugin: LoadedPlugin): void {
/**
* `PLUGIN_DATA` is derived from the manifest name, so two packages claiming
* one name would share a persistent directory and overwrite each other's
* state. The later package is refused before any of its components land.
*/
const claimed = this.pluginsByName.get(plugin.manifest.name);
if (claimed !== undefined) {
this.rejections.push({
code: 'manifest_name_conflict',
severity: 'error',
message: `Plugin name "${plugin.manifest.name}" is already claimed by ${claimed.root}; this package was skipped`,
location: plugin.root,
});
return;
}
this.pluginsByName.set(plugin.manifest.name, plugin);
for (const skill of plugin.skills) {
if (this.skillsByName.has(skill.name)) {
plugin.diagnostics.push({
code: 'skill_invalid',
severity: 'warning',
message: `Skill "${skill.name}" is already provided by another plugin and was skipped`,
location: `${plugin.manifest.name}/skills/${skill.name}`,
});
continue;
}
this.skillsByName.set(skill.name, skill);
}
for (const server of plugin.mcpServers) {
if (this.serversByName.has(server.name)) {
plugin.diagnostics.push({
code: 'mcp_server_invalid',
severity: 'warning',
message: `MCP server "${server.name}" is already provided by another plugin and was skipped`,
location: `${plugin.manifest.name}/mcp.json`,
});
continue;
}
this.serversByName.set(server.name, server.options);
}
this.plugins.push(plugin);
}
addRejection(diagnostics: PluginDiagnostic[]): void {
this.rejections.push(...diagnostics);
}
getDirectory(): string | null {
return this.directory;
}
list(): LoadedPlugin[] {
return this.plugins;
}
skills(): DeploymentSkill[] {
return Array.from(this.skillsByName.values());
}
/** Plugin MCP servers keyed by server name, shaped for `appConfig.mcpConfig`. */
mcpServers(): Record<string, MCPOptions> {
return Object.fromEntries(this.serversByName);
}
diagnostics(): PluginDiagnostic[] {
return [...this.rejections, ...this.plugins.flatMap((plugin) => plugin.diagnostics)];
}
}
let registry = new DeploymentPluginRegistry(null, []);
export function getDeploymentPluginRegistry(): DeploymentPluginRegistry {
return registry;
}
export function getDeploymentPluginSkills(): DeploymentSkill[] {
return registry.skills();
}
export function getDeploymentPluginMcpServers(): Record<string, MCPOptions> {
return registry.mcpServers();
}
/**
* Scans a directory of Agent Plugins packages. Each immediate child directory
* is one plugin; a rejected plugin is reported and skipped so the remaining
* packages still load.
*/
export async function loadPluginsFromDirectory(
directory: string,
options: DeploymentPluginOptions & { explicitlyConfigured?: boolean } = {},
): Promise<DeploymentPluginRegistry> {
let entries: fs.Dirent[];
try {
entries = await fs.promises.readdir(directory, { withFileTypes: true });
} catch (error) {
if (
(error as NodeJS.ErrnoException).code === 'ENOENT' &&
options.explicitlyConfigured !== true
) {
return new DeploymentPluginRegistry(directory, []);
}
throw new Error(`Deployment plugins directory could not be read: ${directory}`);
}
const dataRoot = resolveDeploymentPluginDataDirectory(options);
await fs.promises.mkdir(dataRoot, { recursive: true });
const candidates = entries
.filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
.map((entry) => path.join(directory, entry.name))
.sort();
const results = await Promise.all(
candidates.map((candidate) =>
loadPlugin(candidate, {
dataRoot,
...(options.hookCapabilities !== undefined && {
hookCapabilities: options.hookCapabilities,
}),
}),
),
);
const loaded: LoadedPlugin[] = [];
const rejections: PluginDiagnostic[] = [];
for (const result of results) {
if (result.status === 'loaded') {
loaded.push(result.plugin);
continue;
}
/**
* A rejected package has no manifest name to identify it, so its directory
* is the only thing that tells an operator which one to fix.
*/
for (const diagnostic of result.diagnostics) {
rejections.push({
...diagnostic,
location:
diagnostic.location === undefined ? result.root : `${result.root}/${diagnostic.location}`,
});
}
}
const nextRegistry = new DeploymentPluginRegistry(directory, loaded);
nextRegistry.addRejection(rejections);
return nextRegistry;
}
function reportDiagnostics(current: DeploymentPluginRegistry): void {
for (const diagnostic of current.diagnostics()) {
const location = diagnostic.location === undefined ? '' : ` (${diagnostic.location})`;
const message = `[agentPlugins] ${diagnostic.message}${location}`;
if (diagnostic.severity === 'error') {
logger.error(message);
continue;
}
logger.warn(message);
}
}
export async function initializeDeploymentPlugins(
options: DeploymentPluginOptions = {},
): Promise<DeploymentPluginRegistry> {
const resolved = resolveDeploymentPluginDirectory(options);
registry = await loadPluginsFromDirectory(resolved.directory, {
...options,
explicitlyConfigured: resolved.explicitlyConfigured,
});
reportDiagnostics(registry);
const count = registry.list().length;
if (count === 0) {
logger.debug(`[agentPlugins] No plugins loaded from ${resolved.directory}`);
return registry;
}
const skillCount = registry.skills().length;
const serverCount = Object.keys(registry.mcpServers()).length;
logger.info(
`[agentPlugins] Loaded ${count} plugin(s) from ${resolved.directory}: ${skillCount} skill(s), ${serverCount} MCP server(s)`,
);
return registry;
}