xonecas.io
79113
Ma

mini-coding-agent / commit 97d6f77

chore: commit code review notes for git record

xonecas2026-10-05 97d6f77b2ca8c89c1861048eac536ca5be72cac8 parent 4e73d0e

2 files changed

AGENTS.md+16−10
@@ -2,23 +2,29 @@
22
33 A fast, transparent, config-first terminal coding agent for one user at a time.
44
5-This file holds intent, direction, and guardrails — not a description of the
6-code. The source is the source of truth for behavior. If a fact can be learned
5+The source code is the source of truth for behavior. If a fact can be learned
76 by reading the code, it does not belong here; keep this file short.
87
98 ## Verification
109
11-Verify against the real provider. **Do not stand up mock servers, fixture
12-endpoints, or replay files**; they stall and prove nothing. Use the
13-`OPENCODE_API_KEY` environment variable and a scratch `XDG_CONFIG_HOME` with a
14-`mini-coding-agent/config.json` that declares the provider under test.
10+**Do not stand up mock servers, fixture
11+endpoints, replay files, or mock terminals**; they prove nothing.
12+
13+Use a real bash call for headless runs, and the `tools/stress.sh` script for TUI
14+runs.
15+
16+### Provider
17+
18+Verify against the real provider. Use the `OPENCODE_API_KEY` environment
19+variable and a scratch `XDG_CONFIG_HOME` with a `mini-coding-agent/config.json`
20+that declares the provider under test.
1521
1622 Every Zen/Go request needs the `x-opencode-session` header; set it via the custom
1723 provider's `headers`. Not every catalog model is enabled for the account (for
18-example `claude-opus-5` is disabled and returns `Model access is disabled`), so
19-use the models above. Run a real tool call, not just a text turn.
24+example `claude-opus-5` is disabled and returns `Model access is disabled`).
25+Run a real tool call, not just a text turn.
2026
21-## Driving the TUI with kitty
27+### Driving the TUI with kitty
2228
2329 There is no `tmux` here. `tools/stress.sh` drives the TUI in a real kitty
2430 window over remote control on a private socket, one window per run: it launches
@@ -31,4 +37,4 @@ Frames land in `frame-NNNNN.png`. At the end of a run the pane is written with
3137 its truecolor SGR to `final.txt` (scrollback) and `final-screen.txt` (live
3238 screen). The last line reports frames, wall time, and achieved fps; an
3339 `ended early: MINI-EXIT <n>` line means the app died, and `final.txt` holds the
34-dump. Read the pane text and the frames, not pixels.
40+dump.
notes.md+67−0
@@ -0,0 +1,67 @@
1+# Some notes from reading the code.
2+
3+> Context: I'm mostly a web engineer, with some backend experience with python, node and go.
4+
5+Some of my notes might be because of lack of Zig experience.
6+
7+## Notes
8+
9+`src/session.zig` - I was surprised to see such an awkward syntax format to creating/encoding json. Is this normal for zig? It's hard to read. Is there no `toJSON` type of thing? So we could then write that?
10+
11+`src/json.zig` - Similar to the session comment, I'm surprised at how cumbersome it is to deal with JSON.
12+
13+`src/main.zig` - has some headless concerns mixed into the entry point of the app. Worth considering extracting headless into `src/headless.zig`. Single concern files are easier to make a mental model around.
14+
15+`src/diff.zig` - We are rendering a whole header with index and divider, just to strip it in the TUI. Seems counter productive.
16+
17+`src/config.zig` - When we fixed the issue with the model specific api being at provider level for opencode in a recent commit, apparently we didn't do it for custom providers. Again, the models need to carry the metadata, the provider is just a label grouping.
18+
19+```jsonc
20+// Example custom provider **correct**
21+{
22+ "id": "local",
23+ "name": "Local",
24+ "models": [{
25+ "id": "qwen3-coder",
26+ "api": "openai-completions",
27+ "baseUrl": "http://127.0.0.1:11434/v1"
28+ }],
29+ "envKeys": ["LOCAL_API_KEY"],
30+ "headers": { "x-tenant": "mini" }
31+}
32+```
33+
34+I suggest the above structure, so we match the work we did for opencode. Basically the mistake here is assuming all providers use the same api for all models, which is not true. Not even for local envs.
35+Another note here is that again, I'm shocked at how cumbersome it is to read and validate JSON.
36+
37+
38+*Issues with pausing and canceling being delayed* - When the user presses either pause or cancel in the TUI, there is no immediate feedback, the visible result only happens at the next step. This is correct for pause, but incorrect for cancel. Cancel means stop right now, pause means pause at the next turn boundary. At some point the two got merged into both waiting for a turn boundary to act. And neither is properly displayed in the TUI status (no `pausing` state, canceling shouldn't exist, it …
39+**Comment on line 142 of `src/agent.zig`** - Completely wrong about cancellation and shouldn't be there. Pausing and steering land at turn boundaries, canceling is immediate!
40+`src/agent.zig` - cancel needs to be checked more often, between each phase. once and before tool calls is not responsive enough.
41+
42+`src/api.zig` and `src/config.zig` (possibly more) - I keep seeing the same helpers everywhere, `numField`, `stringField/strField`, `objField`. These exist in multiple files, it's ridiculous, it's an affront to the golden rule of less code. Just grepping the pattern shows the abuse of copy paste like approach.
43+
44+```bash
45+❯ rg "fn .+Field"
46+src/api.zig
47+308:pub fn optNumField(obj: std.json.ObjectMap, key: []const u8) ?u64 {
48+317:pub fn numField(obj: std.json.ObjectMap, key: []const u8) u64 {
49+322:pub fn stringField(obj: std.json.ObjectMap, key: []const u8) ?[]const u8 {
50+331:pub fn objField(obj: std.json.ObjectMap, key: []const u8) ?std.json.ObjectMap {
51+340:pub fn firstObjField(obj: std.json.ObjectMap, key: []const u8) ?std.json.ObjectMap {
52+365:pub fn boolField(obj: std.json.ObjectMap, key: []const u8, default: bool) bool {
53+
54+src/config.zig
55+77:fn strField(a: std.mem.Allocator, obj: std.json.ObjectMap, key: []const u8, path: []const u8) !?[]const u8 {
56+85:fn boolField(obj: std.json.ObjectMap, key: []const u8) ?bool {
57+```
58+
59+**Comments** - Being used randomly without thought, most of them re-state the code they near and add absolutely no value. As we saw above with canceling, they are introducing bugs and having a negative impact. We have a rule about comments, it's time to enforce it repo-wide, before these low quality comments cause more damage.
60+
61+`src/snapshot.zig` - the list of ignored paths is meant to come from the config, not this incomplete hardcoded list.
62+
63+`src/tui/editor.zig` - `pub fn render2` seriously? Where is render1? Naming is important and this is unacceptable.
64+
65+`src/tui/tui.zig` - This file has a lot of responsibilities, making it very big. Token estimation and commands at least, could be extracted.
66+
67+`src/tui/theme.zig` - will eventually grow too much, each theme we add will make that file worse. A refactor for later, since it's ok right now.