power-loop 0.2.0__py3-none-any.whl

power_loop/contracts/errors.py

@@ -0,0 +1,140 @@
+"""Public error hierarchy for power-loop.
+
+All errors raised by the library inherit from :class:`PowerLoopError` so
+callers can ``except PowerLoopError`` as a single catch-all.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class PowerLoopError(Exception):
+    """Base for all power-loop raised exceptions."""
+
+
+class SessionNotFoundError(PowerLoopError):
+    """Raised when a ``session_id`` does not exist in the store."""
+
+    def __init__(self, session_id: str) -> None:
+        super().__init__(f"session not found: {session_id}")
+        self.session_id = session_id
+
+
+class SessionPendingError(PowerLoopError):
+    """Raised when a session has unresolved tool_calls from a previous run.
+
+    The previous loop crashed (or was killed) after the assistant emitted
+    ``tool_calls`` but before all matching ``tool`` messages were appended.
+    The OpenAI/Anthropic message protocol forbids us from sending the next
+    LLM request in this state. The caller must explicitly choose:
+
+      * ``StatefulAgentLoop.resume(sid)`` — finish executing the pending
+        tool_calls and continue the loop, or
+      * ``StatefulAgentLoop.abort_pending(sid)`` — append synthetic
+        ``<aborted>`` tool messages, restoring protocol validity, then
+        proceed with the new user input.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        assistant_seq: int,
+        pending_tool_calls: list[dict[str, Any]],
+    ) -> None:
+        self.session_id = session_id
+        self.assistant_seq = assistant_seq
+        self.pending_tool_calls = pending_tool_calls
+        names = ",".join(
+            str((tc.get("function") or {}).get("name") or tc.get("name") or "?")
+            for tc in pending_tool_calls
+        )
+        super().__init__(
+            f"session {session_id} has {len(pending_tool_calls)} unresolved tool_calls"
+            f" from round (assistant_seq={assistant_seq}): {names}"
+        )
+
+
+class LLMTimeout(PowerLoopError):
+    """Raised when an LLM call (or a sequence of retries) exceeds ``total_timeout``.
+
+    ``elapsed`` is the wall-clock seconds spent since the policy started
+    counting (before the timeout fired). ``attempts`` is how many physical
+    LLM calls were made before giving up.
+    """
+
+    def __init__(self, *, elapsed: float, attempts: int, total_timeout: float) -> None:
+        self.elapsed = elapsed
+        self.attempts = attempts
+        self.total_timeout = total_timeout
+        super().__init__(
+            f"LLM call timed out after {elapsed:.2f}s "
+            f"(total_timeout={total_timeout:.2f}s, attempts={attempts})"
+        )
+
+
+class LLMRetryExhausted(PowerLoopError):
+    """Raised when ``LLMRetryPolicy.max_attempts`` is reached without success.
+
+    ``last_error`` is the exception raised by the most recent attempt — the
+    direct cause of the give-up. Always set as ``__cause__`` via ``raise from``.
+    """
+
+    def __init__(self, *, attempts: int, last_error: BaseException) -> None:
+        self.attempts = attempts
+        self.last_error = last_error
+        super().__init__(
+            f"LLM retry exhausted after {attempts} attempt(s); "
+            f"last error: {type(last_error).__name__}: {last_error}"
+        )
+
+
+class CancellationRequested(PowerLoopError):
+    """Raised when a ``CancellationToken`` fires while the loop is awaiting work.
+
+    This is a controlled, expected exit path — callers cancelling via
+    ``stop_event.set()`` / ``token.cancel()`` / ``HookDirective.CANCEL`` should
+    catch it (or let ``StatefulAgentLoop`` translate it to a ``cancelled``
+    result for them).
+    """
+
+    def __init__(self, reason: str = "cancelled") -> None:
+        self.reason = reason
+        super().__init__(reason)
+
+
+class CompactionFailed(PowerLoopError):
+    """Reserved for the compactor's hard-fail path (M2.5). Soft fail today
+    still emits ``compact.failed`` event and continues — this exception is
+    only raised when the loop must be aborted because the un-compacted
+    history blew the context window."""
+
+
+class ToolNotFound(PowerLoopError):
+    """Raised when a tool name is not registered in the :class:`ToolRegistry`."""
+
+    def __init__(self, tool_name: str) -> None:
+        self.tool_name = tool_name
+        super().__init__(f"tool not found: {tool_name}")
+
+
+class ToolValidationError(PowerLoopError):
+    """Raised when tool arguments fail schema / required-param validation."""
+
+    def __init__(self, tool_name: str, message: str) -> None:
+        self.tool_name = tool_name
+        self.message = message
+        super().__init__(f"tool {tool_name!r}: {message}")
+
+
+class SpecValidationError(PowerLoopError):
+    """Raised when an :class:`~power_loop.runtime.spec.AgentSpec` fails validation.
+
+    Replaces the previous ``AgentSpecError(ValueError)``. ``field`` is the
+    spec key that caused the failure (or ``None`` for a general error).
+    """
+
+    def __init__(self, message: str, *, field: str | None = None) -> None:
+        self.field = field
+        super().__init__(message)

power_loop/contracts/event_payloads.py

@@ -0,0 +1,278 @@
+"""Typed event payload dataclasses — one per AgentEventType.
+
+Each dataclass declares the exact fields an event subscriber receives,
+replacing the untyped ``AgentEvent.payload`` dict.  Subscribers can
+access fields directly with IDE auto-completion and type checking.
+
+Legacy dict-based access is preserved via :meth:`BaseEventPayload.to_dict`
+and the ``AgentEvent.payload`` property for backward compatibility.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# ── Base ──
+
+
+@dataclass
+class BaseEventPayload:
+    """Common base for all event payloads.
+
+    Provides :meth:`to_dict` for backward-compatible dict serialization.
+    """
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for k, v in self.__dict__.items():
+            if not k.startswith("_"):
+                result[k] = v
+        return result
+
+
+# ── Session ──
+
+
+@dataclass
+class LlmRetryAttemptedPayload(BaseEventPayload):
+    """Emitted after each *failed* LLM attempt that will be retried.
+
+    ``attempt`` is the 0-based index of the attempt that **just failed**;
+    ``next_sleep_seconds`` is what the policy will sleep before the next
+    attempt (capped by remaining deadline).
+    """
+    attempt: int = 0
+    max_attempts: int = 0
+    error_type: str = ""
+    error_message: str = ""
+    next_sleep_seconds: float = 0.0
+
+
+@dataclass
+class LlmDegradedPayload(BaseEventPayload):
+    """Emitted when the loop gives up on the LLM (retry exhausted or
+    total_timeout) and proceeds with status=``degraded``."""
+    reason: str = ""           # "retry_exhausted" | "timeout"
+    attempts: int = 0
+    error_type: str = ""
+    error_message: str = ""
+
+
+@dataclass
+class LoopCancelledPayload(BaseEventPayload):
+    """Emitted when the loop terminates because a CancellationToken fired."""
+    reason: str = "cancelled"
+    round_index: int | None = None
+
+
+@dataclass
+class MemoryRecalledPayload(BaseEventPayload):
+    """Emitted after a MemoryProvider.recall() call.
+
+    ``injected`` is the number actually placed into ``messages`` (after
+    the MEMORY_RECALLED hook had a chance to filter/skip). ``returned``
+    is what the provider gave us before hook filtering.
+    """
+    returned: int = 0
+    injected: int = 0
+    budget_tokens: int = 0
+
+
+@dataclass
+class MemoryFailedPayload(BaseEventPayload):
+    """Emitted when recall() or remember() raises.
+
+    The loop continues regardless — memory is best-effort. ``phase`` is
+    ``"recall"`` or ``"remember"`` so subscribers know which side broke.
+    """
+    phase: str = ""
+    error_type: str = ""
+    error_message: str = ""
+
+
+@dataclass
+class SessionStartedPayload(BaseEventPayload):
+    scope: str = "main"
+
+
+@dataclass
+class SessionEndedPayload(BaseEventPayload):
+    reason: str = ""
+
+
+# ── Round ──
+
+
+@dataclass
+class RoundStartedPayload(BaseEventPayload):
+    round_index: int = 0
+
+
+@dataclass
+class RoundCompletedPayload(BaseEventPayload):
+    round_index: int = 0
+    has_tools: bool = False
+    used_todo: bool = False
+
+
+@dataclass
+class RoundToolsPresentPayload(BaseEventPayload):
+    has_tools: bool = False
+
+
+# ── Stream ──
+
+
+@dataclass
+class StreamStartedPayload(BaseEventPayload):
+    stream_id: str = "main"
+
+
+@dataclass
+class StreamDeltaPayload(BaseEventPayload):
+    stream_id: str = "main"
+    text: str = ""
+    is_think: bool = False
+
+
+@dataclass
+class StreamCompletedPayload(BaseEventPayload):
+    stream_id: str = "main"
+
+
+# ── Tool ──
+
+
+@dataclass
+class ToolCallStartedPayload(BaseEventPayload):
+    name: str = ""
+    tool_input: dict[str, Any] = field(default_factory=dict)
+    tool_call_id: str = ""
+
+
+@dataclass
+class ToolCallCompletedPayload(BaseEventPayload):
+    name: str = ""
+    output: str = ""
+    tool_input: dict[str, Any] = field(default_factory=dict)
+    tool_call_id: str = ""
+
+
+@dataclass
+class ToolCallFailedPayload(BaseEventPayload):
+    name: str = ""
+    output: str = ""
+    tool_input: dict[str, Any] = field(default_factory=dict)
+    tool_call_id: str = ""
+
+
+# ── Status ──
+
+
+@dataclass
+class StatusChangedPayload(BaseEventPayload):
+    """Polymorphic status payload, discriminated by ``kind``."""
+    kind: str = ""
+
+
+@dataclass
+class AutoCompactStatusPayload(StatusChangedPayload):
+    kind: str = "auto_compact"
+    phase: str = ""
+    round_index: int = 0
+    trigger: str = ""
+    before_tokens: int = 0
+    after_tokens: int = 0
+
+
+@dataclass
+class RoundUsageStatusPayload(StatusChangedPayload):
+    kind: str = "round_usage"
+    time_iso: str = ""
+    round_index: int = 0
+    round_number: int = 0
+    max_rounds: int = 0
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    reasoning_tokens: int | None = None
+
+
+@dataclass
+class HitRoundLimitStatusPayload(StatusChangedPayload):
+    kind: str = "hit_round_limit"
+    max_rounds: int = 0
+
+
+# ── Usage ──
+
+
+@dataclass
+class UsageUpdatedPayload(BaseEventPayload):
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+# ── Todo ──
+
+
+@dataclass
+class TodoUpdatedPayload(BaseEventPayload):
+    kind: str = "todo_snapshot"
+    items: list[dict[str, Any]] = field(default_factory=list)
+    counts: dict[str, int] = field(default_factory=dict)
+    rendered: str = ""
+    text: str = ""
+
+
+# ── Notification / Log ──
+
+
+@dataclass
+class UserNotificationPayload(BaseEventPayload):
+    message: str = ""
+
+
+@dataclass
+class AgentErrorPayload(BaseEventPayload):
+    error: str = ""
+    error_type: str = ""
+    details: str = ""
+
+
+@dataclass
+class SystemLogPayload(BaseEventPayload):
+    message: str = ""
+    level: str = "info"
+
+
+# ── Subagent ──
+
+
+@dataclass
+class SubagentTaskStartPayload(BaseEventPayload):
+    task: str = ""
+    preset: str = "core"
+    sub_session_id: str = ""
+    depth: int = 0
+
+
+@dataclass
+class SubagentTextPayload(BaseEventPayload):
+    sub_session_id: str = ""
+    status: str = ""
+    rounds: int = 0
+    final_text: str = ""
+
+
+@dataclass
+class SubagentLimitPayload(BaseEventPayload):
+    sub_session_id: str = ""
+    max_rounds: int = 0
+
+
+@dataclass
+class SubagentCompletedPayload(BaseEventPayload):
+    sub_session_id: str = ""
+    status: str = ""
+    rounds: int = 0
+    final_text: str = ""

power_loop/contracts/events.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from power_loop.contracts.event_payloads import BaseEventPayload
+
+
+class AgentEventType(str, Enum):
+    # Session lifecycle
+    SESSION_STARTED = "session_started"
+    SESSION_ENDED = "session_ended"
+
+    # Round lifecycle
+    ROUND_STARTED = "round_started"
+    ROUND_COMPLETED = "round_completed"
+    ROUND_TOOLS_PRESENT = "round_tools_present"
+
+    # LLM retry / cancellation lifecycle
+    LLM_RETRY_ATTEMPTED = "llm_retry_attempted"
+    LLM_DEGRADED = "llm_degraded"
+    LOOP_CANCELLED = "loop_cancelled"
+
+    # Memory lifecycle (M1.9)
+    MEMORY_RECALLED = "memory_recalled"
+    MEMORY_FAILED = "memory_failed"
+
+    # Streaming lifecycle
+    STREAM_STARTED = "stream_started"
+    STREAM_DELTA = "stream_delta"
+    STREAM_THINK_DELTA = "stream_think_delta"
+    STREAM_COMPLETED = "stream_completed"
+
+    # Tool lifecycle
+    TOOL_CALL_STARTED = "tool_call_started"
+    TOOL_CALL_COMPLETED = "tool_call_completed"
+    TOOL_CALL_FAILED = "tool_call_failed"
+
+    # Status and usage
+    STATUS_CHANGED = "status_changed"
+    USAGE_UPDATED = "usage_updated"
+
+    # Task list / planner (optional feature, used when todo tool is enabled)
+    TODO_UPDATED = "todo_updated"
+
+    # System and user-facing notifications
+    USER_NOTIFICATION = "user_notification"
+    AGENT_ERROR = "agent_error"
+    SYSTEM_LOG = "system_log"
+
+    # Subagent events
+    SUBAGENT_TASK_START = "subagent_task_start"
+    SUBAGENT_TEXT = "subagent_text"
+    SUBAGENT_LIMIT = "subagent_limit"
+    SUBAGENT_COMPLETED = "subagent_completed"
+
+
+@dataclass
+class AgentEvent:
+    """Agent lifecycle event with typed payload.
+
+    The ``data`` field holds a strongly-typed payload dataclass (e.g.
+    ``StreamDeltaPayload``, ``ToolCallStartedPayload``).  Subscribers can
+    access fields directly with IDE auto-completion::
+
+        def on_delta(event: AgentEvent) -> None:
+            delta: StreamDeltaPayload = event.data
+            print(delta.text)
+
+    The legacy ``payload`` dict is auto-generated from ``data.to_dict()``
+    for backward compatibility.  If ``data`` is not set, ``payload`` dict
+    is used directly (legacy path).
+    """
+    type: AgentEventType
+    payload: dict[str, Any] = field(default_factory=dict)
+    data: BaseEventPayload | None = field(default=None, repr=False)
+    session_id: str | None = None
+    round_index: int | None = None
+    stream_id: str | None = None
+    source: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.data is not None and not self.payload:
+            self.payload = self.data.to_dict()

power_loop/contracts/handlers.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from power_loop.contracts.events import AgentEvent
+from power_loop.contracts.hook_contexts import BaseHookCtx
+from power_loop.contracts.hooks import HookDirective
+
+
+class EventHandler(Protocol):
+    def __call__(self, event: AgentEvent) -> Any:
+        ...
+
+
+class HookHandler(Protocol):
+    """Hook handler callable.
+
+    The recommended (typed) signature receives a ``BaseHookCtx`` subclass,
+    mutates it in-place, and optionally returns ``HookDirective`` or ``None``.
+
+    Legacy handlers that accept ``HookContext`` are still supported.
+    """
+
+    def __call__(self, ctx: BaseHookCtx) -> HookDirective | None | Awaitable[HookDirective | None]:
+        ...
+
+
+@dataclass
+class ToolHandlerResult:
+    """Normalized tool execution result envelope."""
+
+    ok: bool
+    content: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+class ToolHandler(Protocol):
+    def __call__(self, args: dict[str, Any]) -> ToolHandlerResult | dict[str, Any] | str | Awaitable[ToolHandlerResult | dict[str, Any] | str]:
+        ...
+
+
+ToolHandlerMap = dict[str, ToolHandler]
+EventSubscriber = Callable[[EventHandler], None]