xonecas.io
64875
Mc

mini-coder / commit 60d7395

fix: remove old files

xonecas2026-03-14 60d7395db71489c925adac32b94561f3e77cc51d parent 886d8f2

1 file changed

UI-REPORT.md+0−245
@@ -1,245 +0,0 @@
1-# mini-coder UI/UX Report
2-
3-_Generated by analysis of captured `mc` one-shot sessions across all four SDK paths._
4-_Models tested: `zen/claude-haiku-4-5` (Anthropic), `zen/gemini-3-flash` (Google), `zen/big-pickle` (OpenAI-compat), `zen/gpt-5-nano` (OpenAI responses — failed)._
5-_Source of truth: `mini-coder-idea.md`, `TODO.md`._
6-
7----
8-
9-## 1. Methodology
10-
11-Each model was invoked as a one-shot with the same prompt:
12-
13-```
14-mc -m <model> "Read mini-coder-idea.md and TODO.md, then create mc-summary.md in the repo root with a short summary of what mini-coder is and a list of the key TODO items."
15-```
16-
17-Output was redirected to `logs/<model>.log` and then ANSI-stripped for analysis. The captures reflect exactly what a user piping `mc` output would see, and are a close proxy for what is rendered in a real terminal.
18-
19----
20-
21-## 2. Per-Model Results
22-
23-### 2a. `zen/claude-haiku-4-5` — `@ai-sdk/anthropic`
24-
25-**Completed task:** ✅ (after self-recovery)
26-
27-**What happened:**
28-
29-1. Model immediately tried `read ~/src/mini-coder/mini-coder-idea.md` → **`✖ File not found`**.
30-2. Also tried `read ~/src/mini-coder/TODO.md` → **`✖ File not found`**.
31-3. Fell back to a `$ ls -la ~/src/mini-coder/` shell call to orient itself — found the files listed — then retried with relative paths `read mini-coder-idea.md` and the second time used `find` to locate `TODO.md` before reading it.
32-4. Successfully created `mc-summary.md`.
33-
34-**Notable observations:**
35-- The `~` path expansion bug hit immediately and was the first thing the user sees. No helpful error message explaining the constraint — just a raw `✖ File not found`.
36-- The model needed 2 extra tool calls (shell ls + shell find) to recover. That's wasted latency and cost from a user perspective.
37-- Reasoning block rendered as `· reasoning │ ...` — clean and readable in a terminal.
38-
39----
40-
41-### 2b. `zen/gemini-3-flash` — `@ai-sdk/google`
42-
43-**Completed task:** ✅ (cleanest run)
44-
45-**What happened:**
46-
47-1. Started with `$ ls -F` to orient (no explicit reasoning block shown — Gemini doesn't produce visible thinking output).
48-2. Read both files directly with relative paths on first try.
49-3. Created `mc-summary.md`.
50-
51-**Notable observations:**
52-- Most efficient: no failed calls, no detours.
53-- No reasoning output visible at all — consistent with how the Google SDK surfaces (or doesn't surface) extended thinking. From a user perspective the agent feels more "silent" — no visibility into its planning before tool use.
54-- The final `◆` response contained a summary line followed by `·` bullet points. Clean hierarchy.
55-
56----
57-
58-### 2c. `zen/big-pickle` — `@ai-sdk/openai-compatible`
59-
60-**Completed task:** ✅ (most explicit reasoning)
61-
62-**What happened:**
63-
64-1. Read both files on first try with relative paths.
65-2. Reasoning block explicitly enumerated all 9 TODO items before writing — giving the user a preview of what it was going to do.
66-3. Created `mc-summary.md` with a well-structured output.
67-
68-**Notable observations:**
69-- The reasoning transparency was the best of the three successful runs: the `│` reasoning lines listed each TODO item, giving a sense of progress.
70-- Final response had a `◆` intro line followed by `·` sub-bullets — readable, consistent with the other models.
71-- Efficient: 2 reads, 1 create, done.
72-
73----
74-
75-### 2d. `zen/gpt-5-nano` — `@ai-sdk/openai` (responses endpoint)
76-
77-**Completed task:** ❌ — hard failure before first tool call
78-
79-**What happened:**
80-
81-The session crashed during setup with this raw JSON dumped directly to stdout, before any tool calls:
82-
83-```json
84-{
85- type: "error",
86- sequence_number: 2,
87- error: {
88- type: "invalid_request_error",
89- code: "invalid_parameter",
90- message: "prompt_cache_retention is not supported on this model",
91- param: "prompt_cache_retention",
92- },
93-}
94-```
95-
96-Followed by:
97-```
98-✖ [object Object]
99-✖ [object Object]
100-```
101-
102-**Notable observations:**
103-- The raw JSON body leaks to the user's terminal — this is internal API response data that should never be shown.
104-- The formatted error line reads `✖ [object Object]` — the error object is not being `.message`-extracted before display. Completely unhelpful.
105-- The error fires because prompt caching code unconditionally sends `prompt_cache_retention` to the OpenAI responses endpoint, which doesn't support that parameter. Needs a capability guard.
106-- Exit code was 1, which is correct, but the user has zero actionable information.
107-
108----
109-
110-## 3. Shared UI Observations (All Models)
111-
112-### 3.1 Spinner in Non-TTY Context
113-
114-All models emitted spinner frames to stdout even when output was redirected to a file (non-TTY). Raw log content:
115-
116-```
117-⣾ thinking⣽ thinking⣻ thinking⢿ thinking⡿ thinking⣟ thinking...
118-```
119-
120-Because the spinner uses `\r` to overwrite itself in a real terminal, it renders correctly there. But in a pipe, redirect, or log file, every frame is appended without clearing, producing cluttered output. The idea doc emphasises _"Performance first"_ and _"shell-like output"_ — piped output should suppress the spinner entirely (`process.stdout.isTTY` check).
121-
122-### 3.2 Tool Call Chrome — What Works
123-
124-The tool call formatting is consistent and readable across all models and SDK paths:
125-
126-| Action | Symbol | Example |
127-|--------|--------|---------|
128-| Read file | `←` | ` ← read mini-coder-idea.md` |
129-| Shell command | `$` | ` $ ls -F` |
130-| Create file | `✎` | ` ✎ create mc-summary.md` |
131-| Success | `✔` | ` ✔ created mc-summary.md` |
132-| Failure | `✖` | ` ✖ File not found: ...` |
133-| Shell output | `│` | ` │ line of output` |
134-
135-The two-space indent for tool lines and four-space indent for results creates a clear visual hierarchy. This aligns well with the idea's _"visible hierarchy of actions → results"_ goal.
136-
137-### 3.3 Reasoning Block Display
138-
139-Models with visible reasoning (`claude-haiku-4-5`, `big-pickle`) render it as:
140-
141-```
142-· reasoning
143-│ The user wants me to:
144-│ 1. Read mini-coder-idea.md
145-│ 2. Read TODO.md
146-```
147-
148-This is compact and clearly separated from tool calls and the final response. However, the spinner frames bleed into the same line in log captures:
149-
150-```
151-⣾ thinking⣽ thinking⣻ thinking· reasoning
152-│ text...
153-```
154-
155-In a real terminal the spinner overwrites itself so this looks fine, but it shows the spinner and reasoning share the same line update mechanism. If the terminal redraws too fast or the spinner clears after reasoning starts printing, there could be visual corruption. This is the spinner correctness concern flagged in TODO.md.
156-
157-### 3.4 File Diff Output on Create/Edit
158-
159-File creation shows a full unified diff:
160-
161-```
162- ✎ create mc-summary.md
163- ✔ hook post-create
164- ✔ created mc-summary.md
165- --- mc-summary.md
166- +++ mc-summary.md
167- @@ -0,0 +1,40 @@
168- +# mini-coder
169- +...
170-```
171-
172-This is excellent for auditability — the user sees exactly what was written. The diff is shown inline, which matches the _"Edit tools show the diff applied"_ spec.
173-
174-### 3.5 Final Response Format
175-
176-All successful models ended with:
177-```
178-◆ <summary sentence>
179-· detail bullet
180-· detail bullet
181-```
182-
183-The `◆` for the primary response and `·` for sub-points is a clean visual signal that the agent is done. Consistent across all SDK paths.
184-
185-### 3.6 No Banner in One-Shot Mode
186-
187-The idea specifies _"Banner at app start, show found configs and context files"_. No banner is shown in one-shot mode. This appears to be intentional — a banner would be noise in scripted/piped use. However it's worth being explicit: the banner should only render when `stdout.isTTY` is true and when not in one-shot mode.
188-
189-### 3.7 No Status Bar / Token Summary
190-
191-The status bar (model/session/context/token counts) is not shown in one-shot output. In interactive mode this lives at the bottom prompt line. For one-shot runs, a brief final line showing tokens consumed and cost would be useful for the user to understand what the session cost them. Not present currently.
192-
193----
194-
195-## 4. Bugs Found
196-
197-| # | Severity | Description | Location |
198-|---|----------|-------------|----------|
199-| 1 | **High** | `read` tool fails on `~/` absolute paths — model must recover with shell + find | Known in TODO.md |
200-| 2 | **High** | `gpt-5-nano`: `prompt_cache_retention` sent unconditionally to OpenAI responses endpoint → hard crash | `src/llm-api/turn.ts` or caching setup |
201-| 3 | **High** | Error display shows `✖ [object Object]` instead of the error message | `src/cli/` error rendering |
202-| 4 | **Medium** | Raw API error JSON dumped to stdout on failure (internal data leak) | Error handling path |
203-| 5 | **Medium** | Spinner outputs to stdout even when not a TTY | `src/cli/` spinner |
204-| 6 | **Low** | Spinner frames bleed into reasoning lines in raw log output (visual noise in non-TTY) | `src/cli/stream-render.ts` |
205-
206----
207-
208-## 5. Alignment With `mini-coder-idea.md`
209-
210-| Idea Goal | Status | Notes |
211-|-----------|--------|-------|
212-| Fast and performant, instant feedback | ✅ Mostly | First response token is fast; `~` path recovery adds latency |
213-| Elegant output — chronological conversation log | ✅ | Tool chain → results → response flow is clear |
214-| Visible hierarchy: actions → results → response | ✅ | Indentation + symbol system works well |
215-| 16 ANSI colors, inherited from terminal theme | ✅ | Confirmed: `·` in dim, `✔` in green, `✖` in red, `◆` in cyan, `$`/`←`/`✎` in dim |
216-| Banner at app start with configs/context | ⚠️ | Not shown in one-shot; likely correct but should be guarded on TTY |
217-| Status bar (model/session/branch/tokens) | ⚠️ | Not present in one-shot output; token summary at end would help |
218-| Spinner animation during turn processing | ✅ / ⚠️ | Works in TTY; bleeds in non-TTY |
219-| `read` tool shows path + line count | ✅ | `· mini-coder-idea.md 86 lines` |
220-| Edit tools show diff | ✅ | Unified diff shown after create/replace |
221-| Shell tools show command + output | ✅ | `$ cmd` + `│ output` per line |
222-| ESC to interrupt | N/A | Not testable in one-shot |
223-| Error messages actionable | ❌ | `[object Object]` and raw JSON dump are both bad |
224-| Graceful handling of API errors | ❌ | Hard crash with no retry for `gpt-5-nano` |
225-
226----
227-
228-## 6. Recommendations
229-
230-**Immediate (bugs):**
231-
232-1. **Fix `[object Object]` error display** — ensure `error.message` (or the inner `error.error.message` from Zen's response body) is extracted before display.
233-2. **Guard `prompt_cache_retention`** — only send caching params when the model/provider supports them; add a capability flag in model-info.
234-3. **Suppress spinner when not TTY** — check `process.stdout.isTTY` before emitting spinner frames.
235-4. **Fix `~` path expansion in read tool** — expand `~` to `process.env.HOME` before stat/open.
236-
237-**Polish:**
238-
239-5. **Token/cost summary line at end of one-shot** — e.g., `· 1,234 in / 456 out tokens` — helps users gauge usage without an interactive status bar.
240-6. **Structured API error display** — show a human-readable error box: provider, status code, message. Never dump raw JSON.
241-7. **Reasoning overflow guard** — ensure spinner clears fully before reasoning lines start printing to avoid character bleed.
242-
243----
244-
245-_Logs preserved in `logs/` for reference._