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

langchain_agentx/loop/hook/engine.py

@@ -0,0 +1,321 @@
+"""
+engine.py — Hook 执行引擎（P1/P2）。
+
+职责：
+    负责按顺序执行 Hook 候选并聚合结果，输出 AggregatedHookResult。
+
+链路位置：
+    graph wiring 节点调用 HookEngine.execute(event, ctx) 获取可消费结果。
+
+当前裁剪范围：
+    已覆盖 function/callback + command/http/prompt/agent 执行器；
+    当前执行策略为 callback/function 顺序、其余执行器并行。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import time
+from typing import Any, TYPE_CHECKING
+
+from .config import (
+    HookCandidate,
+    HookCandidateDecision,
+    HooksConfigSnapshot,
+    resolve_executor_callable,
+)
+from .executors import CommandExecutor
+from .executors import HttpExecutor
+from .executors import PromptExecutor
+from .executors import AgentExecutor
+from .types import (
+    AggregatedHookResult,
+    HookContext,
+    HookExecutionRecord,
+    HookResult,
+    PermissionBehavior,
+)
+from .trust import WorkspaceTrustChecker
+
+if TYPE_CHECKING:
+    from ...observability.trace.hook_event_emitter import HookEventEmitter
+
+
+logger = logging.getLogger(__name__)
+
+
+class FunctionExecutor:
+    """执行 function 类型 hook。"""
+
+    async def run(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        fn = resolve_executor_callable(candidate.spec)
+        out = fn(ctx)
+        if inspect.isawaitable(out):
+            out = await out
+        return normalize_hook_result(out)
+
+
+class CallbackExecutor:
+    """执行 callback 类型 hook，支持 timeout。"""
+
+    async def run(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        cb = resolve_executor_callable(candidate.spec)
+        coro = cb(ctx)
+        if not inspect.isawaitable(coro):
+            return normalize_hook_result(coro)
+        timeout = candidate.spec.timeout
+        try:
+            out = await asyncio.wait_for(coro, timeout=timeout)
+        except asyncio.TimeoutError:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=[f"hook timeout after {timeout:.1f}s"],
+            )
+        return normalize_hook_result(out)
+
+
+class HookEngine:
+    """统一调度器（P1 顺序执行）。"""
+
+    def __init__(
+        self,
+        snapshot: HooksConfigSnapshot,
+        *,
+        event_emitter: HookEventEmitter | None = None,
+        trust_checker: WorkspaceTrustChecker | None = None,
+    ) -> None:
+        self._snapshot = snapshot
+        self._function_executor = FunctionExecutor()
+        self._callback_executor = CallbackExecutor()
+        self._command_executor = CommandExecutor()
+        self._http_executor = HttpExecutor()
+        self._prompt_executor = PromptExecutor()
+        self._agent_executor = AgentExecutor()
+        self._event_emitter = event_emitter
+        self._trust_checker = trust_checker
+
+    async def execute(self, ctx: HookContext) -> AggregatedHookResult:
+        candidates, skipped = self._snapshot.get_candidates_with_decisions(ctx)
+        self._emit_skipped_records(ctx, skipped)
+        if not candidates:
+            return AggregatedHookResult()
+        if self._trust_checker is not None:
+            candidates = self._filter_trusted_candidates(ctx, candidates)
+            if not candidates:
+                return AggregatedHookResult()
+
+        result = AggregatedHookResult()
+        sequential_candidates = [
+            candidate
+            for candidate in candidates
+            if candidate.spec.executor_type in {"callback", "function"}
+        ]
+        parallel_candidates = [
+            candidate
+            for candidate in candidates
+            if candidate.spec.executor_type in {"command", "http", "prompt", "agent"}
+        ]
+
+        for candidate in sequential_candidates:
+            one = await self._run_with_record(candidate, ctx)
+            self._merge(result, one)
+
+        if parallel_candidates:
+            parallel_results = await asyncio.gather(
+                *(self._run_with_record(candidate, ctx) for candidate in parallel_candidates)
+            )
+            for one in parallel_results:
+                self._merge(result, one)
+        return result
+
+    def _filter_trusted_candidates(
+        self,
+        ctx: HookContext,
+        candidates: list[HookCandidate],
+    ) -> list[HookCandidate]:
+        trusted: list[HookCandidate] = []
+        for candidate in candidates:
+            executor_type = candidate.spec.executor_type
+            if self._trust_checker is not None and self._trust_checker.should_skip(executor_type):
+                self._emit_trust_skipped_record(ctx, candidate)
+                continue
+            trusted.append(candidate)
+        return trusted
+
+    async def _run_with_record(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        started_at = time.perf_counter()
+        one = await self._run_one(candidate, ctx)
+        duration_ms = (time.perf_counter() - started_at) * 1000
+        outcome = self._emit_execution_record(ctx, candidate, one, duration_ms)
+        if outcome == "success" and candidate.spec.on_success is not None:
+            candidate.spec.on_success()
+        return one
+
+    async def _run_one(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        et = candidate.spec.executor_type
+        if et == "function":
+            return await self._function_executor.run(candidate, ctx)
+        if et == "callback":
+            return await self._callback_executor.run(candidate, ctx)
+        if et == "command":
+            return await self._command_executor.run(candidate, ctx)
+        if et == "http":
+            return await self._http_executor.run(candidate, ctx)
+        if et == "prompt":
+            return await self._prompt_executor.run(candidate, ctx)
+        if et == "agent":
+            return await self._agent_executor.run(candidate, ctx)
+        return HookResult(
+            outcome="non_blocking_error",
+            blocking_errors=[f"unsupported executor in P1: {et}"],
+        )
+
+    @staticmethod
+    def _merge(agg: AggregatedHookResult, one: HookResult) -> None:
+        if one.prevent_continuation:
+            agg.prevent_continuation = True
+        if one.blocking_errors:
+            agg.blocking_errors.extend(one.blocking_errors)
+        if one.additional_context:
+            agg.additional_contexts.append(one.additional_context)
+        if one.updated_input is not None:
+            agg.updated_input = dict(one.updated_input)
+        if one.state_patch:
+            agg.state_patch.update(one.state_patch)
+
+        agg.permission_behavior = merge_permission_behavior(
+            agg.permission_behavior,
+            one.permission_behavior,
+        )
+        if one.hook_permission_decision_reason:
+            agg.hook_permission_decision_reason = one.hook_permission_decision_reason
+
+    def _emit_skipped_records(
+        self,
+        ctx: HookContext,
+        skipped: list[HookCandidateDecision],
+    ) -> None:
+        for decision in skipped:
+            record = HookExecutionRecord(
+                hook_id=decision.spec.hook_id,
+                hook_event=ctx.event.value,
+                hook_source=decision.spec.source,
+                matcher=decision.spec.matcher,
+                matched=decision.matched,
+                skip_reason=decision.skip_reason,
+                snapshot_id=self._snapshot.snapshot_id,
+                policy_source=self._snapshot.policy_source,
+                outcome="cancelled",
+                prevent_continuation=False,
+                duration_ms=0.0,
+            )
+            self._try_emit_record(ctx.session_id, record)
+
+    def _emit_execution_record(
+        self,
+        ctx: HookContext,
+        candidate: HookCandidate,
+        result: HookResult,
+        duration_ms: float,
+    ) -> str:
+        outcome = result.outcome
+        if result.prevent_continuation or result.blocking_errors:
+            outcome = "blocking"
+        record = HookExecutionRecord(
+            hook_id=candidate.spec.hook_id,
+            hook_event=ctx.event.value,
+            hook_source=candidate.spec.source,
+            matcher=candidate.spec.matcher,
+            matched=True,
+            skip_reason=None,
+            snapshot_id=self._snapshot.snapshot_id,
+            policy_source=self._snapshot.policy_source,
+            outcome=outcome,
+            prevent_continuation=result.prevent_continuation,
+            duration_ms=duration_ms,
+        )
+        self._try_emit_record(ctx.session_id, record)
+        return outcome
+
+    def _emit_trust_skipped_record(
+        self,
+        ctx: HookContext,
+        candidate: HookCandidate,
+    ) -> None:
+        reason = (
+            self._trust_checker.skip_reason(candidate.spec.executor_type)
+            if self._trust_checker is not None
+            else "trust_check_skipped"
+        )
+        record = HookExecutionRecord(
+            hook_id=candidate.spec.hook_id,
+            hook_event=ctx.event.value,
+            hook_source=candidate.spec.source,
+            matcher=candidate.spec.matcher,
+            matched=True,
+            skip_reason=reason,
+            snapshot_id=self._snapshot.snapshot_id,
+            policy_source=self._snapshot.policy_source,
+            outcome="trust_skipped",
+            prevent_continuation=False,
+            duration_ms=0.0,
+        )
+        self._try_emit_record(ctx.session_id, record)
+
+    def _try_emit_record(self, session_id: str | None, record: HookExecutionRecord) -> None:
+        if self._event_emitter is None or not session_id:
+            return
+        if not self._event_emitter.collector.has_session(session_id):
+            return
+        try:
+            self._event_emitter.emit_record(session_id, record)
+        except Exception as exc:
+            # 发射失败不应阻断主链路
+            logger.debug("hook event emit failed (non-blocking): %s", exc)
+            return
+
+
+def normalize_hook_result(value: Any) -> HookResult:
+    """兼容 dict/HookResult 返回值。"""
+    if value is None:
+        return HookResult()
+    if isinstance(value, HookResult):
+        return value
+    if isinstance(value, dict):
+        kwargs = dict(value)
+        # 文档约定别名
+        if "preventContinuation" in kwargs and "prevent_continuation" not in kwargs:
+            kwargs["prevent_continuation"] = kwargs.pop("preventContinuation")
+        if "updatedInput" in kwargs and "updated_input" not in kwargs:
+            kwargs["updated_input"] = kwargs.pop("updatedInput")
+        if "permissionBehavior" in kwargs and "permission_behavior" not in kwargs:
+            kwargs["permission_behavior"] = kwargs.pop("permissionBehavior")
+        return HookResult(**kwargs)
+    raise TypeError(f"Unsupported hook result type: {type(value).__name__}")
+
+
+def merge_permission_behavior(
+    current: PermissionBehavior | None,
+    incoming: PermissionBehavior | None,
+) -> PermissionBehavior | None:
+    """deny > ask > allow > passthrough(None effect)."""
+    if incoming is None or incoming == "passthrough":
+        return current
+    if incoming == "deny":
+        return "deny"
+    if incoming == "ask":
+        return "ask" if current != "deny" else "deny"
+    if incoming == "allow":
+        return current or "allow"
+    return current
+
+
+__all__ = [
+    "CallbackExecutor",
+    "FunctionExecutor",
+    "HookEngine",
+    "merge_permission_behavior",
+    "normalize_hook_result",
+]

langchain_agentx/loop/hook/executors/__init__.py

@@ -0,0 +1,9 @@
+"""Hook 执行器子包（P2）。"""
+
+from .agent import AgentExecutor
+from .command import CommandExecutor
+from .http import HttpExecutor
+from .prompt import PromptExecutor
+
+__all__ = ["AgentExecutor", "CommandExecutor", "HttpExecutor", "PromptExecutor"]
+

langchain_agentx/loop/hook/executors/agent.py

@@ -0,0 +1,107 @@
+"""
+agent.py — AgentExecutor（P2）。
+
+职责：
+    执行 agent 类型 hook，构建单轮验证器输入并解析 decision。
+
+链路位置：
+    HookEngine._run_one() 在 executor_type=="agent" 时调用本执行器。
+
+当前裁剪范围：
+    通过配置注入可调用对象执行验证器；prompt 字段仅在运行时读取，不做预处理。
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from ..config import HookCandidate
+from ..types import HookContext, HookResult
+
+
+@dataclass
+class AgentExecutor:
+    """agent 类型 hook 执行器。"""
+
+    async def run(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        config = candidate.spec.config
+        # 对齐 gh-24920 / CC-79：prompt 在运行期按原值读取，不在构建阶段做任何 transform。
+        system_prompt = config.get("prompt")
+        if not isinstance(system_prompt, str) or not system_prompt.strip():
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=["agent hook missing 'prompt'"],
+            )
+
+        runner = self._resolve_runner(config)
+        if runner is None:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=["agent hook missing callable runner"],
+            )
+
+        user_payload = json.dumps(
+            {
+                "event": ctx.event.value,
+                "tool_name": ctx.tool_name,
+                "tool_input": ctx.tool_input,
+            },
+            ensure_ascii=False,
+        )
+        output_text = await self._call_runner(
+            runner=runner,
+            system_prompt=system_prompt,
+            user_payload=user_payload,
+            model=config.get("model"),
+            ctx=ctx,
+        )
+        return self._parse_decision(output_text)
+
+    @staticmethod
+    def _resolve_runner(config: dict[str, Any]) -> Callable[..., Any] | None:
+        runner = config.get("runner") or config.get("agent_runner")
+        return runner if callable(runner) else None
+
+    @staticmethod
+    async def _call_runner(
+        *,
+        runner: Callable[..., Any],
+        system_prompt: str,
+        user_payload: str,
+        model: Any,
+        ctx: HookContext,
+    ) -> str:
+        output = runner(system_prompt, user_payload, model, ctx)
+        if inspect.isawaitable(output):
+            output = await output
+        return str(output or "")
+
+    @staticmethod
+    def _parse_decision(text: str) -> HookResult:
+        lowered = text.lower()
+        if "deny" in lowered:
+            return HookResult(
+                outcome="success",
+                permission_behavior="deny",
+                hook_permission_decision_reason=text.strip() or None,
+            )
+        if "ask" in lowered:
+            return HookResult(
+                outcome="success",
+                permission_behavior="ask",
+                hook_permission_decision_reason=text.strip() or None,
+            )
+        if "allow" in lowered:
+            return HookResult(
+                outcome="success",
+                permission_behavior="allow",
+                hook_permission_decision_reason=text.strip() or None,
+            )
+        return HookResult(
+            outcome="non_blocking_error",
+            blocking_errors=["agent hook cannot parse decision"],
+        )
+

langchain_agentx/loop/hook/executors/command.py

@@ -0,0 +1,230 @@
+"""
+command.py — CommandExecutor（P2）。
+
+职责：
+    执行 command 类型 hook，负责子进程调用、退出码语义与 JSON 响应解析。
+
+链路位置：
+    HookEngine._run_one() 在 executor_type=="command" 时调用本执行器。
+
+当前裁剪范围：
+    实现 command 主路径、async/async_rewake、SESSION_START 的 CLAUDE_ENV_FILE 解析；
+    并行调度语义由 HookEngine 在 F6 阶段统一处理。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_core.messages import HumanMessage
+
+from ..config import HookCandidate
+from ..types import HookContext, HookEvent, HookResult
+
+
+@dataclass
+class CommandExecutor:
+    """command 类型 hook 执行器。"""
+
+    async def run(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        config = candidate.spec.config
+        command = str(config.get("command") or "").strip()
+        if not command:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=["command hook missing 'command'"],
+            )
+
+        shell = str(config.get("shell") or "bash")
+        async_mode = bool(config.get("async", False))
+        async_rewake = bool(config.get("asyncRewake", False) or config.get("async_rewake", False))
+        timeout = candidate.spec.timeout
+        env = self._build_hook_env(candidate, ctx)
+
+        if async_mode:
+            asyncio.create_task(
+                self._run_and_maybe_rewake(
+                    command=command,
+                    shell=shell,
+                    timeout=timeout,
+                    env=env,
+                    ctx=ctx,
+                    async_rewake=async_rewake,
+                )
+            )
+            return HookResult(outcome="success")
+
+        proc = await self._spawn_process(command=command, shell=shell, env=env)
+        return await self._finalize_process(proc=proc, ctx=ctx, timeout=timeout, env=env)
+
+    async def _run_and_maybe_rewake(
+        self,
+        *,
+        command: str,
+        shell: str,
+        timeout: float,
+        env: dict[str, str],
+        ctx: HookContext,
+        async_rewake: bool,
+    ) -> None:
+        proc = await self._spawn_process(command=command, shell=shell, env=env)
+        result = await self._finalize_process(proc=proc, ctx=ctx, timeout=timeout, env=env)
+        if not async_rewake:
+            return
+        if result.outcome != "success":
+            return
+        rewake_text = (result.additional_context or "").strip()
+        if rewake_text:
+            messages = ctx.state.get("messages")
+            if isinstance(messages, list):
+                messages.append(HumanMessage(content=rewake_text))
+
+    async def _spawn_process(
+        self,
+        *,
+        command: str,
+        shell: str,
+        env: dict[str, str],
+    ) -> asyncio.subprocess.Process:
+        if shell == "bash":
+            return await asyncio.create_subprocess_exec(
+                "bash",
+                "-lc",
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+            )
+        if shell == "sh":
+            return await asyncio.create_subprocess_exec(
+                "sh",
+                "-c",
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=env,
+            )
+        return await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+        )
+
+    async def _finalize_process(
+        self,
+        *,
+        proc: asyncio.subprocess.Process,
+        ctx: HookContext,
+        timeout: float,
+        env: dict[str, str],
+    ) -> HookResult:
+        try:
+            stdout_raw, stderr_raw = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        except asyncio.TimeoutError:
+            proc.kill()
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=[f"command hook timeout after {timeout:.1f}s"],
+            )
+
+        stdout = stdout_raw.decode("utf-8", errors="replace")
+        stderr = stderr_raw.decode("utf-8", errors="replace")
+        returncode = int(proc.returncode or 0)
+
+        result = HookResult(outcome="success")
+        parsed_json = self._parse_json(stdout)
+        if isinstance(parsed_json, dict):
+            self._apply_json_result(result, parsed_json)
+
+        if ctx.event == HookEvent.SESSION_START:
+            session_env_patch = self._read_claude_env_file(env)
+            if session_env_patch:
+                result.state_patch["_session_env"] = session_env_patch
+
+        if returncode == 0:
+            if not result.additional_context and stdout.strip():
+                result.additional_context = stdout.strip()
+            return result
+        if returncode == 2:
+            result.outcome = "blocking"
+            result.permission_behavior = result.permission_behavior or "deny"
+            if not result.blocking_errors:
+                result.blocking_errors = [stderr.strip() or "command hook blocked request"]
+            return result
+        result.outcome = "non_blocking_error"
+        if not result.blocking_errors:
+            result.blocking_errors = [stderr.strip() or f"command hook exited with {returncode}"]
+        return result
+
+    @staticmethod
+    def _parse_json(stdout: str) -> dict[str, Any] | None:
+        text = stdout.strip()
+        if not text:
+            return None
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            return None
+        return data if isinstance(data, dict) else None
+
+    @staticmethod
+    def _apply_json_result(result: HookResult, payload: dict[str, Any]) -> None:
+        if payload.get("continue") is False:
+            result.prevent_continuation = True
+        stop_reason = payload.get("stopReason")
+        if isinstance(stop_reason, str) and stop_reason.strip():
+            result.blocking_errors.append(stop_reason.strip())
+        decision = payload.get("decision")
+        if decision in {"allow", "ask", "deny"}:
+            result.permission_behavior = decision
+        reason = payload.get("reason")
+        if isinstance(reason, str) and reason.strip():
+            result.hook_permission_decision_reason = reason.strip()
+        updated_input = payload.get("updatedInput")
+        if isinstance(updated_input, dict):
+            result.updated_input = dict(updated_input)
+        if payload.get("suppressOutput") is True:
+            result.additional_context = ""
+
+    @staticmethod
+    def _build_hook_env(candidate: HookCandidate, ctx: HookContext) -> dict[str, str]:
+        env = dict(os.environ)
+        session_env = ctx.state.get("_session_env") if isinstance(ctx.state, dict) else None
+        if isinstance(session_env, dict):
+            for key, value in session_env.items():
+                if isinstance(key, str) and isinstance(value, str):
+                    env[key] = value
+        env["HOOK_EVENT_NAME"] = ctx.event.value
+        env["HOOK_TOOL_NAME"] = ctx.tool_name or ""
+        env["HOOK_TOOL_INPUT"] = json.dumps(ctx.tool_input or {}, ensure_ascii=False)
+        env["HOOK_SESSION_ID"] = ctx.session_id or ""
+        env["HOOK_SNAPSHOT_ID"] = candidate.stable_key
+        return env
+
+    @staticmethod
+    def _read_claude_env_file(env: dict[str, str]) -> dict[str, str]:
+        path = env.get("CLAUDE_ENV_FILE")
+        if not path:
+            return {}
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                lines = f.readlines()
+        except OSError:
+            return {}
+
+        parsed: dict[str, str] = {}
+        for raw in lines:
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            key = key.strip()
+            if key:
+                parsed[key] = value.strip()
+        return parsed
+