hexcli 2.8.0__py3-none-any.whl

hexcli/compaction.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""hexcli.compaction — history compression and the context budget, lifted
+out of agent.py.
+
+The deterministic merge-aware compactor, the LLM summarizer behind explicit
+/compact, and the derived history budget + auto-compact guard.
+
+Cross-cutting names (call_llm, build_autopilot_prompt, estimate_tokens,
+sync_session_store, the token estimator, and compact_history itself when
+auto-compact fires it) are resolved through the agent module AT CALL TIME —
+the same idiom loop_v2 uses — so every existing sa.<name> patch site keeps
+intercepting. Module-local calls stay module-local only when nothing patches
+them.
+
+Split stage 4 (docs/V2X_ROADMAP.md, "The Split"). Bodies moved verbatim
+apart from those hub lookups.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from hexcli.parsing import strip_thinking
+from hexcli.prompts import COMPACT_SYSTEM_PROMPT
+from hexcli.sessions import touch_session
+from hexcli.ui import C, cprint
+
+
+def _agent():
+    from hexcli import agent
+    return agent
+
+
+# Markers for the deterministic compactor's output. Constants because the
+# compactor must RECOGNISE its own previous output on re-compaction (see
+# below); inline strings in two places would drift apart silently.
+_CONDENSED_MARKER = "[Earlier turns, condensed:]"
+_CONDENSED_ACK = "Understood — continuing with that context in mind."
+_CONDENSED_DROP_RE = re.compile(r"^- \[…(\d+) earlier turn")
+
+# The history budget is derived from the server's INPUT budget
+# (`context_window_tokens`: what npurun enforces before it starts dropping
+# messages; adopted from /v1/models at the first turn, 3,000 when the server
+# does not advertise one), not from a model "cliff". The 2,600-token cliff
+# that lived here from July to September was never a length effect —
+# V2_PLAN §14.7 records uc1 failing at 2,477 while uc2 passed at 2,911 (a
+# regex bug), and the August sweep (evals/cases_cliff.py) found quality flat
+# right up to the server's trim. See docs/RESEARCH_NEXT_LEVERS.md §8.
+_DEFAULT_INPUT_BUDGET_TOKENS = 3_000
+# Reserve for the parts of a turn that are neither system prompt nor history:
+# workspace snapshot, the user's query, and the first tool result coming back.
+_TURN_OVERHEAD_TOKENS = 500
+# Never demand compaction below this — pathological when the prompt is huge.
+_MIN_HISTORY_BUDGET_TOKENS = 250
+# Auto-compact only fires when its dry run shows at least this much freed.
+# Below that, compacting is churn: it rewrites history the model then has to
+# re-read, without buying room for the next turn.
+_AUTO_COMPACT_MIN_GAIN_TOKENS = 100
+
+
+def _expand_condensed(content: str) -> tuple[list[str], int]:
+    """Split a previous condensed block back into (stub_lines, dropped_count)."""
+    lines: list[str] = []
+    dropped = 0
+    for raw in content.splitlines():
+        line = raw.strip()
+        if not line.startswith("- "):
+            continue  # header/footer markers
+        m = _CONDENSED_DROP_RE.match(line)
+        if m:
+            dropped += int(m.group(1))
+            continue
+        lines.append(line)
+    return lines, dropped
+
+
+def compact_history_deterministic(
+    session: dict[str, Any],
+    keep_recent: int = 4,
+    stub_chars: int = 160,
+    total_stub_chars: int = 900,
+) -> list[dict[str, str]]:
+    """Compact history WITHOUT an LLM call.
+
+    Auto-compact used to summarise via the same 4B model that was already at
+    its degradation cliff — the worst possible moment to ask it for a faithful
+    summary, and a full extra re-prefill besides (review finding W10). This
+    keeps the most recent turns verbatim and reduces older ones to one-line
+    stubs: instant, free, and impossible to hallucinate. The LLM summariser
+    stays available for explicit /compact, where the user opts into the cost.
+
+    Re-compaction is merge-aware: a previous run's condensed block is expanded
+    back into its stub lines instead of being stubbed as an opaque message.
+    Before this, every re-compact crushed the whole block into one 160-char
+    stub (stubs-of-stubs), so at the 250-token budget floor — where compaction
+    fires every couple of turns — older context was destroyed almost
+    immediately. Merging also makes the function idempotent: with no new
+    messages the output is byte-identical, which is what lets auto-compact
+    dry-run it as a thrash guard.
+    """
+    messages: list[dict[str, str]] = list(session.get("messages", []))
+    if len(messages) <= keep_recent + 1:
+        return messages
+
+    head, tail = messages[:-keep_recent], messages[-keep_recent:]
+    # Build stubs newest-first and stop at the total budget: recent context is
+    # worth more than old, and an unbounded stub list just recreates the
+    # oversized history we are trying to shed.
+    stub_lines: list[str] = []
+    used = 0
+    dropped = 0
+
+    def _take(line: str) -> None:
+        nonlocal used, dropped
+        if used + len(line) > total_stub_chars:
+            dropped += 1
+            return
+        stub_lines.append(line)
+        used += len(line)
+
+    for m in reversed(head):
+        role = m.get("role")
+        raw = m.get("content") or ""
+        if role == "assistant" and raw.strip() == _CONDENSED_ACK:
+            continue  # scaffolding from a previous compaction, not content
+        if role == "user" and raw.lstrip().startswith(_CONDENSED_MARKER):
+            inner, inner_dropped = _expand_condensed(raw)
+            dropped += inner_dropped
+            for line in reversed(inner):
+                _take(line)
+            continue
+        text = " ".join(raw.split())
+        if not text:
+            continue
+        who = "You" if role == "user" else "Hex"
+        _take(f"- {who}: {text[:stub_chars]}" + ("…" if len(text) > stub_chars else ""))
+    stub_lines.reverse()
+    if dropped:
+        stub_lines.insert(0, f"- […{dropped} earlier turn(s) dropped]")
+
+    new_messages: list[dict[str, str]] = [
+        {
+            "role": "user",
+            "content": (_CONDENSED_MARKER + "\n" + "\n".join(stub_lines)
+                        + "\n[Continue from here]"),
+        },
+        {
+            "role": "assistant",
+            "content": _CONDENSED_ACK,
+        },
+        *tail,
+    ]
+    session["messages"] = new_messages
+    session["compact_count"] = session.get("compact_count", 0) + 1
+    touch_session(session)
+    return new_messages
+
+
+def compact_history(
+    config: dict[str, Any],
+    session: dict[str, Any],
+    *,
+    quiet: bool = False,
+) -> list[dict[str, str]]:
+    """Summarise the current message history and replace it with a compact version.
+
+    quiet=True suppresses the printed summary (used by auto-compact).
+    """
+    messages: list[dict[str, str]] = list(session.get("messages", []))
+    _COMPACT_KEEP_RECENT = 4
+    # Need at least keep_recent+3 messages so that 3+ messages are summarised
+    # and removed — otherwise the 2 summary messages + 4 tail can exceed the
+    # original count (e.g. 5 msgs → 6 msgs after compact).
+    if len(messages) < _COMPACT_KEEP_RECENT + 3:
+        cprint("  Nothing to compact yet.", C.DIM)
+        return messages
+
+    # /no_think disables Qwen3's chain-of-thought block so the token budget
+    # goes to the actual summary rather than being consumed by <think> tags.
+    summary_messages: list[dict[str, str]] = [
+        {"role": "system", "content": COMPACT_SYSTEM_PROMPT},
+        *messages,
+        {"role": "user", "content": "Produce the compact summary now. /no_think"},
+    ]
+    compact_tokens = max(512, int(config.get("compact_max_output_tokens", 512)))
+    config_with_compact = {**config, "_compact_tokens": compact_tokens}
+    summary, _ = _agent().call_llm(config_with_compact, summary_messages,
+                                   "_compact_tokens", label="compacting")
+    summary = strip_thinking(summary).strip()
+
+    # Keep the last few messages verbatim so in-progress task state survives compaction.
+    tail = messages[-_COMPACT_KEEP_RECENT:] if len(messages) > _COMPACT_KEEP_RECENT else []
+
+    new_messages: list[dict[str, str]] = [
+        {
+            "role": "user",
+            "content": (
+                "[Conversation compacted. Summary of prior context:]\n\n"
+                + summary
+                + "\n\n[Continue from here]"
+            ),
+        },
+        {
+            "role": "assistant",
+            "content": "Understood. I have the context summary and will continue from where we left off.",
+        },
+        *tail,
+    ]
+    session["messages"] = new_messages
+    session["compact_count"] = session.get("compact_count", 0) + 1
+    touch_session(session)
+
+    if not quiet:
+        cprint("  Chat history compacted.", C.DIM)
+        print()
+        print(summary)
+        print()
+    return new_messages
+
+
+def _history_budget_tokens(config: dict[str, Any]) -> tuple[int, int]:
+    """Return (warn, critical) history-token thresholds derived from the ACTUAL
+    system prompt size and the server's input budget.
+
+    v1.3–v1.7 hardcoded warn=1,300 on a comment claiming the base prompt was
+    ~1,000 tokens. It is really ~2,100, so auto-compact fired ~900 tokens PAST
+    the degradation cliff — i.e. the safety net never once fired in time, which
+    is what made multi-turn coding sessions collapse from turn 4 (see
+    docs/V2_PLAN.md §14). Measuring the prompt instead of guessing keeps this
+    honest when the prompt changes again.
+    """
+    override = config.get("context_warn_tokens")
+    if override:
+        return int(override), int(override) * 5 // 4
+    ag = _agent()
+    try:
+        base = ag.estimate_tokens(ag.build_autopilot_prompt(
+            cwd=str(Path.cwd()), max_steps=int(config.get("max_agent_steps", 15)),
+        ))
+    except Exception:
+        base = 2_100
+    window = int(config.get("context_window_tokens") or _DEFAULT_INPUT_BUDGET_TOKENS)
+    warn = max(_MIN_HISTORY_BUDGET_TOKENS, window - base - _TURN_OVERHEAD_TOKENS)
+    return warn, warn * 5 // 4
+
+
+def context_fill_percent(session: dict[str, Any] | None, config: dict[str, Any]) -> int:
+    """How full the history budget is, 0-100: 0 on a fresh session, 100 when
+    the next turn will auto-compact. The prompt shows it as a small gauge."""
+    msgs = (session or {}).get("messages", []) or []
+    if not msgs:
+        return 0
+    ag = _agent()
+    est = ag._TOKEN_ESTIMATOR.estimate(sum(len(m.get("content", "")) for m in msgs))
+    warn, _ = _history_budget_tokens(config)
+    return max(0, min(100, round(100 * est / max(warn, 1))))
+
+
+def _maybe_auto_compact(
+    config: dict[str, Any],
+    session: dict[str, Any],
+    sessions: list[dict[str, Any]],
+) -> None:
+    """Silently compact history when the NEXT turn would cross the 4B
+    instruction-following cliff.
+
+    Fires after each autopilot turn. The threshold is derived from the actual
+    system-prompt size (see _history_budget_tokens), not a hardcoded guess.
+    The full summary is suppressed (quiet=True); only a one-line notice prints.
+
+    Thrash guard: before 2.5.0's window-derived budget, a 2,200-token prompt
+    clamped the history budget to the 250-token floor (now ~850 against a
+    3,696-token server budget), and the compacted tail usually exceeded it —
+    so v2.2 re-fired every single turn, shredding the condensed block a little
+    further each time while freeing almost nothing (the user-reported "by the
+    time it compacts, it autocompacts again by the next message"). The
+    deterministic compactor is instant and idempotent, so dry-run it first and
+    fire only when it would actually reclaim meaningful room.
+    """
+    ag = _agent()
+    msgs = session.get("messages", [])
+    est = ag._TOKEN_ESTIMATOR.estimate(sum(len(m.get("content", "")) for m in msgs))
+    warn_tokens, _ = _history_budget_tokens(config)
+    if est < warn_tokens:
+        return
+    use_llm = bool(config.get("auto_compact_uses_llm", False))
+    if not use_llm:
+        probe: dict[str, Any] = {"messages": msgs}
+        est_after = ag._TOKEN_ESTIMATOR.estimate(sum(
+            len(m.get("content", ""))
+            for m in compact_history_deterministic(probe)))
+        if est - est_after < _AUTO_COMPACT_MIN_GAIN_TOKENS:
+            return
+    # One line, after the fact, no numbers — token detail lives in /stats.
+    # The slow LLM path announces itself first so the pause is explained;
+    # the deterministic path is instant and needs no preamble.
+    try:
+        if use_llm:
+            cprint("  Compacting chat history...", C.BCYAN)
+            ag.compact_history(config, session, quiet=True)
+        else:
+            compact_history_deterministic(session)
+        ag.sync_session_store(sessions, session)
+        cprint("  Chat history compacted.", C.DIM)
+    except ag.UserCancelled:
+        cprint("  Auto-compact cancelled. Run /compact manually.", C.YELLOW)
+    except Exception as exc:  # noqa: BLE001
+        cprint(f"  Auto-compact failed ({exc}). Run /compact manually.", C.YELLOW)

hexcli/config.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""hexcli.config — defaults, load/merge, and the /config value tables,
+lifted out of agent.py.
+
+DEFAULT_CONFIG is re-bound in agent.py as the same dict object, so every
+existing sa.DEFAULT_CONFIG reader (and {**sa.DEFAULT_CONFIG, ...} test
+fixture) sees the canonical table.
+
+Split stage 5 (docs/V2X_ROADMAP.md, "The Split"). Bodies moved verbatim.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from hexcli.tools import DEFAULT_TIMEOUT_SECONDS
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "backend": "ollama",
+    "model": "qwen2.5-coder:7b",
+    "temperature": 0.1,
+    "timeout_seconds": DEFAULT_TIMEOUT_SECONDS,
+    "max_output_tokens": 512,
+    "autopilot_max_output_tokens": 2048,
+    "compact_max_output_tokens": 512,
+    "max_agent_steps": 15,
+    "tool_output_limit": 12000,
+    # Compiled Genie window. Per-step tool output is budgeted against it so a
+    # single tool result can never overflow the window (an overflow returns
+    # an EMPTY generation — measured 2026-09-01). Raise only with a bigger
+    # bundle.
+    "context_window_tokens": 3000,
+    "prewarm_after_turn": True,
+    "history_retention_days": 30,
+    "shell_exe": "",
+    "use_streaming": True,
+    # Render streamed answers live (text as it arrives, tool intent announced
+    # early). Off = the old token-counter behaviour.
+    "live_streaming": True,
+    # Print a diff after every successful file mutation.
+    "show_diffs": True,
+    # Network policy for fetch_url, the agent's only outbound channel:
+    # "ask" (default) confirms each fetch and denies when non-interactive;
+    # "allow" fetches silently; "deny" disables the tool and drops its schema.
+    "network_access": "ask",
+    # Omit the procedural rules (13/14) when the query cannot trigger them.
+    # OFF by default on measured evidence: it saves ~330 prompt tokens and 16%
+    # of first-token latency, but extended trap-4 went 5/8 -> 3/18 across three
+    # independent A/B runs (Fisher p~=0.017). See docs/V2_PLAN.md §14.15.
+    # Opt in only with a bigger-context bundle or a different model.
+    "conditional_rules": False,
+    "prompt_split": True,
+    # Byte-stable system prompt (date/cwd move to the first user message).
+    # Precondition for KV prefix reuse; default flips after the A/B.
+    "prompt_stable_prefix": False,
+    # Rich input line: persistent history, Tab completion, multi-line paste.
+    # Falls back to bare input() automatically when stdin/stdout is not a tty.
+    "rich_input": True,
+    "side_padding": 2,
+    "input_history_file": "",
+    "input_history_limit": 500,
+    # Input box pinned at the bottom with a status line under it (context
+    # fill, NPU load, memory in use). Needs rich_input and a console.
+    "status_bar": True,
+    # Light background band behind your echoed messages in the transcript.
+    "user_highlight": True,
+    # After an unverified file mutation, deflect the first "done" once and ask
+    # the agent to check its work. (Was read from config but declared nowhere,
+    # so `/config require_verification false` reported an unknown key.)
+    "require_verification": True,
+    # Confine file MUTATIONS to the working directory (reads stay free).
+    "workspace_write_scope": True,
+    # Extra roots the agent may write to (absolute paths, ~ expanded).
+    "workspace_write_allow": [],
+    "telemetry_enabled": True,
+    "chat_log_enabled": True,
+    "chat_log_dir": "",
+    "memory_enabled": True,
+    # The dreaming consolidation daemon is OFF by default: measured 2026-08-16
+    # writing the same five fabricated machine "facts" (wrong CPU, wrong RAM,
+    # an invented temperature) into memory_rules.md every idle cycle, which
+    # workspace_snapshot then injected as "Prior knowledge" — locking the
+    # model's hardware confabulations in permanently. V2X_ROADMAP already
+    # ruled it ships only with a quality eval; the eval now exists and it
+    # failed it. Re-enable only with new evidence.
+    "memory_dreaming": False,
+    "autopilot_confirm_destructive": True,
+    # Sensitive-data command gate (ssh keys, credential stores, security
+    # files, obfuscated execution). Separate from the destructive flag so
+    # injection defense holds even when destructive confirms are disabled.
+    "autopilot_confirm_sensitive": True,
+    # Agent protocol: "v1" (JSON action loop) or "v2" (native tool-call format,
+    # payload-block edits, persistent shell — see docs/V2_PLAN.md §5).
+    "protocol": "v1",
+    # Auto-compact is deterministic (no LLM call) by default: summarising via
+    # the same model that is already at its context cliff produced unverified
+    # summaries and cost a full extra re-prefill. Set true to restore the
+    # LLM summariser for auto-compact; explicit /compact always uses it.
+    "auto_compact_uses_llm": False,
+    # Override the derived history budget (tokens). Empty = derive from the
+    # measured system-prompt size.
+    "context_warn_tokens": 0,
+    # Local escalation ladder (docs/V2_PLAN.md §4): name of a bigger local
+    # npurun model to consult at hard moments (loop trips, ignored
+    # verification, prose-instead-of-edit). Empty = disabled. The server is
+    # spawned lazily on the bind address below and reused for the session.
+    "escalation_local_model": "",
+    "escalation_local_bind": "127.0.0.1:11436",
+    "escalation_max_output_tokens": 900,
+    "escalation_timeout_seconds": 240,
+    "ollama": {"host": "http://127.0.0.1:11434"},
+    "openai_compatible": {
+        "base_url": "http://127.0.0.1:8000/v1",
+        "api_key": "local",
+    },
+    "anthropic_api_key": "",
+    "escalation_model": "claude-haiku-4-5-20251001",
+}
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def ensure_default_config(path: Path) -> None:
+    if not path.exists():
+        payload = json.dumps(DEFAULT_CONFIG, indent=2) + "\n"
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(payload, encoding="utf-8")
+        tmp.replace(path)
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    ensure_default_config(path)
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    config = deep_merge(DEFAULT_CONFIG, data)
+    # Per-project override: .shellai/config.json in cwd deep-merges on top.
+    project_cfg = Path.cwd() / ".shellai" / "config.json"
+    if project_cfg != path and project_cfg.exists():
+        try:
+            with project_cfg.open("r", encoding="utf-8") as fh:
+                project_data = json.load(fh)
+            config = deep_merge(config, project_data)
+        except Exception:
+            pass
+    return config
+
+
+_CONFIG_SETTABLE: dict[str, str] = {
+    "model":                          "str",
+    "temperature":                    "float",
+    "timeout_seconds":                "int",
+    "max_output_tokens":              "int",
+    "autopilot_max_output_tokens":    "int",
+    "compact_max_output_tokens":      "int",
+    "max_agent_steps":                "int",
+    "tool_output_limit":              "int",
+    "context_window_tokens":          "int",
+    "prewarm_after_turn":             "bool",
+    "history_retention_days":         "int",
+    "use_streaming":                  "bool",
+    "live_streaming":                 "bool",
+    "workspace_write_scope":          "bool",
+    "workspace_write_allow":          "list",
+    "require_verification":           "bool",
+    "show_diffs":                     "bool",
+    "conditional_rules":              "bool",
+    "prompt_split":                   "bool",
+    "prompt_stable_prefix":           "bool",
+    "network_access":                 "str",
+    "rich_input":                     "bool",
+    "side_padding":                   "int",
+    "input_history_file":             "str",
+    "input_history_limit":            "int",
+    "status_bar":                     "bool",
+    "user_highlight":                 "bool",
+    "telemetry_enabled":              "bool",
+    "chat_log_enabled":               "bool",
+    "chat_log_dir":                   "str",
+    "memory_enabled":                 "bool",
+    "memory_dreaming":                "bool",
+    "autopilot_confirm_destructive":  "bool",
+    "autopilot_confirm_sensitive":    "bool",
+    "protocol":                       "str",
+    "auto_compact_uses_llm":          "bool",
+    "context_warn_tokens":            "int",
+    "escalation_local_model":         "str",
+    "escalation_local_bind":          "str",
+    "escalation_max_output_tokens":   "int",
+    "escalation_timeout_seconds":     "int",
+    "anthropic_api_key":              "str",
+    "escalation_model":               "str",
+}
+
+
+def _coerce_config_value(value: str, kind: str) -> Any:
+    if kind == "bool":
+        return value.lower() in ("1", "true", "yes", "on")
+    if kind == "int":
+        return int(value)
+    if kind == "float":
+        return float(value)
+    if kind == "list":
+        # Comma- or semicolon-separated; "" clears. Without this, the one
+        # setting the write-scope error message tells users to change
+        # (workspace_write_allow) could not be changed from inside the tool.
+        return [p.strip() for p in re.split(r"[;,]", value) if p.strip()]
+    return value

hexcli/diffview.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""hexcli.diffview — render what the agent actually changed.
+
+Until now a file mutation showed only "◆ edit_file" and the user had to trust
+it. The harness already holds both sides (undo snapshots are captured before
+the first write to each path), so rendering a diff costs ZERO model tokens and
+no latency — the cheapest trust feature available on 15 tok/s hardware.
+
+Pure formatting: takes before/after text, returns coloured lines. No I/O.
+"""
+from __future__ import annotations
+
+import difflib
+
+from .ui import C
+
+_MAX_HUNK_LINES = 40      # per file, before eliding the middle
+_MAX_LINE_CHARS = 200
+
+
+def render_diff(before: str | None, after: str, path: str,
+                color: bool = True, max_lines: int = _MAX_HUNK_LINES) -> str:
+    """Unified diff for one file. `before=None` means the file was created."""
+    if before is None:
+        lines = after.splitlines()
+        shown = lines[:max_lines]
+        out = [_head(f"+ created {path} ({len(lines)} lines)", color)]
+        out += [_add("+" + _clip(ln), color) for ln in shown]
+        if len(lines) > max_lines:
+            out.append(_dim(f"  … {len(lines) - max_lines} more lines", color))
+        return "\n".join(out)
+
+    if before == after:
+        return _dim(f"  {path}: no change", color)
+
+    diff = list(difflib.unified_diff(
+        before.splitlines(), after.splitlines(),
+        lineterm="", n=2,
+    ))
+    # Drop the ---/+++ header lines; the path is in our own header.
+    body = [ln for ln in diff[2:] if ln]
+    added = sum(1 for ln in body if ln.startswith("+"))
+    removed = sum(1 for ln in body if ln.startswith("-"))
+
+    out = [_head(f"~ {path}  (+{added} −{removed})", color)]
+    if len(body) > max_lines:
+        head_n = max_lines // 2
+        tail_n = max_lines - head_n
+        shown = body[:head_n] + [f"… {len(body) - max_lines} more diff lines …"] + body[-tail_n:]
+    else:
+        shown = body
+    for ln in shown:
+        clipped = _clip(ln)
+        if ln.startswith("+"):
+            out.append(_add(clipped, color))
+        elif ln.startswith("-"):
+            out.append(_rem(clipped, color))
+        elif ln.startswith("@@"):
+            out.append(_dim(clipped, color))
+        else:
+            out.append(_plain(clipped, color))
+    return "\n".join(out)
+
+
+def render_turn_diffs(snapshots: dict[str, str | None],
+                      read_current, color: bool = True) -> str:
+    """Diffs for every path a turn touched.
+
+    `snapshots` is the undo map {resolved_path: original_or_None};
+    `read_current(path)` returns the file's text now (or None if deleted).
+    """
+    blocks: list[str] = []
+    for path, before in snapshots.items():
+        try:
+            after = read_current(path)
+        except Exception:
+            continue
+        if after is None:
+            blocks.append(_head(f"- deleted {path}", color))
+            continue
+        blocks.append(render_diff(before, after, path, color=color))
+    return "\n".join(blocks)
+
+
+def _clip(line: str) -> str:
+    return line if len(line) <= _MAX_LINE_CHARS else line[:_MAX_LINE_CHARS] + " …"
+
+
+def _head(t: str, color: bool) -> str:
+    return f"{C.BCYAN}{t}{C.RESET}" if color else t
+
+
+def _add(t: str, color: bool) -> str:
+    return f"{C.GREEN}{t}{C.RESET}" if color else t
+
+
+def _rem(t: str, color: bool) -> str:
+    return f"{C.RED}{t}{C.RESET}" if color else t
+
+
+def _dim(t: str, color: bool) -> str:
+    return f"{C.DIM}{t}{C.RESET}" if color else t
+
+
+def _plain(t: str, color: bool) -> str:
+    return t