steerable-agent-runtime 0.6.3__tar.gz → 0.6.5__tar.gz

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/PKG-INFO

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

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/pyproject.toml

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

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/src/steerable_agent_runtime/__init__.py

@@ -35,6 +35,13 @@ from .ask_user import (
     AskUserHandler,
     make_ask_user_tool,
 )
+from .todo import (
+    TODO_SCHEMA,
+    TODO_TOOL_NAME,
+    TodoStore,
+    make_todo_write_tool,
+    todo_write_tool_descriptor,
+)
 from .config import (
     DEFAULT_CONFIG_PATH,
     ConfigError,
@@ -262,6 +269,8 @@ __all__ = [
     "TOOL_SEARCH_NAME",
     "ASK_USER_SCHEMA",
     "ASK_USER_TOOL_NAME",
+    "TODO_SCHEMA",
+    "TODO_TOOL_NAME",
     "STEERABLE_TOOLS_ENTRY_POINT_GROUP",
     "AgentPool",
     "AntiHallucinationConfig",
@@ -382,6 +391,7 @@ __all__ = [
     "ToolExecutor",
     "ToolExposure",
     "ToolRouter",
+    "TodoStore",
     "TraceRecorder",
     "TranscriptAppend",
     "TransportAdapter",
@@ -423,6 +433,7 @@ __all__ = [
     "load_recorded_requests",
     "load_transcript",
     "make_ask_user_tool",
+    "make_todo_write_tool",
     "matches_conditions",
     "mcp_invoker",
     "merge_patch",
@@ -456,6 +467,7 @@ __all__ = [
     "system_blocks_with_cache",
     "text_parts",
     "to_otlp_json",
+    "todo_write_tool_descriptor",
     "tool",
     "tool_search_descriptor",
     "upgrade_entry_dict",

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/src/steerable_agent_runtime/ask_user.py

@@ -71,9 +71,16 @@ ASK_USER_SCHEMA: dict[str, Any] = {
                         ),
                     },
                     "placeholder": {"type": "string"},
-                    "multiSelect": {"type": "boolean"},
+                    "multiSelect": {
+                        "type": "boolean",
+                        "description": (
+                            "Whether the user may pick several options. "
+                            "Required (CC parity): commit to single vs multi "
+                            "explicitly — pass false for a single-select."
+                        ),
+                    },
                 },
-                "required": ["id", "text"],
+                "required": ["id", "text", "multiSelect"],
             },
         },
     },
@@ -170,12 +177,15 @@ def _normalize_questions(questions: list[dict[str, Any]]) -> list[dict[str, Any]
                 f"ask_user: questions[{index}].header is {len(header)} chars; "
                 f"the chip label must be <= {_MAX_HEADER_LEN}."
             )
-        # multiSelect: CC requires the model to commit to single vs multi.
-        # Default to False when absent so existing single-select calls keep
-        # working, but stamp it so hosts always read an explicit boolean.
+        # multiSelect: CC requires the model to commit to single vs multi —
+        # the field is required, so an omission is a model error to fix, not
+        # a default to assume.
         if "multiSelect" not in q or q["multiSelect"] is None:
-            q["multiSelect"] = False
-        elif not isinstance(q["multiSelect"], bool):
+            raise ToolDispatchError(
+                f"ask_user: questions[{index}].multiSelect is required "
+                "(CC parity) — pass false for a single-select question."
+            )
+        if not isinstance(q["multiSelect"], bool):
             raise ToolDispatchError(
                 f"ask_user: questions[{index}].multiSelect must be a boolean, "
                 f"got {type(q['multiSelect']).__name__}."

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/src/steerable_agent_runtime/compaction.py

@@ -57,6 +57,14 @@ Two safety rails share the machinery:
   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.
+- A **rapid-refill breaker** (CC parity): a compaction that lands under
+  threshold but refills within ``rapid_refill_window_rounds`` rounds of the
+  previous one counts as a refill; ``max_rapid_refills`` consecutive
+  refills open the same circuit — the transcript is churning faster than
+  compaction can help, so further rewrites only kill the prompt cache.
+  The tripping round appends a ``CompactionThrashingReminder`` (model- and
+  UI-visible) with an actionable converge notice. ``circuit_reason``
+  records which breaker tripped.
 """
 
 from __future__ import annotations
@@ -64,9 +72,10 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import Any
 
-from .hooks import NoopHooks, PreStepAction, RetryAction, RewriteRequest
+from .hooks import NoopHooks, PreStepAction, RetryAction, RewriteRequest, TranscriptAppend
 from .llm import LLMMessage, LLMProvider
 from .llm.errors import classify_error
+from .reminders import CompactionThrashingReminder
 from .tokens import estimate_tokens
 
 _SUMMARY_MARKER = "[context compacted: earlier conversation summarized]"
@@ -108,6 +117,8 @@ class CompactionHooks(NoopHooks):
         recompact_margin_ratio: float = 0.1,
         fold_excerpt_chars: int = _FOLD_EXCERPT_CHARS,
         micro_compact_interval_rounds: int = 0,
+        rapid_refill_window_rounds: int = 3,
+        max_rapid_refills: int = 3,
     ) -> None:
         if not 0 < threshold_ratio <= 1:
             raise ValueError("threshold_ratio must be in (0, 1]")
@@ -115,6 +126,10 @@ class CompactionHooks(NoopHooks):
             raise ValueError("recompact_margin_ratio must be >= 0")
         if not 0 <= micro_compact_interval_rounds:
             raise ValueError("micro_compact_interval_rounds must be >= 0")
+        if not 1 <= rapid_refill_window_rounds:
+            raise ValueError("rapid_refill_window_rounds must be >= 1")
+        if not 1 <= max_rapid_refills:
+            raise ValueError("max_rapid_refills must be >= 1")
         self._max_tokens = max_context_tokens
         self._threshold = threshold_ratio
         self._keep_last = keep_last_messages
@@ -155,9 +170,22 @@ class CompactionHooks(NoopHooks):
         #: parity). The overflow path is bounded separately and unaffected.
         self.max_consecutive_failures = 3
         self._consecutive_failures = 0
+        #: Rapid-refill breaker (CC parity): a compaction that *worked* but
+        #: whose freed space refills within ``rapid_refill_window_rounds``
+        #: rounds counts as a refill; ``max_rapid_refills`` consecutive
+        #: refills open the circuit — the transcript is churning faster than
+        #: compaction can help, and each rewrite only kills the prompt-cache
+        #: prefix. Distinct from the failure breaker above, which catches
+        #: compactions that never get under threshold at all.
+        self.rapid_refill_window_rounds = rapid_refill_window_rounds
+        self.max_rapid_refills = max_rapid_refills
+        self._rapid_refills = 0
+        self._last_compact_round: int | None = None
         # Observability: True once the breaker tripped; the pressure path
         # stops firing for the rest of the session.
         self.circuit_open = False
+        #: Which breaker tripped: "consecutive_failures" | "rapid_refill".
+        self.circuit_reason: str | None = None
 
     def _estimate(self, transcript: Sequence[LLMMessage]) -> int:
         return estimate_tokens(transcript, model=self._model)
@@ -214,9 +242,10 @@ class CompactionHooks(NoopHooks):
                 )
         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.
+            # A healthy round resets both breaker counts — the pathology
+            # (or the transcript that caused it) is gone.
             self._consecutive_failures = 0
+            self._rapid_refills = 0
             return PreStepAction(kind="proceed")
         if self.circuit_open:
             # Breaker tripped: further pressure rewrites only invalidate the
@@ -234,6 +263,7 @@ class CompactionHooks(NoopHooks):
         if self._estimate(compacted) < threshold:
             self.compactions += 1
             self._consecutive_failures = 0
+            notice = self._note_successful_compaction(round_index)
             self._last_compaction_pressure = pressure
             self._reset_observed(ctx)
             return PreStepAction(
@@ -245,13 +275,17 @@ class CompactionHooks(NoopHooks):
                     pre_tokens=pressure,
                     post_tokens=self._estimate(compacted),
                 ),
+                appends=[notice] if notice is not None else None,
+                append_action="reminder" if notice is not None else None,
             )
 
         compacted = await self._summarize_middle(compacted)
         post = self._estimate(compacted)
         self.compactions += 1
+        notice: TranscriptAppend | None = None
         if post < threshold:
             self._consecutive_failures = 0
+            notice = self._note_successful_compaction(round_index)
         else:
             # Ineffective: even fold+summarize stayed over threshold (e.g. a
             # single kept tool result bigger than the window). Three in a
@@ -259,6 +293,7 @@ class CompactionHooks(NoopHooks):
             self._consecutive_failures += 1
             if self._consecutive_failures >= self.max_consecutive_failures:
                 self.circuit_open = True
+                self.circuit_reason = "consecutive_failures"
         self._last_compaction_pressure = pressure
         self._reset_observed(ctx)
         return PreStepAction(
@@ -270,20 +305,52 @@ class CompactionHooks(NoopHooks):
                 pre_tokens=pressure,
                 post_tokens=post,
             ),
+            appends=[notice] if notice is not None else None,
+            append_action="reminder" if notice is not None else None,
         )
 
+    def _note_successful_compaction(self, round_index: int) -> TranscriptAppend | None:
+        """Rapid-refill bookkeeping for a compaction that landed under
+        threshold. A refill is a successful compaction within
+        ``rapid_refill_window_rounds`` of the previous one; on the
+        ``max_rapid_refills``-th consecutive refill the circuit opens and
+        the round carries the thrashing reminder so both the model and the
+        host UI see the actionable notice."""
+        if (
+            self._last_compact_round is not None
+            and round_index - self._last_compact_round <= self.rapid_refill_window_rounds
+        ):
+            self._rapid_refills += 1
+        else:
+            self._rapid_refills = 0
+        self._last_compact_round = round_index
+        if self._rapid_refills >= self.max_rapid_refills and not self.circuit_open:
+            self.circuit_open = True
+            self.circuit_reason = "rapid_refill"
+            reminder = CompactionThrashingReminder(
+                self._rapid_refills, self.rapid_refill_window_rounds
+            )
+            return TranscriptAppend(
+                message=LLMMessage.text_of(reminder.role, reminder.render()),
+                kind=reminder.content_kind,
+                fragment=reminder,
+            )
+        return None
+
     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.
+        A manual pass resets both breaker counts: 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
+        self._rapid_refills = 0
+        self._last_compact_round = None
         if compacted is transcript or compacted == transcript:
             return PreStepAction(kind="proceed", reason="compact: nothing to fold")
         self.compactions += 1

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/src/steerable_agent_runtime/harness.py

@@ -209,6 +209,11 @@ class PressureCompaction:
     # trades cache hits for a bounded transcript. R16 found compaction does not
     # move the eval score, so this stays opt-in capability, not a default.
     micro_compact_interval_rounds: int = 0
+    # Rapid-refill breaker (CC parity): a successful compaction whose freed
+    # space refills within this many rounds of the previous one counts as a
+    # refill; max_rapid_refills consecutive refills open the circuit.
+    rapid_refill_window_rounds: int = 3
+    max_rapid_refills: int = 3
     name: str = "pressure_compaction"
     assumes: str = (
         "long trajectories exceed the window; older detail is expendable "
@@ -231,6 +236,8 @@ class PressureCompaction:
                 summarizer=provider,
                 model=self.model,
                 micro_compact_interval_rounds=self.micro_compact_interval_rounds,
+                rapid_refill_window_rounds=self.rapid_refill_window_rounds,
+                max_rapid_refills=self.max_rapid_refills,
                 **extra,
             ),
             forward=("compact_now",),

{steerable_agent_runtime-0.6.3 → steerable_agent_runtime-0.6.5}/src/steerable_agent_runtime/llm/__init__.py

@@ -158,7 +158,9 @@ from .errors import (
     classify_http_status,
     is_retryable,
 )
+from .google_genai import GoogleGenAIProvider
 from .openai_compat import OpenAICompatProvider
+from .openai_responses import OpenAIResponsesProvider
 from .presets import (
     PROVIDER_PRESETS,
     PresetEntry,
@@ -174,6 +176,7 @@ __all__ = [
     "RETRYABLE_KINDS",
     "AnthropicProvider",
     "ContentPart",
+    "GoogleGenAIProvider",
     "ImagePart",
     "LLMError",
     "LLMErrorKind",
@@ -188,6 +191,7 @@ __all__ = [
     "describe_compat_flags",
     "describe_provider_presets",
     "OpenAICompatProvider",
+    "OpenAIResponsesProvider",
     "TextPart",
     "classify_error",
     "classify_http_status",