@adobe/llm-apps-runtime 0.2.0 → 0.4.0

package/README.md

@@ -71,25 +71,39 @@ When `moduleContext` is provided, the webpack path is used. Otherwise the filesy
 
 **Returns** `{ main }` — an async function compatible with Adobe I/O Runtime's action signature.
 
-### `createLocalServer(main, port)`
+### `createLocalServer(main, port, extraParams)`
 
 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 { createLocalServer, parseParamArgs } = require('@adobe/llm-apps-runtime/local')
 const { main } = require('./dist/index.js') // your webpack bundle
-createLocalServer(main, process.env.PORT || 9080)
+const extraParams = parseParamArgs(process.argv) // --param KEY=VALUE flags
+createLocalServer(main, process.env.PORT || 9080, extraParams)
 ```
 
 **Parameters**
 
-| Parameter | Type     | Default | Description |
-|-----------|----------|---------|-------------|
-| `main`    | Function | —       | The `main(params)` function returned by `createMain`. |
-| `port`    | number   | `9080`  | Port to listen on. |
+| Parameter     | Type     | Default | Description |
+|---------------|----------|---------|-------------|
+| `main`        | Function | —       | The `main(params)` function returned by `createMain`. |
+| `port`        | number   | `9080`  | Port to listen on. |
+| `extraParams` | object   | `{}`    | Key-value pairs merged into every request's `params`, simulating Adobe I/O Runtime action params. |
 
 **Returns** an [`http.Server`](https://nodejs.org/api/http.html#class-httpserver) instance.
 
+#### Passing action params locally
+
+In production, Adobe I/O Runtime merges action params (set via `aio app deploy --param`) into the `params` object that `main()` receives alongside the request. Locally there is no runtime, so you pass them on the command line using the same `--param KEY=VALUE` syntax:
+
+```bash
+node server/local.js \
+  --param MY_API_URL=http://localhost:3000 \
+  --param MY_API_KEY=dev-secret
+```
+
+`parseParamArgs(process.argv)` reads these flags and passes them to `createLocalServer` as `extraParams`. Every inbound request then receives them as top-level `params` fields, so any param-reading code in your action works identically to the deployed runtime.
+
 ### Action loading primitives
 
 Exported from the package root for advanced use cases (custom loaders, integration tests):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/llm-apps-runtime",
-  "version": "0.2.0",
+  "version": "0.4.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": {
@@ -42,5 +42,9 @@
     "serverless",
     "i/o-runtime"
   ],
-  "license": "SEE LICENSE IN LICENSE"
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Adobe-AIFoundations/llm-apps-runtime.git"
+  }
 }

package/src/analytics.js

@@ -13,7 +13,7 @@ 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
+ * Adobe I/O Runtime 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
@@ -25,7 +25,7 @@ governing permissions and limitations under the License.
  * 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
+ * ~600 ms (rounded up to the nearest 100 ms by Adobe I/O Runtime 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.
@@ -85,7 +85,7 @@ function safeSize (value) {
 }
 
 /**
- * Read analytics config from OpenWhisk action params. Returns null when
+ * Read analytics config from Adobe I/O Runtime 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.
  */

package/src/index.js

@@ -207,8 +207,6 @@ function createMain (options = {}) {
 
             logger?.info('MCP request processed by SDK')
 
-            await flushAnalyticsSafe(analyticsConfig)
-
             return {
                 statusCode: response.status,
                 headers: {
@@ -225,10 +223,6 @@ function createMain (options = {}) {
 
             try { server.close() } catch (e) { /* ignore cleanup errors */ }
 
-            // Flush whatever we managed to buffer before the failure so
-            // partial telemetry isn't lost on the error path.
-            await flushAnalyticsSafe(analyticsConfig)
-
             return {
                 statusCode: 500,
                 headers: {
@@ -241,6 +235,11 @@ function createMain (options = {}) {
                     id: null
                 })
             }
+        } finally {
+            // Flush on every exit path — success, error, or unexpected throw.
+            // In JS, finally runs before the pending return resolves, so the
+            // POST completes before the Adobe I/O Runtime container freezes.
+            await flushAnalyticsSafe(analyticsConfig)
         }
     }
 

package/src/local.js

@@ -18,21 +18,47 @@ governing permissions and limitations under the License.
  *
  * Usage in consumer app server/local.js:
  *
- *   const { createLocalServer } = require('@adobe/llm-apps-runtime')
+ *   const { createLocalServer, parseParamArgs } = require('@adobe/llm-apps-runtime/local')
  *   const { main } = require('../dist/index.js')   // webpack bundle
- *   createLocalServer(main, process.env.PORT || 9080)
+ *   const extraParams = parseParamArgs(process.argv)  // --param KEY=VALUE flags
+ *   createLocalServer(main, process.env.PORT || 9080, extraParams)
  */
 
 const http = require('http')
 
+/**
+ * Parse --param KEY=VALUE pairs from an argv array, mirroring the grammar
+ * used by `aio app deploy --param`. Returns a plain object. Entries that
+ * do not contain '=' or have an empty key are silently skipped.
+ *
+ * @param {string[]} argv  process.argv (or any argv-style array)
+ * @returns {object}
+ */
+function parseParamArgs (argv) {
+    const out = {}
+    for (let i = 2; i < argv.length; i++) {
+        if (argv[i] === '--param' && argv[i + 1]) {
+            const eq = argv[i + 1].indexOf('=')
+            if (eq > 0) {
+                out[argv[i + 1].slice(0, eq)] = argv[i + 1].slice(eq + 1)
+            }
+            i++
+        }
+    }
+    return out
+}
+
 /**
  * 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)
+ * @param {Function} main         The main(params) function returned by createMain
+ * @param {number}   port         Port to listen on (default 9080)
+ * @param {object}   extraParams  Optional action params to inject into every request,
+ *                                simulating Adobe I/O Runtime action params (e.g. LLMA_ANALYTICS_*).
+ *                                Use parseParamArgs(process.argv) to populate from --param flags.
  * @returns {http.Server}
  */
-function createLocalServer (main, port) {
+function createLocalServer (main, port, extraParams = {}) {
     // Use ?? (not ||) so an explicit 0 (ephemeral port, useful for tests) is honored.
     const listenPort = port ?? 9080
 
@@ -43,6 +69,7 @@ function createLocalServer (main, port) {
             const rawBody = Buffer.concat(chunks).toString('utf8')
 
             const params = {
+                ...extraParams,             // simulate Adobe I/O Runtime action params
                 __ow_method: req.method.toLowerCase(),
                 __ow_path: req.url,
                 __ow_body: rawBody || undefined,
@@ -88,4 +115,4 @@ function createLocalServer (main, port) {
     return server
 }
 
-module.exports = { createLocalServer }
+module.exports = { createLocalServer, parseParamArgs }