iCode-TUI 0.29.1__py3-none-any.whl

chrys/service/hooks/schema.py

@@ -0,0 +1,407 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Dataclass schema for the on-disk hooks config.
+
+The on-disk shape is::
+
+    version: 1
+    settings:
+      shutdown_grace_seconds: 5
+      max_parallel_hooks: 4
+    hooks:
+      - id: ...
+        event: before_tool_call
+        enabled: true
+        match: { ... }
+        run: { type: script, path: ..., ... }
+        execution: { mode: blocking, timeout_seconds: 10, ... }
+
+YAML and JSON parse to the same intermediate dict; loaders in
+:mod:`chrys.service.hooks.loader` convert that dict into these dataclasses and
+validate combinations (e.g. ``mode: blocking`` + ``detach: true`` is
+rejected at load time).
+
+These classes are deliberately validation-only: they carry no runtime
+behaviour.  :mod:`chrys.service.hooks.runner` and :mod:`chrys.service.hooks.manager`
+operate on instances.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from chrys.service.hooks.events import HookEvent
+
+# ---------------------------------------------------------------------------
+# Matcher
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HookArgMatch:
+    """Operator-tagged matcher for a single tool-call argument.
+
+    All three fields are optional and combine with AND.  ``regex`` is
+    compiled lazily by :mod:`chrys.service.hooks.matcher` and cached on the
+    instance.
+    """
+
+    equals: str | None = None
+    contains: str | None = None
+    regex: str | None = None
+    _compiled_regex: Any = field(default=None, init=False, repr=False, compare=False)
+    _regex_compiled: bool = field(default=False, init=False, repr=False, compare=False)
+
+
+@dataclass
+class HookMatch:
+    """Optional matcher clause.
+
+    All set clauses combine with AND.  ``profiles`` is the any-of form;
+    ``profile`` is the singular form, kept because it reads better when
+    you only care about one profile.
+
+    Tool clauses require a tool payload.  If ``tool_kind``, ``tool_name``,
+    or ``args`` is set on an event that does not carry ``tool``, the hook
+    does not match.
+    """
+
+    profile: str | None = None
+    profiles: list[str] = field(default_factory=list)
+    tool_kind: str | None = None
+    tool_name: str | None = None
+    args: dict[str, HookArgMatch] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Run / Execution
+# ---------------------------------------------------------------------------
+
+HookRunType = Literal["script", "command", "shell"]
+"""``script``: file path, interpreter inferred from extension (matches
+:class:`chrys.service.skills.runner.SubprocessScriptRunner`).
+``command``: explicit argv list, no shell.
+``shell``: a single shell-syntax string, executed via the user's shell
+(intended for one-liners; use sparingly — argv is safer).
+"""
+
+HookExecutionMode = Literal["blocking", "async", "fire_and_forget"]
+"""See :mod:`chrys.service.hooks.manager` for the wait semantics each mode
+implies.  Combined with :attr:`HookExecution.detach` and
+:attr:`HookExecution.delivery` to express the full "must this survive
+chrys exit / must we never lose it" matrix.
+"""
+
+HookDelivery = Literal["best_effort", "durable"]
+"""``durable`` writes a pending-job file to the outbox before spawning
+the subprocess; the runner moves it to ``done/`` on success or
+``failed/`` on non-zero exit.  On chrys startup the manager scans
+``pending/`` and retries stale entries.  ``best_effort`` skips the
+outbox dance entirely.  Blocking hooks are awaited inline and therefore
+do not use the outbox even when configured as ``durable``.
+"""
+
+HookErrorPolicy = Literal["block", "warn", "ignore"]
+"""``block``: a non-zero exit (or timeout) on a ``blocking`` hook denies
+a gated event and surfaces the hook's stderr.  ``warn``: log a warning,
+allow the action.  ``ignore``: log at debug only.  For non-blocking
+hooks and non-gated events, ``block`` falls back to ``warn`` — there's
+nothing to gate.
+"""
+
+
+@dataclass
+class HookRun:
+    """What to run and where."""
+
+    type: HookRunType
+    """``script`` | ``command`` | ``shell``."""
+
+    path: str = ""
+    """Path to the script file.  Required when ``type == 'script'``.
+
+    When loaded from disk, relative paths are resolved against the
+    directory containing the hooks file, so both global and project
+    hook files can keep scripts next to ``hooks.yaml``. Interpreter is
+    inferred from the extension (see ``chrys/service/skills/runner.py``).
+    """
+
+    argv: list[str] = field(default_factory=list)
+    """Explicit argv.  Required when ``type == 'command'``."""
+
+    shell: str = ""
+    """Single shell-syntax string.  Required when ``type == 'shell'``."""
+
+    args: list[str] = field(default_factory=list)
+    """Extra positional arguments appended after the interpreter +
+    script path (``type: script``) or after ``argv`` (``type: command``).
+    Ignored for ``type: shell`` — the string is opaque to chrys.
+    """
+
+    env: dict[str, str] = field(default_factory=dict)
+    """Extra env vars; merged over Chrys's sanitized parent process env."""
+
+    cwd: str = ""
+    """Working directory.  Supports template vars: ``${workspace_cwd}``,
+    ``${chrys_home}``, ``${session_id}``, ``${profile}``.  Empty falls
+    back to the workspace cwd.
+    """
+
+
+@dataclass
+class HookExecution:
+    """Wait / lifetime / delivery semantics for this hook."""
+
+    mode: HookExecutionMode = "fire_and_forget"
+    """How chrys waits for the subprocess.  See :data:`HookExecutionMode`."""
+
+    detach: bool = False
+    """Detach the subprocess from chrys's process group (POSIX:
+    ``setsid``; Windows: ``CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS``)
+    so it survives chrys exit.  Stdio is redirected to a log file under
+    ``<config_dir>/hooks/logs/``.
+
+    Only meaningful with ``mode: fire_and_forget`` — the load-time
+    validator rejects ``detach: true`` paired with ``blocking`` or
+    ``async`` (chrys would deadlock waiting on a process it can't read).
+    """
+
+    delivery: HookDelivery = "best_effort"
+    """``durable`` writes a job file to the outbox before spawning, so a
+    crash between spawn and completion lets the next chrys startup
+    retry.  Requires hooks to be idempotent.  Applies only to
+    non-blocking hook modes; blocking hooks are already fully observed by
+    the caller.
+    """
+
+    timeout_seconds: float = 30.0
+    """Hard timeout for ``blocking``, ``async``, and non-detached
+    ``fire_and_forget`` modes.  Ignored for detached hooks because the
+    detached worker owns the child after Chrys exits.
+    """
+
+    on_error: HookErrorPolicy = "warn"
+    """What to do when the hook fails (non-zero exit or timeout).  See
+    :data:`HookErrorPolicy`.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Top-level hook config
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HookConfig:
+    """A single hook entry from ``hooks.yaml``."""
+
+    id: str
+    """Stable identifier used in logs and durable outbox job metadata.
+
+    IDs must be unique within one file. Same-id hooks across project and
+    global files are allowed by the merged loader and both hooks run.
+    """
+
+    event: HookEvent
+    """Which lifecycle point triggers this hook."""
+
+    run: HookRun
+    """What to execute."""
+
+    execution: HookExecution = field(default_factory=HookExecution)
+    """Wait / lifetime / delivery semantics."""
+
+    match: HookMatch = field(default_factory=HookMatch)
+    """Filter — omit to fire on every event of this type."""
+
+    enabled: bool = True
+    """Set to ``false`` to keep the entry around without firing it.
+    Cheaper than deleting + re-adding.
+    """
+
+    description: str = ""
+    """Free-form description.  Surfaced in the future ``/hooks`` TUI
+    screen; ignored at runtime.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Top-level settings + file
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HookSettings:
+    """File-level knobs (apply to all hooks in the same file)."""
+
+    shutdown_grace_seconds: float = 5.0
+    """Upper bound on how long :meth:`HookManager.drain_session` waits
+    for in-flight ``async`` hooks at shutdown.  ``fire_and_forget`` and
+    detached hooks are never waited on.
+    """
+
+    max_parallel_hooks: int = 4
+    """Cap on how many subprocesses the manager will keep alive at once.
+    Additional dispatches queue until a slot frees.  Detached hooks
+    don't count toward the cap.
+    """
+
+    outbox_retry_age_seconds: float = 60.0
+    """On startup, ``pending/`` entries older than this are eligible for
+    retry.  Younger entries are left alone (assumed to be in-flight from
+    another chrys instance — unlikely but cheap to handle).
+    """
+
+    outbox_max_retries: int = 3
+    """Each pending entry tracks its retry count; entries that hit this
+    cap are moved straight to ``failed/`` on the next startup.
+    """
+
+
+@dataclass
+class HooksFile:
+    """In-memory representation of a parsed ``hooks.yaml`` / ``hooks.json``."""
+
+    version: int = 1
+    settings: HookSettings = field(default_factory=HookSettings)
+    settings_overrides: set[str] = field(default_factory=set)
+    """Names of settings fields explicitly present in the source file."""
+    hooks: list[HookConfig] = field(default_factory=list)
+    skipped_hooks: list[SkippedHook] = field(default_factory=list)
+    """Hooks left out of :attr:`hooks` because their configuration can never
+    work; the rest of the file still loads.  Reported to the user at session
+    start.
+    """
+    source: str = ""
+    """Path the file was loaded from; empty for synthetic configs.  Used
+    in log messages and the future ``/hooks`` screen.
+    """
+
+
+@dataclass(frozen=True)
+class SkippedHook:
+    """A hook the loader left out, and why (English, names the offending field)."""
+
+    id: str
+    reason: str
+
+
+# ---------------------------------------------------------------------------
+# Runtime decision
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class HookDecision:
+    """Aggregated outcome of all blocking hooks for a single event.
+
+    Returned by :meth:`HookManager.fire`.  The caller (middleware /
+    engine) inspects :attr:`blocked` first; if false, applies
+    :attr:`args_override`, then queues :attr:`system_reminders` and
+    :attr:`extra_context` for downstream consumption.
+
+    Each caller applies only the fields meaningful for its event.  For
+    example, ``after_tool_call`` consumes :attr:`extra_context` but ignores
+    :attr:`blocked`, while pure observer events such as ``session_end``
+    ignore the return value entirely.
+    """
+
+    blocked: bool = False
+    """A blocking hook returned ``action: block`` for a gated event.  The
+    caller should short-circuit and report :attr:`block_reason` to the model
+    / user.
+    """
+
+    block_reason: str = ""
+    """Reason text from the first hook that blocked, with the hook id
+    prefixed for traceability.
+    """
+
+    args_override: dict[str, Any] | None = None
+    """When set, merges over ``context.arguments`` before the inner tool
+    runs.  Multiple blocking hooks with ``action: modify`` merge
+    left-to-right (later hook wins on conflict); whoever wrote the file
+    is on the hook to order them deliberately.  Non-blocking hook
+    decisions are ignored because their subprocess may finish after the
+    gated action has already continued.
+    """
+
+    system_reminders: list[str] = field(default_factory=list)
+    """Text to inject as ``<system-reminder>`` blocks.  Used by
+    ``user_prompt_submit`` hooks.
+    """
+
+    extra_context: list[str] = field(default_factory=list)
+    """Text to append to textual tool results (``after_tool_call``) or
+    surface to the user.  Kept distinct from :attr:`system_reminders`
+    because the consumers are different.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Multi-source merge
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class MergedHooksFile:
+    """Combined view of a project-level and a global-level :class:`HooksFile`.
+
+    Produced by :func:`chrys.service.hooks.loader.merge_hooks_files`. Exposes the
+    same ``hooks`` and ``settings`` attributes as :class:`HooksFile` so the
+    existing :class:`HookManager` consumes it without code changes (duck
+    typing). The ``project`` and ``global_`` fields are kept for logging,
+    debugging, and the future ``/hooks`` TUI screen.
+
+    Ordering: ``hooks`` is project entries first (in project YAML order),
+    then global entries (in global YAML order). The "first block
+    short-circuits" rule applies to this combined list as a single chain,
+    so a project block ends the chain before any global hook runs.
+    """
+
+    project: HooksFile | None = None
+    """The project-side :class:`HooksFile`, or ``None`` if no project file
+    was found or it failed to load."""
+
+    global_: HooksFile | None = None
+    """The global-side :class:`HooksFile`, or ``None`` if no global file
+    was found (the existing single-source case)."""
+
+    settings: HookSettings = field(default_factory=HookSettings)
+    """Per-field merge: project wins, then global, then defaults."""
+
+    hooks: list[HookConfig] = field(default_factory=list)
+    """Combined hook list, project first then global. Empty when both
+    sources are absent."""
+
+    sources: list[str] = field(default_factory=list)
+    """Source paths included in this merge, in order. Empty when neither
+    source was found. Used for log lines and the TUI screen; not used
+    for any decision logic."""
+
+    @classmethod
+    def from_single(cls, file: HooksFile, *, as_project: bool = False) -> MergedHooksFile:
+        """Wrap a single :class:`HooksFile` as a :class:`MergedHooksFile`.
+
+        Used by the manager to normalize the single-source case (legacy
+        global-only setups) into the merged view, so the manager never
+        has to branch on input type. ``as_project=True`` treats the file
+        as the project side; default treats it as the global side.
+        """
+        wrapped: HooksFile | None = file
+        return cls(
+            project=wrapped if as_project else None,
+            global_=None if as_project else wrapped,
+            settings=file.settings,
+            hooks=list(file.hooks),
+            sources=[file.source] if file.source else [],
+        )
+
+    @property
+    def source(self) -> str:
+        """Synthetic source label for compatibility with the manager's
+        logging helpers. Format: ``"<project> + <global>"``, ``"<project>"``,
+        ``"<global>"``, or ``""`` when neither source is present."""
+        parts = [p.source for p in (self.project, self.global_) if p is not None and p.source]
+        return " + ".join(parts)

chrys/service/llm/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""LLM abstraction — client factory and model registry."""
+
+from chrys.service.llm.clients import create_client
+
+__all__ = ["create_client"]

chrys/service/llm/_structured_outputs.py

@@ -0,0 +1,192 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Helpers shared by the Chat Completions and Responses wire clients for OpenAI Structured Outputs.
+
+Includes strict-schema compatibility, schema materialization, fine-tuned-model
+constraint rejection, and response-format name sanitisation.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Mapping
+from typing import Any
+
+from openai.lib._pydantic import _ensure_strict_json_schema
+
+logger = logging.getLogger(__name__)
+
+# Structured-output schema names have a stricter, ASCII-only rule than the
+# Chat Completions author-name field: [A-Za-z0-9_-], max 64 chars.
+_INVALID_RESPONSE_FORMAT_NAME_CHARS_RE = re.compile(r"[^A-Za-z0-9_-]+")
+
+
+def _sanitize_response_format_name(name: object) -> str:
+    """Sanitize a response-format schema name; fall back to ``"response"``."""
+    sanitized = _INVALID_RESPONSE_FORMAT_NAME_CHARS_RE.sub("", str(name)) if name is not None else ""
+    return sanitized[:64] or "response"
+
+
+# Composition and dependency keywords Structured Outputs rejects under strict
+# mode. anyOf is the supported one; single-entry allOf is inlined away by the
+# strictifier, so any allOf that remains is the unsupported multi-entry form.
+# The dependent* keywords need flagging by name: their values hold property
+# names or arbitrary subschemas, which the object-closure leg cannot detect.
+_STRICT_UNSUPPORTED_COMPOSITION_KEYWORDS = frozenset(
+    {"allOf", "oneOf", "not", "if", "then", "else", "dependentRequired", "dependentSchemas"}
+)
+
+
+def _strict_schema_branch_incompatible(schema: Any) -> bool:
+    """Return whether a strictified tree still contains strict-incompatible branches.
+
+    The SDK strictifier only traverses keywords it supports (``properties``,
+    ``items``, ``anyOf``, single-entry ``allOf``, ``$defs``), so objects
+    inside anything else stay open — and the unsupported composition
+    keywords are rejected by strict mode even with closed members. Flag all
+    four shapes: a remaining unsupported composition keyword, an
+    object-typed node not explicitly closed with ``additionalProperties:
+    false`` (the strictifier closes every object it actually visits), an
+    object-typed node whose ``required`` does not list exactly its
+    ``properties`` (strict mode demands every field be required, and the
+    strictifier stamps that only on objects it visits — an untraversed
+    object can arrive pre-closed but under-required), and any other
+    explicitly non-false ``additionalProperties``. The walk is
+    deliberately context-blind — a literal property *named* like a keyword
+    can false-positive — because the only cost is falling back to
+    non-strict.
+    """
+    if isinstance(schema, Mapping):
+        schema_type = schema.get("type")
+        is_object_typed = schema_type == "object" or (isinstance(schema_type, list) and "object" in schema_type)
+        if is_object_typed:
+            if schema.get("additionalProperties") is not False:
+                return True
+            properties = schema.get("properties")
+            if isinstance(properties, Mapping):
+                required = schema.get("required")
+                # Entries must be vetted before the set comparison: set()
+                # raises on unhashable entries, and set equality alone would
+                # let duplicate names satisfy the completeness check.
+                if (
+                    not isinstance(required, list)
+                    or len(required) != len(properties)
+                    or not all(isinstance(entry, str) for entry in required)
+                    or set(required) != set(properties)
+                ):
+                    return True
+        return any(
+            key in _STRICT_UNSUPPORTED_COMPOSITION_KEYWORDS
+            or (key == "additionalProperties" and value is not False)
+            or _strict_schema_branch_incompatible(value)
+            for key, value in schema.items()
+        )
+    if isinstance(schema, list):
+        return any(_strict_schema_branch_incompatible(item) for item in schema)
+    return False
+
+
+def _strict_mode_incompatible(schema: Mapping[str, Any]) -> bool:
+    """Return whether a strictified tree still violates the strict-mode contract.
+
+    The SDK strictifier transforms but does not certify: Structured Outputs
+    additionally requires the root to be an object schema without a
+    root-level ``anyOf``, and non-object, type-less, and root-``anyOf``
+    inputs all pass through it unchanged. Any violation falls back to
+    non-strict rather than 400 on the wire.
+    """
+    if schema.get("type") != "object" or "anyOf" in schema:
+        return True
+    return _strict_schema_branch_incompatible(schema)
+
+
+def _materialize_json_structure(value: Any) -> Any:
+    """Recursively materialize mappings and sequences into plain containers.
+
+    The schema copier where ``copy.deepcopy`` would fail: read-only views
+    such as ``MappingProxyType`` are not deep-copyable (deepcopy falls back
+    to pickling them, which raises), and callers hand schemas nested inside
+    frozen structures. Mappings become dicts, lists and tuples become lists;
+    scalars are shared — JSON-shaped schema leaves are immutable, and the
+    in-place strictifier only ever mutates containers.
+    """
+    if isinstance(value, Mapping):
+        return {key: _materialize_json_structure(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_materialize_json_structure(item) for item in value]
+    return value
+
+
+_FINE_TUNED_MODEL_PREFIX = "ft:"
+
+# Constraint keywords Structured Outputs accepts on base models but rejects
+# on fine-tuned ones: string bounds/pattern/format, number bounds, array
+# bounds, and patternProperties.
+_FINE_TUNE_UNSUPPORTED_CONSTRAINT_KEYWORDS = frozenset(
+    {
+        "minLength",
+        "maxLength",
+        "pattern",
+        "format",
+        "minimum",
+        "maximum",
+        "multipleOf",
+        "patternProperties",
+        "minItems",
+        "maxItems",
+    }
+)
+
+
+def _contains_fine_tune_unsupported_keyword(schema: Any) -> bool:
+    if isinstance(schema, Mapping):
+        return any(
+            key in _FINE_TUNE_UNSUPPORTED_CONSTRAINT_KEYWORDS or _contains_fine_tune_unsupported_keyword(value)
+            for key, value in schema.items()
+        )
+    if isinstance(schema, list):
+        return any(_contains_fine_tune_unsupported_keyword(item) for item in schema)
+    return False
+
+
+def _fine_tuned_model_rejects_strict_schema(model: Any, schema: Any) -> bool:
+    """Return whether strict mode must be withheld for a fine-tuned model.
+
+    Fine-tuned (``ft:``-prefixed) models reject constraint keywords that
+    base models accept under strict mode, so a schema carrying any of them
+    goes to the wire non-strict for those models only. The walk is
+    context-blind like the branch walk: a property literally named after a
+    constraint keyword false-positives, and the only cost is the safe
+    non-strict fallback.
+    """
+    if not (isinstance(model, str) and model.startswith(_FINE_TUNED_MODEL_PREFIX)):
+        return False
+    return _contains_fine_tune_unsupported_keyword(schema)
+
+
+def _strictify_response_schema(schema: dict[str, Any], *, model: str | None = None) -> tuple[dict[str, Any], bool]:
+    """Return a strict-compatible copy or the original schema with strict mode disabled."""
+    try:
+        # Strict mode rejects schemas missing ``required`` or nested
+        # ``additionalProperties: false``; the SDK's recursive
+        # strictifier fills both exactly the way it does for model classes.
+        working = _materialize_json_structure(schema)
+        working = _ensure_strict_json_schema(working, path=(), root=working)
+    except Exception:
+        # Shapes the strictifier rejects go to the wire non-strict,
+        # exactly as the caller wrote them: the API enforces schema
+        # completeness only when strict is set.
+        logger.debug("response_format schema not strictifiable; sending non-strict", exc_info=True)
+    else:
+        # The strictifier transforms without certifying: a non-object
+        # or ``anyOf`` root and an explicitly non-false
+        # ``additionalProperties`` all survive it, and strict mode
+        # rejects each — such schemas also go to the wire non-strict.
+        if _strict_mode_incompatible(working):
+            logger.debug("response_format schema incompatible with strict mode; sending non-strict")
+        elif _fine_tuned_model_rejects_strict_schema(model, working):
+            logger.debug("response_format constraint keywords unsupported for fine-tuned models; sending non-strict")
+        else:
+            return working, True
+    return schema, False

chrys/service/llm/anthropic_messages/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Anthropic Messages API client."""
+
+from __future__ import annotations
+
+from .client import AnthropicMessagesClient
+
+__all__ = ["AnthropicMessagesClient"]