@portel/photon 1.20.1 → 1.22.0

package/dist/loader.js

@@ -8,9 +8,11 @@ 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 { recordToolCall, recordCircuitStateChange, recordRateLimitRejection, recordBulkheadRejection, } from './telemetry/metrics.js';
+import { runWithRequestContext } from './telemetry/context.js';
 import { spawn } from 'child_process';
 import { SchemaExtractor, DependencyManager, 
 // Generator utilities (ask/emit pattern from 1.2.0)
@@ -130,6 +132,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.
@@ -203,6 +237,19 @@ export class PhotonLoader {
     middlewareStates = new Map();
     /** Per-photon custom middleware definitions discovered from module exports */
     photonMiddleware = new Map();
+    /** Shadow registry of circuit breaker states, keyed by `${photon}:${instance}:${tool}` */
+    circuitHealthTracker = new Map();
+    /**
+     * Returns all tracked circuit breaker states across all photons.
+     * Each entry uses the key format `${photon}:${instance}:${tool}`.
+     */
+    getCircuitHealth() {
+        const result = {};
+        for (const [key, entry] of this.circuitHealthTracker) {
+            result[key] = { ...entry };
+        }
+        return result;
+    }
     /** Base directory for state/config/cache (defaults to ~/.photon) */
     baseDir;
     /**
@@ -650,15 +697,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') {
@@ -669,9 +713,31 @@ export class PhotonLoader {
             if (typeof instance._callHandler === 'undefined' || instance._callHandler === undefined) {
                 const callBaseDir = this.baseDir;
                 instance._callHandler = async (photonName, method, params, targetInstance) => {
+                    // Propagate trace context to nested photon-to-photon calls so the
+                    // downstream span chains as a child of the current span. Uses
+                    // in-band `_meta.traceparent` which executeTool peeks at before
+                    // schema validation — works through worker threads transparently.
+                    const ctxMod = await import('./telemetry/context.js');
+                    const ctx = ctxMod.getRequestContext();
+                    let forwardedParams = params;
+                    if (ctx) {
+                        const traceparent = ctx.parentTraceparent ||
+                            (ctx.traceId
+                                ? `00-${ctx.traceId}-${crypto.randomBytes(8).toString('hex')}-01`
+                                : undefined);
+                        if (traceparent) {
+                            const existingMeta = params?._meta;
+                            forwardedParams = {
+                                ...(params || {}),
+                                _meta: existingMeta && typeof existingMeta === 'object'
+                                    ? { traceparent, ...existingMeta }
+                                    : { traceparent },
+                            };
+                        }
+                    }
                     // Dynamic import to avoid circular dependency
                     const { sendCommand } = await import('./daemon/client.js');
-                    return sendCommand(photonName, method, params, {
+                    return sendCommand(photonName, method, forwardedParams, {
                         workingDir: callBaseDir,
                         targetInstance,
                     });
@@ -682,6 +748,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(', ')}`);
                 }
@@ -727,15 +795,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
@@ -1001,8 +1062,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 &&
@@ -1052,6 +1118,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
@@ -1123,6 +1191,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
@@ -1152,6 +1222,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) => {
@@ -1186,15 +1258,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;
@@ -1296,7 +1361,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';
@@ -1326,6 +1391,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;
@@ -1341,6 +1408,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)
      */
@@ -1456,7 +1531,7 @@ export class PhotonLoader {
         if (!description)
             return '';
         if (description.includes('@emits') && process.env.PHOTON_DEBUG_EXTRACT) {
-            console.log(`[stripJSDocTags] Input: "${description}"`);
+            this.logger.debug(`[stripJSDocTags] Input: "${description}"`);
         }
         // Remove lines that start with @ (full line removal)
         let cleaned = description
@@ -1467,7 +1542,7 @@ export class PhotonLoader {
         // Also remove inline @ tags (e.g., "text @emits ... " at end of line)
         cleaned = cleaned.replace(/\s*@\w+.*$/gm, '').trim();
         if (description.includes('@emits') && process.env.PHOTON_DEBUG_EXTRACT) {
-            console.log(`[stripJSDocTags] Output: "${cleaned}"`);
+            this.logger.debug(`[stripJSDocTags] Output: "${cleaned}"`);
         }
         return cleaned;
     }
@@ -1550,7 +1625,7 @@ export class PhotonLoader {
                     if (process.env.PHOTON_DEBUG_EXTRACT) {
                         tools.forEach((t) => {
                             if (t.description?.includes('@')) {
-                                console.log(`[EXTRACTOR] Before clean: ${t.name}: "${t.description}"`);
+                                this.logger.debug(`[EXTRACTOR] Before clean: ${t.name}: "${t.description}"`);
                             }
                         });
                     }
@@ -1563,11 +1638,17 @@ export class PhotonLoader {
                     if (process.env.PHOTON_DEBUG_EXTRACT) {
                         tools.forEach((t) => {
                             if (t.name === 'clear') {
-                                console.log(`[EXTRACTOR] After clean: ${t.name}: "${t.description}"`);
+                                this.logger.debug(`[EXTRACTOR] After clean: ${t.name}: "${t.description}"`);
                             }
                         });
                     }
-                    return { tools, templates, statics, settingsSchema: metadata.settingsSchema };
+                    return {
+                        tools,
+                        templates,
+                        statics,
+                        settingsSchema: metadata.settingsSchema,
+                        auth: this.extractAuthTag(source),
+                    };
                 }
                 throw jsonError;
             }
@@ -2241,11 +2322,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');
         }
@@ -2546,14 +2630,17 @@ Run: photon mcp ${mcpName} --config
      * Tags become composable wrappers applied in the correct order via phase-sorted middleware.
      * All middleware (built-in and custom) follows the same code path — no if-chain.
      */
-    applyMiddleware(execute, toolMeta, photonName, toolName, parameters, instanceName) {
+    applyMiddleware(execute, toolMeta, photonName, toolName, parameters, instanceName, outputHandler) {
         // Build middleware context
+        const store = executionContext.getStore();
         const ctx = {
             photon: photonName,
             tool: toolName,
             instance: instanceName || 'default',
             params: parameters,
-        };
+            caller: store?.caller,
+            outputHandler,
+        }; // MiddlewareContext type is in photon-core (read-only); caller/outputHandler added via runtime extension
         // Get declarations from the new middleware[] field
         const declarations = toolMeta.middleware || [];
         if (declarations.length === 0) {
@@ -2605,6 +2692,94 @@ Run: photon mcp ${mcpName} --config
                 return withLockHelper(lockName, next);
             };
         });
+        // Handler override for circuitBreaker — mirror state into circuitHealthTracker for introspection
+        handlerOverrides.set('circuitBreaker', (config, _state) => {
+            const tracker = this.circuitHealthTracker;
+            return async (ctx, next) => {
+                const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+                let circuit = tracker.get(key);
+                if (!circuit) {
+                    circuit = { failures: 0, state: 'closed', openedAt: 0 };
+                    tracker.set(key, circuit);
+                }
+                const openError = () => {
+                    const error = new Error(`Circuit open: ${ctx.photon}.${ctx.tool} has failed ${config.threshold} consecutive times. Resets in ${Math.ceil((config.resetAfterMs - (Date.now() - circuit.openedAt)) / 1000)}s`);
+                    error.name = 'PhotonCircuitOpenError';
+                    return error;
+                };
+                const emitTransition = (from, to) => {
+                    if (from === to)
+                        return;
+                    recordCircuitStateChange({
+                        photon: ctx.photon,
+                        tool: ctx.tool,
+                        instance: ctx.instance,
+                        from,
+                        to,
+                    });
+                    // Broadcast state-change as a domain event so AG-UI clients
+                    // (via createAGUIOutputHandler) receive a STATE_DELTA in real
+                    // time instead of polling /api/health/circuits.
+                    const handler = ctx.outputHandler;
+                    if (handler) {
+                        try {
+                            handler({
+                                channel: `${ctx.photon}:circuits`,
+                                event: 'state-change',
+                                data: {
+                                    key: `${ctx.photon}:${ctx.instance}:${ctx.tool}`,
+                                    from,
+                                    to,
+                                    timestamp: Date.now(),
+                                },
+                            });
+                        }
+                        catch {
+                            /* best-effort — don't fail the middleware chain */
+                        }
+                    }
+                };
+                if (circuit.state === 'open') {
+                    if (Date.now() - circuit.openedAt >= config.resetAfterMs) {
+                        // Transition to half-open and allow exactly one probe through.
+                        emitTransition('open', 'half-open');
+                        circuit.state = 'half-open';
+                        circuit.probeInFlight = true;
+                    }
+                    else {
+                        throw openError();
+                    }
+                }
+                else if (circuit.state === 'half-open') {
+                    // Probe already in flight — reject concurrent requests to avoid stampede.
+                    if (circuit.probeInFlight) {
+                        throw openError();
+                    }
+                    circuit.probeInFlight = true;
+                }
+                const stateBefore = circuit.state;
+                try {
+                    const result = await next();
+                    circuit.failures = 0;
+                    if (stateBefore !== 'closed')
+                        emitTransition(stateBefore, 'closed');
+                    circuit.state = 'closed';
+                    circuit.probeInFlight = false;
+                    return result;
+                }
+                catch (error) {
+                    circuit.failures++;
+                    circuit.probeInFlight = false;
+                    // A failed probe in half-open immediately reopens the circuit.
+                    if (stateBefore === 'half-open' || circuit.failures >= config.threshold) {
+                        emitTransition(circuit.state, 'open');
+                        circuit.state = 'open';
+                        circuit.openedAt = Date.now();
+                    }
+                    throw error;
+                }
+            };
+        });
         return buildMiddlewareChain(execute, declarations, combinedRegistry, this.middlewareStates, ctx, handlerOverrides);
     }
     /**
@@ -2621,11 +2796,54 @@ Run: photon mcp ${mcpName} --config
      * @returns Tool result, or wrapped result with runId for stateful workflows
      */
     async executeTool(mcp, toolName, parameters, options) {
+        // Resolve parentTraceparent from options or in-band `_meta.traceparent` so
+        // the ALS context reflects the true parent for any nested `this.call()`.
+        let resolvedParentTraceparent = options?.parentTraceparent;
+        if (!resolvedParentTraceparent &&
+            parameters &&
+            typeof parameters === 'object' &&
+            '_meta' in parameters) {
+            const metaPeek = parameters._meta;
+            if (metaPeek && typeof metaPeek.traceparent === 'string') {
+                resolvedParentTraceparent = metaPeek.traceparent;
+            }
+        }
+        return runWithRequestContext({
+            photon: mcp.name,
+            tool: toolName,
+            traceId: options?.traceId,
+            parentTraceparent: resolvedParentTraceparent,
+            caller: options?.caller,
+            startedAt: Date.now(),
+        }, () => this._executeToolInner(mcp, toolName, parameters, {
+            ...options,
+            parentTraceparent: resolvedParentTraceparent,
+        }));
+    }
+    async _executeToolInner(mcp, toolName, parameters, options) {
         // Start audit trail recording
         const audit = getAuditTrail();
         const { finish: auditFinish } = audit.start(mcp.name, toolName, parameters || {});
+        // Start wall-clock timer for tool-call duration histogram.
+        const toolStartedAt = Date.now();
+        let metricsStatus = 'ok';
+        let metricsErrorType;
+        // Peek at _meta.traceparent before span creation so distributed traces chain.
+        // Explicit option wins over in-band _meta (server may have extracted from headers).
+        let parentTraceparent = options?.parentTraceparent;
+        if (!parentTraceparent &&
+            parameters &&
+            typeof parameters === 'object' &&
+            '_meta' in parameters) {
+            const metaPeek = parameters._meta;
+            if (metaPeek && typeof metaPeek === 'object' && typeof metaPeek.traceparent === 'string') {
+                parentTraceparent = metaPeek.traceparent;
+            }
+        }
         // Start OTel span for tool execution (no-op if SDK not installed)
-        const span = startToolSpan(mcp.name, toolName, parameters);
+        const toolMetaForSpan = mcp?.meta?.tools?.[toolName];
+        const isStateful = Boolean(toolMetaForSpan?.stateful ?? mcp?.meta?.stateful);
+        const span = startToolSpan(mcp.name, toolName, parameters, options?.traceId, isStateful, parentTraceparent);
         if (mcp.instance?.instanceName) {
             span.setAttribute('photon.instance', mcp.instance.instanceName);
         }
@@ -2658,6 +2876,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, {
@@ -2707,7 +2958,7 @@ Run: photon mcp ${mcpName} --config
                 };
                 // Apply functional tag middleware if any tags present
                 if (hasFunctionalTags) {
-                    executeBase = this.applyMiddleware(executeBase, toolMeta, mcp.name, toolName, parameters, mcp.instance.instanceName);
+                    executeBase = this.applyMiddleware(executeBase, toolMeta, mcp.name, toolName, parameters, mcp.instance.instanceName, options?.outputHandler);
                 }
                 const result = await executeBase();
                 this.progressRenderer.done();
@@ -2735,30 +2986,36 @@ Run: photon mcp ${mcpName} --config
                                 configurable: true,
                             });
                         }
-                        // Construct event data with full context for transmission
-                        // CRITICAL: emit() expects { channel, event, data } structure for daemon pub/sub routing
-                        const eventPayload = {
+                        // Construct CloudEvents 1.0 envelope for @stateful event emissions.
+                        // The `data` field carries the photon-specific payload; `channel` and `event`
+                        // are transport metadata used by the daemon pub/sub router.
+                        const cloudEventData = {
                             method: toolName,
                             params: parameters,
                             result,
-                            timestamp: new Date().toISOString(),
+                            instance: mcp.instance.instanceName ?? null,
                         };
-                        // Add instance name if available
-                        if (mcp.instance.instanceName) {
-                            eventPayload.instance = mcp.instance.instanceName;
-                        }
                         // Add index/pagination info if result is from items array
                         if (result && typeof result === 'object' && Array.isArray(mcp.instance.items)) {
                             const index = mcp.instance.items.findIndex((item) => item === result);
                             if (index !== -1) {
-                                eventPayload.index = index;
-                                eventPayload.totalCount = mcp.instance.items.length;
-                                eventPayload.affectedRange = {
+                                cloudEventData.index = index;
+                                cloudEventData.totalCount = mcp.instance.items.length;
+                                cloudEventData.affectedRange = {
                                     start: index,
                                     end: index + 1,
                                 };
                             }
                         }
+                        // CloudEvents 1.0 envelope (https://cloudevents.io)
+                        const eventPayload = {
+                            specversion: '1.0',
+                            id: crypto.randomUUID(),
+                            source: `photon/${photonName}`,
+                            type: `photon.${photonName}.${toolName}.executed`,
+                            time: new Date().toISOString(),
+                            data: cloudEventData,
+                        };
                         // Wrap in daemon pub/sub format: { channel, event, data }
                         const eventData = {
                             channel: `${photonName}:${toolName}`, // For daemon pub/sub routing
@@ -2770,18 +3027,24 @@ Run: photon mcp ${mcpName} --config
                         if (options?.outputHandler) {
                             try {
                                 if (process.env.PHOTON_DEBUG_EMIT === '1') {
-                                    console.error(`[EMIT-DEBUG] Sending event: method=${eventPayload.method}, channel=${eventData.channel}, hasMeta=${!!result?.__meta}`);
+                                    this.logger.debug('[emit] sending event', {
+                                        method: eventPayload.data.method,
+                                        channel: eventData.channel,
+                                        hasMeta: !!result?.__meta,
+                                    });
                                 }
                                 // Cast to DaemonEventEnvelope - outputHandler is flexible and routes any object with channel property
                                 void Promise.resolve(options.outputHandler(eventData)).catch((e) => {
                                     this.logger.debug('Output handler failed for event', { error: e?.message || e });
                                 });
                                 if (process.env.PHOTON_DEBUG_EMIT === '1') {
-                                    console.error(`[EMIT-DEBUG] Event transmitted to outputHandler`);
+                                    this.logger.debug('[emit] event transmitted to outputHandler');
                                 }
                             }
                             catch (e) {
-                                console.error(`[EMIT-ERROR] Failed to send event through outputHandler: ${e instanceof Error ? e.message : String(e)}`);
+                                this.logger.error('Failed to send event through outputHandler', {
+                                    error: e instanceof Error ? e.message : String(e),
+                                });
                             }
                         }
                         else if (mcp.instance && typeof mcp.instance.emit === 'function') {
@@ -2789,19 +3052,22 @@ Run: photon mcp ${mcpName} --config
                             // (this path won't route to daemon pub/sub, but at least calls emit)
                             try {
                                 if (process.env.PHOTON_DEBUG_EMIT === '1') {
-                                    console.error(`[EMIT-DEBUG] No outputHandler, falling back to instance.emit`);
+                                    this.logger.debug('[emit] no outputHandler, falling back to instance.emit');
                                 }
                                 mcp.instance.emit(eventData);
                             }
                             catch (e) {
-                                console.error(`[EMIT-ERROR] Failed to emit: ${e instanceof Error ? e.message : String(e)}`);
+                                this.logger.error('Failed to emit event via instance.emit', {
+                                    error: e instanceof Error ? e.message : String(e),
+                                });
                             }
                         }
                     }
                     catch (e) {
                         // Log emit errors but don't break tool execution
-                        console.error(`[EMIT-ERROR] Failed to emit @stateful event: ${e instanceof Error ? e.message : String(e)}`);
-                        this.logger.debug(`Failed to emit @stateful event: ${e instanceof Error ? e.message : String(e)}`);
+                        this.logger.error('Failed to emit @stateful event', {
+                            error: e instanceof Error ? e.message : String(e),
+                        });
                     }
                 }
                 // Apply _meta post-processing (format transformation, field selection)
@@ -2858,7 +3124,7 @@ Run: photon mcp ${mcpName} --config
                 });
             // Apply functional tag middleware if any tags present
             if (hasFunctionalTags) {
-                generatorFn = this.applyMiddleware(generatorFn, toolMeta, mcp.name, toolName, parameters, mcp.instance.instanceName);
+                generatorFn = this.applyMiddleware(generatorFn, toolMeta, mcp.name, toolName, parameters, mcp.instance.instanceName, options?.outputHandler);
             }
             // Use maybeStatefulExecute for all executions
             // It handles both regular async and generators, detecting checkpoint yields
@@ -2881,6 +3147,7 @@ Run: photon mcp ${mcpName} --config
                 if (execResult.runId) {
                     error.runId = execResult.runId;
                 }
+                span.recordException(error);
                 span.setStatus('ERROR', error.message);
                 auditFinish(null, error);
                 throw error;
@@ -2913,13 +3180,41 @@ Run: photon mcp ${mcpName} --config
         catch (error) {
             // Clear progress on error too
             this.progressRenderer.done();
+            span.recordException(error);
             span.setStatus('ERROR', error instanceof Error ? error.message : String(error));
             auditFinish(null, error);
+            metricsStatus = 'error';
+            metricsErrorType = error instanceof Error ? error.name || 'Error' : 'unknown';
+            // Emit a dedicated counter for rate-limit rejections so dashboards can
+            // alert on sustained throttling without scanning the generic error
+            // stream.
+            if (metricsErrorType === 'PhotonRateLimitError') {
+                recordRateLimitRejection({
+                    photon: mcp.name,
+                    tool: toolName,
+                    instance: mcp.instance?.instanceName,
+                });
+            }
+            else if (metricsErrorType === 'PhotonBulkheadFullError') {
+                recordBulkheadRejection({
+                    photon: mcp.name,
+                    tool: toolName,
+                    instance: mcp.instance?.instanceName,
+                });
+            }
             this.logger.error(`Tool execution failed: ${toolName} - ${getErrorMessage(error)}`);
             throw error;
         }
         finally {
             span.end();
+            recordToolCall({
+                photon: mcp.name,
+                tool: toolName,
+                durationMs: Date.now() - toolStartedAt,
+                status: metricsStatus,
+                errorType: metricsErrorType,
+                stateful: isStateful,
+            });
         }
     }
     normalizeNestedParamsTool(toolMeta, parameters) {
@@ -3048,7 +3343,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) {
@@ -3115,6 +3410,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'
@@ -3163,7 +3482,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
@@ -3188,95 +3518,39 @@ 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,
+                        });
                     }
+                };
+                // Generators must pass through unwrapped - .then() would kill the iterator protocol
+                if (result && typeof result[Symbol.asyncIterator] === 'function') {
+                    return result;
+                }
+                // 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
      *