power-loop 0.2.0__py3-none-any.whl

power_loop/core/runner.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager, contextmanager
+
+from power_loop.core.agent_context import (
+    reset_ctx,
+    reset_event_bus,
+    reset_hooks,
+    reset_session_id,
+    set_ctx,
+    set_event_bus,
+    set_hooks,
+    set_session_id,
+)
+from power_loop.core.events import DEFAULT_EVENT_BUS, AgentEventBus
+from power_loop.core.hooks import DEFAULT_HOOKS, AgentHooks
+from power_loop.core.state import ContextManager
+
+
+class AgentRunner:
+    """Runner provides per-session isolation for event bus / hooks / state."""
+
+    def __init__(
+        self,
+        *,
+        event_bus: AgentEventBus | None = None,
+        hooks: AgentHooks | None = None,
+    ) -> None:
+        self.event_bus = event_bus if event_bus is not None else DEFAULT_EVENT_BUS
+        self.hooks = hooks if hooks is not None else DEFAULT_HOOKS
+
+    @contextmanager
+    def session(self, *, session_id: str | None = None) -> Iterator[AgentRunner]:
+        tok_bus = set_event_bus(self.event_bus)
+        tok_hooks = set_hooks(self.hooks)
+        tok_ctx = set_ctx(ContextManager(role="main"))
+        tok_sid = set_session_id(session_id)
+        try:
+            yield self
+        finally:
+            reset_session_id(tok_sid)
+            reset_ctx(tok_ctx)
+            reset_hooks(tok_hooks)
+            reset_event_bus(tok_bus)
+
+    @asynccontextmanager
+    async def session_async(self, *, session_id: str | None = None) -> AsyncIterator[AgentRunner]:
+        tok_bus = set_event_bus(self.event_bus)
+        tok_hooks = set_hooks(self.hooks)
+        tok_ctx = set_ctx(ContextManager(role="main"))
+        tok_sid = set_session_id(session_id)
+        try:
+            yield self
+        finally:
+            reset_session_id(tok_sid)
+            reset_ctx(tok_ctx)
+            reset_hooks(tok_hooks)
+            reset_event_bus(tok_bus)
+

power_loop/core/state.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from llm_client.interface import LLMResponse
+from power_loop.contracts.event_payloads import TodoUpdatedPayload
+from power_loop.contracts.events import AgentEvent, AgentEventType
+from power_loop.core.agent_context import get_event_bus, get_session_id
+from power_loop.runtime.env import AGENT_DIR
+from power_loop.runtime.skills import get_default_loader
+
+TOOL_MAX_LINES = 20
+
+
+class TodoManager:
+    def __init__(self) -> None:
+        self.items: list[dict[str, Any]] = []
+
+    def update(self, items: list[dict[str, Any]]) -> str:
+        if len(items) > 20:
+            raise ValueError("Max 20 todos allowed")
+
+        validated: list[dict[str, Any]] = []
+        in_progress_count = 0
+        for i, item in enumerate(items):
+            text = str(item.get("text", "")).strip()
+            status = str(item.get("status", "pending")).lower()
+            item_id = str(item.get("id", str(i + 1)))
+            if not text:
+                raise ValueError(f"Item {item_id}: text required")
+            if status not in ("pending", "in_progress", "completed"):
+                raise ValueError(f"Item {item_id}: invalid status '{status}'")
+            if status == "in_progress":
+                in_progress_count += 1
+            validated.append({"id": item_id, "text": text, "status": status})
+
+        if in_progress_count > 1:
+            raise ValueError("Only one task can be in_progress at a time")
+
+        self.items = validated
+        result = self.render()
+        done = sum(1 for t in self.items if t["status"] == "completed")
+
+        # Publish todo state for any UI subscriber.
+        session_id = get_session_id()
+        get_event_bus().publish(
+            AgentEvent(
+                type=AgentEventType.TODO_UPDATED,
+                data=TodoUpdatedPayload(
+                    items=[dict(x) for x in self.items],
+                    counts={"total": len(self.items), "completed": done},
+                    rendered=result,
+                    text=result,
+                ),
+                session_id=session_id,
+            )
+        )
+        return result
+
+    def render(self) -> str:
+        if not self.items:
+            return "No todos."
+        lines: list[str] = []
+        for item in self.items:
+            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}[item["status"]]
+            lines.append(f"{marker} #{item['id']}: {item['text']}")
+        done = sum(1 for t in self.items if t["status"] == "completed")
+        lines.append(f"\n({done}/{len(self.items)} completed)")
+        return "\n".join(lines)
+
+    def snapshot_for_prompt(self) -> str:
+        if not self.items:
+            return ""
+        return f"\n<current_todos>\n{self.render()}\n</current_todos>"
+
+    @property
+    def has_in_progress(self) -> bool:
+        return any(item["status"] == "in_progress" for item in self.items)
+
+
+@dataclass
+class ContextManager:
+    """Per-session agent context: usage tracking + microcompact + todo state.
+
+    LLM-summary compaction lives in :mod:`power_loop.runtime.compact`
+    (configured via ``AgentLoopConfig.compactor``). This class only owns
+    the orthogonal "spill large tool outputs to disk" path and the
+    telemetry-friendly :meth:`update_usage` parser.
+    """
+
+    role: str = "main"
+    recent_files: list[str] = field(default_factory=list)
+    _file_counter: int = 0
+
+    token_usage: dict[str, Any] = field(default_factory=dict)
+    #: 可选计数器，供测试/扩展使用；**不会**被 ``update_usage`` 自动递增
+    api_calls: int = 0
+
+    subagent_records: list[dict[str, Any]] = field(default_factory=list)
+
+    todo: TodoManager = field(default_factory=TodoManager)
+
+    # Microcompact (large tool-output spill-to-disk) config — orthogonal to
+    # the LLM-summary Compactor in runtime/compact.py.
+    micro_hot_tail: int = field(default_factory=lambda: int(os.getenv("CONTEXT_MICRO_HOT_TAIL", "10")))
+    micro_size_limit: int = field(default_factory=lambda: int(os.getenv("CONTEXT_MICRO_SIZE_LIMIT", "1000")))
+
+    cache_dir: Path = field(default_factory=lambda: (AGENT_DIR / ".cache"))
+
+    def __post_init__(self) -> None:
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        # Ensure skills loader reads from correct runtime env.
+        _ = get_default_loader()
+
+    def track_file(self, path: str) -> None:
+        if not path:
+            return
+        if path in self.recent_files:
+            self.recent_files.remove(path)
+        self.recent_files.append(path)
+        self.recent_files = self.recent_files[-5:]
+
+    def update_usage(self, response: LLMResponse) -> dict[str, int]:
+        usage = None
+        if getattr(response, "token_usage", None) is not None:
+            tu = response.token_usage
+            usage = tu.as_dict() if hasattr(tu, "as_dict") else None
+
+        def _pick(dct: dict, keys: list[str]) -> int:
+            for key in keys:
+                val = dct.get(key)
+                if isinstance(val, (int, float)) and val is not None:
+                    return int(val)
+            return 0
+
+        input_tokens = 0
+        output_tokens = 0
+        cache_read = 0
+        reasoning = 0
+        total_tokens = 0
+
+        if isinstance(usage, dict):
+            input_tokens = _pick(usage, ["prompt_tokens", "input_tokens"])
+            output_tokens = _pick(usage, ["completion_tokens", "output_tokens"])
+            cache_read = _pick(
+                usage,
+                [
+                    "cache_read_input_tokens",
+                    "cache_read_tokens",
+                    "cached_tokens",
+                    "cache_hit_tokens",
+                    "prompt_cached_tokens",
+                ],
+            )
+            reasoning = _pick(usage, ["completion_reasoning_tokens", "reasoning_tokens"])
+            total_tokens = _pick(usage, ["total_tokens"])
+
+        usage_out: dict[str, int] = {
+            "prompt_tokens": input_tokens,
+            "completion_tokens": output_tokens,
+            "cache_read_tokens": cache_read,
+            "reasoning_tokens": reasoning,
+            "total_tokens": total_tokens,
+            # 与常见 OpenAI usage 字段对齐的别名
+            "input": input_tokens,
+            "output": output_tokens,
+            "cache_read": cache_read,
+            "reasoning": reasoning,
+        }
+        self.token_usage = usage_out
+        return usage_out
+
+    def microcompact(self, messages: list[dict[str, Any]]) -> None:
+        # Keep hot tail tool outputs; summarize/cached replace for old tool outputs.
+        tool_output_indices: list[int] = []
+        for i, msg in enumerate(messages):
+            if msg.get("role") == "tool":
+                content = msg.get("content", "")
+                if isinstance(content, str) and len(content) > self.micro_size_limit:
+                    tool_output_indices.append(i)
+
+        if len(tool_output_indices) <= self.micro_hot_tail:
+            return
+
+        cold = tool_output_indices[:-self.micro_hot_tail]
+        for i in cold:
+            msg = messages[i]
+            content = msg.get("content", "")
+            if not isinstance(content, str):
+                continue
+            if content.startswith("[tool output saved to"):
+                continue
+            self._file_counter += 1
+            cache_path = self.cache_dir / f"tool_{self._file_counter:05d}.md"
+            tool_name = str(msg.get("name") or "tool")
+            tool_id = str(msg.get("tool_call_id") or "")
+            md = (
+                f"# Tool Call: {tool_name}\n\n"
+                f"**ID**: `{tool_id}`\n\n"
+                f"**Output** ({len(content)} chars):\n\n"
+                f"{content}\n"
+            )
+            cache_path.write_text(md, encoding="utf-8")
+            replaced = f"[tool output saved to {cache_path.relative_to(AGENT_DIR)}, {tool_name}, {len(content)} chars]"
+            msg["content"] = replaced

power_loop/runtime/budget.py

@@ -0,0 +1,179 @@
+"""Token budgeting utilities — heuristic, vendor-neutral.
+
+These are deliberately approximate: we want a single number that's cheap to
+compute, monotonic with content size, and works without a tokenizer
+dependency. Used by the compactor to decide *when* to trigger; not used for
+billing.
+
+Rule of thumb: ~4 chars per token for English-heavy LLM transcripts. Adjust
+via :data:`CHARS_PER_TOKEN` if needed.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+CHARS_PER_TOKEN = 4
+"""Approximate chars-per-token used by :func:`estimate_tokens`."""
+
+
+def estimate_text_tokens(text: str | None) -> int:
+    if not text:
+        return 0
+    return max(1, len(text) // CHARS_PER_TOKEN)
+
+
+def estimate_message_tokens(message: dict[str, Any]) -> int:
+    """Heuristic token count for a single message dict.
+
+    Counts content (string or JSON-serialized non-string), tool_calls
+    arguments, name fields, and a small per-message overhead for the role
+    framing.
+    """
+    overhead = 4  # role tag + delimiters
+    content = message.get("content")
+    if isinstance(content, str):
+        body = content
+    elif content is None:
+        body = ""
+    else:
+        body = json.dumps(content, ensure_ascii=False)
+    tool_calls = message.get("tool_calls") or []
+    if tool_calls:
+        body += json.dumps(tool_calls, ensure_ascii=False)
+    name = message.get("name") or ""
+    return overhead + estimate_text_tokens(body) + estimate_text_tokens(name)
+
+
+def estimate_tokens(messages: list[dict[str, Any]]) -> int:
+    return sum(estimate_message_tokens(m) for m in messages)
+
+
+def trim_history(
+    messages: list[dict[str, Any]],
+    max_tokens: int,
+    *,
+    keep_system: bool = True,
+    keep_last_n: int = 2,
+) -> list[dict[str, Any]]:
+    """Drop messages from the middle until the token budget fits.
+
+    Used by callers that want to cap context before calling the LLM
+    directly (without the full compactor pipeline). This is a **pure
+    trim** — no summarisation, no LLM calls. For LLM-backed summary
+    compaction, use :class:`power_loop.runtime.compact.DefaultCompactor`.
+
+    Preserves:
+    * All ``role=system`` messages at the front (when ``keep_system=True``).
+    * The last ``keep_last_n`` exchanges (user-bounded). An exchange is
+      a ``user`` message followed by everything up to (but not including)
+      the next ``user`` — so ``assistant(tool_calls) ↔ tool`` pairs stay
+      together.
+    * The ``assistant(tool_calls)`` ↔ ``tool`` atomic pair near the cut
+      boundary: if the first removed message is a ``tool``, we walk back
+      to include the preceding ``assistant(tool_calls)`` so the protocol
+      isn't broken.
+
+    Returns a new list (does not mutate the input). If the budget
+    already fits, the original list is returned unchanged.
+    """
+    if not messages or max_tokens <= 0:
+        return []
+
+    if estimate_tokens(messages) <= max_tokens:
+        return list(messages)
+
+    # Partition: leading system block, body, tail.
+    n = len(messages)
+    sys_end = 0
+    if keep_system:
+        while sys_end < n and messages[sys_end].get("role") == "system":
+            sys_end += 1
+
+    # Find tail exchanges (keep_last_n) by walking backwards from the end.
+    exchanges = 0
+    tail_start = n
+    for i in range(n - 1, sys_end - 1, -1):
+        if messages[i].get("role") == "user":
+            exchanges += 1
+            if exchanges >= keep_last_n:
+                tail_start = i
+                break
+    else:
+        tail_start = sys_end  # not enough exchanges — keep everything after system
+
+    # Walk the cut boundary forward to preserve tool_calls ↔ tool atomicity.
+    # If the first message we'd drop is a ``tool``, extend the tail back
+    # until we include the preceding ``assistant(tool_calls)``.
+    while tail_start > sys_end and messages[tail_start - 1].get("role") == "tool" \
+            and messages[tail_start - 1].get("tool_call_id"):
+        # Walk back to find the matching assistant(tool_calls).
+        tid = messages[tail_start - 1].get("tool_call_id")
+        extended = tail_start - 1
+        while extended > sys_end:
+            extended -= 1
+            role = messages[extended].get("role")
+            if role == "assistant" and messages[extended].get("tool_calls"):
+                # Check if any of its tool_calls match this tool_call_id.
+                tcs = messages[extended].get("tool_calls") or []
+                if any(tc.get("id") == tid for tc in tcs):
+                    tail_start = extended
+                    break
+            elif role == "user":
+                # We hit a user boundary without finding the pair — stop.
+                break
+        else:
+            break  # safety: cannot find pair, stop extending
+
+    # Build result: system + trimmed body + tail.
+    budget_tail = estimate_tokens(messages[tail_start:])
+    remaining = max_tokens - budget_tail
+    system_tokens = estimate_tokens(messages[:sys_end])
+    body_budget = remaining - system_tokens
+
+    if body_budget < 0:
+        # Can't even fit system + tail. Degrade: drop system, keep only tail.
+        if estimate_tokens(messages[tail_start:]) > max_tokens:
+            # Tail alone exceeds budget — last resort: trim from tail end too.
+            result: list[dict[str, Any]] = []
+            spent = 0
+            orphan_tool_ids: set[str] = set()  # tool msgs in result whose assistant is not yet in
+            for m in reversed(messages[tail_start:]):
+                cost = estimate_message_tokens(m)
+                tid = m.get("tool_call_id") or ""
+                if spent + cost > max_tokens:
+                    # Atomicity: if this is an assistant(tool_calls) whose
+                    # tool msg is already in the result, include it anyway.
+                    if m.get("role") == "assistant" and m.get("tool_calls"):
+                        tcs = m.get("tool_calls") or []
+                        if any(tc.get("id") in orphan_tool_ids for tc in tcs):
+                            result.insert(0, m)
+                            spent += cost
+                    # Also: tool message whose assistant is not yet in result
+                    # — skip it (will be pulled in by the assistant if it fits).
+                    elif m.get("role") == "tool" and tid:
+                        pass  # leave orphan_tool_ids entry; don't advance
+                    break
+                result.insert(0, m)
+                spent += cost
+                if m.get("role") == "assistant" and m.get("tool_calls"):
+                    for tc in (m.get("tool_calls") or []):
+                        orphan_tool_ids.discard(tc.get("id") or "")
+                elif m.get("role") == "tool" and tid:
+                    orphan_tool_ids.add(tid)
+            return result
+        return list(messages[tail_start:])
+
+    # Take body messages from index sys_end to tail_start, keep as many
+    # from the front as fit.
+    body: list[dict[str, Any]] = []
+    spent = system_tokens
+    for i in range(sys_end, tail_start):
+        cost = estimate_message_tokens(messages[i])
+        if spent + cost > max_tokens - budget_tail:
+            break
+        body.append(messages[i])
+        spent += cost
+
+    return list(messages[:sys_end]) + body + list(messages[tail_start:])

power_loop/runtime/cancellation.py

@@ -0,0 +1,127 @@
+"""Unified cancellation primitive for power-loop.
+
+Why
+---
+Pipelines and tool handlers come from many places — sync threads, asyncio
+tasks, hook callbacks. Different callers naturally hold different "cancel
+signals":
+
+* a long-running CLI may use ``threading.Event``;
+* an asyncio server may use ``asyncio.Event``;
+* a UI framework may expose only ``is_cancelled()`` as a callable.
+
+``CancellationToken`` is the **one shape** the pipeline checks. Callers pass
+whatever they have; ``from_any`` lifts it into a token. There is also a
+plain "owned" token (``CancellationToken()``) that callers can ``cancel()``
+themselves — used by hook ``HookDirective.CANCEL`` (M1.5) and by
+``StatefulAgentLoop.cancel(sid)``-style helpers.
+
+The token is **read-only from the pipeline's side**: it never *creates*
+cancellation, only observes it. The only mutating method, ``cancel()``,
+is for callers that explicitly created an owned token.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Callable
+from typing import Union
+
+from power_loop.contracts.errors import CancellationRequested
+
+# What callers may hand us. ``None`` means "no cancellation".
+CancellationLike = Union["CancellationToken", asyncio.Event, threading.Event, Callable[[], bool], None]
+
+
+class CancellationToken:
+    """Observable cancellation flag.
+
+    Construct it three ways:
+
+    * ``CancellationToken()`` — owned; flip with ``cancel()``.
+    * ``CancellationToken.from_any(obj)`` — wrap an existing event / callable.
+    * ``CancellationToken.never()`` — sentinel that is never cancelled
+      (sugar for "the caller passed None").
+    """
+
+    __slots__ = ("_check", "_reason", "_owned_event")
+
+    def __init__(self, *, _check: Callable[[], bool] | None = None) -> None:
+        # Owned mode: a private threading.Event so ``cancel()`` works and
+        # waiters relying on Event semantics keep working.
+        self._owned_event = threading.Event()
+        if _check is None:
+            self._check = self._owned_event.is_set
+        else:
+            self._check = _check
+        self._reason: str = "cancelled"
+
+    # ── Factories ───────────────────────────────────────────────────────
+
+    @classmethod
+    def from_any(cls, source: CancellationLike) -> CancellationToken:
+        """Lift any cancel-like object into a token. ``None`` → ``never()``."""
+        if source is None:
+            return cls.never()
+        if isinstance(source, CancellationToken):
+            return source
+        if isinstance(source, threading.Event):
+            tok = cls.__new__(cls)
+            tok._owned_event = source
+            tok._check = source.is_set
+            tok._reason = "cancelled"
+            return tok
+        if isinstance(source, asyncio.Event):
+            tok = cls.__new__(cls)
+            tok._owned_event = threading.Event()  # unused, kept for shape
+            tok._check = source.is_set
+            tok._reason = "cancelled"
+            return tok
+        if callable(source):
+            tok = cls.__new__(cls)
+            tok._owned_event = threading.Event()
+            tok._check = source
+            tok._reason = "cancelled"
+            return tok
+        raise TypeError(
+            f"CancellationToken.from_any: unsupported source type {type(source).__name__}"
+        )
+
+    @classmethod
+    def never(cls) -> CancellationToken:
+        """Sentinel token that is never cancelled."""
+        tok = cls.__new__(cls)
+        tok._owned_event = threading.Event()
+        tok._check = lambda: False
+        tok._reason = "cancelled"
+        return tok
+
+    # ── Observation ─────────────────────────────────────────────────────
+
+    def is_cancelled(self) -> bool:
+        try:
+            return bool(self._check())
+        except Exception:
+            # A user-supplied callable that raises is treated as "not cancelled"
+            # rather than corrupting loop control flow. Errors in cancellation
+            # checks should never abort the loop.
+            return False
+
+    def raise_if_cancelled(self) -> None:
+        if self.is_cancelled():
+            raise CancellationRequested(self._reason)
+
+    # ── Mutation (owned tokens only) ────────────────────────────────────
+
+    def cancel(self, reason: str = "cancelled") -> None:
+        """Flip an owned token. No-op (and safe) on wrapped tokens whose
+        underlying source isn't an Event we own — the underlying source is
+        the canonical signal there."""
+        self._reason = reason
+        # We only know how to flip the owned threading.Event. Wrapped
+        # asyncio.Event / callable sources must be flipped by their owner.
+        self._owned_event.set()
+
+
+__all__ = ["CancellationToken", "CancellationLike"]