iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/agent_middleware/reminders/archive_pointer.py

@@ -0,0 +1,154 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The ``archive`` catalog: a pointer to the records compaction archived from previous turns.
+
+The record count and catalog path are captured when a turn is prepared
+fresh and stay fixed for that turn; a restored retry reuses the persisted
+count (``CATALOG_POINTER_RECORD_COUNT_STATE_KEY``).  A recorded pointer is
+re-rendered at this session's catalog path (``retarget``), so a forked or
+moved session names its own catalog.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from chrys.service.context.compaction.spill import SpillQuota
+
+logger = logging.getLogger(__name__)
+
+_STATE_INTEGER_MAX = (1 << 63) - 1
+CATALOG_POINTER_RECORD_COUNT_STATE_KEY = "last_words_catalog_pointer_record_count"
+
+_CATALOG_POINTER_SUFFIX = " (contains each record's relative path)."
+# The whole pointer sentence, so a reminder that merely quotes part of it
+# (a todo item, a hook note) is never taken for the pointer.
+_CATALOG_POINTER = re.compile(
+    r"(Earlier context compaction archived [1-9][0-9]* records? from previous turns; catalog: )"
+    r".+" + re.escape(_CATALOG_POINTER_SUFFIX),
+    re.DOTALL,
+)
+
+
+def _catalog_pointer_text(record_count: int, path: str) -> str:
+    record_label = "record" if record_count == 1 else "records"
+    return (
+        f"Earlier context compaction archived {record_count} {record_label} from previous turns; "
+        f"catalog: {path}{_CATALOG_POINTER_SUFFIX}"
+    )
+
+
+class ArchivePointerSource:
+    """The archive pointer one middleware offers for its session."""
+
+    name = "archive"
+    """The catalog's record name."""
+
+    def __init__(
+        self,
+        *,
+        session_root: Path | None,
+        file_read_available: bool,
+        spill_quota: SpillQuota | None,
+        enabled: bool,
+    ) -> None:
+        self._session_root = session_root
+        self._session_catalog: str | None = None
+        self._file_read_available = file_read_available
+        self._spill_quota = spill_quota
+        self._enabled = enabled
+        self._record_count = 0
+        self._path: str | None = None
+        self._snapshot_valid = False
+        self._restored_record_count: int | None = None
+
+    def current_text(self) -> str | None:
+        """The pointer this turn offers; None without archived records or a readable catalog."""
+        return _catalog_pointer_text(self._record_count, self._path) if self._record_count and self._path else None
+
+    @property
+    def restored_record_count(self) -> int | None:
+        """The count a restored retry stashed, until the next prepared turn discards it."""
+        return self._restored_record_count
+
+    def restore_record_count(self, value: object) -> None:
+        """Stash a validated turn-start catalog count for a restored retry."""
+        if value is None:
+            self._restored_record_count = None
+            return
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0 or value > _STATE_INTEGER_MAX:
+            logger.debug("Dropping malformed dropped-record catalog pointer count")
+            self._restored_record_count = None
+            return
+        self._restored_record_count = value
+
+    def discard_restored(self) -> None:
+        """Drop the stashed count: it is single-shot."""
+        self._restored_record_count = None
+
+    def record_count_state(self) -> int | None:
+        """Return the persisted turn-start catalog count, including zero."""
+        if self._snapshot_valid:
+            return self._record_count
+        return self._restored_record_count
+
+    def capture_live(self, *, excluded_relative_paths: set[str] | None = None) -> None:
+        """Capture the catalog count/path at a real turn boundary."""
+        if not self._enabled or self._session_root is None or self._spill_quota is None:
+            self.capture(0)
+            return
+        record_count = self._spill_quota.live_record_count(
+            excluded_relative_paths=excluded_relative_paths or (),
+        )
+        self.capture(record_count)
+
+    def capture(self, record_count: int) -> None:
+        """Install one stable turn-start count and derive its read affordance."""
+        self._record_count = record_count
+        self._path = None
+        self._snapshot_valid = True
+        if (
+            record_count
+            and self._enabled
+            and self._file_read_available
+            and self._session_root is not None
+            and self._spill_quota is not None
+            and self._spill_quota.storage_available
+        ):
+            from chrys.service.context.compaction.spill import catalog_path_for_read
+
+            if catalog_path_for_read(self._session_root) is not None:
+                self._path = self._session_catalog_path()
+
+    def retarget(self, text: str) -> str | None:
+        """*text* naming this session's catalog, when it is a whole pointer sentence.
+
+        The pointer names the catalog by absolute path; a session copied
+        elsewhere (fork, a move to a new session root) points it at its own
+        catalog, which changes the prefix once.  None when *text* is not a
+        pointer or there is no session root.
+        """
+        pointer = _CATALOG_POINTER.fullmatch(text)
+        current = self._session_catalog_path() if pointer is not None else None
+        if pointer is None or current is None:
+            return None
+        return f"{pointer.group(1)}{current}{_CATALOG_POINTER_SUFFIX}"
+
+    def _session_catalog_path(self) -> str | None:
+        """This session's compaction catalog, by the absolute path reminders name it with.
+
+        Resolved once: the session root is fixed for the middleware's life,
+        and every call re-renders each recorded pointer with it.
+        """
+        if self._session_root is None:
+            return None
+        if self._session_catalog is None:
+            from chrys.service.context.compaction.spill import CATALOG_RELATIVE_PATH
+
+            self._session_catalog = (self._session_root.resolve(strict=False) / CATALOG_RELATIVE_PATH).as_posix()
+        return self._session_catalog

chrys/service/agent_middleware/reminders/base.py

@@ -0,0 +1,25 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""What the reminder middleware asks of its content sources."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class CatalogSource(Protocol):
+    """Standing context, sent again whenever the latest version in view differs."""
+
+    @property
+    def name(self) -> str:
+        """The catalog's record name; persisted, so it never changes."""
+        ...
+
+    @property
+    def withdrawn(self) -> str | None:
+        """What replaces the catalog once it is no longer offered; None leaves its last version standing."""
+        ...
+
+    def snapshot(self) -> str | None:
+        """The catalog's current text, or None when it offers none."""
+        ...

chrys/service/agent_middleware/reminders/context_usage.py

@@ -0,0 +1,74 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Context usage: the ``[Context Usage]`` line and the high-usage warning.
+
+The warning is an event reminder armed while usage stays below the threshold:
+it goes out on the turn usage reaches the threshold, and again only after
+usage fell below it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from chrys.kernel import Message
+
+
+CONTEXT_USAGE_WARNING = (
+    "[Context Usage] WARNING: Context usage is high. Use `list_compressed_contexts` to see "
+    "available fold markers, then `compress_context` with a marker_id to "
+    "compress older turns into a summary. Use `recall_context` to query "
+    "compressed blocks if you need specific details later."
+)
+"""Sent once when context usage reaches the warning threshold."""
+
+
+def context_usage_percent(usage: Mapping[str, Any], *, max_context_tokens: int) -> float:
+    """The share of the context window *usage* fills, in percent (one decimal)."""
+    return round(_total_tokens(usage) / max_context_tokens * 100, 1) if max_context_tokens else 0.0
+
+
+def format_usage_line(usage: Mapping[str, Any], *, max_context_tokens: int) -> str:
+    """The ``[Context Usage]`` line for *usage*."""
+    total_pct = context_usage_percent(usage, max_context_tokens=max_context_tokens)
+    return f"[Context Usage] current: {total_pct}% ({_total_tokens(usage):,}/{max_context_tokens:,})"
+
+
+def _total_tokens(usage: Mapping[str, Any]) -> int:
+    input_tokens = usage.get("input_token_count") or 0
+    output_tokens = usage.get("output_token_count") or 0
+    return usage.get("total_token_count") or (input_tokens + output_tokens)
+
+
+class ContextWarningSource:
+    """The context-usage warning one middleware offers, and whether it is armed."""
+
+    def __init__(self, *, max_context_tokens: int, warn_threshold_pct: float) -> None:
+        self._max_context_tokens = max_context_tokens
+        self._warn_threshold_pct = warn_threshold_pct
+        # Whether the next turn at or above the warning threshold warns: a
+        # request carrying the warning disarms it, a turn below re-arms it.
+        # A new middleware (rebuild, restart) warns again at most once.
+        self._armed = True
+
+    @property
+    def armed(self) -> bool:
+        """Whether the next turn at or above the threshold warns."""
+        return self._armed
+
+    def snapshot(self, usage: Mapping[str, Any]) -> str | None:
+        """The warning for a turn starting after *usage*, while armed; usage below the threshold re-arms it."""
+        if not usage:
+            return None
+        usage_pct = context_usage_percent(usage, max_context_tokens=self._max_context_tokens)
+        if usage_pct < self._warn_threshold_pct * 100:
+            self._armed = True
+            return None
+        return CONTEXT_USAGE_WARNING if self._armed else None
+
+    def delivered(self, _messages: Sequence[Message]) -> None:
+        """Request observer: a request carried the warning, which disarms it."""
+        self._armed = False

chrys/service/agent_middleware/reminders/file_change.py

@@ -0,0 +1,63 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Workspace file changes: the notice drained from the workspace change tracker.
+
+The tracker is drained when the turn is prepared, so a notice no request
+carried goes back to it (``SystemReminderMiddleware.take_undelivered_file_change``).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from chrys.kernel import Message
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class FileChangeTurn:
+    """One turn's file-change notice."""
+
+    text: str
+    delivered: bool = False
+    """Whether the notice reached at least one established provider request.
+
+    Set by a ``request_message_observers`` callback at the final-handler
+    boundary, not when ``process()`` enriches the messages: on lazy streaming
+    paths ``call_next()`` returns a proxy and the request is only established
+    at first stream consumption. A pass that ends with this still False
+    (Stop, load/hook failure, cancellation before the first request) must
+    requeue the notice — the tracker was already drained at ``prepare_turn``.
+    """
+
+    def mark_delivered(self, _messages: Sequence[Message]) -> None:
+        """The request-message observer that records a delivery."""
+        self.delivered = True
+
+
+class FileChangeSource:
+    """The file-change notices one middleware offers, drained from the workspace change tracker."""
+
+    def __init__(self, provider: Callable[[], str | None] | None) -> None:
+        self._provider = provider
+
+    def drain(self) -> FileChangeTurn | None:
+        """Drain the advisory provider without allowing it to break a turn.
+
+        Unlike the other sources' reads, this consumes the tracker's notice:
+        only ``prepare_turn`` calls it.
+        """
+        if self._provider is None:
+            return None
+        try:
+            text = self._provider() or None
+        except Exception:
+            logger.debug("Workspace file-change reminder provider failed", exc_info=True)
+            return None
+        return FileChangeTurn(text) if text is not None else None

chrys/service/agent_middleware/reminders/mcp.py

@@ -0,0 +1,39 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The ``mcp`` catalog: the instructions the agent's MCP servers publish."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class McpSource:
+    """The MCP server instructions one middleware offers, read from the agent's MCP adapter."""
+
+    name = "mcp"
+    """The catalog's record name."""
+    withdrawn = (
+        "<mcp_instructions>\n"
+        "  <none>No MCP server instructions apply to the current agent; earlier ones no longer apply.</none>\n"
+        "</mcp_instructions>"
+    )
+    """Replaces the instructions once the current agent's servers publish none."""
+
+    def __init__(self, provider: Callable[[], str | None] | None) -> None:
+        self._provider = provider
+
+    def snapshot(self) -> str | None:
+        """The current MCP server instructions block; None without a provider or when it failed."""
+        if self._provider is None:
+            return None
+        try:
+            return self._provider()
+        except Exception:
+            logger.exception("Failed to render MCP server instructions reminder")
+            return None

chrys/service/agent_middleware/reminders/profile_switch.py

@@ -0,0 +1,106 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The profile-switch notice: what the new agent is told after a profile switch.
+
+A switch stays pending until a request whose latest switch notice is its own
+returns normally; consecutive switches before that keep the original *from*.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+@dataclass(frozen=True, slots=True)
+class SwitchSnapshot:
+    """A pending switch as one turn announces it."""
+
+    from_label: str
+    to_label: str
+    notice: str
+
+
+class ProfileSwitchSource:
+    """The profile switch one middleware announces, and the one a request last carried."""
+
+    def __init__(self, tool_names: Sequence[str] | None) -> None:
+        self._tool_names = _dedupe_tool_names(tool_names)
+        self._pending_switch: dict[str, str] | None = None
+        self._consumed_switch_to: str | None = None
+
+    def set_profile_switch(self, from_label: str, to_label: str) -> None:
+        """Set pending profile switch info."""
+        self._pending_switch = {"from": from_label, "to": to_label}
+
+    def update_profile_switch_to(self, to_label: str) -> None:
+        """Update *to* for consecutive switches (keep original *from*)."""
+        if self._pending_switch is not None:
+            self._pending_switch["to"] = to_label
+
+    @property
+    def has_pending_switch(self) -> bool:
+        return self._pending_switch is not None
+
+    def snapshot_pending_switch(self) -> dict[str, str] | None:
+        """Return a copy of pending profile-switch metadata, if any."""
+        return self._pending_switch.copy() if self._pending_switch is not None else None
+
+    @property
+    def consumed_switch_to(self) -> str | None:
+        """The display name we switched to, if consumed this turn."""
+        return self._consumed_switch_to
+
+    def snapshot(self) -> SwitchSnapshot | None:
+        """The pending switch with its notice, None without one."""
+        if self._pending_switch is None:
+            return None
+        ps = self._pending_switch
+        return SwitchSnapshot(ps["from"], ps["to"], self._format_profile_switch_hint(ps["from"], ps["to"]))
+
+    def begin_turn(self) -> None:
+        """Forget the switch the previous turn consumed."""
+        self._consumed_switch_to = None
+
+    def carried(self, switch: SwitchSnapshot) -> None:
+        """Consume *switch*: a request whose latest switch notice is its own returned normally.
+
+        The pending switch clears only while it is still *switch*: one made
+        during the request stays pending for the next turn.
+        """
+        self._consumed_switch_to = switch.to_label
+        pending = self._pending_switch
+        if pending is not None and pending.get("from") == switch.from_label and pending.get("to") == switch.to_label:
+            self._pending_switch = None
+
+    def _format_profile_switch_hint(self, from_label: str, to_label: str) -> str:
+        """Format the profile-switch reminder shown to the new agent."""
+        if self._tool_names:
+            tools = ", ".join(self._tool_names)
+            tool_hint = f"Your currently available tools are: {tools}."
+        else:
+            tool_hint = "Your current agent has no available tools."
+        return (
+            f"[Agent profile switched from '{from_label}' to '{to_label}']\n"
+            "System instructions may also have changed; read and follow your current instructions carefully. "
+            "Earlier conversation may include tool-call records created by the previous agent. "
+            f"{tool_hint} You may only use tools that are currently available to you; "
+            "treat earlier tool calls as reference and context only."
+        )
+
+
+def _dedupe_tool_names(tool_names: Sequence[str] | None) -> tuple[str, ...]:
+    """Return non-empty tool names in caller order, without duplicates."""
+    if not tool_names:
+        return ()
+    names: list[str] = []
+    seen: set[str] = set()
+    for name in tool_names:
+        clean = name.strip()
+        if clean and clean not in seen:
+            names.append(clean)
+            seen.add(clean)
+    return tuple(names)

chrys/service/agent_middleware/reminders/runtime_env.py

@@ -0,0 +1,190 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The ``runtime`` catalog: where the agent runs and, with a shell tool, which Python to run.
+
+Snapshotted when a turn starts fresh; ``system_reminder`` decides when it is
+sent.  Python-execution-path discovery searches ``PATH`` on every snapshot.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from chrys.foundation.platform.files import surrogate_safe_text
+from chrys.foundation.platform.runtime_paths import normalize_path as _normalise_path
+from chrys.foundation.platform.runtime_paths import same_path, which_excluding_runtime
+
+if TYPE_CHECKING:
+    from chrys.foundation.models.session_env import SessionEnvironment
+
+_PYTHON_EXECUTABLE_NAMES = ("python3", "python")
+_WINDOWS_PYTHON_EXECUTABLE_NAMES = ("python3", "python", "py")
+_PROCESS_SAFE_RUNTIME_PYTHON_BASENAMES = frozenset({"chrys-runtime", "chrys-runtime.exe", "chrys-runtimew.exe"})
+
+
+@dataclass(frozen=True)
+class _PythonExecutionPath:
+    """A discovered path relevant to Python execution via a shell tool."""
+
+    label: str
+    path: str
+    version: str = ""
+
+
+class RuntimeEnvSource:
+    """The runtime environment one middleware reports: cwd, OS, shells, working directories."""
+
+    name = "runtime"
+    """The catalog's record name."""
+    withdrawn = None
+    """None: when no runtime hint is offered, the last one in view stays standing."""
+
+    def __init__(self, runtime: SessionEnvironment | None, *, shell_tool_enabled: bool) -> None:
+        self._runtime = runtime
+        self._shell_tool_enabled = shell_tool_enabled
+
+    def snapshot(self) -> str | None:
+        """The runtime hint, or None without a session environment; callers cache it at turn start."""
+        rt = self._runtime
+        if rt is None:
+            return None
+
+        shell = rt.platform.shell
+        shell_line = f"  Shell: {shell.name} {shell.version} ({shell.path})".rstrip()
+        lines = [
+            "[Runtime Environment]",
+            f"  Working directory: {rt.cwd}",
+            f"  OS: {rt.platform.os_name} ({rt.platform.arch})",
+            shell_line,
+        ]
+        lines.extend(
+            f"  Shell: {extra.name} {extra.version} ({extra.path})".rstrip() for extra in rt.platform.extra_shells
+        )
+        if self._shell_tool_enabled:
+            lines.extend(_format_python_execution_paths_hint())
+        if rt.working_dirs:
+            lines.append("  Working directories:")
+            for wd in rt.working_dirs:
+                marker = " (primary)" if wd.is_primary else ""
+                label = f" [{wd.label}]" if wd.label else ""
+                lines.append(f"    - {wd.path}{label}{marker}")
+        return surrogate_safe_text("\n".join(lines))
+
+
+def _format_python_execution_paths_hint() -> list[str]:
+    """Format Python execution paths for agents that can use a shell tool."""
+    paths = _python_execution_paths()
+    if not paths:
+        return []
+
+    has_runtime_python = any(path.label == "your runtime Python" for path in paths)
+    has_system_uv = any(path.label == "system uv" for path in paths)
+    lines = ["  Python execution paths (for Python scripts or Python commands):"]
+    lines.extend(_format_python_execution_path_line(path) for path in paths)
+    if has_system_uv:
+        lines.append(
+            "  Consider uv or uvx for ad-hoc Python scripts/tools with temporary dependencies to avoid modifying "
+            "user system or project Python environments, unless user/project/skill instructions say otherwise."
+        )
+    if has_runtime_python:
+        lines.append(
+            "  Your runtime Python path is a fallback for Python scripts/commands when no suitable system uv or "
+            "Python executable is available."
+        )
+        if not _runtime_python_uses_process_safe_alias():
+            lines.append(
+                "  Avoid broad Python-process termination commands (for example Get-Process python | Stop-Process, "
+                "pkill python, or killall python); they may terminate your own runtime. Target specific PIDs or child "
+                "processes you started."
+            )
+    return lines
+
+
+def _runtime_python_uses_process_safe_alias() -> bool:
+    """Return true when the runtime executable basename is Chrys' PyApp alias."""
+    basename = sys.executable.replace("\\", "/").rsplit("/", 1)[-1].casefold()
+    return basename in _PROCESS_SAFE_RUNTIME_PYTHON_BASENAMES
+
+
+def _python_execution_paths() -> list[_PythonExecutionPath]:
+    """Return available Python execution paths in stable discovery order."""
+    runtime_python = _normalise_path(sys.executable)
+
+    paths: list[_PythonExecutionPath] = []
+    system_uv = which_excluding_runtime("uv", frozen_only=False, fallback_to_runtime=False)
+    if system_uv:
+        _append_python_execution_path(paths, _python_execution_path("system uv", system_uv))
+
+    system_python = _first_executable(
+        _python_executable_names(),
+        exclude_paths=(runtime_python,),
+    )
+    if system_python:
+        _append_python_execution_path(
+            paths,
+            _python_execution_path("system Python", system_python),
+        )
+
+    if runtime_python:
+        _append_python_execution_path(
+            paths,
+            _python_execution_path("your runtime Python", runtime_python, version=_runtime_python_version()),
+        )
+
+    return paths
+
+
+def _format_python_execution_path_line(path: _PythonExecutionPath) -> str:
+    version = f" ({path.version})" if path.version else ""
+    return f"    - {path.label}{version}: {path.path}"
+
+
+def _append_python_execution_path(paths: list[_PythonExecutionPath], new_path: _PythonExecutionPath) -> None:
+    """Append *new_path*, merging labels when the same executable is already listed."""
+    for index, existing in enumerate(paths):
+        if same_path(existing.path, new_path.path):
+            labels = [*existing.label.split(" / "), new_path.label]
+            version = existing.version or new_path.version
+            paths[index] = _PythonExecutionPath(
+                label=" / ".join(dict.fromkeys(labels)),
+                path=existing.path,
+                version=version,
+            )
+            return
+    paths.append(new_path)
+
+
+def _python_execution_path(label: str, path: str, *, version: str = "") -> _PythonExecutionPath:
+    return _PythonExecutionPath(label=label, path=path, version=version)
+
+
+def _runtime_python_version() -> str:
+    version = sys.version_info
+    return f"{version.major}.{version.minor}.{version.micro}"
+
+
+def _python_executable_names() -> tuple[str, ...]:
+    """Return executable names that should be treated as Python on this platform."""
+    if sys.platform == "win32":
+        return _WINDOWS_PYTHON_EXECUTABLE_NAMES
+    return _PYTHON_EXECUTABLE_NAMES
+
+
+def _first_executable(
+    names: tuple[str, ...],
+    *,
+    exclude_paths: tuple[str, ...] = (),
+) -> str:
+    """Return the first executable found on PATH."""
+    for name in names:
+        path = which_excluding_runtime(
+            name,
+            frozen_only=False,
+            fallback_to_runtime=False,
+            exclude_paths=exclude_paths,
+        )
+        if path:
+            return path
+    return ""