npm - @luckydraw/cumulus - Versions diffs - 1.0.0 → 1.0.1 - Mend

@luckydraw/cumulus 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/CHANGELOG.md +9 -0
package/dist/gateway/adapters/webchat.d.ts +13 -0
package/dist/gateway/adapters/webchat.d.ts.map +1 -1
package/dist/gateway/adapters/webchat.js +56 -3
package/dist/gateway/adapters/webchat.js.map +1 -1
package/dist/gateway/static/blex-render.js +341 -0
package/dist/gateway/static/chat.html +1 -0
package/dist/gateway/static/widget.js +112 -127
package/docs/web-app-agent-guide.md +40 -1
package/examples/web-app-agent/README.md +161 -14
package/examples/web-app-agent/gateway.config.example.json +22 -4
package/examples/web-app-agent/public/agent/blex-mount.js +136 -0
package/examples/web-app-agent/public/agent/bridge-mount.js +19 -3
package/examples/web-app-agent/public/agent/commands.js +10 -4
package/examples/web-app-agent/public/agent/device-thread.js +5 -5
package/examples/web-app-agent/public/agent/panel.css +6 -0
package/examples/web-app-agent/public/agent/panel.js +27 -4
package/examples/web-app-agent/public/index.html +15 -0
package/examples/web-app-agent/server.js +148 -11
package/package.json +1 -1

package/docs/web-app-agent-guide.md CHANGED Viewed

@@ -92,6 +92,8 @@ Default is off; with it off every bridge surface is inert.
           "command": "node",
           "args": ["/path/to/myapp/mcp-shim.js"],
           "env": {
+            // 8080 is the fresh-install default — use your gateway's actual
+            // top-level "port" here (jq .port ~/.cumulus/gateway.config.json).
             "GATEWAY_ORIGIN": "http://127.0.0.1:8080",
             "GATEWAY_API_KEY": "sk-myapp-<same-scoped-key>",
             "BRIDGE_THREAD": "{thread}",
@@ -191,6 +193,7 @@ The front end then calls `AgentStart()` once the config arrives, and `AgentStop(
 Notes:
 - **Yes, the scoped key reaches the browser.** That is the design: it is worthless outside `myapp-*`, can enumerate nothing, and each visitor's thread name is its own secret. Ship only the namespace-scoped key — never an admin key.
+- **Enumeration fails as `200` + empty, not `403`.** `/api/threads` and `/api/agents` answer `200 {"threads":[]}` to a scoped key even when the namespace holds hundreds of threads — a scoped caller already knows the one name it needs, and listing siblings would hand out every other visitor's capability. `403` is reserved for reaching _outside_ the namespace. Worth knowing if your client branches on status.
 - **Gate it on a session anyway.** Pursuit takes the older route and injects the key into `<head>` at serve time, which puts it in public HTML, in view-source, and in any intermediary cache. It works, and the blast radius is bounded by the namespace — but a session-gated endpoint is strictly better and costs one route. Use it for new apps.
 - In production, pass the key via a systemd drop-in (`Environment=MYAPP_API_KEY=...`), not a file in the repo.
 - `THREAD_ID` is the **base name**; the browser appends the per-device suffix (§4.1). Minting the suffix client-side keeps the full thread name — the actual capability — from ever travelling server → client.
@@ -292,7 +295,7 @@ MyAppAgent.register(def)   MyAppAgent.call(name, params)
 MyAppAgent.list()          MyAppAgent.manifest()   // → [{ name, description, risk, input_schema }]
 ```
-Risk tiers gate what happens without a human in the loop: `read` and `display` run freely, `mutate` runs but is journaled, and **`export` never auto-runs** — the gateway forces a confirm round-trip (§5.3) regardless of caller flags.
+The gate is binary, and only one tier is on the gated side. **`export` never auto-runs** — the gateway forces a confirm round-trip (§5.3) regardless of caller flags. `read`, `display` and `mutate` all dispatch immediately; the tier is advisory, riding in the tool description the model sees (`[mutate] …`) so it can weigh the call, but nothing stops it. So the question when tiering a command is not "is this irreversible?" — it is **"must a human see this before it happens?"** If yes, it is `export`, whatever the verb is.
 Two commands every app should register (the agent's eyes):
@@ -418,6 +421,42 @@ Delivery is decoupled via an event — `window.dispatchEvent(new CustomEvent('my
 **The `data-agent-ref` convention** is what makes captured feedback _addressable_: any element rendering a record carries `data-agent-ref="accounts:ACME-01"` (optionally `/field:owner`). Ref collection walks ancestors and contained elements of the selection/target, so "this row is wrong" arrives at the agent with the exact records attached.
+### 4.6b Rich blocks (`blex-mount.js`, ~110 lines)
+The gateway instructs **every** thread to emit `~~~blex:TYPE` fences for tabular data, status boards, metrics, charts and diagrams. That rule is in the global includes and `mergeConfigs` is union-only, so a thread cannot opt out of it. The consequence is sharp and easy to miss: **a panel with no blex renderer shows the visitor raw JSON**, and it does so for exactly the content the model was told to present richly. Two independent halves of the system, each correct, never introduced.
+Serve both halves — `blex.min.js` and `blex-render.js` — **from your own origin, resolved out of the installed cumulus package**, exactly as the kit already does for the bridge client (`server.js` → `/agent/blex/*`). Do not vendor them: `blex-render.js` is cumulus's own renderer, shared with the standalone chat widget, so a copy in your tree forks the seam contract and drifts the first time either side moves.
+> **Do not `<script src="${GATEWAY_ORIGIN}/blex.min.js">`.** That recipe is correct only when your app is on a _different_ origin from the gateway. The common production shape is the opposite: `GATEWAY_ORIGIN` is your own hostname and an edge (Caddy, Cloudflare) routes just `/bridge*` and `/api/thread/*` through to the gateway. Your hostname has no `/blex.min.js`, so the load 404s and the panel degrades silently to plain text. Serving from your own origin is correct in **both** deployments, which is why the kit does it unconditionally.
+**Correct origin cache headers are not a defence.** Measured in both directions on this project's own edge, and independently reproduced on a second one: the origin answers `/widget.js` with `Cache-Control: no-cache, must-revalidate` and the browser is handed `max-age=14400`. A CDN-class edge rewrites by **file extension**, regardless of what the origin said. So the `?v=` stamp is not belt-and-braces over your headers — behind such an edge it is the _only_ mechanism you have, and a reader who concludes "my origin already sends no-cache" will skip the one thing that would have worked. HTML is the exception (`no-cache`, `cf-cache-status: DYNAMIC`), which is exactly why an HTML-level stamp works at all — and why everything fetched _after_ the HTML is the hole.
+Three cache traps — the first two measured at a real Cloudflare edge, and each one makes a _correct_ deploy look broken:
+- **404s are cached too.** If you probe the route before it exists, the edge caches the 404 for its default TTL (measured: `max-age=14400` with `cf-cache-status: HIT`, overriding the origin's `no-cache`) — so a correct deploy keeps serving "no library" for four hours. This is nastier than stale content because it reads as "my route isn't registered", sending you to re-debug working code. After adding a route the edge has already seen 404, purge or cache-bust before concluding anything about the route.
+- **An HTML stamp only reaches what HTML requests.** A `?v=` on a `<script src>` versions that file and nothing the file goes on to fetch by itself — so a loader that pulls its own dependencies at runtime has to propagate the version token, or the parent is versioned and its children are not. The kit's `server.js` stamps every `src`/`href` it can see in the served HTML, and — because `panel.css` and the two blex scripts are attached from _inside_ JavaScript — also fills a `window.__AGENT_ASSET_V` map that those loaders consult via `window.agentAsset(url)`. **Do not lift the token off `document.currentScript.src`.** It is the obvious shortcut and it has already shipped broken in a real adopter: that token describes _your_ build, but the library it stamps comes out of the _installed cumulus package_, so a cumulus upgrade changes the bytes while your build — and therefore the URL — stands still, and browsers keep the old library indefinitely. A server-published map gives each file its **own** hash, so the upgrade busts it even though the loader's own bytes didn't move. If you test this, assert that the library URL's token moves when the **package** file changes, not when your build does; a test that rebuilds the app passes against the broken version. (This is a general rule, not a blex problem: `blex.min.js` fetches nothing. Measured on `@luckydraw/blex@0.1.16` — its only dynamic `import()` is the bare `"mermaid"` specifier discussed in §4.6b, `Chart.js v4.5.1` is inlined, and `blex-chart.min.js` is an opt-in companion global that nothing requests.)
+- **Static ESM `import` specifiers can't be stamped this way.** `bridge-mount.js` imports `client.js`, which imports `protocol.js`; both are fetched bare. They ship from the cumulus package and change only on upgrade, and the kit serves them `no-cache, must-revalidate` — which, per the paragraph above, a CDN-class edge will override anyway. Treat these as genuinely unstamped: excluding `/agent/` from your CDN is the fix, not a precaution.
+(One caveat if you probe with `curl -I`: the gateway answers `HEAD` on static assets with `401` while `GET` returns `200` with `Access-Control-Allow-Origin: *`. Probe with `GET`; the asset is not auth-gated.)
+Drive it with an adapter. The required trio is `allowType` / `getInput` / `getSendButton`; `addChip` and `persist` are optional, **and leaving them out is what makes a surface render-only** — there is no mode flag to set.
+```js
+window.CumulusBlexRender.renderOnlyAdapter({
+  getInput: () => document.querySelector('[data-testid="agent-input"]'),
+  getSendButton: () => document.querySelector('[data-testid="agent-send"]'),
+});
+```
+`renderOnlyAdapter` denies `confirm`, `poll`, `form` and `diff`. The test the allow set is derived from is: _a type may render iff every affordance it draws either completes locally or is purely visual._ Selection in `table`/`code`/`file-tree`/`timeline`/`image` is a highlight, so a no-op is invisible. `terminal`/`svg` draw labelled buttons but the clipboard write and the object-URL download both run **before** the emit — the emit is a receipt, not the mechanism. `diff` fails the test: Apply/Reject have no local half, so on a render-only surface they are guaranteed dead buttons that read as "click to apply" — worse than not rendering, because a dead button looks alive in a way raw JSON does not.
+Two implementation traps:
+- **Extract fences before your code-block pass**, not after. Otherwise a fence someone is _showing_ inside a ``` block is eaten by the extractor and vanishes from the block that exists to display it.
+- **Do not implement deny with `unregisterBlockType`.** The registry is module-global, so unregistering `confirm` removes it for every surface sharing that module instance. Deny is a per-render gate. (Nor can you route denials to a library fallback renderer — the global bundle exports no such thing; it exists only on the ESM surface. Leaving the container unclaimed shows the raw fence, which is the honest outcome and costs nothing.)
+Nothing is lost by not rendering `confirm`: export-tier confirms arrive over the **bridge** as a native, audited chip (§4.3), never through message content.
 ### 4.7 Testability (house rules)
 Per the global standards: every interactive element gets a `data-testid` (`agent-panel-*`, `agent-fb-pop|input|send|caret|queue`), the message list carries `data-loading`/`aria-busy` while streaming, and `window.__PUPPET_TEST_MODE__` sets `data-test-mode` to kill animations.

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

@@ -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.
@@ -74,6 +84,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,9 +93,87 @@ 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.
+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.
 ---
@@ -99,6 +188,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,6 +206,40 @@ 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.
+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
@@ -130,16 +264,29 @@ 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.
+| 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/gateway.config.example.json CHANGED Viewed

@@ -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 ADDED Viewed

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

package/examples/web-app-agent/public/agent/bridge-mount.js CHANGED Viewed

@@ -6,7 +6,14 @@
    Because the agent config arrives only after login, this is a function the
    app calls (AgentStart) rather than something that runs at load. AgentStop
-   tears it down on logout so a second login re-mounts cleanly. */
+   tears it down on logout so a second login re-mounts cleanly.
+   KNOWN LIMIT of the version stamp: the import below is a static specifier, so
+   client.js — and protocol.js, which client.js imports in turn — are fetched
+   unstamped. Both ship from the cumulus package and change only on upgrade, and
+   the server sends `no-cache, must-revalidate` on them, so the browser is
+   correct; an edge that overrides that is the exposure. If you put a CDN in
+   front of this app, exclude /agent/ from it. */
 import { BridgeClient } from './bridge-client/client.js';
 let bridge = null;
@@ -16,20 +23,29 @@ window.AgentStart = function () {
   const cfg = window.__AGENT_CONFIG__;
   if (!cfg || !cfg.API_KEY || !window.AgentRegistry || !window.agentDeviceThread) return;
-  window.agentDeviceThread(cfg); // THREAD_ID -> demoapp-v-<deviceId>
+  window.agentDeviceThread(cfg); // THREAD_ID -> <your-namespace>-v-<deviceId>
   console.info('[agent] thread: ' + cfg.THREAD_ID);
   if (!document.getElementById('agent-css')) {
     const link = document.createElement('link');
     link.id = 'agent-css';
     link.rel = 'stylesheet';
-    link.href = '/agent/panel.css';
+    // Built here, so the server's HTML stamp cannot see it — it takes its hash
+    // from the map index.html publishes. Bare URL if that map is absent.
+    link.href =
+      typeof window.agentAsset === 'function'
+        ? window.agentAsset('/agent/panel.css')
+        : '/agent/panel.css';
     document.head.appendChild(link);
   }
   window.AgentChat.init(cfg);
   window.AgentPanel.init();
+  // Rich blocks, loaded same-origin from /agent/blex/. Fire-and-forget: the panel renders
+  // plain markdown until these arrive, and keeps doing so if they never do.
+  if (window.AgentBlex) window.AgentBlex.load(cfg);
   bridge = new BridgeClient({
     url: cfg.BRIDGE_URL,
     thread: cfg.THREAD_ID,

package/examples/web-app-agent/public/agent/commands.js CHANGED Viewed

@@ -11,12 +11,18 @@
    Frozen contract:
      command   { name, description, params, risk, execute(params) }
-     risk      "read"    — answers a question, changes nothing
+     risk      "export"  — the ONLY gated tier. ALWAYS routed through the
+                           confirm chip by the gateway; the model cannot bypass
+                           it, and neither can this file.
+               "read"    — answers a question, changes nothing
                "display" — changes what's on screen only, trivially undoable
                "mutate"  — changes stored data
-               "export"  — irreversible or leaves the app. ALWAYS routed
-                           through the confirm chip by the gateway; the model
-                           cannot bypass it, and neither can this file.
+               The last three are ADVISORY: they dispatch on arrival. The tier
+               rides in the tool description the model sees ("[mutate] …") so it
+               can weigh the call, but nothing stops it. Tier by "must a human
+               see this first?", not by "is this irreversible?" — if yes, it is
+               "export". A command that reads as guarded and isn't fails
+               silently: it just runs.
      execute   -> { summary, data?, affected? }  (may be async)
      call()    never throws — failures become { ok: false, summary }

package/examples/web-app-agent/public/agent/device-thread.js CHANGED Viewed

@@ -5,16 +5,16 @@
    name must be unguessable and must never be minted server-side and broadcast.
    This mints 16 hex characters (64 bits) once per browser, keeps it in
-   localStorage, and pins THREAD_ID = <base>-<deviceId>. The base the server
-   sends is "demoapp-v" — a sub-namespace under "demoapp", so visitor threads
-   get their own gateway config (cheap model, tight prompt) while the base
-   "demoapp" thread stays yours for working on the app.
+   localStorage, and pins THREAD_ID = <base>-<deviceId>. The base comes from the
+   server (this file never names your app). Send "<ns>-v" — a sub-namespace
+   under "<ns>" — so visitor threads get their own gateway config (cheap model,
+   tight prompt) while the base "<ns>" thread stays yours for working on the app.
    Do not shorten the id. 8 hex characters is 32 bits, which is brute-forceable
    against a live gateway. */
 (function () {
   'use strict';
-  var KEY = 'demoapp.deviceId';
+  var KEY = 'agent.deviceId'; // app-neutral: localStorage is origin-partitioned
   window.agentDeviceThread = function (cfg) {
     if (!cfg || !cfg.THREAD_ID) return null;

package/examples/web-app-agent/public/agent/panel.css CHANGED Viewed

@@ -79,6 +79,12 @@
 #agent-root .agmsg table { border-collapse: collapse; font-size: 12.5px; }
 #agent-root .agmsg th, #agent-root .agmsg td { border: 1px solid var(--line); padding: 4px 8px; text-align: left; }
+/* Blex blocks. The container is what the shared renderer (blex-render.js) fills;
+   .blex-fallback is the raw fence, shown when nothing claims the container —
+   a denied type, or blex failing to load. Both beat a blank rectangle. */
+#agent-root .blex-block-container { margin: 6px 0; border-radius: 8px; overflow: hidden; max-width: 100%; }
+#agent-root .blex-fallback { margin: 0; padding: 8px 10px; background: var(--panel3); border: 1px solid var(--line); border-radius: 8px; font-size: 11.5px; line-height: 1.45; white-space: pre-wrap; word-break: break-word; opacity: .85; overflow-x: auto; }
 #agent-root .agactivity { align-self: flex-start; color: var(--muted); font-size: 12px; padding: 0 4px; animation: agpulse 1.4s ease-in-out infinite; }
 @keyframes agpulse { 0%, 100% { opacity: .55; } 50% { opacity: 1; } }
 /* Browser tests set data-test-mode to kill animation timing races. */

package/examples/web-app-agent/public/agent/panel.js CHANGED Viewed

@@ -9,7 +9,9 @@
    window.AgentPanel = { init(), setState(s), confirm(req), notify(text), reset() } */
 (function () {
   'use strict';
-  var LS_KEY = 'demoapp-agent-v1';
+  /* App-neutral on purpose: localStorage is already origin-partitioned, so an
+     app-name prefix buys nothing, and this file is meant to be copied as-is. */
+  var LS_KEY = 'agent-panel-v1';
   var root, barEl, winEl, logEl, inputEl, dotEl;
   var prefs = { expanded: false, draft: '' };
   var streaming = false;
@@ -78,6 +80,20 @@
     });
   }
+  /* Render markdown, then blex blocks into it.
+     Blex fences are pulled out FIRST so the code-block branch below cannot eat
+     them, and the placeholders go back in last. Returns the extracted blocks so
+     the caller can hand them to AgentBlex.render once the HTML is in the DOM.
+     Without blex loaded this is exactly the old behaviour. */
+  function renderRich(text) {
+    var blex = window.AgentBlex;
+    var extracted = blex ? blex.extract(String(text)) : { text: String(text), blocks: [] };
+    var html = renderMarkdown(extracted.text);
+    if (blex) html = blex.insertPlaceholders(html, extracted.blocks);
+    return { html: html, blocks: extracted.blocks };
+  }
   function renderMarkdown(text) {
     var lines = String(text).split('\n');
     var html = '',
@@ -170,8 +186,11 @@
   function addMsg(role, content, asMarkdown) {
     var m = el('div', 'agmsg ' + role, logEl);
-    if (asMarkdown) m.innerHTML = renderMarkdown(content);
-    else m.textContent = content;
+    if (asMarkdown) {
+      var r = renderRich(content);
+      m.innerHTML = r.html;
+      if (window.AgentBlex) window.AgentBlex.render(m, r.blocks);
+    } else m.textContent = content;
     scrollLog();
     return m;
   }
@@ -235,7 +254,11 @@
         streaming = false;
         setLoading(false);
         activity.remove();
-        bubble.innerHTML = renderMarkdown(acc);
+        // Blocks are rendered only at `done` — mid-stream a fence is usually
+        // incomplete, and re-rendering each token would churn the handles.
+        var done = renderRich(acc);
+        bubble.innerHTML = done.html;
+        if (window.AgentBlex) window.AgentBlex.render(bubble, done.blocks);
         scrollLog();
       },
     });