python-agent-harness 1.5.4.2__tar.gz → 1.5.4.5__tar.gz

{python_agent_harness-1.5.4.2/python_agent_harness.egg-info → python_agent_harness-1.5.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.4.2
+Version: 1.5.4.5
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author: huming
 License-Expression: MIT
@@ -186,13 +186,13 @@ All LLM settings live in a single JSON configuration file. Environment variables
 
 ### Configuration options
 
-- **`llm`** — main LLM configuration. Optional keys include `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
+- **`llm`** — main LLM configuration. Optional keys include `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
 - **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
 - **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g., `deepseek-v4`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
-- **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`, `_BACKEND`).
+- **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **Custom config** — use `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
 - **LLM logging** — request and response bodies are logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change the directory. The log path is printed at startup.
 
@@ -248,7 +248,7 @@ python_agent_harness/
 
 ## Development
 
-Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13.
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux and macOS.
 
 ```sh
 make test                           # unit tests

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/README.md

@@ -163,13 +163,13 @@ All LLM settings live in a single JSON configuration file. Environment variables
 
 ### Configuration options
 
-- **`llm`** — main LLM configuration. Optional keys include `backend`, `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
+- **`llm`** — main LLM configuration. Optional keys include `temperature`, `max_tokens`, `timeout`, `reasoning_effort`, and `stream`. Values such as `reasoning_effort` are passed to the API as-is when set. `run --no-stream` overrides `stream`.
 - **`models`** — named LLM profiles for runtime switching with `/model`. A profile is a partial settings dictionary; unset keys inherit from the main `llm`. `default` restores the main LLM configuration.
 - **`context_windows`** — optional per-model context-window overrides (tokens). Keys are model names or substrings (e.g., `deepseek-v4`); matched in file order, first match wins. Overrides the built-in `CONTEXT_WINDOWS` table in `config.py`.
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
-- **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`, `_BACKEND`).
+- **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **Custom config** — use `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
 - **LLM logging** — request and response bodies are logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change the directory. The log path is printed at startup.
 
@@ -225,7 +225,7 @@ python_agent_harness/
 
 ## Development
 
-Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13.
+Requires Python ≥ 3.11. CI runs against Python 3.11, 3.12, and 3.13 on Linux and macOS.
 
 ```sh
 make test                           # unit tests

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.4.2"
+version = "1.5.4.5"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 readme = "README.md"
 requires-python = ">=3.11"

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/__init__.py

@@ -5,7 +5,7 @@ from .mcp.manager import MCPManager
 from .models import AgentMode, Message, ToolCall, ToolSpec
 from .session import Session
 
-__version__ = "1.5.4.2"
+__version__ = "1.5.4.5"
 
 __all__ = [
     "Session",

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/agent.py

@@ -452,7 +452,7 @@ class AgentLoop:
             )
             # sub-agent runs use their own LLM when one is configured
             # (a per-invocation clone of session.subagent_client,
-            # mirroring gptel-agent-harness-subagent-model/-backend);
+            # mirroring gptel-agent-harness-subagent-model);
             # everything unset inherits the main agent's settings, so
             # the sub-agent path is identical when no separate LLM is
             # configured

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/cli.py

@@ -54,8 +54,8 @@ def make_session(
         config_path=config_path,
     )
     # A separate client for sub-agent requests only when a different
-    # LLM is configured (mirrors gptel-agent-harness-subagent-model /
-    # -backend); otherwise the sub-agent shares the main client.
+    # LLM is configured (mirrors gptel-agent-harness-subagent-model);
+    # otherwise the sub-agent shares the main client.
     subagent_client = None
     if any(
         subagent_settings[k] != settings[k] for k in ("base_url", "api_key", "model", "timeout")
@@ -101,7 +101,6 @@ def make_session(
         project_dir=abs_project,
         client=client,
         model=model,
-        backend=settings["backend"],
         system_prompt=system_prompt,
         subagent_system_prompt=subagent_system_prompt,
         temperature=settings["temperature"],
@@ -176,7 +175,7 @@ def cmd_config(args: argparse.Namespace) -> int:
     print(f"config file: {path}")
     if not path.exists():
         print("(file does not exist yet — run `python-agent-harness config --init` to create it)")
-    for key in ("base_url", "model", "backend"):
+    for key in ("base_url", "model"):
         print(f"{key}: {settings[key]}")
     print(f"api_key: {config.mask_secret(settings['api_key'])}")
     print(f"temperature: {settings['temperature']}")

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/config.py

@@ -168,7 +168,6 @@ DEFAULT_LLM: dict = {
     "base_url": "https://api.openai.com/v1",
     "api_key": None,
     "model": "gpt-5-mini",
-    "backend": "OpenAI-compatible",
     "temperature": TEMPERATURE,
     "max_tokens": MAX_TOKENS,
     "timeout": 600.0,
@@ -182,8 +181,7 @@ DEFAULT_PATHS: dict = {
 }
 
 # Sub-agent LLM overrides: every key defaults to None, meaning "inherit
-# the main LLM setting" (mirrors gptel-agent-harness-subagent-model /
-# -backend).  Only the keys the user actually sets differ from the main
+# the main LLM setting" (mirrors gptel-agent-harness-subagent-model).
 # agent's LLM.  ``profile`` references a named profile from the
 # ``models`` section: its settings are applied on top of any explicit
 # subagent_llm keys (profile wins), and unset keys still inherit the
@@ -193,7 +191,6 @@ DEFAULT_SUBAGENT_LLM: dict = {
     "base_url": None,
     "api_key": None,
     "model": None,
-    "backend": None,
     "temperature": None,
     "max_tokens": None,
     "timeout": None,
@@ -264,14 +261,12 @@ _ENV_OVERRIDES = {
     "base_url": "OPENAI_BASE_URL",
     "api_key": "OPENAI_API_KEY",
     "model": "OPENAI_MODEL",
-    "backend": "OPENAI_BACKEND",
 }
 
 _SUBAGENT_ENV_OVERRIDES = {
     "base_url": "OPENAI_SUBAGENT_BASE_URL",
     "api_key": "OPENAI_SUBAGENT_API_KEY",
     "model": "OPENAI_SUBAGENT_MODEL",
-    "backend": "OPENAI_SUBAGENT_BACKEND",
 }
 
 
@@ -320,7 +315,6 @@ def load_llm_config(path: str | os.PathLike | None = None) -> dict:
         "base_url",
         "api_key",
         "model",
-        "backend",
         "temperature",
         "max_tokens",
         "timeout",
@@ -342,7 +336,7 @@ def load_subagent_llm_config(
 ) -> dict:
     """Resolve sub-agent LLM settings; unset keys inherit ``main``.
 
-    Mirrors gptel-agent-harness-subagent-model/-backend: sub-agents
+    Mirrors gptel-agent-harness-subagent-model: sub-agents
     (the Agent tool) use their own LLM when configured, otherwise the
     main agent's.  Precedence: ``main`` settings < config file
     ``subagent_llm`` object < referenced ``models`` profile (when
@@ -379,7 +373,6 @@ def load_subagent_llm_config(
             "base_url",
             "api_key",
             "model",
-            "backend",
             "temperature",
             "max_tokens",
             "timeout",
@@ -507,6 +500,10 @@ def load_context_windows_config(
             raise ValueError(
                 f"config file {_config_path(path)}: context_windows.{pattern} must be an integer"
             )
+        if size <= 0:
+            raise ValueError(
+                f"config file {_config_path(path)}: context_windows.{pattern} must be positive"
+            )
         entries.append((pattern, size))
     return entries
 

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/mcp/manager.py

@@ -23,6 +23,7 @@ SDK/connection errors that the tool adapter turns into error strings.
 from __future__ import annotations
 
 import asyncio
+import concurrent.futures
 import contextlib
 import threading
 import time
@@ -102,7 +103,10 @@ class _LoopThread:
         while True:
             try:
                 exc = future.exception(timeout=0.1)
-            except TimeoutError:
+            # concurrent.futures.TimeoutError is the builtin TimeoutError on
+            # 3.11+ but a distinct class on 3.10 — catch the futures one so
+            # the poll-timeout branch works on every supported Python.
+            except concurrent.futures.TimeoutError:
                 # future still running: enforce deadline / cancellation
                 if deadline is not None and time.monotonic() >= deadline:
                     future.cancel()

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/persistence.py

@@ -107,7 +107,6 @@ class SessionPersistence:
         self,
         project_dir: str,
         model: str,
-        backend: str,
         system_prompt: str | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
@@ -116,7 +115,6 @@ class SessionPersistence:
     ) -> None:
         self.project_dir = project_dir
         self.model = model
-        self.backend = backend
         self.system_prompt = system_prompt
         self.temperature = temperature
         self.max_tokens = max_tokens
@@ -173,7 +171,6 @@ class SessionPersistence:
         pairs = [
             ("python-agent-harness--project-dir", self.project_dir),
             ("gptel-model", self.model),
-            ("gptel--backend-name", self.backend),
             ("gptel-system-prompt", self.system_prompt),
             ("gptel-temperature", self.temperature),
             ("gptel-max-tokens", self.max_tokens),

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/planmode.py

@@ -64,8 +64,11 @@ class PlanMode:
         os.makedirs(os.path.dirname(path), exist_ok=True)
         if not os.path.exists(path):
             Path(path).write_text("", encoding="utf-8")
-        self.plan_file = path
-        return path
+        # Store the canonical path so the plan-mode write guard (which
+        # compares against realpath'd tool targets) matches — on macOS
+        # TMPDIR (/var) is a symlink to /private/var.
+        self.plan_file = os.path.realpath(path)
+        return self.plan_file
 
     def cleanup_plan_file(self) -> None:
         if not self.plan_file:

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/session.py

@@ -71,7 +71,6 @@ class Session:
         project_dir: str,
         client: Client,
         model: str,
-        backend: str = "OpenAI-compatible",
         system_prompt: str | None = None,
         subagent_system_prompt: str | None = None,
         temperature: float = config.TEMPERATURE,
@@ -96,7 +95,6 @@ class Session:
         self.project_dir = project_dir
         self.client = client
         self.model = model
-        self.backend = backend
         self.system_prompt = system_prompt
         self.subagent_system_prompt = subagent_system_prompt
         self.temperature = temperature
@@ -113,7 +111,7 @@ class Session:
         # Sub-agent LLM: a dedicated client (base_url/api_key/model/
         # timeout) and per-request options when a different LLM is
         # configured for sub-agents (mirrors gptel-agent-harness-
-        # subagent-model/-backend); every unset option inherits the
+        # subagent-model); every unset option inherits the
         # main agent's value.  The sub-agent loop never uses this
         # client directly — each Agent tool invocation clones it
         # (see run_subagent) so concurrent sub-agents never share a
@@ -161,7 +159,6 @@ class Session:
         self.store = SessionPersistence(
             project_dir=project_dir,
             model=model,
-            backend=backend,
             system_prompt=system_prompt,
             temperature=temperature,
             max_tokens=max_tokens,
@@ -659,7 +656,6 @@ class Session:
             "base_url": self.client.base_url,
             "api_key": self.client.api_key,
             "model": self.model,
-            "backend": self.backend,
             "temperature": self.temperature,
             "max_tokens": self.max_tokens,
             "timeout": self.client.timeout,
@@ -673,7 +669,6 @@ class Session:
                 "base_url",
                 "api_key",
                 "model",
-                "backend",
                 "temperature",
                 "max_tokens",
                 "timeout",
@@ -690,8 +685,6 @@ class Session:
         # the calibration factor is tokenizer-specific: a factor tuned
         # to the previous model must not skew estimates for the new one
         self.calibrator.reset()
-        self.backend = merged["backend"]
-        self.store.backend = merged["backend"]
         self.temperature = merged["temperature"]
         self.max_tokens = merged["max_tokens"]
         if hasattr(self.client, "set_timeout"):

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/tools/__init__.py

@@ -2,10 +2,16 @@
 
 from __future__ import annotations
 
+import sys
+
 from .agent_tool import AgentTool
 from .base import PendingToolResult, Registry, Tool, ToolContext
 from .bash import Bash
-from .filesystem import Edit, GlobTool, Grep, Insert, Mkdir, Read, Write
+from .edit import Edit
+from .edit_mac import EditMac
+from .filesystem import GlobTool, Grep, Insert, Mkdir, Read, Write
+from .glob_mac import GlobMac
+from .grep_mac import GrepMac
 from .mcp import MCPTool, mcp_tools_from_manager, normalize_mcp_result
 from .planexit import PlanExit
 from .question import Question
@@ -20,8 +26,11 @@ __all__ = [
     "AgentTool",
     "Bash",
     "Edit",
+    "EditMac",
+    "GlobMac",
     "GlobTool",
     "Grep",
+    "GrepMac",
     "Insert",
     "MCPTool",
     "Mkdir",
@@ -38,14 +47,21 @@ __all__ = [
 
 def default_registry() -> Registry:
     reg = Registry()
+    # macOS lacks GNU `patch`, `tree`, and PCRE-enabled git — use
+    # pure-Python / POSIX-compatible Mac variants that register under
+    # the same tool names so callers are platform-independent.
+    _mac = sys.platform == "darwin"
+    edit_tool = EditMac() if _mac else Edit()
+    glob_tool = GlobMac() if _mac else GlobTool()
+    grep_tool = GrepMac() if _mac else Grep()
     for tool in (
         AgentTool(),
         TodoWrite(),
-        GlobTool(),
-        Grep(),
+        glob_tool,
+        grep_tool,
         Read(),
         Insert(),
-        Edit(),
+        edit_tool,
         Write(),
         Mkdir(),
         Bash(),

{python_agent_harness-1.5.4.2 → python_agent_harness-1.5.4.5}/python_agent_harness/tools/agent_tool.py

@@ -6,7 +6,7 @@ sub-agent loop, delivering the result string when it finishes — a
 long-running sub-agent never blocks the parent's sequential tool loop.
 
 Sub-agents run the same agent loop with a fresh loop instance; their
-backend/model can be overridden (see config).  Results flow back to the
+model can be overridden (see config).  Results flow back to the
 parent as a single tool result string.  Errors are contained: an
 unexpected sub-agent response becomes an error string fed to the parent,
 never a crash.

python_agent_harness-1.5.4.5/python_agent_harness/tools/diffapply.py

@@ -0,0 +1,246 @@
+"""Pure-Python unified diff applier (macOS Edit backend).
+
+macOS ships Apple's old BSD ``/usr/bin/patch`` (patch 2.0-12u11-Apple),
+which rejects well-formed hunks that GNU patch accepts: asymmetric
+context (leading but no trailing context, or vice versa), hunks whose
+last body line is a ``---``-rendered content line, etc.  Rather than
+rewriting every diff into a shape that specific patch binary likes, the
+macOS Edit tool applies diffs here, in Python:
+
+- the diff is parsed STRUCTURALLY, so hunk-header counts are advisory
+  (they are recounted from the body, like ``_fix_patch_headers``) and
+  ``---``/``+++`` content lines are only file headers when followed by
+  their ``+++``/``---`` partner;
+- hunks are matched against the file by content with fuzz (context
+  lines may mismatch up to ``FUZZ`` times, removed lines must match
+  exactly), preferring the position the header claims;
+- hunks are applied bottom-up so earlier positions stay valid;
+- files are written only when every hunk of the section matched.
+
+The applier is platform-independent, so its behavior is covered by
+tests on every OS.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+_HUNK_HEADER_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+_FILE_OLD_RE = re.compile(r"^---[ \t]")
+_FILE_NEW_RE = re.compile(r"^\+\+\+[ \t]")
+_HUNK_BOUNDARY_RE = re.compile(r"^@@ ")
+
+# Maximum number of context lines that may mismatch when anchoring a
+# hunk (removed lines must always match exactly).
+FUZZ = 3
+
+
+class _Hunk:
+    __slots__ = ("old_start", "body")
+
+    def __init__(self, old_start: int, body: list[tuple[str, str, bool]]) -> None:
+        # body entries: (kind, content, no_newline); kind in ' ', '-', '+'.
+        self.old_start = old_start
+        self.body = body
+
+    def old_seq(self) -> list[tuple[str, str]]:
+        """(kind, content-without-newline) for the lines that must exist
+        in the old file (' ' context and '-' removed lines)."""
+        return [
+            (kind, content.rstrip("\n")) for kind, content, _ in self.body if kind in (" ", "-")
+        ]
+
+
+class _Section:
+    __slots__ = ("new_path", "hunks")
+
+    def __init__(self, new_path: str, hunks: list[_Hunk]) -> None:
+        self.new_path = new_path
+        self.hunks = hunks
+
+
+def _section_header_at(lines: list[str], idx: int) -> bool:
+    """Whether lines[idx] begins a file section: a ``--- path`` line
+    immediately followed by a ``+++ path`` line.  Removed/added content
+    lines rendered ``---``/``+++`` inside a hunk body are only mistaken
+    for headers when the pair shape matches, so the trailing ``+++``
+    partner is required (mirrors ``_starts_file_section``)."""
+    if idx + 1 >= len(lines):
+        return False
+    return bool(_FILE_OLD_RE.match(lines[idx]) and _FILE_NEW_RE.match(lines[idx + 1]))
+
+
+def _parse(diff_text: str) -> list[_Section]:
+    """Parse a unified diff into file sections (paths + hunks)."""
+    lines = diff_text.splitlines(keepends=True)
+    sections: list[_Section] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        if not _section_header_at(lines, i):
+            i += 1
+            continue
+        new_path = lines[i + 1][len("+++") :].strip()
+        i += 2
+        hunks: list[_Hunk] = []
+        while i < n:
+            m = _HUNK_HEADER_RE.match(lines[i])
+            if m:
+                old_start = int(m.group(1))
+                body: list[tuple[str, str, bool]] = []
+                i += 1
+                while (
+                    i < n
+                    and not _HUNK_BOUNDARY_RE.match(lines[i])
+                    and not _section_header_at(lines, i)
+                ):
+                    line = lines[i]
+                    if line.startswith("\\"):  # ""
+                        if body and body[-1][0] in (" ", "-", "+"):
+                            kind, content, _ = body[-1]
+                            body[-1] = (kind, content, True)
+                    elif line[:1] in (" ", "-", "+"):
+                        body.append((line[0], line[1:], False))
+                    i += 1
+                hunks.append(_Hunk(old_start, body))
+                continue
+            if _section_header_at(lines, i):
+                break
+            i += 1  # stray line (e.g. "diff --git", "index ...") — skip
+        sections.append(_Section(new_path, hunks))
+    return sections
+
+
+def _candidate_positions(start: int, limit: int) -> list[int]:
+    """Match offsets around *start* (0-based), closest first, within
+    ``FUZZ`` lines and bounded by [0, *limit*]."""
+    out: list[int] = []
+    seen: set[int] = set()
+    for d in range(FUZZ + 1):
+        for p in (start - d, start + d):
+            if 0 <= p <= limit and p not in seen:
+                seen.add(p)
+                out.append(p)
+    return out
+
+
+def _match_hunk(hunk: _Hunk, file_lines: list[str]) -> int | None:
+    """Find the 0-based position where the hunk's old lines match.
+
+    Removed lines must match exactly; up to ``FUZZ`` context lines may
+    mismatch (patch-style fuzz).  Pure-insertion hunks (no old lines)
+    anchor at ``old_start - 1``.
+    """
+    old_seq = hunk.old_seq()
+    if not old_seq:
+        p = hunk.old_start - 1
+        return max(0, min(p, len(file_lines)))
+    start = hunk.old_start - 1
+    limit = len(file_lines) - len(old_seq)
+    for p in _candidate_positions(start, limit):
+        mismatches = 0
+        ok = True
+        for i, (kind, content) in enumerate(old_seq):
+            file_content = file_lines[p + i].rstrip("\n")
+            if kind == "-":
+                if file_content != content:
+                    ok = False
+                    break
+            elif file_content != content:
+                mismatches += 1
+                if mismatches > FUZZ:
+                    ok = False
+                    break
+        if ok:
+            return p
+    return None
+
+
+def _apply_hunk(hunk: _Hunk, pos: int, file_lines: list[str]) -> None:
+    """Replace the matched region with the hunk's new lines in place."""
+    old_count = sum(1 for kind, _, _ in hunk.body if kind in (" ", "-"))
+    new_block: list[str] = []
+    p = pos
+    for kind, content, no_newline in hunk.body:
+        if kind == " ":
+            new_block.append(file_lines[p])
+            p += 1
+        elif kind == "-":
+            p += 1
+        else:  # "+"
+            if no_newline:
+                new_block.append(content.rstrip("\n"))
+            elif content.endswith("\n"):
+                new_block.append(content)
+            else:
+                new_block.append(content + "\n")
+    file_lines[pos : pos + old_count] = new_block
+
+
+def _resolve_target(new_path: str, cwd: str, fallback_path: str | None) -> str:
+    """Resolve a diff's ``+++ path`` against *cwd*, with the single-file
+    *fallback_path* as backup when the name does not match an existing
+    file (e.g. the model wrote a bare basename for a deep path)."""
+    name = new_path
+    for prefix in ("a/", "b/"):
+        if name.startswith(prefix):
+            name = name[len(prefix) :]
+            break
+    if os.path.isabs(name):
+        return name
+    target = os.path.join(cwd, name)
+    if not os.path.isfile(target) and fallback_path and os.path.isfile(fallback_path):
+        return fallback_path
+    return target
+
+
+def _apply_section(section: _Section, cwd: str, fallback_path: str | None) -> tuple[bool, str]:
+    target = _resolve_target(section.new_path, cwd, fallback_path)
+    if not os.path.isfile(target):
+        return False, f"target file does not exist: {target}"
+    try:
+        with open(target, encoding="utf-8", errors="replace") as f:
+            file_lines = f.readlines()
+    except OSError as e:
+        return False, f"cannot read {target}: {e}"
+    # Match every hunk against the ORIGINAL content first; only write
+    # when all matched (a failed hunk leaves the file untouched).
+    plan: list[tuple[_Hunk, int]] = []
+    for hunk in section.hunks:
+        pos = _match_hunk(hunk, file_lines)
+        if pos is None:
+            return (
+                False,
+                f"hunk at line {hunk.old_start} failed to match the file content",
+            )
+        plan.append((hunk, pos))
+    new_lines = list(file_lines)
+    for hunk, pos in reversed(plan):  # bottom-up: earlier positions stay valid
+        _apply_hunk(hunk, pos, new_lines)
+    try:
+        with open(target, "w", encoding="utf-8") as f:
+            f.writelines(new_lines)
+    except OSError as e:
+        return False, f"cannot write {target}: {e}"
+    return True, f"patched {target}"
+
+
+def apply_unified_diff(
+    diff_text: str, cwd: str, fallback_path: str | None = None
+) -> tuple[bool, str]:
+    """Apply a unified diff to files under *cwd*.
+
+    Returns ``(ok, message)``; on failure no file is written.  Multi-file
+    diffs are applied section by section.  *fallback_path* is used when a
+    section's target cannot be resolved to an existing file (single-file
+    mode).
+    """
+    sections = _parse(diff_text)
+    if not sections:
+        return False, "no file sections found in diff"
+    for section in sections:
+        ok, msg = _apply_section(section, cwd, fallback_path)
+        if not ok:
+            return False, msg
+    return True, f"applied {len(sections)} file section(s)"