power-loop 9.0.0__tar.gz → 9.1.0__tar.gz

{power_loop-9.0.0 → power_loop-9.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 9.0.0
+Version: 9.1.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -418,3 +418,19 @@ After the exact charge is locally durable, API delivery failure leaves a pending
 budget submission and preserves the real tool result. Reconciliation never calls
 the handler again or reads a replacement price. Managed recovery sources without
 an ordinary callback checkpoint still need a separate adapter.
+
+
+### Host lifecycle extensions
+
+Hosts can raise `power_loop.core.control.ControlledLoopStop(reason, message=...)`
+from session-entry or round-start hooks. The pipeline records a controlled stop,
+keeps completed work, and skips memory summarization on that exit. Hosts own
+quota policy and settlement; the SDK has no application currency or user model.
+
+`power_loop.runtime.invocation.register_invocation_scope(name, factory, exporter=...)`
+installs a synchronous context manager around each actual tool invocation. The
+factory receives `session_id`, `assistant_seq`, `tool_call_id`, and `tool_name`.
+An optional exporter returns a small JSON snapshot which is saved as
+`host_contexts[name]` on original job creation. Replay retains the original saved
+snapshot; hosts restore it when recovering a child job. Business snapshots do not
+carry execution authority and do not replace the SDK's signed task request.

{power_loop-9.0.0 → power_loop-9.1.0}/README.md

@@ -340,3 +340,19 @@ After the exact charge is locally durable, API delivery failure leaves a pending
 budget submission and preserves the real tool result. Reconciliation never calls
 the handler again or reads a replacement price. Managed recovery sources without
 an ordinary callback checkpoint still need a separate adapter.
+
+
+### Host lifecycle extensions
+
+Hosts can raise `power_loop.core.control.ControlledLoopStop(reason, message=...)`
+from session-entry or round-start hooks. The pipeline records a controlled stop,
+keeps completed work, and skips memory summarization on that exit. Hosts own
+quota policy and settlement; the SDK has no application currency or user model.
+
+`power_loop.runtime.invocation.register_invocation_scope(name, factory, exporter=...)`
+installs a synchronous context manager around each actual tool invocation. The
+factory receives `session_id`, `assistant_seq`, `tool_call_id`, and `tool_name`.
+An optional exporter returns a small JSON snapshot which is saved as
+`host_contexts[name]` on original job creation. Replay retains the original saved
+snapshot; hosts restore it when recovering a child job. Business snapshots do not
+carry execution authority and do not replace the SDK's signed task request.

{power_loop-9.0.0 → power_loop-9.1.0}/power_loop/__init__.py

@@ -15,7 +15,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "9.0.0"
+__version__ = "9.1.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-9.0.0 → power_loop-9.1.0}/power_loop/agent/stateful_loop.py

@@ -1737,7 +1737,7 @@ class StatefulAgentLoop:
             else:
                 try:
                     from power_loop.runtime.invocation import invocation_context
-                    with invocation_context(sid, pending.get("assistant_seq"), cid):
+                    with invocation_context(sid, pending.get("assistant_seq"), cid, name):
                         raw = await self.tool_registry.invoke_async(name, args)
                     if not isinstance(raw, str):
                         raw = json.dumps(raw, ensure_ascii=False)

power_loop-9.1.0/power_loop/core/control.py

@@ -0,0 +1,14 @@
+"""Host-controlled stops at lifecycle boundaries, separate from business errors."""
+
+
+class ControlledLoopStop(Exception):
+    """A host hook requests a terminal result without another model request."""
+
+    def __init__(self, reason: str, *, message: str = "", status: str = "budget_exceeded"):
+        if not reason or status not in ("budget_exceeded", "cancelled", "degraded"):
+            raise ValueError("invalid controlled loop stop")
+        self.reason = reason
+        self.message = message
+        self.status = status
+        super().__init__(reason)
+

{power_loop-9.0.0 → power_loop-9.1.0}/power_loop/core/pipeline.py

@@ -768,7 +768,7 @@ class AgentPipeline:
     # ── Helper: finalize session ──
 
     async def _finalize(self, reason: str, *, final_text: str | None = None,
-                        rounds: int | None = None) -> None:
+                        rounds: int | None = None, remember: bool = True) -> None:
         if self._finalized:
             return  # idempotent: SESSION_ENDED fires exactly once per run
         self._finalized = True
@@ -780,7 +780,8 @@ class AgentPipeline:
         )
         await self.hooks.run_typed_async(HookPoint.SESSION_END, ctx)
         self._emit(AgentEventType.SESSION_ENDED, SessionEndedPayload(reason=reason))
-        await self._maybe_remember(reason=reason, final_text=final_text or "")
+        if remember:
+            await self._maybe_remember(reason=reason, final_text=final_text or "")
 
     async def _emit_error_terminal(self, exc: BaseException) -> None:
         """Emit the ``AGENT_ERROR`` channel + a terminal ``SESSION_ENDED`` after an
@@ -1605,7 +1606,7 @@ class AgentPipeline:
                 from power_loop.runtime.invocation import invocation_context
                 with invocation_context(self.session_id,
                         assistant_seq if assistant_seq is not None else getattr(self.sink, "persisted_assistant_seq", None),
-                        tool_call_id):
+                        tool_call_id, tool_name):
                     from power_loop.runtime.task_runtime import check_tool_dispatch
                     registered = await check_tool_dispatch(self.session_id, tool_name, self.tool_registry, tool_args)
                     from power_loop.runtime.tool_contracts import validate_registration
@@ -1668,12 +1669,18 @@ 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
+        from power_loop.core.control import ControlledLoopStop
 
         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)
+        except ControlledLoopStop as stop:
+            await self._finalize(stop.reason, final_text=stop.message,
+                                 rounds=self._completed_rounds, remember=False)
+            return self._make_result(stop.status, final_text=stop.message,
+                                     rounds=self._completed_rounds)
         finally:
             try:
                 from power_loop.runtime.task_runtime import preserve_model_usage

power_loop-9.1.0/power_loop/runtime/invocation.py

@@ -0,0 +1,58 @@
+"""Identity of the actual persisted assistant call currently invoking a tool."""
+
+from __future__ import annotations
+
+from contextlib import ExitStack, contextmanager
+from contextvars import ContextVar
+
+_INVOCATION: ContextVar[tuple[str | None, int | None, str | None] | None] = ContextVar(
+    "power_loop_tool_invocation", default=None
+)
+
+
+_SCOPE_FACTORIES = {}
+
+
+def register_invocation_scope(name, factory, *, exporter=None):
+    """Install a trusted host context manager around each actual invocation."""
+    if not isinstance(name, str) or not name or not callable(factory):
+        raise ValueError("invalid invocation scope provider")
+    _SCOPE_FACTORIES[name] = (factory, exporter)
+
+
+@contextmanager
+def invocation_context(session_id, assistant_seq, tool_call_id, tool_name=None):
+    token = _INVOCATION.set((session_id, assistant_seq, tool_call_id))
+    try:
+        with ExitStack() as scopes:
+            for factory, _exporter in tuple(_SCOPE_FACTORIES.values()):
+                scopes.enter_context(
+                    factory(
+                        session_id=session_id,
+                        assistant_seq=assistant_seq,
+                        tool_call_id=tool_call_id,
+                        tool_name=tool_name,
+                    )
+                )
+            yield
+    finally:
+        _INVOCATION.reset(token)
+
+
+def current_invocation(session_id):
+    current = _INVOCATION.get()
+    # A child's model run inherits ContextVars but must not inherit its parent's
+    # tool identity. A real child tool invocation will install its own context.
+    return current[1:] if current and current[0] == session_id else (None, None)
+
+
+def capture_host_contexts():
+    """Audit-only host snapshots; never part of task authority or request input."""
+    import json
+
+    values = {}
+    for name, (_factory, exporter) in tuple(_SCOPE_FACTORIES.items()):
+        value = exporter() if exporter is not None else None
+        if value is not None:
+            values[name] = json.loads(json.dumps(value, allow_nan=False))
+    return values

{power_loop-9.0.0 → power_loop-9.1.0}/power_loop/runtime/jobs.py

@@ -727,6 +727,10 @@ class JobManager:
             payload["request"] = request_data
         if wait_binding is not None:
             payload["wait_binding"] = wait_binding
+        from .invocation import capture_host_contexts
+        host_contexts = capture_host_contexts()
+        if host_contexts:
+            payload["host_contexts"] = host_contexts
         operation = await self._insert_operation(tx, job_id=job_id, version=1, actor=actor, action="create",
             key=key, fingerprint=fingerprint, call_ref=call_ref, tool_call_id=tool_call_id,
             payload=payload)

{power_loop-9.0.0 → power_loop-9.1.0}/power_loop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 9.0.0
+Version: 9.1.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -418,3 +418,19 @@ After the exact charge is locally durable, API delivery failure leaves a pending
 budget submission and preserves the real tool result. Reconciliation never calls
 the handler again or reads a replacement price. Managed recovery sources without
 an ordinary callback checkpoint still need a separate adapter.
+
+
+### Host lifecycle extensions
+
+Hosts can raise `power_loop.core.control.ControlledLoopStop(reason, message=...)`
+from session-entry or round-start hooks. The pipeline records a controlled stop,
+keeps completed work, and skips memory summarization on that exit. Hosts own
+quota policy and settlement; the SDK has no application currency or user model.
+
+`power_loop.runtime.invocation.register_invocation_scope(name, factory, exporter=...)`
+installs a synchronous context manager around each actual tool invocation. The
+factory receives `session_id`, `assistant_seq`, `tool_call_id`, and `tool_name`.
+An optional exporter returns a small JSON snapshot which is saved as
+`host_contexts[name]` on original job creation. Replay retains the original saved
+snapshot; hosts restore it when recovering a child job. Business snapshots do not
+carry execution authority and do not replace the SDK's signed task request.

{power_loop-9.0.0 → power_loop-9.1.0}/power_loop.egg-info/SOURCES.txt

@@ -44,6 +44,7 @@ power_loop/contrib/mcp.py
 power_loop/contrib/metrics_sink.py
 power_loop/contrib/otel_sink.py
 power_loop/core/agent_context.py
+power_loop/core/control.py
 power_loop/core/events.py
 power_loop/core/hooks.py
 power_loop/core/pass_turn.py

power_loop-9.0.0/power_loop/runtime/invocation.py

@@ -1,24 +0,0 @@
-"""Identity of the actual persisted assistant call currently invoking a tool."""
-from __future__ import annotations
-
-from contextlib import contextmanager
-from contextvars import ContextVar
-
-_INVOCATION: ContextVar[tuple[str | None, int | None, str | None] | None] = ContextVar(
-    "power_loop_tool_invocation", default=None)
-
-
-@contextmanager
-def invocation_context(session_id, assistant_seq, tool_call_id):
-    token = _INVOCATION.set((session_id, assistant_seq, tool_call_id))
-    try:
-        yield
-    finally:
-        _INVOCATION.reset(token)
-
-
-def current_invocation(session_id):
-    current = _INVOCATION.get()
-    # A child's model run inherits ContextVars but must not inherit its parent's
-    # tool identity. A real child tool invocation will install its own context.
-    return current[1:] if current and current[0] == session_id else (None, None)