@luckydraw/cumulus 0.31.66 → 1.0.1

package/examples/web-app-agent/README.md

@@ -0,0 +1,334 @@
+# Web-App Agent — runnable starter kit
+
+A working web app with a persistent cumulus agent that can **see the screen** and
+**drive the app**. Every file here runs. Copy the `agent/` directories into your
+own app, replace one file, and you have the same thing.
+
+The full narrative version is [`docs/web-app-agent-guide.md`](../../docs/web-app-agent-guide.md).
+This is the code that guide describes.
+
+---
+
+## What you get
+
+|                                         |                                                                                              |
+| --------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **A persistent thread per visitor**     | The conversation outlives the tab, the session, and the deploy. Reload and it's still there. |
+| **The agent sees the live screen**      | A fresh `describeView` rides along with every turn — never a cached snapshot.                |
+| **The agent drives the app**            | Through a registry you define, calling your app's own actions — not the DOM.                 |
+| **A human gate on irreversible things** | `risk: "export"` commands stop for a confirm chip. The model cannot bypass it.               |
+| **Capability-scoped access**            | The app's key touches only its own namespace, and lists nothing at all — even its own.       |
+
+## Run it
+
+**If you installed cumulus from npm** (the usual case — the kit ships inside the
+package, already built):
+
+```bash
+cd "$(npm root -g)/@luckydraw/cumulus/examples/web-app-agent"
+GATEWAY_API_KEY=sk-demoapp-REPLACE-ME GATEWAY_ORIGIN=http://127.0.0.1:8080 node server.js
+# -> http://127.0.0.1:8199   password: demo   (override with APP_PASSWORD)
+```
+
+**If you have the cumulus git repo**, build it once first — the browser bridge
+client is served straight out of `dist/`, since this kit vendors no copy of it:
+
+```bash
+npm install && npm run build
+cd examples/web-app-agent
+GATEWAY_API_KEY=sk-demoapp-REPLACE-ME GATEWAY_ORIGIN=http://127.0.0.1:8080 node server.js
+```
+
+Copy the whole directory somewhere writable before you start editing it — a kit
+inside `node_modules` is replaced on the next upgrade.
+
+`8080` is the default port of a _fresh_ install, not a guarantee about your
+machine. Check the real one before you copy anything verbatim:
+
+```bash
+jq .port ~/.cumulus/gateway.config.json     # or: cumulus-gateway config get port
+```
+
+Use that value in `GATEWAY_ORIGIN` here and in the shim's env. If some other
+service owns 8080, a verbatim copy talks to it and fails obscurely.
+
+Without `GATEWAY_API_KEY` the app still runs — it just has no assistant. That is
+the correct degraded state, and it's worth keeping in your own app.
+
+`GATEWAY_ORIGIN` has no default and is required whenever the key is set. That's
+deliberate: a defaulting app plus a mistyped variable is an app that quietly
+talks to whatever gateway happens to be listening on the usual port — a failure
+that looks like success. The server also refuses to start on near-miss names
+(`AGENT_API_KEY`, `GATEWAY_URL`, `DEMO_PASSWORD`, …), naming the variable it
+actually reads.
+
+For the assistant to actually answer you also need a gateway: merge
+[`gateway.config.example.json`](gateway.config.example.json) into
+`~/.cumulus/gateway.config.json`, then reload it
+(`sudo systemctl reload cumulus-gateway`, or `cumulus-gateway reload` if you
+manage it yourself — never `systemctl restart`, which kills in-flight turns).
+
+## What's here
+
+```
+server.js                     your serving layer's one job: hand the scoped key
+                              to authenticated sessions only
+agent/mcp-shim.js             stdio MCP server the gateway spawns per turn;
+                              turns your registry into the model's tools
+gateway.config.example.json   the namespace, the scoped key, the shim
+
+public/index.html             the demo app
+public/app.js                 the demo app + window.HostApp (the adapter)
+
+public/agent/commands.js      ← THE FILE YOU WRITE. Your capability surface.
+public/agent/device-thread.js per-visitor thread identity
+public/agent/bridge-mount.js  wires the bridge client to your registry
+public/agent/chat-client.js   speaks the gateway's chat API (SSE)
+public/agent/blex-mount.js    rich blocks (tables, charts, diagrams) — optional
+public/agent/panel.js         the chat UI
+public/agent/panel.css        themed from six CSS variables
+```
+
+Copy all of `public/agent/` and `agent/mcp-shim.js` as-is. Then **rewrite
+`commands.js`** against your own app and delete the demo's notes commands.
+That's the whole port.
+
+Three browser files are deliberately **not** in this tree — the `BridgeClient`,
+the blex renderer and the blex library. `server.js` resolves all of them out of
+the installed `@luckydraw/cumulus` package and serves them from **your own
+origin** (`/agent/bridge-client/…`, `/agent/blex/…`), so they can't drift from
+the gateway and can't depend on how your edge is routed. Don't fork them, and
+don't load them cross-origin from `GATEWAY_ORIGIN` — that only works if your app
+is on a different hostname than the gateway; if it isn't (the common shape: your
+hostname, with the edge routing only `/bridge*` and `/api/thread/*` through), the
+cross-origin URL 404s and blex degrades to plain text with no obvious cause.
+
+### Rich blocks
+
+The gateway instructs every thread to emit `~~~blex` fences for tables, status
+boards, metrics, charts and diagrams — it's a global rule and a thread can't opt
+out. So a panel with no renderer shows the visitor **raw JSON**. That isn't a
+gateway bug; it's a missing half, and it's what `blex-mount.js` supplies.
+
+It loads two scripts from your own origin (`/agent/blex/…`, served out of the
+installed cumulus package — see above) at mount time, and degrades to plain
+markdown if either is unavailable. Nothing else in the kit depends on it.
+
+The panel is **render-only**: `confirm`, `poll`, `form` and `diff` are not
+rendered, because their buttons have no local half here and a dead "Apply"
+button reads as live in a way raw JSON does not. Denied fences stay visible as
+their original text. Nothing is lost — confirms arrive over the _bridge_ as a
+native audited chip, never through message content.
+
+If your app has a build step that mirrors static assets into an output
+directory, note that adopting this kit adds a whole **directory** (`agent/`) to
+that output. A rollback that merge-copies a snapshot over the output tree
+(`cp -r snapshot/. dist/`) cannot remove a directory the bad build added — the
+agent assets survive the rollback and keep being served while the rest of the
+app has no reference to them. A verification pass that checks referenced assets
+(a version hash, a manifest) reports success — the orphan is unreferenced, so
+nothing looks at it. Roll back by replacing the output directory, and verify
+with `diff -rq` against the snapshot.
+
+### Asset delivery (why every URL carries `?v=`)
+
+`server.js` stamps each asset URL with a hash of its bytes and serves it
+`no-cache, must-revalidate` — unless the request's `?v=` matches the current
+hash, in which case it gets `immutable`. Copy this into your own server.
+
+The reason is measured, not theoretical: a Cloudflare edge **overrides** an
+origin's `no-cache` with `max-age=14400`. Without a stamp, an edit to
+`commands.js` — the file you'll change most — can take four hours to reach a
+browser, and each file expires on its own clock, so a visitor can end up holding
+`panel.js` from one deploy and `commands.js` from another. A content-addressed
+URL is the only part of this a cache policy can't override.
+
+Two details worth keeping when you port it:
+
+- **The hash is computed at serve time**, cached on mtime+size. So a deploy
+  lands with no restart, and the hash always describes the bytes actually on
+  disk — a build-time hash goes stale against anything edited afterwards, and
+  the blex/bridge assets come out of the installed cumulus package, which
+  changes on `npm i`, not on your build.
+- **A stale or forged `?v=` must not get `immutable`.** Otherwise a wrong token
+  pins today's bytes under a key that no longer describes them.
+
+An HTML-level stamp can only reach URLs that appear in the markup. Three assets
+here are loaded from _inside_ JavaScript — `panel.css` (a `<link>` built by
+`bridge-mount`) and the two blex scripts (appended by `blex-mount`) — so
+`index.html` also publishes a `window.__AGENT_ASSET_V` map that the server fills
+in, and those loaders call `window.agentAsset(url)` to look themselves up.
+General rule: **a loader that fetches its own dependencies has to propagate the
+version token**, because nothing upstream can see that URL.
+
+Known limit: `bridge-mount.js` reaches `client.js` through a static ESM
+`import`, and `client.js` imports `protocol.js` in turn, so those two are
+fetched unstamped. Both ship from the cumulus package and change only on
+upgrade, and the server marks them `no-cache`, so the browser is correct — an
+edge that overrides it is the exposure. Simplest answer: exclude `/agent/` from
+your CDN.
+
+And one trap that makes a _correct_ deploy look broken: **404s get cached too.**
+If you probe a route before it exists, the edge caches the 404 for its default
+TTL (measured: `max-age=14400`, `cf-cache-status: HIT`), so after you ship the
+route it keeps serving "not found" for four hours — which reads as "my route is
+wrong" and sends you off to re-debug working code. Purge before concluding
+anything.
+
+---
+
+## The five things that are easy to get wrong
+
+### 1. The thread name is the capability
+
+A scoped key cannot list threads — anywhere, including its own namespace. So
+knowing a thread's name is what grants access to that conversation. Which means:
+
+- Mint the per-visitor suffix **in the browser** (`device-thread.js`), so the
+  full name never travels server → client where it could be logged or cached.
+- Use **at least 16 hex characters** (64 bits). 8 is brute-forceable against a
+  live gateway.
+- Mint them with a **CSPRNG** — `crypto.getRandomValues(new Uint8Array(8))`, as
+  `device-thread.js` does. The length is not the guarantee; the primitive is.
+  `Math.random().toString(16)` yields an id that reads correct at 16 characters
+  and is seeded from predictable state, so it fails the only test that matters.
+
+`device-thread.js` re-mints whenever the stored id fails `/^[0-9a-f]{16,}$/`, so
+an app that previously shipped short ids upgrades every visitor to 64 bits on
+first load — no migration code. Know the cost before you rely on it: a new id is
+a **new thread**, so the prior conversation becomes unreachable from that browser
+(it stays on disk, addressable only by its old name). Widening entropy is
+therefore a one-way cut-over for existing visitors, not a transparent fix.
+
+### 2. Never ship the key in the page
+
+`server.js` serves the scoped key from `GET /api/agent-config`, gated on a
+session. If you inject it into static HTML instead, anyone who views source can
+talk to your gateway as your app.
+
+This is not hypothetical — it has shipped. An app inlined its key into a
+`<script>` block in `index.html`; the key was live on the public origin and
+authenticated successfully against the gateway. What let it survive review was a
+comment elsewhere in the tree describing a _different_ file as the sensitive one
+("dev only, excluded from builds"). The documented mitigation was aimed at a
+file that wasn't the leak. If your repo has a note about where the key lives,
+verify it against what the origin actually serves:
+
+```sh
+curl -s https://your-app.example.com/ | grep -i 'api_key\|sk-'
+```
+
+The blast radius is bounded by §1 and by the gateway's namespace enforcement: a
+scoped key cannot enumerate threads, cannot read outside its namespace, and
+cannot reach gateway settings. So an exposed key is worth exactly the thread
+names an attacker can guess — which is why §1's 64 bits is load-bearing rather
+than belt-and-braces. Exposing the key turns your device-id entropy into the
+_only_ remaining barrier.
+
+**How enumeration fails matters if your client branches on status.** The list
+endpoints do not refuse a scoped key — they answer `200` with an empty list:
+
+```
+GET /api/threads   →  200  {"threads":[]}
+GET /api/agents    →  200  {"agents":[]}
+```
+
+Empty is not "your namespace happens to be empty." It is empty even when the
+namespace holds hundreds of live threads, because a scoped caller already knows
+the one name it needs and listing siblings would hand out every other visitor's
+capability. Reads outside the namespace are the ones that `403`. Don't write a
+client that reads `200` as "I'm allowed to enumerate, there just isn't anything
+here" — it will never see a thread, and no error will tell it why.
+
+### 3. Commands act through an adapter, not the DOM
+
+`window.HostApp` is the app's own actions exposed as functions. Commands call
+those. That's why validation, persistence, and re-render work identically
+whether a human or the model is driving — and why your commands survive a UI
+rewrite.
+
+### 4. Descriptions are the interface
+
+The model decides what to call based entirely on the `description` string.
+Write for a reader who cannot see your UI, and say what a command is _for_, not
+just what it does. Compare:
+
+```js
+description: 'Sets the filter.'; // useless
+description: 'Set the on-screen filter so the human sees a subset. ' +
+  'Use it to SHOW someone something, not to look something up ' +
+  'yourself — for that, use notes.list, which changes nothing.';
+```
+
+The second one prevents a whole class of annoying behaviour.
+
+### 5. Pick the risk tier honestly
+
+| tier      | meaning                                         | gated?                 |
+| --------- | ----------------------------------------------- | ---------------------- |
+| `read`    | answers a question, changes nothing             | no — runs immediately  |
+| `display` | changes the view only, trivially undoable       | no — runs immediately  |
+| `mutate`  | changes stored data, but recoverably            | no — runs immediately  |
+| `export`  | must not happen without a human seeing it first | **yes — confirm chip** |
+
+**The gate is binary and `export` is the only tier on the gated side.** The
+gateway confirm-gates a call when its manifest entry says `risk: "export"`, full
+stop — `read`, `display` and `mutate` all dispatch on arrival. Those three tiers
+are advisory: the tier rides in the tool description the model sees
+(`[mutate] …`) so it can weigh the call, but nothing stops it.
+
+So the question when tiering is **not** "is this irreversible?" — it is _"must a
+human see this before it happens?"_ If yes, it is `export`, whatever the verb
+is. An app that wants every write confirmed puts every write at `export`; the
+alternative is a command that reads as guarded and isn't, and the failure is
+silent — it just runs.
+
+Worth an explicit test: enumerate the registered manifest and fail on anything
+outside an allowlist of genuinely read-only commands that is not `export`. A
+command quietly retiered down becomes an ungated write while a suite that only
+checks the chip's behaviour stays green.
+
+---
+
+## How a turn actually works
+
+```
+visitor types  →  panel.js sends the message to the gateway
+                  AND pushes a fresh describeView over the bridge
+                          ↓
+gateway assembles the turn (history + RAG + your describeView)
+                          ↓
+model calls a tool  →  mcp-shim.js  →  POST /bridge/call
+                          ↓
+gateway → open WebSocket → the visitor's tab → your registry → HostApp
+                          ↓
+result travels back the same way; model composes an answer; SSE streams it
+```
+
+Two consequences worth internalising:
+
+- **The tab must be open** for tool calls to work. With no tab, the gateway
+  answers `{ ok: false }` and the model reports an honest failure instead of
+  hanging.
+- **The tool list is live.** Every `tools/list` re-fetches your manifest, so
+  capabilities appear and disappear as your app changes — no gateway restart,
+  no redeploy.
+
+## Demo mode
+
+An unlicensed gateway caps each namespace at **5 distinct visitor threads**.
+Existing threads keep working; only minting a _new_ one is refused, with `402`
+and a contact address. `chat-client.js` surfaces that as a readable message
+rather than a generic failure.
+
+That's plenty to evaluate with and hits immediately in production, which is the
+point. See [`LICENSE`](../../LICENSE).
+
+## Optional extras
+
+Not in this kit, but in the guide:
+
+- **Selection as context** — let a visitor highlight part of the page and ask
+  about it (guide §4.6).
+- **Executor proxy** — reverse-proxy your app's own API through the gateway so
+  the tab talks to a single origin (`executorProxy` in the example config).

package/examples/web-app-agent/agent/mcp-shim.js

@@ -0,0 +1,105 @@
+// Stdio MCP server that the cumulus gateway spawns once per turn, giving the
+// model tools that execute inside the visitor's live browser tab.
+//
+// Register it on your namespace in gateway.config.json (see
+// gateway.config.example.json). The gateway substitutes {thread} for the
+// actual thread name, which is how one shim serves every visitor.
+//
+// Stateless by design: every tools/list re-fetches the tab's live manifest, so
+// tools appear and disappear as the app's capabilities change — no restart, no
+// redeploy. Every tools/call is forwarded to POST /bridge/call, which
+// dispatches into the tab. With no tab connected the gateway answers
+// { ok: false } and the model sees an honest failure rather than a hang.
+//
+// MCP tool names cannot contain dots, so registry command names are exposed
+// with underscores (notes.create -> notes_create) and mapped back on call.
+//
+// Env (set by the gateway from your namespace config):
+//   GATEWAY_ORIGIN   default http://127.0.0.1:8080 (this shim runs ON the
+//                    gateway host, so the local gateway is the right guess —
+//                    unlike server.js, where there is no safe default)
+//   GATEWAY_API_KEY  a key scoped to this namespace
+//   BRIDGE_THREAD    the thread being served — pass "{thread}" in the config
+
+import readline from 'node:readline';
+
+const GATEWAY_ORIGIN = process.env.GATEWAY_ORIGIN ?? 'http://127.0.0.1:8080';
+const GATEWAY_API_KEY = process.env.GATEWAY_API_KEY ?? '';
+const BRIDGE_THREAD = process.env.BRIDGE_THREAD ?? 'demoapp';
+const SERVER_NAME = process.env.MCP_SERVER_NAME ?? 'demoapp-tools';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const toMcpName = command => command.replaceAll('.', '_');
+let nameToCommand = new Map();
+
+async function fetchManifest() {
+  const res = await fetch(
+    `${GATEWAY_ORIGIN}/bridge/manifest/${encodeURIComponent(BRIDGE_THREAD)}`,
+    { headers: { 'X-API-Key': GATEWAY_API_KEY } }
+  );
+  const manifest = res.ok ? ((await res.json()).manifest ?? []) : [];
+  nameToCommand = new Map(manifest.map(c => [toMcpName(c.name), c.name]));
+  return manifest.map(c => ({
+    name: toMcpName(c.name),
+    // The risk tier rides in the description so the model can see which calls
+    // are reversible and which will stop for a human.
+    description: `[${c.risk ?? 'read'}] ${c.description ?? c.name}`,
+    inputSchema: c.input_schema ?? c.inputSchema ?? { type: 'object', properties: {} },
+  }));
+}
+
+async function callCommand(mcpName, args) {
+  if (!nameToCommand.has(mcpName)) await fetchManifest().catch(() => {});
+  const command = nameToCommand.get(mcpName) ?? mcpName.replaceAll('_', '.');
+  const res = await fetch(`${GATEWAY_ORIGIN}/bridge/call`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'X-API-Key': GATEWAY_API_KEY },
+    body: JSON.stringify({ thread: BRIDGE_THREAD, command, params: args ?? {} }),
+  });
+  if (!res.ok) throw new Error(`bridge call failed: ${res.status}`);
+  return res.json();
+}
+
+const handlers = {
+  initialize: async () => ({
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: { tools: {} },
+    serverInfo: { name: SERVER_NAME, version: '1.0.0' },
+  }),
+  'tools/list': async () => ({ tools: await fetchManifest() }),
+  'tools/call': async ({ name, arguments: args }) => {
+    const result = await callCommand(name, args);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result) }],
+      isError: !result.ok,
+    };
+  },
+  ping: async () => ({}),
+};
+
+const rl = readline.createInterface({ input: process.stdin });
+rl.on('line', async line => {
+  if (!line.trim()) return;
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return;
+  }
+  if (msg.id === undefined) return; // notification (e.g. notifications/initialized)
+
+  const handler = handlers[msg.method];
+  let response;
+  try {
+    if (!handler)
+      throw Object.assign(new Error(`Method not found: ${msg.method}`), { code: -32601 });
+    response = { jsonrpc: '2.0', id: msg.id, result: await handler(msg.params ?? {}) };
+  } catch (err) {
+    response = {
+      jsonrpc: '2.0',
+      id: msg.id,
+      error: { code: err.code ?? -32000, message: err?.message ?? String(err) },
+    };
+  }
+  process.stdout.write(JSON.stringify(response) + '\n');
+});

package/examples/web-app-agent/gateway.config.example.json

@@ -0,0 +1,70 @@
+{
+  "_comment": [
+    "Merge these keys into your ~/.cumulus/gateway.config.json — this file is a fragment, not a whole config.",
+    "Then: sudo systemctl reload cumulus-gateway (SIGHUP; never restart, it kills in-flight turns).",
+    "Replace sk-demoapp-REPLACE-ME with a long random string. It is the app's only credential.",
+    "PORT: 8080 below is the DEFAULT for a fresh install, not a promise about your box.",
+    "Read your own config's top-level \"port\" and use that in GATEWAY_ORIGIN — pointing the",
+    "shim at whatever else happens to own 8080 fails in a confusing, non-obvious way."
+  ],
+
+  "_bridge": [
+    "Top-level and GLOBAL — one setting for the whole gateway, not per-app. If it is",
+    "already true (another app enabled it), leave it alone; adding a second app is a",
+    "namespaces[] entry only. Setting it true again is harmless.",
+    "",
+    "There is one more optional key here: bridge.executorUrl (default",
+    "http://127.0.0.1:8091). It is ALSO global — one URL for the whole gateway, so a",
+    "second app cannot point it somewhere else. It is used for exactly one thing:",
+    "hydrating a visitor's text selection into full records via POST <executorUrl>/execute",
+    "before the turn runs. It soft-fails if unreachable, and it is UNRELATED to the",
+    "per-namespace executorProxy below — enabling that does not require this. Omit it",
+    "unless you have a headless executor serving /execute."
+  ],
+  "bridge": { "enabled": true },
+
+  "namespaces": [
+    {
+      "name": "demoapp",
+      "label": "Demo App",
+
+      "_apiKeys": [
+        "A key listed here is SCOPED: it can touch demoapp-* threads and nothing else,",
+        "and it never sees the base 'demoapp' thread (that one belongs to you, for",
+        "working on the app). It also lists NOTHING: /api/threads and /api/agents answer",
+        "200 with an empty array even when the namespace is full — not 403. Reads outside",
+        "the namespace are what 403. This is the key your serving layer hands to",
+        "logged-in sessions."
+      ],
+      "apiKeys": ["sk-demoapp-REPLACE-ME"],
+
+      "_extraMcpServers": [
+        "Spawned per turn for demoapp-* threads only. {thread} is substituted with the",
+        "calling thread's name, so one shim serves every visitor. Use an absolute path",
+        "to the shim — the gateway spawns it with the thread's own cwd."
+      ],
+      "extraMcpServers": {
+        "demoapp-tools": {
+          "command": "node",
+          "args": ["/absolute/path/to/examples/web-app-agent/agent/mcp-shim.js"],
+          "env": {
+            "GATEWAY_ORIGIN": "http://127.0.0.1:8080",
+            "GATEWAY_API_KEY": "sk-demoapp-REPLACE-ME",
+            "BRIDGE_THREAD": "{thread}",
+            "MCP_SERVER_NAME": "demoapp-tools"
+          }
+        }
+      },
+
+      "_executorProxy": [
+        "OPTIONAL. Only if your app has a backend the agent should reach directly.",
+        "Lets the tab talk to a single origin (the gateway) instead of two.",
+        "Delete this block if you don't need it — the demo does not."
+      ],
+      "executorProxy": {
+        "origin": "http://127.0.0.1:8199",
+        "pathPrefixes": ["/api/public"]
+      }
+    }
+  ]
+}

package/examples/web-app-agent/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "cumulus-web-app-agent-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Runnable starter kit: a web app with a persistent cumulus agent that can see and drive it.",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/examples/web-app-agent/public/agent/blex-mount.js

@@ -0,0 +1,136 @@
+/* Blex mount — gives the panel rich blocks (tables, status, metrics, charts,
+   diagrams) instead of raw JSON.
+
+   WHY THIS FILE EXISTS AT ALL
+   The gateway instructs every thread to emit ~~~blex fences (it is a global
+   rule; a thread cannot opt out). Without a renderer on this side, the model
+   dutifully emits fences into a surface that has never heard of them, and the
+   user sees a wall of JSON. That is not a gateway bug — it is a missing half.
+
+   WHAT IS DELIBERATELY NOT HERE
+   No vendored copy of the renderer. Both scripts come out of the installed
+   cumulus package, served SAME-ORIGIN by this app's own /agent/blex/ route (see
+   server.js, and the load() comment below for why not cross-origin). Vendoring
+   would fork the seam contract and guarantee version drift the first time
+   either side moves.
+
+   RENDER-ONLY
+   This panel supplies only the required adapter members, so `confirm`, `poll`,
+   `form` and `diff` are not rendered — their affordances have no local half
+   here, and a dead "Apply" button reads as live in a way raw JSON does not.
+   Denied fences stay visible as their original text. See the allow-set rationale
+   in cumulus's blex-render.js.
+
+   Confirms come over the BRIDGE (a native, audited chip in panel.js), never
+   through message content — so nothing is lost by not rendering them.
+
+   window.AgentBlex = { load(cfg), ready(), adapter, extract(text), render(el, blocks) } */
+(function () {
+  'use strict';
+
+  var loading = null;
+
+  /* These two URLs exist only here, so the server's HTML stamp cannot reach
+     them — they carry their hashes via the map index.html publishes instead.
+     Falls through to the bare URL if the map is absent. */
+  function assetUrl(url) {
+    return typeof window.agentAsset === 'function' ? window.agentAsset(url) : url;
+  }
+
+  function loadScript(src) {
+    return new Promise(function (resolve, reject) {
+      var existing = document.querySelector('script[data-blex-src="' + src + '"]');
+      if (existing) return resolve();
+      var s = document.createElement('script');
+      s.src = src;
+      s.setAttribute('data-blex-src', src);
+      s.onload = function () {
+        resolve();
+      };
+      s.onerror = function () {
+        reject(new Error('failed to load ' + src));
+      };
+      document.head.appendChild(s);
+    });
+  }
+
+  /* Load both halves SAME-ORIGIN, from this app's own /agent/blex/ route, which
+     serves them straight out of the installed cumulus package (see server.js).
+     Deliberately NOT `GATEWAY_URL + '/blex.min.js'`: that only works when the app
+     is on a different origin from the gateway. In the common shape — your own
+     hostname, with an edge routing only `/bridge*` and `/api/thread/*` through —
+     the gateway origin has no such path and the load 404s into a silent
+     plain-text degrade. Same-origin is correct in both deployments, and it is
+     still not a vendored copy, so it cannot drift from the gateway.
+
+     Resolves either way: a failure here must degrade the panel, never break it. */
+  function load(cfg) {
+    if (loading) return loading;
+    if (!cfg) return Promise.resolve(false);
+    loading = loadScript(assetUrl('/agent/blex/blex.min.js'))
+      .then(function () {
+        return loadScript(assetUrl('/agent/blex/blex-render.js'));
+      })
+      .then(function () {
+        return ready();
+      })
+      .catch(function (err) {
+        // warn, not error: a build gate that fails on any console error should
+        // not go red because an optional enhancement was unavailable.
+        console.warn('[agent] blex unavailable, falling back to plain text:', err.message);
+        return false;
+      });
+    return loading;
+  }
+
+  function ready() {
+    return typeof window.CumulusBlexRender !== 'undefined' && typeof window.Blex !== 'undefined';
+  }
+
+  /* The three required members. addChip/persist are intentionally absent —
+     that absence IS render-only. */
+  function adapter() {
+    return window.CumulusBlexRender.renderOnlyAdapter({
+      getInput: function () {
+        return document.querySelector('[data-testid="agent-input"]');
+      },
+      getSendButton: function () {
+        return document.querySelector('[data-testid="agent-send"]');
+      },
+    });
+  }
+
+  function extract(text) {
+    if (!ready()) return { text: text, blocks: [] };
+    return window.CumulusBlexRender.extractBlocks(text);
+  }
+
+  function insertPlaceholders(html, blocks) {
+    if (!ready() || !blocks || !blocks.length) return html;
+    return window.CumulusBlexRender.insertPlaceholders(html, blocks, {});
+  }
+
+  function render(el, blocks) {
+    if (!ready() || !blocks || !blocks.length) return;
+    try {
+      window.CumulusBlexRender.render(el, blocks, adapter(), {});
+    } catch (err) {
+      console.warn('[agent] blex render failed:', err.message);
+    }
+  }
+
+  function destroy(el) {
+    if (!ready()) return;
+    window.CumulusBlexRender.destroy(el);
+  }
+
+  window.AgentBlex = {
+    load: load,
+    ready: ready,
+    adapter: adapter,
+    extract: extract,
+    insertPlaceholders: insertPlaceholders,
+    render: render,
+    destroy: destroy,
+  };
+})();