@portel/photon 1.18.0 → 1.19.0

package/dist/server.js

@@ -105,7 +105,8 @@ class BeamCompatTransport {
         }
         // Otherwise push to SSE stream if connected
         if (this.sseResponse && !this.sseResponse.writableEnded) {
-            this.sseResponse.write(`data: ${JSON.stringify(message)}\n\n`);
+            const id = message.id ?? crypto.randomUUID();
+            this.sseResponse.write(`event: message\nid: ${id}\ndata: ${JSON.stringify(message)}\n\n`);
         }
     }
     async handleHTTP(req, res, url) {
@@ -204,7 +205,10 @@ class BeamCompatTransport {
             // Notifications have no id — fire-and-forget
             if (parsed.id === undefined) {
                 this.onmessage?.(parsed, { sessionId: this.sessionId });
-                res.writeHead(202);
+                res.writeHead(202, {
+                    'Access-Control-Allow-Origin': '*',
+                    'Mcp-Session-Id': this.sessionId,
+                });
                 res.end();
                 return;
             }
@@ -224,11 +228,11 @@ class BeamCompatTransport {
         }
         // DELETE — session termination (spec compliance)
         if (req.method === 'DELETE') {
-            res.writeHead(200);
+            res.writeHead(200, { 'Access-Control-Allow-Origin': '*' });
             res.end();
             return;
         }
-        res.writeHead(405);
+        res.writeHead(405, { 'Access-Control-Allow-Origin': '*' });
         res.end('Method not allowed');
     }
 }
@@ -309,10 +313,14 @@ 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' }), options.workingDir);
+        const loaderVerbose = (baseLoggerOptions.level ?? 'info') !== 'warn' &&
+            (baseLoggerOptions.level ?? 'info') !== 'error';
+        this.loader = new PhotonLoader(loaderVerbose, this.logger.child({ component: 'photon-loader', scope: 'loader' }), options.workingDir);
         // Create MCP server instance
+        // When channelMode is set, declare claude/channel capability and use photon name as server name
+        const serverName = options.channelMode && options.channelName ? options.channelName : 'photon-mcp';
         this.server = new Server({
-            name: 'photon-mcp',
+            name: serverName,
             version: PHOTON_VERSION,
         }, {
             capabilities: {
@@ -335,7 +343,23 @@ export class PhotonServer {
                 },
                 // Note: Server doesn't declare elicitation capability - that's a client capability
                 // The server uses elicitInput() when the client has elicitation support
+                //
+                // Channel capabilities — declare only the protocols specified by @channel tag.
+                // e.g. @channel claude → { 'claude/channel': {}, 'claude/channel/permission': {} }
+                ...(options.channelMode && options.channelTargets?.length
+                    ? {
+                        experimental: Object.fromEntries(options.channelTargets.flatMap((t) => [
+                            [`${t}/channel`, {}],
+                            [`${t}/channel/permission`, {}],
+                        ])),
+                    }
+                    : {}),
             },
+            ...(options.channelMode && options.channelInstructions
+                ? {
+                    instructions: options.channelInstructions,
+                }
+                : {}),
         });
         // Set up protocol handlers
         this.setupHandlers();
@@ -466,6 +490,62 @@ export class PhotonServer {
             return true;
         return false;
     }
+    /**
+     * Get the channel notification method for the connected client.
+     * Each client uses its own notification namespace under the MCP experimental extension point.
+     * Returns undefined if the client is unknown or doesn't support channels.
+     */
+    /**
+     * Get the notification methods for all declared channel targets.
+     * Each target (e.g. 'claude') maps to its notification method.
+     */
+    getChannelNotificationMethods() {
+        const targets = this.options.channelTargets || [];
+        // Each target's notification method follows the pattern: notifications/{target}/channel
+        return targets.map((t) => `notifications/${t}/channel`);
+    }
+    /**
+     * Handle permission request from the client (e.g. Claude Code asking "Allow tool X?").
+     * Forwards to the photon instance via channel._dispatchPermission().
+     */
+    handlePermissionRequest(params) {
+        if (!params?.request_id || !params?.tool_name)
+            return;
+        const request = {
+            request_id: params.request_id,
+            tool_name: params.tool_name,
+            description: params.description || '',
+            input_preview: params.input_preview || '',
+        };
+        this.log('info', `Permission request: ${request.tool_name} (${request.request_id})`);
+        // Dispatch to the photon instance's permission handler
+        const instance = this.mcp;
+        if (instance?.channel?._dispatchPermission) {
+            instance.channel._dispatchPermission(request);
+        }
+    }
+    /**
+     * Send a permission response back to the client.
+     * Called by the photon instance (via this.channel.respond) when the user approves/denies.
+     */
+    respondToPermission(response) {
+        const targets = this.options.channelTargets || [];
+        for (const target of targets) {
+            const notification = {
+                method: `notifications/${target}/channel/permission`,
+                params: {
+                    request_id: response.request_id,
+                    behavior: response.behavior,
+                },
+            };
+            this.server.notification(notification).catch((e) => {
+                this.log('debug', 'Permission response failed', { error: getErrorMessage(e) });
+            });
+            for (const session of Array.from(this.sseSessions.values())) {
+                session.server.notification(notification).catch(() => { });
+            }
+        }
+    }
     /**
      * Log client identity and capabilities for debugging tier detection
      */
@@ -1887,6 +1967,8 @@ export class PhotonServer {
                 const metadata = await extractor.extractFullMetadata();
                 const isStateful = metadata.stateful;
                 // Start daemon for stateful photons (enables cross-client communication)
+                // Channel mode also uses the daemon — the singleton instance holds the
+                // bot connection, and multiple MCP clients subscribe to its events
                 if (isStateful) {
                     const photonName = metadata.name;
                     this.daemonName = photonName; // Store for subscription
@@ -1921,7 +2003,9 @@ export class PhotonServer {
                     this.mcp = await this.loader.loadFile(this.options.filePath);
                 }
             }
-            // Subscribe to daemon channels for cross-process notifications
+            // Subscribe to daemon channels for cross-process notifications.
+            // In channel mode, handleChannelMessage intercepts 'channel-push' events
+            // and translates them to notifications/claude/channel for the connected client.
             await this.subscribeToChannels();
             // Start with the appropriate transport
             const transport = this.options.transport || 'stdio';
@@ -1982,6 +2066,40 @@ export class PhotonServer {
         if (process.env.PHOTON_DEBUG_EVENTS === '1') {
             console.error(`[PHOTON-SERVER] Received daemon message on ${String(msg.channel)}: event=${String(msg.event)}`);
         }
+        // Channel permission responses — photon called this.channel.respond()
+        if (this.options.channelMode && String(msg.channel).endsWith(':channel-permission-response')) {
+            const data = msg.data;
+            if (data?.request_id && data?.behavior) {
+                this.respondToPermission({
+                    request_id: data.request_id,
+                    behavior: data.behavior,
+                });
+            }
+            return;
+        }
+        // Channel events — translate to client-specific channel notifications.
+        // Each declared target (e.g. 'claude') gets its own notification method.
+        if (this.options.channelMode && String(msg.channel).endsWith(':channel-push')) {
+            const pushData = msg.data;
+            const methods = this.getChannelNotificationMethods();
+            if (methods.length === 0)
+                return;
+            const content = typeof pushData?.content === 'string' ? pushData.content : '';
+            const meta = pushData?.meta || {};
+            try {
+                for (const method of methods) {
+                    const notification = { method, params: { content, meta } };
+                    await this.server.notification(notification);
+                    for (const session of Array.from(this.sseSessions.values())) {
+                        await session.server.notification(notification);
+                    }
+                }
+            }
+            catch (e) {
+                this.log('debug', 'Channel notification failed', { error: getErrorMessage(e) });
+            }
+            return; // Don't also forward as a regular photon event
+        }
         // Use STANDARD notification with embedded photon data
         // Claude Desktop will forward this (it's a standard notification)
         // Our bridge extracts _photon and routes to the appropriate event handler
@@ -2031,9 +2149,15 @@ export class PhotonServer {
     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);
+            // Capture raw capabilities and client name from initialize request
+            if (message?.method === 'initialize' && message?.params) {
+                if (message.params.capabilities) {
+                    this.rawClientCapabilities.set(targetServer, message.params.capabilities);
+                }
+            }
+            // Intercept channel permission requests from the client
+            if (this.options.channelMode && message?.method?.endsWith('/channel/permission_request')) {
+                this.handlePermissionRequest(message.params);
             }
             origOnMessage?.(message, extra);
         };
@@ -2052,15 +2176,16 @@ export class PhotonServer {
      */
     async startSSE() {
         const port = this.options.port || 3000;
-        const useStreamableHTTP = !!this.options.embeddedAssets;
         const ssePath = '/mcp';
         const messagesPath = '/mcp/messages';
-        // For compiled binaries with Beam UI, use a minimal Streamable HTTP transport
-        // that matches what the Beam frontend sends:
-        //   POST /mcp  — JSON-RPC request, Accept: application/json → JSON response
-        //   GET  /mcp?sessionId=X — EventSource for server-to-client notifications
+        // Always use Streamable HTTP transport for SSE mode.
+        // The legacy SSE transport (endpoint event + /mcp/messages?sessionId=) is deprecated
+        // in the MCP spec and not supported by modern clients (e.g. llama.cpp).
+        // Streamable HTTP uses the standard protocol:
+        //   POST /mcp  — JSON-RPC request → JSON response
+        //   GET  /mcp  — SSE stream for server-to-client notifications
         let beamTransport = null;
-        if (useStreamableHTTP) {
+        {
             const photonName = this.mcp?.name || 'photon';
             beamTransport = new BeamCompatTransport(photonName, {
                 description: this.mcp?.description,
@@ -2132,7 +2257,7 @@ export class PhotonServer {
                     res.writeHead(204, {
                         'Access-Control-Allow-Origin': '*',
                         'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
-                        'Access-Control-Allow-Headers': 'Content-Type, Accept, Mcp-Session-Id',
+                        'Access-Control-Allow-Headers': 'Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version',
                         'Access-Control-Expose-Headers': 'Mcp-Session-Id',
                     });
                     res.end();
@@ -2499,17 +2624,7 @@ export class PhotonServer {
         });
         await new Promise((resolve) => {
             this.httpServer.listen(port, () => {
-                this.log('info', `${this.mcp.name} MCP server listening`, {
-                    transport: 'sse',
-                    port,
-                    devMode: this.devMode,
-                });
-                this.log('debug', 'SSE endpoints ready', {
-                    baseUrl: `http://localhost:${port}`,
-                    ssePath,
-                    messagesPath,
-                    playground: this.devMode ? `http://localhost:${port}/playground` : undefined,
-                });
+                process.stdout.write(`⚡ ${this.mcp.name} → http://localhost:${port}${ssePath}\n`);
                 resolve();
             });
         });