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

langchain_agentx/tool_runtime/resolvers/background.py

@@ -0,0 +1,32 @@
+"""
+tool_runtime/resolvers/background.py — 后台任务权限 resolver
+
+职责：
+    后台/批处理场景中拒绝 ask 请求并记录审计日志。
+
+链路位置：
+    ToolExecutorPipeline ask 分支调用，避免任务挂起等待人工输入。
+
+当前裁剪范围：
+    仅记录基础 warning 日志，不接入统一审计事件总线。
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+class BackgroundPermissionResolver:
+    def __init__(self, logger: logging.Logger | None = None) -> None:
+        self._log = logger or logging.getLogger(__name__)
+
+    async def __call__(self, tool_name: str, ask_prompt: str | None) -> bool:
+        self._log.warning(
+            "background_permission_auto_deny tool=%s prompt=%s",
+            tool_name,
+            ask_prompt,
+        )
+        return False
+
+
+__all__ = ["BackgroundPermissionResolver"]

langchain_agentx/tool_runtime/resolvers/base.py

@@ -0,0 +1,20 @@
+"""
+tool_runtime/resolvers/base.py — PermissionResolver 协议定义
+
+职责：
+    提供 ask 分支统一回调协议，隔离 ToolExecutorPipeline 与 UI/会话实现细节。
+
+链路位置：
+    ToolExecutorPipeline 在 auth.behavior=="ask" 时 await PermissionResolver。
+
+当前裁剪范围：
+    仅定义类型协议，不引入具体会话/交互实现。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+PermissionResolver = Callable[[str, str | None], Awaitable[bool]]
+
+__all__ = ["PermissionResolver"]

langchain_agentx/tool_runtime/resolvers/conversation.py

@@ -0,0 +1,22 @@
+"""
+tool_runtime/resolvers/conversation.py — 对话场景权限 resolver
+
+职责：
+    对话（Web/IM）场景下不阻塞当前轮，ask 分支统一返回拒绝。
+
+链路位置：
+    ToolExecutorPipeline ask 分支调用；拒绝后由模型在下一轮解释并重试。
+
+当前裁剪范围：
+    仅返回 False，不包含外部通知/消息回传能力。
+"""
+
+from __future__ import annotations
+
+
+class ConversationPermissionResolver:
+    async def __call__(self, tool_name: str, ask_prompt: str | None) -> bool:
+        return False
+
+
+__all__ = ["ConversationPermissionResolver"]

langchain_agentx/tool_runtime/resolvers/workflow.py

@@ -0,0 +1,73 @@
+"""
+tool_runtime/resolvers/workflow.py — 工作流场景权限 resolver
+
+职责：
+    为 workflow 节点提供同进程可批准/拒绝的等待点（Future 协调）。
+
+链路位置：
+    ToolExecutorPipeline ask 分支 await；审批侧通过 approve/reject 回填。
+
+当前裁剪范围：
+    仅支持基于 tool_name 的单键等待，不含跨会话持久化审批。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+
+
+class WorkflowPermissionResolver:
+    def __init__(self, *, timeout: float = 60.0) -> None:
+        self._pending: dict[str, deque[asyncio.Future[bool]]] = {}
+        self._timeout = timeout
+        self._lock = asyncio.Lock()
+
+    async def __call__(self, tool_name: str, ask_prompt: str | None) -> bool:
+        _ = ask_prompt
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[bool] = loop.create_future()
+        async with self._lock:
+            queue = self._pending.setdefault(tool_name, deque())
+            queue.append(future)
+        try:
+            return await asyncio.wait_for(future, timeout=self._timeout)
+        except asyncio.TimeoutError:
+            return False
+        finally:
+            async with self._lock:
+                queue = self._pending.get(tool_name)
+                if queue is not None:
+                    try:
+                        queue.remove(future)
+                    except ValueError:
+                        pass
+                    if not queue:
+                        self._pending.pop(tool_name, None)
+
+    async def approve(self, tool_name: str) -> bool:
+        future = await self._pop_next_pending(tool_name)
+        if future and not future.done():
+            future.set_result(True)
+            return True
+        return False
+
+    async def reject(self, tool_name: str) -> bool:
+        future = await self._pop_next_pending(tool_name)
+        if future and not future.done():
+            future.set_result(False)
+            return True
+        return False
+
+    async def _pop_next_pending(self, tool_name: str) -> asyncio.Future[bool] | None:
+        async with self._lock:
+            queue = self._pending.get(tool_name)
+            if not queue:
+                return None
+            future = queue.popleft()
+            if not queue:
+                self._pending.pop(tool_name, None)
+            return future
+
+
+__all__ = ["WorkflowPermissionResolver"]

langchain_agentx/tool_runtime/session_store.py

@@ -0,0 +1,132 @@
+"""
+runtime/session_store.py — 会话级状态存储
+
+职责：
+    AgentSessionStore 是 session 级别的状态对象，生命周期与一次 Agent 会话对齐。
+    它独立于 LangGraph graph state（turn 级）和 ToolExecutionContext（call 级），
+    负责跨 turn 持久化的会话状态：
+
+        file_read_state   — 文件读取记录（为 read-before-write 约束服务）
+        file_history      — 文件写入/编辑历史
+        audit_log         — 工具调用审计日志
+        permissions_cache — 权限决策缓存（避免重复询问）
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class FileReadRecord:
+    path: str
+    tool_call_id: str | None
+    ts: float
+    line_start: int | None = None
+    line_end: int | None = None
+
+
+@dataclass
+class FileWriteRecord:
+    path: str
+    operation: str
+    tool_call_id: str | None
+    ts: float
+
+
+class AgentSessionStore:
+    CONFIGURABLE_KEY = "session_store"
+
+    def __init__(self, session_id: str | None = None) -> None:
+        self.session_id: str = session_id or str(uuid.uuid4())
+        self._created_at: float = time.time()
+        self._file_read_state: dict[str, FileReadRecord] = {}
+        self._file_history: list[FileWriteRecord] = []
+        self._audit_log: list[dict[str, Any]] = []
+        self._permissions_cache: dict[str, Any] = {}
+
+    def record_file_read(
+        self,
+        path: str,
+        *,
+        tool_call_id: str | None = None,
+        ts: float | None = None,
+        line_start: int | None = None,
+        line_end: int | None = None,
+    ) -> None:
+        self._file_read_state[path] = FileReadRecord(
+            path=path,
+            tool_call_id=tool_call_id,
+            ts=ts if ts is not None else time.time(),
+            line_start=line_start,
+            line_end=line_end,
+        )
+
+    def has_been_read(self, path: str) -> bool:
+        return path in self._file_read_state
+
+    def get_file_read_record(self, path: str) -> FileReadRecord | None:
+        return self._file_read_state.get(path)
+
+    def get_all_read_paths(self) -> list[str]:
+        return list(self._file_read_state.keys())
+
+    def record_file_write(
+        self,
+        path: str,
+        operation: str,
+        *,
+        tool_call_id: str | None = None,
+        ts: float | None = None,
+    ) -> None:
+        self._file_history.append(
+            FileWriteRecord(
+                path=path,
+                operation=operation,
+                tool_call_id=tool_call_id,
+                ts=ts if ts is not None else time.time(),
+            )
+        )
+
+    def get_file_history(self) -> list[FileWriteRecord]:
+        return list(self._file_history)
+
+    def append_audit(self, record: dict[str, Any]) -> None:
+        self._audit_log.append(record)
+
+    def get_audit_log(self) -> list[dict[str, Any]]:
+        return list(self._audit_log)
+
+    def export_audit_log(self) -> list[dict[str, Any]]:
+        """语义化导出出口；等价于 get_audit_log()."""
+        return self.get_audit_log()
+
+    def cache_permission(self, key: str, decision: Any) -> None:
+        self._permissions_cache[key] = decision
+
+    def get_cached_permission(self, key: str) -> Any | None:
+        return self._permissions_cache.get(key)
+
+    @property
+    def created_at(self) -> float:
+        return self._created_at
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "session_id": self.session_id,
+            "created_at": self._created_at,
+            "files_read": len(self._file_read_state),
+            "file_writes": len(self._file_history),
+            "audit_entries": len(self._audit_log),
+            "cached_permissions": len(self._permissions_cache),
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"<AgentSessionStore session_id={self.session_id!r} "
+            f"files_read={len(self._file_read_state)} "
+            f"audit_entries={len(self._audit_log)}>"
+        )

langchain_agentx/tool_runtime/smoke_test_runtime.py

@@ -0,0 +1,294 @@
+"""
+runtime 框架端到端冒烟测试（smoke_test_runtime.py）
+
+用途：
+    快速验证 runtime 框架的完整执行路径，无需完整环境，
+    可直接 `python smoke_test_runtime.py` 运行（不依赖 pytest）。
+
+覆盖场景：
+    1. 正常工具流转（EchoTool 10 步 pipeline）
+    2. adapter.envelope_to_tool_output 输出格式
+    3. validate_input 失败 → error envelope 短路
+    4. check_permissions deny → blocked envelope 短路
+    5. ToolOutputManager 超限截断 + overflow_file
+    6. registry + DefaultPolicyEngine 无路径字段放行
+    7. StateBridge record_read / has_been_read / append_audit
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import types
+import pathlib
+import importlib.util
+
+# ---------------------------------------------------------------------------
+# 绕过顶层 langchain_agentx/__init__.py（该文件依赖尚未安装的包）
+# 手动注册父包 stub，直接加载 runtime 子模块
+# ---------------------------------------------------------------------------
+
+def _stub_pkg(name: str, path_hint: str) -> None:
+    m = types.ModuleType(name)
+    m.__path__ = [path_hint]
+    m.__package__ = name
+    sys.modules[name] = m
+
+
+# 本文件位于 langchain_agentx/tool_runtime/，parents[2] = 仓库根（含 langchain_agentx 包目录）
+_ROOT = pathlib.Path(__file__).resolve().parents[2]
+
+_stub_pkg("langchain_agentx",         str(_ROOT / "langchain_agentx"))
+_stub_pkg("langchain_agentx.tool_runtime", str(_ROOT / "langchain_agentx/tool_runtime"))
+
+
+def _load_module(sub: str) -> None:
+    mod_name = f"langchain_agentx.tool_runtime.{sub}"
+    path = _ROOT / "langchain_agentx/tool_runtime" / f"{sub}.py"
+    spec = importlib.util.spec_from_file_location(mod_name, path)
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[mod_name] = mod
+    spec.loader.exec_module(mod)
+
+
+for _sub in ["models", "errors", "base", "policy", "state_bridge", "pipeline", "adapter", "registry"]:
+    _load_module(_sub)
+
+# ---------------------------------------------------------------------------
+# 导入
+# ---------------------------------------------------------------------------
+
+from langchain_agentx.tool_runtime.models       import ToolExecutionContext, ToolResultEnvelope, ValidationResult, AuthorizationDecision  # noqa: E402
+from langchain_agentx.tool_runtime.base         import RuntimeTool                # noqa: E402
+from langchain_agentx.tool_runtime.pipeline     import ToolExecutorPipeline       # noqa: E402
+from langchain_agentx.tool_runtime.adapter      import LangChainAdapter           # noqa: E402
+from langchain_agentx.tool_runtime.registry     import RuntimeToolRegistry        # noqa: E402
+from langchain_agentx.tool_runtime.policy       import ToolPolicyConfig, DefaultPolicyEngine  # noqa: E402
+from langchain_agentx.tool_runtime.state_bridge import ToolStateBridge            # noqa: E402
+from pydantic import BaseModel                                                      # noqa: E402
+
+# ---------------------------------------------------------------------------
+# 最小工具定义（所有测试共用）
+# ---------------------------------------------------------------------------
+
+class EchoInput(BaseModel):
+    message: str
+
+
+class EchoTool(RuntimeTool):
+    name        = "echo"
+    description = "回显输入消息"
+    input_model = EchoInput
+    is_read_only = True
+
+    def invoke(self, data, ctx):
+        return data["message"]
+
+    def present(self, data, result, ctx):
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=f"Echo: {result}",
+            payload=result,
+        )
+
+
+# ---------------------------------------------------------------------------
+# 辅助
+# ---------------------------------------------------------------------------
+
+def _make_ctx(state=None) -> ToolExecutionContext:
+    return ToolExecutionContext(
+        tool_name="echo",
+        tool_call_id="call_001",
+        input_args={"message": "hello"},
+        state=state if state is not None else {},
+    )
+
+
+def _pass(label: str) -> None:
+    print(f"  ✅ {label}")
+
+
+def _section(title: str) -> None:
+    print(f"\n=== {title} ===")
+
+
+# ---------------------------------------------------------------------------
+# Smoke tests
+# ---------------------------------------------------------------------------
+
+def test_normal_flow() -> None:
+    _section("Test 1: 正常工具流转")
+    pipeline = ToolExecutorPipeline()
+    ctx = _make_ctx()
+    env = pipeline.run(tool=EchoTool(), raw_input={"message": "hello runtime"}, ctx=ctx)
+    assert env.status == "ok", f"got {env.status}"
+    assert "hello runtime" in env.summary
+    _pass(f"status=ok, summary={env.summary!r}")
+
+
+def test_adapter_output() -> None:
+    _section("Test 2: adapter.envelope_to_tool_output")
+    pipeline = ToolExecutorPipeline()
+    adapter = LangChainAdapter()
+    ctx = _make_ctx()
+    env = pipeline.run(tool=EchoTool(), raw_input={"message": "hello"}, ctx=ctx)
+    output = adapter.envelope_to_tool_output(env)
+    assert "hello" in output
+    _pass(f"output={output!r}")
+
+
+def test_validate_input_short_circuit() -> None:
+    _section("Test 3: validate_input 失败 → error 短路")
+
+    class StrictEcho(EchoTool):
+        name = "strict_echo"
+        def validate_input(self, data, ctx):
+            if len(data["message"]) > 5:
+                return ValidationResult(ok=False, message="message too long")
+            return ValidationResult(ok=True)
+
+    pipeline = ToolExecutorPipeline()
+    ctx = _make_ctx()
+    env = pipeline.run(tool=StrictEcho(), raw_input={"message": "too long message"}, ctx=ctx)
+    assert env.status == "error"
+    assert "too long" in env.summary
+    _pass(f"status=error, summary={env.summary!r}")
+
+
+def test_check_permissions_blocked() -> None:
+    _section("Test 4: check_permissions deny → blocked 短路")
+
+    class DeniedEcho(EchoTool):
+        name = "denied_echo"
+        def check_permissions(self, data, ctx):
+            return AuthorizationDecision(behavior="deny", message="not allowed here")
+
+    pipeline = ToolExecutorPipeline()
+    ctx = _make_ctx()
+    env = pipeline.run(tool=DeniedEcho(), raw_input={"message": "hi"}, ctx=ctx)
+    assert env.status == "blocked"
+    assert "not allowed" in env.summary
+    _pass(f"status=blocked, summary={env.summary!r}")
+
+
+def test_output_manager_truncation() -> None:
+    _section("Test 5: ToolOutputManager 超限截断")
+
+    class TinyEcho(EchoTool):
+        name = "tiny_echo"
+        max_result_size_chars = 5
+
+    pipeline = ToolExecutorPipeline()
+    ctx = _make_ctx()
+    env = pipeline.run(tool=TinyEcho(), raw_input={"message": "hello runtime 1234"}, ctx=ctx)
+    assert env.truncated is True
+    assert env.overflow_file is not None
+    assert os.path.exists(env.overflow_file)
+    _pass(f"truncated=True, overflow_file={env.overflow_file}")
+
+
+def test_registry_and_policy_no_path_field() -> None:
+    _section("Test 6: registry + DefaultPolicyEngine（无路径字段 → allow）")
+    tmpdir = tempfile.mkdtemp()
+    policy = DefaultPolicyEngine(
+        ToolPolicyConfig(read_roots=[tmpdir], write_roots=[tmpdir])
+    )
+    pipeline = ToolExecutorPipeline()
+    adapter = LangChainAdapter()
+    registry = RuntimeToolRegistry(pipeline=pipeline, adapter=adapter)
+    registry.register(EchoTool(policy=policy))
+
+    assert "echo" in registry
+    lc_tools = registry.to_langchain_tools()
+    assert len(lc_tools) == 1
+    assert lc_tools[0].name == "echo"
+
+    ctx = _make_ctx()
+    env = pipeline.run(tool=registry.get("echo"), raw_input={"message": "ok"}, ctx=ctx)
+    assert env.status == "ok"
+    _pass("registry.register + to_langchain_tools OK, policy allow (no path field)")
+
+
+def test_state_bridge() -> None:
+    _section("Test 7: ToolStateBridge record_read / has_been_read / append_audit")
+    bridge = ToolStateBridge()
+    state = {}
+    ctx = ToolExecutionContext(
+        tool_name="echo", tool_call_id="c1", input_args={}, state=state
+    )
+
+    _td = pathlib.Path(tempfile.gettempdir())
+    foo = str(_td / "langchain_agentx_smoke" / "foo.txt")
+    bar = str(_td / "langchain_agentx_smoke" / "bar.txt")
+    bridge.record_read(ctx, foo, line_start=1, line_end=10)
+    assert bridge.has_been_read(ctx, foo)
+    assert not bridge.has_been_read(ctx, bar)
+
+    bridge.append_audit(ctx, {"tool": "echo", "ts": 9999})
+    log = bridge.get_audit_log(ctx)
+    assert len(log) == 1
+    assert log[0]["tool"] == "echo"
+    _pass("record_read / has_been_read / audit OK")
+
+
+def test_exception_captured_as_error_envelope() -> None:
+    _section("Test 8: invoke 抛异常 → pipeline 捕获为 error envelope")
+
+    class BrokenEcho(EchoTool):
+        name = "broken_echo"
+        def invoke(self, data, ctx):
+            raise ValueError("something went wrong")
+
+    pipeline = ToolExecutorPipeline()
+    ctx = _make_ctx()
+    env = pipeline.run(tool=BrokenEcho(), raw_input={"message": "hi"}, ctx=ctx)
+    assert env.status == "error"
+    assert "went wrong" in env.summary
+    assert env.meta is not None and "traceback" in env.meta
+    _pass(f"status=error, summary={env.summary!r}, traceback in meta")
+
+
+def test_schema_parse_failure() -> None:
+    _section("Test 9: Pydantic schema 解析失败 → error 短路")
+    pipeline = ToolExecutorPipeline()
+    ctx = _make_ctx()
+    # 传入错误类型（缺少必填 message 字段）
+    env = pipeline.run(tool=EchoTool(), raw_input={}, ctx=ctx)
+    assert env.status == "error"
+    assert "schema" in env.summary.lower() or "message" in env.summary.lower()
+    _pass(f"status=error on missing field: {env.summary!r}")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    tests = [
+        test_normal_flow,
+        test_adapter_output,
+        test_validate_input_short_circuit,
+        test_check_permissions_blocked,
+        test_output_manager_truncation,
+        test_registry_and_policy_no_path_field,
+        test_state_bridge,
+        test_exception_captured_as_error_envelope,
+        test_schema_parse_failure,
+    ]
+    failed = []
+    for fn in tests:
+        try:
+            fn()
+        except Exception as exc:
+            print(f"  ❌ FAILED: {exc}")
+            failed.append(fn.__name__)
+
+    print()
+    if failed:
+        print(f"❌ {len(failed)} test(s) failed: {failed}")
+        sys.exit(1)
+    else:
+        print(f"✅ All {len(tests)} smoke tests passed")