@portel/photon 1.11.0 → 1.13.0

package/dist/photons/tunnel.photon.ts

@@ -1,10 +1,10 @@
 /**
  * Tunnel - Expose local servers to the internet
  * @description Multi-provider tunneling for remote access to Beam and local services
- * @internal
+ * @icon 🌐
  */
 
-import { spawn, spawnSync, execSync, ChildProcess } from 'child_process';
+import { spawn, spawnSync, ChildProcess } from 'child_process';
 
 interface TunnelInfo {
   provider: string;
@@ -12,6 +12,7 @@ interface TunnelInfo {
   url: string;
   pid: number;
   startedAt: Date;
+  active: boolean;
 }
 
 // Track active tunnels
@@ -27,26 +28,27 @@ export default class Tunnel {
       name: string;
       available: boolean;
       install?: string;
-      note?: string;
     }>;
     activeTunnels: TunnelInfo[];
   }> {
+    // Check which tunnels are still alive
+    for (const [port, tunnel] of activeTunnels) {
+      if (tunnel.process.killed || tunnel.process.exitCode !== null) {
+        tunnel.info.active = false;
+        activeTunnels.delete(port);
+      }
+    }
+
     const providers = [
       {
-        name: 'localtunnel',
-        available: true, // Always available via npx
-        note: 'Ready (uses npx, no install needed)',
+        name: 'cloudflared',
+        available: this._checkCommand('cloudflared'),
+        install: 'brew install cloudflared',
       },
       {
         name: 'ngrok',
         available: this._checkCommand('ngrok'),
-        install: 'brew install ngrok  OR  https://ngrok.com/download',
-      },
-      {
-        name: 'cloudflared',
-        available: this._checkCommand('cloudflared'),
-        install:
-          'brew install cloudflared  OR  https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation',
+        install: 'brew install ngrok',
       },
     ];
 
@@ -59,92 +61,82 @@ export default class Tunnel {
   /**
    * Start a tunnel to expose Beam to the internet
    * @icon 🚀
+   * @format qr
    * @param provider Tunnel provider to use
    */
   async *start({
-    provider = 'localtunnel',
+    provider = 'cloudflared',
   }: {
-    /** Provider: localtunnel, ngrok, or cloudflared */
-    provider?: 'localtunnel' | 'ngrok' | 'cloudflared';
+    /** Provider: cloudflared or ngrok */
+    provider?: 'cloudflared' | 'ngrok';
   } = {}): AsyncGenerator<
     { emit: string; value?: any; message: string },
     {
       message: string;
       url: string;
       link: string;
-      provider: string;
-      port: number;
-      password?: string;
     }
   > {
     // Auto-detect Beam port from environment
     const port = parseInt(process.env.BEAM_PORT || '3117', 10);
 
     // Check if tunnel already exists for this port
-    if (activeTunnels.has(port)) {
-      const existing = activeTunnels.get(port)!;
-      const publicIp = await this._getPublicIp();
-      return {
-        message: `Tunnel already active on port ${port}`,
-        url: existing.info.url,
-        link: existing.info.url,
-        password: existing.info.provider === 'localtunnel' ? publicIp : undefined,
-        provider: existing.info.provider,
-        port,
-      };
+    const existing = activeTunnels.get(port);
+    if (existing) {
+      // Verify the process is still alive
+      if (!existing.process.killed && existing.process.exitCode === null) {
+        return {
+          message: `Tunnel already running via ${existing.info.provider}`,
+          url: existing.info.url,
+          link: existing.info.url,
+        };
+      }
+      // Process died — clean up and start fresh
+      activeTunnels.delete(port);
     }
 
     yield {
       emit: 'status',
       value: { step: 'starting' },
-      message: `Starting ${provider} tunnel for Beam (port ${port})...`,
+      message: `Starting ${provider} tunnel on port ${port}...`,
     };
 
     try {
       let url: string;
-      let process: ChildProcess;
+      let tunnelProcess: ChildProcess;
 
       switch (provider) {
         case 'ngrok':
           if (!this._checkCommand('ngrok')) {
             throw new Error('ngrok not installed. Run: brew install ngrok');
           }
-          ({ url, process } = await this._startNgrok(port));
+          ({ url, process: tunnelProcess } = await this._startNgrok(port));
           break;
 
         case 'cloudflared':
+        default:
           if (!this._checkCommand('cloudflared')) {
             throw new Error('cloudflared not installed. Run: brew install cloudflared');
           }
-          ({ url, process } = await this._startCloudflared(port));
-          break;
-
-        case 'localtunnel':
-        default:
-          ({ url, process } = await this._startLocaltunnel(port));
+          ({ url, process: tunnelProcess } = await this._startCloudflared(port));
           break;
       }
 
-      // Fetch public IP (needed for localtunnel password)
-      const publicIp = await this._getPublicIp();
-
       const info: TunnelInfo = {
         provider,
         port,
         url,
-        pid: process.pid!,
+        pid: tunnelProcess.pid!,
         startedAt: new Date(),
+        active: true,
       };
 
-      activeTunnels.set(port, { process, info });
+      activeTunnels.set(port, { process: tunnelProcess, info });
 
       return {
-        message: `Tunnel started successfully`,
+        message: `Tunnel started via ${provider}`,
         url,
         link: url,
-        password: provider === 'localtunnel' ? publicIp : undefined,
-        provider,
-        port,
       };
     } catch (error: any) {
       throw new Error(error.message);
@@ -215,70 +207,6 @@ export default class Tunnel {
     return result.status === 0;
   }
 
-  private async _getPublicIp(): Promise<string> {
-    // Try multiple services in order
-    const services = ['https://api.ipify.org', 'https://ifconfig.me/ip', 'https://icanhazip.com'];
-
-    for (const service of services) {
-      try {
-        const result = execSync(`curl -s --max-time 3 ${service}`, {
-          encoding: 'utf-8',
-          timeout: 5000,
-        });
-        const ip = result.trim();
-        if (ip && /^\d+\.\d+\.\d+\.\d+$/.test(ip)) {
-          return ip;
-        }
-      } catch {
-        continue;
-      }
-    }
-    return 'unknown';
-  }
-
-  private async _startLocaltunnel(port: number): Promise<{ url: string; process: ChildProcess }> {
-    return new Promise((resolve, reject) => {
-      const proc = spawn('npx', ['localtunnel', '--port', String(port)], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      });
-
-      let output = '';
-      const timeout = setTimeout(() => {
-        reject(new Error('Timeout waiting for localtunnel URL'));
-      }, 30000);
-
-      proc.stdout?.on('data', (data) => {
-        output += data.toString();
-        // localtunnel outputs: "your url is: https://xxx.loca.lt"
-        const match = output.match(/your url is: (https?:\/\/[^\s]+)/i);
-        if (match) {
-          clearTimeout(timeout);
-          resolve({ url: match[1], process: proc });
-        }
-      });
-
-      proc.stderr?.on('data', (data) => {
-        const err = data.toString();
-        if (err.includes('error')) {
-          clearTimeout(timeout);
-          reject(new Error(err));
-        }
-      });
-
-      proc.on('error', (err) => {
-        clearTimeout(timeout);
-        reject(err);
-      });
-
-      proc.on('close', (code) => {
-        if (code !== 0 && !output.includes('your url is')) {
-          clearTimeout(timeout);
-          reject(new Error(`localtunnel exited with code ${code}`));
-        }
-      });
-    });
-  }
-
   private async _startNgrok(port: number): Promise<{ url: string; process: ChildProcess }> {
     return new Promise((resolve, reject) => {
       const proc = spawn('ngrok', ['http', String(port), '--log', 'stdout'], {

package/dist/server.d.ts

@@ -4,6 +4,8 @@
  * Wraps a .photon.ts file as an MCP server using @modelcontextprotocol/sdk
  * Supports both stdio and SSE transports
  */
+import { PhotonLoader } from './loader.js';
+import { PhotonClassExtended } from '@portel/photon-core';
 import type { Marketplace, PhotonMetadata } from './marketplace-manager.js';
 import { Logger, LoggerOptions } from './shared/logger.js';
 export declare class HotReloadDisabledError extends Error {
@@ -35,6 +37,22 @@ export interface PhotonServerOptions {
     unresolvedPhoton?: UnresolvedPhoton;
     /** Working directory override (base dir for state/config/cache) */
     workingDir?: string;
+    /** Pre-imported module (for compiled binaries — skips file I/O and compilation) */
+    preloadedModule?: {
+        default: any;
+        middleware?: any[];
+    };
+    /** Embedded source code (for compiled binaries — used for metadata extraction) */
+    embeddedSource?: string;
+    /** Pre-loaded @photon dependency modules (for compiled binaries) */
+    preloadedDependencies?: Map<string, {
+        module: {
+            default: any;
+            middleware?: any[];
+        };
+        source: string;
+        filePath: string;
+    }>;
 }
 export declare class PhotonServer {
     private loader;
@@ -71,6 +89,10 @@ export declare class PhotonServer {
     private rawClientCapabilities;
     private currentStatus;
     private logger;
+    /** Get the loaded photon (available after start()) */
+    getLoadedPhoton(): PhotonClassExtended | null;
+    /** Get the loader instance (for scheduler registration in compiled binaries) */
+    getLoader(): PhotonLoader;
     constructor(options: PhotonServerOptions);
     createScopedLogger(scope: string): Logger;
     getLogger(): Logger;
@@ -83,6 +105,14 @@ export declare class PhotonServer {
      * Build tool metadata for UI based on detected format
      */
     private buildUIToolMeta;
+    private static readonly ICON_MIME_TYPES;
+    /** Cached resolved icons per tool name */
+    private resolvedIconsCache;
+    /**
+     * Resolve raw icon image paths to MCP Icon[] format (data URIs).
+     * Results are cached so file I/O only happens once per tool.
+     */
+    private resolveIconImages;
     /**
      * Get UI mimeType based on detected format and client capabilities
      */

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

@@ -9,6 +9,8 @@ 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 * as fs from 'fs/promises';
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
 import { createServer } from 'node:http';
 import { URL } from 'node:url';
 import { PhotonLoader } from './loader.js';
@@ -69,6 +71,14 @@ export class PhotonServer {
         timestamp: Date.now(),
     };
     logger;
+    /** Get the loaded photon (available after start()) */
+    getLoadedPhoton() {
+        return this.mcp;
+    }
+    /** Get the loader instance (for scheduler registration in compiled binaries) */
+    getLoader() {
+        return this.loader;
+    }
     constructor(options) {
         // Validate options (filePath validation skipped for unresolved photons)
         if (!options.unresolvedPhoton) {
@@ -145,6 +155,54 @@ export class PhotonServer {
         const uri = this.buildUIResourceUri(uiId);
         return { ui: { resourceUri: uri } };
     }
+    static ICON_MIME_TYPES = {
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.svg': 'image/svg+xml',
+        '.webp': 'image/webp',
+        '.ico': 'image/x-icon',
+    };
+    /** Cached resolved icons per tool name */
+    resolvedIconsCache = new Map();
+    /**
+     * Resolve raw icon image paths to MCP Icon[] format (data URIs).
+     * Results are cached so file I/O only happens once per tool.
+     */
+    resolveIconImages(iconImages) {
+        const cacheKey = iconImages.map((i) => i.path).join('|');
+        const cached = this.resolvedIconsCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const photonDir = path.dirname(this.options.filePath);
+        const icons = [];
+        for (const entry of iconImages) {
+            try {
+                const resolvedPath = path.resolve(photonDir, entry.path);
+                const ext = path.extname(resolvedPath).toLowerCase();
+                const mimeType = PhotonServer.ICON_MIME_TYPES[ext];
+                if (!mimeType)
+                    continue;
+                const data = readFileSync(resolvedPath);
+                const dataUri = `data:${mimeType};base64,${data.toString('base64')}`;
+                const icon = {
+                    src: dataUri,
+                    mimeType,
+                };
+                if (entry.sizes)
+                    icon.sizes = entry.sizes;
+                if (entry.theme)
+                    icon.theme = entry.theme;
+                icons.push(icon);
+            }
+            catch {
+                // Skip unreadable icon files silently
+            }
+        }
+        this.resolvedIconsCache.set(cacheKey, icons);
+        return icons;
+    }
     /**
      * Get UI mimeType based on detected format and client capabilities
      */
@@ -438,6 +496,30 @@ export class PhotonServer {
                 description,
                 inputSchema: tool.inputSchema,
             };
+            // MCP standard annotations (2025-11-25 spec)
+            const schema = tool;
+            const annotations = {};
+            if (schema.title)
+                annotations.title = schema.title;
+            if (schema.readOnlyHint)
+                annotations.readOnlyHint = true;
+            if (schema.destructiveHint)
+                annotations.destructiveHint = true;
+            if (schema.idempotentHint)
+                annotations.idempotentHint = true;
+            if (schema.openWorldHint !== undefined)
+                annotations.openWorldHint = schema.openWorldHint;
+            if (Object.keys(annotations).length > 0)
+                toolDef.annotations = annotations;
+            // MCP structured output schema
+            if (schema.outputSchema)
+                toolDef.outputSchema = schema.outputSchema;
+            // MCP tool icons (resolve image paths to data URIs)
+            if (tool.iconImages && tool.iconImages.length > 0) {
+                const icons = this.resolveIconImages(tool.iconImages);
+                if (icons.length > 0)
+                    toolDef.icons = icons;
+            }
             const linkedUI = this.mcp?.assets?.ui.find((u) => u.linkedTool === tool.name);
             if (linkedUI && this.clientSupportsUI(ctx.server)) {
                 toolDef._meta = this.buildUIToolMeta(linkedUI.id);
@@ -464,6 +546,16 @@ export class PhotonServer {
                 description: `List all available instances.`,
                 inputSchema: { type: 'object', properties: {} },
             });
+            tools.push({
+                name: '_undo',
+                description: `Undo the last state mutation. Reverts the most recent tool call's changes.`,
+                inputSchema: { type: 'object', properties: {} },
+            });
+            tools.push({
+                name: '_redo',
+                description: `Redo the last undone mutation. Re-applies a previously undone change.`,
+                inputSchema: { type: 'object', properties: {} },
+            });
         }
         return { tools };
     }
@@ -472,8 +564,12 @@ export class PhotonServer {
             throw new Error('MCP not loaded');
         }
         const { name: toolName, arguments: args } = request.params;
-        // Route _use and _instances through daemon for stateful photons
-        if (this.daemonName && (toolName === '_use' || toolName === '_instances')) {
+        // Route _use, _instances, _undo, _redo through daemon for stateful photons
+        if (this.daemonName &&
+            (toolName === '_use' ||
+                toolName === '_instances' ||
+                toolName === '_undo' ||
+                toolName === '_redo')) {
             const { sendCommand } = await import('./daemon/client.js');
             const sendOpts = {
                 photonPath: this.options.filePath,
@@ -578,19 +674,35 @@ export class PhotonServer {
         });
         const isStateful = result && typeof result === 'object' && result._stateful === true;
         const actualResult = isStateful ? result.result : result;
-        // Build content with optional mimeType annotation
+        // Build content with optional annotations
         const content = {
             type: 'text',
             text: this.formatResult(actualResult),
         };
+        // Content annotations: audience and priority from schema, mimeType from format
+        const contentAnnotations = {};
+        const schema = tool;
+        if (schema?.audience)
+            contentAnnotations.audience = schema.audience;
+        if (schema?.contentPriority !== undefined)
+            contentAnnotations.priority = schema.contentPriority;
         if (outputFormat) {
             const { formatToMimeType } = await import('./cli-formatter.js');
             const mimeType = formatToMimeType(outputFormat);
-            if (mimeType) {
-                content.annotations = { mimeType };
-            }
+            if (mimeType)
+                contentAnnotations.mimeType = mimeType;
+        }
+        if (Object.keys(contentAnnotations).length > 0) {
+            content.annotations = contentAnnotations;
         }
         const response = { content: [content], isError: false };
+        // Structured output: include structuredContent when outputSchema is declared
+        if (schema?.outputSchema &&
+            actualResult &&
+            typeof actualResult === 'object' &&
+            !Array.isArray(actualResult)) {
+            response.structuredContent = actualResult;
+        }
         // Add x-output-format for format-aware clients
         if (outputFormat) {
             response['x-output-format'] = outputFormat;
@@ -941,8 +1053,20 @@ export class PhotonServer {
         let errorType = 'runtime_error';
         let errorMessage = getErrorMessage(error) || String(error);
         let suggestion = '';
-        // Categorize common errors and provide suggestions
-        if (errorMessage.includes('not a function') || errorMessage.includes('undefined')) {
+        // Photon authors can attach userMessage and hint to errors for friendly display:
+        //   throw Object.assign(new Error('internal'), { userMessage: 'friendly msg', hint: 'try this' })
+        const userMessage = error && typeof error === 'object' && 'userMessage' in error ? String(error.userMessage) : '';
+        const userHint = error && typeof error === 'object' && 'hint' in error ? String(error.hint) : '';
+        // Use userMessage as the display message if provided
+        if (userMessage) {
+            errorMessage = userMessage;
+        }
+        // Use author-provided hint over auto-generated suggestion
+        if (userHint) {
+            suggestion = userHint;
+        }
+        else if (errorMessage.includes('not a function') || errorMessage.includes('undefined')) {
+            // Categorize common errors and provide suggestions
             errorType = 'implementation_error';
             suggestion =
                 'The tool implementation may have an issue. Check that all methods are properly defined.';
@@ -1230,8 +1354,18 @@ export class PhotonServer {
                     }
                 }
                 // Load the Photon MCP file
-                this.log('info', `Loading ${this.options.filePath}...`);
-                this.mcp = await this.loader.loadFile(this.options.filePath);
+                if (this.options.preloadedModule) {
+                    // Wire preloaded @photon dependencies before loading
+                    if (this.options.preloadedDependencies) {
+                        this.loader.preloadedDependencies = this.options.preloadedDependencies;
+                    }
+                    this.log('info', `Loading preloaded module for ${this.options.filePath}...`);
+                    this.mcp = await this.loader.loadFromModule(this.options.preloadedModule, this.options.filePath, this.options.embeddedSource || '');
+                }
+                else {
+                    this.log('info', `Loading ${this.options.filePath}...`);
+                    this.mcp = await this.loader.loadFile(this.options.filePath);
+                }
             }
             // Subscribe to daemon channels for cross-process notifications
             await this.subscribeToChannels();
@@ -1290,6 +1424,10 @@ export class PhotonServer {
         if (!message || typeof message !== 'object')
             return;
         const msg = message;
+        // Debug logging for cross-client event transmission
+        if (process.env.PHOTON_DEBUG_EVENTS === '1') {
+            console.error(`[PHOTON-SERVER] Received daemon message on ${String(msg.channel)}: event=${String(msg.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
@@ -1306,9 +1444,16 @@ export class PhotonServer {
             },
         };
         try {
+            if (process.env.PHOTON_DEBUG_EVENTS === '1') {
+                console.error(`[PHOTON-SERVER] Sending notification to MCP clients...`);
+            }
             await this.server.notification(payload);
+            if (process.env.PHOTON_DEBUG_EVENTS === '1') {
+                console.error(`[PHOTON-SERVER] Notification sent successfully`);
+            }
         }
         catch (e) {
+            console.error(`[PHOTON-SERVER-ERROR] Notification send failed: ${getErrorMessage(e)}`);
             this.log('debug', 'Notification send failed', { error: getErrorMessage(e) });
         }
         // Also send to SSE sessions — snapshot to avoid live-iterator + await issues