micro-models-agent 2.18.0 → 2.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +262 -246
  3. package/dist/i18n/en.json +1 -1
  4. package/dist/i18n/ru.json +1 -1
  5. package/dist/main.js +264 -264
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -3,83 +3,99 @@
3
3
  [![npm version](https://img.shields.io/npm/v/micro-models-agent)](https://www.npmjs.com/package/micro-models-agent)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
5
 
6
- **MMA** — универсальный агент-харнесс, оптимизированный для **небольших локальных языковых моделей** (9B параметров, 32K–64K контекст). Работает на ноутбуке, облачное API не требуется. Это не «агент только для кода»: разработка, поиск в интернете, автоматизация, работа с API, умный дом, персональный ассистент — любой сценарий.
6
+ **A universal agent harness built for small local LLMs** — the kind that fit on your laptop
7
+ (9B parameters, 32K–64K context). No cloud API required. And it is *not* a coding-only agent:
8
+ dev work, web research, home automation, API glue, personal assistant — bring any task you like.
7
9
 
8
10
  ```bash
9
11
  npm install -g micro-models-agent
10
- mma "перепиши модуль авторизации на JWT"
11
- mma "какая погода в Москве и собери сводку за неделю"
12
+ mma "rewrite the auth module to use JWT"
13
+ mma "what's the weather in Berlin? summarize the week"
12
14
  ```
13
15
 
14
- Создан и протестирован с [Qwen3.5-9B](https://qwen.readthedocs.io/) через LM Studio / Ollama / llama.cpp.
16
+ Built and battle-tested with [Qwen3.5-9B](https://qwen.readthedocs.io/) via LM Studio / Ollama / llama.cpp.
15
17
 
16
18
  ---
17
19
 
18
- ## Зачем MMA?
20
+ ## Why MMA?
19
21
 
20
- Большинство агентов (Devin, Cursor, Copilot) завязаны на облачные модели или дорогие API — и предполагают, что задача про код. MMA работает иначе: это **общий** харнесс, где программирование — лишь один из сценариев.
22
+ Most agents (Devin, Cursor, Copilot) are glued to cloud models or pricey APIs — and assume the job is writing code. MMA takes a different bet: a **general-purpose** harness where coding is just one use case.
21
23
 
22
- - **Создан для моделей 9B** — оптимизирован под Qwen3.5-9B на обычном железе
23
- - **Не требует облака** — полностью работает офлайн с любым OpenAI-совместимым бэкендом
24
- - **Выживает в узком контексте** — умное sliding-window compaction держит 32K-модели продуктивными
25
- - **Отлавливает галлюцинации** — 3-стадийный пайплайн валидации ловит выдумки, к которым склонны маленькие модели
26
- - **Agent-Level MoE** — иерархическая декомпозиция задач: маленькие модели справляются со сложной многошаговой работой
24
+ - **Tuned for 9B models** — designed around Qwen3.5-9B running on ordinary hardware
25
+ - **Cloud-optional by design** — works fully offline against any OpenAI-compatible backend
26
+ - **Thrives in a tight context** — smart sliding-window compaction keeps 32K models productive
27
+ - **Catches hallucinations** — a 3-stage validation pipeline spots the lies small models love to tell
28
+ - **Agent-Level MoE** — hierarchical task decomposition lets small models ship big multi-step work
27
29
 
28
30
  ---
29
31
 
30
- ## Возможности
31
-
32
- - **6-состояний цикл агента** (INIT → THINK → ACT → OBSERVE → OUTPUT → ERROR) — чистый, предсказуемый, отлаживаемый
33
- - **Управление бюджетом контекста** — динамический бюджет под модель, sliding-window compaction с извлечением фактов/решений/ошибок
34
- - **Детекция галлюцинаций** — фактическая (пути файлов), согласованности (откат решений), уверенности (короткие/повторяющиеся ответы)
35
- - **Гарантии выполнения** — авто-планирование через LLM (без keyword-эвристик), stuck-detection, off-track предупреждения, авто-продвижение плана
36
- - **Agent-Level MoE** — Router + экспертные сабагенты с фильтрацией инструментов, изолированным контекстом, файловым скоупом, топологическим параллельным выполнением, re-plan-циклом и машиночитаемой верификацией (`success_criteria`)
37
- - **Инструменты** — ФС, шелл, веб-поиск/fetch, браузер (Playwright), планирование, память, сабагенты, MCP, пайплайны, LSP, процессы. Ядро (~26) + модульные `plan`/`todo`/`verify`/`lsp_check`/`project_map`/`set_thinking`/`scope_request`; `question`/`approve` включаются только в веб-режиме
38
- - **24 модуля** — скиллы, плагины, MCP, пайплайны, indexer, память, контекст, сессии, браузер, выполнение, детекция галлюцинаций, апдейтер, профиль пользователя, LSP, сертификация моделей, безопасность, артефакты, процессы, ценообразование, онбординг, провайдеры, reasoning, setup, webui
39
- - **Веб-режим `mma web`** — браузерный чат (SSE + REST) на том же ядре и сессиях, без TTY; первый запуск открывает мастер настройки прямо в браузере
40
- - **Онбординг** — `mma setup` (мастер провайдера), `mma meet` («Познакомимся»: интервью в глобальную память), `mma agents init` (генерация/улучшение `AGENTS.md`)
41
- - **MCP-клиент** — подключение к любому MCP-серверу (stdio или SSE)
42
- - **Модуль безопасности** — включён по умолчанию (balanced): валидация bash-команд, path/network-политики (SSRF), сканирование контента, шифрование сессий, audit-лог; always-on защита путей (`.git/`, `.env*`, ключи)
43
- - **LSP-диагностика** — TypeScript/CSS/HTML серверы: проверка типов после каждой правки и по запросу
44
- - **YAML-пайплайны** — DAG-движок с параллельными волнами, зависимостями и повторными попытками
45
- - **Промпт-кешинг** — cache-подсказки (llama.cpp / OpenAI / OpenRouter) + метрики hit-rate и экономии (`⟡` cache line)
46
- - **Context log** — `--context-log` пишет весь уходящий в модель контекст в git-подобный diff (`context.diff`)
47
- - **Управление сессиями** — постоянные JSONL-сессии, REPL-команды, `mma session export`
48
- - **Карта проекта** — обход файлов + извлечение экспортов + дисковый кэш с валидацией свежести (signature)
49
- - **Единый `/config`** — реестр настроек с валидацией + сахар `/model`, `/provider`, `/context`, `/reasoning`, `/verbose`
50
- - **i18n** — все строки интерфейса через `t()`, включены английский и русский
51
- - **Вывод без гонок** — single-writer `OutputChannel`: никаких прямых `console.*`/stdout вне CLI и машинного JSON
52
- - **8K–120K контекст** — адаптируется под любое контекстное окно модели
53
- - **Без TUI** — минимальный CLI + REPL с markdown→ANSI форматированием
54
- - **llama.cpp / Jinja proven** — проверено на граничных случаях Jinja-шаблонов (system-first, streaming fallback, явный `stream: false`)
32
+ ## Features
33
+
34
+ **The agent loop**
35
+
36
+ - **6-state agent loop** (`INIT → THINK → ACT → OBSERVE → OUTPUT → ERROR`) — clean, predictable, debuggable
37
+ - **Context budget management** — per-model budgets with sliding-window compaction that preserves facts, decisions, and errors
38
+ - **Hallucination detection** — fact checks (file paths), consistency checks (decision rollbacks), confidence checks (short or repeated answers)
39
+ - **Execution guarantees** — LLM-driven auto-planning (no keyword heuristics), stuck detection, off-track warnings, automatic plan advancement
40
+
41
+ **Orchestration & scale**
42
+
43
+ - **Agent-Level MoE** — a router plus expert subagents with tool filtering, isolated context, file scoping, topological parallel execution, a re-plan cycle, and machine-readable verification (`success_criteria`)
44
+ - **YAML pipelines** — a DAG engine with parallel waves, dependencies, and retries
45
+ - **Project map** — file walking, export extraction, and an on-disk cache validated by freshness signature
46
+
47
+ **Tools & integrations**
48
+
49
+ - **Tools** — filesystem, shell, web search/fetch, browser (Playwright), planning, memory, subagents, MCP, pipelines, LSP, processes. A core set (~26) plus modular `plan`/`todo`/`verify`/`lsp_check`/`project_map`/`set_thinking`/`scope_request`; `question`/`approve` register only in web mode
50
+ - **24 modules** — skills, plugins, MCP, pipelines, indexer, memory, context, sessions, browser, execution, hallucination detection, updater, user profile, LSP, model certification, security, artifacts, processes, pricing, onboarding, providers, reasoning, setup, webui
51
+ - **MCP client** — connect to any MCP server (stdio or SSE)
52
+ - **LSP diagnostics** — TypeScript/CSS/HTML servers: type checks after every edit and on demand
53
+
54
+ **Experience**
55
+
56
+ - **Web mode `mma web`** — a browser chat (SSE + REST) on the same core and sessions, no TTY needed; first run opens the setup wizard right in the browser
57
+ - **Onboarding** — `mma setup` (provider wizard), `mma meet` ("Let's get acquainted": an interview written to global memory), `mma agents init` (generate/improve `AGENTS.md`)
58
+ - **Unified `/config`** — a validated settings registry plus sugar commands `/model`, `/provider`, `/context`, `/reasoning`, `/verbose`
59
+ - **Prompt caching** — cache hints (llama.cpp / OpenAI / OpenRouter) with hit-rate and savings metrics (the `⟡` cache line)
60
+ - **Context log** — `--context-log` writes the full outgoing model context to a git-style diff (`context.diff`)
61
+ - **Session management** — persistent JSONL sessions, REPL commands, `mma session export`
62
+ - **i18n** — every UI string goes through `t()`, with English and Russian bundled
63
+ - **Race-free output** — single-writer `OutputChannel`: no stray `console.*`/stdout outside the CLI and machine JSON
64
+ - **Flexible context** — adapts to any model window from 8K to 120K
65
+ - **No TUI** — a minimal CLI + REPL with markdown→ANSI formatting
66
+ - **llama.cpp / Jinja proven** — tested against tricky Jinja-template edge cases (system-first, streaming fallback, explicit `stream: false`)
67
+
68
+ **Safety**
69
+
70
+ - **Security module** — on by default (balanced policy): bash validation, path/network policies (SSRF), content scanning, session encryption, audit log, plus always-on protected paths (`.git/`, `.env*`, keys)
55
71
 
56
72
  ---
57
73
 
58
- ## Установка
74
+ ## Installation
59
75
 
60
- ### Требования
76
+ ### Requirements
61
77
 
62
- - **Среда выполнения:** [Bun](https://bun.sh) (рекомендуется) или Node.js ≥ 20
63
- - **LLM-бэкенд:** Любой OpenAI-совместимый сервер (LM Studio, Ollama, vLLM, llama.cpp, Together AI)
78
+ - **Runtime:** [Bun](https://bun.sh) (recommended) or Node.js ≥ 20
79
+ - **LLM backend:** any OpenAI-compatible server (LM Studio, Ollama, vLLM, llama.cpp, Together AI)
64
80
 
65
- ### Через npm (рекомендуется)
81
+ ### From npm (recommended)
66
82
 
67
83
  ```bash
68
84
  npm install -g micro-models-agent@latest
69
85
  ```
70
86
 
71
- После установки команда `mma` будет доступна в терминале. Если после установки `mma` не находится — попробуйте переоткрыть терминал или выполните:
87
+ The `mma` command is then available in your terminal. If `mma` isn't found, reopen your terminal or run:
72
88
 
73
89
  ```bash
74
90
  # PowerShell
75
91
  npm uninstall -g micro-models-agent
76
92
  npm install -g micro-models-agent@latest
77
93
 
78
- # Проверка
94
+ # Verify
79
95
  mma --version
80
96
  ```
81
97
 
82
- ### Из исходников
98
+ ### From source
83
99
 
84
100
  ```bash
85
101
  git clone https://github.com/your-org/micro-models-agent
@@ -90,79 +106,79 @@ bun run build:prod
90
106
 
91
107
  ---
92
108
 
93
- ## Быстрый старт
109
+ ## Quick Start
94
110
 
95
- ### 1. Запустите LLM-бэкенд
111
+ ### 1. Start an LLM backend
96
112
 
97
- Направьте MMA на любой OpenAI-совместимый эндпоинт. Пример с LM Studio:
113
+ Point MMA at any OpenAI-compatible endpoint. With LM Studio:
98
114
 
99
115
  ```bash
100
- # LM Studio слушает http://localhost:1234 по умолчанию
116
+ # LM Studio listens on http://localhost:1234 by default
101
117
  ```
102
118
 
103
- ### 2. Запустите мастер настройки
119
+ ### 2. Run the setup wizard
104
120
 
105
121
  ```bash
106
122
  bun run mma setup
107
123
  ```
108
124
 
109
- Сканирует локальные порты, находит модель, тестирует соединение и записывает конфиг. Устаревший алиас: `bun run mma init`.
125
+ It scans local ports, finds a model, tests the connection, and writes your config. Legacy alias: `bun run mma init`.
110
126
 
111
- ### 3. Используйте агента
127
+ ### 3. Use the agent
112
128
 
113
129
  ```bash
114
- # Одноразовый режим
115
- bun run mma "создай REST API на Express и добавь тесты"
130
+ # One-shot
131
+ bun run mma "build an Express REST API and add tests"
116
132
 
117
- # Интерактивный REPL
133
+ # Interactive REPL
118
134
  bun run dev
119
135
  ```
120
136
 
121
137
  ---
122
138
 
123
- ## Использование
139
+ ## Usage
124
140
 
125
141
  ### CLI
126
142
 
127
143
  ```bash
128
144
  bun run mma "<prompt>"
129
145
 
130
- # Подкоманды
131
- bun run mma setup # Интерактивный мастер настройки
132
- bun run mma init # Устаревший алиас mma setup (мастер провайдера)
133
- bun run mma meet # «Познакомимся» — интервью, пишет в память
134
- bun run mma agents init # Создать/улучшить AGENTS.md для workspace
146
+ # Subcommands
147
+ bun run mma setup # Interactive setup wizard
148
+ bun run mma init # Legacy alias of mma setup (provider wizard)
149
+ bun run mma meet # "Let's get acquainted" — interview, writes to memory
150
+ bun run mma agents init # Generate/improve AGENTS.md for the workspace
135
151
  bun run mma config set model qwen/qwen3.5-9b
136
152
  bun run mma config show
137
- bun run mma model list # Список доступных моделей (✔ = сертифицирована)
138
- bun run mma model use qwen3.5-9b # Переключить модель
139
- bun run mma model certify <name> # Сертификация модели на бэкенде
140
- bun run mma model cert-status <name> # Статус сертификации
141
- bun run mma model cert-list # Все сертификации
142
- bun run mma model uncertify <name> # Отозвать сертификацию
143
- bun run mma provider list # Список провайдеров
144
- bun run mma provider add local --url http://localhost:1234/v1 # Добавить провайдера
145
- bun run mma provider use opencode-zen # Хостед-провайдер (zen / go)
146
- bun run mma context # Токены/бюджет контекста (--system/--reserve)
147
- bun run mma map [summary|refresh|find] # Карта проекта
148
- bun run mma usage # Баланс провайдера (OpenRouter /key, /credits)
149
- bun run mma security status # Текущая конфигурация безопасности
150
- bun run mma security policies # Доступные политики (strict/balanced/permissive)
151
- bun run mma security set-policy strict # Применить политику
152
- bun run mma plugins list # Загруженные плагины (--all — включая встроенные)
153
- bun run mma session list # Список сессий
154
- bun run mma session show <id> # Детали сессии
155
- bun run mma session export <id> # Экспорт сессии (--format md|json|jsonl, --out -)
156
- bun run mma session delete <id> # Удалить сессию
157
- bun run mma web [--port N] [--host H] [--token T] [--no-open] # Браузерный чат
158
-
159
- # Флаги одноразового запуска
160
- bun run mma "<prompt>" --json # Машиночитаемый JSON-результат
161
- bun run mma "<prompt>" -d <dir> # Рабочая директория агента
162
- bun run mma "<prompt>" --no-agents-md # Не грузить AGENTS.md в системный промпт
163
- bun run mma "<prompt>" --exit-on-complete # Выйти после первого финального ответа
164
- bun run mma "<prompt>" --context-log # Записать контекст в <session>/context.diff
165
- bun run mma "<prompt>" --verbose # Подробный вывод (уровень verbosity)
153
+ bun run mma model list # Available models (✔ = certified)
154
+ bun run mma model use qwen3.5-9b # Switch model
155
+ bun run mma model certify <name> # Certify a model against the backend
156
+ bun run mma model cert-status <name> # Certification status
157
+ bun run mma model cert-list # All certifications
158
+ bun run mma model uncertify <name> # Revoke a certification
159
+ bun run mma provider list # List providers
160
+ bun run mma provider add local --url http://localhost:1234/v1 # Add a provider
161
+ bun run mma provider use opencode-zen # Hosted provider (zen / go)
162
+ bun run mma context # Context tokens/budget (--system/--reserve)
163
+ bun run mma map [summary|refresh|find] # Project map
164
+ bun run mma usage # Provider balance (OpenRouter /key, /credits)
165
+ bun run mma security status # Current security configuration
166
+ bun run mma security policies # Available policies (strict/balanced/permissive)
167
+ bun run mma security set-policy strict # Apply a policy
168
+ bun run mma plugins list # Loaded plugins (--all includes built-in)
169
+ bun run mma session list # List sessions
170
+ bun run mma session show <id> # Session details
171
+ bun run mma session export <id> # Export a session (--format md|json|jsonl, --out -)
172
+ bun run mma session delete <id> # Delete a session
173
+ bun run mma web [--port N] [--host H] [--token T] [--no-open] # Browser chat
174
+
175
+ # One-shot flags
176
+ bun run mma "<prompt>" --json # Machine-readable JSON result
177
+ bun run mma "<prompt>" -d <dir> # Agent working directory
178
+ bun run mma "<prompt>" --no-agents-md # Don't load AGENTS.md into the system prompt
179
+ bun run mma "<prompt>" --exit-on-complete # Exit after the first final answer
180
+ bun run mma "<prompt>" --context-log # Write context to <session>/context.diff
181
+ bun run mma "<prompt>" --verbose # Verbose output (verbosity level)
166
182
  bun run mma "<prompt>" --reasoning <auto|low|medium|high|max>
167
183
  ```
168
184
 
@@ -172,93 +188,93 @@ bun run mma "<prompt>" --reasoning <auto|low|medium|high|max>
172
188
  bun run dev
173
189
  ```
174
190
 
175
- | Команда | Алиасы | Описание |
176
- |---------|--------|----------|
177
- | `/help` | | Показать справку |
178
- | `/sessions` | `/ls` | Список сессий (* = активная) |
179
- | `/new <name>` | `/create` | Создать новую сессию |
180
- | `/resume <id\|name>` | `/switch`, `/use` | Переключиться на сессию |
181
- | `/rename <name>` | | Переименовать текущую сессию |
182
- | `/delete <id>` | `/rm` | Удалить сессию |
183
- | `/model [name]` | | Показать/сменить модель |
184
- | `/provider [list\|use <name>\|add …]` | | Провайдеры (список/переключить/добавить) |
185
- | `/status` | | Статус: модель, плагины, сессия, стоимость |
186
- | `/config [<ключ> [<значение>]]` | | Единый реестр настроек (`/config reset <key>`) |
187
- | `/context` | `/ctx` | Токены и бюджет контекста |
188
- | `/reasoning [show\|hide\|level <...>]` | | Показ reasoning / уровень (`auto`/`low`/…/`max`) |
189
- | `/verbose [quiet\|normal\|verbose]` | | Уровень детализации вывода |
190
- | `/memory [get\|set\|unset\|find\|forget]` | | Просмотр/правка памяти |
191
- | `/meet` | `/познакомимся` | Онбординг-интервью (пишет в глобальную память) |
192
- | `/map [summary\|refresh\|find]` | | Карта проекта |
193
- | `/export [md\|json\|jsonl]` | | Экспорт текущей сессии |
194
- | `/image <path\|url>` | | Прикрепить изображение (или Ctrl+V) |
195
- | `/run <cmd>` | | Выполнить shell-команду без агента |
196
- | `/sysprompt` | | Показать системный промпт |
197
- | `/wizard` | | Мастер настройки |
198
- | `/skill <name>` | | Загрузить скилл |
199
- | `/plugins` | | Плагины (`--all` — все) |
200
- | `/lsp [status\|restart\|check <path>]` | | Диагностика LSP |
201
- | `/reload` | | Перечитать конфиг и модули |
202
- | `/clear` | | Очистить экран (контекст сессии сохраняется) |
203
- | `/exit` | | Выйти из REPL |
204
-
205
- Горячие клавиши: `Esc Esc` — прервать агента; `Ctrl+C` — выход; `Ctrl+V` — вставить изображение из буфера обмена; `Shift+Enter` — перенос строки.
206
-
207
- ### Веб-режим (`mma web`)
208
-
209
- Тот же `bootstrap()` / `Agent` / сессии, но в браузере (SSE + REST, без TTY):
191
+ | Command | Aliases | Description |
192
+ |---------|---------|-------------|
193
+ | `/help` | | Show help |
194
+ | `/sessions` | `/ls` | List sessions (* = active) |
195
+ | `/new <name>` | `/create` | Create a new session |
196
+ | `/resume <id\|name>` | `/switch`, `/use` | Switch to a session |
197
+ | `/rename <name>` | | Rename the current session |
198
+ | `/delete <id>` | `/rm` | Delete a session |
199
+ | `/model [name]` | | Show/switch model |
200
+ | `/provider [list\|use <name>\|add …]` | | Providers (list/switch/add) |
201
+ | `/status` | | Status: model, plugins, session, cost |
202
+ | `/config [<key> [<value>]]` | | Unified settings registry (`/config reset <key>`) |
203
+ | `/context` | `/ctx` | Context tokens and budget |
204
+ | `/reasoning [show\|hide\|level <...>]` | | Reasoning display / level (`auto`/`low`/…/`max`) |
205
+ | `/verbose [quiet\|normal\|verbose]` | | Output verbosity level |
206
+ | `/memory [get\|set\|unset\|find\|forget]` | | View/edit memory |
207
+ | `/meet` | `/познакомимся` | Onboarding interview (writes to global memory) |
208
+ | `/map [summary\|refresh\|find]` | | Project map |
209
+ | `/export [md\|json\|jsonl]` | | Export the current session |
210
+ | `/image <path\|url>` | | Attach an image (or Ctrl+V) |
211
+ | `/run <cmd>` | | Run a shell command without the agent |
212
+ | `/sysprompt` | | Show the system prompt |
213
+ | `/wizard` | | Setup wizard |
214
+ | `/skill <name>` | | Load a skill |
215
+ | `/plugins` | | Plugins (`--all` for all) |
216
+ | `/lsp [status\|restart\|check <path>]` | | LSP diagnostics |
217
+ | `/reload` | | Reload config and modules |
218
+ | `/clear` | | Clear the screen (session context is preserved) |
219
+ | `/exit` | | Exit the REPL |
220
+
221
+ **Hotkeys:** `Esc Esc` — interrupt the agent; `Ctrl+C` — quit; `Ctrl+V` — paste an image from the clipboard; `Shift+Enter` — newline.
222
+
223
+ ### Web mode (`mma web`)
224
+
225
+ The same `bootstrap()` / `Agent` / sessions, but in the browser (SSE + REST, no TTY):
210
226
 
211
227
  ```bash
212
- bun run mma web # откроет браузер
228
+ bun run mma web # opens the browser
213
229
  bun run mma web --port 8080 --host 127.0.0.1 --no-open
214
230
  ```
215
231
 
216
- - **Первый запуск** с пустым конфигом: мастер прямо в браузере (язык → провайдер → ключ → модель → контекст → безопасность → проверка). Чат закрыт, пока настройка не завершена (сервер отвечает `409 setup_required`).
217
- - Панель настроек: модели/провайдеры, контекст, reasoning, память, скиллы, плагины/MCP, безопасность; slash-команды (`/help`, `/status`, `/config`, `/model`, `/provider`, `/memory`, …) работают и в браузере.
232
+ - **First run** with an empty config: the wizard opens right in the browser (language → provider → key → model → context → security → review). Chat stays locked until setup is complete (the server answers `409 setup_required`).
233
+ - Settings panel: models/providers, context, reasoning, memory, skills, plugins/MCP, security. Slash commands (`/help`, `/status`, `/config`, `/model`, `/provider`, `/memory`, …) work in the browser too.
218
234
  - Env: `MMA_WEBUI_PORT`, `MMA_WEBUI_HOST`, `MMA_WEBUI_TOKEN`, `MMA_WEBUI_OPEN=0`, `MMA_WEBUI_MAX_CLIENTS`.
219
235
 
220
- ### Разработка
236
+ ### Development
221
237
 
222
238
  ```bash
223
- bun run mma "почини страницу логина" # Запуск агента
224
- bun run dev # Watch-режим (авто-перезапуск при изменениях)
225
- bun run build:prod # Сборка для публикации (clean → bundle → frontend → assets → minify)
226
- bun test # Запуск тестов
227
- bun run typecheck # Проверка типов бэкенда (tsc --noEmit)
228
- bun run typecheck:frontend # Проверка типов фронтенда (tsconfig.frontend.json)
229
- bun run lint # Линтер Biome
230
- bun run quality # typecheck + frontend + lint + fallow (dead-code gate)
239
+ bun run mma "fix the login page" # Run the agent
240
+ bun run dev # Watch mode (auto-restart on changes)
241
+ bun run build:prod # Publish build (clean → bundle → frontend → assets → minify)
242
+ bun test # Run tests
243
+ bun run typecheck # Backend type check (tsc --noEmit)
244
+ bun run typecheck:frontend # Frontend type check (tsconfig.frontend.json)
245
+ bun run lint # Biome linter
246
+ bun run quality # typecheck + frontend + lint + fallow (dead-code gate)
231
247
  ```
232
248
 
233
- > Прод-сборка (`build:prod`) очищает `dist`, выносит зависимости из бандла
234
- > (`--packages external`) и минифицирует весь `dist` через esbuild. Пакет ~1.7 MB;
235
- > в рантайме ничего не докачивается — всё приходит с `npm install`.
249
+ > The production build (`build:prod`) cleans `dist`, externalizes dependencies
250
+ > (`--packages external`), and minifies everything via esbuild. The package is ~1.7 MB;
251
+ > nothing is downloaded at runtime — it all arrives with `npm install`.
236
252
 
237
253
  ---
238
254
 
239
- ## Конфигурация
240
-
241
- 3-слойный конфиг: `defaults.ts` → `~/.mma/config/*.json` (глобальные домены; legacy `~/.mma/config.json` мигрируется автоматически, с бэкапом) → `.mmrc` (проект) + переменные окружения `MMA_*`.
242
-
243
- Ключевые опции (полный список в `src/config/defaults.ts`, просмотр/правка — `/config` в REPL или `mma config show`):
244
-
245
- | Опция | По умолчанию | Описание |
246
- |-------|-------------|----------|
247
- | `model` | `qwen/qwen3.5-9b` | Имя модели для бэкенда |
248
- | `provider.baseUrl` | `http://localhost:1234/v1` | URL OpenAI-совместимого API (или `provider.entries[]` для failover) |
249
- | `contextWindow` | `32768` | Контекстное окно модели в токенах |
250
- | `contextBudget.systemPrompt` | `0.10` | Доля окна под системный промпт |
251
- | `contextBudget.responseReserve` | `0.15` | Резерв под ответ |
252
- | `autoPlan` | `true` | Авто-создание планов для многошаговых задач |
253
- | `reasoning.mode` | `auto` | `auto` (политика) или фиксированный `none`…`max` |
254
- | `reasoning.baseline` | `low` | Стартовый уровень в auto (растёт на сигналах) |
255
- | `maxToolIterations` | `1000` | Макс. вызовов инструментов за запуск |
256
- | `stuckThreshold` | `6` | Итераций без прогресса до stuck-detection |
257
- | `moe.enabled` | `false` | Включить Agent-Level MoE |
258
- | `security.enabled` | `true` | Модуль безопасности (balanced-политика по умолчанию) |
255
+ ## Configuration
256
+
257
+ A 3-layer config: `defaults.ts` → `~/.mma/config/*.json` (global domains; legacy `~/.mma/config.json` migrates automatically with a backup) → `.mmrc` (project) + `MMA_*` environment variables.
258
+
259
+ Key options (full list in `src/config/defaults.ts`; view/edit via `/config` in the REPL or `mma config show`):
260
+
261
+ | Option | Default | Description |
262
+ |--------|---------|-------------|
263
+ | `model` | `qwen/qwen3.5-9b` | Model name for the backend |
264
+ | `provider.baseUrl` | `http://localhost:1234/v1` | OpenAI-compatible API URL (or `provider.entries[]` for failover) |
265
+ | `contextWindow` | `32768` | Model context window in tokens |
266
+ | `contextBudget.systemPrompt` | `0.10` | Share of the window for the system prompt |
267
+ | `contextBudget.responseReserve` | `0.15` | Reserve for the response |
268
+ | `autoPlan` | `true` | Auto-create plans for multi-step tasks |
269
+ | `reasoning.mode` | `auto` | `auto` (policy) or fixed `none`…`max` |
270
+ | `reasoning.baseline` | `low` | Starting level in auto (grows on signals) |
271
+ | `maxToolIterations` | `1000` | Max tool calls per run |
272
+ | `stuckThreshold` | `6` | Iterations without progress before stuck detection |
273
+ | `moe.enabled` | `false` | Enable Agent-Level MoE |
274
+ | `security.enabled` | `true` | Security module (balanced policy by default) |
259
275
  | `ui.verbosity` | `normal` | `quiet` / `normal` / `verbose` |
260
- | `locale` | `en` | Язык интерфейса (`en` / `ru`) |
261
- | `logLevel` | `info` | Уровень логирования |
276
+ | `locale` | `en` | UI language (`en` / `ru`) |
277
+ | `logLevel` | `info` | Logging level |
262
278
 
263
279
  ### Agent-Level MoE
264
280
 
@@ -279,7 +295,7 @@ bun run quality # typecheck + frontend + lint + fallow (
279
295
 
280
296
  ---
281
297
 
282
- ## Архитектура
298
+ ## Architecture
283
299
 
284
300
  ```
285
301
  CLI (main.ts → commands.ts / repl.ts / setup.ts / web-command.ts)
@@ -293,124 +309,124 @@ CLI (main.ts → commands.ts / repl.ts / setup.ts / web-command.ts)
293
309
  → Output (OutputBus → OutputChannel single writer; JSON/SSE sinks)
294
310
  ```
295
311
 
296
- ### Структура проекта
312
+ ### Project structure
297
313
 
298
314
  ```
299
315
  src/
300
- ├── core/ # Цикл агента, bootstrap/системный промпт, WebHost, типы
301
- ├── llm/ # Абстракция провайдера, OpenAI-совместимость, стриминг, токены, кеш-метрики
302
- ├── tools/ # Ядро инструментов (~26) + реестр, исполнитель, скоуп-гарды
303
- ├── modules/ # 24 модуля (скиллы, плагины, mcp, пайплайны, indexer, память, контекст,
304
- │ # сессии, галлюцинации, выполнение, апдейтер, профиль, браузер, LSP,
305
- │ # безопасность, сертификация, артефакты, процессы, цены, онбординг,
306
- │ # провайдеры, reasoning, setup, webui)
316
+ ├── core/ # Agent loop, bootstrap/system prompt, WebHost, types
317
+ ├── llm/ # Provider abstraction, OpenAI compatibility, streaming, tokens, cache metrics
318
+ ├── tools/ # Tool core (~26) + registry, executor, scope guards
319
+ ├── modules/ # 24 modules (skills, plugins, mcp, pipelines, indexer, memory, context,
320
+ │ # sessions, hallucination, execution, updater, profile, browser, LSP,
321
+ │ # security, certification, artifacts, processes, pricing, onboarding,
322
+ │ # providers, reasoning, setup, webui)
307
323
  ├── output/ # Single-writer OutputChannel + OutputBus, JSON/SSE sinks
308
- ├── cli/ # Точка входа, команды, REPL, мастера (setup), `mma web`
309
- ├── config/ # 3-слойный конфиг: defaults → домены → проект
324
+ ├── cli/ # Entry point, commands, REPL, wizards (setup), `mma web`
325
+ ├── config/ # 3-layer config: defaults → domains → project
310
326
  ├── i18n/ # en.json + ru.json + t()
311
- ├── ui/ # Markdown→ANSI форматтер, renderer, line-editor
312
- └── logger/ # Структурированный логгер с уровнями и дочерними логгерами
327
+ ├── ui/ # Markdown→ANSI formatter, renderer, line-editor
328
+ └── logger/ # Structured logger with levels and child loggers
313
329
  ```
314
330
 
315
331
  ---
316
332
 
317
- ## Инструменты
318
-
319
- | Инструмент | Описание |
320
- |------------|----------|
321
- | `read_file` | Чтение файла с offset/limit |
322
- | `write_file` | Создание/перезапись с созданием директорий |
323
- | `edit_file` | Поиск-и-замена в существующих файлах |
324
- | `glob` | Поиск по glob-паттернам |
325
- | `grep` | Поиск по содержимому через ripgrep |
326
- | `list_dir` | Список содержимого директории |
327
- | `create_dir` | Создание директории (рекурсивно) |
328
- | `delete_file` | Удаление файла или пустой директории |
329
- | `move_file` | Перемещение/переименование файла или директории |
330
- | `file_info` | Метаданные файла/директории |
331
- | `bash` | Выполнение shell-команд |
332
- | `subagent` | Изолированный сабагент со скоупом |
333
- | `web_search` | Поиск в интернете |
334
- | `web_fetch` | Загрузка веб-страницы → markdown (~5K символов, 15s таймаут, SSRF-safe редиректы) |
335
- | `web_browse` | JS-less HTTP fetch страницы без движка (до 3K символов) |
336
- | `browser` | Браузер на Playwright (клик, ввод, скролл, скриншот) |
337
- | `plan` | Создание/обновление/отмена планов |
338
- | `todo` | Отслеживание задач |
339
- | `load_skill` | Загрузить скилл во время выполнения |
340
- | `pipeline_run` | Выполнить YAML-пайплайн |
341
- | `mcp_call` | Вызвать инструмент MCP-сервера |
342
- | `search_history` | Поиск по истории сессий |
343
- | `project_map` | Запрос карты проекта (summary, refresh, find) |
344
- | `chunk_query` | Параллельная обработка больших текстов чанками |
345
- | `download_file` | Скачать бинарный файл по URL на диск |
346
- | `process_list` / `process_log` / `process_kill` | Управление фоновыми процессами |
347
- | `remember` / `recall` | Постоянная память агента |
348
- | `attach_image` | Прикрепить изображение (файл/URL/буфер обмена; в контекст — при vision-модели) |
349
- | `enable_tools` | Включить скрытые группы инструментов на ходу |
350
- | `lsp_check` | Диагностика LSP (TypeScript/CSS/HTML) |
351
- | `verify` | Верификация шагов плана |
352
- | `session_info` | Сведения о текущей сессии (id, модель, контекст, сообщения) |
353
- | `set_thinking` | Сменить уровень reasoning для следующих итераций |
354
- | `scope_request` | Запросить расширение файлового скоупа сабагента |
355
- | `question` / `approve` | Интерактивные меню (регистрируются только в веб-режиме `mma web`) |
356
-
357
- > Примечание: в терминале интерактивные тулзы `question`/`approve` не регистрируются — модель задаёт вопросы текстом. В `mma web` они работают через SSE + `POST /api/answer`.
333
+ ## Tools
334
+
335
+ | Tool | Description |
336
+ |------|-------------|
337
+ | `read_file` | Read a file with offset/limit |
338
+ | `write_file` | Create/overwrite, creating directories as needed |
339
+ | `edit_file` | Find-and-replace in existing files |
340
+ | `glob` | Search by glob patterns |
341
+ | `grep` | Search file contents via ripgrep |
342
+ | `list_dir` | List directory contents |
343
+ | `create_dir` | Create a directory (recursively) |
344
+ | `delete_file` | Delete a file or empty directory |
345
+ | `move_file` | Move/rename a file or directory |
346
+ | `file_info` | File/directory metadata |
347
+ | `bash` | Run shell commands |
348
+ | `subagent` | Isolated, scoped subagent |
349
+ | `web_search` | Web search |
350
+ | `web_fetch` | Fetch a web page → markdown (~5K chars, 15s timeout, SSRF-safe redirects) |
351
+ | `web_browse` | JS-less HTTP page fetch without an engine (up to 3K chars) |
352
+ | `browser` | Playwright browser (click, type, scroll, screenshot) |
353
+ | `plan` | Create/update/cancel plans |
354
+ | `todo` | Task tracking |
355
+ | `load_skill` | Load a skill at runtime |
356
+ | `pipeline_run` | Run a YAML pipeline |
357
+ | `mcp_call` | Call an MCP server tool |
358
+ | `search_history` | Search session history |
359
+ | `project_map` | Query the project map (summary, refresh, find) |
360
+ | `chunk_query` | Process large texts in parallel chunks |
361
+ | `download_file` | Download a binary file by URL to disk |
362
+ | `process_list` / `process_log` / `process_kill` | Manage background processes |
363
+ | `remember` / `recall` | Persistent agent memory |
364
+ | `attach_image` | Attach an image (file/URL/clipboard; added to context with a vision model) |
365
+ | `enable_tools` | Enable hidden tool groups on the fly |
366
+ | `lsp_check` | LSP diagnostics (TypeScript/CSS/HTML) |
367
+ | `verify` | Verify plan steps |
368
+ | `session_info` | Current session info (id, model, context, messages) |
369
+ | `set_thinking` | Change the reasoning level for upcoming iterations |
370
+ | `scope_request` | Request a subagent file-scope extension |
371
+ | `question` / `approve` | Interactive menus (registered only in web mode `mma web`) |
372
+
373
+ > Note: in the terminal, the interactive tools `question`/`approve` are not registered — the model asks questions as plain text. In `mma web` they work via SSE + `POST /api/answer`.
358
374
 
359
375
  ---
360
376
 
361
- ## Тестирование
377
+ ## Testing
362
378
 
363
379
  ```bash
364
- bun test # Модульные + компонентные тесты
365
- bun test tests/agent.test.ts # Один файл
366
- bun run test:integration # Интеграционные тесты (требуют LLM-бэкенд)
367
- bun run typecheck # Проверка типов
380
+ bun test # Unit + component tests
381
+ bun test tests/agent.test.ts # A single file
382
+ bun run test:integration # Integration tests (need an LLM backend)
383
+ bun run typecheck # Type check
368
384
  ```
369
385
 
370
- ### Тестирование агента из консоли (agent-driven)
386
+ ### Agent-driven testing from the console
371
387
 
372
- MMA можно тестировать в одноразовом headless-режиме без интерактивного REPL — это удобно для проверки фич и регрессий из терминала или другим агентом:
388
+ MMA can run headless in one-shot mode without the interactive REPL — handy for checking features and regressions from a terminal or another agent:
373
389
 
374
390
  ```bash
375
- # Одноразовый прогон: без AGENTS.md, выход сразу после ответа, песочница
376
- bun run mma "<промпт>" --no-agents-md --exit-on-complete -d <путь-к-песочнице>
391
+ # One-shot: no AGENTS.md, exit right after the answer, sandboxed
392
+ bun run mma "<prompt>" --no-agents-md --exit-on-complete -d <sandbox-path>
377
393
  ```
378
394
 
379
- - **Песочница** — всегда внутри `_testing/` в корне проекта (например `_testing/<case-name>/`), никогда в корне или в `src/`. Папка `_testing/` добавлена в `.gitignore`.
380
- - **`--no-agents-md`** — не грузить AGENTS.md проекта в системный промпт (чистая среда).
381
- - **`--exit-on-complete`** — выйти сразу после первого финального ответа; интерактивные тулзы (`question`/`approve`) не блокируют stdin, а возвращают ошибку.
382
- - **`-d <dir>`** — рабочая директория агента (туда он создаёт файлы).
383
- - Каждый прогон сохраняется в сессию `~/.mma/sessions/<id>/` — можно посмотреть через `bun run mma session list` / `session show <id>`.
395
+ - **Sandbox** — always inside `_testing/` at the project root (e.g. `_testing/<case-name>/`), never at the root or in `src/`. The `_testing/` folder is in `.gitignore`.
396
+ - **`--no-agents-md`** — don't load the project's AGENTS.md into the system prompt (clean environment).
397
+ - **`--exit-on-complete`** — exit right after the first final answer; interactive tools (`question`/`approve`) don't block stdin but return an error.
398
+ - **`-d <dir>`** — the agent's working directory (where it creates files).
399
+ - Every run is saved to the session `~/.mma/sessions/<id>/` — inspect it via `bun run mma session list` / `session show <id>`.
384
400
 
385
401
  ---
386
402
 
387
- ## Принципы дизайна
403
+ ## Design Principles
388
404
 
389
- 1. **Ни одного файла >300 строк** — разделяй при приближении к лимиту
390
- 2. **Маленькие файлы, одна ответственность** — каждый файл делает одно дело
391
- 3. **KISS state machine** — никаких god-объектов, никакой вложенности if-else в цикле агента
392
- 4. **Изоляция ошибок плагинов** — падение одного плагина не останавливает другие
393
- 5. **Безопасность путей** — файловые инструменты резолвят `realpath` (защита от symlink/junction вне `baseDir`) и блокируют always-on защищённые пути (`.git/`, `.env*`, ключи)
394
- 6. **Single-writer вывод** — всё через `OutputChannel`; прямой stdout только в CLI и машинном JSON
395
- 7. **TDD** — сначала тест, потом реализация, потом коммит
396
- 8. **Никаких захардкоженных строк** — весь текст через `t()` i18n
397
- 9. **Никакого keyword matching** — LLM решает когда планировать, не эвристики
398
- 10. **Без TUI** — минимальный CLI + REPL с markdown→ANSI
405
+ 1. **No file over 300 lines** — split as you approach the limit
406
+ 2. **Small files, one responsibility** — each file does one thing
407
+ 3. **KISS state machine** — no god objects, no nested if-else inside the agent loop
408
+ 4. **Plugin error isolation** — one plugin crashing doesn't stop the others
409
+ 5. **Path safety** — file tools resolve `realpath` (symlink/junction protection outside `baseDir`) and block always-on protected paths (`.git/`, `.env*`, keys)
410
+ 6. **Single-writer output** — everything through `OutputChannel`; direct stdout only in the CLI and machine JSON
411
+ 7. **TDD** — test first, then implementation, then commit
412
+ 8. **No hardcoded strings** — all text through `t()` i18n
413
+ 9. **No keyword matching** — the LLM decides when to plan, not heuristics
414
+ 10. **No TUI** — a minimal CLI + REPL with markdown→ANSI
399
415
 
400
416
  ---
401
417
 
402
- ## Лицензия
418
+ ## License
403
419
 
404
420
  MIT
405
421
 
406
422
  ---
407
423
 
408
- ## Благодарности
424
+ ## Acknowledgements
409
425
 
410
- - [Qwen3.5-9B](https://qwen.readthedocs.io/) — основная целевая модель
411
- - [LM Studio](https://lmstudio.ai/) — рекомендуемый локальный инференс-сервер
412
- - [llama.cpp](https://github.com/ggerganov/llama.cpp) — инференс-движок
426
+ - [Qwen3.5-9B](https://qwen.readthedocs.io/) — the primary target model
427
+ - [LM Studio](https://lmstudio.ai/) — the recommended local inference server
428
+ - [llama.cpp](https://github.com/ggerganov/llama.cpp) — the inference engine
413
429
 
414
430
  ---
415
431
 
416
- **Сделано для локальных моделей. Работает везде.**
432
+ **Built for local models. Runs anywhere.**