@jshookmcp/jshook 0.1.7 → 0.1.9

package/dist/src/server/extensions/ExtensionManager.js

@@ -0,0 +1,247 @@
+import { allTools } from '../ToolCatalog.js';
+import { logger } from '../../utils/logger.js';
+import { DEFAULT_PLUGIN_ROOTS, DEFAULT_WORKFLOW_ROOTS, parseRoots, resolveRoots } from './ExtensionManager.roots.js';
+import { sha256Hex, normalizeHex, isPluginStrictLoad, parseDigestAllowlist, verifyPluginIntegrity } from './ExtensionManager.integrity.js';
+import { isExtensionBuilder, isWorkflowContract } from './ExtensionManager.guards.js';
+import { discoverPluginFiles, discoverWorkflowFiles } from './ExtensionManager.discovery.js';
+import { extractConfigValue, createFreshImportUrl, clearLoadedExtensionTools, buildListResult } from './ExtensionManager.lifecycle.js';
+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 loadWorkflows(ctx, workflowFiles, warnings, errors) {
+    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)}`);
+        }
+    }
+}
+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 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);
+        await loadWorkflows(ctx, workflowFiles, warnings, errors);
+        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 (!isExtensionBuilder(candidate)) {
+                warnings.push(`Skip plugin file without valid ExtensionBuilder: ${pluginFile}`);
+                continue;
+            }
+            plugin = candidate;
+        }
+        catch (error) {
+            errors.push(`Failed to import plugin file ${pluginFile}: ${String(error)}`);
+            continue;
+        }
+        if (ctx.extensionPluginsById.has(plugin.id)) {
+            warnings.push(`Skip plugin "${plugin.id}" from ${pluginFile}: duplicate plugin id`);
+            continue;
+        }
+        try {
+            const verification = await verifyPluginIntegrity(plugin, coreVersion);
+            warnings.push(...verification.warnings);
+            if (!verification.ok) {
+                errors.push(...verification.errors);
+                continue;
+            }
+        }
+        catch (error) {
+            errors.push(`Failed to verify plugin ${plugin.id}: ${String(error)}`);
+            continue;
+        }
+        const runtimeData = new Map();
+        const metrics = new Set();
+        let pluginState = 'loaded';
+        const allowInvokeAll = plugin.allowTools.includes('*');
+        const lifecycleContext = {
+            pluginId: plugin.id,
+            pluginRoot: pluginFile,
+            config: ctx.config,
+            get state() {
+                return pluginState;
+            },
+            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 (!allowInvokeAll && !plugin.allowTools.includes(name)) {
+                    throw new Error(`Plugin "${plugin.id}" is not allowed to invoke "${name}". ` +
+                        'Declare it in allowTool calls.');
+                }
+                if (!baseToolNames.has(name)) {
+                    throw new Error(`Plugin "${plugin.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) {
+                return true;
+            },
+            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 {
+            if (plugin.onLoadHandler) {
+                await plugin.onLoadHandler(lifecycleContext);
+            }
+            pluginState = 'loaded';
+            runtimeRecord.state = pluginState;
+            if (plugin.onValidateHandler) {
+                const validation = await plugin.onValidateHandler(lifecycleContext);
+                if (!validation.valid) {
+                    warnings.push(`Plugin ${plugin.id} validation failed: ${validation.errors.join('; ')}`);
+                    continue;
+                }
+                pluginState = 'validated';
+                runtimeRecord.state = pluginState;
+            }
+            if (plugin.onActivateHandler) {
+                await plugin.onActivateHandler(lifecycleContext);
+                pluginState = 'activated';
+                runtimeRecord.state = pluginState;
+            }
+            ctx.extensionPluginRuntimeById.set(plugin.id, runtimeRecord);
+        }
+        catch (error) {
+            try {
+                if (plugin.onDeactivateHandler && pluginState === 'activated') {
+                    await plugin.onDeactivateHandler(lifecycleContext);
+                    pluginState = 'deactivated';
+                    runtimeRecord.state = pluginState;
+                }
+            }
+            catch (deactivateError) {
+                logger.warn(`Plugin onDeactivate failed during rollback for ${plugin.id}:`, deactivateError);
+            }
+            errors.push(`Plugin lifecycle failed for ${plugin.id}: ${String(error)}`);
+            continue;
+        }
+        const loadedTools = plugin.tools.map((t) => t.name);
+        const record = {
+            id: plugin.id,
+            name: plugin.getName,
+            source: pluginFile,
+            domains: [],
+            workflows: [],
+            tools: loadedTools,
+        };
+        ctx.extensionPluginsById.set(record.id, record);
+    }
+    const workflowFiles = await discoverWorkflowFiles(workflowRoots);
+    await loadWorkflows(ctx, workflowFiles, warnings, errors);
+    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,
+    };
+}

package/dist/src/server/extensions/ExtensionManager.lifecycle.d.ts

@@ -0,0 +1,6 @@
+import type { MCPServerContext } from '../MCPServer.context.js';
+import type { ExtensionListResult } from '../extensions/types.js';
+export declare function extractConfigValue<T = unknown>(ctx: MCPServerContext, path: string, fallback?: T): T;
+export declare function createFreshImportUrl(modulePath: string, kind: 'plugin' | 'workflow'): string;
+export declare function clearLoadedExtensionTools(ctx: MCPServerContext): Promise<number>;
+export declare function buildListResult(ctx: MCPServerContext, pluginRoots: string[], workflowRoots: string[]): ExtensionListResult;

package/dist/src/server/extensions/ExtensionManager.lifecycle.js

@@ -0,0 +1,75 @@
+import { pathToFileURL } from 'node:url';
+import { logger } from '../../utils/logger.js';
+export 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;
+}
+export 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;
+}
+export async function clearLoadedExtensionTools(ctx) {
+    let removed = 0;
+    for (const [pluginId, runtime] of ctx.extensionPluginRuntimeById.entries()) {
+        try {
+            if (runtime.plugin.onDeactivateHandler && runtime.state === 'activated') {
+                await runtime.plugin.onDeactivateHandler(runtime.lifecycleContext);
+                runtime.state = 'deactivated';
+            }
+        }
+        catch (error) {
+            logger.warn(`Plugin onDeactivate failed for "${pluginId}":`, error);
+        }
+        try {
+            if (runtime.plugin.onDeactivateHandler) {
+                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;
+}
+export 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,
+        })),
+    };
+}

package/dist/src/server/extensions/ExtensionManager.roots.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_PLUGIN_ROOTS: string[];
+export declare const DEFAULT_WORKFLOW_ROOTS: string[];
+export declare function parseRoots(raw: string | undefined, fallback: string[]): string[];
+export declare function resolveRoots(roots: string[]): string[];

package/dist/src/server/extensions/ExtensionManager.roots.js

@@ -0,0 +1,23 @@
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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, '..', '..', '..');
+export 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')];
+export const DEFAULT_WORKFLOW_ROOTS = [join(EXTENSION_INSTALL_ROOT, 'workflows')];
+export 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;
+}
+export 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));
+}

package/dist/src/server/extensions/ExtensionManager.version.d.ts

@@ -0,0 +1,3 @@
+export declare function parseVersionParts(version: string): [number, number, number] | null;
+export declare function compareVersion(a: string, b: string): number | null;
+export declare function isCompatibleVersion(range: string, currentVersion: string): boolean;

package/dist/src/server/extensions/ExtensionManager.version.js

@@ -0,0 +1,57 @@
+export 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])];
+}
+export 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;
+}
+export 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;
+}

package/dist/src/server/extensions/plugin-config.js

@@ -0,0 +1,41 @@
+function normalizeSegment(value) {
+    return value.trim().replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '').toUpperCase();
+}
+function envCandidates(pluginId, key) {
+    const pluginSegment = normalizeSegment(pluginId);
+    const keySegment = normalizeSegment(key);
+    return [
+        `PLUGIN_${pluginSegment}_${keySegment}`,
+        `PLUGINS_${pluginSegment}_${keySegment}`,
+    ];
+}
+function parseBoolean(raw) {
+    if (raw == null)
+        return undefined;
+    const value = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(value))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(value))
+        return false;
+    return undefined;
+}
+export function getPluginBooleanConfig(ctx, pluginId, key, fallback) {
+    for (const candidate of envCandidates(pluginId, key)) {
+        const parsed = parseBoolean(process.env[candidate]);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return ctx.getConfig(`plugins.${pluginId}.${key}`, fallback);
+}
+const VALID_BOOST_TIERS = new Set(['search', 'workflow', 'full']);
+export function getPluginBoostTier(pluginId) {
+    for (const candidate of envCandidates(pluginId, 'BOOST_DOMAIN')) {
+        const raw = process.env[candidate]?.trim().toLowerCase();
+        if (raw && VALID_BOOST_TIERS.has(raw))
+            return raw;
+    }
+    const globalDefault = process.env.MCP_DEFAULT_PLUGIN_BOOST_TIER?.trim().toLowerCase();
+    if (globalDefault && VALID_BOOST_TIERS.has(globalDefault))
+        return globalDefault;
+    return 'full';
+}

package/dist/src/server/extensions/types.d.ts

@@ -0,0 +1,61 @@
+import type { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ExtensionBuilder, PluginLifecycleContext, PluginState } from '../plugins/PluginContract.js';
+import type { WorkflowContract } from '../workflows/WorkflowContract.js';
+export interface ExtensionToolRecord {
+    name: string;
+    domain: string;
+    source: string;
+    tool: Tool;
+    registeredTool?: RegisteredTool;
+    boostTier?: string;
+    handler?: Function;
+}
+export interface ExtensionPluginRecord {
+    id: string;
+    name: string;
+    source: string;
+    domains: string[];
+    workflows: string[];
+    tools: string[];
+}
+export interface ExtensionPluginRuntimeRecord {
+    plugin: ExtensionBuilder;
+    lifecycleContext: PluginLifecycleContext;
+    state: PluginState;
+    source: string;
+}
+export interface ExtensionWorkflowRuntimeRecord {
+    workflow: WorkflowContract;
+    source: string;
+}
+export interface ExtensionWorkflowRecord {
+    id: string;
+    displayName: string;
+    source: string;
+    description?: string;
+    tags?: string[];
+    timeoutMs?: number;
+    defaultMaxConcurrency?: number;
+}
+export interface ExtensionListResult {
+    pluginRoots: string[];
+    workflowRoots: string[];
+    pluginCount: number;
+    workflowCount: number;
+    toolCount: number;
+    lastReloadAt?: string;
+    plugins: ExtensionPluginRecord[];
+    workflows: ExtensionWorkflowRecord[];
+    tools: Array<{
+        name: string;
+        domain: string;
+        source: string;
+    }>;
+}
+export interface ExtensionReloadResult extends ExtensionListResult {
+    addedTools: number;
+    removedTools: number;
+    errors: string[];
+    warnings: string[];
+}

package/dist/src/server/observability/InstrumentationContract.d.ts

@@ -0,0 +1,37 @@
+export type MetricType = 'counter' | 'gauge' | 'histogram';
+export interface SpanLike {
+    readonly name: string;
+    readonly startTime: number;
+    end(attrs?: Record<string, unknown>): void;
+    addEvent(name: string, attrs?: Record<string, unknown>): void;
+}
+export interface InstrumentationContract {
+    startSpan(name: string, attrs?: Record<string, unknown>): SpanLike;
+    emitMetric(name: string, value: number, type: MetricType, attrs?: Record<string, unknown>): void;
+    flush?(): Promise<void>;
+}
+export declare const SpanNames: {
+    readonly toolExecute: "tool.execute";
+    readonly toolValidateInput: "tool.validate_input";
+    readonly registryDiscovery: "registry.discovery";
+    readonly pluginLifecycle: "plugin.lifecycle";
+    readonly workflowRun: "workflow.run";
+    readonly workflowStep: "workflow.step";
+    readonly bridgeRequest: "bridge.request";
+    readonly captchaSolve: "captcha.solve";
+};
+export declare const MetricNames: {
+    readonly toolCallsTotal: "tool_calls_total";
+    readonly toolErrorsTotal: "tool_errors_total";
+    readonly toolDurationMs: "tool_duration_ms";
+    readonly workflowRunsTotal: "workflow_runs_total";
+    readonly workflowErrorsTotal: "workflow_errors_total";
+    readonly workflowDurationMs: "workflow_duration_ms";
+    readonly bridgeRequestsTotal: "bridge_requests_total";
+    readonly bridgeDurationMs: "bridge_duration_ms";
+    readonly pluginActiveTotal: "plugin_active_total";
+};
+export declare class NoopInstrumentation implements InstrumentationContract {
+    startSpan(name: string, _attrs?: Record<string, unknown>): SpanLike;
+    emitMetric(_name: string, _value: number, _type: MetricType, _attrs?: Record<string, unknown>): void;
+}

package/dist/src/server/observability/InstrumentationContract.js

@@ -0,0 +1,34 @@
+export const SpanNames = {
+    toolExecute: 'tool.execute',
+    toolValidateInput: 'tool.validate_input',
+    registryDiscovery: 'registry.discovery',
+    pluginLifecycle: 'plugin.lifecycle',
+    workflowRun: 'workflow.run',
+    workflowStep: 'workflow.step',
+    bridgeRequest: 'bridge.request',
+    captchaSolve: 'captcha.solve',
+};
+export const MetricNames = {
+    toolCallsTotal: 'tool_calls_total',
+    toolErrorsTotal: 'tool_errors_total',
+    toolDurationMs: 'tool_duration_ms',
+    workflowRunsTotal: 'workflow_runs_total',
+    workflowErrorsTotal: 'workflow_errors_total',
+    workflowDurationMs: 'workflow_duration_ms',
+    bridgeRequestsTotal: 'bridge_requests_total',
+    bridgeDurationMs: 'bridge_duration_ms',
+    pluginActiveTotal: 'plugin_active_total',
+};
+export class NoopInstrumentation {
+    startSpan(name, _attrs) {
+        const startTime = Date.now();
+        return {
+            name,
+            startTime,
+            end() { },
+            addEvent() { },
+        };
+    }
+    emitMetric(_name, _value, _type, _attrs) {
+    }
+}

package/dist/src/server/plugin-api.d.ts

@@ -0,0 +1,5 @@
+export type { DomainManifest, ToolHandlerDeps } from './registry/contracts.js';
+export type { ExtensionBuilder, PluginLifecycleContext } from './plugins/PluginContract.js';
+export type { ToolArgs } from './types.js';
+export { getPluginBooleanConfig, getPluginBoostTier } from './extensions/plugin-config.js';
+export { loadPluginEnv } from './extensions/plugin-env.js';

package/dist/src/server/plugins/PluginContract.d.ts

@@ -0,0 +1 @@
+export { type ToolProfileId, type ToolArgs, type ToolResponse, type PluginState, type PluginLifecycleContext, type ExtensionToolHandler, type ExtensionToolDefinition, ExtensionBuilder, createExtension, } from '../../../packages/extension-sdk/src/plugin.js';

package/dist/src/server/plugins/PluginContract.js

@@ -0,0 +1 @@
+export { ExtensionBuilder, createExtension, } from '../../../packages/extension-sdk/src/plugin.js';

package/dist/src/server/plugins/examples/minimal-plugin/manifest.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/src/server/plugins/examples/minimal-plugin/manifest.js

@@ -0,0 +1,17 @@
+import { createExtension } from '@jshookmcp/extension-sdk';
+export default createExtension('example.minimal', '1.0.0')
+    .name('Minimal Example Plugin')
+    .description('A super basic plugin with a fluent builder')
+    .allowCommand(['echo', 'ping'])
+    .tool('echo', 'Echoes back the input', {
+    type: 'object',
+    properties: { text: { type: 'string' } },
+    required: ['text']
+}, async (args) => {
+    return {
+        content: [{ type: 'text', text: `Echo: ${args.text}` }]
+    };
+})
+    .onLoad(async (ctx) => {
+    ctx.setRuntimeData('loaded', true);
+});

package/dist/src/server/registry/contracts.d.ts

@@ -0,0 +1,21 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolArgs } from '../types.js';
+import type { MCPServerContext } from '../MCPServer.context.js';
+export type ToolProfileId = 'search' | 'workflow' | 'full';
+export interface ToolHandlerDeps {
+    readonly [depKey: string]: unknown;
+}
+export interface ToolRegistration {
+    readonly tool: Tool;
+    readonly domain: string;
+    readonly bind: (deps: ToolHandlerDeps) => (args: ToolArgs) => Promise<unknown>;
+}
+export interface DomainManifest<TDepKey extends string = string, THandler = unknown, TDomain extends string = string> {
+    readonly kind: 'domain-manifest';
+    readonly version: 1;
+    readonly domain: TDomain;
+    readonly depKey: TDepKey;
+    readonly profiles: readonly ToolProfileId[];
+    readonly registrations: readonly ToolRegistration[];
+    readonly ensure: (ctx: MCPServerContext) => THandler;
+}