@portel/photon 1.10.0 → 1.12.0

package/dist/loader.js

@@ -451,6 +451,11 @@ export class PhotonLoader {
             if (tsContent) {
                 await this.injectMCPDependencies(instance, tsContent, name);
             }
+            // Auto-wrap public methods in @stateful classes to emit events
+            // All method calls automatically produce events with params, result, timestamp
+            if (tsContent) {
+                this.wrapStatefulMethods(instance, tsContent);
+            }
             // Inject MCP client factory if available (enables this.mcp() calls)
             const setMCPFactory = instance.setMCPFactory;
             if (this.mcpClientFactory && typeof setMCPFactory === 'function') {
@@ -796,6 +801,28 @@ export class PhotonLoader {
         });
         return methods;
     }
+    /**
+     * Strip JSDoc tags from descriptions (e.g., @emits, @internal, @deprecated)
+     */
+    stripJSDocTags(description) {
+        if (!description)
+            return '';
+        if (description.includes('@emits') && process.env.PHOTON_DEBUG_EXTRACT) {
+            console.log(`[stripJSDocTags] Input: "${description}"`);
+        }
+        // Remove lines that start with @ (full line removal)
+        let cleaned = description
+            .split('\n')
+            .filter((line) => !line.trim().startsWith('@'))
+            .join('\n')
+            .trim();
+        // Also remove inline @ tags (e.g., "text @emits ... " at end of line)
+        cleaned = cleaned.replace(/\s*@\w+.*$/gm, '').trim();
+        if (description.includes('@emits') && process.env.PHOTON_DEBUG_EXTRACT) {
+            console.log(`[stripJSDocTags] Output: "${cleaned}"`);
+        }
+        return cleaned;
+    }
     /**
      * Extract tools, templates, and statics from a class
      */
@@ -849,6 +876,13 @@ export class PhotonLoader {
                     }
                 }
                 this.log(`Loaded ${tools.length} tools, ${templates.length} templates, ${statics.length} statics from .schema.json override`);
+                // Clean JSDoc tags from descriptions
+                tools = tools.map((t) => ({ ...t, description: this.stripJSDocTags(t.description) }));
+                templates = templates.map((t) => ({
+                    ...t,
+                    description: this.stripJSDocTags(t.description),
+                }));
+                statics = statics.map((s) => ({ ...s, description: this.stripJSDocTags(s.description) }));
                 return { tools, templates, statics };
             }
             catch (jsonError) {
@@ -865,6 +899,27 @@ export class PhotonLoader {
                     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`);
+                    // Clean JSDoc tags from descriptions
+                    if (process.env.PHOTON_DEBUG_EXTRACT) {
+                        tools.forEach((t) => {
+                            if (t.description?.includes('@')) {
+                                console.log(`[EXTRACTOR] Before clean: ${t.name}: "${t.description}"`);
+                            }
+                        });
+                    }
+                    tools = tools.map((t) => ({ ...t, description: this.stripJSDocTags(t.description) }));
+                    templates = templates.map((t) => ({
+                        ...t,
+                        description: this.stripJSDocTags(t.description),
+                    }));
+                    statics = statics.map((s) => ({ ...s, description: this.stripJSDocTags(s.description) }));
+                    if (process.env.PHOTON_DEBUG_EXTRACT) {
+                        tools.forEach((t) => {
+                            if (t.name === 'clear') {
+                                console.log(`[EXTRACTOR] After clean: ${t.name}: "${t.description}"`);
+                            }
+                        });
+                    }
                     return { tools, templates, statics, settingsSchema: metadata.settingsSchema };
                 }
                 throw jsonError;
@@ -884,6 +939,10 @@ export class PhotonLoader {
                 });
             }
         }
+        // Clean JSDoc tags from all descriptions (final safety net)
+        tools = tools.map((t) => ({ ...t, description: this.stripJSDocTags(t.description) }));
+        templates = templates.map((t) => ({ ...t, description: this.stripJSDocTags(t.description) }));
+        statics = statics.map((s) => ({ ...s, description: this.stripJSDocTags(s.description) }));
         return { tools, templates, statics };
     }
     // ════════════════════════════════════════════════════════════════════════════
@@ -1762,6 +1821,99 @@ Run: photon mcp ${mcpName} --config
                 const result = await executeBase();
                 this.progressRenderer.done();
                 auditFinish(result);
+                // CRITICAL FIX: Emit @stateful events at executeTool level
+                // The method wrapper approach is bypassed by Photon.executeTool(),
+                // so we must emit events here where ALL tool executions are guaranteed to pass through
+                if (mcp.instance && typeof mcp.instance.emit === 'function') {
+                    try {
+                        // Check if this is a @stateful photon by looking for emit method and @stateful tag
+                        const photonName = mcp.name;
+                        const hasStatefulTag = mcp.tools.some((t) => t.name === toolName); // Assume @stateful if loaded
+                        // Attach __meta to result if it's an object and doesn't already have it
+                        if (result && typeof result === 'object' && !Array.isArray(result) && !result.__meta) {
+                            const timestamp = new Date().toISOString();
+                            Object.defineProperty(result, '__meta', {
+                                value: {
+                                    createdAt: timestamp,
+                                    createdBy: toolName,
+                                    modifiedAt: null,
+                                    modifiedBy: null,
+                                    modifications: [],
+                                },
+                                enumerable: false,
+                                writable: true,
+                                configurable: true,
+                            });
+                        }
+                        // Construct event data with full context for transmission
+                        // CRITICAL: emit() expects { channel, event, data } structure for daemon pub/sub routing
+                        const eventPayload = {
+                            method: toolName,
+                            params: parameters,
+                            result,
+                            timestamp: new Date().toISOString(),
+                        };
+                        // Add instance name if available
+                        if (mcp.instance.instanceName) {
+                            eventPayload.instance = mcp.instance.instanceName;
+                        }
+                        // Add index/pagination info if result is from items array
+                        if (result && typeof result === 'object' && Array.isArray(mcp.instance.items)) {
+                            const index = mcp.instance.items.findIndex((item) => item === result);
+                            if (index !== -1) {
+                                eventPayload.index = index;
+                                eventPayload.totalCount = mcp.instance.items.length;
+                                eventPayload.affectedRange = {
+                                    start: index,
+                                    end: index + 1,
+                                };
+                            }
+                        }
+                        // Wrap in daemon pub/sub format: { channel, event, data }
+                        const eventData = {
+                            channel: `${photonName}:${toolName}`, // For daemon pub/sub routing
+                            event: 'tool-executed',
+                            data: eventPayload,
+                        };
+                        // Send event through outputHandler for daemon pub/sub routing
+                        // This is the critical path that routes events to subscribers through the daemon
+                        if (options?.outputHandler) {
+                            try {
+                                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
+                                });
+                                if (process.env.PHOTON_DEBUG_EMIT === '1') {
+                                    console.error(`[EMIT-DEBUG] Event transmitted to outputHandler`);
+                                }
+                            }
+                            catch (e) {
+                                console.error(`[EMIT-ERROR] Failed to send event through outputHandler: ${e instanceof Error ? e.message : String(e)}`);
+                            }
+                        }
+                        else if (mcp.instance && typeof mcp.instance.emit === 'function') {
+                            // Fallback for cases where outputHandler isn't available
+                            // (this path won't route to daemon pub/sub, but at least calls emit)
+                            try {
+                                if (process.env.PHOTON_DEBUG_EMIT === '1') {
+                                    console.error(`[EMIT-DEBUG] No outputHandler, falling back to instance.emit`);
+                                }
+                                mcp.instance.emit(eventData);
+                            }
+                            catch (e) {
+                                console.error(`[EMIT-ERROR] Failed to emit: ${e instanceof Error ? e.message : String(e)}`);
+                            }
+                        }
+                    }
+                    catch (e) {
+                        // Log emit errors but don't break tool execution
+                        console.error(`[EMIT-ERROR] Failed to emit @stateful event: ${e instanceof Error ? e.message : String(e)}`);
+                        this.logger.debug(`Failed to emit @stateful event: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                }
                 return result;
             }
             // Plain class - call method directly with implicit stateful support
@@ -2016,6 +2168,131 @@ Run: photon mcp ${mcpName} --config
             }
         }
     }
+    /**
+     * Wrap all public methods in @stateful classes to automatically emit events
+     *
+     * Event structure: { method, params, result, timestamp, instance }
+     * Every public method call produces an event with the method name, input parameters,
+     * return value, and timestamp. This enables real-time UI sync and event-driven architectures.
+     */
+    wrapStatefulMethods(instance, source) {
+        // Check if this class has @stateful decorator
+        if (!/@stateful\b/i.test(source)) {
+            return; // Not a @stateful class
+        }
+        // Get the emit function if available
+        const emit = typeof instance.emit === 'function'
+            ? instance.emit.bind(instance)
+            : null;
+        if (!emit) {
+            return; // No emit function, can't wrap methods
+        }
+        // Get all public method names from the instance
+        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;
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+            return descriptor && typeof descriptor.value === 'function';
+        });
+        if (methodNames.length === 0) {
+            return; // No public methods to wrap
+        }
+        const photonName = instance._photonName || 'photon';
+        this.log(`📡 Wrapping ${methodNames.length} methods in @stateful ${photonName}`);
+        // Wrap each public method
+        for (const methodName of methodNames) {
+            const original = instance[methodName];
+            if (typeof original !== 'function')
+                continue;
+            instance[methodName] = function (...args) {
+                // Extract parameter names and map arguments to them
+                const paramNames = PhotonLoader.extractParamNames(original);
+                const params = Object.fromEntries(paramNames.map((name, i) => [name, args[i]]));
+                // 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 timestamp = new Date().toISOString();
+                    Object.defineProperty(result, '__meta', {
+                        value: {
+                            createdAt: timestamp,
+                            createdBy: methodName,
+                            modifiedAt: null,
+                            modifiedBy: null,
+                            modifications: [],
+                        },
+                        enumerable: false,
+                        writable: true,
+                        configurable: true,
+                    });
+                }
+                // Emit event with complete context
+                const eventData = {
+                    method: methodName,
+                    params,
+                    result,
+                    timestamp: new Date().toISOString(),
+                };
+                if (this.instanceName) {
+                    eventData.instance = this.instanceName;
+                }
+                // Detect array mutations for range-based pagination support (Phase 5)
+                // If result is an object from this.items, add index and array metadata
+                if (result && typeof result === 'object' && Array.isArray(this.items)) {
+                    const index = this.items.findIndex((item) => item === result);
+                    if (index !== -1) {
+                        eventData.index = index;
+                        eventData.totalCount = this.items.length;
+                        // Affected range: just this item
+                        eventData.affectedRange = {
+                            start: index,
+                            end: index + 1,
+                        };
+                    }
+                }
+                // NOTE: Don't emit here - the real emission happens at executeTool level
+                // (line 2362 via outputHandler). This method wrapper is only called during
+                // direct instantiation testing, not in actual MCP execution paths where executeTool
+                // is the proper routing point.
+                //
+                // If we emit here too, we get duplicate messages:
+                // 1. This wrapper emits directly: emit(eventData)
+                // 2. executeTool emits via outputHandler: outputHandler(eventData)
+                // Both route to daemon, causing double notifications.
+                return result;
+            };
+        }
+    }
+    /**
+     * Extract parameter names from a function by parsing its signature
+     *
+     * Examples:
+     * - (text, priority = 'medium') => ['text', 'priority']
+     * - (id) => ['id']
+     * - () => []
+     */
+    static extractParamNames(fn) {
+        const fnStr = fn.toString();
+        // Match parameters inside parentheses: ( ... )
+        const match = fnStr.match(/\(([^)]*)\)/);
+        if (!match?.[1]) {
+            return [];
+        }
+        return match[1]
+            .split(',')
+            .map((param) => {
+            const cleaned = param
+                .trim()
+                .split('=')[0] // Remove default value
+                .split(':')[0] // Remove type annotations
+                .trim();
+            return cleaned;
+        })
+            .filter((name) => name && name !== 'this');
+    }
     /**
      * Extract @mcp dependencies from source and inject them as instance properties
      *