iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/events/workflow.py

@@ -0,0 +1,38 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared workflow lifecycle event family for subscribers and historical projection."""
+
+from __future__ import annotations
+
+from chrys.foundation.events.types import (
+    WorkflowLoopIteration,
+    WorkflowNodeAnswered,
+    WorkflowNodeAskUser,
+    WorkflowNodeOutput,
+    WorkflowNodeStateChanged,
+    WorkflowRunFinished,
+    WorkflowRunNotice,
+    WorkflowRunStarted,
+)
+
+type WorkflowRunEvent = (
+    WorkflowRunStarted
+    | WorkflowNodeStateChanged
+    | WorkflowNodeOutput
+    | WorkflowNodeAskUser
+    | WorkflowNodeAnswered
+    | WorkflowLoopIteration
+    | WorkflowRunNotice
+    | WorkflowRunFinished
+)
+
+WORKFLOW_RUN_EVENTS = (
+    WorkflowRunStarted,
+    WorkflowNodeStateChanged,
+    WorkflowNodeOutput,
+    WorkflowNodeAskUser,
+    WorkflowNodeAnswered,
+    WorkflowLoopIteration,
+    WorkflowRunNotice,
+    WorkflowRunFinished,
+)

chrys/foundation/hosted_tools.py

@@ -0,0 +1,142 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Provider-neutral hosted-tool vocabulary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+from chrys.foundation.tool_kinds import KIND_MCP, KIND_SEARCH, KIND_SHELL
+
+PRESENTATION_TEXT_SEGMENT_ID_KEY: Final[str] = "_chrys_presentation_text_segment_id"
+"""Private Content metadata key identifying one streamed output-text item."""
+
+ANTHROPIC_HOSTED_WIRE_BLOCK_KEY: Final[str] = "anthropic.hosted_block"
+OPENAI_HOSTED_WIRE_ITEM_KEY: Final[str] = "openai.responses.hosted_item"
+HOSTED_WIRE_REPLAY_PROPERTY_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        ANTHROPIC_HOSTED_WIRE_BLOCK_KEY,
+        OPENAI_HOSTED_WIRE_ITEM_KEY,
+    }
+)
+"""Exact provider-wire mirrors that must not be counted beside canonical content."""
+
+
+class HostedToolFamily(StrEnum):
+    """Canonical hosted-tool presentation families."""
+
+    SEARCH = "search"
+    FETCH = "fetch"
+    MCP = "mcp"
+    CODE = "code"
+    IMAGE = "image"
+    SHELL = "shell"
+    TOOL_DISCOVERY = "tool_discovery"
+    FILE_OPERATION = "file_operation"
+    GENERIC = "generic"
+
+
+class HostedToolPhase(StrEnum):
+    """Canonical phases of a hosted-tool lifecycle update."""
+
+    START = "start"
+    DELTA = "delta"
+    SNAPSHOT = "snapshot"
+    TERMINAL = "terminal"
+
+
+class HostedToolStatus(StrEnum):
+    """Canonical hosted-tool lifecycle statuses."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    INTERRUPTED = "interrupted"
+    UNKNOWN = "unknown"
+
+
+class HostedRetrySafety(StrEnum):
+    """Canonical retry-safety classes for provider-hosted work."""
+
+    READ_ONLY = "read_only"
+    SANDBOXED = "sandboxed"
+    SIDE_EFFECTFUL = "side_effectful"
+    UNKNOWN = "unknown"
+
+
+HOSTED_TOOL_DEFAULT_KIND_BY_FAMILY: Final[dict[str, str]] = {
+    HostedToolFamily.SEARCH: KIND_SEARCH,
+    HostedToolFamily.FETCH: KIND_SEARCH,
+    HostedToolFamily.MCP: KIND_MCP,
+    HostedToolFamily.CODE: "",
+    HostedToolFamily.IMAGE: "",
+    HostedToolFamily.SHELL: KIND_SHELL,
+    HostedToolFamily.TOOL_DISCOVERY: "",
+    HostedToolFamily.FILE_OPERATION: "",
+    HostedToolFamily.GENERIC: "",
+}
+
+HOSTED_TOOL_DEFAULT_TITLE_BY_FAMILY: Final[dict[str, str]] = {
+    HostedToolFamily.SEARCH: "Hosted Search",
+    HostedToolFamily.FETCH: "Hosted Fetch",
+    HostedToolFamily.MCP: "Hosted MCP",
+    HostedToolFamily.CODE: "Hosted Code",
+    HostedToolFamily.IMAGE: "Hosted Image",
+    HostedToolFamily.SHELL: "Hosted Shell",
+    HostedToolFamily.TOOL_DISCOVERY: "Hosted Tool Discovery",
+    HostedToolFamily.FILE_OPERATION: "Hosted File Operation",
+    HostedToolFamily.GENERIC: "Hosted Tool",
+}
+
+HOSTED_TOOL_DEFAULT_RETRY_SAFETY_BY_FAMILY: Final[dict[str, HostedRetrySafety]] = {
+    HostedToolFamily.SEARCH: HostedRetrySafety.READ_ONLY,
+    HostedToolFamily.FETCH: HostedRetrySafety.READ_ONLY,
+    HostedToolFamily.MCP: HostedRetrySafety.SIDE_EFFECTFUL,
+    HostedToolFamily.CODE: HostedRetrySafety.SANDBOXED,
+    HostedToolFamily.IMAGE: HostedRetrySafety.SANDBOXED,
+    HostedToolFamily.SHELL: HostedRetrySafety.SIDE_EFFECTFUL,
+    HostedToolFamily.TOOL_DISCOVERY: HostedRetrySafety.READ_ONLY,
+    HostedToolFamily.FILE_OPERATION: HostedRetrySafety.SIDE_EFFECTFUL,
+    HostedToolFamily.GENERIC: HostedRetrySafety.UNKNOWN,
+}
+
+_STATUS_ALIASES: Final[dict[str, HostedToolStatus]] = {
+    "pending": HostedToolStatus.PENDING,
+    "queued": HostedToolStatus.PENDING,
+    "running": HostedToolStatus.RUNNING,
+    "in_progress": HostedToolStatus.RUNNING,
+    "searching": HostedToolStatus.RUNNING,
+    "interpreting": HostedToolStatus.RUNNING,
+    "generating": HostedToolStatus.RUNNING,
+    "completed": HostedToolStatus.COMPLETED,
+    "succeeded": HostedToolStatus.COMPLETED,
+    "success": HostedToolStatus.COMPLETED,
+    "failed": HostedToolStatus.FAILED,
+    "error": HostedToolStatus.FAILED,
+    "incomplete": HostedToolStatus.FAILED,
+    "interrupted": HostedToolStatus.INTERRUPTED,
+    "cancelled": HostedToolStatus.INTERRUPTED,
+    "canceled": HostedToolStatus.INTERRUPTED,
+}
+
+
+def normalize_hosted_tool_status(status: str | None) -> HostedToolStatus:
+    """Normalize a provider status to the canonical hosted-tool vocabulary."""
+    if status is None:
+        return HostedToolStatus.UNKNOWN
+    return _STATUS_ALIASES.get(status.strip().lower(), HostedToolStatus.UNKNOWN)
+
+
+@dataclass(frozen=True, slots=True)
+class HeldHostedEvidence:
+    """Hosted work a stream received but holds back to keep its place behind an unfinished call.
+
+    It rides a contentless update as its ``raw_representation``, so the retry
+    gates count the work as soon as it arrives. The contents themselves are
+    sent, presented and replayed only when the adapter releases them in order.
+    """
+
+    contents: tuple[object, ...]

chrys/foundation/i18n/__init__.py

@@ -0,0 +1,32 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Locale-neutral message definitions and display argument types."""
+
+from chrys.foundation.i18n.locale import SUPPORTED_LOCALES, normalize_locale
+from chrys.foundation.i18n.localizer import CatalogLoadWarning, CatalogWarningCode, Localizer
+from chrys.foundation.i18n.messages import (
+    DisplayBlock,
+    DisplayPath,
+    DisplaySequence,
+    MessageArg,
+    MessageDef,
+    MessageRef,
+    MessageScalar,
+    msg,
+)
+
+__all__ = [
+    "SUPPORTED_LOCALES",
+    "CatalogLoadWarning",
+    "CatalogWarningCode",
+    "DisplayBlock",
+    "DisplayPath",
+    "DisplaySequence",
+    "Localizer",
+    "MessageArg",
+    "MessageDef",
+    "MessageRef",
+    "MessageScalar",
+    "msg",
+    "normalize_locale",
+]

chrys/foundation/i18n/catalogs.py

@@ -0,0 +1,42 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Class-based GNU gettext catalog loading."""
+
+from __future__ import annotations
+
+import gettext
+import struct
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+type CatalogRoot = str | Path | Traversable
+
+
+class CatalogLoadError(Exception):
+    """A requested GNU MO catalog could not be loaded safely."""
+
+
+def load_catalog(
+    locale_name: str,
+    *,
+    catalog_root: CatalogRoot | None = None,
+    domain: str = "chrys",
+) -> gettext.GNUTranslations:
+    """Load one locale's MO as an isolated ``GNUTranslations`` instance."""
+    root = _catalog_root(catalog_root)
+    catalog_path = root / locale_name / "LC_MESSAGES" / f"{domain}.mo"
+    try:
+        with catalog_path.open("rb") as stream:
+            catalog = gettext.GNUTranslations(stream)
+    except (OSError, EOFError, LookupError, SyntaxError, ValueError, struct.error) as error:
+        raise CatalogLoadError("The i18n catalog could not be loaded.") from error
+    return catalog
+
+
+def _catalog_root(configured: CatalogRoot | None) -> Traversable:
+    if configured is None:
+        return resources.files("chrys.foundation.i18n") / "_catalogs"
+    if isinstance(configured, str):
+        return Path(configured)
+    return configured

chrys/foundation/i18n/formatting.py

@@ -0,0 +1,202 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Safe named-slot formatting for locale-neutral display messages."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from chrys.foundation.i18n.messages import MessageRef
+
+_PLACEHOLDER_NAME_RE = re.compile(r"[a-z][a-z0-9_]*\Z")
+_LOOKUP_ID_RE = re.compile(r"[a-z0-9_]+(?:\.[a-z0-9_]+)+(?:#plural)?\Z")
+_REPLACEMENT_CHARACTER = "�"
+
+
+def _cell_len(text: str) -> int:
+    from rich.cells import cell_len
+
+    return cell_len(text)
+
+
+def has_visible_content(text: str) -> bool:
+    """Return whether *text* contains a glyph with positive terminal width."""
+    candidate = "".join(character for character in text if character != "\n" and not character.isspace())
+    return bool(candidate) and _cell_len(candidate) > 0
+
+
+def parse_placeholder_names(template: str) -> frozenset[str]:
+    """Parse the project's strict ``{lowercase_name}`` placeholder grammar.
+
+    A hand-rolled scanner, deliberately not ``string.Formatter.parse``: the
+    Formatter cannot distinguish ``{value}`` from ``{value:}`` (both report an
+    empty format spec), and the strict grammar admits nothing but a bare
+    lowercase name between braces anyway.
+    """
+    if type(template) is not str:
+        raise TypeError("Authored message templates must be strings.")
+
+    names: set[str] = set()
+    index = 0
+    length = len(template)
+    while index < length:
+        character = template[index]
+        if character == "{":
+            if index + 1 < length and template[index + 1] == "{":
+                index += 2
+                continue
+            end = template.find("}", index + 1)
+            if end == -1:
+                raise ValueError("Invalid message placeholder syntax.")
+            name = template[index + 1 : end]
+            if not _PLACEHOLDER_NAME_RE.fullmatch(name):
+                raise ValueError("Message placeholder names must be lowercase snake_case identifiers.")
+            names.add(name)
+            index = end + 1
+        elif character == "}":
+            if index + 1 < length and template[index + 1] == "}":
+                index += 2
+                continue
+            raise ValueError("Invalid message placeholder syntax.")
+        else:
+            index += 1
+    return frozenset(names)
+
+
+def validate_authored_template(template: str, *, multiline: bool) -> frozenset[str]:
+    """Validate controls, markup, and placeholders in an authored template."""
+    if type(multiline) is not bool:
+        raise TypeError("The multiline flag must be a bool.")
+    if type(template) is not str:
+        raise TypeError("Authored message templates must be strings.")
+
+    for character in template:
+        codepoint = ord(character)
+        if character == "\n":
+            if multiline:
+                continue
+            raise ValueError("LF is forbidden in a single-line message template.")
+        if codepoint < 0x20 or 0x7F <= codepoint <= 0x9F:
+            raise ValueError("Control characters are forbidden in message templates.")
+    names = parse_placeholder_names(template)
+    _reject_markup_bracket_pairs(template)
+    return names
+
+
+def _reject_markup_bracket_pairs(template: str) -> None:
+    # Default-deny: ANY unescaped "[" later followed by "]" reads as markup.
+    # Shape-matching Textual's permissive tag lexer is a losing game
+    # (whitespace-tolerant tags, "-"-prefixed tags, LF inside multiline
+    # bodies), and a non-overlapping pair regex can be masked by an escaped
+    # outer bracket swallowing an inner unescaped one. A "[" is escaped only
+    # behind an ODD backslash run — Rich's escape — since each backslash pair
+    # is one literal backslash; "]" needs no escape in Rich, so any "]" after
+    # an unescaped "[" completes a potential tag.
+    backslash_run = 0
+    unescaped_open_seen = False
+    for character in template:
+        if character == "\\":
+            backslash_run += 1
+            continue
+        if character == "[" and backslash_run % 2 == 0:
+            unescaped_open_seen = True
+        elif character == "]" and unescaped_open_seen:
+            raise ValueError("Square-bracket pairs read as Rich/Textual markup and are forbidden in message templates.")
+        backslash_run = 0
+
+
+def _sanitize_controls(text: str, *, keep_lf: bool, keep_tab: bool = False) -> str:
+    sanitized: list[str] = []
+    for character in text:
+        codepoint = ord(character)
+        if (character == "\n" and keep_lf) or (character == "\t" and keep_tab):
+            sanitized.append(character)
+        elif codepoint < 0x20 or 0x7F <= codepoint <= 0x9F:
+            sanitized.append(_REPLACEMENT_CHARACTER)
+        else:
+            sanitized.append(character)
+    return "".join(sanitized)
+
+
+def sanitize_legacy_scalar(text: str) -> str:
+    """Sanitize literal display text with the single-line control policy."""
+    if type(text) is not str:
+        raise TypeError("Legacy display text must be a string.")
+    return _sanitize_controls(text, keep_lf=False)
+
+
+def sanitize_legacy_block(text: str) -> str:
+    """Sanitize literal display text while preserving LF characters."""
+    if type(text) is not str:
+        raise TypeError("Legacy display text must be a string.")
+    return _sanitize_controls(text, keep_lf=True)
+
+
+def sanitize_terminal_block(text: str) -> str:
+    """Sanitize literal text for a terminal while keeping its layout.
+
+    LF and TAB survive; CR and CRLF become LF, so a bare carriage return cannot
+    overwrite a printed line; every other C0/C1 control and DEL is replaced.
+    """
+    if type(text) is not str:
+        raise TypeError("Legacy display text must be a string.")
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    return _sanitize_controls(normalized, keep_lf=True, keep_tab=True)
+
+
+def format_template(template: str, parameters: Mapping[str, str], *, multiline: bool = False) -> str:
+    """Format a validated template with an exact named-parameter schema."""
+    names = validate_authored_template(template, multiline=multiline)
+    parameter_names = set(parameters)
+    expected_names = parameter_names - {"count"}
+    template_names = names - {"count"}
+    if template_names != expected_names or ("count" in names and "count" not in parameter_names):
+        raise ValueError("Message template parameters do not match the bound argument schema.")
+    if any(type(value) is not str for value in parameters.values()):
+        raise TypeError("Formatted message parameters must already be display strings.")
+    return template.format_map(parameters)
+
+
+def _normalized_lookup_candidate(template: str) -> str:
+    # Remove invisible characters FIRST — format/mark categories AND anything
+    # with zero terminal cell width (e.g. U+1160, category Lo): stripping
+    # whitespace before removing them would leave whitespace they were
+    # shielding at the ends.
+    without_invisibles = "".join(
+        character
+        for character in template
+        if unicodedata.category(character) not in {"Cf", "Me", "Mn"} and _cell_len(character) != 0
+    )
+    return without_invisibles.strip()
+
+
+def _is_lookup_id(template: str) -> bool:
+    return bool(_LOOKUP_ID_RE.fullmatch(_normalized_lookup_candidate(template)))
+
+
+def format_message(reference: MessageRef, template: str | None = None) -> str:
+    """Render *reference*, falling back to English for an invalid translation."""
+    from chrys.foundation.i18n.messages import _render_arguments
+
+    definition = reference.definition
+    fallback = definition.fallback if reference.count is None or reference.count == 1 else definition.plural_fallback
+    if fallback is None:
+        raise ValueError("A plural reference requires a plural fallback.")
+    parameters = _render_arguments(reference)
+    english = format_template(fallback, parameters, multiline=definition.multiline)
+    if template is None:
+        return english
+
+    try:
+        if _is_lookup_id(template):
+            raise ValueError("Catalog templates cannot be lookup identifiers.")
+        translated = format_template(template, parameters, multiline=definition.multiline)
+        if not has_visible_content(translated):
+            raise ValueError("The formatted catalog message has no visible content.")
+    except KeyError, ValueError:
+        return english
+    return translated

chrys/foundation/i18n/locale.py

@@ -0,0 +1,92 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Supported locale normalization and side-effect-free system detection."""
+
+from __future__ import annotations
+
+import ctypes
+import logging
+import os
+from typing import Any, cast
+
+from chrys.foundation.platform import get_platform
+
+logger = logging.getLogger(__name__)
+
+ENGLISH_LOCALE = "en"
+SIMPLIFIED_CHINESE_LOCALE = "zh-Hans"
+SUPPORTED_LOCALES = (ENGLISH_LOCALE, SIMPLIFIED_CHINESE_LOCALE)
+
+_ENGLISH_PREFIXES = ("en-", "english-")
+_SIMPLIFIED_CHINESE_PREFIXES = ("zh-cn-", "zh-hans-", "zh-sg-", "zh-chs-")
+_WINDOWS_LOCALE_NAME_MAX_LENGTH = 85
+
+
+def normalize_locale(value: str) -> str:
+    """Resolve one requested locale to the supported effective locale.
+
+    ``system`` consults the operating system without mutating the process C
+    locale. Unsupported system languages quietly use English; malformed or
+    unsupported explicit settings emit one content-free diagnostic.
+    """
+    if type(value) is not str:
+        _warn_unsupported()
+        return ENGLISH_LOCALE
+
+    requested = value.strip()
+    if requested.casefold() == "system":
+        system_locale = _system_locale_name()
+        if system_locale is None:
+            logger.warning("System locale unavailable; using English.")
+            return ENGLISH_LOCALE
+        return (
+            SIMPLIFIED_CHINESE_LOCALE
+            if _normalize_known_locale(system_locale) == SIMPLIFIED_CHINESE_LOCALE
+            else ENGLISH_LOCALE
+        )
+
+    normalized = _normalize_known_locale(requested)
+    if normalized is not None:
+        return normalized
+    _warn_unsupported()
+    return ENGLISH_LOCALE
+
+
+def _normalize_known_locale(value: str) -> str | None:
+    normalized = value.strip().casefold().replace("_", "-")
+    normalized = normalized.split("@", maxsplit=1)[0].split(".", maxsplit=1)[0]
+    normalized = "-".join(normalized.split())
+
+    if normalized in {"c", "posix", "en", "english"} or normalized.startswith(_ENGLISH_PREFIXES):
+        return ENGLISH_LOCALE
+    if normalized in {"zh", "zh-cn", "zh-hans", "zh-sg", "zh-chs", "chinese-(simplified)-china"}:
+        return SIMPLIFIED_CHINESE_LOCALE
+    if normalized.startswith(_SIMPLIFIED_CHINESE_PREFIXES):
+        return SIMPLIFIED_CHINESE_LOCALE
+    return None
+
+
+def _system_locale_name() -> str | None:
+    if get_platform().is_windows:
+        return _windows_locale_name()
+    return os.environ.get("LC_ALL") or os.environ.get("LC_MESSAGES") or os.environ.get("LANG") or None
+
+
+def _windows_locale_name() -> str | None:
+    """Read the Windows user-default locale through ``GetUserDefaultLocaleName``."""
+    try:
+        windows_ctypes = cast(Any, ctypes)
+        kernel32 = windows_ctypes.WinDLL("kernel32", use_last_error=True)
+        get_user_default_locale_name = kernel32.GetUserDefaultLocaleName
+        get_user_default_locale_name.argtypes = [ctypes.POINTER(ctypes.c_wchar), ctypes.c_int]
+        get_user_default_locale_name.restype = ctypes.c_int
+        buffer = ctypes.create_unicode_buffer(_WINDOWS_LOCALE_NAME_MAX_LENGTH)
+        if get_user_default_locale_name(buffer, len(buffer)) == 0:
+            return None
+        return buffer.value or None
+    except OSError, AttributeError, TypeError:
+        return None
+
+
+def _warn_unsupported() -> None:
+    logger.warning("Unsupported locale setting; using English.")