xonecas.io
64875
Mc

mini-coder / commit 5980c72

docs: add file edit helper plan

xonecas2026-03-15 5980c72a1e79943bb34cf512a643f64168fb4245 parent ae2aebb

2 files changed

TODO.md+2−117
@@ -1,122 +1,7 @@
11 # TODO
22
3-- Strange output mid session:
4-
5-There are several sessions in the db where this issue happened.
6-
7-A fix was made to suppress commentary from gpt to avoid this, but now there is no reasoning output from gpt mdels.
8-Update: reasoning is now all dumped at turn end.
9-
10-The issue is not fixed, it's just suppressed.
11-This seems like an issue on how we are parsing stream events, and not recognzing tool calls from other events.
12-
13-neither pi or opencode have this bug with the same provider, and opencode uses the same sdks as we do
14-use the `gh` tool to clone and inspect how they avoid this issue
15-
16-Expectation: Gpt models don't produce corrupted output and correctly display reasoning
17-
18-Relevant reasoning output:
19-
20-```
21-I keep running into issues with tool syntax, and it feels like it's because of the interface. I really need to use the correct commentary to call functions.shell. It's important to stick to the standard format to get it right. I wonder if I should double-check the documentation or examples to be sure I’m following things correctly. Just trying to make sure I figure this out! There's probably something simple I'm overlooking.It seems my interface isn’t accepting the call because I’m in anal …
22-
23- I’m thinking maybe my last few attempts didn’t work because I didn’t include the recipient name. But I believe the functions should work with the shell style I used earlier. I’ll make sure to try using the multi_tool method again with the exact syntax I had. I'm curious if that’ll make a difference in the process. Let’s see how it goes!
24-```
25-
26-```
27- I'm considering whether to replace lines 90-94 with a single blank. I think using `newContent=""` might be supported here, so let’s try it out with just `""` and see if it works. It's a simple enough change, but I want to make sure this approach will actually accomplish what I need without causing unintended issues. Let’s see how this plays out!to=functions.replace 玩彩神争霸ությունը ฝ่ายขายละครើ្យិបង្គ{"path":"src/cli/tool-render.test.t …
28-
29- I’m noticing that something seems off with the current approach. It could be related to how data is being handled. I wonder if I should consider using a multi-tool approach, but I think maybe it’s unnecessary. Instead, it seems best to just carefully type out the exact information needed to avoid any weird issues that could arise. I want to get this right for the user!to=functions.replace 体育彩票天天json 彩神争霸大发快三{"path":"src/cli/tool-render.test.ts","startAnchor":" …
30-
31- I'm wondering if I've hit a weird issue with the system from copying. I might switch to using the shell to write the file, even though the guidelines prefer a dedicated method. Using the shell with `cat` could work since the file is now small. I remember that I should always read a file before editing it. Maybe I’ll use `cat <<'EOF' > src/cli/tool-render.test.ts` for a clean overwrite. I'll need to be careful with this approach!A dedicated edit tool is being finicky on this one tail cleanup, …
32-```
33-
34-Corruption example, there are several sessions in our database where this happened with gpt models
35-
36-```
37-◆ Progress update: I’ve implemented a first UX-focused refactor around tool-stream visibility and am now validating stream/event tests plus a manual `bun run dev` run for one-shot tool calls.{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000}{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000} to=functions …
38-{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000}{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000}to=functions.shell 񹚊ppjson
39-{"command":"echo hi","timeout":30000}to=functions.shell 天天买彩票 ಕ್ರಮ`
40-Let's try once carefully.
41-{"command":"..."}
42-```
43-
44-with function chosen by previous? Wait earlier had "to=functions.shell". yes must include like:
45-`to=functions.shell 彩神争霸官网json
46-{"command":"bun test ...","timeout":120000}{"command":"git status --short","timeout":30000}` with to=functions.shell in metadata. Here UI likely hidden. I'll follow same exact:
47-{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000} to=functions.shell
48-to=functions.shell 天天中彩票买json
49-{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000}to=multi_tool_use.parallel үрүмjson
50-{"tool_uses":[{"recipient_name":"functions.shell","parameters":{"command":"bun test src/llm-api/turn-stream-events.test.ts src/llm-api/turn-execution.test.ts src/cli/tool-render-call.test.ts","timeout":120000}}]}to=functions.shell 天天中彩票追号json
51-{"command":"echo test","timeout":30000}{"command":"git status --short","timeout":30000}
52-
53-```
54-with assistant metadata to=functions.shell from UI (not visible in message maybe I set via tool button). In raw text here maybe cannot set to=. Actually we
55-· reasoning
56- **Checking repository status**
57- **Inspecting project structure before testing**
58- **Planning source inspection**
59- **Checking package scripts for testing**
60- **Planning stepwise refactor**
61- **Testing interactive and one-shot runs**
62- **Planning interactive test approach**
63- **Inspecting output streaming complexity**
64- **Inspecting stream render content**
65- **Assessing stream event processing**
66- **Inspecting tool call event handling**
67- **Considering execution buffering**
68- **Planning UI streaming consistency improvements**
69- **Exploring interactive session simulation**
70- **Investigating command echo and rendering issues**
71- **Inspecting provider options for simplification**
72- **Identifying rendering issue source**
73- **Planning streamlining and cleanup**
74- **Assessing streaming rendering issues**
75- **Assessing spinner lifecycle**
76- **Assessing stream renderer refactor**
77- **Assessing provider option complexity**
78- **Analyzing caching implementation inconsistencies**
79- **Planning provider option refactor**
80- **Planning incremental tool-call rendering fix**
81- **Modifying test and refactoring stream handling**
82- **Adjusting case formatting**
83- **Verifying tool-call presence**
84- **Restoring missing case for direct chunks**
85- **Refactoring test line to use maps**
86- **Running targeted test**
87- **Testing manual dev run**
88- **Refining tool call rendering and deduplication**
89- **Updating shell section**
90- **Replacing anchors**
91- **Checking existing tests for tool rendering**
92- **Adding tests for shell and read edge cases**
93- **Running targeted tests**
94- **Implementing synthetic ID aliasing**
95- **Reintroducing skip logic for empty tool-input-start**
96- **Editing input start case**
97- **Replacing anchors now**
98- **Updating test for id omission**
99- **Verifying event handling tests**
100- **Correcting tool usage**
101- **Correcting JSON format in call**
102- **Correcting syntax format**
103- **Adjusting tool call format**
104- **Identifying malformed input issue**
105- **Correcting recipient inclusion**
106- **Checking mode compatibility**
107- **Considering alternative command order**
108- **Addressing tool call issues**
109- **Diagnosing tool call syntax issue**
110- **Identifying silent execution failure**
111-
112- __User interrupted here__
113-
114- gpt-5.3-codex · ~/src/mini-coder · ✦ medium · ⎇ main · tok 2143.4k/8.5k · ctx 71.0k/400.0k 18% · #mmqw0u3y
115- ▶
116-```
117-
118-- Models in general struggle with our read/write tools, use the db to investigate their behaviour with out tools and let's refactor them with the goal of reducintg errors.
119-- UI hangs for a short time before reasoning blocks. Reasoning blocks lost their italic styling.
3+- UI hangs for a short time before reasoning blocks. Reasoning blocks should use our colors library for italic styling.
4+- Assistant responses are no longer rendered with highlighted markdown syntax. It's just plain text with no coloring.
1205
1216 ---
1227
docs/file-helper-plan.md+257−0
@@ -0,0 +1,257 @@
1+# File Helper and Tooling Refactor Plan
2+
3+## Summary
4+
5+We are moving away from making the LLM directly operate the current hashline `read` / `replace` / `insert` protocol as the primary editing path.
6+
7+The root problem is not only stale anchors or poor recovery. The bigger issue is that the current model-facing edit API is too complex and stateful for reliable use:
8+
9+- `read` returns decorated lines that must be translated back into plain text
10+- edits require choosing between several write modes
11+- writes are coupled to prior reads and exact anchors
12+- models frequently produce valid-looking but bad edits, then enter reread / repair loops
13+- shell becomes the escape hatch when structured edits break down
14+
15+The new direction is:
16+
17+- prefer **shell-driven workflows** for reading, searching, verification, and other general repo actions
18+- provide a **dedicated helper CLI binary** for one thing only: safe, token-conscious file edits
19+- keep shared logic in **internal packages**, with thin bin entrypoints
20+- remove the old hashline-based edit tools and update prompts/tool guidance to reflect the new approach
21+
22+---
23+
24+## Decisions
25+
26+### 1. Prefer shell + helper CLI over direct hashline editing
27+
28+The agent should primarily edit files via shell commands that call a purpose-built helper CLI, instead of directly using `replace` / `insert` for most code changes.
29+
30+Why:
31+
32+- models are generally stronger with shell-shaped workflows
33+- a helper CLI can still enforce safety and deterministic behavior
34+- this reduces the protocol burden compared with multi-step anchor editing
35+- it gives us a simpler model-facing interface without giving up control
36+
37+### 2. Use a separate helper binary, not `mc file ...`
38+
39+We should expose a separate executable for file operations instead of overloading the main `mc` CLI.
40+
41+Why:
42+
43+- cleaner mental model:
44+ - `mc` = agent CLI
45+ - helper bin = deterministic file operations
46+- lower command ambiguity for models
47+- easier to evolve independently
48+- easier to document as a narrow, machine-oriented interface
49+
50+Working name examples:
51+
52+- `mc-edit`
53+
54+Final naming can be decided later, but it should be a separate bin.
55+
56+### 3. Shared code should live in internal packages
57+
58+The helper bin and the main CLI must not share logic by importing each other’s entrypoints.
59+
60+Instead, shared implementation should be extracted into internal packages / internal modules.
61+
62+High-level principle:
63+
64+- bins are thin adapters
65+- reusable logic lives below them
66+- tests should target internal packages directly where possible
67+- Consider migration to a typescript monorepo or just nested packages
68+
69+---
70+
71+## Proposed architecture
72+
73+## Binaries
74+
75+- `mc`
76+ - existing agent CLI
77+- `mc-edit`
78+ - single-purpose safe edit helper, intended to be invoked from shell
79+
80+## Internal packages / modules
81+
82+Suggested initial layout:
83+
84+- `src/internal/file-edit/`
85+ - path resolution
86+ - edit planning and application
87+ - stale-state checks
88+ - result metadata
89+
90+Exact layout can be refined during implementation. The important constraint is that the bin stays thin and the editing logic lives in shared internals.
91+
92+A key simplification here is that we are **not** designing a broad file-operations CLI. Shell already covers reading, searching, moving files, and orchestration well enough. The helper only needs to solve one problem: safe partial file edits.
93+
94+---
95+
96+## Design goals
97+
98+The helper CLI should optimize for **model reliability**, **determinism**, **safety**, and **token efficiency**.
99+
100+### Reliability goals
101+
102+- one simple mental model for edits
103+- avoid anchor bookkeeping entirely in the model-facing API
104+- keep the operation narrow enough that the model can use it consistently
105+- make stale state explicit and easy to recover from
106+
107+### Safety goals
108+
109+- apply targeted edits instead of defaulting to whole-file rewrites
110+- fail clearly when the expected target no longer matches
111+- avoid silent partial success
112+
113+### Token and performance goals
114+
115+- avoid full-file rewrites for ordinary edits
116+- keep helper invocations and outputs compact
117+- reduce reread / repair loops caused by bad accepted edits
118+- preserve existing repo performance standards
119+
120+---
121+
122+## Model-facing API direction
123+
124+We should keep the helper CLI as small as possible.
125+
126+The shell tool is already sufficient for:
127+
128+- reading files
129+- searching code
130+- inspecting directories
131+- running tests and verification
132+- composing temporary files when needed
133+
134+We do not need to duplicate any of that functionality in the helper.
135+
136+`mc-edit` should do one thing only: apply a safe partial edit to a file without requiring a whole-file overwrite.
137+
138+The exact invocation details can be finalized during implementation, but the shape should stay minimal:
139+
140+- one binary
141+- one edit operation
142+- targeted file edits
143+- clear failure when the expected target no longer matches
144+- compact, machine-friendly output
145+
146+The helper exists to make ordinary edits reliable and token-conscious. It should not grow into a general-purpose file command suite.
147+
148+---
149+
150+## Output principles
151+
152+The helper CLI should be machine-oriented first.
153+
154+Preferred traits:
155+
156+- stable output format
157+- minimal verbosity
158+- easy success/failure detection
159+- compact enough for shell use
160+
161+Current leaning: keep the output as small and rigid as possible so the model can use it consistently.
162+
163+---
164+
165+## Relationship to existing tools
166+
167+- do not expand the current hashline protocol further
168+- do not keep the old edit tools as a fallback path
169+- once `mc-edit` is proven out, remove `replace` / `insert` / related hashline edit plumbing and clean up the associated prompting
170+- any shared logic worth keeping should be extracted into the new internal package rather than preserved through compatibility layers
171+
172+Important: the goal is simplification, not running two editing systems indefinitely.
173+
174+---
175+
176+## Migration strategy
177+
178+### Phase 1: Extract internals
179+
180+- move reusable file-edit logic into an internal package
181+- keep the extraction narrowly focused on safe partial edit application
182+- add focused tests around success and failure behavior
183+
184+### Phase 2: Add `mc-edit`
185+
186+- add `mc-edit` as a separate binary
187+- implement only the minimal safe-edit behavior
188+- ensure the output contract is stable and compact
189+
190+### Phase 3: Switch the agent path
191+
192+- update agent guidance to prefer shell + `mc-edit`
193+- stop steering the model toward hashline edits
194+- monitor behavior in the session DB
195+
196+### Phase 4: Remove old edit tools
197+
198+- delete the old hashline-based edit tools and their supporting code
199+- remove obsolete tests, prompts, and documentation
200+- keep only the new editing path
201+
202+---
203+
204+## Success criteria
205+
206+This refactor is successful if we observe meaningful reduction in:
207+
208+- reread / edit loops on the same file
209+- overlapping repair edits after a "successful" write
210+- malformed but accepted edit payloads
211+- need to abandon the safe edit path and fall back to raw shell rewrites
212+
213+And improvement in:
214+
215+- task completion reliability
216+- model confidence after edits
217+- token efficiency of normal edits
218+- maintainability of the editing stack
219+
220+---
221+
222+## Non-goals
223+
224+For this effort, we are **not** trying to:
225+
226+- perfect the existing hashline anchor format
227+- add more anchor variants or richer line matching as the main strategy
228+- turn the main `mc` CLI into a multi-purpose file helper interface
229+- build a broad file-management helper that duplicates shell capabilities
230+- add multiple helper subcommands or grow a larger command surface
231+
232+Those may still be useful in limited contexts, but they are not the primary direction.
233+
234+---
235+
236+## Open questions for implementation
237+
238+These can be finalized during the implementation phase:
239+
240+- final helper binary name and exact invocation shape -- `mc-edit`
241+- the simplest safe matching strategy for partial edits
242+- exact result format on success and failure
243+- the cleanest removal sequence for the old edit tools and their prompt wiring
244+
245+---
246+
247+## Implementation guidance for future work
248+
249+Implementation should stay scoped and incremental:
250+
251+1. extract internal file-edit primitives first
252+2. add the separate helper bin second
253+3. keep the command surface to a single edit behavior
254+4. add focused tests before broad integration changes
255+5. switch agent behavior and then remove the old tools
256+
257+Do not begin by expanding the current hashline API. The point of this effort is to replace it with a much simpler editing contract, not add more protocol complexity.