@portel/photon 1.28.2 → 1.31.0

package/dist/server.js

@@ -7,8 +7,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, GetTaskRequestSchema, ListTasksRequestSchema, CancelTaskRequestSchema, GetTaskPayloadRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, RootsListChangedNotificationSchema, GetTaskRequestSchema, ListTasksRequestSchema, CancelTaskRequestSchema, GetTaskPayloadRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { readText } from './shared/io.js';
+import { detectIsolationMode } from './shared/cross-origin-headers.js';
 import { createServer } from 'node:http';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
@@ -28,13 +29,70 @@ import { isLocalRequest, readBody, setSecurityHeaders, getCorsOrigin } from './s
 import { audit } from './shared/audit.js';
 import { TaskExecutor } from './task-executor.js';
 import { CapabilityNegotiator } from './capability-negotiator.js';
-import { ResourceServer } from './resource-server.js';
+import { ResourceServer, SubscriptionRegistry, } from './resource-server.js';
 export class HotReloadDisabledError extends Error {
     constructor(message) {
         super(message);
         this.name = 'HotReloadDisabledError';
     }
 }
+/**
+ * MIME for SPA sibling files served under /api/ui/<id>/<rest>. Conservative
+ * map covering the file types a typical bundler emits next to index.html;
+ * unknown extensions fall back to application/octet-stream so binary blobs
+ * still transit cleanly.
+ */
+function uiSiblingMime(ext) {
+    switch (ext) {
+        case '.html':
+            return 'text/html; charset=utf-8';
+        case '.js':
+        case '.mjs':
+            return 'text/javascript; charset=utf-8';
+        case '.css':
+            return 'text/css; charset=utf-8';
+        case '.json':
+            return 'application/json; charset=utf-8';
+        case '.svg':
+            return 'image/svg+xml';
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.gif':
+            return 'image/gif';
+        case '.webp':
+            return 'image/webp';
+        case '.ico':
+            return 'image/x-icon';
+        case '.woff':
+            return 'font/woff';
+        case '.woff2':
+            return 'font/woff2';
+        case '.ttf':
+            return 'font/ttf';
+        case '.map':
+            return 'application/json; charset=utf-8';
+        case '.txt':
+            return 'text/plain; charset=utf-8';
+        case '.wasm':
+            return 'application/wasm';
+        default:
+            return 'application/octet-stream';
+    }
+}
+function findFreePort(preferred = 0) {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.listen(preferred, () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : preferred;
+            srv.close((err) => (err ? reject(err) : resolve(port)));
+        });
+        srv.on('error', reject);
+    });
+}
 class BeamCompatTransport {
     photonName;
     photonMeta;
@@ -96,14 +154,16 @@ class BeamCompatTransport {
                 message.result.tools.push(...subTools);
             }
         }
-        // If there's a pending HTTP request waiting for a response, deliver it
-        if (this.pendingResponse) {
+        // JSON-RPC notifications have no 'id' — route to SSE only, never to pendingResponse.
+        // Responses have 'id' + 'result'/'error'. Server-initiated requests have 'id' + 'method'.
+        const isResponse = message.id !== undefined && message.id !== null && !message.method;
+        if (isResponse && this.pendingResponse) {
             const resolve = this.pendingResponse;
             this.pendingResponse = null;
             resolve(message);
             return;
         }
-        // Otherwise push to SSE stream if connected
+        // Notifications and server-initiated requests go to the SSE stream
         if (this.sseResponse && !this.sseResponse.writableEnded) {
             const id = message.id ?? crypto.randomUUID();
             this.sseResponse.write(`event: message\nid: ${id}\ndata: ${JSON.stringify(message)}\n\n`);
@@ -138,11 +198,17 @@ class BeamCompatTransport {
             }, 15000);
             req.on('close', () => {
                 clearInterval(keepalive);
-                this.sseResponse = null;
+                // Only clear if this response is still the active SSE stream.
+                // A newer GET may have already replaced it — don't overwrite that.
+                if (this.sseResponse === res) {
+                    this.sseResponse = null;
+                }
             });
             res.on('error', () => {
                 clearInterval(keepalive);
-                this.sseResponse = null;
+                if (this.sseResponse === res) {
+                    this.sseResponse = null;
+                }
             });
             return;
         }
@@ -209,9 +275,21 @@ class BeamCompatTransport {
                     parsed.params.name = methodName;
                 }
             }
+            // Track C closure: surface CF Access (and equivalent) claims to the
+            // request handlers so the per-claim instance pool can route. The
+            // claims ride on the SDK's MessageExtraInfo.authInfo.extra, which
+            // the protocol layer propagates to setRequestHandler's `extra` arg.
+            const { extractClaimsFromHeaders } = await import('./shared/extract-claims.js');
+            const claims = extractClaimsFromHeaders(req.headers);
+            const messageExtra = claims
+                ? {
+                    sessionId: this.sessionId,
+                    authInfo: { token: '', clientId: '', scopes: [], extra: claims },
+                }
+                : { sessionId: this.sessionId };
             // Notifications have no id — fire-and-forget
             if (parsed.id === undefined) {
-                this.onmessage?.(parsed, { sessionId: this.sessionId });
+                this.onmessage?.(parsed, messageExtra);
                 const notifHeaders = {
                     'Mcp-Session-Id': this.sessionId,
                 };
@@ -224,7 +302,7 @@ class BeamCompatTransport {
             // Request — wait for the Server to call send() with the response
             const response = await new Promise((resolve) => {
                 this.pendingResponse = resolve;
-                this.onmessage?.(parsed, { sessionId: this.sessionId });
+                this.onmessage?.(parsed, messageExtra);
             });
             const resHeaders = {
                 'Content-Type': 'application/json',
@@ -272,6 +350,26 @@ export class PhotonServer {
     daemonInstanceName;
     /** Tracked instance names per SSE session for daemon drift recovery */
     sseInstanceNames = new Map();
+    /**
+     * Track C closure: per-claim instance pool. Populated lazily on first
+     * request from a new authenticated caller when the photon declares
+     * `@stateful` + `@auth`. Without this, every authenticated caller
+     * shares `this.mcp.instance` — meaning two users on the standalone
+     * HTTP server race on the same `this.tasks` / `this.memory`.
+     *
+     * Daemon path doesn't need this — it has its own per-instance loader
+     * (`session-manager.ts`). Cloudflare doesn't need it either — the
+     * outer Worker selects a DO per claim before the request arrives.
+     * This pool is the standalone HTTP server's equivalent.
+     */
+    instancePool = new Map();
+    /**
+     * True iff the loaded photon declares both `@stateful` and `@auth` —
+     * the only shape that actually wants per-caller state isolation. For
+     * everything else, instance routing is a no-op and `this.mcp` is used
+     * directly.
+     */
+    requiresInstanceRouting = false;
     /** Whether client capabilities have been logged (one-time on first tools/list) */
     clientCapabilitiesLogged = false;
     /** Client capability detection and negotiation */
@@ -282,6 +380,24 @@ export class PhotonServer {
     rawClientCapabilities = this.capabilityNegotiator.rawClientCapabilities;
     /** Resource listing, reading, and asset serving */
     resourceServer;
+    /**
+     * Server-wide registry of `resources/subscribe` state. The STDIO server
+     * registers one persistent sink; each SSE session registers a per-session
+     * sink at connect and clears its subscriptions at close.
+     */
+    subscriptions = new SubscriptionRegistry();
+    /** Stable sink for the STDIO server, registered once on first subscribe. */
+    stdioSink;
+    /**
+     * Per-server roots cache. Populated on `oninitialized` if the client
+     * declared the `roots` capability, refreshed on
+     * `notifications/roots/list_changed`. Read at tool-call time and threaded
+     * into ALS so `this.roots` resolves synchronously inside photon code.
+     *
+     * WeakMap-keyed so dead session servers stop holding cache entries
+     * automatically when SSE sessions disconnect.
+     */
+    rootsByServer = new WeakMap();
     currentStatus = {
         type: 'info',
         message: 'Ready',
@@ -329,6 +445,9 @@ export class PhotonServer {
         const loaderVerbose = (baseLoggerOptions.level ?? 'info') !== 'warn' &&
             (baseLoggerOptions.level ?? 'info') !== 'error';
         this.loader = new PhotonLoader(loaderVerbose, this.logger.child({ component: 'photon-loader', scope: 'loader' }), options.workingDir);
+        // Bridge `this.notifyResourceUpdated(uri)` from photon authors into the
+        // server's SubscriptionRegistry so all subscribed clients get fanout.
+        this.loader.setResourceUpdateNotifier((uri) => this.subscriptions.notify(uri));
         // Initialize ChannelManager — owns all channel/pub-sub logic
         // The sink is wired up lazily because `this.server` doesn't exist yet
         const channelSink = {
@@ -367,6 +486,7 @@ export class PhotonServer {
                 },
                 resources: {
                     listChanged: true, // We support hot reload notifications
+                    subscribe: true, // resources/subscribe + notifications/resources/updated
                 },
                 logging: {}, // Required for notifications/message (used by render, log, etc.)
                 tasks: {
@@ -394,6 +514,7 @@ export class PhotonServer {
             filePath: options.filePath,
             embeddedAssets: options.embeddedAssets,
             embeddedUITemplates: options.embeddedUITemplates,
+            embeddedAssetTree: options.embeddedAssetTree,
         });
         // Set up protocol handlers
         this.setupHandlers();
@@ -438,7 +559,7 @@ export class PhotonServer {
     queueNotification(notification) {
         this._notifyQueue = this._notifyQueue
             .then(() => this.server?.notification(notification))
-            .catch(() => { });
+            .catch((err) => this.logger.debug('Failed to send notification', { error: getErrorMessage(err) }));
     }
     /**
      * Create an MCP-aware input provider for generator ask yields
@@ -836,11 +957,54 @@ export class PhotonServer {
         }
         return { tools };
     }
-    async handleCallTool(ctx, request) {
+    /**
+     * Resolve which photon instance handles this call. For `@stateful` +
+     * `@auth` photons we pull claims from the request's `authInfo.extra`
+     * (populated by `BeamCompatTransport` from the HTTP headers), look up
+     * the binding rule from the `@auth` directive, and lazy-load a fresh
+     * photon instance keyed by that claim value. Subsequent calls from
+     * the same caller reuse the cached instance so `this.memory` /
+     * `this.tasks` persist across requests within their per-user scope.
+     *
+     * Returns `this.mcp` (the shared singleton) when the photon doesn't
+     * declare per-caller routing, when claims are missing, or when the
+     * binding rule yields no instance name. The fallback is intentional:
+     * unauthenticated requests still execute, they just share the default
+     * instance — same as a v1.28 photon would.
+     */
+    async resolveInstanceMcp(extra) {
+        if (!this.requiresInstanceRouting || !this.mcp)
+            return this.mcp;
+        const claims = extra?.authInfo?.extra;
+        if (!claims)
+            return this.mcp;
+        const { resolveInstanceFromClaims, parseAuthDirective } = await import('./shared/instance-binding.js');
+        const photonAuth = this.mcp.auth;
+        const { scheme, claim } = parseAuthDirective(photonAuth);
+        const bound = resolveInstanceFromClaims(scheme, claims, claim);
+        if (!bound)
+            return this.mcp;
+        let pending = this.instancePool.get(bound);
+        if (!pending) {
+            this.log('info', `Lazy-loading instance for ${bound}`);
+            pending = this.loader.loadFile(this.options.filePath, { instanceName: bound });
+            this.instancePool.set(bound, pending);
+        }
+        return pending;
+    }
+    async handleCallTool(ctx, request, extra) {
         if (!this.mcp) {
             throw new Error('MCP not loaded');
         }
+        const targetMcp = await this.resolveInstanceMcp(extra);
         const { name: toolName, arguments: args } = request.params;
+        // Per MCP spec, the server must echo the client-supplied progressToken
+        // from request _meta back in notifications/progress so clients can match
+        // streamed progress to their original request. Fall back to a synthetic
+        // token only when the client didn't supply one.
+        const clientProgressToken = request.params
+            ?._meta?.progressToken;
+        const progressToken = clientProgressToken ?? `progress_${toolName}`;
         // Route _use, _instances, _undo, _redo through daemon for stateful photons
         if (this.daemonName &&
             (toolName === '_use' ||
@@ -935,7 +1099,7 @@ export class PhotonServer {
                 this.queueNotification({
                     method: 'notifications/progress',
                     params: {
-                        progressToken: `progress_${toolName}`,
+                        progressToken,
                         progress,
                         total: 100,
                         ...(emit.message ? { message: emit.message } : {}),
@@ -946,7 +1110,7 @@ export class PhotonServer {
                 this.queueNotification({
                     method: 'notifications/progress',
                     params: {
-                        progressToken: `progress_${toolName}`,
+                        progressToken,
                         progress: 0,
                         total: 100,
                         message: emit.message || '',
@@ -985,13 +1149,14 @@ export class PhotonServer {
                 });
             }
         };
-        const tool = this.mcp.tools.find((t) => t.name === toolName);
+        const tool = targetMcp.tools.find((t) => t.name === toolName);
         const outputFormat = tool?.outputFormat;
         const startTime = Date.now();
-        const result = await this.loader.executeTool(this.mcp, toolName, args || {}, {
+        const result = await this.loader.executeTool(targetMcp, toolName, args || {}, {
             inputProvider,
             outputHandler,
             samplingProvider,
+            roots: this.rootsByServer.get(ctx.server),
         });
         const durationMs = Date.now() - startTime;
         const transport = this.options.transport || 'stdio';
@@ -1066,6 +1231,12 @@ export class PhotonServer {
             const uiMeta = this.resourceServer.buildUIToolMeta(this.mcp.name, linkedUI.id);
             response._meta = { ...response._meta, ...uiMeta };
         }
+        // For SSE/Streamable-HTTP transports: flush the notification queue before
+        // returning so that progress/status notifications are delivered via the GET
+        // SSE stream BEFORE the HTTP POST response body is written. Without this, the
+        // client receives the tool result, deletes its _progressHandlers entry, and then
+        // silently drops any notifications that arrive later on the SSE stream.
+        await this._notifyQueue;
         return response;
     }
     handleListPrompts() {
@@ -1122,7 +1293,7 @@ export class PhotonServer {
             }
             return this.handleListTools(ctx);
         });
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             // STDIO-only: deferred conflict resolution
             if (!this.mcp && this.options.unresolvedPhoton) {
                 await this.resolveUnresolvedPhoton();
@@ -1137,6 +1308,8 @@ export class PhotonServer {
                     const executionId = traceId;
                     const inputProvider = this.createMCPInputProvider();
                     const samplingProvider = this.createMCPSamplingProvider();
+                    const clientProgressToken = request.params?._meta?.progressToken;
+                    const progressToken = clientProgressToken ?? `progress_${toolName}`;
                     const outputHandler = (emit) => {
                         this.channelManager.publishIfChannel(emit);
                         // Forward emit yields as MCP notifications for async tools
@@ -1146,7 +1319,7 @@ export class PhotonServer {
                             void this.server?.notification({
                                 method: 'notifications/progress',
                                 params: {
-                                    progressToken: `progress_${toolName}`,
+                                    progressToken,
                                     progress,
                                     total: 100,
                                     message: emit.message || '',
@@ -1201,6 +1374,7 @@ export class PhotonServer {
                         outputHandler,
                         samplingProvider,
                         traceId,
+                        roots: this.rootsByServer.get(ctx.server),
                     })
                         .catch((error) => {
                         this.log('error', `Async tool ${toolName} failed`, {
@@ -1236,7 +1410,7 @@ export class PhotonServer {
                 return this.taskExecutor.handleTaskModeCall(this.mcp.name, toolName, args || {}, taskField);
             }
             try {
-                return await this.handleCallTool(ctx, request);
+                return await this.handleCallTool(ctx, request, extra);
             }
             catch (error) {
                 // STDIO-only: config elicitation retry
@@ -1282,6 +1456,30 @@ export class PhotonServer {
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             return this.resourceServer.handleReadResource(request, this.mcp);
         });
+        // ── resources/subscribe + resources/unsubscribe (STDIO) ──
+        // Sink is created lazily on first subscribe so we never register an idle
+        // sink for clients that don't use the capability.
+        const ensureStdioSink = () => {
+            if (!this.stdioSink) {
+                this.stdioSink = (uri) => this.server.notification({
+                    method: 'notifications/resources/updated',
+                    params: { uri },
+                });
+            }
+            return this.stdioSink;
+        };
+        this.server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+            const uri = request.params.uri;
+            this.subscriptions.subscribe(ensureStdioSink(), uri);
+            return {};
+        });
+        this.server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+            const uri = request.params.uri;
+            if (this.stdioSink) {
+                this.subscriptions.unsubscribe(this.stdioSink, uri);
+            }
+            return {};
+        });
         // ── MCP Tasks handlers (2025-11-25 spec) — delegated to TaskExecutor ──
         this.server.setRequestHandler(GetTaskRequestSchema, async (request) => {
             return this.taskExecutor.handleGetTask(request.params.taskId);
@@ -1295,6 +1493,41 @@ export class PhotonServer {
         this.server.setRequestHandler(GetTaskPayloadRequestSchema, async (request) => {
             return this.taskExecutor.handleGetTaskPayload(request.params.taskId, this.server);
         });
+        this.setupRootsForServer(this.server);
+    }
+    /**
+     * Wire up `roots/list` discovery + `notifications/roots/list_changed`
+     * refresh for one Server instance. Called once for the STDIO server and
+     * once per SSE session.
+     *
+     * Eager fetch on initialize keeps `this.roots` synchronous inside photon
+     * code — clients that don't declare the capability skip the fetch
+     * entirely. The cache is server-scoped (per-session for SSE) so two
+     * clients with different working directories don't see each other's
+     * roots.
+     */
+    setupRootsForServer(server) {
+        server.oninitialized = () => {
+            const caps = server.getClientCapabilities();
+            if (!caps?.roots)
+                return;
+            void this.refreshRootsCache(server);
+        };
+        server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+            await this.refreshRootsCache(server);
+        });
+    }
+    async refreshRootsCache(server) {
+        try {
+            const result = await server.listRoots();
+            const roots = (result?.roots ?? []).map((r) => ({ uri: r.uri, name: r.name }));
+            this.rootsByServer.set(server, roots);
+        }
+        catch (err) {
+            this.log('warn', 'roots/list refresh failed', {
+                error: err instanceof Error ? getErrorMessage(err) : String(err),
+            });
+        }
     }
     /**
      * Format tool result as text
@@ -1662,17 +1895,51 @@ export class PhotonServer {
                     this.mcp = await this.loader.loadFile(this.options.filePath);
                 }
             }
+            // Track C closure: detect whether the loaded photon needs
+            // per-caller state isolation. Only `@stateful` + `@auth` photons
+            // do — everything else stays single-instance. The daemon path
+            // and the Cloudflare outer-Worker have their own routing; this
+            // flag drives the standalone HTTP server's per-claim pool.
+            const photonAuth = this.mcp?.auth;
+            const photonStateful = !!this.mcp?.stateful;
+            this.requiresInstanceRouting = Boolean(photonAuth && photonStateful);
+            if (this.requiresInstanceRouting) {
+                this.log('info', `Per-claim instance routing enabled (auth=${JSON.stringify(photonAuth)})`);
+            }
             // Subscribe to daemon channels for cross-process notifications.
             // In channel mode, ChannelManager intercepts 'channel-push' events
             // and translates them to notifications/claude/channel for the connected client.
             await this.channelManager.subscribeToChannels();
-            // Start with the appropriate transport
+            // Announce web capability when the photon has @get / defined.
+            // HTTP mode: the existing HTTP server already handles web routes at their
+            // declared paths, so we expose the server's own base URL.
+            // STDIO stateful: we spin up a companion HTTP server to host those routes
+            // and expose its URL. Stateless photons cannot have a companion server.
             const transport = this.options.transport || 'stdio';
+            const photonWithMeta = this.mcp;
+            const webRootRoute = photonWithMeta?._httpRoutes?.find((r) => r.method === 'GET' && r.path === '/');
             if (transport === 'sse') {
+                if (webRootRoute) {
+                    const httpPort = Number(this.options.port) || 3000;
+                    const webDescription = photonWithMeta?.description || `${photonWithMeta?.name} web interface`;
+                    this.server.registerCapabilities({
+                        web: { url: `http://localhost:${httpPort}`, description: webDescription },
+                    });
+                }
                 await this.startSSE();
             }
             else {
-                await this.startStdio();
+                if (webRootRoute && photonStateful) {
+                    const webPort = await findFreePort(Number(this.options.port) || 0);
+                    const webDescription = photonWithMeta?.description || `${photonWithMeta?.name} web interface`;
+                    this.server.registerCapabilities({
+                        web: { url: `http://localhost:${webPort}`, description: webDescription },
+                    });
+                    await this.startStdio(webPort);
+                }
+                else {
+                    await this.startStdio();
+                }
             }
             // In dev mode, we could set up file watching here
             if (this.options.devMode) {
@@ -1688,22 +1955,116 @@ export class PhotonServer {
         }
     }
     /**
-     * Start server with stdio transport
+     * Start server with stdio transport.
+     * @param webPort - when set, start a companion HTTP server on this port
+     *                  to serve @get/@post web routes for stateful photons.
      */
-    async startStdio() {
+    async startStdio(webPort) {
         const transport = new StdioServerTransport();
         // Wrap transport.send with a write mutex to prevent concurrent generators
         // from interleaving JSON-RPC messages on stdout
         const originalSend = transport.send.bind(transport);
         let writeChain = Promise.resolve();
         transport.send = (message) => {
-            const p = writeChain.then(() => originalSend(message)).catch(() => { });
+            const p = writeChain
+                .then(() => originalSend(message))
+                .catch((err) => this.logger.debug('STDIO send failed', { error: getErrorMessage(err) }));
             writeChain = p;
             return p;
         };
         this.capabilityNegotiator.interceptTransportForRawCapabilities(transport, this.server, (msg) => this.channelManager.interceptPermissionRequest(msg));
         await this.server.connect(transport);
         this.log('info', `Server started: ${this.mcp.name}`);
+        if (webPort) {
+            const webServer = createServer((req, res) => {
+                void this.handleWebRoute(req, res);
+            });
+            await new Promise((resolve, reject) => {
+                webServer.listen(webPort, () => resolve());
+                webServer.on('error', reject);
+            });
+            this.log('info', `Web UI: http://localhost:${webPort}`);
+        }
+    }
+    /**
+     * Dispatch an incoming HTTP request to the photon's @get/@post web routes.
+     * Used by the companion HTTP server that runs alongside STDIO stateful photons.
+     */
+    async handleWebRoute(req, res) {
+        setSecurityHeaders(res);
+        if (!req.url) {
+            res.writeHead(400).end('Missing URL');
+            return;
+        }
+        const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+        const corsOrigin = getCorsOrigin(req);
+        if (req.method === 'OPTIONS') {
+            const preflightHeaders = {
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Accept',
+            };
+            if (corsOrigin)
+                preflightHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+            res.writeHead(204, preflightHeaders).end();
+            return;
+        }
+        const httpRoutes = this.mcp?._httpRoutes;
+        if (httpRoutes?.length && req.method) {
+            const route = httpRoutes.find((r) => r.method === req.method && r.path === url.pathname);
+            if (route) {
+                const targetMcp = await this.resolveInstanceMcp(undefined);
+                const photonInstance = targetMcp?.instance;
+                const fn = photonInstance?.[route.handler];
+                if (typeof fn === 'function') {
+                    try {
+                        let bodyBuffer = Buffer.alloc(0);
+                        await new Promise((resolve) => {
+                            req.on('data', (chunk) => {
+                                bodyBuffer = Buffer.concat([bodyBuffer, chunk]);
+                            });
+                            req.on('end', resolve);
+                        });
+                        const webReq = new Request(url.toString(), {
+                            method: req.method,
+                            headers: req.headers,
+                            ...(req.method !== 'GET' && bodyBuffer.length > 0 ? { body: bodyBuffer } : {}),
+                        });
+                        const result = await fn.call(photonInstance, webReq);
+                        if (result instanceof Response) {
+                            const responseHeaders = {};
+                            result.headers.forEach((value, key) => {
+                                responseHeaders[key] = value;
+                            });
+                            if (corsOrigin)
+                                responseHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                            res.writeHead(result.status, responseHeaders);
+                            res.end(Buffer.from(await result.arrayBuffer()));
+                            return;
+                        }
+                        const { negotiateAccept } = await import('./format/registry.js');
+                        const { getDefaultRegistry } = await import('./format/seed.js');
+                        const acceptHeader = req.headers['accept'];
+                        const rendered = negotiateAccept({
+                            accept: typeof acceptHeader === 'string' ? acceptHeader : undefined,
+                            declaredFormat: route.format,
+                            value: result,
+                            registry: getDefaultRegistry(),
+                        });
+                        const negotiatedHeaders = { 'Content-Type': rendered.mime };
+                        if (corsOrigin)
+                            negotiatedHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                        res.writeHead(200, negotiatedHeaders);
+                        res.end(typeof rendered.body === 'string' ? rendered.body : Buffer.from(rendered.body));
+                        return;
+                    }
+                    catch (err) {
+                        res.writeHead(500).end(err?.message ?? 'Internal Server Error');
+                        return;
+                    }
+                }
+            }
+        }
+        res.writeHead(404).end('Not Found');
     }
     /**
      * Start server with SSE transport (HTTP)
@@ -1737,6 +2098,9 @@ export class PhotonServer {
                     continue;
                 const icon = loaded.icon || '⚡';
                 const stateful = !!loaded.stateful;
+                // ^^ getLoadedPhotons() returns the canonical PhotonClassExtended type;
+                // these two callsites still need the narrower runtime cast until
+                // the loader's return type widens to PhotonClassWithMeta.
                 const hasSettings = !!loaded.settingsSchema?.hasSettings;
                 // Convert PhotonTool[] to MCP tool format with UI linking
                 const uiAssets = loaded.assets?.ui || [];
@@ -2045,25 +2409,141 @@ export class PhotonServer {
                     });
                     return;
                 }
-                // API: Get UI template
-                if (req.method === 'GET' && url.pathname.startsWith('/api/ui/')) {
-                    const uiId = url.pathname.replace('/api/ui/', '');
+                // API: Get UI template (and directory-style siblings for SPA bundles).
+                //
+                // Two shapes:
+                //   GET /api/ui/<id>           → the @ui-declared file itself
+                //   GET /api/ui/<id>/<rest>    → sibling under the @ui file's directory
+                //
+                // Sibling resolution lets a `@ui dashboard ./dashboard/dist/index.html`
+                // also serve `dashboard/dist/chunks/main.js` (which the index.html
+                // references as `./chunks/main.js`) without per-file @ui declarations.
+                // Path-traversal is rejected by resolving the candidate and confirming
+                // it stays under the @ui's directory root.
+                // `.*` (not `.+`) so a trailing-slash form like `/api/ui/dashboard/`
+                // matches with restPath='' and routes to the top-level branch
+                // alongside the no-slash form. Without the trailing-slash match,
+                // the redirect target below would 404.
+                const uiMatch = req.method === 'GET' && url.pathname.match(/^\/api\/ui\/([^/]+)(?:\/(.*))?$/);
+                if (uiMatch) {
+                    const uiId = uiMatch[1];
+                    const restPath = uiMatch[2] ?? '';
                     const ui = this.mcp?.assets?.ui.find((u) => u.id === uiId);
+                    const photonName = this.mcp?.name || '';
+                    // Top-level fetch (no sub-path): existing single-file behaviour.
+                    if (!restPath) {
+                        // Browsers resolve relative asset URLs against the document
+                        // URL. With `/api/ui/<id>` (no trailing slash) the base is
+                        // `/api/ui/`, so `./chunks/main.js` becomes `/api/ui/chunks/...`
+                        // which would 404 on the sibling resolver below. Redirect to
+                        // the trailing-slash form so the SPA's relative imports work.
+                        // The regex matches both `/api/ui/<id>` and `/api/ui/<id>/`
+                        // to the same restPath='', so we branch on the literal path.
+                        if (ui?.resolvedPath && !url.pathname.endsWith('/')) {
+                            const redirectHeaders = {
+                                Location: url.pathname + '/' + (url.search || ''),
+                            };
+                            if (corsOrigin)
+                                redirectHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                            res.writeHead(308, redirectHeaders);
+                            res.end();
+                            return;
+                        }
+                        if (ui?.resolvedPath) {
+                            try {
+                                const content = await readText(ui.resolvedPath);
+                                const uiHeaders = { 'Content-Type': 'text/html' };
+                                if (corsOrigin)
+                                    uiHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                                // Track D2: cross-origin isolation for standalone tabs so
+                                // SharedArrayBuffer / WebGPU / persistent OPFS / Service
+                                // Workers light up. Iframe embeds keep working because
+                                // detectIsolationMode returns 'embedded' on Sec-Fetch-Dest:
+                                // iframe (and the manual ?embed=1 escape hatch).
+                                if (detectIsolationMode(req) === 'standalone') {
+                                    uiHeaders['Cross-Origin-Opener-Policy'] = 'same-origin';
+                                    uiHeaders['Cross-Origin-Embedder-Policy'] = 'require-corp';
+                                }
+                                res.writeHead(200, uiHeaders);
+                                res.end(content);
+                                return;
+                            }
+                            catch {
+                                // Fall through to 404
+                            }
+                        }
+                        res.writeHead(404).end('UI not found');
+                        return;
+                    }
+                    // Sub-path: directory-style sibling resolution. Try the filesystem
+                    // first (dev mode), then the embedded asset tree (compiled binary).
                     if (ui?.resolvedPath) {
+                        const path = await import('path');
+                        const fs = await import('fs/promises');
+                        const baseDir = path.dirname(ui.resolvedPath);
+                        const candidate = path.resolve(baseDir, restPath);
+                        const baseWithSep = baseDir.endsWith(path.sep) ? baseDir : baseDir + path.sep;
+                        if (!candidate.startsWith(baseWithSep)) {
+                            res.writeHead(403).end('Forbidden');
+                            return;
+                        }
                         try {
-                            const content = await readText(ui.resolvedPath);
-                            const uiHeaders = { 'Content-Type': 'text/html' };
+                            const content = await fs.readFile(candidate);
+                            const ext = path.extname(candidate).toLowerCase();
+                            const mime = uiSiblingMime(ext);
+                            const sibHeaders = { 'Content-Type': mime };
                             if (corsOrigin)
-                                uiHeaders['Access-Control-Allow-Origin'] = corsOrigin;
-                            res.writeHead(200, uiHeaders);
+                                sibHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                            // Track D2: CORP same-origin so a standalone parent page with
+                            // COEP `require-corp` can fetch its own SPA chunks.
+                            sibHeaders['Cross-Origin-Resource-Policy'] = 'same-origin';
+                            res.writeHead(200, sibHeaders);
                             res.end(content);
                             return;
                         }
                         catch {
-                            // Fall through to 404
+                            // Fall through to embedded tree / 404
                         }
                     }
-                    res.writeHead(404).end('UI not found');
+                    if (ui && this.options.embeddedAssetTree && photonName) {
+                        const tree = this.options.embeddedAssetTree[photonName];
+                        if (tree) {
+                            // The @ui declaration is relative to <photon>/assets/. Strip the
+                            // declared filename to get the sibling base, then append rest.
+                            const declared = ui.path.replace(/^\.\//, '');
+                            const lastSlash = declared.lastIndexOf('/');
+                            const baseRel = lastSlash >= 0 ? declared.slice(0, lastSlash + 1) : '';
+                            const cleanRest = restPath.replace(/^\/+/, '');
+                            if (cleanRest.includes('..')) {
+                                res.writeHead(403).end('Forbidden');
+                                return;
+                            }
+                            const siblingKey = baseRel + cleanRest;
+                            const content = tree[siblingKey];
+                            if (typeof content === 'string') {
+                                const path = await import('path');
+                                const ext = path.extname(siblingKey).toLowerCase();
+                                const treeHeaders = {
+                                    'Content-Type': uiSiblingMime(ext),
+                                };
+                                if (corsOrigin)
+                                    treeHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                                // Track D2: CORP same-origin so embedded-binary servers stay
+                                // satisfiable for COEP-isolated parent pages.
+                                treeHeaders['Cross-Origin-Resource-Policy'] = 'same-origin';
+                                // Binary siblings (.png, .woff2, .wasm) ship as base64 in
+                                // the embedded tree to survive round-trip through the
+                                // bundled JS. Decode back to a Buffer so the bytes hit
+                                // the wire unchanged; text entries keep the UTF-8 path.
+                                const { decodeEmbeddedAsset } = await import('./shared/asset-encoding.js');
+                                const decoded = decodeEmbeddedAsset(content);
+                                res.writeHead(200, treeHeaders);
+                                res.end(decoded.buffer ?? decoded.text);
+                                return;
+                            }
+                        }
+                    }
+                    res.writeHead(404).end('UI sibling not found');
                     return;
                 }
                 // Serve embedded frontend assets (compiled binaries with --with-app)
@@ -2073,9 +2553,7 @@ export class PhotonServer {
                     if (req.method === 'GET' && url.pathname === '/api/diagnostics') {
                         const { PHOTON_VERSION } = await import('./version.js');
                         const photonName = this.mcp?.name || 'photon';
-                        const tools = this.mcp
-                            ? Object.keys(this.mcp._toolSchemas || {}).length
-                            : 0;
+                        const tools = this.mcp ? Object.keys(this.mcp._toolSchemas || {}).length : 0;
                         const diagHeaders = { 'Content-Type': 'application/json' };
                         if (corsOrigin)
                             diagHeaders['Access-Control-Allow-Origin'] = corsOrigin;
@@ -2167,44 +2645,152 @@ export class PhotonServer {
                     res.end(this.options.embeddedAssets.indexHtml);
                     return;
                 }
-                // @get / @post HTTP routes — dispatch to photon method, public (no auth)
+                // @get / @post HTTP routes — dispatch to photon method, public (no auth).
+                // Track C: when none match, fall through to the auto-RPC table built
+                // from @expose tags below.
                 const httpRoutes = this.mcp?._httpRoutes;
+                let matchedRoute = null;
                 if (httpRoutes?.length && req.method) {
                     const route = httpRoutes.find((r) => r.method === req.method && r.path === url.pathname);
-                    if (route) {
-                        const photonInstance = this.mcp?.instance;
-                        const fn = photonInstance?.[route.handler];
-                        if (typeof fn === 'function') {
-                            try {
-                                // Collect body for POST routes
-                                let bodyBuffer = Buffer.alloc(0);
-                                await new Promise((resolve) => {
-                                    req.on('data', (chunk) => {
-                                        bodyBuffer = Buffer.concat([bodyBuffer, chunk]);
-                                    });
-                                    req.on('end', resolve);
-                                });
-                                // Build Web-standard Request
-                                const webReq = new Request(url.toString(), {
-                                    method: req.method,
-                                    headers: req.headers,
-                                    ...(req.method !== 'GET' && bodyBuffer.length > 0 ? { body: bodyBuffer } : {}),
+                    if (route)
+                        matchedRoute = { handler: route.handler, format: route.format };
+                }
+                // Track C: auto-RPC. POST /api/<kebab-method> dispatches to @expose'd
+                // methods. Explicit @get/@post takes precedence (matchedRoute already
+                // set above) so a user can override path/verb for any @expose'd
+                // method without surrendering the auto-RPC slot for the rest. The
+                // visibility check below decides whether to allow the call.
+                const exposes = this.mcp?._exposes;
+                if (!matchedRoute &&
+                    exposes?.length &&
+                    req.method === 'POST' &&
+                    url.pathname.startsWith('/api/')) {
+                    const { methodToKebab } = await import('./shared/expose-route-extractor.js');
+                    const segment = url.pathname.slice('/api/'.length);
+                    // Reject calls that try to reach reserved endpoints ('call', 'ui',
+                    // 'diagnostics', etc.) by checking against the @expose table only —
+                    // a user method named `call` would still bind correctly here.
+                    const exposed = exposes.find((e) => methodToKebab(e.handler) === segment);
+                    if (exposed) {
+                        // Visibility gate. `private` requires Sec-Fetch-Site: same-origin
+                        // (browser-set, can't be forged from a cross-origin caller) so a
+                        // SameSite-style guard works without per-photon session cookies.
+                        // `public` skips the check entirely.
+                        if (exposed.visibility === 'private') {
+                            const sfs = req.headers['sec-fetch-site'];
+                            if (typeof sfs === 'string') {
+                                // Browser-set header — honour it verbatim. Same-origin and
+                                // same-site count as SameSite-equivalent; anything else
+                                // ('cross-site', 'none', etc.) is rejected even on
+                                // localhost so a malicious page from another origin can't
+                                // exploit a dev tool's loopback access.
+                                const value = sfs.toLowerCase();
+                                const ok = value === 'same-origin' || value === 'same-site';
+                                if (!ok) {
+                                    res.writeHead(403).end('Forbidden: cross-site @expose call');
+                                    return;
+                                }
+                            }
+                            else if (!isLocalRequest(req)) {
+                                // Non-browser callers (curl, node fetch) often omit the
+                                // header. Allow them only on the loopback interface so a
+                                // public deploy still requires browser-asserted same-origin.
+                                res.writeHead(403).end('Forbidden: missing same-origin signal');
+                                return;
+                            }
+                        }
+                        matchedRoute = { handler: exposed.handler, expose: exposed.visibility };
+                    }
+                }
+                if (matchedRoute) {
+                    // Track C closure (extended): @get/@post and @expose dispatchers
+                    // share the same per-claim instance pool that `handleCallTool`
+                    // uses, so `@stateful` + `@auth` photons isolate state across
+                    // callers regardless of which HTTP surface invokes the method.
+                    // Without this, a `@stateful` + `@auth` photon's `@expose private`
+                    // method (the natural multi-tenant SPA shape) would leak state
+                    // across users — Alice's POST /api/<kebab> would see Bob's
+                    // tasks even though their tools/call paths stay isolated.
+                    const { extractClaimsFromHeaders } = await import('./shared/extract-claims.js');
+                    const httpClaims = extractClaimsFromHeaders(req.headers);
+                    const targetMcp = await this.resolveInstanceMcp(httpClaims ? { authInfo: { extra: httpClaims } } : undefined);
+                    const photonInstance = targetMcp?.instance;
+                    const fn = photonInstance?.[matchedRoute.handler];
+                    if (typeof fn === 'function') {
+                        try {
+                            // Collect body for POST routes
+                            let bodyBuffer = Buffer.alloc(0);
+                            await new Promise((resolve) => {
+                                req.on('data', (chunk) => {
+                                    bodyBuffer = Buffer.concat([bodyBuffer, chunk]);
                                 });
-                                const webRes = await fn.call(photonInstance, webReq);
+                                req.on('end', resolve);
+                            });
+                            // Build Web-standard Request
+                            const webReq = new Request(url.toString(), {
+                                method: req.method,
+                                headers: req.headers,
+                                ...(req.method !== 'GET' && bodyBuffer.length > 0 ? { body: bodyBuffer } : {}),
+                            });
+                            // @expose dispatches receive the parsed JSON body as the first
+                            // arg so handlers share the MCP `addTask({title})`-style
+                            // signature; @get/@post handlers keep the Request directly so
+                            // they can read headers / streams. Empty body → empty object.
+                            let result;
+                            if (matchedRoute.expose && req.method !== 'GET') {
+                                let parsed = {};
+                                if (bodyBuffer.length > 0) {
+                                    try {
+                                        parsed = JSON.parse(bodyBuffer.toString('utf-8'));
+                                    }
+                                    catch {
+                                        res.writeHead(400).end('Invalid JSON body');
+                                        return;
+                                    }
+                                }
+                                result = await fn.call(photonInstance, parsed);
+                            }
+                            else {
+                                result = await fn.call(photonInstance, webReq);
+                            }
+                            // Pass-through: if the handler already returned a Response, do
+                            // NOT touch its bytes. This is the v1.28 contract and is
+                            // locked by tests/v128-byte-compat.test.ts.
+                            if (result instanceof Response) {
                                 const responseHeaders = {};
-                                webRes.headers.forEach((value, key) => {
+                                result.headers.forEach((value, key) => {
                                     responseHeaders[key] = value;
                                 });
                                 if (corsOrigin)
                                     responseHeaders['Access-Control-Allow-Origin'] = corsOrigin;
-                                res.writeHead(webRes.status, responseHeaders);
-                                res.end(Buffer.from(await webRes.arrayBuffer()));
-                            }
-                            catch (err) {
-                                res.writeHead(500).end(err?.message ?? 'Internal Server Error');
+                                res.writeHead(result.status, responseHeaders);
+                                res.end(Buffer.from(await result.arrayBuffer()));
+                                return;
                             }
-                            return;
+                            // Track A: handler returned a plain value. Negotiate Accept
+                            // against the registry, taking the @format JSDoc declaration
+                            // into account, and write the rendered body.
+                            const { negotiateAccept } = await import('./format/registry.js');
+                            const { getDefaultRegistry } = await import('./format/seed.js');
+                            const acceptHeader = req.headers['accept'];
+                            const rendered = negotiateAccept({
+                                accept: typeof acceptHeader === 'string' ? acceptHeader : undefined,
+                                declaredFormat: matchedRoute.format,
+                                value: result,
+                                registry: getDefaultRegistry(),
+                            });
+                            const negotiatedHeaders = {
+                                'Content-Type': rendered.mime,
+                            };
+                            if (corsOrigin)
+                                negotiatedHeaders['Access-Control-Allow-Origin'] = corsOrigin;
+                            res.writeHead(200, negotiatedHeaders);
+                            res.end(typeof rendered.body === 'string' ? rendered.body : Buffer.from(rendered.body));
                         }
+                        catch (err) {
+                            res.writeHead(500).end(err?.message ?? 'Internal Server Error');
+                        }
+                        return;
                     }
                 }
                 res.writeHead(404).end('Not Found');
@@ -2272,15 +2858,31 @@ export class PhotonServer {
             capabilities: {
                 tools: { listChanged: true },
                 prompts: { listChanged: true },
-                resources: { listChanged: true },
+                resources: { listChanged: true, subscribe: true },
                 logging: {},
                 experimental: {
                     sampling: {}, // Support elicitation via MCP sampling protocol
                 },
             },
         });
+        // Per-session sink for `notifications/resources/updated`. Identity is
+        // stable across this session so SubscriptionRegistry can index by it and
+        // the disconnect handler can purge subscriptions in one call.
+        const sessionSink = (uri) => sessionServer.notification({
+            method: 'notifications/resources/updated',
+            params: { uri },
+        });
+        // Mirror web capability onto the per-session server when the photon has web routes.
+        const sessionWebMeta = this.mcp?._httpRoutes?.find((r) => r.method === 'GET' && r.path === '/');
+        if (sessionWebMeta) {
+            const httpPort = Number(this.options.port) || 3000;
+            const webDescription = this.mcp?.description || `${this.mcp?.name} web interface`;
+            sessionServer.registerCapabilities({
+                web: { url: `http://localhost:${httpPort}`, description: webDescription },
+            });
+        }
         // Copy handlers to the session server
-        this.setupSessionHandlers(sessionServer);
+        this.setupSessionHandlers(sessionServer, sessionSink);
         // Create SSE transport
         const transport = new SSEServerTransport(messagesPath, res);
         this.capabilityNegotiator.interceptTransportForRawCapabilities(transport, sessionServer, (msg) => this.channelManager.interceptPermissionRequest(msg));
@@ -2295,6 +2897,7 @@ export class PhotonServer {
                 return;
             closing = true;
             this.sseSessions.delete(sessionId);
+            this.subscriptions.disconnect(sessionSink);
             this.log('info', 'SSE client disconnected', { sessionId });
             void (async () => {
                 try {
@@ -2361,7 +2964,7 @@ export class PhotonServer {
      * Set up handlers for a session-specific MCP server
      * This duplicates handlers from the main server to each session
      */
-    setupSessionHandlers(sessionServer) {
+    setupSessionHandlers(sessionServer, sessionSink) {
         this.logClientCapabilities(sessionServer);
         const sseSessionKey = `sse-${this.daemonName}`;
         const ctx = {
@@ -2375,9 +2978,9 @@ export class PhotonServer {
         sessionServer.setRequestHandler(ListToolsRequestSchema, async () => {
             return this.handleListTools(ctx);
         });
-        sessionServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+        sessionServer.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             try {
-                return await this.handleCallTool(ctx, request);
+                return await this.handleCallTool(ctx, request, extra);
             }
             catch (error) {
                 const { name: toolName, arguments: args } = request.params;
@@ -2399,6 +3002,17 @@ export class PhotonServer {
         sessionServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             return this.resourceServer.handleReadResource(request, this.mcp);
         });
+        if (sessionSink) {
+            sessionServer.setRequestHandler(SubscribeRequestSchema, async (request) => {
+                this.subscriptions.subscribe(sessionSink, request.params.uri);
+                return {};
+            });
+            sessionServer.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+                this.subscriptions.unsubscribe(sessionSink, request.params.uri);
+                return {};
+            });
+        }
+        this.setupRootsForServer(sessionServer);
     }
     /**
      * Stop the server