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

@luckydraw/cumulus 0.31.65 → 1.0.0

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 (60) hide show

package/CHANGELOG.md +6 -555
package/LICENSE +150 -0
package/README.md +161 -17
package/dist/gateway/adapters/webchat.d.ts +2 -0
package/dist/gateway/adapters/webchat.d.ts.map +1 -1
package/dist/gateway/adapters/webchat.js +22 -2
package/dist/gateway/adapters/webchat.js.map +1 -1
package/dist/gateway/config.d.ts +17 -2
package/dist/gateway/config.d.ts.map +1 -1
package/dist/gateway/config.js +10 -3
package/dist/gateway/config.js.map +1 -1
package/dist/gateway/daemon.d.ts +3 -1
package/dist/gateway/daemon.d.ts.map +1 -1
package/dist/gateway/daemon.js +128 -39
package/dist/gateway/daemon.js.map +1 -1
package/dist/gateway/namespaces.d.ts +34 -0
package/dist/gateway/namespaces.d.ts.map +1 -1
package/dist/gateway/namespaces.js +58 -0
package/dist/gateway/namespaces.js.map +1 -1
package/dist/gateway/server.d.ts +8 -0
package/dist/gateway/server.d.ts.map +1 -1
package/dist/gateway/server.js +150 -41
package/dist/gateway/server.js.map +1 -1
package/dist/gateway/setup.d.ts +32 -0
package/dist/gateway/setup.d.ts.map +1 -1
package/dist/gateway/setup.js +23 -3
package/dist/gateway/setup.js.map +1 -1
package/dist/gateway/static/widget.js +897 -611
package/dist/lib/gateway.d.ts +30 -8
package/dist/lib/gateway.d.ts.map +1 -1
package/dist/lib/gateway.js +36 -11
package/dist/lib/gateway.js.map +1 -1
package/dist/lib/history.d.ts +22 -0
package/dist/lib/history.d.ts.map +1 -1
package/dist/lib/history.js +59 -21
package/dist/lib/history.js.map +1 -1
package/dist/lib/huggingface-provider.d.ts.map +1 -1
package/dist/lib/huggingface-provider.js +11 -3
package/dist/lib/huggingface-provider.js.map +1 -1
package/dist/lib/license.d.ts +76 -0
package/dist/lib/license.d.ts.map +1 -0
package/dist/lib/license.js +141 -0
package/dist/lib/license.js.map +1 -0
package/docs/agentic-harness-primer.md +283 -0
package/docs/conditional-continuation.md +167 -0
package/docs/web-app-agent-guide.md +520 -0
package/examples/web-app-agent/README.md +187 -0
package/examples/web-app-agent/agent/mcp-shim.js +105 -0
package/examples/web-app-agent/gateway.config.example.json +52 -0
package/examples/web-app-agent/package.json +13 -0
package/examples/web-app-agent/public/agent/bridge-mount.js +75 -0
package/examples/web-app-agent/public/agent/chat-client.js +104 -0
package/examples/web-app-agent/public/agent/commands.js +250 -0
package/examples/web-app-agent/public/agent/device-thread.js +48 -0
package/examples/web-app-agent/public/agent/panel.css +107 -0
package/examples/web-app-agent/public/agent/panel.js +369 -0
package/examples/web-app-agent/public/app.js +250 -0
package/examples/web-app-agent/public/index.html +111 -0
package/examples/web-app-agent/server.js +242 -0
package/package.json +7 -3

package/examples/web-app-agent/public/index.html ADDED Viewed

@@ -0,0 +1,111 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Demo Notes — cumulus web-app agent</title>
+<style>
+  /* The six variables the agent panel themes itself from. Define these and
+     panel.css needs no edits. */
+  :root {
+    --panel:  #16181d;
+    --panel2: #1e2128;
+    --panel3: #272b34;
+    --line:   #333844;
+    --text:   #e6e8ee;
+    --muted:  #8a91a3;
+    --accent: #5b8cff;
+  }
+  @media (prefers-color-scheme: light) {
+    :root {
+      --panel: #ffffff; --panel2: #f4f5f8; --panel3: #e9ebf0;
+      --line: #d8dbe3; --text: #1b1e25; --muted: #6b7280; --accent: #3b6fe0;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 32px 20px 160px;
+    background: var(--panel); color: var(--text);
+    font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif;
+  }
+  main { max-width: 620px; margin: 0 auto; }
+  h1 { font-size: 20px; margin: 0 0 4px; }
+  .sub { color: var(--muted); font-size: 13px; margin: 0 0 24px; }
+  input, button, textarea { font: inherit; }
+  .field {
+    width: 100%; padding: 9px 12px; border-radius: 9px;
+    background: var(--panel2); border: 1px solid var(--line); color: var(--text); outline: none;
+  }
+  .field:focus { border-color: var(--accent); }
+  .btn {
+    padding: 9px 16px; border-radius: 9px; cursor: pointer;
+    background: var(--accent); color: #fff; border: none;
+  }
+  .btn.ghost { background: var(--panel3); color: var(--text); border: 1px solid var(--line); }
+  .row { display: flex; gap: 8px; margin-bottom: 14px; }
+  .row .field { flex: 1; }
+  ul.notes { list-style: none; padding: 0; margin: 0; }
+  ul.notes li {
+    display: flex; align-items: center; gap: 10px;
+    padding: 10px 12px; margin-bottom: 6px;
+    background: var(--panel2); border: 1px solid var(--line); border-radius: 9px;
+  }
+  ul.notes li.done .text { color: var(--muted); text-decoration: line-through; }
+  ul.notes .text { flex: 1; }
+  ul.notes .id { color: var(--muted); font-size: 12px; font-variant-numeric: tabular-nums; }
+  .empty { color: var(--muted); padding: 18px 2px; }
+  #login { max-width: 300px; margin: 60px auto; }
+  #app[hidden], #login[hidden] { display: none; }
+  .err { color: #f2665e; font-size: 13px; min-height: 18px; }
+  .topbar { display: flex; align-items: baseline; justify-content: space-between; }
+  .link { background: none; border: none; color: var(--muted); cursor: pointer; text-decoration: underline; padding: 0; }
+</style>
+</head>
+<body>
+<section id="login">
+  <h1>Demo Notes</h1>
+  <p class="sub">Sign in to load the assistant. Default password: <code>demo</code></p>
+  <div class="row">
+    <input id="password" class="field" type="password" placeholder="Password" data-testid="login-password" autocomplete="current-password">
+    <button id="login-submit" class="btn" data-testid="login-submit">Sign in</button>
+  </div>
+  <div id="login-error" class="err" data-testid="login-error"></div>
+</section>
+<main id="app" hidden>
+  <div class="topbar">
+    <div>
+      <h1>Demo Notes</h1>
+      <p class="sub">The assistant at the bottom can read this list and change it.</p>
+    </div>
+    <button id="logout" class="link" data-testid="logout">Sign out</button>
+  </div>
+  <div class="row">
+    <input id="new-note" class="field" placeholder="Add a note…" data-testid="note-input">
+    <button id="add-note" class="btn" data-testid="note-add">Add</button>
+  </div>
+  <div class="row">
+    <input id="filter" class="field" placeholder="Filter…" data-testid="filter-input">
+    <button id="clear-filter" class="btn ghost" data-testid="filter-clear">Clear</button>
+  </div>
+  <ul class="notes" id="note-list" data-testid="note-list" data-loading="false"></ul>
+</main>
+<!-- Load order matters: the registry and its dependencies must exist before
+     bridge-mount runs. bridge-mount is a module (it imports the cumulus
+     BridgeClient), so it is deferred automatically. -->
+<script src="/app.js"></script>
+<script src="/agent/device-thread.js"></script>
+<script src="/agent/commands.js"></script>
+<script src="/agent/chat-client.js"></script>
+<script src="/agent/panel.js"></script>
+<script type="module" src="/agent/bridge-mount.js"></script>
+</body>
+</html>

package/examples/web-app-agent/server.js ADDED Viewed

@@ -0,0 +1,242 @@
+// Serving layer for the demo app.
+//
+// The only part of this file that matters for the agent integration is
+// GET /api/agent-config: the scoped gateway key is handed ONLY to an
+// authenticated session, so it never appears in the static page. That is the
+// difference between "anyone who views source can talk to your gateway" and
+// "only your logged-in users can".
+//
+// Everything else here is a deliberately boring static file server so the kit
+// runs with zero dependencies. Your real app already has this part.
+//
+// Env (same names the MCP shim uses — one vocabulary across the kit):
+//   PORT              default 8199
+//   APP_PASSWORD      default "demo" — the app's own login
+//   GATEWAY_API_KEY   scoped cumulus key (namespace "demoapp"). Absent =>
+//                     /api/agent-config 404s and the app runs agent-dark.
+//   GATEWAY_ORIGIN    REQUIRED when GATEWAY_API_KEY is set. There is no default
+//                     on purpose: whatever is listening on the usual gateway
+//                     port is usually a REAL gateway, so a mistyped variable
+//                     would silently point a demo app at production instead
+//                     of failing.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC = path.join(ROOT, 'public');
+/* ---- env, checked loudly --------------------------------------------------
+   An unread environment variable is silent by nature, and the value most
+   likely to be mistyped here is the gateway origin — whose old default was a
+   live gateway. So: names that are NOT read but are plausible mistakes for
+   ones that are get named explicitly and refuse to start. */
+const ENV_ALIASES = {
+  AGENT_GATEWAY_ORIGIN: 'GATEWAY_ORIGIN',
+  AGENT_GATEWAY_URL: 'GATEWAY_ORIGIN',
+  GATEWAY_URL: 'GATEWAY_ORIGIN',
+  CUMULUS_GATEWAY_URL: 'GATEWAY_ORIGIN',
+  AGENT_API_KEY: 'GATEWAY_API_KEY',
+  CUMULUS_API_KEY: 'GATEWAY_API_KEY',
+  API_KEY: 'GATEWAY_API_KEY',
+  DEMO_PASSWORD: 'APP_PASSWORD',
+  PASSWORD: 'APP_PASSWORD',
+};
+function checkEnv(env) {
+  const errors = [];
+  for (const [wrong, right] of Object.entries(ENV_ALIASES)) {
+    if (env[wrong] !== undefined && env[right] === undefined) {
+      errors.push(`${wrong} is not read by this server. Use ${right}.`);
+    }
+  }
+  if (env.GATEWAY_API_KEY && !env.GATEWAY_ORIGIN) {
+    errors.push(
+      'GATEWAY_API_KEY is set but GATEWAY_ORIGIN is not. Set it explicitly ' +
+        '(e.g. GATEWAY_ORIGIN=http://127.0.0.1:8080) — there is no default, because ' +
+        'guessing one would point this app at whatever gateway happens to be running.'
+    );
+  }
+  if (env.GATEWAY_ORIGIN) {
+    try {
+      const u = new URL(env.GATEWAY_ORIGIN);
+      if (!/^https?:$/.test(u.protocol)) throw new Error('not http(s)');
+    } catch {
+      errors.push(`GATEWAY_ORIGIN is not a valid http(s) origin: ${env.GATEWAY_ORIGIN}`);
+    }
+  }
+  return errors;
+}
+const envErrors = checkEnv(process.env);
+if (envErrors.length > 0) {
+  for (const e of envErrors) console.error(`[env] ${e}`);
+  process.exit(1);
+}
+const PORT = Number(process.env.PORT || 8199);
+const PASSWORD = process.env.APP_PASSWORD || 'demo';
+const API_KEY = process.env.GATEWAY_API_KEY || '';
+const GATEWAY_ORIGIN = process.env.GATEWAY_ORIGIN || '';
+/* ---- where the browser's BridgeClient comes from --------------------------
+   Cumulus owns the bridge client (Rule #8: one implementation). We do NOT
+   vendor a copy into this example — we serve the compiled files straight out
+   of the package, so this kit can never drift from the gateway it talks to.
+   `dist/gateway/bridge/*.js` is plain ESM with no Node imports, so a browser
+   loads it directly. */
+function resolveBridgeDir() {
+  const inRepo = path.join(ROOT, '..', '..', 'dist', 'gateway', 'bridge');
+  if (fs.existsSync(path.join(inRepo, 'client.js'))) return inRepo;
+  try {
+    const require = createRequire(import.meta.url);
+    return path.dirname(require.resolve('@luckydraw/cumulus/dist/gateway/bridge/client.js'));
+  } catch {
+    return null;
+  }
+}
+const BRIDGE_DIR = resolveBridgeDir();
+/* ---- sessions (in-memory; your app has real ones) ------------------------ */
+const sessions = new Set();
+function sessionOf(req) {
+  const raw = req.headers.cookie || '';
+  const match = raw.match(/(?:^|;\s*)sid=([a-f0-9]{32})/);
+  return match && sessions.has(match[1]) ? match[1] : null;
+}
+/* ---- helpers ------------------------------------------------------------- */
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+};
+function json(res, status, body, headers = {}) {
+  res.writeHead(status, { 'content-type': MIME['.json'], ...headers });
+  res.end(JSON.stringify(body));
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    req.on('data', c => {
+      raw += c;
+      if (raw.length > 1e5) reject(new Error('body too large'));
+    });
+    req.on('end', () => {
+      try {
+        resolve(raw ? JSON.parse(raw) : {});
+      } catch {
+        reject(new Error('invalid JSON'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+function sendFile(res, file) {
+  fs.readFile(file, (err, buf) => {
+    if (err) {
+      res.writeHead(404);
+      return res.end('not found');
+    }
+    res.writeHead(200, { 'content-type': MIME[path.extname(file)] || 'application/octet-stream' });
+    res.end(buf);
+  });
+}
+/* ---- routes -------------------------------------------------------------- */
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, 'http://localhost');
+  const p = url.pathname;
+  if (req.method === 'POST' && p === '/api/login') {
+    let body;
+    try {
+      body = await readBody(req);
+    } catch (e) {
+      return json(res, 400, { error: e.message });
+    }
+    if (body.password !== PASSWORD) return json(res, 401, { error: 'wrong password' });
+    const sid = crypto.randomBytes(16).toString('hex');
+    sessions.add(sid);
+    return json(
+      res,
+      200,
+      { ok: true },
+      { 'set-cookie': `sid=${sid}; HttpOnly; SameSite=Lax; Path=/` }
+    );
+  }
+  if (req.method === 'POST' && p === '/api/logout') {
+    const sid = sessionOf(req);
+    if (sid) sessions.delete(sid);
+    return json(res, 200, { ok: true }, { 'set-cookie': 'sid=; Max-Age=0; Path=/' });
+  }
+  // Session probe. "Am I signed in?" is a different question from "give me the
+  // key", so it answers 200 either way. Asking the key endpoint instead would
+  // make every logged-out page load emit a 401 in the browser console — correct
+  // behaviour, alarming signal.
+  if (req.method === 'GET' && p === '/api/session') {
+    return json(res, 200, { authenticated: !!sessionOf(req) });
+  }
+  // THE ONE THAT MATTERS. The scoped key reaches only authenticated sessions.
+  // 404 when no key is configured, so the front end simply stays agent-dark
+  // instead of erroring.
+  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',
+      // Base name only. device-thread.js appends the per-visitor suffix in the
+      // browser, so the full thread name never travels from server to client.
+      THREAD_ID: 'demoapp-v',
+      API_KEY,
+    });
+  }
+  // Bridge client, served from the cumulus package rather than a local copy.
+  if (p.startsWith('/agent/bridge-client/')) {
+    const name = path.basename(p);
+    if (!BRIDGE_DIR || !/^(client|protocol)\.js$/.test(name)) {
+      res.writeHead(404);
+      return res.end('bridge client unavailable — build cumulus or npm i @luckydraw/cumulus');
+    }
+    return sendFile(res, path.join(BRIDGE_DIR, name));
+  }
+  if (req.method === 'GET') {
+    const rel = p === '/' ? 'index.html' : p.replace(/^\/+/, '');
+    const file = path.join(PUBLIC, rel);
+    if (!file.startsWith(PUBLIC)) {
+      res.writeHead(403);
+      return res.end('forbidden');
+    }
+    return sendFile(res, file);
+  }
+  res.writeHead(404);
+  res.end('not found');
+});
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`demo app: http://127.0.0.1:${PORT}  (password: ${PASSWORD})`);
+  console.log(
+    `bridge client: ${BRIDGE_DIR ?? 'NOT FOUND — run `npm run build` in the cumulus repo'}`
+  );
+  console.log(
+    API_KEY
+      ? `agent: enabled -> ${GATEWAY_ORIGIN}`
+      : 'agent: disabled (set GATEWAY_API_KEY + GATEWAY_ORIGIN)'
+  );
+});

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "0.31.65",
+  "version": "1.0.0",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,10 @@
   },
   "files": [
     "dist/",
+    "examples/",
+    "docs/web-app-agent-guide.md",
+    "docs/agentic-harness-primer.md",
+    "docs/conditional-continuation.md",
     "package.json",
     "CHANGELOG.md"
   ],
@@ -53,8 +57,8 @@
     "context",
     "mcp"
   ],
-  "author": "",
-  "license": "MIT",
+  "author": "Lucky Draw LLC",
+  "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {
     "access": "public"
   },