@portel/photon 1.4.1 → 1.6.0

package/dist/server.js

@@ -2,23 +2,86 @@
  * Photon MCP Server
  *
  * Wraps a .photon.ts file as an MCP server using @modelcontextprotocol/sdk
+ * Supports both stdio and SSE transports
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import * as fs from 'fs/promises';
+import { createServer } from 'node:http';
+import { URL } from 'node:url';
 import { PhotonLoader } from './loader.js';
+import { createStandaloneMCPClientFactory } from './mcp-client.js';
+import { PHOTON_VERSION } from './version.js';
+import { createLogger } from './shared/logger.js';
+import { getErrorMessage } from './shared/error-handler.js';
+import { validateOrThrow, assertString, notEmpty, inRange, oneOf, hasExtension, } from './shared/validation.js';
+import { generatePlaygroundHTML } from './auto-ui/playground-html.js';
+import { subscribeChannel, pingDaemon, reloadDaemon, publishToChannel } from './daemon/client.js';
+import { isDaemonRunning, startDaemon } from './daemon/manager.js';
+import { PhotonDocExtractor } from './photon-doc-extractor.js';
+export class HotReloadDisabledError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HotReloadDisabledError';
+    }
+}
 export class PhotonServer {
     loader;
     mcp = null;
     server;
     options;
+    mcpClientFactory = null;
+    httpServer = null;
+    sseSessions = new Map();
+    devMode;
+    hotReloadDisabled = false;
+    lastReloadError;
+    statusClients = new Set();
+    channelUnsubscribers = [];
+    daemonName = null;
+    currentStatus = {
+        type: 'info',
+        message: 'Ready',
+        timestamp: Date.now(),
+    };
+    logger;
     constructor(options) {
+        // Validate options (filePath validation skipped for unresolved photons)
+        if (!options.unresolvedPhoton) {
+            assertString(options.filePath, 'filePath');
+            validateOrThrow(options.filePath, [
+                notEmpty('filePath'),
+                hasExtension('filePath', ['ts', 'js']),
+            ]);
+        }
+        if (options.transport) {
+            validateOrThrow(options.transport, [oneOf('transport', ['stdio', 'sse'])]);
+        }
+        if (options.port !== undefined) {
+            validateOrThrow(options.port, [inRange('port', 1, 65535)]);
+        }
         this.options = options;
-        this.loader = new PhotonLoader(true); // verbose=true for server mode
+        this.devMode = options.devMode || false;
+        const baseLoggerOptions = {
+            component: 'photon-server',
+            scope: options.transport ?? 'stdio',
+            minimal: true,
+            ...options.logOptions,
+        };
+        if (!baseLoggerOptions.component) {
+            baseLoggerOptions.component = 'photon-server';
+        }
+        if (!baseLoggerOptions.scope) {
+            baseLoggerOptions.scope = this.devMode ? 'dev' : 'runtime';
+        }
+        this.logger = createLogger(baseLoggerOptions);
+        this.loader = new PhotonLoader(true, this.logger.child({ component: 'photon-loader', scope: 'loader' }));
         // Create MCP server instance
         this.server = new Server({
             name: 'photon-mcp',
-            version: '1.0.0',
+            version: PHOTON_VERSION,
         }, {
             capabilities: {
                 tools: {
@@ -30,43 +93,395 @@ export class PhotonServer {
                 resources: {
                     listChanged: true, // We support hot reload notifications
                 },
+                // Note: Server doesn't declare elicitation capability - that's a client capability
+                // The server uses elicitInput() when the client has elicitation support
             },
         });
         // Set up protocol handlers
         this.setupHandlers();
     }
+    createScopedLogger(scope) {
+        return this.logger.child({ scope });
+    }
+    getLogger() {
+        return this.logger;
+    }
+    log(level, message, meta) {
+        this.logger.log(level, message, meta);
+    }
+    /**
+     * Detect UI format based on client capabilities
+     *
+     * SEP-1865 clients advertise ui capability in experimental or root capabilities.
+     * Legacy Photon clients may not have explicit UI capability but support photon:// URIs.
+     * Text-only clients have no UI support.
+     *
+     * @param server - Optional server instance (for SSE sessions), defaults to main server
+     */
+    getUIFormat(server) {
+        const targetServer = server || this.server;
+        const capabilities = targetServer.getClientCapabilities();
+        if (!capabilities) {
+            // Before initialization or no capabilities - assume legacy Photon
+            return 'photon';
+        }
+        // Check for MCP Apps extension (io.modelcontextprotocol/ui)
+        // Claude Desktop and other MCP Apps clients use this format
+        const extensions = capabilities.extensions;
+        if (extensions?.['io.modelcontextprotocol/ui']) {
+            return 'sep-1865';
+        }
+        // Check for SEP-1865 UI capability
+        // SEP-1865 clients advertise: { experimental: { ui: {} } } or { ui: {} }
+        const experimental = capabilities.experimental;
+        if (experimental?.ui || capabilities.ui) {
+            return 'sep-1865';
+        }
+        // Check client info for known SEP-1865 compatible clients
+        const clientInfo = targetServer._clientVersion;
+        if (clientInfo?.name) {
+            const name = clientInfo.name.toLowerCase();
+            // Known SEP-1865 compatible clients
+            if (name.includes('claude') || name.includes('chatgpt') || name.includes('openai')) {
+                return 'sep-1865';
+            }
+        }
+        // Default to Photon format for backward compatibility
+        return 'photon';
+    }
+    /**
+     * Build UI resource URI based on detected format
+     *
+     * @param uiId - UI template identifier
+     * @param server - Optional server instance (for SSE sessions)
+     */
+    buildUIResourceUri(uiId, server) {
+        const format = this.getUIFormat(server);
+        const photonName = this.mcp?.name || 'unknown';
+        switch (format) {
+            case 'sep-1865':
+                return `ui://${photonName}/${uiId}`;
+            case 'photon':
+            default:
+                return `photon://${photonName}/ui/${uiId}`;
+        }
+    }
+    /**
+     * Build tool metadata for UI based on detected format
+     *
+     * @param uiId - UI template identifier
+     * @param server - Optional server instance (for SSE sessions)
+     */
+    buildUIToolMeta(uiId, server) {
+        const format = this.getUIFormat(server);
+        const uri = this.buildUIResourceUri(uiId, server);
+        switch (format) {
+            case 'sep-1865':
+                // Official MCP Apps spec: _meta.ui.resourceUri
+                return { ui: { resourceUri: uri } };
+            case 'photon':
+            default:
+                return { outputTemplate: uri };
+        }
+    }
+    /**
+     * Get UI mimeType based on detected format and client capabilities
+     *
+     * @param server - Optional server instance (for SSE sessions)
+     */
+    getUIMimeType(server) {
+        const targetServer = server || this.server;
+        const capabilities = targetServer.getClientCapabilities();
+        // Check for MCP Apps extension with declared mimeTypes
+        // Claude Desktop uses: { extensions: { "io.modelcontextprotocol/ui": { mimeTypes: ["text/html;profile=mcp-app"] } } }
+        const extensions = capabilities?.extensions;
+        const mcpUI = extensions?.['io.modelcontextprotocol/ui'];
+        if (mcpUI?.mimeTypes?.[0]) {
+            return mcpUI.mimeTypes[0];
+        }
+        const format = this.getUIFormat(server);
+        return format === 'sep-1865' ? 'text/html;profile=mcp-app' : 'text/html';
+    }
+    /**
+     * Check if client supports elicitation
+     *
+     * Elicitation is a client capability declared during initialization.
+     * The server can use elicitInput() when the client supports it.
+     */
+    clientSupportsElicitation(server) {
+        const targetServer = server || this.server;
+        const capabilities = targetServer.getClientCapabilities();
+        if (!capabilities) {
+            return false;
+        }
+        // Check for elicitation capability (MCP 2025-06 spec)
+        return !!capabilities.elicitation;
+    }
+    /**
+     * Create an MCP-aware input provider for generator ask yields
+     *
+     * Uses MCP elicitInput() when client supports elicitation,
+     * otherwise falls back to readline prompts.
+     */
+    createMCPInputProvider(server) {
+        const targetServer = server || this.server;
+        const capabilities = targetServer.getClientCapabilities();
+        const supportsElicitation = this.clientSupportsElicitation(server);
+        this.log('debug', 'Creating MCP input provider', {
+            supportsElicitation,
+            capabilities: JSON.stringify(capabilities),
+        });
+        return async (ask) => {
+            // If client doesn't support elicitation, fall back to logging the ask
+            // (MCP servers can't use readline - they communicate via protocol)
+            if (!supportsElicitation) {
+                this.log('warn', `Client doesn't support elicitation, ask will be skipped`, {
+                    ask: ask.ask,
+                    message: ask.message,
+                });
+                // Return default values for non-elicitation clients
+                return this.getDefaultForAsk(ask);
+            }
+            try {
+                // Build elicitation request based on ask type
+                const elicitParams = this.buildElicitParams(ask);
+                // Call server.elicitInput() to request user input from the client
+                const result = await targetServer.elicitInput(elicitParams);
+                if (result.action === 'accept' && result.content) {
+                    // Extract the value from the response content
+                    return this.extractElicitValue(ask, result.content);
+                }
+                else if (result.action === 'decline' || result.action === 'cancel') {
+                    this.log('info', `User ${result.action}ed elicitation`, { ask: ask.ask });
+                    return this.getDefaultForAsk(ask);
+                }
+                return this.getDefaultForAsk(ask);
+            }
+            catch (error) {
+                this.log('error', `Elicitation failed`, { ask: ask.ask, error: getErrorMessage(error) });
+                return this.getDefaultForAsk(ask);
+            }
+        };
+    }
+    /**
+     * Build MCP elicit request params from a Photon ask yield
+     */
+    buildElicitParams(ask) {
+        const baseMessage = ask.message || 'Please provide input';
+        switch (ask.ask) {
+            case 'text':
+            case 'password':
+                return {
+                    mode: 'form',
+                    message: baseMessage,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            value: {
+                                type: 'string',
+                                title: ask.label || 'Input',
+                                description: ask.hint || ask.message,
+                                default: ask.default,
+                            },
+                        },
+                        required: ask.required !== false ? ['value'] : [],
+                    },
+                };
+            case 'confirm':
+                return {
+                    mode: 'form',
+                    message: baseMessage,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            confirmed: {
+                                type: 'boolean',
+                                title: 'Confirm',
+                                description: ask.message,
+                                default: ask.default ?? false,
+                            },
+                        },
+                        required: ['confirmed'],
+                    },
+                };
+            case 'number':
+                return {
+                    mode: 'form',
+                    message: baseMessage,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            value: {
+                                type: 'number',
+                                title: ask.label || 'Number',
+                                description: ask.hint || ask.message,
+                                default: ask.default,
+                                minimum: ask.min,
+                                maximum: ask.max,
+                            },
+                        },
+                        required: ask.required !== false ? ['value'] : [],
+                    },
+                };
+            case 'select':
+                // For select, we use enum in the schema
+                const options = (ask.options || []).map((o) => (typeof o === 'string' ? o : o.value));
+                const labels = (ask.options || []).map((o) => (typeof o === 'string' ? o : o.label));
+                return {
+                    mode: 'form',
+                    message: baseMessage + (ask.multi ? ' (select multiple)' : ''),
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            selection: ask.multi
+                                ? {
+                                    type: 'array',
+                                    items: { type: 'string', enum: options },
+                                    title: ask.label || 'Selection',
+                                    description: `Options: ${labels.join(', ')}`,
+                                }
+                                : {
+                                    type: 'string',
+                                    enum: options,
+                                    title: ask.label || 'Selection',
+                                    description: `Options: ${labels.join(', ')}`,
+                                },
+                        },
+                        required: ask.required !== false ? ['selection'] : [],
+                    },
+                };
+            case 'date':
+                return {
+                    mode: 'form',
+                    message: baseMessage,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            value: {
+                                type: 'string',
+                                format: 'date',
+                                title: ask.label || 'Date',
+                                description: ask.hint || ask.message,
+                                default: ask.default,
+                            },
+                        },
+                        required: ask.required !== false ? ['value'] : [],
+                    },
+                };
+            default:
+                // Generic text input for unknown types
+                return {
+                    mode: 'form',
+                    message: baseMessage,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            value: {
+                                type: 'string',
+                                title: 'Input',
+                            },
+                        },
+                    },
+                };
+        }
+    }
+    /**
+     * Extract value from elicitation response content
+     */
+    extractElicitValue(ask, content) {
+        switch (ask.ask) {
+            case 'confirm':
+                return content.confirmed ?? false;
+            case 'select':
+                return content.selection;
+            default:
+                return content.value;
+        }
+    }
+    /**
+     * Get default value for an ask when elicitation is not available or declined
+     */
+    getDefaultForAsk(ask) {
+        if ('default' in ask) {
+            return ask.default;
+        }
+        switch (ask.ask) {
+            case 'confirm':
+                return false;
+            case 'number':
+                return 0;
+            case 'select':
+                return ask.multi ? [] : null;
+            case 'date':
+                return new Date().toISOString().split('T')[0];
+            default:
+                return '';
+        }
+    }
     /**
      * Set up MCP protocol handlers
      */
     setupHandlers() {
         // Handle tools/list
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            // If photon is unresolved (conflict), return placeholder tools from manifest metadata
+            if (!this.mcp && this.options.unresolvedPhoton) {
+                return { tools: this.buildPlaceholderTools() };
+            }
             if (!this.mcp) {
                 return { tools: [] };
             }
             return {
-                tools: this.mcp.tools.map(tool => ({
-                    name: tool.name,
-                    description: tool.description,
-                    inputSchema: tool.inputSchema,
-                })),
+                tools: this.mcp.tools.map((tool) => {
+                    const toolDef = {
+                        name: tool.name,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                    };
+                    // Add _meta with UI template reference (format depends on client capabilities)
+                    const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name);
+                    if (linkedUI) {
+                        toolDef._meta = this.buildUIToolMeta(linkedUI.id);
+                    }
+                    return toolDef;
+                }),
             };
         });
         // Handle tools/call
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name: toolName, arguments: args } = request.params;
+            // Deferred conflict resolution: resolve photon on first tool call
+            if (!this.mcp && this.options.unresolvedPhoton) {
+                await this.resolveUnresolvedPhoton();
+            }
             if (!this.mcp) {
                 throw new Error('MCP not loaded');
             }
-            const { name: toolName, arguments: args } = request.params;
             try {
-                const result = await this.loader.executeTool(this.mcp, toolName, args || {});
+                // Create MCP-aware input provider for elicitation support
+                const inputProvider = this.createMCPInputProvider();
+                // Handler for channel events - forward to daemon for cross-process pub/sub
+                const outputHandler = (emit) => {
+                    if (this.daemonName && emit?.channel) {
+                        publishToChannel(this.daemonName, emit.channel, emit).catch(() => {
+                            // Ignore publish errors - daemon may not be running
+                        });
+                    }
+                };
+                const result = await this.loader.executeTool(this.mcp, toolName, args || {}, {
+                    inputProvider,
+                    outputHandler,
+                });
                 // Find the tool to get its outputFormat
-                const tool = this.mcp.tools.find(t => t.name === toolName);
+                const tool = this.mcp.tools.find((t) => t.name === toolName);
                 const outputFormat = tool?.outputFormat;
+                // Check if this was a stateful workflow execution
+                const isStateful = result && typeof result === 'object' && result._stateful === true;
+                const actualResult = isStateful ? result.result : result;
                 // Build content with optional mimeType annotation
                 const content = {
                     type: 'text',
-                    text: this.formatResult(result),
+                    text: this.formatResult(actualResult),
                 };
                 // Add mimeType annotation if outputFormat is a content type
                 if (outputFormat) {
@@ -76,9 +491,34 @@ export class PhotonServer {
                         content.annotations = { mimeType };
                     }
                 }
+                // For stateful workflows, add run ID as a separate content block
+                // This allows the AI to inform the user about the workflow run
+                if (isStateful && result.runId) {
+                    const workflowInfo = {
+                        type: 'text',
+                        text: `\n\n---\n📋 **Workflow Run**: ${result.runId}\n` +
+                            `Status: ${result.status}${result.resumed ? ' (resumed)' : ''}\n` +
+                            `This is a stateful workflow. To resume if interrupted, use run ID: ${result.runId}`,
+                    };
+                    return { content: [content, workflowInfo] };
+                }
                 return { content: [content] };
             }
             catch (error) {
+                // Check for config error — attempt elicitation to resolve missing env vars
+                const errorMsg = getErrorMessage(error);
+                if (this.mcp?.instance?._photonConfigError &&
+                    this.clientSupportsElicitation()) {
+                    const retryResult = await this.attemptConfigElicitation(toolName, args || {});
+                    if (retryResult)
+                        return retryResult;
+                }
+                // Log error with context for debugging
+                this.log('error', 'Tool execution failed', {
+                    tool: toolName,
+                    error: errorMsg,
+                    args: this.options.devMode ? args : undefined,
+                });
                 // Format error for AI consumption
                 return this.formatError(error, toolName, args);
             }
@@ -89,12 +529,14 @@ export class PhotonServer {
                 return { prompts: [] };
             }
             return {
-                prompts: this.mcp.templates.map(template => ({
+                prompts: this.mcp.templates.map((template) => ({
                     name: template.name,
                     description: template.description,
                     arguments: Object.entries(template.inputSchema.properties || {}).map(([name, schema]) => ({
                         name,
-                        description: schema.description || '',
+                        description: (typeof schema === 'object' && schema && 'description' in schema
+                            ? schema.description
+                            : '') || '',
                         required: template.inputSchema.required?.includes(name) || false,
                     })),
                 })),
@@ -107,7 +549,7 @@ export class PhotonServer {
             }
             const { name: promptName, arguments: args } = request.params;
             // Find the template
-            const template = this.mcp.templates.find(t => t.name === promptName);
+            const template = this.mcp.templates.find((t) => t.name === promptName);
             if (!template) {
                 throw new Error(`Prompt not found: ${promptName}`);
             }
@@ -118,7 +560,11 @@ export class PhotonServer {
                 return this.formatTemplateResult(result);
             }
             catch (error) {
-                throw new Error(`Failed to get prompt: ${error.message}`);
+                this.log('error', 'Prompt execution failed', {
+                    prompt: promptName,
+                    error: getErrorMessage(error),
+                });
+                throw new Error(`Failed to get prompt: ${getErrorMessage(error)}`);
             }
         });
         // Handle resources/list (static URIs only, no parameters)
@@ -127,15 +573,49 @@ export class PhotonServer {
                 return { resources: [] };
             }
             // Only return resources with static URIs (no {parameters})
-            const staticResources = this.mcp.statics.filter(s => !this.isUriTemplate(s.uri));
-            return {
-                resources: staticResources.map(static_ => ({
-                    uri: static_.uri,
-                    name: static_.name,
-                    description: static_.description,
-                    mimeType: static_.mimeType || 'text/plain',
-                })),
-            };
+            const staticResources = this.mcp.statics.filter((s) => !this.isUriTemplate(s.uri));
+            const resources = staticResources.map((static_) => ({
+                uri: static_.uri,
+                name: static_.name,
+                description: static_.description,
+                mimeType: static_.mimeType || 'text/plain',
+            }));
+            // Add assets from asset folder (UI, prompts, resources)
+            if (this.mcp.assets) {
+                const photonName = this.mcp.name;
+                // Add UI assets (format depends on client capabilities)
+                for (const ui of this.mcp.assets.ui) {
+                    // Use pre-generated URI from loader, or build one
+                    const uiUri = ui.uri || this.buildUIResourceUri(ui.id);
+                    resources.push({
+                        uri: uiUri,
+                        name: `ui:${ui.id}`,
+                        description: ui.linkedTool
+                            ? `UI template for ${ui.linkedTool} tool`
+                            : `UI template: ${ui.id}`,
+                        mimeType: ui.mimeType || this.getUIMimeType(),
+                    });
+                }
+                // Add prompt assets
+                for (const prompt of this.mcp.assets.prompts) {
+                    resources.push({
+                        uri: `photon://${photonName}/prompts/${prompt.id}`,
+                        name: `prompt:${prompt.id}`,
+                        description: prompt.description || `Prompt template: ${prompt.id}`,
+                        mimeType: 'text/markdown',
+                    });
+                }
+                // Add resource assets
+                for (const resource of this.mcp.assets.resources) {
+                    resources.push({
+                        uri: `photon://${photonName}/resources/${resource.id}`,
+                        name: `resource:${resource.id}`,
+                        description: resource.description || `Static resource: ${resource.id}`,
+                        mimeType: resource.mimeType || 'application/octet-stream',
+                    });
+                }
+            }
+            return { resources };
         });
         // Handle resources/templates/list (parameterized URIs)
         this.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
@@ -143,9 +623,9 @@ export class PhotonServer {
                 return { resourceTemplates: [] };
             }
             // Only return resources with URI templates (has {parameters})
-            const templateResources = this.mcp.statics.filter(s => this.isUriTemplate(s.uri));
+            const templateResources = this.mcp.statics.filter((s) => this.isUriTemplate(s.uri));
             return {
-                resourceTemplates: templateResources.map(static_ => ({
+                resourceTemplates: templateResources.map((static_) => ({
                     uriTemplate: static_.uri,
                     name: static_.name,
                     description: static_.description,
@@ -159,22 +639,19 @@ export class PhotonServer {
                 throw new Error('MCP not loaded');
             }
             const { uri } = request.params;
-            // Find the static resource by URI
-            const static_ = this.mcp.statics.find(s => s.uri === uri || this.matchUriPattern(s.uri, uri));
-            if (!static_) {
-                throw new Error(`Resource not found: ${uri}`);
-            }
-            try {
-                // Parse URI parameters if URI is a pattern
-                const params = this.parseUriParams(static_.uri, uri);
-                // Execute the static method
-                const result = await this.loader.executeTool(this.mcp, static_.name, params);
-                // Handle Static return type
-                return this.formatStaticResult(result, static_.mimeType);
+            // Check for SEP-1865 ui:// URI format
+            const uiMatch = uri.match(/^ui:\/\/([^/]+)\/(.+)$/);
+            if (uiMatch && this.mcp.assets) {
+                const [, _photonName, assetId] = uiMatch;
+                return this.handleUIAssetRead(uri, assetId);
             }
-            catch (error) {
-                throw new Error(`Failed to read resource: ${error.message}`);
+            // Check for legacy photon:// asset URI format
+            const assetMatch = uri.match(/^photon:\/\/([^/]+)\/(ui|prompts|resources)\/(.+)$/);
+            if (assetMatch && this.mcp.assets) {
+                return this.handleAssetRead(uri, assetMatch);
             }
+            // Handle static resources
+            return this.handleStaticRead(uri);
         });
     }
     /**
@@ -290,12 +767,13 @@ export class PhotonServer {
     formatError(error, toolName, args) {
         // Determine error type
         let errorType = 'runtime_error';
-        let errorMessage = error.message || String(error);
+        let errorMessage = getErrorMessage(error) || String(error);
         let suggestion = '';
         // Categorize common errors and provide suggestions
         if (errorMessage.includes('not a function') || errorMessage.includes('undefined')) {
             errorType = 'implementation_error';
-            suggestion = 'The tool implementation may have an issue. Check that all methods are properly defined.';
+            suggestion =
+                'The tool implementation may have an issue. Check that all methods are properly defined.';
         }
         else if (errorMessage.includes('required') || errorMessage.includes('validation')) {
             errorType = 'validation_error';
@@ -307,7 +785,8 @@ export class PhotonServer {
         }
         else if (errorMessage.includes('ECONNREFUSED') || errorMessage.includes('network')) {
             errorType = 'network_error';
-            suggestion = 'Cannot connect to external service. Check network connection and service availability.';
+            suggestion =
+                'Cannot connect to external service. Check network connection and service availability.';
         }
         else if (errorMessage.includes('permission') || errorMessage.includes('EACCES')) {
             errorType = 'permission_error';
@@ -333,9 +812,9 @@ export class PhotonServer {
             structuredMessage += `\nStack trace:\n${error.stack}\n`;
         }
         // Log to stderr for debugging
-        console.error(`[Photon Error] ${toolName}: ${errorMessage}`);
+        this.log('error', `[Photon Error] ${toolName}: ${errorMessage}`);
         if (this.options.devMode && error.stack) {
-            console.error(error.stack);
+            this.log('debug', error.stack);
         }
         return {
             content: [
@@ -347,29 +826,1333 @@ export class PhotonServer {
             isError: true,
         };
     }
+    /**
+     * Build placeholder tools from unresolved photon manifest metadata
+     */
+    buildPlaceholderTools() {
+        const unresolved = this.options.unresolvedPhoton;
+        if (!unresolved)
+            return [];
+        // Collect tool names from all source metadata
+        const toolNames = new Set();
+        for (const source of unresolved.sources) {
+            if (source.metadata?.tools) {
+                for (const tool of source.metadata.tools) {
+                    toolNames.add(tool);
+                }
+            }
+        }
+        // If no tools in metadata, create a single setup tool
+        if (toolNames.size === 0) {
+            return [
+                {
+                    name: 'setup',
+                    description: `Set up ${unresolved.name} — call this tool to begin.`,
+                    inputSchema: { type: 'object', properties: {} },
+                },
+            ];
+        }
+        return Array.from(toolNames).map((name) => ({
+            name,
+            description: `Requires setup — call to begin.`,
+            inputSchema: { type: 'object', properties: {} },
+        }));
+    }
+    /**
+     * Resolve an unresolved photon (deferred conflict resolution)
+     *
+     * If the client supports elicitation, presents marketplace choices.
+     * Otherwise, auto-picks the recommendation.
+     */
+    async resolveUnresolvedPhoton() {
+        const unresolved = this.options.unresolvedPhoton;
+        if (!unresolved)
+            return;
+        let selectedSource;
+        if (unresolved.sources.length === 1) {
+            selectedSource = unresolved.sources[0];
+        }
+        else if (this.clientSupportsElicitation()) {
+            // Present choices via elicitation
+            const options = {};
+            const sourceLabels = [];
+            for (const source of unresolved.sources) {
+                const version = source.metadata?.version || 'unknown';
+                const label = `${source.marketplace.name} (v${version})`;
+                sourceLabels.push({ const: source.marketplace.name, title: label });
+            }
+            const result = await this.server.elicitInput({
+                message: `Multiple sources found for "${unresolved.name}". Which marketplace should be used?`,
+                requestedSchema: {
+                    type: 'object',
+                    properties: {
+                        marketplace: {
+                            type: 'string',
+                            title: 'Marketplace',
+                            oneOf: sourceLabels,
+                            default: unresolved.recommendation || unresolved.sources[0].marketplace.name,
+                        },
+                    },
+                    required: ['marketplace'],
+                },
+            });
+            const chosen = result.action === 'accept' && result.content
+                ? result.content.marketplace
+                : unresolved.recommendation;
+            selectedSource =
+                unresolved.sources.find((s) => s.marketplace.name === chosen) || unresolved.sources[0];
+        }
+        else {
+            // No elicitation — auto-pick recommendation
+            const rec = unresolved.recommendation;
+            selectedSource = rec
+                ? unresolved.sources.find((s) => s.marketplace.name === rec) || unresolved.sources[0]
+                : unresolved.sources[0];
+            this.log('info', `Auto-selected marketplace: ${selectedSource.marketplace.name}`);
+        }
+        // Download and install photon
+        await this.downloadAndLoadPhoton(unresolved.name, unresolved.workingDir, selectedSource);
+    }
+    /**
+     * Download a photon from a marketplace source, save to workingDir, and load it
+     */
+    async downloadAndLoadPhoton(photonName, workingDir, source) {
+        const { MarketplaceManager, calculateHash } = await import('./marketplace-manager.js');
+        const manager = new MarketplaceManager();
+        await manager.initialize();
+        const result = await manager.fetchMCP(photonName);
+        if (!result) {
+            throw new Error(`Failed to download photon: ${photonName}`);
+        }
+        // Save photon file
+        const { default: fsPromises } = await import('fs/promises');
+        const filePath = (await import('path')).join(workingDir, `${photonName}.photon.ts`);
+        const fileName = `${photonName}.photon.ts`;
+        // Ensure working directory exists
+        await fsPromises.mkdir(workingDir, { recursive: true });
+        await fsPromises.writeFile(filePath, result.content, 'utf-8');
+        // Save metadata
+        if (source.metadata) {
+            const contentHash = calculateHash(result.content);
+            await manager.savePhotonMetadata(fileName, source.marketplace, source.metadata, contentHash);
+            // Download assets if present
+            if (source.metadata.assets && source.metadata.assets.length > 0) {
+                const assets = await manager.fetchAssets(source.marketplace, source.metadata.assets);
+                for (const [assetPath, content] of assets) {
+                    const targetPath = (await import('path')).join(workingDir, assetPath);
+                    const targetDir = (await import('path')).dirname(targetPath);
+                    await fsPromises.mkdir(targetDir, { recursive: true });
+                    await fsPromises.writeFile(targetPath, content, 'utf-8');
+                }
+            }
+        }
+        // Update options and load
+        this.options.filePath = filePath;
+        this.options.unresolvedPhoton = undefined;
+        this.log('info', `Downloaded and loading ${photonName}...`);
+        this.mcp = await this.loader.loadFile(filePath);
+        // Notify clients that tools have changed
+        await this.notifyListsChanged();
+    }
+    /**
+     * Attempt config elicitation to resolve missing env vars, then retry tool call
+     */
+    async attemptConfigElicitation(toolName, args) {
+        try {
+            // Extract constructor params to build form
+            const params = await this.loader.extractConstructorParams(this.options.filePath);
+            if (params.length === 0)
+                return null;
+            const photonName = this.mcp?.name || 'photon';
+            const { toEnvVarName } = await import('./shared/config-docs.js');
+            // Build form properties from constructor params
+            const properties = {};
+            const required = [];
+            for (const param of params) {
+                const envVarName = toEnvVarName(photonName, param.name);
+                const existing = process.env[envVarName];
+                // Skip params that already have values
+                if (existing)
+                    continue;
+                // Skip optional params with defaults
+                if (param.hasDefault || param.isOptional)
+                    continue;
+                properties[envVarName] = {
+                    type: param.type === 'number' ? 'number' : param.type === 'boolean' ? 'boolean' : 'string',
+                    title: param.name,
+                    description: `Environment variable: ${envVarName}`,
+                };
+                required.push(envVarName);
+            }
+            if (Object.keys(properties).length === 0)
+                return null;
+            const result = await this.server.elicitInput({
+                message: `${photonName} requires configuration. Please provide the following:`,
+                requestedSchema: {
+                    type: 'object',
+                    properties,
+                    required,
+                },
+            });
+            if (result.action !== 'accept' || !result.content)
+                return null;
+            // Set env vars from elicitation response
+            const content = result.content;
+            for (const [key, value] of Object.entries(content)) {
+                if (value !== undefined && value !== '') {
+                    process.env[key] = String(value);
+                }
+            }
+            // Reload photon with new env vars
+            this.log('info', 'Reloading photon with elicited configuration...');
+            this.mcp = await this.loader.loadFile(this.options.filePath);
+            await this.notifyListsChanged();
+            // Retry the original tool call
+            const inputProvider = this.createMCPInputProvider();
+            const outputHandler = (emit) => {
+                if (this.daemonName && emit?.channel) {
+                    publishToChannel(this.daemonName, emit.channel, emit).catch(() => { });
+                }
+            };
+            const retryResult = await this.loader.executeTool(this.mcp, toolName, args, {
+                inputProvider,
+                outputHandler,
+            });
+            const isStateful = retryResult && typeof retryResult === 'object' && retryResult._stateful === true;
+            const actualResult = isStateful ? retryResult.result : retryResult;
+            return {
+                content: [{ type: 'text', text: this.formatResult(actualResult) }],
+            };
+        }
+        catch (error) {
+            this.log('warn', `Config elicitation failed: ${getErrorMessage(error)}`);
+            return null; // elicitation unsupported by client
+        }
+    }
     /**
      * Initialize and start the server
      */
     async start() {
         try {
-            // Load the Photon MCP file
-            console.error(`Loading ${this.options.filePath}...`);
-            this.mcp = await this.loader.loadFile(this.options.filePath);
-            // Connect to stdio transport
-            const transport = new StdioServerTransport();
-            await this.server.connect(transport);
-            console.error(`Server started: ${this.mcp.name}`);
+            // If unresolvedPhoton is set, skip loading — defer to first tool call
+            if (this.options.unresolvedPhoton) {
+                this.log('info', `Deferred loading for ${this.options.unresolvedPhoton.name} (${this.options.unresolvedPhoton.sources.length} marketplace sources)`);
+            }
+            else {
+                // Initialize MCP client factory for enabling this.mcp() in Photons
+                // This allows Photons to call external MCPs via protocol
+                try {
+                    this.mcpClientFactory = await createStandaloneMCPClientFactory(this.options.devMode);
+                    const servers = await this.mcpClientFactory.listServers();
+                    if (servers.length > 0) {
+                        this.log('info', `MCP access enabled: ${servers.join(', ')}`);
+                        this.loader.setMCPClientFactory(this.mcpClientFactory);
+                    }
+                }
+                catch (error) {
+                    this.log('warn', `Failed to load MCP config: ${getErrorMessage(error)}`);
+                }
+                // Check if photon is stateful (requires daemon)
+                const extractor = new PhotonDocExtractor(this.options.filePath);
+                const metadata = await extractor.extractFullMetadata();
+                const isStateful = metadata.stateful;
+                // Start daemon for stateful photons (enables cross-client communication)
+                if (isStateful) {
+                    const photonName = metadata.name;
+                    this.daemonName = photonName; // Store for subscription
+                    this.log('info', `Stateful photon detected: ${photonName}`);
+                    if (!isDaemonRunning(photonName)) {
+                        this.log('info', `Starting daemon for ${photonName}...`);
+                        await startDaemon(photonName, this.options.filePath, true);
+                        // Wait for daemon to be ready
+                        for (let i = 0; i < 10; i++) {
+                            await new Promise((r) => setTimeout(r, 500));
+                            if (await pingDaemon(photonName)) {
+                                this.log('info', `Daemon ready for ${photonName}`);
+                                break;
+                            }
+                        }
+                    }
+                    else {
+                        this.log('info', `Daemon already running for ${photonName}`);
+                    }
+                }
+                // Load the Photon MCP file
+                this.log('info', `Loading ${this.options.filePath}...`);
+                this.mcp = await this.loader.loadFile(this.options.filePath);
+            }
+            // Subscribe to daemon channels for cross-process notifications
+            await this.subscribeToChannels();
+            // Start with the appropriate transport
+            const transport = this.options.transport || 'stdio';
+            if (transport === 'sse') {
+                await this.startSSE();
+            }
+            else {
+                await this.startStdio();
+            }
             // In dev mode, we could set up file watching here
             if (this.options.devMode) {
-                console.error('Dev mode enabled - hot reload active');
+                this.log('info', 'Dev mode enabled - hot reload active');
             }
         }
         catch (error) {
-            console.error(`Failed to start server: ${error.message}`);
-            console.error(error.stack);
+            this.log('error', `Failed to start server: ${getErrorMessage(error)}`);
+            if (error instanceof Error && error.stack) {
+                this.log('debug', error.stack);
+            }
             process.exit(1);
         }
     }
+    /**
+     * Subscribe to daemon channels for cross-process notifications
+     * This enables real-time updates when other processes (e.g., Beam UI, other MCP clients) modify data
+     */
+    async subscribeToChannels() {
+        // Only subscribe if we have a daemon running (stateful photon)
+        if (!this.daemonName)
+            return;
+        try {
+            // Subscribe to wildcard channel for all events from this photon
+            // E.g., "kanban:*" receives "kanban:photon", "kanban:my-board", etc.
+            const unsubscribe = await subscribeChannel(this.daemonName, `${this.daemonName}:*`, (message) => {
+                this.handleChannelMessage(message);
+            });
+            this.channelUnsubscribers.push(unsubscribe);
+            this.log('info', `Subscribed to daemon channel: ${this.daemonName}:*`);
+        }
+        catch (error) {
+            this.log('warn', `Failed to subscribe to daemon: ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle incoming channel messages and forward as MCP notifications
+     * This enables cross-client real-time updates (e.g., Beam updates show in Claude Desktop)
+     *
+     * Uses standard MCP Apps notification with embedded _photon data:
+     * - Claude Desktop forwards standard notifications (ui/notifications/host-context-changed)
+     * - Photon bridge extracts _photon field and routes to event listeners
+     * - This ensures cross-client sync works without requiring custom protocol support
+     */
+    async handleChannelMessage(message) {
+        if (!message || typeof message !== 'object')
+            return;
+        const msg = message;
+        // Use STANDARD notification with embedded photon data
+        // Claude Desktop will forward this (it's a standard notification)
+        // Our bridge extracts _photon and routes to the appropriate event handler
+        const payload = {
+            method: 'ui/notifications/host-context-changed',
+            params: {
+                // _photon field carries our custom event data
+                _photon: {
+                    photon: this.daemonName,
+                    channel: msg.channel,
+                    event: msg.event,
+                    data: msg.data,
+                },
+            },
+        };
+        try {
+            await this.server.notification(payload);
+        }
+        catch {
+            // ignore - client may not support notifications
+        }
+        // Also send to SSE sessions
+        for (const session of this.sseSessions.values()) {
+            try {
+                await session.server.notification(payload);
+            }
+            catch {
+                // ignore session errors
+            }
+        }
+    }
+    /**
+     * Start server with stdio transport
+     */
+    async startStdio() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        this.log('info', `Server started: ${this.mcp.name}`);
+    }
+    /**
+     * Start server with SSE transport (HTTP)
+     */
+    async startSSE() {
+        const port = this.options.port || 3000;
+        const ssePath = '/mcp';
+        const messagesPath = '/mcp/messages';
+        this.httpServer = createServer(async (req, res) => {
+            if (!req.url) {
+                res.writeHead(400).end('Missing URL');
+                return;
+            }
+            const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+            // Handle CORS preflight
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204, {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type',
+                });
+                res.end();
+                return;
+            }
+            // SSE connection endpoint
+            if (req.method === 'GET' && url.pathname === ssePath) {
+                await this.handleSSEConnection(res, messagesPath);
+                return;
+            }
+            // Message posting endpoint
+            if (req.method === 'POST' && url.pathname === messagesPath) {
+                await this.handleSSEMessage(req, res, url);
+                return;
+            }
+            // Health check / info endpoint
+            if (req.method === 'GET' && url.pathname === '/') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                const endpoints = {
+                    sse: `http://localhost:${port}${ssePath}`,
+                    messages: `http://localhost:${port}${messagesPath}`,
+                };
+                if (this.devMode) {
+                    endpoints.playground = `http://localhost:${port}/playground`;
+                }
+                res.end(JSON.stringify({
+                    name: this.mcp?.name || 'photon-mcp',
+                    transport: 'sse',
+                    endpoints,
+                    tools: this.mcp?.tools.length || 0,
+                    assets: this.mcp?.assets
+                        ? {
+                            ui: this.mcp.assets.ui.length,
+                            prompts: this.mcp.assets.prompts.length,
+                            resources: this.mcp.assets.resources.length,
+                        }
+                        : null,
+                }));
+                return;
+            }
+            // Playground and API endpoints - only in dev mode
+            if (this.devMode) {
+                if (req.method === 'GET' && url.pathname === '/playground') {
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(await this.getPlaygroundHTML(port));
+                    return;
+                }
+                // API: List all photons
+                if (req.method === 'GET' && url.pathname === '/api/photons') {
+                    res.writeHead(200, {
+                        'Content-Type': 'application/json',
+                        'Access-Control-Allow-Origin': '*',
+                    });
+                    try {
+                        const photons = await this.listAllPhotons();
+                        res.end(JSON.stringify({ photons }));
+                    }
+                    catch (error) {
+                        res.writeHead(500);
+                        res.end(JSON.stringify({ error: getErrorMessage(error) }));
+                    }
+                    return;
+                }
+                // API: List tools (for compatibility, now returns current photon)
+                if (req.method === 'GET' && url.pathname === '/api/tools') {
+                    res.writeHead(200, {
+                        'Content-Type': 'application/json',
+                        'Access-Control-Allow-Origin': '*',
+                    });
+                    const tools = this.mcp?.tools.map((tool) => {
+                        const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name);
+                        return {
+                            name: tool.name,
+                            description: tool.description,
+                            inputSchema: tool.inputSchema,
+                            ui: linkedUI
+                                ? { id: linkedUI.id, uri: `photon://${this.mcp.name}/ui/${linkedUI.id}` }
+                                : null,
+                        };
+                    }) || [];
+                    res.end(JSON.stringify({ tools }));
+                    return;
+                }
+                if (req.method === 'GET' && url.pathname === '/api/status') {
+                    res.writeHead(200, {
+                        'Content-Type': 'application/json',
+                        'Access-Control-Allow-Origin': '*',
+                    });
+                    res.end(JSON.stringify(this.buildStatusSnapshot()));
+                    return;
+                }
+                if (req.method === 'GET' && url.pathname === '/api/status-stream') {
+                    this.handleStatusStream(req, res);
+                    return;
+                }
+            }
+            // API: Call tool
+            if (req.method === 'POST' && url.pathname === '/api/call') {
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Content-Type', 'application/json');
+                let body = '';
+                req.on('data', (chunk) => (body += chunk));
+                req.on('end', async () => {
+                    try {
+                        const { tool, args } = JSON.parse(body);
+                        const result = await this.loader.executeTool(this.mcp, tool, args || {});
+                        const isStateful = result && typeof result === 'object' && result._stateful === true;
+                        res.writeHead(200);
+                        res.end(JSON.stringify({
+                            success: true,
+                            data: isStateful ? result.result : result,
+                        }));
+                    }
+                    catch (error) {
+                        res.writeHead(500);
+                        res.end(JSON.stringify({ success: false, error: getErrorMessage(error) }));
+                    }
+                });
+                return;
+            }
+            // API: Call tool with streaming progress (SSE)
+            if (req.method === 'POST' && url.pathname === '/api/call-stream') {
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Content-Type', 'text/event-stream');
+                res.setHeader('Cache-Control', 'no-cache');
+                res.setHeader('Connection', 'keep-alive');
+                let body = '';
+                req.on('data', (chunk) => (body += chunk));
+                req.on('end', async () => {
+                    let requestId = `run_${Date.now()}`;
+                    const sendMessage = (message) => {
+                        res.write(`event: message\ndata: ${JSON.stringify(message)}\n\n`);
+                    };
+                    try {
+                        const payload = JSON.parse(body || '{}');
+                        const tool = payload.tool;
+                        if (!tool) {
+                            throw new Error('Tool name is required');
+                        }
+                        const args = payload.args || {};
+                        const progressToken = payload.progressToken ?? `progress_${Date.now()}`;
+                        requestId = payload.requestId || requestId;
+                        const sendNotification = (method, params) => {
+                            sendMessage({ jsonrpc: '2.0', method, params });
+                        };
+                        const reportProgress = (emit) => {
+                            const rawValue = typeof emit?.value === 'number' ? emit.value : 0;
+                            const percent = rawValue <= 1 ? rawValue * 100 : rawValue;
+                            sendNotification('notifications/progress', {
+                                progressToken,
+                                progress: percent,
+                                total: 100,
+                                message: emit?.message || null,
+                            });
+                        };
+                        const outputHandler = (emit) => {
+                            if (!emit)
+                                return;
+                            if (emit.emit === 'progress') {
+                                reportProgress(emit);
+                            }
+                            else if (emit.emit === 'status') {
+                                sendNotification('notifications/status', {
+                                    type: emit.type || 'info',
+                                    message: emit.message || '',
+                                });
+                            }
+                            else {
+                                sendNotification('notifications/emit', { event: emit });
+                            }
+                            // Forward channel events to daemon for cross-process pub/sub
+                            if (this.daemonName && emit.channel) {
+                                publishToChannel(this.daemonName, emit.channel, emit).catch(() => {
+                                    // Ignore publish errors - daemon may not be running
+                                });
+                            }
+                        };
+                        sendNotification('notifications/status', {
+                            type: 'info',
+                            message: `Starting ${tool}`,
+                        });
+                        const result = await this.loader.executeTool(this.mcp, tool, args, { outputHandler });
+                        const isStateful = result && typeof result === 'object' && result._stateful === true;
+                        sendMessage({
+                            jsonrpc: '2.0',
+                            id: requestId,
+                            result: {
+                                success: true,
+                                data: isStateful ? result.result : result,
+                            },
+                        });
+                        res.end();
+                    }
+                    catch (error) {
+                        const message = getErrorMessage(error);
+                        const errorPayload = {
+                            jsonrpc: '2.0',
+                            error: { code: -32000, message },
+                        };
+                        if (requestId) {
+                            errorPayload.id = requestId;
+                        }
+                        sendMessage(errorPayload);
+                        res.end();
+                    }
+                });
+                return;
+            }
+            // API: Get UI template
+            if (req.method === 'GET' && url.pathname.startsWith('/api/ui/')) {
+                const uiId = url.pathname.replace('/api/ui/', '');
+                const ui = this.mcp?.assets?.ui.find((u) => u.id === uiId);
+                if (ui?.resolvedPath) {
+                    try {
+                        const content = await fs.readFile(ui.resolvedPath, 'utf-8');
+                        res.writeHead(200, {
+                            'Content-Type': 'text/html',
+                            'Access-Control-Allow-Origin': '*',
+                        });
+                        res.end(content);
+                        return;
+                    }
+                    catch {
+                        // Fall through to 404
+                    }
+                }
+                res.writeHead(404).end('UI not found');
+                return;
+            }
+            res.writeHead(404).end('Not Found');
+        });
+        this.httpServer.on('clientError', (err, socket) => {
+            this.log('warn', 'HTTP client error', { message: err.message });
+            socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+        });
+        await new Promise((resolve) => {
+            this.httpServer.listen(port, () => {
+                this.log('info', `${this.mcp.name} MCP server listening`, {
+                    transport: 'sse',
+                    port,
+                    devMode: this.devMode,
+                });
+                this.log('debug', 'SSE endpoints ready', {
+                    baseUrl: `http://localhost:${port}`,
+                    ssePath,
+                    messagesPath,
+                    playground: this.devMode ? `http://localhost:${port}/playground` : undefined,
+                });
+                resolve();
+            });
+        });
+    }
+    /**
+     * List all photons in the .photon directory
+     */
+    async listAllPhotons() {
+        const { listPhotonFiles, DEFAULT_PHOTON_DIR } = await import('./path-resolver.js');
+        const photonFiles = await listPhotonFiles();
+        const photons = await Promise.all(photonFiles.map(async (file) => {
+            try {
+                const loader = new PhotonLoader(this.devMode, this.logger.child({ component: 'photon-loader', scope: 'discovery' }));
+                const mcp = await loader.loadFile(file);
+                return {
+                    name: mcp.name,
+                    description: mcp.description,
+                    file: file.replace(DEFAULT_PHOTON_DIR + '/', ''),
+                    tools: mcp.tools.map((tool) => ({
+                        name: tool.name,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                    })),
+                };
+            }
+            catch (error) {
+                this.log('warn', `Failed to load photon: ${file}`, { error: getErrorMessage(error) });
+                return null; // skip unloadable photon
+            }
+        }));
+        return photons.filter((p) => p !== null);
+    }
+    /**
+     * Generate playground HTML for interactive testing
+     */
+    async getPlaygroundHTML(port) {
+        const name = this.mcp?.name || 'photon-mcp';
+        return generatePlaygroundHTML({ name, port });
+    }
+    /**
+     * Handle new SSE connection
+     */
+    async handleSSEConnection(res, messagesPath) {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        // Create a new MCP server instance for this session
+        const sessionServer = new Server({
+            name: this.mcp?.name || 'photon-mcp',
+            version: PHOTON_VERSION,
+        }, {
+            capabilities: {
+                tools: { listChanged: true },
+                prompts: { listChanged: true },
+                resources: { listChanged: true },
+                experimental: {
+                    sampling: {}, // Support elicitation via MCP sampling protocol
+                },
+            },
+        });
+        // Copy handlers to the session server
+        this.setupSessionHandlers(sessionServer);
+        // Create SSE transport
+        const transport = new SSEServerTransport(messagesPath, res);
+        const sessionId = transport.sessionId;
+        // Store session
+        this.sseSessions.set(sessionId, { server: sessionServer, transport });
+        // Clean up on close
+        transport.onclose = async () => {
+            this.sseSessions.delete(sessionId);
+            await sessionServer.close();
+        };
+        transport.onerror = (error) => {
+            this.log('warn', 'SSE transport error', {
+                sessionId,
+                error: error instanceof Error ? getErrorMessage(error) : String(error),
+            });
+        };
+        try {
+            await sessionServer.connect(transport);
+            this.log('info', 'SSE client connected', { sessionId });
+        }
+        catch (error) {
+            this.sseSessions.delete(sessionId);
+            this.log('error', 'Failed to establish SSE connection', {
+                sessionId,
+                error: getErrorMessage(error) ?? String(error),
+            });
+            if (!res.headersSent) {
+                res.writeHead(500).end('Failed to establish SSE connection');
+            }
+        }
+    }
+    /**
+     * Handle incoming SSE message
+     */
+    async handleSSEMessage(req, res, url) {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        const sessionId = url.searchParams.get('sessionId');
+        if (!sessionId) {
+            res.writeHead(400).end('Missing sessionId query parameter');
+            return;
+        }
+        const session = this.sseSessions.get(sessionId);
+        if (!session) {
+            res.writeHead(404).end('Unknown session');
+            return;
+        }
+        try {
+            await session.transport.handlePostMessage(req, res);
+        }
+        catch (error) {
+            this.log('error', 'Failed to process SSE message', {
+                sessionId,
+                error: getErrorMessage(error) ?? String(error),
+            });
+            if (!res.headersSent) {
+                res.writeHead(500).end('Failed to process message');
+            }
+        }
+    }
+    /**
+     * Set up handlers for a session-specific MCP server
+     * This duplicates handlers from the main server to each session
+     */
+    setupSessionHandlers(sessionServer) {
+        // Handle tools/list
+        sessionServer.setRequestHandler(ListToolsRequestSchema, async () => {
+            if (!this.mcp)
+                return { tools: [] };
+            return {
+                tools: this.mcp.tools.map((tool) => {
+                    const toolDef = {
+                        name: tool.name,
+                        description: tool.description,
+                        inputSchema: tool.inputSchema,
+                    };
+                    // Add _meta with UI template reference (format depends on client capabilities)
+                    const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name);
+                    if (linkedUI) {
+                        toolDef._meta = this.buildUIToolMeta(linkedUI.id, sessionServer);
+                    }
+                    return toolDef;
+                }),
+            };
+        });
+        // Handle tools/call
+        sessionServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+            if (!this.mcp)
+                throw new Error('MCP not loaded');
+            const { name: toolName, arguments: args } = request.params;
+            try {
+                // Create MCP-aware input provider for elicitation support (use sessionServer for SSE)
+                const inputProvider = this.createMCPInputProvider(sessionServer);
+                // Handler for channel events - forward to daemon for cross-process pub/sub
+                const outputHandler = (emit) => {
+                    if (this.daemonName && emit?.channel) {
+                        publishToChannel(this.daemonName, emit.channel, emit).catch(() => {
+                            // Ignore publish errors - daemon may not be running
+                        });
+                    }
+                };
+                const result = await this.loader.executeTool(this.mcp, toolName, args || {}, {
+                    inputProvider,
+                    outputHandler,
+                });
+                const tool = this.mcp.tools.find((t) => t.name === toolName);
+                const outputFormat = tool?.outputFormat;
+                const isStateful = result && typeof result === 'object' && result._stateful === true;
+                const actualResult = isStateful ? result.result : result;
+                const content = {
+                    type: 'text',
+                    text: this.formatResult(actualResult),
+                };
+                if (outputFormat) {
+                    const { formatToMimeType } = await import('./cli-formatter.js');
+                    const mimeType = formatToMimeType(outputFormat);
+                    if (mimeType) {
+                        content.annotations = { mimeType };
+                    }
+                }
+                const response = { content: [content] };
+                if (isStateful) {
+                    response._meta = { runId: result.runId, status: result.status };
+                }
+                return response;
+            }
+            catch (error) {
+                return this.formatError(error, toolName, args);
+            }
+        });
+        // Handle prompts/list
+        sessionServer.setRequestHandler(ListPromptsRequestSchema, async () => {
+            if (!this.mcp)
+                return { prompts: [] };
+            return {
+                prompts: this.mcp.templates.map((template) => ({
+                    name: template.name,
+                    description: template.description,
+                    arguments: template.inputSchema?.properties
+                        ? Object.entries(template.inputSchema.properties).map(([name, schema]) => ({
+                            name,
+                            description: schema.description || '',
+                            required: template.inputSchema?.required?.includes(name) || false,
+                        }))
+                        : [],
+                })),
+            };
+        });
+        // Handle prompts/get
+        sessionServer.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            if (!this.mcp)
+                throw new Error('MCP not loaded');
+            const { name: promptName, arguments: args } = request.params;
+            try {
+                const result = await this.loader.executeTool(this.mcp, promptName, args || {});
+                return this.formatTemplateResult(result);
+            }
+            catch (error) {
+                throw new Error(`Failed to get prompt: ${getErrorMessage(error)}`);
+            }
+        });
+        // Handle resources/list
+        sessionServer.setRequestHandler(ListResourcesRequestSchema, async () => {
+            if (!this.mcp)
+                return { resources: [] };
+            const resources = [];
+            // Add static resources
+            for (const static_ of this.mcp.statics) {
+                if (!this.isUriTemplate(static_.uri)) {
+                    resources.push({
+                        uri: static_.uri,
+                        name: static_.name,
+                        description: static_.description,
+                        mimeType: static_.mimeType,
+                    });
+                }
+            }
+            // Add asset resources (UI format depends on client capabilities)
+            if (this.mcp.assets) {
+                for (const ui of this.mcp.assets.ui) {
+                    // Use pre-generated URI from loader, or build one
+                    const uiUri = ui.uri || this.buildUIResourceUri(ui.id, sessionServer);
+                    resources.push({
+                        uri: uiUri,
+                        name: `ui:${ui.id}`,
+                        description: ui.linkedTool
+                            ? `UI template for ${ui.linkedTool} tool`
+                            : `UI template: ${ui.id}`,
+                        mimeType: ui.mimeType || this.getUIMimeType(sessionServer),
+                    });
+                }
+                for (const prompt of this.mcp.assets.prompts) {
+                    resources.push({
+                        uri: `photon://${this.mcp.name}/prompts/${prompt.id}`,
+                        name: `prompt:${prompt.id}`,
+                        description: prompt.description || `Prompt template: ${prompt.id}`,
+                        mimeType: 'text/markdown',
+                    });
+                }
+                for (const resource of this.mcp.assets.resources) {
+                    resources.push({
+                        uri: `photon://${this.mcp.name}/resources/${resource.id}`,
+                        name: `resource:${resource.id}`,
+                        description: `Static resource: ${resource.id}`,
+                        mimeType: resource.mimeType || 'application/json',
+                    });
+                }
+            }
+            return { resources };
+        });
+        // Handle resources/templates/list
+        sessionServer.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+            if (!this.mcp)
+                return { resourceTemplates: [] };
+            return {
+                resourceTemplates: this.mcp.statics
+                    .filter((static_) => this.isUriTemplate(static_.uri))
+                    .map((static_) => ({
+                    uriTemplate: static_.uri,
+                    name: static_.name,
+                    description: static_.description,
+                    mimeType: static_.mimeType,
+                })),
+            };
+        });
+        // Handle resources/read
+        sessionServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            if (!this.mcp)
+                throw new Error('MCP not loaded');
+            const { uri } = request.params;
+            // Check for SEP-1865 ui:// URI format
+            const uiMatch = uri.match(/^ui:\/\/([^/]+)\/(.+)$/);
+            if (uiMatch && this.mcp.assets) {
+                const [, _photonName, assetId] = uiMatch;
+                return this.handleUIAssetRead(uri, assetId);
+            }
+            // Check for legacy photon:// asset URI format
+            const assetMatch = uri.match(/^photon:\/\/([^/]+)\/(ui|prompts|resources)\/(.+)$/);
+            if (assetMatch && this.mcp.assets) {
+                return this.handleAssetRead(uri, assetMatch);
+            }
+            // Handle static resources
+            return this.handleStaticRead(uri);
+        });
+    }
+    /**
+     * Handle asset read (for both stdio and SSE handlers)
+     */
+    /**
+     * Handle SEP-1865 ui:// resource read
+     */
+    async handleUIAssetRead(uri, assetId) {
+        const ui = this.mcp.assets.ui.find((u) => u.id === assetId);
+        if (!ui || !ui.resolvedPath) {
+            throw new Error(`UI asset not found: ${uri}`);
+        }
+        let content = await fs.readFile(ui.resolvedPath, 'utf-8');
+        // Inject MCP Apps bridge script for Claude Desktop compatibility
+        const bridgeScript = this.generateMcpAppsBridge();
+        content = content.replace('<head>', `<head>\n${bridgeScript}`);
+        return {
+            contents: [{ uri, mimeType: ui.mimeType || 'text/html;profile=mcp-app', text: content }],
+        };
+    }
+    /**
+     * Generate minimal MCP Apps bridge script for Claude Desktop compatibility
+     * This handles the ui/initialize handshake and tool result delivery
+     */
+    generateMcpAppsBridge() {
+        const photonName = this.mcp?.name || 'photon-app';
+        const injectedPhotons = this.mcp?.injectedPhotons || [];
+        return `<script>
+(function() {
+  'use strict';
+  var pendingCalls = {};
+  var callIdCounter = 0;
+  var toolResult = null;
+  var resultListeners = [];
+  var emitListeners = [];
+  var themeListeners = [];
+  var eventListeners = {};  // For specific event subscriptions (e.g., 'taskMove')
+  var photonEventListeners = {};  // Namespaced by photon name for injected photons
+  var currentTheme = 'dark';
+  var injectedPhotons = ${JSON.stringify(injectedPhotons)};
+
+  function generateCallId() {
+    return 'call_' + (++callIdCounter) + '_' + Math.random().toString(36).slice(2);
+  }
+
+  function postToHost(msg) {
+    window.parent.postMessage(msg, '*');
+  }
+
+  // Listen for messages from host
+  window.addEventListener('message', function(e) {
+    var m = e.data;
+    if (!m || typeof m !== 'object') return;
+
+    // Handle JSON-RPC messages
+    if (m.jsonrpc === '2.0') {
+      // Response to our request (has id, no method)
+      if (m.id && !m.method && pendingCalls[m.id]) {
+        var pending = pendingCalls[m.id];
+        delete pendingCalls[m.id];
+        if (m.error) {
+          pending.reject(new Error(m.error.message));
+        } else {
+          // Extract clean data from MCP result format
+          var result = m.result;
+          var cleanData = result;
+          if (result && result.structuredContent) {
+            cleanData = result.structuredContent;
+          } else if (result && result.content && Array.isArray(result.content)) {
+            var textItem = result.content.find(function(i) { return i.type === 'text'; });
+            if (textItem && textItem.text) {
+              try { cleanData = JSON.parse(textItem.text); } catch(e) { cleanData = textItem.text; }
+            }
+          }
+          pending.resolve(cleanData);
+        }
+        return;
+      }
+
+      // Tool result notification
+      if (m.method === 'ui/notifications/tool-result') {
+        var result = m.params;
+        // Extract data from MCP result format
+        if (result.structuredContent) {
+          toolResult = result.structuredContent;
+        } else if (result.content && Array.isArray(result.content)) {
+          var textItem = result.content.find(function(i) { return i.type === 'text'; });
+          if (textItem && textItem.text) {
+            try { toolResult = JSON.parse(textItem.text); } catch(e) { toolResult = textItem.text; }
+          }
+        } else {
+          toolResult = result;
+        }
+        // Set __PHOTON_DATA__ for UIs that read it at init
+        window.__PHOTON_DATA__ = toolResult;
+        // Dispatch event for UIs to re-initialize with new data
+        window.dispatchEvent(new CustomEvent('photon:data-ready', { detail: toolResult }));
+        resultListeners.forEach(function(cb) { cb(toolResult); });
+      }
+
+      // Host context changed (theme + embedded photon events)
+      if (m.method === 'ui/notifications/host-context-changed') {
+        // Standard theme handling
+        if (m.params && m.params.theme) {
+          currentTheme = m.params.theme;
+          document.documentElement.classList.remove('light', 'dark');
+          document.documentElement.classList.add(m.params.theme);
+          document.documentElement.setAttribute('data-theme', m.params.theme);
+          themeListeners.forEach(function(cb) { cb(currentTheme); });
+        }
+
+        // Extract embedded photon event data
+        // This enables real-time sync via standard MCP protocol
+        if (m.params && m.params._photon) {
+          var photonData = m.params._photon;
+          // Route to generic emit listeners
+          emitListeners.forEach(function(cb) { cb(photonData); });
+
+          var eventName = photonData.event;
+          var sourcePhoton = photonData.data && photonData.data._source;
+
+          // Route to photon-specific listeners if _source is specified (injected photon events)
+          if (sourcePhoton && photonEventListeners[sourcePhoton] && photonEventListeners[sourcePhoton][eventName]) {
+            photonEventListeners[sourcePhoton][eventName].forEach(function(cb) {
+              cb(photonData.data);
+            });
+          }
+
+          // Also route to global event listeners (main photon events, or fallback)
+          if (eventName && eventListeners[eventName]) {
+            eventListeners[eventName].forEach(function(cb) {
+              cb(photonData.data);
+            });
+          }
+        }
+      }
+    }
+  });
+
+  // Mark that we're in MCP Apps context (not Beam)
+  window.__MCP_APPS_CONTEXT__ = true;
+
+  // Expose photon bridge API
+  window.photon = {
+    get toolOutput() { return toolResult; },
+    onResult: function(cb) {
+      resultListeners.push(cb);
+      if (toolResult) cb(toolResult);
+      return function() {
+        var i = resultListeners.indexOf(cb);
+        if (i >= 0) resultListeners.splice(i, 1);
+      };
+    },
+    callTool: function(name, args) {
+      var callId = generateCallId();
+      return new Promise(function(resolve, reject) {
+        pendingCalls[callId] = { resolve: resolve, reject: reject };
+        postToHost({
+          jsonrpc: '2.0',
+          id: callId,
+          method: 'tools/call',
+          params: { name: name, arguments: args || {} }
+        });
+        setTimeout(function() {
+          if (pendingCalls[callId]) {
+            delete pendingCalls[callId];
+            reject(new Error('Tool call timeout'));
+          }
+        }, 30000);
+      });
+    },
+    invoke: function(name, args) { return window.photon.callTool(name, args); },
+    onEmit: function(cb) {
+      emitListeners.push(cb);
+      return function() {
+        var i = emitListeners.indexOf(cb);
+        if (i >= 0) emitListeners.splice(i, 1);
+      };
+    },
+    onThemeChange: function(cb) {
+      themeListeners.push(cb);
+      // Call immediately with current theme
+      cb(currentTheme);
+      return function() {
+        var i = themeListeners.indexOf(cb);
+        if (i >= 0) themeListeners.splice(i, 1);
+      };
+    },
+    get theme() { return currentTheme; },
+
+    // Generic event subscription for real-time sync
+    // Usage: photon.on('taskMove', function(data) { ... })
+    on: function(eventName, cb) {
+      if (!eventListeners[eventName]) eventListeners[eventName] = [];
+      eventListeners[eventName].push(cb);
+      return function() {
+        var i = eventListeners[eventName].indexOf(cb);
+        if (i >= 0) eventListeners[eventName].splice(i, 1);
+      };
+    },
+
+    // Photon-specific event subscription (for injected photon events)
+    // Usage: photon.onPhoton('notifications', 'alertCreated', function(data) { ... })
+    onPhoton: function(photonName, eventName, cb) {
+      if (!photonEventListeners[photonName]) photonEventListeners[photonName] = {};
+      if (!photonEventListeners[photonName][eventName]) photonEventListeners[photonName][eventName] = [];
+      photonEventListeners[photonName][eventName].push(cb);
+      return function() {
+        var i = photonEventListeners[photonName][eventName].indexOf(cb);
+        if (i >= 0) photonEventListeners[photonName][eventName].splice(i, 1);
+      };
+    }
+  };
+
+  // Create direct window object: window.{photonName}
+  // This provides a clean class-like API that mirrors server methods:
+  //   Server: this.emit('taskMove', data)
+  //   Client: kanban.onTaskMove(cb) - subscribe to events
+  //   Client: kanban.taskMove(args) - call server method
+  var photonName = '${photonName}';
+  window[photonName] = new Proxy({}, {
+    get: function(target, prop) {
+      if (typeof prop !== 'string') return undefined;
+
+      // onEventName -> subscribe to 'eventName' event
+      // e.g., onTaskMove -> subscribe to 'taskMove'
+      if (prop.startsWith('on') && prop.length > 2) {
+        var eventName = prop.charAt(2).toLowerCase() + prop.slice(3);
+        return function(cb) {
+          return window.photon.on(eventName, cb);
+        };
+      }
+
+      // methodName -> call server tool
+      // e.g., taskMove(args) -> photon.callTool('taskMove', args)
+      return function(args) {
+        return window.photon.callTool(prop, args);
+      };
+    }
+  });
+
+  // Create proxies for injected photons (for event subscriptions)
+  // e.g., notifications.onAlertCreated(cb) subscribes to 'alertCreated' from 'notifications' photon
+  injectedPhotons.forEach(function(injectedName) {
+    window[injectedName] = new Proxy({}, {
+      get: function(target, prop) {
+        if (typeof prop !== 'string') return undefined;
+
+        // onEventName -> subscribe to photon-specific event
+        if (prop.startsWith('on') && prop.length > 2) {
+          var eventName = prop.charAt(2).toLowerCase() + prop.slice(3);
+          return function(cb) {
+            return window.photon.onPhoton(injectedName, eventName, cb);
+          };
+        }
+
+        // Method calls on injected photons are not supported from client
+        // (injected photon methods are only available server-side)
+        return undefined;
+      }
+    });
+  });
+
+  // Size notification helper
+  function sendSizeChanged() {
+    var body = document.body;
+    var root = document.documentElement;
+
+    // Calculate actual content dimensions
+    var width = Math.max(
+      body.scrollWidth,
+      body.offsetWidth,
+      root.clientWidth,
+      root.scrollWidth,
+      root.offsetWidth
+    );
+    var height = Math.max(
+      body.scrollHeight,
+      body.offsetHeight,
+      root.clientHeight,
+      root.scrollHeight,
+      root.offsetHeight
+    );
+
+    // Check for scrollable containers with overflow:hidden that hide true content size
+    var containers = document.querySelectorAll('.board, [style*="overflow"]');
+    containers.forEach(function(el) {
+      if (el.scrollWidth > width) width = el.scrollWidth;
+      if (el.scrollHeight > height) height = el.scrollHeight;
+    });
+
+    // For kanban-style boards, calculate from column count
+    var columns = document.querySelectorAll('.column');
+    if (columns.length > 0) {
+      var columnWidth = 220; // min-width + gap
+      var boardPadding = 48;
+      var neededWidth = (columns.length * columnWidth) + boardPadding;
+      if (neededWidth > width) width = neededWidth;
+    }
+
+    // Reasonable minimums, maximums, and padding
+    width = Math.max(width, 600) + 32;
+    // Force minimum height for kanban-style boards
+    // header(120) + column headers(50) + 3-4 cards(450) = 620
+    if (columns.length > 0) {
+      height = Math.max(height, 620);
+    } else {
+      height = Math.max(height, 400);
+    }
+
+    postToHost({
+      jsonrpc: '2.0',
+      method: 'ui/notifications/size-changed',
+      params: { width: width, height: height }
+    });
+  }
+
+  // MCP Apps handshake: send ui/initialize and wait for response
+  var initId = generateCallId();
+  pendingCalls[initId] = {
+    resolve: function(result) {
+      // Apply theme from host context
+      if (result.hostContext && result.hostContext.theme) {
+        document.documentElement.classList.add(result.hostContext.theme);
+        document.documentElement.setAttribute('data-theme', result.hostContext.theme);
+      }
+      // Complete handshake
+      postToHost({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} });
+
+      // Set up size notifications after handshake
+      setTimeout(sendSizeChanged, 100);
+      var resizeObserver = new ResizeObserver(function() {
+        sendSizeChanged();
+      });
+      resizeObserver.observe(document.documentElement);
+      resizeObserver.observe(document.body);
+    },
+    reject: function(err) { console.error('MCP Apps init failed:', err); }
+  };
+
+  postToHost({
+    jsonrpc: '2.0',
+    id: initId,
+    method: 'ui/initialize',
+    params: {
+      appInfo: { name: '${photonName}', version: '1.0.0' },
+      appCapabilities: {},
+      protocolVersion: '2026-01-26'
+    }
+  });
+})();
+</script>`;
+    }
+    /**
+     * Handle legacy photon:// asset read
+     */
+    async handleAssetRead(uri, assetMatch) {
+        const [, _photonName, assetType, assetId] = assetMatch;
+        let resolvedPath;
+        let mimeType = 'text/plain';
+        if (assetType === 'ui') {
+            const ui = this.mcp.assets.ui.find((u) => u.id === assetId);
+            if (ui) {
+                resolvedPath = ui.resolvedPath;
+                mimeType = ui.mimeType || 'text/html;profile=mcp-app';
+            }
+        }
+        else if (assetType === 'prompts') {
+            const prompt = this.mcp.assets.prompts.find((p) => p.id === assetId);
+            if (prompt) {
+                resolvedPath = prompt.resolvedPath;
+                mimeType = 'text/markdown';
+            }
+        }
+        else if (assetType === 'resources') {
+            const resource = this.mcp.assets.resources.find((r) => r.id === assetId);
+            if (resource) {
+                resolvedPath = resource.resolvedPath;
+                mimeType = resource.mimeType || 'application/octet-stream';
+            }
+        }
+        if (resolvedPath) {
+            let content = await fs.readFile(resolvedPath, 'utf-8');
+            // Inject MCP Apps bridge for UI assets
+            if (assetType === 'ui') {
+                const bridgeScript = this.generateMcpAppsBridge();
+                content = content.replace('<head>', `<head>\n${bridgeScript}`);
+            }
+            return {
+                contents: [{ uri, mimeType, text: content }],
+            };
+        }
+        throw new Error(`Asset not found: ${uri}`);
+    }
+    /**
+     * Handle static resource read (for both stdio and SSE handlers)
+     */
+    async handleStaticRead(uri) {
+        const static_ = this.mcp.statics.find((s) => s.uri === uri || this.matchUriPattern(s.uri, uri));
+        if (!static_) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        const params = this.parseUriParams(static_.uri, uri);
+        const result = await this.loader.executeTool(this.mcp, static_.name, params);
+        return this.formatStaticResult(result, static_.mimeType);
+    }
     /**
      * Stop the server
      */
@@ -379,11 +2162,102 @@ export class PhotonServer {
             if (this.mcp?.instance?.onShutdown) {
                 await this.mcp.instance.onShutdown();
             }
+            // Disconnect MCP clients
+            if (this.mcpClientFactory) {
+                await this.mcpClientFactory.disconnect();
+            }
+            // Close SSE sessions
+            for (const [_sessionId, session] of this.sseSessions) {
+                await session.server.close();
+            }
+            this.sseSessions.clear();
+            for (const client of this.statusClients) {
+                client.end();
+            }
+            this.statusClients.clear();
+            // Close HTTP server if running
+            if (this.httpServer) {
+                await new Promise((resolve) => {
+                    this.httpServer.close(() => resolve());
+                });
+                this.httpServer = null;
+            }
             await this.server.close();
-            console.error('Server stopped');
+            this.log('info', 'Server stopped');
         }
         catch (error) {
-            console.error(`Error stopping server: ${error.message}`);
+            this.log('error', 'Error stopping server', { error: getErrorMessage(error) });
+        }
+    }
+    buildStatusSnapshot() {
+        const warnings = [];
+        const instance = this.mcp?.instance;
+        if (instance && '_photonConfigError' in instance && instance._photonConfigError) {
+            warnings.push('Photon configuration incomplete. Check env vars and MCP credentials.');
+        }
+        const assets = this.mcp?.assets || { ui: [], prompts: [], resources: [] };
+        const tools = this.mcp?.tools || [];
+        return {
+            photon: this.mcp?.name || null,
+            devMode: this.devMode,
+            hotReloadDisabled: this.hotReloadDisabled,
+            lastReloadError: this.lastReloadError || null,
+            status: this.currentStatus,
+            warnings,
+            summary: {
+                toolCount: tools.length,
+                tools: tools.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description || '',
+                    hasUI: Boolean(assets.ui?.some((ui) => ui.linkedTool === tool.name)),
+                })),
+                uiAssets: (assets.ui || []).map((ui) => ({ id: ui.id, linkedTool: ui.linkedTool })),
+                promptCount: assets.prompts?.length || 0,
+                resourceCount: assets.resources?.length || 0,
+            },
+        };
+    }
+    handleStatusStream(_req, res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'Access-Control-Allow-Origin': '*',
+        });
+        res.write(`data: ${JSON.stringify(this.buildStatusSnapshot())}\n\n`);
+        this.statusClients.add(res);
+        const cleanup = () => {
+            this.statusClients.delete(res);
+        };
+        res.on('close', cleanup);
+        res.on('error', cleanup);
+    }
+    async broadcastReloadStatus(type, message) {
+        this.currentStatus = { type, message, timestamp: Date.now() };
+        this.pushStatusUpdate();
+        const payload = {
+            method: 'notifications/status',
+            params: { type, message },
+        };
+        try {
+            await this.server.notification(payload);
+        }
+        catch {
+            // ignore
+        }
+        for (const session of this.sseSessions.values()) {
+            try {
+                await session.server.notification(payload);
+            }
+            catch {
+                // ignore session errors
+            }
+        }
+    }
+    pushStatusUpdate() {
+        const frame = `data: ${JSON.stringify(this.currentStatus)}\n\n`;
+        for (const client of this.statusClients) {
+            client.write(frame);
         }
     }
     /**
@@ -398,8 +2272,11 @@ export class PhotonServer {
             clearTimeout(this.reloadRetryTimeout);
             this.reloadRetryTimeout = undefined;
         }
+        if (this.hotReloadDisabled) {
+            throw new HotReloadDisabledError('Hot reload temporarily disabled after repeated failures. Restart Photon or fix the errors to re-enable.');
+        }
         try {
-            console.error('🔄 Reloading...');
+            this.log('info', 'Reloading Photon');
             // Store old instance in case we need to rollback
             const oldInstance = this.mcp;
             // Call shutdown hook on old instance (but keep it for rollback)
@@ -408,7 +2285,7 @@ export class PhotonServer {
                     await oldInstance.instance.onShutdown();
                 }
                 catch (shutdownError) {
-                    console.error(`⚠️  Shutdown hook failed: ${shutdownError.message}`);
+                    this.log('warn', 'Shutdown hook failed during reload', { error: shutdownError.message });
                     // Continue with reload anyway
                 }
             }
@@ -417,40 +2294,70 @@ export class PhotonServer {
             // Success! Update instance and reset failure count
             this.mcp = newMcp;
             this.reloadFailureCount = 0;
+            this.hotReloadDisabled = false;
+            this.lastReloadError = undefined;
             // Send list_changed notifications to inform client of updates
             await this.notifyListsChanged();
-            console.error('✅ Reload complete');
+            // If daemon is running for this photon, reload it too
+            if (this.daemonName && isDaemonRunning(this.daemonName)) {
+                try {
+                    const result = await reloadDaemon(this.daemonName, this.options.filePath);
+                    if (result.success) {
+                        this.log('info', 'Daemon reloaded', { sessionsUpdated: result.sessionsUpdated });
+                    }
+                    else {
+                        this.log('warn', 'Daemon reload failed', { error: result.error });
+                    }
+                }
+                catch (err) {
+                    this.log('warn', 'Daemon reload failed, may need manual restart', {
+                        error: getErrorMessage(err),
+                    });
+                }
+            }
+            await this.broadcastReloadStatus('info', 'Hot reload complete');
+            this.log('info', 'Reload complete');
         }
         catch (error) {
             this.reloadFailureCount++;
-            console.error(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-            console.error(`❌ Reload failed (attempt ${this.reloadFailureCount}/${this.MAX_RELOAD_FAILURES})`);
-            console.error(`Error: ${error.message}`);
-            console.error(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-            if (error.name === 'PhotonInitializationError') {
-                console.error(`\n💡 The onInitialize() lifecycle hook failed.`);
-                console.error(`   Common causes:`);
-                console.error(`   - Database connection failure`);
-                console.error(`   - API authentication error`);
-                console.error(`   - Missing environment variables`);
-                console.error(`   - Invalid configuration`);
+            this.log('error', 'Reload failed', {
+                attempt: this.reloadFailureCount,
+                maxAttempts: this.MAX_RELOAD_FAILURES,
+                error: getErrorMessage(error),
+            });
+            if (error instanceof Error && error.name === 'PhotonInitializationError') {
+                this.log('warn', 'onInitialize lifecycle hook failed', {
+                    hints: [
+                        'Database connection failure',
+                        'API authentication error',
+                        'Missing environment variables',
+                        'Invalid configuration',
+                    ],
+                });
             }
+            this.lastReloadError = {
+                message: getErrorMessage(error),
+                stack: error instanceof Error ? error.stack : undefined,
+                timestamp: Date.now(),
+                attempts: this.reloadFailureCount,
+            };
+            await this.broadcastReloadStatus('error', `Hot reload failed: ${getErrorMessage(error)}`);
             if (this.reloadFailureCount >= this.MAX_RELOAD_FAILURES) {
-                console.error(`\n⚠️  Maximum reload failures reached (${this.MAX_RELOAD_FAILURES})`);
-                console.error(`   Keeping previous working version active.`);
-                console.error(`   Fix the errors and save the file again to retry.`);
-                console.error(`\n   Or restart the server: photon mcp <name> --dev`);
-                // Reset counter after cooling off
+                this.log('error', 'Maximum reload failures reached', {
+                    maxAttempts: this.MAX_RELOAD_FAILURES,
+                    action: 'keeping previous version active',
+                });
+                this.log('info', 'Server still running with previous version');
+                this.hotReloadDisabled = true;
                 this.reloadFailureCount = 0;
+                throw new HotReloadDisabledError('Hot reload disabled after repeated failures. Restart Photon dev server once the errors are resolved.');
             }
-            else {
-                // Schedule automatic retry
-                const retryDelay = Math.min(5000 * this.reloadFailureCount, 15000); // 5s, 10s, 15s max
-                console.error(`\n🔄 Will retry reload in ${retryDelay / 1000}s if file changes again...`);
-                console.error(`   Previous working version remains active.`);
-            }
-            // Keep the old instance running - it's still functional
-            console.error(`\n✓ Server still running with previous version`);
+            const retryDelay = Math.min(5000 * this.reloadFailureCount, 15000);
+            this.log('warn', 'Reload failed - waiting for next change', {
+                retrySeconds: retryDelay / 1000,
+            });
+            this.log('info', 'Server still running with previous version');
+            throw error;
         }
     }
     /**
@@ -471,11 +2378,13 @@ export class PhotonServer {
             await this.server.notification({
                 method: 'notifications/resources/list_changed',
             });
-            console.error('Sent list_changed notifications');
+            this.log('debug', 'Sent list_changed notifications');
         }
         catch (error) {
             // Notification sending is best-effort - don't fail reload if it fails
-            console.error(`Warning: Failed to send list_changed notifications: ${error.message}`);
+            this.log('warn', 'Failed to send list_changed notifications', {
+                error: getErrorMessage(error),
+            });
         }
     }
 }