@luckydraw/cumulus 1.0.0 → 1.0.2

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

@@ -17,7 +17,7 @@ This is the code that guide describes.
 | **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 can touch its own namespace and cannot enumerate anything, anywhere.           |
+| **Capability-scoped access**            | The app's key touches only its own namespace, and lists nothing at all — even its own.       |
 
 ## Run it
 
@@ -42,6 +42,16 @@ GATEWAY_API_KEY=sk-demoapp-REPLACE-ME GATEWAY_ORIGIN=http://127.0.0.1:8080 node
 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.
 
@@ -66,6 +76,9 @@ server.js                     your serving layer's one job: hand the scoped key
 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
+thread-config.example.json    YOUR management thread's config
+thread-config.visitor.example.json  EVERY visitor's config — the cheap model
+agent/apply-thread-configs.mjs      one command to push both to the gateway
 
 public/index.html             the demo app
 public/app.js                 the demo app + window.HostApp (the adapter)
@@ -74,6 +87,7 @@ 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
 ```
@@ -82,13 +96,108 @@ 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.
 
-The browser `BridgeClient` is deliberately **not** in this tree. It's served
-from `dist/gateway/bridge/` in the cumulus package, so it can never drift from
-the gateway it talks to. Don't fork it.
+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.
+
+**Diagrams need one extra tag.** `~~~blex:mermaid` is the only block type whose
+renderer loads a library at render time, using a **bare** module specifier — and
+an import map is the one thing a browser can resolve that with. `index.html`
+carries it; keep it when you copy:
+
+```html
+<script type="importmap">
+  { "imports": { "mermaid": "/agent/blex/mermaid-esm.js" } }
+</script>
+```
+
+The vendored mermaid bundle is served by the same `/agent/blex/*` route, and only
+fetched when a diagram actually renders. Drop the tag and nothing breaks — the
+renderer checks the document for the mapping and leaves mermaid fences as
+readable text rather than painting an error box. Diagram colours follow the blex
+card's own background, so they match whatever you theme blex to.
+
+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
+## The six things that are easy to get wrong
 
 ### 1. The thread name is the capability
 
@@ -99,6 +208,17 @@ knowing a thread's name is what grants access to that conversation. Which means:
   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
 
@@ -106,14 +226,87 @@ knowing a thread's name is what grants access to that conversation. Which means:
 session. If you inject it into static HTML instead, anyone who views source can
 talk to your gateway as your app.
 
-### 3. Commands act through an adapter, not the DOM
+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. Visitor threads need their OWN model config
+
+Your app has two kinds of thread and they should not run the same model:
+
+| File                    | Applies to                             |
+| ----------------------- | -------------------------------------- |
+| `demoapp.config.json`   | your management thread — strong model  |
+| `demoapp-v.config.json` | **every visitor** — small, fast, cheap |
+
+The `-v` is what makes that possible. `server.js` sends `THREAD_ID: 'demoapp-v'`
+and `device-thread.js` appends the device id, so a visitor lands on
+`demoapp-v-<deviceId>`. Config resolves by stripping trailing segments and taking
+the longest match:
+
+```
+demoapp-v-a3f8c2d1.config.json   (none — visitors never get their own)
+demoapp-v.config.json            <- every visitor turn
+demoapp.config.json              (only if the -v file is absent)
+```
+
+**Omit the `-v` file and every anonymous visitor runs your management thread's
+model.** It is invisible in development — with one tester the bill looks fine —
+and it is the most expensive mistake in this kit.
+
+Edit the two `thread-config*.example.json` files and push them:
+
+```bash
+GATEWAY_ORIGIN=http://127.0.0.1:8080 GATEWAY_ADMIN_KEY=sk-... \
+  node agent/apply-thread-configs.mjs --namespace demoapp
+```
+
+The **admin** key, not the app's: a namespace covers `demoapp-*`, so the scoped
+key can write `demoapp-v` but is refused on the bare `demoapp`. The config API
+takes `projectDir`, `template`, `model`, `effort`, `claudeModel` and
+`contextLimit`; `alwaysInclude` and `disallowedTools` have to be added to the file
+on the gateway host (that is deliberate — `alwaysInclude` plus `projectDir` would
+let a public scoped key read any file into its own prompt). The applier reads each
+config back and tells you exactly what didn't stick. No reload needed.
+
+### 4. 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
+### 5. 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
@@ -128,18 +321,31 @@ description: 'Set the on-screen filter so the human sees a subset. ' +
 
 The second one prevents a whole class of annoying behaviour.
 
-### 5. Pick the risk tier honestly
-
-| tier      | meaning                                                              |
-| --------- | -------------------------------------------------------------------- |
-| `read`    | answers a question, changes nothing                                  |
-| `display` | changes the view only, trivially undoable                            |
-| `mutate`  | changes stored data, but recoverably                                 |
-| `export`  | irreversible, or leaves the app (sends, publishes, deletes, charges) |
-
-`export` is **always** routed through the confirm chip by the gateway — the
-model can't bypass it and neither can your front end. Anything that spends
-money, emails a customer, or destroys data belongs here.
+### 6. 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.
 
 ---
 

package/examples/web-app-agent/agent/apply-thread-configs.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/* Apply this app's two thread configs to the gateway — the base thread you work
+   in, and the '-v' sub-namespace every visitor turn inherits.
+ *
+ * WHY A SCRIPT
+ * The visitor config is the one piece of per-app setup with no UI and no obvious
+ * home: it lives in a file on the gateway host, its name encodes a namespace rule
+ * (see thread-config.visitor.example.json), and getting it wrong silently costs
+ * money — every anonymous visitor runs whatever model your management thread uses.
+ * One command, run once per app, beats a paragraph telling you to hand-write JSON
+ * in a directory you may not have shell access to.
+ *
+ *   GATEWAY_ORIGIN=http://127.0.0.1:8080 \
+ *   GATEWAY_ADMIN_KEY=sk-... \
+ *   node agent/apply-thread-configs.mjs [--namespace demoapp] [--dry-run]
+ *
+ * GATEWAY_ADMIN_KEY, not the app's scoped key: a namespace covers '<ns>-*' only,
+ * so a scoped key can write '<ns>-v' but is refused (403) on the bare '<ns>' base
+ * thread. That asymmetry is the P7 access model working, not a bug — this is an
+ * operator action.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const ORIGIN = process.env.GATEWAY_ORIGIN;
+const KEY = process.env.GATEWAY_ADMIN_KEY;
+
+/* Near-miss names fail loudly rather than falling back to a default that might be
+   somebody's real gateway — the same rule server.js applies. */
+const ALIASES = {
+  GATEWAY_URL: 'GATEWAY_ORIGIN',
+  AGENT_GATEWAY_ORIGIN: 'GATEWAY_ORIGIN',
+  GATEWAY_KEY: 'GATEWAY_ADMIN_KEY',
+  ADMIN_KEY: 'GATEWAY_ADMIN_KEY',
+  GATEWAY_API_KEY: 'GATEWAY_ADMIN_KEY (the scoped app key cannot write the base thread)',
+};
+
+function die(msg) {
+  console.error(`\n  ${msg}\n`);
+  process.exit(1);
+}
+
+for (const [wrong, right] of Object.entries(ALIASES)) {
+  if (process.env[wrong] && !(wrong === 'GATEWAY_API_KEY' && KEY)) {
+    die(`${wrong} is set but this script reads ${right}.`);
+  }
+}
+if (!ORIGIN) die('GATEWAY_ORIGIN is required (no default — it must not guess a live gateway).');
+if (!KEY) die('GATEWAY_ADMIN_KEY is required.');
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const nsFlag = args.indexOf('--namespace');
+const namespace = nsFlag !== -1 ? args[nsFlag + 1] : 'demoapp';
+if (!/^[a-z0-9][a-z0-9-]*$/i.test(namespace)) die(`invalid --namespace: ${namespace}`);
+
+/** Read an example config and drop the `_`-prefixed annotation keys. */
+function load(file) {
+  const full = path.join(ROOT, file);
+  if (!fs.existsSync(full)) die(`missing ${file}`);
+  const parsed = JSON.parse(fs.readFileSync(full, 'utf-8'));
+  return Object.fromEntries(Object.entries(parsed).filter(([k]) => !k.startsWith('_')));
+}
+
+const targets = [
+  { thread: namespace, file: 'thread-config.example.json' },
+  { thread: `${namespace}-v`, file: 'thread-config.visitor.example.json' },
+];
+
+let failed = false;
+for (const { thread, file } of targets) {
+  const config = load(file);
+  if (String(config.projectDir || '').startsWith('/absolute/path/')) {
+    die(`${file} still has the placeholder projectDir — edit it before applying.`);
+  }
+  const label = `${thread.padEnd(24)} <- ${file}`;
+  if (dryRun) {
+    console.log(`DRY RUN  ${label}\n         ${JSON.stringify(config)}`);
+    continue;
+  }
+  let res;
+  try {
+    res = await fetch(`${ORIGIN}/api/thread/${encodeURIComponent(thread)}/config`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': KEY },
+      body: JSON.stringify(config),
+    });
+  } catch (err) {
+    die(`cannot reach ${ORIGIN}: ${err.message}`);
+  }
+  if (res.ok) {
+    console.log(`OK       ${label}`);
+    /* The config API applies a whitelist (projectDir, template, model, effort,
+       claudeModel, contextLimit). alwaysInclude and disallowedTools are NOT in it,
+       deliberately: combined with projectDir, alwaysInclude would let a
+       namespace-scoped key — which ships in your public page — read an arbitrary
+       file into its own prompt. So rather than assume, read the config back and
+       name anything that did not stick. A silent drop here would look like a
+       working persona that was never installed. */
+    try {
+      const check = await fetch(`${ORIGIN}/api/thread/${encodeURIComponent(thread)}/config`, {
+        headers: { 'X-API-Key': KEY },
+      });
+      if (check.ok) {
+        const stored = (await check.json()) ?? {};
+        const missing = Object.keys(config).filter(k => stored[k] === undefined);
+        if (missing.length) {
+          console.log(`         not applied by the API: ${missing.join(', ')}`);
+          console.log(
+            `         add them by hand to ~/.cumulus/threads/${thread}.config.json on the`
+          );
+          console.log('         gateway host — this file is exactly those contents.');
+        }
+      }
+    } catch {
+      /* the write succeeded; a failed read-back is not worth failing over */
+    }
+  } else {
+    failed = true;
+    const body = await res.text();
+    console.error(`FAILED   ${label}\n         ${res.status} ${body.slice(0, 200)}`);
+    if (res.status === 403) {
+      console.error('         403 on the base thread means the key is namespace-scoped.');
+      console.error('         Use the gateway admin key for this one-time setup.');
+    }
+  }
+}
+
+if (failed) process.exit(1);
+if (!dryRun) {
+  console.log(
+    `\nDone. Visitor turns on ${namespace}-v-<deviceId> now read ${namespace}-v.config.json;\n` +
+      `your own ${namespace} thread is unaffected. No gateway reload needed —\n` +
+      'thread config is read per turn.'
+  );
+}

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

@@ -2,9 +2,25 @@
   "_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."
+    "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": [
@@ -14,9 +30,11 @@
 
       "_apiKeys": [
         "A key listed here is SCOPED: it can touch demoapp-* threads and nothing else,",
-        "it cannot enumerate any thread anywhere, and it never sees the base 'demoapp'",
-        "thread (that one belongs to you, for working on the app). This is the key your",
-        "serving layer hands to logged-in sessions."
+        "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"],
 

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,
+  };
+})();