xonecas.io
64875
Mc

mini-coder / commit 0a1598b

docs: add audit report, remove stale /agent command from skill, fix resolved known issue

- AUDIT-REPORT.md: full codebase audit report from multi-provider testing
- SKILL.md: remove /agent command row (not implemented)
- KNOWN_ISSUES.md: remove /model autocomplete issue (already fixed)

xonecas2026-03-21 0a1598b8a7affc3ebdf39b3bbb1b0600c9c0daa4 parent 4b62adb

3 files changed

.agents/skills/mini-coder/SKILL.md+0−1
@@ -41,7 +41,6 @@ Inside `mc`:
4141 | `/mcp add <name> http <url>` | Add HTTP MCP server |
4242 | `/mcp add <name> stdio <cmd> [args...]` | Add stdio MCP server |
4343 | `/mcp remove <name>` | Remove MCP server |
44-| `/agent [name]` | Set or clear active custom agent |
4544 | `/login [provider]` | Show or start OAuth login |
4645 | `/logout <provider>` | Clear OAuth tokens |
4746 | `/exit`, `/quit`, `/q` | Leave the session |
AUDIT-REPORT.md+100−0
@@ -0,0 +1,100 @@
1+# Audit Report — mini-coder v0.2.1
2+
3+**Date:** 2026-03-21
4+**Auditor:** Claude Code (automated audit skill)
5+
6+## Summary
7+
8+**Phase 1** reviewed every module (`agent/`, `cli/`, `llm-api/`, `tools/`, `session/`, `mcp/`, `internal/`) against the core idea document. All checks pass (`bun run check` — formatting, types, lint, knip, jscpd, 307 tests). Code duplication is minimal (0.28%, 41 lines / 4 clones across 129 files).
9+
10+**Phase 2** tested 5 model paths interactively via tmux:
11+| Model | SDK path | Result |
12+|---|---|---|
13+| `zen/claude-haiku-4-5` | `@ai-sdk/anthropic` | ✅ Clean multi-turn, reasoning display, tool calls |
14+| `zen/gemini-3-flash` | `@ai-sdk/google` | ✅ Working, parallel tool calls rendered inline |
15+| `zen/gpt-5.4-nano` | `@ai-sdk/openai` (responses) | ✅ Working, verbose reasoning, redundant tool calls (model behavior) |
16+| `zen/minimax-m2.5` | `@ai-sdk/openai-compatible` | ✅ Clean, concise tool use |
17+| `anthropic/claude-haiku-4-5` | Anthropic OAuth | ✅ Parallel tool calls, ESC interrupt works |
18+
19+Also tested: one-shot mode (`bun run dev 'What is 2+2?'`) — clean output with no banner noise.
20+
21+## Code & Architecture
22+
23+### Correctness issues
24+
25+1. **Status bar loses context tokens after ESC interrupt.** After pressing ESC to cancel a streaming response, the status bar shows `tok 12.9k/258` without the `ctx` field. The interrupt path in `processUserInput` catches the error and re-throws without updating `lastContextTokens`. The turn's partial token data is lost.
26+
27+2. ~~**`/agent` command documented but not implemented.** The `mini-coder` skill SKILL.md documents `/agent [name]` ("Set or clear active custom agent") but no such command exists in `commands.ts`. The help output also omits it. Either the doc should be updated or the feature should be implemented.~~ Done
28+
29+### KISS/DRY/YAGNI observations
30+
31+3. **`turn-execution.ts` (402 lines) does a lot.** It contains: tool conversion (`toCoreTool`, `buildToolSet`), Anthropic tool caching (`annotateToolCaching`), turn state tracking (`createTurnStateTracker`), stream normalization (`StreamToolCallTracker`, `StreamTextPhaseTracker`), and stream-to-event mapping. These are logically distinct responsibilities. The file is manageable but is the second-largest non-test file and the most complex.
32+
33+4. **`isOpenAIReasoningModelFamily` matches `gpt-5*` and `o*` prefixes.** The `o*` prefix is very broad — any future `ollama/`-like model ID starting with `o` routed through zen would match. Currently safe because `getZenBackend` only hits this via `openai` path, but the routing function's generality could surprise.
34+
35+5. **`compactToolResultPayloads` iterates all messages every step.** It's called via `prepareStep` on every multi-step tool loop. Each call scans and potentially clones the entire message array. For long conversations with many tool results this could become a hot path. Not a bug, but worth noting for performance.
36+
37+### Architecture alignment with core idea
38+
39+- ✅ **Shell-first tool surface** — `shell`, `listSkills`, `readSkill`, MCP, and optional web tools. Small and focused.
40+- ✅ **Append-only scrolling log** — no redraws observed, output pushes the prompt down.
41+- ✅ **16 ANSI colors** — `yoctocolors` only, no RGB/256-color escapes.
42+- ✅ **Single system prompt across all providers** — no provider-specific branches in `buildSystemPrompt`.
43+- ✅ **AGENTS.md / CLAUDE.md autodiscovery** — both `.agents/` and `.claude/` conventions supported with conflict warnings.
44+- ✅ **Skills discovery** — local + global, recursive walk, frontmatter validation, proper naming rules.
45+- ✅ **Prompt caching** — Anthropic cache breakpoints are correctly managed per-step, tool caching annotated.
46+- ✅ **Context pruning** — rolling pruning per step with separate logic for turn-level vs step-level to preserve cache.
47+- ✅ **No max steps or tool call limits** — `stopWhen: () => false` with user interrupt only.
48+- ✅ **MCP support** — StreamableHTTP with SSE fallback and stdio, tool names prefixed with server name.
49+- ✅ **Session management** — sqlite-backed, resume/new/list/switch all working.
50+- ✅ **OAuth** — Anthropic OAuth with PKCE, token caching, priority over env var.
51+
52+### Minor observations
53+
54+6. **`loadSkillsIndex` is called multiple times per interaction** — once in `buildSystemPrompt`, once in help, once in command dispatch. Each call re-scans the filesystem. The scan is fast (reads only frontmatter), but caching would be cleaner.
55+
56+7. **`autoTitleSession` is called on every `processUserInput` call**, not just the first. The underlying `setSessionTitle` should be idempotent (only sets if untitled), but it hits the DB every turn.
57+
58+## UI/UX Alignment
59+
60+### What matches the core idea
61+
62+- **Banner** — correctly shows version, model, cwd, AGENTS.md files, skills count, connected providers, and helpful keybindings. Clean and informative.
63+- **Status bar** — shows model, session ID, git branch, thinking effort, token counts, context percentage. Updated between turns. Matches the spec.
64+- **Tool rendering** — shell commands show the command then output. MCP tools prefixed with server name. Skill tools show one-line name + description.
65+- **Spinner** — inline spinner with label ("thinking", "running shell") visible during processing. Disappears cleanly.
66+- **Reasoning display** — reasoning blocks clearly indented with `· reasoning` prefix. Togglable with `/reasoning`.
67+- **Error handling** — errors logged and displayed as one-line summaries; user returned to prompt.
68+- **ESC interrupt** — works correctly, preserves partial response in history.
69+
70+### Cross-provider UI consistency
71+
72+All 5 tested paths produce consistent output formatting:
73+
74+- Tool call lines use the same `?`/`$`/`←` glyph vocabulary across providers.
75+- Streaming text renders incrementally with the `◆` assistant glyph.
76+- Status bar format is identical across providers.
77+- Reasoning display works for Anthropic (native), Gemini (thinking), and OpenAI (commentary → reasoning mapping). This is impressively uniform given the SDK differences.
78+
79+### Notable UI findings
80+
81+8. **GPT parallel tool calls display overlap.** When gpt-5.4-nano made parallel tool calls, the display showed an unusual nested format with `↳` prefix. While readable, it's denser than the sequential display from other providers. This is functional but visually less clean.
82+
83+9. **Verbose output enabled by default.** Both `reasoning: on` and `verbose: on` were shown in the banner. For most users, the default should probably be non-verbose (truncated) to avoid wall-of-text outputs. This matches the core idea's "shell tool: model can [get large outputs]" concern — truncation should be the default for large tool outputs.
84+
85+## Recommendations
86+
87+### Immediate bugs
88+
89+- **Fix status bar token tracking after ESC interrupt** — the interrupt path should still update `totalIn`/`totalOut`/`lastContextTokens` from the turn error event's partial data.
90+
91+### Code changes
92+
93+- **Remove `/agent` from mini-coder skill SKILL.md** — or implement it. Currently it's misleading documentation.
94+- **Consider splitting `turn-execution.ts`** — the stream normalization classes (`StreamToolCallTracker`, `StreamTextPhaseTracker`) and the tool conversion logic could be separate files, improving readability.
95+
96+### Polish items
97+
98+- **Cache `loadSkillsIndex` result per-turn** — avoid redundant filesystem scans within a single interaction cycle.
99+- **Make `autoTitleSession` skip DB calls after first title** — add a flag to `ActiveSession` to avoid repeated no-op DB writes.
100+- **Review `verbose: on` as default** — the core idea emphasizes truncation for large outputs; having verbose on by default works against this.
docs/KNOWN_ISSUES.md+0−1
@@ -2,7 +2,6 @@
22
33 ## Bugs
44
5-- `/model` doesn't autocomplete models provider/name pattern.
65 - AI SDK expands `claude-3-5-haiku` → dated variant that Zen doesn't serve (404).
76 - Shell tool: model can `tmux kill-session` the host tmux session if names collide (e.g. audit skill creates session named "audit" matching the user's). Not a code bug — the skill/model just picks a conflicting name. Mitigate via skill wording or session name prefixing.