mini-coder 0.2.1 → 0.2.3

package/docs/KNOWN_ISSUES.md

@@ -2,9 +2,8 @@
 
 ## Bugs
 
-- `/model` doesn't autocomplete models provider/name pattern.
 - AI SDK expands `claude-3-5-haiku` → dated variant that Zen doesn't serve (404).
-- Shell tool max-timeout leaves the parent terminal in a broken state.
+- 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.
 
 ## Features
 

package/docs/design-decisions.md

@@ -0,0 +1,74 @@
+# Design Decisions
+
+Documenting why mini-coder makes certain architectural choices — especially where we intentionally diverge from AI SDK defaults or common patterns.
+
+## Why not ToolLoopAgent?
+
+**Decision:** Use `streamText` directly instead of the AI SDK's `ToolLoopAgent`.
+
+`ToolLoopAgent` is a convenience wrapper that manages the tool-call loop, context, and stopping conditions. Mini-coder needs explicit control over every aspect it abstracts away:
+
+- **Streaming event rendering** — We yield granular `TurnEvent`s (text deltas, tool calls, tool results, reasoning, context-pruned notifications) as they arrive from `fullStream`. The reporter renders them append-only into the terminal in real time. `ToolLoopAgent` gives you the final result; we need the firehose.
+- **ESC interrupt mid-turn** — An `AbortController` is wired through to `streamText`'s `signal`. On ESC, we abort, preserve partial messages, and append an interrupt stub so the LLM retains context. `ToolLoopAgent` doesn't expose this kind of mid-stream abort-and-preserve behavior.
+- **Custom context pruning** — After every turn, `SessionRunner` runs `applyContextPruning` + `compactToolResultPayloads` on the in-memory history. This is rolling, per-turn pruning that must not break prompt caching. `ToolLoopAgent`'s built-in context management doesn't match these constraints.
+- **Per-step DB persistence** — Each turn's messages are saved to SQLite with a turn index as they complete. The in-memory `coreHistory` diverges from the DB history (pruned vs. full). `ToolLoopAgent` has no hook for this.
+- **Provider-specific caching annotations** — `annotateToolCaching` adds caching metadata to the tool set based on the model string, injected directly into the `streamText` call.
+- **No step/tool-call limits** — Per the design: "No max steps or tool call limits — user can interrupt." `ToolLoopAgent` defaults to `stopWhen: stepCountIs(20)`.
+
+**Summary:** `ToolLoopAgent` reduces boilerplate for simple request→response agents. Mini-coder is a shell-first coding agent where the loop _is_ the product. Using `ToolLoopAgent` would mean fighting the abstraction at every turn.
+
+## Why no cross-session memory?
+
+**Decision:** No agent-managed persistent memory across sessions. The repo and user-authored config files are the memory.
+
+The AI SDK offers several memory approaches (Anthropic memory tool, Mem0, Letta, custom tools) that let agents save facts and recall them in future conversations. We intentionally don't use any of these.
+
+### What we have instead
+
+- **Within-session persistence** — Full message history saved to SQLite per-turn, sessions resumable via `/session`.
+- **Context pruning** — `applyContextPruning` and `applyStepPruning` strip old reasoning/tool-calls to fit context windows without breaking prompt caching.
+- **Static cross-session context** — `AGENTS.md`/`CLAUDE.md` files loaded into the system prompt. This is user-curated project knowledge, not agent-managed memory.
+- **Skills** — Reusable instruction sets discoverable via `/` autocomplete.
+
+### Why not agent-written memory?
+
+We considered having the agent write to `~/.agents/AGENTS.md` for cross-session recall. Rejected because:
+
+- **Intrusive** — `~/.agents/` is the user's space. Agent writes would mix generated noise with intentional configuration, creating surprises ("where did this line come from?").
+- **Violates conventions** — `AGENTS.md`/`CLAUDE.md` are community standards meant to be human-authored instructions _to_ the agent, not an agent scratchpad. Using them as memory inverts the relationship.
+- **Safety conflict** — Our own system prompt requires confirmation before irreversible actions. Silently modifying a user's global config violates that principle.
+- **Complexity** — Memory adds storage, retrieval, relevance ranking, and non-determinism. The design philosophy is performance first, minimal setup.
+
+### If we ever want this
+
+A dedicated `~/.config/mini-coder/memories.md` that's clearly agent-owned and separate from user config would be the right path — not overloading existing community standards.
+
+**Summary:** For a coding agent that operates on a repo, the repo _is_ the memory. Users who want cross-session context write it in `AGENTS.md` themselves — that's an intentional act, not an LLM side effect.
+
+## Why no tool-call permissions?
+
+**Decision:** No approval prompts, no blacklists, no whitelists. Every tool call executes immediately.
+
+Our inspirations (Claude Code, OpenCode) require user approval for tool calls — shell commands, file writes, etc. We intentionally skip this.
+
+### Permission systems provide a false sense of security
+
+- **Shell bypasses everything.** An LLM with shell access can `curl`, `eval`, pipe through `bash`, encode payloads, or chain commands in ways no static blacklist can anticipate. Any permission scheme that allows shell but blocks specific patterns is playing whack-a-mole.
+- **Blacklists and whitelists always have gaps.** Block `rm -rf /`? The model uses `find -delete`. Block `git push --force`? It uses `git push origin +main`. The surface area is unbounded.
+- **Approval fatigue degrades security.** After the 20th "Allow shell command?" prompt, users auto-approve everything. The permission system trains the user to click "yes" reflexively — the opposite of its intent.
+
+### Permissions are cumbersome
+
+A coding agent runs dozens of shell commands per task. Requiring approval for each one destroys the flow that makes a CLI agent useful. The whole point of mini-coder is: small, fast, stays out of the way.
+
+### Isolation is a separate concern
+
+Sandboxing is a real need, but it belongs at the OS/container level — not inside the agent. Tools like [nono](https://nono.sh/) provide proper filesystem and network isolation that the LLM cannot circumvent. This is defense in depth done right: the agent runs unrestricted inside a sandbox that enforces actual boundaries.
+
+### Our approach
+
+- The system prompt includes safety rules (no secrets, confirm destructive actions, no unauthorized reverts).
+- The user can interrupt at any time with ESC (preserve context) or Ctrl+C (hard exit).
+- For real isolation, run mini-coder inside a sandboxed environment.
+
+**Summary:** Permission dialogs give the appearance of safety without the substance. Real security comes from sandboxing the environment, not gatekeeping individual tool calls. Mini-coder codes — isolating it is a job for the right tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mini-coder",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A small, fast CLI coding agent",
   "module": "src/index.ts",
   "type": "module",
@@ -31,6 +31,7 @@
     "diff": "^8.0.3",
     "yoctocolors": "^2.1.2",
     "yoctomarkdown": "^0.0.7",
+    "yoctoselect": "0.0.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {