mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-17 13:33:45 +00:00
* 🔌 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>
266 lines
8.3 KiB
TypeScript
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;
|
|
}
|