micro-models-agent 2.11.0 → 2.13.1

package/dist/tools/question.js

@@ -1,23 +1,38 @@
+/** Тул вопросов юзеру: меню, memory pre-check, батч-cap, сессионные ответы. */
 import { t } from "../i18n/index";
 import { askUser } from "./user-input";
-const DESCRIPTION = `Use this tool when you need to ask the user questions during execution. This allows you to:
-1. Gather user preferences or requirements
-2. Clarify ambiguous instructions
-3. Get decisions on implementation choices as you work
-4. Offer choices to the user about what direction to take.
-
-Usage notes:
-- When "custom" is enabled (default), a "Type your own answer" option is added automatically; don't include "Other" or catch-all options
-- Answers are returned as arrays of labels; set "multiple": true to allow selecting more than one
-- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
-- Execution blocks until the user answers every question
-- Omit "options" for a free-text question`;
+import { MemoryStore } from "../modules/memory/store";
+import { globalMemoryDir } from "../config/paths";
+const DESCRIPTION = `Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- When "custom" is enabled (default), a "Type your own answer" option is added automatically; don't include "Other" or catch-all options
+- Answers are returned as arrays of labels; set "multiple": true to allow selecting more than one
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+- Execution blocks until the user answers every question
+- Omit "options" for a free-text question
+- Never ask choice questions as a plain-text list in your reply — always call
+  this tool (it renders interactive buttons and blocks until answered).
+  When the user asks for a Q&A session with options, use this tool for every
+  question, not chat text
+- Before asking, the tool checks agent memory itself: questions memory
+  already answers are skipped (reported back, not asked) — never ask what
+  is already known
+- Answers live only in the current session; nothing is written to memory.
+  Call "remember" separately to persist something, and only when asked to
+- At most 3 unknown questions are asked per call; keep batches small`;
+/** Проверяет форму опции (label + description — строки). */
 function isOption(val) {
     if (!val || typeof val !== "object")
         return false;
     const opt = val;
     return typeof opt.label === "string" && typeof opt.description === "string";
 }
+/** Нормализует args в спеки (массив + legacy `{ question }`). Битые — пропуск. */
 function normalizeQuestions(args) {
     const raw = args.questions;
     if (Array.isArray(raw)) {
@@ -29,8 +44,8 @@ function normalizeQuestions(args) {
             if (typeof q.question !== "string" || !q.question.trim())
                 continue;
             const options = Array.isArray(q.options) ? q.options.filter(isOption) : undefined;
-            // An explicitly provided options array with no valid entries is a
-            // malformed call — skip the question instead of blocking on stdin.
+            // Явно данный массив опций без валидных записей — malformed вызов:
+            // вопрос пропустить, а не висеть на stdin.
             if (Array.isArray(q.options) && options.length === 0)
                 continue;
             specs.push({
@@ -43,17 +58,120 @@ function normalizeQuestions(args) {
         }
         return specs;
     }
-    // Legacy format: { question: "..." } — plain free-text question.
+    // Legacy-формат: { question: "..." } — plain free-text вопрос.
     if (typeof args.question === "string" && args.question.trim()) {
         return [{ question: args.question }];
     }
     return [];
 }
+/** Максимум незнакомых вопросов за вызов — большие батчи малые модели теряют. */
+export const MAX_QUESTIONS_PER_CALL = 3;
+/** Токенный bound memory pre-check: хиты репортятся повопросно. */
+const MAX_MEMORY_HITS = 2;
+const MAX_HIT_CHARS = 200;
+/**
+ * Делит спеки на известные памяти (репорт, не спрашивать) и незнакомые.
+ * Чистая через инжектируемый lookup — тесты не трогают реальный memory dir.
+ */
+export function splitByMemory(specs, lookup) {
+    const known = [];
+    const unknown = [];
+    for (const spec of specs) {
+        const hits = lookup(spec);
+        if (hits.length > 0)
+            known.push({ spec, hits });
+        else
+            unknown.push(spec);
+    }
+    return { known, unknown };
+}
+/**
+ * Значимые слова текста: lowercase, unicode-разбивка, длина ≥ 4. Короче
+ * ("тип", "для", "что") — шум для overlap-мэтчинга.
+ */
+export function extractKeywords(...texts) {
+    const out = new Set();
+    for (const text of texts) {
+        if (!text)
+            continue;
+        for (const word of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+            if (word.length >= 4)
+                out.add(word);
+        }
+    }
+    return [...out];
+}
+/**
+ * Строка памяти считается ответом, только если делит со вопросом не меньше
+ * стольких distinct keywords. Одно общее слово ("какой", "город") — обычно
+ * совпадение: пропуск на нём ответил бы из stale-данных вместо вопроса.
+ * Precision важнее recall: промах просто спросит.
+ */
+const MIN_KEYWORD_OVERLAP = 2;
+/**
+ * Keyword-overlap поиск по памяти через инжектируемый покейвордный поиск.
+ * Чистая — прод-обвязка (`lookupMemory`) передаёт `MemoryStore.search`.
+ */
+export function collectMemoryHits(searchOne, spec) {
+    const keywords = extractKeywords(spec.question, spec.header, ...(spec.options ?? []).flatMap((o) => [o.label, o.description]));
+    if (keywords.length === 0)
+        return [];
+    const lines = new Map();
+    for (const kw of keywords) {
+        let hits;
+        try {
+            hits = searchOne(kw);
+        }
+        catch {
+            continue;
+        }
+        for (const r of hits) {
+            const key = `${r.file}\n${r.match}`;
+            let entry = lines.get(key);
+            if (!entry) {
+                entry = { text: `[${r.file}] ${r.match}`, matched: new Set() };
+                lines.set(key, entry);
+            }
+            entry.matched.add(kw);
+        }
+    }
+    return [...lines.values()]
+        .filter((e) => e.matched.size >= MIN_KEYWORD_OVERLAP)
+        .slice(0, MAX_MEMORY_HITS)
+        .map((e) => e.text.slice(0, MAX_HIT_CHARS));
+}
+/**
+ * Fail-open поиск по памяти: нечитаемая/отсутствующая память вопрос не блокирует.
+ * Возврат — короткие `file: match`-сниппеты, токенно ограниченные.
+ */
+function lookupMemory(spec) {
+    try {
+        const store = new MemoryStore(globalMemoryDir());
+        return collectMemoryHits((kw) => store.search(kw), spec);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Тестовый шов: `memorySearch` на контексте стабит memory pre-check (тот же
+ * override-паттерн, что `ToolContext.agentFactory` — моки Bun-модулей глобальны
+ * на процесс, plain vi.mock тут не годится).
+ */
+function resolveSearch(ctx) {
+    const stub = ctx
+        .memorySearch;
+    return typeof stub === "function" ? stub : lookupMemory;
+}
+/** Тул вопросов: выбор/мультивыбор/free-text, memory pre-check, батч-cap 3. */
 export const questionTool = {
     name: "question",
     icon: "❓",
     description: DESCRIPTION,
     tags: ["core"],
+    // Интерактивные тулы переживают сужение тегов: спросить модель должна уметь
+    // всегда, при любом типе задачи (P5 auto-narrowing).
+    alwaysOn: true,
     interactive: true,
     parameters: {
         type: "object",
@@ -113,10 +231,18 @@ export const questionTool = {
         if (questions.length === 0) {
             return { success: false, output: t("tool.question.no_questions") };
         }
+        // Memory pre-check: известное памяти не спрашивать. Известные вопросы —
+        // репорт, не опрос. В память ничего не пишется: ответы живут только в сессии
+        // (persist — отдельным "remember" по просьбе).
+        const { known, unknown } = splitByMemory(questions, resolveSearch(ctx));
+        // Батч-cap: не больше MAX_QUESTIONS_PER_CALL за раз, остаток — пометкой,
+        // чтобы модель довызвала, а не потеряла вопросы молча.
+        const truncated = unknown.length - MAX_QUESTIONS_PER_CALL;
+        const toAsk = truncated > 0 ? unknown.slice(0, MAX_QUESTIONS_PER_CALL) : unknown;
         const answers = [];
-        for (let i = 0; i < questions.length; i++) {
-            const q = questions[i];
-            const progress = questions.length > 1
+        for (let i = 0; i < toAsk.length; i++) {
+            const q = toAsk[i];
+            const progress = toAsk.length > 1
                 ? t("tool.question.progress", {
                     current: i + 1,
                     total: questions.length,
@@ -130,12 +256,33 @@ export const questionTool = {
                 progress,
             }, ctx.promptIO));
         }
-        const formatted = questions
-            .map((q, i) => `"${q.question}"="${answers[i].length ? answers[i].join(", ") : t("tool.question.unanswered")}"`)
-            .join(", ");
-        return {
-            success: true,
-            output: t("tool.question.answered", { formatted }),
-        };
+        const parts = [];
+        if (toAsk.length > 0) {
+            const formatted = toAsk
+                .map((q, i) => `"${q.question}"="${answers[i].length ? answers[i].join(", ") : t("tool.question.unanswered")}"`)
+                .join(", ");
+            parts.push(t("tool.question.answered", { formatted }));
+        }
+        else {
+            parts.push(t("tool.question.memory_only"));
+        }
+        if (known.length > 0) {
+            const formatted = known
+                .map((k) => `"${k.spec.question}"="${k.hits.join("; ")}"`)
+                .join(", ");
+            parts.push(t("tool.question.memory_known", { formatted }));
+        }
+        parts.push(t("tool.question.session_only"));
+        if (truncated > 0) {
+            parts.push(t("tool.question.batch_truncated", {
+                shown: MAX_QUESTIONS_PER_CALL,
+                total: unknown.length,
+            }));
+        }
+        // display:"" гасит UI-эхо (tool-batch предпочитает display и пропускает
+        // пустые): модели — полный output в role:"tool", чату — только блок вопроса
+        // с ↳-ответами. Текст output — model-facing директивы (сессия/память/батч),
+        // не контент юзера: и verbose идёт через tool_end, не meta.
+        return { success: true, output: parts.join(" "), display: "" };
     },
 };

package/dist/tools/read-file.js

@@ -1,3 +1,4 @@
+/** Тул чтения файла: постранично, со стримингом больших файлов. */
 import { readFileSync, existsSync, statSync, openSync, readSync, closeSync } from "fs";
 import { extname } from "path";
 import { t } from "../i18n/index";
@@ -5,27 +6,27 @@ import { isPathInScope } from "../modules/security/path-validator";
 import { DEFAULT_SECURITY_CONFIG } from "../config/security";
 import { logSecurityBlock } from "../modules/security/audit-log";
 import { safeResolvePath } from "./path-utils";
+import { errMsg } from "../utils";
 /**
- * Default lines per read_file call. Deliberately much larger than
- * MAX_PREVIEW_LINES (15): a 15-line default forces the model to issue 10-17
- * calls per file, which floods the context and drives compaction every 15
- * iterations (observed: 96 read_file calls, App.tsx read 23x, then 11
- * compactions in ~20 min that deleted the user's task mid-turn). 300 lines
- * covers typical component files in one call while still capping output.
+ * Строк на вызов read_file по умолчанию. Намеренно больше MAX_PREVIEW_LINES
+ * (15): дефолт 15 заставлял модель делать 10–17 вызовов на файл, что заливало
+ * контекст и дёргало компакцию каждые 15 итераций (наблюдено: 96 вызовов
+ * read_file, 11 компакций за ~20 мин со сносом задачи). 300 строк покрывают
+ * типичный файл за один вызов, вывод всё равно ограничен.
  */
 const DEFAULT_LIMIT = 300;
+/** Жёсткий потолок явного `limit` (тул исключён из усечения по бюджету). */
+const MAX_READ_LIMIT = 2000;
 /**
- * Files larger than this are read through a bounded streaming path instead of
- * readFileSync (which loads the whole file into memory just to slice a few
- * hundred lines).
+ * Файлы крупнее — через ограниченный стриминг вместо readFileSync (который
+ * грузит весь файл в память ради пары сотен строк).
  */
 const LARGE_FILE_BYTES = 1024 * 1024;
 const STREAM_CHUNK = 256 * 1024;
 /**
- * Bounded line-slice read for large files: streams the file in chunks,
- * collects only the requested [offset, offset+limit) window, then counts the
- * remaining newlines raw (no decode) to produce the total. Memory stays
- * bounded regardless of file size.
+ * Ограниченное построчное чтение больших файлов: стримит чанками, собирает
+ * только окно [offset, offset+limit), остаток переводов строк считает сырым
+ * (без декода) для total. Память ограничена при любом размере файла.
  */
 function readLineSlice(path, offset, limit) {
     const fd = openSync(path, "r");
@@ -52,7 +53,7 @@ function readLineSlice(path, offset, limit) {
                 lineNumber++;
             }
             if (lineNumber >= endLine && collected.length >= limit) {
-                // Window complete — count remaining newlines without decoding.
+                // Окно собрано — остаток переводов строк считаем без декодирования.
                 const rest = [];
                 while (true) {
                     const n = readSync(fd, buf, 0, STREAM_CHUNK, pos);
@@ -65,7 +66,10 @@ function readLineSlice(path, offset, limit) {
                 for (let i = 0; i < tail.length; i++)
                     if (tail[i] === 0x0a)
                         total++;
-                total++; // last line has no trailing newline
+                // Плюс финальная строка без перевода — только если файл им не
+                // кончается, иначе посчитаем фантомную пустую строку.
+                if (tail.length > 0 && tail[tail.length - 1] !== 0x0a)
+                    total++;
                 return { selected: collected.join("\n"), total };
             }
         }
@@ -80,12 +84,14 @@ function readLineSlice(path, offset, limit) {
         closeSync(fd);
     }
 }
+/** Читает файл постранично (offset/limit); кешируемый, с cap вывода. */
 export const readFileTool = {
     name: "read_file",
     icon: "👀",
     description: `Read a file from the filesystem. Reads up to ${DEFAULT_LIMIT} lines at a time by default; use offset to page through large files.`,
     tags: ["file", "code"],
     boundedOutput: true,
+    cacheable: true,
     parameters: {
         type: "object",
         properties: {
@@ -107,8 +113,7 @@ export const readFileTool = {
         const securityPaths = ctx.config?.security?.paths || DEFAULT_SECURITY_CONFIG.paths;
         const scopeCheck = isPathInScope(ctx.baseDir, resolved, ctx.scope, securityPaths);
         if (!scopeCheck.allowed) {
-            const pathStr = path;
-            logSecurityBlock(ctx.sessionId || undefined, "file_read", scopeCheck.reason || "Path not allowed", pathStr);
+            logSecurityBlock(ctx.sessionId || undefined, "file_read", scopeCheck.reason || "Path not allowed", path);
             return {
                 success: false,
                 output: t("file.path_not_allowed", {
@@ -117,8 +122,8 @@ export const readFileTool = {
             };
         }
         if (!existsSync(resolved)) {
-            // For relative paths, tell the model WHERE the path resolved — the
-            // "not found" alone is confusing (it cannot tell baseDir from cwd).
+            // Для относительных путей показываем, КУДА резолвилось: голое
+            // "not found" не даёт модели отличить baseDir от cwd.
             const output = resolved !== path
                 ? t("file.notfound_resolved", {
                     path,
@@ -127,22 +132,39 @@ export const readFileTool = {
                 : t("file.notfound", { path });
             return { success: false, output };
         }
-        const offset = args.offset || 1;
-        const limit = args.limit || DEFAULT_LIMIT;
+        // Кламп обоих: `offset: 0` давал slice(-1, end) с ПОСЛЕДНЕЙ строкой, а
+        // безграничный `limit` (тул вне усечения по бюджету) тянул бы целый
+        // большой файл в контекст.
+        const offset = Math.max(1, typeof args.offset === "number" ? Math.floor(args.offset) : 1);
+        const limit = Math.min(MAX_READ_LIMIT, Math.max(1, typeof args.limit === "number" ? Math.floor(args.limit) : DEFAULT_LIMIT));
         let lines;
         let total;
         let selected;
-        if (statSync(resolved).size > LARGE_FILE_BYTES) {
-            const slice = readLineSlice(resolved, offset, limit);
-            total = slice.total;
-            selected = slice.selected;
+        try {
+            if (statSync(resolved).size > LARGE_FILE_BYTES) {
+                const slice = readLineSlice(resolved, offset, limit);
+                total = slice.total;
+                selected = slice.selected;
+            }
+            else {
+                const content = readFileSync(resolved, "utf-8");
+                lines = content.split("\n");
+                // Файл с финальным переводом даёт фантомный пустой элемент — снять,
+                // чтобы счёт строк совпал со стриминг-путем.
+                if (lines.length > 1 && lines[lines.length - 1] === "")
+                    lines.pop();
+                total = lines.length;
+                const end = Math.min(offset - 1 + limit, total);
+                selected = lines.slice(offset - 1, end).join("\n");
+            }
         }
-        else {
-            const content = readFileSync(resolved, "utf-8");
-            lines = content.split("\n");
-            total = lines.length;
-            const end = Math.min(offset - 1 + limit, total);
-            selected = lines.slice(offset - 1, end).join("\n");
+        catch (err) {
+            // Файл мог исчезнуть между existsSync и чтением (TOCTOU) или оказаться
+            // директорией — возвращаем понятную ошибку, а не голый throw.
+            return {
+                success: false,
+                output: t("file.read_failed", { path, error: errMsg(err) }),
+            };
         }
         const end = Math.min(offset - 1 + limit, total);
         const ext = extname(resolved) || "(no extension)";
@@ -159,9 +181,8 @@ export const readFileTool = {
                 next: String(end + 1),
             })
             : "";
-        // Compact user-facing display: the tool header already shows the path,
-        // so only a partial read needs extra info (the range within the file).
-        // A full read adds nothing — keeps the card to two lines.
+        // Компактный display: заголовок уже показывает путь, доп. инфо (диапазон)
+        // нужна только частичному чтению. Полное чтение — пусто, карточка в 2 строки.
         const fullRead = offset === 1 && end >= total;
         const display = fullRead
             ? ""

package/dist/tools/recall.js

@@ -1,8 +1,10 @@
-import { homedir } from "os";
-import { join } from "path";
+/** Тул чтения межсессионной памяти (поиск, категории, всё целиком). */
 import { t } from "../i18n/index";
 import { MemoryStore } from "../modules/memory/store";
+import { globalMemoryDir } from "../config/paths";
+/** Категории памяти. */
 const CATEGORIES = ["preferences", "conventions", "decisions", "errors", "facts"];
+/** Читает/ищет по памяти. Параметры: query (full-text), category (опционально). */
 export const recallTool = {
     name: "recall",
     icon: "💾",
@@ -25,18 +27,18 @@ export const recallTool = {
     handler: async (_ctx, args) => {
         const query = args.query ? String(args.query) : "";
         const category = args.category ? String(args.category) : "";
-        const memoryDir = join(homedir(), ".mma", "memory");
+        const memoryDir = globalMemoryDir();
         const store = new MemoryStore(memoryDir);
         try {
-            // No query, no category → show everything
+            // Без запроса и категории — показать всё.
             if (!query && !category) {
                 return { success: true, output: formatAll(store) };
             }
-            // Category only → show that category
+            // Только категория — показать её.
             if (!query && category) {
                 return { success: true, output: formatCategory(store, category) };
             }
-            // Query with optional category → search
+            // Запрос с опциональной категорией — поиск.
             if (category) {
                 const results = searchCategory(store, category, query);
                 if (results.length === 0) {
@@ -47,7 +49,7 @@ export const recallTool = {
                     output: t("tool.recall.search_results", { category, results: results.join("\n") }),
                 };
             }
-            // Query across all
+            // Запрос по всем категориям.
             const results = store.search(query);
             if (results.length === 0) {
                 return { success: true, output: t("tool.recall.empty", { query }) };
@@ -59,10 +61,12 @@ export const recallTool = {
             };
         }
         catch (err) {
-            return { success: true, output: t("tool.memory_error", { error: String(err) }) };
+            // Чтение отсутствующей/битой категории — ошибка, а не пустой успех.
+            return { success: false, output: t("tool.memory_error", { error: String(err) }) };
         }
     },
 };
+/** Форматирует всю память (преференсы + последние 5 записей категорий). */
 function formatAll(store) {
     const parts = [];
     const prefs = store.getPreferences();
@@ -84,6 +88,7 @@ function formatAll(store) {
     }
     return parts.length > 0 ? parts.join("\n") : t("tool.recall.no_memory");
 }
+/** Форматирует одну категорию. */
 function formatCategory(store, category) {
     if (category === "preferences") {
         const prefs = store.getPreferences();
@@ -101,6 +106,7 @@ function formatCategory(store, category) {
         return t("tool.recall.no_memory");
     return `${category.charAt(0).toUpperCase() + category.slice(1)} (${entries.length} entries):\n${entries.join("\n")}`;
 }
+/** Ищет запрос внутри категории (регистронезависимо). */
 function searchCategory(store, category, query) {
     if (category === "preferences") {
         const prefs = store.getPreferences();

package/dist/tools/registry.js

@@ -12,12 +12,15 @@ export class ToolRegistry {
     has(name) {
         return this.tools.has(name);
     }
+    /** Тулы по именам (отсортированы). */
     list() {
         return Array.from(this.tools.keys()).sort();
     }
+    /** Все зарегистрированные определения. */
     getAll() {
         return Array.from(this.tools.values());
     }
+    /** Подмножество с любым из тегов (без alwaysOn). */
     getByTags(tags) {
         return this.getAll().filter((t) => {
             if (!t.tags || t.tags.length === 0)
@@ -26,17 +29,15 @@ export class ToolRegistry {
         });
     }
     /**
-     * Tools to expose to the LLM. Always includes `alwaysOn` tools, then tools
-     * matching the given tags. When no tags are given, returns every registered
-     * tool (backward-compatible). Duplicates are impossible because the
-     * alwaysOn + tagged sets are unioned by name.
+     * Тулы для LLM: всегда `alwaysOn`, плюс совпавшие по тегам. Без тегов —
+     * все (backward-compatible). Дубликаты исключены объединением по имени.
      */
     getAllForLLM(tags) {
         const all = this.getAll();
         const tagSet = new Set(tags ?? []);
         const selected = tagSet.size === 0
             ? all
-            : all.filter((t) => t.alwaysOn || (t.tags && t.tags.some((tag) => tagSet.has(tag))));
+            : all.filter((t) => t.alwaysOn || (t.tags?.some((tag) => tagSet.has(tag))));
         return selected.map((t) => ({
             name: t.name,
             description: t.description,

package/dist/tools/remember.js

@@ -1,8 +1,10 @@
-import { homedir } from "os";
-import { join } from "path";
+/** Тул записи в межсессионную память (preferences, факты, решения, ошибки). */
 import { t } from "../i18n/index";
 import { MemoryStore } from "../modules/memory/store";
+import { globalMemoryDir } from "../config/paths";
+/** Категории памяти. */
 const CATEGORIES = ["preferences", "conventions", "decisions", "errors", "facts"];
+/** Пишет факт/преференс в глобальную память. Параметры: category, key/value или entry. */
 export const rememberTool = {
     name: "remember",
     icon: "🧠",
@@ -36,7 +38,7 @@ export const rememberTool = {
         if (!CATEGORIES.includes(category)) {
             return { success: false, output: t("tool.invalid_params") };
         }
-        const memoryDir = join(homedir(), ".mma", "memory");
+        const memoryDir = globalMemoryDir();
         const store = new MemoryStore(memoryDir);
         try {
             if (category === "preferences") {
@@ -62,7 +64,9 @@ export const rememberTool = {
             };
         }
         catch (err) {
-            return { success: true, output: t("tool.memory_error", { error: String(err) }) };
+            // Упавшая запись — провал: отчёт об успехе заставлял агента (и учёт
+            // падений) верить, что память сохранена.
+            return { success: false, output: t("tool.memory_error", { error: String(err) }) };
         }
     },
 };

package/dist/tools/scope-request.js

@@ -1,3 +1,4 @@
+/** Тулы записи (для классификации отказа как write). */
 const WRITE_TOOLS = new Set([
     "write_file",
     "edit_file",
@@ -7,8 +8,8 @@ const WRITE_TOOLS = new Set([
     "download_file",
 ]);
 /**
- * Scope denials funnel through i18n keys file.path_not_allowed(_short)
- * ("Path not allowed" / "Путь недопустим") and chunk-query's "[SCOPE]" prefix.
+ * Отказы скоупа идут через i18n-ключи file.path_not_allowed(_short)
+ * ("Path not allowed" / "Путь недопустим") и "[SCOPE]"-префикс chunk-query.
  */
 export function isPathDenialOutput(output) {
     if (!output)
@@ -17,6 +18,7 @@ export function isPathDenialOutput(output) {
         output.includes("Путь недопустим") ||
         output.startsWith("[SCOPE]"));
 }
+/** Извлекает путь из аргументов tool call (по именам ключей, иначе по виду). */
 function pathArgOf(args) {
     if (!args)
         return "";
@@ -31,30 +33,31 @@ function pathArgOf(args) {
     }
     return "";
 }
-/** Observes the sub-agent's tool results and records scope-denied paths. */
+/** Наблюдает результаты тулов субагента, копит scope-отказы по путям. */
 export class ScopeDenialCollector {
     denied = new Map();
     plugin = {
         name: "scope-denial-collector",
         isBuiltin: true,
         onAfterTool: (_ctx, call, result) => {
-            const name = call?.name;
+            const name = call.name;
             if (!name || !result || result.success)
                 return;
             if (!isPathDenialOutput(typeof result.output === "string" ? result.output : undefined)) {
                 return;
             }
-            const path = pathArgOf(call?.arguments);
+            const path = pathArgOf(call.arguments);
             if (!path)
                 return;
             const write = WRITE_TOOLS.has(name);
             this.denied.set(path, { path, write });
         },
     };
+    /** Все отказы дедуплицированно. */
     getDenied() {
         return Array.from(this.denied.values());
     }
-    /** read_only=true only when every denial was a pure read denial. */
+    /** read_only=true — только если все отказы были чисто read. */
     toScopeRequest(reason = "sub-agent was denied access to files needed for the task") {
         const all = this.getDenied();
         if (all.length === 0)
@@ -66,9 +69,11 @@ export class ScopeDenialCollector {
         };
     }
 }
+/** Сериализует запрос в `<scope-request>`-блок результата. */
 export function formatScopeRequest(req) {
     return `<scope-request>${JSON.stringify(req)}</scope-request>`;
 }
+/** Парсит `<scope-request>`-блок из текста. Битый/пустой — null. */
 export function parseScopeRequest(text) {
     if (!text)
         return null;