power-loop 0.4.0__tar.gz → 0.4.1__tar.gz

{power_loop-0.4.0 → power_loop-0.4.1}/PKG-INFO

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

{power_loop-0.4.0 → power_loop-0.4.1}/power_loop/__init__.py

@@ -7,6 +7,7 @@ Stability tiers
 业务方（如 DeepTalk `agent` 服务）只应依赖这一层。
 
     StatefulAgentLoop, StatefulResult,
+    FollowUpQueued,
     AgentLoopConfig, AgentLoopResult,
     SessionStore,
     PowerLoopError,
@@ -21,10 +22,11 @@ Stability tiers
 无版本承诺，可随时变更或删除。
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 from power_loop.agent.sink import MessageSink, NullSink, SQLiteSink
 from power_loop.agent.stateful_loop import StatefulAgentLoop, StatefulResult
+from power_loop.agent.follow_up import FollowUpQueued
 from power_loop.agent.system_prompt import (
     BUILTIN_SECTIONS,
     DEFAULT_AGENT_SYSTEM_PROMPT,

power_loop-0.4.1/power_loop/agent/follow_up.py

@@ -0,0 +1,61 @@
+"""Follow-up / steering queue for in-flight agent loops."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from power_loop.agent.types import LoopMessage
+
+FOLLOW_UP_MESSAGE_NAME = "follow_up"
+
+
+@dataclass(frozen=True)
+class FollowUpQueued:
+    """Returned when :meth:`StatefulAgentLoop.follow_up` enqueues steering input."""
+
+    session_id: str
+    queue_depth: int
+
+
+def format_follow_up_user_message(text: str) -> LoopMessage:
+    """Wrap steering text as a user message for the LLM transcript."""
+    body = text.strip()
+    return {
+        "role": "user",
+        "name": FOLLOW_UP_MESSAGE_NAME,
+        "content": f"<follow_up>\n{body}\n</follow_up>",
+    }
+
+
+def merge_follow_up_inputs(items: list[str | LoopMessage]) -> LoopMessage | None:
+    """Merge queued follow-up payloads into one user message."""
+    parts: list[str] = []
+    for item in items:
+        if isinstance(item, str):
+            text = item.strip()
+        else:
+            text = _content_as_text(item.get("content")).strip()
+        if text:
+            parts.append(text)
+    if not parts:
+        return None
+    return format_follow_up_user_message("\n\n".join(parts))
+
+
+def _content_as_text(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    import json
+
+    return json.dumps(content, ensure_ascii=False)
+
+
+__all__ = [
+    "FOLLOW_UP_MESSAGE_NAME",
+    "FollowUpQueued",
+    "format_follow_up_user_message",
+    "merge_follow_up_inputs",
+]

{power_loop-0.4.0 → power_loop-0.4.1}/power_loop/agent/stateful_loop.py

@@ -1,7 +1,8 @@
 """StatefulAgentLoop — the single public entry point for power-loop.
 
 Owns a :class:`SessionStore` and gives callers a stateful,
-``new_session()`` + ``send(user_input, session_id=...)`` interface.
+``new_session()`` + ``send(user_input, session_id=...)`` interface, plus
+:meth:`follow_up` for steering an in-flight loop without blocking.
 Everything else — pipeline orchestration, hooks, events, tool invocation,
 persistence, pending-state machine — is wired up internally.
 
@@ -23,6 +24,7 @@ from dataclasses import dataclass, field, replace
 from typing import Any
 
 from llm_client.interface import LLMService
+from power_loop.agent.follow_up import FollowUpQueued, merge_follow_up_inputs
 from power_loop.agent.sink import SQLiteSink
 from power_loop.agent.system_prompt import (
     DEFAULT_AGENT_SYSTEM_PROMPT,
@@ -93,6 +95,8 @@ class StatefulAgentLoop:
         self.tool_registry = tool_registry
         self._runner = AgentRunner(event_bus=event_bus, hooks=hooks)
         self._locks: dict[str, asyncio.Lock] = {}
+        self._follow_up_queues: dict[str, list[str | LoopMessage]] = {}
+        self._follow_up_queue_locks: dict[str, asyncio.Lock] = {}
 
     # ── lifecycle ─────────────────────────────────────────────────────────
 
@@ -144,6 +148,42 @@ class StatefulAgentLoop:
             self._persist_user_input(sid, user_input)
             return await self._run_loop(sid, stop_event=stop_event)
 
+    async def follow_up(
+        self,
+        user_input: str | LoopMessage,
+        session_id: str,
+        *,
+        stop_event: CancellationLike = None,
+    ) -> StatefulResult | FollowUpQueued:
+        """Steer an in-flight loop, or fall back to :meth:`send`.
+
+        When the session lock is held by a running :meth:`send` / :meth:`resume`
+        / :meth:`submit_input`, the input is appended to a per-session queue.
+        The pipeline drains that queue at each **round** boundary (before
+        ``prepare_round``), injects a wrapped ``<follow_up>`` user message, and
+        clears the drained items.
+
+        When the session is idle (lock not held), behaves like :meth:`send`.
+        """
+        sid = session_id
+        self._ensure_session_or_raise(sid)
+        session_lock = self._lock_for(sid)
+        if session_lock.locked():
+            depth = await self._enqueue_follow_up(sid, user_input)
+            return FollowUpQueued(session_id=sid, queue_depth=depth)
+        return await self.send(user_input, sid, stop_event=stop_event)
+
+    def follow_up_sync(
+        self,
+        user_input: str | LoopMessage,
+        session_id: str,
+        *,
+        stop_event: CancellationLike = None,
+    ) -> StatefulResult | FollowUpQueued:
+        return asyncio.run(
+            self.follow_up(user_input, session_id, stop_event=stop_event)
+        )
+
     def send_sync(
         self,
         user_input: str | LoopMessage,
@@ -365,6 +405,25 @@ class StatefulAgentLoop:
             self._locks[sid] = lock
         return lock
 
+    def _follow_up_queue_lock_for(self, sid: str) -> asyncio.Lock:
+        lock = self._follow_up_queue_locks.get(sid)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._follow_up_queue_locks[sid] = lock
+        return lock
+
+    async def _enqueue_follow_up(self, sid: str, user_input: str | LoopMessage) -> int:
+        async with self._follow_up_queue_lock_for(sid):
+            queue = self._follow_up_queues.setdefault(sid, [])
+            queue.append(user_input)
+            return len(queue)
+
+    async def _drain_follow_up_messages(self, sid: str) -> list[LoopMessage]:
+        async with self._follow_up_queue_lock_for(sid):
+            pending = self._follow_up_queues.pop(sid, [])
+        merged = merge_follow_up_inputs(pending)
+        return [merged] if merged is not None else []
+
     def _ensure_session_or_raise(self, sid: str) -> None:
         if self.store.get_session(sid) is None:
             raise SessionNotFoundError(sid)
@@ -457,6 +516,9 @@ class StatefulAgentLoop:
         async with self._runner.session_async(session_id=sid):
             loop_token = set_current_loop(self)
             try:
+                async def _drain_follow_ups() -> list[LoopMessage]:
+                    return await self._drain_follow_up_messages(sid)
+
                 pipeline = AgentPipeline(
                     llm=self.llm,
                     config=runtime_config,
@@ -468,6 +530,7 @@ class StatefulAgentLoop:
                     stop_event=stop_event,
                     sink=sink,
                     store=self.store,
+                    drain_follow_ups=_drain_follow_ups,
                 )
                 result: AgentLoopResult = await pipeline.run(history)
             finally:
@@ -555,4 +618,4 @@ def _as_tool_result_text(value: Any) -> str:
     return json.dumps(value, ensure_ascii=False)
 
 
-__all__ = ["StatefulAgentLoop", "StatefulResult", "MessageState"]
+__all__ = ["StatefulAgentLoop", "StatefulResult", "MessageState", "FollowUpQueued"]

{power_loop-0.4.0 → power_loop-0.4.1}/power_loop/core/pipeline.py

@@ -201,6 +201,7 @@ class AgentPipeline:
         stop_event: CancellationLike = None,
         sink: MessageSink | None = None,
         store: Any | None = None,
+        drain_follow_ups: Any | None = None,
     ) -> None:
         self.llm = llm
         self.config = config
@@ -215,6 +216,7 @@ class AgentPipeline:
         self.stop_event = stop_event if isinstance(stop_event, threading.Event) else None
         self.sink: MessageSink = sink if sink is not None else NullSink()
         self.store = store
+        self._drain_follow_ups = drain_follow_ups
 
         base_prompt = (config.system_prompt or DEFAULT_AGENT_SYSTEM_PROMPT).strip()
         self.runtime_tools = tool_registry.to_openai_tools() if tool_registry is not None else None
@@ -639,6 +641,12 @@ class AgentPipeline:
             if isinstance(round_ctx.messages, list):
                 self.history = round_ctx.messages
 
+            # ── In-flight steering: drain follow-up queue at round boundary ──
+            if self._drain_follow_ups is not None:
+                drained = await self._drain_follow_ups()
+                for msg in drained:
+                    await self._append_message(msg, round_index=round_idx)
+
             # ── Business logic: prepare round ──
             await self.prepare_round(round_idx)
 

{power_loop-0.4.0 → power_loop-0.4.1}/power_loop.egg-info/PKG-INFO

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

{power_loop-0.4.0 → power_loop-0.4.1}/power_loop.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ power_loop.egg-info/dependency_links.txt
 power_loop.egg-info/requires.txt
 power_loop.egg-info/top_level.txt
 power_loop/agent/__init__.py
+power_loop/agent/follow_up.py
 power_loop/agent/sink.py
 power_loop/agent/stateful_loop.py
 power_loop/agent/system_prompt.py