iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/models/invocations.py

@@ -0,0 +1,63 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Immutable invocation identities, independent of execution and persistence."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class InvocationOrigin:
+    """A logical caller operation, including its explicitly bound ancestry."""
+
+    kind: Literal["turn", "sub_agent", "workflow_node"]
+    session_id: str
+    invocation_id: str
+    parent: InvocationOrigin | None
+    attempt: int = 0
+    """The workflow scheduler attempt a node pass belongs to; 0 for invocations without attempts.
+
+    Part of equality, so a publisher bound to one attempt rejects another attempt's facts. Backend
+    admission and continuation tickets compare with :meth:`same_invocation` instead.
+    """
+
+    def __post_init__(self) -> None:
+        if self.kind not in ("turn", "sub_agent", "workflow_node") or not self.invocation_id:
+            raise ValueError("A live invocation requires a kind and invocation identity")
+
+    def same_invocation(self, other: InvocationOrigin | None) -> bool:
+        """Whether *other* names this logical invocation, in any of its attempts."""
+        return (
+            other is not None
+            and other.kind == self.kind
+            and other.session_id == self.session_id
+            and other.invocation_id == self.invocation_id
+            and other.parent == self.parent
+        )
+
+    @property
+    def root(self) -> InvocationOrigin:
+        """The outermost bound ancestor: the chat turn or workflow node an operation runs under, or itself."""
+        origin = self
+        while origin.parent is not None:
+            origin = origin.parent
+        return origin
+
+
+@dataclass(frozen=True, slots=True)
+class ParentToolOccurrence:
+    """Both parent tool identifiers, scoped to the parent invocation."""
+
+    parent_invocation_id: str
+    parent_event_call_id: str
+    parent_provider_call_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class PassHandle:
+    """An immutable cancellation target; never a provider call identifier."""
+
+    invocation_id: str
+    pass_id: str

chrys/foundation/models/mutation_scope.py

@@ -0,0 +1,28 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Stable execution identities used by mutation queries and file rollback.
+
+A scope identifies one Chat turn or one Workflow run, never a node/attempt.
+Display ordinals are presentation data, not execution identities.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ChatTurnScope:
+    """One turn in a Chat session (retries retain this identity)."""
+
+    turn_id: int
+
+
+@dataclass(frozen=True)
+class WorkflowRunScope:
+    """One run in a Workflow session (all nodes and retries share it)."""
+
+    run_id: str
+
+
+type MutationScope = ChatTurnScope | WorkflowRunScope

chrys/foundation/models/session_env.py

@@ -0,0 +1,87 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""SessionEnvironment — immutable environment snapshot for a Chrys session.
+
+Captured when an agent is built and rebuilt after workspace/profile changes.
+Passed to tools and context providers so session-scoped code uses one explicit
+environment snapshot instead of ad-hoc process globals.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from chrys.foundation.platform import PlatformInfo, get_platform
+
+if TYPE_CHECKING:
+    from chrys.foundation.models.workspace import WorkingDir, Workspace
+
+
+@dataclass(frozen=True)
+class SessionEnvironment:
+    """Immutable snapshot of the current session environment.
+
+    Passed to instance tools (e.g. ShellTools) and context providers so they
+    can reference the workspace cwd, platform info, and other session-scoped
+    state without relying on module-level globals.
+    """
+
+    # Working directory (primary cwd from workspace, or launch dir)
+    cwd: str
+
+    # Platform detection result
+    platform: PlatformInfo
+
+    # Session metadata
+    session_id: str = ""
+    created_at: datetime = field(default_factory=lambda: datetime.now(tz=UTC))
+
+    # Filtered environment snapshot (safe subset)
+    env: dict[str, str] = field(default_factory=dict)
+
+    # Current time at capture
+    local_time: str = ""  # e.g. "2026-03-18 20:30:45 PDT"
+    utc_time: str = ""  # e.g. "2026-03-19 03:30:45 UTC"
+
+    # Working directories from Workspace
+    working_dirs: tuple[WorkingDir, ...] = ()  # tuple for frozen dataclass
+
+    @classmethod
+    def capture(
+        cls,
+        session_id: str = "",
+        workspace: Workspace | None = None,
+    ) -> SessionEnvironment:
+        """Capture current environment into an immutable context.
+
+        If *workspace* is provided, uses its cwd and working dirs.
+        Otherwise falls back to ``os.getcwd()``.
+        """
+        if workspace is not None:
+            cwd = workspace.primary_cwd
+            working_dirs = tuple(workspace.working_dirs)
+        else:
+            cwd = os.getcwd()
+            working_dirs = ()
+
+        now_local = datetime.now().astimezone()
+        now_utc = datetime.now(tz=UTC)
+
+        return cls(
+            cwd=cwd,
+            platform=get_platform(),
+            session_id=session_id,
+            local_time=now_local.strftime("%Y-%m-%d %H:%M:%S %Z"),
+            utc_time=now_utc.strftime("%Y-%m-%d %H:%M:%S UTC"),
+            env=_safe_env_snapshot(),
+            working_dirs=working_dirs,
+        )
+
+
+def _safe_env_snapshot() -> dict[str, str]:
+    """Capture a filtered subset of environment variables (no secrets)."""
+    safe_keys = {"HOME", "USER", "SHELL", "LANG", "PATH", "TERM", "EDITOR"}
+    return {k: v for k, v in os.environ.items() if k in safe_keys}

chrys/foundation/models/session_surface.py

@@ -0,0 +1,29 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The user-facing surface (TUI, CLI or ACP) that last worked in a session."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class SessionSurface(StrEnum):
+    """Where a session was last used for a conversation turn or a workflow run.
+
+    Persisted as its value. A session with no recorded surface predates the
+    field and is treated as TUI by the session browser.
+    """
+
+    TUI = "tui"
+    CLI = "cli"
+    ACP = "acp"
+
+
+def parse_session_surface(value: object) -> SessionSurface | None:
+    """Read a persisted surface; missing and unknown values are ``None``."""
+    if not isinstance(value, str):
+        return None
+    try:
+        return SessionSurface(value)
+    except ValueError:
+        return None

chrys/foundation/models/todos.py

@@ -0,0 +1,74 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Todo-list data model shared by service, orchestration, TUI and ACP layers."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Final, Literal, TypeIs, get_args
+
+logger = logging.getLogger(__name__)
+
+TodoStatus = Literal["pending", "in_progress", "completed"]
+
+TODO_STATUSES: Final[frozenset[str]] = frozenset(get_args(TodoStatus))
+
+MAX_TODO_ITEMS: Final[int] = 128
+MAX_TODO_TEXT_LENGTH: Final[int] = 500
+"""Per-field cap for ``content`` and ``active_form`` (both persisted and rendered)."""
+
+
+def _is_todo_status(value: object) -> TypeIs[TodoStatus]:
+    """Return whether *value* is a supported todo status."""
+    return isinstance(value, str) and value in TODO_STATUSES
+
+
+@dataclass(frozen=True, slots=True)
+class TodoItem:
+    """One entry of the session todo list."""
+
+    content: str
+    """Imperative description, e.g. ``"Run the test suite"``."""
+
+    status: TodoStatus = "pending"
+
+    active_form: str = ""
+    """Optional present-continuous label shown while in progress, e.g. ``"Running tests"``."""
+
+
+def parse_todo_items(raw: object) -> tuple[TodoItem, ...]:
+    """Tolerantly decode persisted ``chrys_todos`` payloads into :class:`TodoItem` tuples.
+
+    The ONE raw→``TodoItem`` decoder: both ``TodoTracker.restore()`` and the
+    TUI session reseed go through it, so malformed or legacy state degrades to
+    skipped items instead of crashing or desyncing the sidebar. Non-list input
+    yields ``()``; per-item bad shape is skipped with a log; never raises.
+    """
+    if not isinstance(raw, list):
+        if raw is not None:
+            logger.warning("Ignoring non-list todo payload of type %s", type(raw).__name__)
+        return ()
+    items: list[TodoItem] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            logger.warning("Skipping non-dict todo entry of type %s", type(entry).__name__)
+            continue
+        content = entry.get("content")
+        if not isinstance(content, str) or not content.strip():
+            logger.warning("Skipping todo entry without usable content: %r", entry)
+            continue
+        status = entry.get("status", "pending")
+        if not _is_todo_status(status):
+            logger.warning("Skipping todo entry with unknown status %r", status)
+            continue
+        active_form = entry.get("active_form", "")
+        if not isinstance(active_form, str):
+            active_form = ""
+        items.append(TodoItem(content=content, status=status, active_form=active_form))
+    return tuple(items)
+
+
+def serialize_todo_items(items: tuple[TodoItem, ...]) -> list[dict[str, str]]:
+    """Encode *items* as the plain-dict ``chrys_todos`` payload."""
+    return [{"content": item.content, "status": item.status, "active_form": item.active_form} for item in items]

chrys/foundation/models/turns.py

@@ -0,0 +1,125 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Canonical turn-boundary resolution for session message histories.
+
+A **real turn** starts at a user message the user actually submitted as a new
+prompt (the *opener*).  Two other kinds of user message appear mid-turn and
+must never open a turn:
+
+- **Injected** (``HistoryMarkerKind.INJECTED_KEY``): user-authored input that
+  arrived while the agent was working — live injections and resume guidance.
+  Permanent user content.
+- **Continuation** (``HistoryMarkerKind.CONTINUATION_KEY``): the synthetic
+  ``"continue"`` nudge the orchestration sends to resume an interrupted run.  Never
+  user-authored; normally removed post-run.
+
+Design rule: turn-boundary resolution and injected/continue classification go
+through this module and the ``HistoryMarkerKind`` constants — no ad-hoc
+``role == "user"`` turn splits and no raw ``"_injected"``/``"_continuation"``
+literals elsewhere.  Sanctioned exceptions (documented at their sites): the
+"literal last user input" anchors (reminder attach point, trailing-cleanup
+scans) and the legacy ``text == "continue"`` fallback in
+``remove_continuation_message``, which serves pre-flag histories.
+
+This module is foundation tier: structural typing only, no kernel import.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+from chrys.foundation.models.history_markers import HistoryMarkerKind
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+UserMessageKind = Literal["opener", "injected", "continuation"]
+
+
+class SupportsTurnMessage(Protocol):
+    """Structural shape of a history message (kernel ``Message`` compatible)."""
+
+    @property
+    def role(self) -> str: ...
+
+    @property
+    def text(self) -> str | None: ...
+
+    @property
+    def additional_properties(self) -> dict[str, Any]: ...
+
+
+def is_mid_turn_user_message(msg: SupportsTurnMessage) -> bool:
+    """User message that continues the current task instead of opening a turn."""
+    return msg.role == "user" and any(
+        msg.additional_properties.get(key, False) for key in HistoryMarkerKind.MID_TURN_USER_KEYS
+    )
+
+
+def opens_turn(msg: SupportsTurnMessage) -> bool:
+    """User message that opens a real turn (unflagged user input)."""
+    return msg.role == "user" and not is_mid_turn_user_message(msg)
+
+
+def is_injected_message(msg: SupportsTurnMessage) -> bool:
+    """User-authored mid-turn message (live injection or resume guidance)."""
+    return msg.role == "user" and bool(msg.additional_properties.get(HistoryMarkerKind.INJECTED_KEY, False))
+
+
+def is_continuation_message(msg: SupportsTurnMessage) -> bool:
+    """Synthetic ``"continue"`` nudge — never user-authored content."""
+    return msg.role == "user" and bool(msg.additional_properties.get(HistoryMarkerKind.CONTINUATION_KEY, False))
+
+
+def user_text_matches(msg: SupportsTurnMessage, text: str, *, kind: UserMessageKind) -> bool:
+    """Kind-compatible user text match: role, text equality, AND flag compatibility.
+
+    ``kind="opener"`` matches unflagged user messages only;
+    ``"injected"``/``"continuation"`` match messages carrying their flag.
+    Shared by every same-text dedup that must not confuse message kinds —
+    a retry-guidance note worded identically to the turn opener is a
+    *different* message and must never dedup against it (and vice versa).
+    """
+    if msg.role != "user" or (msg.text or "") != text:
+        return False
+    props = msg.additional_properties
+    if kind == "opener":
+        return not any(props.get(key, False) for key in HistoryMarkerKind.MID_TURN_USER_KEYS)
+    if kind == "injected":
+        return bool(props.get(HistoryMarkerKind.INJECTED_KEY, False))
+    if kind == "continuation":
+        return bool(props.get(HistoryMarkerKind.CONTINUATION_KEY, False))
+    raise ValueError(f"unknown user message kind: {kind!r}")
+
+
+def turn_slices(messages: Sequence[SupportsTurnMessage]) -> list[tuple[int, int]]:
+    """Return ``(start, end)`` index pairs, one per real turn.
+
+    Splits on :func:`opens_turn` only: injected and continuation user
+    messages stay inside the turn they arrived in.  Messages before the
+    first opener (compressed summaries, provider context, or malformed
+    flagged-first histories) belong to no turn.
+    """
+    slices: list[tuple[int, int]] = []
+    current_start: int | None = None
+    for i, msg in enumerate(messages):
+        if opens_turn(msg):
+            if current_start is not None:
+                slices.append((current_start, i))
+            current_start = i
+    if current_start is not None:
+        slices.append((current_start, len(messages)))
+    return slices
+
+
+def current_turn_start(messages: Sequence[SupportsTurnMessage]) -> int:
+    """Return the index just after the last ``_chrys_kind='turn'`` marker.
+
+    ``0`` when no turn marker exists — the whole history is the current
+    (first) turn region.  This is the marker-region scan shared by history
+    dedup, continuation cleanup, and current-run metadata logic.
+    """
+    for i in range(len(messages) - 1, -1, -1):
+        if messages[i].additional_properties.get(HistoryMarkerKind.KEY) == HistoryMarkerKind.TURN:
+            return i + 1
+    return 0

chrys/foundation/models/workflow_session.py

@@ -0,0 +1,89 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The workflow and owned workspace selected by one admitted session."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from chrys.foundation.models.workspace import WorkingDir, Workspace
+
+
+@dataclass(frozen=True, slots=True)
+class WorkingDirSnapshot:
+    path: str
+    label: str = ""
+    is_primary: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceSnapshot:
+    """A prepared target never retains the caller's mutable Workspace or directory lists."""
+
+    primary_cwd: str
+    working_dirs: tuple[WorkingDirSnapshot, ...] = ()
+    reference_files: tuple[str, ...] = ()
+
+    @classmethod
+    def capture(cls, workspace: Workspace) -> WorkspaceSnapshot:
+        return cls(
+            workspace.primary_cwd,
+            tuple(WorkingDirSnapshot(d.path, d.label, d.is_primary) for d in workspace.working_dirs),
+            tuple(workspace.reference_files),
+        )
+
+    def materialize(self) -> Workspace:
+        return Workspace(
+            self.primary_cwd,
+            [WorkingDir(d.path, d.label, d.is_primary) for d in self.working_dirs],
+            list(self.reference_files),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowModelSelection:
+    """A model profile identity plus durable display text; never stores credentials."""
+
+    profile_id: str
+    name: str
+    model_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowDraft:
+    workflow_id: str
+    workspace: WorkspaceSnapshot
+    model: WorkflowModelSelection | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowIdentity:
+    workflow_id: str
+    canonical_path: str
+    source_kind: str
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowPins:
+    """The exact source, specification and environment reviewed before submission."""
+
+    identity: WorkflowIdentity
+    spec_digest: str
+    environment_fingerprint: str
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowSessionSelection:
+    """Replace the selection as a whole; workspace belongs to this session, never to Chat."""
+
+    session_id: str
+    identity: WorkflowIdentity
+    workspace: WorkspaceSnapshot
+    model: WorkflowModelSelection | None = None
+
+    @property
+    def workflow_id(self) -> str:
+        return self.identity.workflow_id
+
+
+type WorkflowTarget = WorkflowDraft | WorkflowSessionSelection

chrys/foundation/models/workspace.py

@@ -0,0 +1,59 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Workspace data model — session-scoped working directory configuration.
+
+A workspace groups the primary cwd, additional working directories,
+and reference files for a single session.  Changes trigger a SessionEnvironment
+rebuild but preserve conversation history.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class WorkingDir:
+    """A single working directory within a workspace."""
+
+    path: str  # Absolute path
+    label: str = ""  # Optional user label (e.g. "frontend", "api")
+    is_primary: bool = False  # Exactly one must be True per workspace
+
+    @property
+    def exists(self) -> bool:
+        """Check if the directory still exists on disk."""
+        return os.path.isdir(self.path)
+
+
+@dataclass
+class Workspace:
+    """Workspace — working directory configuration for a session.
+
+    Groups the primary cwd, additional working directories, and reference
+    files.  Can be updated mid-session (e.g. changing cwd, adding reference
+    dirs/files).  Changes trigger a SessionEnvironment rebuild but preserve
+    conversation history.
+    """
+
+    primary_cwd: str
+    working_dirs: list[WorkingDir] = field(default_factory=list)
+    reference_files: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_cwd(cls, cwd: str | None = None) -> Workspace:
+        """Create from a working directory (defaults to os.getcwd())."""
+        raw = cwd or os.getcwd()
+        return cls(primary_cwd=os.path.abspath(os.path.expanduser(raw)))
+
+    def missing_primary(self) -> str | None:
+        """Return the primary cwd when it is no longer a directory, else ``None``.
+
+        New work (turns, retries, restores, workflow runs) refuses to start
+        while this returns a path; additional working dirs are optional and
+        never block. The raw path is returned for display and filesystem use.
+        """
+        if self.primary_cwd and not os.path.isdir(self.primary_cwd):
+            return self.primary_cwd
+        return None

chrys/foundation/net/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Network address classification primitives."""

chrys/foundation/net/address_class.py

@@ -0,0 +1,57 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Conservative public-address classification, shared by web capabilities."""
+
+from __future__ import annotations
+
+import socket
+from ipaddress import IPv4Address, IPv6Address, ip_address, ip_network
+
+_PROTOCOL_ASSIGNMENTS = ip_network("192.0.0.0/24")
+# RFC 6052's well-known NAT64 prefix, which carries only global IPv4 addresses.
+# The local-use 64:ff9b:1::/48 stays restricted: its IPv4 half may be private.
+_NAT64_WELL_KNOWN = ip_network("64:ff9b::/96")
+
+
+def is_restricted_address(value: str) -> bool:
+    """Reject non-global, multicast and IPv4-mapped restricted destinations."""
+    address = ip_address(value)
+    if isinstance(address, IPv4Address) and address in _PROTOCOL_ASSIGNMENTS:
+        return True
+    if isinstance(address, IPv6Address):
+        if address.ipv4_mapped is not None:
+            return is_restricted_address(str(address.ipv4_mapped))
+        # DNS64 answers with this prefix on an IPv6-only network, where every
+        # site resolves into it: it is as public as the IPv4 address it embeds.
+        if address in _NAT64_WELL_KNOWN:
+            return is_restricted_address(str(IPv4Address(int(address) & 0xFFFFFFFF)))
+        # Transition addresses must not smuggle a private IPv4 destination.
+        if address.sixtofour is not None or address.teredo is not None:
+            return True
+        # Deprecated site-local space (fec0::/10) still routes on some networks,
+        # yet Python classifies it as global.
+        if address.is_site_local:
+            return True
+    return not address.is_global or address.is_multicast or address.is_reserved
+
+
+def literal_address(host: str) -> str | None:
+    """Return the address *host* names without DNS, or None for a name DNS must answer.
+
+    Besides IP literals this reads the numeric IPv4 forms a resolver accepts in
+    place of a name (``2130706433``, ``0x7f.1``, ``127.1``), so a name handed
+    to someone else's resolver cannot reach an address it hides.
+    """
+    try:
+        return str(ip_address(host))
+    except ValueError:
+        pass
+    try:
+        return socket.inet_ntoa(socket.inet_aton(host))
+    except OSError, UnicodeError, ValueError:
+        return None
+
+
+def names_this_host(host: str) -> bool:
+    """RFC 6761: ``localhost`` and every name under it resolve to loopback."""
+    return host == "localhost" or host.endswith(".localhost")