python-agent-harness 1.5.6.2__tar.gz → 1.5.6.3__tar.gz

{python_agent_harness-1.5.6.2/python_agent_harness.egg-info → python_agent_harness-1.5.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.6.2
+Version: 1.5.6.3
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.6.2"
+version = "1.5.6.3"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 authors = [
     {name = "Huming Chen", email = "chenhuming@gmail.com"}

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/__init__.py

@@ -8,7 +8,7 @@ from .mcp.config import MCPConfig, MCPServerConfig
 from .mcp.manager import MCPManager
 from .session.session import Session
 
-__version__ = "1.5.6.2"
+__version__ = "1.5.6.3"
 
 __all__ = [
     "Client",

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/core/models.py

@@ -5,9 +5,30 @@ from __future__ import annotations
 import base64
 import enum
 import json
+import re
 from dataclasses import dataclass, field
 from typing import Any, Union
 
+# Lone surrogates (\ud800-\udfff) reach a str when a file is decoded with
+# errors="surrogateescape" — which every tool deliberately does, so a
+# non-UTF-8 source file round-trips instead of becoming U+FFFD.  Such a
+# string cannot be encoded to UTF-8, so anything that leaves the process
+# (a JSON request body, a terminal write) must replace them first.
+_SURROGATE_RE = re.compile(r"[\ud800-\udfff]")
+
+
+def api_safe(text: str) -> str:
+    """TEXT with lone surrogates replaced by U+FFFD, safe to serialize.
+
+    The tools read files with ``errors="surrogateescape"``, so a
+    conversation can carry lone surrogates from a non-UTF-8 (Latin-1,
+    GBK, ...) source.  A request body containing one cannot be encoded
+    to UTF-8 — ``httpx`` raised ``UnicodeEncodeError`` — so they are
+    replaced at the OUTBOUND boundary only: the stored history, the
+    session file and the file on disk keep the exact bytes.
+    """
+    return _SURROGATE_RE.sub("\ufffd", text)
+
 
 class AgentMode(enum.Enum):
     BUILD = "build"
@@ -136,7 +157,10 @@ class Message:
     def to_api(self) -> dict[str, Any]:
         d: dict[str, Any] = {"role": self.role}
         if self.content is not None:
-            d["content"] = self._api_content()
+            content = self._api_content()
+            # outbound boundary: a lone surrogate cannot be encoded into
+            # the JSON body (see api_safe)
+            d["content"] = api_safe(content) if isinstance(content, str) else content
         if self.tool_calls:
             d["tool_calls"] = [
                 {
@@ -144,9 +168,13 @@ class Message:
                     "type": "function",
                     "function": {
                         "name": tc.name,
-                        "arguments": tc.arguments
-                        if isinstance(tc.arguments, str)
-                        else json.dumps(tc.arguments, ensure_ascii=False),
+                        # ensure_ascii=False keeps non-ASCII readable;
+                        # api_safe then removes the unencodable surrogates
+                        "arguments": api_safe(
+                            tc.arguments
+                            if isinstance(tc.arguments, str)
+                            else json.dumps(tc.arguments, ensure_ascii=False)
+                        ),
                     },
                 }
                 for tc in self.tool_calls
@@ -188,7 +216,11 @@ class Message:
     @staticmethod
     def _part_to_api(part: ContentPart) -> Any:
         """Serialize one content part to its provider-specific dict."""
-        if isinstance(part, (TextPart, ImagePart)):
+        if isinstance(part, TextPart):
+            # text parts are a second carrier of file content into the
+            # payload, so they need the same outbound treatment
+            return {"type": "text", "text": api_safe(part.text)}
+        if isinstance(part, ImagePart):
             return part.to_api()
         return part
 

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/entry/headless.py

@@ -22,6 +22,7 @@ import sys
 import threading
 from typing import Any, TextIO
 
+from ..core.models import api_safe
 from ..io.text_filter import strip_final_check
 from ..session.session import Session
 from .controller import Controller
@@ -166,7 +167,13 @@ def final_answer_text(session: Session) -> str:
             continue
         text = strip_final_check(msg.text_without_reasoning()).strip()
         if text:
-            return text
+            # api_safe: the answer is written to stdout (headless prints it
+            # verbatim; --json and serve JSON-encode it), and a lone
+            # surrogate from a restored non-UTF-8 session raised
+            # UnicodeEncodeError there — headless died before writing the
+            # result line, and serve's _write_line SWALLOWED it (it is a
+            # ValueError), reporting success with an empty stream.
+            return api_safe(text)
     return ""
 
 
@@ -295,7 +302,10 @@ def restore_session(controller: Controller, spec: str, err: TextIO) -> bool:
     if not path or not os.path.isfile(path):
         err.write(f"no session found: {spec or 'latest'}\n")
         return False
-    with open(path, encoding="utf-8") as fh:
+    # surrogateescape must mirror SessionPersistence.save: the saved body
+    # may carry lone surrogates (the tools read non-UTF-8 files that way),
+    # and a strict decode raised UnicodeDecodeError here.
+    with open(path, encoding="utf-8", errors="surrogateescape") as fh:
         text = fh.read()
     meta = SessionPersistence.parse_metadata(text)
     body = SessionPersistence.strip_metadata(text)
@@ -417,7 +427,10 @@ def run_headless(
         return 1
     answer = final_answer_text(session)
     if answer:
-        view.out.write(answer + "\n")
+        # api_safe: the answer carries whatever the conversation carried
+        # (a restored non-UTF-8 session), and a strict-UTF-8 stdout
+        # raised UnicodeEncodeError here — losing the result line.
+        view.out.write(api_safe(answer) + "\n")
         view.out.flush()
     return 1 if view.errors else 0
 
@@ -512,7 +525,11 @@ class JsonlView(HeadlessView):
         line = {"seq": self._seq, "protocol": PROTOCOL_VERSION, **payload}
         if self.run_id is not None:
             line["run_id"] = self.run_id
-        self.out.write(json.dumps(line, ensure_ascii=False, default=str) + "\n")
+        # api_safe at the sink: the JSON body is written to the driver's
+        # stdout, and a lone surrogate (restored non-UTF-8 session) made
+        # the write raise UnicodeEncodeError — the run then ended without
+        # its terminal `result` line.
+        self.out.write(api_safe(json.dumps(line, ensure_ascii=False, default=str)) + "\n")
         self.out.flush()
 
     def _emit(self, payload: dict[str, Any]) -> None:

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/entry/server.py

@@ -127,6 +127,7 @@ import time
 import uuid
 from typing import Any, TextIO
 
+from ..core.models import api_safe
 from ..session.session import Session
 from .controller import Controller
 from .headless import PROTOCOL_VERSION, JsonlView, _restorable_handler, final_answer_text
@@ -530,7 +531,11 @@ class AgentServer:
         live run lines get ``seq``/``run_id`` via the view's ``_write``.
         """
         text = (
-            json.dumps({"protocol": PROTOCOL_VERSION, **payload}, ensure_ascii=False, default=str)
+            api_safe(
+                json.dumps(
+                    {"protocol": PROTOCOL_VERSION, **payload}, ensure_ascii=False, default=str
+                )
+            )
             + "\n"
         )
         view = self.view
@@ -892,7 +897,19 @@ class AgentServer:
     def _read_ops(self) -> None:
         """The reader loop proper: dispatch ops until EOF/shutdown."""
         while not self._stopped.is_set():
-            line = self.inp.readline()
+            try:
+                line = self.inp.readline()
+            except (UnicodeDecodeError, ValueError, OSError) as e:
+                # Unreadable input must never take the resident process
+                # down.  A single non-UTF-8 byte on a strict-UTF-8 stdin
+                # (the common C.UTF-8/LANG=en_US.UTF-8 container setup)
+                # raised out of serve_forever, which skipped the run drain
+                # below: an in-flight run then emitted NO result line and
+                # its token usage was lost.  Report it as a protocol error
+                # and stop reading, so the drain still runs.  ValueError
+                # covers a stdin closed underneath us.
+                self._error("protocol", f"cannot read op: {e}")
+                break
             if not line:  # EOF: the host closed the pipe
                 break
             line = line.strip()

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/io/persistence.py

@@ -195,7 +195,16 @@ class SessionPersistence:
             session_dir().mkdir(parents=True, exist_ok=True)
             content = conversation_text.rstrip("\n") + "\n\n" + self.metadata_block() + "\n"
             tmp = path + ".tmp"
-            Path(tmp).write_text(content, encoding="utf-8")
+            # surrogateescape: the tools deliberately read files with it
+            # (see atomic_write_text / Edit._string_replace), so a
+            # conversation can legitimately carry lone surrogates from a
+            # non-UTF-8 source file.  A strict write raised
+            # UnicodeEncodeError, which is NOT an OSError, so it escaped
+            # auto_save's handler: the turn was never saved and a stray
+            # <name>.md.tmp was left behind.  The matching reads
+            # (headless restore_session, TUI /restore and /sessions) use
+            # the same error handler so the bytes round-trip.
+            Path(tmp).write_text(content, encoding="utf-8", errors="surrogateescape")
             os.replace(tmp, path)
             return path
 

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/lsp/client.py

@@ -13,6 +13,7 @@ import os
 import queue
 import subprocess
 import threading
+import time
 from pathlib import Path
 from typing import Any
 
@@ -21,6 +22,13 @@ class LSPError(RuntimeError):
     pass
 
 
+# Upper bound for one framed JSON-RPC message.  A Content-Length header is
+# untrusted input: a bogus or malicious value must not make the reader
+# reserve gigabytes.  Real LSP responses (even documentSymbol on a huge
+# file) are orders of magnitude smaller.
+MAX_MESSAGE_BYTES = 64 * 1024 * 1024
+
+
 class LSPClient:
     def __init__(self, command: list[str], root: str, language_id: str, timeout: float = 30.0):
         self.command = command
@@ -39,15 +47,75 @@ class LSPClient:
         self._capabilities: dict[str, Any] = {}
         self.position_encoding = "utf-16"
         self._closed = False
+        # Set when the reader thread exits for ANY reason other than an
+        # explicit close(): the transport can no longer deliver responses,
+        # so the client must count as dead even while the child process is
+        # still running (a framing error, a crashed/hung server).  Without
+        # this, `alive` kept reporting True and `manager.get_client` never
+        # replaced the broken client -- every later LSP call then burned
+        # the full request timeout for the rest of the session.
+        self._reader_dead = False
+        # Identity of the CURRENT reader thread's generation.  A reader
+        # superseded by start() can finish after the new one is installed;
+        # without this counter it would mark the fresh (healthy) transport
+        # dead in its finally block -- the proc identity check alone does
+        # not cover the window before the new proc is assigned.
+        self._reader_gen = 0
+        # True while start() is running its initialize handshake.  start()
+        # reaches request(), which calls start_if_needed(): a server that
+        # dies immediately leaves `alive` False, so without this flag each
+        # level re-entered start() -- spawning another process -- until
+        # RecursionError instead of a clean "failed to start" error.
+        self._starting = False
 
     @property
     def alive(self) -> bool:
-        return self.proc is not None and self.proc.poll() is None and not self._closed
+        return (
+            self.proc is not None
+            and self.proc.poll() is None
+            and not self._closed
+            and not self._reader_dead
+        )
 
     def start(self) -> None:
-        if self.alive:
+        """Start the server if it is not already running.
+
+        Re-entrancy-safe: ``_start()`` performs the initialize handshake
+        through ``request()``, which calls ``start_if_needed()``.  A server
+        that dies immediately (reader EOF before the request is written)
+        leaves ``alive`` False, so without the ``_starting`` guard every
+        level re-entered ``start()`` and spawned another process until
+        RecursionError.  With the guard the inner call is a no-op and the
+        handshake fails fast with a clean LSPError.
+        """
+        if self.alive or self._starting:
             return
+        self._starting = True
+        try:
+            self._start()
+        finally:
+            self._starting = False
+
+    def _start(self) -> None:
+        # Invalidate any superseded reader FIRST: _release_proc() below
+        # unblocks it, and if it reached its finally block while the
+        # generation still matched it would mark this fresh transport dead
+        # (and fail its waiters) before the replacement is installed.
+        self._reader_gen += 1
+        # A previous child can still be running when only the reader died
+        # (framing error / crashed transport): release it before the pipes
+        # are replaced, or the process and its descriptors leak.
+        if self.proc is not None:
+            self._release_proc()
         self._closed = False
+        self._reader_dead = False
+        # A fresh server has no documents open: forget the previous
+        # session's bookkeeping, or open_document() would send didChange
+        # for a document this process never opened.
+        with self._state_lock:
+            self._opened.clear()
+            self._texts.clear()
+        self.position_encoding = "utf-16"
         try:
             self.proc = subprocess.Popen(
                 self.command,
@@ -59,8 +127,9 @@ class LSPClient:
             )
         except OSError as e:
             raise LSPError(f"failed to start LSP server {' '.join(self.command)!r}: {e}") from e
+        gen = self._reader_gen
         self._reader = threading.Thread(
-            target=self._read_loop, daemon=True, name=f"lsp-reader:{self.command[0]}"
+            target=self._read_loop, args=(gen,), daemon=True, name=f"lsp-reader:{self.command[0]}"
         )
         self._reader.start()
         try:
@@ -111,7 +180,7 @@ class LSPClient:
             message["params"] = params
         try:
             self._send(message)
-            kind, value = waiter.get(timeout=self.timeout)
+            kind, value = self._wait_response(waiter, method)
         except queue.Empty as e:
             with self._state_lock:
                 self._pending.pop(request_id, None)
@@ -130,6 +199,27 @@ class LSPClient:
             raise LSPError(f"LSP {method} failed ({code}): {msg}")
         return value
 
+    def _wait_response(self, waiter: queue.Queue, method: str) -> tuple[str, Any]:
+        """Wait for WAITER, failing fast once the transport is dead.
+
+        The reader drains every waiter when it exits, but a request that
+        registers AFTER that drain finds an empty pending map and could
+        only wait out the full request timeout for a response nobody can
+        deliver.  Polling in slices lets the wait end as soon as the
+        transport is known to be dead.  Raises ``queue.Empty`` on a real
+        timeout so the caller keeps its single timeout message.
+        """
+        deadline = time.monotonic() + self.timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise queue.Empty
+            try:
+                return waiter.get(timeout=min(0.1, remaining))
+            except queue.Empty:
+                if self._reader_dead:
+                    raise LSPError(f"LSP server exited while waiting for {method}") from None
+
     def notify(self, method: str, params: Any = None) -> None:
         self.start_if_needed()
         message: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
@@ -149,6 +239,7 @@ class LSPClient:
         # write can deadlock the reader thread (which needs _state_lock to
         # deliver responses/diagnostics) if the pipe buffer fills.
         with self._state_lock:
+            gen = self._reader_gen
             version = self._opened.get(uri, 0)
             if version:
                 if self._texts.get(uri) == text:
@@ -174,6 +265,16 @@ class LSPClient:
                     }
                 }
         self.notify(method, params)
+        if self._reader_gen != gen:
+            # The transport restarted between the bookkeeping above and the
+            # send: start() cleared _opened, and this notification either
+            # went to a server that is gone or to a replacement that never
+            # received didOpen.  Drop the stale claim so the next call
+            # re-opens the document against the current server instead of
+            # sending didChange for a document it does not know.
+            with self._state_lock:
+                self._opened.pop(uri, None)
+                self._texts.pop(uri, None)
 
     def close_document(self, uri: str) -> None:
         with self._state_lock:
@@ -192,28 +293,20 @@ class LSPClient:
         if self._closed:
             return
         proc = self.proc
-        was_alive = proc is not None and proc.poll() is None
+        # The graceful path (shutdown request + exit notification) goes
+        # through request()/notify(), which call start_if_needed() — and
+        # with the reader dead `alive` is False, so closing would SPAWN A
+        # FRESH SERVER just to shut it down, leaking the old process.
+        # When the transport is already broken there is nobody to talk to:
+        # go straight to terminate.
+        was_alive = proc is not None and proc.poll() is None and not self._reader_dead
         if was_alive:
             with contextlib.suppress(Exception):
                 self.request("shutdown", None)
             with contextlib.suppress(Exception):
                 self.notify("exit", None)
         self._closed = True
-        proc = self.proc
-        if proc is not None and proc.poll() is None:
-            with contextlib.suppress(Exception):
-                proc.terminate()
-                proc.wait(timeout=2)
-            with contextlib.suppress(Exception):
-                proc.kill()
-        # Close the pipe file objects so their file descriptors are
-        # released (subprocess does not close them on terminate/kill —
-        # leaving them open leaks fds and emits ResourceWarning).
-        if proc is not None:
-            for stream in (proc.stdin, proc.stdout):
-                if stream is not None:
-                    with contextlib.suppress(Exception):
-                        stream.close()
+        self._release_proc()
         with self._state_lock:
             with contextlib.suppress(queue.Full):
                 for waiter in self._pending.values():
@@ -222,6 +315,33 @@ class LSPClient:
             self._opened.clear()
             self._texts.clear()
 
+    def _release_proc(self) -> None:
+        """Terminate + reap the current server process and close its pipes.
+
+        Shared by ``close()`` (explicit teardown) and ``start()`` (a
+        restart after the reader died): in the latter case the child may
+        still be running, and the pipes MUST be released either way --
+        ``subprocess`` does not close them on terminate/kill, so leaving
+        them open leaks descriptors and emits ResourceWarning.
+        """
+        proc = self.proc
+        if proc is None:
+            return
+        if proc.poll() is None:
+            with contextlib.suppress(Exception):
+                proc.terminate()
+                proc.wait(timeout=2)
+            with contextlib.suppress(Exception):
+                proc.kill()
+            # Reap the killed child so it does not linger as a zombie
+            # until subprocess's global cleanup runs.
+            with contextlib.suppress(Exception):
+                proc.wait(timeout=2)
+        for stream in (getattr(proc, "stdin", None), getattr(proc, "stdout", None)):
+            if stream is not None:
+                with contextlib.suppress(Exception):
+                    stream.close()
+
     def _send(self, message: dict[str, Any]) -> None:
         data = json.dumps(message, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
         packet = b"Content-Length: " + str(len(data)).encode("ascii") + b"\r\n\r\n" + data
@@ -235,16 +355,24 @@ class LSPClient:
             except OSError as e:
                 raise LSPError(f"failed writing to LSP server: {e}") from e
 
-    def _read_loop(self) -> None:
+    def _read_loop(self, gen: int | None = None) -> None:
+        proc = self.proc
         try:
-            proc = self.proc
             if proc is None or proc.stdout is None:
                 return
             stream = proc.stdout
             while not self._closed:
                 headers: dict[str, str] = {}
                 while True:
-                    line = stream.readline()
+                    try:
+                        line = stream.readline()
+                    except (ValueError, OSError):
+                        # close() may release the pipes while this thread
+                        # is parked in a read; that surfaces here as a
+                        # closed-file/most-unblocked error.  Treat it as
+                        # EOF instead of letting a traceback escape a
+                        # daemon thread.
+                        return
                     if not line:
                         return
                     line = line.rstrip(b"\r\n")
@@ -259,8 +387,14 @@ class LSPClient:
                     length = int(headers.get("content-length", "0"))
                 except ValueError:
                     continue
-                payload = stream.read(length)
-                if len(payload) != length:
+                if length < 0 or length > MAX_MESSAGE_BYTES:
+                    # Unusable framing: a bogus/huge header must not make
+                    # read() reserve gigabytes, and a negative one can
+                    # never be satisfied.  Stop reading; the finally block
+                    # marks the transport dead so the server is replaced.
+                    return
+                payload = self._read_exactly(stream, length)
+                if payload is None:
                     return
                 try:
                     message = json.loads(payload.decode("utf-8"))
@@ -268,12 +402,57 @@ class LSPClient:
                     continue
                 self._handle_message(message)
         finally:
-            with self._state_lock:
-                pending = list(self._pending.values())
-                self._pending.clear()
-            with contextlib.suppress(queue.Full):
+            # Mark the transport dead for every exit path except an
+            # explicit close(): `alive` must go False so the manager
+            # replaces this client instead of sending requests into a
+            # pipe nobody reads (which only produced timeouts).  Both
+            # guards matter: a superseded reader (start() installed a
+            # replacement) must not kill the fresh transport, and a
+            # concurrent close() already owns the flag.
+            current = (gen is None or gen == self._reader_gen) and self.proc is proc
+            if current:
+                self._reader_dead = True
+                # Only the CURRENT reader owns this client's waiters: a
+                # superseded reader exiting during a restart must not fail
+                # requests that belong to the replacement transport.
+                with self._state_lock:
+                    pending = list(self._pending.values())
+                    self._pending.clear()
                 for waiter in pending:
-                    waiter.put_nowait(("error", {"message": "LSP server exited"}))
+                    # Per waiter: one already-filled queue must not stop
+                    # the rest from being notified.
+                    with contextlib.suppress(queue.Full):
+                        waiter.put_nowait(("error", {"message": "LSP server exited"}))
+
+    @staticmethod
+    def _read_exactly(stream: Any, length: int) -> bytes | None:
+        """Read exactly LENGTH bytes from STREAM; None on EOF first.
+
+        ``read(n)`` on a pipe-backed raw stream returns UP TO n bytes: it
+        reports what a single ``read(2)`` delivered, which for a message
+        larger than the pipe buffer is a partial message.  Treating that
+        short read as EOF killed the reader thread permanently -- one
+        large documentSymbol/hover/findReferences result silently
+        disabled LSP for the rest of the session.  Accumulate until the
+        framed length is satisfied; only a genuinely empty read (every
+        writer gone) is EOF.
+        """
+        if length == 0:
+            return b""
+        chunks: list[bytes] = []
+        remaining = length
+        while remaining:
+            try:
+                chunk = stream.read(remaining)
+            except (ValueError, OSError):
+                return None  # pipe closed under us (see the readline guard)
+            if not chunk:
+                return None
+            chunks.append(chunk)
+            # Clamp: a stream that over-delivers must not make `remaining`
+            # negative (a negative read() means "until EOF", i.e. a loop).
+            remaining = max(0, remaining - len(chunk))
+        return b"".join(chunks)
 
     def _handle_message(self, message: dict[str, Any]) -> None:
         if "id" in message and ("result" in message or "error" in message):

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/prompts/agent.md

@@ -56,9 +56,9 @@ The user will primarily request you perform software engineering tasks. This inc
 - Use the available search tools to understand the codebase and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.
 - Implement the solution using all tools available to you
 - Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the README or search codebase to determine the testing approach.
-- VERY IMPORTANT: When you have completed a task, you MUST run the lint and typecheck commands (e.g. npm run lint, npm run typecheck, ruff, etc.) with Bash if they were provided to you to ensure your code is correct. If you are unable to find the correct command, ask the user for the command to run and if they supply it, proactively suggest writing it to AGENTS.md so that you will know to run it next time.
-NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
-
+- VERY IMPORTANT:
+  - When you have completed a task, you MUST run the lint and typecheck commands (e.g. npm run lint, npm run typecheck, ruff, etc.) with Bash if they were provided to you to ensure your code is correct. If you are unable to find the correct command, ask the user for the command to run and if they supply it, proactively suggest writing it to AGENTS.md so that you will know to run it next time.
+  - NEVER commit changes unless the user explicitly asks you to.
 - Tool results and user messages may include <system-reminder> tags. <system-reminder> tags contain useful information and reminders. They are NOT part of the user's provided input or the tool result.
 
 # Tool usage policy

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/session/session.py

@@ -698,7 +698,11 @@ class Session:
                 self.store.save(text)
                 self._save_error = None
                 return
-            except OSError as e:
+            except (OSError, UnicodeError) as e:
+                # UnicodeError too: a save failure must never escape into
+                # the agent loop (it unwound the run and lost the turn).
+                # The writer uses surrogateescape now, so this is a
+                # defensive net rather than the primary fix.
                 self._save_error = str(e)
                 if attempt == 1:
                     time.sleep(0.2)

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/tools/edit.py

@@ -65,14 +65,16 @@ class Edit(Tool):
 
 **When NOT to use `Edit`:**
 - Creating brand new files → use `Write`
-- You haven't read the file yet → must `Read` first (tool will error)
-- The old_string is not unique and you want to replace all occurrences → use `replace_all: true`
+- You haven't read the file yet → must `Read` first
+- The old_string is not unique and you want to replace all occurrences → pass `replace_all: true`
 
 **How to use `Edit`:**
-- MUST `Read` the file first (required, tool will error otherwise)
-- Provide exact `old_string` to match (including proper inion from file content, not line number prefixes)
+- MUST `Read` the file first
+- Provide exact `old_string` to match (including proper indentation from the file content, not line number prefixes)
 - Provide `new_string` as replacement (must be different from old_string)
-- The edit will FAIL if old_string is not unique
+- The edit will FAIL if old_string is not unique — add context, or set `replace_all: true`
+- `replace_all: true` replaces EVERY occurrence (use it deliberately: it is not
+  scoped to one region)
 - Preserve exact indentation from the file content (ignore line number prefixes from `Read` output)
 - Always prefer editing existing files over creating new ones
 """
@@ -107,6 +109,13 @@ class Edit(Tool):
                 "description": "Original string to replace.  If providing a unified diff, this should be false",
             },
             "new_str": {"type": "string", "description": "Replacement string OR unified diff text"},
+            "replace_all": {
+                "type": "boolean",
+                "description": (
+                    "Replace EVERY occurrence of old_str instead of failing when it "
+                    "is not unique.  Default false (a non-unique match is an error)."
+                ),
+            },
             "diff": {
                 "type": "boolean",
                 "description": "Whether the replacement is a string or a diff.  `true` for a diff, `false` otherwise.",
@@ -127,7 +136,13 @@ class Edit(Tool):
         diffp = args.get("diff")
         # gptel: string mode when `diff` is false OR `old_str` is provided.
         if diffp is False or old is not None:
-            return self._string_replace(path, old, new_str, ctx)
+            # `is True`, not bool(): a model that sends the string "false"
+            # (or 0) must not be read as "replace every occurrence" --
+            # bool("false") is True, which would silently mass-replace.
+            # Anything unrecognised fails closed, like `diffp is False`.
+            return self._string_replace(
+                path, old, new_str, ctx, replace_all=args.get("replace_all") is True
+            )
         # Diff mode runs `patch` in Emacs `file-name-directory' of the path
         # (see _patch_cwd): a trailing-slash directory path -> that
         # directory itself, so a multi-file diff applies to files within
@@ -135,7 +150,15 @@ class Edit(Tool):
         cwd = _patch_cwd(raw, path)
         return self._apply_patch(path, cwd, new_str, ctx)
 
-    def _string_replace(self, path: str, old: str | None, new_str: str, ctx: ToolContext) -> str:
+    def _string_replace(
+        self,
+        path: str,
+        old: str | None,
+        new_str: str,
+        ctx: ToolContext,
+        *,
+        replace_all: bool = False,
+    ) -> str:
         if os.path.isdir(path):
             return (
                 f"Error: String replacement is intended for single files, not directories ({path})"
@@ -144,6 +167,10 @@ class Edit(Tool):
             return "Error: old_str is required for non-diff edits"
         if not isinstance(old, str) or not isinstance(new_str, str):
             return "Error: old_str and new_str must be strings"
+        if not old:
+            # `str.count("")` is len+1 and `replace("", x)` splices x
+            # between every character — never a meaningful edit.
+            return "Error: old_str must not be empty"
         # surrogateescape: invalid UTF-8 bytes (Latin-1, GBK, ...) survive
         # the read/rewrite round trip — errors="replace" would silently
         # persist U+FFFD for every such byte.  newline="": the file's own
@@ -162,12 +189,12 @@ class Edit(Tool):
         count = content.count(old)
         if count == 0:
             return f'Error: Could not find old_str "{old[:20]}" in file {path}'
-        if count > 1:
+        if count > 1 and not replace_all:
             return (
-                "Error: Match is not unique. Consider providing more context "
-                "for the replacement, or a unified diff"
+                f"Error: Match is not unique ({count} occurrences). Consider providing more "
+                "context for the replacement, passing replace_all: true, or using a unified diff"
             )
-        new = content.replace(old, new_str, 1)
+        new = content.replace(old, new_str) if replace_all else content.replace(old, new_str, 1)
         from .filesystem import atomic_write_text
 
         try:
@@ -177,6 +204,11 @@ class Edit(Tool):
         diff_text = unified_diff(content, new, path)
         if diff_text:
             ctx.record_diff(diff_text)
+        if replace_all and count > 1:
+            return (
+                f"Successfully replaced all {count} occurrences of {old[:20]} (truncated) "
+                f"with {new_str[:20]} (truncated)"
+            )
         return f"Successfully replaced {old[:20]} (truncated) with {new_str[:20]} (truncated)"
 
     def _apply_patch(self, path: str, cwd: str, diff: str, ctx: ToolContext) -> str:

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/tui/commands.py

@@ -628,7 +628,8 @@ class CommandMixin:
             return
         for f in files:
             try:
-                with open(f, encoding="utf-8") as fh:
+                # surrogateescape mirrors SessionPersistence.save (see there)
+                with open(f, encoding="utf-8", errors="surrogateescape") as fh:
                     text = fh.read()
             except OSError:
                 continue
@@ -672,7 +673,8 @@ class CommandMixin:
             self.console.print(f"[red]file not found: {safe_markup(path)}[/red]")
             return
         try:
-            with open(path, encoding="utf-8") as fh:
+            # surrogateescape mirrors SessionPersistence.save (see there)
+            with open(path, encoding="utf-8", errors="surrogateescape") as fh:
                 text = fh.read()
         except OSError as e:
             self.console.print(f"[red]cannot read {safe_markup(path)}: {safe_markup(e)}[/red]")

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3}/python_agent_harness/tui/render.py

@@ -20,7 +20,7 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
 
-from ..core.models import ImagePart, display_args
+from ..core.models import ImagePart, api_safe, display_args
 from ..io.diffrender import render_diff
 from ..io.text_filter import strip_final_check, strip_reasoning
 from ..prompts import _is_mode_reminder_text
@@ -66,8 +66,13 @@ def sanitize_terminal(text: str) -> str:
     what actually ran), spoof hyperlinks, or -- on terminals that honor
     OSC 52 -- write the user's clipboard.  Tabs and newlines survive;
     colors in command output are dropped along with everything else.
+
+    Lone surrogates (a non-UTF-8 file read with ``surrogateescape``)
+    become U+FFFD: Rich would hand them to the terminal verbatim and the
+    UTF-8 encoder raised ``UnicodeEncodeError`` — killing the TUI while
+    rendering a restored session.
     """
-    return _TERMINAL_CONTROL.sub("", text)
+    return _TERMINAL_CONTROL.sub("", api_safe(text))
 
 
 def safe_markup(value: object) -> str:
@@ -465,14 +470,39 @@ class RenderMixin:
 
     @staticmethod
     def _est_lines(row: Any, width: int) -> int:
-        """Rough wrapped-line estimate for a row (used for the budget)."""
+        """Estimated wrapped-line count for ROW at WIDTH (budget math).
+
+        The estimate must never be a LOWER bound: ``_apply_budget`` keeps
+        the newest rows by subtracting estimates from a fixed budget, so
+        under-estimating a tall row lets it through, the frame overflows,
+        and rich's ``Live`` crops it from the BOTTOM -- hiding exactly the
+        newest rows the budget exists to protect.
+
+        Two shapes made the old per-type estimate collapse to 1 line:
+
+        - multi-line ``Text`` (the old formula divided the total length by
+          the width, so 20 short lines counted as ~2 and were billed as 1);
+        - ``Group`` (a rendered diff is one ``Text`` per diff line, so a
+          300-line Edit diff was counted as a single line and disabled the
+          budget entirely).
+
+        Both now count real newlines, and ``Group`` recurses into its
+        renderables.
+        """
+        width = max(1, width)
+
+        def _wrapped(text: str) -> int:
+            return sum(max(1, math.ceil(cell_len(line) / width)) for line in text.split("\n"))
+
         if isinstance(row, Text):
-            return max(1, math.ceil(len(row.plain) / max(1, width)))
+            return _wrapped(row.plain)
         if isinstance(row, Markdown):
-            return max(1, math.ceil(len(row.markup) / max(1, width)))
+            return _wrapped(row.markup)
         if isinstance(row, Panel):
             inner = getattr(row.renderable, "renderables", None)
             return 3 + (len(inner) if isinstance(inner, (list, tuple)) else 1)
+        if isinstance(row, Group):
+            return sum(RenderMixin._est_lines(child, width) for child in row.renderables)
         return 1
 
     def _render_frame(self) -> Group:

{python_agent_harness-1.5.6.2 → python_agent_harness-1.5.6.3/python_agent_harness.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.6.2
+Version: 1.5.6.3
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT