micro-models-agent 2.11.0 → 2.12.0

package/dist/core/session-logger.js

@@ -1,14 +1,12 @@
 import { setAuditSessionDir } from "../modules/security/audit-log";
 import { sanitizeLogMessage } from "../modules/security/data-sanitizer";
-import { join } from "path";
-import { readFileSync, existsSync } from "fs";
+import { redactContextSecrets } from "./agent/context-log";
 /**
- * Thin wrapper around SessionManager that eliminates repetitive
- * `if (sessionManager)` + `new Date().toISOString()` boilerplate
- * from the agent loop.
+ * Тонкая обёртка над SessionManager: убирает повторяющиеся
+ * `if (sessionManager)` + `new Date().toISOString()` из цикла агента.
  *
- * When constructed, it configures the app logger and audit log to write into
- * the session directory (instead of global ~/.mma/logs/).
+ * При создании привязывает логгер приложения и аудит-лог к каталогу сессии
+ * (вместо глобального ~/.mma/logs/).
  */
 export class SessionLogger {
     session;
@@ -21,26 +19,36 @@ export class SessionLogger {
         this.bindSessionDir();
     }
     bindSessionDir() {
-        const meta = this.session?.getActiveMeta();
-        if (!meta)
+        const session = this.session;
+        const meta = session?.getActiveMeta();
+        if (!session || !meta)
             return;
-        const dir = this.session.getSessionDirectory(meta.id);
+        const dir = session.getSessionDirectory(meta.id);
         if (this.logger) {
             this.logger.setSessionDir(dir);
             this.logger.initSessionLog(meta.id);
         }
         setAuditSessionDir(dir);
     }
+    /** Есть ли активная сессия. */
     get active() {
         return !!this.session?.getActive();
     }
+    /**
+     * Пишет системное сообщение в лог сессии.
+     * @param content текст системного сообщения.
+     */
     logSystem(content) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
             type: "system",
-            content,
+            content: redactContextSecrets(content),
         });
     }
+    /**
+     * Пишет сообщение пользователя (санитизированное).
+     * @param content текст пользователя.
+     */
     logUser(content) {
         const sanitized = sanitizeLogMessage(content);
         this.session?.appendMessage({
@@ -54,13 +62,18 @@ export class SessionLogger {
             content: sanitized,
         });
     }
+    /**
+     * Пишет ответ ассистента (+ reasoning и tool_calls при наличии).
+     * @param content текст ответа; @param reasoning reasoning-контент;
+     * @param toolCalls вызовы тулов; @param iteration номер итерации.
+     */
     logAssistant(content, reasoning, toolCalls, iteration) {
         const caller = this.getCaller?.();
         if (reasoning) {
             this.session?.appendLog({
                 ts: new Date().toISOString(),
                 type: "reasoning",
-                content: reasoning,
+                content: redactContextSecrets(reasoning),
                 iteration,
                 provider: caller?.provider,
                 model: caller?.model,
@@ -69,7 +82,7 @@ export class SessionLogger {
         this.session?.appendLog({
             ts: new Date().toISOString(),
             type: "assistant",
-            content,
+            content: redactContextSecrets(content),
             ...(toolCalls
                 ? {
                     tool_calls: toolCalls.map((tc) => ({
@@ -84,16 +97,24 @@ export class SessionLogger {
             model: caller?.model,
         });
     }
+    /**
+     * Сохраняет сообщение ассистента в историю сессии (для resume).
+     * @param content текст сообщения.
+     */
     saveAssistantMessage(content) {
         const caller = this.getCaller?.();
         this.session?.appendMessage({
             role: "assistant",
-            content,
+            content: redactContextSecrets(content),
             timestamp: new Date().toISOString(),
             provider: caller?.provider,
             model: caller?.model,
         });
     }
+    /**
+     * Пишет набор определений тулов итерации (состав для пост-анализа).
+     * @param toolCount число тулов; @param toolNames имена; @param iteration итерация.
+     */
     logToolDefs(toolCount, toolNames, iteration) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
@@ -103,16 +124,46 @@ export class SessionLogger {
             iteration,
         });
     }
+    /**
+     * Пишет вызов тула (имя, id, санитизированные аргументы).
+     * @param call вызов тула; @param iteration номер итерации.
+     */
     logToolCall(call, iteration) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
             type: "tool_call",
             tool: call.name,
             tool_call_id: call.id,
-            args: JSON.parse(sanitizeLogMessage(JSON.stringify(call.arguments))),
+            args: this.sanitizeArgs(call.arguments),
             iteration,
         });
     }
+    /**
+     * Сериализует аргументы тула для лога. Санитайзер может испортить JSON
+     * (например, режет закрывающую кавычку в `password=secret"`), поэтому при
+     * ошибке парсинга пишем сырую санитизированную строку и предупреждаем —
+     * запись tool_call не должна теряться.
+     */
+    sanitizeArgs(args) {
+        const raw = JSON.stringify(args ?? {});
+        const sanitized = sanitizeLogMessage(raw);
+        try {
+            const parsed = JSON.parse(sanitized);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+            return { raw: sanitized };
+        }
+        catch {
+            this.logger?.warn(`tool_call args sanitization broke JSON; storing raw string (${raw.length} chars)`);
+            return { raw: sanitized };
+        }
+    }
+    /**
+     * Пишет результат тула (успех, вывод, diff, длительность).
+     * @param call вызов; @param result результат; @param duration длительность, мс;
+     * @param iteration номер итерации.
+     */
     logToolResult(call, result, duration, iteration) {
         const caller = this.getCaller?.();
         this.session?.appendMessage({
@@ -137,6 +188,10 @@ export class SessionLogger {
             model: caller?.model,
         });
     }
+    /**
+     * Пишет событие компакции (причина, токены/качество до и после).
+     * @param info параметры компакции.
+     */
     logCompaction(info) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
@@ -155,6 +210,10 @@ export class SessionLogger {
             summary: info.summary,
         });
     }
+    /**
+     * Пишет снапшот контекста (бюджеты, токены, качество, состав блоков).
+     * @param info параметры снапшота.
+     */
     logContext(info) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
@@ -179,6 +238,10 @@ export class SessionLogger {
             blocks: info.blocks,
         });
     }
+    /**
+     * Пишет usage LLM-вызова (токены, источник, кеш, стабильность префикса).
+     * @param iteration номер итерации; @param usage токены и мета.
+     */
     logLlmUsage(iteration, usage) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
@@ -198,13 +261,21 @@ export class SessionLogger {
             cacheSource: usage.cache?.source,
         });
     }
+    /**
+     * Пишет ошибку в лог сессии.
+     * @param message текст ошибки.
+     */
     logError(message) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
             type: "error",
-            content: message,
+            content: redactContextSecrets(message),
         });
     }
+    /**
+     * Пишет вердикт финального аудита.
+     * @param summary сводка аудита; @param iteration номер итерации.
+     */
     logAudit(summary, iteration) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
@@ -213,6 +284,10 @@ export class SessionLogger {
             iteration,
         });
     }
+    /**
+     * Пишет событие плана MoE/обычного (создание, шаги, re-plan).
+     * @param event имя события; @param detail детали; @param iteration итерация.
+     */
     logPlan(event, detail, iteration) {
         this.session?.appendLog({
             ts: new Date().toISOString(),
@@ -223,24 +298,23 @@ export class SessionLogger {
         });
     }
     /**
-     * Log session startup diagnostics: environment, LSP probe, plugins, skills.
-     * Should be the FIRST entry in session.jsonl so the file is self-describing.
-     * Skips if a session_start entry already exists (e.g. logged by REPL).
+     * Пишет стартовую диагностику сессии: окружение, LSP-проба, плагины, скиллы.
+     * Должна быть ПЕРВОЙ записью в session.jsonl (файл самоописываем).
+     * Пропускает, если session_start уже есть (напр., записан REPL).
      */
     logSessionStart(data) {
-        // Skip if session_start already logged (REPL may have logged it with LSP probe)
+        // Пропуск при уже записанном session_start (REPL мог записать с LSP-пробой).
+        // Чтение через decrypt-aware store: при шифровании сессии строки на диске —
+        // шифртекст, поэтому проверка подстрокой никогда не срабатывала и дубль дописывался.
         const meta = this.session?.getActiveMeta();
         if (meta) {
-            const logPath = join(this.session.getSessionDirectory(meta.id), "session.jsonl");
             try {
-                if (existsSync(logPath)) {
-                    const content = readFileSync(logPath, "utf-8");
-                    if (content.includes('"type":"session_start"'))
-                        return;
-                }
+                const entries = this.session.loadSessionLog(meta.id);
+                if (entries.some((e) => e.type === "session_start"))
+                    return;
             }
             catch {
-                // File read error — proceed to write
+                // Ошибка чтения — всё равно пишем
             }
         }
         this.session?.appendLog({
@@ -254,7 +328,7 @@ export class SessionLogger {
         });
     }
     /**
-     * Log a reasoning control event (level set, policy evaluation).
+     * Пишет событие управления reasoning (уровень, оценка политики).
      */
     logReasoningControl(data) {
         this.session?.appendLog({
@@ -269,8 +343,8 @@ export class SessionLogger {
         });
     }
     /**
-     * Log a MoE observability event (moe_plan / moe_subtask / moe_replan /
-     * moe_verify). Emitted by runWithMoE and MoEExecutor (Plan 4.2).
+     * Пишет событие наблюдаемости MoE (moe_plan / moe_subtask / moe_replan /
+     * moe_verify). Эмитят runWithMoE и MoEExecutor (Plan 4.2).
      */
     logMoE(event, data) {
         this.session?.appendLog({
@@ -280,4 +354,22 @@ export class SessionLogger {
             ...data,
         });
     }
+    /** Пишет событие онбординга (meet/init) для пост-анализа. */
+    logOnboarding(event, data = {}) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: `onboarding_${event}`,
+            content: event,
+            ...data,
+        });
+    }
+    /** Пишет событие критика (контр-агент). */
+    logCritic(event, data = {}) {
+        this.session?.appendLog({
+            ts: new Date().toISOString(),
+            type: event,
+            content: data.summary ?? event,
+            ...data,
+        });
+    }
 }

package/dist/core/system-prompt.js

@@ -0,0 +1,117 @@
+/**
+ * Рендерит системный промпт (чистая функция).
+ * @param config конфиг приложения; @param baseDir workspace;
+ * @param profileCompressed сжатый профиль окружения.
+ * @returns текст системного сообщения для модели.
+ */
+export function buildSystemInfo(config, baseDir, profileCompressed) {
+    const now = new Date().toISOString().replace("T", " ").slice(0, 19);
+    const isWin = profileCompressed.toLowerCase().includes("win32");
+    const lines = [
+        `You are MMA v2, an AI agent for small models (${config.model}). Date: ${now}.`,
+        `Workspace: ${baseDir}. ${profileCompressed}.`,
+        `Reply in the user's language. Explain briefly if not obvious.`,
+        ``,
+        `TOOLS: file ops (read/write/edit/delete), search (glob/grep), shell (bash), web, subagents, browser, MCP.`,
+        `On tool failure: analyze, fix the call, retry up to 2x with different approaches, then ask the user.`,
+        ``,
+        `SCOPE — do ONLY what the user explicitly asked: no extra features, files, refactors, or fixes beyond the request.`,
+        `Read-only requests ("расскажи", "покажи", "объясни", "check") mean READ-ONLY: inspect and answer, never modify anything.`,
+        `Ambiguous task (unclear what/where/which) or target not found — STOP and ask via the "question" tool, do not guess.`,
+        `A "not found" tool result means the PATH was wrong, not that the project is missing: list_dir the workspace first,`,
+        `then the parent of a user-named path. NEVER scaffold a new project for questions about an existing one.`,
+        ``,
+        `ARTIFACTS: CREATE a file ONLY when the user explicitly asks for a file — "write/save to file", "create a file/document",`,
+        `or a filename/path with an extension.`,
+        `Bare "recommendation", "summary", "report", "result" mean ANSWER IN CHAT, never files.`,
+        `Use the requested format and stack; never add unagreed libraries.`,
+        `If a needed choice is unspecified, ask or search first.`,
+        ``,
+        `MEMORY: the current user message outranks stored memory/preferences.`,
+        `Never "correct" an explicit value from stored facts.`,
+        `Never ask what memory already answers (the "question" tool checks memory itself); "remember" only on explicit request.`,
+        `MEMORY PRIVACY: never copy stored personal facts (birthday, height, name, contacts) into workspace files unless asked.`,
+        ``,
+        `PROTECTED PATHS: never touch VCS internals (.git/, .hg/, .svn/) or secrets (.env*, *.key, *.pem, *.p12, *.pfx, *.crt,`,
+        `*.secret, *.token, .npmrc, .netrc, .git-credentials, .gitconfig) without explicit confirmation via the "approve" tool.`,
+        `Do not retry around a refusal or work around it with bash.`,
+        ``,
+        `WORK RULES: 1) install deps BEFORE source (verify lockfile; no uninstalled imports); 2) framework init BEFORE app code;`,
+        `3) plan sequentially, verify each step's deliverables exist with real content; 4) verify on disk + command output;`,
+        `5) no premature work (no files/imports for future steps); 6) stuck after 2+ failures: STOP, change approach, ask.`,
+        ``,
+        `SESSION START (first turn with a workspace task): 1) inspect — list_dir the workspace, note package.json/tests/config;`,
+        `2) baseline for CODE tasks only — run project checks (bun test / tsc --noEmit),`,
+        `report pass/fail BEFORE changing code;`,
+        `3) trivial chat/questions skip the baseline. Then proceed with the user's task.`,
+        ``,
+        `FORBIDDEN:`,
+        `- Marking done without proof (no clean check output) — see VERIFY.`,
+        `- Creating files the user didn't ask for — see ARTIFACTS.`,
+        `- Retrying the same failing command a 3rd time — change approach or ask.`,
+        `- Claiming "fixed" from a fresh port/server while the user's endpoint still fails.`,
+        ``,
+        `DONE CONDITIONS — finished only when ALL hold: all plan steps are marked done;`,
+        `requested files/artifacts exist with real content; each runnable verification reports clean.`,
+        `Then reply with a short summary of what changed (files created/edited).`,
+        `STOP AND ASK THE USER WHEN: the task is ambiguous (multiple approaches, unclear what/where);`,
+        `you could not find what the user asked about after listing the parent directory;`,
+        `finishing would delete/overwrite important files;`,
+        `or you are stuck after 2+ different approaches.`,
+        `Ask via the "question" tool (one short question, options when known) and wait.`,
+        `Plain text only when interactive tools are unavailable.`,
+    ];
+    if (isWin) {
+        lines.push(`Windows (PowerShell): use list_dir/read_file/delete_file/create_dir tools instead of dir/type/del/mkdir.`, `No PowerShell cmdlets (Get-Content, Select-Object, Write-Output), no head/tail/grep/cat.`, `Forward slashes in paths. CWD: ${baseDir}`);
+    }
+    // MMA — Bun-only проект (скрипты package.json, Bun API в коде): модель
+    // должна предпочитать bun, а не node/tsx/ts-node, для запуска TypeScript
+    // (наблюдалось: модель жгла 10+ итераций на установку tsx вместо `bun file.ts`).
+    lines.push(`Runtime: Bun is available — run TypeScript directly with "bun <file.ts>", tests with "bun test" (no tsx/ts-node needed).`, `Bash: pass "workdir", never "cd dir && cmd". One command per call.`, `Long-running: "background: true", else auto-backgrounded — check with process_log.`, ``, `VERIFY EVERY WRITE: after write_file/edit_file with NO [LSP errors], [LSP warnings], [Syntax check failed],`, `or [Project typecheck failed] in the result — call "lsp_check" on that file BEFORE marking the step done.`, `Never assume, prove.`, `PLAN QUALITY: each step = CONCRETE deliverables (exact paths, packages, commands).`, `No vague steps. 5-8 steps, init → verify.`, `Each step needs a 1:1 verification contract in "checks":`, `"file-exists:<path>", "command:<exact command>", or "manual:<what>".`, `For "check/fix errors" tasks each verification step names the exact proving command`, `("bun run build", "bun test", "lsp_check").`, `A step is done only after its check reports clean — then "plan_step step=N status=done".`);
+    if (config.autoPlan) {
+        lines.push(`PLAN (MANDATORY): file creation, package installs, or multi-action tasks MUST create a "plan" BEFORE starting.`);
+    }
+    // Баг в терминах runtime-поведения (что происходит при запуске) доказывается
+    // только ВОСПРОИЗВЕДЕНИЕМ — запуском app/build/browser и сверкой с реальным
+    // выводом. Модель решает сама, когда это применимо (без классификации по
+    // ключевым словам). Протухшие dev-серверы держат СТАРЫЙ пайплайн в памяти и
+    // продолжают кидать исходную ошибку (наблюдалось: старый vite на 5173–5176
+    // сыпал postcss после фикса на диске, а свежий на 5177 был чист) — фикс
+    // реален, только когда чист сервер ПОЛЬЗОВАТЕЛЯ.
+    lines.push(`Runtime verification: when a bug is described in terms of runtime behavior`, `(what happens when the app runs), reproduce it —`, `run the app / build / browser tool — confirm the fix against actual runtime output`, `before calling "plan_step step=N status=done".`, `Check existing servers first (process_list/process_log): a stale dev server`, `runs the old pipeline and keeps failing after the fix.`, `Restart/kill it (process_kill) and verify the exact endpoint/port reported —`, `a fresh port does NOT prove the user's error is gone.`);
+    // Правила безопасности: при включённой защите модель должна знать ограничения
+    // заранее — заблокированный вызов стоит итерацию, а этот блок ~100 токенов
+    // один раз. Компактно и с cap, чтобы длинный blacklist не рвал бюджет.
+    const sec = config.security;
+    if (sec?.enabled) {
+        const secLines = [
+            `SECURITY RESTRICTIONS (enforced — blocked calls return "[SECURITY BLOCKED]", do not retry them):`,
+        ];
+        if (sec.bash?.enabled && sec.bash.blacklist.length > 0) {
+            const cmds = sec.bash.blacklist.slice(0, 15).join(", ");
+            secLines.push(`Forbidden bash commands: ${cmds}${sec.bash.blacklist.length > 15 ? ", …" : ""}.`);
+            if (sec.bash.whitelist.length > 0) {
+                secLines.push(`Only whitelisted bash commands are allowed: ${sec.bash.whitelist.slice(0, 15).join(", ")}.`);
+            }
+            if (sec.bash.blockDangerousFlags) {
+                secLines.push(`Pipes/redirects/chaining (| > >> ; &&) in bash are blocked — one plain command per call.`);
+            }
+        }
+        if (sec.paths?.enabled && sec.paths.denied.length > 0) {
+            const paths = sec.paths.denied.slice(0, 10).join(", ");
+            secLines.push(`Denied paths (read/write): ${paths}${sec.paths.denied.length > 10 ? ", …" : ""}.`);
+        }
+        if (sec.network?.enabled && sec.network.deniedDomains.length > 0) {
+            const domains = sec.network.deniedDomains.slice(0, 10).join(", ");
+            secLines.push(`Denied network domains: ${domains}${sec.network.deniedDomains.length > 10 ? ", …" : ""}.`);
+        }
+        if (secLines.length > 1) {
+            lines.push(...secLines);
+        }
+    }
+    const hasMCP = config.mcpServers && Object.values(config.mcpServers).some((s) => s.enabled !== false);
+    if (hasMCP) {
+        lines.push(`MCP servers are available — use the named MCP tools (prefixed mcp__) to query external services.`);
+    }
+    return lines.join("\n");
+}

package/dist/core/version.js

@@ -1,9 +1,11 @@
+/** Версия MMA: читается из package.json в рантайме. */
 import { existsSync, readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 /**
- * Read the MMA version from package.json at runtime (never a static import —
- * bundlers inline a stale value at build time, see design rule #12).
+ * Читает версию MMA из package.json в рантайме (не статическим импортом —
+ * бандлеры инлайнят устаревшее значение на этапе сборки, см. правило №12).
+ * @returns версия из package.json либо "0.0.0", если файл не найден/бит.
  */
 export function readMmaVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -16,11 +18,11 @@ export function readMmaVersion() {
                     return raw.version;
             }
             catch {
-                // Broken package.json — fall through to the next candidate
+                // Битый package.json — пробуем следующий кандидат
             }
         }
     }
     return "0.0.0";
 }
-/** Legacy alias — use readMmaVersion(). */
+/** Устаревший алиас — используй readMmaVersion(). */
 export const readVersion = readMmaVersion;

package/dist/core/web-host.js

@@ -0,0 +1,34 @@
+import { defaultOutputBus } from "../output/bus";
+/** Реализация хоста для `mma web` — без TTY, без LineEditor. */
+export class WebHost {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    isBusy() {
+        return this.deps.isBusy();
+    }
+    async submit(text, o) {
+        if (this.deps.isBusy())
+            throw new Error("agent is busy");
+        for (const url of o?.images ?? [])
+            this.deps.addPendingImage?.(url);
+        return this.deps.runAgent(text);
+    }
+    interrupt() {
+        if (this.deps.isBusy())
+            this.deps.interrupt();
+    }
+    subscribeOutput(fn) {
+        return defaultOutputBus.subscribe(fn);
+    }
+    async executeCommand(line) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("/"))
+            return;
+        await this.deps.executeCommand(trimmed);
+    }
+    getState() {
+        return this.deps.getState();
+    }
+}

package/dist/core/workspace.js

@@ -1,6 +1,7 @@
+/** Резолвинг путей workspace: поиск корня проекта по манифестам. */
 import { existsSync, readdirSync } from "fs";
 import { resolve, isAbsolute, join } from "path";
-/** Files/dirs that mark a directory as a project root. */
+/** Файлы/каталоги — маркеры корня проекта. */
 const PROJECT_MANIFESTS = [
     "package.json",
     "bun.lockb",
@@ -14,7 +15,7 @@ const PROJECT_MANIFESTS = [
     "Gemfile",
     "composer.json",
 ];
-/** Immediate subdirectories that are never candidate project roots. */
+/** Подкаталоги, никогда не кандидаты в корень проекта. */
 const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".hg", ".svn"]);
 const subdirCache = new Map();
 function scanSubdirs(baseDir) {
@@ -35,27 +36,30 @@ function scanSubdirs(baseDir) {
         subdirCache.set(baseDir, dirs);
     return dirs;
 }
+/**
+ * Есть ли в каталоге манифест проекта.
+ * @param dir каталог для проверки.
+ * @returns true, если найден известный манифест.
+ */
 export function hasProjectManifest(dir) {
     return PROJECT_MANIFESTS.some((m) => existsSync(join(dir, m)));
 }
 /**
- * Resolve a file/dir path inside a workspace, tolerating the common case
- * where the agent runs from a parent directory while the actual project
- * lives in a single immediate subdirectory (e.g. baseDir=<repo>,
- * project=<repo>/app). Resolution order:
- *   1. absolute path as-is;
- *   2. baseDir/<p> тАФ project rooted directly at baseDir;
- *   3. <subdir>/<p> for each immediate project subdirectory of baseDir
- *      (manifest-bearing subdirectories are preferred).
- * Returns baseDir/<p> as a fallback when nothing exists, so callers that
- * check existsSync() still correctly report the path as missing.
+ * Резолвит путь внутри workspace. Терпит запуск из родителя, когда проект
+ * лежит в одном подкаталоге (baseDir=<repo>, проект=<repo>/app). Порядок:
+ *   1. абсолютный путь как есть;
+ *   2. baseDir/<p> — проект прямо в baseDir;
+ *   3. <subdir>/<p> по подкаталогам (приоритет — с манифестом).
+ * Фолбэк — baseDir/<p>, чтобы вызывающий через existsSync() корректно
+ * определил отсутствие пути.
+ * @param baseDir корень workspace; @param p относительный/абсолютный путь.
  */
 export function resolveProjectPath(baseDir, p) {
     const abs = isAbsolute(p) ? p : resolve(baseDir, p);
     if (existsSync(abs))
         return abs;
-    // baseDir itself is a project root тАФ paths are relative to it. Probing
-    // subdirectories here would match files in unrelated nested packages.
+    // Сам baseDir — корень проекта: подкаталоги не сканируем, иначе
+    // зацепим файлы посторонних вложенных пакетов.
     if (hasProjectManifest(baseDir))
         return abs;
     let fallback = abs;
@@ -70,7 +74,7 @@ export function resolveProjectPath(baseDir, p) {
     }
     return fallback;
 }
-/** Clear the internal subdirectory cache (used by tests). */
+/** Сбрасывает кэш подкаталогов (нужен тестам). */
 export function clearWorkspaceCache() {
     subdirCache.clear();
 }

package/dist/i18n/index.js

@@ -1,3 +1,4 @@
+// i18n: плоские словари en/ru, t(key, params) с фолбэком на английский.
 import en from "./en.json";
 import ru from "./ru.json";
 const locales = { en, ru };
@@ -22,25 +23,58 @@ const flat = {};
 for (const [name, dict] of Object.entries(locales)) {
     flat[name] = flatten(dict);
 }
+/**
+ * Переключает текущую локаль. Неизвестное имя игнорируется.
+ * @param locale имя локали ("en" | "ru").
+ */
 export function setLocale(locale) {
     if (flat[locale]) {
         currentLocale = locale;
     }
 }
+/**
+ * Плоские словари по именам локалей. Нужны веб-API, чтобы отдать все переводы
+ * в браузер для локализации его интерфейса. Только чтение — не мутировать.
+ */
+export function getFlatDicts() {
+    return flat;
+}
+/**
+ * Подменяет/добавляет словарь локали в рантайме (плагины, тесты).
+ * @param name имя локали; @param dict вложенный словарь переводов.
+ */
 export function loadLocale(name, dict) {
     locales[name] = dict;
     flat[name] = flatten(dict);
 }
+/**
+ * Ставит обработчик отсутствующих ключей (debug-диагностика). Подключается
+ * из bootstrap на logger.debug, чтобы не тянуть логер в i18n (циклы).
+ */
+let missingKeyReporter;
+export function setMissingKeyReporter(reporter) {
+    missingKeyReporter = reporter;
+}
+/**
+ * Переводит ключ с подстановкой `{params}`. Нет ключа — вернёт сам ключ.
+ * @param key точечный ключ; @param params значения подстановок.
+ */
 export function t(key, params) {
     const localeDict = flat[currentLocale];
-    const enDict = flat["en"];
-    let template = localeDict?.[key] ?? enDict?.[key] ?? key;
+    const enDict = flat.en;
+    const template = localeDict?.[key] ?? enDict?.[key];
+    if (template === undefined) {
+        missingKeyReporter?.(key);
+        return key;
+    }
     if (!template)
         return key;
     if (params) {
+        let result = template;
         for (const [k, v] of Object.entries(params)) {
-            template = template.replaceAll(`{${k}}`, String(v));
+            result = result.replaceAll(`{${k}}`, String(v));
         }
+        return result;
     }
     return template;
 }

package/dist/index.js

@@ -1,3 +1,6 @@
+/**
+ * Публичные экспорты пакета и библиотечный хелпер миграции конфига.
+ */
 export { DEFAULTS, loadConfig } from "./config/index";
 export { Logger } from "./logger/index";
 export { PromptBuilder } from "./core/index";
@@ -10,12 +13,13 @@ import { t } from "./i18n/index";
 import { defaultOutputBus, getDefaultChannel } from "./output";
 import { homedir } from "os";
 import { join } from "path";
+import { MMA_DIR_NAME } from "./config/paths";
 export function checkMigration(configDir) {
-    const dir = configDir || join(homedir(), ".mma");
+    const dir = configDir || join(homedir(), MMA_DIR_NAME);
     const detector = new MigrationDetector(dir);
     if (detector.needsMigration()) {
-        // Ensure a terminal subscriber exists before emitting to the bus; library
-        // consumers have no other eager channel creation.
+        // Терминальный подписчик должен существовать до отправки в шину: у
+        // библиотечных потребителей нет другого eager-создания канала.
         getDefaultChannel();
         const backup = new BackupManager(dir);
         backup.backupConfig();