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

langchain_agentx/tool_runtime/pipeline.py

@@ -0,0 +1,621 @@
+"""
+runtime/pipeline.py — 工具执行管道与输出大小管控
+
+职责：
+    ToolOutputManager：工具输出大小管控，超限时截断并持久化到文件，
+    向模型提供摘要 + overflow_file 路径，防止超大输出膨胀 context window。
+
+    ToolExecutorPipeline：统一编排工具生命周期的 10 步执行顺序，
+    处理所有短路场景（schema 错误、validate 失败、权限拒绝、执行异常），
+    确保始终返回结构化的 ToolResultEnvelope。
+
+    PermissionAskInterrupt：check_permissions 返回 ask 且处于交互模式时抛出，
+    由 LangGraph checkpointer + HumanInTheLoopMiddleware 捕获并弹出人机确认。
+    headless=True 时 ask 自动降级为 deny，不抛异常。
+
+与 CC 对比：
+    CC 的 maxResultSizeChars 方案：当工具输出超过阈值时，将完整内容写入文件，
+    Claude 收到 preview + 文件路径。本框架 ToolOutputManager 实现等价逻辑。
+    CC 中 Read 工具将 maxResultSizeChars 设为 Infinity（自带分页），
+    对应本框架 RuntimeTool.never_truncate=True。
+
+    CC 中工具执行由 ToolNode 直接调用工具函数，异常处理分散在各工具内。
+    本框架将完整生命周期收敛到 ToolExecutorPipeline，工具只需实现业务逻辑。
+
+    CC 中 headless/print 模式通过 shouldAvoidPermissionPrompts=True 使 ask→deny。
+    本框架等价实现：ToolExecutorPipeline(headless=True) 时 ask 结果直接转 blocked。
+
+    同参重复调用：
+        RuntimeTool.dedupe_identical_calls=True 时，在权限通过后、invoke 前查询
+        IdenticalCallMemo；命中则直接返回带 Hint 的 ToolResultEnvelope（不执行 invoke），
+        作为“软提示防重复”策略的执行层硬约束替代。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from typing import Any
+
+from pydantic import ValidationError
+
+from .base import RuntimeTool
+from .errors import (
+    blocked_envelope,
+    exception_to_envelope,
+    validation_error_envelope,
+)
+from .identical_call_cache import (
+    IdenticalCallMemo,
+    dedup_cache_key,
+    envelope_with_dedup_notice,
+)
+from .models import AuthorizationDecision, ToolExecutionContext, ToolResultEnvelope
+from .resolvers import PermissionResolver
+from langchain_agentx.observability.replay.store import OBS_SCHEMA_VERSION
+from langchain_agentx.observability.logging import (
+    ObservabilityLoggerAdapter,
+    build_log_context,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# PermissionAskInterrupt
+# ---------------------------------------------------------------------------
+
+class PermissionAskInterrupt(Exception):
+    """
+    已废弃（v2）：
+        ask 分支迁移为 permission_resolver 回调，不再使用异常承载常态控制流。
+
+    保留该类型仅用于兼容历史导入；新代码不应再 raise/catch 此异常。
+    """
+
+    def __init__(
+        self,
+        tool_name: str,
+        ask_prompt: str | None,
+        decision: "AuthorizationDecision",
+    ) -> None:
+        self.tool_name = tool_name
+        self.ask_prompt = ask_prompt
+        self.decision = decision
+        super().__init__(f"[{tool_name}] requires user permission: {ask_prompt or 'confirm to proceed'}")
+
+
+# ---------------------------------------------------------------------------
+# ToolOutputManager
+# Named Spec: 工具输出大小管控器
+# 对应 CC maxResultSizeChars 方案
+# ---------------------------------------------------------------------------
+
+class ToolOutputManager:
+    """
+    工具输出大小管控器。
+
+    当 envelope 的文本输出超过 max_result_size_chars 时：
+    1. 将完整内容写入 overflow_dir/<tool_call_id>.txt
+    2. 截断 payload 到前 N 字符
+    3. 设置 envelope.truncated = True
+    4. 设置 envelope.overflow_file = 持久化路径
+    5. 在 summary 中追加 "[Full result saved to: <path>]"
+
+    对应 CC：
+        maxResultSizeChars — 本框架 max_result_size_chars
+        Infinity（Read 工具）— 本框架 RuntimeTool.never_truncate=True
+    """
+
+    DEFAULT_MAX_CHARS = 20_000
+    OVERFLOW_DIR = ".agent_tool_output"
+
+    def __init__(
+        self,
+        max_result_size_chars: int = DEFAULT_MAX_CHARS,
+        overflow_dir: str = OVERFLOW_DIR,
+    ) -> None:
+        self._max_chars = max_result_size_chars
+        self._overflow_dir = overflow_dir
+
+    def truncate_if_needed(
+        self,
+        envelope: ToolResultEnvelope,
+        tool: RuntimeTool,
+        tool_call_id: str | None = None,
+    ) -> ToolResultEnvelope:
+        """
+        检查 envelope 输出大小，超限时截断并持久化。
+
+        never_truncate=True 的工具（如 ReadRuntimeTool）直接原样返回。
+        """
+        if tool.never_truncate:
+            return envelope
+
+        max_chars = tool.max_result_size_chars
+
+        # 将 payload 序列化为文本估算大小
+        text = self._envelope_to_text(envelope)
+        if len(text) <= max_chars:
+            return envelope
+
+        # 超限：持久化完整内容
+        overflow_path = self._persist(text, tool_call_id)
+
+        # 截断 payload
+        truncated_text = text[:max_chars]
+        truncated_summary = (
+            envelope.summary
+            + f"\n[Output truncated at {max_chars} chars."
+            + f" Full result saved to: {overflow_path}]"
+        )
+
+        return ToolResultEnvelope(
+            status=envelope.status,
+            tool_name=envelope.tool_name,
+            summary=truncated_summary,
+            payload=truncated_text,
+            artifacts=envelope.artifacts,
+            hints=envelope.hints,
+            meta=envelope.meta,
+            error=envelope.error,
+            truncated=True,
+            overflow_file=overflow_path,
+        )
+
+    def _envelope_to_text(self, envelope: ToolResultEnvelope) -> str:
+        """将 envelope payload 转为文本用于大小估算。"""
+        if envelope.payload is None:
+            return envelope.summary
+        if isinstance(envelope.payload, str):
+            return envelope.payload
+        # dict payload：简单序列化
+        import json
+        try:
+            return json.dumps(envelope.payload, ensure_ascii=False)
+        except Exception:
+            return str(envelope.payload)
+
+    def _persist(self, text: str, tool_call_id: str | None) -> str:
+        """将完整内容写入 overflow_dir，返回文件路径。"""
+        os.makedirs(self._overflow_dir, exist_ok=True)
+        filename = f"{tool_call_id or int(time.time() * 1000)}.txt"
+        path = os.path.join(self._overflow_dir, filename)
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(text)
+        return path
+
+
+# ---------------------------------------------------------------------------
+# ToolExecutorPipeline
+# Named Spec: 工具执行管道
+# ---------------------------------------------------------------------------
+
+class ToolExecutorPipeline:
+    """
+    工具执行管道，统一编排工具生命周期的 10 步执行顺序。
+
+    执行顺序：
+        1.  normalize_input      — 输入预处理
+        2.  schema parse         — Pydantic 校验，失败 → error envelope
+        3.  validate_input       — 语义校验，失败 → error envelope（模型可重试）
+        4.  check_permissions    — 权限控制：
+                                   · deny  → blocked envelope（不可绕过）
+                                   · ask + headless=True  → blocked envelope（ask 降级）
+                                   · ask + headless=False → 抛 PermissionAskInterrupt
+        5.  before_invoke        — 执行前钩子
+        6.  invoke / ainvoke     — 核心业务，异常 → error envelope
+        7.  after_invoke         — 执行后钩子（状态写入、审计）
+        8.  state_bridge.update  — 状态桥接（如有）
+        9.  present              — 结果呈现 → ToolResultEnvelope
+        10. output_manager       — 输出大小管控
+
+    headless 模式（API 调用、CI、批处理）：
+        - check_permissions 返回 ask 时自动降级为 deny（不等待人工确认）
+        - 对应 CC 的 shouldAvoidPermissionPrompts=True / isNonInteractiveSession=True
+
+    交互模式（headless=False，默认）：
+        - check_permissions 返回 ask 时抛出 PermissionAskInterrupt
+        - 由 LangGraph checkpointer + HumanInTheLoopMiddleware 捕获
+
+    pipeline 不负责：
+        - 将 envelope 映射为 LangChain tool return（由 LangChainAdapter 负责）
+        - 决定 ToolNode 路由
+        - 管理 agent loop
+    """
+
+    _ASK_HEADLESS_DENY_MSG = (
+        "Operation requires interactive user approval, "
+        "which is not available in headless/non-interactive mode."
+    )
+    _ASK_SYNC_DENY_MSG = (
+        "Synchronous pipeline does not support interactive permission ask. "
+        "Use async pipeline with permission_resolver or run in headless mode."
+    )
+
+    def __init__(
+        self,
+        *,
+        output_manager: ToolOutputManager | None = None,
+        headless: bool = False,
+        identical_call_memo: IdenticalCallMemo | None = None,
+        permission_resolver: PermissionResolver | None = None,
+    ) -> None:
+        self._output_manager = output_manager or ToolOutputManager()
+        self._headless = headless
+        self._identical_call_memo = identical_call_memo if identical_call_memo is not None else IdenticalCallMemo()
+        self._permission_resolver = permission_resolver
+
+    def run(
+        self,
+        *,
+        tool: RuntimeTool,
+        raw_input: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        """同步执行完整 pipeline，始终返回 ToolResultEnvelope。"""
+        log = ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(
+                run_id=getattr(ctx, "run_id", None),
+                session_id=getattr(ctx, "thread_id", None),
+                tool_call_id=getattr(ctx, "tool_call_id", None),
+                agent_id=getattr(ctx, "agent_id", None),
+            ).as_extra(),
+        )
+        log.info("tool pipeline run start tool=%s", tool.name)
+        try:
+            out = self._run(tool=tool, raw_input=raw_input, ctx=ctx)
+            log.info("tool pipeline run done tool=%s status=%s", tool.name, out.status)
+            return out
+        except Exception as exc:
+            log.error("tool pipeline run failed tool=%s err=%s", tool.name, exc)
+            return exception_to_envelope(exc, tool.name)
+
+    def set_permission_resolver(self, resolver: PermissionResolver | None) -> None:
+        """运行时更新 permission_resolver。"""
+        self._permission_resolver = resolver
+
+    async def arun(
+        self,
+        *,
+        tool: RuntimeTool,
+        raw_input: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        """异步执行完整 pipeline，始终返回 ToolResultEnvelope。"""
+        log = ObservabilityLoggerAdapter(
+            logger,
+            build_log_context(
+                run_id=getattr(ctx, "run_id", None),
+                session_id=getattr(ctx, "thread_id", None),
+                tool_call_id=getattr(ctx, "tool_call_id", None),
+                agent_id=getattr(ctx, "agent_id", None),
+            ).as_extra(),
+        )
+        log.info("tool pipeline arun start tool=%s", tool.name)
+        try:
+            out = await self._arun(tool=tool, raw_input=raw_input, ctx=ctx)
+            log.info("tool pipeline arun done tool=%s status=%s", tool.name, out.status)
+            return out
+        except Exception as exc:
+            log.error("tool pipeline arun failed tool=%s err=%s", tool.name, exc)
+            return exception_to_envelope(exc, tool.name)
+
+    # ---- 内部实现 ----
+
+    def _run(
+        self,
+        *,
+        tool: RuntimeTool,
+        raw_input: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        # Step 1: normalize_input
+        normalized = tool.normalize_input(raw_input, ctx)
+
+        # Step 2: schema parse
+        parsed_data, schema_error = self._parse_schema(tool, normalized)
+        if schema_error is not None:
+            return schema_error
+
+        # Step 3: validate_input
+        validation = tool.validate_input(parsed_data, ctx)
+        if not validation.ok:
+            return validation_error_envelope(
+                tool.name,
+                validation.message or "Input validation failed.",
+                code=validation.code,
+            )
+
+        # Step 4: check_permissions
+        auth = tool.check_permissions(parsed_data, ctx)
+        if auth.behavior == "deny":
+            logger.warning("tool permission denied tool=%s policy_id=%s", tool.name, auth.policy_id)
+            env = blocked_envelope(
+                tool.name,
+                auth.message or "Permission denied.",
+                policy_id=auth.policy_id,
+            )
+            self._attach_runtime_observability(
+                env,
+                ctx=ctx,
+                events=[
+                    {"event": "permission_checked", "behavior": "deny", "policy_id": auth.policy_id},
+                ],
+                decision_trace=(auth.metadata or {}).get("decision_trace"),
+            )
+            return env
+        if auth.behavior == "ask":
+            logger.warning(
+                "tool permission requires ask tool=%s headless=%s policy_id=%s",
+                tool.name,
+                self._headless,
+                auth.policy_id,
+            )
+            env = blocked_envelope(
+                tool.name,
+                self._ASK_HEADLESS_DENY_MSG if self._headless else self._ASK_SYNC_DENY_MSG,
+                policy_id=auth.policy_id,
+            )
+            self._attach_runtime_observability(
+                env,
+                ctx=ctx,
+                events=[
+                    {"event": "permission_checked", "behavior": "ask_sync_denied", "policy_id": auth.policy_id},
+                ],
+                decision_trace=(auth.metadata or {}).get("decision_trace"),
+            )
+            return env
+        # allow：可能有 updated_input（策略层路径规范化回写）
+        if auth.updated_input:
+            parsed_data = auth.updated_input
+
+        dedup_key: str | None = None
+        if getattr(tool, "dedupe_identical_calls", False):
+            dedup_key = dedup_cache_key(ctx, tool.name, parsed_data)
+            cached = self._identical_call_memo.get(dedup_key)
+            if cached is not None:
+                out = envelope_with_dedup_notice(cached, ctx=ctx)
+                self._attach_runtime_observability(
+                    out,
+                    ctx=ctx,
+                    events=[
+                        {"event": "identical_call_dedup", "behavior": "cache_hit"},
+                    ],
+                    decision_trace=(auth.metadata or {}).get("decision_trace"),
+                )
+                return self._output_manager.truncate_if_needed(
+                    out, tool, ctx.tool_call_id
+                )
+
+        # Step 5: before_invoke
+        tool.before_invoke(parsed_data, ctx)
+
+        # Step 6: invoke
+        result = tool.invoke(parsed_data, ctx)
+
+        # Step 7: after_invoke
+        tool.after_invoke(parsed_data, result, ctx)
+
+        # Step 9: present
+        envelope = tool.present(parsed_data, result, ctx)
+        self._attach_runtime_observability(
+            envelope,
+            ctx=ctx,
+            events=[
+                {"event": "permission_checked", "behavior": "allow", "policy_id": auth.policy_id},
+                {"event": "invoke_completed", "tool_name": tool.name},
+            ],
+            decision_trace=(auth.metadata or {}).get("decision_trace"),
+        )
+
+        # Step 10: output_manager
+        final = self._output_manager.truncate_if_needed(
+            envelope, tool, ctx.tool_call_id
+        )
+        if dedup_key is not None:
+            self._identical_call_memo.put(dedup_key, final)
+        return final
+
+    async def _arun(
+        self,
+        *,
+        tool: RuntimeTool,
+        raw_input: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        # Step 1: normalize_input
+        normalized = tool.normalize_input(raw_input, ctx)
+
+        # Step 2: schema parse
+        parsed_data, schema_error = self._parse_schema(tool, normalized)
+        if schema_error is not None:
+            return schema_error
+
+        # Step 3: validate_input
+        validation = tool.validate_input(parsed_data, ctx)
+        if not validation.ok:
+            return validation_error_envelope(
+                tool.name,
+                validation.message or "Input validation failed.",
+                code=validation.code,
+            )
+
+        # Step 4: check_permissions（支持异步 policy）
+        if tool._policy is not None and hasattr(tool._policy, "aauthorize"):
+            auth = await tool._policy.aauthorize(
+                tool_name=tool.name, input_data=parsed_data, ctx=ctx
+            )
+        else:
+            auth = tool.check_permissions(parsed_data, ctx)
+
+        if auth.behavior == "deny":
+            logger.warning("tool permission denied tool=%s policy_id=%s", tool.name, auth.policy_id)
+            env = blocked_envelope(
+                tool.name,
+                auth.message or "Permission denied.",
+                policy_id=auth.policy_id,
+            )
+            self._attach_runtime_observability(
+                env,
+                ctx=ctx,
+                events=[
+                    {"event": "permission_checked", "behavior": "deny", "policy_id": auth.policy_id},
+                ],
+                decision_trace=(auth.metadata or {}).get("decision_trace"),
+            )
+            return env
+        if auth.behavior == "ask":
+            logger.warning(
+                "tool permission requires ask tool=%s headless=%s policy_id=%s",
+                tool.name,
+                self._headless,
+                auth.policy_id,
+            )
+            if self._headless or self._permission_resolver is None:
+                env = blocked_envelope(
+                    tool.name,
+                    self._ASK_HEADLESS_DENY_MSG,
+                    policy_id=auth.policy_id,
+                )
+                self._attach_runtime_observability(
+                    env,
+                    ctx=ctx,
+                    events=[
+                        {"event": "permission_checked", "behavior": "ask_auto_denied", "policy_id": auth.policy_id},
+                    ],
+                    decision_trace=(auth.metadata or {}).get("decision_trace"),
+                )
+                return env
+            allowed = await self._permission_resolver(tool.name, auth.ask_prompt)
+            if not allowed:
+                env = blocked_envelope(
+                    tool.name,
+                    auth.ask_prompt or "User rejected the operation.",
+                    policy_id=auth.policy_id,
+                )
+                self._attach_runtime_observability(
+                    env,
+                    ctx=ctx,
+                    events=[
+                        {
+                            "event": "permission_checked",
+                            "behavior": "ask_rejected_by_resolver",
+                            "policy_id": auth.policy_id,
+                        },
+                    ],
+                    decision_trace=(auth.metadata or {}).get("decision_trace"),
+                )
+                return env
+        if auth.updated_input:
+            parsed_data = auth.updated_input
+
+        dedup_key: str | None = None
+        if getattr(tool, "dedupe_identical_calls", False):
+            dedup_key = dedup_cache_key(ctx, tool.name, parsed_data)
+            cached = self._identical_call_memo.get(dedup_key)
+            if cached is not None:
+                out = envelope_with_dedup_notice(cached, ctx=ctx)
+                self._attach_runtime_observability(
+                    out,
+                    ctx=ctx,
+                    events=[
+                        {"event": "identical_call_dedup", "behavior": "cache_hit"},
+                    ],
+                    decision_trace=(auth.metadata or {}).get("decision_trace"),
+                )
+                return self._output_manager.truncate_if_needed(
+                    out, tool, ctx.tool_call_id
+                )
+
+        # Step 5: before_invoke
+        tool.before_invoke(parsed_data, ctx)
+
+        # Step 6: ainvoke
+        result = await tool.ainvoke(parsed_data, ctx)
+
+        # Step 7: after_invoke
+        tool.after_invoke(parsed_data, result, ctx)
+
+        # Step 9: present
+        envelope = tool.present(parsed_data, result, ctx)
+        self._attach_runtime_observability(
+            envelope,
+            ctx=ctx,
+            events=[
+                {"event": "permission_checked", "behavior": "allow", "policy_id": auth.policy_id},
+                {"event": "invoke_completed", "tool_name": tool.name},
+            ],
+            decision_trace=(auth.metadata or {}).get("decision_trace"),
+        )
+
+        # Step 10: output_manager
+        final = self._output_manager.truncate_if_needed(
+            envelope, tool, ctx.tool_call_id
+        )
+        if dedup_key is not None:
+            self._identical_call_memo.put(dedup_key, final)
+        return final
+
+    @staticmethod
+    def _parse_schema(
+        tool: RuntimeTool,
+        data: dict[str, Any],
+    ) -> tuple[dict[str, Any], ToolResultEnvelope | None]:
+        """
+        用 tool.input_model 做 Pydantic schema 解析。
+        成功返回 (parsed_dict, None)，失败返回 ({}, error_envelope)。
+        """
+        try:
+            parsed = tool.input_model.model_validate(data)
+            return parsed.model_dump(), None
+        except ValidationError as exc:
+            detail = "; ".join(
+                f"{'.'.join(str(l) for l in e['loc'])}: {e['msg']}"
+                for e in exc.errors()
+            )
+            envelope = validation_error_envelope(
+                tool.name,
+                f"Input schema error: {detail}",
+                code="INPUT_SCHEMA_ERROR",
+            )
+            return {}, envelope
+        except Exception as exc:
+            return {}, exception_to_envelope(exc, tool.name)
+
+    @staticmethod
+    def _attach_runtime_observability(
+        envelope: ToolResultEnvelope,
+        *,
+        ctx: ToolExecutionContext,
+        events: list[dict[str, Any]],
+        decision_trace: list[dict[str, Any]] | None = None,
+    ) -> None:
+        meta = dict(envelope.meta or {})
+        obs = meta.get("observability")
+        if not isinstance(obs, dict):
+            obs = {
+                "schema_version": OBS_SCHEMA_VERSION,
+                "trace_context": {
+                    "thread_id": ctx.thread_id,
+                    "run_id": ctx.run_id,
+                    "tool_call_id": ctx.tool_call_id,
+                    "tool_name": ctx.tool_name,
+                },
+                "scenario": "runtime_pipeline",
+                "events": [],
+            }
+        merged_events = list(obs.get("events", []))
+        start_seq = len(merged_events)
+        for i, ev in enumerate(events, start=1):
+            merged_events.append({"seq": start_seq + i, **ev})
+        obs["events"] = merged_events
+        meta["observability"] = obs
+        if decision_trace:
+            meta.setdefault("decision_trace", decision_trace)
+        if ctx.tool_call_id:
+            meta.setdefault("tool_call_id", ctx.tool_call_id)
+        envelope.meta = meta