@portel/photon 1.28.2 → 1.29.0

package/dist/auto-ui/streamable-http-transport.js

@@ -18,6 +18,7 @@
  */
 import { randomUUID } from 'crypto';
 import { readdir, stat, readFile, writeFile } from 'fs/promises';
+import { readText } from '../shared/io.js';
 import { join, dirname, extname, resolve, normalize } from 'path';
 import { homedir } from 'os';
 import { PHOTON_VERSION } from '../version.js';
@@ -34,6 +35,7 @@ import { buildToolMetadataExtensions } from './types.js';
 import { generateServerCard } from '../server-card.js';
 import { audit } from '../shared/audit.js';
 import { writePhotonEditorDeclaration } from '../photon-editor-declarations.js';
+import { isUriTemplate, matchUriTemplate, parseUriTemplateParams, SubscriptionRegistry, } from '../resource-server.js';
 import { createTask, getTask, updateTask, listTasks, registerController, unregisterController, getController, taskEvents, } from '../tasks/store.js';
 import { toWireFormat, relatedTaskMeta, TERMINAL_STATES } from '../tasks/types.js';
 import { runTaskExecution, resolveTaskInput, waitForTerminalOrInput } from '../tasks/executor.js';
@@ -76,6 +78,40 @@ const sessions = new Map();
 const pendingElicitations = new Map();
 const pendingServerRequests = new Map();
 let nextServerRequestId = 1;
+/**
+ * Registry of `resources/subscribe` state for the streamable-HTTP transport.
+ * Sinks are keyed by sessionId so per-session disconnect can purge in O(1).
+ *
+ * `attachLoaderForResourceUpdates(loader)` (exported) bridges photon-author
+ * `this.notifyResourceUpdated(uri)` calls into `streamableSubscriptions.notify(uri)`
+ * so subscribers get `notifications/resources/updated` over the SSE stream.
+ */
+const streamableSubscriptions = new SubscriptionRegistry();
+const sessionSubscriptionSinks = new Map();
+function getOrCreateSessionSink(sessionId) {
+    const existing = sessionSubscriptionSinks.get(sessionId);
+    if (existing)
+        return existing;
+    const sink = (uri) => {
+        sendToSession(sessionId, 'notifications/resources/updated', { uri });
+    };
+    sessionSubscriptionSinks.set(sessionId, sink);
+    return sink;
+}
+function disconnectSessionSubscriptions(sessionId) {
+    const sink = sessionSubscriptionSinks.get(sessionId);
+    if (!sink)
+        return;
+    streamableSubscriptions.disconnect(sink);
+    sessionSubscriptionSinks.delete(sessionId);
+}
+/**
+ * Wire a PhotonLoader's `notifyResourceUpdated` channel into the streamable-HTTP
+ * subscription registry. Call once at server start.
+ */
+export function attachLoaderForResourceUpdates(loader) {
+    loader.setResourceUpdateNotifier((uri) => streamableSubscriptions.notify(uri));
+}
 /**
  * Send a JSON-RPC request to a Beam session over its SSE stream and
  * await the reply. Backs photon-facing providers (sampling, future
@@ -339,6 +375,7 @@ function startSessionCleanup() {
         for (const [id, session] of sessions) {
             if (now - session.lastActivity.getTime() > SESSION_TIMEOUT_MS) {
                 sessions.delete(id);
+                disconnectSessionSubscriptions(id);
             }
         }
     }, 60 * 1000);
@@ -556,7 +593,7 @@ const handlers = {
                 capabilities: {
                     tools: { listChanged: true },
                     prompts: { listChanged: true },
-                    resources: { listChanged: true },
+                    resources: { listChanged: true, subscribe: true },
                     tasks: {
                         list: {},
                         cancel: {},
@@ -2049,23 +2086,72 @@ const handlers = {
         }
     },
     // ─────────────────────────────────────────────────────────────────────────────
-    // Resources (MCP Apps ui:// scheme)
+    // Resources
+    //
+    // Mirrors what STDIO surfaces via ResourceServer (src/resource-server.ts):
+    // - ui://<photon>/<id>            UI Apps templates (assets.ui)
+    // - approval://<photon>/<id>      pending approval requests
+    // - photon://<photon>/prompts/<id>  class-level @prompt static-file
+    // - photon://<photon>/resources/<id>  class-level @resource static-file
+    // - <author-defined-uri>          method-level @resource / @Static
+    //                                 (non-templated entries from mcp.statics)
+    //
+    // Templated method-level URIs (`person://{slug}`) belong on
+    // resources/templates/list and resolve via resources/read.
     // ─────────────────────────────────────────────────────────────────────────────
     'resources/list': async (req, session, ctx) => {
         const resources = [];
         for (const photon of ctx.photons) {
-            if (!photon.configured || !photon.assets?.ui)
+            if (!photon.configured)
                 continue;
-            for (const uiAsset of photon.assets.ui) {
-                const uri = uiAsset.uri || `ui://${photon.name}/${uiAsset.id}`;
-                resources.push({
-                    uri,
-                    name: uiAsset.id,
-                    mimeType: uiAsset.mimeType || 'text/html;profile=mcp-app',
-                    description: uiAsset.linkedTool
-                        ? `UI template for ${photon.name}/${uiAsset.linkedTool}`
-                        : `UI template: ${uiAsset.id}`,
-                });
+            const mcp = ctx.photonMCPs.get(photon.name);
+            if (photon.assets?.ui) {
+                for (const uiAsset of photon.assets.ui) {
+                    const uri = uiAsset.uri || `ui://${photon.name}/${uiAsset.id}`;
+                    resources.push({
+                        uri,
+                        name: uiAsset.id,
+                        mimeType: uiAsset.mimeType || 'text/html;profile=mcp-app',
+                        description: uiAsset.linkedTool
+                            ? `UI template for ${photon.name}/${uiAsset.linkedTool}`
+                            : `UI template: ${uiAsset.id}`,
+                    });
+                }
+            }
+            // Class-level @prompt <id> <path> static-file prompts
+            if (mcp?.assets?.prompts) {
+                for (const prompt of mcp.assets.prompts) {
+                    resources.push({
+                        uri: `photon://${photon.name}/prompts/${prompt.id}`,
+                        name: `prompt:${prompt.id}`,
+                        mimeType: 'text/markdown',
+                        description: `Prompt template: ${prompt.id}`,
+                    });
+                }
+            }
+            // Class-level @resource <id> <path> static-file resources
+            if (mcp?.assets?.resources) {
+                for (const resource of mcp.assets.resources) {
+                    resources.push({
+                        uri: `photon://${photon.name}/resources/${resource.id}`,
+                        name: `resource:${resource.id}`,
+                        mimeType: resource.mimeType || 'application/octet-stream',
+                        description: `Static resource: ${resource.id}`,
+                    });
+                }
+            }
+            // Method-level @resource / @Static — non-templated URIs only.
+            if (mcp?.statics) {
+                for (const stat of mcp.statics) {
+                    if (isUriTemplate(stat.uri))
+                        continue;
+                    resources.push({
+                        uri: stat.uri,
+                        name: stat.name,
+                        mimeType: stat.mimeType || 'text/plain',
+                        description: stat.description || `Resource: ${stat.name}`,
+                    });
+                }
             }
         }
         // Add pending approval resources (approval:// scheme)
@@ -2081,9 +2167,30 @@ const handlers = {
         }
         return { jsonrpc: '2.0', id: req.id, result: { resources } };
     },
+    'resources/templates/list': async (req, _session, ctx) => {
+        const resourceTemplates = [];
+        for (const photon of ctx.photons) {
+            if (!photon.configured)
+                continue;
+            const mcp = ctx.photonMCPs.get(photon.name);
+            if (!mcp?.statics)
+                continue;
+            for (const stat of mcp.statics) {
+                if (!isUriTemplate(stat.uri))
+                    continue;
+                resourceTemplates.push({
+                    uriTemplate: stat.uri,
+                    name: stat.name,
+                    mimeType: stat.mimeType || 'text/plain',
+                    description: stat.description || `Resource template: ${stat.name}`,
+                });
+            }
+        }
+        return { jsonrpc: '2.0', id: req.id, result: { resourceTemplates } };
+    },
     'resources/read': async (req, session, ctx) => {
         const { uri } = req.params;
-        // Parse approval:// URI
+        // approval://<photon>/<id>
         const approvalMatch = uri.match(/^approval:\/\/([^/]+)\/(.+)$/);
         if (approvalMatch) {
             const [, photonName, approvalId] = approvalMatch;
@@ -2106,36 +2213,128 @@ const handlers = {
                 },
             };
         }
-        // Parse ui:// URI
-        const match = uri.match(/^ui:\/\/([^/]+)\/(.+)$/);
-        if (!match) {
+        // ui://<photon>/<id>
+        const uiMatch = uri.match(/^ui:\/\/([^/]+)\/(.+)$/);
+        if (uiMatch) {
+            const [, photonName, uiId] = uiMatch;
+            const result = await ctx.loadUIAsset(photonName, uiId);
+            if (!result) {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    error: { code: -32602, message: `Resource not found: ${uri}` },
+                };
+            }
+            const mimeType = result.isPhotonTemplate
+                ? 'text/html;profile=mcp-app;photon-template=true'
+                : 'text/html;profile=mcp-app';
             return {
                 jsonrpc: '2.0',
                 id: req.id,
-                error: { code: -32602, message: `Invalid URI: ${uri}` },
+                result: { contents: [{ uri, mimeType, text: result.content }] },
             };
         }
-        const [, photonName, uiId] = match;
-        const result = await ctx.loadUIAsset(photonName, uiId);
-        if (!result) {
+        // photon://<photon>/(prompts|resources)/<id> — class-level static-file assets
+        const assetMatch = uri.match(/^photon:\/\/([^/]+)\/(prompts|resources)\/(.+)$/);
+        if (assetMatch) {
+            const [, photonName, kind, assetId] = assetMatch;
+            const mcp = ctx.photonMCPs.get(photonName);
+            if (!mcp?.assets) {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    error: { code: -32602, message: `Photon assets not found: ${uri}` },
+                };
+            }
+            const list = kind === 'prompts' ? mcp.assets.prompts : mcp.assets.resources;
+            const asset = list?.find((a) => a.id === assetId);
+            const resolvedPath = asset?.resolvedPath;
+            if (!resolvedPath) {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    error: { code: -32602, message: `Asset not found: ${uri}` },
+                };
+            }
+            const text = await readText(resolvedPath);
+            const mimeType = kind === 'prompts'
+                ? 'text/markdown'
+                : asset?.mimeType || 'application/octet-stream';
             return {
                 jsonrpc: '2.0',
                 id: req.id,
-                error: { code: -32602, message: `Resource not found: ${uri}` },
+                result: { contents: [{ uri, mimeType, text }] },
             };
         }
-        // Signal declarative mode (.photon.html) via mimeType parameter
-        const mimeType = result.isPhotonTemplate
-            ? 'text/html;profile=mcp-app;photon-template=true'
-            : 'text/html;profile=mcp-app';
+        // Method-level @resource / @Static — match against any photon's statics.
+        // The URI may be exact or match a registered template; on match, dispatch
+        // through the loader so middleware (auth, logging, audit) applies.
+        for (const photon of ctx.photons) {
+            const mcp = ctx.photonMCPs.get(photon.name);
+            if (!mcp?.statics)
+                continue;
+            for (const stat of mcp.statics) {
+                const matched = stat.uri === uri || matchUriTemplate(stat.uri, uri);
+                if (!matched)
+                    continue;
+                const params = isUriTemplate(stat.uri) ? parseUriTemplateParams(stat.uri, uri) : {};
+                if (!ctx.loader) {
+                    return {
+                        jsonrpc: '2.0',
+                        id: req.id,
+                        error: {
+                            code: -32603,
+                            message: 'Loader not available for static resource resolution',
+                        },
+                    };
+                }
+                const result = await ctx.loader.executeTool(mcp, stat.name, params);
+                const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        contents: [{ uri, mimeType: stat.mimeType || 'text/plain', text }],
+                    },
+                };
+            }
+        }
         return {
             jsonrpc: '2.0',
             id: req.id,
-            result: {
-                contents: [{ uri, mimeType, text: result.content }],
-            },
+            error: { code: -32602, message: `Resource not found: ${uri}` },
         };
     },
+    // resources/subscribe and resources/unsubscribe — exact-URI keyed.
+    // The session's sink is keyed off session.id so disconnect logic in the
+    // session-cleanup path can purge subscriptions in O(1).
+    'resources/subscribe': async (req, session) => {
+        const { uri } = req.params;
+        if (typeof uri !== 'string' || !uri) {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                error: { code: -32602, message: 'resources/subscribe requires `uri`' },
+            };
+        }
+        const sink = getOrCreateSessionSink(session.id);
+        streamableSubscriptions.subscribe(sink, uri);
+        return { jsonrpc: '2.0', id: req.id, result: {} };
+    },
+    'resources/unsubscribe': async (req, session) => {
+        const { uri } = req.params;
+        if (typeof uri !== 'string' || !uri) {
+            return {
+                jsonrpc: '2.0',
+                id: req.id,
+                error: { code: -32602, message: 'resources/unsubscribe requires `uri`' },
+            };
+        }
+        const sink = sessionSubscriptionSinks.get(session.id);
+        if (sink)
+            streamableSubscriptions.unsubscribe(sink, uri);
+        return { jsonrpc: '2.0', id: req.id, result: {} };
+    },
     'prompts/list': async (req, _session, ctx) => {
         const prompts = [];
         for (const photon of ctx.photons) {