micro-models-agent 2.11.0 → 2.12.0

package/dist/modules/memory/module.js

@@ -1,10 +1,10 @@
-import { homedir } from "os";
-import { join } from "path";
 import { MemoryStore } from "./store";
 import { rememberTool } from "../../tools/remember";
 import { recallTool } from "../../tools/recall";
 import { estimateTokens } from "../../llm/token-counter";
+import { globalMemoryDir } from "../../config/paths";
 const MEMORY_MD_FILES = ["errors", "conventions", "decisions", "facts"];
+/** Модуль долговременной памяти: системный блок + тулы `remember`/`recall`. */
 export class MemoryModule {
     name = "memory";
     store;
@@ -13,10 +13,11 @@ export class MemoryModule {
             this.store = storeOrDir;
         }
         else {
-            const dir = storeOrDir || join(homedir(), ".mma", "memory");
+            const dir = storeOrDir || globalMemoryDir();
             this.store = new MemoryStore(dir);
         }
     }
+    /** Системный блок: преференсы пользователя + хвост уроков прошлых сессий. */
     getSystemPromptBlock() {
         const parts = [];
         const prefs = this.store.getPreferences();
@@ -40,9 +41,9 @@ export class MemoryModule {
         };
     }
     /**
-     * Bounded tail of the append-only .md memory files (errors, conventions,
-     * decisions, facts). This is what makes past-session lessons visible in the
-     * system prompt — without it the loop's error rules are write-only.
+     * Ограниченный хвост append-only .md-файлов памяти (errors, conventions,
+     * decisions, facts). Именно он делает уроки прошлых сессий видимыми в
+     * системном промпте — без него правила ошибок цикла только пишутся.
      */
     getMemoryTail() {
         const sections = [];
@@ -63,14 +64,16 @@ export class MemoryModule {
         if (sections.length === 0)
             return null;
         let joined = sections.join("\n\n");
-        // Hard cap so a huge errors.md can never blow the system prompt budget.
+        // Жёсткий кап, чтобы огромный errors.md не раздул бюджет системного промпта.
         if (joined.length > 1200)
-            joined = joined.slice(0, 1200) + "\n…";
+            joined = `${joined.slice(0, 1200)}\n…`;
         return joined;
     }
+    /** Тулы модуля: `remember` (запись) и `recall` (чтение/поиск). */
     getToolDefinitions() {
         return [rememberTool, recallTool];
     }
+    /** Плагин: тот же блок памяти через хук построения промпта. */
     getPlugin() {
         return {
             name: "memory",
@@ -91,6 +94,7 @@ export class MemoryModule {
             },
         };
     }
+    /** Доступ к underlying-хранилищу (для команд `/memory`, тестов). */
     getStore() {
         return this.store;
     }

package/dist/modules/memory/search.js

@@ -1,11 +1,14 @@
+// Поиск по файлам памяти: подстрока без учёта регистра по .md и preferences.json.
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
 const MEMORY_FILES = ["conventions", "decisions", "errors", "facts"];
+/** Поисковик по каталогу памяти (создаётся под запрос, состояния нет). */
 export class MemorySearch {
     memoryDir;
     constructor(memoryDir) {
         this.memoryDir = memoryDir;
     }
+    /** Ищет подстроку (без учёта регистра) по .md-файлам и преференсам. */
     query(query) {
         const results = [];
         const lowerQuery = query.toLowerCase();
@@ -21,7 +24,7 @@ export class MemorySearch {
                 }
             }
         }
-        // Search preferences.json
+        // Поиск по preferences.json
         const prefsPath = join(this.memoryDir, "preferences.json");
         if (existsSync(prefsPath)) {
             try {

package/dist/modules/memory/store.js

@@ -1,7 +1,9 @@
+// Хранилище памяти: append-only .md-категории и preferences.json в каталоге.
 import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { MemorySearch } from "./search";
 const MEMORY_FILES = ["conventions", "decisions", "errors", "facts"];
+/** Хранилище памяти: категории-заметки с дописыванием и ключ-значение преференсов. */
 export class MemoryStore {
     memoryDir;
     constructor(memoryDir) {
@@ -19,18 +21,33 @@ export class MemoryStore {
             mkdirSync(this.memoryDir, { recursive: true });
         }
     }
+    /**
+     * Отклоняет имена вне фиксированных категорий памяти. Без этого
+     * подставленная моделью `category` (поле `enum` в схеме тула — подсказка,
+     * а не enforcement) могла бы выйти из каталога памяти, например
+     * `recall category="../../Users/x/notes"` прочитал бы чужой `notes.md`.
+     */
+    fileFor(name) {
+        if (!MEMORY_FILES.includes(name)) {
+            throw new Error(`unknown memory category: ${name}`);
+        }
+        return join(this.memoryDir, `${name}.md`);
+    }
+    /** Читает весь файл категории (пусто, если файла нет). */
     read(name) {
-        const path = join(this.memoryDir, `${name}.md`);
+        const path = this.fileFor(name);
         if (!existsSync(path))
             return "";
         return readFileSync(path, "utf-8");
     }
+    /** Дописывает запись с таймстампом в файл категории. */
     append(name, entry) {
-        const path = join(this.memoryDir, `${name}.md`);
+        const path = this.fileFor(name);
         const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
         const formatted = `- **${timestamp}** — ${entry}\n`;
         appendFileSync(path, formatted, "utf-8");
     }
+    /** Ищет подстроку по всем файлам памяти. */
     search(query) {
         const searchModule = new MemorySearch(this.memoryDir);
         return searchModule.query(query);
@@ -38,6 +55,7 @@ export class MemoryStore {
     prefsPath() {
         return join(this.memoryDir, "preferences.json");
     }
+    /** Все преференсы пользователя (пусто, если файла нет/бит). */
     getPreferences() {
         const path = this.prefsPath();
         if (!existsSync(path))
@@ -49,11 +67,13 @@ export class MemoryStore {
             return {};
         }
     }
+    /** Записывает/обновляет один преференс. */
     setPreference(key, value) {
         const prefs = this.getPreferences();
         prefs[key] = value;
         writeFileSync(this.prefsPath(), JSON.stringify(prefs, null, 2), "utf-8");
     }
+    /** Удаляет преференс; false, если ключа не было. */
     deletePreference(key) {
         const prefs = this.getPreferences();
         if (!(key in prefs))
@@ -62,6 +82,24 @@ export class MemoryStore {
         writeFileSync(this.prefsPath(), JSON.stringify(prefs, null, 2), "utf-8");
         return true;
     }
+    /** Удаляет n-ю (с 1) append-only запись (весь её блок) из файла категории. */
+    deleteEntry(name, n) {
+        const path = join(this.memoryDir, `${name}.md`);
+        if (!existsSync(path))
+            return false;
+        const lines = readFileSync(path, "utf-8").split(/\r?\n/);
+        const starts = lines
+            .map((l, i) => (l.startsWith("- ") ? i : -1))
+            .filter((i) => i >= 0);
+        if (n < 1 || n > starts.length)
+            return false;
+        const start = starts[n - 1];
+        const end = n < starts.length ? starts[n] : lines.length;
+        lines.splice(start, end - start);
+        writeFileSync(path, lines.join("\n"), "utf-8");
+        return true;
+    }
+    /** Дописывает структурированное правило «паттерн/причина/решение». */
     appendRule(category, pattern, cause, solution) {
         const entry = `**pattern:** ${pattern}\n  **cause:** ${cause}\n  **solution:** ${solution}`;
         this.append(category, entry);

package/dist/modules/onboarding/init.js

@@ -0,0 +1,47 @@
+// Генерация/улучшение AGENTS.md: один прогон агента со строгим allowlist без bash.
+import { join } from "path";
+import { estimateTokens } from "../../llm/token-counter";
+import { preflightFromConfig } from "../providers/preflight";
+import { INIT_SYSTEM_PROMPT, INIT_TOOLS } from "./prompts";
+import { t } from "../../i18n/index";
+import { pc } from "../../ui/colors";
+/**
+ * Генерирует или улучшает AGENTS.md воркспейса. Один прогон агента со
+ * строгим allowlist (без bash). Возвращает false, когда провайдер недоступен
+ * или уже активен другой онбординг-режим.
+ */
+export async function runInit(ctx, opts = {}) {
+    if (ctx.toolCtx.onboarding) {
+        ctx.output.writeLine(pc.yellow(t("onboarding.already")));
+        return false;
+    }
+    if (process.stdout.isTTY !== true) {
+        ctx.output.writeLine(pc.yellow(t("onboarding.non_interactive")));
+        return false;
+    }
+    const check = opts.preflight ?? (() => preflightFromConfig(ctx));
+    const pre = await check();
+    if (!pre.ok) {
+        ctx.output.writeLine(pc.yellow(t("repl.init_unavailable", { reason: pre.reason })));
+        ctx.output.writeLine(t("repl.meet_unavailable_hint"));
+        return false;
+    }
+    const block = {
+        content: INIT_SYSTEM_PROMPT,
+        priority: "high",
+        essential: true,
+        estimatedTokens: estimateTokens(INIT_SYSTEM_PROMPT),
+    };
+    ctx.agent.pushPromptBlock(block);
+    ctx.toolCtx.toolAllowlist = [...INIT_TOOLS];
+    ctx.toolCtx.writePathAllowlist = [join(ctx.baseDir, "AGENTS.md")];
+    try {
+        await ctx.runAgent(t("repl.init_start_prompt", { dir: join(ctx.baseDir, "AGENTS.md") }));
+    }
+    finally {
+        ctx.agent.removePromptBlock(block);
+        ctx.toolCtx.toolAllowlist = undefined;
+        ctx.toolCtx.writePathAllowlist = undefined;
+    }
+    return true;
+}

package/dist/modules/onboarding/meet.js

@@ -0,0 +1,30 @@
+import { preflightFromConfig } from "../providers/preflight";
+import { enterMeetMode } from "./mode";
+import { t } from "../../i18n/index";
+import { pc } from "../../ui/colors";
+/**
+ * Запускает интервью-знакомство. Проверяет провайдер, входит в meet-режим
+ * и делает первый ход агента. Режим живёт между ходами REPL, пока не
+ * сработает `meet_done` или пользователь не выйдет.
+ * Возвращает false, когда провайдер недоступен (ничего не меняется).
+ */
+export async function runMeet(ctx, opts = {}) {
+    if (ctx.toolCtx.onboarding) {
+        ctx.output.writeLine(pc.yellow(t("repl.meet_already_hint")));
+        return true;
+    }
+    if (process.stdout.isTTY !== true) {
+        ctx.output.writeLine(pc.yellow(t("onboarding.non_interactive")));
+        return false;
+    }
+    const check = opts.preflight ?? (() => preflightFromConfig(ctx));
+    const pre = await check();
+    if (!pre.ok) {
+        ctx.output.writeLine(pc.yellow(t("repl.meet_unavailable", { reason: pre.reason })));
+        ctx.output.writeLine(t("repl.meet_unavailable_hint"));
+        return false;
+    }
+    enterMeetMode(ctx);
+    await ctx.runAgent(t("repl.meet_start_prompt"));
+    return true;
+}

package/dist/modules/onboarding/mode.js

@@ -0,0 +1,30 @@
+import { estimateTokens } from "../../llm/token-counter";
+import { MEET_SYSTEM_PROMPT, MEET_TOOLS } from "./prompts";
+/**
+ * Входит в meet-режим на shared-агенте: режет тулы до allowlist, создаёт
+ * shared-состояние онбординга (с блоком гайда) и инжектит гайд интервью.
+ * Режим живёт между ходами REPL до `exitMeetMode` (по сентинелу `meet_done`).
+ */
+export function enterMeetMode(ctx) {
+    const block = {
+        content: MEET_SYSTEM_PROMPT,
+        priority: "high",
+        essential: true,
+        estimatedTokens: estimateTokens(MEET_SYSTEM_PROMPT),
+    };
+    ctx.toolCtx.toolAllowlist = [...MEET_TOOLS];
+    ctx.toolCtx.onboarding = { done: false, block };
+    ctx.agent.pushPromptBlock(block);
+}
+/** Выходит из meet-режима: убирает гайд и возвращает полные тулы. */
+export function exitMeetMode(ctx) {
+    const block = ctx.toolCtx.onboarding?.block;
+    if (block)
+        ctx.agent.removePromptBlock(block);
+    ctx.toolCtx.toolAllowlist = undefined;
+    ctx.toolCtx.onboarding = undefined;
+}
+/** True, когда сентинел-тул сработал в активной meet-сессии. */
+export function isMeetDone(ctx) {
+    return ctx.toolCtx.onboarding?.done === true;
+}

package/dist/modules/onboarding/prompts.js

@@ -0,0 +1,43 @@
+// Промпты и allowlist онбординга: интервью «Познакомимся» и автор AGENTS.md.
+/** Тулы, доступные во время интервью (строгий allowlist). */
+export const MEET_TOOLS = ["remember", "question", "meet_done"];
+/** Тулы, доступные при генерации AGENTS.md (строгий allowlist). */
+export const INIT_TOOLS = [
+    "read_file",
+    "list_dir",
+    "glob",
+    "grep",
+    "project_map",
+    "question",
+    "write_file",
+    "edit_file",
+];
+/**
+ * Полускриптовое интервью. Гайд отвечает за покрытие и вайтлист ключей
+ * преференсов; модель — за формулировки и лёгкие уточнения. Домен-нейтрально.
+ * Тело промпта — на английском: уходит модели как есть.
+ */
+export const MEET_SYSTEM_PROMPT = `You are getting acquainted with the user. This is a short interview, not a task.
+Rules:
+- Ask 1-3 short questions per turn, in the user's language.
+- For closed / multiple-choice questions (e.g. response style, autonomy), use the "question" tool and provide explicit options. For open-ended questions, ask in plain text.
+- START by asking what the user will mainly use the agent for (their domain / usage profile): e.g. software development, working with APIs, smart home, automation, personal assistant, web search, computer setup — or anything else. Never assume their use case is software development.
+- Then cover: name; reply language; response style (concise | balanced | detailed); tools & experience; working habits; hard "do not do without asking" rules; goals.
+- Only if the user named software development as a use case may you ask about code / commit language.
+- Save each answer with the "remember" tool. Use category=preferences with these keys ONLY: domain, name, language, response_style, autonomy, code_language. Use category=facts (free text, user's language) for experience, habits, goals and any concrete "do not" rule (preserve it verbatim).
+- Leave code_language out entirely when development is not a use case.
+- Keep preference values as canonical English tokens: domain=development,api; response_style=concise|balanced|detailed; autonomy=ask|act. Record language as the token the user chose (e.g. language=ru) and name exactly as the user wrote it.
+- Never touch the file system, run commands, or inspect the repository.
+- When every topic is covered (or the user wants to stop), give a one-line summary of what you remembered, then call the "meet_done" tool.`;
+/**
+ * Гайд автора AGENTS.md. Домен-нейтрален: код, доки, заметки или конфиги;
+ * код — лишь частный случай. Тело промпта — на английском: уходит модели как есть.
+ */
+export const INIT_SYSTEM_PROMPT = `You create or improve an AGENTS.md file for the current workspace.
+Rules:
+- First read what is here: use project_map, read_file, list_dir, glob, grep. The workspace may be code, docs, notes, configs or mixed — never assume a programming project.
+- If AGENTS.md already exists, IMPROVE it in place: produce a proposed full version, show it, and let the user confirm before writing. Never silently overwrite.
+- Capture: purpose & usage profile; key structure; how to run/use things (only if applicable); conventions; setup quirks/gotchas; references to existing instruction sources (e.g. Cursor/Copilot rules).
+- Ask targeted questions only when the files cannot answer.
+- Keep it concise and within the instructions budget.
+- Write with write_file or edit_file; do not run shell commands.`;

package/dist/modules/pipelines/engine.js

@@ -1,6 +1,11 @@
 import { t } from "../../i18n/index";
+/** Движок пайплайна: порядок обхода зависимостей и учёт статусов шагов. */
 export class PipelineEngine {
     stepStatus = new Map();
+    /**
+     * Топологически сортирует шаги по `depends_on`. Бросает при цикле.
+     * Возвращает id в порядке выполнения.
+     */
     resolveDependencies(steps) {
         const visited = new Set();
         const inStack = new Set();
@@ -29,6 +34,7 @@ export class PipelineEngine {
         }
         return order;
     }
+    /** Шаги, готовые к запуску: не завершены, не в работе/провале, зависимости закрыты. */
     getReadySteps(steps, completed) {
         return steps.filter((s) => {
             if (completed.has(s.id))
@@ -42,18 +48,22 @@ export class PipelineEngine {
             return s.depends_on.every((d) => completed.has(d));
         });
     }
+    /** Ставит статус шага. */
     setStepStatus(stepId, status) {
         this.stepStatus.set(stepId, status);
     }
+    /** Статус шага; неизвестному — `pending`. */
     getStepStatus(stepId) {
         return this.stepStatus.get(stepId) || "pending";
     }
+    /** True, когда все шаги `done` или `skipped`. */
     isComplete(stepIds) {
         return stepIds.every((id) => {
             const s = this.stepStatus.get(id);
             return s === "done" || s === "skipped";
         });
     }
+    /** Сбрасывает все статусы (перезапуск пайплайна). */
     reset() {
         this.stepStatus.clear();
     }

package/dist/modules/pipelines/index.js

@@ -1,3 +1,4 @@
+// Публичная поверхность пайплайнов: парсер, движок, шаблоны и типы.
 export { PipelineParser } from "./parser";
 export { PipelineEngine } from "./engine";
 export { TemplateEngine } from "./template";

package/dist/modules/pipelines/parser.js

@@ -1,10 +1,13 @@
+// Минималистичный парсер YAML-описаний пайплайнов (без внешних зависимостей).
 import { t } from "../../i18n/index";
+/** Парсер описания пайплайна. Бросает при невалидном YAML/полях. */
 export class PipelineParser {
+    /** Разбирает YAML в `Pipeline`; бросает с локализованной ошибкой. */
     static parse(yaml) {
         const lines = yaml.split("\n").filter((l) => l.trim());
         const result = {};
         let currentSection = null;
-        let currentSteps = [];
+        const currentSteps = [];
         for (const line of lines) {
             if (line.match(/^\w+:/) && !line.startsWith(" ") && !line.startsWith("  -")) {
                 const [key, ...valParts] = line.split(":");

package/dist/modules/pipelines/template.js

@@ -1,4 +1,8 @@
+// Подстановка в шаблоны: `{param}` из params и `{{steps.<id>.output}}` из выходов шагов.
 export class TemplateEngine {
+    /**
+     * Рендерит шаблон. Неизвестный выход шага остаётся плейсхолдером как есть.
+     */
     static render(template, params, stepOutputs) {
         let result = template;
         for (const [key, val] of Object.entries(params)) {