@adobe/llm-apps-runtime 0.2.0

package/src/loader.js

@@ -0,0 +1,496 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * Action Loader for @adobe/llm-apps-runtime.
+ *
+ * Two loading paths:
+ *
+ *   loadActionsFromContexts(server, { moduleContext, htmlContext, actionsConfig })
+ *     Used at runtime when webpack has already resolved the action modules and widget
+ *     HTML files into context objects. Called from the consumer app's entry.js.
+ *
+ *   loadActionsFromFs(server, actionsDir, actionsConfig)
+ *     Used in Jest tests and any environment without webpack (plain Node).
+ *     Reads modules and HTML files directly from the filesystem.
+ *
+ * Registration is driven by actionsConfig (the parsed actions.json) in both paths.
+ * When actionsConfig is empty, both paths fall back to filesystem discovery and print
+ * a banner reminding the developer to download actions.json from the llm-apps UI.
+ *
+ * Widget resolution priority (same in both paths):
+ *   1. widget.html file in the action directory
+ *   2. EDS config in actionsConfig (auto-generates aem-embed template)
+ *   3. Tool-only (no widget)
+ *
+ * Handler export shape (only shape accepted):
+ *   module.exports = async (args) => ({ content, structuredContent? })
+ * ESM default-function exports are also accepted.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { z } = require('zod')
+const { safeSize } = require('./analytics.js')
+
+const RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app'
+
+const MISSING_CONFIG_BANNER = [
+    '',
+    '  ┌─────────────────────────────────────────────────────────────────────┐',
+    '  │  No actions.json found.                                             │',
+    '  │  Handlers will be registered with empty metadata.                   │',
+    '  │  Download actions.json from the llm-apps UI to mirror production.   │',
+    '  └─────────────────────────────────────────────────────────────────────┘',
+    ''
+].join('\n')
+
+function normalizeAction (mod) {
+    if (typeof mod === 'function') return { handler: mod }
+    if (mod && typeof mod.default === 'function') return { handler: mod.default }
+    return null
+}
+
+function validateAction (mod, source) {
+    if (normalizeAction(mod)) return true
+    console.warn(`Skipping ${source}: expected module.exports to be an async function`)
+    return false
+}
+
+function createDefaultHandler () {
+    return async () => ({
+        content: [{ type: 'text', text: '' }],
+        structuredContent: {}
+    })
+}
+
+function jsonSchemaPropertyToZod (prop, isRequired) {
+    let zodType
+    if (prop.enum) {
+        zodType = z.enum(prop.enum)
+    } else {
+        switch (prop.type) {
+        case 'string':
+            zodType = z.string()
+            break
+        case 'number':
+            zodType = z.number()
+            break
+        case 'integer':
+            zodType = z.number().int()
+            break
+        case 'boolean':
+            zodType = z.boolean()
+            break
+        case 'array':
+            zodType = z.array(prop.items ? jsonSchemaPropertyToZod(prop.items, true) : z.any())
+            break
+        default:
+            zodType = z.any()
+        }
+    }
+    if (prop.description) zodType = zodType.describe(prop.description)
+    if (!isRequired) zodType = zodType.optional()
+    return zodType
+}
+
+function jsonSchemaToZodShape (jsonSchema) {
+    if (!jsonSchema || jsonSchema.type !== 'object' || !jsonSchema.properties) {
+        return undefined
+    }
+    const required = new Set(jsonSchema.required || [])
+    const shape = {}
+    for (const [key, prop] of Object.entries(jsonSchema.properties)) {
+        shape[key] = jsonSchemaPropertyToZod(prop, required.has(key))
+    }
+    return shape
+}
+
+function buildResourceMeta (resourceMeta) {
+    if (!resourceMeta) return undefined
+
+    const ui = {}
+    const src = resourceMeta.ui || resourceMeta
+    if (src.csp) ui.csp = src.csp
+    if (src.permissions) ui.permissions = src.permissions
+    if (src.domain !== undefined) ui.domain = src.domain
+    if (src.prefersBorder !== undefined) ui.prefersBorder = src.prefersBorder
+
+    return Object.keys(ui).length > 0 ? { ui } : undefined
+}
+
+function generateEdsWidgetHtml (config) {
+    if (config?.widget_type !== 'EDS') return null
+
+    const edsWidget = config.eds_widget
+    if (!edsWidget?.script_url || !edsWidget?.widget_embed_url) {
+        console.warn(`  ⚠ EDS widget for "${config.name}": missing script_url or widget_embed_url in eds_widget config`)
+        return null
+    }
+
+    return `<script src="${edsWidget.script_url}" type="module"></script>\n<div>\n    <aem-embed url="${edsWidget.widget_embed_url}"></aem-embed>\n</div>\n`
+}
+
+/**
+ * Wrap a tool handler with analytics instrumentation.
+ *
+ * Captures per-call timing/size into a per-invocation buffer that the
+ * server flushes as one signed batch at end-of-request. Inputs and outputs
+ * are NEVER serialized — only byte sizes via safeSize().
+ *
+ * If analyticsConfig is absent (no buffer) the original handler is returned
+ * unchanged so unconfigured deploys cost zero overhead.
+ */
+function wrapHandlerWithAnalytics (name, handler, analyticsConfig) {
+    if (!analyticsConfig || !analyticsConfig.buffer) return handler
+
+    return async function instrumented (...args) {
+        const startedAt = Date.now()
+        const occurredAt = new Date(startedAt).toISOString()
+        const inputSize = safeSize(args[0])
+
+        try {
+            const result = await handler(...args)
+            analyticsConfig.buffer.push({
+                occurred_at: occurredAt,
+                tool_name: name,
+                duration_ms: Date.now() - startedAt,
+                status: 'ok',
+                input_size_bytes: inputSize,
+                output_size_bytes: safeSize(result),
+                mcp_method: 'tools/call'
+            })
+            return result
+        } catch (err) {
+            const errorClass = (err && err.constructor && err.constructor.name) || 'Error'
+            analyticsConfig.buffer.push({
+                occurred_at: occurredAt,
+                tool_name: name,
+                duration_ms: Date.now() - startedAt,
+                status: 'error',
+                input_size_bytes: inputSize,
+                output_size_bytes: 0,
+                mcp_method: 'tools/call',
+                error_class: errorClass
+            })
+            throw err
+        }
+    }
+}
+
+function registerAction (server, name, action, widgetHtml, config, analyticsConfig) {
+    const toolMeta = {}
+
+    const inputSchema = config?.inputSchema ? jsonSchemaToZodShape(config.inputSchema) : undefined
+
+    if (widgetHtml) {
+        const resourceUri = `ui://${name}/widget.html`
+        const resourceMeta = buildResourceMeta(config?.resource_meta)
+
+        server.registerResource(
+            `${name}-widget`,
+            resourceUri,
+            { mimeType: RESOURCE_MIME_TYPE },
+            async () => ({
+                contents: [{
+                    uri: resourceUri,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: widgetHtml,
+                    ...(resourceMeta ? { _meta: resourceMeta } : {})
+                }]
+            })
+        )
+
+        toolMeta.ui = { resourceUri, ...(config?.tool_meta?.ui || {}) }
+        toolMeta['ui/resourceUri'] = resourceUri
+        toolMeta['openai/outputTemplate'] = resourceUri
+        toolMeta['openai/resultCanProduceWidget'] = true
+    }
+
+    if (config?.tool_meta) {
+        for (const [key, value] of Object.entries(config.tool_meta)) {
+            if (key !== 'ui') {
+                toolMeta[key] = value
+            }
+        }
+    }
+
+    // Per-action gate: only wrap when the action explicitly opts in AND the
+    // runtime has analytics configured. Either gate failing => bare handler.
+    const wrappedHandler = (config?.analyticsEnabled === true && analyticsConfig)
+        ? wrapHandlerWithAnalytics(name, action.handler, analyticsConfig)
+        : action.handler
+
+    server.registerTool(name, {
+        title: config?.title || name,
+        description: config?.description || name,
+        inputSchema,
+        annotations: config?.annotations || undefined,
+        _meta: Object.keys(toolMeta).length > 0 ? toolMeta : undefined
+    }, wrappedHandler)
+}
+
+/**
+ * Load actions config from actions.json, keyed by action name.
+ * Looks for actions.json at actionsDir/../actions.json (the app root).
+ */
+function loadActionsConfig (actionsDir) {
+    const configPath = path.resolve(actionsDir, '..', 'actions.json')
+    try {
+        if (fs.existsSync(configPath)) {
+            const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+            const map = {}
+            for (const act of raw.actions || []) {
+                if (act.name) map[act.name] = act
+            }
+            console.log(`Loaded actions.json with ${Object.keys(map).length} action(s)`)
+            return map
+        }
+    } catch (e) {
+        console.warn('Failed to load actions.json:', e.message)
+    }
+    return {}
+}
+
+/**
+ * Resolve actions from webpack-resolved context maps into a plain array.
+ *
+ * Returns [{ name, action, widgetHtml, config }] — no McpServer param.
+ * Logs startup info once. Intended to be called at createMain() time so
+ * logs fire on cold start only, not on every request.
+ *
+ * actionsConfig — raw actions.json: { actions: [{ name, ... }, ...] }
+ *                 Pass require('./actions.json') directly from entry.js.
+ */
+function resolveActionsFromContexts ({ moduleContext, htmlContext, actionsConfig }) {
+    const moduleMap = {}
+    for (const key of moduleContext.keys()) {
+        moduleMap[key.split('/')[1]] = moduleContext(key)
+    }
+
+    const widgetMap = {}
+    for (const key of htmlContext.keys()) {
+        widgetMap[key.split('/')[1]] = htmlContext(key)
+    }
+
+    const resolved = []
+    const configActions = (actionsConfig && actionsConfig.actions || []).filter(a => a && a.name)
+
+    if (configActions.length > 0) {
+        console.log(`Registering ${configActions.length} action(s) from actions.json`)
+
+        for (const config of configActions) {
+            const name = config.name
+            try {
+                const mod = moduleMap[name] || moduleMap[name.replace(/_/g, '-')]
+                const action = mod && validateAction(mod, name)
+                    ? normalizeAction(mod)
+                    : { handler: createDefaultHandler() }
+                const widgetHtml = widgetMap[name] || widgetMap[name.replace(/_/g, '-')] || generateEdsWidgetHtml(config)
+
+                const hasHandler = !!mod
+                if (widgetMap[name] || widgetMap[name.replace(/_/g, '-')]) {
+                    console.log(`  ✓ ${name} (${hasHandler ? 'handler' : 'default'} + widget)`)
+                } else if (widgetHtml) {
+                    console.log(`  ✓ ${name} (${hasHandler ? 'handler' : 'default'} + EDS widget)`)
+                } else {
+                    console.log(`  ✓ ${name} (${hasHandler ? 'handler' : 'default'}, tool only)`)
+                }
+
+                resolved.push({ name, action, widgetHtml, config })
+            } catch (error) {
+                console.error(`Error resolving action "${name}":`, error.message)
+            }
+        }
+    } else {
+        console.warn(MISSING_CONFIG_BANNER)
+
+        const modules = moduleContext.keys()
+        console.log(`Discovering ${modules.length} action(s) from filesystem`)
+
+        for (const key of modules) {
+            try {
+                const mod = moduleContext(key)
+                const dirName = key.split('/')[1]
+
+                if (!validateAction(mod, key)) continue
+
+                const action = normalizeAction(mod)
+                const widgetHtml = widgetMap[dirName] || null
+
+                if (widgetHtml) {
+                    console.log(`  ✓ Loaded action: ${dirName} (tool + widget)`)
+                } else {
+                    console.log(`  ✓ Loaded action: ${dirName} (tool only)`)
+                }
+
+                resolved.push({ name: dirName, action, widgetHtml, config: undefined })
+            } catch (error) {
+                console.error(`Error loading action from ${key}:`, error.message)
+            }
+        }
+    }
+
+    return resolved
+}
+
+/**
+ * Resolve actions from the filesystem into a plain array.
+ *
+ * Returns [{ name, action, widgetHtml, config }] — no McpServer param.
+ * Logs startup info once. Intended to be called at createMain() time.
+ */
+function resolveActionsFromFs (actionsDir, actionsConfig) {
+    const resolved = []
+    const configNames = Object.keys(actionsConfig)
+
+    if (configNames.length > 0) {
+        console.log(`Registering ${configNames.length} action(s) from actions.json`)
+
+        for (const name of configNames) {
+            try {
+                const config = actionsConfig[name]
+                const dirName = fs.existsSync(path.join(actionsDir, name)) ? name : name.replace(/_/g, '-')
+                const indexPath = path.join(actionsDir, dirName, 'index.js')
+                const hasHandler = fs.existsSync(indexPath)
+
+                const action = hasHandler
+                    ? (mod => validateAction(mod, name) ? normalizeAction(mod) : { handler: createDefaultHandler() })(require(indexPath))
+                    : { handler: createDefaultHandler() }
+
+                const widgetPath = path.join(actionsDir, dirName, 'widget.html')
+                const hasWidgetFile = fs.existsSync(widgetPath)
+                const widgetHtml = hasWidgetFile
+                    ? fs.readFileSync(widgetPath, 'utf-8')
+                    : generateEdsWidgetHtml(config)
+
+                if (hasWidgetFile) {
+                    console.log(`  ✓ ${name} (${hasHandler ? 'handler' : 'default'} + widget)`)
+                } else if (widgetHtml) {
+                    console.log(`  ✓ ${name} (${hasHandler ? 'handler' : 'default'} + EDS widget)`)
+                } else {
+                    console.log(`  ✓ ${name} (${hasHandler ? 'handler' : 'default'}, tool only)`)
+                }
+
+                resolved.push({ name, action, widgetHtml, config })
+            } catch (error) {
+                console.error(`Error resolving action "${name}":`, error.message)
+            }
+        }
+    } else {
+        console.warn(MISSING_CONFIG_BANNER)
+
+        if (!fs.existsSync(actionsDir)) {
+            console.warn(`Actions directory not found: ${actionsDir}`)
+            return resolved
+        }
+
+        const dirs = fs.readdirSync(actionsDir, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name)
+
+        console.log(`Discovering ${dirs.length} action(s) from ${actionsDir}`)
+
+        for (const dirName of dirs) {
+            try {
+                const indexPath = path.join(actionsDir, dirName, 'index.js')
+                if (!fs.existsSync(indexPath)) {
+                    console.warn(`Skipping ${dirName}: no index.js found`)
+                    continue
+                }
+
+                const mod = require(indexPath)
+                if (!validateAction(mod, dirName)) continue
+
+                const action = normalizeAction(mod)
+                const widgetPath = path.join(actionsDir, dirName, 'widget.html')
+                const hasWidgetFile = fs.existsSync(widgetPath)
+                const widgetHtml = hasWidgetFile ? fs.readFileSync(widgetPath, 'utf-8') : null
+
+                if (hasWidgetFile) {
+                    console.log(`  ✓ Loaded action: ${dirName} (tool + widget)`)
+                } else {
+                    console.log(`  ✓ Loaded action: ${dirName} (tool only)`)
+                }
+
+                resolved.push({ name: dirName, action, widgetHtml, config: undefined })
+            } catch (error) {
+                console.error(`Error loading action from ${dirName}:`, error.message)
+            }
+        }
+    }
+
+    return resolved
+}
+
+/**
+ * Resolve actions from either webpack contexts or the filesystem.
+ *
+ * Picks the right path based on options:
+ *   - options.moduleContext present → resolveActionsFromContexts
+ *   - otherwise → resolveActionsFromFs
+ *
+ * Returns [{ name, action, widgetHtml, config }].
+ * Call once at createMain() time; pass the result to createMcpServer().
+ */
+function resolveActions (options) {
+    if (options.moduleContext !== undefined) {
+        return resolveActionsFromContexts({
+            moduleContext: options.moduleContext,
+            htmlContext: options.htmlContext || { keys: () => [] },
+            actionsConfig: options.actionsConfig || {}
+        })
+    }
+    const actionsDir = options.actionsDir || path.join(process.cwd(), 'actions')
+    const cfg = loadActionsConfig(actionsDir)
+    return resolveActionsFromFs(actionsDir, cfg)
+}
+
+/**
+ * Register actions from webpack-resolved context maps onto an McpServer.
+ *
+ * Thin wrapper around resolveActionsFromContexts + registerAction.
+ * Used directly in tests and anywhere a server instance is already available.
+ * In production (createMain), prefer resolveActions + registerAction loop
+ * so resolution happens once at startup rather than per-request.
+ */
+function loadActionsFromContexts (server, { moduleContext, htmlContext, actionsConfig }, analyticsConfig) {
+    const resolved = resolveActionsFromContexts({ moduleContext, htmlContext, actionsConfig })
+    for (const { name, action, widgetHtml, config } of resolved) {
+        registerAction(server, name, action, widgetHtml, config, analyticsConfig)
+    }
+}
+
+/**
+ * Filesystem-based action loading.
+ *
+ * Thin wrapper around resolveActionsFromFs + registerAction.
+ * Used in Jest tests and plain Node environments without webpack.
+ */
+function loadActionsFromFs (server, actionsDir, actionsConfig, analyticsConfig) {
+    const resolved = resolveActionsFromFs(actionsDir, actionsConfig)
+    for (const { name, action, widgetHtml, config } of resolved) {
+        registerAction(server, name, action, widgetHtml, config, analyticsConfig)
+    }
+}
+
+module.exports = {
+    resolveActions,
+    loadActionsFromContexts,
+    loadActionsFromFs,
+    loadActionsConfig,
+    createDefaultHandler,
+    generateEdsWidgetHtml,
+    registerAction,
+    wrapHandlerWithAnalytics,
+    RESOURCE_MIME_TYPE
+}

package/src/local.js

@@ -0,0 +1,91 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * Local development HTTP server for MCP Apps.
+ *
+ * Wraps a main() function (from createMain) in a plain Node.js HTTP server so
+ * developers can run without Adobe I/O Runtime credentials.
+ *
+ * Usage in consumer app server/local.js:
+ *
+ *   const { createLocalServer } = require('@adobe/llm-apps-runtime')
+ *   const { main } = require('../dist/index.js')   // webpack bundle
+ *   createLocalServer(main, process.env.PORT || 9080)
+ */
+
+const http = require('http')
+
+/**
+ * Start a local HTTP server that routes plain HTTP requests to an MCP main() function.
+ *
+ * @param {Function} main   The main(params) function returned by createMain
+ * @param {number}   port   Port to listen on (default 9080)
+ * @returns {http.Server}
+ */
+function createLocalServer (main, port) {
+    // Use ?? (not ||) so an explicit 0 (ephemeral port, useful for tests) is honored.
+    const listenPort = port ?? 9080
+
+    const server = http.createServer(async (req, res) => {
+        const chunks = []
+        req.on('data', chunk => chunks.push(chunk))
+        req.on('end', async () => {
+            const rawBody = Buffer.concat(chunks).toString('utf8')
+
+            const params = {
+                __ow_method: req.method.toLowerCase(),
+                __ow_path: req.url,
+                __ow_body: rawBody || undefined,
+                __ow_headers: req.headers,
+                LOG_LEVEL: process.env.LOG_LEVEL || 'info'
+            }
+
+            try {
+                const result = await main(params)
+
+                res.statusCode = result.statusCode || 200
+                for (const [key, value] of Object.entries(result.headers || {})) {
+                    res.setHeader(key, value)
+                }
+                res.end(result.body || '')
+            } catch (err) {
+                console.error('Unhandled error:', err)
+                res.statusCode = 500
+                res.setHeader('Content-Type', 'application/json')
+                res.end(JSON.stringify({ error: err.message }))
+            }
+        })
+    })
+
+    server.listen(listenPort, () => {
+        // When listenPort is 0, the OS picks the real port — read it back.
+        const actualPort = server.address().port
+        console.log('')
+        console.log('  LLM Apps local server running')
+        console.log(`  Endpoint: http://localhost:${actualPort}`)
+        console.log('')
+        console.log('  To test:')
+        console.log(`    curl -sX POST http://localhost:${actualPort} \\`)
+        console.log('      -H \'content-type: application/json\' \\')
+        console.log('      -H \'accept: application/json;q=1.0, text/event-stream;q=0.5\' \\')
+        console.log('      -d \'{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\' | python3 -m json.tool')
+        console.log('')
+        console.log('  MCP Inspector:  npx @modelcontextprotocol/inspector')
+        console.log(`  Inspector URL:  http://localhost:${actualPort}`)
+        console.log('')
+    })
+
+    return server
+}
+
+module.exports = { createLocalServer }