iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/tools/registry.py

@@ -0,0 +1,242 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""ToolRegistry — dynamic tool management for profile-driven tool loading."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from chrys.service.tools.builtins.ask_user import ask_user
+from chrys.service.tools.builtins.filesystem import FilesystemTools
+from chrys.service.tools.builtins.search import SearchTools
+from chrys.service.tools.builtins.shell import ShellTools
+from chrys.service.tools.builtins.sleep import sleep
+from chrys.service.tools.builtins.todo import todo_write
+from chrys.service.vision import VIEW_IMAGE_TOOL_NAME
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from chrys.foundation.config.settings import Settings
+    from chrys.foundation.models.session_env import SessionEnvironment
+    from chrys.service.profiles.agents.schema import ShellFilterConfig
+    from chrys.service.tools.builtins.doc_converter import DocConverterTools
+    from chrys.service.tools.builtins.web.build import WebTools
+
+# Categories that use plain function tools (no runtime context needed).
+_STATIC_CATEGORIES: dict[str, list[Any]] = {
+    "ask_user": [ask_user],
+    "sleep": [sleep],
+    "todo": [todo_write],
+}
+
+# Categories that require SessionEnvironment and/or Settings and produce instance tools.
+_INSTANCE_CATEGORIES: set[str] = {
+    "filesystem.write",
+    "filesystem.read",
+    "search",
+    "shell",
+    "doc_converter",
+}
+
+# Categories whose tools the caller assembles beforehand (``assemble_web_tools``).
+_WEB_CATEGORIES: frozenset[str] = frozenset({"web_search", "web_fetch"})
+
+
+BUILTIN_TOOL_CATEGORIES: frozenset[str] = (
+    frozenset(_STATIC_CATEGORIES) | frozenset(_INSTANCE_CATEGORIES) | _WEB_CATEGORIES
+)
+"""Every category name a profile's ``tools.builtins`` can load."""
+
+
+class ToolRegistry:
+    """Central registry for all available tools.
+
+    Supports dynamic loading and unloading of tools as profiles are switched.
+    Tools can come from builtins, custom modules, or MCP servers.
+    """
+
+    def __init__(self, *, vision_enabled: bool = False) -> None:
+        self._tools: dict[str, Any] = {}
+        self._categories: dict[str, list[str]] = {}
+        self._vision_enabled = vision_enabled
+        self._doc_converters: list[DocConverterTools] = []
+
+    def register(self, tool: Any, *, name: str | None = None, category: str = "custom") -> None:
+        """Register a tool."""
+        tool_name = name or getattr(tool, "name", None) or getattr(tool, "__name__", str(tool))
+        if tool_name in _WEB_CATEGORIES and tool_name in self._tools:
+            # Approval rules match these names by kind, so a second tool must never replace one silently.
+            raise ValueError(f"A tool named {tool_name!r} is already registered")
+        self._tools[tool_name] = tool
+        self._categories.setdefault(category, []).append(tool_name)
+        self._refresh_doc_converter_image_capability()
+
+    def unregister(self, name: str) -> None:
+        """Remove a registered tool."""
+        self._tools.pop(name, None)
+        for names in self._categories.values():
+            if name in names:
+                names.remove(name)
+        self._refresh_doc_converter_image_capability()
+
+    def get(self, name: str) -> Any | None:
+        """Get a tool by name."""
+        return self._tools.get(name)
+
+    def get_all(self) -> list[Any]:
+        """Get all registered tools."""
+        return list(self._tools.values())
+
+    def get_by_category(self, category: str) -> list[Any]:
+        """Get all tools in a category."""
+        names = self._categories.get(category, [])
+        return [self._tools[n] for n in names if n in self._tools]
+
+    def load_builtins(
+        self,
+        categories: list[str],
+        runtime: SessionEnvironment | None = None,
+        settings: Settings | None = None,
+        shell_filter_config: ShellFilterConfig | None = None,
+        session_id: str | None = None,
+        session_dir: Path | None = None,
+        web: WebTools | None = None,
+    ) -> list[Any]:
+        """Load built-in tool categories by name.
+
+        Args:
+            categories: Category names like ["filesystem", "shell", "context", "search"]
+            runtime: SessionEnvironment for instance tools that need session-scoped state.
+            settings: Settings for instance tools that need configuration (e.g. context tools).
+            shell_filter_config: Optional shell command filter configuration from the profile.
+            session_id: Current session ID (used by instance tools that need session dir access).
+            session_dir: Current session directory, when already resolved by the caller.
+            web: The build's assembled web tools; without them the web categories load nothing.
+
+        Returns:
+            List of all loaded tool functions/instances.
+        """
+        # A category from a newer version (or a typo) loads nothing; the profile keeps it so
+        # saving never drops it.
+        unknown = [category for category in categories if category not in BUILTIN_TOOL_CATEGORIES]
+        if unknown:
+            logger.warning("Ignoring unknown built-in tool categories: %s", ", ".join(unknown))
+        effective: list[str] = []
+        for category in categories:
+            # A web tool's name must stay unique, so a repeated web category loads once.
+            if category in BUILTIN_TOOL_CATEGORIES and not (category in _WEB_CATEGORIES and category in effective):
+                effective.append(category)
+        loaded: list[Any] = []
+        for cat in effective:
+            if cat in _WEB_CATEGORIES:
+                tools = web.tools(cat) if web is not None else []
+            elif cat in _INSTANCE_CATEGORIES:
+                tools = self._create_instance_tools(
+                    cat,
+                    runtime,
+                    settings,
+                    shell_filter_config,
+                    session_id,
+                    session_dir,
+                )
+            else:
+                tools = _STATIC_CATEGORIES.get(cat, [])
+            for t in tools:
+                self.register(t, category=cat)
+                loaded.append(t)
+        return loaded
+
+    def _create_instance_tools(
+        self,
+        category: str,
+        runtime: SessionEnvironment | None,
+        settings: Settings | None = None,
+        shell_filter_config: ShellFilterConfig | None = None,
+        session_id: str | None = None,
+        session_dir: Path | None = None,
+    ) -> list[Any]:
+        """Create instance-based tools that need SessionEnvironment or Settings."""
+        if runtime is None:
+            from chrys.foundation.models.session_env import SessionEnvironment as RC
+
+            runtime = RC.capture()
+
+        if category == "shell":
+            command_filter = _build_shell_filter(shell_filter_config)
+            shell = ShellTools(runtime, command_filter=command_filter, session_dir=session_dir)
+            tools = shell.tools()
+            # Register additional shells (e.g. Git Bash on Windows)
+            for extra_shell in runtime.platform.extra_shells:
+                extra = ShellTools(
+                    runtime,
+                    command_filter=command_filter,
+                    shell=extra_shell,
+                    session_dir=session_dir,
+                )
+                tools.extend(extra.tools())
+            return tools
+
+        if category == "filesystem.write":
+            fs = FilesystemTools(runtime)
+            return [fs.write_file, fs.edit_file]
+
+        if category == "filesystem.read":
+            fs = FilesystemTools(runtime, session_dir=session_dir, session_id=session_id or "")
+            return [fs.read_file, fs.view_image]
+
+        if category == "search":
+            search = SearchTools(runtime, respect_gitignore=settings.search_respect_gitignore if settings else True)
+            return search.tools()
+
+        if category == "doc_converter":
+            from chrys.service.tools.builtins.doc_converter import DocConverterTools
+
+            dc = DocConverterTools(runtime, session_id=session_id or "", session_dir=session_dir)
+            self._doc_converters.append(dc)
+            return dc.tools()
+
+        return []
+
+    def clear(self) -> None:
+        """Remove all registered tools."""
+        for converter in self._doc_converters:
+            converter.set_image_extraction_enabled(False)
+        self._tools.clear()
+        self._categories.clear()
+        self._doc_converters.clear()
+
+    def _refresh_doc_converter_image_capability(self) -> None:
+        """Make converter image extraction match final registry capabilities."""
+        enabled = self._vision_enabled and self.get(VIEW_IMAGE_TOOL_NAME) is not None
+        for converter in self._doc_converters:
+            converter.set_image_extraction_enabled(enabled)
+
+
+def _build_shell_filter(config: ShellFilterConfig | None) -> Any:
+    """Build a :class:`ShellCommandFilter` from profile config, or ``None``."""
+    if config is None:
+        return None
+
+    from chrys.service.tools.builtins.shell_filter import ShellCommandFilter, get_preset
+
+    # Preset takes priority
+    if config.preset:
+        preset = get_preset(config.preset)
+        if preset is not None:
+            return preset
+
+    # Custom filter from explicit command list
+    if not config.commands:
+        return None
+
+    cmd_set = frozenset(config.commands)
+    return ShellCommandFilter(
+        whitelist=cmd_set if config.mode == "whitelist" else None,
+        blacklist=cmd_set if config.mode == "blacklist" else None,
+        allow_redirections=config.allow_redirections,
+        allow_subshells=config.allow_subshells,
+    )

chrys/service/tools/result_metadata.py

@@ -0,0 +1,103 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Runtime helpers for recording structured tool-result metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextvars import ContextVar
+
+from chrys.foundation.platform.files import surrogate_safe_text
+from chrys.foundation.tool_result_metadata import (
+    PROCESS_EXIT_CODE_METADATA_KEY,
+    PROCESS_TIMED_OUT_METADATA_KEY,
+    PROCESS_TIMEOUT_SECONDS_METADATA_KEY,
+    TOOL_ERROR_CODE_METADATA_KEY,
+    TOOL_ERROR_DETAILS_METADATA_KEY,
+    TOOL_ERROR_KIND_METADATA_KEY,
+    TOOL_ERROR_MESSAGE_METADATA_KEY,
+    TOOL_ERROR_RETRYABLE_METADATA_KEY,
+    TOOL_FAILED_METADATA_KEY,
+)
+from chrys.kernel._serialization import make_json_safe
+
+tool_result_metadata: ContextVar[dict[str, object] | None] = ContextVar("tool_result_metadata", default=None)
+"""Mutable metadata buffer set by tool event middleware for the active tool call."""
+
+
+def record_tool_failure(
+    kind: str,
+    message: str,
+    *,
+    code: str | int | None = None,
+    retryable: bool | None = None,
+    details: Mapping[str, object] | None = None,
+) -> None:
+    """Record structured metadata for a tool failure in the active tool context."""
+    metadata = tool_result_metadata.get(None)
+    if metadata is None:
+        return
+    metadata[TOOL_FAILED_METADATA_KEY] = True
+    metadata[TOOL_ERROR_KIND_METADATA_KEY] = kind
+    metadata[TOOL_ERROR_MESSAGE_METADATA_KEY] = _unprefixed_error(message)
+    if code is not None:
+        metadata[TOOL_ERROR_CODE_METADATA_KEY] = code
+    if retryable is not None:
+        metadata[TOOL_ERROR_RETRYABLE_METADATA_KEY] = retryable
+    if details is not None:
+        metadata[TOOL_ERROR_DETAILS_METADATA_KEY] = make_json_safe(details)
+
+
+def tool_error(
+    kind: str,
+    message: str,
+    *,
+    code: str | int | None = None,
+    retryable: bool | None = None,
+    details: Mapping[str, object] | None = None,
+) -> str:
+    """Return model-visible ``Error:`` text and record structured failure metadata."""
+    safe_message = surrogate_safe_text(message)
+    record_tool_failure(kind, safe_message, code=code, retryable=retryable, details=details)
+    if safe_message.startswith("Error:"):
+        return safe_message
+    return f"Error: {safe_message}"
+
+
+def record_tool_success() -> None:
+    """Record structured success metadata in the active tool context."""
+    metadata = tool_result_metadata.get(None)
+    if metadata is None or metadata.get(TOOL_FAILED_METADATA_KEY) is True:
+        return
+    metadata[TOOL_FAILED_METADATA_KEY] = False
+
+
+def record_process_result(exit_code: int) -> None:
+    """Record generic process completion metadata for the active tool context."""
+    metadata = tool_result_metadata.get(None)
+    if metadata is None:
+        return
+    metadata[PROCESS_EXIT_CODE_METADATA_KEY] = exit_code
+    if exit_code != 0:
+        metadata[TOOL_FAILED_METADATA_KEY] = True
+    elif metadata.get(TOOL_FAILED_METADATA_KEY) is not True:
+        metadata[TOOL_FAILED_METADATA_KEY] = False
+
+
+def record_process_timeout(timeout_seconds: int | float | None = None) -> None:
+    """Record generic process timeout metadata for the active tool context."""
+    metadata = tool_result_metadata.get(None)
+    if metadata is None:
+        return
+    metadata[PROCESS_TIMED_OUT_METADATA_KEY] = True
+    metadata[TOOL_FAILED_METADATA_KEY] = True
+    if timeout_seconds is not None:
+        metadata[PROCESS_TIMEOUT_SECONDS_METADATA_KEY] = make_json_safe(timeout_seconds)
+
+
+def _unprefixed_error(message: str) -> str:
+    if message.startswith("Error: "):
+        return message[len("Error: ") :]
+    if message.startswith("Error:"):
+        return message[len("Error:") :].lstrip()
+    return message

chrys/service/tools/session_artifacts.py

@@ -0,0 +1,196 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Strict-UTF-8 handles and shared roots for session-owned tool artifacts."""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Final
+
+from chrys.foundation.config.settings import resolve_sessions_dir
+from chrys.foundation.platform import get_platform
+from chrys.foundation.platform.files import (
+    atomic_write_owner_only_bytes,
+    secure_open_owner_verified_binary,
+    secure_open_regular_binary,
+)
+from chrys.foundation.util.session_ids import session_short_id
+
+_DOCUMENT_ARTIFACT_PREFIX: Final[str] = "chrys-session-document:"
+_MAX_FILENAME_BYTES: Final[int] = 1024
+_INVALID_FILENAME_CHARS: Final[frozenset[str]] = frozenset('<>:"/\\|?*')
+_DOCUMENT_MARKDOWN_SUFFIXES: Final[frozenset[str]] = frozenset({".md"})
+_DOCUMENT_IMAGE_SUFFIXES: Final[frozenset[str]] = frozenset({".png", ".jpg", ".jpeg", ".webp"})
+DOCUMENT_IMAGE_ARTIFACT_MAX_FILES: Final[int] = 8192
+DOCUMENT_IMAGE_ARTIFACT_MAX_FILE_BYTES: Final[int] = 50 * 1024 * 1024
+DOCUMENT_IMAGE_ARTIFACT_MAX_TOTAL_BYTES: Final[int] = 512 * 1024 * 1024
+
+
+class DocumentImageArtifactLimitError(OSError):
+    """Raised when a session's document-image artifact set exceeds its bounds."""
+
+
+def iter_document_image_artifacts(
+    artifact_root: Path,
+    *,
+    max_files: int = DOCUMENT_IMAGE_ARTIFACT_MAX_FILES,
+    max_file_bytes: int = DOCUMENT_IMAGE_ARTIFACT_MAX_FILE_BYTES,
+    max_total_bytes: int = DOCUMENT_IMAGE_ARTIFACT_MAX_TOTAL_BYTES,
+) -> Iterator[tuple[Path, int]]:
+    """Yield bounded regular image artifacts without materializing the directory."""
+    file_count = 0
+    total_bytes = 0
+    with os.scandir(artifact_root) as entries:
+        for entry in entries:
+            if os.path.splitext(entry.name)[1].lower() not in _DOCUMENT_IMAGE_SUFFIXES:
+                continue
+            file_count += 1
+            if file_count > max_files:
+                raise DocumentImageArtifactLimitError("session document-image file count exceeds its limit")
+            info = entry.stat(follow_symlinks=False)
+            if not stat.S_ISREG(info.st_mode):
+                raise OSError("session document-image artifact is not a regular file")
+            if info.st_size > max_file_bytes:
+                raise DocumentImageArtifactLimitError("session document-image artifact exceeds its file-size limit")
+            total_bytes += info.st_size
+            if total_bytes > max_total_bytes:
+                raise DocumentImageArtifactLimitError("session document-image artifacts exceed their byte limit")
+            yield Path(entry.path), info.st_size
+
+
+def _verified_document_artifact_root(session_dir: Path) -> Path | None:
+    """Return a session's link-free artifact root, or ``None`` when it has none."""
+    artifact_root = session_dir / "doc_converter"
+    try:
+        info = artifact_root.lstat()
+    except FileNotFoundError:
+        return None
+    if not stat.S_ISDIR(info.st_mode) or stat.S_ISLNK(info.st_mode) or os.path.isjunction(artifact_root):
+        raise OSError("session document-image artifact root is not a regular directory")
+    return artifact_root
+
+
+def reharden_document_image_artifacts(
+    source_session_dir: Path, destination_session_dir: Path, *, legacy_import: bool = False
+) -> None:
+    """Re-publish copied document images with a protected owner-only Windows DACL.
+
+    Sources are read owner-verified, as fork reads the user's own session.
+    ``legacy_import`` (session migration) reads them as the legacy reader
+    does instead: an older release running elevated owned its images by the
+    Administrators group, and the chosen legacy folder may sit behind a parent
+    alias such as a mapped drive.
+    """
+    if not get_platform().is_windows:
+        return
+
+    # Judge the source first: a junction there is dropped by the copy ignore,
+    # so checking the destination ahead of it would report the resulting
+    # absence instead of the redirected root that caused it.
+    source_root = _verified_document_artifact_root(source_session_dir)
+    if source_root is None:
+        return
+    destination_root = _verified_document_artifact_root(destination_session_dir)
+    if destination_root is None:
+        raise OSError("session document-image artifact root is missing from the copy")
+
+    read_source = secure_open_regular_binary if legacy_import else secure_open_owner_verified_binary
+    for destination_path, expected_size in list(iter_document_image_artifacts(destination_root)):
+        source_path = source_root / destination_path.name
+        with read_source(source_path) as source:
+            payload = source.read(DOCUMENT_IMAGE_ARTIFACT_MAX_FILE_BYTES + 1)
+        if len(payload) != expected_size:
+            raise OSError("session document-image artifact changed while being copied")
+        atomic_write_owner_only_bytes(destination_path, payload)
+
+
+def _validate_document_filename(
+    filename: str,
+    *,
+    allowed_suffixes: frozenset[str] = _DOCUMENT_MARKDOWN_SUFFIXES,
+) -> bytes:
+    """Return strict UTF-8 filename bytes or raise for an unsafe handle target."""
+    if not filename or filename in {".", ".."} or any(char in _INVALID_FILENAME_CHARS for char in filename):
+        raise ValueError("document artifact filename must be one path component")
+    suffix = os.path.splitext(filename)[1].lower()
+    if suffix not in allowed_suffixes:
+        allowed = ", ".join(sorted(allowed_suffixes))
+        raise ValueError(f"document artifact filename must use one of these suffixes: {allowed}")
+    if any(ord(char) < 0x20 or 0xD800 <= ord(char) <= 0xDFFF for char in filename):
+        raise ValueError("document artifact filename contains unsupported characters")
+    encoded = filename.encode("utf-8")
+    if len(encoded) > _MAX_FILENAME_BYTES:
+        raise ValueError("document artifact filename is too long")
+    return encoded
+
+
+def make_document_artifact_handle(filename: str) -> str:
+    """Return a readable UTF-8 handle scoped to the session document directory."""
+    _validate_document_filename(filename)
+    return _DOCUMENT_ARTIFACT_PREFIX + filename
+
+
+def make_document_image_artifact_handle(filename: str) -> str:
+    """Return a readable UTF-8 handle for a normalized document image."""
+    _validate_document_filename(filename, allowed_suffixes=_DOCUMENT_IMAGE_SUFFIXES)
+    return _DOCUMENT_ARTIFACT_PREFIX + filename
+
+
+def is_document_artifact_handle(reference: str) -> bool:
+    """Return whether *reference* uses the reserved document-handle namespace."""
+    return reference.startswith(_DOCUMENT_ARTIFACT_PREFIX)
+
+
+def resolve_tool_session_dir(
+    config_dir: Path,
+    *,
+    session_id: str = "",
+    session_dir: Path | None = None,
+) -> Path | None:
+    """Return the one session directory shared by artifact producers and readers."""
+    if session_dir is not None:
+        return session_dir
+    if not session_id:
+        return None
+    return resolve_sessions_dir(config_dir, create=False) / session_short_id(session_id)
+
+
+def resolve_document_markdown_artifact_handle(reference: str, session_dir: Path | None) -> str | None:
+    """Resolve a Markdown document artifact for ``read_file``."""
+    return _resolve_document_artifact_handle(reference, session_dir, allowed_suffixes=_DOCUMENT_MARKDOWN_SUFFIXES)
+
+
+def resolve_document_image_artifact_handle(reference: str, session_dir: Path | None) -> str | None:
+    """Resolve a normalized document image artifact for ``view_image``."""
+    return _resolve_document_artifact_handle(reference, session_dir, allowed_suffixes=_DOCUMENT_IMAGE_SUFFIXES)
+
+
+def _resolve_document_artifact_handle(
+    reference: str,
+    session_dir: Path | None,
+    *,
+    allowed_suffixes: frozenset[str],
+) -> str | None:
+    """Resolve one policy-scoped session artifact handle."""
+    if not is_document_artifact_handle(reference):
+        return None
+    if session_dir is None:
+        raise ValueError("document artifact handle is unavailable without a session directory")
+
+    filename = reference.removeprefix(_DOCUMENT_ARTIFACT_PREFIX)
+    _validate_document_filename(filename, allowed_suffixes=allowed_suffixes)
+
+    session_root = os.path.realpath(os.fspath(session_dir))
+    artifact_root = os.path.join(session_root, "doc_converter")
+    if os.path.normcase(os.path.realpath(artifact_root)) != os.path.normcase(artifact_root):
+        raise ValueError("session document directory must not be redirected")
+
+    resolved = os.path.join(artifact_root, filename)
+    if os.path.dirname(resolved) != artifact_root:
+        raise ValueError("document artifact handle resolves outside the session document directory")
+    if os.path.normcase(os.path.realpath(resolved)) != os.path.normcase(resolved):
+        raise ValueError("document artifact file must not be redirected")
+    return resolved