@portel/photon 1.4.0 → 1.5.1

package/dist/loader.js

@@ -7,42 +7,180 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { pathToFileURL } from 'url';
 import * as crypto from 'crypto';
-import { SchemaExtractor, DependencyManager } from '@portel/photon-core';
+import { spawn } from 'child_process';
+import { SchemaExtractor, DependencyManager, 
+// Generator utilities (ask/emit pattern from 1.2.0)
+isAsyncGenerator, executeGenerator, 
+// Implicit stateful execution (auto-detect checkpoint yields)
+maybeStatefulExecute, 
+// Elicit for fallback
+prompt as elicitPrompt, confirm as elicitConfirm, 
+// Progress rendering
+ProgressRenderer, createMCPProxy, MCPConfigurationError, SDKMCPClientFactory, resolveMCPSource, 
+// Photon runtime configuration
+loadPhotonMCPConfig, resolveEnvVars, 
+// Shared utilities (photon-core 2.4.0)
+isClass as sharedIsClass, hasAsyncMethods as sharedHasAsyncMethods, findPhotonClass as sharedFindPhotonClass, parseEnvValue as sharedParseEnvValue, compilePhotonTS, getMimeType as sharedGetMimeType, parseRuntimeRequirement, checkRuntimeCompatibility, discoverAssets as sharedDiscoverAssets, } from '@portel/photon-core';
 import * as os from 'os';
+import { MarketplaceManager } from './marketplace-manager.js';
+import { PHOTON_VERSION } from './version.js';
+// Timeout for external fetch requests (marketplace, GitHub)
+const FETCH_TIMEOUT_MS = 30 * 1000;
+import { generateConfigErrorMessage, summarizeConstructorParams, toEnvVarName, } from './shared/config-docs.js';
+import { createLogger } from './shared/logger.js';
+import { getErrorMessage } from './shared/error-handler.js';
+import { validateOrThrow, assertString, notEmpty, hasExtension } from './shared/validation.js';
 export class PhotonLoader {
     dependencyManager;
     verbose;
-    constructor(verbose = false) {
+    mcpClientFactory;
+    /** Cache of loaded Photon instances by source path */
+    loadedPhotons = new Map();
+    /** MCP clients cache - reuse connections */
+    mcpClients = new Map();
+    /** SDK factory for MCP connections */
+    sdkFactory;
+    /** Cached MCP config from ~/.photon/config.json */
+    mcpConfig;
+    /** Progress renderer for inline CLI animation */
+    progressRenderer = new ProgressRenderer();
+    /** Marketplace manager for resolving remote Photons */
+    marketplaceManager;
+    marketplaceManagerPromise;
+    logger;
+    constructor(verbose = false, logger) {
         this.dependencyManager = new DependencyManager();
         this.verbose = verbose;
+        this.logger = logger ?? createLogger({ component: 'photon-loader', minimal: true });
+    }
+    /**
+     * Load MCP configuration from ~/.photon/config.json
+     * Called lazily on first MCP injection
+     */
+    async ensureMCPConfig() {
+        if (!this.mcpConfig) {
+            this.mcpConfig = await loadPhotonMCPConfig();
+            const serverCount = Object.keys(this.mcpConfig.mcpServers).length;
+            if (serverCount > 0) {
+                this.log(`Loaded ${serverCount} MCP servers from config`);
+            }
+        }
+        return this.mcpConfig;
+    }
+    async getMarketplaceManager() {
+        if (this.marketplaceManager) {
+            return this.marketplaceManager;
+        }
+        if (!this.marketplaceManagerPromise) {
+            this.marketplaceManagerPromise = (async () => {
+                const managerLogger = this.logger.child({ component: 'marketplace-manager' });
+                const manager = new MarketplaceManager(managerLogger);
+                await manager.initialize();
+                return manager;
+            })();
+        }
+        this.marketplaceManager = await this.marketplaceManagerPromise;
+        return this.marketplaceManager;
+    }
+    /**
+     * Set MCP client factory for enabling this.mcp() in Photons
+     */
+    setMCPClientFactory(factory) {
+        this.mcpClientFactory = factory;
     }
     /**
      * Log message only if verbose mode is enabled
      */
-    log(message) {
+    log(message, meta) {
         if (this.verbose) {
-            console.error(message);
+            this.logger.info(message, meta);
         }
     }
+    /**
+     * Generate deterministic cache key for an MCP + photon path
+     */
+    getCacheKey(mcpName, photonPath) {
+        const normalized = path.resolve(photonPath);
+        const hash = crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 8);
+        return `${mcpName}-${hash}`;
+    }
+    getPhotonCacheDir() {
+        return path.join(os.homedir(), '.photon', '.cache', 'photons');
+    }
+    sanitizeCacheLabel(label) {
+        return label.replace(/[^a-zA-Z0-9._-]/g, '_');
+    }
+    async writePhotonCacheFile(label, content, hashHint) {
+        const cacheDir = this.getPhotonCacheDir();
+        await fs.mkdir(cacheDir, { recursive: true });
+        const hash = hashHint
+            ? hashHint.replace(/^sha256:/, '').slice(0, 12)
+            : crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+        const safeLabel = this.sanitizeCacheLabel(label);
+        const cachePath = path.join(cacheDir, `${safeLabel}.${hash}.photon.ts`);
+        await fs.writeFile(cachePath, content, 'utf-8');
+        return cachePath;
+    }
+    async runCommand(command, args, cwd) {
+        await new Promise((resolve, reject) => {
+            const child = spawn(command, args, {
+                cwd,
+                stdio: 'inherit',
+            });
+            child.on('error', reject);
+            child.on('exit', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`${command} ${args.join(' ')} exited with code ${code}`));
+                }
+            });
+        });
+    }
     /**
      * Directory where MCP-specific dependencies are cached
      */
-    getDependencyCacheDir(mcpName) {
-        return path.join(os.homedir(), '.cache', 'photon-mcp', 'dependencies', mcpName);
+    getDependencyCacheDir(cacheKey) {
+        return path.join(os.homedir(), '.cache', 'photon-mcp', 'dependencies', cacheKey);
+    }
+    getBuildCacheDir(cacheKey) {
+        return path.join(this.getDependencyCacheDir(cacheKey), '.build');
+    }
+    async clearBuildCache(cacheKey) {
+        const buildDir = this.getBuildCacheDir(cacheKey);
+        await fs.rm(buildDir, { recursive: true, force: true });
+    }
+    async clearDependencyCache(cacheKey) {
+        await this.dependencyManager.clearCache(cacheKey);
+    }
+    async clearAllCaches(cacheKey) {
+        await this.clearDependencyCache(cacheKey);
+        await this.clearBuildCache(cacheKey);
     }
     /**
      * Path to metadata file describing installed dependencies
      */
-    getDependencyMetadataPath(mcpName) {
-        return path.join(this.getDependencyCacheDir(mcpName), 'metadata.json');
+    getDependencyMetadataPath(cacheKey) {
+        return path.join(this.getDependencyCacheDir(cacheKey), 'metadata.json');
     }
-    async readDependencyMetadata(mcpName) {
+    async readDependencyMetadata(cacheKey) {
         try {
-            const data = await fs.readFile(this.getDependencyMetadataPath(mcpName), 'utf-8');
+            const data = await fs.readFile(this.getDependencyMetadataPath(cacheKey), 'utf-8');
             return JSON.parse(data);
         }
+        catch (error) {
+            this.logger.debug('Failed to read dependency metadata', { error });
+            return null; // cache miss
+        }
+    }
+    async pathExists(targetPath) {
+        try {
+            await fs.access(targetPath);
+            return true;
+        }
         catch {
-            return null;
+            return false; // path does not exist
         }
     }
     dependenciesEqual(a, b) {
@@ -52,32 +190,45 @@ export class PhotonLoader {
         if (a.length !== b.length) {
             return false;
         }
-        const normalize = (deps) => deps.map(d => `${d.name}@${d.version}`).sort().join('|');
+        const normalize = (deps) => deps
+            .map((d) => `${d.name}@${d.version}`)
+            .sort()
+            .join('|');
         return normalize(a) === normalize(b);
     }
-    async writeDependencyMetadata(mcpName, hash, dependencies) {
-        const metadataPath = this.getDependencyMetadataPath(mcpName);
+    async writeDependencyMetadata(cacheKey, hash, dependencies, photonPath) {
+        const metadataPath = this.getDependencyMetadataPath(cacheKey);
         await fs.mkdir(path.dirname(metadataPath), { recursive: true });
-        await fs.writeFile(metadataPath, JSON.stringify({ hash, dependencies }, null, 2), 'utf-8');
+        await fs.writeFile(metadataPath, JSON.stringify({ hash, dependencies, photonPath: photonPath ? path.resolve(photonPath) : undefined }, null, 2), 'utf-8');
     }
-    async ensureDependenciesWithHash(mcpName, dependencies, sourceHash) {
-        const metadata = await this.readDependencyMetadata(mcpName);
+    async ensureDependenciesWithHash(cacheKey, mcpName, dependencies, sourceHash, photonPath) {
+        const metadata = await this.readDependencyMetadata(cacheKey);
         const hashMatches = metadata?.hash === sourceHash;
-        const depsMatch = metadata ? this.dependenciesEqual(metadata.dependencies, dependencies) : false;
+        const depsMatch = metadata
+            ? this.dependenciesEqual(metadata.dependencies, dependencies)
+            : false;
         const needsClear = Boolean(metadata && (!hashMatches || !depsMatch));
         if (needsClear) {
-            this.log(`🔄 Dependencies changed for ${mcpName}, clearing cache`);
-            await this.dependencyManager.clearCache(mcpName);
+            const depDir = this.getDependencyCacheDir(cacheKey);
+            const buildDir = this.getBuildCacheDir(cacheKey);
+            this.log(`🔄 Dependencies changed for ${mcpName} (${cacheKey}), clearing caches`, {
+                dependencyCache: depDir,
+                buildCache: buildDir,
+            });
+            await this.clearAllCaches(cacheKey);
         }
         let nodeModules = null;
         if (dependencies.length > 0) {
-            nodeModules = await this.dependencyManager.ensureDependencies(mcpName, dependencies);
+            nodeModules = await this.dependencyManager.ensureDependencies(cacheKey, dependencies);
+            if (nodeModules) {
+                this.log(`📦 Dependencies ready for ${mcpName}`, { nodeModules });
+            }
         }
-        await this.writeDependencyMetadata(mcpName, sourceHash, dependencies);
+        await this.writeDependencyMetadata(cacheKey, sourceHash, dependencies, photonPath);
         return nodeModules;
     }
     shouldRetryInstall(error) {
-        const message = error?.message?.toString() || '';
+        const message = error instanceof Error ? error.message : String(error);
         return (message.includes('Cannot find package') ||
             message.includes('ERR_MODULE_NOT_FOUND') ||
             message.includes('Cannot find module'));
@@ -87,7 +238,10 @@ export class PhotonLoader {
         const regex = /@dependencies\s+([^\r\n]+)/g;
         let match;
         while ((match = regex.exec(source)) !== null) {
-            const entries = match[1].split(',').map(entry => entry.trim()).filter(Boolean);
+            const entries = match[1]
+                .split(',')
+                .map((entry) => entry.trim())
+                .filter(Boolean);
             for (const entry of entries) {
                 const atIndex = entry.lastIndexOf('@');
                 if (atIndex <= 0) {
@@ -112,10 +266,17 @@ export class PhotonLoader {
         }
         return Array.from(map.entries()).map(([name, version]) => ({ name, version }));
     }
+    // parseRuntimeRequirement and checkRuntimeCompatibility are now imported from photon-core
     /**
      * Load a single Photon MCP file
      */
     async loadFile(filePath) {
+        // Validate input
+        assertString(filePath, 'filePath');
+        validateOrThrow(filePath, [
+            notEmpty('Photon file path'),
+            hasExtension('Photon file', ['ts', 'js']),
+        ]);
         try {
             // Resolve to absolute path
             const absolutePath = path.resolve(filePath);
@@ -127,21 +288,39 @@ export class PhotonLoader {
             let dependencies = [];
             let sourceHash;
             let mcpName = '';
+            let cacheKey = null;
             if (absolutePath.endsWith('.ts')) {
                 tsContent = await fs.readFile(absolutePath, 'utf-8');
+                // Check runtime version compatibility
+                const requiredRuntime = parseRuntimeRequirement(tsContent);
+                if (requiredRuntime) {
+                    const check = checkRuntimeCompatibility(requiredRuntime, PHOTON_VERSION);
+                    if (!check.compatible) {
+                        throw new Error(check.message);
+                    }
+                }
                 const extracted = await this.dependencyManager.extractDependencies(absolutePath);
                 const parsed = PhotonLoader.parseDependenciesFromSource(tsContent);
                 dependencies = PhotonLoader.mergeDependencySpecs(extracted, parsed);
+                // Auto-include @portel/photon-core if imported (it's the runtime, always available)
+                if (tsContent.includes('@portel/photon-core') &&
+                    !dependencies.some((d) => d.name === '@portel/photon-core')) {
+                    dependencies.push({
+                        name: '@portel/photon-core',
+                        version: `^${PHOTON_VERSION.split('.').slice(0, 2).join('.')}.0`,
+                    });
+                }
                 mcpName = path.basename(absolutePath, '.ts').replace('.photon', '');
+                cacheKey = this.getCacheKey(mcpName, absolutePath);
                 sourceHash = crypto.createHash('sha256').update(tsContent).digest('hex');
                 if (dependencies.length > 0) {
                     this.log(`📦 Found ${dependencies.length} dependencies`);
                 }
-                await this.ensureDependenciesWithHash(mcpName, dependencies, sourceHash);
+                await this.ensureDependenciesWithHash(cacheKey, mcpName, dependencies, sourceHash, absolutePath);
             }
             const importModule = async () => {
                 if (tsContent) {
-                    const cachedJsPath = await this.compileTypeScript(absolutePath, mcpName, tsContent);
+                    const cachedJsPath = await this.compileTypeScript(absolutePath, cacheKey, tsContent);
                     const cachedJsUrl = pathToFileURL(cachedJsPath).href;
                     return await import(`${cachedJsUrl}?t=${Date.now()}`);
                 }
@@ -152,10 +331,10 @@ export class PhotonLoader {
                 module = await importModule();
             }
             catch (error) {
-                if (this.shouldRetryInstall(error) && tsContent && sourceHash && mcpName) {
+                if (this.shouldRetryInstall(error) && tsContent && sourceHash && mcpName && cacheKey) {
                     this.log(`⚠️  Missing dependency detected, reinstalling dependencies for ${mcpName}`);
-                    await this.dependencyManager.clearCache(mcpName);
-                    await this.ensureDependenciesWithHash(mcpName, dependencies, sourceHash);
+                    await this.clearAllCaches(cacheKey);
+                    await this.ensureDependenciesWithHash(cacheKey, mcpName, dependencies, sourceHash, absolutePath);
                     module = await importModule();
                 }
                 else {
@@ -164,66 +343,91 @@ export class PhotonLoader {
             }
             // Find the exported class
             const MCPClass = this.findMCPClass(module);
-            if (!MCPClass) {
+            if (!MCPClass || !this.isClass(MCPClass)) {
                 throw new Error('No MCP class found in file. Expected a class with async methods.');
             }
             // Get MCP name
             const name = this.getMCPName(MCPClass);
-            // Extract constructor parameters from source
-            const constructorParams = await this.extractConstructorParams(absolutePath);
-            // Resolve values from environment variables
-            const { values, configError } = this.resolveConstructorArgs(constructorParams, name);
-            // Create instance with injected config
+            // Resolve all constructor injections using type-based detection
+            const { values, configError } = await this.resolveAllInjections(tsContent || '', name, absolutePath);
+            // Create instance with injected dependencies
             let instance;
             try {
                 instance = new MCPClass(...values);
             }
             catch (error) {
                 // Constructor threw an error (likely validation failure)
-                // Enhance the error message with config information
-                const enhancedError = this.enhanceConstructorError(error, name, constructorParams, configError);
+                const constructorParams = await this.extractConstructorParams(absolutePath);
+                const enhancedError = this.enhanceConstructorError(error instanceof Error ? error : new Error(String(error)), name, constructorParams, configError);
                 throw enhancedError;
             }
             // Store config warning for later if there were missing params
-            // (constructor didn't throw, but params were missing - they had defaults)
             if (configError) {
                 instance._photonConfigError = configError;
-                console.error(`⚠️  ${name} loaded with configuration warnings:`);
-                console.error(configError);
+                this.logger.warn(`⚠️  ${name} loaded with configuration warnings:`);
+                this.logger.warn(String(configError));
+            }
+            // Inject @mcp dependencies from source (this.github, this.fs, etc.)
+            if (tsContent) {
+                await this.injectMCPDependencies(instance, tsContent, name);
+            }
+            // Inject MCP client factory if available (enables this.mcp() calls)
+            const setMCPFactory = instance.setMCPFactory;
+            if (this.mcpClientFactory && typeof setMCPFactory === 'function') {
+                setMCPFactory.call(instance, this.mcpClientFactory);
+                this.log(`Injected MCP factory into ${name}`);
+            }
+            // Check @cli dependencies (required system CLI tools)
+            if (tsContent) {
+                await this.checkCLIDependencies(tsContent, name);
             }
             // Call lifecycle hook if present with error handling
-            if (instance.onInitialize) {
+            const onInitialize = instance.onInitialize;
+            if (typeof onInitialize === 'function') {
                 try {
-                    await instance.onInitialize();
+                    await onInitialize.call(instance);
                 }
                 catch (error) {
-                    const initError = new Error(`Initialization failed for ${name}: ${error.message}\n` +
+                    const initError = new Error(`Initialization failed for ${name}: ${getErrorMessage(error)}\n` +
                         `\nThe onInitialize() lifecycle hook threw an error.\n` +
                         `Check your constructor configuration and initialization logic.`);
                     initError.name = 'PhotonInitializationError';
-                    initError.stack = error.stack;
+                    if (error instanceof Error && error.stack) {
+                        initError.stack = error.stack;
+                    }
                     throw initError;
                 }
             }
             // Extract tools, templates, and statics (with schema override support)
             const { tools, templates, statics } = await this.extractTools(MCPClass, absolutePath);
+            // Extract assets from source and discover asset folder
+            const assets = await this.discoverAssets(absolutePath, tsContent || '');
             const counts = [
                 tools.length > 0 ? `${tools.length} tools` : null,
                 templates.length > 0 ? `${templates.length} templates` : null,
                 statics.length > 0 ? `${statics.length} statics` : null,
-            ].filter(Boolean).join(', ');
+                assets && (assets.ui.length > 0 || assets.prompts.length > 0 || assets.resources.length > 0)
+                    ? `${assets.ui.length + assets.prompts.length + assets.resources.length} assets`
+                    : null,
+            ]
+                .filter(Boolean)
+                .join(', ');
             this.log(`✅ Loaded: ${name} (${counts})`);
-            return {
+            const result = {
                 name,
                 description: `${name} MCP`,
                 tools,
                 templates,
                 statics,
                 instance,
+                assets,
             };
+            // Store class constructor for static method access
+            result.classConstructor = MCPClass;
+            return result;
         }
         catch (error) {
-            console.error(`❌ Failed to load ${filePath}: ${error.message}`);
+            this.logger.error(`❌ Failed to load ${filePath}: ${getErrorMessage(error)}`);
             throw error;
         }
     }
@@ -238,9 +442,10 @@ export class PhotonLoader {
             const tsContent = await fs.readFile(absolutePath, 'utf-8');
             const hash = crypto.createHash('sha256').update(tsContent).digest('hex').slice(0, 16);
             const mcpName = path.basename(absolutePath, '.ts').replace('.photon', '');
-            const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'dependencies', mcpName);
+            const cacheKey = this.getCacheKey(mcpName, absolutePath);
+            const buildDir = this.getBuildCacheDir(cacheKey);
             const fileName = path.basename(absolutePath, '.ts');
-            const cachedJsPath = path.join(cacheDir, `${fileName}.${hash}.mjs`);
+            const cachedJsPath = path.join(buildDir, `${fileName}.${hash}.mjs`);
             try {
                 await fs.unlink(cachedJsPath);
             }
@@ -252,94 +457,47 @@ export class PhotonLoader {
     }
     /**
      * Compile TypeScript file to JavaScript and cache it
+     * Delegates to shared compilePhotonTS from photon-core
      */
-    async compileTypeScript(tsFilePath, mcpName, tsContent) {
-        const source = tsContent ?? await fs.readFile(tsFilePath, 'utf-8');
-        const hash = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
-        // Store compiled files in the same directory as dependencies for module resolution
-        const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'dependencies', mcpName);
-        const fileName = path.basename(tsFilePath, '.ts');
-        const cachedJsPath = path.join(cacheDir, `${fileName}.${hash}.mjs`);
-        // Check if cached version exists
-        try {
-            await fs.access(cachedJsPath);
-            this.log(`Using cached compiled version`);
-            return cachedJsPath;
-        }
-        catch {
-            // Cache miss - compile it
-        }
-        // Compile TypeScript to JavaScript
-        this.log(`Compiling ${path.basename(tsFilePath)} with esbuild...`);
-        const esbuild = await import('esbuild');
-        const result = await esbuild.transform(source, {
-            loader: 'ts',
-            format: 'esm',
-            target: 'es2022',
-            sourcemap: 'inline'
-        });
-        // Ensure cache directory exists
-        await fs.mkdir(cacheDir, { recursive: true });
-        // Write compiled JavaScript to cache
-        await fs.writeFile(cachedJsPath, result.code, 'utf-8');
-        this.log(`Compiled and cached`);
-        return cachedJsPath;
+    async compileTypeScript(tsFilePath, cacheKey, tsContent) {
+        const cacheDir = this.getBuildCacheDir(cacheKey);
+        const result = await compilePhotonTS(tsFilePath, { cacheDir, content: tsContent });
+        this.log(`Compiled: ${path.basename(tsFilePath)}`, { cached: result });
+        return result;
     }
     /**
      * Find the MCP class in a module
-     * Looks for default export or any class with async methods
+     * Delegates to shared findPhotonClass from photon-core
      */
     findMCPClass(module) {
-        // Try default export first
-        if (module.default && this.isClass(module.default)) {
-            if (this.hasAsyncMethods(module.default)) {
-                return module.default;
-            }
-        }
-        // Try named exports
-        for (const exportedItem of Object.values(module)) {
-            if (this.isClass(exportedItem) && this.hasAsyncMethods(exportedItem)) {
-                return exportedItem;
-            }
-        }
-        return null;
+        return sharedFindPhotonClass(module);
     }
     /**
      * Check if a function is a class constructor
+     * Delegates to shared isClass from photon-core
      */
     isClass(fn) {
-        return typeof fn === 'function' && /^\s*class\s+/.test(fn.toString());
+        return sharedIsClass(fn);
     }
     /**
      * Check if a class has async methods
+     * Delegates to shared hasAsyncMethods from photon-core
      */
     hasAsyncMethods(ClassConstructor) {
-        const prototype = ClassConstructor.prototype;
-        for (const key of Object.getOwnPropertyNames(prototype)) {
-            if (key === 'constructor')
-                continue;
-            const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
-            if (descriptor && typeof descriptor.value === 'function') {
-                // Check if it's an async function
-                const fn = descriptor.value;
-                if (fn.constructor.name === 'AsyncFunction') {
-                    return true;
-                }
-            }
-        }
-        return false;
+        return sharedHasAsyncMethods(ClassConstructor);
     }
     /**
      * Get MCP name from class
      */
     getMCPName(mcpClass) {
         // Try to use PhotonMCP's method if available
-        if (typeof mcpClass.getMCPName === 'function') {
-            return mcpClass.getMCPName();
+        const classWithStatic = mcpClass;
+        if (typeof classWithStatic.getMCPName === 'function') {
+            return classWithStatic.getMCPName();
         }
         // Fallback: implement convention for plain classes
         // Convert PascalCase to kebab-case (e.g., MyAwesomeMCP → my-awesome-mcp)
-        return mcpClass.name
+        return classWithStatic.name
             .replace(/MCP$/, '') // Remove "MCP" suffix if present
             .replace(/([A-Z])/g, '-$1')
             .toLowerCase()
@@ -350,22 +508,39 @@ export class PhotonLoader {
      */
     getToolMethods(mcpClass) {
         // Try to use PhotonMCP's method if available
-        if (typeof mcpClass.getToolMethods === 'function') {
-            return mcpClass.getToolMethods();
+        const classWithStatic = mcpClass;
+        if (typeof classWithStatic.getToolMethods === 'function') {
+            return classWithStatic.getToolMethods();
         }
         // Fallback: implement convention for plain classes
-        const prototype = mcpClass.prototype;
+        const prototype = classWithStatic.prototype;
         const methods = [];
+        const conventionMethods = new Set([
+            'constructor',
+            'onInitialize',
+            'onShutdown',
+            'configure',
+            'getConfig',
+        ]);
+        const builtInStatics = new Set(['length', 'name', 'prototype', 'getToolMethods']);
+        // Get instance methods from prototype
         Object.getOwnPropertyNames(prototype).forEach((name) => {
-            // Skip constructor, private methods (starting with _), and lifecycle hooks
-            if (name !== 'constructor' &&
-                !name.startsWith('_') &&
-                name !== 'onInitialize' &&
-                name !== 'onShutdown' &&
+            if (!name.startsWith('_') &&
+                !conventionMethods.has(name) &&
                 typeof prototype[name] === 'function') {
                 methods.push(name);
             }
         });
+        // Get static methods from class constructor
+        const classAsRecord = mcpClass;
+        Object.getOwnPropertyNames(mcpClass).forEach((name) => {
+            if (!name.startsWith('_') &&
+                !builtInStatics.has(name) &&
+                !conventionMethods.has(name) &&
+                typeof classAsRecord[name] === 'function') {
+                methods.push(name);
+            }
+        });
         return methods;
     }
     /**
@@ -425,14 +600,17 @@ export class PhotonLoader {
             }
             catch (jsonError) {
                 // .schema.json doesn't exist, try extracting from .ts source
-                if (jsonError.code === 'ENOENT') {
+                const isNotFound = jsonError instanceof Error &&
+                    'code' in jsonError &&
+                    jsonError.code === 'ENOENT';
+                if (isNotFound) {
                     const extractor = new SchemaExtractor();
                     const source = await fs.readFile(sourceFilePath, 'utf-8');
                     const metadata = extractor.extractAllFromSource(source);
                     // Filter by method names that exist in the class
-                    tools = metadata.tools.filter(t => methodNames.includes(t.name));
-                    templates = metadata.templates.filter(t => methodNames.includes(t.name));
-                    statics = metadata.statics.filter(s => methodNames.includes(s.name));
+                    tools = metadata.tools.filter((t) => methodNames.includes(t.name));
+                    templates = metadata.templates.filter((t) => methodNames.includes(t.name));
+                    statics = metadata.statics.filter((s) => methodNames.includes(s.name));
                     this.log(`Extracted ${tools.length} tools, ${templates.length} templates, ${statics.length} statics from source`);
                     return { tools, templates, statics };
                 }
@@ -440,7 +618,7 @@ export class PhotonLoader {
             }
         }
         catch (error) {
-            console.error(`⚠️  Failed to extract schemas: ${error.message}. Using basic tools.`);
+            this.logger.warn(`⚠️  Failed to extract schemas: ${getErrorMessage(error)}. Using basic tools.`);
             // Fallback: create basic tools without detailed schemas
             for (const methodName of methodNames) {
                 tools.push({
@@ -465,18 +643,471 @@ export class PhotonLoader {
             return extractor.extractConstructorParams(source);
         }
         catch (error) {
-            console.error(`Failed to extract constructor params: ${error.message}`);
+            this.logger.warn(`Failed to extract constructor params: ${getErrorMessage(error)}`);
             return [];
         }
     }
+    /**
+     * Resolve all constructor injections using type-based detection
+     * - Primitives (string, number, boolean) → env var
+     * - Non-primitives matching @mcp → MCP client
+     * - Non-primitives matching @photon → Photon instance
+     *
+     * Throws MCPConfigurationError if MCP dependencies are missing
+     */
+    async resolveAllInjections(source, mcpName, photonPath) {
+        const extractor = new SchemaExtractor();
+        const injections = extractor.resolveInjections(source, mcpName);
+        const values = [];
+        const missingEnvVars = [];
+        const missingMCPs = [];
+        const missingPhotons = [];
+        for (const injection of injections) {
+            const { param, injectionType } = injection;
+            switch (injectionType) {
+                case 'env': {
+                    // Inject from environment variable
+                    const envVarName = injection.envVarName;
+                    const envValue = process.env[envVarName];
+                    if (envValue !== undefined) {
+                        values.push(this.parseEnvValue(envValue, param.type));
+                    }
+                    else if (param.hasDefault || param.isOptional) {
+                        values.push(undefined);
+                    }
+                    else {
+                        missingEnvVars.push({
+                            paramName: param.name,
+                            envVarName,
+                            type: param.type,
+                        });
+                        values.push(undefined);
+                    }
+                    break;
+                }
+                case 'mcp': {
+                    // Inject MCP client
+                    const mcpDep = injection.mcpDependency;
+                    try {
+                        const client = await this.getMCPClient(mcpDep);
+                        values.push(client);
+                        this.log(`  ✅ Injected MCP: ${mcpDep.name} (${mcpDep.source})`);
+                    }
+                    catch (error) {
+                        // If it's already an MCPConfigurationError, re-throw it directly
+                        if (error instanceof MCPConfigurationError) {
+                            throw error;
+                        }
+                        this.log(`  ⚠️ Failed to create MCP client for ${mcpDep.name}: ${getErrorMessage(error)}`);
+                        missingMCPs.push({
+                            name: mcpDep.name,
+                            source: mcpDep.source,
+                            sourceType: mcpDep.sourceType,
+                            declaredIn: path.basename(photonPath),
+                            originalError: getErrorMessage(error),
+                        });
+                        values.push(undefined);
+                    }
+                    break;
+                }
+                case 'photon': {
+                    // Inject Photon instance
+                    const photonDep = injection.photonDependency;
+                    try {
+                        const photonInstance = await this.getPhotonInstance(photonDep, photonPath);
+                        values.push(photonInstance);
+                        this.log(`  ✅ Injected Photon: ${photonDep.name} (${photonDep.source})`);
+                    }
+                    catch (error) {
+                        this.log(`  ⚠️ Failed to load Photon ${photonDep.name}: ${getErrorMessage(error)}`);
+                        missingPhotons.push(`@photon ${photonDep.name} ${photonDep.source}: ${getErrorMessage(error)}`);
+                        values.push(undefined);
+                    }
+                    break;
+                }
+            }
+        }
+        // Throw MCPConfigurationError immediately if MCP dependencies are missing
+        // This provides actionable guidance to users
+        if (missingMCPs.length > 0) {
+            throw new MCPConfigurationError(missingMCPs);
+        }
+        // Build config error for env vars and photon dependencies
+        let configError = null;
+        if (missingEnvVars.length > 0 || missingPhotons.length > 0) {
+            const parts = [];
+            if (missingEnvVars.length > 0) {
+                parts.push(generateConfigErrorMessage(mcpName, missingEnvVars));
+            }
+            if (missingPhotons.length > 0) {
+                parts.push(`Missing Photon dependencies:\n` +
+                    missingPhotons.map((d) => `  • ${d}`).join('\n') +
+                    `\n\nEnsure these Photons are installed and accessible.`);
+            }
+            configError = parts.join('\n\n');
+        }
+        return { values, configError };
+    }
+    /**
+     * Get or create an MCP client for a dependency
+     *
+     * Resolution order:
+     * 1. Check ~/.photon/config.json for configured server
+     * 2. Fall back to resolving from @mcp declaration source
+     *
+     * Validates connection on first use - throws MCPConfigurationError if connection fails
+     */
+    async getMCPClient(dep) {
+        // Check cache first
+        if (this.mcpClients.has(dep.name)) {
+            return this.mcpClients.get(dep.name);
+        }
+        // Try to get config from ~/.photon/config.json first
+        const photonConfig = await this.ensureMCPConfig();
+        let serverConfig;
+        let isFromConfig = false;
+        if (photonConfig.mcpServers[dep.name]) {
+            // Use pre-configured server from config.json
+            serverConfig = resolveEnvVars(photonConfig.mcpServers[dep.name]);
+            isFromConfig = true;
+            this.log(`  Using configured MCP: ${dep.name} from config.json`);
+        }
+        else {
+            // Fall back to resolving from @mcp declaration
+            serverConfig = resolveMCPSource(dep.name, dep.source, dep.sourceType);
+            this.log(`  Resolving MCP: ${dep.name} from @mcp declaration (${dep.source})`);
+        }
+        // Build config with this MCP
+        const mcpConfig = {
+            mcpServers: {
+                [dep.name]: serverConfig,
+            },
+        };
+        // Create a factory for this MCP
+        // Note: Each MCP gets its own factory for isolation
+        const factory = new SDKMCPClientFactory(mcpConfig, this.verbose);
+        // Create client and proxy
+        const client = factory.create(dep.name);
+        const proxy = createMCPProxy(client);
+        // Validate connection by attempting to list tools
+        // This catches configuration errors early (missing env vars, wrong command, etc.)
+        try {
+            this.log(`  Connecting to MCP: ${dep.name}...`);
+            await client.list();
+            this.log(`  ✅ Connected to MCP: ${dep.name}`);
+        }
+        catch (error) {
+            const errorMsg = getErrorMessage(error) || 'Unknown connection error';
+            // If not configured in mcp-servers.json, throw configuration error
+            if (!isFromConfig) {
+                throw new MCPConfigurationError([
+                    {
+                        name: dep.name,
+                        source: dep.source,
+                        sourceType: dep.sourceType,
+                        originalError: errorMsg,
+                    },
+                ]);
+            }
+            // If configured but failed, provide more specific error
+            throw new Error(`MCP "${dep.name}" is configured but failed to connect: ${errorMsg}\n` +
+                `Check your ~/.photon/config.json configuration and ensure:\n` +
+                `  • The command/URL is correct\n` +
+                `  • Required environment variables are set\n` +
+                `  • The MCP server is accessible`);
+        }
+        // Cache it
+        this.mcpClients.set(dep.name, proxy);
+        return proxy;
+    }
+    /**
+     * Get or load a Photon instance for a dependency
+     */
+    async getPhotonInstance(dep, currentPhotonPath) {
+        // Resolve the Photon path
+        const resolvedPath = await this.resolvePhotonPath(dep, currentPhotonPath);
+        // Check cache
+        if (this.loadedPhotons.has(resolvedPath)) {
+            return this.loadedPhotons.get(resolvedPath).instance;
+        }
+        // Load the Photon (recursive call)
+        this.log(`  📦 Loading Photon dependency: ${dep.name} from ${resolvedPath}`);
+        const loaded = await this.loadFile(resolvedPath);
+        // Cache it
+        this.loadedPhotons.set(resolvedPath, loaded);
+        return loaded.instance;
+    }
+    /**
+     * Resolve Photon dependency path based on source type
+     */
+    async resolvePhotonPath(dep, currentPhotonPath) {
+        switch (dep.sourceType) {
+            case 'local':
+                if (dep.source.startsWith('./') || dep.source.startsWith('../')) {
+                    return path.resolve(path.dirname(currentPhotonPath), dep.source);
+                }
+                return dep.source;
+            case 'marketplace':
+                return await this.resolveMarketplacePhoton(dep, currentPhotonPath);
+            case 'github':
+                return await this.fetchGithubPhoton(dep);
+            case 'npm':
+                return await this.resolveNpmPhoton(dep);
+            default:
+                throw new Error(`Unknown Photon source type: ${dep.sourceType}`);
+        }
+    }
+    async resolveMarketplacePhoton(dep, currentPhotonPath) {
+        const { slug, fileName, marketplaceHint } = this.normalizeMarketplaceSource(dep.source);
+        const photonDir = path.dirname(currentPhotonPath);
+        const candidates = [
+            path.resolve(photonDir, fileName),
+            path.resolve(photonDir, 'photons', fileName),
+            path.resolve(photonDir, 'templates', fileName),
+            path.join(process.cwd(), fileName),
+            path.join(process.cwd(), 'photons', fileName),
+            path.join(process.cwd(), 'templates', fileName),
+            path.join(os.homedir(), '.photon', fileName),
+            path.join(os.homedir(), '.photon', 'photons', fileName),
+            path.join(os.homedir(), '.photon', 'marketplace', fileName),
+        ];
+        for (const candidate of candidates) {
+            if (await this.pathExists(candidate)) {
+                return candidate;
+            }
+        }
+        const downloaded = await this.fetchPhotonFromMarketplace(slug, marketplaceHint);
+        if (downloaded) {
+            return downloaded;
+        }
+        throw new Error(`Photon "${dep.source}" not found in local paths or configured marketplaces. ` +
+            `Checked: ${candidates.join(', ')}`);
+    }
+    normalizeMarketplaceSource(source) {
+        let slugSource = source;
+        let marketplaceHint;
+        if (source.includes('/')) {
+            const [hint, rest] = source.split('/', 2);
+            if (hint && rest) {
+                marketplaceHint = hint;
+                slugSource = rest;
+            }
+        }
+        const slug = slugSource
+            .replace(/\.photon\.ts$/, '')
+            .replace(/\.photon$/, '')
+            .replace(/\.ts$/, '')
+            .trim();
+        const normalizedSlug = slug || slugSource.replace(/[\\/]/g, '-');
+        const fileName = `${normalizedSlug}.photon.ts`;
+        return { slug: normalizedSlug, fileName, marketplaceHint };
+    }
+    async fetchPhotonFromMarketplace(slug, marketplaceHint) {
+        try {
+            const manager = await this.getMarketplaceManager();
+            try {
+                await manager.autoUpdateStaleCaches();
+            }
+            catch {
+                // Best effort; stale caches are acceptable
+            }
+            if (marketplaceHint) {
+                const hinted = manager.get(marketplaceHint);
+                if (hinted) {
+                    const hintedPath = await this.fetchPhotonFromSpecificMarketplace(hinted, slug);
+                    if (hintedPath) {
+                        return hintedPath;
+                    }
+                }
+            }
+            const result = await manager.fetchMCP(slug);
+            if (result?.content) {
+                return await this.writePhotonCacheFile(`${result.marketplace.name}-${slug}`, result.content, result.metadata?.hash);
+            }
+        }
+        catch (error) {
+            this.log(`  ⚠️ Marketplace lookup failed for ${slug}: ${getErrorMessage(error)}`);
+        }
+        return null;
+    }
+    async fetchPhotonFromSpecificMarketplace(marketplace, slug) {
+        try {
+            if (marketplace.sourceType === 'local') {
+                const localPath = marketplace.url.replace('file://', '');
+                const photonPath = path.join(localPath, `${slug}.photon.ts`);
+                if (await this.pathExists(photonPath)) {
+                    return photonPath;
+                }
+                return null;
+            }
+            const baseUrl = marketplace.url.replace(/\/$/, '');
+            const response = await fetch(`${baseUrl}/${slug}.photon.ts`, {
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+            if (response.ok) {
+                const content = await response.text();
+                return await this.writePhotonCacheFile(`${marketplace.name}-${slug}`, content);
+            }
+        }
+        catch (error) {
+            this.log(`  ⚠️ Failed to fetch ${slug} from marketplace ${marketplace.name}: ${getErrorMessage(error)}`);
+        }
+        return null;
+    }
+    async fetchGithubPhoton(dep) {
+        const info = this.parseGithubSource(dep);
+        const url = `https://raw.githubusercontent.com/${info.owner}/${info.repo}/${info.ref}/${info.filePath}`;
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to download Photon from GitHub (${dep.source}): HTTP ${response.status}`);
+        }
+        const content = await response.text();
+        const label = `${info.owner}-${info.repo}-${info.filePath.replace(/[\\/]/g, '_')}`;
+        return await this.writePhotonCacheFile(label, content);
+    }
+    parseGithubSource(dep) {
+        let source = dep.source
+            .replace(/^github:/, '')
+            .replace(/^https?:\/\/github\.com\//, '')
+            .replace(/^git@github\.com:/, '')
+            .replace(/\.git$/, '');
+        const parts = source.split('/');
+        if (parts.length < 2) {
+            throw new Error(`Invalid GitHub source: ${dep.source}`);
+        }
+        const owner = parts.shift();
+        let repoPart = parts.shift();
+        let ref = 'main';
+        const repoRefMatch = repoPart.match(/([^@]+)@(.+)/);
+        if (repoRefMatch) {
+            repoPart = repoRefMatch[1];
+            ref = repoRefMatch[2];
+        }
+        if (parts[0] === 'blob' && parts.length >= 2) {
+            parts.shift();
+            ref = parts.shift();
+        }
+        let filePath;
+        if (parts.length === 0) {
+            const slug = dep.name
+                .replace(/([A-Z])/g, '-$1')
+                .toLowerCase()
+                .replace(/^-/, '');
+            filePath = `${slug || 'photon'}.photon.ts`;
+        }
+        else {
+            filePath = parts.join('/');
+            if (!filePath.endsWith('.ts')) {
+                filePath = filePath.endsWith('.photon') ? `${filePath}.ts` : `${filePath}.photon.ts`;
+            }
+        }
+        return { owner, repo: repoPart, ref, filePath };
+    }
+    async resolveNpmPhoton(dep) {
+        const { packageSpec, packageName, filePath } = this.parseNpmSource(dep.source);
+        const cacheDir = path.join(os.homedir(), '.photon', '.cache', 'npm', this.sanitizeCacheLabel(packageSpec));
+        await fs.mkdir(cacheDir, { recursive: true });
+        await this.ensureNpmPackageInstalled(cacheDir, packageSpec, packageName);
+        const packageRoot = this.getPackageInstallPath(cacheDir, packageName);
+        if (!(await this.pathExists(packageRoot))) {
+            throw new Error(`npm package "${packageSpec}" did not install correctly.`);
+        }
+        if (filePath) {
+            const normalized = filePath.replace(/^\//, '');
+            const explicitCandidates = [path.join(packageRoot, normalized)];
+            if (!normalized.endsWith('.ts')) {
+                explicitCandidates.push(path.join(packageRoot, `${normalized}.photon.ts`));
+            }
+            for (const candidate of explicitCandidates) {
+                if (await this.pathExists(candidate)) {
+                    return candidate;
+                }
+            }
+        }
+        const discovered = await this.findPhotonFile(packageRoot);
+        if (discovered) {
+            return discovered;
+        }
+        throw new Error(`Unable to locate a .photon.ts file within npm package ${packageSpec}.`);
+    }
+    parseNpmSource(source) {
+        let cleaned = source.replace(/^npm:/, '');
+        const [specPart, filePath] = cleaned.split('#', 2);
+        return {
+            packageSpec: specPart,
+            packageName: this.extractPackageName(specPart),
+            filePath,
+        };
+    }
+    extractPackageName(spec) {
+        if (spec.startsWith('@')) {
+            const idx = spec.indexOf('@', 1);
+            return idx === -1 ? spec : spec.slice(0, idx);
+        }
+        const idx = spec.indexOf('@');
+        return idx === -1 ? spec : spec.slice(0, idx);
+    }
+    getPackageInstallPath(cacheDir, packageName) {
+        if (packageName.startsWith('@')) {
+            const segments = packageName.split('/');
+            return path.join(cacheDir, 'node_modules', segments[0], segments[1] || '');
+        }
+        return path.join(cacheDir, 'node_modules', packageName);
+    }
+    async ensureNpmPackageInstalled(cacheDir, packageSpec, packageName) {
+        const packageJsonPath = path.join(cacheDir, 'package.json');
+        if (!(await this.pathExists(packageJsonPath))) {
+            const pkgName = `photon-npm-${this.sanitizeCacheLabel(packageSpec)}`;
+            await fs.writeFile(packageJsonPath, JSON.stringify({ name: pkgName, version: PHOTON_VERSION }, null, 2), 'utf-8');
+        }
+        const packageRoot = this.getPackageInstallPath(cacheDir, packageName);
+        if (await this.pathExists(packageRoot)) {
+            return;
+        }
+        const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        await this.runCommand(npmCmd, ['install', packageSpec, '--omit=dev', '--silent', '--no-save'], cacheDir);
+    }
+    async findPhotonFile(dir, depth = 0) {
+        if (depth > 4) {
+            return null;
+        }
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            this.logger.debug('Failed to read directory', { error });
+            return null; // directory inaccessible
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.photon.ts')) {
+                return path.join(dir, entry.name);
+            }
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name === '.git') {
+                    continue;
+                }
+                const child = await this.findPhotonFile(path.join(dir, entry.name), depth + 1);
+                if (child) {
+                    return child;
+                }
+            }
+        }
+        return null;
+    }
     /**
      * Resolve constructor arguments from environment variables
+     * @deprecated Use resolveAllInjections instead
      */
     resolveConstructorArgs(params, mcpName) {
         const values = [];
         const missing = [];
         for (const param of params) {
-            const envVarName = this.toEnvVarName(mcpName, param.name);
+            const envVarName = toEnvVarName(mcpName, param.name);
             const envValue = process.env[envVarName];
             if (envValue !== undefined) {
                 // Environment variable provided - parse and use it
@@ -497,67 +1128,23 @@ export class PhotonLoader {
                 values.push(undefined);
             }
         }
-        const configError = missing.length > 0
-            ? this.generateConfigErrorMessage(mcpName, missing)
-            : null;
+        const configError = missing.length > 0 ? generateConfigErrorMessage(mcpName, missing) : null;
         return { values, configError };
     }
-    /**
-     * Convert MCP name and parameter name to environment variable name
-     * Example: filesystem, workdir → FILESYSTEM_WORKDIR
-     */
-    toEnvVarName(mcpName, paramName) {
-        const mcpPrefix = mcpName.toUpperCase().replace(/-/g, '_');
-        const paramSuffix = paramName
-            .replace(/([A-Z])/g, '_$1')
-            .toUpperCase()
-            .replace(/^_/, '');
-        return `${mcpPrefix}_${paramSuffix}`;
-    }
     /**
      * Parse environment variable value based on TypeScript type
+     * Delegates to shared parseEnvValue from photon-core
      */
     parseEnvValue(value, type) {
-        switch (type) {
-            case 'number':
-                return parseFloat(value);
-            case 'boolean':
-                return value.toLowerCase() === 'true';
-            case 'string':
-            default:
-                return value;
-        }
+        return sharedParseEnvValue(value, type);
     }
     /**
      * Enhance constructor error with configuration guidance
      */
     enhanceConstructorError(error, mcpName, constructorParams, configError) {
-        const originalMessage = error.message;
+        const originalMessage = getErrorMessage(error);
         // Build detailed env var documentation with examples
-        const envVarDocs = constructorParams.map(param => {
-            const envVarName = this.toEnvVarName(mcpName, param.name);
-            const required = !param.isOptional && !param.hasDefault;
-            const status = required ? '[REQUIRED]' : '[OPTIONAL]';
-            // Generate helpful example values based on type and name
-            const exampleValue = this.generateExampleValue(param.name, param.type);
-            const defaultInfo = param.hasDefault
-                ? ` (default: ${JSON.stringify(param.defaultValue)})`
-                : '';
-            let line = `  • ${envVarName} ${status}`;
-            line += `\n    Type: ${param.type}${defaultInfo}`;
-            if (exampleValue) {
-                line += `\n    Example: ${envVarName}="${exampleValue}"`;
-            }
-            return line;
-        }).join('\n\n');
-        // Build example config with placeholder values
-        const envExample = {};
-        constructorParams.forEach(param => {
-            const envVarName = this.toEnvVarName(mcpName, param.name);
-            if (!param.isOptional && !param.hasDefault) {
-                envExample[envVarName] = this.generateExampleValue(param.name, param.type) || `your-${param.name}`;
-            }
-        });
+        const { docs: envVarDocs, exampleEnv: envExample } = summarizeConstructorParams(constructorParams, mcpName);
         const enhancedMessage = `
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ❌ Configuration Error: ${mcpName} MCP failed to initialize
@@ -601,118 +1188,396 @@ Run: photon mcp ${mcpName} --config
         return enhanced;
     }
     /**
-     * Generate helpful example values based on parameter name and type
+     * Execute a tool on the loaded MCP instance
+     * Handles both regular async methods and async generators
+     *
+     * For generators with checkpoint yields, automatically uses stateful execution
+     * with JSONL persistence. The run ID is returned in the result for stateful workflows.
+     *
+     * @param mcp - The loaded Photon MCP
+     * @param toolName - Name of the tool to execute
+     * @param parameters - Input parameters for the tool
+     * @param options - Optional execution options
+     * @returns Tool result, or wrapped result with runId for stateful workflows
      */
-    generateExampleValue(paramName, paramType) {
-        const lowerName = paramName.toLowerCase();
-        // API keys and tokens
-        if (lowerName.includes('apikey') || lowerName.includes('api_key')) {
-            return 'sk_your_api_key_here';
-        }
-        if (lowerName.includes('token') || lowerName.includes('secret')) {
-            return 'your_secret_token';
-        }
-        // URLs and endpoints
-        if (lowerName.includes('url') || lowerName.includes('endpoint')) {
-            return 'https://api.example.com';
-        }
-        if (lowerName.includes('host') || lowerName.includes('server')) {
-            return 'localhost';
+    async executeTool(mcp, toolName, parameters, options) {
+        try {
+            // Check for configuration errors before executing tool
+            if (mcp.instance._photonConfigError) {
+                throw new Error(mcp.instance._photonConfigError);
+            }
+            // Check if instance has PhotonMCP's executeTool method
+            if (typeof mcp.instance.executeTool === 'function') {
+                // PhotonMCP base class handles execution
+                const outputHandler = options?.outputHandler || this.createOutputHandler();
+                const inputProvider = options?.inputProvider || this.createInputProvider();
+                const result = await mcp.instance.executeTool(toolName, parameters, { outputHandler });
+                // Handle generator result (if tool returns a generator)
+                if (isAsyncGenerator(result)) {
+                    const finalResult = await executeGenerator(result, {
+                        inputProvider,
+                        outputHandler,
+                    });
+                    // Clear any lingering progress
+                    this.progressRenderer.done();
+                    return finalResult;
+                }
+                // Clear any lingering progress
+                this.progressRenderer.done();
+                return result;
+            }
+            // Plain class - call method directly with implicit stateful support
+            // Check instance first, then prototype, then static methods on class
+            let method = mcp.instance[toolName];
+            let isStatic = false;
+            if (typeof method !== 'function') {
+                method = Object.getPrototypeOf(mcp.instance)?.[toolName];
+            }
+            // Check for static method on class constructor
+            if (typeof method !== 'function' && mcp.classConstructor) {
+                method = mcp.classConstructor[toolName];
+                isStatic = true;
+            }
+            if (!method || typeof method !== 'function') {
+                throw new Error(`Tool not found: ${toolName}`);
+            }
+            // Create a generator factory for maybeStatefulExecute
+            // This allows re-execution on resume
+            // For static methods, call on the class itself; for instance methods, bind to instance
+            const generatorFn = isStatic
+                ? () => method.call(null, parameters)
+                : () => method.call(mcp.instance, parameters);
+            // Use maybeStatefulExecute for all executions
+            // It handles both regular async and generators, detecting checkpoint yields
+            const execResult = await maybeStatefulExecute(generatorFn, {
+                photon: mcp.name,
+                tool: toolName,
+                params: parameters,
+                inputProvider: options?.inputProvider || this.createInputProvider(),
+                outputHandler: options?.outputHandler || this.createOutputHandler(),
+                resumeRunId: options?.resumeRunId,
+            });
+            // Clear any lingering progress
+            this.progressRenderer.done();
+            // If there was an error, throw it
+            if (execResult.error) {
+                const error = new Error(execResult.error);
+                if (execResult.runId) {
+                    error.runId = execResult.runId;
+                }
+                throw error;
+            }
+            // For stateful workflows, wrap result with metadata
+            if (execResult.isStateful && execResult.runId) {
+                return {
+                    _stateful: true,
+                    runId: execResult.runId,
+                    resumed: execResult.resumed,
+                    resumedFromStep: execResult.resumedFromStep,
+                    checkpointsCompleted: execResult.checkpointsCompleted,
+                    status: execResult.status,
+                    result: execResult.result,
+                };
+            }
+            // For ephemeral execution, return result directly
+            return execResult.result;
         }
-        // Ports
-        if (lowerName.includes('port')) {
-            return '5432';
+        catch (error) {
+            // Clear progress on error too
+            this.progressRenderer.done();
+            this.logger.error(`Tool execution failed: ${toolName} - ${getErrorMessage(error)}`);
+            throw error;
         }
-        // Database
-        if (lowerName.includes('database') || lowerName.includes('db')) {
-            return 'my_database';
+    }
+    /**
+     * Create an input provider for generator ask yields
+     * Supports the new ask/emit pattern from photon-core 1.2.0
+     */
+    createInputProvider() {
+        return async (ask) => {
+            switch (ask.ask) {
+                case 'text':
+                case 'password':
+                    return await elicitPrompt(ask.message, 'default' in ask ? ask.default : undefined);
+                case 'confirm':
+                    return await elicitConfirm(ask.message);
+                case 'select': {
+                    const options = (ask.options || []).map((o) => typeof o === 'string' ? o : o.label);
+                    const result = await elicitPrompt(`${ask.message}\nOptions: ${options.join(', ')}`);
+                    return result;
+                }
+                case 'number': {
+                    const result = await elicitPrompt(ask.message, ask.default?.toString());
+                    return result ? parseFloat(result) : (ask.default ?? 0);
+                }
+                case 'date': {
+                    const result = await elicitPrompt(ask.message, ask.default);
+                    return result || ask.default || new Date().toISOString();
+                }
+                case 'file':
+                    // File selection not supported in CLI readline
+                    this.logger.warn(`⚠️ File selection not supported in CLI: ${ask.message}`);
+                    return null;
+                default: {
+                    const unknownAsk = ask;
+                    this.logger.warn(`⚠️ Unknown ask type: ${unknownAsk.ask || 'unknown'}`);
+                    return undefined;
+                }
+            }
+        };
+    }
+    /**
+     * Create an output handler for generator emit yields
+     * Supports the new ask/emit pattern from photon-core 1.2.0
+     * Uses inline progress animation for CLI
+     */
+    createOutputHandler() {
+        return (emit) => {
+            switch (emit.emit) {
+                case 'progress':
+                    // Use inline progress bar with spinner animation
+                    this.progressRenderer.render(emit.value, emit.message);
+                    // Clear progress line when complete
+                    if (emit.value >= 1) {
+                        this.progressRenderer.done();
+                    }
+                    break;
+                case 'status':
+                    // Status shows as ephemeral spinner with auto-animation
+                    // Updates the message if already spinning, or starts a new spinner
+                    if (this.progressRenderer.active) {
+                        this.progressRenderer.updateMessage(emit.message);
+                    }
+                    else {
+                        this.progressRenderer.startSpinner(emit.message);
+                    }
+                    break;
+                case 'log': {
+                    // Logs clear progress first to avoid overlap
+                    this.progressRenderer.done();
+                    const level = (emit.level || 'info');
+                    const prefix = level === 'error' ? '❌' : level === 'warn' ? '⚠️' : 'ℹ';
+                    this.logger[level](`${prefix} ${emit.message}`);
+                    break;
+                }
+                case 'toast':
+                    this.progressRenderer.done();
+                    const icon = emit.type === 'error'
+                        ? '❌'
+                        : emit.type === 'warning'
+                            ? '⚠️'
+                            : emit.type === 'success'
+                                ? '✅'
+                                : 'ℹ';
+                    this.logger.info(`${icon} ${emit.message}`);
+                    break;
+                case 'thinking':
+                    if (emit.active) {
+                        // Show thinking as indeterminate progress
+                        this.progressRenderer.render(0, 'Processing...');
+                    }
+                    else {
+                        this.progressRenderer.done();
+                    }
+                    break;
+                case 'stream':
+                    // Stream clears progress first
+                    this.progressRenderer.done();
+                    if (typeof emit.data === 'string') {
+                        process.stdout.write(emit.data);
+                    }
+                    else {
+                        process.stdout.write(JSON.stringify(emit.data));
+                    }
+                    break;
+                case 'artifact':
+                    this.progressRenderer.done();
+                    this.logger.info(`📦 ${emit.title || emit.type}: ${emit.mimeType}`);
+                    break;
+            }
+        };
+    }
+    /**
+     * Extract @mcp dependencies from source and inject them as instance properties
+     *
+     * This enables the pattern:
+     * ```typescript
+     * /**
+     *  * @mcp github anthropics/mcp-server-github
+     *  *\/
+     * export default class MyPhoton extends PhotonMCP {
+     *   async doSomething() {
+     *     const issues = await this.github.list_issues({ repo: 'owner/repo' });
+     *   }
+     * }
+     * ```
+     */
+    async injectMCPDependencies(instance, source, photonName) {
+        const extractor = new SchemaExtractor();
+        const mcpDeps = extractor.extractMCPDependencies(source);
+        if (mcpDeps.length === 0) {
+            return;
         }
-        if (lowerName.includes('user') || lowerName.includes('username')) {
-            return 'admin';
+        this.log(`🔌 Found ${mcpDeps.length} @mcp dependencies`);
+        // Build MCP config from declarations
+        const mcpServers = {};
+        for (const dep of mcpDeps) {
+            try {
+                const config = resolveMCPSource(dep.name, dep.source, dep.sourceType);
+                mcpServers[dep.name] = config;
+                this.log(`  - ${dep.name}: ${dep.source} (${dep.sourceType})`);
+            }
+            catch (error) {
+                this.logger.warn(`⚠️  Failed to resolve MCP ${dep.name}: ${getErrorMessage(error)}`);
+            }
         }
-        if (lowerName.includes('password')) {
-            return 'your_secure_password';
+        if (Object.keys(mcpServers).length === 0) {
+            return;
         }
-        // Paths
-        if (lowerName.includes('path') || lowerName.includes('dir')) {
-            return '/path/to/directory';
+        // Create factory for these MCPs
+        const mcpConfig = { mcpServers };
+        const factory = new SDKMCPClientFactory(mcpConfig, this.verbose);
+        // Inject each MCP as an instance property with proxy
+        for (const dep of mcpDeps) {
+            if (mcpServers[dep.name]) {
+                const client = factory.create(dep.name);
+                const proxy = createMCPProxy(client);
+                // Inject as instance property: this.github, this.fs, etc.
+                Object.defineProperty(instance, dep.name, {
+                    value: proxy,
+                    writable: false,
+                    enumerable: true,
+                    configurable: false,
+                });
+                this.log(`  ✅ Injected this.${dep.name}`);
+            }
         }
-        // Common names
-        if (lowerName.includes('name')) {
-            return 'my-service';
+        // Store factory reference for cleanup
+        instance._mcpClientFactory = factory;
+    }
+    /**
+     * Check CLI dependencies declared via @cli tags
+     *
+     * Validates that required command-line tools are available on the system.
+     * Throws a helpful error with install URLs if any are missing.
+     *
+     * Format: @cli <name> - <install_url>
+     *
+     * Example:
+     * ```typescript
+     * /**
+     *  * @cli git - https://git-scm.com/downloads
+     *  * @cli ffmpeg - https://ffmpeg.org/download.html
+     *  *\/
+     * ```
+     */
+    async checkCLIDependencies(source, photonName) {
+        const extractor = new SchemaExtractor();
+        const cliDeps = extractor.extractCLIDependencies(source);
+        if (cliDeps.length === 0) {
+            return;
         }
-        if (lowerName.includes('region')) {
-            return 'us-east-1';
+        this.log(`🔧 Checking ${cliDeps.length} CLI dependencies`);
+        const missing = [];
+        for (const dep of cliDeps) {
+            const exists = await this.checkCLIExists(dep.name);
+            if (exists) {
+                this.log(`  ✅ ${dep.name}`);
+            }
+            else {
+                this.log(`  ❌ ${dep.name} not found`);
+                missing.push(dep);
+            }
         }
-        // Type-based defaults
-        if (paramType === 'boolean') {
-            return 'true';
+        if (missing.length > 0) {
+            const lines = missing.map((dep) => {
+                if (dep.installUrl) {
+                    return `  - ${dep.name}: Install from ${dep.installUrl}`;
+                }
+                return `  - ${dep.name}`;
+            });
+            const error = new Error(`${photonName} requires the following CLI tools to be installed:\n${lines.join('\n')}`);
+            error.name = 'CLIDependencyError';
+            throw error;
         }
-        if (paramType === 'number') {
-            return '3000';
+    }
+    /**
+     * Check if a CLI command exists on the system
+     */
+    async checkCLIExists(command) {
+        return new Promise((resolve) => {
+            const check = spawn(process.platform === 'win32' ? 'where' : 'which', [command], {
+                stdio: 'ignore',
+            });
+            check.on('close', (code) => resolve(code === 0));
+            check.on('error', () => resolve(false));
+        });
+    }
+    /**
+     * Discover and extract assets from a Photon file
+     * Uses shared discoverAssets from photon-core for core logic,
+     * then applies photon-specific extensions (method UI links, URI generation).
+     */
+    async discoverAssets(photonPath, source) {
+        const basename = path.basename(photonPath, '.photon.ts');
+        // Use shared discovery from photon-core
+        const assets = await sharedDiscoverAssets(photonPath, source);
+        if (!assets) {
+            return undefined;
         }
-        return null;
+        // Apply method-level @ui links AFTER auto-discovery
+        this.applyMethodUILinks(source, assets);
+        // Generate ui:// URIs for MCP Apps Extension support (SEP-1865)
+        this.generateAssetURIs(basename, assets);
+        return assets;
     }
     /**
-     * Generate user-friendly configuration error message
+     * Generate ui:// URIs for all UI assets (MCP Apps Extension support)
+     * URI format: ui://<photon-name>/<asset-id>
      */
-    generateConfigErrorMessage(mcpName, missing) {
-        const envVarList = missing.map(m => `  • ${m.envVarName} (${m.paramName}: ${m.type})`).join('\n');
-        const exampleEnv = Object.fromEntries(missing.map(m => [m.envVarName, `<your-${m.paramName}>`]));
-        return `
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⚠️  Configuration Warning: ${mcpName} MCP
-
-Missing required environment variables:
-${envVarList}
-
-Tools will fail until configuration is fixed.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-To fix, add environment variables to your MCP client config:
-
-{
-  "mcpServers": {
-    "${mcpName}": {
-      "command": "npx",
-      "args": ["@portel/photon", "${mcpName}"],
-      "env": ${JSON.stringify(exampleEnv, null, 8).replace(/\n/g, '\n      ')}
+    generateAssetURIs(photonName, assets) {
+        for (const ui of assets.ui) {
+            // Add uri field for MCP Apps compatibility
+            ui.uri = `ui://${photonName}/${ui.id}`;
+            this.log(`  🔗 URI: ${ui.uri}`);
+        }
     }
-  }
-}
-
-Or run: photon ${mcpName} --config
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-`.trim();
+    /**
+     * Apply method-level @ui annotations to link UI assets to tools
+     * Called after auto-discovery so all UI assets are available
+     */
+    applyMethodUILinks(source, assets) {
+        // Match method JSDoc with @ui annotation: /** ... @ui <id> ... */ async methodName
+        const methodUiRegex = /\/\*\*[\s\S]*?@ui\s+(\w[\w-]*)[\s\S]*?\*\/\s*(?:async\s+)?\*?\s*(\w+)/g;
+        let match;
+        while ((match = methodUiRegex.exec(source)) !== null) {
+            const [, uiId, methodName] = match;
+            const asset = assets.ui.find((u) => u.id === uiId);
+            if (asset && !asset.linkedTool) {
+                asset.linkedTool = methodName;
+                this.log(`  🔗 UI ${uiId} → ${methodName}`);
+            }
+        }
     }
+    // autoDiscoverAssets is now handled by sharedDiscoverAssets from photon-core
     /**
-     * Execute a tool on the loaded MCP instance
+     * Check if a file exists
      */
-    async executeTool(mcp, toolName, parameters) {
+    async fileExists(filePath) {
         try {
-            // Check for configuration errors before executing tool
-            if (mcp.instance._photonConfigError) {
-                throw new Error(mcp.instance._photonConfigError);
-            }
-            // Check if instance has PhotonMCP's executeTool method
-            if (typeof mcp.instance.executeTool === 'function') {
-                return await mcp.instance.executeTool(toolName, parameters);
-            }
-            else {
-                // Plain class - call method directly
-                const method = mcp.instance[toolName];
-                if (!method || typeof method !== 'function') {
-                    throw new Error(`Tool not found: ${toolName}`);
-                }
-                return await method.call(mcp.instance, parameters);
-            }
+            await fs.access(filePath);
+            return true;
         }
-        catch (error) {
-            console.error(`Tool execution failed: ${toolName} - ${error.message}`);
-            throw error;
+        catch {
+            return false; // file does not exist
         }
     }
+    /**
+     * Get MIME type from file extension
+     * Delegates to shared getMimeType from photon-core
+     */
+    getMimeType(filename) {
+        return sharedGetMimeType(filename);
+    }
 }
 //# sourceMappingURL=loader.js.map