iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/trajectory_timing.py

@@ -0,0 +1,97 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Portable timing metadata for persisted conversation trajectories.
+
+The adapter-facing contract is a ``_chrys_timing`` object containing UTC
+ISO-8601 ``started_at`` / ``finished_at`` values and an integer
+``duration_ms``. It is stored on user/assistant message
+``additional_properties`` and on both sides of each tool exchange (the call
+and its paired result content). User input is an event, so its timestamps are
+equal and its duration is zero. Assistant and tool spans use monotonic clocks
+for duration while retaining wall-clock timestamps for dashboard placement.
+
+Older session files remain readable and may omit the object; adapters should
+treat absence as unknown legacy timing instead of inventing a duration.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from datetime import UTC, datetime
+from typing import Any
+
+from chrys.foundation.util.time import parse_created_at, utc_iso
+
+TRAJECTORY_TIMING_KEY = "_chrys_timing"
+"""Additional-properties key shared by messages and tool call/result contents."""
+
+
+def build_trajectory_timing(
+    *,
+    started_at: datetime | str,
+    finished_at: datetime | str,
+    duration_ms: int,
+) -> dict[str, Any]:
+    """Return one JSON-safe timing envelope with canonical UTC timestamps."""
+    if not isinstance(duration_ms, int) or isinstance(duration_ms, bool) or duration_ms < 0:
+        raise ValueError("Trajectory timing duration_ms must be a non-negative integer.")
+    parsed_started_at = parse_created_at(started_at)
+    parsed_finished_at = parse_created_at(finished_at)
+    if parsed_started_at is None or parsed_finished_at is None:
+        raise ValueError("Trajectory timing timestamps must be valid ISO-8601 values.")
+    return {
+        "started_at": utc_iso(parsed_started_at),
+        "finished_at": utc_iso(parsed_finished_at),
+        "duration_ms": duration_ms,
+    }
+
+
+def build_instant_trajectory_timing(at: datetime | str | None = None) -> dict[str, Any]:
+    """Return a zero-duration envelope for an event-like trajectory item."""
+    timestamp = parse_created_at(at) if at is not None else datetime.now(UTC)
+    if timestamp is None:
+        raise ValueError("Trajectory timing timestamp must be a valid ISO-8601 value.")
+    return build_trajectory_timing(started_at=timestamp, finished_at=timestamp, duration_ms=0)
+
+
+def trajectory_timing_from_metadata(metadata: Mapping[str, Any]) -> dict[str, Any] | None:
+    """Return a normalized copy of a stored timing envelope, or ``None``."""
+    value = metadata.get(TRAJECTORY_TIMING_KEY)
+    if not isinstance(value, Mapping):
+        return None
+    started_at = value.get("started_at")
+    finished_at = value.get("finished_at")
+    duration_ms = value.get("duration_ms")
+    if (
+        not isinstance(started_at, datetime | str)
+        or not isinstance(finished_at, datetime | str)
+        or not isinstance(duration_ms, int)
+        or isinstance(duration_ms, bool)
+    ):
+        return None
+    try:
+        return build_trajectory_timing(
+            started_at=started_at,
+            finished_at=finished_at,
+            duration_ms=duration_ms,
+        )
+    except ValueError:
+        return None
+
+
+def stamp_trajectory_timing(
+    metadata: MutableMapping[str, Any],
+    timing: Mapping[str, Any],
+    *,
+    overwrite: bool = False,
+) -> bool:
+    """Persist a validated timing envelope, returning whether metadata changed."""
+    if TRAJECTORY_TIMING_KEY in metadata and not overwrite:
+        return False
+    normalized = trajectory_timing_from_metadata({TRAJECTORY_TIMING_KEY: timing})
+    if normalized is None:
+        return False
+    if metadata.get(TRAJECTORY_TIMING_KEY) == normalized:
+        return False
+    metadata[TRAJECTORY_TIMING_KEY] = normalized
+    return True

chrys/foundation/util/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Small dependency-free utility helpers."""

chrys/foundation/util/async_tasks.py

@@ -0,0 +1,29 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared asyncio task-boundary helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+async def await_task_quiescence(task: asyncio.Task[None] | None) -> None:
+    """Await one captured task while distinguishing caller cancellation.
+
+    The captured task's cancellation or failure still establishes quiescence;
+    cancellation of the waiting task propagates to its caller.
+    """
+    if task is None or task is asyncio.current_task():
+        return
+    try:
+        await asyncio.shield(task)
+    except asyncio.CancelledError:
+        waiter = asyncio.current_task()
+        if waiter is not None and waiter.cancelling() > 0:
+            raise
+        logger.debug("Captured task was cancelled before quiescence", exc_info=True)
+    except Exception:
+        logger.debug("Captured task failed before quiescence", exc_info=True)

chrys/foundation/util/chrys_headers.py

@@ -0,0 +1,23 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared Chrys-managed HTTP header names."""
+
+MODEL_ID_HEADER = "Chrys-Model-Id"
+PARENT_SESSION_ID_HEADER = "Chrys-Parent-Session-Id"
+SESSION_ID_HEADER = "Chrys-Session-Id"
+X_PARENT_SESSION_ID_HEADER = "X-Parent-Session-ID"
+X_SESSION_ID_HEADER = "X-Session-ID"
+
+_RESERVED_CHRYS_HEADER_PREFIXES = ("chrys-", "chrys_")
+_CHRYS_MANAGED_HEADER_NAMES = frozenset({X_PARENT_SESSION_ID_HEADER.casefold(), X_SESSION_ID_HEADER.casefold()})
+
+
+def _is_reserved_chrys_header_name(name: str) -> bool:
+    """Return whether an HTTP header name is reserved for Chrys-managed metadata."""
+    return name.strip().casefold().startswith(_RESERVED_CHRYS_HEADER_PREFIXES)
+
+
+def is_chrys_managed_header_name(name: str) -> bool:
+    """Return whether an HTTP header name is managed by Chrys."""
+    normalized = name.strip().casefold()
+    return _is_reserved_chrys_header_name(name) or normalized in _CHRYS_MANAGED_HEADER_NAMES

chrys/foundation/util/env_templates.py

@@ -0,0 +1,104 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Runtime environment-variable template resolution.
+
+Configuration files may carry literal placeholders such as ``{{API_KEY}}``.
+Those placeholders are intentionally resolved only at runtime so saved YAML
+keeps the user-authored value and never receives resolved secrets.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+_ENV_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_ESCAPED_OPEN = "\0CHRYS_ENV_TEMPLATE_OPEN\0"
+_ESCAPED_CLOSE = "\0CHRYS_ENV_TEMPLATE_CLOSE\0"
+
+
+class EnvVarResolutionError(ValueError):
+    """Raised when an environment-variable placeholder cannot be resolved."""
+
+
+def _invalid_placeholder_message(raw: str, location: str) -> str:
+    return (
+        f"Invalid environment variable placeholder {raw!r} in {location}. "
+        "Use {{ENV_VAR}} with letters, digits, and underscores only, and no spaces."
+    )
+
+
+def resolve_env_templates(value: str, *, location: str) -> str:
+    """Resolve ``{{ENV_VAR}}`` placeholders in a string.
+
+    Resolution is single-pass: if the environment value itself contains
+    ``{{...}}``, that text is preserved literally.  Missing or empty
+    environment variables are treated as errors because an explicit
+    placeholder means the user expects that runtime value to exist.
+    Only double-brace blocks containing a valid environment variable
+    identifier are resolved; other non-empty blocks, such as
+    ``{{"kind":"json"}}``, are preserved literally.
+    """
+    value = value.replace("{{{{", _ESCAPED_OPEN).replace("}}}}", _ESCAPED_CLOSE)
+    if "{{" not in value and "}}" not in value:
+        return value.replace(_ESCAPED_OPEN, "{{").replace(_ESCAPED_CLOSE, "}}")
+
+    parts: list[str] = []
+    pos = 0
+    while True:
+        start = value.find("{{", pos)
+        stray_end = value.find("}}", pos)
+        if start == -1:
+            if stray_end != -1:
+                raise EnvVarResolutionError(_invalid_placeholder_message("}}", location))
+            parts.append(value[pos:])
+            break
+        if stray_end != -1 and stray_end < start:
+            raise EnvVarResolutionError(_invalid_placeholder_message("}}", location))
+
+        end = value.find("}}", start + 2)
+        if end == -1:
+            raise EnvVarResolutionError(_invalid_placeholder_message(value[start:], location))
+
+        parts.append(value[pos:start])
+        name = value[start + 2 : end]
+        raw_placeholder = value[start : end + 2]
+        if name == "":
+            raise EnvVarResolutionError(_invalid_placeholder_message(raw_placeholder, location))
+        if _ENV_NAME_RE.fullmatch(name) is None:
+            stripped = name.strip()
+            if stripped != name and _ENV_NAME_RE.fullmatch(stripped) is not None:
+                raise EnvVarResolutionError(_invalid_placeholder_message(raw_placeholder, location))
+            parts.append(raw_placeholder)
+            pos = end + 2
+            continue
+
+        resolved = os.environ.get(name)
+        if resolved is None or resolved == "":
+            raise EnvVarResolutionError(
+                f"Environment variable {name!r} is required by {location}, but it is not set. "
+                f"Set {name} in the environment or remove the {{{{{name}}}}} placeholder."
+            )
+        parts.append(resolved)
+        pos = end + 2
+
+    return "".join(parts).replace(_ESCAPED_OPEN, "{{").replace(_ESCAPED_CLOSE, "}}")
+
+
+def resolve_env_template_mapping(values: dict[str, Any], *, location: str) -> dict[str, str]:
+    """Resolve placeholders in mapping values, coercing keys and values to strings."""
+    return {
+        str(key): resolve_env_templates(str(value), location=f"{location}[{key!r}]") for key, value in values.items()
+    }
+
+
+def resolve_env_template_values(value: Any, *, location: str) -> Any:
+    """Recursively resolve placeholders in string values within JSON-like data."""
+    if isinstance(value, str):
+        return resolve_env_templates(value, location=location)
+    if isinstance(value, list):
+        return [resolve_env_template_values(item, location=f"{location}[{index}]") for index, item in enumerate(value)]
+    if isinstance(value, dict):
+        return {key: resolve_env_template_values(item, location=f"{location}[{key!r}]") for key, item in value.items()}
+    return value

chrys/foundation/util/filenames.py

@@ -0,0 +1,96 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Filesystem-safe filename helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+# Characters forbidden on Windows file systems + POSIX separators + control bytes.
+_UNSAFE_FILENAME_RE = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+_WINDOWS_RESERVED_BASENAMES = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{i}" for i in range(1, 10)),
+    *(f"LPT{i}" for i in range(1, 10)),
+}
+
+
+def safe_fs_name(name: str) -> str:
+    """Replace characters that are unsafe in file/directory names with ``_``."""
+    return _UNSAFE_FILENAME_RE.sub("_", name)
+
+
+def safe_platform_basename(name: str, *, default: str = "unnamed") -> str:
+    """Return a non-empty, platform-safe basename."""
+    safe = safe_fs_name(name).rstrip(" .")
+    if not safe or safe in {".", ".."}:
+        safe = default
+    if _is_windows_reserved_basename(safe):
+        safe = f"_{safe}"
+    return safe
+
+
+def bounded_safe_stem(
+    name: str,
+    *,
+    prefix: str = "",
+    suffix: str = "",
+    max_filename_bytes: int = 255,
+    temp_prefix: str = "",
+    temp_suffix: str = "",
+    default: str = "unnamed",
+    digest_chars: int = 8,
+) -> str:
+    """Return a safe basename stem that fits a final filename budget.
+
+    ``prefix`` and ``suffix`` are final filename affixes around the stem.
+    ``temp_prefix`` and ``temp_suffix`` reserve room for atomic-write temporary
+    filenames derived from the final basename.
+    """
+    safe = safe_platform_basename(name, default=default)
+    reserved = _utf8_len(prefix) + _utf8_len(suffix) + _utf8_len(temp_prefix) + _utf8_len(temp_suffix)
+    budget = max(1, max_filename_bytes - reserved)
+    if _utf8_len(safe) <= budget:
+        return safe
+
+    digest = hashlib.sha256(name.encode("utf-8", errors="surrogatepass")).hexdigest()[: max(1, digest_chars)]
+    marker = f"_{digest}"
+    marker_len = _utf8_len(marker)
+    if marker_len >= budget:
+        truncated = _truncate_utf8(digest, budget)
+        return safe_platform_basename(truncated, default=default)
+
+    prefix = _truncate_utf8(safe, budget - marker_len).rstrip(" ._")
+    if not prefix:
+        prefix = default
+    stem = f"{prefix}{marker}"
+    if _is_windows_reserved_basename(stem):
+        stem = f"_{stem}"
+    return _truncate_utf8(stem, budget).rstrip(" .") or default
+
+
+def _is_windows_reserved_basename(name: str) -> bool:
+    base = name.split(".", 1)[0].upper()
+    return base in _WINDOWS_RESERVED_BASENAMES
+
+
+def _utf8_len(value: str) -> int:
+    return len(value.encode("utf-8", errors="surrogatepass"))
+
+
+def _truncate_utf8(value: str, max_bytes: int) -> str:
+    if max_bytes <= 0:
+        return ""
+    used = 0
+    out: list[str] = []
+    for char in value:
+        size = _utf8_len(char)
+        if used + size > max_bytes:
+            break
+        out.append(char)
+        used += size
+    return "".join(out)

chrys/foundation/util/header_charset.py

@@ -0,0 +1,138 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Charset validation for values that travel in HTTP headers.
+
+httpx encodes header names and values as ASCII, so one stray non-ASCII
+or control character in an API key, model id, or custom header aborts
+the request locally — an opaque ``UnicodeEncodeError`` raised before
+anything reaches the provider.  The validators here reject exactly that
+class of value and deliberately nothing more: no provider key prefixes,
+no length rules, no model-id grammar.  Custom gateways and
+OpenAI-compatible servers keep working, and a genuinely wrong-but-
+encodable credential still fails server-side with a clear 401.
+
+Values are constrained to printable ASCII (U+0020 through U+007E) with
+no leading or trailing space: h11 rejects field values with outer
+whitespace (``LocalProtocolError``), so an edge space fails locally just
+like a non-ASCII character — internal spaces remain allowed.  HTAB is
+technically legal in RFC 9110 field values but never needed by API
+credentials or model ids; rejecting all control characters also keeps
+CR/LF header smuggling impossible.
+
+Secret-bearing fields (API keys, header values) are never echoed back:
+their messages report only the 1-based character position.
+"""
+
+from __future__ import annotations
+
+import string
+
+# RFC 9110 ``token`` — the grammar for HTTP field (header) names.
+_HEADER_NAME_SPECIALS = "!#$%&'*+-.^_`|~"
+_HEADER_NAME_CHARS = frozenset(_HEADER_NAME_SPECIALS + string.ascii_letters + string.digits)
+
+
+def find_non_printable_ascii(value: str) -> int | None:
+    """Return the index of the first character outside printable ASCII, else ``None``."""
+    for index, char in enumerate(value):
+        if not "\x20" <= char <= "\x7e":
+            return index
+    return None
+
+
+def _describe_char(char: str) -> str:
+    code = ord(char)
+    if code < 0x20 or code == 0x7F:
+        return f"a control character (U+{code:04X})"
+    return f"unsupported character {char!r} (U+{code:04X})"
+
+
+def _describe_outer_space(value: str) -> str | None:
+    """Describe a leading/trailing space, else ``None``.
+
+    Only plain spaces need this check: every other whitespace character
+    is a control character and already fails the printable-ASCII scan.
+    """
+    if value.startswith(" "):
+        return "starts with a space"
+    if value.endswith(" "):
+        return "ends with a space"
+    return None
+
+
+def api_key_charset_error(value: str) -> str | None:
+    """Return an error message when *value* cannot be sent as an HTTP credential.
+
+    API keys ride in ``Authorization`` / ``x-api-key`` headers, so the
+    whole key must be printable ASCII.  The key is a secret: the message
+    reports the character position, never the content.
+    """
+    index = find_non_printable_ascii(value)
+    if index is not None:
+        return (
+            f"API key contains a non-ASCII or control character at position {index + 1}; "
+            "only printable ASCII is supported."
+        )
+    outer_space = _describe_outer_space(value)
+    if outer_space is not None:
+        return f"API key {outer_space}; HTTP header values cannot carry leading or trailing whitespace."
+    return None
+
+
+def model_id_charset_error(value: str) -> str | None:
+    """Return an error message when *value* cannot ride in an HTTP header.
+
+    Model ids travel in the ``Chrys-Model-Id`` header as well as the
+    request body, so they carry the same printable-ASCII constraint as
+    headers.  Not a secret — the offending character is echoed so the
+    fix is obvious.
+    """
+    if not value:
+        return "Model ID is empty."
+    index = find_non_printable_ascii(value)
+    if index is not None:
+        return (
+            f"Model ID contains {_describe_char(value[index])} at position {index + 1}; "
+            "only printable ASCII is supported."
+        )
+    outer_space = _describe_outer_space(value)
+    if outer_space is not None:
+        return f"Model ID {outer_space}; HTTP header values cannot carry leading or trailing whitespace."
+    return None
+
+
+def header_name_charset_error(name: str) -> str | None:
+    """Return an error message when *name* is not a valid HTTP header name.
+
+    Header names must match the RFC 9110 ``token`` grammar; a name is
+    not a secret, so both the name and the offending character are
+    echoed.
+    """
+    if not name:
+        return "Header name is empty."
+    for index, char in enumerate(name):
+        if char not in _HEADER_NAME_CHARS:
+            return (
+                f"Header name {name!r} contains {_describe_char(char)} at position {index + 1}; "
+                f"header names may only use letters, digits, and {_HEADER_NAME_SPECIALS} characters."
+            )
+    return None
+
+
+def header_value_charset_error(name: str, value: str) -> str | None:
+    """Return an error message when a header *value* cannot be encoded on the wire.
+
+    Header values routinely carry credentials, so like API keys the
+    message reports the position only, never the content.  *name* is
+    echoed to identify the offending header.
+    """
+    index = find_non_printable_ascii(value)
+    if index is not None:
+        return (
+            f"Header {name!r} value contains a non-ASCII or control character at position {index + 1}; "
+            "only printable ASCII is supported."
+        )
+    outer_space = _describe_outer_space(value)
+    if outer_space is not None:
+        return f"Header {name!r} value {outer_space}; HTTP header values cannot carry leading or trailing whitespace."
+    return None

chrys/foundation/util/httpx_helpers.py

@@ -0,0 +1,12 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared helpers for constructing ``httpx`` clients."""
+
+from __future__ import annotations
+
+BYPASS_PROXY_MOUNTS: dict[str, None] = {
+    "http://": None,
+    "https://": None,
+    "all://": None,
+}
+"""Mounts that force httpx to use its direct transport instead of env proxies."""