@inetafrica/open-claudia 3.5.75 → 3.5.77

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 3.5.77
+
+3.5.76 plus two pieces first run on the Mac build (Sumeet 12 Nov, card 6af54622: one test bot first, then the rest on his word).
+
+- **Claude Fable 5.2 in the model picker and price table** (`core/providers/claude.js`, `core/model-prices.js`): `claude-fable-5-2` leads the picker and is billed at its own prices (8 / 40 per million, cache read 0.2, cache write 10 / 16) instead of falling through to the Fable 5 row. Needs Claude Code 2.1.302 or newer when named in full; the image installs the latest Claude Code at build time.
+- **`call --help` never dials** (`bin/cli.js`, `rust/maia-cli/src/main.rs`): `open-claudia call --help` or `-h` prints usage, and an unknown flag is refused with "nothing was dialled". Before, the call verb passed every argument on as a call, so asking for help rang the owner (9 Nov). Fixed in both the Node CLI and the Rust front door.
+
+Tests: `test-call-flags.js` (new, in the suite), plus additions to `test-rust-cli-parity.js`, `test-provider-claude.js` and `test-cost-by-part.js`.
+
+## 3.5.76
+
+3.5.75 plus the memory cuts from the usage work, the lessons ranking fix, the empty-lock fix, `handoff --new`, HTML views and the type-check guard (Sumeet 9 Nov: "all bots get all features"). Every new setting is optional: unset, a bot behaves as 3.5.75 except where noted.
+
+- **Recall helper sleeps when idle** (`core/recall/warm-walker.js`): the warm recall walker stops after 10 minutes with no walks (about 160 MB back) and starts again on the next one. `RECALL_WARM_WALKER_IDLE_MS` changes the wait; `0` keeps it running.
+- **Usage history read only when needed** (`core/runner.js`): a bot no longer parses its whole usage history after every turn; it reads it only when usage alerts are on.
+- **Node flags for the bot only** (`docker-entrypoint.sh`): `OC_NODE_FLAGS` in a bot's env (for example a heap limit) goes on the main node command line, never `NODE_OPTIONS`, so agents, hooks and CLI runs do not inherit it. Unset, the start command is unchanged.
+- **`RECALL_ENGINE` in the bot's `.env` works** (`core/recall/index.js`): the engine set in `.env` is now honoured, not only one set in the process env. A per-chat `/engine` choice still comes first.
+- **Pack reviews wait their turn** (`core/pack-review.js`): reviews run one at a time per bot behind a queue instead of being dropped when too many came at once. `OC_REVIEW_CONCURRENCY` (default 1) and `OC_REVIEW_QUEUE_MAX` (default 20; the oldest is dropped with a log line) tune it.
+- **Heavy libraries load on demand**: the call library (werift) loads on the first Kazee call and the Telegram library only when a Telegram token is set (about 40 MB less idle). The first call after a start takes a few seconds longer.
+- **Type checks take their turn** (`core/tool-guard.js`): `tsc` now counts in the test-run guard, so only one test run or type check goes at a time on a bot and the free-memory floor applies.
+- **Lessons keep their ranking** (`core/lessons.js`): reading one pack's topic lessons no longer resets every other lesson's ranking to zero.
+- **An old empty migration lock no longer blocks start** (`core/migration-backup.js`): a lock file left empty by a run that died before writing its pid is treated as stale once old, so the bot stops crash-looping on it. A fresh empty lock still counts as held.
+- **`open-claudia handoff --new "<title>" "<message>"`** (`core/thread-handoff.js`): starts a real titled Kazee thread, posts the hand-off in it tagging the person who asked (so it shows in their Threads list), then wakes it. Refused hand-offs start nothing.
+- **HTML views** (`bin/views.js`, `core/views.js`): `open-claudia view send <page.html> --title "<t>" [--handler <file>] [--wake each|none]` sends an interactive page into Kazee Chat as a card with an Open button; it opens walled off (libraries from public CDNs, no data fetched from the internet). What the person does on the page runs the handler or wakes the conversation. `open-claudia view push` sends data back into open pages; `open-claudia view example` prints a quiz page and handler. Kazee Chat only.
+
+Tests: `test-walker-idle-stop.js`, `test-usage-history-lazy.js`, `test-node-flags-entrypoint.js`, `test-recall-engine-env.js`, `test-review-queue.js`, `test-lazy-heavy-libs.js`, `test-lessons-meta-keep.js`, `test-views.js` (all in the suite), plus additions to `test-test-run-guard.js`, `test-provider-migration-backup.js` and `test-thread-handoff.js`.
+
 ## 3.5.75
 
 3.5.74 plus personal bots act for their owner through a pass (from the Maia build), and the one-tap switch-on card. Nothing changes for a bot until Central has `bot:me` (an older Central answers 404 and the bot stays as it was). Autonomous bots are unchanged.

package/Dockerfile

@@ -102,5 +102,7 @@ EXPOSE 8080
 # Switch to non-root user
 USER 1001
 
+# OC_NODE_FLAGS in a bot's env: docker-entrypoint.sh puts those flags on this
+# node command only. Unset, the command below runs as is.
 ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["node", "bin/cli.js", "web"]

package/bin/cli.js

@@ -460,6 +460,17 @@ switch (command) {
       const { postJson } = require("./loopback-client");
       try {
         const rest = args.slice(1);
+        // `call --help` once rang the owner (9 Nov): help and unknown flags never dial.
+        const usage = `Usage: open-claudia call [<userId>] [--about "<why>"]\nRings the owner (or <userId>) in Kazee Chat.`;
+        if (rest.includes("--help") || rest.includes("-h")) {
+          console.log(usage);
+          process.exit(0);
+        }
+        const unknown = rest.find((arg, i) => arg.startsWith("-") && arg !== "--about" && rest[i - 1] !== "--about");
+        if (unknown) {
+          console.error(`Unknown option ${unknown}; nothing was dialled.\n${usage}`);
+          process.exit(2);
+        }
         const aboutAt = rest.indexOf("--about");
         const reason = aboutAt >= 0 ? String(rest[aboutAt + 1] || "").trim() : "";
         const toUserId = String(rest.find((arg, i) => !arg.startsWith("--") && rest[i - 1] !== "--about") || "").trim();
@@ -494,6 +505,10 @@ switch (command) {
     require("./cards").runDecide(args.slice(1));
     break;
   }
+  case "view": {
+    require("./views").runView(args.slice(1));
+    break;
+  }
   case "teach": {
     Promise.resolve(require("./teach").run(args.slice(1)))
       .catch((e) => { console.error(`teach command failed: ${e.message}`); process.exitCode = 1; });
@@ -682,6 +697,7 @@ Send tools (only work inside an active bot-spawned task):
   open-claudia card pieces           List the pieces a card is built from (table, tick, date, slots, rows, board...) and their examples
   open-claudia card update <id> ...  Close/open a card you sent, add a note, or replace its spec (card example <name> for specs)
   open-claudia decide "<q>" --option id="label" ...   Queue a decision card for the owner (one at a time; decide list|cancel)
+  open-claudia view send <page.html> --title "<t>" [--handler <file>]   Send an interactive web page (Kazee Chat); view push|example
   open-claudia teach list|show|finish|cancel <id>   Browser recordings from Teach me; finish deletes the pictures, cancel the whole recording
 
 Memory tools:
@@ -726,6 +742,7 @@ Multi-user / cross-channel:
   open-claudia auth list|revoke <chatId>           Raw authorization view + direct deauth
   open-claudia send-to --person "<name>" "<msg>"   Relay a message to another team member
   open-claudia handoff --thread <id> "<msg>"       Post in another Kazee thread and wake it to start work
+  open-claudia handoff --new "<title>" "<msg>"    Start a titled thread, tag the asker, hand off into it
                                                    ([--chat <chatId>] [--title "<label>"]; owner only)
   open-claudia recent --person "<name>" [--limit]  Read recent activity from another chat
 

package/bin/handoff.js

@@ -9,8 +9,12 @@ Hand work to another Kazee thread: post the message there (visibly, as the
 bot) and wake that thread's conversation to start on it now.
 
   open-claudia handoff --thread <threadId> "<message>" [--chat <chatId>] [--title "<short label>"]
+  open-claudia handoff --new "<thread title>" "<message>" [--chat <chatId>]
 
   --thread  the target thread's id (its root message id)
+  --new     start a NEW titled thread (1-80 characters) and hand off into it;
+            the person who asked is tagged so it shows in their Threads list.
+            Never post a plain main-chat message and hand off onto that.
   --chat    the Kazee chat the thread is in (default: this conversation's chat)
   --title   a short label for the wake-up job (cron-list shows it)
 
@@ -35,6 +39,7 @@ async function run(argv) {
     process.exit(args[0] === "--help" || args[0] === "help" ? 0 : 2);
   }
   const targetThreadId = takeFlag(args, "thread");
+  const newTitle = takeFlag(args, "new");
   const targetChatId = takeFlag(args, "chat");
   const title = takeFlag(args, "title");
   if (args[0] && /^--[a-z]/.test(args[0])) {
@@ -42,16 +47,20 @@ async function run(argv) {
     process.exit(2);
   }
   const message = args.join(" ").trim();
-  if (!targetThreadId) { console.error("Missing --thread <threadId>."); process.exit(2); }
+  if (targetThreadId && newTitle !== null) { console.error('Use --thread <threadId> or --new "<title>", not both.'); process.exit(2); }
+  if (!targetThreadId && newTitle === null) { console.error('Missing --thread <threadId> (an existing thread) or --new "<title>" (a new thread).'); process.exit(2); }
+  if (newTitle !== null && !newTitle.trim()) { console.error('--new needs a title: --new "<title>".'); process.exit(2); }
   if (!message) { console.error("Missing message text."); process.exit(2); }
   try {
-    const body = { targetThreadId, message };
+    const body = { message };
+    if (targetThreadId) body.targetThreadId = targetThreadId;
+    if (newTitle !== null) body.newThreadTitle = newTitle;
     if (targetChatId) body.targetChatId = targetChatId;
     if (title) body.title = title;
     const res = await postJson("thread-handoff", body);
     const target = res.target || {};
     const where = target.title ? `"${target.title}" (${target.threadId})` : `thread ${target.threadId || targetThreadId}`;
-    console.log(`Handed off to ${where}: posted message ${res.messageId || "(no id)"}, wake job ${res.jobId || "?"} (hand-off ${res.hop || "?"} of ${res.maxHops || 3} in a row).`);
+    console.log(`Handed off to ${res.newThread ? "new thread " : ""}${where}: posted message ${res.messageId || "(no id)"}, wake job ${res.jobId || "?"} (hand-off ${res.hop || "?"} of ${res.maxHops || 3} in a row).`);
     process.exit(0);
   } catch (e) {
     console.error(e.message);

package/bin/views.js

@@ -0,0 +1,255 @@
+// `open-claudia view ...`: HTML views in Kazee Chat from inside a turn. A
+// view is a web page sent as a card with an Open button; it opens in a
+// walled-off panel and talks back with kazee.send / kazee.on (core/views.js
+// answers its events).
+
+const fs = require("fs");
+const path = require("path");
+const { postJson } = require("./loopback-client");
+
+const FILE_MAX = 2 * 1024 * 1024;
+const PUSH_MAX = 16384;
+
+const VIEW_USAGE = `Usage:
+  open-claudia view send <page.html> --title "<title>" [--body "<text>"] [--label "<button>"]
+                         [--preview <picture.png|.jpg>] [--handler <file>] [--wake each|none]
+  open-claudia view push <messageId> <json | -> [--to <userId>]
+  open-claudia view example [page|handler]
+Views are Kazee Chat only. The page (.html, at most 2 MB) opens in a walled-off
+panel: it may load scripts, styles and fonts from cdn.jsdelivr.net, unpkg.com,
+cdnjs.cloudflare.com and esm.sh, but cannot fetch anything from the internet,
+so put its data in the page. In the page:
+  kazee.send(name, data)   send an event to you (name: a-z 0-9 _ . -, data under 4 KB as JSON)
+  kazee.on(data => ...)    receive what you push (view push, or a handler's {"push": ...})
+Events wake this conversation (--wake each, the default; events close together
+come as one wake) or are dropped (--wake none). With --handler, a script runs
+once per event instead (node for .js, else run directly; 10 s; its folder is the
+working directory). It gets the event as JSON on stdin
+  {"messageId","chatId","userId","userName","name","data","at"}
+and each line it prints that is JSON is an order:
+  {"push": <data>, "to": "<userId>"}   back to the page ("to" optional: only that person)
+  {"wake": "<text>"}                    wake this conversation
+Never put answers you check (a quiz key) in the page: people can read it. Keep them in the handler.`;
+
+const EXAMPLE_PAGE = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Quick quiz</title>
+<style>
+  body { font: 16px/1.4 system-ui, sans-serif; margin: 0; padding: 16px; background: #f7f7f8; color: #1d1d1f; }
+  .q { background: #fff; border-radius: 12px; padding: 14px; margin-bottom: 12px; box-shadow: 0 1px 2px rgba(0,0,0,.08); }
+  .q h3 { margin: 0 0 10px; font-size: 16px; }
+  button { display: block; width: 100%; text-align: left; margin: 6px 0; padding: 10px 12px; border: 1px solid #d0d0d6;
+           border-radius: 8px; background: #fff; font: inherit; cursor: pointer; }
+  button:disabled { cursor: default; opacity: .7; }
+  button.right { border-color: #2e9d57; background: #e7f6ec; opacity: 1; }
+  button.wrong { border-color: #d0453b; background: #fbeceb; opacity: 1; }
+  .note { font-size: 14px; color: #555; min-height: 1.2em; }
+  #score { font-weight: 600; text-align: center; }
+</style>
+</head>
+<body>
+<div id="quiz"></div>
+<p id="score"></p>
+<script>
+  // The questions only. The right answers stay in the handler: anyone can read this page.
+  const QUESTIONS = [
+    { id: "q1", text: "Which planet is closest to the sun?", options: ["Venus", "Mercury", "Mars"] },
+    { id: "q2", text: "How many legs does a spider have?", options: ["6", "8", "10"] },
+    { id: "q3", text: "What is the boiling point of water at sea level?", options: ["90 °C", "100 °C", "120 °C"] },
+  ];
+  const results = {};
+  const quiz = document.getElementById("quiz");
+  for (const q of QUESTIONS) {
+    const box = document.createElement("div");
+    box.className = "q";
+    box.innerHTML = "<h3></h3><div class='opts'></div><div class='note'></div>";
+    box.querySelector("h3").textContent = q.text;
+    q.options.forEach((label, i) => {
+      const b = document.createElement("button");
+      b.textContent = label;
+      b.onclick = () => {
+        box.querySelectorAll("button").forEach((x) => { x.disabled = true; });
+        b.dataset.picked = "1";
+        box.querySelector(".note").textContent = "Checking...";
+        window.kazee.send("answer", { q: q.id, choice: i });
+      };
+      box.querySelector(".opts").appendChild(b);
+    });
+    box.id = q.id;
+    quiz.appendChild(box);
+  }
+  // The bot's replies: { q, correct, right, note } for each answer.
+  window.kazee.on((data) => {
+    if (!data || !data.q) return;
+    const box = document.getElementById(data.q);
+    if (!box) return;
+    const buttons = box.querySelectorAll("button");
+    buttons.forEach((b, i) => {
+      if (i === data.right) b.className = "right";
+      else if (b.dataset.picked) b.className = "wrong";
+    });
+    box.querySelector(".note").textContent = data.note || "";
+    results[data.q] = !!data.correct;
+    const done = Object.keys(results).length;
+    if (done === QUESTIONS.length) {
+      const score = Object.values(results).filter(Boolean).length;
+      document.getElementById("score").textContent = "You got " + score + " of " + QUESTIONS.length + ".";
+      window.kazee.send("done", { score, of: QUESTIONS.length });
+    }
+  });
+</script>
+</body>
+</html>
+`;
+
+const EXAMPLE_HANDLER = `// handler.js: answers the quiz page's events. Sent with
+//   open-claudia view send quiz.html --title "Quick quiz" --handler handler.js
+// It runs once per event: the event is JSON on stdin, each JSON line printed is an order.
+const KEY = { q1: { right: 1, note: "Mercury is closest." },
+              q2: { right: 1, note: "Spiders have 8 legs." },
+              q3: { right: 1, note: "100 °C at sea level." } };
+
+let input = "";
+process.stdin.on("data", (c) => { input += c; });
+process.stdin.on("end", () => {
+  const ev = JSON.parse(input);
+  const out = (order) => console.log(JSON.stringify(order));
+  if (ev.name === "answer" && ev.data && KEY[ev.data.q]) {
+    const k = KEY[ev.data.q];
+    // Only to the person who answered: others with the page open keep their own quiz.
+    out({ push: { q: ev.data.q, correct: ev.data.choice === k.right, right: k.right, note: k.note }, to: ev.userId });
+  } else if (ev.name === "done" && ev.data) {
+    // Wake the conversation once, when someone finishes.
+    out({ wake: \`\${ev.userName || "Someone"} finished the quiz: \${Number(ev.data.score)} of \${Number(ev.data.of)}.\` });
+  }
+});
+`;
+
+function flag(args, name) {
+  const i = args.indexOf(name);
+  if (i < 0) return undefined;
+  const v = args[i + 1];
+  if (v === undefined || v.startsWith("--")) throw new Error(`${name} needs a value`);
+  args.splice(i, 2);
+  return v;
+}
+
+function readFileFor(file, what, exts) {
+  const full = path.resolve(file);
+  const ext = path.extname(full).toLowerCase();
+  if (!exts.includes(ext)) throw new Error(`the ${what} must be a ${exts.join(" or ")} file: ${file}`);
+  let st;
+  try { st = fs.statSync(full); } catch (_) { throw new Error(`${what} not found: ${file}`); }
+  if (!st.isFile()) throw new Error(`${what} is not a file: ${file}`);
+  if (st.size === 0) throw new Error(`the ${what} is empty: ${file}`);
+  if (st.size > FILE_MAX) throw new Error(`the ${what} is over 2 MB: ${file}`);
+  return { fileName: path.basename(full), data: fs.readFileSync(full).toString("base64") };
+}
+
+/** `view send` arguments into the loopback body (throws on bad input). */
+function parseSend(argv) {
+  const args = [...argv];
+  const title = flag(args, "--title");
+  const body = flag(args, "--body");
+  const label = flag(args, "--label");
+  const preview = flag(args, "--preview");
+  const handler = flag(args, "--handler");
+  const wake = flag(args, "--wake");
+  const unknown = args.find((a) => a.startsWith("--"));
+  if (unknown) throw new Error(`unknown option ${unknown}`);
+  if (args.length !== 1) throw new Error(args.length ? `one page only (got ${args.join(" ")})` : "missing the page (.html file)");
+  if (!title || !title.trim()) throw new Error("--title is required");
+  if (title.trim().length > 140) throw new Error("--title is over 140 characters");
+  if (body && body.length > 600) throw new Error("--body is over 600 characters");
+  if (label && label.trim().length > 40) throw new Error("--label is over 40 characters");
+  if (wake !== undefined && !["each", "none"].includes(wake)) throw new Error("--wake must be each or none");
+  let handlerPath = null;
+  if (handler) {
+    handlerPath = path.resolve(handler);
+    let st = null;
+    try { st = fs.statSync(handlerPath); } catch (_) {}
+    if (!st || !st.isFile()) throw new Error(`handler not found: ${handler}`);
+    if (!/\.(c|m)?js$/i.test(handlerPath)) {
+      try { fs.accessSync(handlerPath, fs.constants.X_OK); }
+      catch (_) { throw new Error(`the handler is not a .js file and not executable (chmod +x it): ${handler}`); }
+    }
+  }
+  return {
+    title: title.trim(),
+    ...(body ? { body } : {}),
+    ...(label ? { label: label.trim() } : {}),
+    ...(wake ? { wake } : {}),
+    handler: handlerPath,
+    page: readFileFor(args[0], "page", [".html", ".htm"]),
+    ...(preview ? { preview: readFileFor(preview, "preview", [".png", ".jpg", ".jpeg"]) } : {}),
+  };
+}
+
+/** `view push` arguments into the loopback body; `readStdin` for "-". */
+function parsePush(argv, readStdin = () => fs.readFileSync(0, "utf8")) {
+  const args = [...argv];
+  const to = flag(args, "--to");
+  const unknown = args.find((a) => a.startsWith("--"));
+  if (unknown) throw new Error(`unknown option ${unknown}`);
+  const [messageId, raw] = args;
+  if (!messageId) throw new Error("missing the view's message id");
+  if (raw === undefined) throw new Error("missing the data (JSON, or - for stdin)");
+  if (args.length > 2) throw new Error("too many arguments (quote the JSON)");
+  const text = raw === "-" ? readStdin() : raw;
+  let data;
+  try { data = JSON.parse(text); }
+  catch (_) { throw new Error(`the data is not JSON (a string needs quotes: '"hello"')`); }
+  if (Buffer.byteLength(JSON.stringify(data)) > PUSH_MAX) throw new Error("the data is over 16 KB as JSON");
+  return { messageId, data, ...(to ? { to } : {}) };
+}
+
+function exampleText(which) {
+  if (which === "page") return EXAMPLE_PAGE;
+  if (which === "handler") return EXAMPLE_HANDLER;
+  if (which) throw new Error("examples: page, handler (or nothing for both)");
+  return [
+    "# quiz.html (open-claudia view example page > quiz.html)",
+    EXAMPLE_PAGE,
+    "# handler.js (open-claudia view example handler > handler.js)",
+    EXAMPLE_HANDLER,
+    '# Send it: open-claudia view send quiz.html --title "Quick quiz" --handler handler.js',
+    "",
+  ].join("\n");
+}
+
+function fail(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+async function runView(argv) {
+  const args = [...argv];
+  const sub = args.shift();
+  try {
+    if (sub === "example") {
+      process.stdout.write(exampleText(args[0]));
+      return;
+    }
+    if (sub === "send") {
+      const body = parseSend(args);
+      const res = await postJson("view-send", body);
+      const events = res.handler ? `events run ${res.handler}` : `events wake this conversation: ${res.wake}`;
+      console.log(`Sent view ${res.messageId} (${events})`);
+      return;
+    }
+    if (sub === "push") {
+      const body = parsePush(args);
+      await postJson("view-push", body);
+      console.log(`Pushed to view ${body.messageId}${body.to ? ` (only to ${body.to})` : ""}`);
+      return;
+    }
+    fail(VIEW_USAGE, sub && sub !== "help" && sub !== "--help" ? 1 : 0);
+  } catch (e) {
+    fail(`view ${sub}: ${e.message}`);
+  }
+}
+
+module.exports = { runView, parseSend, parsePush, exampleText, VIEW_USAGE, EXAMPLE_PAGE, EXAMPLE_HANDLER };

package/channels/kazee/adapter.js

@@ -546,6 +546,25 @@ class KazeeAdapter {
         raw: payload,
       });
     });
+    // HTML views: someone in the chat sent an event from a view page this bot
+    // sent (kazee.send in the page). Routed like a card answer; core/views.js
+    // runs the view's handler or wakes the conversation the view came from.
+    socket.on("view:event", (payload) => {
+      if (!payload || !payload.messageId) return;
+      const userId = payload.userId ? String(payload.userId) : "";
+      this._emit("action", {
+        adapter: this,
+        channelId: String(payload.chatId || ""),
+        canonicalUserId: userId ? canonicalForChannel("kazee", userId) : null,
+        userId: userId || null,
+        type: "action",
+        messageId: payload.messageId,
+        threadId: payload.threadRoot ? String(payload.threadRoot) : null,
+        action: { buttonId: `kv:${payload.messageId}`, payload: `kv:${payload.messageId}`, sourceMessageId: payload.messageId },
+        view: payload,
+        raw: payload,
+      });
+    });
     socket.on("message:action", (payload) => {
       const channelId = String(payload.chatId);
       const known = this._sentMessages.has(String(payload.messageId || ""));
@@ -733,6 +752,18 @@ class KazeeAdapter {
   // What the bot reads to name a thread: the root's text, the first replies
   // (the bot's own marked) and the title the thread already has, when the
   // server sends one. Throws like _fetchThread.
+  // Start a real thread (chat-central startThread): a titled header root the
+  // chat's bots never hear. Followers are the starter plus whoever the first
+  // reply tags, so callers tag the person the thread is for. Resolves the
+  // root message id; throws when chat-central refuses.
+  async startThread(chatId, title) {
+    const route = `/thread/${encodeURIComponent(String(chatId))}/start`;
+    const res = await withTimeout(this._request("POST", route, { userId: String(this.botUserId), title: String(title || "") }), THREAD_TITLE_TIMEOUT_MS, "Kazee thread start");
+    const root = res && ((res.message && res.message._id) || (res.data && res.data._id));
+    if (!root) throw new Error(`Kazee thread start gave no root id${res && res.error ? `: ${res.error}` : ""}`);
+    return String(root);
+  }
+
   async threadTitleSource(chatId, rootId) {
     const data = await this._fetchThread(String(chatId), String(rootId), THREAD_TITLE_SOURCE_LIMIT);
     const root = data.root && typeof data.root === "object" ? data.root : null;
@@ -1435,6 +1466,9 @@ class KazeeAdapter {
     };
     if (opts.replyTo) body.replyTo = opts.replyTo;
     if (buttons) body.interactive = { buttons };
+    // People tagged as @[Name](id) in the text (a hand-off into a new thread
+    // tags whoever asked, so it shows in their Threads list and as unread).
+    if (Array.isArray(opts.mentions) && opts.mentions.length) body.mentions = opts.mentions.map(String);
     const threadId = opts.threadId ? String(opts.threadId) : null;
     if (threadId) body.threadRootId = threadId;
     // Tags of other bots (./bot-handoffs.js). chat-central reads mentions out
@@ -1574,6 +1608,32 @@ class KazeeAdapter {
     return view;
   }
 
+  // Upload one file as chat media (chat-central `uploadMedia`) and answer its
+  // media id. For HTML views: the page and its preview picture go up first,
+  // then the card names them by id. Throws when the server keeps no id.
+  async uploadMedia(channelId, { buffer, fileName, contentType } = {}) {
+    const upload = await this._uploadMultipart(
+      `/chat/media/${encodeURIComponent(channelId)}`,
+      { media: { buffer, fileName, contentType } },
+    );
+    const saved = Array.isArray(upload?.media) ? upload.media[0] : null;
+    if (!saved || !saved._id) {
+      const why = Array.isArray(upload?.errors) && upload.errors[0]?.error ? `: ${upload.errors[0].error}` : "";
+      throw new Error(`Kazee Chat kept no media id for ${fileName}${why}`);
+    }
+    return String(saved._id);
+  }
+
+  // HTML views: hand data to an open view page (kazee.on in the page).
+  // Only the message's sender may push; `to` limits it to one person.
+  async pushView(messageId, data, to) {
+    const body = { data: data === undefined ? null : data };
+    if (to) body.to = String(to);
+    const res = await this._request("PUT", `/message/${encodeURIComponent(messageId)}/view/push`, body);
+    if (res && res.success === false) throw new Error(res.error || "view push refused");
+    return true;
+  }
+
   // A card as the server shows it now (its state: open, closed, decided),
   // read through the one-message lookup. Null when the message is gone.
   async readCard(chatId, messageId) {
@@ -2083,7 +2143,7 @@ class KazeeAdapter {
       const boundary = `----oc-${Date.now()}-${Math.random().toString(36).slice(2)}`;
       const parts = [];
       for (const [field, info] of Object.entries(files)) {
-        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"; filename="${info.fileName}"\r\nContent-Type: application/octet-stream\r\n\r\n`));
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"; filename="${info.fileName}"\r\nContent-Type: ${info.contentType || "application/octet-stream"}\r\n\r\n`));
         parts.push(info.buffer);
         parts.push(Buffer.from("\r\n"));
       }

package/channels/kazee/call/camera.js

@@ -11,7 +11,6 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { spawn } = require("child_process");
-const { dePacketizeRtpPackets } = require("werift");
 
 const STILL_EVERY_S = 2;
 const STILL_SIZE = 768;
@@ -152,7 +151,7 @@ class CameraStills {
       if ((packets[index].header.sequenceNumber - packets[index - 1].header.sequenceNumber + 65536) % 65536 !== 1) return this._lost();
     }
     let frame;
-    try { frame = dePacketizeRtpPackets("VP8", packets); } catch (_) { return this._lost(); }
+    try { frame = require("werift").dePacketizeRtpPackets("VP8", packets); } catch (_) { return this._lost(); }
     if (!frame?.data?.length) return;
     const size = frame.isKeyframe ? vp8KeyframeSize(frame.data) : null;
     if (this._needKeyframe) {

package/channels/kazee/call/session.js

@@ -1,6 +1,7 @@
 "use strict";
 
-const { MediaStreamTrack, RTCPeerConnection, RTCRtpHeaderExtensionParameters, RtpHeader, RtpPacket } = require("werift");
+// Loaded on the first call, so a bot that takes no calls never holds this library.
+const werift = () => require("werift");
 const { JanusClient } = require("./janus-client");
 const { projectAssignedIce, supportedIceServers } = require("./access");
 const { AdaptiveTurnDetector, OpusAudioCodec, WEBRTC_SAMPLES, downsample48To16, upsampleTo48, rmsDbfs } = require("./audio");
@@ -227,7 +228,7 @@ class KazeeCallSession {
   constructor({ roomId, chatId, callerId, botUserId, janusUrl, janusToken, janusTokenExpiresAt, roomToken, roomTokenExpiresAt, managedRoom = false, refreshRoomAccess, iceServers = [], iceCredentialsExpiresAt, onTranscript, onEnded, onMediaReady,
     maxCallMs, idleMs, checkInMs, checkInGraceMs, dropMs, dropGiveUpMs, humDb, finalWaitMs, synthesize = synthesizePcm, synthesizeStream = null, asCaller = false, greeting = null,
     turnDecision = detectTurn, acknowledgement = selectAcknowledgement, onSpeechStart, onSpeechNoise, onEarlyWords, onUtteranceDropped,
-    JanusClientImpl = JanusClient, PeerConnectionImpl = RTCPeerConnection, SpeechStreamImpl = SpeechStream } = {}) {
+    JanusClientImpl = JanusClient, PeerConnectionImpl = werift().RTCPeerConnection, SpeechStreamImpl = SpeechStream } = {}) {
     this.roomId = Number(roomId);
     this.chatId = String(chatId);
     this.callerId = String(callerId);
@@ -357,7 +358,7 @@ class KazeeCallSession {
     // A feed's connection also takes the caller's camera; with the
     // orientation extension a phone held upright gives an upright still.
     const pc = new this.PeerConnectionImpl(camera
-      ? { iceServers: this.iceServers, headerExtensions: { audio: [], video: [new RTCRtpHeaderExtensionParameters({ id: 13, uri: VIDEO_ORIENTATION_URI })] } }
+      ? { iceServers: this.iceServers, headerExtensions: { audio: [], video: [new (werift().RTCRtpHeaderExtensionParameters)({ id: 13, uri: VIDEO_ORIENTATION_URI })] } }
       : { iceServers: this.iceServers });
     if (Number.isFinite(expiresAt)) {
       this._transportIceExpiry.set(pc, expiresAt);
@@ -515,7 +516,7 @@ class KazeeCallSession {
         this._maybeGreet();
       }
     });
-    const track = new MediaStreamTrack({ kind: "audio" });
+    const track = new (werift().MediaStreamTrack)({ kind: "audio" });
     const sender = pc.addTrack(track);
     this.publisher = { pc, track, sender, pending: [], remoteSet: false };
     const offer = await pc.createOffer();
@@ -1046,7 +1047,7 @@ class KazeeCallSession {
     if (frame.length < WEBRTC_SAMPLES * 2) frame = Buffer.concat([frame, Buffer.alloc(WEBRTC_SAMPLES * 2 - frame.length)]);
     const opus = this.codec.encode(frame);
     const payloadType = this.publisher?.sender?.codec?.payloadType || 111;
-    this.publisher?.track?.writeRtp(new RtpPacket(new RtpHeader({
+    this.publisher?.track?.writeRtp(new (werift().RtpPacket)(new (werift().RtpHeader)({
       payloadType, sequenceNumber: this.sequence++ & 0xffff, timestamp: this.timestamp >>> 0, ssrc: this.ssrc,
     }), opus));
     this.timestamp = (this.timestamp + WEBRTC_SAMPLES) >>> 0;

package/channels/telegram/adapter.js

@@ -6,7 +6,6 @@
 const fs = require("fs");
 const path = require("path");
 const https = require("https");
-const TelegramBot = require("node-telegram-bot-api");
 const { TEMP_DIR, FILES_DIR, CONFIG_DIR } = require("../../core/config");
 const { safeJoin } = require("../../core/safe-filename");
 const { canonicalForChannel } = require("../../core/identity");
@@ -27,6 +26,8 @@ class TelegramAdapter {
     // one bot) sidesteps the stale-socket trap that drove the old restart storm.
     // We still own the agent so a heal can destroy any lingering socket.
     this._agent = new https.Agent({ keepAlive: false });
+    // Loaded here so a bot with no Telegram token never holds this library.
+    const TelegramBot = require("node-telegram-bot-api");
     this.bot = new TelegramBot(token, {
       polling: { autoStart: false, params: { timeout: 30 } },
       // Socket-idle timeout on every request (getUpdates included). With

package/core/actions.js

@@ -148,6 +148,14 @@ function appendMandateLine(rec, lineText, log, opts) {
 }
 
 async function handleAction(envelope) {
+  // HTML views: an event from a view page this bot sent (channels/kazee
+  // adapter, view:event). core/views.js runs its handler or wakes the
+  // conversation it came from; nothing is sent into the chat from here.
+  if (envelope.view) {
+    try { await require("./views").handleViewEvent(envelope.view, { adapter: envelope.adapter }); }
+    catch (e) { console.error("[views] handling an event failed:", e.message); }
+    return;
+  }
   // Kazee Cards: an answer to a card this bot sent (channels/kazee adapter,
   // card:response). The card ledger decides what it wakes; nothing is sent
   // into the chat from here.

package/core/lessons.js

@@ -184,7 +184,8 @@ function topicLessons(dir, { exclude = null, max = 3, maxChars = 900 } = {}) {
   const lessons = readLessons().filter((l) => l.src === dir);
   if (lessons.length === 0) return [];
   const skip = exclude || new Set(injectedLessons().map((l) => l.id));
-  const meta = reconcileMeta(lessons);
+  // The full list: reconciling just this pack would drop every other lesson's meta.
+  const meta = reconcileMeta();
   const ranked = lessons.filter((l) => !skip.has(l.id)).sort((a, b) => {
     const ma = meta[a.id] || {}, mb = meta[b.id] || {};
     return (mb.reinforced || 0) - (ma.reinforced || 0)