@portel/photon 1.18.0 → 1.20.0

package/dist/loader.js

@@ -36,7 +36,7 @@ executionContext,
 // Lock helper
 withLock as withLockHelper, 
 // Middleware system
-builtinRegistry, MiddlewareRegistry, buildMiddlewareChain, } from '@portel/photon-core';
+builtinRegistry, MiddlewareRegistry, buildMiddlewareChain, detectNamespace, getCacheDir, } from '@portel/photon-core';
 import { getDefaultContext } from './context.js';
 import * as os from 'os';
 import { MarketplaceManager } from './marketplace-manager.js';
@@ -332,7 +332,7 @@ export class PhotonLoader {
      * Directory where MCP-specific dependencies are cached
      */
     getDependencyCacheDir(cacheKey) {
-        return path.join(os.homedir(), '.cache', 'photon-mcp', 'dependencies', cacheKey);
+        return path.join(getCacheDir(), 'dependencies', cacheKey);
     }
     getBuildCacheDir(cacheKey) {
         return path.join(this.getDependencyCacheDir(cacheKey), '.build');
@@ -402,7 +402,11 @@ export class PhotonLoader {
             ? this.dependenciesEqual(metadata.dependencies, dependencies)
             : false;
         const resolvedCoreVersion = getResolvedPhotonCoreVersion();
-        const coreVersionChanged = metadata?.photonCoreVersion !== resolvedCoreVersion;
+        // Compare versions tolerantly: "2.17.6" matches "^2.17.6" and vice versa
+        // This prevents unnecessary cache clears when createRequire fallback returns a range
+        const storedVersion = metadata?.photonCoreVersion || '';
+        const coreVersionChanged = storedVersion !== resolvedCoreVersion &&
+            storedVersion.replace(/^[\^~]/, '') !== resolvedCoreVersion.replace(/^[\^~]/, '');
         // Only clear dependency cache when deps or core version actually changed.
         // Source-only changes just need a build cache clear (recompile is fast).
         const needsDepClear = Boolean(metadata && (!depsMatch || coreVersionChanged));
@@ -457,24 +461,39 @@ export class PhotonLoader {
         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'));
+            message.includes('Cannot find module') ||
+            message.includes('require is not defined'));
     }
     static parseDependenciesFromSource(source) {
         const deps = [];
+        // Only match @dependencies inside JSDoc blocks (/** ... */)
+        const jsdocBlocks = source.match(/\/\*\*[\s\S]*?\*\//g) || [];
+        const jsdocText = jsdocBlocks.join('\n');
         const regex = /@dependencies\s+([^\r\n]+)/g;
         let match;
-        while ((match = regex.exec(source)) !== null) {
+        while ((match = regex.exec(jsdocText)) !== null) {
             const entries = match[1]
+                .replace(/\*\/$/, '') // strip trailing */ if on same line
                 .split(',')
                 .map((entry) => entry.trim())
                 .filter(Boolean);
             for (const entry of entries) {
                 const atIndex = entry.lastIndexOf('@');
+                let name;
+                let version;
                 if (atIndex <= 0) {
+                    // No version specified (e.g., "sharp") — default to latest
+                    name = entry.trim();
+                    version = '*';
+                }
+                else {
+                    name = entry.slice(0, atIndex).trim();
+                    version = entry.slice(atIndex + 1).trim();
+                }
+                // Validate: npm package names are lowercase, may have @scope/, no spaces
+                if (name.includes(' ') || !/^(@[a-z0-9-]+\/)?[a-z0-9._-]+$/.test(name)) {
                     continue;
                 }
-                const name = entry.slice(0, atIndex).trim();
-                let version = entry.slice(atIndex + 1).trim();
                 // Trailing ? marks the dependency as optional (e.g. sharp@^0.33.0?)
                 const optional = version.endsWith('?');
                 if (optional) {
@@ -609,8 +628,9 @@ export class PhotonLoader {
                 this.logger.warn(`⚠️  ${name} loaded with configuration warnings:`);
                 this.logger.warn(String(configError));
             }
-            // Set photon name for event source identification
+            // Set photon name and namespace for event source identification and data paths
             instance._photonName = name;
+            instance._photonNamespace = this.resolveNamespace(absolutePath);
             // Inject instance name for named instances (runtime concept, not code)
             instance.instanceName = options?.instanceName ?? '';
             // Inject file path for storage()/assets() resolution
@@ -686,9 +706,17 @@ export class PhotonLoader {
                                     timestamp: Date.now(),
                                     source: name,
                                 })
-                                    .catch(() => { }); // Best-effort
+                                    .catch((e) => {
+                                    this.logger.debug('Failed to publish broker event', {
+                                        error: e?.message || e,
+                                    });
+                                });
                             })
-                                .catch(() => { });
+                                .catch((e) => {
+                                this.logger.debug('Failed to import photon-core for broker', {
+                                    error: e?.message || e,
+                                });
+                            });
                         }
                     };
                     // Also inject render() — convenience wrapper around emit
@@ -702,11 +730,12 @@ export class PhotonLoader {
                     };
                 }
                 if (caps.has('memory')) {
-                    // Inject lazy memory provider
+                    // Inject lazy memory provider — capture baseDir from loader context
+                    const memoryBaseDir = this.baseDir;
                     Object.defineProperty(instance, 'memory', {
                         get() {
                             if (!this._memory) {
-                                this._memory = new MemoryProvider(name, this._sessionId);
+                                this._memory = new MemoryProvider(name, this._sessionId, this._photonNamespace, memoryBaseDir);
                             }
                             return this._memory;
                         },
@@ -904,6 +933,42 @@ export class PhotonLoader {
                 }
                 this.log(`🔌 Injected channel event infrastructure into ${name}`);
             }
+            // Inject this.channel() for channel notifications — works for both Photon
+            // subclasses and plain classes. Emits on '{photonName}:channel-push' daemon
+            // channel which the MCP server intercepts and translates to the client's
+            // notification method (e.g. notifications/claude/channel).
+            //
+            // this.channel(content, meta) — send a message to the client
+            // this.channel.respond(id, behavior) — respond to permission requests
+            // this.channel.onPermission(handler) — register permission request handler
+            if (typeof instance.emit === 'function') {
+                const emitFn = instance.emit.bind(instance);
+                // Permission handler stored locally — wired by server after load
+                let permissionHandler;
+                const channelFn = Object.assign((content, meta) => {
+                    emitFn({
+                        channel: `${name}:channel-push`,
+                        event: 'channel',
+                        data: { content, meta },
+                    });
+                }, {
+                    respond: (requestId, behavior) => {
+                        emitFn({
+                            channel: `${name}:channel-permission-response`,
+                            event: 'permission-response',
+                            data: { request_id: requestId, behavior },
+                        });
+                    },
+                    onPermission: (handler) => {
+                        permissionHandler = handler;
+                    },
+                    // Internal: called by the server when a permission request arrives
+                    _dispatchPermission: (request) => {
+                        permissionHandler?.(request);
+                    },
+                });
+                instance.channel = channelFn;
+            }
             // Check @cli dependencies (required system CLI tools)
             if (tsContent) {
                 await this.checkCLIDependencies(tsContent, name);
@@ -1037,6 +1102,7 @@ export class PhotonLoader {
             instance._photonConfigError = configError;
         }
         instance._photonName = name;
+        instance._photonNamespace = this.resolveNamespace(absolutePath);
         instance.instanceName = options?.instanceName ?? '';
         // Inject file path for storage()/assets() resolution.
         // For preloaded modules (compiled binaries), remap to ~/.photon/ so storage()
@@ -1100,9 +1166,15 @@ export class PhotonLoader {
                                 timestamp: Date.now(),
                                 source: name,
                             })
-                                .catch(() => { });
+                                .catch((e) => {
+                                this.logger.debug('Failed to publish broker event', { error: e?.message || e });
+                            });
                         })
-                            .catch(() => { });
+                            .catch((e) => {
+                            this.logger.debug('Failed to import photon-core for broker', {
+                                error: e?.message || e,
+                            });
+                        });
                     }
                 };
                 // Also inject render() — convenience wrapper around emit
@@ -1116,10 +1188,11 @@ export class PhotonLoader {
                 };
             }
             if (caps.has('memory')) {
+                const memoryBaseDir = this.baseDir;
                 Object.defineProperty(instance, 'memory', {
                     get() {
                         if (!this._memory) {
-                            this._memory = new MemoryProvider(name, this._sessionId);
+                            this._memory = new MemoryProvider(name, this._sessionId, this._photonNamespace, memoryBaseDir);
                         }
                         return this._memory;
                     },
@@ -1945,7 +2018,7 @@ export class PhotonLoader {
             }
             // 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` +
+                `Check your config.json configuration and ensure:\n` +
                 `  • The command/URL is correct\n` +
                 `  • Required environment variables are set\n` +
                 `  • The MCP server is accessible`);
@@ -1984,6 +2057,7 @@ export class PhotonLoader {
         }
         // Resolve the Photon path
         const resolvedPath = await this.resolvePhotonPath(dep, currentPhotonPath);
+        await this.materializeSiblingDependencySymlink(dep, currentPhotonPath, resolvedPath);
         // Cache key includes instance name to allow multiple instances of the same photon
         const cacheKey = dep.instanceName ? `${resolvedPath}::${dep.instanceName}` : resolvedPath;
         // Check cache
@@ -2047,14 +2121,15 @@ export class PhotonLoader {
      * Resolve Photon dependency path based on source type
      */
     async resolvePhotonPath(dep, currentPhotonPath) {
+        const resolvedCurrentPhotonPath = await this.resolveRealPhotonPath(currentPhotonPath);
         switch (dep.sourceType) {
             case 'local':
                 if (dep.source.startsWith('./') || dep.source.startsWith('../')) {
-                    return path.resolve(path.dirname(currentPhotonPath), dep.source);
+                    return path.resolve(path.dirname(resolvedCurrentPhotonPath), dep.source);
                 }
                 return dep.source;
             case 'marketplace':
-                return await this.resolveMarketplacePhoton(dep, currentPhotonPath);
+                return await this.resolveMarketplacePhoton(dep, resolvedCurrentPhotonPath);
             case 'github':
                 return await this.fetchGithubPhoton(dep);
             case 'npm':
@@ -2136,6 +2211,48 @@ export class PhotonLoader {
         throw new Error(`Photon "${dep.source}" not found in local paths or configured marketplaces. ` +
             `Checked: ${candidates.join(', ')}`);
     }
+    async resolveRealPhotonPath(currentPhotonPath) {
+        try {
+            return await fs.realpath(currentPhotonPath);
+        }
+        catch {
+            return currentPhotonPath;
+        }
+    }
+    async materializeSiblingDependencySymlink(dep, currentPhotonPath, resolvedPath) {
+        if (dep.sourceType !== 'marketplace')
+            return;
+        if (dep.source.includes(':'))
+            return;
+        if (dep.source.includes('/'))
+            return;
+        const realCurrentPhotonPath = await this.resolveRealPhotonPath(currentPhotonPath);
+        if (realCurrentPhotonPath === currentPhotonPath)
+            return;
+        if (path.dirname(realCurrentPhotonPath) !== path.dirname(resolvedPath))
+            return;
+        const linkPath = path.join(this.baseDir, path.basename(resolvedPath));
+        await this.createSymlinkIfMissing(resolvedPath, linkPath);
+        const depName = path.basename(resolvedPath).replace(/\.photon\.(ts|js)$/, '');
+        const sourceAssetDir = path.join(path.dirname(resolvedPath), depName);
+        const targetAssetDir = path.join(this.baseDir, depName);
+        if (existsSync(sourceAssetDir)) {
+            await this.createSymlinkIfMissing(sourceAssetDir, targetAssetDir, 'dir');
+        }
+    }
+    async createSymlinkIfMissing(sourcePath, targetPath, type) {
+        try {
+            const existing = await fs.lstat(targetPath).catch(() => null);
+            if (existing)
+                return;
+            await fs.mkdir(path.dirname(targetPath), { recursive: true });
+            symlinkSync(sourcePath, targetPath, type);
+            this.log(`🔗 Materialized sibling photon symlink: ${path.basename(targetPath)}`);
+        }
+        catch (error) {
+            this.log(`⚠️ Failed to materialize sibling symlink ${path.basename(targetPath)}: ${getErrorMessage(error)}`);
+        }
+    }
     normalizeMarketplaceSource(source) {
         let slugSource = source;
         let marketplaceHint;
@@ -2642,9 +2759,9 @@ Run: photon mcp ${mcpName} --config
                                 if (process.env.PHOTON_DEBUG_EMIT === '1') {
                                     console.error(`[EMIT-DEBUG] Sending event: method=${eventPayload.method}, channel=${eventData.channel}, hasMeta=${!!result?.__meta}`);
                                 }
-                                // Cast to any - outputHandler is flexible and routes any object with channel property
-                                void Promise.resolve(options.outputHandler(eventData)).catch(() => {
-                                    // Ignore output handler errors - don't break tool execution
+                                // Cast to DaemonEventEnvelope - outputHandler is flexible and routes any object with channel property
+                                void Promise.resolve(options.outputHandler(eventData)).catch((e) => {
+                                    this.logger.debug('Output handler failed for event', { error: e?.message || e });
                                 });
                                 if (process.env.PHOTON_DEBUG_EMIT === '1') {
                                     console.error(`[EMIT-DEBUG] Event transmitted to outputHandler`);
@@ -2990,12 +3107,19 @@ Run: photon mcp ${mcpName} --config
             return; // No emit function, can't wrap methods
         }
         // Get all public method names from the instance
+        // Skip runtime-injected methods (emit, render, push, ask) — these are
+        // capability methods injected by the loader, not user-defined tools
+        const RUNTIME_METHODS = new Set(['emit', 'render', 'channel', 'ask', 'call']);
         const proto = Object.getPrototypeOf(instance);
         const methodNames = Object.getOwnPropertyNames(proto).filter((name) => {
             // Skip constructor and private/protected methods
             if (name === 'constructor' || name.startsWith('_')) {
                 return false;
             }
+            // Skip runtime-injected capability methods
+            if (RUNTIME_METHODS.has(name)) {
+                return false;
+            }
             const descriptor = Object.getOwnPropertyDescriptor(proto, name);
             return descriptor && typeof descriptor.value === 'function';
         });
@@ -3016,7 +3140,11 @@ Run: photon mcp ${mcpName} --config
                 // Call the original method
                 const result = original.apply(this, args);
                 // Attach __meta to returned objects for audit trail
-                if (result && typeof result === 'object' && !Array.isArray(result) && !result.__meta) {
+                const resultObj = result;
+                if (resultObj &&
+                    typeof resultObj === 'object' &&
+                    !Array.isArray(resultObj) &&
+                    !resultObj.__meta) {
                     const timestamp = new Date().toISOString();
                     Object.defineProperty(result, '__meta', {
                         value: {
@@ -3211,6 +3339,25 @@ Run: photon mcp ${mcpName} --config
             check.on('error', () => resolve(false));
         });
     }
+    /**
+     * Resolve the namespace for a photon based on its file path.
+     * Extracts the directory name between baseDir and the photon file.
+     *
+     * Examples:
+     *   ~/.photon/portel-dev/todo.photon.ts → 'portel-dev'
+     *   ~/.photon/acme/todo.photon.ts       → 'acme'
+     *   ~/.photon/todo.photon.ts            → detected from git or 'local'
+     */
+    resolveNamespace(absolutePath) {
+        const rel = path.relative(this.baseDir, absolutePath);
+        const parts = rel.split(path.sep);
+        // If file is in a subdirectory (namespace/photon.ts), use that as namespace
+        if (parts.length >= 2) {
+            return parts[0];
+        }
+        // Flat file at root — detect from git remote or default to 'local'
+        return detectNamespace(this.baseDir);
+    }
     /**
      * Discover and extract assets from a Photon file
      * Uses shared discoverAssets from photon-core for core logic,