@luckydraw/cumulus 1.0.1 → 1.0.3

package/examples/web-app-agent/agent/apply-thread-configs.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/* Apply this app's two thread configs to the gateway — the base thread you work
+   in, and the '-v' sub-namespace every visitor turn inherits.
+ *
+ * WHY A SCRIPT
+ * The visitor config is the one piece of per-app setup with no UI and no obvious
+ * home: it lives in a file on the gateway host, its name encodes a namespace rule
+ * (see thread-config.visitor.example.json), and getting it wrong silently costs
+ * money — every anonymous visitor runs whatever model your management thread uses.
+ * One command, run once per app, beats a paragraph telling you to hand-write JSON
+ * in a directory you may not have shell access to.
+ *
+ *   GATEWAY_ORIGIN=http://127.0.0.1:8080 \
+ *   GATEWAY_ADMIN_KEY=sk-... \
+ *   node agent/apply-thread-configs.mjs [--namespace demoapp] [--dry-run]
+ *
+ * GATEWAY_ADMIN_KEY, not the app's scoped key: a namespace covers '<ns>-*' only,
+ * so a scoped key can write '<ns>-v' but is refused (403) on the bare '<ns>' base
+ * thread. That asymmetry is the P7 access model working, not a bug — this is an
+ * operator action.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const ORIGIN = process.env.GATEWAY_ORIGIN;
+const KEY = process.env.GATEWAY_ADMIN_KEY;
+
+/* Near-miss names fail loudly rather than falling back to a default that might be
+   somebody's real gateway — the same rule server.js applies. */
+const ALIASES = {
+  GATEWAY_URL: 'GATEWAY_ORIGIN',
+  AGENT_GATEWAY_ORIGIN: 'GATEWAY_ORIGIN',
+  GATEWAY_KEY: 'GATEWAY_ADMIN_KEY',
+  ADMIN_KEY: 'GATEWAY_ADMIN_KEY',
+  GATEWAY_API_KEY: 'GATEWAY_ADMIN_KEY (the scoped app key cannot write the base thread)',
+};
+
+function die(msg) {
+  console.error(`\n  ${msg}\n`);
+  process.exit(1);
+}
+
+for (const [wrong, right] of Object.entries(ALIASES)) {
+  if (process.env[wrong] && !(wrong === 'GATEWAY_API_KEY' && KEY)) {
+    die(`${wrong} is set but this script reads ${right}.`);
+  }
+}
+if (!ORIGIN) die('GATEWAY_ORIGIN is required (no default — it must not guess a live gateway).');
+if (!KEY) die('GATEWAY_ADMIN_KEY is required.');
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const nsFlag = args.indexOf('--namespace');
+const namespace = nsFlag !== -1 ? args[nsFlag + 1] : 'demoapp';
+if (!/^[a-z0-9][a-z0-9-]*$/i.test(namespace)) die(`invalid --namespace: ${namespace}`);
+
+/** Read an example config and drop the `_`-prefixed annotation keys. */
+function load(file) {
+  const full = path.join(ROOT, file);
+  if (!fs.existsSync(full)) die(`missing ${file}`);
+  const parsed = JSON.parse(fs.readFileSync(full, 'utf-8'));
+  return Object.fromEntries(Object.entries(parsed).filter(([k]) => !k.startsWith('_')));
+}
+
+const targets = [
+  { thread: namespace, file: 'thread-config.example.json' },
+  { thread: `${namespace}-v`, file: 'thread-config.visitor.example.json' },
+];
+
+let failed = false;
+for (const { thread, file } of targets) {
+  const config = load(file);
+  if (String(config.projectDir || '').startsWith('/absolute/path/')) {
+    die(`${file} still has the placeholder projectDir — edit it before applying.`);
+  }
+  const label = `${thread.padEnd(24)} <- ${file}`;
+  if (dryRun) {
+    console.log(`DRY RUN  ${label}\n         ${JSON.stringify(config)}`);
+    continue;
+  }
+  let res;
+  try {
+    res = await fetch(`${ORIGIN}/api/thread/${encodeURIComponent(thread)}/config`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': KEY },
+      body: JSON.stringify(config),
+    });
+  } catch (err) {
+    die(`cannot reach ${ORIGIN}: ${err.message}`);
+  }
+  if (res.ok) {
+    console.log(`OK       ${label}`);
+    /* The config API applies a whitelist (projectDir, template, model, effort,
+       claudeModel, contextLimit). alwaysInclude and disallowedTools are NOT in it,
+       deliberately: combined with projectDir, alwaysInclude would let a
+       namespace-scoped key — which ships in your public page — read an arbitrary
+       file into its own prompt. So rather than assume, read the config back and
+       name anything that did not stick. A silent drop here would look like a
+       working persona that was never installed. */
+    try {
+      const check = await fetch(`${ORIGIN}/api/thread/${encodeURIComponent(thread)}/config`, {
+        headers: { 'X-API-Key': KEY },
+      });
+      if (check.ok) {
+        const stored = (await check.json()) ?? {};
+        const missing = Object.keys(config).filter(k => stored[k] === undefined);
+        if (missing.length) {
+          console.log(`         not applied by the API: ${missing.join(', ')}`);
+          console.log(
+            `         add them by hand to ~/.cumulus/threads/${thread}.config.json on the`
+          );
+          console.log('         gateway host — this file is exactly those contents.');
+        }
+      }
+    } catch {
+      /* the write succeeded; a failed read-back is not worth failing over */
+    }
+  } else {
+    failed = true;
+    const body = await res.text();
+    console.error(`FAILED   ${label}\n         ${res.status} ${body.slice(0, 200)}`);
+    if (res.status === 403) {
+      console.error('         403 on the base thread means the key is namespace-scoped.');
+      console.error('         Use the gateway admin key for this one-time setup.');
+    }
+  }
+}
+
+if (failed) process.exit(1);
+if (!dryRun) {
+  console.log(
+    `\nDone. Visitor turns on ${namespace}-v-<deviceId> now read ${namespace}-v.config.json;\n` +
+      `your own ${namespace} thread is unaffected. No gateway reload needed —\n` +
+      'thread config is read per turn.'
+  );
+}

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

@@ -4,6 +4,19 @@
 <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>
+<!-- KEEP THIS if you want ~~~blex:mermaid diagrams to render in the panel.
+     blex's mermaid renderer resolves the bare specifier "mermaid", and an import
+     map is the only mechanism in a browser that can satisfy one. The library is
+     served out of the installed cumulus package by this app's own /agent/blex/
+     route (see server.js) — not vendored, not cross-origin. The URL is stamped
+     with a content hash at serve time.
+     Drop this tag and nothing breaks: blex-render.js checks for the mapping and
+     leaves mermaid fences as readable text instead of painting an error box. -->
+<script type="importmap">{"imports":{"mermaid":"/agent/blex/mermaid-esm.js"}}</script>
+<!-- Diagram colours are derived from the blex card's own background (the
+     --blex-bg variable), so they follow whatever you theme blex to with no
+     declaration here. Set window.__CUMULUS_MERMAID_THEME to a mermaid theme name
+     ('default' | 'dark' | 'neutral' | 'forest' | 'base') only to override it. -->
 <style>
   /* The six variables the agent panel themes itself from. Define these and
      panel.css needs no edits. */

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

@@ -168,9 +168,15 @@ function assetUrlToFile(pathname) {
   // 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.
+  // mermaid-esm.js is the vendored mermaid library wrapped as an ES module. It is
+  // fetched by the browser resolving the bare specifier "mermaid" through the
+  // import map in index.html — never by a script tag — so it must be served from
+  // this app's own origin like the rest.
   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;
+    if (!STATIC_DIR || !/^(blex\.min|blex-render|blex-chart\.min|mermaid-esm)\.js$/.test(name)) {
+      return null;
+    }
     return path.join(STATIC_DIR, name);
   }
   const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
@@ -191,16 +197,34 @@ const RUNTIME_LOADED = [
 
 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. */
+/** Stamp served HTML: `?v=` on every same-origin .js/.css src/href AND on
+    import-map values, plus the version map for the runtime-loaded set.
+
+    Import maps need their own pass: the module URL lives in JSON inside a
+    `<script type="importmap">`, where the src/href rule cannot see it — and an
+    unstamped module URL is exactly the multi-hour edge staleness this mechanism
+    exists to prevent. Import-map *keys* are bare specifiers, so they cannot match
+    a pattern that requires a leading `/`. */
 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 stampUrl = url => {
+    const v = assetVersion(assetUrlToFile(url));
+    return v ? `${url}?v=${v}` : undefined;
+  };
+  const stamped = html
+    .replace(/(\s(?:src|href)=")(\/[^"?#]+\.(?:js|css))(")/g, (m, pre, url, post) => {
+      const s = stampUrl(url);
+      return s ? `${pre}${s}${post}` : m;
+    })
+    .replace(
+      /(<script[^>]*type="importmap"[^>]*>)([\s\S]*?)(<\/script>)/gi,
+      (m, open, body, close) =>
+        open +
+        body.replace(/"(\/[^"?#]+\.m?js)"/g, (inner, url) => {
+          const s = stampUrl(url);
+          return s ? `"${s}"` : inner;
+        }) +
+        close
+    );
   const map = {};
   for (const url of RUNTIME_LOADED) {
     const v = assetVersion(assetUrlToFile(url));

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

@@ -0,0 +1,22 @@
+{
+  "_readme": [
+    "BASE THREAD CONFIG  ->  ~/.cumulus/threads/demoapp.config.json",
+    "",
+    "This is YOUR management thread for the app — the one you talk to while",
+    "building it. It is NOT a visitor thread: a namespace covers '<ns>-*' only, so",
+    "the bare 'demoapp' name stays owned by your admin key and the app's scoped key",
+    "is rejected (403) on it.",
+    "",
+    "Give this one a strong model. Visitor turns read the sibling file",
+    "thread-config.visitor.example.json instead — see the '_readme' in there for how",
+    "the two are kept apart.",
+    "",
+    "Apply both with:  node agent/apply-thread-configs.mjs",
+    "Keys starting with '_' are annotations and are stripped before sending."
+  ],
+
+  "projectDir": "/absolute/path/to/your/app",
+  "model": "claude",
+  "effort": "high",
+  "alwaysInclude": ["docs/demoapp-system-prompt.md"]
+}

package/examples/web-app-agent/thread-config.visitor.example.json

@@ -0,0 +1,41 @@
+{
+  "_readme": [
+    "VISITOR THREAD CONFIG  ->  ~/.cumulus/threads/demoapp-v.config.json",
+    "",
+    "WHY THIS FILE EXISTS, AND WHY THE '-v' MATTERS",
+    "The server hands the browser THREAD_ID = 'demoapp-v' and device-thread.js",
+    "appends 16 hex characters, so every visitor gets 'demoapp-v-<deviceId>'.",
+    "Config is resolved by prefix-fallback: a turn on 'demoapp-v-a3f8c2d1' looks for",
+    "its own exact file, then strips one trailing '-segment' at a time and takes the",
+    "longest match:",
+    "",
+    "    demoapp-v-a3f8c2d1.config.json   (none — visitors never get their own)",
+    "    demoapp-v.config.json            <- THIS FILE. Every visitor turn.",
+    "    demoapp.config.json              (only if this file is absent)",
+    "",
+    "That middle layer is the whole point. Without it, visitor turns inherit your",
+    "management thread's config and run your expensive model for every anonymous",
+    "visitor. With it, the two are set independently and neither can affect the",
+    "other — writes are always exact, so a visitor session can never mutate this",
+    "file or the base.",
+    "",
+    "COST IS THE MAIN DIAL. Visitor traffic is unbounded and mostly shallow, so a",
+    "small fast model is usually right here even when the base thread runs a large",
+    "one. Both live gateway apps on this box do exactly that.",
+    "",
+    "Apply with:  node agent/apply-thread-configs.mjs",
+    "Keys starting with '_' are annotations and are stripped before sending."
+  ],
+
+  "projectDir": "/absolute/path/to/your/app",
+  "model": "claude",
+  "claudeModel": "claude-haiku-4-5",
+  "effort": "medium",
+  "alwaysInclude": ["docs/demoapp-system-prompt.md"],
+
+  "_disallowedTools": [
+    "Visitor-facing threads should not be able to stop and ask the operator a",
+    "question — there is nobody on the other end, and the turn would hang. Strip it:"
+  ],
+  "disallowedTools": ["AskUserQuestion"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "cumulus-gateway": "./dist/gateway/daemon.js"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc && cp -r src/gateway/static dist/gateway/static && cp node_modules/@luckydraw/blex/dist/blex.min.global.js dist/gateway/static/blex.min.js && cp node_modules/@luckydraw/blex/dist/blex-chart.min.global.js dist/gateway/static/blex-chart.min.js",
+    "build": "rm -rf dist && tsc && cp -r src/gateway/static dist/gateway/static && cp node_modules/@luckydraw/blex/dist/blex.min.global.js dist/gateway/static/blex.min.js && cp node_modules/@luckydraw/blex/dist/blex-chart.min.global.js dist/gateway/static/blex-chart.min.js && node scripts/build-mermaid-esm.mjs",
     "dev": "tsc --watch",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
@@ -88,6 +88,7 @@
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",
     "lint-staged": "^16.2.7",
+    "mermaid": "^10.9.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0",