langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/hook/__init__.py

@@ -0,0 +1,48 @@
+"""
+loop.hook — Hook 子系统（P1/P2）。
+
+职责：
+    提供 Hook 定义、配置快照与执行引擎的公共导出。
+
+链路位置：
+    由 loop 图装配层调用，用于替代历史中间件机制。
+
+当前裁剪范围：
+    已包含 P1 + P2 基础执行器导出；并行聚合与治理细节见 HookEngine/规划文档。
+"""
+
+from .config import HookCandidate, HookCandidateDecision, HookSpec, HooksConfigSnapshot
+from .async_hook_runner import AsyncHookRunner
+from .engine import HookEngine
+from .executors import AgentExecutor, CommandExecutor, HttpExecutor, PromptExecutor
+from .graph_wiring import HookGraphWiring
+from .registry import HookRegistry
+from .trust import WorkspaceTrustChecker
+from .types import (
+    AggregatedHookResult,
+    HookContext,
+    HookEvent,
+    HookExecutionRecord,
+    HookResult,
+)
+
+__all__ = [
+    "AggregatedHookResult",
+    "AsyncHookRunner",
+    "HookCandidate",
+    "HookCandidateDecision",
+    "HookContext",
+    "HookEngine",
+    "HookEvent",
+    "HookExecutionRecord",
+    "HookGraphWiring",
+    "HookRegistry",
+    "HookResult",
+    "HookSpec",
+    "HooksConfigSnapshot",
+    "CommandExecutor",
+    "HttpExecutor",
+    "PromptExecutor",
+    "AgentExecutor",
+    "WorkspaceTrustChecker",
+]

langchain_agentx/loop/hook/async_hook_runner.py

@@ -0,0 +1,62 @@
+"""
+async_hook_runner.py — Hook 同步入口的异步执行协作者。
+
+职责：
+    为同步节点提供统一的 async hook 执行策略，避免 event loop 存在时退化跳过。
+
+链路位置：
+    HookGraphWiring 与 graph_edges 通过本协作者调用 HookEngine.execute()。
+
+当前裁剪范围：
+    P1 仅实现线程桥接执行；不引入 nest_asyncio，不修改外部事件循环。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from threading import Lock
+
+from .engine import HookEngine
+from .types import AggregatedHookResult, HookContext
+
+
+class AsyncHookRunner:
+    """同步调用场景下的 Hook 执行器。"""
+
+    def __init__(self) -> None:
+        self._executor: ThreadPoolExecutor | None = None
+        self._executor_lock = Lock()
+
+    def run(self, hook_engine: HookEngine, ctx: HookContext) -> AggregatedHookResult:
+        """统一执行 HookEngine.execute，兼容有无运行中事件循环两种场景。"""
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(hook_engine.execute(ctx))
+        return self._run_in_thread(hook_engine, ctx)
+
+    def _run_in_thread(self, hook_engine: HookEngine, ctx: HookContext) -> AggregatedHookResult:
+        """在独立线程内创建事件循环执行 hook。"""
+        executor = self._get_or_create_executor()
+        future = executor.submit(self._thread_entry, hook_engine, ctx)
+        return future.result()
+
+    def _get_or_create_executor(self) -> ThreadPoolExecutor:
+        with self._executor_lock:
+            if self._executor is None:
+                self._executor = ThreadPoolExecutor(max_workers=1)
+            return self._executor
+
+    def close(self) -> None:
+        with self._executor_lock:
+            if self._executor is not None:
+                self._executor.shutdown(wait=True)
+                self._executor = None
+
+    @staticmethod
+    def _thread_entry(hook_engine: HookEngine, ctx: HookContext) -> AggregatedHookResult:
+        return asyncio.run(hook_engine.execute(ctx))
+
+
+__all__ = ["AsyncHookRunner"]

langchain_agentx/loop/hook/config.py

@@ -0,0 +1,280 @@
+"""
+config.py — Hook 配置快照与候选集构建（P1/P2）。
+
+职责：
+    定义 HookSpec，维护 HooksConfigSnapshot，并产出可执行候选列表。
+
+链路位置：
+    HookEngine 在每次事件执行前通过 snapshot 拉取 candidates。
+
+当前裁剪范围：
+    已支持 P1/P2 执行器候选构建（matcher/condition/policy/dedup/type-order）；
+    与执行器并行策略由 HookEngine 协同完成。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+import json
+from threading import Lock
+from typing import Any, Callable, Literal
+from uuid import uuid4
+
+from .types import HookContext, HookEvent, HookSource
+
+ExecutorType = Literal["function", "callback", "command", "http", "prompt", "agent"]
+HTTP_UNSUPPORTED_EVENTS = {HookEvent.SESSION_START}
+TYPE_ORDER: dict[ExecutorType, int] = {
+    "command": 0,
+    "prompt": 1,
+    "agent": 2,
+    "http": 3,
+    "callback": 4,
+    "function": 5,
+}
+
+
+@dataclass
+class HookSpec:
+    """单条 Hook 配置。"""
+
+    event: HookEvent
+    executor_type: ExecutorType
+    config: dict[str, Any] = field(default_factory=dict)
+    matcher: str = "*"
+    timeout: float = 30.0
+    managed: bool = False
+    source: HookSource = "settings"
+    plugin_source: str | None = None
+    once: bool = False
+    on_success: Callable[[], None] | None = None
+    hook_id: str = field(default_factory=lambda: uuid4().hex)
+
+    def matches(self, ctx: HookContext) -> bool:
+        """根据 matcher 判断是否命中当前上下文。"""
+        if self.event != ctx.event:
+            return False
+        if self.matcher == "*":
+            return True
+        if ctx.tool_name is None:
+            return False
+        return fnmatch(ctx.tool_name, self.matcher)
+
+
+@dataclass(frozen=True)
+class HookCandidate:
+    """可执行候选（带稳定顺序键）。"""
+
+    spec: HookSpec
+    stable_key: str
+
+
+@dataclass(frozen=True)
+class HookCandidateDecision:
+    """候选筛选决策记录（用于可观测跳过原因）。"""
+
+    spec: HookSpec
+    stable_key: str
+    matched: bool
+    skip_reason: str | None
+
+
+class HooksConfigSnapshot:
+    """多来源 Hook 配置快照。"""
+
+    def __init__(self) -> None:
+        self.snapshot_id: str = uuid4().hex
+        self._specs: list[HookSpec] = []
+        self._lock = Lock()
+        self._disable_all: bool = False
+        self._allow_managed_only: bool = False
+        self._policy_source: str | None = None
+
+    @property
+    def disable_all(self) -> bool:
+        return self._disable_all
+
+    @property
+    def allow_managed_only(self) -> bool:
+        return self._allow_managed_only
+
+    @property
+    def policy_source(self) -> str | None:
+        return self._policy_source
+
+    def add_spec(self, spec: HookSpec) -> None:
+        self._specs.append(spec)
+
+    def load_from_settings(self, settings: dict[str, Any]) -> None:
+        self._disable_all = bool(settings.get("disable_all_hooks", False))
+        self._allow_managed_only = bool(settings.get("allow_managed_hooks_only", False))
+        self._policy_source = settings.get("policy_source")
+
+    def register_session_hook(self, spec: HookSpec) -> str:
+        session_spec = HookSpec(
+            event=spec.event,
+            executor_type=spec.executor_type,
+            config=dict(spec.config),
+            matcher=spec.matcher,
+            timeout=spec.timeout,
+            managed=spec.managed,
+            source="session",
+            once=spec.once,
+            on_success=spec.on_success,
+        )
+        self._specs.append(session_spec)
+        return session_spec.hook_id
+
+    def unregister_session_hook(self, hook_id: str) -> None:
+        self._specs = [spec for spec in self._specs if spec.hook_id != hook_id]
+
+    def replace_plugin_hooks_atomic(self, specs: list[HookSpec]) -> None:
+        """原子替换所有插件来源 hook（仅影响 source == "plugin"）。"""
+        with self._lock:
+            self._specs = [spec for spec in self._specs if spec.source != "plugin"]
+            self._specs.extend(specs)
+
+    def remove_plugin_hooks(self, plugin_source: str) -> None:
+        """移除指定插件来源 hook（仅影响 source == "plugin"）。"""
+        with self._lock:
+            self._specs = [
+                spec
+                for spec in self._specs
+                if not (
+                    spec.source == "plugin" and spec.plugin_source == plugin_source
+                )
+            ]
+
+    def get_candidates(self, ctx: HookContext) -> list[HookCandidate]:
+        """构建候选集：matcher -> last-wins 去重 -> 类型重排序。"""
+        candidates, _ = self.get_candidates_with_decisions(ctx)
+        return candidates
+
+    def get_candidates_with_decisions(
+        self, ctx: HookContext
+    ) -> tuple[list[HookCandidate], list[HookCandidateDecision]]:
+        """构建候选集并返回被跳过的决策记录。"""
+        skipped: list[HookCandidateDecision] = []
+        dedup: dict[str, HookSpec] = {}
+
+        for spec in self._specs:
+            if spec.event != ctx.event:
+                continue
+            key = self._dedup_key(spec)
+            if not spec.matches(ctx):
+                skipped.append(
+                    HookCandidateDecision(
+                        spec=spec,
+                        stable_key=key,
+                        matched=False,
+                        skip_reason="matcher_not_matched",
+                    )
+                )
+                continue
+            if spec.executor_type == "http" and ctx.event in HTTP_UNSUPPORTED_EVENTS:
+                skipped.append(
+                    HookCandidateDecision(
+                        spec=spec,
+                        stable_key=key,
+                        matched=True,
+                        skip_reason="http_unsupported_event",
+                    )
+                )
+                continue
+            condition = str(spec.config.get("if") or "").strip() or None
+            if not evaluate_condition(condition, ctx):
+                skipped.append(
+                    HookCandidateDecision(
+                        spec=spec,
+                        stable_key=key,
+                        matched=True,
+                        skip_reason="condition_not_matched",
+                    )
+                )
+                continue
+            policy_skip = self._policy_skip_reason(spec)
+            if policy_skip is not None:
+                skipped.append(
+                    HookCandidateDecision(
+                        spec=spec,
+                        stable_key=key,
+                        matched=True,
+                        skip_reason=policy_skip,
+                    )
+                )
+                continue
+            if key in dedup:
+                skipped.append(
+                    HookCandidateDecision(
+                        spec=dedup[key],
+                        stable_key=key,
+                        matched=True,
+                        skip_reason="dedup_overridden",
+                    )
+                )
+            dedup[key] = spec
+
+        deduped = list(dedup.items())
+        deduped.sort(key=lambda kv: (TYPE_ORDER[kv[1].executor_type], kv[0]))
+        candidates = [HookCandidate(spec=spec, stable_key=key) for key, spec in deduped]
+        return candidates, skipped
+
+    def _policy_skip_reason(self, spec: HookSpec) -> str | None:
+        if self._disable_all and not spec.managed:
+            return "disable_all"
+        if self._allow_managed_only and not spec.managed:
+            return "managed_only"
+        return None
+
+    @staticmethod
+    def _dedup_key(spec: HookSpec) -> str:
+        name = str(spec.config.get("name") or spec.config.get("id") or spec.hook_id)
+        return f"{spec.event.value}:{spec.matcher}:{name}"
+
+
+def resolve_executor_callable(spec: HookSpec) -> Callable[..., Any]:
+    """从 HookSpec config 解析可执行对象。"""
+    fn = spec.config.get("fn") or spec.config.get("callback")
+    if not callable(fn):
+        raise TypeError(f"HookSpec {spec.hook_id} missing callable 'fn/callback'")
+    return fn
+
+
+def evaluate_condition(condition: str | None, ctx: HookContext) -> bool:
+    """评估 Hook `if` 条件，支持 `tool_name(arg_glob)` 简化语法。"""
+    if condition is None:
+        return True
+    text = condition.strip()
+    if not text:
+        return True
+    if text == "*":
+        return True
+
+    open_idx = text.find("(")
+    if open_idx == -1:
+        return bool(ctx.tool_name) and fnmatch(ctx.tool_name, text)
+
+    if not text.endswith(")") or open_idx == 0:
+        return False
+
+    tool_pattern = text[:open_idx].strip()
+    arg_pattern = text[open_idx + 1 : -1].strip()
+    if not ctx.tool_name or not fnmatch(ctx.tool_name, tool_pattern):
+        return False
+    if not arg_pattern:
+        return True
+
+    tool_input_json = json.dumps(ctx.tool_input or {}, ensure_ascii=False)
+    return fnmatch(tool_input_json, arg_pattern)
+
+
+__all__ = [
+    "ExecutorType",
+    "HookCandidate",
+    "HookCandidateDecision",
+    "HookSpec",
+    "HooksConfigSnapshot",
+    "evaluate_condition",
+    "resolve_executor_callable",
+]