micro-models-agent 2.11.0 → 2.13.1

package/dist/migration/backup.js

@@ -1,11 +1,15 @@
+// Бэкапы перед миграцией: config.json.bak и копия всего configDir.
 import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { t } from "../i18n/index";
+import { defaultOutputBus } from "../output";
+/** Делает бэкапы конфига перед миграцией v1 → v2. */
 export class BackupManager {
     configDir;
     constructor(configDir) {
         this.configDir = configDir;
     }
+    /** Копия config.json в config.json.bak. Нет файла — ничего не делает. */
     backupConfig() {
         const configPath = join(this.configDir, "config.json");
         if (!existsSync(configPath))
@@ -13,24 +17,31 @@ export class BackupManager {
         const bakPath = join(this.configDir, "config.json.bak");
         copyFileSync(configPath, bakPath);
     }
+    /** Рекурсивная копия всего configDir в `<dir>.bak` (один раз, не перезаписывает). */
     backupAll() {
-        const bakDir = this.configDir + ".bak";
-        if (existsSync(bakDir))
+        const bakDir = `${this.configDir}.bak`;
+        if (existsSync(bakDir)) {
+            // Повторная миграция не перезаписывает бэкап — фиксируем в логе, чтобы
+            // «нет бэкапа за этот запуск» не выглядело как потеря данных.
+            defaultOutputBus.log("debug", "migration", `Backup already exists at ${bakDir}; keeping the previous state (not overwritten).`);
             return;
+        }
         if (existsSync(this.configDir)) {
             cpSync(this.configDir, bakDir, { recursive: true });
         }
     }
+    /** Пишет свежий конфиг v2 в config.json (создаёт каталог при нужде). */
     writeFreshConfig(config) {
         if (!existsSync(this.configDir)) {
             mkdirSync(this.configDir, { recursive: true });
         }
         writeFileSync(join(this.configDir, "config.json"), JSON.stringify(config, null, 2), "utf-8");
     }
+    /** Человекочитаемая сводка: какие бэкапы есть, или что миграция не нужна. */
     getBackupSummary() {
         const lines = [];
         const bakConfig = join(this.configDir, "config.json.bak");
-        const bakDir = this.configDir + ".bak";
+        const bakDir = `${this.configDir}.bak`;
         if (existsSync(bakConfig)) {
             lines.push(t("migration.config_bak"));
         }

package/dist/migration/detect.js

@@ -1,11 +1,18 @@
+// Детект необходимости миграции: отличает конфиг v1 от v2 и битого файла.
 import { existsSync, readFileSync, readdirSync } from "fs";
 import { join } from "path";
 const V1_ONLY_FIELDS = ["apiBase", "apiKey", "chatEndpoint", "temperature", "maxTokens"];
+/** Проверяет, лежит ли в configDir конфиг формата v1. Битый файл — не v1. */
 export class MigrationDetector {
     configDir;
     constructor(configDir) {
         this.configDir = configDir;
     }
+    /**
+     * Нужна ли миграция: есть v1-поля или нет всех обязательных v2-полей.
+     * Битый/вручную правленный конфиг — не повод: loadConfig предупредит
+     * и откатится на дефолты, файл не трогаем.
+     */
     needsMigration() {
         const configPath = join(this.configDir, "config.json");
         if (!existsSync(configPath))
@@ -13,7 +20,7 @@ export class MigrationDetector {
         try {
             const content = readFileSync(configPath, "utf-8");
             const config = JSON.parse(content);
-            if (config.version && config.version.startsWith("2."))
+            if (config.version?.startsWith("2."))
                 return false;
             for (const field of V1_ONLY_FIELDS) {
                 if (field in config)
@@ -26,17 +33,19 @@ export class MigrationDetector {
             return false;
         }
         catch {
-            // A corrupt or hand-edited config must NOT be treated as v1 and deleted.
-            // loadConfig will warn and fall back to defaults instead.
+            // Битый или вручную правленный конфиг — НЕ v1, удалять нельзя.
+            // loadConfig предупредит и откатится на дефолты.
             return false;
         }
     }
+    /** Есть ли старые сессии в каталоге sessions. */
     hasOldSessions() {
         const sessionsDir = join(this.configDir, "sessions");
         if (!existsSync(sessionsDir))
             return false;
         return readdirSync(sessionsDir).length > 0;
     }
+    /** Профиль старого формата: есть profile.json без полей platform/os. */
     hasOldProfile() {
         const profilePath = join(this.configDir, "profile.json");
         if (!existsSync(profilePath))

package/dist/migration/index.js

@@ -1,2 +1,3 @@
+// Миграция конфига v1 → v2: детект устаревшего формата и бэкапы.
 export { MigrationDetector } from "./detect";
 export { BackupManager } from "./backup";

package/dist/modules/artifacts/store.js

@@ -1,15 +1,16 @@
+// Хранилище артефактов сессии: запись/чтение файлов в <baseDir>/.mma/artifacts/<sessionId>.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve, relative, isAbsolute } from "node:path";
+/** Файловое хранилище артефактов сессии (jail внутри root). */
 export class ArtifactStore {
     root;
     constructor(opts) {
         const artifactsDir = opts.artifactsDir || ".mma/artifacts";
         this.root = resolve(opts.baseDir, artifactsDir, opts.sessionId);
     }
-    /** Normalize to [a-zA-Z0-9._-]; never empty, never "." or "..". */
+    /** Нормализует имя к [a-zA-Z0-9._-]; никогда не пустое, не "." и не "..". */
     static sanitizeName(name) {
-        // Strip traversal prefixes so "../../etc/passwd" becomes "etc_passwd",
-        // never ".._.._etc_passwd".
+        // Срезаем префиксы обхода: "../../etc/passwd" станет "etc_passwd", а не ".._.._etc_passwd".
         const stripped = name.replace(/^(\.\.?[\\/])+/g, "").replace(/^\.{1,2}$/, "");
         const cleaned = stripped
             .replace(/[^a-zA-Z0-9._-]/g, "_")
@@ -20,7 +21,7 @@ export class ArtifactStore {
         }
         return cleaned;
     }
-    /** True when `candidate` is strictly inside (or equal to) `root`. */
+    /** True, если `candidate` строго внутри `root` (или равен ему). */
     static isInside(root, candidate) {
         const rel = relative(root, candidate);
         if (rel === "")
@@ -28,8 +29,8 @@ export class ArtifactStore {
         return !rel.startsWith("..") && !isAbsolute(rel);
     }
     /**
-     * Persist content to <root>/<name>.<ext> and return the absolute path.
-     * Throws if the resolved path escapes root (defense in depth — sanitizeName already removes separators).
+     * Сохраняет контент в <root>/<name>.<ext>, возвращает абсолютный путь.
+     * Бросает, если путь выходит за root (defense in depth — sanitizeName уже убрал разделители).
      */
     save(name, content, ext = "md") {
         const safe = ArtifactStore.sanitizeName(name);
@@ -42,7 +43,7 @@ export class ArtifactStore {
         writeFileSync(abs, content, "utf8");
         return abs;
     }
-    /** Read an artifact by its file name (relative to root); null when outside the root or missing. */
+    /** Читает артефакт по имени файла (относительно root); null, если вне root или нет файла. */
     read(path) {
         const abs = resolve(this.root, path);
         if (!ArtifactStore.isInside(this.root, abs))
@@ -51,7 +52,7 @@ export class ArtifactStore {
             return null;
         return readFileSync(abs, "utf8");
     }
-    /** First maxChars chars (trimmed) + truncation marker. */
+    /** Первые maxChars символов (обрезанные справа) + маркер усечения. */
     summary(content, maxChars) {
         if (content.length <= maxChars)
             return content;

package/dist/modules/browser/actions.js

@@ -1,3 +1,5 @@
+// JS-сниппеты для действий в странице: клик, ввод, скролл, разметка, извлечение текста.
+/** JS для клика по элементу с индексом из снапшота. */
 export function buildClickScript(elementIndex) {
     return `
     const el = document.querySelector('[data-browser-index="${elementIndex}"]');
@@ -5,6 +7,7 @@ export function buildClickScript(elementIndex) {
     el.click();
   `;
 }
+/** JS для ввода текста в поле: фокус, установка значения, события input/change. */
 export function buildTypeScript(elementIndex, text) {
     const escaped = JSON.stringify(text);
     return `
@@ -17,6 +20,7 @@ export function buildTypeScript(elementIndex, text) {
     el.dispatchEvent(new Event('change', { bubbles: true }));
   `;
 }
+/** JS для прокрутки страницы в заданном направлении. */
 export function buildScrollScript(direction) {
     switch (direction) {
         case "down":
@@ -29,6 +33,7 @@ export function buildScrollScript(direction) {
             return `window.scrollTo({ top: document.body.scrollHeight, behavior: 'smooth' })`;
     }
 }
+/** JS для простановки интерактивным элементам атрибутов data-browser-index. */
 export function buildIndexInjectionScript() {
     return `
     const selectors = 'a[href], button, input, textarea, select, [role="button"], [role="link"], [role="textbox"], [role="checkbox"], [role="radio"], [contenteditable="true"]';
@@ -41,6 +46,7 @@ export function buildIndexInjectionScript() {
     });
   `;
 }
+/** JS для извлечения видимого текстового содержимого страницы построчно. */
 export function buildTextExtractionScript() {
     return `
     const contentTags = new Set(['h1','h2','h3','h4','h5','h6','p','li','article','main','section','blockquote','pre','td','th','dt','dd','figcaption']);

package/dist/modules/browser/bridge-client.js

@@ -1,18 +1,19 @@
+// Драйвер через node-мост (дочерний процесс bridge-server.mjs по JSON-RPC поверх stdio).
 import { spawn } from "child_process";
 import { createInterface } from "readline";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { ConsoleBuffer } from "./session";
+import { ConsoleBuffer } from "./console-buffer";
 import { pickExistingPath } from "./bridge-path";
-const BRIDGE_REQUEST_TIMEOUT_MS = 30000;
+import { BROWSER_BRIDGE_REQUEST_TIMEOUT_MS as BRIDGE_REQUEST_TIMEOUT_MS } from "../../config/timeouts";
 function bridgeScriptPath() {
-    // Resolve the bridge script for BOTH layouts (rule #12 — read from disk):
+    // Резолв скрипта моста для ОБЕИХ раскладок (пути читаются с диска):
     //   src/modules/browser/bridge-server.mjs          (bun run src/…)
-    //   dist/modules/browser/bridge-server.mjs         (bundle at dist/main.js +
-    //                                                   assets copied by copy-assets.ts)
-    // The single-candidate version looked next to the bundle (dist/bridge-server.mjs),
-    // which copy-assets.ts never produces — so the browser tool died with ENOENT
-    // in the released npm package (observed: v0.37.0).
+    //   dist/modules/browser/bridge-server.mjs         (бандл dist/main.js +
+    //                                                   ассеты от copy-assets.ts)
+    // Версия с одним кандидатом искала рядом с бандлом (dist/bridge-server.mjs),
+    // чего copy-assets.ts не создаёт, — и тул браузера падал с ENOENT
+    // в опубликованном npm-пакете (наблюдалось: v0.37.0).
     const dir = dirname(fileURLToPath(import.meta.url));
     const candidates = [
         join(dir, "bridge-server.mjs"),
@@ -20,6 +21,7 @@ function bridgeScriptPath() {
     ];
     return pickExistingPath(candidates);
 }
+/** Драйвер поверх node-моста: команды шлются JSON-строками в stdin дочернего процесса. */
 export class BridgeDriver {
     proc = null;
     rl = null;
@@ -50,7 +52,7 @@ export class BridgeDriver {
                 clearTimeout(timer);
                 resolve(resp);
             });
-            this.proc.stdin.write(JSON.stringify({ id, cmd, params }) + "\n");
+            this.proc.stdin.write(`${JSON.stringify({ id, cmd, params })}\n`);
         });
         this.drainEvents(response);
         if (!response.ok)
@@ -108,14 +110,14 @@ export class BridgeDriver {
         });
         proc.on("error", (err) => {
             if (this.proc !== proc)
-                return; // stale child — a newer bridge is alive
+                return; // протухший потомок — жив уже новый мост
             this.failPending(`Bridge process failed to start: ${err.message}`);
             this.proc = null;
             this.rl = null;
         });
         proc.on("exit", (code) => {
             if (this.proc !== proc)
-                return; // stale child — a newer bridge is alive
+                return; // протухший потомок — жив уже новый мост
             const stderrTail = this.lastStderr.join("").trim();
             this.failPending(stderrTail
                 ? `Bridge process exited (code ${code}): ${stderrTail.slice(0, 300)}`
@@ -184,7 +186,7 @@ export class BridgeDriver {
                 await this.send("close");
         }
         catch {
-            // ignore — we're shutting down
+            // игнорируем — идёт завершение работы
         }
         this.dispose();
     }

package/dist/modules/browser/bridge-path.js

@@ -1,9 +1,9 @@
+// Поиск скрипта node-моста: раскладки src/ и dist/ (тестируемо без запуска моста).
 import { existsSync } from "fs";
 /**
- * Pick the first existing candidate path, falling back to the first candidate.
- * Split out of bridge-client.ts so the source-vs-dist layout resolution is
- * unit-testable without spawning a node bridge (rule #12: build-time values
- * are resolved from disk at runtime, never inlined).
+ * Первый существующий путь из кандидатов, иначе — первый кандидат.
+ * Вынесено из bridge-client.ts, чтобы резолв раскладки src-vs-dist
+ * тестировался без спавна node-моста (пути читаются с диска в рантайме, не инлайнятся).
  */
 export function pickExistingPath(candidates, fallback = candidates[0]) {
     return candidates.find((p) => existsSync(p)) ?? fallback;

package/dist/modules/browser/console-buffer.js

@@ -0,0 +1,37 @@
+const CONSOLE_MAX_LINE = 400;
+/**
+ * Ограниченный буфер записей консоли браузера.
+ * Вынесен из `session.ts`, чтобы `driver.ts` и `bridge-client.ts` делили его
+ * БЕЗ импорта `session.ts` — это ребро давало два цикла импортов
+ * (`driver ↔ session`, `driver → bridge-client → session`).
+ */
+export class ConsoleBuffer {
+    entries = [];
+    maxEntries;
+    constructor(maxEntries = 20) {
+        this.maxEntries = maxEntries;
+    }
+    /** Добавить запись; пустые отбрасываются, длинные строки режутся. */
+    add(type, text) {
+        const clean = String(text).replace(/\s+/g, " ").trim();
+        if (!clean)
+            return;
+        const line = clean.length > CONSOLE_MAX_LINE ? `${clean.slice(0, CONSOLE_MAX_LINE)}…` : clean;
+        this.entries.push({ type, text: line });
+        if (this.entries.length > this.maxEntries) {
+            this.entries.splice(0, this.entries.length - this.maxEntries);
+        }
+    }
+    /** Очистить буфер. */
+    clear() {
+        this.entries = [];
+    }
+    /** Все записи копией. */
+    getAll() {
+        return [...this.entries];
+    }
+    /** Текущее число записей. */
+    get size() {
+        return this.entries.length;
+    }
+}

package/dist/modules/browser/cookie-store.js

@@ -1,14 +1,18 @@
+// Персистентное хранилище cookies браузера (cookies.json в cookieDir).
 import { readFile, writeFile, mkdir } from "fs/promises";
 import { join } from "path";
+/** Файловое хранилище кук (cookies.json). */
 export class CookieStore {
     filePath;
     constructor(cookieDir) {
         this.filePath = join(cookieDir, "cookies.json");
     }
+    /** Сохранить куки в файл. */
     async save(cookies) {
         await mkdir(join(this.filePath, ".."), { recursive: true });
         await writeFile(this.filePath, JSON.stringify(cookies, null, 2), "utf-8");
     }
+    /** Загрузить куки; при отсутствии/битом файле — пустой список. */
     async load() {
         try {
             const data = await readFile(this.filePath, "utf-8");
@@ -18,6 +22,7 @@ export class CookieStore {
             return [];
         }
     }
+    /** Удалить все куки. */
     async clear() {
         await this.save([]);
     }

package/dist/modules/browser/driver-types.js

@@ -0,0 +1 @@
+export {};

package/dist/modules/browser/driver.js

@@ -1,9 +1,15 @@
+// Playwright-драйвер: запуск Chromium, навигация, снапшоты, выбор транспорта.
 import { chromium } from "playwright";
-import { ConsoleBuffer } from "./session";
-export const DIRECT_LAUNCH_TIMEOUT_MS = 8000;
+import { ConsoleBuffer } from "./console-buffer";
+import { MMA_ENV } from "../../config/env";
+import { BROWSER_DIRECT_LAUNCH_TIMEOUT_MS as CANONICAL_DIRECT_LAUNCH_TIMEOUT_MS } from "../../config/timeouts";
+/** Таймаут прямого запуска Playwright до отката на node-мост. */
+/** Публичный экспорт-алиас: то же значение из реестра. */
+export const DIRECT_LAUNCH_TIMEOUT_MS = CANONICAL_DIRECT_LAUNCH_TIMEOUT_MS;
+/** Оверрайды запуска из env (MMA_BROWSER_EXECUTABLE/MMA_BROWSER_CHANNEL). */
 export function resolveBrowserLaunchOverrides(env = process.env) {
-    const executablePath = env.MMA_BROWSER_EXECUTABLE?.trim();
-    const channel = env.MMA_BROWSER_CHANNEL?.trim();
+    const executablePath = env[MMA_ENV.BROWSER_EXECUTABLE]?.trim();
+    const channel = env[MMA_ENV.BROWSER_CHANNEL]?.trim();
     const out = {};
     if (executablePath)
         out.executablePath = executablePath;
@@ -11,15 +17,15 @@ export function resolveBrowserLaunchOverrides(env = process.env) {
         out.channel = channel;
     return out;
 }
-/** System browsers to try when the bundled Chromium revision is missing. */
+/** Системные браузеры, если bundled-ревизия Chromium отсутствует. */
 const SYSTEM_CHANNEL_FALLBACKS = ["chrome", "msedge"];
 function isMissingBrowserError(err) {
     return /Executable doesn't exist|is not found|looks like Playwright was just installed/i.test(String(err?.message ?? err));
 }
 /**
- * Launch Chromium, falling back to an installed system Chrome/Edge when the
- * bundled revision is absent (CDN unreachable). An explicit override always
- * wins and suppresses the fallback — the user's choice must fail loudly.
+ * Запуск Chromium с фолбэком на системный Chrome/Edge, если bundled-ревизии
+ * нет (CDN недоступен). Явный оверрайд всегда побеждает и подавляет фолбэк —
+ * выбор пользователя должен падать громко.
  */
 export async function launchChromiumWithFallback(launch, cfg, overrides = {}) {
     const base = { headless: cfg.headless, timeout: cfg.timeoutMs, ...overrides };
@@ -45,6 +51,7 @@ export async function launchChromiumWithFallback(launch, cfg, overrides = {}) {
 function launchChromium(cfg, overrides) {
     return launchChromiumWithFallback((opts) => chromium.launch(opts), cfg, overrides);
 }
+/** Драйвер поверх Playwright: страница, консоль, сетевые ошибки. */
 export class PlaywrightDriver {
     browser = null;
     context = null;
@@ -145,6 +152,7 @@ export class PlaywrightDriver {
         return this.page;
     }
 }
+/** Создать драйвер: прямой Playwright, при неудаче — node-мост. */
 export function createBrowserDriver(config) {
     const common = {
         headless: config.headless,
@@ -153,9 +161,9 @@ export function createBrowserDriver(config) {
         overrides: resolveBrowserLaunchOverrides(),
     };
     return (async () => {
-        // Playwright's pipe/websocket transport is broken under Bun on some
-        // platforms (see oven-sh/bun#31105, #9911). Under Bun we always use the
-        // Node bridge. Under Node we try the direct path first.
+        // Транспорт pipe/websocket у Playwright сломан под Bun на части платформ
+        // (см. oven-sh/bun#31105, #9911). Под Bun всегда идём через node-мост,
+        // под Node сначала пробуем прямой путь.
         if (process.versions.bun) {
             return launchBridge(config, common);
         }

package/dist/modules/browser/index.js

@@ -1,5 +1,7 @@
+// Публичный фасад модуля браузера: сессия, драйверы, снапшоты, типы.
 export { BrowserModule } from "./module";
-export { BrowserSession, BrowserActionTracker, ConsoleBuffer } from "./session";
+export { BrowserSession, BrowserActionTracker } from "./session";
+export { ConsoleBuffer } from "./console-buffer";
 export { CookieStore } from "./cookie-store";
 export { createBrowserDriver, PlaywrightDriver } from "./driver";
 export { BridgeDriver } from "./bridge-client";

package/dist/modules/browser/module.js

@@ -1,4 +1,5 @@
 import { createBrowserTool, closeBrowserSession } from "../../tools/browser";
+/** Модуль headless-браузера: промпт workflow, тул, плагин закрытия сессии. */
 export class BrowserModule {
     name = "browser";
     getSystemPromptBlock() {
@@ -8,7 +9,7 @@ export class BrowserModule {
                 "Workflow: open(url) → read snapshot → click/type on element numbers → read updated snapshot.",
                 'Each snapshot includes a "Content" section with the visible page text, a "Console" section with browser messages, and network errors. Use these to understand the page, detect JS errors, and verify the result of your actions.',
                 'Always start with "open" action. Use element numbers from snapshot for click/type targets.',
-                'Use "screenshot" action only if the model supports vision. Otherwise rely on the text snapshot.',
+                'The "screenshot" action is delivered automatically: a vision model receives the image, a text-only model receives the text snapshot instead. You do not need to decide — just call it and read what you get.',
             ].join("\n"),
             priority: "normal",
             essential: false,

package/dist/modules/browser/session.js

@@ -3,39 +3,14 @@ import { extractInteractiveElements, formatSnapshot } from "./snapshot";
 import { buildClickScript, buildTypeScript, buildScrollScript, buildIndexInjectionScript, buildTextExtractionScript, } from "./actions";
 import { CookieStore } from "./cookie-store";
 import { t } from "../../i18n/index";
-const CONSOLE_MAX_LINE = 400;
-export class ConsoleBuffer {
-    entries = [];
-    maxEntries;
-    constructor(maxEntries = 20) {
-        this.maxEntries = maxEntries;
-    }
-    add(type, text) {
-        const clean = String(text).replace(/\s+/g, " ").trim();
-        if (!clean)
-            return;
-        const line = clean.length > CONSOLE_MAX_LINE ? clean.slice(0, CONSOLE_MAX_LINE) + "…" : clean;
-        this.entries.push({ type, text: line });
-        if (this.entries.length > this.maxEntries) {
-            this.entries.splice(0, this.entries.length - this.maxEntries);
-        }
-    }
-    clear() {
-        this.entries = [];
-    }
-    getAll() {
-        return [...this.entries];
-    }
-    get size() {
-        return this.entries.length;
-    }
-}
+/** Ловит N одинаковых действий подряд на одном URL и возвращает предупреждение. */
 export class BrowserActionTracker {
     history = [];
     threshold;
     constructor(threshold = 3) {
         this.threshold = threshold;
     }
+    /** Записать действие; при серии повторов — текст предупреждения, иначе null. */
     record(action, args, url) {
         this.history.push({ action, args, url });
         if (this.history.length < this.threshold)
@@ -52,10 +27,12 @@ export class BrowserActionTracker {
         }
         return null;
     }
+    /** Сбросить историю (вызывается при open). */
     reset() {
         this.history = [];
     }
 }
+/** Сессия: ленивый драйвер, куки, выполнение действий модели, снапшоты. */
 export class BrowserSession {
     driver = null;
     config;
@@ -71,9 +48,11 @@ export class BrowserSession {
         this.config = config;
         this.cookieStore = new CookieStore(config.cookieDir);
     }
+    /** Копия текущего состояния (открыта/URL/заголовок/счётчик элементов). */
     getState() {
         return { ...this.state };
     }
+    /** Выполнить действие модели (open/click/type/…); ошибки — текстом в ActionResult. */
     async execute(action, args) {
         try {
             let result;
@@ -117,7 +96,7 @@ export class BrowserSession {
             if (action !== "open") {
                 const warning = this.actionTracker.record(action, args, this.driver?.url() || "");
                 if (warning && result.success) {
-                    result.output = result.output + "\n\n⚠️ " + warning;
+                    result.output = `${result.output}\n\n⚠️ ${warning}`;
                 }
             }
             return result;
@@ -186,13 +165,13 @@ export class BrowserSession {
     async open(url) {
         if (!url)
             return { success: false, output: t("browser.url_required") };
-        // Security: block dangerous schemes (file:, chrome:, about:, data:).
+        // Блок опасных схем (file:, chrome:, about:, data:) — обход запретов исключён.
         if (/^(file|chrome|about|data|javascript|view-source):/i.test(url)) {
             return { success: false, output: `[SECURITY BLOCKED] scheme not allowed: ${url}` };
         }
         if (!url.startsWith("http://") && !url.startsWith("https://") && !url.startsWith("file://")) {
             const isLocalhost = /^(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?$/i.test(url);
-            url = isLocalhost ? "http://" + url : "https://" + url;
+            url = isLocalhost ? `http://${url}` : `https://${url}`;
         }
         await this.launch();
         if (!this.driver)
@@ -330,6 +309,7 @@ export class BrowserSession {
         const snapshot = await this.takeSnapshot();
         return { success: true, output: snapshot };
     }
+    /** Закрыть сессию: сохранить куки, убить драйвер, сбросить состояние. */
     async close() {
         await this.saveCookies();
         if (this.driver) {

package/dist/modules/browser/snapshot.js

@@ -24,11 +24,11 @@ function inferRole(tag, type) {
 }
 function getName(tag, attrs, html, matchIndex) {
     const fromAttr = attrs["aria-label"] ||
-        attrs["placeholder"] ||
-        attrs["title"] ||
-        attrs["alt"] ||
-        attrs["value"] ||
-        attrs["name"] ||
+        attrs.placeholder ||
+        attrs.title ||
+        attrs.alt ||
+        attrs.value ||
+        attrs.name ||
         "";
     if (fromAttr)
         return fromAttr;
@@ -47,6 +47,10 @@ function getName(tag, attrs, html, matchIndex) {
         .trim();
     return text.slice(0, 50);
 }
+/**
+ * Вытащить интерактивные элементы из HTML (ссылки, кнопки, поля).
+ * @param html сырой HTML страницы. @param maxElements лимит элементов.
+ */
 export function extractInteractiveElements(html, maxElements = 30) {
     const elements = [];
     const tagRegex = /<(a|button|input|textarea|select|div|span)([^>]*)>/gi;
@@ -62,19 +66,19 @@ export function extractInteractiveElements(html, maxElements = 30) {
         while ((attrMatch = attrRegex.exec(attrStr)) !== null) {
             attrs[attrMatch[1].toLowerCase()] = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4] ?? "";
         }
-        if (attrs["style"]?.includes("display:none") || attrs["style"]?.includes("display: none"))
+        if (attrs.style?.includes("display:none") || attrs.style?.includes("display: none"))
             continue;
-        if (attrs["hidden"] !== undefined)
+        if (attrs.hidden !== undefined)
             continue;
         if (attrs["aria-hidden"] === "true")
             continue;
-        if (tag === "input" && attrs["type"] === "hidden")
+        if (tag === "input" && attrs.type === "hidden")
             continue;
-        const role = attrs["role"] || inferRole(tag, attrs["type"]);
-        const isInteractive = ["a", "button", "input", "textarea", "select"].includes(tag) || attrs["role"] !== undefined;
+        const role = attrs.role || inferRole(tag, attrs.type);
+        const isInteractive = ["a", "button", "input", "textarea", "select"].includes(tag) || attrs.role !== undefined;
         if (!isInteractive)
             continue;
-        if (tag === "a" && !attrs["href"])
+        if (tag === "a" && !attrs.href)
             continue;
         const name = getName(tag, attrs, html, match.index);
         elements.push({
@@ -82,13 +86,14 @@ export function extractInteractiveElements(html, maxElements = 30) {
             tag,
             role,
             name,
-            value: attrs["value"],
-            href: attrs["href"],
+            value: attrs.value,
+            href: attrs.href,
             visible: true,
         });
     }
     return elements;
 }
+/** Обрезать текст по лимиту, предпочтительно по границе строки. */
 export function truncateText(text, maxChars) {
     if (maxChars <= 0)
         return "";
@@ -99,6 +104,7 @@ export function truncateText(text, maxChars) {
     const safe = lastNewline > maxChars * 0.6 ? cut.slice(0, lastNewline) : cut;
     return `${safe}\n${t("browser.truncated")}`;
 }
+/** Собрать текстовый снапшот: элементы, контент, консоль, сетевые ошибки. */
 export function formatSnapshot(snapshot, maxContentChars = DEFAULT_BROWSER_CONFIG.maxContentChars) {
     const lines = [];
     lines.push(`Page: "${snapshot.title}"`);

package/dist/modules/browser/types.js

@@ -1,3 +1,4 @@
+/** Дефолтный конфиг браузера. */
 export const DEFAULT_BROWSER_CONFIG = {
     headless: true,
     maxElements: 30,