mycode-coding-agent 0.1.0__py3-none-any.whl

mycode/tools/registry.py

@@ -0,0 +1,279 @@
+import asyncio
+from collections.abc import Iterable
+from dataclasses import dataclass, field, replace
+
+from mycode.permissions import (
+    ConfirmationRequest,
+    Confirmer,
+    DefaultPermissionChecker,
+    PermissionChecker,
+    PermissionDecision,
+    PermissionRequest,
+    RejectingConfirmer,
+    ScopedApprovalState,
+)
+from mycode.tools.base import (
+    BaseTool,
+    SyncTool,
+    ToolArgumentValidationError,
+    ToolResult,
+)
+
+
+class DuplicateToolError(ValueError):
+    pass
+
+
+class ToolNotFoundError(KeyError):
+    pass
+
+
+@dataclass
+class ToolRegistry:
+    _tools: dict[str, BaseTool] = field(default_factory=dict)
+    permission_checker: PermissionChecker = field(default_factory=DefaultPermissionChecker)
+    confirmer: Confirmer = field(default_factory=RejectingConfirmer)
+    scoped_approvals: ScopedApprovalState = field(default_factory=ScopedApprovalState)
+
+    @classmethod
+    def from_tools(
+        cls,
+        tools: Iterable[BaseTool],
+        *,
+        permission_checker: PermissionChecker | None = None,
+        confirmer: Confirmer | None = None,
+    ) -> "ToolRegistry":
+        registry = cls()
+        if permission_checker is not None:
+            registry.permission_checker = permission_checker
+        if confirmer is not None:
+            registry.confirmer = confirmer
+
+        for tool in tools:
+            registry.register(tool)
+
+        return registry
+
+    def register(self, tool: BaseTool) -> None:
+        if tool.name in self._tools:
+            raise DuplicateToolError(f"Tool already registered: {tool.name}")
+
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> BaseTool | None:
+        return self._tools.get(name)
+
+    def require(self, name: str) -> BaseTool:
+        tool = self.get(name)
+
+        if tool is None:
+            raise ToolNotFoundError(f"Tool not found: {name}")
+
+        return tool
+
+    def run_tool(self, name: str, arguments: dict[str, object]) -> ToolResult:
+        tool = self.get(name)
+
+        if tool is None:
+            return ToolResult.failure(
+                error=f"Tool not found: {name}",
+                metadata={"tool_name": name},
+            )
+        if not isinstance(tool, SyncTool):
+            return ToolResult.failure(
+                error="Tool requires async execution path",
+                metadata={
+                    "tool_name": name,
+                    "reason": "async_execution_required",
+                },
+            )
+
+        try:
+            args = tool.parse_arguments(arguments)
+        except ToolArgumentValidationError as error:
+            return ToolResult.failure(
+                error="Invalid tool arguments",
+                metadata={"validation_errors": error.errors},
+            )
+
+        try:
+            request, decision = tool.check_permission(args, self.permission_checker)
+        except Exception as error:  # noqa: BLE001 - normalize permission boundary
+            return ToolResult.failure(
+                error=f"Tool permission check failed: {error}",
+                metadata={
+                    "tool_name": name,
+                    "exception_type": type(error).__name__,
+                },
+            )
+
+        decision, permission_failure = _resolve_permission(
+            request,
+            decision,
+            self.confirmer,
+            self.scoped_approvals,
+        )
+        if permission_failure is not None:
+            return permission_failure
+
+        return _with_confirmation_metadata(tool.run_authorized(args, decision), decision)
+
+    def is_concurrency_safe(self, name: str) -> bool:
+        tool = self.get(name)
+        if tool is None:
+            return False
+
+        return bool(
+            getattr(tool, "concurrency_safe", False)
+            and getattr(tool, "capability", None) == "read"
+            and getattr(tool, "risk", None) == "low"
+        )
+
+    async def run_tool_async(
+        self,
+        name: str,
+        arguments: dict[str, object],
+        *,
+        permission_lock: asyncio.Lock,
+    ) -> ToolResult:
+        """Run any tool through the common async execution contract."""
+        tool = self.get(name)
+
+        if tool is None:
+            return ToolResult.failure(
+                error=f"Tool not found: {name}",
+                metadata={"tool_name": name},
+            )
+
+        try:
+            args = tool.parse_arguments(arguments)
+        except ToolArgumentValidationError as error:
+            return ToolResult.failure(
+                error="Invalid tool arguments",
+                metadata={"validation_errors": error.errors},
+            )
+
+        async with permission_lock:
+            try:
+                request, decision = tool.check_permission(
+                    args,
+                    self.permission_checker,
+                )
+            except Exception as error:  # noqa: BLE001 - normalize permission boundary
+                return ToolResult.failure(
+                    error=f"Tool permission check failed: {error}",
+                    metadata={
+                        "tool_name": name,
+                        "exception_type": type(error).__name__,
+                    },
+                )
+
+            decision, permission_failure = _resolve_permission(
+                request,
+                decision,
+                self.confirmer,
+                self.scoped_approvals,
+            )
+            if permission_failure is not None:
+                return permission_failure
+
+        try:
+            result = await tool.run_authorized_async(args, decision)
+        except Exception as error:  # noqa: BLE001 - normalize tool boundary
+            result = ToolResult.failure(
+                error=f"Tool execution failed: {error}",
+                metadata={"exception_type": type(error).__name__},
+            )
+        return _with_confirmation_metadata(result, decision)
+
+    def list_tools(self) -> list[BaseTool]:
+        return list(self._tools.values())
+
+    def get_schemas(self) -> list[dict[str, object]]:
+        return [tool.get_schema() for tool in self.list_tools()]
+
+
+def _with_confirmation_metadata(
+    result: ToolResult, decision: PermissionDecision,
+) -> ToolResult:
+    """Keep approval provenance even when a tool does not copy its decision."""
+    keys = (
+        "confirmation_status", "confirmation_scope", "confirmation_source",
+        "confirmation_message", "confirmation_metadata", "grant_scope",
+    )
+    metadata = {key: decision.metadata[key] for key in keys if key in decision.metadata}
+    if not metadata:
+        return result
+    return replace(result, metadata={**result.metadata, **metadata})
+
+
+def _permission_failure(decision: PermissionDecision) -> ToolResult:
+    return ToolResult.failure(
+        error=decision.message or "Permission denied",
+        metadata={
+            "permission_status": decision.status,
+            "permission_reason": decision.reason,
+            **decision.metadata,
+        },
+    )
+
+
+def _resolve_permission(
+    request: PermissionRequest,
+    decision: PermissionDecision,
+    confirmer: Confirmer,
+    scoped_approvals: ScopedApprovalState,
+) -> tuple[PermissionDecision, ToolResult | None]:
+    if decision.status == "deny":
+        return decision, _permission_failure(decision)
+
+    if decision.status != "ask":
+        return decision, None
+
+    grant_scope = scoped_approvals.allows_ask()
+    if grant_scope is not None:
+        return PermissionDecision.allow(
+            message=decision.message,
+            metadata={
+                **decision.metadata,
+                "confirmation_status": "approved",
+                "confirmation_scope": grant_scope,
+                "confirmation_source": "scoped_grant",
+                "grant_scope": grant_scope,
+            },
+        ), None
+
+    confirmation_request = ConfirmationRequest(
+        permission_request=request,
+        permission_decision=decision,
+        prompt=decision.message,
+        metadata=decision.metadata,
+    )
+    confirmation_result = confirmer.confirm(confirmation_request)
+    if confirmation_result.status == "rejected":
+        return decision, ToolResult.failure(
+            error=confirmation_result.message
+            or "Permission confirmation rejected",
+            metadata={
+                "permission_status": decision.status,
+                "permission_reason": decision.reason,
+                "confirmation_status": confirmation_result.status,
+                "confirmation_message": confirmation_result.message,
+                **decision.metadata,
+                "confirmation_metadata": confirmation_result.metadata,
+            },
+        )
+
+    assert confirmation_result.scope is not None
+    scoped_approvals.approve(confirmation_result.scope)
+    return PermissionDecision.allow(
+        message=decision.message,
+        metadata={
+            **decision.metadata,
+            "confirmation_status": confirmation_result.status,
+            "confirmation_scope": confirmation_result.scope,
+            "confirmation_source": "explicit",
+            "confirmation_message": confirmation_result.message,
+            "confirmation_metadata": confirmation_result.metadata,
+        },
+    ), None

mycode/tools/run_command.py

@@ -0,0 +1,237 @@
+import json
+import subprocess
+from pathlib import Path
+
+from pydantic import Field, field_validator
+
+from mycode.permissions import PermissionChecker, PermissionDecision, PermissionRequest
+from mycode.tools.base import PydanticTool, ToolArgs, ToolResult
+from mycode.tools.command_executor import CommandExecutionArgs, execute_command
+from mycode.tools.command_risk import CommandRiskAnalysis, analyze_command_risk
+from mycode.tools.permission_metadata import with_permission_metadata
+from mycode.tools.workspace import Workspace, WorkspacePathError
+
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_MAX_OUTPUT_CHARS = 12000
+MAX_TIMEOUT_SECONDS = 300.0
+MAX_OUTPUT_CHARS = 200000
+COMMAND_DESCRIPTION = (
+    "要执行的 argv 字符串数组。第一个元素是可执行程序，后续元素是参数。"
+    "不是 Shell 命令字符串，不支持 &&、||、|、>、< 等 Shell 操作符，也不会展开"
+    " *.py 等通配符。需要切换工作目录时使用 cwd，不要执行 cd。例如："
+    "[\"pytest\", \"tests/test_a.py\", \"-q\"]。"
+)
+COMMAND_VALIDATION_ERROR = (
+    "command 必须是 argv 字符串数组，而不是 Shell 命令字符串。请使用 cwd 代替 cd；"
+    "不支持 &&、||、|、>、< 等 Shell 语法。"
+)
+CWD_DESCRIPTION = (
+    "命令执行时的工作目录，必须位于 workspace 内。需要切换目录时使用该参数，不要执行 cd。"
+)
+
+
+class RunCommandArgs(ToolArgs):
+    command: list[str] = Field(min_length=1, description=COMMAND_DESCRIPTION)
+    cwd: str = Field(default=".", min_length=1, description=CWD_DESCRIPTION)
+    timeout_seconds: float = Field(
+        default=DEFAULT_TIMEOUT_SECONDS,
+        gt=0,
+        le=MAX_TIMEOUT_SECONDS,
+    )
+    max_output_chars: int = Field(
+        default=DEFAULT_MAX_OUTPUT_CHARS,
+        ge=0,
+        le=MAX_OUTPUT_CHARS,
+    )
+
+    @field_validator("command", mode="before")
+    @classmethod
+    def normalize_json_encoded_command(cls, value: object) -> object:
+        """Accept one common Provider mistake without introducing shell parsing."""
+
+        if not isinstance(value, str):
+            if not isinstance(value, (list, tuple)) or not value or any(
+                not isinstance(part, str) for part in value
+            ):
+                raise ValueError(COMMAND_VALIDATION_ERROR)
+            return value
+        try:
+            decoded = json.loads(value)
+        except json.JSONDecodeError as error:
+            raise ValueError(COMMAND_VALIDATION_ERROR) from error
+        if not isinstance(decoded, list) or not decoded or any(
+            not isinstance(part, str) for part in decoded
+        ):
+            raise ValueError(COMMAND_VALIDATION_ERROR)
+        return decoded
+
+    @field_validator("command")
+    @classmethod
+    def command_parts_must_not_be_empty(cls, value: list[str]) -> list[str]:
+        if any(part == "" for part in value):
+            raise ValueError(COMMAND_VALIDATION_ERROR)
+        if any("\x00" in part for part in value):
+            raise ValueError(COMMAND_VALIDATION_ERROR)
+
+        return value
+
+
+class RunCommandTool(PydanticTool[RunCommandArgs]):
+    name = "run_command"
+    description = (
+        "在 workspace 内执行非交互命令。command 使用结构化 argv，命令直接执行，不经过 Shell 解释。"
+    )
+    args_model = RunCommandArgs
+    capability = "command"
+    risk = "high"
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+
+    def build_permission_request(self, args: RunCommandArgs) -> PermissionRequest:
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=self.name,
+            target=_display_command(args.command),
+            arguments=args.model_dump(),
+            description="Run a non-interactive command.",
+        )
+
+    def check_permission(
+        self,
+        args: RunCommandArgs,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        try:
+            resolved_cwd = self.workspace.resolve_path(args.cwd)
+        except WorkspacePathError:
+            return request, PermissionDecision.deny(
+                reason="outside_workspace",
+                message=f"Command working directory is outside workspace: {args.cwd}",
+                metadata=_command_metadata(
+                    args=args,
+                    workspace_root=self.workspace.root,
+                    resolved_cwd=_resolve_candidate_path(self.workspace, args.cwd),
+                    cwd_scope="outside_workspace",
+                ),
+            )
+
+        risk_analysis = analyze_command_risk(args.command)
+        metadata = _command_metadata(
+            args=args,
+            workspace_root=self.workspace.root,
+            resolved_cwd=resolved_cwd,
+            cwd_scope="inside_workspace",
+            risk_analysis=risk_analysis,
+        )
+
+        if not resolved_cwd.exists():
+            return request, PermissionDecision.deny(
+                reason="unsupported_operation",
+                message=f"Command working directory does not exist: {args.cwd}",
+                metadata=metadata,
+            )
+
+        if not resolved_cwd.is_dir():
+            return request, PermissionDecision.deny(
+                reason="unsupported_operation",
+                message=f"Command working directory is not a directory: {args.cwd}",
+                metadata=metadata,
+            )
+
+        if risk_analysis.decision == "deny":
+            return request, PermissionDecision.deny(
+                reason="dangerous_command",
+                message=risk_analysis.reason,
+                metadata=metadata,
+            )
+
+        decision = permission_checker.check(
+            request,
+            self.get_permission_profile(),
+        )
+
+        return request, with_permission_metadata(decision, metadata)
+
+    def run_authorized(
+        self,
+        args: RunCommandArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        try:
+            cwd = Path(str(decision.metadata["resolved_cwd"]))
+            return execute_command(
+                args=CommandExecutionArgs(
+                    command=args.command,
+                    timeout_seconds=args.timeout_seconds,
+                    max_output_chars=args.max_output_chars,
+                ),
+                cwd=cwd,
+                permission_metadata=decision.metadata,
+                permission_status=decision.status,
+            )
+        except Exception as error:
+            return ToolResult.failure(
+                error=f"Tool execution failed: {error}",
+                metadata={
+                    **decision.metadata,
+                    "permission_status": decision.status,
+                    "exception_type": type(error).__name__,
+                },
+            )
+
+    def _run(self, args: RunCommandArgs) -> ToolResult:
+        return ToolResult.failure(
+            error="run_command must be run through ToolRegistry.run_tool().",
+            metadata={
+                "command": args.command,
+                "cwd": args.cwd,
+                "reason": "permission_required",
+            },
+        )
+
+
+def _resolve_candidate_path(workspace: Workspace, path: str) -> Path:
+    requested_path = Path(path)
+    if requested_path.is_absolute():
+        return requested_path.resolve(strict=False)
+
+    return (workspace.root / requested_path).resolve(strict=False)
+
+
+def _command_metadata(
+    *,
+    args: RunCommandArgs,
+    workspace_root: Path,
+    resolved_cwd: Path,
+    cwd_scope: str,
+    risk_analysis: CommandRiskAnalysis | None = None,
+) -> dict[str, object]:
+    metadata: dict[str, object] = {
+        "command": list(args.command),
+        "command_display": _display_command(args.command),
+        "cwd": args.cwd,
+        "resolved_cwd": resolved_cwd.as_posix(),
+        "workspace_root": workspace_root.as_posix(),
+        "cwd_scope": cwd_scope,
+        "timeout_seconds": args.timeout_seconds,
+        "max_output_chars": args.max_output_chars,
+    }
+    if risk_analysis is not None:
+        metadata.update(
+            {
+                "command_risk_category": risk_analysis.category,
+                "command_risk": risk_analysis.risk,
+                "command_risk_decision": risk_analysis.decision,
+                "command_risk_reason": risk_analysis.reason,
+            }
+        )
+
+    return metadata
+
+
+def _display_command(command: list[str]) -> str:
+    return subprocess.list2cmdline(command)