miii-agent 0.1.7 → 0.1.9

package/README.md

@@ -1,5 +1,7 @@
 # miii
 
+> small · simple · smart · strategic · semantic
+>
 > Your code never leaves your machine. No API keys. No cloud. No bullshit.
 
 **miii** is a local-first AI coding agent that lives in your terminal. Powered by [Ollama](https://ollama.com), it reads your code, writes features, runs tests, and fixes bugs — entirely on your hardware, at native speed.
@@ -10,6 +12,18 @@
 
 ---
 
+## The name
+
+**miii** stands for five principles it's built around:
+
+- **small** — tight codebase, no bloat. You can read the whole thing.
+- **simple** — no API keys, no accounts, no config ceremony. Just run it.
+- **smart** — decomposes problems and verifies its own work like an engineer.
+- **strategic** — plans before it acts; tools are gated, paths are confined.
+- **semantic** — works from the meaning of your code, not blind text matching.
+
+---
+
 ## Demo
 
 ![miii demo](demo.gif)
@@ -115,7 +129,35 @@ miii ships with a built-in tool suite the agent can invoke autonomously:
 | `grep` | Regex search across files |
 | `run_bash` | Execute shell commands |
 
-Every sensitive operation is gated by a permission system — you approve what the agent can touch.
+Every sensitive operation is gated by a permission system — you approve what the agent can touch, and "always" approvals persist to `~/.miii/permissions.json` so you're never asked twice. File tools are confined to your working directory; `../` traversal and absolute paths outside it are rejected.
+
+---
+
+## Checking your setup
+
+miii is model-agnostic — but not every local model can actually drive an agent. A model that can't emit clean tool calls will chat at you instead of editing files. `miii doctor` tells you which of *your* installed models are up to the job, before you waste time wondering why nothing happens.
+
+```bash
+miii doctor                     # check every local model (from `ollama list`)
+miii doctor qwen2.5-coder:7b    # check one model
+miii doctor gemma4:e4b grep     # one model, only scenarios matching "grep"
+```
+
+It runs the real agent against a handful of concrete tasks (edit a file, read-and-answer, create a file, locate a definition) and checks the *outcome* — did the file actually change, was the answer right — then prints a verdict per model:
+
+```
+=== qwen3-coder ===
+PASS  edit-exact-string   ...
+PASS  read-then-answer    ...
+PASS  create-new-file     ...
+PASS  grep-locate         ...
+  → qwen3-coder: 4/4 — ready
+
+=== gemma4:e4b ===
+  → gemma4:e4b: 1/4 — not recommended — weak tool-calling
+```
+
+With more than one model it also prints a compatibility matrix (`+` pass, `.` fail). Cloud models are skipped by default; name one explicitly to include it. If a model comes back `marginal` or `not recommended`, pull a stronger coding model and try again.
 
 ---
 
@@ -137,8 +179,9 @@ graph TD
 
     subgraph Agent ["Agent Layer"]
         AgentLoop -->|"chat request"| Adapter["Ollama Adapter\n(agent/adapter.ts)"]
-        AgentLoop -->|"tool call"| ToolRegistry["Tool Registry\n(tools/registry.ts)"]
-        AgentLoop -->|"permission check"| Policy["Permission Policy\n(permissions/policy.ts)"]
+        AgentLoop -->|"1. validate input"| Validate["Input Validator\n(tools/validate.ts)"]
+        AgentLoop -->|"2. permission check"| Policy["Permission Policy\n(permissions/policy.ts)"]
+        AgentLoop -->|"3. tool call"| ToolRegistry["Tool Registry\n(tools/registry.ts)"]
         AgentLoop -->|"events"| EventBus["Event Bus\n(hooks/bus.ts)"]
     end
 
@@ -149,6 +192,9 @@ graph TD
         ToolRegistry --> Glob["glob"]
         ToolRegistry --> Grep["grep"]
         ToolRegistry --> RunBash["run_bash"]
+        ReadFile -.-> Confine["Path Confinement\n(tools/paths.ts)"]
+        WriteFile -.-> Confine
+        EditFile -.-> Confine
     end
 
     Adapter -->|"HTTP streaming"| Ollama["Ollama\n(local LLM server)"]
@@ -159,9 +205,11 @@ graph TD
 
     subgraph Storage ["Local Storage"]
         Config["~/.miii/config.json\n(model, host, effort)"]
+        Rules["~/.miii/permissions.json\n(saved allow rules)"]
     end
 
     App -.->|"reads"| Config
+    Policy -.->|"reads / persists 'always'"| Rules
 ```
 
 ---
@@ -176,11 +224,25 @@ npm run dev
 ```
 
 ```bash
-npm run build   # production build
-npm run start   # run built output
+npm run build       # production build
+npm run start       # run built output
+npm run typecheck   # type-check src + eval
+npm run eval        # run the eval harness as a CI / regression gate
 ```
 
----
+The eval harness lives in `eval/` and powers `miii doctor`. As `npm run eval` it doubles as a regression gate — it exits non-zero if any model fails any scenario, so a prompt or tool change that regresses a baseline model is caught in CI. Same engine, two doors: `miii doctor` for users checking their setup, `npm run eval` for maintainers gating changes.
+
+### Testing the `miii` command against your local changes
+
+The global `miii` command points at whatever was last installed with `npm install -g miii-agent` — **not** your working tree. After editing source, the global binary is stale, so `miii` (and `miii doctor`) will run the old code and may appear to ignore your changes (e.g. printing the wrong model). Two ways to run your local build:
+
+```bash
+node dist/cli.js doctor <model>   # run the freshly built output directly
+# — or —
+npm run build && npm link         # point the global `miii` at this repo
+```
+
+`npm link` symlinks the global `miii` to `dist/cli.js` in this repo, so each `npm run build` is picked up automatically. Restore the published version later with `npm install -g miii-agent`. Note: `npm run dev` / `npm run start` always run the current source and never have this staleness problem.
 
 ## Project Status