@portel/photon 1.20.0 → 1.21.0

package/dist/loader.js

@@ -8,7 +8,7 @@ import { realpathSync, existsSync, mkdirSync, symlinkSync, readFileSync } from '
 import { readText, readJSON, writeText, writeJSON } from './shared/io.js';
 import { createRequire } from 'module';
 import * as path from 'path';
-import { pathToFileURL } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import * as crypto from 'crypto';
 import { startToolSpan } from './telemetry/otel.js';
 import { spawn } from 'child_process';
@@ -130,6 +130,38 @@ const cliRenderZone = new CLIRenderZone();
 export function clearRenderZone() {
     cliRenderZone.clear();
 }
+/**
+ * Inject emit-based convenience helpers on a plain-class instance.
+ * Every helper is a thin wrapper around this.emit so generator-yield and
+ * imperative-call styles produce identical wire events.
+ */
+function injectEmitHelpers(instance) {
+    const emit = (data) => instance.emit(data);
+    // Mirrors photon-core base-class render(): UI-feedback formats route to their
+    // dedicated emit events; all other formats go through the render channel.
+    instance.render = (format, value) => {
+        if (format === undefined)
+            return emit({ emit: 'render:clear' });
+        if (format === 'status')
+            return emit(typeof value === 'string'
+                ? { emit: 'status', message: value }
+                : { emit: 'status', ...value });
+        if (format === 'progress')
+            return emit(typeof value === 'number' ? { emit: 'progress', value } : { emit: 'progress', ...value });
+        if (format === 'toast')
+            return emit(typeof value === 'string' ? { emit: 'toast', message: value } : { emit: 'toast', ...value });
+        emit({ emit: 'render', format, value });
+    };
+    instance.toast = (message, opts = {}) => emit({ emit: 'toast', message, ...opts });
+    instance.log = (message, opts = {}) => emit({ emit: 'log', message, level: opts.level ?? 'info', data: opts.data });
+    instance.status = (message) => emit({ emit: 'status', message });
+    instance.progress = (value, message) => emit({ emit: 'progress', value, message });
+    instance.thinking = (active = true) => emit({ emit: 'thinking', active });
+}
+/** Extra regex checks that force 'emit' capability when helper methods are used. */
+function detectEmitHelperUsage(source) {
+    return /this\.(toast|log|status|progress|thinking)\s*\(/.test(source);
+}
 /**
  * Render a formatted value in the CLI using @portel/cli's formatOutput.
  * Uses clear-and-replace semantics — each call overwrites the previous render.
@@ -225,6 +257,12 @@ export class PhotonLoader {
      * without file I/O when running as a standalone binary.
      */
     preloadedDependencies;
+    /**
+     * Optional progress callback — invoked during long-running init phases
+     * (dependency install, compilation, onInitialize). Used by worker-host
+     * to send keepalive signals so the spawn timeout resets.
+     */
+    onProgress;
     constructor(verbose = false, logger, baseDir) {
         this.dependencyManager = new DependencyManager();
         this.verbose = verbose;
@@ -332,7 +370,7 @@ export class PhotonLoader {
      * Directory where MCP-specific dependencies are cached
      */
     getDependencyCacheDir(cacheKey) {
-        return path.join(getCacheDir(), 'dependencies', cacheKey);
+        return path.join(getCacheDir(process.env.PHOTON_DIR), 'dependencies', cacheKey);
     }
     getBuildCacheDir(cacheKey) {
         return path.join(this.getDependencyCacheDir(cacheKey), '.build');
@@ -425,6 +463,7 @@ export class PhotonLoader {
         }
         let nodeModules = null;
         if (dependencies.length > 0) {
+            this.onProgress?.('installing dependencies');
             nodeModules = await this.dependencyManager.ensureDependencies(cacheKey, dependencies);
             if (nodeModules) {
                 this.log(`📦 Dependencies ready for ${mcpName}`, { nodeModules });
@@ -572,6 +611,7 @@ export class PhotonLoader {
             }
             const importModule = async () => {
                 if (tsContent) {
+                    this.onProgress?.('compiling typescript');
                     const cachedJsPath = await this.compileTypeScript(absolutePath, cacheKey, tsContent);
                     const cachedJsUrl = pathToFileURL(cachedJsPath).href;
                     return await import(`${cachedJsUrl}?t=${Date.now()}`);
@@ -642,15 +682,12 @@ export class PhotonLoader {
             // Auto-wire ReactiveArray/Map/Set properties for zero-boilerplate reactivity
             // Developers just `import { Array } from '@portel/photon-core'` and use normally
             this.wireReactiveCollections(instance);
+            // Inject format catalog — this.formats
+            this.injectFormatCatalog(instance);
             // Inject @mcp dependencies from source (this.github, this.fs, etc.)
             if (tsContent) {
                 await this.injectMCPDependencies(instance, tsContent, name);
             }
-            // Auto-wrap public methods in @stateful classes to emit events
-            // All method calls automatically produce events with params, result, timestamp
-            if (tsContent) {
-                this.wrapStatefulMethods(instance, tsContent);
-            }
             // Inject MCP client factory if available (enables this.mcp() calls)
             const setMCPFactory = instance.setMCPFactory;
             if (this.mcpClientFactory && typeof setMCPFactory === 'function') {
@@ -674,6 +711,8 @@ export class PhotonLoader {
             // Photon base class already has these built-in, so only inject for plain classes
             if (tsContent && typeof instance.executeTool !== 'function') {
                 const caps = detectCapabilities(tsContent);
+                if (detectEmitHelperUsage(tsContent))
+                    caps.add('emit');
                 if (caps.size > 0) {
                     this.log(`🔍 Detected capabilities for ${name}: ${[...caps].join(', ')}`);
                 }
@@ -719,15 +758,8 @@ export class PhotonLoader {
                             });
                         }
                     };
-                    // Also inject render() — convenience wrapper around emit
-                    instance.render = (format, value) => {
-                        if (format === undefined) {
-                            instance.emit({ emit: 'render:clear' });
-                        }
-                        else {
-                            instance.emit({ emit: 'render', format, value });
-                        }
-                    };
+                    // Inject convenience helpers (render, toast, log, status, progress, thinking)
+                    injectEmitHelpers(instance);
                 }
                 if (caps.has('memory')) {
                     // Inject lazy memory provider — capture baseDir from loader context
@@ -978,6 +1010,7 @@ export class PhotonLoader {
             // instance after loadFile returns, then onInitialize is called manually.
             const onInitialize = instance.onInitialize;
             if (typeof onInitialize === 'function' && !options?.skipInitialize) {
+                this.onProgress?.('running onInitialize');
                 try {
                     await onInitialize.call(instance);
                 }
@@ -992,8 +1025,13 @@ export class PhotonLoader {
                     throw initError;
                 }
             }
+            // Auto-wrap public methods in @stateful classes to emit events
+            // Must happen AFTER capability injection so that emit() is available
+            if (tsContent) {
+                this.wrapStatefulMethods(instance, tsContent);
+            }
             // Extract tools, templates, and statics (with schema override support)
-            const { tools, templates, statics, settingsSchema } = await this.extractTools(MCPClass, absolutePath);
+            const { tools, templates, statics, settingsSchema, auth: extractedAuth, } = await this.extractTools(MCPClass, absolutePath);
             // ═══ SETTINGS INJECTION ═══
             // If the photon declared `protected settings = { ... }`, inject persistence + proxy
             if (settingsSchema?.hasSettings &&
@@ -1043,6 +1081,8 @@ export class PhotonLoader {
                 result.icon = classIcon;
             if (isStateful)
                 result.stateful = true;
+            if (extractedAuth)
+                result.auth = extractedAuth;
             // Store class constructor for static method access
             result.classConstructor = MCPClass;
             // Store settings schema for Beam UI
@@ -1114,6 +1154,8 @@ export class PhotonLoader {
         instance._photonResolver = (photonName, instanceName) => {
             return this.resolveAndLoadPhoton(photonName, absolutePath, instanceName);
         };
+        // Inject format catalog — this.formats
+        this.injectFormatCatalog(instance);
         // Wire reactive collections
         this.wireReactiveCollections(instance);
         // Inject @mcp dependencies
@@ -1143,6 +1185,8 @@ export class PhotonLoader {
         // Detect and inject capabilities for plain classes
         if (tsContent && typeof instance.executeTool !== 'function') {
             const caps = detectCapabilities(tsContent);
+            if (detectEmitHelperUsage(tsContent))
+                caps.add('emit');
             this.injectPathHelpers(instance, tsContent);
             if (caps.has('emit')) {
                 instance.emit = (data) => {
@@ -1177,15 +1221,8 @@ export class PhotonLoader {
                         });
                     }
                 };
-                // Also inject render() — convenience wrapper around emit
-                instance.render = (format, value) => {
-                    if (format === undefined) {
-                        instance.emit({ emit: 'render:clear' });
-                    }
-                    else {
-                        instance.emit({ emit: 'render', format, value });
-                    }
-                };
+                // Inject convenience helpers (render, toast, log, status, progress, thinking)
+                injectEmitHelpers(instance);
             }
             if (caps.has('memory')) {
                 const memoryBaseDir = this.baseDir;
@@ -1276,6 +1313,7 @@ export class PhotonLoader {
         // Call lifecycle hook
         const onInitialize = instance.onInitialize;
         if (typeof onInitialize === 'function' && !options?.skipInitialize) {
+            this.onProgress?.('running onInitialize');
             try {
                 await onInitialize.call(instance);
             }
@@ -1286,7 +1324,7 @@ export class PhotonLoader {
             }
         }
         // Extract tools and metadata from embedded source (no disk I/O)
-        const { tools, templates, statics, settingsSchema } = await this.extractTools(MCPClass, absolutePath, tsContent);
+        const { tools, templates, statics, settingsSchema, auth: extractedAuth, } = await this.extractTools(MCPClass, absolutePath, tsContent);
         // Settings injection
         if (settingsSchema?.hasSettings && instance.settings && typeof instance.settings === 'object') {
             const instanceName = options?.instanceName || 'default';
@@ -1316,6 +1354,8 @@ export class PhotonLoader {
             result.icon = classIcon;
         if (isStateful)
             result.stateful = true;
+        if (extractedAuth)
+            result.auth = extractedAuth;
         result.classConstructor = MCPClass;
         if (settingsSchema?.hasSettings) {
             result.settingsSchema = settingsSchema;
@@ -1331,6 +1371,14 @@ export class PhotonLoader {
         const match = source.match(/\/\*\*([\s\S]*?)\*\/\s*export\s+default\s+class\b/);
         return match ? match[1] : '';
     }
+    extractAuthTag(source) {
+        const docblock = this.extractClassDocblock(source);
+        // Use \b to avoid matching @author, @authorize, etc.
+        const match = docblock.match(/@auth\b(?:\s+(\S+))?/i);
+        if (!match)
+            return undefined;
+        return match[1]?.trim() || 'required';
+    }
     /**
      * Reload a Photon MCP file (for hot reload)
      */
@@ -1557,7 +1605,13 @@ export class PhotonLoader {
                             }
                         });
                     }
-                    return { tools, templates, statics, settingsSchema: metadata.settingsSchema };
+                    return {
+                        tools,
+                        templates,
+                        statics,
+                        settingsSchema: metadata.settingsSchema,
+                        auth: this.extractAuthTag(source),
+                    };
                 }
                 throw jsonError;
             }
@@ -2231,11 +2285,14 @@ export class PhotonLoader {
             return;
         if (path.dirname(realCurrentPhotonPath) !== path.dirname(resolvedPath))
             return;
-        const linkPath = path.join(this.baseDir, path.basename(resolvedPath));
+        // Symlink into the directory where the current photon's symlink lives
+        // (e.g. ~/.photon/), NOT this.baseDir which may be a different workspace.
+        const symlinkDir = path.dirname(currentPhotonPath);
+        const linkPath = path.join(symlinkDir, path.basename(resolvedPath));
         await this.createSymlinkIfMissing(resolvedPath, linkPath);
         const depName = path.basename(resolvedPath).replace(/\.photon\.(ts|js)$/, '');
         const sourceAssetDir = path.join(path.dirname(resolvedPath), depName);
-        const targetAssetDir = path.join(this.baseDir, depName);
+        const targetAssetDir = path.join(symlinkDir, depName);
         if (existsSync(sourceAssetDir)) {
             await this.createSymlinkIfMissing(sourceAssetDir, targetAssetDir, 'dir');
         }
@@ -2648,6 +2705,39 @@ Run: photon mcp ${mcpName} --config
             if (mcp.instance._photonConfigError) {
                 throw new Error(mcp.instance._photonConfigError);
             }
+            // Enforce @auth at method level — works across ALL transports (CLI, STDIO, HTTP, daemon)
+            const photonAuth = mcp.auth;
+            if (photonAuth === 'required') {
+                const caller = options?.caller;
+                if (!caller || caller.anonymous) {
+                    const inputProvider = options?.inputProvider || this.createInputProvider();
+                    try {
+                        const token = await inputProvider({
+                            ask: 'password',
+                            message: `${mcp.name} requires authentication. Enter your access token:`,
+                        });
+                        if (token && typeof token === 'string') {
+                            options = {
+                                ...options,
+                                caller: {
+                                    id: token.slice(0, 8),
+                                    name: 'authenticated-user',
+                                    anonymous: false,
+                                    claims: { token },
+                                },
+                            };
+                        }
+                        else {
+                            throw new Error(`Authentication required: ${mcp.name} has @auth required but no credentials were provided`);
+                        }
+                    }
+                    catch (e) {
+                        if (e.message?.includes('Authentication required'))
+                            throw e;
+                        throw new Error(`Authentication required: ${mcp.name} has @auth required. Provide credentials via Authorization header, MCP elicitation, or CLI prompt.`);
+                    }
+                }
+            }
             // Intercept auto-generated settings tool
             if (toolName === 'settings' && mcp.instance._settingsBacking) {
                 const result = await this.executeSettingsTool(mcp.instance, parameters, {
@@ -2659,7 +2749,10 @@ Run: photon mcp ${mcpName} --config
                 return result;
             }
             // Get tool metadata for functional tags
-            const toolMeta = mcp.tools.find((t) => t.name === toolName) || {};
+            const rawToolMeta = mcp.tools.find((t) => t.name === toolName) || {};
+            const normalized = this.normalizeNestedParamsTool(rawToolMeta, parameters);
+            const toolMeta = normalized.toolMeta;
+            parameters = normalized.parameters;
             const hasFunctionalTags = toolMeta.middleware?.length > 0;
             // Validate required parameters before execution
             const requiredParams = toolMeta.inputSchema?.required || [];
@@ -2909,6 +3002,47 @@ Run: photon mcp ${mcpName} --config
             span.end();
         }
     }
+    normalizeNestedParamsTool(toolMeta, parameters) {
+        const schema = toolMeta?.inputSchema;
+        if (!schema?.properties || typeof schema.properties !== 'object') {
+            return { toolMeta, parameters };
+        }
+        const propNames = Object.keys(schema.properties);
+        if (propNames.length !== 1 || propNames[0] !== 'params') {
+            return { toolMeta, parameters };
+        }
+        const nested = schema.properties.params;
+        if (!nested ||
+            nested.type !== 'object' ||
+            !nested.properties ||
+            typeof nested.properties !== 'object') {
+            return { toolMeta, parameters };
+        }
+        const normalizedToolMeta = {
+            ...toolMeta,
+            inputSchema: {
+                type: 'object',
+                properties: nested.properties,
+                ...(Array.isArray(nested.required) ? { required: nested.required } : {}),
+            },
+            // Named object params should stay as a single object argument at runtime.
+            simpleParams: false,
+        };
+        if (parameters &&
+            typeof parameters === 'object' &&
+            'params' in parameters &&
+            parameters.params &&
+            typeof parameters.params === 'object') {
+            return {
+                toolMeta: normalizedToolMeta,
+                parameters: parameters.params,
+            };
+        }
+        return {
+            toolMeta: normalizedToolMeta,
+            parameters,
+        };
+    }
     /**
      * Create an input provider for generator ask yields
      * Supports the new ask/emit pattern from photon-core 1.2.0
@@ -2994,7 +3128,7 @@ Run: photon mcp ${mcpName} --config
                             : emit.type === 'success'
                                 ? '✅'
                                 : 'ℹ';
-                    this.logger.info(`${icon} ${emit.message}`);
+                    process.stdout.write(`${icon} ${emit.message}\n`);
                     break;
                 case 'thinking':
                     if (emit.active) {
@@ -3061,6 +3195,30 @@ Run: photon mcp ${mcpName} --config
      * }
      * ```
      */
+    _formatCatalogCache = null;
+    injectFormatCatalog(instance) {
+        if (instance.formats)
+            return;
+        // Eagerly load once per loader, cached across all photon instances
+        if (!this._formatCatalogCache) {
+            try {
+                const loaderDir = path.dirname(fileURLToPath(import.meta.url));
+                const renderersPath = path.join(loaderDir, 'auto-ui', 'bridge', 'renderers.js');
+                const esmRequire = createRequire(import.meta.url);
+                this._formatCatalogCache = esmRequire(renderersPath).FORMAT_CATALOG;
+            }
+            catch (e) {
+                this.logger.debug('Failed to load format catalog', { error: e?.message });
+                this._formatCatalogCache = {};
+            }
+        }
+        Object.defineProperty(instance, 'formats', {
+            value: this._formatCatalogCache,
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        });
+    }
     wireReactiveCollections(instance) {
         // Get the emit function if available
         const emit = typeof instance.emit === 'function'
@@ -3109,7 +3267,18 @@ Run: photon mcp ${mcpName} --config
         // Get all public method names from the instance
         // Skip runtime-injected methods (emit, render, push, ask) — these are
         // capability methods injected by the loader, not user-defined tools
-        const RUNTIME_METHODS = new Set(['emit', 'render', 'channel', 'ask', 'call']);
+        const RUNTIME_METHODS = new Set([
+            'emit',
+            'render',
+            'channel',
+            'ask',
+            'call',
+            'toast',
+            'log',
+            'status',
+            'progress',
+            'thinking',
+        ]);
         const proto = Object.getPrototypeOf(instance);
         const methodNames = Object.getOwnPropertyNames(proto).filter((name) => {
             // Skip constructor and private/protected methods
@@ -3134,95 +3303,35 @@ Run: photon mcp ${mcpName} --config
             if (typeof original !== 'function')
                 continue;
             instance[methodName] = function (...args) {
-                // Extract parameter names and map arguments to them
-                const paramNames = PhotonLoader.extractParamNames(original);
-                const params = Object.fromEntries(paramNames.map((name, i) => [name, args[i]]));
-                // Call the original method
                 const result = original.apply(this, args);
-                // Attach __meta to returned objects for audit trail
-                const resultObj = result;
-                if (resultObj &&
-                    typeof resultObj === 'object' &&
-                    !Array.isArray(resultObj) &&
-                    !resultObj.__meta) {
-                    const timestamp = new Date().toISOString();
-                    Object.defineProperty(result, '__meta', {
-                        value: {
-                            createdAt: timestamp,
-                            createdBy: methodName,
-                            modifiedAt: null,
-                            modifiedBy: null,
-                            modifications: [],
-                        },
-                        enumerable: false,
-                        writable: true,
-                        configurable: true,
-                    });
-                }
-                // Emit event with complete context
-                const eventData = {
-                    method: methodName,
-                    params,
-                    result,
-                    timestamp: new Date().toISOString(),
-                };
-                if (this.instanceName) {
-                    eventData.instance = this.instanceName;
-                }
-                // Detect array mutations for range-based pagination support (Phase 5)
-                // If result is an object from this.items, add index and array metadata
-                if (result && typeof result === 'object' && Array.isArray(this.items)) {
-                    const index = this.items.findIndex((item) => item === result);
-                    if (index !== -1) {
-                        eventData.index = index;
-                        eventData.totalCount = this.items.length;
-                        // Affected range: just this item
-                        eventData.affectedRange = {
-                            start: index,
-                            end: index + 1,
-                        };
+                const attachMeta = (obj) => {
+                    if (obj && typeof obj === 'object' && !Array.isArray(obj) && !obj.__meta) {
+                        Object.defineProperty(obj, '__meta', {
+                            value: {
+                                createdAt: new Date().toISOString(),
+                                createdBy: methodName,
+                                modifiedAt: null,
+                                modifiedBy: null,
+                                modifications: [],
+                            },
+                            enumerable: false,
+                            writable: true,
+                            configurable: true,
+                        });
                     }
+                };
+                // For async methods, attach __meta to the resolved value, not the Promise
+                if (result && typeof result.then === 'function') {
+                    return result.then((resolved) => {
+                        attachMeta(resolved);
+                        return resolved;
+                    });
                 }
-                // NOTE: Don't emit here - the real emission happens at executeTool level
-                // (line 2362 via outputHandler). This method wrapper is only called during
-                // direct instantiation testing, not in actual MCP execution paths where executeTool
-                // is the proper routing point.
-                //
-                // If we emit here too, we get duplicate messages:
-                // 1. This wrapper emits directly: emit(eventData)
-                // 2. executeTool emits via outputHandler: outputHandler(eventData)
-                // Both route to daemon, causing double notifications.
+                attachMeta(result);
                 return result;
             };
         }
     }
-    /**
-     * Extract parameter names from a function by parsing its signature
-     *
-     * Examples:
-     * - (text, priority = 'medium') => ['text', 'priority']
-     * - (id) => ['id']
-     * - () => []
-     */
-    static extractParamNames(fn) {
-        const fnStr = fn.toString();
-        // Match parameters inside parentheses: ( ... )
-        const match = fnStr.match(/\(([^)]*)\)/);
-        if (!match?.[1]) {
-            return [];
-        }
-        return match[1]
-            .split(',')
-            .map((param) => {
-            const cleaned = param
-                .trim()
-                .split('=')[0] // Remove default value
-                .split(':')[0] // Remove type annotations
-                .trim();
-            return cleaned;
-        })
-            .filter((name) => name && name !== 'this');
-    }
     /**
      * Extract @mcp dependencies from source and inject them as instance properties
      *