smolcoder 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leon van Zyl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# smolcoder
+
+A tiny, zero-config CLI coding agent for **local models**. Ollama and LM Studio only — and because it supports only those, it can make them first-class: no base URLs, no API keys, no config files, no setup questions. Start it and code.
+
+```bash
+npm install -g smolcoder
+smol
+```
+
+Works on Windows, macOS, and Linux. Zero runtime dependencies.
+
+## The TUI
+
+smol opens straight into a session — the last model you used (or the first one detected) is picked automatically. Everything is changed in-session:
+
+- **`/` slash commands** with an autocomplete menu: `/models` (switch model, type to filter), `/mode`, `/effort`, `/tasks`, `/compact`, …
+- **shift+tab** cycles read-only → edit → bypass permissions
+- **esc** cancels a running turn; **ctrl+c ×2** quits
+- The status line under the input shows mode · model · effort · context fill · running background tasks, live.
+- `/effort` maps to Ollama's `think` parameter and LM Studio's `reasoning_effort`. `off` disables thinking on qwen3-class models — a real speedup. Models that don't support it fall back silently.
+
+For scripts and automations there is a headless mode that prints the transcript and exits: `smol -p "prompt"` (reasoning noise suppressed, exit code reflects success).
+
+## Why
+
+Most coding harnesses treat local models as an afterthought: you configure endpoints by hand, and then they inject huge system prompts, dozens of tools, MCP servers and skills into a model with a small context window. smolcoder is built the other way around:
+
+- **Zero config.** Probes the standard Ollama (`127.0.0.1:11434`, or `$OLLAMA_HOST`) and LM Studio (`127.0.0.1:1234`) endpoints and lists whatever models you already have. Docker-hosted Ollama with the usual port mapping is picked up automatically.
+- **Tiny context footprint.** A two-paragraph system prompt, exactly seven flat tools, hard caps on every tool output, and no MCP, no skills, no subagents.
+- **Context windows handled properly.** For Ollama, smolcoder respects the server's own configured context length (the Ollama app's setting) — it preloads the model and reads the effective window from `/api/ps`, sending an explicit `num_ctx` only on old Ollama versions where the silent tiny default would truncate prompts, or when you pass `--ctx`. For LM Studio it reads the loaded context length from `/api/v0/models` and budgets within it. Real token usage reported by the backend drives a live context meter and automatic compaction (old tool output is evicted first — nearly free — and the conversation is summarized only when that's not enough).
+- **Small-model-friendly tools.** Flat string parameters, an example call in every description, and error messages written as coaching (a failed edit shows the closest real snippet to copy). The edit tool forgives whitespace drift — the difference between usable and unusable local editing.
+
+## Modes
+
+| Mode | Files | Commands |
+|------|-------|----------|
+| `ro` (read-only) | read/search only | none |
+| `edit` (default) | read/write/edit | runs freely inside the workspace (`npm install`, tests, scripts); a command that reaches outside it asks y/n (or **a**lways-allow that program for the session) |
+| `bypass` (bypass permissions) | read/write/edit | never asks for approval |
+
+The mode decides which tools *exist* — in read-only mode the model is never even told a write tool exists. File tools are sandboxed to the workspace folder (symlink escapes included). Commands run with the workspace as their working directory, and in edit mode the command text is scanned before it runs: absolute paths outside the workspace, `/tmp`, `~`, temp-dir variables, `..` climbing past the root, and global package installs all trigger the approval prompt (with the reason shown). This is a best-effort text scan, not an OS sandbox — a command can still reach outside through, say, a script it runs — so use read-only mode for untrusted work and bypass only when you want no prompts at all.
+
+## The plan — a compass for small models
+
+For multi-step tasks the agent keeps a to-do list via a `plan` tool (`set` / `done` / `add` / `show`). It's not a gimmick copied from the big harnesses — it's built for small context windows:
+
+- The list lives in the **harness**, not in a file or the transcript, so rendering it costs zero tokens and **compaction can never destroy it** — after every compaction the checklist is re-injected, so the model wakes up looking at its map.
+- Every `done` result answers "what's next" in ~10 tokens, continuously re-focusing the model.
+- If the model tries to stop with steps unfinished, the harness pushes back once — attacking the classic local-model failure of quitting halfway.
+- You see it live: a checklist block in the TUI whenever it changes, `plan 2/4` in the status bar, `/plan` to reprint it, and checklist updates on stderr in headless runs.
+
+## AGENTS.md memory
+
+If the workspace contains an `AGENTS.md`, its contents are injected right after the system prompt (size-capped at ~2k tokens) and survive compaction. Put your project conventions, commands, and quirks there.
+
+## Tools the model gets
+
+`read_file` · `write_file` · `edit_file` · `list_files` · `search` · `plan` · `run_command` · `task`
+
+`task` manages background processes (dev servers, watchers): `start`, `list`, `logs`, `stop`. Background tasks are non-blocking, keep a ring buffer of recent output, show up in the status line, and are killed when smolcoder exits. You can inspect them yourself with `/tasks`, `/logs <id>`, `/stop <id>`.
+
+## Usage
+
+```bash
+smol                        # current folder, remembers your last model & mode
+smol path/to/project        # a specific workspace
+smol --mode bypass          # bypass permissions: no approval prompts
+smol --model qwen3          # pick a model by (partial) name
+smol --ctx 16384            # cap the context window (Ollama: sets num_ctx)
+smol -p "fix the failing test"   # one-shot, non-interactive
+```
+
+In a session: `/mode`, `/model`, `/context`, `/compact`, `/tasks`, `/logs <id>`, `/stop <id>`, `/clear`, `/help`, `/exit`. `Ctrl+C` cancels a running turn.
+
+## Backend notes: Ollama vs LM Studio
+
+Measured head-to-head with identical qwen3.8-27B Q4_K_M weights on one RTX 5090
+(the model is a hybrid recurrent `qwen35` build; Ollama 0.33, LM Studio 0.4.21):
+
+| | Ollama | LM Studio |
+|---|---|---|
+| prompt processing (6.7k-token cold prompt) | ~3,300 tok/s | ~3,000–3,400 tok/s |
+| generation, 400 tokens of prose, thinking off | ~120 tok/s | ~68 (4 slots + MTP) / ~76 (1 slot, no MTP) tok/s |
+| generation, 1,200 tokens of JavaScript, thinking off | ~170 tok/s | ~110 (1 slot + MTP) / ~76 (no MTP) tok/s |
+| one agent step (plan + write call), thinking off | 0.9 s | 1.5–1.8 s |
+| one agent step with thinking, same prompt | 0.8–10 s (38–3,500 reasoning chars) | 1.8–85 s (250–19,000 reasoning chars) |
+
+The engine is the same llama.cpp on both, so the differences come from what the
+harness sends and from load settings:
+
+- **Reasoning effort was the whole story behind "LM Studio is slow".** LM Studio's
+  API takes `reasoning_effort` none/minimal/low/medium/high/xhigh, but each model only
+  supports some of them and a value the model lacks is silently replaced by the
+  model's *default* — which for current qwen3.x builds is **xhigh**, the maximum.
+  Asking for `high` therefore produced 8,000-token thinking bursts before single
+  tool calls. smolcoder now reads the model's supported levels and default from
+  `/api/v1/models`, sends `none` for `off` (measured: fully disables thinking), and
+  snaps other levels to the nearest one the model has (`high` → `medium` on qwen;
+  ties go to the cheaper level). The status line shows the mapping (`high → medium`,
+  `default → xhigh`), and a warning is printed when the default is the maximum.
+  On Ollama, `off` is a real `think: false` and any other level is `think: true`
+  (levels only exist for gpt-oss there).
+- **Thinking is unpredictable on local models.** The same prompt at the same level
+  thought for 250 characters one run and 19,000 the next. For long tool loops,
+  `--effort off` is the reliable setting on both backends; `low`/`medium` are fine
+  for questions and planning.
+- **Generation is ~1.5× faster on Ollama** with default settings (Ollama also
+  drafts 4 tokens per step with the model's MTP head; LM Studio drafts 2). On LM
+  Studio, keep MTP speculative decoding ON for coding — it took code generation from
+  76 to ~110 tok/s (it slightly slows prose, which is what most benchmarks measure) —
+  and load with a single slot, which is another ~10%:
+  `lms load <model> --context-length 65536 --parallel 1 --speculative-draft-mtp`.
+  Prompt caching works on both (only the new tail of the prompt is processed).
+- **Ollama keeps the model resident** for 30 minutes between calls (its own default
+  unloads after 5 min — a long approval pause used to cost a 10–20 s reload).
+  Override with `SMOLCODER_KEEP_ALIVE=1h`.
+- **Reasoning traces are not replayed** for finished turns (the qwen templates drop
+  them anyway); only the current turn's traces travel with the tool loop. On a
+  thinking model this is the largest single prompt-size saving.
+
+## End-to-end: the same Minecraft build on both backends
+
+One headless run each (`smol -p "<prompt>" --mode bypass --effort off`), same
+model weights, same prompt (procedural voxel terrain, first-person controls, block
+place/remove, three.js from a CDN, then serve it). Nobody typed "continue".
+
+| | Ollama | LM Studio (1 slot, MTP on) |
+|---|---|---|
+| wall clock | 64 s | 85 s |
+| tool calls | 20 (5 files) | 14 (3 files) |
+| tokens generated | 9.4k @ 171 tok/s | 7.4k @ 96 tok/s |
+| plan | 6/6 done | 3/3 done |
+| syntax warnings from the write hook | 0 | 0 |
+| result in the browser | loads, no console errors; one mesh-winding bug | loads, no console errors; terrain not visible |
+
+Both agents finished on their own, checked their files with `node --check`, and
+started a static server to prove the page served. Reproduce with `bench/run.sh`
+(the prompt is `bench/minecraft-prompt.txt`; every headless run ends with a
+`[stats]` JSON line on stderr). Both first drafts had one real bug
+(this is a 27B model writing a voxel engine with thinking off); each was fixed with
+a second headless turn carrying a one-paragraph, symptom-only bug report:
+
+| fix turn | Ollama | LM Studio |
+|---|---|---|
+| wall clock | 42 s | 100 s |
+| tool calls | 27 (reads, searches, 3 edits, node one-liners) | 27 (7 reads, 3 edits, 10 commands, 6 plan) |
+| tokens generated | 4.8k @ 165 tok/s | 6.9k @ 79 tok/s |
+| outcome | solid terrain; face vertex order fixed | terrain renders; spawn height + camera pitch fixed |
+
+### The same build with reasoning on (`--effort high`)
+
+`high` resolves to `medium` on this LM Studio model (its levels are off/low/medium/xhigh;
+ties snap to the cheaper neighbour) and to `think: true` on Ollama.
+
+| | Ollama (`think: true`) | LM Studio (`high → medium`) |
+|---|---|---|
+| wall clock | 84 s | 289 s (about a third of it a port-collision detour caused by the test setup) |
+| tool calls | 16 | 28 |
+| tokens generated | 10.6k @ 146 tok/s, ~2.6k of them reasoning | 22.5k @ 84 tok/s, ~12.2k of them reasoning |
+| plan | 4/4 | 5/5 |
+| result in the browser | correct on the first try: terrain, hills, controls, no console errors | correct on the first try: terrain, hills, controls, no console errors |
+
+Reasoning bought correctness: both first drafts worked, where both effort-off drafts had
+needed a bug-fix turn. The price is time — the model's per-step thinking is where the
+backends differ most (Ollama's `think: true` produced a quarter as many reasoning
+tokens as LM Studio's `medium`), and LM Studio's default `xhigh` would have been far
+slower still. Note that the two effort-off runs plus their fix turns (106 s on Ollama,
+185 s on LM Studio) still beat the reasoning runs on wall clock.
+
+### Forcing compaction
+
+The same build with the window capped at 12k tokens (`--ctx 12000`, output budget
+3k) is the stress test for everything above: Ollama finished the whole game in
+104 s and 28 tool calls with context management kicking in five times, the plan
+reported 5/5, and the page rendered. On LM Studio the same run went through a tier-1
+eviction (7.4k → 5.1k tokens) and then a real tier-2 compaction (7.5k → 2.1k tokens:
+system prompt + plan + model-written hand-over notes + the working tail), after which
+the model carried on with the remaining steps — syntax check, serve, summarize. (That
+LM Studio build parses and serves but throws a runtime TypeError on load — a file
+assembled in five pieces under a 3k output cap is where a 27B model starts to slip,
+and a parse check cannot catch runtime errors.) Two things made the runs work at all:
+
+- when a whole-file `write_file` overflows the output cap, the model is told the call
+  was **not executed** and coached to write the file in parts (first part with
+  `write_file`, then `edit_file` appends) — before that coaching existed the model
+  retried the same oversized write three times in a row;
+- the plan and the hand-over notes are re-injected after every compaction, so the
+  model resumes at the right step instead of starting over.
+
+## Requirements
+
+- Node.js 18+
+- [Ollama](https://ollama.com) with at least one tool-capable model pulled (e.g. `ollama pull qwen3`), **or** LM Studio with its local server running (Developer tab → Start Server).
+
+## License
+
+[MIT](LICENSE)

package/dist/agent.js

@@ -0,0 +1,411 @@
+"use strict";
+// The agent loop: one tool call at a time, tool results fed back, until the
+// model answers in plain text. Parallel tool calls are not requested; if a
+// model emits several anyway, they simply run sequentially. Malformed calls
+// come back as coaching errors so the model can retry instead of derailing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+exports.isAutoApproved = isAutoApproved;
+exports.describeStats = describeStats;
+const index_1 = require("./tools/index");
+const util_1 = require("./util");
+const sandbox_1 = require("./sandbox");
+const TRANSIENT_ERROR = /fetch failed|econn|socket|network|timed?.?out|50[0234]/i;
+/** Shell metacharacters that let one "allowed program" smuggle in others.
+ * Auto-approval via always-allow only applies to commands without them. */
+const SHELL_META = /[;&|`$<>(){}\n\r\\]/;
+/** Exported for tests: does the always-allow set cover this exact command?
+ * First-token match alone is bypassable (`npm -v; evil`) because commands run
+ * under a real shell — so chained/piped/substituted commands always re-prompt. */
+function isAutoApproved(command, allowed) {
+    const trimmed = command.trim();
+    let program = trimmed.split(/\s+/)[0] ?? "";
+    if (process.platform === "win32")
+        program = program.toLowerCase();
+    return allowed.has(program) && !SHELL_META.test(trimmed);
+}
+class Agent {
+    provider;
+    mode;
+    systemPrompt;
+    toolCtx;
+    ctxMgr;
+    bus;
+    ui;
+    interactive;
+    maxSteps;
+    messages = [];
+    tools;
+    alwaysAllowed = new Set();
+    originalRequest = "";
+    currentRequest = "";
+    planNudged = false;
+    abort = null;
+    /** Speed/size figures for the last completed turn (for the turn-end label
+     * and headless stats). */
+    lastTurnStats = null;
+    constructor(provider, mode, systemPrompt, toolCtx, ctxMgr, bus, ui, interactive, 
+    /** Tool-call budget per user turn. Headless runs get a much larger one. */
+    maxSteps = 30) {
+        this.provider = provider;
+        this.mode = mode;
+        this.systemPrompt = systemPrompt;
+        this.toolCtx = toolCtx;
+        this.ctxMgr = ctxMgr;
+        this.bus = bus;
+        this.ui = ui;
+        this.interactive = interactive;
+        this.maxSteps = maxSteps;
+        this.messages = [{ role: "system", content: systemPrompt }];
+        this.tools = (0, index_1.buildToolSpecs)(mode);
+    }
+    setMode(mode, systemPrompt) {
+        this.mode = mode;
+        this.tools = (0, index_1.buildToolSpecs)(mode);
+        this.messages[0] = { role: "system", content: systemPrompt };
+    }
+    setProvider(provider) {
+        this.provider = provider;
+    }
+    resetTranscript() {
+        this.messages = [this.messages[0]];
+        this.originalRequest = "";
+        this.currentRequest = "";
+        this.planNudged = false;
+        // Session facts feed the compaction state note — stale ones from a
+        // cleared conversation would assert work the new task never did.
+        this.toolCtx.filesTouched.clear();
+        this.toolCtx.commandsRun.length = 0;
+        this.ctxMgr.resetAnchor();
+    }
+    cancel() {
+        this.abort?.abort();
+    }
+    contextPercent() {
+        return this.ctxMgr.fillPercent(this.messages, this.tools);
+    }
+    contextTokens() {
+        return this.ctxMgr.estimatePrompt(this.messages, this.tools);
+    }
+    async compactNow() {
+        await this.bus.emit("pre_compact");
+        const { messages, report } = await this.ctxMgr.manage(this.messages, this.tools, this.provider, {
+            originalRequest: this.originalRequest,
+            currentRequest: this.currentRequest,
+            filesTouched: this.toolCtx.filesTouched,
+            commandsRun: this.toolCtx.commandsRun,
+            planLine: this.toolCtx.plan.compactLine(),
+        });
+        this.messages = messages;
+        await this.bus.emit("post_compact", report);
+    }
+    async runTurn(userInput) {
+        if (!this.originalRequest)
+            this.originalRequest = userInput;
+        this.currentRequest = userInput; // the task compaction must never lose
+        this.messages.push({ role: "user", content: userInput });
+        this.abort = new AbortController();
+        const signal = this.abort.signal;
+        const t0 = Date.now();
+        let completed = false;
+        let steps = 0;
+        let nudges = 0;
+        let toolCallsThisTurn = 0;
+        let sincePlanUpdate = 0;
+        const stats = {
+            modelCalls: 0,
+            toolCalls: 0,
+            generatedTokens: 0,
+            genSeconds: 0,
+            thinkingChars: 0,
+            promptTokensLast: 0,
+            durationMs: 0,
+        };
+        this.lastTurnStats = stats;
+        try {
+            while (steps++ < this.maxSteps) {
+                // Context management before every request.
+                await this.bus.emit("pre_request");
+                if (this.ctxMgr.needsAttention(this.messages, this.tools)) {
+                    this.ui.status("· context is getting full — compacting…");
+                    await this.compactNow();
+                }
+                this.ui.startSpinner("thinking");
+                let result;
+                try {
+                    result = await this.chatWithRetry(signal);
+                }
+                finally {
+                    this.ui.stopSpinner();
+                }
+                this.messages.push({
+                    role: "assistant",
+                    content: result.content,
+                    toolCalls: result.toolCalls.length ? result.toolCalls : undefined,
+                    thinking: result.thinking,
+                });
+                // Anchor AFTER the push: lastPromptTokens+lastCompletionTokens then
+                // cover exactly the first `messages.length` messages — recording
+                // before the push double-counted the reply in every estimate.
+                this.ctxMgr.recordUsage(result.promptTokens, result.completionTokens, this.messages.length);
+                stats.modelCalls++;
+                if (result.generatedTokens) {
+                    stats.generatedTokens += result.generatedTokens;
+                    if (result.genTokPerSec)
+                        stats.genSeconds += result.generatedTokens / result.genTokPerSec;
+                }
+                if (result.promptTokens)
+                    stats.promptTokensLast = result.promptTokens;
+                if (result.thinking)
+                    stats.thinkingChars += result.thinking.length;
+                if (result.content)
+                    this.ui.println(); // end the streamed line
+                if (result.toolCalls.length === 0) {
+                    // A reply cut off by the output cap, or an empty reply, is not a
+                    // finished turn — that is how local-model sessions die silently.
+                    // Nudge the model back on track (bounded).
+                    if (result.truncated && nudges < 3) {
+                        nudges++;
+                        this.ui.status("· reply hit the output limit — asking the model to continue");
+                        // Reasoning models can burn the ENTIRE budget thinking, arriving
+                        // with no visible output at all — "continue where you left off"
+                        // would just restart the same doomed think. Target that case.
+                        // With thinking off, an empty truncated reply is almost always a
+                        // tool call whose arguments (a whole file) overflowed the cap — it
+                        // was never parsed, so nothing was saved and "continue" cannot
+                        // work. Name the cap and coach the split explicitly.
+                        const noContent = !result.content.trim();
+                        const burnedByThinking = noContent && !!result.thinking?.trim();
+                        const nudgeText = burnedByThinking
+                            ? `[Your reasoning used the entire output limit (${this.provider.maxOutputTokens} tokens) and produced no answer. Do not re-derive everything — reply now with your next tool call or a brief answer.]`
+                            : noContent
+                                ? `[${this.truncatedCallHint()}]`
+                                : `[Your reply was cut off by the output length limit of ${this.provider.maxOutputTokens} tokens. Continue where you left off. If a file was too large for one write_file call, split the content into separate files — writing the same path again replaces it completely.]`;
+                        this.messages.push({ role: "user", content: nudgeText });
+                        continue;
+                    }
+                    if (!result.content.trim() && nudges < 2) {
+                        nudges++;
+                        this.ui.status("· empty reply — nudging the model");
+                        this.messages.push({
+                            role: "user",
+                            content: "[Your reply was empty. If the task is finished, summarize what you did. Otherwise make the next tool call now.]",
+                        });
+                        continue;
+                    }
+                    // The model wants to stop but its own plan still has open steps —
+                    // the classic local-model quit-halfway. One bounded push back.
+                    // One nudge PER PLAN STATE, not per turn: an abandoned plan must not
+                    // drag every later unrelated question back to stale work. The flag
+                    // re-arms only when the plan actually changes (set/done/add).
+                    const plan = this.toolCtx.plan;
+                    if (plan.exists && plan.currentIndex >= 0 && toolCallsThisTurn > 0 && !this.planNudged) {
+                        this.planNudged = true;
+                        this.ui.status("· plan has unfinished steps — nudging the model to continue");
+                        this.messages.push({
+                            role: "user",
+                            content: `[Your plan still has unfinished steps: ${plan.pendingSummary()}. Continue with the next step now — or if a step no longer applies, mark it done with the plan tool and explain why.]`,
+                        });
+                        continue;
+                    }
+                    completed = true;
+                    return; // plain answer — turn over
+                }
+                nudges = 0;
+                for (const call of result.toolCalls) {
+                    if (signal.aborted)
+                        throw abortError();
+                    this.ui.toolCall(call.name, call.parseError ? { __raw: (call.rawArgs ?? "").slice(0, 80) } : call.args);
+                    let output;
+                    if (call.parseError) {
+                        // LM Studio streams the partial arguments of a cut-off call, so
+                        // the overflow surfaces here as unparseable JSON.
+                        output = result.truncated
+                            ? `Error: ${this.truncatedCallHint()}`
+                            : `Error: your tool call arguments could not be parsed (${call.parseError}). Send the arguments as a single JSON object, e.g. {"path": "src/app.js"}.`;
+                    }
+                    else if (!this.tools.some((t) => t.name === call.name)) {
+                        // HARD mode enforcement. The schemas sent to the model are only
+                        // advisory — a hallucinated or injected write_file/run_command in
+                        // read-only mode must be rejected here, at execution time.
+                        output = `Error: the tool "${call.name}" is not available in ${index_1.MODE_LABELS[this.mode]} mode. Available tools: ${this.tools.map((t) => t.name).join(", ")}.`;
+                    }
+                    else {
+                        output = await this.gateAndExecute(call.name, call.args, signal);
+                        toolCallsThisTurn++;
+                        stats.toolCalls++;
+                        // Tier-0 context hygiene: a full overwrite makes every earlier
+                        // read of that file wrong. Stub them out right away.
+                        if (call.name === "write_file" && !output.startsWith("Error") && typeof call.args?.path === "string") {
+                            this.ctxMgr.evictStaleReads(this.messages, call.args.path);
+                        }
+                        // Keep the plan honest: small models forget to mark steps done
+                        // mid-flow, leaving the checklist stale for minutes. A periodic
+                        // one-line reminder riding on a tool result fixes it cheaply.
+                        const plan = this.toolCtx.plan;
+                        if (call.name === "plan") {
+                            sincePlanUpdate = 0;
+                            if (!output.startsWith("Error"))
+                                this.planNudged = false; // plan changed — re-arm
+                        }
+                        else if (plan.exists && plan.currentIndex >= 0 && ++sincePlanUpdate >= 4) {
+                            sincePlanUpdate = 0;
+                            const cur = plan.steps[plan.currentIndex];
+                            output += `\n[Reminder: the plan still shows step ${plan.currentIndex + 1} "${cur.text}" as current. If you have finished steps, mark each with plan {"action": "done"} now.]`;
+                        }
+                    }
+                    // Plan changes render as the visual checklist instead of a ✓ line.
+                    if (call.name === "plan" &&
+                        !output.startsWith("Error") &&
+                        ["set", "done", "add"].includes(String(call.args?.action))) {
+                        this.ui.planUpdated(this.toolCtx.plan);
+                    }
+                    else {
+                        this.ui.toolResult(output);
+                    }
+                    this.messages.push({
+                        role: "tool",
+                        content: output,
+                        toolCallId: call.id,
+                        toolName: call.name,
+                    });
+                    await this.bus.emit("post_tool", { name: call.name, args: call.args });
+                    // A cancel during tool execution ends the turn now, with the
+                    // (cancelled) result already recorded so the transcript stays valid.
+                    if (signal.aborted)
+                        throw abortError();
+                }
+            }
+            this.ui.warn(`Stopped after ${this.maxSteps} tool calls in one turn. Say "continue" to keep going.`);
+            completed = true;
+        }
+        catch (err) {
+            if (err?.name === "AbortError" || signal.aborted) {
+                this.ui.println();
+                this.ui.status("· cancelled");
+                this.sanitizeAfterCancel();
+                return;
+            }
+            throw err;
+        }
+        finally {
+            this.abort = null;
+            stats.durationMs = Date.now() - t0;
+            if (completed) {
+                this.ui.turnEnd(`${index_1.MODE_LABELS[this.mode]} · ${this.provider.modelId} · ${(0, util_1.fmtDuration)(stats.durationMs)}${describeStats(stats)}`);
+            }
+        }
+    }
+    /** Coaching for a tool call that overflowed the output cap. Exported via
+     * the class for tests. */
+    truncatedCallHint() {
+        const cap = this.provider.maxOutputTokens;
+        const part = Math.max(300, Math.floor(cap * 0.5));
+        return (`Your tool call was cut off by the output limit of ${cap} tokens, so it was NOT executed and nothing was saved. ` +
+            `Send smaller calls: write the file in parts of at most ~${part} tokens — write_file with the first part, ` +
+            `then edit_file to append each next part (old_text = the last line you wrote, new_text = that line followed by the next part) — ` +
+            `or split the code across several smaller files.`);
+    }
+    /** One model call, with bounded retries on transient backend failures
+     * (Ollama/LM Studio hiccups, dropped sockets, 5xx). The transcript is
+     * unchanged between attempts, so a retry is always safe. */
+    async chatWithRetry(signal) {
+        let lastErr;
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            try {
+                return await this.provider.chat(this.messages, this.tools, {
+                    signal,
+                    onToken: (t) => this.ui.token(t),
+                    onThinking: (t) => this.ui.thinking(t),
+                });
+            }
+            catch (err) {
+                if (err?.name === "AbortError" || signal.aborted)
+                    throw err;
+                lastErr = err;
+                if (attempt === 3 || !TRANSIENT_ERROR.test(String(err?.message ?? err)))
+                    throw err;
+                this.ui.warn(`· backend error (${String(err?.message ?? err).slice(0, 80)}) — retrying in ${attempt * 3}s`);
+                await new Promise((r) => setTimeout(r, attempt * 3000));
+            }
+        }
+        throw lastErr;
+    }
+    async gateAndExecute(name, args, signal) {
+        const command = (0, index_1.commandOf)(name, args);
+        // Gate everywhere except bypass (defense-in-depth: in ro mode exec tools are
+        // already rejected before this point by the tool-existence check). Edit
+        // mode runs commands that stay inside the workspace without asking and
+        // only prompts for ones that reach outside it.
+        if (command !== null && this.mode !== "bypass") {
+            const reason = (0, sandbox_1.commandEscapesWorkspace)(command, this.toolCtx.workspace);
+            if (reason !== null && !isAutoApproved(command, this.alwaysAllowed)) {
+                if (!this.interactive) {
+                    return `Error: this command ${reason}, which needs user approval, and this session is non-interactive. Keep every path inside the workspace (relative paths, a scratch folder in the workspace instead of /tmp), or the user can rerun smol with --mode bypass, or run this themselves: ${command}`;
+                }
+                const answer = await this.ui.confirmCommand(command, reason);
+                if (answer === "no") {
+                    return "The user declined to run this command. Continue without it, or ask the user what to do instead.";
+                }
+                if (answer === "always") {
+                    let program = command.trim().split(/\s+/)[0] ?? "";
+                    if (process.platform === "win32")
+                        program = program.toLowerCase();
+                    if (program)
+                        this.alwaysAllowed.add(program);
+                }
+            }
+        }
+        return (0, index_1.executeTool)(name, args, this.toolCtx, signal);
+    }
+    /**
+     * After a cancel, the most recent assistant tool-call message may have some
+     * calls unanswered — strict backends reject that shape on the next request.
+     * A cancel mid-way through a MULTI-call batch buries that assistant message
+     * behind the already-pushed tool results, so walk back past them.
+     */
+    sanitizeAfterCancel() {
+        let i = this.messages.length - 1;
+        while (i >= 0 && this.messages[i].role === "tool")
+            i--;
+        const anchor = this.messages[i];
+        if (anchor?.role === "assistant" && anchor.toolCalls?.length) {
+            for (const tc of anchor.toolCalls) {
+                const answered = this.messages.some((m) => m.role === "tool" && m.toolCallId === tc.id);
+                if (!answered) {
+                    this.messages.push({
+                        role: "tool",
+                        content: "[cancelled by the user before this tool ran]",
+                        toolCallId: tc.id,
+                        toolName: tc.name,
+                    });
+                }
+            }
+        }
+    }
+    statusLine() {
+        const pct = this.contextPercent();
+        const tasks = this.toolCtx.taskManager.runningSummary();
+        const taskPart = tasks.length ? ` · ${tasks.length} bg task${tasks.length > 1 ? "s" : ""}` : "";
+        return util_1.c.gray(`ctx ${pct}% of ${this.provider.contextWindow.toLocaleString()} · ${this.provider.label} · ${this.mode}${taskPart}`);
+    }
+}
+exports.Agent = Agent;
+/** " · 12 tools · 4.1k tok @ 118 tok/s" — the speed readout local-model users
+ * actually want to compare backends with. */
+function describeStats(s) {
+    const parts = [];
+    if (s.toolCalls)
+        parts.push(`${s.toolCalls} tool${s.toolCalls === 1 ? "" : "s"}`);
+    if (s.generatedTokens) {
+        const k = s.generatedTokens >= 1000 ? `${(s.generatedTokens / 1000).toFixed(1)}k` : String(s.generatedTokens);
+        const rate = s.genSeconds > 0 ? ` @ ${Math.round(s.generatedTokens / s.genSeconds)} tok/s` : "";
+        parts.push(`${k} tok${rate}`);
+    }
+    return parts.length ? " · " + parts.join(" · ") : "";
+}
+function abortError() {
+    const e = new Error("aborted");
+    e.name = "AbortError";
+    return e;
+}