local-operator 0.45.2__tar.gz → 0.45.4__tar.gz

{local_operator-0.45.2 → local_operator-0.45.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: local-operator
-Version: 0.45.2
+Version: 0.45.4
 Summary: A team of proactive AI assistants that can work together behind the scenes to help you get mundane tasks done so you can focus on the fun stuff.
 Author-email: Damian Tran <damian@gominerva.com>
 License: MIT License

{local_operator-0.45.2 → local_operator-0.45.4}/local_operator/compaction/api.py

@@ -50,16 +50,23 @@ from .pruning import (
     _is_useless,
     compute_suffix_tokens,
     prune_tool_outputs,
+    shed_frames_to_wire_budget,
 )
 from .thresholds import (
+    DEFAULT_WIRE_BYTES_BUDGET,
+    DEFAULT_WIRE_BYTES_TRIGGER,
     RECOVERY_BAND,
+    WIRE_RECOVERY_BAND,
     CompactionSettings,
     cleared_headroom,
+    cleared_wire_headroom,
     compaction_context_tokens,
     effective_reserve_tokens,
     resolve_advisor_floor_tokens,
     resolve_strategy,
     resolve_threshold_tokens,
+    resolve_wire_bytes_budget,
+    resolve_wire_bytes_trigger,
     should_compact,
 )
 from .tokens import (
@@ -69,6 +76,7 @@ from .tokens import (
     clear_estimate_cache,
     estimate_messages_tokens,
     estimate_tokens,
+    estimate_wire_bytes,
     history_chars,
     invalidate_message_cache,
     messages_tokens_upper_bound,
@@ -87,6 +95,9 @@ __all__ = [
     "MIN_PRUNE_TOKENS",
     "PRESERVED_USER_TURN_KEY",
     "RECOVERY_BAND",
+    "WIRE_RECOVERY_BAND",
+    "DEFAULT_WIRE_BYTES_BUDGET",
+    "DEFAULT_WIRE_BYTES_TRIGGER",
     "SUMMARIZATION_SYSTEM_PROMPT",
     "SUPERSEDED_NOTICE",
     "TOOL_ARGS_MAX_CHARS",
@@ -96,11 +107,13 @@ __all__ = [
     "build_compaction_prompt",
     "clear_estimate_cache",
     "cleared_headroom",
+    "cleared_wire_headroom",
     "compaction_context_tokens",
     "compute_suffix_tokens",
     "effective_reserve_tokens",
     "estimate_messages_tokens",
     "estimate_tokens",
+    "estimate_wire_bytes",
     "extract_file_ops_from_messages",
     "extract_preserved_user_turns",
     "find_cut_point",
@@ -112,11 +125,14 @@ __all__ = [
     "parse_hint",
     "prepare_partitions",
     "prune_tool_outputs",
+    "shed_frames_to_wire_budget",
     "register_invalidator",
     "render_file_operations",
     "resolve_advisor_floor_tokens",
     "resolve_strategy",
     "resolve_threshold_tokens",
+    "resolve_wire_bytes_budget",
+    "resolve_wire_bytes_trigger",
     "serialize_conversation",
     "should_compact",
     "summarize_messages",

{local_operator-0.45.2 → local_operator-0.45.4}/local_operator/compaction/pass_.py

@@ -39,14 +39,15 @@ from .marker import (
     build_compaction_marker,
     render_compaction_marker,
 )
-from .pruning import prune_stale_frames, prune_tool_outputs
+from .pruning import prune_stale_frames, prune_tool_outputs, shed_frames_to_wire_budget
 from .thresholds import (
     CompactionSettings,
     compaction_context_tokens,
     resolve_strategy,
+    resolve_wire_bytes_budget,
     should_compact,
 )
-from .tokens import estimate_messages_tokens
+from .tokens import estimate_messages_tokens, estimate_wire_bytes
 
 logger = logging.getLogger(__name__)
 
@@ -152,11 +153,32 @@ async def run_compaction_pass(
         working, frames_dropped = prune_stale_frames(
             working, keep_recent_frames=settings.keep_recent_frames
         )
+    else:
+        # (2b) Byte shed, for the surface that did NOT opt in. A session is
+        # not statically one kind or the other — the session this guard was
+        # written for was an ordinary chat for hundreds of turns and then
+        # started driving a browser, without any config changing — so the
+        # honest discriminator is the observed byte pressure, not a static
+        # per-surface guess. Under budget this is one cheap scan that changes
+        # nothing; over budget the alternative is a request the provider
+        # refuses outright, taking every frame with it.
+        working, frames_dropped = shed_frames_to_wire_budget(
+            working, budget=resolve_wire_bytes_budget(settings)
+        )
 
-    # (3) Trigger through the single resolver.
+    # (3) Trigger through the single resolver. Bytes go in as a second input
+    # to the SAME resolver rather than as a second predicate: an image-heavy
+    # history can be far under every token threshold and still be too large to
+    # send, and two functions free to disagree about when a pass is due is the
+    # drift this package forbids.
     local_estimate = estimate_messages_tokens(working)
     tokens_before = compaction_context_tokens(provider_context_tokens, local_estimate)
-    if respect_threshold and not should_compact(tokens_before, model.context_window, settings):
+    if respect_threshold and not should_compact(
+        tokens_before,
+        model.context_window,
+        settings,
+        wire_bytes=estimate_wire_bytes(working),
+    ):
         return _refused(
             working,
             "below-threshold",

{local_operator-0.45.2 → local_operator-0.45.4}/local_operator/compaction/pruning.py

@@ -40,7 +40,7 @@ from typing import Any, Sequence
 from local_operator.harness.types import Content, ImageContent, Message, TextContent
 
 from .marker import marker_exists
-from .tokens import estimate_tokens, invalidate_message_cache
+from .tokens import estimate_tokens, estimate_wire_bytes, invalidate_message_cache
 
 __all__ = [
     "MIN_PRUNE_TOKENS",
@@ -52,6 +52,7 @@ __all__ = [
     "count_stale_observations",
     "prune_stale_frames",
     "prune_tool_outputs",
+    "shed_frames_to_wire_budget",
     "shed_stale_frames",
 ]
 
@@ -157,6 +158,62 @@ def prune_stale_frames(
     return out, dropped
 
 
+def shed_frames_to_wire_budget(
+    messages: Sequence[Message], *, budget: int
+) -> tuple[list[Message], int]:
+    """Replace the OLDEST frames with notices until the request fits ``budget``
+    bytes, keeping as many recent frames as possible.
+
+    The last-resort transport guard. Ordinary compaction decides what to keep
+    by *context* value; this decides by whether the provider will accept the
+    request at all, which is a different and strictly narrower question — so
+    it engages only when the payload is already over a ceiling set below the
+    provider's cap, and does nothing at all below it. The early return is not
+    an optimisation detail: it is the guarantee that every session under
+    budget behaves byte-identically to one without this function.
+
+    Built on :func:`prune_stale_frames` rather than as a second
+    frame-dropping primitive, so there is ONE definition of "which frames are
+    recent" and one set of copy/identity semantics. That also means no message
+    is ever removed — user/assistant alternation and tool pairings survive
+    untouched, which a transport guard running on arbitrary history must
+    guarantee, since it cannot know what is mid-tool-call.
+
+    The loop mirrors ``_shed_stale_turns`` in the evaluation runner's provider
+    client: walk the keep count DOWN and stop when a step frees nothing.
+    Termination is structural — ``keep`` strictly decreases toward 0, and
+    ``keep=0`` drops every image there is — so a payload still over budget
+    with no images left exits rather than spinning. That residual case is
+    real: a text-only history cannot be shed here, and the caller must be
+    prepared for "still over" rather than assuming success (this is what the
+    byte-side auto-continue band checks).
+
+    Sheds the FEWEST frames that fit, not a fixed count, because every frame
+    dropped is evidence the user may still need. Returns ``(messages,
+    frames_dropped)``; ``frames_dropped`` is 0 and the input list is returned
+    unchanged when nothing was over budget.
+    """
+    if budget <= 0:
+        return list(messages), 0
+    if estimate_wire_bytes(messages) <= budget:
+        return list(messages), 0
+
+    keep = count_frame_messages(messages)
+    working = list(messages)
+    dropped = 0
+    while keep > 0:
+        keep -= 1
+        candidate, candidate_dropped = prune_stale_frames(messages, keep_recent_frames=keep)
+        if candidate_dropped <= dropped:
+            # This step freed nothing new; another turn of the loop cannot
+            # either, since the keep count only shrinks.
+            break
+        working, dropped = candidate, candidate_dropped
+        if estimate_wire_bytes(working) <= budget:
+            break
+    return working, dropped
+
+
 def compute_suffix_tokens(messages: Sequence[Message]) -> list[int]:
     """Per-index sum of estimated tokens of all messages strictly AFTER it.
 

{local_operator-0.45.2 → local_operator-0.45.4}/local_operator/compaction/thresholds.py

@@ -30,9 +30,15 @@ __all__ = [
     "DEFAULT_RESERVE_TOKENS",
     "DEFAULT_THRESHOLD_PERCENT",
     "DEFAULT_THRESHOLD_TOKENS",
+    "DEFAULT_WIRE_BYTES_BUDGET",
+    "DEFAULT_WIRE_BYTES_TRIGGER",
     "CompactionSettings",
     "RECOVERY_BAND",
+    "WIRE_RECOVERY_BAND",
     "cleared_headroom",
+    "cleared_wire_headroom",
+    "resolve_wire_bytes_budget",
+    "resolve_wire_bytes_trigger",
     "compaction_context_tokens",
     "effective_reserve_tokens",
     "resolve_advisor_floor_tokens",
@@ -58,6 +64,28 @@ DEFAULT_THRESHOLD_PERCENT = 0.80
 #: when that is a small fraction of a very large window.
 DEFAULT_THRESHOLD_TOKENS = 600_000
 
+#: HARD ceiling on the serialized request, in bytes — the number the render
+#: seam sheds frames to satisfy. NOT a token figure; see
+#: :func:`~.tokens.estimate_wire_bytes` for why the two rulers stay apart.
+#:
+#: 24 MB is Anthropic's 32 MB Messages-API cap minus 25% headroom for the
+#: system prompt, the tool schemas, the ~2.2% JSON envelope, and the growth
+#: the NEXT request adds before another guard runs.
+#:
+#: Calibrated against real traffic rather than guessed: a scan of all **4,738
+#: sessions** in a production session store found exactly **one** above 24 MB
+#: (the session that wedged on HTTP 413), two above 16 MB, ten above 8 MB, and
+#: none above 32 MB. So this budget sheds nothing that works today — it fires
+#: only on the shape that was already failing outright.
+DEFAULT_WIRE_BYTES_BUDGET = 24_000_000
+
+#: SOFT trigger: fires a real compaction pass (with a summary) well before the
+#: hard budget forces amputation. ~2/3 of the hard budget, which on the
+#: measured store is above every session but the three largest — the point is
+#: that a screenshot-heavy session compacts *properly and early* instead of
+#: surviving by shedding frames at the wall.
+DEFAULT_WIRE_BYTES_TRIGGER = 16_000_000
+
 
 class CompactionSettings(BaseModel):
     """Compaction knobs, mirrored from ``config.yml`` ``values.compaction.*``.
@@ -123,6 +151,16 @@ class CompactionSettings(BaseModel):
     # at $262. So the knob is opt-in per surface, and ``None`` means the frame
     # prune is not even consulted — ``run_compaction_pass`` with the defaults
     # is byte-identical to a pass without it, which a test pins.
+    #
+    # EXTENDED, not reversed: ``None`` now means "never prune frames for
+    # size-of-CONTEXT reasons", and a byte shed engages underneath it when the
+    # request would otherwise be REFUSED outright (``wire_bytes_budget``). The
+    # argument above assumes pruning frames costs the user content for no
+    # forced reason, which is exactly right up to the wall; at the wall the
+    # alternative is not "keep every frame", it is losing the whole session —
+    # a session that 413s loses all 42 frames, while the shed keeps 28. The
+    # default and the distinct-attachments reasoning are both untouched, and a
+    # session under budget still performs no work here at all.
     keep_recent_frames: int | None = Field(
         default=None,
         description=(
@@ -133,6 +171,36 @@ class CompactionSettings(BaseModel):
         ),
     )
 
+    # --- Transport size budget (BYTES, not tokens) --------------------------
+    #
+    # These two are the only knobs in this model measured in bytes, and the
+    # separation is deliberate: the token thresholds above answer "how much of
+    # the context WINDOW is occupied", these answer "will the HTTP request be
+    # accepted". A screenshot-heavy session can sit at 15% of a 1M window and
+    # still be over a provider's request cap, because a flat per-image token
+    # charge (correct for billing) is blind to base64 length. Never compare a
+    # value here against a token figure.
+    #
+    # Registered in ``settings_io.SETTINGS`` so an operator on a provider with
+    # a different cap can move them without editing code.
+    wire_bytes_budget: int = Field(
+        default=DEFAULT_WIRE_BYTES_BUDGET,
+        description=(
+            "Hard ceiling on the serialized request in BYTES. Older screenshots"
+            " are shed from the rendered history (never from the transcript) to"
+            " stay under it. Non-positive disables the shed."
+        ),
+    )
+    wire_bytes_trigger: int = Field(
+        default=DEFAULT_WIRE_BYTES_TRIGGER,
+        description=(
+            "Soft trigger in BYTES: a compaction pass fires once the serialized"
+            " request passes this, so a screenshot-heavy session summarises"
+            " early instead of shedding frames at the hard budget."
+            " Non-positive disables the byte trigger."
+        ),
+    )
+
     # --- Speculative compaction advisor (BETA, off by default) -------------
     #
     # Every field below is optional with an inert default, so a config written
@@ -386,6 +454,7 @@ def should_compact(
     settings: CompactionSettings,
     *,
     advisory_ok: bool = False,
+    wire_bytes: int = 0,
 ) -> bool:
     """Whether the current context exceeds the compaction threshold.
 
@@ -411,15 +480,79 @@ def should_compact(
     the disabled/off short-circuit — is untouched, so a future reader citing
     this as precedent should carry those constraints too.
 
-    With ``advisory_ok`` false (its default, and what every caller but the
-    plan gate passes) the function is byte-identical to its previous form.
+    ``wire_bytes`` is the second input with that posture, and it is here for
+    the same reason ``advisory_ok`` is: it is a different QUESTION about the
+    same decision ("will the request be accepted?" beside "does the context
+    fit the window?"), and a separate ``should_compact_for_size()`` beside
+    this one would be exactly the trigger drift the module docstring forbids.
+    So it is OR-ed into the one resolved answer, where it can only pull the
+    trigger EARLIER.
+
+    The byte term is what makes an image-heavy session compact at all. Its
+    token estimate is honest and small — 42 screenshots read as 154,690
+    tokens, 15.5% of a 1M window — while the serialized request is 34 MB,
+    past the provider's cap. No token threshold can see that, because the
+    per-image token charge is flat by design (see
+    :func:`~.tokens.estimate_wire_bytes`).
+
+    Monotonicity is preserved in BOTH numeric arguments, which the session's
+    cheap upper-bound pre-gate depends on: raising either can only turn a
+    ``False`` into a ``True``. Bytes are exact and cheap, so the pre-gate can
+    pass the real figure rather than a bound.
+
+    With ``advisory_ok`` false and ``wire_bytes`` 0 (their defaults, and what
+    every caller but the plan gate passes) the function is byte-identical to
+    its previous form.
     """
     if not settings.enabled or settings.strategy == "off" or window_tokens <= 0:
         return False
     threshold = resolve_threshold_tokens(window_tokens, settings)
     if advisory_ok and getattr(settings, "advisor_enabled", False):
         threshold = min(threshold, resolve_advisor_floor_tokens(window_tokens, settings))
-    return context_tokens > threshold
+    if context_tokens > threshold:
+        return True
+    byte_trigger = resolve_wire_bytes_trigger(settings)
+    return byte_trigger > 0 and wire_bytes > byte_trigger
+
+
+def resolve_wire_bytes_budget(settings: CompactionSettings) -> int:
+    """THE hard byte ceiling, resolved in one place.
+
+    Same discipline as :func:`resolve_threshold_tokens`: one resolver, no
+    caller re-deriving the number from the settings model. A non-positive
+    value means "no byte ceiling" and is returned as ``0`` so every caller can
+    test it the same way; a garbage value falls back to the default rather
+    than disabling the guard silently, because a typo here is the difference
+    between a session that recovers and one that 413s forever.
+    """
+    raw = getattr(settings, "wire_bytes_budget", DEFAULT_WIRE_BYTES_BUDGET)
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        logger.warning("compaction.wire_bytes_budget is not an integer; using the default")
+        return DEFAULT_WIRE_BYTES_BUDGET
+    return value if value > 0 else 0
+
+
+def resolve_wire_bytes_trigger(settings: CompactionSettings) -> int:
+    """THE soft byte trigger, resolved in one place.
+
+    Clamped to the hard budget: a trigger ABOVE the ceiling would mean the
+    render seam amputates frames before a proper compaction pass ever fires,
+    which inverts the whole design — the soft trigger exists so the session
+    summarises with a model call instead of surviving by amputation. Returns
+    ``0`` when the byte trigger is disabled.
+    """
+    raw = getattr(settings, "wire_bytes_trigger", DEFAULT_WIRE_BYTES_TRIGGER)
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        logger.warning("compaction.wire_bytes_trigger is not an integer; using the default")
+        value = DEFAULT_WIRE_BYTES_TRIGGER
+    if value <= 0:
+        return 0
+    budget = resolve_wire_bytes_budget(settings)
+    return min(value, budget) if budget > 0 else value
 
 
 def compaction_context_tokens(provider_reported: int | None, local_estimate: int) -> int:
@@ -452,6 +585,40 @@ def cleared_headroom(residual_tokens: int, threshold_tokens: int) -> int:
     return threshold_tokens - residual_tokens
 
 
+#: The byte-side twin of :data:`RECOVERY_BAND`, and it exists because that
+#: constant CANNOT cover the byte trigger. ``RECOVERY_BAND`` is defined on
+#: tokens against the token threshold; a pass fired by byte pressure can leave
+#: the token residual comfortably inside the token band while the request is
+#: still over the byte budget — the token side would then say "headroom
+#: created", schedule an auto-continue, and the next turn would fire the byte
+#: trigger again on a context nothing had shrunk. That is precisely the live
+#: dead-loop ``RECOVERY_BAND`` was added for, arrived at through the new
+#: trigger, so the guard has to be restated in the new trigger's own units.
+#:
+#: Same 0.8 ratio, same meaning: a pass counts as having created byte headroom
+#: only when the residual request lands at or below ``0.8 x`` the soft byte
+#: trigger.
+WIRE_RECOVERY_BAND = 0.8
+
+
+def cleared_wire_headroom(residual_bytes: int, settings: CompactionSettings) -> bool:
+    """Whether a pass created real BYTE headroom, for the auto-continue gate.
+
+    Returns ``True`` when the byte trigger is disabled, so a session that
+    never opted into byte pressure keeps exactly the token-only behaviour it
+    has today — this must not become a second veto on ordinary text sessions.
+
+    Otherwise the residual must sit at or below
+    ``WIRE_RECOVERY_BAND * trigger``. A pass that shaved a screenshot or two
+    and is still near the trigger has NOT recovered, and scheduling a
+    continuation on it re-enters the same pass next turn.
+    """
+    trigger = resolve_wire_bytes_trigger(settings)
+    if trigger <= 0:
+        return True
+    return residual_bytes <= WIRE_RECOVERY_BAND * trigger
+
+
 def resolve_strategy(
     settings: CompactionSettings, model: Any
 ) -> Literal["context-full", "snapcompact"]: