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

langchain_agentx/tools/bash/result_presenter.py

@@ -0,0 +1,324 @@
+"""
+tools/bash/result_presenter.py — BashRuntimeTool 模块5：结果展示协作者
+
+职责：
+    统一承接 Bash 工具的结果展示语义，把 `BashToolOutput` 映射为
+    `ToolResultEnvelope`，避免 `tool.py` 继续堆积 background / image /
+    sandbox / no-output 等展示分支。
+
+在整体链路中的位置：
+    - 由 `tool.py::present()` 调用
+    - 依赖 `output_utils.py` 识别特殊输出形态
+    - 不参与命令执行、权限判断或 sandbox 决策
+
+当前包含：
+    1. 后台任务、中断、sandbox violation 的统一 envelope 生成
+    2. image data URI -> artifact 的结果映射
+    3. no-output / return-code / destructive warning / sandbox hint 的展示汇总
+
+与 CC 对照：
+    对应 CC `BashToolResultMessage.tsx` 与 `utils.ts` 中一部分“结果层”逻辑。
+    当前是基础版 presenter：先把结构化结果和多模态 artifact 接口立住。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import ToolContentBlock, ToolHint, ToolResultEnvelope
+
+from .models import BashToolOutput
+from .output_utils import BashOutputArtifactBuilder
+
+
+class BashResultPresenter:
+    """Bash 结果展示协作者。"""
+
+    def __init__(
+        self,
+        artifact_builder: BashOutputArtifactBuilder | None = None,
+    ) -> None:
+        self._artifact_builder = artifact_builder or BashOutputArtifactBuilder()
+
+    def present(
+        self,
+        *,
+        tool_name: str,
+        data: Any,
+        result: BashToolOutput,
+    ) -> ToolResultEnvelope:
+        # `data` 通常来自工具的 input_model（Pydantic BaseModel），
+        # 但在部分链路/测试中也可能是普通 dict。
+        if hasattr(data, "model_dump"):
+            # Pydantic v2 BaseModel
+            data_dict: dict[str, Any] = data.model_dump()  # type: ignore[assignment]
+        elif isinstance(data, dict):
+            data_dict = data
+        else:
+            # 兜底：尽量不因展示层失败而中断工具链路
+            data_dict = {}
+
+        command = str(data_dict.get("command", ""))
+        description = data_dict.get("description")
+        description_text = str(description) if isinstance(description, str) else None
+
+        if result.background_task_id:
+            return self._present_background(tool_name=tool_name, result=result)
+
+        if result.interrupted:
+            return self._present_interrupted(tool_name=tool_name, result=result)
+
+        if result.sandbox_violation_message:
+            return self._present_sandbox_violation(
+                tool_name=tool_name,
+                command=command,
+                result=result,
+            )
+
+        image_artifact = self._artifact_builder.build_image_artifact(result.stdout)
+        if image_artifact is not None:
+            hints = self._build_hints(result)
+            if image_artifact.was_resized:
+                hints.append(
+                    ToolHint(
+                        message=(
+                            "Image output was resized/downsampled before being exposed "
+                            "to the model."
+                        )
+                    )
+                )
+
+            image_meta = {
+                "exit_code": result.exit_code,
+                "media_type": image_artifact.media_type,
+                "image_size_bytes": image_artifact.size_bytes,
+            }
+            if image_artifact.width is not None:
+                image_meta["image_width"] = image_artifact.width
+            if image_artifact.height is not None:
+                image_meta["image_height"] = image_artifact.height
+
+            summary = description_text or "Image output produced by bash command"
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=tool_name,
+                summary=summary,
+                payload=f"[Image output detected: {image_artifact.media_type}]",
+                blocks=[
+                    ToolContentBlock(type="status", text="image_output_detected"),
+                    ToolContentBlock(
+                        type="image",
+                        uri=image_artifact.artifact.uri,
+                        media_type=image_artifact.media_type,
+                    ),
+                ],
+                artifacts=[image_artifact.artifact],
+                hints=hints or None,
+                meta=self._attach_observability(image_meta, result),
+            )
+
+        if result.no_output_expected and not result.stdout.strip():
+            summary = description_text or f"Ran: {command[:60]}"
+            hints = self._build_hints(result)
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=tool_name,
+                summary=summary,
+                payload="Done",
+                blocks=[ToolContentBlock(type="status", text="command_completed_no_output")],
+                hints=hints or None,
+                meta=self._attach_observability({
+                    "exit_code": result.exit_code,
+                    "task_mode": result.task_mode,
+                    "task_status": result.task_status,
+                    "task_exit_code": result.task_exit_code,
+                }, result),
+            )
+
+        summary = description_text or f"Ran: {command[:60]}"
+        payload = result.stdout or "(No output)"
+        hints = self._build_hints(result)
+        if result.output_truncated and result.overflow_file:
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=tool_name,
+                summary=summary + " (stdout truncated; full output spilled to file)",
+                payload=(
+                    f"{payload}\n\n"
+                    f"[Full output: {result.overflow_file} — use Read tool with this path]"
+                ),
+                blocks=[
+                    ToolContentBlock(
+                        type="status",
+                        text="stdout_truncated",
+                        meta={"overflow_file": result.overflow_file},
+                    ),
+                    ToolContentBlock(
+                        type="reference",
+                        text="full_stdout",
+                        uri=result.overflow_file,
+                    ),
+                    ToolContentBlock(type="text", text=payload),
+                ],
+                hints=hints or None,
+                truncated=True,
+                overflow_file=result.overflow_file,
+                meta=self._attach_observability({
+                    "exit_code": result.exit_code,
+                    "task_mode": result.task_mode,
+                    "task_status": result.task_status,
+                    "task_exit_code": result.task_exit_code,
+                }, result),
+            )
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=tool_name,
+            summary=summary,
+            payload=payload,
+            blocks=[
+                ToolContentBlock(
+                    type="status",
+                    text=f"task:{result.task_status}",
+                    meta={"task_mode": result.task_mode, "task_exit_code": result.task_exit_code},
+                ),
+                ToolContentBlock(type="text", text=payload),
+            ],
+            hints=hints or None,
+            meta=self._attach_observability({
+                "exit_code": result.exit_code,
+                "task_mode": result.task_mode,
+                "task_status": result.task_status,
+                "task_exit_code": result.task_exit_code,
+            }, result),
+        )
+
+    def _present_background(
+        self,
+        *,
+        tool_name: str,
+        result: BashToolOutput,
+    ) -> ToolResultEnvelope:
+        summary = f"Command submitted to background (task: {result.background_task_id})"
+        if result.auto_backgrounded:
+            summary = f"Command auto-backgrounded (task: {result.background_task_id})"
+        content = (
+            "Command is running in the background.\n"
+            f"Task ID: {result.background_task_id}\n"
+            f"Output file: {result.background_output_path}\n"
+            "You will be notified when it completes. "
+            f"To read output: use the Read tool on {result.background_output_path}"
+        )
+        hints = self._build_hints(result)
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=tool_name,
+            summary=summary,
+            payload=content,
+            blocks=[
+                ToolContentBlock(
+                    type="status",
+                    text=f"background_task:{result.task_status}",
+                    meta={"task_id": result.background_task_id},
+                ),
+                ToolContentBlock(
+                    type="reference",
+                    text="background_output",
+                    uri=result.background_output_path,
+                ),
+            ],
+            hints=hints or None,
+            meta=self._attach_observability({
+                "task_id": result.background_task_id,
+                "task_mode": result.task_mode,
+                "task_status": result.task_status,
+                "auto_backgrounded": result.auto_backgrounded,
+            }, result),
+        )
+
+    def _present_interrupted(
+        self,
+        *,
+        tool_name: str,
+        result: BashToolOutput,
+    ) -> ToolResultEnvelope:
+        content = result.stdout
+        if result.stdout:
+            content = result.stdout + "\n<error>Command was aborted before completion</error>"
+        else:
+            content = "<error>Command was aborted before completion</error>"
+        return ToolResultEnvelope(
+            status="error",
+            tool_name=tool_name,
+            summary="Command timed out or was interrupted",
+            payload=content,
+            blocks=[ToolContentBlock(type="status", text="interrupted")],
+            meta=self._attach_observability({"exit_code": result.exit_code}, result),
+        )
+
+    def _present_sandbox_violation(
+        self,
+        *,
+        tool_name: str,
+        command: str,
+        result: BashToolOutput,
+    ) -> ToolResultEnvelope:
+        payload = result.stdout.strip()
+        if payload:
+            payload = f"{payload}\n{result.sandbox_violation_message}"
+        else:
+            payload = result.sandbox_violation_message
+        return ToolResultEnvelope(
+            status="error",
+            tool_name=tool_name,
+            summary="Sandbox restriction prevented command execution",
+            payload=payload,
+            blocks=[ToolContentBlock(type="status", text="sandbox_violation")],
+            meta=self._attach_observability({"exit_code": result.exit_code, "command": command}, result),
+        )
+
+    def _build_hints(self, result: BashToolOutput) -> list[ToolHint]:
+        hints: list[ToolHint] = []
+
+        if result.return_code_interpretation:
+            hints.append(ToolHint(message=result.return_code_interpretation))
+
+        if result.destructive_warning:
+            hints.append(ToolHint(message=f"Warning: {result.destructive_warning}"))
+
+        if result.sandboxed and result.sandbox_temp_dir:
+            hints.append(
+                ToolHint(
+                    message=(
+                        "Command ran in sandbox mode with isolated temporary directory: "
+                        f"{result.sandbox_temp_dir}"
+                    )
+                )
+            )
+        elif result.sandbox_bypass_reason:
+            hints.append(
+                ToolHint(
+                    message=(
+                        "Command ran without sandbox. "
+                        f"Reason: {result.sandbox_bypass_reason}"
+                    )
+                )
+            )
+
+        if result.auto_backgrounded:
+            hints.append(
+                ToolHint(
+                    message=(
+                        "Command was automatically moved to background due to "
+                        "long-timeout policy."
+                    )
+                )
+            )
+
+        return hints
+
+    @staticmethod
+    def _attach_observability(base_meta: dict, result: BashToolOutput) -> dict:
+        meta = dict(base_meta)
+        if result.observability:
+            meta["observability"] = result.observability
+        return meta

langchain_agentx/tools/bash/sandbox_decision.py

@@ -0,0 +1,133 @@
+"""
+tools/bash/sandbox_decision.py — BashRuntimeTool 模块4：沙箱决策层
+
+职责：
+    在真正执行命令前，决定本次 Bash 调用是否应走 sandbox backend，
+    并给出 bypass / excluded / override_not_allowed 等结构化原因。
+
+设计目标：
+    - 对齐 CC `shouldUseSandbox.ts` 的决策链，但按本工程 OOP 风格拆成独立协作者
+    - 让 `tool.py` 只负责编排，不在执行前散落沙箱规则
+    - 为后续替换成真实 OS 级沙箱后端保留稳定输入输出契约
+
+当前覆盖：
+    - sandbox enable / disable 总开关
+    - `dangerously_disable_sandbox` 参数
+    - ctx.tool_flags 注入的策略控制（允许绕过、excluded commands）
+    - 基于 canonical command 的 excluded pattern 匹配
+
+与 CC 对照：
+    对应 CC `shouldUseSandbox.ts` 的基础版能力，不包含其动态配置系统和完整
+    SandboxManager 实现。
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext
+
+from .bash_hardening import BashCommandCanonicalizer
+
+
+@dataclass(frozen=True)
+class BashSandboxConfig:
+    enabled: bool = True
+    allow_unsandboxed_commands: bool = False
+    excluded_commands: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class BashSandboxDecision:
+    use_sandbox: bool
+    reason: str
+    matched_excluded_pattern: str | None = None
+    override_requested: bool = False
+    override_allowed: bool = False
+
+
+class BashSandboxDecisionEngine:
+    """Bash 沙箱决策协作者。"""
+
+    def __init__(
+        self,
+        config: BashSandboxConfig | None = None,
+        canonicalizer: BashCommandCanonicalizer | None = None,
+    ) -> None:
+        self._config = config or BashSandboxConfig()
+        self._canonicalizer = canonicalizer or BashCommandCanonicalizer()
+
+    def decide(
+        self,
+        *,
+        command: str,
+        dangerously_disable_sandbox: bool,
+        ctx: ToolExecutionContext,
+    ) -> BashSandboxDecision:
+        if not self._config.enabled:
+            return BashSandboxDecision(use_sandbox=False, reason="sandbox_disabled")
+
+        if not command.strip():
+            return BashSandboxDecision(use_sandbox=False, reason="empty_command")
+
+        matched_pattern = self._match_excluded_pattern(command, ctx)
+        if matched_pattern is not None:
+            return BashSandboxDecision(
+                use_sandbox=False,
+                reason="excluded_command",
+                matched_excluded_pattern=matched_pattern,
+            )
+
+        if dangerously_disable_sandbox:
+            override_allowed = self._override_allowed(ctx)
+            if override_allowed:
+                return BashSandboxDecision(
+                    use_sandbox=False,
+                    reason="explicit_override",
+                    override_requested=True,
+                    override_allowed=True,
+                )
+            return BashSandboxDecision(
+                use_sandbox=True,
+                reason="override_not_allowed",
+                override_requested=True,
+                override_allowed=False,
+            )
+
+        return BashSandboxDecision(use_sandbox=True, reason="sandbox_enabled")
+
+    def _match_excluded_pattern(
+        self,
+        command: str,
+        ctx: ToolExecutionContext,
+    ) -> str | None:
+        candidates = self._candidate_commands(command)
+        configured_patterns = list(self._config.excluded_commands)
+        configured_patterns.extend(
+            tuple((ctx.tool_flags or {}).get("sandbox_excluded_commands", ()))
+        )
+        for pattern in configured_patterns:
+            if any(self._matches_pattern(candidate, pattern) for candidate in candidates):
+                return pattern
+        return None
+
+    def _candidate_commands(self, command: str) -> list[str]:
+        canonical = self._canonicalizer.canonicalize(command)
+        candidates = [command.strip()]
+        if canonical and canonical not in candidates:
+            candidates.append(canonical)
+        return candidates
+
+    def _override_allowed(self, ctx: ToolExecutionContext) -> bool:
+        tool_flags = ctx.tool_flags or {}
+        return bool(
+            tool_flags.get("allow_dangerously_disable_sandbox")
+            or self._config.allow_unsandboxed_commands
+        )
+
+    @staticmethod
+    def _matches_pattern(command: str, pattern: str) -> bool:
+        if any(symbol in pattern for symbol in "*?[]"):
+            return fnmatch.fnmatch(command, pattern)
+        return command == pattern or command.startswith(f"{pattern} ")