power-loop 7.2.0__tar.gz → 7.3.1__tar.gz

{power_loop-7.2.0 → power_loop-7.3.1}/PKG-INFO

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

{power_loop-7.2.0 → power_loop-7.3.1}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "7.2.0"
+__version__ = "7.3.1"
 
 # 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).
@@ -140,6 +140,7 @@ from power_loop.contracts.tools import ToolDefinition, validate_tool_args
 from power_loop.core.agent_context import get_effective_tools
 from power_loop.core.events import AgentEventBus
 from power_loop.core.hooks import AgentHooks
+from power_loop.core.pass_turn import PASS_TURN_TOOL, pass_progress, request_pass
 from power_loop.core.phase import PhaseContext, PhaseResult, phase
 from power_loop.core.pipeline import AgentPipeline
 from power_loop.core.runner import AgentRunner
@@ -303,6 +304,9 @@ STABLE_API = (
 )
 
 __all__ = [
+    "PASS_TURN_TOOL",
+    "request_pass",
+    "pass_progress",
     "ToolContextPolicy",
     "ToolContextConfig",
 	"__version__",

{power_loop-7.2.0 → power_loop-7.3.1}/power_loop/agent/stateful_loop.py

@@ -64,6 +64,7 @@ from power_loop.core.agent_context import (
 )
 from power_loop.core.events import AgentEventBus
 from power_loop.core.hooks import AgentHooks
+from power_loop.core.pass_turn import ensure_pass_turn
 from power_loop.core.pipeline import (
     AgentPipeline,
     _tool_call_args,
@@ -132,6 +133,12 @@ class StatefulResult:
     usage: dict[str, int] = field(default_factory=dict)
     #: Tool invocations executed during this send.
     tool_calls: int = 0
+    #: design/188：调 pass_turn 明确结束的、理由；停的那一刻有没有刚折进来的新输入。
+    passed: bool = False
+    pass_reason: str | None = None
+    new_input_after_pass: bool = False
+    #: 每一步写的文字：[{step, text, tools}]，按顺序（不只是最后一段）。
+    texts: list[dict[str, Any]] = field(default_factory=list)
 
 
 class _SyncLoopRunner:
@@ -1415,7 +1422,8 @@ class StatefulAgentLoop:
             base,
             inject_tool_descriptions=self.config.inject_tool_descriptions,
             tool_catalog_header=self.config.tool_catalog_header,
-            tool_registry=self.tool_registry,
+            # pipeline 会补上永远在的 pass_turn（design/188）：预览也补，才和模型看到的一样
+            tool_registry=ensure_pass_turn(self.tool_registry) if self.tool_registry is not None else None,
             skills_dir=self.config.skills_dir,
         )
 
@@ -2232,6 +2240,10 @@ class StatefulAgentLoop:
             pending_interactions=result.pending_interactions,
             usage=result.usage,
             tool_calls=result.tool_calls,
+            passed=result.passed,
+            pass_reason=result.pass_reason,
+            new_input_after_pass=result.new_input_after_pass,
+            texts=result.texts,
         )
 
     async def _migrate_prior_history_to_projection(

{power_loop-7.2.0 → power_loop-7.3.1}/power_loop/agent/types.py

@@ -464,3 +464,9 @@ class AgentLoopResult:
     usage: dict[str, int] = field(default_factory=dict)
     #: Tool invocations executed during this run.
     tool_calls: int = 0
+    #: design/188：这一轮是不是调 pass_turn 明确结束的、理由；停的那一刻是否有刚折进来的新输入。
+    passed: bool = False
+    pass_reason: str | None = None
+    new_input_after_pass: bool = False
+    #: 每一步写的文字（不只是最后一段）：[{step, text, tools}]，按顺序。
+    texts: list[dict[str, Any]] = field(default_factory=list)

power_loop-7.3.1/power_loop/core/pass_turn.py

@@ -0,0 +1,101 @@
+"""pass_turn —— 内置的「这一步做完了，结束这一轮」(design/188)。
+
+一个 send 有两种正常的结束：这一轮只写字、不调工具（自然结束）；或者调 ``pass_turn``（明确结束）。
+不强制以 pass_turn 结尾。
+
+- 工具**永远在**：pipeline 建立时 ``ensure_pass_turn`` 把它补进工具表（宿主去不掉）。
+- 宿主可以用同名工具覆盖说明和处理（例如先核对再决定停不停）；处理里调 ``request_pass(理由)`` 才算数。
+- 硬停：标记之后，pipeline 在**下一轮开始前**停（不再调模型），结果上 ``passed=True``、``pass_reason``；
+  停的时候若有刚折进来的新输入（转向消息），记 ``new_input_after_pass``，由宿主决定要不要另起一轮。
+- 状态按 send 隔离（ContextVar，每个 pipeline.run 开始时装一份、结束时还原）：子 agent 在同一个任务里
+  内联跑，它的 pass 不会翻父 send 的标记。
+"""
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Any
+
+from power_loop.contracts.tools import ToolDefinition
+
+NAME = "pass_turn"
+REASON_MAX = 300
+
+DESCRIPTION = (
+    "这一步的事做完了，结束这一轮（不再继续调用模型）。"
+    "什么时候用：要做的已经做完、结果已经交出去（写出来了或用工具交了），没有别的要做；"
+    "或者在等后台的结果（它好了会叫醒你）。"
+    "只写字、不调工具也会结束这一轮——用它是明确地说「做完了」。reason 写一句为什么结束。"
+)
+
+PASS_TURN_TOOL = ToolDefinition(
+    name=NAME,
+    description=DESCRIPTION,
+    input_schema={
+        "type": "object",
+        "properties": {"reason": {"type": "string", "description": "一句话：为什么结束这一轮（记日志，不展示）。"}},
+        "required": ["reason"],
+    },
+    required_params=("reason",),
+)
+
+_state: ContextVar[dict[str, Any] | None] = ContextVar("power_loop_pass_turn", default=None)
+
+
+def begin() -> Token:
+    """一个 send 开始：装一份新的状态。返回还原用的 token。"""
+    return _state.set({"passed": False, "reason": None, "new_input_after_pass": False, "texts": 0, "work_tools": 0})
+
+
+def end(token: Token) -> None:
+    _state.reset(token)
+
+
+def current() -> dict[str, Any] | None:
+    return _state.get()
+
+
+def request_pass(reason: str = "") -> bool:
+    """标记「这一轮结束」：下一轮开始前停。不在 send 里（没有状态）返回 False。"""
+    st = _state.get()
+    if st is None:
+        return False
+    st["passed"] = True
+    st["reason"] = (reason or "").strip()[:REASON_MAX]
+    return True
+
+
+def note_step(wrote_text: bool, tool_names: list[str]) -> None:
+    """pipeline 每一轮调一次：记下这次 send 写过几段字、调过几次别的工具（pass_turn 不算）。"""
+    st = _state.get()
+    if st is None:
+        return
+    if wrote_text:
+        st["texts"] = st.get("texts", 0) + 1
+    st["work_tools"] = st.get("work_tools", 0) + sum(1 for n in tool_names if n != PASS_TURN_TOOL.name)
+
+
+def pass_progress() -> dict[str, int] | None:
+    """这次 send 到现在：写过几段字（texts）、调过几次别的工具（work_tools）。宿主覆盖 pass_turn 时用来判断
+    「还什么都没交就要结束」。不在 send 里返回 None。"""
+    st = _state.get()
+    if st is None:
+        return None
+    return {"texts": int(st.get("texts", 0)), "work_tools": int(st.get("work_tools", 0))}
+
+
+def pass_requested() -> bool:
+    st = _state.get()
+    return bool(st and st.get("passed"))
+
+
+def default_handler(reason: str = "") -> str:
+    if not request_pass(reason):
+        return "pass_turn 记下了（当前没有在跑的一轮）。"
+    return "这一轮结束了。不用再写别的。"
+
+
+def ensure_pass_turn(registry: Any) -> Any:
+    """工具表里没有 pass_turn 就补上（永远在）。"""
+    if not registry.has(NAME):
+        registry.register(PASS_TURN_TOOL, default_handler)
+    return registry

{power_loop-7.2.0 → power_loop-7.3.1}/power_loop/core/pipeline.py

@@ -353,7 +353,10 @@ class AgentPipeline:
     ) -> None:
         self.llm = llm
         self.config = config
-        self.tool_registry = tool_registry
+        # design/188：pass_turn 永远在（宿主可以用同名工具覆盖说明和处理）。
+        # 没有工具表 = 工具全由宿主执行（调用原样交回，pending_tools）：那种模式不补，宿主自己处理
+        from power_loop.core.pass_turn import ensure_pass_turn
+        self.tool_registry = ensure_pass_turn(tool_registry) if tool_registry is not None else None
         self.hooks = hooks
         self.bus = bus
         self.ctx = ctx
@@ -845,6 +848,11 @@ class AgentPipeline:
                      pending_interactions: list | None = None) -> AgentLoopResult:
         self._completed_rounds = rounds  # for MemorySnapshot
         self._log_send_summary(status, rounds)
+        st = getattr(self, "_pass_state", None) or {}
+        texts = list(getattr(self, "_step_texts", []) or [])
+        # 明确结束（pass_turn）时最后一轮往往没有文字：答案取最后一段写过的文字
+        if st.get("passed") and not final_text and texts:
+            final_text = texts[-1]["text"]
         return AgentLoopResult(
             status=status,  # type: ignore[arg-type]
             final_text=final_text,
@@ -854,6 +862,10 @@ class AgentPipeline:
             messages=self.history,
             usage=dict(self.ctx.usage_totals),
             tool_calls=int(self.ctx.tool_calls),
+            passed=bool(st.get("passed")),
+            pass_reason=st.get("reason"),
+            new_input_after_pass=bool(st.get("new_input_after_pass")),
+            texts=texts,
         )
 
     async def _persist_pending_interaction(
@@ -1516,6 +1528,17 @@ class AgentPipeline:
 
     async def run(self, messages: list[LoopMessage]) -> AgentLoopResult:
         """Run the full agent loop. Returns when done, cancelled, or hit round limit."""
+        from power_loop.core import pass_turn as _pass
+
+        token = _pass.begin()          # pass_turn 的状态按 send 隔离（子 agent 内联跑也不串）
+        self._pass_state = _pass.current()
+        self._step_texts: list[dict[str, Any]] = []
+        try:
+            return await self._run(messages)
+        finally:
+            _pass.end(token)
+
+    async def _run(self, messages: list[LoopMessage]) -> AgentLoopResult:
         self.history = [dict(m) for m in messages]
         self._image_rounds = {}   # 6.12.0：本 send 新入的图片行 id(row) → round_index
         self._tok_len = -1  # SCALE-4: wholesale (re)assignment invalidates the estimate
@@ -1663,6 +1686,14 @@ class AgentPipeline:
                 for msg in drained:
                     await self._append_message(msg, round_index=round_idx)
 
+            # ── pass_turn：上一轮调了 → 这一轮开始前硬停（design/188，不再调模型）──
+            if self._pass_state and self._pass_state.get("passed"):
+                if drained_count:
+                    # 停的这一刻有刚折进来的新输入：不撤销停，留痕交给宿主（另起一轮处理）
+                    self._pass_state["new_input_after_pass"] = True
+                await self._finalize("pass_turn")
+                return self._make_result("completed", rounds=round_idx)
+
             # ── Hook: ROUND_START ──
             round_ctx = RoundStartCtx(
                 round_index=round_idx, messages=self.history,
@@ -1871,6 +1902,13 @@ class AgentPipeline:
             tool_calls = response.get_tool_calls()
             self._emit(AgentEventType.ROUND_TOOLS_PRESENT, RoundToolsPresentPayload(has_tools=bool(tool_calls)), round_index=round_idx)
 
+            # 每一步的文字（design/188）：模型每一轮都可能写字，全部留着交给宿主（不只是最后一段）
+            if assistant_text:
+                self._step_texts.append({"step": round_idx + 1, "text": assistant_text,
+                                         "tools": [_tool_call_name(tc) for tc in (tool_calls or [])]})
+            from power_loop.core import pass_turn as _pass_state
+            _pass_state.note_step(bool(assistant_text), [_tool_call_name(tc) for tc in (tool_calls or [])])
+
             # Any productive round (said something OR called a tool) clears the empty streak.
             if assistant_text or tool_calls:
                 self._empty_response_streak = 0

{power_loop-7.2.0 → power_loop-7.3.1}/power_loop.egg-info/PKG-INFO

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

{power_loop-7.2.0 → power_loop-7.3.1}/power_loop.egg-info/SOURCES.txt

@@ -46,6 +46,7 @@ power_loop/contrib/otel_sink.py
 power_loop/core/agent_context.py
 power_loop/core/events.py
 power_loop/core/hooks.py
+power_loop/core/pass_turn.py
 power_loop/core/phase.py
 power_loop/core/pipeline.py
 power_loop/core/runner.py