levix-bot 4.0.4 → 4.1.0

package/src/services/aiTools.cjs

@@ -1,16 +1,23 @@
 // The tools the AI agent can actually call.
 //
-// Each entry is { declaration, run(args, ctx), describe(args) }:
+// Each entry is { declaration, access?, run(args, ctx), describe(args) }:
 //   declaration - what Gemini sees (name + JSON schema)
+//   access      - who may call it (see aiToolAuth.cjs): the command it stands
+//                 in for, plus any role that command checks internally. A
+//                 function of the arguments when the action they pick changes
+//                 the rule (global vs chat memory). Absent = open to anyone
+//                 who may use the AI at all.
 //   run         - what happens when the model calls it; ALWAYS resolves to a
 //                 plain object (errors included) so one bad tool call doesn't
 //                 kill the turn
 //   describe    - the Arabic line shown in the live status message while the
 //                 tool runs ("🔍 ببحث عن: ...")
 //
-// Anything privileged (roles) is gated on the *caller*, not on the model: the
-// agent can ask, but the tool refuses when the person who sent the message
-// isn't allowed to do it.
+// Anything privileged is gated on the *caller* — the person whose message
+// started the run, resolved by aiToolAuth.resolveCaller() — and never on the
+// model. runTool() checks `access` before run() is reached, and tools take
+// every identity they act on (chat, sender, targets) from ctx.caller, never
+// from their arguments.
 
 const dns = require("node:dns").promises;
 const https = require("node:https");
@@ -22,7 +29,9 @@ const logger = require("../utils/logger.cjs");
 const memory = require("../utils/memory.cjs");
 const { decodeBuffer, stripHtml, decodeText } = require("../utils/textDecode.cjs");
 const { grantRole, revokeRole, listRoles } = require("../utils/permissions.cjs");
+const { authorize } = require("./aiToolAuth.cjs");
 const { isForbiddenIp } = require("../utils/providerUrl.cjs");
+const { sendBotMessage } = require("../utils/sendBotMessage.cjs");
 
 // @google/genai exports a `Type` enum (the old SDK called it `SchemaType`).
 // Its members are the uppercase wire values — Type.STRING === "STRING" — so the
@@ -345,33 +354,30 @@ function scopeOf(args) {
   return memory.normalizeScope(args?.scope);
 }
 
-// نفس قاعدة أمر !memory بالظبط: الكتابة في الذاكرة العامة والمسح محتاجين
-// أدمن/مالك. الفحص لازم يكون هنا مش في البرومبت — الموديل بيقرا صفحات ويب
-// ورسايل ناس، وأي واحدة فيهم ممكن تقوله "احفظ ده في الذاكرة العامة".
-function isBotPrivileged(ctx) {
-  return Boolean(ctx?.isOwner || ctx?.isAdmin);
-}
-
-function isChatMemoryAdmin(ctx) {
-  return isBotPrivileged(ctx) || Boolean(ctx?.isGroupAdmin);
-}
-
-function roleTargetBound(target, ctx) {
+// A role change may only target someone the sender themselves named: a
+// mention, the author of the message they replied to, or a number they typed.
+// A target the model came up with — from a web page, say — is refused.
+function roleTargetBound(target, caller) {
   const raw = String(target || "").trim();
   if (!raw) return false;
-  const ids = [...(ctx?.mentionedJids || []), ctx?.quotedParticipant].filter(Boolean);
+  const ids = [...(caller?.mentionedJids || []), caller?.quotedParticipant].filter(Boolean);
   const { sameUserSync } = require("../utils/permissions.cjs");
   if (ids.some((id) => sameUserSync(id, raw))) return true;
   const digits = raw.replace(/\D/g, "");
-  if (digits.length >= 8 && String(ctx?.userText || "").replace(/\D/g, "").includes(digits)) {
+  if (
+    digits.length >= 8 &&
+    String(caller?.text || "")
+      .replace(/\D/g, "")
+      .includes(digits)
+  ) {
     return true;
   }
   return false;
 }
 
-const NOT_PRIVILEGED = {
-  error: "only the bot owner or an admin can do this",
-};
+function roleOf(args) {
+  return String(args?.role || "admin").toLowerCase() === "owner" ? "owner" : "admin";
+}
 
 function preview(value, length = 40) {
   const text = String(value || "")
@@ -535,24 +541,26 @@ const TOOLS = {
       `🧠 Saving to ${scopeOf(args) === "global" ? "global" : "chat"} memory: ${preview(
         args?.content,
       )}`,
-    async run(args, ctx) {
+    // Same rule as `!memory add`: anyone may add to this chat, but global
+    // memory reaches every chat's prompt, so only the owner or a bot admin.
+    access: (args) => ({
+      command: "memory",
+      role: scopeOf(args) === "global" ? "botPrivileged" : undefined,
+    }),
+    async run(args, { caller }) {
       const scope = scopeOf(args);
-      // الذاكرة العامة بتتحقن في البرومبت بتاع كل الشاتات، فمش أي حد يكتب فيها.
-      if (scope === "global" && !isBotPrivileged(ctx)) {
-        return { ...NOT_PRIVILEGED, saved: false };
-      }
       const entry = memory.addMemory({
         scope,
-        chatId: ctx.chatId,
+        chatId: caller.chatId,
         content: args?.content,
-        by: ctx.senderName || ctx.senderId,
-        chatName: ctx.chatName,
+        by: caller.senderName || caller.senderId,
+        chatName: caller.chatName,
       });
       return {
         saved: true,
         id: entry.id,
         scope,
-        file: scope === "global" ? "global.md" : `chats/${ctx.chatId}.md`,
+        file: scope === "global" ? "global.md" : `chats/${caller.chatId}.md`,
       };
     },
   },
@@ -578,13 +586,15 @@ const TOOLS = {
     },
     describe: () => "🧠 جاري البحث في الذاكرة...",
     describeEn: () => "🧠 Searching memory...",
-    async run(args, ctx) {
+    // `!memory search` reads both scopes for anyone who may run `!memory`.
+    access: { command: "memory" },
+    async run(args, { caller }) {
       const wanted = String(args?.scope || "chat").toLowerCase();
       const scopes = wanted === "all" ? ["chat", "global"] : [scopeOf(args)];
       const out = {};
       for (const scope of scopes) {
         out[scope] = memory
-          .searchMemory(args?.query, { scope, chatId: ctx.chatId })
+          .searchMemory(args?.query, { scope, chatId: caller.chatId })
           .map((entry) => ({ id: entry.id, content: entry.content, at: entry.at }));
       }
       return out;
@@ -610,13 +620,17 @@ const TOOLS = {
     },
     describe: (args) => `🗑️ جاري الحذف من الذاكرة: ${preview(args?.ref)}`,
     describeEn: (args) => `🗑️ Removing from memory: ${preview(args?.ref)}`,
-    async run(args, ctx) {
+    // `!memory forget`: global needs the owner or a bot admin; chat memory
+    // also lets an admin of this group tidy their own chat.
+    access: (args) => ({
+      command: "memory",
+      role: scopeOf(args) === "global" ? "botPrivileged" : "chatModerator",
+    }),
+    async run(args, { caller }) {
       const scope = scopeOf(args);
-      const allowed = scope === "global" ? isBotPrivileged(ctx) : isChatMemoryAdmin(ctx);
-      if (!allowed) return { ...NOT_PRIVILEGED, removed: false };
       const removed = memory.removeMemory({
         scope,
-        chatId: ctx.chatId,
+        chatId: caller.chatId,
         ref: args?.ref,
       });
       return removed
@@ -647,20 +661,20 @@ const TOOLS = {
       `🔑 جاري فحص صلاحيات: ${preview(args?.target, 25)} (${args?.role || "admin"})`,
     describeEn: (args) =>
       `🔑 Checking permissions: ${preview(args?.target, 25)} (${args?.role || "admin"})`,
-    async run(args, ctx) {
-      if (!ctx.isOwner) {
-        return { error: "only the bot owner can grant roles", granted: false };
-      }
-      if (!roleTargetBound(args?.target, ctx)) {
+    // `!perm add`: that command's level (owner only unless the operator
+    // changed it), and the owner role is always the owner's to hand out.
+    access: (args) => ({ command: "perm", role: roleOf(args) === "owner" ? "owner" : undefined }),
+    async run(args, { caller }) {
+      if (!roleTargetBound(args?.target, caller)) {
         return {
           error: "mention, quote, or type the target phone number in your own request",
           granted: false,
         };
       }
-      const role = String(args?.role || "admin").toLowerCase() === "owner" ? "owner" : "admin";
+      const role = roleOf(args);
       const record = await grantRole(args?.target, role);
       logger.info(
-        { target: args?.target, role, by: ctx.senderId },
+        { target: args?.target, role, by: caller.senderId },
         "[aiTools] role granted by the agent",
       );
       return {
@@ -686,17 +700,16 @@ const TOOLS = {
     },
     describe: (args) => `🔑 جاري سحب الصلاحية من: ${preview(args?.target, 25)}`,
     describeEn: (args) => `🔑 Revoking permissions from: ${preview(args?.target, 25)}`,
-    async run(args, ctx) {
-      if (!ctx.isOwner) {
-        return { error: "only the bot owner can revoke roles", revoked: false };
-      }
-      if (!roleTargetBound(args?.target, ctx)) {
+    // `!perm remove`, gated exactly like grant_role.
+    access: (args) => ({ command: "perm", role: roleOf(args) === "owner" ? "owner" : undefined }),
+    async run(args, { caller }) {
+      if (!roleTargetBound(args?.target, caller)) {
         return {
           error: "mention, quote, or type the target phone number in your own request",
           revoked: false,
         };
       }
-      const role = String(args?.role || "admin").toLowerCase() === "owner" ? "owner" : "admin";
+      const role = roleOf(args);
       const record = await revokeRole(args?.target, role);
       return { revoked: true, role, user: record ? record.jid : args?.target };
     },
@@ -705,15 +718,15 @@ const TOOLS = {
   list_roles: {
     declaration: {
       name: "list_roles",
-      description: "List who currently holds bot owner / admin roles. Owners and admins only.",
+      description:
+        "List who currently holds bot owner / admin roles. Allowed for whoever may run !perm (the owner, by default).",
       parameters: { type: T.OBJECT, properties: {} },
     },
     describe: () => "🔑 جاري جلب قائمة الصلاحيات...",
     describeEn: () => "🔑 Fetching roles list...",
-    async run(_args, ctx) {
-      if (!ctx.isOwner && !ctx.isAdmin) {
-        return { error: "only owners and admins can list roles" };
-      }
+    // `!perm list` — the roster is `!perm`'s to show.
+    access: { command: "perm" },
+    async run() {
       const { owners, admins } = await listRoles();
       const shape = (user) => ({
         id: user.jid,
@@ -757,6 +770,317 @@ const TOOLS = {
       return { iso: now.toISOString(), timezone: timeZone, local };
     },
   },
+
+  calculate: {
+    declaration: {
+      name: "calculate",
+      description:
+        "Evaluate a math expression EXACTLY — arithmetic, percentages ('15% من 300'), powers, factorials, sqrt/log/trig and min/max/avg/sum. Always use this for numbers instead of computing in your head.",
+      parameters: {
+        type: T.OBJECT,
+        properties: {
+          expression: {
+            type: T.STRING,
+            description: "The expression, e.g. '(12 + 8) * 3', '2^10', 'sqrt(144) + 5!', '25% من 480'.",
+          },
+        },
+        required: ["expression"],
+      },
+    },
+    describe: (args) => `🧮 جاري الحساب: ${preview(args?.expression, 40)}`,
+    describeEn: (args) => `🧮 Calculating: ${preview(args?.expression, 40)}`,
+    async run(args) {
+      const expression = String(args?.expression || "").trim();
+      if (!expression) return { error: "expression is required" };
+      // Same hand-written parser the !calc command uses — never eval.
+      const calc = require("../commands/calc.cjs");
+      try {
+        const { normalized, value } = calc._evaluate(expression);
+        return { expression: normalized, result: calc._format(value) };
+      } catch (err) {
+        return { error: err?.message || "could not parse the expression" };
+      }
+    },
+  },
+
+  create_reminder: {
+    declaration: {
+      name: "create_reminder",
+      description:
+        "Schedule a reminder message that the bot sends into THIS chat at a chosen time ('remind me in 20 minutes', 'ذكّرني بكرة الصبح'). Give EITHER in_minutes OR at_time, never both.",
+      parameters: {
+        type: T.OBJECT,
+        properties: {
+          message: {
+            type: T.STRING,
+            description: "What the reminder should say — short and standalone.",
+          },
+          in_minutes: {
+            type: T.NUMBER,
+            description: "Fire this many minutes from now (1-10080, i.e. up to 7 days).",
+          },
+          at_time: {
+            type: T.STRING,
+            description:
+              "Absolute time in the bot's timezone, format 'HH:mm DD-MM-YYYY' (e.g. '22:30 07-06-2026'). Use get_datetime first to convert 'tomorrow 9am' into this.",
+          },
+        },
+        required: ["message"],
+      },
+    },
+    describe: (args) => `⏰ جاري إعداد التذكير: ${preview(args?.message, 40)}`,
+    describeEn: (args) => `⏰ Setting a reminder: ${preview(args?.message, 40)}`,
+    // Posting into a chat at a later time is exactly what `!schedule` does, so
+    // it takes `!schedule`'s permission level — whatever the dashboard sets.
+    access: { command: "schedule" },
+    async run(args, { caller }) {
+      const message = String(args?.message || "").trim().slice(0, 500);
+      if (!message) return { error: "message is required" };
+
+      const { zonedTimeToDate } = require("../utils/datetime.cjs");
+      let when;
+      if (args?.at_time !== undefined && args?.at_time !== null && String(args.at_time).trim()) {
+        const match = /^(\d{1,2}):(\d{2})\s+(\d{1,2})-(\d{1,2})-(\d{4})$/.exec(
+          String(args.at_time).trim(),
+        );
+        if (!match) {
+          return { error: "at_time must be 'HH:mm DD-MM-YYYY' in the bot's timezone" };
+        }
+        const [, hour, minute, day, month, year] = match.map(Number);
+        when = zonedTimeToDate({ year, month, day, hour, minute });
+      } else {
+        const minutes = Number(args?.in_minutes);
+        if (!Number.isFinite(minutes) || minutes <= 0) {
+          return { error: "give either in_minutes (1-10080) or at_time ('HH:mm DD-MM-YYYY')" };
+        }
+        if (minutes > 7 * 24 * 60) return { error: "in_minutes can be at most 10080 (7 days)" };
+        when = new Date(Date.now() + minutes * 60_000);
+      }
+      if (Number.isNaN(when.getTime())) return { error: "that time is not a valid date" };
+      if (when.getTime() <= Date.now()) return { error: "that time is already in the past" };
+
+      // Same job shape the !schedule command stores, delivered by the same
+      // scheduler — one mechanism, two doors into it.
+      const scheduler = require("../../scheduler.cjs");
+      const job = {
+        id: `${Date.now()}${Math.floor(Math.random() * 90) + 10}`,
+        type: "once",
+        date: when.toISOString(),
+        message,
+        targetJid: caller.chatId,
+        creatorJid: caller.senderId || caller.chatId,
+        status: "pending",
+      };
+      const result = scheduler.scheduleJobNow(job);
+      if (!result.ok) {
+        return result.reason === "no_connection"
+          ? { error: "WhatsApp is not connected right now, so the reminder cannot be armed" }
+          : { error: "the reminder time is invalid" };
+      }
+      let local;
+      try {
+        local = new Intl.DateTimeFormat("ar-EG", {
+          timeZone: settings.get("bot_timezone"),
+          dateStyle: "full",
+          timeStyle: "short",
+        }).format(when);
+      } catch {
+        local = when.toISOString();
+      }
+      return {
+        scheduled: true,
+        id: job.id,
+        willFireAt: when.toISOString(),
+        localTime: local,
+        delivery: `the bot posts it in this chat, prefixed with a "رسالة مجدولة" header`,
+      };
+    },
+  },
+
+  cancel_reminder: {
+    declaration: {
+      name: "cancel_reminder",
+      description:
+        "Cancel one pending reminder in THIS chat, by the id create_reminder returned. Allowed for whoever may run !deleteschedule here.",
+      parameters: {
+        type: T.OBJECT,
+        properties: {
+          id: { type: T.STRING, description: "The reminder id returned by create_reminder." },
+        },
+        required: ["id"],
+      },
+    },
+    describe: (args) => `⏰ جاري إلغاء التذكير: ${preview(args?.id, 20)}`,
+    describeEn: (args) => `⏰ Cancelling reminder: ${preview(args?.id, 20)}`,
+    // Deleting a scheduled job is `!deleteschedule`'s job, so its level.
+    access: { command: "deleteschedule" },
+    async run(args, { caller }) {
+      const id = String(args?.id || "").trim();
+      if (!id) return { error: "id is required" };
+
+      const scheduler = require("../../scheduler.cjs");
+      // Only jobs posting into the chat the request came from. An id is all
+      // it takes to address a job, and one can reach the model from a pasted
+      // message or a web page; `!deleteschedule` is the door for other chats.
+      const job = scheduler
+        .getScheduledJobs()
+        .find((entry) => String(entry.id) === id && entry.targetJid === caller.chatId);
+      if (!job) return { error: "no reminder with that id in this chat", cancelled: false };
+
+      scheduler.deleteScheduledJob(id);
+      return { cancelled: true, id, message: job.message };
+    },
+  },
+
+  speak: {
+    declaration: {
+      name: "speak",
+      description:
+        "Send your answer as a WhatsApp VOICE NOTE (text-to-speech) instead of text. Only when the user explicitly asks to hear it — 'قولها بصوت', 'read it aloud', 'send it as voice'. The text must be ready to be read aloud; keep it short.",
+      parameters: {
+        type: T.OBJECT,
+        properties: {
+          text: {
+            type: T.STRING,
+            description: "What the voice note says. Plain spoken prose, no markdown, no links.",
+          },
+          language: {
+            type: T.STRING,
+            description: "Optional language code, e.g. 'ar' (default) or 'en'.",
+          },
+        },
+        required: ["text"],
+      },
+    },
+    describe: (args) => `🎙️ جاري تحويل الرد لرسالة صوتية: ${preview(args?.text, 40)}`,
+    describeEn: (args) => `🎙️ Converting the reply to a voice note: ${preview(args?.text, 40)}`,
+    // Posting a voice note into this chat is what `!tts` does, so its level.
+    access: { command: "tts" },
+    async run(args, { caller, sock }) {
+      const text = String(args?.text || "").trim();
+      if (!text) return { error: "text is required" };
+      if (text.length > 3000) {
+        return { error: "text is too long for one voice note (3000 characters max)" };
+      }
+      if (!sock) return { error: "no WhatsApp connection is attached to this turn" };
+
+      const lang = String(args?.language || "ar").trim() || "ar";
+      const tts = require("../commands/tts.cjs");
+      const voice = await tts._synthesizeVoice(text, lang);
+      await sendBotMessage(
+        sock,
+        caller.chatId,
+        { audio: voice.audio, mimetype: voice.mimetype, ptt: voice.ptt },
+        { typing: false },
+      );
+      return {
+        sent: true,
+        format: voice.ptt ? "voice-note (ogg/opus)" : "audio (mp3 fallback)",
+      };
+    },
+  },
+
+  create_poll: {
+    declaration: {
+      name: "create_poll",
+      description:
+        "Create a native WhatsApp poll in THIS chat — members vote with a tap. Only when the user asks for a poll/vote ('اعمل استفتاء', 'create a poll').",
+      parameters: {
+        type: T.OBJECT,
+        properties: {
+          question: { type: T.STRING, description: "The poll question." },
+          options: {
+            type: T.ARRAY,
+            items: { type: T.STRING },
+            description: "2 to 12 distinct options.",
+          },
+          multi: {
+            type: T.BOOLEAN,
+            description: "true = members may pick several answers. Default false.",
+          },
+        },
+        required: ["question", "options"],
+      },
+    },
+    describe: (args) => `📊 جاري إنشاء الاستفتاء: ${preview(args?.question, 40)}`,
+    describeEn: (args) => `📊 Creating a poll: ${preview(args?.question, 40)}`,
+    // A poll is a group message like any other, so `!poll`'s level.
+    access: { command: "poll" },
+    async run(args, { caller, sock }) {
+      if (!sock) return { error: "no WhatsApp connection is attached to this turn" };
+      // Same builder the !poll command uses: dedupes, caps lengths, enforces
+      // WhatsApp's 2-12 option ceiling, and throws the user-facing Arabic
+      // message on any violation.
+      const poll = require("../commands/poll.cjs");
+      const content = poll._buildPollContent(args?.question, args?.options, {
+        multi: Boolean(args?.multi),
+      });
+      await sendBotMessage(sock, caller.chatId, content, { typing: false });
+      return {
+        sent: true,
+        question: content.poll.name,
+        options: content.poll.values,
+        multiAnswer: content.poll.selectableCount > 1,
+      };
+    },
+  },
+
+  summarize_chat: {
+    declaration: {
+      name: "summarize_chat",
+      description:
+        "Summarize THIS chat's stored conversation window and save only the durable, useful facts to long-term memory (max 8 short facts). Only when the user asks for it — 'لخص محادثتنا واحفظ المهم', 'summarize our chat and remember the important stuff'.",
+      parameters: {
+        type: T.OBJECT,
+        properties: {
+          scope: {
+            type: T.STRING,
+            description:
+              "'chat' (default) saves to this chat's memory only; 'global' shares with every chat and needs the owner or a bot admin.",
+          },
+        },
+      },
+    },
+    describe: () => "🧠 جاري تلخيص المحادثة وحفظ المهم...",
+    describeEn: () => "🧠 Summarizing the chat and saving what matters...",
+    // Saving chat memory is what `!memory add` allows here; the global scope
+    // reaches every chat's prompt, so it takes save_memory's owner/admin role.
+    access: (args) => ({
+      command: "memory",
+      role: scopeOf(args) === "global" ? "botPrivileged" : undefined,
+    }),
+    async run(args, { caller }) {
+      const scope = scopeOf(args);
+      const { getChatHistoryAsync } = require("../utils/storage-hub.cjs");
+      const history = await getChatHistoryAsync(caller.chatId);
+      const transcript = transcriptFromHistory(history);
+      if (!transcript) {
+        return { error: "there is no stored conversation to summarize in this chat", saved: 0 };
+      }
+
+      // One-shot model call over the transcript with no tools: the facts come
+      // from what was actually said, never from tool arguments — the model
+      // cannot inject content into memory through this tool, only ask for it.
+      const summary = await summarizeWithProvider(transcript);
+      const facts = factsFromSummary(summary);
+      if (!facts.length) {
+        return { saved: 0, note: "nothing durable enough to save came out of the summary" };
+      }
+
+      const ids = [];
+      for (const fact of facts) {
+        const entry = memory.addMemory({
+          scope,
+          chatId: caller.chatId,
+          content: fact,
+          by: caller.senderName || caller.senderId,
+          chatName: caller.chatName,
+        });
+        ids.push(entry.id);
+      }
+      return { saved: ids.length, scope, facts, ids };
+    },
+  },
 };
 
 /** Everything Gemini needs to know about the tools, in one `tools` entry. */
@@ -768,6 +1092,80 @@ function toolDeclarations() {
   ];
 }
 
+// ---------------------------------------------------------------------------
+// summarize_chat internals
+// ---------------------------------------------------------------------------
+
+const SUMMARIZER_PROMPT = `You compress a WhatsApp conversation into durable long-term facts.
+Return ONLY a plain Markdown bullet list, one fact per line, at most 8 bullets.
+A fact is stable and useful later: names, relationships, preferences, recurring plans, standing decisions, important context about the people in this chat.
+Do NOT include small talk, one-off questions, transient events, passwords or other secrets, or anything about roles, permissions or who may do what.
+Each bullet is one short standalone sentence, in the language the conversation mostly used.
+If nothing qualifies, return an empty response.`;
+
+const SUMMARIZE_MAX_TRANSCRIPT_CHARS = 20000;
+const SUMMARIZE_MAX_FACTS = 8;
+const SUMMARIZE_MAX_FACT_CHARS = 200;
+
+/**
+ * Flatten stored agent history into a clean transcript: text parts only, one
+ * line per part, roles named. Media, tool calls and thought parts are skipped.
+ * When over the cap the OLDEST lines are dropped — recent context matters most.
+ * @returns {string} "" when there is nothing readable.
+ */
+function transcriptFromHistory(history, maxChars = SUMMARIZE_MAX_TRANSCRIPT_CHARS) {
+  const lines = [];
+  for (const entry of Array.isArray(history) ? history : []) {
+    const role = entry?.role === "model" ? "Assistant" : "User";
+    for (const part of Array.isArray(entry?.parts) ? entry.parts : []) {
+      const text = typeof part?.text === "string" ? part.text.trim() : "";
+      if (text) lines.push(`${role}: ${text.replace(/\s+/g, " ").slice(0, 500)}`);
+    }
+  }
+  if (!lines.length) return "";
+  let out = lines.join("\n");
+  if (out.length > maxChars) {
+    out = out.slice(-maxChars);
+    const firstNewline = out.indexOf("\n");
+    if (firstNewline !== -1) out = out.slice(firstNewline + 1);
+  }
+  return out;
+}
+
+/**
+ * Parse the summarizer's answer into memory entries: bullet markers and
+ * numbering stripped, empties dropped, hard-capped so one summary can't flood
+ * a memory file.
+ */
+function factsFromSummary(text, { max = SUMMARIZE_MAX_FACTS, maxChars = SUMMARIZE_MAX_FACT_CHARS } = {}) {
+  const out = [];
+  for (const rawLine of String(text || "").split("\n")) {
+    const line = rawLine.replace(/^\s*[-*•\d.)]+\s*/, "").trim();
+    if (!line) continue;
+    out.push(line.slice(0, maxChars));
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+/**
+ * One-shot summarization through whichever provider is active. No tools, no
+ * search, no persona: a plain completion over the transcript so a summary
+ * can't recurse into the agent loop or spend the caller's tool budget.
+ */
+async function summarizeWithProvider(transcript) {
+  const { getProvider } = require("./aiRouter.cjs");
+  const result = await getProvider().runTurn({
+    parts: [{ text: transcript }],
+    history: [],
+    useTools: false,
+    search: false,
+    maxSteps: 1,
+    systemInstruction: SUMMARIZER_PROMPT,
+  });
+  return result?.text || "";
+}
+
 /** The status line for a tool call (falls back to the raw name). */
 function describeCall(name, args, lang = settings.get("bot_language")) {
   const tool = TOOLS[name];
@@ -784,16 +1182,49 @@ function describeCall(name, args, lang = settings.get("bot_language")) {
   }
 }
 
+/**
+ * The model's arguments, cut down to the properties the tool declares. The
+ * model writes these after reading strangers' messages and web pages, so
+ * nothing undeclared (a `senderId`, an `isOwner`) may ride along into run().
+ * Frozen, so access() and run() are guaranteed to see the same values.
+ */
+function declaredArgs(tool, args) {
+  const declared = tool.declaration?.parameters?.properties || {};
+  const out = {};
+  if (args && typeof args === "object") {
+    for (const key of Object.keys(declared)) {
+      if (Object.hasOwn(args, key)) out[key] = args[key];
+    }
+  }
+  return Object.freeze(out);
+}
+
 /**
  * Run one tool call. Never throws — a failure comes back as `{ error }` so the
  * model can apologise or try something else instead of the turn dying.
+ *
+ * `ctx.caller` must come from aiToolAuth.resolveCaller(); a tool with `access`
+ * refuses anything else before run() is reached.
  */
 async function runTool(name, args, ctx) {
   const tool = TOOLS[name];
   if (!tool) return { error: `unknown tool: ${name}` };
 
+  const input = declaredArgs(tool, args);
+  const caller = ctx?.caller;
+
   try {
-    const result = await tool.run(args || {}, ctx || {});
+    const access = typeof tool.access === "function" ? tool.access(input) : tool.access;
+    const verdict = authorize(access || null, caller);
+    if (!verdict.allowed) {
+      logger.info(
+        { tool: name, chatId: caller?.chatId, senderId: caller?.senderId },
+        "[aiTools] tool call refused",
+      );
+      return { error: verdict.error, denied: true };
+    }
+
+    const result = await tool.run(input, { caller, sock: ctx?.sock });
     return result && typeof result === "object" ? result : { result };
   } catch (err) {
     logger.warn({ err: err?.message, tool: name }, "[aiTools] tool call failed");
@@ -806,6 +1237,10 @@ module.exports = {
   toolDeclarations,
   describeCall,
   runTool,
+  transcriptFromHistory,
+  factsFromSummary,
+  summarizeWithProvider,
+  SUMMARIZER_PROMPT,
   webSearch,
   searchNews,
   searchWikipedia,