micro-models-agent 2.18.0 → 2.18.1
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.
- package/CHANGELOG.md +6 -0
- package/README.md +262 -246
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,12 @@ All notable changes to Micro Models Agent (MMA) will be documented in this file.
|
|
|
4
4
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
|
|
6
6
|
|
|
7
|
+
## [2.18.1] - 2026-10-04
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- **README rewritten in English** (`README.md`): fully translated from Russian, reorganized into scannable themes (agent loop / orchestration / tools / experience / safety), and given a sharper intro and feature framing. Content — commands, config, tools, architecture, testing, principles — preserved. Documentation only, no behavior change.
|
|
12
|
+
|
|
7
13
|
## [2.18.0] - 2026-10-04
|
|
8
14
|
|
|
9
15
|
### Added
|
package/README.md
CHANGED
|
@@ -3,83 +3,99 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/micro-models-agent)
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
|
|
6
|
-
**
|
|
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 "
|
|
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
|
-
|
|
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
|
-
##
|
|
20
|
+
## Why MMA?
|
|
19
21
|
|
|
20
|
-
|
|
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
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
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
|
-
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
- **
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
- **
|
|
42
|
-
-
|
|
43
|
-
- **
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
- **
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
- **
|
|
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
|
-
-
|
|
63
|
-
- **LLM
|
|
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
|
-
###
|
|
81
|
+
### From npm (recommended)
|
|
66
82
|
|
|
67
83
|
```bash
|
|
68
84
|
npm install -g micro-models-agent@latest
|
|
69
85
|
```
|
|
70
86
|
|
|
71
|
-
|
|
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.
|
|
111
|
+
### 1. Start an LLM backend
|
|
96
112
|
|
|
97
|
-
|
|
113
|
+
Point MMA at any OpenAI-compatible endpoint. With LM Studio:
|
|
98
114
|
|
|
99
115
|
```bash
|
|
100
|
-
# LM Studio
|
|
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
|
-
|
|
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 "
|
|
130
|
+
# One-shot
|
|
131
|
+
bun run mma "build an Express REST API and add tests"
|
|
116
132
|
|
|
117
|
-
#
|
|
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 #
|
|
133
|
-
bun run mma meet #
|
|
134
|
-
bun run mma agents init #
|
|
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 #
|
|
146
|
-
bun run mma context #
|
|
147
|
-
bun run mma map [summary|refresh|find] #
|
|
148
|
-
bun run mma usage #
|
|
149
|
-
bun run mma security status #
|
|
150
|
-
bun run mma security policies #
|
|
151
|
-
bun run mma security set-policy strict #
|
|
152
|
-
bun run mma plugins list #
|
|
153
|
-
bun run mma session list #
|
|
154
|
-
bun run mma session show <id> #
|
|
155
|
-
bun run mma session export <id> #
|
|
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 #
|
|
161
|
-
bun run mma "<prompt>" -d <dir> #
|
|
162
|
-
bun run mma "<prompt>" --no-agents-md #
|
|
163
|
-
bun run mma "<prompt>" --exit-on-complete #
|
|
164
|
-
bun run mma "<prompt>" --context-log #
|
|
165
|
-
bun run mma "<prompt>" --verbose #
|
|
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 [
|
|
187
|
-
| `/context` | `/ctx` |
|
|
188
|
-
| `/reasoning [show\|hide\|level <...>]` | |
|
|
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>` | |
|
|
195
|
-
| `/run <cmd>` | |
|
|
196
|
-
| `/sysprompt` | |
|
|
197
|
-
| `/wizard` | |
|
|
198
|
-
| `/skill <name>` | |
|
|
199
|
-
| `/plugins` | |
|
|
200
|
-
| `/lsp [status\|restart\|check <path>]` | |
|
|
201
|
-
| `/reload` | |
|
|
202
|
-
| `/clear` | |
|
|
203
|
-
| `/exit` | |
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
###
|
|
208
|
-
|
|
209
|
-
|
|
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
|
-
-
|
|
217
|
-
-
|
|
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
|
|
225
|
-
bun run build:prod
|
|
226
|
-
bun test
|
|
227
|
-
bun run typecheck
|
|
228
|
-
bun run typecheck:frontend
|
|
229
|
-
bun run lint
|
|
230
|
-
bun run quality
|
|
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
|
-
>
|
|
234
|
-
> (`--packages external`)
|
|
235
|
-
>
|
|
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
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
|
246
|
-
|
|
247
|
-
| `model` | `qwen/qwen3.5-9b` |
|
|
248
|
-
| `provider.baseUrl` | `http://localhost:1234/v1` |
|
|
249
|
-
| `contextWindow` | `32768` |
|
|
250
|
-
| `contextBudget.systemPrompt` | `0.10` |
|
|
251
|
-
| `contextBudget.responseReserve` | `0.15` |
|
|
252
|
-
| `autoPlan` | `true` |
|
|
253
|
-
| `reasoning.mode` | `auto` | `auto` (
|
|
254
|
-
| `reasoning.baseline` | `low` |
|
|
255
|
-
| `maxToolIterations` | `1000` |
|
|
256
|
-
| `stuckThreshold` | `6` |
|
|
257
|
-
| `moe.enabled` | `false` |
|
|
258
|
-
| `security.enabled` | `true` |
|
|
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` |
|
|
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/ #
|
|
301
|
-
├── llm/ #
|
|
302
|
-
├── tools/ #
|
|
303
|
-
├── modules/ # 24
|
|
304
|
-
│ #
|
|
305
|
-
│ #
|
|
306
|
-
│ #
|
|
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/ #
|
|
309
|
-
├── config/ # 3
|
|
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
|
|
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` |
|
|
322
|
-
| `write_file` |
|
|
323
|
-
| `edit_file` |
|
|
324
|
-
| `glob` |
|
|
325
|
-
| `grep` |
|
|
326
|
-
| `list_dir` |
|
|
327
|
-
| `create_dir` |
|
|
328
|
-
| `delete_file` |
|
|
329
|
-
| `move_file` |
|
|
330
|
-
| `file_info` |
|
|
331
|
-
| `bash` |
|
|
332
|
-
| `subagent` |
|
|
333
|
-
| `web_search` |
|
|
334
|
-
| `web_fetch` |
|
|
335
|
-
| `web_browse` | JS-less HTTP fetch
|
|
336
|
-
| `browser` |
|
|
337
|
-
| `plan` |
|
|
338
|
-
| `todo` |
|
|
339
|
-
| `load_skill` |
|
|
340
|
-
| `pipeline_run` |
|
|
341
|
-
| `mcp_call` |
|
|
342
|
-
| `search_history` |
|
|
343
|
-
| `project_map` |
|
|
344
|
-
| `chunk_query` |
|
|
345
|
-
| `download_file` |
|
|
346
|
-
| `process_list` / `process_log` / `process_kill` |
|
|
347
|
-
| `remember` / `recall` |
|
|
348
|
-
| `attach_image` |
|
|
349
|
-
| `enable_tools` |
|
|
350
|
-
| `lsp_check` |
|
|
351
|
-
| `verify` |
|
|
352
|
-
| `session_info` |
|
|
353
|
-
| `set_thinking` |
|
|
354
|
-
| `scope_request` |
|
|
355
|
-
| `question` / `approve` |
|
|
356
|
-
|
|
357
|
-
>
|
|
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 #
|
|
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
|
-
###
|
|
386
|
+
### Agent-driven testing from the console
|
|
371
387
|
|
|
372
|
-
MMA
|
|
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
|
-
#
|
|
376
|
-
bun run mma "
|
|
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
|
-
-
|
|
380
|
-
- **`--no-agents-md`** —
|
|
381
|
-
- **`--exit-on-complete`** —
|
|
382
|
-
- **`-d <dir>`** —
|
|
383
|
-
-
|
|
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.
|
|
390
|
-
2.
|
|
391
|
-
3. **KISS state machine** —
|
|
392
|
-
4.
|
|
393
|
-
5.
|
|
394
|
-
6. **Single-writer
|
|
395
|
-
7. **TDD** —
|
|
396
|
-
8.
|
|
397
|
-
9.
|
|
398
|
-
10.
|
|
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.**
|