@@ -1,27 +1,63 @@
11 # mini-coding-agent (`mini` for short)
22
3-A fast, transparent, config-first terminal coding agent for one user at a time.
3+A fast, transparent, config-first terminal coding agent.
44
55 The source code is the source of truth for behavior. If a fact can be learned
66 by reading the code, it does not belong here; keep this file short.
77
8+## Guardrails
9+
10+- No sandbox or permission layer. Tools run with the user's permissions;
11+ isolation is an environment concern (`nono`), not the agent's.
12+- No loop limits. No max turns, tool calls, token budgets, or agent-imposed
13+ timeouts. The user's ability to interrupt is the limit.
14+- Config-first. Every user-facing behavior that can vary comes from config with
15+ a sane default. Global config only — no project-local config, no
16+ config-override flags — and never duplicate `pi-ai`'s catalog or env vars.
17+- Minimal context. The model sees the configured system prompt plus explicitly
18+ opted-in resource files — never reminders, hidden blocks, or harness
19+ meta-text.
20+- Never invent a parallel model. Consume `pi-ai`'s `Message` and stream types
21+ directly.
22+- The agent never imports the TUI. Headless and TUI are two projections of the
23+ same agent events; the TUI owns no agent or provider semantics.
24+- Sessions are append-only JSONL, one message per line, fsynced on write. Never
25+ rewrite or delete committed lines. A persistence failure stops the turn.
26+- The loop has no compaction, no retries, and no meta-messages between steps.
27+ Provider errors surface as-is, never masked or summarized.
28+- `edit`, `read`, and `bash` only. Tool arguments are untrusted and validated
29+ once at the boundary. `read` returns image blocks only for models that declare
30+ image input.
31+- Interruption: ESC politely pauses at the next step boundary; Ctrl+C cancels
32+ the turn (abort the request, kill the tool's process group, persist the
33+ aborted message); Ctrl+D exits on an empty draft. Completed side effects are
34+ never undone.
35+- Trace the real data flow before designing; apply guards at the narrowest
36+ boundary.
37+- Validate untrusted input once at the boundary, then keep internal code
38+ plain-typed.
39+- Ask before adding a dependency.
40+- Do not add tests unless explicitly asked; verify manually.
41+- Before finishing, review the diff against the guardrails, remove anything that
42+ added scope, and report any requirement you could not satisfy.
43+
844 ## Verification
945
10-**Do not stand up mock servers, fixture
11-endpoints, replay files, or mock terminals**; they prove nothing.
46+**Do not stand up mock servers, fixture endpoints, replay files, or mock
47+terminals**; they prove nothing.
1248
1349 Use a real bash call for headless runs, and the `tools/stress.sh` script for TUI
1450 runs.
1551
1652 ### Provider
1753
18-Verify against the real provider. Use the `OPENCODE_API_KEY` environment
54+Verify against the real provider. Use the `OPENCODE_API_KEY` environment
1955 variable and a scratch `XDG_CONFIG_HOME` with a `mini-coding-agent/config.json`
2056 that declares the provider under test.
2157
2258 Use these models:
2359
24-- `openai-completions` -> `opnecode-go/deepseek-v4.1-flash`
60+- `openai-completions` -> `opencode-go/deepseek-v4.1-flash`
2561 - `openai-responses` -> `opencode-go/gpt-6-luna`
2662 - `anthropic-messages` -> `opencode-go/minimax-m3`
2763 - `google-generative-ai` -> `opencode/gemini-3.8-flash`