power-loop 6.2.0__tar.gz → 6.3.0__tar.gz

{power_loop-6.2.0 → power_loop-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 6.2.0
+Version: 6.3.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT

{power_loop-6.2.0 → power_loop-6.3.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "6.2.0"
+__version__ = "6.3.0"
 
 # Public LLM contract (SDK-free) re-exported so callers (e.g. writing llm.* hooks or
 # a custom LLMService) don't reach into the internal vendored transport package (H3.4).

{power_loop-6.2.0 → power_loop-6.3.0}/power_loop/core/pipeline.py

@@ -1044,12 +1044,18 @@ class AgentPipeline:
                 await self._append_message(_pm, round_index=round_idx)
                 llm_before.messages.append(dict(_pm))
 
-            # EPHEMERAL image recall: a tool (e.g. recall_send hitting an image row) can put a
-            # picture back in front of the model for exactly ONE round. Appended to the request
-            # only — never persisted, so it does not enter history or the projection. Durable
-            # would mean an agent that recalled three times carries three images forever, which
-            # is the unbounded growth the projection exists to prevent.
-            for _img in drain_queued_images(self.session_id):
+            # Image recall: a tool (see_image / recall_send / an image generator) can put
+            # pictures in front of the model. DURABLE ones become real `user` rows — the image
+            # stays in view for the rest of the send (cheap: it sits in the provider's cached
+            # prefix) and is distilled to `[image: … · file_uuid=…]` across sends, so nothing
+            # accumulates without bound. EPHEMERAL ones go into this request only.
+            # Appended AFTER the hook's own persist_messages so a tool's picture lands below
+            # the tool result that announced it — which is exactly where the model expects it.
+            _durable_imgs, _ephemeral_imgs = drain_queued_images(self.session_id)
+            for _img in _durable_imgs:
+                await self._append_message(_img, round_index=round_idx)
+                llm_before.messages.append(dict(_img))
+            for _img in _ephemeral_imgs:
                 llm_before.messages.append(_img)
 
             if llm_before.directive == HookDirective.SHORT_CIRCUIT:

{power_loop-6.2.0 → power_loop-6.3.0}/power_loop/runtime/image_recall.py

@@ -13,10 +13,16 @@ on which vendor the definition happens to point at, and definitions switch model
 So the image travels as its own **user** message instead, and the tool returns only a line
 saying it is there.
 
-Why EPHEMERAL: the queued message is appended to the round's request, never to the store. A
-durable injection would write the image into history and the projection, so an agent that
-recalled three times would carry three images forever — exactly the unbounded growth the
-projection exists to prevent. One round, then gone; recall again if you need another look.
+DURABLE by default, and that default was reversed on purpose. The first cut was ephemeral —
+request-only, gone next round — out of a fear that "recall three times and you carry three
+images forever". Measurement killed that fear: the provider's prefix cache serves a stable
+history at ~99% hit rate, so an image sitting in the prefix costs about a tenth of its face
+value every later round. Meanwhile the SEMANTICS clearly favour durable: an agent that looked
+at a UI screenshot and then spends fifteen rounds coding against it should still have the
+picture in front of it, not have to ask for it again. Across sends the projection distils the
+row down to `[image: shot.png · file_uuid=…]`, so nothing accumulates without bound.
+
+Pass ``durable=False`` for the look-once case (request-only, never stored).
 """
 
 from __future__ import annotations
@@ -38,9 +44,14 @@ MAX_PENDING_PER_SESSION = 8
 
 
 def queue_image_for_next_round(
-    session_id: str | None, *, path: str, note: str = "", ref: str = ""
+    session_id: str | None, *, path: str, note: str = "", ref: str = "",
+    durable: bool = True,
 ) -> bool:
-    """Queue one image (by local path) to be shown to the model on the next round.
+    """Queue one image (by local path) to be shown to the model from the next round on.
+
+    ``durable=True`` (default) stores it as a real ``user`` row, so it stays in front of the
+    model for the rest of the send and is distilled to a text reference across sends.
+    ``durable=False`` puts it in the request only — visible for exactly one round.
 
     Returns False when there is no session to queue against, or the queue is full — the caller
     should then say so in its own return value rather than pretend the image was delivered.
@@ -62,16 +73,27 @@ def queue_image_for_next_round(
         queue = _pending.setdefault(session_id, [])
         if len(queue) >= MAX_PENDING_PER_SESSION:
             return False
-        queue.append({"role": "user", "content": blocks})
+        queue.append({"role": "user", "content": blocks, "__durable__": durable})
     return True
 
 
-def drain_queued_images(session_id: str | None) -> list[LoopMessage]:
-    """Take everything queued for this session (and clear it)."""
+def drain_queued_images(session_id: str | None) -> tuple[list[LoopMessage], list[LoopMessage]]:
+    """Take everything queued for this session (and clear it).
+
+    Returns ``(durable, ephemeral)`` — the caller persists the first group and appends the
+    second to this round's request only. The marker key is stripped so neither ever reaches
+    a provider payload.
+    """
     if not session_id:
-        return []
+        return [], []
     with _lock:
-        return _pending.pop(session_id, [])
+        queued = _pending.pop(session_id, [])
+    durable: list[LoopMessage] = []
+    ephemeral: list[LoopMessage] = []
+    for item in queued:
+        keep = bool(item.pop("__durable__", True))
+        (durable if keep else ephemeral).append(item)
+    return durable, ephemeral
 
 
 def discard_queued_images(session_id: str | None) -> None:

{power_loop-6.2.0 → power_loop-6.3.0}/power_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 6.2.0
+Version: 6.3.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT