@luckydraw/cumulus 0.31.66 → 1.0.1

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

@@ -0,0 +1,559 @@
+# Building a Persistent Web-App Agent with Cumulus
+
+How to embed a persistent AI agent into any web app using the cumulus gateway — an agent that can **drive the app's UI**, **answer questions about the app and its data**, and **remember every conversation per visitor**, with no fork, no second gateway, and no per-app backend beyond a static file server.
+
+**Start here:** [`examples/web-app-agent/`](../examples/web-app-agent/) is a complete, runnable version of everything below — a small app with a working agent, ~700 lines you can copy. Run that first, then use this document to understand what each piece is doing and why.
+
+Two implementations run live on this recipe: **Kalendeer** (`kalendeer.soapko.com`), which the starter kit is extracted from, and **Pursuit** (`pursuit.soapko.com`), the original. Where they differ, prefer Kalendeer: it delivers the scoped key through a session-gated endpoint rather than injecting it into public HTML (§3.1), and it mints 16-hex device ids rather than 8 (§4.1). Both differences are security-relevant, not stylistic.
+
+> **Versions:** requires cumulus gateway `>= 0.31.41` (bridge, namespaces, capability-by-name enforcement, config prefix-fallback all landed in the 0.31.38–0.31.41 series, tasks 097/098).
+
+---
+
+## 1. Architecture at a glance
+
+```
+ Browser tab (your app)                        Thundercat gateway (cumulus)
+┌───────────────────────────────┐             ┌──────────────────────────────────┐
+│ your app UI                   │             │  one thread per visitor:         │
+│  ├─ command registry          │   wss       │   myapp-<deviceId>               │
+│  │   (window.MyAppAgent)      │  /bridge    │   ├─ full history + RAG          │
+│  ├─ BridgeClient  ────────────┼────────────▶│   ├─ per-thread config           │
+│  ├─ agent panel (chat UI)     │   https     │   │   (inherited from            │
+│  │   POST /api/thread/…  ─────┼────────────▶│   │    myapp.config.json)        │
+│  └─ selection / right-click   │   SSE       │   └─ Claude subprocess per turn  │
+│     feedback capture          │             │        └─ MCP shim ──────────────┼──┐
+└───────────────────────────────┘             └──────────────────────────────────┘  │
+                                                    ▲                               │
+                                              POST /bridge/call ◀───────────────────┘
+                                              (agent tool call → executes in the tab)
+```
+
+Three moving parts:
+
+1. **The gateway** (already running) — owns conversation history, RAG retrieval, prompt assembly, and spawns Claude per turn. One config block per app.
+2. **The app's front end** — registers a typed **command registry** (what the agent can see and do in the UI), mounts the **bridge client** (a WebSocket back to the gateway), and renders the **agent panel** (chat UI + feedback capture).
+3. **An MCP shim** — a ~120-line stdio script the gateway spawns per turn. It fetches the app's command manifest and exposes each command as a tool the model can call; calls are forwarded to `POST /bridge/call`, which dispatches into the live browser tab.
+
+The loop that makes the agent "drive the app": the model calls a tool → shim → `POST /bridge/call` → gateway pushes `call` over the tab's WebSocket → the tab executes it against the registry (through the app's own actions, so guards/routing/notifications all still work) → result flows back to the model.
+
+### Key concepts
+
+| Concept                            | What it is                                                                                                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Namespace**                      | A config block (`namespaces[]`) that groups an app's threads (`myapp-*`), scopes its API key, and carries its per-app settings (proxy, MCP servers).          |
+| **Base thread** (`myapp`)          | _Your_ management thread for the app — visible only to your admin key. Never used by visitors. Also the config template for visitor threads.                  |
+| **Visitor threads** (`myapp-<id>`) | One per browser/device, minted client-side. Full persistent history + RAG each. Hidden from the default thread list.                                          |
+| **Bridge**                         | The gateway↔tab WebSocket: tab registers its command manifest; gateway dispatches agent tool calls into the tab.                                              |
+| **Command registry**               | The app-side catalog of typed commands (`{ name, description, params, risk, execute }`) — the single capability surface for both the UI and the agent.        |
+| **Capability-by-name**             | The security model: a scoped key can only touch threads in its namespace, can enumerate nothing, and the random thread name itself is the per-visitor secret. |
+
+---
+
+## 2. Gateway setup (one config edit)
+
+All gateway-side setup is a single edit to `~/.cumulus/gateway.config.json`; the gateway admin then reloads the gateway (if needed) to pick it up. No code changes, no publish.
+
+> The snippets below are annotated for readability — the real config file is **strict JSON**: strip the comments and trailing commas when copying.
+
+### 2.1 Enable the bridge (once, global)
+
+```jsonc
+{
+  "bridge": { "enabled": true },
+}
+```
+
+Default is off; with it off every bridge surface is inert.
+
+### 2.2 Add the app's namespace
+
+```jsonc
+{
+  "namespaces": [
+    {
+      "name": "myapp", // covers threads matching myapp-*
+      "label": "My App",
+      "apiKeys": ["sk-myapp-<random>"], // the app's OWN key — mint a fresh one
+
+      // OPTIONAL: reverse-proxy selected paths to the app's backend through
+      // the gateway origin (so the front end needs only one origin).
+      "executorProxy": {
+        "origin": "http://127.0.0.1:8097",
+        "pathPrefixes": ["/state", "/journal"],
+      },
+
+      // OPTIONAL but required for "drive the app": the MCP shim that turns
+      // the app's command manifest into model-callable tools. Spawned per
+      // turn, ONLY for threads in this namespace. {thread} is substituted
+      // with the actual thread name (myapp-<deviceId>) in args AND env.
+      "extraMcpServers": {
+        "myapp-tools": {
+          "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}",
+          },
+        },
+      },
+    },
+  ],
+}
+```
+
+Namespace semantics (locked in task 097):
+
+- `myapp` (the bare name) is **not** in the namespace — it's your management thread, owned by your admin key. The namespace covers `myapp-*` only.
+- Longest prefix wins, so `myapp-demo` can be its own nested namespace under `myapp` later.
+- The scoped key is **confined**: it can read/write only `myapp-*` threads, gets an empty list from every enumeration surface (`/api/threads`, `/api/agents`, dashboard), and is rejected (403) everywhere else.
+
+### 2.3 Create the base thread config
+
+Visitor threads inherit their config from the base by **prefix-fallback** (task 098): a turn on `myapp-a3f8c2d1` that has no exact `myapp-a3f8c2d1.config.json` reads `myapp.config.json` instead. Writes stay exact, so a visitor session can never mutate the base.
+
+`~/.cumulus/threads/myapp.config.json` (real Pursuit example):
+
+```json
+{
+  "projectDir": "/home/you/projects/myapp",
+  "model": "claude",
+  "effort": "high",
+  "alwaysInclude": ["docs/myapp-system-prompt.md"]
+}
+```
+
+- `projectDir` — the working directory for the agent's turns (where `alwaysInclude` paths resolve).
+- `alwaysInclude` — the app's **system prompt document**: what the app is, how to talk to its users, when to use which commands, tone. This is where the agent's product knowledge and persona live.
+- `model` / `effort` — per-app quality/latency dial.
+
+### 2.4 Verify
+
+Verify with the scoped key:
+
+```bash
+# Confined: in-namespace works, everything else 403s, lists come back empty
+curl -s -H "X-API-Key: sk-myapp-..." https://gw.example.com/api/thread/myapp-smoketest/history   # 200
+curl -s -H "X-API-Key: sk-myapp-..." https://gw.example.com/api/thread/someother/history         # 403
+curl -s -H "X-API-Key: sk-myapp-..." https://gw.example.com/api/threads                          # {"threads":[]}
+```
+
+### 2.5 The license key (this is the part that gates production)
+
+Everything in this guide runs unlicensed — that is deliberate, so you can build
+and evaluate the whole integration before anyone signs anything. What an
+unlicensed gateway will not do is **carry a visitor population**: each configured
+namespace may hold at most **5 distinct threads**. Minting the 6th is refused with
+`402` and a contact address; existing threads keep working, and threads outside a
+namespace (your own, the CLI, the TUI) are never limited.
+
+Since every visitor gets their own thread (§4.1), that cap is invisible during
+development and hits on roughly your sixth real user. Budget for it before launch,
+not after.
+
+```json
+{ "licenseKey": "cumulus-lic-v1...." }
+```
+
+Add it to `gateway.config.json` and reload. Keys are verified offline — nothing is
+transmitted, and an air-gapped gateway works fine — and are issued per whole-number
+release, so a `1.x` key covers every `1.x.y`. The gateway logs its licence state at
+startup and hourly, and the admin UI shows it under **Settings → License**.
+
+Commercial licensing: **ops@luckydrawdesign.com**. See [`LICENSE`](../LICENSE).
+
+---
+
+## 3. The app backend: serving layer + shim
+
+### 3.1 Serve the agent config from a session-gated endpoint
+
+The front end is configured by a single `window.__AGENT_CONFIG__` object. Never hardcode gateway details or keys into the app bundle — and prefer handing them out **only to an authenticated session**, as Kalendeer does (`examples/web-app-agent/server.js`):
+
+```js
+if (req.method === 'GET' && p === '/api/agent-config') {
+  if (!sessionOf(req)) return json(res, 401, { error: 'not signed in' });
+  if (!API_KEY) return json(res, 404, { error: 'agent not configured' });
+  return json(res, 200, {
+    GATEWAY_URL: GATEWAY_ORIGIN,
+    BRIDGE_URL: GATEWAY_ORIGIN.replace(/^http/, 'ws') + '/bridge',
+    THREAD_ID: 'myapp-v', // BASE name — the browser appends the per-device suffix
+    API_KEY, // namespace-scoped, from env; never in the repo
+  });
+}
+```
+
+Give `GATEWAY_ORIGIN` **no default**, and refuse to start when a key is configured without it. Whatever is listening on the usual gateway port is usually a real gateway, so an app that defaults plus an operator who mistypes the variable is an app quietly pointed at a live one — a failure that looks like success. The kit's `server.js` also exits on near-miss names it does _not_ read (`AGENT_API_KEY`, `GATEWAY_URL`, `DEMO_PASSWORD`, …), naming the one it does.
+
+The front end then calls `AgentStart()` once the config arrives, and `AgentStop()` on logout.
+
+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.
+- When the endpoint 404s (no key configured), every agent module no-ops cleanly and the app runs with its agent features dark. Keep that path working; it's what local dev uses.
+
+### 3.2 The MCP shim (~120 lines, copy Pursuit's)
+
+The shim is a stdio MCP server the gateway spawns per turn. Pursuit's (`server/executor/src/mcp-shim.js`) is app-agnostic apart from its env defaults — the whole job:
+
+1. **`tools/list`** → fetch the manifest and return it as MCP tool definitions.
+   - Source: `GET {GATEWAY_ORIGIN}/bridge/manifest/{BRIDGE_THREAD}` (the gateway serves the tab's **live** registration, or the **persisted last-known** manifest when no tab is connected).
+   - Optionally merge a headless manifest from your own backend (Pursuit merges its executor's `/manifest` first, headless-wins, so grounded reads work with no tab open).
+   - MCP tool names can't contain dots: expose `search.query` as `search_query`, map back on call.
+   - Prefix each description with the risk tier: `"[read] Run a filter query…"`.
+2. **`tools/call`** → `POST {GATEWAY_ORIGIN}/bridge/call` with `{ thread, command, params }`, return the JSON result (`{ ok, summary, data?, affected? }`), setting `isError: !result.ok`.
+   - If no tab is connected the gateway returns a graceful `{ ok:false, summary:'No active app session' }` — the model sees an honest failure, not a hang.
+
+Because the manifest is fetched fresh every `tools/list`, **new front-end commands surface to the agent with zero backend changes** — ship a new registry entry in the app and the model can call it on the next turn.
+
+### 3.3 Optional: executor proxy
+
+If the app has its own backend the agent panel needs to reach (state reads, journals), list its path prefixes under `executorProxy` (§2.2) and the gateway will forward them — the browser only ever talks to one origin. Longest-prefix, segment-boundary matching; upstream status/content-type relayed; 502 when unreachable.
+
+---
+
+## 4. Front-end integration
+
+Pursuit's agent layer is ~10 small files under `agent/`. Load order matters — classic scripts first (registry, identity, dock), ES modules after (bridge mount), React panel last:
+
+```html
+<!-- 1. classic scripts, in order -->
+<script src="agent/device-thread.js"></script>
+<!-- BEFORE any __AGENT_CONFIG__ consumer -->
+<script src="agent/commands.js"></script>
+<!-- registry: window.MyAppAgent -->
+<script src="agent/dock.js"></script>
+<script src="agent/chat-client.js"></script>
+<script src="agent/selection.js"></script>
+<!-- 2. ES module (deferred — always runs after classic scripts) -->
+<script type="module" src="agent/bridge-mount.js"></script>
+<!-- 3. the React panel mounts in its OWN root, sibling of the app's -->
+```
+
+### 4.1 Per-visitor thread identity (`device-thread.js`, 31 lines)
+
+Rewrites the injected base `THREAD_ID` to a per-device name before anything else reads it:
+
+```js
+(function () {
+  var cfg = window.__AGENT_CONFIG__;
+  if (!cfg || !cfg.THREAD_ID) return; // local dev — no-op
+
+  var KEY = 'myapp.deviceId';
+  var id = null;
+  try {
+    id = localStorage.getItem(KEY);
+  } catch (e) {}
+  if (!id || !/^[0-9a-f]{8,}$/.test(id)) {
+    // accept legacy widths
+    var bytes = new Uint8Array(8); // 16 hex chars for new devices
+    crypto.getRandomValues(bytes);
+    id = Array.prototype.map
+      .call(bytes, function (b) {
+        return ('0' + b.toString(16)).slice(-2);
+      })
+      .join('');
+    try {
+      localStorage.setItem(KEY, id);
+    } catch (e) {}
+  }
+  cfg.THREAD_ID = cfg.THREAD_ID + '-' + id; // myapp-<deviceId>
+})();
+```
+
+- The thread name doubles as the visitor's capability (§6) — use **at least 16 hex chars (8 random bytes)** for new apps. (Pursuit predates this guidance with 8 hex; its validation regex is being loosened, not tightened, so legacy ids survive.)
+- Every consumer (chat client, panel, bridge mount) reads `cfg.THREAD_ID` _after_ this runs — hence "first classic script."
+
+### 4.2 The command registry (`commands.js`)
+
+The single capability surface. The UI and the agent are two equal clients of it — commands go through the app's existing actions/engines only, so guards, router history, and notifications keep working when the agent drives.
+
+> **Build the registry first, independent of the agent — this inversion is the load-bearing idea.** The registry is a plain global (`window.MyAppAgent`) that works with **no bridge, no gateway, and no network**; the bridge mount (§4.3) merely hands the client a two-member adapter (`{ manifest, execute }`) over it. There is no `registerTool` on the bridge client, and there should not be: an app whose capabilities live inside the agent transport can't be driven when the gateway is down, can't be unit-tested without it, and can't be reused by anything else. Write the registry as **your app's own public API**; the agent is simply its second client.
+
+Frozen contracts:
+
+```js
+// command shape
+{ name: 'search.query',
+  description: 'Run a filter query headlessly… Does NOT change what the user sees — use search.show for that.',
+  params: { /* JSON Schema */ },
+  risk: 'read',                       // read | display | mutate | export
+  execute(params) { return { summary, data, affected }; } }
+
+// result shape (call() never throws — errors become { ok:false, summary })
+{ ok: true, summary: '412 accounts match 2 filters.', data: {...}, affected: [...] }
+
+// registry API (window.MyAppAgent)
+MyAppAgent.register(def)   MyAppAgent.call(name, params)
+MyAppAgent.list()          MyAppAgent.manifest()   // → [{ name, description, risk, input_schema }]
+```
+
+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):
+
+- **`app.describe`** _(read)_ — static knowledge: what each route/section is (with aliases), a glossary, and how-to recipes. This is how the agent answers "where do I…" / "what is…" questions accurately instead of guessing.
+- **`app.describeView`** _(read)_ — what the user is looking at **right now**. Recomputed fresh on every call, never cached. This is the single most load-bearing command for the "answer questions about the app" half of the job, so its payload deserves real design. Pursuit's shape:
+
+  ```js
+  {
+    route, page, entity,                  // where the user is
+    filters: [ /* committed filters only — not half-typed ones */ ],
+    activeSavedSearchId,
+    selection:      { accounts: [key], contacts: [key], signals: [key] },
+    selectionNamed: { accounts: [{ key, name }], … },  // ← see below
+    detail,                               // open record slide-over, if any
+    highlight,                            // what's spotlighted on screen
+    worksheetId, agentId, instanceId, … , // page-scoped ids
+    results: { count, visible: [{ key, name }] }   // only on list pages, top 20
+  }
+  ```
+
+  Three design rules worth copying:
+  - **Resolve ids to names** (`selectionNamed`) so the agent can say _"Maria Chen"_ instead of `A-001::mchen@…`. Raw keys alone make the agent sound like a database.
+  - **Add page-conditional blocks** rather than one flat shape — Pursuit appends `inboxView` / `impactView` / `usageView` only on those routes, so the agent isn't blind on a screen the generic shape doesn't cover.
+  - **Cap list payloads** (`visible` = first 20 with a true `count`) — the view snapshot rides along on every turn, so it must stay small.
+
+Beyond those, register whatever the app can already do: `search.query` / `search.show`, `nav.goTo`, `records.get`, `worksheets.list`, mutations, exports. Write descriptions **for the model** — say when _not_ to use a command and where ids come from (Pursuit's descriptions are the benchmark: `"keys come from search.query / app.describeView rows"`).
+
+### 4.3 Mounting the bridge (`bridge-mount.js`, ~70 lines)
+
+The `BridgeClient` is **served by cumulus** (vendored at `src/gateway/bridge/client.ts`; Pursuit ships it as `agent/bridge-client/`) — mount it, don't modify it. It owns the socket lifecycle: registers `{ thread, apiKey, manifest }` on open, executes incoming `call`s against your registry, handles confirm round-trips, reconnects with exponential backoff (500ms → 15s).
+
+```js
+import { BridgeClient } from './bridge-client/client.js';
+
+const cfg = window.__AGENT_CONFIG__;
+const bridge = new BridgeClient({
+  url: cfg.BRIDGE_URL, // wss://gw.example.com/bridge
+  thread: cfg.THREAD_ID, // myapp-<deviceId>
+  apiKey: cfg.API_KEY, // the scoped key
+  registry: {
+    manifest: MyAppAgent.manifest(),
+    execute: (command, params) => Promise.resolve(MyAppAgent.call(command, params)),
+  },
+  // Recomputed on EVERY sendContext — never cached (contract).
+  describeView: () => {
+    const r = MyAppAgent.call('app.describeView');
+    return r.ok ? r.data : { error: r.summary };
+  },
+  // Export-tier confirms surface as UI chips; without this hook they are
+  // auto-DECLINED — export can never silently execute.
+  onConfirmRequest: req =>
+    window.dispatchEvent(new CustomEvent('myapp:agent-confirm', { detail: req })),
+  onStateChange: s => console.info('[bridge] ' + s),
+});
+bridge.connect();
+window.MyAppBridge = bridge; // panel calls sendContext() on each user turn
+```
+
+The gateway's registration handler checks that the presented key is entitled to that thread — a scoped key can only register tabs for its own namespace.
+
+### 4.4 The chat client (`chat-client.js`, ~140 lines)
+
+Plain `fetch` + SSE against the gateway's chat API — no library:
+
+```
+POST {GATEWAY_URL}/api/thread/{THREAD_ID}/message      body { message }, header X-API-Key
+  → SSE stream:  token {text}  ·  segment {type,…}  ·  error  ·  done
+GET  {GATEWAY_URL}/api/thread/{THREAD_ID}/history      → prior messages (reload survival)
+```
+
+Expose a tiny surface for the panel — `send(message, { onToken, onSegment, onError, onDone }) → { cancel() }` and `history()` — and keep a stub emitter behind it for offline dev.
+
+### 4.5 The agent panel UX (`panel.jsx` + `panel.css` + `dock.js`)
+
+The patterns Karl called out, as Pursuit implements them:
+
+**Own React root, immortal across navigation.** The panel renders into `#agent-panel-root`, a _sibling_ of the app's root — route changes can never unmount it. Open state, position, size, collapse, draft text, and message list all survive navigation; geometry persists in `localStorage` (`ps-agent-panel-v1`) so it also survives reloads.
+
+**Minimized home bar, pinned bottom-center.** The resting state is a slim input bar at the bottom of the page, width `min(560px, 100vw − 32px)`. Typing into it (or clicking) expands the panel.
+
+**Expands upward from the bar.** The expanded window re-anchors bottom-centered, 16px off the floor, keeping the bar's width and the user's last height (capped at ~72% of viewport) — it reads as the bar _growing upward_, not a new window appearing.
+
+**Floating window ergonomics.** Movable and resizable with two clamping modes: a loose clamp while dragging (you can park it near an edge but a grab-strip always stays on screen) and a strict re-fit on mount/viewport-resize (a rect saved on a big monitor can't start offscreen on a laptop — if it would be >half offscreen it resets to the default slot).
+
+**Dockable into pages.** `dock.js` is a 60-line framework-agnostic registry: any page can mount an element and call `MyAppDock.register(id, el)`; the panel then portals its body into that slot instead of floating. One dock at a time; the user's explicit undock preference is remembered per slot id; leaving the page returns the panel to floating.
+
+**In-message record chips.** Assistant markdown renders `[[entity:key|Label]]` refs as navigable chips that open the record **through the command registry** (`detail.open` / `worksheets.open` / `nav.goTo` per entity) — so answers link straight into the app and navigation still goes through the app's own action layer. Teach the convention in your system-prompt doc and the agent will emit refs unprompted.
+
+Two parsing traps, both real (Pursuit's `markdown.jsx` handles them and a naive renderer will not):
+
+- **Inside a GFM table cell the ref's pipe is escaped** — the agent emits `[[accounts:A-001\|Los Angeles USD]]` so the literal `|` doesn't split the cell. Tolerate the optional backslash and strip trailing escapes off the key, or you look up `"A-001\"` and navigation silently fails.
+- **Split table cells on _unescaped_ pipes only**, for the same reason.
+
+Inline parse order matters too: code → chip → link → bold → italic (`**` before `*`).
+
+**Not a mobile design.** State plainly what this is: `panel.css` contains **zero `@media` queries**. Small screens are handled by the same viewport-fit clamping math as large ones (`min(560px, 100vw − 32px)`, height capped to a fraction of viewport), which keeps the panel usable but is not a designed mobile experience. If you need real mobile — full-screen sheet, keyboard-aware layout, touch drag — that is your work to add, not something inherited by copying these files.
+
+**Streaming + activity.** The panel renders `token` events as streaming text and `segment` events (thinking / tool_use / tool_result) as activity indicators, so tool-heavy turns show liveness rather than a dead spinner.
+
+**Fresh context on every turn.** On each user send, the panel calls `MyAppBridge.sendContext(window.__agentSelection)` — piggybacking a fresh `describeView` (and any pending selection context) onto the turn. Gateway-side this arrives as an ephemeral CONTEXT block in the prompt: the agent always knows what screen the user is on _right now_, without it being persisted as fake history.
+
+### 4.6 Selection & right-click feedback (`selection.js`, ~300 lines)
+
+Two entry points, one composer popup:
+
+1. **Text selection** — anywhere (app page _or_ chat window). On pointer **release** (never mid-drag, and never stealing focus — the selection stays live and copyable), a small composer opens near the selection.
+2. **Right-click on any element** — highlights the block (outline class), captures it as context, opens the same composer at the cursor. Target picking prefers a record-bearing element (`[data-agent-ref]`), then a semantic block (`td, li, p, h2, article, button…`), then the nearest reasonably-sized `div` — never the whole page.
+
+The composer is a plain DOM popup (no framework): a textarea (`"Ask about this, or leave feedback…"`), a context hint (`<div> · 3 records`), and a split button — **Send** (submit to the agent now) or **Queue Feedback** (attach as a chip on the panel composer, comment becomes the draft). Enter sends; Escape closes.
+
+What gets captured (the `context` object):
+
+```js
+{ text,                                   // the selected text, if any
+  refs: [{ entity, key, field? }],        // parsed from data-agent-ref attributes
+  element: { tag, id, classes, agentRef, testid, screen },   // right-click only
+  view }                                  // fresh app.describeView snapshot
+```
+
+**No screenshot is captured** — worth stating, because "right-click for feedback" implies a screen grab to most readers. There is no canvas capture, no `toDataURL`, no image of any kind. The context is entirely textual: the element's `innerText` (truncated at 2,000 chars), the record refs parsed from `data-agent-ref`, a small element descriptor, and a fresh `app.describeView`. That is deliberate — it is cheaper, it is legible in the prompt, and it stays accurate because `describeView` is recomputed rather than pictured. It also means **the agent's understanding of "this thing here" is only as good as your `data-agent-ref` coverage and your `describeView` payload**, not something the browser supplies for free.
+
+Delivery is decoupled via an event — `window.dispatchEvent(new CustomEvent('myapp:agent-compose', { detail: { mode, comment, context } }))` — the panel owns sending it to the gateway. The latest context also mirrors to `window.__agentSelection`, so a plain panel send carries it implicitly.
+
+**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.
+
+---
+
+## 5. Runtime flows (what actually happens)
+
+### 5.1 Answering a question
+
+1. Visitor types into the panel → panel calls `MyAppBridge.sendContext(selection)` then `POST /api/thread/myapp-<id>/message`.
+2. Gateway assembles the prompt: system prompt doc (`alwaysInclude`), RAG-retrieved history _from this visitor's own thread_, recent conversation, and the ephemeral CONTEXT block (current view + selection).
+3. Claude answers — calling `app_describe` / `search_query` / `records_get` through the shim when it needs live data — and streams back over SSE.
+
+### 5.2 Driving the app
+
+1. Model calls e.g. `search_show` (a `display`-tier tool) → shim → `POST /bridge/call { thread, command: 'search.show', params }`.
+2. Gateway pushes `call` down the tab's `/bridge` WebSocket; the `BridgeClient` executes it against the registry; the app's own action layer updates the screen.
+3. `{ ok, summary, data?, affected? }` returns up the same path to the model. Timeout: 10s per call; no tab connected → graceful `ok:false`.
+
+### 5.3 Export-tier confirm (human in the loop)
+
+1. Model calls an `export` command → the gateway **never dispatches it directly**; it sends `confirm-request` to the tab instead.
+2. `onConfirmRequest` fires → the panel renders a confirm chip with the summary; the user clicks Accept (executes, result flows back) or Decline (refusal reported). No handler wired = auto-decline. Confirm timeout: 120s.
+
+### 5.4 What else the agent can do
+
+Every gateway thread also gets cumulus's standard tools: persistent RAG over its own history and stored content (`search_history`, `read_file`, …), inter-agent messaging (`send_to_agent` — e.g. a visitor session escalating to your `myapp` management thread), push notifications (`notify_user`), and email if configured. The system prompt doc decides what the agent should actually use.
+
+---
+
+## 6. Security model (capability-by-name)
+
+Locked in task 097 P7 and verified live:
+
+| Property                             | Enforcement                                                                                                                                                   |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scoped key confined to its namespace | 403 on any thread outside `myapp-*`, on every REST/WS/bridge surface, including bridge tab registration                                                       |
+| No enumeration                       | Scoped keys get empty results from `/api/threads`, `/api/agents`, WS thread lists, and the dashboard — there is no surface that lists visitor thread names    |
+| Thread name = per-visitor capability | Names are `myapp-<random hex>`; knowing a name is what grants access to that conversation. Use ≥16 hex chars of `crypto.getRandomValues` entropy for new apps |
+| Base thread belongs to the owner     | `myapp` itself is outside the namespace — the app's key can't read your management thread                                                                     |
+| Visitor configs can't touch the base | Config prefix-fallback is **read-only**; writes stay exact (task 098)                                                                                         |
+| Export can't auto-run                | Confirm path enforced gateway-side regardless of caller flags                                                                                                 |
+
+Operational corollaries:
+
+- Never ship an admin key to a browser. One scoped key per app.
+- Don't log request URIs on the public edge (thread names appear in paths like `/bridge/manifest/:thread`). The default Caddy setup here has no access log; keep it that way or accept the exposure knowingly.
+- Key rotation = edit `namespaces[].apiKeys`, have the admin reload the gateway, and redeploy the serving layer's env.
+
+---
+
+## 7. Standing up your next app — checklist
+
+**Gateway (5 minutes):**
+
+1. Mint a key: `sk-<app>-$(openssl rand -hex 16)`.
+2. Add the `namespaces[]` block (§2.2); ensure `bridge.enabled: true`. Before asking for a reload, validate the edited file against the installed loader — note `loadGatewayConfig` is **async**, so await it:
+
+   ```bash
+   node -e 'import(process.argv[1] + "/@luckydraw/cumulus/dist/gateway/config.js")
+     .then(m => m.loadGatewayConfig(process.env.HOME + "/.cumulus/gateway.config.json"))
+     .then(() => console.log("config OK"), e => { console.error(e.message); process.exit(1); })' "$(npm root -g)"
+   ```
+
+3. Write `<app>.config.json` (projectDir, model, effort, `alwaysInclude` system-prompt doc) and the system-prompt doc itself.
+4. Ask the gateway admin to reload the gateway (if needed), then run the §2.4 probes.
+
+**App backend:** 5. Serve `__AGENT_CONFIG__` from a session-gated route (key from env, not the repo) — §3.1. 6. Copy `examples/web-app-agent/agent/mcp-shim.js`; point its env at your gateway + key; wire it in `extraMcpServers` with `BRIDGE_THREAD: "{thread}"`.
+
+**Front end:** 7. Copy `examples/web-app-agent/public/agent/` wholesale — `device-thread.js` (rename the localStorage key), `bridge-mount.js`, `chat-client.js`, `panel.js`, `panel.css` — and serve cumulus's `dist/gateway/bridge/{client,protocol}.js` at `/agent/bridge-client/` rather than vendoring a copy. 8. Write `commands.js` for _your_ app: `app.describe`, `app.describeView`, then your reads/displays/mutates/exports. Put `data-agent-ref` on record-bearing elements, `data-testid` on interactive ones. 9. Check script load order (§4) and the no-`__AGENT_CONFIG__` no-op path for local dev.
+
+**Verify end-to-end:** 10. Open the app → console shows `[device-thread] thread: <app>-<id>` and `[bridge] open`. 11. Ask the panel a question that needs live data — confirm a `[read]` tool call round-trips. 12. Ask it to change the screen — confirm a `display` command drives the UI. 13. Trigger an `export` — confirm the chip appears and Decline suppresses execution. 14. Right-click an element, send feedback — confirm the agent receives element + refs + view context.
+
+**Before launch:** 15. Add the `licenseKey` (§2.5) and reload. Unlicensed, the
+namespace stops minting new visitor threads at 5 — a limit you will not hit in
+development and will hit on your first real day.
+
+---
+
+## 8. Reference: file map
+
+Every path below exists in the shipped package — this is the runnable kit, not a description of someone else's repo.
+
+| Layer     | File                                                 | Role                                                      |
+| --------- | ---------------------------------------------------- | --------------------------------------------------------- |
+| Gateway   | `~/.cumulus/gateway.config.json`                     | namespace, scoped key, `executorProxy`, `extraMcpServers` |
+| Gateway   | `examples/web-app-agent/gateway.config.example.json` | the fragment to merge into it                             |
+| Gateway   | `~/.cumulus/threads/myapp-v.config.json`             | base config visitor threads inherit (model, prompt, cwd)  |
+| Gateway   | `dist/gateway/bridge/{protocol,gateway,client}.js`   | the bridge itself — cumulus-owned, never forked           |
+| Serving   | `examples/web-app-agent/server.js`                   | session-gated `/api/agent-config`                         |
+| Shim      | `examples/web-app-agent/agent/mcp-shim.js`           | manifest → MCP tools; calls → `/bridge/call`              |
+| Front end | `public/agent/device-thread.js`                      | per-visitor thread identity (16-hex)                      |
+| Front end | `public/agent/commands.js`                           | **the command registry — the file you write**             |
+| Front end | `public/agent/bridge-mount.js`                       | wires the cumulus browser client to your registry         |
+| Front end | `public/agent/chat-client.js`                        | SSE chat against `/api/thread/:name/message`              |
+| Front end | `public/agent/panel.js`, `panel.css`                 | chat window + home bar                                    |
+| Front end | `public/app.js` (`window.HostApp`)                   | the adapter commands act through — never the DOM          |
+
+Two pieces described in this guide are **not** in the starter kit, to keep it small: the selection/right-click feedback composer (§4.6) and a rich markdown renderer with entity chips. Both are additive — add them once the core loop works.