power-loop 0.2.0__py3-none-any.whl

power_loop/contracts/hook_contexts.py

@@ -0,0 +1,265 @@
+"""Typed hook context dataclasses — one per hook point.
+
+Each dataclass declares the exact fields a hook handler receives and can
+modify, replacing the untyped ``HookContext.values`` dict.  Handlers
+mutate the context in place and set ``directive`` when needed.
+
+Usage::
+
+    def my_handler(ctx: ToolBeforeCtx) -> None:
+        if "rm -rf" in str(ctx.tool_args):
+            ctx.output = "[blocked by policy]"
+            ctx.directive = HookDirective.SKIP
+"""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from power_loop.contracts.hooks import HookDirective
+
+if TYPE_CHECKING:
+    from llm_client.interface import LLMResponse
+    from power_loop.agent.types import LoopMessage
+
+
+# ── Base ──
+
+
+@dataclass
+class BaseHookCtx:
+    """Common fields shared by all hook contexts."""
+
+    round_index: int = 0
+    directive: HookDirective = HookDirective.CONTINUE
+
+
+# ── Session ──
+
+
+@dataclass
+class SessionStartCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.SESSION_START`.
+
+    Handler may modify ``messages``.
+    """
+
+    scope: str = "main"
+    messages: list[LoopMessage] = field(default_factory=list)
+    stop_event: threading.Event | None = None
+
+
+@dataclass
+class SessionEndCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.SESSION_END` (read-only)."""
+
+    scope: str = "main"
+    reason: str = ""
+    messages: list[LoopMessage] = field(default_factory=list)
+    final_text: str | None = None
+
+
+# ── Round ──
+
+
+@dataclass
+class RoundStartCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.ROUND_START`.
+
+    Directives: BREAK (set ``reason``), SKIP.
+    Handler may modify ``messages``.
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    stop_event: threading.Event | None = None
+    # Handler output
+    reason: str = ""
+
+
+@dataclass
+class RoundEndCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.ROUND_END` (read-only).
+
+    Both ``response_text`` and ``used_todo`` are always present.
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    has_tools: bool = False
+    response_text: str = ""
+    used_todo: bool = False
+
+
+# ── LLM ──
+
+
+@dataclass
+class LlmBeforeCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.LLM_BEFORE`.
+
+    Directives: SHORT_CIRCUIT (set ``output`` to an ``LLMResponse``), BREAK.
+    Handler may modify any input field.
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    system_prompt: str = ""
+    tools: list[dict[str, Any]] | None = None
+    max_tokens: int = 8000
+    temperature: float = 0.0
+    # Handler output (for SHORT_CIRCUIT)
+    output: LLMResponse | None = None
+
+
+@dataclass
+class LlmAfterCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.LLM_AFTER`.
+
+    Directives: BREAK.
+    Handler may replace ``output``.
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    output: LLMResponse | None = None
+
+
+# ── Round decide ──
+
+
+@dataclass
+class RoundDecideCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.ROUND_DECIDE`.
+
+    Directives: SKIP (set ``output`` as skip message), BREAK.
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    assistant_text: str = ""
+    # Handler output (for SKIP)
+    output: str = "[skipped by round_decide hook]"
+
+
+# ── Tools batch ──
+
+
+@dataclass
+class ToolsBatchBeforeCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.TOOLS_BATCH_BEFORE`.
+
+    Directives: SKIP (set ``output`` as placeholder result for all tools).
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+    # Handler output (for SKIP)
+    output: str = "[skipped by batch hook]"
+
+
+@dataclass
+class ToolsBatchAfterCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.TOOLS_BATCH_AFTER` (read-only)."""
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    used_todo: bool = False
+
+
+# ── Individual tool ──
+
+
+@dataclass
+class ToolBeforeCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.TOOL_BEFORE`.
+
+    Directives: SKIP (set ``output``).
+    Handler may modify ``tool_name`` and ``tool_args``.
+    """
+
+    tool_call: dict[str, Any] = field(default_factory=dict)
+    tool_name: str = ""
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    # Handler output (for SKIP)
+    output: str = "[skipped by hook]"
+
+
+@dataclass
+class ToolAfterCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.TOOL_AFTER`.
+
+    Directives: BREAK.
+    Handler may replace ``output`` and ``failed``.
+    """
+
+    tool_call: dict[str, Any] = field(default_factory=dict)
+    tool_name: str = ""
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    output: str = ""
+    failed: bool = False
+
+
+@dataclass
+class ToolErrorCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.TOOL_ERROR`.
+
+    Directives: SKIP (use ``output`` as fallback), SHORT_CIRCUIT (retry).
+    """
+
+    tool_call: dict[str, Any] = field(default_factory=dict)
+    tool_name: str = ""
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    error: Exception | None = None
+    error_message: str = ""
+    # Handler output (fallback for SKIP)
+    output: str = ""
+
+
+# ── Compact ──
+
+
+@dataclass
+class CompactBeforeCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.COMPACT_BEFORE`.
+
+    Directives: SKIP (skip compaction this round).
+    """
+
+    messages: list[LoopMessage] = field(default_factory=list)
+
+
+@dataclass
+class CompactAfterCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.COMPACT_AFTER` (read-only)."""
+
+    messages: list[LoopMessage] = field(default_factory=list)
+    messages_before_count: int = 0
+    messages_after_count: int = 0
+
+
+# ── Message ──
+
+
+@dataclass
+class MessageAppendCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.MESSAGE_APPEND`.
+
+    Handler may modify ``message``.
+    """
+
+    message: dict[str, Any] = field(default_factory=dict)
+    session_id: str | None = None
+
+
+# ── Memory (M1.9) ──
+
+
+@dataclass
+class MemoryRecalledCtx(BaseHookCtx):
+    """Context for :pyattr:`HookPoint.MEMORY_RECALLED`.
+
+    Fired after :meth:`MemoryProvider.recall` returns, before injection.
+    Handler may mutate ``recalled`` (filter, redact, reorder) or set
+    ``directive=SKIP`` to drop everything and inject nothing.
+    """
+
+    recalled: list[dict[str, Any]] = field(default_factory=list)
+    session_id: str | None = None
+    budget_tokens: int = 1500

power_loop/contracts/hooks.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class HookPoint(str, Enum):
+    SESSION_START = "session.start"
+    SESSION_END = "session.end"
+    ROUND_START = "round.start"
+    ROUND_END = "round.end"
+    LLM_BEFORE = "llm.before"
+    LLM_AFTER = "llm.after"
+    TOOLS_BATCH_BEFORE = "tools.batch.before"
+    TOOLS_BATCH_AFTER = "tools.batch.after"
+    TOOL_BEFORE = "tool.before"
+    TOOL_AFTER = "tool.after"
+    TOOL_ERROR = "tool.error"
+    ROUND_DECIDE = "round.decide"
+    COMPACT_BEFORE = "compact.before"
+    COMPACT_AFTER = "compact.after"
+    MESSAGE_APPEND = "message.append"
+    MEMORY_RECALLED = "memory.recalled"
+
+
+class HookDirective(str, Enum):
+    """Control-flow directives that hooks can return to influence the agent loop.
+
+    Not every directive is valid at every hook point. The agent loop checks
+    the directive returned by ``hooks.run_async`` and acts accordingly.
+
+    Supported combinations:
+        ROUND_START        -> BREAK (end loop), SKIP (skip this round)
+        LLM_BEFORE         -> SHORT_CIRCUIT (use values["response"] instead of calling LLM)
+        LLM_AFTER          -> BREAK (end loop, ignore tool calls)
+        ROUND_DECIDE       -> SKIP (skip tool execution), BREAK (end loop)
+        TOOLS_BATCH_BEFORE -> SKIP (skip all tools this round)
+        TOOL_BEFORE        -> SKIP (skip this tool, use values["tool_output"] as result)
+        TOOL_ERROR         -> SKIP (swallow error, use values["tool_output"]),
+                              SHORT_CIRCUIT (retry — re-invoke the tool)
+        TOOL_AFTER         -> BREAK (stop executing remaining tools, proceed to next round)
+        COMPACT_BEFORE     -> SKIP (skip compaction this round)
+    """
+
+    CONTINUE = "continue"
+    SKIP = "skip"
+    BREAK = "break"
+    SHORT_CIRCUIT = "short_circuit"
+
+
+@dataclass
+class HookContext:
+    """Mutable context passed through each hook chain."""
+
+    values: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HookResult:
+    """Return value from hook execution, carrying both context and control directive."""
+
+    context: HookContext = field(default_factory=HookContext)
+    directive: HookDirective = HookDirective.CONTINUE

power_loop/contracts/messages.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+MessageRole = Literal["system", "user", "assistant", "tool"]
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """Normalized tool call contract emitted by assistant messages."""
+
+    id: str
+    name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+
+    def to_openai_tool_call(self) -> dict[str, Any]:
+        import json
+
+        return {
+            "id": self.id,
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "arguments": json.dumps(self.arguments, ensure_ascii=False),
+            },
+        }
+
+
+@dataclass
+class AgentMessage:
+    """Unified runtime message contract used inside AgentLoop."""
+
+    role: MessageRole
+    content: str
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str | None = None
+    name: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_openai_message(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "role": self.role,
+            "content": self.content,
+        }
+        if self.role == "assistant" and self.tool_calls:
+            payload["tool_calls"] = [call.to_openai_tool_call() for call in self.tool_calls]
+        if self.role == "tool" and self.tool_call_id:
+            payload["tool_call_id"] = self.tool_call_id
+        if self.name:
+            payload["name"] = self.name
+        return payload
+
+
+def SystemMessage(content: str, **metadata: Any) -> AgentMessage:
+    return AgentMessage(role="system", content=content, metadata=dict(metadata))
+
+
+def UserMessage(content: str, **metadata: Any) -> AgentMessage:
+    return AgentMessage(role="user", content=content, metadata=dict(metadata))
+
+
+def AssistantMessage(
+    content: str,
+    *,
+    tool_calls: list[ToolCall] | None = None,
+    **metadata: Any,
+) -> AgentMessage:
+    return AgentMessage(
+        role="assistant",
+        content=content,
+        tool_calls=list(tool_calls or []),
+        metadata=dict(metadata),
+    )
+
+
+def ToolResultMessage(
+    content: str,
+    *,
+    tool_call_id: str,
+    name: str | None = None,
+    **metadata: Any,
+) -> AgentMessage:
+    return AgentMessage(
+        role="tool",
+        content=content,
+        tool_call_id=tool_call_id,
+        name=name,
+        metadata=dict(metadata),
+    )

power_loop/contracts/protocols.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Any, Protocol
+
+from power_loop.contracts.events import AgentEvent, AgentEventType
+from power_loop.contracts.handlers import EventHandler, HookHandler
+from power_loop.contracts.hook_contexts import BaseHookCtx
+from power_loop.contracts.hooks import HookContext, HookPoint, HookResult
+
+
+class EventBusProtocol(Protocol):
+    def subscribe(self, event_type: AgentEventType | None, handler: EventHandler, *, priority: int = 0) -> None:
+        ...
+
+    def unsubscribe(self, handler: EventHandler) -> None:
+        ...
+
+    def publish(self, event: AgentEvent) -> None:
+        ...
+
+    async def publish_async(self, event: AgentEvent) -> None:
+        ...
+
+
+class HookManagerProtocol(Protocol):
+    def register(self, hook_point: HookPoint | str, handler: HookHandler, *, order: int = 0) -> None:
+        ...
+
+    def clear(self, hook_point: HookPoint | str | None = None) -> None:
+        ...
+
+    def run(self, hook_point: HookPoint | str, context: HookContext) -> HookResult:
+        ...
+
+    async def run_async(self, hook_point: HookPoint | str, context: HookContext) -> HookResult:
+        ...
+
+    def run_typed(self, hook_point: HookPoint | str, ctx: BaseHookCtx) -> None:
+        ...
+
+    async def run_typed_async(self, hook_point: HookPoint | str, ctx: BaseHookCtx) -> None:
+        ...
+
+
+class ToolArgsValidator(Protocol):
+    def __call__(self, tool_name: str, args: dict[str, Any]) -> str | None | Awaitable[str | None]:
+        ...

power_loop/contracts/tools.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ToolDefinition:
+    name: str
+    description: str
+    input_schema: dict[str, Any] = field(default_factory=lambda: {"type": "object", "properties": {}})
+    required_params: tuple[str, ...] = ()
+
+    def to_openai_tool(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": dict(self.input_schema),
+            },
+        }
+
+
+DEFAULT_REQUIRED_PARAMS: dict[str, tuple[str, ...]] = {
+    "write_file": ("path", "content"),
+    "read_file": ("path",),
+    "edit_file": ("path", "old_text", "new_text"),
+    "apply_patch": ("path", "patch"),
+    "bash": ("command",),
+    "glob": ("pattern",),
+    "grep": ("pattern",),
+    "load_skill": ("name",),
+    "todo": ("items",),
+    "background_run": ("command",),
+    "web_search": ("query",),
+    "generate_image": ("prompt",),
+    "edit_image": ("image_paths", "prompt"),
+}
+
+
+def validate_tool_args(tool_name: str, args: Mapping[str, Any]) -> str | None:
+    required = DEFAULT_REQUIRED_PARAMS.get(tool_name)
+    if not required:
+        return None
+    missing = [param for param in required if param not in args]
+    if not missing:
+        return None
+    req = ", ".join(required)
+    miss = ", ".join(missing)
+    return (
+        f"Error: missing required parameter(s): {miss}. "
+        f"{tool_name} requires: {req}. "
+        "Please provide all required parameters as a valid JSON object."
+    )

power_loop/core/agent_context.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from power_loop.agent.stateful_loop import StatefulAgentLoop
+    from power_loop.core.events import AgentEventBus
+    from power_loop.core.hooks import AgentHooks
+    from power_loop.core.state import ContextManager
+
+
+_current_event_bus: ContextVar[AgentEventBus | None] = ContextVar("power_loop_event_bus", default=None)
+_current_hooks: ContextVar[AgentHooks | None] = ContextVar("power_loop_hooks", default=None)
+_current_ctx: ContextVar[ContextManager | None] = ContextVar("power_loop_ctx", default=None)
+_current_session_id: ContextVar[str | None] = ContextVar("power_loop_session_id", default=None)
+_current_loop: ContextVar[StatefulAgentLoop | None] = ContextVar(
+    "power_loop_current_loop", default=None
+)
+
+
+def get_event_bus() -> AgentEventBus:
+    bus = _current_event_bus.get()
+    # Local import to avoid import cycles
+    from power_loop.core.events import DEFAULT_EVENT_BUS
+
+    return DEFAULT_EVENT_BUS if bus is None else bus
+
+
+def get_hooks() -> AgentHooks:
+    hooks = _current_hooks.get()
+    from power_loop.core.hooks import DEFAULT_HOOKS
+
+    return DEFAULT_HOOKS if hooks is None else hooks
+
+
+def get_ctx() -> ContextManager:
+    ctx = _current_ctx.get()
+    if ctx is None:
+        from power_loop.core.state import ContextManager
+
+        ctx = ContextManager(role="main")
+        _current_ctx.set(ctx)
+        return ctx
+    return ctx
+
+
+def get_session_id() -> str | None:
+    return _current_session_id.get()
+
+
+def get_current_loop() -> StatefulAgentLoop | None:
+    return _current_loop.get()
+
+
+def set_current_loop(loop: StatefulAgentLoop | None) -> Token:
+    return _current_loop.set(loop)
+
+
+def reset_current_loop(token: Token) -> None:
+    _current_loop.reset(token)
+
+
+def set_event_bus(bus: AgentEventBus | None) -> Token:
+    return _current_event_bus.set(bus)
+
+
+def set_hooks(hooks: AgentHooks | None) -> Token:
+    return _current_hooks.set(hooks)
+
+
+def set_ctx(ctx: ContextManager | None) -> Token:
+    return _current_ctx.set(ctx)
+
+
+def set_session_id(session_id: str | None) -> Token:
+    return _current_session_id.set(session_id)
+
+
+def reset_event_bus(token: Token) -> None:
+    _current_event_bus.reset(token)
+
+
+def reset_hooks(token: Token) -> None:
+    _current_hooks.reset(token)
+
+
+def reset_ctx(token: Token) -> None:
+    _current_ctx.reset(token)
+
+
+def reset_session_id(token: Token) -> None:
+    _current_session_id.reset(token)
+