@portel/photon 1.23.1 → 1.25.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)
@@ -164,6 +164,68 @@ function injectEmitHelpers(instance) {
 function detectEmitHelperUsage(source) {
     return /this\.(toast|log|status|progress|thinking)\s*\(/.test(source);
 }
+/**
+ * Always-inject `this.sample`, `this.confirm`, and `this.elicit` on plain
+ * classes. Each pulls its provider out of the ALS execution context
+ * (set by the loader when it invokes a tool). User-defined methods on
+ * the class win — these wrappers only fill in when absent.
+ *
+ * Mirrors the Photon base class implementations in photon-core/base.ts,
+ * so a plain class and a class that extends Photon behave identically.
+ */
+function injectSamplingAndElicitation(instance) {
+    if (!instance.confirm) {
+        instance.confirm = async (question) => {
+            const store = executionContext.getStore();
+            if (!store?.inputProvider) {
+                throw new Error('this.confirm() requires a connected MCP client that supports ' +
+                    'elicitation. None is attached to the current invocation.');
+            }
+            const result = await store.inputProvider({
+                ask: 'confirm',
+                question,
+                message: question,
+            });
+            return Boolean(result);
+        };
+    }
+    if (!instance.elicit) {
+        instance.elicit = async (params) => {
+            const store = executionContext.getStore();
+            if (!store?.inputProvider) {
+                throw new Error('this.elicit() requires a connected MCP client that supports ' +
+                    'elicitation. None is attached to the current invocation.');
+            }
+            return await store.inputProvider(params);
+        };
+    }
+    if (!instance.sample) {
+        instance.sample = async (params) => {
+            const store = executionContext.getStore();
+            if (!store?.samplingProvider) {
+                throw new Error('this.sample() requires the connected MCP client to declare the ' +
+                    '`sampling` capability. None is available in this invocation.');
+            }
+            if (!params.prompt && !params.messages?.length) {
+                throw new Error('this.sample() requires either `prompt` or `messages`.');
+            }
+            const messages = params.messages ?? [
+                { role: 'user', content: { type: 'text', text: params.prompt } },
+            ];
+            const result = await store.samplingProvider({
+                messages,
+                systemPrompt: params.systemPrompt,
+                maxTokens: params.maxTokens ?? 1024,
+                temperature: params.temperature,
+                modelPreferences: params.modelPreferences,
+                stopSequences: params.stopSequences,
+                includeContext: params.includeContext,
+            });
+            const first = Array.isArray(result.content) ? result.content[0] : result.content;
+            return first?.type === 'text' ? first.text : '';
+        };
+    }
+}
 /**
  * Render a formatted value in the CLI using @portel/cli's formatOutput.
  * Uses clear-and-replace semantics — each call overwrites the previous render.
@@ -230,6 +292,14 @@ export class PhotonLoader {
     marketplaceManager;
     marketplaceManagerPromise;
     logger;
+    /**
+     * Per-instance call queue. Two tool invocations targeting the same photon
+     * instance are serialized: the second starts only after the first returns.
+     * Prevents lost-update and read-after-write races between methods that share
+     * state via `this.memory` or instance fields. Keyed on the instance object
+     * via WeakMap so hot-reload drops the queue automatically.
+     */
+    _instanceCallTails = new WeakMap();
     // ════════════════════════════════════════════════════════════════════════════
     // MIDDLEWARE STATE
     // ════════════════════════════════════════════════════════════════════════════
@@ -695,6 +765,31 @@ export class PhotonLoader {
             instance.instanceName = options?.instanceName ?? '';
             // Inject file path for storage()/assets() resolution
             instance._photonFilePath = absolutePath;
+            // Inject schedule-unschedule hook so `this.schedule.cancel()` evicts
+            // the in-memory cron registration at the same time as unlinking
+            // the file. Prevents ghost schedule registrations — the scenario
+            // where a cancel + re-enable under the same name leaves the old
+            // cron firing in parallel with the new one until the next daemon
+            // restart. The hook is best-effort: if the daemon is unreachable
+            // the fire-time phantom-prune (daemon checks sourceFile before
+            // running) catches the ghost on its next tick.
+            const photonNameForSchedule = name;
+            const scheduleLogger = this.logger;
+            instance._scheduleUnscheduleHook = async (jobId) => {
+                try {
+                    const { unscheduleJob } = await import('./daemon/client.js');
+                    return await unscheduleJob(photonNameForSchedule, jobId);
+                }
+                catch (err) {
+                    // Daemon unreachable or IPC failure — log loudly so operators
+                    // notice. Phantom-prune (daemon checks sourceFile before
+                    // running) still evicts the ghost on its next fire, but for
+                    // low-frequency schedules that may be hours away. Returning
+                    // false lets `schedule.cancel` surface the outcome too.
+                    scheduleLogger.warn(`[schedule] failed to evict in-memory cron registration for ${photonNameForSchedule}:${jobId}`, { error: err instanceof Error ? err.message : String(err) });
+                    return false;
+                }
+            };
             // Inject this.shell — execSync wrapper with cwd defaulted to the
             // photon's own folder. Shelling out from a photon method should run
             // from where the photon lives, not the daemon's cwd, so that
@@ -778,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');
@@ -866,8 +967,18 @@ export class PhotonLoader {
                     // Inject convenience helpers (render, toast, log, status, progress, thinking)
                     injectEmitHelpers(instance);
                 }
-                if (caps.has('memory')) {
-                    // Inject lazy memory provider — capture baseDir from loader context
+                // Always-inject lazy memory provider. The getter is a pure closure
+                // that constructs MemoryProvider on first access — zero cost until
+                // used. Gating this on a regex (`detectCapabilities`) missed TS
+                // cast shapes with function-type parens like
+                // `(this as unknown as { memory: { set: (k: string) => void } })` —
+                // the classic TypeScript workaround when memory isn't on the
+                // declared class — and silently left `this.memory` undefined. That
+                // turned every `.memory.set(...)` call into a data-loss bug that
+                // only surfaced on daemon cold start.
+                // User-defined memory wins; `in` walks the prototype chain
+                // so Photon-base getters aren't silently shadowed.
+                if (!('memory' in instance)) {
                     const memoryBaseDir = this.baseDir;
                     Object.defineProperty(instance, 'memory', {
                         get() {
@@ -879,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
@@ -915,6 +1040,13 @@ export class PhotonLoader {
                         return client;
                     };
                 }
+                // Always-inject sample/confirm/elicit helpers. These read the
+                // relevant provider from the ALS execution context the loader
+                // populates when it invokes a tool. Injections are pure closures —
+                // zero cost until the method uses them. Matches the always-inject
+                // philosophy: detection-gate misses mean silent breakage, so don't
+                // gate cheap capabilities. User-defined methods win.
+                injectSamplingAndElicitation(instance);
                 // Always-inject caller getter. The prototype check preserves any
                 // user-defined getter on the class (e.g. Photon base class has its
                 // own) so we don't clobber.
@@ -955,8 +1087,10 @@ export class PhotonLoader {
                         },
                     };
                 }
-                if (caps.has('instanceMeta')) {
-                    // Inject instance metadata (file-stat-based timestamps)
+                // Always-inject instance metadata. One file-stat call per load is
+                // cheap and avoids the same detection-gate trap as memory. User-
+                // defined instanceMeta on the class wins.
+                if (!instance.instanceMeta) {
                     const instanceName = options?.instanceName || 'default';
                     const stateFile = getInstanceStatePath(name, instanceName, this.baseDir);
                     try {
@@ -1309,8 +1443,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,
                 });
@@ -1359,7 +1519,8 @@ export class PhotonLoader {
                 // Inject convenience helpers (render, toast, log, status, progress, thinking)
                 injectEmitHelpers(instance);
             }
-            if (caps.has('memory')) {
+            // Always-inject memory (see primary load path for rationale).
+            if (!('memory' in instance)) {
                 const memoryBaseDir = this.baseDir;
                 Object.defineProperty(instance, 'memory', {
                     get() {
@@ -1371,6 +1532,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) => {
@@ -1384,6 +1554,8 @@ export class PhotonLoader {
                     return instance._callHandler(target.slice(0, dotIndex), target.slice(dotIndex + 1), params, opts?.instance);
                 };
             }
+            // Always-inject sample/confirm/elicit (see primary load path).
+            injectSamplingAndElicitation(instance);
         }
         // Channel event capability: inject on()/off()/_dispatch()/_matchesFilter()
         // when source uses this._dispatch( — the universal channel dispatch pattern.
@@ -2890,29 +3062,63 @@ 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;
+                }
             }
         }
-        return runWithRequestContext({
+        const run = () => runWithRequestContext({
             photon: mcp.name,
             tool: toolName,
             traceId: options?.traceId,
             parentTraceparent: resolvedParentTraceparent,
             caller: options?.caller,
+            cwd: resolvedCallerCwd,
             startedAt: Date.now(),
         }, () => this._executeToolInner(mcp, toolName, parameters, {
             ...options,
             parentTraceparent: resolvedParentTraceparent,
         }));
+        const gateKey = mcp.instance;
+        if (!gateKey)
+            return run();
+        return this._withInstanceGate(gateKey, run);
+    }
+    /**
+     * Serialize calls targeting the same photon instance. Concurrent callers
+     * queue behind the current in-flight call; each invocation gets an exclusive
+     * slot for the duration of its method body (including all awaits), so two
+     * methods that touch shared state via `this.memory` cannot interleave.
+     */
+    async _withInstanceGate(instance, fn) {
+        const prev = this._instanceCallTails.get(instance) ?? Promise.resolve();
+        let release;
+        const tail = new Promise((r) => {
+            release = r;
+        });
+        this._instanceCallTails.set(instance, tail);
+        try {
+            await prev;
+            return await fn();
+        }
+        finally {
+            release();
+            if (this._instanceCallTails.get(instance) === tail) {
+                this._instanceCallTails.delete(instance);
+            }
+        }
     }
     async _executeToolInner(mcp, toolName, parameters, options) {
         // Start audit trail recording
@@ -3210,9 +3416,19 @@ Run: photon mcp ${mcpName} --config
             }
             let generatorFn = isStatic
                 ? () => method.call(null, ...args)
-                : () => executionContext.run({
+                : () => executionContext.run(
+                // inputProvider and samplingProvider are attached to the ALS
+                // store so photon-core's `this.confirm()`, `this.elicit()`,
+                // and `this.sample()` can find them without every method
+                // having to accept runtime plumbing as an argument. The
+                // @portel/cli ExecutionContext type doesn't declare these
+                // optional fields, so the object is cast through `unknown`;
+                // photon-core reads them back with matching casts.
+                {
                     outputHandler: outputHandler,
                     caller: options?.caller,
+                    inputProvider,
+                    samplingProvider: options?.samplingProvider,
                 }, () => {
                     return method.call(mcp.instance, ...args);
                 });