micro-models-agent 2.11.0 → 2.12.0

package/dist/core/crash-handler.js

@@ -1,3 +1,4 @@
+/** Глобальные обработчики падений: запись краша в ~/.mma/logs/crash.jsonl. */
 import { appendFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
@@ -5,9 +6,15 @@ import { collectEnvironment } from "./environment";
 import { sanitizeLogMessage } from "../modules/security/data-sanitizer";
 import { t } from "../i18n/index";
 import { errMsg } from "../utils";
-export const CRASH_LOG_DIR = join(homedir(), ".mma", "logs");
+import { globalLogsDir } from "../config/paths";
+/** Каталог краш-логов. */
+export const CRASH_LOG_DIR = globalLogsDir();
+/** Имя файла краш-лога. */
 export const CRASH_LOG_FILE = "crash.jsonl";
-/** Build a sanitized crash entry. Environment is captured at crash time (no tool scan). */
+/**
+ * Строит санитизированную запись о падении. Окружение снимается в момент
+ * краша (без сканирования тулов).
+ */
 export function formatCrashEntry(type, err) {
     const message = errMsg(err);
     const stack = err instanceof Error && err.stack ? err.stack : message;
@@ -19,20 +26,23 @@ export function formatCrashEntry(type, err) {
         environment: collectEnvironment({ configDir: homedir(), scanTools: false }),
     };
 }
+/**
+ * Дописывает запись в краш-лог. Best-effort: отчёт о краше никогда не роняет процесс.
+ */
 export function writeCrashEntry(dir, entry) {
     try {
         mkdirSync(dir, { recursive: true });
-        appendFileSync(join(dir, CRASH_LOG_FILE), JSON.stringify(entry) + "\n", "utf-8");
+        appendFileSync(join(dir, CRASH_LOG_FILE), `${JSON.stringify(entry)}\n`, "utf-8");
     }
     catch {
-        // Best effort — never crash while reporting a crash
+        // Best-effort — отчёт о краше не должен ронять процесс
     }
 }
 let installed = false;
 /**
- * Global crash handlers. uncaughtException is logged + re-raised (exit 1 so the
- * process never continues in a broken state); unhandledRejection is logged only
- * (the event loop keeps running). Entries land in ~/.mma/logs/crash.jsonl.
+ * Ставит глобальные обработчики. uncaughtException логируется и завершает
+ * процесс (exit 1 — продолжение в битом состоянии недопустимо);
+ * unhandledRejection только логируется (цикл продолжает работу).
  */
 export function installCrashHandlers() {
     if (installed)

package/dist/core/environment.js

@@ -1,3 +1,4 @@
+/** Отчёт об окружении: рантайм, ОС, тулы, провайдер, Playwright. */
 import { existsSync, readFileSync, readdirSync } from "fs";
 import { spawnSync } from "child_process";
 import { createRequire } from "module";
@@ -8,7 +9,7 @@ import { env } from "process";
 import { readMmaVersion } from "./version";
 import { sanitizeUrl } from "../modules/security/network-validator";
 import { t } from "../i18n/index";
-/** Tools probed for availability on PATH (real executables only — no .cmd shims). */
+/** Тулы, проверяемые в PATH (только реальные бинари, без .cmd-шимов). */
 const TOOL_CHECKS = ["bun", "node", "git", "python"];
 function readEngineRequirement() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -22,12 +23,16 @@ function readEngineRequirement() {
                 return String(raw.engines.node);
         }
         catch {
-            // Broken package.json — fall through
+            // Битый package.json — пропускаем
         }
     }
     return ">=20";
 }
-/** Numeric tuple comparison: does `version` meet the minimum in `requirement` (e.g. `>=20`)? */
+/**
+ * Проверяет версию against минимума из requirement (напр. `>=20`).
+ * @param version проверяемая версия; @param requirement требование engines.
+ * @returns true, если версия не ниже минимальной.
+ */
 export function satisfiesMinimum(version, requirement) {
     const minMatch = requirement.match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
     if (!minMatch)
@@ -51,6 +56,10 @@ export function satisfiesMinimum(version, requirement) {
     }
     return true;
 }
+/**
+ * Детектит рантайм (Bun vs Node) и сверяет Node с engines из package.json.
+ * @returns информация о рантайме.
+ */
 export function detectRuntime() {
     const bun = globalThis.Bun;
     const isBun = typeof bun !== "undefined" && typeof bun?.version !== "undefined";
@@ -62,9 +71,9 @@ export function detectRuntime() {
         runtimeVersion,
         nodeVersion: process.version,
         engine,
-        // engines.node applies to the Node runtime. Bun satisfies it through its
-        // embedded Node (process.version) — never compare the Bun version itself
-        // against a Node requirement (Bun 1.x would always look "too old").
+        // engines.node — про Node-рантайм. Bun проходит через встроенный Node
+        // (process.version); версию самого Bun с требованием не сравниваем
+        // (Bun 1.x всегда выглядел бы «слишком старым»).
         engineOk: satisfiesMinimum(process.version, engine),
     };
 }
@@ -85,7 +94,10 @@ function toolVersion(cmd) {
         return "missing";
     }
 }
-/** Where Playwright keeps downloaded browser binaries (env override wins). */
+/**
+ * Каталог бинарников браузеров Playwright (env-переменная приоритетнее).
+ * @returns путь к каталогу браузеров.
+ */
 export function playwrightBrowsersDir() {
     if (process.env.PLAYWRIGHT_BROWSERS_PATH)
         return process.env.PLAYWRIGHT_BROWSERS_PATH;
@@ -93,14 +105,17 @@ export function playwrightBrowsersDir() {
         ? join(homedir(), "AppData", "Local", "ms-playwright")
         : join(homedir(), ".cache", "ms-playwright");
 }
-/** Playwright package presence/version + whether browser binaries are downloaded. */
+/**
+ * Наличие/версия пакета Playwright + скачаны ли бинарники браузеров.
+ * @returns installed/version/browsersDir/browsersInstalled.
+ */
 export function playwrightInfo() {
     let installed = false;
     let version = "";
     const browsersDir = playwrightBrowsersDir();
     try {
-        // Rule #12: resolve from disk at runtime — works in both src/ and dist/
-        // layouts, and under both Bun and Node (the bridge uses createRequire too).
+        // Правило №12: резолв с диска в рантайме — работает и в src/, и в dist/,
+        // и под Bun, и под Node (мост тоже через createRequire).
         const require = createRequire(import.meta.url);
         const pkgPath = require.resolve("playwright/package.json");
         installed = existsSync(pkgPath);
@@ -120,7 +135,10 @@ export function playwrightInfo() {
     }
     return { installed, version, browsersDir, browsersInstalled };
 }
-/** Pure requirements check — produces warnings from a report (no side effects). */
+/**
+ * Чистая проверка требований — варнинги из отчёта, без сайд-эффектов.
+ * @param report отчёт collectEnvironment; @returns список варнингов.
+ */
 export function checkEnvironmentRequirements(report) {
     const warnings = [];
     if (report.runtime.runtime === "node") {
@@ -148,6 +166,10 @@ export function checkEnvironmentRequirements(report) {
     }
     return warnings;
 }
+/**
+ * Собирает полный отчёт об окружении (рантайм, ОС, тулы, провайдер).
+ * @param opts configDir/baseDir/config/scanTools; @returns готовый отчёт.
+ */
 export function collectEnvironment(opts) {
     const runtime = detectRuntime();
     const tools = {};
@@ -192,7 +214,10 @@ export function collectEnvironment(opts) {
     report.warnings = checkEnvironmentRequirements(report);
     return report;
 }
-/** Compact human line + full structured report into the JSONL log. */
+/**
+ * Компактная строка для человека + полный отчёт в JSONL-лог.
+ * @param report отчёт окружения; @param logger логгер сессии.
+ */
 export function logEnvironment(report, logger) {
     logger.info(`Environment: ${report.os.platform} ${report.os.arch} | ${report.runtime.runtime} ${report.runtime.runtimeVersion} (node ${report.runtime.nodeVersion}) | mma ${report.mmaVersion} | ${report.provider?.model ?? "no provider"}`);
     logger.logStructured("environment", report);

package/dist/core/host-plan.js

@@ -0,0 +1,43 @@
+/**
+ * Чистая проекция плана модуля исполнения в план снапшота хоста.
+ * @param plan план в форме ActivePlanLike; @returns план снапшота либо null.
+ */
+export function planSnapshotFromModule(plan) {
+    if (!plan)
+        return null;
+    return {
+        steps: plan.steps.map((s) => ({ text: s.text, status: s.status })),
+        currentIndex: plan.currentIndex,
+    };
+}
+/**
+ * Планы несут пятый статус (`skipped`) без `currentIndex`. Маппим на контракт
+ * хоста: skipped — settled, читается как done; текущий индекс — первый шаг
+ * не в done/skipped.
+ */
+function toPlanStepStatus(status) {
+    switch (status) {
+        case "skipped":
+            return "done";
+        case "pending":
+        case "in_progress":
+        case "done":
+        case "failed":
+            return status;
+    }
+}
+/**
+ * Адаптирует реальный `Plan` модуля исполнения под вход снапшота.
+ * @param plan план исполнения; @returns ActivePlanLike либо null.
+ */
+export function adaptActivePlan(plan) {
+    if (!plan)
+        return null;
+    return {
+        steps: plan.steps.map((s) => ({
+            text: s.description,
+            status: toPlanStepStatus(s.status),
+        })),
+        currentIndex: plan.steps.findIndex((s) => s.status !== "done" && s.status !== "skipped"),
+    };
+}

package/dist/core/host.js

@@ -0,0 +1,23 @@
+import { defaultOutputBus } from "../output/bus";
+/**
+ * Строит HostBridge для плагинов (`ctx.hostBridge`). Веб-клиенты (и любой
+ * плагин) шлют сообщения через ТОТ ЖЕ runAgent-путь, что и терминальный ввод:
+ * рендеринг, лог сессии и single-flight guard общие, без дублирования.
+ */
+export function createHostBridge(opts) {
+    return {
+        isBusy: opts.isBusy,
+        async submit(text, o) {
+            if (opts.isBusy())
+                throw new Error("agent is busy");
+            for (const url of o?.images ?? [])
+                opts.addPendingImage(url);
+            return opts.runAgent(text);
+        },
+        interrupt() {
+            if (opts.isBusy())
+                opts.interruptRun();
+        },
+        subscribeOutput: (fn) => defaultOutputBus.subscribe(fn),
+    };
+}

package/dist/core/index.js

@@ -1,2 +1,3 @@
+/** Ядро агента: реэкспорт Agent, PromptBuilder и базовых типов. */
 export { PromptBuilder } from "./prompt-builder";
 export { Agent } from "./agent";

package/dist/core/prompt-builder.js

@@ -6,22 +6,38 @@ const PRIORITY_ORDER = {
 };
 function blockLabel(content) {
     const firstLine = content.split("\n")[0].trim();
-    return firstLine.length > 70 ? firstLine.slice(0, 67) + "..." : firstLine;
+    return firstLine.length > 70 ? `${firstLine.slice(0, 67)}...` : firstLine;
 }
+/**
+ * Собирает системный промпт из блоков: essential всегда, остальные по
+ * приоритету, пока влезают в бюджет.
+ */
 export class PromptBuilder {
     blocks = [];
     budget;
     constructor(budget) {
         this.budget = budget;
     }
+    /**
+     * Добавляет один блок.
+     * @param block блок промпта с приоритетом и оценкой токенов.
+     */
     addBlock(block) {
         this.blocks.push(block);
     }
+    /**
+     * Добавляет несколько блоков.
+     * @param blocks массив блоков промпта.
+     */
     addBlocks(blocks) {
         for (const b of blocks) {
             this.blocks.push(b);
         }
     }
+    /**
+     * Строит промпт: essential-блоки всегда, остальные по приоритету в бюджет.
+     * @returns промпт, исключённое и поблочная разбивка.
+     */
     build() {
         const essential = [];
         const nonEssential = [];

package/dist/core/prompt-overflow.js

@@ -1,13 +1,13 @@
-// src/core/prompt-overflow.ts
+/** Переполнение системного промпта: dry-run, суммаризация, подсказки. */
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 import { PromptBuilder } from "./prompt-builder";
 import { estimateTokens } from "../llm/token-counter";
 import { t } from "../i18n/index";
-/** How many tokens the model-facing hint block costs (upper bound for allocation). */
+/** Цена model-facing hint-блока в токенах (верхняя граница для аллокации). */
 export const HINT_BLOCK_TOKENS = 60;
-/** Rough chars-per-token factor used for hard truncation fallback. */
+/** Грубый фактор символов на токен для жёсткого усечения. */
 const CHARS_PER_TOKEN = 4;
 const KIND_ORDER = ["instructions", "project-map"];
 const KIND_LABEL = {
@@ -19,9 +19,8 @@ const KIND_SOURCE_FILE = {
     "project-map": "",
 };
 /**
- * Static dry-run of the system-prompt budget: which kind-carrying blocks do
- * not fit. Used by bootstrap for the startup banner and by Agent before the
- * first LLM call (the real resolution).
+ * Статический dry-run бюджета системного промпта: какие kind-блоки не влезают.
+ * Нужен bootstrap для стартового баннера и Agent перед первым LLM-вызовом.
  */
 export function dryRunOverflow(allBlocks, systemBudget) {
     const builder = new PromptBuilder(systemBudget);
@@ -51,13 +50,13 @@ function readCache(cacheDir, key) {
             }
         }
         catch {
-            // Legacy plain-text entry — treat as a summary hit
+            // Легаси plain-text запись — считаем попаданием суммаризации
             return { mode: "summary", text: raw };
         }
         return null;
     }
     catch {
-        // Corrupted cache — fall through to re-summarize
+        // Битый кэш — идём на повторную суммаризацию
     }
     return null;
 }
@@ -67,16 +66,16 @@ function writeCache(cacheDir, key, entry) {
         writeFileSync(join(cacheDir, `${key}.md`), JSON.stringify(entry), "utf-8");
     }
     catch {
-        // Best-effort — cache failure must not crash the agent
+        // Best-effort — падение кэша не должно ронять агента
     }
 }
-/** Collect a full text response from the streaming provider API. */
+/** Собирает полный текстовый ответ через стриминговый API провайдера. */
 async function collectText(provider, prompt, maxTokens) {
     let text = "";
-    // Reasoning must be off: a thinking model would burn the completion cap on
-    // <think> before emitting any summary content (observed on qwen3.5-9b).
-    // 2x headroom over the target: token estimates are heuristics, and the
-    // clamp below enforces the real cap no matter what the model returns.
+    // Reasoning выкл: думающая модель сожгла бы cap на <think> до любого
+    // суммаризирующего контента (наблюдалось на qwen3.5-9b).
+    // 2x запас сверх цели: оценки токенов эвристичны, а clamp ниже держит
+    // реальный cap независимо от ответа модели.
     for await (const chunk of provider.chat([{ role: "user", content: prompt }], undefined, undefined, {
         maxTokens: maxTokens * 2,
         reasoningEffort: "none",
@@ -96,17 +95,16 @@ function truncateToTokens(content, maxTokens) {
         cut = cut.slice(0, lastBreak);
     return `${cut.trimEnd()}\n\n[...truncated — read the full file for details...]`;
 }
-/** One-line first-line label for warnings/logs. */
+/** Однострочная метка по первой строке (для варнингов/логов). */
 function blockLabel(content) {
     const first = content.split("\n")[0].trim();
     return first.length > 60 ? `${first.slice(0, 57)}...` : first;
 }
 /**
- * Summarize (or, failing that, truncate) prompt blocks that exceeded the
- * system-prompt budget so the project instructions / project map still reach
- * the model. Summaries are cached on disk keyed by kind + content + budget.
- * Blocks are resolved in KIND_ORDER priority; the first gets the full
- * remaining budget, later blocks get whatever is left.
+ * Суммаризирует (или, не вышло, усекает) блоки сверх бюджета, чтобы инструкции
+ * проекта/карта всё равно дошли до модели. Суммаризации кэшируются на диске
+ * (ключ: kind + контент + бюджет). Порядок — KIND_ORDER; первый забирает весь
+ * остаток бюджета, остальным — что останется.
  */
 export async function resolvePromptOverflow(opts) {
     const { overflow, includedTokens, systemBudget, provider, cacheDir, logger } = opts;
@@ -114,10 +112,10 @@ export async function resolvePromptOverflow(opts) {
     const replacements = [];
     const warnings = [];
     let used = includedTokens;
-    let unresolved = [];
-    // The bootstrap dry-run only warns that blocks "will be summarized before the
-    // first run". Without a notice here the first prompt appears to hang while
-    // the model rewrites AGENTS.md / the project map — surface it.
+    const unresolved = [];
+    // Dry-run bootstrap лишь предупреждает, что блоки «будут суммаризированы
+    // перед первым запуском». Без нотиса тут первый промпт выглядит зависшим,
+    // пока модель переписывает AGENTS.md / карту — показываем явно.
     if (sorted.length > 0) {
         logger?.warn(t("prompt.overflow.compressing", { count: String(sorted.length) }));
     }
@@ -147,8 +145,8 @@ export async function resolvePromptOverflow(opts) {
             try {
                 const prompt = [
                     `Summarize the following ${KIND_LABEL[kind]} document.`,
-                    // 3 chars/token (not 4): non-Latin text (Cyrillic etc.) is ~2-3 chars
-                    // per token, so a 4x target lands the summary over the clamp.
+                    // 3 символа/токен (не 4): нелатиница (кириллица и т.п.) — ~2–3 символа
+                    // на токен, поэтому цель x4 уводит суммаризацию за clamp.
                     `Target length: at most ${targetChars} characters (~${maxTokens} tokens). Be strict about it.`,
                     `Preserve concrete facts: file paths, commands, rules, naming conventions, workflow steps.`,
                     `Keep the structure (headings / bullet lists). Output ONLY the summary text.`,
@@ -158,10 +156,9 @@ export async function resolvePromptOverflow(opts) {
                     `--- DOCUMENT END ---`,
                 ].join("\n");
                 text = await collectText(provider, prompt, maxTokens);
-                // Small models routinely ignore length instructions (observed: the 9B
-                // model produced ~4700 chars against a 3170-char target). One
-                // self-compression retry on the overshoot — the shorter input makes
-                // compliance much likelier — before falling back to the hard clamp.
+                // Маленькие модели регулярно игнорируют лимит длины (наблюдалось: 9B
+                // выдала ~4700 символов при цели 3170). Один retry самокомпрессии на
+                // перелёт — короткий вход резко повышает послушание — затем жёсткий clamp.
                 let retries = 0;
                 while (text && estimateTokens(text) > maxTokens && retries < 1) {
                     retries++;
@@ -186,7 +183,7 @@ export async function resolvePromptOverflow(opts) {
             }
         }
         if (!text) {
-            // No provider or summarization failed — hard truncation fallback.
+            // Нет провайдера или суммаризация упала — фолбэк жёсткого усечения.
             mode = "truncate";
             logger?.warn(t("prompt.overflow.truncating", {
                 label: blockLabel(block.content),
@@ -194,7 +191,7 @@ export async function resolvePromptOverflow(opts) {
             }));
             text = truncateToTokens(block.content, maxTokens);
         }
-        // LLMs overshoot: enforce the cap no matter what produced the text.
+        // LLM перелетают: держим cap независимо от источника текста.
         if (estimateTokens(text) > maxTokens) {
             if (mode === "summary") {
                 mode = "truncate";
@@ -238,6 +235,10 @@ export async function resolvePromptOverflow(opts) {
         : null;
     return { replacements, hintBlock, warnings };
 }
+/**
+ * Резолвит источник активного окна контекста (запись провайдера или глобал).
+ * @param config конфиг приложения; @returns источник и значение окна.
+ */
 export function resolveContextWindowSource(config) {
     const entries = config.provider.entries ?? [];
     const activeLabel = config.provider.active;
@@ -249,9 +250,8 @@ export function resolveContextWindowSource(config) {
     return { source: "global", value: config.contextWindow };
 }
 /**
- * Human-facing hint on how to raise the context window, aware of whether the
- * active value comes from the global config (`mma context <N>`) or from a
- * provider entry override (must be edited in the provider domain file).
+ * Человеческая подсказка, как поднять окно контекста: глобал (`mma context <N>`)
+ * или override записи провайдера (править файл домена провайдера).
  */
 export function contextWindowHint(config, configDir, recommended) {
     const src = resolveContextWindowSource(config);
@@ -261,29 +261,28 @@ export function contextWindowHint(config, configDir, recommended) {
     return `edit "${join(configDir, "config", "provider.json")}" → provider.entries[label="${src.label}"].contextWindow = ${recommended}`;
 }
 /**
- * Recommend the next standard context size whose system budget (10%)
- * accommodates `neededSystemTokens`. Falls back to the largest known size.
+ * Ближайший стандартный размер контекста, чей системный бюджет (10%)
+ * вмещает `neededSystemTokens`. Фолбэк — крупнейший известный.
  */
 export function recommendContextSize(neededSystemTokens) {
     const sizes = [8192, 16384, 32768, 65536, 131072, 262144];
     return (sizes.find((s) => Math.floor(s * 0.1) >= neededSystemTokens) ?? sizes[sizes.length - 1]);
 }
-/** Context window needed so that `systemFraction` of it covers `neededTokens`. */
+/** Окно контекста, чтобы доля `systemFraction` покрыла `neededTokens`. */
 export function requiredContextWindow(neededTokens, systemFraction) {
     const fraction = systemFraction > 0 ? systemFraction : 0.1;
     return Math.ceil(neededTokens / fraction);
 }
-/** System-prompt share of the CURRENT window needed to cover `neededTokens`. */
+/** Доля системного промпта ТЕКУЩЕГО окна, чтобы покрыть `neededTokens`. */
 export function requiredSystemFraction(neededTokens, contextWindow) {
     if (contextWindow <= 0)
         return 1;
     return Math.min(1, Math.ceil((neededTokens / contextWindow) * 100) / 100);
 }
 /**
- * Localized, concrete fix for an oversized system prompt. Instead of only
- * snapping to a coarse standard size (which makes a 32K project jump straight
- * to 131072), it states the raw requirement and both levers: a bigger window
- * or a bigger share of the current window.
+ * Локализованный конкретный фикс переполненного системного промпта. Вместо
+ * грубого стандартного размера (проект 32K прыгал бы сразу на 131072) даёт
+ * сырое требование и оба рычага: больше окно или больше доля текущего окна.
  */
 export function overflowHint(config, configDir, neededTokens) {
     const fraction = config.contextBudget?.systemPrompt ?? 0.1;