iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/cli/headless.py

@@ -0,0 +1,223 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Runtime preparation, warnings and output primitives shared by headless commands."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import os
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from chrys.foundation.config.context import EvalContext
+from chrys.foundation.config.settings import (
+    HEADLESS_DEFAULT_MAX_TRANSIENT_RETRIES,
+    MAX_TRANSIENT_RETRIES_LIMIT,
+    Settings,
+)
+from chrys.foundation.config.settings_store import LoadedSettings, SettingsWarning
+from chrys.foundation.config.spec import ENV_SOURCES
+from chrys.foundation.config.warnings import settings_warning_events
+from chrys.foundation.events.types import Warning
+from chrys.foundation.i18n import Localizer, MessageRef, msg
+from chrys.foundation.i18n.formatting import format_message, sanitize_legacy_scalar
+from chrys.orchestration.startup import bootstrap_runtime
+
+_MAX_TRANSIENT_RETRIES_INVALID = msg(
+    "settings.max_transient_retries_invalid",
+    fallback=(
+        "Ignoring invalid CHRYS_MAX_TRANSIENT_RETRIES={raw}; "
+        "expected a non-negative integer and will use the frontend default."
+    ),
+)
+
+
+_MAX_TRANSIENT_RETRIES_CLAMPED = msg(
+    "settings.max_transient_retries_clamped",
+    fallback=("CHRYS_MAX_TRANSIENT_RETRIES={value} exceeds the limit of {limit}; clamping to {limit}."),
+)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class PreparedRuntime:
+    """Settings, localization, and warnings established by runtime preparation."""
+
+    loaded: LoadedSettings
+    localizer: Localizer
+    pending_warnings: list[Warning]
+
+    @property
+    def settings(self) -> Settings:
+        """The assembled settings, for callers that need nothing else."""
+        return self.loaded.settings
+
+
+_RETRY_KEY = "llm.retry.max_transient"
+
+
+def speaks_for_the_env_var(warning: SettingsWarning) -> bool:
+    """Whether this verdict gets the wording headless callers have been parsing.
+
+    Only where the value really is spelled ``CHRYS_MAX_TRANSIENT_RETRIES``.
+    The same key rejected in ``settings.yaml`` is a different thing for the
+    user to go and fix, and telling them to check an environment variable they
+    never set sends them looking in the wrong place. One predicate for both the
+    skip and the report below, so the two cannot drift into double-reporting a
+    warning or dropping one.
+    """
+    return warning.key == _RETRY_KEY and warning.origin.layer in ENV_SOURCES
+
+
+def retry_warning_ref(warning: SettingsWarning) -> MessageRef:
+    if warning.rejected:
+        return _MAX_TRANSIENT_RETRIES_INVALID.bind(raw=repr(warning.outcome.raw))
+    # ``outcome.value`` is the post-clamp value (50); this message reports what
+    # the user wrote ("999 exceeds the limit of 50"), so it binds the raw text.
+    return _MAX_TRANSIENT_RETRIES_CLAMPED.bind(
+        value=warning.outcome.raw.strip(),
+        limit=MAX_TRANSIENT_RETRIES_LIMIT,
+    )
+
+
+def prepare_runtime(*, restoring_session: bool = False) -> PreparedRuntime:
+    """Load environment, apply runtime patches, and prepare display state without writing stderr.
+
+    A ``--session`` restore loads its settings from the saved session's own
+    root, which need not be the process cwd — bootstrapping project-free keeps
+    the pending warnings from describing a repository the run doesn't live in.
+    A failed restore aborts the run outright, so no fallback session ever runs
+    on these project-free settings.
+    """
+    bootstrap = bootstrap_runtime(
+        dotenv_override=True,
+        configure_stdio=True,
+        eval_context=EvalContext(
+            frontend_default_max_transient_retries=HEADLESS_DEFAULT_MAX_TRANSIENT_RETRIES,
+        ),
+        project_root=None if restoring_session else Path(os.getcwd()),
+    )
+    localizer = Localizer("en")
+    # Every warning composed here is root-independent — environment and user
+    # layers, plus ``settle_session_root``'s verdict — so the list is right for
+    # a restored session too, whatever root it lives in. The target root's own
+    # additions (its project layer) are printed by ``run_command`` after the
+    # restore, as the delta over this list.
+    # This one key keeps its own wording, which predates the shared composer and
+    # is what headless callers have been parsing; everything else gets the
+    # generic message rather than being dropped.
+    pending_warnings = [
+        *bootstrap.warnings,
+        *settings_warning_events(bootstrap.loaded, skip=speaks_for_the_env_var),
+    ]
+
+    for warning in bootstrap.loaded.warnings:
+        if not speaks_for_the_env_var(warning):
+            continue
+        display_message = retry_warning_ref(warning)
+        pending_warnings.append(
+            Warning(
+                code="invalid_max_transient_retries",
+                message=format_message(display_message),
+                display_message=display_message,
+            )
+        )
+
+    return PreparedRuntime(
+        loaded=bootstrap.loaded,
+        localizer=localizer,
+        pending_warnings=pending_warnings,
+    )
+
+
+def configure_logging() -> None:
+    """Prevent library logs from writing to stderr by default in headless CLI mode."""
+    logging.basicConfig(handlers=[logging.NullHandler()])
+
+
+def write_error(
+    message: str, *, as_json: bool, code: str = "error", session_id: str | None = None, detail: str | None = None
+) -> None:
+    """Write one error to stderr; text mode puts *detail* (the raw error text) on an indented line below."""
+    if as_json:
+        payload = {"error": message, "code": code}
+        if session_id:
+            # Failed runs still persist their session; surfacing the id lets a
+            # batch runner locate and export the trajectory from JSON output
+            # alone.
+            payload["session_id"] = session_id
+        sys.stderr.write(json.dumps(payload, ensure_ascii=False))
+        sys.stderr.write("\n")
+        return
+    sys.stderr.write(f"Error: {sanitize_legacy_scalar(message)}\n")
+    if detail:
+        sys.stderr.write(f"  detail: {sanitize_legacy_scalar(detail)}\n")
+
+
+def write_warning(message: str, *, as_json: bool, code: str = "warning") -> None:
+    if as_json:
+        sys.stderr.write(json.dumps({"warning": message, "code": code}, ensure_ascii=False))
+        sys.stderr.write("\n")
+        return
+    sys.stderr.write(f"Warning: {sanitize_legacy_scalar(message)}\n")
+
+
+def write_warning_events(warnings: Iterable[Warning], localizer: Localizer, *, as_json: bool) -> None:
+    for warning in warnings:
+        if as_json:
+            message = warning.message
+        elif warning.display_message is not None:
+            message = localizer.render(warning.display_message)
+        else:
+            message = warning.message
+        write_warning(message, code=warning.code, as_json=as_json)
+
+
+def write_pending_warnings(runtime: PreparedRuntime, *, as_json: bool) -> None:
+    write_warning_events(runtime.pending_warnings, runtime.localizer, as_json=as_json)
+
+
+def restore_delta_warnings(loaded: LoadedSettings, pending: Iterable[Warning]) -> list[Warning]:
+    """Warnings the restored session's settings load adds over the bootstrap's.
+
+    The two loads share every root-independent layer (environment, user
+    document), so their verdicts overlap almost entirely; the delta is what
+    the project-free bootstrap could not see — the target root's project
+    layer and dormant project files. Comparing the composed events keeps the
+    overlap out while leaving the already-printed pending list — with its
+    settle verdict and its compatibility retry wording — untouched.
+    """
+    already = {(warning.code, warning.message) for warning in pending}
+    return [
+        warning
+        for warning in settings_warning_events(loaded, skip=speaks_for_the_env_var)
+        if (warning.code, warning.message) not in already
+    ]
+
+
+def reported_warning_keys(runtime: PreparedRuntime) -> set[tuple[str, str]]:
+    """``(code, message)`` of every pending warning, under both of its wordings.
+
+    The pending list reports the retry environment variable in its
+    compatibility wording, while a later settings load (an engine start, a
+    workflow's admission) composes the same verdict generically; progress
+    output counts either spelling as already reported.
+    """
+    keys = {(warning.code, warning.message) for warning in runtime.pending_warnings}
+    keys.update((warning.code, warning.message) for warning in settings_warning_events(runtime.loaded))
+    return keys
+
+
+def exception_message(exc: BaseException) -> str:
+    # KeyError's ``str()`` wraps the message in quotes; ``args[0]`` keeps it clean.
+    if isinstance(exc, KeyError) and exc.args:
+        return str(exc.args[0])
+    return str(exc) or type(exc).__name__
+
+
+def write_json(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+    sys.stdout.write("\n")

chrys/app/cli/launch_cwd.py

@@ -0,0 +1,42 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Check that the directory a command was launched from still exists.
+
+A shell can keep a directory as its cwd after it was deleted or moved. Every
+entry point resolves its workspace, ``.env`` and project settings against that
+directory, so each one checks it once after parsing its arguments (and after
+``-C`` changed into another directory), and stops with one clear line instead
+of a traceback from deep inside startup.
+"""
+
+from __future__ import annotations
+
+import os
+
+LAUNCH_CWD_MISSING_CODE = "working_dir_missing"
+
+
+def launch_cwd_missing_message(*, workdir_flag: bool, workdir: str = "") -> str | None:
+    """Return the error line when the process cwd no longer exists, else ``None``.
+
+    *workdir_flag* says whether the command accepts ``-C``, so the hint only
+    names options the user can actually pass. *workdir* is the ``-C`` value
+    given, if any: with the launch directory gone only an existing absolute
+    directory replaces it, because a relative one (``-C .``) resolves against
+    the missing directory.
+    """
+    try:
+        cwd = os.getcwd()
+    except OSError:
+        cwd = None
+    if cwd is not None and os.path.isdir(cwd):
+        return None
+    expanded = os.path.expanduser(workdir) if workdir else ""
+    if expanded and os.path.isabs(expanded) and os.path.isdir(expanded):
+        return None
+    hint = (
+        "cd to an existing directory or pass -C with an absolute path."
+        if workdir_flag
+        else "cd to an existing directory."
+    )
+    return f"The current directory no longer exists; {hint}"

chrys/app/cli/profiles.py

@@ -0,0 +1,298 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Profile discovery commands for the Chrys CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from chrys.app.cli import headless
+from chrys.app.cli.launch_cwd import LAUNCH_CWD_MISSING_CODE, launch_cwd_missing_message
+from chrys.foundation.branding import APP_COMMAND, APP_DISPLAY_NAME
+from chrys.foundation.config.settings import DEFAULT_AGENT_PROFILE, Settings
+from chrys.foundation.config.warnings import settings_warning_events
+from chrys.foundation.events.types import Warning
+from chrys.orchestration.startup import bootstrap_runtime
+from chrys.service.profiles.agents.registry import AgentProfileRegistry
+from chrys.service.profiles.agents.registry import resolve_profile_selector as resolve_agent_profile_selector
+from chrys.service.profiles.agents.schema import AgentProfile
+from chrys.service.profiles.models.registry import ModelProfileRegistry
+from chrys.service.profiles.models.resolver import resolve_profile_selector as resolve_model_profile_selector
+from chrys.service.profiles.models.schema import API_STYLE_CHAT_COMPLETIONS, ModelProfile
+
+
+@dataclass(frozen=True)
+class _AgentRow:
+    profile: AgentProfile
+    is_default: bool
+    source: str
+    model: str
+
+
+@dataclass(frozen=True)
+class _ModelRow:
+    profile: ModelProfile
+    is_active: bool
+    flags: str
+
+
+def build_agents_parser() -> argparse.ArgumentParser:
+    """Build the ``chrys agents`` parser."""
+    parser = argparse.ArgumentParser(
+        prog=f"{APP_COMMAND} agents",
+        description=f"List {APP_DISPLAY_NAME} agent profiles that can be selected with --agent.",
+        add_help=False,
+    )
+    parser.add_argument(
+        "-h", "--help", action="help", default=argparse.SUPPRESS, help="Show this help message and exit"
+    )
+    parser.add_argument("command", nargs="?", choices=["list"], default="list", help=argparse.SUPPRESS)
+    parser.add_argument("--json", action="store_true", help="Emit JSON output")
+    return parser
+
+
+def build_models_parser() -> argparse.ArgumentParser:
+    """Build the ``chrys models`` parser."""
+    parser = argparse.ArgumentParser(
+        prog=f"{APP_COMMAND} models",
+        description=f"List {APP_DISPLAY_NAME} model profiles that can be selected with --model.",
+        add_help=False,
+    )
+    parser.add_argument(
+        "-h", "--help", action="help", default=argparse.SUPPRESS, help="Show this help message and exit"
+    )
+    parser.add_argument("command", nargs="?", choices=["list"], default="list", help=argparse.SUPPRESS)
+    parser.add_argument("--json", action="store_true", help="Emit JSON output")
+    return parser
+
+
+def agents_main(argv: list[str] | None = None) -> int:
+    """Entry point for ``chrys agents``."""
+    parser = build_agents_parser()
+    args = parser.parse_args(argv)
+    _ = args.command
+    if _launch_cwd_missing(as_json=args.json):
+        return 1
+
+    settings = _prepare_runtime()
+    agent_registry = AgentProfileRegistry()
+    model_registry = ModelProfileRegistry()
+    agent_registry.load_all()
+    model_registry.load_all()
+
+    profiles = sorted(
+        agent_registry.list_profiles(include_sub_agent_only=True),
+        key=lambda profile: profile.name.casefold(),
+    )
+    default_name = _default_agent_name(profiles, settings)
+    rows = [
+        _AgentRow(
+            profile=profile,
+            is_default=profile.name == default_name,
+            source="builtin" if agent_registry.is_builtin(profile.name) else "user",
+            model=_agent_model_label(profile, model_registry),
+        )
+        for profile in profiles
+    ]
+
+    if args.json:
+        _write_json({"agents": [_agent_payload(row) for row in rows], "default": default_name})
+        return 0
+
+    _print_agents(rows)
+    return 0
+
+
+def models_main(argv: list[str] | None = None) -> int:
+    """Entry point for ``chrys models``."""
+    parser = build_models_parser()
+    args = parser.parse_args(argv)
+    _ = args.command
+    if _launch_cwd_missing(as_json=args.json):
+        return 1
+
+    settings = _prepare_runtime()
+    registry = ModelProfileRegistry()
+    registry.load_all()
+
+    active = resolve_model_profile_selector(registry, settings.model_profile) if settings.model_profile else None
+    active_id = active.id if active is not None else ""
+    profiles = sorted(registry.list_profiles(), key=lambda profile: (profile.name.casefold(), profile.id))
+    rows = [
+        _ModelRow(profile=profile, is_active=profile.id == active_id, flags=_model_flags(profile))
+        for profile in profiles
+    ]
+
+    if args.json:
+        _write_json({"models": [_model_payload(row) for row in rows], "active": active_id})
+        return 0
+
+    _print_models(rows)
+    return 0
+
+
+def _prepare_runtime() -> Settings:
+    bootstrap = bootstrap_runtime(dotenv_override=True, configure_stdio=True, setup_telemetry=False)
+    for warning in (*bootstrap.warnings, *settings_warning_events(bootstrap.loaded)):
+        _write_warning(warning)
+    return bootstrap.settings
+
+
+def _launch_cwd_missing(*, as_json: bool) -> bool:
+    """Report a launch directory that no longer exists; ``True`` when the command must stop."""
+    message = launch_cwd_missing_message(workdir_flag=False)
+    if message is None:
+        return False
+    headless.write_error(message, as_json=as_json, code=LAUNCH_CWD_MISSING_CODE)
+    return True
+
+
+def _write_warning(warning: Warning) -> None:
+    sys.stderr.write(f"Warning: {warning.message}\n")
+
+
+def _default_agent_name(profiles: list[AgentProfile], settings: Settings) -> str:
+    profiles = [profile for profile in profiles if profile.acp is None and not profile.sub_agent_only]
+    requested = settings.default_agent.strip() or DEFAULT_AGENT_PROFILE
+    profile = resolve_agent_profile_selector(profiles, requested)
+    if profile is not None:
+        return profile.name
+    if requested != DEFAULT_AGENT_PROFILE:
+        profile = resolve_agent_profile_selector(profiles, DEFAULT_AGENT_PROFILE)
+        if profile is not None:
+            return profile.name
+    return profiles[0].name if profiles else ""
+
+
+def _agent_model_label(profile: AgentProfile, registry: ModelProfileRegistry) -> str:
+    profile_id = profile.model.profile_id
+    if not profile_id:
+        return "active"
+    model = registry.get(profile_id)
+    if model is None:
+        return f"missing:{profile_id}"
+    return model.name
+
+
+def _model_flags(profile: ModelProfile) -> str:
+    flags: list[str] = []
+    if profile.stream:
+        flags.append("stream")
+    if profile.vision:
+        flags.append("vision")
+    return ", ".join(flags) if flags else "-"
+
+
+def _format_context(tokens: int) -> str:
+    if tokens >= 1_000_000 and tokens % 1_000_000 == 0:
+        return f"{tokens // 1_000_000}m"
+    if tokens >= 1_000 and tokens % 1_000 == 0:
+        return f"{tokens // 1_000}k"
+    return str(tokens)
+
+
+def _format_api_style(api_style: str) -> str:
+    if api_style == API_STYLE_CHAT_COMPLETIONS:
+        return "chat"
+    return api_style
+
+
+def _write_json(payload: dict[str, object]) -> None:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False))
+    sys.stdout.write("\n")
+
+
+def _agent_payload(row: _AgentRow) -> dict[str, object]:
+    profile = row.profile
+    return {
+        "id": profile.id,
+        "name": profile.name,
+        "displayName": profile.display_name,
+        "description": profile.description,
+        "default": row.is_default,
+        "model": row.model,
+        "source": row.source,
+        "kind": "acp" if profile.acp is not None else "kernel",
+        "subAgentOnly": profile.sub_agent_only,
+        "launchableAsMain": profile.acp is None and not profile.sub_agent_only,
+    }
+
+
+def _model_payload(row: _ModelRow) -> dict[str, object]:
+    profile = row.profile
+    return {
+        "id": profile.id,
+        "name": profile.name,
+        "provider": profile.provider,
+        "apiStyle": profile.api_style,
+        "modelId": profile.model_id,
+        "maxContextTokens": profile.max_context_tokens,
+        "stream": profile.stream,
+        "vision": profile.vision,
+        "active": row.is_active,
+    }
+
+
+def _print_agents(rows: list[_AgentRow]) -> None:
+    console = Console(file=sys.stdout, highlight=False)
+    if not rows:
+        console.print(Text("No agent profiles found."))
+        return
+
+    table = Table(box=None, show_edge=False, pad_edge=False)
+    table.add_column("Default", no_wrap=True, justify="center")
+    table.add_column("Name", no_wrap=True)
+    table.add_column("Display Name", overflow="fold")
+    table.add_column("ID", no_wrap=True)
+    table.add_column("Model", overflow="fold")
+    table.add_column("Source", no_wrap=True)
+    table.add_column("Description", overflow="fold")
+    for row in rows:
+        profile = row.profile
+        table.add_row(
+            Text("*" if row.is_default else ""),
+            Text(profile.name),
+            Text(profile.display_name or "-"),
+            Text(profile.id or "-"),
+            Text(row.model),
+            Text(row.source),
+            Text(profile.description or "-"),
+        )
+    console.print(table)
+
+
+def _print_models(rows: list[_ModelRow]) -> None:
+    console = Console(file=sys.stdout, highlight=False)
+    if not rows:
+        console.print(Text("No model profiles found."))
+        return
+
+    table = Table(box=None, show_edge=False, pad_edge=False)
+    table.add_column("Active", no_wrap=True, justify="center")
+    table.add_column("ID", no_wrap=True)
+    table.add_column("Name", overflow="fold")
+    table.add_column("Provider", overflow="fold")
+    table.add_column("API", no_wrap=True)
+    table.add_column("Model", overflow="fold")
+    table.add_column("Context", no_wrap=True, justify="right")
+    table.add_column("Flags", overflow="fold")
+    for row in rows:
+        profile = row.profile
+        table.add_row(
+            Text("*" if row.is_active else ""),
+            Text(profile.id or "-"),
+            Text(profile.name),
+            Text(profile.provider or "-"),
+            Text(_format_api_style(profile.api_style) if profile.api_style else "-"),
+            Text(profile.model_id or "-"),
+            Text(_format_context(profile.max_context_tokens)),
+            Text(row.flags),
+        )
+    console.print(table)