@portel/photon 1.24.0 → 1.26.0

package/dist/loader.js

@@ -12,7 +12,7 @@ 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 { runWithRequestContext, getRequestContext } from './telemetry/context.js';
 import { spawn, execSync } from 'child_process';
 import { SchemaExtractor, DependencyManager, 
 // Generator utilities (ask/emit pattern from 1.2.0)
@@ -873,27 +873,33 @@ 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.
+                    // Propagate trace context and caller cwd to nested photon-to-photon
+                    // calls so the downstream span chains as a child of the current span
+                    // and the callee can resolve relative paths against the originating
+                    // CLI directory. Uses in-band `_meta` 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;
+                    const metaAdditions = {};
                     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 },
-                            };
-                        }
+                        if (traceparent)
+                            metaAdditions.traceparent = traceparent;
+                        if (ctx.cwd)
+                            metaAdditions.callerCwd = ctx.cwd;
+                    }
+                    if (Object.keys(metaAdditions).length > 0) {
+                        const existingMeta = params?._meta;
+                        forwardedParams = {
+                            ...(params || {}),
+                            _meta: existingMeta && typeof existingMeta === 'object'
+                                ? { ...metaAdditions, ...existingMeta }
+                                : metaAdditions,
+                        };
                     }
                     // Dynamic import to avoid circular dependency
                     const { sendCommand } = await import('./daemon/client.js');
@@ -984,6 +990,20 @@ export class PhotonLoader {
                         configurable: true,
                     });
                 }
+                // Always-inject `this.callerCwd`. Reads the originating CLI cwd from
+                // the request context, falling back to `process.cwd()` when no context
+                // is active (direct in-process load with no caller info). Inside a
+                // daemon worker `process.cwd()` is the daemon's cwd, so photons that
+                // resolve defaults relative to the user's invocation directory must
+                // prefer `this.callerCwd`.
+                if (!('callerCwd' in instance)) {
+                    Object.defineProperty(instance, 'callerCwd', {
+                        get() {
+                            return getRequestContext()?.cwd ?? process.cwd();
+                        },
+                        configurable: true,
+                    });
+                }
                 // Inject call() for cross-photon communication. Always-inject (no
                 // capability-detection gate) because the underlying _callHandler
                 // is ALWAYS wired above. Gating on a regex that matches literal
@@ -1229,7 +1249,17 @@ export class PhotonLoader {
                         permissionHandler?.(request);
                     },
                 });
-                instance.channel = channelFn;
+                // Only inject if 'channel' is not already defined as a getter on the instance/prototype.
+                // Some photons define a private `get channel()` getter for their own internal use —
+                // attempting a plain assignment onto a getter-only property throws in strict mode.
+                const channelDescriptor = Object.getOwnPropertyDescriptor(instance, 'channel') ??
+                    Object.getOwnPropertyDescriptor(Object.getPrototypeOf(instance), 'channel');
+                const channelIsGetter = channelDescriptor?.get !== undefined;
+                if (!channelIsGetter) {
+                    instance.channel = channelFn;
+                }
+                // If the photon already has its own getter for 'channel', skip injection —
+                // the photon is using the name for its own purpose and likely calls this.emit() directly.
             }
             // Check @cli dependencies (required system CLI tools)
             if (tsContent) {
@@ -1246,7 +1276,7 @@ export class PhotonLoader {
                 this.wrapStatefulMethods(instance, tsContent);
             }
             // Extract tools, templates, and statics (with schema override support)
-            const { tools, templates, statics, settingsSchema, auth: extractedAuth, } = await this.extractTools(MCPClass, absolutePath);
+            const { tools, templates, statics, settingsSchema, auth: extractedAuth, httpRoutes: extractedHttpRoutes, } = await this.extractTools(MCPClass, absolutePath);
             // ═══ SETTINGS INJECTION ═══
             // If the photon declared `protected settings = { ... }`, inject persistence + proxy
             if (settingsSchema?.hasSettings &&
@@ -1298,6 +1328,8 @@ export class PhotonLoader {
                 result.stateful = true;
             if (extractedAuth)
                 result.auth = extractedAuth;
+            if (extractedHttpRoutes?.length)
+                result._httpRoutes = extractedHttpRoutes;
             // Store class constructor for static method access
             result.classConstructor = MCPClass;
             // Store settings schema for Beam UI
@@ -1423,8 +1455,34 @@ export class PhotonLoader {
         if (typeof instance._callHandler === 'undefined' || instance._callHandler === undefined) {
             const callBaseDir = this.baseDir;
             instance._callHandler = async (photonName, method, params, targetInstance) => {
+                // Mirror the primary path: propagate trace context and caller cwd via
+                // in-band `_meta` so the callee resolves relative paths against the
+                // originating CLI directory and traces chain across worker boundaries.
+                const ctxMod = await import('./telemetry/context.js');
+                const ctx = ctxMod.getRequestContext();
+                let forwardedParams = params;
+                const metaAdditions = {};
+                if (ctx) {
+                    const traceparent = ctx.parentTraceparent ||
+                        (ctx.traceId
+                            ? `00-${ctx.traceId}-${crypto.randomBytes(8).toString('hex')}-01`
+                            : undefined);
+                    if (traceparent)
+                        metaAdditions.traceparent = traceparent;
+                    if (ctx.cwd)
+                        metaAdditions.callerCwd = ctx.cwd;
+                }
+                if (Object.keys(metaAdditions).length > 0) {
+                    const existingMeta = params?._meta;
+                    forwardedParams = {
+                        ...(params || {}),
+                        _meta: existingMeta && typeof existingMeta === 'object'
+                            ? { ...metaAdditions, ...existingMeta }
+                            : metaAdditions,
+                    };
+                }
                 const { sendCommand } = await import('./daemon/client.js');
-                return sendCommand(photonName, method, params, {
+                return sendCommand(photonName, method, forwardedParams, {
                     workingDir: callBaseDir,
                     targetInstance,
                 });
@@ -1486,6 +1544,15 @@ export class PhotonLoader {
                     configurable: true,
                 });
             }
+            // Always-inject callerCwd (see primary load path for rationale).
+            if (!('callerCwd' in instance)) {
+                Object.defineProperty(instance, 'callerCwd', {
+                    get() {
+                        return getRequestContext()?.cwd ?? process.cwd();
+                    },
+                    configurable: true,
+                });
+            }
             // Always-inject call() (see the primary load path for rationale).
             if (!instance.call) {
                 instance.call = async (target, params = {}, opts) => {
@@ -1566,7 +1633,7 @@ export class PhotonLoader {
         // Call lifecycle hook
         await this.invokeInitialize(instance, name, options);
         // Extract tools and metadata from embedded source (no disk I/O)
-        const { tools, templates, statics, settingsSchema, auth: extractedAuth, } = await this.extractTools(MCPClass, absolutePath, tsContent);
+        const { tools, templates, statics, settingsSchema, auth: extractedAuth, httpRoutes: extractedHttpRoutes, } = await this.extractTools(MCPClass, absolutePath, tsContent);
         // Settings injection
         if (settingsSchema?.hasSettings && instance.settings && typeof instance.settings === 'object') {
             const instanceName = options?.instanceName || 'default';
@@ -1598,6 +1665,8 @@ export class PhotonLoader {
             result.stateful = true;
         if (extractedAuth)
             result.auth = extractedAuth;
+        if (extractedHttpRoutes?.length)
+            result._httpRoutes = extractedHttpRoutes;
         result.classConstructor = MCPClass;
         if (settingsSchema?.hasSettings) {
             result.settingsSchema = settingsSchema;
@@ -1751,6 +1820,21 @@ export class PhotonLoader {
         }
         return cleaned;
     }
+    /**
+     * Extract @get and @post HTTP route declarations from photon source.
+     * Methods tagged with @get or @post are HTTP-only and must NOT appear as MCP tools.
+     */
+    extractHttpRoutesFromSource(source) {
+        const routes = [];
+        // Match JSDoc blocks that contain @get or @post followed by the async method name.
+        // Pattern: /** ... @get /path ... */ async methodName(
+        const routeRe = /\/\*\*[\s\S]*?@(get|post)\s+(\/[^\s*]*)[\s\S]*?\*\/\s*(?:async\s+)?(\w+)\s*\(/gi;
+        let m;
+        while ((m = routeRe.exec(source)) !== null) {
+            routes.push({ method: m[1].toUpperCase(), path: m[2], handler: m[3] });
+        }
+        return routes;
+    }
     /**
      * Extract tools, templates, and statics from a class
      */
@@ -1821,8 +1905,11 @@ export class PhotonLoader {
                     const extractor = new SchemaExtractor();
                     const source = sourceContent || (await readText(sourceFilePath));
                     const metadata = extractor.extractAllFromSource(source);
-                    // Filter by method names that exist in the class
-                    tools = metadata.tools.filter((t) => methodNames.includes(t.name));
+                    // Extract @get/@post HTTP routes from source (not in photon-core SchemaExtractor)
+                    const httpRoutesFromSource = this.extractHttpRoutesFromSource(source);
+                    const routeHandlerNames = new Set(httpRoutesFromSource.map((r) => r.handler));
+                    // Filter by method names that exist in the class; exclude HTTP-route methods from tools
+                    tools = metadata.tools.filter((t) => methodNames.includes(t.name) && !routeHandlerNames.has(t.name));
                     templates = metadata.templates.filter((t) => methodNames.includes(t.name));
                     statics = metadata.statics.filter((s) => methodNames.includes(s.name));
                     this.log(`Extracted ${tools.length} tools, ${templates.length} templates, ${statics.length} statics from source`);
@@ -1853,6 +1940,7 @@ export class PhotonLoader {
                         statics,
                         settingsSchema: metadata.settingsSchema,
                         auth: this.extractAuthTag(source),
+                        httpRoutes: httpRoutesFromSource.length ? httpRoutesFromSource : undefined,
                     };
                 }
                 throw jsonError;
@@ -3007,16 +3095,21 @@ 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()`.
+        // Resolve parentTraceparent and callerCwd from options or in-band `_meta`
+        // so the ALS context reflects the true parent for any nested `this.call()`
+        // and the originating CLI invocation directory propagates through worker
+        // boundaries.
         let resolvedParentTraceparent = options?.parentTraceparent;
-        if (!resolvedParentTraceparent &&
-            parameters &&
-            typeof parameters === 'object' &&
-            '_meta' in parameters) {
+        let resolvedCallerCwd;
+        if (parameters && typeof parameters === 'object' && '_meta' in parameters) {
             const metaPeek = parameters._meta;
-            if (metaPeek && typeof metaPeek.traceparent === 'string') {
-                resolvedParentTraceparent = metaPeek.traceparent;
+            if (metaPeek) {
+                if (!resolvedParentTraceparent && typeof metaPeek.traceparent === 'string') {
+                    resolvedParentTraceparent = metaPeek.traceparent;
+                }
+                if (typeof metaPeek.callerCwd === 'string') {
+                    resolvedCallerCwd = metaPeek.callerCwd;
+                }
             }
         }
         const run = () => runWithRequestContext({
@@ -3025,6 +3118,7 @@ Run: photon mcp ${mcpName} --config
             traceId: options?.traceId,
             parentTraceparent: resolvedParentTraceparent,
             caller: options?.caller,
+            cwd: resolvedCallerCwd,
             startedAt: Date.now(),
         }, () => this._executeToolInner(mcp, toolName, parameters, {
             ...options,