levix-bot 2.0.0 → 2.1.0

package/src/services/aiAgent.cjs

@@ -15,10 +15,10 @@
 
 const fs = require("fs");
 const path = require("path");
-const { GoogleGenerativeAI } = require("@google/generative-ai");
+const { GoogleGenAI, FunctionCallingConfigMode } = require("@google/genai");
 
 const logger = require("../utils/logger.cjs");
-const brand = require("../config/brand.cjs");
+const aiIdentity = require("../config/ai-identity.cjs");
 const settings = require("../config/settings.cjs");
 const memory = require("../utils/memory.cjs");
 const { toolDeclarations, describeCall, runTool } = require("./aiTools.cjs");
@@ -30,13 +30,19 @@ const { toolDeclarations, describeCall, runTool } = require("./aiTools.cjs");
 
 // One client per key. The dashboard can set a key on a bot that started
 // without one, so the client is built lazily and rebuilt when the key changes.
+//
+// @google/genai replaced the old `new GoogleGenerativeAI(key)` +
+// `getGenerativeModel({model, tools, systemInstruction})` pair with a single
+// client whose model and per-request configuration are passed at call time —
+// which suits Levix, because the model and the tool set are settings that may
+// change between one message and the next.
 let clientCache = { key: null, client: null };
 
 function geminiClient() {
   const key = settings.get("gemini_api_key");
   if (!key) return null;
   if (clientCache.key !== key) {
-    clientCache = { key, client: new GoogleGenerativeAI(key) };
+    clientCache = { key, client: new GoogleGenAI({ apiKey: key }) };
   }
   return clientCache.client;
 }
@@ -57,26 +63,36 @@ try {
   // Not fatal: loadPersona() falls back to DEFAULT_PERSONA below.
 }
 
-// Fallback only — the real persona is config/ai-persona.md (editable from the
-// dashboard). No name in here: identity comes from brand.cjs and is prepended
-// separately so it survives any edit to the persona.
-const DEFAULT_PERSONA = `بوت واتساب ذكي وخفيف الظل.
-اتكلم مصري عامي، ردودك قصيرة ومباشرة، واستخدم أدواتك بدل التخمين.`;
+// Fallback only, for the moment between "the file is missing" and "the template
+// has been copied". The real persona is the operator's copy of ai-persona.md.
+// No product identity in here: that comes from src/config/ai-identity.cjs and is
+// prepended separately, so it survives any edit to the persona.
+const DEFAULT_PERSONA = `You are a capable personal WhatsApp assistant.
+Be concise and direct by default, reply in the language the user writes in, and
+use your tools instead of guessing when something needs to be looked up.`;
 
-let personaCache = { text: null, mtime: 0 };
+let personaCache = { text: null, stamp: null };
 
-/** The persona file, re-read whenever it changes on disk. */
+/**
+ * The persona file, re-read whenever it changes on disk.
+ *
+ * Keyed on the nanosecond mtime AND the size, not `mtimeMs`: that is a
+ * millisecond float, and two saves inside the same millisecond — the dashboard
+ * writing twice, or a test — produced the same key, so the second edit was
+ * served from the cache and the operator's change silently did not apply.
+ */
 function loadPersona() {
   try {
-    const { mtimeMs } = fs.statSync(PERSONA_FILE);
-    if (personaCache.text && personaCache.mtime === mtimeMs) {
+    const stat = fs.statSync(PERSONA_FILE, { bigint: true });
+    const stamp = `${stat.mtimeNs}:${stat.size}`;
+    if (personaCache.text && personaCache.stamp === stamp) {
       return personaCache.text;
     }
     const raw = fs.readFileSync(PERSONA_FILE, "utf8").trim();
     // Everything above the `---` separator is a note to the human editing the
     // file, not part of the prompt.
     const body = raw.includes("\n---") ? raw.split(/\n---\s*\n/).slice(1).join("\n---\n") : raw;
-    personaCache = { text: body.trim() || DEFAULT_PERSONA, mtime: mtimeMs };
+    personaCache = { text: body.trim() || DEFAULT_PERSONA, stamp };
     return personaCache.text;
   } catch {
     return DEFAULT_PERSONA;
@@ -96,13 +112,12 @@ function nowLabel() {
 }
 
 /**
- * frozen identity + persona + who/where/when + long-term memory.
+ * product identity + persona + who/where/when + long-term memory.
  *
- * The identity block goes FIRST and does not come from the persona file: the
- * operator can rewrite the persona from the dashboard, but not the bot's name
- * or who wrote it.
- * Deliberately short: the old prompt was a page of rules, and the operator
- * asked for it to go away.
+ * The identity block goes FIRST and does not come from the persona file. The
+ * operator owns the persona and can rewrite it from the dashboard; they do not
+ * own what the product is called or who wrote it, so that part is code (see
+ * src/config/ai-identity.cjs) and is never rendered by the panel.
  */
 function buildSystemInstruction(context = {}) {
   const {
@@ -116,17 +131,19 @@ function buildSystemInstruction(context = {}) {
   } = context;
 
   const runtime = [
-    "## السياق الحالي",
-    `- المتكلم: ${senderName || "غير معروف"}${senderId ? ` (${senderId})` : ""}`,
-    `- صلاحيته: ${isOwner ? "مالك البوت" : isAdmin ? "أدمن" : "مستخدم عادي"}`,
-    `- المكان: ${isGroup ? `جروب${chatName ? ` اسمه "${chatName}"` : ""}` : "محادثة خاصة"}`,
-    `- الوقت دلوقتي: ${nowLabel()}`,
-    "- في جروب: الكل شايف ردك، فخلي بالك.",
+    "# Current context",
+    `- Speaking to you: ${senderName || "unknown"}${senderId ? ` (${senderId})` : ""}`,
+    `- Their role: ${isOwner ? "bot owner" : isAdmin ? "bot admin" : "ordinary user"}`,
+    `- Where: ${isGroup ? `a group chat${chatName ? ` called "${chatName}"` : ""}` : "a private one-to-one chat"}`,
+    `- Local time now: ${nowLabel()}`,
+    isGroup
+      ? "- This is a group: every participant sees your reply. Say nothing here that belongs to one person."
+      : "- This is a private chat: only this person sees your reply.",
   ].join("\n");
 
   const memoryBlock = memory.buildMemoryContext(chatId);
 
-  return [brand.identityPrompt, loadPersona(), runtime, memoryBlock]
+  return [aiIdentity.systemBlock, loadPersona(), runtime, memoryBlock]
     .filter(Boolean)
     .join("\n\n");
 }
@@ -152,12 +169,19 @@ function trimHistory(history) {
   return out;
 }
 
-/** Gemini file URIs live ~48h; after that every call fails on the old parts. */
+/**
+ * Gemini file URIs live ~48h; after that every call fails on the old parts.
+ *
+ * @google/genai throws its own `ApiError` with a numeric `status`, where the
+ * old SDK put the code in a handful of different places. Both are still read:
+ * the shapes are cheap to check and the stored history can outlive an upgrade.
+ */
 function isFileReferenceError(error) {
   if (!error) return false;
   const status =
     error.status ||
     error.statusCode ||
+    error.code ||
     error.response?.status ||
     error.error?.code;
   const message = `${error.message || ""} ${error.details || ""}`.toLowerCase();
@@ -204,6 +228,143 @@ function isAgentEnabled() {
   return Boolean(geminiClient()) && settings.get("ai_agent");
 }
 
+// ===========================================================================
+// Google Search — Gemini's own, not ours
+// ===========================================================================
+//
+// `{ googleSearch: {} }` is a BUILT-IN tool: the model decides when a question
+// needs the web, Google runs the search inside the same request, and the answer
+// comes back already grounded with the sources it used. There is no
+// google_search function declaration anywhere in Levix, nothing to execute in
+// the tool loop, and no search API key — deliberately. A hand-rolled search
+// tool would be a second, worse implementation of something the model already
+// does better.
+//
+// The shape is the Gemini 2.x one. The older `googleSearchRetrieval` is what
+// 1.5 models take; this SDK's TypeScript types only know that one, but the SDK
+// passes `tools` through to the REST API untouched (dist/index.js:1377), so the
+// 2.x shape reaches the model exactly as written.
+
+const GOOGLE_SEARCH_TOOL = Object.freeze({ googleSearch: {} });
+
+/** Gemini-only. Nothing here is offered to Groq or any other provider. */
+function googleSearchEnabled() {
+  return settings.get("ai_google_search") === true;
+}
+
+/**
+ * The `tools` array for one request.
+ *
+ * Custom function declarations and the built-in search go in the same array;
+ * Gemini 2.x accepts both together. When it does not (see runAgent), the search
+ * half is dropped and Levix's own tools are kept — never the other way round.
+ */
+function buildTools({ useTools = true, search = googleSearchEnabled() } = {}) {
+  const tools = [];
+  if (useTools) tools.push(...toolDeclarations());
+  if (search) tools.push(GOOGLE_SEARCH_TOOL);
+  return tools;
+}
+
+/**
+ * The tool configuration that lets a built-in tool and custom functions run in
+ * the same request.
+ *
+ * Gemini 3 calls this "tool context circulation": the server runs Google Search
+ * itself, and `includeServerSideToolInvocations` is what puts those server-side
+ * calls into the conversation so the custom functions can see them. Without the
+ * flag the combination is refused outright.
+ *
+ * Turning it on also constrains function calling to VALIDATED — AUTO is not
+ * supported alongside it — so the two are set together or not at all.
+ *
+ * Returns undefined when there is nothing to combine, which leaves the ordinary
+ * AUTO behaviour exactly as it was.
+ */
+function buildToolConfig({ useTools = true, search = googleSearchEnabled() } = {}) {
+  if (!useTools || !search) return undefined;
+  return {
+    includeServerSideToolInvocations: true,
+    functionCallingConfig: { mode: FunctionCallingConfigMode.VALIDATED },
+  };
+}
+
+/**
+ * Does this error mean "this model will not take search and functions at once"?
+ *
+ * Some model/API combinations refuse the mix with a 400. Rather than quietly
+ * shipping fewer tools forever, runAgent() retries once without the built-in
+ * search and says so in the log — Levix's own tools are the ones that must
+ * survive, because commands depend on them.
+ */
+function isToolCombinationError(error) {
+  const status = Number(error?.status ?? error?.statusCode ?? error?.error?.code ?? 0);
+  const message = `${error?.message || ""} ${error?.statusText || ""}`.toLowerCase();
+  if (status && status !== 400) return false;
+  return (
+    message.includes("tool") &&
+    (message.includes("not supported") ||
+      message.includes("unsupported") ||
+      message.includes("only one tool") ||
+      message.includes("cannot be used") ||
+      message.includes("at most one"))
+  );
+}
+
+/**
+ * Pull the sources Gemini actually grounded on out of one response.
+ *
+ * Reads only real grounding metadata — `candidates[].groundingMetadata` — so a
+ * turn where the model answered from its own knowledge yields nothing and no
+ * Sources block is ever invented.
+ */
+function extractSources(response) {
+  const out = [];
+  // The path is unchanged from the old SDK: candidates[].groundingMetadata
+  // .groundingChunks[].web.{uri,title}. Verified against @google/genai's
+  // GroundingMetadata / GroundingChunkWeb, which also adds a Vertex-only
+  // `domain` field that the Gemini Developer API does not populate.
+  for (const candidate of response?.candidates || []) {
+    const grounding = candidate?.groundingMetadata;
+    for (const chunk of grounding?.groundingChunks || []) {
+      const uri = chunk?.web?.uri;
+      if (!uri) continue;
+      out.push({ uri, title: chunk.web.title || hostOf(uri) || "source" });
+    }
+  }
+  return out;
+}
+
+function hostOf(uri) {
+  try {
+    return new URL(uri).hostname.replace(/^www\./, "");
+  } catch {
+    return null;
+  }
+}
+
+/** How many sources are worth putting under a WhatsApp answer. */
+const MAX_SOURCES = 5;
+
+/**
+ * A compact Sources block, or "" when there is nothing to cite.
+ *
+ * Deduplicated by URL, capped, and written in the plain style the rest of the
+ * bot uses — no Markdown links, which WhatsApp renders literally.
+ */
+function formatSources(sources) {
+  const seen = new Set();
+  const lines = [];
+  for (const source of sources || []) {
+    if (!source?.uri || seen.has(source.uri)) continue;
+    seen.add(source.uri);
+    const label = String(source.title || hostOf(source.uri) || "source").trim();
+    lines.push(`• ${label} — ${source.uri}`);
+    if (lines.length >= MAX_SOURCES) break;
+  }
+  return lines.length ? `\n\n*Sources:*\n${lines.join("\n")}` : "";
+}
+
 /**
  * Run one agent turn.
  *
@@ -227,24 +388,61 @@ async function runAgent({
   if (!genAI) throw new Error("GEMINI_API_KEY غير معرف");
 
   const stepBudget = maxSteps ?? settings.get("ai_max_tool_steps");
-
-  const model = genAI.getGenerativeModel({
-    model: settings.get("gemini_model"),
-    systemInstruction: buildSystemInstruction(context),
-    ...(useTools ? { tools: toolDeclarations() } : {}),
-  });
-
-  const chat = model.startChat({ history: trimHistory(history) });
+  const systemInstruction = buildSystemInstruction(context);
+  const trimmed = trimHistory(history);
+  const model = settings.get("gemini_model");
+
+  // `ai.chats` rather than a hand-rolled contents array on purpose. Gemini 3
+  // returns a `thoughtSignature` on the parts it produces and expects it back
+  // on the following turns of a multi-step tool run; the Chat class records
+  // `candidates[0].content` verbatim into its history, signature included, so
+  // circulating it is not something this file has to remember to do. Levix
+  // persists that same history, and a signature is a plain string, so it
+  // survives the round trip through SQLite too.
+  const openChat = (search) => {
+    const tools = buildTools({ useTools, search });
+    const toolConfig = buildToolConfig({ useTools, search });
+    return genAI.chats.create({
+      model,
+      history: trimmed,
+      config: {
+        systemInstruction,
+        ...(tools.length ? { tools } : {}),
+        ...(toolConfig ? { toolConfig } : {}),
+      },
+    });
+  };
+
+  let searchOffered = googleSearchEnabled();
+  let chat = openChat(searchOffered);
   const toolCalls = [];
+  // Only ever filled from real grounding metadata; see extractSources().
+  const sources = [];
+
+  let response;
+  try {
+    response = await chat.sendMessage({ message: parts });
+  } catch (error) {
+    // Defensive only. Gemini 3 takes the built-in search and custom functions
+    // in one request, so this is not the expected path — but a model that
+    // refuses the combination must not cost Levix its own tools, which the
+    // commands depend on. Search is what gets dropped, never the functions.
+    if (!searchOffered || !isToolCombinationError(error)) throw error;
+    logger.warn(
+      { err: error?.message, model },
+      "[aiAgent] this model refused Google Search together with function tools — retrying with functions only"
+    );
+    searchOffered = false;
+    chat = openChat(false);
+    response = await chat.sendMessage({ message: parts });
+  }
 
-  let result = await chat.sendMessage(parts);
+  sources.push(...extractSources(response));
   let steps = 0;
 
   while (steps < stepBudget) {
-    const calls =
-      (typeof result.response?.functionCalls === "function"
-        ? result.response.functionCalls()
-        : null) || [];
+    // `functionCalls` is a getter on the new response object, not a method.
+    const calls = response.functionCalls || [];
     if (!calls.length) break;
 
     steps += 1;
@@ -264,28 +462,42 @@ async function runAgent({
         "[aiAgent] tool call"
       );
 
-      let response;
+      // Named apart from the outer `response` on purpose: that one is the
+      // model's reply and is reassigned at the bottom of this loop.
+      let toolResult;
       try {
-        response = await withTimeout(
+        toolResult = await withTimeout(
           runTool(call.name, call.args, context),
           settings.get("ai_tool_timeout_ms"),
           call.name
         );
       } catch (err) {
-        response = { error: err?.message || String(err) };
+        toolResult = { error: err?.message || String(err) };
       }
       responses.push({
-        functionResponse: { name: call.name, response },
+        functionResponse: {
+          // Echoed back when the model supplied one: with several calls in a
+          // single turn the id is how the API pairs each result with its call.
+          ...(call.id ? { id: call.id } : {}),
+          name: call.name,
+          response: toolResult,
+        },
       });
     }
 
     if (status) await status.update("🤖 بجهّز الرد...");
-    result = await chat.sendMessage(responses);
+    // One message carrying every functionResponse part, which is what the API
+    // expects when the model asked for several calls in one turn.
+    response = await chat.sendMessage({ message: responses });
+    // Grounding can happen on any turn, not just the first.
+    sources.push(...extractSources(response));
   }
 
+  // `text` is a getter now, and it returns undefined rather than throwing when
+  // the candidate has no text part.
   let text = "";
   try {
-    text = result.response.text();
+    text = response.text ?? "";
   } catch (err) {
     logger.warn({ err: err?.message }, "[aiAgent] response had no text part");
   }
@@ -297,16 +509,34 @@ async function runAgent({
 
   let newHistory = [];
   try {
-    newHistory = trimHistory(await chat.getHistory());
+    // Synchronous in this SDK, and `true` asks for the curated history — the
+    // turns the API would actually accept back, with empty or invalid model
+    // outputs left out. That is exactly what Levix wants to persist.
+    newHistory = trimHistory(chat.getHistory(true));
   } catch (err) {
     logger.warn({ err: err?.message }, "[aiAgent] could not read chat history");
   }
 
-  return { text, history: newHistory, toolCalls, steps };
+  return {
+    text,
+    history: newHistory,
+    toolCalls,
+    steps,
+    // Empty unless Gemini actually grounded this answer on a search.
+    sources,
+    searchOffered,
+  };
 }
 
 module.exports = {
   runAgent,
+  buildTools,
+  buildToolConfig,
+  googleSearchEnabled,
+  extractSources,
+  formatSources,
+  isToolCombinationError,
+  GOOGLE_SEARCH_TOOL,
   buildSystemInstruction,
   loadPersona,
   isAgentEnabled,

package/src/services/aiTools.cjs

@@ -26,21 +26,23 @@ const {
   listRoles,
 } = require("../utils/permissions.cjs");
 
-// The SDK exports a SchemaType enum; fall back to the wire values if a future
-// version drops it, so a rename can't take the whole agent down.
-let SchemaType = null;
+// @google/genai exports a `Type` enum (the old SDK called it `SchemaType`).
+// Its members are the uppercase wire values — Type.STRING === "STRING" — so the
+// fallback below is the same thing spelled out, and a future rename can't take
+// the whole agent down with it.
+let Type = null;
 try {
-  ({ SchemaType } = require("@google/generative-ai"));
+  ({ Type } = require("@google/genai"));
 } catch {
-  SchemaType = null;
+  Type = null;
 }
-const T = SchemaType || {
-  STRING: "string",
-  NUMBER: "number",
-  INTEGER: "integer",
-  BOOLEAN: "boolean",
-  ARRAY: "array",
-  OBJECT: "object",
+const T = Type || {
+  STRING: "STRING",
+  NUMBER: "NUMBER",
+  INTEGER: "INTEGER",
+  BOOLEAN: "BOOLEAN",
+  ARRAY: "ARRAY",
+  OBJECT: "OBJECT",
 };
 
 const UA =

package/src/utils/storage.esm.js

@@ -34,6 +34,11 @@ export const getAllNotes = store.getAllNotes;
 export const deleteNote = store.deleteNote;
 export const getAllNotesFlat = store.getAllNotesFlat;
 
+// ===== WhatsApp auth =====
+// Only the wipe. Reads and writes go through src/auth/, which owns the
+// serialisation; unlinking has to work with no socket alive to ask.
+export const clearAuthState = store.authClearAll;
+
 // ===== Pairing QR =====
 export const saveQrCode = store.saveQrCode;
 export const getQrCode = store.getQrCode;

package/views/dashboard.ejs

@@ -100,17 +100,34 @@
           <section class="view" id="view-connection">
             <div class="section-head">
               <h2>Connection</h2>
-              <p>Link a WhatsApp account, or unlink the one in use.</p>
+              <p>Start or stop the WhatsApp session, and link or unlink an account.</p>
             </div>
 
             <div class="card">
               <div class="card-head">
-                <h2>Account</h2>
+                <h2>Session</h2>
                 <div class="spacer"></div>
                 <span id="conn-state"></span>
               </div>
 
-              <div id="qr-panel">
+              <div class="hint" id="conn-detail"></div>
+
+              <div class="hint" id="conn-proxy"></div>
+
+              <div class="inline" style="margin-top:12px">
+                <button class="btn btn-primary" id="start-btn">Start session</button>
+                <button class="btn" id="reconnect-btn">Reconnect to apply</button>
+                <button class="btn" id="stop-btn">Stop session</button>
+                <button class="btn btn-danger" id="unlink-btn">Unlink account</button>
+                <button class="btn" id="restart-btn">Restart bot</button>
+              </div>
+              <div class="hint" style="margin-top:8px">
+                Levix runs whether or not WhatsApp is connected. Starting the session is
+                the only thing that opens a connection; restart only comes back on its own
+                under a supervisor (pm2, systemd, Docker).
+              </div>
+
+              <div id="qr-panel" style="display:none">
                 <div class="qr-box">
                   <div class="qr-frame" id="qr-frame"></div>
                   <div class="hint" id="qr-note">Waiting for a QR code…</div>
@@ -121,14 +138,6 @@
                   </ol>
                 </div>
               </div>
-
-              <div class="inline" style="margin-top:12px">
-                <button class="btn btn-danger" id="unlink-btn">Unlink account</button>
-                <button class="btn" id="restart-btn">Restart bot</button>
-              </div>
-              <div class="hint" style="margin-top:8px">
-                Restart only comes back on its own under a supervisor (pm2, systemd, Docker).
-              </div>
             </div>
           </section>
 

package/views/qr.ejs

@@ -55,6 +55,10 @@
             <li>Settings → Linked devices → Link a device.</li>
             <li>Point the camera at the code above.</li>
           </ol>
+          <div class="hint">
+            No code yet? Levix only connects when you ask it to — press
+            <strong>Start session</strong> on the dashboard's Connection screen.
+          </div>
         </div>
 
         <a class="btn" href="/">Back to the dashboard</a>
@@ -63,7 +67,7 @@
       <div class="foot"><%= brand.name %> · by <%= brand.developer %></div>
     </div>
 
-    <script src="/socket.io/socket.io.js"></script>
+    <script src="/socket.io.min.js"></script>
     <script src="/qrcode.min.js"></script>
     <script>
       (() => {
@@ -94,13 +98,29 @@
         if (initial) render(initial);
         else setState("Waiting for a code…", "");
 
+        function clear(text, kind) {
+          painted = null;
+          frame.innerHTML = "";
+          setState(text, kind || "");
+        }
+
         const socket = io();
         socket.on("qr", render);
-        socket.on("status_update", (data) => {
-          if (data.status === "Connected") {
+
+        // The backend drops a code the moment it stops being scannable. Without
+        // this the page sat on an expired QR forever, and somebody would keep
+        // pointing a phone at it.
+        socket.on("qr_cleared", () => clear("Waiting for a code…", ""));
+
+        socket.on("session", (state) => {
+          if (state.state === "connected") {
             frame.innerHTML = '<div style="padding:60px 30px;color:#0d1730">Linked ✓</div>';
+            painted = null;
             setState("Connected", "on");
+            return;
           }
+          if (state.state === "waiting_for_qr") return; // the qr event paints it
+          clear(state.canStart ? "Not started — start it from the dashboard" : "Connecting…", "");
         });
       })();
     </script>