iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/observability/sink.py

@@ -0,0 +1,228 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session-state holder for the OpenTelemetry pipeline.
+
+Kept deliberately free of ``opentelemetry`` imports so the engine can
+import :func:`get_otel_sink` without requiring the SDK to be installed.
+The SDK-dependent pieces (``SpanExporter`` / ``LogRecordExporter`` /
+``SpanProcessor``) live in :mod:`chrys.foundation.observability.exporters` and
+are only loaded from :func:`chrys.foundation.observability.setup.setup_otel` when the
+user has enabled OTel and the SDK is available.
+
+The sink holds:
+
+* the active chrys session_id (read by the span processor to stamp
+  ``chrys.session_id`` and ``gen_ai.conversation.id`` on every span),
+* the file paths JSONL exporters should write to,
+* thread-safe bounded buffers that hold spans/logs emitted before a
+  session is active, or before the lazily-created session directory has
+  been materialized by the first real session writer.
+
+:meth:`activate` is called by :class:`chrys.orchestration.engine.engine.AgentEngine`
+once a session id is active; :meth:`deactivate` is called on
+session delete.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_MAX_BUFFERED_LINES = 1000
+
+
+class OtelSessionSink:
+    """Per-process state bridge between OTel exporters and the chrys session.
+
+    ``write_files`` picks the exporter strategy:
+
+    * ``True`` — Chrys installs JSONL span + log exporters that write
+      to ``{session_dir}/otel/`` once :meth:`activate` is called.  Used
+      when no ``OTEL_EXPORTER_OTLP_ENDPOINT`` is configured.
+    * ``False`` — Span/log data ships via OTLP exporters that ``setup_otel``
+      builds from standard OTel env vars. The sink still tracks the
+      session_id so the span processor can stamp attributes.
+    """
+
+    def __init__(self, *, write_files: bool) -> None:
+        self._session_id: str | None = None
+        self._write_files = write_files
+        self._span_path: Path | None = None
+        self._log_path: Path | None = None
+        self._span_buffer: list[str] = []
+        self._log_buffer: list[str] = []
+        self._file_write_failed = False
+        self._lock = threading.Lock()
+
+    # --- Session state ---------------------------------------------------
+
+    @property
+    def session_id(self) -> str | None:
+        with self._lock:
+            return self._session_id
+
+    @property
+    def write_files(self) -> bool:
+        return self._write_files
+
+    def activate(self, session_id: str, session_dir: Path | None) -> None:
+        """Bind a session.  Flushes any buffered span/log lines to disk."""
+        with self._lock:
+            if self._session_id is not None and self._session_id != session_id:
+                self._span_buffer.clear()
+                self._log_buffer.clear()
+            self._session_id = session_id
+            self._file_write_failed = False
+            self._span_path = None
+            self._log_path = None
+            if not self._write_files:
+                self._span_buffer.clear()
+                self._log_buffer.clear()
+                return
+            if session_dir is None:
+                self._file_write_failed = True
+                self._span_buffer.clear()
+                self._log_buffer.clear()
+                return
+        try:
+            otel_dir = session_dir / "otel"
+            with self._lock:
+                self._span_path = otel_dir / "traces.jsonl"
+                self._log_path = otel_dir / "logs.jsonl"
+                if self._span_buffer:
+                    self._write_or_buffer_unlocked(self._span_path, self._span_buffer, [])
+                if self._log_buffer:
+                    self._write_or_buffer_unlocked(self._log_path, self._log_buffer, [])
+        except OSError:
+            logger.warning("Failed to activate OTel session file sink in %s", session_dir, exc_info=True)
+            with self._lock:
+                self._file_write_failed = True
+                self._span_path = None
+                self._log_path = None
+                self._span_buffer.clear()
+                self._log_buffer.clear()
+
+    def deactivate(self) -> None:
+        with self._lock:
+            self._session_id = None
+            self._span_path = None
+            self._log_path = None
+            self._file_write_failed = True
+            self._span_buffer.clear()
+            self._log_buffer.clear()
+
+    def flush_pending(self, session_id: str) -> None:
+        """Retry buffered file writes after the session root is materialized."""
+        with self._lock:
+            if not self._write_files:
+                return
+            if self._file_write_failed:
+                return
+            if self._session_id != session_id:
+                return
+            try:
+                if self._span_path is not None and self._span_buffer:
+                    self._write_or_buffer_unlocked(self._span_path, self._span_buffer, [])
+                if self._log_path is not None and self._log_buffer:
+                    self._write_or_buffer_unlocked(self._log_path, self._log_buffer, [])
+            except OSError:
+                logger.warning("Failed to flush buffered OTel file lines for session %s", session_id, exc_info=True)
+                self._file_write_failed = True
+                self._span_path = None
+                self._log_path = None
+                self._span_buffer.clear()
+                self._log_buffer.clear()
+
+    # --- Exporter write paths --------------------------------------------
+
+    def write_spans(self, lines: list[str]) -> None:
+        """Append pre-serialized JSONL lines to the span file (buffer if unset)."""
+        if not lines:
+            return
+        with self._lock:
+            if not self._write_files:
+                return
+            if self._file_write_failed:
+                return
+            if self._span_path is None:
+                self._buffer_lines_unlocked(self._span_buffer, lines)
+            else:
+                try:
+                    self._write_or_buffer_unlocked(self._span_path, self._span_buffer, lines)
+                except OSError:
+                    logger.warning("Failed to write OTel span file %s", self._span_path, exc_info=True)
+                    self._file_write_failed = True
+                    self._span_path = None
+                    self._log_path = None
+                    self._span_buffer.clear()
+                    self._log_buffer.clear()
+
+    def write_logs(self, lines: list[str]) -> None:
+        """Append pre-serialized JSONL lines to the log file (buffer if unset)."""
+        if not lines:
+            return
+        with self._lock:
+            if not self._write_files:
+                return
+            if self._file_write_failed:
+                return
+            if self._log_path is None:
+                self._buffer_lines_unlocked(self._log_buffer, lines)
+            else:
+                try:
+                    self._write_or_buffer_unlocked(self._log_path, self._log_buffer, lines)
+                except OSError:
+                    logger.warning("Failed to write OTel log file %s", self._log_path, exc_info=True)
+                    self._file_write_failed = True
+                    self._span_path = None
+                    self._log_path = None
+                    self._span_buffer.clear()
+                    self._log_buffer.clear()
+
+    def _write_or_buffer_unlocked(self, path: Path, buffer: list[str], lines: list[str]) -> None:
+        pending = [*buffer, *lines] if buffer else list(lines)
+        if not pending:
+            return
+        if self._append_lines_unlocked(path, pending):
+            buffer.clear()
+            return
+        buffer.clear()
+        self._buffer_lines_unlocked(buffer, pending)
+
+    @staticmethod
+    def _buffer_lines_unlocked(buffer: list[str], lines: list[str]) -> None:
+        if not lines:
+            return
+        buffer.extend(lines)
+        overflow = len(buffer) - _MAX_BUFFERED_LINES
+        if overflow > 0:
+            del buffer[:overflow]
+
+    @staticmethod
+    def _append_lines_unlocked(path: Path, lines: list[str]) -> bool:
+        try:
+            path.parent.mkdir(exist_ok=True)
+            with path.open("a", encoding="utf-8") as f:
+                f.writelines(lines)
+            return True
+        except FileNotFoundError:
+            return False
+
+
+# --- Module singleton ---------------------------------------------------------
+
+_SINK: OtelSessionSink | None = None
+
+
+def set_otel_sink(sink: OtelSessionSink | None) -> None:
+    """Install the process-wide sink.  Called by :func:`setup_otel`."""
+    global _SINK
+    _SINK = sink
+
+
+def get_otel_sink() -> OtelSessionSink | None:
+    """Return the installed sink, or ``None`` if OTel is disabled."""
+    return _SINK

chrys/foundation/patches/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Patches for third-party dependencies.
+
+This module provides a mechanism to apply targeted patches to installed
+site-packages when upstream libraries lack required features. Each patch
+is defined as a pair of code fragments (original → patched). The patcher
+validates the source file before applying:
+
+- If it matches the original → apply the patch
+- If it already matches the patched version → skip (idempotent)
+- If it matches neither → raise an error (upstream changed, patch needs update)
+
+Call ``apply_all()`` at startup before the patched code is imported.
+"""
+
+from chrys.foundation.patches.patcher import apply_all
+
+__all__ = ["apply_all"]

chrys/foundation/patches/mdurl_cache.py

@@ -0,0 +1,59 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Publish mdurl's lookup tables only once they are complete.
+
+mdurl 0.1.2 builds each percent-encoding table lazily and stores the empty list
+in its module-level cache before filling it. Markdown blocks are built in
+executor threads, so a second thread normalizing a link at the same moment can
+take the half-filled list and index past its end (``IndexError`` from
+``encode``) or decode with a table that is missing entries. Build each table
+first and publish it with one ``setdefault``, so every thread either builds its
+own copy or reads a finished one.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+_RUNTIME_PATCH_MDURL_VERSION = "0.1.2"
+_RUNTIME_PATCH_MARKER = "_chrys_publishes_complete_tables"
+logger = logging.getLogger(__name__)
+
+
+def apply_runtime_patch() -> None:
+    """Replace the two table builders of the pinned mdurl."""
+    try:
+        import mdurl
+        from mdurl import _decode, _encode
+    except ImportError:
+        return
+    if mdurl.__version__ != _RUNTIME_PATCH_MDURL_VERSION:
+        logger.warning("Skipping mdurl cache patch for unsupported mdurl %s", mdurl.__version__)
+        return
+    if getattr(_encode.get_encode_cache, _RUNTIME_PATCH_MARKER, False):
+        return
+
+    # The tables mdurl 0.1.2 builds; encode() and decode() look the builders up at call time.
+    def get_encode_cache(exclude: str) -> Sequence[str]:
+        cache = _encode.encode_cache.get(exclude)
+        if cache is None:
+            table = [chr(i) if chr(i) in _encode.ASCII_LETTERS_AND_DIGITS else f"%{i:02X}" for i in range(128)]
+            for ch in exclude:
+                table[ord(ch)] = ch
+            cache = _encode.encode_cache.setdefault(exclude, table)
+        return cache
+
+    def get_decode_cache(exclude: str) -> Sequence[str]:
+        cache = _decode.decode_cache.get(exclude)
+        if cache is None:
+            table = [chr(i) for i in range(128)]
+            for ch in exclude:
+                table[ord(ch)] = f"%{ord(ch):02X}"
+            cache = _decode.decode_cache.setdefault(exclude, table)
+        return cache
+
+    setattr(get_encode_cache, _RUNTIME_PATCH_MARKER, True)
+    setattr(get_decode_cache, _RUNTIME_PATCH_MARKER, True)
+    _encode.get_encode_cache = get_encode_cache
+    _decode.get_decode_cache = get_decode_cache

chrys/foundation/patches/patcher.py

@@ -0,0 +1,287 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Generic site-packages patcher.
+
+Patches are defined as ``FilePatch`` objects — each specifies a package,
+a module-relative file path, and an (old_fragment, new_fragment) pair.
+The patcher locates the installed file, checks its content, and applies
+or skips as appropriate.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import logging
+import os
+import stat
+import tempfile
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class FilePatch:
+    """A single find-and-replace patch for an installed package file."""
+
+    package: str
+    """Top-level package name (e.g. ``some_package``)."""
+
+    module_file: str
+    """File path relative to the package root (e.g. ``_tools.py``)."""
+
+    old_fragment: str
+    """Exact code fragment expected in the original (unpatched) file."""
+
+    new_fragment: str
+    """Replacement code fragment."""
+
+    description: str = ""
+    """Human-readable description of what this patch does."""
+
+    equivalent_fragments: tuple[str, ...] = ()
+    """Already-patched fragments that are behaviorally equivalent to ``new_fragment``."""
+
+
+@dataclass
+class PatchResult:
+    """Outcome of attempting to apply a single patch."""
+
+    patch: FilePatch
+    status: str  # "applied", "skipped", "error"
+    detail: str = ""
+
+
+# Module-level registry so patch definitions can self-register.
+_patches: list[FilePatch] = []
+
+
+def register(*patches: FilePatch) -> None:
+    """Register one or more patches."""
+    _patches.extend(patches)
+
+
+def _locate_package_dir(package: str) -> Path:
+    """Return the directory of an installed package."""
+    spec = importlib.util.find_spec(package)
+    if spec is None or spec.origin is None:
+        raise ImportError(f"Package {package!r} is not installed.")
+    return Path(spec.origin).parent
+
+
+def _atomic_write_text(path: Path, payload: str) -> None:
+    """Atomically write text to an installed patch target.
+
+    Writes via a binary file descriptor on the same filesystem so
+    ``os.replace`` is genuinely atomic on POSIX and Windows.  Binary
+    mode avoids ``\\r\\n`` translation under Windows and lets
+    ``os.fsync`` accept the file descriptor uniformly.  The original
+    file's mode bits are preserved so a stricter umask on the temp
+    file doesn't leave the patched module unreadable.
+    """
+    target_mode = stat.S_IMODE(path.stat().st_mode)
+    fd, tmp_name = tempfile.mkstemp(prefix=f"{path.name}.", suffix=".tmp", dir=path.parent)
+    tmp_path = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(payload.encode("utf-8"))
+            f.flush()
+            os.fsync(f.fileno())
+        os.chmod(tmp_path, target_mode)
+        os.replace(tmp_path, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            tmp_path.unlink()
+        raise
+
+
+def _patch_target(patch: FilePatch) -> Path:
+    """Resolve the installed file targeted by a patch."""
+    return _locate_package_dir(patch.package) / patch.module_file
+
+
+def _missing_fragment_detail(patch: FilePatch, target: Path) -> str:
+    return (
+        f"Source file does not contain the expected original fragment.\n"
+        f"The upstream package may have been updated — please review and "
+        f"update the patch.\n"
+        f"File: {target}"
+    )
+
+
+def apply_patch(patch: FilePatch) -> PatchResult:
+    """Apply a single patch, returning the result."""
+    try:
+        target = _patch_target(patch)
+    except ImportError as exc:
+        # A package that is not installed has nothing to patch. Every
+        # entrypoint runs apply_all(), so "error" would log a warning per
+        # patch on every invocation. A missing file inside an INSTALLED
+        # package stays an error below — that one really is broken.
+        return PatchResult(patch, "skipped", str(exc))
+
+    if not target.is_file():
+        return PatchResult(patch, "error", f"File not found: {target}")
+
+    source = target.read_text(encoding="utf-8")
+
+    if patch.new_fragment in source or any(fragment in source for fragment in patch.equivalent_fragments):
+        return PatchResult(patch, "skipped", "Already patched.")
+
+    if patch.old_fragment not in source:
+        return PatchResult(patch, "error", _missing_fragment_detail(patch, target))
+
+    patched = source.replace(patch.old_fragment, patch.new_fragment, 1)
+    _atomic_write_text(target, patched)
+    return PatchResult(patch, "applied", f"Patched {target}")
+
+
+def apply_patch_group(patches: list[FilePatch]) -> list[PatchResult]:
+    """Apply same-file patches all-or-nothing.
+
+    The patcher often registers several fragments against one upstream
+    module.  Staging them as a group prevents a package upgrade from
+    leaving that module half-mutated if one later fragment no longer
+    matches.
+    """
+    if not patches:
+        return []
+
+    first = patches[0]
+    if any((patch.package, patch.module_file) != (first.package, first.module_file) for patch in patches):
+        return [PatchResult(patch, "error", "Patch group contains multiple target files.") for patch in patches]
+
+    try:
+        target = _patch_target(first)
+    except ImportError as exc:
+        # A package that is not installed has nothing to patch — see apply_patch.
+        return [PatchResult(patch, "skipped", str(exc)) for patch in patches]
+
+    if not target.is_file():
+        return [PatchResult(patch, "error", f"File not found: {target}") for patch in patches]
+
+    source = target.read_text(encoding="utf-8")
+    staged_source = source
+    staged_results: list[PatchResult] = []
+
+    for index, patch in enumerate(patches):
+        if patch.new_fragment in staged_source or any(
+            fragment in staged_source for fragment in patch.equivalent_fragments
+        ):
+            staged_results.append(PatchResult(patch, "skipped", "Already patched."))
+            continue
+        if patch.old_fragment not in staged_source:
+            detail = _missing_fragment_detail(patch, target)
+            aborted_detail = f"Patch group aborted before writing because another fragment failed.\n{detail}"
+            return (
+                [
+                    result if result.status == "skipped" else PatchResult(result.patch, "error", aborted_detail)
+                    for result in staged_results
+                ]
+                + [PatchResult(patch, "error", detail)]
+                + [
+                    PatchResult(remaining, "error", "Patch group aborted before this fragment was checked.")
+                    for remaining in patches[index + 1 :]
+                ]
+            )
+        staged_source = staged_source.replace(patch.old_fragment, patch.new_fragment, 1)
+        staged_results.append(PatchResult(patch, "applied", f"Patched {target}"))
+
+    if staged_source != source:
+        _atomic_write_text(target, staged_source)
+    return staged_results
+
+
+def _apply_runtime_patches(runtime_patches: tuple[tuple[str, Callable[[], None]], ...]) -> None:
+    """Apply independent in-process patches without making startup all-or-nothing."""
+    for name, apply_runtime_patch in runtime_patches:
+        try:
+            apply_runtime_patch()
+        except Exception as exc:
+            logger.warning("Runtime patch error: %s — %s", name, exc, exc_info=True)
+
+
+def apply_all() -> list[PatchResult]:
+    """Apply all registered patches. Returns results for each."""
+    # Import patch definition modules so they call ``register()``.
+    import chrys.foundation.patches.mdurl_cache as mdurl_cache
+    import chrys.foundation.patches.textual_block_border as textual_block_border
+    import chrys.foundation.patches.textual_button_ansi as textual_button_ansi
+    import chrys.foundation.patches.textual_callback_cache as textual_callback_cache
+    import chrys.foundation.patches.textual_callback_dispatch as textual_callback_dispatch
+    import chrys.foundation.patches.textual_compositor_cjk as textual_compositor_cjk
+    import chrys.foundation.patches.textual_dispatch_cache as textual_dispatch_cache
+    import chrys.foundation.patches.textual_ime_cursor_anchor as textual_ime_cursor_anchor
+    import chrys.foundation.patches.textual_kitty_keyboard as textual_kitty_keyboard
+    import chrys.foundation.patches.textual_lru_acyclic as textual_lru_acyclic
+    import chrys.foundation.patches.textual_message_pump as textual_message_pump
+    import chrys.foundation.patches.textual_node_diet as textual_node_diet
+    import chrys.foundation.patches.textual_one_shot_timer as textual_one_shot_timer
+    import chrys.foundation.patches.textual_option_list as textual_option_list
+    import chrys.foundation.patches.textual_precompose as textual_precompose
+    import chrys.foundation.patches.textual_pruned_tabs as textual_pruned_tabs
+    import chrys.foundation.patches.textual_reflow_reuse as textual_reflow_reuse
+    import chrys.foundation.patches.textual_removed_node_caches as textual_removed_node_caches
+    import chrys.foundation.patches.textual_removed_screen_callbacks as textual_removed_screen_callbacks
+    import chrys.foundation.patches.textual_selection_extract as textual_selection_extract
+    import chrys.foundation.patches.textual_strip_cycles as textual_strip_cycles
+    import chrys.foundation.patches.textual_tab_selection as textual_tab_selection
+    import chrys.foundation.patches.textual_timer_skip as textual_timer_skip
+    import chrys.foundation.patches.textual_utf8_decoder as textual_utf8_decoder
+    import chrys.foundation.patches.textual_win_sleep as textual_win_sleep
+    import chrys.foundation.patches.watchdog_fsevents as watchdog_fsevents
+    import chrys.foundation.patches.watchdog_windows as watchdog_windows
+
+    grouped: dict[tuple[str, str], list[FilePatch]] = defaultdict(list)
+    for patch in _patches:
+        grouped[(patch.package, patch.module_file)].append(patch)
+
+    results: list[PatchResult] = []
+    for patches in grouped.values():
+        group_results = apply_patch_group(patches)
+        for result in group_results:
+            patch = result.patch
+            if result.status == "applied":
+                logger.info("Patch applied: %s — %s", patch.description, result.detail)
+            elif result.status == "skipped":
+                logger.debug("Patch skipped: %s — %s", patch.description, result.detail)
+            else:
+                logger.warning("Patch error: %s — %s", patch.description, result.detail)
+        results.extend(group_results)
+
+    _apply_runtime_patches(
+        (
+            ("mdurl_cache", mdurl_cache.apply_runtime_patch),
+            ("watchdog_windows", watchdog_windows.apply_runtime_patch),
+            ("watchdog_fsevents", watchdog_fsevents.apply_runtime_patch),
+            ("textual_win_sleep", textual_win_sleep.apply_runtime_patch),
+            ("textual_block_border", textual_block_border.apply_runtime_patch),
+            ("textual_button_ansi", textual_button_ansi.apply_runtime_patch),
+            ("textual_callback_cache", textual_callback_cache.apply_runtime_patch),
+            ("textual_callback_dispatch", textual_callback_dispatch.apply_runtime_patch),
+            ("textual_compositor_cjk", textual_compositor_cjk.apply_runtime_patch),
+            ("textual_message_pump", textual_message_pump.apply_runtime_patch),
+            ("textual_dispatch_cache", textual_dispatch_cache.apply_runtime_patch),
+            ("textual_one_shot_timer", textual_one_shot_timer.apply_runtime_patch),
+            ("textual_timer_skip", textual_timer_skip.apply_runtime_patch),
+            ("textual_reflow_reuse", textual_reflow_reuse.apply_runtime_patch),
+            ("textual_strip_cycles", textual_strip_cycles.apply_runtime_patch),
+            ("textual_lru_acyclic", textual_lru_acyclic.apply_runtime_patch),
+            ("textual_node_diet", textual_node_diet.apply_runtime_patch),
+            ("textual_option_list", textual_option_list.apply_runtime_patch),
+            ("textual_precompose", textual_precompose.apply_runtime_patch),
+            ("textual_pruned_tabs", textual_pruned_tabs.apply_runtime_patch),
+            ("textual_removed_node_caches", textual_removed_node_caches.apply_runtime_patch),
+            ("textual_removed_screen_callbacks", textual_removed_screen_callbacks.apply_runtime_patch),
+            ("textual_selection_extract", textual_selection_extract.apply_runtime_patch),
+            ("textual_tab_selection", textual_tab_selection.apply_runtime_patch),
+            ("textual_ime_cursor_anchor", textual_ime_cursor_anchor.apply_runtime_patch),
+            ("textual_kitty_keyboard", textual_kitty_keyboard.apply_runtime_patch),
+            ("textual_utf8_decoder", textual_utf8_decoder.apply_runtime_patch),
+        )
+    )
+    return results