@jshookmcp/jshook 0.1.8 → 0.1.9

package/dist/server/extensions/ExtensionManager.js

@@ -1,868 +0,0 @@
-import { readdir, readFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
-import { allTools, getTierIndex } from '../ToolCatalog.js';
-import { logger } from '../../utils/logger.js';
-import { getPluginBoostTier } from '../extensions/plugin-config.js';
-const IS_TS_RUNTIME = import.meta.url.endsWith('.ts');
-const EXTENSION_MANAGER_DIR = dirname(fileURLToPath(import.meta.url));
-const EXTENSION_INSTALL_ROOT = resolve(EXTENSION_MANAGER_DIR, '..', '..', '..');
-const DEFAULT_PLUGIN_ROOTS = IS_TS_RUNTIME
-    ? [join(EXTENSION_INSTALL_ROOT, 'plugins'), join(EXTENSION_INSTALL_ROOT, 'dist', 'plugins')]
-    : [join(EXTENSION_INSTALL_ROOT, 'dist', 'plugins'), join(EXTENSION_INSTALL_ROOT, 'plugins')];
-const DEFAULT_WORKFLOW_ROOTS = [join(EXTENSION_INSTALL_ROOT, 'workflows')];
-function parseRoots(raw, fallback) {
-    const value = raw?.trim();
-    if (!value)
-        return fallback;
-    const roots = value
-        .split(',')
-        .map((item) => item.trim())
-        .filter(Boolean);
-    return roots.length > 0 ? [...new Set(roots)] : fallback;
-}
-function resolveRoots(roots) {
-    const resolved = roots.map((root) => (isAbsolute(root) ? root : resolve(process.cwd(), root)));
-    return [...new Set(resolved)].sort((a, b) => a.localeCompare(b));
-}
-function parseVersionParts(version) {
-    const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
-    if (!match)
-        return null;
-    return [Number(match[1]), Number(match[2]), Number(match[3])];
-}
-function compareVersion(a, b) {
-    const aa = parseVersionParts(a);
-    const bb = parseVersionParts(b);
-    if (!aa || !bb)
-        return null;
-    const [aMajor, aMinor, aPatch] = aa;
-    const [bMajor, bMinor, bPatch] = bb;
-    if (aMajor > bMajor)
-        return 1;
-    if (aMajor < bMajor)
-        return -1;
-    if (aMinor > bMinor)
-        return 1;
-    if (aMinor < bMinor)
-        return -1;
-    if (aPatch > bPatch)
-        return 1;
-    if (aPatch < bPatch)
-        return -1;
-    return 0;
-}
-function isCompatibleVersion(range, currentVersion) {
-    const input = range.trim();
-    if (!input || input === '*')
-        return true;
-    if (input.startsWith('>=')) {
-        const base = input.slice(2).trim();
-        const cmp = compareVersion(currentVersion, base);
-        return cmp !== null && cmp >= 0;
-    }
-    if (input.startsWith('^')) {
-        const base = input.slice(1).trim();
-        const cc = parseVersionParts(currentVersion);
-        const bb = parseVersionParts(base);
-        if (!cc || !bb)
-            return false;
-        const cmp = compareVersion(currentVersion, base);
-        return cmp !== null && cmp >= 0 && cc[0] === bb[0];
-    }
-    if (input.startsWith('~')) {
-        const base = input.slice(1).trim();
-        const cc = parseVersionParts(currentVersion);
-        const bb = parseVersionParts(base);
-        if (!cc || !bb)
-            return false;
-        const cmp = compareVersion(currentVersion, base);
-        return cmp !== null && cmp >= 0 && cc[0] === bb[0] && cc[1] === bb[1];
-    }
-    const cmp = compareVersion(currentVersion, input);
-    return cmp !== null && cmp === 0;
-}
-async function sha256Hex(filePath) {
-    const content = await readFile(filePath);
-    return createHash('sha256').update(content).digest('hex');
-}
-function normalizeHex(value) {
-    return value.trim().toLowerCase().replace(/^0x/, '');
-}
-function safeHexEquals(a, b) {
-    const left = Buffer.from(normalizeHex(a), 'hex');
-    const right = Buffer.from(normalizeHex(b), 'hex');
-    if (left.length === 0 || right.length === 0 || left.length !== right.length)
-        return false;
-    return timingSafeEqual(left, right);
-}
-function isTruthyEnv(value) {
-    return ['1', 'true'].includes((value ?? '').toLowerCase());
-}
-function isPluginSignatureRequired() {
-    const raw = process.env.MCP_PLUGIN_SIGNATURE_REQUIRED;
-    if (raw === undefined || raw.trim() === '') {
-        return process.env.NODE_ENV === 'production';
-    }
-    return isTruthyEnv(raw);
-}
-function isPluginStrictLoad() {
-    const raw = process.env.MCP_PLUGIN_STRICT_LOAD;
-    if (raw === undefined || raw.trim() === '') {
-        return isPluginSignatureRequired();
-    }
-    return isTruthyEnv(raw) || isPluginSignatureRequired();
-}
-function parseDigestAllowlist(raw) {
-    const value = raw?.trim();
-    if (!value)
-        return new Set();
-    return new Set(value
-        .split(',')
-        .map((item) => normalizeHex(item))
-        .filter((item) => item.length > 0));
-}
-async function verifyPluginIntegrity(plugin, pluginFile, currentVersion) {
-    const errors = [];
-    const warnings = [];
-    if (!isCompatibleVersion(plugin.manifest.compatibleCore, currentVersion)) {
-        errors.push(`Plugin ${plugin.manifest.id} incompatible with core ${currentVersion}; requires ${plugin.manifest.compatibleCore}`);
-    }
-    let fileDigest;
-    if (plugin.manifest.checksum || plugin.manifest.signature) {
-        fileDigest = await sha256Hex(pluginFile);
-    }
-    if (plugin.manifest.checksum && fileDigest) {
-        if (!safeHexEquals(plugin.manifest.checksum, fileDigest)) {
-            errors.push(`Plugin ${plugin.manifest.id} checksum mismatch`);
-        }
-    }
-    const signatureRequired = isPluginSignatureRequired();
-    const signatureSecret = process.env.MCP_PLUGIN_SIGNATURE_SECRET?.trim();
-    const signature = plugin.manifest.signature?.trim();
-    if (signatureRequired && !signature) {
-        errors.push(`Plugin ${plugin.manifest.id} is missing required signature`);
-    }
-    if (signature) {
-        if (!signatureSecret) {
-            if (signatureRequired) {
-                errors.push('MCP_PLUGIN_SIGNATURE_SECRET is required to verify plugin signatures');
-            }
-            else {
-                warnings.push(`Plugin ${plugin.manifest.id} has signature but MCP_PLUGIN_SIGNATURE_SECRET is not set; signature not verified`);
-            }
-        }
-        else if (fileDigest) {
-            const expected = createHmac('sha256', signatureSecret).update(fileDigest).digest('hex');
-            if (!safeHexEquals(signature, expected)) {
-                errors.push(`Plugin ${plugin.manifest.id} signature verification failed`);
-            }
-        }
-    }
-    return {
-        ok: errors.length === 0,
-        errors,
-        warnings,
-    };
-}
-function isPluginContract(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const candidate = value;
-    const manifest = candidate.manifest;
-    return !!(manifest &&
-        manifest.kind === 'plugin-manifest' &&
-        manifest.version === 1 &&
-        typeof manifest.id === 'string' &&
-        typeof candidate.onLoad === 'function');
-}
-function isDomainManifest(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const candidate = value;
-    return !!(candidate.kind === 'domain-manifest' &&
-        candidate.version === 1 &&
-        typeof candidate.domain === 'string' &&
-        typeof candidate.depKey === 'string' &&
-        typeof candidate.ensure === 'function' &&
-        Array.isArray(candidate.registrations));
-}
-function isWorkflowContract(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const candidate = value;
-    return !!(candidate.kind === 'workflow-contract' &&
-        candidate.version === 1 &&
-        typeof candidate.id === 'string' &&
-        typeof candidate.displayName === 'string' &&
-        typeof candidate.build === 'function');
-}
-async function collectMatchingFiles(roots, matcher) {
-    const ignoredDirs = new Set(['node_modules', '.git', '.pnpm']);
-    const files = [];
-    const queue = [...roots].sort((a, b) => a.localeCompare(b));
-    while (queue.length > 0) {
-        const current = queue.shift();
-        let entries;
-        try {
-            entries = await readdir(current, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        const sortedEntries = [...entries].sort((a, b) => a.name.localeCompare(b.name));
-        for (const entry of sortedEntries) {
-            const abs = join(current, entry.name);
-            if (entry.isDirectory()) {
-                if (ignoredDirs.has(entry.name)) {
-                    continue;
-                }
-                queue.push(abs);
-                queue.sort((a, b) => a.localeCompare(b));
-                continue;
-            }
-            if (entry.isFile() && matcher(entry.name)) {
-                files.push(abs);
-            }
-        }
-    }
-    return files.sort((a, b) => a.localeCompare(b));
-}
-function normalizeExtensionCandidateKey(root, file) {
-    const normalizedRoot = root
-        .replace(/\\/g, '/')
-        .replace(/\/+/g, '/')
-        .replace(/^\/+|\/+$/g, '')
-        .toLowerCase();
-    const relDir = dirname(file)
-        .slice(root.length)
-        .replace(/^[/\\]+/, '')
-        .replace(/\\/g, '/')
-        .replace(/\/+/g, '/')
-        .replace(/^\/+|\/+$/g, '')
-        .toLowerCase();
-    if (!relDir || relDir === 'dist') {
-        return `${normalizedRoot}::`;
-    }
-    const normalizedRelDir = relDir.endsWith('/dist') ? relDir.slice(0, -'/dist'.length) : relDir;
-    return `${normalizedRoot}::${normalizedRelDir}`;
-}
-async function discoverPluginFiles(pluginRoots) {
-    const candidates = [];
-    for (const [rootIndex, root] of pluginRoots.entries()) {
-        const files = await collectMatchingFiles([root], (filename) => filename === 'manifest.js' || filename === 'manifest.ts');
-        for (const file of files) {
-            candidates.push({
-                file,
-                key: normalizeExtensionCandidateKey(root, file),
-                isJs: file.endsWith('.js'),
-                isTs: file.endsWith('.ts'),
-                rootIndex,
-            });
-        }
-    }
-    const extensionRank = (candidate) => {
-        if (candidate.isJs)
-            return 0;
-        if (candidate.isTs)
-            return 1;
-        return 2;
-    };
-    const byKey = new Map();
-    for (const candidate of candidates.sort((a, b) => a.file.localeCompare(b.file))) {
-        const existing = byKey.get(candidate.key);
-        if (!existing) {
-            byKey.set(candidate.key, candidate);
-            continue;
-        }
-        const existingRoot = existing.rootIndex;
-        const candidateRoot = candidate.rootIndex;
-        const existingExtRank = extensionRank(existing);
-        const candidateExtRank = extensionRank(candidate);
-        const shouldReplace = candidateRoot < existingRoot ||
-            (candidateRoot === existingRoot && candidateExtRank < existingExtRank) ||
-            (candidateRoot === existingRoot &&
-                candidateExtRank === existingExtRank &&
-                candidate.file.localeCompare(existing.file) < 0);
-        if (shouldReplace) {
-            byKey.set(candidate.key, candidate);
-        }
-    }
-    return [...byKey.values()].map((item) => item.file).sort((a, b) => a.localeCompare(b));
-}
-async function discoverWorkflowFiles(workflowRoots) {
-    const candidates = [];
-    for (const [rootIndex, root] of workflowRoots.entries()) {
-        const files = await collectMatchingFiles([root], (filename) => filename.endsWith('.workflow.js') ||
-            filename.endsWith('.workflow.ts') ||
-            filename === 'workflow.js' ||
-            filename === 'workflow.ts');
-        for (const file of files) {
-            candidates.push({
-                file,
-                key: normalizeExtensionCandidateKey(root, file),
-                isJs: file.endsWith('.js'),
-                isTs: file.endsWith('.ts'),
-                rootIndex,
-            });
-        }
-    }
-    const extensionRank = (candidate) => {
-        if (candidate.isJs)
-            return 0;
-        if (candidate.isTs)
-            return 1;
-        return 2;
-    };
-    const byKey = new Map();
-    for (const candidate of candidates.sort((a, b) => a.file.localeCompare(b.file))) {
-        const existing = byKey.get(candidate.key);
-        if (!existing) {
-            byKey.set(candidate.key, candidate);
-            continue;
-        }
-        const existingRoot = existing.rootIndex;
-        const candidateRoot = candidate.rootIndex;
-        const existingExtRank = extensionRank(existing);
-        const candidateExtRank = extensionRank(candidate);
-        const shouldReplace = candidateRoot < existingRoot ||
-            (candidateRoot === existingRoot && candidateExtRank < existingExtRank) ||
-            (candidateRoot === existingRoot &&
-                candidateExtRank === existingExtRank &&
-                candidate.file.localeCompare(existing.file) < 0);
-        if (shouldReplace) {
-            byKey.set(candidate.key, candidate);
-        }
-    }
-    return [...byKey.values()].map((item) => item.file).sort((a, b) => a.localeCompare(b));
-}
-function extractConfigValue(ctx, path, fallback) {
-    const segments = path.split('.').filter(Boolean);
-    let current = ctx.config;
-    for (const segment of segments) {
-        if (!current || typeof current !== 'object')
-            return fallback;
-        current = current[segment];
-    }
-    return current ?? fallback;
-}
-function createFreshImportUrl(modulePath, kind) {
-    const moduleUrl = new URL(pathToFileURL(modulePath).href);
-    moduleUrl.searchParams.set('reloadTs', String(Date.now()));
-    logger.debug(`[extensions] Loading fresh ${kind} module: ${modulePath}`);
-    return moduleUrl.href;
-}
-async function clearLoadedExtensionTools(ctx) {
-    let removed = 0;
-    for (const [pluginId, runtime] of ctx.extensionPluginRuntimeById.entries()) {
-        try {
-            if (runtime.plugin.onDeactivate && runtime.state === 'activated') {
-                await runtime.plugin.onDeactivate(runtime.lifecycleContext);
-                runtime.state = 'deactivated';
-            }
-        }
-        catch (error) {
-            logger.warn(`Plugin onDeactivate failed for "${pluginId}":`, error);
-        }
-        try {
-            if (runtime.plugin.onUnload) {
-                await runtime.plugin.onUnload(runtime.lifecycleContext);
-                runtime.state = 'unloaded';
-            }
-        }
-        catch (error) {
-            logger.warn(`Plugin onUnload failed for "${pluginId}":`, error);
-        }
-    }
-    for (const record of ctx.extensionToolsByName.values()) {
-        try {
-            record.registeredTool?.remove();
-        }
-        catch (error) {
-            logger.warn(`Failed to remove extension tool "${record.name}":`, error);
-        }
-        ctx.router.removeHandler(record.name);
-        ctx.activatedToolNames.delete(record.name);
-        ctx.activatedRegisteredTools.delete(record.name);
-        removed++;
-    }
-    ctx.extensionToolsByName.clear();
-    ctx.extensionPluginsById.clear();
-    ctx.extensionPluginRuntimeById.clear();
-    ctx.extensionWorkflowsById.clear();
-    ctx.extensionWorkflowRuntimeById.clear();
-    return removed;
-}
-function buildListResult(ctx, pluginRoots, workflowRoots) {
-    return {
-        pluginRoots,
-        workflowRoots,
-        pluginCount: ctx.extensionPluginsById.size,
-        workflowCount: ctx.extensionWorkflowsById.size,
-        toolCount: ctx.extensionToolsByName.size,
-        lastReloadAt: ctx.lastExtensionReloadAt,
-        plugins: [...ctx.extensionPluginsById.values()],
-        workflows: [...ctx.extensionWorkflowsById.values()],
-        tools: [...ctx.extensionToolsByName.values()].map((record) => ({
-            name: record.name,
-            domain: record.domain,
-            source: record.source,
-        })),
-    };
-}
-export function listExtensions(ctx) {
-    const pluginRoots = resolveRoots(parseRoots(process.env.MCP_PLUGIN_ROOTS, DEFAULT_PLUGIN_ROOTS));
-    const workflowRoots = resolveRoots(parseRoots(process.env.MCP_WORKFLOW_ROOTS, DEFAULT_WORKFLOW_ROOTS));
-    return buildListResult(ctx, pluginRoots, workflowRoots);
-}
-let reloadMutex = Promise.resolve();
-export async function reloadExtensions(ctx) {
-    const prev = reloadMutex;
-    let resolve;
-    reloadMutex = new Promise((r) => { resolve = r; });
-    await prev;
-    try {
-        return await reloadExtensionsInner(ctx);
-    }
-    finally {
-        resolve();
-    }
-}
-async function reloadExtensionsInner(ctx) {
-    const warnings = [];
-    const errors = [];
-    const removedTools = await clearLoadedExtensionTools(ctx);
-    const pluginRoots = resolveRoots(parseRoots(process.env.MCP_PLUGIN_ROOTS, DEFAULT_PLUGIN_ROOTS));
-    const workflowRoots = resolveRoots(parseRoots(process.env.MCP_WORKFLOW_ROOTS, DEFAULT_WORKFLOW_ROOTS));
-    const allowedDigests = parseDigestAllowlist(process.env.MCP_PLUGIN_ALLOWED_DIGESTS);
-    const signatureRequired = isPluginSignatureRequired();
-    const strictLoad = isPluginStrictLoad();
-    if (strictLoad && allowedDigests.size === 0) {
-        const msg = 'MCP_PLUGIN_ALLOWED_DIGESTS is required when MCP_PLUGIN_SIGNATURE_REQUIRED=true ' +
-            'or MCP_PLUGIN_STRICT_LOAD=true. The digest allowlist is the only pre-import trust boundary — ' +
-            'without it, plugin code executes before integrity verification. No plugins will be loaded.';
-        errors.push(msg);
-        logger.error('[extensions] ' + msg);
-        const workflowFiles = await discoverWorkflowFiles(workflowRoots);
-        for (const workflowFile of workflowFiles) {
-            try {
-                const mod = await import(createFreshImportUrl(workflowFile, 'workflow'));
-                const candidate = mod.default ?? mod;
-                if (!isWorkflowContract(candidate)) {
-                    warnings.push(`Skip workflow file without valid WorkflowContract: ${workflowFile}`);
-                    continue;
-                }
-                const workflow = candidate;
-                if (ctx.extensionWorkflowsById.has(workflow.id)) {
-                    warnings.push(`Skip workflow "${workflow.id}" from ${workflowFile}: duplicate id`);
-                    continue;
-                }
-                ctx.extensionWorkflowsById.set(workflow.id, {
-                    id: workflow.id,
-                    displayName: workflow.displayName,
-                    source: workflowFile,
-                    description: workflow.description,
-                    tags: workflow.tags,
-                    timeoutMs: workflow.timeoutMs,
-                    defaultMaxConcurrency: workflow.defaultMaxConcurrency,
-                });
-                const runtimeRecord = {
-                    workflow,
-                    source: workflowFile,
-                };
-                ctx.extensionWorkflowRuntimeById.set(workflow.id, runtimeRecord);
-            }
-            catch (error) {
-                errors.push(`Failed to import workflow file ${workflowFile}: ${String(error)}`);
-            }
-        }
-        ctx.lastExtensionReloadAt = new Date().toISOString();
-        const list = buildListResult(ctx, pluginRoots, workflowRoots);
-        return { ...list, addedTools: 0, removedTools, warnings, errors };
-    }
-    if (allowedDigests.size === 0) {
-        logger.warn('[extensions] Loading plugins WITHOUT MCP_PLUGIN_ALLOWED_DIGESTS allowlist. ' +
-            'Plugin code will execute on import() before post-load integrity checks. ' +
-            'Set MCP_PLUGIN_STRICT_LOAD=true to enforce allowlist requirement.');
-    }
-    const baseToolNames = new Set(allTools.map((tool) => tool.name));
-    const pluginFiles = await discoverPluginFiles(pluginRoots);
-    const coreVersion = ctx.config?.mcp?.version ?? '0.0.0';
-    for (const pluginFile of pluginFiles) {
-        let fileDigest;
-        try {
-            fileDigest = normalizeHex(await sha256Hex(pluginFile));
-            if (allowedDigests.size > 0 && !allowedDigests.has(fileDigest)) {
-                warnings.push(`Skip plugin file not in MCP_PLUGIN_ALLOWED_DIGESTS allowlist: ${pluginFile}`);
-                continue;
-            }
-        }
-        catch (error) {
-            errors.push(`Failed to hash plugin file ${pluginFile}: ${String(error)}`);
-            continue;
-        }
-        let plugin;
-        try {
-            const mod = await import(createFreshImportUrl(pluginFile, 'plugin'));
-            const candidate = mod.default ?? mod;
-            if (!isPluginContract(candidate)) {
-                warnings.push(`Skip plugin file without valid PluginContract: ${pluginFile}`);
-                continue;
-            }
-            plugin = candidate;
-        }
-        catch (error) {
-            errors.push(`Failed to import plugin file ${pluginFile}: ${String(error)}`);
-            continue;
-        }
-        if (ctx.extensionPluginsById.has(plugin.manifest.id)) {
-            warnings.push(`Skip plugin "${plugin.manifest.id}" from ${pluginFile}: duplicate plugin id`);
-            continue;
-        }
-        try {
-            const verification = await verifyPluginIntegrity(plugin, pluginFile, coreVersion);
-            warnings.push(...verification.warnings);
-            if (!verification.ok) {
-                errors.push(...verification.errors);
-                continue;
-            }
-        }
-        catch (error) {
-            errors.push(`Failed to verify plugin ${plugin.manifest.id}: ${String(error)}`);
-            continue;
-        }
-        const runtimeData = new Map();
-        const domains = [];
-        const workflows = [];
-        const metrics = new Set();
-        let pluginState = 'loaded';
-        const pluginPermissions = plugin.manifest.permissions ?? {};
-        const permissionEnforce = strictLoad || signatureRequired;
-        const toolExecutionPermission = pluginPermissions.toolExecution;
-        const allowInvokedTools = Array.isArray(toolExecutionPermission?.allowTools)
-            ? toolExecutionPermission.allowTools.filter((value) => typeof value === 'string' && value.length > 0)
-            : [];
-        const allowInvokeAll = allowInvokedTools.includes('*');
-        const impliedCapabilities = [];
-        if (plugin.manifest.contributes?.domains?.length)
-            impliedCapabilities.push('toolExecution');
-        if (plugin.manifest.contributes?.workflows?.length)
-            impliedCapabilities.push('toolExecution');
-        for (const cap of impliedCapabilities) {
-            if (!pluginPermissions[cap]) {
-                const msg = `Plugin "${plugin.manifest.id}" contributes domains/workflows but does not declare "${cap}" permission`;
-                if (permissionEnforce) {
-                    errors.push(msg + ' (blocked by strict mode)');
-                    continue;
-                }
-                warnings.push(msg);
-            }
-        }
-        function checkRegistrationPermission(capability, action) {
-            const declared = !!pluginPermissions[capability];
-            if (!declared) {
-                const msg = `Plugin "${plugin.manifest.id}" attempted ${action} without declaring "${capability}" permission`;
-                if (permissionEnforce) {
-                    errors.push(msg + ' (blocked by strict mode)');
-                    return false;
-                }
-                warnings.push(msg + ' (allowed — set MCP_PLUGIN_STRICT_LOAD=true to enforce)');
-            }
-            return true;
-        }
-        const lifecycleContext = {
-            pluginId: plugin.manifest.id,
-            pluginRoot: pluginFile,
-            config: ctx.config,
-            get state() {
-                return pluginState;
-            },
-            registerDomain(manifest) {
-                if (!checkRegistrationPermission('toolExecution', `registerDomain("${manifest.domain ?? 'unknown'}")`)) {
-                    return;
-                }
-                domains.push(manifest);
-            },
-            registerWorkflow(workflow) {
-                if (!checkRegistrationPermission('toolExecution', `registerWorkflow("${workflow.id ?? 'unknown'}")`)) {
-                    return;
-                }
-                workflows.push(workflow);
-            },
-            registerMetric(metricName) {
-                metrics.add(metricName);
-            },
-            async invokeTool(name, args = {}) {
-                if (typeof name !== 'string' || name.length === 0) {
-                    throw new Error('invokeTool requires a non-empty tool name');
-                }
-                if (!checkRegistrationPermission('toolExecution', `invokeTool("${name}")`)) {
-                    throw new Error(`Plugin "${plugin.manifest.id}" is not allowed to invoke tools`);
-                }
-                if (!allowInvokeAll && !allowInvokedTools.includes(name)) {
-                    throw new Error(`Plugin "${plugin.manifest.id}" is not allowed to invoke "${name}". ` +
-                        'Declare it in permissions.toolExecution.allowTools.');
-                }
-                if (!baseToolNames.has(name)) {
-                    throw new Error(`Plugin "${plugin.manifest.id}" can only invoke built-in tools. "${name}" is not built-in.`);
-                }
-                if (!ctx.router.has(name)) {
-                    throw new Error(`Tool "${name}" is not available in the current active profile.`);
-                }
-                return ctx.executeToolWithTracking(name, (args ?? {}));
-            },
-            hasPermission(capability) {
-                const permissions = plugin.manifest.permissions;
-                return !!permissions?.[capability];
-            },
-            getConfig(path, fallback) {
-                return extractConfigValue(ctx, path, fallback);
-            },
-            setRuntimeData(key, value) {
-                runtimeData.set(key, value);
-            },
-            getRuntimeData(key) {
-                return runtimeData.get(key);
-            },
-        };
-        const runtimeRecord = {
-            plugin,
-            lifecycleContext,
-            state: pluginState,
-            source: pluginFile,
-        };
-        try {
-            await plugin.onLoad(lifecycleContext);
-            pluginState = 'loaded';
-            runtimeRecord.state = pluginState;
-            if (plugin.onValidate) {
-                const validation = await plugin.onValidate(lifecycleContext);
-                if (!validation.valid) {
-                    warnings.push(`Plugin ${plugin.manifest.id} validation failed: ${validation.errors.join('; ')}`);
-                    continue;
-                }
-                pluginState = 'validated';
-                runtimeRecord.state = pluginState;
-            }
-            if (plugin.onRegister) {
-                await plugin.onRegister(lifecycleContext);
-                pluginState = 'registered';
-                runtimeRecord.state = pluginState;
-            }
-            if (plugin.onActivate) {
-                await plugin.onActivate(lifecycleContext);
-                pluginState = 'activated';
-                runtimeRecord.state = pluginState;
-            }
-            ctx.extensionPluginRuntimeById.set(plugin.manifest.id, runtimeRecord);
-        }
-        catch (error) {
-            try {
-                if (plugin.onDeactivate && pluginState === 'activated') {
-                    await plugin.onDeactivate(lifecycleContext);
-                    pluginState = 'deactivated';
-                    runtimeRecord.state = pluginState;
-                }
-            }
-            catch (deactivateError) {
-                logger.warn(`Plugin onDeactivate failed during rollback for ${plugin.manifest.id}:`, deactivateError);
-            }
-            try {
-                if (plugin.onUnload) {
-                    await plugin.onUnload(lifecycleContext);
-                    pluginState = 'unloaded';
-                    runtimeRecord.state = pluginState;
-                }
-            }
-            catch (unloadError) {
-                logger.warn(`Plugin onUnload failed during rollback for ${plugin.manifest.id}:`, unloadError);
-            }
-            errors.push(`Plugin lifecycle failed for ${plugin.manifest.id}: ${String(error)}`);
-            continue;
-        }
-        for (const manifestDomain of plugin.manifest.contributes?.domains ?? []) {
-            if (checkRegistrationPermission('toolExecution', `contributes.domains("${manifestDomain.domain ?? 'unknown'}")`)) {
-                domains.push(manifestDomain);
-            }
-        }
-        for (const workflow of plugin.manifest.contributes?.workflows ?? []) {
-            if (checkRegistrationPermission('toolExecution', `contributes.workflows("${workflow.id ?? 'unknown'}")`)) {
-                workflows.push(workflow);
-            }
-        }
-        for (const metric of plugin.manifest.contributes?.metrics ?? []) {
-            metrics.add(metric);
-        }
-        const configDefaults = plugin.manifest.contributes?.configDefaults;
-        if (configDefaults && typeof configDefaults === 'object') {
-            const runtimeConfig = ctx.config;
-            for (const [key, value] of Object.entries(configDefaults)) {
-                if (!(key in runtimeConfig)) {
-                    runtimeConfig[key] = value;
-                }
-            }
-        }
-        const loadedTools = [];
-        const loadedDomains = new Set();
-        const loadedWorkflows = new Set();
-        const pluginBoostTier = getPluginBoostTier(plugin.manifest.id);
-        const currentTierIdx = getTierIndex(ctx.currentTier);
-        const boostTierIdx = getTierIndex(pluginBoostTier);
-        const shouldDefer = boostTierIdx >= 0 && currentTierIdx >= 0 && boostTierIdx > currentTierIdx;
-        for (const domain of domains) {
-            if (!isDomainManifest(domain)) {
-                warnings.push(`Plugin ${plugin.manifest.id} returned invalid domain manifest`);
-                continue;
-            }
-            let handlerInstance;
-            try {
-                handlerInstance = domain.ensure(ctx);
-            }
-            catch (error) {
-                errors.push(`Plugin ${plugin.manifest.id} failed to initialize domain ${domain.domain}: ${String(error)}`);
-                continue;
-            }
-            loadedDomains.add(domain.domain);
-            const deps = { ...ctx.handlerDeps, [domain.depKey]: handlerInstance };
-            for (const registration of domain.registrations) {
-                const toolName = registration.tool.name;
-                if (baseToolNames.has(toolName)) {
-                    warnings.push(`Skip plugin tool "${toolName}" from ${plugin.manifest.id}: name conflicts with built-in tool`);
-                    continue;
-                }
-                if (ctx.extensionToolsByName.has(toolName)) {
-                    warnings.push(`Skip plugin tool "${toolName}" from ${plugin.manifest.id}: already loaded by another extension`);
-                    continue;
-                }
-                try {
-                    const handler = registration.bind(deps);
-                    if (shouldDefer) {
-                        ctx.extensionToolsByName.set(toolName, {
-                            name: toolName,
-                            domain: registration.domain || domain.domain,
-                            source: plugin.manifest.id,
-                            tool: registration.tool,
-                            boostTier: pluginBoostTier,
-                            handler,
-                        });
-                        loadedTools.push(toolName);
-                    }
-                    else {
-                        const registeredTool = ctx.registerSingleTool(registration.tool);
-                        try {
-                            ctx.router.addHandlers({ [toolName]: handler });
-                        }
-                        catch (routerError) {
-                            try {
-                                registeredTool.remove();
-                            }
-                            catch { }
-                            throw routerError;
-                        }
-                        ctx.activatedToolNames.add(toolName);
-                        ctx.activatedRegisteredTools.set(toolName, registeredTool);
-                        ctx.extensionToolsByName.set(toolName, {
-                            name: toolName,
-                            domain: registration.domain || domain.domain,
-                            source: plugin.manifest.id,
-                            tool: registration.tool,
-                            registeredTool,
-                            boostTier: pluginBoostTier,
-                            handler,
-                        });
-                        loadedTools.push(toolName);
-                    }
-                }
-                catch (error) {
-                    errors.push(`Plugin ${plugin.manifest.id} failed to register tool ${toolName}: ${String(error)}`);
-                }
-            }
-        }
-        for (const workflow of workflows) {
-            if (!isWorkflowContract(workflow)) {
-                warnings.push(`Plugin ${plugin.manifest.id} returned invalid workflow contract`);
-                continue;
-            }
-            if (ctx.extensionWorkflowsById.has(workflow.id)) {
-                warnings.push(`Skip workflow "${workflow.id}" from ${plugin.manifest.id}: duplicate id`);
-                continue;
-            }
-            ctx.extensionWorkflowsById.set(workflow.id, {
-                id: workflow.id,
-                displayName: workflow.displayName,
-                source: plugin.manifest.id,
-                description: workflow.description,
-                tags: workflow.tags,
-                timeoutMs: workflow.timeoutMs,
-                defaultMaxConcurrency: workflow.defaultMaxConcurrency,
-            });
-            const runtimeRecord = {
-                workflow,
-                source: plugin.manifest.id,
-            };
-            ctx.extensionWorkflowRuntimeById.set(workflow.id, runtimeRecord);
-            loadedWorkflows.add(workflow.id);
-        }
-        const record = {
-            id: plugin.manifest.id,
-            name: plugin.manifest.name,
-            source: pluginFile,
-            domains: [...loadedDomains],
-            workflows: [...loadedWorkflows],
-            tools: loadedTools,
-        };
-        ctx.extensionPluginsById.set(record.id, record);
-    }
-    const workflowFiles = await discoverWorkflowFiles(workflowRoots);
-    for (const workflowFile of workflowFiles) {
-        try {
-            const mod = await import(createFreshImportUrl(workflowFile, 'workflow'));
-            const candidate = mod.default ?? mod;
-            if (!isWorkflowContract(candidate)) {
-                warnings.push(`Skip workflow file without valid WorkflowContract: ${workflowFile}`);
-                continue;
-            }
-            const workflow = candidate;
-            if (ctx.extensionWorkflowsById.has(workflow.id)) {
-                warnings.push(`Skip workflow "${workflow.id}" from ${workflowFile}: duplicate id`);
-                continue;
-            }
-            const record = {
-                id: workflow.id,
-                displayName: workflow.displayName,
-                source: workflowFile,
-                description: workflow.description,
-                tags: workflow.tags,
-                timeoutMs: workflow.timeoutMs,
-                defaultMaxConcurrency: workflow.defaultMaxConcurrency,
-            };
-            ctx.extensionWorkflowsById.set(record.id, record);
-            const runtimeRecord = {
-                workflow,
-                source: workflowFile,
-            };
-            ctx.extensionWorkflowRuntimeById.set(record.id, runtimeRecord);
-        }
-        catch (error) {
-            errors.push(`Failed to import workflow file ${workflowFile}: ${String(error)}`);
-        }
-    }
-    if (ctx.extensionToolsByName.size > 0 || removedTools > 0) {
-        try {
-            await ctx.server.sendToolListChanged();
-        }
-        catch (error) {
-            logger.warn('sendToolListChanged failed after extension reload:', error);
-        }
-    }
-    ctx.lastExtensionReloadAt = new Date().toISOString();
-    const list = buildListResult(ctx, pluginRoots, workflowRoots);
-    return {
-        ...list,
-        addedTools: ctx.extensionToolsByName.size,
-        removedTools,
-        warnings,
-        errors,
-    };
-}