@portel/photon 1.6.1 → 1.8.0

package/dist/server.js

@@ -12,15 +12,17 @@ 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 { generateExecutionId, } from '@portel/photon-core';
+import { createSDKMCPClientFactory } from '@portel/photon-core';
 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 { subscribeChannel, pingDaemon, publishToChannel } from './daemon/client.js';
+import { isGlobalDaemonRunning, startGlobalDaemon } from './daemon/manager.js';
 import { PhotonDocExtractor } from './photon-doc-extractor.js';
+import { isLocalRequest, readBody, setSecurityHeaders, isPathWithin, validateAssetPath, } from './shared/security.js';
 export class HotReloadDisabledError extends Error {
     constructor(message) {
         super(message);
@@ -41,6 +43,12 @@ export class PhotonServer {
     statusClients = new Set();
     channelUnsubscribers = [];
     daemonName = null;
+    /** Tracked instance name for daemon drift recovery (STDIO path) */
+    daemonInstanceName;
+    /** Tracked instance names per SSE session for daemon drift recovery */
+    sseInstanceNames = new Map();
+    /** Whether client capabilities have been logged (one-time on first tools/list) */
+    clientCapabilitiesLogged = false;
     currentStatus = {
         type: 'info',
         message: 'Ready',
@@ -112,95 +120,31 @@ export class PhotonServer {
     /**
      * 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.
+     * All clients use the MCP Apps standard (SEP-1865) ui:// format.
      * 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';
+    getUIFormat() {
+        return 'sep-1865';
     }
     /**
      * 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);
+    buildUIResourceUri(uiId) {
         const photonName = this.mcp?.name || 'unknown';
-        switch (format) {
-            case 'sep-1865':
-                return `ui://${photonName}/${uiId}`;
-            case 'photon':
-            default:
-                return `photon://${photonName}/ui/${uiId}`;
-        }
+        return `ui://${photonName}/${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 };
-        }
+    buildUIToolMeta(uiId) {
+        const uri = this.buildUIResourceUri(uiId);
+        return { ui: { resourceUri: 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';
+    getUIMimeType() {
+        return 'text/html;profile=mcp-app';
     }
     /**
      * Check if client supports elicitation
@@ -217,6 +161,51 @@ export class PhotonServer {
         // Check for elicitation capability (MCP 2025-06 spec)
         return !!capabilities.elicitation;
     }
+    // Known clients that support MCP Apps UI (fallback when capability isn't announced)
+    static UI_CAPABLE_CLIENTS = new Set(['chatgpt', 'mcpjam', 'mcp-inspector']);
+    /**
+     * Check if client supports MCP Apps UI (structuredContent + _meta.ui)
+     *
+     * Detection order:
+     * 1. capabilities.experimental["io.modelcontextprotocol/ui"] — official MCP Apps negotiation
+     * 2. clientInfo.name — fallback for known UI-capable clients
+     *
+     * Basic/unknown clients get text-only responses (no structuredContent, no _meta.ui).
+     */
+    clientSupportsUI(server) {
+        const targetServer = server || this.server;
+        // 1. Check capabilities (official MCP Apps negotiation)
+        const capabilities = targetServer.getClientCapabilities();
+        if (capabilities?.experimental?.['io.modelcontextprotocol/ui']) {
+            return true;
+        }
+        // 2. Check clientInfo.name (fallback for known UI-capable clients)
+        const clientInfo = targetServer.getClientVersion();
+        if (clientInfo?.name) {
+            if (clientInfo.name === 'beam')
+                return true;
+            if (PhotonServer.UI_CAPABLE_CLIENTS.has(clientInfo.name))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Log client identity and capabilities for debugging tier detection
+     */
+    logClientCapabilities(server) {
+        const clientInfo = server.getClientVersion();
+        const capabilities = server.getClientCapabilities();
+        const supportsUI = this.clientSupportsUI(server);
+        const supportsElicitation = this.clientSupportsElicitation(server);
+        this.log('debug', 'Client connected', {
+            name: clientInfo?.name ?? 'unknown',
+            version: clientInfo?.version ?? 'unknown',
+            tier: supportsUI ? 'mcp-apps' : 'basic',
+            supportsUI,
+            supportsElicitation,
+            capabilities: JSON.stringify(capabilities),
+        });
+    }
     /**
      * Create an MCP-aware input provider for generator ask yields
      *
@@ -418,240 +407,387 @@ export class PhotonServer {
                 return '';
         }
     }
+    // ─── Shared handler implementations ─────────────────────────────────
+    // These methods contain the core logic shared between STDIO and SSE transports.
+    // Both setupHandlers() and setupSessionHandlers() delegate to these.
+    handleListTools(ctx) {
+        if (!this.mcp) {
+            return { tools: [] };
+        }
+        const tools = this.mcp.tools.map((tool) => {
+            const toolDef = {
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            };
+            const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name);
+            if (linkedUI && this.clientSupportsUI(ctx.server)) {
+                toolDef._meta = this.buildUIToolMeta(linkedUI.id);
+            }
+            return toolDef;
+        });
+        // Add runtime-injected instance tools for stateful photons
+        if (this.daemonName) {
+            tools.push({
+                name: '_use',
+                description: `Switch to a named instance. Pass empty name for default. Omit name to select interactively.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'Instance name. Pass empty string "" for default. Omit entirely to select interactively.',
+                        },
+                    },
+                },
+            });
+            tools.push({
+                name: '_instances',
+                description: `List all available instances.`,
+                inputSchema: { type: 'object', properties: {} },
+            });
+        }
+        return { tools };
+    }
+    async handleCallTool(ctx, request) {
+        if (!this.mcp) {
+            throw new Error('MCP not loaded');
+        }
+        const { name: toolName, arguments: args } = request.params;
+        // Route _use and _instances through daemon for stateful photons
+        if (this.daemonName && (toolName === '_use' || toolName === '_instances')) {
+            const { sendCommand } = await import('./daemon/client.js');
+            const sendOpts = {
+                photonPath: this.options.filePath,
+                sessionId: ctx.sessionId,
+                instanceName: ctx.getInstanceName(),
+            };
+            // Elicitation-based instance selection when _use called without name
+            if (toolName === '_use' &&
+                (!args || !('name' in args)) &&
+                this.clientSupportsElicitation(ctx.server)) {
+                const instancesResult = (await sendCommand(this.daemonName, '_instances', {}, sendOpts));
+                const instances = instancesResult?.instances || ['default'];
+                const options = instances.map((inst) => ({
+                    const: inst,
+                    title: inst === 'default' ? '(default)' : inst,
+                }));
+                options.push({ const: '__create_new__', title: 'Create new...' });
+                const result = await ctx.server.elicitInput({
+                    message: 'Select an instance',
+                    requestedSchema: {
+                        type: 'object',
+                        properties: {
+                            instance: {
+                                type: 'string',
+                                title: 'Instance',
+                                oneOf: options,
+                                default: instancesResult?.current || 'default',
+                            },
+                        },
+                        required: ['instance'],
+                    },
+                });
+                if (result.action !== 'accept' || !result.content) {
+                    return { content: [{ type: 'text', text: 'Cancelled' }] };
+                }
+                let selectedName = result.content.instance;
+                // Handle "Create new..." selection
+                if (selectedName === '__create_new__') {
+                    const nameResult = await ctx.server.elicitInput({
+                        message: 'Enter a name for the new instance',
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                name: { type: 'string', title: 'Instance name' },
+                            },
+                            required: ['name'],
+                        },
+                    });
+                    if (nameResult.action !== 'accept' || !nameResult.content) {
+                        return { content: [{ type: 'text', text: 'Cancelled' }] };
+                    }
+                    selectedName = nameResult.content.name;
+                }
+                const useResult = await sendCommand(this.daemonName, '_use', { name: selectedName }, sendOpts);
+                ctx.setInstanceName(selectedName);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(useResult, null, 2) }],
+                };
+            }
+            const result = await sendCommand(this.daemonName, toolName, (args || {}), sendOpts);
+            // Track instance name after successful _use
+            if (toolName === '_use') {
+                ctx.setInstanceName(String(args?.name || ''));
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        // Create MCP-aware input provider for elicitation support
+        const inputProvider = this.createMCPInputProvider(ctx.server);
+        // 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 tool = this.mcp.tools.find((t) => t.name === toolName);
+        const outputFormat = tool?.outputFormat;
+        const result = await this.loader.executeTool(this.mcp, toolName, args || {}, {
+            inputProvider,
+            outputHandler,
+        });
+        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(actualResult),
+        };
+        if (outputFormat) {
+            const { formatToMimeType } = await import('./cli-formatter.js');
+            const mimeType = formatToMimeType(outputFormat);
+            if (mimeType) {
+                content.annotations = { mimeType };
+            }
+        }
+        const response = { content: [content], isError: false };
+        // Add x-output-format for format-aware clients
+        if (outputFormat) {
+            response['x-output-format'] = outputFormat;
+        }
+        // Add stateful workflow metadata (machine-readable _meta)
+        if (isStateful && result.runId) {
+            response._meta = { ...response._meta, runId: result.runId, status: result.status };
+        }
+        // Enrich response with structuredContent + _meta for tools with linked UIs
+        const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === toolName);
+        if (linkedUI && this.clientSupportsUI(ctx.server)) {
+            if (actualResult !== undefined && actualResult !== null) {
+                response.structuredContent =
+                    typeof actualResult === 'string' ? { text: actualResult } : actualResult;
+            }
+            const uiMeta = this.buildUIToolMeta(linkedUI.id);
+            response._meta = { ...response._meta, ...uiMeta };
+        }
+        return response;
+    }
+    handleListPrompts() {
+        if (!this.mcp) {
+            return { prompts: [] };
+        }
+        return {
+            prompts: this.mcp.templates.map((template) => ({
+                name: template.name,
+                description: template.description,
+                arguments: Object.entries(template.inputSchema.properties || {}).map(([name, schema]) => ({
+                    name,
+                    description: (typeof schema === 'object' && schema && 'description' in schema
+                        ? schema.description
+                        : '') || '',
+                    required: template.inputSchema.required?.includes(name) || false,
+                })),
+            })),
+        };
+    }
+    async handleGetPrompt(request) {
+        if (!this.mcp) {
+            throw new Error('MCP not loaded');
+        }
+        const { name: promptName, arguments: args } = request.params;
+        const template = this.mcp.templates.find((t) => t.name === promptName);
+        if (!template) {
+            throw new Error(`Prompt not found: ${promptName}`);
+        }
+        const result = await this.loader.executeTool(this.mcp, promptName, args || {});
+        return this.formatTemplateResult(result);
+    }
+    handleListResources(ctx) {
+        if (!this.mcp) {
+            return { resources: [] };
+        }
+        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',
+        }));
+        if (this.mcp.assets) {
+            const photonName = this.mcp.name;
+            for (const ui of this.mcp.assets.ui) {
+                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(),
+                });
+            }
+            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',
+                });
+            }
+            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 };
+    }
+    handleListResourceTemplates() {
+        if (!this.mcp) {
+            return { resourceTemplates: [] };
+        }
+        const templateResources = this.mcp.statics.filter((s) => this.isUriTemplate(s.uri));
+        return {
+            resourceTemplates: templateResources.map((static_) => ({
+                uriTemplate: static_.uri,
+                name: static_.name,
+                description: static_.description,
+                mimeType: static_.mimeType || 'text/plain',
+            })),
+        };
+    }
+    async handleReadResource(request) {
+        if (!this.mcp) {
+            throw new Error('MCP not loaded');
+        }
+        const { uri } = request.params;
+        const uiMatch = uri.match(/^ui:\/\/([^/]+)\/(.+)$/);
+        if (uiMatch && this.mcp.assets) {
+            const [, _photonName, assetId] = uiMatch;
+            return this.handleUIAssetRead(uri, assetId);
+        }
+        const assetMatch = uri.match(/^photon:\/\/([^/]+)\/(ui|prompts|resources)\/(.+)$/);
+        if (assetMatch && this.mcp.assets) {
+            return this.handleAssetRead(uri, assetMatch);
+        }
+        return this.handleStaticRead(uri);
+    }
+    // ─── Transport-specific setup ─────────────────────────────────────
     /**
-     * Set up MCP protocol handlers
+     * Set up MCP protocol handlers (STDIO transport)
      */
     setupHandlers() {
-        // Handle tools/list
+        const ctx = {
+            server: this.server,
+            getInstanceName: () => this.daemonInstanceName,
+            setInstanceName: (name) => {
+                this.daemonInstanceName = name;
+            },
+            sessionId: `stdio-${this.daemonName}`,
+        };
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            // If photon is unresolved (conflict), return placeholder tools from manifest metadata
+            if (!this.clientCapabilitiesLogged) {
+                this.clientCapabilitiesLogged = true;
+                this.logClientCapabilities(this.server);
+            }
+            // STDIO-only: deferred conflict resolution
             if (!this.mcp && this.options.unresolvedPhoton) {
                 return { tools: this.buildPlaceholderTools() };
             }
-            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);
-                    }
-                    return toolDef;
-                }),
-            };
+            return this.handleListTools(ctx);
         });
-        // 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
+            // STDIO-only: deferred conflict resolution
             if (!this.mcp && this.options.unresolvedPhoton) {
                 await this.resolveUnresolvedPhoton();
             }
-            if (!this.mcp) {
-                throw new Error('MCP not loaded');
-            }
-            try {
-                // 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
+            // STDIO-only: @async fire-and-forget execution
+            if (this.mcp) {
+                const { name: toolName, arguments: args } = request.params;
                 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(actualResult),
-                };
-                // Add mimeType annotation if outputFormat is a content type
-                if (outputFormat) {
-                    const { formatToMimeType } = await import('./cli-formatter.js');
-                    const mimeType = formatToMimeType(outputFormat);
-                    if (mimeType) {
-                        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}`,
+                if (tool?.isAsync) {
+                    const executionId = generateExecutionId();
+                    const inputProvider = this.createMCPInputProvider();
+                    const outputHandler = (emit) => {
+                        if (this.daemonName && emit?.channel) {
+                            publishToChannel(this.daemonName, emit.channel, emit).catch(() => { });
+                        }
+                    };
+                    this.loader
+                        .executeTool(this.mcp, toolName, args || {}, { inputProvider, outputHandler })
+                        .catch((error) => {
+                        this.log('error', `Async tool ${toolName} failed`, {
+                            executionId,
+                            error: getErrorMessage(error),
+                        });
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    executionId,
+                                    status: 'running',
+                                    photon: this.mcp.name,
+                                    method: toolName,
+                                    message: `Task started in background. Use execution ID to check status.`,
+                                }, null, 2),
+                            },
+                        ],
                     };
-                    return { content: [content, workflowInfo] };
                 }
-                return { content: [content] };
+            }
+            try {
+                return await this.handleCallTool(ctx, request);
             }
             catch (error) {
-                // Check for config error — attempt elicitation to resolve missing env vars
-                const errorMsg = getErrorMessage(error);
-                if (this.mcp?.instance?._photonConfigError &&
-                    this.clientSupportsElicitation()) {
+                // STDIO-only: config elicitation retry
+                const { name: toolName, arguments: args } = request.params;
+                if (this.mcp?.instance?._photonConfigError && this.clientSupportsElicitation()) {
                     const retryResult = await this.attemptConfigElicitation(toolName, args || {});
                     if (retryResult)
                         return retryResult;
                 }
-                // Log error with context for debugging
+                // STDIO-only: verbose error logging
                 this.log('error', 'Tool execution failed', {
                     tool: toolName,
-                    error: errorMsg,
+                    error: getErrorMessage(error),
                     args: this.options.devMode ? args : undefined,
                 });
-                // Format error for AI consumption
                 return this.formatError(error, toolName, args);
             }
         });
-        // Handle prompts/list
         this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
-            if (!this.mcp) {
-                return { prompts: [] };
-            }
-            return {
-                prompts: this.mcp.templates.map((template) => ({
-                    name: template.name,
-                    description: template.description,
-                    arguments: Object.entries(template.inputSchema.properties || {}).map(([name, schema]) => ({
-                        name,
-                        description: (typeof schema === 'object' && schema && 'description' in schema
-                            ? schema.description
-                            : '') || '',
-                        required: template.inputSchema.required?.includes(name) || false,
-                    })),
-                })),
-            };
+            return this.handleListPrompts();
         });
-        // Handle prompts/get
         this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-            if (!this.mcp) {
-                throw new Error('MCP not loaded');
-            }
-            const { name: promptName, arguments: args } = request.params;
-            // Find the template
-            const template = this.mcp.templates.find((t) => t.name === promptName);
-            if (!template) {
-                throw new Error(`Prompt not found: ${promptName}`);
-            }
             try {
-                // Execute the template method
-                const result = await this.loader.executeTool(this.mcp, promptName, args || {});
-                // Handle Template/TemplateResponse return types
-                return this.formatTemplateResult(result);
+                return await this.handleGetPrompt(request);
             }
             catch (error) {
+                // STDIO-only: verbose error logging for prompts
+                const { name: promptName } = request.params;
                 this.log('error', 'Prompt execution failed', {
                     prompt: promptName,
                     error: getErrorMessage(error),
                 });
-                throw new Error(`Failed to get prompt: ${getErrorMessage(error)}`);
+                throw error;
             }
         });
-        // Handle resources/list (static URIs only, no parameters)
         this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-            if (!this.mcp) {
-                return { resources: [] };
-            }
-            // Only return resources with static URIs (no {parameters})
-            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 };
+            return this.handleListResources(ctx);
         });
-        // Handle resources/templates/list (parameterized URIs)
         this.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
-            if (!this.mcp) {
-                return { resourceTemplates: [] };
-            }
-            // Only return resources with URI templates (has {parameters})
-            const templateResources = this.mcp.statics.filter((s) => this.isUriTemplate(s.uri));
-            return {
-                resourceTemplates: templateResources.map((static_) => ({
-                    uriTemplate: static_.uri,
-                    name: static_.name,
-                    description: static_.description,
-                    mimeType: static_.mimeType || 'text/plain',
-                })),
-            };
+            return this.handleListResourceTemplates();
         });
-        // Handle resources/read
         this.server.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);
+            return this.handleReadResource(request);
         });
     }
     /**
@@ -874,7 +1010,6 @@ export class PhotonServer {
         }
         else if (this.clientSupportsElicitation()) {
             // Present choices via elicitation
-            const options = {};
             const sourceLabels = [];
             for (const source of unresolved.sources) {
                 const version = source.metadata?.version || 'unknown';
@@ -939,7 +1074,13 @@ export class PhotonServer {
             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);
+                    // Security: validate asset path to prevent traversal
+                    const safePath = validateAssetPath(assetPath);
+                    const targetPath = (await import('path')).join(workingDir, safePath);
+                    if (!isPathWithin(targetPath, workingDir)) {
+                        this.log('warn', `Skipping unsafe asset path: ${assetPath}`);
+                        continue;
+                    }
                     const targetDir = (await import('path')).dirname(targetPath);
                     await fsPromises.mkdir(targetDir, { recursive: true });
                     await fsPromises.writeFile(targetPath, content, 'utf-8');
@@ -1011,7 +1152,9 @@ export class PhotonServer {
             const inputProvider = this.createMCPInputProvider();
             const outputHandler = (emit) => {
                 if (this.daemonName && emit?.channel) {
-                    publishToChannel(this.daemonName, emit.channel, emit).catch(() => { });
+                    publishToChannel(this.daemonName, emit.channel, emit).catch((e) => {
+                        this.log('debug', 'Publish to channel failed', { error: getErrorMessage(e) });
+                    });
                 }
             };
             const retryResult = await this.loader.executeTool(this.mcp, toolName, args, {
@@ -1042,7 +1185,7 @@ export class PhotonServer {
                 // 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);
+                    this.mcpClientFactory = await createSDKMCPClientFactory(this.options.devMode);
                     const servers = await this.mcpClientFactory.listServers();
                     if (servers.length > 0) {
                         this.log('info', `MCP access enabled: ${servers.join(', ')}`);
@@ -1061,9 +1204,9 @@ export class PhotonServer {
                     const photonName = metadata.name;
                     this.daemonName = photonName; // Store for subscription
                     this.log('info', `Stateful photon detected: ${photonName}`);
-                    if (!isDaemonRunning(photonName)) {
+                    if (!isGlobalDaemonRunning()) {
                         this.log('info', `Starting daemon for ${photonName}...`);
-                        await startDaemon(photonName, this.options.filePath, true);
+                        await startGlobalDaemon(true);
                         // Wait for daemon to be ready
                         for (let i = 0; i < 10; i++) {
                             await new Promise((r) => setTimeout(r, 500));
@@ -1156,16 +1299,16 @@ export class PhotonServer {
         try {
             await this.server.notification(payload);
         }
-        catch {
-            // ignore - client may not support notifications
+        catch (e) {
+            this.log('debug', 'Notification send failed', { error: getErrorMessage(e) });
         }
         // Also send to SSE sessions
         for (const session of this.sseSessions.values()) {
             try {
                 await session.server.notification(payload);
             }
-            catch {
-                // ignore session errors
+            catch (e) {
+                this.log('debug', 'Session notification failed', { error: getErrorMessage(e) });
             }
         }
     }
@@ -1185,6 +1328,8 @@ export class PhotonServer {
         const ssePath = '/mcp';
         const messagesPath = '/mcp/messages';
         this.httpServer = createServer(async (req, res) => {
+            // Security: set standard security headers on all responses
+            setSecurityHeaders(res);
             if (!req.url) {
                 res.writeHead(400).end('Missing URL');
                 return;
@@ -1271,7 +1416,7 @@ export class PhotonServer {
                             description: tool.description,
                             inputSchema: tool.inputSchema,
                             ui: linkedUI
-                                ? { id: linkedUI.id, uri: `photon://${this.mcp.name}/ui/${linkedUI.id}` }
+                                ? { id: linkedUI.id, uri: `ui://${this.mcp.name}/${linkedUI.id}` }
                                 : null,
                         };
                     }) || [];
@@ -1293,34 +1438,48 @@ export class PhotonServer {
             }
             // API: Call tool
             if (req.method === 'POST' && url.pathname === '/api/call') {
-                res.setHeader('Access-Control-Allow-Origin', '*');
+                // Security: restrict CORS to localhost and require local request
+                res.setHeader('Access-Control-Allow-Origin', `http://localhost:${this.options.port || 3000}`);
                 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) }));
-                    }
-                });
+                if (!isLocalRequest(req)) {
+                    res.writeHead(403);
+                    res.end(JSON.stringify({ success: false, error: 'Forbidden: non-local request' }));
+                    return;
+                }
+                if (!this.mcp) {
+                    res.writeHead(503);
+                    res.end(JSON.stringify({ success: false, error: 'Photon not loaded' }));
+                    return;
+                }
+                try {
+                    const body = await readBody(req);
+                    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) {
+                    const status = error.message?.includes('too large') ? 413 : 500;
+                    res.writeHead(status);
+                    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('Access-Control-Allow-Origin', `http://localhost:${this.options.port || 3000}`);
                 res.setHeader('Content-Type', 'text/event-stream');
                 res.setHeader('Cache-Control', 'no-cache');
                 res.setHeader('Connection', 'keep-alive');
+                if (!this.mcp) {
+                    res.writeHead(503, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ success: false, error: 'Photon not loaded' }));
+                    return;
+                }
                 let body = '';
                 req.on('data', (chunk) => (body += chunk));
                 req.on('end', async () => {
@@ -1508,10 +1667,21 @@ export class PhotonServer {
         const sessionId = transport.sessionId;
         // Store session
         this.sseSessions.set(sessionId, { server: sessionServer, transport });
-        // Clean up on close
+        // Clean up on close (guard against recursive close:
+        // onclose → sessionServer.close() → transport.close() → onclose)
+        let closing = false;
         transport.onclose = async () => {
+            if (closing)
+                return;
+            closing = true;
             this.sseSessions.delete(sessionId);
-            await sessionServer.close();
+            this.log('info', 'SSE client disconnected', { sessionId });
+            try {
+                await sessionServer.close();
+            }
+            catch {
+                // Ignore errors during cleanup (transport already closed)
+            }
         };
         transport.onerror = (error) => {
             this.log('warn', 'SSE transport error', {
@@ -1568,184 +1738,42 @@ export class PhotonServer {
      * This duplicates handlers from the main server to each session
      */
     setupSessionHandlers(sessionServer) {
-        // Handle tools/list
+        this.logClientCapabilities(sessionServer);
+        const sseSessionKey = `sse-${this.daemonName}`;
+        const ctx = {
+            server: sessionServer,
+            getInstanceName: () => this.sseInstanceNames.get(sseSessionKey),
+            setInstanceName: (name) => {
+                this.sseInstanceNames.set(sseSessionKey, name);
+            },
+            sessionId: sseSessionKey,
+        };
         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;
-                }),
-            };
+            return this.handleListTools(ctx);
         });
-        // 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;
+                return await this.handleCallTool(ctx, request);
             }
             catch (error) {
+                const { name: toolName, arguments: args } = request.params;
                 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,
-                        }))
-                        : [],
-                })),
-            };
+            return this.handleListPrompts();
         });
-        // 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)}`);
-            }
+            return this.handleGetPrompt(request);
         });
-        // 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 };
+            return this.handleListResources(ctx);
         });
-        // 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,
-                })),
-            };
+            return this.handleListResourceTemplates();
         });
-        // 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);
+            return this.handleReadResource(request);
         });
     }
     /**
@@ -1852,9 +1880,26 @@ export class PhotonServer {
         // Standard theme handling
         if (m.params && m.params.theme) {
           currentTheme = m.params.theme;
-          document.documentElement.classList.remove('light', 'dark');
+          document.documentElement.classList.remove('light', 'dark', 'light-theme');
           document.documentElement.classList.add(m.params.theme);
           document.documentElement.setAttribute('data-theme', m.params.theme);
+          // Apply theme token CSS variables (matching platform-compat applyThemeTokens)
+          if (m.params.styles && m.params.styles.variables) {
+            var root = document.documentElement;
+            var vars = m.params.styles.variables;
+            for (var key in vars) { root.style.setProperty(key, vars[key]); }
+          }
+          // Apply background/text colors to match platform-compat bridge
+          if (m.params.theme === 'light') {
+            document.documentElement.classList.add('light-theme');
+            document.documentElement.style.colorScheme = 'light';
+            document.documentElement.style.backgroundColor = '#ffffff';
+            if (document.body) { document.body.style.backgroundColor = '#ffffff'; document.body.style.color = '#1a1a1a'; }
+          } else {
+            document.documentElement.style.colorScheme = 'dark';
+            document.documentElement.style.backgroundColor = '#0d0d0d';
+            if (document.body) { document.body.style.backgroundColor = '#0d0d0d'; document.body.style.color = '#e6e6e6'; }
+          }
           themeListeners.forEach(function(cb) { cb(currentTheme); });
         }
 
@@ -2068,10 +2113,24 @@ export class PhotonServer {
   var initId = generateCallId();
   pendingCalls[initId] = {
     resolve: function(result) {
-      // Apply theme from host context
+      // Apply theme from host context (matching platform-compat bridge)
       if (result.hostContext && result.hostContext.theme) {
+        currentTheme = result.hostContext.theme;
+        document.documentElement.classList.remove('light', 'dark', 'light-theme');
         document.documentElement.classList.add(result.hostContext.theme);
         document.documentElement.setAttribute('data-theme', result.hostContext.theme);
+        // Apply theme token CSS variables from host context
+        if (result.hostContext.styles && result.hostContext.styles.variables) {
+          var root = document.documentElement;
+          var vars = result.hostContext.styles.variables;
+          for (var key in vars) { root.style.setProperty(key, vars[key]); }
+        }
+        if (result.hostContext.theme === 'light') {
+          document.documentElement.classList.add('light-theme');
+          document.documentElement.style.colorScheme = 'light';
+        } else {
+          document.documentElement.style.colorScheme = 'dark';
+        }
       }
       // Complete handshake
       postToHost({ jsonrpc: '2.0', method: 'ui/notifications/initialized', params: {} });
@@ -2101,7 +2160,7 @@ export class PhotonServer {
 </script>`;
     }
     /**
-     * Handle legacy photon:// asset read
+     * Handle photon:// asset read (Beam format)
      */
     async handleAssetRead(uri, assetMatch) {
         const [, _photonName, assetType, assetId] = assetMatch;
@@ -2242,15 +2301,15 @@ export class PhotonServer {
         try {
             await this.server.notification(payload);
         }
-        catch {
-            // ignore
+        catch (e) {
+            this.log('debug', 'Notification send failed', { error: getErrorMessage(e) });
         }
         for (const session of this.sseSessions.values()) {
             try {
                 await session.server.notification(payload);
             }
-            catch {
-                // ignore session errors
+            catch (e) {
+                this.log('debug', 'Session notification failed', { error: getErrorMessage(e) });
             }
         }
     }
@@ -2298,23 +2357,6 @@ export class PhotonServer {
             this.lastReloadError = undefined;
             // Send list_changed notifications to inform client of updates
             await this.notifyListsChanged();
-            // 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');
         }