minima-cli 0.7.1__tar.gz → 0.8.0__tar.gz

{minima_cli-0.7.1 → minima_cli-0.8.0}/.gitignore

@@ -13,6 +13,10 @@ build/
 .minima_state/
 .seed_progress.json
 
+# Local experimental / throwaway files
+scratch/
+playground/
+
 
 # Astro docs site
 docs-site/node_modules/

{minima_cli-0.7.1 → minima_cli-0.8.0}/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to Minima are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] - 2026-07-06
+
+### Added (TUI)
+- **Fullscreen renderer (new default)** — alternate screen buffer with the prompt glued
+  to the bottom row, height-accurate transcript windowing, and in-app history scrolling
+  (mouse wheel / trackpad on by default; PgUp/PgDn always work). Opt out with
+  `--no-fullscreen` or `MINIMA_TUI_INLINE=1` for the classic inline renderer with native
+  terminal scrollback.
+- **Live current-action line** — while a tool runs, the footer shows what the agent is
+  doing right now (e.g. `⚙ bash: git diff --stat`), with `(+N more)` for parallel tools.
+- **New tools**: `question` (ask the user mid-run, never permission-gated),
+  `apply_patch` (multi-file add/update/delete/move), and Exa-backed `web_search` +
+  `web_fetch` (require `EXA_API_KEY`).
+- `--thinking LEVEL` is now actually applied (was parsed but ignored).
+- Busy indicator with rotating tips; thinking states renamed to `reasoning`/`running`.
+
+### Fixed (TUI)
+- **Esc / Ctrl+C abort a running turn** (was dead code behind the busy guard); a second
+  Ctrl+C within 2.5s force-quits even if a provider stream cannot be cancelled.
+- Plan mode (read-only) blocks `apply_patch` alongside write/edit/bash.
+- Live streaming region can never outgrow the viewport: over-budget final lines are
+  hard-sliced (fixes the fullscreen garble class and inline scrollback wipes).
+- `/fork` and `/clone` no longer claim fake success — they say they're not implemented.
+- glob/grep are permission-scoped as directory READS (`read from <dir>`) instead of
+  generic `run glob` prompts.
+
+### Changed (TUI)
+- **Permission denials are reframed for the model** ("the user declined … do not retry
+  the call and do not attempt the same action through other tools") — stops the
+  sandbox-spiral where models retry or work around a deliberate user decline.
+- Memory-recall block is annotated reference-only (do NOT run tools from recall).
+
 ## [0.7.1] - 2026-07-05
 
 ### Changed (API behavior — note for integrators)

{minima_cli-0.7.1 → minima_cli-0.8.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: install run test lint fmt live eval seed refresh-catalog tui-install tui-test tui-check tui-build tui tui-dev
+.PHONY: install run test lint fmt live eval seed refresh-catalog tui-install tui-test tui-check tui-build tui tui-dev tui-shot
 
 install:
 	uv sync --extra dev   # dev pulls server + reasoner extras for the full test suite
@@ -30,6 +30,9 @@ seed:
 
 TUI := packages/tui
 TUI_BIN := $(TUI)/dist/minima
+# Default PTY-capture spec: idle interactive UI at 100x30, run from the repo root so .env loads.
+# Emits a PNG to the gitignored playground/ so the rendered UI can be inspected as an image.
+SPEC ?= {"cmd":["bun","run","$(TUI)/src/cli/main.ts","--offline"],"cwd":"$(CURDIR)","cols":100,"rows":30,"duration":6,"png":"$(CURDIR)/playground/tui-shot.png"}
 
 tui-install:
 	cd $(TUI) && bun install
@@ -54,3 +57,11 @@ tui:
 # Run from source via Bun (no compile step) — fastest dev loop.
 tui-dev:
 	cd $(TUI) && bun run src/cli/main.ts $(ARGS)
+
+# Capture a text "screenshot" of the TUI in a real PTY (pyte emulator). No committed venv — uv pulls
+# pyte on demand. Override SPEC to size the terminal / send keystrokes; see the script's docstring:
+#   make tui-shot
+#   make tui-shot SPEC='{"cmd":["bun","run","packages/tui/src/cli/main.ts","--offline","--model","claude-haiku-4-5","--provider","anthropic"],"cwd":"'"$$PWD"'","cols":80,"rows":24,"duration":8,"steps":[{"after":2,"send":"hi<CR>"}]}'
+tui-shot:
+	@mkdir -p $(CURDIR)/playground
+	uv run --with pyte --with pillow python $(TUI)/scripts/pty_capture.py '$(SPEC)'

{minima_cli-0.7.1 → minima_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: minima-cli
-Version: 0.7.1
+Version: 0.8.0
 Summary: Minima CLI: cost-aware LLM model routing — recommend cheaper models, backed by Mubit memory.
 Project-URL: Homepage, https://docs.minima.sh
 Project-URL: Documentation, https://docs.minima.sh

minima_cli-0.8.0/docs/feature-gap-analysis.md

@@ -0,0 +1,190 @@
+# Feature Gap Analysis: minima vs. Claude Code, Codex CLI & OpenCode
+
+**Date:** 2026-07-02
+**Scope:** The minima **coding agent** (`src/minima_harness/`, the `minima` CLI/TUI, v0.5.0 "Beta"). The routing service in `src/minima/` is minima's wedge, not the comparison surface.
+**Comparators:** Claude Code (Anthropic), Codex CLI (OpenAI), OpenCode (open source).
+**Goal:** Rank the features these three have that minima lacks, by **popularity/usability**, **time to build**, and **compatibility with minima's architecture**.
+
+---
+
+## How to read this
+
+- **Popularity / Usability (1–5):** How strongly users expect the feature in 2026. 5 = table-stakes.
+- **Build effort:** Engineer-days for a first solid version, with a T‑shirt size. *Lower is better.*
+- **Compatibility (1–5):** How cleanly it slots into minima's existing architecture (tools system, routing loop, session store, extensions). 5 = drop-in / synergistic.
+- **Priority rank:** My recommended build order, balancing all three. High value + low effort + high fit floats to the top; a couple of high-effort items still rank high because they are table-stakes.
+
+The ranking is a recommendation, not a formula output — the numeric columns are there so you can re-weight if your priorities differ (e.g., if enterprise security matters more, sandboxing jumps up).
+
+---
+
+## Executive summary
+
+Minima's coding agent is a competent port of the PI agent toolkit with a **genuinely differentiated core**: cost-aware model routing across a large multi-provider pool, memory-backed learning from realized outcomes, and per-turn/per-goal cost tracking. Nothing in the comparators matches that wedge.
+
+But on the *table-stakes agent surface*, it trails all three comparators in a few specific, high-visibility places. The biggest gaps, in order: **MCP support** (all three have it; minima has none), **sub-agents** (all three; minima is single-agent), **LSP feedback** (OpenCode's marquee feature; minima scaffolded then deleted it), **web search/fetch** (Claude Code + Codex; minima has none), and **plan mode** (all three; minima has a `# TODO` where it should be).
+
+The good news: several of these are cheap because minima already has the substrate — the tools system, the routing/judge loop, image plumbing, and `/compact` all exist. Five of the top seven items are days-scale, not weeks-scale.
+
+### Top-15 ranked table
+
+| # | Feature (minima lacks) | Who has it | Popularity/Usability | Build effort | Compatibility | Notes / minima synergy |
+|---|---|---|:--:|---|:--:|---|
+| 1 | **MCP client support** | CC, Codex, OC | 5 | ~5–8d (**M**) | 5 | Table-stakes ecosystem. MCP tools map onto the existing tool interface; routing treats them as more tools. |
+| 2 | **Web search / fetch tool** | CC, Codex | 5 | ~2–3d (**S**) | 5 | Two new builtin tools over a search API. Highest ROI after image input. |
+| 3 | **Expose image/vision input** | Codex | 4 | ~1–2d (**XS**) | 5 | Already plumbed end-to-end (`ai/types.py:ImageContent`, all 3 providers); only the TUI attach path is missing. Fastest win in the doc. |
+| 4 | **Plan mode (read-only)** | CC, Codex, OC | 5 | ~3–4d (**S**) | 5 | `ROUTE_MODES=("auto","confirm")` + tool gating exist; the plan/act split is already a documented **"Phase‑3"** item (`app.py:98`) — design intent exists, de-risking the build. |
+| 5 | **Automatic context compaction** | CC | 4 | ~2–3d (**S**) | 5 | Notice site (`app.py:945`) + reusable `summarize()` both exist; wire an auto-trigger there. |
+| 6 | **`/review` code-review command** | Codex | 4 | ~2–3d (**S**) | 5 | Diff vs. base/commit → review prompt routed to a strong model. Pure reuse of git(bash)+routing. |
+| 7 | **Sub-agents / multi-agent** | CC, Codex, OC | 5 | ~8–15d (**L**) | 4 | Biggest *differentiation* opportunity: route **each subagent independently to the cheapest capable model**. No competitor does cost-routed fan-out. |
+| 8 | **LSP integration (re-add)** | OC | 4 | ~8–12d (**L**) | 4 | Feeds compiler diagnostics back into the loop → sharper quality/judge signal → strengthens minima's feedback thesis. Was scaffolded (`lsp/` now stale `.pyc` only). |
+| 9 | **Filesystem checkpoints / rewind** | CC, OC (undo), Codex (git) | 5 | ~6–10d (**M/L**) | 4 | Session tree branches *conversations*; extend to snapshot *files* per turn + restore. |
+| 10 | **Dedicated git integration** | CC, Codex, OC | 4 | ~3–5d (**S/M**) | 4 | Status/diff/branch awareness in context + optional auto-commit. Today git is bash-only. |
+| 11 | **Best-of-N / parallel attempts** | Codex (`--attempts`) | 3 | ~4–6d (**M**) | 5 | Natural fit: judge + routing already exist. Run N candidates across models, judge, pick. A routing differentiator. |
+| 12 | **Sandboxing (OS-level)** | CC, Codex | 4 | ~10–15d (**L/XL**) | 3 | bash runs with full user perms today. Platform-specific (seatbelt/landlock/container). Enterprise value. |
+| 13 | **Session sharing (`/share`)** | OC | 3 | ~5–8d (**M**) + infra | 3 | Needs a hosting backend — Mubit could host it (synergy), otherwise heavy. |
+| 14 | **IDE integrations (VS Code/JetBrains)** | CC, Codex, OC | 5 | ~20–40d (**XL**) | 2 | High demand but a whole new product surface; needs an exposed agent server protocol. |
+| 15 | **Desktop / web app** | CC, OC | 4 | ~25–40d (**XL**) | 2 | Long-term; large surface, low reuse of the TUI. |
+
+**Micro-wins (do opportunistically, each < 1 day):** fuzzy `@`-file picker (Codex has autocomplete; minima's `@path` only inlines a known path), external prompt editor via `$EDITOR`/Ctrl+G (Codex), shell completions (`codex completion …`), `/copy` of last output (minima has `/copy`+`/export` already — mostly covered).
+
+---
+
+## Recommended roadmap (sequenced)
+
+**Sprint 1 — Quick wins (≈2 weeks, all days-scale, high visibility):**
+`#3 image input` → `#2 web search/fetch` → `#4 plan mode` → `#5 auto-compaction` → `#6 /review`. These close five obvious "why doesn't it do X" gaps for ~10–16 engineer-days total and touch only the tools/TUI/route-mode layers.
+
+**Sprint 2 — Table-stakes core (≈2 weeks):**
+`#1 MCP client` (the single most important gap; unlocks the whole external-tool ecosystem) + `#10 git integration`.
+
+**Sprint 3 — Strategic differentiators (≈4–6 weeks):**
+`#7 cost-routed sub-agents` and `#8 LSP re-add`. These are the two places where minima's wedge (routing + outcome feedback) turns a copied feature into a *better* feature. Add `#11 best-of-N` and `#9 checkpoints` as they fit.
+
+**Backlog / heavy bets:** `#12 sandboxing`, `#13 sharing`, `#14 IDE`, `#15 desktop/web`.
+
+---
+
+## Detail & build notes
+
+### Tier 1 — Quick wins
+
+- **Image/vision input (#3).** The hard part is done: `ImageContent(data: base64, mime_type)` is fully defined (`ai/types.py:104`) and all three providers (`anthropic-messages`, `google-generative-ai`, `openai-completions`) already serialize images. Missing: a user path to attach one — `editor.py:21` only inline-expands *text* `@path`. Add a `-i/--image` CLI flag and a paste/`@image.png` route that builds an `ImageContent` and injects it. ~1–2 days.
+- **Web search / fetch (#2).** Append two `AgentTool`s to `default_toolset()` (`tools/builtin.py:13`) backed by a search API (Brave/Tavily/Exa) or provider-native grounding. Minima already routes to web-grounded models (Perplexity Sonar) but has no tool. ~2–3 days.
+- **Plan mode (#4).** `ROUTE_MODES = ("auto","confirm")` at `app.py:99`; the plan/act split is explicitly deferred to "Phase‑3" in the comment at `app.py:98`, and tool gating (`-nt`, `--exclude-tools`) already exists. Add a read-only mode that restricts to `read/grep/find/ls`, produces a plan, and gates execution behind approval. ~3–4 days. (Team roadmap intent already documented — lower design risk.)
+- **Auto-compaction (#5).** The trigger site already exists: `app.py:945` shows `"context near limit — /compact to free space"` today, and `summarize(messages, model, *, instructions="")` (`tui/compaction.py:8`) is a clean reusable async fn. Auto-compaction = call `summarize()` at that notice point instead of just warning. ~2–3 days (revised down from 4 — the hook and summarizer both exist).
+- **`/review` (#6).** A slash command that diffs against a base branch / uncommitted changes (git via bash), builds a review prompt, and routes it to a strong model. Pure reuse. ~2–3 days.
+
+### Tier 2 — Table-stakes core
+
+- **MCP client (#1).** The highest-impact gap: all three comparators support MCP; minima has neither client nor server (grep-confirmed absent). Implement a stdio + streamable-HTTP client, register discovered tools into the existing tool registry, and add config. Because minima's tool interface is already pluggable (extensions register tools today), MCP tools slot in cleanly and are automatically eligible for routing/permissions. ~5–8 days. (A `codex mcp-server`-style server that exposes minima *as* an MCP tool is a separate, later item.)
+- **Git integration (#10).** Surface `git status`/diff/branch into context, be gitignore-aware, optionally offer auto-commit with generated messages. ~3–5 days.
+
+### Tier 3 — Strategic differentiators (lean into the wedge)
+
+- **Cost-routed sub-agents (#7).** All three comparators spawn subagents; **none route each subagent to the cheapest capable model.** Minima can: a spawn tool + isolated context + result synthesis, with every child going through the recommend→judge→feedback loop. This makes "fan out 5 agents" measurably cheaper and is a story no competitor can tell. The loop is already anyio-parallel, so concurrency isn't from scratch. ~8–15 days.
+- **LSP re-add (#8).** OpenCode's headline feature: feed compiler diagnostics back after each edit so the model self-corrects. This is *directly aligned* with minima's outcome-feedback thesis — diagnostics become a quality signal for the judge and for routing feedback. Source was scaffolded and deleted (`lsp/` and `tests/harness/lsp/` hold only stale `.pyc`), so prior design exists to mine. ~8–12 days.
+- **Best-of-N routing (#11).** Codex Cloud has `--attempts` (1–4). Minima already has a judge and multi-model routing — run N candidates across models, judge, select the winner, and log outcomes. A routing-native version of a known feature. ~4–6 days.
+- **Checkpoints / rewind (#9).** Users expect an undo net (Claude Code rewind, OpenCode undo/redo). Snapshot touched files per turn and restore on request; integrate with the existing session tree so a rewind can branch conversation *and* files together. ~6–10 days.
+
+### Tier 4 — Heavy / long-term
+
+- **Sandboxing (#12):** OS-level isolation for `bash` (seatbelt on macOS, landlock/seccomp on Linux, or containers). Real enterprise value but platform-specific and invasive. ~10–15 days.
+- **Session sharing (#13):** `/share` link. Needs a hosting backend — a natural thing for Mubit to host, otherwise expensive. ~5–8 days + infra.
+- **IDE integrations (#14) / Desktop-web app (#15):** New product surfaces requiring an exposed agent server protocol; high demand, weeks-to-months of work, low reuse of the current TUI.
+
+---
+
+## What minima already matches (not gaps)
+
+So this doesn't read as "behind on everything" — minima is at parity or ahead here:
+
+- **Slash commands** (~37), **skills** (Agent Skills standard + Mubit skills), **prompt templates** as `/commands`, **custom commands** — parity.
+- **Hooks/extensibility:** Python extensions register tools/commands/event hooks (`text`/`tool_start`/`tool_end`/`turn`/`finish`) + a git-based **package manager** (`minima install <git-url>`) — comparable to plugins.
+- **Permissions/approval modes:** PermissionRequest modal, always-allow, `/yolo`, `--dangerously-skip-permissions`, `/edits` forced diff review — parity (minus sandboxing).
+- **Headless/scripting:** `--print` and `--mode json` event stream — matches `codex exec` / `claude -p`.
+- **Sessions:** append-only JSONL session **tree** with continue/resume/fork/clone/branch + goals that survive resume — arguably *ahead* of the comparators on branching.
+- **Themes, keybinds, mouse select+copy, `/export` to Markdown, diff preview, `/stats`+`/cost` analytics** — parity or better on cost analytics.
+- **Multi-provider:** Anthropic, Google, and an OpenAI-compatible path covering OpenAI/OpenRouter/Groq/Together/Fireworks/DeepInfra/Cerebras/DeepSeek/Mistral/xAI/Perplexity, etc. — **plus first-class local-runtime specs for Ollama, LM Studio, vLLM, llama.cpp, and LocalAI** (`ai/provider_catalog.py:110–124`, no API key required, e.g. Ollama at `localhost:11434/v1`). This is *ahead* of most comparators on local-runtime breadth. *(Corrected in iteration 5 — the initial inventory wrongly reported no local provider.)*
+
+## Minima's unique wedge (protect and lean into)
+
+No comparator has: **cost-aware routing across a large candidate pool**, **memory-backed learning from realized outcomes** (`/recall`, `/optimize`, learned lessons), and **cost/budget tracking** (est-vs-actual-vs-baseline savings %, budgeted `/ledger` goals). The strategic read: build the table-stakes gaps to remove reasons *not* to use minima, but make sub-agents, best-of-N, and LSP feedback **routing-native** so the copied features are cheaper/smarter than the originals.
+
+---
+
+## Validation notes (iteration 2 — 2026-07-02)
+
+The Tier‑1 estimates were re-checked against source (not just inferred from the inventory). All held; a couple were revised down because the reuse points exist:
+
+| Claim | Verified against | Result |
+|---|---|---|
+| Image plumbed but not exposed | `ai/types.py:104` (`ImageContent(data:base64, mime_type)`), `editor.py:21` (text-only `@path`) | ✅ Confirmed — only the TUI attach path is missing. |
+| Plan mode absent, scaffold exists | `app.py:98–99` (`ROUTE_MODES=("auto","confirm")`, "Phase‑3 plan/act split" comment) | ✅ Confirmed — and it's already on the team roadmap. |
+| Auto-compaction absent | `app.py:945` (warn-only notice), `_compact` at `app.py:1226`, reusable `summarize()` at `compaction.py:8` | ✅ Confirmed — **estimate revised 2–4d → 2–3d** (hook + summarizer exist). |
+| Web search/fetch absent | grep across `src/minima_harness/` (empty); `default_toolset()` at `tools/builtin.py:13` is the clean insertion point | ✅ Confirmed absent, insertion point trivial. |
+| MCP absent | grep across `src/minima_harness/` (empty) | ✅ Confirmed absent (client and server). |
+
+### Tier‑2/3 validation (iteration 3 — 2026-07-02)
+
+Source-checked the expensive roadmap-driving items. All estimates held; compatibility claims confirmed, with sharpened risk notes:
+
+| Item | Verified against | Result / refinement |
+|---|---|---|
+| MCP client (#1, ~5–8d, fit 5) | `AgentTool` dataclass (`agent/tools.py:42`: `name`/`description`/`parameters: type[BaseModel]`/async `execute`); extensions already register `AgentTool`s dynamically (`extensions.py:30`) | ✅ Fit confirmed. The **one real risk** is bridging MCP's JSON-Schema tool params → a pydantic model (`pydantic.create_model` or a passthrough model). Everything else is wiring. |
+| Cost-routed sub-agents (#7, ~8–15d, fit 4) | `agent_loop(...)` is a plain async fn over explicit `AgentState`/`AgentLoopConfig` (`loop.py:48`); tool exec already parallel via `anyio.create_task_group()` (`loop.py:245`) | ✅ Nesting a child loop is clean (no global refactor); concurrency primitives exist. The cost-routing-per-child synergy is real — each child re-enters the same runtime. |
+| LSP re-add (#8, ~8–12d, fit 4) | Only `.pyc` survives (`lsp/__pycache__/` client+manager+protocol + compiled tests); no `.py` source | ✅ Estimate holds. Module split is a **design hint only** — py3.14 decompilers are immature, so don't count on recovering the deleted code. |
+| Checkpoints/rewind (#9, ~6–10d, fit 4) | `SessionStore` is a conversation DAG (`store.py`: `append`/`set_tip`/`fork_to`/`path_to`), not file state | ✅ Estimate holds; **refinement:** the DAG is a clean anchor for rewind, but the per-turn **file-snapshot layer is net-new** (fit is really 3–4). |
+| Git integration (#10, ~3–5d, fit 4) | No dedicated git code (bash-only); context assembled in `tui/context.py` | ✅ Pure context injection (shell out to git, summarize into context) + optional auto-commit. Low risk. |
+
+Tier‑4 items (sandboxing, sharing, IDE, desktop/web) remain first-pass — deliberately, as they're backlog.
+
+---
+
+## Changelog refresh (iteration 4 — 2026-07-02)
+
+Swept the **June–July 2026** changelogs to keep the gap list current. Net: the existing top gaps got *reinforced* (the bar rose), a few new candidates appeared, and — notably — a competitor started copying minima's wedge.
+
+**Existing gaps reinforced (the bar moved):**
+- **Sub-agents (#7):** Claude Code now ships **nested sub-agents (3-level depth)**, `fallbackModel` chains, and background-subagent permission prompts routed to the main session. The expectation moved from "has subagents" to "has *nested, resilient* subagents" — which makes minima's cost-routed-fan-out angle more valuable, not less.
+- **MCP (#1):** now table-stakes-plus — Claude `claude mcp login/logout`, Codex smarter MCP tool-search, OpenCode MCP OAuth + refresh tokens + resource autocomplete. Minima is still at zero; this remains the #1 gap.
+- **Checkpoints/rewind (#9):** Claude `/rewind` can now restore from *before* `/clear` was run.
+- **Web search (#2):** Codex added an **indexed mode** (live search but restricted to server-approved URLs) — a safer default worth copying when minima builds this.
+
+**New candidate gaps (June 2026):**
+
+| Candidate | Who shipped it | Pop. | Effort | Fit | Where it slots |
+|---|---|:--:|---|:--:|---|
+| Test-runner auto-detection + run | OpenCode (cargo/uv/bun/dotnet) | 3 | ~2–3d (**S**) | 5 | Confirmed absent in minima (no in-agent test integration; bash-only). A tool/context add that routes a "run tests" action. Tier-1-sized quick win. |
+| Mobile / remote control | Codex Remote GA (QR pairing), CC remote | 4 | ~20–40d (**XL**) | 2 | New surface (server + device pairing). Backlog, alongside IDE. |
+| Org/admin policy controls (default model, governance) | Claude Code org defaults | 2–3 | ~5–8d (**M**) | 3 | Enterprise/team governance. Backlog. |
+
+*Dropped candidate (iteration 5):* "first-class Ollama support" — **minima already has it** (see parity list below). OpenCode's only edge here is *optimized* local streaming (Ollama streaming v2, ~−40% first-token latency) — a minor perf item, not a feature gap.
+
+**Already at parity with newly-shipped features (no action needed):**
+- OpenCode just added a **yolo mode** to auto-approve permissions — minima has `/yolo` + `--dangerously-skip-permissions` already.
+- OpenCode's `--session` transcript pinning — minima has `--session` **plus** a full session tree.
+- **Local models** — OpenCode/Ollama focus notwithstanding, minima ships first-class specs for Ollama, LM Studio, vLLM, llama.cpp, and LocalAI (`ai/provider_catalog.py:110–124`). Minima is ahead here on breadth; the only competitor edge is streaming latency tuning.
+- **Codex just shipped "rollout token budgets" that abort a turn when exhausted** — a step *toward* minima's existing cost/budget wedge (`/ledger` budgeted goals, per-turn est-vs-actual-vs-baseline savings). Signal: the market is moving toward minima's differentiator. **Suggested move:** add a hard budget-abort to `/ledger` to stay a step ahead of where Codex just landed.
+
+---
+
+## Sources
+
+- Claude Code — [25 Features Guide 2026 (MarkTechPost)](https://www.marktechpost.com/2026/06/14/claude-code-guide-2026-25-features-with-examples-demo/), [Subagents docs](https://code.claude.com/docs/en/sub-agents), [Hooks/Subagents/Skills guide](https://ofox.ai/blog/claude-code-hooks-subagents-skills-complete-guide-2026/)
+- Codex CLI — [Features](https://developers.openai.com/codex/cli/features), [CLI docs](https://developers.openai.com/codex/cli), [Changelog](https://developers.openai.com/codex/changelog), [Codex as MCP server](https://codex.danielvaughan.com/2026/05/12/codex-cli-agents-sdk-mcp-server-multi-agent-workflows/)
+- OpenCode — [Docs / intro](https://opencode.ai/docs/), [GitHub](https://github.com/opencode-ai/opencode), [Developer guide 2026](https://www.developersdigest.tech/blog/opencode-developer-guide-2026)
+- June–July 2026 changelogs — [Codex changelog](https://developers.openai.com/codex/changelog), [Codex June 2026 recap](https://www.developersdigest.tech/blog/codex-changelog-june-2026), [Claude Code what's new](https://code.claude.com/docs/en/whats-new), [Claude Code June 2026 features](https://www.sitepoint.com/claude-code-june-2026-10-new-features-devs-need-to-know/), [OpenCode changelog](https://opencode.ai/changelog)
+- minima — codebase inventory (`src/minima_harness/`), `docs/harness.md`, `README.md`
+
+*Build estimates assume one engineer familiar with the codebase. Tier‑1 through Tier‑3 estimates have been source-validated (see Validation notes); Tier‑4 remains first-pass by design.*
+
+---
+
+## Revision history
+
+- **Iteration 1** — Initial report: minima feature inventory + competitor research → ranked 15-item gap table + 3-sprint roadmap.
+- **Iteration 2** — Source-validated Tier‑1 estimates; revised auto-compaction down (2–4d → 2–3d).
+- **Iteration 3** — Source-validated Tier‑2/3 estimates (MCP JSON-Schema bridge risk, clean sub-agent nesting, LSP `.pyc`-only remnants, net-new checkpoint file layer).
+- **Iteration 4** — June–July 2026 changelog refresh: reinforced gaps, new candidates, and the signal that Codex is converging on minima's cost-budget wedge.
+- **Iteration 5** — Validated new candidates; **corrected a factual error** — minima already ships first-class local-runtime providers (Ollama/LM Studio/vLLM/llama.cpp/LocalAI); confirmed test-runner detection is a genuine gap. Report considered complete.

{minima_cli-0.7.1 → minima_cli-0.8.0}/packages/tui/README.md

@@ -44,6 +44,24 @@ Tests are fully hermetic: the client injects a mock `fetch`, the faux provider s
 LLM replies, and the Minima integration runs the full loop against an in-process mock
 service — no network, no keys.
 
+### Screenshot the TUI
+
+To inspect the layout as a "screenshot", drive the TUI in a real PTY with `scripts/pty_capture.py`
+(pyte emulator; no committed venv — `uv` pulls pyte/pillow on demand):
+
+```bash
+# from the repo root (so .env / .env.harness load):
+make tui-shot                                  # idle UI at 100x30 -> playground/tui-shot.png
+make tui-shot SPEC='{"cmd":["bun","run","packages/tui/src/cli/main.ts","--offline","--model","claude-haiku-4-5","--provider","anthropic"],"cwd":"'"$PWD"'","cols":80,"rows":24,"duration":8,"png":"'"$PWD"'/playground/shot.png","steps":[{"after":4,"send":"hi"},{"after":6,"send":"<CR>"}]}'
+```
+
+It prints the visible grid plus the **scrollback** (lines that scrolled off the top), and — when the
+spec has a `"png"` key — rasterizes the visible grid (colors/bold, Menlo font) to a **PNG image** you
+can open. Verifies "prompt at the bottom / clean render / scroll"; true wheel/trackpad scrolling is a
+real-terminal, human check. Tips: give Ink ~4s to warm up and send the prompt text and `<CR>` as
+separate `steps`. See the script's docstring for the full JSON spec and send-tokens
+(`<CR> <UP> <PGUP> <CTRLC> …`).
+
 ## Use
 
 ```bash

{minima_cli-0.7.1 → minima_cli-0.8.0}/packages/tui/bun.lock

@@ -10,6 +10,7 @@
         "@mubit-ai/sdk": "^0.10.0",
         "ink": "^5.0.0",
         "react": "^18.3.0",
+        "string-width": "^7.2.0",
       },
       "devDependencies": {
         "@biomejs/biome": "^1.9.0",

{minima_cli-0.7.1 → minima_cli-0.8.0}/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minima-tui",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Minima harness + TUI — the `minima` CLI (TypeScript/Ink; successor to the removed Python harness). Talks to the Python FastAPI recommender service over the /v1/* contract.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -32,7 +32,8 @@
     "@google/genai": "^0.3.0",
     "@mubit-ai/sdk": "^0.10.0",
     "ink": "^5.0.0",
-    "react": "^18.3.0"
+    "react": "^18.3.0",
+    "string-width": "^7.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",

minima_cli-0.8.0/packages/tui/scripts/pty_capture.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Capture a "screenshot" of the Minima TUI by driving it in a real PTY.
+
+The TUI is an Ink/React app that renders inline in the terminal's MAIN screen buffer and commits
+its finalized transcript to native scrollback via <Static>. A fixed-grid emulator alone can't show
+that scrollback, so this uses pyte's HistoryScreen: the visible grid is the "screen", and lines that
+scroll off the top land in history — which is exactly how we verify the transcript is scrollable.
+
+Usage:
+    uv run --with pyte python packages/tui/scripts/pty_capture.py '<json-spec>'
+
+Spec (JSON):
+    {
+      "cmd": ["bun", "run", "src/cli/main.ts", "--offline"],  # argv (required)
+      "cwd": "/path/to/repo",        # optional; set to the repo root so .env(.harness) load
+      "cols": 100, "rows": 30,       # terminal size (default 80x24)
+      "duration": 8,                 # seconds to run before SIGKILL (default 8)
+      "show_history": true,          # also print scrollback above the screen (default true)
+      "steps": [                     # timed keystrokes; "send" supports the tokens below
+        {"after": 2.0, "send": "hello"},
+        {"after": 3.0, "send": "<CR>"}
+      ]
+    }
+
+Send tokens: <ESC> <CR> <ENTER> <TAB> <UP> <DOWN> <LEFT> <RIGHT> <PGUP> <PGDN> <BS>
+             <CTRLC> <CTRLL> <CTRLP> <CTRLR> <SPACE>
+
+Notes:
+  - A present CI env var (even empty) flips Ink into non-interactive mode, so it is stripped.
+  - The child is SIGKILLed at `duration` (before it can emit its exit sequences), so the last Ink
+    paint stays on the emulated grid.
+  - pyte models a fixed grid + scrollback; it proves "prompt at the bottom / no void / clean render /
+    lines in scrollback". True wheel/trackpad scrolling is a real-terminal, human check.
+"""
+import fcntl
+import json
+import os
+import select
+import signal
+import struct
+import subprocess
+import sys
+import termios
+import time
+
+import pyte
+
+TOKENS = {
+    "<ESC>": "\x1b", "<CR>": "\r", "<ENTER>": "\r", "<TAB>": "\t",
+    "<UP>": "\x1b[A", "<DOWN>": "\x1b[B", "<LEFT>": "\x1b[D", "<RIGHT>": "\x1b[C",
+    "<PGUP>": "\x1b[5~", "<PGDN>": "\x1b[6~", "<BS>": "\x7f",
+    "<CTRLC>": "\x03", "<CTRLL>": "\x0c", "<CTRLP>": "\x10", "<CTRLR>": "\x12",
+    "<SPACE>": " ",
+}
+
+
+def expand(s: str) -> bytes:
+    for k, v in TOKENS.items():
+        s = s.replace(k, v)
+    return s.encode()
+
+
+def render_row(row, cols: int) -> str:
+    """A pyte row (sparse column->Char mapping) as a plain string, trailing space trimmed."""
+    return "".join(row[x].data for x in range(cols)).rstrip()
+
+
+# pyte's 16 ANSI color names -> RGB. Note pyte uses "brown" for SGR 33 (not "yellow"),
+# and 256/truecolor come through as "RRGGBB" hex strings handled in _resolve().
+_PALETTE = {
+    "black": (0, 0, 0), "red": (194, 54, 33), "green": (37, 188, 36),
+    "brown": (173, 173, 39), "blue": (73, 46, 225), "magenta": (211, 56, 211),
+    "cyan": (51, 187, 200), "white": (203, 204, 205),
+    "brightblack": (129, 131, 131), "brightred": (252, 57, 31),
+    "brightgreen": (49, 231, 34), "brightbrown": (234, 236, 35),
+    "brightblue": (88, 51, 255), "brightmagenta": (249, 53, 248),
+    "brightcyan": (20, 240, 240), "brightwhite": (233, 235, 235),
+}
+_DEFAULT_FG = (205, 205, 205)
+_DEFAULT_BG = (13, 13, 13)
+
+
+def _resolve(color: str, default):
+    if color == "default":
+        return default
+    if color in _PALETTE:
+        return _PALETTE[color]
+    try:  # 256/truecolor arrive as "RRGGBB" hex
+        return (int(color[0:2], 16), int(color[2:4], 16), int(color[4:6], 16))
+    except (ValueError, IndexError):
+        return default
+
+
+def render_png(screen, path: str, font_size: int = 18) -> None:
+    """Rasterize the visible pyte grid (with colors/bold/reverse) to a PNG via Pillow + Menlo, so a
+    reader can visually inspect the TUI. Requires pillow (`uv run --with pillow`)."""
+    import unicodedata
+
+    from PIL import Image, ImageDraw, ImageFont
+
+    font_path = "/System/Library/Fonts/Menlo.ttc"
+    regular = ImageFont.truetype(font_path, font_size, index=0)
+    bold = ImageFont.truetype(font_path, font_size, index=1)
+    ascent, descent = regular.getmetrics()
+    cw = int(round(regular.getlength("M")))  # monospace advance width
+    ch = ascent + descent  # cell height
+    cols, rows = screen.columns, screen.lines
+
+    img = Image.new("RGB", (cols * cw, rows * ch), _DEFAULT_BG)
+    d = ImageDraw.Draw(img)
+    for y in range(rows):
+        line = screen.buffer[y]  # defaultdict; indexing empty cells returns default_char
+        x = 0
+        while x < cols:
+            c = line[x]
+            fg = _resolve(c.fg, _DEFAULT_FG)
+            bg = _resolve(c.bg, _DEFAULT_BG)
+            if c.reverse:
+                fg, bg = bg, fg
+            wide = 2 if (c.data and unicodedata.east_asian_width(c.data[0]) in "WF") else 1
+            px, py = x * cw, y * ch
+            if bg != _DEFAULT_BG:
+                d.rectangle([px, py, px + cw * wide - 1, py + ch - 1], fill=bg)
+            if c.data and c.data != " ":
+                d.text((px, py), c.data, font=(bold if c.bold else regular), fill=fg)
+            x += wide
+    img.save(path, "PNG")
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: pty_capture.py '<json-spec>'", file=sys.stderr)
+        return 2
+    spec = json.loads(sys.argv[1])
+    rows = spec.get("rows", 24)
+    cols = spec.get("cols", 80)
+    duration = spec.get("duration", 8)
+    steps = spec.get("steps", [])
+    show_history = spec.get("show_history", True)
+
+    master, slave = os.openpty()
+    fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+    env = dict(os.environ)
+    env["TERM"] = "xterm-256color"
+    env["COLUMNS"] = str(cols)
+    env["LINES"] = str(rows)
+    env.pop("CI", None)  # a present CI var (even empty) flips Ink into non-interactive mode
+
+    p = subprocess.Popen(
+        spec["cmd"], stdin=slave, stdout=slave, stderr=slave,
+        env=env, cwd=spec.get("cwd"), close_fds=True, preexec_fn=os.setsid,
+    )
+    os.close(slave)
+
+    start = time.time()
+    sent = [False] * len(steps)
+    raw = bytearray()
+    while time.time() - start < duration:
+        now = time.time() - start
+        for i, s in enumerate(steps):
+            if not sent[i] and now >= s["after"]:
+                os.write(master, expand(s["send"]))
+                sent[i] = True
+        r, _, _ = select.select([master], [], [], 0.1)
+        if r:
+            try:
+                data = os.read(master, 65536)
+            except OSError:
+                break
+            if not data:
+                break
+            raw += data
+
+    try:
+        os.killpg(os.getpgid(p.pid), signal.SIGKILL)
+    except Exception:
+        pass
+
+    # Feed the full accumulated stream once (robust vs. escapes split across reads). HistoryScreen
+    # keeps lines that scrolled off the top in `history.top` — that is the native scrollback.
+    screen = pyte.HistoryScreen(cols, rows, history=5000, ratio=0.5)
+    pyte.ByteStream(screen).feed(bytes(raw))
+
+    if show_history and screen.history.top:
+        hist = list(screen.history.top)
+        print(f"=== SCROLLBACK ({len(hist)} lines above the screen) ===")
+        for idx, row in enumerate(hist):
+            print(f"h{idx:03} |{render_row(row, cols)}")
+
+    print(f"=== SCREEN {cols}x{rows} (visible) ===")
+    for idx, line in enumerate(screen.display):
+        print(f"{idx:2} |{line.rstrip()}")
+    print(f"=== {len(screen.display)} visible rows; {len(screen.history.top)} in scrollback ===")
+
+    png = spec.get("png")
+    if png:
+        render_png(screen, png)
+        print(f"=== wrote PNG: {png} ===")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{minima_cli-0.7.1 → minima_cli-0.8.0}/packages/tui/src/ai/providers/anthropic.ts

@@ -48,7 +48,10 @@ const EPHEMERAL = { type: "ephemeral" };
 /** Minimal client shape this provider consumes; the real SDK client satisfies it. */
 export interface AnthropicClientLike {
   messages: {
-    stream(opts: Record<string, unknown>): AsyncIterable<AnthropicStreamEvent>;
+    stream(
+      opts: Record<string, unknown>,
+      requestOptions?: { signal?: AbortSignal },
+    ): AsyncIterable<AnthropicStreamEvent>;
   };
 }
 export interface AnthropicStreamEvent {
@@ -85,7 +88,9 @@ export class AnthropicProvider {
 
     yield startEv(assistant);
     try {
-      const s = client.messages.stream(kwargs);
+      // Forward the abort signal so Esc/Ctrl+C actually cancels the in-flight request — without
+      // it, agent.abort() sets the flag but the SDK keeps streaming to completion.
+      const s = client.messages.stream(kwargs, { signal: opts.signal });
       for await (const ev of s) {
         const etype = ev.type;
         if (etype === "message_start") {
@@ -190,7 +195,7 @@ export class AnthropicProvider {
  * SDK expects milliseconds. Passing seconds through gave every request a 30-60ms
  * deadline: all Claude calls died with "Request timed out". */
 export function sdkTimeoutMs(options: Record<string, unknown>): number {
-  return Math.round(((options.timeout as number) ?? 60) * 1000);
+  return Math.round(Number(options.timeout ?? 60) * 1000);
 }
 
 async function buildClient(options: Record<string, unknown>): Promise<AnthropicClientLike> {

{minima_cli-0.7.1 → minima_cli-0.8.0}/packages/tui/src/ai/providers/google.ts

@@ -100,6 +100,9 @@ export class GoogleProvider {
 
     try {
       const contents = toContents(context);
+      // NOTE: @google/genai 0.3.x exposes no abortSignal on generateContentStream, so opts.signal
+      // cannot cancel an in-flight Gemini stream here (unlike the Anthropic/OpenAI providers).
+      // Abort still stops the multi-turn loop between turns; mid-stream cancellation needs an SDK bump.
       const stream = await client.models.generateContentStream({
         model: model.id,
         contents,
@@ -290,5 +293,10 @@ function convertSchema(node: Record<string, unknown>): Record<string, unknown> {
     }
     out.properties = props;
   }
+  // Array element schema. Gemini REQUIRES `items` for an ARRAY type — omitting it makes the
+  // API reject the whole request with a 400 "exception parsing response", so recurse into it.
+  if (node.items && typeof node.items === "object") {
+    out.items = convertSchema(node.items as Record<string, unknown>);
+  }
   return out;
 }