@portel/photon 1.8.4 → 1.10.0

package/dist/server.js

@@ -12,7 +12,7 @@ import * as fs from 'fs/promises';
 import { createServer } from 'node:http';
 import { URL } from 'node:url';
 import { PhotonLoader } from './loader.js';
-import { generateExecutionId, } from '@portel/photon-core';
+import { generateExecutionId } from '@portel/photon-core';
 import { createSDKMCPClientFactory } from '@portel/photon-core';
 import { PHOTON_VERSION } from './version.js';
 import { createLogger } from './shared/logger.js';
@@ -22,7 +22,8 @@ import { generatePlaygroundHTML } from './auto-ui/playground-html.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';
+import { isLocalRequest, readBody, setSecurityHeaders } from './shared/security.js';
+import { audit } from './shared/audit.js';
 export class HotReloadDisabledError extends Error {
     constructor(message) {
         super(message);
@@ -49,6 +50,19 @@ export class PhotonServer {
     sseInstanceNames = new Map();
     /** Whether client capabilities have been logged (one-time on first tools/list) */
     clientCapabilitiesLogged = false;
+    /**
+     * Raw client capabilities captured from the initialize request BEFORE Zod parsing.
+     *
+     * The MCP SDK uses Zod to validate incoming requests, which strips unknown fields
+     * from ClientCapabilities. Notably, `extensions` (protocol 2025-11-25+) is not in
+     * the SDK's Zod schema yet, so `getClientCapabilities()` returns an object without
+     * it. Real clients like Claude Desktop and ChatGPT send UI capability under
+     * `extensions`, not `experimental`. We intercept the raw JSON-RPC message to
+     * capture the full capabilities before Zod strips them.
+     *
+     * Key: Server instance → Value: raw capabilities object from initialize request
+     */
+    rawClientCapabilities = new WeakMap();
     currentStatus = {
         type: 'info',
         message: 'Ready',
@@ -85,7 +99,7 @@ export class PhotonServer {
             baseLoggerOptions.scope = this.devMode ? 'dev' : 'runtime';
         }
         this.logger = createLogger(baseLoggerOptions);
-        this.loader = new PhotonLoader(true, this.logger.child({ component: 'photon-loader', scope: 'loader' }));
+        this.loader = new PhotonLoader(true, this.logger.child({ component: 'photon-loader', scope: 'loader' }), options.workingDir);
         // Create MCP server instance
         this.server = new Server({
             name: 'photon-mcp',
@@ -117,15 +131,6 @@ export class PhotonServer {
     log(level, message, meta) {
         this.logger.log(level, message, meta);
     }
-    /**
-     * Detect UI format based on client capabilities
-     *
-     * All clients use the MCP Apps standard (SEP-1865) ui:// format.
-     * Text-only clients have no UI support.
-     */
-    getUIFormat() {
-        return 'sep-1865';
-    }
     /**
      * Build UI resource URI based on detected format
      */
@@ -161,32 +166,38 @@ 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']);
+    static MCP_UI_CAPABILITY = 'io.modelcontextprotocol/ui';
     /**
      * 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
+     * Looks for the "io.modelcontextprotocol/ui" capability in the client's
+     * initialize handshake. Any MCP client that advertises this capability
+     * gets rich UI responses — Claude Desktop, ChatGPT, MCPJam, etc.
+     *
+     * The capability may appear under `experimental` (older SDK types) or
+     * `extensions` (protocol version 2025-11-25+). We check both so it
+     * just works regardless of which field the client uses.
      *
-     * Basic/unknown clients get text-only responses (no structuredContent, no _meta.ui).
+     * Beam is special-cased because it's our own SSE transport where the
+     * capability is implicit.
      */
     clientSupportsUI(server) {
         const targetServer = server || this.server;
-        // 1. Check capabilities (official MCP Apps negotiation)
+        // Check SDK-parsed capabilities (works for `experimental` which is in the Zod schema)
         const capabilities = targetServer.getClientCapabilities();
-        if (capabilities?.experimental?.['io.modelcontextprotocol/ui']) {
+        if (capabilities?.experimental?.[PhotonServer.MCP_UI_CAPABILITY]) {
             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;
+        // Check raw capabilities captured before Zod parsing (needed for `extensions`
+        // which the SDK's Zod schema strips — Claude Desktop and ChatGPT use this field)
+        const raw = this.rawClientCapabilities.get(targetServer);
+        if (raw?.extensions?.[PhotonServer.MCP_UI_CAPABILITY]) {
+            return true;
         }
+        // Beam is our own transport — UI support is implicit
+        const clientInfo = targetServer.getClientVersion();
+        if (clientInfo?.name === 'beam')
+            return true;
         return false;
     }
     /**
@@ -415,9 +426,16 @@ export class PhotonServer {
             return { tools: [] };
         }
         const tools = this.mcp.tools.map((tool) => {
+            // Append deprecation notice to tool description if tagged
+            let description = tool.description;
+            const deprecated = tool.deprecated;
+            if (deprecated) {
+                const notice = typeof deprecated === 'string' ? deprecated : 'This tool is deprecated.';
+                description = `[DEPRECATED: ${notice}] ${description}`;
+            }
             const toolDef = {
                 name: tool.name,
-                description: tool.description,
+                description,
                 inputSchema: tool.inputSchema,
             };
             const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name);
@@ -461,6 +479,7 @@ export class PhotonServer {
                 photonPath: this.options.filePath,
                 sessionId: ctx.sessionId,
                 instanceName: ctx.getInstanceName(),
+                workingDir: this.options.workingDir,
             };
             // Elicitation-based instance selection when _use called without name
             if (toolName === '_use' &&
@@ -518,7 +537,8 @@ export class PhotonServer {
             const result = await sendCommand(this.daemonName, toolName, (args || {}), sendOpts);
             // Track instance name after successful _use
             if (toolName === '_use') {
-                ctx.setInstanceName(String(args?.name || ''));
+                const nameVal = args?.name;
+                ctx.setInstanceName(typeof nameVal === 'string' ? nameVal : '');
             }
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -529,17 +549,33 @@ export class PhotonServer {
         // 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(() => {
+                publishToChannel(this.daemonName, emit.channel, emit, this.options.workingDir).catch(() => {
                     // Ignore publish errors - daemon may not be running
                 });
             }
         };
         const tool = this.mcp.tools.find((t) => t.name === toolName);
         const outputFormat = tool?.outputFormat;
+        const startTime = Date.now();
         const result = await this.loader.executeTool(this.mcp, toolName, args || {}, {
             inputProvider,
             outputHandler,
         });
+        const durationMs = Date.now() - startTime;
+        const transport = this.options.transport || 'stdio';
+        this.log('info', `${toolName} completed in ${durationMs}ms`, {
+            durationMs,
+            photon: this.mcp?.name,
+            transport,
+        });
+        audit({
+            ts: new Date().toISOString(),
+            event: 'tool_call',
+            photon: this.mcp?.name,
+            method: toolName,
+            client: transport,
+            durationMs,
+        });
         const isStateful = result && typeof result === 'object' && result._stateful === true;
         const actualResult = isStateful ? result.result : result;
         // Build content with optional mimeType annotation
@@ -716,7 +752,7 @@ 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, this.options.workingDir).catch(() => { });
                         }
                     };
                     this.loader
@@ -1052,41 +1088,14 @@ export class PhotonServer {
      * 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 { MarketplaceManager } = 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) {
-                    // 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');
-                }
-            }
-        }
+        const { photonPath: filePath } = await manager.installPhoton(result, photonName, workingDir);
         // Update options and load
         this.options.filePath = filePath;
         this.options.unresolvedPhoton = undefined;
@@ -1152,7 +1161,7 @@ export class PhotonServer {
             const inputProvider = this.createMCPInputProvider();
             const outputHandler = (emit) => {
                 if (this.daemonName && emit?.channel) {
-                    publishToChannel(this.daemonName, emit.channel, emit).catch((e) => {
+                    publishToChannel(this.daemonName, emit.channel, emit, this.options.workingDir).catch((e) => {
                         this.log('debug', 'Publish to channel failed', { error: getErrorMessage(e) });
                     });
                 }
@@ -1259,8 +1268,8 @@ export class PhotonServer {
             // 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);
-            });
+                void this.handleChannelMessage(message);
+            }, { workingDir: this.options.workingDir });
             this.channelUnsubscribers.push(unsubscribe);
             this.log('info', `Subscribed to daemon channel: ${this.daemonName}:*`);
         }
@@ -1302,8 +1311,8 @@ export class PhotonServer {
         catch (e) {
             this.log('debug', 'Notification send failed', { error: getErrorMessage(e) });
         }
-        // Also send to SSE sessions
-        for (const session of this.sseSessions.values()) {
+        // Also send to SSE sessions — snapshot to avoid live-iterator + await issues
+        for (const session of Array.from(this.sseSessions.values())) {
             try {
                 await session.server.notification(payload);
             }
@@ -1312,11 +1321,30 @@ export class PhotonServer {
             }
         }
     }
+    /**
+     * Intercept a transport to capture raw client capabilities before Zod strips them.
+     *
+     * The MCP SDK's Zod schema for ClientCapabilities doesn't include `extensions`
+     * (protocol 2025-11-25+), so getClientCapabilities() returns an object without it.
+     * We intercept the transport's onmessage to capture the raw `initialize` request
+     * and store capabilities before Zod parsing occurs.
+     */
+    interceptTransportForRawCapabilities(transport, targetServer) {
+        const origOnMessage = transport.onmessage;
+        transport.onmessage = (message, extra) => {
+            // Capture raw capabilities from initialize request
+            if (message?.method === 'initialize' && message?.params?.capabilities) {
+                this.rawClientCapabilities.set(targetServer, message.params.capabilities);
+            }
+            origOnMessage?.(message, extra);
+        };
+    }
     /**
      * Start server with stdio transport
      */
     async startStdio() {
         const transport = new StdioServerTransport();
+        this.interceptTransportForRawCapabilities(transport, this.server);
         await this.server.connect(transport);
         this.log('info', `Server started: ${this.mcp.name}`);
     }
@@ -1327,263 +1355,269 @@ export class PhotonServer {
         const port = this.options.port || 3000;
         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;
-            }
-            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) }));
-                    }
+        this.httpServer = createServer((req, res) => {
+            void (async () => {
+                // Security: set standard security headers on all responses
+                setSecurityHeaders(res);
+                if (!req.url) {
+                    res.writeHead(400).end('Missing URL');
                     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',
+                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',
                     });
-                    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: `ui://${this.mcp.name}/${linkedUI.id}` }
-                                : null,
-                        };
-                    }) || [];
-                    res.end(JSON.stringify({ tools }));
+                    res.end();
                     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()));
+                // SSE connection endpoint
+                if (req.method === 'GET' && url.pathname === ssePath) {
+                    await this.handleSSEConnection(res, messagesPath);
                     return;
                 }
-                if (req.method === 'GET' && url.pathname === '/api/status-stream') {
-                    this.handleStatusStream(req, res);
+                // Message posting endpoint
+                if (req.method === 'POST' && url.pathname === messagesPath) {
+                    await this.handleSSEMessage(req, res, url);
                     return;
                 }
-            }
-            // API: Call tool
-            if (req.method === 'POST' && url.pathname === '/api/call') {
-                // 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');
-                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);
+                // 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({
-                        success: true,
-                        data: isStateful ? result.result : result,
+                        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,
                     }));
-                }
-                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', `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 () => {
-                    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();
+                // 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;
                     }
-                    catch (error) {
-                        const message = getErrorMessage(error);
-                        const errorPayload = {
-                            jsonrpc: '2.0',
-                            error: { code: -32000, message },
-                        };
-                        if (requestId) {
-                            errorPayload.id = requestId;
+                    // 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) }));
                         }
-                        sendMessage(errorPayload);
-                        res.end();
+                        return;
                     }
-                });
-                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');
+                    // 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: `ui://${this.mcp.name}/${linkedUI.id}` }
+                                    : null,
+                            };
+                        }) || [];
+                        res.end(JSON.stringify({ tools }));
+                        return;
+                    }
+                    if (req.method === 'GET' && url.pathname === '/api/status') {
                         res.writeHead(200, {
-                            'Content-Type': 'text/html',
+                            'Content-Type': 'application/json',
                             'Access-Control-Allow-Origin': '*',
                         });
-                        res.end(content);
+                        res.end(JSON.stringify(this.buildStatusSnapshot()));
                         return;
                     }
-                    catch {
-                        // Fall through to 404
+                    if (req.method === 'GET' && url.pathname === '/api/status-stream') {
+                        this.handleStatusStream(req, res);
+                        return;
                     }
                 }
-                res.writeHead(404).end('UI not found');
-                return;
-            }
-            res.writeHead(404).end('Not Found');
+                // API: Call tool
+                if (req.method === 'POST' && url.pathname === '/api/call') {
+                    // 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');
+                    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', `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', () => {
+                        void (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, this.options.workingDir).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 });
@@ -1610,7 +1644,8 @@ export class PhotonServer {
      * List all photons in the .photon directory
      */
     async listAllPhotons() {
-        const { listPhotonFiles, DEFAULT_PHOTON_DIR } = await import('./path-resolver.js');
+        const { listPhotonFiles } = await import('./path-resolver.js');
+        const { getDefaultContext } = await import('./context.js');
         const photonFiles = await listPhotonFiles();
         const photons = await Promise.all(photonFiles.map(async (file) => {
             try {
@@ -1619,7 +1654,7 @@ export class PhotonServer {
                 return {
                     name: mcp.name,
                     description: mcp.description,
-                    file: file.replace(DEFAULT_PHOTON_DIR + '/', ''),
+                    file: file.replace(getDefaultContext().baseDir + '/', ''),
                     tools: mcp.tools.map((tool) => ({
                         name: tool.name,
                         description: tool.description,
@@ -1664,24 +1699,27 @@ export class PhotonServer {
         this.setupSessionHandlers(sessionServer);
         // Create SSE transport
         const transport = new SSEServerTransport(messagesPath, res);
+        this.interceptTransportForRawCapabilities(transport, sessionServer);
         const sessionId = transport.sessionId;
         // Store session
         this.sseSessions.set(sessionId, { server: sessionServer, transport });
         // Clean up on close (guard against recursive close:
         // onclose → sessionServer.close() → transport.close() → onclose)
         let closing = false;
-        transport.onclose = async () => {
+        transport.onclose = () => {
             if (closing)
                 return;
             closing = true;
             this.sseSessions.delete(sessionId);
             this.log('info', 'SSE client disconnected', { sessionId });
-            try {
-                await sessionServer.close();
-            }
-            catch {
-                // Ignore errors during cleanup (transport already closed)
-            }
+            void (async () => {
+                try {
+                    await sessionServer.close();
+                }
+                catch {
+                    // Ignore errors during cleanup (transport already closed)
+                }
+            })();
         };
         transport.onerror = (error) => {
             this.log('warn', 'SSE transport error', {
@@ -1945,15 +1983,17 @@ export class PhotonServer {
         if (i >= 0) resultListeners.splice(i, 1);
       };
     },
-    callTool: function(name, args) {
+    callTool: function(name, args, opts) {
       var callId = generateCallId();
       return new Promise(function(resolve, reject) {
         pendingCalls[callId] = { resolve: resolve, reject: reject };
+        var a = args || {};
+        if (opts && opts.instance !== undefined) { a = Object.assign({}, a, { _targetInstance: opts.instance }); }
         postToHost({
           jsonrpc: '2.0',
           id: callId,
           method: 'tools/call',
-          params: { name: name, arguments: args || {} }
+          params: { name: name, arguments: a }
         });
         setTimeout(function() {
           if (pendingCalls[callId]) {
@@ -1963,7 +2003,7 @@ export class PhotonServer {
         }, 30000);
       });
     },
-    invoke: function(name, args) { return window.photon.callTool(name, args); },
+    invoke: function(name, args, opts) { return window.photon.callTool(name, args, opts); },
     onEmit: function(cb) {
       emitListeners.push(cb);
       return function() {
@@ -2225,8 +2265,18 @@ export class PhotonServer {
             if (this.mcpClientFactory) {
                 await this.mcpClientFactory.disconnect();
             }
-            // Close SSE sessions
-            for (const [_sessionId, session] of this.sseSessions) {
+            // Unsubscribe daemon channels
+            for (const unsubscribe of this.channelUnsubscribers) {
+                try {
+                    unsubscribe();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            this.channelUnsubscribers = [];
+            // Close SSE sessions — snapshot to avoid live-iterator + await issues
+            for (const session of Array.from(this.sseSessions.values())) {
                 await session.server.close();
             }
             this.sseSessions.clear();
@@ -2304,7 +2354,8 @@ export class PhotonServer {
         catch (e) {
             this.log('debug', 'Notification send failed', { error: getErrorMessage(e) });
         }
-        for (const session of this.sseSessions.values()) {
+        // Snapshot to avoid live-iterator + await issues
+        for (const session of Array.from(this.sseSessions.values())) {
             try {
                 await session.server.notification(payload);
             }