@portel/photon 1.28.2 → 1.31.0

package/dist/loader.js

@@ -6,7 +6,11 @@
 import * as fs from 'fs/promises';
 import { realpathSync, existsSync, mkdirSync, symlinkSync, readFileSync, statSync, } from 'fs';
 import { readText, readJSON, writeText, writeJSON } from './shared/io.js';
+import { parseCfBindings } from './cf-bindings-parser.js';
+import { CFLocalRuntime, mergeBindings } from './runtime/cf-local.js';
+import { scanCfUsage } from './cf-usage-scanner.js';
 import { extractHttpRoutesFromSource } from './shared/http-route-extractor.js';
+import { extractExposesFromSource } from './shared/expose-route-extractor.js';
 import { createRequire } from 'module';
 import * as path from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
@@ -27,7 +31,7 @@ ProgressRenderer,
 // CLI formatting
 formatOutput as cliFormatOutput, createMCPProxy, MCPConfigurationError, SDKMCPClientFactory, resolveMCPSource, 
 // Photon runtime configuration
-loadPhotonMCPConfig, resolveEnvVars, isClass as sharedIsClass, findPhotonClass as sharedFindPhotonClass, parseEnvValue as sharedParseEnvValue, compilePhotonTS, parseRuntimeRequirement, checkRuntimeCompatibility, discoverAssets as sharedDiscoverAssets, 
+loadPhotonMCPConfig, resolveEnvVars, isClass as sharedIsClass, findPhotonClass as sharedFindPhotonClass, parseEnvValue as sharedParseEnvValue, compilePhotonTS, parseRuntimeRequirement, checkRuntimeCompatibility, 
 // Execution audit trail
 getAuditTrail, 
 // Capability detection for auto-injection
@@ -48,6 +52,8 @@ import { PHOTON_VERSION, getResolvedPhotonCoreVersion } from './version.js';
 // Timeout for external fetch requests (marketplace, GitHub)
 const FETCH_TIMEOUT_MS = 30 * 1000;
 import { generateConfigErrorMessage, summarizeConstructorParams } from './shared/config-docs.js';
+import { SettingsPersistence } from './settings-persistence.js';
+import { AssetResolver } from './asset-resolver.js';
 import { createLogger } from './shared/logger.js';
 import { getErrorMessage } from './shared/error-handler.js';
 import { validateOrThrow, assertString, notEmpty, hasExtension } from './shared/validation.js';
@@ -141,26 +147,71 @@ export function clearRenderZone() {
  */
 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 });
+    // User-declared methods always win — these helpers only fill in when absent.
+    // `in` walks the prototype chain so user methods on the class aren't shadowed
+    // by injected closures. Without the guards, a photon that declares `@get
+    // /status` (or any method named `render`/`toast`/`log`/`progress`/`thinking`)
+    // sees its handler clobbered and the dispatcher invokes the emit closure
+    // instead, which returns undefined and produces a hung response.
+    if (!('render' in instance)) {
+        // 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 });
+        };
+    }
+    if (!('toast' in instance)) {
+        instance.toast = (message, opts = {}) => emit({ emit: 'toast', message, ...opts });
+    }
+    if (!('log' in instance)) {
+        instance.log = (message, opts = {}) => emit({ emit: 'log', message, level: opts.level ?? 'info', data: opts.data });
+    }
+    if (!('status' in instance)) {
+        instance.status = (message) => emit({ emit: 'status', message });
+    }
+    if (!('progress' in instance)) {
+        instance.progress = (value, message) => emit({ emit: 'progress', value, message });
+    }
+    if (!('thinking' in instance)) {
+        instance.thinking = (active = true) => emit({ emit: 'thinking', active });
+    }
+}
+/** True when the scanner detected any CF usage that warrants attaching a runtime. */
+function cfUsageNonEmpty(usage) {
+    for (const cat of ['kv', 'r2', 'd1', 'queue', 'vectorize']) {
+        if (usage.qualifiers[cat].size > 0)
+            return true;
+    }
+    return usage.shared.ai || usage.shared.images || usage.shared.browser;
+}
+/** Short, log-friendly summary of which CF surfaces a photon reaches for. */
+function describeUsage(usage, declared) {
+    const parts = [];
+    for (const cat of ['kv', 'r2', 'd1', 'queue', 'vectorize']) {
+        if (usage.qualifiers[cat].size > 0)
+            parts.push(`${cat}×${usage.qualifiers[cat].size}`);
+    }
+    if (usage.shared.ai)
+        parts.push('ai');
+    if (usage.shared.images)
+        parts.push('images');
+    if (usage.shared.browser)
+        parts.push('browser');
+    if (parts.length === 0 && declared)
+        parts.push('overrides-only');
+    return parts.join(', ') || 'cf';
 }
 /** Extra regex checks that force 'emit' capability when helper methods are used. */
 function detectEmitHelperUsage(source) {
@@ -217,6 +268,15 @@ function injectSamplingAndElicitation(instance) {
             return await store.inputProvider(params);
         };
     }
+    if (!Object.getOwnPropertyDescriptor(Object.getPrototypeOf(instance), 'roots')) {
+        Object.defineProperty(instance, 'roots', {
+            get() {
+                const store = executionContext.getStore();
+                return store?.roots ?? [];
+            },
+            configurable: true,
+        });
+    }
     if (!instance.sample) {
         instance.sample = async (params) => {
             const store = executionContext.getStore();
@@ -242,6 +302,37 @@ function injectSamplingAndElicitation(instance) {
         };
     }
 }
+/**
+ * Inject `this.notifyResourceUpdated(uri)` so `@resource` photon authors can
+ * fan out `notifications/resources/updated` to subscribed clients.
+ *
+ * Unlike sample/elicit/confirm — which fire only inside a tool call and so can
+ * read their provider from `executionContext.getStore()` — resource updates
+ * commonly fire from setInterval, event handlers, or async paths that resolved
+ * after the triggering tool returned. We close over a notifier passed in by
+ * the loader (sourced from PhotonServer's SubscriptionRegistry) so the helper
+ * keeps working outside the ALS context.
+ *
+ * No-op if the runtime has no notifier wired (e.g. CLI execution outside an
+ * MCP server). User-defined methods on the class win.
+ */
+function injectResourceNotifier(instance, notifier) {
+    // Only skip if the instance itself (own property, not via prototype/base
+    // class) has a user-defined override. Otherwise install the wired version
+    // on the instance, shadowing any base-class default.
+    if (Object.prototype.hasOwnProperty.call(instance, 'notifyResourceUpdated'))
+        return;
+    instance.notifyResourceUpdated = (uri) => {
+        if (!notifier)
+            return;
+        try {
+            void notifier(uri);
+        }
+        catch {
+            // Notifier failures must never propagate into photon code.
+        }
+    };
+}
 /**
  * Render a formatted value in the CLI using @portel/cli's formatOutput.
  * Uses clear-and-replace semantics — each call overwrites the previous render.
@@ -308,6 +399,14 @@ export class PhotonLoader {
     marketplaceManager;
     marketplaceManagerPromise;
     logger;
+    settingsPersistence;
+    assetResolver;
+    /**
+     * One CFLocalRuntime per photon name. Boot is lazy inside the runtime
+     * itself; this cache just ensures every instance of a given photon
+     * shares a single miniflare sandbox.
+     */
+    cfRuntimes = new Map();
     /**
      * Per-instance call queue. Two tool invocations targeting the same photon
      * instance are serialized: the second starts only after the first returns.
@@ -369,6 +468,8 @@ export class PhotonLoader {
         this.verbose = verbose;
         this.logger = logger ?? createLogger({ component: 'photon-loader', minimal: true });
         this.baseDir = baseDir || getDefaultContext().baseDir;
+        this.settingsPersistence = new SettingsPersistence(this.baseDir, (msg, meta) => this.log(msg, meta));
+        this.assetResolver = new AssetResolver((msg, meta) => this.log(msg, meta));
     }
     /**
      * Load MCP configuration from ~/.photon/config.json
@@ -390,6 +491,63 @@ export class PhotonLoader {
         });
         return this.mcpConfigPromise;
     }
+    /**
+     * Resolve the path where a photon's CF binding override JSON lives.
+     * The override layers on top of `protected cfBindings` so users can
+     * repoint a binding (e.g., point `kv: cache` at a different namespace)
+     * without editing source.
+     */
+    getCfOverridePath(photonName) {
+        return path.join(this.baseDir, '.data', 'cf-overrides', `${photonName}.json`);
+    }
+    /** Load the per-photon CF override JSON. Returns null if missing. */
+    async loadCfOverride(photonName) {
+        try {
+            return await readJSON(this.getCfOverridePath(photonName));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Persist the CF override for a photon. Creates parent directories as
+     * needed; called by the `photon cf set` CLI command.
+     */
+    async saveCfOverride(photonName, override) {
+        const overridePath = this.getCfOverridePath(photonName);
+        await fs.mkdir(path.dirname(overridePath), { recursive: true });
+        await writeJSON(overridePath, override);
+        return overridePath;
+    }
+    /**
+     * Build (or fetch the cached) CFLocalRuntime for `photonName`. Uses
+     * the new options-form constructor so auto-naming applies and
+     * miniflare seeds every literal qualifier the scanner found, plus
+     * any override-declared bindings.
+     */
+    async attachCfRuntime(photonName, usage, declared) {
+        let runtime = this.cfRuntimes.get(photonName);
+        if (runtime)
+            return runtime;
+        const overrideJson = await this.loadCfOverride(photonName);
+        const overrides = mergeBindings(declared, overrideJson);
+        runtime = new CFLocalRuntime({
+            photonName,
+            baseDir: this.baseDir,
+            usage,
+            overrides,
+        });
+        this.cfRuntimes.set(photonName, runtime);
+        return runtime;
+    }
+    /** Read the effective bindings for a photon: declared (from source) plus override. */
+    async getEffectiveCfBindings(photonName, tsContent) {
+        const declared = parseCfBindings(tsContent);
+        if (!declared)
+            return { declared: null, override: null, effective: null };
+        const override = await this.loadCfOverride(photonName);
+        return { declared, override, effective: mergeBindings(declared, override) };
+    }
     async getMarketplaceManager() {
         if (this.marketplaceManager) {
             return this.marketplaceManager;
@@ -411,6 +569,16 @@ export class PhotonLoader {
     setMCPClientFactory(factory) {
         this.mcpClientFactory = factory;
     }
+    /**
+     * Notifier wired by PhotonServer so `this.notifyResourceUpdated(uri)`
+     * fans out to all subscribed MCP clients (STDIO + SSE sessions).
+     * `undefined` outside the MCP-server runtime, in which case the helper is
+     * a no-op.
+     */
+    resourceUpdateNotifier;
+    setResourceUpdateNotifier(notifier) {
+        this.resourceUpdateNotifier = notifier;
+    }
     /**
      * Log message only if verbose mode is enabled
      */
@@ -487,6 +655,18 @@ export class PhotonLoader {
         await this.clearDependencyCache(cacheKey);
         await this.clearBuildCache(cacheKey);
     }
+    /**
+     * Clear all caches for a photon identified by file path.
+     * Called by Beam when a photon fails to load, so the next reload
+     * recompiles from source rather than using stale cached artifacts.
+     */
+    async clearCacheForFile(filePath) {
+        const absolutePath = path.resolve(filePath);
+        const mcpName = path.basename(absolutePath, '.ts').replace('.photon', '');
+        const cacheKey = this.getCacheKey(mcpName, absolutePath);
+        await this.clearAllCaches(cacheKey);
+        this.log(`🗑️  Cache cleared for ${mcpName} (auto-retry after load failure)`);
+    }
     /**
      * Path to metadata file describing installed dependencies
      */
@@ -604,6 +784,11 @@ export class PhotonLoader {
             message.includes('Cannot find module') ||
             message.includes('require is not defined'));
     }
+    isCompilationServiceError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return (message.includes('The service was stopped') ||
+            message.includes('The service is no longer running'));
+    }
     static parseDependenciesFromSource(source) {
         const deps = [];
         // Only match @dependencies inside JSDoc blocks (/** ... */)
@@ -731,6 +916,12 @@ export class PhotonLoader {
                     module = await importModule();
                 }
                 else {
+                    if (this.isCompilationServiceError(error) && cacheKey) {
+                        // Compiler process crashed — clear the build cache so the next startup
+                        // recompiles from source instead of finding a stale or missing artifact.
+                        await this.clearBuildCache(cacheKey);
+                        this.log(`⚠️  Compiler service crashed for ${mcpName || 'unknown'}, build cache cleared. Restart to recover.`);
+                    }
                     throw error;
                 }
             }
@@ -1017,6 +1208,12 @@ export class PhotonLoader {
                         configurable: true,
                     });
                 }
+                // `this.cf` is no longer always-injected. The CF runtime
+                // injection block above sets `instance.cf` directly when the
+                // photon either references the surface (scanner detection) or
+                // declares `protected cfBindings`. Plain photons that never
+                // touch CF leave `this.cf` undefined — a plain runtime error
+                // beats a throwing-Proxy stub for the diagnostic.
                 // 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
@@ -1074,6 +1271,7 @@ export class PhotonLoader {
                 // philosophy: detection-gate misses mean silent breakage, so don't
                 // gate cheap capabilities. User-defined methods win.
                 injectSamplingAndElicitation(instance);
+                injectResourceNotifier(instance, this.resourceUpdateNotifier);
                 // 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.
@@ -1303,16 +1501,34 @@ export class PhotonLoader {
                 this.wrapStatefulMethods(instance, tsContent);
             }
             // Extract tools, templates, and statics (with schema override support)
-            const { tools, templates, statics, settingsSchema, auth: extractedAuth, httpRoutes: extractedHttpRoutes, } = await this.extractTools(MCPClass, absolutePath);
+            const { tools, templates, statics, settingsSchema, auth: extractedAuth, httpRoutes: extractedHttpRoutes, exposes: extractedExposes, } = await this.extractTools(MCPClass, absolutePath);
+            // ═══ CF RUNTIME INJECTION ═══
+            // The photon's CF surface comes from the new `Cloudflare` injection
+            // (constructor param typed `Cloudflare`, or the forgiving `this.cf.*`
+            // path on plain classes). The scanner discovers literal qualifiers
+            // so miniflare seeds them up front; `protected cfBindings` is now
+            // an optional override layer for repointing bindings at pre-existing
+            // CF resources.
+            if (tsContent) {
+                const usage = scanCfUsage(tsContent);
+                const overrides = parseCfBindings(tsContent);
+                const photonUsesCf = cfUsageNonEmpty(usage) || overrides !== null;
+                if (photonUsesCf) {
+                    const runtime = await this.attachCfRuntime(name, usage, overrides);
+                    instance.cf = runtime;
+                    const what = describeUsage(usage, overrides);
+                    this.log(`☁️  CF runtime attached to ${name} (${what})`);
+                }
+            }
             // ═══ SETTINGS INJECTION ═══
             // If the photon declared `protected settings = { ... }`, inject persistence + proxy
             if (settingsSchema?.hasSettings &&
                 instance.settings &&
                 typeof instance.settings === 'object') {
                 const instanceName = options?.instanceName || 'default';
-                await this.injectSettings(instance, name, instanceName, settingsSchema);
+                await this.settingsPersistence.inject(instance, name, instanceName, settingsSchema);
                 // Auto-generate the `settings` MCP tool from the schema
-                const settingsTool = this.generateSettingsTool(settingsSchema);
+                const settingsTool = this.settingsPersistence.generateTool(settingsSchema);
                 tools.push(settingsTool);
                 this.log(`⚙️  Settings tool auto-generated for ${name} (${settingsSchema.properties.length} props)`);
             }
@@ -1321,8 +1537,8 @@ export class PhotonLoader {
                 this.logger.warn(`⚠️  ${name}: configure() method is deprecated. Use 'protected settings = { ... }' property instead.`);
             }
             // Extract assets from source and discover asset folder
-            const assets = await this.discoverAssets(absolutePath, tsContent || '');
-            this.attachAssetsToInstance(instance, assets);
+            const assets = await this.assetResolver.discover(absolutePath, tsContent || '');
+            this.assetResolver.attachToInstance(instance, assets);
             const counts = [
                 tools.length > 0 ? `${tools.length} tools` : null,
                 templates.length > 0 ? `${templates.length} templates` : null,
@@ -1357,6 +1573,8 @@ export class PhotonLoader {
                 result.auth = extractedAuth;
             if (extractedHttpRoutes?.length)
                 result._httpRoutes = extractedHttpRoutes;
+            if (extractedExposes?.length)
+                result._exposes = extractedExposes;
             // Store class constructor for static method access
             result.classConstructor = MCPClass;
             // Store settings schema for Beam UI
@@ -1595,6 +1813,7 @@ export class PhotonLoader {
             }
             // Always-inject sample/confirm/elicit (see primary load path).
             injectSamplingAndElicitation(instance);
+            injectResourceNotifier(instance, this.resourceUpdateNotifier);
         }
         // Channel event capability: inject on()/off()/_dispatch()/_matchesFilter()
         // when source uses this._dispatch( — the universal channel dispatch pattern.
@@ -1660,16 +1879,26 @@ 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, httpRoutes: extractedHttpRoutes, } = await this.extractTools(MCPClass, absolutePath, tsContent);
+        const { tools, templates, statics, settingsSchema, auth: extractedAuth, httpRoutes: extractedHttpRoutes, exposes: extractedExposes, } = await this.extractTools(MCPClass, absolutePath, tsContent);
+        // CF runtime injection (mirrors the loadFile path above)
+        if (tsContent) {
+            const usage = scanCfUsage(tsContent);
+            const overrides = parseCfBindings(tsContent);
+            const photonUsesCf = cfUsageNonEmpty(usage) || overrides !== null;
+            if (photonUsesCf) {
+                const runtime = await this.attachCfRuntime(name, usage, overrides);
+                instance.cf = runtime;
+            }
+        }
         // Settings injection
         if (settingsSchema?.hasSettings && instance.settings && typeof instance.settings === 'object') {
             const instanceName = options?.instanceName || 'default';
-            await this.injectSettings(instance, name, instanceName, settingsSchema);
-            tools.push(this.generateSettingsTool(settingsSchema));
+            await this.settingsPersistence.inject(instance, name, instanceName, settingsSchema);
+            tools.push(this.settingsPersistence.generateTool(settingsSchema));
         }
         // Discover assets (for @ui)
-        const assets = await this.discoverAssets(absolutePath, tsContent);
-        this.attachAssetsToInstance(instance, assets);
+        const assets = await this.assetResolver.discover(absolutePath, tsContent);
+        this.assetResolver.attachToInstance(instance, assets);
         this.log(`✅ Loaded (preloaded): ${name} (${tools.length} tools)`);
         // Extract class-level metadata from docblock (icon, description, stateful)
         const classDocblock = this.extractClassDocblock(tsContent);
@@ -1694,6 +1923,8 @@ export class PhotonLoader {
             result.auth = extractedAuth;
         if (extractedHttpRoutes?.length)
             result._httpRoutes = extractedHttpRoutes;
+        if (extractedExposes?.length)
+            result._exposes = extractedExposes;
         result.classConstructor = MCPClass;
         if (settingsSchema?.hasSettings) {
             result.settingsSchema = settingsSchema;
@@ -1742,7 +1973,10 @@ export class PhotonLoader {
             const files = await fs.readdir(buildDir).catch(() => []);
             for (const f of files) {
                 if (f.startsWith(fileName) && f.endsWith('.mjs')) {
-                    await fs.unlink(path.join(buildDir, f)).catch(() => { });
+                    await fs.unlink(path.join(buildDir, f)).catch((err) => this.logger.debug('Failed to remove stale cache file', {
+                        file: f,
+                        error: String(err),
+                    }));
                 }
             }
         }
@@ -1954,6 +2188,15 @@ export class PhotonLoader {
                             }
                         });
                     }
+                    // Track C: capture @expose'd methods so the runtime dispatcher
+                    // can auto-bind them at /api/<kebab>. We only honour declarations
+                    // for methods the class actually defines (mirrors the tool/route
+                    // filter above) so a stray comment never opens a phantom
+                    // endpoint. Methods that already carry an explicit @get/@post are
+                    // excluded so the user's path/verb wins — the auto-RPC slot only
+                    // fills *unclaimed* spots.
+                    const httpRouteHandlers = new Set(httpRoutesFromSource.map((r) => r.handler));
+                    const exposesFromSource = extractExposesFromSource(source).filter((e) => methodNames.includes(e.handler) && !httpRouteHandlers.has(e.handler));
                     return {
                         tools,
                         templates,
@@ -1961,6 +2204,7 @@ export class PhotonLoader {
                         settingsSchema: metadata.settingsSchema,
                         auth: this.extractAuthTag(source),
                         httpRoutes: httpRoutesFromSource.length ? httpRoutesFromSource : undefined,
+                        exposes: exposesFromSource.length ? exposesFromSource : undefined,
                     };
                 }
                 throw jsonError;
@@ -1986,199 +2230,9 @@ export class PhotonLoader {
         statics = statics.map((s) => ({ ...s, description: this.stripJSDocTags(s.description) }));
         return { tools, templates, statics };
     }
-    // ════════════════════════════════════════════════════════════════════════════
-    // SETTINGS — property-driven configuration with auto-persistence
-    // ════════════════════════════════════════════════════════════════════════════
-    /**
-     * Get the settings persistence path for a photon instance.
-     * Co-located with state under Option B: the settings JSON lives next to
-     * state.json inside the per-instance directory.
-     */
-    getSettingsPath(photonName, instanceName) {
-        // getInstanceStatePath returns `.../state/{instance}/state.json`; swap
-        // the filename so settings land at `.../state/{instance}/settings.json`.
-        // Keeps the source of truth for the layout in context-store.
-        const statePath = getInstanceStatePath(photonName, instanceName, this.baseDir);
-        return path.join(path.dirname(statePath), 'settings.json');
-    }
-    /**
-     * Load persisted settings from disk
-     */
-    async loadSettings(photonName, instanceName) {
-        const settingsPath = this.getSettingsPath(photonName, instanceName);
-        try {
-            return await readJSON(settingsPath);
-        }
-        catch {
-            return {};
-        }
-    }
-    /**
-     * Persist settings to disk
-     */
-    async persistSettings(photonName, instanceName, values) {
-        const settingsPath = this.getSettingsPath(photonName, instanceName);
-        const dir = path.dirname(settingsPath);
-        await fs.mkdir(dir, { recursive: true });
-        await writeJSON(settingsPath, values);
-    }
-    /**
-     * Inject settings into a photon instance:
-     * - Load persisted values (persisted wins over defaults)
-     * - Replace instance.settings with a read-only Proxy
-     * - Store writable backing object for the settings tool
-     */
-    async injectSettings(instance, photonName, instanceName, schema) {
-        const defaults = instance.settings;
-        const persisted = await this.loadSettings(photonName, instanceName);
-        // Merge: persisted values over defaults
-        const backing = { ...defaults };
-        for (const key of Object.keys(persisted)) {
-            if (persisted[key] !== undefined) {
-                backing[key] = persisted[key];
-            }
-        }
-        // Store the writable backing object for the settings tool to update
-        instance._settingsBacking = backing;
-        instance._settingsPhotonName = photonName;
-        instance._settingsInstanceName = instanceName;
-        instance._settingsSchema = schema;
-        // Replace with read-only Proxy
-        instance.settings = new Proxy(backing, {
-            get(target, prop) {
-                if (typeof prop === 'string') {
-                    return target[prop];
-                }
-                return undefined;
-            },
-            set(_target, prop, _value) {
-                throw new Error(`Cannot directly set settings.${String(prop)}. ` +
-                    `Use the 'settings' tool to change settings (e.g., settings({ ${String(prop)}: newValue })).`);
-            },
-            deleteProperty(_target, prop) {
-                throw new Error(`Cannot delete settings.${String(prop)}. Use the 'settings' tool instead.`);
-            },
-        });
-    }
-    /**
-     * Generate an MCP tool definition from a SettingsSchema
-     */
-    generateSettingsTool(schema) {
-        const properties = {};
-        for (const prop of schema.properties) {
-            const propSchema = { type: prop.type };
-            if (prop.description) {
-                propSchema.description = prop.description;
-            }
-            if (prop.default !== undefined) {
-                propSchema.default = prop.default;
-            }
-            properties[prop.name] = propSchema;
-        }
-        return {
-            name: 'settings',
-            description: 'View or update photon settings. Call with no arguments to view current settings. Pass parameters to update specific settings.',
-            inputSchema: {
-                type: 'object',
-                properties,
-                // No required params — all settings are optional when calling the tool
-            },
-        };
-    }
-    /**
-     * Execute the auto-generated settings tool:
-     * - No params → return current settings
-     * - Params with values → update those settings, persist, emit change
-     * - Params with undefined + no default → trigger elicitation
-     */
-    async executeSettingsTool(instance, parameters, options) {
-        const backing = instance._settingsBacking;
-        const photonName = instance._settingsPhotonName;
-        const instanceName = instance._settingsInstanceName;
-        const schema = instance._settingsSchema;
-        if (!backing || !photonName || !schema) {
-            throw new Error('Settings not initialized for this photon');
-        }
-        // No params or empty params → return current settings
-        if (!parameters || Object.keys(parameters).length === 0) {
-            // Check if any required settings (undefined defaults) need elicitation
-            const needsElicitation = schema.properties.filter((p) => p.required && backing[p.name] === undefined);
-            if (needsElicitation.length > 0 && options?.inputProvider) {
-                for (const prop of needsElicitation) {
-                    const result = await options.inputProvider({
-                        ask: prop.type === 'number' ? 'number' : 'text',
-                        message: prop.description || `Enter value for ${prop.name}:`,
-                    });
-                    if (result !== undefined && result !== null) {
-                        const oldValue = backing[prop.name];
-                        backing[prop.name] = result;
-                        this.log(`⚙️  Settings: ${prop.name} = ${JSON.stringify(result)} (elicited)`);
-                        this.emitSettingsChange(instance, prop.name, oldValue, result);
-                    }
-                }
-                await this.persistSettings(photonName, instanceName, backing);
-            }
-            return { ...backing };
-        }
-        // Update specified settings
-        const changes = [];
-        for (const [key, value] of Object.entries(parameters)) {
-            // Verify this is a valid setting
-            const prop = schema.properties.find((p) => p.name === key);
-            if (!prop)
-                continue;
-            if (value === undefined && prop.required) {
-                // Elicit value from user
-                if (options?.inputProvider) {
-                    const result = await options.inputProvider({
-                        ask: prop.type === 'number' ? 'number' : 'text',
-                        message: prop.description || `Enter value for ${key}:`,
-                    });
-                    if (result !== undefined && result !== null) {
-                        const oldValue = backing[key];
-                        backing[key] = result;
-                        changes.push({ property: key, oldValue, newValue: result });
-                    }
-                }
-            }
-            else {
-                const oldValue = backing[key];
-                backing[key] = value;
-                changes.push({ property: key, oldValue, newValue: value });
-            }
-        }
-        // Persist if anything changed
-        if (changes.length > 0) {
-            await this.persistSettings(photonName, instanceName, backing);
-            for (const change of changes) {
-                this.log(`⚙️  Settings: ${change.property}: ${JSON.stringify(change.oldValue)} → ${JSON.stringify(change.newValue)}`);
-                this.emitSettingsChange(instance, change.property, change.oldValue, change.newValue);
-            }
-        }
-        // Re-apply proxy (backing object is already updated in place, proxy still references it)
-        return { ...backing };
-    }
-    /**
-     * Emit a settings:changed event through the photon's emit system
-     */
-    emitSettingsChange(instance, property, oldValue, newValue) {
-        if (typeof instance.emit === 'function') {
-            try {
-                instance.emit({
-                    event: 'settings:changed',
-                    data: {
-                        property,
-                        oldValue,
-                        newValue,
-                        timestamp: Date.now(),
-                    },
-                });
-            }
-            catch {
-                // Best-effort emit
-            }
-        }
-    }
+    // Settings persistence (load, persist, inject Proxy, generate tool, execute
+    // updates) lives in `./settings-persistence.ts` and is reachable via
+    // `this.settingsPersistence`.
     /**
      * Extract constructor parameters from source file
      */
@@ -2950,7 +3004,6 @@ Run: photon mcp ${mcpName} --config
      * All middleware (built-in and custom) follows the same code path — no if-chain.
      */
     applyMiddleware(execute, toolMeta, photonName, toolName, parameters, instanceName, outputHandler) {
-        // Build middleware context
         const store = executionContext.getStore();
         const ctx = {
             photon: photonName,
@@ -2959,7 +3012,7 @@ Run: photon mcp ${mcpName} --config
             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) {
@@ -3193,9 +3246,13 @@ Run: photon mcp ${mcpName} --config
                 parentTraceparent = metaPeek.traceparent;
             }
         }
-        // Start OTel span for tool execution (no-op if SDK not installed)
-        const toolMetaForSpan = mcp?.meta?.tools?.[toolName];
-        const isStateful = Boolean(toolMetaForSpan?.stateful ?? mcp?.meta?.stateful);
+        // Start OTel span for tool execution (no-op if SDK not installed).
+        // The `mcp.meta` shape is an internal extension some callers stamp on the
+        // loaded photon — it isn't on PhotonClass so we type the lookup as a
+        // narrow structural shape rather than reach for `as any`.
+        const mcpMeta = mcp.meta;
+        const toolMetaForSpan = mcpMeta?.tools?.[toolName];
+        const isStateful = Boolean(toolMetaForSpan?.stateful ?? mcpMeta?.stateful);
         const span = startToolSpan(mcp.name, toolName, parameters, options?.traceId, isStateful, parentTraceparent);
         if (mcp.instance?.instanceName) {
             span.setAttribute('photon.instance', mcp.instance.instanceName);
@@ -3229,7 +3286,9 @@ 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)
+            // Enforce @auth at method level — works across ALL transports (CLI, STDIO, HTTP, daemon).
+            // `auth` is a runtime extension stamped by the loader on top of the published
+            // PhotonClass type; reach via the narrower PhotonClassWithMeta interface.
             const photonAuth = mcp.auth;
             if (photonAuth === 'required') {
                 const caller = options?.caller;
@@ -3262,9 +3321,29 @@ Run: photon mcp ${mcpName} --config
                     }
                 }
             }
+            // Track C: auth → instance binding. For `@stateful` photons with an
+            // `@auth` scheme, derive `_targetInstance` from the caller's claims
+            // so each authenticated user lands on a disjoint per-user instance.
+            // Existing `_targetInstance` on the call wins (explicit overrides
+            // implicit). Standalone `photon mcp` is single-tenant — this only
+            // takes effect via the daemon and streamable-HTTP transport, which
+            // both consume `_targetInstance` to route the call.
+            if (photonAuth &&
+                isStateful &&
+                options?.caller?.claims &&
+                parameters &&
+                typeof parameters === 'object' &&
+                !('_targetInstance' in parameters)) {
+                const { resolveInstanceFromClaims, parseAuthDirective } = await import('./shared/instance-binding.js');
+                const { scheme, claim } = parseAuthDirective(photonAuth);
+                const bound = resolveInstanceFromClaims(scheme, options.caller.claims, claim);
+                if (bound) {
+                    parameters._targetInstance = bound;
+                }
+            }
             // Intercept auto-generated settings tool
             if (toolName === 'settings' && mcp.instance._settingsBacking) {
-                const result = await this.executeSettingsTool(mcp.instance, parameters, {
+                const result = await this.settingsPersistence.execute(mcp.instance, parameters, {
                     outputHandler: options?.outputHandler,
                     inputProvider: options?.inputProvider,
                 });
@@ -3482,6 +3561,7 @@ Run: photon mcp ${mcpName} --config
                     caller: options?.caller,
                     inputProvider,
                     samplingProvider: options?.samplingProvider,
+                    roots: options?.roots,
                 }, () => {
                     return method.call(mcp.instance, ...args);
                 });
@@ -3565,7 +3645,7 @@ Run: photon mcp ${mcpName} --config
                     instance: mcp.instance?.instanceName,
                 });
             }
-            this.logger.error(`Tool execution failed: ${toolName} - ${getErrorMessage(error)}`);
+            this.logger.debug(`Tool execution failed: ${toolName} - ${getErrorMessage(error)}`);
             throw error;
         }
         finally {
@@ -4075,57 +4155,8 @@ Run: photon mcp ${mcpName} --config
             throw initError;
         }
     }
-    /**
-     * Discover and extract assets from a Photon file
-     * Uses shared discoverAssets from photon-core for core logic,
-     * then applies photon-specific extensions (method UI links, URI generation).
-     */
-    async discoverAssets(photonPath, source) {
-        const basename = path.basename(photonPath, '.photon.ts');
-        // Use shared discovery from photon-core
-        const assets = await sharedDiscoverAssets(photonPath, source);
-        if (!assets) {
-            return undefined;
-        }
-        // Apply method-level @ui links AFTER auto-discovery
-        this.applyMethodUILinks(source, assets);
-        // Generate ui:// URIs for MCP Apps Extension support (SEP-1865)
-        this.generateAssetURIs(basename, assets);
-        return assets;
-    }
-    /**
-     * Expose discovered asset metadata on the instance without breaking Photon.assets().
-     *
-     * Photon subclasses inherit an `assets(subpath)` method from photon-core. We bind that
-     * method and decorate the function object with discovered metadata so both of these work:
-     * - `this.assets('templates')`
-     * - `this.assets.ui`
-     *
-     * Plain classes don't have the inherited method, so they receive the metadata object directly.
-     */
-    attachAssetsToInstance(instance, assets) {
-        if (!assets) {
-            return;
-        }
-        const existingAssets = instance.assets;
-        if (typeof existingAssets === 'function') {
-            const boundAssets = existingAssets.bind(instance);
-            Object.assign(boundAssets, assets);
-            Object.defineProperty(instance, 'assets', {
-                value: boundAssets,
-                configurable: true,
-                enumerable: false,
-                writable: false,
-            });
-            return;
-        }
-        Object.defineProperty(instance, 'assets', {
-            value: assets,
-            configurable: true,
-            enumerable: false,
-            writable: false,
-        });
-    }
+    // Asset discovery + binding lives in `./asset-resolver.ts` and is reachable
+    // via `this.assetResolver`.
     /**
      * Inject Photon path helpers for plain classes that use them without extending Photon.
      */
@@ -4182,48 +4213,5 @@ Run: photon mcp ${mcpName} --config
             };
         }
     }
-    /**
-     * Generate ui:// URIs for all UI assets (MCP Apps Extension support)
-     * URI format: ui://<photon-name>/<asset-id>
-     */
-    generateAssetURIs(photonName, assets) {
-        for (const ui of assets.ui) {
-            // Add uri field for MCP Apps compatibility
-            ui.uri = `ui://${photonName}/${ui.id}`;
-            this.log(`  🔗 URI: ${ui.uri}`);
-        }
-    }
-    /**
-     * Apply method-level @ui annotations to link UI assets to tools
-     * Called after auto-discovery so all UI assets are available
-     */
-    applyMethodUILinks(source, assets) {
-        // Match method JSDoc with @ui annotation: /** ... @ui <id> ... */ async methodName
-        const methodUiRegex = /\/\*\*[\s\S]*?@ui\s+(\w[\w-]*)[\s\S]*?\*\/\s*(?:async\s+)?\*?\s*(\w+)/g;
-        let match;
-        while ((match = methodUiRegex.exec(source)) !== null) {
-            const [, uiId, methodName] = match;
-            const asset = assets.ui.find((u) => u.id === uiId);
-            if (asset) {
-                // First method wins as primary (used for app detection)
-                if (!asset.linkedTool) {
-                    asset.linkedTool = methodName;
-                    this.log(`  🔗 UI ${uiId} → ${methodName}`);
-                }
-                // Track all methods that reference this UI
-                if (!asset.linkedTools)
-                    asset.linkedTools = [];
-                if (!asset.linkedTools.includes(methodName)) {
-                    asset.linkedTools.push(methodName);
-                    if (asset.linkedTools.length > 1) {
-                        this.log(`  🔗 UI ${uiId} → ${methodName} (shared)`);
-                    }
-                }
-            }
-            else {
-                this.log(`  ⚠️ @ui ${uiId} on ${methodName}: asset not found (check file exists)`);
-            }
-        }
-    }
 }
 //# sourceMappingURL=loader.js.map