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

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

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

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

{power_loop-7.3.0 → power_loop-8.0.0}/power_loop/agent/stateful_loop.py

@@ -1302,6 +1302,8 @@ class StatefulAgentLoop:
                              "title": str(w.get("workflow") or "")[:80],
                              "status": "running" if is_run_live(rid) else "orphaned",
                              "started_at": ts, "origin": _origin(ts)})
+        from power_loop.runtime.delegation import running_jobs
+        jobs.extend(running_jobs(store, session_id))
         for tm in await store.list_timers(session_id, statuses=("armed",)):
             jobs.append({"id": f"timer:{tm.timer_id}", "kind": "timer",
                          "title": str(tm.note or "")[:80], "status": "armed",
@@ -1343,6 +1345,9 @@ class StatefulAgentLoop:
                     result = "stopped"
         elif kind == "wf" and ref:
             result = await stop_run(ref, grace_s=pol.workflow_s, reason="stopped")
+        elif kind == "sub" and ref:
+            from power_loop.runtime.delegation import stop
+            result = await stop(store, session_id, ref, pol.workflow_s)
         elif kind == "timer" and ref.isdigit():
             result = "stopped" if await self.cancel_timer(session_id, int(ref)) else "finished"
         return {"id": job_id, "result": result}
@@ -2407,14 +2412,10 @@ class StatefulAgentLoop:
     ) -> None:
         """Project the just-finished send's ``pl_messages`` rows into ``pl_project_messages`` (v2).
 
-        Skips sub-agent CHILD sessions (their transcript lives in their own pl_session) by
-        ``parent_session_id`` — NOT ``scope``, which ``_finalize`` hardcodes to ``'main'`` even
-        for children. Defers on a still-in-flight status (the resume re-finalizes under the SAME
+        Includes child sessions regardless of their tool-context/fuse setting.
+        Defers on a still-in-flight status (the resume re-finalizes under the SAME
         ``send_index``; the idempotent UPSERT then overwrites). Best-effort — the caller swallows
         failures, since ``pl_messages`` remains the source of truth."""
-        if (session_row is not None and session_row.parent_session_id is not None
-                and self.config.tool_context is None):
-            return  # legacy behavior; policy-enabled children prepare their own context
         if status in ("waiting_for_input", "pending_tools"):
             return  # send not finished; the resume will re-finalize under the same send_index
         # 只取本 send 的行：这里要投影的就是这一个 send，从前是读全表再在 Python 里过滤，

{power_loop-7.3.0 → power_loop-8.0.0}/power_loop/core/pass_turn.py

@@ -43,7 +43,7 @@ _state: ContextVar[dict[str, Any] | None] = ContextVar("power_loop_pass_turn", d
 
 def begin() -> Token:
     """一个 send 开始：装一份新的状态。返回还原用的 token。"""
-    return _state.set({"passed": False, "reason": None, "new_input_after_pass": False})
+    return _state.set({"passed": False, "reason": None, "new_input_after_pass": False, "texts": 0, "work_tools": 0})
 
 
 def end(token: Token) -> None:
@@ -64,6 +64,25 @@ def request_pass(reason: str = "") -> bool:
     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"))

{power_loop-7.3.0 → power_loop-8.0.0}/power_loop/core/pipeline.py

@@ -1906,6 +1906,8 @@ class AgentPipeline:
             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:
@@ -2336,8 +2338,13 @@ class AgentPipeline:
                                                     tool_call_id=call_id, failed=failed),
                            round_index=round_idx)
 
+                stored_output = _truncate_result(output, self.config.tool_result_max_chars)
+                if tool_name == "spawn_agent":
+                    from power_loop.runtime.delegation import result_view
+                    # Structured receipts/results cannot be cut through their metadata or JSON.
+                    stored_output = result_view(str(output), self.config.tool_result_max_chars or 20000) or stored_output
                 await self._append_message(
-                    {"role": "tool", "tool_call_id": call_id, "name": tool_name, "content": _truncate_result(output, self.config.tool_result_max_chars)},
+                    {"role": "tool", "tool_call_id": call_id, "name": tool_name, "content": stored_output},
                     round_index=round_idx,
                 )
 

power_loop-8.0.0/power_loop/runtime/delegation.py

@@ -0,0 +1,382 @@
+"""Asynchronous subagent sessions, durable results and serialized continuation.
+
+The host owns idle-parent wake routing. No notification callback starts a bare parent loop.
+Execution is process-local; records and undelivered inbox items survive the process.
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import secrets
+import weakref
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from power_loop.agent.follow_up import InboxItem
+from power_loop.core.agent_context import get_session_id
+from power_loop.runtime.cancellation import CancellationToken
+from power_loop.runtime.recall import authorize, dumps
+from power_loop.runtime.spec import (
+    _ON_CHILD_SESSION,
+    _USAGE_SINK,
+    AgentSpec,
+    run_agent_spec,
+    workflow_continuation_loop,
+)
+
+log = logging.getLogger(__name__)
+RESULT_PREFIX = "[subagent_result]\n"
+
+
+@dataclass
+class Running:
+    run_id: str
+    task: asyncio.Task | None = None
+    token: Any = None
+    parent: str = ""
+    title: str = ""
+    suppress_wake: bool = False
+    phase: str = "running"
+    descendant_usage: dict = field(default_factory=dict)
+    projection_expected: bool = True
+
+
+_RUNNING: dict[tuple[int, str], Running] = {}
+_TASKS: set[asyncio.Task] = set()
+
+
+def _retain(task):
+    _TASKS.add(task)
+    task.add_done_callback(_TASKS.discard)
+
+
+async def _save_result(store, parent, sid, run, raw, after_seq, lifecycle):
+    messages = await store.history_bounds(sid)
+    messages = [max(after_seq + 1, messages[0]), messages[1]] if messages and messages[1] > after_seq else None
+    projection, projection_status = None, "empty"
+    try:
+        projection = await store.history_bounds(sid, source="projection", after_seq=after_seq)
+        projection_status = "ready" if projection else "failed" if run.projection_expected else "disabled"
+    except ValueError:
+        projection_status = "disabled"
+    usage = dict(raw.get("usage") or {})
+    for name, value in run.descendant_usage.items():
+        usage[name] = usage.get(name, 0) + value
+    result = {**raw, "usage": usage, "session_id": sid, "run_id": run.run_id, "messages": messages,
+              "projection": projection, "history_status": "available" if messages else "empty",
+              "projection_status": projection_status}
+    # Persist ownership/prepared result BEFORE any destructive cleanup.
+    key = "subagent:run:" + run.run_id
+    await store.set_runtime_state(parent, key, {"phase": "prepared", "result": result})
+    if lifecycle == "ephemeral" and raw.get("status") == "completed":
+        await store.close_session(sid, cascade=True)
+        result.update(messages=None, projection=None, history_status="deleted", projection_status="deleted")
+        await store.set_runtime_state(parent, "subagent:child:" + sid,
+                                      {"deleted": True, "lifecycle": lifecycle})
+    await store.set_runtime_state(parent, key, {"phase": "completed", "result": result, "notified": False})
+    return result
+
+
+async def _finish(loop, parent, sid, running, raw, after_seq, lifecycle, finalize, on_complete):
+    store = await loop.ensure_store()
+    running.phase = "settling"
+    children = [r.task for (key, _), r in list(_RUNNING.items())
+                if key == id(store) and r.parent == sid and r.task is not None]
+    if children:
+        await asyncio.gather(*children)
+    if finalize is not None:
+        raw = await finalize(sid, raw)
+    # A nudge racing finalization is already durable. Consume it in this run before returning.
+    continuation = None
+    while (await store.inbox_counts(sid))["pending"]:
+        if running.token.is_cancelled():
+            break
+        if continuation is None:
+            continuation = await workflow_continuation_loop(loop, sid)
+        with contextlib.ExitStack() as guards:
+            for _, guard in getattr(loop, "_child_run_guards", ()):
+                guards.enter_context(guard())
+            extra = await continuation.flush_follow_ups(sid, stop_event=running.token)
+        if extra is None:
+            break
+        raw["final_text"] = str(extra.final_text or "")
+        raw["status"] = extra.status
+        raw["rounds"] = int(raw.get("rounds", 0)) + int(extra.rounds)
+        usage = dict(raw.get("usage") or {})
+        for key, value in (extra.usage or {}).items():
+            usage[key] = usage.get(key, 0) + value
+        raw["usage"] = usage
+        if finalize is not None:
+            raw = await finalize(sid, raw)
+    # From the final pending check through cleanup, nudge uses our gate (below).
+    async with _gate(store, sid):
+        child_active = any(key == id(store) and r.parent == sid for (key, _), r in _RUNNING.items())
+        if ((await store.inbox_counts(sid))["pending"] or child_active) and not running.token.is_cancelled():
+            # Re-enter outside the gate; callers can enqueue without losing accepted input.
+            again = True
+        else:
+            again = False
+            result = await _save_result(store, parent, sid, running, raw, after_seq, lifecycle)
+            def accumulate(value):
+                totals = dict(value or {})
+                for name, count in result.get("usage", {}).items():
+                    if isinstance(count, (int, float)) and not isinstance(count, bool):
+                        totals[name] = totals.get(name, 0) + count
+                return totals
+            await store.mutate_runtime_state(parent, "subagent:usage:total", accumulate, default={})
+            parent_run = _RUNNING.get((id(store), parent))
+            if parent_run is not None:
+                for name, value in result.get("usage", {}).items():
+                    if isinstance(value, (int, float)) and not isinstance(value, bool):
+                        parent_run.descendant_usage[name] = parent_run.descendant_usage.get(name, 0) + value
+            _RUNNING.pop((id(store), sid), None)
+            _publish_completion(loop, parent, sid, result)
+    if again:
+        return await _finish(loop, parent, sid, running, raw, after_seq, lifecycle, finalize, on_complete)
+    try:
+        if running.suppress_wake:
+            return result
+        # Inbox delivery is durable and deduplicated before asking the host to wake an idle
+        # parent. A failed/skipped wake still leaves the result for its next normal send.
+        await loop.deliver(InboxItem(RESULT_PREFIX + completion_view(loop, result), kind="task_done",
+                                    item_id="subagent:" + running.run_id), parent, enqueue_only=True)
+        if on_complete is not None:
+            await on_complete(parent, result)
+        record = await store.get_runtime_state(parent, "subagent:run:" + running.run_id)
+        await store.set_runtime_state(parent, "subagent:run:" + running.run_id, {**record, "notified": True})
+    except Exception:
+        log.exception("subagent completion not delivered; durable result retained: %s", running.run_id)
+    return result
+
+
+_GATES: weakref.WeakValueDictionary = weakref.WeakValueDictionary()
+
+
+def _gate(store, sid):
+    return _GATES.setdefault((id(store), sid), asyncio.Lock())
+
+
+async def _complete(loop, parent, sid, run, raw, after_seq, lifecycle, finalize, on_complete):
+    """Finalization errors/cancellation must not leave an immortal running job."""
+    store = await loop.ensure_store()
+    try:
+        return await _finish(loop, parent, sid, run, raw, after_seq, lifecycle, finalize, on_complete)
+    except BaseException as exc:
+        failed = {**raw, "status": "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed",
+                  "error": f"subagent finalization: {type(exc).__name__}: {exc}"}
+        try:
+            result = await _save_result(store, parent, sid, run, failed, after_seq, lifecycle)
+            _publish_completion(loop, parent, sid, result)
+            if not run.suppress_wake:
+                await loop.deliver(InboxItem(RESULT_PREFIX + completion_view(loop, result), kind="task_done",
+                                            item_id="subagent:" + run.run_id), parent, enqueue_only=True)
+                if on_complete is not None:
+                    await on_complete(parent, result)
+            return result
+        except Exception:
+            log.exception("subagent finalization failed; original records retained: %s", run.run_id)
+    finally:
+        if _RUNNING.get((id(store), sid)) is run:
+            _RUNNING.pop((id(store), sid), None)
+
+
+async def start(loop, spec: AgentSpec, task: str, *, on_complete=None, finalize=None,
+                admission: asyncio.Semaphore | None = None) -> dict[str, Any]:
+    parent = get_session_id()
+    if parent is None:
+        raise ValueError("spawn_agent requires an active parent session")
+    store = await loop.ensure_store()
+    parent_run = _RUNNING.get((id(store), parent))
+    ready = asyncio.get_running_loop().create_future()
+    run = Running(secrets.token_hex(8), token=CancellationToken(), parent=parent, title=spec.name)
+    if parent_run is not None:
+        run.token = parent_run.token.child()
+
+    admitted = False
+
+    async def created(sid):
+        nonlocal admitted
+        session = await store.get_session(sid)
+        run.projection_expected = session.config.get("context_projection", True)
+        _RUNNING[(id(store), sid)] = run
+        await store.set_runtime_state(parent, "subagent:child:" + sid,
+                                      {"deleted": False, "lifecycle": spec.lifecycle})
+        await store.set_runtime_state(parent, "subagent:run:" + run.run_id,
+                                      {"phase": "running", "session_id": sid, "run_id": run.run_id})
+        await store.merge_session_metadata(sid, {"standalone_subagent": True})
+        ready.set_result(sid)
+        if admission is not None:
+            run.phase = "queued"
+            await admission.acquire()
+            admitted = True
+            run.phase = "running"
+
+    async def execute():
+        token = _ON_CHILD_SESSION.set(created)
+        usage = _USAGE_SINK.set(None)
+        sid = None
+        try:
+            # Manager owns cleanup, after repair/projection/range collection.
+            raw = await run_agent_spec(replace(spec, lifecycle="linked", metadata={**spec.metadata, "managed_subagent": True}), task,
+                                       parent_loop=loop, stop_event=run.token)
+            sid = ready.result() if ready.done() and not ready.cancelled() else None
+            if sid is None:
+                raise ValueError(raw.get("final_text") or "child session was not created")
+        except BaseException as exc:
+            if not ready.done():
+                ready.set_exception(exc)
+                return
+            sid = ready.result()
+            raw = {"status": "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed",
+                   "final_text": "", "rounds": 0, "usage": {}, "error": str(exc)}
+        finally:
+            _ON_CHILD_SESSION.reset(token)
+            _USAGE_SINK.reset(usage)
+            if admitted:
+                admission.release()
+        await _complete(loop, parent, sid, run, raw, 0, spec.lifecycle, finalize, on_complete)
+
+    run.task = asyncio.create_task(execute(), name="subagent-" + run.run_id)
+    _retain(run.task)
+    sid = await asyncio.shield(ready)
+    return {"session_id": sid, "run_id": run.run_id, "mode": "create", "status": "queued"}
+
+
+async def nudge(loop, sid: str, message: str, *, on_complete=None, finalize=None,
+                admission: asyncio.Semaphore | None = None) -> dict[str, Any]:
+    parent = get_session_id()
+    if parent is None:
+        raise ValueError("nudge requires an active parent session")
+    store = await loop.ensure_store()
+    _, unavailable = await authorize(store, parent, sid)
+    if unavailable:
+        return {"status": "unavailable", "reason": unavailable, "session_id": sid}
+    row = await store.get_session(sid)
+    if not row.metadata.get("standalone_subagent"):
+        raise ValueError("not a standalone subagent; use the owning workflow's nudge")
+    # Build using the saved child contract and current parent policy, never the parent's full tools.
+    child_loop = await workflow_continuation_loop(loop, sid)
+    async with _gate(store, sid):
+        running = _RUNNING.get((id(store), sid))
+        if running is not None:
+            await child_loop.deliver(InboxItem(message, mode="steer"), sid, enqueue_only=True)
+            return {"session_id": sid, "run_id": running.run_id, "mode": "steer", "status": "accepted"}
+        if child_loop._lock_for(sid).locked():
+            raise ValueError("session is owned by another execution; nudge was not accepted")
+        record = await store.get_runtime_state(parent, "subagent:child:" + sid)
+        lifecycle = record.get("lifecycle", "linked")
+        before = await store.history_bounds(sid)
+        after_seq = before[1] if before else 0
+        run = Running(secrets.token_hex(8), token=CancellationToken(), parent=parent, title=str(row.metadata.get("spec_name") or "subagent"))
+        run.projection_expected = child_loop.config.projection_representation is not None
+        parent_run = _RUNNING.get((id(store), parent))
+        if parent_run is not None:
+            run.token = parent_run.token.child()
+        _RUNNING[(id(store), sid)] = run
+        await store.set_runtime_state(parent, "subagent:run:" + run.run_id,
+                                      {"phase": "queued", "session_id": sid, "run_id": run.run_id})
+
+        async def execute():
+            from power_loop.contracts.event_payloads import SubagentTaskStartPayload
+            from power_loop.contracts.events import AgentEventType
+            from power_loop.runtime.spec import _publish_subagent_event
+            from power_loop.workflow.engine import InProcessExecutor
+            _publish_subagent_event(loop, parent, AgentEventType.SUBAGENT_TASK_START,
+                                   SubagentTaskStartPayload(task=message, preset=run.title,
+                                                           sub_session_id=sid, depth=row.spawn_depth))
+            admitted = False
+            try:
+                if admission is not None:
+                    run.phase = "queued"
+                    await admission.acquire()
+                    admitted = True
+                run.phase = "running"
+                raw = await InProcessExecutor().continue_agent(
+                    sid, message, parent_loop=loop, extra_rounds=child_loop.config.max_rounds,
+                    stop_event=run.token)
+            except BaseException as exc:
+                raw = {"status": "cancelled" if isinstance(exc, asyncio.CancelledError) else "failed",
+                       "final_text": "", "rounds": 0, "usage": {}, "error": str(exc)}
+            finally:
+                if admitted:
+                    admission.release()
+            await _complete(loop, parent, sid, run, raw, after_seq, lifecycle, finalize, on_complete)
+
+        run.task = asyncio.create_task(execute(), name="subagent-" + run.run_id)
+        _retain(run.task)
+        return {"session_id": sid, "run_id": run.run_id, "mode": "continue", "status": "queued"}
+
+
+def result_view(text: str, cap: int = 600) -> str | None:
+    """Tool-context rule: only final_text may change, never envelope metadata."""
+    import json
+    try:
+        value = json.loads(text)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(value, dict) or "session_id" not in value or not value.get("run_id"):
+        return None
+    if isinstance(value.get("final_text"), str) and len(value["final_text"]) > cap:
+        value["final_text"] = value["final_text"][:max(0, cap)] + "…[truncated]"
+    return dumps(value)
+
+
+def running_jobs(store, parent):
+    return [{"id": "sub:" + run.run_id, "kind": "subagent", "title": run.title,
+             "status": run.phase, "session_id": sid, "started_at": None, "origin": ""}
+            for (key, sid), run in _RUNNING.items() if key == id(store) and run.parent == parent]
+
+
+async def stop(store, parent, run_id, grace_s):
+    run = next((run for (key, _), run in _RUNNING.items()
+                if key == id(store) and run.parent == parent and run.run_id == run_id), None)
+    if run is None:
+        return "finished"
+    run.suppress_wake = True
+    run.token.cancel("stopped")
+    try:
+        await asyncio.wait_for(asyncio.shield(run.task), timeout=grace_s)
+        return "stopped"
+    except TimeoutError:
+        run.task.cancel()
+        return "forced"
+
+
+async def await_children(store, parent, stop_event=None, timeout_s=1800):
+    """Owning executors must collect asynchronous descendants before settling a leaf."""
+    deadline = asyncio.get_running_loop().time() + timeout_s
+    token = CancellationToken.from_any(stop_event)
+    while True:
+        runs = [run for (key, _), run in _RUNNING.items()
+                if key == id(store) and run.parent == parent and run.task is not None]
+        if not runs:
+            return
+        if token.is_cancelled():
+            for run in runs:
+                run.token.cancel("parent cancelled")
+            raise ValueError("cancelled while waiting for subagents")
+        if asyncio.get_running_loop().time() >= deadline:
+            raise ValueError("subagents still pending after completion wait")
+        await asyncio.wait([run.task for run in runs], timeout=0.1)
+
+
+def completion_view(loop, result):
+    config = getattr(loop, "config", None)
+    policy = getattr(config, "tool_context", None)
+    projection = getattr(getattr(config, "representation", None), "projection_cfg", {}) or {}
+    overrides = getattr(policy, "overrides", {}) or {}
+    cap = overrides.get("spawn_agent", {}).get("result_max_chars") or projection.get("final_text_cap") or 600
+    return result_view(dumps(result), int(cap))
+
+
+def _publish_completion(loop, parent, sid, result):
+    from power_loop.contracts.event_payloads import SubagentCompletedPayload, SubagentTextPayload
+    from power_loop.contracts.events import AgentEventType
+    from power_loop.runtime.spec import _publish_subagent_event
+    status = str(result.get("status") or "failed")
+    fields = {"sub_session_id": sid, "status": status, "rounds": int(result.get("rounds") or 0),
+              "final_text": str(result.get("final_text") or "")}
+    if status == "completed":
+        _publish_subagent_event(loop, parent, AgentEventType.SUBAGENT_TEXT, SubagentTextPayload(**fields))
+    _publish_subagent_event(loop, parent, AgentEventType.SUBAGENT_COMPLETED, SubagentCompletedPayload(**fields))