power-loop 0.8.0__tar.gz → 0.9.0__tar.gz

{power_loop-0.8.0/power_loop.egg-info → power_loop-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 0.8.0
+Version: 0.9.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -55,6 +55,11 @@ agent runs model-authored or otherwise untrusted commands, run them in your own
 (`runtime.exec_backend`); power-loop launches the persistent shell through your backend.
 Keep secrets in your orchestrator — the loop does not scrub the tool environment for you.
 
+Likewise there is **no built-in scheduler/timer**: a session only runs while a `send()` /
+`resume()` call is in flight. "Wake this agent again in 10 minutes" is orchestrator state —
+keep it in your own durable store and call `send()` when it fires (that survives restarts;
+an in-process timer would not).
+
 ## Install
 
 ```bash
@@ -156,6 +161,38 @@ with runtime_env_context(RuntimeEnv(workspace_dir=tenant_workspace)):
 
 See [`examples/23_per_send_overrides.py`](examples/23_per_send_overrides.py).
 
+### Token usage accounting
+
+Every `send()` returns the run's cumulative token usage — summed over all LLM
+calls of that run (tool loops make several) — so cost accounting needs no event
+plumbing:
+
+```python
+res = await loop.send("…", session_id=sid)
+res.usage
+# {"prompt_tokens": 1234, "completion_tokens": 56, "cache_read_tokens": 0,
+#  "reasoning_tokens": 0, "total_tokens": 1290, "calls": 2}
+```
+
+For per-call, real-time metering subscribe to the `usage_updated` event (one
+per LLM call, tagged with `session_id`). See
+[`examples/25_token_usage.py`](examples/25_token_usage.py).
+
+### Crash recovery: `heal_pending`
+
+A run killed mid tool-call leaves the session with unresolved `tool_calls`;
+the next `send()` raises `SessionPendingError` (the message protocol forbids
+continuing). Orchestrators whose runs can legitimately die (human interrupts,
+process restarts) can opt into self-healing:
+
+```python
+res = await loop.send("…", session_id=sid, heal_pending=True)
+# stale tool_calls are aborted with synthetic <aborted> results, then the
+# send proceeds. Default remains raise — healing discards in-flight work.
+```
+
+Or recover explicitly with `resume(sid)` / `abort_pending(sid)`.
+
 ## Public API
 
 Stable imports are re-exported from `power_loop`:

{power_loop-0.8.0 → power_loop-0.9.0}/README.md

@@ -18,6 +18,11 @@ agent runs model-authored or otherwise untrusted commands, run them in your own
 (`runtime.exec_backend`); power-loop launches the persistent shell through your backend.
 Keep secrets in your orchestrator — the loop does not scrub the tool environment for you.
 
+Likewise there is **no built-in scheduler/timer**: a session only runs while a `send()` /
+`resume()` call is in flight. "Wake this agent again in 10 minutes" is orchestrator state —
+keep it in your own durable store and call `send()` when it fires (that survives restarts;
+an in-process timer would not).
+
 ## Install
 
 ```bash
@@ -119,6 +124,38 @@ with runtime_env_context(RuntimeEnv(workspace_dir=tenant_workspace)):
 
 See [`examples/23_per_send_overrides.py`](examples/23_per_send_overrides.py).
 
+### Token usage accounting
+
+Every `send()` returns the run's cumulative token usage — summed over all LLM
+calls of that run (tool loops make several) — so cost accounting needs no event
+plumbing:
+
+```python
+res = await loop.send("…", session_id=sid)
+res.usage
+# {"prompt_tokens": 1234, "completion_tokens": 56, "cache_read_tokens": 0,
+#  "reasoning_tokens": 0, "total_tokens": 1290, "calls": 2}
+```
+
+For per-call, real-time metering subscribe to the `usage_updated` event (one
+per LLM call, tagged with `session_id`). See
+[`examples/25_token_usage.py`](examples/25_token_usage.py).
+
+### Crash recovery: `heal_pending`
+
+A run killed mid tool-call leaves the session with unresolved `tool_calls`;
+the next `send()` raises `SessionPendingError` (the message protocol forbids
+continuing). Orchestrators whose runs can legitimately die (human interrupts,
+process restarts) can opt into self-healing:
+
+```python
+res = await loop.send("…", session_id=sid, heal_pending=True)
+# stale tool_calls are aborted with synthetic <aborted> results, then the
+# send proceeds. Default remains raise — healing discards in-flight work.
+```
+
+Or recover explicitly with `resume(sid)` / `abort_pending(sid)`.
+
 ## Public API
 
 Stable imports are re-exported from `power_loop`:

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/__init__.py

@@ -22,7 +22,7 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 from power_loop.agent.follow_up import FollowUpQueued
 from power_loop.agent.sink import MessageSink, NullSink, SQLiteSink

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/agent/stateful_loop.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 from collections.abc import Sequence
 from dataclasses import dataclass, field, replace
 from typing import Any
@@ -56,6 +57,8 @@ from power_loop.runtime.session_store import (
 from power_loop.runtime.skills import SkillLoader
 from power_loop.tools.registry import ToolRegistry
 
+logger = logging.getLogger("power_loop.stateful")
+
 
 @dataclass
 class StatefulResult:
@@ -67,6 +70,10 @@ class StatefulResult:
     rounds: int = 0
     pending_tool_calls: list[dict[str, Any]] = field(default_factory=list)
     pending_interactions: list[dict[str, Any]] = field(default_factory=list)
+    #: Cumulative token usage for this send (summed over every LLM call):
+    #: {prompt_tokens, completion_tokens, cache_read_tokens, reasoning_tokens,
+    #:  total_tokens, calls}. Empty when the run never reached the LLM.
+    usage: dict[str, int] = field(default_factory=dict)
 
 
 class StatefulAgentLoop:
@@ -134,6 +141,7 @@ class StatefulAgentLoop:
         stop_event: CancellationLike = None,
         tools: Sequence[str] | ToolRegistry | None = None,
         system_prompt: str | None = None,
+        heal_pending: bool = False,
     ) -> StatefulResult:
         """Append one user input to the session and run the loop.
 
@@ -149,13 +157,24 @@ class StatefulAgentLoop:
           (precedence: this arg > session system_prompt > config).
 
         Raises :class:`SessionPendingError` if the session has unresolved
-        tool_calls; the caller must call :meth:`resume` or
-        :meth:`abort_pending` first.
+        tool_calls (a previous run died mid tool-call); the caller must call
+        :meth:`resume` or :meth:`abort_pending` first — or pass
+        ``heal_pending=True`` to have ``send`` abort the stale tool_calls
+        itself and proceed (the right default for orchestrators whose runs
+        can be killed, e.g. by a human interrupt).
         """
         sid = session_id
         async with self._lock_for(sid):
             self._ensure_session_or_raise(sid)
-            self._raise_if_pending(sid)
+            if heal_pending:
+                healed = self._heal_pending(sid)
+                if healed:
+                    logger.warning(
+                        "send(heal_pending=True): aborted %d stale tool_call(s) "
+                        "in session %s before proceeding", healed, sid,
+                    )
+            else:
+                self._raise_if_pending(sid)
             self._persist_user_input(sid, user_input)
             return await self._run_loop(
                 sid, stop_event=stop_event, tools=tools, system_prompt=system_prompt
@@ -217,6 +236,7 @@ class StatefulAgentLoop:
         stop_event: CancellationLike = None,
         tools: Sequence[str] | ToolRegistry | None = None,
         system_prompt: str | None = None,
+        heal_pending: bool = False,
     ) -> StatefulResult:
         return asyncio.run(
             self.send(
@@ -225,6 +245,7 @@ class StatefulAgentLoop:
                 stop_event=stop_event,
                 tools=tools,
                 system_prompt=system_prompt,
+                heal_pending=heal_pending,
             )
         )
 
@@ -301,6 +322,14 @@ class StatefulAgentLoop:
 
             return await self._run_loop(session_id, stop_event=stop_event, sink=sink)
 
+    def _heal_pending(self, sid: str) -> int:
+        """abort_pending without the session-existence re-check (callers in
+        send already hold the lock and have validated the session)."""
+        state = self.store.get_state(sid)
+        if state is None or not state.pending:
+            return 0
+        return self.abort_pending(sid, reason="auto-healed by send(heal_pending=True)")
+
     def abort_pending(self, session_id: str, *, reason: str = "aborted") -> int:
         """Synthesize ``<aborted: reason>`` tool messages for every unresolved
         tool_call, restoring message-protocol validity. Returns the number of
@@ -593,6 +622,7 @@ class StatefulAgentLoop:
             rounds=result.rounds,
             pending_tool_calls=result.pending_tool_calls,
             pending_interactions=result.pending_interactions,
+            usage=result.usage,
         )
 
     def _prime_sink_from_pending(self, sid: str, sink: SQLiteSink) -> None:

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/agent/types.py

@@ -66,3 +66,7 @@ class AgentLoopResult:
     pending_tool_calls: list[dict[str, Any]] = field(default_factory=list)
     pending_interactions: list[dict[str, Any]] = field(default_factory=list)
     messages: list[LoopMessage] = field(default_factory=list)
+    #: Cumulative token usage across every LLM call of this run:
+    #: {prompt_tokens, completion_tokens, cache_read_tokens, reasoning_tokens,
+    #:  total_tokens, calls}. Empty dict when the run never reached the LLM.
+    usage: dict[str, int] = field(default_factory=dict)

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/contracts/errors.py

@@ -52,7 +52,10 @@ class SessionPendingError(PowerLoopError):
         )
         super().__init__(
             f"session {session_id} has {len(pending_tool_calls)} unresolved tool_calls"
-            f" from round (assistant_seq={assistant_seq}): {names}"
+            f" from round (assistant_seq={assistant_seq}): {names}."
+            " Recover with resume(sid) to finish them, abort_pending(sid) to"
+            " discard them, or call send(..., heal_pending=True) to auto-abort"
+            " and proceed"
         )
 
 

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/core/pipeline.py

@@ -389,6 +389,7 @@ class AgentPipeline:
             pending_tool_calls=pending_tool_calls or [],
             pending_interactions=pending_interactions or [],
             messages=self.history,
+            usage=dict(self.ctx.usage_totals),
         )
 
     def _persist_pending_interaction(

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/core/state.py

@@ -94,7 +94,14 @@ class ContextManager:
     recent_files: list[str] = field(default_factory=list)
     _file_counter: int = 0
 
+    #: Usage of the **last** LLM call only (overwritten by every
+    #: :meth:`update_usage`). For whole-run totals use :attr:`usage_totals`.
     token_usage: dict[str, Any] = field(default_factory=dict)
+    #: Cumulative usage across every LLM call of this context's lifetime
+    #: (one context = one ``send``/run): prompt_tokens / completion_tokens /
+    #: cache_read_tokens / reasoning_tokens / total_tokens / calls.
+    #: Surfaced on ``AgentLoopResult.usage`` and ``StatefulResult.usage``.
+    usage_totals: dict[str, int] = field(default_factory=dict)
     #: 可选计数器，供测试/扩展使用；**不会**被 ``update_usage`` 自动递增
     api_calls: int = 0
 
@@ -165,6 +172,11 @@ class ContextManager:
             "reasoning": reasoning,
         }
         self.token_usage = usage_out
+        totals = self.usage_totals
+        totals["calls"] = totals.get("calls", 0) + 1
+        for key in ("prompt_tokens", "completion_tokens", "cache_read_tokens",
+                    "reasoning_tokens", "total_tokens"):
+            totals[key] = totals.get(key, 0) + usage_out[key]
         return usage_out
 
     def microcompact(self, messages: list[dict[str, Any]]) -> None:

{power_loop-0.8.0 → power_loop-0.9.0}/power_loop/runtime/notes.py

@@ -190,5 +190,10 @@ class SQLiteNoteMemory:
             return []
         return [{"role": "system", "name": "memory_notes", "content": text}]
 
-    async def remember(self, snapshot: Any) -> None:  # noqa: ARG002
+    async def remember(
+        self,
+        *,
+        snapshot: Any,
+        session_id: str | None = None,
+    ) -> None:
         return None

{power_loop-0.8.0 → power_loop-0.9.0/power_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: power-loop
-Version: 0.8.0
+Version: 0.9.0
 Summary: Embeddable agent execution kernel — LLM loop, hooks, events, tools, dynamic sub-agents.
 Author-email: zhangran <zhangran24@126.com>
 License: MIT
@@ -55,6 +55,11 @@ agent runs model-authored or otherwise untrusted commands, run them in your own
 (`runtime.exec_backend`); power-loop launches the persistent shell through your backend.
 Keep secrets in your orchestrator — the loop does not scrub the tool environment for you.
 
+Likewise there is **no built-in scheduler/timer**: a session only runs while a `send()` /
+`resume()` call is in flight. "Wake this agent again in 10 minutes" is orchestrator state —
+keep it in your own durable store and call `send()` when it fires (that survives restarts;
+an in-process timer would not).
+
 ## Install
 
 ```bash
@@ -156,6 +161,38 @@ with runtime_env_context(RuntimeEnv(workspace_dir=tenant_workspace)):
 
 See [`examples/23_per_send_overrides.py`](examples/23_per_send_overrides.py).
 
+### Token usage accounting
+
+Every `send()` returns the run's cumulative token usage — summed over all LLM
+calls of that run (tool loops make several) — so cost accounting needs no event
+plumbing:
+
+```python
+res = await loop.send("…", session_id=sid)
+res.usage
+# {"prompt_tokens": 1234, "completion_tokens": 56, "cache_read_tokens": 0,
+#  "reasoning_tokens": 0, "total_tokens": 1290, "calls": 2}
+```
+
+For per-call, real-time metering subscribe to the `usage_updated` event (one
+per LLM call, tagged with `session_id`). See
+[`examples/25_token_usage.py`](examples/25_token_usage.py).
+
+### Crash recovery: `heal_pending`
+
+A run killed mid tool-call leaves the session with unresolved `tool_calls`;
+the next `send()` raises `SessionPendingError` (the message protocol forbids
+continuing). Orchestrators whose runs can legitimately die (human interrupts,
+process restarts) can opt into self-healing:
+
+```python
+res = await loop.send("…", session_id=sid, heal_pending=True)
+# stale tool_calls are aborted with synthetic <aborted> results, then the
+# send proceeds. Default remains raise — healing discards in-flight work.
+```
+
+Or recover explicitly with `resume(sid)` / `abort_pending(sid)`.
+
 ## Public API
 
 Stable imports are re-exported from `power_loop`: