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

langchain_agentx/loop/hook/executors/http.py

@@ -0,0 +1,114 @@
+"""
+http.py — HttpExecutor（P2）。
+
+职责：
+    执行 http 类型 hook，负责请求构建、响应解析与错误收敛。
+
+链路位置：
+    HookEngine._run_one() 在 executor_type=="http" 时调用本执行器。
+
+当前裁剪范围：
+    实现 HTTP POST 主路径与 JSON 协议解析；并行调度由 F6 统一处理。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ..config import HookCandidate
+from ..types import HookContext, HookResult
+
+
+@dataclass
+class HttpExecutor:
+    """http 类型 hook 执行器。"""
+
+    async def run(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        config = candidate.spec.config
+        url = str(config.get("url") or "").strip()
+        if not url:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=["http hook missing 'url'"],
+            )
+
+        timeout = candidate.spec.timeout
+        body = {
+            "event": ctx.event.value,
+            "session_id": ctx.session_id,
+            "tool_name": ctx.tool_name,
+            "tool_input": ctx.tool_input,
+            "hook_stable_key": candidate.stable_key,
+        }
+        headers = self._build_headers(config)
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                response = await client.post(url, json=body, headers=headers)
+        except Exception as exc:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=[f"http hook request failed: {exc}"],
+            )
+
+        if response.status_code != 200:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=[f"http hook status {response.status_code}"],
+            )
+
+        payload = self._parse_json(response)
+        result = HookResult(outcome="success")
+        if isinstance(payload, dict):
+            self._apply_json_result(result, payload)
+        return result
+
+    @staticmethod
+    def _build_headers(config: dict[str, Any]) -> dict[str, str]:
+        headers_raw = config.get("headers")
+        headers: dict[str, str] = {}
+        if isinstance(headers_raw, dict):
+            headers = {str(k): str(v) for k, v in headers_raw.items()}
+
+        allowed_raw = config.get("allowedEnvVars")
+        allowed_env = allowed_raw if isinstance(allowed_raw, list) else []
+        env_values = {name: os.environ.get(name, "") for name in allowed_env if isinstance(name, str)}
+        for key, value in list(headers.items()):
+            rendered = value
+            for env_name, env_val in env_values.items():
+                rendered = rendered.replace(f"${env_name}", env_val)
+            headers[key] = rendered
+        return headers
+
+    @staticmethod
+    def _parse_json(response: httpx.Response) -> dict[str, Any] | None:
+        try:
+            data = response.json()
+        except json.JSONDecodeError:
+            return None
+        except Exception:
+            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)
+

langchain_agentx/loop/hook/executors/prompt.py

@@ -0,0 +1,92 @@
+"""
+prompt.py — PromptExecutor（P2）。
+
+职责：
+    执行 prompt 类型 hook，负责 `$ARGUMENTS` 替换与 decision 解析。
+
+链路位置：
+    HookEngine._run_one() 在 executor_type=="prompt" 时调用本执行器。
+
+当前裁剪范围：
+    通过配置注入可调用对象执行模型推理；并行调度在 F6 统一处理。
+"""
+
+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 PromptExecutor:
+    """prompt 类型 hook 执行器。"""
+
+    async def run(self, candidate: HookCandidate, ctx: HookContext) -> HookResult:
+        config = candidate.spec.config
+        template = str(config.get("prompt") or "").strip()
+        if not template:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=["prompt hook missing 'prompt'"],
+            )
+
+        runner = self._resolve_runner(config)
+        if runner is None:
+            return HookResult(
+                outcome="non_blocking_error",
+                blocking_errors=["prompt hook missing callable runner"],
+            )
+
+        arguments = json.dumps(ctx.tool_input or {}, ensure_ascii=False)
+        rendered_prompt = template.replace("$ARGUMENTS", arguments)
+        output_text = await self._call_runner(runner, rendered_prompt, config, 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("llm") or config.get("model_runner")
+        return runner if callable(runner) else None
+
+    @staticmethod
+    async def _call_runner(
+        runner: Callable[..., Any],
+        rendered_prompt: str,
+        config: dict[str, Any],
+        ctx: HookContext,
+    ) -> str:
+        output = runner(rendered_prompt, config.get("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=["prompt hook cannot parse decision"],
+        )
+

langchain_agentx/loop/hook/graph_wiring.py

@@ -0,0 +1,134 @@
+"""
+graph_wiring.py — Hook 与 Loop 图装配协作者（Phase 2）。
+
+职责：
+    封装 Hook 节点工厂与最小接线路径，避免 factory.py 继续膨胀。
+
+链路位置：
+    由 loop/graph/factory.py 在构图阶段调用，产出 loop_start / stop_hooks 节点。
+
+当前裁剪范围：
+    Phase 2 仅接入 `loop_start` 与 `stop_hooks` 主路径；before/after/loop_end 节点先提供工厂占位。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from .async_hook_runner import AsyncHookRunner
+from .engine import HookEngine
+from .types import AggregatedHookResult, HookContext, HookEvent
+
+
+def _to_hook_result_dict(result: AggregatedHookResult) -> dict[str, Any]:
+    return {
+        "prevent_continuation": result.prevent_continuation,
+        "blocking_errors": list(result.blocking_errors) or None,
+        "permission_behavior": result.permission_behavior,
+        "hook_permission_decision_reason": result.hook_permission_decision_reason,
+        "additional_contexts": list(result.additional_contexts),
+        "updated_input": result.updated_input,
+        "state_patch": dict(result.state_patch),
+    }
+
+
+@dataclass
+class HookGraphWiring:
+    """Hook 图装配器。"""
+
+    hook_engine: HookEngine
+    trace_lifecycle_collector: Any | None = None
+    session_memory: Any | None = None
+    memory_extractor: Any | None = None
+    agent_memory_extractor: Any | None = None
+    workspace_cfg: Any | None = None
+    session_id: str | None = None
+    container_type: str = "interactive"
+    subagent_type: str | None = None
+    hook_runner: AsyncHookRunner = field(default_factory=AsyncHookRunner)
+
+    def loop_start_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
+        run_id = state.get("_run_id")
+        if not isinstance(run_id, str) or not run_id:
+            preferred = getattr(self.trace_lifecycle_collector, "default_run_id", None)
+            run_id = preferred if isinstance(preferred, str) and preferred else uuid4().hex
+        state_with_run_id = dict(state)
+        state_with_run_id["_run_id"] = run_id
+        patch: dict[str, Any] = {"_run_id": run_id}
+        patch["_hook_engine"] = self.hook_engine
+        patch["_hook_runner"] = self.hook_runner
+        if self.trace_lifecycle_collector is not None:
+            patch.update(self.trace_lifecycle_collector.loop_start_node(state_with_run_id))
+        result = self._execute_sync(HookEvent.LOOP_START, state_with_run_id)
+        if result is not None:
+            patch["__hook_result__"] = _to_hook_result_dict(result)
+            if result.state_patch:
+                patch.update(dict(result.state_patch))
+        return patch
+
+    def before_model_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
+        result = self._execute_sync(HookEvent.BEFORE_MODEL, state)
+        patch = {"__hook_result__": _to_hook_result_dict(result)} if result is not None else {}
+        if result is not None and result.state_patch:
+            patch.update(dict(result.state_patch))
+        if self.trace_lifecycle_collector is not None:
+            patch.update(self.trace_lifecycle_collector.before_model_node(state))
+        return patch
+
+    def after_model_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
+        result = self._execute_sync(HookEvent.AFTER_MODEL, state)
+        patch = {"__hook_result__": _to_hook_result_dict(result)} if result is not None else {}
+        if result is not None and result.state_patch:
+            patch.update(dict(result.state_patch))
+        if self.session_memory is not None:
+            self.session_memory.maybe_trigger(state)
+        if self.trace_lifecycle_collector is not None:
+            patch.update(self.trace_lifecycle_collector.after_model_node(state))
+        return patch
+
+    def stop_hooks_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
+        # 仅在 loop_controller 会读取的时机执行 stop，避免每轮额外开销。
+        if not bool(state.get("should_end")):
+            return {}
+        if self.memory_extractor is not None and self.workspace_cfg is not None:
+            self.memory_extractor.trigger_from_state(
+                state=state,
+                workspace_cfg=self.workspace_cfg,
+                session_id=self.session_id or str(state.get("_session_id") or ""),
+                container_type=self.container_type,
+            )
+        if self.agent_memory_extractor is not None and self.workspace_cfg is not None:
+            self.agent_memory_extractor.trigger_from_state(
+                state=state,
+                workspace_cfg=self.workspace_cfg,
+                session_id=self.session_id or str(state.get("_session_id") or ""),
+                container_type=self.container_type,
+                agent_type=self.subagent_type,
+            )
+        result = self._execute_sync(HookEvent.STOP, state)
+        if result is None:
+            return {}
+        patch = {"__hook_result__": _to_hook_result_dict(result)}
+        if result.state_patch:
+            patch.update(dict(result.state_patch))
+        return patch
+
+    def loop_end_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
+        result = self._execute_sync(HookEvent.LOOP_END, state)
+        patch = {"__hook_result__": _to_hook_result_dict(result)} if result is not None else {}
+        if result is not None and result.state_patch:
+            patch.update(dict(result.state_patch))
+        if self.trace_lifecycle_collector is not None:
+            patch.update(self.trace_lifecycle_collector.loop_end_node(state))
+        return patch
+
+    def _execute_sync(
+        self, event: HookEvent, state: dict[str, Any]
+    ) -> AggregatedHookResult | None:
+        ctx = HookContext(event=event, state=state, session_id=state.get("_run_id"))
+        return self.hook_runner.run(self.hook_engine, ctx)
+
+
+__all__ = ["HookGraphWiring"]

langchain_agentx/loop/hook/registry.py

@@ -0,0 +1,262 @@
+"""
+registry.py — HookRegistry 用户侧入口。
+
+职责：
+    提供类型安全的 Hook 注册 API（装饰器 / 命令式），通过 build_snapshot() 桥接到
+    HooksConfigSnapshot，对用户隐藏 HookSpec 内部结构。
+
+链路位置：
+    用户构造 HookRegistry 后传入 create_loop_agent(hooks=registry)；
+    LoopGraphBuilder._prepare_compile_context() 调用 build_snapshot() 获取快照。
+
+当前裁剪范围：
+    已支持 P1/P2 执行器注册（function/callback/command/http/prompt/agent）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .config import HookSpec, HooksConfigSnapshot
+from .types import HookEvent
+
+
+class HookRegistry:
+    """用户侧 Hook 注册入口。
+
+    隐藏 HookSpec 内部结构，通过 build_snapshot() 桥接到 HooksConfigSnapshot。
+    """
+
+    def __init__(self) -> None:
+        self._specs: list[HookSpec] = []
+        self._snapshots: list[HooksConfigSnapshot] = []
+
+    # ── 装饰器 API（P1）──
+
+    def on(
+        self,
+        event: HookEvent,
+        *,
+        matcher: str = "*",
+        timeout: float = 30.0,
+        managed: bool = False,
+        once: bool = False,
+    ) -> Callable:
+        """注册 function hook（装饰器用法）。"""
+        def decorator(fn: Callable) -> Callable:
+            self._specs.append(self._make_spec(
+                event=event,
+                executor_type="function",
+                config={"fn": fn},
+                matcher=matcher,
+                timeout=timeout,
+                managed=managed,
+                source="session",
+                once=once,
+            ))
+            return fn
+        return decorator
+
+    def add_callback(
+        self,
+        event: HookEvent,
+        callback: Callable,
+        *,
+        matcher: str = "*",
+        timeout: float = 30.0,
+        managed: bool = False,
+        once: bool = False,
+    ) -> str:
+        """注册 callback hook，返回 hook_id 供撤销。"""
+        spec = self._make_spec(
+            event=event,
+            executor_type="callback",
+            config={"fn": callback},
+            matcher=matcher,
+            timeout=timeout,
+            managed=managed,
+            source="session",
+            once=once,
+        )
+        self._specs.append(spec)
+        return spec.hook_id
+
+    def remove(self, hook_id: str) -> None:
+        """撤销已注册的 hook。"""
+        self._specs = [s for s in self._specs if s.hook_id != hook_id]
+        for snapshot in self._snapshots:
+            snapshot.unregister_session_hook(hook_id)
+
+    # ── P2 注册 API ──
+
+    def add_command(
+        self,
+        event: HookEvent,
+        command: str,
+        *,
+        matcher: str = "*",
+        timeout: float = 60.0,
+        shell: str = "bash",
+        condition: str | None = None,
+        once: bool = False,
+        async_: bool = False,
+        async_rewake: bool = False,
+    ) -> str:
+        """注册 command hook。"""
+        spec = self._make_spec(
+            event=event,
+            executor_type="command",
+            config={
+                "command": command,
+                "shell": shell,
+                "if": condition,
+                "once": once,
+                "async": async_,
+                "asyncRewake": async_rewake,
+            },
+            matcher=matcher,
+            timeout=timeout,
+            source="session",
+            once=once,
+        )
+        self._specs.append(spec)
+        return spec.hook_id
+
+    def add_http(
+        self,
+        event: HookEvent,
+        url: str,
+        *,
+        matcher: str = "*",
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        allowed_env_vars: list[str] | None = None,
+        condition: str | None = None,
+        once: bool = False,
+    ) -> str:
+        """注册 http hook。"""
+        spec = self._make_spec(
+            event=event,
+            executor_type="http",
+            config={
+                "url": url,
+                "headers": headers or {},
+                "allowedEnvVars": allowed_env_vars or [],
+                "if": condition,
+                "once": once,
+            },
+            matcher=matcher,
+            timeout=timeout,
+            source="session",
+            once=once,
+        )
+        self._specs.append(spec)
+        return spec.hook_id
+
+    def add_prompt(
+        self,
+        event: HookEvent,
+        prompt: str,
+        runner: Callable,
+        *,
+        matcher: str = "*",
+        timeout: float = 30.0,
+        model: str | None = None,
+        condition: str | None = None,
+        once: bool = False,
+    ) -> str:
+        """注册 prompt hook。"""
+        config: dict[str, Any] = {
+            "prompt": prompt,
+            "runner": runner,
+            "if": condition,
+            "once": once,
+        }
+        if model is not None:
+            config["model"] = model
+        spec = self._make_spec(
+            event=event,
+            executor_type="prompt",
+            config=config,
+            matcher=matcher,
+            timeout=timeout,
+            source="session",
+            once=once,
+        )
+        self._specs.append(spec)
+        return spec.hook_id
+
+    def add_agent(
+        self,
+        event: HookEvent,
+        prompt: str,
+        runner: Callable,
+        *,
+        matcher: str = "*",
+        timeout: float = 60.0,
+        model: str | None = None,
+        condition: str | None = None,
+        once: bool = False,
+    ) -> str:
+        """注册 agent hook。"""
+        config: dict[str, Any] = {
+            "prompt": prompt,
+            "runner": runner,
+            "if": condition,
+            "once": once,
+        }
+        if model is not None:
+            config["model"] = model
+        spec = self._make_spec(
+            event=event,
+            executor_type="agent",
+            config=config,
+            matcher=matcher,
+            timeout=timeout,
+            source="session",
+            once=once,
+        )
+        self._specs.append(spec)
+        return spec.hook_id
+
+    # ── 桥接到引擎层 ──
+
+    def build_snapshot(self) -> HooksConfigSnapshot:
+        """将注册的所有 spec 构建为 HooksConfigSnapshot，供 HookEngine 消费。"""
+        snapshot = HooksConfigSnapshot()
+        for spec in self._specs:
+            snapshot.add_spec(spec)
+        self._snapshots.append(snapshot)
+        return snapshot
+
+    def __len__(self) -> int:
+        return len(self._specs)
+
+    def _make_spec(
+        self,
+        *,
+        event: HookEvent,
+        executor_type: str,
+        config: dict[str, Any],
+        matcher: str,
+        timeout: float,
+        source: str,
+        managed: bool = False,
+        once: bool = False,
+    ) -> HookSpec:
+        spec = HookSpec(
+            event=event,
+            executor_type=executor_type,
+            config=config,
+            matcher=matcher,
+            timeout=timeout,
+            managed=managed,
+            source=source,
+            once=once,
+        )
+        if once:
+            spec.on_success = lambda hook_id=spec.hook_id: self.remove(hook_id)
+        return spec
+
+
+__all__ = ["HookRegistry"]

langchain_agentx/loop/hook/trust.py

@@ -0,0 +1,43 @@
+"""
+trust.py — Hook 执行信任闸门。
+
+职责：
+    在 HookEngine 执行前判断当前工作区信任状态，决定是否跳过高风险执行器。
+
+链路位置：
+    HookEngine.execute() 入口处调用，集中拦截 command/http/agent。
+
+当前裁剪范围：
+    仅提供 should_skip/skip_reason 判断，不负责 trust 交互与持久化。
+"""
+
+from __future__ import annotations
+
+HIGH_RISK_EXECUTORS = frozenset({"command", "http", "agent"})
+
+
+class WorkspaceTrustChecker:
+    """Hook 执行前的工作区信任检查器。"""
+
+    def __init__(
+        self,
+        *,
+        headless: bool = False,
+        workspace_trust_accepted: bool = False,
+    ) -> None:
+        self._headless = headless
+        self._workspace_trust_accepted = workspace_trust_accepted
+
+    def should_skip(self, executor_type: str) -> bool:
+        if executor_type not in HIGH_RISK_EXECUTORS:
+            return False
+        return not self._workspace_trust_accepted
+
+    def skip_reason(self, executor_type: str) -> str:
+        return (
+            "workspace trust not accepted; "
+            f"executor type '{executor_type}' requires trusted workspace"
+        )
+
+
+__all__ = ["HIGH_RISK_EXECUTORS", "WorkspaceTrustChecker"]