xonecas.io
79113
Ma

mini-coding-agent / commit c2abd82

chore: docs cleanup and remove slopscripts

xonecas2026-10-08 c2abd828c2bb3c7e66d4f4858cd7246893c1c6a4 parent b7215a5

4 files changed

AGENTS.md+7−8
@@ -1,12 +1,14 @@
11 # mini-coding-agent (`mini` for short)
22
3-A fast, transparent, config-first terminal coding agent.
3+A fast, transparent, config-first terminal coding agent written in Zig.
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
88 ## Guardrails
99
10+- Minimalist by design.
11+- Lightweight! Single binary, fast to boot and low memory usage.
1012 - No sandbox or permission layer. Tools run with the user's permissions;
1113 isolation is an environment concern (`nono`), not the agent's.
1214 - No loop limits. No max turns, tool calls, token budgets, or agent-imposed
@@ -17,8 +19,6 @@ by reading the code, it does not belong here; keep this file short.
1719 - Minimal context. The model sees the configured system prompt plus explicitly
1820 opted-in resource files — never reminders, hidden blocks, or harness
1921 meta-text.
20-- Never invent a parallel model. Consume `pi-ai`'s `Message` and stream types
21- directly.
2222 - The agent never imports the TUI. Headless and TUI are two projections of the
2323 same agent events; the TUI owns no agent or provider semantics.
2424 - Sessions are append-only JSONL, one message per line, fsynced on write. Never
@@ -38,12 +38,11 @@ by reading the code, it does not belong here; keep this file short.
3838 plain-typed.
3939 - Ask before adding a dependency.
4040 - 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.
41+- We are the maintainers of this codebase, treat it with care and attention to detail.
4342
4443 ## Verification
4544
46-**Do not stand up mock servers, fixture endpoints, replay files, or mock
45+**Do not stand up mock servers, fixture endpoints, replay files, throwaway scripts, or mock
4746 terminals**; they prove nothing.
4847
4948 Use a real bash call for headless runs, and the `tools/stress.sh` script for TUI
@@ -52,8 +51,7 @@ runs.
5251 ### Provider
5352
5453 Verify against the real provider. Use the `OPENCODE_API_KEY` environment
55-variable and a scratch `XDG_CONFIG_HOME` with a `mini-coding-agent/config.json`
56-that declares the provider under test.
54+variable and a `config.json` that declares the provider under test.
5755
5856 Use these models:
5957
@@ -76,3 +74,4 @@ its truecolor SGR to `final.txt` (scrollback) and `final-screen.txt` (live
7674 screen). The last line reports frames, wall time, and achieved fps; an
7775 `ended early: MINI-EXIT <n>` line means the app died, and `final.txt` holds the
7876 dump.
77+Make sure to review both images and text, so you can inspect the TUI themeing.
README.md+6−2
@@ -12,7 +12,9 @@ Requires Zig 0.16.0.
1212
1313 zig build
1414
15-The binary lands at `zig-out/bin/mini`.
15+The binary lands at `zig-out/bin/mini`. `zig build run -- <args>` builds and
16+runs it. Provider model metadata is embedded from `src/models_dev.json`; refresh
17+it with `python3 tools/gen_models_dev.py`.
1618
1719 ## Run
1820
@@ -28,7 +30,8 @@ Arguments:
2830 | `-c`, `--config` | read a config file after the global one; its keys win |
2931
3032 `-p` requires a model in the config. Without one it exits 1 and prints where
31-the config lives. Interactive mode requires a TTY.
33+the config lives. Interactive mode requires a TTY. In `-p` mode tool calls and
34+tool output go to stderr, the assistant text to stdout; a failed turn exits 1.
3235
3336 ## TUI commands
3437
@@ -95,6 +98,7 @@ A full example:
9598 "models": [
9699 {
97100 "id": "qwen3-coder",
101+ "name": "Qwen3 Coder",
98102 "api": "openai-completions",
99103 "baseUrl": "http://127.0.0.1:11434/v1",
100104 "context": 32768,
tools/qa-matrix.sh+0−94
@@ -1,94 +0,0 @@
1-#!/usr/bin/env bash
2-#
3-# qa-matrix.sh - run the QA scenarios from tools/qa.sh against every provider
4-# listed in AGENTS.md and print a pass/fail summary per scenario.
5-#
6-# tools/qa-matrix.sh [-o root] [-C cwd] [-d max-seconds] [-p provider]...
7-#
8-# Each provider needs a scratch XDG_CONFIG_HOME at <root>/configs/<provider>
9-# holding mini-coding-agent/config.json, and each scenario gets <root>/runs/
10-# <provider>/<scenario>. Only the providers named with -p are run; with none,
11-# all four from AGENTS.md are.
12-
13-set -euo pipefail
14-
15-here=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
16-root=/tmp/mini-qa
17-cwd=$PWD
18-maxd=90
19-providers=()
20-
21-usage() {
22- cat <<'EOF'
23-usage: qa-matrix.sh [options]
24- -o root where configs and runs live (default /tmp/mini-qa)
25- -C cwd working directory mini runs in (default $PWD)
26- -d seconds capture cap per scenario (default 90)
27- -p name provider to run (repeatable); default all of AGENTS.md
28-EOF
29-}
30-
31-while getopts 'o:C:d:p:h' opt; do
32- case $opt in
33- o) root=$OPTARG ;;
34- C) cwd=$OPTARG ;;
35- d) maxd=$OPTARG ;;
36- p) providers+=("$OPTARG") ;;
37- h) usage; exit 0 ;;
38- *) usage; exit 2 ;;
39- esac
40-done
41-if (( ${#providers[@]} == 0 )); then
42- providers=(completions responses anthropic google)
43-fi
44-root=$(readlink -f -- "$root")
45-cwd=$(cd -- "$cwd" && pwd)
46-
47-run() {
48- local provider=$1 scenario=$2 duration=$3 spec=$4
49- local out=$root/runs/$provider/$scenario
50- rm -rf -- "$out"
51- mkdir -p -- "$out"
52- echo "== $provider / $scenario =="
53- "$here/qa.sh" -C "$cwd" -o "$out" -e "$root/configs/$provider" \
54- -n "qa-$provider-$scenario" -d "$duration" -s "$spec" > "$out/run.log" 2>&1 || true
55- tail -n 3 "$out/run.log" | sed 's/^/ /'
56-}
57-
58-# A flag is "the app died" when the pane reports MINI-EXIT with a nonzero code,
59-# or the app never reached an idle prompt after the scenario's final step.
60-check() {
61- local provider=$1 scenario=$2 expect=$3
62- local out=$root/runs/$provider/$scenario
63- local final=$out/final.txt
64- local verdict="ok"
65- if grep -q 'MINI-EXIT' "$final" && ! grep -q 'MINI-EXIT 0' "$final"; then
66- verdict="CRASH"
67- elif ! grep -q '\[complete' "$final"; then
68- verdict="NO-TURN"
69- elif ! grep -qiE "$expect" "$final"; then
70- verdict="MISSING:$expect"
71- fi
72- printf '%-11s %-10s %s\n' "$provider" "$scenario" "$verdict"
73-}
74-
75-dur() {
76- local want=$1
77- if (( want > maxd )); then echo "$maxd"; else echo "$want"; fi
78-}
79-
80-for p in "${providers[@]}"; do
81- run "$p" single "$(dur 40)" 'text=Read a.txt and tell me its contents in one short sentence;;key=enter;;wait=30;;shot=done'
82- run "$p" multi "$(dur 55)" 'text=Read a.txt and b.txt, then tell me both contents;;key=enter;;wait=45;;shot=done'
83- run "$p" cancel "$(dur 45)" 'text=Run this exact bash command: sleep 30; echo done;;key=enter;;wait=6;;shot=running;;key=ctrl+c;;wait=5;;shot=cancelled;;text=Say hi in one word;;key=enter;;wait=20;;shot=recovered'
84- run "$p" pause "$(dur 55)" 'text=Run this exact bash command: sleep 12; echo HELLO. Then run: sleep 12; echo WORLD. Then say ALL DONE;;key=enter;;wait=4;;shot=running;;key=esc;;wait=13;;shot=paused;;text=Stop, just say STEERED;;key=enter;;wait=25;;shot=steered'
85-done
86-
87-echo
88-echo "summary (expect = text that must appear in final.txt, else MISSING):"
89-for p in "${providers[@]}"; do
90- check "$p" single 'hello world'
91- check "$p" multi 'foo bar'
92- check "$p" cancel 'cancelled'
93- check "$p" pause 'STEERED'
94-done
tools/qa.sh+0−225
@@ -1,225 +0,0 @@
1-#!/usr/bin/env bash
2-#
3-# qa.sh - drive the real TUI in a real kitty window through a timed script of
4-# keystrokes and prompts, screenshotting throughout. stress.sh types one prompt
5-# and watches; this fires submissions, cancellations and pauses at chosen times
6-# so turn control paths can be exercised on a repeatable run.
7-#
8-# tools/qa.sh -C <cwd> -o <outdir> -e <xdg config home> -s <spec> [-s <spec>...]
9-#
10-# A spec is a sequence of steps separated by ``;;``:
11-#
12-# wait=<seconds> pause before the next step
13-# text=<string> type the string into the editor (may contain commas)
14-# key=<name> press a key: enter, shift+enter, ctrl+c, esc, tab, ctrl+d
15-# shot=<label> write the pane text to <outdir>/mark-<n>-<label>.txt
16-#
17-# The first step runs once the banner is up. Every action is logged to
18-# <outdir>/steps.txt with its wall time. Frames land in <outdir>/frame-NNNNN.png
19-# and the final pane in final.txt / final-screen.txt.
20-
21-set -euo pipefail
22-
23-fps=15
24-seconds=180
25-name="qa-$$"
26-here=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
27-bin=$here/../zig-out/bin/mini
28-cwd=$PWD
29-out=
30-xdg=
31-specs=()
32-
33-usage() {
34- cat <<'EOF'
35-usage: qa.sh [options]
36- -d seconds how long to capture at most (default 180)
37- -r fps capture rate (default 15)
38- -o outdir where frames go (required)
39- -C cwd working directory mini runs in (default $PWD)
40- -e path XDG_CONFIG_HOME holding mini-coding-agent/config.json
41- -b path mini binary (default ../zig-out/bin/mini)
42- -n name kitty session name (default qa-$$)
43- -s spec a step list (repeatable), see the header comment
44-EOF
45-}
46-
47-while getopts 'd:r:o:C:e:b:n:s:h' opt; do
48- case $opt in
49- d) seconds=$OPTARG ;;
50- r) fps=$OPTARG ;;
51- o) out=$OPTARG ;;
52- C) cwd=$OPTARG ;;
53- e) xdg=$OPTARG ;;
54- b) bin=$OPTARG ;;
55- n) name=$OPTARG ;;
56- s) specs+=("$OPTARG") ;;
57- h) usage; exit 0 ;;
58- *) usage; exit 2 ;;
59- esac
60-done
61-
62-if (( fps <= 0 || seconds <= 0 )); then
63- echo "qa: fps and seconds must be positive" >&2
64- exit 2
65-fi
66-if [[ -z $out || ${#specs[@]} -eq 0 ]]; then
67- usage >&2
68- exit 2
69-fi
70-if [[ ! -x $bin ]]; then
71- echo "qa: no executable at $bin (run zig build first)" >&2
72- exit 2
73-fi
74-bin=$(readlink -f -- "$bin")
75-cwd=$(cd -- "$cwd" && pwd)
76-mkdir -p -- "$out"
77-out=$(readlink -f -- "$out")
78-socket=/tmp/mini-$name.sock
79-
80-now_ms() {
81- local t=${EPOCHREALTIME/,/.}
82- echo $(( ${t%.*} * 1000 + 10#${t#*.} / 1000 ))
83-}
84-
85-kt() { kitty @ --to "unix:$socket" "$@"; }
86-pane() { kt get-text -m "id:$wid" --extent="$1" --ansi 2>/dev/null; }
87-
88-wid=
89-cleanup() {
90- if [[ -n $wid ]]; then
91- kt close-window -m "id:$wid" >/dev/null 2>&1 || true
92- fi
93- rm -f -- "$socket"
94-}
95-trap cleanup EXIT
96-trap 'exit 1' INT TERM
97-
98-printf -v launch 'cd %q; %q; printf "\nMINI-EXIT %%d\n" $?; exec sleep 86400' "$cwd" "$bin"
99-
100-rm -f -- "$socket"
101-env_args=()
102-if [[ -n $xdg ]]; then
103- env_args=(env "XDG_CONFIG_HOME=$xdg")
104-fi
105-kitty --detach --listen-on "unix:$socket" \
106- -o allow_remote_control=yes -o remember_window_size=no \
107- -o initial_window_width=110c -o initial_window_height=34c \
108- --title "mini-$name" \
109- "${env_args[@]}" bash --norc --noprofile -c "$launch"
110-
111-for _ in $(seq 100); do
112- wid=$(kt ls 2>/dev/null | grep -o '"id": [0-9]*' | tail -n1 | tr -dc '0-9' || true)
113- [[ -n $wid ]] && break
114- sleep 0.1
115-done
116-if [[ -z $wid ]]; then
117- echo "qa: kitty never reported a window on $socket" >&2
118- exit 1
119-fi
120-
121-for _ in $(seq 300); do
122- pane all | grep -q 'mini ·' && break
123- sleep 0.1
124-done
125-if ! pane all | grep -q 'mini ·'; then
126- echo "qa: mini did not start; pane says:" >&2
127- pane all >&2
128- exit 1
129-fi
130-
131-log=$out/steps.txt
132-: > "$log"
133-echo "qa: $out"
134-shot=0
135-
136-send_text() {
137- kt send-text -m "id:$wid" "$1"
138-}
139-
140-send_key() {
141- case $1 in
142- enter) kt send-key -m "id:$wid" enter ;;
143- shift+enter) kt send-key -m "id:$wid" shift+enter ;;
144- ctrl+c) kt send-key -m "id:$wid" ctrl+c ;;
145- esc) kt send-key -m "id:$wid" escape ;;
146- tab) kt send-key -m "id:$wid" tab ;;
147- ctrl+d) kt send-key -m "id:$wid" ctrl+d ;;
148- *) echo "qa: unknown key $1" >&2; exit 2 ;;
149- esac
150-}
151-
152-# Expand every -s spec into a flat list of "at_ms<TAB>verb<TAB>arg" lines.
153-steps=()
154-t=0
155-for spec in "${specs[@]}"; do
156- spec=${spec//;;/$'\n'}
157- while IFS= read -r part; do
158- part=${part#"${part%%[![:space:]]*}"}
159- [[ -z $part ]] && continue
160- verb=${part%%=*}
161- arg=${part#*=}
162- if [[ $verb == wait ]]; then
163- t=$(awk "BEGIN { printf \"%d\", $t + $arg * 1000 }")
164- continue
165- fi
166- steps+=("$t $verb $arg")
167- done < <(printf '%s\n' "$spec")
168-done
169-
170-exec_steps() {
171- local now=$1
172- while (( ${#steps[@]} > 0 )); do
173- local line=${steps[0]}
174- local at=${line%% *}
175- if (( at > now - start )); then break; fi
176- steps=("${steps[@]:1}")
177- local rest=${line#* }
178- local verb=${rest%% *}
179- local arg=${rest#* }
180- case $verb in
181- text) send_text "$arg"; printf '%s text %s\n' "$(( now - start ))" "$arg" >> "$log" ;;
182- key) send_key "$arg"; printf '%s key %s\n' "$(( now - start ))" "$arg" >> "$log" ;;
183- shot)
184- shot=$(( shot + 1 ))
185- pane all > "$out/mark-$(printf '%02d' "$shot")-$arg.txt" || true
186- printf '%s shot %s\n' "$(( now - start ))" "$arg" >> "$log"
187- ;;
188- *) echo "qa: unknown step $verb" >&2; exit 2 ;;
189- esac
190- done
191-}
192-
193-end_reason=
194-start=$(now_ms)
195-next=$start
196-frames=0
197-while :; do
198- now=$(now_ms)
199- (( now - start >= seconds * 1000 )) && break
200- exec_steps $now
201-
202- if ! kt screenshot -m "id:$wid" "$out/frame-$(printf '%05d' "$frames").png" >/dev/null 2>&1; then
203- end_reason="window vanished after $frames frames"
204- break
205- fi
206- frames=$(( frames + 1 ))
207-
208- if pane screen | grep -q 'MINI-EXIT'; then
209- end_reason=$(pane screen | grep -o 'MINI-EXIT -\?[0-9]*' | tail -n1)
210- break
211- fi
212-
213- next=$(( next + 1000 / fps ))
214- sleep "$(awk "BEGIN { printf \"%.3f\", 1 / $fps }")"
215-done
216-
217-exec_steps 999999999
218-elapsed=$(( $(now_ms) - start ))
219-pane all > "$out/final.txt" || true
220-pane screen > "$out/final-screen.txt" || true
221-
222-echo "qa: $frames frames in $(( elapsed / 1000 ))s"
223-if [[ -n $end_reason ]]; then
224- echo "qa: ended early: $end_reason"
225-fi