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

mycode/tools/inspect_changes.py

@@ -0,0 +1,269 @@
+from pathlib import Path
+import re
+import shutil
+from typing import Literal, Self
+
+from pydantic import Field, field_validator, model_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.ignore import is_sensitive_path
+from mycode.tools.path_permissions import PathPermissionPolicy
+from mycode.tools.permission_metadata import with_permission_metadata
+from mycode.tools.workspace import Workspace, WorkspacePathError
+
+
+DEFAULT_INSPECT_TIMEOUT_SECONDS = 30.0
+DEFAULT_INSPECT_MAX_OUTPUT_CHARS = 20000
+MAX_INSPECT_OUTPUT_CHARS = 100000
+MAX_INSPECT_PATHS = 20
+SAFE_REF_PATTERN = re.compile(
+    r"(?:HEAD|[A-Za-z0-9][A-Za-z0-9._/-]*)(?:[~^][0-9]+)?"
+)
+
+InspectChangesAction = Literal["status", "diff"]
+
+
+class InspectChangesArgs(ToolArgs):
+    action: InspectChangesAction
+    paths: list[str] = Field(default_factory=list, max_length=MAX_INSPECT_PATHS)
+    staged: bool = False
+    base_ref: str | None = Field(default=None, max_length=200)
+    max_output_chars: int = Field(
+        default=DEFAULT_INSPECT_MAX_OUTPUT_CHARS,
+        ge=0,
+        le=MAX_INSPECT_OUTPUT_CHARS,
+    )
+
+    @field_validator("paths")
+    @classmethod
+    def validate_plain_paths(cls, values: list[str]) -> list[str]:
+        normalized: list[str] = []
+        for value in values:
+            path = value.strip()
+            if path == "":
+                raise ValueError("inspect_changes paths must not be blank.")
+            if len(path) > 500:
+                raise ValueError("inspect_changes paths must not exceed 500 characters.")
+            if path.startswith(":") or any(marker in path for marker in ("*", "?", "[", "]", "\x00")):
+                raise ValueError("inspect_changes paths must be literal paths, not pathspecs.")
+            normalized.append(path)
+        return normalized
+
+    @field_validator("base_ref")
+    @classmethod
+    def validate_base_ref(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        if (
+            normalized == ""
+            or normalized.startswith("-")
+            or SAFE_REF_PATTERN.fullmatch(normalized) is None
+        ):
+            raise ValueError("base_ref must be a plain Git revision, not an option.")
+        return normalized
+
+    @model_validator(mode="after")
+    def action_arguments_must_match(self) -> Self:
+        if self.action == "status" and (
+            self.paths or self.staged or self.base_ref is not None
+        ):
+            raise ValueError(
+                "status does not accept paths, staged, or base_ref arguments."
+            )
+        if self.action == "diff" and not self.paths:
+            raise ValueError("diff requires at least one explicit path.")
+        return self
+
+
+class InspectChangesTool(PydanticTool[InspectChangesArgs]):
+    name = "inspect_changes"
+    description = (
+        "Inspect Git status or a bounded diff for explicit non-sensitive workspace paths."
+    )
+    args_model = InspectChangesArgs
+    capability = "read"
+    risk = "low"
+    concurrency_safe = True
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+
+    def build_permission_request(self, args: InspectChangesArgs) -> PermissionRequest:
+        target = "repository status" if args.action == "status" else ", ".join(args.paths)
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=f"{self.name}.{args.action}",
+            target=target,
+            arguments=args.model_dump(),
+            description="Inspect repository changes without arbitrary command execution.",
+        )
+
+    def check_permission(
+        self,
+        args: InspectChangesArgs,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        resolved_paths: list[str] = []
+        for path in args.paths:
+            try:
+                resolved = self.workspace.resolve_path(path)
+            except WorkspacePathError:
+                return request, PermissionDecision.deny(
+                    reason="outside_workspace",
+                    message=f"inspect_changes path is outside workspace: {path}",
+                    metadata={
+                        "path": path,
+                        "workspace_root": self.workspace.root.as_posix(),
+                        "inspect_action": args.action,
+                    },
+                )
+            if is_sensitive_path(resolved, self.workspace.root):
+                return request, PermissionDecision.deny(
+                    reason="sensitive_path",
+                    message=f"inspect_changes refuses sensitive path content: {path}",
+                    metadata={
+                        "path": path,
+                        "resolved_path": resolved.as_posix(),
+                        "workspace_root": self.workspace.root.as_posix(),
+                        "inspect_action": args.action,
+                    },
+                )
+
+            path_decision = PathPermissionPolicy(self.workspace).check_path(request, path)
+            if path_decision.status != "allow":
+                return request, with_permission_metadata(
+                    path_decision,
+                    {
+                        "inspect_action": args.action,
+                        "resolved_paths": [*resolved_paths, resolved.as_posix()],
+                        "staged": args.staged,
+                        "base_ref": args.base_ref,
+                    },
+                )
+            resolved_paths.append(resolved.as_posix())
+
+        decision = permission_checker.check(request, self.get_permission_profile())
+        if decision.status != "allow":
+            return request, decision
+        return request, PermissionDecision.allow(
+            message=decision.message,
+            metadata={
+                **decision.metadata,
+                "workspace_root": self.workspace.root.as_posix(),
+                "resolved_cwd": self.workspace.root.as_posix(),
+                "inspect_action": args.action,
+                "resolved_paths": resolved_paths,
+                "staged": args.staged,
+                "base_ref": args.base_ref,
+            },
+        )
+
+    def run_authorized(
+        self,
+        args: InspectChangesArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        try:
+            return self._run_authorized(args, decision)
+        except Exception as error:
+            return ToolResult.failure(
+                error=f"Tool execution failed: {error}",
+                metadata={
+                    **decision.metadata,
+                    "exception_type": type(error).__name__,
+                },
+            )
+
+    def _run_authorized(
+        self,
+        args: InspectChangesArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        git_executable = shutil.which("git")
+        if git_executable is None:
+            return ToolResult.failure(
+                error="Git executable was not found.",
+                metadata={**decision.metadata, "reason": "git_not_found"},
+            )
+        resolved_git = Path(git_executable).resolve(strict=False)
+        if resolved_git.is_relative_to(self.workspace.root):
+            return ToolResult.failure(
+                error="Refusing to execute a workspace-local Git executable.",
+                metadata={
+                    **decision.metadata,
+                    "reason": "workspace_local_executable",
+                    "git_executable": resolved_git.as_posix(),
+                },
+            )
+
+        command = self._build_command(args, resolved_git)
+        safe_git_flags = [
+            "--no-optional-locks",
+            "-c core.fsmonitor=false",
+            "--no-pager",
+            "--ignore-submodules=all",
+        ]
+        if args.action == "diff":
+            safe_git_flags.extend(["--no-ext-diff", "--no-textconv"])
+        return execute_command(
+            args=CommandExecutionArgs(
+                command=command,
+                timeout_seconds=DEFAULT_INSPECT_TIMEOUT_SECONDS,
+                max_output_chars=args.max_output_chars,
+            ),
+            cwd=self.workspace.root,
+            permission_metadata={
+                **decision.metadata,
+                "command": command,
+                "safe_git_flags": safe_git_flags,
+            },
+            permission_status=decision.status,
+        )
+
+    def _run(self, args: InspectChangesArgs) -> ToolResult:
+        return ToolResult.failure(
+            error="inspect_changes must be run through ToolRegistry.run_tool().",
+            metadata={"action": args.action, "reason": "permission_required"},
+        )
+
+    def _build_command(self, args: InspectChangesArgs, git_executable: Path) -> list[str]:
+        command = [
+            git_executable.as_posix(),
+            "--no-optional-locks",
+            "-c",
+            "core.fsmonitor=false",
+            "--no-pager",
+        ]
+        if args.action == "status":
+            return [
+                *command,
+                "status",
+                "--short",
+                "--branch",
+                "--untracked-files=all",
+                "--ignore-submodules=all",
+            ]
+
+        command.extend(
+            [
+                "diff",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--ignore-submodules=all",
+            ]
+        )
+        if args.staged:
+            command.append("--cached")
+        if args.base_ref is not None:
+            command.append(args.base_ref)
+        resolved_paths = [
+            self.workspace.resolve_path(path).relative_to(self.workspace.root).as_posix()
+            for path in args.paths
+        ]
+        command.extend(["--", *resolved_paths])
+        return command

mycode/tools/load_skill.py

@@ -0,0 +1,92 @@
+from pydantic import Field
+
+from mycode.skills import (
+    MAX_ACTIVE_SKILLS,
+    ActiveSkillLimitError,
+    ActiveSkillState,
+    SkillNotFoundError,
+    SkillRegistry,
+)
+from mycode.tools.base import PydanticTool, ToolArgs, ToolResult
+
+
+class LoadSkillArgs(ToolArgs):
+    name: str = Field(min_length=1)
+
+
+class LoadSkillTool(PydanticTool[LoadSkillArgs]):
+    name = "load_skill"
+    description = (
+        "加载一个与当前任务相关的 Skill。加载后的完整 Skill 指导会从下一轮模型调用"
+        "开始可见；如果后续操作依赖该 Skill，请先加载 Skill，再根据加载后的指导继续执行。"
+    )
+    args_model = LoadSkillArgs
+    capability = "control"
+    risk = "low"
+
+    def __init__(self, registry: SkillRegistry, state: ActiveSkillState) -> None:
+        self.registry = registry
+        self.state = state
+
+    def _run(self, args: LoadSkillArgs) -> ToolResult:
+        try:
+            skill = self.registry.require(args.name)
+        except SkillNotFoundError:
+            return ToolResult.failure(
+                error=f"Skill not found: {args.name}",
+                metadata={"skill_name": args.name, "already_active": False},
+            )
+        if self.state.is_active(skill.name):
+            return ToolResult.success(
+                content=f"Skill '{skill.name}' 已经激活。",
+                metadata={
+                    "skill_name": skill.name,
+                    "skill_source": skill.source,
+                    "already_active": True,
+                },
+            )
+        if len(self.state.get_active()) >= MAX_ACTIVE_SKILLS:
+            return ToolResult.failure(
+                error=f"最多只能同时激活 {MAX_ACTIVE_SKILLS} 个 Skill。",
+                metadata={
+                    "skill_name": skill.name,
+                    "skill_source": skill.source,
+                    "already_active": False,
+                    "active_skill_count": len(self.state.get_active()),
+                    "max_active_skills": MAX_ACTIVE_SKILLS,
+                },
+            )
+        try:
+            instructions = self.registry.load_instructions(skill.name)
+            self.state.activate(skill, instructions)
+        except ActiveSkillLimitError as error:
+            return ToolResult.failure(
+                error=str(error),
+                metadata={
+                    "skill_name": skill.name,
+                    "skill_source": skill.source,
+                    "already_active": False,
+                    "active_skill_count": len(self.state.get_active()),
+                    "max_active_skills": MAX_ACTIVE_SKILLS,
+                },
+            )
+        except ValueError as error:
+            return ToolResult.failure(
+                error=f"无法加载 Skill '{skill.name}'：{error}",
+                metadata={
+                    "skill_name": skill.name,
+                    "skill_source": skill.source,
+                    "already_active": False,
+                },
+            )
+        metadata = {
+            "skill_name": skill.name,
+            "skill_source": skill.source,
+            "already_active": False,
+        }
+        return ToolResult.success(
+            content=(
+                f"Skill '{skill.name}' 已为当前任务激活。完整指导将从下一轮模型调用开始可见。"
+            ),
+            metadata=metadata,
+        )

mycode/tools/memory.py

@@ -0,0 +1,264 @@
+from pydantic import field_validator
+
+from mycode.memory import (
+    MemoryKind,
+    MemoryScope,
+    MemoryStore,
+    SensitiveMemoryError,
+    validate_memory_content,
+    validate_memory_key,
+)
+from mycode.permissions import PermissionChecker, PermissionDecision, PermissionRequest
+from mycode.tools.base import PydanticTool, ToolArgs, ToolResult
+from mycode.tools.permission_metadata import with_permission_metadata
+
+
+class ListMemoriesArgs(ToolArgs):
+    scope: MemoryScope | None = None
+
+
+class SaveMemoryArgs(ToolArgs):
+    scope: MemoryScope
+    kind: MemoryKind
+    key: str
+    content: str
+
+    @field_validator("key")
+    @classmethod
+    def validate_key(cls, value: str) -> str:
+        return validate_memory_key(value)
+
+    @field_validator("content")
+    @classmethod
+    def validate_content(cls, value: str) -> str:
+        try:
+            return validate_memory_content(value, max_chars=2000)
+        except SensitiveMemoryError as error:
+            raise ValueError(str(error)) from error
+
+
+class DeleteMemoryArgs(ToolArgs):
+    scope: MemoryScope
+    key: str
+
+    @field_validator("key")
+    @classmethod
+    def validate_key(cls, value: str) -> str:
+        return validate_memory_key(value)
+
+
+class ListMemoriesTool(PydanticTool[ListMemoriesArgs]):
+    name = "list_memories"
+    description = "List safe long-term memories for the current user or project."
+    args_model = ListMemoriesArgs
+    capability = "read"
+    risk = "low"
+    concurrency_safe = True
+
+    def __init__(self, store: MemoryStore) -> None:
+        self.store = store
+
+    def _run(self, args: ListMemoriesArgs) -> ToolResult:
+        entries = self.store.list_entries(args.scope)
+        issues = self.store.list_issues(args.scope)
+        lines: list[str] = []
+        for entry in entries:
+            lines.extend(
+                [
+                    f"[{entry.scope}/{entry.kind}] {entry.key}",
+                    entry.content,
+                    "",
+                ]
+            )
+        if issues:
+            lines.append("WITHHELD_OR_INVALID")
+            lines.extend(issue.display for issue in issues)
+        content = "\n".join(lines).rstrip()
+        if content == "":
+            content = "No long-term memories found."
+        return ToolResult.success(
+            content=content,
+            metadata={
+                "scope": args.scope or "all",
+                "memory_count": len(entries),
+                "issue_count": len(issues),
+            },
+        )
+
+
+class SaveMemoryTool(PydanticTool[SaveMemoryArgs]):
+    name = "save_memory"
+    description = (
+        "Create or correct one user-level or project-level long-term memory. "
+        "Only use when the user explicitly asks to remember the information."
+    )
+    args_model = SaveMemoryArgs
+    capability = "write"
+    risk = "medium"
+
+    def __init__(self, store: MemoryStore) -> None:
+        self.store = store
+
+    def build_permission_request(self, args: SaveMemoryArgs) -> PermissionRequest:
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=f"save {args.scope} memory",
+            target=str(self.store.path_for_scope(args.scope)),
+            arguments={
+                "scope": args.scope,
+                "kind": args.kind,
+                "key": args.key,
+                "content_chars": len(args.content),
+            },
+            description="Save one reviewed long-term memory.",
+        )
+
+    def check_permission(
+        self,
+        args: SaveMemoryArgs,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        decision = permission_checker.check(request, self.get_permission_profile())
+        return request, with_permission_metadata(
+            decision,
+            {
+                "memory_scope": args.scope,
+                "memory_kind": args.kind,
+                "memory_key": args.key,
+                "memory_content": args.content,
+                "memory_path": str(self.store.path_for_scope(args.scope)),
+            },
+        )
+
+    def run_authorized(
+        self,
+        args: SaveMemoryArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        try:
+            result = self.store.save(
+                scope=args.scope,
+                kind=args.kind,
+                key=args.key,
+                content=args.content,
+            )
+        except Exception as error:
+            return ToolResult.failure(
+                error=f"Memory write failed: {error}",
+                metadata={
+                    **_safe_permission_metadata(decision),
+                    "memory_scope": args.scope,
+                    "memory_kind": args.kind,
+                    "memory_key": args.key,
+                    "exception_type": type(error).__name__,
+                },
+            )
+        return ToolResult.success(
+            content=(
+                f"Memory {result.action}: "
+                f"[{args.scope}/{args.kind}] {args.key}"
+            ),
+            metadata={
+                **_safe_permission_metadata(decision),
+                "memory_scope": args.scope,
+                "memory_kind": args.kind,
+                "memory_key": args.key,
+                "memory_action": result.action,
+                "memory_path": str(result.path),
+            },
+        )
+
+    def _run(self, args: SaveMemoryArgs) -> ToolResult:
+        return ToolResult.failure(
+            error="save_memory must be run through ToolRegistry.run_tool().",
+            metadata={"memory_key": args.key, "reason": "permission_required"},
+        )
+
+
+class DeleteMemoryTool(PydanticTool[DeleteMemoryArgs]):
+    name = "delete_memory"
+    description = "Delete one user-level or project-level long-term memory by key."
+    args_model = DeleteMemoryArgs
+    capability = "write"
+    risk = "medium"
+
+    def __init__(self, store: MemoryStore) -> None:
+        self.store = store
+
+    def build_permission_request(self, args: DeleteMemoryArgs) -> PermissionRequest:
+        return PermissionRequest(
+            tool_name=self.name,
+            capability=self.capability,
+            action=f"delete {args.scope} memory",
+            target=str(self.store.path_for_scope(args.scope)),
+            arguments={"scope": args.scope, "key": args.key},
+            description="Delete one long-term memory.",
+        )
+
+    def check_permission(
+        self,
+        args: DeleteMemoryArgs,
+        permission_checker: PermissionChecker,
+    ) -> tuple[PermissionRequest, PermissionDecision]:
+        request = self.build_permission_request(args)
+        decision = permission_checker.check(request, self.get_permission_profile())
+        return request, with_permission_metadata(
+            decision,
+            {
+                "memory_scope": args.scope,
+                "memory_key": args.key,
+                "memory_path": str(self.store.path_for_scope(args.scope)),
+            },
+        )
+
+    def run_authorized(
+        self,
+        args: DeleteMemoryArgs,
+        decision: PermissionDecision,
+    ) -> ToolResult:
+        try:
+            deleted = self.store.delete(scope=args.scope, key=args.key)
+        except Exception as error:
+            return ToolResult.failure(
+                error=f"Memory delete failed: {error}",
+                metadata={
+                    **_safe_permission_metadata(decision),
+                    "memory_scope": args.scope,
+                    "memory_key": args.key,
+                    "exception_type": type(error).__name__,
+                },
+            )
+        if not deleted:
+            return ToolResult.failure(
+                error=f"Memory not found: [{args.scope}] {args.key}",
+                metadata={
+                    **_safe_permission_metadata(decision),
+                    "memory_scope": args.scope,
+                    "memory_key": args.key,
+                },
+            )
+        return ToolResult.success(
+            content=f"Memory deleted: [{args.scope}] {args.key}",
+            metadata={
+                **_safe_permission_metadata(decision),
+                "memory_scope": args.scope,
+                "memory_key": args.key,
+                "memory_action": "deleted",
+            },
+        )
+
+    def _run(self, args: DeleteMemoryArgs) -> ToolResult:
+        return ToolResult.failure(
+            error="delete_memory must be run through ToolRegistry.run_tool().",
+            metadata={"memory_key": args.key, "reason": "permission_required"},
+        )
+
+
+def _safe_permission_metadata(decision: PermissionDecision) -> dict[str, object]:
+    return {
+        key: value
+        for key, value in decision.metadata.items()
+        if key != "memory_content"
+    }

mycode/tools/path_permissions.py

@@ -0,0 +1,78 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from mycode.permissions import PermissionDecision, PermissionRequest
+from mycode.tools.ignore import is_ignored_path, is_sensitive_path
+from mycode.tools.workspace import Workspace, WorkspacePathError
+
+
+@dataclass(frozen=True)
+class PathPermissionPolicy:
+    workspace: Workspace
+
+    def check_path(
+        self,
+        request: PermissionRequest,
+        path: str | Path,
+    ) -> PermissionDecision:
+        resolved_path = _resolve_candidate_path(self.workspace, path)
+        metadata = _build_metadata(
+            request=request,
+            path=path,
+            resolved_path=resolved_path,
+            workspace_root=self.workspace.root,
+        )
+
+        try:
+            self.workspace.resolve_path(path)
+        except WorkspacePathError:
+            return PermissionDecision.ask(
+                reason="outside_workspace",
+                message=f"Path outside workspace requires confirmation: {path}",
+                metadata={**metadata, "path_scope": "outside_workspace"},
+            )
+
+        if is_sensitive_path(resolved_path, self.workspace.root):
+            return PermissionDecision.ask(
+                reason="sensitive_path",
+                message=f"Sensitive path requires confirmation: {path}",
+                metadata={**metadata, "path_scope": "sensitive_path"},
+            )
+
+        if is_ignored_path(resolved_path, self.workspace.root):
+            return PermissionDecision.ask(
+                reason="ignored_path",
+                message=f"Ignored path requires confirmation: {path}",
+                metadata={**metadata, "path_scope": "ignored_path"},
+            )
+
+        return PermissionDecision.allow(
+            message=f"Path inside workspace allowed: {path}",
+            metadata={**metadata, "path_scope": "inside_workspace"},
+        )
+
+
+def _resolve_candidate_path(workspace: Workspace, path: str | Path) -> 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 _build_metadata(
+    *,
+    request: PermissionRequest,
+    path: str | Path,
+    resolved_path: Path,
+    workspace_root: Path,
+) -> dict[str, object]:
+    return {
+        "tool_name": request.tool_name,
+        "capability": request.capability,
+        "action": request.action,
+        "target": request.target,
+        "path": str(path),
+        "resolved_path": resolved_path.as_posix(),
+        "workspace_root": workspace_root.as_posix(),
+    }