@portel/photon 1.6.1 → 1.8.0

package/dist/auto-ui/beam.js

@@ -14,6 +14,7 @@ import * as os from 'os';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
+import { isPathWithin, isLocalRequest, setSecurityHeaders, readBody, SimpleRateLimiter, } from '../shared/security.js';
 /**
  * Generate a unique ID for a photon based on its path.
  * This ensures photons with the same name from different paths are distinguishable.
@@ -28,15 +29,17 @@ const __dirname = path.dirname(__filename);
 import { listPhotonMCPs, resolvePhotonPath } from '../path-resolver.js';
 import { PhotonLoader } from '../loader.js';
 import { logger, createLogger } from '../shared/logger.js';
+import { getErrorMessage } from '../shared/error-handler.js';
 import { toEnvVarName } from '../shared/config-docs.js';
 import { MarketplaceManager } from '../marketplace-manager.js';
 import { PhotonDocExtractor } from '../photon-doc-extractor.js';
 import { TemplateManager } from '../template-manager.js';
 import { subscribeChannel, pingDaemon } from '../daemon/client.js';
+import { ensureDaemon } from '../daemon/manager.js';
 import { SchemaExtractor, } from '@portel/photon-core';
 import { generateOpenAPISpec } from './openapi-generator.js';
 import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, sendToSession, requestExternalElicitation, } from './streamable-http-transport.js';
-import { SDKMCPClientFactory } from '../mcp-client.js';
+import { SDKMCPClientFactory } from '@portel/photon-core';
 import { getBundledPhotonPath, BEAM_BUNDLED_PHOTONS } from '../shared-utils.js';
 // SDK imports for direct resource access (transport wrapper doesn't expose these yet)
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -45,7 +48,7 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 // Config file path
-const CONFIG_FILE = path.join(os.homedir(), '.photon', 'config.json');
+const CONFIG_FILE = process.env.PHOTON_CONFIG_FILE || path.join(os.homedir(), '.photon', 'config.json');
 // ════════════════════════════════════════════════════════════════════════════════
 // EXTERNAL MCP STATE (module-level for MCP transport access)
 // ════════════════════════════════════════════════════════════════════════════════
@@ -178,8 +181,7 @@ async function loadExternalMCPs(config) {
                 try {
                     const resourcesResult = await sdkClient.listResources();
                     const resources = resourcesResult.resources || [];
-                    const appResources = resources.filter((r) => r.uri?.startsWith('ui://') ||
-                        r.mimeType === 'application/vnd.mcp.ui+html');
+                    const appResources = resources.filter((r) => r.uri?.startsWith('ui://') || r.mimeType === 'application/vnd.mcp.ui+html');
                     // Count only non-UI resources (UI resources are internal implementation detail)
                     mcpInfo.resourceCount = resources.length - appResources.length;
                     if (appResources.length > 0) {
@@ -257,8 +259,7 @@ async function loadExternalMCPs(config) {
                         const resourcesResult = await sdkClient.listResources();
                         const resources = resourcesResult.resources || [];
                         // Check for MCP App resources (ui:// scheme or application/vnd.mcp.ui+html mime)
-                        const appResources = resources.filter((r) => r.uri?.startsWith('ui://') ||
-                            r.mimeType === 'application/vnd.mcp.ui+html');
+                        const appResources = resources.filter((r) => r.uri?.startsWith('ui://') || r.mimeType === 'application/vnd.mcp.ui+html');
                         // Count only non-UI resources (UI resources are internal implementation detail)
                         mcpInfo.resourceCount = resources.length - appResources.length;
                         if (appResources.length > 0) {
@@ -278,19 +279,10 @@ async function loadExternalMCPs(config) {
                     mcpInfo.methods = methods;
                 }
                 catch (sdkError) {
-                    // SDK client failed - fall back to wrapper client
-                    logger.debug(`SDK client failed for ${name}, using wrapper: ${sdkError}`);
-                    // Try wrapper client as fallback
-                    const tools = await client.list();
-                    methods = (tools || []).map((tool) => ({
-                        name: tool.name,
-                        description: tool.description || '',
-                        params: tool.inputSchema || { type: 'object', properties: {} },
-                        returns: { type: 'object' },
-                        icon: tool['x-icon'],
-                    }));
-                    mcpInfo.connected = true;
-                    mcpInfo.methods = methods;
+                    // SDK client failed — don't fall back to wrapper for stdio MCPs
+                    // (same command would fail identically, and wrapper spawns a process
+                    // without stderr suppression, leaking raw Node.js stack traces)
+                    throw sdkError;
                 }
             }
             else {
@@ -319,7 +311,17 @@ async function loadExternalMCPs(config) {
         catch (error) {
             const errorMsg = error instanceof Error ? error.message : String(error);
             mcpInfo.errorMessage = errorMsg.slice(0, 200);
-            logger.warn(`⚠️ Failed to connect to external MCP: ${name} - ${errorMsg}`);
+            // User-friendly error messages for common failures
+            const shortMsg = errorMsg.includes('Cannot find module')
+                ? `Module not found (run npm build in the MCP directory)`
+                : errorMsg.includes('ENOENT')
+                    ? `Command not found: ${serverConfig.command}`
+                    : errorMsg.includes('Connection timeout')
+                        ? `Connection timed out (server may not be running)`
+                        : errorMsg.includes('Connection closed')
+                            ? `Server exited immediately (check configuration)`
+                            : errorMsg.slice(0, 120);
+            logger.warn(`⚠️  External MCP "${name}" — ${shortMsg}`);
         }
         results.push(mcpInfo);
     }
@@ -358,8 +360,7 @@ async function reconnectExternalMCP(name) {
             try {
                 const resourcesResult = await sdkClient.listResources();
                 const resources = resourcesResult.resources || [];
-                const appResources = resources.filter((r) => r.uri?.startsWith('ui://') ||
-                    r.mimeType === 'application/vnd.mcp.ui+html');
+                const appResources = resources.filter((r) => r.uri?.startsWith('ui://') || r.mimeType === 'application/vnd.mcp.ui+html');
                 // Count only non-UI resources (UI resources are internal implementation detail)
                 mcp.resourceCount = resources.length - appResources.length;
                 if (appResources.length > 0) {
@@ -671,8 +672,8 @@ export async function startBeam(rawWorkingDir, port) {
                     defaultValue: p.defaultValue,
                 }));
                 // Extract @ui template path from class-level JSDoc
-                const classJsdocMatch = source.match(/\/\*\*[\s\S]*?\*\/\s*(?=export\s+default\s+class)/)
-                    || source.match(/^\/\*\*([\s\S]*?)\*\//);
+                const classJsdocMatch = source.match(/\/\*\*[\s\S]*?\*\/\s*(?=export\s+default\s+class)/) ||
+                    source.match(/^\/\*\*([\s\S]*?)\*\//);
                 if (classJsdocMatch) {
                     const uiMatch = classJsdocMatch[0].match(/@ui\s+([^\s*]+)/);
                     if (uiMatch) {
@@ -745,7 +746,9 @@ export async function startBeam(rawWorkingDir, port) {
                     linkedUi: linkedAsset?.id,
                     ...(schema.isStatic ? { isStatic: true } : {}),
                     ...(schema.webhook ? { webhook: schema.webhook } : {}),
-                    ...(schema.scheduled || schema.cron ? { scheduled: schema.scheduled || schema.cron } : {}),
+                    ...(schema.scheduled || schema.cron
+                        ? { scheduled: schema.scheduled || schema.cron }
+                        : {}),
                     ...(schema.locked ? { locked: schema.locked } : {}),
                 };
             });
@@ -799,6 +802,7 @@ export async function startBeam(rawWorkingDir, port) {
             catch {
                 // No install metadata - that's fine
             }
+            const isStateful = schemaSource ? /@stateful\b/.test(schemaSource) : false;
             return {
                 id: generatePhotonId(photonPath),
                 name,
@@ -818,8 +822,10 @@ export async function startBeam(rawWorkingDir, port) {
                 resourceCount,
                 promptCount,
                 installSource,
+                ...(isStateful && { stateful: true }),
                 ...(constructorParams.length > 0 && { requiredParams: constructorParams }),
-                ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+                ...(mcp.injectedPhotons &&
+                    mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
             };
         }
         catch (error) {
@@ -839,57 +845,58 @@ export async function startBeam(rawWorkingDir, port) {
         }
     }
     const channelSubscriptions = new Map();
-    const EVENT_BUFFER_SIZE = 30; // Keep last 30 events per channel
+    /** Buffer retention window — events older than this are purged */
+    const EVENT_BUFFER_DURATION_MS = 5 * 60 * 1000; // 5 minutes
     const channelEventBuffers = new Map();
     // Store an event in the channel buffer
     function bufferEvent(channel, method, params) {
         let buffer = channelEventBuffers.get(channel);
         if (!buffer) {
-            buffer = { events: [], nextId: 1 };
+            buffer = { events: [] };
             channelEventBuffers.set(channel, buffer);
         }
-        const eventId = buffer.nextId++;
+        const now = Date.now();
         const event = {
-            id: eventId,
+            id: now,
             method,
             params,
-            timestamp: Date.now(),
+            timestamp: now,
         };
         buffer.events.push(event);
-        // Keep only last N events (circular buffer)
-        if (buffer.events.length > EVENT_BUFFER_SIZE) {
+        // Purge events older than retention window
+        const cutoff = now - EVENT_BUFFER_DURATION_MS;
+        while (buffer.events.length > 0 && buffer.events[0].timestamp < cutoff) {
             buffer.events.shift();
         }
-        return eventId;
+        return now;
     }
-    // Replay missed events to a specific session, or signal refresh needed
-    function replayEventsToSession(sessionId, channel, lastEventId) {
+    // Replay missed events to a specific session, or signal full sync needed
+    function replayEventsToSession(sessionId, channel, lastTimestamp) {
         const buffer = channelEventBuffers.get(channel);
         // No buffer = no events ever sent on this channel
         if (!buffer || buffer.events.length === 0) {
             return { replayed: 0, refreshNeeded: false };
         }
-        // No lastEventId = client is fresh, no replay needed
-        if (lastEventId === undefined) {
+        // No lastTimestamp = client is fresh, no replay needed
+        if (lastTimestamp === undefined) {
             return { replayed: 0, refreshNeeded: false };
         }
         const oldestEvent = buffer.events[0];
-        // If lastEventId is older than our oldest buffered event, signal refresh needed
-        if (lastEventId < oldestEvent.id) {
+        // Stale: client's timestamp is older than buffer window → full sync needed
+        if (lastTimestamp < oldestEvent.timestamp) {
             sendToSession(sessionId, 'photon/refresh-needed', { channel });
-            logger.info(`📡 Replay: ${channel} - lastEventId ${lastEventId} too old (oldest: ${oldestEvent.id}), refresh needed`);
+            logger.info(`📡 Stale client on ${channel} - last seen ${new Date(lastTimestamp).toISOString()}, oldest buffered ${new Date(oldestEvent.timestamp).toISOString()}, full sync needed`);
             return { replayed: 0, refreshNeeded: true };
         }
-        // Find events to replay (all events after lastEventId)
-        const eventsToReplay = buffer.events.filter((e) => e.id > lastEventId);
+        // Delta sync: replay events after client's last timestamp
+        const eventsToReplay = buffer.events.filter((e) => e.timestamp > lastTimestamp);
         if (eventsToReplay.length === 0) {
             return { replayed: 0, refreshNeeded: false };
         }
-        // Replay each missed event to this session
         for (const event of eventsToReplay) {
-            sendToSession(sessionId, event.method, { ...event.params, _eventId: event.id });
+            sendToSession(sessionId, event.method, { ...event.params, _eventId: event.timestamp });
         }
-        logger.info(`📡 Replay: ${channel} - replayed ${eventsToReplay.length} events (${lastEventId + 1} to ${buffer.nextId - 1})`);
+        logger.info(`📡 Delta sync: ${channel} - replayed ${eventsToReplay.length} events`);
         return { replayed: eventsToReplay.length, refreshNeeded: false };
     }
     // ══════════════════════════════════════════════════════════════════════════════
@@ -963,8 +970,8 @@ export async function startBeam(rawWorkingDir, port) {
     // Called when a client starts viewing a board (from MCP notification)
     // photonId: hash of photon path (unique across servers)
     // itemId: whatever the photon uses to identify the item (e.g., board name)
-    // lastEventId: optional - if provided, replay missed events or signal refresh needed
-    function onClientViewingBoard(sessionId, photonId, itemId, lastEventId) {
+    // lastTimestamp: optional - if provided, delta sync missed events or signal full sync needed
+    function onClientViewingBoard(sessionId, photonId, itemId, lastTimestamp) {
         const prevState = sessionViewState.get(sessionId);
         // Unsubscribe from previous item if different
         if (prevState?.itemId && (prevState.photonId !== photonId || prevState.itemId !== itemId)) {
@@ -975,9 +982,9 @@ export async function startBeam(rawWorkingDir, port) {
         const channel = `${photonId}:${itemId}`;
         sessionViewState.set(sessionId, { photonId, itemId });
         subscribeToChannel(channel);
-        // Replay missed events if lastEventId is provided
-        if (lastEventId !== undefined) {
-            replayEventsToSession(sessionId, channel, lastEventId);
+        // Delta sync missed events if lastTimestamp is provided
+        if (lastTimestamp !== undefined) {
+            replayEventsToSession(sessionId, channel, lastTimestamp);
         }
     }
     // Called when a client disconnects
@@ -1014,8 +1021,12 @@ export async function startBeam(rawWorkingDir, port) {
             return null; // UI asset not found
         }
     };
+    // Security: rate limiter for API endpoints
+    const apiRateLimiter = new SimpleRateLimiter(30, 60_000);
     // Create HTTP server
     const server = http.createServer(async (req, res) => {
+        // Security: set standard security headers on all responses
+        setSecurityHeaders(res);
         const url = new URL(req.url || '/', `http://${req.headers.host}`);
         // ══════════════════════════════════════════════════════════════════════════
         // MCP Streamable HTTP Transport (standard MCP clients like Claude Desktop)
@@ -1133,17 +1144,18 @@ export async function startBeam(rawWorkingDir, port) {
                     root = path.resolve(workdirEnv);
                 }
             }
-            const dirPath = url.searchParams.get('path') || root || workingDir;
+            // Security: default browse root to workingDir if not specified
+            if (!root) {
+                root = workingDir;
+            }
+            const dirPath = url.searchParams.get('path') || root;
             try {
                 const resolved = path.resolve(dirPath);
-                // Validate path is within root (if specified)
-                if (root) {
-                    const resolvedRoot = path.resolve(root);
-                    if (!resolved.startsWith(resolvedRoot)) {
-                        res.writeHead(403);
-                        res.end(JSON.stringify({ error: 'Access denied: outside allowed directory' }));
-                        return;
-                    }
+                // Security: always enforce path boundary using isPathWithin
+                if (!isPathWithin(resolved, root)) {
+                    res.writeHead(403);
+                    res.end(JSON.stringify({ error: 'Access denied: outside allowed directory' }));
+                    return;
                 }
                 const stat = await fs.stat(resolved);
                 if (!stat.isDirectory()) {
@@ -1187,6 +1199,12 @@ export async function startBeam(rawWorkingDir, port) {
                 return;
             }
             const resolved = path.resolve(filePath);
+            // Security: prevent path traversal — file must be within working directory
+            if (!isPathWithin(resolved, workingDir)) {
+                res.writeHead(403);
+                res.end('Access denied: outside allowed directory');
+                return;
+            }
             try {
                 const fileStat = await fs.stat(resolved);
                 if (!fileStat.isFile()) {
@@ -1367,9 +1385,19 @@ export async function startBeam(rawWorkingDir, port) {
             }
             // Resolve template path relative to photon's directory
             const photonDir = path.dirname(photon.path);
-            const fullTemplatePath = path.isAbsolute(templateFile)
-                ? templateFile
-                : path.join(photonDir, templateFile);
+            // Security: reject absolute template paths — must be relative to photon dir
+            if (path.isAbsolute(templateFile)) {
+                res.writeHead(403);
+                res.end(JSON.stringify({ error: 'Absolute template paths are not allowed' }));
+                return;
+            }
+            const fullTemplatePath = path.join(photonDir, templateFile);
+            // Security: validate resolved path is within photon directory
+            if (!isPathWithin(fullTemplatePath, photonDir)) {
+                res.writeHead(403);
+                res.end(JSON.stringify({ error: 'Template path traversal detected' }));
+                return;
+            }
             try {
                 const templateContent = await fs.readFile(fullTemplatePath, 'utf-8');
                 res.setHeader('Content-Type', 'text/html');
@@ -1608,38 +1636,49 @@ export async function startBeam(rawWorkingDir, port) {
         }
         // Invoke API: Direct HTTP endpoint for method invocation (used by PWA)
         if (url.pathname === '/api/invoke' && req.method === 'POST') {
-            let body = '';
-            req.on('data', (chunk) => (body += chunk));
-            req.on('end', async () => {
-                try {
-                    const { photon: photonName, method, args } = JSON.parse(body);
-                    if (!photonName || !method) {
-                        res.writeHead(400);
-                        res.end(JSON.stringify({ error: 'Missing photon or method' }));
-                        return;
-                    }
-                    const mcp = photonMCPs.get(photonName);
-                    if (!mcp || !mcp.instance) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Photon not found: ${photonName}` }));
-                        return;
-                    }
-                    if (typeof mcp.instance[method] !== 'function') {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Method not found: ${method}` }));
-                        return;
-                    }
-                    const result = await mcp.instance[method](args || {});
-                    res.setHeader('Content-Type', 'application/json');
-                    res.writeHead(200);
-                    res.end(JSON.stringify({ result }));
+            // Security: only allow local requests
+            if (!isLocalRequest(req)) {
+                res.writeHead(403);
+                res.end(JSON.stringify({ error: 'Forbidden: non-local request' }));
+                return;
+            }
+            // Security: rate limiting
+            const clientKey = req.socket?.remoteAddress || 'unknown';
+            if (!apiRateLimiter.isAllowed(clientKey)) {
+                res.writeHead(429);
+                res.end(JSON.stringify({ error: 'Too many requests' }));
+                return;
+            }
+            try {
+                const body = await readBody(req);
+                const { photon: photonName, method, args } = JSON.parse(body);
+                if (!photonName || !method) {
+                    res.writeHead(400);
+                    res.end(JSON.stringify({ error: 'Missing photon or method' }));
+                    return;
                 }
-                catch (err) {
-                    res.setHeader('Content-Type', 'application/json');
-                    res.writeHead(500);
-                    res.end(JSON.stringify({ error: err.message || String(err) }));
+                const mcp = photonMCPs.get(photonName);
+                if (!mcp || !mcp.instance) {
+                    res.writeHead(404);
+                    res.end(JSON.stringify({ error: `Photon not found: ${photonName}` }));
+                    return;
                 }
-            });
+                if (typeof mcp.instance[method] !== 'function') {
+                    res.writeHead(404);
+                    res.end(JSON.stringify({ error: `Method not found: ${method}` }));
+                    return;
+                }
+                const result = await mcp.instance[method](args || {});
+                res.setHeader('Content-Type', 'application/json');
+                res.writeHead(200);
+                res.end(JSON.stringify({ result }));
+            }
+            catch (err) {
+                const status = err.message?.includes('too large') ? 413 : 500;
+                res.setHeader('Content-Type', 'application/json');
+                res.writeHead(status);
+                res.end(JSON.stringify({ error: err.message || String(err) }));
+            }
             return;
         }
         // Platform Bridge API: Generate platform compatibility script
@@ -2232,6 +2271,26 @@ export async function startBeam(rawWorkingDir, port) {
             logger.info(isNewPhoton
                 ? `✨ New photon detected: ${photonName}`
                 : `🔄 File change detected, reloading ${photonName}...`);
+            // Auto-scaffold empty photon files with a starter template
+            if (isNewPhoton) {
+                try {
+                    const rawContent = await fs.readFile(photonPath, 'utf-8');
+                    if (rawContent.trim().length === 0) {
+                        const className = photonName
+                            .split(/[-_]/)
+                            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                            .join('');
+                        const scaffold = `/**\n * ${className} Photon\n */\n\nexport default class ${className} {\n  /**\n   * Example tool\n   * @param message Message to echo\n   */\n  async echo(params: { message: string }) {\n    return \`Echo: \${params.message}\`;\n  }\n}\n`;
+                        await fs.writeFile(photonPath, scaffold, 'utf-8');
+                        logger.info(`📝 Scaffolded empty file: ${photonName}.photon.ts`);
+                        // The write triggers another watcher event which will load the scaffolded photon
+                        return;
+                    }
+                }
+                catch {
+                    // File read failed, continue with normal load attempt
+                }
+            }
             // For new photons, check if configuration is needed first
             if (isNewPhoton) {
                 const extractor = new SchemaExtractor();
@@ -2342,6 +2401,7 @@ export async function startBeam(rawWorkingDir, port) {
                     // Can't extract params
                 }
                 backfillEnvDefaults(mcp.instance, reloadConstructorParams);
+                const isStateful = /@stateful\b/.test(reloadSource);
                 const reloadedPhoton = {
                     id: generatePhotonId(photonPath),
                     name: photonName,
@@ -2353,8 +2413,10 @@ export async function startBeam(rawWorkingDir, port) {
                     description: reloadClassMeta.description,
                     icon: reloadClassMeta.icon,
                     internal: reloadClassMeta.internal,
+                    ...(isStateful && { stateful: true }),
                     ...(reloadConstructorParams.length > 0 && { requiredParams: reloadConstructorParams }),
-                    ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+                    ...(mcp.injectedPhotons &&
+                        mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
                 };
                 if (isNewPhoton) {
                     photons.push(reloadedPhoton);
@@ -2499,12 +2561,22 @@ export async function startBeam(rawWorkingDir, port) {
                     process.exit(1);
                 }
             });
-            server.listen(currentPort, '0.0.0.0', () => {
+            // Security: bind to localhost by default, configurable via BEAM_BIND_ADDRESS
+            const bindAddress = process.env.BEAM_BIND_ADDRESS || '127.0.0.1';
+            server.listen(currentPort, bindAddress, () => {
                 process.env.BEAM_PORT = String(currentPort);
                 const url = `http://localhost:${currentPort}`;
                 console.log(`\n⚡ Photon Beam → ${url} (loading photons...)\n`);
                 resolve();
             });
+            // Configure server and socket timeouts to prevent premature disconnections
+            // Disable server timeout for long-lived SSE connections (0 = no timeout)
+            server.setTimeout(0);
+            // Enable TCP keepalive on all connections to prevent intermediary timeouts
+            server.on('connection', (socket) => {
+                socket.setKeepAlive(true, 60000); // Send keepalive probe every 60s
+                socket.setTimeout(0); // Disable socket inactivity timeout
+            });
         };
         tryListen();
     });
@@ -2529,12 +2601,49 @@ export async function startBeam(rawWorkingDir, port) {
     const photonStatus = unconfiguredCount > 0
         ? `${configuredCount} ready, ${unconfiguredCount} need setup`
         : `${configuredCount} photon${configuredCount !== 1 ? 's' : ''} ready`;
-    const mcpStatus = externalMCPList.length > 0
-        ? `, ${connectedMCPs}/${externalMCPList.length} MCPs`
-        : '';
+    const mcpStatus = externalMCPList.length > 0 ? `, ${connectedMCPs}/${externalMCPList.length} MCPs` : '';
     console.log(`⚡ Photon Beam ready (${photonStatus}${mcpStatus})`);
     // Notify connected clients that photon list is now available
     broadcastPhotonChange();
+    // Auto-start daemon and subscribe to state-changed events for stateful photons
+    // Uses reconnect: true so subscriptions survive daemon restarts
+    const statefulPhotons = photons.filter((p) => p.stateful && p.configured);
+    if (statefulPhotons.length > 0) {
+        try {
+            await ensureDaemon();
+            for (const photon of statefulPhotons) {
+                const photonName = photon.name;
+                const channel = `${photonName}:state-changed`;
+                subscribeChannel(photonName, channel, (message) => {
+                    broadcastToBeam('photon/state-changed', {
+                        photon: photonName,
+                        method: message?.method,
+                        data: message?.data,
+                    });
+                }, {
+                    reconnect: true,
+                    onReconnect: () => logger.info(`📡 Reconnected ${channel} subscription`),
+                    onRefreshNeeded: () => {
+                        logger.info(`📡 Refresh needed for ${channel} (events lost during daemon restart)`);
+                        broadcastToBeam('photon/state-changed', {
+                            photon: photonName,
+                            method: '_refresh',
+                            data: {},
+                        });
+                    },
+                })
+                    .then(() => {
+                    logger.info(`📡 Subscribed to ${channel} for cross-client sync`);
+                })
+                    .catch((err) => {
+                    logger.warn(`Failed to subscribe to ${channel}: ${getErrorMessage(err)}`);
+                });
+            }
+        }
+        catch (err) {
+            logger.warn(`Failed to start daemon for stateful photons: ${getErrorMessage(err)}`);
+        }
+    }
     // Set up file watchers for symlinked and bundled photon assets (now that photons are loaded)
     for (const photon of photons) {
         if (!photon.path) {
@@ -2673,7 +2782,9 @@ export async function startBeam(rawWorkingDir, port) {
                             externalMCPSDKClients.delete(name);
                         }
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        /* ignore */
+                    }
                     externalMCPClients.delete(name);
                     logger.info(`🔌 Removed external MCP: ${name}`);
                 }
@@ -2701,7 +2812,9 @@ export async function startBeam(rawWorkingDir, port) {
                                 externalMCPSDKClients.delete(name);
                             }
                         }
-                        catch { /* ignore */ }
+                        catch {
+                            /* ignore */
+                        }
                         externalMCPClients.delete(name);
                         externalMCPs.splice(idx, 1);
                     }
@@ -2812,7 +2925,8 @@ async function configurePhotonViaMCP(photonName, config, photons, photonMCPs, lo
             isApp,
             appEntry: mainMethod,
             assets: mcp.assets,
-            ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+            ...(mcp.injectedPhotons &&
+                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
         };
         photons[photonIndex] = configuredPhoton;
         logger.info(`✅ ${photonName} configured via MCP`);
@@ -2908,7 +3022,8 @@ async function reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, saved
             description: reloadClassMeta.description,
             icon: reloadClassMeta.icon,
             internal: reloadClassMeta.internal,
-            ...(mcp.injectedPhotons && mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+            ...(mcp.injectedPhotons &&
+                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
         };
         photons[photonIndex] = reloadedPhoton;
         logger.info(`🔄 ${photonName} reloaded via MCP`);
@@ -3000,10 +3115,7 @@ async function generatePhotonHelpMarkdown(photonName, photons) {
     const mdPath = path.join(sourceDir, `${photonName}.md`);
     // Check if .md file already exists and is newer than the photon source
     try {
-        const [mdStat, srcStat] = await Promise.all([
-            fs.stat(mdPath),
-            fs.stat(photon.path),
-        ]);
+        const [mdStat, srcStat] = await Promise.all([fs.stat(mdPath), fs.stat(photon.path)]);
         if (mdStat.mtimeMs >= srcStat.mtimeMs) {
             const existing = await fs.readFile(mdPath, 'utf-8');
             if (existing.trim()) {