@portel/photon 1.7.0 → 1.8.1

package/dist/auto-ui/streamable-http-transport.js

@@ -124,6 +124,20 @@ function generateConfigurationSchema(photons) {
     }
     return schema;
 }
+/**
+ * Format a tool result for MCP content text.
+ * Mirrors server.ts formatResult(): strings returned as-is, objects/arrays JSON-stringified,
+ * other primitives converted via String().
+ */
+function formatResultText(result) {
+    if (result === undefined || result === null)
+        return 'Done';
+    if (typeof result === 'string')
+        return result;
+    if (typeof result === 'object')
+        return JSON.stringify(result, null, 2);
+    return String(result);
+}
 const handlers = {
     // ─────────────────────────────────────────────────────────────────────────────
     // Lifecycle
@@ -149,6 +163,7 @@ const handlers = {
                 },
                 capabilities: {
                     tools: { listChanged: true },
+                    prompts: { listChanged: true },
                     resources: { listChanged: true },
                 },
                 // SEP-1596 inspired: configuration schema for unconfigured photons
@@ -192,14 +207,14 @@ const handlers = {
     // Client notifies what resource they're viewing (for on-demand subscriptions)
     // photonId: hash of photon path (unique across servers)
     // itemId: whatever the photon uses to identify the item (e.g., board name)
-    // lastEventId: optional - for replay of missed events on reconnect
+    // lastTimestamp: optional - for delta sync of missed events on reconnect
     'beam/viewing': async (req, session, ctx) => {
         const params = req.params;
         const photonId = params?.photonId;
         const itemId = params?.itemId;
-        const lastEventId = params?.lastEventId;
+        const lastTimestamp = params?.lastTimestamp;
         if (photonId && itemId && ctx.subscriptionManager) {
-            ctx.subscriptionManager.onClientViewingBoard(session.id, photonId, itemId, lastEventId);
+            ctx.subscriptionManager.onClientViewingBoard(session.id, photonId, itemId, lastTimestamp);
         }
         // Notification - no response needed
         return { jsonrpc: '2.0' };
@@ -226,6 +241,7 @@ const handlers = {
                     'x-photon-description': photon.description,
                     'x-photon-icon': photon.icon,
                     'x-photon-internal': photon.internal,
+                    'x-photon-stateful': photon.stateful || false,
                     'x-photon-prompt-count': photon.promptCount ?? 0,
                     'x-photon-resource-count': photon.resourceCount ?? 0,
                     ...buildToolMetadataExtensions(method),
@@ -245,6 +261,33 @@ const handlers = {
                 });
             }
         }
+        // Add runtime-injected instance tools for stateful photons
+        for (const photon of ctx.photons) {
+            if (!photon.configured || !photon.stateful)
+                continue;
+            tools.push({
+                name: `${photon.name}/_use`,
+                description: `Switch to a named instance of ${photon.name}. Omit name to select interactively.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'Instance name (empty for default). Omit to select interactively.',
+                        },
+                    },
+                },
+                'x-photon-id': photon.id,
+                'x-photon-internal': true,
+            });
+            tools.push({
+                name: `${photon.name}/_instances`,
+                description: `List all available instances of ${photon.name}.`,
+                inputSchema: { type: 'object', properties: {} },
+                'x-photon-id': photon.id,
+                'x-photon-internal': true,
+            });
+        }
         // Add external MCP tools (from mcpServers in config.json)
         if (ctx.externalMCPs) {
             for (const mcp of ctx.externalMCPs) {
@@ -547,7 +590,7 @@ const handlers = {
                     jsonrpc: '2.0',
                     id: req.id,
                     result: {
-                        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        content: [{ type: 'text', text: formatResultText(result) }],
                         isError: false,
                     },
                 };
@@ -576,6 +619,134 @@ const handlers = {
         if (methodInfo?.outputFormat) {
             uiMetadata['x-output-format'] = methodInfo.outputFormat;
         }
+        // Stateful photons: route through daemon for shared instance across all clients
+        if (photonInfo?.stateful && photonInfo.path) {
+            try {
+                const { sendCommand, pingDaemon } = await import('../daemon/client.js');
+                const { isGlobalDaemonRunning, startGlobalDaemon } = await import('../daemon/manager.js');
+                // Ensure daemon is running
+                if (!isGlobalDaemonRunning()) {
+                    await startGlobalDaemon(true);
+                    // Wait for daemon readiness
+                    for (let i = 0; i < 10; i++) {
+                        await new Promise((r) => setTimeout(r, 500));
+                        if (await pingDaemon(photonName))
+                            break;
+                    }
+                }
+                // Each browser tab gets its own daemon session via the MCP session ID.
+                // Instance state is tracked per-session on the daemon — no global persistence.
+                const beamSessionId = `beam-${session.id}`;
+                const sendOpts = {
+                    photonPath: photonInfo.path,
+                    sessionId: beamSessionId,
+                    instanceName: session.instanceName,
+                };
+                // Elicitation-based instance selection when _use called without name
+                if (methodName === '_use' && (!args || !('name' in args))) {
+                    const instancesResult = (await sendCommand(photonName, '_instances', {}, sendOpts));
+                    const instances = instancesResult?.instances || ['default'];
+                    // Build select options for elicitation modal
+                    const selectOptions = instances.map((inst) => ({
+                        value: inst,
+                        label: inst === 'default' ? '(default)' : inst,
+                        selected: inst === (instancesResult?.current || 'default'),
+                    }));
+                    selectOptions.push({ value: '__create_new__', label: 'Create new...', selected: false });
+                    const elicitResult = await requestBeamElicitation({
+                        ask: 'select',
+                        message: 'Select an instance',
+                        options: selectOptions,
+                    });
+                    if (elicitResult.action !== 'accept' || !elicitResult.content) {
+                        return {
+                            jsonrpc: '2.0',
+                            id: req.id,
+                            result: {
+                                content: [{ type: 'text', text: 'Cancelled' }],
+                                isError: false,
+                            },
+                        };
+                    }
+                    let selectedName = elicitResult.content;
+                    // Handle "Create new..." selection
+                    if (selectedName === '__create_new__') {
+                        const nameResult = await requestBeamElicitation({
+                            ask: 'text',
+                            message: 'Enter a name for the new instance',
+                            placeholder: 'e.g. groceries, work, personal',
+                        });
+                        if (nameResult.action !== 'accept' || !nameResult.content) {
+                            return {
+                                jsonrpc: '2.0',
+                                id: req.id,
+                                result: {
+                                    content: [{ type: 'text', text: 'Cancelled' }],
+                                    isError: false,
+                                },
+                            };
+                        }
+                        selectedName = nameResult.content;
+                    }
+                    const useResult = await sendCommand(photonName, '_use', { name: selectedName }, sendOpts);
+                    session.instanceName = selectedName;
+                    // Notify UI to refresh after instance switch
+                    broadcastToBeam('photon/state-changed', {
+                        photon: photonName,
+                        method: '_use',
+                        data: { instance: selectedName },
+                    });
+                    return {
+                        jsonrpc: '2.0',
+                        id: req.id,
+                        result: {
+                            content: [{ type: 'text', text: formatResultText(useResult) }],
+                            isError: false,
+                        },
+                    };
+                }
+                // For direct _use with name, also broadcast state-changed
+                if (methodName === '_use') {
+                    const result = await sendCommand(photonName, methodName, (args || {}), sendOpts);
+                    session.instanceName = String(args?.name || '');
+                    broadcastToBeam('photon/state-changed', {
+                        photon: photonName,
+                        method: '_use',
+                        data: { instance: args?.name || 'default' },
+                    });
+                    return {
+                        jsonrpc: '2.0',
+                        id: req.id,
+                        result: {
+                            content: [{ type: 'text', text: formatResultText(result) }],
+                            isError: false,
+                        },
+                    };
+                }
+                const result = await sendCommand(photonName, methodName, (args || {}), sendOpts);
+                const resultText = formatResultText(result);
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [{ type: 'text', text: resultText }],
+                        isError: false,
+                        ...uiMetadata,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [{ type: 'text', text: `Error: ${message}` }],
+                        isError: true,
+                    },
+                };
+            }
+        }
         const mcp = ctx.photonMCPs.get(photonName);
         if (!mcp?.instance) {
             // Check if it's a disconnected external MCP
@@ -788,11 +959,12 @@ const handlers = {
                 }
                 // Use return value if no chunks were yielded, otherwise use chunks
                 const finalResult = chunks.length > 0 ? (chunks.length === 1 ? chunks[0] : chunks) : returnValue;
+                const genResultText = formatResultText(finalResult);
                 const genResponse = {
                     jsonrpc: '2.0',
                     id: req.id,
                     result: {
-                        content: [{ type: 'text', text: JSON.stringify(finalResult, null, 2) }],
+                        content: [{ type: 'text', text: genResultText }],
                         isError: false,
                         ...uiMetadata,
                     },
@@ -811,11 +983,13 @@ const handlers = {
                 }
                 return genResponse;
             }
+            // For void methods, provide a success acknowledgment so the UI shows feedback
+            const resultText = formatResultText(result);
             const toolResponse = {
                 jsonrpc: '2.0',
                 id: req.id,
                 result: {
-                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                    content: [{ type: 'text', text: resultText }],
                     isError: false,
                     ...uiMetadata,
                 },
@@ -896,6 +1070,83 @@ const handlers = {
             },
         };
     },
+    'prompts/list': async (req, _session, ctx) => {
+        const prompts = [];
+        for (const photon of ctx.photons) {
+            if (!photon.configured)
+                continue;
+            const mcp = ctx.photonMCPs.get(photon.name);
+            if (!mcp?.templates)
+                continue;
+            for (const template of mcp.templates) {
+                prompts.push({
+                    name: `${photon.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 { jsonrpc: '2.0', id: req.id, result: { prompts } };
+    },
+    'prompts/get': async (req, _session, ctx) => {
+        const { name } = req.params;
+        const args = req.params.arguments || {};
+        const slashIndex = name.indexOf('/');
+        if (slashIndex === -1) {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                error: { code: -32602, message: `Invalid prompt name: ${name}` },
+            };
+        }
+        const photonName = name.slice(0, slashIndex);
+        const promptName = name.slice(slashIndex + 1);
+        const mcp = ctx.photonMCPs.get(photonName);
+        if (!mcp) {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                error: { code: -32602, message: `Photon not found: ${photonName}` },
+            };
+        }
+        const template = mcp.templates?.find((t) => t.name === promptName);
+        if (!template) {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                error: { code: -32602, message: `Prompt not found: ${promptName}` },
+            };
+        }
+        try {
+            const result = await ctx.loader.executeTool(mcp, promptName, args);
+            // Format as prompt response
+            if (result && typeof result === 'object' && 'messages' in result) {
+                return { jsonrpc: '2.0', id: req.id, result: { messages: result.messages } };
+            }
+            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                result: {
+                    messages: [{ role: 'user', content: { type: 'text', text } }],
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                error: { code: -32603, message: `Prompt execution failed: ${message}` },
+            };
+        }
+    },
 };
 // ════════════════════════════════════════════════════════════════════════════════
 // BEAM SYSTEM TOOLS
@@ -1459,7 +1710,7 @@ async function handleBeamStudioWrite(req, ctx, args) {
             const versionMatch = source.match(/@version\s+(\S+)/);
             const runtimeMatch = source.match(/@runtime\s+(\S+)/);
             const iconMatch = source.match(/@icon\s+(\S+)/);
-            const statefulMatch = source.match(/@stateful\s+true/);
+            const statefulMatch = source.match(/@stateful\b/);
             const depsMatch = source.match(/@dependencies\s+(.+)/);
             const tagsMatch = source.match(/@tags\s+(.+)/);
             parseResult = {
@@ -1558,7 +1809,7 @@ async function handleBeamStudioParse(req, args) {
         const versionMatch = source.match(/@version\s+(\S+)/);
         const runtimeMatch = source.match(/@runtime\s+(\S+)/);
         const iconMatch = source.match(/@icon\s+(\S+)/);
-        const statefulMatch = source.match(/@stateful\s+true/);
+        const statefulMatch = source.match(/@stateful\b/);
         const depsMatch = source.match(/@dependencies\s+(.+)/);
         const tagsMatch = source.match(/@tags\s+(.+)/);
         const errors = [];
@@ -1673,20 +1924,40 @@ export async function handleStreamableHTTP(req, res, options) {
         });
         // Disable Nagle's algorithm for immediate writes
         res.socket?.setNoDelay(true);
+        // Enable TCP keepalive to prevent connection drops from intermediaries
+        res.socket?.setKeepAlive(true, 60000);
         // Store SSE response for server-initiated messages
         session.sseResponse = res;
-        // Keep connection alive
+        // Keep connection alive with SSE data events (every 15s for better reliability)
         const keepAlive = setInterval(() => {
-            res.write(': keepalive\n\n');
-        }, 30000);
-        req.on('close', () => {
+            // Check if response is still writable before sending keepalive
+            if (!res.writableEnded && !res.destroyed) {
+                try {
+                    // Send as data event so client onmessage handler fires and updates lastMessageTime
+                    res.write('data: {"type":"keepalive"}\n\n');
+                }
+                catch (err) {
+                    // If write fails, connection is dead - clean up
+                    clearInterval(keepAlive);
+                    session.sseResponse = undefined;
+                }
+            }
+            else {
+                clearInterval(keepAlive);
+            }
+        }, 15000); // Reduced from 30s to 15s for better responsiveness
+        // Handle client disconnect
+        const cleanup = () => {
             clearInterval(keepAlive);
             session.sseResponse = undefined;
             // Clean up subscriptions when client disconnects
             if (options.subscriptionManager) {
                 options.subscriptionManager.onClientDisconnect(session.id);
             }
-        });
+        };
+        req.on('close', cleanup);
+        req.on('error', cleanup);
+        res.on('error', cleanup);
         return true;
     }
     // POST - Handle JSON-RPC requests
@@ -1791,12 +2062,33 @@ export function broadcastNotification(method, params, beamOnly = false) {
         method,
         params,
     };
-    for (const session of sessions.values()) {
-        if (session.sseResponse && !session.sseResponse.writableEnded) {
+    const data = `data: ${JSON.stringify(notification)}\n\n`;
+    const deadSessions = [];
+    for (const [sessionId, session] of sessions) {
+        if (session.sseResponse &&
+            !session.sseResponse.writableEnded &&
+            !session.sseResponse.destroyed) {
             // Skip non-Beam clients if beamOnly is true
             if (beamOnly && !session.isBeam)
                 continue;
-            session.sseResponse.write(`data: ${JSON.stringify(notification)}\n\n`);
+            try {
+                session.sseResponse.write(data);
+            }
+            catch (err) {
+                // Mark session for cleanup if write fails
+                deadSessions.push(sessionId);
+            }
+        }
+        else if (session.sseResponse) {
+            // Response is ended/destroyed - mark for cleanup
+            deadSessions.push(sessionId);
+        }
+    }
+    // Clean up dead sessions
+    for (const sessionId of deadSessions) {
+        const session = sessions.get(sessionId);
+        if (session) {
+            session.sseResponse = undefined;
         }
     }
 }
@@ -1827,7 +2119,7 @@ export function getActiveSessionCount() {
  */
 export function sendToSession(sessionId, method, params) {
     const session = sessions.get(sessionId);
-    if (!session?.sseResponse || session.sseResponse.writableEnded) {
+    if (!session?.sseResponse || session.sseResponse.writableEnded || session.sseResponse.destroyed) {
         return false;
     }
     const notification = {
@@ -1835,8 +2127,15 @@ export function sendToSession(sessionId, method, params) {
         method,
         params,
     };
-    session.sseResponse.write(`data: ${JSON.stringify(notification)}\n\n`);
-    return true;
+    try {
+        session.sseResponse.write(`data: ${JSON.stringify(notification)}\n\n`);
+        return true;
+    }
+    catch (err) {
+        // Write failed - connection is dead
+        session.sseResponse = undefined;
+        return false;
+    }
 }
 /**
  * Request elicitation from the frontend for an external MCP.
@@ -1882,4 +2181,39 @@ export function requestExternalElicitation(mcpName, request) {
         }, 300000);
     });
 }
+/**
+ * Request elicitation from Beam using Photon-native ask types (select, text, etc.)
+ * Unlike requestExternalElicitation which uses MCP form/url mode, this sends
+ * the ask type directly so the elicitation modal renders the appropriate UI.
+ */
+function requestBeamElicitation(data) {
+    const elicitationId = randomUUID();
+    return new Promise((resolve) => {
+        pendingElicitations.set(elicitationId, {
+            resolve: (value) => {
+                resolve({ action: 'accept', content: value });
+            },
+            reject: (error) => {
+                if (error.message.includes('cancelled')) {
+                    resolve({ action: 'cancel' });
+                }
+                else {
+                    resolve({ action: 'decline' });
+                }
+            },
+            sessionId: '',
+        });
+        // Broadcast with Photon-native ask format (not MCP form mode)
+        broadcastToBeam('beam/elicitation', {
+            elicitationId,
+            ...data,
+        });
+        setTimeout(() => {
+            if (pendingElicitations.has(elicitationId)) {
+                pendingElicitations.delete(elicitationId);
+                resolve({ action: 'cancel' });
+            }
+        }, 300000);
+    });
+}
 //# sourceMappingURL=streamable-http-transport.js.map