iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/util/lock.py

@@ -0,0 +1,236 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Cross-platform advisory file lock for serialising shared-file writes.
+
+When multiple chrys processes touch the same file under ``~/.chrys/`` (config,
+session metadata, mutation snapshots, etc.), wrapping the read-modify-write in
+a :class:`FileLock` against a sibling ``.lock`` file prevents lost updates and
+torn writes. The OS releases the lock automatically when the file descriptor
+closes (process exit, crash, or normal release), so stale lock files are not a
+concern.
+
+POSIX uses ``fcntl.flock`` (LOCK_EX, advisory). Windows uses ``msvcrt.locking``
+(LK_LOCK, mandatory on the locked byte range). Both are blocking by default;
+release happens on context exit or fd close.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import IO
+
+_IS_WINDOWS = sys.platform == "win32"
+
+if _IS_WINDOWS:
+    import msvcrt
+else:
+    import fcntl
+
+
+# In-process serializer keyed by lock-file path. Same-process threads queue
+# here before competing for the OS lock — without it, Windows' polled
+# ``msvcrt.locking(LK_NBLCK)`` can starve under thread contention because it
+# has no kernel-side fairness guarantee. ``threading.Lock`` is not strictly
+# FIFO but in practice serializes well enough to eliminate the starvation.
+# Across processes the OS lock still does the work; this layer only collapses
+# within-process noise.
+_PATH_LOCKS: dict[str, threading.Lock] = {}
+_PATH_LOCKS_GUARD = threading.Lock()
+
+
+def _get_path_lock(path: Path) -> threading.Lock:
+    # Normalize to an absolute lexical path so equivalent spellings
+    # (``foo.lock`` vs ``./foo.lock`` vs absolute) hash to the same key.
+    # ``absolute()`` is purely lexical (no stat/symlink resolution) so it
+    # stays cheap on the hot path. ``normcase`` collapses Windows
+    # case-insensitive variants (``C:\Foo`` vs ``c:\foo``); it's a no-op
+    # on POSIX.
+    key = os.path.normcase(str(path.absolute()))
+    with _PATH_LOCKS_GUARD:
+        lock = _PATH_LOCKS.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _PATH_LOCKS[key] = lock
+        return lock
+
+
+class FileLock:
+    """Context-managed exclusive lock on a sidecar ``.lock`` file.
+
+    The lock file is created if missing. Locking blocks until acquired (with an
+    optional timeout). Release happens on ``__exit__`` or fd close — the OS
+    cleans up if the process dies mid-critical-section.
+
+    Usage::
+
+        with FileLock(path):
+            # critical section — exclusive across processes
+            ...
+    """
+
+    # Time slice for non-blocking lock-retry polling (seconds).
+    _RETRY_INTERVAL = 0.05
+
+    def __init__(self, path: Path | str, timeout: float | None = None) -> None:
+        """Create a lock bound to ``path``.
+
+        Args:
+            path: Sidecar lock file path. Parent dir must exist (caller's job).
+            timeout: Max seconds to wait; ``None`` blocks indefinitely. Raises
+                ``TimeoutError`` if exceeded.
+        """
+        self._path = Path(path)
+        self._timeout = timeout
+        self._fp: IO[bytes] | None = None
+        self._proc_lock: threading.Lock | None = None
+
+    def __enter__(self) -> FileLock:
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()
+
+    def acquire(self) -> None:
+        """Acquire the lock, blocking until success or timeout."""
+        proc_lock = _get_path_lock(self._path)
+        deadline = None if self._timeout is None else time.monotonic() + self._timeout
+        # Block in-process threads here first so only one thread per process
+        # races for the OS lock. The OS-lock step gets whatever timeout is
+        # left after this wait.
+        if self._timeout is None:
+            proc_lock.acquire()
+        elif not proc_lock.acquire(timeout=self._timeout):
+            msg = f"Timed out acquiring lock {self._path}"
+            raise TimeoutError(msg)
+        try:
+            # Open in append+binary so the file is created if missing and content
+            # is never truncated. We never read or write the file — only lock it.
+            fp = self._open_lock_file()
+            try:
+                if deadline is None:
+                    self._lock_fd(fp)
+                else:
+                    # ``_lock_fd`` already tries once non-blocking before
+                    # checking the deadline, so a free OS lock succeeds
+                    # even when file-open ate the timeout budget. Clamp
+                    # to 0 so the inner loop raises on the first miss.
+                    remaining = deadline - time.monotonic()
+                    prior_timeout = self._timeout
+                    self._timeout = max(0.0, remaining)
+                    try:
+                        self._lock_fd(fp)
+                    finally:
+                        self._timeout = prior_timeout
+            except BaseException:
+                fp.close()
+                raise
+            self._fp = fp
+            self._proc_lock = proc_lock
+        except BaseException:
+            proc_lock.release()
+            raise
+
+    def _open_lock_file(self) -> IO[bytes]:
+        """Open the sidecar lock file, refusing anything but a regular file.
+
+        A same-uid but untrusted process (e.g. an ACP sub-agent) can pre-plant
+        a symlink or FIFO at the predictable ``.lock`` path. A plain
+        ``Path.open("ab")`` would follow the symlink, or — for a FIFO — *block
+        indefinitely inside open()*, before the acquire timeout (which only
+        guards the flock step) ever begins. When a lock is taken synchronously
+        on the event-loop thread that freezes the whole process. So on POSIX we
+        open with ``O_NOFOLLOW | O_NONBLOCK`` (reject a symlinked leaf, never
+        block on a FIFO) and then require ``S_ISREG`` via ``fstat`` (reject
+        FIFO/socket/device). We only advisory-lock the fd and never read or
+        write it, so the residual ``O_NONBLOCK`` is harmless.
+        """
+        flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_BINARY", 0)
+        if _IS_WINDOWS:
+            flags |= getattr(os, "O_NOINHERIT", 0)
+        else:
+            flags |= os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, "O_CLOEXEC", 0)
+        fd = os.open(self._path, flags, 0o600)
+        try:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                msg = f"Refusing to lock non-regular file {self._path}"
+                raise OSError(msg)
+        except BaseException:
+            os.close(fd)
+            raise
+        return os.fdopen(fd, "ab")
+
+    def release(self) -> None:
+        """Release the lock. Safe to call multiple times."""
+        fp = self._fp
+        proc_lock = self._proc_lock
+        if fp is None:
+            return
+        self._fp = None
+        self._proc_lock = None
+        try:
+            try:
+                self._unlock_fd(fp)
+            finally:
+                fp.close()
+        finally:
+            if proc_lock is not None:
+                proc_lock.release()
+
+    def _lock_fd(self, fp: IO[bytes]) -> None:
+        if _IS_WINDOWS:
+            self._lock_windows(fp)
+        else:
+            self._lock_posix(fp)
+
+    def _unlock_fd(self, fp: IO[bytes]) -> None:
+        if _IS_WINDOWS:
+            try:
+                fp.seek(0)
+                msvcrt.locking(fp.fileno(), msvcrt.LK_UNLCK, 1)
+            except OSError:
+                # If the lock was never granted or already gone, ignore.
+                pass
+        else:
+            fcntl.flock(fp.fileno(), fcntl.LOCK_UN)
+
+    def _lock_posix(self, fp: IO[bytes]) -> None:
+        if self._timeout is None:
+            fcntl.flock(fp.fileno(), fcntl.LOCK_EX)
+            return
+
+        deadline = time.monotonic() + self._timeout
+        while True:
+            try:
+                fcntl.flock(fp.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                return
+            except BlockingIOError:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    msg = f"Timed out acquiring lock {self._path}"
+                    raise TimeoutError(msg) from None
+                time.sleep(min(self._RETRY_INTERVAL, remaining))
+
+    def _lock_windows(self, fp: IO[bytes]) -> None:
+        # msvcrt locks a byte range; we lock byte 0. The file is opened in
+        # append mode so the position is at EOF — seek to 0 first.
+        fp.seek(0)
+        deadline = None if self._timeout is None else time.monotonic() + self._timeout
+        while True:
+            try:
+                msvcrt.locking(fp.fileno(), msvcrt.LK_NBLCK, 1)
+                return
+            except OSError:
+                if deadline is None:
+                    time.sleep(self._RETRY_INTERVAL)
+                    continue
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    msg = f"Timed out acquiring lock {self._path}"
+                    raise TimeoutError(msg) from None
+                time.sleep(min(self._RETRY_INTERVAL, remaining))

chrys/foundation/util/once_close.py

@@ -0,0 +1,46 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Cancel-safe, run-once close.
+
+A close runs as ONE task: the first caller creates it and every later caller
+awaits that same task. A waiter's cancellation never reaches the task, so the
+resource is released even when every caller gives up waiting.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+
+async def finish_close(task: asyncio.Task[None]) -> None:
+    """Drain an owned cleanup task even after repeated waiter cancellation."""
+    cancelled: asyncio.CancelledError | None = None
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError as exc:
+            cancelled = exc
+    task.result()
+    if cancelled is not None:
+        raise cancelled
+
+
+class OnceClose:
+    """Run *close* at most once; concurrent and later callers share its task."""
+
+    def __init__(self, close: Callable[[], Awaitable[None]]) -> None:
+        self._close = close
+        self._task: asyncio.Task[None] | None = None
+
+    @property
+    def started(self) -> bool:
+        return self._task is not None
+
+    async def _run(self) -> None:
+        await self._close()
+
+    async def __call__(self) -> None:
+        if self._task is None:
+            self._task = asyncio.create_task(self._run())
+        await finish_close(self._task)

chrys/foundation/util/session_ids.py

@@ -0,0 +1,29 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session identifier helpers shared across Chrys layers."""
+
+from __future__ import annotations
+
+# Number of hex characters used when projecting a full session UUID
+# down to a short identifier for display and on-disk folder names.
+# The canonical session id is the full ``uuid4().hex`` (32 chars);
+# ``session_id[:SESSION_SHORT_ID_LEN]`` is the user-facing / folder
+# form.  Pre-refactor sessions were themselves 12 hex chars — slicing
+# a legacy id by ``[:SESSION_SHORT_ID_LEN]`` returns the same string,
+# so the same code paths handle both.
+SESSION_SHORT_ID_LEN = 12
+
+
+def session_short_id(session_id: str) -> str:
+    """Return the short projection of *session_id* for display / folder.
+
+    The canonical session id is the RFC 4122 UUID string with dashes
+    (36 chars, e.g. ``"4201eebc-ca45-4328-8882-272f3d7c41cb"``).  The
+    short form strips dashes then truncates to
+    :data:`SESSION_SHORT_ID_LEN` hex chars — yielding a clean prefix of
+    the dashless form (e.g. ``"4201eebcca45"``).  Pre-refactor sessions
+    whose id was already 12 hex chars slice to themselves, so this
+    helper handles both shapes uniformly.
+    """
+    safe_id = session_id.replace("/", "_").replace("\\", "_").replace("-", "")
+    return safe_id[:SESSION_SHORT_ID_LEN]

chrys/foundation/util/shell_tokens.py

@@ -0,0 +1,88 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shell token splitting helpers shared by tools and mutation detection."""
+
+from __future__ import annotations
+
+
+def split_on_operators(command: str) -> list[str]:
+    """Split *command* on unquoted ``|``, ``&&``, ``||``, ``&``, ``;``, or newline operators.
+
+    Respects single and double quotes so that ``echo 'a|b'`` is not split.
+    """
+    segments: list[str] = []
+    current: list[str] = []
+    i = 0
+    in_single = False
+    in_double = False
+
+    while i < len(command):
+        ch = command[i]
+
+        # Backslash escape (not inside single quotes)
+        if ch == "\\" and not in_single and i + 1 < len(command):
+            current.append(ch)
+            current.append(command[i + 1])
+            i += 2
+            continue
+
+        # Quote tracking
+        if ch == "'" and not in_double:
+            in_single = not in_single
+            current.append(ch)
+            i += 1
+            continue
+        if ch == '"' and not in_single:
+            in_double = not in_double
+            current.append(ch)
+            i += 1
+            continue
+
+        # Operators (only outside quotes)
+        if not in_single and not in_double:
+            if ch == "|":
+                if i + 1 < len(command) and command[i + 1] == "|":
+                    # ||
+                    segments.append("".join(current))
+                    current = []
+                    i += 2
+                    continue
+                # |
+                segments.append("".join(current))
+                current = []
+                i += 1
+                continue
+            if ch == "&" and i + 1 < len(command) and command[i + 1] == "&":
+                # &&
+                segments.append("".join(current))
+                current = []
+                i += 2
+                continue
+            if ch == "&":
+                prev_ch = command[i - 1] if i > 0 else ""
+                next_ch = command[i + 1] if i + 1 < len(command) else ""
+                if prev_ch in "><" or next_ch == ">":
+                    current.append(ch)
+                    i += 1
+                    continue
+                segments.append("".join(current))
+                current = []
+                i += 1
+                continue
+            if ch in ";\r\n":
+                segments.append("".join(current))
+                current = []
+                i += 1
+                continue
+
+        current.append(ch)
+        i += 1
+
+    if current:
+        segments.append("".join(current))
+
+    return [s for s in segments if s.strip()]
+
+
+_split_on_operators = split_on_operators
+"""Backward-compatible alias for callers predating the public helper."""

chrys/foundation/util/sub_agent_context.py

@@ -0,0 +1,38 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Context variables shared between sub-agent event middleware and tools."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any
+
+SUB_AGENT_RESULT_COMMIT_CALLBACK_KEY = "_chrys_sub_agent_result_commit_callback"
+SUB_AGENT_TRANSCRIPT_FINAL_TEXT_METADATA_KEY = "sub_agent_transcript_final_text"
+
+# Carries the parent tool call id into the sub-agent tool body. Tool event
+# middleware sets it before invoking KIND_SUB_AGENT tools; the sub-agent tool
+# reads it when emitting InvocationStarted.
+sub_agent_parent_call_id: ContextVar[str] = ContextVar("sub_agent_parent_call_id", default="")
+
+
+@dataclass(slots=True)
+class SubAgentParentResultMetadata:
+    """Mutable parent-call metadata populated by sub-agent tool invocations."""
+
+    parent_provider_call_id: str = ""
+    parent_event_call_id: str = ""
+    sub_agent_invocation_id: str = ""
+    sub_agent_log_file: str = ""
+    sub_agent_audit_complete: bool = False
+    transcript_final_text: str | None = None
+    interrupted_result_committed: bool = False
+    commit_interrupted_result: Callable[[Mapping[str, Any]], None] | None = None
+
+
+sub_agent_parent_result_metadata: ContextVar[SubAgentParentResultMetadata | None] = ContextVar(
+    "sub_agent_parent_result_metadata",
+    default=None,
+)

chrys/foundation/util/time.py

@@ -0,0 +1,35 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Time helpers shared across Chrys."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+def parse_created_at(value: object) -> datetime | None:
+    """Parse Chrys timestamp metadata into a datetime, or None when invalid."""
+    if isinstance(value, datetime):
+        return value
+    if not isinstance(value, str):
+        return None
+    raw = value.strip()
+    if not raw:
+        return None
+    if raw.endswith(("Z", "z")):
+        raw = f"{raw[:-1]}+00:00"
+    try:
+        return datetime.fromisoformat(raw)
+    except ValueError:
+        return None
+
+
+def utc_iso(value: datetime | None = None) -> str:
+    """Return a canonical aware UTC ISO-8601 timestamp."""
+    if value is None:
+        value = datetime.now(UTC)
+    elif value.tzinfo is None or value.utcoffset() is None:
+        value = value.replace(tzinfo=UTC)
+    else:
+        value = value.astimezone(UTC)
+    return value.isoformat(timespec="microseconds")

chrys/foundation/util/unicode_scalars.py

@@ -0,0 +1,36 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Unpaired-surrogate detection and repair for text that must cross a JSON wire."""
+
+from __future__ import annotations
+
+
+def find_unpaired_surrogate(text: str) -> int:
+    """Return the index of the first unpaired surrogate in *text*, or ``-1``.
+
+    A high surrogate directly followed by a low surrogate counts as a pair
+    (JSON encoders emit and decoders re-join it); anything else in the
+    surrogate range is unpaired.
+    """
+    index = 0
+    length = len(text)
+    while index < length:
+        codepoint = ord(text[index])
+        if 0xD800 <= codepoint <= 0xDBFF:
+            if index + 1 >= length or not 0xDC00 <= ord(text[index + 1]) <= 0xDFFF:
+                return index
+            index += 2
+            continue
+        if 0xDC00 <= codepoint <= 0xDFFF:
+            return index
+        index += 1
+    return -1
+
+
+def replace_unpaired_surrogates(text: str) -> str:
+    """Join surrogate pairs into their scalar and replace lone ones with U+FFFD."""
+    try:
+        text.encode("utf-8")
+    except UnicodeEncodeError:
+        return text.encode("utf-16", "surrogatepass").decode("utf-16", "replace")
+    return text

chrys/foundation/vendor/__init__.py

@@ -0,0 +1,43 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Vendored third-party binaries bundled at build time."""
+
+from __future__ import annotations
+
+import platform as _platform
+import shutil
+from pathlib import Path
+
+VENDOR_RIPGREP = Path(__file__).resolve().parent / "ripgrep"
+
+# Platform triple → rg binary filename inside foundation/vendor/ripgrep/.
+# Multi-platform builds (--all) use suffixed names; local builds use plain "rg"/"rg.exe".
+_TRIPLE_MAP: dict[tuple[str, str], tuple[str, str]] = {
+    # (system, machine) → (triple-suffixed name, generic name)
+    ("Darwin", "arm64"): ("rg-aarch64-apple-darwin", "rg"),
+    ("Darwin", "x86_64"): ("rg-x86_64-apple-darwin", "rg"),
+    ("Linux", "x86_64"): ("rg-x86_64-unknown-linux-musl", "rg"),
+    ("Linux", "aarch64"): ("rg-aarch64-unknown-linux-gnu", "rg"),
+    ("Windows", "AMD64"): ("rg-x86_64-pc-windows-msvc.exe", "rg.exe"),
+    ("Windows", "ARM64"): ("rg-aarch64-pc-windows-msvc.exe", "rg.exe"),
+}
+
+
+def find_rg() -> str | None:
+    """Locate the bundled ``rg`` binary, or return *None* if not found.
+
+    Checks the platform-specific name first (CD multi-platform wheel), then
+    the generic name (local single-platform build), then ``PATH``.
+    """
+    key = (_platform.system(), _platform.machine())
+    names = _TRIPLE_MAP.get(key)
+    if names:
+        for name in names:
+            candidate = VENDOR_RIPGREP / name
+            if candidate.is_file():
+                return str(candidate)
+    # Fallback: system PATH
+    which = shutil.which("rg")
+    if which:
+        return which
+    return None