@portel/photon 1.29.0 → 1.31.1

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -82,6 +82,17 @@ function uiSiblingMime(ext) {
             return 'application/octet-stream';
     }
 }
+function findFreePort(preferred = 0) {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.listen(preferred, () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : preferred;
+            srv.close((err) => (err ? reject(err) : resolve(port)));
+        });
+        srv.on('error', reject);
+    });
+}
 class BeamCompatTransport {
     photonName;
     photonMeta;
@@ -143,14 +154,16 @@ class BeamCompatTransport {
                 message.result.tools.push(...subTools);
             }
         }
-        // If there's a pending HTTP request waiting for a response, deliver it
-        if (this.pendingResponse) {
+        // JSON-RPC notifications have no 'id' — route to SSE only, never to pendingResponse.
+        // Responses have 'id' + 'result'/'error'. Server-initiated requests have 'id' + 'method'.
+        const isResponse = message.id !== undefined && message.id !== null && !message.method;
+        if (isResponse && this.pendingResponse) {
             const resolve = this.pendingResponse;
             this.pendingResponse = null;
             resolve(message);
             return;
         }
-        // Otherwise push to SSE stream if connected
+        // Notifications and server-initiated requests go to the SSE stream
         if (this.sseResponse && !this.sseResponse.writableEnded) {
             const id = message.id ?? crypto.randomUUID();
             this.sseResponse.write(`event: message\nid: ${id}\ndata: ${JSON.stringify(message)}\n\n`);
@@ -185,11 +198,17 @@ class BeamCompatTransport {
             }, 15000);
             req.on('close', () => {
                 clearInterval(keepalive);
-                this.sseResponse = null;
+                // Only clear if this response is still the active SSE stream.
+                // A newer GET may have already replaced it — don't overwrite that.
+                if (this.sseResponse === res) {
+                    this.sseResponse = null;
+                }
             });
             res.on('error', () => {
                 clearInterval(keepalive);
-                this.sseResponse = null;
+                if (this.sseResponse === res) {
+                    this.sseResponse = null;
+                }
             });
             return;
         }
@@ -540,7 +559,7 @@ export class PhotonServer {
     queueNotification(notification) {
         this._notifyQueue = this._notifyQueue
             .then(() => this.server?.notification(notification))
-            .catch(() => { });
+            .catch((err) => this.logger.debug('Failed to send notification', { error: getErrorMessage(err) }));
     }
     /**
      * Create an MCP-aware input provider for generator ask yields
@@ -1212,6 +1231,12 @@ export class PhotonServer {
             const uiMeta = this.resourceServer.buildUIToolMeta(this.mcp.name, linkedUI.id);
             response._meta = { ...response._meta, ...uiMeta };
         }
+        // For SSE/Streamable-HTTP transports: flush the notification queue before
+        // returning so that progress/status notifications are delivered via the GET
+        // SSE stream BEFORE the HTTP POST response body is written. Without this, the
+        // client receives the tool result, deletes its _progressHandlers entry, and then
+        // silently drops any notifications that arrive later on the SSE stream.
+        await this._notifyQueue;
         return response;
     }
     handleListPrompts() {
@@ -1885,13 +1910,36 @@ export class PhotonServer {
             // In channel mode, ChannelManager intercepts 'channel-push' events
             // and translates them to notifications/claude/channel for the connected client.
             await this.channelManager.subscribeToChannels();
-            // Start with the appropriate transport
+            // Announce web capability when the photon has @get / defined.
+            // HTTP mode: the existing HTTP server already handles web routes at their
+            // declared paths, so we expose the server's own base URL.
+            // STDIO stateful: we spin up a companion HTTP server to host those routes
+            // and expose its URL. Stateless photons cannot have a companion server.
             const transport = this.options.transport || 'stdio';
+            const photonWithMeta = this.mcp;
+            const webRootRoute = photonWithMeta?._httpRoutes?.find((r) => r.method === 'GET' && r.path === '/');
             if (transport === 'sse') {
+                if (webRootRoute) {
+                    const httpPort = Number(this.options.port) || 3000;
+                    const webDescription = photonWithMeta?.description || `${photonWithMeta?.name} web interface`;
+                    this.server.registerCapabilities({
+                        web: { url: `http://localhost:${httpPort}`, description: webDescription },
+                    });
+                }
                 await this.startSSE();
             }
             else {
-                await this.startStdio();
+                if (webRootRoute && photonStateful) {
+                    const webPort = await findFreePort(Number(this.options.port) || 0);
+                    const webDescription = photonWithMeta?.description || `${photonWithMeta?.name} web interface`;
+                    this.server.registerCapabilities({
+                        web: { url: `http://localhost:${webPort}`, description: webDescription },
+                    });
+                    await this.startStdio(webPort);
+                }
+                else {
+                    await this.startStdio();
+                }
             }
             // In dev mode, we could set up file watching here
             if (this.options.devMode) {
@@ -1907,22 +1955,116 @@ export class PhotonServer {
         }
     }
     /**
-     * Start server with stdio transport
+     * Start server with stdio transport.
+     * @param webPort - when set, start a companion HTTP server on this port
+     *                  to serve @get/@post web routes for stateful photons.
      */
-    async startStdio() {
+    async startStdio(webPort) {
         const transport = new StdioServerTransport();
         // Wrap transport.send with a write mutex to prevent concurrent generators
         // from interleaving JSON-RPC messages on stdout
         const originalSend = transport.send.bind(transport);
         let writeChain = Promise.resolve();
         transport.send = (message) => {
-            const p = writeChain.then(() => originalSend(message)).catch(() => { });
+            const p = writeChain
+                .then(() => originalSend(message))
+                .catch((err) => this.logger.debug('STDIO send failed', { error: getErrorMessage(err) }));
             writeChain = p;
             return p;
         };
         this.capabilityNegotiator.interceptTransportForRawCapabilities(transport, this.server, (msg) => this.channelManager.interceptPermissionRequest(msg));
         await this.server.connect(transport);
         this.log('info', `Server started: ${this.mcp.name}`);
+        if (webPort) {
+            const webServer = createServer((req, res) => {
+                void this.handleWebRoute(req, res);
+            });
+            await new Promise((resolve, reject) => {
+                webServer.listen(webPort, () => resolve());
+                webServer.on('error', reject);
+            });
+            this.log('info', `Web UI: http://localhost:${webPort}`);
+        }
+    }
+    /**
+     * Dispatch an incoming HTTP request to the photon's @get/@post web routes.
+     * Used by the companion HTTP server that runs alongside STDIO stateful photons.
+     */
+    async handleWebRoute(req, res) {
+        setSecurityHeaders(res);
+        if (!req.url) {
+            res.writeHead(400).end('Missing URL');
+            return;
+        }
+        const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+        const corsOrigin = getCorsOrigin(req);
+        if (req.method === 'OPTIONS') {
+            const preflightHeaders = {
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Accept',
+            };
+            if (corsOrigin)
+                preflightHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+            res.writeHead(204, preflightHeaders).end();
+            return;
+        }
+        const httpRoutes = this.mcp?._httpRoutes;
+        if (httpRoutes?.length && req.method) {
+            const route = httpRoutes.find((r) => r.method === req.method && r.path === url.pathname);
+            if (route) {
+                const targetMcp = await this.resolveInstanceMcp(undefined);
+                const photonInstance = targetMcp?.instance;
+                const fn = photonInstance?.[route.handler];
+                if (typeof fn === 'function') {
+                    try {
+                        let bodyBuffer = Buffer.alloc(0);
+                        await new Promise((resolve) => {
+                            req.on('data', (chunk) => {
+                                bodyBuffer = Buffer.concat([bodyBuffer, chunk]);
+                            });
+                            req.on('end', resolve);
+                        });
+                        const webReq = new Request(url.toString(), {
+                            method: req.method,
+                            headers: req.headers,
+                            ...(req.method !== 'GET' && bodyBuffer.length > 0 ? { body: bodyBuffer } : {}),
+                        });
+                        const result = await fn.call(photonInstance, webReq);
+                        if (result instanceof Response) {
+                            const responseHeaders = {};
+                            result.headers.forEach((value, key) => {
+                                responseHeaders[key] = value;
+                            });
+                            if (corsOrigin)
+                                responseHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                            res.writeHead(result.status, responseHeaders);
+                            res.end(Buffer.from(await result.arrayBuffer()));
+                            return;
+                        }
+                        const { negotiateAccept } = await import('./format/registry.js');
+                        const { getDefaultRegistry } = await import('./format/seed.js');
+                        const acceptHeader = req.headers['accept'];
+                        const rendered = negotiateAccept({
+                            accept: typeof acceptHeader === 'string' ? acceptHeader : undefined,
+                            declaredFormat: route.format,
+                            value: result,
+                            registry: getDefaultRegistry(),
+                        });
+                        const negotiatedHeaders = { 'Content-Type': rendered.mime };
+                        if (corsOrigin)
+                            negotiatedHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                        res.writeHead(200, negotiatedHeaders);
+                        res.end(typeof rendered.body === 'string' ? rendered.body : Buffer.from(rendered.body));
+                        return;
+                    }
+                    catch (err) {
+                        res.writeHead(500).end(err?.message ?? 'Internal Server Error');
+                        return;
+                    }
+                }
+            }
+        }
+        res.writeHead(404).end('Not Found');
     }
     /**
      * Start server with SSE transport (HTTP)
@@ -1956,6 +2098,9 @@ export class PhotonServer {
                     continue;
                 const icon = loaded.icon || '⚡';
                 const stateful = !!loaded.stateful;
+                // ^^ getLoadedPhotons() returns the canonical PhotonClassExtended type;
+                // these two callsites still need the narrower runtime cast until
+                // the loader's return type widens to PhotonClassWithMeta.
                 const hasSettings = !!loaded.settingsSchema?.hasSettings;
                 // Convert PhotonTool[] to MCP tool format with UI linking
                 const uiAssets = loaded.assets?.ui || [];
@@ -2408,9 +2553,7 @@ export class PhotonServer {
                     if (req.method === 'GET' && url.pathname === '/api/diagnostics') {
                         const { PHOTON_VERSION } = await import('./version.js');
                         const photonName = this.mcp?.name || 'photon';
-                        const tools = this.mcp
-                            ? Object.keys(this.mcp._toolSchemas || {}).length
-                            : 0;
+                        const tools = this.mcp ? Object.keys(this.mcp._toolSchemas || {}).length : 0;
                         const diagHeaders = { 'Content-Type': 'application/json' };
                         if (corsOrigin)
                             diagHeaders['Access-Control-Allow-Origin'] = corsOrigin;
@@ -2729,6 +2872,15 @@ export class PhotonServer {
             method: 'notifications/resources/updated',
             params: { uri },
         });
+        // Mirror web capability onto the per-session server when the photon has web routes.
+        const sessionWebMeta = this.mcp?._httpRoutes?.find((r) => r.method === 'GET' && r.path === '/');
+        if (sessionWebMeta) {
+            const httpPort = Number(this.options.port) || 3000;
+            const webDescription = this.mcp?.description || `${this.mcp?.name} web interface`;
+            sessionServer.registerCapabilities({
+                web: { url: `http://localhost:${httpPort}`, description: webDescription },
+            });
+        }
         // Copy handlers to the session server
         this.setupSessionHandlers(sessionServer, sessionSink);
         // Create SSE transport