iCode-TUI 0.29.1__py3-none-any.whl

chrys/orchestration/session_resources.py

@@ -0,0 +1,95 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared session identity, workspace, accounting and filesystem resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from chrys.service.context.compaction.spill import SpillQuota
+from chrys.service.session.runtime_metadata import SessionUsageMetadata
+from chrys.service.state.locks import ActiveSessionGuard
+from chrys.service.state.store import session_write_lock_path
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from chrys.foundation.models.workspace import Workspace
+    from chrys.service.hooks.manager import HookManager
+    from chrys.service.mutations.coordination import MutationCoordinator
+    from chrys.service.mutations.tracker import MutationTracker
+    from chrys.service.session.persistence import SessionPersistence
+
+
+class SessionResources[Metadata: SessionUsageMetadata]:
+    """Resources used by either mode; contains no conversation, turn or agent state."""
+
+    def __init__(
+        self,
+        *,
+        persistence: SessionPersistence,
+        runtime_meta: Metadata,
+        workspace: Workspace | None,
+        session_id: str | None = None,
+    ) -> None:
+        self._persistence = persistence
+        self.workspace = workspace
+        self.session_id: str | None = session_id
+        self.runtime_meta = runtime_meta
+        self.spill_quota = SpillQuota()
+        self.guard = ActiveSessionGuard(persistence.state_store)
+        self.mutation_tracker: MutationTracker | None = None
+        self.mutation_coordinator: MutationCoordinator | None = None
+        self.hook_manager: HookManager | None = None
+
+    def workspace_cwd(self) -> str:
+        """Return the current workspace cwd, falling back only before workspace initialization."""
+        if self.workspace is not None:
+            return self.workspace.primary_cwd
+        from chrys.foundation.platform import safe_getcwd
+
+        return safe_getcwd()
+
+    @property
+    def session_dir(self) -> Path | None:
+        """Return the session directory path, or ``None`` if no session is active.
+
+        Delegates to the state store when available so that tests using
+        ``tmp_path``-based stores write to the temp directory. Without a
+        store, fall back to the active sessions directory.
+        """
+        session_id = self.session_id
+        if not session_id:
+            return None
+        return self.session_dir_for(session_id)
+
+    def session_dir_for(self, session_id: str) -> Path:
+        """Resolve a session directory for an explicit, already-captured id."""
+        store = self._persistence.state_store
+        if store is not None:
+            return store.session_dir(session_id)
+        from chrys.foundation.config.settings import resolve_sessions_dir
+        from chrys.foundation.util.session_ids import session_short_id
+
+        return resolve_sessions_dir() / session_short_id(session_id)
+
+    def sessions_root_dir(self, session_id: str) -> Path | None:
+        """Return the sessions root used for lock files."""
+        store = self._persistence.state_store
+        if store is not None:
+            return store.session_dir(session_id).parent
+        from chrys.foundation.config.settings import resolve_sessions_dir
+
+        return resolve_sessions_dir()
+
+    def session_write_lock_path(self, session_id: str) -> Path | None:
+        sessions_dir = self.sessions_root_dir(session_id)
+        if sessions_dir is None:
+            return None
+        path = session_write_lock_path(sessions_dir, session_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def reset_spill_quota(self) -> None:
+        """Start a fresh engine-owned spill ledger for a newly opened session."""
+        self.spill_quota = SpillQuota()

chrys/orchestration/session_usage.py

@@ -0,0 +1,219 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session-wide usage accounting shared by Chat and Workflow execution owners."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Protocol
+
+from chrys.foundation.events.types import UsageUpdate
+from chrys.service.profiles.models.schema import DEFAULT_MAX_CONTEXT_TOKENS
+
+if TYPE_CHECKING:
+    from chrys.foundation.events.bus import EventBus
+    from chrys.service.session.runtime_metadata import SessionUsageMetadata
+
+
+class UsageSession(Protocol):
+    @property
+    def session_id(self) -> str | None: ...
+    @property
+    def runtime_meta(self) -> SessionUsageMetadata: ...
+
+
+class SessionUsagePublisher:
+    """Accumulate invocation spend without assuming a main agent or a context window."""
+
+    def __init__(self, *, bus: EventBus, session: UsageSession) -> None:
+        self._bus = bus
+        self._session = session
+        self._usage_tasks: set[asyncio.Task[None]] = set()
+        self._usage_publish_tail: asyncio.Task[None] | None = None
+
+    def make_usage_event(self, *, session_id: str | None = None) -> UsageUpdate:
+        identity = session_id or self._session.session_id
+        meta = self._session.runtime_meta
+        return UsageUpdate(
+            session_id=identity,
+            usage_source_id=identity or "",
+            total_session_tokens=meta.total_session_tokens,
+            total_session_input_tokens=meta.total_session_input_tokens,
+            total_session_output_tokens=meta.total_session_output_tokens,
+            total_session_cache_hit_tokens=meta.total_session_cache_hit_tokens,
+        )
+
+    @property
+    def tasks(self) -> set[asyncio.Task[None]]:
+        """The currently retained usage publications."""
+        return self._usage_tasks
+
+    @property
+    def tail(self) -> asyncio.Task[None] | None:
+        """The last publication in the ordered chain."""
+        return self._usage_publish_tail
+
+    def accumulate_invocation_usage(
+        self,
+        total_tokens: int,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        local_tokens: int = 0,
+        calibration_ratio: float = 1.0,
+        system_overhead_tokens: int = 0,
+        cache_hit_tokens: int | None = None,
+        max_context_tokens: int | None = None,
+        agent_profile: str = "",
+        usage_source_id: str = "",
+        authoritative_total: int | None = None,
+        use_local_context_estimate: bool = False,
+    ) -> None:
+        """Accumulate invocation spend and publish its live context reading.
+
+        ``local_tokens``, ``calibration_ratio``, ``system_overhead_tokens``, and
+        ``max_context_tokens`` come from this invocation's ContextManager/model.
+        They are copied only onto the live UsageUpdate. The session stores
+        cumulative spend; Chat's main-invocation context remains independent.
+        """
+        self._session.runtime_meta.accumulate_invocation_usage(
+            total_tokens,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_hit_tokens=cache_hit_tokens,
+            authoritative_total=authoritative_total,
+        )
+        # Each invocation may use a different model. A context percentage must
+        # use that invocation's window, including when it runs alongside a
+        # Chat agent with a different model. Use the caller's value or a
+        # neutral default when the backend has not reported its window.
+        max_ctx = DEFAULT_MAX_CONTEXT_TOKENS if max_context_tokens is None else max_context_tokens
+        window_input_tokens = local_tokens if use_local_context_estimate else input_tokens
+        window_total_tokens = window_input_tokens + output_tokens if use_local_context_estimate else total_tokens
+        pct = round(window_total_tokens / max_ctx * 100, 1) if max_ctx else 0.0
+        self.enqueue_usage_event(
+            UsageUpdate(
+                agent_profile=agent_profile,
+                usage_source_id=usage_source_id,
+                input_tokens=window_input_tokens,
+                output_tokens=output_tokens,
+                total_tokens=window_total_tokens,
+                pct=pct,
+                max_context_tokens=max_ctx,
+                total_session_tokens=self._session.runtime_meta.total_session_tokens,
+                total_session_input_tokens=self._session.runtime_meta.total_session_input_tokens,
+                total_session_output_tokens=self._session.runtime_meta.total_session_output_tokens,
+                total_session_cache_hit_tokens=self._session.runtime_meta.total_session_cache_hit_tokens,
+                cache_hit_tokens=cache_hit_tokens,
+                local_tokens=local_tokens,
+                calibration_ratio=calibration_ratio,
+                system_overhead_tokens=system_overhead_tokens,
+                session_id=self._session.session_id,
+            ),
+        )
+
+    def accumulate_side_call_usage(
+        self,
+        usage_details: Mapping[str, Any],
+        *,
+        agent_profile: str = "",
+        usage_source_id: str = "",
+        max_context_tokens: int | None = None,
+    ) -> None:
+        """Callback from Phase-4 LAST_WORDS generators — fold side-call spend into session totals.
+
+        Side-call responses are consumed inside the client and never reach the
+        middleware chain, so their provider-reported usage is fed here directly
+        — every attempt, including responses later rejected by validation or
+        the tool-call guard.  Accumulate-only: the parent's ``last_usage_details``
+        (context meter) stays untouched. A child source publishes its own
+        side-call window; unscoped callers refresh the main window unchanged.
+        """
+        from chrys.service.context.middleware.usage import extract_cache_hit_tokens
+
+        input_tokens = int(usage_details.get("input_token_count") or 0)
+        output_tokens = int(usage_details.get("output_token_count") or 0)
+        total_tokens = int(usage_details.get("total_token_count") or 0)
+        if not (input_tokens or output_tokens or total_tokens):
+            return
+        # Response usage_details carry the kernel-normalized cache field; raw
+        # provider keys (what extract_cache_hit_tokens reads) only as a fallback.
+        cache_hit_tokens = usage_details.get("cache_read_input_token_count")
+        if cache_hit_tokens is None:
+            cache_hit_tokens = extract_cache_hit_tokens(dict(usage_details))
+        if usage_source_id:
+            self.accumulate_invocation_usage(
+                total_tokens,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                cache_hit_tokens=int(cache_hit_tokens) if cache_hit_tokens is not None else None,
+                agent_profile=agent_profile,
+                usage_source_id=usage_source_id,
+                max_context_tokens=max_context_tokens,
+            )
+            return
+        self._session.runtime_meta.accumulate_out_of_band_usage(
+            total_tokens,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_hit_tokens=int(cache_hit_tokens) if cache_hit_tokens is not None else None,
+        )
+        self.enqueue_usage_event(self.make_usage_event())
+
+    def enqueue_usage_event(self, event: UsageUpdate) -> None:
+        """Keep usage publish tasks alive and deliver them in creation order."""
+        previous = self._usage_publish_tail
+
+        async def _publish_after_previous() -> None:
+            if previous is not None:
+                # ``gather(return_exceptions=True)`` waits for ``previous`` without
+                # inheriting its failure or cancellation, so a cancelled earlier
+                # publish cannot cascade-cancel every queued UsageUpdate behind it.
+                # ``contextlib.suppress(Exception)`` would not catch CancelledError
+                # (BaseException since 3.8), so the chain would otherwise unravel
+                # silently on shutdown.
+                await asyncio.gather(previous, return_exceptions=True)
+            await self._bus.publish(event)
+
+        task = asyncio.create_task(_publish_after_previous())
+        self._usage_publish_tail = task
+        self.track(task)
+
+    def clear_tail(self, task: asyncio.Task[None]) -> None:
+        if self._usage_publish_tail is task:
+            self._usage_publish_tail = None
+
+    def track(self, task: asyncio.Task[None]) -> None:
+        """Retain a usage publish and observe its completion."""
+        self._usage_tasks.add(task)
+        task.add_done_callback(self._usage_tasks.discard)
+        task.add_done_callback(self.clear_tail)
+        task.add_done_callback(_observe_task_exception)
+
+    async def drain(self) -> None:
+        """Await all pending UsageUpdate publish tasks.
+
+        Sub-agent ``_invoke`` calls this in its ``finally`` so the sub-agent's
+        trailing UsageUpdate is delivered before the parent's ToolCallResult.
+        Without it a slow subscriber can let the parent tool result overtake
+        the sub-agent's last usage event.
+        """
+        tail = self._usage_publish_tail
+        if tail is None:
+            return
+        await asyncio.gather(tail, return_exceptions=True)
+
+    async def settle(self) -> None:
+        """Finish retained publishes and clear their bookkeeping at shutdown."""
+        if self._usage_tasks:
+            await asyncio.gather(*tuple(self._usage_tasks), return_exceptions=True)
+        self._usage_tasks.clear()
+        self._usage_publish_tail = None
+
+
+def _observe_task_exception(task: asyncio.Task[None]) -> None:
+    if task.cancelled():
+        return
+    with contextlib.suppress(Exception):
+        task.exception()

chrys/orchestration/startup.py

@@ -0,0 +1,255 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Shared process bootstrap for Chrys entrypoints."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from chrys.foundation.config.context import EvalContext
+from chrys.foundation.config.process_settings import install_process_settings, settle_session_root
+from chrys.foundation.config.runtime_pointer import MODEL_POINTER_KEY, set_model_pointer
+from chrys.foundation.config.settings import Settings
+from chrys.foundation.config.settings_store import DEFAULT_EVAL_CONTEXT, LoadedSettings, load_settings
+from chrys.foundation.events.types import Warning
+from chrys.foundation.i18n import CatalogLoadWarning, CatalogWarningCode, msg
+from chrys.foundation.i18n.formatting import format_message
+
+logger = logging.getLogger(__name__)
+
+_INVALID_NO_PROXY_ENV = msg(
+    "startup.invalid_no_proxy_env",
+    fallback="{var} is invalid for httpx and was ignored ({value}). Remove or fix this environment value.",
+)
+_CATALOG_LOAD_FAILED = msg(
+    "i18n.catalog_load_failed",
+    fallback="Could not load translations for locale {locale}; using English.",
+)
+_RAW_HTTP_CAPTURE_ON = msg(
+    "startup.raw_http_capture_on",
+    fallback=(
+        "Raw HTTP capture is on ({source}): request and response logs record API keys, "
+        "prompts and model output unredacted. Turn it off when you are done."
+    ),
+)
+_SETTINGS_MIGRATION_FAILED = msg(
+    "startup.settings_migration_failed",
+    fallback=(
+        "Could not migrate settings into {path} ({error}). "
+        "Your existing configuration still applies; migration retries on the next start."
+    ),
+)
+# Deliberately not the sentence above: the legacy ``.env`` keeps loading as a
+# layer when its migration fails, so that configuration really does still
+# apply — but nothing reads the legacy notifications file any more, so a
+# failure there means the preferences in it are not in force at all.
+_NOTIFICATIONS_MIGRATION_FAILED = msg(
+    "startup.notifications_migration_failed",
+    fallback=(
+        "Could not migrate notification preferences into {path} ({error}). "
+        "This start uses the default notification settings; migration retries on the next start."
+    ),
+)
+
+
+@dataclass(frozen=True)
+class RuntimeBootstrap:
+    """Result of entrypoint runtime bootstrapping."""
+
+    loaded: LoadedSettings
+    warnings: list[Warning] = field(default_factory=list)
+
+    @property
+    def settings(self) -> Settings:
+        """The assembled settings, for callers that need nothing else."""
+        return self.loaded.settings
+
+
+def _dangerous_setting_warnings(loaded: LoadedSettings) -> list[Warning]:
+    """Say out loud what a dangerous switch is doing to this process.
+
+    Not a rejected value, so it never appears in ``LoadedSettings.warnings``:
+    the setting is valid, took effect, and that is the problem. Raw HTTP capture
+    writes API keys, prompts and model output to disk unredacted, and it
+    persists across restarts by design — someone who turned it on to chase one
+    bug should not find out months later that it never stopped.
+
+    Composed from the installed process values rather than the candidate
+    settings, because this field is ``Apply.RESTART``: a reload that changed it
+    would report a state this process is not in.
+    """
+    from chrys.foundation.config.process_settings import process_settings
+    from chrys.foundation.config.warnings import setting_source_label
+
+    if not process_settings().raw_http_capture:
+        return []
+    key = "log.raw_http_capture"
+    display_message = _RAW_HTTP_CAPTURE_ON.bind(source=setting_source_label(key, loaded.source_for(key)))
+    return [
+        Warning(
+            code="raw_http_capture_on",
+            message=format_message(display_message),
+            display_message=display_message,
+        )
+    ]
+
+
+def _migrate_legacy_settings() -> list[Warning]:
+    """Run the legacy-source imports, reporting rather than failing the boot.
+
+    A migration that cannot run — a stuck lock, a full disk — leaves the world
+    exactly as the previous version ran in it: the legacy source still loads
+    the way it always did, and the untouched ledger retries next start. That
+    is a degraded state worth a warning, never a reason chrys does not open.
+    Each component runs independently, so one failing does not hold back the
+    other.
+
+    The theme rename is a rewrite inside the document, not an import, and the
+    loader follows the rename whatever the document says — so a rewrite that
+    cannot happen degrades nothing, and is logged rather than reported.
+    """
+    from chrys.foundation.config.migrations import (
+        migrate_dotenv_v0,
+        migrate_notifications_v0,
+        migrate_renamed_theme,
+    )
+    from chrys.foundation.config.user_settings import user_settings_path
+    from chrys.foundation.config.warnings import migration_warning_events
+
+    warnings: list[Warning] = []
+    components = (
+        (migrate_dotenv_v0, _SETTINGS_MIGRATION_FAILED, "settings_migration_failed"),
+        (migrate_notifications_v0, _NOTIFICATIONS_MIGRATION_FAILED, "notifications_migration_failed"),
+    )
+    for migrate, failure, code in components:
+        try:
+            migration = migrate()
+        except Exception as error:
+            display_message = failure.bind(path=str(user_settings_path()), error=str(error))
+            warnings.append(
+                Warning(
+                    code=code,
+                    message=format_message(display_message),
+                    display_message=display_message,
+                )
+            )
+            continue
+        warnings.extend(migration_warning_events(migration.warnings))
+    try:
+        migrate_renamed_theme()
+    except Exception:
+        logger.info("Could not rename the saved theme in %s", user_settings_path(), exc_info=True)
+    return warnings
+
+
+def catalog_load_warning(warning: CatalogLoadWarning) -> Warning:
+    """Compose a catalog-load failure for a root's normal warning route."""
+    display_message = _CATALOG_LOAD_FAILED.bind(locale=warning.requested_locale)
+    return Warning(
+        code=str(CatalogWarningCode.LOAD_FAILED),
+        message=format_message(display_message),
+        display_message=display_message,
+    )
+
+
+def configure_utf8_stdio() -> None:
+    """Force UTF-8 for this process and spawned subprocesses."""
+    os.environ.setdefault("PYTHONUTF8", "1")
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            with contextlib.suppress(Exception):
+                reconfigure(encoding="utf-8", errors="replace")
+
+
+def set_process_title(title: str = "chrys") -> None:
+    """Set the visible process title when the optional platform support works."""
+    try:
+        from setproctitle import setproctitle
+    except Exception:
+        return
+
+    with contextlib.suppress(Exception):
+        setproctitle(title)
+
+
+def bootstrap_runtime(
+    *,
+    dotenv_override: bool,
+    dotenv_cwd: str | os.PathLike[str] | None = None,
+    configure_stdio: bool = False,
+    apply_patches: bool = True,
+    setup_telemetry: bool = True,
+    eval_context: EvalContext = DEFAULT_EVAL_CONTEXT,
+    project_root: Path | None = None,
+) -> RuntimeBootstrap:
+    """Load environment, apply process patches, and build settings.
+
+    Args:
+        eval_context: The frontend's own policy, passed *into* the load rather
+            than substituted afterwards. ``chrys run`` raises the transient
+            retry default, and that number is an input to the project layer's
+            tighten/loosen verdicts — replacing it after the fact would arrive
+            after the decisions it informs.
+        project_root: The workspace root whose project trust domain the loaded
+            settings live under. The TUI and ``chrys run`` pass their working
+            directory — except a ``chrys run --session`` restore, which passes
+            nothing because the saved session's own root is the one the restore
+            loads from; the ACP manager passes nothing — its base settings are
+            deliberately project-free because each session derives its own
+            root, and a manager-level project layer would leak one session's
+            trust decisions into every other.
+    """
+    set_process_title()
+
+    if configure_stdio:
+        configure_utf8_stdio()
+
+    from chrys.foundation.config.env_file import config_env_path
+    from chrys.foundation.config.env_layers import freeze_process_env, inject_bootstrap_dotenv
+    from chrys.service.profiles.models.env_bridge import sanitize_no_proxy_env
+
+    # The snapshot must predate the injection below: it is the "real shell
+    # environment" every later settings load resolves against.
+    freeze_process_env()
+    inject_bootstrap_dotenv(
+        [Path(dotenv_cwd if dotenv_cwd is not None else os.getcwd()) / ".env", config_env_path()],
+        override=dotenv_override,
+    )
+
+    warnings = [
+        Warning(
+            code="invalid_no_proxy",
+            message=f"{var} is invalid for httpx and was ignored ({value!r}). Remove or fix this environment value.",
+            display_message=_INVALID_NO_PROXY_ENV.bind(var=var, value=repr(value)),
+        )
+        for var, value in sanitize_no_proxy_env().items()
+    ]
+    warnings.extend(_migrate_legacy_settings())
+
+    if apply_patches:
+        from chrys.foundation.patches import apply_all
+
+        apply_all()
+
+    loaded = settle_session_root(load_settings(project_root=project_root, eval_context=eval_context))
+    install_process_settings(loaded)
+    # Seed the live model pointer with the layered verdict, origin intact —
+    # never an unconditional overwrite: when the shell exported a value, that
+    # value IS the verdict, so the write is a no-op and the origin stays ENV.
+    if loaded.settings.model_profile:
+        set_model_pointer(loaded.settings.model_profile, origin=loaded.source_for(MODEL_POINTER_KEY))
+    warnings.extend(_dangerous_setting_warnings(loaded))
+
+    if setup_telemetry:
+        from chrys.foundation.observability.setup import setup_otel
+
+        setup_otel(loaded.settings)
+
+    return RuntimeBootstrap(loaded=loaded, warnings=warnings)

chrys/orchestration/sub_agents/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Sub-agent runtime orchestration."""