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

langchain_agentx/tool_runtime/policy.py

@@ -0,0 +1,447 @@
+"""
+runtime/policy.py — 工具权限策略引擎
+
+职责：
+    提供可复用的最小策略层，将工具本地校验（validate_input）与
+    全局权限治理（check_permissions）分开。PolicyEngine 作为可注入
+    的策略对象，由 RuntimeTool.__init__ 接收，在 check_permissions
+    默认实现中委托调用。
+
+    DefaultPolicyEngine 实现 v1.5 范围：
+        - read_roots / write_roots 读写分离路径限制
+        - deny_globs 用户自定义禁止模式匹配
+        - ask_globs 需要人工确认的敏感路径模式（headless 时降级为 deny）
+        - enable_builtin_deny 内置危险路径黑名单（.env/.ssh/*.key 等）
+        - read_only_mode 全局只读
+        - allow / deny / ask 三种决策
+
+    决策优先级（严格顺序）：
+        [1] read_only_mode + is_destructive → deny
+        [2] enable_builtin_deny → 内置黑名单 → deny
+        [3] deny_globs 命中 → deny
+        [4] ask_globs 命中 → ask（headless 模式下由 pipeline 降级为 deny）
+        [5] 读写分权：is_read_only → read_roots；否则 → write_roots
+        [6] 通过 → allow
+
+与 CC 对比：
+    CC 的权限系统分三层：
+        Layer 1: 每个工具的 checkPermissions()
+        Layer 2: hasPermissionsToUseToolInner() 全局引擎
+                 alwaysDenyRules → alwaysAskRules → alwaysAllowRules → PermissionMode
+        Layer 3: HITL race（User UI + Hooks + Classifier + Bridge）
+    本框架 v1.5 实现 Layer 1 + Layer 2 完整版：
+        - deny_globs + BUILTIN_DENY_GLOBS 对应 CC alwaysDenyRules
+        - ask_globs 对应 CC alwaysAskRules（需人工确认路径）
+        - read_roots / write_roots 对应 CC allWorkingDirectories
+        - headless 模式 ask → deny 对应 CC shouldAvoidPermissionPrompts
+        - HITL 交互（Layer 3 完整 race）延期到 v2
+
+    详细设计见 docs/design-docs/tool-runtime/tool-permission-system.md
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import AuthorizationDecision, ToolExecutionContext
+from .permission_context import get_active_auto_approved_tools
+
+
+# ---------------------------------------------------------------------------
+# ToolPolicyConfig
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolPolicyConfig:
+    """
+    工具策略配置。
+
+    read_roots:         允许读操作的路径根列表（read/glob/grep 等只读工具）。
+                        空列表 = 不限制（开发模式）。
+    write_roots:        允许写操作的路径根列表（write/edit/bash 等写工具）。
+                        通常是 read_roots 的子集。空列表 = 不限制（开发模式）。
+    deny_globs:         硬拒绝的 glob 模式列表，优先级高于 roots 检查。
+                        对应 CC alwaysDenyRules。
+                        示例：["**/secrets/**", "**/*.prod.env"]
+    ask_globs:          需要人工确认的敏感路径 glob 模式列表。
+                        对应 CC alwaysAskRules。
+                        headless 模式下自动降级为 deny；交互模式下触发 HITL。
+                        示例：["**/config/**", "**/.claude/**"]
+    read_only_mode:     全局只读模式，is_destructive=True 的工具直接拒绝。
+    enable_builtin_deny: 启用内置危险路径保护（.env/.ssh/*.key/credentials 等）。
+                        生产环境建议保持 True。
+    """
+
+    read_roots: list[str] = field(default_factory=list)
+    write_roots: list[str] = field(default_factory=list)
+    deny_globs: list[str] = field(default_factory=list)
+    ask_globs: list[str] = field(default_factory=list)
+    read_only_mode: bool = False
+    enable_builtin_deny: bool = True
+
+
+# ---------------------------------------------------------------------------
+# PolicyEngine 抽象基类
+# ---------------------------------------------------------------------------
+
+class PolicyEngine(ABC):
+    """
+    权限策略引擎抽象基类。
+
+    由 RuntimeTool.check_permissions() 默认实现委托调用。
+    子类实现 authorize() / aauthorize() 提供具体策略决策。
+    """
+
+    @abstractmethod
+    def authorize(
+        self,
+        *,
+        tool_name: str,
+        input_data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        """同步授权决策。"""
+        ...
+
+    async def aauthorize(
+        self,
+        *,
+        tool_name: str,
+        input_data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        """
+        异步授权决策，默认委托同步 authorize()。
+        有真正异步需求（如远程策略服务）的子类可覆盖。
+        """
+        return self.authorize(tool_name=tool_name, input_data=input_data, ctx=ctx)
+
+
+# ---------------------------------------------------------------------------
+# DefaultPolicyEngine — v1 实现
+# ---------------------------------------------------------------------------
+
+class DefaultPolicyEngine(PolicyEngine):
+    """
+    v1.5 默认策略引擎。
+
+    决策优先级（严格顺序）：
+        [1] read_only_mode + is_destructive → deny      最高优先级
+        [2] enable_builtin_deny → BUILTIN_DENY_GLOBS → deny
+        [3] deny_globs 命中 → deny
+        [4] ask_globs 命中 → ask（headless 时 pipeline 降级为 deny）
+        [5] 读写分权：
+              is_read_only=True  → 检查 read_roots
+              is_read_only=False → 检查 write_roots
+              roots 为空列表 → 跳过，视为不限制
+        [6] 通过 → allow
+
+    对应 CC：
+        [1] ~ read_only_mode（全局禁止写操作）
+        [2][3] ~ alwaysDenyRules（固定拒绝）
+        [4] ~ alwaysAskRules（需确认）
+        [5] ~ allWorkingDirectories（访问空间限制）
+
+    工具读写标志来源：
+        从 ctx.tool_flags["is_read_only"] / ctx.tool_flags["is_destructive"] 读取。
+        由 LangChainAdapter.build_tool_execution_context() 在构造 ctx 时注入。
+
+    路径提取规则：
+        从 input_data 中按优先级查找路径字段：file_path > path > pattern
+        找不到路径字段时跳过路径相关检查（直接 allow）。
+
+    路径校验：
+        使用 realpath 双检（对 path 和 root 均做 realpath），
+        防路径遍历（../）、符号链接绕过、前缀误匹配。
+    """
+
+    # 按优先级尝试的路径字段名
+    _PATH_FIELDS = ("file_path", "path", "pattern")
+
+    # 内置危险路径黑名单，对应 CC 的危险目录/文件检查
+    BUILTIN_DENY_GLOBS: list[str] = [
+        # 环境变量 / 配置
+        "**/.env", "**/.env.*", "**/*.env",
+        # SSH 密钥
+        "**/id_rsa", "**/id_rsa.pub", "**/id_ed25519", "**/id_ed25519.pub",
+        "**/.ssh/**",
+        # 证书与密钥文件
+        "**/*.pem", "**/*.key", "**/*.p12", "**/*.pfx",
+        # 云服务凭证
+        "**/.aws/credentials", "**/.aws/config",
+        "**/.gcp/**", "**/service-account*.json",
+        # 密码/密钥目录
+        "**/secrets/**", "**/.secrets/**", "**/credentials/**",
+    ]
+
+    def __init__(self, config: ToolPolicyConfig) -> None:
+        self._config = config
+        self._read_roots = [os.path.realpath(r) for r in config.read_roots]
+        self._write_roots = [os.path.realpath(r) for r in config.write_roots]
+
+    def authorize(
+        self,
+        *,
+        tool_name: str,
+        input_data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        tool_flags = ctx.tool_flags if hasattr(ctx, "tool_flags") else {}
+        is_destructive = tool_flags.get("is_destructive", False)
+        is_read_only_tool = tool_flags.get("is_read_only", True)
+        active_auto_approved_tools = get_active_auto_approved_tools(
+            getattr(ctx, "session_store", None)
+        )
+        active_auto_approved_tools_lower = {
+            name.lower() for name in active_auto_approved_tools
+        }
+
+        # [1] 全局只读模式：拒绝破坏性工具
+        if self._config.read_only_mode and is_destructive:
+            return self._with_decision_source(
+                AuthorizationDecision(
+                behavior="deny",
+                message="Operation not permitted: agent is in read-only mode.",
+                policy_id="read_only_mode",
+                ),
+                matched_rule="read_only_mode",
+            )
+
+        # Bash 工具按“命令字符串”做规则匹配，不参与路径 roots 校验。
+        # 对齐 docs/design-docs/tool-design/bash-tool.md 的 v2 方案。
+        if tool_name == "bash":
+            command = input_data.get("command")
+            if not isinstance(command, str) or not command.strip():
+                return AuthorizationDecision(behavior="allow")
+
+            deny_result = self._check_deny_globs(command)
+            if deny_result is not None:
+                return self._with_decision_source(
+                    deny_result,
+                    matched_rule=deny_result.policy_id,
+                )
+
+            ask_result = self._check_ask_globs(command)
+            if ask_result is not None:
+                return self._with_decision_source(
+                    ask_result,
+                    matched_rule=ask_result.policy_id,
+                )
+
+            return self._with_decision_source(
+                AuthorizationDecision(behavior="allow"),
+                matched_rule="default_allow",
+            )
+
+        # 提取并规范化路径字段
+        path = self._extract_path(input_data)
+        if path is None:
+            return self._with_decision_source(
+                AuthorizationDecision(behavior="allow"),
+                matched_rule="no_path_field",
+            )
+
+        real_path = os.path.realpath(os.path.expanduser(path))
+
+        # [2] 用户自定义 deny_globs
+        deny_result = self._check_deny_globs(real_path)
+        if deny_result is not None:
+            return self._with_decision_source(
+                deny_result,
+                matched_rule=deny_result.policy_id,
+            )
+
+        # [3] 内置危险路径黑名单
+        if self._config.enable_builtin_deny:
+            for pattern in self.BUILTIN_DENY_GLOBS:
+                if fnmatch.fnmatch(real_path, pattern):
+                    return self._with_decision_source(
+                        AuthorizationDecision(
+                            behavior="deny",
+                            message="Permission denied: access to this path is not allowed.",
+                            policy_id="builtin_deny",
+                        ),
+                        matched_rule="builtin_deny",
+                    )
+
+        # [4] ask_globs：敏感路径需要人工确认
+        # headless 模式下 pipeline 会将 ask 自动降级为 deny；交互模式触发 HITL
+        ask_result = self._check_ask_globs(real_path)
+        if ask_result is not None:
+            if tool_name.lower() in active_auto_approved_tools_lower:
+                decision = AuthorizationDecision(
+                    behavior="allow",
+                    policy_id="skill_auto_approved_bypass_ask",
+                    metadata={
+                        "tool_name": tool_name,
+                        "source": "skill_allowed_tools",
+                        "decision_trace": [
+                            {
+                                "stage": "ask_globs",
+                                "matched": True,
+                                "decision": "allow",
+                                "reason": "skill_auto_approved_bypass_ask",
+                                "tool_name": tool_name,
+                                "active_auto_approved_tools": sorted(active_auto_approved_tools),
+                            }
+                        ],
+                    },
+                )
+                return self._with_decision_source(
+                    decision,
+                    matched_rule="skill_auto_approved_bypass_ask",
+                )
+            return self._with_decision_source(
+                ask_result,
+                matched_rule=ask_result.policy_id,
+            )
+
+        # [5] 读写分权根目录检查
+        roots = self._read_roots if is_read_only_tool else self._write_roots
+        if roots:
+            if not any(self._within_root(real_path, r) for r in roots):
+                return self._with_decision_source(
+                    AuthorizationDecision(
+                        behavior="deny",
+                        message="Permission denied: path is outside the allowed workspace.",
+                        policy_id="read_roots" if is_read_only_tool else "write_roots",
+                    ),
+                    matched_rule="read_roots" if is_read_only_tool else "write_roots",
+                )
+
+        return self._with_decision_source(
+            AuthorizationDecision(behavior="allow"),
+            matched_rule="default_allow",
+        )
+
+    def authorize_path(
+        self,
+        path: str,
+        *,
+        is_write: bool,
+    ) -> AuthorizationDecision:
+        """
+        对单个文件系统路径做授权。
+
+        供 BashRuntimeTool v2 的路径安全层调用，避免 bash 因 command-string
+        特殊分支而跳过 read_roots / write_roots / builtin deny 检查。
+        """
+        real_path = os.path.realpath(os.path.expanduser(path))
+
+        if self._config.read_only_mode and is_write:
+            return self._with_decision_source(
+                AuthorizationDecision(
+                behavior="deny",
+                message="Operation not permitted: agent is in read-only mode.",
+                policy_id="read_only_mode",
+                ),
+                matched_rule="read_only_mode",
+            )
+
+        deny_result = self._check_deny_globs(real_path)
+        if deny_result is not None:
+            return self._with_decision_source(
+                deny_result,
+                matched_rule=deny_result.policy_id,
+            )
+
+        if self._config.enable_builtin_deny:
+            for pattern in self.BUILTIN_DENY_GLOBS:
+                if fnmatch.fnmatch(real_path, pattern):
+                    return self._with_decision_source(
+                        AuthorizationDecision(
+                        behavior="deny",
+                        message="Permission denied: access to this path is not allowed.",
+                        policy_id="builtin_deny",
+                        ),
+                        matched_rule="builtin_deny",
+                    )
+
+        ask_result = self._check_ask_globs(real_path)
+        if ask_result is not None:
+            return self._with_decision_source(
+                ask_result,
+                matched_rule=ask_result.policy_id,
+            )
+
+        roots = self._write_roots if is_write else self._read_roots
+        if roots:
+            if not any(self._within_root(real_path, root) for root in roots):
+                return self._with_decision_source(
+                    AuthorizationDecision(
+                        behavior="deny",
+                        message="Permission denied: path is outside the allowed workspace.",
+                        policy_id="write_roots" if is_write else "read_roots",
+                    ),
+                    matched_rule="write_roots" if is_write else "read_roots",
+                )
+
+        return self._with_decision_source(
+            AuthorizationDecision(behavior="allow"),
+            matched_rule="default_allow",
+        )
+
+    # ---- 内部辅助 ----
+
+    def _extract_path(self, input_data: dict[str, Any]) -> str | None:
+        for field_name in self._PATH_FIELDS:
+            val = input_data.get(field_name)
+            if isinstance(val, str) and val:
+                return val
+        return None
+
+    def _check_deny_globs(self, real_path: str) -> AuthorizationDecision | None:
+        for glob_pattern in self._config.deny_globs:
+            if fnmatch.fnmatch(real_path, glob_pattern):
+                return AuthorizationDecision(
+                    behavior="deny",
+                    message="Permission denied: path matches a restricted pattern.",
+                    policy_id=f"deny_glob:{glob_pattern}",
+                )
+        return None
+
+    @staticmethod
+    def _with_decision_source(
+        decision: AuthorizationDecision,
+        *,
+        matched_rule: str | None,
+    ) -> AuthorizationDecision:
+        meta = dict(decision.metadata or {})
+        meta.setdefault("rule_source", "default_policy_engine")
+        if matched_rule is not None:
+            meta.setdefault("matched_rule", matched_rule)
+        decision.metadata = meta
+        return decision
+
+    def _check_ask_globs(self, real_path: str) -> AuthorizationDecision | None:
+        """
+        检查路径是否命中 ask_globs（需要人工确认的敏感路径）。
+        命中时返回 behavior="ask"，由 pipeline 根据 headless 标志决定后续处理：
+            headless=True  → pipeline 自动降级为 deny
+            headless=False → pipeline 抛出 PermissionAskInterrupt
+        """
+        for glob_pattern in self._config.ask_globs:
+            if fnmatch.fnmatch(real_path, glob_pattern):
+                return AuthorizationDecision(
+                    behavior="ask",
+                    ask_prompt=(
+                        f"Tool wants to access a sensitive path: {real_path}\n"
+                        f"(matched pattern: {glob_pattern})\n"
+                        f"Allow this operation?"
+                    ),
+                    policy_id=f"ask_glob:{glob_pattern}",
+                )
+        return None
+
+    @staticmethod
+    def _within_root(path: str, root: str) -> bool:
+        """
+        判断 path 是否在 root 目录内。
+        root 已在 __init__ 中 realpath，path 在调用前已 realpath，
+        使用 os.sep 边界确保不会前缀误匹配（如 /proj 不会匹配 /proj_evil）。
+        """
+        return path == root or path.startswith(root.rstrip(os.sep) + os.sep)

langchain_agentx/tool_runtime/registry.py

@@ -0,0 +1,81 @@
+"""
+runtime/registry.py — 工具注册表
+
+职责：
+    管理所有 RuntimeTool 的注册与查询。
+    register() 只存储 RuntimeTool，不构造 StructuredTool。
+    to_langchain_tools() 在需要时按需构造 StructuredTool；控制面由 RunnableConfig 注入。
+
+与 CC 对比：
+    CC 中工具通过静态 TOOLS 数组集中声明，没有显式注册表。
+    本框架引入 RuntimeToolRegistry 作为运行时注册中心，支持动态注册。
+    StructuredTool 构造时序由 factory 控制（需 state 生命周期对齐），不在注册时提前构造。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+from .adapter import LangChainAdapter
+from .base import RuntimeTool
+from .errors import ToolNotFoundError, ToolRegistrationError
+from .pipeline import ToolExecutorPipeline
+
+
+class RuntimeToolRegistry:
+    """
+    工具注册表。
+
+    register(tool)                      — 注册 RuntimeTool，工具名重复时抛 ToolRegistrationError
+    get(name)                           — 按名查询 RuntimeTool，不存在时抛 ToolNotFoundError
+    list()                              — 返回所有已注册 RuntimeTool 列表
+    to_langchain_tools()                — 按需构造 StructuredTool 列表
+    """
+
+    def __init__(
+        self,
+        *,
+        pipeline: ToolExecutorPipeline,
+        adapter: LangChainAdapter,
+    ) -> None:
+        self._pipeline = pipeline
+        self._adapter = adapter
+        self._tools: dict[str, RuntimeTool] = {}
+
+    def register(self, tool: RuntimeTool) -> None:
+        """注册一个 RuntimeTool。工具名重复时抛 ToolRegistrationError。"""
+        if tool.name in self._tools:
+            raise ToolRegistrationError(tool.name)
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> RuntimeTool:
+        """按名查询 RuntimeTool。不存在时抛 ToolNotFoundError。"""
+        if name not in self._tools:
+            raise ToolNotFoundError(name)
+        return self._tools[name]
+
+    def list(self) -> list[RuntimeTool]:
+        """返回所有已注册 RuntimeTool 列表（按注册顺序）。"""
+        return list(self._tools.values())
+
+    def to_langchain_tools(self) -> list[BaseTool]:
+        """按需构造并返回所有 StructuredTool。"""
+        return [
+            self._adapter.build_structured_tool(
+                tool=t,
+                pipeline=self._pipeline,
+            )
+            for t in self._tools.values()
+        ]
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def __repr__(self) -> str:
+        names = list(self._tools.keys())
+        return f"<RuntimeToolRegistry tools={names}>"

langchain_agentx/tool_runtime/resolvers/__init__.py

@@ -0,0 +1,27 @@
+"""
+tool_runtime/resolvers/ — ask 分支权限 resolver 集合
+
+职责：
+    汇总导出 PermissionResolver 协议与四类场景实现。
+
+链路位置：
+    由会话/工作流装配层注入 ToolExecutorPipeline。
+
+当前裁剪范围：
+    仅提供 resolver 定义与基础实现，不负责 UI 事件循环集成。
+"""
+
+from .agent_session import AgentSessionPermissionResolver, PermissionRequest
+from .background import BackgroundPermissionResolver
+from .base import PermissionResolver
+from .conversation import ConversationPermissionResolver
+from .workflow import WorkflowPermissionResolver
+
+__all__ = [
+    "PermissionResolver",
+    "PermissionRequest",
+    "AgentSessionPermissionResolver",
+    "ConversationPermissionResolver",
+    "BackgroundPermissionResolver",
+    "WorkflowPermissionResolver",
+]

langchain_agentx/tool_runtime/resolvers/agent_session.py

@@ -0,0 +1,125 @@
+"""
+tool_runtime/resolvers/agent_session.py — CLI 会话权限确认 resolver
+
+职责：
+    在同进程交互场景中通过 asyncio.Queue + Future 等待用户批准/拒绝。
+
+链路位置：
+    AgentSession 注入 resolver -> ToolExecutorPipeline ask 分支 await。
+
+当前裁剪范围：
+    仅实现单路 UI 队列确认，不实现 hook/classifier 多路 race。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable
+
+
+@dataclass
+class PermissionRequest:
+    tool_name: str
+    ask_prompt: str | None
+    future: asyncio.Future[bool]
+    created_at: float = field(default_factory=time.monotonic)
+
+
+class _OnceGuard:
+    """多路 race 原子 claim，防止重复 resolve。"""
+
+    def __init__(self) -> None:
+        self._claimed = False
+        self._lock = asyncio.Lock()
+
+    async def claim(self) -> bool:
+        async with self._lock:
+            if self._claimed:
+                return False
+            self._claimed = True
+            return True
+
+
+class AgentSessionPermissionResolver:
+    """CLI 交互 resolver：支持 UI future 与 hook 决策多路 race。"""
+
+    def __init__(
+        self,
+        request_queue: asyncio.Queue[PermissionRequest],
+        *,
+        timeout: float = 300.0,
+        hook_runner: Callable[[str, str | None], Awaitable[bool | None]] | None = None,
+    ) -> None:
+        self._queue = request_queue
+        self._timeout = timeout
+        self._hook_runner = hook_runner
+
+    async def __call__(self, tool_name: str, ask_prompt: str | None) -> bool:
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[bool] = loop.create_future()
+        await self._queue.put(
+            PermissionRequest(
+                tool_name=tool_name,
+                ask_prompt=ask_prompt,
+                future=future,
+            )
+        )
+        guard = _OnceGuard()
+        ui_task = asyncio.create_task(self._await_ui_future(future, guard))
+        tasks: list[asyncio.Task[bool | None]] = [ui_task]
+        if self._hook_runner is not None:
+            tasks.append(asyncio.create_task(self._await_hook_decision(tool_name, ask_prompt, guard, future)))
+        try:
+            done, pending = await asyncio.wait(
+                tasks,
+                timeout=self._timeout,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if not done:
+                return False
+            result = done.pop().result()
+            return bool(result)
+        except asyncio.TimeoutError:
+            return False
+        finally:
+            for task in tasks:
+                if not task.done():
+                    task.cancel()
+            if not future.done():
+                future.cancel()
+
+    async def _await_ui_future(self, future: asyncio.Future[bool], guard: _OnceGuard) -> bool | None:
+        try:
+            result = await asyncio.wait_for(future, timeout=self._timeout)
+        except asyncio.TimeoutError:
+            if await guard.claim():
+                return False
+            return None
+        except asyncio.CancelledError:
+            return None
+        if await guard.claim():
+            return result
+        return None
+
+    async def _await_hook_decision(
+        self,
+        tool_name: str,
+        ask_prompt: str | None,
+        guard: _OnceGuard,
+        ui_future: asyncio.Future[bool],
+    ) -> bool | None:
+        if self._hook_runner is None:
+            return None
+        hook_result = await self._hook_runner(tool_name, ask_prompt)
+        if hook_result is None:
+            return None
+        if await guard.claim():
+            if not ui_future.done():
+                ui_future.cancel()
+            return bool(hook_result)
+        return None
+
+
+__all__ = ["PermissionRequest", "AgentSessionPermissionResolver"]