@luckydraw/cumulus 0.31.65 → 1.0.0

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

@@ -0,0 +1,187 @@
+# Web-App Agent — runnable starter kit
+
+A working web app with a persistent cumulus agent that can **see the screen** and
+**drive the app**. Every file here runs. Copy the `agent/` directories into your
+own app, replace one file, and you have the same thing.
+
+The full narrative version is [`docs/web-app-agent-guide.md`](../../docs/web-app-agent-guide.md).
+This is the code that guide describes.
+
+---
+
+## What you get
+
+|                                         |                                                                                              |
+| --------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **A persistent thread per visitor**     | The conversation outlives the tab, the session, and the deploy. Reload and it's still there. |
+| **The agent sees the live screen**      | A fresh `describeView` rides along with every turn — never a cached snapshot.                |
+| **The agent drives the app**            | Through a registry you define, calling your app's own actions — not the DOM.                 |
+| **A human gate on irreversible things** | `risk: "export"` commands stop for a confirm chip. The model cannot bypass it.               |
+| **Capability-scoped access**            | The app's key can touch its own namespace and cannot enumerate anything, anywhere.           |
+
+## Run it
+
+**If you installed cumulus from npm** (the usual case — the kit ships inside the
+package, already built):
+
+```bash
+cd "$(npm root -g)/@luckydraw/cumulus/examples/web-app-agent"
+GATEWAY_API_KEY=sk-demoapp-REPLACE-ME GATEWAY_ORIGIN=http://127.0.0.1:8080 node server.js
+# -> http://127.0.0.1:8199   password: demo   (override with APP_PASSWORD)
+```
+
+**If you have the cumulus git repo**, build it once first — the browser bridge
+client is served straight out of `dist/`, since this kit vendors no copy of it:
+
+```bash
+npm install && npm run build
+cd examples/web-app-agent
+GATEWAY_API_KEY=sk-demoapp-REPLACE-ME GATEWAY_ORIGIN=http://127.0.0.1:8080 node server.js
+```
+
+Copy the whole directory somewhere writable before you start editing it — a kit
+inside `node_modules` is replaced on the next upgrade.
+
+Without `GATEWAY_API_KEY` the app still runs — it just has no assistant. That is
+the correct degraded state, and it's worth keeping in your own app.
+
+`GATEWAY_ORIGIN` has no default and is required whenever the key is set. That's
+deliberate: a defaulting app plus a mistyped variable is an app that quietly
+talks to whatever gateway happens to be listening on the usual port — a failure
+that looks like success. The server also refuses to start on near-miss names
+(`AGENT_API_KEY`, `GATEWAY_URL`, `DEMO_PASSWORD`, …), naming the variable it
+actually reads.
+
+For the assistant to actually answer you also need a gateway: merge
+[`gateway.config.example.json`](gateway.config.example.json) into
+`~/.cumulus/gateway.config.json`, then reload it
+(`sudo systemctl reload cumulus-gateway`, or `cumulus-gateway reload` if you
+manage it yourself — never `systemctl restart`, which kills in-flight turns).
+
+## What's here
+
+```
+server.js                     your serving layer's one job: hand the scoped key
+                              to authenticated sessions only
+agent/mcp-shim.js             stdio MCP server the gateway spawns per turn;
+                              turns your registry into the model's tools
+gateway.config.example.json   the namespace, the scoped key, the shim
+
+public/index.html             the demo app
+public/app.js                 the demo app + window.HostApp (the adapter)
+
+public/agent/commands.js      ← THE FILE YOU WRITE. Your capability surface.
+public/agent/device-thread.js per-visitor thread identity
+public/agent/bridge-mount.js  wires the bridge client to your registry
+public/agent/chat-client.js   speaks the gateway's chat API (SSE)
+public/agent/panel.js         the chat UI
+public/agent/panel.css        themed from six CSS variables
+```
+
+Copy all of `public/agent/` and `agent/mcp-shim.js` as-is. Then **rewrite
+`commands.js`** against your own app and delete the demo's notes commands.
+That's the whole port.
+
+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.
+
+---
+
+## The five things that are easy to get wrong
+
+### 1. The thread name is the capability
+
+A scoped key cannot list threads — anywhere, including its own namespace. So
+knowing a thread's name is what grants access to that conversation. Which means:
+
+- Mint the per-visitor suffix **in the browser** (`device-thread.js`), so the
+  full name never travels server → client where it could be logged or cached.
+- Use **at least 16 hex characters** (64 bits). 8 is brute-forceable against a
+  live gateway.
+
+### 2. Never ship the key in the page
+
+`server.js` serves the scoped key from `GET /api/agent-config`, gated on a
+session. If you inject it into static HTML instead, anyone who views source can
+talk to your gateway as your app.
+
+### 3. Commands act through an adapter, not the DOM
+
+`window.HostApp` is the app's own actions exposed as functions. Commands call
+those. That's why validation, persistence, and re-render work identically
+whether a human or the model is driving — and why your commands survive a UI
+rewrite.
+
+### 4. Descriptions are the interface
+
+The model decides what to call based entirely on the `description` string.
+Write for a reader who cannot see your UI, and say what a command is _for_, not
+just what it does. Compare:
+
+```js
+description: 'Sets the filter.'; // useless
+description: 'Set the on-screen filter so the human sees a subset. ' +
+  'Use it to SHOW someone something, not to look something up ' +
+  'yourself — for that, use notes.list, which changes nothing.';
+```
+
+The second one prevents a whole class of annoying behaviour.
+
+### 5. Pick the risk tier honestly
+
+| tier      | meaning                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `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.
+
+---
+
+## How a turn actually works
+
+```
+visitor types  →  panel.js sends the message to the gateway
+                  AND pushes a fresh describeView over the bridge
+                          ↓
+gateway assembles the turn (history + RAG + your describeView)
+                          ↓
+model calls a tool  →  mcp-shim.js  →  POST /bridge/call
+                          ↓
+gateway → open WebSocket → the visitor's tab → your registry → HostApp
+                          ↓
+result travels back the same way; model composes an answer; SSE streams it
+```
+
+Two consequences worth internalising:
+
+- **The tab must be open** for tool calls to work. With no tab, the gateway
+  answers `{ ok: false }` and the model reports an honest failure instead of
+  hanging.
+- **The tool list is live.** Every `tools/list` re-fetches your manifest, so
+  capabilities appear and disappear as your app changes — no gateway restart,
+  no redeploy.
+
+## Demo mode
+
+An unlicensed gateway caps each namespace at **5 distinct visitor threads**.
+Existing threads keep working; only minting a _new_ one is refused, with `402`
+and a contact address. `chat-client.js` surfaces that as a readable message
+rather than a generic failure.
+
+That's plenty to evaluate with and hits immediately in production, which is the
+point. See [`LICENSE`](../../LICENSE).
+
+## Optional extras
+
+Not in this kit, but in the guide:
+
+- **Selection as context** — let a visitor highlight part of the page and ask
+  about it (guide §4.6).
+- **Executor proxy** — reverse-proxy your app's own API through the gateway so
+  the tab talks to a single origin (`executorProxy` in the example config).

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

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

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

@@ -0,0 +1,52 @@
+{
+  "_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."
+  ],
+
+  "bridge": { "enabled": true },
+
+  "namespaces": [
+    {
+      "name": "demoapp",
+      "label": "Demo App",
+
+      "_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."
+      ],
+      "apiKeys": ["sk-demoapp-REPLACE-ME"],
+
+      "_extraMcpServers": [
+        "Spawned per turn for demoapp-* threads only. {thread} is substituted with the",
+        "calling thread's name, so one shim serves every visitor. Use an absolute path",
+        "to the shim — the gateway spawns it with the thread's own cwd."
+      ],
+      "extraMcpServers": {
+        "demoapp-tools": {
+          "command": "node",
+          "args": ["/absolute/path/to/examples/web-app-agent/agent/mcp-shim.js"],
+          "env": {
+            "GATEWAY_ORIGIN": "http://127.0.0.1:8080",
+            "GATEWAY_API_KEY": "sk-demoapp-REPLACE-ME",
+            "BRIDGE_THREAD": "{thread}",
+            "MCP_SERVER_NAME": "demoapp-tools"
+          }
+        }
+      },
+
+      "_executorProxy": [
+        "OPTIONAL. Only if your app has a backend the agent should reach directly.",
+        "Lets the tab talk to a single origin (the gateway) instead of two.",
+        "Delete this block if you don't need it — the demo does not."
+      ],
+      "executorProxy": {
+        "origin": "http://127.0.0.1:8199",
+        "pathPrefixes": ["/api/public"]
+      }
+    }
+  ]
+}

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

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

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

@@ -0,0 +1,75 @@
+/* Bridge mount — wires the cumulus-owned BridgeClient to this app's registry.
+
+   The BridgeClient is served straight out of the cumulus package (see
+   server.js). Don't fork it: it is the seam contract, and the gateway on the
+   other end is versioned with it.
+
+   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. */
+import { BridgeClient } from './bridge-client/client.js';
+
+let bridge = null;
+
+window.AgentStart = function () {
+  if (bridge) return; // already live this page-load
+  const cfg = window.__AGENT_CONFIG__;
+  if (!cfg || !cfg.API_KEY || !window.AgentRegistry || !window.agentDeviceThread) return;
+
+  window.agentDeviceThread(cfg); // THREAD_ID -> demoapp-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';
+    document.head.appendChild(link);
+  }
+
+  window.AgentChat.init(cfg);
+  window.AgentPanel.init();
+
+  bridge = new BridgeClient({
+    url: cfg.BRIDGE_URL,
+    thread: cfg.THREAD_ID,
+    apiKey: cfg.API_KEY,
+
+    registry: {
+      manifest: window.AgentRegistry.manifest(),
+      execute: (command, params) => Promise.resolve(window.AgentRegistry.call(command, params)),
+    },
+
+    // Recomputed on EVERY sendContext, never cached — this is what keeps the
+    // agent looking at the same screen the human is.
+    describeView: () => {
+      const r = window.AgentRegistry.callNow('app.describeView');
+      return r.ok ? r.data : { error: r.summary };
+    },
+
+    // Export-tier commands land here instead of executing. Returning without
+    // calling accept() or decline() means the gateway times the call out —
+    // which is the safe outcome.
+    onConfirmRequest: req => window.AgentPanel.confirm(req),
+
+    onStateChange: s => {
+      console.info('[agent] bridge ' + s);
+      window.AgentPanel.setState(s);
+    },
+  });
+
+  bridge.connect();
+  window.AgentBridge = bridge;
+};
+
+window.AgentStop = function () {
+  if (!bridge) return;
+  bridge.close();
+  bridge = null;
+  window.AgentBridge = null;
+  if (window.AgentPanel) window.AgentPanel.reset();
+};
+
+// The config may already be present if the session check finished before this
+// module executed.
+if (window.__AGENT_CONFIG__) window.AgentStart();

package/examples/web-app-agent/public/agent/chat-client.js

@@ -0,0 +1,104 @@
+/* Gateway chat client. Speaks the cumulus HTTP API:
+
+     POST /api/thread/:name/message   ->  SSE stream: token | segment | error | done
+     GET  /api/thread/:name/history   ->  prior turns, for reload survival
+
+   Both authenticate with the scoped key in the X-API-Key header. Note there is
+   no thread-creation call: posting to a thread that does not exist creates it.
+   That is exactly what the demo-mode visitor cap gates, so a 402 here means the
+   gateway is unlicensed and at capacity.
+
+   window.AgentChat = {
+     init(cfg) -> boolean, live,
+     send(message, handlers) -> { cancel() }
+       handlers: onToken(text), onSegment(seg), onError(err), onDone(payload)
+     history() -> Promise<array>    ([] when unavailable)
+   } */
+(function () {
+  'use strict';
+  var origin = null,
+    thread = null,
+    apiKey = null;
+
+  async function streamSSE(resp, handlers, cancelled) {
+    var reader = resp.body.getReader();
+    var decoder = new TextDecoder();
+    var buf = '';
+    while (true) {
+      var chunk = await reader.read();
+      if (chunk.done || cancelled.is) break;
+      buf += decoder.decode(chunk.value, { stream: true });
+      var idx;
+      while ((idx = buf.indexOf('\n\n')) >= 0) {
+        var raw = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        var event = 'message',
+          data = '';
+        raw.split('\n').forEach(function (line) {
+          if (line.indexOf('event:') === 0) event = line.slice(6).trim();
+          else if (line.indexOf('data:') === 0) data += line.slice(5).trim();
+        });
+        if (!data) continue;
+        var payload;
+        try {
+          payload = JSON.parse(data);
+        } catch {
+          continue;
+        }
+        if (event === 'token' && handlers.onToken) handlers.onToken(payload.text || '');
+        else if (event === 'segment' && handlers.onSegment) handlers.onSegment(payload);
+        else if (event === 'error' && handlers.onError) handlers.onError(payload);
+        else if (event === 'done' && handlers.onDone) handlers.onDone(payload);
+      }
+    }
+  }
+
+  window.AgentChat = {
+    live: false,
+
+    init: function (cfg) {
+      origin = cfg.GATEWAY_URL;
+      thread = cfg.THREAD_ID;
+      apiKey = cfg.API_KEY;
+      this.live = !!(origin && thread && apiKey);
+      return this.live;
+    },
+
+    send: function (message, handlers) {
+      var cancelled = { is: false };
+      fetch(origin + '/api/thread/' + encodeURIComponent(thread) + '/message', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+        body: JSON.stringify({ message: message }),
+      })
+        .then(function (resp) {
+          if (resp.status === 402)
+            throw new Error('Gateway is in demo mode and at its visitor limit');
+          if (!resp.ok) throw new Error('Gateway returned ' + resp.status);
+          return streamSSE(resp, handlers, cancelled);
+        })
+        .catch(function (err) {
+          if (!cancelled.is && handlers.onError)
+            handlers.onError({ error: String(err.message || err) });
+        });
+      return {
+        cancel: function () {
+          cancelled.is = true;
+        },
+      };
+    },
+
+    history: async function () {
+      try {
+        var resp = await fetch(origin + '/api/thread/' + encodeURIComponent(thread) + '/history', {
+          headers: { 'X-API-Key': apiKey },
+        });
+        if (!resp.ok) return [];
+        var j = await resp.json();
+        return Array.isArray(j) ? j : j.messages || j.items || [];
+      } catch {
+        return [];
+      }
+    },
+  };
+})();