minimalcode 1.5.2__py3-none-any.whl

minimalcode/agent.py

@@ -0,0 +1,1084 @@
+from __future__ import annotations
+
+import json
+import sys
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, TextIO
+
+from .config import Settings
+from .highlight import (
+    MarkdownHighlighter,
+    TerminalSanitizer,
+    ThinkingRenderer,
+    sanitize_terminal_text,
+    style_activity_tag,
+)
+from .prompt import build_system_prompt, merge_agents_summary
+from .provider import OpenAICompatibleProvider, ProviderError, ToolCall
+from .session import Session
+from .shell import ShellSpec
+from .tools import ToolError, ToolRuntime, available_tool_schemas, tool_result_text
+from .tools.schemas import READ_ONLY_TOOLS
+
+
+def _is_wide_character(char: str) -> bool:
+    """Return True for scripts whose characters cost roughly one token each."""
+    code = ord(char)
+    return (
+        0x1100 <= code <= 0x115F  # Hangul Jamo
+        or 0x2E80 <= code <= 0x9FFF  # CJK radicals through CJK unified ideographs
+        or 0xA000 <= code <= 0xA4CF  # Yi
+        or 0xAC00 <= code <= 0xD7A3  # Hangul syllables
+        or 0xF900 <= code <= 0xFAFF  # CJK compatibility ideographs
+        or 0xFE30 <= code <= 0xFE6F  # CJK compatibility forms
+        or 0xFF00 <= code <= 0xFF60  # Fullwidth forms
+        or 0xFFE0 <= code <= 0xFFE6
+        or 0x1F300 <= code <= 0x1FAFF  # Emoji
+        or 0x20000 <= code <= 0x3FFFD
+    )
+
+
+def estimate_text_tokens(text: str) -> int:
+    """Estimate tokens for one string, weighted by character width.
+
+    ``len(text) // 4`` is a decent ASCII rule and a fourfold undercount for CJK:
+    a Chinese character carries roughly one token, not a quarter of one. Because
+    this estimate is the compaction trigger and the fallback when a provider
+    omits usage, undercounting silently lets the history outgrow the window.
+    """
+    if not text:
+        return 0
+    wide = 0
+    for char in text:
+        if _is_wide_character(char):
+            wide += 1
+    narrow = len(text) - wide
+    return wide + (narrow + 3) // 4
+
+
+def estimate_tokens(messages: list[dict[str, Any]]) -> int:
+    return max(1, estimate_text_tokens(json.dumps(messages, ensure_ascii=False)))
+
+
+def _tool_output_preview(result: dict[str, Any]) -> str:
+    if result.get("status") == "success":
+        if "stderr" in result and result.get("stderr"):
+            return f"exit {result.get('exit_code', 0)}; stderr present"
+        return "ok"
+    return str(result.get("message") or result.get("status") or "error")
+
+
+_ACTIVITY_OUTPUT_MAX_LINES = 12
+_ACTIVITY_OUTPUT_MAX_CHARS = 4000
+# One model turn that asks for hundreds of calls is either a broken provider
+# or an attempted resource exhaustion; it is never a normal coding step.
+_MAX_TOOL_CALLS_PER_TURN = 32
+_INCOMPLETE_FINISH_REASONS = {
+    "length",
+    "max_tokens",
+    "content_filter",
+    "max_output_tokens",
+    "failed",
+    "cancelled",
+    "canceled",
+    "incomplete",
+    "incomplete_stream",
+    "in_progress",
+    "queued",
+    "server_error",
+}
+# A compaction replaces the dropped prefix with this many synthetic messages, so
+# a cut has to remove more than that to make the history smaller.
+_COMPACT_HEAD_MESSAGES = 2
+_COMPACTED_SUMMARY_PREFIX = (
+    "[Earlier conversation compacted. Continue from this state.]"
+)
+_COMPACTED_SUMMARY_ACK = "Context received. I will continue from the recorded state."
+
+
+def _clip_activity_output(text: str) -> str:
+    """Keep tool activity readable without echoing entire command output."""
+    lines = text.splitlines()
+    if len(lines) > _ACTIVITY_OUTPUT_MAX_LINES:
+        head = _ACTIVITY_OUTPUT_MAX_LINES // 2
+        tail = _ACTIVITY_OUTPUT_MAX_LINES - head
+        omitted = len(lines) - _ACTIVITY_OUTPUT_MAX_LINES
+        lines = [*lines[:head], f"  … {omitted} lines omitted", *lines[-tail:]]
+    clipped = "\n".join(lines)
+    if len(clipped) > _ACTIVITY_OUTPUT_MAX_CHARS:
+        clipped = clipped[:_ACTIVITY_OUTPUT_MAX_CHARS] + "…"
+    return clipped
+
+
+def _shell_output_activity(result: dict[str, Any]) -> str:
+    lines: list[str] = []
+    exit_code = result.get("exit_code")
+    if isinstance(exit_code, int):
+        lines.append(f"  exit {exit_code}")
+    else:
+        lines.append(f"  {result.get('status', 'error')}")
+
+    stdout = _clip_activity_output(str(result.get("stdout") or "").rstrip())
+    stderr = _clip_activity_output(str(result.get("stderr") or "").rstrip())
+    message = str(result.get("message") or "").strip()
+    if stdout:
+        lines.extend(("  stdout:", stdout))
+    if stderr:
+        lines.extend(("  stderr:", stderr))
+    if message:
+        lines.append(f"  {message}")
+    return "\n".join(lines)
+
+
+def _repair_tool_history(
+    messages: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], bool]:
+    repaired: list[dict[str, Any]] = []
+    changed = False
+    call_order: list[str] | None = None
+    call_names: dict[str, str] = {}
+    block_results: list[dict[str, Any]] = []
+
+    def synthetic_result(call_id: str, name: str) -> dict[str, Any]:
+        return {
+            "role": "tool",
+            "tool_call_id": call_id,
+            "name": name,
+            "content": json.dumps(
+                {
+                    "status": "error",
+                    "message": "interrupted before tool result was recorded",
+                },
+                separators=(",", ":"),
+            ),
+        }
+
+    def flush_block() -> None:
+        nonlocal changed, call_order, call_names, block_results
+        if call_order is None:
+            block_results = []
+            return
+        by_id: dict[str, dict[str, Any]] = {}
+        for result in block_results:
+            call_id = str(result.get("tool_call_id") or "")
+            if call_id in call_names and call_id not in by_id:
+                by_id[call_id] = result
+            else:
+                # A result for an unknown or already answered call id makes
+                # most providers reject the whole request; drop it.
+                changed = True
+        for call_id in call_order:
+            result = by_id.get(call_id)
+            if result is not None:
+                repaired.append(result)
+            else:
+                repaired.append(synthetic_result(call_id, call_names[call_id]))
+                changed = True
+        call_order = None
+        call_names = {}
+        block_results = []
+
+    for message in messages:
+        role = message.get("role")
+        if call_order is not None and role != "tool":
+            flush_block()
+        if role == "tool" and call_order is not None:
+            block_results.append(dict(message))
+            continue
+        if role == "tool":
+            # Orphan result: no assistant tool_calls precedes it, so replaying
+            # it is a protocol error for every OpenAI-compatible server.
+            changed = True
+            continue
+        if (
+            role == "assistant"
+            and message.get("content") is None
+            and (
+                not isinstance(message.get("tool_calls"), list)
+                or not message["tool_calls"]
+            )
+        ):
+            # Older sessions stored an empty reply as null content. Providers
+            # reject that shape on the next request, so repair it in place.
+            repaired.append({**message, "content": ""})
+            changed = True
+        else:
+            repaired.append(dict(message))
+        if role == "assistant" and isinstance(message.get("tool_calls"), list):
+            call_order = []
+            call_names = {}
+            for call in message["tool_calls"]:
+                if not isinstance(call, dict):
+                    continue
+                call_id = str(call.get("id") or "")
+                function = call.get("function")
+                # A hand-edited session file can carry a non-object `function`;
+                # reading it with `.get` raised AttributeError before any turn ran.
+                name = (
+                    str(function.get("name") or "")
+                    if isinstance(function, dict)
+                    else ""
+                )
+                if call_id:
+                    if call_id not in call_names:
+                        call_order.append(call_id)
+                    call_names[call_id] = name
+    flush_block()
+    return repaired, changed
+
+
+@dataclass(slots=True)
+class AgentResult:
+    text: str
+    completed: bool
+    usage: dict[str, int] = field(default_factory=dict)
+    run_usage: dict[str, int] = field(default_factory=dict)
+    turns: int = 0
+    # True when at least one turn in this run had no provider-reported usage and
+    # the numbers came from ``estimate_tokens`` instead.
+    usage_estimated: bool = False
+
+
+SUMMARY_PROMPT = """\
+Summarize this coding-agent session as durable repository notes for the next \
+session. Record what was asked, the files created or modified, the decisions \
+taken and why, the commands and tests that were actually run with their \
+outcomes, and any remaining work, blockers, or known limitations. Write short \
+Markdown sections with terse bullets. Omit greetings, narration, and reasoning \
+that did not change the result. Never claim a check ran unless the transcript \
+shows it ran, and do not wrap the answer in a code fence.
+"""
+
+
+def _is_compacted_head(messages: list[dict[str, Any]]) -> bool:
+    """Return True when the history already starts with a compaction summary.
+
+    Replacing that pair again would summarize the summary and leave an equally
+    long history, which is what used to happen on every turn of a long tool
+    loop.
+    """
+    if len(messages) < _COMPACT_HEAD_MESSAGES:
+        return False
+    first, second = messages[0], messages[1]
+    content = first.get("content")
+    # The summary prefix identifies the pair; the acknowledgement wording is not
+    # matched exactly so a history written by an older version still counts.
+    return (
+        first.get("role") == "user"
+        and isinstance(content, str)
+        and content.startswith(_COMPACTED_SUMMARY_PREFIX)
+        and second.get("role") == "assistant"
+    )
+
+
+def _compaction_boundaries(messages: list[dict[str, Any]], target: int) -> list[int]:
+    """Return replay-safe cut points in preference order.
+
+    A cut may only land before a message that does not belong to a tool-call
+    block, otherwise the kept tail starts with an orphan tool result. The
+    largest usable tail wins, so the search starts at ``target`` and walks
+    backwards to the nearest user message.
+
+    A long tool loop inside one user turn can leave no user message between the
+    previous summary and ``target``. Cutting there would re-summarize the
+    summary without shrinking anything, so the next user message after
+    ``target`` is offered as well: the summary still covers everything that is
+    dropped, including the tool results in between.
+
+    Some session files start mid-turn and have no user message at all; the last
+    candidate is any message outside a tool-call block so compaction can still
+    make progress.
+    """
+    boundaries: list[int] = []
+    for index in range(target, 0, -1):
+        if messages[index].get("role") == "user":
+            boundaries.append(index)
+            break
+    for index in range(target + 1, len(messages)):
+        if messages[index].get("role") == "user":
+            boundaries.append(index)
+            break
+    for index in range(target, 0, -1):
+        if messages[index].get("role") == "tool":
+            continue
+        previous = messages[index - 1]
+        if previous.get("role") == "assistant" and previous.get("tool_calls"):
+            continue
+        boundaries.append(index)
+        break
+    return boundaries
+
+
+class Agent:
+    def __init__(
+        self,
+        *,
+        settings: Settings,
+        provider: OpenAICompatibleProvider,
+        session: Session,
+        tool_runtime: ToolRuntime,
+        shell: ShellSpec,
+        max_turns: int | None = None,
+        output: TextIO | None = None,
+        error_output: TextIO | None = None,
+        quiet: bool = False,
+        stream_output: bool = True,
+        markdown_highlight: bool | None = None,
+    ):
+        self.settings = settings
+        self.provider = provider
+        self.session = session
+        self.tools = tool_runtime
+        self.tool_schemas = available_tool_schemas(
+            self.tools.web_client,
+            self.tools.vision_client,
+            self.tools.subagent_enabled,
+            allowed=self._allowed_tools(),
+        )
+        self.shell = shell
+        configured_turns = (
+            settings.get("max_turns", 1000) if max_turns is None else max_turns
+        )
+        self.max_turns = max(1, int(configured_turns))
+        self.output = output or sys.stdout
+        self.error_output = error_output or sys.stderr
+        self.quiet = quiet
+        self.stream_output = stream_output
+        # Retry notices travel through the activity stream, so --quiet and
+        # --json stay silent while an interactive turn shows the retries.
+        if hasattr(self.provider, "notify"):
+            self.provider.notify = self._activity
+        highlight_enabled = (
+            bool(settings.get("output.markdown_highlight", True))
+            if markdown_highlight is None
+            else markdown_highlight
+        )
+        self._highlighter = (
+            MarkdownHighlighter(
+                self.output,
+                theme=str(settings.get("output.theme", "dark")),
+            )
+            if stream_output and highlight_enabled
+            else None
+        )
+        # Reasoning is shown in the six-level heading style, so it follows the
+        # same switch as highlighting: no ANSI means no reasoning block, and
+        # redirected stdout keeps carrying the answer alone.
+        self._thinking_renderer = (
+            ThinkingRenderer(
+                self.output,
+                theme=str(settings.get("output.theme", "dark")),
+            )
+            if stream_output and highlight_enabled
+            else None
+        )
+        self.last_prompt_tokens = 0
+        # Number of session messages covered by last_prompt_tokens. Messages
+        # appended after the request (the new user turn and tool results) are
+        # not in the provider-reported prompt size yet.
+        self._prompt_session_count = 0
+        # Number of messages at the last failed compaction. Retrying the same
+        # summary request before every turn can dominate the bill when the
+        # provider is down; wait for the history to grow instead.
+        self._compact_blocked_at: int | None = None
+        self.estimated_turns = 0
+        self._system_prompt: str | None = None
+        self._plain_sanitizer = TerminalSanitizer()
+        self.total_usage = {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+            "cached_tokens": 0,
+            "reasoning_tokens": 0,
+        }
+
+        self._repair_history()
+
+    def _repair_history(self) -> None:
+        """Close tool_calls left without results by an interrupted turn.
+
+        Ctrl-C or a provider failure can stop the loop between an assistant
+        tool call and its result. Replaying that history makes most providers
+        reject the next request, so the gap is filled before every run.
+        """
+        repaired, changed = _repair_tool_history(self.session.messages)
+        if changed:
+            self.session.replace_messages(
+                repaired,
+                summary="Recovered an interrupted tool turn.",
+                dropped_messages=0,
+            )
+
+    def refresh_instructions(self) -> None:
+        """Drop the cached system prompt so the next build re-reads instructions.
+
+        ``AGENTS.md`` / ``CLAUDE.md`` are read at the start of every run rather
+        than once per process: ``/summary`` and external editors rewrite them
+        between turns, and a stale copy would silently keep old rules.
+        """
+        self._system_prompt = None
+
+    def _system_messages(self) -> list[dict[str, Any]]:
+        if self._system_prompt is None:
+            # Building the prompt reads SYSTEM.md plus every AGENTS.md/CLAUDE.md
+            # on the path; missing files are skipped. The tool loop calls this
+            # several times per run, so the result is cached until the next run.
+            self._system_prompt = build_system_prompt(
+                self.settings,
+                self.session.cwd,
+                self.shell,
+            )
+        return [{"role": "system", "content": self._system_prompt}]
+
+    def _messages(self) -> list[dict[str, Any]]:
+        return [*self._system_messages(), *self.session.messages]
+
+    def _accumulate_usage(
+        self,
+        usage: dict[str, int],
+        messages: list[dict[str, Any]],
+        reply_text: str = "",
+        *,
+        update_prompt_state: bool = True,
+    ) -> None:
+        """Record one turn's usage, estimating only what the provider omitted.
+
+        A missing usage object is not the same as a turn that cost nothing: Chat
+        servers that ignore ``stream_options`` report nothing at all, and
+        printing ``0 completion`` for a real answer is a lie. Estimates are
+        flagged so the CLI can mark them instead of presenting them as reported.
+        Compaction and summary requests pass ``update_prompt_state=False`` so
+        their prompt size is counted in the totals without becoming the main
+        conversation's compaction trigger.
+        """
+        estimated = not usage
+        if estimated:
+            prompt = estimate_tokens(messages)
+            completion = estimate_text_tokens(reply_text)
+            normalized = {
+                "prompt_tokens": prompt,
+                "completion_tokens": completion,
+                "total_tokens": prompt + completion,
+            }
+        else:
+            normalized = dict(usage)
+            if reply_text and not int(normalized.get("completion_tokens", 0) or 0):
+                prompt = int(normalized.get("prompt_tokens", 0) or 0)
+                completion = estimate_text_tokens(reply_text)
+                normalized["completion_tokens"] = completion
+                normalized["total_tokens"] = max(
+                    int(normalized.get("total_tokens", 0) or 0), prompt + completion
+                )
+                estimated = True
+        for key in self.total_usage:
+            self.total_usage[key] += int(normalized.get(key, 0))
+        if update_prompt_state:
+            self.last_prompt_tokens = int(normalized.get("prompt_tokens", 0))
+        if estimated:
+            self.estimated_turns += 1
+        self.session.append_usage(normalized)
+
+    def _complete_text(self, messages: list[dict[str, Any]]) -> str:
+        """Complete a summary/compaction request and account for its usage."""
+        complete = getattr(self.provider, "complete", None)
+        if callable(complete):
+            reply = complete(messages)
+            self._accumulate_usage(
+                reply.usage,
+                messages,
+                reply.content,
+                update_prompt_state=False,
+            )
+            return reply.content
+        # Lightweight providers used by embedders and tests only implement
+        # ``complete_text``; there is no usage object to record.
+        return self.provider.complete_text(messages)
+
+    def _close_thinking(self) -> None:
+        """Finish the reasoning block and resync the Markdown line state."""
+        if self._thinking_renderer is None:
+            return
+        if self._thinking_renderer.finish() and self._highlighter is not None:
+            self._highlighter.note_external_newline()
+
+    def _write_delta(self, text: str) -> None:
+        # Close the reasoning block first, so the answer never continues on the
+        # styled line the reasoning was written to.
+        self._close_thinking()
+        if self.stream_output:
+            if self._highlighter is not None:
+                self._highlighter.feed(text)
+            else:
+                safe = self._plain_sanitizer.feed(text)
+                if safe:
+                    self.output.write(safe)
+                    self.output.flush()
+
+    def _write_thinking(self, text: str) -> None:
+        """Render one reasoning delta in the six-level heading style."""
+        if self._thinking_renderer is not None:
+            self._thinking_renderer.feed(text)
+
+    def _finish_delta(self) -> None:
+        self._close_thinking()
+        if self._highlighter is not None:
+            self._highlighter.finish()
+        else:
+            self._plain_sanitizer.finish()
+            self._plain_sanitizer = TerminalSanitizer()
+
+    def _activity(self, message: str) -> None:
+        if not self.quiet:
+            self.error_output.write(
+                style_activity_tag(message, self.error_output) + "\n"
+            )
+            self.error_output.flush()
+
+    def _parse_tool_arguments(self, raw_arguments: str) -> dict[str, Any]:
+        try:
+            arguments = json.loads(raw_arguments or "{}")
+        except json.JSONDecodeError as exc:
+            raise ToolError(f"invalid tool JSON: {exc}") from exc
+        if not isinstance(arguments, dict):
+            raise ToolError("tool arguments must be an object")
+        return arguments
+
+    def _run_tool(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        try:
+            return self.tools.dispatch(name, arguments)
+        except (ToolError, OSError, TypeError, ValueError) as exc:
+            return {"status": "error", "message": str(exc)}
+        except Exception as exc:  # noqa: BLE001 - a bad tool must not end the turn
+            # Any unexpected failure inside a handler is still reported to the
+            # model as a tool result; re-raising would abort the whole turn and
+            # leave the user message without an answer. Subagent workers rely on
+            # the same contract, so this never raises inside a thread either.
+            return {"status": "error", "message": f"{type(exc).__name__}: {exc}"}
+
+    def _execute_tool(self, name: str, raw_arguments: str) -> dict[str, Any]:
+        try:
+            arguments = self._parse_tool_arguments(raw_arguments)
+        except ToolError as exc:
+            return {"status": "error", "message": str(exc)}
+        self._activity(self.tools.activity(name, arguments))
+        return self._run_tool(name, arguments)
+
+    def _allowed_tools(
+        self, tool_runtime: ToolRuntime | None = None
+    ) -> frozenset[str] | None:
+        """Return the tool names the runtime accepts, or None when unrestricted."""
+        allowed = getattr(tool_runtime or self.tools, "allowed_tools", None)
+        return allowed if isinstance(allowed, frozenset) else None
+
+    def _execute_tool_calls(self, calls: list[ToolCall]) -> list[dict[str, Any]]:
+        """Run one turn's tool calls, overlapping adjacent independent calls.
+
+        A subagent is a separate process that shares no in-memory state with
+        the parent, and the read-only tools cannot change the workspace, so a
+        run of adjacent calls from either set executes at the same time and
+        still reports results in request order. Everything else keeps strict
+        order: a ``write`` followed by a command that reads the file depends on
+        the earlier call finishing, so an independent group never overlaps a
+        neighbouring tool. Mixing a read with a write would also let the read
+        observe a half-written file.
+        """
+        results: list[dict[str, Any]] = []
+        index = 0
+        while index < len(calls):
+            name = calls[index].name
+            end = index + 1
+            limit = 1
+            if name == "subagent":
+                while end < len(calls) and calls[end].name == "subagent":
+                    end += 1
+                limit = self.tools.subagent_max_parallel
+            elif name in READ_ONLY_TOOLS:
+                while end < len(calls) and calls[end].name in READ_ONLY_TOOLS:
+                    end += 1
+                limit = self.tools.max_parallel
+            if limit <= 1:
+                # A group larger than the limit still has to answer every call:
+                # taking only the first one left the rest unexecuted and
+                # unanswered, and a provider rejects an unpaired tool call on
+                # the next turn.
+                for call in calls[index:end]:
+                    results.append(self._execute_tool(call.name, call.arguments))
+            elif end - index == 1:
+                results.append(self._execute_tool(name, calls[index].arguments))
+            else:
+                results.extend(self._execute_group(calls[index:end], limit))
+            index = end
+        return results
+
+    def _execute_group(self, calls: list[ToolCall], limit: int) -> list[dict[str, Any]]:
+        """Run one independent group concurrently, in call order.
+
+        Activity lines are still written from this thread before the workers
+        start, so the terminal shows requests in the order the model made them.
+        """
+        # Every slot gets an answer up front: a worker that dies before writing
+        # its result must not turn into a KeyError that aborts the turn.
+        outcomes: dict[int, dict[str, Any]] = {
+            index: {"status": "error", "message": "tool result was not recorded"}
+            for index in range(len(calls))
+        }
+        runnable: list[tuple[int, str, dict[str, Any]]] = []
+        for index, call in enumerate(calls):
+            try:
+                arguments = self._parse_tool_arguments(call.arguments)
+            except ToolError as exc:
+                # A malformed call is answered at once so it cannot block the
+                # valid calls requested in the same turn.
+                outcomes[index] = {"status": "error", "message": str(exc)}
+                continue
+            self._activity(self.tools.activity(call.name, arguments))
+            runnable.append((index, call.name, arguments))
+        if runnable:
+            # The semaphore, not the thread count, is the concurrency limit:
+            # one thread per call keeps Ctrl-C free to abandon the join below.
+            slots = threading.BoundedSemaphore(max(1, limit))
+            lock = threading.Lock()
+
+            def run(index: int, name: str, arguments: dict[str, Any]) -> None:
+                with slots:
+                    result = self._run_tool(name, arguments)
+                with lock:
+                    outcomes[index] = result
+
+            threads = [
+                threading.Thread(
+                    target=run,
+                    args=(index, name, arguments),
+                    name=f"{name}-{index}",
+                    daemon=True,
+                )
+                for index, name, arguments in runnable
+            ]
+            started: list[threading.Thread] = []
+            for thread, (index, _name, _arguments) in zip(threads, runnable):
+                try:
+                    thread.start()
+                except RuntimeError as exc:
+                    # Thread exhaustion must not abort the turn or leave a slot
+                    # without an answer; report it as that call's tool failure.
+                    outcomes[index] = {
+                        "status": "error",
+                        "message": f"cannot start tool worker: {exc}",
+                    }
+                    continue
+                started.append(thread)
+            # Daemon threads keep Ctrl-C from waiting on every child: the
+            # interrupt leaves this join and the process can exit.
+            for thread in started:
+                thread.join()
+        return [outcomes[index] for index in range(len(calls))]
+
+    def run(self, user_text: str) -> AgentResult:
+        if not user_text.strip():
+            raise ValueError("user message is empty")
+        # Read AGENTS.md / CLAUDE.md again for this run: instructions may have
+        # changed on disk since the previous turn (including via /summary).
+        self.refresh_instructions()
+        self._repair_history()
+        usage_before = dict(self.total_usage)
+        estimated_before = self.estimated_turns
+        self.session.append_message({"role": "user", "content": user_text})
+        final_text = ""
+        final_completed = False
+        final_finish_reason: str | None = None
+        turn = 0
+
+        for turn in range(1, self.max_turns + 1):
+            if self.should_compact():
+                self._compact(force=False)
+            messages = self._messages()
+            self._prompt_session_count = len(self.session.messages)
+            try:
+                reply = self.provider.stream_chat(
+                    messages,
+                    tools=self.tool_schemas,
+                    on_text=self._write_delta,
+                    on_thinking=self._write_thinking,
+                )
+            finally:
+                self._finish_delta()
+            self._accumulate_usage(reply.usage, messages, reply.content)
+            if reply.content or reply.tool_calls:
+                self.session.append_message(reply.as_message())
+            final_text = reply.content
+            final_finish_reason = reply.finish_reason
+
+            if not reply.tool_calls:
+                final_completed = reply.finish_reason in {None, "stop", "completed"}
+                if final_completed and not reply.content.strip():
+                    # A finished turn with neither text nor a tool call is a
+                    # provider-side failure; nothing was delivered to the user.
+                    final_completed = False
+                break
+
+            if reply.finish_reason in _INCOMPLETE_FINISH_REASONS:
+                for call in reply.tool_calls:
+                    result = {
+                        "status": "error",
+                        "message": (
+                            "tool call was not executed because the provider "
+                            f"stopped with finish reason {reply.finish_reason!r}"
+                        ),
+                    }
+                    self.session.append_message(
+                        {
+                            "role": "tool",
+                            "tool_call_id": call.id,
+                            "name": call.name,
+                            "content": tool_result_text(result),
+                        }
+                    )
+                    self._activity(f"  {_tool_output_preview(result)}")
+                break
+
+            if len(reply.tool_calls) > _MAX_TOOL_CALLS_PER_TURN:
+                message = (
+                    f"provider requested {len(reply.tool_calls)} tool calls in one "
+                    f"turn; the limit is {_MAX_TOOL_CALLS_PER_TURN}"
+                )
+                for call in reply.tool_calls:
+                    result = {
+                        "status": "error",
+                        "message": message,
+                    }
+                    self.session.append_message(
+                        {
+                            "role": "tool",
+                            "tool_call_id": call.id,
+                            "name": call.name,
+                            "content": tool_result_text(result),
+                        }
+                    )
+                self._activity(f"  {message}")
+                break
+
+            results = self._execute_tool_calls(reply.tool_calls)
+            for call, result in zip(reply.tool_calls, results):
+                tool_message = {
+                    "role": "tool",
+                    "tool_call_id": call.id,
+                    "name": call.name,
+                    "content": tool_result_text(result),
+                }
+                self.session.append_message(tool_message)
+                if call.name in {"shell", "subagent"}:
+                    self._activity(_shell_output_activity(result))
+                else:
+                    self._activity(f"  {_tool_output_preview(result)}")
+
+        if not final_completed:
+            self._report_incomplete(
+                turn=turn,
+                final_text=final_text,
+                finish_reason=final_finish_reason,
+            )
+        return AgentResult(
+            text=final_text,
+            completed=final_completed,
+            usage=dict(self.total_usage),
+            run_usage={
+                key: value - usage_before.get(key, 0)
+                for key, value in self.total_usage.items()
+            },
+            turns=turn,
+            usage_estimated=self.estimated_turns > estimated_before,
+        )
+
+    def _report_incomplete(
+        self,
+        *,
+        turn: int,
+        final_text: str,
+        finish_reason: str | None,
+    ) -> None:
+        if self.quiet:
+            return
+        if finish_reason in _INCOMPLETE_FINISH_REASONS:
+            # A provider-side stop is the concrete cause; max_turns only says
+            # how many rounds were allowed. Report the cause first even when the
+            # stop happened on the final allowed round.
+            preview = " ".join(final_text.split()) if final_text.strip() else ""
+            if len(preview) > 200:
+                preview = preview[:197] + "..."
+            if preview:
+                message = f"Provider stopped early: {preview}"
+            else:
+                message = (
+                    "The provider returned an empty response; the task is unfinished."
+                )
+        elif turn >= self.max_turns:
+            message = f"Reached max turns ({self.max_turns}); task may be incomplete."
+        elif not final_text.strip():
+            message = "The provider returned an empty response; the task is unfinished."
+        else:
+            # Never echo a whole answer to stderr while reporting the failure.
+            preview = " ".join(final_text.split())
+            if len(preview) > 200:
+                preview = preview[:197] + "..."
+            message = f"Provider stopped early: {preview}"
+        if finish_reason and finish_reason not in {"stop", "completed", "tool_calls"}:
+            message = f"{message} (finish reason: {finish_reason})"
+        message = sanitize_terminal_text(message)
+        self.error_output.write(message + "\n")
+        self.error_output.flush()
+
+    def should_compact(self) -> bool:
+        if self._compact_blocked_at == len(self.session.messages):
+            return False
+        threshold = float(self.settings.get("context.compact_at", 0.8))
+        window = max(1, self.provider.context_window)
+        # Re-serializing the whole history on every turn is O(n^2) over a long
+        # session; the provider-reported prompt size is the better signal and is
+        # only missing before the first reply or right after a compaction.
+        current = self.last_prompt_tokens
+        if current <= 0:
+            current = estimate_tokens(self._messages())
+        else:
+            # The provider-reported size describes the request that was sent,
+            # not the user message and tool results appended since then.
+            appended = self.session.messages[self._prompt_session_count :]
+            if appended:
+                current += estimate_tokens(appended)
+        return current >= int(window * threshold)
+
+    def _compact(self, *, force: bool) -> bool:
+        keep = max(4, int(self.settings.get("context.keep_messages", 12)))
+        messages = self.session.messages
+        if len(messages) <= keep + 2:
+            return False
+
+        target = len(messages) - keep
+        # Compaction replaces everything before the cut with a summary pair.
+        # Rewriting the pair a previous compaction wrote would summarize the
+        # summary and leave the history the same length, so that cut only counts
+        # when real messages go with it; every other boundary is accepted as
+        # soon as it drops something, because even two large early messages are
+        # worth replacing with a summary.
+        head_is_summary = _is_compacted_head(messages)
+        cut = next(
+            (
+                index
+                for index in _compaction_boundaries(messages, target)
+                if index > _COMPACT_HEAD_MESSAGES or not head_is_summary
+            ),
+            None,
+        )
+        if cut is None:
+            if not force:
+                return False
+            raise RuntimeError(
+                "cannot compact: no message boundary would shrink the history"
+            )
+
+        old_messages = messages[:cut]
+        transcript = self._transcript(old_messages)
+        prompt = (
+            "Summarize this coding-agent conversation for continuation. Preserve modified "
+            "files, decisions, exact commands or tests already run, errors, and remaining "
+            "work. Omit greetings and redundant reasoning. Use compact plain text."
+        )
+        try:
+            summary = self._complete_text(
+                [
+                    {"role": "system", "content": prompt},
+                    {
+                        "role": "user",
+                        "content": transcript,
+                    },
+                ]
+            ).strip()
+        except ProviderError:
+            if force:
+                raise
+            self._compact_blocked_at = len(self.session.messages)
+            self._activity("[compact] skipped: provider request failed")
+            return False
+        if not summary:
+            self._compact_blocked_at = len(self.session.messages)
+            return False
+
+        replacement = [
+            {
+                "role": "user",
+                "content": f"{_COMPACTED_SUMMARY_PREFIX}\n\n{summary}",
+            },
+            {
+                "role": "assistant",
+                "content": _COMPACTED_SUMMARY_ACK,
+            },
+            *messages[cut:],
+        ]
+        self.session.replace_messages(
+            replacement,
+            summary=summary,
+            dropped_messages=len(old_messages),
+        )
+        self._compact_blocked_at = None
+        self.last_prompt_tokens = 0
+        self._prompt_session_count = 0
+        self._activity(f"[compact] {len(old_messages)} messages -> summary")
+        return True
+
+    def compact(self) -> bool:
+        return self._compact(force=True)
+
+    def summarize(self) -> str:
+        """Ask the provider to condense the whole session into durable notes."""
+        summary = self._complete_text(
+            [
+                {"role": "system", "content": SUMMARY_PROMPT},
+                {
+                    "role": "user",
+                    # Summarize the conversation, not the system prompt: the
+                    # prompt already includes AGENTS.md, and feeding it back
+                    # would copy old summaries into the new one.
+                    "content": self._transcript(self.session.messages),
+                },
+            ]
+        ).strip()
+        if not summary:
+            raise ProviderError("the provider returned an empty summary")
+        return summary
+
+    def write_summary(self) -> Path:
+        """Write the session summary into the workspace ``AGENTS.md``.
+
+        The path goes through the sandbox resolver like any tool path, so a
+        symlinked or sensitive ``AGENTS.md`` is refused instead of overwritten.
+        """
+        target = self.tools.sandbox.resolve_path(
+            "AGENTS.md",
+            cwd=self.session.cwd,
+            operation="write",
+            allow_outside=self.tools.allow_outside,
+        )
+        existing: str | None = None
+        if target.is_file():
+            try:
+                existing = target.read_text(encoding="utf-8-sig")
+            except UnicodeDecodeError as exc:
+                raise ToolError(f"{target} is not valid UTF-8 text") from exc
+            except OSError as exc:
+                raise ToolError(f"cannot read {target}: {exc}") from exc
+        merged = merge_agents_summary(existing, self.summarize())
+        # Dispatch instead of calling `write` directly: `--read-only` and
+        # `tools.allow` are enforced there, and `/summary` must not be a way
+        # around them.
+        self.tools.dispatch("write", {"path": str(target), "content": merged})
+        return target
+
+    def _transcript(self, messages: list[dict[str, Any]]) -> str:
+        lines: list[str] = []
+        for message in messages:
+            role = str(message.get("role", "unknown"))
+            content = message.get("content")
+            if isinstance(content, list):
+                content = json.dumps(content, ensure_ascii=False, separators=(",", ":"))
+            lines.append(f"{role.upper()}: {content or ''}")
+            calls = message.get("tool_calls")
+            if isinstance(calls, list):
+                for call in calls:
+                    if not isinstance(call, dict):
+                        continue
+                    function = call.get("function")
+                    if not isinstance(function, dict):
+                        continue
+                    lines.append(
+                        f"TOOL_CALL {function.get('name', '')}: "
+                        f"{function.get('arguments', '')}"
+                    )
+        text = "\n".join(lines)
+        # Fit the transcript comfortably in the model window: roughly half the
+        # token budget converted to characters, bounded so a 1M-token model
+        # does not produce a multi-megabyte summarization request.
+        max_chars = min(200_000, max(4_000, self.provider.context_window // 2))
+        if len(text) > max_chars:
+            head = int(max_chars * 0.25)
+            tail = max_chars - head
+            text = text[:head] + "\n...<middle omitted>...\n" + text[-tail:]
+        return text
+
+    def new_session(self, session: Session, tool_runtime: ToolRuntime) -> None:
+        """Start a fresh conversation while keeping the active provider."""
+        schemas = available_tool_schemas(
+            tool_runtime.web_client,
+            tool_runtime.vision_client,
+            tool_runtime.subagent_enabled,
+            allowed=self._allowed_tools(tool_runtime),
+        )
+        self.session = session
+        self.tools = tool_runtime
+        self.tool_schemas = schemas
+        self.last_prompt_tokens = 0
+        self._prompt_session_count = 0
+        self._compact_blocked_at = None
+        self.estimated_turns = 0
+        self._system_prompt = None
+        self.total_usage = dict.fromkeys(self.total_usage, 0)
+
+    def switch_runtime(
+        self,
+        provider: OpenAICompatibleProvider,
+        tool_runtime: ToolRuntime,
+    ) -> None:
+        """Adopt a new provider/model without discarding the session history.
+
+        The caller owns the old provider and its optional web/vision clients and
+        closes them after this returns. Tool declarations are rebuilt because a
+        provider without ``web_tools`` or ``vision`` must stop advertising those
+        tools, and the previous prompt size is dropped because it describes the
+        old model's context window.
+        """
+        schemas = available_tool_schemas(
+            tool_runtime.web_client,
+            tool_runtime.vision_client,
+            tool_runtime.subagent_enabled,
+            allowed=self._allowed_tools(tool_runtime),
+        )
+        if hasattr(provider, "notify"):
+            provider.notify = self._activity
+        self.provider = provider
+        self.tools = tool_runtime
+        self.tool_schemas = schemas
+        self.last_prompt_tokens = 0
+        self._prompt_session_count = 0
+        self._compact_blocked_at = None
+        # A resumed session must continue with the provider that was active
+        # when the switch happened, not the one recorded at creation.
+        self.session.provider = provider.name
+        self.session.model = provider.model
+        try:
+            self.session.append_event(
+                {
+                    "type": "meta",
+                    "provider": provider.name,
+                    "model": provider.model,
+                }
+            )
+        except (OSError, TypeError, ValueError):
+            pass
+
+    def status(self) -> dict[str, Any]:
+        summary = getattr(self.tools, "sandbox_summary", None)
+        return {
+            "provider": self.provider.name,
+            "model": self.provider.model,
+            "effort": self.provider.thinking,
+            "shell": self.shell.label,
+            "session": str(self.session.path) if self.session.path else "<memory>",
+            "messages": len(self.session.messages),
+            "last_prompt_tokens": self.last_prompt_tokens,
+            "context_window": self.provider.context_window,
+            "usage": dict(self.total_usage),
+            "usage_estimated": self.estimated_turns > 0,
+            "read_only": getattr(self.tools, "read_only", False),
+            "tools": sorted(self._allowed_tools() or ()),
+            "sandbox": summary() if callable(summary) else {"enabled": False},
+        }