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

@luckydraw/cumulus 0.31.66 → 1.0.1

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

Files changed (63) hide show

package/CHANGELOG.md +12 -556
package/LICENSE +150 -0
package/README.md +27 -8
package/dist/gateway/adapters/webchat.d.ts +15 -0
package/dist/gateway/adapters/webchat.d.ts.map +1 -1
package/dist/gateway/adapters/webchat.js +78 -5
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/blex-render.js +341 -0
package/dist/gateway/static/chat.html +1 -0
package/dist/gateway/static/widget.js +1009 -738
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 +559 -0
package/examples/web-app-agent/README.md +334 -0
package/examples/web-app-agent/agent/mcp-shim.js +105 -0
package/examples/web-app-agent/gateway.config.example.json +70 -0
package/examples/web-app-agent/package.json +13 -0
package/examples/web-app-agent/public/agent/blex-mount.js +136 -0
package/examples/web-app-agent/public/agent/bridge-mount.js +91 -0
package/examples/web-app-agent/public/agent/chat-client.js +104 -0
package/examples/web-app-agent/public/agent/commands.js +256 -0
package/examples/web-app-agent/public/agent/device-thread.js +48 -0
package/examples/web-app-agent/public/agent/panel.css +113 -0
package/examples/web-app-agent/public/agent/panel.js +392 -0
package/examples/web-app-agent/public/app.js +250 -0
package/examples/web-app-agent/public/index.html +126 -0
package/examples/web-app-agent/server.js +379 -0
package/package.json +7 -3

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

@@ -0,0 +1,126 @@
+<!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>
+<!-- Asset versions. server.js rewrites the empty map at serve time (stampHtml),
+     and stamps the src/href attributes below with the same hashes. The map
+     exists for assets that are loaded from inside JavaScript — panel.css and
+     the blex pair — because an HTML-level stamp cannot see a URL that only
+     appears in a script. Left as {} by a server that does not do the rewrite,
+     in which case agentAsset() returns URLs unchanged. -->
+<script>
+  window.__AGENT_ASSET_V = {};
+  window.agentAsset = function (url) {
+    var v = window.__AGENT_ASSET_V[url];
+    return v ? url + '?v=' + v : url;
+  };
+</script>
+<!-- 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/blex-mount.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,379 @@
+// 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();
+/* ---- where the browser's blex renderer comes from -------------------------
+   Same rule as the bridge client above, and for a sharper reason than symmetry.
+   The obvious alternative — point a <script> at GATEWAY_ORIGIN + '/blex.min.js'
+   — is only correct for an app 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/*` to
+   the gateway. There is no `/blex.min.js` on your hostname, so the cross-origin
+   recipe 404s and blex silently degrades to plain text — a failure that reads
+   like "my route is broken" rather than "my asset is missing". Serving the
+   assets ourselves is origin-agnostic and still not a vendored copy.
+   (Measured by @cdda, which hit exactly this.) */
+function resolveStaticDir() {
+  const inRepo = path.join(ROOT, '..', '..', 'dist', 'gateway', 'static');
+  if (fs.existsSync(path.join(inRepo, 'blex-render.js'))) return inRepo;
+  try {
+    const require = createRequire(import.meta.url);
+    return path.dirname(require.resolve('@luckydraw/cumulus/dist/gateway/static/blex-render.js'));
+  } catch {
+    return null;
+  }
+}
+const STATIC_DIR = resolveStaticDir();
+/* ---- asset versioning -----------------------------------------------------
+   Without this, a CDN in front of your app decides how long your agent surface
+   stays stale. Measured at a real Cloudflare edge: it overrides an origin's
+   `no-cache` with `max-age=14400`, so an edit to commands.js — the file you
+   change most — can take four hours to reach a browser, and the panel's files
+   expire on independent clocks, so a visitor can hold two files from DIFFERENT
+   deploys. `?v=<content hash>` makes the URL change when the bytes change,
+   which no cache policy can override.
+   Computed at SERVE time, not build time: this kit has no build step, and its
+   blex/bridge assets come out of the installed cumulus package, so a build-time
+   hash would describe the wrong bytes after `npm i`. */
+const assetStampCache = new Map();
+/** First 8 hex of sha1, cached and invalidated on mtime+size — so an edit is
+    picked up with no restart. undefined if the file cannot be read. */
+function assetVersion(file) {
+  if (!file) return undefined;
+  try {
+    const stat = fs.statSync(file);
+    const hit = assetStampCache.get(file);
+    if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.hash;
+    const hash = crypto.createHash('sha1').update(fs.readFileSync(file)).digest('hex').slice(0, 8);
+    assetStampCache.set(file, { hash, mtimeMs: stat.mtimeMs, size: stat.size });
+    return hash;
+  } catch {
+    return undefined;
+  }
+}
+/** URL path -> file on disk, or null if it is not an asset we serve. ONE owner
+    for this mapping: the routes below and the stamp both go through it, so a
+    URL can never be versioned as one file and served as another. The basename
+    allowlists are the whole traversal defence for the two directories outside
+    PUBLIC — do not loosen them to a prefix match. */
+function assetUrlToFile(pathname) {
+  if (pathname.startsWith('/agent/bridge-client/')) {
+    const name = path.basename(pathname);
+    if (!BRIDGE_DIR || !/^(client|protocol)\.js$/.test(name)) return null;
+    return path.join(BRIDGE_DIR, name);
+  }
+  // blex-chart.min.js is an OPT-IN companion global (blex.min.js inlines Chart.js
+  // and never fetches it). Nothing requests it today; it is allowlisted so an
+  // adopter who wants it can add one script tag instead of editing this server.
+  if (pathname.startsWith('/agent/blex/')) {
+    const name = path.basename(pathname);
+    if (!STATIC_DIR || !/^(blex\.min|blex-render|blex-chart\.min)\.js$/.test(name)) return null;
+    return path.join(STATIC_DIR, name);
+  }
+  const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
+  const file = path.join(PUBLIC, rel);
+  return file === PUBLIC || file.startsWith(PUBLIC + path.sep) ? file : null;
+}
+/* Assets loaded from INSIDE JavaScript — a <link> built at runtime, a script
+   element appended by blex-mount. An HTML-level stamp cannot see a URL that
+   only exists in JS, so these get their hashes through the map below instead.
+   (This is the "a loader that fetches its own dependencies must propagate the
+   version token" case, applied where it is actually true.) */
+const RUNTIME_LOADED = [
+  '/agent/panel.css',
+  '/agent/blex/blex.min.js',
+  '/agent/blex/blex-render.js',
+];
+const ASSET_MAP_MARKER = 'window.__AGENT_ASSET_V = {};';
+/** Stamp served HTML: `?v=` on every same-origin .js/.css src/href, plus the
+    version map for the runtime-loaded set. */
+function stampHtml(html) {
+  const stamped = html.replace(
+    /(\s(?:src|href)=")(\/[^"?#]+\.(?:js|css))(")/g,
+    (m, pre, url, post) => {
+      const v = assetVersion(assetUrlToFile(url));
+      return v ? `${pre}${url}?v=${v}${post}` : m;
+    }
+  );
+  const map = {};
+  for (const url of RUNTIME_LOADED) {
+    const v = assetVersion(assetUrlToFile(url));
+    if (v) map[url] = v;
+  }
+  return stamped.replace(ASSET_MAP_MARKER, `window.__AGENT_ASSET_V = ${JSON.stringify(map)};`);
+}
+/* ---- 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, requestedVersion) {
+  fs.readFile(file, (err, buf) => {
+    if (err) {
+      res.writeHead(404);
+      return res.end('not found');
+    }
+    const ext = path.extname(file);
+    const body = ext === '.html' ? Buffer.from(stampHtml(buf.toString('utf8')), 'utf8') : buf;
+    // A ?v= that matches the CURRENT hash is content-addressed, so it is safe to
+    // cache forever. A stale or forged one must NOT be — that would pin today's
+    // bytes under a key that no longer describes them. HTML is never immutable:
+    // it is what carries the stamps.
+    const contentAddressed =
+      ext !== '.html' && requestedVersion !== undefined && requestedVersion === assetVersion(file);
+    res.writeHead(200, {
+      'content-type': MIME[ext] || 'application/octet-stream',
+      'cache-control': contentAddressed
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache, must-revalidate',
+    });
+    res.end(body);
+  });
+}
+/* ---- 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,
+    });
+  }
+  // Static assets. assetUrlToFile owns the URL -> disk mapping (and the
+  // allowlists for the two directories outside PUBLIC); the routes below only
+  // pick the right 404 message when it declines.
+  const version = url.searchParams.get('v') ?? undefined;
+  // Bridge client, served from the cumulus package rather than a local copy.
+  if (p.startsWith('/agent/bridge-client/')) {
+    const file = assetUrlToFile(p);
+    if (!file) {
+      res.writeHead(404);
+      return res.end('bridge client unavailable — build cumulus or npm i @luckydraw/cumulus');
+    }
+    return sendFile(res, file, version);
+  }
+  // Blex renderer + library, likewise served from the package.
+  if (p.startsWith('/agent/blex/')) {
+    const file = assetUrlToFile(p);
+    if (!file) {
+      res.writeHead(404);
+      return res.end('blex unavailable — build cumulus or npm i @luckydraw/cumulus');
+    }
+    return sendFile(res, file, version);
+  }
+  if (req.method === 'GET') {
+    const file = assetUrlToFile(p);
+    if (!file) {
+      res.writeHead(403);
+      return res.end('forbidden');
+    }
+    return sendFile(res, file, version);
+  }
+  res.writeHead(404);
+  res.end('not found');
+});
+server.listen(PORT, '127.0.0.1', () => {
+  // The bound port, not the requested one — PORT=0 means "pick one for me".
+  const bound = server.address().port;
+  console.log(`demo app: http://127.0.0.1:${bound}  (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.66",
+  "version": "1.0.1",
   "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"
   },