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

langchain_agentx/tool_runtime/loader.py

@@ -0,0 +1,195 @@
+"""
+runtime/loader.py — 工具运行时框架进程级初始化入口
+
+职责：
+    进程级一次性初始化，组装框架核心组件（pipeline / policy / registry）并统一管理工具注册。
+    loader 只负责注册 RuntimeTool，不构造 StructuredTool。
+    StructuredTool 构造由 factory（create_loop_agent）在 graph 构建时负责，
+    通过 create_loop_agent(loader=...) 在构图时调用 to_langchain_tools() 构造 StructuredTool。
+
+    policy_config 用于构造 DefaultPolicyEngine，在 register() 时自动注入给每个工具。
+    工具无需手动传入 policy，由 loader 统一治理。
+
+装配路径：
+    ToolRuntimeLoader(policy_config=...) 构造
+        → DefaultPolicyEngine(policy_config)
+        → register(tool): 只存储 RuntimeTool，注入 policy
+        → 传入 create_loop_agent(loader=loader, ...)
+        → factory 内部调用 loader._registry.to_langchain_tools() 构造 StructuredTool
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.tools import BaseTool
+
+from .adapter import LangChainAdapter
+from .base import RuntimeTool
+from .pipeline import ToolExecutorPipeline, ToolOutputManager
+from .policy import DefaultPolicyEngine, PolicyEngine, ToolPolicyConfig
+from .registry import RuntimeToolRegistry
+from .resolvers import PermissionResolver
+from .session_store import AgentSessionStore
+
+
+class ToolRuntimeLoader:
+    """
+    工具运行时进程级装配入口。
+
+    policy_config:  策略配置，构造 DefaultPolicyEngine 并自动注入给所有注册工具。
+                    为 None 时不注入 policy（工具默认 allow，适用于开发/测试模式）。
+    policy_engine:  直接传入自定义 PolicyEngine 实例（优先于 policy_config）。
+    output_manager: 工具输出大小管控器，为 None 时使用默认配置。
+    headless:       是否处于无交互（headless）模式。
+                    True  — check_permissions 返回 ask 时自动降级为 deny（API 调用、CI、批处理场景）。
+                    False — check_permissions 返回 ask 时抛出 PermissionAskInterrupt（交互场景，默认）。
+                    对应 CC 的 shouldAvoidPermissionPrompts / isNonInteractiveSession。
+    """
+
+    def __init__(
+        self,
+        *,
+        policy_config: ToolPolicyConfig | None = None,
+        policy_engine: PolicyEngine | None = None,
+        output_manager: ToolOutputManager | None = None,
+        headless: bool = False,
+        permission_resolver: PermissionResolver | None = None,
+    ) -> None:
+        self._headless = headless
+        self._permission_resolver = permission_resolver
+        self._pipeline = ToolExecutorPipeline(
+            output_manager=output_manager,
+            headless=headless,
+            permission_resolver=permission_resolver,
+        )
+        self._adapter = LangChainAdapter()
+        self._registry = RuntimeToolRegistry(
+            pipeline=self._pipeline,
+            adapter=self._adapter,
+        )
+        # 优先使用外部传入的 policy_engine；其次从 policy_config 构造；否则为 None
+        if policy_engine is not None:
+            self._policy: PolicyEngine | None = policy_engine
+        elif policy_config is not None:
+            self._policy = DefaultPolicyEngine(policy_config)
+        else:
+            self._policy = None
+
+    def register(self, tool: RuntimeTool) -> "ToolRuntimeLoader":
+        """
+        注册工具并自动注入 PolicyEngine。
+
+        注入规则：
+            - 工具已有 _policy（初始化时手动传入）→ 不覆盖，保留工具自己的 policy
+            - 工具无 _policy（_policy is None）→ 注入 loader 的统一 policy
+        这允许个别工具使用专属 policy，其余工具统一受 loader policy 保护。
+        """
+        if self._policy is not None and getattr(tool, "_policy", None) is None:
+            tool._policy = self._policy
+        self._registry.register(tool)
+        return self
+
+    def register_default_tools(
+        self,
+        *,
+        workspace_root: str,
+        agent_home: str = ".langchain_agentx",
+        include_agent: bool = True,
+        include_skill: bool = False,
+        agent_registry: Any | None = None,
+    ) -> "ToolRuntimeLoader":
+        """
+        注册默认工具集（Read/Grep/Glob/Bash + 可选 Agent/Skill）。
+
+        用于打通默认工具装配链路，避免每个调用方重复手写 register 序列。
+        """
+        from pathlib import Path
+
+        from langchain_agentx.tools.bash import BashRuntimeTool
+        from langchain_agentx.tools.glob import GlobRuntimeTool
+        from langchain_agentx.tools.grep import GrepRuntimeTool
+        from langchain_agentx.tools.read import ReadRuntimeTool
+        from langchain_agentx.tools.ripgrep_plugin_exclusions import PluginCacheGlobExclusions
+        from langchain_agentx.tool_runtime.state_bridge import ToolStateBridge
+        from langchain_agentx.workspace.config import AgentWorkspaceConfig
+
+        self.register(ReadRuntimeTool())
+        default_tool_state_bridge = ToolStateBridge()
+        wr = Path(workspace_root).resolve()
+        cfg = AgentWorkspaceConfig(workspace_root=wr, agent_home=agent_home)
+        plugin_ex = PluginCacheGlobExclusions(
+            cache_root=str(cfg.plugin_cache_dir.resolve()),
+        )
+        self.register(
+            GrepRuntimeTool(
+                workspace_root=str(wr),
+                plugin_cache_glob_exclusions=plugin_ex,
+            )
+        )
+        self.register(
+            GlobRuntimeTool(
+                workspace_root=str(wr),
+                plugin_cache_glob_exclusions=plugin_ex,
+                state_bridge=default_tool_state_bridge,
+            )
+        )
+        self.register(BashRuntimeTool())
+
+        if include_agent:
+            from langchain_agentx.tools.agent import AgentRuntimeTool
+
+            self.register(AgentRuntimeTool(registry=agent_registry))
+
+        if include_skill:
+            from langchain_agentx.tools.skill import SkillRuntimeTool
+
+            self.register(
+                SkillRuntimeTool(
+                    workspace_root=workspace_root,
+                    agent_home=agent_home,
+                )
+            )
+
+        return self
+
+    def create_session(self, session_id: str | None = None) -> AgentSessionStore:
+        return AgentSessionStore(session_id=session_id)
+
+    def fork_with_tools(self, tools: list[RuntimeTool]) -> "ToolRuntimeLoader":
+        """
+        基于当前 loader 派生一个子 loader（共享 policy/headless 语义），并注册给定工具集。
+
+        目的：为 subagent 组装“过滤后的工具池”而不丢失权限/管控语义。
+        """
+        child = ToolRuntimeLoader(
+            policy_engine=self._policy,
+            headless=self._headless,
+            permission_resolver=self._permission_resolver,
+        )
+        for t in tools:
+            child.register(t)
+        return child
+
+    def set_permission_resolver(
+        self,
+        permission_resolver: PermissionResolver | None,
+    ) -> None:
+        """更新 loader 与 pipeline 的 permission_resolver。"""
+        self._permission_resolver = permission_resolver
+        self._pipeline.set_permission_resolver(permission_resolver)
+
+    @property
+    def registry(self) -> RuntimeToolRegistry:
+        return self._registry
+
+    @property
+    def pipeline(self) -> ToolExecutorPipeline:
+        return self._pipeline
+
+    @property
+    def adapter(self) -> LangChainAdapter:
+        return self._adapter
+
+    def __repr__(self) -> str:
+        return f"<ToolRuntimeLoader tools={list(self._registry._tools.keys())}>"

langchain_agentx/tool_runtime/models.py

@@ -0,0 +1,260 @@
+"""
+runtime/models.py — 工具运行时框架核心数据模型
+
+职责：
+    定义框架内部所有稳定的数据契约（Named Spec），包括：
+    - ToolExecutionContext：运行时归一化上下文，隔离 LangGraph 底层依赖
+    - ToolResultEnvelope：工具执行统一内部结果协议，分离模型可见输出与内部数据
+    - ValidationResult：输入语义校验结果（失败时告知模型，模型可修正重试）
+    - AuthorizationDecision：权限授权决策（失败时策略拒绝，不可绕过）
+    - ToolErrorInfo / ToolHint / ToolArtifact：辅助结构
+
+与 CC 对比：
+    CC Tool.ts 中 ToolUseContext 是一个大而全的上下文对象，包含 abortController、
+    readFileState、getAppState、messages 等大量 UI/应用层字段。
+    本框架的 ToolExecutionContext 只保留框架稳定依赖的最小字段集，
+    UI/应用层依赖由 LangChainAdapter 在边界处消费，不透传到工具内部。
+    协作取消：``cancel_event`` 对应 CC ``AbortSignal``（由上层 ``set()`` 终止 ripgrep 等子进程）。
+
+    CC 的 ValidationResult / PermissionResult 是 TypeScript union type。
+    本框架用 dataclass 实现等价语义，保持 Python 风格。
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, MutableMapping
+
+
+from .session_store import AgentSessionStore
+
+
+# ---------------------------------------------------------------------------
+# ToolExecutionContext
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolExecutionContext:
+    """
+    运行时归一化上下文。
+
+    由 LangChainAdapter.build_tool_execution_context() 从 RunnableConfig 构造，
+    隔离 LangGraph / RunnableConfig 等底层依赖，工具内部只依赖此对象。
+
+    字段来源：
+        tool_name       — RuntimeTool.name
+        tool_call_id    — RunnableConfig.configurable["tool_call_id"]
+        input_args      — 归一化后的输入 dict
+        state           — LangGraph state 引用（工具可读写）
+        now_ts          — pipeline 入口时间戳
+        thread_id       — RunnableConfig.configurable.get("thread_id")
+        run_id          — RunnableConfig.configurable.get("run_id")
+        actor           — 当前版本固定 "agent"
+        tool_flags      — 工具行为标志（由 LangChainAdapter 从 RuntimeTool 类属性注入）
+                          {"is_read_only": bool, "is_destructive": bool}
+                          PolicyEngine 从此处读取读写属性，不污染 input_data。
+
+    父 loop 控制面（由 LangChainAdapter 从 RunnableConfig.configurable["loop_config"] 填充，工具层只读）：
+        model           — 父 loop 当前模型，子代理继承的 SSOT；对应 CC options.mainLoopModel
+                          来源：AgentLoopConfig.model
+        available_tools — 父工具池视图，子代理工具池组装的基础；对应 CC options.tools
+                          来源：AgentLoopConfig.available_tools
+        agent_id        — 当前 agent ID，用于日志与追踪；对应 CC agentId
+                          来源：state["agent_id"]
+        agent_depth     — 嵌套深度，防止无限递归；对应 CC queryTracking.depth
+                          来源：state["agent_depth"]
+    """
+
+    tool_name: str
+    tool_call_id: str | None
+    input_args: dict[str, Any]
+    state: MutableMapping[str, Any]
+    now_ts: float = field(default_factory=time.time)
+    thread_id: str | None = None
+    run_id: str | None = None
+    session_id: str | None = None
+    conversation_session_id: str | None = None
+    actor: Literal["agent", "human", "system"] = "agent"
+    session_store: AgentSessionStore | None = field(default=None)
+    tool_loader: Any | None = None
+    tool_registry: Any | None = None
+    tool_flags: dict[str, Any] = field(default_factory=dict)
+    """
+    工具行为标志，由 LangChainAdapter.build_tool_execution_context() 注入。
+    标准键：
+        is_read_only    — 对应 RuntimeTool.is_read_only
+        is_destructive  — 对应 RuntimeTool.is_destructive
+    PolicyEngine.authorize() 从此处读取，避免污染 input_data。
+    """
+    # 父 loop 控制面
+    model: Any | None = None
+    available_tools: list[Any] = field(default_factory=list)
+    agent_id: str | None = None
+    agent_depth: int = 0
+    workspace_root: str | None = None
+    agent_home: str = ".langchain_agentx"
+    cwd: str | None = None  # 工具执行时的路径基准（CC 对照：getCwd()）
+    trace_enabled: bool = True
+    cancel_event: threading.Event | None = None
+    """可选；由 ``RunnableConfig.configurable[\"cancel_event\"]`` 注入。set 后 Grep/Glob 应中断 rg。"""
+
+
+# ---------------------------------------------------------------------------
+# 辅助结构
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolErrorInfo:
+    """工具执行错误细节，附在 ToolResultEnvelope.error 上。"""
+
+    message: str
+    code: str | None = None
+    exception_type: str | None = None
+    traceback: str | None = None
+
+
+@dataclass
+class ToolHint:
+    """
+    下一步操作提示，面向模型。
+
+    例如：ReadRuntimeTool 在文件被截断时提示模型用更大的 offset 继续读取。
+    suggested_action 可携带建议的工具调用参数，提高模型遵从率。
+    """
+
+    message: str
+    suggested_action: dict[str, Any] | None = None
+
+
+@dataclass
+class ToolArtifact:
+    """
+    工具产出的文件 / 媒体引用。
+
+    对应 CC 的 content_and_artifact response_format，
+    模块 5 起可用于承载 Bash 图片输出等结构化媒体结果。
+    """
+
+    uri: str
+    media_type: str
+    description: str | None = None
+
+
+@dataclass
+class ToolContentBlock:
+    """
+    结构化结果块（P1 协议升级）。
+
+    type:
+        - text: 普通文本
+        - image: 图片（结合 artifact uri）
+        - status: 状态信息（task/sandbox）
+        - reference: 大输出文件引用
+    """
+
+    type: Literal["text", "image", "status", "reference"]
+    text: str | None = None
+    uri: str | None = None
+    media_type: str | None = None
+    meta: dict[str, Any] | None = None
+
+
+# ---------------------------------------------------------------------------
+# ToolResultEnvelope
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolResultEnvelope:
+    """
+    工具运行时统一内部结果协议。
+
+    框架内部始终使用此结构传递工具执行结果。
+    LangChainAdapter.envelope_to_tool_output() 负责将其映射为
+    LangChain ToolMessage.content 字符串，meta 默认不进入模型上下文。
+
+    字段说明：
+        status          — ok / blocked / error
+        tool_name       — 工具名
+        summary         — 面向模型的简短结论（必须进入模型上下文）
+        payload         — 主体数据（经映射后进入模型）
+        artifacts       — 文件/媒体引用（v1 预留，默认 None）
+        hints           — 下一步提示（进入模型）
+        meta            — 审计/性能信息（不进入模型）
+        error           — 错误细节（error 场景必须填写）
+        truncated       — 输出是否被 ToolOutputManager 截断
+        overflow_file   — 超大输出的持久化文件路径（截断时填写，告知模型）
+    """
+
+    status: Literal["ok", "blocked", "error"]
+    tool_name: str
+    summary: str
+    payload: dict[str, Any] | str | None = None
+    blocks: list[ToolContentBlock] | None = None
+    artifacts: list[ToolArtifact] | None = None
+    hints: list[ToolHint] | None = None
+    meta: dict[str, Any] | None = None
+    error: ToolErrorInfo | None = None
+    truncated: bool = False
+    overflow_file: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# ValidationResult
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ValidationResult:
+    """
+    输入语义校验结果，由 RuntimeTool.validate_input() 返回。
+
+    ok=False 时，pipeline 短路并生成 status="error" 的 envelope。
+    模型会收到 message，可据此修正输入后重试。
+
+    与 CC 对比：
+        CC validateInput 返回 ValidationResult = { result: "success" } | { result: "error", message }
+        本框架等价语义，额外增加 code（稳定错误码）和 normalized_input（校验阶段回写归一化输入）。
+    """
+
+    ok: bool
+    message: str | None = None
+    code: str | None = None
+    normalized_input: dict[str, Any] | None = None
+
+
+# ---------------------------------------------------------------------------
+# AuthorizationDecision
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AuthorizationDecision:
+    """
+    权限授权决策，由 RuntimeTool.check_permissions() 返回。
+
+    behavior 语义：
+        "allow"  — 放行，继续执行
+        "deny"   — 策略拒绝，pipeline 短路返回 status="blocked" envelope，不可绕过
+        "ask"    — 需要人工确认（HITL）：
+                   · headless 模式（ToolRuntimeLoader(headless=True)）：pipeline 自动降级为 deny
+                   · 交互模式：pipeline 抛出 PermissionAskInterrupt，
+                     由 LangGraph checkpointer + HumanInTheLoopMiddleware 处理
+
+    ask_prompt: 展示给用户的确认提示文本（headless 时忽略）。
+    updated_input: 策略层在授权时回写修正后的输入（如路径规范化），
+                   对应 CC PermissionAllowDecision.updatedInput。
+    metadata: 可选结构化扩展（如 bash 攻防 rule_code、审计快照），便于观测与 UI 对齐 CC。
+
+    与 CC 对比：
+        CC checkPermissions 返回 PermissionResult，包含 allow / ask / deny / passthrough。
+        本框架 v1.5 实现 allow / deny / ask 三种行为：
+            - headless=True 时 ask → deny（对应 CC shouldAvoidPermissionPrompts）
+            - headless=False 时 ask → PermissionAskInterrupt（对应 CC HITL race）
+    """
+
+    behavior: Literal["allow", "deny", "ask"]
+    message: str | None = None
+    policy_id: str | None = None
+    updated_input: dict[str, Any] | None = None
+    ask_prompt: str | None = None
+    metadata: dict[str, Any] | None = None

langchain_agentx/tool_runtime/permission_context.py

@@ -0,0 +1,78 @@
+"""
+tool_runtime/permission_context.py — 会话级工具权限上下文
+
+职责：在 AgentSessionStore 上管理 skill 触发的 auto-approved 工具窗口（pending/active）。
+在整体链路中的位置：SkillRuntimeTool 写入 pending；模型调用前轮转为 active；PolicyEngine 消费。
+CC 对照：allowedTools 进入 alwaysAllowRules，并在局部会话上下文生效。
+当前裁剪范围：v1 单轮窗口语义（pending -> active），不实现多层嵌套栈。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .session_store import AgentSessionStore
+
+_PENDING_KEY = "tool_scope.auto_approved.pending"
+_ACTIVE_KEY = "tool_scope.auto_approved.active"
+
+
+def _normalize_names(names: Iterable[str]) -> list[str]:
+    result: list[str] = []
+    seen_lower: set[str] = set()
+    for name in names:
+        n = str(name).strip()
+        lower = n.lower()
+        if not n or lower in seen_lower:
+            continue
+        seen_lower.add(lower)
+        result.append(n)
+    return result
+
+
+def set_pending_auto_approved_tools(
+    session_store: AgentSessionStore | None,
+    tool_names: Iterable[str],
+) -> None:
+    if session_store is None:
+        return
+    names = _normalize_names(tool_names)
+    if not names:
+        return
+    session_store.cache_permission(_PENDING_KEY, names)
+    session_store.append_audit(
+        {
+            "event": "tool_scope_pending_updated",
+            "pending_auto_approved": names,
+        }
+    )
+
+
+def rotate_auto_approved_window(session_store: AgentSessionStore | None) -> None:
+    """模型调用前轮转权限窗口：pending -> active，旧 active 自动清空。"""
+    if session_store is None:
+        return
+    pending = session_store.get_cached_permission(_PENDING_KEY)
+    pending_names = _normalize_names(pending if isinstance(pending, list) else [])
+    prev_active = get_active_auto_approved_tools(session_store)
+    session_store.cache_permission(_ACTIVE_KEY, pending_names)
+    session_store.cache_permission(_PENDING_KEY, [])
+    session_store.append_audit(
+        {
+            "event": "tool_scope_window_rotated",
+            "previous_active": sorted(prev_active),
+            "active_auto_approved": pending_names,
+        }
+    )
+
+
+def get_active_auto_approved_tools(
+    session_store: AgentSessionStore | None,
+) -> set[str]:
+    if session_store is None:
+        return set()
+    active = session_store.get_cached_permission(_ACTIVE_KEY)
+    if not isinstance(active, list):
+        return set()
+    return set(_normalize_names(active))
+