@luckydraw/cumulus 0.31.65 → 0.31.66

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.31.66
+
+- New README guide for building persistent web-app agents: gateway setup, front-end integration, and the security model.
+
 ## v0.31.65
 
 You've hit your weekly limit · resets Aug 6, 9pm (UTC)

package/README.md

@@ -9,6 +9,7 @@ Originally a CLI wrapper for Claude, Cumulus has grown into a full gateway platf
 - **Gateway daemon** (`cumulus-gateway`) — HTTP + WebSocket server with per-thread conversations, streaming responses, and an admin API.
 - **Web chat widget** — embeddable `/chat` interface with voice mode, push notifications, file uploads with progress, and rich [blex block](https://www.npmjs.com/package/@luckydraw/blex) rendering (tables, forms, charts, kanban, diagrams).
 - **Channel adapters** — Slack and Discord bots, inbound email webhooks (Resend), and generic HTTP webhooks — all injecting into the same thread model.
+- **Persistent web-app agents** — embed an agent into any web app that can _drive its UI_, answer questions about its data, and remember every conversation per visitor. See [Persistent web-app agents](#persistent-web-app-agents).
 - **Inter-agent messaging** — threads can talk to each other via `send_to_agent`, with support for CC/BCC visibility.
 - **Per-thread model selection** — Claude (via CLI) or any HuggingFace model (GLM-5, Kimi-K2.5, Qwen3, etc.) with tool calling.
 - **Scheduled triggers, email, push, media serving** — built-in MCP tools so agents can send emails, schedule themselves, notify you, and upload files.
@@ -207,6 +208,139 @@ cumulus-gateway rollback           # restores the previous version
 
 The widget's top bar also shows an "Update available" indicator (with a manual ↻ check button) when a new version lands on npm.
 
+## Persistent web-app agents
+
+Cumulus can embed a persistent agent into any web app — one that **drives the app's UI**, **answers questions about the app and its data**, and **remembers every conversation per visitor**. No fork of the gateway, no per-app backend beyond a static file server.
+
+Requires `>= 0.31.41`.
+
+### How it works
+
+```
+ Browser tab (your app)                        cumulus gateway
+┌───────────────────────────────┐             ┌──────────────────────────────────┐
+│ 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       │   └─ model turn per message      │
+│     feedback capture          │             │        └─ MCP shim ──────────────┼──┐
+└───────────────────────────────┘             └──────────────────────────────────┘  │
+                                                    ▲                               │
+                                              POST /bridge/call ◀───────────────────┘
+                                              (agent tool call → executes in the tab)
+```
+
+Three moving parts:
+
+1. **The gateway** — owns history, RAG retrieval, and prompt assembly, and runs a model turn per message. One config block per app; no code changes.
+2. **Your 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.
+3. **An MCP shim** — a small stdio script the gateway spawns per turn. It fetches the app's command manifest and exposes each command as a model-callable tool; calls are forwarded to `POST /bridge/call`, which dispatches them 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 through the app's own actions (so guards, routing, and notifications all still fire) → the result flows back to the model.
+
+Because the manifest is re-fetched every turn, **shipping a new UI command makes it agent-callable with zero gateway or backend changes.**
+
+### Key concepts
+
+| Concept                            | What it is                                                                                                                                             |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Namespace**                      | A config block grouping an app's threads (`myapp-*`), scoping its API key, and carrying its per-app settings (proxy, MCP servers).                     |
+| **Base thread** (`myapp`)          | Your own management thread for the app, visible only to your admin key. Never used by visitors — but it _is_ the config template they inherit.         |
+| **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: the tab registers its command manifest; the gateway dispatches agent tool calls into the tab.                               |
+| **Command registry**               | The app-side catalog of typed commands (`{ name, description, params, risk, execute }`) — one capability surface shared by 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 is the per-visitor secret. |
+
+### Gateway setup
+
+One edit to `~/.cumulus/gateway.config.json` (annotated below; the real file is strict JSON):
+
+```jsonc
+{
+  "bridge": { "enabled": true }, // global, default off — every bridge surface is inert until enabled
+
+  "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 real
+      // thread name (myapp-<deviceId>) in both args and env.
+      "extraMcpServers": {
+        "myapp-tools": {
+          "command": "node",
+          "args": ["/path/to/myapp/mcp-shim.js"],
+          "env": {
+            "GATEWAY_URL": "http://127.0.0.1:8090",
+            "GATEWAY_API_KEY": "sk-myapp-<same-scoped-key>",
+            "BRIDGE_THREAD": "{thread}",
+          },
+        },
+      },
+    },
+  ],
+}
+```
+
+Then give visitor threads their persona and working directory via the base thread config, `~/.cumulus/threads/myapp.config.json`:
+
+```json
+{
+  "projectDir": "/home/you/projects/myapp",
+  "model": "claude",
+  "effort": "high",
+  "alwaysInclude": ["docs/myapp-system-prompt.md"]
+}
+```
+
+A turn on `myapp-a3f8c2d1` with no config of its own inherits this by prefix-fallback. Writes stay exact, so a visitor session can never mutate the base. `alwaysInclude` is where the app's product knowledge and persona live.
+
+### Front-end integration
+
+Your app ships four small pieces (all vanilla-JS-able, no framework required):
+
+| Piece                | Job                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **Device thread id** | Mint `myapp-<random hex>` once, persist in `localStorage`. This _is_ the visitor's identity — use 16+ hex chars of entropy.      |
+| **Command registry** | Expose `window.MyAppAgent` with typed commands. Include a `describeView`-style command so the agent can read the current screen. |
+| **Bridge mount**     | Open `wss://<gateway>/bridge`, register the manifest, execute inbound `call` frames against the registry.                        |
+| **Chat client**      | `POST /api/thread/<thread>/message` and render the SSE stream. Mark risky commands so they route through a confirm step.         |
+
+Serve the gateway URL and scoped key to the browser at request time (e.g. `window.__APP_AGENT_CONFIG__` injected by your serving layer from an env var) — never commit the key into the repo.
+
+### Security model
+
+The browser must hold a credential — the bridge sends its key inside a WebSocket frame, which no reverse proxy can inject. So the model is _confinement_, not concealment:
+
+- A **scoped key** can read/write only `myapp-*` threads; everything else is `403`.
+- A scoped key **enumerates nothing** — `/api/threads`, `/api/agents`, and the dashboard all return empty. Reaching another visitor's thread means guessing its random name.
+- The **thread name is the per-visitor secret**, the same capability-URL pattern as content-hashed `/media/*` filenames, one notch stricter (unguessable _and_ key-gated).
+
+Mint fresh device ids with at least 16 hex characters; 8 is too thin against a determined brute-forcer.
+
+### Checklist
+
+1. Enable `bridge` and add the namespace + scoped key to the gateway config; reload.
+2. Create the base thread config with `projectDir`, `model`, and the `alwaysInclude` system-prompt document.
+3. Verify the scoped key: in-namespace `200`, out-of-namespace `403`, `/api/threads` empty.
+4. Inject the gateway URL + scoped key into the page at serve time.
+5. Ship the device thread id, command registry, bridge mount, and chat client.
+6. Point the namespace's `extraMcpServers` shim at your manifest endpoint.
+7. End-to-end check: ask the agent a question about the current screen, then ask it to navigate.
+
 ## Classic CLI mode
 
 The original RLM chat loop still works. Great for quick terminal work without running the gateway.
@@ -291,28 +425,19 @@ All `/api/*` routes require `X-API-Key: <key>` (from `apiKeys[]`).
 
 WebSocket (`/chat/ws`) carries the same semantics with streaming, interjection, `inject`, and voice-mode audio frames.
 
-## Development
+## Upgrading
 
 ```bash
-git clone https://github.com/soapko/cumulus
-cd cumulus
-npm install
-npm run build
-npm test            # vitest
-npm run lint
-npm run type-check
+npm install -g @luckydraw/cumulus@latest
+cumulus-gateway reload      # SIGHUP — drains active streams before restarting
 ```
 
-- **Build:** `dist/` compiled TypeScript plus static assets (widget HTML/CSS/JS, blex bundles).
-- **Tests:** vitest, 700+ tests covering agentic loop, retriever, adapters, scheduler, push.
-- **Deploy workflow:** bump version, `npm publish`, then `cumulus-gateway reload` on the host (SIGHUP drains active streams — see `docs/tasks/050-graceful-restart.md`).
+Or use the built-in updater (`cumulus-gateway update` / `rollback`), which does the same thing and keeps the previous version for a one-command rollback. See [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
 ## Background
 
 Cumulus implements the **Recursive Language Model** pattern: treat conversation history as an external environment the model queries programmatically, rather than stuffing everything into context. This enables reasoning over contexts 2+ orders of magnitude beyond the model's window, with graceful cost scaling.
 
-See `docs/` for task documents, ADRs, and implementation notes.
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "0.31.65",
+  "version": "0.31.66",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",