steerable-agent-runtime 0.4.0__tar.gz → 0.6.0__tar.gz

{steerable_agent_runtime-0.4.0 → steerable_agent_runtime-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerable-agent-runtime
-Version: 0.4.0
+Version: 0.6.0
 Summary: Steerable agent runtime: LLM, tool, storage, and transport adapters.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{steerable_agent_runtime-0.4.0 → steerable_agent_runtime-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerable-agent-runtime"
-version = "0.4.0"
+version = "0.6.0"
 description = "Steerable agent runtime: LLM, tool, storage, and transport adapters."
 readme = "README.md"
 requires-python = ">=3.10"

{steerable_agent_runtime-0.4.0 → steerable_agent_runtime-0.6.0}/src/steerable_agent_runtime/__init__.py

@@ -29,6 +29,24 @@ from .approval_policy import (
     PolicyApprover,
     rule_from_amendment,
 )
+from .ask_user import (
+    ASK_USER_SCHEMA,
+    ASK_USER_TOOL_NAME,
+    AskUserHandler,
+    make_ask_user_tool,
+)
+from .config import (
+    DEFAULT_CONFIG_PATH,
+    ConfigError,
+    ResolvedConfig,
+    load_user_config,
+    resolve_config,
+)
+from .plugins import (
+    STEERABLE_TOOLS_ENTRY_POINT_GROUP,
+    PluginLoadError,
+    load_tool_entry_points,
+)
 from .branch import (
     BranchPoint,
     ForkResult,
@@ -39,6 +57,7 @@ from .branch import (
 )
 from .cache_control import (
     CacheControlProvider,
+    CacheDriftMonitor,
     CacheRetention,
     place_cache_breakpoints,
     system_blocks_with_cache,
@@ -195,6 +214,7 @@ from .subagent import (
     FilteredToolsExecutor,
     SubagentConfig,
     SubagentExecutor,
+    SubagentRegistry,
     subagent_tool_descriptor,
 )
 from .tokens import (
@@ -230,8 +250,13 @@ __all__ = [
     "REASONING_EFFORT_ORDER",
     "RECORD_FORMAT_VERSION",
     "TOOL_SEARCH_NAME",
+    "ASK_USER_SCHEMA",
+    "ASK_USER_TOOL_NAME",
+    "STEERABLE_TOOLS_ENTRY_POINT_GROUP",
     "AgentPool",
     "AntiHallucinationConfig",
+    "AskUserHandler",
+    "PluginLoadError",
     "AntiHallucinationHooks",
     "ApprovalAborted",
     "ApprovalDecision",
@@ -242,9 +267,13 @@ __all__ = [
     "ApprovalStore",
     "Approver",
     "AutoApprover",
+    "ConfigError",
+    "DEFAULT_CONFIG_PATH",
+    "ResolvedConfig",
     "BranchPoint",
     "BudgetExhaustedError",
     "CacheControlProvider",
+    "CacheDriftMonitor",
     "CacheRetention",
     "CalibratingProvider",
     "ChainHooks",
@@ -328,6 +357,7 @@ __all__ = [
     "StorageError",
     "SubagentConfig",
     "SubagentExecutor",
+    "SubagentRegistry",
     "TextPart",
     "ToolDispatchError",
     "ToolExecutor",
@@ -367,8 +397,12 @@ __all__ = [
     "last_world_state_snapshot",
     "lineage",
     "load_history_transcript",
+    "load_tool_entry_points",
+    "load_user_config",
+    "resolve_config",
     "load_recorded_requests",
     "load_transcript",
+    "make_ask_user_tool",
     "matches_conditions",
     "mcp_invoker",
     "merge_patch",

steerable_agent_runtime-0.6.0/src/steerable_agent_runtime/ask_user.py

@@ -0,0 +1,154 @@
+"""Structured user questions — the ``ask_user`` tool.
+
+The agent pauses mid-run and asks the user a structured set of questions
+(select / text / password) before continuing. The wire payload mirrors the
+protocol's ``AskUserQuestionsPayload`` (TS) so the desktop card renders it
+unchanged; the handler is the seam a product injects to actually collect the
+answers (a UI card over the reverse channel, an ACP elicitation, a CLI
+prompt).
+
+The tool is blocking by construction: ``dispatch`` awaits the handler, and
+the answers are returned as the tool result so they land in the durable
+record and the model's next context. This mirrors dsh's ``ask_user_question``
+— the loop does not continue until the user (or a timeout) answers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol
+
+from .errors import ToolDispatchError
+
+#: The tool name the model calls.
+ASK_USER_TOOL_NAME = "ask_user"
+
+#: JSON Schema for the tool's arguments — one intro plus a list of questions.
+#: Field names match ``AskUserQuestionsPayload`` so the host can render the
+#: arguments directly as the card payload.
+ASK_USER_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "intro": {
+            "type": "string",
+            "description": "One-line framing shown above the questions.",
+        },
+        "outro": {
+            "type": "string",
+            "description": "Optional line shown below the questions.",
+        },
+        "questions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "text": {"type": "string"},
+                    "type": {
+                        "type": "string",
+                        "enum": ["select", "text", "password"],
+                    },
+                    "options": {"type": "array", "items": {"type": "string"}},
+                    "placeholder": {"type": "string"},
+                    "multiSelect": {"type": "boolean"},
+                },
+                "required": ["id", "text"],
+            },
+        },
+    },
+    "required": ["intro", "questions"],
+}
+
+#: Alias keys real models emit for the canonical ``AskUserQuestionsPayload``
+#: fields (observed: gpt-oss via Ollama answers the schema with Inquirer-style
+#: ``name``/``message``/``choices``). Normalized at this model-JSON boundary so
+#: hosts only ever render the canonical payload; the canonical key wins when
+#: both are present.
+_QUESTION_ALIASES = {"id": "name", "text": "message", "options": "choices"}
+
+
+def _normalize_questions(questions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Map known alias keys onto the canonical payload fields and require the
+    two fields the host card cannot render without (``id`` to key the answer,
+    ``text`` to label the control). A violation raises ``ToolDispatchError`` —
+    the router wraps it as the tool result, so the model sees exactly what to
+    fix and retries within the same turn."""
+    if not isinstance(questions, list):
+        raise ToolDispatchError(
+            f"ask_user: questions must be an array, got {type(questions).__name__}"
+        )
+    normalized: list[dict[str, Any]] = []
+    for index, question in enumerate(questions):
+        if not isinstance(question, dict):
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}] must be an object, "
+                f"got {type(question).__name__}"
+            )
+        q = dict(question)
+        for canonical, alias in _QUESTION_ALIASES.items():
+            if canonical not in q and alias in q:
+                q[canonical] = q.pop(alias)
+        if not isinstance(q.get("id"), str) or not q["id"]:
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}] is missing a non-empty string "
+                '"id" (the answer-map key).'
+            )
+        if not isinstance(q.get("text"), str) or not q["text"]:
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}] is missing a non-empty string "
+                '"text" (the question label shown to the user).'
+            )
+        normalized.append(q)
+    return normalized
+
+
+class AskUserHandler(Protocol):
+    """Product-injected seam that collects answers for one question set.
+
+    Receives the validated ``intro`` and ``questions`` list and returns a
+    mapping of question id → answer (a string, or a list of strings for a
+    multi-select). Implementations must not raise on a user cancel — return
+    an empty mapping so the loop records "no answer" and moves on.
+    """
+
+    def __call__(
+        self, intro: str, questions: list[dict[str, Any]]
+    ) -> Awaitable[dict[str, Any]]: ...
+
+
+def make_ask_user_tool(handler: AskUserHandler) -> Callable[..., Awaitable[dict[str, Any]]]:
+    """Build the ``ask_user`` tool handler bound to ``handler``.
+
+    The returned coroutine function carries the registration metadata the
+    router reads (name, description, schema) so a host registers it with one
+    call. The tool is marked ``require_consent=False`` and
+    ``concurrency_safe=False``: asking the user is itself the interaction, and
+    two concurrent question cards would race for the same UI surface.
+    """
+
+    async def ask_user(
+        intro: str, questions: list[dict[str, Any]], outro: str | None = None
+    ) -> dict[str, Any]:
+        normalized = _normalize_questions(questions)
+        answers = await handler(intro, normalized)
+        return {
+            "intro": intro,
+            "outro": outro,
+            "questions": normalized,
+            "answers": answers,
+        }
+
+    ask_user.__steerable_tool_meta__ = {  # type: ignore[attr-defined]
+        "name": ASK_USER_TOOL_NAME,
+        "mode": "read",  # no side effects on the workspace; it gathers input
+        "description": (
+            "Pause and ask the user a structured set of questions (select / "
+            "text / password) when you need information only they have. "
+            "Blocks until they answer; the answers come back as the result."
+        ),
+        "schema": ASK_USER_SCHEMA,
+        "require_consent": False,
+        "concurrency_safe": False,
+        "exposure": "direct",
+    }
+    return ask_user

{steerable_agent_runtime-0.4.0 → steerable_agent_runtime-0.6.0}/src/steerable_agent_runtime/cache_control.py

@@ -23,12 +23,16 @@ comes from the prefix stability the rest of the stack already keeps.
 
 from __future__ import annotations
 
+import logging
 from collections.abc import AsyncIterator, Sequence
 from dataclasses import dataclass
 from typing import Any, Iterable, Literal
 
+from .hooks import NoopHooks, PreStepAction
 from .llm import LLMMessage, LLMProvider, LLMStreamChunk, LLMUsage
 
+logger = logging.getLogger(__name__)
+
 CacheRetention = Literal["none", "short", "long"]
 
 #: Anthropic's explicit breakpoint API. Other providers have no breakpoint
@@ -36,6 +40,19 @@ CacheRetention = Literal["none", "short", "long"]
 _EXPLICIT_CACHE_PROVIDERS = {"anthropic", "claude"}
 
 
+def _marker_for(retention: CacheRetention) -> dict[str, Any]:
+    """Map a retention class onto the Anthropic breakpoint marker.
+
+    ``short`` is the 5-minute default; ``long`` opts into the 1-hour TTL
+    (CC ``CLAUDE_CODE_PROMPT_CACHE_TTL`` parity — a deliberate trade: fewer
+    cache writes on slow-moving prefixes, at Anthropic's higher 1h write
+    price). ``none`` never reaches here (the request skips anchoring).
+    """
+    if retention == "long":
+        return {"type": "ephemeral", "ttl": "1h"}
+    return {"type": "ephemeral"}
+
+
 @dataclass(slots=True)
 class CacheControlProvider:
     """LLMProvider decorator: emits prompt-cache breakpoints per request.
@@ -105,10 +122,15 @@ class CacheControlProvider:
             kwargs.pop("cache_retention", None)
             return tools, kwargs
         out = dict(kwargs)
+        marker = _marker_for(retention)
         shaped_tools = (
-            place_cache_breakpoints(list(tools)) if tools is not None else None
+            place_cache_breakpoints(list(tools), cache_control=marker)
+            if tools is not None
+            else None
         )
-        out["_cache_tail_anchor"] = True
+        # The provider-owned anchors (system block, transcript tail) read the
+        # marker off this key so all three breakpoints share one TTL.
+        out["_cache_tail_anchor"] = marker
         return shaped_tools, out
 
     def _effective_retention(self, kwargs: dict[str, Any]) -> CacheRetention:
@@ -152,3 +174,81 @@ def system_blocks_with_cache(
     """
     marker = cache_control or {"type": "ephemeral"}
     return [{"type": "text", "text": system_text, "cache_control": marker}]
+
+
+class CacheDriftMonitor(NoopHooks):
+    """``pre_step`` observer: flag prompt-cache drift from provider usage.
+
+    Each round it reads the PREVIOUS request's accounting off the loop ctx
+    (``last_prompt_tokens`` / ``last_cached_prompt_tokens`` — the read side
+    surfaced on ``stage_complete``). The monitor arms once a round shows the
+    cache actually serving tokens; from then on, ``consecutive_rounds``
+    rounds whose hit rate stays below ``min_hit_rate`` (while the prompt is
+    at least ``min_prompt_tokens`` — below that, caching barely matters) set
+    ``drift_detected`` and log a warning with the numbers. A round at or
+    above the rate resets the count and clears the flag.
+
+    This is the deliberate loop logic behind the raw ``stage_complete``
+    numbers (CC ``globalCacheStrategy`` / ``cacheControlHash`` parity): a
+    collapse means the cached prefix broke — a transcript rewrite, a changed
+    tool list, a TTL expiry — and one low round is normal right after a
+    compaction (the prefix re-warms on the next request), which is why the
+    verdict requires consecutive low rounds. Providers without cache
+    accounting never arm the monitor, so implicit-cache deployments that
+    report nothing see no false drift.
+    """
+
+    def __init__(
+        self,
+        *,
+        min_prompt_tokens: int = 1024,
+        min_hit_rate: float = 0.5,
+        consecutive_rounds: int = 3,
+    ) -> None:
+        if not 0 < min_hit_rate <= 1:
+            raise ValueError("min_hit_rate must be in (0, 1]")
+        if not 1 <= consecutive_rounds:
+            raise ValueError("consecutive_rounds must be >= 1")
+        self._min_prompt = min_prompt_tokens
+        self._min_hit_rate = min_hit_rate
+        self._consecutive_rounds = consecutive_rounds
+        # Observability for callers/tests (CompactionHooks-counter pattern).
+        self.armed = False
+        self.drift_detected = False
+        self.consecutive_low_hit_rounds = 0
+        self.last_hit_rate: float | None = None
+
+    async def pre_step(
+        self, transcript: list[LLMMessage], ctx: Any
+    ) -> PreStepAction:
+        prompt = getattr(ctx, "last_prompt_tokens", None)
+        cached = getattr(ctx, "last_cached_prompt_tokens", None)
+        if not prompt or cached is None or prompt < self._min_prompt:
+            return PreStepAction(kind="proceed")
+        hit_rate = cached / prompt
+        self.last_hit_rate = hit_rate
+        if cached > 0:
+            self.armed = True
+        if not self.armed:
+            return PreStepAction(kind="proceed")
+        if hit_rate >= self._min_hit_rate:
+            self.consecutive_low_hit_rounds = 0
+            self.drift_detected = False
+            return PreStepAction(kind="proceed")
+        self.consecutive_low_hit_rounds += 1
+        if (
+            self.consecutive_low_hit_rounds >= self._consecutive_rounds
+            and not self.drift_detected
+        ):
+            self.drift_detected = True
+            logger.warning(
+                "prompt-cache drift: hit rate %.2f below %.2f for %d "
+                "consecutive rounds (prompt=%d cached=%d) — the cached "
+                "prefix broke (rewrite, tool-list change, or TTL expiry)",
+                hit_rate,
+                self._min_hit_rate,
+                self.consecutive_low_hit_rounds,
+                prompt,
+                cached,
+            )
+        return PreStepAction(kind="proceed")

{steerable_agent_runtime-0.4.0 → steerable_agent_runtime-0.6.0}/src/steerable_agent_runtime/compaction.py

@@ -25,6 +25,36 @@ System messages and the first user message (the goal) are always kept; the
 most recent ``keep_last_messages`` are never touched. Between compactions
 the transcript is append-only, so provider prompt caches keep hitting; a
 rewrite invalidates the cache once, then the prefix is stable again.
+
+Three trigger paths share the fold/summarize machinery:
+
+- **pressure** (``pre_step``, above) — the reactive default;
+- **overflow recovery** (``on_request_error``) — the heuristic threshold can
+  still miss the real window, so a context-overflow error forces one
+  compaction pass and retries, bounded per round;
+- **micro-compaction** (``pre_step``, opt-in ``micro_compact_interval_rounds``)
+  — every N rounds, fold old tool results regardless of pressure (CC
+  time-based microcompact parity). Off by default: each fold invalidates the
+  prompt-cache prefix, so the interval trades cache hits for a bounded
+  transcript;
+- **manual** (``compact_now``) — the host-command path (CC ``/compact``
+  parity): fold + summarize on demand, bypassing threshold, hysteresis, and
+  the circuit breaker.
+
+Two safety rails share the machinery:
+
+- Every rewrite carries its ``pre_tokens`` / ``post_tokens`` estimate onto
+  the recorded ``CompactionBoundary`` (CC ``compact_boundary`` parity), so
+  traces chart compaction effectiveness without re-estimating from bodies.
+- A **circuit breaker** (CC auto-compact breaker parity): a pressure
+  compaction whose post-estimate is still over threshold counts as
+  ineffective; three consecutive ineffective compactions open the circuit
+  and the pressure path stops firing — each further rewrite would only
+  invalidate the prompt-cache prefix without shrinking the transcript. The
+  overflow-recovery path keeps its own per-round bound and stays live, so
+  the turn still fails loud (bounded retries, then a named error) instead
+  of spinning. A round that lands under threshold — or any successful
+  compaction — resets the count.
 """
 
 from __future__ import annotations
@@ -75,17 +105,26 @@ class CompactionHooks(NoopHooks):
         model: str | None = None,
         recompact_margin_ratio: float = 0.1,
         fold_excerpt_chars: int = _FOLD_EXCERPT_CHARS,
+        micro_compact_interval_rounds: int = 0,
     ) -> None:
         if not 0 < threshold_ratio <= 1:
             raise ValueError("threshold_ratio must be in (0, 1]")
         if not 0 <= recompact_margin_ratio:
             raise ValueError("recompact_margin_ratio must be >= 0")
+        if not 0 <= micro_compact_interval_rounds:
+            raise ValueError("micro_compact_interval_rounds must be >= 0")
         self._max_tokens = max_context_tokens
         self._threshold = threshold_ratio
         self._keep_last = keep_last_messages
         self._keep_last_tools = keep_last_tool_results
         self._fold_excerpt_chars = fold_excerpt_chars
         self._summarizer = summarizer
+        #: Proactive micro-compaction (CC time-based microcompact parity):
+        #: every N rounds, fold old tool results regardless of pressure, so a
+        #: long chatty run never drifts toward the window. 0 (default) is off
+        #: — each fold invalidates the provider prompt-cache prefix, so the
+        #: interval trades cache hits for a bounded transcript.
+        self._micro_compact_interval = micro_compact_interval_rounds
         #: Model name used for calibrated token estimates (see tokens.py).
         self._model = model
         #: Hysteresis: after a compaction, pressure must grow by
@@ -98,6 +137,8 @@ class CompactionHooks(NoopHooks):
         self._last_compaction_pressure: int | None = None
         # Observability for callers/tests: how many compactions happened.
         self.compactions = 0
+        # Observability: how many of them were periodic micro-compactions.
+        self.micro_compactions = 0
         # Overflow-recovery state: consecutive context-overflow retries within
         # one round. Capped so a pathological transcript cannot spin a
         # compact→overflow→compact loop forever.
@@ -107,6 +148,14 @@ class CompactionHooks(NoopHooks):
         self.max_overflow_retries = 2
         # Observability: how many overflow-driven compactions happened.
         self.overflow_recoveries = 0
+        #: Consecutive ineffective pressure compactions (post-estimate still
+        #: over threshold) before the circuit opens (CC auto-compact breaker
+        #: parity). The overflow path is bounded separately and unaffected.
+        self.max_consecutive_failures = 3
+        self._consecutive_failures = 0
+        # Observability: True once the breaker tripped; the pressure path
+        # stops firing for the rest of the session.
+        self.circuit_open = False
 
     def _estimate(self, transcript: Sequence[LLMMessage]) -> int:
         return estimate_tokens(transcript, model=self._model)
@@ -137,8 +186,40 @@ class CompactionHooks(NoopHooks):
     async def pre_step(
         self, transcript: list[LLMMessage], ctx: Any
     ) -> PreStepAction:
+        round_index = getattr(ctx, "round_index", 0)
+        if (
+            self._micro_compact_interval > 0
+            and round_index > 0
+            and round_index % self._micro_compact_interval == 0
+        ):
+            pruned = self._fold_old_tool_results(transcript)
+            if pruned is not transcript:
+                self.compactions += 1
+                self.micro_compactions += 1
+                self._reset_observed(ctx)
+                return PreStepAction(
+                    kind="proceed",
+                    rewrite=RewriteRequest(
+                        messages=pruned,
+                        reason=(
+                            "micro-compact: periodic tool-result prune "
+                            f"(every {self._micro_compact_interval} rounds)"
+                        ),
+                        action="micro_compact",
+                        pre_tokens=self._estimate(transcript),
+                        post_tokens=self._estimate(pruned),
+                    ),
+                )
         pressure = self._pressure(transcript, ctx)
         if pressure < self._threshold * self._max_tokens:
+            # A healthy round resets the breaker count — the pathology (or
+            # the transcript that caused it) is gone.
+            self._consecutive_failures = 0
+            return PreStepAction(kind="proceed")
+        if self.circuit_open:
+            # Breaker tripped: further pressure rewrites only invalidate the
+            # prompt-cache prefix without shrinking the transcript. The
+            # overflow path stays live and fails loud if the window is hit.
             return PreStepAction(kind="proceed")
         if (
             self._last_compaction_pressure is not None
@@ -146,9 +227,11 @@ class CompactionHooks(NoopHooks):
         ):
             return PreStepAction(kind="proceed")
 
+        threshold = self._threshold * self._max_tokens
         compacted = self._fold_old_tool_results(transcript)
-        if self._estimate(compacted) < self._threshold * self._max_tokens:
+        if self._estimate(compacted) < threshold:
             self.compactions += 1
+            self._consecutive_failures = 0
             self._last_compaction_pressure = pressure
             self._reset_observed(ctx)
             return PreStepAction(
@@ -157,11 +240,23 @@ class CompactionHooks(NoopHooks):
                     messages=compacted,
                     reason="context pressure: folded old tool results",
                     action="compact",
+                    pre_tokens=pressure,
+                    post_tokens=self._estimate(compacted),
                 ),
             )
 
         compacted = await self._summarize_middle(compacted)
+        post = self._estimate(compacted)
         self.compactions += 1
+        if post < threshold:
+            self._consecutive_failures = 0
+        else:
+            # Ineffective: even fold+summarize stayed over threshold (e.g. a
+            # single kept tool result bigger than the window). Three in a
+            # row open the circuit.
+            self._consecutive_failures += 1
+            if self._consecutive_failures >= self.max_consecutive_failures:
+                self.circuit_open = True
         self._last_compaction_pressure = pressure
         self._reset_observed(ctx)
         return PreStepAction(
@@ -170,6 +265,36 @@ class CompactionHooks(NoopHooks):
                 messages=compacted,
                 reason="context pressure: summarized middle",
                 action="compact",
+                pre_tokens=pressure,
+                post_tokens=post,
+            ),
+        )
+
+    async def compact_now(self, transcript: list[LLMMessage], ctx: Any) -> PreStepAction:
+        """Manual compaction (CC ``/compact`` parity): fold old tool results,
+        then summarize the middle, regardless of pressure, hysteresis, or the
+        circuit breaker — the user asked for it. Returns a ``proceed`` action
+        carrying the rewrite; when neither stage changes anything the action
+        carries no rewrite (nothing was worth invalidating the cache for).
+        A manual pass resets the breaker count: the user has taken over.
+        """
+        pre = self._estimate(transcript)
+        compacted = self._fold_old_tool_results(transcript)
+        compacted = await self._summarize_middle(compacted)
+        self._consecutive_failures = 0
+        if compacted is transcript or compacted == transcript:
+            return PreStepAction(kind="proceed", reason="compact: nothing to fold")
+        self.compactions += 1
+        self._last_compaction_pressure = pre
+        self._reset_observed(ctx)
+        return PreStepAction(
+            kind="proceed",
+            rewrite=RewriteRequest(
+                messages=compacted,
+                reason="manual compact",
+                action="compact",
+                pre_tokens=pre,
+                post_tokens=self._estimate(compacted),
             ),
         )
 
@@ -214,13 +339,22 @@ class CompactionHooks(NoopHooks):
                 messages=compacted,
                 reason="context overflow: compacted transcript before retry",
                 action="overflow_recovery",
+                pre_tokens=self._estimate(transcript),
+                post_tokens=self._estimate(compacted),
             ),
         )
 
     # ------------------------------------------------------------------
 
     def _fold_old_tool_results(self, transcript: list[LLMMessage]) -> list[LLMMessage]:
-        tool_idx = [i for i, m in enumerate(transcript) if m.role == "tool"]
+        # Already-folded results are excluded: re-folding them would stack
+        # markers and invalidate the prompt-cache prefix for zero gain, and
+        # ``keep_last_tool_results`` should count *readable* results.
+        tool_idx = [
+            i
+            for i, m in enumerate(transcript)
+            if m.role == "tool" and not m.content_text.startswith(_FOLDED_TOOL_MARKER)
+        ]
         fold_before = len(tool_idx) - self._keep_last_tools
         if fold_before <= 0:
             return transcript