@adobe/llm-apps-runtime 0.2.0

package/LICENSE

@@ -0,0 +1,60 @@
+Adobe Inc. ("Adobe")
+Adobe Technology License Terms
+
+================================================================================
+
+NOTICE TO USER: ADOBE LICENSES THE ADOBE TECHNOLOGY ONLY ON THE CONDITION
+THAT YOU ACCEPT ALL OF THE TERMS CONTAINED OR REFERENCED IN THIS AGREEMENT.
+
+================================================================================
+
+YOUR ACCESS TO AND USE OF THE ADOBE TECHNOLOGY IS GOVERNED BY THE ENTERPRISE
+LICENSING TERMS PREVIOUSLY AGREED TO BY YOU AND ADOBE OR AN AUTHORIZED ADOBE
+RESELLER IN A SEPARATE AGREEMENT. IF YOU HAVE NOT PREVIOUSLY AGREED TO
+LICENSING TERMS THEN YOUR INSTALLATION AND USE OF THE ADOBE TECHNOLOGY IS
+SUBJECT TO THE CURRENT APPLICABLE ADOBE LICENSING TERMS AVAILABLE AT
+HTTP://WWW.ADOBE.COM/LEGAL/TERMS/ENTERPRISE-LICENSING.HTML. YOU AGREE THAT
+THIS AGREEMENT WILL HAVE THE SAME EFFECT AS ANY WRITTEN NEGOTIATED AGREEMENT
+SIGNED BY YOU.
+
+By selecting the "I accept" button or other button or mechanism designed to
+acknowledge agreement to the terms of an electronic copy of this Agreement, or
+by installing, downloading, accessing, or otherwise copying or using all or any
+portion of the Adobe Technology:
+
+  (i)   you accept this Agreement on behalf of the entity for which you are
+        authorized to act (e.g., an employer) and acknowledge that such entity
+        is legally bound by this Agreement (and you agree to act in a manner
+        consistent with this Agreement) or, if there is no such entity for
+        which you are authorized to act, you accept this Agreement on behalf
+        of yourself as an individual and acknowledge that you are legally bound
+        by this Agreement,
+
+  (ii)  you represent and warrant that you have the right, power and authority
+        to act on behalf of and bind such entity (if any) or yourself, and
+
+  (iii) you agree, as applicable, to use generative AI Adobe Technology
+        features in accordance with the Adobe Experience Cloud Generative AI
+        User Guidelines located at
+        https://www.adobe.com/legal/licenses-terms/adobe-dx-gen-ai-user-guidelines.html
+        ("Guidelines") which govern your use of generative AI features in the
+        Adobe Technology and are incorporated by reference into this Agreement.
+
+You may not accept this Agreement on behalf of another entity unless you are an
+employee or other agent of such other entity with the right, power and authority
+to act on behalf of such other entity.
+
+BY CLICKING TO ACCEPT, OR BY DOWNLOADING, COPYING, INSTALLING OR USING THE
+ADOBE TECHNOLOGY, YOU ACCEPT AND AGREE TO BE BOUND BY ALL THE TERMS AND
+CONDITIONS OF THIS AGREEMENT INCLUDING ALL TERMS INCORPORATED HEREIN BY
+REFERENCE.
+
+THIS AGREEMENT IS ENFORCEABLE AGAINST ANY PERSON OR ENTITY THAT INSTALLS AND
+USES THE ADOBE TECHNOLOGY AND ANY PERSON OR ENTITY (E.G., SYSTEM INTEGRATOR,
+CONSULTANT OR CONTRACTOR) THAT INSTALLS OR USES THE ADOBE TECHNOLOGY ON
+ANOTHER PERSON'S OR ENTITY'S BEHALF.
+
+================================================================================
+
+EULA-en_US-20250115
+Copyright 2026 Adobe. All rights reserved.

package/README.md

@@ -0,0 +1,243 @@
+# @adobe/llm-apps-runtime
+
+Server runtime for **Adobe LLM Apps** — a platform for building AI tools and interactive widgets that plug into Claude, Cursor, ChatGPT, and other LLM hosts.
+
+This package powers every Adobe LLM App deployed on [Adobe I/O Runtime](https://developer.adobe.com/runtime/). It handles the full request lifecycle — action loading, tool registration, widget resources, CORS, and transport — so app developers only need to write their action handlers. Under the hood it speaks the [Model Context Protocol](https://modelcontextprotocol.io/) via the official [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+
+## Install
+
+```bash
+npm install @adobe/llm-apps-runtime
+```
+
+## Quick start
+
+Wire the runtime into your Adobe I/O Runtime action:
+
+```js
+// entry.js — webpack entry point of your Adobe I/O Runtime action
+const { createMain } = require('@adobe/llm-apps-runtime')
+
+const moduleContext = require.context('./actions', true, /index\.js$/)
+const htmlContext   = require.context('./actions', true, /widget\.html$/)
+let actionsConfig = {}
+try { actionsConfig = require('./actions.json') } catch (e) { /* optional */ }
+
+module.exports = createMain({ moduleContext, htmlContext, actionsConfig })
+```
+
+Write your handlers as plain async functions:
+
+```js
+// actions/echo/index.js
+module.exports = async ({ message }) => ({
+    content: [{ type: 'text', text: `Echo: ${message}` }]
+})
+```
+
+That's it. Deploy with `aio app deploy` and your handlers are reachable as tools in any LLM host that speaks MCP.
+
+## Features
+
+- **Zero-config action discovery** — drop a folder under `actions/`, it becomes a tool
+- **Config-driven metadata** — descriptions, schemas, annotations, and widget config come from `actions.json`
+- **Interactive widgets** — ship `widget.html` alongside your handler for rich UIs in Claude, Cursor, ChatGPT, etc.
+- **EDS widget support** — auto-generate widget markup for [Adobe Edge Delivery Services](https://www.aem.live/) content
+- **Local development** — run your app as a plain HTTP server with no Adobe credentials
+- **Test-friendly** — handlers are plain functions; a filesystem loader lets you write full-stack integration tests without webpack
+
+## API
+
+### `createMain(options)`
+
+Creates the Adobe I/O Runtime `main(params)` function that serves your app.
+
+```js
+const { main } = createMain(options)
+```
+
+**Options**
+
+| Option          | Type            | Default              | Description |
+|-----------------|-----------------|----------------------|-------------|
+| `moduleContext` | webpack context | —                    | `require.context` for `actions/**/index.js`. Webpack path. |
+| `htmlContext`   | webpack context | —                    | `require.context` for `actions/**/widget.html`. Webpack path. |
+| `actionsConfig` | object          | `{}`                 | Parsed `actions.json` keyed by action name. Webpack path. |
+| `actionsDir`    | string          | `<cwd>/actions`      | Absolute path to the actions directory. Fs path. |
+| `serverName`    | string          | `'adobe-llm-apps'`   | App name reported to MCP clients. |
+| `serverVersion` | string          | `'1.0.0'`            | App version reported to MCP clients. |
+
+When `moduleContext` is provided, the webpack path is used. Otherwise the filesystem path is used (via `actionsDir`).
+
+**Returns** `{ main }` — an async function compatible with Adobe I/O Runtime's action signature.
+
+### `createLocalServer(main, port)`
+
+Starts a plain Node.js HTTP server that wraps a `main(params)` function. Useful for `npm run dev:local` in consumer apps — no Adobe credentials required.
+
+```js
+const { createLocalServer } = require('@adobe/llm-apps-runtime')
+const { main } = require('./dist/index.js') // your webpack bundle
+createLocalServer(main, process.env.PORT || 9080)
+```
+
+**Parameters**
+
+| Parameter | Type     | Default | Description |
+|-----------|----------|---------|-------------|
+| `main`    | Function | —       | The `main(params)` function returned by `createMain`. |
+| `port`    | number   | `9080`  | Port to listen on. |
+
+**Returns** an [`http.Server`](https://nodejs.org/api/http.html#class-httpserver) instance.
+
+### Action loading primitives
+
+Exported from the package root for advanced use cases (custom loaders, integration tests):
+
+- `loadActionsFromContexts(server, { moduleContext, htmlContext, actionsConfig })` — webpack-based loader
+- `loadActionsFromFs(server, actionsDir, actionsConfig)` — filesystem-based loader
+- `loadActionsConfig(actionsDir)` — read and key `actions.json` by name
+
+Most users won't need these — `createMain` calls them internally based on which options you pass.
+
+## Handler contract
+
+A handler is an async function exported from `actions/<name>/index.js`:
+
+```js
+module.exports = async function handler(args) {
+    return {
+        // Shown to the LLM and rendered as text by clients
+        content: [{ type: 'text', text: 'Result' }],
+
+        // Optional. Passed to the widget iframe via window.openai.toolOutput.
+        // Never sent to the LLM.
+        structuredContent: { key: 'value' }
+    }
+}
+```
+
+`args` is the tool's `arguments` object, already validated against the `inputSchema` in `actions.json`.
+
+See the [MCP spec](https://modelcontextprotocol.io/docs/concepts/tools) for the full response schema.
+
+## `actions.json`
+
+`actions.json` is the source of truth for tool metadata. The runtime reads it from one level above `actionsDir` (i.e. the app root). Each entry drives tool registration:
+
+```json
+{
+  "actions": [
+    {
+      "name": "my-action",
+      "title": "My Action",
+      "description": "Does something useful",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string", "description": "The query" }
+        },
+        "required": ["query"]
+      },
+      "annotations": { "readOnlyHint": true },
+      "widget_type": "EDS",
+      "eds_widget": {
+        "script_url": "https://.../aem-embed.js",
+        "widget_embed_url": "https://.../embed"
+      },
+      "resource_meta": {
+        "ui": {
+          "csp": { "connect_domains": ["https://..."] },
+          "prefersBorder": true
+        }
+      },
+      "tool_meta": {
+        "openai/widgetAccessible": true
+      }
+    }
+  ]
+}
+```
+
+### Widget resolution priority
+
+1. `widget.html` file in the action directory
+2. EDS config in `actions.json` (auto-generates `<aem-embed>` markup)
+3. Tool-only (no widget)
+
+## Testing your handlers
+
+Handlers are plain async functions — test them directly:
+
+```js
+const handler = require('./index.js')
+
+test('echoes the message', async () => {
+    const out = await handler({ message: 'hello' })
+    expect(out.content[0].text).toBe('Echo: hello')
+})
+```
+
+For full-stack integration tests, use the filesystem loader path:
+
+```js
+const path = require('path')
+const { createMain } = require('@adobe/llm-apps-runtime')
+
+const { main } = createMain({
+    actionsDir: path.join(__dirname, '..', 'actions')
+})
+
+test('tool call returns expected content', async () => {
+    const res = await main({
+        __ow_method: 'post',
+        __ow_body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'tools/call',
+            params: { name: 'echo', arguments: { message: 'hi' } }
+        }),
+        __ow_headers: {
+            'content-type': 'application/json',
+            accept: 'application/json;q=1.0, text/event-stream;q=0.5'
+        }
+    })
+    const body = JSON.parse(res.body)
+    expect(body.result.content[0].text).toBe('Echo: hi')
+})
+```
+
+## Requirements
+
+- Node.js `>=24.0.0` (matches Adobe I/O Runtime `nodejs:24`)
+- Webpack 5 (for bundling when deploying to I/O Runtime)
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) — The open protocol Adobe LLM Apps speak
+- [MCP Apps extension](https://modelcontextprotocol.github.io/ext-apps/) — The widget spec this runtime implements
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) — Underlying protocol implementation
+- [Adobe I/O Runtime](https://developer.adobe.com/runtime/) — Serverless platform Adobe LLM Apps deploy to
+
+## Releasing
+
+Releases are published to npm automatically via GitHub Actions when a GitHub Release is created.
+
+**Steps to release a new version:**
+
+1. Bump the version in `package.json` and commit to `main`:
+   ```bash
+   npm version patch   # or minor / major
+   git push
+   ```
+2. Create a GitHub Release with a tag that matches the version (e.g. `v0.2.0`):
+   - Go to **Releases → Draft a new release** on GitHub
+   - Set the tag to `v<version>` (must match `package.json`)
+   - Click **Publish release**
+3. The [`publish` workflow](.github/workflows/publish.yml) runs `npm test` then `npm publish` automatically.
+
+**Required secret:** Add `NPM_TOKEN` to the repository's **Settings → Secrets and variables → Actions**. The token must have the `publish` permission scoped to the `@adobe` org (or be a classic Automation token).
+
+## License
+
+See [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@adobe/llm-apps-runtime",
+  "version": "0.2.0",
+  "description": "Server runtime for Adobe LLM Apps — a platform for building AI tools and interactive widgets on Adobe I/O Runtime",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./local": "./src/local.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@adobe/aio-sdk": "^5.0.0",
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "adobe-io",
+    "mcp",
+    "model-context-protocol",
+    "serverless",
+    "i/o-runtime"
+  ],
+  "license": "SEE LICENSE IN LICENSE"
+}

package/src/analytics.js

@@ -0,0 +1,264 @@
+/*
+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.
+*/
+
+/**
+ * Per-invocation analytics buffering + signed batch flush.
+ *
+ * OpenWhisk freezes containers after `main()` returns, so we cannot fire-and-forget
+ * HTTP from one invocation and have it complete in the next. The wrapper buffers
+ * events in a per-invocation array, then performs a single awaited POST at
+ * end-of-request. One MCP request that triggers N tool calls = one HTTP round-trip
+ * with N events.
+ *
+ * Hard invariant: tool inputs and outputs are NEVER serialized into events.
+ * Only byte sizes are recorded via `safeSize()`.
+ *
+ * Cost model: this code runs inside the customer's Adobe I/O Runtime namespace
+ * and consumes the customer's App Builder Pack entitlement (6M GB-s/year). The
+ * 500 ms hard timeout caps the customer's billable activation extension at
+ * ~600 ms (rounded up to the nearest 100 ms by OpenWhisk billing). The circuit
+ * breaker exists primarily to protect the customer's GB-s budget when ingest
+ * is slow or unhealthy — load-shedding for the customer's wallet, not just for
+ * our service.
+ */
+
+const crypto = require('crypto')
+
+const DEFAULT_FLUSH_TIMEOUT_MS = 500
+const MAX_EVENTS_PER_BATCH = 100
+const MAX_BODY_BYTES = 256 * 1024
+
+const CB_FAILURE_THRESHOLD = 3
+const CB_COOLDOWN_MS = 30_000
+
+// Module-level circuit breaker. Lives across requests in the same warm
+// container, which is exactly what we want for shedding load when ingest
+// is unhealthy or slow — every minute we keep the breaker open is a minute
+// of customer GB-s we don't burn on doomed POSTs.
+const breaker = {
+    consecutiveFailures: 0,
+    openUntil: 0
+}
+
+function isCircuitOpen () {
+    return Date.now() < breaker.openUntil
+}
+
+function recordSuccess () {
+    breaker.consecutiveFailures = 0
+    breaker.openUntil = 0
+}
+
+function recordFailure () {
+    breaker.consecutiveFailures += 1
+    if (breaker.consecutiveFailures >= CB_FAILURE_THRESHOLD) {
+        breaker.openUntil = Date.now() + CB_COOLDOWN_MS
+    }
+}
+
+function _resetBreakerForTest () {
+    breaker.consecutiveFailures = 0
+    breaker.openUntil = 0
+}
+
+/**
+ * Bounded JSON-size estimator. Computes serialized byte length only; never
+ * inspects content for analytics emission. Returns 0 on any serialization
+ * error so a misbehaving payload cannot crash the wrapper.
+ */
+function safeSize (value) {
+    if (value === null || value === undefined) return 0
+    try {
+        return Buffer.byteLength(JSON.stringify(value), 'utf8')
+    } catch (e) {
+        return 0
+    }
+}
+
+/**
+ * Read analytics config from OpenWhisk action params. Returns null when
+ * any required field is missing; the wrapper short-circuits to a no-op
+ * so unconfigured deploys cost zero network calls.
+ */
+function readAnalyticsConfig (params) {
+    if (!params || typeof params !== 'object') return null
+
+    const url = params.LLMA_ANALYTICS_URL
+    const appId = params.LLMA_ANALYTICS_APP_ID
+    const orgId = params.LLMA_ANALYTICS_ORG_ID
+    const version = params.LLMA_ANALYTICS_VERSION
+    const epoch = params.LLMA_ANALYTICS_EPOCH
+    const keyHex = params.LLMA_ANALYTICS_KEY
+
+    if (!url || !appId || !orgId || !version || epoch === undefined || epoch === null || !keyHex) {
+        return null
+    }
+
+    return {
+        url: String(url),
+        appId: String(appId),
+        orgId: String(orgId),
+        version: String(version),
+        epoch: String(epoch),
+        keyHex: String(keyHex),
+        runtimeNamespace: String(params.__OW_NAMESPACE || params.__ow_namespace || '')
+    }
+}
+
+/**
+ * Build the Authorization header for a signed envelope.
+ *
+ * MAC input is `version || \n || ts || \n || raw_body_bytes`. Server-side
+ * verification recomputes this exact string against the on-the-wire body bytes.
+ */
+function signEnvelope ({ rawBody, ts, appId, version, epoch, kAppHex }) {
+    const macInput = `${version}\n${ts}\n${rawBody}`
+    const key = Buffer.from(kAppHex, 'hex')
+    const mac = crypto.createHmac('sha256', key).update(macInput, 'utf8').digest('base64')
+    return `LLMA-HMAC-SHA256 v=${version}, app=${appId}, epoch=${epoch}, ts=${ts}, mac=${mac}`
+}
+
+/**
+ * Per-invocation buffer with size enforcement. Returns an object with
+ * `push(event)` and `flush(cfg, opts)`.
+ *
+ * Limits are enforced on push: the 101st event and any event that would
+ * push the serialized envelope past 256 KB are dropped (counted via
+ * `droppedCount`). Dropping is the right failure mode here because the
+ * server caps each ingest request at the same numbers — sending more
+ * would just produce a 400 for the whole batch.
+ */
+function createBuffer ({ logger } = {}) {
+    const events = []
+    let totalBytes = 0
+    let dropped = 0
+
+    function push (event) {
+        if (events.length >= MAX_EVENTS_PER_BATCH) {
+            dropped += 1
+            return false
+        }
+        let size
+        try {
+            size = Buffer.byteLength(JSON.stringify(event), 'utf8')
+        } catch (e) {
+            // Unserializable event (circular reference, BigInt, etc.) — drop
+            // it now rather than letting JSON.stringify(envelope) crash flush.
+            dropped += 1
+            return false
+        }
+        if (totalBytes + size > MAX_BODY_BYTES) {
+            dropped += 1
+            return false
+        }
+        events.push(event)
+        totalBytes += size
+        return true
+    }
+
+    async function flush (cfg, opts = {}) {
+        if (events.length === 0) {
+            return { ok: true, sent: 0, skipped: 'empty', dropped }
+        }
+        if (!cfg) {
+            return { ok: true, sent: 0, skipped: 'no-config', dropped }
+        }
+        if (isCircuitOpen()) {
+            logger?.warn?.('analytics circuit open; skipping flush')
+            return { ok: false, sent: 0, skipped: 'circuit-open', dropped }
+        }
+
+        const envelope = {
+            schema_version: 1,
+            app_id: cfg.appId,
+            org_id: cfg.orgId,
+            runtime_namespace: cfg.runtimeNamespace || '',
+            events: events.slice()
+        }
+
+        const ts = Math.floor(Date.now() / 1000)
+        let rawBody
+        try {
+            rawBody = JSON.stringify(envelope)
+        } catch (err) {
+            recordFailure()
+            logger?.warn?.(`analytics flush serialization failed: ${err.message}`)
+            return { ok: false, sent: 0, error: 'serialization-error', dropped }
+        }
+        const authorization = signEnvelope({
+            rawBody,
+            ts,
+            appId: cfg.appId,
+            version: cfg.version,
+            epoch: cfg.epoch,
+            kAppHex: cfg.keyHex
+        })
+
+        const fetchImpl = opts.fetchImpl || (typeof globalThis.fetch === 'function' ? globalThis.fetch : null)
+        if (!fetchImpl) {
+            recordFailure()
+            return { ok: false, sent: 0, error: 'no-fetch-impl', dropped }
+        }
+
+        const timeoutMs = opts.timeoutMs || DEFAULT_FLUSH_TIMEOUT_MS
+
+        try {
+            const res = await fetchImpl(cfg.url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization
+                },
+                body: rawBody,
+                signal: AbortSignal.timeout(timeoutMs)
+            })
+
+            if (res && res.ok) {
+                recordSuccess()
+                return { ok: true, sent: envelope.events.length, dropped }
+            }
+
+            recordFailure()
+            return {
+                ok: false,
+                sent: 0,
+                status: res ? res.status : 0,
+                dropped
+            }
+        } catch (err) {
+            recordFailure()
+            logger?.warn?.(`analytics flush failed: ${err.message}`)
+            return { ok: false, sent: 0, error: err.message, dropped }
+        }
+    }
+
+    return {
+        push,
+        flush,
+        get size () { return events.length },
+        get droppedCount () { return dropped },
+        get totalBytes () { return totalBytes }
+    }
+}
+
+module.exports = {
+    createBuffer,
+    readAnalyticsConfig,
+    safeSize,
+    signEnvelope,
+    MAX_EVENTS_PER_BATCH,
+    MAX_BODY_BYTES,
+    DEFAULT_FLUSH_TIMEOUT_MS,
+    CB_FAILURE_THRESHOLD,
+    CB_COOLDOWN_MS,
+    _resetBreakerForTest
+}