iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/platform/pty_output.py

@@ -0,0 +1,19 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Reading the master of a pseudo-terminal to the end of what its program wrote."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+class PtyOutputProtocol(asyncio.StreamReaderProtocol):
+    """Ends a pseudo-terminal's output the same way however its master does.
+
+    Linux reports the program's exit as an I/O error on the master, not as end of file, and a
+    `StreamReader` raises an error it was given ahead of handing over what it still holds: the
+    program's last words, whenever whoever reads was busy with the ones before.
+    """
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        super().connection_lost(None if isinstance(exc, OSError) else exc)

chrys/foundation/platform/runtime_paths.py

@@ -0,0 +1,281 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Runtime executable path helpers.
+
+PyApp-packaged Chrys runs from an embedded Python distribution.  On some
+platforms that distribution's executable directories appear early on PATH,
+causing child shells and subprocess tools to resolve ``python`` / ``uv`` to
+Chrys's private runtime instead of the user's system install.  These helpers
+demote those runtime directories only for packaged runs while preserving them
+as a fallback.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import sysconfig
+from collections.abc import Mapping, MutableMapping
+from pathlib import Path
+
+_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+_WINDOWS_DEFAULT_PATHEXT = (".COM", ".EXE", ".BAT", ".CMD")
+_PYTHON_HOME_OVERRIDE_KEYS = frozenset({"PYTHONHOME"})
+_PYTHON_RUNTIME_OVERRIDE_KEYS = frozenset({"PYTHONHOME", "PYTHONPATH"})
+
+
+def is_frozen_runtime(env: Mapping[str, str] | None = None) -> bool:
+    """Return whether this process is running from a packaged PyApp runtime."""
+    source = os.environ if env is None else env
+    forced = source.get("CHRYS_FORCE_FROZEN", "").strip().lower()
+    return forced in _TRUE_VALUES or bool(source.get("PYAPP"))
+
+
+def normalize_path(path: str | os.PathLike[str]) -> str:
+    """Return an absolute path for comparison/display, or ``""`` for empty inputs."""
+    raw = os.fspath(path)
+    if not raw:
+        return ""
+    return os.path.abspath(os.path.expanduser(raw))
+
+
+def same_path(left: str | os.PathLike[str], right: str | os.PathLike[str]) -> bool:
+    """Compare paths using platform normalization."""
+    left_norm = normalize_path(left)
+    right_norm = normalize_path(right)
+    if not left_norm or not right_norm:
+        return left_norm == right_norm
+    return os.path.normcase(os.path.realpath(left_norm)) == os.path.normcase(os.path.realpath(right_norm))
+
+
+def runtime_executable_dirs() -> tuple[str, ...]:
+    """Return executable/search directories associated with Chrys's Python runtime."""
+    dirs: list[str] = []
+
+    executable = normalize_path(sys.executable)
+    if executable:
+        _append_unique_path(dirs, str(Path(executable).parent))
+
+    for raw_prefix in (sys.prefix, sys.exec_prefix):
+        if raw_prefix:
+            _append_unique_path(dirs, raw_prefix)
+
+    scripts = sysconfig.get_path("scripts")
+    if scripts:
+        _append_unique_path(dirs, scripts)
+
+    script_dir_name = "Scripts" if sys.platform == "win32" else "bin"
+    for raw_prefix in (sys.prefix, sys.exec_prefix):
+        if raw_prefix:
+            _append_unique_path(dirs, str(Path(raw_prefix) / script_dir_name))
+            if sys.platform == "win32":
+                _append_unique_path(dirs, str(Path(raw_prefix) / "Library" / "bin"))
+
+    return tuple(dirs)
+
+
+def path_env_key(env: Mapping[str, str]) -> str | None:
+    """Return the actual PATH key casing present in *env*."""
+    if sys.platform == "win32":
+        # Plain dicts can contain both Path and PATH after merges; mirror
+        # Windows' effective last-writer-wins behavior for that degenerate case.
+        keys = _path_env_keys(env)
+        return keys[-1] if keys else None
+    if "PATH" in env:
+        return "PATH"
+    keys = _path_env_keys(env)
+    if keys:
+        return keys[0]
+    return None
+
+
+def strip_python_runtime_overrides(
+    env: MutableMapping[str, str],
+    *,
+    strip_pythonpath: bool = True,
+) -> MutableMapping[str, str]:
+    """Remove inherited Python runtime path overrides from a child environment.
+
+    This is intentionally not gated on :func:`is_frozen_runtime`: a normal
+    Chrys process may spawn a PyApp or standalone Python command whose CPython
+    bootstrap would otherwise honor the parent's ``PYTHONHOME`` / ``PYTHONPATH``
+    before the child application can defend itself.
+
+    ``strip_pythonpath=False`` keeps user module search paths for managed
+    commands that do not have their own explicit environment override.
+    """
+    blocked_keys = _PYTHON_RUNTIME_OVERRIDE_KEYS if strip_pythonpath else _PYTHON_HOME_OVERRIDE_KEYS
+    for key in list(env):
+        if key.upper() in blocked_keys:
+            del env[key]
+    return env
+
+
+def reorder_path_demoting_runtime(env: MutableMapping[str, str]) -> MutableMapping[str, str]:
+    """Move runtime PATH entries behind user/system entries for packaged runs.
+
+    The operation is a stable partition: non-runtime entries keep their
+    original relative order at the front; runtime entries keep their original
+    relative order at the back.  Duplicate entries are preserved.
+    """
+    if not is_frozen_runtime(env):
+        return env
+
+    key = path_env_key(env)
+    if key is None:
+        return env
+    _drop_duplicate_path_keys(env, keep=key)
+
+    entries = _path_entries(env[key])
+    if not entries:
+        env[key] = ""
+        return env
+
+    runtime_dirs = runtime_executable_dirs()
+    if not runtime_dirs:
+        return env
+
+    normal_entries: list[str] = []
+    runtime_entries: list[str] = []
+    for entry in entries:
+        if _is_runtime_dir(entry, runtime_dirs):
+            runtime_entries.append(entry)
+        else:
+            normal_entries.append(entry)
+
+    env[key] = os.pathsep.join([*normal_entries, *runtime_entries])
+    return env
+
+
+def which_excluding_runtime(
+    name: str,
+    *,
+    env: Mapping[str, str] | None = None,
+    frozen_only: bool = True,
+    fallback_to_runtime: bool = True,
+    exclude_paths: tuple[str, ...] = (),
+) -> str:
+    """Resolve *name* from PATH, preferring non-runtime directories.
+
+    By default the runtime-dir preference only activates for packaged PyApp
+    runs.  ``fallback_to_runtime`` keeps Chrys's embedded tools available when
+    the system does not provide the requested executable.
+    """
+    source = os.environ if env is None else env
+    key = path_env_key(source)
+    if key is None:
+        return normalize_path(shutil.which(name) or "") if env is None else ""
+
+    entries = _path_entries(source[key])
+    if not entries:
+        return ""
+
+    should_exclude = not frozen_only or is_frozen_runtime(source)
+    if not should_exclude:
+        return _which_on_path_entries(name, entries, env=source, exclude_paths=exclude_paths)
+
+    runtime_dirs = runtime_executable_dirs()
+    non_runtime_entries = [entry for entry in entries if not _is_runtime_dir(entry, runtime_dirs)]
+    found = _which_on_path_entries(name, non_runtime_entries, env=source, exclude_paths=exclude_paths)
+    if found or not fallback_to_runtime:
+        return found
+    return _which_on_path_entries(name, entries, env=source, exclude_paths=exclude_paths)
+
+
+def _append_unique_path(paths: list[str], new_path: str | os.PathLike[str]) -> None:
+    normalized = normalize_path(new_path)
+    if not normalized:
+        return
+    if any(same_path(normalized, existing) for existing in paths):
+        return
+    paths.append(normalized)
+
+
+def _path_entries(path_value: str) -> list[str]:
+    return [entry for entry in path_value.split(os.pathsep) if entry]
+
+
+def _path_env_keys(env: Mapping[str, str]) -> list[str]:
+    return [key for key in env if key.upper() == "PATH"]
+
+
+def _drop_duplicate_path_keys(env: MutableMapping[str, str], *, keep: str) -> None:
+    if sys.platform != "win32":
+        return
+    for key in list(env):
+        if key != keep and key.upper() == "PATH":
+            del env[key]
+
+
+def _is_runtime_dir(path: str, runtime_dirs: tuple[str, ...]) -> bool:
+    return any(same_path(path, runtime_dir) for runtime_dir in runtime_dirs)
+
+
+def _which_on_path_entries(
+    name: str,
+    entries: list[str],
+    *,
+    env: Mapping[str, str],
+    exclude_paths: tuple[str, ...],
+) -> str:
+    for raw_dir in entries:
+        directory = normalize_path(raw_dir)
+        if not directory:
+            continue
+        path = _which_in_directory(name, directory, env=env)
+        if not path:
+            continue
+        if any(same_path(path, excluded_path) for excluded_path in exclude_paths if excluded_path):
+            continue
+        return path
+    return ""
+
+
+def _which_in_directory(name: str, directory: str, *, env: Mapping[str, str]) -> str:
+    if sys.platform != "win32":
+        return normalize_path(shutil.which(name, path=directory) or "")
+
+    directory_entries = _windows_directory_entries(Path(directory))
+    for candidate_name in _windows_candidate_names(name, env):
+        path = directory_entries.get(candidate_name.casefold()) or normalize_path(Path(directory) / candidate_name)
+        if _access_check(path):
+            return path
+    return ""
+
+
+def _windows_directory_entries(directory: Path) -> dict[str, str]:
+    """Return child paths keyed case-insensitively, preserving on-disk casing."""
+    try:
+        return {child.name.casefold(): normalize_path(child) for child in directory.iterdir()}
+    except OSError:
+        return {}
+
+
+def _windows_candidate_names(name: str, env: Mapping[str, str]) -> tuple[str, ...]:
+    pathext = _windows_pathext(env)
+    suffix = Path(name).suffix
+    names: list[str] = []
+    if suffix and any(suffix.upper() == ext.upper() for ext in pathext):
+        names.append(name)
+    names.extend(f"{name}{ext}" for ext in pathext)
+    return tuple(dict.fromkeys(names))
+
+
+def _windows_pathext(env: Mapping[str, str]) -> tuple[str, ...]:
+    raw = _case_insensitive_env_value(env, "PATHEXT")
+    if raw is None:
+        return _WINDOWS_DEFAULT_PATHEXT
+    exts = tuple(ext.rstrip(".") for ext in raw.split(";") if ext)
+    return exts or _WINDOWS_DEFAULT_PATHEXT
+
+
+def _case_insensitive_env_value(env: Mapping[str, str], key: str) -> str | None:
+    for env_key, value in env.items():
+        if env_key.upper() == key.upper():
+            return value
+    return None
+
+
+def _access_check(path: str) -> bool:
+    return os.path.exists(path) and os.access(path, os.F_OK | os.X_OK) and not os.path.isdir(path)

chrys/foundation/platform/win_console.py

@@ -0,0 +1,129 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Windows console-mode preservation.
+
+When the chrys TUI spawns a child process on Windows (e.g. the agent
+runs ``uv run icode`` via PowerShell through ``ShellTools``), the child
+can mutate the mode flags of any console input/output handle it has
+access to.  Even after PR #146 (``CREATE_NEW_CONSOLE + SW_HIDE``), the
+child still inherits the parent's standard handles unless ``stdin`` /
+``stdout`` / ``stderr`` are explicitly redirected — so a grandchild TUI
+calling ``SetConsoleMode(GetStdHandle(STD_INPUT_HANDLE), …)`` can wipe
+``ENABLE_MOUSE_INPUT`` / ``ENABLE_WINDOW_INPUT`` on the outer TUI and
+leave mouse and keyboard events broken after it exits.
+
+:func:`preserve_console_mode` snapshots the outer console mode on entry
+and restores it on exit, protecting the TUI regardless of what the
+child (or its descendants) do.  On non-Windows platforms it is a
+no-op.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+from collections.abc import Iterator
+from typing import Any
+
+from chrys.foundation.platform.c_api import declare_functions
+
+_STD_INPUT_HANDLE = -10
+_STD_OUTPUT_HANDLE = -11
+
+
+def _load_kernel32() -> Any:
+    """Load ``kernel32.dll`` with correct argtypes / restype for 64-bit safety.
+
+    Without explicit ``restype`` on ``GetStdHandle``, ctypes defaults to
+    ``c_int`` and truncates the 64-bit ``HANDLE`` return value, silently
+    breaking ``GetConsoleMode`` / ``SetConsoleMode``.  Returns ``None`` on
+    non-Windows platforms or if the DLL cannot be loaded.
+    """
+    if sys.platform != "win32":
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        declare_functions(
+            kernel32,
+            {
+                "GetStdHandle": (wintypes.HANDLE, [wintypes.DWORD]),
+                "GetConsoleMode": (wintypes.BOOL, [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]),
+                "SetConsoleMode": (wintypes.BOOL, [wintypes.HANDLE, wintypes.DWORD]),
+            },
+        )
+        return kernel32
+    except OSError, AttributeError:
+        return None
+
+
+def _get_console_mode(handle_id: int) -> int | None:
+    """Return the current console mode for a standard handle, or ``None``.
+
+    ``None`` is returned if the handle is not a console (e.g. redirected
+    to a pipe or file), if the Windows API call fails, or if called on
+    a non-Windows platform.
+    """
+    kernel32 = _load_kernel32()
+    if kernel32 is None:
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        handle = kernel32.GetStdHandle(handle_id)
+        # ``INVALID_HANDLE_VALUE`` is (HANDLE)-1 — as an unsigned pointer
+        # on 64-bit that is ``0xFFFFFFFFFFFFFFFF``.  ``GetStdHandle`` can
+        # also return ``NULL`` when there is no associated standard
+        # handle (e.g. for a detached GUI process).
+        if not handle or handle == wintypes.HANDLE(-1).value:
+            return None
+        mode = wintypes.DWORD()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return None
+        return int(mode.value)
+    except OSError, AttributeError:
+        return None
+
+
+def _set_console_mode(handle_id: int, mode: int) -> None:
+    """Restore the console mode for a standard handle. Best-effort."""
+    kernel32 = _load_kernel32()
+    if kernel32 is None:
+        return
+    try:
+        from ctypes import wintypes
+
+        handle = kernel32.GetStdHandle(handle_id)
+        if not handle or handle == wintypes.HANDLE(-1).value:
+            return
+        kernel32.SetConsoleMode(handle, mode)
+    except OSError, AttributeError:
+        pass
+
+
+@contextlib.contextmanager
+def preserve_console_mode() -> Iterator[None]:
+    """Snapshot and restore Windows console mode around a block.
+
+    Wrap any subprocess that may spawn a Windows console TUI (shell tool,
+    skill-script runner) so the outer chrys TUI's mouse / keyboard mode
+    flags survive regardless of what the child does to them.
+
+    No-op on non-Windows platforms.
+    """
+    if sys.platform != "win32":
+        yield
+        return
+
+    saved_in = _get_console_mode(_STD_INPUT_HANDLE)
+    saved_out = _get_console_mode(_STD_OUTPUT_HANDLE)
+    try:
+        yield
+    finally:
+        if saved_in is not None:
+            _set_console_mode(_STD_INPUT_HANDLE, saved_in)
+        if saved_out is not None:
+            _set_console_mode(_STD_OUTPUT_HANDLE, saved_out)

chrys/foundation/reasoning_origin.py

@@ -0,0 +1,67 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The endpoint that issued a reasoning payload, so the payload replays only there.
+
+Anthropic thinking signatures and redacted thinking, Responses encrypted
+reasoning and Chat Completions ``reasoning_details`` are state only the
+endpoint that issued them can read back. A client stamps such reasoning with
+its protocol and the origin (scheme, host and port) of its base URL, and
+replays it only to a client of the same protocol and origin; the model does
+not count. Such reasoning without a stamp (received before stamps existed, or
+from a base URL with no origin) replays as it did before; a stamp on it that
+does not read as this version's never replays.
+
+Anthropic thinking text goes with its signature. Other plaintext reasoning is
+not gated: Chat Completions plaintext fields are never stamped, and a
+message's stamp gates only its ``reasoning_details``; a plaintext Responses
+dialect replays reasoning text whatever its stamp.
+
+An origin is a coarse identity: tenants behind one origin on different paths,
+another key or organization on the same URL, and a router that switches the
+service behind it all look alike.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from dataclasses import dataclass
+from typing import Any
+
+from chrys.foundation.errors.route import origin_of
+
+REASONING_ORIGIN_KEY = "_chrys_reasoning_origin"
+"""Content ``additional_properties`` key of the stamp; Chat Completions also sets it on the message."""
+
+_VERSION = 1
+
+
+@dataclass(frozen=True, slots=True)
+class ReasoningOrigin:
+    """The endpoint one client sends to."""
+
+    protocol: str
+    origin: str
+
+    @classmethod
+    def of(cls, protocol: str, base_url: object) -> ReasoningOrigin | None:
+        """The endpoint of a *protocol* client at *base_url*; None when the URL has no origin."""
+        found = origin_of(base_url)
+        if found is None:
+            return None
+        host = f"[{found.host}]" if ":" in found.host else found.host
+        return cls(protocol, f"{found.scheme}://{host}:{found.port}")
+
+    def stamp(self, properties: MutableMapping[str, Any]) -> None:
+        """Record this endpoint as the issuer of the reasoning *properties* belong to."""
+        properties[REASONING_ORIGIN_KEY] = self.stamp_value()
+
+    def stamp_value(self) -> dict[str, Any]:
+        """The stamp this endpoint writes, a fresh dict each time."""
+        return {"v": _VERSION, "protocol": self.protocol, "origin": self.origin}
+
+
+def replays_to(properties: Mapping[str, Any], endpoint: ReasoningOrigin | None) -> bool:
+    """Whether reasoning with *properties* may be sent to *endpoint* (None: an unknown one)."""
+    if REASONING_ORIGIN_KEY not in properties:
+        return True
+    return endpoint is not None and properties[REASONING_ORIGIN_KEY] == endpoint.stamp_value()

chrys/foundation/recovery.py

@@ -0,0 +1,16 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Typed outcomes for strict recovery-sidecar persistence."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class RecoveryPersistOutcome(Enum):
+    """Result of one strict recovery persistence request."""
+
+    PERSISTED = "persisted"
+    UNCONFIGURED = "unconfigured"
+    NOTHING_TO_PERSIST = "nothing_to_persist"
+    FAILED = "failed"