@@ -0,0 +1,489 @@
1+# mini-coder vNext direction
2+
3+This document captures the product direction and path forward derived from the
4+user's brain dump in [`TODO.md`](../TODO.md), discussion about it, repository
5+history, the archived mini-coder implementations, Feather, Pi extensions, and
6+OpenCode usage.
7+
8+It records intent, decisions, and decision gates. It is deliberately not a
9+complete implementation specification. Code, tests, focused acceptance journeys,
10+and short decision records should remain the detailed sources of truth as vNext
11+evolves.
12+
13+## Product statement
14+
15+mini-coder should be a transparent, extensible terminal coding agent with an
16+excellent input experience, a small auditable core, first-class local and hosted
17+model support, and sessions that remain intelligible and owned by the user.
18+
19+Local and hosted models are peers. Local support should not be a separate or
20+reduced edition, while hosted-provider support should not force local users
21+through verbose cloud-oriented configuration.
22+
23+## Product character
24+
25+mini-coder should combine:
26+
27+- Pi's small agent core, minimal system prompt, versatility, and extension-first
28+ philosophy.
29+- OpenCode's attention to terminal UX and presentation.
30+- Locally owned, readable sessions and transparent agent behavior.
31+- First-class local-model onboarding and context management.
32+- A dependency and maintenance surface small enough for a hobby project to
33+ understand and sustain.
34+
35+Transparency does not require showing every event at full volume. The default UI
36+may summarize information to remain readable, but model requests, reasoning made
37+available by the provider, tool activity, compaction, delegation, errors, and
38+other meaningful work must be visible or directly inspectable. The application
39+must not replace concrete activity with generic messages such as "a subagent is
40+doing things."
41+
42+## Lessons from previous implementations
43+
44+The repository history contains several useful experiments:
45+
46+1. The original implementation owned substantial provider and terminal behavior.
47+ It became expensive to maintain alongside the actual agent.
48+2. The 0.5 implementation adopted pi-ai and cel-tui, but accumulated a broad
49+ feature set and a detailed specification that was costly to keep synchronized
50+ with the code.
51+3. The current prototype recovered a small and understandable core, but removed
52+ too much product structure around observability, editing, extensibility,
53+ provider-neutral presentation, and durable session semantics.
54+4. Feather demonstrated useful local-provider, append-only session, and terminal
55+ ideas. It also showed that owning providers, tools, sessions, context, and the
56+ TUI while avoiding runtime dependencies creates a large maintenance surface of
57+ its own.
58+
59+vNext should therefore not begin as another comprehensive spec-driven rewrite,
60+and it should not grow by attaching features directly to the current mutable TUI
61+state. It should proceed through measured decisions and narrow vertical slices.
62+
63+## Confirmed decisions
64+
65+### Model support
66+
67+Local and hosted providers are equal product paths.
68+
69+The local path should eventually provide straightforward endpoint discovery,
70+health reporting, model discovery, capability and context-window information,
71+and useful defaults for at least Ollama and llama.cpp. It should not require users
72+to reproduce an entire provider model record for a normal setup.
73+
74+### Initial extension surface
75+
76+The first extension API should focus on three demonstrated needs:
77+
78+- tools,
79+- commands,
80+- custom agents.
81+
82+Provider plugins, arbitrary lifecycle hooks, and custom TUI components should not
83+be included until a concrete extension requires them.
84+
85+Extensions are trusted in-process code. mini-coder should state that plainly
86+instead of presenting an application-level plugin permission system as a
87+security boundary.
88+
89+### Initial editor scope
90+
91+The first editor should target ordinary notepad-level input rather than Vim,
92+Emacs, or readline parity.
93+
94+The initial scope is:
95+
96+- multiline insertion and deletion,
97+- predictable cursor movement across lines,
98+- normal selection and clipboard-oriented editing supported by the chosen TUI
99+ and terminal,
100+- reliable typing, deletion, newline handling, and large paste handling,
101+- draft preservation when opening and closing UI controls,
102+- a clear way to attach text files and supported images.
103+
104+The initial scope explicitly excludes:
105+
106+- Vim or Emacs modes,
107+- undo and redo,
108+- persistent input history,
109+- prompt history search,
110+- general filesystem path completion.
111+
112+File attachments are required even though general path completion is deferred.
113+The attachment interaction can be purpose-built rather than making a complete
114+path-completion system a prerequisite.
115+
116+### Diagnostics and telemetry
117+
118+vNext should provide local diagnostics for development and dogfooding. No usage,
119+prompt, error, or performance telemetry should be sent remotely.
120+
121+Local diagnostics should make startup, provider requests, agent phases, tool
122+execution, rendering, cancellation, and failures traceable. Secrets and prompt or
123+tool content should be excluded or redacted by default, with more detailed local
124+logging enabled explicitly when needed.
125+
126+Future opt-in user telemetry is not ruled out. The initial implementation should
127+keep diagnostic event production separate from its local storage or display, but
128+should not build a generalized telemetry platform before another sink exists.
129+
130+### Repository and release strategy
131+
132+The current main branch should be preserved in a new archive branch before vNext
133+work changes it substantially.
134+
135+After that archive exists, vNext may replace the current implementation on main
136+or reuse useful pieces. This should be decided from evidence rather than assuming
137+that either a clean rewrite or incremental migration is inherently better.
138+
139+vNext will not be published to npm until it provides a better overall experience
140+than the currently published version. The archived version remains the behavioral
141+and benchmark baseline during development.
142+
143+## Architectural direction
144+
145+These are starting constraints to validate through the first vertical slice, not
146+a prescribed file tree.
147+
148+### Owned application model
149+
150+pi-ai remains the initial provider implementation, but mini-coder should translate
151+its messages and stream events once at a narrow adapter boundary.
152+
153+The rest of the application should consume small mini-coder-owned values for:
154+
155+- readable user and assistant content,
156+- reasoning content when a provider exposes it,
157+- tool calls and arguments,
158+- tool progress and results,
159+- usage,
160+- model and provider identity,
161+- stop reasons, cancellation, and errors.
162+
163+Presentation code should not repeatedly inspect pi-ai content unions. Provider
164+metadata may be retained as an optional sidecar for same-provider continuation,
165+but it must not be the only carrier of session meaning.
166+
167+A separate modular provider library should remain a research topic until concrete
168+provider divergence demonstrates that pi-ai plus a narrow adapter cannot satisfy
169+mini-coder. vNext should not depend on solving a universal provider abstraction
170+first.
171+
172+### User-owned sessions
173+
174+The local session record should be canonical, readable, versioned, and append-only.
175+It should retain enough normalized information for another model or provider to
176+understand and continue the work without dereferencing provider-owned state.
177+
178+Durable records should include meaningful completed events such as messages, tool
179+calls and results, cancellations, compaction summaries, model changes, and
180+subagent lineage. High-frequency streaming deltas can remain transient.
181+Provider-specific opaque data may be preserved as optional metadata, never as the
182+sole readable record.
183+
184+This follows the session-portability principle that local applications should own
185+an intelligible transcript:
186+<https://earendil.com/posts/session-portability/>.
187+
188+### Distinct state boundaries
189+
190+The application should distinguish:
191+
192+1. **Session history** — the durable semantic record of what happened.
193+2. **Live run state** — waiting, streaming, running a tool, cancelled, or failed.
194+3. **Diagnostic events** — timings and implementation details used to investigate
195+ failures and stalls.
196+
197+The TUI and headless modes should be projections of the same application events.
198+Neither should own agent semantics or provider message conversion.
199+
200+### Transparent custom agents
201+
202+A custom agent should be a configuration over the same agent runtime, with at
203+least:
204+
205+- a name and description,
206+- model and reasoning effort,
207+- its own prompt,
208+- an allowed tool set.
209+
210+The main agent can invoke it through one explicit delegation tool. A delegated run
211+should have isolated context and durable lineage. The UI should show the selected
212+agent and model, current action, elapsed state, final result, and a directly
213+inspectable child transcript.
214+
215+The core should not automatically delegate work or hide child prompts and actions.
216+The existing Exa and adversary extensions are useful acceptance cases for the
217+extension API: one ordinary streaming tool and one tool backed by an isolated
218+agent.
219+
220+### TypeScript and runtime validation
221+
222+Bun and TypeScript remain the preferred implementation environment for vNext.
223+Changing language would discard too much validated provider, extension, and TUI
224+work without addressing the main product problems.
225+
226+TypeScript types should remain local and plain. Runtime schemas should be used at
227+actual trust boundaries such as settings, session records, extension manifests,
228+provider payloads, and tool arguments. A validation dependency should be selected
229+through a small trial against real boundary data, based on readable code, useful
230+errors, package maturity, dependency surface, and JSON Schema interoperability.
231+It should not spread schema-derived types through every internal operation.
232+
233+## TUI and conversation model decision spike
234+
235+Both major conversation models remain open:
236+
237+### Full-screen conversation
238+
239+Potential benefits:
240+
241+- completed and historical rows can be updated or expanded in place,
242+- overlays and rich navigation fit naturally,
243+- the application controls a consistent polished layout,
244+- tool calls and subagents can retain live structured rows.
245+
246+Costs to measure:
247+
248+- long histories require correct virtualization or another bounded rendering
249+ strategy,
250+- terminal-native selection and scrollback may be harder,
251+- resizing, alternate-screen recovery, and rendering bugs become application
252+ responsibilities,
253+- the UI can obscure activity if its state and event handling stall.
254+
255+### Append-only conversation with a bounded live region
256+
257+Potential benefits:
258+
259+- the terminal emulator owns durable scrollback, selection, and much scrolling,
260+- completed output does not need to be continuously rerendered,
261+- memory and rendering work can remain bounded,
262+- terminal history remains available naturally after the application exits.
263+
264+Costs to measure:
265+
266+- committed rows cannot be freely updated in place,
267+- in-flight tool and assistant output need a carefully bounded live area,
268+- overlays and navigation may interact awkwardly with scrollback,
269+- expanded details may need to be appended rather than toggled in place.
270+
271+### Spike method
272+
273+The decision should not be made from library preference or screenshots. Build
274+small disposable prototypes that replay the same deterministic recorded agent
275+events and provide the same editor and attachment interaction.
276+
277+The leading framework candidates are cel-tui and OpenTUI. OpenTUI deserves direct
278+evaluation because it powers OpenCode and provides Bun/TypeScript bindings, input,
279+textarea, scrolling, selection, code, and diff primitives:
280+
281+- <https://github.com/anomalyco/opentui>
282+- <https://opentui.com/>
283+
284+Adopting OpenTUI would not by itself reproduce OpenCode's UX. Its native runtime,
285+prebuilt artifacts, development pace, framework bindings, and supply-chain impact
286+must be evaluated. Retaining cel-tui must include the maintenance cost of any
287+library changes and the current specification/documentation workflow.
288+
289+Do not build every framework and conversation-model combination. Start with the
290+most natural implementation of each conversation model, use the same replay and
291+acceptance cases, and investigate a second implementation only where framework
292+behavior prevents a fair comparison.
293+
294+### Measurements
295+
296+Use a fixed corpus containing long text, reasoning, edits, large and rapidly
297+streaming tool output, failures, cancellations, images or attachment metadata,
298+and nested agent activity.
299+
300+Measure:
301+
302+- startup time,
303+- idle CPU usage,
304+- streaming CPU usage and render latency,
305+- memory use as history grows,
306+- terminal bytes written,
307+- responsiveness with a large history,
308+- scroll behavior and stick-to-bottom behavior,
309+- terminal-native text selection and copying,
310+- resize behavior,
311+- large paste and multiline editing behavior,
312+- overlay and draft preservation,
313+- terminal restoration after normal exit, cancellation, and injected failure,
314+- implementation size and conceptual complexity,
315+- required upstream or local TUI-framework changes,
316+- manual readability and sense of control during real use.
317+
318+For a full-screen design, the large-history test must exercise virtualization or
319+an equivalent bounded strategy. For an append-only design, it must demonstrate
320+that the live region remains correct while the terminal owns a large committed
321+history.
322+
323+Record the result in a short decision note containing evidence, rejected options,
324+and known costs. Spike code should not become production architecture merely
325+because it exists.
326+
327+## Context management for local models
328+
329+Small local context windows make context management a core behavior rather than a
330+late optimization.
331+
332+The initial policy should progress visibly through:
333+
334+1. bounded tool output with explicit omission metadata,
335+2. masking or digesting older observations,
336+3. readable client-controlled summaries with recorded lineage,
337+4. a clear context error when reduction is insufficient.
338+
339+Compaction should affect the provider request projection, not destroy durable
340+session history. Summaries should be inspectable and portable. Provider-side
341+opaque compaction must never be the only surviving representation.
342+
343+Context behavior should be tested with deliberately constrained 8k and 16k local
344+models and tool-heavy tasks, not inferred only from large hosted context windows.
345+
346+## Development path
347+
348+Progress is controlled by exit criteria rather than dates.
349+
350+### Stage 0: preserve and baseline
351+
352+- Commit the direction documents and current brain dump.
353+- Create an archive branch for the current main implementation.
354+- Record the exact archive branch name and commit.
355+- Preserve benchmark results and representative current UX behavior.
356+- Add only narrow local observability if needed to reproduce current stalls.
357+- Define a small set of end-to-end acceptance journeys.
358+
359+Exit when the current implementation can be restored exactly and vNext decisions
360+can be compared against a stable baseline.
361+
362+### Stage 1: decision spikes
363+
364+- Run the full-screen versus append/live TUI spike.
365+- Compare the leading TUI framework choices where necessary.
366+- Exercise a pi-ai-to-mini-coder event adapter with one local and one hosted model.
367+- Exercise the proposed append-only session format, including a truncated final
368+ write and a provider handoff.
369+- Trial runtime validation options against real settings, session, and extension
370+ data.
371+
372+Exit with short evidence-based decisions. Do not implement the whole product in
373+spike form.
374+
375+### Stage 2: walking vertical slice
376+
377+Build one usable path containing:
378+
379+- startup and settings,
380+- one local and one hosted provider path,
381+- normalized application events,
382+- a minimal system prompt,
383+- notepad-level input and file attachments,
384+- streaming assistant output,
385+- `bash`, `read`, and `edit`,
386+- unambiguous request and tool states,
387+- cancellation,
388+- append-only session persistence and resume,
389+- local diagnostics.
390+
391+Exit when this slice can complete and diagnose real coding tasks without hidden
392+stalls.
393+
394+At this point, decide whether continuing from the current source or replacing it
395+produces the smaller, clearer implementation. Reuse current authentication,
396+provider, argument, or tool code where it fits the new boundaries directly. Start
397+fresh where reuse would require parallel message models, compatibility state, or
398+continued coupling between provider, session, and TUI concerns.
399+
400+### Stage 3: UX quality
401+
402+- Complete the initial editor and attachment contract.
403+- Polish readable tool, reasoning, error, and cancellation presentation.
404+- Add settings UI with useful defaults.
405+- Harden scrolling, resizing, selection, terminal restoration, and long sessions.
406+- Keep advanced editing modes, history, and path completion deferred.
407+
408+Exit when regular dogfooding feels materially better than the published version.
409+
410+### Stage 4: local context and provider hardening
411+
412+- Add first-class Ollama and llama.cpp onboarding and diagnostics.
413+- Implement and expose context reduction stages.
414+- Run constrained-context local-model scenarios.
415+- Verify hosted-provider continuation and provider handoff.
416+
417+Exit when local support is genuinely a peer rather than a custom-provider example.
418+
419+### Stage 5: resources and extensions
420+
421+- Add root-to-leaf `AGENTS.md` and `CLAUDE.md` support.
422+- Add prompt templates and progressively disclosed skills.
423+- Add the narrow extension loader and API for tools, commands, and agents.
424+- Validate it with Exa and the adversary agent.
425+- Document extension development from the actual stable API.
426+
427+Exit when users can add those demonstrated behaviors without patching core.
428+
429+### Stage 6: release hardening
430+
431+- Add provider fixtures and contract tests.
432+- Add PTY and TUI tests plus a manual terminal matrix.
433+- Review dependency provenance, install scripts, updates, and locked versions.
434+- Define session migration and export behavior.
435+- Compare correctness, startup, resource use, and UX against the archived version.
436+- Dogfood local and hosted paths before publishing.
437+
438+Publish only when vNext is a better overall experience than the currently
439+published version.
440+
441+## Acceptance journeys
442+
443+The initial product decisions should be checked against a small stable set of
444+journeys rather than a large prose specification:
445+
446+1. A first-time local user reaches an Ollama or llama.cpp model without writing a
447+ verbose provider model object.
448+2. A hosted-provider user can authenticate, choose a model, and use the same agent
449+ and UI behavior.
450+3. A coding turn always exposes whether it is preparing, waiting for a provider,
451+ streaming, running a named tool, cancelled, failed, or complete.
452+4. A multiline prompt can be edited predictably, survives an opened and cancelled
453+ control, accepts a large paste, and includes text or image attachments.
454+5. A provider or rendering stall can be diagnosed from local logs without sending
455+ data elsewhere.
456+6. A long tool-heavy task on a constrained local context shows what was omitted or
457+ summarized while preserving the complete durable transcript.
458+7. A session can continue with another provider from readable local history.
459+8. Exa can be installed as a tool extension without core changes.
460+9. An adversary agent can be configured with its own prompt, model, effort, and
461+ tools; its actions and transcript remain inspectable.
462+10. A long conversation remains responsive and copyable under the chosen
463+ full-screen or append/live presentation model.
464+
465+## Documentation policy
466+
467+Avoid another comprehensive spec that duplicates implementation details.
468+Maintain only:
469+
470+- this product direction document,
471+- the original user feedback in `TODO.md`,
472+- focused acceptance journeys and tests,
473+- short decision records for expensive choices,
474+- extension and user documentation derived from working behavior.
475+
476+Do not prescribe detailed file trees, helper APIs, rendering sketches, or internal
477+state before they are implemented and verified.
478+
479+## Remaining decisions
480+
481+The next decisions should come from the Stage 1 spikes:
482+
483+- full-screen virtualized conversation or append-only conversation with a bounded
484+ live region,
485+- cel-tui, OpenTUI, or another choice justified by the spike evidence,
486+- reuse versus replacement of the current source,
487+- exact normalized session record and provider sidecar shape,
488+- runtime validation dependency,
489+- archive branch name and the commit at which vNext begins.