@tiens.nguyen/gu-cli 1.0.747 → 1.0.749

package/gonext_agent_chat.py

@@ -2140,8 +2140,34 @@ def _usage_reports_cache(usage) -> bool:
 # against the corrected counter so that the OBSERVED GOOD BEHAVIOUR is preserved: one pass in
 # 86 steps, firing where it fired before. Raising the counter without raising the threshold
 # would fire earlier and more often — the nibbling this whole mechanism exists to stop.
-_TRIM_FIRST_AT_CHARS = 125_000    # ≈ where a real turn's history stood when it last fired
+_TRIM_FIRST_AT_CHARS = 90_000     # was 125k: a first trim frees most of the history, so it pays
+                                  # back fast — the payback gate below keeps that honest
 _TRIM_AGAIN_AFTER_CHARS = 60_000  # …and not again until it has grown this much further
+# A trim REWRITES the history into the prompt cache, so it is only worth it when the smaller
+# prompt repays that within a few steps (task #279). Prices relative to a normal input token:
+# Anthropic cache write 1.25x (5-minute TTL), cache read 0.1x. Measured 2026-09-25 on one turn:
+# trim 1 (69.7k → 28.3k tokens) paid back in ~2 steps; trim 2 (54.8k → 38.6k) needed ~15 and
+# only 3 followed, so it cost ~18k more than it saved.
+_TRIM_PAYBACK_STEPS = 5
+_CACHE_WRITE_X = 1.25
+_CACHE_READ_X = 0.1
+
+
+def _trim_payback_steps(history_chars: int, freed_chars: int) -> float:
+    """How many later steps a trim needs to repay its cache cost. inf when it frees nothing.
+
+    After a trim, the history that remains is written to the cache once instead of read
+    (costing WRITE - READ more per token); every later step then reads `freed` fewer tokens
+    (saving READ each). Chars stand in for tokens — only the ratio matters.
+    """
+    if freed_chars <= 0:
+        return float("inf")
+    remaining = max(0, history_chars - freed_chars)
+    return ((_CACHE_WRITE_X - _CACHE_READ_X) * remaining) / (_CACHE_READ_X * freed_chars)
+
+
+def _trim_pays_back(history_chars: int, freed_chars: int, limit: float = _TRIM_PAYBACK_STEPS) -> bool:
+    return _trim_payback_steps(history_chars, freed_chars) <= limit
 
 
 def _step_memory_chars(steps) -> int:
@@ -7994,16 +8020,24 @@ def run_agent_chat(cfg):
         # ORDER to use them in and the CONSTRAINTS that bite — so keep those, drop the third
         # retelling. Every rule below is a scar: token waste (#63/#79), no-shell/no-sudo,
         # key-only deploys (#57).
-        "    THE EDIT LOOP: grep_repo to LOCATE → read_file_lines around the hit (a SMALL "
-        "range; never re-read the whole file or the same range twice — large reads are "
-        "truncated and slow every later step) → edit_lines to change it → run_command to "
-        "VERIFY. edit_file only for a byte-exact unique string; create_file(overwrite=True) "
+        # Task #48 (GitHub): string edits are the default, like Claude Code's Edit tool. A
+        # line-number edit needs a fresh read before every edit (each one shifts the numbers):
+        # a measured turn spent 12 of its 43 steps on read → edit_lines → read → edit_lines.
+        "    THE EDIT LOOP: LOCATE (explore, grep_repo) → read_file_lines ONCE around what you will "
+        "change (a SMALL range; never re-read the whole file or the same range twice) → make ALL "
+        "of that file's edits in ONE block with edit_file(path, old_string, new_string), quoting "
+        "a short UNIQUE snippet from what you read — no line numbers, so no re-read between "
+        "edits → VERIFY with run_command (in the same block when you can). edit_lines only when "
+        "you cannot quote a unique string (e.g. replacing a long range); create_file(overwrite=True) "
         "replaces a whole file in ONE call (no read+edit just to rewrite it).\n"
-        "    EXPLORE FIRST for a broad question about the code (where is X handled, how does Y "
-        "work, what would a change to Z touch): explore(question) searches in a SEPARATE "
-        "context and returns a short summary with path:line references — its greps and reads "
-        "do not pile up here. Use grep_repo/read_file_lines directly when you already know "
-        "the file or the exact string.\n"
+        "    EXPLORE FIRST — before CHANGING code you have not seen yet in this conversation "
+        "(always for a change that spans several files or layers — frontend + backend, UI + API), "
+        "and for any broad question (where is X handled, how does Y work, what would a change to Z "
+        "touch): call explore(question) ONCE to map the files and lines involved. It searches in "
+        "a SEPARATE context and returns a short summary with path:line references, so its greps "
+        "and reads do not pile up here and are not re-sent on every later step. Then read only "
+        "the exact ranges you will edit. Use grep_repo/read_file_lines directly when you already "
+        "know the file or the exact string.\n"
         "    run_command CHAINS: put dependent commands in ONE call with && — e.g. "
         "run_command(\"cd app && ./gradlew assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk\") "
         "— they run in order, `cd` sets the folder for the rest, and the first failure stops the "
@@ -8043,12 +8077,11 @@ def run_agent_chat(cfg):
         "- user asks to FIX A BUG / MODIFY / ADD CODE in a workspace -> "
         "grep_repo(pattern) when you know the exact string, or rag_search_workspace(query) "
         "when you do not, to FIND the file, THEN "
-        "read_file_lines(file, around the hit) to see exact lines, THEN "
-        "edit_lines(file, start, end, new_content) to change them, THEN "
+        "read_file_lines(file, around the hit) ONCE, THEN edit_file(file, old_string, new_string) "
+        "for EACH change to that file — all in ONE block —, THEN "
         "run_command('…test…') to VERIFY if run permission exists — read failures and fix, "
         "iterate. Finish with final_answer summarizing WHAT you changed (files + lines). "
-        "AFTER editing, re-read with grep_repo/read_file_lines (an indexed knowledge base may be "
-        "stale — do not trust rag_search for freshly edited code).\n"
+        "Do not trust rag_search for freshly edited code (the index may be stale).\n"
     ) if _WS_AVAILABLE else ""
     _email_choose_line = (
         "- 'email …' / 'send an email to …' -> send_email(to, subject, body) "
@@ -8232,7 +8265,9 @@ def run_agent_chat(cfg):
         # the cached reference above. Workspace/coding mode only.
         + ("Remember: FINISH what was asked yourself — fix blockers, VERIFY the outcome, then "
            "final_answer with evidence; never hand the task back. If it only asks to RECORD work "
-           "(create a task, a note, a plan), recording it IS the task — do not start the work.\n"
+           "(create a task, a note, a plan), recording it IS the task — do not start the work. "
+           "To change code you have not seen yet — especially across several files — map it with "
+           "ONE explore() call first, then make each file's edits in ONE block with edit_file.\n"
            if _WS_AVAILABLE else "")
         + "\nTASK (answer THIS, choose the tool that fits it):\n"
         f"{task_text}\n"
@@ -9142,38 +9177,47 @@ def run_agent_chat(cfg):
             # context is not big enough for that trade to pay, so history is left ALONE and
             # every step appends cleanly onto a cached prefix.
             if _steps and len(_steps) > 2 and _trim_due(_mem_chars, _trim_state):
-                _trim_n, _trim_saved = 0, 0
+                # PLAN FIRST, then apply only if it pays back its cache cost (task #279): a
+                # trim rewrites the history into the cache, and one that frees little costs
+                # more than it saves. Each edit is (object, attribute, new value, chars freed).
+                _plan = []
                 for _st in _steps[:-2]:
                     _obs = getattr(_st, "observations", None)
                     if isinstance(_obs, str) and len(_obs) > 900:
-                        _before = len(_obs)
-                        _st.observations = (
-                            _obs[:400].rstrip()
-                            + "\n…[earlier observation trimmed to save context — "
-                            "re-read the file/dir with a small range if you still need it]")
-                        _trim_n += 1
-                        _trim_saved += _before - len(_st.observations)
+                        _new = (_obs[:400].rstrip()
+                                + "\n…[earlier observation trimmed to save context — "
+                                "re-read the file/dir with a small range if you still need it]")
+                        _plan.append((_st, "observations", _new, len(_obs) - len(_new)))
                     _mo = getattr(_st, "model_output", None)
                     if isinstance(_mo, str) and len(_mo) > 700:
-                        _before = len(_mo)
                         # Keep the Thought (everything before the code block); the code is
                         # redundant with the observation that already came back.
                         _head = re.split(r"<code[\s>]|```", _mo, maxsplit=1)[0].rstrip()
                         _kept = (_head[:500].rstrip() if _head else _mo[:300].rstrip())
                         _new = _kept + "\n…[code trimmed to save context — its result is in the Observation]"
-                        if len(_new) < _before:
-                            _st.model_output = _new
-                            _trim_n += 1
-                            _trim_saved += _before - len(_new)
-                    # The SAME code, a second time: smolagents keeps the parsed code
-                    # action in step.tool_calls and renders it as its own message on
-                    # every request, so stripping <code> from model_output above saved
-                    # nothing on its own. Trim the duplicate too — see
-                    # _trim_tool_call_args for why this is safe.
-                    _tc_saved = _trim_tool_call_args(_st, 300)
-                    if _tc_saved:
+                        if len(_new) < len(_mo):
+                            _plan.append((_st, "model_output", _new, len(_mo) - len(_new)))
+                    # The SAME code, a second time: smolagents keeps the parsed code action in
+                    # step.tool_calls and renders it as its own message on every request, so
+                    # stripping <code> from model_output above saves nothing on its own. See
+                    # _trim_tool_call_args for why trimming the duplicate is safe.
+                    for _tc in (getattr(_st, "tool_calls", None) or []):
+                        _a = getattr(_tc, "arguments", None)
+                        if isinstance(_a, str) and len(_a) > 300:
+                            _new = _a[:300].rstrip() + _CODE_TRIMMED_MARK
+                            if len(_new) < len(_a):
+                                _plan.append((_tc, "arguments", _new, len(_a) - len(_new)))
+                _freed = sum(p[3] for p in _plan)
+                _trim_n, _trim_saved = 0, 0
+                if _trim_pays_back(_mem_chars, _freed):
+                    for _obj, _attr, _new, _gain in _plan:
+                        setattr(_obj, _attr, _new)
                         _trim_n += 1
-                        _trim_saved += _tc_saved
+                        _trim_saved += _gain
+                else:
+                    _log(f"context trim skipped: would free ~{_freed} of {_mem_chars} chars — "
+                         f"repays its cache rewrite only after ~{_trim_payback_steps(_mem_chars, _freed):.0f} "
+                         f"steps (> {_TRIM_PAYBACK_STEPS})")
                 # Arm the next pass off the size we actually reached, so a big win buys a
                 # long quiet period and a small one cannot re-fire next step.
                 _note_trimmed(_step_memory_chars(_steps), _trim_state)
@@ -11563,7 +11607,7 @@ def run_agent_chat(cfg):
 
         @tool
         def edit_lines(path: str, start_line: int, end_line: int, new_content: str) -> str:
-            """Replace lines start_line..end_line (inclusive, 1-based) of a workspace file with new_content. The PRIMARY edit tool — get exact line numbers from grep_repo/read_file_lines first. A backup is saved automatically.
+            """Replace lines start_line..end_line (inclusive, 1-based) of a workspace file with new_content. Use it only when you cannot quote a unique string for edit_file (e.g. replacing a long range). Line numbers shift after every edit, so re-read before another edit_lines in the same file. A backup is saved automatically.
 
             Args:
                 path: file inside a registered workspace.
@@ -11620,7 +11664,7 @@ def run_agent_chat(cfg):
 
         @tool
         def edit_file(path: str, old_string: str, new_string: str) -> str:
-            """Replace an EXACT unique text occurrence in a workspace file (must match byte-for-byte incl. whitespace). Prefer edit_lines when you have line numbers. A backup is saved automatically.
+            """The PRIMARY edit tool: replace an EXACT, unique text occurrence in a workspace file (byte-for-byte, incl. whitespace). It needs no line numbers, so several edit_file calls to one file go in ONE block after a single read. A backup is saved automatically.
 
             Args:
                 path: file inside a registered workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.747",
+  "version": "1.0.749",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",