@portel/photon 1.17.6 → 1.19.0

package/dist/server.js

@@ -7,7 +7,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, GetTaskRequestSchema, ListTasksRequestSchema, CancelTaskRequestSchema, GetTaskPayloadRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { readFileSync } from 'node:fs';
 import { readText } from './shared/io.js';
 import * as path from 'node:path';
@@ -26,6 +26,9 @@ import { isGlobalDaemonRunning, startGlobalDaemon } from './daemon/manager.js';
 import { PhotonDocExtractor } from './photon-doc-extractor.js';
 import { isLocalRequest, readBody, setSecurityHeaders } from './shared/security.js';
 import { audit } from './shared/audit.js';
+import { createTask, getTask, updateTask, listTasks, registerController, getController, unregisterController, } from './tasks/store.js';
+import { toWireFormat, relatedTaskMeta, TERMINAL_STATES } from './tasks/types.js';
+import { runTaskExecution, resolveTaskInput, waitForTerminalOrInput } from './tasks/executor.js';
 export class HotReloadDisabledError extends Error {
     constructor(message) {
         super(message);
@@ -102,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) {
@@ -201,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;
             }
@@ -221,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');
     }
 }
@@ -306,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: {
@@ -323,9 +334,32 @@ export class PhotonServer {
                     listChanged: true, // We support hot reload notifications
                 },
                 logging: {}, // Required for notifications/message (used by render, log, etc.)
+                tasks: {
+                    list: {},
+                    cancel: {},
+                    requests: {
+                        tools: { call: {} },
+                    },
+                },
                 // 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();
@@ -456,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
      */
@@ -1340,6 +1430,27 @@ export class PhotonServer {
                     };
                 }
             }
+            // ── Task mode: when params contain task field, run async ──
+            const taskField = request.params?.task;
+            if (taskField && this.mcp) {
+                const { name: toolName, arguments: args } = request.params;
+                const ttl = typeof taskField.ttl === 'number' ? taskField.ttl : undefined;
+                const task = createTask(this.mcp.name, toolName, args, ttl);
+                const controller = new AbortController();
+                registerController(task.id, controller);
+                const executeFn = async (taskInputProvider, outputHandler) => {
+                    return this.loader.executeTool(this.mcp, toolName, args || {}, {
+                        outputHandler,
+                        inputProvider: taskInputProvider,
+                    });
+                };
+                runTaskExecution(task.id, executeFn, {
+                    signal: controller.signal,
+                });
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ task: toWireFormat(task) }, null, 2) }],
+                };
+            }
             try {
                 return await this.handleCallTool(ctx, request);
             }
@@ -1386,6 +1497,129 @@ export class PhotonServer {
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             return this.handleReadResource(request);
         });
+        // ── MCP Tasks handlers (2025-11-25 spec) ──
+        this.server.setRequestHandler(GetTaskRequestSchema, async (request) => {
+            const { taskId } = request.params;
+            const task = getTask(taskId);
+            if (!task)
+                throw new Error(`Task not found: ${taskId}`);
+            return toWireFormat(task);
+        });
+        this.server.setRequestHandler(ListTasksRequestSchema, async (request) => {
+            const allTasks = listTasks();
+            const cursor = request.params?.cursor;
+            const offset = cursor ? parseInt(cursor, 10) || 0 : 0;
+            const pageSize = 50;
+            const page = allTasks.slice(offset, offset + pageSize);
+            const nextCursor = offset + pageSize < allTasks.length ? String(offset + pageSize) : undefined;
+            return {
+                tasks: page.map(toWireFormat),
+                ...(nextCursor && { nextCursor }),
+            };
+        });
+        this.server.setRequestHandler(CancelTaskRequestSchema, async (request) => {
+            const { taskId } = request.params;
+            const task = getTask(taskId);
+            if (!task)
+                throw new Error(`Task not found: ${taskId}`);
+            if (TERMINAL_STATES.includes(task.state)) {
+                throw new Error(`Cannot cancel task in terminal state: ${task.state}`);
+            }
+            const controller = getController(taskId);
+            if (controller)
+                controller.abort();
+            const updated = updateTask(taskId, {
+                state: 'cancelled',
+                statusMessage: 'The task was cancelled by request.',
+            });
+            unregisterController(taskId);
+            return toWireFormat(updated);
+        });
+        this.server.setRequestHandler(GetTaskPayloadRequestSchema, async (request) => {
+            const { taskId } = request.params;
+            const task = getTask(taskId);
+            if (!task)
+                throw new Error(`Task not found: ${taskId}`);
+            // Helper to format terminal task result
+            const formatResult = (t) => {
+                if (t.state === 'failed') {
+                    return {
+                        content: [{ type: 'text', text: t.error || 'Task failed' }],
+                        isError: true,
+                        _meta: relatedTaskMeta(taskId),
+                    };
+                }
+                if (t.state === 'cancelled') {
+                    return {
+                        content: [{ type: 'text', text: 'Task was cancelled.' }],
+                        isError: false,
+                        _meta: relatedTaskMeta(taskId),
+                    };
+                }
+                // Completed
+                if (t.result && typeof t.result === 'object' && 'content' in t.result) {
+                    return { ...t.result, _meta: relatedTaskMeta(taskId) };
+                }
+                const text = typeof t.result === 'string' ? t.result : JSON.stringify(t.result ?? null);
+                return {
+                    content: [{ type: 'text', text }],
+                    isError: false,
+                    _meta: relatedTaskMeta(taskId),
+                };
+            };
+            // Already terminal — return immediately
+            if (TERMINAL_STATES.includes(task.state)) {
+                return formatResult(task);
+            }
+            // If input_required, try to get input via elicitation
+            if (task.state === 'input_required' && task.input) {
+                const inputProvider = this.createMCPInputProvider(this.server);
+                try {
+                    const value = await inputProvider(task.input);
+                    resolveTaskInput(taskId, value);
+                }
+                catch {
+                    resolveTaskInput(taskId, null);
+                }
+            }
+            // Block until terminal (max 5 min per call)
+            try {
+                const abortController = new AbortController();
+                const timeout = setTimeout(() => abortController.abort(), 300000);
+                try {
+                    while (true) {
+                        const current = await waitForTerminalOrInput(taskId, abortController.signal);
+                        if (TERMINAL_STATES.includes(current.state)) {
+                            return formatResult(current);
+                        }
+                        if (current.state === 'input_required' && current.input) {
+                            const inputProvider = this.createMCPInputProvider(this.server);
+                            try {
+                                const value = await inputProvider(current.input);
+                                resolveTaskInput(taskId, value);
+                            }
+                            catch {
+                                resolveTaskInput(taskId, null);
+                            }
+                        }
+                    }
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            catch {
+                const current = getTask(taskId);
+                if (current && TERMINAL_STATES.includes(current.state)) {
+                    return formatResult(current);
+                }
+                return {
+                    content: [{ type: 'text', text: `Task ${taskId} is still running.` }],
+                    isError: false,
+                    _meta: relatedTaskMeta(taskId),
+                };
+            }
+        });
     }
     /**
      * Format tool result as text
@@ -1733,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
@@ -1767,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';
@@ -1828,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
@@ -1877,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);
         };
@@ -1898,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,
@@ -1978,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();
@@ -2345,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();
             });
         });