power-loop 7.1.0__tar.gz → 7.3.0__tar.gz

{power_loop-7.1.0 → power_loop-7.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 7.1.0
+Version: 7.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-7.1.0 → power_loop-7.3.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "7.1.0"
+__version__ = "7.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).
@@ -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, 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,8 @@ STABLE_API = (
 )
 
 __all__ = [
+    "PASS_TURN_TOOL",
+    "request_pass",
     "ToolContextPolicy",
     "ToolContextConfig",
 	"__version__",

{power_loop-7.1.0 → power_loop-7.3.0}/power_loop/_vendor/llm_client/interface.py

@@ -204,6 +204,10 @@ class LLMTokenUsage:
     accepted_tokens: int | None = None
     rejected_tokens: int | None = None
 
+    #: Charge the provider itself reported for this call (e.g. OpenRouter's ``usage.cost``), in the
+    #: provider's billing currency. ``None`` = not reported; hosts then price tokens themselves.
+    cost: float | None = None
+
     def as_dict(self) -> dict[str, int | None]:
         return dict(self.__dict__)
 

{power_loop-7.1.0 → power_loop-7.3.0}/power_loop/_vendor/llm_client/llm_factory.py

@@ -419,6 +419,14 @@ class OpenAICompatibleChatLLMService(LLMService):
         return raw
 
     def _usage_obj(self, usage: Any = None) -> LLMTokenUsage:
+        def _cost_or_none(v: Any) -> float | None:
+            if isinstance(v, bool) or not isinstance(v, (int, float, str)):
+                return None
+            try:
+                return float(v)
+            except ValueError:
+                return None
+
         d = self._last_usage if usage is None else self._usage_dict_from_any(usage)
 
         def _int_or_none(v: Any) -> int | None:
@@ -448,6 +456,7 @@ class OpenAICompatibleChatLLMService(LLMService):
             reasoning_tokens=_int_or_none(d.get("reasoning_tokens")),
             accepted_tokens=_int_or_none(d.get("accepted_tokens")),
             rejected_tokens=_int_or_none(d.get("rejected_tokens")),
+            cost=_cost_or_none(d.get("cost")),
         )
 
     async def _with_retries(self, fn, *, method: str) -> Any:

{power_loop-7.1.0 → power_loop-7.3.0}/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.1.0 → power_loop-7.3.0}/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.1.0 → power_loop-7.3.0}/power_loop/contracts/event_payloads.py

@@ -80,6 +80,13 @@ class LlmCallCompletedPayload(BaseEventPayload):
     #: ``ok`` · ``error`` · ``timeout`` · ``aborted`` (the attempt's task was cancelled: a retry
     #: deadline, steering, a stop).
     outcome: str = "ok"
+    #: 7.2: which endpoint served the call (the transport's base URL) — hosts price per connection,
+    #: and one model name can be served by several providers at different prices.
+    endpoint: str = ""
+    #: 7.2: charge the provider reported for this call (``LLMTokenUsage.cost``), ``None`` if not reported.
+    provider_cost: float | None = None
+    #: 7.2: image input tokens, when the provider splits them out (``None`` = not reported).
+    prompt_image_tokens: int | None = None
 
 
 @dataclass

power_loop-7.3.0/power_loop/core/pass_turn.py

@@ -0,0 +1,82 @@
+"""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})
+
+
+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 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.1.0 → power_loop-7.3.0}/power_loop/core/pipeline.py

@@ -202,6 +202,19 @@ def _maybe_compact_accepts_context(func: Any) -> bool:
 
 # ── Utility functions (unchanged from old agent.py) ──
 
+def _llm_endpoint(llm: Any) -> str:
+    """The base URL that serves this LLM (unwrapping retry / proxy wrappers), or ""."""
+    for _ in range(5):
+        if llm is None:
+            break
+        cfg = getattr(llm, "_cfg", None) or getattr(llm, "config", None)
+        url = getattr(cfg, "base_url", None)
+        if url:
+            return str(url)
+        llm = getattr(llm, "inner", None) or getattr(llm, "_inner", None) or getattr(llm, "llm", None)
+    return ""
+
+
 def _truncate_result(output: Any, limit: int | None = RESULT_MAX_CHARS) -> str:
     """Cap a tool result before it enters history and the audit log (None = no cap). Keeps the
     head and the tail: errors and summaries are usually at the end."""
@@ -340,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
@@ -832,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,
@@ -841,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(
@@ -1333,6 +1358,7 @@ class AgentPipeline:
                             success=False, error_type=type(exc).__name__,
                             prompt_tokens=p_est, completion_tokens=c_est,
                             total_tokens=p_est + c_est, estimated=True, outcome=outcome,
+                            endpoint=_llm_endpoint(self.llm),
                         ),
                         round_index=round_index, stream_id="main",
                     )
@@ -1364,6 +1390,9 @@ class AgentPipeline:
                         prompt_cached_tokens=getattr(usage, "prompt_cached_tokens", None),
                         prompt_cache_miss_tokens=getattr(usage, "prompt_cache_miss_tokens", None),
                         estimated=estimated,
+                        endpoint=_llm_endpoint(self.llm),
+                        provider_cost=getattr(usage, "cost", None),
+                        prompt_image_tokens=getattr(usage, "prompt_image_tokens", None),
                     ),
                     round_index=round_index, stream_id="main",
                 )
@@ -1499,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
@@ -1646,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,
@@ -1854,6 +1902,11 @@ 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 [])]})
+
             # 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.1.0 → power_loop-7.3.0}/power_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 7.1.0
+Version: 7.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-7.1.0 → power_loop-7.3.0}/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