@tiens.nguyen/gu-cli 1.0.746 → 1.0.748

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:
@@ -7999,11 +8025,13 @@ def run_agent_chat(cfg):
         "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) "
         "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, 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 "
@@ -8232,7 +8260,8 @@ 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, map it with ONE explore() call first.\n"
            if _WS_AVAILABLE else "")
         + "\nTASK (answer THIS, choose the tool that fits it):\n"
         f"{task_text}\n"
@@ -9142,38 +9171,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)

package/gu-repl.mjs

@@ -18,10 +18,10 @@
  * Conversation history is saved to ~/.gonext/sessions/<hash-of-folder-path>.json after
  * every turn and reloaded on the next `gu` in the SAME folder — so closing the
  * terminal and coming back later still has context (e.g. "continue" after an
- * interrupted investigation actually resumes it). /reset clears it.
+ * interrupted investigation actually resumes it). /new clears it.
  *
  * Requires the worker daemon to be running (it claims the job).
- * Commands: /exit  /model  /reset  /help   Ctrl-C stops following the current run.
+ * Commands: /exit  /model  /new  /help   Ctrl-C stops following the current run.
  */
 import { readFile, mkdir, writeFile, unlink, rename } from "node:fs/promises";
 import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, openSync, readSync, closeSync } from "node:fs";
@@ -577,11 +577,12 @@ if (cliVerdict.kind === "run") {
       "  -v, --verbose   show RAG index-file activity in the bottom bar (each shard written)\n" +
       "  -h, --help      this help\n\n" +
       "Auth comes from ~/.gonext/worker.env; models/budgets/RAG come from your web Settings.\n" +
-      "Inside the REPL: /exit · /model · /reset · /help — Ctrl-C stops following a turn.\n" +
+      "Inside the REPL: /exit · /model · /new · /help — Ctrl-C stops following a turn.\n" +
       "Questions are enqueued like web questions and executed by the RUNNING\n" +
       "gu-cli daemon — its terminal shows the full [gu-agent] logs.\n" +
       "Conversation history is saved per-folder in ~/.gonext/sessions and resumed next time\n" +
-      "you run `gu` in the same folder; /reset forgets it and starts fresh."
+      "you run `gu` in the same folder; /new starts a new conversation and keeps the old one\n" +
+      "in ~/.gonext/sessions/archive."
   );
   process.exit(0);
 }
@@ -814,6 +815,9 @@ const COMMANDS = [
   { name: "/doctor", desc: "check every configured model ANSWERS — especially the embedder, which a turn only reaches after several steps" },
   { name: "/tokens", desc: "break down the last prompt sent to the coding model — how much of it was RAG" },
   { name: "/full-log", usage: "/full-log [on|off|status] [account]", desc: "administrators: Enable Full Log for an account — asks for an admin token from the web admin page first" },
+  // ONE name, /new (user, #278). /reset and /clear still work (HIDDEN_COMMANDS) for habit and
+  // for Claude Code users — not to be confused with `gu clear` in a shell, which wipes gu's state.
+  { name: "/new", desc: "start a new conversation in this folder — the old one is kept (archived); the folder's settings stay" },
   { name: "/hooks", usage: "/hooks [list|approve|unapprove]", desc: "hooks: commands gu runs on onStart, onAsk, onToolDone, onTurnEnd — list them, approve this project's" },
   { name: "/mcp", usage: "/mcp [list|tools|add|remove|enable|disable|approve|allow|disallow|reconnect]", desc: "MCP servers: see which connect, add one (asks step by step), choose which tools run without asking" },
   { name: "/help", desc: "list these commands" },
@@ -11162,7 +11166,7 @@ async function main() {
   if (history.length > 0) {
     const turns = history.filter((m) => m.role === "user").length;
     console.log(
-      wrapGutter(`Resumed session: ${turns} prior turn(s) from last time in this folder — /reset to start fresh.`, dim) + "\n"
+      wrapGutter(`Resumed session: ${turns} prior turn(s) from last time in this folder — /new starts a new conversation (this one is kept).`, dim) + "\n"
     );
   }
   // Ctrl-C arrives on ONE of two paths depending on the readline mode: with
@@ -11516,7 +11520,7 @@ async function main() {
       );
       continue;
     }
-    if (line === "/reset" || line === "/new") {
+    if (line === "/reset" || line === "/new" || line === "/clear") {
       const kept = history.length;
       const where = await startNewConversation(cwd, history);
       history.length = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.746",
+  "version": "1.0.748",
   "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",

package/terminal-layout.mjs

@@ -2077,8 +2077,8 @@ export const HIDDEN_COMMANDS = [
   "/rag-cloud",                 // they say — unlisted so /help offers one way into the setting
   "/thought",                   // the reasoning display stays ON; only the toggle is unlisted
   "/hover",                     // in-turn mouse capture — behaviour unchanged, just hidden
-  "/reset",
-  "/new",
+  "/reset",                     // the old name of /new (#278) — still works, one name is offered
+  "/clear",                     // Claude Code's name for it — still works, likewise unlisted
   "/reset-output-token-global", // pending a rename to /reset-global-token that also resets
                                 // the INPUT total — which does not exist yet as a counter
 ];